---
name: cut-release
description: Prepare a release of the @rootplatform/cli — bump the version, add a CHANGELOG entry, run checks, and open a PR with release notes. Use when the user wants to cut/prepare a release, bump the CLI version (before merging), add a changelog entry, or mentions "release", "version bump", or "publish the CLI".
---

# Cut a release

Prepares a release PR for `@rootplatform/cli`. Versioning and the changelog are **manual**; npm
publish is automated (`.github/workflows/publish.yml` runs on a GitHub Release being *created*
and publishes whatever version is in `package.json`). This skill covers everything up to merge.

## Workflow

1. **Pick the bump type.** Repo convention has used **patch** for the whole `2.0.x` line, even for
   small features. Strict semver wants **minor** for new features, **major** for breaking changes.
   Default to patch to match history, but if the change is a user-facing feature, confirm
   patch-vs-minor with the author before bumping — it's their call. The bump itself is not
   optional — the "Version bump check" CI job fails any PR whose version is not strictly
   greater than main's; only the level is the author's call.

2. **Bump the version** (never hand-edit the numbers — keeps `package.json` and
   `package-lock.json` in sync):
   ```bash
   npm version <patch|minor|major> --no-git-tag-version
   ```
   Verify the diff touches only the three `"version"` fields.

3. **Add a CHANGELOG entry.** `CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com).
   Insert a new section directly above the most recent one:
   ```md
   ## [<version>] - <YYYY-MM-DD>     # use today's date

   ### Added            # or Changed / Fixed / Removed / Security
   - **<Short title>** - <what changed, from the user's point of view>.
   ```
   **The CHANGELOG is public.** Keep entries user-facing — describe what `rp` users can now do.
   Do NOT reference internal API/wire field names, server-side storage, or cross-repo
   (platform) dependencies. Those belong in the PR description, not here.

4. **Run the checks** (the publish workflow runs `npm test` + `npm run build`, so they must pass):
   ```bash
   npm run build   # tsc
   npm test        # tsc + mocha
   npm run lint
   ```
   Gotchas:
   - Mocha aborts with `Cannot find module 'X'` pointing at a `dist/...` path → stale orphaned
     build output: `rm -rf dist` and re-run.
   - `tsc` errors about `fetch`/`Response`/`ora` in files you didn't touch → `node_modules` drift:
     `npm ci`.
   - `npm run lint` has pre-existing repo-wide errors; lint only your changed files to judge impact.

5. **Commit on a feature branch.** Use the repo's emoji commit style; bump on its own commit:
   ```
   ✨ <feature summary>
   ⚙️ Bumped version to <version>
   ```
   End commit messages with the `Co-Authored-By: Claude ...` footer.

6. **Open the PR** filling every section of `PULL_REQUEST_TEMPLATE.md`, including the
   **"Version bump & rationale"** section (the new version and why patch/minor/major). The
   **"Release title & description"** section matters most — it's the source for the GitHub
   Release notes published on deploy. Cover backwards compatibility explicitly (the template requires it).

## After merge (human step, not automated by this skill)

Someone creates a **GitHub Release** (`gh release create` or the UI). That triggers
`publish.yml` → `npm test` + `npm run build` + `npm publish` of the version in `package.json`,
then a Slack notification. There is no separate version tag step beyond the release.