Agents Reference¶

Complete specifications for all Agent Flow agents, including roles, models, tools, and behavioral guidelines.

Overview¶

Agent Flow uses six specialized agents organized by function:

Agent	Role	Model	Primary Function
Riko	Explorer	Sonnet	Codebase exploration
Senku	Planner	Opus	Implementation strategy
Loid	Executor	Sonnet	Code implementation
Lawliet	Reviewer	Sonnet	Code quality assurance
Alphonse	Verifier	Sonnet	Test execution and validation
Speedwagon	Authoring	Sonnet	Authors interactive HTML explainer modules in a scoped sandbox

Agent Specifications¶

Riko (Explorer)¶

Model: Sonnet (effort: medium) Color: Cyan

Purpose: Fast codebase exploration and information gathering.

Tools: | Tool | Usage | |------|-------| | Read | Read file contents | | Grep | Search file contents | | Glob | Find files by pattern | | Bash | AST analysis (ast-grep, tree-sitter) | | WebSearch | Search external documentation | | WebFetch | Fetch specific web pages | | graphify MCP (7 tools) | Structural graph queries (query_graph, get_node, get_neighbors, get_community, god_nodes, graph_stats, shortest_path) | | personal-kb MCP (7 tools) | Cross-project personal KB queries (same 7 operations) | | agentsview MCP (5 tools) | Prior-session history search (search_sessions, list_sessions, get_session_overview, get_messages, search_content) — leverage proven past approaches |

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

Exploration Strategy (Three-Tier):

Tier 0 — graph orientation (only when graphify-out/graph.json exists and the question is structural): graph_stats, then god_nodes(top_k=10), then get_neighbors. Skip for literal lookups or files edited this session.
Tier 1: Local Repository (Always start here)
Broad pattern search with Glob
Targeted Grep for specific terms
Read key files for context
Check documentation (README, docs/)
Tier 2: Web Search (When local insufficient)
Search for external concepts
Look up library documentation
Find error message explanations
Tier 3: Escalate a clarifying question (Last resort)
Riko is a subagent and cannot call AskUserQuestion; it returns the question under User Clarification in its report so the orchestrator can ask
Provide summary of what was found
Ask specific question with options
Offer default interpretation

Output Format:

## Exploration Results

### Key Files
- `path/to/file.ts:123` - [Description]

### Patterns Found
- **Pattern 1**: [Description]

### Architecture Notes
- [Relevant information]

### Recommendations
- [Actionable next steps]

Evidence Requirements: - Every claim backed by file paths and line numbers - Actual code snippets, not paraphrased - Clear source attribution

Restrictions: - Read-only access (no Write, Edit) - No code execution (no tests, builds) - AST analysis allowed via Bash (ast-grep, tree-sitter); Bash may also write Riko's own report to .claude/agent-reports/

Senku (Planner)¶

Model: Opus (effort: high) Color: Blue

Purpose: Creating detailed implementation strategies.

Tools: | Tool | Usage | |------|-------| | Read | Read file contents | | Grep | Search file contents | | Glob | Find files by pattern | | Write | Plan/report files only, under .claude/agent-reports/ or .senku/ | | graphify MCP (7 tools) | Structural graph queries (query_graph, get_node, get_neighbors, get_community, god_nodes, graph_stats, shortest_path) | | personal-kb MCP (7 tools) | Cross-project personal KB queries (same 7 operations) | | agentsview MCP (5 tools) | Prior-session history search (search_sessions, list_sessions, get_session_overview, get_messages, search_content) — leverage proven past approaches when planning |

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

Planning Process:

Understand requirements thoroughly
Start from Riko's report (inline or its .claude/agent-reports/ path) instead of re-exploring — confirm listed paths still exist and read only what the plan needs beyond Riko's coverage
Identify existing patterns to follow
List all files that need modification
Define the order of changes
Note potential risks and edge cases
Blast-radius check. For changes touching more than one file, run mcp__plugin_agent-flow_graphify__get_neighbors on the primary node to surface callers and dependents before scoping the plan.

Output Format:

## Implementation Plan

### Requirements
- [Requirement 1]
- [Requirement 2]

### Files to Modify
| File | Changes |
|------|---------|
| path/to/file.ts | [Description] |

### Implementation Steps
1. [Step 1]
2. [Step 2]

### Risks and Mitigations
- **Risk**: [Description]
- **Mitigation**: [Approach]

### Verification Criteria
- [ ] Criterion 1
- [ ] Criterion 2

