Claude
0a34178e22
Closes the gap between ClaudeForge and the Anthropic docs at
code.claude.com/docs/en/memory (and its linked hooks / skills / plugins
pages). Five tightly-scoped changes, each verified by smoke test.
A. Fix guardian hook frontmatter shape (agent/claude-md-guardian.md)
The previous array-of-{event, commands} shape did not match the
documented schema (hooks: { EventName: [{ matcher, hooks: [{ type,
command }] }] }), so the guardian's hooks silently did not fire.
Rewritten to the canonical keyed-object shape with PostToolUse,
PreToolUse, SessionStart, and the new InstructionsLoaded event.
B+C. Plugin-level hooks/hooks.json + hooks/validate-claude-md.py
New deterministic enforcement of the 150-line cap. The validator
script reads the hook payload from stdin, extracts any referenced
CLAUDE.md path (supports both PostToolUse tool_input.file_path and
InstructionsLoaded path / file shapes), and exits 2 with stderr
feedback when the file is over 150 lines. Wired to both PostToolUse
on Write|Edit and InstructionsLoaded on every load_reason
(session_start, nested_traversal, path_glob_match, include, compact).
The cap is now enforced at every load *and* write, not only when the
guardian decides to run sync.
D. ContentGenerator.generate_rules_file() (skill/generator.py)
Emits path-scoped .claude/rules/*.md instruction files with name,
description, and paths: glob frontmatter. Claude loads these
lazily — only when accessing files matching the globs — so
file-type-specific guidance no longer has to live in the root
CLAUDE.md. Validates that paths is non-empty (ValueError otherwise).
E. AGENTS.md / .cursorrules / .windsurfrules interop
command/enhance-claude-md.md Phase 1 now lists which sibling
instruction files exist. ContentGenerator.generate_root_file() reads
project_context['existing_instruction_files'] and prepends an
## External Instructions section with @AGENTS.md (etc.) imports, so
repos already using other agent tooling can adopt ClaudeForge
without losing their existing instructions.
Smoke tests (all pass):
- Guardian hooks frontmatter parses as a dict with 4 events, each
carrying matcher + nested hooks array of {type, command} entries.
- hooks.json is valid JSON; PostToolUse matcher = Write|Edit;
InstructionsLoaded matcher covers all five load_reason values.
- validate-claude-md.py: small file -> rc 0, bloated file (200 lines)
-> rc 2 with stderr referencing the 150 cap, InstructionsLoaded
payload shape also handled, non-CLAUDE.md paths ignored, no stdin
-> rc 0.
- generate_rules_file emits valid frontmatter with paths glob and
raises ValueError when paths is empty.
- generate_root_file inserts @AGENTS.md and @.cursorrules imports
when existing_instruction_files lists them; omits the section
otherwise.
- Regression: large-fullstack root still 52 lines with chain imports
intact; all five sub-CLAUDE.md files in this repo still pass
validator (status = pass).
Docs:
- agent/CLAUDE.md updated to show the canonical hook shape and the
hook-driven validator wiring.
- skill/CLAUDE.md notes generate_rules_file and AGENTS.md interop.
- CHANGELOG.md documents all five changes under Unreleased.
6.1 KiB
description, permissions, hooks
| description | permissions | hooks | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Initialize or enhance CLAUDE.md files using the claude-md-enhancer skill with interactive workflow and 100% native format compliance |
|
|
CLAUDE.md Enhancer Command
This command uses the claude-md-enhancer skill to initialize or enhance CLAUDE.md files for your project.
Phase 1: Discovery - Check Current State
Check if CLAUDE.md exists
!ls -la CLAUDE.md 2>/dev/null || echo "CLAUDE.md not found"
Check for modular CLAUDE.md files
!find . -name "CLAUDE.md" -type f -not -path "./node_modules/*" -not -path "./.git/*" | head -10
Get repository status
!git status --short 2>/dev/null || echo "Not a git repository"
Check project structure
!ls -la
Check for sibling agent / rule files
If AGENTS.md, .cursorrules, or .windsurfrules exists, ClaudeForge will preserve it and chain it from the root CLAUDE.md via @AGENTS.md (or the equivalent) instead of overwriting. Detect them now:
!for f in AGENTS.md .cursorrules .windsurfrules; do [ -f "$f" ] && echo "found: $f ($(wc -l < "$f") lines)" || echo "absent: $f"; done
Deep project scan via Explore agent
For non-trivial repositories, delegate the codebase walk to the Explore subagent so the discovery does not bloat this command's context window. Ask it a single, scoped question — for example:
Walk this repository and report: project type (web_app / api / fullstack / cli / library / mobile / desktop), languages and frameworks detected, primary tech stack files (package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml), team-size indicators (number of contributors, CODEOWNERS), workflow indicators (.github/workflows, Dockerfile, CI configs), and any subdirectories that warrant their own CLAUDE.md (backend/, frontend/, database/, docs/, .github/). Return findings as a compact JSON object. Under 250 words.
Use the general-purpose subagent only for research that requires synthesising findings across multiple agents (e.g. comparing detected stack against template registry). Keep agent prompts self-contained and ask for short, structured reports.
Phase 2: Analysis - Determine Action
Based on the discovery above, I need to determine the appropriate action:
If CLAUDE.md does NOT exist → Interactive Initialization Workflow If CLAUDE.md exists → Analysis and Enhancement Workflow
For New Projects (No CLAUDE.md):
The claude-md-enhancer skill will:
- Explore your repository structure
- Detect project type, tech stack, team size, development phase
- Show you the discoveries and ask for confirmation
- Create customized CLAUDE.md file(s) after your approval
- Apply 100% native format compliance (project structure diagrams, setup instructions, architecture sections)
For Existing Projects (CLAUDE.md exists):
The claude-md-enhancer skill will:
- Analyze current CLAUDE.md for quality and completeness
- Calculate quality score (0-100)
- Identify missing sections
- Provide actionable recommendations
- Offer to enhance with missing native format sections
Phase 3: Task - Execute with Skill or Agent
Option A: Direct Skill Invocation
I can invoke the claude-md-enhancer skill directly to handle the appropriate workflow based on what I discovered above.
The skill provides:
- ✨ 100% Native Format Compliance: All generated files follow official Claude Code format with project structure diagrams, setup instructions, architecture sections, and file structure explanations
- 🆕 Interactive Initialization: For new projects, explores repository and asks for confirmation before creating files
- ✅ Intelligent Analysis: For existing projects, scans and evaluates for quality and completeness
- 🚀 Smart Generation: Creates customized CLAUDE.md files from scratch
- 🔧 Enhancement: Adds missing sections and improves existing files
- 📦 Modular Architecture: Supports context-specific files (backend/, frontend/, database/)
Always-On: Karpathy Behavioral Guidelines
Every generated or enhanced CLAUDE.md MUST include a ## Behavioral Guidelines section summarising the four Karpathy principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) with a link to the installed karpathy-guidelines skill.
The claude-md-enhancer skill inserts this section automatically — both in template_selector.customize_template() for new files and in generator.merge_with_existing() for enhanced files. Do not strip it during enhancement; if it is missing from an existing CLAUDE.md, treat that as a required addition.
The full skill is installed at ~/.claude/skills/karpathy-guidelines/SKILL.md (or ./.claude/skills/karpathy-guidelines/SKILL.md for project-level installs).
Option B: Agent Invocation (Recommended for Maintenance)
For ongoing maintenance and automatic updates throughout your project lifecycle, I can invoke the claude-md-guardian agent instead:
When to use the agent:
- After feature completion
- After major refactoring
- When new dependencies are added
- After architecture changes
- For periodic CLAUDE.md synchronization
Agent benefits:
- 🔄 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 completion signals
- ✨ Native Format: Ensures 100% Claude Code format compliance
Your Task
I'm ready to proceed. What would you like me to do?
For new projects: I'll run the interactive initialization workflow (skill) For existing projects: I'll analyze your current CLAUDE.md and suggest improvements (skill) For maintenance: I'll invoke claude-md-guardian agent to check for updates and synchronize
Please confirm how you'd like to proceed, or let me know if you have specific requirements (e.g., "Create a CLAUDE.md for my Python FastAPI project" or "Invoke claude-md-guardian to update my CLAUDE.md").