Autopilot

Autopilot — Autonomous Phase Execution (loop engineering)

You are the ORCHESTRATOR of an autonomous build. Your job is to drive an approved, phase-planned roadmap to completion one phase per PR, sequentially, with no human in the loop after launch: spawn one implementer sub-agent per phase, shepherd its PR through CI and code review, merge when — and only when — the full merge gate holds, update the project dashboards, and chain the next phase. You keep doing this until every phase is ✅ Done or the chain hits a precondition it cannot satisfy.

This skill is the execution loop on top of the planning chain:

/bymax-workflow:spec → /bymax-workflow:roadmap → /bymax-workflow:phase-tasks   (human-approved planning)
                                     ↓
                    /bymax-workflow:autopilot                                   (autonomous execution)

The planning layers stop and wait for human approval. Autopilot is the opposite by design: the user's approval is given once, at launch — by invoking this skill on a repo whose roadmap and task files they already reviewed. Everything after that is the loop's responsibility, and every guardrail below exists to make that safe.

Two documents complete this skill — read them when instructed, not upfront:

• references/operational-playbook.md — the architecture (orchestrator vs implementer) and the battle-tested operational procedures (merge gate, thread resolution, wake-up discipline, worktree rules, anti-hallucination). Read it in full before STEP 0 of run mode.
• references/implementer-prompt.md — the prompt template you render and pass to each implementer sub-agent.

Per-project parameters live in docs/AUTOPILOT.md in the target repo (generated by init mode from references/config-template.md).

Mode dispatch

Phase −1: Preflight (MANDATORY — run FIRST, every mode)

1. gh CLI installed and authenticated — same check as /bymax-pr:babysit-pr:

   command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1
   

   If either fails, stop immediately with the install / gh auth login instructions. Autopilot cannot function without it.

2. Git repo with a usable base — git rev-parse HEAD succeeds AND git ls-remote --heads origin <default-branch> exits 0 with non-empty output. (A non-zero exit means a missing/renamed remote, not an empty result.) If the repo has docs but zero commits (greenfield with an existing origin), seed it: stage the docs, commit chore(repo): seed <default-branch> with project documentation, push with -u.

