STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 1 immediately.

Step 0 — Immediate Output

Before ANY tool calls, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► RELEASE                                    ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:release — Changelog & Release Notes

You are running the release skill. This skill generates polished, user-facing changelog entries from project history — milestone summaries, commit logs, and planning artifacts. It produces Keep a Changelog format with bolded feature names and impact-focused descriptions.

This skill runs inline (no subagents).

Argument Parsing

Parse $ARGUMENTS:

$ARGUMENTS format: [version] [--flag]

Examples:
  ""                 → mode=draft, version=auto-detect from package.json
  "v2.2.0"           → mode=draft, version=v2.2.0
  "--draft"          → mode=draft, version=auto-detect
  "--update v2.1.0"  → mode=update, version=v2.1.0
  "--clean"          → mode=clean, run clean-changelog.js on existing CHANGELOG.md

Modes:

draft (default) — Generate a new changelog entry for unreleased work
update — Regenerate the entry for an existing version
clean — Run the scope-cleaning script on the current CHANGELOG.md

Mode: `clean`

Run the changelog cleaning script to strip internal scopes from existing entries:

node scripts/clean-changelog.js --write

Display the result and exit.

Mode: `draft` or `update`

Step 1 — Gather Context

Determine version:
- If provided: use it (auto-prefix v if missing)
- If not: read package.json version field and use that
Read current CHANGELOG.md (if exists):
- Parse existing version entries to avoid duplicating
- If update mode: find the section for the target version to replace
Determine the change range:

For draft mode (unreleased work):
- Find the most recent git tag: git describe --tags --abbrev=0
- Collect commits since that tag: git log {tag}..HEAD --oneline
- Read any milestone archive SUMMARY.md files created since the tag
For update mode (existing version):
- Find the tag for the target version
- Find the tag before it
- Collect commits between those two tags
- Read the milestone archive for that version if it exists

Step 2 — Read Summaries

Read SUMMARY.md files from the relevant phases (archived or active):

Check .planning/milestones/ for version-matched archives
Check .planning/phases/ for active phase summaries
Extract provides, key_files, and key_decisions fields from frontmatter
Read commit messages for additional context

Step 3 — Draft the Entry

Generate a changelog entry in Keep a Changelog format:

## [{version}] - {YYYY-MM-DD}

### Added
- **Feature name** — What it does and why it matters
- **Another feature** — User-facing description

### Changed
- **Existing feature** — What changed and why

### Fixed
- **Bug description** — What was broken and how it's resolved

Rules:

Lead with user-visible impact, not implementation details
Group related commits into single entries (5 auth commits → one "Authentication" entry)
Use bold feature names with em-dash descriptions
No commit hashes in the changelog (they're in git, not in prose)
No internal scopes (phase-plan numbers, TDD markers, quick-NNN)
Omit empty sections (no ### Changed if nothing changed)
End with: Install/upgrade: \npx @sienklogic/plan-build-run@latest``

Step 4 — User Review

Present the draft to the user:

Use AskUserQuestion:

question: "Here's the draft changelog for {version}. Review and approve?"
header: "Changelog Draft"
options:
  - label: "Looks good"        description: "Write this to CHANGELOG.md"
  - label: "Edit"              description: "I'll provide corrections or additions"
  - label: "Regenerate"        description: "Try again with different grouping"
  - label: "Cancel"            description: "Don't write anything"

If "Looks good": proceed to Step 5
If "Edit" or "Other": apply corrections, present again
If "Regenerate": re-draft with user feedback incorporated, present again
If "Cancel": exit without writing

Step 5 — Write

Write to CHANGELOG.md:
- For draft: insert the new entry after the file header, before existing versions
- For update: replace the existing entry for that version

Commit:

git add CHANGELOG.md
git commit -m "docs: update changelog for {version}"

Update GitHub Release (if tag exists):

Check if a GitHub release exists for this version:

gh release view {tag} --json tagName 2>/dev/null

If it exists, offer to update the release body:

Use AskUserQuestion:

question: "A GitHub release exists for {tag}. Update its release notes too?"
header: "GitHub Release"
options:
  - label: "Yes"    description: "Update the GitHub release body with the new notes"
  - label: "No"     description: "Only update CHANGELOG.md"

If "Yes":

gh release edit {tag} --notes-file - <<< "{changelog entry}"

Step 6 — Confirm

Display:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► CHANGELOG UPDATED                          ║
╚══════════════════════════════════════════════════════════════╝

Version: {version}
Sections: {Added: N, Changed: N, Fixed: N}
File: CHANGELOG.md

{if GitHub release updated: "GitHub release also updated."}

Anti-Patterns

DO NOT include commit hashes in changelog entries — this is user-facing prose
DO NOT use internal scopes (01-01, quick-003) — use descriptive feature names
DO NOT list every commit individually — group related work into features
DO NOT write the changelog without user confirmation via AskUserQuestion
DO NOT include TDD markers (RED, GREEN, REFACTOR) in descriptions
DO NOT skip empty section removal — no ### Changed with no entries