/release

name: release
description: Cut a paad release — pick the semver bump from what is in [Unreleased], run make release, merge, tag, and verify the published plugin
metadata:
  internal: true

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];
    "Draft release notes, get sign-off" [shape=box];
    "gh release create" [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" -> "Draft release notes, get sign-off";
    "Draft release notes, get sign-off" -> "gh release create";
    "gh release create" -> "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 sh