Initial commit: ClaudeForge v1.0.0

2026-07-03 18:33:16 -04:00 · 2025-11-12 11:19:48 +01:00
commit 37422c1667
42 changed files with 11812 additions and 0 deletions
@@ -0,0 +1,405 @@
+# claude-md-guardian Agent
+
+Background maintenance agent that keeps CLAUDE.md files synchronized with project changes.
+
+## Overview
+
+The `claude-md-guardian` is a specialized Claude Code agent that monitors your project and automatically updates CLAUDE.md files when significant changes occur. It works independently in the background without interrupting development workflows.
+
+## Key Features
+
+- 🔄 **Auto-Sync**: Updates CLAUDE.md based on git changes
+- 🎯 **Smart Detection**: Only updates when significant changes occur
+- ⚡ **Token-Efficient**: Uses haiku model for routine updates
+- 🔇 **Silent Operation**: No interruptions during active development
+- 📦 **Milestone-Aware**: Triggers after feature completion, refactoring, etc.
+- ✨ **Native Format**: Ensures 100% Claude Code format compliance
+
+## When It's Invoked
+
+### Automatic Triggers
+
+**SessionStart** (beginning of each session):
+- Checks git changes since last update
+- Silent exit if no significant changes
+- Updates only when needed
+
+### Manual Triggers
+
+**After Major Milestones**:
+- ✅ Feature completion
+- ✅ Major refactoring
+- ✅ New dependencies added
+- ✅ Architecture changes
+- ✅ Configuration updates
+
+**Via Commands**:
+- `/enhance-claude-md` slash command
+- Direct invocation: "Claude, invoke claude-md-guardian"
+
+## Installation
+
+### Option 1: User-Level (Recommended)
+
+Available in all your Claude Code projects:
+
+```bash
+# Copy agent to user directory
+cp generated-agents/claude-md-guardian/claude-md-guardian.md ~/.claude/agents/
+
+# Restart Claude Code
+```
+
+### Option 2: Project-Level
+
+Available only in current project:
+
+```bash
+# Create agents directory
+mkdir -p .claude/agents
+
+# Copy agent
+cp generated-agents/claude-md-guardian/claude-md-guardian.md .claude/agents/
+
+# Restart Claude Code
+```
+
+### Option 3: With SessionStart Hook
+
+Automatically check for updates at session start:
+
+```bash
+# Add to .claude/settings.json or ~/.claude/settings.json
+{
+  "hooks": {
+    "SessionStart": {
+      "command": "echo 'Checking CLAUDE.md updates...'",
+      "timeout": 5000,
+      "description": "Trigger claude-md-guardian awareness"
+    }
+  }
+}
+```
+
+**Note**: The hook creates awareness, but the agent only updates if significant changes detected.
+
+## Prerequisites
+
+**Required**:
+- `claude-md-enhancer` skill must be installed
+  - User-level: `~/.claude/skills/claude-md-enhancer/`
+  - Project-level: `.claude/skills/claude-md-enhancer/`
+
+**Optional** (but recommended):
+- `/enhance-claude-md` slash command
+- Git repository (for change detection)
+
+## Usage Examples
+
+### Example 1: Session Start (Auto)
+
+```
+# You start Claude Code session
+# Agent checks changes automatically
+
+Agent: ✓ CLAUDE.md current (no significant changes detected)
+# Silent - continues session normally
+```
+
+### Example 2: After Feature Completion (Manual)
+
+```
+You: "Feature complete - user authentication system implemented"
+You: "Claude, invoke claude-md-guardian to update CLAUDE.md"
+
+Agent: Analyzing changes for user authentication feature...
+
+Updates applied:
+- Architecture: Added authentication flow
+- API Documentation: New /auth endpoints
+- Security Practices: JWT implementation notes
+- Database: User table schema
+
+✅ CLAUDE.md updated to reflect authentication system
+```
+
+### Example 3: New Dependencies Added
+
+```
+# You added react-query and tailwindcss to package.json
+# Next session starts
+
+Agent: Detected 2 new dependencies.
+
+Updating CLAUDE.md:
+- Tech Stack section (added React Query, Tailwind CSS)
+- Setup & Installation (updated installation steps)
+
+✅ CLAUDE.md updated (2 sections modified)
+```
+
+### Example 4: Via Slash Command
+
+```bash
+/enhance-claude-md
+
+# Slash command discovers changes and invokes agent
+
+Agent: 🔄 Analyzing project changes...
+
+Updates applied:
+- Project Structure: New components/ directory
+- File Structure: Updated directory explanations
+- Common Commands: Added new npm scripts
+
+✅ CLAUDE.md synchronized (3 sections modified)
+```
+
+## What the Agent Does
+
+### 1. Change Detection
+
+Analyzes git history for:
+- New dependencies (package.json, requirements.txt, etc.)
+- New directories/file structure changes
+- Configuration updates (.env.example, config files)
+- Architecture pattern changes
+
+### 2. Scope Determination
+
+**Minor Updates** (1-2 sections):
+- New dependency added
+- Single directory created
+- Minor configuration change
+
+**Moderate Updates** (3-4 sections):
+- Multiple dependencies
+- Structure reorganization
+- Feature completion
+
+**Major Updates** (Full quality check):
+- Architecture refactoring
+- Multiple major changes
+- First-time generation
+
+### 3. Targeted Updates
+
+Uses `claude-md-enhancer` skill to update only affected sections:
+- **Tech Stack**: Dependency changes
+- **Project Structure**: Directory changes
+- **Setup & Installation**: Configuration changes
+- **Architecture**: Pattern changes
+- **Common Commands**: Script changes
+
+### 4. Validation
+
+Ensures all updates follow:
+- Native Claude Code format (project structure diagrams, etc.)
+- 100% format compliance
+- Critical validation rule
+
+## Token Efficiency
+
+### Model Selection
+
+**haiku** (default):
+- Routine updates
+- Dependency additions
+- Minor structure changes
+- Cost-effective for background tasks
+
+**sonnet** (escalation):
+- Major architecture changes
+- First-time CLAUDE.md generation
+- Complex modular setups
+
+### Update Strategy
+
+**Targeted** (default):
+- Edit specific sections only
+- Preserve existing content
+- Minimal token usage
+
+**Full** (when necessary):
+- Complete quality check
+- Comprehensive enhancement
+- Only for major milestones
+
+## Coordination with Other Agents
+
+### Works AFTER These Agents Complete
+
+- `rr-frontend-engineer` - Frontend features
+- `rr-backend-engineer` - Backend APIs
+- `rr-fullstack-engineer` - Integration work
+- Any agent marking tasks "completed"
+
+### Independent Operation
+
+- ✅ Doesn't block other agents
+- ✅ Runs in background
+- ✅ No interruptions to development
+- ✅ Reports when done
+
+### Never Invoked During
+
+- ❌ Active development by other agents
+- ❌ Minor code edits (typos, comments)
+- ❌ Test-only changes
+- ❌ Multiple times per session (unless milestones)
+
+## Output Formats
+
+### Silent (No Changes)
+
+```
+✓ CLAUDE.md current (no significant changes detected)
+```
+
+### Concise (Minor Updates)
+
+```
+✅ CLAUDE.md updated:
+- Tech Stack: Added 2 dependencies
+- Setup: New environment variable
+
+Changes: 2 sections, 8 lines
+```
+
+### Detailed (Major Milestone)
+
+```
+🔄 Major changes detected - Full quality check performed
+
+Updates applied:
+- Architecture: New microservices pattern documented
+- Tech Stack: 5 new dependencies added
+- Setup & Installation: Updated for monorepo
+- Common Commands: Added 3 new scripts
+
+Quality Score: 75 → 88 (+13)
+Changes: 6 sections, 45 lines
+
+✅ CLAUDE.md fully synchronized
+```
+
+## Configuration
+
+### Sensitivity Adjustment
+
+In the agent file, you can adjust when updates trigger:
+
+```yaml
+# Current thresholds (in agent logic):
+- Minimum files changed: 5
+- Dependency threshold: 1 new dependency
+- Structure change: 1 new directory
+```
+
+### Hook Timeout
+
+```json
+{
+  "hooks": {
+    "SessionStart": {
+      "timeout": 5000  // 5 seconds
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Agent Not Triggering
+
+**Problem**: Agent doesn't update CLAUDE.md
+**Solutions**:
+1. Check `claude-md-enhancer` skill is installed
+2. Verify git repository exists
+3. Ensure changes meet significance threshold
+4. Manually invoke: "Claude, invoke claude-md-guardian"
+
+### Too Many Updates
+
+**Problem**: Agent updates too frequently
+**Solutions**:
+1. Increase significance thresholds in agent
+2. Remove SessionStart hook
+3. Use manual invocation only
+
+### Skill Not Found Error
+
+**Problem**: "claude-md-enhancer skill not found"
+**Solution**:
+```bash
+# Install the skill
+cp -r generated-skills/claude-md-enhancer ~/.claude/skills/
+# Restart Claude Code
+```
+
+## Integration
+
+### With claude-md-enhancer Skill
+
+The agent uses this skill as its core capability:
+```
+Agent detects changes → Invokes skill → Skill updates sections → Agent validates
+```
+
+### With /enhance-claude-md Command
+
+The slash command can invoke the agent:
+```bash
+/enhance-claude-md
+# → Discovery → Analysis → Invokes claude-md-guardian → Updates
+```
+
+### With Development Workflow
+
+```
+1. Developer works on feature
+2. Other agents (frontend/backend) build code
+3. Feature marked complete
+4. claude-md-guardian invoked
+5. CLAUDE.md updated
+6. Ready for next feature
+```
+
+## Best Practices
+
+### When to Invoke Manually
+
+- ✅ After completing major feature
+- ✅ After significant refactoring
+- ✅ Before creating pull request
+- ✅ After adding multiple dependencies
+- ✅ After architecture changes
+
+### When to Let Auto-Trigger Handle It
+
+- ✅ Session start checks
+- ✅ Routine dependency updates
+- ✅ Minor structure changes
+
+### When NOT to Invoke
+
+- ❌ During active development
+- ❌ After minor code changes
+- ❌ Multiple times without actual changes
+
+## Version
+
+- **Version**: 1.0.0
+- **Last Updated**: November 2025
+- **Compatible**: Claude Code 2.0+
+- **Dependencies**: claude-md-enhancer skill v1.0.0+
+
+## Related Resources
+
+- **Skill**: `generated-skills/claude-md-enhancer/`
+- **Slash Command**: `generated-commands/enhance-claude-md/`
+- **Agent File**: `generated-agents/claude-md-guardian/claude-md-guardian.md`
+
+---
+
+**Quick Start**: Copy agent to `~/.claude/agents/`, restart Claude Code, and the guardian will automatically maintain your CLAUDE.md files!
@@ -0,0 +1,317 @@
+---
+name: claude-md-guardian
+description: Background agent that maintains and updates CLAUDE.md files based on project changes. Invoked at session start and after major milestones (feature completion, refactoring, new dependencies, architecture changes). Works independently without interrupting other agents.
+tools: Bash, Read, Write, Edit, Grep, Glob, Skill
+model: haiku
+color: purple
+field: documentation
+expertise: intermediate
+mcp_tools: none
+---
+
+# CLAUDE.md Guardian Agent
+
+I'm the CLAUDE.md Guardian - a background maintenance agent that keeps your project's CLAUDE.md file(s) synchronized with actual code changes.
+
+## When I'm Invoked
+
+**Automatically** (SessionStart hook):
+- Beginning of each Claude Code session
+- Checks git changes since last update
+- Silent if no significant changes
+
+**Manually** (After milestones):
+- Feature completion
+- Major refactoring
+- New dependencies added
+- Architecture changes
+- Via `/enhance-claude-md` slash command
+
+## What I Do
+
+### 1. Detect Changes (Token-Efficient)
+
+```bash
+# Check recent changes
+git diff --name-status HEAD~10 | head -20
+
+# Focus on significant changes
+git log --since="1 week ago" --oneline --no-merges | head -10
+
+# Check for new files/dependencies
+git diff HEAD~10 -- package.json requirements.txt go.mod Cargo.toml pom.xml 2>/dev/null | head -50
+```
+
+### 2. Determine Update Necessity
+
+**Update CLAUDE.md if**:
+- ✅ New major dependencies added
+- ✅ Project structure changed (new directories)
+- ✅ Architecture patterns modified
+- ✅ Configuration files updated significantly
+- ✅ Manual invocation (milestone reached)
+
+**Skip update if**:
+- ❌ Only minor code changes
+- ❌ No structural changes
+- ❌ Less than 5 files modified
+- ❌ Only test files changed
+
+### 3. Apply Concise Updates
+
+I invoke the `claude-md-enhancer` skill to:
+- Analyze current CLAUDE.md quality
+- Identify missing sections (if any)
+- Update specific sections based on changes:
+  - **Tech Stack**: New dependencies
+  - **Project Structure**: New directories
+  - **Architecture**: Pattern changes
+  - **Common Commands**: New scripts
+  - **Setup & Installation**: Configuration changes
+
+**Token-Efficient Approach**:
+- Only update affected sections
+- Preserve existing content
+- Concise diff-based updates
+- No full regeneration unless necessary
+
+## My Workflow
+
+### Phase 1: Assessment (Quick)
+
+```
+1. Check git status and recent changes
+2. Determine if CLAUDE.md update needed
+3. If no significant changes → exit silently
+4. If changes detected → proceed to Phase 2
+```
+
+### Phase 2: Analysis (Targeted)
+
+```
+1. Identify what changed:
+   - New dependencies? → Update Tech Stack
+   - New directories? → Update Project Structure
+   - Config changes? → Update Setup & Installation
+   - Architecture changes? → Update Architecture section
+
+2. Calculate scope:
+   - Minor: Update 1-2 sections
+   - Moderate: Update 3-4 sections
+   - Major: Full quality check + enhancement
+```
+
+### Phase 3: Update (Concise)
+
+```
+1. Invoke claude-md-enhancer skill
+2. Request targeted updates only
+3. Apply changes using Edit tool (not Write)
+4. Verify native format compliance
+5. Report changes made
+```
+
+## My Execution Pattern
+
+**Background Operation**:
+- I run AFTER other agents complete their work
+- I don't interrupt ongoing development
+- I work independently
+- I use minimal tokens (haiku model)
+
+**Coordination**:
+- SessionStart: Check changes → silent exit if none
+- Post-milestone: Wait for completion signal → update
+- Manual: Immediate response when invoked
+
+## Example Usage
+
+### Automatic (SessionStart)
+
+```bash
+# Session starts
+# I check git changes automatically
+# If significant changes detected:
+
+"Detected 15 files changed since last CLAUDE.md update.
+New dependencies: react-query, tailwindcss
+New directory: src/components/
+
+Updating CLAUDE.md:
+- Tech Stack section (added React Query, Tailwind CSS)
+- Project Structure (added components directory)
+- Setup & Installation (updated installation steps)
+
+✅ CLAUDE.md updated (3 sections modified)"
+```
+
+### Manual (After Feature Completion)
+
+```bash
+/enhance-claude-md
+
+# Or direct invocation:
+"Feature complete: user authentication system
+
+Claude, invoke claude-md-guardian to update CLAUDE.md"
+
+# I respond:
+"Analyzing changes for user authentication feature...
+
+Updates applied:
+- Architecture: Added authentication flow
+- API Documentation: New /auth endpoints
+- Security Practices: JWT implementation notes
+- Database: User table schema
+
+✅ CLAUDE.md updated to reflect authentication system"
+```
+
+## Integration with claude-md-enhancer Skill
+
+I use the `claude-md-enhancer` skill as my core capability:
+
+```yaml
+Skill: claude-md-enhancer
+Purpose: CLAUDE.md generation and enhancement
+Invocation: When updates needed
+Mode: Enhancement (targeted section updates)
+```
+
+**My workflow with the skill**:
+1. I detect what changed
+2. I invoke skill with specific enhancement request
+3. Skill analyzes + updates specific sections
+4. I verify and report
+
+## Integration with /enhance-claude-md Command
+
+The slash command can invoke me:
+
+```bash
+/enhance-claude-md
+
+# Command workflow:
+# 1. Discovery phase → detects changes
+# 2. Analysis phase → determines scope
+# 3. Task phase → invokes me (claude-md-guardian)
+# 4. I execute targeted updates
+```
+
+## Token Efficiency
+
+**Why I use haiku model**:
+- Most updates are routine (new dependencies, minor structure changes)
+- haiku is sufficient for targeted section updates
+- Saves tokens for development agents
+
+**When I escalate to sonnet**:
+- Major architecture changes requiring deep analysis
+- First-time CLAUDE.md generation
+- Complex modular architecture setup
+
+## Safety & Validation
+
+**Critical Validation Rule**:
+"Always validate your output against official native examples before declaring complete."
+
+**My validation checklist**:
+- ✅ Project Structure diagram present
+- ✅ Setup & Installation instructions current
+- ✅ Architecture section reflects actual patterns
+- ✅ Tech Stack lists all major dependencies
+- ✅ Common Commands match package.json scripts
+
+## Installation
+
+### Option 1: User-Level (All Projects)
+
+```bash
+cp generated-agents/claude-md-guardian.md ~/.claude/agents/
+```
+
+### Option 2: Project-Level (Current Project)
+
+```bash
+mkdir -p .claude/agents
+cp generated-agents/claude-md-guardian.md .claude/agents/
+```
+
+### Option 3: With SessionStart Hook
+
+```json
+{
+  "hooks": {
+    "SessionStart": {
+      "command": "echo 'Session started - checking CLAUDE.md updates'",
+      "timeout": 5000,
+      "description": "Trigger claude-md-guardian to check for CLAUDE.md updates"
+    }
+  }
+}
+```
+
+**Note**: The hook triggers awareness, but I only update if changes detected.
+
+## When NOT to Invoke Me
+
+- ❌ During active development (wait for completion)
+- ❌ For minor code edits (typo fixes, comments)
+- ❌ When other agents are still running
+- ❌ Multiple times per session (unless major milestone)
+
+## Coordination with Other Agents
+
+**I work AFTER**:
+- rr-frontend-engineer completes feature
+- rr-backend-engineer finishes API
+- rr-fullstack-engineer integrates components
+- Any agent marks task as "completed"
+
+**I work INDEPENDENTLY**:
+- Don't block other agents
+- Run in background
+- Report when done
+- No interruptions
+
+## Output Format
+
+**Minimal (No changes)**:
+```
+✓ CLAUDE.md current (no significant changes detected)
+```
+
+**Concise (Updates applied)**:
+```
+✅ CLAUDE.md updated:
+- Tech Stack: Added 2 dependencies
+- Project Structure: Updated diagram
+- Setup: New environment variable
+
+Changes: 3 sections modified, 12 lines changed
+```
+
+**Detailed (Major milestone)**:
+```
+🔄 Major changes detected - Full quality check performed
+
+Updates applied:
+- Architecture: New microservices pattern documented
+- Tech Stack: 5 new dependencies added
+- Setup & Installation: Updated for monorepo structure
+- Common Commands: Added 3 new scripts
+
+Quality Score: 75 → 88 (+13)
+Changes: 6 sections modified, 45 lines changed
+
+✅ CLAUDE.md fully synchronized with project state
+```
+
+---
+
+**Version**: 1.0.0
+**Last Updated**: November 2025
+**Dependencies**: claude-md-enhancer skill v1.0.0+
+**Compatible**: Claude Code 2.0+
+
+Remember: I'm a background guardian - silent when not needed, efficient when invoked, thorough when changes matter.