Parallel 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 (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.

1. 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."
2. Launch disjoint agents in parallel; implement the risky PRs yourself while they run.
3. 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.
4. 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.
5. 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 && git show origin/: > ), verify git diff origin/ -- 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 --json state says MERGED, then WORKTREE_FORCE=1 bash ~/.claude/skills/ship-pr/scripts/worktree-close.sh .
• 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: davidtheproduct
• Source: davidtheproduct/claude-ship-skills
• License: MIT

Install and usage instructions live in the source repository linked above.