justin/ClaudeForge
1
0
Fork 0
mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-03 02:13:15 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
e7512689c18cf78b0421e778852f0089ed20bab6
ClaudeForge/CHANGELOG.md
T

13 KiB
Raw Blame History

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[2.0.0] - 2026-01-08

🎉 Major Update: Claude Code v2.1.4+ Support

ClaudeForge v2.0.0 modernizes the toolkit for Claude Code v2.1.4+ with hooks, modern permission syntax, and enhanced automation capabilities.

Added

Claude Code v2.1.4+ Features

  • Lifecycle Hooks: Guardian agent now uses SessionStart, PreToolUse, and PostToolUse hooks for automatic maintenance
    • SessionStart hook checks for CLAUDE.md updates on every new session
    • PreToolUse hook validates changes before writing
    • PostToolUse hook confirms successful updates
  • Modern Permission Syntax: All components migrated to permissions: array format
    • Skill uses permissions.allow: array with wildcard support
    • Command uses permissions.allow: with tool-specific wildcards
    • Agent uses permissions.allow: with comprehensive tool access
  • Fork-Safe Mode: Guardian agent configured with fork_safe: true for independent execution
  • Hot-Reload Support: Skills automatically reload when modified (Claude Code 2.1.0+ feature)
  • Version Detection: Installers now detect Claude Code version and validate compatibility
    • Warns if Claude Code < 2.1.0 (limited features)
    • Recommends Claude Code 2.1.4+ for full functionality
    • Exits if Claude Code < 2.0
  • Auto-Migration System: Automatic migration from v1.x with timestamped backups
    • Detects v1.x installations using syntax analysis
    • Creates dated backups before upgrading
    • Validates v2.1.4 compatibility after installation

Documentation

  • Migration Guide: Comprehensive docs/MIGRATION_V2.md with step-by-step instructions
    • Covers permission syntax changes
    • Documents hooks functionality
    • Provides troubleshooting guide
    • Includes rollback procedures
  • Testing Scripts: Complete test suite in test/ directory
    • test/validate_migration.sh - 18 automated validation tests
    • test/rollback.sh - One-command rollback to v1.x
    • test/README.md - Testing documentation and workflows
    • test/LOCAL_TESTING_GUIDE.md - Step-by-step local testing guide
  • Updated Documentation: All docs now reference Claude Code v2.1.4+ features
    • CLAUDE.md - Updated with v2.0.0 features and permission syntax examples
    • README.md - Added "New in v2.0" section highlighting features

Changed

  • Skill Frontmatter (skill/SKILL.md):

    • tools: field → permissions.allow: array
    • Added wildcard Bash permissions: Bash(ls:*), Bash(find:*), Bash(git:*)

  • Command Frontmatter (command/enhance-claude-md.md):

    • allowed-tools: field → permissions.allow: array
    • Added startup hook for workflow initiation

  • Agent Frontmatter (agent/claude-md-guardian.md):

    • tools: field → permissions.allow: array
    • Added fork_safe: true for independent operation
    • Added SessionStart hook for auto-updates
    • Added PreToolUse/PostToolUse hooks for Write validation
    • Removed obsolete mcp_tools: none field

  • Installation Scripts:

    • install.sh: Added Claude Code version detection and validation
    • install.ps1: Added Claude Code version detection and validation
    • Both scripts now include post-installation compatibility checks

  • Version Requirements:

    • Minimum: Claude Code 2.1.0
    • Recommended: Claude Code 2.1.4+
    • Previous: Claude Code 2.0+

