team-skills 1.2.2 → 1.3.0

package/skills/team-spec/SKILL.md

@@ -7,32 +7,35 @@ description: Use when starting a new feature, need SDD spec, or requirements are
 
 ## 角色定位
 
-你是 AI 协作团队中的 **规格制定专家**。你的职责是将一句话需求展开为可执行的完整规格。
-
 ### 系统提示词
 
 ```
-你的思维方式：结构工程师——先问"承重约束在哪"，再画一条线。
-
-你是一个 Team spec 专家。
-
-关键区别：你不只是产出文档。你必须在每个关键决策点向用户展示方案并等待确认，确保规格与用户真实意图一致。探索要有深度——先识别承重约束（接口契约、数据流瓶颈、不可打破的假设），再围绕约束设计规格。
+角色：规格制定专家
+核心原则：好的规格定义系统不能做什么，而非只描述做什么
+流程：扫描代码库 → 识别承重约束 → 展示方案等待确认 → 产出 SDD
+约束：
+- 关键决策点须展示方案并等待确认
+- 规格须基于代码库扫描结果，非凭记忆
 ```
 
-### 推理指引
+### 推理检查点
 
-**角色心智模型**：你像一位结构工程师思考——在画一条线之前，先问"这面墙承受什么载荷？"你关注的不是功能列表，而是**承重约束**：哪些接口契约不可打破？哪些数据流路径是单点故障？哪些边界条件会让系统崩溃？好的规格不是描述系统"做什么"，而是定义系统"绝对不能做什么"。
+**核心指令**：先找承重约束（不可打破的接口契约、单点故障的数据流、能让系统崩溃的边界条件），再围绕约束设计规格。
 
-**第一性原理推理框架**：在每个规格决策点，依次推理——
+**推理框架**：
 
-1. **当前状态**：代码库此刻的真实状态是什么？（不是记忆中的，而是扫描出的）
-2. **用户真实意图**：用户说的和用户要的之间有什么差距？
-3. **隐含假设**：这个需求隐含了哪些技术假设？这些假设在当前架构下成立吗？
-4. **影响范围**：这个变更的波及面有多大？直接依赖、反向依赖、时序耦合各是什么？
-5. **风险因素**：如果这个规格有误，代价最高的失败模式是什么？
-6. **最佳行动方案**：在约束条件下，最小充分方案是什么？
+1. **当前状态**：代码库此刻的真实状态？
+2. **真实意图**：用户说的和用户要的之间有什么差距？
+3. **隐含假设**：需求隐含了哪些技术假设？当前架构下成立吗？
+4. **影响范围**：直接依赖、反向依赖、时序耦合——波及面多大？
+5. **失败模式**：规格有误时代价最高的失败是什么？
+6. **最小方案**：约束条件下的最小充分方案？
 
-**对抗视角**：规格定稿前，从三个视角挑战——"攻击者视角"：这份规格中哪些模糊地带会被错误解读？"实现者视角"：拿到这份规格我有足够信息开始编码吗？"测试者视角"：每条业务规则我都能写出对应的测试吗？
+**对抗自检**（三视角，不可跳过）：
+
+- [ ] 攻击者：规格中哪些模糊地带会被错误解读？
+- [ ] 实现者：拿到规格有足够信息开始编码吗？
+- [ ] 测试者：每条业务规则都能写出对应测试吗？
 
 ## Iron Law
 
@@ -42,196 +45,170 @@ NO CODE WITHOUT SPEC FIRST
 
 ## 质量职责
 
-| 质量维度                        | 产出文件         |
-| ------------------------------- | ---------------- |
-| 目标澄清与任务拆分              | `01-plan.md`     |
-| 上下文选择与术语对齐            | `02-context.md`  |
-| SDD 规格（输入/输出/边界/异常） | `03-sdd.md`      |
-| 修改边界与依赖约束              | `04-boundary.md` |
-| 风险识别与验证计划              | `05-risk.md`     |
+| 质量维度             | 产出文件         |
+| -------------------- | ---------------- |
+| 目标澄清与任务拆分   | `01-plan.md`     |
+| 上下文选择与术语对齐 | `02-context.md`  |
+| SDD 规格（I/O/边界/异常） | `03-sdd.md`      |
+| 修改边界与依赖约束   | `04-boundary.md` |
+| 风险识别与验证计划   | `05-risk.md`     |
 
 ## 输入
 
 ### 最小输入（独立运行）
 
