Team recap · 27 July 2026

Chaining plan authoring into the build skill

A session that began as a question about one skill’s behaviour and ended with a committed, reviewed plan to change it. No product code moved — what shipped is the design.

At a glance

3
Documents shipped
8
Decisions made
12
Steps planned
5
Open items

The work started from a plain question: what does the build skill do when you give it no plan? It stops, and tells you to go run a different command. The session turned that dead end into a designed, reviewed proposal for walking the user through to a finished plan instead.

The finding that shaped everything came early. The pipeline this work needed already existed, wired in the opposite direction. The task was never “build a pipeline” — it was “let one skill enter the pipeline that is already there.” That reframing cut the estimated change from three files to roughly twenty-five lines in one.

Everything is committed as 3c37605. Nothing is implemented: the plan’s status is todo.

What changed

A design proposal recording the decisions

Affects: reviewers Committed

Captures why this work should happen, with each decision dated and each rejected alternative named, so nobody re-argues a settled point. Four appendices ground the claims in real evidence — including a trace of a genuine defect in how these skills inherit their model.

docs/proposals/chain-plan-authoring-into-build.md

A twelve-step implementation plan

Affects: whoever builds this Not implemented

Twelve steps, fourteen acceptance criteria, and a test section that is honest about its own limits. Every step carries why it exists and how to confirm it worked.

/plan-agent:build docs/plans/add-plan-authoring-to-build.md

A reviewed and twice-narrowed scope

Affects: nobody yet Applied to the plan

A five-reviewer panel produced three high-severity findings, each verified against the source files before being accepted rather than taken on trust. Two later rounds narrowed the design further: first repairing a flaw that a concrete usage scenario exposed, then scoping the whole feature to the explicit command.

Review Record — inside the plan document

How it works now

printed prompt, user pastes

direct call

direct call

back to menu

PROPOSED new entry

build-proposal

implementation-plan

review-plan

build (writes the code)

The whole proposal is the dashed arrow from build back up to build-proposal. Every other connection already exists today — which is why the change is small.

yes, and it exists

yes, but missing

no

yes

no

yes

no

not yet

yes

/plan-agent:build a todo app

Was a plan file named?

Implement it

STOP - name the paths tried

Was a goal given?

Skip the search entirely

Offer up to 3 found plans, plus write a new one

Start from a proposal?

Write a proposal

Write the plan

Ready to build?

STOP - plan saved, nothing built

Look at the two STOP boxes — both are deliberate. A mistyped filename must never trigger writing a whole new plan, and choosing “not yet” must never build anyway.

Before and after

SituationTodayAfter this plan
No plan named, none foundStops, tells you to run another commandWalks you through proposal, plan, review
No plan named, one foundSilently uses itOffers it, plus “write a new one”
No plan named, many foundAsks which oneOffers 3 at most, says how many were hidden
A goal was givenNot possible — no way to pass oneSearch skipped; your goal wins
Mistyped filenameStops, names the paths triedUnchanged, deliberately
“build a todo app” as plain textNeeds an existing plan; routes awayUnchanged, deliberately
Which model writes the codeWhatever the session was usingPinned, so it stops inheriting the reviewer’s
Version bump for the release—Major, not minor

Decisions

Reuse the pipeline that already exists, rather than rebuilding it inside build.

The handoffs between the three skills are already wired. Re-implementing them would mean a new flag on a neighbouring skill plus a guard against infinite loops, spread across three files.

Rejectedbuild sequencing the stages itself (touches three files, duplicates existing logic); a fourth skill owning the pipeline (cleanest boundaries, but a whole new skill to avoid ~25 lines).
Ask once whether to start from a proposal.

The proposal skill handles a small, well-understood idea by just answering it — producing no document. Running it unconditionally would leave the chain holding nothing.

RejectedAlways running it and letting it scale itself down; skipping the proposal stage entirely.
Offer what the search found instead of silently adopting it.

Otherwise a forgotten plan sitting in the directory can quietly win over the goal the user just typed.

RejectedSkipping the search entirely (loses the ability to resume interrupted work); only chaining when the directory is completely empty (leaves the silent pickup in place).
“Not yet” ends the whole run, not just one step of it.

That prompt is the only place the user is asked whether to build. Treating it as declining just the inner step would build the thing they declined seconds earlier.

RejectedThe narrow reading, which the proposal originally documented; asking a second time on the way back.
Pin an explicit model on the skill that writes code.

Kept even after a reviewer argued against it, because the alternative is inheriting whatever the previous stage happened to set.

RejectedReverting to inherited; documenting the defect instead of fixing it. The reviewer’s cost and access objections are recorded as a known tradeoff rather than acted on.
Write the new tests scoped to the section they guard.

The existing test file documents, in its own comments, a whole-file search passing against a change that deleted all five rules it was supposed to protect.

RejectedWhole-file searches (demonstrably weaker); a structural parser heavier than anything else in the test suite.
Release this as a major version, not a minor one.

The repository’s own rule classifies changes to how a command accepts input as major. The automated check only enforces “newer than the main branch,” so it would never have caught the undersized bump.

RejectedMinor, as originally written into the plan.
Reach the new behaviour only through the explicit command.

The goal becomes a parameter you pass, not a phrase that triggers the skill. This removes an entire class of false matches instead of trying to word around it.

RejectedA narrow automatic trigger for phrasing that sounds like creating something; a wide trigger that asks a clarifying question at runtime.

Learnings

Open items

Resolved during review. One appendix of the proposal described the old “not yet” behaviour that step 7 of the plan overrides. Automated review pushed on it, so the appendix now documents path-based resolution plus an explicit rule covering both “not yet” and “run as a workflow”, and names the reading it replaces.

Files touched

Proposals
  • docs/proposals/chain-plan-authoring-into-build.md
    New. The decision record with four appendices; revised once when the trigger condition was corrected.
Plans
  • docs/plans/add-plan-authoring-to-build.md
    New. The twelve-step specification and the authoritative source. Renamed mid-session when a filename check rejected the first name.
  • docs/plans/add-plan-authoring-to-build.html
    New. Generated from the file above; never edited by hand.

Glossary

Skill
An instruction file the coding assistant loads on demand — either when you type its command, or when what you asked for matches its description.
Automatic activation
A skill loading because your wording matched it, rather than because you typed its command by name.
Command
Invoking a skill explicitly by name, with arguments you pass to it.
Source and render
The text file is authoritative; the web page beside it is generated from that file and safe to overwrite.
Plan status
One of todo, in-progress, or completed, recorded at the top of the plan.
Acceptance criterion
A short statement that is plainly true or false, describing the result rather than the work.
Objective test
The one test that checks the stated goal was actually achieved, as opposed to testing the pieces.
Major / minor version
Release numbering. Major warns everyone already using the tool that something they rely on has changed.
Re-entrancy
Something being started again while an earlier run of it is still in progress — here, a skill calling a chain that calls back into itself.
Worktree
A second working copy of a repository, checked out to a different branch in its own folder.