@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/swarm/references/agent-types.md

@@ -0,0 +1,260 @@
+# Agent 能力与角色选型
+
+> 本文件描述的是 Claude Code 当前（2.1.x 系列）的多 agent 能力。带版本号的条目表示该行为是某个版本引入或改变的，升级后请复核。
+>
+> **目录**
+> - §1 五种并行机制怎么选
+> - §2 内置 subagent 类型
+> - §3 自定义 subagent（`.claude/agents/*.md`）
+> - §4 teammate 的运行事实
+> - §5 模型与 effort
+> - §6 权限模式与继承规则
+> - §7 subagent 拿不到的工具，以及它对提示词的影响
+> - §8 隔离：worktree 与文件冲突
+> - §9 角色提示词写法
+> - §10 成本与缓存
+> - §11 来源
+
+---
+
+## §1 五种并行机制怎么选
+
+| 机制 | 谁在协调 | worker 之间能说话吗 | 适合 |
+|------|---------|------------------|------|
+| **subagent**（`Agent` 工具） | 你（主对话），派完收结果 | 不能，只把结果交回派出它的对话 | 侧任务、一次性调研、并行评审 |
+| **agent view**（`claude agents`） | 你自己，一个个看 | 不能（可用跨会话消息传递发现） | 你手上有几个独立任务想分别托管 |
+| **agent team** | lead（主会话）规划、派活、监督 | 能，`SendMessage` 直连；有 Task 工具时还共享任务清单 | 多个较长任务、需要来回协商 |
+| **动态 workflow** | 一段 JS 脚本 | 不能直接说话，但脚本能把 A 的结论喂给 B | 同一套动作跑几十上百次、要交叉验证 |
+| **projects**（claude.ai/code） | 云端 | 各自独立 thread | 跨天跨周的长期工作，机器关机也要跑 |
+
+两个打包好的用法，不用自己搭：
+
+- **`/batch` skill** — 把一个大改动拆成 5–30 个 worktree 隔离的 subagent，每个各开一个 PR。
+- **`/workflow-authoring` skill** — 帮你把一段编排写成脚本存到 `.claude/workflows/<name>.js`，之后用 `/<name>` 直接跑。
+
+### 动态 workflow 的原语与硬限制
+
+脚本体是纯 JavaScript，不能 `import()`，也不能自己读写文件或跑命令——**文件操作和命令都由 agent 做，脚本只负责编排**。
+
+| 原语 | 作用 |
+|------|------|
+| `agent(prompt, opts)` | 跑一个 subagent，返回它的结果 |
+| `parallel([...])` / `pipeline([...])` | 扇出并行 / 串成流水线 |
+| `phase(name, fn)` | 分阶段，`/workflows` 里能看到进度 |
+| `log(msg)` | 打进度 |
+| `args` | 调用时传入的参数 |
+
+限制：默认最多 16 个 agent 并发（环境变量可调到 256）；单次运行最多 1000 个 agent；单个 `parallel()`/`pipeline()` 最多 4096 项。运行中**不能问用户**——只有权限提示和用量等待会让它暂停。需要中途签字确认的，把每一段拆成独立的 workflow。
+
+触发方式：提示词里写 `ultracode`，或 `/effort ultracode`，或直接说「用 workflow 做」。`/workflows` 查看运行中的和已完成的。
+
+**判断口诀**：worker 之间要说话、要共享任务清单、要多轮往返 → agent team；同一套动作重复很多次、结果要互相校验 → workflow；只是不想让侧任务污染主对话 → 后台 subagent。
+
+---
+
+## §2 内置 subagent 类型
+
+通过 `Agent` 工具的 `subagent_type` 指定。省略 `subagent_type` 时，如果会话里没有 `general-purpose` 可回退，会报 `subagent_type is required`。
+
+| 类型 | 工具 | 模型 | 特点与坑 |
+|------|------|------|---------|
+| **`general-purpose`** | subagent 可用的全部工具 | `CLAUDE_CODE_SUBAGENT_MODEL`，否则跟随主对话 | 需要既探索又改动的多步任务。实现类角色的默认载体 |
+| **`Explore`** | 只读；`Write`/`Edit` 被拒 | 跟随主对话，但在 Claude API 上**封顶到 Opus** | 搜索/理解代码库。调用时要指定彻底程度：**quick**（定点查找）/ **medium**（均衡）/ **very thorough**（全面） |
+| **`Plan`** | 只读 | 跟随主对话 | plan mode 下收集上下文、出方案的研究 agent。做架构分析可以，但它不是为「常驻架构师」设计的 |
+| **`claude`** | subagent 可用的全部工具 | 按模型顺序解析 | 兜底类型，任务不匹配任何专门 agent 时用 |
+| `statusline-setup` / `claude-code-guide` | — | Sonnet / Haiku | Claude Code 自用，别拿来当团队角色 |
+
+> **`Explore` 和 `Plan` 都不加载 CLAUDE.md，也不看父会话的 git status**（为了让研究快而便宜）。其他内置类型和自定义 subagent 两者都加载，除非定义里写了 `omitClaudeMd`。所以：凡是依赖仓库约定的角色（架构师、需要遵守目录规范的实现者），别用 `Explore`/`Plan`，或者把必要的约定直接抄进提示词。
+
+两点实用推论：
+
+1. **想让探索跑在便宜模型上**：在项目或用户目录定义一个同名 `Explore` 的自定义 subagent，它会覆盖内置版本并保留自己的 `model` 字段（例如 `model: haiku`）。
+2. **想禁掉某个内置类型**：加 deny 规则；`CLAUDE_CODE_DISABLE_BUILTIN_AGENTS=1` 则全部禁用，只留你自己的。
+
+---
+
+## §3 自定义 subagent（`.claude/agents/*.md`）
+
+项目级放 `.claude/agents/`，用户级放 `~/.claude/agents/`，插件也可以带。文件是「YAML frontmatter + Markdown 正文（系统提示词）」。
+
+**什么时候值得落盘成文件**，而不是每次在提示词里现写：
+
+- 这个角色会被反复用（例如每次审计都要的 `security-reviewer`）
+- 需要限制工具集（只读审查者不给 `Write`/`Edit`/`Bash`）
+- 需要固定模型、effort 或权限模式
+- 需要 worktree 隔离
+
+frontmatter 字段（按需选用，不必写全）：
+
+| 字段 | 作用 |
+|------|------|
+| `name` | 调用名，`subagent_type` 用它 |
+| `description` | 什么时候该派它——写清楚才会被自动选中 |
+| `tools` / `disallowedTools` | 白名单 / 黑名单。带参数的条目如 `Bash(git push *)` 会**移除整个工具**，不是只移除该参数形式 |
+| `model` | `sonnet` / `opus` / `haiku` / `fable` / 完整 ID（如 `claude-opus-5`）/ `inherit` |
+| `permissionMode` | 见 §6。`manual` 是 `default` 的别名（需 v2.1.200+）。插件 subagent 忽略此字段 |
+| `maxTurns` | 到上限就停，输出会标注被截断 |
+| `effort` | 推理强度，见 §5 |
+| `skills` | 预加载的 skill。**注意：对 teammate 不生效**（见 §4） |
+| `mcpServers` | 只给它连的 MCP server。**只在 split-pane teammate 下生效** |
+| `hooks` | 这个 subagent 专属的 hook |
+| `memory` | 跨调用记忆 |
+| `background` | 是否后台跑。**in-process teammate 派出的 subagent 不能后台**，会报错 |
+| `isolation` | `worktree` → 给它单独的 git worktree |
+| `omitClaudeMd` | 不注入 CLAUDE.md |
+| `color` / `initialPrompt` / `experimental.cacheTtl` | 外观与缓存微调 |
+
+校验：`claude plugin validate .claude/agents`（v2.1.233+）能查出 frontmatter 解析不了的文件。
+
+`/agents` 自 v2.1.198 起**不再打开交互式创建面板**，只会提示文件位置。要建就直接让 Claude 写文件，或自己写。
+
+---
+
+## §4 teammate 的运行事实
+
+这些是 agent team 与「一次性 subagent」的关键差别，设计角色时必须知道：
+
+| 事实 | 影响 |
+|------|------|
+| 团队是**隐式**的，一个会话一个，名字形如 `session-xxxxxxxx` | 没有 `team_name` 参数可传，也没有 `TeamCreate` / `TeamDelete`（2.1.178 起移除），资源自动清理 |
+| teammate 用 `Agent` 工具 + `name` 参数启动 | `name` 就是后续 `SendMessage` 的收件地址 |
+| **lead 固定**，主会话终生是 lead | 不能把某个 teammate 提升为 lead，也不能移交 |
+| **不能嵌套**：teammate 不能再开 teammate | 需要两层分工时，第二层只能是它自己派的一次性 subagent |
+| 权限模式在 spawn 时**不能按人指定** | teammate 继承 lead 的模式（`dontAsk` 除外）；spawn 之后可以单独改某个人的 |
+| 用 `.claude/agents/*.md` 当 teammate 时：`tools`、`model`、正文生效；**`skills` 不生效**；`mcpServers` 只在 split-pane 生效 | 需要 teammate 遵循某个 skill 的做法时，把要点直接写进提示词 |
+| **idle 通知**会把 teammate 的最终答复自动送给 lead | 不要轮询；等通知 |
+| in-process 面板里空闲的行会在整块面板空闲 30 秒后隐藏；超过 3 个空闲折叠成 `N idle agents` | 消失 ≠ 停止。按名字发消息即可唤回 |
+| shutdown 是**请求**，teammate 可以拒绝 | 它会先做完当前请求或工具调用；别指望立刻消失 |
+| `/resume`、`/rewind` **不恢复** in-process teammate | 恢复会话后 lead 可能去给已不存在的 teammate 发消息——重新 spawn |
+| 任务状态会滞后，teammate 也可能遇错就停 | lead 要主动核实、手动改状态、追加指令或换人 |
+| split panes 需要 tmux 或 iTerm2（`it2` CLI + Python API） | VS Code 集成终端、Windows Terminal、Ghostty 不支持；`teammateMode` 设置或 `--teammate-mode` 切换 |
+| 打开 agent teams 后，**任何被 lead 指名的 subagent 都会变成 teammate** | 想恢复成普通 subagent：把 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 设为 `0`（用户级 settings 的 `0` 会覆盖 shell 导出；项目/本地/`--settings`/托管设置的优先级更高）。改完不用重启会话 |
+| teammate 的权限请求会冒泡到 lead | spawn 前先在 permission 设置里预批常用操作，否则会被打断很多次 |
+| 相关 hook：`TeammateIdle`、`TaskCreated`、`TaskCompleted` | `TaskCompleted` 退出码 2 可以拦下完成并把反馈送回 teammate |
+
+**共享任务清单不一定有**：`TaskCreate` / `TaskGet` / `TaskList` / `TaskUpdate` 按模型注入——Claude 3.x、Opus 4–4.7、Sonnet 4–4.6、Haiku 4.5 默认有；其他模型（含 Opus 4.8、Sonnet 5、Fable 5）默认没有，且实测即使设 `CLAUDE_CODE_ENABLE_TASKS=1` 也可能仍被模型门控掉（见 anthropics/claude-code#76076）。**设计流程时按「可能没有清单」来做**：lead 自己记一张任务表，依赖写进派发消息，用 `SendMessage` 推进。`TodoWrite` 在有 Task 工具的会话里默认被禁用，设 `CLAUDE_CODE_ENABLE_TASKS=0` 可换回它。
+
+---
+
+## §5 模型与 effort
+
+### 模型别名
+
+| 别名 | 解析为 |
+|------|-------|
+| `default` | 特殊值：清除覆盖，回到账号的运行时默认模型。它本身不是别名 |
+| `best` | Fable 可用时用 Fable，否则等同 `opus` |
+| `fable` | 当前 provider 的 Fable 模型，用于最难、最长时任务 |
+| `opus` | 最新 Opus，复杂推理 |
+| `sonnet` | 最新 Sonnet，日常编码 |
+| `haiku` | 最快的 Haiku，简单检索与格式化 |
+| `inherit` | 与主对话同模型（仅自定义 subagent 的 `model` 字段支持） |
+
+也可以写完整 ID，如 `claude-opus-5`、`claude-sonnet-5`；第三方部署（Bedrock / Vertex / Foundry）写各自的 ARN、部署名或版本名。
+
+### subagent / teammate 的模型解析顺序
+
+1. 定义里的 `model` 字段，或 `Agent` 调用时传的 `model`
+2. `CLAUDE_CODE_SUBAGENT_MODEL`（`_FORCE` 变体会压过第 1 条；只设 `_FORCE` 时内置 `Explore` 仍保留自己的 Opus 封顶）
+3. 主对话的模型
+
+### effort（推理强度）
+
+`low` / `medium` / `high` / `xhigh` / `max`，可用档位随模型而变：Fable 5.1 与 5、Opus 5、Sonnet 5、Opus 4.8、Opus 4.7 支持到 `max`；Opus 4.6 与 Sonnet 4.6 只到 `high` + `max`。设了模型不支持的档位会回落到它支持的最高档。`/effort` 命令改当前会话，自定义 subagent 用 `effort` 字段。
+
+### 给角色配模型的经验
+
+| 角色性质 | 模型 | 理由 |
+|---------|------|------|
+| lead、架构师、裁决者、需求设计 | `opus` 或 `fable` + `high` | 判断错了整队白跑 |
+| 实现者、写文档者 | `sonnet` | 性价比 |
+| 只读审查、检索、格式化 | `haiku`，或自定义 `Explore` 覆盖成 `haiku` | 便宜；内置 `Explore` 会被封顶到 Opus，想省钱必须自己定义 |
+| 交叉验证里的「第二意见」 | 与被验证者**不同**的模型 | 同模型同偏差，验不出东西 |
+
+---
+
+## §6 权限模式与继承规则
+
+| 模式 | 行为 |
+|------|------|
+| `default`（别名 `manual`） | 手动模式，逐个提示 |
+| `acceptEdits` | 自动接受文件编辑与常见文件操作 |
+| `auto` | 由分类器判断工具调用是否放行；Pro/Max/Team 计划上主对话的默认起点 |
+| `dontAsk` | 不提示（teammate 不继承这个模式） |
+| `bypassPermissions` | 跳过权限确认 |
+| `plan` | 只读规划，方案批准后才动手 |
+
+继承规则（**很容易踩**）：
+
+- 主对话处于 `bypassPermissions`、`acceptEdits` 或 `auto` 时，subagent **强制跟随主对话的模式**，你在 `permissionMode` 里写的值被忽略。`auto` 模式下分类器还会在 subagent 交付前复审它的工作和最终报告。
+- 主对话处于 `default`、`dontAsk` 或 `plan` 时，subagent 用你写的 `permissionMode`——**但 `bypassPermissions` 除外**，声明了也会保持主对话的模式（该例外需 v2.1.267+）。
+- teammate 继承 lead 的模式，`dontAsk` 除外；不能在 spawn 时按人指定，spawn 后可以单独改。
+
+**实践建议**：想给只读审查者真正上锁，别只靠 `permissionMode`——用 `tools` / `disallowedTools` 把 `Write`、`Edit`、`Bash` 拿掉，或在 permission 设置里加 deny 规则。工具集是硬的，模式会被主对话覆盖。
+
+---
+
+## §7 subagent 拿不到的工具，以及它对提示词的影响
+
+每个 subagent 都会被摘掉这些工具：
+
+`AskUserQuestion`、`EnterPlanMode`、`ExitPlanMode`（除非它的 `permissionMode` 就是 `plan`）、`Workflow`、`TaskOutput`、`ScheduleWakeup`、`WaitForMcpServers`、`EndConversation`，以及在深度上限处的 `Agent`。后台运行的 subagent 还会再被裁掉一批内置工具。fork（`/subtask`）跳过这两层过滤，拿到主对话的完整工具集。
+
+另外：主对话在 macOS / Linux / WSL 上默认没有 `Glob` 和 `Grep`，但 subagent 可以被单独授予它们。
+
+**这些主会话状态永远不会传给非 fork 的 subagent**：output style（它跑自己的系统提示词）、auto memory、内置 agent 的预加载 skill。CLAUDE.md 里的规则默认会到（`Explore`/`Plan` 除外），但如果某条规则对这个角色至关重要——比如「忽略 `vendor/` 目录」「所有接口必须过 `xxx` 中间件」——**在派发提示词里重述一遍**，别赌它读到了。
+
+**这四条推论直接决定提示词怎么写**：
+
+1. **teammate 问不到用户。** 任何需要用户拍板的事，它只能回传给 lead。提示词里要明说：「不确定就回传 lead，不要替用户决定」——否则它会自己脑补一个答案继续跑，这是团队里最难发现的错误来源。
+2. **teammate 不能开自己的 workflow，也不能在 in-process 下派后台 subagent。** 需要扇出的活儿由 lead 或脚本来扇。
+3. **它看不到主对话历史。** 背景、约束、验收口径都得写进提示词，别指望它「知道我们刚才说的」。
+4. **结果通过最后一条消息交付。** 让它把结论、证据、未决问题写成结构化的收尾消息，而不是散在中途的碎碎念里。
+
+---
+
+## §8 隔离：worktree 与文件冲突
+
+- **agent team 不会自动给 teammate 开 worktree。** 这是团队里最常见的翻车点：两个人同时改一个文件，后写的覆盖前写的。
+- 三种解法，按代价从低到高：
+  1. **切分文件范围**——每个角色有明确的可写目录和禁区，写进提示词。共享文件（配置、类型定义、路由表、锁文件）由 lead 统一改。
+  2. **`isolation: worktree`**——自定义 subagent 定义里加这个字段，它就在自己的 git worktree 里干活。
+  3. **手动 worktree / `/batch`**——你自己开多个 checkout，或用 `/batch` 让 5–30 个 subagent 各自在 worktree 里做完并各开一个 PR。
+- 契约类产物（接口定义、数据模型、事件格式）要**先冻结再并行**：由一个角色定稿，其他人只读引用，要改走 lead。
+
+---
+
+## §9 角色提示词写法
+
+teammate 的上下文是空的，提示词就是它的全部世界。五条要点，每条都对应一种典型翻车：
+
+1. **开头定角色与立场。** 「你是安全审查者，只报安全问题，不做风格评价」——不写立场，它会什么都管一点、什么都不深。
+2. **给足背景。** 任务来源、相关模块、已有约束、验收口径。它读不到主对话，也（`Explore`）读不到 CLAUDE.md。
+3. **划死文件范围。** 可写目录 + 禁区 + 谁负责禁区。这是防冲突的唯一有效手段。
+4. **规定输出契约。** 固定字段、判定档位、引用格式（`文件:行号`）。要「结论 + 证据 + 建议改法」，不要「感觉这里可以再考虑一下」——无法执行的评审意见等于没有。
+5. **写清协作与收尾。** 什么时候 `SendMessage` 通知谁；不确定就回传 lead；完成后把结构化结论作为最后一条消息发出。
+
+模板见 `SKILL.md` 第 4 步。
+
+**一个反复出现的反模式**：把「审查者」也给了写权限，理由是「顺手改一下更高效」。结果是几个审查者同时改同一批文件，冲突掩盖了真正的问题。审查者就该只读——发现问题、报告、由实现者统一改。
+
+---
+
+## §10 成本与缓存
+
+- 每个 teammate 是独立会话，**各自烧 token**。官方建议 3–5 人起步；本 skill 的规模表按任务复杂度给到 2–8 人。
+- in-process teammate 的请求落在主对话的缓存 TTL 桶之外，默认只缓存 5 分钟（订阅计划也一样）；把设置项 `subagentPromptCacheTtl` 设为 `1h` 可延长。注意 API 对 1 小时缓存写入按更高费率计费。
+- 动态 workflow 的成本随 agent 数线性涨（上限 1000 个/次）；先用小样本（比如 10 个文件）验证脚本逻辑，再全量跑。
+- 便宜的活儿别用贵模型：检索、格式化、定点查找给 `haiku`；判断、裁决、设计给 `opus`/`fable`。
+
+---
+
+## §11 来源
+
+- Claude Code 文档 · Orchestrate teams of Claude Code sessions — `https://code.claude.com/docs/en/agent-teams`
+- Claude Code 文档 · Create custom subagents — `https://code.claude.com/docs/en/sub-agents`
+- Claude Code 文档 · Orchestrate subagents at scale with dynamic workflows — `https://code.claude.com/docs/en/workflows`
+- Claude Code 文档 · Agents and parallel work — `https://code.claude.com/docs/en/agents`
+- Claude Code 文档 · Tools reference（含 Task tool availability） — `https://code.claude.com/docs/en/tools-reference`
+- Claude Code 文档 · Model configuration（模型别名与 effort 档位） — `https://code.claude.com/docs/en/model-config`
+- anthropics/claude-code#76076 — 较新模型上 Task 工具被门控的实测报告

