--- description: Initialize CHANGELOG.md and RELEASE_NOTES.md for a new project or retroactively from git history aliases: ["cl-init"] --- # changelog-init Initialize changelog documentation for a project by analyzing entire git history and generating both developer and user-facing documentation files. ## Usage ```bash /changelog-init # Interactive initialization /changelog-init --from-beginning # Analyze entire git history /changelog-init --from-tag v1.0.0 # Start from specific version /changelog-init --empty # Create empty template files # Historical Replay Mode (NEW) /changelog-init --replay # Interactive period-based replay /changelog-init --replay --period monthly # Monthly period grouping /changelog-init --replay --period weekly # Weekly period grouping /changelog-init --replay --period by-release # Group by releases /changelog-init --replay --period auto # Auto-detect best period ``` ## Workflow ### Step 1: Project Analysis - Detects existing version files (package.json, setup.py, etc.) - Identifies versioning scheme in use - Analyzes git tag patterns - Detects commit message conventions ### Step 2: History Processing - Extracts all commits from starting point - Groups by releases (if tags exist) - Categorizes changes - Identifies key milestones ### Step 3: File Generation - Creates CHANGELOG.md with complete history - Creates RELEASE_NOTES.md with major highlights - Generates .changelog.yaml configuration - Sets up .changelog-metadata.json for tracking ## Replay Workflow (Historical Period-Based Generation) The `--replay` mode generates changelogs by "replaying" history through time periods (daily/weekly/monthly/by-release), creating changelog entries as if they were updated in real-time during development. ### Phase 1: Period Detection **Agent: period-detector (Claude Haiku)** ``` 🔍 Analyzing repository structure... Repository: user/awesome-project First commit: 2023-03-15 (619 days ago) Total commits: 523 Contributors: 24 Git tags: 12 releases detected Auto-detecting optimal period strategy... ✅ Recommended: weekly (21.4 commits/week average) Period options: 1. Weekly (74 periods, ~7 commits/period) 2. Monthly (20 periods, ~26 commits/period) 3. By-Release (12 periods, ~44 commits/period) 4. Auto (use recommended: weekly) Select period strategy [1-4] or press Enter for auto: _ ``` **Detection Logic:** - Analyzes commit frequency and distribution - Detects existing release tags - Calculates project age and activity patterns - Provides smart recommendations with rationale ### Phase 2: Boundary Calculation **Agent: period-detector (Claude Haiku)** ``` 📅 Calculating period boundaries... Strategy: Weekly (Monday-Sunday) Total periods: 74 Empty periods (will be skipped): 8 Merge-only periods (will be skipped): 3 Active periods to analyze: 63 Period boundaries: - Week 1: 2023-03-13 to 2023-03-19 (15 commits) - Week 2: 2023-03-20 to 2023-03-26 (22 commits) - Week 3: 2023-03-27 to 2023-04-02 (18 commits) ... - Week 74: 2025-11-10 to 2025-11-16 (8 commits) [Unreleased] First period note: Week 1 has 287 commits (initial development) → Will use summary mode for clarity Continue with analysis? [Y/n]: _ ``` **Boundary Features:** - Calendar-aligned periods (weeks start Monday, months are calendar months) - Automatic skip of empty periods - Automatic skip of merge-only periods - First-period summarization for large initial development - Partial final period handling (→ [Unreleased]) ### Phase 3: Parallel Period Analysis **Agent: period-coordinator (Claude Sonnet)** ``` ⚙️ Orchestrating multi-period analysis... Execution plan: - Total periods: 63 - Concurrent workers: 3 - Estimated time: ~4 minutes - Cache enabled: Yes Batch 1/21: Analyzing periods 1-3 in parallel... ✅ Week 1 (2023-03-13): 287 commits → Summarized ✅ Week 2 (2023-03-20): 22 commits → 18 changes categorized ✅ Week 3 (2023-03-27): 18 commits → 15 changes categorized Batch 2/21: Analyzing periods 4-6 in parallel... ✅ Week 4 (2023-04-03): 25 commits → 20 changes categorized ⚠️ Week 5 (2023-04-10): Analysis timeout, retrying... ✅ Week 5 (2023-04-10): 31 commits → 28 changes categorized ✅ Week 6 (2023-04-17): 19 commits → 16 changes categorized [Progress: 9/63 periods complete - 14% - ETA 3m 42s] ... ``` **Per-Period Analysis:** Each period invokes: 1. **git-history-analyzer** (Sonnet): Extract and group commits for period 2. **commit-analyst** (Haiku): Batch-analyze unclear commits (invoked automatically by git-history-analyzer) 3. Caching: Results cached per period for instant regeneration ### Phase 4: Changelog Synthesis **Agent: changelog-synthesizer (Claude Sonnet)** ``` 📝 Generating hybrid-format changelog... Format: Hybrid (version releases with period subsections) Structure: - [Unreleased] section: 2 active periods - Released versions: 12 versions across 61 periods - Total entries: 412 changes categorized Generating CHANGELOG.md... ✅ 63 period sections created ✅ 12 version sections created ✅ Navigation TOC added (74 periods) ✅ 412 changes formatted Generating RELEASE_NOTES.md... ✅ Period-aware user-facing notes created ✅ Adapted tone for end-users ✅ Highlighted major features per period ``` **Output Format:** - **CHANGELOG.md**: Hybrid format with version sections containing period subsections - **RELEASE_NOTES.md**: User-friendly with period-based highlights - **Navigation**: Table of contents for changelogs >10 periods ### Phase 5: Verification and Commit ``` ✅ Changelog generation complete! Files created: - CHANGELOG.md (1,847 lines, 63 period sections) - RELEASE_NOTES.md (423 lines, user-friendly format) - .changelog.yaml (configuration persisted) - .changelog-cache/ (63 period analyses cached) Preview of CHANGELOG.md: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # Changelog ## [Unreleased] ### Week of November 11, 2025 #### Added - Real-time notification system (#256) ### Week of November 4, 2025 #### Added - Advanced search filters (#252) ## [2.1.0] - 2024-10-27 ### Week of October 21, 2024 #### Added - REST API v2 with pagination (#234) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Actions: 1. Review generated files? [Y/n] 2. Commit to git? [Y/n] 3. Create version tag? [y/N] ``` ## Agent Orchestration **CRITICAL**: You MUST use the Task tool to invoke these agents in the correct sequence. ### Standard Mode Agent Sequence For standard `/changelog-init` (non-replay): #### 1. Project Context Extractor (Claude Haiku) ``` Use Task tool with: - subagent_type: "changelog-manager:project-context-extractor" - description: "Extract project context from documentation" - prompt: "Analyze CLAUDE.md, README.md, and docs/ to extract project context for user-focused release notes." ``` #### 2. Git History Analyzer (Claude Sonnet) ``` Use Task tool with: - subagent_type: "changelog-manager:git-history-analyzer" - description: "Analyze entire git history" - prompt: "Extract all commits from beginning (or specified tag), group by releases/PRs/features, categorize changes, and detect breaking changes." ``` #### 3. GitHub Matcher (Claude Sonnet) - OPTIONAL ``` Only invoke if GitHub integration enabled. Use Task tool with: - subagent_type: "changelog-manager:github-matcher" - description: "Match commits to GitHub artifacts" - prompt: "Enrich all historical commits with GitHub references." ``` #### 4. Changelog Synthesizer (Claude Sonnet) ``` Use Task tool with: - subagent_type: "changelog-manager:changelog-synthesizer" - description: "Generate initial changelog files" - prompt: "Generate complete CHANGELOG.md and RELEASE_NOTES.md from entire project history using project context for user focus." ``` ### Replay Mode Agent Sequence For `/changelog-init --replay` (period-based historical generation): #### 1. Project Context Extractor (Claude Haiku) Same as standard mode. #### 2. Period Detector (Claude Haiku) ``` Use Task tool with: - subagent_type: "changelog-manager:period-detector" - description: "Detect optimal period strategy" - prompt: "Analyze repository history to detect optimal period strategy (daily/weekly/monthly/by-release), calculate period boundaries, and present options to user." ``` **Purpose**: Analyzes commit frequency, project age, and release patterns to recommend optimal period grouping strategy. **Output**: Period boundaries with start/end commits and dates for each period. #### 3. Period Coordinator (Claude Sonnet) ``` Use Task tool with: - subagent_type: "changelog-manager:period-coordinator" - description: "Orchestrate multi-period analysis" - prompt: "Coordinate parallel analysis of all periods by invoking git-history-analyzer for each period, managing cache, and handling retries." ``` **Purpose**: Orchestrates parallel analysis of all time periods, invoking git-history-analyzer once per period with period context. **Sub-invocations** (managed by period-coordinator): - For each period: Invokes **git-history-analyzer** with period boundaries - Optional: Invokes **github-matcher** to enrich period commits - Caches results per period for fast regeneration #### 4. Changelog Synthesizer (Claude Sonnet) ``` Use Task tool with: - subagent_type: "changelog-manager:changelog-synthesizer" - description: "Generate hybrid-format changelogs" - prompt: "Generate hybrid-format CHANGELOG.md (versions with period subsections) and period-aware RELEASE_NOTES.md from multi-period analysis." ``` **Purpose**: Synthesizes period-based analysis into hybrid changelog format with version sections containing period subsections. ### Integration Flow **Standard Mode:** ``` project-context-extractor (Haiku) ↓ git-history-analyzer (Sonnet) ↓ github-matcher (Sonnet) [OPTIONAL] ↓ changelog-synthesizer (Sonnet) ↓ Write files ``` **Replay Mode:** ``` project-context-extractor (Haiku) ↓ period-detector (Haiku) ↓ period-coordinator (Sonnet) ↓ └─→ [For each period in parallel] git-history-analyzer (Sonnet) github-matcher (Sonnet) [OPTIONAL] ↓ changelog-synthesizer (Sonnet) ↓ Write files ``` ## Options ### Standard Mode - `--from-beginning`: Analyze entire repository history - `--from-tag `: Start from specific git tag - `--empty`: Create template files without historical content - `--config-only`: Only generate .changelog.yaml configuration - `--force`: Overwrite existing files (backup created) ### Replay Mode (NEW) - `--replay`: Enable historical replay mode with period-based generation - `--period `: Period grouping strategy - `daily`: One entry per day with commits - `weekly`: One entry per week (Monday-Sunday) - `monthly`: One entry per calendar month - `quarterly`: One entry per quarter (Q1, Q2, Q3, Q4) - `annual`: One entry per year - `by-release`: One entry per git tag/release - `auto`: Auto-detect best strategy (default) - `--calendar-align`: Align periods to calendar boundaries (default: true) - `--skip-empty`: Skip periods with no commits (default: true) - `--skip-merge-only`: Skip periods with only merge commits (default: true) - `--max-workers `: Concurrent period analyses (default: 3, max: 5) - `--no-cache`: Disable caching (slower but always fresh) - `--hybrid-format`: Generate hybrid format CHANGELOG.md (default: true) - `--replay-in-release-notes`: Apply replay structure to RELEASE_NOTES.md (default: true) ## Examples ### New Project Setup ```bash You: /changelog-init --empty Claude: 📝 Initializing changelog files... Created: ✅ CHANGELOG.md (template) ✅ RELEASE_NOTES.md (template) ✅ .changelog.yaml (configuration) Your changelog files are ready! Next steps: 1. Customize .changelog.yaml for your project 2. Run `/changelog update` after making changes 3. Run `/changelog release` when ready to publish ``` ### Retroactive Generation ```bash You: /changelog-init --from-beginning Claude: 📊 Analyzing repository history... Found: - 523 commits - 12 tagged releases - 24 contributors - First commit: 2023-03-15 Generating comprehensive changelog... ✅ Generated CHANGELOG.md with 12 versions ✅ Generated RELEASE_NOTES.md with major milestones ✅ Created configuration files Notable milestones detected: - v1.0.0: Initial release - v2.0.0: Major rewrite with breaking changes - v2.5.0: Performance optimizations ``` ### Replay Mode: Auto-Detection ```bash You: /changelog-init --replay Claude: 🔍 Analyzing repository for replay... Repository analysis: - Total commits: 523 - First commit: 2023-03-15 (619 days ago) - Releases: 12 tagged versions - Contributors: 24 - Commit frequency: 21.4 commits/week Auto-detection results: ✅ Recommended strategy: weekly Rationale: Consistent activity (15-30 commits/week) Alternative strategies: - Monthly: 20 periods, ~26 commits/period - By-Release: 12 periods, ~44 commits/period Use recommended strategy? [Y/n]: Y 📅 Calculating 74 weekly periods... - Active periods: 63 - Empty periods (skipped): 8 - Merge-only periods (skipped): 3 Proceed with analysis? [Y/n]: Y ⚙️ Executing parallel analysis (3 workers)... [Progress bar] 63/63 periods analyzed - 100% - 3m 42s elapsed ✅ Generated CHANGELOG.md (1,847 lines, hybrid format) ✅ Generated RELEASE_NOTES.md (423 lines, period-aware) ✅ Configuration saved to .changelog.yaml ✅ Cache created: .changelog-cache/ (63 period analyses) ``` ### Replay Mode: Monthly Periods ```bash You: /changelog-init --replay --period monthly Claude: 📅 Generating changelog with monthly periods... Period breakdown: - March 2023: 45 commits - April 2023: 67 commits - May 2023: 52 commits ... - November 2025: 23 commits (partial, → [Unreleased]) Total: 20 active months, 3 empty months (skipped) Analyzing in parallel (3 workers)... ✅ Complete! Generated hybrid CHANGELOG.md with 20 month sections. ``` ### Replay Mode: Release-Based ```bash You: /changelog-init --replay --period by-release Claude: 🏷️ Grouping history by releases... Detected releases: - v0.1.0 (2023-03-15): 15 commits - v0.2.0 (2023-04-12): 28 commits - v1.0.0 (2023-06-01): 67 commits (major release) - v1.1.0 (2023-07-15): 34 commits ... - v2.5.0 (2024-10-27): 42 commits - Unreleased: 23 commits Total: 12 releases + unreleased section Analyzing releases... ✅ Generated CHANGELOG.md with 13 sections (12 releases + unreleased) ``` ### Replay Mode: High-Activity Project (Daily) ```bash You: /changelog-init --replay --period daily Claude: ⚠️ Daily period strategy selected Repository has 523 commits over 619 days This will create ~619 daily periods Recommendation: Weekly or monthly might be more readable Continue with daily strategy? [y/N]: y 📅 Calculating daily periods... - Active days: 287 - Empty days (skipped): 332 Proceed? This may take ~8 minutes [Y/n]: Y ⚙️ Analyzing 287 daily periods (3 workers)... [Progress: 287/287 - 100% - 7m 53s] ✅ Generated CHANGELOG.md (3,421 lines) ⚠️ Note: Changelog is very large. Consider using weekly strategy. ``` ### Replay Mode: Custom Configuration ```bash You: /changelog-init --replay --period weekly --max-workers 5 --hybrid-format Claude: 📋 Replay configuration: - Period: Weekly (Monday-Sunday) - Workers: 5 concurrent analyses - Format: Hybrid (versions + periods) - Cache: Enabled - Skip empty: Yes - Skip merge-only: Yes ⚙️ Executing with 5 concurrent workers... [Faster execution with more parallelism] ✅ Complete in 2m 18s (vs estimated 4m with 3 workers) ``` ### Replay Mode: Regenerate Specific Period ```bash You: /changelog-init --replay-period "2024-Q3" --force Claude: 🔄 Regenerating specific period... Period: Q3 2024 (July-September) - Original analysis: 2025-01-15 - Commits in period: 87 - Previous entries: 64 changes Regenerating with current configuration... ✅ Period regenerated ✅ Updated CHANGELOG.md (merged new analysis) ✅ Backup created: CHANGELOG.2025-11-14.md.backup ``` ## Generated Files ### CHANGELOG.md Template ```markdown # 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] ### Added - Initial project setup ### Changed ### Deprecated ### Removed ### Fixed ### Security ``` ### Configuration File ```yaml # .changelog.yaml changelog: conventional_commits: true include_authors: true include_commit_hash: false categories: - Added - Changed - Deprecated - Removed - Fixed - Security release_notes: audience: "end-users" tone: "professional" use_emoji: true versioning: strategy: "semver" auto_bump: breaking: "major" features: "minor" fixes: "patch" replay: enabled: false default_strategy: "auto" performance: enable_parallel: true max_concurrent_periods: 3 enable_cache: true ``` ### Hybrid Format CHANGELOG.md (Replay Mode) ```markdown # 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). ## Table of Contents - **2025** - [Week of November 11](#week-of-november-11-2025) - Unreleased - [Week of November 4](#week-of-november-4-2025) - Unreleased - [Week of October 21](#week-of-october-21-2024) - v2.1.0 - [Week of October 14](#week-of-october-14-2024) - v2.1.0 - **2024** - [Month of September](#month-of-september-2024) - v2.0.0 ... ## [Unreleased] ### Week of November 11, 2025 #### Added - Real-time notification system with WebSocket support (#256, @dev2) - Automatic reconnection with exponential backoff - Event types: entity.created, entity.updated, entity.deleted #### Fixed - Memory leak in background job processor (#258, @dev1) ### Week of November 4, 2025 #### Added - Advanced search filters with fuzzy matching (#252, @dev3) ## [2.1.0] - 2024-10-27 ### Week of October 21, 2024 #### Added - REST API v2 with cursor-based pagination (#234, @dev1) - Backward compatible with v1 using version headers - See migration guide in docs/api/v2-migration.md #### Changed - **BREAKING:** Authentication now uses JWT tokens instead of server sessions - Sessions will be invalidated upon upgrade - Update client libraries to v2.x for compatibility ### Week of October 14, 2024 #### Fixed - Race condition in concurrent file uploads (#245, @dev2) - Implemented proper file locking mechanism #### Security - Updated dependencies to address CVE-2024-1234 (High severity) ## [2.0.0] - 2024-09-30 ### Month of September 2024 #### Added - Complete UI redesign with modern component library (#210, @design-team) - Dark mode support across all views (#215, @dev4) #### Changed - Migrated from Webpack to Vite - Development server startup reduced from 30s to 3s - Bundle size reduced by 22% #### Removed - Legacy XML export format (use JSON or CSV) - Python 3.7 support (minimum version now 3.8) [Unreleased]: https://github.com/user/repo/compare/v2.1.0...HEAD [2.1.0]: https://github.com/user/repo/compare/v2.0.0...v2.1.0 [2.0.0]: https://github.com/user/repo/releases/tag/v2.0.0 ``` ## Integration This command works with: - `/changelog update` - Add new changes - `/changelog release` - Prepare releases - Git hooks - Automate updates