plan2code/.claude/skills/plan2code-changelog/SKILL.md

name, description

name

description

plan2code-changelog

Validate and fix the CHANGELOG.md version number before opening a PR. Reads main branch to determine the current latest version, classifies changes on the current branch, and proposes the correct next semver. Use this skill when the user mentions changelog, version number, preparing a PR, release version, semver check, or says 'check the changelog', 'what version should this be', 'prepare for PR', or 'fix the version'. Also use proactively when you notice a CHANGELOG entry that may have an incorrect version number.

Plan2Code Changelog Validator

Ensure the CHANGELOG.md entry for the current branch has the correct semver version before a PR is opened. This skill exists because parallel branches independently pick version numbers that collide or leap-frog when merged — this validates against main's actual state right before the PR.

Workflow

Step 1 — Gather state

Run these commands to understand the current situation:

# 1. Current latest version on main
git show main:CHANGELOG.md | head -20

# 2. Current branch name (for ticket ID extraction)
git branch --show-current

# 3. What this branch changed (commit subjects)
git log main...HEAD --oneline

# 4. Files changed on this branch
git diff main...HEAD --name-only

Extract from main's CHANGELOG:

• The latest version number (first ## vX.Y.Z line)

Note: on Windows, PowerShell's console encoding mangles the emoji in the ### headings to ?. Read CHANGELOG.md with the file-read or grep tool rather than Get-Content / Select-String when you need to see them.

Extract from the branch:

• The list of changed files to classify the change type
• The commit messages for changelog entry content

Step 2 — Classify the change

Determine the change type by examining what was modified on this branch:

Signal	Classification	Version Bump	Heading
An install target removed, or an existing workflow's contract broken	Breaking change	Major (X.0.0)	### 💥 Breaking
New workflow prompt (.md file under src/)	New workflow	Minor (x.Y.0)	### ✨ Added
New capability added to an existing prompt, or a new .claude/skills/ skill	New capability	Patch (x.y.Z)	### ✨ Added
Behavioral changes to existing prompt(s), installer, or docs	Behavior change	Patch (x.y.Z)	### 🔧 Changed
Bug fix to existing prompt(s) or tooling	Bug fix	Patch (x.y.Z)	### 🐛 Fixed
A prompt, target, or file deleted	Removal	Patch (x.y.Z)	### 🗑️ Removed
README / .readme/ / docs-site only	Documentation	Patch (x.y.Z)	### 📚 Documentation
Mix of the above	Use the highest bump (major > minor > patch)	Combine headings

Use only the headings in this table — the CHANGELOG has historical one-off variants (🎁 Added, 📦 Updated, 📝 Documentation, 🏎️ Improved, 🧪 Testing) that should not be introduced in new entries.

Step 3 — Compute the correct version

Starting from main's latest version:

• Major bump: increment the first number, reset the rest (e.g., 1.16.1 → 2.0.0)
• Minor bump: increment the middle number, reset patch to 0 (e.g., 2.0.0 → 2.1.0)
• Patch bump: increment the last number (e.g., 2.1.0 → 2.1.1)

Step 4 — Check the current branch's CHANGELOG

Read the current CHANGELOG.md on the branch. Look for:

0. You are on main with no diff — there is no branch to validate. Instead, compare the top CHANGELOG version against git log since the commit that released it: if commits have landed on main without a CHANGELOG entry, treat those commits as the change set and continue from Step 2. Say so explicitly rather than reporting "nothing to do."

1. No entry exists yet for this branch's work — the branch hasn't added a version entry above main's latest. Proceed to Step 5 to draft one.

2. An entry exists but the version is wrong — the branch has a version entry, but it doesn't match the computed correct version (common when branches were rebased or other PRs merged first). Report the discrepancy:

   Version check for branch: {branch-name}
   
   Main is at:      {main-version}
   Branch claims:   {branch-version}  
   Correct version: {computed-version} ({classification})
   
   The version needs to be updated: {branch-version} → {computed-version}
   

   Ask: "Update the version to {computed-version}? (yes / no)"

3. An entry exists and the version is correct — report success:

   Version check for branch: {branch-name}
   
   Main is at:      {main-version}
   Branch version:  {branch-version} ({classification})
   
   Version is correct. CHANGELOG is ready for PR.
   

   Stop here unless the user asks for content changes.

Step 5 — Draft or fix the CHANGELOG entry

If no entry exists, draft a new one based on the commits and changed files. Match this repo's house format exactly — a bare ## vX.Y.Z heading with no date, emoji ### headings from the Step 2 table, and a blank line between bullets:

## {computed-version-with-v-prefix}

### ✨ Added

- **{prompt-or-area}** — {what changed, and why it matters to someone installing it}

### 🔧 Changed

- **{prompt-or-area}** — {what changed}

Conventions to follow, drawn from existing entries:

• Bold lead-in naming the prompt, file, or area, then an em dash (—), then the description.
• Reference prompts by their command (/plan2code-1-plan) or path (src/plan2code-init.md), not by informal name.
• One paragraph per bullet is fine — this CHANGELOG favours substantive entries over terse one-liners, and a bullet may carry extra indented paragraphs for detail.
• A release with a big theme may open with a one-line summary paragraph directly under the ## vX.Y.Z heading, before the first ###.

Insert the new section directly below the All notable changes... line and above the previous version's heading.

Present the draft and ask for approval before writing.

If the version is wrong, update only the version number — preserve the existing content unless the user asks for content changes too.

After any changes, show the final CHANGELOG entry for confirmation.

Step 6 — Sync package.json and version.json versions

After writing or updating the CHANGELOG entry, update the version field in package.json at the repo root to match the computed version:

1. Read package.json and version.json then check the current version value.
2. If it already matches the computed version, skip — no change needed.
3. If it differs, update the "version" field in both files to the computed version (e.g., "version": "2.1.1").
4. Set releaseDate in version.json to today's date in YYYY-MM-DD. This is the only place a date is recorded — the CHANGELOG headings carry no date.
5. Include package.json and version.json in the same commit as the CHANGELOG changes.

This keeps package.json, version.json, and CHANGELOG.md in lockstep so npm pkg get version always reflects the latest release.

Rules

• Never create a version entry without checking main first — the whole point is to derive the version from main's current state
• Always present changes before writing — the user should see and approve the CHANGELOG entry
• Match the existing file's format — ## vX.Y.Z with no date, emoji ### headings. Do not introduce Keep a Changelog's ## [x.y.z] - date style
• Write for someone reading the release notes, not for someone reading the diff — say what the change lets them do
• If multiple change types exist (Added + Changed), use multiple headings under the same version
• version.json's releaseDate is today's date, i.e. when the release is being prepared, not when the work started
• If the branch has no meaningful changes vs main (e.g., only non-shipping files changed), say so and ask if a CHANGELOG entry is actually needed