Skip to content

Multi-agent orchestration

Implemented Designed

Source: doc/governance/Multi_Agent_Execution_Playbook.md · doc/governance/Agent_Orchestrator_v1.md · doc/governance/Agent_Orchestrator_v2_Coordinated_Execution.md · doc/governance/Agent_Startup_Prompts.md · doc/governance/Multi_Agent_Review_Model.md

How role-based coding agents execute work in parallel against the shared queue without corrupting history, stepping on each other, or weakening contract-first / evidence-first discipline.

The orchestrator model in one diagram

flowchart TB
    classDef src fill:#fff8e1,stroke:#f57f17
    classDef agent fill:#e3f2fd,stroke:#1565c0
    classDef wt fill:#fff3e0,stroke:#e65100
    classDef hist fill:#eceff1,stroke:#455a64

    Q[Agent_Work_Queue.yaml<br/>406 tasks<br/>states todo / in_progress / blocked / done]:::src
    SP[Agent_Startup_Prompts.md<br/>per-role bootstrap]:::src
    POL[agent_policy.yaml<br/>machine policy floor]:::src

    Q --> O[Agent orchestrator]:::agent
    SP --> O
    POL --> O

    O --> A[A-backend lane]:::agent
    O --> B[B-ui lane]:::agent
    O --> C[C-ops lane]:::agent
    O --> D[D-arch reviewer lane]:::agent
    O --> E[E-governance reviewer lane]:::agent

    A --> WT_A[(agent/A-backend worktree)]:::wt
    B --> WT_B[(agent/B-ui worktree)]:::wt
    C --> WT_C[(agent/C-ops worktree)]:::wt

    WT_A --> PR_A[PR from A]
    WT_B --> PR_B[PR from B]
    WT_C --> PR_C[PR from C]

    PR_A --> D
    PR_B --> D
    PR_C --> D
    PR_A --> E
    PR_B --> E
    PR_C --> E

    D & E --> MERGE[Merge to master]
    MERGE --> Q
    MERGE --> HIST[(Audit history:<br/>commit + completed_at + acceptance_checks)]:::hist

Two versions of the orchestrator

flowchart LR
    classDef now fill:#d1e7dd,stroke:#0a3622
    classDef next fill:#fff3cd,stroke:#332701

    V1[Orchestrator v1<br/>non-destructive]:::now
    V1 --> V1A[Observe queue + git state]:::now
    V1 --> V1B[Validate schema + invariants]:::now
    V1 --> V1C[Recommend dispatch order]:::now
    V1 --> V1D[Queue mutation still explicit<br/>via make queue-claim<br/>+ make queue-set-status]:::now

    V2[Orchestrator v2<br/>coordinated execution]:::next
    V2 --> V2A[Coordinator loop<br/>post-human-signoff]:::next
    V2 --> V2B[Auto-claim eligible tasks]:::next
    V2 --> V2C[Merge + release authority<br/>remain auditable]:::next
    V2 --> V2D[Role agents proceed without<br/>repeated human scheduling]:::next

    V1 -.evolution path.-> V2
v1 (current) v2 (designed)
Mode Observe + validate + recommend Auto-coordinate
Queue mutation Explicit operator commands Coordinator-claimed within policy
Merge authority Reviewer-gated Reviewer-gated (unchanged)
Audit Per-commit + queue history Same + coordinator log
Status Implemented Designed (orchestrator_v2 doc)

v1 orchestrator commands (today)

sequenceDiagram
    autonumber
    participant OP as Operator
    participant Q as Agent_Work_Queue.yaml
    participant G as Git
    participant V as scripts/ci/agent_queue_validate.sh

    OP->>V: make queue-validate
    V->>Q: schema + invariant check
    V-->>OP: pass / fail

    OP->>Q: make queue-claim ID=A-PROV-SCHED-001 OWNER=A
    Q->>Q: status=in_progress, owner=A, branch=agent/A
    OP->>G: git switch -c agent/A
    OP->>OP: do the work
    OP->>G: commit + push
    OP->>Q: make queue-set-status ID=... STATUS=done COMMIT=<sha>
    OP->>V: make queue-git-check
    V-->>OP: queue ↔ git consistent

Concrete commands in the playbook:

make queue-validate         # schema + invariants
make queue-claim            # claim a task for a role
make queue-set-status       # mark in_progress / blocked / done
make queue-git-check        # queue ↔ git branch consistency

