justin/ClaudeForge
1
0
Fork 0
mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-03 18:33:16 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
c374cc28a1465c26eea191b31fde5071513478d8
ClaudeForge/CHANGELOG.md
T
Claude a45e6f5dbd feat(plugin): ship as Claude Code plugin with 150-line cap and sync command 
Turns ClaudeForge into an installable Claude Code plugin and adds the
missing pieces for a clean lifecycle: hard line-cap enforcement, modular
chaining via @path imports, a sync/cleanup command, and Explore-agent
delegation for project discovery.

- .claude-plugin/plugin.json: plugin manifest registering both skills,
  both commands, and the guardian agent (installable via /plugin marketplace
  add alirezarezvani/ClaudeForge && /plugin install claudeforge)
- skill/validator.py: MAX_RECOMMENDED_LINES 300 -> 150 (warning at 120)
- skill/template_selector.py: target_lines capped at 150 across all
  team sizes (solo 75 / small 100 / medium 125 / large 150) so any
  single CLAUDE.md fits within the cap; bigger projects spread content
  across modular sub-files
- skill/analyzer.py: length thresholds, quality scoring, and recommendations
  rebased on the 150 cap (was 300/400)
- skill/generator.py: modular root now emits @path imports next to the
  human-readable links; every sub-CLAUDE.md gets a back-link header
  pointing to ../CLAUDE.md (markdown + @import) for bidirectional chaining
- command/sync-claude-md.md: new /sync-claude-md command that inventories
  every CLAUDE.md, prunes stale references, enforces the 150 cap by
  splitting into sub-files, and repairs the root <-> sub chain
- command/enhance-claude-md.md: discovery phase now delegates the deep
  codebase scan to the Explore subagent to keep context lean
- install.sh / install.ps1: each command in command/ installs as its own
  ~/.claude/commands/<name>.md (legacy bundle backed up on upgrade)
- skill/SKILL.md, CLAUDE.md, README.md, CHANGELOG.md: docs updated for
  the plugin install path, sync command, and new line cap

Verified via smoke test: validator constants, template targets, generator
output line counts across 5 presets (all <= 150), context files with
backlinks, @-import chain in modular root, idempotent merge_with_existing,
validator status transitions at the new cap, analyzer quality differential,
and plugin manifest JSON shape with all referenced paths existing on disk.
2026-05-19 02:03:59 +00:00

15 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]

Added

  • 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

Made with ❤️ for the Claude Code community

Reference in New Issue View Git Blame Copy Permalink