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.

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.

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:

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.

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.

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.

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:

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:

/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 — the spine, foundation phases, and adaptive depth in practice.
• Commands — every phase as a CLI and /forge.* slash command.
• Persistent memory — how intent survives across sessions and teammates.
• The enforcement doctrine — where the methodology stops advising and starts enforcing.