@haaaiawd/anws 1.2.5 → 2.0.1

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

@@ -1,5 +1,5 @@
 ---
-description: 从 0 到代码的项目启动全流程，将模糊想法转化为清晰的 PRD、架构文档和 ADR，适用于新项目立项、重大功能重构或架构升级。
+description: "从 0 到代码的项目启动全流程。适用于新项目立项、重大功能重构或架构升级。产出 PRD、Architecture Overview、ADR、concept_model.json 等核心文档，建立版本化架构基础。"
 ---
 
 # /genesis
@@ -11,18 +11,17 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 将用户模糊的想法转化为**清晰的文档基础**，完成从0到文档的全流程设计。
 
 **核心原则**：
-- **版本化架构** - 架构文档必须版本化 (`genesis/v1`, `genesis/v2`...)
+- **版本化架构** - 架构文档必须版本化 (`.anws/v1`, `.anws/v2`...)
 - **文档先行** - 代码是文档的实现，而非相反
 - **产品优先** - 先PRD后技术，先需求后方案
 - **系统拆解** - 识别独立系统，关注点分离
 
 **Output Goal (Versioned)**: 
-- `genesis/v{N}/00_MANIFEST.md` ← 版本元数据
-- `genesis/v{N}/concept_model.json`
-- `genesis/v{N}/01_PRD.md`
-- `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`
-- `genesis/v{N}/03_ADR/*`
-- `genesis/v{N}/06_CHANGELOG.md` ← 变更日志
+- `.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` ← 变更日志
 </phase_context>
 
 ---
@@ -46,23 +45,23 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 > 我们从不直接修改旧的架构文档。我们永远是 **Copy & Evolve**。
 
 1.  **检查现有版本**:
-    扫描 `genesis/` 目录，找到所有 `v{N}` 版本文件夹。
+    扫描 `.anws/` 目录，找到所有 `v{N}` 版本文件夹。
 
 2.  **确定目标版本**:
-    - 如果 `genesis/` 为空 -> 目标是 `v1`。
+    - 如果 `.anws/` 为空 -> 目标是 `v1`。
     - 如果存在 `v1`, `v2` -> 目标是 `v3`。
 
 3.  **准备工作空间**:
     - **Case A (新项目)**:
-      创建目录结构: `genesis/v1/03_ADR` 和 `genesis/v1/04_SYSTEM_DESIGN`
+      创建目录结构: `.anws/v1/03_ADR` 和 `.anws/v1/04_SYSTEM_DESIGN`
 
     - **Case B (迭代更新)**:
-      创建目录 `genesis/v{N+1}` (例如 v3)，复制 `genesis/v{N}/*` 到新目录，清理旧任务文件 (如 `genesis/v{N}/05_TASKS.md`)
+      创建目录 `.anws/v{N+1}` (例如 v3)，复制 `.anws/v{N}/*` 到新目录，清理旧任务文件 (如 `.anws/v{N}/05_TASKS.md`)
 
 4.  **初始化版本文件**:
-    创建 `genesis/v{N}/00_MANIFEST.md`:
+    创建 `.anws/v{N}/00_MANIFEST.md`:
     ```markdown
-    # Genesis v{N} - 版本清单
+    # .anws v{N} - 版本清单
 
     **创建日期**: {YYYY-MM-DD}
     **状态**: Active
@@ -86,9 +85,9 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
     ```
 
 5.  **初始化变更日志**:
-    创建 `genesis/v{N}/06_CHANGELOG.md`:
+    创建 `.anws/v{N}/06_CHANGELOG.md`:
     ```markdown
-    # 变更日志 - Genesis v{N}
+    # 变更日志 - .anws v{N}
 
     > 此文件记录本版本迭代过程中的微调变更（由 /change 处理）。新增功能/任务需创建新版本（由 /genesis 处理）。
 
@@ -100,12 +99,12 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
     ---
 
     ## {YYYY-MM-DD} - 初始化
-    - [ADD] 创建 Genesis v{N} 版本
+    - [ADD] 创建 `.anws` v{N} 版本
     ```
 
 6.  **设定上下文变量**:
