Skip to main content

Module 3: Spec-first design

Module 0 introduced spec-first as one of the two big ideas behind ADW. This module makes it concrete: what a spec actually is, why it gets reviewed before implementation starts, and how it connects to the rest of the loop you'll run in Module 4.

Go deeper

For the full breakdown of how a spec is formulated — the /spec-create pipeline, where a spec pulls its context, the anatomy of a proper spec, and how it drives the whole loop — see the Spec-Driven Development deep dive.

Why write a spec before code​

The real local ADW loop (adws/adw_plan_build.py) doesn't jump straight from a task description to a diff. It classifies the work, generates a branch, and then plans the implementation with Claude Sonnet (claude-sonnet-4-6) before a single line of production code changes. If a spec_file is attached to the task, there's also a dedicated step to review the spec for completeness once implementation is done — skipped only if the spec was already complete going in.

The reason this ordering matters: a plan is something a different pass can check against. "Did the implementation do what it said it would do?" is a well-posed question when there's a written plan to check it against, and a much fuzzier one when the only record of intent is buried in a chat history.

ADW: The Spec-First Agentic Engine (infographic — NotebookLM-generated, illustrative)
ADW: The Spec-First Agentic Engine (infographic — NotebookLM-generated, illustrative)
Reading the infographic

This infographic frames spec-first as an "engine," which is a fair description of the effect but not a literal architecture diagram. The concrete mechanic behind the artwork is what's described above: plan → review plan → implement → (optional) review spec completeness. That's the sequence you'll run yourself in Module 4.

What makes a good spec​

A spec doesn't need to be long. It needs to be specific enough that someone other than its author could review it and know whether the result matches it. At minimum, a usable spec covers:

  • What should change (the concrete behavior, not just a feeling — "the export button should include a CSV option" rather than "improve exports").
  • Why it matters (so a reviewer — human or agent — can catch a technically-correct-but-pointless implementation).
  • Scope boundaries — what's explicitly out of scope, so an agent doesn't wander into an unrelated refactor.
  • How you'd know it worked — even a rough acceptance criterion gives the later evidence-gating step (Module 5) something to check against.

The AI-architect critique​

Before implementation starts, the plan gets reviewed — an agent acting as a critic reads the plan against the spec and the project's own lat.md-grounded context, and flags gaps: missing edge cases, scope creep, an approach that conflicts with an existing documented decision. This is the same "don't grade your own homework" principle from Module 0's maker-checker gate, just applied one step earlier, to the plan rather than the implementation.

Terms like "quality gate"

You may see illustrative phrasing elsewhere (a specific dimension count on a "quality gate," for instance) attached to this review step. Treat the count as marketing framing from the seed material rather than something to memorize. What's real and worth remembering is the mechanic: a plan gets reviewed by a separate pass before implementation, using the spec as the yardstick.

Roadmap-as-code​

A single spec describes one change. Projects that run many ADW tasks over time track their specs and deliverables as a structured roadmap committed to the repo — a machine-readable roadmap file rather than a wiki page that drifts out of date. Deliverables move through an evidence-driven lifecycle (for example: planned, implemented, validated, deployed), and a linter enforces that a deliverable can't claim a later stage without the evidence to back it up — the same "done means proven" principle that governs the draft-PR gate at the end of the loop. You'll see this connect directly to your own project in Module 7, when you onboard a repo onto ADW.

Wastey says

A spec you'd be comfortable handing to a new teammate with zero other context is almost always specific enough for an agent, too. If you find yourself writing "just follow the existing pattern" with no further detail, that's a sign the spec needs one more pass.

Hands-on lab​

  1. Pick a small, real (or realistic) change you could imagine making to a project you know — a bug fix, a small feature, or a chore. Nothing large; this is a practice spec, not a design doc.
  2. Write it down in four short sections: What, Why, Out of scope, and How you'd know it worked. A few sentences per section is enough.
  3. Hand your spec to a Claude Code session and ask it to critique the spec before implementing anything — explicitly ask it to look for missing edge cases, ambiguity, or scope creep, the same way the AI-architect review step would.
  4. Revise your spec based on at least one piece of that feedback. Notice how much more concrete the revised version is.

Practice: step through the spec-first flow​

Step 1 of 5Spec-first flow

1. Write the spec

What should change, why it matters, what's explicitly out of scope, and how you'd know it worked.

Order the roadmap lifecycle​

Put a roadmap-as-code deliverable's lifecycle stages in order:Put in order
1deployed
2planned
3implemented
4validated

Knowledge check​

In the real local ADW loop, what happens between classifying a task and implementing it?
Why does having a written spec matter for later review steps?
What is roadmap-as-code?

Next up: Module 4 — The local ADW loop.