Release

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