Data Flows¶

Detailed sequence diagrams showing how data flows through Agent Flow during orchestration and deep-dive workflows.

Orchestration Data Flow¶

Complete Workflow Sequence¶

sequenceDiagram
    participant U as User
    participant H as Hooks
    participant O as Orchestrator
    participant ST as State File
    participant R as Riko
    participant S as Senku
    participant L as Loid
    participant LW as Lawliet
    participant A as Alphonse

    %% Initialization
    U->>O: /orchestrate "Add auth feature"
    O->>H: UserPromptSubmit
    H->>H: Prompt refinement check
    H-->>O: Refined prompt (if needed)
    O->>ST: init-orchestration.sh
    Note over O,ST: init-orchestration.sh calls detect-graph-context.sh<br/>and detect-personal-kb.sh, writing graph + personal_kb blocks into state
    ST-->>O: State initialized (with graph/personal_kb context blocks)

    %% Phase 1: Exploration
    rect rgb(200, 230, 255)
        Note over O,R: Phase 1: Exploration
        O->>R: Task: Explore codebase
        R->>R: Glob, Grep, Read
        R-->>O: Findings (files, patterns)
        O->>ST: update-state --phase planning
    end

    %% Phase 2: Planning
    rect rgb(200, 255, 200)
        Note over O,S: Phase 2: Planning
        O->>S: Task: Create plan<br/>(includes Riko findings)
        S->>S: Analyze, TodoWrite
        S-->>O: Implementation plan
        O->>ST: update-state --phase implementation
    end

    %% Phase 3: Implementation
    rect rgb(255, 255, 200)
        Note over O,L: Phase 3: Implementation
        O->>L: Task: Implement plan
        L->>H: PreToolUse (Write/Edit)
        H-->>L: Allowed
        L->>L: Write, Edit, Bash
        L->>H: PostToolUse
        H-->>L: Validation passed
        L-->>O: Changes made + sanity tests
        O->>ST: update-state --phase review
    end

    %% Phase 4: Review
    rect rgb(255, 230, 200)
        Note over O,LW: Phase 4: Review
        O->>LW: Task: Review changes
        LW->>LW: Static analysis (tsc, eslint)
        alt NEEDS_CHANGES
            LW-->>O: Issues found
            O->>L: Fix issues
            L-->>O: Fixed
            O->>LW: Re-review
        end
        LW-->>O: APPROVED
        O->>ST: update-state --phase verification
    end

    %% Phase 5: Verification
    rect rgb(255, 200, 200)
        Note over O,A: Phase 5: Verification
        O->>A: Task: Verify all
        A->>A: npm test, tsc, lint, build
        alt FAILED
            A-->>O: Failures (with output)
            O->>L: Fix failures
            L-->>O: Fixed
            O->>A: Re-verify
        end
        A-->>O: VERIFIED (with evidence)
        O->>ST: update-state --complete
    end

    %% Completion
    O->>H: Stop hook
    H->>H: verify-completion.sh
    H-->>O: Gates passed
    O->>U: TASK VERIFIED

Data Passed Between Phases¶

From	To	Data
User	Orchestrator	Task description
Hooks	Orchestrator	Refined prompt
Orchestrator	State	Phase transitions, gate results
detect-graph-context.sh	State	`graph:` block (available, path, nodes, edges, communities)
detect-personal-kb.sh	State	`personal_kb:` block (available, path, graph_path, nodes)
Riko	Orchestrator	Files, patterns, architecture
Orchestrator	Senku	Task + Riko's findings
Senku	Orchestrator	Implementation plan
Orchestrator	Loid	Plan + context
Loid	Orchestrator	Changed files + test results
Orchestrator	Lawliet	Changed files list
Lawliet	Orchestrator	Review verdict + issues
Orchestrator	Alphonse	Full codebase
Alphonse	Orchestrator	Verification evidence

Deep-Dive Data Flow¶

Parallel Exploration Sequence¶