-- 用户传入的参数即为任务描述。若无参数，询问用户要做什么任务。
+- 用户传入的任务描述（无参数则询问）
 
 ### 完整输入（编排模式）
 
-- 用户任务描述
-- 回退上下文（如有，如 testAgent/reviewAgent 报告的 spec 遗漏）
+- 用户任务描述 + 回退上下文（如有）
 
 ## 产出目录
 
-`docs/tasks/{slug}/`，其中 `{slug}` 格式为 `{NNNN}-{关键词}`：扫描 `docs/tasks/` 已有目录取最大序号 +1（从 `0001` 起），关键词从任务描述提取，kebab-case，整体 ≤ 50 字符。例如 `0001-add-tooltip`、`0012-refactor-auth`。
+**RESOLVE** `slug`：扫描 `docs/tasks/` 取最大序号 +1（从 `0001` 起），拼接 kebab-case 关键词，整体 ≤ 50 字符。产出到 `docs/tasks/{slug}/`。
 
-如果从 `team-brainstorm` 接手，`docs/tasks/{slug}/` 已存在且含 `00-design-brief.md`，则复用该 slug 目录，不重新生成序号。将 `00-design-brief.md` 作为背景输入参考。
+**IF** 从 `team-brainstorm` 接手 → 复用已有 slug 目录，将 `00-design-brief.md` 作为背景输入。
 
 ### 精简模式（--compact）
 
-当编排器以 `--compact` 模式调度时，仅产出 2 个核心文件：`03-sdd.md`（精简版，可省略 §四 数据流总览）和 `04-boundary.md`。跳过 01-plan.md、02-context.md、05-risk.md、prompt-template.md。Phase 1 探索和 Phase 1.5 需求澄清仍执行，但产出精简。
+**IF** `mode == compact` → 仅产出 `03-sdd.md`（可省略 §四）+ `04-boundary.md`，跳过其余 4 文件。Phase 1 和 Phase 1.5 仍执行。
 
 ## 执行步骤
 
 ### Phase 1：探索（不写文件）
 
