Spec-driven development with plan files

The pattern that took over agentic coding workflows in the last year is a pipeline: high-level spec → technical plan → implementation → review. The agent drafts the plan as a file; the human edits the file — cheap to correct at this stage — and only then does code get written. The insight is old engineering wisdom re-applied: errors cost least where they're introduced. A wrong assumption costs one edited line in a plan file, an hour of generated code later. This is also the biggest token lever there is — wrong-direction implementation is the most expensive waste an agent produces, and no context command refunds it.

Plans fail in two directions: the vague wish-list ("improve the API") and the 600-line pseudo-implementation nobody reviews. The load-bearing parts are four:

SPEC       5-8 lines. Verifiable OUTCOMES, not activities.
           "users can reset passwords via email" not "work on auth"

PHASES     each with a scope boundary (what it does NOT touch)
           and a TEST GATE: the check that must pass before the next phase

RISKS      the 2-3 likely failure points, each with a rollback path

SEQUENCE   one paragraph: why this order (dependencies, risk front-loading)

The test gate is the piece most plans miss, and it's the one Anthropic's agent guidance keeps circling: give the model a check it can run. A phase without a gate is a vibe; a phase with one is verifiable. Scope boundaries do the quiet work of stopping the agent's favorite failure — wandering into adjacent code "while it's there."

Turning a goal into that structure is itself a prompt job, and it's the same job every time — which makes it exactly the kind of prompt worth versioning instead of re-improvising. Ours is public: spec-driven-plan produces the four-part plan (and states its assumptions instead of silently choosing); its sibling prioritization-matrix handles the step before — deciding which goal deserves a plan at all:

ple get spec-driven-plan \
  --var goal="add magic-link login" \
  --var constraints="no new deps; ship behind a flag" | claude -p

Each project's plans then improve the prompt itself: gates that caught real breakage graduate into v2's instructions, with the version history as the paper trail of what your team learned about planning — the file that compounds while individual plans come and go.