package/skills/swarm/references/teams/code-audit.md

@@ -0,0 +1,81 @@
+# 团队模式 · 代码审计
+
+> 六个团队模式之一，只在命中时读这一个。
+
+**适用**：PR review、上线前体检、安全/性能/正确性专项审计、接手陌生代码前的摸底。
+
+**不适用**：只想知道某段逻辑怎么工作（一个 `Explore` subagent 就够）；审计完还要立刻改（审计与修复分成两个阶段，见规则 6）。
+
+---
+
+## 机制建议：按规模选，别默认开团队
+
+| 范围 | 机制 |
+|------|------|
+| ≤10 个文件 / 单个 PR | **并行后台 subagent**，一个视角一个，lead 合成。开团队是浪费 |
+| 全库 / 上百文件 / 每个文件都要过同一套检查 | **动态 workflow**（提示词里写 `ultracode`）。脚本按文件扇出，再派一个 agent 交叉验证发现——这是 workflow 的主场 |
+| 审查者要互相质疑、多轮追问、边审边让实现者解释 | **agent team** |
+
+---
+
+## 角色
+
+| 角色 | 载体 | 模型 | 关注面 |
+|------|------|------|-------|
+| **lead** | 当前会话 | — | 去重、排优先级、裁决分歧、合成总报告 |
+| **security-reviewer** | `Explore`（只读） | `sonnet`+ | 认证授权、注入、密钥泄露、越权、SSRF、依赖漏洞 |
+| **performance-reviewer** | `Explore` | `sonnet` | 查询与 N+1、打包体积、渲染与重排、缓存缺失、同步阻塞 |
+| **correctness-reviewer** | `Explore` | `sonnet`/`opus` | 边界条件、错误处理、并发与竞态、状态机漏洞、空值 |
+| **contract-reviewer** | `Explore` | `sonnet` | API 契约与向后兼容、数据模型迁移、公开类型变更 |
+| **test-coverage-reviewer** | `Explore` | `sonnet` | 覆盖缺口、关键路径无测试、测试是否在测真东西 |
+
+按任务取舍视角，不要每次全上。
+
+> `Explore` 作为审查载体很合适（`Write`/`Edit` 被拒，锁得住），但它**不加载 CLAUDE.md**。如果仓库约定对判定有影响（「所有查询走 ORM」「禁止直连外部 API」这类），把这些规则抄进审查者的提示词，否则它会漏报一整类问题。
+
+---
+
+## 铁律
+
+1. **审查者一律只读**，不给 `Write`/`Edit`/`Bash`。「顺手修一下」会让几个审查者同时改同一批文件，冲突掩盖真问题；而且改完的代码就不再是大家正在评审的那份代码。发现问题 → 报告 → 由实现者统一改。
+2. **每条问题必须带 `文件:行号` + 为什么是问题 + 建议改法 + 严重度。** 没有定位的意见无法执行，也无法验证是否修好。
+3. **严重度口径由 lead 在派发时定死**（P0 阻塞上线 / P1 必须修 / P2 应该修 / P3 可选）。不定口径，每份报告里的「高优先级」不是一个意思。
+4. **先切范围再动手。** 明确告诉每个审查者「你只看这块，别的视角有人负责」。不切范围的结果是五个人报同一条问题、漏掉另外二十条。
+5. **lead 合成时去重并交叉验证。** 同一根因被多人报出要合并；只有一人报出的高危项，派第二个 agent（最好换个模型）复核后再定级。
+6. **审计与修复分阶段。** 审计团队收尾出报告；修复另起（功能开发团队或 `/batch`）。混在一起会让审查者变成实现者，失去独立视角。
+
+---
+
+## 输出契约
+
+每个审查者交：
+
+```
+## <视角> 审计报告
+结论：通过 / 有条件通过 / 打回
+
+| 严重度 | 位置（文件:行号） | 问题 | 影响 | 建议改法 |
+|--------|------------------|------|------|---------|
+
+未覆盖范围：<明确说出没看什么、为什么没看>
+```
+
+「未覆盖范围」这一栏是诚实性的关键——它让 lead 和用户知道这份报告**不能**为什么背书。省掉它，一份只看了三个目录的报告会读起来像全库体检。
+
+---
+
+## 规模
+
+3–6 人，由视角数决定。
+
+---
+
+## 常见失败
+
+| 症状 | 处理 |
+|------|------|
+| 审查者顺手改代码 | 载体用 `Explore`，或在自定义定义里 `disallowedTools: Write, Edit, Bash` |
+| 报告没有行号，无法定位 | 输出契约里写死引用格式 |
+| 五个人报同一条问题 | 派发时切范围，合成时去重 |
+| 只报问题，不报没看的地方 | 强制「未覆盖范围」栏 |
+| 审计完直接开始改，范围失控 | 分阶段，修复另起团队 |

