/ship

name: ship
description: "Run a release end to end, autonomous by default: version bump everywhere, changelog, docs, landing page, tag, push, GitHub release, PyPI/npm. Use to ship, cut, or tag a release. Don't use for routine commits, pull requests, or marketplace publishing."
license: MIT
effort: max
metadata:
  version: 3.0.1
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Ship

Release a project end to end: the version in every place it appears, the developer changelog and end-user notes, the README, docs, and landing page, then build, tag, push, GitHub release, and PyPI/npm publish.

Usage

/ship [X.Y.Z | major | minor | patch] [--auto | --no-auto]

• **Auto mode (default)** runs every step without asking. Each point where interactive mode asks has a fixed outcome: continue, skip with `PARTIAL`, or stop with `BLOCKED`.
• **Interactive mode (`--no-auto`)** asks the user to confirm the version, the file changes, the build, the push, the GitHub release, and each publish. "Ask me before each step" selects it too.
• **Version argument**: `X.Y.Z` releases that version; `major|minor|patch` sets the bump.

Read `references/auto-mode.md` before Step 1: outcome table, hard stops, version rules.

**Scope.** A mode removes confirmations; it never widens the request. Only `/ship` or an explicit request to ship, cut, tag, or publish a release runs Steps 6-9. "What changed?" or "draft release notes" runs Step 2 and the changelog-generator only, and changes no file. "Bump the version" or "update the docs/landing page for the release" runs Steps 1-5 and leaves the changes uncommitted.

Steps

1. **Pre-flight**: mode, resume check, clean tree, branch, sync, release tool 2. **Determine version** from the commits since the last tag, and check the registries 3. **Prepare changes**: *(subagents, two waves)* version, changelog, docs, landing page 4. **Review**: *(subagent)* mandatory in auto mode 5. **Apply and sweep**: write the changes, prove no stale version remains 6. **Build** 7. **Commit, tag, push** 8. **GitHub release** 9. **Publish** to PyPI and/or npm

Repo Sync Before Edits (mandatory)

Before creating, updating, or deleting files, sync the current branch with the remote. If the working tree is not clean, run `git stash push -u -m "pre-sync"` first and `git stash pop` after:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"

If a rebase or stash conflict occurs, stop with `BLOCKED — sync conflict` and list the files under `Decision` (interactive mode: ask the user). If `origin` is missing, follow the `origin missing` row in `references/auto-mode.md`.

---

Step 1: Pre-flight (inline)

1. Print the mode, the version argument, and the scope. 2. Full release only: run `git status --porcelain`. If it prints anything: auto mode stops with `BLOCKED — uncommitted changes` and lists the files; interactive mode asks whether to stash (pop after the final report), commit, or abort. Never discard work. 3. Full release only: check that the current branch is the default branch: `git symbolic-ref --short refs/remotes/origin/HEAD` prints `origin/<default>`; if that ref is missing, read the `HEAD branch:` line of `git remote show origin`. If the branches differ, follow the `Not on the default branch` row in `references/auto-mode.md`. 4. Full release only: run `git describe --exact-match --tags HEAD`. Resume that release only when no version argument was given, or an explicit version equals the tag's release version. A different version or `major|minor|patch` continues through the sync and normal version selection. For resume, follow `references/resume.md`: skip version preparation, but rebuild and verify artifacts before any unfinished local upload. 5. Run the Repo Sync above. 6. Check for a release tool or a monorepo:

   ls -d .releaserc* .changeset .versionrc* lerna.json release.config.* pnpm-workspace.yaml 2>/dev/null
   grep -qs '^\[workspace\]' Cargo.toml && echo "cargo workspace"
   grep -E '"(release|semantic-release|release-it|@changesets/cli|standard-version|workspaces)"[[:space:]]*:' package.json 2>/dev/null

The `package.json` grep matches a `scripts.release` entry, a release-tool dependency, or `workspaces`, never `"version"`. On a match, follow the `Release tool detected` or `Monorepo` row in `references/auto-mode.md`.

Step 2: Determine Version (inline)

last_tag="$(git describe --tags --abbrev=0 2>/dev/null)"
range="${last_tag:+$last_tag..}HEAD"
git log "$range" --oneline --no-merges -n 300
git log "$range" --format=%B --no-merges | grep -E '^BREAKING[ -]CHANGE:'

`OLD_VERSION` is `last_tag` without its prefix; the new tag keeps that prefix (`v` when there are no tags). Choose `NEW_VERSION` by the first rule that applies:

1. A version argument → use it. 2. `last_tag` exists and the log is empty → `BLOCKED — nothing to release`. 3. A row in `references/auto-mode.md` → _Version rules_ matches → use its outcome. 4. Commits: **MAJOR** for a `BREAKING:` or `!:` subject or a `BREAKING CHANGE:` footer, **MINOR** for `feat:`, else **PATCH**.

Stop with `BLOCKED` before any file changes if the tag for `NEW_VERSION` exists locally or on origin, or if a registry the project publishes to already has `NEW_VERSION` (`references/publishing.md` → _Decide per registry_). Print "N features, M fixes, K breaking since vOLD → **vNEW** (rule: <rule>)". Interactive mode asks the user to confirm or override; auto mode continues.

Step 3: Prepare Changes (subagents, two waves)

Subagents read in isolated context so the main agent's context window stays small. Spawn inputs, file ownership, and the workspace: `references/orchestration.md`. Without the Agent tool, run each agent file inline in the same order.

• **Wave 1**, same turn: `version-bumper` and `changelog-generator`.
• **Wave 2**, same turn, after wave 1 returns: `docs-updater` and `landing-page-updater`, both reading `version-changes