release

# Release skill

This skill prepares a new tagged release of `corezoid-ai-plugin`. It runs through six phases in order. Do not skip phases, and do not collapse them — the user expects to see and approve each one before the next begins.

## Why a dedicated skill

A release of this plugin touches four separate manifest files plus the changelog. Forgetting any one of them ships a broken or inconsistent release: marketplace listings disagree about the version, Codex installs the wrong build, or the changelog drifts from what was actually tagged. The single source of release truth for this repo is `RELEASE_CHECKLIST.md` — this skill executes that checklist programmatically so nothing is missed.

## The six phases

### Phase 1 — Inspect what changed since the last tag

Goal: understand and summarise everything that has landed since the previous release.

Run, in parallel:

```bash
git fetch --tags --quiet
git describe --tags --abbrev=0                         # the last released tag, e.g. v2.3.9
git log <last-tag>..HEAD --pretty=format:'%h %s'       # commit subjects since that tag
git diff --stat <last-tag>..HEAD                       # files touched, magnitude of change
git status --short                                     # uncommitted work that may need to ship in this release
```

Then read the actual diff for any commit subjects that are vague or for any non-trivial file changes — commit subjects alone often understate what shipped. Pay particular attention to:

- New skills under `plugins/corezoid/skills/` (added directories).
- MCP server changes in `plugins/corezoid/mcp-server/` (new tools, schema changes, breaking behaviour).
- Docs changes in `plugins/corezoid/docs/` and root-level docs (`README.md`, `SECURITY.md`, `CLAUDE.md`).
- CI / workflow changes in `.github/`.

If `git status` shows uncommitted changes, ask the user whether those should be part of this release or stay out of it. Don't assume — pending edits are sometimes the whole point of the release and sometimes unrelated work.

Output to the user: a short bulleted summary grouped by category, the kind of bullets that would end up in the changelog. Use the same vocabulary the existing CHANGELOG.md uses: `Feat:`, `Fix:`, `Docs:`, `Chore:`, `CI:`, `Security:`, `Refactor:`. Keep each bullet to one line.

### Phase 2 — Ask which new version to publish

Goal: get the new semantic version from the user.

Use `AskUserQuestion` with the **current** version pulled from `plugins/corezoid/.claude-plugin/plugin.json` and three suggested bumps:

- Patch (`X.Y.Z+1`) — bug fixes, docs, internal cleanup only.
- Minor (`X.Y+1.0`) — new skills, new MCP tools, additive features.
- Major (`X+1.0.0`) — breaking changes to manifests, MCP tool schemas, or skill contracts.

Recommend a level based on Phase 1 (e.g. if a new skill directory appeared, suggest a minor bump). Always allow the user to override with a custom version via the "Other" answer.

The version the user picks is the only version that should appear anywhere downstream in this skill run. Store it once and reuse it — do not re-derive it.

### Phase 3 — Draft the CHANGELOG.md entry

Goal: produce a new section at the top of `CHANGELOG.md`, matching the existing format exactly.

Read `CHANGELOG.md`. The format is rigid:

```
## [X.Y.Z]

- Feat: …
- Fix: …
- Docs: …
```

Rules:

- The new section goes immediately after the top-level `# Changelog` heading, **before** the previous version.
- Use the same category prefixes seen in prior entries. Don't invent new ones unless the change genuinely doesn't fit (e.g. `Refactor:` is fine, `Stuff:` is not).
- One bullet per logical change, not one bullet per commit. Squash related commits.
- Write in the past tense, imperative-ish style matching prior entries ("add", "fix", "remove" — not "added", "fixes").
- Drop trivia: bumps of internal version numbers, merge commits, formatting-only changes. The changelog is for users of the plugin, not for git archeologists.

Show the drafted entry to the user before writing it to disk. They will often want to reword a bullet or merge two of them — that's expected.

### Phase 4 — Sync the version across all four manifests

Goal: the new version appears in exactly four places, all in agreement.

The files and the field to update:

| File | Field to edit |
| --- | --- |
| `plugins/corezoid/.claude-plugin/plugin.json` | top-level `"version"` |
| `plugins/corezoid/.codex-plugin/plugin.json` | top-level `"version"` |
| `.claude-plugin/marketplace.json` | `plugins[0].version` |
| `.agents/plugins/marketplace.json` | `plugins[0].version` |

Use the `Edit` tool with `old_string` containing the full `"version": "..."` line so the replacement is unambiguous. Do not rewrite the whole file. Do not touch any other field — license, description, paths must stay as-is.

After editing, verify with a single grep:

```bash
grep -n '"version"' \
  plugins/corezoid/.claude-plugin/plugin.json \
  plugins/corezoid/.codex-plugin/plugin.json \
  .claude-plugin/marketplace.json \
  .agents/plugins/marketplace.json
```

All four lines must show the new version. If any one disagrees, fix it before moving on — never proceed to commit with mismatched manifests.

Then validate that the JSON still parses:

```bash
python3 -m json.tool .claude-plugin/marketplace.json >/dev/null
python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
python3 -m json.tool plugins/corezoid/.claude-plugin/plugin.json >/dev/null
python3 -m json.tool plugins/corezoid/.codex-plugin/plugin.json >/dev/null
```

### Phase 5 — Confirm with the user

Goal: nothing is committed without explicit go-ahead.

Show the user:

1. The new version number.
2. The CHANGELOG.md entry as it will be written.
3. A `git diff --stat` of all currently staged/unstaged changes (including any pre-existing edits from Phase 1 that they confirmed should ship).
4. The exact commit message and tag name you intend to create.

Then use `AskUserQuestion` with options like "Proceed wit