-    - 在接下来的所有步骤中，输出路径指向 **`genesis/v{N}/...`**
-    - *Self-Correction*: "我现在的 Target Dir 是 `genesis/v{N}`"
+    - 在接下来的所有步骤中，输出路径指向 **`.anws/v{N}/...`**
+    - *Self-Correction*: "我现在的 Target Dir 是 `.anws/v{N}`"
 
 ---
 
@@ -127,7 +126,7 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
     *   名词捕捉 (Entities)
     *   动词分析 (Flows)
     *   暗物质探测 (Missing)
-3.  **输出**: 保存到 `genesis/v{N}/concept_model.json`
+3.  **输出**: 保存到 `.anws/v{N}/concept_model.json`
 
 ---
 
@@ -137,10 +136,10 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 
 1.  **调用技能**: `spec-writer`
 2.  **执行撰写**:
-    *   基于 `concept_model.json`
+    *   基于用户需求
     *   分配 ID `[REQ-XXX]`
     *   Given-When-Then 验收标准
-3.  **输出**: 保存到 `genesis/v{N}/01_PRD.md`
+3.  **输出**: 保存到 `.anws/v{N}/01_PRD.md`
 
 **人类检查点 #1** ⚠️:
 - 确认 PRD Goals & User Stories。
@@ -149,13 +148,26 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 
 ## Step 3: 技术选型 (Tech Stack Selection)
 
-**目标**: 选择最适合项目的技术栈。
+> [!TIP]
+> **Skill 交互说明**:
+> 以下步骤中，Skill 可能需要向用户追问信息：
+> - Step 2 (`spec-writer`): **会追问模糊需求**，这是预期行为，不要跳过
+> - Step 3 (`tech-evaluator`): 可能需要用户提供团队/预算信息
+> 
+> 每个 Skill 的追问都是必要的交互，应当执行而非绕过。
+
+**目标**: 评估技术栈候选方案,为 Step 5 的 ADR 决策提供依据。
+
+> [!IMPORTANT]
+> 你**必须**只输出评估结果,**不要提前写入 ADR 文件**。
+>
+> **为什么**: ADR 是正式决策记录,需要在 Step 5 经过完整审视后才能写入。Step 3 只负责技术评估,不做最终决策。
 
 1.  **调用技能**: `tech-evaluator`
 2.  **执行评估**:
     *   基于 PRD 约束
     *   12 维度评估
-3.  **输出**: 保存到 `genesis/v{N}/03_ADR/ADR_001_TECH_STACK.md`
+3.  **输出**: 候选方案对比表 (Markdown 格式,暂存在内存中,不写入文件)
 
 ---
 
@@ -171,32 +183,36 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 4.  **定义物理代码结构** (CRITICAL):
     *   为每个系统指定**源码根目录** (例如: `src/packages/frontend`)
     *   确定**项目结构树** (ASCII Tree 格式)
-5.  **输出**: 保存到 `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`
+5.  **输出**: 保存到 `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
 
 **人类检查点 #2** ⚠️:
 - 确认系统拆分合理性。
 
 ---
 
-## Step 5: 架构决策 (Architecture Decisions) - Optional
+## Step 5: 架构决策 (Architecture Decisions)
 
-**目标**: 记录重大架构决策 (ADR)。
+**目标**: 基于 Step 3 的技术评估,正式记录架构决策 (ADR)。
 
-1.  **识别决策**: 认证方式、通讯协议等。
-2.  **输出**: 保存到 `genesis/v{N}/03_ADR/ADR_00X_*.md`
-
----
-
-## Step 6: 复杂度审计 (Complexity Audit) - Optional
+> [!IMPORTANT]
+> 你**必须**基于 Step 3 的候选方案对比表,正式写入 ADR 文件。
+>
+> **为什么**: ADR 是跨系统决策的唯一记录源,后续 SYSTEM_DESIGN 会引用它。
 
-**目标**: 审核架构是否有过度设计。
+1.  **基于 Step 3 评估**: 将 Step 3 的候选方案对比表转化为正式 ADR
+2.  **使用 ADR 模板**: 参考 `tech-evaluator` skill 的 ADR_TEMPLATE.md
+3.  **输出**: 保存到 `.anws/v{N}/03_ADR/ADR_001_TECH_STACK.md`
+4.  **识别其他决策**: 认证方式、通讯协议等跨系统决策
+5.  **输出其他 ADR**: 保存到 `.anws/v{N}/03_ADR/ADR_00X_*.md`
 
-1.  **调用技能**: `complexity-guard`
-2.  **输出**: 审计报告 (内联或单独文件)。
+**检查清单**:
+- [ ] ADR 包含"影响范围"章节
+- [ ] ADR 状态为 `Accepted`
+- [ ] 决策理由清晰,有候选方案对比
 
 ---
 
-## Step 7: 完成总结 (Completion Summary)
+## Step 6: 完成总结 (Completion Summary)
 
 **目标**: 总结产出，并**更新 AGENTS.md** 以反映新版本。
 
@@ -212,7 +228,7 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 
 **更新 "📍 当前状态"**:
 ```markdown
