/prepare-release

name: prepare-release
description: "End-to-end release automation — reads commits since last tag, infers semver bump, drafts changelog, creates release PR, merges it, waits for CI green, tags, and monitors the Docker build to completion. Use when the user says: prepare release, cut a release, bump version, create release PR, ship a new version, tag a release, deploy new version, or when all feature PRs are merged and it is time to release."
disable-model-invocation: true

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:

| Condition | Plugin Bump | |-----------|-------------| | Breaking change to skill interface, hook behavior, or orchestration context contract (including removing a shipped component) | **major** | | New skill, new hook, new orchestration component added | **minor** | | Content fixes, wording, skill adjustments, script tweaks | **patch** |

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:

| Condition | Bump | |-----------|------| | Any breaking API change (removed tool, renamed/removed required parameter, incompatible response schema) | **major** | | New tool, new capability on existing tool, new config option, new query parameter | **minor** | | Bug fix, performance improvement, docs only, internal refactor with no API change | **patch** |

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

-