Changelog Manager

🤖 AUTO-ACTIVATION TRIGGERS

This skill AUTOMATICALLY activates when Claude detects ANY of these keywords or phrases:

🎯 Release & Version Keywords

• "update changelog"
• "prepare release"
• "create release"
• "bump version"
• "new version"
• "release v" or "version v" (e.g., "release v1.2.3")
• "major release" / "minor release" / "patch release"
• "ready to release"
• "push to production"
• "tag release"

📝 Changelog Keywords

• "update the changelog"
• "add to changelog"
• "document changes"
• "changelog entry"
• "version history"

🚀 Git Keywords

• "create git tag"
• "tag version"
• "push release"
• "release to github"

💡 Natural Language Triggers

• "I'm done with [feature], update changelog"
• "Finished implementing [feature], prepare release"
• "Ready to push these changes"
• "Let's release this"
• "Can you update the changelog?"

🎨 VISUAL OUTPUT FORMATTING

CRITICAL: Use MINIMAL colored output (2-3 calls max) to prevent screen flickering!

Use Colored-Output Skill

Example formatted output (MINIMAL PATTERN):

# START: Header only
bash .claude/skills/colored-output/color.sh skill-header "changelog-manager" "Analyzing changes for release..."

# MIDDLE: Regular text (no colored calls)
Detected version bump: v1.8.1 → v1.8.2
Updated 5 files
- CHANGELOG.md updated
- package.json updated
- README.md badge updated
Creating release v1.8.2...

# END: Result only
bash .claude/skills/colored-output/color.sh success "" "Release v1.8.2 complete!"

When to Use Colored Output

DO Use:

• Initial header: bash .claude/skills/colored-output/color.sh skill-header "changelog-manager" "Starting..."
• Final result: bash .claude/skills/colored-output/color.sh success "" "Release complete!"
• Errors only: bash .claude/skills/colored-output/color.sh error "" "Git command failed"

DON'T Use:

• ❌ Progress updates - use regular text
• ❌ Info messages - use regular text
• ❌ File updates - use regular text

WHY: Each bash call creates a task in Claude CLI, causing screen flickering. Keep it minimal!

⚡ CRITICAL: Auto-Activation Behavior for Claude

When this skill auto-activates (user says trigger keywords), Claude MUST:

