---

name: changelog-manager description: Create and update CHANGELOG.md with entries that include AI model/CLI attribution, PRD context, and task references.

Changelog Manager

Goal

Maintain a comprehensive CHANGELOG.md that tracks all changes with attribution to the AI model/CLI that made them, linked to PRDs and tasks when applicable.

Input

• Entry type: Manual entry, PR-based entry, or bulk update
• Change description: What was changed
• Optional context: PRD file path, task reference, PR number

Output

• File: CHANGELOG.md at repository root
• Format: Enhanced Keep a Changelog with attribution metadata

---

Process

Phase 1: Initialization

1. Detect AI Model/CLI

   Copy# Auto-detect which AI is running
   # Codex: Check for CLAUDE_CODE_VERSION env var or .claude directory
   # Gemini: Check for .gemini directory
   # Codex: Check for .codex directory
   # Default: "AI Assistant"
   
   if [[ -d ".claude" ]] || [[ -n "$CLAUDE_CODE_VERSION" ]]; then
     AI_SYSTEM="Codex"
   elif [[ -d ".gemini" ]]; then
     AI_SYSTEM="Gemini CLI"
   elif [[ -d ".codex" ]]; then
     AI_SYSTEM="Codex"
   else
     AI_SYSTEM="AI Assistant"
   fi
   

2. Check if CHANGELOG.md exists

   Copyif [[ ! -f CHANGELOG.md ]]; then
     echo "CHANGELOG.md not found. Creating..."
     # Initialize new changelog (see template below)
   fi
   

Phase 2: Entry Creation

1. Gather Entry Details

   Ask the user:

   CopyWhat type of change is this?
   a) Added (new feature)
   b) Fixed (bug fix)
   c) Changed (refactor, improvement)
   d) Deprecated (feature marked for removal)
   e) Removed (feature removed)
   f) Security (security fix)
   g) Documentation (docs only)
   

2. Gather Context

   Ask the user:

   CopyRelated to a PRD? (optional)
   - If yes: path to PRD file (e.g., tasks/0001-prd-feature.md)
   
   Related to a task? (optional)
   - If yes: task reference (e.g., Task 1.2 from tasks-0001-prd-feature.md)
   
   Related to a PR? (optional)
   - If yes: PR number
   

3. Capture Description

   Prompt:

   CopyDescribe the change in one line:
   (e.g., "User profile editing with avatar upload")
   

4. Generate Entry

   Format:

   Copy- [Description] ([AI System], YYYY-MM-DD)
     - **Context:** [PRD link] | Task [reference] | PR #[number]
   

   If no context:

   Copy- [Description] ([AI System], YYYY-MM-DD)
   

Phase 3: Update CHANGELOG.md

1. Parse Existing Changelog

   • Find [Unreleased] section
   • Find appropriate category subsection (### Added, ### Fixed, etc.)
   • Create subsection if it doesn't exist

2. Insert Entry

   Copy# Insert under appropriate category in [Unreleased]
   # Maintain chronological order (newest first)
   

3. Validate Format

   • Ensure proper markdown structure
   • Verify all links are valid
   • Check for duplicate entries

4. Commit Changes

   Copy# Verify CHANGELOG.md exists and was modified
   [[ -f CHANGELOG.md ]] || {
     echo "❌ Error: CHANGELOG.md not found"
     exit 1
   }
   
   # Check if file was actually modified
   git diff CHANGELOG.md | grep -q . || {
     echo "⚠️  Warning: CHANGELOG.md not modified. Entry may already exist."
     echo "Skipping commit."
     exit 0
   }
   
   # Stage the changelog
   git add CHANGELOG.md || {
     echo "❌ Error: Failed to stage CHANGELOG.md"
     exit 1
   }
   
   # Commit with error handling
   git commit -m "docs(changelog): add entry for [description]
   
   Added by $AI_SYSTEM
   
   " || {
     echo "❌ Error: git commit failed"
     echo "This may be due to:"
     echo "  - Pre-commit hooks failing"
     echo "  - No git user configured"
     echo "  - Repository in bad state"
     git status
     exit 1
   }
   
   # Verify commit succeeded
   git log -1 --oneline | grep -q "docs(changelog)" || {
     echo "❌ Error: Commit verification failed"
     exit 1
   }
   
   echo "✅ CHANGELOG.md updated and committed successfully"
   

