release · git:20261110.b2430ff · 2026-11-10 · sha256 c72e0788dec66cff

release git:20261110.b2430ffA

Immutable. This exact content never changes and is served at /api/v1/blob/c72e0788dec66cff.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_z3bcnbgejtbbdshg/c72e0788dec66cff75df5d1e0b90a728312800cca3a36bdc9dcfe420d3534516.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 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. Tag the commit that the merge put on the default branch as `vX.Y.Z`, and push the tag.
4. Watch the Release workflow (`.github/workflows/release.yml`). The tag starts it: it verifies the tag, runs every check, and creates the GitHub release with that version's `CHANGELOG.md` section as its notes.

Only a pushed 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. Tag right after the merge.

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 step 2: 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.

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/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 step 6. When it prints `closed without merge`, stop.

## 6. Tag the merge commit

Tag the commit that the PR's merge put on the default branch, `gh pr view N --json mergeCommit --jq .mergeCommit.oid`. Never tag the branch's head: another PR can land right after this one, and it must not be released.

```bash
git fetch origin
scripts/verify-release.py vX.Y.Z <merge commit> origin/main
git tag -a vX.Y.Z <merge commit> -m "antithesis plugin X.Y.Z"
git push origin refs/tags/vX.Y.Z
```

The script 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. If it fails, tell the user and stop. Don't push the tag.

## 7. Watch the release

Find the Release run for the tag with `gh run list --workflow release.yml --commit <merge commit> --json databaseId,headBranch,status`. It can take a few seconds to appear.

Watch it 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 it 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 its 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. Never move or delete a pushed tag without asking the user.