Multi-Phase Discovery: Automatically detects if CLAUDE.md exists and determines appropriate action
Interactive Workflow: For new projects, explores repository and asks for confirmation before creating files
Quality Analysis: For existing projects, analyzes current CLAUDE.md and provides actionable recommendations
100% Native Format Compliance: Generates files with project structure diagrams, setup instructions, architecture sections
Modular Architecture Support: Creates context-specific CLAUDE.md files (backend/, frontend/, database/)
v2.0.0: Enhanced hooks support with background execution and conditional triggers

Installation

Option 1: Project-Level (Current Project Only)

# Copy command to your project
cp -r command /path/to/your/project/.claude/commands/

# Or create symlink
ln -s $(pwd)/command /path/to/your/project/.claude/commands/enhance-claude-md

Option 2: User-Level (All Projects)

# Copy command to user commands directory
cp -r command ~/.claude/commands/

# Restart Claude Code

Usage

Basic Usage (Auto-Detect)

/enhance-claude-md

Claude will:

Check if CLAUDE.md exists in your project
If not found: Run interactive initialization workflow
If found: Analyze and offer enhancement recommendations

New Project (No CLAUDE.md)

When you run /enhance-claude-md on a new project:

Phase 1: Discovery
- Checks for existing CLAUDE.md files
- Examines project structure
- Reviews git status

Phase 2: Analysis
- Detects project type (web_app, api, fullstack, etc.)
- Identifies tech stack (TypeScript, Python, React, etc.)
- Estimates team size and development phase

Phase 3: Task
- Shows you the discoveries
- Asks for confirmation
- Creates customized CLAUDE.md file(s)
- Applies native format (project structure diagrams, setup, architecture)

Example Output:

Based on my exploration, here's what I discovered:

📦 Project Type: Full-Stack Application
🛠️ Tech Stack: TypeScript, React, Node.js, PostgreSQL
👥 Team Size: Small (5 developers)
🚀 Development Phase: MVP

📋 Recommended Structure:
- Root CLAUDE.md (~100 lines)
- backend/CLAUDE.md (~150 lines)
- frontend/CLAUDE.md (~175 lines)

Would you like me to create these files?

Existing Project (CLAUDE.md exists)

When you run /enhance-claude-md on an existing project:

Phase 1: Discovery
- Finds existing CLAUDE.md
- Checks for modular files

Phase 2: Analysis
- Analyzes current file for quality
- Calculates quality score (0-100)
- Identifies missing sections

Phase 3: Task
- Shows quality report
- Recommends improvements
- Offers to enhance with missing sections

Example Output:

Current CLAUDE.md Quality Score: 65/100

Missing Sections:
- Project Structure (ASCII diagram)
- Setup & Installation
- Architecture

Issues:
- File length: 320 lines (recommend <300)
- No project structure diagram
- Missing setup instructions

Would you like me to enhance your CLAUDE.md with these sections?

Command Structure

The command follows the Multi-Phase Pattern (similar to codebase-analyze):

Phase 1: Discovery

Checks for CLAUDE.md existence
Examines project structure
Reviews git status

Phase 2: Analysis

Determines appropriate workflow (initialize vs. enhance)
Provides context about current state

Phase 3: Task

Invokes claude-md-enhancer skill
Executes appropriate workflow based on analysis

Prerequisites

Required:

claudeforge-skill must be installed
- Project-level: .claude/skills/claudeforge-skill/
- User-level: ~/.claude/skills/claudeforge-skill/
- v2.0.0: Auto-migrates from old claude-md-enhancer name

Recommended:

Git repository (for better context detection)
Project files in place (package.json, requirements.txt, etc.)

Advanced Usage

Specify Project Type

/enhance-claude-md

"I need a CLAUDE.md for my Python FastAPI project with PostgreSQL"

Request Modular Architecture

/enhance-claude-md

"Create a modular CLAUDE.md setup with separate files for backend, frontend, and database"

Analyze Only

/enhance-claude-md

"Just analyze my current CLAUDE.md, don't make changes yet"

Enhance Specific Sections

/enhance-claude-md

"Add Project Structure and Setup & Installation sections to my CLAUDE.md"

Output

The command can invoke either the claudeforge-skill directly OR the claude-md-guardian agent (recommended for maintenance).

Option A: Direct Skill Invocation

The skill generates:

For New Projects

Root CLAUDE.md: Navigation hub with native format sections
Context Files (if modular): backend/CLAUDE.md, frontend/CLAUDE.md, etc.

Native Format Sections Included:

Overview
Project Structure (ASCII tree diagram)
File Structure (directory explanations)
Setup & Installation
Architecture (for complex projects)
Core Principles
Tech Stack
Development Workflow
Testing Requirements
Error Handling
Common Commands

For Existing Projects

Quality Report: Score, missing sections, issues, recommendations
Enhanced CLAUDE.md: Updated with missing sections (if requested)

Option B: Agent Invocation (Recommended for Maintenance)

