Skip to content

MULTI_ORCHESTRATOR.md

Latest commit

 

History

History
211 lines (149 loc) · 5.45 KB

MULTI_ORCHESTRATOR.md

File metadata and controls

211 lines (149 loc) · 5.45 KB

Multi-Orchestrator Coordination System

The Problem

You have multiple VS Code windows running Roo Code orchestrators. Without coordination:

  • Multiple orchestrators try to build at the same time → file locks, wasted CPU
  • Multiple orchestrators fix the same code → conflicts, overwritten work
  • No visibility into what each orchestrator is doing → chaos

The Solution

A single markdown file that all orchestrators read and write to coordinate:

.ralph/scratchpads/master_coordination.md

This file contains:

  • Build Lock - Who's running cmake
  • Active Orchestrators - Who's online
  • Task Queue - What needs to be done
  • File Locks - Who's editing what

How It Works

1. Orchestrator Startup

Every orchestrator does this on startup:

1. Generate unique ID: orch-<HHMM>-<random4>
   Example: orch-1430-7842

2. Read master_coordination.md

3. Add self to "Active Orchestrators" table:
   | orch-1430-7842 | Active | - | 2026-01-21T14:30:00Z |

4. Check "Build Lock" - is someone building?

5. Find unclaimed task (Claimed By = "-")

6. Write ID to claim it:
   | T003 | 2 | Fix physics | physics | orch-1430-7842 |

7. Move task to "In Progress" table

8. Begin work

2. First-Write-Wins

When two orchestrators try to claim the same task:

  • Orchestrator A reads task, sees Claimed By = "-"
  • Orchestrator B reads task, sees Claimed By = "-"
  • Orchestrator A writes their ID
  • Orchestrator B writes their ID (overwrites A)
  • B wins, A needs to pick a different task

In practice, with proper sequencing (read → claim → move), conflicts are rare.

3. Build Lock

## 🔒 Build Lock

| Field | Value |
|-------|-------|
| **Locked By** | orch-1430-7842 |
| **Locked At** | 2026-01-21T14:30:00Z |
| **Expires** | 2026-01-21T14:40:00Z |
  • Only one orchestrator builds at a time
  • 10-minute expiration prevents stale locks
  • Release lock immediately when done

4. File Locks

## 🔐 File Locks

| File Path | Locked By | Since |
|-----------|-----------|-------|
| src/physics/collision.cpp | orch-1430-7842 | 2026-01-21T14:32:00Z |
  • Lock before editing source files
  • Unlock when done
  • Stale locks (>5 min) can be broken

Setup

Step 1: Copy the Template

cp multi_orchestrator/master_coordination_template.md .ralph/scratchpads/master_coordination.md

Step 2: Update Your .roomodes

Add the coordination instructions to your orchestrator's roleDefinition. See orchestrator_instructions.md.

Step 3: Sync to All Profiles

.\multi_orchestrator\sync_profiles.ps1 -Source ".\.roomodes" -AgentCount 20

Step 4: Generate Launch Scripts

.\multi_orchestrator\generate_launch_scripts.ps1 -Workspace "C:\YourProject" -AgentCount 10

Step 5: Launch Orchestrators

Double-click Launch-Agent-1.bat, Launch-Agent-2.bat, etc.

In each window:

  1. Open Roo Code
  2. Select Orchestrator mode
  3. Type "Go"

Example Session

14:30:00 - Window 1 (agent1)
  └─ Generates ID: orch-1430-7842
  └─ Claims T001 (build task)
  └─ Acquires build lock
  └─ Running cmake...

14:30:05 - Window 2 (agent2)
  └─ Generates ID: orch-1430-5931
  └─ Sees T001 claimed by orch-1430-7842
  └─ Sees build lock taken
  └─ Claims T002 (docs task)
  └─ Working on docs...

14:30:10 - Window 3 (agent3)
  └─ Generates ID: orch-1430-2847
  └─ Sees T001, T002 claimed
  └─ Claims T003 (testing task)
  └─ Running tests...

14:32:00 - Window 1 completes build
  └─ Releases build lock
  └─ Claims T004 (world data)

14:32:05 - Window 4 (agent4) starts
  └─ Generates ID: orch-1432-9183
  └─ Sees build lock available!
  └─ Claims T005 (build-related task)
  └─ Acquires build lock

All four work in parallel without stepping on each other!

Troubleshooting

Orchestrators Not Registering

  1. Check that .roomodes has the coordination instructions
  2. Run sync_profiles.ps1 to copy to all profiles
  3. Start a new task in Roo Code (changes don't apply mid-conversation)

Stale Build Lock

If an orchestrator crashes while holding the build lock:

  1. Open master_coordination.md
  2. Set "Locked By" to none
  3. Clear "Locked At" and "Expires"

Task Conflicts

If two orchestrators claim the same task:

  • The second one wins (overwrites the first)
  • First orchestrator should notice on next read and pick a different task

Profiles Not Syncing

Make sure the profile directory exists:

Test-Path "C:\VsCodeAgents\agent1\User\globalStorage\rooveterinaryinc.roo-cline\settings"

If not, launch VS Code with that profile first to create it:

code --user-data-dir "C:\VsCodeAgents\agent1" "C:\YourProject"

Why Not Use a Database?

This system uses a single markdown file instead of a database because:

  1. Simplicity - No setup, no dependencies
  2. Transparency - You can read the file and see exactly what's happening
  3. Debugging - Easy to manually edit if something goes wrong
  4. Git-friendly - Can be committed and tracked
  5. AI-native - LLMs can read/write markdown naturally

Files

File Purpose
master_coordination_template.md Template to copy to your project
orchestrator_instructions.md Instructions to add to .roomodes
sync_profiles.ps1 Copy .roomodes to all agent profiles
generate_launch_scripts.ps1 Create Launch-Agent-N.bat files
Launch-Agent.bat Generic launcher (pass agent number)