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

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

Scan what needs validation:

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.