package/skills/swarm/references/teams/debug-race.md

@@ -0,0 +1,70 @@
+# 团队模式 · 调试竞争（假设并行验证）
+
+> 六个团队模式之一，只在命中时读这一个。
+
+**适用**：复现困难或根因不明的 bug、多个互斥假设需要同时验证、性能劣化归因、偶发失败。
+
+**不适用**：报错信息已经直指原因（自己修）；需要的其实是功能改动而不是归因。
+
+---
+
+## 机制建议
+
+**并行后台 subagent 是默认选择**——每个假设一个调查员，独立跑，互不干扰，lead 裁决。只有在假设之间需要互相质疑、或调查要跨多轮逐步收窄时，才升级成 agent team。
+
+---
+
+## 角色
+
+| 角色 | 载体 | 权限 | 职责 |
+|------|------|------|------|
+| **lead** | 当前会话 | — | 拆假设、分配、裁决、决定下一轮 |
+| **reproducer** | `general-purpose` | 可写 `tmp/`、测试目录 | 造最小复现；给出稳定复现步骤，或证明不可复现 |
+| **hypothesis-A/B/C 调查员** | `Explore`（只读） | 只读 | 各自独立调查一个假设 |
+| **fixer** | `general-purpose` | `acceptEdits` | 根因确认后**唯一**动手改的人 |
+
+---
+
+## 顺序
+
+```
+t1 最小复现（reproducer）        ← 没有稳定复现，后面都是猜
+   ↓
+t2 假设 A ‖ 假设 B ‖ 假设 C 并行调查（互斥、可证伪）
+   ↓
+t3 lead 裁决根因（证据不足则补一轮新假设）
+   ↓
+t4 fixer 修复 + 回归测试
+   ↓
+t5 用 t1 的复现验证已修复，并复述根因链条
+```
+
+---
+
+## 规则
+
+1. **假设必须互斥且可证伪。** 派活前 lead 把每个假设写成「如果 X 为真，应该能观察到 Y」的形式。「可能是缓存问题」不是假设；「列表接口在缓存过期后仍返回旧数据，因为 TTL 用了创建时间而非更新时间」才是。假设不互斥，三个调查员查的是同一件事。
+2. **调查员只读。** 边查边改会破坏现场，也会让另一个调查员的观察失效。想验证某个猜想，写进报告请 reproducer 或 fixer 去做。
+3. **每人交三段式结论：支持证据 / 反对证据 / 判定（成立 / 不成立 / 证据不足）。** 只报支持证据的调查员没有价值——确认偏误是这类团队的主要风险，明确要求列出反对证据能压住它。
+4. **鼓励互相质疑**（team 模式下）：A 发现与 B 的假设矛盾的证据时，直接 `SendMessage` 给 B 和 lead。
+5. **根因确认后只留一个 fixer。** 多人同时改，事后无法判断到底是哪一处修好的。
+6. **修完要留回归测试，并写出根因链条**：触发条件 → 代码路径 → 为什么之前没暴露。写不出这条链，说明根因还没找到，只是症状被压住了。
+
+---
+
+## 规模
+
+3–5 人（复现者 + 2–3 个假设 + fixer，lead 兼裁决）。
+
+---
+
+## 常见失败
+
+| 症状 | 处理 |
+|------|------|
+| 三个调查员查的是同一件事 | 派活前把假设写成可证伪的形式，检查互斥性 |
+| 没有稳定复现就开工 | t1 是硬前置；不可复现时先解决复现 |
+| 调查员边查边改，现场被污染 | 载体用 `Explore`（`Write`/`Edit` 被拒） |
+| 报告只列支持证据 | 输出契约强制「反对证据」栏 |
+| 根因没定就多手修复 | t4 只留一个 fixer |
+| 修完没测试，两周后同一个 bug 回来 | t4 必须附回归测试 |

