mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-04 02:43:15 -04:00
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.
134 lines
6.1 KiB
Markdown
134 lines
6.1 KiB
Markdown
---
|
|
description: Initialize or enhance CLAUDE.md files using the claude-md-enhancer skill with interactive workflow and 100% native format compliance
|
|
permissions:
|
|
allow:
|
|
- Bash(ls:*)
|
|
- Bash(find:*)
|
|
- Bash(git status:*)
|
|
- Read
|
|
- Glob
|
|
- Skill
|
|
hooks:
|
|
- matcher: ""
|
|
once: true
|
|
commands:
|
|
- echo "Starting CLAUDE.md enhancement workflow"
|
|
---
|
|
|
|
# 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:
|
|
1. Explore your repository structure
|
|
2. Detect project type, tech stack, team size, development phase
|
|
3. Show you the discoveries and ask for confirmation
|
|
4. Create customized CLAUDE.md file(s) after your approval
|
|
5. Apply 100% native format compliance (project structure diagrams, setup instructions, architecture sections)
|
|
|
|
### For Existing Projects (CLAUDE.md exists):
|
|
|
|
The `claude-md-enhancer` skill will:
|
|
1. Analyze current CLAUDE.md for quality and completeness
|
|
2. Calculate quality score (0-100)
|
|
3. Identify missing sections
|
|
4. Provide actionable recommendations
|
|
5. 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").
|