agent-team-orchestrator

Agent Teams intelligent orchestration decision engine

Core decision logic

Step 1: Task characteristic analysis

After receiving the user's task,automatically perform the following 5-dimension assessment(without requiring the user to explicitly ask):

1. Parallelism dimension

✅ Suited to Teams: Multiple subtasks can be executed fully independently in parallel without needing to wait for each other's results
❌ Suited to Subagent: The task has a clear sequential order, and later steps depend on earlier results

2. Communication needs dimension

✅ Suited to Teams: Members need to share findings with each other, challenge each other's conclusions, and negotiate decisions
❌ Suited to Subagent: Only need to report results to the main Agent, with no communication needed among members

3. Context isolation dimension

✅ Suited to Teams: Each member needs to focus on a different domain to avoid context contamination
❌ Suited to Subagent: All work shares the same knowledge background and context

4. File conflict dimension

✅ Suited to Teams: Each member operates on a different file set, with no concurrent editing conflicts
❌ Suited to Subagent: Multiple people need to modify the same file (which would cause overwrite conflicts)

5. Cost-benefit dimension

✅ Suited to Teams: The value of parallel exploration > Token cost (such as research, review, new feature development)
❌ Suited to Subagent: Simple task, coordination overhead outweighs the benefit

Step 2: Decision matrix

Based on the scores of the above dimensions, apply the following rules:

Scenario type	Parallelism	Communication needs	Context isolation	File conflict	Recommended approach	Confidence
Multi-perspective code review	✓	✓	✓	✓	Agent Teams	95%
Competing-hypothesis debugging	✓	✓	✓	✓	Agent Teams	95%
Cross-layer coordinated development	✓	✓	✓	✓	Agent Teams	90%
Independent directory search	✓	✗	✓	✓	Subagent	85%
Sequential data processing	✗	✗	✗	✓	Subagent	90%
Single-file multi-person editing	✓	✗	✗	✗	Subagent	95%

Decision rules:

4-5 ✓ → Strongly recommend Agent Teams
2-3 ✓ → Decide based on task complexity
0-1 ✓ → Recommend Subagent

Team design guide

Team size recommendations

简单任务（代码审查、小型调试）: 2-3 人
中等复杂度（新功能开发）: 3-5 人
高复杂度（大型重构、架构设计）: 5-7 人
⚠️ 警告：超过 7 人协调成本急剧上升

Role assignment principles

1. Clear responsibilities

✅ Good:security-reviewer Focus only on security vulnerabilities
❌ Bad:general-reviewer Review everything (which leads to duplicated work)

2. Skill complementarity

✅ Good:frontend-dev + backend-dev + test-engineer
❌ Bad: all 3 are fullstack-dev(lack of specialization)

3. Clear file ownership

✅ Good: each member is responsible for a different directory/module
❌ Bad: multiple people modify the same file (which causes overwrite conflicts)

Task Granularity Design

Ideal Task Granularity:

Time per task: 15-30 minutes
Number of tasks per person: 5-6
Task output: a clear deliverable (a function, a test file, a report)

Tasks that are too small:

❌ "检查第 42 行是否有 bug"
❌ "读取 config.json 文件"

Tasks that are too large:

❌ "重构整个认证系统"
❌ "实现完整的订单模块"

Appropriate tasks:

✅ "审查 auth 模块的安全漏洞，输出 security-report.md"
✅ "实现用户登录 API 端点，包含参数验证和错误处理"
✅ "编写 OrderService 的单元测试，覆盖主要场景"

Prompt Template Library

Template 1: Multi-perspective Code Review

创建一个 Agent Team 来审查 PR #{pr_number}。团队成员：

1. **security-reviewer**:
   - 聚焦安全漏洞（SQL注入、XSS、CSRF、认证绕过）
   - 输出 security-findings.md

2. **performance-reviewer**:
   - 检查性能问题（N+1查询、内存泄漏、阻塞操作）
   - 输出 performance-findings.md

3. **test-reviewer**:
   - 验证测试覆盖率，检查边界用例
   - 输出 test-coverage-report.md

要求：
- 各自独立审查后，互相质疑对方发现的问题
- 达成共识后，由 Lead 综合生成最终审查报告

Template 2: Competing Hypothesis Debugging

用户报告：{bug_description}

创建 5 人调试团队，每人提出并验证一个假说：

1. **hypothesis-1**: {假说描述}
2. **hypothesis-2**: {假说描述}
3. **hypothesis-3**: {假说描述}
4. **hypothesis-4**: {假说描述}
5. **hypothesis-5**: {假说描述}

要求：
- 每人提供支持/反驳自己假说的证据
- 互相质疑对方的推理逻辑
- 通过科学辩论的方式，淘汰不成立的假说
- 最终只保留经得起质疑的根因分析

