| name | spec-driven |
| description | Spec before plan for non-trivial work. Invoke when the user asks for a feature, refactor, workflow change, API change, or any multi-step task where the why, scope, or acceptance criteria could drift. Do not let implementation become the de facto spec. |
Spec Driven
A plan tells you how to build. A spec tells you what you are building, why it exists, and what is out of scope. If the change is non-trivial and no spec exists, the agent is guessing.
Use this skill to make the spec the source of truth before planning and implementation.
When a spec is required
Write or update a spec when any of these are true:
- user-visible behavior will change
- API shape, CLI behavior, or data contracts will change
- multiple files or phases are involved
- there are explicit non-goals or scope boundaries to preserve
- reasonable engineers could disagree on what "done" means
- you'd be annoyed if the implementation set policy by accident
Skip the full spec only for mechanical, single-commit changes with obvious scope. If you skip it, say so explicitly.
Step 1 - Choose the spec type
Choose the smallest document that can hold the decision:
docs/product-specs/<feature>.md for user-facing scope, goals, non-goals, and success criteriadocs/design-docs/<topic>.md for technical shape, invariants, and rejected alternatives- both, if the feature has product intent and a non-trivial technical decision
Rule of thumb:
- "What problem are we solving and for whom?" -> product spec
- "Why this architecture and not another?" -> design doc
If the repo has no docs/ structure yet, create the minimum path you need rather than keeping the spec in chat.
Step 2 - Write the minimum viable spec
The spec must answer the questions implementation will otherwise answer by accident.
Product spec must cover
- problem
- goals
- non-goals
- solution sketch
- success metrics or acceptance criteria
- open questions
Design spec must cover
- context / forcing constraint
- decision
- rejected alternatives with reasons
- consequences
- invariants future code must respect
- revisit signal
Keep it lean. A good spec is decisive, not long.
Step 3 - Make it executable
A spec is usable only if an agent can turn it into a plan without guessing.
Check for:
- concrete scope boundaries, not "improve UX" or "support auth"
- observable acceptance criteria
- explicit non-goals
- named users, callers, or systems affected
- unresolved questions separated from settled decisions
Bad spec signals:
- implementation detail fills the page but user-visible behavior is unclear
- "TBD", "etc.", "and more"
- hidden policy decisions inside code examples
- no statement of what must not change
If a reviewer could interpret the spec in two materially different ways, it is not ready.
Step 4 - Gate planning on the spec
Do not write the execution plan first.
Sequence:
- explore the code and current docs
- write or update the spec
- get user alignment on the spec if the change is non-trivial
- write the execution plan that references the spec
- implement
The plan should cite the spec path directly. The plan is allowed to decompose work; it is not allowed to redefine product scope or architecture silently.
Step 5 - Keep spec and code aligned
If implementation reveals that the chosen shape is wrong:
- stop
- update the spec or design doc
- note the change in the plan
- then continue
Do not let code diverge and promise to "clean up docs later". That turns the spec into fiction.
What this bundle is not
- Not a replacement for
planning-first - that bundle governs exploration, questions, options, and approval flow
- Not a replacement for
docs-as-code - that bundle defines the broader documentation system and doc taxonomy
- Not a replacement for
quality-gates - a spec can be correct and the implementation can still be broken
This bundle exists to prevent one specific failure mode: implementation becoming the first precise statement of scope.
