Release Skill for Claude

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:

| In the entry | Verdict |

|---|---|

| What changed, who it affects, what to do | Keep |

| A pointer to paad-help or README | Keep |

| How the feature works internally — phases, agents, gates | Cut |

| Why the design is right, or what was rejected | Cut |

| Testing evidence, run counts, measured before/after | Cut |

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:

| Change | Bump |

|---|---|

| A new skill, or new user-facing behavior in an existing one | MINOR |

| Wording, digraph, or bug fixes only | PATCH |

| A renamed or removed skill | breaking — say so explicitly |

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:

• plugins/paad overwritten wholesale by promotion's rsync — the release's

actual payload, and the largest of the three.

• The changelog rolled into a dated section, with a fresh [Unreleased].
• 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:

• /plugin → Installed → paad → Update now
• Restart Claude Code
• 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.