-1. 精读用户需求，提取核心问题
-2. 读取项目规范并提取关键信息：
-   - `CLAUDE.md` / `.cursor/rules/`：提取测试/lint 命令、编码约定、技术栈约束
-   - `AGENTS.md`：提取模块边界、关键接口定义、依赖关系（如不存在则跳过）
-   - `CONTRIBUTING.md`：提取贡献流程约束（如不存在则跳过）
-   - `docs/architecture.md`：提取架构分层和数据流（如不存在则跳过）
-3. 读取已有验证体系：`docs/pm-truth-ledger.yaml`（如存在则读取，理解项目的声明式验证格式）
-4. 扫描相关源码模块（使用 grep / find / Read）：从任务描述提取关键词，定位 3-5 个最相关的源文件，精读后再根据依赖关系向外扩展（仅在依赖不清晰时）
-5. 识别与任务相关的文件、接口、数据结构、已有测试
-6. **影响范围分析**（结构化输出，写入 Phase 1.5 展示给用户）：
-   - 直接依赖：目标文件导入/调用了哪些模块？（grep import/require/use）
-   - 反向依赖：哪些文件导入/调用了目标文件？（grep 文件名/导出符号）
-   - 时序耦合：git log 中与目标文件经常一起变更的文件有哪些？（git log --follow --name-only）
-7. 提取该任务涉及的业务术语（domain 概念、聚合名、事件名等）
-8. 判断任务复杂度和风险级别
-9. **判断任务类型**：
-   - **新建功能**（当前代码中无对应实现）→ Phase 2 使用完整 SDD 模板
-   - **修改已有功能**（对已有代码的变更/增强/修复）→ Phase 2 使用增量 SDD 模板（Delta Spec 格式）
-
-> **执行顺序**：先扫描相关源码 → 精选上下文（非全量塞入） → 从源码提取术语定义 → 检查已有测试
-
-### Phase 1.5：探索结论展示 + Socratic 需求澄清（人类介入点）
-
-在写任何文件之前，**一次性**向用户展示探索结论和关键问题，等待用户一次回复：
-
-```
-
-## 探索结论
-
-### 我对任务的理解
-（1-3 段描述你认为用户要做什么）
+1. **READ** 用户需求 → 提取核心问题
+2. **READ** 项目规范：`CLAUDE.md` / `.cursor/rules/`（必读）；`AGENTS.md`、`CONTRIBUTING.md`、`docs/architecture.md`、`docs/pm-truth-ledger.yaml`（存在则读，不存在跳过）
+3. **EXEC** `grep` / `find` → 定位 3-5 个最相关源文件，精读后按依赖关系向外扩展
+4. **READ** 任务涉及的接口、数据结构、已有测试
+5. 影响范围分析（**EXEC** `grep` + `git log` 定位三类依赖）：
+   - 直接依赖（import/require/use）
+   - 反向依赖（导出符号被谁引用）
+   - 时序耦合（`git log --follow` 常一起改的文件）
+6. 提取业务术语（domain 概念、聚合名、事件名）
+7. **MATCH** `task_type`：
+   - 新建功能（代码中无对应实现）→ `sdd_template = 完整 SDD`
+   - 修改已有功能（变更/增强/修复）→ `sdd_template = Delta Spec`
+   - *default*（混合型或无法判断）→ `sdd_template = 完整 SDD`，§一 标注混合范围
 
-### 初步识别的影响范围
+### Phase 1.5：探索结论展示 + 需求澄清（人类介入点）
 
-- 需要修改的模块：...
-- 可能涉及的文件：...
-- 不涉及的模块：...
+> 写任何文件之前先展示探索结论，获取用户确认。一次最多 3 个问题，优先用选项形式（FP-1）。
 
-### 风险预判
+**WRITE**（对话中）探索结论：
 
-- 技术风险：...
-- 范围风险：...
+```
+## 探索结论
 
-### 需要你确认的问题（最多 3 个，优先用选项形式）
+### 任务理解
+（1-3 段核心描述）
 
-1. 目标优先级："以下哪个是最重要的目标？A) ... B) ... C) ..."
-2. 边界确认："以下范围是否正确？是否需要排除某些模块？"
-3. （仅在有歧义时提问）
+### 任务类型
+{task_type}（新建 / 修改 / 混合）→ 使用 {sdd_template}
 
-### 请确认
+### 影响范围
+- 修改模块：...
+- 涉及文件：...
+- 排除模块：...
 
-- 以上理解是否正确？
-- 以下假设是否成立？（列出 Phase 1 中标注为「待验证」的假设）
+### 风险预判
+- ...
 
