@haaaiawd/anws 1.2.5 → 2.0.0

package/templates/{.agent → .agents}/workflows/design-system.md

@@ -1,5 +1,5 @@
 ---
-description: 为单个系统设计详细的技术文档，通过调研最佳实践和深度思考产出完整的 System Design，包含架构图、接口设计和 Trade-offs 讨论。
+description: "为单个系统设计详细的技术文档。适用于架构拆解后需要对特定系统深入设计的场景。产出 04_SYSTEM_DESIGN/{system-id}.md（含 Mermaid 架构图、接口设计、Trade-offs 讨论）。"
 ---
 
 # /design-system
@@ -10,7 +10,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 **你的能力**：
 - 为单个系统设计详细的技术架构
 - 调研业界最佳实践（/explore）
-- 深度思考设计方案（sequentialthinking）
+- 使用 `sequential-thinking` skill 组织多步设计推理
 - 产出完整的系统设计文档
 
 **核心理念**：
@@ -25,7 +25,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 - `/design-system database-system`
 - `/design-system agent-system`
 
-**Output Goal**: `genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.md`
+**Output Goal**: `.anws/v{N}/04_SYSTEM_DESIGN/{system-id}.md`
 </phase_context>
 
 ---
@@ -95,12 +95,12 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 **加载步骤**:
 
 ### 1.1 检查文件存在性
-扫描 `genesis/` 目录，找到所有 `v{N}` 版本文件夹。
+扫描 `.anws/` 目录，找到所有 `v{N}` 版本文件夹。
 
 **检查**:
-- [ ] `genesis/v{N}/01_PRD.md` 存在
-- [ ] `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md` 存在
-- [ ] `genesis/v{N}/03_ADR/` 存在
+- [ ] `.anws/v{N}/01_PRD.md` 存在
+- [ ] `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md` 存在
+- [ ] `.anws/v{N}/03_ADR/` 存在
 
 **如果缺失**:
 - 提示用户先运行 `/genesis`
@@ -109,7 +109,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 ---
 
 ### 1.2 加载PRD
-读取 `genesis/v{N}/01_PRD.md`
+读取 `.anws/v{N}/01_PRD.md`
 
 **关注重点**:
 - Executive Summary - 项目核心目的
@@ -122,7 +122,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 ---
 
 ### 1.3 加载Architecture Overview
-读取 `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`
+读取 `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
 
 **关注重点**:
 - 系统清单 - 了解所有系统
@@ -132,7 +132,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 ---
 
 ### 1.4 查找该系统的详细定义
-在 `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md` 中搜索 system-id 相关内容
+在 `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md` 中搜索 system-id 相关内容
 
 或手动在Architecture Overview中查找该系统的：
 - **职责 (Responsibility)**: 这个系统负责什么
@@ -143,21 +143,34 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 ---
 
 ### 1.5 加载相关ADR
-扫描 `genesis/v{N}/03_ADR/` 目录
+扫描 `.anws/v{N}/03_ADR/` 目录
+
+> [!IMPORTANT]
+> **ADR 与 SYSTEM_DESIGN 的单向引用链**:
+> - ADR 记录跨系统决策详情
+> - SYSTEM_DESIGN §8 Trade-offs **只引用 ADR，不复制决策内容**
+> - 在设计时，必须识别哪些决策已在 ADR 中记录
 
 **选择性加载**与该系统相关的ADR，例如：
 - 技术栈选择 (ADR001_TECH_STACK.md)
 - 认证方式 (ADR002_AUTHENTICATION.md，如果该系统涉及认证)
 - 数据库选择 (如果该系统是后端或数据库系统)
 
-读取 `genesis/v{N}/03_ADR/ADR001_TECH_STACK.md`
+**引用格式** (在 §8 中使用):
+```markdown
+> **决策来源**: [ADR-XXX: 决策标题](../03_ADR/ADR_XXX.md)
+>
+> 本系统实现 ADR-XXX 定义的设计，不在此重复决策理由。
+```
+
+读取 `.anws/v{N}/03_ADR/ADR001_TECH_STACK.md`
 
 ---
 
 ### 1.6 生成上下文摘要
 
 > [!IMPORTANT]
-> 你**必须**使用 `sequentialthinking` (3-5步) 生成上下文摘要。
+> 你**必须**使用 `sequential-thinking` skill 组织 3-5 个 thought 生成上下文摘要。
 
 **思考引导**:
 1. "该系统关联哪些PRD需求？[REQ-XXX]"
@@ -198,12 +211,41 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 
 ---
 
+### 1.7 检查 ADR 引用清单
+
+> [!IMPORTANT]
+> 你**必须**在设计前明确哪些 ADR 需要在 §8 Trade-offs 中引用。
+>
+> **为什么**: 未雨绸缪,在设计前就明确哪些决策来自 ADR,避免在 §8 时才发现遗漏或重复记录决策。
+
+**检查步骤**:
+1. 列出 `.anws/v{N}/03_ADR/` 目录中的所有 ADR 文件
+2. 识别与本系统相关的 ADR (如技术栈、认证方式、数据库选型等)
+3. 生成"需要引用的 ADR 清单"
+
+**输出**: ADR 引用清单 (保存在内存中)
+
+**示例清单**:
+```markdown
+## ADR 引用清单
+
+需要在 §8 Trade-offs 中引用的 ADR:
+- [ADR-001: 技术栈选型](../03_ADR/ADR_001_TECH_STACK.md) - 本系统使用 React + Vite
+- [ADR-002: 认证方式](../03_ADR/ADR_002_AUTH.md) - 本系统需要处理 JWT Token
+
+本系统特有决策 (不在 ADR 中):
+- 状态管理方案 (Context vs Zustand)
+- 组件库选择
+```
+
+---
+
 ## Step 2: 系统理解 (System Understanding)
 
 **目标**: 深度理解该系统的职责和边界
 
 > [!IMPORTANT]
-> 你**必须**使用 `sequentialthinking` (3-5步) 进行系统理解。
+> 你**必须**使用 `sequential-thinking` skill 组织 3-5 个 thought 进行系统理解。
 >
 > **为什么？** 深度理解是良好设计的前提。
 
@@ -262,7 +304,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 ```
 
 **产出**:
