SDD — Spec-Driven Development
A Claude Code plugin for structured, spec-driven development workflows. Every feature goes through specify → plan → tasks → implement with auto-complexity detection that fast-tracks small changes.
Installation
# Add the SDD marketplace
/plugin marketplace add alfredoperez/sdd
# Install the plugin
/plugin install sdd@sdd-marketplace
Quick Start
Auto mode (recommended)
/sdd:auto "add user authentication with OAuth2"
One command runs the full pipeline. For normal-complexity changes, it pauses after spec generation for your review. For small changes, it runs straight through.
Step-by-step with resume
/sdd:specify "add rate limiting"
/sdd:resume # advances to plan
/sdd:resume # advances to tasks
/sdd:resume # advances to implement
Manual (full control)
/sdd:specify "add user authentication with OAuth2"
/sdd:plan 001-add-oauth2-auth
/sdd:tasks 001-add-oauth2-auth
/sdd:implement 001-add-oauth2-auth
Small fix (fast path — auto-detected)
/sdd:specify "fix button hover color"
/sdd:implement 002-fix-button-hover
SDD auto-detects that small changes (≤3 files, <10 lines) don't need separate plan/tasks steps and generates everything in one shot.
Commands
| Command | Description |
|---|
/sdd:auto <description> | Run the full pipeline automatically |
/sdd:resume [slug] | Advance one pipeline step (clears pause if set) |
/sdd:pause [slug] | Pause a spec to prevent auto-advance |
/sdd:specify <description> | Create a spec from a feature description |
/sdd:plan [slug] | Generate an implementation plan from a spec |
/sdd:tasks [slug] | Generate a phased task list from a plan |
/sdd:implement [slug] | Execute tasks, run checkpoints, commit and PR |
/sdd:status | Show dashboard of all spec states |
How It Works
Spec Structure
Every feature gets a directory under specs/:
specs/001-my-feature/
├── spec.md # What to build and why
├── plan.md # How to build it (files, approach)
├── tasks.md # Step-by-step task list
└── .spec-context.json # Current workflow state
Building Blocks
| Block | Location | Purpose |
|---|
| Skills | skills/{name}/SKILL.md | Workflow steps — each skill is a standalone command |
| Templates | lib/templates/*.md | Markdown stubs filled in by skills (single source of truth) |
| State | specs/{slug}/.spec-context.json | Tracks workflow progress per feature |
Skills load templates from lib/templates/ and fill placeholders. See lib/templates/README.md for the canonical variable set.
Complexity Detection
| Signal | Mode |
|---|
| ≤3 existing files, <10 lines | minimal → fast path |
| Pure style or config tweak | minimal → fast path |
| 4+ files, new component/service | normal → full path |
| New public behavior or API | normal → full path |
State Tracking
Each spec tracks progress in .spec-context.json:
{
"workflow": "sdd",
"currentStep": "implement",
"currentTask": "T003",
"progress": "code-review",
"next": "done",
"updated": "2026-03-26"
}
- currentStep: Current phase (specify, plan, tasks, implement)
- currentTask: Current task ID during implement
- progress: Granular position within a step for precise recovery after context loss
- next: Next pipeline step for
/sdd:resume auto-advance (plan, tasks, implement, done, or null)
- updated: Last modification date
If a session ends mid-workflow, re-running the same command resumes from exactly where it left off.
Full field reference, lifecycle, and JSON Schema: docs/STATE.md.
Checkpoints
The implement step has 3 gates:
- CP1 — Code Review: Review changes, verify scenarios
- CP2 — Test Results: Verify tests pass (if run)
- CP3 — Commit & PR: Review commit message and PR body
Design Principles
- Right-sized process — A one-line CSS fix and a new auth system shouldn't go through the same ceremony. SDD auto-detects complexity and adjusts.
- Specs as artifacts — Specifications are committed alongside code in
specs/. They travel with the PR.
- Checkpoints, not bureaucracy — Every gate prevents a real category of mistake. No checkpoint exists "just because."
- State enables continuity —
.spec-context.json + substep tracking means no work is lost on context loss.
- Convention over configuration — Works with zero config. Everything customizable via
.sdd.json when needed.
Configuration
Optional .sdd.json in project root:
