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:

• Get changed files: git diff --name-only origin/main...HEAD

• Find directly modified Claude docs

• 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

• 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:

• Review aggregated findings

• Prioritize by impact (breaking vs cosmetic)

• Generate proposed edits for each issue

• 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", "new_string": "foo" } ] }

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:

• Log the failure with context

• Continue with other agents

• Mark affected validations as "INCOMPLETE"

• Include in final report for manual review