| name | spawn-team |
| description | Team lead 组建 Claude Code agent team 的结构化流程。6 阶段：任务分解 → 阵容提案 (从 role_archetypes 选) → plan-mode gating → 对抗性检查 → 用户确认 → 用 Agent 工具（name 必须为 <slug>-<role>；权限模式继承 lead，不在 spawn 时单设）逐一 spawn 每个 teammate + 保存 team_recipe。Phase 5 用户确认后直接 spawn，不再额外确认。Agent 可自主调用；若当前是扁平工位，会先引导 /promote-to-team。
|
| disable-model-invocation | false |
| allowed-tools | Read Write Edit Glob Grep Agent |
| mode | interactive |
/spawn-team — 结构化组建 Agent Team
本 skill 协助 team lead 把复杂任务拆解为 team 阵容，然后用 Agent 工具（带 name 参数）逐一 spawn 每个 teammate。
⚠️ 创建 teammate 与创建 subagent 的区别：调用 Agent 工具时必须传 name 参数才能创建真正的 teammate（加入当前会话级 team、可互发消息）；缺 name 就只是普通 subagent。name 必须形如 <slug>-<role> 且全局唯一（见 Phase 3 命名规范）。
关于 team_name（CC ≥2.1.178）：不要再传 team_name——该参数已被忽略。每个 session 启动时自动创建唯一会话级 team，Agent(name=…) 自动把 teammate 并入它；teammate 退出时自动清理。
mode 字段：当前只支持 interactive。未来会加 autonomous 模式配合 /loop 实现端到端自动化，届时由更高阶模型驱动。
身份前置检查
先从对话 context 推断：如果你已经清楚自己是 team lead 还是扁平工位，直接使用该信息。
无法推断时才落地检查：
- 定位当前对话对应的工位目录
- 检查目录名是否以
_team 结尾 AND 存在 roundtable/ 子目录
当前是扁平工位
不直接执行 spawn-team 流程，而是：
- 向用户说明："我当前是扁平工位，需要先升级为 team lead 才能组建 team"
- 询问用户："我建议运行
/promote-to-team 先升级，然后我们再回来 /spawn-team。你同意吗？"
- 等待用户自然语言同意后，agent 自主调用
/promote-to-team
- 升级完成后，回到本流程的 Phase 1
当前是 team lead
直接进入 Phase 1。
Phase 1: 任务上下文收集
从对话 context 中提取用户给的任务描述。如果信息不完整，向用户补问：
- 目标：这次任务要达成什么？成功标准是什么？
- 输入：有哪些现成的文件/数据/代码/前期成果可以用？
- 输出：最终产物是什么形式？写到哪里？
- 时间：有 deadline 吗？是一次性任务还是长跑？
- 约束：什么东西不能动？什么规则必须遵守？
- 风险：你最担心哪个环节会翻车？
把回答整理成一个结构化任务描述，作为 Phase 2 的输入。
Phase 2: 任务分解
将任务拆分成可并行或有先后的子工作项。对每个子项标注：
- 类型：写代码 / 写配置 / 环境配置 / 容器构建 / 分析 / 调研 / 评审 / 对抗性质疑 / 结果汇总
- 依赖：依赖哪些其他子项先完成
- 并行性：和哪些子项可以同时跑
- 预估 context 消耗（lead 的判断）：多 / 中 / 少
关键原则（rule 12）：lead 自己不做动手工作。所有动手的子项都要交给 teammate。
Phase 3: 阵容提案
查阅以下资源：
- 通用 subagent（
resources/agents/）：tracker、investigator、reviewer、devil-advocate、git-repo-manager
- 角色原型（
resources/role_archetypes/）：coding (3) + config (2) + infra (2) + analysis (2)
- 本 team 已有的自定义 teammate（
<SELF>_team/teammates/*.md）：Tier 2 存档
根据 Phase 2 的分解结果，组成 3~5 人的 team（最多 5 人——更多会导致协调成本暴涨；如果必须超过 5，明确说明理由）。
对每个 teammate 输出：
- 角色名（
name，必须形如 <slug>-<role>、全局唯一）：
slug = 本 team 工位名去掉 _team 后缀、单 token（不含 -/_）。例：team 工位 architect_team → slug architect。role = 该 teammate 的职责短名，可含连字符。例 reviewer、plan-a-author。- 合起来：
architect-reviewer、architect-plan-a-author。
- ⚠️ 这条命名是 load-bearing：idle checkpoint hook 靠
${name%%-*}_team 从 name 反推工位（slug 必须是无连字符的单 token，hook 才能正确切出）。旧式昵称（Fixer、Tracker）只对存量 teammate 容忍，新 spawn 一律用 <slug>-<role>。
- 角色来源：
- 引用通用 subagent（Claude Code 自动加载，直接 spawn 时指定 name）
- 引用角色原型（需把原型 markdown 内容填入 spawn prompt，补入项目特定细节）
- 引用 team Tier 2 存档
- 完全原创的 inline persona
- 模型选择：
haiku（快/便宜，适合机械的轮询、小修改）/ sonnet（默认，适合大多数编码/评审）/ opus（贵，适合需要深度推理的架构设计）
- plan-mode gating：YES 则 teammate 进入 read-only plan mode 先提方案待 lead approve 再实施；NO 则直接执行
- 作用域：具体可以碰哪些文件/目录；禁区列表
- 交付物：这个 teammate 结束时要产出什么（代码 / 报告 / 配置 / 测试结果 ...）
Plan-mode gating 的决策原则
- 需要修改核心文件或多文件 refactor → YES
- 结果会影响其他 teammate 的工作 → YES
- 单文件局部修改、测试脚本、只读分析 → NO
- 对抗性审阅（devil-advocate / reviewer）→ NO（本来就是只读）
Phase 4: 对抗性检查（可选但推荐）
如果任务复杂且方向不明（例如没有现成 baseline、结果反常的调研、架构抉择），建议：
- 在 team 中加一个 devil-advocate teammate，明确指令是"找漏洞、质疑方案、列失败路径，但不否决——暴露盲点后决策权回 lead"
- 对于需要"竞争假设"的调研，可以开 2-3 个 investigator teammate 各自持不同初始假设，让它们互相挑战（注意：这会显著增加 token 消耗）
如果任务路径清晰（例如"把这个模型的 forward 重写成支持 flash-attn"），不加 devil-advocate，直接进入 Phase 5。
Phase 5: 向用户展示阵容 + 收集反馈
把完整提案展示给用户：
# Team 提案 — <任务简述>
## 任务分解
1. [子项 A] - 依赖: 无, 可并行: B
2. [子项 B] - 依赖: 无, 可并行: A
3. [子项 C] - 依赖: A, B
...
## 阵容 (N 人)
### Teammate 1: <昵称> — <来源: subagent_name / role_archetype/xxx.md>
- 模型: sonnet
- Plan-mode gating: YES (理由: ...)
- 作用域: ...
- 禁区: ...
- 交付物: ...
### Teammate 2: ...
...
## 执行流程
- 阶段 1 (并行): Teammate 1 + Teammate 2 开工
- 阶段 2 (串行): Teammate 1/2 完成后 → Teammate 3 接手
- 阶段 3 (审阅): Reviewer 审阅所有产出
你同意这个阵容吗？要调整什么（加/减 teammate、换模型、改作用域、换来源）？
迭代：根据用户反馈调整，直到用户明确同意。不要假装用户同意——守则 #11，有疑问必须问。
Phase 6: Spawn Team + 保存 Recipe
6a. 为每个 teammate 准备 spawn prompt
对 Phase 5 最终阵容中的每个 teammate，单独准备一段 prompt 字符串，包含：
你是 <昵称>，<team_name> 的 teammate。
## 角色定义
<角色原型内容 / 引用 subagent persona / 原创 inline persona>
## 当前任务
目标：<具体任务描述>
作用域：<可以操作的文件/目录>
禁区：<绝对不能动的文件/目录>
交付物：<完成时需要产出什么>
Plan-mode gating：<是/否；若是，说明批准标准>
## 协作方式
- 重要里程碑、完成通知、阻塞报告 → 写到 _agent_team_work_zone/<SELF>_team/roundtable/
frontmatter 必须包含 kind 字段（TASK / DONE / ERR）
- 需要联系其他 teammate 或 lead → 通过 Claude Code 内置 mailbox（SendMessage）
## 工位与持久化（Rule 13）
你的工位：_agent_team_work_zone/<SELF>_team/teammates/<昵称>/
lead 已初始化 5 个骨架文件（README / working-context.md / completed.md / TODO.md / commitments.md）。
进入 idle 前、收到 checkpoint 提醒时、任务完成后 → 调用 /checkpoint 更新 working-context.md。
这是你跨 session 恢复状态的唯一桥梁（Claude Code 不自动保留 teammate session）。
若你的工位 README 里有旧的完整守则区（标题匹配 `## 工作守则` 或 `## Work Rules`，且不在
<!-- TEAMMATE_RULES:START --> 标记内），用 _agent_team_work_zone/resources/teammate_rules.md
的内容替换掉那个旧守则区（从该标题起，到下一个 `## ` 同级标题之前、或文件末为止，连标题一起
替换）；否则，若你的工位 README 里没有 <!-- TEAMMATE_RULES:START --> 区块，从该文件复制该区块
追加到你自己 README 末尾（你只能改自己的文件）。
6b. 初始化每个 teammate 的工位骨架
对 Phase 5 最终版的每个 teammate，创建工位目录和 5 个骨架文件（Rule 13 规定的 teammate 自维护文件）：
路径：_agent_team_work_zone/<SELF>_team/teammates/<teammate-name>/
6c. 写入 / 更新 TEAMMATE_INFO.json
路径：_agent_team_work_zone/<SELF>_team/TEAMMATE_INFO.json
如果文件已存在（team 之前运行过 spawn-team），不覆写；而是把新成员 append 进 active_teammates。如果是第一次 spawn-team 或文件不存在，按 schema v1 初始化（见 docs/teammate_info_schema.md）。
每个新 teammate 的条目：
{
"name": "<teammate-name>",
"role_source": { "type": "...", "path": "..." },
"model": "<haiku|sonnet|opus>",
"plan_mode_gating": <true|false>,
"scope": "<作用域简述>",
"spawned_at": "<ISO8601 当前时间>",
"last_checkpoint_at": null,
"revived_count": 0,
"status": "active"
}
同时更新顶层 updated_at。
6d. 保存 team recipe 审计记录
将完整 spawn prompt + 任务上下文 + 阵容设计保存到：
_agent_team_work_zone/<SELF>_team/team_recipes/<YYYYMMDD_HHMM>_<slug>.md
格式：
---
created: YYYY-MM-DD HH:MM
lead: <SELF>
task: <一句话任务摘要>
team_size: N
mode: interactive
---
# Team Recipe: <slug>
## 任务上下文
<Phase 1 的收集结果>
## 任务分解
<Phase 2 的结果>
## 阵容
<Phase 3 + Phase 5 的最终版>
## 对抗性检查
<Phase 4 是否加了 devil-advocate / 竞争假设，为什么>
## Spawn Prompts（每个 teammate 各一段）
<Phase 6a 为每个 teammate 准备的 prompt>
## 备注
<任何值得后续 team 复用的经验>
6e. 用 Agent 工具逐一 spawn 每个 teammate
Phase 5 的用户同意是最终授权——不要再次询问，直接开始 spawn。
对每个 teammate 调用 Agent 工具：
Agent(
description="Spawn <name>: <一句话角色描述>",
subagent_type="<见下方选择规则>",
model="<haiku|sonnet|opus>", # 来自 Phase 3 决策
name="<slug>-<role>", # ← 必须有，否则只是 subagent；须为 <slug>-<role>、与工位目录名一致
prompt="<6a 中为该 teammate 准备的 prompt>"
)
CC ≥2.1.178：不传 team_name（已被忽略）。teammate 由 Agent(name=…) 自动并入当前会话级 team。
也不传 mode：teammate 的权限模式无法在 spawn 时单设，它继承 lead 当时的权限模式（详见下方「权限模式 vs teammateMode」）。
subagent_type 选择规则：
role_source.type == "subagent" → subagent_type = role_source.subagent_name（如 "tracker"、"reviewer"）role_source.type == "archetype" / "tier2" / "inline" → subagent_type = "general-purpose"（角色通过 prompt 注入）
spawn 顺序：按执行依赖顺序——可并行的 teammate 可以同时在一条消息里发出多个 Agent 调用，有先后依赖的串行调用。
spawn 完成后输出简短确认：
✅ teammates/ 工位骨架已创建（N 个 teammate × 5 文件）
✅ TEAMMATE_INFO.json 已初始化/追加（N 个 active_teammates）
✅ team_recipes/<timestamp>_<slug>.md 已保存
✅ Team spawned: <昵称1>、<昵称2>... 已就位，等待第一条任务指令
终端 / tmux 相关（仅在 spawn 报 tmux 错、或想调显示/持久化方式时看）
tmux 不是 agent team 的必需品——in-process 模式在任何终端都能跑完整 team 功能。本段仅在遇到下列报错、或你想改显示/持久化方式时才相关，正常 spawn 流程无需理会。
两个 tmux spawn 报错的含义（硬性版本/环境检查由 bootstrap.sh 负责，本 skill 不自己跑检查）：
Failed to create teammate pane: size invalid → 你在 tmux 内、但 tmux 版本太老（< 3.0）。升级 tmux ≥ 3.0（3.6a 实测 OK），或退出 tmux 改用 in-process。Could not determine current tmux pane/window → PATH 里的 tmux 与当前 session（$TMUX socket）的 tmux 不是同一个（多版本共存）。让 PATH 指向启动当前 session 的那个 tmux。- 这两个错 bootstrap 会在你进 tmux 后预先拦截并诊断——看到就重跑 bootstrap，按它的指引修。
权限模式 vs teammateMode（两个不同的东西，别混）：
- 权限模式（
default / acceptEdits / auto / plan / bypassPermissions）：控制 teammate 要不要为工具调用弹权限确认。teammate spawn 时继承 lead 当时的权限模式——官方明确 per-teammate 模式无法在 spawn 时设置（Agent(mode=…) 对 teammate 权限模式无效）。要 teammate 起手即 auto mode → 让 lead 自己处于 auto（Shift+Tab 切，或在 settings.json 设 permissions.defaultMode:"auto"，则 lead 起手 auto、teammate 继承）；spawn 后只能逐个手动改。
teammateMode（settings.json 字段）：只控制 teammate 在终端里怎么显示（分面板 vs in-process），与权限无关。
teammateMode（显示方式，settings.json 字段）：
| 值 | 行为 |
|---|
in-process | 所有 teammate 在主终端，↑↓ 选 + Enter 查看/发消息；任何终端可用。默认（自 CC v2.1.179） |
auto | 在 tmux session 内或 iTerm2 里 → 分面板；否则回落 in-process |
tmux | 启用分面板，自动探测用 tmux 还是 iTerm2 |
iterm2（CC v2.1.186+） | 显式用 iTerm2 原生分面板（需 it2 CLI） |
teammateMode 是用户级设置（~/.claude/settings.json）；也可 --teammate-mode 单会话覆盖；分面板需 tmux 或 iTerm2。- 想要分面板 → 用
auto（在 tmux/iTerm2 内）或 tmux；idle 不隐藏：每个 teammate 一个独立窗格，谁在干活、谁卡住、谁 idle 一目了然。
- 不想被拆窗格 → 用
in-process（任何终端可用，功能不打折）。别手改 settings.json——重跑 bootstrap.sh 的"显示模式选择"菜单（它写全局 ~/.claude/settings.json）。详见 docs/user_manual.md 的 tmux 部分。
注意事项
- Rule 12 贯穿全程：lead 不做动手工作；复杂任务必须组建 team 而不是一个人扛
- 最多 5 人：超过会显著增加 coordination 开销
- 对话是黑盒：用户只用自然语言和 lead 交互，
/spawn-team 被 agent 自主调起，用户不需要记命令
- Team recipe 是可复用资产：下次遇到类似任务，lead 可以先查
team_recipes/ 找类似案例
- Agent 工具必须带
name（<slug>-<role>）：缺 name 就只是普通 subagent，无法参与 team 协作；team_name 在 CC ≥2.1.178 已被忽略、不要传。Phase 5 用户同意 = 最终授权，直接调用，不二次确认
mode: interactive 标注：frontmatter 已留好位置，将来切到 autonomous 时扩展本文件的 Phase 7（启动 /loop + hook）
