Implement plan

Implement Plan

Execute a whole plan without a human turn between phases. Work is durable only once committed and ticked — that is the unit of progress. Everything else happens between checkpoints.

Workflow

1. Resume before you start — every invocation, including the first.

   • Run the pickup sequence in recovery.md: worktree list, state scan, ## Run state, commit log, reconcile.
   • Finish or abort any half-open rebase/merge in its owning worktree first.
   • Redoing finished work is the most expensive failure available.

2. Read the plan; pin the base.

   • Collect every phase with unmet - [ ] (plan anatomy: create-plan).
   • Detect the base branch with git symbolic-ref --short refs/remotes/origin/HEAD.
   • Fall back to git ls-remote --symref origin HEAD.
   • If neither resolves, ask — do not assume main.
   • Then pin it: BASE=$(git rev-parse refs/heads/<base>).
   • Every dry run, rebase and merge targets $BASE, never a moving branch name.

3. Review every unmet phase in one pass — ambiguous criteria, missing context files, conflicting instructions, criteria no command can verify.

4. Choose the shape — execution mode and the concurrency test, both in orchestration.md. Sequential is the default.

   • Then set each phase's review tier per verification-depth.md.

5. Present the run contract and get one go-ahead. Contract:

   • plan path, base branch and pinned sha
   • the phase list with its grouping and each phase's review tier
   • worktree paths and branch names
   • the verification command, the stop conditions
   • every question from step 3
   • every shell command the agents need that is not already allowlisted — an unattended run stalls on a permission prompt

   The run's only planned human turn. It is using-git-worktrees step 3's confirm-before-creating, asked once instead of once per worktree.

6. Create the run worktree .worktrees/plan-<slug> on branch plan/<slug> from $BASE, per using-git-worktrees.

   • Confirm a clean baseline there before the first edit: the verify command passes on unchanged code.
   • Later failures are then attributable.

7. Execute each unit in order.

   • Sequential phases run in the run worktree.
   • A concurrency-eligible group gets one worktree, one branch and one agent per phase.
   • Dispatch per orchestration.md and the delegation contract.
   • No two agents ever write one file; no agent ever writes the plan file.

8. Commit per acceptance criterion that names its own change, then tick.

   • A criterion asserting only the gate, or restating a sibling's verification, rides along with the change it describes. Never mint an empty commit for it.
   • Implement one criterion at a time, so its commit is whatever the tree already holds.
   • Never write a phase broadly and then partition it into criteria.
   • That bisecting is the only thing that makes a commit expensive. The commit itself is a second.
   • The phase's own worker runs the verification command: make test or make check if the repo has a Makefile.
   • Otherwise the language-appropriate default: go test ./..., pnpm test, mvn test.
   • Per criterion the worker runs only the targeted tests for what it changed.
   • The full gate runs once per phase, before the phase reports.
   • Scope even that gate to the languages the phase touched.
   • A Python-only phase paying for a frontend build is waste times the criterion count.
   • A whole gate multiplied by the criterion count is a phase's largest avoidable cost.
   • The lead reads that exit code. It re-runs the gate only after a fold, a rebase, or an edit the gate has not seen.
   • Commit the change with the run trailer (Constraints).
   • Tick the phase's criteria in one commit when the phase closes, not one commit per box.
   • The plan file is lead-owned, which is why the tick is a commit of its own — bookkeeping, not granularity.
   • Tick only what a tool result from this session proves.
   • If verification fails twice on one phase for the same reason, switch to systematic-debugging.
   • If that does not resolve it, stop.

9. Fold each parallel group into plan/<slug> in ascending phase order.

   • Use the fold sequence in integration.md.
   • Transcribe that phase's ticks as you go.
   • Re-run verification after each fold — passing in isolation does not mean passing together.

10. Land plan/<slug> on the base branch with the landing sequence in integration.md, then re-verify in the main checkout.

    • Delete the ## Run state block and commit that removal before landing.
    • The base branch never receives it.
    • Every acceptance criterion in the plan ticked: git rm the plan file in the main checkout after landing.
    • Commit that removal on the base branch as its own commit.
    • Any unticked criterion keeps the file.
    • Step 11 then reports the plan file as surviving.
    • Then git worktree remove each worktree the run created.
    • And git branch -d each merged branch.
    • Push, PR or discard is finish-branch's decision, not yours.

