[PierreMardon]

/surface-plan wrote plan.md itself, from a template of seven numbered sections. Nothing in the chain read most of that form, and what it held, a good plan, is what the Plan agent built into Claude Code already produces. That agent now drafts the plan, held to the minimum the chain reads.

What was done

• Step 6 goes to the Plan agent. /surface-plan launches it fresh, with a prompt of file paths only: the plan folder and the template. The chain ships no definition for it, so the template is its whole mandate. The agent has no write tool: it returns the plan, the command writes plan.md as returned, then checks the minimum the chain reads and nothing else. A return that is no plan, or one that fails that minimum, gets one more launch, then the command tells the developer and stops.

• The template is the minimum, under three headings without numbers:

  • the acceptance criteria, numbered, which the blueprint carries and the review cites;
  • the slices, each behind its <!-- slice:N --> marker and enough for an agent that starts fresh, a number never reused;
  • the gates block.

  The design and its layout, decisions, tests, risks and assumptions, are the agent's. No code beyond a signature or a schema fragment, in the language exploration.md names.

• A new revision keeps what is built. The agent redrafts from the existing plan, the amendments and accepted plan changes of interview.md, and the journal: a slice a slice-done line records stays under its number, and what is left to build goes into slices that have not run, or into new ones.

• The gates stay the command's. It finds them, writes them in exploration.md as the gates of the plan, and corrects the gates block when the agent wrote others.

• A shorter exploration. Step 4 reads the code as far as the interview needs, so that no question is asked that the code answers. The path through the code, layer by layer, is the agent's.

• A planner role in models of .claude/surface.json, opus by default, passed on the Agent call like the other roles. show --json gains the field, with no new version.

• No prompt names a section of a document by a number: a test holds it for the prompts and the templates.

• ADR 0035 records the decision. ARCHITECTURE.md, the guide and the end to end guide follow, and the toy's plan and exploration take the new form.

Decisions

On the questions #56 left open. The developer chose the model; the others were proposed to them and not objected to.

• What the agent is given: the plan folder and the template, file paths only. With no definition of the chain to carry a mandate, the template is the one place that says what a plan holds and what to return.
• The exploration stays, shorter: every other agent reads exploration.md for the language, the conventions and the gates, and the interview needs enough of the code to ask nothing it answers.
• The model: a role planner in models, rather than the session's, so that the chain pins the models of its agents whatever the session (ADR 0031). With no definition, nothing carries a default nor an effort: launched without the model the agent would run on the session's, and it runs at the session's effort.
• An ADR: the choice was made against two credible alternatives, the command as the writer and an agent of the chain's own, and is one a reader would be tempted to undo by adding a planner definition.

Tests

scripts/gate.sh is green. The contract of the prompts holds the three headings of the template without numbers, the readable markers and gates block, the mandate the template carries, the order of step 6, write as returned then check the minimum, the gates named by the command, the exploration that stops at the interview, the planner role with no definition behind it, and that no prompt names a section by a number.

The end to end tests were run in the container, on real sessions:

• The four automated scenarios pass: the nominal path reaches conformant, a session killed in a slice resumes it, a modified blueprint stops the loop, the ceiling hands back. The executor and the reviewer work from a plan of the new form.
• Planning from the specs, by hand, on the toy. After the interview the command launched Plan on opus with the two paths, wrote its return, and the plan held the three headings, two slices behind their markers and the gate of the toy, around sections of the agent's own: context, decisions, assumptions, risks. The extraction and the cross-check followed, with no omission, then the hand over.
• A reply that agrees, "Looks fine to me, go ahead.": nothing recorded, and the session said that the launch of /surface-execute approves.
• An amendment in the same conversation, "put the year first": revision 2 was drafted by a fresh Plan agent, cross-checked with no omission, and pushed.
• An amendment on the plan the ceiling scenario leaves blocked, both slices done: revision 2 kept slices 1 and 2 under their numbers, said they are done, and added slices 3 and 4 for what was left to build.

All of it cost 3.70 USD at list price.

Risks

• The chain depends on an agent it does not own. A release of Claude Code that renames it, removes it or changes what it returns changes step 6, and a host that denies it stops planning there.
• The agent adds what it is used to: both plans drafted on a revision closed with a section of its own, a list of critical files, after the gates. It is written as returned and nothing reads it.
• The plans are not judged, no more than those the command wrote. The agent added two acceptance criteria the specs and the interview do not state, no regression of the existing command and the standard library only: the blueprint carried them, where the developer reads them.
• A plan costs one more agent launch, and the code the feature touches is read twice.

Closes #56