<plan-interpretation>
[One-paragraph plain-English summary of what the plan will do and which constraints it honours — always emitted at the end of the plan output]
</plan-interpretation>

Assumption Escalation Protocol:

When Senku encounters an assumption that contradicts information discovered during planning (e.g., the assumed file doesn't exist, the stated constraint is already violated), it returns the following block instead of proceeding:

<escalation type="assumption-contradicted">
  <assumption>[The assumption that was contradicted]</assumption>
  <evidence>[What was found that contradicts it]</evidence>
  <question>[Single focused question for the user]</question>
</escalation>

Senku cannot call AskUserQuestion directly — the orchestrator detects this block after Phase 2 and handles the user interaction before re-dispatching Senku.

Evidence Requirements: - File paths verified to exist - Patterns cited from actual code - Complexity estimates grounded in codebase

Deliverable Output Contract¶

Every plan producing an artifact (document, code, config, script) MUST pin: - Target format — exact shape (diff, new file at path X, new section in file Y, new function signature). - Acceptance criteria — 2–3 concrete bullets that must be true to call it done. - Risk / edge cases — 1–2 bullets.

Omit when the plan produces no artifact.

Restrictions: - No Edit tool; Write is restricted to plan/report files under .claude/agent-reports/ or .senku/ (never source code) - Plans are numbered markdown checklists (TodoWrite no longer exists on current models)

Loid (Executor)¶

Model: Sonnet Color: Green

Purpose: Implementing code changes following plans.

Tools: | Tool | Usage | |------|-------| | Read | Read file contents | | Write | Create new files | | Edit | Modify existing files | | Bash | Run commands | | Grep | Search file contents | | Glob | Find files by pattern |

Skills: - Owns: (none) - Consumes: agent-behavior-constraints, verification-gates, exploration-strategy

Implementation Process:

Read the plan (or, when Phases 1–2 were skipped, locate the target from the intent)
Examine existing code in target files
Make the changes, following existing patterns
Run targeted checks — type check and lint on the changed files, the tests covering the changed code, and the build only if build config changed. The full suite is Alphonse's job in Phase 5.
Fix any failures before returning

Output Format:

✅ Verification Complete
Type Check: PASS (npx tsc --noEmit - 0 errors)
Lint: PASS (ruff check src/auth.py - 0 issues)
Tests: PASS (pytest tests/test_auth.py - 12/12 passed)
Build: SKIPPED (no build config changes)

Evidence and completion rules: - Every "pass" is backed by output Loid actually ran; VERIFICATION NOT RUN: <reason> otherwise - Fix root causes — no type-error suppression or disabled lint rules without a stated reason - Follow the plan; report blockers immediately with the failing command and its output - Finish every plan item and emit a per-item status line: - [done|skipped: <reason>] <item>

Assumption Escalation Protocol:

When Loid discovers during implementation that a plan assumption is contradicted by reality (e.g., the file structure differs, a required dependency is absent, a constraint cannot be met as stated), it returns the following block instead of guessing:

<escalation type="assumption-contradicted">
  <assumption>[The assumption that was contradicted]</assumption>
  <evidence>[What was found that contradicts it]</evidence>
  <question>[Single focused question for the user]</question>
</escalation>

Loid cannot call AskUserQuestion directly — the orchestrator detects this block after Phase 3 and handles the user interaction before re-dispatching Loid. This rule is an extension of "Report blockers immediately".

Lawliet (Reviewer)¶

Model: Sonnet Color: Yellow

Purpose: Code quality assurance through static analysis.

Tools: | Tool | Usage | |------|-------| | Read | Read file contents | | Grep | Search file contents | | Glob | Find files by pattern | | Bash | Run static analysis tools | | graphify MCP (7 tools) | Structural graph queries (query_graph, get_node, get_neighbors, get_community, god_nodes, graph_stats, shortest_path) | | personal-kb MCP (7 tools) | Cross-project personal KB queries (same 7 operations) | | agentsview MCP (5 tools) | Prior-session history search (search_sessions, list_sessions, get_session_overview, get_messages, search_content) — cross-verify current handling against precedent |

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

Review Process:

First move — graph orientation. Run mcp__plugin_agent-flow_graphify__graph_stats then god_nodes(top_n=5) to orient before reading any file. For changes touching >1 file or >1 module this step is mandatory.
Read the changed files
Run static analysis tools:
Type checking: tsc --noEmit, mypy
Linting: eslint, ruff check
Security: npm audit, bandit
Check against requirements
Verify patterns are followed
Look for edge cases
Intent-fidelity check: Compare the patch against the stated intent.goal and intent.constraints from the orchestration state. If the patch passes all static checks but does not satisfy the stated goal or violates a constraint, flag intent-mismatch as a WARNING (→ NEEDS_CHANGES). This is independent of the complexipy cognitive-complexity check.

Output Format:

## Code Review

### Summary
[Brief summary]

### Issues Found
One line per issue: `<SEVERITY>: <file>:<line>: <issue>`
- **ERROR** (Critical): must fix
- **WARNING** (Major): must fix before approval — includes `intent-mismatch` (patch passes static analysis but misses stated Goal/Constraints)
- **INFO** (Minor): nice to fix — never triggers a fix round

### Security Concerns
- [Any security issues]

### Suggestions
- [Improvements]

### Verdict
[APPROVED | NEEDS_CHANGES]

Verdict Definitions: - APPROVED: Code meets quality standards and satisfies stated intent - NEEDS_CHANGES: Issues found, return to implementation (static failures or intent-mismatch). Any ERROR/WARNING with file:line blocks regardless of verdict, so Lawliet returns NEEDS_CHANGES whenever it lists one.

Note: BLOCKED is a Codex-only verdict (used when Codex finds a severity-blocker with a file:line citation during Phase 4 co-review) — Lawliet itself never emits BLOCKED. See the disagreement truth table in skills/verification-gates/references/codex-co-review.md.

Restrictions: - Static analysis only (no test execution) - No code modification - Bash limited to analysis tools

Codex co-reviewer (external, optional)¶

Codex is not an agent-flow persona — it is an external OpenAI CLI dispatched by the orchestrator during Phase 4 when available. It runs in parallel with Lawliet (without Lawliet's findings — its AGENTS.md rubric already excludes linter-level issues) and emits an independent verdict on the same diff; in review-fix rounds it reviews only the fix (--diff-base). See Using Codex Co-Review for setup and reconciliation rules.

Alphonse (Verifier)¶

Model: Sonnet Color: Red

Purpose: Comprehensive verification through test execution.

Tools: | Tool | Usage | |------|-------| | Bash | Run verification commands | | Read | Read file contents | | Grep | Search for patterns |

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

Verification Process:

Identify project type
Run appropriate test commands
Run type checking if applicable
Run linters if configured
Attempt build if applicable

Parallel review mode: in /orchestrate, Alphonse runs alongside Lawliet. Lawliet runs type checking and linting in that round, so Alphonse runs tests and build only and reports those two gates as COVERED (Lawliet); its Overall verdict rests on tests and build. Invoked on its own, Alphonse runs all four gates.

Verification Commands by Language (Alphonse's commands; the Stop hook only checks Node.js and Python):

Language	Tests	Types	Lint	Build
Node.js	`npm test`	`npx tsc --noEmit`	`npm run lint`	`npm run build`
Python	`pytest`	`mypy .`	`ruff check .`	`python -m build`
Go	`go test ./...`	`go build`	`golangci-lint run`	`go build`
Rust	`cargo test`	`cargo check`	`cargo clippy`	`cargo build`

Output Format:

## Verification Results

### Tests
- Status: [PASS | FAIL]
- Output: [Command output]

### Type Check
- Status: [PASS | FAIL | SKIPPED (<why>) | COVERED (Lawliet)]
- Errors: [List if any]

### Lint
- Status: [PASS | FAIL | SKIPPED (<why>) | COVERED (Lawliet)]
- Warnings: [Count]

### Build
- Status: [PASS | FAIL | SKIPPED (<why>)]
- Issues: [Details if any]

### Overall: [VERIFIED | FAILED | ENVIRONMENT_BLOCKED]

ENVIRONMENT_BLOCKED is emitted only when a gate fails solely due to an interpreter/dependency-version/environment mismatch the change did not introduce (exact error signature cited, e.g. requires-python >=3.10 vs the interpreter actually running). A repo-internal missing module is FAILED, not ENVIRONMENT_BLOCKED. See skills/verification-gates/references/failure-handling.md for the full triage rule.

Evidence Requirements: - Exact command output (not summaries) - Pass/fail counts with specifics - Full error messages for failures

Restrictions: - No code modification - Reports results only - Does not fix issues

Speedwagon (Authoring)¶

Model: Sonnet Color: Pink

Purpose: Transforming a topic-scope bundle (from Riko) and a curriculum plan (from Senku) into a module brief and an HTML fragment that the assembler combines into explain-out/index.html.

Tools:

Tool	Usage
Read	Read source files and verify file:line references
Grep	Search file contents
Glob	Find files by pattern
Write†	Write module briefs and HTML fragments (scoped)
Edit†	Modify briefs and fragments (scoped)
Bash‡	Run the assembler (scoped)

† Write/Edit scoped to explain-out/ and .claude/explain-briefs/ only. ‡ Bash scoped to bash ${CLAUDE_PLUGIN_ROOT}/scripts/compile-explain.sh [--revise <slug>] only — no other commands.

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

Authoring Process:

Read source files. For every file:line reference in Riko's scope bundle, use Read to load and verify the actual content. Note discrepancies rather than fabricating content.
Equip the design skill. Read skills/explainer-design-system/SKILL.md and relevant reference files before rendering any HTML.
Write the module brief. Output .claude/explain-briefs/<slug>.md following the brief shape in ${CLAUDE_PLUGIN_ROOT}/templates/explain/module-brief-example.md.
Write the HTML fragment. Output .claude/explain-briefs/<slug>.fragment.html by filling in ${CLAUDE_PLUGIN_ROOT}/templates/explain/module-fragment.html.tmpl. Replace all __PLACEHOLDER__ tokens with real content using only the primitives defined in the allowed vocabulary.
Invoke the assembler. Run bash ${CLAUDE_PLUGIN_ROOT}/scripts/compile-explain.sh and report the exit code and output path.

Output Format:

Brief path:      .claude/explain-briefs/<slug>.md
Fragment path:   .claude/explain-briefs/<slug>.fragment.html
Assembler exit:  0
Output:          explain-out/index.html

Restrictions / Scope: - Writes only to explain-out/ and .claude/explain-briefs/ - Bash limited to bash ${CLAUDE_PLUGIN_ROOT}/scripts/compile-explain.sh [--revise <slug>] - Does not modify application source, agent definitions, skills, commands, scripts, hooks, or config files - Does not call other agents (orchestrator manages routing) - Does not run tests, install packages, or operate the application

Tool Access Summary¶

Tool              Riko  Senku  Loid  Lawliet  Alphonse  Speedwagon
--------          ----  -----  ----  -------  --------  ----------
Read              Yes   Yes    Yes   Yes      Yes       Yes
Grep              Yes   Yes    Yes   Yes      Yes       Yes
Glob              Yes   Yes    Yes   Yes      -         Yes
Write             -     §      Yes   -        -         †
Edit              -     -      Yes   -        -         †
Bash              *     -      Yes   **       Yes       ‡
WebSearch         Yes   -      -     -        -         -
WebFetch          Yes   -      -     -        -         -
graphify MCP      Yes   Yes    -     Yes      -         -
personal-kb MCP   Yes   Yes    -     Yes      -         -
agentsview MCP    Yes   Yes    -     Yes      -         -

*  Riko: Bash only for AST analysis tools (plus writing its own report)
§  Senku: Write only for plan/report files under .claude/agent-reports/ or .senku/
** Lawliet: Bash only for static analysis tools
†  Speedwagon: Write/Edit scoped to explain-out/ and .claude/explain-briefs/
‡  Speedwagon: Bash scoped to bash ${CLAUDE_PLUGIN_ROOT}/scripts/compile-explain.sh [--revise <slug>]

Report Delivery¶

Long final messages get truncated when relayed back to the orchestrator. Every agent follows the same rule: if its report exceeds ~3000 characters, it writes the full report to .claude/agent-reports/<agent>-<slug>.md and its final message is only a ≤1500-character summary, its verdict, and that path. The orchestrator Reads the file before acting. .claude/agent-reports/ is gitignored (managed by ensure-gitignore.sh).

Workflow Participation¶

Phase	Primary Agent	Support
Exploration	Riko	-
Planning	Senku	Riko's findings
Implementation	Loid	Senku's plan
Review	Lawliet	Loid's changes
Verification	Alphonse	All changes
Authoring (/explain)	Speedwagon	Riko scope + Senku curriculum

Agent Specialization - Why specialization matters
Model Selection Guide - Opus vs Sonnet
Adding Agents - How to add new agents
Skills Reference - Skill system details

Agents Reference¶

Overview¶

Agent Specifications¶

Riko (Explorer)¶

Senku (Planner)¶

Deliverable Output Contract¶

Loid (Executor)¶

Lawliet (Reviewer)¶

Codex co-reviewer (external, optional)¶

Alphonse (Verifier)¶

Speedwagon (Authoring)¶

Tool Access Summary¶

Report Delivery¶

Workflow Participation¶

Related Documentation¶