The claude-md-guardian agent provides:

Auto-Sync: Detects changes and updates CLAUDE.md automatically
Smart Detection: Only updates when significant changes occur
Targeted Updates: Modifies specific sections based on detected changes
Token-Efficient: Uses haiku model for routine updates
Concise Reporting: Reports only what changed

Agent triggers on:

Feature completion
Major refactoring
New dependencies added
Architecture changes
Manual invocation via this command

Agent output:

✅ CLAUDE.md updated:
- Tech Stack: Added 2 dependencies
- Project Structure: Updated diagram
- Setup: New environment variable

Changes: 3 sections modified, 12 lines changed

Validation

The command enforces the critical validation rule:

"Always validate your output against official native examples before declaring complete."

All generated CLAUDE.md files:

Follow official /update-claude-md slash command format
Include project structure diagrams
Have setup & installation instructions
Document architecture for complex projects
Match native Claude Code format 100%

Examples

Example 1: New TypeScript React Project

/enhance-claude-md

Claude Response:

Discovered: TypeScript + React + Node.js project
Team size: Small (5 devs)
Phase: MVP

I'll create:
- CLAUDE.md (~125 lines) with full native format

Proceed?

Example 2: Existing Project Missing Sections

/enhance-claude-md

Claude Response:

Quality Score: 55/100

Missing:
- Project Structure diagram
- Setup & Installation
- Architecture section

I can add these native format sections to improve quality to ~85/100.

Proceed?

Example 3: Large Full-Stack Project

/enhance-claude-md

Claude Response:

Discovered: Full-stack TypeScript project
Recommend: Modular architecture

I'll create:
- Root CLAUDE.md (~100 lines)
- backend/CLAUDE.md (~200 lines)
- frontend/CLAUDE.md (~225 lines)

Proceed?

Troubleshooting

"Skill not found" error

Solution: Install the claudeforge-skill first:

cp -r skill ~/.claude/skills/claudeforge-skill/
# Note: v2.0.0 auto-migrates from old claude-md-enhancer name

Command not recognized

Solution: Ensure command is in correct location:

Project: .claude/commands/enhance-claude-md/enhance-claude-md.md
User: ~/.claude/commands/enhance-claude-md/enhance-claude-md.md

Then restart Claude Code.

No project structure detected

Solution: Ensure project has recognizable files:

Node.js: package.json
Python: requirements.txt, pyproject.toml
Go: go.mod
Rust: Cargo.toml

Integration with claude-md-guardian Agent

This slash command can invoke the claude-md-guardian agent for automatic CLAUDE.md maintenance:

How They Work Together

/enhance-claude-md (command)
    ↓
Discovery → Analysis → Task
    ↓
Invokes claude-md-guardian (agent)
    ↓
Agent uses claudeforge-skill (skill)
    ↓
CLAUDE.md updated and synchronized

v2.0.0 Enhancement: Hooks can now trigger background validation checks. Example:

{
  "hooks": {
    "AfterCommit": {
      "command": "/enhance-claude-md",
      "run_in_background": true,
      "timeout": 10000,
      "description": "Validate CLAUDE.md after commits"
    }
  }
}

When to Use the Agent

Via this command:

After feature completion
After major refactoring
When new dependencies added
After architecture changes
For periodic synchronization

Automatic (with SessionStart hook):

Beginning of each session
Silent if no significant changes
Updates only when needed

See: agent/README.md for complete agent documentation

Skill Documentation: ../skill/README.md
Skill Examples: ../skill/examples/
Agent Documentation: ../agent/README.md
Official Slash Command Reference: documentation/references/slash-command-update-claude-md-example.md

Version

Version: 2.0.0
Last Updated: January 2026
Compatible: Claude Code 2.1.4+
Dependencies: claudeforge-skill v2.0.0+
Migration: See docs/MIGRATION_V2.md for upgrade guide

Quick Start: Run /enhance-claude-md in any project to initialize or enhance your CLAUDE.md file with 100% native format compliance!

README.md

/enhance-claude-md Slash Command

Features

Installation

Option 1: Project-Level (Current Project Only)

Option 2: User-Level (All Projects)

Usage

Basic Usage (Auto-Detect)

New Project (No CLAUDE.md)

Existing Project (CLAUDE.md exists)

Command Structure

Phase 1: Discovery

Phase 2: Analysis

Phase 3: Task

Prerequisites

Advanced Usage

Specify Project Type

Request Modular Architecture

Analyze Only

Enhance Specific Sections

Output

Option A: Direct Skill Invocation

For New Projects

For Existing Projects

Option B: Agent Invocation (Recommended for Maintenance)

Validation

Examples

Example 1: New TypeScript React Project

Example 2: Existing Project Missing Sections

Example 3: Large Full-Stack Project

Troubleshooting

"Skill not found" error

Command not recognized

No project structure detected

Integration with claude-md-guardian Agent

How They Work Together

When to Use the Agent

Related Resources

Version