Spec-Driven Workflow

Spec-Driven Workflow

Development where the specification is the source of truth and the code is its implementation, rather than a document that was true at kickoff and fiction by week three. The mechanism is unglamorous: every normative statement gets a stable ID, every ID appears in a test, and the merge gate fails when the two drift apart. Without that mechanical link a spec is a memo, and memos do not survive contact with a sprint.

When to use this skill

• Starting a greenfield feature where the interface is contested and the cost of building the wrong thing is high
• Reviving a stale spec that no longer matches shipped behaviour and needs reconciling before the next change
• Gating merges on coverage so a PR that implements two of five committed requirements cannot silently land
• Auditing what actually shipped ahead of a stakeholder review or a compliance obligation
• Handing a feature to another team who need the intent, not just the code
• Generating an implementation from a spec — which only works if the spec is precise enough that two engineers would build the same thing

Inputs the skill expects

• A specification document in markdown, with normative statements using must/shall/should/may
• Acceptance criteria per requirement, ideally in given/when/then form
• The source tree and test suite where implementations will be annotated
• The coverage bar the merge gate enforces (mandatory-requirement coverage, typically 1.0)
• The previous requirements snapshot, when checking for drift against a baseline
• Which requirements are explicitly out of scope for the current milestone

Clarify First

Before writing or auditing a spec, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• What must be true for this to be "done" — becomes the acceptance criteria; without it the spec is a wish list and nothing is verifiable
• Which constraints are hard vs preferences — decides must/shall versus should, which in turn decides what the merge gate blocks on
• Who consumes the spec — an implementing engineer, a generating model, and an auditor need different precision; the generating case needs the most
• Scope boundary for this milestone — requirements outside it must be marked, or coverage reports will show permanent false gaps

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1 — Write the spec, then prove it is precise