Spec Driven Development

Spec Driven Development (SDD)

Concept of the skill

Use when starting a non-trivial feature, refactor, or agent implementation that needs a written spec, plan, task breakdown, and verification path before code changes.

Coverage

• When to require SDD: non-trivial work, core-module refactors, ambiguous agent loops, cross-boundary changes, or any task where hidden requirements could be expensive after code exists.
• Artifact chain: spec.md for what and why, plan.md for how, tasks.md for ordered work, implementation commits for execution, and a final verification report for spec compliance.
• Phase discipline: specification before plan, plan before tasks, tasks before implementation, and verification before completion.
• Traceability: each task and verification check maps back to a requirement, constraint, or success criterion.
• Review gates: human approval when available, or an explicit documented rationale when autonomous work must proceed.
• Scope control: if implementation discovers the spec or plan is wrong, update the upstream artifact before continuing.
• Post-implementation learning: measure whether the change solved the problem when the task has a product, operational, or user-facing success metric.

Philosophy of the skill

AI agents default to implementation-first thinking: receive a prompt, start coding. That produces features that compile, pass narrow tests, and still miss the actual requirement. SDD makes the specification the source of truth and turns the plan, task list, implementation, and verification report into derived artifacts.

GitHub Spec Kit frames the core process as Spec → Plan → Tasks → Implement. This skill keeps that source shape and adds a final Verify gate because a skill application is not complete until the implementation is checked against the spec that justified it.

The most important separation is what versus how. The spec names user value, constraints, non-goals, and success criteria. The plan names architecture, contracts, data flow, testing, and risk. Collapsing those two artifacts creates design debt before the first file is edited.

Workflow

Use this workflow in order. If a phase reveals that an earlier artifact is wrong, update the earlier artifact first and restart from there.

1. Decide Whether SDD Is Required

Use the lightweight path only for small, local, reversible edits. Use SDD when any of these are true:

• More than one module, service, schema, public API, or user flow may change.
• Requirements are ambiguous or conflict with existing behavior.
• Security, privacy, accessibility, data integrity, or migration risk is present.
• An agent loop has stalled because it keeps discovering new scope while coding.

2. Specify (spec.md)

The specification defines the desired outcome without prescribing implementation mechanics.

• Requirements: user-visible behavior, system behavior, and must-have outcomes.
• Constraints: architecture boundaries, security/privacy rules, accessibility, performance, compatibility, and data handling.
• Non-goals: what this change explicitly will not solve.
• Success criteria: observable facts that prove the work is done.
• Edge cases: zero states, failure states, concurrent access, volume limits, and rollback paths.

Anti-pattern: Describing implementation details (e.g., "Use a for loop") in the spec. The spec is for "What", not "How".

Exit gate: the spec is approved by the human owner, or the agent records why it is safe to proceed without explicit approval.

3. Plan (plan.md)

The plan translates the spec into an implementation strategy.

• Architecture: affected modules, new components, storage/schema changes, migration path, and rollback strategy.
• Data flow: how data moves between inputs, processing, storage, outputs, and external systems.
• Contracts: API request/response shapes, events, schemas, status codes, and compatibility promises.
• Testing: evidence needed at unit, integration, contract, E2E, manual, or visual levels.
• Risks: hidden dependencies, breaking changes, sequencing hazards, and observability needs.

Exit gate: the plan explains how every success criterion will be implemented and verified.

4. Decompose (tasks.md)

Break the plan into ordered, testable tasks.

• One behavioral change per task.
• Each task names the spec requirement or plan section it satisfies.
• Each task includes a verification command, check, or review step.
• Dependencies are topologically ordered so prerequisite work appears first.
• Parallel tasks are marked only when they can be executed without touching the same files or contracts.

Exit gate: a reader can execute tasks in order without rediscovering architecture decisions.

5. Implement

Implement from tasks.md, not from memory.

• Complete tasks in dependency order.
• Keep each commit or patch scoped to the task it claims.
• If a task exposes a wrong requirement, update spec.md; if it exposes a wrong design, update plan.md; then regenerate or adjust tasks.
• Do not silently add scope just because the implementation made it convenient.
• Keep tests, docs, and operational checks attached to the task that requires them.

6. Verify

Verification is the only path to finality.

• Spec compliance: every must-have and success criterion has evidence.
• Plan compliance: implementation follows the chosen architecture or documents an approved change.
• Regression evidence: focused tests, lint/type checks, contract checks, or manual verification ran.
• User-facing quality: UI, copy, accessibility, and visual behavior match the spec and the project design system.
• Documentation: repo instructions, API docs, decisions, and runbooks are updated when the behavior or workflow changed.
• Residual risk: any skipped check has a named reason and owner.

7. Learn

When the spec has a product, operational, or user-facing metric, measure whether the change solved the intended problem.

• Define the success metric before implementation.
• Confirm the measurement mechanism exists.
• Collect enough evidence for the decision.
• Record whether to continue, adjust, or stop.

Skip the learning loop for pure infrastructure chores, small bug fixes with a regression test, and cosmetic edits with no measurable hypothesis.

Verification Checklist

SDD CHECK
=========
[ ] spec.md exists or the fast-track rationale is documented
[ ] spec.md separates requirements, constraints, non-goals, success criteria, and edge cases
[ ] plan.md maps each success criterion to architecture, contracts, data flow, and verification evidence
[ ] tasks.md is ordered, traceable, and verifiable
[ ] No code was written before the plan gate, or the exception is documented
[ ] Every implementation deviation updated the upstream spec or plan
[ ] Final verification confirms all spec success criteria
[ ] Eval, routing, or quality claims remain unverified unless the corresponding check actually ran

Do NOT Use When

Verification

After applying this skill, verify:

• Changes follow the patterns documented above
• No regressions in affected functionality
• The final report names which spec criteria were satisfied and which checks produced evidence