# Spec-Driven Development **In plain words:** most teams write code first and let the documentation catch up later — which means the docs quietly go stale the moment the code changes. SDD flips that: the plan (the "spec") is written and kept correct *first*, and the code is treated as something generated and checked against it, the way a house is built from a blueprint rather than the blueprint being redrawn after the fact to match whatever got built. For decades, code has been king. Specifications served code — they were scaffolding you built and discarded once the "real work" began. PRDs guided development, design docs informed implementation, but every one of them was subordinate to the code itself. **Spec-Driven Development (SDD) inverts this.** Specifications don't serve code — code serves specifications. The proposal isn't a guide for implementation; it's the source that generates it. The technical plan isn't a document that informs coding; it's the precise definition that produces the code. Forge is the runtime that makes that inversion enforceable rather than aspirational. ## What SDD inverts The traditional loop treats the spec as a lossy prelude. You write intent in prose, translate it by hand into code, and the moment the two diverge the code wins by default — because the code is what runs. The prose rots. SDD flips the authority. The spec is the artifact you maintain; the code is its expression in one particular language and framework. Maintaining software means evolving specifications, then regenerating and verifying the code that satisfies them. A pivot stops being a manual rewrite and becomes a systematic regeneration. ```mermaid graph LR Idea["Idea"] -->|dialogue| Spec["Specification"] Spec -->|clarify| Plan["Technical plan"] Plan -->|tasks| Exec["Task graph"] Exec -->|implement| Code["Code + tests"] Code -->|verify| Delivery["Validated delivery"] Delivery -->|archive| Canon["Canonical spec"] Canon -.->|next change| Spec ``` ::: info Why this is possible now Natural-language specifications can now reliably generate working code. SDD is not about replacing developers — it's about automating the mechanical translation from spec to implementation, so the human stays on intent and the machine handles the transcription. As systems grow past dozens of services and requirements pivot faster, hand-maintaining alignment between intent and code stops scaling. The spec becomes the only durable anchor. ::: ## The three layers, kept separate A specification artifact carries three distinct concerns. Collapsing them into one undifferentiated document is the failure mode that breaks spec-driven workflows the instant an upstream assumption pivots. Forge keeps them in separate, separable layers. | Layer | Question it answers | Where it lives | Owner | | --- | --- | --- | --- | | **Intent** | What, under what constraints, at what scale, and what to do when the goal can't be met | `spec.md` — user stories, non-functional requirements, failure conditions | You, the author | | **Contract** | What is testable — what passes or fails | `spec.md` — functional requirements plus measurable success criteria | You, the author | | **Implementation** | Which architecture and technology satisfy the intent | `plan.md` and the foundation `infra` baseline, plus optional `data-model.md` / `contracts/{interface-name}.md` companions when the change introduces or modifies entities/interfaces | The system, derived from intent | The load-bearing rule: **scale and non-functional targets are intent, not implementation.** "1M concurrent users" and "recover within 30s of an AZ failure" drive the architecture — so they are authored as intent, and the technical design *consumes* them rather than re-authoring them. That separability is what makes pivots cheap: swapping a deploy target invalidates only the implementation layer, never the intent or the contract above it. ::: warning Scale is not a technology choice The most common way spec-driven work degrades is writing throughput targets or failure budgets into the design layer. When you do, an architecture change silently drops the requirement that justified it. Keep targets in intent; let the design derive from them. ::: ## The spine that carries the layers Forge threads the three layers through **one canonical SDD spine** — the same ordered phases for every change: ```mermaid flowchart LR E[explore] --> P[propose] --> S[specify] --> C[clarify] C --> PL[plan] --> T[tasks] --> I[implement] I --> V[verify] --> A[archive] ``` `explore → propose → specify → clarify → plan → tasks → implement → verify → archive`. Each phase writes a specific artifact — `proposal.md`, a **delta spec**, `plan.md`, `tasks.md`, `verify-report.md` — and every artifact is a file you can read, diff, and commit. The `plan` phase may also write optional `data-model.md` and `contracts/{interface-name}.md` companions alongside `plan.md`, when the change introduces or modifies entities or external-facing interfaces. `specify` and `clarify` author the intent and contract layers; `plan` derives the implementation layer; `verify` proves the code satisfies the contract before anything is promoted. Every change is a *subset* of this spine, never a different one. **Adaptive depth** decides where a change enters — a typo fast-forwards to `implement → verify`; a bounded feature runs the Standard path; anything on a hot path or over 400 changed lines runs the full spine. The ordering never changes, only how much of it a given change traverses. ## The constitutional foundation At the base of every change sits a **constitution** — the immutable principles that govern how specifications become code. It is a foundation phase: you author it once with `/forge.constitution`, alongside the other standing-truth phases (`security`, `infra`, `brand`, `design`), and the spine operates within the ground rules it sets. Typical articles read as constraints the model cannot argue its way past: - **Test-first** — no implementation before its tests are written and approved. - **Simplicity** — start simple; justify every added layer. - **Observability** — everything inspectable and testable. - **Modularity** — features begin as standalone, reusable units. Principles are immutable; their *application* evolves through dated amendments. And the constitution is load-bearing in a mechanical sense: conflicts against it cap your `analyze` quality score, so a stale constitution quietly drags down every assessment until you bring it current. ## How constraints beat prompts The reason SDD produces stable specs is not exhortation — it's structure. Forge renders phase instructions and templates that constrain what the model is allowed to produce, and the harness verifies the parts that must not be left to narration. - **Preventing premature implementation.** The spec phase forces WHAT and WHY and defers HOW, keeping the intent and contract layers stable as technologies change. - **Forcing explicit uncertainty.** Open questions are marked, not guessed. A "login system" is flagged for `/forge.clarify` rather than silently assumed to mean email-and-password. - **Structured thinking.** Checklists act as unit tests for the spec — nothing forgotten, every requirement testable. - **Constitutional gates.** The plan phase must pass the constitution's gates — simplicity, anti-abstraction — before proceeding. ::: tip Forge is not in the model's inference loop The methodology steers; the harness enforces. Forge renders the instructions and the agent's model carries them out — but for the handful of failure modes that narration can't be trusted with (a runaway verify loop, unbounded spend, unreviewed delivery), Forge checks deterministic evidence in an **enforced ledger** and returns a non-zero exit regardless of what the agent claims. See [the enforcement doctrine](/harness/overview). ::: ## Drift is the enemy the spine defends against Because the spec is authoritative, the only real risk is code and spec silently diverging. Forge names that risk and hunts it. `/forge.drift` classifies divergence into three kinds: - **Ghost** — code with no spec behind it. - **Phantom** — spec with no code implementing it. - **Mutated** — code and spec that disagree. `/forge.reconcile` brings the two back into agreement, and `/forge.analyze` produces a reproducible 100-point quality score you can track over time. These are cross-cutting and non-destructive — run them at any point without disturbing an in-flight change. ## Promotion makes the spec canonical A change lives in its own directory while in flight. Its spec is a **delta spec** — the slice of truth this change adds or alters. On `archive`, and only after `verify` passes, that delta is **promoted into the canonical `.forge/specs/{domain}/spec.md`**, and the change moves into the immutable archive. ```mermaid flowchart LR Delta[".forge/changes/<name>/ delta spec"] --> Verify[verify] Verify --> Archive[archive] Archive --> Canon[".forge/specs/{domain}/spec.md"] Archive --> Trail["changes/archive/YYYY-MM-DD-<name>/"] ``` This is where the inversion becomes concrete. The canonical spec is not a record of what someone once intended — it is the accumulated, verified source of truth that the next change reads, extends, and regenerates from. Archive is gated on honesty: it stays blocked while any task is unfinished, so a promoted spec is always a real signal that the work behind it is done. ## Traditional vs. SDD The economics are the point. Under the traditional loop, documentation is a tax you pay before the real work and abandon afterward: ```text PRD (3 hours) → Design docs (3 hours) → Project setup (30 min) → Technical specs (4 hours) → Test plans (2 hours) → Implementation Total documentation: ~12 hours — then it rots ``` Under SDD the same artifacts are produced in minutes, stay authoritative, and drive the code rather than trailing it: ```text /forge.specify (5 min) → /forge.clarify (5 min) → /forge.plan (5 min) → /forge.tasks (5 min) → /forge.analyze (2 min) → /forge.implement Total documentation: ~15 minutes — and the docs are the source of truth ``` This is not about replacing developers or automating creativity. It's about amplifying human capability by automating mechanical translation — a tight loop where specification, design, and code evolve together, each iteration tightening the alignment between intent and implementation. ## Next steps - [The workflow](/guide/workflow) — the spine, foundation phases, and adaptive depth in practice. - [Commands](/guide/commands) — every phase as a CLI and `/forge.*` slash command. - [Persistent memory](/concepts/memory) — how intent survives across sessions and teammates. - [The enforcement doctrine](/harness/overview) — where the methodology stops advising and starts enforcing.