Skip to content

Multi-Agent Lane Worktrees v1

Purpose: - Adapt the lane/worktree idea to the current GPUaaS execution model. - Keep delivery, review, and coordination isolated without conflicting with the queue or release-branch workflow. - Provide a practical bridge between the current manual coordinator loop and future orchestration automation.

Use this together with: - Multi_Agent_Execution_Playbook.md - Multi_Agent_Review_Model.md - Agent_Orchestrator_v1.md

1. Current GPUaaS lane model

Delivery lanes: - A-backend -> backend/services/contracts/workers - B-ui -> web UX/e2e - C-ops -> ops/runbooks/platform validation

Review lanes: - D-arch -> architecture/contracts review - E-governance -> governance/quality/security review

Coordinator: - the main repo checkout acts as the coordinator workspace - it owns queue review, orchestration commands, merge decisions, and promotion to release/platform-control

This is intentionally different from a generic “one branch per lane + merge to master” sketch: - master is the integration branch - release/platform-control is the deploy branch - queue state remains the work authority

2. Branch model

Persistent role branches: - agent/A-backend - agent/B-ui - agent/C-ops - agent/D-arch - agent/E-governance

Branch roles: - role branches are persistent workspaces, not deploy branches - master remains integration - release/platform-control remains promotion/deploy only

Do not use: - detached review checkouts via FETCH_HEAD - direct day-to-day work on release/platform-control

3. Directory model

The current checkout remains the coordinator workspace.

Persistent worktree directories: - gpuas-A-backend - gpuas-B-ui - gpuas-C-ops - gpuas-D-arch - gpuas-E-governance

This preserves: - filesystem isolation between lanes - persistent shell/editor state - independent uncommitted work per lane

4. Setup and launch helpers

Create the lane worktrees:

bash scripts/ops/setup_agent_lanes.sh

Launch the Zellij control-room layout:

bash scripts/ops/launch_agent_lanes.sh

The launcher uses: - the current checkout as the COORDINATOR pane - lane worktrees for delivery/review panes

5. Manual operating flow

5.1 Delivery

  1. In coordinator: 

    make orchestrator-tick

  2. Claim work explicitly: 

    make queue-claim ROLE=A-backend OWNER=agent-a BRANCH=agent/A-backend

  3. Implement in the lane worktree.

  4. Push the role branch for traceability: 

    git push -u origin agent/A-backend

5.2 Review

When review lanes are used: - D-arch reviews architecture/contract impact - E-governance reviews governance/quality/security impact

Do not review using detached FETCH_HEAD.

Recommended refresh flow inside a review lane:

git fetch origin
git rebase origin/master
git fetch origin agent/A-backend
git branch -f review/A-backend origin/agent/A-backend
git switch review/A-backend

This gives the reviewer: - a named local review branch - no detached HEAD state - a stable branch that can be reset on the next review pass

5.3 Findings

Review findings should not be dropped randomly into the repo root.

If persistent review evidence is needed, prefer a dedicated path such as: - doc/governance/reviews/

Long term, findings and sign-off should live in the structured queue/orchestrator store rather than inside the product tree.

5.4 Merge and promotion

Coordinator workspace owns: - merge to master - queue done updates - promotion to release/platform-control

Recommended sequence:

git checkout master
git pull --ff-only origin master
git merge --ff-only agent/A-backend
git push origin master

Later, when ready to deploy:

scripts/ci/platform_control_promote_release_branch.sh origin/master

Release branch policy: - release/platform-control should point to one exact source SHA that is already integrated in master. - Do not assemble release by cherry-picking individual files or hotfixing only the release branch. - CI now enforces this with scripts/ci/platform_control_release_branch_guard.sh unless a temporary override is set deliberately.

6. Why this model fits GPUaaS better than the generic sketch

It aligns with current reality: - queue-driven work assignment - persistent role branches already in governance docs - master as integration, not auto-deploy - release/platform-control as the only auto-deploy branch - review as a lane overlay, not an alternative source of work authority

It also avoids the main issues in the generic sketch: - no detached FETCH_HEAD review flow - no accidental treatment of master as the live deploy branch - no second “coordinator clone” that drifts from the real integration checkout

7. What this enables next

This lane/worktree layout is the practical first step toward coordinator automation: - tmux/zellij session startup - role-aware task assignment - review-lane routing - status inspection from one coordinator pane - eventual integration with a structured queue store

That future automation should build on: - persistent lane worktrees - queue/orchestrator authority - explicit coordinator ownership of merge and promotion

Not on ad hoc branch hopping or detached review sessions.