Write the spec: what the agent does, never how

The first promotion turns your brief into a spec: a written document the worker reads on every run that says exactly what it does, on what, and to what standard. The method for writing one has a foundation and four phases: constitution, then Research, Specify, Clarify, Build, and any gap found while building sends you back to fix the spec. ¹ Every project run this way leaves the same four artifacts behind, the constitution, spec.md, plan.md and tasks.md, plus the working result. ¹ This page gives the method, then says where the four live and what each one looks like.

The spec is the product; code is a build output

For decades the spec served the code: write a brief, build the thing, discard the brief. Spec-driven development inverts that. The spec is the durable artifact you maintain; code is generated from it, and re-generated when the spec changes, which means re-running the build loop over the updated spec and reviewing the result, not pressing a compile button. ¹

A good spec answers three questions, in order: why, what problem and for whom; what must be true when this is done, the behaviours, inputs, outputs, rules and edge cases; and what not to build, the boundaries, the one section that prevents most "it did too much" and "it did the wrong thing" failures. What is missing is the how. "Users can reset a forgotten password via an emailed link that expires in 30 minutes" is spec; "use a JWT and a Postgres tokens table" is implementation, and belongs in the plan. Mixing the two too early is the most common beginner mistake. ¹

The test for every line of a spec: could a competent person build the wrong thing and still technically satisfy this line? If yes, tighten it. A spec is finished not when there is nothing left to add, but when there is nothing left to misread. ¹

The book attaches one caveat to the inversion. "Build output" does not mean black box. The spec is the source of truth for what the system does; the code is still the only honest evidence of how well it is holding together, because coupling, duplication and names that no longer match reality are visible only in the implementation. It cites a 2026 field report from production systems maintained with agents: a tangled codebase makes the agent make more wrong assumptions, burn more context and chase more dead ends, so bad design still costs money, and the bill now arrives in tokens and retries. ¹

Three levels, and the one this room uses

Spec-driven development is not all or nothing. ¹

Start at Spec-First and grow into Spec-Anchored. The discipline is identical at every level; only how strictly you keep the spec in sync changes, and a higher level does not reduce the obligation to read what shipped, it raises it, because agent-written code decays faster than human-written code and the debt compounds earlier. ¹ A worker that runs every week is maintained for months, so this room is Spec-Anchored from its first change; the rule for that is at the end of this page.

The constitution: rules above every spec

Before any one feature, write a short document of persistent rules for all of them. In a coding agent it is the rules file (CLAUDE.md or AGENTS.md). It is principles, not an encyclopedia, and it is persistent context, not enforced law: the agent loads it every session and follows it more reliably the more specific and concise it is, but loaded is not guaranteed. Rules that must never be broken, such as never committing secrets, need backing by tests, hooks, permissions or a human reviewing the diff. ¹

Six to eight lines is the right size. The test for every rule: would removing it let the AI make a mistake? "Write clean code" fails that test, because the AI already tries to; "never touch published/" passes, because the AI could not have known it. ¹ A constitution that demands enterprise-grade process for a weekend project poisons every phase after it; match it to the stakes and raise the bar later. ¹

The book's example, for a note-taking app, shows the shape, and its third line is the rule this page turns on: every feature ships with its spec in specs/. ¹

# Constitution, Smart Notes

## Principles

- Plain language over cleverness. A new contributor should understand any file in 5 minutes.
- Prefer well-established libraries over custom code. Research before reinventing.
- Every feature ships with its spec in `specs/`. The spec is the source of truth.

## Constraints

- Stack: keep it to what's already here. Propose, don't add, new dependencies.
- Never touch `published/` or anything in `src/generated/`.

## Definition of done

- Behaviour matches the spec, edge cases included.
- A human has reviewed the diff against the spec before merge.

Three versions of the same constitution show the two ways it fails. Too light is "write clean code, be consistent, use best practices", which says nothing. Too strict is twelve rules on coverage percentages, performance budgets, commit-message format and review steps, all for a weekend app. Just right is the six to eight lines above: principles the AI cannot infer and constraints it could not have known. ¹

For the agent this room builds, the constitution is the place to write the gates from your step table as rules the worker can never argue with: which actions it may take alone, and which stop for a person. It is a prompt, and so is every instruction and brief on the pages that follow; write them under the AI prompting guide: only what the model cannot work out on its own, neutrally framed, pruned by the delete test.

Phase 1: research before you write

You cannot spec what you do not understand. Have the AI map the territory first and report a one-page findings document, not code and not yet a spec. The prompt that works in any tool: ¹

