gh-xloxn69-agileflow/commands/changelog.md

description, allowed-tools

description	allowed-tools
generate-changelog	Bash, Read, Edit, Write, Glob, Grep

generate-changelog

Automatically generate changelog from PR titles, commits, and tags.

Prompt

ROLE: Changelog Generator

OBJECTIVE Create or update CHANGELOG.md based on merged PRs, commits, and version tags following Keep a Changelog format.

INPUTS (optional)

• VERSION= (e.g., 1.2.0) (default: auto-detect from latest tag)
• SINCE= (default: last version tag)
• FORMAT=keepachangelog|simple|github (default: keepachangelog)
• AUTO_COMMIT=yes|no (default: no, ask first)

CHANGELOG FORMAT

Follow Keep a Changelog standard:

# 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/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.2.0] - 2025-10-16

### Added
- New feature X for users to do Y (#123)
- Support for Z configuration (#125)

### Changed
- Improved performance of A by 40% (#124)
- Updated B to use new API (#126)

### Deprecated
- Old method C will be removed in v2.0 (#127)

### Removed
- Unused dependency D (#128)

### Fixed
- Bug where E caused F (#129)
- Crash when G is null (#130)

### Security
- Patched XSS vulnerability in H (#131)

## [1.1.0] - 2025-09-15
[...]

DATA COLLECTION

1. Get Version Info

# Get latest tag
git describe --tags --abbrev=0

# If no VERSION provided, suggest next version based on changes:
# - Major (2.0.0): Breaking changes
# - Minor (1.X.0): New features (Added)
# - Patch (1.1.X): Bug fixes only (Fixed)

2. Get Commits Since Last Release

git log <SINCE>..HEAD --oneline --no-merges

3. Get Merged PRs (if using GitHub)

gh pr list --state merged --base main --json number,title,mergedAt,labels

4. Parse Conventional Commits

Recognize commit prefixes:

• feat: or feat(scope): → Added
• fix: or fix(scope): → Fixed
• docs: → (skip or Documentation)
• style: → (skip)
• refactor: → Changed
• perf: → Changed (note performance improvement)
• test: → (skip)
• chore: → (skip unless important)
• BREAKING CHANGE: or exclamation mark → Changed (breaking) + note
• security: → Security

CATEGORIZATION

Auto-Categorize Commits

commit: feat(auth): add OAuth2 support (#123)
→ Added: OAuth2 authentication support (#123)

commit: fix(api): handle null user in login endpoint (#124)
→ Fixed: Crash when user is null in login endpoint (#124)

commit: perf(db): optimize user query with index (#125)
→ Changed: Improved user query performance by 50% (#125)

commit: feat(ui)!: redesign dashboard layout (#126)
→ Changed: **BREAKING** Redesigned dashboard layout (#126)

Manual Review

If commit messages are unclear, suggest manual categorization:

Unclear commits (need categorization):
- "update stuff" (abc123)
- "fix things" (def456)

Please categorize:
1. Added / Changed / Fixed / Security? update stuff
   → [User inputs: Changed]

2. Added / Changed / Fixed / Security? fix things
   → [User inputs: Fixed]

BREAKING CHANGES

Detect breaking changes:

• Commit with exclamation mark after type: feat!: new API
• Commit with BREAKING CHANGE: footer
• PR label: breaking-change

Highlight prominently:

### Changed
- ⚠️ **BREAKING**: Redesigned API endpoints. See migration guide. (#126)
- ...

VERSION SUGGESTION

Based on changes:

Changes detected:
- 3 Added (feat:)
- 5 Fixed (fix:)
- 1 BREAKING (feat!:)

Suggested version: 2.0.0 (MAJOR - breaking change)
Current version: 1.5.2

Accept suggested version? (YES/NO/CUSTOM)

CHANGELOG GENERATION

New Changelog (if doesn't exist)

Create CHANGELOG.md with:

• Header (Keep a Changelog notice)
• [Unreleased] section (empty)
• [VERSION] section with all changes
• Footer links

Update Existing Changelog

1. Read existing CHANGELOG.md
2. Find ## [Unreleased] section
3. Move unreleased items to new [VERSION] section
4. Add new changes to [VERSION] section
5. Clear [Unreleased] section
6. Update footer links

EXAMPLE OUTPUT

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [2.0.0] - 2025-10-16

### Added
- OAuth2 authentication support for Google and GitHub providers (#123)
- User profile settings page with avatar upload (#135)
- Dark mode toggle in user preferences (#137)

### Changed
- ⚠️ **BREAKING**: Redesigned API endpoints to RESTful structure. See [migration guide](docs/migration-v2.md). (#126)
- Improved user query performance by 50% with database indexing (#125)
- Updated UI component library from v3 to v4 (#138)

### Fixed
- Crash when user object is null in login endpoint (#124)
- Memory leak in WebSocket connection handler (#139)
- Incorrect timezone display in activity logs (#140)

### Security
- Patched XSS vulnerability in comment rendering (#131)
- Updated dependencies with known CVEs (#141)

## [1.5.2] - 2025-09-15
[Previous release...]

---

[unreleased]: https://github.com/user/repo/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/user/repo/compare/v1.5.2...v2.0.0
[1.5.2]: https://github.com/user/repo/compare/v1.5.1...v1.5.2

WORKFLOW

1. Detect current version and changes since last release
2. Parse commits/PRs and categorize
3. Suggest next version number
4. Generate changelog entry preview (diff-first)
5. Ask: "Update CHANGELOG.md? (YES/NO)"
6. If YES:
   • Update CHANGELOG.md
   • Optionally commit:

     git add CHANGELOG.md
     git commit -m "chore(release): update CHANGELOG for v${VERSION}"
     

7. Optionally create release:
   • Git tag: git tag -a v${VERSION} -m "Release v${VERSION}"
   • GitHub release: gh release create v${VERSION} --notes-file CHANGELOG-${VERSION}.md

INTEGRATION

CI Automation

Suggest adding to release workflow:

name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version number (e.g., 1.2.0)'
        required: true

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Get all tags

      - name: Generate changelog
        run: npx claude-code /AgileFlow:generate-changelog VERSION=${{ github.event.inputs.version }}

      - name: Commit changelog
        run: |
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add CHANGELOG.md
          git commit -m "chore(release): update CHANGELOG for v${{ github.event.inputs.version }}"

      - name: Create tag
        run: git tag -a v${{ github.event.inputs.version }} -m "Release v${{ github.event.inputs.version }}"

      - name: Push changes
        run: |
          git push origin main
          git push origin v${{ github.event.inputs.version }}

      - name: Create GitHub release
        run: gh release create v${{ github.event.inputs.version }} --generate-notes
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Story Integration

Create story after release:

US-XXXX: Post-release tasks for v${VERSION}
- [ ] Announce release (blog, social media)
- [ ] Update documentation
- [ ] Monitor error tracking for new issues

CUSTOMIZATION

Read project-specific settings from .agileflow/changelog-config.json:

{
  "categories": {
    "feat": "Added",
    "fix": "Fixed",
    "perf": "Changed",
    "docs": "Documentation"
  },
  "excludeLabels": ["wip", "draft"],
  "includeAuthors": true,
  "groupByScope": true
}

RULES

• Follow Keep a Changelog format strictly
• Include PR/issue numbers for traceability
• Highlight breaking changes prominently
• Use consistent verb tense (past tense)
• Group similar changes together
• Never remove old changelog entries
• Diff-first, YES/NO before updating
• Suggest semantic version based on changes

OUTPUT

• Version suggestion
• Changelog entry preview
• Updated CHANGELOG.md (if approved)
• Optional: Git tag and release creation