Skip to content

Instantly share code, notes, and snippets.

@johnlindquist

johnlindquist/demo13-diagram.md

Created January 29, 2026 03:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save johnlindquist/7d8a35373d63eec10acf5c513e96cb09 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save johnlindquist/7d8a35373d63eec10acf5c513e96cb09 to your computer and use it in GitHub Desktop.
Download ZIP
Vercel-Native Agent Hub (Demo 13) - Architecture diagram showing 15 specialized agents orchestrating TDD-based Vercel app development with quality gates
Raw
demo13-diagram.md

Vercel-Native Agent Hub (Demo 13) - Architecture Diagram

This diagram illustrates the complete flow of the Vercel-Native Agent Hub system, which orchestrates 15 specialized agents to build Vercel-native applications using a TDD workflow with quality gates.

System Overview

  • 15 Total Agents: 1 PM Hub + 7 Core Advisors + 2 Optional Advisors + 5 Builders
  • Capability Scoping: Each agent has specific tool permissions (no dangerously-skip-permissions)
  • Quality Gates: Architect Gate, QA Gate, and GitOps verification
  • TDD Workflow: Tests are written first, then implementation, then verification
flowchart TB
    subgraph User["User Input"]
        U[("User Request")]
    end

    subgraph PMHub["PM Hub (Project Manager)"]
        PM["PM<br/>Routes & Synthesizes<br/><i>Tools: Read, Glob, Grep, WebFetch</i>"]
    end

    subgraph CoreAdvisors["Core Advisors (Read-Only)"]
        direction TB
        NextJS["NextJS<br/><i>App Router, RSC</i>"]
        AISDK["AI-SDK<br/><i>streamText, tools</i>"]
        AIGateway["AI-Gateway<br/><i>OIDC, routing</i>"]
        Platform["Platform<br/><i>Fluid compute, env</i>"]
        Workflow["Workflow<br/><i>use workflow/step</i>"]
        Security["Security<br/><i>WAF, rate limits</i>"]
        Observability["Observability<br/><i>Tracing, OTEL</i>"]
    end

    subgraph OptionalAdvisors["Optional Advisors (Read-Only)"]
        Flags["Flags<br/><i>Feature flags, A/B</i>"]
        Geist["Geist<br/><i>Design system</i>"]
    end

    subgraph AdvisorTools["Advisor Capabilities"]
        AT["Read, Glob, Grep, WebFetch<br/>(read-only retrieval)"]
    end

    subgraph Builders["Builder Agents (Capability-Scoped)"]
        direction TB
        Architect["Architect<br/><i>Architecture Gate</i><br/>Tools: Read, Glob, Grep, Bash<br/>(tsc only)"]
        Testing["Testing<br/><i>TDD Planner</i><br/>Tools: Read, Glob, Grep, Bash<br/>(test commands)"]
        Builder["Builder<br/><i>Code Implementation</i><br/>Tools: Read, Write, Edit,<br/>Glob, Grep, Bash"]
        QA["QA<br/><i>Quality Gate</i><br/>Tools: Read, Glob, Grep, Bash<br/>(checks only)"]
        GitOps["GitOps<br/><i>Version Control</i><br/>Tools: Read, Glob, Grep, Bash<br/>(git commands)"]
    end

    subgraph Outputs["Final Outputs"]
        Committed[("Code Committed<br/>[COMMITTED]")]
        Blocked[("Commit Blocked<br/>[COMMIT_BLOCKED]")]
    end

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

    %% PM Fan-out to Advisors
    PM -->|"[NextJS] question"| NextJS
    PM -->|"[AI-SDK] question"| AISDK
    PM -->|"[AI-Gateway] question"| AIGateway
    PM -->|"[Platform] question"| Platform
    PM -->|"[Workflow] question"| Workflow
    PM -->|"[Security] question"| Security
    PM -->|"[Observability] question"| Observability
    PM -.->|"(when relevant)"| Flags
    PM -.->|"(when relevant)"| Geist

    %% Advisors respond with status
    NextJS -->|"status: READY/USER/BLOCKED"| PM
    AISDK -->|"status: READY/USER/BLOCKED"| PM
    AIGateway -->|"status: READY/USER/BLOCKED"| PM
    Platform -->|"status: READY/USER/BLOCKED"| PM
    Workflow -->|"status: READY/USER/BLOCKED"| PM
    Security -->|"status: READY/USER/BLOCKED"| PM
    Observability -->|"status: READY/USER/BLOCKED"| PM
    Flags -.->|"status: READY/USER/BLOCKED"| PM
    Geist -.->|"status: READY/USER/BLOCKED"| PM

    %% Advisor tool access
    CoreAdvisors -.-> AT
    OptionalAdvisors -.-> AT

    %% PM synthesizes and creates plan
    PM -->|"[BUILD] Plan Ready"| Architect

    %% Architect Gate Decision
    Architect -->|"[APPROVED]"| Testing
    Architect -->|"[REVISION]<br/>(max 3 times)"| PM

    %% Testing creates TDD plan
    Testing -->|"Test Plan"| Builder

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

    %% QA Gate Decision
    QA -->|"[QA_PASS]"| GitOps
    QA -->|"[QA_FAIL]"| Blocked

    %% GitOps commits
    GitOps -->|"[COMMITTED]"| Committed
    GitOps -->|"[BUILDER] needs fixes"| Builder
    GitOps -->|"[COMMIT_BLOCKED]"| Blocked

    %% User interaction loop
    PM -->|"[USER] needs clarification"| U
    U -->|"User Response"| PM

    %% Styling
    classDef pmStyle fill:#3b82f6,stroke:#1d4ed8,color:#fff
    classDef advisorStyle fill:#8b5cf6,stroke:#6d28d9,color:#fff
    classDef optionalStyle fill:#a78bfa,stroke:#7c3aed,color:#fff
    classDef builderStyle fill:#22c55e,stroke:#16a34a,color:#fff
    classDef gateStyle fill:#f59e0b,stroke:#d97706,color:#fff
    classDef outputStyle fill:#10b981,stroke:#059669,color:#fff
    classDef blockedStyle fill:#ef4444,stroke:#dc2626,color:#fff
    classDef userStyle fill:#6366f1,stroke:#4f46e5,color:#fff

    class PM pmStyle
    class NextJS,AISDK,AIGateway,Platform,Workflow,Security,Observability advisorStyle
    class Flags,Geist optionalStyle
    class Builder builderStyle
    class Architect,Testing,QA gateStyle
    class GitOps gateStyle
    class Committed outputStyle
    class Blocked blockedStyle
    class U userStyle
