release

Release

Bump version, write changelog, commit, and push for a single plugin in the monorepo. The changelog entry is critical because the upgrade skill (skills/hermit-evolve/SKILL.md) reads it to know what to tell hermits during /hermitd:hermit-evolve.

Usage

/release <plugin-slug> — release the plugin at plugins/<plugin-slug>/.

Examples:

• /release hermitd — release the core plugin
• /release hermitd-dev — release the dev hermit
• /release hermitd-homeassistant — release the HA hermit
• /release hermitd-laravel-forge — release the Laravel Forge hermit

If invoked without a slug, list all plugins/<name>/ directories that contain .claude-plugin/plugin.json and ask the operator which one via AskUserQuestion before proceeding.

Steps

0. Identify target plugin

Resolve the plugin slug:

• If the user passed <slug> as argument, use that.
• Otherwise, glob plugins/*/.claude-plugin/plugin.json, collect the directory names, and ask via AskUserQuestion: "Which plugin to release?" with one option per slug.

Validate plugins/<slug>/.claude-plugin/plugin.json exists. If it does not, abort: Plugin 'plugins/<slug>/' not found. Suggest the available slugs.

Throughout the rest of this skill, $PLUGIN_DIR refers to plugins/<slug>/.

1. Pre-release validation

Run before anything else. Abort the release if any step fails.

1. Run the native plugin validator (CLI form):

   claude plugin validate plugins/<slug> 2>&1
   

   Abort on any error.

2. Run test suites for the target plugin. Detect the convention and dispatch:

   • If plugins/<slug>/tests/run-all.sh exists (bash entrypoint, used by dev/fitness/scribe/forge):

     bash plugins/<slug>/tests/run-all.sh 2>&1
     

   • Else if any plugins/<slug>/tests/*.test.ts exists (bun entrypoint, used by core/HA):

     cd plugins/<slug> && bun test 2>&1
     

   • Else if a plugins/<slug>/tests/ dir exists but neither marker matched: abort the release with Plugin '<slug>' has a tests/ dir but no recognized convention (run-all.sh or *.test.ts) — fix the dispatch before releasing. Do not silently skip.
   • Else (no tests/ dir at all): skip this step and note it in the release report.

   If any test fails, stop and fix before releasing.

3. Run the plugin-validator agent in release mode (plugin-validator <slug> release) to cross-reference plugin integrity. Pass it the plugin slug explicitly so it knows which plugin to audit:

   • Skills referenced in the plugin README or AGENTS.md match actual plugins/<slug>/skills/ directories
   • Agents referenced in the plugin README or AGENTS.md match actual plugins/<slug>/agents/ files
   • Hook scripts referenced in plugins/<slug>/hooks/hooks.json exist in plugins/<slug>/scripts/
   • State-template JSON files parse correctly
   • config.json.template keys are in sync with DEFAULT_CONFIG in plugins/<slug>/scripts/hermitd-start.ts (core only)

If the auditor reports any FAIL, fix before proceeding. WARNs are acceptable if justified. Stale-reference detection-and-fix is consolidated into Step 4 below.

1.5. Refresh the knowledge graph

The repo carries graphify knowledge graphs (all gitignored): a root monorepo graph at graphify-out/ and one per-plugin graph at plugins/<slug>/graphify-out/. Refresh both so they reflect the code that's shipping: the root graph (covers the whole monorepo, including this plugin's code) and this plugin's own graph. /release is single-plugin, so only the target plugin's per-plugin graph is refreshed here, not the other siblings'. This runs before the fast-path branch in Step 2, so it fires on both the normal and already-bumped paths, always before either push.

ROOT="$(git rev-parse --show-toplevel)"
if command -v graphify >/dev/null; then
  # Root monorepo graph
  [ -f "$ROOT/graphify-out/graph.json" ] && (cd "$ROOT" && graphify update .)
  # This plugin's own graph (single-plugin scope; "if exists")
  [ -f "$ROOT/plugins/<slug>/graphify-out/graph.json" ] && (cd "$ROOT" && graphify update plugins/<slug>)
fi

AST-only, no API cost. Each update is guarded by its graph.json existing, so it skips silently on checkouts where graphify isn't set up. Both graph dirs are gitignored, so this never affects release staging or the Step 6 git status check. If an update errors, warn and continue: a stale graph must not block a release.

2. Determine version bump

Already-bumped fast-path (two-phase release flow): Find the most recent tag for this plugin:

git tag --list "<slug>--v*" | sort -V | tail -1

Compare its version to plugin.json. If plugin.json is already ahead (e.g. tag is dev-hermit--v0.2.0, plugin.json says 0.3.0), the version was bumped on a plugin branch that has since merged to main. Skip steps 2–7 entirely — the CHANGELOG, version files, and commit are already done. Jump directly to step 8.

Normal path: Read plugins/<slug>/.claude-plugin/plugin.json for the current version and plugins/<slug>/CHANGELOG.md for recent entries.

Review the uncommitted or recently committed changes (git diff and/or git log since the last <slug>--v<version> tag).

Decide the bump level:

• Patch (0.0.X) — bug fixes, behavioral changes via updated instructions, small additions
• Minor (0.X.0) — new features, new skills, structural changes, breaking config migrations
• Major (X.0.0) — only if the user explicitly asks

Present the suggested version and rationale. Wait for confirmation before proceeding.

3. Write the changelog entry

Prepend a new entry to plugins/<slug>/CHANGELOG.md immediately after the # Changelog header, before the previous version entry. If a [Unreleased] section already exists, rename it to [X.Y.Z] - YYYY-MM-DD instead of prepending a new one — the entry has been accumulating during development.

Docs-only double-check (do this before promoting/writing the entry). Read every narrative bullet about to ship in this version and confirm each describes a real code/behavior change an operator experiences. Drop any bullet whose only change is documentation (README, docs/, instruction files, or code comments), including bullets that pair a docs correction onto an otherwise-code entry (keep the code half, cut the docs half). Docs corrections belong in the commit message and PR description, never the CHANGELOG. Cross-check against the actual diff: git diff <last-tag>..HEAD -- plugins/<slug>; if a bullet's only backing changes are .md or comment edits, it should not be in the changelog. This mirrors the root AGENTS.md §Commits and releases rule.

Format:

## [X.Y.Z] - YYYY-MM-DD

### Added / Changed / Fixed
(use whichever sections apply — skip empty ones)

- Plain sentence-case line describing the change; the header carries the category. Backticks for `commands`, `paths`, `--flags`.

### Upgrade Instructions

Run `/hermitd:hermit-evolve`. The evolve skill handles:

1. **Imperative step title** — what to do, in one sentence.

No `config.json` changes required.

Template constraints (enforce these):

1. Narrative bullets (Added / Changed / Fixed): canonical format lives in root AGENTS.md §Commits and releases; enforce it here: a plain sentence-case line under the category header, no **component:** prefix and no leading Fixed/Added verb (the header carries the category). Backticks for commands/paths/flags. Target 1–2 lines. If a bullet wants to grow longer, the surplus belongs in the PR description, not here.

   • Do NOT list internal refactors, helper extractions, test scaffolding, or renamed variables — those are visible in git diff.
   • Recovery procedures, migration shell snippets, and breaking-change steps belong in ### Upgrade Instructions, never in the narrative bullet. Write a tight summary ("changed default X to Y") and let that section carry the imperative steps — hermit-evolve reads them step-by-step.

2. Upgrade Instructions — strict imperative block:

   • Every step starts with a verb (Add, Replace, Copy, Run, Delete, Refresh).
   • Each step is a single action. No "also do X, but only if Y, unless Z" run-ons — split into separate numbered steps.
   • No passive voice, no rationale clauses. If an operator needs to understand why, that belongs in the Changed bullet above, not here.
   • Include what hermit-evolve does NOT need to touch only if omission would cause it to act destructively. Otherwise silence.
   • Close with No config.json changes required. if true — it's the most common case and operators scan for it.

3. What belongs where:

   • Why it changed → Changed/Fixed bullet.
   • What evolve executes → Upgrade Instructions (imperative, numbered).
   • Behavior deltas that need no action but operators should know → one final line after the numbered list, prefixed **Note:**. Not a step.

The Upgrade Instructions section is the most important part. The evolve skill reads this to know what actions to take for each hermit. Non-imperative steps cause evolve to misparse or skip them.

4. Refresh references

For each new skill, agent, or hook added since the last release of this plugin, detect missing entries and add them in one pass:

• Plugin README component descriptions and any affected plugins/<slug>/AGENTS.md constraints (keep inventories out of instruction files)
• plugins/<slug>/docs/skills.md (if the doc exists)
• Hook descriptions in the plugin README or relevant docs if the hook surface area changed

Skip the step entirely if nothing was added. The plugin-validator (Step 1.3) covers structural integrity; this step is about narrative references.

5. Bump version in all locations

Update the version string in:

• plugins/<slug>/.claude-plugin/plugin.json → "version" field
• .claude-plugin/marketplace.json → find the entry in plugins[] where "name" == "<slug>" and update its "version" field. Other plugin entries are untouched.
• plugins/<slug>/README.md → version badge if present: both the img.shields.io URL slug (version-X.Y.Z-green.svg) and the alt text (Version X.Y.Z). Confirm with grep "version-" plugins/<slug>/README.md that the new version appears and the old one does not. Skip silently if the README has no version badge. (For hermitd, skip this direct edit — the sync block below re-derives the whole file from root, picking up the updated badge automatically.)
• If <slug> is hermitd: also update the root README.md badge — version-OLD-green.svg → version-NEW-green.svg and Version OLD → Version NEW. This is the only plugin whose version the root README tracks.

Sync plugin README from root (hermitd only): plugins/hermitd/README.md is a path-adjusted derivative of the root README.md. After updating version badges, re-derive it by applying these substitutions to the root README content:

In root README.md	In plugin README.md
href="LICENSE"	href="../../LICENSE"
[MIT](LICENSE)	[MIT](../../LICENSE)
href="plugins/hermitd/CHANGELOG.md"	href="CHANGELOG.md"
src="plugins/hermitd/assets/	src="assets/
](plugins/hermitd/docs/	](docs/
](plugins/hermitd-dev/	](../hermitd-dev/
](plugins/hermitd-homeassistant/	](../hermitd-homeassistant/
](plugins/hermitd-fitness/	](../hermitd-fitness/
](plugins/hermitd-laravel-forge/	](../hermitd-laravel-forge/

Write the result to plugins/hermitd/README.md.

After editing, verify the manifest and marketplace are in sync — the plugin manifest wins silently if they differ:

jq -r '.version' plugins/<slug>/.claude-plugin/plugin.json
jq -r --arg slug "<slug>" '.plugins[] | select(.name == $slug) | .version' .claude-plugin/marketplace.json

Both must print the same string. If they differ, fix .claude-plugin/marketplace.json before continuing.

6. Final validation

Steps 3–5 only edit Markdown and JSON, so re-running the test suite is unnecessary. Confirm:

jq -e . plugins/<slug>/.claude-plugin/plugin.json > /dev/null
jq -e . .claude-plugin/marketplace.json > /dev/null
git status --short

Both jq checks must succeed and git status must show only the files this release touched (CHANGELOG, plugin.json, marketplace.json, optional CLAUDE.md / README badge / state-templates updates). Any unexpected entry → investigate before committing.

7. Commit and push

Stage only the changed files (not git add -A). Commit with:

<slug> v<X.Y.Z>: One-line summary of the release

Push to origin.

8. Branch check before tagging

Run git branch --show-current and compare to main (or the repo's default branch from gh repo view --json defaultBranchRef -q .defaultBranchRef.name).

• On main/default branch → tag immediately (step 9).

• On any other branch (e.g. dev-hermit/v0.3.0) → stop. Do not tag yet. Tagging the branch tip creates a commit SHA that main never carries after a regular merge (and is outright wrong after squash/rebase), leaving the tag stranded on an orphan commit.

  Recommended path (default): open a PR, merge into main, then re-run /release <slug> from main. Step 2's already-bumped detection will skip straight to tagging.

  If the user explicitly wants to tag now despite the risk, offer that as a secondary option. Wait for their explicit choice before proceeding.

9. Tag and publish

The tag format is plugin-prefixed with double-dash separator: <slug>--v<X.Y.Z>. This is the format Claude Code's native dependency resolver requires to find matching versions for dependencies entries.

Run claude plugin tag --push from the plugin directory — it validates plugin contents, confirms plugin.json and marketplace.json versions agree, requires a clean working tree, and refuses if the tag already exists:

(cd plugins/<slug> && claude plugin tag --push)

Then create the GitHub release pointing to the new double-dash tag. Source the release notes from the CHANGELOG section we just wrote — --generate-notes would otherwise interleave commits from sibling-plugin releases that landed since the last core tag.

VERSION=$(jq -r '.version' plugins/<slug>/.claude-plugin/plugin.json)
TAG="<slug>--v$VERSION"
NOTES_FILE=$(mktemp)
awk -v ver="$VERSION" '
  $0 ~ "^## \\[" ver "\\]" {flag=1; next}
  /^## \[/ && flag {exit}
  flag {print}
' plugins/<slug>/CHANGELOG.md > "$NOTES_FILE"
[ ! -s "$NOTES_FILE" ] && { echo "CHANGELOG section for $VERSION not found in plugins/<slug>/CHANGELOG.md — fix and retry"; rm "$NOTES_FILE"; exit 1; }
gh release create "$TAG" --title "$TAG" --notes-file "$NOTES_FILE"
rm "$NOTES_FILE"

10. Report

Print the slug, the new version, the commit hash, the tag name, and a one-liner confirming it's pushed.