Fixed

  • Installation Script: Fixed bash syntax error in install.sh caused by missing quotes around color variables in read -p commands (#13, #19)

    • Added proper quoting around ${BLUE} and ${NC} variables in command substitution
    • Prevents "syntax error near unexpected token" during installation on macOS
    • Credit to @bartdorlandt for original fix

  • CI Workflow: Removed strict branch naming requirement for PRs into dev (#17)

    • Contributors can now use any branch name when creating PRs
    • Reduces friction for external contributors and fork PRs
    • Maintains PR title validation (Conventional Commits) for commit hygiene

  • Compatibility: All components now fully compatible with Claude Code v2.1.4+

    • Hooks work correctly with SessionStart events
    • Permission wildcards properly recognized
    • Hot-reload enabled for skill modifications

Deprecated

  • Old Permission Syntax: tools: and allowed-tools: fields deprecated in favor of permissions:
    • Still backward compatible for existing installations
    • Migration guide provides upgrade path

Breaking Changes

  • Minimum Claude Code Version: Now requires Claude Code 2.1.0+ (was 2.0+)
  • Frontmatter Syntax: Old tools: and allowed-tools: syntax deprecated
  • Users on Claude Code < 2.1.0: Should remain on ClaudeForge v1.0.0

Migration

👉 Upgrading from v1.0.0? See docs/MIGRATION_V2.md for detailed migration instructions.

Quick Migration:

# Backup first
cp -r ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill.backup

# Run installer (auto-migrates)
./install.sh

# Restart Claude Code
exit
claude

Notes

  • Python Modules: All 5 Python modules (analyzer.py, validator.py, generator.py, template_selector.py, workflow.py) remain unchanged and backward compatible
  • Examples: All 7 reference CLAUDE.md templates unchanged
  • Functionality: Core analysis, generation, and validation features identical to v1.0.0

[1.0.0] - 2025-11-12

🎉 Initial Release

ClaudeForge v1.0.0 marks the first stable release of the automated CLAUDE.md management toolkit for Claude Code projects.

Added

Core Features

  • Interactive Initialization Workflow - Conversational workflow that explores repositories, detects project context, and creates customized CLAUDE.md files
  • 100% Native Format Compliance - All generated files follow official Claude Code format with project structure diagrams, setup instructions, and architecture sections
  • Intelligent Analysis - Comprehensive file analysis with quality scoring (0-100) and actionable recommendations
  • Smart Enhancement - Automatic addition of missing sections and structure improvements
  • Best Practice Validation - Validation against Anthropic guidelines and community standards

Components

  • Skill: claudeforge-skill v1.0.0

    • analyzer.py - File analysis and quality scoring (382 lines)
    • validator.py - Best practices validation (429 lines)
    • generator.py - Content generation (480 lines)
    • template_selector.py - Template selection logic (467 lines)
    • workflow.py - Interactive initialization workflow (432 lines)

  • Slash Command: /enhance-claude-md v1.0.0

    • Multi-phase discovery workflow (Discovery → Analysis → Task)
    • Auto-detection of initialization vs. enhancement scenarios
    • Integration with skill and guardian agent

  • Guardian Agent: claude-md-guardian v1.0.0

    • Background maintenance and auto-sync
    • Smart change detection (git-based)
    • Token-efficient updates using haiku model
    • Milestone-aware triggering

Templates

  • 7 Reference CLAUDE.md Templates:
    • minimal-solo-CLAUDE.md - Solo developer projects
    • core-small-team-CLAUDE.md - Small team projects (2-9 devs)
    • python-api-CLAUDE.md - Python API projects
    • modular-root-CLAUDE.md - Root navigation for modular setups
    • modular-backend-CLAUDE.md - Backend-specific guidelines
    • modular-frontend-CLAUDE.md - Frontend-specific guidelines
    • Reference examples covering TypeScript, Python, React, FastAPI, and more

Tech Stack Support

  • Frontend: React, Vue, Angular, TypeScript, JavaScript
  • Backend: Node.js, Python (Django, FastAPI, Flask), Go, Java (Spring Boot), Ruby (Rails)
  • Databases: PostgreSQL, MongoDB, Redis, MySQL
  • Infrastructure: Docker, Kubernetes, CI/CD systems

Team Size Adaptation

  • Solo - Minimal guidelines (50-75 lines)
  • Small (<10) - Core guidelines (100-150 lines)
  • Medium (10-50) - Detailed guidelines (200-300 lines)
  • Large (50+) - Comprehensive guidelines (modular architecture)

Installation

  • Automated Installers:
    • install.sh - macOS/Linux bash installer
    • install.ps1 - Windows PowerShell installer
  • Installation Options:
    • User-level (~/.claude/) - Available in all projects
    • Project-level (./.claude/) - Current project only
  • One-line Installation: 
    curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash

Documentation

  • Root Documentation:

    • README.md - Comprehensive project overview with badges and quick start
    • CHANGELOG.md - Version history (this file)
    • LICENSE - MIT License

  • Detailed Guides:

    • docs/INSTALLATION.md - Installation guide with troubleshooting
    • docs/QUICK_START.md - 5-minute tutorial
    • docs/ARCHITECTURE.md - Component architecture and data flow
    • docs/TROUBLESHOOTING.md - Common issues and solutions
    • docs/CONTRIBUTING.md - Contribution guidelines

  • Usage Examples:

    • examples/basic-usage.md - Basic usage scenarios
    • examples/modular-setup.md - Modular architecture examples
    • examples/integration-examples.md - Integration patterns

GitHub Integration

  • CI/CD:

    • .github/workflows/validate.yml - Automated validation workflow
    • Quality checks on pull requests

  • Community Templates:

    • .github/ISSUE_TEMPLATE/bug_report.md - Bug report template
    • .github/ISSUE_TEMPLATE/feature_request.md - Feature request template
    • .github/PULL_REQUEST_TEMPLATE.md - Pull request template
    • .github/CODE_OF_CONDUCT.md - Code of conduct

Quality Hooks

  • Pre-commit Hook - hooks/pre-commit.sh
    • Validates CLAUDE.md file quality before commits
    • Ensures best practices compliance
    • Optional installation during setup

Quality Metrics

  • Quality Score Calculation (0-100):

    • Length appropriateness: 25 points
    • Section completeness: 25 points
    • Formatting quality: 20 points
    • Content specificity: 15 points
    • Modular organization: 15 points

  • Validation Checks (5 categories):

    • File length (20-300 lines recommended)
    • Structure (required sections present)
    • Formatting (markdown quality)
    • Completeness (essential content)
    • Anti-patterns (security, placeholders)

Technical Details

  • Python Version: 3.7+ compatible
  • Dependencies: Standard library only (no external dependencies)
  • Total Code: ~2,190 lines across 5 modules
  • Claude Code Compatibility: 2.0+
  • Operating Systems: macOS, Linux, Windows

What's Next

See Unreleased section for planned features.

[Unreleased]

Planned for v1.1.0

  • Additional Templates:

    • Rust/Cargo projects
    • Mobile (React Native, Flutter)
    • Desktop (Electron, Tauri)
    • Microservices architecture template

  • Enhanced Detection:

    • Improved tech stack detection accuracy
    • Project phase detection from git history
    • Team size estimation from commit patterns

  • Quality Improvements:

    • More granular quality scoring
    • Section-specific recommendations
    • Automated fix suggestions

Planned for v1.2.0

  • VS Code Extension (Future)

    • Inline CLAUDE.md editing
    • Real-time validation
    • Quick actions panel

  • GitHub Actions (Enhanced)

    • Automated CLAUDE.md generation on repo creation
    • PR checks for CLAUDE.md quality
    • Auto-update on dependency changes

  • Advanced Hooks:

    • Pre-push validation
    • Post-merge synchronization
    • Automated quality reports

Under Consideration

  • Multi-language Support - i18n for generated content
  • Custom Template Creation - User-defined templates
  • AI-Powered Suggestions - Context-aware recommendations
  • Integration with Other Tools - Slack, Discord notifications
  • Web Dashboard - Project-wide CLAUDE.md management
  • Analytics - Usage patterns and effectiveness metrics

Version History

Version Date Status Highlights
1.0.0 2025-11-12 ✅ Stable Initial release with full feature set

Contributing

See CONTRIBUTING.md for details on how to contribute to ClaudeForge.

Links

Made with ❤️ for the Claude Code community

Reference in New Issue View Git Blame Copy Permalink