@haaaiawd/anws 1.0.1 → 1.2.0

package/templates/.agent/workflows/forge.md

@@ -108,9 +108,12 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 5. **如果必需文件缺失**: 报错并提示运行 `/genesis` + `/blueprint`。
 
 6. **断点续做判定**:
-   - 读取 `.agent/rules/agents.md` 的 "当前状态"
-   - 如果存在 "当前波次" 信息 → **断点续做** → 跳入 Step 3 继续未完成的波次
-   - 如果没有 → **新开始** → 继续 Step 1
+   - 读取 `.agent/rules/agents.md` 的 `🌊 Wave` 块
+   - 如果存在波次信息：
+     - 查看波次任务列表，对照 `05_TASKS.md` 中的 checkbox
+     - 如有未完成任务 → **断点续做** → 跳入 Step 3 继续未完成的任务
+     - 如全部完成 → **新波次** → 继续 Step 1
+   - 如果不存在 → **新开始** → 继续 Step 1
 
 ---
 
@@ -133,11 +136,11 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 
 按以下策略组织一个波次:
 
-| 策略 | 说明 |
-|------|------|
-| **同系统优先** | 属于同一 System 的任务分到一波（共享上下文） |
-| **文档依赖收敛** | 引用相同文档的任务分到一波（减少加载量） |
-| **2-5 个/波** | 过多→上下文溢出；过少→效率低 |
+| 策略             | 说明                                         |
+| ---------------- | -------------------------------------------- |
+| **同系统优先**   | 属于同一 System 的任务分到一波（共享上下文） |
+| **文档依赖收敛** | 引用相同文档的任务分到一波（减少加载量）     |
+| **2-5 个/波**    | 过多→上下文溢出；过少→效率低                 |
 
 ### 1.3 波次确认
 
@@ -146,10 +149,10 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 ```markdown
 ## 📋 Wave {N} 建议
 
-| 任务 ID | 标题 | 依赖文档 | 估时 |
-|---------|------|---------|:----:|
-| T{X.Y.Z} | ... | `04_SYSTEM_DESIGN/core.md` §... | Xh |
-| ... | ... | ... | ... |
+| 任务 ID  | 标题 | 依赖文档                        | 估时  |
+| -------- | ---- | ------------------------------- | :---: |
+| T{X.Y.Z} | ...  | `04_SYSTEM_DESIGN/core.md` §... |  Xh   |
+| ...      | ...  | ...                             |  ...  |
 
 **波次总估时**: ~Xh
 **需加载文档**: [文档列表]
@@ -157,7 +160,14 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 确认此波次？或调整任务组合？
 ```
 
-**人类检查点** ⚠️: 用户确认后才进入 Step 2。
+**人类检查点** ⚠️: 用户确认后，将确认的波次写入 `.agent/rules/agents.md` 的 `🌊 Wave` 块：
+
+```markdown
+### 🌊 Wave {N} — {波次目标简述}
+T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
+```
+
+然后进入 Step 2。
 
 ---
 
@@ -172,13 +182,23 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 
 ### 加载层级
 
-| 层级 | 内容 | 目的 |
-|:----:|------|------|
-| **L0 全局** | `02_ARCHITECTURE_OVERVIEW.md` — 仅系统清单和总体架构图部分 | 定位感 |
-| **L1 波级** | 本波涉及系统的 `04_SYSTEM_DESIGN/{system}.md` + 相关 ADR | 设计规范 |
-| **L2 任务级** | 每个任务的 `**输入**` 字段指定的精确文档章节 | 实现细节 |
+|      层级       | 内容                                                                     | 目的                 |
+| :-------------: | ------------------------------------------------------------------------ | -------------------- |
+|   **L0 全局**   | `02_ARCHITECTURE_OVERVIEW.md` — 仅系统清单和总体架构图部分               | 定位感               |
+|   **L1 波级**   | 本波涉及系统的 `04_SYSTEM_DESIGN/{system}.md`（L0 导航层）+ 相关 ADR     | 设计规范、接口契约   |
+| **L1.5 实现级** | 本波任务 `**输入**` 字段中明确引用的 `{system}.detail.md` **对应 §章节** | 算法伪代码、配置常量 |
+|  **L2 任务级**  | 每个任务的 `**输入**` 字段指定的精确文档章节                             | 实现细节             |
+
+> [!IMPORTANT]
+> **L1.5 加载规则（CRITICAL）**:
+>
+> - `{system}.md`（L0 导航层）**始终加载** ← 这是默认行为
+> - `{system}.detail.md`（L1 实现层）**仅当任务 `**输入**` 字段明确引用时才加载**
+> - 如果任务 `**输入**` 写的是 "`core.md` §战斗系统" → 只加载 `core.md` 对应章节
+> - 如果任务 `**输入**` 写的是 "`core.detail.md` §3.5" → 才加载 `core.detail.md` 对应章节
+> - **禁止**"以防万一"加载整个 `.detail.md`
 
