Deep Dive: Spec-Driven Development

The spec is the contract an ADW run is measured against. Agents don't implement your intent — they implement the spec. So the quality of an ADW run is capped by the quality of its spec: a vague spec produces vague work; a spec that pulls in the right context, names the real files, and states how to verify itself produces work you can actually merge.

This deep dive is the "why and how" behind Module 3. It covers the methodology, where a spec gets its context, the anatomy of a proper spec, and how the spec drives the rest of the loop.

The one rule

Always use /spec-create. Never hand-write a spec file.

/spec-create is the single entry point. It deduplicates against existing specs and tasks, infers the target project, researches that project for context, writes the spec in the house format, registers a digest task, and uploads the spec to the shared store. Writing a spec file by hand (a raw Write) skips every one of those steps — the spec ends up ungrounded, unregistered, and invisible to the pipeline.

Where a spec gets its context

A good spec is mostly context the agent would otherwise have to guess. /spec-create gathers that context up front, from distinct sources, so the implementing agent starts grounded instead of inferring from whatever it happens to read. Click each source to see what it contributes.

The three context sources a spec pulls from — lat.md is the primary knowledge base.

Context sources a spec pulls fromInteractive

Click any step to see what happens and who's responsible.

How a spec is formulated — the phased flow

/spec-create runs an adaptive pipeline. Step through what actually happens between your one-line description and a registered, grounded spec.

The /spec-create pipeline, end to end (quick vs deep mode).

Step 1 of 6/spec-create

1. Load planning state (silent)

Inventory active specs, open digest tasks, and the project registry (15 manifests). Nothing is shown to you — it's the context the next steps reason over.

Quick mode vs deep mode

The pipeline scales to the input. Answer honestly and it tells you which path you're on.

Choose your pathquick vs deep

Is your idea a clear, single-project change?

Anatomy of a proper spec

The house format exists so every spec carries the same load-bearing sections. Click each to see what belongs there — and why a missing section shows up later as a bad ADW run.

The load-bearing sections of a spec — plus the Gen-2 OpenSpec shape.

The spec formatInteractive

Click any step to see what happens and who's responsible.

Methodology, architecture & deployment belong in the spec

A proper spec doesn't just say what to build — it fixes the architecture and deployment decisions so the agent doesn't invent them. Real specs state the stack, the hosting/deploy model, the auth model, and the access/roles up front. For example, the Avalara reconciler's spec named its whole shape in one place:

▸What a real spec pins down (Avalara reconciler)

Gen-2: OpenSpec + roadmap-as-code

Newer projects (starting with Avalara) formalize the spec into OpenSpec: a change is a folder with proposal.md (Why / What Changes), design.md (architecture decisions), and tasks.md (the deliverables) — plus a structured roadmap.toml where each deliverable moves planned → implemented → validated → deployed, and a CI gate that refuses to mark anything "validated" without its evidence. Same spirit as the .md spec, made machine-checkable.

How the spec drives the ADW loop

Once registered, the spec is what every downstream step is measured against. Put the flow in order:

From spec to merged, in order:Put in order

1Evidence is produced and checked (RESULTS.md / validation)

2/spec-create formulates + registers the grounded spec

3A draft PR is opened for human review + merge

4The maker-checker verifies the work against the spec

5ADW plans the implementation against the spec (Sonnet)

6ADW implements on an isolated branch (Sonnet)

Notice the spec appears at both ends: it seeds the plan, and it's the yardstick the maker-checker and the evidence gate judge against. A weak spec weakens every step after it — which is why formulation is where the leverage is.

Try it

from ~/projects/wg-orchestration

$ /spec-create "add row-count validation to the QA page"▋

Hands-on lab

1. From ~/projects/wg-orchestration, run /spec-create "<a small, real change you understand>" and watch the phases: notice the dedup check and the project-research step.
2. Open the spec file it wrote under specs/. Read the Project Context and Verification sections — would an agent that read only this spec know what to build and how to prove it? If not, that's the gap to tighten.
3. Compare a Gen-1 .md spec with a Gen-2 OpenSpec change (e.g. Avalara's openspec/changes/.../proposal.md). Note what design.md and roadmap.toml add.
4. Pick one section of your spec and make it more concrete — add a real file path, a specific command in Verification. That single edit is the highest-leverage thing you can do for the run.

Knowledge check

Why should you always use /spec-create instead of writing a spec file by hand?

It's faster to typeIt deduplicates, infers + researches the project, formats, registers a task, and stores the spec — hand-writing skips all of thatHand-written files aren't valid Markdown

What makes the 'Project Context' section of a spec so important?

It's required for the file to saveIt's the researched architecture/patterns the implementing agent starts from — the difference between a grounded run and a guessing oneIt lists the PR reviewers

The spec is used at which points in the ADW loop?

Only at the very start, to seed the planAt both ends — it seeds the plan AND is the yardstick the maker-checker and evidence gate judge againstOnly by the human reviewer at merge time