Release

3. Cut it

Confirm you are on a branch, not main — make release refuses on main, but say so before running rather than after.

Cut the release branch from an up-to-date main. The old rule — release from the branch that carries the work — is retired, and CLAUDE.md says so: preview/ closed the leak it existed to avoid, so work merges to main unbumped and unpromoted and accumulates there until someone decides to ship.

Releasing from an older feature branch is now a hazard rather than a habit. make promote rsyncs this working tree's preview/paad, so a branch behind main silently omits everything merged since, and every check passes because the omitted work is not there to fail on. make release refuses when origin/main is not an ancestor of HEAD; git fetch origin first so that check is comparing against something current.

make release VERSION=X.Y.Z

That single command promotes preview/paad over plugins/paad and strips the preview markers, rolls the changelog with today's real date, opens a fresh [Unreleased], fixes both link refs, rewrites every version string in both trees, regenerates kiro_and_antigravity/ and pi/, and runs make test.

Promotion refuses on a dirty tree, so uncommitted work stops the release before it mutates anything. That covers uncommitted work only — it is not a general safety net, and everything below assumes a run that got past it.

If it fails, stop and report the failure. Do not hand-patch around it. A failing check at this point means either the release is not ready or a generator is wrong, and both need a decision from Ovid.

Report the state along with the failure, because it is not clean. A failure at make test leaves three mutations in place, and the first is the one that matters most:

1. plugins/paad overwritten wholesale by promotion's rsync — the release's actual payload, and the largest of the three.
2. The changelog rolled into a dated section, with a fresh [Unreleased].
3. Every version string bumped, in both trees.

Say that re-running make release will not work: it refuses on the now-dirty tree, and roll_changelog.py refuses a second time on a version that already has a section.

Do not offer make export && make test as the way forward for a failure that needs a SKILL.md edit. It cannot work. The fix has to land in preview/, make promote then refuses on the dirty tree, and make export regenerates from the unfixed plugins/ — so the only way that advice succeeds is the hand-edit of plugins/ this project forbids everywhere else. For that class, the way out is a reset, not a patch. It is available for a failure that touches nothing under preview/ — a stale export, say — where make export and a commit genuinely finish the job.

The way out is a reset, and git checkout -- . alone does not do it. Promotion brings across skills that exist only in preview/, and those arrive as untracked paths that git checkout does not touch — .gitignore covers nothing under plugins/, kiro_and_antigravity/ or pi/, so the operator sees a green git diff and concludes the rollback worked while an unreleased skill sits in the shipped tree, waiting for the next git add -A. Use both:

git checkout -- . && git clean -fd plugins/ kiro_and_antigravity/ pi/

Scoping git clean to those three is safe because all three are generated-only. Neither route is the hand-patching this step forbids — that means editing the generated output to make a check pass.

4. Read the payload, then show the work

git diff plugins/

That diff is the release's actual payload — everything preview/ accumulated since the last release, arriving in the shipped tree all at once — and this is the last moment to catch something unintended. Read it before anything else. Say what promotion did: which skills changed, which are new, and which --delete removed because they left preview/.

Then show the diff — at minimum the changelog section boundary and the version strings. Get sign-off, then commit:

git commit -a -m "release: paad X.Y.Z"

5. Merge and tag

Merge the branch into main and push. Ovid uses git-done; plain git checkout main && git merge --no-ff <branch> && git push works too.

Then, on main, after the merge is pushed:

make tag

It reads the version from plugin.json, refuses if you are not on a synced main, if the tree is dirty, if the changelog has no matching section, or if the tag already exists — then annotates and pushes.

The tag goes on the merge commit because that is the tree users receive. Never move a published tag; if the wrong commit got tagged, ask Ovid before doing anything about it.

6. Hand off the verification you cannot do

You cannot run this part — it happens in Ovid's Claude Code session. Tell him to:

1. /plugin → Installed → paad → Update now
2. Restart Claude Code
3. Run any skill and confirm the announce line reads vX.Y.Z

This is the cheapest way to catch a bump that never made it to main.

Step 1 refreshes the marketplace catalog itself before it checks for a new version. It is the panel action and nothing else — if the plugin never actually updated, the version check at step 3 reads the old version and reports a release that shipped fine as broken.

Then report what shipped: the version, the tag, the commit it points at, and a one-line summary of the changelog section.

What this skill does not do

• No GitHub Release. The tag is the record. Do not run gh release create unless Ovid asks.
• No [Unreleased] housekeeping. If a change is missing from the changelog, that is a separate commit before the release, not a silent addition during it.
• No version invention. Step 2 ends in a question, always.