-**L2 在 Step 3 的每个任务开始时按需加载，不在此处全部加载。**
+**L1.5 在 Step 3 的每个任务开始时按需加载，不在此处全部加载。**
 
 ### 加载步骤
 
@@ -239,21 +259,36 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 
 ### 3.4 验证 (Verify)
 
-**逐条验证验收标准**:
+**逐条验证验收标准**，并按类型分类证据:
+
+> [!IMPORTANT]
+> **验收标准分为两类，处理方式不同**:
+>
+> | 类型 | 标记 | 要求 |
+> |------|:----:|------|
+> | 🔧 可执行验证 | ✅/❌ | 必须实际运行命令/测试，贴出终端输出作为证据 |
+> | 👁️ 需人工确认 | ⏳ | 不允许 AI 自行判定为 ✅，标记为 ⏳ 等待用户确认 |
 
 ```markdown
 ### ✅ 验证报告: T{X.Y.Z}
 
-| 验收标准 | 状态 | 证据 |
-|---------|:----:|------|
-| [验收标准1] | ✅/❌ | [如何验证的] |
-| [验收标准2] | ✅/❌ | [如何验证的] |
+**可执行验证**:
+| 验收标准 | 命令/检查     | 输出摘要                    | 状态  |
+| -------- | ------------- | --------------------------- | :---: |
+| 启动正常 | `npm run dev` | Server running on port 3000 |   ✅   |
+| 测试通过 | `npm test`    | 12 passed, 0 failed         |   ✅   |
+
+**需人工确认**:
+| 验收标准     | 说明                       | 状态  |
+| ------------ | -------------------------- | :---: |
+| 页面显示正确 | 需要打开浏览器确认渲染效果 |   ⏳   |
 ```
 
 按任务的 `**验证说明**` 字段执行检查。
 
-- 全部 ✅ → 继续 3.5
-- 有 ❌ → **修复后重新验证**，不得跳过
+- 可执行验证全部 ✅ 且无人工确认项 → 继续 3.5
+- 可执行验证全部 ✅ 但有人工确认项 → 继续 3.5（人工项随后确认）
+- 可执行验证有 ❌ → **修复后重新验证**，不得跳过
 
 ---
 
@@ -261,13 +296,15 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 
 **检查清单** (每条都要回答):
 
-| # | 检查项 | 通过？ |
-|---|--------|:-----:|
-| 1 | 代码接口与 SYSTEM_DESIGN 定义一致？ | ✅/❌ |
-| 2 | 未引入 ADR 未批准的依赖？ | ✅/❌ |
-| 3 | 未添加任务范围外的功能？ | ✅/❌ |
-| 4 | 代码风格与项目一致，lint 通过？ | ✅/❌ |
-| 5 | 所有验收标准已验证通过？ | ✅/❌ |
+| #   | 检查项                              | 通过？ |
+| --- | ----------------------------------- | :----: |
+| 1   | 代码接口与 SYSTEM_DESIGN 定义一致？ |  ✅/❌   |
+| 2   | 未引入 ADR 未批准的依赖？           |  ✅/❌   |
+| 3   | 未添加任务范围外的功能？            |  ✅/❌   |
+| 4   | 代码风格与项目一致，lint 通过？     |  ✅/❌   |
+| 5   | 所有验收标准已验证通过？            |  ✅/❌   |
+| 6   | 所有可执行验收标准有终端输出证据？  |  ✅/❌   |
+| 7   | 需人工确认的验收标准已标记 ⏳？      |  ✅/❌   |
 
 - 全部 ✅ → 继续 3.6
 - 有 ❌ → **修复**
@@ -280,8 +317,16 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
    - 消息格式: `feat(system-id): T{X.Y.Z} — 任务标题`
    - 例: `feat(core): T2.1.1 — 地形与资源数据模型`
 
-2. **更新 05_TASKS.md**:
-   将该任务的 `- [ ]` 改为 `- [x]`
+2. **任务完成持久化** (立即回写):
+
+   > [!IMPORTANT]
+   > **每完成一个 task 并通过验证，立即回写 `05_TASKS.md`**。
+   > 这是进度持久化的核心机制——即使 AI 上下文丢失或会话崩溃，
+   > 下次加载 TASKS.md 就能看到精确进度。
+   > 配合 agents.md 的 Wave 块形成**双层恢复机制**: 粗粒度(Wave) + 细粒度(Task checkbox)。
+
+   - 将该任务的 `- [ ]` 改为 `- [x]`
+   - 确保回写后的 `05_TASKS.md` 与实际进度一致
 
 3. **继续下一个任务** → 回到 3.1
 
