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
CODEBLOCK0
2. Spawn a Task
CODEBLOCK1
3. Add a Reviewer
CODEBLOCK2
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:
CODEBLOCK3
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
- Where artifacts are — exact file paths
- How to verify — test commands or acceptance criteria
- Known issues — anything incomplete or risky
- 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.
→ Read references/communication.md when setting up agent communication channels.
→ Read references/patterns.md for proven multi-step workflows.
Reference Files
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) |
Common Pitfalls
Spawning without clear artifact output paths
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.
No review step = quality drift
"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.
Agents not commenting on task progress
Silent agents create coordination blind spots. Require comments at: start, blocker, handoff, completion. If an agent goes silent, assume it's stuck.
Not verifying agent capabilities before assigning
Assigning browser-based testing to an agent without browser access. Assigning image work to a text-only model. Check capabilities before routing.
Orchestrator doing execution work
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.
When NOT to Use This Skill
- - Single-agent setups — Just follow standard AGENTS.md conventions. Team orchestration adds overhead that solo agents don't need.
- One-off task delegation — Use
sessions_spawn directly. This skill is for sustained workflows with multiple handoffs. - Simple question routing — If you're just forwarding a question to a specialist, that's a message, not a workflow.
This skill is for sustained team workflows — recurring collaboration patterns where agents depend on each other's output over multiple tasks.
智能体团队编排
多智能体团队运行的生产手册，包含明确的角色分工、结构化任务流程和质量关卡。
快速入门：最小化双智能体团队
一个构建者加一个审查者。最简单的实用团队。
1. 定义角色
编排者（你）—— 分配任务、跟踪状态、汇报结果
构建智能体 —— 执行工作、产出制品
2. 生成任务
- 1. 创建任务记录（文件、数据库或任务看板）
- 生成构建智能体，附带：
- 任务ID和描述
- 制品输出路径
- 交接说明（产出什么、放在哪里）
- 3. 完成后：审查制品、标记完成、汇报结果
3. 添加审查者
构建智能体产出制品 → 审查者检查制品 → 编排者交付或退回
这就是核心循环。以下所有内容都是对该模式的扩展。
核心概念
角色
每个智能体只有一个主要角色。角色重叠会导致混乱。
| 角色 | 目的 | 模型指导 |
|---|
| 编排者 | 分配工作、跟踪状态、做出优先级决策 | 高推理模型（负责判断） |
| 构建者 |
产出制品——代码、文档、配置 | 可使用经济型模型处理机械性工作 |
|
审查者 | 验证质量、指出不足 | 高推理模型（发现构建者遗漏的问题） |
|
运维 | 定时任务、站会、健康检查、任务分派 | 最可靠的经济型模型 |
→ 定义新团队或添加智能体时，请阅读 references/team-setup.md。
任务状态
每个任务都经历定义好的生命周期：
收件箱 → 已分配 → 进行中 → 审查中 → 已完成 | 失败
规则：
- - 编排者负责状态转换——不要依赖智能体自行更新状态
- 每次转换都要添加备注（谁、做了什么、为什么）
- 失败是有效的最终状态——记录失败原因并继续推进
→ 设计任务流程或调试卡住的任务时，请阅读 references/task-lifecycle.md。
交接
当工作在智能体之间传递时，交接消息包含：
- 1. 已完成的工作 —— 变更/输出的摘要
- 制品位置 —— 确切的文件路径
- 验证方法 —— 测试命令或验收标准
- 已知问题 —— 任何不完整或有风险的内容
- 下一步工作 —— 接收智能体明确的下一步行动
糟糕的交接：已完成，检查文件。
良好的交接：已构建认证模块，位于 /shared/artifacts/auth/。运行 npm test auth 进行验证。已知问题：速率限制尚未实现。下一步：审查者检查错误处理的边界情况。
审查
跨角色审查可防止质量下滑：
- - 构建者审查规格说明 —— 这可行吗？缺少什么？
- 审查者检查构建成果 —— 这符合规格说明吗？边界情况呢？
- 编排者审查优先级 —— 现在做这个工作对吗？
跳过审查步骤，质量会在3-5个任务内下降。每次都是如此。
→ 设置智能体通信渠道时，请阅读 references/communication.md。
→ 获取经过验证的多步骤工作流程，请阅读 references/patterns.md。
参考文件
设计任务状态、转换、备注 |
|
communication.md | 设置异步/同步通信、制品路径 |
|
patterns.md | 实现特定工作流程（规格→构建→测试、并行研究、升级处理） |
常见陷阱
生成任务时未指定清晰的制品输出路径
智能体产出优秀成果，但你找不到它。始终在生成提示中指定确切的输出路径。使用具有可预测结构的共享制品目录。
没有审查步骤 = 质量下滑
这只是个小改动，跳过审查。这样做三次，你就会遇到累积错误。每个制品至少要有非产出者的一双眼睛检查。
智能体不备注任务进度
沉默的智能体会造成协调盲点。要求在以下节点添加备注：开始、遇到阻碍、交接、完成。如果智能体保持沉默，假设它卡住了。
分配任务前未验证智能体能力
将基于浏览器的测试分配给没有浏览器访问权限的智能体。将图像工作分配给纯文本模型。在分配任务前检查能力。
编排者执行具体工作
编排者负责分配和跟踪——不负责构建。当你开始只是快速做这一件事时，你就失去了对团队其他成员的监督。
何时不使用此技能
- - 单智能体设置 —— 只需遵循标准的 AGENTS.md 约定。团队编排带来的开销是单智能体不需要的。
- 一次性任务委派 —— 直接使用 sessions_spawn。此技能适用于需要多次交接的持续工作流程。
- 简单问题转发 —— 如果你只是将问题转发给专家，那是一条消息，而不是一个工作流程。
此技能适用于持续的团队工作流程 —— 智能体在多个任务中依赖彼此输出的重复协作模式。