sequenceDiagram
    participant U as User
    participant O as Orchestrator
    participant ST as State File
    participant R1 as Riko: Structure
    participant R2 as Riko: Conventions
    participant R3 as Riko: Anti-patterns
    participant R4 as Riko: Build/CI
    participant R5 as Riko: Architecture
    participant R6 as Riko: Testing
    participant S as Senku

    %% Initialization
    U->>O: /deep-dive
    O->>ST: init-deep-dive.sh
    ST-->>O: State initialized

    %% Phase 1: Parallel Exploration
    rect rgb(200, 230, 255)
        Note over O,R6: Phase 1: Parallel Exploration
        par Fire all agents simultaneously
            O->>R1: Explore structure
            O->>R2: Explore conventions
            O->>R3: Find anti-patterns
            O->>R4: Analyze build/CI
            O->>R5: Map architecture
            O->>R6: Examine testing
        end
        par Agents return findings
            R1-->>O: Directory structure
            R2-->>O: Config files, patterns
            R3-->>O: DO NOT list
            R4-->>O: Build commands, CI
            R5-->>O: Component map
            R6-->>O: Test patterns
        end
    end

    %% Phase 2: Synthesis
    rect rgb(200, 255, 200)
        Note over O,S: Phase 2: Synthesis
        O->>S: Merge all findings
        S->>S: Analyze, organize, deduplicate
        S-->>O: Unified context document
    end

    %% Phase 3: Compile
    rect rgb(255, 255, 200)
        Note over O,ST: Phase 3: Compile Output
        O->>ST: compile-deep-dive.sh
        ST-->>O: Context saved
    end

    O->>U: Deep-dive complete

Data Gathered by Each Agent¶

Agent	Explores	Output
Structure	Directory layout	Entry points, packages, organization
Conventions	Config files	Naming patterns, style rules
Anti-patterns	Comments, docs	DO NOT list, warnings
Build/CI	Scripts, workflows	Test commands, CI pipeline
Architecture	Source code	Component map, dependencies
Testing	Test files	Framework, patterns, utilities

State File Data Flow¶

Orchestration State Updates¶

flowchart TB
    subgraph Init["Initialization"]
        I1[init-orchestration.sh]
        I2["active: true<br/>phase: exploration<br/>iteration: 1"]
    end

    subgraph Phase1["Phase 1"]
        P1[Exploration complete]
        S1["phase: planning<br/>gates.exploration: passed"]
    end

    subgraph Phase2["Phase 2"]
        P2[Planning complete]
        S2["phase: implementation<br/>gates.planning: passed"]
    end

    subgraph Phase3["Phase 3"]
        P3[Implementation complete]
        S3["phase: review<br/>gates.implementation: passed"]
    end

    subgraph Phase4["Phase 4"]
        P4[Review complete]
        S4["phase: verification<br/>gates.review: passed"]
    end

    subgraph Phase5["Phase 5"]
        P5[Verification complete]
        S5["phase: complete<br/>gates.verification: passed"]
    end

    I1 --> I2
    I2 --> P1 --> S1
    S1 --> P2 --> S2
    S2 --> P3 --> S3
    S3 --> P4 --> S4
    S4 --> P5 --> S5

Deep-Dive State Updates¶

flowchart TB
    subgraph Init["Initialization"]
        I1[init-deep-dive.sh]
        I2["scope: full<br/>phase: exploring"]
    end

    subgraph Explore["Exploration"]
        E1[Agents complete]
        E2["phase: synthesizing"]
    end

    subgraph Synth["Synthesis"]
        S1[Senku complete]
        S2["phase: compiling"]
    end

    subgraph Output["Output"]
        O1[compile-deep-dive.sh]
        O2["phase: complete"]
    end

    I1 --> I2
    I2 --> E1 --> E2
    E2 --> S1 --> S2
    S2 --> O1 --> O2

Hook Data Flow¶

PreToolUse Flow¶

