release

1. Prepare the branch

Start from a branch whose changes are finished. Every step below runs against that branch's committed tree, never against uncommitted edits.

1. Run git fetch origin and rebase the branch onto origin/main.
2. Commit any README, manifest or docs text this change made stale.
3. Decide whether the change reaches anyone who installs the plugin. A change confined to .claude/ or to documentation does not, and carries no version: skip steps 4 to 6 and go to section 2.
4. Compute the bump against origin/main HEAD: a removal or rename is major, an addition is minor, a fix is patch. Show the user the computed bump; the user rules the actual one.
5. Confirm the ruled version is unused: it appears in no CHANGELOG heading on origin/main, and no existing git tag matches it.
6. Commit the version in .claude-plugin/plugin.json and the new CHANGELOG entry.

2. Run the checks

Run checks 1 to 4 against the branch's committed tree and record each result.

1. Tests. Run git branch -f main origin/main, then run tests/.venv/bin/python tests/run.py --changed --runtime claude-code --record. It runs the offline tests, then the model tests covering every changed file. When it writes tests/releases/<version>/, commit that folder. Any failed case is a failed check: fix the cause, then record again; the attempt count it prints goes in the pull request. When it refuses because the version is unchanged, the change needs a version: return to step 4 of section 1.
2. CI, locally. Run PYTHON=tests/.venv/bin/python .github/validate.sh, the script the validate job runs on every pull request. It must exit 0. Its last step is the release gate: it fails when the recording from check 1 is missing, failed, or does not match a covered file's current content.
3. Manifests. List agents/, skills/ and workflows/ from disk and diff them against .claude-plugin/plugin.json and .claude-plugin/marketplace.json. Grep the repo for by-name references to anything added, renamed or removed in this release.
4. Changelog. Skip this when the change carries no version. Otherwise the new entry is present and follows the style of the entries above it.
5. If origin/main moved while you were working, rebase onto it and run these checks and the review again against the new head commit. Check 1 records again only when check 2's gate fails.

3. Get it cleared

This skill sits in .claude/skills/release/ and counts as running the checks, so a change to it needs a reviewer.

When the table says a reviewer is required, dispatch one independent reviewer holding the diff, the check results from section 2, and the table above. When check 1 wrote tests/releases/<version>/, the reviewer also confirms its manifest.json matches the run report at the tests/results/ path the manifest names. The reviewer must have no ability to edit the repository, and whoever authored the release never clears it.

Ask for one verdict: CLEAR or BLOCKED, with findings, naming the exact head commit it covers. When the release changes a frontmatter description, the reviewer also rules on whether the new wording routes the way the change intends.

BLOCKED sends the work back. After a fix, the next verdict names the new head commit.

4. Open the pull request

1. Push the branch to origin.
2. Open or update the pull request against main. The body carries the verdict and the commit it names, every check from section 2 with its result, and the path to tests/releases/<version>/ when check 1 wrote one.
3. Stop there. Never merge — the user merges, always.
4. Tell the user, when handing over: merge only while the verdict names the pull request's current head commit. A force-push replaces that commit and voids the verdict.

5. Publish

Runs after the user merges, never before: a tag belongs on a merge commit. Skip this section when the change carries no version — there is nothing to tag, and nothing new for anyone to install.

1. Pin the merge commit. Read it with gh pr view <number> --json mergeCommit. Check out main, pull, and confirm that commit is on it. Tag that SHA. Never tag local HEAD.
2. Tag it vX.Y.Z and push the tag.
3. Publish to every target in the table below.
4. Confirm the pull request's validate check passed on the head commit that was merged, and that main's branch protection requires branches to be up to date (required_status_checks.strict is true). If it is not, the merged tree is untested: run .github/validate.sh on the merge commit and report the result.
5. Comment on the merged pull request with the tag, each target's proof, and the CI result.

Adding a marketplace adds a row. No step above it changes.

When claude plugin tag --push refuses: a tag already on this commit is the end state you wanted, so record it and carry on. A dirty tree gets committed or stashed, never discarded, and if the changes are not yours, hand back to the user. A version disagreement between the manifests is a failure — stop and report it. A tag created but not pushed is not done: run the git push it prints.

If a published release breaks users

Revert it on a fresh branch, then run this procedure again as a patch release. Never revert a revert — fix forward instead.

Never

• Report a release as done while a check is unrun and unmentioned. A check that cannot run here is named in the pull request, with the reason.
• Publish half of a multi-part change. Stage every part on one branch until the whole change is ready.
• Narrow .github/workflows/validate.yml to selected paths, or delete it while pull requests still require it.
• Add a step to this file without removing one.