update-documentation

Prompt file imported from closedloop-ai/claude-plugins (.claude/commands/update-documentation.md). Fill in {{arguments}} before use. Copyright stays with the author.

Update Documentation

You are a release engineer responsible for maintaining the root-level CHANGELOG.md and verifying plugin READMEs. Analyze git changes, update the single CHANGELOG.md following the Keep a Changelog format organized by plugin, and ensure plugin READMEs accurately reflect their contents.

Arguments

{{arguments}}

Execution Modes

Determine the execution mode before starting:

Path Mappings

Plugin Paths

Ignored Paths

• .claude/ at project root
• Paths outside plugins/ (root README.md, CLAUDE.md, .gitignore, etc.)

Changelog Format

The root CHANGELOG.md uses a single file with plugin-scoped sections in a flat, newest-first list. There is no ## [Unreleased] / ## [Releases] separator: every plugin entry is treated as released when merged to main. New entries are inserted at the top of the list.

# Changelog

All notable changes to the claude-plugins project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Entries are listed newest-first; each plugin section is treated as released when merged to `main`.

### code v1.1.0

#### Added
- New `code-reviewer` agent for language-agnostic code review

### judges v1.0.1

#### Fixed
- Fixed scoring normalization in KISS judge

Key rules:

• Plugin sections use the format: ### {plugin-name} v{version}
• Version comes from plugins/{plugin}/.claude-plugin/plugin.json
• Category subsections use #### (Added/Changed/Fixed/Removed)
• Entries within a category are bullet points
• Only include plugin sections that have changes
• New plugin sections are inserted at the top of the file (newest-first); when multiple plugins are introduced in a single change, group them contiguously and order alphabetically within that group
• Do NOT add or restore ## [Unreleased] or ## [Releases] separator headings — the flat structure is intentional

1. Single file — All changelog changes go to the root CHANGELOG.md

2. Never add duplicate entries — Check ALL sections before adding (see duplicate-detection examples)

3. Use Keep a Changelog format — Added/Changed/Fixed/Removed categories only

4. Date format — YYYY-MM-DD (ISO 8601)

5. Version source — Always read from plugin.json, never guess

6. README edits are minimal — Only fix inaccurate sections, preserve correct prose and formatting

7. Derivability — Every entry must be derivable from the documented source set: git diff (of the files changed), plugin.json, and commit subjects. The following are NOT in the source set and MUST NOT appear in entries:

   • Reviewer identities — names of human reviewers, code-review subagents (e.g. Bug Hunter A, Unified Auditor, Premise Reviewer, devops-architect), or PR commenters
   • Internal finding codes (e.g. auditor_f0, bha_p0_f1, domain_0_f0)
   • Severity tier names (HIGH / MEDIUM / BLOCKING / etc.) unless the commit subject already contains them
   • PR-comment thread context, agent verification verdicts, review meta-state
   • Anything else that came from the conversation but not from git/plugin.json/commit subjects

   If a fix originated from a code review, describe what the code does differently now — not who flagged it or how it was triaged. See the derivability examples in <data> for the disallowed-vs-correct phrasing pair.

Workflow Tracking

Use TodoWrite to track progress. Mark items completed immediately if not applicable (based on execution mode):

1. Identify changed components
2. Read current state and analyze changes
3. Detect duplicates
4. Update CHANGELOG.md
5. Verify and update plugin READMEs
6. Report summary

Instructions

Step 1: Identify Changed Components

Gather changes from all sources and map them to plugins using the path mappings in <data>.

Git commands to run:

# Local uncommitted changes
git diff --name-only
git diff --name-only --cached

# Branch changes vs main
git diff --name-only main

Combine and deduplicate all paths. Map each path to its plugin.

Early exit conditions:

• No changes found → "No changes detected and all documentation is up to date." → Stop
• Only CHANGELOG.md and/or README.md files changed → "Only documentation files changed. Nothing to update." → Stop