@@ -293,15 +338,14 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 
 ### 4.1 更新状态
 
-**更新 `.agent/rules/agents.md` "当前状态"**:
+**更新 `.agent/rules/agents.md`**:
+
+1. 更新 `🌊 Wave` 块为下一波的初始状态（如果已知下一波任务），或标记当前波已完成：
 ```markdown
-- **最新架构版本**: `genesis/v{N}`
-- **活动任务清单**: `genesis/v{N}/05_TASKS.md`
-- **当前波次**: Wave {N} ✅ 已完成
-- **已完成任务**: T{...}, T{...}, ...
-- **待办任务数**: {剩余数}
-- **最近一次更新**: {YYYY-MM-DD}
+### 🌊 Wave {N} ✅ — {波次目标简述}
+T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 ```
+2. 更新 `最近一次更新` 日期
 
 ### 4.2 波次回顾
 
@@ -352,3 +396,12 @@ chore: Wave {N} settlement — update task progress
 - ✅ .agent/rules/agents.md 当前状态已更新
 - ✅ 用户已确认波次完成
 </completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **微调任务** → `/change` — 发现问题需要微调任务 *(执行中发现任务描述不准确时)*
+- **质量审查** → `/challenge` — 完成阶段后对成果进行审查 *(完成一个 Sprint 后可选)*

package/templates/.agent/workflows/genesis.md

@@ -252,7 +252,30 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 
 将文档清单中的 checkbox 标记为已完成。
 