-- 调研报告自动保存到: `genesis/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
+- 调研报告自动保存到: `.anws/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
 
 **关键要点**: 从调研中提取:
 - 推荐的架构模式
@@ -273,12 +315,12 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 
 ---
 
-## Step 4: 设计 (Design via sequentialthinking)
+## Step 4: 设计 (Design via sequential-thinking)
 
 **目标**: 基于调研和上下文，深度设计系统架构
 
 > [!IMPORTANT]
-> 你**必须**使用 `sequentialthinking` (5-7步) 进行设计思考。
+> 你**必须**使用 `sequential-thinking` skill 组织 5-7 个 thought 进行设计思考。
 >
 > **为什么？** 好的设计需要深度思考，不是拍脑袋决定。
 
@@ -423,24 +465,35 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 **关键要求**:
 - **L0 架构图**: 必须使用 Mermaid 绘制
 - **L0 决策树**: 用 Mermaid `flowchart TD`，不用伪代码
-- **L1 锚点原则 (L1 Anchor Principle)**: L0 作为大纲与目录，**必须**为 L1 里的所有细节块留下导航坐标（锚点）。例如在数据模型末尾必须显式注明 *“常量字典配置祥见 [xxx.detail.md §1](./xxx.detail.md)”*。**严禁在 L1 中存在 L0 完全没有提及/引用的“孤岛内容”**。
+- **L1 锚点原则 (L1 Anchor Principle)**: L0 作为大纲与目录，**必须**为 L1 里的所有细节块留下导航坐标（锚点）。例如在数据模型末尾必须显式注明 *"常量字典配置祥见 [xxx.detail.md §1](./xxx.detail.md)"*。**严禁在 L1 中存在 L0 完全没有提及/引用的"孤岛内容"**。
 - **Trade-offs**: 每个重要技术选型都要说明"为什么选 A 不选 B"
 - **追溯链**: 在相关章节引用 PRD 需求 [REQ-XXX]
 - **约束继承**: 从 PRD 和 ADR 继承约束
 
+> [!IMPORTANT]
+> **§8 Trade-offs 必须使用引用格式**
+>
+> 你**必须**使用 Step 1.7 生成的 ADR 引用清单,区分"引用 ADR"vs"本系统特有决策"。
+>
+> **为什么**: 决策只记录一次,避免重复和遗漏。
+>
+> - 跨系统决策 → 引用 ADR,不复制内容
+> - 本系统特有决策 → 详细说明"为什么选 A 不选 B"
+> - 引用格式参考 `system-design-template.md` §8 的示例
+
 ---
 
 ### 5.3 保存文档
 
 **保存 L0 文件**（必须）:
-将内容保存到 `genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.md`
+将内容保存到 `.anws/v{N}/04_SYSTEM_DESIGN/{system-id}.md`
 
 **保存 L1 文件**（如果 5.0 决策为「需要」）:
-将内容保存到 `genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.detail.md`
+将内容保存到 `.anws/v{N}/04_SYSTEM_DESIGN/{system-id}.detail.md`
 
 **示例路径**:
-- L0: `genesis/v{N}/04_SYSTEM_DESIGN/core.md`
-- L1: `genesis/v{N}/04_SYSTEM_DESIGN/core.detail.md`
+- L0: `.anws/v{N}/04_SYSTEM_DESIGN/core.md`
+- L1: `.anws/v{N}/04_SYSTEM_DESIGN/core.detail.md`
 
 ---
 
@@ -455,7 +508,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 
 **调用方式**:
 ```
-/challenge genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.md
+/challenge .anws/v{N}/04_SYSTEM_DESIGN/{system-id}.md
 ```
 
 **产出**: 质疑报告 + 改进建议
@@ -478,8 +531,8 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 **展示**:
 ```
 ✅ 系统设计文档已生成:
-  - 文件: genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.md
-  - 调研: genesis/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md
+  - 文件: .anws/v{N}/04_SYSTEM_DESIGN/{system-id}.md
+  - 调研: .anws/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md
 
 📋 文档包含:
   - 14个章节（完整版）或 11个章节（简化版）
@@ -508,7 +561,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 
 ```markdown
 ### 系统边界
