@zeyue0329/xiaoma-cli 1.11.0 → 1.13.0

package/docs/roadshow/04-/345/267/245/344/275/234/346/265/201/346/211/247/350/241/214/350/257/246/350/247/243.md

@@ -0,0 +1,1038 @@
+# 工作流执行详解
+
+本文档深入解析 XiaoMa-CLI 的 26 个结构化工作流，涵盖从需求分析到交付的完整软件开发生命周期。每个工作流均采用 Step-File 微架构模式，确保 AI 在长会话中保持精确执行。
+
+---
+
+## 1. 工作流全景
+
+XiaoMa-CLI 的 26 个工作流分布在 5 个开发阶段中，形成完整的敏捷开发流水线：
+
+```mermaid
+graph LR
+    subgraph P1["阶段一：分析（5个）"]
+        W1[创建产品简报]
+        W2[市场研究]
+        W3[领域研究]
+        W4[技术研究]
+        W5[自动需求流水线]
+    end
+
+    subgraph P2["阶段二：规划（4个）"]
+        W6[创建PRD]
+        W7[验证PRD]
+        W8[编辑PRD]
+        W9[UX设计]
+    end
+
+    subgraph P3["阶段三：方案设计（3个）"]
+        W10[创建架构]
+        W11[创建史诗与故事]
+        W12[实施就绪检查]
+    end
+
+    subgraph P4["阶段四：实施（8个）"]
+        W13[Sprint规划]
+        W14[创建故事]
+        W15[开发故事]
+        W16[代码评审]
+        W17[Sprint状态]
+        W18[航向修正]
+        W19[史诗回顾]
+        W20[自动故事流水线]
+    end
+
+    subgraph P5["阶段五：全流程（1个）"]
+        W21[自动全流程流水线]
+    end
+
+    subgraph AUX["辅助工作流（5个）"]
+        W22[快速规格]
+        W23[快速开发]
+        W24[项目文档化]
+        W25[生成项目上下文]
+        W26[QA E2E测试]
+    end
+
+    P1 --> P2 --> P3 --> P4
+    W21 -.->|编排| P1
+    W21 -.->|编排| P4
+```
+
+**工作流分类统计：**
+
+| 阶段 | 工作流数量 | 核心职能 |
+|------|-----------|---------|
+| 阶段一：分析 | 5 | 需求发现、市场/领域/技术调研 |
+| 阶段二：规划 | 4 | PRD 创建/验证/编辑、UX 设计 |
+| 阶段三：方案设计 | 3 | 架构设计、史诗/故事分解、就绪检查 |
+| 阶段四：实施 | 8 | Sprint 管理、开发、评审、测试 |
+| 阶段五：全流程 | 1 | 端到端自动化编排 |
+| 辅助工作流 | 5 | 快速流、文档化、QA 测试 |
+| **总计** | **26** | |
+
+---
+
+## 2. 阶段一：分析（5 个工作流）
+
+分析阶段是一切的起点，负责将模糊的需求想法转化为结构化的产品简报和研究文档。
+
+### 2.1 创建产品简报 (xiaoma-create-product-brief)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 分析师 (xiaofen)，触发命令：`BP` 或 `CB` |
+| **目标** | 通过引导式协作发现，创建全面的产品简报文档 |
+| **输出产物** | `product-brief.md` |
+
+**执行步骤（6 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-init.md` | 初始化配置、检测是否继续已有简报 |
+| step-01b | `step-01b-continue.md` | 恢复中断的简报创建流程 |
+| step-02 | `step-02-vision.md` | 愿景和目标定义 |
+| step-03 | `step-03-users.md` | 用户画像和目标群体分析 |
+| step-04 | `step-04-metrics.md` | 成功指标定义 |
+| step-05 | `step-05-scope.md` | 范围界定 |
+| step-06 | `step-06-complete.md` | 完成并输出最终产品简报 |
+
+**核心特点：**
+- 追加式文档构建 -- 每步向输出文件追加内容，而非一次性生成
+- 前端元数据 `stepsCompleted` 跟踪进度，支持中断恢复
+- 菜单式交互，等待用户在每个关键节点做出选择
+
+---
+
+### 2.2 市场研究 (xiaoma-market-research)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 分析师 (xiaofen)，触发命令：`MR` |
+| **目标** | 使用网络搜索数据进行全面市场研究 |
+| **前置条件** | AI IDE 需支持网络搜索能力 |
+| **输出产物** | 带引用来源的市场研究文档 |
+
+**执行步骤（6 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-init.md` | 初始化研究范围和方向 |
+| step-02 | `step-02-customer-behavior.md` | 客户行为模式分析 |
+| step-03 | `step-03-customer-pain-points.md` | 客户痛点挖掘 |
+| step-04 | `step-04-customer-decisions.md` | 客户决策因素研究 |
+| step-05 | `step-05-competitive-analysis.md` | 竞品分析 |
+| step-06 | `step-06-research-completion.md` | 研究综合与结论输出 |
+
+**核心特点：**
+- 基于研究模板 (`research.template.md`) 结构化输出
+- 每个步骤聚焦市场研究的不同维度
+- 要求所有数据点附带引用来源
+
+---
+
+### 2.3 领域研究 (xiaoma-domain-research)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 分析师 (xiaofen)，触发命令：`DR` |
+| **目标** | 行业/领域深度调研，理解领域生态和趋势 |
+| **前置条件** | AI IDE 需支持网络搜索能力 |
+| **输出产物** | 领域研究文档 |
+
+**执行步骤（6 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-init.md` | 初始化领域研究方向 |
+| step-02 | `step-02-domain-analysis.md` | 领域现状与结构分析 |
+| step-03 | `step-03-competitive-landscape.md` | 竞争格局分析 |
+| step-04 | `step-04-regulatory-focus.md` | 法规与合规性聚焦 |
+| step-05 | `step-05-technical-trends.md` | 技术趋势分析 |
+| step-06 | `step-06-research-synthesis.md` | 研究综合与洞察输出 |
+
+**核心特点：**
+- 独立的领域专用步骤目录 (`domain-steps/`)
+- 覆盖法规、技术趋势等领域特有维度
+- 输出遵循统一的研究模板格式
+
+---
+
+### 2.4 技术研究 (xiaoma-technical-research)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 分析师 (xiaofen)，触发命令：`TR` |
+| **目标** | 技术可行性评估和实现方案研究 |
+| **前置条件** | AI IDE 需支持网络搜索能力 |
+| **输出产物** | 技术研究文档 |
+
+**核心特点：**
+- 聚焦技术栈选择、可行性分析、性能基准
+- 基于研究模板结构化输出
+- 可作为架构设计阶段的技术输入
+
+---
+
+### 2.5 自动需求流水线 (auto-requirements-pipeline)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 分析师 (xiaofen)，触发命令：`AR` |
+| **目标** | 全自动需求分析生命周期，从需求文档到架构设计一站式完成 |
+| **输入** | `req.md`（需求文档） |
+| **输出产物** | `requirements-analysis.md`、`current-architecture-analysis.md`、`prd.md`、`epics.md`、`architecture.md`、`pipeline-status.json` |
+
+**执行步骤（8 步）：**
+
+```mermaid
+flowchart TD
+    S1["step-01<br/>初始化与验证"] --> S2["step-02<br/>需求分析<br/>（分析师角色）"]
+    S2 --> S3["step-03<br/>架构分析<br/>（架构师角色）"]
+    S3 --> S4["step-04<br/>创建PRD<br/>（产品经理角色）"]
+    S4 --> S5["step-05<br/>验证PRD<br/>（产品经理角色）"]
+    S5 --> S6["step-06<br/>创建史诗与故事<br/>（产品经理角色）"]
+    S6 --> S7["step-07<br/>创建架构设计<br/>（架构师角色）"]
+    S7 --> S8["step-08<br/>最终交付"]
+
+    S2 -.->|质量不达标<br/>最多重试2次| S2
+    S3 -.->|质量不达标<br/>最多重试2次| S3
+    S5 -.->|验证失败<br/>最多重试3次| S5
+```
+
+**角色切换编排：**
+
+| 步骤 | 角色 | 智能体 |
+|------|------|--------|
+| step-01 | 流水线编排器 | -- |
+| step-02 | 分析师 | xiaofen |
+| step-03 | 架构师 | xiaojia |
+| step-04 | 产品经理 | xiaochan |
+| step-05 | 产品经理 | xiaochan |
+| step-06 | 产品经理 | xiaochan |
+| step-07 | 架构师 | xiaojia |
+| step-08 | 流水线编排器 | -- |
+
+**重试机制：**
+- 需求分析质量门控：最多 2 次重试
+- 架构分析质量门控：最多 2 次重试
+- PRD 验证质量门控：最多 3 次重试（因为 PRD 验证委托给完整的 14 步验证工作流，成本更高）
+
+**两种架构文档的区别：**
+- `current-architecture-analysis.md`（step-03 输出）：分析现有代码库的架构，描述"现状是什么"
+- `architecture.md`（step-07 输出）：为新需求设计的技术架构，描述"应该是什么"
+
+---
+
+## 3. 阶段二：规划（4 个工作流）
+
+规划阶段将分析成果转化为可执行的产品需求文档（PRD）和用户体验设计。
+
+### 3.1 创建 PRD (xiaoma-create-prd)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 产品经理 (xiaochan)，触发命令：`CP` |
+| **目标** | 通过引导式流程创建符合 XiaoMa 标准的 PRD |
+| **输入** | 产品简报、研究文档（可选） |
+| **输出产物** | `prd.md` |
+
+**核心特点：**
+- Step-File 架构执行
+- 前端元数据状态跟踪
+- 追加式文档构建
+- 符合 XiaoMa PRD 标准格式
+
+---
+
+### 3.2 验证 PRD (xiaoma-validate-prd)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 产品经理 (xiaochan)，触发命令：`VP` |
+| **目标** | 对标 XiaoMa 标准，对现有 PRD 进行全面质量验证 |
+| **角色** | 验证架构师 + QA 专家 |
+| **输出产物** | PRD 验证报告 |
+
+**执行步骤（14 步）：**
+
+| 步骤 | 文件 | 验证维度 |
+|------|------|---------|
+| step-v-01 | `step-v-01-discovery.md` | 发现并加载 PRD 文件 |
+| step-v-02 | `step-v-02-format-detection.md` | PRD 格式检测与识别 |
+| step-v-02b | `step-v-02b-parity-check.md` | 一致性与对等性检查 |
+| step-v-03 | `step-v-03-density-validation.md` | 内容密度验证 |
+| step-v-04 | `step-v-04-brief-coverage-validation.md` | 产品简报覆盖度验证 |
+| step-v-05 | `step-v-05-measurability-validation.md` | 可衡量性验证 |
+| step-v-06 | `step-v-06-traceability-validation.md` | 需求可追溯性验证 |
+| step-v-07 | `step-v-07-implementation-leakage-validation.md` | 实施泄漏检测 |
+| step-v-08 | `step-v-08-domain-compliance-validation.md` | 领域合规性验证 |
+| step-v-09 | `step-v-09-project-type-validation.md` | 项目类型适配验证 |
+| step-v-10 | `step-v-10-smart-validation.md` | SMART 原则智能验证 |
+| step-v-11 | `step-v-11-holistic-quality-validation.md` | 整体质量评估 |
+| step-v-12 | `step-v-12-completeness-validation.md` | 完整性验证 |
+| step-v-13 | `step-v-13-report-complete.md` | 汇总报告生成 |
+
+**验证流程图：**
+
+```mermaid
+flowchart TD
+    V01["发现PRD"] --> V02["格式检测"]
+    V02 --> V02b["一致性检查"]
+    V02b --> V03["密度验证"]
+    V03 --> V04["简报覆盖"]
+    V04 --> V05["可衡量性"]
+    V05 --> V06["可追溯性"]
+    V06 --> V07["实施泄漏"]
+    V07 --> V08["领域合规"]
+    V08 --> V09["项目类型"]
+    V09 --> V10["SMART验证"]
+    V10 --> V11["整体质量"]
+    V11 --> V12["完整性"]
+    V12 --> V13["汇总报告"]
+
+    style V01 fill:#e1f5fe
+    style V13 fill:#e8f5e9
+```
+
+**核心特点：**
+- 14 步渐进式深度验证，覆盖 PRD 质量的所有维度
+- 实施泄漏检测：确保 PRD 只描述"做什么"而不涉及"怎么做"
+- SMART 原则验证：确保每个需求都是具体的、可衡量的、可达成的、相关的、有时限的
+- 最终输出包含评分和改进建议
+
+---
+
+### 3.3 编辑 PRD (xiaoma-edit-prd)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 产品经理 (xiaochan)，触发命令：`EP` |
+| **目标** | 编辑改进现有 PRD，包括遗留格式转换 |
+| **输出产物** | 更新后的 `prd.md` |
+
+**执行步骤：**
+
+1. **发现** -- 查找并加载现有 PRD 文件
+2. **遗留转换** -- 如果 PRD 不符合 XiaoMa 格式，先进行格式转换
+3. **审核** -- 分析 PRD 当前状态和改进空间
+4. **编辑** -- 根据审核结果和用户指示进行编辑
+5. **完成** -- 输出最终编辑后的 PRD
+
+**核心特点：**
+- 支持将遗留格式的 PRD 转换为 XiaoMa 标准格式
+- 保留原有内容的同时优化结构和质量
+- 引导式编辑流程，确保改动有据可循
+
+---
+
+### 3.4 创建 UX 设计 (xiaoma-create-ux-design)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | UX 设计师 (xiaolei)，触发命令：`CU` |
+| **目标** | 创建全面的 UX 设计规范文档 |
+| **输出产物** | `ux-design-specification.md` |
+
+**执行步骤（14 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-init.md` | 初始化与配置加载 |
+| step-01b | `step-01b-continue.md` | 恢复中断的设计流程 |
+| step-02 | `step-02-discovery.md` | 设计发现与需求理解 |
+| step-03 | `step-03-core-experience.md` | 核心体验定义 |
+| step-04 | `step-04-emotional-response.md` | 情感化设计响应 |
+| step-05 | `step-05-inspiration.md` | 设计灵感收集 |
+| step-06 | `step-06-design-system.md` | 设计系统定义 |
+| step-07 | `step-07-defining-experience.md` | 体验定义与细化 |
+| step-08 | `step-08-visual-foundation.md` | 视觉基础设计 |
+| step-09 | `step-09-design-directions.md` | 设计方向确定 |
+| step-10 | `step-10-user-journeys.md` | 用户旅程映射 |
+| step-11 | `step-11-component-strategy.md` | 组件策略规划 |
+| step-12 | `step-12-ux-patterns.md` | UX 模式定义 |
+| step-13 | `step-13-responsive-accessibility.md` | 响应式与无障碍设计 |
+| step-14 | `step-14-complete.md` | 完成并输出最终 UX 规范 |
+
+**核心特点：**
+- 从情感化设计到组件策略的全面覆盖
+- 基于 UX 设计模板 (`ux-design-template.md`) 结构化输出
+- 包含响应式设计和无障碍访问设计
+- 14 步是所有工作流中步骤最多的单体工作流之一
+
+---
+
+## 4. 阶段三：方案设计（3 个工作流）
+
+方案设计阶段将 PRD 转化为技术架构和可开发的史诗/故事，为实施阶段做好准备。
+
+### 4.1 创建架构 (xiaoma-create-architecture)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 架构师 (xiaojia)，触发命令：`CA` |
+| **目标** | 创建全面的架构决策文档 |
+| **输出产物** | `architecture.md` |
+
+**执行步骤（8 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-init.md` | 初始化与配置加载 |
+| step-01b | `step-01b-continue.md` | 恢复中断的架构设计 |
+| step-02 | `step-02-context.md` | 上下文收集与分析 |
+| step-03 | `step-03-starter.md` | 架构起点与约束确定 |
+| step-04 | `step-04-decisions.md` | 架构决策记录 (ADR) |
+| step-05 | `step-05-patterns.md` | 设计模式选择 |
+| step-06 | `step-06-structure.md` | 系统结构设计 |
+| step-07 | `step-07-validation.md` | 架构验证与评审 |
+| step-08 | `step-08-complete.md` | 完成并输出架构文档 |
+
+**核心特点：**
+- 基于架构决策模板 (`architecture-decision-template.md`) 输出
+- 用户审批门控 -- 关键架构决策需要用户确认后才能继续
+- 涵盖从上下文分析到设计模式、系统结构的完整架构设计流程
+
+---
+
+### 4.2 创建史诗与故事 (xiaoma-create-epics-and-stories)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 产品经理 (xiaochan)，触发命令：`CE` |
+| **目标** | 将 PRD 和架构转化为结构化的史诗与用户故事 |
+| **输入** | `prd.md`、`architecture.md` |
+| **输出产物** | `epics.md`（BDD 格式验收标准） |
+
+**执行步骤（4 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-validate-prerequisites.md` | 验证前置产物是否就绪 |
+| step-02 | `step-02-design-epics.md` | 设计史诗结构 |
+| step-03 | `step-03-create-stories.md` | 创建用户故事（含BDD验收标准） |
+| step-04 | `step-04-final-validation.md` | 最终验证与输出 |
+
+**核心特点：**
+- 基于史诗模板 (`epics-template.md`) 结构化输出
+- 每个用户故事包含 BDD (行为驱动开发) 格式的验收标准
+- 故事按优先级和依赖关系排序
+- 确保 PRD 中的每个需求都可追溯到至少一个故事
+
+---
+
+### 4.3 实施就绪检查 (xiaoma-check-implementation-readiness)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 架构师/产品经理，触发命令：`IR` |
+| **目标** | 验证 PRD、架构、史诗/故事三者的对齐与完整性 |
+| **输出产物** | 实施就绪报告 |
+
+**执行步骤（6 步）：**
+
+| 步骤 | 文件 | 验证维度 |
+|------|------|---------|
+| step-01 | `step-01-document-discovery.md` | 发现并加载所有项目产物 |
+| step-02 | `step-02-prd-analysis.md` | PRD 质量与完整性分析 |
+| step-03 | `step-03-epic-coverage-validation.md` | 史诗覆盖度验证 |
+| step-04 | `step-04-ux-alignment.md` | UX 设计对齐验证 |
+| step-05 | `step-05-epic-quality-review.md` | 史诗/故事质量评审 |
+| step-06 | `step-06-final-assessment.md` | 最终就绪评估与报告 |
+
+**验证焦点：**
+- 需求可追溯性 -- 每个 PRD 需求是否都有对应的故事
+- 逻辑组织 -- 史诗和故事的分组是否合理
+- 缺口检测 -- 是否存在未覆盖的需求或孤立的故事
+- UX 对齐 -- 技术实现方案是否与 UX 设计一致
+- 基于就绪报告模板 (`readiness-report-template.md`) 输出
+
+---
+
+## 5. 阶段四：实施（8 个工作流）
+
+实施阶段是 XiaoMa-CLI 工作流最密集的阶段，涵盖从 Sprint 规划到代码交付的完整开发循环。
+
+### 5.1 Sprint 规划 (xiaoma-sprint-planning)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | Scrum Master (xiaomin)，触发命令：`SP` |
+| **目标** | 从史诗/故事中生成 Sprint 计划和跟踪文件 |
+| **输入** | `epics.md` |
+| **输出产物** | `sprint-status.yaml` |
+
+**核心特点：**
+- 智能检测逻辑：优先加载整体文档，分片版本作为回退
+- 生成机器可读的 `sprint-status.yaml`，用于后续工作流自动消费
+- 为每个故事分配初始状态 (`backlog`)
+
+**状态机模型：**
+
+```mermaid
+stateDiagram-v2
+    [*] --> backlog : Sprint规划
+    backlog --> ready_for_dev : 创建故事
+    ready_for_dev --> in_progress : 开发故事
+    in_progress --> review : 代码评审
+    review --> done : 评审通过
+    review --> in_progress : 评审不通过
+    done --> [*]
+```
+
+---
+
+### 5.2 创建故事 (xiaoma-create-story)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | Scrum Master (xiaomin)，触发命令：`CS` |
+| **目标** | 创建包含完整上下文的故事文件，让开发智能体拥有实现所需的全部信息 |
+| **输出产物** | `{story_key}.md` 故事文件 |
+
+**执行流程（内联 6 步）：**
+
+| 步骤 | 内容 |
+|------|------|
+| step-1 | 确定目标故事（从 sprint-status.yaml 选取或用户指定） |
+| step-2 | 加载核心产物（PRD、架构、史诗、UX 设计） |
+| step-3 | 架构与代码库分析 -- 穷尽式扫描相关代码和依赖 |
+| step-4 | Web 研究 -- 对不确定的技术方案进行在线调研 |
+| step-5 | 创建故事文件 -- 包含任务清单、验收标准、技术上下文 |
+| step-6 | 更新 sprint-status.yaml 状态为 `ready-for-dev` |
+
+**核心特点：**
+- **穷尽式产物分析** -- 不是简单从史诗复制，而是深度分析所有相关产物提取上下文
+- **前序故事智能** -- 分析已完成故事的实现方式，避免重复工作
+- **Git 智能** -- 感知当前代码库状态，识别可复用的组件
+- **Web 研究** -- 对技术方案不确定时主动进行在线调研
+- **零用户干预** -- 除初始选择外，全自动执行
+
+---
+
+### 5.3 开发故事 (xiaoma-dev-story)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 开发工程师 (xiaokai)，触发命令：`DS` |
+| **目标** | 按照故事文件规范完成完整的代码实现 |
+| **输入** | 故事文件 (`{story_key}.md`) |
+| **输出** | 实现代码 + 测试代码 + 更新后的故事文件 |
+
+**执行流程（内联 10 步）：**
+
+```mermaid
+flowchart TD
+    S1["step-1<br/>查找故事文件"] --> S2["step-2<br/>加载上下文"]
+    S2 --> S3["step-3<br/>检测评审续接"]
+    S3 --> S4["step-4<br/>标记进行中"]
+    S4 --> S5["step-5<br/>实现任务"]
+    S5 --> S6["step-6<br/>编写测试"]
+    S6 --> S7["step-7<br/>运行验证"]
+    S7 --> S8["step-8<br/>验证标记完成"]
+    S8 --> S9["step-9<br/>故事完成"]
+    S9 --> S10["step-10<br/>完成通知"]
+
+    S7 -.->|测试失败| S5
+    S3 -.->|评审返回<br/>有未解决问题| S5
+```
+
+| 步骤 | 内容 |
+|------|------|
+| step-1 | 查找下一个 `ready-for-dev` 状态的故事文件 |
+| step-2 | 加载故事文件和项目上下文 |
+| step-3 | 检测是否是评审返回（评审发现问题需要修复） |
+| step-4 | 将故事状态标记为 `in-progress` |
+| step-5 | 按任务清单逐项实现代码 |
+| step-6 | 编写测试代码 |
+| step-7 | 运行测试和 Lint 验证 |
+| step-8 | 勾选所有已完成的任务和验收标准 |
+| step-9 | 确认故事完成并更新状态 |
+| step-10 | 输出完成通知和摘要 |
+
+**Red-Green-Refactor 循环：**
+1. **Red** -- 先编写会失败的测试用例
+2. **Green** -- 编写最小代码让测试通过
+3. **Refactor** -- 在测试保护下重构代码
+
+**完成定义（Definition of Done）：**
+- 所有任务/子任务勾选完毕
+- 所有验收标准（AC）满足
+- 所有测试通过
+- Lint 检查零警告
+- 故事文件中的 Dev Agent Record 更新
+
+---
+
+### 5.4 代码评审 (xiaoma-code-review)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 开发工程师/快速流开发者，触发命令：`CR` |
+| **目标** | 通过并行对抗式评审层对代码进行全面审查 |
+| **输出产物** | 结构化评审报告 |
+
+**执行步骤（4 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-gather-context.md` | 收集代码变更上下文 |
+| step-02 | `step-02-review.md` | 执行并行对抗式代码评审 |
+| step-03 | `step-03-triage.md` | 对评审发现进行结构化分诊 |
+| step-04 | `step-04-present.md` | 呈现评审结果和改进建议 |
+
+**核心特点：**
+- **并行对抗式评审层** -- 多个评审视角同时检查代码，包括安全性、性能、可维护性等
+- **结构化分诊** -- 对每个发现按严重程度分类（阻塞/重要/建议）
+- **精准无噪音** -- 只报告真正的问题，不产生无意义的"风格建议"
+
+---
+
+### 5.5 Sprint 状态 (xiaoma-sprint-status)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | Scrum Master (xiaomin) |
+| **目标** | 查看和管理当前 Sprint 的状态 |
+
+**运行模式：**
+
+| 模式 | 说明 |
+|------|------|
+| 交互式 | 人机交互方式查看状态和进行操作 |
+| 数据 | 输出机器可读的状态数据 |
+| 验证 | 检查状态一致性和健康度 |
+
+**风险检测机制：**
+- 评审中故事过多 -- 可能存在瓶颈
+- 全部积压 -- Sprint 进度落后
+- 过期状态 -- 故事长时间未更新
+- 孤立故事 -- 不属于任何史诗的故事
+
+---
+
+### 5.6 航向修正 (xiaoma-correct-course)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 产品经理/Scrum Master，触发命令：`CC` |
+| **目标** | 管理 Sprint 执行期间的重大变更 |
+| **输出产物** | `sprint-change-proposal-{date}.md` |
+
+**执行步骤（5 步）：**
+
+| 步骤 | 内容 |
+|------|------|
+| step-1 | 初始化 -- 加载所有项目产物（PRD、史诗、架构、UX、技术规格） |
+| step-2 | 变更分析 -- 分析触发变更的问题及其影响范围 |
+| step-3 | 变更提案 -- 制定结构化的变更方案 |
+| step-4 | Sprint 变更方案 -- 评估对当前 Sprint 的具体影响 |
+| step-5 | 路由实施 -- 根据变更规模选择执行路径 |
+
+**变更规模路由：**
+
+```mermaid
+flowchart TD
+    CHANGE["变更触发"] --> ANALYZE["影响分析"]
+    ANALYZE --> SMALL["小型变更<br/>直接实施"]
+    ANALYZE --> MEDIUM["中型变更<br/>重新排列故事"]
+    ANALYZE --> LARGE["大型变更<br/>重新规划Sprint"]
+
+    SMALL --> IMPL["直接修改故事文件"]
+    MEDIUM --> REORDER["调整故事优先级和依赖"]
+    LARGE --> REPLAN["触发新的Sprint规划"]
+```
+
+---
+
+### 5.7 史诗回顾 (xiaoma-retrospective)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | Scrum Master (xiaomin)，触发命令：`ER` |
+| **目标** | 史诗完成后的团队回顾，提取经验教训 |
+| **输出产物** | 回顾报告 |
+
+**核心特点：**
+- **Party 模式** -- 多智能体 + 用户参与的圆桌对话
+  - 所有智能体对话使用格式：`Name (Role): dialogue`
+  - 展示不同观点、分歧和真实的团队动态
+  - 用户作为项目负责人参与讨论
+- **心理安全** -- 无指责文化，聚焦系统和流程改进
+- **两部分结构**：(1) 史诗回顾 + (2) 下一史诗准备
+- **可操作的行动项** -- 每个改进建议必须有明确的负责人
+
+---
+
+### 5.8 自动故事流水线 (auto-story-pipeline)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | Scrum Master (xiaomin)，触发命令：`ASP` |
+| **目标** | 全自动故事开发生命周期，从创建到交付一站式完成 |
+| **模式** | 单故事模式 / 批处理模式 |
+
+**执行步骤（9 步）：**
+
+```mermaid
+flowchart TD
+    S1["step-01<br/>初始化与验证"] --> S2["step-02<br/>创建故事<br/>（SM角色）"]
+    S2 --> S3["step-03<br/>验证故事<br/>（PM角色）"]
+    S3 --> S4["step-04<br/>开发故事<br/>（DEV角色）"]
+    S4 --> S5["step-05<br/>代码评审<br/>（评审者角色）"]
+    S5 --> S6["step-06<br/>QA测试<br/>（QA角色）"]
+    S6 --> S7["step-07<br/>Bug修复<br/>（DEV角色）"]
+    S7 --> S8["step-08<br/>最终验证"]
+    S8 --> S9["step-09<br/>循环检查"]
+
+    S3 -.->|验证失败<br/>最多3次| S3
+    S6 -.->|测试失败| S7
+    S7 -.->|修复后重测<br/>最多5次| S6
+    S9 -.->|批处理模式<br/>还有未完成故事| S2
+```
+
+**角色切换编排：**
+
+| 步骤 | 角色 | 智能体 |
+|------|------|--------|
+| step-01 | 编排器 | -- |
+| step-02 | Scrum Master | xiaomin |
+| step-03 | 产品经理 | xiaochan |
+| step-04 | 开发工程师 | xiaokai |
+| step-05 | 代码评审者 | -- |
+| step-06 | QA 工程师 | xiaoce |
+| step-07 | 开发工程师 | xiaokai |
+| step-08 | 编排器 | -- |
+| step-09 | 编排器 | -- |
+
+**故事状态机：**
+
+```
+backlog --> ready-for-dev --> in-progress --> review --> done
+```
+
+**关键机制：**
+- **批处理循环** -- step-09 检查是否还有未完成故事，如果有则循环回 step-02
+- **Bug 修复迭代** -- 最多 5 次修复-重测循环（可通过 `max_fix_iterations` 配置）
+- **故事验证** -- 最多 3 次验证尝试
+- **修复来源追踪** -- `fix_source` 变量区分修复来源（代码评审/QA测试/混合），决定后续路由
+
+---
+
+## 6. 阶段五：全流程（1 个工作流）
+
+### 6.1 自动全流程流水线 (auto-full-pipeline)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | Scrum Master (xiaomin)，触发命令：`AFP` |
+| **目标** | 从需求文档到代码交付的完全自动化端到端流水线 |
+| **输入** | `req.md`（需求文档） |
+| **输出** | 完整的项目代码、测试、文档 |
+
+**三大阶段架构：**
+
+```mermaid
+flowchart LR
+    subgraph Phase1["阶段一：需求分析（8步）"]
+        direction TB
+        P1S1["初始化"] --> P1S2["需求分析"]
+        P1S2 --> P1S3["架构分析"]
+        P1S3 --> P1S4["创建PRD"]
+        P1S4 --> P1S5["验证PRD"]
+        P1S5 --> P1S6["创建史诗"]
+        P1S6 --> P1S7["创建架构"]
+        P1S7 --> P1S8["交付"]
+    end
+
+    subgraph Phase2["阶段二：桥接"]
+        direction TB
+        P2S1["Sprint规划"]
+    end
+
+    subgraph Phase3["阶段三：故事开发（批处理循环）"]
+        direction TB
+        P3S1["创建故事"] --> P3S2["验证故事"]
+        P3S2 --> P3S3["开发故事"]
+        P3S3 --> P3S4["代码评审"]
+        P3S4 --> P3S5["QA测试"]
+        P3S5 --> P3S6["Bug修复"]
+        P3S6 --> P3S7["循环检查"]
+        P3S7 -.->|还有故事| P3S1
+    end
+
+    Phase1 --> Phase2 --> Phase3
+```
+
+**执行步骤（5 步主编排）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-init-and-validate.md` | 统一前置条件检查与初始化 |
+| step-02 | `step-02-run-requirements-pipeline.md` | 委托执行自动需求流水线（8步） |
+| step-03 | `step-03-bridge-sprint-planning.md` | 桥接步骤：自动执行 Sprint 规划 |
+| step-04 | `step-04-run-story-pipeline.md` | 委托执行自动故事流水线（批处理模式） |
+| step-05 | `step-05-finalize.md` | 统一完成报告 |
+
+**全角色编排：**
+
+分析师 (xiaofen) --> 架构师 (xiaojia) --> 产品经理 (xiaochan) --> Scrum Master (xiaomin) --> 开发工程师 (xiaokai) --> QA 工程师 (xiaoce)
+
+**步骤总数计算：**
+
+总步骤 = 8 (需求流水线) + 5 (Sprint 规划) + 9 x N (故事流水线，N 为故事数量)
+
+**上下文管理策略：**
+- **阶段边界摘要** -- 每个阶段结束时输出状态快照，确保关键状态在上下文压缩后存活
+- **故事批处理检查点** -- 每完成一个故事输出运行统计，提供恢复锚点
+- **磁盘优先于内存** -- 始终从磁盘重新读取 `sprint-status.yaml`，而非依赖内存中的缓存状态
+
+**主状态机：**
+
+```
+initializing --> requirements-phase --> bridge-phase --> development-phase --> complete
+```
+
+---
+
+## 7. 辅助工作流（5 个）
+
+辅助工作流不属于主开发流水线，但为特定场景提供专门能力。
+
+### 7.1 快速规格 (xiaoma-quick-spec)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 快速流开发者 (xiaokuai)，触发命令：`QS` |
+| **目标** | 快速生成技术规格文档，适用于小型任务 |
+| **输出产物** | 技术规格文档（基于 `tech-spec-template.md`） |
+
+**执行步骤（4 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-understand.md` | 理解需求和上下文 |
+| step-02 | `step-02-investigate.md` | 调研技术方案 |
+| step-03 | `step-03-generate.md` | 生成技术规格 |
+| step-04 | `step-04-review.md` | 审核与完善 |
+
+---
+
+### 7.2 快速开发 (xiaoma-quick-dev)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 快速流开发者 (xiaokuai)，触发命令：`QD` |
+| **目标** | 快速实现小型功能或修复，内置自检和对抗式评审 |
+
+**执行步骤（6 步）：**
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| step-01 | `step-01-mode-detection.md` | 模式检测（新功能/修复/重构） |
+| step-02 | `step-02-context-gathering.md` | 上下文收集 |
+| step-03 | `step-03-execute.md` | 执行实现 |
+| step-04 | `step-04-self-check.md` | 自我检查 |
+| step-05 | `step-05-adversarial-review.md` | 对抗式自评审 |
+| step-06 | `step-06-resolve-findings.md` | 解决评审发现 |
+
+**核心特点：**
+- 适用于不需要完整敏捷流程的小型任务
+- 内置对抗式自评审机制，在快速模式下也保证代码质量
+
+---
+
+### 7.3 项目文档化 (xiaoma-document-project)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | 分析师/技术写作，触发命令：`DP` |
+| **目标** | 对现有项目进行全面文档化 |
+
+**两种工作模式：**
+- **全扫描模式** (`full-scan-workflow.md`) -- 扫描整个项目并生成文档索引
+- **深度探究模式** (`deep-dive-workflow.md`) -- 对特定模块进行深入文档化
+
+**核心特点：**
+- 基于检查清单 (`checklist.md`) 确保文档覆盖度
+- 深度探究模式使用专用模板 (`deep-dive-template.md`)
+- 适用于棕地项目（已有代码库）的知识提取
+
+---
+
+### 7.4 生成项目上下文 (xiaoma-generate-project-context)
+
+| 属性 | 描述 |
+|------|------|
+| **目标** | 生成 `project-context.md` 文件，为所有工作流提供项目背景信息 |
+| **输出产物** | `project-context.md` |
+
+**核心特点：**
+- 扫描项目代码库提取关键信息
+- 生成的上下文文件被多个工作流引用（创建故事、开发故事、代码评审等）
+- 是其他工作流的通用依赖
+
+---
+
+### 7.5 QA E2E 测试生成 (xiaoma-qa-generate-e2e-tests)
+
+| 属性 | 描述 |
+|------|------|
+| **触发者** | QA 工程师 (xiaoce)，触发命令：`QA` |
+| **目标** | 生成端到端测试用例和测试代码 |
+
+**核心特点：**
+- 基于 SKILL.md 定义的技能规范执行
+- 包含测试检查清单 (`checklist.md`)
+- 生成可执行的 E2E 测试代码
+
+---
+
+## 8. Step-File 微架构模式
+
+所有 XiaoMa 工作流均采用 Step-File 微架构模式。这是整个系统的核心执行引擎。
+
+### 8.1 架构图
+
+```mermaid
+flowchart LR
+    WF["workflow.md<br/>入口点"] --> S1["step-01.md"]
+    S1 --> S2["step-02.md"]
+    S2 --> S3["step-03.md"]
+    S3 --> SN["step-N.md"]
+
+    WF -.-> CFG["config.yaml<br/>配置"]
+    WF -.-> TPL["templates/<br/>模板"]
+    WF -.-> DATA["data/<br/>数据"]
+    WF -.-> SKILL["SKILL.md<br/>技能定义"]
+```
+
+### 8.2 核心设计原则
+
+| 原则 | 说明 |
+|------|------|
+| **微文件设计** | 每个步骤是独立的、自包含的指令文件 |
+| **即时加载** | 每次仅加载当前步骤文件，绝不提前加载未来步骤 |
+| **顺序执行** | 严格按编号顺序执行，不跳跃、不优化顺序 |
+| **状态跟踪** | 通过前端元数据 `stepsCompleted` 数组记录已完成步骤 |
+| **追加式构建** | 输出文档通过逐步追加内容构建，而非一次性生成 |
+
+### 8.3 步骤处理规则
+
+1. **完整阅读** -- 在采取任何行动之前，必须完整读取整个步骤文件
+2. **按序执行** -- 步骤文件内的编号章节必须按顺序执行
+3. **等待输入** -- 遇到菜单时必须暂停，等待用户选择
+4. **检查续接** -- 如果步骤有"Continue"菜单选项，只有用户选择 `C` 才能继续
+5. **保存状态** -- 加载下一步之前，更新输出文件的 `stepsCompleted` 前端元数据
+6. **加载下一步** -- 指示加载下一步时，完整读取并执行
+
+### 8.4 不可违反的规则
+
+- 永远不要同时加载多个步骤文件
+- 永远不要在执行前跳过对步骤文件的完整阅读
+- 永远不要跳过步骤或"优化"执行顺序
+- 永远不要从未来的步骤中提前创建待办事项
+- 始终在写入最终输出后更新前端元数据
+- 始终在菜单处暂停并等待用户输入
+
+### 8.5 为什么采用这种设计
+
+**问题：** 大型语言模型在长上下文中会出现"中间丢失"（Lost in the Middle）现象 -- 对话越长，中间部分的信息越容易被遗忘或混淆。
+
+**解决方案：** Step-File 架构通过每次只加载一个步骤文件，确保 AI 的注意力始终聚焦在当前任务上。状态通过文件系统持久化，而非依赖内存。
+
+---
+
+## 9. 工作流数据依赖图
+
+以下图表展示了各工作流之间的数据依赖关系，箭头表示产物的流动方向：
+
+```mermaid
+flowchart TD
+    REQ["req.md<br/>需求文档"] --> RA["需求分析<br/>auto-requirements-pipeline"]
+    RA --> RANALYSIS["requirements-analysis.md"]
+    RA --> CAA["current-architecture-analysis.md"]
+    RA --> PRD["prd.md"]
+    RA --> EPIC["epics.md"]
+    RA --> ARCH["architecture.md"]
+
+    BRIEF["product-brief.md<br/>产品简报"] --> CPRD["创建PRD<br/>xiaoma-create-prd"]
+    CPRD --> PRD2["prd.md"]
+
+    PRD2 --> VP["验证PRD<br/>xiaoma-validate-prd"]
+    VP --> REPORT["验证报告"]
+    REPORT --> EP["编辑PRD<br/>xiaoma-edit-prd"]
+    EP --> PRD3["prd.md（改进版）"]
+
+    PRD --> CE["创建史诗与故事<br/>xiaoma-create-epics-and-stories"]
+    ARCH --> CE
+    CE --> EPIC2["epics.md"]
+
+    PRD --> CA["创建架构<br/>xiaoma-create-architecture"]
+    CA --> ARCH2["architecture.md"]
+
+    PRD --> IR["实施就绪检查<br/>xiaoma-check-implementation-readiness"]
+    EPIC2 --> IR
+    ARCH2 --> IR
+    IR --> READY["就绪报告"]
+
+    EPIC2 --> SP["Sprint规划<br/>xiaoma-sprint-planning"]
+    SP --> SS["sprint-status.yaml"]
+
+    SS --> CST["创建故事<br/>xiaoma-create-story"]
+    PRD --> CST
+    ARCH2 --> CST
+    EPIC2 --> CST
+    CST --> STORY["story-file.md"]
+
+    STORY --> DS["开发故事<br/>xiaoma-dev-story"]
+    DS --> CODE["实现代码"]
+    CODE --> CR2["代码评审<br/>xiaoma-code-review"]
+    CR2 --> QAT["QA测试"]
+    QAT --> DONE["故事完成"]
+
+    DONE --> RETRO["史诗回顾<br/>xiaoma-retrospective"]
+```
+
+### 关键数据流说明
+
+| 产物 | 生产者 | 消费者 |
+|------|--------|--------|
+| `product-brief.md` | 创建产品简报 | 创建 PRD |
+| `prd.md` | 创建 PRD / 自动需求流水线 | 验证 PRD、编辑 PRD、创建史诗、创建架构、创建故事、实施就绪检查 |
+| `architecture.md` | 创建架构 / 自动需求流水线 | 创建史诗、创建故事、实施就绪检查 |
+| `epics.md` | 创建史诗与故事 / 自动需求流水线 | Sprint 规划、创建故事、实施就绪检查 |
+| `sprint-status.yaml` | Sprint 规划 | 创建故事、开发故事、Sprint 状态、自动故事流水线 |
+| `{story_key}.md` | 创建故事 | 开发故事 |
+| `project-context.md` | 生成项目上下文 | 创建故事、开发故事、代码评审 |
+
+---
+
+## 10. 工作流触发命令速查表
+
+| 命令 | 工作流 | 触发智能体 |
+|------|--------|-----------|
+| `BP` / `CB` | 创建产品简报 | 分析师 (xiaofen) |
+| `MR` | 市场研究 | 分析师 (xiaofen) |
+| `DR` | 领域研究 | 分析师 (xiaofen) |
+| `TR` | 技术研究 | 分析师 (xiaofen) |
+| `AR` | 自动需求流水线 | 分析师 (xiaofen) |
+| `CP` | 创建 PRD | 产品经理 (xiaochan) |
+| `VP` | 验证 PRD | 产品经理 (xiaochan) |
+| `EP` | 编辑 PRD | 产品经理 (xiaochan) |
+| `CU` | UX 设计 | UX 设计师 (xiaolei) |
+| `CA` | 创建架构 | 架构师 (xiaojia) |
+| `CE` | 创建史诗与故事 | 产品经理 (xiaochan) |
+| `IR` | 实施就绪检查 | 架构师/产品经理 |
+| `SP` | Sprint 规划 | Scrum Master (xiaomin) |
+| `CS` | 创建故事 | Scrum Master (xiaomin) |
+| `DS` | 开发故事 | 开发工程师 (xiaokai) |
+| `CR` | 代码评审 | 开发工程师/快速流开发者 |
+| `CC` | 航向修正 | 产品经理/Scrum Master |
+| `ER` | 史诗回顾 | Scrum Master (xiaomin) |
+| `ASP` | 自动故事流水线 | Scrum Master (xiaomin) |
+| `AFP` | 自动全流程流水线 | Scrum Master (xiaomin) |
+| `QS` | 快速规格 | 快速流开发者 (xiaokuai) |
+| `QD` | 快速开发 | 快速流开发者 (xiaokuai) |
+| `DP` | 项目文档化 | 分析师/技术写作 |
+| `QA` | QA E2E 测试 | QA 工程师 (xiaoce) |