Commands Reference

Complete reference for Agent Flow commands, including arguments, workflows, and integration patterns.

Overview

Agent Flow provides five primary commands for multi-agent workflows:

Command	Purpose	Primary Use Case
/orchestrate	Execute complex tasks through agent pipeline	Feature implementation, refactoring
/team-orchestrate	Deprecated — points to /orchestrate	— (use /orchestrate)
/deep-dive	Gather comprehensive codebase context	New project onboarding, exploration
/agent-flow:analyze	Surface subagent behaviour and improvement opportunities	Observability, retrospective analysis
/agent-flow:explain	Generate an interactive HTML explainer for any topic	Teaching a codebase concept to a new team member

/orchestrate

Coordinate complex multi-step tasks through the agent system.

Syntax

/orchestrate [--use-deep-dive] <task description>

Arguments

Argument	Required	Description
<task description>	Yes	What you want to accomplish
--use-deep-dive	No	Use existing deep-dive context

Examples

# Basic orchestration
/orchestrate Add user authentication with JWT tokens

# Using existing deep-dive context
/orchestrate --use-deep-dive Add user profile page

# Complex refactoring
/orchestrate Refactor the database layer to use connection pooling

Workflow Phases

sequenceDiagram
    participant U as User
    participant O as Orchestrator
    participant R as Riko
    participant S as Senku
    participant W as implement-review-verify workflow
    participant L as Loid
    participant LW as Lawliet + Codex
    participant A as Alphonse

    U->>O: /orchestrate task
    Note over O: Phase 0: ticket intake, prompt refinement,<br/>tier + execution profile
    opt standard / thorough profile
        O->>R: Phase 1: gather context
        R-->>O: findings (or .claude/agent-reports path)
        O->>S: Phase 2: plan from Riko's report
        S-->>O: checklist plan
    end
    O->>W: Phases 3–5 (intent, plan, profile, codex)
    Note over W: snapshot untracked files (when Codex is available)
    loop until gates pass or round cap (1/2/3)
        W->>L: implement / fix all blocking findings
        L-->>W: per-item status + targeted checks
        par parallel review & verification
            W->>LW: review (fix diff only after round 1)
        and
            W->>A: tests + build (type/lint COVERED by Lawliet)
        end
    end
    W-->>O: complete | capped | escalation | divergence | blocked
    Note over O: Phase 6: report, open findings, Intent Ledger
    O->>U: result

• Ticket intake — an issue key (ABC-123) or Jira/GitHub-issue URL in the task is fetched first and seeds the intent's Goal, Constraints, and acceptance criteria.
• Execution profile — chosen by the orchestrator, never by a flag. fast (trivial, or a localized 1–2 file change) skips Riko, Senku, and Codex and allows one fix round; standard skips Riko/Senku only for trivial tasks and allows two; thorough (complex tier, or any auth/security/payments/migration/concurrency/public-API surface) runs everything and allows three. A run only escalates to a higher profile mid-way, never downgrades. On the workflow path the upgrade applies at the next launch. Research/exploratory tiers (or an explicit report request) take a report-only route instead: Riko, plus Senku unless plain exploratory, then the Research Short-Circuit — no Phases 3–5 and no Post-Plan Confirmation.
• Phases 3–5 as a workflow — when the Workflow tool is available the orchestrator launches /agent-flow:implement-review-verify (workflows/implement-review-verify.js). The script holds the round cap (plus one extra round when ERRORs dropped since the previous review in the same launch), batches all blocking findings into one Loid fix, scopes re-review to the fix diff, reconciles Lawliet/Codex per the truth table in skills/verification-gates/references/codex-co-review.md, and returns early for anything needing the user. Without workflows the orchestrator runs the same rules turn by turn.
• Review-fix rounds — only ERROR/WARNING findings with file:line trigger a round; INFO goes to the report. A Lawliet APPROVED that lists a cited ERROR/WARNING still triggers a round. Codex blocks only with a cited ERROR/WARNING. At the cap, remaining findings are listed under "Open findings"; the orchestrator pauses only for one it judges unsafe to ship.

Delegation Decision Matrix

The orchestrator must route tool calls to persona owners:

