export default check-changelogs

name

check-changelogs

description

Verify that each plugin has a CHANGELOG.md with an entry for the current version from plugin.json. Use when (1) before creating a pull request or release to ensure version history is documented, (2) after bumping version numbers with bump-version, (3) when asked to verify project health or release readiness, (4) during release preparation to confirm all changes are documented, (5) as part of comprehensive validation alongside check-versions and check-skill-counts, (6) when onboarding a new plugin to ensure proper version documentation.

Check Changelogs

Verify that CHANGELOG.md files exist for each plugin and document the current version declared in plugin.json. This ensures users can understand what changed in each release and that version history is properly maintained.

Instructions

1. Understand what's being validated. Each plugin must have a CHANGELOG.md file that documents release history, and the current version from plugin.json must have a corresponding entry in the CHANGELOG—the validation ensures that version bumps are accompanied by documentation, signaling intentional change tracking rather than undocumented drift.

2. Execute validation to establish current state. Running the check-changelogs script reveals both whether CHANGELOG.md files exist and whether they document current versions, establishing a baseline that separates compliant plugins from those needing remediation—this automated check surfaces gaps that manual review might miss across multiple plugins.

3. Interpret the results. The validation examines both file existence and version documentation—changelogs must exist and must contain heading entries (like ## 1.3.0) matching the current declared versions.

4. Guide remediation collaboratively. When changelog entries are missing, gather information from the user about what changed, examining recent git commits for the affected plugin to build context that informs suggested changelog entries. Draft appropriate changelog entries following the existing format while treating version bumps as deliberate acts requiring human explanation—each bump signals changes worth documenting, and the validation ensures this documentation exists before release.

5. Respect changelog conventions. The repository uses a standard format with version headers (## X.Y.Z) followed by bullet points describing changes—this consistency allows users scanning release history to quickly locate specific versions and understand what changed, making the format a discovery aid rather than mere decoration. Maintain this structure when suggesting new entries.

Script Usage

.claude/scripts/check-changelogs.sh

The script takes no arguments and checks all plugins in the repository. It returns exit code 0 if all changelogs exist with current version entries, or exit code 1 if problems are found.

Examples

Example 1: All changelogs valid

$ .claude/scripts/check-changelogs.sh

Checking CHANGELOG.md files and version entries...

thinkies:
  CHANGELOG.md: ✅ exists
  Version 1.3.0: ✅ documented

software:
  CHANGELOG.md: ✅ exists
  Version 1.1.2: ✅ documented

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ PASS: All plugins have valid changelogs

In this case, report success and confirm that release documentation is complete.

Example 2: Missing changelog entry

$ .claude/scripts/check-changelogs.sh

Checking CHANGELOG.md files and version entries...

thinkies:
  CHANGELOG.md: ✅ exists
  Version 1.4.0: ❌ not documented

software:
  CHANGELOG.md: ✅ exists
  Version 1.1.2: ✅ documented

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ FAIL: Found 1 plugin(s) with changelog issues

In this scenario:

1. Report that thinkies version 1.4.0 is missing from CHANGELOG.md
2. Check recent commits for context:

   git log --oneline plugins/thinkies/ | head -10
   

3. Ask the user what changed in version 1.4.0
4. Suggest an entry following the existing format:

   ## 1.4.0
   
   - Added new-skill for solving specific problem type
   - Fixed bug in existing-skill where it handled edge case incorrectly
   - Improved documentation for another-skill
   

Example 3: Missing CHANGELOG.md file

$ .claude/scripts/check-changelogs.sh

Checking CHANGELOG.md files and version entries...

thinkies:
  CHANGELOG.md: ✅ exists
  Version 1.3.0: ✅ documented

expression:
  CHANGELOG.md: ❌ missing

software:
  CHANGELOG.md: ✅ exists
  Version 1.1.2: ✅ documented

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ FAIL: Found 1 plugin(s) with changelog issues

In this case:

1. Report that expression plugin has no CHANGELOG.md
2. Read the plugin.json to see the current version
3. Look at the entire git history for the expression plugin
4. Suggest creating a CHANGELOG.md with all historical versions documented, starting from version 1.0.0 through the current version

Example 4: Examining changelog format

When drafting a changelog entry, first read the existing CHANGELOG.md to understand the format:

# Changelog

## 1.3.0

- Added introspect-reference-notes skill for listing and searching prior sessions
- Added /reason command for full lifecycle orchestration
- Refactored introspection scripts to use flag-based arguments

## 1.2.0

- Version bump for marketplace release

Maintain this format: version header, followed by bullet points in past tense, focusing on user-visible changes rather than implementation details.