Ship Pipeline

Standalone Codex

Skip Claude's !command interpolation below. Run git branch --show-current, git status --porcelain, and git log --oneline -5 explicitly. Create a new reviewer with spawn_agent, continue it while live with send_message, trigger another turn once it is idle with followup_task, wait with wait_agent, and stop its current turn with interrupt_agent only when necessary. Never spawn codex-verifier and never run codex-run.ts from inside Codex.

Writers share the working tree unless the live host explicitly offers isolation. Assign non-overlapping ownership and serialize any implementer and test-writer fixes; only read-only reviewers may overlap. Codex implementers are not promised Claude worktree isolation. Codex also skips TLDR and uses git diff --name-only, direct import searches, and test-name searches to choose affected tests.

You are in Maestro orchestration mode. Execute the shipping checklist in order.

Claude current state

• Branch: !git branch --show-current 2>/dev/null || echo "unknown"
• Working tree: !git status --porcelain 2>/dev/null | head -20
• Recent commits: !git log --oneline -5 2>/dev/null || echo "no commits"

Pipeline (All Steps Mandatory)

Step 0: Preflight

bun "$HOME/.claude/src/scripts/git-transport.ts"

Follow its Git push: line for every push in this run, so a dropped SSH agent never costs a failed push. Never retry SSH after "Permission denied (publickey)". The 1Password instruction applies only when that line mentions 1Password; a Commits are signed through 1Password line means ask the user to unlock it now, before the first commit, because signing fails once the agent is locked. not logged in means stop and ask the user to log in. No output means no GitHub origin: use a plain git push.

When the repo maps to a Linear team (the startup Linear: line, or ~/.claude/tmp/linear-map.json), confirm the Linear MCP server is connected (a Linear tool such as list_teams is available and answers). If it is not, stop before any commit and hand back: "Sign in to Linear: run /mcp and select the Linear server, then rerun /ship. If you signed in from another session, restart this one; an open session keeps the Linear tools it started with", unless the user says this PR goes without a ticket.

Read and validate package.json before choosing commands. Invalid JSON or invalid script declarations block the pipeline. Do not commit until all applicable gates in Steps 1–4 (typecheck/build/test/lint) are green; record an absent build script as N/A with its reason. Skipping ahead is where amend churn comes from — --amend to fix a lint error you would have caught in 30 seconds invalidates signatures and CI runs.

Step 1: Type Check

bunx tsc --noEmit

If errors: fix them. Do not proceed until clean.

Step 2: Build

Inspect the validated manifest: if scripts.build is a nonempty string, run:

bun run build

If the configured build fails, fix it; do not proceed until clean. If build is absent, record N/A — no build script and continue with the applicable typecheck, test, and lint gates. An empty, whitespace-only, or non-string build declaration is invalid and blocks the pipeline. Do not add a dummy build script or silently replace a failing build with typecheck. A proof runner that only detects typecheck/test/lint does not replace this configured-build gate.

Step 3: Test (if tests exist)

3a. Affected tests first. In Claude, use TLDR when available. Standalone Codex uses the native searches in its host branch. Run only the tests touched by your changes before the full suite.

tldr change-impact --project . 2>/dev/null

If TLDR returns a list, run those tests first (bun test <file> or vitest run <file>). If they fail, fix before the full run — don't waste cycles on the rest.

3b. Full suite.

Select one configured runner before executing it. Never treat a second runner as a fallback after a real test failure:

if bun -e 'const p = await Bun.file("package.json").json(); process.exit(typeof p.scripts?.test === "string" ? 0 : 1)'; then
  bun run test
elif bun -e 'const p = await Bun.file("package.json").json(); process.exit(p.devDependencies?.vitest || p.dependencies?.vitest ? 0 : 1)'; then
  ./node_modules/.bin/vitest run
else
  bun test
fi

If no tests or runner are configured, record the evidence and skip this step. If the selected runner fails, stop and fix that failure. Do not run a narrower suite to turn a real failure green.

Step 4: Lint

biome check .

If errors: fix or justify.

Step 5: Web Quality Gate

Quick sanity check before review:

• No loading="lazy" on above-fold/LCP images
• Images have explicit dimensions or fill prop
• No console.log left in production code
• Meta tags present on new pages (title, description, canonical)
• Structured data valid on new content pages