Tool(s)	Owner	Exception
Read, Grep, Glob	Riko	single-line config read
Write, Edit	Loid	orchestration.local.md state updates; .claude/research-*.local.md via compile-research-report.sh
Bash (tests, build)	Alphonse	—
Bash (static analysis: type check, lint)	Lawliet	—
Plan tracking (numbered markdown checklist)	Senku	plans persist in the state file / .claude/agent-reports/ (no todo tool)
Agent dispatch	Orchestrator	—
mcp__plugin_agent-flow_graphify__*	Riko / Senku / Lawliet	orchestrator may peek for routing decisions
mcp__plugin_agent-flow_agentsview__*	Riko / Senku / Lawliet	orchestrator may peek for routing decisions
mcp__personal-kb__*	Riko / Senku / Lawliet	orchestrator may peek for routing decisions

Dispatch protocol: agents are dispatched as Agent(subagent_type="agent-flow:<Name>", ...) and run in the background. The orchestrator waits for each agent's completion notification before updating state or advancing — never on the launch acknowledgement, and without polling.

Report delivery: every dispatch prompt ends with the report-length rule — if a report exceeds ~3000 characters, the agent writes it to .claude/agent-reports/<agent>-<slug>.md and returns only a ≤1500-character summary, its verdict, and the path. The orchestrator Reads that file before acting (long relayed reports were observed to be truncated). Loid must finish every plan item and emit a per-item [done|skipped] status line.

Cache-read heuristic: if a non-Bash tool call would read >200 lines or repeats a file already read in this phase, dispatch instead of inlining.

Dispatch Recovery: If a dispatched agent returns a transport/API error or a completely empty reply (a "crash"), the orchestrator auto-retries the same dispatch once, silently. Idempotent read-only agents (Riko, Lawliet, Alphonse) are always safe to retry; Loid (mutating) is retried only after confirming no partial write landed, otherwise the failure is surfaced to the user. See commands/orchestrate.md's Dispatch Recovery subsection for the full crash discriminator.

See the command files themselves for full matrix and anti-pattern examples.

Phase Details

Phase 0: Prompt Refinement

Before beginning orchestration, the system ensures the task is well-defined:

1. Check clarity: Does the request specify what, where, and why?
2. If vague: Ask ONE clarifying question with options
3. If clear: Transform to structured format and capture:
4. Goal: One-sentence outcome
5. Description: What and why (2-3 sentences)
6. Actions: Concrete steps
7. Constraints: What must not be broken or changed
8. Assumptions: What is taken for granted
9. Classify task_complexity tier (trivial/exploratory/implementation/complex/research)
10. Persist the full intent to state via --set-intent-* / --set-task-complexity flags

Phase 1: Exploration

Agent: Riko (Explorer) Purpose: Gather codebase context

Standard flow: - Find relevant files and patterns - Understand existing architecture - Identify key areas to modify

With --use-deep-dive: - Read existing deep-dive context - Perform targeted exploration only - Skip redundant architecture discovery

Phase 2: Planning

Agent: Senku (Planner) Purpose: Create implementation strategy

Output: - Files to modify - Step-by-step implementation plan - Risks and edge cases - Verification criteria - Deliverable Output Contract (target format / acceptance criteria / risk & edge cases) — required for any plan producing an artifact - <plan-interpretation> block at the end of the plan (always emitted)

Note: Senku runs on Opus with effort: high and returns its plan as a numbered markdown checklist (long plans are written to .claude/agent-reports/senku-<slug>.md).

Assumption Escalation Gate (after Phase 2): The orchestrator scans Senku's reply for <escalation type="assumption-contradicted">. If present, the orchestrator calls AskUserQuestion and re-dispatches Senku. This gate runs before advancing state to Phase 3. Silent on happy path.

Post-Plan Confirmation Gate (between Phase 2 and 3, complex tasks only): For task_complexity == "complex" (case-insensitive), the orchestrator replays Senku's <plan-interpretation> together with the captured intent and prompts the user once to confirm or correct. If the task is not complex, this gate is skipped with an info: log entry. Skipped on the report-only route (the Research Short-Circuit runs first).

Research Short-Circuit

The short-circuit runs before Post-Plan Confirmation: right after Phase 1 when Senku is skipped, otherwise after the Phase 2 Assumption Escalation Gate.