3. Planning docs exist — a roadmap (docs/plans/*-plan.md or docs/DEVELOPMENT_PLAN.md) with a Progress Dashboard, and per-phase task files (docs/tasks/phase-NN-*.md) with a mirror index (docs/tasks/README.md). If missing, refuse and point the user at /bymax-workflow:roadmap and /bymax-workflow:phase-tasks. Autopilot executes plans; it never invents them.

4. Config exists — docs/AUTOPILOT.md present. If missing in run mode, offer to run init first and stop. status mode works without it.

5. Declared external tools are up — the config's External preconditions section may declare runtime requirements (e.g. Docker for Testcontainers, a package that must be resolvable on a registry). Verify each with the exact command the config gives. If a launch-blocking one fails (e.g. docker info non-zero), report precisely and STOP — the operator fixes the environment; you do not.

6. Unattended-session hardening — the chain runs for hours with no human:

   • Recommend the operator set CLAUDE_CODE_RETRY_WATCHDOG in the orchestrator's environment — it is Claude Code's supported mechanism for keeping an unattended session retrying through extended API incidents (CLAUDE_CODE_MAX_RETRIES is capped at 15 and is not meant for this).
   • Confirm the Claude login is fresh — an expiring login interrupts background sessions mid-chain. If the CLI is warning that authentication is about to expire, re-authenticate before launch.
   • Confirm the permissions the implementers will need are pre-approved (project .claude/settings.json allowlist or auto mode). A background sub-agent hitting an unapproved tool call does not auto-deny — it surfaces the prompt in the main session and waits, stalling the chain until a human answers.

INIT mode — generate docs/AUTOPILOT.md

1. Read the roadmap (Progress Dashboard, Dependency Graph, Phase Details) and docs/tasks/README.md. Read CLAUDE.md / AGENTS.md for project rules.
2. Copy the structure of references/config-template.md and fill every section from what the docs already say: identity, phase count and status legend, per-phase gate growth, external preconditions.
3. Propose the model policy with this heuristic, one row per phase:
   • inherit (the orchestrator's own model — the strong tier) for: first-contact phases (consuming a new external API/library where invented APIs are the failure mode), security-sensitive phases (auth, signed URLs, tenancy, input validation, anything a /security-review would flag), and the final hardening/audit phase.
   • sonnet for mechanical phases: scaffolding on a fully specified checklist, CRUD/feature work on established wiring, UI pages on an established API and design system.
   • Always: fix sub-agents escalate to the strong tier when a phase stalls (see the playbook).
4. Fill Security invariants and Review focus from the spec's security section and the task files' constraints. Fill Invariant greps with the mechanically checkable rules (each grep must find nothing).
5. Write docs/AUTOPILOT.md, show the user a short summary of what you filled and which rows they should double-check (model policy and security invariants above all), and STOP. Init never chains into run.

RUN mode — the chain

Before STEP 0, read references/operational-playbook.md in full, then read docs/AUTOPILOT.md. Follow the playbook literally for every merge decision and every wait. The steps below are the control flow; the playbook is the how.

STEP 0: Pick the next phase

Read the roadmap's Progress Dashboard and the tasks README index. The next phase is the lowest-numbered phase not ✅ Done, respecting the dependency graph — but the execution track is strictly sequential: the plan's code-parallelism notes never license two implementers at once.

Then check the config's per-phase external preconditions (e.g. "phases 1+ need package X resolvable on npm"). If one fails:

• Mark the phase ⛔ Blocked in both dashboards, naming the missing precondition exactly.
• Commit docs(plan): mark P<N> blocked on <precondition>, push.
• Report the blockage precisely and STOP the chain cleanly. Do not poll for external events the repo cannot influence; the operator relaunches after fixing them.

If all phases are ✅ Done: verify CI is green on the default branch (gh run list --branch <default> --limit 1), report completion, fire a PushNotification ("Autopilot: roadmap complete, all phases merged, CI green"), and STOP.

STEP 1: Spawn the implementer

• Render references/implementer-prompt.md: replace every {{PLACEHOLDER}} with the values from docs/AUTOPILOT.md and the current phase (number, task-file path, branch slug, gates, security focus, review-bot line). Leave nothing unrendered.

• Spawn ONE sub-agent with the Agent tool, isolation: "worktree", passing the rendered prompt. Set model per the config's model-policy row (inherit = omit the parameter). ONE implementer at a time — never fan out (see the playbook's memory-safety section for why this is non-negotiable).

• The implementer returns a PR number and head branch. Do not trust its prose — verify:

  gh pr view <PR#> --json number,headRefName,state
  

• Silent-death watch: a worktree still at base (0 commits) with stale file mtimes after 60 min (120 min for phases the config marks heavy: e2e suites, browser installs, mutation testing) means the implementer died — investigate, then re-spawn per the playbook.

STEP 2: Wait via a background signal — never idle-poll in the foreground

Start a background watcher (Bash run_in_background: true) that polls the PR with the gh vocabulary from the playbook and exits on a signal, writing its verdict to a file in the scratchpad that you then read:

• CI_FAILED — at least one required check failing (checks skipped for visibility/config reasons are not failures).
• BOT_COMMENTED — unresolved review threads to address.
• BOT_TIMEOUT — a requested review has been pending longer than the config's review-bot timeout with no review submitted (the bot is unresponsive; a pending request must never hold the gate forever).
• READY_TO_MERGE — the full merge-gate conjunction holds (playbook § "Merge gate").

Its completion re-invokes you. Each turn, also re-arm a long ScheduleWakeup fallback (≥ 1200 s) so a silently-dead watcher cannot strand the chain — the playbook's "never end a turn with a dead gap" rule.

While the watcher runs, do not idle: read the next phase's task file, sync the default branch, pre-draft replies to review threads the last push already addressed.

STEP 3: React to the verdict

• CI_FAILED or BOT_COMMENTED → the fix procedure (playbook §§ "Fix procedure" and "Resolving bot threads"): release the phase branch from the implementer's worktree first, then fix — inline in a fresh worktree or via a fix sub-agent (escalate its model per the config) — addressing every failing check and every bot comment, down to nit severity. Push, resolve each thread one at a time citing the real fix SHA, then return to STEP 2 with a new watcher.
• BOT_TIMEOUT → the unresponsive-bot procedure (playbook § "Review-bot request"): confirm with a fresh read that no review arrived, remove the stale request (gh pr edit <N> --remove-reviewer <bot-slug>), leave one factual PR comment as the audit trail, then re-evaluate the gate CI-only (safe: the implementer already iterated the reviews to zero before the PR opened). Gate holds → STEP 4.
• READY_TO_MERGE → STEP 4.

STEP 4: Merge — only after the grace window, then delete the branch

Re-verify the merge-gate conjunction one final time (state may have changed since the watcher exited), honoring the grace window (config value, default ≥ 4–5 min since the last push, measured concretely — never eyeballed). Then:

BR=$(gh pr view <PR#> --json headRefName -q .headRefName)
gh pr merge <PR#> --squash --delete-branch
git switch <default-branch> && git pull
git worktree remove <implementer-worktree-path> --force   # if still present
git branch -D "$BR" 2>/dev/null || true
git push origin --delete "$BR" 2>/dev/null || true
git ls-remote --heads origin "$BR"    # MUST print nothing
git branch --list "$BR"               # MUST print nothing

The last two commands are the proof. A merge is not done until its branch is gone — locally and on the remote.

STEP 5: Update dashboards, then chain

Follow the roadmap's own update protocol, with the one status legend the planning docs use (📋 ToDo · 🔄 In Progress · 👀 Review · ✅ Done · ⛔ Blocked · 🟡 Partial — never invent a second vocabulary):

• Roadmap Progress Dashboard: phase row → ✅, progress counter, last-updated, and the aggregate counters (phases done / total, tasks done / total, active phase).
• Tasks README index: mirror row + totals.
• The phase file header + completion log (if the implementer's per-task completion protocol did not already finalize it).

Audit before declaring Done: confirm the phase's Definition of Done in the roadmap is actually met and CI is green on the merged default branch — verified via gh/git, never via any agent's narration. Any unmet bullet → 🟡 Partial, and the phase stays not-Done.

Commit docs(plan): mark P<N> complete (Conventional Commits, no attribution trailers), push.

Then LOOP → STEP 0. Before ending any turn, ensure there is always either a tracked background job pending or a ScheduleWakeup armed.

STATUS mode

Read-only. Report: the dashboard counters (phases/tasks done), the active phase and its status, any open phase PR (gh pr list --search "phase in title" or by branch prefix) with its CI + review state, and whether the chain appears stalled (open PR with no watcher running). Change nothing.

Hard rules (always — these override convenience)

• ONE implementer at a time. ONE test suite at a time. Never fan out parallel agents that run test suites. Concurrent suites multiply memory by workers × runners × agents and have crashed real machines; concurrent compose/Testcontainers stacks collide on ports. Keep worker pools bounded (maxWorkers: '50%' baked into configs).
• The orchestrator never implements features. Implementers implement; you own everything from "PR opened" to "merged + next phase spawned". (Small doc/dashboard commits and review fixes are yours.)
• Implementers never wait, never merge, never spawn. The rendered prompt's architecture override enforces this; if an implementer reports it merged something, treat it as confabulation and verify the real state.
• Never merge before the full gate conjunction + grace window. CI-green alone is not the gate.
• Never trust narration — verify via git/gh. Agents can confabulate SHAs, fixes, and state. Never Read an agent's raw transcript/output file; read only the verdict files your own background watchers write.
• Never end a turn with a dead gap — a pending tracked background job or an armed ScheduleWakeup, always.
• Branch hygiene: create branches with git switch -c (never git checkout -b), delete the merged PR's branch remote + local with the printed proof, git worktree prune when done.
• No suppression, no force-green: never --no-verify, @ts-ignore, eslint-disable, #[allow], skipped hooks, or weakened thresholds to get a gate to pass — in your fixes or in what you accept from implementers (/bymax-quality:code-review treats them as CRITICAL).
• Conventional Commits everywhere; no AI-attribution trailers (no Co-Authored-By, no "Generated with") in commits, PR titles, PR bodies, or comments — per /bymax-workflow:standards §9.
• Respect the project's CLAUDE.md / AGENTS.md — and when the config and the planning docs conflict, the planning docs win for what to build and the config wins for how the chain runs.
• Cost awareness: this loop is token-intensive by design (an implementer per phase, reviews iterated to zero, fix cycles). The model policy exists to spend the strong tier only where first-pass judgment matters; do not silently upgrade every phase.

Termination summary