Research what's involved in building [feature]. Investigate these separately
and report each on its own: (1) how this kind of thing is usually done,
(2) the main approaches and their trade-offs, (3) anything in our existing
project it has to fit, (4) the failure modes and edge cases I should worry
about. Give me a one-page findings doc: what exists, the options, and what's
still unknown. Don't propose a final design or write any code yet.

Phase 2: write the spec, the what and why, never the how

Draft it with the AI, then make it precise by hand. A workable spec has, at minimum, six sections: ¹

Describe behaviour only: no database, framework or file layout. That belongs in the plan, and keeping the spec implementation-free is what lets you change tooling later without rewriting your intent. The book's own "is my spec done?" list is those six sections plus that one line: no how. ¹

What "tighten by hand" means, in the book's own before and after: ¹

Before: "Users can reset their password."

After: "A signed-out user can request a password reset by email. The link works once, expires after 30 minutes, and a used or expired link shows a 'request a new link' message. The response never reveals whether an email is registered."

The first line would pass a build that emails a plaintext password to anyone who asks. Every detail you leave out, the AI decides for you, so decide the ones that matter here, in words. ¹

Your three lines from Gate 3 map straight onto this: "works from" and "want at the end" become the user scenarios, "done when" becomes the acceptance criteria, and the DECISION rows of your step table become edge cases and rules that say "stop and ask".

Phase 3: clarify by interview

The highest-value, most-skipped step: turn the questioning around and have the AI interview you until nothing is left to misread. Fixing an ambiguity here costs a sentence; fixing it after implementation costs a rebuild. ¹

Before we build anything, interview me about this spec. Ask one question at
a time, focusing on ambiguities, missing edge cases, and unstated assumptions.
Keep going until you could hand this spec to a stranger and trust they'd
build exactly what I mean. Don't write any code yet.

The book's example of skipping it: a team specs "users can upload a profile photo", and within a day a 40 MB file, two users overwriting each other, and a broken file rendering blank arrive as bugs, three unstated assumptions the interview would have caught in a sentence each. ¹

How this record runs the interview. The book's prompt says one question at a time. This record keeps every question and changes the pace, because a person who is not an engineer gives up after the tenth round, and a question dropped to save time is a blank the model fills with a default. Three rules:

1. Nothing is skipped. Every ambiguity, edge case and unstated assumption is still asked. The spec is not drafted until every blank is answered; an unanswered question stays open and the spec waits.
2. Rounds, not one question per message. Gather every question the current section needs into one message, as a short numbered list, so the person answers a round at a time. Three or four rounds are normal; thirty single questions are not.
3. Three answers with every question. The first two are the most likely answers, written out in plain words, so the person can pick one; the third is always "something else, in your own words". A proposed answer is a suggestion to accept or correct, never a default that stands if the person stays silent.

Plain words throughout: the person sees what the worker will do, where a person says yes, and what "done" looks like, never the names of the files.

The first round is pre-filled. Before any section is interviewed, the opening round on demo or production proposes the depth, the model and every blank that can be read from the person's own words, with the most likely answer already selected and marked as the assumption. The three-answer rule still holds; what changes is that the person only corrects. At demo depth that round, with at most one round of corrections, is the interview, and one approval word covers the spec and the plan.

Phase 4: build from the spec

Right-size the process to the change: a one-sentence change, just ask; an uncertain approach or a few files, plan first and review the plan before any code; a multi-file change, the full loop of plan, build, verify in small checkable steps. Two things never change: review the approach before code, and check the result against the spec. ¹

PLAN:   Based on the agreed spec, propose a technical plan: stack, structure,
        and the key decisions, each with its trade-off. Match our constitution
        and reuse what already exists rather than adding new dependencies.
        Don't write code yet; I'll review the plan first.

BUILD:  Implement the agreed plan in small, checkable steps. Do one step at a
        time, and after each, check it against the spec and stop for me to
        confirm before the next. Commit after each so every step has a clean
        rollback point.

Who breaks the work into tasks? The agent does. You do not hand-write a task list. Claude Code and OpenCode plan and decompose the work into their own tracked checklist and work through it, marking each item done as they go; your job is reviewing that breakdown and checking each step against the spec, not authoring it. In a chat tool with no task tool, ask for the list as a document. ¹

The expensive thinking is the plan. Once the approach is agreed, building is following the steps, which a cheaper or faster model does well; in the coding agents that is one setting. ¹

Close the loop: turn the acceptance criteria into actual checks, automated tests where you can write them, and run them after each step. If a check fails because the spec was vague rather than the code wrong, fix the spec first. ¹ That is exactly what the tests page does: the acceptance criteria become the tests, written before the code.

