ship

---

name: ship description: "Release-gate sequence: validate → review → push → tag. Wraps kernel:git mechanics with the pre-ship safety chain. Triggers: ship, release, push to main, ready to merge, deploy." allowed-tools: Read, Bash, Task, Edit kernel: kind: operator version: 1 side_effects: writes_remote confirmation: on_side_effect

Sequence

1. Preflight

   • git status --porcelain — clean? If not: ask user to commit, stash, or abandon.
   • git branch --show-current — matches intent? Wrong branch → stop.
   • git log --oneline {main}..HEAD — commit range matches what you think you're shipping?
   • (gate: any mismatch → AskUserQuestion before continuing)

2. Validate

   • Invoke /kernel:validate (spawns validator agent, full 9-gate safety chain).
   • If unavailable: run project's nearest configured command (see reference/ship-research.md for equivalents).
   • (gate: any FAIL → stop; report which gate; do NOT push)
   • For plugins that support multiple loaders, validate each loader's schema independently and exercise one installed payload per loader. A shared file parsing successfully is not proof that its armed behavior is equivalent.
   • Run install, supported upgrade, and documented recovery commands in a disposable plugin/cache copy from outside the source checkout. Assert user data and user-owned files are unchanged.
   • Put an explicit resource ceiling around heavyweight suites when available; a release gate must fail loudly instead of exhausting the host machine.

3. Review

   • Tier 1 (1–2 file changes, low risk): self-review via Big 5 from skills/quality/SKILL.md.
   • Tier 2+: invoke /kernel:review (spawns reviewer agent, >80% confidence threshold).
   • (gate: REQUEST CHANGES → stop; address feedback; restart from step 2)
   • (gate: COMMENT → AskUserQuestion: "Address now, ship anyway, or hold?")
   • (gate: APPROVE → continue)

4. Push

   • Feature branch (feat/*, fix/*, chore/*, etc.): git push (or git push -u origin {branch} if upstream not set).
   • main / master: STOP. AskUserQuestion required. (NEXUS I0.8)
   • Detached HEAD or unexpected state: stop; investigate.
   • (gate: push rejected / non-fast-forward → surface to user; do NOT force-push)

5. Version + Tag (on a release)

   • Semver: patch=fix, minor=feature or behavior-preserving refactor, major=breaking. Confirm the number with the user.
   • Bump ALL canonical declarations in one shot: scripts/bump-version.sh X.Y.Z updates .claude-plugin/plugin.json, .claude-plugin/marketplace.json, governance/kernel.md.tmpl, regenerates AGENTS.md and CLAUDE.md, and updates skills/help/SKILL.md. NEVER hand-edit one location — drift fails test_version_sync_all.
   • Human-author the release prose the script does NOT touch: the plugin/marketplace description highlight + a CHANGELOG.md entry (## [X.Y.Z] - DATE + Added/Changed/Fixed).
   • (gate: bash tests/run-tests.sh green — test_version_sync_all confirms no stale version anywhere.)
   • If a native manifest validator rejects required safety metadata, do not weaken the safety metadata or hand-author an unvalidated manifest. Keep the proven compatibility loader, record the limitation, and defer the native manifest until both schemas can be satisfied.
   • Tag (only if user requested a tagged release): git tag -l to avoid clobber → git tag -a v{X.Y.Z} -m "{summary}" → git push origin v{X.Y.Z}.
   • Before upgrading the installed plugin on this machine: pgrep -fl codex. The upgrade deletes the old cache directory under a live session's feet and every hook in that session exits 127 until it restarts. Name the live sessions in the handoff and say they need a restart; never report "upgraded" as if it covered them (docs/upgrading.md, 2026-08-27).
   • After publishing the GitHub release, install it into Claude's own cache and verify a fresh headless Claude process: scripts/install-release.sh X.Y.Z. The script updates only Claude's marketplace/cache, atomically advances Claude's current selector, and fails unless both the installed manifest and the fresh process report X.Y.Z. Codex installation remains a separate operation.

6. Human pass (any user-facing release: app build, deploy, anything a person will touch)

   • Load skills/human-pass/SKILL.md and write the guide for THIS build: literal controls, paste-ready inputs, expected outcome per step, worst case first, bundled to one sitting with the time cost stated.
   • Hand it over and wait. The build is not shipped, it is awaiting verdict.
   • (gate: no guide, or no recorded verdict → the release is NOT done. Say "awaiting your pass on ", never "shipped". A green pipeline is not a person having used the thing.)
   • Findings come back as prose; YOU convert them into issues, not the human.
   • Record the verdict as a state-change receipt on the release issue, naming what it unlocks (next build, submission, deploy promotion).

7. Checkpoint

   • agentdb learn pattern "ship: {branch} {commit_range} {sha_pushed}" "validate=pass review=pass push=ok"
   • Profile-gated: github-oss/github-production → post PR or release note via gh CLI.

The verdict is part of done

For anything a person will use, the completion states are ordered: validated, merged, deployed, accepted. CI proves the first three. Only a human who used the build proves the fourth, and only that one predicts whether the release was any good: a 15-minute guided pass found five defects that 500+ green tests had not, because some properties only exist on the far side of a real screen with real data. Report the state you actually reached, by name.

Ask-user gates (mandatory pause points)

Point	Condition	Question
Preflight	Branch or commit range is ambiguous	"Shipping {N} commits on {branch}. Confirm?"
Review	COMMENT verdict	"Review returned {N} comments. Address now, ship anyway, or hold?"
Push	Target is main/master	"About to push to main. NEXUS I0.8 requires explicit say-so. Confirm?"

Failure modes

1. validate FAIL → block; report which gate; do not loop silently
2. review REQUEST_CHANGES → block; address comments; restart from step 2
3. push rejected (non-fast-forward) → ask user; never auto-rebase or force-push
4. tag conflict → check git tag -l first; suggest next version; never overwrite existing tag

Anti-patterns

• ship_without_validate — every step depends on the previous; skipping validate skips type/test/security
• silent_skip_review — review FAIL with no surfacing to user = trust violation
• auto_push_to_main — NEXUS I0.8; main requires explicit user confirmation
• force_push_on_rejection — rejection means remote has work you don't; investigate before overwriting
• tag_without_release_intent — tags are durable; casual pushes get no tag
• skip_checkpoint — shipped-but-unrecorded work breaks retrospective and learning loops

<on_complete> agentdb write-end '{"skill":"ship","branch":"X","commits":N,"validate":"pass","review":"approve|comment|skip","pushed":true,"tagged":"X.Y.Z|none"}' </on_complete>