ship

name	ship
description	Meta pipeline: review → land → deploy → smoke → heal → monitor. Takes one or more PRs from "open" through merged, deployed, live-verified, and monitored until every declared KPI is healthy. Use when asked to "ship this", "land and monitor", "take this all the way to prod", or when a feature spans repos and needs the full loop closed (per policy hq-smoke-cross-repo-contracts-before-done).
allowed-tools	Bash, Read, Grep, Glob, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskUpdate, Monitor, CronCreate, CronList

Ship

REVIEW → LAND → DEPLOY → SMOKE → HEAL (on any failure) → MONITOR.

This skill is a meta-pipeline that composes existing pack skills into one closed loop. It does not reimplement them — it sequences them and owns the failure/heal/re-verify cycle plus standing monitoring. A PR is not "shipped" when it merges; it is shipped when the live user-facing path works and a standing monitor is watching it.

Reference implementation of the full loop: the 2026-07-08 session that shipped hq-console PRs #419/#420 + hq-pro #1028 (Team signup funnel) — journal at companies/indigo/projects/hq-selfserve-team-signup/journal/2026-07-08-new-buyer-create-company.md.

Input

Accepts any combination of:

• PR refs — one or more, each as owner/repo#123, a PR URL, a bare number (repo inferred from cwd), or nothing (open PR for the current branch).
• KPI checklist — a list of observable health criteria the shipped feature must satisfy (e.g. "funnel smoke passes", "no 5xx on /api/me/signup/*", "checkout redirect lands on Stripe"). If omitted, derive one in Step 0 and confirm it with the user.
• Flags — --no-monitor (skip Step 6 standing monitor), --skip-review (only when the PRs already carry a completed paranoid review this session).

Done Criteria (define BEFORE executing)

The pipeline is complete only when ALL of these are observably true:

1. Every input PR is merged (state MERGED, merge commit recorded).
2. Every production deploy triggered by those merges completed successfully (Vercel deployment READY on the production target, and/or the deploy-prod GitHub workflow run concluded success).
3. A real end-to-end smoke against the LIVE deployed stack passed — real auth, real data, whole loop, cleanup done (hard policy hq-smoke-cross-repo-contracts-before-done).
4. A standing monitor exists and is verified (cron smoke workflow or scheduled task), OR --no-monitor was passed.
5. Every KPI in the checklist reads healthy, and the final report includes the KPI table.

Write these as concrete, checkable statements for THIS run in Step 0 (with the actual repo names, URLs, workflow names, KPI probes) before touching anything.

Step 0: Resolve Scope + Ordering

1. Resolve each PR ref → {repo, number, title, branch, base}. Anchor every gh call with -R owner/repo.
2. Resolve the owning company; load companies/{co}/policies/_digest.md and the manifest infra fields for deploy targets. Never guess credentials.
3. Identify each repo's production deploy mechanism:
   • Vercel git integration — merge to main auto-deploys; watch via vercel ls/vercel inspect or the GitHub deployment status API.
   • GH deploy-prod workflow — merge triggers (or you dispatch) a workflow; watch the run.
   • Manual (SST etc.) — merging does NOT deploy; the deploy is an explicit pipeline step you must run and watch.
4. Multi-repo ordering (hard rule): when PRs span a producer and consumer of a shared contract, land in contract-safe order — additive API fields / server first, defensive consumers second. The server must tolerate old clients before any client that depends on the new field/route deploys. Removals invert: consumers stop reading first, producer removes last. Build the merge order accordingly; within a tier, smallest/lowest-risk first (reuse land-batch triage semantics for >2 PRs).
5. Derive or confirm the KPI checklist. Each KPI must name its probe (command, URL, query, or workflow) — a KPI without a probe is not a KPI.
6. Present the plan (PRs, order, deploy mechanisms, KPIs, done criteria) and get an explicit go. Landing + deploying is irreversible-adjacent; this gate is mandatory.

Step 1: REVIEW (pre-merge gate)

For each PR, run the paranoid pre-landing review — reuse hq-pack-engineering:review semantics (two-pass: CRITICAL blocks, INFORMATIONAL goes in the PR body), or /code-review where available. For multi-PR ships, additionally review the CROSS-PR contract: do the field names, envelopes, auth token types, and encodings match on both sides of every boundary the PRs touch? (This is exactly where mocked unit tests lie — see the six-bug cascade in the smoke policy.)

• CRITICAL findings → fix on the branch, push, wait for CI, re-review.
• Never merge past an unresolved CRITICAL without explicit user override.

Step 2: LAND

For each PR in the Step 0 order, reuse hq-pack-engineering:land semantics:

1. Wait for CI green — use a background Monitor on gh pr checks {n} -R {repo} (see Background Monitors below). Fix failures at root cause; no skipped/loosened tests, ever.
2. Resolve outstanding review threads (bot suggestions applied if valid; human comments summarized to the user).
3. Merge: gh pr merge {n} -R {repo} --squash --delete-branch (respect repo merge policy). Verify state MERGED and record the merge commit.
4. Between PRs: pull main, re-check the next PR's mergeable (earlier merges can create conflicts), and re-verify contract ordering still holds.

