Skip to content

System Architecture Overview

Agent Flow transforms Claude Code into a multi-agent orchestrated system with verification gates. This document explains how the components fit together and why the system is designed this way.

Design Philosophy

Agent Flow is built on three core principles:

  1. Specialization over generalization - Each agent has a focused role with specific tools
  2. Verification over trust - Every claim must be backed by evidence
  3. Cost awareness over convenience - Use expensive models only where they add value

High-Level Architecture

flowchart TB
    subgraph User["User Layer"]
        U[User]
    end

    subgraph Commands["Command Layer"]
        O["/orchestrate"]
        TO["/team-orchestrate<br/>(deprecated)"]
        D["/deep-dive"]
        EX["/explain"]
        AN["/analyze"]
    end

    subgraph Orchestration["Orchestration Layer"]
        ORC[Orchestrator]
    end

    subgraph Agents["Agent Layer"]
        subgraph Strategic["Strategic (Opus)"]
            S[Senku<br/>Planner]
        end
        subgraph Execution["Execution (Sonnet)"]
            R[Riko<br/>Explorer]
            L[Loid<br/>Executor]
            LW[Lawliet<br/>Reviewer]
            A[Alphonse<br/>Verifier]
            SW[Speedwagon<br/>Authoring]
        end
    end

    subgraph Skills["Skill Layer"]
        ES[exploration-strategy]
        TC[task-classification]
        PR[prompt-refinement]
        VG[verification-gates]
        ABC[agent-behavior-constraints]
        GU[graphify-usage]
        PKU[personal-kb-usage]
        AVU[agentsview-usage]
        EDW[evidence-driven-work]
        EDS[explainer-design-system]
        SAM[skill-agent-mapping]
    end

    subgraph MCP["MCP Server Layer"]
        GMCP[graphify MCP server]
        PKMCP[personal-kb MCP server<br/>user-registered]
        AVMCP[agentsview MCP server]
    end

    subgraph Hooks["Hook Layer"]
        H1[UserPromptSubmit]
        H2[PreToolUse]
        H3[PostToolUse]
        H4[SessionStart]
        H5[Stop]
        H6[SubagentStop]
        H7[SessionEnd]
    end

    subgraph State["State Layer"]
        OS[orchestration.local.md]
        DS[deep-dive.local.md]
    end

    U --> O & TO & D & EX & AN
    O & TO & D & EX & AN --> ORC
    ORC --> R & S & L & LW & A & SW
    SW -.-> EDS
    R -.-> ES
    R -.-> GU & PKU & AVU
    S -.-> TC & PR
    A -.-> VG
    R & S & L & LW & A -.-> ABC
    LW & A -.-> EDW
    H1 & H2 & H3 & H4 & H5 & H6 & H7 -.-> ORC
    ORC --> OS & DS
    R & S & LW --> GMCP
    R & S & LW --> PKMCP
    R & S & LW --> AVMCP

Component Overview

Command Layer

Commands are the entry points for multi-agent workflows:

Command Purpose Output
/orchestrate Execute complex tasks through the agent pipeline (Phases 1–3 in order, review + verification in parallel; Phases 3–5 run as the implement-review-verify workflow) Modified files, verified
/team-orchestrate Deprecated — points users to /orchestrate (Agent Teams tools were removed from Claude Code) Modified files, verified
/deep-dive Gather comprehensive codebase context .claude/deep-dive.local.md
/explain Author an interactive HTML explainer for a topic (Riko, Senku, Speedwagon) explain-out/index.html
/analyze Load session transcripts into SQLite and report on subagent behavior .claude/observability/report.md

Orchestration Layer

The orchestrator is the main Claude instance. It picks an execution profile (fast, standard or thorough) from task tier and risk. Phases 1–2 run sequentially, Phases 3–5 run as the implement-review-verify workflow (with a manual fallback), and Phase 6 is the report. It: - Receives user requests - Delegates to specialist agents - Passes context between phases - Enforces verification gates - Reports completion status

The orchestrator never implements code directly - it coordinates specialists.

Agent Layer

Six specialized agents: five run in the /orchestrate pipeline, and Speedwagon authors /explain modules.

Agent Model Role Key Tools
Riko Sonnet Codebase exploration Read, Grep, Glob, Bash*, WebSearch, WebFetch, graph + session-history MCP tools†
Senku Opus Implementation planning Read, Grep, Glob, Write (plan/report files only), graph + session-history MCP tools†
Loid Sonnet Code implementation Read, Write, Edit, Grep, Glob, Bash
Lawliet Sonnet Code review Read, Grep, Glob, Bash, graph + session-history MCP tools†
Alphonse Sonnet Verification Bash, Read, Grep
Speedwagon Sonnet Interactive explainer authoring for /explain Read, Grep, Glob, Write, Edit, Bash (scoped to explainer output)
  • Riko's Bash access is limited to AST analysis tools only (ast-grep, tree-sitter, language parsers), plus writing its own report to .claude/agent-reports/