Loading

Detailed Phase Flow

flowchart LR
    subgraph Phase1["Phase 1: Triage & Route"]
        P1A["PM receives request"]
        P1B["PM tags relevant advisors"]
        P1C["Advisors respond with YAML status"]
        P1D{"All advisors<br/>READY?"}
        P1A --> P1B --> P1C --> P1D
        P1D -->|"No"| P1B
    end

    subgraph Phase2["Phase 2: Synthesize & Plan"]
        P2A["PM synthesizes responses"]
        P2B["PM writes implementation plan"]
        P2C["PM emits [BUILD] tag"]
        P2A --> P2B --> P2C
    end

    subgraph Phase3["Phase 3: Architecture Gate"]
        P3A["Architect reviews plan"]
        P3B{"Approved?"}
        P3C["[APPROVED]"]
        P3D["[REVISION]"]
        P3A --> P3B
        P3B -->|"Yes"| P3C
        P3B -->|"No"| P3D
    end

    subgraph Phase4["Phase 4: TDD Implementation"]
        P4A["Testing creates test plan"]
        P4B["Builder writes tests first"]
        P4C["Builder runs tests (fail)"]
        P4D["Builder implements code"]
        P4E["Builder runs tests"]
        P4F{"Tests pass?"}
        P4A --> P4B --> P4C --> P4D --> P4E --> P4F
        P4F -->|"No (retry)"| P4D
    end

    subgraph Phase5["Phase 5: Quality Gate"]
        P5A["QA runs type check"]
        P5B["QA runs lint"]
        P5C["QA runs tests"]
        P5D["QA runs build"]
        P5E["QA security review"]
        P5F["QA observability review"]
        P5G{"All pass?"}
        P5A --> P5B --> P5C --> P5D --> P5E --> P5F --> P5G
    end

    subgraph Phase6["Phase 6: GitOps"]
        P6A["Verify files exist"]
        P6B["Create .gitignore"]
        P6C["Run prettier"]
        P6D["Git commit"]
        P6A --> P6B --> P6C --> P6D
    end

    Phase1 --> Phase2
    P1D -->|"Yes"| Phase2
    Phase2 --> Phase3
    P3C --> Phase4
    P3D -->|"max 3x"| Phase1
    P4F -->|"Yes"| Phase5
    P5G -->|"Yes [QA_PASS]"| Phase6
    P5G -->|"No [QA_FAIL]"| BLOCKED["Blocked"]

    classDef phaseStyle fill:#e0e7ff,stroke:#6366f1
    class Phase1,Phase2,Phase3,Phase4,Phase5,Phase6 phaseStyle
