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.

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

Task States

Every task moves through a defined lifecycle:

Inbox → Assigned → In Progress → Review → Done | Failed

Rules:

• Orchestrator owns state transitions — don't rely on agents to update their own status
• Every transition gets a comment (who, what, why)
• Failed is a valid end state — capture why and move on

→ Read references/task-lifecycle.md when designing task flows or debugging stuck tasks.

Handoffs

When work passes between agents, the handoff message includes:

1. What was done — summary of changes/output
2. Where artifacts are — exact file paths
3. How to verify — test commands or acceptance criteria
4. Known issues — anything incomplete or risky
5. What's next — clear next action for the receiving agent

Bad handoff: "Done, check the files." Good handoff: "Built auth module at /shared/artifacts/auth/. Run npm test auth to verify. Known issue: rate limiting not implemented yet. Next: reviewer checks error handling edge cases."

Reviews

Cross-role reviews prevent quality drift:

• Builders review specs — "Is this feasible? What's missing?"
• Reviewers check builds — "Does this match the spec? Edge cases?"
• Orchestrator reviews priorities — "Is this the right work right now?"

Skip the review step and quality degrades within 3-5 tasks. Every time.