sdd

SDD — Spec-Driven Development for Claude Code

A self-contained Claude Code plugin that carries a feature from a one-line idea to reviewed, verified, shipped code through 23 atomic, stack-agnostic skills and a TDD implementation engine — with a living decomposition roadmap above the per-feature flow and a design pipeline (design-system · ux-flows · screens) for UI features.

Every skill is Socratic (it walks decisions with you, it doesn't dump a wall of output), gated (a stage hard-refuses when its prerequisite artifact is missing), and stack-agnostic (no language, tracker, or test tool is hard-coded — the skills detect what your repo uses). The Q&A skills are depth-tunable (easy / medium / hard) and run on any Claude plan or model tier — no skill requires a specific one; judgment agents default to opus and degrade gracefully when it's unavailable (see Levers).

The flow

There are three kinds of skill. Most of your time is the backbone — a straight line you walk in order. A few are utilities you call whenever you need them. Two close the loop after the code is written.

flowchart LR
    IV[interview<br/>optional] -->|docs/idea-brief.md| SV[survey<br/>once per repo]
    SV -->|docs/architecture-map.md| RM[roadmap<br/>decomposition]
    RM -->|greenfield: step 1| SC[scaffold] --> S
    SV -.->|greenfield, no brief| SC
    RM -.->|per step| S
    IV -.-> S
    SV -.->|brownfield| S
    DS[design-system<br/>once per repo, UI] -.-> UX
    subgraph backbone["BACKBONE — run in order"]
        S[specify] --> CL[clarify] --> UX[ux-flows<br/>UI features] --> D[design] --> SQ[sequences] --> DM[data-model] --> API[api] --> SCR[screens<br/>UI features] --> T[tasks] --> PT[plan-tests] --> IM[implement]
        CL -.->|no UI| D
        API -.->|no UI| T
    end
    IM --> RV[review] --> SH[ship]
    subgraph util["UTILITIES — call anytime"]
        CFG[config]
        CS[classify-size]
        GL[glossary]
        ADR[decide-adr]
        FX[fix]
    end
    CL -.-> GL -.-> D
    SH --> done([shipped: PR + changelog])

Install

Claude Code — native plugin:

/plugin marketplace add genkovich/sdd
/plugin install sdd@sdd

After updating to a new release: re-run /plugin install sdd@sdd, then /reload-plugins.

Codex CLI — cd into your project first (installs into .agents/skills/ + .codex/agents/ of the current directory; --global for ~, --prefix DIR for an arbitrary directory):

cd your-project
curl -fsSL https://raw.githubusercontent.com/genkovich/sdd/main/install.sh | bash -s -- codex

Restart codex and type $sdd-specify. Alternative: codex plugin marketplace add genkovich/sdd, then inside codex /plugins → the sdd tab → Install plugin — registers the unprefixed names ($specify) instead of the script's $sdd-specify. Pick one path, not both — running both shows every skill twice. Undo: install.sh codex --uninstall (script) or /plugins → uninstall (marketplace). Windows: run the installer from Git Bash or WSL — the dot-directories it writes are hidden by default in Explorer.

Cursor (2.4+) — the same script (.cursor/skills/ + .cursor/agents/); restart Cursor (or Developer: Reload Window), then type / and pick sdd-specify:

cd your-project
curl -fsSL https://raw.githubusercontent.com/genkovich/sdd/main/install.sh | bash -s -- cursor

How every Claude-specific mechanism — AskUserQuestion, subagents, /clear, the implement engine modes — maps to Codex / Cursor is one table: skills/_shared/tool-adapters.md.

First run

The flow is a straight line: each stage writes a file the next one reads, and refuses to run if its input is missing — so you can't skip ahead by accident. The argument every stage takes is a kebab-case feature slug you make up once (here checkout-discounts); it becomes docs/features/checkout-discounts/, so use the same slug at every stage.

/sdd:interview                          # optional: pressure-test a raw idea → docs/idea-brief.md
/sdd:survey                             # once per repo: map the current architecture
/sdd:roadmap                            # optional: decompose into steps + waves
/sdd:specify       checkout-discounts   # interview → spec (reads the architecture map)
/sdd:clarify       checkout-discounts
/sdd:ux-flows      checkout-discounts   # UI features only — user flows + screen inventory
/sdd:design        checkout-discounts
/sdd:sequences     checkout-discounts
/sdd:data-model    checkout-discounts
/sdd:api           checkout-discounts
/sdd:screens       checkout-discounts   # UI features only — the per-state screen manifest
/sdd:tasks         checkout-discounts
/sdd:plan-tests    checkout-discounts
/sdd:implement     checkout-discounts
/sdd:review        checkout-discounts   # independent review of the whole change
/sdd:ship          checkout-discounts   # verify it runs, changelog, PR

Every stage ends with a copy-ready handoff block (skills/_shared/handoff.md) — What I did + Review before continuing + Run next: /clear, then the next /sdd:… command, ready to copy. /clear matters because each stage re-reads its inputs from disk, so clearing keeps context small instead of letting one stage's chatter drift into the next (loop-backs like review → implement are the exception; utilities make it optional):

## ✅ specify — checkout-discounts
**What I did** — wrote docs/features/checkout-discounts/spec.md, size M; commit `spec: checkout-discounts`
**Review** — spec.md: goals, user stories, the §5 acceptance criteria
**Run next** — /clear, then: /sdd:clarify checkout-discounts

Three notes: classify-size is optional up front — specify writes .size itself when it's absent; run it only to size before specifying, or to re-classify. Skip the depth question with /sdd:specify checkout-discounts --depth=easy (also clarify/design; see Levers). And ux-flows/screens auto-skip for backend-only work, no confirmation needed.

Step 0 — survey (once per repo, before the backbone)

#	Skill	What it does	Reads → Produces
0	survey	Existing repo → scans once, persists the current architecture. Empty repo → level-adaptive foundation session → fixes the foundation + emits a scaffold tasks.json for scaffold.	the repo (+ docs/idea-brief.md if present) → docs/architecture-map.md (+ scaffold tasks.json on greenfield)
0b	scaffold	Greenfield only: materializes the skeleton the foundation planned — sequentially inline, anchored on the skeleton smoke test (builds + boots + empty test suite + migration tool)	architecture-map.md + _scaffold/tasks.json → the committed skeleton
0c	design-system	Once per repo, before the first UI feature: fixes the committed design canon — the drawing tool (Figma / Pencil / code), platform posture, tokens, component inventory	the repo (+ design MCPs) → docs/design-system.md

Backbone — the straight line (run in order)

#	Skill	What it does	Reads → Produces
1	specify	Interviews you to capture the idea, writes the product spec + acceptance criteria (reads the architecture map for constraints)	your idea, architecture-map.md → spec.md
2	clarify	Sweeps the spec for ambiguities (a devil's-advocate pass), closes or defers each	spec.md → tightened spec.md
3	ux-flows	UI features only (auto-skipped otherwise): derives one user flow per UI-touching user story (happy + AC-driven error branches) + the SCR-NN screen inventory — always markdown+mermaid, whatever the design tool	spec.md, design-system.md → ux-flows.md
4	design	Matches the feature to your existing architecture + declares the target surfaces (reading ux-flows.md as evidence), writes the Arc42 SAD + C4 + ADRs	spec.md (+ ux-flows.md, CONTEXT.md if present) → sad.md, adr/*
5	sequences	Draws the runtime flows as Mermaid sequence diagrams (UI-driven flows agree with ux-flows.md)	sad.md → sad.md §6
6	data-model	Designs the schema and writes the actual forward+rollback migrations — staged under the feature folder, not the live tree (implement promotes them)	spec.md, sad.md, sequences → data-model.md, staged migrations/*.up/down.sql
7	api	Derives the OpenAPI contract from the data model (or the existing schema on the fast lane) + sequences + spec	data-model.md, sequences, spec.md → contracts/openapi.yaml
8	screens	UI features only (auto-skipped otherwise): the canonical screen manifest — every screen in every state (default / loading / empty / error / …), reuse-first components; drawn per the canon's tool	ux-flows.md, sad.md, contracts, design-system.md → screens.md
9	tasks	Breaks the work into atomic ≤1-day tasks + a tasks.json dependency DAG (each ui task cites screens.md SCR ids + states)	all of the above → tasks/*, tasks.json
10	plan-tests	Maps every acceptance criterion to ≥1 test (inline in the spec for XS/S; e2e-through-UI paths from ux-flows.md, component states from screens.md)	spec.md, data-model.md → test-plan.md (M+) or an inline ## Test plan in spec.md (XS/S)
11	implement	The TDD engine: writes a failing test, makes it pass, gates, commits — per task; promotes each staged migration into the live migrations/ as it builds; a ui task builds to the screens.md states, reusing the inventory	tasks.json + all artifacts → code + tests + promoted migrations, committed

Close the loop (after the code is written)

#	Skill	What it does	Reads → Produces
12	review	An independent, clean-context code review of the whole change against spec/AC + quality (incl. built-screen ↔ screens.md match)	the diff + spec.md → review record, PASS / CHANGES REQUESTED
13	ship	Verifies the feature actually runs (not just green tests), writes the changelog, opens the PR	the reviewed change → changelog + PR (never auto-merges)

review can bounce back to implement if it finds an unmet acceptance criterion. ship is the end: a reviewed, verified change with a changelog and an open PR — merging to main stays your call. Tests-pass happens continuously inside implement (a per-task gate); review is the cross-cutting whole-change check a human reviewer would do; ship runs the feature for real.

Utilities — call whenever you need them (not part of the line)

• interview (before roadmap / specify) — gets the idea out of your head and onto disk: an adaptive engineering interview with bounded fact-checking and risk-based critique. Writes the 8-section docs/idea-brief.md with decisions, evidence and readiness. Outside a repo or in Plan Mode it stays talk-only; headless it stops before writes/helpers. specify reuses its answers.
• config — the per-project settings file .claude/sdd.local.md: creates it with documented defaults, then walks six grouped questions and patches only the keys you confirm (your comments, key order and unknown keys survive untouched). The only skill that changes a setting — the six creating skills create and read, they never offer to tune.
• classify-size — size the feature XS/S/M/L/XL (writes .size); later skills read it. Run it at the start, or any time scope changes.
• glossary — capture a domain term in CONTEXT.md. Run it whenever a new term shows up; design and the spec read it.
• decide-adr — write a standalone ADR after the fact, when tasks (or a review) flags a decision that needs recording but wasn't captured during design.