| name | ship |
| description | Commit, version bump, tag, and publish a release. Use when the user says 'ship', 'release', 'publish', 'bump version', 'tag a release', 'push a new version', 'let's ship this', 'cut a release', 'publish to npm', or any variation of wanting to commit and deploy a library release. |
Ship
Commit changes, bump the version, tag, and push to trigger an npm publish.
Process
Step 1: Pre-flight checks
Run bun run check and bun test. Both must pass before proceeding. If either fails, stop and fix — do not skip checks (no --no-verify).
Step 2: Stage and commit the changes
- Run
git status and git diff to understand what changed.
- Run
git log --oneline -10 to match the existing commit message style.
- If multiple distinct intents are mixed in the working tree, split into multiple commits — invoke
/commit to do that cleanly, then return.
- Stage specific files (never
git add -A) and commit with a message that follows the project convention from CLAUDE.md.
Always update CLAUDE.md and README.md if conventions, file structure, or invariants changed in this release.
Step 3: Determine the version bump
Ask the user whether this is a major, minor, or patch change. Use these guidelines to suggest one:
- Major (
x.0.0): Breaking API changes — removed exports, renamed methods, changed return types, changed signatures that existing consumers depend on. If still on 0.x.0, minor bumps may carry breaking changes by convention.
- Minor (
0.x.0): New features, new exports, new options — anything additive that doesn't break existing code.
- Patch (
0.0.x): Bug fixes, doc updates, internal refactors with no API change.
Present the suggestion but let the user decide.
Step 4: Bump the version
- Read the current version from
package.json.
- Compute the new version based on the bump type.
- Update
package.json.
- Commit with message:
chore: bump version to {new_version}
Step 5: Tag and push
- Create an annotated git tag:
git tag -a v{new_version} -m "v{new_version}: <one-line summary of the release>". The annotation should be enough that someone reading git show v{new_version} understands what shipped.
- Ask the user for confirmation before pushing.
- Push the commits and the tag:
git push && git push --tags
This triggers .github/workflows/publish.yml, which publishes to npm via OIDC trusted publishing.
Step 6: Verify
After pushing, report:
- The new version number and the tag (
v{new_version}).
- A link to the publish run:
gh run list --workflow=publish.yml --limit=1.
Safety rules
- NEVER skip the pre-commit hook (
--no-verify). If it fails, fix the issue and try again.
- NEVER amend a previous commit — always create new commits.
- NEVER force push.
- ALWAYS ask for confirmation before
git push or git push --tags.
- ALWAYS update CLAUDE.md and README.md before committing if anything documented there has changed.
- The version tag format is
v{version} (e.g. v0.10.0), NOT just the number.
