plan-a-release

name	plan-a-release
description	Plan a release end to end — decide the semver bump from the change set, assemble a human-readable changelog (Keep a Changelog groups), and run a release checklist (tests green, version bumped, tag signed, artifact + provenance, advisory if needed). Returns the version, the changelog entry, and the release runbook. Used by `release-and-versioning-engineer` (primary).

Skill: plan-a-release

Invoked by: release-and-versioning-engineer (primary).

When to invoke: "is this a major/minor/patch?"; "cut a release"; "write the changelog".

Output: the semver bump + the rule that picked it, the changelog entry, and the release checklist.

Step 1 — decide the bump (semver)

Traverse ../../knowledge/semver-and-release-decision-tree.md:

If the change set contains…	Bump
Any backward-incompatible change (removed/renamed public API, changed contract, dropped runtime)	MAJOR
A backward-compatible new feature or a non-breaking deprecation	MINOR
Only fixes / internal changes with no API surface change	PATCH

Pre-1.0.0: a 0.x minor may break; communicate it. The first stable release is 1.0.0, a stability commitment — not a marketing milestone.

Step 2 — write the changelog (for humans)

Group entries per Keep a Changelog: Added / Changed / Deprecated / Removed / Fixed / Security. Each line is what a user needs to upgrade, not a commit message. Lead breaking changes with **BREAKING:** and link the migration guide.

## [2.0.0] — 2026-06-23
### Removed
- **BREAKING:** dropped the deprecated `createClient(url)` signature; use `createClient({ url })`. Migration: ./docs/migrate-2.0.md
### Added
- `retry` option on all client calls (#412)
### Fixed
- race in the connection pool under high concurrency (#398)

Step 3 — run the release checklist

Use ../../templates/release-checklist.md. Minimum gates:

• CI green on the release commit (the actual head — verify a run exists for this SHA)
• Version bumped in the manifest(s) and consistent across a monorepo
• CHANGELOG updated and dated
• Tag created and signed; release notes attached
• Artifact published with provenance (Sigstore / SLSA / npm --provenance)
• If security-relevant: advisory published and disclosure timed (see coordinate-a-security-release)

Guardrails

• Bump by the change, not the feeling — a removed public symbol is a major even if it "feels small". See ../../best-practices/semver-bump-by-the-change-not-the-feeling.md.
• No release without a changelog entry — the advisory hook flags a version bump with no nearby CHANGELOG edit.
• Automate it if you can — release-please / semantic-release / Changesets turn this into a single merge; see ../../knowledge/oss-tooling-2026.md. If you automate, the Conventional Commits convention is the input — enforce it.