-- {system-id}: {一句话职责} — 详细设计见 `genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.md`
+- {system-id}: {一句话职责} — 详细设计见 `.anws/v{N}/04_SYSTEM_DESIGN/{system-id}.md`
 ```
 
 > 仅追加，不覆盖已有系统的条目（除非同一 system-id 有更新值）。
@@ -518,9 +571,9 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 <completion_criteria>
 - ✅ 系统ID已确认
 - ✅ 上下文已加载（PRD + Architecture Overview + 相关ADR）
-- ✅ 系统理解已完成 (sequentialthinking 3-5步)
+- ✅ 系统理解已完成 (`sequential-thinking` 3-5 thoughts)
 - ✅ 调研已完成 (/explore)
-- ✅ 设计已完成 (sequentialthinking 5-7步)
+- ✅ 设计已完成 (`sequential-thinking` 5-7 thoughts)
 - ✅ 文档已生成 (使用模板)
 - ✅ 更新了 AGENTS.md AUTO:BEGIN 区块 (系统边界)
 - ✅ 用户已确认
@@ -541,29 +594,3 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 
 **为多智能体系统设计**:
 `/design-system agent-system`
-
----
-
-## 🛡️ 常见问题 (FAQ)
-
-**Q1: 如果Architecture Overview中没有我要设计的系统怎么办？**
-A: 提示用户先运行 `/genesis` 或更新 `02_ARCHITECTURE_OVERVIEW.md` 添加该系统。
-
-**Q2: 如果调研找不到相关最佳实践怎么办？**
-A: 调整调研关键词，或基于通用软件架构原则设计。记录在文档的"References"章节说明缺乏参考资料。
-
-**Q3: 小项目是否需要完整的14章节？**
-A: 结构保持一致，但可以简化内容。可省略章节: 13 (未来考虑), 14 (附录)。可简化章节: 12 (部署)。
-
----
-
-## 🔀 Handoffs
-
-完成本工作流后，根据情况选择：
-
-- **生成任务清单** → `/blueprint` — 将架构拆解为可执行任务
-- **质疑设计决策** → `/challenge` — 对当前系统设计进行系统性挑战
-
----
-
-// turbo-all

package/templates/{.agent → .agents}/workflows/explore.md

@@ -1,6 +1,5 @@
 ---
-description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双向螺旋产出结构化洞察，适用于技术调研、方案选型和头脑风暴。
-
+description: "深度探索复杂问题，产出结构化洞察。适用于技术调研、方案选型、头脑风暴等需要系统性思考的场景。通过向外搜索（收集事实）与向内发散（产生创意）的双向螺旋完成探索。"
 ---
 
 # /explore
@@ -25,7 +24,7 @@ description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双
 ## ⚠️ CRITICAL 深度思考要求
 
 > [!IMPORTANT]
-> **为什么必须使用 `sequentialthinking`？**
+> **为什么必须使用 `sequential-thinking`？**
 > 
 > 探索不是"搜一下 + 想一下"。真正的探索需要：
 > - **分解问题**：找到正确的问题比找到答案更重要
@@ -58,7 +57,7 @@ description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双
 **目标**: 真正理解问题，将其分解为可探索的子问题。
 
 > [!IMPORTANT]
-> 你**必须**调用 `sequentialthinking` 进行 **3-5 步**思考。
+> 你**必须**使用 `sequential-thinking` skill 组织 **3-5 个 thought**。
 >
 > **为什么？** 问题分解的质量决定了整个探索的方向。错误的分解会导致：
 > - 搜索了不相关的信息
@@ -125,7 +124,7 @@ description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双
 用于：产生创意、探索可能性、突破常规
 
 > [!IMPORTANT]
-> 你**必须**调用 `sequentialthinking` 进行 **5-8 步**发散思考。
+> 你**必须**使用 `sequential-thinking` skill 组织 **5-8 个 thought**进行发散思考。
 >
 > **为什么？** 第一个想法通常是最普通的。突破需要：
 > - 强迫自己继续想
@@ -186,7 +185,7 @@ description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双
 **目标**: 整合所有发现，验证一致性，收敛到核心洞察。
 
 > [!IMPORTANT]
-> 你**必须**调用 `sequentialthinking` 进行 **3-5 步**收敛思考。
+> 你**必须**使用 `sequential-thinking` skill 组织 **3-5 个 thought**进行收敛思考。
 >
 > **为什么？** 原始发现是碎片化的。你需要：
 > - 识别模式和主题
@@ -209,7 +208,7 @@ description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双
 **目标**: 产出结构化的探索报告。
 
 **保存路径**:
-- 如果由 `/design-system` 调用: `genesis/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
+- 如果由 `/design-system` 调用: `.anws/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
 - 如果独立调用: `explore/reports/{YYYYMMDD}_{topic_slug}.md`
 - 确保对应目录存在
 
@@ -302,15 +301,3 @@ description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双
 - "探索 Rust 和 Go 在系统编程中的优缺点"
 - "探索解决远程团队协作问题的方案"
 - "探索 AI 辅助编程的最佳实践"
-
----
-
-## 🔀 Handoffs
-
-完成本工作流后，根据情况选择：
-
-- **将调研结果应用到项目** → `/genesis` — 基于调研结论启动或更新项目架构 *(调研结论需要落地时)*
-
----
-
-// turbo-all

package/templates/{.agent → .agents}/workflows/forge.md

@@ -1,5 +1,5 @@
 ---
-description: 按照架构文档和任务清单将设计锻造为代码，通过波次执行、渐进式上下文加载和零降级护栏确保高质量交付，前提是已完成 /blueprint。
+description: "按照架构文档和任务清单将设计锻造为代码。适用于已完成 /blueprint 后的编码执行阶段。通过波次执行、渐进式上下文加载、零降级护栏确保高质量交付。"
 ---
 
 # /forge
@@ -17,7 +17,7 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 - 逐条验证验收标准
 
 **你的限制**：
-- **绝不**修改 `genesis/` 下的任何文档
+- **绝不**修改 `.anws/` 下的任何文档
 - **绝不**添加文档未定义的功能或依赖
 - **绝不**在有疑问时猜测——必须停下来确认
 
@@ -45,7 +45,7 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 > | 运行测试和 lint | ✅ | |
 > | Git commit 已完成的任务 | ✅ | |
 > | 更新 `AGENTS.md` 当前状态 | ✅ | |
-> | **修改 `genesis/` 下任何设计文档** | | ❌ |
+> | **修改 `.anws/` 下任何设计文档** | | ❌ |
 > | **创建 TASKS.md 中不存在的功能** | | ❌ |
 > | **降级或跳过验收标准** | | ❌ |
 > | **引入 ADR 未批准的第三方依赖** | | ❌ |
@@ -91,10 +91,10 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 **目标**: 找到 Source of Truth，判断是新开始还是断点续做。
 
 1. **扫描版本**:
-   扫描 `genesis/` 目录，找到最新版本号 `v{N}`。
+   扫描 `.anws/` 目录，找到最新版本号 `v{N}`。
 
 2. **确定 TARGET_DIR**:
-   **TARGET_DIR** = `genesis/v{N}`（数字最大的文件夹）。
+   **TARGET_DIR** = `.anws/v{N}`（数字最大的文件夹）。
 
 3. **检查必需文件**:
    - [ ] `{TARGET_DIR}/01_PRD.md` 存在
@@ -259,36 +259,42 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 3.4 验证 (Verify)
 
-**逐条验证验收标准**，并按类型分类证据:
+**根据任务的验证类型执行相应验证**，并按类型分类证据:
 
 > [!IMPORTANT]
-> **验收标准分为两类，处理方式不同**:
+> **验证类型决定验证方式和证据要求**：
 >
-> | 类型 | 标记 | 要求 |
-> |------|:----:|------|
-> | 🔧 可执行验证 | ✅/❌ | 必须实际运行命令/测试，贴出终端输出作为证据 |
-> | 👁️ 需人工确认 | ⏳ | 不允许 AI 自行判定为 ✅，标记为 ⏳ 等待用户确认 |
+> | 验证类型 | 验证方式 | 证据要求 | 标记 |
+> |---------|---------|---------|:----:|
+> | **单元测试** | 运行 `npm test` 或等效命令 | 终端输出：`X passed, 0 failed` | ✅/❌ |
+> | **集成测试** | 运行集成测试脚本 | 终端输出或日志 | ✅/❌ |
+> | **E2E测试** | 运行 E2E 测试脚本 | 测试报告或截图 | ✅/❌ |
+> | **编译检查** | 运行 `npm run build` 或等效命令 | 终端输出：`Build succeeded` | ✅/❌ |
+> | **Lint检查** | 运行 `npm run lint` 或等效命令 | 终端输出：`0 problems` | ✅/❌ |
+> | **手动验证** | 人工检查 | 用户确认 | ⏳ |
 
 ```markdown
 ### ✅ 验证报告: T{X.Y.Z}
 
