PR Swarm

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

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 .login vs. 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

Poll every ~60-120s with jitter: tail each lane's log, check liveness (see references/launch-mechanics.md for the zombie-PID trap). Never treat a lane's own self-reported completion as the gate. After a lane's process exits, independently re-verify via the checks in references/verification-gates.md — merge state, CI conclusion, unresolved review threads (including body-only bot reviews), and current state (a maintainer-closed PR looks identical to a healthy one on every other field).

A lane inheriting a PR that already has red CI or open feedback at launch is normal input, not a swarm-level stop condition — the independence check (Phase 2) governs whether the swarm proceeds, not the target PR's current health. Each lane's own orientation and watch loop react to that starting state directly (see references/lane-prompt-template.md): fix what's already visible first, and react to the first individually-failing check rather than waiting for every check in a CI run to finish, or for an admin-gated gh run rerun that a non-admin lane can't invoke anyway (see "React to the first failing check, not the full matrix" in references/verification-gates.md).