SDD-flow

A spec-driven, agentic software-development framework that runs on Claude.

About

SDD-flow turns a human's description of what to build into working, tested software — through a disciplined pipeline of specialized AI agents rather than one free-forming assistant. It is designed specifically for Claude, using Claude Code: a top-level Orchestrator Claude session coordinates six specialist subagents, each an expert at a single stage of the software lifecycle, and drives the project from intent to release-ready code.

The framework rests on four ideas:

• Specifications are the contract. Requirements and architecture are captured as immutable, versioned, schema-validated JSON documents. Every downstream artifact — the backlog, the tests, the code — traces back to them.
• Git is the memory. Everything needed to resume lives in the repository: document versions are git tags, approvals are git tags, and any session can reconstruct exactly where the project stands with no reliance on chat history.
• The human stays in control. You approve each specification and — at the default cadence — each unit of work before it is committed. Nothing lands until an automated validation gate passes.
• Independent judgement. No agent grades its own homework: the Planner plans, the Implementer builds, and a separate Verifier decides whether the work is accepted — against a test plan written independently of the implementation.

The agents

A project is driven by an Orchestrator — the top-level Claude session that owns all git operations, assembles each subagent's context, and never writes specialist artifacts itself. It spawns six stateless specialists, each owning exactly one kind of document:

Agent	Does	Produces
Analyst	Turns human input into clear, testable requirements; triages new requests	requirements.json
Designer	Turns requirements into a technical architecture and an environment setup script	architecture.json + setup-env.sh
Planner	Breaks specs into an executable backlog of initiatives → epics → tasks	backlog.json
Test Planner	Derives an independent test plan straight from the requirements (never from the code)	tests.json
Implementer	Builds one task as production code plus executable tests, keeping the build green	source + tests
Verifier	Independently reviews and QA-tests one task, then accepts or rejects it	verification report

Because the Test Planner works only from the requirements, the tests are an objective yardstick — so the Verifier's accept/reject decision can't be gamed by an implementation that merely satisfies its own tests.

The workflow

human intent
     │
  ① Requirements   → Analyst        → requirements.json   (approve → tag)
     │
  ② Architecture   → Designer       → architecture.json   (approve → tag)
     │
  ③ Planning       → Planner ‖ Test Planner  → backlog.json + tests.json
     │
  ④ Development loop   (per epic, per task)
        Implementer → code + tests
        Verifier    → accept / reject
             ├─ reject → back to Implementer (up to 3 rounds, then escalate)
             └─ accept → commit the task, then merge the epic
     │
  release-ready software

Each specification passes an automated commit gate (schema validity + cross-document integrity) and a human approval gate before it is committed and tagged. In the development loop, work happens on a branch per epic; a task is committed only after the Verifier accepts it and the gate passes, and the epic is merged when all its tasks are done.

Two more flows keep a long-lived project healthy:

• Intake & triage — after the initial build, new human input (a change request, a bug, a tech-debt item) enters via /sdd-intake; the Analyst classifies it and it is routed back into the pipeline.
• Consolidation — a periodic design-coherence pass (/sdd-consolidate) that guards against spec drift as change requests accumulate.

Along the way the framework records discoveries (knowledge surfaced during a task that matters for future work) and a token-usage ledger (spend per agent and per task/epic/initiative). A self-contained HTML dashboard renders the specs, backlog, tests, full traceability, discoveries, and token usage — refreshed on demand.

Getting started

Prerequisites: Claude Code, Python 3, and git.

1. Bootstrap a project. From a Claude session in this framework repo, run:

   /sdd-init my-project
   

   This scaffolds a new, self-contained SDD-flow-managed repository (by default a sibling directory ../my-project), captures your intent and any files you provide, copies in the playbooks, schemas, tooling, commands, and agents, and commits a baseline.

2. Move into the project. Close the framework session, cd into the new project, and start a Claude session there. It recognizes itself as SDD-flow-managed and presents the current phase and the recommended next step.

3. Drive the pipeline. Use /sdd-next to advance a step at a time (or --auto to run to the next gate), approve the specs and tasks as they come up, and inspect progress with /sdd-status and the rendered dashboard.

You choose the cadence at bootstrap: task (approve before each task's commit — the default), epic (approve before each epic merges), or autonomous (no gates; the framework self-approves).

Commands

Command	Purpose
/sdd-init	(framework only) Bootstrap a new managed project and hand off
/sdd-next [--auto]	Advance the pipeline one bounded step, or run to the next gate
/sdd-status	Show the current phase, state, and recommended next step
/sdd-check	Validate every document's schema + cross-document integrity
/sdd-render	Regenerate the human-readable HTML dashboard
/sdd-intake	Capture new human input (change request, bug, tech-debt) post-init
/sdd-consolidate	Run a periodic design-coherence pass over the specs

Approvals are conversational — there is no command; you simply review and say yes.

Repository layout

Path	What it is
schemas/	The 10 JSON Schemas — the canonical contract for every document
orchestrator/	Orchestrator playbooks: the development flow, git conventions, context assembly, token accounting
agents/	The six specialist agent definitions
commands/	Lifecycle slash-command templates installed into each project
templates/	The config.json and CLAUDE.md stubs stamped into a project at init
scripts/	The sdd_*.py tooling (validate, index, render, token accounting)

Status

SDD-flow is in active development. The full agent set, schemas, orchestrator playbooks, tooling, and bootstrap flow are in place; see CLAUDE.md for how the repository is organized and how to work on the framework itself.