Trigger: task_complexity is research or exploratory, OR report_requested=true in orchestration state (set during Phase 0 Prompt Refinement when the user explicitly requested a written report, investigation guide, or planning document).

What happens: Phases 3–5 (Implementation/Review/Verification) are skipped. The orchestrator runs init-research-report.sh and compile-research-report.sh directly (script-mediated write — see Delegation Decision Matrix), populating the report with findings from Riko (Phase 1) and, when it ran, Senku (Phase 2).

Artifact path: .claude/research-<slug>-<stamp>.local.md — gitignored via .claude/*.local.*, durable across sessions.

Completion tag variant:

<research-report-complete>REPORT WRITTEN: .claude/research-<slug>-<stamp>.local.md</research-report-complete>

This replaces the <orchestration-complete> promise for research/exploratory paths. The Intent Ledger is printed just before this tag.

See State Files Reference for the full frontmatter schema and body sections.

Plan-approved continuation: if the user approves implementing a finished research/plan-only run ("ok", "go ahead"), the orchestrator does not edit code in the main thread — it re-activates the state file and re-enters the pipeline at Phase 3 (Loid with the approved plan), then runs Phases 4–6 as normal.

Phase 3: Implementation

Agent: Loid (Executor) Purpose: Write code changes

Process: - Follow Senku's plan precisely - Make changes incrementally - Run targeted checks on changed code (Alphonse runs the full suite) - Report any blockers immediately

Assumption Escalation Gate (after Phase 3): The orchestrator scans Loid's reply for <escalation type="assumption-contradicted">. If present, the orchestrator calls AskUserQuestion and re-dispatches Loid. This gate runs before advancing state to Phase 4. Silent on happy path.

Phase 4: Review

Agent: Lawliet (Reviewer) Purpose: Check code quality

Checks: - Code correctness - Security issues (via static analysis) - Pattern adherence - Potential bugs - Intent fidelity: Flags intent-mismatch (Major → NEEDS_CHANGES) when a patch passes static analysis but does not satisfy the stated Goal/Constraints. This is separate from the complexipy cognitive-complexity check.

Outcomes: - APPROVED: Proceed to verification - NEEDS_CHANGES: Return to implementation (includes intent-mismatch findings)

Codex co-review (optional): When codex.available is true in orchestration state, the OpenAI Codex CLI runs as a co-reviewer alongside Lawliet via scripts/dispatch-codex-review.sh. If the Codex run fails, the review degrades to ADVISORY (Lawliet-only) with codex_skip_reason set to timeout or error. The final verdict follows the disagreement truth table in skills/verification-gates/references/codex-co-review.md (loaded by /orchestrate Phase 4); set AGENT_FLOW_NO_CODEX=1 to disable for a run. See Using Codex Co-Review for details.

Divergence Cap: When Lawliet keeps approving with no cited ERROR/WARNING of its own but Codex keeps citing the same set of ERROR/WARNING file:lines while verification is clean (a "divergence round"; a Lawliet APPROVED that lists its own cited ERROR/WARNING blocks on its own and is not a divergence round), the orchestrator tracks a codex_divergence_rounds counter in state. After 2 consecutive same-citation divergence rounds, the orchestrator stops re-dispatching Loid and instead calls AskUserQuestion (Accept Codex / Accept Lawliet / provide guidance; defaults to Lawliet if unanswered). In the workflow path the cap is enforced in code and the divergence result carries open_findings + rounds_used, so an Accept-Codex relaunch still counts against the round cap; a standoff that repeats at the cap itself is reported as capped. See skills/verification-gates/references/codex-co-review.md for the full mechanics and State Files Reference for the codex_divergence_rounds field.

Phase 5: Verification

Agent: Alphonse (Verifier) Purpose: Run all verification gates

Required checks: Alphonse runs in parallel with Lawliet (and Codex, when the profile includes it), because none of them writes code. Lawliet runs type check and lint; Alphonse runs tests and build and reports type/lint as COVERED (Lawliet). Run on its own, Alphonse runs all four gates.

Outcomes (three-way, per Alphonse's Overall verdict): - VERIFIED (all gates PASS): Proceed to completion - FAILED (a real code defect): Return to implementation - ENVIRONMENT_BLOCKED (gate failed solely due to an interpreter/dependency-version/environment mismatch the change did not introduce): warn-and-proceed — NOT routed to Loid; the blocker is recorded with its caveat in the Phase 6 Intent Ledger. See skills/verification-gates/references/failure-handling.md for the environment-blocked triage rule.

Phase 6: Completion

Once every gate passes (or the only open gate is ENVIRONMENT_BLOCKED), the orchestrator writes an inline summary following the evidence-driven-work reporting shape (skills/evidence-driven-work/references/expression.md): outcome first, naming any caveat such as an ENVIRONMENT_BLOCKED gate, then background, what changed, impact and purpose, evidence with exact identifiers, and what was not done. The Intent Ledger and completion promise follow:

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

Intent Ledger (printed before the completion promise):

## Intent Ledger

**Captured intent** (from state file):
- Goal: <intent.goal>
- Constraints: <intent.constraints or "none recorded">
- Key assumptions: <intent.assumptions or "none recorded">
- Task complexity: <task_complexity>

**Gap-handlers that fired this run:**
- Intent clarification (Gap 1): <"asked: <q>" | "not needed — task was clear">
- Interpretation/rationale confirm (Gaps 2/3): <"shown & confirmed" | "shown & corrected: <what>" | "skipped — task_complexity != complex">
- Lossless context pass-through (Gap 4): <"intent passed verbatim across phases" — always on>
- Behavioral guardrails (Gap 5): <"no plan deviations" | "deviations flagged: <what>">
- Assumption escalations (Gap 7): <"none" | one line per escalation: assumption → resolution>
- Intent-fidelity review (Gap 6): <"PASS" | "intent-mismatch flagged: <what>, resolved in iteration N">
- Environment gates (P1-2): <"none" | "environment-blocked: <what>, proceeded with caveat">

State Tracking

Progress lives in .claude/orchestration.local.md; see State Files for the schema.

Iteration Handling

Every blocking finding (ERROR/WARNING with file:line) from Lawliet, Codex and Alphonse goes to Loid in one batch. Re-review covers only the fix diff, and Alphonse re-runs. Rounds are capped at 1 / 2 / 3 by profile. At the cap, one extra round is allowed if the last round reduced the open ERRORs; otherwise the run stops with status capped and lists the remaining findings under "Open findings" without the completion promise. The state file's max_iterations (default 10) is recorded only; nothing enforces it.

---

/team-orchestrate

Deprecated

/team-orchestrate is deprecated. The Agent Teams tools it relied on (TeamCreate, TeamDelete, TaskCreate, TaskUpdate) were removed from Claude Code — every session now has one implicit team — and /orchestrate already runs agents in the background. Use /orchestrate instead.

---

/deep-dive

Gather comprehensive codebase context using parallel exploration agents.

Syntax

/deep-dive [--full | --focus=<path> | --refresh]

Arguments

Argument	Default	Description
--full	Yes	Full codebase exploration
--focus=<path>	No	Focus on specific directory
--refresh	No	Refresh existing context

Examples

# Full codebase exploration
/deep-dive

# Focus on specific area
/deep-dive --focus=src/auth

# Refresh existing context
/deep-dive --refresh

Workflow

flowchart TB
    subgraph Phase1["Phase 1: Parallel Exploration"]
        R1[Riko: Structure]
        R2[Riko: Conventions]
        R3[Riko: Anti-patterns]
        R4[Riko: Build/CI]
        R5[Riko: Architecture]
        R6[Riko: Testing]
        R7[Riko: Purpose & Use Cases]
        R8[Riko: Key Flows]
    end

    subgraph Phase2["Phase 2: Synthesis"]
        S[Senku: Merge Findings]
    end

    subgraph Phase3["Phase 3: Output"]
        O[deep-dive.local.md]
    end

    R1 & R2 & R3 & R4 & R5 & R6 & R7 & R8 --> S
    S --> O

Exploration Aspects

Each Riko agent explores a different aspect:

Aspect	Focus Areas
Structure	Directory layout, entry points, monorepo detection
Conventions	Config files, naming patterns, style guides
Anti-patterns	DO NOT patterns, deprecated code, warnings
Build/CI	Package scripts, CI configs, test framework
Architecture	Core modules, dependencies, data flow
Testing	Test directories, patterns, utilities
Purpose & Use Cases	What it is, problems solved, adoption modes, design rationale
Key Flows	Numbered file:line hops per traced flow, plus failure notes

Each aspect prompt carries a per-task Graph hint: that tells Riko when to prefer graphify MCP tools over Grep.

Each explorer writes reports over ~3000 characters to .claude/agent-reports/riko-<aspect>.md and returns a short summary plus the path. The orchestrator waits for every explorer's completion notification; if one goes idle without a report, that single aspect is re-dispatched once with a narrower prompt before synthesis proceeds.

Dynamic Scaling

Additional agents spawn based on project size:

Factor	Threshold	Additional Agents
Total files	>100	+1 per 100 files
Directory depth	>= 4	+2 for deep exploration
Monorepo	detected	+1 per package
Multiple languages	>1	+1 per language

Output Format

The deep-dive creates .claude/deep-dive.local.md:

---
generated: 2024-01-15T10:00:00Z
scope: full
focus_path: null
phase: complete
---

# Deep-Dive Context

## Repository Overview
- Tech stack: TypeScript, React, Node.js
- Entry points: src/index.ts, src/server.ts
- Key patterns: Repository pattern, Dependency injection

## Purpose & Use Cases
(optional; present when synthesized) What it is, problems solved, use cases/adoption modes.

## Architecture Map
| Component | Location | Purpose |
|-----------|----------|---------|
| API Layer | src/api/ | REST endpoints |
| Services | src/services/ | Business logic |
| Models | src/models/ | Data structures |

## Key Flows
(optional; present when synthesized) Numbered `file:line` hops per traced flow.

## Conventions
- Naming: camelCase for functions, PascalCase for classes
- Testing: Jest with __tests__ directories
- Error handling: Custom AppError class

## Anti-Patterns (DO NOT)
- Do not use `any` type
- Do not import from `src/internal/`
- Do not modify global state

## Gotchas & Failure Modes
(optional; present when synthesized) Fragile spots and known failure modes.

## Key Files Quick Reference
| Task | Look Here |
|------|-----------|
| Add API endpoint | src/api/routes/ |
| Add database model | src/models/ |
| Add service | src/services/ |

## Agent Notes
- Authentication uses JWT with refresh tokens
- Database uses Prisma ORM
- Tests require running database

Integration with /orchestrate

After deep-dive completes:

/orchestrate --use-deep-dive Add user authentication

This injects deep-dive context into Phase 1, allowing targeted exploration instead of full discovery.

---

/agent-flow:analyze

Parse Claude Code session transcripts and live hook events to surface subagent behaviour, tool usage, token costs, and improvement opportunities.

Syntax

/agent-flow:analyze

Or via CLI:

bash <plugin-root>/scripts/analyze.sh <subcommand> [options]   # run from your project root

Arguments

The slash command takes these arguments and maps them onto analyze.sh subcommands (load, report, sessions, sql):

• --all-sessions (default for the first run): load every session from the auto-detected transcripts directory
• --session <id>: load one session UUID
• --report: generate the Markdown report (default after loading)
• --sessions: list loaded sessions with event counts
• --sql <query>: run ad-hoc SQL against the events database
• --transcripts-dir <path>: override the transcripts directory
• --db <path>: override the database path (default .claude/observability/events.db)
• --redact: mask credential patterns (AWS keys, OpenAI keys, GitHub PATs) before storing

Subcommands

Subcommand	Purpose
load	Parse transcripts and write events to the SQLite store
report	Generate a Markdown report from the loaded data
sessions	List all sessions in the database
sql <query>	Run an ad-hoc SQL query against the store
retention	Prune old sessions (--days N or --all)
label <session_id>	Interactive recall labeling
label export	Export labels to CSV
export	Export events to an external sink

Examples

# Slash command — load current session and report
/agent-flow:analyze

# Load all sessions and report
bash scripts/analyze.sh load --all-sessions && bash scripts/analyze.sh report

# Single-session report
bash scripts/analyze.sh report --session <session_id>

# Ad-hoc query
bash scripts/analyze.sh sql "SELECT agent_type, COUNT(*) n FROM events GROUP BY agent_type ORDER BY n DESC"

# Prune sessions older than 30 days
bash scripts/analyze.sh retention --days 30

Output Files

File	Description
.claude/observability/events.db	SQLite WAL store
.claude/observability/report.md	All-sessions report
.claude/observability/<session_id>.md	Per-session report
.claude/observability/export.jsonl	JSONL export

Further Reading

See Using Analyze for a complete how-to including privacy, retention, labeling, and exporter configuration. See Observability Schema for table DDL and example queries.

---

/agent-flow:explain

Generate an interactive HTML explainer for a codebase topic. Riko gathers the relevant code scope, Senku designs a 3–5 screen teaching arc, Speedwagon authors the module brief and HTML fragment, and the assembler concatenates everything into explain-out/index.html — a file you can open directly in a browser.

Syntax

/agent-flow:explain <topic>
/agent-flow:explain --revise <slug>

Arguments

Argument	Required	Description
<topic>	Yes (normal mode)	The concept or system to explain (e.g. how does orchestration work)
--revise <slug>	Yes (revise mode)	Slug of an existing brief to improve (e.g. --revise orchestration-pipeline)

Examples

# Explain a concept from scratch
/agent-flow:explain how does orchestration work

# Explain authentication flow
/agent-flow:explain JWT authentication middleware

# Revise an existing explainer
/agent-flow:explain --revise orchestration-pipeline

Workflow Phases

sequenceDiagram
    participant U as User
    participant R as Riko (Explorer)
    participant S as Senku (Planner)
    participant SW as Speedwagon (Authoring)
    participant A as Assembler + lint

    U->>R: /agent-flow:explain <topic>
    R->>S: Scope bundle (file:line refs, graph nodes, terminology)
    S->>SW: Curriculum plan (3–5 screens, metaphor, translator pick)
    SW->>A: HTML fragment (.claude/explain-briefs/<slug>.fragment.html)
    A->>U: explain-out/index.html (open in browser)

Phase 1 — Scope (Riko): Reads .claude/deep-dive.local.md when present (otherwise the README and up to 5 entry-point files), queries the graphify graph if present, identifies 3–8 file:line refs, 2–4 graph node names, and 3–6 key terminology terms. Returns a structured scope bundle, including a "Why It Matters" note.

Phase 2 — Curriculum (Senku): Designs a 3–5 screen teaching arc from the scope bundle. Selects one code snippet for the code↔English translator primitive. Produces a curriculum plan with a metaphor, screen titles, screen bodies, and a translator pick.

Phase 3 — Authoring (Speedwagon): Reads every file:line reference to verify content. Writes the module brief to .claude/explain-briefs/<slug>.md and the HTML fragment to .claude/explain-briefs/<slug>.fragment.html. Runs the assembler.

Phase 4 — Assembly: bash ${CLAUDE_PLUGIN_ROOT}/scripts/compile-explain.sh concatenates all fragments into explain-out/index.html. The lint guardrail (scripts/lib/explain-lint.py) checks eleven rules on every compile. Only forbidden classes and the forbidden inline handlers (selectOption, checkQuiz, resetQuiz) fail the compile; everything else — undefined CSS classes/variables, other onclick attributes, aria integrity, the language allow-list, diagram-first ordering, and the readability checks (text-only screens, overlong paragraphs, unfilled placeholders) — is a warning that fails only with --strict.

Output Structure

explain-out/
  index.html        rendered explainer (gitignored)
  status.json       per-module feedback state (gitignored)

.claude/explain-briefs/
  <slug>.md             module brief
  <slug>.fragment.html  filled-in HTML fragment

The index.html is a self-contained file you can open directly in a browser. The explain-out/ directory is gitignored — generated artifacts are never committed.

Revise Mode

When invoked as /agent-flow:explain --revise <slug>:

1. Checks .claude/explain-briefs/<slug>.md exists — errors if not.
2. Reads explain-out/status.json for revision notes on that slug.
3. Dispatches Speedwagon to apply the notes, rewrite the HTML fragment, and run bash ${CLAUDE_PLUGIN_ROOT}/scripts/compile-explain.sh --revise <slug>.

Revise mode skips Phase 1 (Riko scope) and Phase 2 (Senku curriculum) when the brief already exists, jumping directly to Speedwagon.

State / Prerequisites

Requirement	Status	Notes
.claude/deep-dive.local.md	Optional	Used when present for richer context; run /deep-dive first for best results, but /explain never blocks on it
graphify-out/graph.json	Optional	Used if present; degrades gracefully if absent

Further Reading

See Using Explain for a complete how-to guide including prerequisites, best practices, and troubleshooting. See Agents Reference for the Speedwagon agent specification and the explainer-design-system skill it uses.

---

State Files

All commands use state files in .claude/:

File	Command	Purpose
orchestration.local.md	/orchestrate	Track phase progress
deep-dive.local.md	/deep-dive	Store codebase context

See State Files Reference for format details.

Command Comparison

Aspect	/orchestrate	/deep-dive	/agent-flow:explain
Purpose	Execute tasks	Gather context	Generate interactive explainer
Output	Modified files	Context file	explain-out/index.html
Agents	Riko, Senku, Loid, Lawliet, Alphonse (+ Codex)	Riko + Senku	Riko + Senku + Speedwagon
Verification	Full gates	None	lint guardrail only
Reusable	No	Yes	Brief + revise mode
Prerequisites	None	None	/deep-dive optional
Parallelization	Review + Verification	Exploration	None

Best Practices

When to Use /deep-dive

• Starting work on unfamiliar codebase
• Beginning a new development session
• Before complex refactoring
• When orchestration exploration seems slow

When to Use /orchestrate

• Implementing new features
• Fixing bugs
• Refactoring code
• Any task requiring code changes
• Debugging workflows (easier to trace sequential flow)

When to Use /team-orchestrate

Deprecated — use /orchestrate.

When to Use /agent-flow:explain

• Onboarding a new team member to a specific subsystem
• Documenting a complex concept as an interactive reference
• Teaching yourself a part of the codebase you haven't touched
• Creating shareable educational material from existing code

Combining Commands

# First session: explore the codebase
/deep-dive

# Subsequent tasks: leverage context
/orchestrate --use-deep-dive Add feature A
/orchestrate --use-deep-dive Fix bug B
/orchestrate --use-deep-dive Refactor module C

# After major changes: refresh context
/deep-dive --refresh

Environment Variables

Variable	Description
AGENT_FLOW_NO_GITIGNORE	Any non-empty value stops agent-flow from editing your .gitignore. See State Files.
AGENT_FLOW_CODEX_MODEL	Model passed to Codex; overrides model in ~/.codex/config.toml.
AGENT_FLOW_PERSONAL_KB_PATH	Absolute path to your personal knowledge base root. See Using Personal KB.
AGENT_FLOW_NO_AGENTSVIEW	Set to 1 to disable AgentsView prior-session-history search for a single run. See Using AgentsView.
AGENT_FLOW_NO_CODEX	Any non-empty value (e.g. 1) disables Codex co-review for a single Claude Code session. Must be set at Claude Code startup, not at slash-command invocation time. Applies to /orchestrate.
AGENT_FLOW_CODEX_TIMEOUT	Codex co-review timeout in seconds (default 480; was a hard-coded 120s). Non-integer values fall back to 480. In the workflow path Codex runs in a foreground Bash call. The Bash tool caps calls at 600000 ms (10 min) unless BASH_MAX_TIMEOUT_MS is raised, so values above ~540 need that too; without it the workflow clamps the run to the cap minus 60 s so the helper reports a clean timeout instead of being killed. See Using Codex Co-Review.
AGENT_FLOW_CODEX_MAX_FILE_BYTES	Untracked files larger than this many bytes (plus binaries and common artifact dirs) are listed as omitted instead of inlined in the Codex prompt (default 100000).
AGENT_FLOW_CODEX_MAX_DIFF_CHARS	If the Codex review diff exceeds this many characters, Codex receives git diff --stat instead and reads files itself (default 800000).
AGENT_FLOW_CODEX_INLINE_UNTRACKED	Set to 0 to disable inlining untracked files entirely when the .claude/review-baseline-untracked.local.txt baseline is missing or stale (default 1). See Using Codex Co-Review.

Related Documentation

• Using Orchestrate Guide - Step-by-step usage
• Using Deep-Dive Guide - Step-by-step usage
• State Files Reference - State file formats
• Agents Reference - Agent specifications