Claude Documentation Sync

Validate and synchronize all Claude-related documentation before commits.

Quick Start

Mode selection:
- full    → Exhaustive validation of all docs
- changed → Only docs affected by current branch (default)

Execution Flow

Phase 1: Discovery

Full mode: Find all Claude docs in repository:

• **/CLAUDE.md (excluding .terragrunt-cache/, .terragrunt-stack/)
• .claude/skills/*/SKILL.md
• .claude/skills/*/references/*.md

Changed mode: Analyze branch diff:

1. Get changed files: git diff --name-only origin/main...HEAD
2. Find directly modified Claude docs
3. Find docs that reference changed paths (smart detection)

Phase 2: Parallel Validation (Haiku Agents)

Spawn parallel Haiku agents organized by validation type:

Agent Group A: Path Validators (by directory)

One agent per major directory validates file/directory references:

• infrastructure/ paths
• kubernetes/ paths
• .taskfiles/ paths
• Root and other paths

Validation checks:

• File paths mentioned exist: [path/to/file](path/to/file)
• Directory paths exist: infrastructure/modules/
• Glob patterns return results: **/*.tf

Agent Group B: Code Reference Validators

Validate code-level claims:

• Function/class names exist where documented
• Line number references are approximately accurate (±10 lines)
• Variable names in examples exist in referenced files

Agent Group C: Command Validators

Validate command examples:

• task <name> commands exist in Taskfile
• CLI tools referenced are in Brewfile
• Command syntax is valid (dry-run where safe)

Agent Group D: Cross-Reference Validators

Validate documentation consistency:

• Skill references in CLAUDE.md match actual skills
• Table entries match actual directories
• Runbook references exist

Phase 3: Aggregation

Collect results from all agents into a unified report:

┌─────────────────────────────────────────────────────────────┐
│ SYNC-CLAUDE VALIDATION REPORT                               │
├─────────────────────────────────────────────────────────────┤
│ Mode: [full|changed]                                        │
│ Docs Scanned: N                                             │
│ Issues Found: N                                             │
├─────────────────────────────────────────────────────────────┤
│ ISSUES BY CATEGORY:                                         │
│                                                             │
│ 🔴 Path References (N issues)                               │
│   • infrastructure/CLAUDE.md:45 - path not found            │
│     Referenced: infrastructure/units/foo/                   │
│     Suggestion: Path was renamed to infrastructure/units/bar│
│                                                             │
│ 🟡 Command References (N issues)                            │
│   • .taskfiles/CLAUDE.md:67 - task not found                │
│     Referenced: task tg:deploy-live                         │
│     Suggestion: Task was renamed to task tg:apply-live      │
│                                                             │
│ 🟢 Valid References: N                                      │
└─────────────────────────────────────────────────────────────┘

Phase 4: Opus Validation

Spawn Opus agent to:

1. Review aggregated findings
2. Prioritize by impact (breaking vs cosmetic)
3. Generate proposed edits for each issue
4. Present final change list for approval

Agent Prompts

Discovery Agent (Haiku)

Discover all Claude documentation files in the repository.

Search patterns:
- **/CLAUDE.md (exclude .terragrunt-cache/, .terragrunt-stack/)
- .claude/skills/*/SKILL.md
- .claude/skills/*/references/*.md

For each file found, extract:
1. All file path references (markdown links, code blocks)
2. All directory references
3. All command examples (task, kubectl, git, etc.)
4. All cross-references to other docs/skills

Return structured JSON:
{
  "file": "path/to/doc.md",
  "path_refs": ["path1", "path2"],
  "dir_refs": ["dir1/", "dir2/"],
  "commands": ["task foo", "kubectl get"],
  "cross_refs": ["skill:name", "doc:path"]
}

Path Validator Agent (Haiku)

Validate file and directory references in Claude documentation.

Input: List of {doc_path, references}

For each reference:
1. Check if path exists using Glob/Read
2. If not found, search for similar paths (fuzzy match)
3. Determine if path was renamed, moved, or deleted

Return:
{
  "valid": [...],
  "invalid": [
    {
      "doc": "path/to/doc.md",
      "line": 45,
      "reference": "infrastructure/foo/",
      "status": "not_found",
      "suggestion": "Renamed to infrastructure/bar/"
    }
  ]
}

Command Validator Agent (Haiku)

Validate command examples in Claude documentation.

Input: List of {doc_path, commands}

Validation steps:
1. task commands: Verify in Taskfile.yaml or .taskfiles/*
2. CLI tools: Verify in Brewfile
3. kubectl commands: Syntax check only (no cluster access)
4. git commands: Syntax validation

Return:
{
  "valid": [...],
  "invalid": [
    {
      "doc": "path/to/doc.md",
      "line": 67,
      "command": "task tg:deploy",
      "status": "task_not_found",
      "suggestion": "Did you mean: task tg:apply-*"
    }
  ]
}

Change Impact Analyzer (Haiku) – Changed Mode Only

Analyze git diff to find impacted documentation.

Steps:
1. Parse diff: git diff --name-only origin/main...HEAD
2. For each changed file, find docs that might reference it:
   - Direct path references
   - Parent directory references
   - Related command references (if Taskfile changed)
3. Include any directly modified Claude docs

Return list of doc paths requiring validation.

Opus Validator Agent

Review sync-claude validation results and propose fixes.

Input: Aggregated validation results from all Haiku agents

Tasks:
1. Deduplicate findings
2. Categorize by severity:
   - CRITICAL: Broken references users will hit
   - WARNING: Outdated but still functional
   - INFO: Style/cosmetic issues
3. For each issue, generate a proposed Edit:
   - old_string: exact text to replace
   - new_string: corrected text
4. Verify proposed edits don't break other references

Output format:
{
  "summary": {
    "total_issues": N,
    "critical": N,
    "warning": N,
    "info": N
  },
  "proposed_edits": [
    {
      "file": "path/to/doc.md",
      "severity": "CRITICAL",
      "description": "Fix broken path reference",
      "old_string": "[foo](infrastructure/foo/)",
      "new_string": "[foo](infrastructure/bar/)"
    }
  ]
}

Present edits for user approval before applying.

Mode Selection Logic

IF user specifies mode:
  USE specified mode
ELSE IF on main branch:
  USE full mode
ELSE IF branch has commits ahead of origin/main:
  USE changed mode
ELSE:
  USE full mode (no changes to analyze)

Exclusions

Always exclude from scanning:

• .terragrunt-cache/
• .terragrunt-stack/
• node_modules/
• .git/
• *.rendered/

Error Handling

If an agent fails:

1. Log the failure with context
2. Continue with other agents
3. Mark affected validations as “INCOMPLETE”
4. Include in final report for manual review