prepare-release

name	prepare-release
description	Use this skill when the user asks to "prepare a release", "update the changelog", "bump the version", "prepare release notes", or "cut a release". Automates changelog generation from git commits since the last tag and version bumping across gradle.properties files.
version	1.0.0

Prepare Release Skill

Automates the release-prep workflow: a CHANGELOG.md entry plus version bumps.

Versioning scheme

Bravo versions are major.minor.patch.build:

• major.minor.patch tracks upstream Maestro — CLI_VERSION in maestro-cli/gradle.properties and VERSION_NAME in gradle.properties. These are overwritten by upstream on rebase; we follow them.
• build is the fork-owned segment — BRAVO_BUILD. It is auto-incremented at release time by the publish-cli workflow (it finds the highest existing cli-<CLI_VERSION>.<N> release and uses N+1, or 0 for a new Maestro version), so fork-only fixes ship without drifting from Maestro's version. You do not hand-edit it; the value in maestro-cli/gradle.properties is only a local-build fallback.

The composed major.minor.patch.build is assembled in maestro-cli/build.gradle.kts (FULL_CLI_VERSION) and used for version.properties, the JReleaser tag (cli-X.Y.Z.B), and the release name. The CHANGELOG and its consistency test stay keyed on the 3-part CLI_VERSION (the build segment is fork metadata, not a Maestro changelog version).

Steps

1. Determine the release type and version

Decide which kind of release this is:

• Fork-only release — a fix to Bravo's own additions on the same Maestro base. Nothing to bump: leave CLI_VERSION/VERSION_NAME as-is. publish-cli will pick the next BRAVO_BUILD automatically when you dispatch it. This skill's only job here is an optional CHANGELOG bullet (step 3); steps 4 is a no-op.
• Upstream-tracking release — major.minor.patch is moving (typically right after an upstream rebase). Set CLI_VERSION/VERSION_NAME to the new Maestro version (step 4); BRAVO_BUILD resets to 0 on its own, since there are no cli-<new version>.<N> releases yet.

If the user hasn't said which, use AskUserQuestion to confirm the type and the target major.minor.patch (no v prefix).

2. Find commits since the last tag

Run these two commands:

git describe --tags --abbrev=0

Then use the resulting tag (e.g. v2.5.0) to list commits:

git log <tag>..HEAD --oneline

3. Update CHANGELOG.md

File: CHANGELOG.md. CHANGELOG headers are the 3-part major.minor.patch.

• Upstream-tracking release: insert a new section between the ## Unreleased line and the first existing version header, headed by the new major.minor.patch.
• Fork-only release (BRAVO_BUILD bump, same major.minor.patch): the section for the current major.minor.patch already exists — append the fork fix as a new bullet there rather than adding a new header. (The consistency test only requires a non-empty entry for CLI_VERSION.)

Section format:

## <major.minor.patch>

- <entry 1>
- <entry 2>
...

Editorial rules for commit → entry conversion:

• Each commit becomes one - bullet point.
• Strip conventional-commit prefixes (fix:, feat:, fix(scope):, etc.) and capitalise the first word.
• Remove PR number suffixes like (#1234) only if the commit message is already clear without them; otherwise keep them.
• Rewrite for clarity and consistency with the existing CHANGELOG tone (sentence case, imperative or noun phrases).
• Do not add a "Thanks to" contributors line — that is added manually.

4. Update version numbers (upstream-tracking release only)

For a fork-only release, skip this step — leave the version files untouched.

For an upstream-tracking release, set the new 3-part Maestro version in both files. Leave BRAVO_BUILD alone (it is auto-incremented at release time):

gradle.properties — VERSION_NAME (3-part Maestro version):

VERSION_NAME=<major.minor.patch>

maestro-cli/gradle.properties — CLI_VERSION (3-part):

CLI_VERSION=<major.minor.patch>

5. Run ChangeLogUtilsTest

./gradlew :maestro-cli:test --tests "maestro.cli.util.ChangeLogUtilsTest"

The key test (test format last version) reads the generated version, takes its 3-part base (major.minor.patch), and asserts the CHANGELOG contains a non-empty entry for it. So the CHANGELOG must have a populated section for the current CLI_VERSION — the BRAVO_BUILD segment is ignored by this check.

Report the test result. If it fails, diagnose and fix before finishing.