| name | changelog |
| description | Add CHANGELOG.md entries, derive them from commits, or cut a Keep a Changelog and SemVer release. |
| user-invocable | true |
| allowed-tools | Read, Edit, Write, Bash, AskUserQuestion |
changelog
Manage CHANGELOG.md per Keep a Changelog 1.1.0 and SemVer 2.0.0:
- add: one entry;
- from-commits: derive entries from Conventional Commits;
- release: cut a version.
Edit only CHANGELOG.md. Never change version files, commit, or tag; release prints suggested commands.
Step 1 — Resolve the action
Resolve add, from-commits (commits), or release from $ARGUMENTS or the request; ask if ambiguous.
Step 2 — Pre-flight (all actions)
root=$(git rev-parse --show-toplevel 2>/dev/null) || root=.
ls "$root/CHANGELOG.md" 2>/dev/null
Always use $root/CHANGELOG.md, never a cwd-relative path.
- Existing: read and preserve style.
- Missing for
add/from-commits: create the standard linked title, intro, and ## [Unreleased] skeleton.
- Missing for
release: stop and suggest /changelog add or /changelog from-commits.
Step 3 — Insert under [Unreleased] (add, from-commits)
Append - <imperative description> to its category under [Unreleased], creating the category in canonical order. Never edit released sections or date [Unreleased].
Step 4 — Run the action
Load writing guidelines for entry rules, commit mapping, and SemVer bumps.
- add — use the user's text or ask for one of the six categories and a ≤15-word description; tighten and insert it.
- from-commits — follow the process below.
- release — follow
references/release.md.
from-commits
The changelog, not git tags, is the source of truth for what shipped — derive entries, don't mirror the log.
- Range: use
<latest-tag>..HEAD; without tags, find the commit for the latest released section. Without either baseline, show the commit count and ask for all, last 30, last 100, or another range. Never silently choose all.
- Gather: inspect subjects and bodies; breaking footers may be in bodies.
- Derive: map, filter, aggregate, and deduplicate per the guidelines. Collapse a 10–20-commit feature into 1–3 user-facing entries.
- Confirm: show grouped proposals plus skipped or aggregated items with reasons, then insert only after approval.
