Release

Start

Announce: "Preparing a paad release…"

Read @CLAUDE.md.

make release and make tag own everything mechanical: the promotion of preview/paad into plugins/paad, the changelog roll, the version rewrite across every manifest and announce line in both trees, the export regeneration, the full check suite, and the annotated tag. This skill owns the parts a Makefile cannot decide — which number to bump to, whether a release is wanted at all, and whether the thing users install actually works afterwards.

Never hand-edit plugin.json, marketplace.json, package.json, a SKILL.md announce line, or the changelog's version headings and link refs. Those are generated. If the generated result is wrong, fix the generator.

Never hand-edit plugins/paad at all. It is written only by promotion. A hand edit there does not survive: make release opens with make promote, whose rsync -a --delete copies the pre-fix preview/paad straight over it. Nothing catches that — the tree is committed so the dirty guard passes, and the result is self-consistent so every check passes. The release ships and the changelog announces a fix that is not in it. Fixes go in preview/paad, hotfixes included.

digraph release {
    "Read [Unreleased]" [shape=box];
    "Anything there?" [shape=diamond];
    "STOP — ask whether a release is wanted" [shape=box, style=bold];
    "Entries within the length rule?" [shape=diamond];
    "STOP — trim first, as its own commit" [shape=box, style=bold];
    "Propose MAJOR/MINOR/PATCH with reasoning" [shape=box];
    "User confirms version?" [shape=diamond];
    "Every preview skill in README?" [shape=diamond];
    "STOP — add the README entry as its own commit" [shape=box, style=bold];
    "On a branch?" [shape=diamond];
    "Create release branch" [shape=box];
    "make release VERSION=X.Y.Z" [shape=box];
    "Passed?" [shape=diamond];
    "STOP — report the failure and the half-applied state" [shape=box, style=bold];
    "Read git diff plugins/ — the payload" [shape=box];
    "Show the diff, get sign-off" [shape=box];
    "Commit, merge to main, push" [shape=box];
    "make tag" [shape=box];
    "Hand off in-app verification" [shape=doublecircle];

    "Read [Unreleased]" -> "Anything there?";
    "Anything there?" -> "STOP — ask whether a release is wanted" [label="empty"];
    "Anything there?" -> "Entries within the length rule?" [label="entries"];
    "Entries within the length rule?" -> "STOP — trim first, as its own commit" [label="no"];
    "Entries within the length rule?" -> "Propose MAJOR/MINOR/PATCH with reasoning" [label="yes"];
    "Propose MAJOR/MINOR/PATCH with reasoning" -> "User confirms version?";
    "User confirms version?" -> "Propose MAJOR/MINOR/PATCH with reasoning" [label="no"];
    "User confirms version?" -> "Every preview skill in README?" [label="yes"];
    "Every preview skill in README?" -> "STOP — add the README entry as its own commit" [label="no"];
    "Every preview skill in README?" -> "On a branch?" [label="yes"];
    "On a branch?" -> "Create release branch" [label="on main"];
    "On a branch?" -> "make release VERSION=X.Y.Z" [label="on a branch"];
    "Create release branch" -> "make release VERSION=X.Y.Z";
    "make release VERSION=X.Y.Z" -> "Passed?";
    "Passed?" -> "STOP — report the failure and the half-applied state" [label="no"];
    "Passed?" -> "Read git diff plugins/ — the payload" [label="yes"];
    "Read git diff plugins/ — the payload" -> "Show the diff, get sign-off";
    "Show the diff, get sign-off" -> "Commit, merge to main, push";
    "Commit, merge to main, push" -> "make tag";
    "make tag" -> "Hand off in-app verification";
}

1. Read what is actually unreleased

Read the ## [Unreleased] section of CHANGELOG.md.

If it is empty, stop and ask. There is nothing to release. Do not invent a version to bump to, and do not go hunting through git log for things that should have been logged — an unrecorded change is a changelog bug to fix first, as its own commit, not something to sweep into a release.

1.5. Check the entries against the length rule

CLAUDE.md sets it: 1–3 lines per entry, at most 8 for a new skill, ending in a pointer to paad-help or README. Once this section rolls into a version heading it is published, and trimming it afterwards means editing released history. Catch it here.

Read each bullet and ask what it is doing:

The test from CLAUDE.md: if it explains a mechanism, it is in the wrong file. That material is worth keeping — it belongs in the commit message, in README, or in paad-help, all of which already exist. A changelog copy is a third copy that has to be hand-synced and drifts.

Sanity check the size:

awk '/^## \[/{if(n)print len" lines  "n; n=$0; len=0; next} {len++} END{print len" lines  "n}' CHANGELOG.md | head -5

A section running past ~40 lines for a normal release is the signal. Sections in this file's history run to 200 lines; those are the mistake, not the precedent.

If entries are too long, stop and say so. Trimming is its own commit before the release, exactly like a missing entry is — not a silent edit during it, and not something to fold into the release commit. Propose the shortened text, get sign-off, commit it, then start again at step 1.

2. Propose the version

Semver against what is in [Unreleased], not against how much work it felt like:

paad has stayed on 1.x. A breaking change still gets called out in the changelog even if the major does not move; raise it and let Ovid decide.

State your reasoning and the proposed number, then wait for confirmation. Do not proceed on a version you picked unilaterally.

Note for the experimental skills (agentic-dedup, test-roadmap): their arguments and output may change in any release including a patch, so a breaking change to one of them does not force a major.

2.5. Check README covers everything preview is about to ship

check-readme runs against the shipped tree, and promotion is what puts a preview-only skill there. So a skill that has been sitting in preview/ without a README entry passes every check until the release promotes it — and then fails make test at the very end of make release, with the rsync, the changelog roll and both trees' version strings already written, and make release unable to re-run against the dirty tree it just made.

make promote now runs check-readme TREE=preview/paad before its rsync, so this fails the release before anything is written rather than after. Run it up front anyway — knowing at step 2.5 costs a second, and finding out at step 3 means starting over:

make check-readme TREE=preview/paad

Anything listed, stop. Write the README entry as its own commit on this branch, then start again at step 1. It costs nothing there and merges with the release, so README never advertises a skill nobody can install. The same goes for a missing paad-help entry, though check-help runs per-tree and would already have caught that one.

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.