release · git:20261114.9e2b1ef · 2026-11-14 · sha256 d3adec36c29c5d5c
release git:20261114.9e2b1efA
Immutable. This exact content never changes and is served at /api/v1/blob/d3adec36c29c5d5c.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_z3bcnbgejtbbdshg/d3adec36c29c5d5c31b840a5d2e041df9b86967af6c0a44966b188bf0ea2549e.json
Then /plugin install release@markdownregistry-z3bcnbgejtbbdshg in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: release
description: Release the Antithesis plugin. Use when the user asks to "release the plugin", "cut a release", "bump the version", or gives a version, like "release plugin 0.2.0".
---
# Release the plugin
You drive a release end to end, and watch every step until it finishes:
1. Open a pull request, from a `release/vX.Y.Z` branch, that bumps the plugin's version and adds its notes to `CHANGELOG.md`, and watch its checks.
2. Wait while the user reviews the PR and merges it.
3. Watch the Tag release workflow (`.github/workflows/tag-release.yml`). The merge of a `release/` branch starts it: it tags the merge commit as `vX.Y.Z`, and runs the Release workflow (`.github/workflows/release.yml`) on the tag.
4. Watch the Release workflow. It verifies the tag, runs every check, and creates the GitHub release with that version's `CHANGELOG.md` section as its notes.
Only a tag makes a GitHub release. CI never does, whatever version the default branch is at.
Users install the plugin from the default branch, and Claude Code and Codex update it when its version changes. So merging the PR ships the version to every user, and the tag and release record it.
The Release PR workflow (`.github/workflows/release-pr.yml`) opens a release PR every weekday on its own, when CI passed on the default branch and the plugin changed since the last release. Claude picks the version and writes the notes as "Pick and check the version" and "Write the notes" say, in a job that can't write to the repository. Another job writes them to `CHANGELOG.md`, sets the version, and opens the PR. Started by hand, it takes an optional version, which may be a release candidate: Claude uses it, and the workflow releases even when nothing changed.
A release is `X.Y.Z`. A release candidate is `X.Y.Z-rc.N`, and follows the same steps: its PR bumps the default branch to the candidate, so every user gets it too, and its GitHub release is a pre-release. Below, `X.Y.Z` stands for the whole version, with its `-rc.N` for a candidate.
## 1. Pick and check the version
Get the current version from `plugins/antithesis/plugin.json`. If the user gave a version, strip any leading `v`. Otherwise, pick the next one once you've read the changes in "Write the notes": bump the minor version if any change is breaking, and the patch version otherwise. When the user asks for a release candidate, the next one after `X.Y.Z-rc.N` is `X.Y.Z-rc.N+1`, and the first is `-rc.1` of the version you'd pick. Releasing a candidate's `X.Y.Z` drops the suffix. Say which you picked and why in the PR, so the user can change it in review.
Before changing anything, check:
- The version is `MAJOR.MINOR.PATCH` or `MAJOR.MINOR.PATCH-rc.N`, and higher than the current version. A candidate is lower than its release: `0.1.0-rc.2` is above `0.1.0-rc.1` and `0.0.9`, and below `0.1.0`.
- `git tag -l vX.Y.Z` and `gh release view vX.Y.Z` find nothing.
- `git status --porcelain` is empty, and you're on the default branch, up to date with the remote.
- No release PR is open: `gh pr list --state open --limit 1000 --json url,headRefName,isCrossRepository --jq '.[] | select((.headRefName | startswith("release/")) and (.isCrossRepository | not)) | .url'` prints nothing.
If a check fails, tell the user and stop.
## 2. Write the notes
Write the notes from what changed, not from PR descriptions. A description can show an approach that changed in review, and a later PR can change the behavior again.
Find the previous release, skipping candidates: `git fetch --tags && git tag -l 'v[0-9]*' --sort=-v:refname | grep -v -- -rc | head -1`. Every candidate's notes, and the release's, cover everything since that release. Read what users get from the plugin since then:
- What the skill tells agents to do: `git diff vPREV..HEAD -- plugins/antithesis/skills/`.
- How users install it and what it needs: `git diff vPREV..HEAD -- plugins/antithesis/*.json plugins/antithesis/.*-plugin/ .claude-plugin/ .agents/plugins/ README.md docs/`.
Then list the commits with `git log --oneline vPREV..HEAD`. When the diffs don't explain a change, read its commit with `git show <sha>`. Use the PR number, `(#N)` at the end of a squash-merged subject, only to link the entry.
If there is no previous release, write a short summary of what the plugin does instead: its modules, and the platforms it installs on.
Write the notes at the level of modules and what the agent does differently:
- One entry per module or feature. Merge the PRs that changed the same thing into one entry.
- Leave out rewording that doesn't change what the agent does, and internal changes: CI, scripts, this skill, contributor docs.
- Write each entry as the net change since the previous release. A module that's new in this release is one entry, not the PRs that built it. When one change reverses another, leave out both.
- Put breaking changes first, then the rest, largest first. A change is breaking if something that worked with the previous release now fails or needs the user to act: a renamed module or command, a new requirement on the user's setup, a changed harness layout that existing workloads need to adopt. Start each with `**Breaking**:` and say what to do instead.
- Link every PR that contributes to an entry, under the repository's URL from `gh repo view --json url -q .url`, e.g. `([#7](https://github.com/antithesishq/antithesis-plugin/pull/7))`.
Put the notes in `CHANGELOG.md` under `# Version X.Y.Z (YYYY-MM-DD)` with today's date, above every other version, and below the HTML comments at the top of the file.
`CHANGELOG.md` holds at most one candidate's section, at the top. A new candidate replaces the previous candidate's section, heading and notes, with its own. A release replaces it with the release's section. `check:changelog` fails otherwise. Then check that `scripts/changelog-section.py X.Y.Z` prints them: the release workflow uses the same script.
## 3. Bump the version
Run `scripts/set-version.py X.Y.Z`, then `scripts/set-version.py --check`. This sets the version in every manifest, and in the skill's `SKILL.md`, where agents read it.
## 4. Open the PR
```bash
git switch -c release/vX.Y.Z
git add CHANGELOG.md plugins/antithesis/plugin.json plugins/antithesis/.claude-plugin/plugin.json plugins/antithesis/.devin-plugin/plugin.json plugins/antithesis/.cursor-plugin/plugin.json plugins/antithesis/skills/antithesis/SKILL.md
git commit -m "Release antithesis plugin X.Y.Z"
git push -u origin release/vX.Y.Z
gh pr create --title "Release antithesis plugin X.Y.Z" --body "<body>"
```
If `git status` shows any other change, stop: the release commit holds only the notes and the version.
In the body, say which version this releases and which release the notes start from. If you picked the version yourself, say why. Say that merging doesn't create the release: you tag the merge commit once it lands.
Don't merge the PR yourself. Give the user the PR's URL.
## 5. Watch the PR until it merges
Invoke the `watch-pr` skill with the PR's number. It runs the watcher, and says how to read each event, whose comments to act on, and how to reply. The user asks for changes in comments, and review bots comment too.
For a release PR, also:
- A fix that isn't the notes or the version, like a lint rule or a script, can go in the release PR. Say why in the PR body.
- If someone who can write to the repository asks to abort the release, close the PR and stop.
- When the watcher prints `merged`, go on to "Watch the tag and the release". When it prints `closed without merge`, stop.
## 6. Watch the tag and the release
Get the commit that the PR's merge put on the default branch, `gh pr view N --json mergeCommit --jq .mergeCommit.oid`. Tag release tags that commit, never the branch's head: another PR can land right after this one, and it must not be released. Before it tags, it runs `scripts/verify-release.py vX.Y.Z <merge commit> origin/main`, which reads the files at the commit, and checks that it is on the default branch, that every manifest has the version, that `CHANGELOG.md` has its notes, and that the tag isn't taken or released.
Find each run with `gh run list --workflow <file> --commit <commit> --json databaseId,headBranch,status`. Tag release runs on the PR's merge, so GitHub records it under the PR's head commit, `gh pr view N --json headRefOid --jq .headRefOid`. Release runs on the tag, so it's under the merge commit, with the tag as its `headBranch`. Each can take a few seconds to appear.
Watch a run with `gh api`, not `gh run watch` or `gh run view`. They fetch jobs from GitHub's absolute `jobs_url`, which bypasses a proxy set as gh's host. Every 30 seconds or so, check:
- the run: `gh api repos/{owner}/{repo}/actions/runs/<id> --jq '.status, .conclusion'`, until `status` is `completed`
- its jobs: `gh api 'repos/{owner}/{repo}/actions/runs/<id>/jobs?per_page=100' --jq '.jobs[] | [.id, .name, .status, .conclusion] | @tsv'`
When Release passes, check that `targetCommitish` from `gh release view vX.Y.Z --json url,targetCommitish,isPrerelease` is the merge commit, and that it's a pre-release exactly when the version is a candidate. Give the user the release's URL.
If a run's conclusion isn't `success`, read each failed job's log with `gh api --allow-escape-sequences repos/{owner}/{repo}/actions/jobs/<job id>/logs | sed 's/\x1b\[[0-9;]*[A-Za-z]//g' | tail -100` (gh refuses to print the log's color codes without the flag, and `sed` strips them), and tell the user what failed. A check that failed for a transient reason, like a link that was briefly down, can be rerun with `gh api -X POST repos/{owner}/{repo}/actions/runs/<id>/rerun-failed-jobs`. Then watch the run again. When Tag release failed, don't tag the commit yourself unless the user asks. Never move or delete a pushed tag without asking the user.