Claude Documentation Sync
Validate all Claude-related documentation before commits. Default mode is changed (branch-scoped); use full for exhaustive validation.
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/pathskubernetes/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 grouped by severity (CRITICAL / WARNING / INFO), showing doc path, line number, the broken reference, and a suggested fix. Count valid references. Present issues before proposing edits.
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 Responsibilities
Discovery Agent (Haiku): Use discover-claude-docs.sh (or discover-claude-docs.sh --changed) to enumerate files. For each file, run extract-references.sh to get path refs, dir refs, commands, skill refs, and CLI tools as structured JSON. Scripts are in .claude/skills/sync-claude/scripts/.
Path Validator Agents (Haiku, one per directory domain): Verify each path ref exists using Glob/Read. For misses, fuzzy-search for renames. Return valid/invalid lists with suggestions.
Command Validator Agent (Haiku): Verify task <name> commands exist in Taskfile.yaml or .taskfiles/*. Verify CLI tools appear in Brewfile. kubectl/git: syntax check only. Return valid/invalid with suggestions.
Change Impact Analyzer (Haiku, changed mode only): Parse git diff --name-only origin/main...HEAD. Find docs directly modified. Search all docs for references to changed paths/directories. Return impacted doc list.
Opus Validator Agent: Deduplicate all Haiku findings. Categorize severity (CRITICAL: broken refs users will hit; WARNING: outdated but functional; INFO: cosmetic). Generate proposed Edit operations (old_string/new_string). Present 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