blueprint — spec to ordered task plan

A plan's job is to make the build boring: a sequence of small, ordered steps, each of which leaves the system working and can be checked on its own. You are turning the what (the spec) into an executable in-what-order, without writing the code yet.

Read CONVENTIONS.md for the workspace (§1), the resume sweep (§5), git isolation (§11), the ledger (§2), the intake schema (§3), memory (§4), integrations and data leaving (§10), the role dial (§6), gates (§7), multi-agent rules (§8), commit policy (§12 — Status is the resume marker), freshness (§17), and workspace integrity (§20).

Journal every run (§2.1). The first write of the run, once the task folder is resolved (§20.1), is a START entry in the task's log.md; then set this phase in_progress in state.json. Append a DECISION entry before acting on any choice that shapes the work, and a STOP entry before every reply that ends the turn. Write only the files the workspace tree names (§1): nothing lost, nothing stray. Before asking a question or deciding, check the user's judgment (§4.1) for a confirmed rule that covers it, and journal who decided.

Step 1 — Read the spec, the standards, and the code

Load spec.md and standards.md, then read the code each task will touch and its neighbours of the same kind. Every file a Shape or Mirrors line names must be one you opened in this run; a file the plan creates is marked new, and a kind the repo has never had is labelled new (§4.2). Check whether the behaviour already exists, searching two ways (§5.2): a task that rebuilds existing code is a plan error. Every task must trace back to a success criterion in the spec and fit the project's established conventions. If a criterion has no task, or a task serves no criterion, fix the mismatch before continuing.

Step 1b — Validate the dependency reality