Step 3: DEPLOY (watch to completion)

For each merged PR, watch its production deploy to a terminal state:

• Vercel: find the deployment created from the merge commit and watch until READY on production (gh api repos/{owner}/{repo}/deployments + statuses, or vercel inspect). A READY preview is not done — it must be the production target.
• GH workflow: find the run triggered by the merge (or dispatch it), then gh run watch {id} -R {repo} in the background until concluded success.
• Manual deploy repos: run the documented deploy, watch it, and say so in the report — never report "merged" as "deployed" for these.

Respect the Step 0 ordering here too: do not start a consumer's deploy until its producer's deploy is live, when the consumer needs the new contract.

Step 4: SMOKE (live, end-to-end)

Hard gate per hq-smoke-cross-repo-contracts-before-done:

• Exercise the WHOLE user-facing loop on the LIVE deployed stack with real auth and real data — not unit tests, not previews, not mocked boundaries. (Reference: the funnel ship created a real company via the new route and followed the redirect all the way onto real Stripe checkout.)
• Prefer agent-browser for browser flows (pack policy hq-prefer-agent-browser); API loops via real authed requests.
• Clean up every test artifact the smoke creates (delete smoke companies, test records, orders) — or explicitly hand the leftover to the user in the report with a deletion note.
• Record exactly what was exercised and what was observed; "it loaded" is not a smoke result.

Step 5: HEAL (on any failure, any step)

On any failure — CI red, review CRITICAL, deploy failed, smoke broke, KPI unhealthy — do NOT patch blind. Apply hq-pack-engineering:investigate discipline:

1. Scope-lock to the failure; form ranked hypotheses; test one variable at a time; 3-strike rule before widening scope.
2. Fix at root cause, with a regression test (hq-bugfix-requires-tests).
3. Re-enter the pipeline at the earliest affected step: fix → review the fix → land it → watch its deploy → re-smoke. Never re-verify less than what the fix could have affected.
4. If the failure is in production and user-impacting, tell the user immediately (security/blocker signal) and offer revert as an option before a slow forward-fix.

Step 6: MONITOR (standing, until KPIs are green)

1. Verify or create a standing monitor:
   • Check for an existing cron smoke — a scheduled GitHub workflow smoking this path, or a scheduled task (CronList / scheduled-tasks) already probing it. If one exists and covers the shipped path, verify it ran green post-deploy.
   • If none exists, create one: a scheduled smoke workflow in the owning repo, or a scheduled task that runs the smoke and alerts on failure (the funnel ship used a 6-hour scheduled task alerting #hq-dev).
2. Watch until healthy: probe every KPI in the checklist. Use background Monitors with sensible windows — not sleep loops (see below). Keep watching until every KPI reads healthy for at least one full probe cycle post-deploy, healing (Step 5) anything that reads unhealthy.
3. Confirm the standing monitor itself works (trigger it once or verify its most recent run) — an unverified monitor is not a monitor.

Background Monitors (not sleep loops)

NEVER busy-wait with foreground sleep loops. Use the harness's background facilities:

• gh run watch / long-poll commands via Bash run_in_background: true — the harness re-invokes you when they exit.
• The Monitor tool with an until-condition for waiting on external state.
• Scheduled tasks / cron workflows for anything beyond the session's horizon.

Multiple independent watches (e.g. two repos' deploys) run as parallel background monitors, not serially.

Step 7: Report

Ship Complete
─────────────
PRs:      #{n} {repo} → merged {commit[:8]}  (one line each, in landed order)
Review:   {pass | N criticals fixed}
Deploys:  {repo}: {vercel READY | workflow success | manual done}  (each)
Smoke:    {what was exercised} → PASS  (artifacts cleaned: {yes | handed off})
Heals:    {none | N failures root-caused and re-landed, one line each}
Monitor:  {existing verified | created: name + schedule + alert channel}

KPI Table
| KPI | Probe | Status |
|-----|-------|--------|
| ... | ...   | ✅/❌  |

All KPIs must be ✅ (or explicitly waived by the user) before reporting done. Then journal the ship per session-journal discipline.

Rules

• Done criteria are written in Step 0 and never loosened mid-run.
• Never skip CI, never fake or loosen a test, every bugfix ships a regression test (hq-no-test-shortcuts, hq-bugfix-requires-tests).
• Additive-first / defensive-consumer ordering is a hard rule for multi-repo ships — both for merge order and deploy order.
• Merged ≠ deployed ≠ working. Only a live smoke plus healthy KPIs closes the loop; a standing monitor keeps it closed.
• Anchor every git/gh mutation (git -C, gh -R); never mutate from HQ root.
• Company isolation: one company's credentials and deploy targets only.
• Failures are reported plainly and immediately; healing is transparent in the final report, not hidden.