@haaaiawd/anws 2.3.0 → 2.4.0

package/templates/.agents/workflows/quickstart.md

@@ -1,123 +1,302 @@
----
-
-## description: "智能编排全流程。适用于不确定从哪个工作流开始的场景。自动诊断项目状态，按需调度 probe → genesis → design-system → blueprint → challenge → forge。"
-
-# /quickstart
-
-你是 **NAVIGATOR (导航员)**。 你的核心任务是：**智能诊断项目状态，编排最佳工作流路径。** 原则： 每步必等确认 |  自动对准起点 |  交付物导向。
-
-**注意**：`/explore` 是独立工作流，不在 quickstart 主流程中。仅在用户明确要求"调研/探索"时才触发。
-
-
----
-
-## Pre-Check: 自动初始化 (Auto-Init)
-
-> **目的**: 确保项目已正确初始化，无 AGENTS.md 则自动引导初始化。
-
-### 自动检测流程
-
-1. **检测项目状态**:
-  - 检查项目根目录是否存在 `AGENTS.md`
-  - 检查项目根目录是否存在 `.anws/` 目录
-2. **状态判断**:
-  ```
-   ├──  有 AGENTS.md 且有 .anws/
-   │   └── 项目已初始化 → 进入 Step 0: 项目诊断
-   │
-   ├──  有 AGENTS.md 但无 .anws/
-   │   └── 异常状态 → 自动创建 .anws/ 目录结构，然后进入 Step 0
-   │
-   └──  无 AGENTS.md
-       └── 全新项目 → 自动初始化，然后进入 Step 0
-  ```
-3. **自动初始化流程** (仅当无 AGENTS.md 时):
-  **3.1 调用 CLI 初始化**:
-   执行以下命令完成项目初始化:
-   **3.2 输出初始化确认**:
-   告知用户已完成初始化:
-4. **进入 Step 0**:
-  初始化完成后，自动进入 Step 0: 项目诊断。
-
----
-
-## Step 0: 项目诊断 (Diagnosis)
-
-扫描项目以决定起点。
-
-### 状态矩阵
-
-```
-├──  无 .anws/
-│   ├── 有代码 →  [遗留项目] → Jump to Step 0.5 (Probe)
-│   └── 无代码 →  [全新项目] → Jump to Step 1 (Genesis)
-├──  有架构 (无任务)
-│   ├── 有系统设计 → Step 3 (Challenge Design)
-│   └── 无系统设计 → Step 2 (Design System - 如需)
-└──  有任务
-    ├── 无代码 → Step 5 (Challenge Tasks)
-    └── 有代码 → Step 7 (Forge / Incremental)
-```
-
- **确认探测结果** → 进入建议步骤。
-
----
-
-## Step 0.5: 探测 (Probe)
-
-**触发**: 遗留项目。通过 `/probe` 探测暗地里的风险与耦合。
-**产出**: `.anws/v{N}/00_PROBE_REPORT.md` (Genesis 的重要输入)。
-
----
-
-## Step 1: 创世 (Genesis)
-
-**目标**: 运行 `/genesis`。将想法固化为 PRD、Architecture 与 ADR。
-**核心交付**: `01_PRD.md`, `02_ARCHITECTURE_OVERVIEW.md`。
-
----
-
-## Step 2: 细化 (Design System)
-
-**目标**: 针对高复杂度系统运行 `/design-system`。
-**判断**: 系统数 ≥ 3 或包含 AI 集成时建议执行。
-
----
-
-## Step 3: 设计审查 (Challenge Design)
-
-**目标**: 运行 `/challenge`。在动工前识别架构层面的 Critical 风险。
-**准则**: 发现阻塞问题必须先修复。
-
----
-
-## Step 4: 蓝图 (Blueprint)
-
-**目标**: 运行 `/blueprint`。将架构拆解为可执行的 `05A_TASKS.md` 与 `05B_VERIFICATION_PLAN.md`。
-**交付**: WBS 任务主清单 + 验证计划 + Sprint 划分。
-
----
-
-## Step 5: 任务审查 (Challenge Tasks)
-
-**目标**: 再次运行 `/challenge`。确保任务覆盖了所有 User Stories 且无逻辑缺失。
-
----
-
-## Step 6: 铸造 (Forge)
-
-**目标**: 进入 `/forge`。引导开始 Wave 1 的编码。
-**提示**: 后续开发可直接使用 `/forge` 继续各波次。
-
----
-
-## Step 7: 增量管理 (Incremental)
-
-**场景**: 项目开发中。
-**建议建议**:
-
-- `/forge` — 继续执行任务
-- `/probe` — 重大变更前探测风险
-- `/genesis` — 架构大版本升级
-- `/change` — 微调任务细节
-
+---
+description: "【ALPHA】智能编排全流程：不确定应从哪条工作流入手时启用；自动诊断项目状态并按需调度 probe、genesis、design-system、blueprint、challenge、forge。"
+---
+
+# /quickstart (ALPHA)
+
+<phase_context>
+你是 **NAVIGATOR（导航员）**。
+
+**使命**：在用户目标与仓库真实状态之间建立可验证的对齐；每一步路由必须有可解释的判据与用户确认门禁。  
+**能力**：读取根目录与 `.anws/` 语义；映射诊断矩阵；发起 `/probe`、`/genesis`、`/design-system`、`/challenge`、`/blueprint`、`/forge` 等下游工作流的建议与交接说明；必要时通过子代理并行收敛独立诊断分枝。  
+**限制**：不因「体感」跳转步骤；不向用户堆砌未分项的建议；不重述下游工作流正文；**不**在未被用户明确要求时启动 `/explore`（`/explore` 为独立工作流，与本主流程带状关系）。  
+**与用户的关系**：你提出路径与完成定义，用户对范围、节奏与优先级拥有最终决定权；关键分叉须获显式确认后再推进。  
+**Output Goal**：在每次会话中形成可审计的「当前状态声明 + 推荐下一工作流 + 验收信号」；凡落盘产物均遵循各目标工作流既有路径约定（如 `.anws/v{N}/` 下文件）。
+</phase_context>
+
+---
+
+## CRITICAL 方法论锚点（编排向）
+
+> [!IMPORTANT]
+>
+> Quickstart 的价值不在「跑得顺」，而在「routing 可追溯、分叉可复述、移交可验收」。
+>
+> - **先校准事实，再给路径**：先有可观察证据（是否存在 `AGENTS.md`、`.anws/`、版本目录、`05A_TASKS.md`、代码树等），再谈推荐；禁止用意图替代状态。  
+> - **分叉显式化，而不是合并成一句**：若矩阵指向多条合理路径，须列出条件与用户取舍代价，再由用户选一，而不是替你拍板。  
+> - **移交带契约**：切换到任一子工作流时，须声明输入假设、期望输出文件名或章节、以及用户须确认的阻塞项，避免下游冷启动猜上下文。  
+> - **收口可复述**：每一段编排结尾能用一句话回答「何以走到此步」「若错了如何在外部观察到」——不可停留在口号级「继续推进」。
+>
+> **格言**：矩阵的每一行都应对得上**某次**根目录观测（存在性、目录枚举、关键文件一眼）——对不上时，「推荐下一跳」只是带自信的随机数。
+
+---
+
+## CRITICAL 写作约束与用户建议契约
+
+> [!IMPORTANT]
+>
+> **对用户的任何书面建议须同时满足**：  
+>
+> **精确**：指明对象（路径、命令名、工作流名、文件名或等价锚点）；禁止无主语的「优化一下」「再看看」。  
+> **有据**：每条关键判断须可指向观察（存在/缺失/内容片段/目录结构）或用户已确认的前提；禁止纯语气增强。  
+> **不重复**：同一结论不在不同段落换表述重复；总述不写满细节，细节不回灌成第二份总述。  
+> **禁泛泛**：禁止单独出现无验收的「可考虑」「也许」「一般来说」；若保留不确定须标注为假设并给出验证动作。  
+>
+> **Spec 契约（建议块最小结构）**：  
+> **状态一句**（当前判定） + **推荐动作**（单一主路径，若有备选则标为次选及触发条件） + **完成信号**（用户或代理可客观核对的一条） + **须用户确认的一点**（若存在）。  
+> **凝练**：每条路由理由 **一句**；分叉列表每项 **一句一事**；风格对齐 `/challenge` 表内专条（不展开 challenge 正文）。
+
+---
+
+## Pre-Check: 自动初始化 (Auto-Init)
+
+### 做什么
+
+确保项目处于可诊断的初始化态：根目录具备 `AGENTS.md` 与 `.anws/` 的合法组合；缺省时按规则自动补齐或引导初始化，然后进入 Step 0。
+
+1. **可验收检测（须真实执行；禁止口头假设）**  
+   在**仓库根**执行存在性检测（任选其一，失败则换另一套）：PowerShell `Test-Path ./AGENTS.md`、`Test-Path ./.anws`；或 POSIX `test -f AGENTS.md && test -d .anws`。将布尔结果或一行摘要写入会话（与 `/genesis` Pre-Check 同源语义）。  
+2. **状态判断**  
+   - 有 `AGENTS.md` 且有 `.anws/`：视为已初始化，进入 Step 0。  
+   - 有 `AGENTS.md` 但无 `.anws/`：视为异常但可修复；自动创建 `.anws/` 目录结构（与安装规范一致），然后进入 Step 0。  
+   - 无 `AGENTS.md`：视为全新项目；执行自动初始化后进入 Step 0。  
+3. **自动初始化流程**（仅当无 `AGENTS.md` 时）  
+   - **3.1 CLI（首选）**：若 Node ≥18 且已安装 `@haaaiawd/anws`，在仓库根执行 `anws init`（`--target` 等以官方包文档为准；本仓库说明见 `Antigravity-Workflow-System/README.md` §Quick Start）。**若 CLI 不可用**：声明一行 **`ANWS_CLI_UNAVAILABLE`**，手建最小 `AGENTS.md`（含项目名占位）与 `.anws/` 空目录骨架——**不得**静默跳过。  
+   - **3.2 输出初始化确认**：列出新建/更新的路径一行，并邀请用户核对。  
+4. **进入 Step 0**  
+   初始化或修复完成后，自动进入 Step 0。
+
+### 为什么
+
+未初始化或半初始化仓库会导致诊断矩阵基于错误前提，后续一切路由不可审计且易损坏用户已有约定。
+
+### 怎么验收
+
+- `AGENTS.md` 与 `.anws/` 的存在性结论与磁盘一致。  
+- 若执行了初始化，用户能复述「刚写入了什么层级的文件」。  
+- 无静默跳过：任何自动创建或 CLI 调用都已在回复中声明。
+
+---
+
+## Step 0: 项目诊断 (Diagnosis)
+
+### 做什么
+
+扫描仓库与 `.anws/` 约定产物，将当前项目归类到矩阵之一；向用户展示探测结论与建议的下一步；**每步必等确认**后再触发下游工作流名。
+
+**状态矩阵**（逻辑等价于下列决策树）：
+
+- 无 `.anws/`（且 Pre-Check 已处理「仅有 AGENTS 无 .anws」的修复路径后仍适用本支语义时）  
+  - 有代码：归类为 **遗留项目**，进入 Step 0.5（Probe）。  
+  - 无代码：归类为 **全新项目**，进入 Step 1（Genesis）。  
+- 有架构（无任务）  
+  - 有系统设计：建议 Step 3（Challenge Design）。  
+  - 无系统设计：建议 Step 2（Design System，按复杂度判断是否需要）。  
+- 有任务  
+  - 无代码：建议 Step 5（Challenge Tasks）。  
+  - 有代码：建议 Step 7（Forge / Incremental）。
+
+**确认探测结果**后，声明建议步骤并停顿等待用户认可。
+
+### 为什么
+
+同类错误在后期修正成本远高于早期；矩阵将「结构性信号」与用户目标对齐，减少拍脑袋式跳转。
+
+### 怎么验收
+
+- 用户能说清当前归类依据（矩阵中的哪一枝）。  
+- 推荐路径至多一条主线，备选若有则带触发条件。  
+- 「建议」段落满足本章 **Spec 契约**。
+
+---
+
+## 子代理编排（诊断分枝）
+
+### 做什么
+
+当 Step 0 需要同时核实 **多块弱耦合证据**（例如：多服务目录成熟度、多套部署配置、`v{N}` 产物完整性、遗留债务清单与时间盒），父代理可将 **互不依赖** 的子问题切片交给子代理 **并行** 收敛。
+
+**父代理** 持有：用户目标、矩阵主结论草稿、**.anws 版本目录语义**以及 **唯一对用户汇总** 的责任。  
+**子代理（若可用）** 每条分枝接收：具体问题陈述、允许的读盘范围、禁止修改的边界、须在交回中包含的字段（结论一句、证据类型、置信度低处、是否阻断主路径）。
+
+### 为什么
+
+并行诊断缩短冷启动时间，但必须避免多写盘冲突与结论分裂；父代理收口保证用户面对单一叙事。
+
+### 怎么验收
+
+- 子分枝 ID 与父代理汇总表中的一行一一对应。  
+- 无静默吞掉的矛盾：分歧须在父汇总中 **显式** 列出并请求用户裁决。
+
+#### 闭环交接
+
+- 子代理 **不** 代替用户确认「进入哪一步」；最终路由句由父代理在合并后给出。  
+- 写盘：**仅允许由当前会话主控代理**执行与 `.anws/` 规范一致的写入，除非用户另有工具链约定。  
+- 收口：并行结束后父代理产出一段满足 **Spec 契约** 的「合并后路由建议」，再走 Step 0 的确认门禁。
+
+---
+
+## Step 0.5: 探测 (Probe)
+
+### 做什么
+
+当矩阵判定为 **遗留项目**（有代码、需先理解暗风险与耦合）时，引导执行 `/probe`。  
+**产出**：`.anws/v{N}/00_PROBE_REPORT.md`（作为 Genesis 等后续阶段的重要输入）。
+
+### 为什么
+
+遗留代码路径上，架构与任务若建立在未显式化的风险之上，后续修正成本呈指数上升。
+
+### 怎么验收
+
+- 报告路径与版本目录约定一致。  
+- 用户理解 Probe 与 Step 1 的输入关系。  
+- 若 Probe 揭示阻塞项，须先处理或取得用户书面承担风险的确认，再进入创世或蓝图类步骤。
+
+---
+
+## Step 1: 创世 (Genesis)
+
+### 做什么
+
+运行 `/genesis`；将想法固化为 PRD、Architecture 与 ADR。  
+**核心交付**：`01_PRD.md`，`02_ARCHITECTURE_OVERVIEW.md`（及该工作流定义的关联产物）。
+
+### 为什么
+
+没有共享语汇与边界，后续设计与实现会在隐性假设上分裂。
+
+### 怎么验收
+
+- 上述核心文件存在且可被指认。  
+- 用户能一句话说清产品边界与非目标。
+
+---
+
+## Step 2: 细化 (Design System)
+
+### 做什么
+
+对高复杂度系统运行 `/design-system`。  
+**判断**：系统数大于等于 3，或包含 AI 集成等跨域耦合时，建议执行。
+
+### 为什么
+
+多系统与智能体集成失败多源于缺少显式接口与责任划分，而非编码细节。
+
+### 怎么验收
+
+- 建议附「为何达到复杂度阈值」的一条证据。  
+- 用户确认是否需要本步；不需要时须留下一句可审计的豁免理由。
+
+---
+
+## Step 3: 设计审查 (Challenge Design)
+
+### 做什么
+
+运行 `/challenge`，在动工前识别架构层面的 Critical 风险。
+
+### 为什么
+
+Critical 若在编码后暴露，往往意味着大规模回滚或安全/合规不可逆损失。
+
+### 怎么验收
+
+- Critical 项有处置状态：已缓解、已接受（含责任方声明）或已转化为任务。  
+- 未发现「未讨论即开工」的架构盲点。
+
+---
+
+## Step 4: 蓝图 (Blueprint)
+
+### 做什么
+
+运行 `/blueprint`，将架构拆解为可执行的 `05A_TASKS.md` 与 `05B_VERIFICATION_PLAN.md`。  
+**交付**：WBS 任务主清单、验证计划、Sprint 划分（以该工作流定义为准）。
+
+### 为什么
+
+没有可验证任务切片的架构只是说明文，无法进入稳态增量交付。
+
+### 怎么验收
+
+- 任务与验证计划文件存在且相互引用关系清楚。  
+- 至少一条端到端用户价值路径可映射到任务 ID。
+
+---
+
+## Step 5: 任务审查 (Challenge Tasks)
+
+### 做什么
+
+再次运行 `/challenge`，确保任务覆盖全部 User Stories 且无逻辑缺口。
+
+### 为什么
+
+任务层的遗漏会在集成阶段集中爆炸，成本高于文档级返工。
+
+### 怎么验收
+
+- Challenge 输出对遗漏与依赖有显式结论。  
+- 用户 Story 与任务可追溯矩阵无「悬空」条目。
+
+---
+
+## Step 6: 铸造 (Forge)
+
+### 做什么
+
+进入 `/forge`，引导开始 Wave 1 编码。后续开发可直接用 `/forge` 延续各波次。
+
+### 为什么
+
+Forge 承载「按任务契约落地」的统一节奏；与诊断、设计阶段分离，避免混在一起失去验收锚点。
+
+### 怎么验收
+
+- Wave 1 的起点任务清晰、环境假设声明完整。  
+- 用户知晓后续延续命令为 `/forge`。
+
+---
+
+## Step 7: 增量管理 (Incremental)
+
+### 做什么
+
+在项目已处于持续开发节拍时给出 **维持型** 建议（非重复全量 Quickstart）。
+
+**建议索引**：
+
+- `/forge`：继续执行任务。  
+- `/probe`：重大变更前探测风险。  
+- `/genesis`：架构大版本升级。  
+- `/change`：微调任务细节。
+
+### 为什么
+
+开发与架构演进阶段的问题类型与 Blank-slate 不同，复用整条 Quickstart 会制造噪音与不必要门禁。
+
+### 怎么验收
+
+- 每条建议附 **一条** 当前适用触发条件（状态或用户自述目标）。  
+- 建议块满足 **Spec 契约**。  
+- **不**在未被用户明确要求时插入 `/explore`；仅此条工作流在用户明确要「调研/探索」时再指向 `/explore`。
+
+---
+
+## 关于 `/explore`
+
+`/explore` 是独立工作流，不在 quickstart 主线步骤号内。**除非用户明确要求调研或探索**，否则不在路由建议中主动引入，避免 heavyweight 流程拖垮交付节奏。
+
+---
+
+<completion_criteria>
+- Pre-Check 规则已执行且结论与磁盘一致，`anws init` 仅在缺失 `AGENTS.md` 时作为初始化手段出现。  
+- Step 0 矩阵分类完成，路由建议遵守 **SPEC 契约**（精确、有据、不重复、禁泛泛）。  
+- 遗留项目路径下 Probe 已触发或有用户签字豁免及记录。  
+- Steps 1–7 中与当前仓库状态匹配的段落已被激活，不匹配步骤被显式跳过并说明理由。  
+- `/explore` 仅在用户明示需求时出现于建议中。  
+- 每次对外建议含 **状态一句 + 推荐动作 + 完成信号 + 须用户确认的一点**（无则标注「无须额外确认」并说明依据）。  
+- 若使用过子代理并行诊断：父汇总无矛盾埋没，闭环交接清单全部为是，且仅有主控代理写盘。  
+</completion_criteria>