Orchestrate multi-agent teams with defined roles, task lifecycles, handoff protocols, and review workflows. Use when: (1) Setting up a team of 2+ agents with different specializations, (2) Defining task routing and lifecycle (inbox → spec → build → review → done), (3) Creating handoff protocols between agents, (4) Establishing review and quality gates, (5) Managing async communication and artifact sharing between agents.
Production playbook for running multi-agent teams with clear roles, structured task flow, and quality gates.
A builder and a reviewer. The simplest useful team.
Orchestrator (you) — Route tasks, track state, report results
Builder agent — Execute work, produce artifacts
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
Builder produces artifact → Reviewer checks it → Orchestrator ships or returns
That's the core loop. Everything below scales this pattern.
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.
Every task moves through a defined lifecycle:
Inbox → Assigned → In Progress → Review → Done | Failed
Rules:
→ Read references/task-lifecycle.md when designing task flows or debugging stuck tasks.
When work passes between agents, the handoff message includes:
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."
Cross-role reviews prevent quality drift:
Skip the review step and quality degrades within 3-5 tasks. Every time.
→ Read references/communication.md when setting up agent communication channels. → Read references/patterns.md for proven multi-step workflows.
| File | Read when... |
|---|---|
| team-setup.md | Defining agents, roles, models, workspaces |
| task-lifecycle.md | Designing task states, transitions, comments |
| communication.md | Setting up async/sync communication, artifact paths |
| patterns.md | Implementing specific workflows (spec→build→test, parallel research, escalation) |
Agent produces great work, but you can't find it. Always specify the exact output path in the spawn prompt. Use a shared artifacts directory with predictable structure.
"It's a small change, skip review." Do this three times and you have compounding errors. Every artifact gets at least one set of eyes that didn't produce it.
Silent agents create coordination blind spots. Require comments at: start, blocker, handoff, completion. If an agent goes silent, assume it's stuck.
Assigning browser-based testing to an agent without browser access. Assigning image work to a text-only model. Check capabilities before routing.
The orchestrator routes and tracks — it doesn't build. The moment you start "just quickly doing this one thing," you've lost oversight of the rest of the team.
sessions_spawn directly. This skill is for sustained workflows with multiple handoffs.This skill is for sustained team workflows — recurring collaboration patterns where agents depend on each other's output over multiple tasks.