| name | spec-driven-development |
| description | Create machine-readable technical specs before implementing non-trivial features, APIs, or refactors. Use before BUILD phase when PLAN is STANDARD/COMPLEX and precise typed contracts, behavioral invariants, and example pairs are needed for validation. Triggers on "write a spec", "spec-first", "define the contract". |
When to use
- Create machine-readable technical specs before implementing non-trivial features, APIs, or refactors
On-demand loading: This skill is loaded only when explicitly invoked. It is not active by default.
Spec-Driven Development Skill
Use this skill before implementing any non-trivial feature, refactor, or API to create a machine-readable technical spec that the agent and reviewer can validate against.
Pipeline: requirements-gathering → prd → spec-driven-development → writing-plans
Triggers: "write a spec for", "spec-first", "design before coding", "define the contract", "spec this out", or when PLAN classification is STANDARD/COMPLEX and brainstorming + PRD alone are insufficient technical precision.
What this skill produces
A technical spec document — not a PRD, not a plan, not pseudocode. A spec defines:
- Exact function/class/API signatures with typed parameters and return values
- Behavioral contracts: what it guarantees (invariants) and what it assumes (preconditions)
- Edge cases and failure modes with expected behavior for each
- Data shapes: input/output schemas with example payloads
- Test cases as examples: 3–5 concrete in/out pairs that define the expected behavior
Step 1 — Define the subject
State precisely what you are specifying:
- A single function? An HTTP endpoint? A React component? A service class? A database schema?
- What layer does it live in (UI / API / service / data / infra)?
- What are the inputs and outputs at the boundary?
If you don't know the boundary yet — STOP and use brainstorming or requirements-gathering first.
Step 2 — Write the signatures
Produce typed signatures for every public-facing interface (function, HTTP endpoint, React component).
→ Format examples in references/spec-format.md § Step 2.
Step 3 — Define behavioral contracts
Write INVARIANTS (always true), PRECONDITIONS (caller guarantees), and POSTCONDITIONS (this function guarantees).
→ Format in references/spec-format.md § Step 3.
Step 4 — Enumerate edge cases
List every non-happy-path scenario with expected behavior in a table: input condition → expected behavior.
→ Example table in references/spec-format.md § Step 4.
Step 5 — Write example pairs (executable contracts)
Write 3–5 concrete in/out examples: happy path, validation failure, idempotency, not-found. These become your test cases.
→ Format in references/spec-format.md § Step 5.
Step 6 — State what is explicitly out of scope
List what this spec does NOT cover (authorization, rate limiting, logging, UI presentation, etc.).
→ Format in references/spec-format.md § Step 6.
Step 7 — Produce the spec document
Combine Steps 2–6 into one structured spec block: Subject, Layer, Owner, Signatures, Contracts, Edge Cases, Examples, Out of Scope, Acceptance Criteria.
→ Full template in references/spec-format.md § Step 7.
When to hand off to BUILD
Hand off to ship-feature or build-full only when:
- All signatures are typed and complete
- At least 3 example pairs are written
- Edge cases table covers empty input, invalid input, and not-found scenarios
- Out of scope section lists at least 2 items
The spec becomes the binding contract for implementation and review.
