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 19 atomic, stack-agnostic skills and a TDD implementation engine — with a living roadmap above the per-feature flow.

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 (specify / clarify / design) are also depth-tunable — an easy / medium / hard dial decides how much the skill decides for you vs. interrogates you with trade-offs.

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: the script installs into the current directory (.agents/skills/ + .codex/agents/). Add --global after codex to install under ~ instead, or --prefix DIR to install under an arbitrary directory (useful for trying it out in a sandbox):

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

Then restart codex (skills are discovered at session start) and type $sdd-specify.

Alternative — the plugin marketplace. Note that add only registers the marketplace, it installs nothing by itself:

codex plugin marketplace add genkovich/sdd

then inside codex run /plugins, switch to the sdd marketplace tab and pick Install plugin. One naming nuance: the marketplace install registers the original skill names ($specify), while the installer script prefixes them — $sdd-specify — because bare names like review / design / api collide with generic skills. Pick one of the two paths, not both — they register different names for the same skills, so running both shows every skill twice. To undo the script install: re-run install.sh codex --uninstall from the same directory (or with the same --global / --prefix). To undo the marketplace install: /plugins → the sdd tab → uninstall (or remove the [plugins."sdd@…"] entry from ~/.codex/config.toml). The script warns when it detects a marketplace install already registered.

Windows note. The installer is a bash script — run it from Git Bash or WSL. The directories it writes (.agents/, .codex/, .cursor/) start with a dot, which Explorer hides by default — enable «Hidden items» (or dir /a) to see them.

Cursor (2.4+) — the same script; cd into your project first (installs into .cursor/skills/ + .cursor/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 -- cursor

Then restart Cursor (or run Developer: Reload Window) and invoke a stage by typing / in the chat and picking sdd-specify. (Cursor also reads .agents/skills/, so a Codex install is already visible to Cursor.) Once the plugin is listed on the Cursor marketplace, installing from the in-app marketplace panel works too — project- or user-scoped.

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

Start here

The flow is a straight line: each stage writes a file the next one reads. Run them in order (the diagram + table are just below).

/sdd:survey                         ← once per repo: map an existing codebase, OR bootstrap an empty one
/sdd:specify checkout-discounts     ← interviews you, writes the spec (you don't bring one)
/sdd:design … → /sdd:implement … → /sdd:review … → /sdd:ship

Two things to know up front: survey runs once per repo — on an existing codebase it maps the current architecture to docs/architecture-map.md (every later stage reads it); on an empty repo it runs a short foundation session and scaffolds the skeleton (detail below). And specify creates the spec from a short interview — you bring the idea, not the document.

From there you walk the backbone in order. Each step reads the previous step's file and refuses if it's missing, so you can't skip ahead by accident.

Every stage ends with a copy-ready handoff block (skills/_shared/handoff.md): What I did + Review before continuing (links to the files it wrote, so you can eyeball them at the gate) + Run next — /clear, then the next /sdd:… command in a fenced block you copy in one click. The /clear matters because each stage is gated and re-reads its inputs from disk, so it needs no carryover — clearing keeps the context small and stops one stage's chatter from drifting into the next. (Loop-backs are the exception — when review bounces back to implement, you stay in context to iterate; utilities make /clear optional.) It looks like this:

## ✅ specify — checkout-discounts

**What I did**
- wrote docs/features/checkout-discounts/spec.md — size M (from .size); proposed commit `spec: checkout-discounts`

**Review before continuing**
- docs/features/checkout-discounts/spec.md — goals, user stories, the §5 acceptance criteria

**Run next**
1. /clear — mandatory (fresh context; the next stage re-reads its inputs from disk)
2. then run:  /sdd:clarify checkout-discounts

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] -.-> S
    SV[survey<br/>once per repo] --> S
    subgraph backbone["BACKBONE — run in order"]
        S[specify] --> CL[clarify] --> D[design] --> SQ[sequences] --> DM[data-model] --> API[api] --> T[tasks] --> PT[plan-tests] --> IM[implement]
    end
    IM --> RV[review] --> SH[ship]
    subgraph util["UTILITIES — call anytime"]
        CS[classify-size]
        GL[glossary]
        ADR[decide-adr]
        FX[fix]
    end
    CL -.-> GL -.-> D
    SH --> done([shipped: PR + changelog])

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 implement. | the repo → docs/architecture-map.md (+ scaffold tasks.json on greenfield) |

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 | design | Matches the feature to your existing architecture (see below) + declares the target surfaces, writes the Arc42 SAD + C4 + ADRs | spec.md (+ CONTEXT.md if present) → sad.md, adr/* | | 4 | sequences | Draws the runtime flows as Mermaid sequence diagrams | sad.md → sad.md §6 | | 5 | 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 | | 6 | 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 | | 7 | tasks | Breaks the work into atomic ≤1-day tasks + a tasks.json dependency DAG | all of the above → tasks/*, tasks.json | | 8 | plan-tests | Maps every acceptance criterion to ≥1 test (inline in the spec for XS/S) | spec.md, data-model.md → test-plan.md (M+) or an inline ## Test plan in spec.md (XS/S) | | 9 | 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 | tasks.json + all artifacts → code + tests + promoted migrations, committed |

Close the loop (after the code is written)

| # | Skill | What it does | Reads → Produces | |---|---|---|---| | 10 | review | An independent, clean-context code review of the whole change against spec/AC + quality | the diff + spec.md → review record, PASS / CHANGES REQUESTED | | 11 | 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.

"We test and review, right?" Yes — in two places. implement runs a per-task gate (unit + integration + lint + vet) on every task as it goes, so each task is green before it's committed. Then review does the independent, whole-change code review a human reviewer would do on the PR, and ship runs the feature for real against its acceptance criteria. Tests-pass happens continuously inside implement; the cross-cutting review + real-world verification are the explicit review and `ship