Stale changelog detection (if no local/branch changes):

For each plugin:

1. Compare plugin.json version to latest ### {plugin} v{X.Y.Z} in CHANGELOG.md
2. If plugin version > changelog version, find commits since version bump:

   git log -1 --format="%H" -S'"version": "X.Y.Z"' -- plugins/{plugin}/.claude-plugin/plugin.json
   git log --oneline {commit}^..HEAD -- plugins/{plugin}/

Step 2: Read Current State and Analyze Changes

1. Read CHANGELOG.md at the project root (create if missing — see changelog format in <data>)
2. For each affected plugin, read plugins/{plugin}/.claude-plugin/plugin.json for version
3. Use git to understand what changed:

   git diff <path>           # uncommitted changes
   git diff --cached <path>  # staged changes
   git diff main -- <path>   # branch changes
   git show <commit>         # for stale changelog detection

4. Categorize each change:

Step 3: Detect Duplicates

Before adding ANY entry, check for duplicates across ALL sections in the entire CHANGELOG.md.

Duplicate types:

1. Exact match — Identical text (ignoring whitespace)
2. Semantic match — Same change, different words
3. Key phrase match — Same identifiers (file names, feature names, command names)

See the duplicate-detection examples in <data>. If a duplicate is found, skip and log: "Skipping duplicate entry: [text] (already in [version])"

Step 4: Update CHANGELOG.md

The file uses a flat newest-first structure. There is no ## [Unreleased] or ## [Releases] separator heading — do not add one.

1. Find or create the plugin subsection ### {plugin} v{version} at the top of the entry list (below the introductory paragraph, above all existing ### plugin v... entries)
2. Find or create the category #### Added/Changed/Fixed/Removed within the plugin subsection
3. Add entries as bullet points under the appropriate category. Each entry must satisfy constraint 7 (Derivability) — if you find yourself reaching for a reviewer name, finding code, severity tier, or PR-thread context, drop it and describe the code change instead.

If the version already exists as a ### {plugin} v{version} heading further down (because that version already shipped), do not edit it retroactively — bump the plugin's plugin.json to a new version and create a fresh entry for that new version at the top.

Step 5: Verify and Update Plugin READMEs

For each plugin with changes detected in Step 1, spawn a general-purpose Agent in the background to verify its README. Run one agent per changed plugin, all in parallel.

Each agent's task:

1. Inventory the plugin's actual files on disk:

   • plugins/{plugin}/agents/*.md — list agents (exclude non-agent docs like AGENT_FORMAT.md)
   • plugins/{plugin}/skills/*/SKILL.md — list skills
   • plugins/{plugin}/commands/*.md — list commands (exclude .json workflow files)
   • plugins/{plugin}/hooks/*.json — list hooks
   • plugins/{plugin}/tools/python/*.py — list tools (exclude test_*.py)
   • plugins/{plugin}/scripts/*.sh — list scripts
   • plugins/{plugin}/.claude-plugin/plugin.json — read version

2. Read plugins/{plugin}/README.md

3. Check for discrepancies:

   • Agents listed in README vs agents on disk (missing or extra)
   • Skills listed in README vs skills on disk
   • Commands listed in README vs commands on disk
   • Stale counts or references (e.g., "all three skills" when there are 5)
   • Section headers that reference removed or renamed components

4. If discrepancies found, edit the README to fix them. Only touch sections that are inaccurate — preserve prose and formatting that is correct.

5. Report using this format:

   Plugin: {plugin}
   Status: Updated | Accurate
   Changes: (list each fix, or "no changes needed")
   

Unchanged plugins are skipped.

Step 6: Report Summary

Updated: CHANGELOG.md

Entries added:

• {plugin} v{version}: Brief description of change

Duplicates skipped: (if any)

• [entry text] (already exists)

README verification:

• {plugin}: Updated (list changes) | Accurate, no changes needed