Skip to content

Lane worktrees & review

Implemented

Source: doc/governance/Multi_Agent_Lane_Worktrees_v1.md · doc/governance/Multi_Agent_Review_Model.md · doc/governance/Platform_Control_Release_Promotion_Policy.md

How multiple agents work simultaneously without merge conflicts or claim races: a 5-lane model with git worktree isolation and a cross-engine review overlay.

The 5-lane model

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

    subgraph DEL[Delivery lanes — produce changes]
        A[A-backend<br/>services / workers / contracts<br/>233 tasks owned]:::del
        B[B-ui<br/>web UX + e2e<br/>123 tasks owned]:::del
        C[C-ops<br/>observability / runbooks / platform docs<br/>50 tasks owned]:::del
    end
    subgraph REVIEW[Review lanes — gatekeep merge]
        D[D-arch<br/>architecture / contracts reviewer<br/>doc/api, doc/architecture]:::rev
        E[E-governance<br/>process / quality / security reviewer<br/>doc/governance, test/gate posture]:::rev
    end

    A & B & C -.PRs flow up.-> D
    A & B & C -.PRs flow up.-> E
    D -.reviews each other.-> E
    E -.reviews each other.-> D

Per-lane worktree topology

Each delivery lane works in its own git worktree on its own branch. Worktrees share the same .git but have separate working directories — so two agents can edit the same file at the same time without colliding.

flowchart LR
    classDef wt fill:#fff3e0,stroke:#e65100
    classDef branch fill:#e3f2fd,stroke:#1565c0
    classDef shared fill:#eceff1,stroke:#455a64

    GIT[(.git repository<br/>shared object store)]:::shared
    M[master branch]:::branch

    GIT --> WTA[worktree:<br/>.claude/worktrees/A-backend/]:::wt
    GIT --> WTB[worktree:<br/>.claude/worktrees/B-ui/]:::wt
    GIT --> WTC[worktree:<br/>.claude/worktrees/C-ops/]:::wt

    WTA --> BR_A[agent/A-backend branch]:::branch
    WTB --> BR_B[agent/B-ui branch]:::branch
    WTC --> BR_C[agent/C-ops branch]:::branch

    BR_A -.PR.-> M
    BR_B -.PR.-> M
    BR_C -.PR.-> M

Why worktrees instead of separate clones

flowchart TB
    Q[Why git worktrees and not separate clones?]
    Q --> R1[Single .git object store<br/>→ commits visible across worktrees]
    Q --> R2[No re-fetch latency on switch]
    Q --> R3[Sharing avoids 'lost branch'<br/>between clone instances]
    Q --> R4[Lane work doesn't pollute the main checkout]
    Q --> R5[Coordinator can list active worktrees<br/>and detect orphans]

    classDef ok fill:#d1e7dd,stroke:#0a3622
    class R1,R2,R3,R4,R5 ok

Typical commands:

# coordinator sets up lane worktrees once
git worktree add .claude/worktrees/A-backend agent/A-backend
git worktree add .claude/worktrees/B-ui      agent/B-ui
git worktree add .claude/worktrees/C-ops     agent/C-ops

# coordinator lists what's active
git worktree list

# agent enters its lane
cd .claude/worktrees/A-backend
make queue-claim ID=A-PROV-SCHED-001 OWNER=A
# ... work ...
make queue-set-status ID=A-PROV-SCHED-001 STATUS=done COMMIT=$(git rev-parse HEAD)

# coordinator prunes finished worktrees
git worktree prune

Independence rules

flowchart LR
    classDef rule fill:#fff3cd,stroke:#332701

    R1[A lane must NOT self-approve<br/>its own critical changes]:::rule
    R2[D-arch and E-governance<br/>must review each other]:::rule
    R3[Prefer cross-engine review diversity<br/>implementation by one model,<br/>review by another]:::rule
    R4[Same-model exception must be<br/>documented in task handoff]:::rule

The "cross-model" preference is unusual but explicit. If one model implements something, a different model reviews it. When the same model has to do both, it's documented as an exception so future audits can find it.

Merge gate scope

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

    PR[PR opened from agent/<lane>] --> CHK1{reviewguard<br/>policy check}
    CHK1 -- fail --> BLOCK[Block PR]:::block
    CHK1 -- pass --> CHK2{scripts/ci/*.sh<br/>all green}
    CHK2 -- fail --> BLOCK
    CHK2 -- pass --> CHK3{Cross-lane reviewers<br/>assigned + approved}
    CHK3 -- fail --> BLOCK
    CHK3 -- pass --> CHK4{Acceptance checks<br/>from task notes pass}
    CHK4 -- fail --> BLOCK
    CHK4 -- pass --> MERGE[Merge to master]:::ok
    MERGE --> Q[Queue task → done<br/>commit + completed_at recorded]:::ok

Conflict avoidance

flowchart LR
    Q[Two agents want to edit<br/>the same file] --> CASE{Same task or<br/>different tasks?}
    CASE -- same task --> S1[Impossible: queue-claim is atomic;<br/>only one owner at a time]
    CASE -- different tasks --> S2[Different worktrees,<br/>different branches]
    S2 --> S3[Each agent commits in its branch]
    S3 --> S4[Rebase / merge<br/>resolved at PR time]
    S4 --> S5[reviewer mediates if both<br/>changes are correct]
    S4 --> S6[CI catches semantic conflicts<br/>tests + integration]

    classDef ok fill:#d1e7dd,stroke:#0a3622
    class S1,S2,S5,S6 ok

Release branch protection

The release/platform-control branch has its own promotion policy. From AGENTS.md:

Before any release/platform-control promotion or deploy work, read Platform_Control_Release_Promotion_Policy.md and Multi_Agent_Lane_Worktrees_v1.md.

Hard rules:

Allowed Forbidden
Merge fixes to master first, then promote Hand-edit release/platform-control as a normal workflow
Use scripts/ci/platform_control_promote_release_branch.sh Direct branch push
Audit signoff before deploy Skip-hook commits
Lane worktree for promotion work Mixing promotion + feature work in one worktree 
sequenceDiagram
    autonumber
    participant DEV as Lane (any)
    participant M as master
    participant P as platform-control-promotion worktree
    participant REL as release/platform-control
    participant SCR as promote script

    DEV->>M: merge feature PR to master
    Note over P: Promotion is its own worktree
    P->>SCR: run platform_control_promote_release_branch.sh
    SCR->>REL: rebuild release branch from master HEAD<br/>cherry-pick only approved changes
    SCR->>SCR: enforce signoff policy<br/>(architecture + security + ops)
    SCR-->>REL: promoted
    REL-->>DEV: deploy pipeline triggers

How a lane gets onboarded

flowchart TB
    NEW[New lane needed e.g. D-arch] --> CFG[Add lane to<br/>Multi_Agent_Lane_Worktrees_v1.md]
    CFG --> POL[Add lane to<br/>roles in Agent_Work_Queue.yaml]
    POL --> SP[Add startup prompt to<br/>Agent_Startup_Prompts.md]
    SP --> WT[Create worktree:<br/>git worktree add .claude/worktrees/D-arch agent/D-arch]
    WT --> RG[Update reviewguard policy<br/>if lane has special merge rules]
    RG --> READY[Lane is operational]

    classDef ready fill:#d1e7dd,stroke:#0a3622
    class READY ready

Where to look next