Skip to main content
One command. Commit, push, open the PR, fix CodeQL, resolve threads, fix CI, verify everything is green. Never merges. That’s a human decision.
/ship is the local escape hatch for the cloud pipeline. The cloud pipeline (ai-workflows, claude-code-routines) gets a PR opened and reviewed without you. /ship is what you run from a Claude Code session when you are the one iterating on a PR and want it driven to a ready-to-merge state in one command.

​
What /ship does

/ship is a thin orchestrator. It detects uncommitted changes (commits them), discovers recently-created PRs, then for each PR invokes /finalize-pr — which is where the real work happens. 
/ship
  ├─ Step 0: verify git repo
  ├─ Step 1: commit any uncommitted changes; discover PRs in scope
  ├─ Step 1.5: build a context brief from the conversation
  ├─ Step 2: invoke /finalize-pr per PR, sequentially
  └─ Step 3: re-verify each PR with live GitHub state before reporting

​
What /finalize-pr does

/finalize-pr is the loop. Five phases per PR:
PhaseWhat it owns
1. DiscoverResolve which PR(s) to act on (current branch, all, or org-wide)
2. Resolve loopStart CI monitor in background; in parallel: invoke /resolve-codeql fix, /resolve-pr-threads, merge-conflict resolution; once CI completes, run /simplify once on the cumulative changes
3. Verify gateRe-query live GitHub state — state, mergeable, mergeStateStatus, reviewDecision, statusCheckRollup.state, all reviewThreads.isResolved, CodeQL alert count
4. Update metadataA subagent updates PR title, description, linked issues
5. Report readyEmit the canonical PR status block; wait for human merge

​
What it never does

  • Never merges. Merge is always a human decision.
  • Never approves. No auto-approval of PRs.
  • Never crosses org boundaries in org-wide mode.
  • Never bypasses branch protection.

​
Subagents in the call chain

/ship → /finalize-pr → /resolve-codeql fix
                     → /resolve-pr-threads → superpowers:receiving-code-review
                     → /simplify
                     → haiku subagent (PR metadata update)
                     → background CI monitor (Task tool)
Each subagent runs scoped to its task and reports back. The orchestrator re-verifies live state — never trusts a subagent’s self-report as ground truth.

​
Known reliability gaps

/ship has been ending prematurely without leaving PRs fully mergeable. Root causes traced to the current SKILL.md files:
Failure modeWhy it happens
Exits “blocked” when a fix could have continuedPhase 3 → Phase 2 loop is prose with no enforced iteration counter — subagents treat it as advisory
Treats async-pending checks as failuresPhase 3 aborts on statusCheckRollup.state ≠ SUCCESS, but Phase 2 can’t fix a pending check
Silent subagent failure passes throughAfter /resolve-codeql and /resolve-pr-threads, skill advances without re-querying state to confirm fixes landed
CI monitor dies silentlyBackground Task agent can fail without propagating
All Phase 3 aborts treated identicallySome failures are agent-fixable, some are wait, some require humans (REVIEW_REQUIRED)
Fix in flight: explicit iteration counter (cap 5), wait-for-async-checks phase, post-fix verification of subagent work, CI-monitor failure fallback, and a failure-mode taxonomy that maps each mergeStateStatus/reviewDecision to a handler. After the fix, every /ship invocation reports one of three categories with a specific reason — never silent half-finalization:
  • Ready to merge — all gates clean
  • Ready except human gate — only REVIEW_REQUIRED remaining
  • Ship aborted — specific gate stuck with manual-action suggestion
Tracked as a PR against claude-code-plugins.

​
When to use /ship vs the cloud pipeline

SituationUse
Issue is filed, you want a PR drafted without thinkingai-workflows (the cloud pipeline triggered on issue open)
You’re editing a PR locally and want CI/threads/CodeQL handled in one command/ship from your Claude Code session
You want a daily org-wide sweepclaude-code-routines (cron-scheduled)
You want to know if a PR is really ready to merge/finalize-pr <N> directly — gives you the canonical gate output without re-running fixes

​
Where to go next

CodeQL resolution

Why CodeQL is fixed separately from CI checks, and what /resolve-codeql does.

claude-code-plugins

The plugin home for /ship, /finalize-pr, and all the supporting skills.

Source: ship/SKILL.md

The full skill definition.

Source: finalize-pr/SKILL.md

Phases, gates, and the merge prohibition.