/release

name: release
description: Bump a plugin's version, write a detailed changelog entry for the upgrade skill to consume, and commit+push. Takes a plugin slug argument identifying which plugin under `plugins/` to release. Use this skill whenever the user says "release", "version bump", "cut a release", "changelog and push", or finishes a set of changes and wants to ship them. Also trigger when the user says "do the release thing" or asks to prepare changes for hermits to pick up.

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 in `plugins/<slug>/CLAUDE.md` match actual `plugins/<slug>/skills/` directories
• Agents in `plugins/<slug>/CLAUDE.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.

1.6. Reconcile the proposal queue

Skip this step entirely if `.claude/skills/stale-proposals/` doesn't exist (monorepo-internal; not present in every checkout).

Run `/stale-proposals` before deciding what's shipping in this release — closing anything this release already delivers keeps the release notes and the proposal queue honest at the same time. Dispatch a `general-purpose` subagent at **`model: "sonnet"`** to run `stale-proposals/SKILL.md`'s Steps 1–2b (collect the evidence bundle and match), then apply `SHIPPED-STRONG` verdicts per that skill's Step 3. This is an interactive release flow, so — unlike the unattended routine — `SHIPPED-WEAK` and `AGED` verdicts go through `AskUserQuestion` exactly as `stale-proposals/SKILL.md` Step 4 describes, not a queued channel ask.

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