Prepare Release

Prepare Release

End-to-end release workflow. Reads commits since the last release tag, infers the semver bump, drafts a user-facing changelog, confirms with you, creates a release PR, merges it, verifies CI is green, tags the release, and monitors the Docker build to completion.

Usage: /prepare-release

Run this from any branch after all feature PRs have been merged to main.

Step 1 — Ensure Clean Main

Switch to main and pull latest:

git checkout main
git pull origin main
git status

If git status shows uncommitted changes, stop and resolve them before continuing. The working tree must be clean.

Step 2 — Find Last Release Tag

git describe --tags --abbrev=0

Note this as LAST_TAG (e.g., v2.0.2). All commits after this tag are candidates for the release.

If this command fails (no tags exist yet), use the full history — note the first commit hash as the baseline and treat the release as the initial version.

Step 3 — Gather Commits Since Last Tag

git log <LAST_TAG>...HEAD --oneline
git diff <LAST_TAG>...HEAD --stat
git diff <LAST_TAG>...HEAD --name-only

Collect the full output of each. Do not truncate.

Step 4 — Filter and Synthesize (Critical Reasoning Step)

This is not a raw dump of commit messages. Analyze the material and produce a curated, user-facing summary.

4a. Discard internal-only commits

Ignore commits that match any of the following:

• Subject starts with: wip, WIP, checkpoint, fixup!, chore: rebase, Merge branch, version bump, release:
• Commit only touches: build.gradle.kts, gradle/, *.properties, .gitignore, .github/, Dockerfile, docker-compose.yml, scripts/, *.md files with no API impact
• Subject is a bare file list or CI housekeeping note

4b. Group meaningful changes by theme

Use only these categories (omit any that have no entries):

• Breaking Changes — removed tool, renamed/removed parameter, incompatible schema change
• New Features — new MCP tool, new operation on existing tool, new config option, new query parameter
• Bug Fixes — incorrect behavior corrected, crash fixed, data integrity issue resolved
• Performance — measurable throughput or latency improvement
• Documentation — user-visible docs (only if substantive)

4c. Write 3-8 user-facing bullet points

Rules for each bullet:

• Start with a past-tense verb (Added, Fixed, Improved, Removed, Changed)
• Name the tool or feature affected (e.g., query_items, advance_item)
• Describe the benefit to the user, not the implementation detail
• Do not mention internal class names, Kotlin types, or file paths
• Example: Added \includeAncestors` to `query_items` — eliminates parent-walk call chains for breadcrumb context`

4d. Detect plugin content changes

Check if any files under claude-plugins/ changed since the last tag:

git diff <LAST_TAG>...HEAD --name-only -- claude-plugins/

If the output is non-empty, plugin content changed. Also check if any server source files (Kotlin, migrations, Gradle config) changed:

git diff <LAST_TAG>...HEAD --name-only -- current/src/ current/build.gradle.kts gradle/

Classify the release type:

• server — server source changed, no plugin changes
• both — server source and plugin content both changed
• plugin-only — only plugin files changed (skills, hooks, orchestration context), no server source

Read the current plugin version from the authoritative source — do not assume it matches any git tag. The version in the repository files may have been bumped in a previous release:

cat claude-plugins/task-orchestrator/.claude-plugin/plugin.json | grep '"version"'

Determine the plugin bump level using the same semver rules as the server version, but scoped to plugin content:

Note the plugin bump level separately from the server bump level — they are independent. If no plugin files changed, skip plugin versioning entirely (server-only release).

Step 5 — Infer Bump Level

Plugin-only release: If the release type is plugin-only, skip the server bump entirely. The server version in version.properties stays unchanged. Only the plugin version (determined in Step 4d) is bumped. Proceed to Step 6 with the server version as-is and the plugin version as the new value.

Server or both release: Examine the synthesized changes and determine the bump level:

If multiple conditions apply, use the highest applicable level.

State the bump level and the one-sentence reason. Example:

Bump: minor — GitHub wiki CI sync and release automation added (new capability, no breaking change).

Calculate the proposed new version:

• patch: increment VERSION_PATCH by 1, keep others
• minor: increment VERSION_MINOR by 1, reset VERSION_PATCH to 0, keep VERSION_MAJOR
• major: increment VERSION_MAJOR by 1, reset VERSION_MINOR and VERSION_PATCH to 0

Step 6 — Present for Confirmation

Output the following block and stop. Wait for the user to confirm or request changes.

## Proposed Release: vX.Y.Z  (CURRENT -> NEW)

**Release type:** <server | both | plugin-only>
**Bump level:** <major | minor | patch>
**Reason:** <one sentence>

**Plugin version:** <CURRENT -> NEW> (<bump level>) — or "No plugin changes"

