review-agents

name	review-agents
description	Review all specialist agent definitions in .claude/agents/ for accuracy, currency, and Anthropic best-practice compliance. Flags stale references, wrong model assignments, missing examples, merge/split candidates, and gap-analysis coverage. Creates board tasks for every finding.
disable-model-invocation	true
user-invocable	true

Agent Review Protocol

Comprehensive review of every .claude/agents/*.md file. Part of the review-* skill family. Cites ../_shared/review-checklist.md and ../_shared/anthropic-configuration-guide.md.

Owner: docs-manager agent.

When to invoke

• Periodic audit (quarterly or after major infrastructure changes)
• After model upgrades (e.g., Opus 4.7 → 4.8)
• When new services, features, or domains land without a specialist
• Before a big delegation-heavy initiative where agent accuracy matters

Output contract

This skill produces only board tasks. It does not write findings into the conversation. Main-agent output = a lean summary pointing to the Vibe Board parent task.

---

Step 1 — Inventory

Read every file matching .claude/agents/*.md. Extract:

• name, description, model, color, memory, tools (if present)
• Trigger keywords from description
• File/path references (via regex for .md, src/, services/, docs/)
• Service references (cross-check with services/ directory)
• Table references (cross-check with Postgres schema)
• Code snippets (language fence blocks)
• <example> block count

Record in a structured list. Don't dump it to the user.

Step 2 — Frontmatter validation

Apply the schema from review-checklist.md §"Agents". For each agent, flag:

Issue	Severity
Missing name or mismatched with filename	critical
Missing description	critical
Missing model (defaulting to inherit without justification)	high
description uses undocumented frontmatter conventions	medium
No <example> blocks or only 1	medium
No <commentary> in examples	low
description + when_to_use combined > 1,536 chars	high
Uses invented (non-Anthropic) keys	high

Step 3 — Description quality

Check each description against the canonical pattern: [role]. [what it does]. [when to invoke + triggers].

Flag:

• Generic phrasing ("helps with database stuff")
• No trigger keywords
• Vague "when to use" that doesn't distinguish from peer agents
• Missing examples showing delegation pattern

Step 4 — Model assignment review

For each agent, check the model tier against the rubric in review-checklist.md §"Model assignment".

Priority: flag Opus assignments on routine-content work first (highest cost savings). Flag Sonnet or Haiku on critical-review work second (highest correctness risk).

Known high-value reassignment candidates (verify during review):

• Routine-content specialists currently on Opus → likely Sonnet
• Orchestrators currently on Sonnet or below → likely Opus
• inherit on any critical-path agent → pin explicitly

User is on max Claude plan — bias upward on ambiguous cases.

Step 5 — Content freshness

For each agent, verify:

1. Referenced file paths — Glob every path mentioned in the body; flag missing.
2. Code examples — Grep for the pattern in the current codebase; flag dead references.
3. Service references — cross-check services/ directory; flag retired services (e.g., Supabase Edge Functions — archived 2026-02-24).
4. Table references — cross-check with current Postgres schema via pg MCP or SSH psql.
5. Domain/URL references — Confirm ai.<your-domain>, <your-domain>, etc. still current.
6. Command references — Confirm Enter C -push, /plan, /review etc. still work.

Step 6 — Merge / split analysis

For the roster as a whole:

Merge candidates — pairs of agents where:

• Description overlap > 80% semantic similarity
• Trigger keywords overlap > 50%
• Same domain boundary

Split candidates — single agents where:

• Description uses "and" to join unrelated domains
• Trigger keywords cluster into 2+ disjoint groups
• Prompt body spans multiple distinct concerns

For each recommendation, include rationale and proposed new structure.

Step 7 — Gap analysis

Find new ground without a specialist:

1. List services in services/ — does each have a specialist (directly or under a broader agent)?
2. List top-level directories in src/features/ — does each map to a specialist?
3. List Cloud Run services — covered?
4. List MIG services — covered?
5. List newly added systems in recent CLAUDE.md commits — covered?

Flag gaps as "Create new agent for [feature/service]".

Step 8 — README consistency

Check .claude/agents/README.md:

• Agent count matches actual file count (excluding archived)
• Every agent in the roster has a row in the appropriate tier table
• Trigger keywords in README match the agent's description
• Archived agents section accurate

Step 9 — File findings to the board

MANDATORY: every finding becomes a board task. Nothing lives only in conversation.

1. Create parent tasks per severity tier on the current project (or Opus 4.7 System Audit/Review project, id <YOUR_AUDIT_PROJECT_ID>):
   • [review-agents] Critical findings
   • [review-agents] High findings
   • [review-agents] Medium findings
   • [review-agents] Low findings
2. For each finding, create a subtask under the matching parent with:
   • title: [agent-name]: [short issue]
   • description: file path + specific issue + recommended fix
   • assigned_agent: typically docs-manager (it owns agent files)
   • priority: matches severity tier
3. Log the summary via board_log_activity on the parent tasks.

Step 10 — Summary

Return to the main agent (keep ≤ 100 words):

AGENT REVIEW COMPLETE
- [N] agents reviewed (excluding [X] archived)
- [C] critical findings → board parent <id>
- [H] high findings → board parent <id>
- [M] medium findings → board parent <id>
- [L] low findings → board parent <id>
- [G] gap candidates → board <id>
- [MS] merge/split recommendations → board <id>

All findings in Vibe Board project [project_id]. Review checklist: ../_shared/review-checklist.md.

Anti-patterns to flag proactively

• Agent descriptions that start with "Use this agent when..." without concrete trigger keywords
• Model field missing or implicit inherit on a critical-path agent
• Code examples that reference dead or renamed services
• Two agents with near-identical trigger keyword sets
• Agent prompt body > 1500 words
• Missing <example> blocks in description
• References to deprecated Claude Code commands (/tag, /vim, /output-style)
• References to removed infrastructure (Supabase Edge Functions, old MIG versions)

Tools used

• Read — agent file contents
• Glob — file/path existence
• Grep — code pattern freshness
• Bash (restricted) — ls on service directories, psql via SSH for schema checks
• Board MCP — board_create_task, board_update_task, board_log_activity