Spec-Driven Development is a methodology where every code change follows a structured pipeline: problem → specification → design → implementation → verification. Each phase produces an artifact that feeds the next, so no implementation decision is made without a documented reason behind it. The result is a codebase with full traceability from the original problem statement through to archived code.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt
Use this file to discover all available pages before exploring further.
Phase diagram
Phases explained
Read-only analysis. First searches archived specs and past decisions for relevant context (recall), then reads existing code, identifies patterns, and checks canonical specs. No files are created or modified — this phase is purely about understanding the system before any change is proposed.
Skill:
/sdd-propose (or embedded in /sdd-new)
Artifact: proposal.md
Execution: Inline (interactive)Defines the problem and proposed solution. Includes alternatives that were discarded and why, plus an impact estimate covering affected files, domains, and tests. This is the “why” document — it captures the reasoning before any spec or code is written.
Describes expected behavior — not implementation. Uses Given/When/Then format for behavior definitions. The spec is a delta against the canonical spec — only what changes is documented, not the full system.
The spec phase is where most bugs are prevented. A clear spec means fewer surprises during implementation.
Translates the behavior spec into a concrete implementation plan. Lists every file to create or modify, records architecture decisions, and assesses scope. Runs as a subagent so the analysis is self-contained and the main conversation context stays clean. If scope exceeds 20 files, the design recommends splitting the change.
Breaks the design into atomic tasks, each corresponding to one file and one commit. Tasks are ordered by dependencies: interfaces first, then implementations, then tests. Nothing gets implemented without appearing in this list.
Skill:
/sdd-apply
Artifact: Code + atomic commits
Execution: Orchestrator spawns one subagent per taskImplements code task by task. Each task runs in its own subagent to keep the orchestrator context clean. The subagent reads similar code, implements the change, runs quality checks, and commits atomically. The orchestrator marks the task as done and asks the user before launching the next agent. Unplanned work gets registered as
BUGxx or IMPxx before implementation — nothing is implemented without being tracked.Final validation: full test suite, linter, self-review checklist, convention audit, and smoke test (for UI projects). All checks must pass before proceeding. Runs as a subagent because it executes checks and produces a report without requiring interactive decisions.
Two speeds
The workflow supports two paths depending on how much confidence you have in the scope of the change:| Path | When to use | Commands |
|---|---|---|
| Standard | Complex changes, team review needed | /sdd-new then /sdd-continue repeatedly |
| Fast-forward | Clear scope, straightforward changes | /sdd-ff then /sdd-apply |
/sdd-ff) generates all documentation in one pass — proposal, spec, design, and tasks — without pausing between phases. If ambiguity is found, it pauses to ask, then continues. Use it when the change is simple enough that you trust the AI’s judgment without reviewing each phase individually.
Principles
Every phase of the SDD workflow is grounded in five principles:- Specs before code — define behavior, then implement. A spec answers “what should this do?” before anyone asks “how should this work?”
- Atomic commits — one task, one file, one commit. This makes history readable and rollbacks surgical.
- No unilateral decisions — the AI stops and asks when something unexpected comes up, presenting options rather than silently making judgment calls.
- Living documentation — canonical specs are always current after archive. The
openspec/directory reflects what the system does right now. - Project memory — conventions and rules persist across sessions via steering files. The AI doesn’t forget what it learned from past corrections.