Workflow · last verified 2026-07-18

Spec-first development: brainstorm → spec → plan → implement

The job this workflow does

A capable coding agent will produce a complete, plausible, well-formatted implementation of the wrong thing exactly as readily as the right one — fluency is not a signal that the request was well specified. Handed an underspecified prompt, the agent does not stop and ask; it picks an interpretation and commits, and the diff reads as confident regardless of which interpretation it picked. The failure does not show up as an error. It shows up two weeks later as a feature nobody asked for, built on assumptions nobody reviewed, because nothing forced them into the open before the code did.

This is a specialization of the general Claude Code loop — explore, plan, implement, verify (see the Claude Code workflow) — for changes where "explore then implement" is not enough: multi-file changes, anything touching a commercial claim or a shared boundary, anything where getting the "what" wrong is expensive to discover after the "how" is already built. It adds two things on top of the base loop: a written spec that settles what before anyone plans how, and gates between steps that are scripts and hooks, not sentences in a prompt.

This platform runs the loop on itself. The page you are reading is proof of its own claim: it was written as one task in a plan file that was itself generated from an owner-approved, review-hardened spec, which itself opened with a recorded brainstorm session. Nothing here is aspirational — it is the same practice that produced this page.

The workflow

1. Brainstorm — produce a design doc

Explore intent, options, and trade-offs before anything is locked in. The point is not polish — it is surfacing the interpretation you would otherwise pick silently and never revisit. A brainstorm that never gets written down is not a step in this workflow; it is a conversation nobody can check later.

In practice on this repo, the brainstorm is a recorded decision, not a vibe: the spec this very page traces back to opens with a status line that names the session it came from — "draft — owner-approved design (brainstorm session 2026-07-17), spec pending owner review." The brainstorm produced a design the owner approved; only after that did spec-writing start.

HITL checkpoint: the design gets a human look before it is formalized. This is the cheapest point in the whole workflow to change your mind — before a spec, a plan, or a line of code depends on the answer.

Artifact: a design doc, or a short approved-design note — sometimes a few paragraphs, sometimes literally the opening of the spec that follows. What matters is that the trade-offs got written down and looked at by a person, not that the review took any particular form.

2. Spec — produce a spec file

Convert the reviewed design into a structured spec. The spec template works backwards from the customer outcome — a discipline borrowed from Amazon's working-backwards practice — deriving scope, constraints, and implementation from that outcome, not the reverse. On this repo every implementation spec follows one fixed section order, so both humans and agents know exactly where to find scope, constraints, and the acceptance bar without re-deriving the shape of the document each time:

# the section order every spec on this repo keeps
Business Objective    # why, in one sentence, and what success means
User Outcome           # what changes for the person on the other end
User Journey            # the primary path through the change
Scope                   # exactly what changes + an explicit Out of scope
Constraints             # architecture / product / technical
Implementation           # file-by-file steps
Decision Guidance        # tie-breakers for whoever implements it
Acceptance Criteria       # machine-testable where possible
Measurement              # how you will know it worked, and when you check
Release Notes

The "Decision Guidance" section carries its own weight: it is where the spec author writes down what the implementer should default to when it hits a choice the spec did not anticipate, instead of leaving that choice to be improvised mid-implementation.

HITL checkpoint: the spec's status flips from draft to owner-approved before anyone writes a plan against it. This is the point where "what are we building" gets settled, deliberately separated from "how are we building it" — collapsing the two is how a plan ends up encoding an assumption nobody actually agreed to.

Artifact: the spec file itself, committed to version control and versioned like code — not a chat transcript, not a Slack thread, a file with a status that changes when it is approved.

3. Plan — produce a plan file

Turn the approved spec into an ordered, file-by-file task list. Each task names the files it touches, what it consumes and produces from the other tasks (so independent tasks can run in parallel without stepping on each other), and how to verify it before it is considered done. The plan is where "what" turns into a sequence of concrete, checkable steps — and where a spec that skipped a hard question gets caught, because you cannot write a task list for a decision that was never made.

This is also where Claude Code's own Plan Mode earns its name. Switching a session to the read-only plan permission mode enforces exactly this boundary at the tool level, not just as a convention: the agent can investigate and propose, but it cannot edit or write a single file until the plan is explicitly approved (see the permission-modes table on the Claude Code workflow page for the full mode list). Whether the plan comes out of an interactive Plan Mode session or a saved plan file generated from the spec, the shape is identical — a plan is a proposal, not an action, until a human says go.