Template 3: Cross-layer Coordinated Development

实现新功能：{feature_description}

创建 Agent Team，职责划分：

1. **frontend-dev**:
   - 目录：src/pages/{feature}/, src/components/{feature}/
   - 技术栈：React 19 + TailwindCSS
   - 输出：功能页面 + 组件

2. **backend-dev**:
   - 目录：backend/src/api/{feature}/, backend/src/services/{feature}/
   - 技术栈：FastAPI + Pydantic
   - 输出：API 端点 + 业务逻辑

3. **test-engineer**:
   - 目录：tests/integration/{feature}/
   - 技术栈：pytest + httpx
   - 输出：集成测试

协调要求：
- frontend-dev 和 backend-dev 先协商 API 契约（接口定义）
- backend-dev 完成 API 后通知 frontend-dev
- test-engineer 等两人都完成后编写集成测试

Template 4: Research and Design

研究主题：{research_topic}

创建研究团队，各自从不同角度探索：

1. **ux-researcher**: 用户体验角度
2. **tech-architect**: 技术可行性角度
3. **devil-advocate**: 挑战者角色，找问题和风险

要求：
- 每人独立调研 20 分钟
- 互相分享发现，质疑彼此的结论
- devil-advocate 必须对另外两人的方案提出至少 3 个挑战
- Lead 综合后输出：推荐方案 + 风险评估 + 备选方案

Best Practices Checklist

✅ Before Creating a Team

