ClaudeForge/CHANGELOG.md

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]

Added (wave 3 — adoption hardening)

• Command discovery metadata (command/enhance-claude-md.md, command/sync-claude-md.md): both commands now declare allowed-tools, disallowedTools (blocks WebFetch/WebSearch), argument-hint, and when_to_use so Claude Code can auto-suggest and zero-prompt them.
• Path-scoped Karpathy guidelines (skill/karpathy-guidelines/SKILL.md): paths: glob on code-file extensions (*.py, *.ts, *.go, *.rs, etc.) so the guardrails load only when editing code, not when editing markdown or data.
• Cheaper skill execution (skill/SKILL.md): model: haiku, effort: medium, and paths: scoping the skill to CLAUDE.md / AGENTS.md / .claude/rules/*.md so validator + generator passes run cheaply without affecting the user-facing model.
• CLAUDE.local.md personal tier: validator.BestPracticesValidator now accepts filename= and waives the 150-line cap for any *.local.md file. hooks/validate-claude-md.py is exempt-suffix aware too. .gitignore excludes CLAUDE.local.md, **/CLAUDE.local.md, .claude/settings.local.json, and hooks/hooks-config.local.json.
• Layered hook config (hooks/hooks-config.json shared + hooks/hooks-config.local.json gitignored): validate-claude-md.py merges the two and honours validateClaudeMd.enabled: false, maxLines, exemptFilenameSuffix, and exitCodeOnViolation. Teams can opt out per developer without forking the shipped config.
• Stop audit hook (hooks/audit-claude-md.py + entry in hooks/hooks.json): prints a 1-line summary to stderr at session end — total CLAUDE.md tracked, count over the cap, count near it — so users see drift before the session's context is lost.
• Fail-closed contract on guardian (agent/claude-md-guardian.md Safety & Validation section): the guardian now states it invokes claude-md-enhancer exclusively through the Skill tool (never paraphrases SKILL.md content), aborts on missing validated output, never auto-commits, and respects the local hook config.

Patterns adapted (with attribution and in original prose) from the MIT-licensed shanraisshan/claude-code-best-practice.

Fixed

• Guardian agent hook frontmatter (agent/claude-md-guardian.md): rewritten from the array-of-objects shape (hooks: [{ event, commands }]) to Anthropic's canonical keyed-object shape (hooks: { EventName: [{ matcher, hooks: [{ type: "command", command }] }] }). The previous shape did not match the documented schema, so the guardian's hooks did not fire. (docs)

Added

• Plugin-level hooks (hooks/hooks.json + hooks/validate-claude-md.py): every Edit/Write to a CLAUDE.md and every InstructionsLoaded event (all five load_reason values — session_start, nested_traversal, path_glob_match, include, compact) runs validate-claude-md.py, which exits 2 with stderr feedback when the touched file exceeds the 150-line cap. Turns the cap from advisory into deterministic enforcement at load time and write time.
• generate_rules_file() on ContentGenerator (skill/generator.py): emits path-scoped .claude/rules/*.md instruction files with name, description, and paths: glob frontmatter. Claude loads these conditionally when accessing files that match the globs, so file-type-specific guidance (e.g. backend-only standards) no longer has to live in the root CLAUDE.md.
• AGENTS.md / .cursorrules / .windsurfrules interop: command/enhance-claude-md.md Phase 1 now detects these sibling instruction files, and ContentGenerator.generate_root_file() prepends an ## External Instructions section with @AGENTS.md-style imports when project_context['existing_instruction_files'] lists them. Repos already using other agent tooling can adopt ClaudeForge without losing their existing instructions.

Added (earlier in this Unreleased window)

• Claude Code plugin manifest (.claude-plugin/plugin.json): ClaudeForge is now installable as a Claude Code plugin via /plugin marketplace add alirezarezvani/ClaudeForge && /plugin install claudeforge. Manifest registers all skills, commands, and the guardian agent in one bundle.
• /sync-claude-md slash command (command/sync-claude-md.md): walks every CLAUDE.md in the project, prunes stale references (removed dependencies, deleted paths, broken modular links), enforces the 150-line cap, and repairs the root ↔ sub chain. Designed to run after refactors, dependency changes, or before a release.
• Karpathy Guidelines skill (skill/karpathy-guidelines/SKILL.md): behavioural-guardrail skill applied to every coding, review, and refactoring task. Covers four principles — Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution — adapted with attribution from the MIT-licensed forrestchang/andrej-karpathy-skills repository.
• Automatic embedding into every CLAUDE.md: skill/template_selector.py and skill/generator.py insert a ## Behavioral Guidelines section into every generated and enhanced CLAUDE.md.
• Modular chaining via @path imports: the modular root generator emits both human-readable markdown links and Claude Code @path/to/CLAUDE.md imports for every sub-CLAUDE.md. Sub-files now get a back-link header pointing to the root file so navigation is bidirectional.
• Explore-agent delegation in /enhance-claude-md: deep project scans are delegated to the Explore subagent to keep the calling session's context lean.

Changed

• Hard 150-line cap per CLAUDE.md: validator.MAX_RECOMMENDED_LINES lowered from 300 to 150 (warning at 120). template_selector.TEAM_SIZE_TEMPLATES target lines lowered to fit (solo 75 / small 100 / medium 125 / large 150). analyzer length thresholds and quality scoring rebased on the new cap. Projects that need more content split it across chained sub-files instead of growing the root.
• Installers register commands as top-level files: install.sh and install.ps1 now install each .md under command/ as its own ~/.claude/commands/<name>.md (registering as /<name>) rather than bundling the whole directory under one path. Legacy ~/.claude/commands/enhance-claude-md/ bundles are backed up automatically on upgrade.

Verified

• Smoke tests: validator constants, all four team-size templates, generator output for solo/small/medium/large + library presets (all ≤ 150 lines), context files with back-links, @-import chain in modular root, idempotent merge_with_existing, validator status transitions (pass / warning / fail) at the new cap, analyzer quality score differential between compliant and bloated files, plugin manifest JSON shape and that every referenced path exists on disk.

---

[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

• Repository: https://github.com/alirezarezvani/ClaudeForge
• Issues: https://github.com/alirezarezvani/ClaudeForge/issues
• Discussions: https://github.com/alirezarezvani/ClaudeForge/discussions
• Releases: https://github.com/alirezarezvani/ClaudeForge/releases

---

Made with ❤️ for the Claude Code community