Autopilot

You are the orchestrator. You run on Opus, in the main thread. Workers run on Sonnet, reviewers on Haiku.

Structural constraint: subagents cannot spawn subagents. Workers therefore do not review their own work and do not open PRs. Review and shipping happen here.

You never merge. Autopilot ends with green PRs awaiting human review.

Phase 1 - Triage

gh issue list --limit 60

Read the candidates. Rank by implementation complexity, not by label. Write the ranked queue to <repo root>/.claude/temp/autopilot-queue.md - that directory is tracked and always exists, so write to it directly rather than creating it (a relative mkdir from the nested project root would make a second, wrong .claude/):

| # | Issue | Title | Complexity | Files | Backwards-compat risk |

Defer, with a stated reason, anything that:

• needs a product or design decision the issue does not settle
• cannot preserve backwards compatibility
• depends on an open PR landing first
• is a research question rather than a change

Good autopilot candidates: a reproducible bug with a clear expected behaviour, a missing test, a documented helper that does not exist yet, a mechanical refactor with tests already covering it. Bad candidates: anything whose first step is "decide how X should work".

Phase 2 - Plan

For the top 3, write a concrete plan each:

• the success criterion - what is observably true when done
• the failing test to write first, named, and where it goes
• files to touch
• backwards-compatibility risk, explicitly
• anything the worker should stop and ask about

A worker with a vague plan produces vague work. Be specific enough that it never has to guess.

Phase 3 - Dispatch

Workers run in parallel, so each needs its own checkout - three agents cannot share one working tree. Create a worktree per issue, in a directory outside the repository so the build trees and scratch files never collide with it:

git worktree add <worktrees-dir>/<short-name> -b <type>/<slug> <base>

Use the worktree root the user names. If none was given, default to a sibling of the repository (e.g. ../<repo-name>-worktrees/) and say which you chose. <base> defaults to origin/main unless told otherwise - record whichever value you used, since Phase 5 needs the same one for gh pr create --base. Record the mapping of issue to worktree so you can find each one again in Phase 4.

Spawn 3 Sonnet agents in parallel, one issue each. Give each: the issue body, its plan, its worktree path, and its branch name (already created - the worker works in place).

Instruct each worker to follow work-an-issue steps 1 and 3-6 only - understand, failing test, instrument, implement, build and test. Skip step 2; its branch already exists. Then report back with:

• the full diff
• test results with counts
• anything it had to assume

Tell it explicitly: do not review, do not touch docs, do not commit, do not push, do not open a PR. Those are the orchestrator's.

Builds run at --parallel 4 (the build-and-test skill enforces this). Three unbounded C++ builds on one machine would thrash every core.

Phase 4 - Review

For each worker that reported back:

1. Dispatch a Haiku agent pointed at the worker's worktree, running project-code-review. Give it the worktree path, not just diff text - project-code-review requires searching tools/ for helper reuse and checking tests/CMakeLists.txt for registration, neither possible from a diff alone.
2. Dispatch a Haiku to run docs-check the same way, in the same worktree.

If either turns up findings, send them to the owning worker via SendMessage rather than spawning a new agent - the worker still holds all the context about why it wrote what it wrote, so a fresh agent would just re-derive it at full cost.

Loop until the diff is clean. If a worker cannot resolve a finding after two rounds, stop on that issue and record it for the report rather than burning turns.

Phase 4b - Performance check (serialized)

Only for worktrees whose diff touches the simulation hot path (src/elements/, src/simulation/, src/tools/, include/tools/math.h, include/tools/fft_convolution.h, include/tools/simd_dispatch.h). Skip the rest and say so.

Run these one at a time, with every other worker idle. Three parallel workers make wall-clock measurement worthless - this is the one phase that cannot be parallelised, and running it concurrently produces confident nonsense rather than an error.

For each qualifying worktree, use the perf-regression-test skill. Because the machine is running agents, treat the result as advisory: note any delta over 5% in the PR body, and stop on the issue only past 15% - a delta that large is a real regression regardless of the noise.

An inconclusive result goes in the PR body as unverified. Do not re-run in a loop chasing a clean number.

Phase 5 - Ship

Once a diff is clean, from the worker's worktree:

git add -A && git commit -m "<type>: <lowercase summary>"
git push -u origin <branch>
gh pr create --base <base> --title "<type>: <summary>" --body "<what / why / how to verify>

Closes #<N>"

gh pr create --base takes a branch name, not a ref - main, not origin/main. Use whichever branch Phase 3's <base> pointed at.

Phase 6 - Monitor

Poll each open PR:

gh pr checks <N>
gh pr view <N> --comments

Expect these jobs: build-and-test-linux (plus coverage, headless example smoke-run and a single-process order-dependence check), sanitizers-linux (asan-ubsan and tsan), build-and-test-windows, macOS, and clang-tidy from Static Analysis. This is not fast - check roughly every 5-8 minutes rather than tight-looping.

Address failures and CodeRabbit comments by messaging the owning worker. A CI failure that reproduces locally is a real bug in the change; one that does not is worth reporting rather than patching blind.

If CodeRabbit hits its rate limit, note it in the report and move on - do not block.

Stop when checks are green and review comments are resolved. Do not merge.

Phase 7 - Report

• PRs opened, with URLs and one line each on what they do
• for each PR: perf verdict from Phase 4b - checked / skipped (with the reason) / inconclusive / regression (with the delta)
• issues deferred, each with the reason
• anything that needs a human decision
• anything left mid-flight, and its exact state

Report honestly. A PR that is green because a test was weakened is worse than no PR, and saying "3 issues done" when one is half-finished wastes more time than it saves.