mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-03 10:23:15 -04:00

Files

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

11 KiB

Raw Blame History

ClaudeForge

Automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects

ClaudeForge is a comprehensive toolkit that eliminates the tedious process of manually creating and maintaining CLAUDE.md files. With intelligent analysis, automated generation, and background maintenance, your CLAUDE.md files stay perfectly synchronized with your codebase.

🆕 New in v2.0 (Claude Code v2.1.4+ Support)

Lifecycle Hooks: Guardian agent automatically checks for updates at session start using SessionStart hooks
Modern Permissions: All components now use permissions: syntax for fine-grained control
Hot-Reload: Skills automatically reload when modified (no restart needed)
Fork-Safe Mode: Guardian runs independently with fork_safe: true without blocking operations
Version Detection: Installers validate Claude Code version and ensure compatibility
Auto-Migration: Seamless upgrade from v1.x with automatic backups

👉 Upgrading from v1.x? See docs/MIGRATION_V2.md for migration guide.

✨ Features

🚀 Interactive Initialization - Explores your repository, detects project context, and creates customized CLAUDE.md files through conversational workflow
✅ Intelligent Analysis - Scans and evaluates existing CLAUDE.md files with quality scoring (0-100) and actionable recommendations
🔧 Smart Enhancement - Adds missing sections and improves structure automatically
🛡️ Background Maintenance - Guardian agent keeps CLAUDE.md synchronized with codebase changes
📦 Modular Architecture - Supports complex projects with context-specific files (backend/, frontend/, database/)
🎯 100% Native Format - All generated files follow official Claude Code format with project structure diagrams, setup instructions, and architecture sections
🛠️ Tech Stack Customization - Tailors guidelines to TypeScript, Python, Go, React, Vue, FastAPI, and more
👥 Team Size Adaptation - Adjusts complexity based on team size (solo, small, medium, large)

📦 What's Included

1. Skill (`claudeforge-skill`)

Core capability for CLAUDE.md analysis, generation, validation, and enhancement

2. Slash Command (`/enhance-claude-md`)

Interactive interface with multi-phase discovery workflow. Delegates deep codebase scans to the Explore subagent so the discovery does not bloat the calling session.

3. Slash Command (`/sync-claude-md`)

Walks every CLAUDE.md in the project, prunes stale references (removed dependencies, deleted files, dead modular links), enforces the 150-line hard cap per file, and repairs the root ↔ subdirectory chain (markdown links + @path imports). Run after refactors, dependency changes, or before cutting a release.

4. Guardian Agent (`claude-md-guardian`)

Background agent for automatic CLAUDE.md maintenance and synchronization

5. Karpathy Guidelines Skill (`karpathy-guidelines`)

Behavioral guardrails — Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution — installed as a standalone skill and automatically embedded into every CLAUDE.md generated or enhanced by /enhance-claude-md. Adapted with attribution from the MIT-licensed forrestchang/andrej-karpathy-skills repository, inspired by Andrej Karpathy's observations on common LLM coding failure modes.

🚀 Quick Start

Installation

Claude Code Plugin (recommended)

ClaudeForge ships as a Claude Code plugin. From any Claude Code session:

/plugin marketplace add alirezarezvani/ClaudeForge
/plugin install claudeforge

This installs every component (skills, slash commands, guardian agent) and registers /enhance-claude-md and /sync-claude-md for any project. Works the same at the user level (available everywhere) or scoped to a single project.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash

Windows (PowerShell)

iwr https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.ps1 -useb | iex

Manual Installation

git clone https://github.com/alirezarezvani/ClaudeForge.git
cd ClaudeForge
./install.sh  # or .\install.ps1 on Windows

Usage

After installation, restart Claude Code and run:

/enhance-claude-md

That's it! The command will:

✅ Explore your project structure
✅ Detect tech stack and project type
✅ Show discoveries and ask for confirmation
✅ Create customized CLAUDE.md file(s)
✅ Apply best practices and native format

💡 Use Cases

New Project (No CLAUDE.md)

/enhance-claude-md