11. Report. Counts line first, then one bullet per field:

    • 3 phases — 2 complete, 1 blocked; 9 criteria ticked; 11 commits landed
    • Phases — completed, with criteria ticked and commits landed.
    • Dropped — agents that returned nothing, and what happened to their work.
    • Unticked — anything left unticked, with the reason.
    • Plan file — deleted, or surviving with the unticked criteria that kept it.
    • Nothing dropped and nothing unticked: say so in one line, no padding.

Stop and ask

Two different things live here, and conflating them is what turns a run into a stall.

• A forced stop ends the run and hands back. There is no question to answer.
• A judgment call runs the ask gate first. Most resolve to a single option and never reach the user.

Forced stops

• Any merge or rebase conflict.
  • Abort in the owning worktree, report the paths and their classes, hand back.
  • Nothing is auto-resolved by content — see integration.md.
• Verification fails repeatedly for the same reason after a debugging pass.
• Proceeding would need anything on the hazard list, a push, a force-push, or --no-verify.
• Proceeding would delete a branch, worktree or file the run did not create.
• A worktree, branch, index.lock or refs/agent-lock/* the run does not own is dirty, held, or mid-operation and blocks the path.
  • Report it; never clear another worktree's state.
• A usage limit or a terminal API error.
  • Write and commit the ## Run state block.
  • Then report the verbatim failure string and any reset time it printed.
  • Taxonomy in recovery.md.

Judgment calls

• A phase's criterion is ambiguous, unverifiable, or names something that does not exist.
  • Read the plan's ### Context, the repo and its conventions first.
  • One reading survives: implement it and say which reading you took in the commit body. Two survive with no clear winner: stop and ask.
• The plan would have to change.
  • A different design, or a new phase, is create-plan's job — stop.
  • A criterion whose wording is wrong but whose intent is unambiguous is not a plan change. Implement the intent; note the wording in the report.
• A phase needs a shell command the allowlist does not cover.
  • Reach the goal with an allowlisted command where one exists.
  • None exists: stop, and name the exact command in the handoff.

Constraints

• Commit message: Conventional Commit subject plus one trailer, Plan: <slug> phase <N> criterion <M>.
  • That trailer makes a dead agent's work findable after its branch is gone.
  • No AI attribution trailers.
• The run owns the turn. Between phases, folds and landings there is no human turn — see the opening line.
  • A phase report goes in the same turn as the next phase's first action.
  • Waiting on a dispatched agent or workflow is waiting inside the turn.
  • scripts/plan-run-guard.sh blocks a stop while plan/<slug> still has an unticked criterion, so a yielded turn costs a round trip.
• One writer per file, always. The lead is the sole writer of the plan file for the whole run; subagents receive its path to read.
  • Index files, lockfiles and entry points are lead-owned, as in distill/parallelism.md.
• Never git stash — it is repo-global, not per-worktree, so two agents pop each other's work. Commit instead.
• Never run any of these:
  • git gc --prune=now
  • git update-ref on a branch
  • git rebase --update-refs
  • git checkout -- .
  • git restore .
  • git clean -fd
  • git reset --hard
  • git branch -D
  • git worktree remove --force
• What each destroys and its safe substitute are in integration.md.
• Never push the base branch, never force-push, never --no-verify.
• Set model explicitly on every delegated agent; routing in distill/parallelism.md.
• Prefer simple, clear, idiomatic solutions.
  • No performance optimisation at the cost of readability.
  • Small local duplication is fine when it aids understanding.
• If the user wants to write the code themselves, that is guided-implementation.

Quality

• After each phase lands on plan/<slug>, run the shared self-review checklist on that phase's diff.
• Review beyond that checklist is bought at the phase's tier — verification-depth.md.
• Defects a review returns go back to that phase's own worker, by SendMessage.
  • A fresh fixer re-reads what that worker already holds; never dispatch one.
  • Rule and mechanics: dispatching-parallel-agents.
• Carry the defect classes into the next phase's worker prompt.
  • Unnamed, the same class recurs in every later phase and is bought twice each time.
• Surface issues in the chat only if found.
• The final report follows the output style contract.