do-epic

Work on GitHub Epic (Autonomous, DAG-scheduled)

Work on epic issue $ARGUMENTS end-to-end. Builds a dependency DAG from the epic's child stories, schedules them into waves, runs each wave in parallel via per-story worktrees, and drives every story through agent code review with binary PASS/FAIL verdicts.

Preflight (mandatory)

Run this first. If it exits non-zero, halt and report the stderr output to the user verbatim. Do not claim, do not branch, do not start any worktree.

uv run maverick preflight do-epic

The check verifies: the project is initialised, the Maverick GitHub App is configured (maverick gh-app status reports configured: true), git worktrees are usable, and required tools (gh, git, uv) are on PATH. PR code review runs locally inside each story's worktree as the agent-code-reviewer subagent (delegated from do-issue-solo Phase 9). For epics that fan out across many parallel workers, consider opting into the CI-side re-run described in mav-bp-remote-code-review so the merge is gated by an independent check even if a worker's local review fails to fire — that workflow is optional and not enforced by preflight.

Before You Begin

$ARGUMENTS must be the GitHub issue number of a Maverick epic — an issue whose body contains a task table of child stories. If it is a single story, dispatch do-issue-solo instead.

Phase 0: Coordination

1. Resolve repo: gh repo view --json nameWithOwner.
2. Cold-start hydrate per mav-durability-on-gh:
   • Read the maverick-dag marker on the epic.
   • Read the maverick-state marker.
   • Read the maverick-bprop marker — if present, resume block propagation first before continuing.
   • Read open PRs for the epic's child-story branches.
3. Decide claim scope:
   • Whole epic if no live claim exists.
   • A specific wave if another instance already holds other stories.
   • Single story if another instance holds the epic but not the story you were asked about.
4. Claim: uv run maverick coord claim <repo> $ARGUMENTS --scope <csv-of-issues>. On ClaimRejected, abort and report per mav-multi-instance-coordination.
5. Start heartbeat daemons for every issue in the claim scope. Each daemon exits on its own when the matching claim is released; check liveness anytime with coord heartbeat-status:

   for issue in <epic> <story1> <story2> …; do
     uv run maverick coord heartbeat-loop <repo> $issue --daemonize
   done
   

   Never background the foreground loop with & — a process backgrounded from a tool shell dies with the shell or leaks unobservably.
6. Release on exit is automatic. The plugin's SessionEnd hook runs coord release-all, releasing every claim this instance recorded — the matching heartbeat-loop processes detect the cleared labels and exit on their own; lease expiry covers machine death. Your only explicit releases are the per-story ones at workflow boundaries (merged / ejected). Do not attempt trap-on-exit wrappers — each Bash call is a fresh shell, so a trap cannot survive to session end.