Spec-Driven Development (SDD)

Spec-Driven Development (SDD)

What this is

Code consistency is the casualty of LLM agent velocity.

LLMs write code faster than any human can read it — and faster than the agent can stay coherent with itself. SDD keeps the spec small, dense, and durable. It's the part the agent re-reads every turn, so task ten is built against the same constraints as task one.

The mechanics:

• Every row has an address. §V.<n> / §T.<n> / §B.<n> are stable cites — code comments link to the invariant they uphold, tests reference the bug they guard, commits cite the task they close. SPEC.md survives /clear and team handoff.
• Telegraph encoding cuts tokens ~40% vs Claude prose for the same content (measured per-row mean 41%, median 39%, n=30 — see benchmarks/telegraph/). The savings come from terse grammar — dropped articles/filler, fragments, unpadded pipe tables — plus compact §-refs and a curated low-token symbol set (→ ≥ ≤ ! ? § |); Distinct from steno (the bundled human-facing shorthand).
• Every test failure feeds back into the spec. A §B row, usually a new §V invariant. The drift report stays trustworthy because every prior failure tightened the spec.
• Main Claude does all the writes. Code edits, SPEC.md mutations, status flips, commits. Read-only audits (e.g. /sdd:check) may fan out to sub-agents. No orchestrator. Same spec + same task → same plan.
• Re-onboarding is one command. Come back to the repo after a week, run /sdd:check. You get a read-only drift report: which §V invariants the code violates, which §T tasks remain. No digging through old transcripts.

The spec is the only artifact that earns its tokens. Everything else must save more tokens later, save the agent's context, or get cut.

SPEC.md is for the LLM, not you

SPEC.md is an LLM-facing artifact. You operate it through Claude — /sdd:spec writes, /sdd:build and /sdd:check read, /sdd:explain decodes a citation back to prose when you want to read along. The loop is human → /sdd:* → Claude → SPEC.md, not hand-editing in your editor.

That framing is load-bearing. Telegraphic fragments over full sentences, pipe tables over bulleted lists, dropped line citations — all optimized for the model that re-parses the spec every command, not the human skimming it. If you want to skim it as a human, /sdd:explain is the front door.

Install

/plugin marketplace add kborovik/spec-driven-dev

/plugin install sdd@spec-driven-dev

Then in any repo:

/sdd:spec   # creates SPEC.md if missing

The mental model

   ┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
   │/sdd:design │──►│ /sdd:spec  │──►│ /sdd:build │──►│ /sdd:check │
   │  propose   │   │  mutator   │   │ plan→exec  │   │ read-only  │
   └────────────┘   └─────▲──────┘   └─────┬──────┘   └─────┬──────┘
                          │                │                │
                          │                ▼ on failure     │ on drift
                          │          ┌────────────┐         │
                          │          │  backprop  │         │
                          │          │ §B (+ §V)  │         │
                          │          └─────┬──────┘         │
                          │                │                │
                          └────────────────┴────────────────┘
                                     amend SPEC.md

• One spec file. SPEC.md. No docs/ tree, no JSON sidecars.
• One writer. /sdd:spec. (/sdd:build may flip a . → x; nothing else writes.)
• Read-only commands write nothing. /sdd:check (drift report) and /sdd:explain (decompression).

SPEC.md format

Six fixed sections, fixed order. Each row is addressable as §<S>.<n>.

# SPEC

## §G GOAL

one line. what code must do.

## §C CONSTRAINTS

- non-negotiable boundary
- tech / language / library locked in

## §I INTERFACES

external surface — what the world sees.

- cmd: `foo bar` → stdout JSON
- api: POST /x → 200 {id}
- file: `config.yaml` schema …
- env: `FOO_KEY` required

## §V INVARIANTS

numbered. testable. each ! MUST hold.
V<n>: every req → auth check before handler
V<n>: token expiry ≤ current_time → reject
V<n>: DB write ! in transaction

## §T TASKS

id|status|task|cites
T<n>|.|scaffold repo|-
T<n>|.|impl §I.api POST /x|V<n>
T<n>|x|add §V.<n> middleware|V<n>,I.api

## §B BUGS

id|date|cause|fix
B<n>|2026-04-20|token `<` not `≤`|V<n>
B<n>|2026-04-21|race on write|V<n>

Status markers: . todo · x done. Cell rules: literal | → \|. Empty cell = -. Backticks OK.

Commands

/sdd:design — propose-then-critique