Skip to content

Spec (Spec-Driven Development)

Overview

Create a stable “source of truth” for agents and humans: write specs with testable acceptance criteria and keep them aligned with implementation.

This skill treats specs as operational tooling: they prevent scope drift, enforce invariants, and make AI iteration converge.

Core Idea

  • Specs define what must be true (contracts, scenarios, invariants, NFRs), not “how we coded it”.
  • Plans/tasks define how we’ll get there (phases, work breakdown, acceptance per task).
  • Code + tests are the proof.

Where Specs Live (Opinionated)

Use one (or both) of these:

  • System specs: specs/*.md for cross-service rules and shared constraints (auth, observability, eventing, product scope).
  • Decision records: specs/decisions/*.md for significant choices (trade-offs, migrations, taxonomy, compatibility).
  • Service spec bundle: apps/<service>/spec/ for service-local truth:
  • spec.md: requirements and acceptance scenarios
  • contracts/: OpenAPI/proto/WS message contracts
  • data-model.md: domain entities + storage boundaries
  • plan.md: phases and wiring/structure
  • tasks.md: checklist-style backlog with acceptance criteria
  • quickstart.md: how to run/verify the service in dev

Chooser (What Spec Artifact To Write)

  • Cross-service rule or shared constraint (auth, observability, eventing, product scope): write/update a system spec (specs/NNN-<topic>.md).
  • Significant trade-off or migration decision: write a decision record (specs/decisions/NNN-<topic>.md).
  • New or changed service behavior: write/update the service spec bundle (apps/<service>/spec/).
  • API/contract change (new endpoint, changed schema, new event): update contracts (contracts/: OpenAPI/proto/WS docs) in the spec bundle.
  • Task breakdown for implementation: update tasks.md in the spec bundle (or specs/tasks.md for repo-level backlog).
  • Minor behavior tweak within existing contracts: update acceptance scenarios in the existing spec; no new artifacts needed.

Inputs / Outputs

Inputs: Plan output — objective function, scope (optional); archobs JSON — cluster boundaries, risk scores; forecast lifecycle data (if pinning external dependency contract). Outputs: Spec artifacts (service spec, API contracts, ADRs, task lists). Consumed by testing (acceptance scenarios as test sources), plan (task breakdown), finish (intent artifact check).

Clarifying Questions

  • Is this change scoped to one service or does it cross service boundaries?
  • Does it change externally visible behavior (API shapes, error codes, event schemas, auth rules)?
  • Are there existing specs/contracts that should be updated vs creating new ones?
  • Who are the consumers of this contract (other services, clients, external partners)?
  • Is backward compatibility required, or can we make breaking changes?

Workflow

  1. Load archobs data (before spec writing begins): 
    archobs show clusters --format json
archobs show risks --format json

Use in spec writing: - Ensure spec contracts honor existing cluster boundaries. If the spec introduces a new boundary that cuts across a cluster with cohesion > 0.60, flag the conflict — the spec is fighting natural structure. - Files with risk > 0.5 in the spec's scope warrant stricter acceptance criteria and testing requirements. - Clusters with leakage > 0.20 that the spec touches may need explicit boundary contracts (interface types, Facade).

If archobs artifacts are missing: run archobs report or note as a gap. Do not block spec writing on archobs — the spec can be amended when data becomes available.

0b. Versioning guidance from forecast (conditional — run when the spec pins an external dependency contract such as an API version, SDK, or protocol):

intel forecast    # lifecycle phase for the dependency

Decision mapping: See Lifecycle Decision Mapping — Spec: Versioning Strategy for lifecycle phase → versioning strategy table.

  1. Decide the scope:
  2. One service? write/update the service spec bundle.
  3. Cross-service or product-wide? write/update a system spec.
  4. Write the objective function up front:
  5. goal, constraints, anti-goals
  6. boundary (in/out) and time horizon
  7. Externalize the system sketch:
  8. actors + incentives
  9. key flows (work/data/risk)
  10. top constraints/bottlenecks
  11. Write acceptance-first:
  12. user story + “independent test”
  13. acceptance scenarios (Given/When/Then)
  14. edge cases and invariants (“constitution requirements”)
  15. Lock down contracts:
  16. HTTP/gRPC schemas, message types, error codes, idempotency keys
  17. versioning rules and backward compatibility expectations
  18. Add non-functional requirements (NFRs) that matter:
  19. latency budgets, concurrency, durability, audit, privacy
  20. observability and resilience requirements (trace/log/metrics, timeouts/retries/idempotency)
  21. Add a compact decision table:
  22. options considered (include baseline/no-change)
  23. what is optimized vs knowingly worsened
  24. kill criteria / reversal trigger
  25. Stress-test the decision (if 2+ viable approaches exist; skip for single viable approach):
  26. Assumptions: What are facts vs assumptions? Which assumption is least certain — how will we validate it? Cross-reference with archobs data from step 0 and versioning guidance from step 0b (if applicable). (attach to decision table)
  27. Second-Order Effects: What happens next week / next quarter / next year? What new load, toil, coupling, or failure mode does this create? If this fails in 6-12 months, what likely caused failure? Cross-reference with archobs data from step 0 and versioning guidance from step 0b (if applicable). (attach to decision table)
  28. Opportunity Cost: What are we saying "no" to? Are we favoring this due to sunk cost, familiarity, or novelty? (attach to decision table)
  29. If probe output already exists from an earlier Define-stage skill in this flow (including workflow orchestration), refine it instead of re-running.
  30. Add a measurement ladder:
  31. decision being measured
  32. leading indicators (early signal)
  33. lagging outcomes (business/ops)
  34. instrumentation sources + review ritual (owner/cadence/action trigger)
  35. Break it into tasks with acceptance:
  36. keep tasks small and orderable
  37. each task has an observable acceptance check
  38. Implement and keep docs honest:
  39. if implementation forces a change in behavior, update specs first
  40. keep quickstarts and contracts current

Minimum viable execution

When context or time is constrained, these are the load-bearing steps:

  1. Decide scope (step 1) — one service vs cross-service.
  2. Write acceptance scenarios (step 4) — Given/When/Then with edge cases and invariants.
  3. Lock down contracts (step 5) — HTTP/gRPC schemas, error codes, versioning rules.
  4. Break into tasks with acceptance (step 10) — each task must be verifiable.

Steps that can be cut under pressure: system sketch (step 3), NFRs (step 6), decision table (step 7), measurement ladder (step 9).

Guardrails

  • “No spec, no change”: don’t implement major behavior without updating the spec surface.
  • Don’t hide requirements in code; put them in spec.md where agents can find them.
  • Keep contracts stable; prefer additive changes and version explicitly when you can’t.
  • Write down non-goals to stop scope creep.
  • For non-trivial decisions, record opportunity cost explicitly to avoid accidental scope drift.
  • No metric without a named decision and review ritual.
  • If a design cannot be measured cheaply enough to guide weekly decisions, treat that as a constraint and simplify.

Common failure modes

  • Writes the spec after implementation — the spec becomes documentation of what was built, not a source of truth that guides what to build.
  • Over-specifies implementation details instead of boundary contracts — specs should define what must be true (response shapes, error codes, invariants), not how to code it.
  • Doesn't version contracts when making breaking changes — consumers break silently because the contract didn't signal the incompatibility.
  • Spec doesn't match actual code — spec drift accumulates when implementation changes aren't reflected back to specs.

References

Output Template

When using this skill, return:

  • Scope + objective: boundary, constraints, anti-goals.
  • Artifacts created/updated: exact spec files (and contracts/ADRs when relevant).
  • Decision summary: options considered, selected option, trade-offs, kill criteria, and assumptions (facts vs assumptions, opportunity costs).
  • Measurement ladder: leading + lagging indicators, owner/cadence/action trigger.
  • Verification plan: concrete checks/commands that prove acceptance scenarios and failure expectations.
  • Next implementation tasks: ordered checklist with observable acceptance per task.