Acceptance criteria prove the behaviour is right. They do not prove the system is still healthy, and only the first question is automated. So every few build cycles, run a separate design pass: ask the agent to list the files it touched, where a rule is now written in two places, and which names no longer describe what the thing does, then read that part of the code yourself, because the agent is a poor judge of its own output here; it optimises for a passing build, not for a system that stays cheap to change. ¹

Where the four artifacts live

In a coding agent every artifact is a file, version-controlled next to the code it produced, and the tool enforces the gates you self-imposed in a chat window. The constitution is the rules file, CLAUDE.md or AGENTS.md. The rest live in specs/, one folder per feature: in the book's example the research findings land in specs/weekly-digest/research.md, and spec.md and plan.md are kept as files beside them. The task list is usually the agent's own tracked checklist, worked through one task at a time with a commit after each, so git log reads like that list; write it out as tasks.md when the tool has no task tool or you want the breakdown reviewed as a document. In claude.ai the same four are Artifacts you copy forward. ¹

One spec is a document; a folder of dozens is a system. Once specs/ holds many, the live question stops being "is this spec clear?" and becomes "do these specs still agree?" Features interact, so a change to one can ripple into others, and when two specs point to conflicting choices the constitution is what settles it. Keeping the whole set consistent as it grows is the real jump from "I can spec a feature" to "I run a repo on this method". ¹

This room keeps every document about one worker in that one folder, specs/<worker>/: the delegation map, the gates, the experience brief, the research, the spec, the plan and the governance record. That is the room's own convention, built on the book's rule that every feature ships with its spec in specs/; the skill page lists the full layout.

Keep the spec alive. A spec is only the source of truth if it stays true. When behaviour changes, change the spec first, in the same commit as the code, then re-derive the code. The book's name for skipping this is Waterfall, and its picture of the drift is plain: someone tweaks an email's subject line directly in the code and ships it; the spec still describes the old subject; three weeks later a new teammate reads the spec, "fixes" the code to match it, and quietly breaks the thing that was working. The fix is cheap and boring: the change goes into spec.md in the same commit as the code, every time, and a change is done when the diff on the spec and the diff on the code tell the same story. ¹

What the four artifacts look like

The book's trimmed examples, kept because their shape is what matters: every functional requirement is numbered, every edge case is a rule, every acceptance criterion is checkable, every task cites the requirement it satisfies, and the final task is verification, derived straight from the acceptance criteria. Real ones are longer. ¹

# spec.md, Weekly Digest

## Goal
Email each user a once-a-week summary of their own notes so they
re-engage without opening the app. Reduce silent churn.

## User Scenarios
- A user with notes this week gets a Monday-morning digest listing them.
- A user with no notes this week gets nothing (not an empty email).
- An unsubscribed user gets nothing, ever.

## Functional Requirements
FR-1 Digest sends on the user's local Monday at 8:00am.
FR-2 Include only notes created or edited in the prior 7 days.
FR-3 Zero qualifying notes: no email is sent.
FR-4 Unsubscribed users are skipped.
FR-5 A send failure is retried once, then logged; it never blocks others.

## Edge Cases & Rules
- Time zone missing: fall back to UTC.
- 50+ notes: list the 10 most recent, then "and N more."

## Out of Scope
- Digest customization, frequency options, non-email channels.

## Acceptance Criteria
- [ ] A user in Asia/Karachi receives the digest at their local Monday 8am.
- [ ] An empty week sends no email (verified in logs).
- [ ] Unsubscribed users receive nothing.
- [ ] One simulated send failure retries once, then logs, others still send.

# plan.md, Weekly Digest

## Approach
Reuse the existing mailer service (constitution: prefer what exists).
A scheduled job runs hourly, selects users whose local time is Mon 08:00,
builds the digest from the notes query, and hands it to the mailer.

## Key Decisions
- Scheduling: hourly cron + per-user timezone check (no per-user timers).
- Templating: reuse existing email template system.
- Failure handling: wrap each send; retry-once lives in the job, not the mailer.

## Touch Points
- new: jobs/weekly_digest.* | reuse: services/mailer, models/note
- no schema change required

# tasks.md, Weekly Digest

1. Note-selection query: notes per user from the last 7 days. [FR-2]
2. Eligibility check: local Monday 08:00 + subscribed. [FR-1, FR-4]
3. Digest builder: top 10 + "and N more"; skip if empty. [FR-3, edge]
4. Wire to mailer with retry-once + logging. [FR-5]
5. Tests for each acceptance criterion. [Verify]

Write yours in the same shape for the worker you are promoting, then continue to govern it; its answers become rules and acceptance criteria in this spec before any test is written.