package/skills/swarm/references/teams/feature-dev.md

@@ -0,0 +1,71 @@
+# 团队模式 · 功能开发
+
+> 六个团队模式之一，只在命中时读这一个。
+
+**适用**：新功能、跨层变更（前端+后端+测试）、一个需求要同时动多处但各处相对独立。
+
+**不适用**：改动只落在一两个文件（自己干或一个 subagent）；同一个改动要复制到 5–30 个独立单元（用 `/batch`）；需求本身还没定（先去产品团队）。
+
+**机制建议**：agent team。理由是前后端在实现中要协商接口细节、测试要在实现后追问边界，这些是真正的多轮往返。如果接口契约能在开工前一次定死、之后互不打扰，两个并行后台 subagent 更省。
+
+---
+
+## 角色
+
+| 角色 | 载体 | 模型/effort | 权限 | 可写范围 |
+|------|------|-----------|------|---------|
+| **lead** | 当前会话 | — | — | 合并、共享文件 |
+| **architect** | 自定义 `.claude/agents/architect.md`（只读） | `opus`/`sonnet` + `high` | `plan` | 无 |
+| **frontend-dev** | `general-purpose` | `sonnet` | `acceptEdits` | `src/components/`、`src/pages/` |
+| **backend-dev** | `general-purpose` | `sonnet` | `acceptEdits` | `src/api/`、`src/services/` |
+| **test-engineer** | `general-purpose` | `sonnet` | `acceptEdits` | `tests/` |
+
+**为什么架构师不用内置 `Explore` 或 `Plan`**：这两个内置类型**不加载 CLAUDE.md、也不看 git status**，而架构判断恰恰依赖仓库约定；`Plan` 还是为 plan mode 的一次性研究设计的。要一个像样的常驻架构师，落一个自定义 subagent 文件，正文写清设计产出格式（接口契约、数据模型、错误码、迁移步骤），并给 `permissionMode: plan`。
+
+---
+
+## 顺序与依赖
+
+```
+t1 架构设计 → 契约冻结            architect
+   ↓
+t2 前端实现  frontend-dev    ‖    t3 后端实现  backend-dev      （并行）
+   ↓                                  ↓
+t4 测试编写与执行  test-engineer（等 t2、t3 的关键路径就绪）
+   ↓
+t5 集成验证与合并  lead
+```
+
+---
+
+## 协作规则
+
+1. **契约冻结后，前后端只读引用。** 谁要改契约，发消息给 lead 和对方，由 lead 裁决后统一改。契约在实现中途被单边改动，是跨层开发里最贵的返工。
+2. **各自独立 worktree，或严格分目录。** 共享文件（路由表、类型定义、i18n、配置、锁文件）由 lead 统一改。
+3. **测试工程师提前进场。** 契约一冻结就先写用例骨架和 fixture，实现完成后补断言——省掉一轮串行等待。
+4. **实现者遇到契约没覆盖的情况**：按最小惊讶原则实现并**记录下来**，然后通知 lead，不要静默扩权改契约。
+5. **lead 不下场写代码。** 发现自己开始实现时，停下来派活。
+
+---
+
+## 输出契约
+
+每个实现者的收尾消息包含：改动的文件清单、对外接口或行为的变化、未完成项及原因、需要 lead 处理的共享文件改动。
+
+---
+
+## 规模
+
+2–5 人。单模块 2 人（实现 + 测试）；跨层 4–5 人。
+
+---
+
+## 常见失败
+
+| 症状 | 处理 |
+|------|------|
+| 架构师一边设计一边开始写代码 | 用只读载体 + `permissionMode: plan` 锁住 |
+| 前后端同时改 `types/api.ts` | 共享类型归 lead |
+| 测试最后才进场，发现问题时实现者已经空闲关闭 | 契约冻结后就写测试骨架 |
+| lead 上下文被代码吃光，没人协调 | lead 只审查与合并，不实现 |
+| 契约中途被单边改动，另一端按旧契约写完 | 改动一律走 lead 广播 |