1. ✅ DO NOT ask for confirmation - Skill already activated, just proceed
2. ✅ DO NOT manually invoke the skill again - It's already running
3. ✅ Proceed directly with the workflow - Start analyzing changes immediately
4. ✅ The skill is already loaded - You'll see <command-message>The "changelog-manager" skill is running</command-message>
5. ✅ USE COLORED OUTPUT - Start first response with \033[1;34m🔧 [changelog-manager]\033[0m

Example of CORRECT behavior:

User: "release update"
Claude: [Skill auto-activates]
Claude: "I'll analyze your changes and prepare the release."
Claude: [Proceeds with git status, git diff, version detection...]

Example of INCORRECT behavior (DO NOT DO THIS):

User: "release update"
Claude: [Skill auto-activates]
Claude: "Would you like me to use changelog-manager?" ❌ WRONG - Don't ask!
User: "yes"
Claude: [Manually invokes skill again] ❌ WRONG - Skill already running!

Why this matters:

• Asking for confirmation when skill already activated causes double-triggering
• Manually invoking an already-running skill creates duplicate messages
• Auto-activation means user ALREADY confirmed by using trigger keywords

🛡️ Git Command Interception (Automatic Guard)

CRITICAL: This skill automatically intercepts git commands to prevent bypassing proper release workflow!

Intercepts BEFORE executing:

• ANY git commit command (when release indicators detected)
• ANY git tag command (always intercepts)
• ANY git push command (when unpushed release-like commits exist)

Detection Logic: When Claude attempts a git command, automatically check for release indicators:

1. Analyze Changes:

   git diff --cached --name-only  # What's staged
   git diff --name-only           # What's uncommitted
   

2. Detect Release Indicators:

   • ✅ 3+ files changed → Likely a release
   • ✅ skill.md or agent.md version changed → Definitely a release
   • ✅ CHANGELOG.md modified → Definitely a release
   • ✅ README.md badges changed → Likely a release
   • ✅ package.json version changed → Definitely a release

3. Extract Version Info (if version file changed):

   # Old version vs new version
   git diff skill.md | grep "version:"
   # Example: -version: 2.4.0 / +version: 2.5.0
   

4. Block Command & Ask User:

   🛡️ GIT COMMAND INTERCEPTED
   
   Detected: changelog-manager/skill.md
   Version: 2.4.0 → 2.5.0
   
   Changes:
   - .claude/skills/changelog-manager/skill.md (version bump)
   - generic-claude-framework/skills/changelog-manager/skill.md
   - CHANGELOG.md (unreleased section)
   
   ⚠️ This looks like a release!
   
   Options:
   1. Use changelog-manager for proper release workflow
      ✅ Auto-generates CHANGELOG entry
      ✅ Updates README badges
      ✅ Runs documentation generation
      ✅ Creates commit + tag + pushes everything
   
   2. Proceed with manual git commit
      ⚠️ Skips release automation
   
   Which do you prefer? (say "use changelog-manager" or "proceed manually")
   

5. Wait for User Decision:

   • If user says "use changelog-manager" → Full release workflow
   • If user says "proceed manually" → Allow direct git command

This prevents accidentally bypassing changelog-manager, even when Claude works autonomously!

When activated, changelog-manager will:

1. ✅ Analyze all uncommitted changes
2. ✅ Generate changelog entries automatically
3. ✅ Determine appropriate version bump (patch/minor/major)
4. ✅ Update CHANGELOG.md, package.json, README.md badges
5. ✅ Auto-generate documentation for changed agents/skills
6. ✅ Commit all changes with comprehensive message
7. ✅ Create annotated git tag with version number (MANDATORY)
8. ✅ Push both commit AND tag to remote repository
9. ✅ Confirm successful release with GitHub URL

No manual invocation needed! Skill auto-activates on keywords OR git command attempts.

⚠️ CONDITIONAL REQUIREMENTS

Git Tag Creation - Context-Aware Decision

Git tags are CONDITIONAL based on project type:

✅ CREATE GIT TAGS (Public/Open-Source Projects):

• Public GitHub repositories
• Open-source projects with contributors
• Published packages (npm, composer, PyPI)
• Framework/library releases
• Projects with semantic versioning requirements

Why tags are essential here:

• GitHub Releases page for users
• Package registry integration (npm, composer)
• Semantic versioning tracking for consumers
• Rollback capabilities for public releases
• CI/CD triggers for automated publishing
• Version history integrity for contributors

❌ SKIP GIT TAGS (Private/Internal Projects):

• Private repositories for internal use
• Client projects without public releases
• Internal tools and automation scripts
• Prototype/experimental projects
• Projects without external consumers

Why tags may not be needed:

• No public release process
• Internal versioning sufficient
• CHANGELOG.md + package.json enough
• Reduces git history noise
• Simpler workflow for internal teams

🎯 Detection Strategy

Auto-detect project type by checking:

# 1. Check if remote is public GitHub
git remote -v | grep "github.com" && check if repo is public

# 2. Check for package registry files
- package.json with "private": false → Public npm package → USE TAGS
- composer.json with public packagist → USE TAGS
- pyproject.toml with PyPI config → USE TAGS

# 3. Check repository visibility
- GitHub API: Check if repo.private === false → USE TAGS
- GitLab/Bitbucket: Check visibility settings

# 4. Ask user if unclear
"This appears to be a [public/private] project. Should I create git tags for releases? (Y/n)"

📋 Decision Table

Changelog Manager Skill

A comprehensive skill for managing project changelogs, package version synchronization, semantic versioning, and automated release workflows.

🎯 Interactive Menu

If no specific command is provided, show this menu:

📋 Changelog Manager - Interactive Mode
=======================================

🚀 What would you like to do?

🔹 Option 1: Update Changelog with Uncommitted Changes
   Usage: /changelog-manager "update changelog"
   Usage: /changelog-manager "prepare release"
   Analyzes uncommitted changes and updates changelog with new version

🔹 Option 2: Create Specific Version
   Usage: /changelog-manager "release v1.2.4"
   Usage: /changelog-manager "major release" (bumps to next major version)
   Usage: /changelog-manager "minor release" (bumps to next minor version)
   Creates specific version with custom entries

🔹 Option 3: Review Current Changes
   Usage: /changelog-manager "review changes"
   Shows what would be added to changelog without committing

📝 Version Types:
• Patch (default): Bug fixes and minor improvements (1.2.3 → 1.2.4)
• Minor: New features, non-breaking changes (1.2.3 → 1.3.0)
• Major: Breaking changes, major updates (1.2.3 → 2.0.0)

💡 Examples:
• /changelog-manager "I've finished the new subscription filtering feature, update changelog"
• /changelog-manager "Ready to release v1.5.0"
• /changelog-manager "Review what changes would be included"

🔒 Security & Privacy:
========================
✅ Automatically filters out admin/backend changes
✅ Excludes technical implementation details
✅ Only includes user-facing improvements
✅ Removes sensitive information from changelog

⚙️  Workflow:
========================
1. 📊 Analyze uncommitted git changes
2. 🔍 Filter out admin/internal changes
3. 📝 Generate user-friendly changelog entries
4. 📈 Determine version increment (patch/minor/major)
5. ✍️  Update CHANGELOG.md
6. 📦 Update package.json version
7. 📦 Update composer.json version (if exists)
8. 💾 Commit ALL changes (including updated package files)
9. 🚀 Push to remote repository

Overview

This skill automates the complete changelog update and version release process for SubsHero, ensuring:

• User-focused changelog entries (no technical jargon)
• Privacy-first approach (no internal details exposed)
• Semantic versioning compliance
• Automatic package version synchronization (package.json + composer.json)
• Automated git commit and push workflow

Capabilities

🔍 Change Analysis

• Analyze uncommitted changes using git status and diff
• Identify modified, added, and deleted files
• Understand code changes and their user impact
• Filter out admin and internal changes automatically

🔒 Privacy & Security

Automatically excludes from public changelog:

• Admin panel improvements and backend tools
• Database migrations and schema changes
• API endpoints and middleware updates
• Configuration and environment changes
• Logging, debugging, and monitoring tools
• Authentication and security updates
• Deployment scripts and infrastructure
• Test improvements and code refactoring

Only includes in changelog:

• New user-facing features
• UI/UX improvements
• Bug fixes affecting user experience
• Performance improvements users can notice
• Integration with new platforms

📊 Version Management

• Patch increment (default): 1.2.3 → 1.2.4
• Minor increment: 1.2.3 → 1.3.0
• Major increment: 1.2.3 → 2.0.0
• Automatic version detection from CHANGELOG.md
• Semantic versioning compliance

✍️ Changelog & Package Version Updates

• Standard changelog format (Keep a Changelog)
• Organized by change type:
  • Added: New features
  • Changed: Modifications to existing features
  • Fixed: Bug fixes
  • Improved: Performance and UX improvements
• User-friendly, non-technical language
• Clear dates and version numbers
• Automatic package version synchronization:
  • Updates package.json version field
  • Updates composer.json version field (if exists)
  • Ensures all version numbers align with CHANGELOG.md

🚀 Git Automation

• Stage ALL uncommitted files
• Create comprehensive commit messages
• Push changes to remote repository
• Verify successful completion
• Detailed operation summary

Workflow Steps

5. Package Version Synchronization

CRITICAL: Version Alignment Across All Package Files

After updating CHANGELOG.md, the skill MUST update package version numbers to maintain consistency.

5.1 Update package.json

• Read current package.json
• Update version field to match CHANGELOG.md version
• Example: "version": "2.3.9" → "version": "2.3.10"

5.2 Update composer.json (if version field exists)

• Read current composer.json
• Check if version field exists (OPTIONAL)
• If exists, update to match CHANGELOG.md version
• Note: composer.json version field may not exist

Important Notes:

• composer.json version field is OPTIONAL - only update if it exists
• package.json version field is REQUIRED - always update
• Both files MUST match the CHANGELOG.md version number
• Version format: semantic versioning (MAJOR.MINOR.PATCH)

6. README.md Badge Updates

Automatic Badge & Release Section Synchronization

After updating version in CHANGELOG.md and package.json, update README.md:

6.1 Update Version Badge

• Search for version badge pattern: [![Version](https://img.shields.io/badge/version-X.X.X-orange)]
• Update version number to match new release
• Ensures README displays correct version at all times

Example:

# Before
[![Version](https://img.shields.io/badge/version-1.1.0-orange)](CHANGELOG.md)

# After
[![Version](https://img.shields.io/badge/version-1.2.0-orange)](CHANGELOG.md)

6.2 Update Agent/Skill Count Badges

Automatic Count Calculation:

Count actual agents and skills in framework directories:

# Count agents (directories in generic-claude-framework/agents/)
AGENT_COUNT=$(find generic-claude-framework/agents -maxdepth 1 -type d ! -name agents | wc -l)

# Count skills (directories in generic-claude-framework/skills/)
SKILL_COUNT=$(find generic-claude-framework/skills -maxdepth 1 -type d ! -name skills | wc -l)

Update badges with calculated counts:

# Before
[![Agents](https://img.shields.io/badge/agents-14-blue)](docs/AGENT_CATALOG.md)
[![Skills](https://img.shields.io/badge/skills-11-green)](docs/SKILL_CATALOG.md)

# After (if counts changed)
[![Agents](https://img.shields.io/badge/agents-15-blue)](docs/AGENT_CATALOG.md)
[![Skills](https://img.shields.io/badge/skills-12-green)](docs/SKILL_CATALOG.md)

Why Auto-Calculate?

• Always accurate (no manual updates needed)
• Reflects current framework state
• Prevents badge drift from reality

6.3 Add/Update Latest Release Section

Create "Latest Release" Section:

Insert after badges, before main content (after line with badges, before "## 🎯 What is This?"):

<details open>
<summary><b>📦 Latest Release: v1.7.0 (2025-10-22)</b></summary>

### Added
- cli-modern-tools Skill v1.1.0 with automatic command replacement
  - New cli-wrapper.sh script for auto-detection and fallback
  - Auto-replaces: cat→bat, ls→eza, find→fd, tree→eza --tree

### Changed
- Documentation generator now supports selective updates
  - New flags: --skill <name>, --agent <name>, --catalogs-only

[View Full Changelog →](CHANGELOG.md)
</details>

Extraction Logic:

1. Parse CHANGELOG.md to find latest version entry
2. Extract content between ## [X.X.X] - YYYY-MM-DD and next ##
3. Format into collapsible <details> block
4. Replace existing "Latest Release" section or insert if missing

Benefits:

• Users see latest changes immediately on GitHub
• Collapsible to keep README clean
• Auto-extracted from CHANGELOG (single source of truth)
• Always shows current version

6.4 Smart Documentation Generation

Automatic Agent/Skill Documentation Updates

Before committing, intelligently regenerate documentation for changed agents/skills:

Detection Logic:

# Detect changed agent files
CHANGED_AGENTS=$(git diff --name-only --cached | grep "generic-claude-framework/agents/.*/agent.md" | sed 's|generic-claude-framework/agents/\(.*\)/agent.md|\1|')

# Detect changed skill files
CHANGED_SKILLS=$(git diff --name-only --cached | grep "generic-claude-framework/skills/.*/skill.md" | sed 's|generic-claude-framework/skills/\(.*\)/skill.md|\1|')

Selective Documentation Generation:

1. If agent files changed:

   for agent in $CHANGED_AGENTS; do
     python scripts/generate_docs.py --agent "$agent"
   done
   

2. If skill files changed:

   for skill in $CHANGED_SKILLS; do
     python scripts/generate_docs.py --skill "$skill"
   done
   

3. Always update catalogs (to reflect new counts):

   # Catalogs are auto-updated by selective generation
   # They include updated counts and links
   

What Gets Regenerated:

• Agent changed: generic-claude-framework/agents/<agent-name>/README.md
• Skill changed: generic-claude-framework/skills/<skill-name>/README.md
• Always: docs/AGENT_CATALOG.md and docs/SKILL_CATALOG.md

Benefits:

• ✅ Zero mental overhead - Docs auto-update during releases
• ✅ Smart & selective - Only regenerates changed items
• ✅ Always in sync - Documentation matches code state
• ✅ Faster commits - Selective generation is quick
• ✅ Clean git diffs - Only relevant docs change

Example Flow:

User: "Prepare release v1.8.0"

Detected changes:
- generic-claude-framework/skills/cli-modern-tools/skill.md (modified)

Actions:
1. Update CHANGELOG, package.json, README badges
2. Run: python scripts/generate_docs.py --skill cli-modern-tools
   → Regenerates: cli-modern-tools/README.md
   → Updates: SKILL_CATALOG.md, AGENT_CATALOG.md
3. Stage all updated files
4. Commit + tag + push

Result: All documentation automatically synchronized!

7. Git Operations

Complete Release Workflow:

1. Stage All Changes

   # Stage release files
   git add CHANGELOG.md package.json README.md [composer.json if exists]
   
   # Stage generated documentation (if any)
   git add docs/AGENT_CATALOG.md docs/SKILL_CATALOG.md
   git add generic-claude-framework/agents/*/README.md
   git add generic-claude-framework/skills/*/README.md
   

2. Create Comprehensive Commit

   git commit -m "Release vX.X.X - [Brief summary]
   
   ## Version X.X.X
   
   Updated CHANGELOG.md, package.json, and README.md to reflect version X.X.X.
   
   ### Highlights
   [Key changes from changelog]
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   
   Co-Authored-By: Claude <noreply@anthropic.com>"
   

3. Create Git Tag

   git tag -a vX.X.X -m "Release vX.X.X - [Brief summary]"
   

4. Push to Remote

   git push origin main && git push origin vX.X.X
   

5. Create GitHub Release

   # Extract release notes from CHANGELOG.md for this version
   # Use gh CLI to create formatted GitHub Release
   gh release create vX.X.X \
     --title "Release vX.X.X - [Brief summary]" \
     --notes "$(cat <<'EOF'
   [Extract content from CHANGELOG.md for this version]
   
   See [CHANGELOG.md](CHANGELOG.md) for full details.
   EOF
   )"
   

6. Verify Success

   • Confirm commit pushed successfully
   • Confirm tag created on remote
   • Confirm GitHub Release published
   • Provide GitHub release URL

🎬 COMPLETE AUTOMATED WORKFLOW

⚠️ CRITICAL: Follow EVERY step below. NO steps can be skipped!

When user says: "update changelog" or "prepare release"

✅ STEP 1: Analyze Changes

🔧 BASH COMMAND ATTRIBUTION PATTERN:

CRITICAL: Before executing EACH bash command, MUST output:

🔧 [changelog-manager] Running: <command>

MUST RUN ALL THREE COMMANDS WITH ATTRIBUTION:

1. Announce: 🔧 [changelog-manager] Running: git status Execute: git status to find uncommitted changes

2. Announce: 🔧 [changelog-manager] Running: git diff --stat Execute: git diff --stat to see file change summary

3. Announce: 🔧 [changelog-manager] Running: git log --oneline -5 Execute: git log --oneline -5 to see recent commit patterns

Output to user: Summarize what files changed (X files modified, Y additions, Z deletions)

✅ STEP 2: Determine Version Bump

MUST analyze changes and decide version bump type:

Automatic Detection Rules:

• MAJOR bump (X.0.0) if:

  • User says "major release" OR "breaking changes"
  • CHANGELOG mentions "BREAKING" or "Breaking Changes"
  • Files deleted or major refactoring detected

• MINOR bump (X.Y.0) if:

  • User says "minor release" OR "new feature"
  • New directories/files created
  • Significant additions detected (>100 lines added)
  • CHANGELOG mentions "Added" or "New Feature"

• PATCH bump (X.Y.Z) if:

  • User says "patch release" OR "bug fix"
  • Only modifications to existing files
  • Small changes (<100 lines)
  • CHANGELOG mentions "Fixed" or "Bug Fix"
  • DEFAULT if unclear

Read current version from CHANGELOG.md (top version number)

Calculate new version (e.g., 1.9.0 → 1.10.0 for MINOR)

Output to user: "Current version: X.Y.Z → New version: X.Y.Z (MINOR release)"

✅ STEP 3: Generate Changelog Entry

MUST create comprehensive changelog entry:

Structure:

## [X.X.X] - YYYY-MM-DD

### Added
- [New features based on git diff analysis]

### Changed
- [Modifications based on git diff analysis]

### Fixed
- [Bug fixes based on git diff analysis]

### Documentation
- [Documentation updates]

Content Analysis:

• Parse git diff for file changes
• Identify new files → "Added" section
• Identify modified files → "Changed" section
• Look for "fix" in commit messages → "Fixed" section
• Look for documentation changes → "Documentation" section

Output to user: Show draft changelog entry for review

✅ STEP 4: Update All Version Files

MUST update ALL version files (no exceptions):

4.1 Update CHANGELOG.md:

• Add new version entry at top (after [Unreleased])
• Update version links at bottom:

  [Unreleased]: https://github.com/USER/REPO/compare/vX.X.X...HEAD
  [X.X.X]: https://github.com/USER/REPO/compare/vX.Y.Z...vX.X.X
  

4.2 Update package.json:

• Change "version" field to new version

4.3 Update README.md:

• Update version badge: [![Version](https://img.shields.io/badge/version-X.X.X-orange)](CHANGELOG.md)

4.4 Update composer.json (if exists):

• Check if file exists with test -f composer.json
• If exists, update "version" field

Output to user: "Updated 3-4 version files: CHANGELOG.md, package.json, README.md [, composer.json]"

✅ STEP 5: Generate Documentation (CRITICAL - DO NOT SKIP!)

⚠️ MANDATORY STEP - This step was previously missed!

MUST run documentation generation script WITH ATTRIBUTION:

1. Announce: 🔧 [changelog-manager] Running: python scripts/generate_docs.py Execute: python scripts/generate_docs.py

This script:

• Regenerates all agent READMEs
• Regenerates all skill READMEs
• Updates AGENT_CATALOG.md
• Updates SKILL_CATALOG.md

Check if documentation was generated WITH ATTRIBUTION:

2. Announce: 🔧 [changelog-manager] Running: git status --short | grep -E "(README.md|CATALOG.md)" Execute: git status --short | grep -E "(README.md|CATALOG.md)"

Expected output: 20-30 documentation files updated

Output to user: "Generated documentation: X agent READMEs, Y skill READMEs, 2 catalogs updated"

If script fails: Report error and ask user how to proceed

✅ STEP 6: Detect Project Type & Git Tag Decision

MUST determine if git tags should be created:

Auto-Detection Process:

# 1. Check package.json for "private" field
PRIVATE=$(cat package.json | grep '"private": true')

# 2. Check git remote for public GitHub
GITHUB_PUBLIC=$(git remote -v | grep "github.com")

# 3. Decision logic
if [[ -z "$PRIVATE" && -n "$GITHUB_PUBLIC" ]]; then
    USE_TAGS=true   # Public GitHub repo → Use tags
else
    USE_TAGS=false  # Private/internal → Skip tags
fi

Ask user if unclear:

"This project appears to be [public/private]. Should I create git tags for this release? (Y/n)"

Output to user: "Project type: [public/private] → Git tags: [enabled/disabled]"

✅ STEP 7: Stage ALL Changes

MUST stage ALL modified files:

git add -A

This includes:

• CHANGELOG.md
• package.json
• README.md
• composer.json (if exists)
• All generated documentation files (agent READMEs, skill READMEs, catalogs)
• Any other modified files from the original changes

Verify staging WITH ATTRIBUTION:

Announce: 🔧 [changelog-manager] Running: git status --short Execute: git status --short

Output to user: "Staged X files for commit"

✅ STEP 8: Create Release Commit

MUST create comprehensive commit message:

git commit -m "$(cat <<'EOF'
Release vX.X.X - [Brief Summary]

## Version X.X.X

Updated CHANGELOG.md, package.json, README.md, and auto-generated documentation to reflect version X.X.X.

### Highlights
[Top 3 changes from changelog]

### Files Updated
- CHANGELOG.md (added vX.X.X entry)
- package.json (X.Y.Z → X.X.X)
- README.md (version badge updated)
- Documentation: X agent READMEs, Y skill READMEs, 2 catalogs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Verify commit WITH ATTRIBUTION:

Announce: 🔧 [changelog-manager] Running: git log -1 --oneline Execute: git log -1 --oneline

Output to user: "Created commit: [commit hash] Release vX.X.X"

✅ STEP 9: Create Git Tag (if enabled)

IF git tags enabled (public project):

git tag -a vX.X.X -m "Release vX.X.X - [Brief Summary]"

Verify tag:

git tag -l vX.X.X

Output to user: "Created tag: vX.X.X"

IF git tags disabled (private project):

• Skip this step
• Output to user: "Skipping git tag (private project)"

✅ STEP 10: Push to Remote

MUST push commit and tag (if enabled):

IF git tags enabled:

git push origin main && git push origin vX.X.X

IF git tags disabled:

git push origin main

Output to user: "Pushed to origin/main [+ tag vX.X.X]"

✅ STEP 11: Verify & Report

MUST verify all steps completed:

git status  # Should show "working tree clean"

Output comprehensive summary:

Success Message (Public Project with Tags):

✅ Release vX.X.X Complete!

📋 Updated Files:
- CHANGELOG.md (added vX.X.X entry)
- package.json (X.Y.Z → X.X.X)
- README.md (version badge updated)
- Documentation: X agent READMEs, Y skill READMEs, 2 catalogs

🏷️  Git Tag: vX.X.X created
🚀 Pushed to: origin/main

🔗 View Release:
https://github.com/USER/REPO/releases/tag/vX.X.X

📝 Summary:
- Added: [Count] new features
- Changed: [Count] improvements
- Fixed: [Count] bug fixes

Success Message (Private Project without Tags):

✅ Release vX.X.X Complete!

📋 Updated Files:
- CHANGELOG.md (added vX.X.X entry)
- package.json (X.Y.Z → X.X.X)
- README.md (version badge updated)
- Documentation: X agent READMEs, Y skill READMEs, 2 catalogs

🚀 Pushed to: origin/main

📝 Summary:
- Added: [Count] new features
- Changed: [Count] improvements
- Fixed: [Count] bug fixes

💡 Note: Git tags skipped (private project)

🔍 VERIFICATION CHECKLIST

⚠️ CRITICAL: Before reporting success, Claude MUST verify ALL items below:

Pre-Commit Verification

• ✅ Ran git status and analyzed uncommitted changes
• ✅ Ran git diff --stat and reviewed changes
• ✅ Determined correct version bump (MAJOR/MINOR/PATCH)
• ✅ Read current version from CHANGELOG.md
• ✅ Calculated new version number correctly
• ✅ Generated comprehensive changelog entry
• ✅ Updated CHANGELOG.md with new version entry
• ✅ Updated CHANGELOG.md version links at bottom
• ✅ Updated package.json version field
• ✅ Updated README.md version badge
• ✅ Checked for composer.json and updated if exists
• ✅ Ran python scripts/generate_docs.py (MANDATORY!)
• ✅ Verified documentation files were generated (git status)
• ✅ Staged ALL files with git add -A
• ✅ Verified staging with git status --short

Commit Verification

• ✅ Created commit with comprehensive message
• ✅ Commit message includes version number
• ✅ Commit message includes highlights
• ✅ Commit message includes documentation update count
• ✅ Verified commit with git log -1 --oneline

Tag & Push Verification

• ✅ Determined if project is public/private
• ✅ Created git tag (if public) OR skipped tag (if private)
• ✅ Pushed commit to origin/main
• ✅ Pushed tag to origin (if public)
• ✅ Verified with git status (working tree clean)

Final Verification

• ✅ All version numbers match across all files
• ✅ Documentation was generated and committed
• ✅ Commit includes ALL changes (original + version files + docs)
• ✅ Remote repository updated successfully
• ✅ Reported comprehensive summary to user

If ANY checkbox is unchecked, the release is INCOMPLETE!

❌ Common Mistakes to Avoid

1. Skipping documentation generation - ALWAYS run python scripts/generate_docs.py
2. Forgetting to stage documentation - Use git add -A to stage everything
3. Not verifying staging - Always check git status --short before commit
4. Incomplete commit message - Must mention documentation updates
5. Not checking working tree - Verify git status shows clean after push
6. Skipping verification checklist - ALWAYS go through all checkboxes

Step 7: Confirm & Report

Success Message (Public Project with Tags & GitHub Release):

✅ Release v1.2.0 Complete!

📋 Updated Files:
- CHANGELOG.md (added v1.2.0 entry)
- package.json (1.1.0 → 1.2.0)
- README.md (version badge updated)

🏷️  Git Tag: v1.2.0 created
🚀 Pushed to: origin/main
📦 GitHub Release: Published

🔗 View Release:
https://github.com/USER/REPO/releases/tag/v1.2.0

📝 Summary:
- Added: [Count] new features
- Changed: [Count] improvements
- Fixed: [Count] bug fixes

Success Message (Private Project without Tags):

✅ Release v1.2.0 Complete!

📋 Updated Files:
- CHANGELOG.md (added v1.2.0 entry)
- package.json (1.1.0 → 1.2.0)
- README.md (version badge updated)

🚀 Pushed to: origin/main

📝 Summary:
- Added: [Count] new features
- Changed: [Count] improvements
- Fixed: [Count] bug fixes

💡 Note: Git tags skipped (private project)

🔄 INTEGRATION WITH COMMIT WORKFLOW

Proactive Auto-Detection:

Claude should automatically invoke this skill when:

1. After Making Code Changes: User completes task and says:

   • "I'm done"
   • "Finished implementing [feature]"
   • "All done with [task]"
   • → Claude asks: "Would you like me to update the changelog and create a release?"

2. Before Major Commits: User has significant uncommitted changes

   • → Claude suggests: "I notice you have significant changes. Should I prepare a changelog entry?"

3. User Mentions Release Intent:

   • Any of the trigger keywords detected
   • → Claude automatically activates changelog-manager

Example Conversation:

User: "I've finished adding the ecosystem reference feature"

Claude: "Great! I notice you have uncommitted changes. Would you like me to:
1. Update the changelog with these changes
2. Bump the version (this looks like a minor release)
3. Create a git tag and push to GitHub?

This will create version 1.2.0 based on the ecosystem reference feature."

User: "Yes, do it"

Claude: [Automatically invokes changelog-manager skill]
→ Analyzes changes
→ Updates CHANGELOG.md with v1.2.0
→ Updates package.json to 1.2.0
→ Updates README.md badge
→ Commits all changes
→ Creates git tag v1.2.0
→ Pushes to GitHub
→ Reports success

🛡️ GIT COMMAND GUARD (Anti-Bypass Protection)

Purpose: Prevent accidentally bypassing changelog-manager when using direct git commands.

How It Works

Before ANY git commit/tag/push command executes, this guard automatically:

1. Scans for Release Indicators:

   # Check staged changes
   git diff --cached --name-only
   
   # Look for these patterns
   - 3+ files changed
   - skill.md with version: X.Y.Z changed
   - agent.md with version: X.Y.Z changed
   - CHANGELOG.md modified
   - README.md badges changed
   - package.json version changed
   

2. Extracts Version Information:

   # If version file detected, show old vs new
   git diff skill.md | grep -E "^[-+]version:"
   # Example output:
   # -version: 2.5.0
   # +version: 2.6.0
   

3. Blocks Command & Presents Options:

   🛡️ GIT COMMAND INTERCEPTED
   
   I detected you're about to commit changes that look like a release:
   
   File: changelog-manager/skill.md
   Version Change: 2.5.0 → 2.6.0
   
   Files to be committed (5):
   - .claude/skills/changelog-manager/skill.md (version bump detected)
   - generic-claude-framework/skills/changelog-manager/skill.md
   - CHANGELOG.md (unreleased changes)
   - docs/SKILL_CATALOG.md
   - README.md
   
   ⚠️ RECOMMENDATION: Use changelog-manager for proper release workflow
   
   Option 1: Use changelog-manager (Recommended)
   ✅ Auto-generates CHANGELOG entry from git changes
   ✅ Updates all version references (package.json, README badges)
   ✅ Generates documentation for changed agents/skills
   ✅ Creates semantic commit message
   ✅ Creates annotated git tag v2.6.0
   ✅ Pushes commit + tag to GitHub
   ✅ Complete release in one command
   
   Option 2: Proceed with manual commit (Not recommended)
   ⚠️ You'll need to manually:
      - Update CHANGELOG.md with entries
      - Update version badges in README
      - Run documentation generation
      - Create git tag manually
      - Push tag separately
   
   What would you like to do?
   - Say "use changelog-manager" for Option 1
   - Say "proceed manually" for Option 2
   

4. Waits for User Decision:

   • User says "use changelog-manager" → Invokes full release workflow
   • User says "proceed manually" → Allows direct git command (with warning logged)

What Gets Intercepted

Always Intercepted:

• git tag -a v... → Always assumes this is a release
• git commit when CHANGELOG.md is modified
• git commit when skill.md/agent.md version changed
• git commit when package.json version changed

Conditionally Intercepted:

• git commit with 3+ files → Asks user
• git commit with README.md badges → Asks user
• git push with unpushed commits that look like releases → Asks user

Never Intercepted:

• git commit with single file (typo fix, WIP)
• git commit on feature branches (not main)
• git status, git diff, git log (read-only operations)
• git push with only documentation commits

Examples

Example 1: Version Bump Detected

You: [working autonomously, Claude bumps skill version 2.5.0 → 2.6.0]
Claude: [attempts git commit...]
Guard: 🛡️ INTERCEPTED - Version change detected
Guard: [Shows prompt with options]
You: "use changelog-manager"
Guard: ✅ Invoking changelog-manager...
changelog-manager: [runs full release workflow]
Result: Proper v2.6.0 release created

Example 2: Multiple Files, No Version

You: [changed 5 files across different features]
Claude: [attempts git commit...]
Guard: 🛡️ INTERCEPTED - 5 files changed
Guard: "This looks like a release. Use changelog-manager?"
You: "proceed manually" (it's just WIP work)
Guard: ✅ Allowing manual commit
Result: Manual commit proceeds

Example 3: Single File Change

You: [fixed typo in README]
Claude: [attempts git commit...]
Guard: [No interception - single trivial file]
Result: Direct commit allowed (fast path)

Benefits

1. Prevents Bypass: Even when Claude works autonomously, can't skip proper release workflow
2. User Control: Always asks before forcing changelog-manager
3. Smart Detection: Knows the difference between releases and WIP commits
4. Educational: Shows what proper release workflow would do
5. Safe Fallback: User can always choose manual if needed

Configuration

No configuration needed! The guard is always active and automatically detects release patterns.

To disable guard (not recommended):

• Add --skip-guard flag to git commands
• Or explicitly say "I know this is a release but proceed manually anyway"

Version History

v2.1.0

• AUTO-ACTIVATION: Skill now automatically activates on release keywords
• COMPLETE WORKFLOW: Added comprehensive 6-step automated workflow
• README BADGE SYNC: Automatically updates version badges in README.md
• GIT TAG AUTOMATION: Creates and pushes git tags automatically
• INTELLIGENT VERSION DETECTION: Analyzes changes to suggest MAJOR/MINOR/PATCH
• PROACTIVE SUGGESTIONS: Claude asks about changelog when task completed
• COMPREHENSIVE DOCS: Detailed workflow steps and integration examples

v2.0.0

• BREAKING: Now automatically updates package.json and composer.json versions
• Added package version synchronization feature
• Enhanced commit messages to include package file updates
• Improved version mismatch detection and resolution

v1.0.0

• Initial release
• Automatic change analysis and filtering
• User-focused changelog generation
• Semantic versioning support
• Automated git commit and push

Support

For issues or questions:

• Ensure git repository is initialized
• Verify CHANGELOG.md exists (will be created if missing)
• Verify package.json exists (will be created if missing)
• Ensure package.json and composer.json are valid JSON