HITL checkpoint: plan approval is the last point before any code changes, and on this repo it is the one gate the tooling enforces technically rather than just procedurally — a session in Plan Mode is structurally unable to skip it.

Artifact: the plan file — dated, checkbox-driven, one task per file or surface, each task carrying its own verification command. This page is exactly one such task, in a plan file that lists three other pages as its siblings and names the file each one had to produce.

4. Implement — produce a reviewed diff, behind deterministic gates

Execute the plan's tasks, one scoped diff per task. This is where prompt-only instructions stop being sufficient. An instruction living in a CLAUDE.md file or a prompt is advisory — the agent can drift from it, especially deep into a long session, after a compaction, or simply because the instruction never fired for the specific case in front of it. The gate that actually holds is a deterministic check: a script, a hook, a test — something that fails closed on its own, instead of depending on the session remembering to ask.

This repo has a real, dated example of exactly that failure and fix, not a hypothetical one. Getting a public-copy diff reliably routed to an independent claims-review pass took three attempts at rewriting a skill's trigger description — a phrasing tweak, then another — before any of them held. What actually closed the gap was not a fourth rewrite; it was a PreToolUse hook that fires on what changed — a diff touching a commercial or positioning claim — rather than on whether the session happened to notice a trigger phrase mid-conversation, with a deterministic release gate behind it as the final invariant: even a diff that slips past the hook cannot ship unreviewed. Fail-closed beat prompt-only the moment the test case was a session that was tired, compacted, or simply did not reread the instructions.

// the shape of the fix - gate on WHAT changed, not on the session remembering to ask
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "node scripts/check-copy-gate.mjs" }]
    }]
  }
}

HITL checkpoint: the reviewed diff. A human, or an independent review pass with clean context, signs off before merge — never the same session that wrote the diff grading its own work. On this repo that pairing is literal: deterministic checks (typecheck, tests, content-lint scripts) plus an independent reviewer agent for anything touching public copy, run before the owner's own sign-off.

Artifact: the reviewed diff — gates green, ready to ship.

Artifacts this workflow produces

• The design doc — the brainstorm's trade-offs, written down and reviewed (step 1).
• The spec file — working-backwards structure, status flipped to approved before planning starts (step 2).
• The plan file — an ordered, checkbox task list, one task per file, each carrying its own verification command (step 3).
• The reviewed diff — gated by deterministic checks, signed off by a human or a clean-context reviewer, not by the session that wrote it (step 4).
• The gate config itself — hooks and lint scripts, versioned in the repo like the code they protect.

Pitfalls

• Skipping the spec because the diff "looks small." A small diff is exactly where an unwritten assumption slips through unreviewed — the size of the change is not the size of the risk it carries.
• Treating the plan as busywork instead of a contract. If a task's file list drifts from what the spec actually scoped, the implementation drifts from what got reviewed at the spec step, and nobody re-reviews it.
• Gating with an instruction instead of a hook. A prompt-only fix reads as done in the session that wrote it and then fails on the exact session that is compacted, distracted, or new — that is not a hypothetical, it is what three failed rewrites proved before a hook closed it.
• Skipping the checkpoint between plan and implement. This is the one gate Claude Code enforces at the tool level, not just as a convention — skipping it turns "review the plan" into "review the diff after it already happened."
• Letting the writer grade its own work. The session that wrote the diff has every incentive to read it as compliant. Use an independent reviewer with clean context, the same Writer/Reviewer split the Claude Code workflow prescribes for verification generally.

When not to use this workflow

Skip the full apparatus for a change that fits in one sentence — a copy fix, a version bump, a one-line rename needs no spec and no plan file. The overhead should scale with what is at stake, not apply uniformly to every diff. Skip the deterministic-hook step specifically for changes that are genuinely reversible and low-blast-radius, where an ordinary code-review pass already catches the failure mode a hook would catch.

The exemption is narrow on purpose: it covers "small," not "convenient." A change that touches a shared boundary, a public claim, pricing, or anything you cannot cheaply revert once it ships was never actually small — reaching for the exemption there is scope creep dressed up as judgment, exactly what the claims-gate example in step 4 crossed.

Changelog

• 2026-07-18 — initial version, verified against this platform's own spec/plan practice and the Claude Code Plan Mode and hooks facts already sourced on the Claude Code workflow page.