Before cutting tasks, check what the plan will lean on — surprises here become release/test failures later: are the libraries the plan assumes actually in the manifest and lockfile (read them in this run)? Are their versions current and supported (checked on the web against today's date and cited, §17, never from memory)? Does the plan call any deprecated API/method? Is a needed capability missing entirely? That is not a task you add: it goes to the plan gate as options (which library, or build it), each with what data it would send outside (§10), and the user chooses. Flag findings in the plan so no task builds on a dependency that isn't really there.

Step 2 — Decompose into vertical slices

Break the work into thin vertical slices — each slice delivers a small piece of working, testable behavior end-to-end, rather than a horizontal layer that can't be exercised alone. Size each task; anything large enough to hide surprises gets broken down further. Order the tasks by dependency: a task appears only after everything it needs is already built. Within that ordering, schedule the highest-risk / highest-uncertainty tasks first — fail fast where failure is cheapest. Split heuristics: an "and" in the title, more than 3 acceptance bullets, or two independent subsystems means it's two tasks.

For each task capture:

### Task NN — <short title>
Goal:        <the behavior this delivers>
Consumes:    <what must exist first — prior tasks, interfaces, data>
Produces:    <the interface/behavior it leaves behind for later tasks>
Acceptance:  <the observable check that proves this task is done — a test can assert it>
Shape:       <which files this touches or creates · new abstraction vs reuse-and-pass-args,
              with the reason. Genuinely ambiguous (new base class vs reuse + arguments)? Put
              BOTH options and the trade-off here — the approval gate only works on a choice
              the user can see>
Mirrors:     <the existing files this task follows, and what it takes from each (§4.2). If
              the codebase has two ways for this kind of code, the choice goes here as a
              question with both ways and a recommendation, so the gate settles it.
              A better way worth proposing (§4.3) goes here too, with its options, so the
              user chooses it at the plan gate instead of discovering it in the diff>
Size:        <XS | S | M | L>  (break down anything L)
Status:      todo   (construct updates this to in-progress → done as the slice goes green —
                     it is the resume marker now that slices aren't committed individually, §12)

The Consumes/Produces fields are what let each task be built and reviewed in isolation — and what let worker agents run in parallel where the dependency graph allows.

Step 3 — Write plan.md

Write the ordered task list to plan.md in the task folder. Lead with a one-line build sequence, then the task detail. Mark which tasks are independent (parallelizable) and which are strictly sequential — engineer uses this to decide fan-out.

At higher roles (Principal/VP), also note the invariants the plan must preserve and any architectural decision worth an ADR entry in decisions.md.

Step 4 — Write to disk, verify, then update the ledger

The plan is not done when it exists in chat — write plan.md to disk, list the file to verify it exists non-empty — then run Step 4b's fresh-eyes pass against the file you just wrote, and only after it passes set blueprint in state.json (§20.2). Close with the artifact checklist so the user sees reality, not claims:

Task artifacts on disk (from a listing run now): log.md · intake.md · spec.md · plan.md · state.json

For multi-repo workspaces, every task in the plan names its target repo (Repo: line) — per the profile's implement/review-only roles (§4).

Step 4b — Fresh-eyes pass, before you present it

Review the plan as if someone else wrote it, reading only plan.md and spec.md. You know what you meant by each task; the file is all the builder gets, and a step you can fill in from memory is a step that isn't written down. In multi-agent mode dispatch a fresh reader that never saw the decomposition (§8's five-field brief; Output: is the answers below). Single-agent, re-read the two files alone — not the conversation — and check:

• Does every spec success criterion map to at least one task? Does every task serve one — except setup/scaffold tasks, which serve all of them and map to none? A greenfield plan legitimately opens with "create the project", and a check that flags it teaches you to ignore the check.
• Could someone else build each task from its Goal / Acceptance / Shape alone, without asking you what you meant? That is the actual bar — worker agents and your colleagues both get only the file.
• Does any task contain a placeholder or a hand-wave ("handle errors somehow")? Replace it.
• Are the Consumes/Produces interfaces consistent — does each task's Consumes match a prior task's Produces?
• Is anything ordered wrong (a task needing something built later)?

Fix what this finds before presenting — an approval gate only works on a plan the user can actually evaluate.

These thoughts mean stop — you are about to present a plan that hides its decisions:

Step 5 — Approval gate

Present the plan and get explicit approval before building starts. Record it in intake.md (§3) and set blueprint.approved: true in state.json (§2). Do not begin construct until the plan is approved. A plan.md on disk with approved:false is not done — a resumed run will re-present it, not build from it. If the user is absent, leave approved:false and stop.

Plan amendments (when build reality disagrees)

Plans meet reality in construct. Deviating silently and stalling are both failure modes; the amendment loop is the correct third path — but not every surprise deserves the full loop.

Separate a ruling from an amendment, or the plan gates start firing on trivia and the user learns to approve without reading:

• A ruling — the plan is silent or ambiguous, and the choice changes nothing the user approved: what to name a private function, the order of two independent steps. Journal the decision and its one-line reason in log.md as By: run, then continue (§2.1). Never in intake.md, which holds the user's answers and feeds judgment (§4.1). Which of two existing helpers to reuse, or anything a lock names, is never a ruling: it is §4.2's question or an amendment.
• An amendment — the approved shape changes: a task is infeasible, mis-ordered, or missing; scope moves; an interface the spec named changes. Amend plan.md (change only what must change), bump a plan version note (v2, with a one-line reason), get the changed part re-approved (§7 — the original approval doesn't cover a different plan), and record it in intake.md.

When unsure which it is, it is an amendment. And anything destructive or irreversible — dropping a feature, deleting data, changing a public contract — is always an amendment, never a ruling, however obvious it looks from inside the build.

Composition

• Consumes: spec.md, standards.md, project memory.
• Produces: plan.md, the blueprint phase marked done+validated in state.json, and any new ADR entries in decisions.md.
• Receives from: define (approved spec), engineer (PLAN phase), or construct when build reality forces an amendment.
• Hands off to: construct, which builds each task TDD-first in plan order.
• Invoked directly, or by engineer as the PLAN phase.

Skip rule

For a trivial one-step change, planning can be skipped on §7's terms (announce it when the blast-radius search shows nothing depends on the change, ask when something does), and construct handles it directly with a single implicit task.

Self-review (author's notes)

• Mis-routed? engineer routes here once a spec is approved; wrong for a self-contained one-liner, which construct handles directly. Pick this over discover when the what is settled and only the order is open.
• Single-agent safe? Yes — it only reads, decomposes, and writes a plan file.
• Leaks specifics? No framework or product is named; conventions come from standards.md.
• Contradicts another skill? No — it stops at approval and never writes production code.