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
- 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).
- 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.
- 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."
- Launch disjoint agents in parallel; implement the risky PRs yourself while they run.
- 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.
- 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.
- 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 stepepic-ship - the sequential counterpart: one PR per phase when each phase builds on the last
1---2name: parallel-ship3description: 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.4---56# Parallel Ship78Coordinate 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.910This 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.1112## When to use1314- One analysis/design context has produced 3+ shippable changes.15- The changes touch **disjoint files** (check before launching; two agents on the same file = merge conflicts).16- 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.1718When 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`).1920## Workflow21221. **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).232. **Split by risk, not by size.**24 - Mechanical/well-specified changes (new components, sweeps, copy, config) -> background agents, cheaper model is fine.25 - 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.263. **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."274. **Launch disjoint agents in parallel; implement the risky PRs yourself while they run.**285. **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.296. **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.307. **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`.3132## Coordination tricks (learned the hard way)3334- **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.35- **`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>`.36- **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.37- **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.38- Post a brief status line as each PR opens; agents' reports aren't visible to the user unless you relay them.3940## Related4142- `ship-pr` - the single-PR workflow each agent follows internally, including branch prefixes and the verify step43- `epic-ship` - the sequential counterpart: one PR per phase when each phase builds on the last
davidtheproduct