/prepare-release

name: prepare-release
description: >
  Prepare a new touchdesigner-mcp release: inspect the unreleased diff since the
  last tag, decide independently how the MCP **package version** and the **MCP
  API version** each move (the API axis stays put unless the server/API contract
  changed), write the CHANGELOG entry, bump the six version-bearing files, commit,
  and open the development → main release PR. Use when cutting a release, bumping
  the version, updating the CHANGELOG for a release, or when asked to "release",
  "prepare a release", or "cut vX.Y.Z". Pairs with `release-test-audit` (verify
  integration-test coverage of the release diff first) and the `release-manager`
  agent that orchestrates both.

Prepare release

Cut a release for **touchdesigner-mcp**. The job has one non-obvious core: the repo has **two independent version axes**, and `npm version` bumps both — the API axis must be reverted when the release has no server/API contract change. Read [references/version-policy.md](references/version-policy.md) before touching any version file.

Land the release via a `development → main` PR (historical flow; PR title is the version, e.g. `v1.4.13`). Do **not** merge or publish — stop at the opened PR.

Step 0 — preflight

git fetch --tags
LAST_TAG=$(git describe --tags --abbrev=0)   # e.g. v1.4.12
git log "$LAST_TAG"..HEAD --oneline           # the unreleased commits
git diff "$LAST_TAG"..HEAD --stat             # the unreleased surfaces

If the range is empty, there is nothing to release — stop and say so.

Step 1 — audit integration-test coverage first

Before writing anything, confirm the release diff is adequately tested. Invoke the **`release-test-audit`** skill: it walks the API/MCP surface changes in the unreleased range and reports coverage gaps. Resolve (or consciously waive) gaps via the `integration-test-guard` skill **before** cutting the release. Don't bump a release with an untested API/MCP surface change.

Step 2 — decide the two version axes

Read [references/version-policy.md](references/version-policy.md) and decide, from the Step 0 diff:

• **Package version** — always bumps. Pick patch / minor / major from the change

set (features → minor, fixes/deps → patch, breaking → major).

• **MCP API version** — bumps **only** if the diff changes the server/API

contract (`src/api/**`, contract-changing `src/features/tools/**` or `td/modules/mcp/**`, `src/server/**`, `src/tdClient/**`, `src/transport/**`). Otherwise it **stays put** and must be reverted after `npm version`.

State the decision out loud before proceeding — it drives both the bump and the CHANGELOG wording.

Step 3 — write the CHANGELOG entry

Follow [references/changelog-format.md](references/changelog-format.md). Group the Step 0 commits into Keep-a-Changelog sections, write impact-first prose, reference the merged PRs, and include the mandatory "Released version … across …" bullet whose last sentence records the Step 2 API-axis decision.

If the file already opens with an `## [Unreleased]` block (feature PRs may land their entries there ahead of a release), rename that heading to `## [X.Y.Z] - YYYY-MM-DD` and fold the new bullets into it — never leave it behind as a second block under the released version.

Two sections bracket the entry (both defined in changelog-format.md):

• **`### Upgrade Notes` first** — required whenever the API axis moves, and

whenever the release otherwise changes what existing users experience. Derive it from the Node-side vs TD-side split of the diff.

• **`### Contributors` last** — credit every human contributor, cross-checking

commit authors, `Co-Authored-By` trailers, and PR authors (squash merges can hide a contributor behind the maintainer's commit email).

Step 4 — bump the version-bearing files

Per [references/version-policy.md](references/version-policy.md):

npm run build:mcpb                       # must precede version:mcp (it hashes the bundle)
npm version <patch|minor|major> --no-git-tag-version

**If the API axis stays put** (Step 2), revert the three API files and the `expectedApiVersion` field now:

git checkout HEAD -- src/api/index.yml td/modules/utils/version.py pyproject.toml
npm pkg set mcpCompatibility.expectedApiVersion=<OLD_API_VERSION>

Then verify the split is correct:

grep -H version package.json src/api/index.yml pyproject.toml
grep MCP_API_VERSION td/modules/utils/version.py
grep -A3 mcpCompatibility package.json
# package.json version = NEW package version; the API-axis files AND
# mcpCompatibility.expectedApiVersion = OLD API version (unless Step 2 bumped them)

> The `server.json` `fileSha256` will not match the CI-rebuilt release asset — > that mismatch is a known, expected issue. See version-policy.md.

Step 4b — the bundled `touchdesigner` plugin

The plugin is **not** one of the version-bearing files, and `npm version` does not touch it. It has two independent knobs; check both on every release.

**Every release — did the plugin's own tree change?**

git diff --stat "$LAST_TAG"..HEAD -- plugin/touchdesigner

If anything under `plugin/touchdesigner/` changed in the range, bump `version` in `plugin/touchdesigner/.claude-plugin/plugin.json`. That is the plugin's own semver axis: it follows the plugin's changes, not the npm version, and it moves on a PATCH release just as readily as on a MAJOR one. Marketplace consumers only see an update when it moves, so a skill, hook, or manifest fix shipped without a bump ships invisibly. It is the only hand-edited copy: the Claude marketplace entry deliberately carries no `version`, so this step cannot leave a stale one behind. Should one ever be added there, it has to move with this one — `tests/unit/pluginManifestSync.test.ts` compares them whenever the marketplace names a version, and would fail this release.

**MAJOR only — the server pin.** The plugin resolves the server from npm rather than fro