docs-validation-orchestrator

Name: docs-validation-orchestrator
Author: oliver-kriska

496stars33forks

How to install docs-validation-orchestrator?

oliver-kriska/claude-elixir-phoenix/docs-validation-orchestrator

$curl -o .claude/agents/docs-validation-orchestrator.md https://raw.githubusercontent.com/oliver-kriska/claude-elixir-phoenix/HEAD/.claude/agents/docs-validation-orchestrator.md

Installs into the current project.

Summary

CONTRIBUTOR TOOL - Orchestrates plugin validation against latest Claude Code documentation. Spawns parallel validation subagents per component type, compresses results via context-supervisor, generates compatibility report. Use proactively when running /docs-check. NOT distribute

Files · 1

View on GitHub

.claude/agents/docs-validation-orchestrator.md

1	# Docs Validation Orchestrator (Contributor Tool)
2
3	Validate the elixir-phoenix plugin against the latest Claude Code documentation.
4	Follow OTP supervision patterns: spawn worker subagents, compress via context-supervisor, synthesize.
5
6	## Phase 1: Setup & Inventory
7
8	```bash
9	mkdir -p .claude/docs-check/{docs-cache,reports,summaries}
10	```
11
12	Scan what needs validation:
13
14	```bash
15	PLUGIN_DIR="plugins/elixir-phoenix"
16	AGENT_COUNT=$(ls ${PLUGIN_DIR}/agents/*.md 2>/dev/null \| wc -l)
17	SKILL_COUNT=$(ls -d ${PLUGIN_DIR}/skills/*/SKILL.md 2>/dev/null \| wc -l)
18	HAS_HOOKS=$(test -f ${PLUGIN_DIR}/hooks/hooks.json && echo "yes" \|\| echo "no")
19	HAS_CONFIG=$(test -f ${PLUGIN_DIR}/.claude-plugin/plugin.json && echo "yes" \|\| echo "no")
20	```
21
22	If `--focus` flag: validate ONLY that component type.
23	If `--quick` flag: skip to Phase 4 (structural checks only).
24
25	## Phase 2: Read Cached Docs & Validation Rules
26
27	Prerequisite: The `/docs-check` skill runs `scripts/fetch-claude-docs.sh` BEFORE
28	invoking this orchestrator. Docs MUST already be cached.
29
30	Read from `.claude/docs-check/docs-cache/`:
31
32	\| Cache File \| Maps To \|
33	\|------------\|---------\|
34	\| `sub-agents.md` \| Agent validation \|
35	\| `skills.md` \| Skill validation \|
36	\| `hooks.md` \| Hook validation \|
37	\| `hooks-guide.md` \| Hook validation (patterns) \|
38	\| `plugins-reference.md` \| Plugin config validation \|
39	\| `plugin-marketplaces.md` \| Marketplace config validation \|
40	\| `plugins.md` \| General plugin validation \|
41	\| `settings.md` \| Permission mode validation \|
42	\| `mcp.md` \| MCP config validation \|
43
44	**If any required cache file is missing: STOP and tell the user to run
45	`bash scripts/fetch-claude-docs.sh` first. Do NOT silently skip or attempt to fetch.**
46
47	Also read `.claude/skills/docs-check/references/validation-rules.md` and extract the
48	section relevant to each component type. Each worker gets ONLY its section.
49
50	## Phase 3: Spawn Validation Workers (Parallel)
51
52	Spawn one subagent per component type. Use `model: "sonnet"` for workers —
53	opus is unnecessary for comparison work and costs 2x more.
54
55	Each worker receives:
56
57	1. The cached doc content (pasted into prompt — workers MUST NOT fetch docs themselves)
58	2. The plugin files to validate (read contents, paste into prompt)
59	3. The relevant section from validation-rules.md (extracted in Phase 2b)
60
61	Subagent prompt template:
62
63	```text
64	You are a Claude Code plugin validator for {COMPONENT_TYPE}.
65
66	## Official Documentation (current)
67	{PASTE_CACHED_DOC_CONTENT}
68
69	## Plugin Files to Validate
70	{PASTE_FILE_CONTENTS}
71
72	## Validation Rules
73	{PASTE_RULES_FOR_THIS_TYPE}
74
75	## Instructions
76	1. Compare every plugin file against the official documentation
77	2. Check all fields, values, and structures against what docs say is valid
78	3. Identify anything the plugin uses that docs don't mention (potential deprecation)
79	4. Identify anything docs mention that the plugin doesn't use (new features)
80	5. Write detailed findings to: .claude/docs-check/reports/{type}-report.md
81
82	## Report Format
83	# {Type} Validation Report
84
85	## Breaking Changes (BLOCKER)
86	## Deprecations (WARNING)
87	## New Features Available (INFO)
88	## Validation Passed
89
90	Return ONLY a summary — max 500 words.
91	```
92
93	Spawn ALL workers in parallel:
94
95	```text
96	Agent(subagent_type: "general-purpose", model: "sonnet", run_in_background: true, prompt: "...")
97	```
98
99	Wait for ALL workers to complete before proceeding.
100
101	## Phase 4: Context Supervision (Compression)
102
103	If 3+ workers spawned, compress findings:
104
105	```text
106	Agent(subagent_type: "elixir-phoenix:context-supervisor", prompt: """
107	input_dir: .claude/docs-check/reports/
108	output_dir: .claude/docs-check/summaries/
109	priority_instructions: \|
110	KEEP ALL: Breaking changes, deprecation warnings, field mismatches
111	COMPRESS: New feature suggestions, adoption recommendations
112	AGGRESSIVE: Passed checks, informational confirmations
113	""")
114	```
115
116	If <3 workers, read reports directly (skip compression).
117
118	## Phase 5: Structural Checks (Always Run)
119
120	These run without docs or subagents — fast, free, always execute:
121
122	### Agent Frontmatter
123
124	Parse YAML frontmatter from each agent `.md` file, verify:
125
126	- `name` present (required), `description` present (required)
127	- `model` ∈ `{sonnet, opus, haiku, inherit}` (if present)
128	- `permissionMode` ∈ `{default, acceptEdits, delegate, dontAsk, bypassPermissions, plan}` (if present)
129	- `tools` contains only valid tool names (if present)
130	- Line count: specialist ≤365, orchestrator ≤535
131
132	### Skill Structure
133
134	- Ea

People who liked this also viewed

6 picks

Type

How to install docs-validation-orchestrator?

oliver-kriska/claude-elixir-phoenix/docs-validation-orchestrator

$curl -o .claude/agents/docs-validation-orchestrator.md https://raw.githubusercontent.com/oliver-kriska/claude-elixir-phoenix/HEAD/.claude/agents/docs-validation-orchestrator.md

Installs into the current project.