ClaudeForge/agent/README.md

# 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 agent/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 agent/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.

**v2.0.0 Update**: Hooks now support advanced features like `run_in_background`, environment variables, and conditional execution. See [docs/MIGRATION_V2.md](../docs/MIGRATION_V2.md) for details.

## Prerequisites

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

**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**: "claudeforge-skill not found"
**Solution**:
```bash
# Install the skill
cp -r skill ~/.claude/skills/claudeforge-skill/
# Restart Claude Code
# Note: v2.0.0 auto-migrates from old claude-md-enhancer name
```

## Integration

### With claudeforge-skill

The agent uses this skill as its core capability:
```
Agent detects changes → Invokes skill → Skill updates sections → Agent validates
```

**v2.0.0**: Uses new `permissions:` syntax for tool access control.

### 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**: 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](../docs/MIGRATION_V2.md) for upgrade guide

## Related Resources

- **Skill**: `skill/` (claudeforge-skill)
- **Slash Command**: `command/` (enhance-claude-md)
- **Agent File**: `agent/claude-md-guardian.md`

---

**Quick Start**: Copy agent to `~/.claude/agents/`, restart Claude Code, and the guardian will automatically maintain your CLAUDE.md files!