### Changelog Draft

## [X.Y.Z] - YYYY-MM-DD

### <Added | Changed | Fixed>
- <bullet 1>
- <bullet 2>
...

---

Use today's date in YYYY-MM-DD format. If the user requests changes, revise and re-present before continuing.

Step 7 — Create Release Branch

After confirmation:

git checkout -b release/vX.Y.Z

Step 8 — Apply Changes

8a. Update version.properties and server.json

Plugin-only release: Skip this step — the server version stays unchanged.

Server or both release: Edit version.properties in the project root. Set only the lines that need to change. Reset lower components on a major or minor bump.

Example for a minor bump from 2.0.2 -> 2.1.0:

VERSION_MAJOR=2
VERSION_MINOR=1
VERSION_PATCH=0

Then edit server.json (the MCP Registry record) in the project root — two fields:

• Set the top-level version to the new version (X.Y.Z, no v prefix).
• Update the OCI identifier in packages[] to the immutable release image tag: ghcr.io/jpicklyk/task-orchestrator:X.Y.Z (no v prefix — this is the Docker tag, not the git tag). Never leave it on :latest; the MCP Registry record for a version is immutable, so a mutable tag makes that record drift to whatever image later owns latest (#297). docker-publish.yml fails the release if either field disagrees with version.properties, and then publishes the record to the registry via mcp-publisher.

Do not skip the server.json edit. It is the one file in this step that no build reads, so a missed bump is invisible until the registry publish fails (or, before the guard existed, silently published a stale record — v3.3.0 through v3.13.1 shipped with server.json still at 3.2.0).

History: this paragraph was first added by #298 to a flat .claude/skills/prepare-release.md that duplicated this file, and was lost when #321 deleted the duplicate. The skill lives only at .claude/skills/prepare-release/SKILL.md — never recreate the flat file.

8b. Update plugin version files (if plugin content changed)

Skip this step if no plugin files changed in Step 4d.

Read the current plugin version from claude-plugins/task-orchestrator/.claude-plugin/plugin.json (already retrieved in Step 4d). Calculate the new version using the plugin bump level from Step 4d.

Update both files with the new version:

1. claude-plugins/task-orchestrator/.claude-plugin/plugin.json — update the version field
2. .claude-plugin/marketplace.json — update plugins[name="task-orchestrator"].version

Also update the version table in claude-plugins/CLAUDE.md:

• Find the row for task-orchestrator and replace the version number

Stage the three files (in addition to version.properties):

git add claude-plugins/task-orchestrator/.claude-plugin/plugin.json \
        .claude-plugin/marketplace.json \
        claude-plugins/CLAUDE.md

8c. Insert new section into CHANGELOG.md

Read CHANGELOG.md. Feature PRs accumulate entries under a ## [Unreleased] section at the top of the file; check whether one exists before writing anything.

If ## [Unreleased] exists: rename that header in place to ## [X.Y.Z] - YYYY-MM-DD and fold your synthesized bullets from Step 4 into its existing ### Added / ### Changed / ### Fixed subsections (create a subsection only if it is missing). Keep every existing bullet — they are the per-PR record — and add only what Step 4 found missing. Do not leave an empty [Unreleased] section behind; the next feature PR recreates it. Match each merged PR in git log <LAST_TAG>..HEAD to a bullet by the behaviour it describes (per-PR bullets usually cite no PR number) — merged PRs with no bullet are the gaps to fill, except a PR whose body states Changelog: none (<why>), which is intentionally bullet-less (the September 2026 release prep found three bug-wave PRs entirely absent).

If no ## [Unreleased] section exists: find the first ## [ versioned entry (after the header). Insert the new section immediately above it, with a trailing --- separator and a blank line:

## [X.Y.Z] - YYYY-MM-DD

### Added
- bullet 1
- bullet 2

---

## [previous version] ...

Do not modify any existing entries below the new section.

If plugin content changed (Step 4d), add under the appropriate section:

• Bumped plugin version to X.Y.Z (<reason>)

8d. Stage, commit, and push

Plugin-only release (plugin files already staged from 8b):

git add CHANGELOG.md
git status   # confirm only plugin version files + changelog are staged
git commit -m "release: bump to vX.Y.Z — plugin vA.B.C"
git push origin release/vX.Y.Z

Server-only release:

git add version.properties server.json CHANGELOG.md
git status   # confirm only expected files are staged
git commit -m "release: bump to vX.Y.Z"
git push origin release/vX.Y.Z

Both release (plugin files already staged from 8b):

git add version.properties server.json CHANGELOG.md
git status   # confirm expected files are staged
git commit -m "release: bump to vX.Y.Z"
git push origin release/vX.Y.Z