Parallel Ship

---
name: parallel-ship
description: Ship 3+ related PRs in one session by fanning out background agents from the session that holds the analysis context - instead of writing a plan, generating a handoff prompt, and spinning up fresh sessions. Use when one piece of analysis or design work produces several independently shippable PRs across disjoint files, in any repo. For a single PR use ship-pr; for sequential dependent phases use epic-ship.
---

# Parallel Ship

Coordinate several PR-sized changes at once by launching background agents from the session that did the analysis, keeping high-risk changes (payments, auth, anything that shouldn't self-merge) in the main session.

This is the chairperson pattern in its parallel form: the session that did the analysis is the only one holding the verified facts, so it stays in charge - writing complete briefs for disposable worker agents, judging their reports against context only it holds - rather than handing off a lossy summary to fresh sessions.

## When to use

- One analysis/design context has produced 3+ shippable changes.
- The changes touch **disjoint files** (check before launching; two agents on the same file = merge conflicts).
- The spec for each change is concrete enough to write down (file paths, exact behavior, verification commands). If you cannot write the spec, the analysis is not finished - do not launch.

When NOT to use: sequential phases where PR N+1 builds on PR N's code (use `epic-ship`), or a single change (use `ship-pr`).

## Workflow

1. **Carve the work into PRs by file/module boundary.** One worktree per PR, all forked from the same base via `bash ~/.claude/skills/ship-pr/scripts/worktree-new.sh <branch>` (never stacked - each agent starts from the remote default branch, not from another agent's branch).
2. **Split by risk, not by size.**
   - Mechanical/well-specified changes (new components, sweeps, copy, config) -> background agents, cheaper model is fine.
   - High-risk changes (payments, auth, data-integrity, anything that shouldn't self-merge) -> the MAIN session implements these itself, and they don't auto-merge even on green CI.
3. **Write self-contained agent specs.** Each agent prompt must include: worktree setup (via `ship-pr`'s `worktree-new.sh`, never edit the base checkout directly), exact file targets, any project-specific copy/style rules, verification commands (build/typecheck/test - fresh, not cached), commit message format, and "open PR with a DO NOT MERGE line, do not merge, do not close the worktree, return PR URL + decisions made."
4. **Launch disjoint agents in parallel; implement the risky PRs yourself while they run.**
5. **Review each agent's report against your context** - you hold the verified facts from the analysis pass, so judgment calls the agents made (placement, naming, edge cases) are cheap to check against it.
6. **Preview round:** all PRs sit unmerged with preview links or `gh pr diff`. Relay feedback by resuming the same agents (they keep their worktree and context) rather than starting fresh ones.
7. **Merge in dependency order on the user's go**, `gh pr merge --squash --delete-branch`, then close every worktree via `ship-pr`'s `worktree-close.sh`.

## Coordination tricks (learned the hard way)

- **Two parallel PRs need the same new util file:** copy it byte-identical between branches (`git fetch origin <other-branch> && git show origin/<other-branch>:<path> > <path>`), verify `git diff origin/<other-branch> -- <path>` is EMPTY. Identical additions merge cleanly in either order; any divergence creates a squash conflict.
- **`worktree-close.sh` fails after squash-merging a multi-commit branch** (single-commit branches close fine, since the squash SHA differs from any commit on the branch). Confirm `gh pr view <n> --json state` says MERGED, then `WORKTREE_FORCE=1 bash ~/.claude/skills/ship-pr/scripts/worktree-close.sh <slug>`.
- **Write deliverable files (briefs, docs, reports) inside a worktree from the start**, not the base checkout. An untracked copy sitting in the base checkout blocks the next pull once that file merges via PR.
- **Third-party services with production-only credentials** (payment providers, etc.) often can't be tested against a staging/preview environment lacking those secrets. Pin those calls to production explicitly and note it in the PR description rather than discovering a silent 500 in preview.
- Post a brief status line as each PR opens; agents' reports aren't visible to the user unless you relay them.

## Related

- `ship-pr` - the single-PR workflow each agent follows internally, including branch prefixes and the verify step
- `epic-ship` - the sequential counterpart: one PR per phase when each phase builds on the last