/agent-teams-playbook

name: agent-teams-playbook
metadata:
  version: "4.8.0"
description: |
  Cross-runtime playbook for multi-agent collaboration, agent teams, swarm orchestration, parallel task distribution, capability discovery, and quality gates on Claude Code, Codex, OpenClaw, and Cursor. Use for 多agent、agent协作、agent编排、并行agent、分工协作、拉团队、多代理协作 or complex work needing independent roles and review. Map the six-stage workflow to the active host's actual capabilities; report sequential degradation when parallel agents are unavailable.

Agent Teams 编排手册

本 Skill 为调用方提供多 Agent 分工、执行和质量检查建议。宿主协调器负责角色边界、过程与最终交付；在 Meta_Kim 中，Router、跨组件状态机和最终验收仍由 Meta_Kim 负责，本包不接管这些职责。

> **核心理解（铁律）**：Agent Teams 是"并行处理 + 结果汇总"模式，不是扩大单个 agent 的上下文窗口。每个 teammate 是独立的执行单元，拥有独立上下文，可以并行处理大量信息，但最终需要将结果汇总压缩后返回主会话。

跨平台兼容层（新增，不替代原流程）

本 Skill 的完整 6 阶段工作流、按需能力解析、Agent → Skill 委派模式、质量把关和故障处理规则仍然保留。四个平台的差异只影响"用什么工具执行"，不影响"是否执行这些阶段"。

先识别当前平台，再把下列抽象动作映射到平台原生能力。不要在非 Claude Code 平台原样承诺 `Task`、`TeamCreate`、`SendMessage` 或 `Skill(...)` 一定存在；也不要因为平台工具名不同而跳过阶段0-5。

| 抽象动作 | Claude Code | Codex | OpenClaw | Cursor | |------|------|------|------|------| | 调用 Skill | `Skill(skill="name", args="...")` 或 slash skill | 读取并遵循本地 skill 指令；只有宿主暴露 skill 工具时才称为"调用" | 读取并遵循 `openclaw/skills` 或全局 skill；按 OpenClaw 当前工具执行 | 读取并遵循 `.cursor/skills` 或全局 skill；按 Cursor 当前 agent 能力执行 | | 启动独立 Subagent | 使用宿主当前暴露的 `Agent` / `Task`，至少携带必填 `prompt`，并按当前 schema 提供 `subagent_type`、`description`/`name` 和边界 | 使用当前宿主暴露的原生 spawn schema（见下方 profiles） | workspace / agent 调度能力；不可用则主线程分阶段执行 | background agent / agent mode；不可用则主线程分阶段执行 | | 组建 Agent Team | 宿主暴露时使用 `TeamCreate` + `Agent` / `Task(team_name)` | 同一轮并发调用多个宿主原生 spawn 调用，由主线程汇总；不伪装共享团队总线 | team / workspace 能力存在时使用；否则多个任务或主线程 | background agents / team-like workflow 存在时使用；否则多个任务或主线程 | | 成员通信/进度 | `SendMessage` 或 Agent/Task result | 子任务结果回报；只有宿主暴露 agent I/O 时才中途通信 | 平台消息/日志；不可用时用阶段性文本汇报 | IDE/agent 日志；不可用时用阶段性文本汇报 | | 规划文件 | `planning-with-files` skill | 若本地 skill/tool 存在则使用；否则使用内联计划或平台计划工具 | 若本地 planning skill 存在则使用；否则维护可见计划记录 | 若本地 planning skill 存在则使用；否则维护可见计划记录 |

**平台适配底线**： 1. 写计划时使用抽象动作名；执行时使用当前平台真实工具名。 2. Claude Code 使用宿主当前暴露的 `Agent` / `Task`；只有宿主确实暴露 `TeamCreate` / `SendMessage` 时才承诺共享团队语义。不要把 Codex 参数复制到 Claude Code。 3. Codex 以当前宿主实际暴露的工具 schema 和权限为准，再选择匹配的 profile；不能只凭产品名或版本猜参数。只有工具调用成功且有返回的 Agent 标识，才报告已启动。 4. OpenClaw/Cursor 的 team 能力可能来自项目插件、workspace 或 IDE 能力；先探测，再承诺。 5. 若平台不支持真正并行或团队通信，明确降级为"主线程分阶段执行"，但仍执行阶段0-5的治理流程。

Codex 宿主 profiles（薄适配）

当前宿主 schema 优先于以下已知示例。先读取工具名、必填字段、可选字段、返回标识、并发与通信权限；只提交当前 schema 允许的字段。宿主未暴露工具时不要猜名字，也不要为适配自行实现执行引擎。`agent_type`、`model`、`reasoning_effort` 可能受 feature flags 隐藏；即便暴露，也要遵循宿主的选择/继承规则，不自动覆盖。

• **codex-v1**：已知上游 namespace 为 `multi_agent_v1.spawn_agent`，任务用 `message` 或 `items`，历史继承用布尔 `fork_context`；`agent_type` 仅在当前 schema 暴露并允许选择时可用。
• **codex-v2**：已知上游顶层 `spawn_agent` 必填 `task_name` 和 `message`，历史继承用字符串 `fork_turns`（`none`、`all` 或正整数字符串）；不能向它传 V1 的 `fork_context`。
• **codex-v2-limited**：工具名和必填字段同 V2，但宿主可隐藏 `agent_type`、`model`、`reasoning_effort`；不能照搬其他 profile 的可选字段。
• **no-capability**：没有可用 spawn，或权限不允许并发时，明确采用主线程分阶段执行，仍保留阶段0-5；不得报告真实并行、团队通信或子 Agent 成功。通信工具也必须单独探测。

