release

name	release
description	Prepare a new release by updating CHANGELOG.md, verifying documentation (README.md, CLAUDE.md, AGENTS.md, ROADMAP.md, docs/), bumping patch version in package.json, building, and suggesting publish commands. Use when asked to release, bump version, prepare release, or publish.

Release — Prepare and Document a New Version

Phase 1: Analyze Changes

Understand what changed since the last release:

1. Read current version from package.json.
2. Read CHANGELOG.md to understand the last documented version and its date. Note any gap — if package.json is ahead of the changelog, intermediate releases were shipped without entries.
3. Find the release boundary. Try git tag -l 'v*' --sort=-v:refname | head -5 for the latest tag. If no tags exist, find the commit that last bumped the version (e.g., git log --oneline --all -- package.json | head -5) and use that SHA as the base.
4. Run git log <base>..HEAD to collect all commit messages since the last release.
5. Run git diff <base>..HEAD to see all committed file changes. Also run git diff HEAD to capture any uncommitted work in the working tree — this may contain unreleased feature work.
6. Count templates from the filesystem to verify against documentation:
   • ls templates/presets/ | wc -l
   • ls templates/modules/ | wc -l
   • ls templates/roles/ | wc -l
7. Pay attention to:
   • New features (new files, new actions, new UI steps)
   • Bug fixes (error handling, logic corrections)
   • Template changes (new presets, modules, roles, prompt updates)
   • Configuration changes (new settings, defaults)
   • Breaking changes (removed features, renamed fields, API changes)
8. Categorize changes into: Added, Changed, Fixed, Removed, Template system (if applicable).

Phase 2: Update CHANGELOG.md

1. Read CHANGELOG.md to understand the existing format and style.

2. If intermediate versions exist without changelog entries (e.g., package.json jumped from 0.1.0 to 0.1.2 but the changelog only has 0.1.0), create brief entries for the skipped versions too — even if they were just version bumps or metadata changes.

3. Add a new version section at the top (below the header), following Keep a Changelog format:

   ## [X.Y.Z] — YYYY-MM-DD
   
   ### Added
   - Feature description
   
   ### Changed
   - Change description
   
   ### Fixed
   - Bug fix description
   

4. Match the tone and detail level of existing entries. Be specific — mention file names, action names, field names where relevant.

5. Do NOT include trivial changes (formatting, comments) unless they affect behavior.

Phase 3: Verify Documentation

Check each documentation file against the actual codebase. For each file, read it and verify accuracy. Only edit if something is factually wrong or missing due to the changes being released.

Files to check

1. README.md — Verify:

   • Feature descriptions match current behavior
   • Configuration options are up to date
   • Template counts (presets, modules, roles) are accurate
   • Example commands still work
   • Any new features from this release are mentioned where appropriate

2. CLAUDE.md — Verify:

   • Architecture description matches current source layout
   • Key concepts are accurate (especially if state fields, actions, or API flow changed)
   • Template system description is current
   • Build/test commands are correct

3. AGENTS.md — Verify:

   • Project vision still matches reality
   • Architecture diagram is current
   • Design principles haven't been violated by changes
   • Template/module/role counts are accurate

4. ROADMAP.md — Verify:

   • Move newly completed items from "Backlog" or "In Progress" to "Done"
   • Add any new backlog items discovered during development
   • Remove items that are no longer relevant

5. docs/ directory — Verify:

   • Any documentation files are consistent with template/module changes
   • Cross-references between docs are still valid

Documentation rules

• Only update what's actually wrong or missing. Don't rewrite prose that's still accurate.
• If counts changed (e.g., "14 presets" → "15 presets"), update all occurrences across all files.
• If a new state field was added, ensure CLAUDE.md's WizardContext description mentions it.
• If new worker actions were added, ensure they're listed in the architecture section.

Phase 4: Bump Version

You MUST bump the version. Do NOT skip this phase. Do NOT leave the version unchanged.

1. Read package.json to get the current version.
2. Check for recent version-bump commits — run git log --oneline -5 -- package.json to ensure you're not colliding with a version that was already bumped externally. If the current version was bumped by a recent commit you haven't accounted for, increment from that version instead.
3. Increment the patch version (e.g., 0.1.5 → 0.1.6). Always patch. Never minor or major unless the user explicitly says so.
4. Edit package.json — change the "version" field to the new version.
5. Edit src/manifest.ts — change the version field to the same new version.
6. Verify both files match — grep both files to confirm the version is identical.
7. Also check if the version appears in any other files (README badges, etc.) and update those too.

Phase 5: Build and Verify

1. Run pnpm build — ensure it succeeds with no errors.
2. Run pnpm typecheck — ensure no type errors.
3. Run pnpm test — vitest plugin tests.
4. Run pnpm test:logic — node:test logic suite. Both test suites must pass.

If any step fails, fix the issue before proceeding.

Phase 6: Suggest Publish Commands

Do NOT run these commands — just print them for the user to review and execute manually.

Present the commands in order:

# Review the changes one more time:
git diff

# Commit everything:
git add -A
git commit -m "chore: release vX.Y.Z"

# Tag the release:
git tag vX.Y.Z

# Push:
git push && git push --tags

# Publish to npm:
pnpm publish --access public

If the package is scoped (starts with @), remind the user that --access public is needed for public packages.

Also mention: "After publishing, reload the plugin in the Paperclip UI to pick up the new version."