/release

name: release
description: |
  CONTRIBUTOR TOOL - Cut a plugin release: bump plugin.json version, finalize
  CHANGELOG, update README if needed, gate on make ci, commit, tag vX.Y.Z, and
  create the GitHub release. Use when shipping a new plugin version. NOT distributed.
argument-hint: "[patch|minor|major] | [X.Y.Z]"
effort: medium

Plugin Release

Cuts a versioned release of the Elixir/Phoenix plugin. Drives the full checklist from `CLAUDE.md` (Release + Versioning) so every release is consistent. **Contributor tooling — not shipped in the plugin.**

Iron Laws — Never Violate These

1. **NEVER release on a red `make ci`** — the gate runs BEFORE committing. No green, no release. 2. **NEVER `claude plugin tag`** — this is a marketplace layout (`plugins/elixir-phoenix/.claude-plugin/plugin.json`, not repo root). Tag manually: `git tag vX.Y.Z`. 3. **THREE NUMBERS MUST MATCH** — `plugin.json` version == CHANGELOG heading == git tag (`vX.Y.Z`). Verify before pushing. 4. **CONFIRM BEFORE PUBLISHING** — pushing the tag and `gh release create` are outward-facing and hard to reverse. Stop and confirm with the user; show exactly what will be pushed/published first. 5. **USERS ONLY UPDATE ON A `plugin.json` BUMP** — never ship CHANGELOG/code changes without bumping the version, or installed users get nothing (cache). 6. **ALWAYS leave a fresh empty `## [Unreleased]`** — one `[Unreleased]` becomes one version heading; re-add an empty one on top. 7. **NEVER force-push** — `git push --force` is hook-blocked here. If history needs rewriting, the user runs it via `!`. 8. **EVERY release body links the docs site** — append the `https://phxagents.dev` footer. Releases are this project's one measured promotion lever (v3.0.1: 51 → 120 cloners in a day). 9. **UPGRADE-BREAKING RELEASES LEAD WITH THE WARNING** — if users must do anything beyond `/plugin update`, the release body opens with a `> [!WARNING]` block carrying the exact commands (see #135).

Step 0: Preconditions

• On `main`, working tree clean except intended release files. If feature work is uncommitted, commit it first.
• Determine version. Run `git describe --tags --abbrev=0` FIRST — the last

released tag is the bump base, NOT `plugin.json` (which may carry an unreleased phased bump). If `plugin.json` is already ahead of the tag, apply the consolidation check below before picking a number.

• Read current `plugins/elixir-phoenix/.claude-plugin/plugin.json`. Pick bump from `## [Unreleased]` contents:
• **MAJOR** — breaking change (removed command, workflow redesign)
• **MINOR** — new skill / agent / command / hook
• **PATCH** — bug fix, doc/reference update, description tweak
• **Consolidation check** (per memory): if several phased branch bumps never released, collapse to ONE bump from the last released tag — don't stack intermediate versions.

Step 1: Bump the version — five files by hand, two generated

A partial bump does not just cost users the update; it fails `scripts/tests/test_codex.py`, which asserts the Codex manifest matches canonical.

Set `"version"` to `X.Y.Z` in:

1. `plugins/elixir-phoenix/.claude-plugin/plugin.json` — canonical 2. `plugins/ecto/.claude-plugin/plugin.json` 3. `plugins/lv/.claude-plugin/plugin.json` 4. `package.json` — Pi package metadata, tracks the plugin version since v3.0.0 5. `package-lock.json` — run `npm install --package-lock-only`, never hand-edit (an unrelated dependency can share the old version string)

Then regenerate the two templated manifests and bless their digests:

make generated-skills-sync        # updates targets/codex + targets/pi manifests
make generated-skills-snapshots   # re-bless after reviewing the diff

Confirm every file agrees before moving on:

grep -rn '"version"' plugins/*/.claude-plugin/plugin.json package.json \
  targets/codex/.codex-plugin/plugin.json targets/pi/package.json

(Often already bumped during the feature work — confirm it matches the target.)

Step 2: Finalize CHANGELOG

In `CHANGELOG.md`:

1. Rename `## [Unreleased]` → `## [X.Y.Z] - YYYY-MM-DD` (today's date). 2. Insert a fresh empty section on top (see `${CLAUDE_SKILL_DIR}/references/templates.md`). 3. Optionally add a one-line summary under the new heading (past releases do).

Step 3: README + intro (only if needed)

• Update `README.md` ONLY if counts/version callouts changed: skill count, agent

count (`grep -nE "[0-9]+ (skills|agents|specialist)" README.md`), or a version banner. A pure doc/reference PATCH usually needs **no** README change — verify, don't assume.

• Check `plugins/elixir-phoenix/skills/intro/references/tutorial-content.md` cheat sheet

if commands/skills/agents were added, removed, or renamed.

Step 4: Gate on `make ci`

Run `make ci` (lint + test + validate + eval-all). **Must be green.** If lint trips on untracked non-source dirs (e.g. `social/`, `.rtk/`), that is not a code failure — exclude them, don't ship around real failures. See `${CLAUDE_SKILL_DIR}/references/templates.md`.

Step 5: Commit

git add CHANGELOG.md plugins/elixir-phoenix/.claude-plugin/plugin.json   # + README if touched
git commit   # message below

Commit subject (matches history): `Release vX.Y.Z — <short summary>` End the message with the `Co-Authored-By` trailer (see `CLAUDE.md`).

Step 6: Tag

git tag vX.Y.Z

Step 7: CONFIRM, then publish (outward-facing)

Show the user the pending commit, tag, and release notes. **On confirmation:**

git push origin main
git push origin vX.Y.Z
gh release create vX.Y.Z --title "vX.Y.Z — <summary>" --notes-file <changelog-section>

Use the new CHANGELOG section as release notes (extract it to a temp file or `--notes`), then **prepend any upgrade warning** (Iron Law 9) and **append the docs footer** before publishing — a release body is read at the moment someone decides whether to install:

---

Docs, install guides, and the runtime compatibility matrix: <https://phxagents.dev>