The queue's mutation is gated. Hand-edits to Agent_Work_Queue.yaml get rejected because they break the validator.

Agent role startup

Each role has a documented startup prompt covering: read order, expected scope, invariants, and merge requirements.

flowchart LR
    classDef step fill:#e3f2fd,stroke:#1565c0

    S1[Read AGENTS.md<br/>+ Coding_Standards.md]:::step
    S1 --> S2[Read role-specific<br/>startup prompt]:::step
    S2 --> S3[Read agent_policy.yaml<br/>+ reviewguard policy]:::step
    S3 --> S4[Inspect queue for<br/>eligible tasks in your role]:::step
    S4 --> S5[Claim one task]:::step
    S5 --> S6[Switch to lane worktree]:::step
    S6 --> S7[Read 'pre-read' files<br/>in task notes]:::step
    S7 --> S8[Implement + test +<br/>acceptance checks]:::step
    S8 --> S9[Open PR]:::step

→ Source: Agent_Startup_Prompts.md

Cross-lane handoff

sequenceDiagram
    autonumber
    participant A as A-backend
    participant B as B-ui
    participant C as C-ops
    participant Q as Queue
    participant CI as CI

    Note over A,Q: A finishes API endpoint (contract-first)
    A->>Q: mark task done — commit recorded
    Note over B,Q: B's UI task depends_on A's task
    B->>Q: claim UI task (was blocked → todo → in_progress)
    B->>B: pnpm typecheck + vitest pass
    B->>Q: mark done — commit recorded
    Note over C: C adds runbook + alert for the new endpoint
    C->>Q: claim ops task
    C->>C: write runbook, register alert
    C->>Q: mark done — commit recorded
    Q->>CI: all 3 in one release window
    CI->>CI: validate end-to-end

depends_on is a first-class field on every task. The orchestrator only surfaces a task as eligible once its dependencies are done.

How "no agent corrupts history" is enforced

flowchart TB
    classDef block fill:#f8d7da,stroke:#42101e
    classDef ok fill:#d1e7dd,stroke:#0a3622

    HAND[Hand-edit queue YAML?]:::block --> X1[Rejected by<br/>agent_queue_validate.sh]:::block
    MERGE[Merge without acceptance_checks?]:::block --> X2[Rejected by<br/>reviewguard]:::block
    SAME[Same task claimed by 2 agents?]:::block --> X3[Rejected by<br/>queue-claim atomicity]:::block
    DROP[Drop tests to make CI green?]:::block --> X4[Rejected by<br/>coverage gate +<br/>Testing_Standards]:::block
    DIR[Direct push to release branch?]:::block --> X5[Rejected by<br/>Platform_Control_Release_Promotion_Policy]:::block

    OK[All five paths require human reviewer + CI green]:::ok

Why this is unusual

flowchart LR
    classDef typical fill:#ffebee,stroke:#c62828
    classDef us fill:#d1e7dd,stroke:#0a3622

    TYP[Typical agent setup<br/>chat in IDE → edits files →<br/>human reviews PR]:::typical
    US[GPUaaS setup<br/>structured queue → role agent →<br/>lane worktree → cross-model review →<br/>machine policy enforcement →<br/>audited merge]:::us

    note1[Pros: parallelism, audit,<br/>contract discipline preserved]
    US -.gives.-> note1

Trade-off accepted: more upfront infrastructure (queue + orchestrator + policy YAML + lane worktrees) in exchange for multi-agent parallel execution that doesn't corrupt history.

Review model overlay

Cross-engine review is encouraged. The 5-lane model:

flowchart TB
    classDef del fill:#e3f2fd,stroke:#1565c0
    classDef rev fill:#ede7f6,stroke:#5e35b1

    subgraph DEL[Delivery lanes]
        A[A-backend<br/>services / workers / contracts]:::del
        B[B-ui<br/>web UX + e2e]:::del
        C[C-ops<br/>observability / runbooks / platform docs]:::del
    end
    subgraph REV[Review lanes]
        D[D-arch<br/>architecture / contracts review]:::rev
        E[E-governance<br/>process / quality / security review]:::rev
    end

    A & B & C -.PR.-> D
    A & B & C -.PR.-> E
    D -.reviews.-> E
    E -.reviews.-> D

    NOTE[Independence rules:<br/>1. A lane must NOT self-approve its own critical changes<br/>2. D-arch and E-governance must review each other<br/>3. Prefer cross-engine review diversity]

→ Source: Multi_Agent_Review_Model.md

Where to look next