planning-flow

Planning Flow

Overview

Turn a request into one plan: the current, complete answer to the user's ask, with the decisions that shaped it and the caveats that remain. The process behind it — a map of the codebase, parallel exploration, a zero-context review, rounds of questions, spikes, an adversarial review — exists to make the plan right; none of it belongs in the plan or in the message that delivers it.

These rules bind everything below:

1. The plan never describes its own earlier versions. Every revision rewrites the file in place so it reads as if written fresh today. The only record of the past is the decisions section, where you record a choice with its alternative and its reason. No "revisited", no "Edit:", no "after the review", no struck text, no revision headings, and no reviewer tally in chat.
2. The reader has not seen the code. You read hundreds of lines; the user read none. A function, file, or variable name is a label for a thing you must explain in plain words, never the explanation. Full rules in communication.md.
3. Technical direction is yours, logged; functional and operational direction is the user's, asked. The authority table below decides which is which, and a decision the user already made is never asked again.
4. Facts are yours to find; decisions are the user's to make. Find the facts yourself. Ask the user only what the codebase cannot answer. Ask every question in the one shape in question-format.md, and in chat ask one per message, each after the questions it depends on are answered. Never answer a question you put to the user. A change can be so simple that there are no questions; do not invent them.
5. The plan is a document, and it plans the simplest thing that works. The deliverable is markdown and nothing else — the plan file, and, outside plan mode, the shared codebase map step 0 keeps beside it: no prototype, mockup, scaffold, demo, or code is handed over as part of the plan. While planning, probes, prototypes, and scaffolds are encouraged as ways to check a fact (rule 8), under the permission lanes in verification.md, and are deleted before the plan is presented. Inside that file, use everything the viewer can render: Mermaid diagrams, diff and migration fences, API cards, file trees, question fences, a summary card. A picture of the design belongs in the plan; a working copy does not. The solution sits on the lowest rung of the ladder in plan-template.md that answers the ask: not needed → cut it; the codebase has it → reuse it; the standard library or platform has it → use it; an installed dependency has it → use it; otherwise the minimum that works. A higher rung is a decisions entry, rejected, with the reason. Never cut: validation at a trust boundary, data-loss handling, security, accessibility.
6. Nothing an agent writes counts things that live elsewhere. The plan, the codebase map, a decisions entry, a question, a message: none says how many there are ("the 24 handlers", "all seven tests", "three services"). The next one added makes the number wrong, and a stale number still reads as a fact. List the items, or state the rule that finds them; a reader who needs the number counts. A number stays only when it is itself the fact: a limit or threshold the code enforces, a quantity the work must use ("batches of 500"), a version, a size band, or a measurement with what it measured.
7. Every subagent is one-shot; more work is a new subagent. A mapper, explorer, reviewer, cold implementer, spike, or verifier gets one self-contained prompt, returns its result, and ends. It never waits for a reply, for the user, or for your next instruction, and you never resume, message, or continue it (SendMessage in Claude Code, or the equivalent elsewhere): a follow-up question, a re-run of the cold implementer check, and a second look at a finding each go to a new subagent with everything it needs in its prompt. A subagent left idle loses its prompt cache within minutes, so the next message re-reads its whole history at full price — often hundreds of thousands of tokens — and a reviewer that has already seen the earlier draft is no longer zero-context.
8. An unknown a check can settle is settled now, or you ask to settle it now. When you find an unknown whose answer would change the plan, run the check at once or ask the user for permission to run it, at that moment, not when the plan is presented. Never mention that something "could be tested" and move on. Which checks run unasked is decided by what they touch, never by their size (verification.md). Run without asking: reads inside the working directory (never a secret), installed dependency source, public docs, and read-only commands. Run with a one-line note: a throwaway probe in the scratch directory with no network and no installs, and existing tests you confirmed touch only this machine or a disposable local stack. Ask first: any network call past the machine, a browser MCP or any tool that drives the user's apps, a shared database or service, anything outside the working or scratch directory, installs, credentials, money, long runs, and prototypes bigger than a probe. When in doubt, ask. A request names each check, exactly what it reaches, where that target came from, and why the plan needs the answer.
9. Long commands keep a heartbeat no more than three minutes apart. A subagent's prompt cache expires about five minutes after its last model request, and while it waits on a command it makes no requests, so a silent wait past five minutes re-reads its whole history at full price. Any command that may run past three minutes (a full test suite, a build, an E2E run, a container start) starts in the background with its output and exit code going to a log, for example ( <command>; echo "EXIT=$?" ) > <log> 2>&1 &. The subagent checks it with a foreground loop capped at three minutes, for i in $(seq 18); do grep -q '^EXIT=' <log> && break; sleep 10; done; tail -n 3 <log>, and repeats until the log shows EXIT=. A bare sleep may be refused by the tool; the loop is not. It never waits on a monitor or notification with no cap, and never ends its run while the command is still going. If the expected wait is longer than about 40 minutes, it skips the checks: one cold restart is cheaper. Do not act on a subagent until its final report arrives; a notice that it is still waiting on its own work is not a result.