flowchart LR
    subgraph Agent["Agent Action"]
        A1[Write/Edit tool called]
    end

    subgraph PreHook["PreToolUse Hook"]
        H1[enforce-delegation.sh]
        H2[validate-changes.sh]
    end

    subgraph Decision["Decision"]
        D1{Path valid?}
        D2[Block operation]
        D3[Allow operation]
    end

    A1 --> H1
    H1 --> H2
    H2 --> D1
    D1 -->|No| D2
    D1 -->|Yes| D3

PostToolUse Flow¶

flowchart LR
    subgraph Tool["Tool Execution"]
        T1[Task tool completes]
    end

    subgraph PostHook["PostToolUse Hook"]
        H1[Prompt hook]
        H2[Verify based on agent type]
    end

    subgraph Guidance["Verification Guidance"]
        G1[Riko: Accept findings]
        G2[Senku: Review plan]
        G3[Loid: Full verification]
        G4[Lawliet: Consider feedback]
        G5[Alphonse: Check results]
    end

    T1 --> H1
    H1 --> H2
    H2 --> G1 & G2 & G3 & G4 & G5

Stop Hook Flow¶

flowchart TB
    subgraph Trigger["Task Completion"]
        T1[User sees response]
    end

    subgraph Hook["Stop Hook"]
        H1[verify-completion.sh]
    end

    subgraph Detect["Project Detection"]
        D1{package.json?}
        D2{pyproject.toml?}
        D3{Cargo.toml?}
        D4{go.mod?}
    end

    subgraph Verify["Verification"]
        V1[npm test]
        V2[pytest]
        V3[cargo test]
        V4[go test]
    end

    subgraph Result["Result"]
        R1[Pass: Allow completion]
        R2[Fail: Block completion]
    end

    T1 --> H1
    H1 --> D1
    D1 -->|Yes| V1
    D1 -->|No| D2
    D2 -->|Yes| V2
    D2 -->|No| D3
    D3 -->|Yes| V3
    D3 -->|No| D4
    D4 -->|Yes| V4

    V1 & V2 & V3 & V4 --> R1 & R2

Integration Points¶

Deep-Dive to Orchestrate¶

flowchart LR
    subgraph DeepDive["Deep-Dive"]
        DD1["/deep-dive"]
        DD2["deep-dive.local.md<br/>(phase: complete)"]
    end

    subgraph Orchestrate["Orchestrate"]
        O1["/orchestrate --use-deep-dive"]
        O2["Check deep-dive exists"]
        O3["Load context"]
        O4["Targeted exploration"]
    end

    DD1 --> DD2
    DD2 -.-> O1
    O1 --> O2
    O2 --> O3
    O3 --> O4

Iteration Loop¶

flowchart TB
    subgraph Main["Main Flow"]
        M1[Implementation]
        M2[Review]
        M3[Verification]
        M4[Complete]
    end

    subgraph Iteration["Iteration Loop"]
        I1{Review passed?}
        I2{Verification passed?}
        I3[Increment iteration]
        I4{Max iterations?}
        I5[Fail task]
    end

    M1 --> M2 --> I1
    I1 -->|Yes| M3 --> I2
    I1 -->|No| I3
    I2 -->|Yes| M4
    I2 -->|No| I3
    I3 --> I4
    I4 -->|No| M1
    I4 -->|Yes| I5

Architecture Overview - System design
Commands Reference - Command specifications
Hooks Reference - Hook system details
State Files Reference - State file formats

Data Flows¶

Orchestration Data Flow¶

Complete Workflow Sequence¶

Data Passed Between Phases¶

Deep-Dive Data Flow¶

Parallel Exploration Sequence¶

Data Gathered by Each Agent¶

State File Data Flow¶

Orchestration State Updates¶

Deep-Dive State Updates¶

Hook Data Flow¶

PreToolUse Flow¶

PostToolUse Flow¶

Stop Hook Flow¶

Integration Points¶

Deep-Dive to Orchestrate¶

Iteration Loop¶

Related Documentation¶