If issues found: fix them before proceeding to review.

Step 6: Review Changes

Spawn reviewer agent:

Agent(reviewer, "Review all staged changes for quality, TypeScript strictness, a11y, and performance issues.")

Standalone Codex branch: follow the native lifecycle above and use a fresh read-only reviewer. Skip the Claude bridge branch below.

When the Codex bridge is available, run the one cross-model review for this PR in parallel — a different model family catches what Claude self-review misses, and this is right before a commit lands, the cheapest place to catch a Critical. Skip it if a Codex review already covered this diff:

Agent(codex-verifier, "Cross-model review of the staged diff. Report findings by severity.")

If Claude and Codex disagree on a Critical/HIGH finding, surface it to the user as a gate before Step 7 — don't auto-commit through a cross-model disagreement. The bridge is gated and fails open: if Codex is unavailable, proceed with the Claude review alone.

If the codex-verifier spawn fails, or it reports that Bash was stripped (forked skill contexts), run bun "$HOME/.claude/src/scripts/codex-run.ts" review directly instead — never skip the cross-model pass.

Step 7: Commit (Bisectable)

Read ~/.claude/rules/git.md if present; Steps 7 and 8 follow its "Commit and PR mechanics".

git branch --show-current printing main or master means branch off before the first commit: run steps 1-4 of "Linear issue" below to get the ID (skip them when the repo has no Linear or the user opted out of a ticket), then git switch -c <type>/<LINEAR-ID>-<slug> and commit there. /ship never pushes to main or master; the safety-net hook asks the user before any such push.

Analyze the diff to decide commit strategy:

git diff --cached --stat | tail -1

Small diff (<50 lines changed across <4 files): Single commit.

git add <relevant files>
git commit -F <msgfile> -- <relevant files>

Every commit, split ones included, names its paths in both calls and takes its message from a file; see rules/git.md "Commit and PR mechanics".

Larger diff: Split into ordered commits by dependency layer. Each commit must be independently valid — no broken imports, no forward references.

Commit order (skip layers with no changes):

1. Infrastructure — config files, env changes, package.json, build config
2. Types/interfaces — type definitions, schemas, shared interfaces
3. Logic — utilities, hooks, services, lib code (group with their tests when small)
4. UI — components, pages, styles (group with their tests when small)
5. Tests — remaining test files not already grouped with their subjects
6. Meta — docs, changelog, version bumps — always last commit

Per-commit validation: Each commit must independently pass:

bunx tsc --noEmit && bunx biome check .

If a commit would break either check in isolation, merge it with the next commit in the sequence.

Commit messages: Each gets a conventional prefix (feat:, fix:, refactor:, test:, chore:, docs:).

Step 8: Push and PR

No git remote (git remote prints nothing) means a local-only run: skip every push and PR step and report the commits.

Push with the method the Git push: line from Step 0 names:

<push command from the Git push: line>
gh pr list --head "$(git branch --show-current)" --state open --json number,url,headRefName,headRepositoryOwner

Read the PR list by the rules in rules/git.md "Commit and PR mechanics": branch name only, a non-zero exit means PR state is unknown (stop, do not create), and a non-empty list means the push updated that PR. In that case skip gh pr create, rewrite the body only if it does not match the full range, run "Linear issue" below, and go to Step 9. Never open a second PR for the same branch.

If gh is not available, provide the push command and instruct the user to create the PR manually.

Linear issue

Every PR carries a Linear issue. Work often starts before anyone files one, so this step creates it when it is missing, without asking, and reports the link:

1. Find an existing ID (ABC-123) in the branch name, the PR title and body, and git log <base>..HEAD. Confirm each candidate with the Linear MCP get_issue: UTF-8 and SHA-256 have the same shape and are not issues.