-**可执行验证**:
-| 验收标准 | 命令/检查     | 输出摘要                    | 状态  |
-| -------- | ------------- | --------------------------- | :---: |
-| 启动正常 | `npm run dev` | Server running on port 3000 |   ✅   |
-| 测试通过 | `npm test`    | 12 passed, 0 failed         |   ✅   |
+**验证类型**: [单元测试 | 集成测试 | E2E测试 | 编译检查 | Lint检查 | 手动验证]
 
-**需人工确认**:
-| 验收标准     | 说明                       | 状态  |
-| ------------ | -------------------------- | :---: |
-| 页面显示正确 | 需要打开浏览器确认渲染效果 |   ⏳   |
+**自动验证** (单元测试/集成测试/E2E/编译/Lint):
+| 验收标准 | 命令 | 输出摘要 | 状态 |
+| -------- | ---- | -------- | :--: |
+| 测试通过 | `npm test` | 12 passed, 0 failed | ✅ |
+| 构建成功 | `npm run build` | Build succeeded | ✅ |
+
+**手动验证**:
+| 验收标准 | 说明 | 状态 |
+| -------- | ---- | :--: |
+| 页面显示正确 | 需要打开浏览器确认渲染效果 | ⏳ |
 ```
 
-按任务的 `**验证说明**` 字段执行检查。
+按任务的 `**验证类型**` 和 `**验证说明**` 字段执行检查。
 
-- 可执行验证全部 ✅ 且无人工确认项 → 继续 3.5
-- 可执行验证全部 ✅ 但有人工确认项 → 继续 3.5（人工项随后确认）
-- 可执行验证有 ❌ → **修复后重新验证**，不得跳过
+- 自动验证类型全部 ✅ 且无手动验证项 → 继续 3.5
+- 自动验证类型全部 ✅ 但有手动验证项 → 继续 3.5（手动项随后确认）
+- 自动验证类型有 ❌ → **修复后重新验证**，不得跳过
 
 ---
 
@@ -397,11 +403,3 @@ chore: Wave {N} settlement — update task progress
 - ✅ 用户已确认波次完成
 </completion_criteria>
 
----
-
-## 🔀 Handoffs
-
-完成本工作流后，根据情况选择：
-
-- **微调任务** → `/change` — 发现问题需要微调任务 *(执行中发现任务描述不准确时)*
-- **质量审查** → `/challenge` — 完成阶段后对成果进行审查 *(完成一个 Sprint 后可选)*