Agent Specialization

Understanding why Agent Flow uses multiple specialized agents instead of a single general-purpose agent, and how model selection optimizes for both quality and cost.

The Case for Specialization

A single general-purpose agent attempting to handle exploration, planning, implementation, review, and verification faces several challenges:

1. Context overload: Trying to hold all skills in context dilutes focus
2. Tool conflicts: Having all tools available creates temptation to shortcut
3. Role confusion: Unclear when to plan vs. implement vs. verify
4. No separation of concerns: Self-review is inherently less rigorous

Agent Flow addresses these by creating focused specialists, each with: - A clear role and responsibility - A restricted set of appropriate tools - Specific behavioral guidelines - An optimal model for their task type

Agent Roles

Riko - The Explorer

Purpose: Fast codebase exploration and information gathering

Why specialized? - Exploration requires breadth-first thinking - Read-only access prevents accidental modifications - Web access enables external documentation lookup - Focus on finding, not implementing

Model: Sonnet, effort: medium (breadth-first exploration favors speed)

Tools: Read, Grep, Glob, Bash (AST analysis only), WebSearch, WebFetch, graphify MCP (7 tools), personal-kb MCP (7 tools), agentsview MCP (5 tools)

Skills: Owns exploration-strategy, graphify-usage, personal-kb-usage, agentsview-usage; consumes agent-behavior-constraints, task-classification

Key behaviors: - Tier 0: Graph Orientation (when graphify-out/graph.json exists): run graph_stats + god_nodes for structural overview before grepping - Three-tier search: local repository, web, user clarification - Evidence-based findings with file paths and line numbers - Never runs code or modifies files

Senku - The Planner

Purpose: Strategic planning and implementation strategy

Why specialized? - Planning requires foresight and risk assessment - Separation from implementation prevents premature coding - Numbered markdown checklists create structured, trackable plans - Focus on strategy, not execution

Model: Opus (strategic planning needs deep reasoning)

Tools: Read, Grep, Glob, Write (plan/report files only), graphify MCP (7 tools), personal-kb MCP (7 tools), agentsview MCP (5 tools)

Skills: Owns task-classification, prompt-refinement; consumes agent-behavior-constraints, exploration-strategy, graphify-usage, personal-kb-usage, agentsview-usage

Key behaviors: - Explores codebase to understand existing patterns - Runs get_neighbors blast-radius check (when graph available) before finalizing file list - Creates step-by-step implementation plans - Identifies risks and edge cases - Produces a Deliverable Output Contract (target format / acceptance criteria / risks) in every plan that yields an artifact - Never writes code directly

Loid - The Executor

Purpose: Code implementation following plans

Why specialized? - Implementation benefits from focused execution - Having Write/Edit tools concentrated in one agent - Quick sanity tests catch immediate issues - Clear handoff points to verification

Model: Sonnet (fast execution with sufficient capability)

Tools: Read, Write, Edit, Bash, Grep, Glob

Key behaviors: - Follows plans precisely - Makes changes incrementally - Runs targeted checks on changed code; Alphonse runs the full suite - Reports blockers immediately

Lawliet - The Reviewer

Purpose: Code quality assurance through static analysis

Why specialized? - Review requires independent perspective - Separation from implementation enables objectivity - Static analysis focus (no test execution) - Clear verdict for proceed/iterate decision

Model: Sonnet (fast iteration for review cycles)

Tools: Read, Grep, Glob, Bash (static analysis only), graphify MCP (7 tools), personal-kb MCP (7 tools), agentsview MCP (5 tools)

Skills: Consumes agent-behavior-constraints, verification-gates, graphify-usage, personal-kb-usage, agentsview-usage, evidence-driven-work

Key behaviors: - First move on any multi-file review is graph_stats + god_nodes(top_n=5) for blast-radius orientation — before reading files - Reviews all modified files - Runs get_neighbors blast-radius check (when graph available) to scope high-risk review targets - Runs type checking and linting - Checks security concerns - Provides actionable feedback

Alphonse - The Verifier

Purpose: Comprehensive verification through test execution

Why specialized? - Verification is the final quality gate - Separation from implementation prevents bias - Focus on running commands and reporting results - Clear pass/fail determination

Model: Sonnet (quick command execution)

Tools: Bash, Read, Grep

Skills: Owns verification-gates; consumes agent-behavior-constraints, evidence-driven-work

Key behaviors: - Runs the test suite and build (type check and lint too when run on its own; in the parallel flow Lawliet covers those) - Reports exact command output - Never modifies code

Speedwagon - The Author

Purpose: Authors interactive HTML explainer modules for /explain; it is not part of the /orchestrate pipeline

Model: Sonnet (fast content authoring)

Tools: Read, Grep, Glob, Write, Edit, Bash, each scoped. Write/Edit only to explain-out/ and .claude/explain-briefs/; Bash only for compile-explain.sh.

Skills: Consumes explainer-design-system, exploration-strategy, agent-behavior-constraints

