CLAUDE.md · diff
git:20260518.ffff0fc to git:20260519.032c5e5
46 added, 493 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# CLAUDE.md
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
- ---
+ Top-level guidance for Claude Code when working on this repository.
## Project Overview
- **ClaudeForge** is a comprehensive toolkit for automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects. The repository consists of four integrated components:
-
- 1. **Skill** (`claudeforge-skill`) - Core Python modules for analysis, generation, and validation
- 2. **Slash Command** (`/enhance-claude-md`) - Interactive multi-phase discovery workflow
- 3. **Guardian Agent** (`claude-md-guardian`) - Background maintenance agent
- 4. **Karpathy Guidelines Skill** (`karpathy-guidelines`) - Behavioral guardrails embedded into every generated CLAUDE.md and installed as a standalone skill, adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repository
-
- ---
-
- ## What's New in v2.0.0
-
- **Claude Code v2.1.4+ Support:**
- - **Lifecycle Hooks**: Guardian agent uses SessionStart, PreToolUse, PostToolUse hooks
- - **Modern Permissions**: Updated to `permissions:` array syntax
- - **Hot-Reload**: Skills auto-reload when modified (no restart needed)
- - **Fork-Safe Mode**: Guardian runs independently with `fork_safe: true`
- - **Auto-Migration**: Seamless upgrade from v1.x with automatic backups
-
- **Migration:** See `docs/MIGRATION_V2.md` for upgrading from v1.0.0.
-
- ---
-
- ## Architecture
-
- ### Component Interaction Flow
-
- ```
- User Project
- ↓
- /enhance-claude-md (Slash Command)
- ↓
- [Phase 1: Discovery] → [Phase 2: Analysis] → [Phase 3: Task]
- ↓
- claude-md-guardian (Agent) OR Direct Skill Invocation
- ↓
- claudeforge-skill (Python Modules)
- ↓
- workflow.py → analyzer.py → validator.py → template_selector.py → generator.py
- ↓
- CLAUDE.md Created/Updated with 100% Native Format
- ```
-
- ### Python Module Architecture
-
- The skill consists of 5 core modules (~2,190 lines):
-
- **workflow.py (432 lines)** - `InitializationWorkflow` class
- - Orchestrates interactive initialization for new projects
- - Methods: `check_claude_md_exists()`, `generate_exploration_prompt()`, `analyze_discoveries()`
- - Detects: project type, tech stack, team size, development phase, workflows
- - Returns: Project context dictionary for template selection
-
- **analyzer.py (382 lines)** - `CLAUDEMDAnalyzer` class
- - Analyzes existing CLAUDE.md files
- - Methods: `analyze_file()`, `detect_sections()`, `calculate_quality_score()`, `generate_recommendations()`
- - Quality scoring: 0-100 based on length (25pts), completeness (25pts), formatting (20pts), specificity (15pts), modularity (15pts)
- - Returns: Analysis report with quality score and actionable recommendations
-
- **validator.py (429 lines)** - `BestPracticesValidator` class
- - Validates against Anthropic guidelines
- - Methods: `validate_length()`, `validate_structure()`, `validate_formatting()`, `validate_completeness()`, `validate_all()`
- - Checks: file length (20-300 lines), required sections, markdown formatting, anti-patterns
- - Returns: Validation report with pass/fail status and detailed issues
-
- **template_selector.py (467 lines)** - `TemplateSelector` class
- - Selects appropriate template based on context
- - Methods: `select_template()`, `customize_template()`, `recommend_modular_structure()`
- - Logic: Maps project type + team size → template complexity
- - Returns: Template configuration with target line count and modular recommendation
-
- **generator.py (480 lines)** - `ContentGenerator` class
- - Generates new or enhanced CLAUDE.md content
- - Methods: `generate_root_file()`, `generate_context_file()`, `generate_section()`, `merge_with_existing()`
- - Supports: Root files, context-specific files (backend/, frontend/, database/), individual sections
- - Returns: Complete CLAUDE.md content with 100% native format compliance
-
- ### Critical Validation Rule
-
- All generated CLAUDE.md files MUST include:
- - Project structure (ASCII tree diagram)
- - File structure explanations
- - Setup & installation instructions
- - Architecture section (for complex projects)
- - Validation against `/update-claude-md` slash command format
- - Cross-check against reference examples in `skill/examples/`
-
- ---
-
- ## Installation & Testing
-
- ### Test Installation Scripts
-
- ```bash
- # macOS/Linux
- ./install.sh
- # Choose option 1 (user-level) or 2 (project-level)
- # Verify installation at ~/.claude/ or ./.claude/
-
- # Windows
- .\install.ps1
- # Same options as above
-
- # Verify components installed:
- ls -la ~/.claude/skills/claudeforge-skill/
- ls -la ~/.claude/commands/enhance-claude-md/
- ls -la ~/.claude/agents/claude-md-guardian.md
- ```
-
- ### Directory Structure After Installation
-
- ```
- ~/.claude/ # User-level installation
- ├── skills/
- │ └── claudeforge-skill/ # Copied from skill/
- │ ├── SKILL.md
- │ ├── analyzer.py
- │ ├── validator.py
- │ ├── generator.py
- │ ├── template_selector.py
- │ ├── workflow.py
- │ └── examples/ # 7 reference templates
- ├── commands/
- │ └── enhance-claude-md/ # Copied from command/
- │ └── enhance-claude-md.md
- └── agents/
- └── claude-md-guardian.md # Copied from agent/
- ```
-
- ---
-
- ## Development Workflow
-
- ### Modifying Python Modules
-
- When updating skill modules (analyzer.py, generator.py, etc.):
-
- 1. Edit files in `skill/` directory
- 2. Test changes by reinstalling: `./install.sh` (choose option 2 for project-level testing)
- 3. Test skill invocation in Claude Code: `/enhance-claude-md`
- 4. Validate output against reference examples in `skill/examples/`
- 5. Update `CHANGELOG.md` with changes
-
- ### Modifying Slash Command
-
- When updating `/enhance-claude-md` command:
-
- 1. Edit `command/enhance-claude-md.md`
- 2. Key sections to modify:
- - **Phase 1 (Discovery)**: Bash commands that check project state
- - **Phase 2 (Analysis)**: Logic that determines initialize vs. enhance
- - **Phase 3 (Task)**: Skill/agent invocation logic
- 3. Test by reinstalling command: `cp command/enhance-claude-md.md ~/.claude/commands/enhance-claude-md/`
- 4. Restart Claude Code and test: `/enhance-claude-md`
-
- ### Modifying Guardian Agent
-
- When updating `claude-md-guardian` agent:
-
- 1. Edit `agent/claude-md-guardian.md`
- 2. Key YAML frontmatter fields:
- - `permissions`: [Bash, Read, Write, Edit, Grep, Glob, Skill]
- - `model`: Set to `haiku` for token efficiency
- - `color`: Visual indicator (purple)
- - `fork_safe`: Set to `true` for independent execution
- - `hooks`: Array of lifecycle hooks (SessionStart, PreToolUse, PostToolUse)
- 3. Agent workflow phases:
- - Phase 1: Assessment (check git changes)
- - Phase 2: Analysis (determine scope)
- - Phase 3: Update (invoke skill for targeted updates)
- 4. Test: `cp agent/claude-md-guardian.md ~/.claude/agents/`
-
- **Example Agent Definition with v2.0.0 Syntax:**
- ```yaml
- ---
- name: claude-md-guardian
- permissions: [Bash, Read, Write, Edit, Grep, Glob, Skill]
- model: haiku
- color: purple
- fork_safe: true
- hooks:
- - SessionStart
- - PreToolUse
- - PostToolUse
- ---
- ```
-
- ### Adding New Templates
-
- To add a new reference template (e.g., Rust, mobile):
-
- 1. Create new template file in `skill/examples/`
- 2. Follow native format structure:
- - Project structure diagram (ASCII tree)
- - Setup & installation
- - Architecture section
- - Tech-specific guidelines
- 3. Update `skill/examples/README.md` with new template description
- 4. Update `template_selector.py` logic to detect when to use new template
- 5. Add test case in `skill/sample_input.json`
-
- ---
-
- ## Testing & Validation
-
- ### Manual Testing Checklist
-
- **Test New Project Initialization:**
- ```bash
- # 1. Create test project
- mkdir test-project && cd test-project
- git init
- npm init -y # or create package.json
-
- # 2. Run slash command
- /enhance-claude-md
-
- # 3. Verify Claude:
- # - Explores repository
- # - Detects TypeScript/Node project
- # - Shows discoveries
- # - Asks for confirmation
- # - Creates CLAUDE.md with native format
- ```
-
- **Test Existing Project Enhancement:**
- ```bash
- # 1. Create basic CLAUDE.md
- echo "# CLAUDE.md\n\n## Tech Stack\n- TypeScript" > CLAUDE.md
-
- # 2. Run slash command
- /enhance-claude-md
+ **ClaudeForge** is a Claude Code plugin (manifest at `.claude-plugin/plugin.json`) and standalone toolkit for the CLAUDE.md lifecycle: initialise, enhance, sync, and modularise files with a hard **150-line cap**, automatic chaining via `@path` imports, and Karpathy behavioural guardrails. Works in any Claude Code or Claude.cowork project.
- # 3. Verify Claude:
- # - Analyzes existing file
- # - Calculates quality score (0-100)
- # - Identifies missing sections (Project Structure, Setup, etc.)
- # - Asks to enhance
- # - Adds missing native format sections
- ```
+ Five components ship in this repo:
- **Test Guardian Agent:**
- ```bash
- # 1. Make significant changes
- npm install react # Add new dependency
- mkdir src/components # New directory
+ 1. **Skill** (`claudeforge-skill`, in `skill/`) — Python modules for analysis, generation, validation. Enforces the 150-line cap.
+ 2. **Slash command** (`/enhance-claude-md`, in `command/`) — interactive init/enhance workflow. Delegates deep codebase scans to the Explore subagent.
+ 3. **Slash command** (`/sync-claude-md`, in `command/`) — walks every CLAUDE.md, prunes stale references, enforces the 150-line cap, repairs the root ↔ sub chain.
+ 4. **Guardian agent** (`claude-md-guardian`, in `agent/`) — background sync triggered by `SessionStart` / `PreToolUse` / `PostToolUse` hooks.
+ 5. **Karpathy guidelines skill** (`karpathy-guidelines`, in `skill/karpathy-guidelines/`) — behavioural guardrails embedded into every generated CLAUDE.md. Adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repo.
- # 2. Start new Claude Code session (triggers SessionStart)
+ Current version: **2.1.0** — see `CHANGELOG.md`. v1 → v2 upgrade: `docs/MIGRATION_V2.md`.
- # 3. Verify agent:
- # - Detects changes via git diff
- # - Updates CLAUDE.md automatically
- # - Reports: "Tech Stack: Added react", "Project Structure: Updated diagram"
- ```
+ ## Quick Navigation
- ### Quality Validation
+ - [Skill development](skill/CLAUDE.md)
+ - [Slash command development](command/CLAUDE.md)
+ - [Guardian agent development](agent/CLAUDE.md)
+ - [Installation, testing & release](docs/CLAUDE.md)
- All generated CLAUDE.md files should pass these checks:
+ Chained context (Claude Code auto-imports these):
- ```python
- # Use validator.py
- validator = BestPracticesValidator(content)
- results = validator.validate_all()
+ @skill/CLAUDE.md
+ @command/CLAUDE.md
+ @agent/CLAUDE.md
+ @docs/CLAUDE.md
- # Expected passes:
- # - File length: 20-300 lines (or modular if >300)
- # - Structure: Required sections present
- # - Formatting: Valid markdown, proper heading hierarchy
- # - Completeness: Code examples, tech stack, workflows
- # - Anti-patterns: No hardcoded secrets, no TODOs/placeholders
- ```
+ ## Behavioral Guidelines
- ---
+ Behavioural guardrails applied to every coding, review, and refactoring task in this repo. Full skill: `~/.claude/skills/karpathy-guidelines/SKILL.md`.
- ## File Organization
+ 1. **Think before coding.** State load-bearing assumptions; if a request has multiple reasonable interpretations, surface them instead of picking silently. Stop and ask when something is genuinely unclear.
+ 2. **Simplicity first.** Write the minimum code that solves the stated problem. No speculative abstractions, no unrequested configuration, no error handling for conditions that cannot occur.
+ 3. **Surgical changes.** Touch only what the task requires. Match surrounding style. Every changed line should trace directly to the user's request.
+ 4. **Goal-driven execution.** Convert vague requests into verifiable success criteria before coding (failing test first), and state a step-by-step plan with per-step verification for multi-step work.
- ### Repository Structure
+ ## Repository Layout (top level)
```
ClaudeForge/
- ├── skill/ # Python modules (core capability)
- │ ├── analyzer.py # File analysis
- │ ├── validator.py # Best practices validation
- │ ├── generator.py # Content generation
- │ ├── template_selector.py # Template selection logic
- │ ├── workflow.py # Interactive initialization
- │ ├── SKILL.md # Skill definition (YAML frontmatter)
- │ ├── sample_input.json # Test scenarios (6 examples)
- │ ├── expected_output.json # Expected outputs
- │ └── examples/ # 7 reference templates
- │
- ├── command/ # Slash command definition
- │ ├── enhance-claude-md.md # Multi-phase workflow
- │ └── README.md
- │
- ├── agent/ # Guardian agent definition
- │ ├── claude-md-guardian.md # Background maintenance agent
- │ └── README.md
- │
- ├── docs/ # Documentation
- │ ├── INSTALLATION.md
- │ ├── QUICK_START.md
- │ ├── ARCHITECTURE.md
- │ ├── TROUBLESHOOTING.md
- │ └── CONTRIBUTING.md
- │
- ├── examples/ # Usage examples (markdown)
- ├── hooks/ # Quality hooks (pre-commit)
- ├── .github/ # GitHub templates & workflows
- │ ├── workflows/validate.yml # CI/CD validation
- │ ├── ISSUE_TEMPLATE/
- │ ├── PULL_REQUEST_TEMPLATE.md
- │ └── CODE_OF_CONDUCT.md
- │
- ├── install.sh # macOS/Linux installer
- ├── install.ps1 # Windows installer
- ├── README.md # Project overview
- ├── CHANGELOG.md # Version history
- ├── LICENSE # MIT License
- └── CLAUDE.md # This file
- ```
-
- ### Important: Dual Directory Structure
-
- Note the duplication: `claude-md-enhancer/` (legacy) and `skill/` (current). When making changes:
- - **Always edit `skill/`** - This is the active version used by installers
- - `claude-md-enhancer/` is kept for reference but not actively maintained
-
- ---
-
- ## Common Operations
-
- ### Update Reference Templates
-
- ```bash
- # Edit template
- vim skill/examples/python-api-CLAUDE.md
-
- # Test template selection
- # 1. Create test project matching template criteria
- mkdir test-python-api && cd test-python-api
- echo "fastapi" > requirements.txt
-
- # 2. Run slash command and verify template is used
- /enhance-claude-md
- ```
-
- ### Update Quality Scoring Logic
-
- ```bash
- # Edit analyzer.py
- vim skill/analyzer.py
-
- # Update calculate_quality_score() method
- # Current scoring breakdown:
- # - length_appropriateness: 25 points (20-300 lines ideal)
- # - section_completeness: 25 points (required sections present)
- # - formatting_quality: 20 points (markdown, headings, code blocks)
- # - content_specificity: 15 points (project-specific, not generic)
- # - modular_organization: 15 points (context files if needed)
-
- # Test scoring
- python3 -c "
- from skill.analyzer import CLAUDEMDAnalyzer
- with open('test-CLAUDE.md') as f:
- analyzer = CLAUDEMDAnalyzer(f.read())
- report = analyzer.analyze_file()
- print(f'Quality Score: {report[\"quality_score\"]}/100')
- "
- ```
-
- ### Update Installer Scripts
-
- ```bash
- # Edit installer
- vim install.sh # or install.ps1
-
- # Key sections:
- # - Installation paths (user-level vs project-level)
- # - Component copying (skill, command, agent)
- # - Backup logic (existing installations)
- # - Quality hooks installation (optional)
-
- # Test installer
- ./install.sh
- # Choose test option and verify all components copied correctly
- ```
-
- ---
-
- ## Integration Points
-
- ### Skill ↔ Slash Command
-
- The slash command invokes the skill via:
- ```markdown
- # In command/enhance-claude-md.md, Phase 3:
-
- I can invoke the `claude-md-enhancer` skill directly to handle the appropriate workflow based on what I discovered above.
- ```
-
- Claude Code recognizes the skill name `claude-md-enhancer` and calls Python modules.
-
- ### Skill ↔ Guardian Agent
-
- The agent uses the skill as its core capability:
- ```yaml
- # In agent/claude-md-guardian.md:
- permissions: [Bash, Read, Write, Edit, Grep, Glob, Skill]
- hooks:
- - SessionStart # Detects project changes on session start
- - PreToolUse # Validates before tool execution
- - PostToolUse # Validates after CLAUDE.md updates
- ```
-
- Agent invokes skill with: `Skill: claude-md-enhancer` in agent workflow.
-
- **Example Hook Usage:**
- ```markdown
- # When SessionStart hook triggers:
- 1. Check git diff for changes
- 2. If significant changes detected → invoke skill
- 3. Update CLAUDE.md automatically
-
- # When PostToolUse hook triggers after Edit/Write to CLAUDE.md:
- 1. Validate updated content with validator.py
- 2. Report quality score
- 3. Suggest improvements if needed
- ```
-
- ### Agent ↔ Git
-
- Agent detects changes via git commands:
- ```bash
- git diff --name-status HEAD~10
- git log --since="1 week ago" --oneline --no-merges
- git diff HEAD~10 -- package.json requirements.txt
+ ├── .claude-plugin/plugin.json # plugin manifest
+ ├── skill/ # core Python modules + karpathy-guidelines/
+ ├── command/ # /enhance-claude-md, /sync-claude-md
+ ├── agent/ # claude-md-guardian
+ ├── docs/ # operational docs (installation, testing, release)
+ ├── examples/ # usage examples
+ ├── hooks/ # quality hooks (pre-commit)
+ ├── .github/ # CI workflows, issue/PR templates
+ ├── install.sh / install.ps1 # installers
+ ├── README.md / CHANGELOG.md / LICENSE
+ └── CLAUDE.md # this file
```
- Triggers update when:
- - 5+ files modified
- - New dependencies added
- - New directories created
- - Manual invocation after milestone
-
- ---
-
- ## Tech Stack Detection Logic
-
- The workflow and template selector detect tech stacks via:
-
- **Frontend Detection:**
- - React: `package.json` contains `"react"`
- - Vue: `package.json` contains `"vue"`
- - Angular: `angular.json` exists
- - TypeScript: `tsconfig.json` exists
-
- **Backend Detection:**
- - Node.js: `package.json` exists
- - Python: `requirements.txt`, `pyproject.toml`, `setup.py`
- - Go: `go.mod` exists
- - Java: `pom.xml`, `build.gradle`
- - Rust: `Cargo.toml` exists
-
- **Database Detection:**
- - PostgreSQL: `package.json` or `requirements.txt` contains "pg" or "psycopg2"
- - MongoDB: Contains "mongoose" or "pymongo"
- - Redis: Contains "redis" or "ioredis"
-
- Update detection logic in: `skill/workflow.py` → `_detect_tech_stack()` method
-
- ---
-
- ## Repository Naming
-
- **Project Name:** ClaudeForge
- **GitHub URL:** https://github.com/alirezarezvani/ClaudeForge
- **Skill Name:** `claudeforge-skill` (installed as directory name)
- **Slash Command:** `/enhance-claude-md` (fixed name, cannot be changed by user)
- **Agent Name:** `claude-md-guardian` (file name)
-
- When updating references:
- - `skill/SKILL.md` → YAML frontmatter `name: claude-md-enhancer` (kept for compatibility)
- - `README.md` → Use "ClaudeForge" as display name
- - `install.sh` → Copies to `claudeforge-skill/` directory
- - Internal documentation → Use "ClaudeForge" consistently
-
- ---
-
- ## Version Management
-
- **Current Version:** 2.0.0 (see CHANGELOG.md)
- **Versioning:** Semantic Versioning (MAJOR.MINOR.PATCH)
-
- When releasing new version:
- 1. Update `CHANGELOG.md` with changes under new version header
- 2. Update version in `README.md` badge
- 3. Update version in `skill/SKILL.md` bottom section
- 4. Create git tag: `git tag -a v2.1.0 -m "Release v2.1.0"`
- 5. Push tag: `git push origin v2.1.0`
- 6. Create GitHub release with CHANGELOG excerpt
-
- ---
+ ## Naming Reference
- ## License & Copyright
+ - **Project / display name:** ClaudeForge
+ - **GitHub:** https://github.com/alirezarezvani/ClaudeForge
+ - **Skill name (frontmatter):** `claude-md-enhancer` (kept for backwards compatibility); installed as `claudeforge-skill/`
+ - **Slash commands:** `/enhance-claude-md`, `/sync-claude-md` (names fixed by file name)
+ - **Agent:** `claude-md-guardian`
+ - **Standalone skill:** `karpathy-guidelines`
- **License:** MIT License
- **Copyright:** © 2025 Alireza Rezvani
+ ## License
- All files should include appropriate copyright headers. The LICENSE file is authoritative.
+ MIT — © 2025 Alireza Rezvani. See `LICENSE`.