@xgent-ai/skills 0.1.0 → 0.4.0

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 + 可断言验收标准 + UAT 场景预期状态；六维推演与 SMAR 检查，分期建议放末尾，不创建 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 | 将验收条件与 UAT 状态展开为测试方法及「标准 → 用例」映射；不得覆盖或改写既有用例（含历史 PRD 种子） |
+| `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 / 估点 / 出用例 |

package/skills/swarm/references/teams/refactor-migration.md

@@ -0,0 +1,73 @@
+# 团队模式 · 重构 / 迁移
+
+> 六个团队模式之一，只在命中时读这一个。
+
+**适用**：大规模重构、框架/语言/版本迁移、模块拆分或合并、批量 API 替换、数百文件级的机械改动。
+
+**不适用**：小范围整理（自己干）；重构目标本身还没想清楚（先去研究辩论，或产品团队定需求）。
+
+---
+
+## 机制建议：这一类最容易被误用团队
+
+| 形态 | 机制 |
+|------|------|
+| 同一套改动要重复几十到几百次（升级 API、换导入路径、拆文件） | **动态 workflow** 或 **`/batch`**，不是 agent team。脚本能保证每个单元用同一套规则；5 个 teammate 各自理解规则会产出 5 种风格 |
+| 改动需要跨模块协商共享契约（拆服务、抽公共层） | **agent team** |
+| 两者混合（最常见） | lead + planner + verifier 用 team，机械批量部分交给 workflow |
+
+---
+
+## 角色
+
+| 角色 | 载体 | 权限 | 可写范围 |
+|------|------|------|---------|
+| **lead** | 当前会话 | — | 共享文件、合并 |
+| **planner（规划师）** | 自定义只读 agent 或 `Explore` | 只读 | 无 |
+| **module-A/B/C owner** | `general-purpose` | `acceptEdits` | 各自模块目录，或各自 worktree |
+| **verifier（验证者）** | `general-purpose` | `acceptEdits`（只写测试与基准脚本） | `tests/`、基准脚本 |
+
+---
+
+## 顺序
+
+```
+t1 现状分析与边界拆分（planner）
+t2 建立验证基线（verifier）              ← 可与 t1 并行
+t3 契约冻结 + 迁移步骤排序（planner → lead 确认）
+t4 模块 A ‖ B ‖ C 并行重构（各自 worktree）
+t5 逐模块回归对比（verifier）
+t6 集成、共享文件收口、合并（lead）
+t7 全量基线对比 + 回滚点确认
+```
+
+---
+
+## 规则
+
+1. **契约先冻结。** planner 产出模块边界、对外接口、共享类型、迁移步骤与顺序、回滚点；定稿后冻结，模块 owner 只读引用，要改走 lead。并行的前提是接口稳定，否则每个模块会按自己的理解长出不同的形状。
+2. **每个模块独立 worktree。** agent team **不会**自动隔离 teammate——用 `isolation: worktree` 或手动开 checkout。理由不只是防冲突：某个模块要推倒重来时，能单独丢弃它的工作树。
+3. **行为不变是验收标准。** 重构的定义是不改外部行为。verifier 在动手**前**建立基线（测试全绿 + 关键路径的输出/性能快照），改完对比。没有基线的重构无法证明它没弄坏东西。
+4. **小步提交，每步可回滚。** 每个 owner 按规划的步骤分批提交，不要攒一个巨型 commit。
+5. **机械改动交给脚本或 workflow，不要交给「理解力」。** 能用 codemod 完成的部分（重命名、导入路径、API 替换）写成脚本一次跑完；agent 只处理脚本处理不了的判断部分。这比让 5 个 agent 各自手工改快得多，也一致得多。
+6. **共享依赖变更要广播。** 某个模块需要改公共类型或工具函数时，先通知 lead 和其他 owner，由 lead 统一改并广播。
+7. **不要一次迁完所有模块。** 先迁一个最小但有代表性的模块，验证规则与脚本，再扇出到其余模块。第一个模块是探针，不是负担。
+
+---
+
+## 规模
+
+3–6 人。模块数决定 owner 数，但**并行 owner 不要超过 5 个**——lead 的协调能力是瓶颈，超过就分批做。
+
+---
+
+## 常见失败
+
+| 症状 | 处理 |
+|------|------|
+| 各模块长歪，接口对不上 | 契约没冻结就并行；t3 是硬前置 |
+| 说「重构完成」但没人能证明行为没变 | t2 基线是硬前置，t7 做全量对比 |
+| 共享文件被多人改，合并冲突成片 | 共享文件归 lead；owner 提示词写死禁区 |
+| 巨型 commit，出问题无法回滚 | 规则 4：小步提交 |
+| 机械改动让 agent 手工做，慢且风格不一 | 规则 5：codemod / workflow |
+| 5 个模块产出 5 种代码风格 | 用 workflow 或脚本统一规则，而不是靠 5 个人各自理解 |

package/skills/swarm/references/teams/research-debate.md

@@ -0,0 +1,73 @@
+# 团队模式 · 研究辩论
+
+> 六个团队模式之一，只在命中时读这一个。
+
+**适用**：技术选型、架构决策、自研 vs 买/用开源、方案 A vs B、某个技术方向值不值得投入。
+
+**不适用**：有客观标准答案的问题（查文档就行）；已经决定只差执行。
+
+---
+
+## 机制建议
+
+辩论的价值在**多轮往返**——正方看到反方的证据后要能回应，这需要一个常驻对手，所以 **agent team** 更合适。
+
+如果只要「从多个角度各写一份分析，然后交叉验证」，不需要真辩论，用**动态 workflow** 扇出更省（`ultracode`，或 `/workflow-authoring` 存成脚本复用）。
+
+---
+
+## 角色
+
+| 角色 | 载体 | 模型 | 职责 |
+|------|------|------|------|
+| **lead（决策者）** | 当前会话 | `opus`/`fable` | 定评判标准与权重、主持交换、最终决策并记录取舍 |
+| **advocate（正方）** | `general-purpose` | `sonnet`/`opus` | 全力支持方案 A，给出最强论证 |
+| **adversary（反方）** | `general-purpose` | `sonnet`/`opus` | 全力反对 A，提出并论证替代方案 |
+| **researcher（研究员）** | `Explore`，需要联网时用 `general-purpose` | `sonnet` | 找真实案例、benchmark、版本与维护状态、事故报告 |
+| **synthesizer（合成者）** | `general-purpose` | `opus` | 辩论结束后总结双方、指出真正的分歧点、提出折中或分阶段方案 |
+
+正反方建议用**不同模型**：同模型同偏差，辩不出新东西。
+
+---
+
+## 顺序
+
+```
+t0 lead 定评判标准与权重
+t1 researcher 供事实                     （可与 t2 并行启动）
+t2 正方立论 ‖ 反方立论
+t3 lead 把双方论点交换给对方
+t4 正方回应 ‖ 反方回应（第二轮）
+t5 synthesizer 合成
+t6 lead 决策 + 记录取舍与重评条件
+```
+
+---
+
+## 规则
+
+1. **先定评判标准，再开始辩论。** lead 在派发前写下这次决策看重什么（开发速度 / 运维成本 / 团队熟悉度 / 可逆性 / 性能上限 / 合规），并给权重。没有标准，辩论会退化成「谁更会说话」。
+2. **角色是强指派。** 明确告诉正方「你的任务是把 A 论证到最强，并逐条回应反方」，反方同理。让 agent「客观分析一下」的结果是两份温吞的、谁也不得罪的中间派报告，学不到东西。
+3. **必须引证据，不能空对空。** 每条论点标注来源：官方文档、真实项目案例、benchmark 数据、**本仓库的代码事实**。研究员供给事实，辩论双方解释事实。
+4. **至少两轮交叉。** 第一轮各自立论 → lead 交换论点 → 第二轮各自回应。只有一轮的「辩论」其实是两份独立报告。
+5. **合成者在辩论结束后才跑**，且任务不是和稀泥：要指出「双方其实同意的部分」「真正不可调和的分歧」「哪个分歧能被一个实验或一组数据解决」。
+6. **lead 的决策要可追溯**：选了哪个、放弃了什么、依据哪条证据、什么条件下应该重新评估。这份记录比结论本身更值钱——半年后一定有人会问「当初为什么选这个」。
+
+---
+
+## 规模
+
+4–5 人。
+
+---
+
+## 常见失败
+
+| 症状 | 处理 |
+|------|------|
+| 辩论没有焦点，各说各的 | t0 先定标准与权重，写进每个人的提示词 |
+| 两边都在让步，读不出差异 | 强化角色指派：「全力论证」「逐条回应」 |
+| 论点无来源，全是推断 | 输出契约要求每条论点带来源；不足的交给 researcher 补 |
+| 只辩一轮就收尾 | t3 交换 + t4 回应是必需环节 |
+| 合成者给出「两者各有优劣」 | 要求它指出真正的分歧点，以及哪个分歧可用数据解决 |
+| 决策没留记录，半年后重新吵一遍 | t6 产出决策记录（选择、放弃、依据、重评条件） |

package/skills/tdd/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: tdd
+description: "Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested."
+disable-model-invocation: true
+---
+
+# TDD Bug Fix
+
+When fixing a bug with a clear, cheap test path, make the broken behavior executable before changing production code. The goal is a focused regression test that fails before the fix and passes after it.
+
+Do not force a test when it would be impractical. If the available test would require broad harness setup, brittle mocks, slow end-to-end infrastructure, production-only state, vague reproduction steps, or large unrelated fixture churn, skip adding a new test and use the closest useful verification instead.
+
+## Workflow
+
+1. **Understand the bug.** Identify the intended behavior, current behavior, affected path, and smallest observable reproduction.
+2. **Choose the narrowest executable check.** Prefer the closest unit, component, integration, or regression test already used for that codepath. If no practical test path is obvious, do not create one from scratch just to satisfy the workflow.
+3. **Write the failing test first.** Add the smallest focused test that would have caught the bug. The test should encode intended behavior, not mirror the current implementation.
+4. **Run the new test before fixing.** Confirm it fails for the intended reason. If it passes or fails for an unrelated reason, correct the test or reproduction before editing the implementation.
+5. **Fix the bug.** Make the smallest production change that satisfies the intended behavior while preserving nearby contracts.
+6. **Rerun the regression test.** Confirm the test now passes.
+
+## If a Failing Test Is Impractical
+
+Use the closest executable regression check instead: a targeted script, manual reproduction command, browser automation, snapshot comparison, log assertion, or focused integration check.
+
+Prefer no new test over a bad test. A bad test is one that mostly tests mocks, encodes current implementation details, depends on timing or unrelated global state, needs expensive infrastructure for a small fix, or would be deleted immediately after proving the fix.
+
+## Guardrails
+
+- Do not change tests merely to match a wrong implementation.
+- Do not weaken existing assertions unless the expected behavior has genuinely changed and the reason is clear.
+- Keep the regression test focused on the bug. Avoid broad fixture churn or unrelated coverage expansion.
+- If the bug is flaky, make the test deterministic where possible and document the signal being locked down.
+- If the bug exposes a broader class of failures, first land the focused regression path, then consider additional sibling coverage.
+
+## Final Response
+
+Report the evidence, not just the outcome:
+
+- Name the failing-before test or executable check and the failure it produced.
+- Name the passing-after test run and any nearby validation performed.
+- If failing-before evidence could not be demonstrated, state why and describe the closest regression check used instead.

package/skills/teach/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: teach
+description: "Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'."
+disable-model-invocation: true
+---
+
+# Teach
+
+**You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.**
+
+Teach sits on top of `how` and `why`. Get your bearings on what the work is and what it touches, then run `how` for how it works and `why` for why it's that way. Those are real skill invocations that do their own digging. Blend what they find into one plain explanation, lead with what matters to the person, and go deeper when they ask. Reword freely for teaching, with one exception. Keep `why`'s confidence language intact (its hedges are findings, not style).
+
+1. Decide the few things they should walk away understanding. Choose them from why they're asking (about to change it, reviewing it, debugging it, new to it) and what they already know, both read from the conversation, not quizzed out of them. Skip what they plainly already know. Put the depth where their question is.
+2. Let `how` and `why` do the work, don't redo it. Read the code yourself to get oriented, then run `how` for how it works and `why` for why. Run them in parallel and combine the results. Match the size to the question. Run both for a subsystem, maybe one is enough for a small change. Keep `why` narrow by default since its full sweep is slow. Put the narrowing in the ask itself (a scoped question, git plus a source or two) so `why` records the skipped categories per its own contract, and widen it only when the reasons are the point.
+3. Start with a plain definition. Name the thing and say what it is in general terms, the way a senior engineer would say it out loud, with its common name if it has one. Then tie it to the case in front of you ("in X, we use this to ...") and build from there: how it works, the deeper reasons, the edge cases. For each part, explain the idea so it clicks: the problem it solves and how it actually works. Walk through what happens as the person does the thing (opens a long chat, scrolls up) when that is what makes it land. Listing functions and constants is reference, not teaching. Don't print framing labels ("the one idea to hold onto", "the thing to walk away with", "the key insight", "at its core", "TL;DR"). Give the smallest complete answer first, a sentence or two, not a dense paragraph, then stop. Add layers when they ask. Never a wall of text.
+4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater. Don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end.
+5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, reach for the image-generation tool and draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure.
+
+Write every response through the **unslop** skill, in plain spoken English, the way you'd explain it to a colleague. Be tight, not terse. Cut filler and hedging, keep the part that makes it click. State the concrete mechanism, not a metaphor, a framing, or a preview of what is coming. This is the target density: "Virtualization runs in two parts, one for rendering and one for loading from disk. When an item scrolls out past the buffer, both its DOM node and its in-memory data are evicted." Normal sentence case, not all-lowercase. No em dashes. Prefer periods over commas. Keep each sentence to one or two commas. If clauses pile up, split them into separate sentences. Give each concept one name and keep it. Avoid mirror sentences ("A without B, or B without A") and tidy closers ("the rest follows", "it all falls out"). The words in these steps are directions to you, not labels to print. Don't echo the structure as headers or stock phrases.
+
+**Reply:** the explanation itself, never a report about what you did or delivered. Lead with the main point, then the plain account of what it is, how it works, and why, and the threads worth chasing with `how` or `why`.