{"id":"release","name":"release","summary":"CONTRIBUTOR TOOL - プラグインリリースをカット:バージョンplugin.jsonアップ、CHANGELOGの最終化、必要に応じてREADMEの更新、make ciのゲート、コミット、vx.y.zタグ付け、GitHubリリースの作成。","body":"# Plugin Release\n\nCuts a versioned release of the Elixir/Phoenix plugin. Drives the full\nchecklist from `CLAUDE.md` (Release + Versioning) so every release is\nconsistent. **Contributor tooling — not shipped in the plugin.**\n\n## Iron Laws — Never Violate These\n\n1. **NEVER release on a red `make ci`** — the gate runs BEFORE committing. No green, no release.\n2. **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`.\n3. **THREE NUMBERS MUST MATCH** — `plugin.json` version == CHANGELOG heading == git tag (`vX.Y.Z`). Verify before pushing.\n4. **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.\n5. **USERS ONLY UPDATE ON A `plugin.json` BUMP** — never ship CHANGELOG/code changes without bumping the version, or installed users get nothing (cache).\n6. **ALWAYS leave a fresh empty `## [Unreleased]`** — one `[Unreleased]` becomes one version heading; re-add an empty one on top.\n7. **NEVER force-push** — `git push --force` is hook-blocked here. If history needs rewriting, the user runs it via `!`.\n8. **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).\n9. **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).\n\n## Step 0: Preconditions\n\n- On `main`, working tree clean except intended release files. If feature work is uncommitted, commit it first.\n- Determine version. Run `git describe --tags --abbrev=0` FIRST — the last\n  released tag is the bump base, NOT `plugin.json` (which may carry an\n  unreleased phased bump). If `plugin.json` is already ahead of the tag,\n  apply the consolidation check below before picking a number.\n- Read current `plugins/elixir-phoenix/.claude-plugin/plugin.json`. Pick bump from `## [Unreleased]` contents:\n  - **MAJOR** — breaking change (removed command, workflow redesign)\n  - **MINOR** — new skill / agent / command / hook\n  - **PATCH** — bug fix, doc/reference update, description tweak\n- **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.\n\n## Step 1: Bump the version — five files by hand, two generated\n\nA partial bump does not just cost users the update; it fails\n`scripts/tests/test_codex.py`, which asserts the Codex manifest matches canonical.\n\nSet `\"version\"` to `X.Y.Z` in:\n\n1. `plugins/elixir-phoenix/.claude-plugin/plugin.json` — canonical\n2. `plugins/ecto/.claude-plugin/plugin.json`\n3. `plugins/lv/.claude-plugin/plugin.json`\n4. `package.json` — Pi package metadata, tracks the plugin version since v3.0.0\n5. `package-lock.json` — run `npm install --package-lock-only`, never hand-edit\n   (an unrelated dependency can share the old version string)\n\nThen regenerate the two templated manifests and bless their digests:\n\n```\nmake generated-skills-sync        # updates targets/codex + targets/pi manifests\nmake generated-skills-snapshots   # re-bless after reviewing the diff\n```\n\nConfirm every file agrees before moving on:\n\n```\ngrep -rn '\"version\"' plugins/*/.claude-plugin/plugin.json package.json \\\n  targets/codex/.codex-plugin/plugin.json targets/pi/package.json\n```\n\n(Often already bumped during the feature work — confirm it matches the target.)\n\n## Step 2: Finalize CHANGELOG\n\nIn `CHANGELOG.md`:\n\n1. Rename `## [Unreleased]` → `## [X.Y.Z] - YYYY-MM-DD` (today's date).\n2. Insert a fresh empty section on top (see `${CLAUDE_SKILL_DIR}/references/templates.md`).\n3. Optionally add a one-line summary under the new heading (past releases do).\n\n## Step 3: README + intro (only if needed)\n\n- Update `README.md` ONLY if counts/version callouts changed: skill count, agent\n  count (`grep -nE \"[0-9]+ (skills|agents|specialist)\" README.md`), or a version banner.\n  A pure doc/reference PATCH usually needs **no** README change — verify, don't assume.\n- Check `plugins/elixir-phoenix/skills/intro/references/tutorial-content.md` cheat sheet\n  if commands/skills/agents were added, removed, or renamed.\n\n## Step 4: Gate on `make ci`\n\nRun `make ci` (lint + test + validate + eval-all). **Must be green.** If lint trips on\nuntracked non-source dirs (e.g. `social/`, `.rtk/`), that is not a code failure — exclude\nthem, don't ship around real failures. See `${CLAUDE_SKILL_DIR}/references/templates.md`.\n\n## Step 5: Commit\n\n```\ngit add CHANGELOG.md plugins/elixir-phoenix/.claude-plugin/plugin.json   # + README if touched\ngit commit   # message below\n```\n\nCommit subject (matches history): `Release vX.Y.Z — <short summary>`\nEnd the message with the `Co-Authored-By` trailer (see `CLAUDE.md`).\n\n## Step 6: Tag\n\n```\ngit tag vX.Y.Z\n```\n\n## Step 7: CONFIRM, then publish (outward-facing)\n\nShow the user the pending commit, tag, and release notes. **On confirmation:**\n\n```\ngit push origin main\ngit push origin vX.Y.Z\ngh release create vX.Y.Z --title \"vX.Y.Z — <summary>\" --notes-file <changelog-section>\n```\n\nUse the new CHANGELOG section as release notes (extract it to a temp file or `--notes`),\nthen **prepend any upgrade warning** (Iron Law 9) and **append the docs footer** before\npublishing — a release body is read at the moment someone decides whether to install:\n\n```\n---\n\nDocs, install guides, and the runtime compatibility matrix: <https://phxagents.dev>\n```\n\nSee `${CLAUDE_SKILL_DIR}/references/templates.md` for the one-line `printf` that\nappends it to the extracted notes.\n\n## Step 8: Verify\n\n```\ngh release view vX.Y.Z\ngit describe --tags --abbrev=0    # should print vX.Y.Z\n```\n\nConfirm to the user: released, tag pushed, GitHub release live.\n\n## Reference\n\n- `${CLAUDE_SKILL_DIR}/references/templates.md` — CHANGELOG/release-notes templates, gate snippets, gotchas","author":"@oliver-kriska","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/.claude/skills/release","license":"MIT","category":"document","lang":"en","tokens":1579,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/templates.md","size":5134,"sha256":"a9177a5b772b3d709b1efdb30bc793daa7f5678b115e44719e39c53d06035327"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["phxagents.dev"]}}