Agent Hub Flow Diagram - Multi-agent orchestration system from 12-agent-hub.ts

agent-hub-flow.md

Agent Hub Flow Diagram

This diagram illustrates the multi-agent orchestration system from 12-agent-hub.ts.

Main Flow Diagram

flowchart TB
    subgraph User["User Input"]
        U[("User")]
    end

    subgraph Planning["Planning Phase"]
        PM["PM<br/>(Project Manager Hub)"]

        subgraph Experts["Expert Advisors (ExpertSession)"]
            NJS["NextJS"]
            AISDK["AI-SDK"]
            PLAT["Platform"]
            WF["Workflow"]
            GEIST["Geist"]
            AIGW["AI-Gateway"]
            FLAGS["Flags"]
        end
    end

    subgraph Review["Architecture Review"]
        ARCH["Architect<br/>(BuilderSession)"]
    end

    subgraph TDD["TDD Phase"]
        TEST["Testing<br/>(BuilderSession)"]
        BUILD["Builder<br/>(BuilderSession)"]
    end

    subgraph Quality["Quality & Commit"]
        QA["QA<br/>(BuilderSession)"]
        GIT["GitOps<br/>(BuilderSession)"]
    end

    subgraph Output["Output"]
        DONE(["Committed<br/>to Git"])
        BLOCKED(["Commit<br/>Blocked"])
    end

    %% Main Flow
    U -->|"Initial Request"| PM

    %% PM routes to experts
    PM <-->|"[NextJS]"| NJS
    PM <-->|"[AI-SDK]"| AISDK
    PM <-->|"[Platform]"| PLAT
    PM <-.->|"[Workflow]"| WF
    PM <-.->|"[Geist]"| GEIST
    PM <-.->|"[AI-Gateway]"| AIGW
    PM <-.->|"[Flags]"| FLAGS

    %% Expert cross-talk
    NJS <-.->|"Tag each other"| AISDK
    AISDK <-.->|"Tag each other"| PLAT

    %% PM creates plan
    PM -->|"[BUILD]<br/>Plan Ready"| ARCH

    %% Architect review
    ARCH -->|"[APPROVED]"| TEST
    ARCH -->|"[REVISION]"| PM
    ARCH <-.->|"Consult Experts"| Experts

    %% Testing creates TDD plan
    TEST -->|"Test Plan"| BUILD

    %% Builder implements
    BUILD -->|"[TESTS_PASS]"| GIT
    BUILD -->|"[TESTS_FAIL]<br/>(retry up to 3x)"| BUILD

    %% GitOps review and commit
    GIT -->|"[BUILDER]<br/>Needs fixes"| BUILD
    BUILD -->|"[FIXED]"| GIT
    GIT -->|"[COMMITTED]"| DONE
    GIT -->|"[COMMIT_BLOCKED]"| BLOCKED

    %% Styling
    classDef hub fill:#3b82f6,color:white,stroke:#1d4ed8
    classDef expert fill:#06b6d4,color:white,stroke:#0891b2
    classDef builder fill:#ef4444,color:white,stroke:#dc2626
    classDef review fill:#8b5cf6,color:white,stroke:#7c3aed
    classDef testing fill:#f97316,color:white,stroke:#ea580c
    classDef qa fill:#22d3ee,color:black,stroke:#06b6d4
    classDef gitops fill:#f59e0b,color:black,stroke:#d97706
    classDef success fill:#22c55e,color:white,stroke:#16a34a
    classDef failure fill:#dc2626,color:white,stroke:#b91c1c

    class PM hub
    class NJS,AISDK,PLAT,WF,GEIST,AIGW,FLAGS expert
    class BUILD builder
    class ARCH review
    class TEST testing
    class QA qa
    class GIT gitops
    class DONE success
    class BLOCKED failure

Loading

Session Types

flowchart LR
    subgraph ExpertSession["ExpertSession (Limited)"]
        direction TB
        E1["Single-turn responses"]
        E2["No tool access"]
        E3["--max-turns 1"]
        E4["Advisory only"]
    end

    subgraph BuilderSession["BuilderSession (Full Access)"]
        direction TB
        B1["Multi-turn conversations"]
        B2["Full tool access"]
        B3["--dangerously-skip-permissions"]
        B4["Can create/modify files"]
    end

    ExpertSession --> |"Used by"| Advisors["NextJS, AI-SDK, Platform,<br/>Workflow, Geist, AI-Gateway, Flags"]
    BuilderSession --> |"Used by"| Builders["Architect, Testing,<br/>Builder, QA, GitOps"]

