consolidate-review-agents

name: consolidate-review-agents description: 'Merge overlapping review specialist agents into a single general-review-specialist. Use when: (1) multiple review agents have overlapping scopes, (2) project complexity doesn''t justify 10+ specialists, (3) you want to reduce total agent count while keeping full review coverage.' category: architecture date: 2026-03-05 version: 1.0.0 user-invocable: false

Overview

When to Use

Trigger this skill when:

1. Agent count for a single concern (e.g., code review) has grown to 10+
2. Most specialists share identical YAML frontmatter (same tools, model, level, phase, hooks)
3. Specialists cross-reference each other in "What I do NOT review" sections, creating circular scope
4. The project is still in planning/early implementation phase — premature specialization adds overhead
5. An orchestrator's delegates_to list has more than 5–6 entries for the same concern

Verified Workflow

Step 1: Identify candidates for merging

Read all candidate files. Look for:

• Same tools, model, level, phase, and hooks in YAML frontmatter
• Scope definitions that explicitly exclude each other ("→ Implementation Specialist", "→ Algorithm Specialist")
• Small, focused review checklists (5–10 items each)

Agents to keep separate if they have genuinely unique requirements:

• Mojo-language-specific agents (special syntax knowledge)
• Security agents (distinct attack-vector expertise)
• Test agents (coverage metrics, assertions)
• Orchestrators (coordination role, different tools)

Step 2: Create general-review-specialist.md

Create .claude/agents/general-review-specialist.md with:

---
name: general-review-specialist
description: "Reviews code for [list all merged dimensions]. Select for any general code review dimension not covered by [remaining specialists]."
level: 3
phase: Cleanup
tools: Read,Grep,Glob
model: sonnet
delegates_to: []
receives_from: [code-review-orchestrator]
hooks:
  PreToolUse:
    - matcher: "Edit"
      action: "block"
      reason: "Review specialists are read-only - cannot modify files"
    - matcher: "Write"
      action: "block"
      reason: "Review specialists are read-only - cannot create files"
    - matcher: "Bash"
      action: "block"
      reason: "Review specialists are read-only - cannot run commands"
---

Body structure:

• One ## Scope section with subsections per merged domain
• Merged review checklists (one per domain)
• Representative example review per domain (keep 3–4, skip redundant ones)
• Coordinates With pointing to remaining specialists

Step 3: Delete the merged files

git rm .claude/agents/algorithm-review-specialist.md \
       .claude/agents/architecture-review-specialist.md \
       # ... (all 10)

Step 4: Update the orchestrator

In code-review-orchestrator.md, update:

• delegates_to list: replace 10 entries with general-review-specialist
• Delegation decision matrix: merge 10 rows into one catch-all row
• Routing dimensions table: collapse to 4 rows
• "Delegates To" section: 13 items → 4 items
• Body text mentioning "13 specialists" → "4 specialists"

Step 5: Update hierarchy documentation

In agents/hierarchy.md, update:

• Level 3 specialist count in the ASCII diagram
• Level 3 agent count in the "Level Summaries" section
• Agent Count table (Level 3 row + Total row)
• Level 3 Breakdown bullet list

Step 6: Validate

python3 tests/agents/validate_configs.py .claude/agents/
pixi run pre-commit run --all-files

All hooks should pass. The mojo GLIBC errors on older Linux systems are pre-existing environment issues unrelated to agent file changes.

Failed Attempts

Results & Parameters

ProjectOdyssey outcome:

Before: 13 review specialists (algorithm, architecture, data-engineering,
        dependency, documentation, implementation, mojo-language, paper,
        performance, research, safety, security, test)

After: 5 review agents (general, mojo-language, security, test, orchestrator)

Files changed: -10 deleted, +1 created, +2 updated
Lines changed: -1063 insertions, +297 deletions (net -766 lines)
Total agents: 44 → 35

Which specialists to keep separate (decision criteria):

Key insight: When 10 agents all have identical tools: Read,Grep,Glob, model: sonnet, level: 3, phase: Cleanup, and identical hooks blocks, they are structurally identical. The only difference is the review checklist — which can live as subsections in one file.