Plugin Documentation Compatibility Check

Validates plugin agents, skills, hooks, and config against the latest Claude Code documentation to catch breaking changes and discover new features.

Usage

/docs-check # Full validation (all components) /docs-check --quick # Structural checks only (no docs fetch, no tokens) /docs-check --focus=agents # Validate only agents /docs-check --focus=skills # Validate only skills /docs-check --focus=hooks # Validate only hooks /docs-check --focus=config # Validate only plugin.json/marketplace.json

Architecture (OTP Supervision Pattern)

┌─────────────────────────────────────────────────────────────────┐ │ /docs-check (skill entry point) │ │ │ │ │ ├─ Step 1: bash scripts/fetch-claude-docs.sh (zero tokens) │ │ │ Always fetches all 9 doc pages (~420KB) │ │ │ │ │ └─ Step 2: delegate to orchestrator (reads from cache only) │ │ │ │ │ │ docs-validation-orchestrator (opus) │ │ │ │ │ │ SCAN → READ CACHE → SPAWN WORKERS → COMPRESS → REPORT │ │ │ │ │ │ │ │ │ │ │ ↓ ↓ ↓ ↓ ↓ │ │ │ inventory pre-fetched 4 parallel context report │ │ │ plugin docs-cache subagents supervisor │ │ │ components (sonnet) (haiku) │ │ └─────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────┘

Execution

Step 1: Fetch Docs (Automatic)

Always run first. Downloads all doc pages to cache. Skips pages already cached within 24h. Zero token cost — pure curl.

--quick mode: skip this step entirely (structural checks only)

All other modes: always fetch

bash scripts/fetch-claude-docs.sh

Step 2: Delegate to Orchestrator

After docs are cached, delegate. The orchestrator reads from cache only and crashes if cache files are missing.

Task(subagent_type: "docs-validation-orchestrator")

Pass the user's flags (--quick, --focus) in the prompt.

What the Orchestrator Does

• Inventory — scan plugins/elixir-phoenix/ for existing components

• Read cached docs — from .claude/docs-check/docs-cache/ (never fetches)

• Spawn workers — one sonnet subagent per component type, in parallel

• Compress — context-supervisor (haiku) if 3+ workers

• Structural checks — fast local checks, always run

• Report & Action — write report, offer PR if issues found

Iron Laws

• Fetch ALL docs upfront — no conditional fetching, no partial downloads

• Use scripts/fetch-claude-docs.sh — single source of truth for doc fetching

• Workers get docs IN PROMPT — no runtime fetching

• Workers use sonnet — opus is wasteful for comparison tasks

• Structural checks always run — even if docs fetch fails

• Breaking changes are BLOCKERS — surface prominently

References

• references/validation-rules.md — Per-component validation checklists

• references/doc-pages.md — Component-to-URL mapping