-- **最新架构版本**: `genesis/v{N}`
+- **最新架构版本**: `.anws/v{N}`
 - **活动任务清单**: `尚未生成` (等待 /blueprint)
 - **最近一次更新**: `{YYYY-MM-DD}`
 ```
@@ -225,7 +241,7 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 
 ```text
 {项目根目录}/
-├── genesis/v{N}/          # 架构文档
+├── .anws/v{N}/            # 架构文档
 ├── src/
 │   ├── {system-1}/        # 系统1 源码
 │   └── {system-2}/        # 系统2 源码
@@ -236,16 +252,21 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 ```markdown
 ## 🧭 导航指南 (Navigation Guide)
 
-- **架构总览**: `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`
-- **ADR**: 架构决策见 `genesis/v{N}/03_ADR/`
-- **详细设计**: 待 `/design-system` 执行后更新 (将填充 `genesis/v{N}/04_SYSTEM_DESIGN/`)
-- **任务清单**: 待 `/blueprint` 执行后更新 (将生成 `genesis/v{N}/05_TASKS.md`)
+- **架构总览**: `.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}` → 设计 `genesis/v{N}/04_SYSTEM_DESIGN/{system-1}.md`
+> - **{System-1}**: 源码 `src/{path1}` → 设计 `.anws/v{N}/04_SYSTEM_DESIGN/{system-1}.md`
 > ```
 
 ### 7.2 更新 00_MANIFEST.md
