docs-validation-orchestrator

# Docs Validation Orchestrator (Contributor Tool)

Validate the elixir-phoenix plugin against the latest Claude Code documentation.
Follow OTP supervision patterns: spawn worker subagents, compress via context-supervisor, synthesize.

## Phase 1: Setup & Inventory

```bash
mkdir -p .claude/docs-check/{docs-cache,reports,summaries}
```

Scan what needs validation:

```bash
PLUGIN_DIR="plugins/elixir-phoenix"
AGENT_COUNT=$(ls ${PLUGIN_DIR}/agents/*.md 2>/dev/null | wc -l)
SKILL_COUNT=$(ls -d ${PLUGIN_DIR}/skills/*/SKILL.md 2>/dev/null | wc -l)
HAS_HOOKS=$(test -f ${PLUGIN_DIR}/hooks/hooks.json && echo "yes" || echo "no")
HAS_CONFIG=$(test -f ${PLUGIN_DIR}/.claude-plugin/plugin.json && echo "yes" || echo "no")
```

If `--focus` flag: validate ONLY that component type.
If `--quick` flag: skip to Phase 4 (structural checks only).

## Phase 2: Read Cached Docs & Validation Rules

**Prerequisite**: The `/docs-check` skill runs `scripts/fetch-claude-docs.sh` BEFORE
invoking this orchestrator. Docs MUST already be cached.

Read from `.claude/docs-check/docs-cache/`:

| Cache File | Maps To |
|------------|---------|
| `sub-agents.md` | Agent validation |
| `skills.md` | Skill validation |
| `hooks.md` | Hook validation |
| `hooks-guide.md` | Hook validation (patterns) |
| `plugins-reference.md` | Plugin config validation |
| `plugin-marketplaces.md` | Marketplace config validation |
| `plugins.md` | General plugin validation |
| `settings.md` | Permission mode validation |
| `mcp.md` | MCP config validation |

**If any required cache file is missing: STOP and tell the user to run
`bash scripts/fetch-claude-docs.sh` first. Do NOT silently skip or attempt to fetch.**

Also read `.claude/skills/docs-check/references/validation-rules.md` and extract the
section relevant to each component type. Each worker gets ONLY its section.

## Phase 3: Spawn Validation Workers (Parallel)

Spawn one subagent per component type. **Use `model: "sonnet"` for workers** —
opus is unnecessary for comparison work and costs 2x more.

Each worker receives:

1. The cached doc content (pasted into prompt — workers MUST NOT fetch docs themselves)
2. The plugin files to validate (read contents, paste into prompt)
3. The relevant section from validation-rules.md (extracted in Phase 2b)

**Subagent prompt template:**

```text
You are a Claude Code plugin validator for {COMPONENT_TYPE}.

## Official Documentation (current)
{PASTE_CACHED_DOC_CONTENT}

## Plugin Files to Validate
{PASTE_FILE_CONTENTS}

## Validation Rules
{PASTE_RULES_FOR_THIS_TYPE}

## Instructions
1. Compare every plugin file against the official documentation
2. Check all fields, values, and structures against what docs say is valid
3. Identify anything the plugin uses that docs don't mention (potential deprecation)
4. Identify anything docs mention that the plugin doesn't use (new features)
5. Write detailed findings to: .claude/docs-check/reports/{type}-report.md

## Report Format
# {Type} Validation Report

## Breaking Changes (BLOCKER)
## Deprecations (WARNING)
## New Features Available (INFO)
## Validation Passed

Return ONLY a summary — max 500 words.
```

**Spawn ALL workers in parallel:**

```text
Agent(subagent_type: "general-purpose", model: "sonnet", run_in_background: true, prompt: "...")
```

**Wait for ALL workers to complete before proceeding.**

## Phase 4: Context Supervision (Compression)

If 3+ workers spawned, compress findings:

```text
Agent(subagent_type: "phx:context-supervisor", prompt: """
  input_dir: .claude/docs-check/reports/
  output_dir: .claude/docs-check/summaries/
  priority_instructions: |
    KEEP ALL: Breaking changes, deprecation warnings, field mismatches
    COMPRESS: New feature suggestions, adoption recommendations
    AGGRESSIVE: Passed checks, informational confirmations
""")
```

If <3 workers, read reports directly (skip compression).

## Phase 5: Structural Checks (Always Run)

These run without docs or subagents — fast, free, always execute:

### Agent Frontmatter

Parse YAML frontmatter from each agent `.md` file, verify:

- `name` present (required), `description` present (required)
- `model` ∈ `{sonnet, opus, haiku, inherit}` (if present)
- `permissionMode` ∈ `{default, acceptEdits, delegate, dontAsk, bypassPermissions, plan}` (if present)
- `tools` contains only valid tool names (if present)
- Line count: specialist ≤365, orchestrator ≤535

### Skill Structure

- Each skill dir has `SKILL.md` with `name` in frontmatter
- No `triggers:` field in frontmatter
- Line count: SKILL.md ≤185, references/*.md ≤350

### Hook Schema

- Valid JSON, top-level key `hooks`
- Event names ∈ valid set (see validation-rules.md)
- Each hook has `type` ∈ `{command, prompt, agent}`

### Plugin Config

- Valid JSON, `name` field present (required)
- All path references resolve to existing files/directories

## Phase 6: Generate Report

Read compressed summary + structural results.
Write to `.claude/docs-check/docs-check-{YYYY-MM-DD}.md`:

```markdown
# Plugin Documentation Compatibility Report

**Date**: {date}
**Plugin Version**: {from plugin.json}
**Docs Fetched**: {list of pages}

## Summary

| Category | Status | Blockers | Warnings | New Features |
|----------|--------|----------|----------|--------------|
| Agents   | ✅/⚠️/❌ | 0 | 0 | 0 |
| Skills   | ✅/⚠️/❌ | 0 | 0 | 0 |
| Hooks    | ✅/⚠️/❌ | 0 | 0 | 0 |
| Config   | ✅/⚠️/❌ | 0 | 0 | 0 |
| Structure| ✅/⚠️/❌ | 0 | 0 | — |

### Verdict: {COMPATIBLE | WARNINGS | ACTION REQUIRED}

## Breaking Changes / Deprecations / New Features / Structural Issues
## Detailed Findings
```

## Phase 7: Action

**If issues found:** Offer three choices:

1. "Create a branch and fix issues, then open a PR"
2. "Show the detailed report only"
3. "Fix only the blockers"

**If clean:** "Plugin is compatible. {n} new features available — want to explore any?"

## Iron Laws

1. **NEVER fetch docs** — read from cache only, crash if missing
2. **Every worker gets docs IN PROMPT** — workers must not fetch