† Read-only MCP tools: the project graphify graph, the personal-kb graph, and agentsview session search (see tools: in each agents/*.md)

Report delivery: long subagent reports get truncated when relayed to the orchestrator. Any agent whose report exceeds ~3000 characters writes it to .claude/agent-reports/<agent>-<slug>.md and returns only a ≤1500-character summary, its verdict, and the path.

See Agent Reference for detailed specifications.

Skill Layer

Skills are domain expertise modules that provide behavioral patterns:

Skill Owner Purpose
exploration-strategy Riko Codebase exploration patterns
task-classification Senku Task routing decisions
prompt-refinement Senku Ambiguous request handling
verification-gates Alphonse Quality validation patterns
agent-behavior-constraints System Universal behavioral rules
graphify-usage Riko Knowledge graph query patterns and tool decision table
personal-kb-usage Riko Cross-project personal knowledge base queries
agentsview-usage Riko Prior session-history search patterns
evidence-driven-work System Perception, evidence, argument and reporting practices
explainer-design-system Vendored (upstream: zarazhangrui) Interactive HTML explainer design system for /explain
skill-agent-mapping System Registry of skill ownership and consumption relationships

See Skills Reference for detailed specifications.

Hook Layer

Hooks provide lifecycle automation:

Hook Trigger Purpose
UserPromptSubmit User sends message Deterministic prompt-refinement nudge (command hook, never blocks)
PreToolUse Before tool execution File-path validation (deny via permissionDecision), dispatch logging
PostToolUse After tool execution Observability event logging
SubagentStop Subagent finishes Observability event logging
SessionEnd Session ends Observability session close
SessionStart Session begins Project context detection
Stop Task completion Verification gates (skipped when no uncommitted non-doc changes)

The former TeammateIdle / TaskCompleted hooks were removed — they read fields absent from current hook input and never took effect.

See Hooks Reference for detailed specifications.

State Layer

State files track workflow progress:

File Scope Content
orchestration.local.md Session Phase, iteration, gate results, task_complexity tier, structured intent (goal/description/actions/constraints/assumptions)
deep-dive.local.md Session Codebase context, patterns
research-*.local.md Durable Report-only route output

The state file also holds report_requested, codex_divergence_rounds, max_iterations, per-phase gates, and the graph / personal_kb / codex / agentsview context blocks.

task_complexity holds the task-routing tier (trivial/exploratory/implementation/complex/research) set during Phase 0 Prompt Refinement. It is distinct from complexipy's code cognitive-complexity metric used by Lawliet in Phase 4. The intent object is seeded at init and populated at Phase 0; it is passed verbatim to all downstream agents — no re-summarization.

See State Files Reference for format specifications.

Information Flow

Orchestration Flow

User Request
    |
    v
[Prompt Refinement + classify] -- ask once if vague; pick execution profile
    |
    v
[Riko: Exploration] -- skipped under fast (and for trivial tasks under standard)
    |
    v
[Senku: Planning] -- same skip rule; complex tasks pause once for plan confirmation
    |
    v
[Workflow: implement-review-verify]
    |   [Loid: Implementation]
    |        |
    |        v
    |   [Parallel: Lawliet | Codex (optional) | Alphonse]
    |        |
    |        v
    |   blocking findings? -> one batched Loid fix -> re-review fix diff (capped rounds)
    |
    v
[Phase 6: report + Intent Ledger] -- completion promise only if no findings remain open

Research and exploratory tasks take a report-only route: after Phase 1 (and Phase 2 unless plain exploratory) the orchestrator writes a report, skipping Phases 3–5. /team-orchestrate is deprecated and routes to /orchestrate.

Deep-Dive Flow

User Request
    |
    v
[Parallel Riko Agents] -- 8 concurrent explorations
    |                      - Structure
    |                      - Conventions
    |                      - Anti-patterns
    |                      - Build/CI
    |                      - Architecture
    |                      - Testing
    |                      - Purpose & Use Cases
    |                      - Key Flows
    v
[Senku: Synthesis] -- Merge findings
    |
    v
deep-dive.local.md -- Reusable context

Model Selection Strategy

Agent Flow optimizes costs by matching model capabilities to task requirements:

flowchart LR
    subgraph Opus["Opus (Higher Cost)"]
        direction TB
        O1[Deep Reasoning]
        O2[Complex Analysis]
        O3[Strategic Planning]
    end

    subgraph Sonnet["Sonnet (Lower Cost)"]
        direction TB
        S1[Fast Execution]
        S2[Clear Criteria]
        S3[Repetitive Tasks]
    end

    O1 --> SK[Senku]
    O2 --> SK
    O3 --> SK

    S1 --> R[Riko]
    S1 --> L[Loid]
    S2 --> A[Alphonse]
    S3 --> LW[Lawliet]

Use Opus when: - Designing complex architectures - Making strategic decisions - Analyzing ambiguous requirements

Use Sonnet when: - Exploring and searching the codebase (Riko, effort: medium) - Implementing well-defined plans - Running verification commands - Performing code review - Executing repetitive operations

Tool Access Control

Agents have restricted tool access based on their roles:

Riko (Explorer):     [Read] [Grep] [Glob] [Bash]* [WebSearch] [WebFetch]
Senku (Planner):     [Read] [Grep] [Glob] [Write]§
Loid (Executor):     [Read] [Write] [Edit] [Bash] [Grep] [Glob]
Lawliet (Reviewer):  [Read] [Grep] [Glob] [Bash]
Alphonse (Verifier): [Read] [Bash] [Grep]
Speedwagon (Author): [Read] [Grep] [Glob] [Write]† [Edit]† [Bash]‡

Key restrictions: - Only Loid can modify source files (Write, Edit); Senku and Speedwagon have scoped Write - Only Riko can access the web (WebSearch, WebFetch) - Senku writes plans as numbered markdown checklists (TodoWrite no longer exists on current models)

§ Senku's Write is restricted 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 to compile-explain.sh

Riko, Senku and Lawliet also get the graphify, personal-kb and AgentsView MCP tools (read-only). * Riko's Bash access is limited to AST analysis tools only (ast-grep, tree-sitter, language parsers)

This ensures separation of concerns and prevents agents from exceeding their responsibilities.

Verification Architecture

Verification is layered throughout the system:

┌─────────────────────────────────────────────────────────┐
│                    Verification Layers                   │
├─────────────────────────────────────────────────────────┤
│ Layer 1: Agent Self-Check                               │
│   - Loid runs targeted checks on changed code           │
│   - Lawliet runs type check, lint, patterns in review   │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Dedicated Verifier                             │
│   - Alphonse runs full test suite                       │
│   - Alphonse verifies build (types/lint: Lawliet)       │
├─────────────────────────────────────────────────────────┤
│ Layer 3: Hook Enforcement                               │
│   - Stop hook runs tests and type checks (skipped when │
│     only docs/.claude changed; cached by fingerprint)   │
│   - PreToolUse denies unsafe file writes                │
├─────────────────────────────────────────────────────────┤
│ Layer 4: Orchestrator Gates                             │
│   - Must see actual command output                      │
│   - Must confirm zero errors                            │
│   - Must see all required checks pass                   │
└─────────────────────────────────────────────────────────┘

Codex Co-Review

Under standard/thorough, when Codex is installed, an external read-only reviewer runs in parallel with Lawliet and Alphonse. Its verdict is reconciled with Lawliet's by a truth table: only file:line-cited ERROR/WARNING findings count. See Using Codex Co-Review.

Observability Layer

The observability layer provides visibility into what agents actually do across sessions without altering the orchestration control flow.

It follows a three-tier model:

  1. Tier A — Offline transcript parser: bash scripts/analyze.sh load reads stored Claude Code JSONL transcripts and writes structured rows into SQLite. Works without any hooks installed.
  2. Tier B — Live hook sink: Four hooks (PreToolUse:Agent|Task, matcherless PostToolUse, SubagentStop, SessionEnd) capture events in real time and append them to the same SQLite store. Hook execution is non-blocking; a JSONL fallback is used if the database is locked.
  3. Tier C — External exporters: bash scripts/analyze.sh export pushes data from SQLite to configurable sinks (JSONL by default; MLflow opt-in). This tier is entirely opt-in.
flowchart LR
    T[JSONL transcripts] --> L[analyze load]
    H[Live hooks\nPreToolUse · PostToolUse\nSubagentStop · SessionEnd] --> DB

    L --> DB[(events.db\nSQLite WAL)]

    DB --> R[report.md]
    DB --> CSV[labels-export.csv]
    DB --> E[Exporters\nJSONL / MLflow]

The observability layer is passive: it reads hook event data and transcript files but never modifies them, and it has no influence over agent decisions or orchestration gates.

See Using Analyze for usage and Observability Schema for the database schema.

Extension Points

Agent Flow is designed to be extensible:

Extension Type Location Process
New Agent agents/*.md Define role, model, tools, skills
New Skill skills/*/SKILL.md Define domain expertise, references
New Command commands/*.md Define workflow, state management
New Hook hooks/hooks.json Define trigger, matcher, action

See the extension guides: - Adding Agents - Adding Skills