@@ -273,27 +294,18 @@ description: 从 0 到代码的项目启动全流程，将模糊想法转化为
 - ADR-002: {标题} — {结论摘要}
 ```
 
-> 新版本 genesis (v{N+1}) 覆盖旧版本的自动区块内容。
+> 新版本 `.anws` (v{N+1}) 覆盖旧版本的自动区块内容。
 
 ### 7.4 展示产出
 
 告知用户阶段完成，列出产出文档，并指引下一步行动（design-system 或 blueprint）。
 
 <completion_criteria>
-- ✅ 创建了 `genesis/v{N}/00_MANIFEST.md`
-- ✅ 创建了 `genesis/v{N}/06_CHANGELOG.md`
+- ✅ 创建了 `.anws/v{N}/00_MANIFEST.md`
+- ✅ 创建了 `.anws/v{N}/06_CHANGELOG.md`
 - ✅ 生成了 PRD, Architecture Overview, ADRs
 - ✅ 更新了 AGENTS.md (当前状态、项目结构、导航指南)
 - ✅ 更新了 AGENTS.md AUTO:BEGIN 区块 (技术栈、系统边界、活跃 ADR)
 - ✅ 用户已在人类检查点确认
 </completion_criteria>
 
----
-
-## 🔀 Handoffs
-
-完成本工作流后，根据情况选择：
-
-- **设计系统详细架构** → `/design-system` — 为 {system-id} 设计详细架构 *(项目包含复杂系统时)*
-- **生成任务清单** → `/blueprint` — 将架构拆解为可执行任务
-- **质疑设计决策** → `/challenge` — 对当前设计进行系统性挑战

package/templates/.agents/workflows/probe.md

@@ -0,0 +1,168 @@
+---
+description: "探测系统风险、隐藏耦合和架构暗坑。适用于接手遗留项目、重大变更前的风险评估。产出 00_PROBE_REPORT.md（含系统指纹、构建/运行时拓扑、Git 热点、风险矩阵）。"
+---
+
+# /probe
+
+<phase_context>
+你是 **Probe - 系统探测专家**。
+
+**核心使命**：
+在架构更新 (`.anws/v{N}`) 之前或之后，探测系统风险、暗坑和耦合。
+探测结果将作为**输入**反馈给 Architectural Overview。
+
+**核心能力**：
+- 调用 `nexus-mapper` 执行完整 PROBE 五阶段协议
+- 调用 `runtime-inspector` 补充进程边界分析
+- 产出风险矩阵和 Gap Analysis
+
+**你的限制**：
+- 不修改架构，只**观测**和**报告**
+- 不重复 skill 内部逻辑，只负责编排调用
+
+**与用户的关系**：
+你是用户的**侦察兵**，为重大决策提供情报支撑。
+
+**Output Goal**: `.anws/v{N}/00_PROBE_REPORT.md`
+</phase_context>
+
+---
+
+## ⚠️ CRITICAL 流程约束
+
+> [!IMPORTANT]
+> Probe 不修改架构，只**观测**和**报告**。
+> 你的报告应该被 Genesis 过程参考。
+>
+> **为什么？** 探测的目的是发现问题，而非解决问题。混在一起会导致视角偏差。
+
+> [!NOTE]
+> **Probe 双模式说明**:
+> - **模式 A (Genesis 前)**: 侦察遗留代码，产出作为 genesis 的输入
+> - **模式 B (Genesis 后)**: 验证设计与代码的一致性 (Gap Analysis)
+>
+> 判断方式: 如果 `.anws/v{N}/` 存在 → 模式 B，执行对比分析
+> 如果不存在 → 模式 A，仅提取代码现状
+
+---
+
+## Step 1: 执行 nexus-mapper PROBE 协议
+
+**目标**: 完成项目深度探测，产出 `.nexus-map/` 知识库。
+
+> [!IMPORTANT]
+> 你**必须**调用 `nexus-mapper` 执行完整的 PROBE 五阶段协议。
+>
+> **为什么？** nexus-mapper 已整合了构建拓扑、Git 热点、领域概念分析能力，一次调用即可获得完整的项目认知。
+
+**调用技能**: `nexus-mapper`
+
+**nexus-mapper 内置能力**:
+- **PROFILE**: AST 提取、文件树、语言覆盖
+- **REASON**: 构建拓扑、依赖分析（原 build-inspector 功能）
+- **OBJECT**: 质疑验证、三维度分析
+- **BENCHMARK**: Git 热点、耦合对分析（原 git-forensics 功能）
+- **EMIT**: 概念模型、知识库生成（原 concept-modeler 功能）
+
+**输出**: `.nexus-map/` 目录，包含：
+- `INDEX.md` — AI 冷启动入口
+- `arch/systems.md` — 系统边界
+- `arch/dependencies.md` — Mermaid 依赖图
+- `concepts/concept_model.json` — 机器可读概念模型
+- `hotspots/git_forensics.md` — Git 热点分析
+
+---
+
+## Step 2: 补充运行时拓扑分析
+
+**目标**: 追踪进程间通信和契约状态（nexus-mapper 不覆盖此领域）。
+
+**调用技能**: `runtime-inspector`
+
+**思考引导**:
+1. "进程边界在哪里？通信协议是什么？"
+2. "有没有僵尸进程或协议漂移风险？"
+3. "契约是强类型还是隐式约定？"
+
+**输出**: Process Roots + Contract Status
+
+---
+
+## Step 3: Gap Analysis (模式 B)
+
+**目标**: 对比代码实现与架构文档的偏差。
+
+> [!IMPORTANT]
+> 仅在 `.anws/v{N}/` 存在时执行此步骤。
+
+**Gap Analysis 内容**:
+- 将 `.nexus-map/concepts/concept_model.json` 与 `.anws/v{N}/` 中的架构定义对比
+- 识别文档与实现的偏差
+- 标记概念漂移或隐式设计
+
+**思考引导**:
+1. "代码中实际存在哪些领域概念？"
+2. "与架构文档描述是否一致？"
+3. "有没有概念漂移或隐式设计？"
+
+---
+
+## Step 4: 风险矩阵
+
+**目标**: 综合分析，识别 "Change Impact"。
+
+**思考引导**:
+1. "如果进行 Genesis 更新，新需求会触碰哪些热点？"
+2. "哪些风险是阻塞性的？哪些是可接受的？"
+3. "有没有'改了就炸'的暗坑？"
+
+**输出**: Risk Matrix (按严重度分级)
+
+---
+
+## Step 5: 生成报告
+
+**目标**: 保存探测报告。
+
+> [!IMPORTANT]
+> 报告必须保存到 `.anws/v{N}/00_PROBE_REPORT.md`。
+> 如果版本不存在，默认为 v1。
+
+**报告模板**:
+
+```markdown
+# PROBE Report
+
+**探测时间**: [时间戳]
+**探测模式**: [模式 A/B]
+
+## 1. System Fingerprint
+[项目结构概览]
+
+## 2. Build Topology
+[构建边界和依赖]
+
+## 3. Runtime Topology
+[进程边界和契约]
+
+## 4. Temporal Topology
+[历史耦合和热点]
+
+## 5. Gap Analysis
+[文档 vs 代码偏差]
+
+## 6. Risk Matrix
+
+| 风险 | 严重度 | 影响 | 建议 |
+| ---- | :----: | ---- | ---- |
+| ... | 🔴/🟡/🟢 | ... | ... |
+```
+
+<completion_criteria>
+- ✅ 建立了系统指纹
+- ✅ 识别了构建和运行时拓扑
+- ✅ 发现了历史耦合热点
+- ✅ 完成了 Gap Analysis
+- ✅ 产出了风险矩阵
+</completion_criteria>
+

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

@@ -1,5 +1,5 @@
 ---
-description: 智能编排全流程（scout → genesis → design → blueprint → challenge → forge）。
+description: "智能编排全流程。适用于不确定从哪个工作流开始的场景。自动诊断项目状态，按需调度 probe → genesis → design-system → blueprint → challenge → forge。"
 ---
 
 # /quickstart
@@ -18,8 +18,8 @@ description: 智能编排全流程（scout → genesis → design → blueprint
 
 ### 状态矩阵
 ```