-### 7.3 展示产出
+### 7.3 Agent Context 自更新
+
+**更新 `.agent/rules/agents.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
+
+仅修改 `<!-- AUTO:BEGIN -->` 和 `<!-- AUTO:END -->` 之间的内容，保留手动添加的内容不变。
+
+```markdown
+### 技术栈决策
+- 语言: {从 tech-evaluator 产出提取}
+- 框架: {从 ADR 提取}
+- 构建工具: {从 ADR 提取}
+
+### 系统边界
+- {system-1}: {一句话职责}
+- {system-2}: {一句话职责}
+
+### 活跃 ADR
+- ADR-001: {标题} — {结论摘要}
+- ADR-002: {标题} — {结论摘要}
+```
+
+> 新版本 genesis (v{N+1}) 覆盖旧版本的自动区块内容。
+
+### 7.4 展示产出
 
 告知用户阶段完成，列出产出文档，并指引下一步行动（design-system 或 blueprint）。
 
@@ -261,5 +284,16 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 - ✅ 创建了 `genesis/v{N}/06_CHANGELOG.md`
 - ✅ 生成了 PRD, Architecture Overview, ADRs
 - ✅ 更新了 .agent/rules/agents.md (当前状态、项目结构、导航指南)
+- ✅ 更新了 agents.md AUTO:BEGIN 区块 (技术栈、系统边界、活跃 ADR)
 - ✅ 用户已在人类检查点确认
-</completion_criteria>
+</completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **设计系统详细架构** → `/design-system` — 为 {system-id} 设计详细架构 *(项目包含复杂系统时)*
+- **生成任务清单** → `/blueprint` — 将架构拆解为可执行任务
+- **质疑设计决策** → `/challenge` — 对当前设计进行系统性挑战

package/templates/.agent/workflows/quickstart.md

@@ -0,0 +1,262 @@
+---
+description: 一键启动入口。智能检测项目状态，编排 genesis → design-system → blueprint → challenge → forge 全流程，每一步等待用户确认后才继续。新用户只需知道这一个命令。
+---
+
+# /quickstart
+
+<phase_context>
+你是 **NAVIGATOR (导航员)**。
+
+**你的使命**：
+引导用户走完从"想法"到"可执行代码"的全流程。你不做具体工作——具体工作由各个专业工作流完成。你的价值在于**智能判断项目状态**和**编排正确的工作流顺序**。
+
+**核心原则**:
+- ⏸️ **绝不自动推进** — 每个 Step 结束后必须等待用户明确确认
+- 🧭 **智能起点** — 自动检测项目进度，从正确的位置开始
+- 📋 **清晰汇报** — 每个暂停点展示产出摘要、下一步内容、预估工作量
+- 🔀 **随时退出** — 用户可以随时中断，切换到具体工作流精细操作
+</phase_context>
+
+---
+
+## Step 0: 项目状态检测 (Project State Detection)
+
+**目标**: 智能判断项目当前处于哪个阶段，从正确的位置开始。
+
+### 检测逻辑
+
+```
+1. 扫描 genesis/ 目录
+2. 判断状态:
+
+   ├── 无 genesis/ 目录
+   │   → 🆕 全新项目 → Jump to Step 1
+   │
+   ├── 有 genesis/v{N}/ 但无 05_TASKS.md
+   │   ├── 有 04_SYSTEM_DESIGN/ → 需要 blueprint → Jump to Step 3
+   │   └── 无 04_SYSTEM_DESIGN/ → 可能需要 design-system → Jump to Step 2
+   │
+   ├── 有 05_TASKS.md 但无 src/ 代码
+   │   → 需要开始执行 → Jump to Step 5
+   │
+   └── 有代码 + 有任务
+       → 增量模式 → Jump to Step 6
+```
+
+### 状态报告
+
+向用户展示：
+
+```markdown
+## 🧭 项目状态检测
+
+**检测到的架构版本**: genesis/v{N} (或: 未找到 genesis 目录)
+**PRD**: ✅ 存在 / ❌ 缺失
+**Architecture**: ✅ 存在 / ❌ 缺失
+**System Design**: ✅ 已有 {X} 个系统设计 / ⚠️ 未找到
+**Tasks**: ✅ 共 {N} 个任务 ({M} 已完成) / ❌ 缺失
+**代码**: ✅ src/ 存在 / ❌ 未开始
+
+📍 **建议从 Step {X} 开始**: {原因}
+```
+
+⏸️ **等待用户确认** → 用户同意后按检测结果跳转到对应 Step。
+
+---
+
+## Step 1: 需求收集 (Genesis)
+
+**目标**: 执行 `/genesis`，将模糊想法转化为 PRD + 架构文档 + ADR。
+
+> 引导用户执行 `/genesis` 工作流。
+
+### 完成后展示
+
+```markdown
+## ✅ Step 1 完成: 需求与架构
+
+**产出文件**:
+- 📄 genesis/v{N}/01_PRD.md — {X} 个 User Story, {Y} 个需求
+- 📄 genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md — {Z} 个系统
+- 📁 genesis/v{N}/03_ADR/ — {W} 个架构决策记录
+
+**下一步**: Step 2 — 系统详细设计 (如需要) 或 Step 3 — 任务拆解
+**预估**: Step 2 每个系统约 30-60 分钟; Step 3 约 20-40 分钟
+```
+
+⏸️ **等待用户确认** → 用户确认后进入 Step 2。
+
+---
+
+## Step 2: 系统设计 (Design System — 如需要)
+
+**目标**: 评估是否需要为各系统执行 `/design-system`。
+
+### 复杂度评估
+
+检查 `02_ARCHITECTURE_OVERVIEW.md` 中的系统数量和复杂度：
+
+| 条件 | 判断 | 建议 |
+|------|------|------|
+| 系统数 ≤ 2，且无复杂跨系统交互 | 简单项目 | 建议跳过，blueprint 时可按需补充 |
+| 系统数 ≥ 3，或有复杂状态同步 | 复杂项目 | 建议为每个核心系统执行 /design-system |
+| 包含 AI/LLM 集成 | 需要详细设计 | 至少为 AI 相关系统做设计 |
+
+### 展示评估结果
+
+```markdown
+## 🔍 Step 2: 系统设计评估
+
+**架构中包含 {N} 个系统**:
+
+| 系统 | 复杂度 | 建议 |
+|------|:------:|------|
+| {system-1} | 🔴 高 | 建议执行 /design-system |
+| {system-2} | 🟡 中 | 可选 |
+| {system-3} | 🟢 低 | 可跳过 |
+
+**建议**: 为 {system-1} 执行详细设计。其余可在 blueprint 阶段按需补充。
+```
+
+⏸️ **等待用户确认** → 用户选择要设计的系统 → 依次执行 `/design-system` → 全部完成后进入 Step 3。
+
+---
+
+## Step 3: 任务拆解 (Blueprint)
+
+**目标**: 执行 `/blueprint`，将架构拆解为可执行的 WBS 任务清单。
+
+> 引导用户执行 `/blueprint` 工作流。含 User Story Overlay 交叉验证。
+
+### 完成后展示
+
+```markdown
+## ✅ Step 3 完成: 任务清单
+
+**产出文件**: genesis/v{N}/05_TASKS.md
+
+**统计**:
+- 总任务数: {N}
+- P0 (Must): {X} | P1 (Should): {Y} | P2 (Nice): {Z}
+- Sprint 数: {S}
+- 总预估工时: {T}h
+
+**User Story 覆盖**:
+- {covered}/{total} US 完整覆盖
+- {gaps} 个覆盖 GAP (已在 Overlay 中标注)
+
+**下一步**: Step 4 — 质量审查 (建议执行，约 15-30 分钟)
+```
+
+⏸️ **等待用户确认** → 用户确认后进入 Step 4。
+
+---
+
+## Step 4: 质量审查 (Challenge)
+
+**目标**: 执行 `/challenge`，对设计和任务进行系统性审查。
+
+> 引导用户执行 `/challenge` 工作流（含 design-reviewer + task-reviewer）。
+
+### 完成后展示
+
+```markdown
+## ✅ Step 4 完成: 质量审查
+
+**审查结果**:
+| 级别 | 数量 |
+|------|:----:|
+| 🔴 Critical | {X} |
+| 🟠 High | {Y} |
+| 🟡 Medium | {Z} |
+| 🟢 Low | {W} |
+
+**详细报告**: genesis/v{N}/07_CHALLENGE_REPORT.md
+```
+
+### 判断逻辑
+
+- **有 CRITICAL 问题**: "⚠️ 发现 {X} 个阻塞问题，建议先通过 /change 修复后再继续执行。"
+- **无 CRITICAL**: "✅ 无阻塞问题。可以开始执行。"
+
+```markdown
+**下一步**: Step 5 — 开始编码执行 (Wave 1)
+```
+
+⏸️ **等待用户确认** → 用户确认后进入 Step 5。
+
+---
+
+## Step 5: 开始执行 (Forge)
+
+**目标**: 引导进入 `/forge` 的第一个波次。
+
+> 引导用户执行 `/forge` 工作流。
+
+### 展示 Wave 1 建议
+
+```markdown
+## 🔨 Step 5: 准备开始执行
+
+基于任务清单和依赖关系，建议 Wave 1 包含:
+
+| 任务 | 标题 | 估时 |
+|------|------|:----:|
+| T{X.Y.Z} | ... | Xh |
+| T{X.Y.Z} | ... | Xh |
+
+**总估时**: ~{T}h
+
+准备好了吗？确认后将进入 /forge 开始编码。
+此后可直接使用 /forge 继续后续波次。
+```
+
+⏸️ **等待用户确认** → 确认后执行 `/forge`。
+
+---
+
+## Step 6: 增量模式 (Incremental)
+
+**目标**: 项目已有进度时，展示当前状态并建议下一步。
+
+### 展示当前进度
+
+```markdown
+## 📊 项目进度
+
+**架构版本**: genesis/v{N}
+**任务进度**: {completed}/{total} ({percentage}%)
+**当前波次**: Wave {W} ({status})
+
+| Sprint | 任务数 | 已完成 | 状态 |
+|--------|:-----:|:-----:|:----:|
+| S1 | {X} | {Y} | ✅/🔶/⬜ |
+| S2 | {X} | {Y} | ✅/🔶/⬜ |
+
+**建议下一步**:
+1. `/forge` — 继续执行未完成的任务
+2. `/change` — 微调已有任务
+3. `/challenge` — 对当前状态做一次审查
+4. `/genesis` — 启动新版本架构 (v{N+1})
+```
+
+⏸️ **等待用户选择** → 根据选择跳转到对应工作流。
+
+---
+
+<completion_criteria>
+- ✅ 正确检测了项目状态
+- ✅ 每个 Step 结束后等待了用户确认
+- ✅ 用户已进入具体工作流开始工作
+</completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **从头开始** → `/genesis` — 从零开始，将想法转化为 PRD 和架构
+- **任务拆解** → `/blueprint` — 将架构拆解为可执行任务
+- **开始编码** → `/forge` — 按任务清单开始波次执行
+- **质疑设计** → `/challenge` — 对当前设计进行系统性挑战

package/templates/.agent/workflows/scout.md

@@ -1,5 +1,6 @@
 ---
 description: 探测系统风险、隐藏耦合和"改了就炸"的暗坑，通过 Git 热点分析和 Gap Analysis 产出风险报告，适用于接手遗留项目或重大变更前。
+
 ---
 
 # /scout
@@ -127,4 +128,12 @@ Scout 的发现将作为**输入**反馈给 Architectural Overview。
 - ✅ 建立了系统指纹
 - ✅ 发现了文档与代码的 Gap
 - ✅ 产出了带有时间戳的风险报告
-</completion_criteria>
+</completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **启动新版本架构** → `/genesis` — 基于侦察发现启动架构重构 *(发现需要重大重构时)*