package/skills/swarm/references/teams/product.md

@@ -0,0 +1,114 @@
+# 团队模式 · 产品团队（需求设计 · 澄清 · 评审）
+
+> 六个团队模式之一，只在命中时读这一个。
+
+**适用**：
+- 一句模糊诉求要变成可执行需求（PRD、FR/NFR、验收标准）
+- 已有需求文档要评审：完整性、歧义、可测性、可行性
+- 需求评审会前的准备——把各方视角的问题一次性备齐
+- 需求拆分与排序、验收标准体检
+- 跨角色/跨端需求的边界澄清（权限、租户、空数据、重复与超限、状态机、前置未就绪）
+
+**不适用**：需求已定稿只差实现（→ 功能开发）；纯技术方案选型（→ 研究辩论）；只给一条需求估点（`story-points` skill 单人就够）；只把验收标准扩成成套用例（`test-plan` skill 单人就够）。
+
+---
+
+## 机制建议：两段式，别一上来开满编
+
+产品工作的形态是「多轮修订 + 每轮多视角评审」，两段的最佳机制不同：
+
+- **摸底与评审**：多个独立视角看同一份材料，彼此不需要协商 → **并行后台 subagent**（视角多时用动态 workflow 扇出更省事）
+- **草稿 → 澄清 → 修订**：设计师与澄清官要多轮往返 → **agent team**（teammate 常驻，改一版不用重新解释背景）
+
+一个硬约束决定了流程形状：**teammate 拿不到 `AskUserQuestion`，只有 lead 能问用户。** 所有澄清问题必须先汇聚到 lead、批量问一次、再把答复广播回去。让每个角色各自去问，等于让用户被问五遍——然后一个都答不上来。
+
+---
+
+## 角色
+
+| 角色 | 载体 | 模型/effort | 权限 | 可写范围 | 职责 |
+|------|------|-----------|------|---------|------|
+| **lead（产品负责人）** | 当前会话 | — | — | 定稿合入 | 唯一与用户对话的人；汇聚澄清问题并批量提问；裁决分歧；合成评审结论 |
+| **product-designer（产品设计师）** | `general-purpose`，或自定义 `.claude/agents/product-designer.md` | `opus`/`sonnet` + `high` | `acceptEdits` | `docs/prd/<feature>.md`（**PRD 唯一写手**） | 按 PRD 骨架产出：概述/目标/非目标 + 逐条 FR/NFR + 可断言验收标准 + TC 种子；分期建议放末尾 |
+| **clarifier（需求澄清官）** | `Explore`（只读） | `sonnet` | 只读 | 不写文件，交问题清单 | 找歧义、缺口、隐含假设；构造 2–4 个高信息量业务场景压测语义与边界；问题分级并给建议默认值 |
+| **stakeholder-proxy（干系人代理）** | `Explore` | `sonnet` | 只读 | 交立场报告 | 分别代入最终用户 / 运营 / 客服 / 合规 / 数据等视角，指出这份需求会让哪个角色受伤、哪句话会被误解 |
+| **feasibility-reviewer（技术可行性评审）** | `Explore` | `sonnet`/`opus` | 只读 | 交可行性报告 | 对着**代码库事实**核对：现有数据模型/接口/权限能否承接、影响面、隐藏成本；结论分「可直接做 / 需先改 X / 做不到」 |
+| **acceptance-reviewer（验收评审）** | `Explore` | `sonnet` | 只读 | 交验收体检报告 | 逐条验收标准判定是否可断言、可测；抓「体验流畅」这类无法成例的写法并给出改写 |
+| **estimator（估点与排期，可选）** | `general-purpose` | `sonnet` | `default` | 不写 PRD | 按因子表给点数与判定依据，复核 Sprint 容量 |
+
+> 只读评审角色用 `Explore` 最省事，但它**不加载 CLAUDE.md 与 git status**。对 feasibility-reviewer 这通常有影响（判断「能不能承接」往往要看仓库约定与当前分支状态）——这时改用自定义只读 agent，或把相关约定直接抄进提示词。
+
+---
+
+## 三轮流程
+
+```
+轮次 1 · 摸底（并行，全部只读）
+  clarifier    → 歧义与缺口清单 + 压测场景 S1…Sn
+  feasibility  → 代码现状盘点（能承接什么、要先改什么）
+  stakeholder  → 各角色诉求与受伤点
+        ↓
+  lead 合成一张「澄清问题单」（阻塞级 ≤8 条），用 AskUserQuestion 一次性问用户
+
+轮次 2 · 成稿
+  product-designer → PRD 草稿（吃进轮次 1 结论 + 用户答复）
+        ↓
+  acceptance-reviewer → 验收标准体检
+        ↓
+  product-designer → 修订
+
+轮次 3 · 评审定稿（并行 fan-out）
+  feasibility / stakeholder / acceptance 三视角同时评审定稿候选
+        ↓
+  lead 合成决议（通过 / 有条件通过 / 打回）
+        ↓
+  product-designer 定稿 → lead 问用户是否接 dev-plan / 估点 / 出用例
+```
+
+---
+
+## 协作规则
+
+1. **PRD 只能有一个写手。** 评审者一律输出独立报告（`docs/prd/reviews/<feature>-<role>.md`）或把结论作为收尾消息发回，**不许直接改 PRD**。两个理由：多 agent 同改一份文档必然互相覆盖；更关键的是，评审意见一旦被别人「顺手改掉」，就失去了「谁提的、为什么提、最后怎么处置」的追溯链——而这条链正是需求评审的价值所在。合入由 designer 或 lead 统一做。
+2. **澄清问题要批量、分级、可回答。** 一次交一张清单，每条标明「阻塞设计 / 影响验收 / 可后置」，并给出**建议默认值**。这样用户没空逐条回答时，也能按默认值推进，而不是整队卡住。阻塞级控制在 8 条以内——问 30 个问题的结果是一个都得不到回答。
+3. **不许替用户决定。** 每个角色的提示词里都写明：不确定就回传 lead。产品团队最隐蔽的失败，是某个 agent 自己脑补了用户意图，然后整份需求建立在那个想象上。
+4. **评审要有判定，不要有感想。** 固定结构：结论档位（通过 / 有条件通过 / 打回）+ 逐条问题（引用原文 → 为什么是问题 → 建议改法）。「建议再考虑一下」这类无法执行的条目不要写。
+5. **代码事实优先于产品想象。** 可行性评审必须引用真实文件路径、接口名、字段名，不许凭常识判断「这个应该好做」。产品团队最贵的错误是承诺了一个代码库承接不了的需求。
+6. **正文写终局，分期放末尾。** PRD 正文按目标全景写，分期交付建议只在末尾一次给出并逐条标明终验期——否则阶段交付会被误记为整条需求已完成。
+
+---
+
+## 与本仓其他 skill 的联动
+
+`skills` 字段对 teammate 不生效，所以要**在提示词里点名让它用**，并把关键约定抄进去：
+
+| skill | 谁用 | 提示词里要交代的事 |
+|-------|------|------------------|
+| `prd` | product-designer | PRD 骨架、FR/NFR 编号与验收标准写法、SPMS 写入口径 |
+| `story-points` | estimator | 四轴因子表、复现性要求（同输入同输出）、写回 `plannedPoints` 前需 lead 同意 |
+| `test-plan` | acceptance-reviewer | 「标准 → 用例」映射；不得覆盖或改写 PRD 种下的 TC 种子 |
+| `dev-plan` | 定稿后由 lead 触发 | 需求定稿是 dev-plan 的前置输入 |
+
+---
+
+## 规模
+
+- **最小可用 3 人**：lead + product-designer + clarifier
+- **标准 5 人**：再加 feasibility-reviewer + acceptance-reviewer
+- **完整 6–7 人**：再加 stakeholder-proxy + estimator
+
+宁少勿多：产品团队的产出是文档，多一个视角就多一份要合成的报告，而 lead 的合成能力才是瓶颈。
+
+---
+
+## 常见失败
+
+| 症状 | 根因 | 处理 |
+|------|------|------|
+| PRD 被改得面目全非，没人知道哪句是谁改的 | 多个评审者有写权限 | 收回写权限，只留 designer 一个写手 |
+| 用户被反复追问，最后放弃回答 | 各角色各自提问 | 全部汇聚到 lead，一次问完 |
+| 验收标准写着「体验流畅」「性能良好」 | 没人做可测性体检 | acceptance-reviewer 的核心职责，要求改写成可断言形式 |
+| 需求写得很完整但代码库承接不了 | 没对着代码核对 | feasibility-reviewer 必须引用真实路径与接口 |
+| 评审报告全是「建议关注」 | 输出契约没定判定档位 | 提示词里固定档位与字段 |
+| 澄清官一次抛 30 个问题 | 没有分级与上限 | 阻塞级 ≤8 条，其余标「可后置」并给默认值 |
+| 定稿后团队散去，需求没人接 | 流程没写下一步 | lead 定稿后主动问是否进 dev-plan / 估点 / 出用例 |