@haaaiawd/anws 1.0.1 → 1.2.0

package/templates/.agent/skills/task-reviewer/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: task-reviewer
+description: 系统性审查 05_TASKS.md 的质量与完备性。通过 6 大检测 Pass 在语义模型上运行，检测重复、歧义、欠详述、不一致、覆盖缺口和质量问题。
+---
+
+# 任务审查大师手册
+
+> "计划的质量取决于最薄弱的那个任务。  
+> 在代码暴露问题之前，找到裂缝。"
+
+你是**任务审查大师**，负责对 `05_TASKS.md` 进行系统性审计——以 PRD、Architecture 和 ADR 文档为基准，运行 **6 大检测 Pass**。你的武器是**语义模型**，而非朴素的字符串匹配。
+
+---
+
+## ⚡ 任务目标
+
+1. **加载文档 (必须)**: 读取 `genesis/v{N}/05_TASKS.md`、`01_PRD.md`、`02_ARCHITECTURE_OVERVIEW.md` 以及所有 `03_ADR/*.md`。
+2. **构建语义模型**: 构建 3 个清单模型（见 §语义模型构建）。
+3. **执行 6 大 Pass (A→F)**: 顺序执行每个检测 Pass——每个 Pass 在语义模型上操作。
+4. **严重度分级**: 为每条发现分配严重度（CRITICAL / HIGH / MEDIUM / LOW）。
+5. **生成报告**: 输出任务审查报告（见 §输出格式）。
+6. **展示摘要**: 向用户展示检测汇总表 + 前 10 条发现。
+
+## 🛑 硬约束
+
+- **发现上限**: 最多 50 条。超出时按严重度排序 → 截断 → 追加溢出摘要。
+- **只报告不修复**: 本技能**仅输出报告**。修复由用户或其他工作流完成。
+- **跨文档依赖**: Pass D 和 E **依赖** PRD + Architecture。若缺失，跳过相应 Pass 并注明。
+- **客观性**: 仅标记客观可检测的问题。不要为了填满报告而捏造问题。
+
+---
+
+## 🧠 语义模型构建
+
+> 在执行任何 Pass 之前，先构建以下 3 个模型。所有 Pass 在模型上操作，而非原始文本。
+
+### 模型 1: 需求清单 (Requirements Inventory)
+
+从 `01_PRD.md` 提取**每一条**需求：
+
+```
+REQ-001: slug-key-from-title
+  ├── 来源章节: §4 User Stories / §3 功能需求
+  ├── 优先级: P0 | P1 | P2
+  ├── 验收标准: [列表]
+  └── 关键词: [提取的名词短语，用于模糊匹配]
+```
+
+### 模型 2: 用户故事清单 (User Story Inventory)
+
+从 `01_PRD.md` 提取**每一个** User Story：
+
+```
+US-001: 标题 (Priority)
+  ├── 用户价值: [一句话]
+  ├── 涉及系统: [系统 ID 列表]
+  ├── 独立可测: [如何独立验证]
+  ├── 验收场景: [Given-When-Then 列表]
+  └── 边界情况: [边界条件]
+```
+
+### 模型 3: 任务覆盖映射 (Task Coverage Mapping)
+
+为 `05_TASKS.md` 中的每个任务提取：
+
+```
+T{X.Y.Z}: 标题
+  ├── 显式 REQ: 任务头部标注的 [REQ-XXX]
+  ├── 推断 REQ: 通过关键词与 REQ 清单匹配
+  ├── 关联 US: 通过 REQ 或系统重叠连接的 [US-XXX]
+  ├── 所属系统: Level 1 WBS 系统名称
+  ├── 依赖: [T{A.B.C}, ...]
+  ├── 验收标准: [列表]
+  ├── 预估工时: N
+  └── Sprint: S{N}
+```
+
+---
+
+## 🔍 6 大检测 Pass
+
+### Pass A: 重复检测 (Duplication Detection)
+
+**目标**: 发现浪费精力或导致混乱的冗余任务。
+
+| # | 检查项 | 如何检查 |
+|---|--------|---------|
+| A1 | **近重复任务** | 比较任务标题+描述的语义相似度。标记意图重叠 >70% 的任务对。 |
+| A2 | **共享验收标准** | 相同的 Given-When-Then 在多个任务中逐字或换述出现。 |
+| A3 | **输出重叠** | 两个任务产出同一个文件/组件/接口。 |
+
+**建议**: 合并重复项，或标注为"共享验收"（如确实都需要）。
+
+---
+
+### Pass B: 歧义检测 (Ambiguity Detection)
+
+**目标**: 消除使任务不可验证的模糊语言。
+
+| # | 检查项 | 如何检查 |
+|---|--------|---------|
+| B1 | **模糊形容词扫描** | 标记验收标准中的这些词：正确/正常/合理/快速/稳定/安全/直观/健壮/appropriate/proper/correct/fast/stable/secure/intuitive/robust |
+| B2 | **未解决占位符扫描** | 标记：`TODO`、`TBD`、`???`、`<placeholder>`、`[TBD]`、`FIXME` |
+| B3 | **未量化的非功能需求** | 没有具体数字的性能/安全需求（如"快速响应"但无延迟目标） |
+| B4 | **含糊代词** | 任务描述中 "它"、"这个"、"系统" 指代不明 |
+
+**严重度规则**: B1/B3 在 P0 任务中 → HIGH；在 P2 任务中 → MEDIUM。B2 一律 → HIGH。
+
+---
+
+### Pass C: 欠详述检测 (Underspecification)
+
+**目标**: 发现信息不足以执行的任务。
+
+| # | 检查项 | 如何检查 |
+|---|--------|---------|
+| C1 | **有动词无宾语** | 验收标准有动作动词但无具体目标（如"处理错误" → 什么错误？哪个处理器？） |
+| C2 | **缺失验收标准** | 任务的验收标准为零或只有 1 条模糊标准 |
+| C3 | **幽灵引用** | 任务引用了 Architecture 文档中不存在的组件/接口/API |
+| C4 | **缺失输入/输出** | 任务没有明确的输入或输出字段 |
+| C5 | **缺失验证说明** | 任务没有说明如何验证完成 |
+
+**严重度规则**: C2 在 P0 任务上 → CRITICAL。C3 一律 → HIGH。
+
+---
+
+### Pass D: 不一致性检测 (Inconsistency) — 跨文档交叉验证
+
+> ⚠️ 依赖 PRD + Architecture。若不可用，跳过并注明。
+
+**目标**: 捕捉 PRD、Architecture、ADR 和 Tasks 之间的矛盾。
+
+| # | 检查项 | 如何检查 |
+|---|--------|---------|
+| D1 | **术语漂移** | 同一概念在不同文档中使用不同名称（如 PRD: "game core", Architecture: "Core Engine", Tasks: "核心引擎"） |
+| D2 | **孤儿架构组件** | Architecture 中定义的系统/组件在 Tasks 中没有对应任务覆盖 |
+| D3 | **依赖与排期冲突** | 任务 A 依赖任务 B，但 A 被安排在比 B 更早的 Sprint |
+| D4 | **技术栈冲突** | ADR 选定技术 X，但任务中使用技术 Y |
+| D5 | **接口不匹配** | 任务 A 的输出格式 ≠ 任务 B 的预期输入格式（当 B 依赖 A 时） |
+
+**严重度规则**: D3 一律 → CRITICAL（执行必然失败）。D2 → HIGH。D1 → MEDIUM。
+
+---
+
+### Pass E: 覆盖率检测 (Coverage Gaps)
+
+**目标**: 确保没有遗漏。
+
+| # | 检查项 | 如何检查 |
+|---|--------|---------|
+| E1 | **正向覆盖** | PRD 中每个 REQ-XXX → 至少 1 个 task？构建 REQ 覆盖矩阵。 |
+| E2 | **反向覆盖（幽灵任务）** | 每个 task → 追溯到某个 REQ？无 REQ 追溯的任务是"幽灵任务"——可能是过度工程。 |
+| E3 | **User Story 完整性** | 每个 US-XXX → 任务链覆盖其所有涉及系统？能形成独立可验证的闭环？ |
+| E4 | **NFR 覆盖** | 非功能需求（性能、安全、无障碍）→ 有专门任务或已融入现有任务？ |
+| E5 | **边界/错误覆盖** | PRD 边界情况 → 有对应的测试/处理任务？ |
+
+**输出**: REQ 覆盖矩阵 + US 完整性表（见 §输出格式）。
+
+**严重度规则**: E1 在 P0 REQ 上缺失 → CRITICAL。E2 幽灵任务 → LOW（仅信息）。E3 不完整 US → HIGH。
+
+---
+
+### Pass F: 质量与粒度检查 (Quality & Granularity)
+
+**目标**: 确保任务大小合理、结构正确。
+
+| # | 检查项 | 如何检查 |
+|---|--------|---------|
+| F1 | **过大任务** | 预估工时 > 8h → 建议拆分 |
+| F2 | **过小任务** | 预估工时 < 1h → 建议与相关任务合并 |
+| F3 | **深度依赖链** | 链长 > 5 → 警告瓶颈风险 |
+| F4 | **孤立任务** | 无依赖方且不被依赖（孤岛）→ 确认是否有意为之 |
+| F5 | **关键路径分析** | 识别最长依赖链 → 标出瓶颈任务 |
+| F6 | **验收标准质量** | Given-When-Then 完整性 + 可执行验证方法 |
+| F7 | **Sprint 均衡度** | Sprint 工作量方差 > 均值 50% → 不均衡警告 |
+
+**严重度规则**: F1 > 16h → HIGH。F3 链 > 7 → HIGH。F5 仅信息 → LOW。
+
+---
+
+## 📊 输出格式：任务审查报告
+
+按以下结构生成报告：
+
+```markdown
+## 📊 任务审查报告
+
+> **审查文件**: genesis/v{N}/05_TASKS.md  
+> **对照文档**: 01_PRD.md, 02_ARCHITECTURE_OVERVIEW.md, 03_ADR/*  
+> **日期**: {YYYY-MM-DD}
+
+---
+
+### 检测摘要
+
+| Pass | 检测项数 | CRITICAL | HIGH | MEDIUM | LOW |
+|------|:-------:|:--------:|:----:|:------:|:---:|
+| A 重复检测 | — | — | — | — | — |
+| B 歧义检测 | — | — | — | — | — |
+| C 欠详述检测 | — | — | — | — | — |
+| D 不一致性检测 | — | — | — | — | — |
+| E 覆盖率检测 | — | — | — | — | — |
+| F 质量粒度 | — | — | — | — | — |
+| **合计** | **—** | **—** | **—** | **—** | **—** |
+
+**整体健康度**: 🟢 健康 / 🟡 需关注 / 🔴 阻塞
+
+---
+
+### REQ 覆盖率
+
+| REQ-ID | 标题 | 优先级 | 关联任务 | 状态 |
+|--------|------|:------:|---------|:----:|
+| REQ-001 | ... | P0 | T2.1.1, T2.1.2 | ✅ |
+| REQ-003 | ... | P0 | — | ❌ GAP |
+
+**覆盖率**: {已覆盖}/{总数} ({百分比}%)
+
+---
+
+### User Story 完整性
+
+| US-ID | 标题 | 涉及系统 | 关联任务 | 独立可测 | 状态 |
+|-------|------|---------|---------|:--------:|:----:|
+| US-001 | ... | core, client | T2.1.1→T7.2.1 | ✅ | ✅ |
+| US-003 | ... | core, executor | T3.2.1 (不完整) | ❌ | ⚠️ |
+
+---
+
+### 术语一致性
+
+| 术语 | PRD 中 | Architecture 中 | Tasks 中 | 状态 |
+|------|--------|----------------|---------|:----:|
+| ... | "..." | "..." | "..." | ⚠️ 漂移 |
+
+---
+
+### 关键路径
+
+> 最长依赖链，高亮瓶颈任务。
+
+```mermaid
+graph LR
+  T1.1.1 --> T2.1.1 --> T2.1.2 --> T4.1.1:::bottleneck --> T6.1.1
+  classDef bottleneck fill:#f96,stroke:#333
+```
+
+---
+
+### 问题清单
+
+| ID | 严重度 | Pass | 描述 | 建议 |
+|----|:------:|:----:|------|------|
+| TR-01 | CRITICAL | E | REQ-003 无对应任务 | 在 S2 增加 T2.2.6 |
+| TR-02 | HIGH | B | T4.1.3 验收标准使用"正确处理" | 量化：指明具体错误码+兜底行为 |
+| TR-03 | HIGH | D | "game core" vs "核心引擎" 术语漂移 | 按 ADR 统一为 "Core Engine" |
+| ... | ... | ... | ... | ... |
+
+---
+
+### 溢出摘要（发现 > 50 条时）
+
+{N} 条额外发现被省略。主要类别: ...
+```
+
+---
+
+## 🎚️ 严重度分级
+
+| 等级 | 判定标准 | 典型示例 |
+|:----:|---------|---------|
+| **CRITICAL** | 阻塞执行或遗漏核心功能 | PRD 需求零覆盖；Sprint 依赖环；核心文档缺失 |
+| **HIGH** | 导致返工或产出不可验证 | 重复任务；模糊的安全/性能验收；不可测标准；技术栈冲突 |
+| **MEDIUM** | 影响质量但不阻塞 | 术语漂移；NFR 覆盖缺失；边界情况欠详细 |
+| **LOW** | 润色项，不影响执行 | 措辞改进；轻微冗余；仅供参考 |
+
+**升级规则**: CRITICAL ≥ 1 → 整体健康度设为 🔴 阻塞。HIGH ≥ 5 → 🟡 需关注。其余 → 🟢 健康。
+
+---
+
+## 💡 审查要诀
+
+1. **不要过度标记**: 如果任务虽措辞不完美但意思明确，最多标 LOW。
+2. **上下文很重要**: 游戏 Tick 循环里的"快速"和批处理任务里的"快速"含义截然不同。
+3. **架构感知**: 用 `02_ARCHITECTURE_OVERVIEW.md` 的系统边界验证任务范围。
+4. **尊重 ADR**: 如果 ADR 明确选择了某个权衡并有文档记录，不要重新翻旧账。
+5. **增量价值**: 哪怕只找到 3 条 CRITICAL，审查就物有所值。完美不是目标。

package/templates/.agent/workflows/blueprint.md

@@ -75,8 +75,8 @@ description: 将架构设计拆解为可执行的 WBS 任务清单，每个任
 ```markdown
 - [ ] **T{X}.{Y}.{Z}** [REQ-XXX]: 任务标题
   - **描述**: 具体要做什么
-  - **输入**: 依赖的文件/接口
-  - **输出**: 产出的文件/组件
+  - **输入**: 依赖的文件/接口（如依赖前置任务，必须引用其具体输出产物）
+  - **输出**: 产出的文件/组件/接口
   - **验收标准**: 
     - Given [前置条件]
     - When [执行动作]
@@ -86,6 +86,16 @@ description: 将架构设计拆解为可执行的 WBS 任务清单，每个任
   - **依赖**: T{A}.{B}.{C} (如有)
 ```
 
+### 接口追溯规则
+
+> [!IMPORTANT]
+> **任务间的输入/输出必须对齐。**
+>
+> 如果任务 B 依赖任务 A，则 B 的「输入」必须明确引用 A 的「输出」的具体产物（文件路径、接口名、数据格式）。
+>
+> - ✅ 好: B 输入 = “T2.1.2 产出的 `MapGenerator` 类（`src/core/map_gen.py`）的 `generate()` 方法返回的 `World` 对象”
+> - ❌ 差: B 输入 = “地图数据”
+
 ### 验证说明格式指南
 
 > [!IMPORTANT]
@@ -106,7 +116,50 @@ description: 将架构设计拆解为可执行的 WBS 任务清单，每个任
 
 ---
 
-## Step 3: 依赖分析 (Dependency Analysis)
+## Step 3: Sprint 路线图与退出标准 (Sprint Roadmap)
+
+**目标**: 将任务分组为 Sprint/里程碑，每个 Sprint 必须有明确的退出标准和集成验证任务。
+
+> [!IMPORTANT]
+> **每个 Sprint 必须有退出标准和集成验证任务。**
+>
+> Sprint 不只是“一堆任务”，而是一个有明确入口和出口的工作单元。
+> 退出标准定义“什么算做完”，集成验证任务负责“证明做完”。
+
+### Sprint 路线图格式
+
+```markdown
+## 📊 Sprint 路线图
+
+| Sprint | 代号 | 核心任务 | 退出标准 | 预估 |
+|--------|------|---------|---------|------|
+| S1 | Hello World | 基础设施+核心数据 | headless 运行通过 + 基本渲染可见 | 3-4d |
+| S2 | 功能成型 | 实体+交互 | 完整功能可演示 + HUD 正常 | 5-6d |
+```
+
+### 集成验证任务 (INT Task)
+
+每个 Sprint 末尾必须生成一个 **INT-S{N}** 集成验证任务，专门负责验证该 Sprint 的退出标准：
+
+```markdown
+- [ ] **INT-S{N}** [MILESTONE]: S{N} 集成验证 — {代号}
+  - **描述**: 验证 S{N} 退出标准，确认所有跨系统功能正常协作
+  - **输入**: S{N} 所有任务的产出
+  - **输出**: 集成验证报告（通过/失败 + Bug 清单）
+  - **验收标准**:
+    - Given S{N} 所有任务已完成
+    - When 执行退出标准中的每一项检查
+    - Then 全部通过 → Sprint 完成; 有失败 → 记录 Bug 并触发修复波次
+  - **验证说明**: 按土出标准逐条执行，截图/录屏/日志确认
+  - **估时**: 2-4h
+  - **依赖**: S{N} 所有任务
+```
+
+> INT 任务是该 Sprint 的“关门任务”。未通过 INT 任务的 Sprint 不得标记为完成。
+
+---
+
+## Step 4: 依赖分析 (Dependency Analysis)
 
 **目标**: 生成 Mermaid 依赖图。
 
@@ -121,7 +174,7 @@ graph TD
 
 ---
 
-## Step 4: 复杂度审计
+## Step 5: 复杂度审计
 
 调用 `complexity-guard` 确保:
 - 单个任务 ≤ 8 小时
@@ -130,9 +183,54 @@ graph TD
 
 ---
 
-## Step 5: 生成文档
+## Step 5.5: User Story Overlay (交叉验证)
+
+**目标**: 从**用户价值维度**验证任务完备性。WBS 按系统拆解，这一步从 User Story 视角交叉检查。
+
+> [!IMPORTANT]
+> **User Story Overlay 是覆盖率安全网**
+>
+> WBS 确保每个系统都有任务，但无法保证每个用户故事都能端到端跑通。
+> 这一步能捕获"系统内任务齐全，但跨系统 User Story 链断裂"的问题。
+
+### 执行步骤
 
-**目标**: 保存最终的任务清单，并**更新 AGENTS.md**。
+1. **读取 PRD 的 User Stories**: 从 `{TARGET_DIR}/01_PRD.md` 提取所有 `US-XXX`
+2. **构建映射**: 将每个 US 涉及的系统 → 对应的 tasks（通过 REQ 追溯 + 系统归属匹配）
+3. **验证三项闭环**:
+   - 每个 US 是否有足够的 tasks 覆盖其**所有涉及系统**？
+   - 每个 US 的 task 链是否能形成**可独立验证**的闭环？
+   - 高优先级 US (P0) 的 task 是否分布在靠前的 Sprint？
+
+4. **生成 User Story View**: 追加到 `05_TASKS.md` 末尾
+
+### User Story View 格式
+
+```markdown
+## 🎯 User Story Overlay
+
+### US-001: [标题] (P1)
+**涉及任务**: T2.1.1 → T2.1.2 → T7.2.1 → T6.1.2
+**关键路径**: T2.1.1 → T2.1.2 → T7.2.1
+**独立可测**: ✅ S1 结束即可演示
+**覆盖状态**: ✅ 完整
+
+### US-003: [标题] (P2)
+**涉及任务**: T3.2.1
+**关键路径**: T3.1.1 → T3.2.1
+**独立可测**: ❌ 缺少 T4.x 衔接
+**覆盖状态**: ⚠️ 不完整 — 缺少 executor 侧任务
+```
+
+### 覆盖 GAP 处理
+
+- 如有不完整的 US → 在 Overlay 中标注 `⚠️`，并在任务清单中补充缺失的 task
+- 如有 US 的 task 全部在后期 Sprint → 建议前移部分 task 以实现早期验证
+- 补充的 task 必须遵守 Step 2 的任务格式模板
+
+---
+
+## Step 6: 生成文档
 
 **目标**: 保存最终的任务清单，并**更新 .agent/rules/agents.md**。
 
@@ -140,20 +238,27 @@ graph TD
 2.  **验证**: 确保文件包含所有任务、验收标准和依赖图。
 3.  **更新 .agent/rules/agents.md "当前状态"**:
     - 活动任务清单: `genesis/v{N}/05_TASKS.md`
-    - 待办任务数: `{X}` (计算 total tasks)
     - 最近一次更新: `{Today}`
+    - 写入初始波次建议，让 `/forge` 可以直接启动：
+    ```markdown
+    ### 🌊 Wave 1 — {S1 的第一批任务目标}
+    T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
+    ```
 
 ---
 
 ## 检查清单
+- ✅ 每个 Sprint 有退出标准和 INT 集成验证任务？
 - ✅ 05_TASKS.md 是否包含所有 WBS 任务？
 - ✅ 每个任务是否有 Context 和 Acceptance Criteria？
+- ✅ 任务间的输入/输出是否对齐（接口追溯）？
 - ✅ 是否生成了 Mermaid 依赖图？
-- ✅ 已更新 .agent/rules/agents.md？
+- ✅ User Story Overlay 已生成，覆盖 GAP 已补充？
+- ✅ 已更新 .agent/rules/agents.md（含初始波次建议）？
 
 ---
 
-## Step 6: 最终确认
+## Step 7: 最终确认
 
 **展示统计**:
 ```markdown
@@ -175,11 +280,41 @@ graph TD
 
 ---
 
+### Agent Context 自更新
+
+**更新 `.agent/rules/agents.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
+
+在 `### 当前任务状态` 下写入：
+
+```markdown
+### 当前任务状态
+- 任务清单: genesis/v{N}/05_TASKS.md
+- 总任务数: {N}, P0: {X}, P1: {Y}, P2: {Z}
+- Sprint 数: {S}
+- Wave 1 建议: T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
+- 最近更新: {Today}
+```
+
+---
+
 <completion_criteria>
 - ✅ 定位到最新架构版本 `v{N}`
 - ✅ 任务清单 `05_TASKS.md` 已生成
 - ✅ 每个 Level 3 任务包含验证说明
+- ✅ 任务间输入/输出已对齐（接口追溯）
+- ✅ 每个 Sprint 有退出标准和 INT 集成验证任务
 - ✅ 生成了 Mermaid 依赖图
-- ✅ 已更新 .agent/rules/agents.md
+- ✅ User Story Overlay 已生成并验证覆盖完整性
+- ✅ 已更新 .agent/rules/agents.md（含初始波次建议）
+- ✅ 更新了 agents.md AUTO:BEGIN 区块 (当前任务状态)
 - ✅ 用户已确认
-</completion_criteria>
+</completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **质疑设计与任务** → `/challenge` — 对设计和任务清单进行系统性审查
+- **开始编码执行** → `/forge` — 按任务清单开始波次执行