Model Selection Strategy

Agent Flow uses two model tiers optimized for different task types:

flowchart TB
    subgraph Opus["Opus - Strategic Tasks"]
        direction LR
        O1["Deep Reasoning"]
        O2["Complex Analysis"]
        O4["Strategic Planning"]
    end

    subgraph Sonnet["Sonnet - Execution Tasks"]
        direction LR
        S1["Well-Defined Tasks"]
        S2["Fast Iteration"]
        S3["Clear Criteria"]
        S4["Command Execution"]
    end

    Opus --> SK[Senku]
    Sonnet --> R[Riko] & L[Loid] & LW[Lawliet] & A[Alphonse] & SW[Speedwagon]

Model Assignment Rationale

Agent	Model	Rationale
Riko	Sonnet	Exploration is breadth-first search; speed matters more than deep reasoning
Senku	Opus	Strategic planning requires deep reasoning for task decomposition
Loid	Sonnet	Implementation benefits from speed with sufficient capability
Lawliet	Sonnet	Review cycles need fast iteration for feedback loops
Alphonse	Sonnet	Verification is command-focused with clear pass/fail criteria
Speedwagon	Sonnet	Explainer authoring fills a fixed template from Riko's scope and Senku's curriculum

Tool Access Matrix

Each agent has a restricted toolset matching their responsibilities:

Agent           Read  Grep  Glob  Write  Edit  Bash  Web   graphify  personal-kb  agentsview
-----------     ----  ----  ----  -----  ----  ----  ---   --------  -----------  ----------
Riko            Yes   Yes   Yes   -      -     Yes*  Yes   MCP       MCP          MCP
Senku           Yes   Yes   Yes   Yes†   -     -     -     MCP       MCP          MCP
Loid            Yes   Yes   Yes   Yes    Yes   Yes   -     -         -            -
Lawliet         Yes   Yes   Yes   -      -     Yes** -     MCP       MCP          MCP
Alphonse        Yes   Yes   -     -      -     Yes   -     -         -            -
Speedwagon      Yes   Yes   Yes   Yes‡   Yes‡  Yes‡  -     -         -            -

*  Riko's Bash is restricted to AST analysis tools (ast-grep, tree-sitter, language parsers),
   plus writing its own report to .claude/agent-reports/
** Lawliet's Bash is restricted to static analysis tools, plus writing its own report to
   .claude/agent-reports/
†  Senku's Write is scoped to plan/report files under .claude/agent-reports/ or .senku/
‡  Speedwagon's Write/Edit are scoped to explain-out/ and .claude/explain-briefs/; its Bash
   runs only the explainer assembler (scripts/compile-explain.sh)
MCP = read-only access via MCP server tools

Key Restrictions

1. Only Loid modifies source files (Write, Edit)
2. Scoped exceptions: Senku writes plan/report files, Speedwagon writes explain-out/ and .claude/explain-briefs/, and Riko, Lawliet and Alphonse write their own long reports to .claude/agent-reports/
3. Prevents accidental changes during exploration

4. Creates clear audit trail

5. Only Riko can access the web (WebSearch, WebFetch)

6. Focuses web usage on research
7. Prevents implementation shortcuts

8. Maintains codebase focus

9. Only Senku authors plans (numbered markdown checklists; Write scoped to plan/report files)

10. Centralizes planning authority
11. Creates structured implementation paths
12. Prevents ad-hoc task creation

Specialization Benefits

Clear Responsibility

Each agent knows exactly what they should and should not do:

Riko:    "I find things. I don't change things."
Senku:   "I plan things. I don't implement things."
Loid:    "I implement things. I don't plan things."
Lawliet: "I review things. I don't fix things."
Alphonse: "I verify things. I don't modify things."

Separation of Concerns

The agent pipeline creates natural checkpoints:

Exploration -> Planning -> Implementation -> Review + Verification (parallel)
    |             |             |              |
  Context      Strategy       Code        Quality assurance
  gathering    design        changes      and evidence

Lawliet, Alphonse and (when the profile includes it) Codex run in parallel because none of them writes code. Exploration and planning are skipped for small tasks.

Independent Verification

Because verification agents didn't write the code: - No bias toward "my code works" - Fresh perspective on quality - Objective pass/fail determination

Extending with New Agents

When adding new agents, consider:

1. What is their specific responsibility?
2. Single, focused purpose

3. Clear boundaries with existing agents

4. What tools do they need?

5. Minimum necessary for their role

6. Avoid overlapping capabilities

7. Which model tier?

8. Strategic/planning tasks -> Opus

9. Execution/verification tasks -> Sonnet

10. How do they fit the workflow?

11. Which phase do they participate in?
12. What handoffs do they receive/provide?

See Adding Agents Guide for implementation details.

Related Concepts

• The "Subagents LIE" Principle - Why verification is separate
• Evidence-Based Verification - What constitutes proof
• Architecture Overview - System design
• Agents Reference - Complete specifications