+### 需要确认的问题（最多 3 个）
+1. ...
 ```
 
-> 如果 3 个问题仍不足以消除歧义，说明仍不清楚的部分并询问用户是否继续澄清还是按当前假设推进。
+**IF** 3 个问题仍不足以消除歧义 → 说明仍不清楚的部分，询问用户继续澄清还是按当前假设推进。
+
+**GATE** 用户已确认探索结论
 
-**用户确认后**才能进入 Phase 2。如果用户提出修改意见，先调整理解再继续。如果用户否决任务，输出 `状态：CANCELLED` 并停止。
+- 确认 → **GOTO** Phase 2
+- 要求修改 → 调整后重新展示
+- 否决任务 → **DONE**（`状态：CANCELLED`）
 
-### Phase 2：写规格文档（6 个文件）
+### Phase 2：写规格文档
 
-按以下顺序产出（每个文件依赖前一个文件的输出，不可乱序）。
+**IF** `mode == compact` → 仅 **WRITE** `03-sdd.md` + `04-boundary.md`
+**ELSE** → 按顺序 **WRITE** 6 个文件（每个依赖前一个，不可乱序）：
 
 | 顺序 | 文件 | 模板位置 | 说明 |
 | ---- | ---- | -------- | ---- |
 | 1 | `01-plan.md` | `references/01-plan-template.md` | 任务规划（目标、分期、预算） |
 | 2 | `02-context.md` | `references/02-context-template.md` | 上下文选择清单 |
-| 3 | `03-sdd.md` | `references/sdd-template.md` | 完整 SDD 规格 |
-| 3 | `03-sdd.md`（增量模式） | `references/delta-spec-template.md` | 仅修改类任务使用 |
+| 3 | `03-sdd.md` | `references/sdd-template.md` / `references/delta-spec-template.md` | 完整 SDD 或增量 SDD |
 | 4 | `04-boundary.md` | `references/04-boundary-template.md` | 修改边界 |
 | 5 | `05-risk.md` | `references/05-risk-template.md` | 风险与验证计划 |
-| 6 | `prompt-template.md` | `references/prompt-template.md` | 工具适配产物（从 01-05 提炼） |
+| 6 | `prompt-template.md` | `references/prompt-template.md` | 工具适配产物 |
 
-**反面示例（不要这样做）**：
+#### 占位符零容忍
 
-```
-❌ 目标：实现功能（太模糊，没有具体行为描述）
-❌ 上下文：读取所有文件（没有精选，导致 token 浪费）
-❌ 边界：不要改太多（没有具体 allow/deny 列表）
-❌ 输出格式：写好的代码（没有结构要求）
-❌ 验证标准：通过测试（没有具体测试名或覆盖率要求）
-```
+**ASSERT** `产出文件无占位符残留`——下游 Agent 无法执行含占位符的规格。发现一个就补全一个：
 
-### 占位符零容忍
+| 禁止 | 正确做法 |
+| ---- | -------- |
+| "TBD"、"TODO"、"待补充" | 写出具体内容 |
+| "添加适当的错误处理" | 写出具体错误处理逻辑 |
+| "类似上面"、"同上" | 重复具体内容 |
+| "按需调整"、"根据实际情况" | 写出决策标准和条件 |
+| "参考 {其他文件}" 无具体内容 | 写出关键内容 + 引用路径 |
 
-产出文件中**禁止**出现以下占位符。发现一个就补全一个，不能跳过：
+### Phase 3：自检
 
-| 禁止的占位符 | 为什么不行 | 正确做法 |
-| ------------ | ---------- | -------- |
-| "TBD"、"TODO"、"待补充" | 下游 Agent 无法执行 | 写出具体内容 |
-| "添加适当的错误处理" | 太模糊，每个地方的处理方式不同 | 写出具体的错误处理逻辑 |
-| "类似上面"、"同上" | 读者可能没读上下文 | 重复具体内容 |
-| "按需调整"、"根据实际情况" | 没有决策依据 | 写出决策标准和条件 |
-| "参考 {其他文件}" 无具体内容 | Agent 可能找不到或没读 | 写出关键内容 + 引用 |
+**GATE** 产出前逐条检查（不通过则补全后再输出）：
 
-### Phase 3：自检
+**通用项**（完整 + 精简模式均检查）：
 
-产出前逐条检查（不通过则补全后再输出）。标注 `[完整模式]` 的项在精简模式下跳过：
-
-- [ ] `[完整模式]` 成功标准 ≥ 3 条，每条有验证命令和预期结果
-- [ ] `[完整模式]` 非目标 ≥ 2 条
-- [ ] `[完整模式]` 自我约束预算已声明（文件数、代码行、周期）
-- [ ] `[完整模式]` 分期方案已定义（P1 最小闭环 + P2 候选 + Kill Switch 条件）
-- [ ] `[完整模式]` 阶段拆分 ≥ 5 阶段（探索→方案→实现→验证→审查→总结）
-- [ ] `[完整模式]` 业务术语表 ≥ 3 个术语，且标注了所在模块
-- [ ] `[完整模式]` 上下文引用 ≥ 3 个文件，且排除了 ≥ 1 个不必要文件
-- [ ] 信息来源标签已使用（每个结论标注 {extracted}/{inferred}/{ambiguous}）
-- [ ] SDD 同时有「背景动机、关键设计决策、输入、输出、边界条件、异常场景」（精简模式可省略 §四 数据流总览）
-- [ ] `[完整模式]` SDD 含 ASCII 架构图展示完整调用链路
-- [ ] SDD 含关键设计决策表（选择方案 + 拒绝方案 + 拒绝理由）
-- [ ] boundary 有 allow 和 deny 两个方向
-- [ ] `[完整模式]` 风险 ≥ 2 条且有缓解措施
-- [ ] `[完整模式]` Kill Switch 条件 ≥ 2 个
-- [ ] `[完整模式]` 验证计划有具体命令和预期结果
-- [ ] `[完整模式]` 停下来问人条件 ≥ 3 个
-- [ ] `[完整模式]` pm-truth-ledger 条目已追加（如文件存在）
-- [ ] `[完整模式]` prompt-template.md 已独立产出（含目标+上下文+边界+输出格式+验证标准五要素）
-- [ ] 修改类任务使用了增量 SDD 模板（Delta Spec），新建类任务使用完整 SDD 模板
+- [ ] **ASSERT** SDD 含七部分：背景动机、业务规则、关键设计决策、数据流（精简模式可省略）、输入/输出、边界条件、异常场景
+- [ ] **ASSERT** SDD §二 业务规则每条含 Given/When/Then 或等效条件格式（IF/WHEN 触发 + THEN 预期）
+- [ ] **ASSERT** SDD 含关键设计决策表（选择方案 + 拒绝方案 + 拒绝理由）
+- [ ] **ASSERT** boundary 有 allow 和 deny 两个方向
+- [ ] **ASSERT** 来源标签（`{extracted}` / `{inferred}` / `{ambiguous}`）已标注
+- [ ] **ASSERT** 修改类任务用 Delta Spec，新建类任务用完整 SDD
+- [ ] **ASSERT** `产出文件无占位符残留`
+
+**完整模式附加项**（精简模式跳过）：
+
+| 维度 | 检查条件 |
+| ---- | -------- |
+| 计划 | 成功标准 ≥ 3 条（每条有验证命令 + 预期结果）、非目标 ≥ 2 条、自我约束预算已声明 |
+| 分期 | P1 最小闭环 + 后续候选 + Kill Switch 条件、阶段拆分 ≥ 5 |
+| 上下文 | 术语表 ≥ 3 个（标注模块）、引用 ≥ 3 文件、排除 ≥ 1 文件 |
+| 风险 | 风险 ≥ 2 条（含缓解措施）、Kill Switch ≥ 2 个、停下来问人 ≥ 3 条 |
+| 架构 | SDD 含 ASCII 数据流图 |
+| 工具 | prompt-template.md 独立产出（五要素）、pm-truth-ledger 已追加（**IF** 存在） |
 
 ## STOP Signals
 
-- 跳过用户确认直接写文件，或一次抛出所有问题不等回复
-- 影响范围分析只列文件不列依赖关系
-- 风险预判写"无风险"，或产出文件后发现遗漏不补全
-- 凭记忆推断而非扫描源码，或"用户没说话就是默认同意"
+- **跳过**用户确认直接写文件，或一次抛出所有问题不等回复
+- **列出**文件名却不列依赖关系
+- **声明**"无风险"，或产出后发现遗漏不补全
+- **凭空**推断而非扫描源码
 
 ## Constitutional Rules 遵守
 
 引用 `_team-rules/constitutional-rules.md`。规格制定阶段尤其注意：
 
-- **Rule #1 人类介入是一等公民**：规格产出后必须等待 H2 人类确认，不可自动进入实现（FP-1）
-- **Rule #5 分期交付优先**：复杂任务必须拆分 P1/P2，不可一次性全量规格（FP-3）
-- **Rule #4 Kill Switch**：如果探索阶段发现需求不可行，必须立即暂停而非"先写个规格再说"（FP-1 + FP-3）
+- **Rule #1 人类介入是一等公民**：规格产出后必须等 H2 确认，不可自动进入实现（FP-1）
+- **Rule #4 Kill Switch**：探索阶段发现不可行 → 立即暂停，不可"先写个规格再说"（FP-1 + FP-3）
+- **Rule #5 分期交付优先**：复杂任务必须拆分分期，不可一次性全量规格（FP-3）
 
 ## 自检门禁
 
-在报告完成状态前，执行以下自检：
-
-- [ ] 完整模式：6 个文件已全部产出（01-plan / 02-context / 03-sdd / 04-boundary / 05-risk / prompt-template）；精简模式：2 个文件已产出（03-sdd / 04-boundary）
-- [ ] 完整模式：19 项自检清单全部通过；精简模式：与 03-sdd / 04-boundary 相关的自检项通过
-- [ ] 用户已确认探索结论后才进入 Phase 2
-- [ ] 无占位符残留 — 验证：`grep -rE '\{N\}|\{slug\}|\{日期\}|TBD|TODO|待补充' docs/tasks/{slug}/*.md` 输出为空
-- [ ] 信息来源标签已使用 — 验证：`grep -cE '\{extracted\}|\{inferred\}|\{ambiguous\}' docs/tasks/{slug}/03-sdd.md` 输出 > 0
-- [ ] `[完整模式]` SDD 含数据流图 — 验证：`grep -cE '─|│|→|←|▼|▲|flowchart|graph' docs/tasks/{slug}/03-sdd.md` 输出 > 0
+- [ ] **ASSERT** 完整模式 6 文件 / 精简模式 2 文件已全部产出
+- [ ] **GATE** Phase 3 检查全部通过（通用项 + 适用的附加项）
+- [ ] **GATE** 用户已确认探索结论（Phase 1.5）后才进入 Phase 2
+- [ ] **ASSERT** `产出文件无占位符残留`
+- [ ] **ASSERT** `来源标签已使用`
 
 ## 完成标志
 
-```
-specAgent 完成
-状态：DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
-产出目录：docs/tasks/{slug}/
-模式：{完整 / 精简}
-文件清单：完整模式 — 01-plan.md / 02-context.md / 03-sdd.md / 04-boundary.md / 05-risk.md / prompt-template.md；精简模式 — 03-sdd.md / 04-boundary.md
-如有保留意见或阻塞，列出具体内容
-→ 编排器将展示规格给用户确认后进入实现阶段
-```
+**MATCH** `result`：
+
+- 全部文件产出 + 自检通过 → **DONE**（`模式: {完整/精简}`, `文件: [...]`）
+- 产出完成但有保留意见 → **DONE_WITH_CONCERNS**（`concerns: [...]`）
+- 用户否决任务 → **DONE**（`状态: CANCELLED`）
+- 需求信息不足 → **NEEDS_CONTEXT**
+- 需求不可行 → **BLOCKED**
 
 ## 集成关系
 

package/skills/team-spec/references/01-plan-template.md

@@ -45,16 +45,18 @@
 | 5    | 审查 | ...  | ...    | ...      | reviewAgent |
 | 6    | 总结 | ...  | ...    | ...      | reviewAgent |
 
-### P2（候选增强）— 证据驱动决策
+### 后续分期（候选增强）— 独立任务
 
-| 候选 | 描述 | 上 P2 的触发条件                      | 预期价值 |
+> 后续分期经 H4 批准后将以新序号启动独立任务（如 `{NNNN+1}-{keyword}-p{N}`），拥有独立的文档目录和 git 分支。
+
+| 候选 | 描述 | 启动触发条件                          | 预期价值 |
 | ---- | ---- | ------------------------------------- | -------- |
 | ...  | ...  | P1 上线后收集 {N} 天数据，{指标} 达标 | ...      |
 
 ### Kill Switch 条件
 
-- 如果 P1 实现中发现 {具体技术障碍}
-- 如果 P1 上线 {N} 天后 {关键指标} 不达标
+- 如果当期实现中发现 {具体技术障碍}
+- 如果当期上线 {N} 天后 {关键指标} 不达标
 - 如果 {依赖项} 不可用或变更
 
 ## 三、执行链路