Agent Team Orchestration

Production playbook for running multi-agent teams with clear roles, structured task flow, and quality gates.

Quick Start: Minimal 2-Agent Team

A builder and a reviewer. The simplest useful team.

1. Define Roles

Orchestrator (you) — Route tasks, track state, report results
Builder agent     — Execute work, produce artifacts

2. Spawn a Task

1. Create task record (file, DB, or task board)
2. Spawn builder with:
   - Task ID and description
   - Output path for artifacts
   - Handoff instructions (what to produce, where to put it)
3. On completion: review artifacts, mark done, report

3. Add a Reviewer

Builder produces artifact → Reviewer checks it → Orchestrator ships or returns

That's the core loop. Everything below scales this pattern.

Core Concepts

Roles

Every agent has one primary role. Overlap causes confusion.

Role	Purpose	Model guidance
Orchestrator	Route work, track state, make priority calls	High-reasoning model (handles judgment)
Builder	Produce artifacts — code, docs, configs	Can use cost-effective models for mechanical work
Reviewer	Verify quality, push back on gaps	High-reasoning model (catches what builders miss)
Ops	Cron jobs, standups, health checks, dispatching	Cheapest model that's reliable

→ Read references/team-setup.md when defining a new team or adding agents.

Task States

Every task moves through a defined lifecycle: