Purpose: Take a project from "code is ready" to "tagged and ready to push."

git tag --sort=-version:refname -l 'v*' | head -1

• If no

  v*

  tags exist, use the first commit:

  git rev-list --max-parents=0 HEAD

• The range is

  <last-tag>..HEAD

• If range is empty (no new commits), stop and tell the user

feat

• Group related commits that share a component prefix (e.g.,

  auth:

  ,

  api:

  ,

  feat(users)

  )
• Combine grouped commits into a single bullet with a merged description
• Match the existing CHANGELOG style — read the most recent versioned entry and replicate its bullet format, separator style, and heading structure
• If a commit message is ambiguous, read the diff with

  git show --stat <hash>

  to clarify

• Don't invent — only document what git log shows
• Omit empty sections — don't include

  ### Removed

  if nothing was removed
• Commits, not diffs — classify from commit messages; read diffs only when ambiguous
• Merge-commit subjects are noise — already filtered by

  --no-merges

• description of new feature

• description of change

• description of fix

Use today's date in `YYYY-MM-DD` format.

**Style adaptation:** Read the existing CHANGELOG entries and match their conventions:
- Bullet format (plain text vs bold names vs backtick names)
- Separator style (em-dash ` — `, hyphen ` - `, colon `: `)
- Grouping patterns (flat list vs sub-sections)
- Level of detail (terse vs verbose)

If no existing entries to reference (first release), use plain Keep a Changelog defaults.

1. The generated changelog entry (fenced markdown block)
2. The version bumps (file-by-file diff preview)
3. What will happen: "Will write CHANGELOG.md, update 2 version files, create release commit, create tag v1.7.0"

--dry-run

• "Proceed with this release?"
• Options: "Yes, do it" / "Let me edit the changelog first" / "Abort"

1. Update CHANGELOG.md:
   • Find the

     ## [Unreleased]

     line
   • Find where the unreleased section ends (next

     ## [

     line or EOF)
   • Replace with: fresh empty

     ## [Unreleased]

     + blank line + versioned entry
2. Update version files (if user accepted bumps)

• Would a first-time visitor understand every bullet?
• Are internal code names explained or omitted? (e.g., "Gate 4" means nothing — say "retry loop after validation failure")
• Does the Highlights paragraph answer "why should I care?" in plain English?
• Is every bullet about user-visible impact, not implementation detail?

undefined

• Self-healing validation — Failed code reviews now retry automatically with failure context, instead of stopping and waiting for you
• Faster skill loading — Five core skills restructured to load reference content on demand instead of all at once
• 3 security fixes — Command injection, regex injection, and JSON injection vulnerabilities patched in hook scripts

• Self-healing retry loop for the validation lifecycle
• Security and documentation sections for Go, Python, Rust, JSON, YAML standards
• 26 hook integration tests (injection resistance, kill switches, allowlist enforcement)
• Monorepo-friendly quickstart detection

• Command injection in task validation hook (now allowlist-based)
• Regex injection in task validation hook (now literal matching)
• JSON injection in prompt nudge hook (now safe escaping)
• 12 broken links and doc inaccuracies fixed across the project

• Deprecated

  /judge

  skill (use

  /council

  instead)

**Always write release notes to a file immediately after generating:**

```bash
mkdir -p .agents/releases

.agents/releases/YYYY-MM-DD-v<version>-notes.md

gh release create

• Pre-flight validation (tests, lint, clean tree, versions, branch)
• Changelog generation from git history
• Semver suggestion from commit classification
• Version string bumps in package files
• Release commit + annotated tag
• Release notes (highlights + changelog) for GitHub Release page
• Draft GitHub Release (default, opt-out with

  --no-gh-release

  )
• Post-release guidance
• Audit trail

• No publishing — no

  npm publish

  ,

  cargo publish

  ,

  twine upload

  . CI handles this.
• No building — no

  go build

  ,

  npm pack

  ,

  docker build

  . CI handles this.
• No pushing — no

  git push

  , no

  git push --tags

  . The user decides when to push.
• No CI triggering — the tag push (done by the user) triggers CI.
• No monorepo multi-version — one version, one changelog, one tag. Scope for v2.

• Bad changelog → edit the file
• Wrong version bump →

  git reset HEAD~1

• Bad tag →

  git tag -d v<version>

• Draft GitHub Release → delete from the UI

• Don't invent — only document what git log shows
• No commit hashes in the final output
• No author names in the final output
• Concise — one sentence per bullet, technical but readable
• Adapt, don't impose — match the project's existing style rather than forcing a particular format
• User confirms — never write without showing the draft first
• Local only — never push, publish, or trigger remote actions
• Two audiences — CHANGELOG.md is for contributors (file paths, issue IDs, implementation detail). Release notes are for feed readers (plain English, user-visible impact, no insider jargon). Never copy-paste the changelog into the release notes.