Loading

Call Stack Routing

sequenceDiagram
    participant PM
    participant NextJS
    participant AI-SDK
    participant Platform

    Note over PM: User asks question
    PM->>NextJS: [NextJS] What's the routing strategy?
    Note over PM: Stack: [{returnTo: PM, queue: [AI-SDK, Platform]}]
    NextJS->>AI-SDK: [AI-SDK] Need streaming for this?
    Note over PM: Stack: [{returnTo: PM, queue: [Platform]}, {returnTo: NextJS, queue: []}]
    AI-SDK-->>NextJS: Response + [READY]
    Note over PM: Pop stack, return to NextJS
    NextJS-->>PM: Response + [READY]
    Note over PM: Continue with queue
    PM->>AI-SDK: [AI-SDK] already answered
    PM->>Platform: [Platform] Deployment config?
    Platform-->>PM: Response + [READY]
    Note over PM: All experts ready, write [BUILD]

Loading

Decision Points & Gates

flowchart TB
    subgraph PMGate["PM Gate"]
        PM_Q{"All experts<br/>[READY]?"}
        PM_Q -->|"Yes"| PM_BUILD["[BUILD]"]
        PM_Q -->|"No"| PM_ROUTE["Route to<br/>remaining experts"]
    end

    subgraph ArchGate["Architect Gate"]
        ARCH_Q{"Architecture<br/>quality OK?"}
        ARCH_Q -->|"Good"| ARCH_APP["[APPROVED]"]
        ARCH_Q -->|"Issues"| ARCH_REV["[REVISION]<br/>(up to 3x)"]
        ARCH_Q -->|"Need info"| ARCH_ASK["Tag experts"]
    end

    subgraph BuildGate["Builder Gate"]
        BUILD_Q{"Tests<br/>pass?"}
        BUILD_Q -->|"Yes"| BUILD_PASS["[TESTS_PASS]"]
        BUILD_Q -->|"No"| BUILD_FAIL["[TESTS_FAIL]<br/>(retry up to 3x)"]
    end

    subgraph GitGate["GitOps Gate"]
        GIT_Q{"Code<br/>quality OK?"}
        GIT_Q -->|"Good"| GIT_COMMIT["[COMMITTED]"]
        GIT_Q -->|"Issues"| GIT_BUILDER["[BUILDER]<br/>(up to 5x)"]
        GIT_Q -->|"Critical"| GIT_BLOCK["[COMMIT_BLOCKED]"]
    end

    PM_BUILD --> ARCH_Q
    ARCH_APP --> BUILD_Q
    BUILD_PASS --> GIT_Q

Loading

Revision Loops

flowchart LR
    subgraph ArchitectLoop["Architect Revision Loop (max 3)"]
        A1["PM writes plan"] --> A2["Architect reviews"]
        A2 -->|"[REVISION]"| A1
        A2 -->|"[APPROVED]"| A3["Continue to Testing"]
    end

    subgraph GitOpsLoop["GitOps/Builder Loop (max 5)"]
        G1["Builder implements"] --> G2["GitOps reviews"]
        G2 -->|"[BUILDER]"| G3["Builder fixes"]
        G3 -->|"[FIXED]"| G2
        G2 -->|"[COMMITTED]"| G4["Done"]
    end

Loading

Legend

Symbol	Meaning
[TAG]	Control flow tag in agent response
-->	Required/primary flow
-.->	Optional/conditional flow
<-->	Bidirectional communication
Blue	Hub (PM)
Cyan	Expert Advisors
Purple	Architecture Review
Orange	Testing/TDD
Red	Builder
Yellow	GitOps
Green	Success state
Dark Red	Blocked/Failed state

Key Tags Reference

Agent	Tag	Purpose
All Experts	[READY]	Expert has finished contributing
All Experts	[USER]	Need user clarification
All Experts	[NextJS] [AI-SDK] etc.	Tag another expert
PM	[BUILD]	Plan is ready for Architect
Architect	[APPROVED]	Plan passes review
Architect	[REVISION]	Send back to PM
Builder	[TESTS_PASS]	All tests pass
Builder	[TESTS_FAIL]	Tests failed
Builder	[FIXED]	Fixed GitOps feedback
GitOps	[COMMITTED]	Code committed
GitOps	[BUILDER]	Send back for fixes
GitOps	[COMMIT_BLOCKED]	Cannot commit