Skip to content

Agent Flow Documentation

Transform Claude Code into a multi-agent orchestrated system with verification gates.

Overview

Agent Flow is a Claude Code plugin that coordinates multiple specialized agents to complete complex development tasks. Instead of a single agent attempting everything, Agent Flow delegates to experts who work together through a verified pipeline.

flowchart LR
    subgraph Input
        U[User Request]
    end

    subgraph Agents["Specialized Agents"]
        R[Riko<br/>Explorer]
        S[Senku<br/>Planner]
        L[Loid<br/>Executor]
        LW[Lawliet<br/>Reviewer]
        A[Alphonse<br/>Verifier]
        SW[Speedwagon<br/>Authoring]
    end

    subgraph Output
        V[Verified<br/>Code]
        E[explain-out/<br/>index.html]
    end

    U --> R --> S --> L --> LW & A --> V
    S -.->|/explain| SW --> E

Riko and Senku are skipped under the fast profile; Lawliet, Alphonse (and Codex) run in parallel.

Key Features

Feature Description
Specialized Agents Six agents with distinct roles and tool access
Execution Profiles The orchestrator picks fast, standard or thorough from task tier and risk (no flags); round caps 1 / 2 / 3
Verification Gates Mandatory testing, linting, and type checking
Cost-Aware Models Opus for planning, Sonnet for execution
Hook Automation Lifecycle events trigger validation
Skill System Domain expertise modules guide behavior
Graphify Integration Shared knowledge graph lets subagents query codebase structure via MCP
Personal KB Integration Cross-project personal knowledge base lets agents recall prior decisions and patterns
AgentsView Integration Riko/Senku/Lawliet search prior session history to leverage proven approaches and cross-verify current handling; degrades gracefully with AGENT_FLOW_NO_AGENTSVIEW=1 opt-out
Codex Co-Review (optional) Cross-vendor second-opinion review in Phase 4 — OpenAI Codex CLI runs alongside Lawliet when installed; availability-gated with AGENT_FLOW_NO_CODEX=1 opt-out
Observability Session analysis, tool-usage reports, and pluggable exporters via /agent-flow:analyze

Getting Started

Core Concepts

Guides

Reference

Architecture

The Problem We Solve

LLMs can confidently claim task completion without actual verification. They generate responses based on patterns, not memories of actions taken. An agent might report "all tests pass" without ever running tests.

Agent Flow solves this by:

  1. Separating implementation from verification - Different agents handle different concerns
  2. Requiring evidence, not claims - Actual command output must be provided
  3. Automating quality gates - Hooks enforce verification before completion
  4. Tracking state - Progress is recorded in a state file

The Agents

Agent Model Role Key Capability
Riko Sonnet Explorer Finds files, understands patterns
Senku Opus Planner Creates implementation strategies
Loid Sonnet Executor Writes and modifies code
Lawliet Sonnet Reviewer Checks code quality
Alphonse Sonnet Verifier Runs tests and validation
Speedwagon Sonnet Authoring Authors interactive HTML explainer modules

Each agent has restricted tool access matching their role. Only Loid can modify files in the application source. Only Alphonse runs comprehensive tests. Senku writes only plan/report files, and Speedwagon writes only to explain-out/ and .claude/explain-briefs/.

Example Workflow

User: /orchestrate Add user authentication with JWT tokens

[Riko explores the codebase]
Found: src/auth/, src/middleware/, src/routes/

[Senku creates a plan]
Plan: 1. Add JWT config, 2. Create auth middleware, 3. Add routes...

[Loid implements the plan]
Modified: src/auth/jwt.ts, src/middleware/auth.ts, src/routes/auth.ts

[Lawliet and Alphonse run in parallel]
Lawliet: APPROVED (types clean, lint clean, patterns followed)
Alphonse: Tests: 47/47 passed | Build: success | Types/Lint: COVERED (Lawliet)

<orchestration-complete>TASK VERIFIED</orchestration-complete>

The orchestrator picks an execution profile from the task's tier and risk; there are no flags. fast (trivial, or a localized 1–2 file change) skips Riko, Senku and Codex; standard skips Riko and Senku only for trivial tasks; thorough (complex, or anything touching auth, security, payments, migrations, concurrency or a public API) runs everything. Review-fix rounds are capped at 1 / 2 / 3.

Getting Started

1. Install

/plugin marketplace add josix/agent-flow
/plugin install agent-flow@josix-plugins

Or clone it (git clone https://github.com/josix/agent-flow.git ~/agent-flow) and launch with claude --plugin-dir ~/agent-flow.

2. Use

/orchestrate Add input validation to the user form

For detailed instructions, see Installation and Quick Start.

Design Principles

Never Trust, Always Verify

Every claim from an agent must be backed by actual evidence. "Tests pass" is not acceptable - show the test output.

Specialized Over General

Six specialized agents (five in the /orchestrate pipeline, plus Speedwagon for /explain) outperform one general agent. Each knows their role and stays within boundaries.

Cost-Aware Model Selection

Opus for strategic planning (Senku). Sonnet for exploration, implementation, review, and verification.

Automated Quality Gates

Hooks enforce verification at lifecycle events. You can't claim completion without passing gates.

Contributing

Agent Flow is extensible. You can:

  • Add agents for new specialized roles
  • Add skills for domain expertise
  • Add hooks for lifecycle automation
  • Add commands for new workflows

See the extension guides for details.

Support

  • Documentation: You're reading it
  • Issues: GitHub Issues
  • Source: GitHub Repository

Version: 1.13.2 License: MIT