PR Swarm — Parallel Own-PR-to-Green Loops
Problem
A repository checkout can only have one branch active at a time. A user with N independent, already-open pull requests — disjoint branches, disjoint changed files, no real relationship between them — that each need conflict resolution, review-feedback triage, and CI watching wastes wall-clock time driving them one after another when nothing about them actually depends on each other.
Root cause
git worktree removes the one-checkout constraint: N branches can be checked out simultaneously, each in its own directory, sharing one .git object store. Combined with N independent headless Claude Code sessions (own process, own context window, own token budget — not subagents sharing this session's budget), the PRs can be driven to green concurrently with zero cross-talk.
Reference Files
| File | Contents | Load When |
|---|---|---|
references/launch-mechanics.md |
claude -p flags, detached background launch pattern, watchdog/liveness checks, exit-code capture |
Phase 5 (Launch) |
references/verification-gates.md |
GitHub API correctness pitfalls: stale mergeStateStatus, body-only bot reviews, stale statusCheckRollup entries, review-thread pagination, reacting to the first failing check instead of waiting for the full CI matrix, review triage and the three-round cap |
Phase 6 (Monitor & Verify) |
references/lane-prompt-template.md |
The literal per-lane task prompt (termination conditions, orientation, conflict resolution, review triage, round cap, watch loop) | Phase 4 (Lane Prompt) |
Scope boundary
This skill drives PRs that are already open. It does not create PRs from issues, does not decide whether unrelated PRs are safe to parallelize (that's Phase 2, and it's a hard stop on any real overlap, not a judgment call this skill makes silently), and does not resolve PRs closed by a maintainer for policy reasons — see "Mid-loop external closure" in Phase 6.
Workflow
Phase 1 — Resolve each PR
For every requested PR number N:
gh pr view N --json number,state,headRefName,baseRefName,author,url,isCrossRepository
state != OPEN→ drop this PR from the swarm and report why; do not silently skip it.isCrossRepository == true(PR from an unrelated fork, not the user's own) → flag for confirmation before proceeding; this skill assumes the invoker's own fork/branch setup.- Author check:
gh api user --jq .loginvs.author.login. Mismatch is a warning, not a stop — co-driving a teammate's PR is legitimate, but the invoker should see it flagged.
Phase 2 — Independence check (mandatory, not optional)
Do this before creating any worktree. A user asserting "these are unrelated" is not proof — verify the actual changed files:
for N in "${PRS[@]}"; do
base="$(gh pr view "$N" --json baseRefName -q .baseRefName)"
head="$(gh pr view "$N" --json headRefName -q .headRefName)"
git fetch origin "$head:refs/remotes/origin/$head" --quiet
merge_base="$(git merge-base "origin/$base" "origin/$head")"
files["$N"]="$(git diff --name-only "$merge_base" "origin/$head")"
done
Pairwise-intersect files[N] against files[M] for every pair in the requested set. Any non-empty intersection → stop, report exactly which files and which two PRs collide, and ask before proceeding — running two lanes that touch the same file concurrently is exactly the failure mode this skill exists to prevent, not something to wave through because the user said it was fine.
Phase 3 — Worktree and branch naming (inferred, never asked for)
Short name derivation from each headRefName:
raw="$head" # e.g. feat/status-line-token-count
short="${raw#*/}" # strip one leading "<type>/" segment if present
short="$(echo "$short" | tr '[:upper:]_' '[:lower:]-' | tr -s '/' '-')"
[[ -n "${used[$short]:-}" ]] && short="${short}-${N}" # disambiguate collisions with the PR number
used["$short"]=1
Worktree directory convention: check bunfig.toml / lockfile config / .gitignore for an existing .worktrees/** or .wt/** pattern first — that is the project's own sanctioned convention if present. Default to .worktrees/<short>/ when nothing is declared. Free the main checkout first if it currently holds one of the target branches (git switch main or another branch outside the set — a branch can be checked out in only one worktree).
git worktree add ".worktrees/$short" "$head"
Per-worktree install is mandatory under a hoisted linker (check bunfig.toml for linker = "hoisted", or npm/yarn without workspaces hoisting): node_modules is not shareable across worktrees since each can have a different lockfile state. Run installs for all lanes in parallel, not serially.
Gitignored build artifacts don't come back with a fresh worktree checkout — native addons, generated code, compiled binaries. If the repo has any (check for *.node, .wasm, generated protobuf/codegen output, or a documented build step), rebuild or relink them per worktree before running tests; a lane that skips this fails with a confusing "module not found" that looks unrelated to its actual task.
Phase 4 — Lane prompt
Render references/lane-prompt-template.md per PR, substituting {PR_NUMBER}, {REPO} (owner/name), {WORKTREE_PATH}, and {OTHER_PR_NUMBERS} (the rest of the swarm, so the lane's own COI instruction is concrete, not abstract). Write each rendered prompt to a file in the worktree ($WORKTREE/.pr-swarm-prompt.md) rather than passing it inline — a multi-hundred-word prompt through shell quoting is a real failure mode, a file path is not.
Phase 5 — Launch
See references/launch-mechanics.md for the exact claude -p invocation, detachment pattern, and liveness-check mechanics. One lane per PR, launched independently — never chain multiple launches in a single tool call (each launch needs its own call so a launch failure for lane 2 doesn't silently ride on lane 1's success).
Phase 6 — Monitor and verify
Monitor active lanes at a bounded cadence; use the launch reference for liveness checks. After a lane exits, independently verify current PR state, required and repository-mandated checks, applicable review requirements and substantive feedback dispositions using references/verification-gates.md. Report explicitly advisory checks separately. A lane's self-report is not evidence.
Existing red CI or feedback is normal input. Triage actionable blocking failures as soon as they appear; do not wait for the full matrix. Batch fixes before pushing. Once current gates and acceptance pass, report readiness immediately: no fixed quiet window, second insurance wait or requirement that advisory bots become silent. New substantive feedback arriving before the final state read is still actionable.
Phase 7 — Report
Per PR: final state and mergeability, blocking CI and advisory CI separately, substantive feedback dispositions, review rounds used, worktree state and lane exit code. Report ordinary merge readiness when the base branch has no merge queue. Only for a queue-backed base branch, distinguish ready-for-enrollment on an open, unqueued PR from validated queue-candidate readiness; required candidate checks still gate landing. A stopped-at-cap or unverified lane remains unresolved. Readiness authorizes neither enrollment nor merge.
Phase 8 — Teardown
Only after every lane is externally confirmed clean:
git worktree remove ".worktrees/$short"
Leave any unresolved PR's worktree in place for continued work. Removing a worktree just because the batch finished, while that one PR is still dirty, destroys debugging context for no benefit.
Output
Report structure, filled in per swarm run:
## Resolution
#{N}: {short-name} — {state}, author={login}{, author mismatch flagged if applicable}
...
## Independence check
PASS — no changed-file overlap across {PRS}
(or)
STOP — #{N} and #{M} both touch {path}; resolve before proceeding
## Worktrees
#{N} → .worktrees/{short-name} (branch {headRefName})
...
## Fleet status
| PR | state | readiness stage | mergeStateStatus | CI | unresolved threads | review rounds | worktree | exit code |
|---|---|---|---|---|---|---|---|---|
## Teardown
#{N}: removed / left in place (reason)
A PR missing from the "Fleet status" table (dropped in resolution or blocked by the independence check) must still appear in "Resolution" with the reason — never silently omitted from the report.
Single-PR invocation
pr-swarm with exactly one PR still runs the full worktree-and-own-session path — no fast path that skips isolation. The value being delivered (own session, own context/budget, no shared state with the invoking conversation) doesn't depend on fan-out width; collapsing back to inline execution for N=1 would silently drop the one guarantee that was asked for.
Capacity sanity check
- Bound active lanes by local CPU/RAM and remote CI/review capacity, not just the number of PRs. Queue excess PRs rather than saturating runners and increasing everyone's wait.
- Use focused local checks during edits, repository preflight before coherent pushes, and required integration-candidate checks before merge. Preserve broad mainline/release coverage; local success does not replace provider gates.
- Each worktree needs the dependency environment its own lockfile selects. Preserve unresolved worktrees for debugging.
- Release finished lanes when their current gates pass; different lane durations do not justify extra waiting or more speculative work.
Error Handling
| Problem | Resolution |
|---|---|
| PR number not found / no read access | Drop from swarm, report, continue with the rest |
PR state != OPEN |
Drop from swarm, report why, do not attempt to reopen |
| Two or more PRs share a changed file (Phase 2) | Stop before creating any worktree; report the exact overlap and ask |
| Branch already checked out in the main worktree | git switch it away before git worktree add |
| Worktree directory already exists from a prior run | Reuse it if the branch matches; otherwise stop and ask (don't silently overwrite) |
| Hoisted-linker install fails in one lane | That lane's setup fails independently; other lanes proceed unaffected |
| PR already has failing CI checks or unresolved feedback when the swarm launches | Not a stop condition — the lane starts by fixing what's already visible instead of waiting on a clean baseline (see references/verification-gates.md) |
| Lane still receives new Important findings after three review rounds | Lane stops pushing and reports the recurring bug class; report the PR unresolved and let the user decide between rethinking the approach and another round (see "Review triage and round cap" in references/verification-gates.md) |
gh not authenticated, or missing repo/workflow scopes |
Stop before Phase 1 — nothing downstream can function without it |
Verification
- Every reported-clean PR was checked with the current
state, not a cached read from earlier in the run - Independence check (Phase 2) ran and passed before any worktree was created
- Feedback assessment includes review bodies and inline threads, with optional findings explicitly dispositioned and provider-required thread rules preserved
- Every lane's exit code was captured, not inferred from log tail alone
- Teardown only ran for lanes independently confirmed clean
Red Flags
- Trusting a lane's final log line ("PR is ready to merge") without an independent
gh pr viewre-check - Skipping Phase 2 because "the user said they're unrelated"
- Removing a worktree for a lane whose PR isn't confirmed clean, because the batch as a whole finished
- Counting
reviewThreads.isResolved == falseas the complete unresolved-feedback signal without also scanning review bodies - A lane waiting for a full CI matrix to finish, or for an admin-gated
gh run rerun, before reacting to a check that already failed or feedback that already landed - A lane pushing a commit for every nit, or running a fourth review round without the user's decision
- Waiting through a fixed quiet window after required checks and review are already satisfied
- Treating every advisory status or optional comment as a merge veto, or ignoring a provider-required check