-├── 🛑 无 genesis/ 
-│   ├── 有代码 → 🏚️ [遗留项目] → Jump to Step 0.5 (Scout)
+├── 🛑 无 .anws/ 
+│   ├── 有代码 → 🏚️ [遗留项目] → Jump to Step 0.5 (Probe)
 │   └── 无代码 → 🆕 [全新项目] → Jump to Step 1 (Genesis)
 ├── 📝 有架构 (无任务)
 │   ├── 有系统设计 → Step 3 (Challenge Design)
@@ -33,10 +33,10 @@ description: 智能编排全流程（scout → genesis → design → blueprint
 
 ---
 
-## Step 0.5: 侦察 (Scout)
+## Step 0.5: 探测 (Probe)
 
-**触发**: 遗留项目。通过 `/scout` 探测暗地里的风险与耦合。
-**产出**: `00_SCOUT_REPORT.md` (Genesis 的重要输入)。
+**触发**: 遗留项目。通过 `/probe` 探测暗地里的风险与耦合。
+**产出**: `.anws/v{N}/00_PROBE_REPORT.md` (Genesis 的重要输入)。
 
 ---
 
@@ -86,12 +86,7 @@ description: 智能编排全流程（scout → genesis → design → blueprint
 **场景**: 项目开发中。
 **建议建议**:
 - `/forge` — 继续执行任务
-- `/scout` — 重大变更前探测风险
+- `/probe` — 重大变更前探测风险
 - `/genesis` — 架构大版本升级
 - `/change` — 微调任务细节
 
