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 & Physical Strike (Justin Protocol)
When work passes between agents or to the physical strike layer (Justin), the protocol is:
- 1. What was done — summary of changes/output.
- Where artifacts are — exact file paths (Default:
E:\clawd_workspace\Share\artifacts\). - Physical Strike (Justin) — The Main Agent (Justin) is the SOLE physical executor.
- Header Double-Check — BEFORE hitting Enter, Justin MUST verify the browser tab/group header matches the target (e.g., "MK守约-粉丝群").
- Audit — After Enter, Justin MUST take a snapshot to verify the blue bubble appeared in the correct chat.
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。
交接与物理执行（Justin协议）
当工作在智能体之间传递或传递到物理执行层（Justin）时，协议如下：
- 1. 已完成的工作——变更/输出的摘要。
- 制品所在位置——确切的文件路径（默认：E:\clawd_workspace\Share\artifacts\）。
- 物理执行（Justin）——主智能体（Justin）是唯一的物理执行者。
- 标题双重确认——在按下回车键之前，Justin必须验证浏览器标签页/组标题与目标匹配（例如，MK守约-粉丝群）。
- 审计——按下回车键后，Justin必须截图确认蓝色气泡出现在正确的聊天中。
审查
跨角色审查可防止质量下滑：
- - 构建者审查规格——这可行吗？缺少什么？
- 审查者检查构建——这符合规格吗？边界情况呢？
- 编排者审查优先级——现在做这个工作对吗？
跳过审查步骤，质量会在3-5个任务内下降。每次都如此。
→ 设置智能体通信渠道时，请阅读 references/communication.md。
→ 对于经过验证的多步骤工作流程，请阅读 references/patterns.md。
参考文件
设计任务状态、转换、备注 |
|
communication.md | 设置异步/同步通信、制品路径 |
|
patterns.md | 实现特定工作流程（规格→构建→测试、并行研究、升级处理） |
常见陷阱
生成任务时未明确制品输出路径
智能体产出优秀成果，但你找不到它。始终在生成提示中指定确切的输出路径。使用具有可预测结构的共享制品目录。
无审查步骤 = 质量下滑
这只是个小改动，跳过审查。这样做三次，你就会累积错误。每个制品至少要有非产出者的另一双眼睛检查。
智能体不备注任务进度
沉默的智能体会造成协调盲区。要求在以下节点添加备注：开始、遇到阻碍、交接、完成。如果智能体保持沉默，假设它卡住了。
分配任务前未验证智能体能力
将基于浏览器的测试分配给没有浏览器访问权限的智能体。将图像工作分配给纯文本模型。在分配前检查能力。
编排者执行具体工作
编排者负责分配和跟踪——而不是构建。一旦你开始就快速做这一件事，你就失去了对团队其他成员的监督。
何时不使用此技能
- - 单智能体设置——只需遵循标准的AGENTS.md约定。团队编排会增加单智能体不需要的额外开销。
- 一次性任务委派——直接使用 sessions_spawn。此技能适用于具有多次交接的持续工作流程。
- 简单问题转发——如果你只是将问题转发给专家，那是一条消息，而不是一个工作流程。
此技能适用于持续的团队工作流程——智能体在多个任务中依赖彼此输出的重复协作模式。
