ship · git:20261016.5abfc14 · 2026-10-16 · sha256 23cf81add575e9c3

ship git:20261016.5abfc14A

Immutable. This exact content never changes and is served at /api/v1/blob/23cf81add575e9c3.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_5lm4753pqguotxjk/23cf81add575e9c36f4e6e1577822364743bdc302676e398493ba322ec5aeb9d.json

Then /plugin install ship@markdownregistry-5lm4753pqguotxjk in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: ship
description: Goal-oriented workflow for landing a requested change safely. Use when the user asks to ship, fix and ship, take a change through validation, or drive PR/CI/merge to completion.
metadata:
  internal: true
user-invocable: true
---

# Ship

Land the requested change with evidence, and merge only after CI is green.

Read [`knowledge/project/shipping.md`](../../../knowledge/project/shipping.md) first — it owns the success bar, the
constraints, the CI opt-out labels, and the reporting standard. This skill owns execution only.
Start from the goal and the changed risk surface, then take the shortest path that proves the
change is ready; do not walk this file as a fixed checklist.

## Sequence

1. **Check the branch.** Never ship from `main`. Clean tree before the final push.
2. **Review the delta.** `git diff origin/main...HEAD` and `git log origin/main..HEAD`. Confirm the
   requested behavior is actually implemented, then simplify avoidable complexity you introduced.
3. **Validate to the risk.** Pick from the evidence commands below; deepen only where signal is
   weak. Bug fixes prefer a failing test before the fix.
4. **Security review.** Mandatory for any change touching code, config, or infrastructure. Follow
   [`references/security-review.md`](references/security-review.md).
5. **Sync artifacts** the change actually affects: `knowledge/`, `knowledge/security/threat-model.md`, `AGENTS.md`,
   `knowledge/test-cases/`, `apps/docs/`, OpenAPI exports. When the PR completes a user-facing
   change that meets the public changelog's impact criteria, its entry with screenshots is part
   of the change; when it changes an older entry's behavior, that entry is updated. See
   [`references/changelog-entry.md`](references/changelog-entry.md).
6. **Smoke test the affected flows** end to end. For a coding-agent stack, follow the canonical
   startup contract in the root `AGENTS.md`; it includes the DB-backed infrastructure required for
   database, migration, infra, or API integration risk.
   Stop anything you started. Docs- or config-only changes may skip this with a stated reason.
7. **Decide follow-ups explicitly.** Prefer implementing in-scope work now. List anything deferred
   under **Follow-ups** in the PR body with a one-line rationale, or state "No follow-ups." — a
   reader must be able to tell "nothing left" from "agent forgot". File Linear issues (OSS/EVE) for
   non-trivial deferrals.
8. **Open the PR and merge** — see [`references/pr-and-merge.md`](references/pr-and-merge.md).

## Migrations

Migrations are named by UTC timestamp (`just new-migration <name>`), so parallel branches do not
collide and nothing needs renumbering after a rebase. `bash scripts/lib/check-migration-ordering.sh`
rejects a retired `NNN_` name or a shared version; CI runs it on the PR and on main after merge.

## Evidence commands

Pick only what matches the changed surface:

- `just pre-push` / `just pre-pr`
- `cargo fmt --check`, `cargo clippy --all-targets --all-features -- -D warnings`,
  `cargo test --all-features`, `cargo fetch --locked`
- `cd apps/ui && pnpm run format:check && pnpm run lint && pnpm run build`
- `cd apps/docs && pnpm run check && pnpm run build`
- `./scripts/export-openapi.sh`, then `cd apps/ui && pnpm run api-types:generate` —
  the UI's generated types are derived from the exported spec and CI fails on
  drift, so exporting without regenerating them is a guaranteed red build
- `bash scripts/lib/check-migration-ordering.sh` (migration names and unique versions)

If `just fmt` can auto-fix a failing format check, use it once and retry.

## Stopping

Stop and report only for blockers you cannot resolve safely alone: merge conflicts you cannot
adjudicate, missing credentials, ambiguous product intent, or CI failures you cannot reproduce.