Diagrams — Module 1: The Execution Loop

flowchart LR
    subgraph REACT["ReAct / TAO"]
        R1[Thought] --> R2[Action] --> R3[Observation] --> R1
    end

    subgraph PLAN["Plan-then-Execute"]
        P1[Plan all steps] --> P2[Execute step 1] --> P3[Execute step 2] --> P4[...step N]
    end

    subgraph GRAPH["Graph-based (LangGraph)"]
        G1((node A)) --> G2((node B))
        G2 --> G3((node C))
        G3 -.-> G2
        G3 --> G4((done))
    end

    subgraph DUMB["Dumb Loop"]
        D1[Model decides] --> D2[Harness executes] --> D1
    end

    subgraph CONV["Conversation-driven"]
        C1[Agent 1] <--> C2[Agent 2]
        C2 <--> C3[Agent 3]
        C1 <--> C3
    end

    style REACT fill:#0d1b2a,stroke:#1b4f72,color:#85c1e9
    style PLAN fill:#0d2818,stroke:#1e8449,color:#82e0aa
    style GRAPH fill:#2a1810,stroke:#a04000,color:#f0a868
    style DUMB fill:#15152d,stroke:#20208a,color:#a0a0d0
    style CONV fill:#2a0d0d,stroke:#a00000,color:#f08080

sequenceDiagram
    participant H as Harness (loop)
    participant M as Model
    participant T as Tool Executor

    H->>M: [system + history + tools + user task]
    Note over M: THOUGHT: "I should read the file first"
    M-->>H: tool_use: read_file({path: "auth.ts"})

    H->>T: read_file("auth.ts")
    T-->>H: {content: "...248 lines...", tokens: 1840}

    H->>M: [history + tool_result]
    Note over M: THOUGHT: "The function is too long. Extract validation."
    M-->>H: tool_use: write_file({path: "auth.ts", content: "..."})

    H->>T: write_file(...)
    T-->>H: {status: "ok", bytes: 3420}

    H->>M: [history + tool_result]
    Note over M: Task complete.
    M-->>H: stop_reason: "end_turn" — final answer

    H->>H: Loop exits. Return to user.

stateDiagram-v2
    [*] --> Running
    Running --> CheckStop: each turn
    CheckStop --> Done: end_turn (no tool call)
    CheckStop --> Done: max iterations cap
    CheckStop --> Done: token budget exhausted
    CheckStop --> Done: error threshold (N consecutive)
    CheckStop --> PausedHITL: human interrupt
    CheckStop --> Running: none triggered — continue
    PausedHITL --> Running: human approves
    PausedHITL --> Done: human rejects
    Done --> [*]

    note right of CheckStop
        A loop with NO stop condition
        is a production defect —
        the infinite loop problem.
    end note

quadrantChart
    title Subagent patterns: control vs visibility
    x-axis "Parent loses visibility" --> "Parent keeps visibility"
    y-axis "Synchronous" --> "Parallel"
    quadrant-1 "Worktree: parallel + mergeable"
    quadrant-2 "Agents-as-tools: sync, parent in control"
    quadrant-3 "Handoffs: terminal, one-way"
    quadrant-4 "Fork: isolated, independent"
    "Agents-as-tools": [0.75, 0.25]
    "Handoffs": [0.2, 0.3]
    "Fork": [0.4, 0.75]
    "Worktree": [0.7, 0.8]