2. Resolve the repo's team for gh repo view --json nameWithOwner --jq .nameWithOwner, matching owner/repo ignoring case. The first hit wins:

   • ~/.claude/linear-teams.json, a per-person override. Each value is {"server": "<Linear MCP server name>", "team": "<team key>", "project": "<project ID>"}, or null. project is optional. When the file is missing or cannot be read, go on to the next source.
   • The startup Linear: team <KEY>, project "<name or ID>" line in this session's context, which SessionStart builds from the shared map below. Use it as is; save_issue takes the project name or ID.
   • ~/.claude/tmp/linear-map.json, the shared map that SessionStart caches from team-knowledge: {"map": {"owner/repo": {"team": "<team key>", "project": "<project ID>", "projectName": "<optional>"}}, "checkedAt": "..."}. It names no MCP server, so use the connected Linear server whose list_teams has that team.

   A null value means the repo has no Linear, which ends this step. Never make up a placeholder ID such as DR-000. Missing from all three means ask once with AskUserQuestion (the teams from each connected Linear server's list_teams, plus "No Linear for this repo"), then the project (that team's list_projects, plus "No project"), then write the answers into linear-teams.json. For a darkroomengineering repo, also tell the user to add it to linear-map.json in team-knowledge by PR. Where the question tool is unavailable, skip the step and report that the repo needs a mapping.

