gupsammy/make-changelog

Changelog Generator

Create or update CHANGELOG.md from git history using Keep-a-Changelog format. Launch one haiku subagent per version range for parallel, token-efficient processing.

Step 1 — Assess Project State

Run the range-planning script to validate the repo and gather all version ranges:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py --output json

• Exit 2 = not a git repository, or repository has no commits. Stop and report the error message from stderr to the user.
• Exit 0 = proceed. JSON output contains all ranges the skill would cover.

Also check for an existing changelog:

ls CHANGELOG.md CHANGELOG 2>/dev/null

If CHANGELOG.md exists, read it to identify the last documented version (the most recent ## [x.y.z] heading).

Step 2 — Determine Scope

No tags exist: Script returns a single Unreleased range. Proceed in fresh mode.

Tags exist, no CHANGELOG.md: Fresh mode — process all ranges the script returned.

Tags exist, CHANGELOG.md exists: Fill mode — re-run the script with --since-tag to get only the uncovered ranges:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py \
  --since-tag <last_documented_tag> --output json

If the intent is ambiguous (user said "update changelog" but the file has extensive existing content), ask the user to choose:

• "Fill missing only" — add new versions/unreleased since last entry
• "Rebuild from scratch" — regenerate the full file from git history
• "Unreleased only" — refresh only the [Unreleased] section

Step 3 — Plan Subagents

Inspect the JSON output from Step 1 or 2. Each range object has:

• label — version string (1.2.0 or Unreleased)
• from_ref — lower git ref (empty string = from initial commit)
• to_ref — upper git ref
• date — tag date or today
• commit_count — number of commits in range

Skip ranges where commit_count == 0 — no subagent needed.

Cap at 12 subagents. If the non-empty range list exceeds 12, ask the user whether to limit to the most recent 12 or process all (noting it will take longer).

Step 4 — Launch Haiku Subagents

Spawn one Task per non-empty range in a single message (parallel). Use model: "haiku" for all subagents. Each subagent receives this self-contained prompt (substitute values from the range object):

You are generating one section of a CHANGELOG.md.

Version: [label]
Date: [date]
Git command: git log [from_ref]..[to_ref] --format="%s"
(If from_ref is empty, use: git log [to_ref] --format="%s")

Categorize by user-observable impact, not by commit prefix. The conventional
commit prefix (feat:, fix:, etc.) is a hint only — a commit labelled "feat:"
that clearly corrects a bug belongs in Fixed, not Added. Use the prefix as a
starting signal and override it when the commit subject contradicts it.

Sections and classification signals:
- Added: new capabilities users can invoke (add, introduce, implement, support)
- Changed: modified behavior of existing features (update, change, refactor, improve)
- Deprecated: features explicitly flagged for future removal
- Removed: capabilities or endpoints deleted (remove, drop, delete)
- Fixed: bugs corrected, regardless of prefix (fix, resolve, patch, correct, hotfix)
- Security: vulnerability patches (security, CVE, sanitize, escape)

Skip: merge commits, CI/CD configuration changes, version-bump commits,
formatting-only changes.

Use present tense, imperative mood: "Add X", not "Added X" or "adds X".
Omit empty sections. Omit internal variable names and implementation details.

Output ONLY the markdown block, no preamble:

## [VERSION] - DATE

### Added
- ...

### Fixed
- ...

Collect all Task results before Step 5.

Step 5 — Assemble Changelog

Order version blocks newest-first. Full document structure:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

[content from unreleased subagent, or omit section if empty]

## [1.2.0] - 2024-03-15

[content from subagent]

Fill mode: Insert new version sections immediately after the # Changelog header block, before the first existing ## [ entry. Preserve all existing content exactly.

Fresh/rebuild mode: Write the complete file.

Step 6 — Write and Report

Fresh mode: Write CHANGELOG.md. Confirm overwrite with AskUserQuestion if the file already exists.

Fill mode: Use Edit to insert new sections at the correct position.

After writing, report:

• Mode used (fresh / fill / unreleased-only)
• Versions covered (label, date, commit count — from script output)
• Number of subagents used
• Any ranges that were empty (skipped)
• Any commits that could not be confidently categorized (flag for user review)

Scripts

scripts/list_ranges.py — queries git tags and computes version ranges. Invoked in Steps 1 and 2. Exit 2 = repo invalid or empty; exit 0 = success.

# All ranges (text preview)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py

# All ranges (JSON for skill use)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py --output json

# Fill mode: only ranges newer than a specific tag
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py \
  --since-tag v1.2.0 --output json