agentsclimarketplace

Spec object review

Skill agent-ix/quoin/skills/spec-object-review

Audit spec domain objects, cross-references, and entity completeness across single or multi-repo ecosystems.From its SKILL.md

Install
npx -y skills add agent-ix/quoin --skill spec-object-review

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 20 stars20 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

6.5 KB, as published. Nobody here has run it

Spec Object Review

Audit a codebase's spec domain objects for completeness, cross-reference integrity, and alignment with the object-type-guide format.

When to Use

  • After initial spec creation to verify domain coverage.
  • When integrating a new service into an existing ecosystem.
  • When fixing spec-code misalignments or tracing integration bugs.
  • As a periodic health check on spec quality.

Process

1. Inventory

Scan all spec/ directories in scope (single repo or ecosystem-wide):

find spec/ -name "*.md" -path "*/functional/*"

For each FR, extract frontmatter fields: id, title, type, object.

2. Cross-Reference Audit

For every FR with a Traceability / Dependencies section:

  • Verify upstream refs exist: If FR-A says it depends on repo-B FR-003, confirm repo-B/spec/functional/FR-003-*.md exists.
  • Verify bidirectional tracing: If FR-A references FR-B as upstream, FR-B should reference FR-A as downstream (or vice versa).
  • Check endpoint paths match code: For any API endpoint documented in a spec, grep the source code to confirm the path is correct. Pay attention to router prefixes that may not appear in the FR but are applied at app mount time.

Common Pitfalls:

  • Router prefixes (e.g., /auth prefix) silently changing the actual path vs what the FR documents.
  • References using vague service names ("identity") instead of specific FR IDs ("identity FR-006").
  • depends_on in master spec frontmatter being empty when runtime dependencies exist.

3. Domain Object Completeness

Check whether domain objects defined inline in specs have proper dedicated FRs with object: frontmatter.

Scan for inline objects:

Pattern in specMissing Domain FR Type
### Data Models table with field/type columnsentity or value_object
API Request/Response JSON bodies in ## API Contractvalue_object
class X(SQLModel) or Pydantic model in code without FRentity
class X(str, Enum) or status fieldsvalue_object or state_machine
Multi-step behavior spanning servicesprocess
Env var / configuration table in spec.mdconfiguration
stateDiagram-v2 in spec.mdstate_machine

The Semantic Payload Trap: Inline JSON bodies inside of an endpoint's API Contract section are the #1 cause of cross-repo semantic drift. Even if the syntax matches (e.g. { "username": "string" }), the semantics drift (email vs account_name). Any structured payload passed across a bounded context MUST have a dedicated value_object FR to anchor its field semantics.

Reference: See object-type-guide.md for the full type taxonomy.

4. Frontmatter Validation

All FRs must use standard frontmatter:

---
id: FR-XXX
title: "Descriptive Title"
type: FR
object: entity          # Only if FR defines a domain object
relationships:          # Structured array of cross-references
  - target: "ix://org/repo/TargetFR"
    type: "depends_on"
    cardinality: "1:1"
---

Check for:

  • type: functional instead of type: FR (non-standard value).
  • Missing object: on FRs that clearly define domain objects.
  • domain: or status: fields that aren't part of the standard schema.
  • Missing relationships: array in the frontmatter when the body references upstream/downstream dependencies (such as an API, an event, a data entity, or a required permission).
  • Dependencies defined as generic Markdown text lists or raw Mermaid diagrams instead of structured YAML relational objects.
  • Relationships using generic type: "depends_on" when a more specific semantic linkage applies (e.g. calls, publishes, consumes, triggers, reads, writes, requires).

5. Rebuild Test

Ask yourself these questions. If the answer is "no" to any, there's a gap:

  1. Can I rebuild this system from spec alone? Every entity, its fields, invariants, and relationships should be in a dedicated FR — not just inline markdown tables.
  2. Can I find how to perform operation X? End-to-end flows (login, deploy, sync) should have object: process FRs that show the full sequence across services.
  3. Can I find how to integrate? Each service should document what it consumes and what it exposes, with FR-level traceability.
  4. Can I troubleshoot? Error handling sections should exist in every API endpoint and process FR.

6. Application-Level Check

For multi-service domains (e.g., Auth = auth-service + identity + auth-py + auth-fastapi + ts-auth-sdk):

  • Is there a catalog fixture defining the Application entity?
  • Does an application-level repo exist to own:
    • The bounded context / domain FR.
    • Cross-service process FRs.
    • The catalog fixture itself.
  • Do individual service repos avoid duplicating domain-level concerns?

Output

Produce a review report with:

PriorityFindingRepoImpact
P0Spec-code mismatchrepoIncorrect documentation
P1Missing cross-referencerepoTraceability gap
P2Missing object: frontmatterrepoParser incompatibility
P3Missing domain-typed FRrepoIncomplete domain model

Tips from Real Reviews

  • Router prefix trap: FastAPI router prefixes (e.g., router = APIRouter(prefix="/auth")) silently change paths. Always verify spec paths against the mounted path, not just the route decorator.
  • Vague traceability: | identity | Fetches user | is weaker than | identity FR-006 | Fetches user via internal lookup |. Always use FR-level IDs.
  • Empty depends_on: Client libraries almost always depend on the service they consume. An empty depends_on: [] in a client SDK spec is a red flag.
  • Section number gaps: Master specs jumping from §8 to §19 suggest template sections were deleted. Check if §8 (Domain Model) and §9 (Events and Signals) should be populated.
  • Shared entities: If two FRs reference the same model (e.g., AuthToken used by both API Keys FR-004 and OAuth Clients FR-008), the model needs its own entity FR to avoid ambiguity.
  • Semantic mismatch trap: Even when endpoint signatures align, field semantics can drift across bounded contexts (e.g., UI sends email mapped to SDK's username field, but Backend strictly expects an account name). Always cross-check the meaning and format of data passed across boundaries, especially in multi-repo systems like Auth.

Keep looking

Skills are one crate of 611,919. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.