Orchestrator Guide

How to coordinate multiple AI coding agents on a single project.

Overview

The Multimodel Orchestrator defines how different AI agents share work, avoid conflicts, and hand off context. In v0.1, it's a protocol specification — a set of conventions your team follows manually.

Quick Start

1. Define Roles

Edit .ai/config.yaml:

orchestrator:
  mode: "sequential"
  agents:
    - name: "planner"
      tool: "claude"
      role: "Architecture and planning"
      files: ["docs/**", "AGENTS.md", "MEMORY.md"]
      permissions: "read+write"

    - name: "builder"
      tool: "cursor"
      role: "Implementation"
      files: ["src/**", "lib/**", "tests/**"]
      permissions: "read+write"

    - name: "checker"
      tool: "codex"
      role: "Code review and testing"
      files: ["**"]
      permissions: "read-only"

2. Choose a Mode

Mode	How It Works	Best For
sequential	One agent at a time, session log between each	Solo devs switching tools
parallel	Multiple agents on different file scopes	Teams with clear boundaries
supervised	Human reviews between each agent	Critical/production code

3. Use Handoff Logs

When switching from one agent to another, the outgoing agent writes a session log:

# Handoff: planner → builder

**Timestamp:** 2026-05-30T12:00:00Z
**Agent:** Claude (planner)

## Action Summary
Designed the auth module with JWT tokens and refresh token rotation.

## Files Changed
- docs/auth-design.md (created)
- TASKS.md (updated)

## Next Steps
1. Implement /auth/login endpoint
2. Implement /auth/refresh endpoint

## Blockers
- Need to decide: Redis vs PostgreSQL for refresh token storage

Save to: .ai/session-logs/2026-05-30-planner-auth-design.md

Common Workflows

Solo Dev, Multiple Tools

Morning:  Claude (architecture) → session log
Afternoon: Cursor (implementation) → session log
Evening:  Codex (review) → session log

Pair: Human + AI

Human: writes TASKS.md with requirements
Agent: reads TASKS.md, implements, updates MEMORY.md
Human: reviews, provides feedback
Agent: iterates, writes session log

Team: Multiple Humans + Multiple AIs

Dev A + Claude: works on auth module (src/auth/**)
Dev B + Cursor: works on dashboard (src/dashboard/**)
Both: read shared MEMORY.md, coordinate via TASKS.md

Conflict Prevention

1. Define file scopes — each agent role specifies which files it can touch
2. Check before writing — agents should read TASKS.md and recent session logs first
3. Atomic tasks — each agent completes a coherent unit before handing off
4. Single writer — only one agent should modify a given file at a time

Limitations (v0.3)

• Local structural audits and templates are automated, but active daemon runtime orchestrations are not yet implemented.
• Handoff logs are structured but must be generated by agents/humans at task completion.
• Real-time model-to-model active messaging is not supported.

Roadmap

Version	Feature	Status
v0.2.0	Local CLI & stack templates	✅ Completed
v0.3.0	npm / npx dynamic installer integrations	✅ Completed
v0.4.0	Adapter automated synchronization (sync)	📋 Planned
v0.5.0	Dynamic conflict assertions & daemon tracking	📋 Planned