3. Synced GitHub issue. When the PR closes a GitHub issue (Fixes #N, Closes #N in the body or commits), Linear's GitHub issue sync may already hold a copy. Search that team with list_issues (team, query set to the GitHub issue's title) and confirm a hit with get_issue, asking for attachments in fields when that server's schema has a fields parameter: it counts only when an attachment URL is that GitHub issue's URL. Use the confirmed ID as an existing ID and create nothing; keep Fixes #N in the body.
4. No confirmed ID: create the issue with save_issue in that team and, when the mapping names one, that project, assigned to the user. Write its title and description from the same plain-English summary as the PR body, effect first, per rules/git.md "Issue descriptions".
5. Link it. Put the ID at the end of the PR title (<type>: <title> (DR-123)) and Fixes <ID> on its own line in the PR body, for an issue this step created or found, or one named only in commits; Linear's GitHub integration links the PR, moves the issue through the team's workflow, and closes it on merge. An ID already in the branch name, title, or body is linked; leave it as the author wrote it. The branch is already pushed, so never rename it to add the ID. For an existing PR, add the title suffix with gh pr edit --title and the body line with gh pr edit --body-file.

Linear not connected was already caught in Step 0 (stop and ask). A Linear call that fails twice means stop and report what failed. CC_SKIP_LINEAR=1 in front of gh pr create is only for when the user explicitly said this PR has no ticket; it lets the linear-gate hook pass, and the report says the PR has no issue.

Author the PR body, never --fill (it pastes commit messages into the description). Write it from the full git log <base>..HEAD range and the diff, using the repo's own PR template or the structure in rules/git.md "PRs", then pass it with --body-file:

BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/pr-body.XXXXXX") && cat > "$BODY_FILE" <<'EOF'
<body per rules/git.md>
EOF
gh pr create --title "<type>: <concise, plain-English title> (<Linear ID>)" --body-file "$BODY_FILE"

Step 9: Watch CI Until Green (post-push)

After gh pr create, watch the PR-attached checks until all pass. This step is the watcher: never hand-roll an until/while poll, a sleep N && gh ... loop, a heredoc merge script, or one model turn per poll. Each of those re-reads the whole context to learn "still pending", and the improvised ones have merged before checks finished, waited forever on a check that never appears, and outlived their PR.

1. Find the required set first. gh pr checks --required misses checks that an org ruleset requires as a workflow (Darkroom's ci-gate is one: it never appears in the PR rollup). Read the base branch's rules:

   gh api "repos/{owner}/{repo}/rules/branches/BASE" \
     --jq '.[] | select(.type=="workflows" or .type=="required_status_checks") | .parameters'

   A workflows rule names its file (ci-gate.yml); verify it by run, not by gh pr checks, matching the run's path to the rule's path (display names can collide, and a commit can have both push and PR runs):

   gh api "repos/{owner}/{repo}/actions/runs?head_sha=HEAD_SHA" \
     --jq '.workflow_runs[] | select(.path==".github/workflows/ci-gate.yml") | "\(.id) \(.event) \(.status) \(.conclusion)"'

   Take the newest matching run for the PR's event. A required_status_checks rule names contexts that do appear in gh pr checks. An empty result from both means nothing is required, so every reported check is the gate.

2. Watch once, blocking:

   gh pr checks --watch --fail-fast --interval 30

   Run it in the background when other work can proceed; the harness notifies you when it exits. If it exits within seconds saying no checks are reported, the checks have not registered yet: re-run it once after 30 seconds rather than treating it as green or red.

3. Read the verdict, then the required workflows. Green means every required check and run concluded success. "No failures" while something is still pending or missing is not green. Re-read gh pr checks --json name,bucket,state,workflow,link, then confirm each required workflow run from step 1 with the actions/runs query. If that run is still in progress after the PR checks finish, wait on it by ID with one blocking gh run watch RUN_ID --exit-status --interval 30, then read its conclusion. That run is part of this step's watch, not a new loop.

If a check fails:

1. Identify the failing job and fetch logs (gh run view RUN_ID --log-failed for GHA; follow the link for external services). On a red or missing check, also fetch the team-knowledge index and read any note whose title matches the workflow/CI symptom before assuming a runner problem; the fetch command is in docs/knowledge-system.md (fail-open — skip if gh is unavailable).
2. Reproduce the exact failing guard locally against the real built artifact before pushing a fix — run the same test script / check command CI ran, against the binary or output CI would see. A fix verified only by reasoning is a push-and-pray loop.
3. Apply the smallest fix. Use the fix skill's "Variant: Failing PR CI" if the failure is non-trivial. For version/metadata guards, use the repo's canonical script (bump-version.sh-style) — never hand-edit versioned fields; hand-bumps desync the sibling fields the script maintains.
4. Push, then re-read gh pr checks — the check set can change between runs.
5. Repeat until green.

Guardrails:

• Scope each fix to a single failure cause.
• If failures are flaky, retry once and report flake evidence rather than chasing a phantom fix.
• If the failure is unrelated to the PR and already fixed on main, merge main into the branch instead of bloating the PR.
• Never take a watcher pipeline's exit code as the verdict — in gh run watch ID; gh run view ID ... the shell reports the last command's exit, not the run's outcome. Read the conclusion explicitly: gh run view ID --json conclusion --jq .conclusion (or gh pr checks).

Land Mode (existing PR → merged → clean)

Invoked as /ship land or when the ask is "review/fix CI then merge then clean up" on a PR that already exists. Skip Steps 0–8; run:

1. Capture the head you're validating: gh pr view --json headRefOid,reviewDecision,mergeable. Everything below is checked against THIS headRefOid.
2. Run Step 9 (required set, one blocking watch, verdict). If red, run its CI-fix loop until green. A CI fix that pushes a new commit moves the head: re-capture headRefOid and re-check against it.
3. Confirm review state from step 1: if reviewDecision is CHANGES_REQUESTED or mergeable is CONFLICTING, stop and report — do not merge through either.
4. Re-validate immediately before merging — gh pr view --json headRefOid,reviewDecision,mergeable. All three can drift while the CI loop ran (a new push moves headRefOid; a late review flips reviewDecision to CHANGES_REQUESTED; a base-branch change flips mergeable) — the head moving is not the only race. If headRefOid differs from the SHA you validated, STOP and re-run checks against the new head; if reviewDecision/mergeable regressed, STOP and report. Don't merge stale-green. (A post-merge SHA check can't catch a moved head: a squash commit does not contain the PR head as an ancestor, so the guard has to run before merge. See the gh-merge-race learning.)
5. Merge with the repo's preferred strategy (gh pr merge --squash --delete-branch --match-head-commit SHA unless repo convention says otherwise; --match-head-commit makes GitHub refuse the merge if the head moved after your check). If the repo disallows auto-merge, never wait on --auto; merge directly once Step 9 is green. Branch protection / a merge queue, if enabled, is the atomic final gate.
6. Cleanup: git checkout main && git pull, delete the local branch, prune remotes (git remote prune origin). Leave only main unless other branches have open PRs.
7. Report: PR link, merge commit, branches deleted.

Per CLAUDE-FULL.md "Autonomy": steps 5–7 are pre-approved once CI is green, the head is confirmed unchanged, and review is clean — report, don't ask. External-org repos: land mode is forbidden entirely.

Output

Return:

• Build status: Pass/Fail/N/A (N/A requires the reason: no build script)
• Test status: Pass/Fail (with count)
• Lint status: Pass/Fail
• Review status: Approved/Needs Changes
• Commits created: Count and summary of each
• PR link: URL if created
• Linear issue: ID and link, marked created or existing; or skipped, with the reason