# Claude explores your repository and responds:
#
# "Based on my exploration, here's what I discovered:
#
#  📦 Project Type: Full-Stack Application
#  🛠️ Tech Stack: TypeScript, React, Node.js, PostgreSQL, Docker
#  👥 Team Size: Small (5 developers)
#  🚀 Development Phase: MVP
#
#  📋 Recommended Structure:
#  - Root CLAUDE.md (navigation hub, ~100 lines)
#  - backend/CLAUDE.md (API guidelines, ~150 lines)
#  - frontend/CLAUDE.md (React guidelines, ~175 lines)
#
#  Would you like me to create these files?"
#
# You: "Yes"
#
# ✅ CLAUDE.md created (108 lines)
# ✅ backend/CLAUDE.md created (156 lines)
# ✅ frontend/CLAUDE.md created (182 lines)

Existing Project (Needs Improvement)

/enhance-claude-md

# Claude analyzes your current CLAUDE.md:
#
# "Quality Score: 65/100
#
#  Missing Sections:
#  - Project Structure (ASCII diagram)
#  - Setup & Installation
#  - Architecture
#
#  Would you like me to enhance your CLAUDE.md with these sections?"
#
# You: "Yes"
#
# ✅ CLAUDE.md enhanced (+2 sections, quality score: 65 → 88)

Background Maintenance

# You start a new Claude Code session
# Guardian agent automatically checks for changes
#
# ✅ CLAUDE.md updated:
# - Tech Stack: Added 2 dependencies (react-query, tailwindcss)
# - Project Structure: Updated diagram with new components/ directory
# - Setup & Installation: New environment variables
#
# Changes: 3 sections, 12 lines

📚 Documentation

Document	Description
Quick Start Guide	5-minute tutorial to get started
Installation Guide	Detailed installation instructions and troubleshooting
Architecture Overview	How components work together
GitHub Workflows	CI/CD automation and quality gates
Branching Strategy	Branch flow and protection rules
Troubleshooting	Common issues and solutions
Contributing Guide	How to contribute to ClaudeForge

📖 Examples

See the examples/ directory for:

Basic usage scenarios
Modular architecture setup
Integration with existing projects
Advanced customization

🔧 Components Deep Dive

Skill: claudeforge-skill

Core Capabilities:

Analysis - Scans existing CLAUDE.md files for quality and completeness
Validation - Checks against Anthropic guidelines and best practices
Generation - Creates new CLAUDE.md files from scratch
Enhancement - Adds missing sections and improves structure
Template Selection - Chooses appropriate templates based on project context

Quality Scoring (0-100):

Length appropriateness (25 pts)
Section completeness (25 pts)
Formatting quality (20 pts)
Content specificity (15 pts)
Modular organization (15 pts)

Slash Command: /enhance-claude-md

Multi-Phase Workflow:

Discovery - Checks for existing CLAUDE.md, examines project structure
Analysis - Determines appropriate action (initialize vs. enhance)
Task - Invokes skill or agent to execute workflow

Agent: claude-md-guardian

Background Maintenance:

Auto-Sync - Updates CLAUDE.md based on detected changes
Smart Detection - Only updates when significant changes occur
Token-Efficient - Uses haiku model for routine updates
Milestone-Aware - Triggers after feature completion, refactoring, etc.

🎯 Requirements

Claude Code 2.0 or later
Git (recommended for change detection)
Operating Systems: macOS, Linux, Windows (PowerShell)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

🐛 Issues & Support

Bug Reports: GitHub Issues
Feature Requests: GitHub Discussions
Documentation: docs/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built for the Claude Code community
Inspired by best practices from Anthropic's official documentation
Special thanks to all contributors and early adopters

🚦 Project Status

Version: 1.0.0 Status: ✅ Stable & Production-Ready Last Updated: November 12, 2025

📊 Quick Stats

7 reference CLAUDE.md templates included
100% native Claude Code format compliance
5 Python modules
3 integrated components (skill, command, agent)
10+ usage examples and scenarios

🌟 Star History

If you find ClaudeForge helpful, please consider giving it a star on GitHub!

⬆ Back to Top

Made with ❤️ for the Claude Code community

11 KiB Raw Blame History