epic-autopilot
Outer loop driving an epic to full completion. Composes, does not replace, the inner
skills: fork adjudication (grill-yourself/mantras vs the repo's principles doc),
handoff regeneration.
Project parameters come from the repo's CLAUDE.md (## Epic-autopilot parameters
block): issue tracker commands, worktree root, quality gates, never-do list,
principles doc path, handoff path convention, stop-vs-self-compact protocol.
Do not hardcode any of these here.
Mental model
User kicks off ONCE. After that the loop continues only because of:
- Per-iteration discipline — each issue finished fully to pushed-on-main; repo never
left half-done when context dies.
- Rolling handoff — ONE durable file (path per CLAUDE.md) always holding: main tip,
shipped log, the SINGLE next issue + contract + carried gotchas.
- Forward command — literal re-entry command written by you, executed by fresh-you:
minimal + pointer-based (issue id, one-line scope, handoff path, relevant memories).
Fat command duplicating the handoff = drift.
Over-document the NEXT step, not history.
Iteration (top to bottom, every issue)
- Orient.
git fetch origin. Read handoff. Inspect epic in tracker (show epic,
list ready/unblocked). Pick next unblocked child — dependency-respecting, ONE only.
Assume other agents moved main since the handoff was written — re-verify, don't trust.
- Isolate + claim. Worktree off FRESH origin/ at the repo's worktree root,
branch = issue id. Claim in tracker. Reproduce per-worktree setup CLAUDE.md lists.
- Build. Scope against real contracts in source, not handoff summaries
(verify-don't-trust). Every technical fork → adjudicate against the principles doc;
decide autonomously; escalate only product/business calls or principle conflicts.
TDD where repo does.
- Gate. Run the repo's real quality gates; read output honestly. Know the
pre-existing red baseline (CLAUDE.md slot) — don't chase ghosts, never mask failure.
Unrelated bug found → file issue IMMEDIATELY with clean-base proof; fix inline only
if hard dependency AND tiny.
- Land (concurrency-safe). Other agents move main. NEVER merge via the main tree
or touch another agent's worktree. Use the detached-temp-worktree merge recipe from
CLAUDE.md: merge origin/ into branch until ancestor-clean → detached temp
worktree at origin/ → merge --no-ff branch → push origin HEAD: →
rejected = refetch + retry → remove temp worktree. Stage explicit paths only.
- Record. Close issue in tracker; commit/push tracker export if file-based.
Durable facts → handoff (agent-local memory does not travel). Remove issue
worktree + branch.
- Refresh handoff. New main tip, one "shipped" line (id, one-liner, merge commit),
rewrite NEXT to exactly the next issue: contract, gotchas, verify-don't-trust
caveats, forward command. Written for a context-free agent: lead with the command,
reference (don't duplicate) design docs/commits.
- Continue per protocol (CLAUDE.md slot — pick one):
- stop-after-each-bead: refresh handoff, STOP, wait for user to compact +
re-issue the forward command.
- self-compact at ~N tokens: under threshold → loop to step 1; at threshold →
finalize handoff, self-compact passing forward command as the compact argument.
Forward command shape
continue with (, <surface/route>) — see ;
use <skills/memories>
Stop condition
Every child closed → final handoff marked complete (no NEXT), report to user.
Never silently chain into another epic.
Break the loop and ask when
- Fork is genuine product/business call, or principles irreconcilably conflict. Bundle escalations.
- Gate failure implies the issue's PREMISE is wrong (contract mismatch, missing
backend) → file blocker issue, surface, don't fake-pass.
- All remaining children blocked → report, don't spin.