/pr-swarm

name: pr-swarm
description: 'Parallelizes two or more independent "own PR to green" loops for a single repository using isolated git worktrees and separate headless Claude Code sessions per PR — resolving merge conflicts, clearing review feedback, and watching CI to completion without one PR''s diff or feedback leaking into another''s context. Triggers on: "parallelize these PRs", "drive PR #123 and #456 to green in parallel", "own-PR-to-green fleet", "run these PRs concurrently", "isolated worktree loops for my PRs", "pr-swarm". Use this skill when a user has two or more already-open, file-disjoint pull requests in the same repository that each need conflict resolution, review-feedback triage, and CI monitoring, and wants them driven to merge-ready at the same time instead of one after another.'
metadata:
  version: 1.1.0
  category: operations
  tags: [git-worktree, parallel-execution, pull-requests, headless-cli, ci-monitoring]
  difficulty: advanced
  phase: ship

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|Phase 6 (Monitor & Verify)| |`references/lane-prompt-template.md`|The literal per-lane task prompt (termination conditions, orientation, conflict resolution, 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 .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 o