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。此技能适用于需要多次交接的持续工作流。
- 简单问题转发 —— 如果你只是将问题转发给专家，那是一条消息，而不是一个工作流。
此技能适用于持续的团队工作流 —— 智能体在多个任务中依赖彼此输出的重复协作模式。
