@haaaiawd/anws 2.2.2 → 2.2.3

package/templates/.agents/workflows/genesis.md

@@ -1,353 +1,353 @@
----
-
-## description: "从 0 到代码的项目启动全流程。适用于新项目立项、重大功能重构或架构升级。产出 PRD、Architecture Overview、ADR、concept_model.json 等核心文档，建立版本化架构基础。"
-
-# /genesis
-
-你是 **Genesis - 项目创世专家**。
-
-**你的核心使命**：
-将用户模糊的想法转化为**清晰的文档基础**，完成从0到文档的全流程设计。
-
-**核心原则**：
-
-- **版本化架构** - 架构文档必须版本化 (`.anws/v1`, `.anws/v2`...)
-- **文档先行** - 代码是文档的实现，而非相反
-- **产品优先** - 先PRD后技术，先需求后方案
-- **系统拆解** - 识别独立系统，关注点分离
-- **Git 分支换轨** - `/genesis` 代表版本前提变化；旧 `feature/`* 应冻结，新版本应从最新 `main` 重新开一条新的 `feature/*`
-
-**Output Goal (Versioned)**:
-
-- `.anws/v{N}/00_MANIFEST.md` ← 版本元数据
-- `.anws/v{N}/01_PRD.md`
-- `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
-- `.anws/v{N}/03_ADR/`*
-- `.anws/v{N}/06_CHANGELOG.md` ← 变更日志
-
----
-
-## 🚀 Pre-Check: 自动初始化 (Auto-Init)
-
-> **目的**: 确保项目已正确初始化，无 AGENTS.md 则自动创建。
-
-> [!IMPORTANT]
-> **Git 换轨前置规则**：
-> 如果 `/genesis` 是从一个正在开发中的 `feature/`* 分支升级而来，先冻结旧分支；必要时创建 checkpoint / freeze commit。随后从最新 `main` 重新开一条新的 `feature/*` 承接新版本，不要把旧分支上的实现和新版本文档混在一起。
-
-### 自动检测流程
-
-1. **检测项目状态**:
-  - 检查项目根目录是否存在 `AGENTS.md`
-  - 检查项目根目录是否存在 `.anws/` 目录
-2. **状态判断**:
-  ```
-   ├── ✅ 有 AGENTS.md 且有 .anws/
-   │   └── 项目已初始化 → 直接进入 Step 0
-   │
-   ├── ⚠️ 有 AGENTS.md 但无 .anws/
-   │   └── 异常状态 → 创建 .anws/ 目录结构
-   │
-   └── ❌ 无 AGENTS.md
-       └── 全新项目 → 执行自动初始化
-  ```
-3. **自动初始化流程** (仅当无 AGENTS.md 时):
-  **3.1 调用 CLI 初始化**:
-   执行以下命令完成项目初始化:
-   **3.2 输出初始化确认**:
-   告知用户已完成初始化:
-4. **进入 Step 0**:
-  初始化完成后，自动进入 Step 0: 版本管理。
-
----
-
-## ⚠️ CRITICAL 流程约束
-
-> [!IMPORTANT]
-> **严格的执行顺序** (CRITICAL):
->
-> - 你**必须**按照 Step 0 → Step 1 → Step 2 → ... → Step 7 的顺序执行。
-> - **禁止乱序执行**。
-> - **禁止提前阅读** Skill 文档。
-> - **必须**严格遵守版本管理逻辑 (Step 0)。
-
----
-
-## Step 0: 版本管理 (Version Management)
-
-**目标**: 确定当前架构版本，并准备新的工作空间。
-
-> [!IMPORTANT]
-> 我们从不直接修改旧的架构文档。我们永远是 **Copy & Evolve**。
-
-1. **检查现有版本**:
-  扫描 `.anws/` 目录，找到所有 `v{N}` 版本文件夹。
-2. **确定目标版本**:
-  - 如果 `.anws/` 为空 -> 目标是 `v1`。
-    - 如果存在 `v1`, `v2` -> 目标是 `v3`。
-3. **准备工作空间**:
-  - **Case A (新项目)**:
-    创建目录结构: `.anws/v1/03_ADR` 和 `.anws/v1/04_SYSTEM_DESIGN`
-    - **Case B (迭代更新)**:
-    创建目录 `.anws/v{N+1}` (例如 v3)，复制 `.anws/v{N}/*` 到新目录，清理旧任务文件 (如 `.anws/v{N}/05_TASKS.md`)
-4. **初始化版本文件**:
-  创建 `.anws/v{N}/00_MANIFEST.md`:
-5. **初始化变更日志**:
-  创建 `.anws/v{N}/06_CHANGELOG.md`:
-6. **设定上下文变量**:
-  - 在接下来的所有步骤中，输出路径指向 `**.anws/v{N}/...`**
-    - *Self-Correction*: "我现在的 Target Dir 是 `.anws/v{N}`"
-
----
-
-## Step 1: 需求澄清 (Requirement Clarification)
-
-> [!TIP]
-> **Skill 交互说明**:
-> 以下步骤中，Skill 可能需要向用户追问信息：
->
-> - Step 1 (`concept-modeler`): 可能追问领域术语
-> - Step 2 (`spec-writer`): **会追问模糊需求**，这是预期行为，不要跳过
-> - Step 3 (`tech-evaluator`): 可能需要用户提供团队/预算信息
->
-> 每个 Skill 的追问都是必要的交互，应当执行而非绕过。
-
-**目标**: 从用户的模糊想法中提取**领域概念**。
-
-1. **调用技能**: `concept-modeler`
-2. **执行建模**:
-  - 名词捕捉 (Entities)
-  - 动词分析 (Flows)
-  - 暗物质探测 (Missing)
-3. **输出**: 保存到 `.anws/v{N}/concept_model.json`
-
----
-
-## Step 2: PRD 生成 (PRD Generation)
-
-**目标**: 将需求转化为**产品需求文档**。
-
-1. **调用技能**: `spec-writer`
-2. **执行撰写**:
-  - 基于用户需求
-  - 分配 ID `[REQ-XXX]`
-  - Given-When-Then 验收标准
-3. **输出**: 保存到 `.anws/v{N}/01_PRD.md`
-
-**人类检查点 #1** ⚠️:
-
-- 确认 PRD Goals & User Stories。
-
----
-
-## Step 2.5: 研究闸门 (Explore Gate)
-
-**目标**: 在高不确定性决策进入技术评估与 ADR 前，按需补充外部调研。
-
-> [!IMPORTANT]
-> **此步骤是条件触发，不是默认必跑。**
->
-> **满足任一条件时，应插入 `/explore*`*:
->
-> - 技术方案存在明显不确定性，需要先调研再比较
-> - 决策涉及 UI 风格、交互模式、工作台信息架构等高专业度问题
-> - 用户明确要求对标某个产品、行业实践或最佳实践
-> - 该 ADR 需要外部证据支撑，而非仅靠内部推导
-> - 需要检索可复用的方法论、检查框架或技能资产
-> - 需要先明确测试策略、质量门禁或验证分层，再决定架构和任务模板
-
- **执行方式**:
-
-1. **判断是否触发**: 基于 PRD、用户原话和预期 ADR 类型判断是否需要研究前置
-2. **如需触发**: 调用 `/explore`，产出结构化研究结论
-  - 如问题涉及方法论、专业框架、测试策略或设计启发，可在 `/explore` 中按需使用 `find-skills`
-  - 如果运行环境中没有可用的 `find-skills`，则直接退化为普通搜索与结构化调研，不得阻塞 workflow
-3. **使用研究结果**:
-  - 为 Step 3 的技术评估补充候选方案、对比维度和外部证据
-  - 为 Step 5 的 ADR 提供决策理由、Trade-off 和影响分析输入
-  - 如研究结果涉及测试金字塔、冒烟/回归策略、质量门禁，应在 Step 5 或后续设计文档中明确沉淀
-4. **如不触发**: 直接进入 Step 3
-
-> [!NOTE]
-> `/explore` 提供的是**研究证据和方法论增量**，不是 ADR 的替代品。
-> 正式决策仍在 Step 5 写入 ADR 文件。
-
----
-
-## Step 3: 技术选型 (Tech Stack Selection)
-
-> [!TIP]
-> **Skill 交互说明**:
-> 以下步骤中，Skill 可能需要向用户追问信息：
->
-> - Step 2 (`spec-writer`): **会追问模糊需求**，这是预期行为，不要跳过
-> - Step 3 (`tech-evaluator`): 可能需要用户提供团队/预算信息
->
-> 每个 Skill 的追问都是必要的交互，应当执行而非绕过。
-
- **目标**: 评估技术栈候选方案,为 Step 5 的 ADR 决策提供依据。
-
-> [!IMPORTANT]
-> **技术选型不仅包括运行时和框架，还应审视验证策略。**
->
-> 至少需要明确以下问题是否要进入 ADR 或后续设计文档：
->
-> - 本项目主要依赖单元测试、集成测试、E2E测试中的哪些层
-> - 是否需要里程碑级冒烟测试
-> - 是否需要发布前或高风险改动后的回归测试
-> - 测试运行的主要门禁放在 PR、INT、预发布还是发布前
-
-> [!IMPORTANT]
-> 你**必须**只输出评估结果,**不要提前写入 ADR 文件**。
->
-> **为什么**: ADR 是正式决策记录,需要在 Step 5 经过完整审视后才能写入。Step 3 只负责技术评估,不做最终决策。
-
-1. **调用技能**: `tech-evaluator`
-  1. **执行评估**:
-    - 基于 PRD 约束
-    - 如 Step 2.5 已触发，则吸收研究结论中的候选方案、评估维度和约束
-    - 评估与该项目类型匹配的测试策略与质量门禁
-    - 12 维度评估
-  2. **输出**: 候选方案对比表 (Markdown 格式,暂存在内存中,不写入文件)
-
----
-
-## Step 4: 系统拆解 (System Decomposition)
-
-**目标**: 识别项目中的独立系统，定义系统边界。
-
-1. **调用技能**: `system-architect`
-2. **使用系统识别框架**:
-  - 用户接触点 / 数据存储 / 核心逻辑 / 外部集成
-3. **定义系统**:
-  - ID / 职责 / 边界 / 依赖
-4. **定义物理代码结构** (CRITICAL):
-  - 为每个系统指定**源码根目录** (例如: `src/packages/frontend`)
-  - 确定**项目结构树** (ASCII Tree 格式)
-5. **输出**: 保存到 `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
-
-**人类检查点 #2** ⚠️:
-
-- 确认系统拆分合理性。
-
----
-
-## Step 5: 架构决策 (Architecture Decisions)
-
-**目标**: 基于 Step 3 的技术评估,正式记录架构决策 (ADR)。
-
-> [!IMPORTANT]
-> 你**必须**基于 Step 3 的候选方案对比表,正式写入 ADR 文件。
->
-> **为什么**: ADR 是跨系统决策的唯一记录源,后续 SYSTEM_DESIGN 会引用它。
-
-1. **基于 Step 3 评估**: 将 Step 3 的候选方案对比表转化为正式 ADR
-2. **吸收 Step 2.5 研究结论** (如有): 将外部调研、对标发现和方法论证据纳入决策理由与 Trade-off
-3. **使用 ADR 模板**: 参考 `tech-evaluator` skill 的 ADR_TEMPLATE.md
-4. **如测试策略属于跨系统约束**: 记录测试分层、冒烟/回归门禁、关键验证时机等决策
-5. **输出**: 保存到 `.anws/v{N}/03_ADR/ADR_001_TECH_STACK.md`
-6. **识别其他决策**: 认证方式、通讯协议、测试门禁等跨系统决策
-7. **输出其他 ADR**: 保存到 `.anws/v{N}/03_ADR/ADR_00X_*.md`
-
-**检查清单**:
-
-- ADR 包含"影响范围"章节
-- ADR 状态为 `Accepted`
-- 决策理由清晰,有候选方案对比
-
----
-
-## Step 6: 完成总结 (Completion Summary)
-
-**目标**: 总结产出，并**更新 AGENTS.md** 以反映新版本。
-
-> [!IMPORTANT]
-> **必须完成以下 3 个更新动作**:
->
-> 1. 更新 AGENTS.md "当前状态"
-> 2. 更新 AGENTS.md "项目结构"
-> 3. 更新 AGENTS.md "导航指南"
-
-### 7.1 更新 AGENTS.md
-
-使用 `replace_file_content` 或 `multi_replace_file_content`:
-
-**更新 "📍 当前状态"**:
-
-```markdown
-- **最新架构版本**: `.anws/v{N}`
-- **活动任务清单**: `尚未生成` (等待 /blueprint)
-- **最近一次更新**: `{YYYY-MM-DD}`
-```
-
-**更新 "🌳 项目结构"**:
-
-```markdown
-## 🌳 项目结构 (Project Tree)
-
-> **注意**: 此部分由 `/genesis` 维护。
-
-```text
-{项目根目录}/
-├── .anws/v{N}/            # 架构文档
-├── src/
-│   ├── {system-1}/        # 系统1 源码
-│   └── {system-2}/        # 系统2 源码
-└── ...
-```
-
-**更新 "🧭 导航指南"**:
-
-```markdown
-## 🧭 导航指南 (Navigation Guide)
-
-- **架构总览**: `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
-- **ADR**: 架构决策见 `.anws/v{N}/03_ADR/` (跨系统决策的唯一记录源)
-- **详细设计**: 待 `/design-system` 执行后更新 (将填充 `.anws/v{N}/04_SYSTEM_DESIGN/`)
-- **任务清单**: 待 `/blueprint` 执行后更新 (将生成 `.anws/v{N}/05_TASKS.md`)
-
-### ADR ↔ SYSTEM_DESIGN 关系
-- **ADR** 记录跨系统决策 (如技术栈、认证方式)
-- **SYSTEM_DESIGN** §8 Trade-offs 引用 ADR,不复制决策内容
-- 修改 ADR 时,检查"影响范围"章节,确认引用该 ADR 的系统
-```
-
-> [!NOTE]
-> 如果项目有已知系统，可使用以下格式替代上方"详细设计"行:
->
-> ```markdown
-> - **{System-1}**: 源码 `src/{path1}` → 设计 `.anws/v{N}/04_SYSTEM_DESIGN/{system-1}.md`
-> ```
-
-### 7.2 更新 00_MANIFEST.md
-
-将文档清单中的 checkbox 标记为已完成。
-
-### 7.3 Agent Context 自更新
-
-**更新 `AGENTS.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
-
-仅修改 `<!-- AUTO:BEGIN -->` 和 `<!-- AUTO:END -->` 之间的内容，保留手动添加的内容不变。
-
-```markdown
-### 技术栈决策
-- 语言: {从 tech-evaluator 产出提取}
-- 框架: {从 ADR 提取}
-- 构建工具: {从 ADR 提取}
-
-### 系统边界
-- {system-1}: {一句话职责}
-- {system-2}: {一句话职责}
-
-### 活跃 ADR
-- ADR-001: {标题} — {结论摘要}
-- ADR-002: {标题} — {结论摘要}
-```
-
-> 新版本 `.anws` (v{N+1}) 覆盖旧版本的自动区块内容。
-
-### 7.4 展示产出
-
-告知用户阶段完成，列出产出文档，并指引下一步行动（design-system 或 blueprint）。
-
-- ✅ 创建了 `.anws/v{N}/00_MANIFEST.md` - ✅ 创建了 `.anws/v{N}/06_CHANGELOG.md` - ✅ 生成了 PRD, Architecture Overview, ADRs - ✅ 更新了 AGENTS.md (当前状态、项目结构、导航指南) - ✅ 更新了 AGENTS.md AUTO:BEGIN 区块 (技术栈、系统边界、活跃 ADR) - ✅ 用户已在人类检查点确认
+---
+
+## description: "从 0 到代码的项目启动全流程。适用于新项目立项、重大功能重构或架构升级。产出 PRD、Architecture Overview、ADR、concept_model.json 等核心文档，建立版本化架构基础。"
+
+# /genesis
+
+你是 **Genesis - 项目创世专家**。
+
+**你的核心使命**：
+将用户模糊的想法转化为**清晰的文档基础**，完成从0到文档的全流程设计。
+
+**核心原则**：
+
+- **版本化架构** - 架构文档必须版本化 (`.anws/v1`, `.anws/v2`...)
+- **文档先行** - 代码是文档的实现，而非相反
+- **产品优先** - 先PRD后技术，先需求后方案
+- **系统拆解** - 识别独立系统，关注点分离
+- **Git 分支换轨** - `/genesis` 代表版本前提变化；旧 `feature/`* 应冻结，新版本应从最新 `main` 重新开一条新的 `feature/*`
+
+**Output Goal (Versioned)**:
+
+- `.anws/v{N}/00_MANIFEST.md` ← 版本元数据
+- `.anws/v{N}/01_PRD.md`
+- `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
+- `.anws/v{N}/03_ADR/`*
+- `.anws/v{N}/06_CHANGELOG.md` ← 变更日志
+
+---
+
+## Pre-Check: 自动初始化 (Auto-Init)
+
+> **目的**: 确保项目已正确初始化，无 AGENTS.md 则自动创建。
+
+> [!IMPORTANT]
+> **Git 换轨前置规则**：
+> 如果 `/genesis` 是从一个正在开发中的 `feature/`* 分支升级而来，先冻结旧分支；必要时创建 checkpoint / freeze commit。随后从最新 `main` 重新开一条新的 `feature/*` 承接新版本，不要把旧分支上的实现和新版本文档混在一起。
+
+### 自动检测流程
+
+1. **检测项目状态**:
+  - 检查项目根目录是否存在 `AGENTS.md`
+  - 检查项目根目录是否存在 `.anws/` 目录
+2. **状态判断**:
+  ```
+   ├──  有 AGENTS.md 且有 .anws/
+   │   └── 项目已初始化 → 直接进入 Step 0
+   │
+   ├──  有 AGENTS.md 但无 .anws/
+   │   └── 异常状态 → 创建 .anws/ 目录结构
+   │
+   └──  无 AGENTS.md
+       └── 全新项目 → 执行自动初始化
+  ```
+3. **自动初始化流程** (仅当无 AGENTS.md 时):
+  **3.1 调用 CLI 初始化**:
+   执行以下命令完成项目初始化:
+   **3.2 输出初始化确认**:
+   告知用户已完成初始化:
+4. **进入 Step 0**:
+  初始化完成后，自动进入 Step 0: 版本管理。
+
+---
+
+## CRITICAL 流程约束
+
+> [!IMPORTANT]
+> **严格的执行顺序** (CRITICAL):
+>
+> - 你**必须**按照 Step 0 → Step 1 → Step 2 → ... → Step 7 的顺序执行。
+> - **禁止乱序执行**。
+> - **禁止提前阅读** Skill 文档。
+> - **必须**严格遵守版本管理逻辑 (Step 0)。
+
+---
+
+## Step 0: 版本管理 (Version Management)
+
+**目标**: 确定当前架构版本，并准备新的工作空间。
+
+> [!IMPORTANT]
+> 我们从不直接修改旧的架构文档。我们永远是 **Copy & Evolve**。
+
+1. **检查现有版本**:
+  扫描 `.anws/` 目录，找到所有 `v{N}` 版本文件夹。
+2. **确定目标版本**:
+  - 如果 `.anws/` 为空 -> 目标是 `v1`。
+    - 如果存在 `v1`, `v2` -> 目标是 `v3`。
+3. **准备工作空间**:
+  - **Case A (新项目)**:
+    创建目录结构: `.anws/v1/03_ADR` 和 `.anws/v1/04_SYSTEM_DESIGN`
+    - **Case B (迭代更新)**:
+    创建目录 `.anws/v{N+1}` (例如 v3)，复制 `.anws/v{N}/*` 到新目录，清理旧任务文件 (如 `.anws/v{N}/05_TASKS.md`)
+4. **初始化版本文件**:
+  创建 `.anws/v{N}/00_MANIFEST.md`:
+5. **初始化变更日志**:
+  创建 `.anws/v{N}/06_CHANGELOG.md`:
+6. **设定上下文变量**:
+  - 在接下来的所有步骤中，输出路径指向 `**.anws/v{N}/...`**
+    - *Self-Correction*: "我现在的 Target Dir 是 `.anws/v{N}`"
+
+---
+
+## Step 1: 需求澄清 (Requirement Clarification)
+
+> [!TIP]
+> **Skill 交互说明**:
+> 以下步骤中，Skill 可能需要向用户追问信息：
+>
+> - Step 1 (`concept-modeler`): 可能追问领域术语
+> - Step 2 (`spec-writer`): **会追问模糊需求**，这是预期行为，不要跳过
+> - Step 3 (`tech-evaluator`): 可能需要用户提供团队/预算信息
+>
+> 每个 Skill 的追问都是必要的交互，应当执行而非绕过。
+
+**目标**: 从用户的模糊想法中提取**领域概念**。
+
+1. **调用技能**: `concept-modeler`
+2. **执行建模**:
+  - 名词捕捉 (Entities)
+  - 动词分析 (Flows)
+  - 暗物质探测 (Missing)
+3. **输出**: 保存到 `.anws/v{N}/concept_model.json`
+
+---
+
+## Step 2: PRD 生成 (PRD Generation)
+
+**目标**: 将需求转化为**产品需求文档**。
+
+1. **调用技能**: `spec-writer`
+2. **执行撰写**:
+  - 基于用户需求
+  - 分配 ID `[REQ-XXX]`
+  - Given-When-Then 验收标准
+3. **输出**: 保存到 `.anws/v{N}/01_PRD.md`
+
+**人类检查点 #1** :
+
+- 确认 PRD Goals & User Stories。
+
+---
+
+## Step 2.5: 研究闸门 (Explore Gate)
+
+**目标**: 在高不确定性决策进入技术评估与 ADR 前，按需补充外部调研。
+
+> [!IMPORTANT]
+> **此步骤是条件触发，不是默认必跑。**
+>
+> **满足任一条件时，应插入 `/explore*`*:
+>
+> - 技术方案存在明显不确定性，需要先调研再比较
+> - 决策涉及 UI 风格、交互模式、工作台信息架构等高专业度问题
+> - 用户明确要求对标某个产品、行业实践或最佳实践
+> - 该 ADR 需要外部证据支撑，而非仅靠内部推导
+> - 需要检索可复用的方法论、检查框架或技能资产
+> - 需要先明确测试策略、质量门禁或验证分层，再决定架构和任务模板
+
+ **执行方式**:
+
+1. **判断是否触发**: 基于 PRD、用户原话和预期 ADR 类型判断是否需要研究前置
+2. **如需触发**: 调用 `/explore`，产出结构化研究结论
+  - 如问题涉及方法论、专业框架、测试策略或设计启发，可在 `/explore` 中按需使用 `find-skills`
+  - 如果运行环境中没有可用的 `find-skills`，则直接退化为普通搜索与结构化调研，不得阻塞 workflow
+3. **使用研究结果**:
+  - 为 Step 3 的技术评估补充候选方案、对比维度和外部证据
+  - 为 Step 5 的 ADR 提供决策理由、Trade-off 和影响分析输入
+  - 如研究结果涉及测试金字塔、冒烟/回归策略、质量门禁，应在 Step 5 或后续设计文档中明确沉淀
+4. **如不触发**: 直接进入 Step 3
+
+> [!NOTE]
+> `/explore` 提供的是**研究证据和方法论增量**，不是 ADR 的替代品。
+> 正式决策仍在 Step 5 写入 ADR 文件。
+
+---
+
+## Step 3: 技术选型 (Tech Stack Selection)
+
+> [!TIP]
+> **Skill 交互说明**:
+> 以下步骤中，Skill 可能需要向用户追问信息：
+>
+> - Step 2 (`spec-writer`): **会追问模糊需求**，这是预期行为，不要跳过
+> - Step 3 (`tech-evaluator`): 可能需要用户提供团队/预算信息
+>
+> 每个 Skill 的追问都是必要的交互，应当执行而非绕过。
+
+ **目标**: 评估技术栈候选方案,为 Step 5 的 ADR 决策提供依据。
+
+> [!IMPORTANT]
+> **技术选型不仅包括运行时和框架，还应审视验证策略。**
+>
+> 至少需要明确以下问题是否要进入 ADR 或后续设计文档：
+>
+> - 本项目主要依赖单元测试、集成测试、E2E测试中的哪些层
+> - 是否需要里程碑级冒烟测试
+> - 是否需要发布前或高风险改动后的回归测试
+> - 测试运行的主要门禁放在 PR、INT、预发布还是发布前
+
+> [!IMPORTANT]
+> 你**必须**只输出评估结果,**不要提前写入 ADR 文件**。
+>
+> **为什么**: ADR 是正式决策记录,需要在 Step 5 经过完整审视后才能写入。Step 3 只负责技术评估,不做最终决策。
+
+1. **调用技能**: `tech-evaluator`
+  1. **执行评估**:
+    - 基于 PRD 约束
+    - 如 Step 2.5 已触发，则吸收研究结论中的候选方案、评估维度和约束
+    - 评估与该项目类型匹配的测试策略与质量门禁
+    - 12 维度评估
+  2. **输出**: 候选方案对比表 (Markdown 格式,暂存在内存中,不写入文件)
+
+---
+
+## Step 4: 系统拆解 (System Decomposition)
+
+**目标**: 识别项目中的独立系统，定义系统边界。
+
+1. **调用技能**: `system-architect`
+2. **使用系统识别框架**:
+  - 用户接触点 / 数据存储 / 核心逻辑 / 外部集成
+3. **定义系统**:
+  - ID / 职责 / 边界 / 依赖
+4. **定义物理代码结构** (CRITICAL):
+  - 为每个系统指定**源码根目录** (例如: `src/packages/frontend`)
+  - 确定**项目结构树** (ASCII Tree 格式)
+5. **输出**: 保存到 `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
+
+**人类检查点 #2** :
+
+- 确认系统拆分合理性。
+
+---
+
+## Step 5: 架构决策 (Architecture Decisions)
+
+**目标**: 基于 Step 3 的技术评估,正式记录架构决策 (ADR)。
+
+> [!IMPORTANT]
+> 你**必须**基于 Step 3 的候选方案对比表,正式写入 ADR 文件。
+>
+> **为什么**: ADR 是跨系统决策的唯一记录源,后续 SYSTEM_DESIGN 会引用它。
+
+1. **基于 Step 3 评估**: 将 Step 3 的候选方案对比表转化为正式 ADR
+2. **吸收 Step 2.5 研究结论** (如有): 将外部调研、对标发现和方法论证据纳入决策理由与 Trade-off
+3. **使用 ADR 模板**: 参考 `tech-evaluator` skill 的 ADR_TEMPLATE.md
+4. **如测试策略属于跨系统约束**: 记录测试分层、冒烟/回归门禁、关键验证时机等决策
+5. **输出**: 保存到 `.anws/v{N}/03_ADR/ADR_001_TECH_STACK.md`
+6. **识别其他决策**: 认证方式、通讯协议、测试门禁等跨系统决策
+7. **输出其他 ADR**: 保存到 `.anws/v{N}/03_ADR/ADR_00X_*.md`
+
+**检查清单**:
+
+- ADR 包含"影响范围"章节
+- ADR 状态为 `Accepted`
+- 决策理由清晰,有候选方案对比
+
+---
+
+## Step 6: 完成总结 (Completion Summary)
+
+**目标**: 总结产出，并**更新 AGENTS.md** 以反映新版本。
+
+> [!IMPORTANT]
+> **必须完成以下 3 个更新动作**:
+>
+> 1. 更新 AGENTS.md "当前状态"
+> 2. 更新 AGENTS.md "项目结构"
+> 3. 更新 AGENTS.md "导航指南"
+
+### 7.1 更新 AGENTS.md
+
+使用 `replace_file_content` 或 `multi_replace_file_content`:
+
+**更新 " 当前状态"**:
+
+```markdown
+- **最新架构版本**: `.anws/v{N}`
+- **活动任务清单**: `尚未生成` (等待 /blueprint)
+- **最近一次更新**: `{YYYY-MM-DD}`
+```
+
+**更新 " 项目结构"**:
+
+```markdown
+## 项目结构 (Project Tree)
+
+> **注意**: 此部分由 `/genesis` 维护。
+
+```text
+{项目根目录}/
+├── .anws/v{N}/            # 架构文档
+├── src/
+│   ├── {system-1}/        # 系统1 源码
+│   └── {system-2}/        # 系统2 源码
+└── ...
+```
+
+**更新 " 导航指南"**:
+
+```markdown
+## 导航指南 (Navigation Guide)
+
+- **架构总览**: `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
+- **ADR**: 架构决策见 `.anws/v{N}/03_ADR/` (跨系统决策的唯一记录源)
+- **详细设计**: 待 `/design-system` 执行后更新 (将填充 `.anws/v{N}/04_SYSTEM_DESIGN/`)
+- **任务清单**: 待 `/blueprint` 执行后更新 (将生成 `.anws/v{N}/05_TASKS.md`)
+
+### ADR  SYSTEM_DESIGN 关系
+- **ADR** 记录跨系统决策 (如技术栈、认证方式)
+- **SYSTEM_DESIGN** §8 Trade-offs 引用 ADR,不复制决策内容
+- 修改 ADR 时,检查"影响范围"章节,确认引用该 ADR 的系统
+```
+
+> [!NOTE]
+> 如果项目有已知系统，可使用以下格式替代上方"详细设计"行:
+>
+> ```markdown
+> - **{System-1}**: 源码 `src/{path1}` → 设计 `.anws/v{N}/04_SYSTEM_DESIGN/{system-1}.md`
+> ```
+
+### 7.2 更新 00_MANIFEST.md
+
+将文档清单中的 checkbox 标记为已完成。
+
+### 7.3 Agent Context 自更新
+
+**更新 `AGENTS.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
+
+仅修改 `<!-- AUTO:BEGIN -->` 和 `<!-- AUTO:END -->` 之间的内容，保留手动添加的内容不变。
+
+```markdown
+### 技术栈决策
+- 语言: {从 tech-evaluator 产出提取}
+- 框架: {从 ADR 提取}
+- 构建工具: {从 ADR 提取}
+
+### 系统边界
+- {system-1}: {一句话职责}
+- {system-2}: {一句话职责}
+
+### 活跃 ADR
+- ADR-001: {标题} — {结论摘要}
+- ADR-002: {标题} — {结论摘要}
+```
+
+> 新版本 `.anws` (v{N+1}) 覆盖旧版本的自动区块内容。
+
+### 7.4 展示产出
+
+告知用户阶段完成，列出产出文档，并指引下一步行动（design-system 或 blueprint）。
+
+- 创建了 `.anws/v{N}/00_MANIFEST.md` -  创建了 `.anws/v{N}/06_CHANGELOG.md` -  生成了 PRD, Architecture Overview, ADRs -  更新了 AGENTS.md (当前状态、项目结构、导航指南) -  更新了 AGENTS.md AUTO:BEGIN 区块 (技术栈、系统边界、活跃 ADR) -  用户已在人类检查点确认