do-issue-solo

Work on GitHub Issue (Autonomous)

Work on GitHub issue $ARGUMENTS autonomously, coordinating safely with any other Maverick instance that might also hold a claim on this issue. Follow every phase in order. Only pause to ask the user when you are blocked or need clarification.

Preflight (mandatory)

Preflight output, captured when this skill was invoked (dynamic-content pilot — the command ran before you read this):

!uv run maverick preflight do-issue-solo 2>&1 && echo PREFLIGHT_OK

• Ends with PREFLIGHT_OK → prerequisites are met; proceed.

• Shows an error → halt and report the output verbatim to the user. Do not proceed, do not work around missing prerequisites.

• Empty, or shows the literal command text (dynamic skill content is disabled via disableSkillShellExecution) → run it manually first and apply the same rules:

  uv run maverick preflight do-issue-solo
  

The check verifies: the project is initialised, the Maverick GitHub App is configured (maverick gh-app status reports configured: true), and required tools (gh, git, uv) are on PATH.

Before You Begin

If $ARGUMENTS is empty or not a valid issue number, ask the user for the issue number before proceeding.

Determine the repo (via gh repo view --json nameWithOwner) — you will pass it to every maverick coord command below.

PR code review runs locally during Phase 9 as the agent-code-reviewer subagent — its binary PASS/FAIL verdict is the gate. Some projects also opt into a CI-side re-run via mav-bp-remote-code-review (independent verification for multi-machine fleets or audit needs); when present it adds a status check the auto-merge in Phase 10 will wait on, but its absence is not a blocker.

Phase 0: Coordination + cold-start

Before any other phase.

1. Run uv run maverick coord read <repo> $ARGUMENTS and inspect the snapshot. Decide which of the four branches in mav-multi-instance-coordination applies:
   • Blocked (blocked-by:#N label): abort cleanly, report to user.
   • Claimed with live lease: abort cleanly, report holder + expiry.
   • Claimed with stale lease: decide take-over vs defer.
   • Free: proceed to claim.
2. Claim the issue: uv run maverick coord claim <repo> $ARGUMENTS. The command exits non-zero if the claim is rejected — treat that as abort.
3. Start the workflow report (writes a run-start row that later report calls inherit maverick_skill from):

   uv run maverick report run-start do-issue-solo --issue $ARGUMENTS --phase claimed
   

   From here, agent-dispatch intervals are recorded automatically by the plugin's Subagent hooks (open on dispatch, closed on return), and invoking a tracked inner skill auto-opens its skill-dispatch interval. Your only bookkeeping obligation is the one-line report end --auto --outcome <…> after each inner skill returns — everything else is hooks. Anything left open is flushed as outcome=unknown by report generate.
4. Start the heartbeat daemon. It refreshes the lease every HEARTBEAT_INTERVAL_MINUTES minutes for as long as you hold the claim and exits on its own when the claim is released:

   uv run maverick coord heartbeat-loop <repo> $ARGUMENTS --daemonize
   

   Never background the foreground loop with & — a process backgrounded from a tool shell dies with the shell or leaks unobservably. Liveness is checked in the task loop with coord heartbeat-status.
5. Release is handled on every exit path without any action from you: the plugin's SessionEnd hook runs coord release-all when the session ends (normal exit, user interrupt, crash-caught), and lease expiry (10-minute TTL) covers machine death. Your only release obligations are the explicit ones at workflow boundaries: --reason merged after auto-merge lands, --reason ejected on eject. Do not attempt trap-on-exit wrappers — each Bash call is a fresh shell, so a trap cannot survive to session end.
6. Authorization scopes (only when needed): if the issue explicitly authorizes infrastructure changes — the maverick-authorize-infra label or a Maverick-Authorize: infra line in the issue body — record it so the scope-guard hook permits those edits in autonomous mode:

   uv run maverick coord authorize <repo> $ARGUMENTS infra
   

   If the command exits non-zero, the issue does not authorize the scope: do not make infrastructure changes; note the gap in the solution design instead. Never write .maverick/session-auth.json by any other means — the hook blocks it, and self-granting defeats the authorization model.
7. Cold-start hydrate per mav-durability-on-gh. The skill is fully resumable — a fresh agent re-entering after a crash, stop, or context-exhaustion must skip phases that already completed rather than re-running them against an in-flight or merged PR (#41). Do not reconstruct the resume position by hand:

   uv run maverick coord resume-point <repo> $ARGUMENTS
   

   The command reads the task-progress marker, finds the PR via the recorded branch, inspects CI and the review verdict, and returns {next, instruction, evidence} — follow the instruction. Also check for an existing worktree under .maverick/worktrees/ before creating one. Each phase below ends with a task-progress set write so re-entry advances one boundary at a time without re-running anything.