---

CHANGELOG.md Template

Initial Creation

Copy# 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/),
with enhanced attribution to track which AI model/CLI made each change.

## [Unreleased]

### Added

### Fixed

### Changed

### Deprecated

### Removed

### Security

---

## Format Notes

Each entry includes:
- **Description** - What was changed
- **Attribution** - Which AI model/CLI made the change (Codex, Gemini CLI, etc.)
- **Date** - When the change was made (YYYY-MM-DD)
- **Context** (optional) - Links to PRD, task reference, or PR number

Example:

Added

• User profile editing with avatar upload (Codex, 2025-01-16)
  • Context: PRD | Task 1.2 | PR #42

Copy
---

*Changelog initialized YYYY-MM-DD*

---

Entry Formats

With Full Context

Copy### Added
- Real-time notifications via WebSocket (Codex, 2025-01-16)
  - **Context:** [PRD](tasks/0003-prd-notifications.md) | Task 2.1 | PR #45
  - **Details:** Implemented server-sent events with fallback to polling

With PRD Only

Copy### Fixed
- Login session timeout on mobile (Gemini CLI, 2025-01-15)
  - **Context:** [PRD](tasks/0001-prd-auth.md)

With Task Only

Copy### Changed
- Refactored database connection pooling (Codex, 2025-01-14)
  - **Context:** Task 3.4 from [tasks-0005-prd-performance.md](tasks/tasks-0005-prd-performance.md)

With PR Only (Auto-generated)

Copy### Security
- Patched XSS vulnerability in message rendering (Codex, 2025-01-13)
  - **Context:** PR #49

Minimal Entry (No Context)

Copy### Documentation
- Updated API documentation (Codex, 2025-01-12)

---

Bulk Update Mode

For updating changelog from multiple PRs or commits:

1. Scan Git History

   Copy# Get commits since last changelog update
   git log --oneline --since="$(git log -1 --format=%ai CHANGELOG.md)" --no-merges
   

2. Parse Each Commit

   • Extract conventional commit type
   • Extract description
   • Check for PR reference in commit message

3. Generate Entries

   • Group by category (Added/Fixed/Changed/etc.)
   • Add attribution based on co-author tag or default to current AI

4. Present for Review

   • Show proposed entries
   • Allow user to edit before inserting

---

Version Release

When releasing a new version:

1. Move [Unreleased] to Version Section

   Copy## [1.2.0] - 2025-01-16
   
   ### Added
   [All entries from Unreleased/Added]
   
   ### Fixed
   [All entries from Unreleased/Fixed]
   
   ...
   
   ## [1.1.0] - 2025-01-10
   ...
   

2. Reset [Unreleased]

   Copy## [Unreleased]
   
   ### Added
   
   ### Fixed
   
   ### Changed
   
   ### Deprecated
   
   ### Removed
   
   ### Security
   

3. Commit

   Copygit add CHANGELOG.md
   git commit -m "docs(changelog): release v1.2.0"
   git tag v1.2.0
   

---

Integration with PR Review Loop

The pr-review-loop skill automatically calls this skill after merging:

Copy# After PR merge:
changelog-manager \
  --type "Added" \
  --description "Feature from PR title" \
  --pr 123 \
  --auto

This adds an entry without user prompting.

---

Interaction Model

Manual Mode (Default)

• Prompts user for change type, description, context
• Interactive and guided

Auto Mode (from PR merge)

• Accepts parameters via flags
• No user interaction
• Used by pr-review-loop

Bulk Mode

• Scans git history
• Proposes entries for review
• User confirms/edits before insertion

---

Key Principles

1. Attribution - Every entry shows which AI made the change
2. Context - Link to PRD/task/PR when available
3. Chronological - Newest entries first within each category
4. Searchable - Easy to find when a change was made and by whom
5. Standard Format - Keep a Changelog compliance

---

References

• See reference.md for format examples
• Keep a Changelog: https://keepachangelog.com/en/1.0.0/