release

System Release Command

Create a new release: bump the version, update the changelog, run harness maintenance, create a git tag, publish to npm, and optionally create a GitHub Release. Quick pre-flight checks and all user interaction happen in the main context; the context-heavy changelog/commit analysis for auto-detect is delegated to a context-isolator subagent.

Arguments

• $ARGUMENTS — Optional bump type or explicit version, plus optional flags:
  • (no argument) — Auto-detect version bump from changelog and commits
  • patch / minor / major — Force that bump type
  • X.Y.Z — Explicit version number (e.g., 0.2.0)
  • --dry-run — Show what would happen without making changes

Semantic Versioning

Bump Type	When to Use	Example
MAJOR	Breaking changes to user config or workflows	0.1.0 -> 1.0.0
MINOR	New features, backward compatible	0.1.0 -> 0.2.0
PATCH	Bug fixes, documentation updates	0.1.0 -> 0.1.1

---

Phase 1: Parse Arguments

Determine the bump type (patch, minor, major, explicit version, or auto — the default) and whether --dry-run is present.

---

Phase 2: Pre-flight Checks

# Check 1: Working directory is clean
git status --porcelain

If output is not empty, STOP: report the uncommitted files and tell the user to commit or stash before releasing.

# Check 2: On main branch, up to date with origin
git branch --show-current
git pull --ff-only

If not main, STOP: releases are cut from current main.

Repo reality (learned across v0.59.0–v0.65.0): main is push-protected and merges only through the merge queue, so the release commit CANNOT be pushed directly, and all branch/commit work happens in a dedicated worktree — never by switching the shared main checkout's branch. Phase 6 below is written for that flow: edit → release worktree → PR → queue merges it → tag the MERGED squash SHA → publish npm last. Tagging your local pre-merge commit tags the wrong SHA (squash rewrites it), and pnpm publish before the merge fails pnpm's git-checks (ERR_PNPM_GIT_NOT_LATEST).