agent-team-orchestration

通过定义的角色、任务生命周期、移交协议和审核工作流程来协调多代理团队。在以下情况下使用：(1) 建立由 2 个以上具有不同专业知识的代理组成的团队，(2) 定义任务路由和生命周期（收件箱 → 规范 → 构建 → 审核 → 完成），(3) 在代理之间创建移交协议，(4) 建立审核和质量门控，(5) 管理代理之间的异步通信和工件共享。

# 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.

| 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](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](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.

→ *Read [references/communication.md](references/communication.md) when setting up agent communication channels.*
→ *Read [references/patterns.md](references/patterns.md) for proven multi-step workflows.*

## Reference Files

| File | Read when... |
|------|-------------|
| [team-setup.md](references/team-setup.md) | Defining agents, roles, models, workspaces |
| [task-lifecycle.md](references/task-lifecycle.md) | Designing task states, transitions, comments |
| [communication.md](references/communication.md) | Setting up async/sync communication, artifact paths |
| [patterns.md](references/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.

---

## 中文说明

# Agent Team Orchestration

用于运行多代理团队的生产手册，具有清晰的角色、结构化的任务流和质量门控。

## 快速开始：最小化 2 代理团队

一个构建者和一个审核者。最简单的实用团队。

### 1. 定义角色

```
Orchestrator (you) — Route tasks, track state, report results
Builder agent     — Execute work, produce artifacts
```

### 2. 派生任务

```
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. 添加审核者

```
Builder produces artifact → Reviewer checks it → Orchestrator ships or returns
```

这就是核心循环。下面的一切都是对这个模式的扩展。

## 核心概念

### 角色

每个代理都有一个主要角色。重叠会导致混乱。

| 角色 | 用途 | 模型指引 |
|------|---------|---------------|
| **Orchestrator** | 路由工作、跟踪状态、做出优先级决策 | 高推理模型（处理判断） |
| **Builder** | 生产产物 — 代码、文档、配置 | 机械性工作可使用成本高效的模型 |
| **Reviewer** | 验证质量、对缺口提出异议 | 高推理模型（捕捉构建者遗漏的问题） |
| **Ops** | Cron 任务、站会、健康检查、调度 | 可靠的最便宜模型 |

→ *定义新团队或添加代理时阅读 [references/team-setup.md](references/team-setup.md)。*

### 任务状态

每个任务都经过一个定义好的生命周期：

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

**规则：**
- 协调器拥有状态转换 — 不要依赖代理更新自己的状态
- 每次转换都附带注释（谁、什么、为什么）
- Failed 是一个有效的终态 — 记录原因并继续

→ *设计任务流或调试卡住的任务时阅读 [references/task-lifecycle.md](references/task-lifecycle.md)。*

### 移交

当工作在代理之间传递时，移交消息包括：

1. **完成了什么** — 变更/输出的摘要
2. **产物在哪里** — 确切的文件路径
3. **如何验证** — 测试命令或验收标准
4. **已知问题** — 任何不完整或有风险的内容
5. **下一步是什么** — 接收方代理的明确后续操作

糟糕的移交：*"完成了，检查文件吧。"*
良好的移交：*"在 `/shared/artifacts/auth/` 构建了认证模块。运行 `npm test auth` 验证。已知问题：速率限制尚未实现。下一步：审核者检查错误处理的边缘情况。"*

### 审核

跨角色审核可防止质量漂移：

- **构建者审核规范** — "这可行吗？缺少什么？"
- **审核者检查构建** — "这是否符合规范？边缘情况？"
- **协调器审核优先级** — "这是当下正确的工作吗？"

跳过审核步骤，质量会在 3-5 个任务内退化。每次都是。

→ *设置代理通信渠道时阅读 [references/communication.md](references/communication.md)。*
→ *查阅经过验证的多步工作流，参见 [references/patterns.md](references/patterns.md)。*

## 参考文件

| 文件 | 何时阅读…… |
|------|-------------|
| [team-setup.md](references/team-setup.md) | 定义代理、角色、模型、工作区 |
| [task-lifecycle.md](references/task-lifecycle.md) | 设计任务状态、转换、注释 |
| [communication.md](references/communication.md) | 设置异步/同步通信、产物路径 |
| [patterns.md](references/patterns.md) | 实现特定工作流（规范→构建→测试、并行研究、升级） |

## 常见陷阱

### 派生时未指定清晰的产物输出路径
代理产出了出色的工作，但你找不到它。始终在派生提示中指定确切的输出路径。使用具有可预测结构的共享产物目录。

### 没有审核步骤 = 质量漂移
"这是个小改动，跳过审核吧。"这样做三次，你就会有复合性错误。每个产物都至少要经过一双不是其生产者的眼睛审视。

### 代理不对任务进度发表评论
沉默的代理会造成协调盲点。要求在以下时刻评论：开始、阻碍、移交、完成。如果某个代理沉默了，假设它卡住了。

### 分配前未验证代理能力
将基于浏览器的测试分配给没有浏览器访问权限的代理。将图像工作分配给纯文本模型。路由前检查能力。

### 协调器做执行工作
协调器负责路由和跟踪 — 它不构建。一旦你开始"就快速做这一件事"，你就失去了对团队其余部分的监督。

## 何时不应使用此技能

- **单代理设置** — 只需遵循标准的 AGENTS.md 约定。团队协调增加了独立代理不需要的开销。
- **一次性任务委派** — 直接使用 `sessions_spawn`。此技能适用于具有多次移交的持续性工作流。
- **简单的问题路由** — 如果你只是将问题转发给专家，那是一条消息，而非工作流。

此技能适用于**持续性团队工作流** — 代理在多个任务中相互依赖彼此输出的循环协作模式。