以下最小调用样例只展示静态协议，不承诺真实宿主已实测。测试夹具验证文档与已知 schema 的一致性；新的宿主 schema 有差异时，以现场发现为准并记录差异。

<!-- contract: codex-v1 -->

{"tool":"multi_agent_v1.spawn_agent","arguments":{"message":"Review the bounded task and return evidence.","fork_context":false}}

<!-- contract: codex-v2 -->

{"tool":"spawn_agent","arguments":{"task_name":"review_task","message":"Review the bounded task and return evidence.","fork_turns":"none"}}

<!-- contract: codex-v2-limited -->

{"tool":"spawn_agent","arguments":{"task_name":"review_task","message":"Review the bounded task and return evidence."}}

<!-- contract: no-capability -->

{"tool":null,"arguments":null,"mode":"sequential","parallel":false}

参考：[OpenAI Codex schema 快照](https://github.com/openai/codex/blob/ca466061d64f0b44f416135c7fd06aa7af850bbc/codex-rs/core/src/tools/handlers/multi_agents_spec.rs)（2026-10-02 核验，V1/V2 与字段开关并存）；[Agent Skills 格式规范](https://agentskills.io/specification)（自定义版本放在 `metadata.version`，包事实以 `capability.json` 为准）。

适用 vs 不适用

| 适用 | 不适用 | |------|--------| | 跨文件重构、多维度审查 | 单文件小修改 | | 大规模代码生成、并行处理 | 简单问答、线性顺序任务 | | 需要多角色协作的复杂任务 | 单agent可完成的任务 |

**边界处理**：用户输入模糊时，先引导明确任务再决策；任务太简单时，主动建议使用单agent而非组建团队。

用户可见性铁律

1. 每个阶段启动前输出计划，完成后输出结果 2. 子agent在后台执行，但进度必须汇报给用户 3. 任务拆分计划必须经用户确认后再执行；若宿主平台或项目指令要求直接执行，则说明采用的默认假设 4. 失败时立即通知：`❌ [角色名] 失败: [原因]`，提供重试/跳过/终止选项 5. 全部完成后输出汇总报告（见阶段5格式），并说明真实使用的平台工具和任何降级路径

场景决策树

**执行顺序**：先执行阶段0和阶段1（强制），再根据任务复杂度选择场景（影响阶段2-5）。

| 问题 | 路径 | |------|------| | Q0: 阶段1找到可完整解决任务的现有 provider（Agent / Skill / Tool）？ | 是 → 场景2 / 否 → Q1 | | Q1: 任务复杂度？ | 简单(1-2步) → 场景1 / 中等(3-5步) → 场景3 / 复杂(6+步) → Q2 | | Q2: 需要明确团队分工？ | 是 → 场景4 / 否 → 场景5 |

• 用户直接指定场景编号时,跳过决策树直接执行
• 未指定场景时，默认用**场景3（计划+评审）**
• **注意**：阶段0（规划）和阶段1（本地能力发现）是所有场景的前置步骤；外部 `find-skills` 只在本地能力确有缺口时触发

5大编排场景

| # | 场景 | 适用条件 | 核心策略 | |---|------|---------|---------| | 1 | 提示增强 | 简单任务，1-2步 | 优化单agent提示词，不拆分不组队 | | 2 | Provider直接复用 | 任务可由单个现有 Agent / Skill / Tool 完全解决 | 直接绑定已发现 provider，无需外部搜索或组建Agent Teams | | 3 | 计划+评审 | 中等/复杂任务（**默认**） | 出计划 → 用户确认 → 并行执行 → Review验收 | | 4 | Lead-Member | 需要明确团队分工 | Leader协调分配，Member并行执行，通过TaskList协同 | | 5 | 复合编排 | 复杂任务，无固定模式 | 动态组合上述场景，按阶段切换策略 |

**模型分工**（所有场景通用）：通过平台支持的模型选择能力按任务复杂度分配；Claude Code 可通过 Task 工具的 `model` 参数分配——`opus`处理复杂推理，`haiku`处理简单任务，`sonnet`处理常规任务。平台不支持模型选择时，不要写死模型承诺。

协作模式

| 模式 | 通信方式 | 适用场景 | Claude Code 启动方式 | Codex 启动方式 | OpenClaw / Cursor 启动方式 | |------|---------|---------|---------|---------|---------| | Subagent | 子agent → 主协调器单向汇报 | 并行独立任务 | 宿主当前的 `Agent` / `Task` | 当前宿主原生 spawn schema | 平台 agent/background/workspace 能力；不可用则主线程分阶段执行 | | Agent Team | 成员间可双向通信(SendMessage) | 需要协作的复杂任务 | `TeamCreate` + `Agent` / `Task(team_name)`（仅宿主暴露时） | 多个宿主原生 spawn 调用 + 主线程协调；仅在宿主暴露 agent I/O 时中途交互 | 平台 team/workspace/background-agent 能力；没有则降级 |

选择原则：任务间无依赖用Subagent（简单高效），任务间需要协调用A