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.