Confirm that the task truly requires parallel exploration rather than sequential execution
Confirm that members need to communicate with and challenge each other
Confirm that each member works on a different set of files
Confirm that the task complexity is sufficient to offset the coordination cost
Give Teammates sufficient context (they do not inherit the Lead's conversation history)

✅ While the Team Is Running

Check task progress regularly (do not let the team run unsupervised for too long)
Redirect ineffective exploration directions promptly
Encourage Teammates to challenge and discuss with each other
Monitor file conflicts and reassign tasks when necessary
Use Ctrl+T to view the task list status

✅ Cleanup After Completion

Confirm that all tasks have been completed
Synthesize the findings of each Teammate
Send shutdown requests to all Teammates
Wait for all Teammates to approve shutdown
Perform team cleanup (delete ~/.claude/teams/ and ~/.claude/tasks/)

Common Pitfalls and How to Avoid Them

Pitfall 1: The Lead Does the Work Itself

Symptoms: The Lead starts writing code itself without waiting for Teammates

Solution:

按 Shift+Tab 启用 Delegate 模式
或在 prompt 中明确："You are the Lead. Do NOT implement code yourself.
Only coordinate teammates, assign tasks, and synthesize results."

Pitfall 2: File Overwrite Conflicts

Symptoms: Two Teammates modify the same file, and the latter overwrites the former's changes

Solution:

设计任务时明确文件所有权：
- Teammate A: src/api/users.py
- Teammate B: src/api/orders.py
- Teammate C: tests/
禁止交叉修改

Pitfall 3: Inappropriate Task Granularity

Symptoms: Tasks are too small (high coordination overhead) or too large (long execution time)

Solution:

理想粒度：15-30 分钟/任务
每人 5-6 个任务
产出明确的交付物

Pitfall 4: Lack of Context

Symptoms: Teammates do not know what to do and ask frequently

Solution:

在 spawn prompt 中包含：
- 具体文件路径
- 技术栈说明
- 期望产出格式
- 相关领域知识

❌ "Spawn a reviewer"
✅ "Spawn a security-reviewer to audit src/api/auth.py, focusing on
    JWT token validation and SQL injection. Output security-report.md."

Pitfall 5: Premature Cleanup

Symptoms: Attempting to clean up the team while Teammates are still running

Solution:

清理顺序：
1. 所有任务完成 → 2. 发送关闭请求 → 3. 等待批准 → 4. 执行清理

如果有 Teammate 拒绝关闭，检查是否有未完成的工作

Output Format Specification

When Deciding to Use Agent Teams

Output template:

📊 **任务分析**
- 并行性: ✓ (多个子任务可独立执行)
- 通信需求: ✓ (成员需互相质疑)
- 上下文隔离: ✓ (各自聚焦不同领域)
- 文件冲突: ✓ (无并发编辑)
- 成本收益: ✓ (研究价值 > Token 成本)

✅ **推荐方案**: Agent Teams (置信度 95%)

🎯 **团队设计**
- 团队规模: {N} 人
- 角色分配:
  1. {role-1}: {职责描述}
  2. {role-2}: {职责描述}
  ...

📝 **生成 Prompt**
{根据场景生成的具体 prompt}

⚠️ **注意事项**
- {关键风险点 1}
- {关键风险点 2}

When Deciding to Use Subagent

Output template:

📊 **任务分析**
- 并行性: ✗ (有明确的执行顺序)
- 通信需求: ✗ (只需报告结果)
...

✅ **推荐方案**: Subagent (置信度 90%)

💡 **理由**: {简要说明为什么 Subagent 更合适}

继续用标准的 Task tool 执行任务...

Quick Reference Card

When to use Agent Teams?

✓ 多角度并行审查
✓ 竞争假说调试
✓ 跨层协调开发（前端/后端/测试）
✓ 研究与设计探索
✓ 成员需要互相质疑和讨论

When to use Subagent?

✓ 只需要结果的聚焦搜索
✓ 顺序执行的任务流
✓ 简单的并行查询（无需通信）
✓ 单文件编辑
✓ 协调成本 > 并行收益

Team Creation Process

1. 分析任务特征（自动）
2. 设计团队结构
3. 生成 spawn prompt
4. 创建团队 (TeamCreate)
5. 监控进度
6. 综合结果
7. 关闭 Teammates
8. 清理团队资源

Key Metrics

团队规模: 2-7 人（最优 3-5 人）
任务粒度: 15-30 分钟/任务
每人任务数: 5-6 个
Token 消耗: 线性增长（N × 单人成本）

Technical Details

Storage Location

团队配置: ~/.claude/teams/{team-name}/config.json
任务列表: ~/.claude/tasks/{team-name}/

Communication Mechanism

Automatic message delivery (no polling required)
Point-to-point messages (SendMessage with recipient)
Broadcast messages (use with caution, high cost)
Idle notifications (automatically notified after a Teammate completes a round)

Permission Rules

Teammates inherit the Lead's permission settings
The mode of a Teammate can be adjusted individually after creation
Permissions for individual Teammates cannot be set at creation time

Display mode

in-process: All Teammates in the main terminal, switch with Shift+Up/Down
split panes: Each Teammate in an independent pane (requires tmux/iTerm2)
auto: Automatic selection (use split in a tmux environment, otherwise use in-process)

Diagnostics and troubleshooting

Issue: Teammates do not appear

检查项：
1. 是否启用了实验性功能？(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
2. 任务是否足够复杂？（简单任务不会创建团队）
3. In-process 模式：试试按 Shift+Down
4. Split panes 模式：确认在 tmux session 中

Issue: Teammate stops on error

解决方法：
1. 直接向该 Teammate 发消息补充指令
2. 或生成新的 Teammate 替代
3. 或调整任务分配

Issue: Lead exits early

解决方法：
在 prompt 中添加：
"Wait for all teammates to complete their tasks before finalizing."

Issue: Too many permission prompts

解决方法：
在 permission settings 中预批准常用操作：
- File read/write
- Bash execution
- Git operations

Performance optimization suggestions

Token cost control

1. 避免创建过多 Teammates（3-5 人最优）
2. 避免广播消息（成本 = N × 单条消息）
3. 任务完成后立即关闭不需要的 Teammates
4. 对简单任务使用 Subagent 而非 Teams

Execution efficiency optimization

1. 任务粒度适中（15-30 分钟）
2. 明确文件所有权，避免冲突
3. 预先定义好 API 契约（跨层开发）
4. 使用任务依赖关系（blockedBy/blocks）

Coordination cost reduction

1. 在 spawn prompt 中给足上下文
2. 角色职责清晰化
3. 减少不必要的跨 Teammate 通信
4. Lead 定期监控但不过度干预

About this skill

Core decision logic

Step 1: Task characteristic analysis

1. Parallelism dimension

2. Communication needs dimension

3. Context isolation dimension

4. File conflict dimension

5. Cost-benefit dimension

Step 2: Decision matrix

Team design guide

Team size recommendations

Role assignment principles

Task Granularity Design

Prompt Template Library

Template 1: Multi-perspective Code Review

Template 2: Competing Hypothesis Debugging

Template 3: Cross-layer Coordinated Development

Template 4: Research and Design

Best Practices Checklist

✅ Before Creating a Team

✅ While the Team Is Running

✅ Cleanup After Completion

Common Pitfalls and How to Avoid Them

Pitfall 1: The Lead Does the Work Itself

Pitfall 2: File Overwrite Conflicts

Pitfall 3: Inappropriate Task Granularity

Pitfall 4: Lack of Context

Pitfall 5: Premature Cleanup

Output Format Specification

When Deciding to Use Agent Teams

When Deciding to Use Subagent

Quick Reference Card

When to use Agent Teams?

When to use Subagent?

Team Creation Process

Key Metrics

Technical Details

Storage Location

Communication Mechanism

Permission Rules

Display mode

Diagnostics and troubleshooting

Issue: Teammates do not appear

Issue: Teammate stops on error

Issue: Lead exits early

Issue: Too many permission prompts

Performance optimization suggestions

Token cost control

Execution efficiency optimization

Coordination cost reduction