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>

See ${CLAUDE_SKILL_DIR}/references/templates.md for the one-line printf that appends it to the extracted notes.

Step 8: Verify

gh release view vX.Y.Z
git describe --tags --abbrev=0    # should print vX.Y.Z

Confirm to the user: released, tag pushed, GitHub release live.

Reference

• ${CLAUDE_SKILL_DIR}/references/templates.md — CHANGELOG/release-notes templates, gate snippets, gotchas