----
-
-## 🔀 快速跳转 (Handoffs)
-
-- `/scout` | `/genesis` | `/blueprint` | `/challenge` | `/forge`

package/templates/.agents/workflows/upgrade.md

@@ -0,0 +1,192 @@
+---
+description: "在执行 anws update 后，读取 .anws/changelog/vX.Y.Z.md，判断升级等级（Minor / Major），生成人类可审核的升级计划，并路由到 /change 或 /genesis 执行后续修改。"
+---
+
+# /upgrade
+
+<phase_context>
+你是 **UPGRADE ORCHESTRATOR (升级编排师)**。
+
+**核心使命**：
+在 `anws update` 执行完成后，读取 `.anws/changelog/` 中最新的升级记录，分析框架层变化对业务文档的影响，判断应走 `/change` 还是 `/genesis`，并在获得人类批准后**路由到对应工作流继续执行**。
+
+**核心原则**：
+- **changelog 是升级依据** - 不凭印象升级，必须读取 `.anws/changelog/vX.Y.Z.md`
+- **先定级，后路由** - 先判断 Minor / Major，再决定调用 `/change` 还是 `/genesis`
+- **保护业务常量** - 禁止覆盖业务域名词、业务规则、产品约束
+- **upgrade 只负责编排** - `/upgrade` 不自行绕过规范直接改文档，实际写操作必须遵循被路由工作流
+- **人类审批** - 写操作前必须先展示升级计划，等待用户批准
+
+**Output Goal**:
+- 输出升级等级：`Minor` / `Major`
+- 输出升级计划：影响范围、受影响文档、风险提示、推荐路由
+- 获得人类批准后，明确切换到 `/change` 或 `/genesis`
+</phase_context>
+
+---
+
+## ⚠️ CRITICAL 执行顺序
+
+> [!IMPORTANT]
+> 必须严格按 Step 0 → Step 1 → Step 2 → Step 3 → Step 4 执行。
+> 禁止跳过 changelog 读取，禁止未定级先决定路由，禁止绕过人类检查点，禁止不读 `/change` 或 `/genesis` 就直接落笔。
+
+---
+
+## Step 0: 定位升级输入
+
+1. 扫描 `.anws/changelog/`
+2. 找到最新的 `vX.Y.Z.md`
+3. 读取最新升级记录，提取：
+   - 文件级变更
+   - 内容级变更详情
+   - 可能受影响的 workflow / skill / template
+4. 扫描 `.anws/` 目录，找到最新的架构版本 `v{N}`
+5. 设定上下文变量：
+   - `LATEST_CHANGELOG = .anws/changelog/vX.Y.Z.md`
+   - `CURRENT_ARCH = .anws/v{N}`
+
+**若缺失任一目录**：停止并提示用户先运行 `anws update` 或 `/genesis`。
+
+---
+
+## Step 1: 升级定级 (Minor / Major)
+
+> [!IMPORTANT]
+> 升级类型由 AI 判断，不从 changelog 静态读取。
+> **不再使用 Patch 级别**，只保留 `Minor` 与 `Major`，因为 `/upgrade` 的目标是决定跳转逻辑，而不是表达实现细粒度。
+
+使用以下判定规则：
+
+| 级别 | 判定标准 |
+|------|---------|
+| Minor | 变更可在当前版本内通过 `/change` 完成，不需要创建新的架构版本 |
+| Major | 版本目录规则变化、核心工作流协议变化、架构边界变化、需要新版本承载 |
+
+### 强制评估问题
+
+1. 是否改变版本目录或核心路径约定？
+2. 是否改变多个工作流的执行协议？
+3. 是否影响 `01_PRD.md`、`02_ARCHITECTURE_OVERVIEW.md`、`03_ADR/` 的结构语义？
+4. 是否需要保留旧版架构文档作为兼容参考？
+
+**判定逻辑**：
+- 影响局部文档、无需新版本 → `Minor`
+- 需要新版本承载、会改变架构语义或目录协议 → `Major`
+
+---
+
+## Step 2: 影响分析与路由建议
+
+1. 读取 `CURRENT_ARCH` 下的以下文件（按需）:
+   - `01_PRD.md`
+   - `02_ARCHITECTURE_OVERVIEW.md`
+   - `03_ADR/*`
+   - `04_SYSTEM_DESIGN/*`
+   - `05_TASKS.md`（若存在）
+2. 建立“框架变更 → 业务文档节点”的映射
+3. 识别以下三类影响：
+   - **路径迁移**：如 `.agent/` → `.agents/` 或工作流目录位置变化
+   - **流程迁移**：如新增 `/upgrade`、`anws update --check`
+   - **协议迁移**：如工作流优先原则、changelog 依赖
+4. 对每个影响点标注：
+   - 受影响文件
+   - 受影响章节
+   - 修改原因
+   - 是否涉及 AI 推断填充
+5. 生成**推荐路由**：
+   - `Minor` → 推荐调用 `/change`
+   - `Major` → 推荐调用 `/genesis`
+
+> [!IMPORTANT]
+> 此处只产出“升级计划”和“路由建议”，**不执行实际文档写入**。
+
+---
+
+## Step 3: 人类检查点 ⚠️
+
+> [!IMPORTANT]
+> 未经用户明确批准，禁止写任何文件。
+
+必须向用户展示以下内容：
+
+```markdown
+⚠️ 人类检查点 — 升级计划确认
+
+**最新 changelog**: `.anws/changelog/vX.Y.Z.md`
+**当前架构版本**: `.anws/v{N}`
+**升级定级**: Minor / Major
+**推荐路由**: `/change` 或 `/genesis`
+
+## 受影响文件
+- `.anws/v{N}/01_PRD.md` — 原因: 路径约定变更
+- `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md` — 原因: 新增 update --check 流程
+
+## 执行策略
+- Minor: 进入 `/change`，按 `/change` 的权限边界和检查点修改
+- Major: 进入 `/genesis`，按 `/genesis` 的版本化规则创建/演进新版本
+
+## 风险提示
+- 哪些段落需要 AI 推断
+- 哪些业务常量将被保护不改
+
+请确认: ✅ 批准并路由 / ❌ 拒绝 / ✏️ 调整
+```
+
+---
+
+## Step 4: 路由到目标工作流
+
+### Case A: Minor → `/change`
+
+1. 接下来**必须读取**当前 target 对应的 `/change` 原生投影文件
+2. 将 Step 2 的影响分析结果带入 `/change`
+3. 后续所有修改动作必须遵守 `/change` 的权限边界、人类检查点和 CHANGELOG 记录规则
+4. 若在 `/change` 评估中发现超出其权限边界，立即终止并改走 `/genesis`
+
+### Case B: Major → `/genesis`
+
+1. 接下来**必须读取**当前 target 对应的 `/genesis` 原生投影文件
+2. 将 Step 2 的影响分析结果作为新版本演进输入带入 `/genesis`
+3. 后续版本复制、文档演进、Manifest/ADR 变更必须遵守 `/genesis` 的版本管理逻辑
+
+### AI 推断填充规则
+
+若某段内容需要 AI 基于上下文补全，必须在段前加入：
+
+```markdown
+> [!WARNING]
+> AI 推断填充，请人类复核。
+```
+
+### 业务常量保护规则
+
+以下内容禁止被框架升级覆盖：
+- 业务领域术语
+- 产品目标
+- 用户故事中的业务意图
+- 团队特定约束
+- 自定义系统边界
+
+---
+
+## 完成报告
+
+完成路由后，向用户输出：
+- 升级级别
+- 推荐路由 (`/change` 或 `/genesis`)
+- 计划影响的文件列表
+- 是否预计创建新版本
+- 是否存在 AI 推断填充风险
+- 下一步必须读取的工作流文件
+
+---
+
+<completion_criteria>
+- ✅ 已读取最新 `.anws/changelog/vX.Y.Z.md`
+- ✅ 已完成升级定级
+- ✅ 已输出推荐路由 (`/change` / `/genesis`)
+- ✅ 已展示升级计划并获得用户批准
+- ✅ 已在执行前切换去读取目标工作流
+- ✅ 后续写操作由目标工作流规范接管
+</completion_criteria>