Loading

Agent Capability Matrix

graph LR
    subgraph Capabilities["Tool Capabilities by Agent Type"]
        subgraph ReadOnly["Read-Only (Advisors)"]
            RO["Read | Glob | Grep | WebFetch"]
        end

        subgraph ArchitectCap["Architect"]
            AC["Read | Glob | Grep | Bash<br/>(tsc, cat, ls, find only)"]
        end

        subgraph TesterCap["Testing"]
            TC["Read | Glob | Grep | Bash<br/>(npm test, vitest, jest, playwright)"]
        end

        subgraph BuilderCap["Builder"]
            BC["Read | Write | Edit | Glob | Grep | Bash<br/>(npm, npx, bun, mkdir, touch, tsc)"]
        end

        subgraph QACap["QA"]
            QC["Read | Glob | Grep | Bash<br/>(npm test, tsc, lint, build)"]
        end

        subgraph GitOpsCap["GitOps"]
            GC["Read | Glob | Grep | Bash<br/>(git, prettier only)"]
        end
    end

    classDef readonly fill:#dbeafe,stroke:#3b82f6
    classDef limited fill:#fef3c7,stroke:#f59e0b
    classDef full fill:#dcfce7,stroke:#22c55e

    class RO readonly
    class AC,TC,QC,GC limited
    class BC full
Loading

Response Schema (YAML Block)

Every advisor must end their response with this structured format:

status: READY | USER | BLOCKED
assumptions:
  - assumption 1
  - assumption 2
decisions:
  - decision 1
risks:
  - severity: low|med|high
    issue: description
next_actions:
  - owner: PM|Builder|etc
    action: what to do
vercel_implications:
  - vercel-specific consideration

Key State Tags

Tag Emitter Meaning
[AdvisorName] PM Routes question to specific advisor
[USER] PM/Advisor Needs user clarification
[BUILD] PM Plan complete, ready for build
[APPROVED] Architect Architecture review passed
[REVISION] Architect Architecture needs changes
[TESTS_PASS] Builder All tests passing
[TESTS_FAIL] Builder Tests failed
[QA_PASS] QA All quality checks passed
[QA_FAIL] QA Quality issues found (blocks GitOps)
[COMMITTED] GitOps Code successfully committed
[BUILDER] GitOps Issues found, needs Builder fixes
[COMMIT_BLOCKED] GitOps Critical issues, cannot proceed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment