@zeyue0329/xiaoma-cli 1.6.5 → 1.8.0

package/README.md

@@ -13,7 +13,7 @@
 
 Traditional AI tools do the thinking for you, producing average results. XiaoMa agents and facilitated workflows act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI.
 
-- **AI Intelligent Help** — Ask `/xiaoma-help` anytime for guidance on what's next
+- **AI Intelligent Help** — Invoke the `xiaoma-help` skill anytime for guidance on what's next
 - **Scale-Domain-Adaptive** — Automatically adjusts planning depth based on project complexity
 - **Structured Workflows** — Grounded in agile best practices across analysis, planning, architecture, and implementation
 - **Specialized Agents** — 12+ domain experts (PM, Architect, Developer, UX, Scrum Master, and more)
@@ -40,7 +40,7 @@ Traditional AI tools do the thinking for you, producing average results. XiaoMa
 npx xiaoma-cli install
 ```
 
-> If you are getting a stale beta version, use: `npx xiaoma-cli@6.0.1 install`
+> Want the newest prerelease build? Use `npx xiaoma-cli@next install`. Expect higher churn than the default install.
 
 Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, etc.) in your project folder.
 
@@ -52,7 +52,7 @@ npx xiaoma-cli install --directory /path/to/project --modules xmc --tools claude
 
 [See all installation options](https://docs.xiaoma-cli.org/how-to/non-interactive-installation/)
 
-> **Not sure what to do?** Run `/xiaoma-help` — it tells you exactly what's next and what's optional. You can also ask questions like `/xiaoma-help I just finished the architecture, what do I do next?`
+> **Not sure what to do?** Ask `xiaoma-help` — it tells you exactly what's next and what's optional. You can also ask questions like `xiaoma-help I just finished the architecture, what do I do next?`
 
 ## Modules
 
@@ -60,11 +60,11 @@ XiaoMa Method extends with official modules for specialized domains. Available d
 
 | Module                                                                                                            | Purpose                                           |
 | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| **[XiaoMa Method (BMM)](https://github.com/xiaoma-code-org/XiaoMa-Cli)**                                             | Core framework with 34+ workflows                 |
-| **[XiaoMa Builder (BMB)](https://github.com/xiaoma-code-org/xiaoma-builder)**                                           | Create custom XiaoMa agents and workflows           |
-| **[Test Architect (TEA)](https://github.com/xiaoma-code-org/xiaoma-cli-test-architecture-enterprise)**             | Risk-based test strategy and automation           |
-| **[Game Dev Studio (BMGD)](https://github.com/xiaoma-code-org/xiaoma-module-game-dev-studio)**                        | Game development workflows (Unity, Unreal, Godot) |
-| **[Creative Intelligence Suite (CIS)](https://github.com/xiaoma-code-org/xiaoma-module-creative-intelligence-suite)** | Innovation, brainstorming, design thinking        |
+| **[XiaoMa Method (BMM)](https://github.com/zqyl-xiaoma/XiaoMa-CLI)**                                             | Core framework with 34+ workflows                 |
+| **[XiaoMa Builder (BMB)](https://github.com/zqyl-xiaoma/xiaoma-builder)**                                           | Create custom XiaoMa agents and workflows           |
+| **[Test Architect (TEA)](https://github.com/zqyl-xiaoma/xiaoma-cli-test-architecture-enterprise)**             | Risk-based test strategy and automation           |
+| **[Game Dev Studio (BMGD)](https://github.com/zqyl-xiaoma/xiaoma-module-game-dev-studio)**                        | Game development workflows (Unity, Unreal, Godot) |
+| **[Creative Intelligence Suite (CIS)](https://github.com/zqyl-xiaoma/xiaoma-module-creative-intelligence-suite)** | Innovation, brainstorming, design thinking        |
 
 ## Documentation
 
@@ -73,15 +73,15 @@ XiaoMa Method extends with official modules for specialized domains. Available d
 **Quick links:**
 - [Getting Started Tutorial](https://docs.xiaoma-cli.org/tutorials/getting-started/)
 - [Upgrading from Previous Versions](https://docs.xiaoma-cli.org/how-to/upgrade-to-v6/)
-- [Test Architect Documentation](https://xiaoma-code-org.github.io/xiaoma-cli-test-architecture-enterprise/)
+- [Test Architect Documentation](https://zqyl-xiaoma.github.io/xiaoma-cli-test-architecture-enterprise/)
 
 
 ## Community
 
 - [Discord](https://discord.gg/gk8jAdXWmj) — Get help, share ideas, collaborate
 - [Subscribe on YouTube](https://www.youtube.com/@XiaoMaCode) — Tutorials, master class, and podcast (launching Feb 2025)
-- [GitHub Issues](https://github.com/xiaoma-code-org/XiaoMa-Cli/issues) — Bug reports and feature requests
-- [Discussions](https://github.com/xiaoma-code-org/XiaoMa-Cli/discussions) — Community conversations
+- [GitHub Issues](https://github.com/zqyl-xiaoma/XiaoMa-CLI/issues) — Bug reports and feature requests
+- [Discussions](https://github.com/zqyl-xiaoma/XiaoMa-CLI/discussions) — Community conversations
 
 ## Support XiaoMa
 
@@ -102,8 +102,8 @@ MIT License — see [LICENSE](LICENSE) for details.
 
 ---
 
-**XiaoMa** and **XiaoMa-Cli** are trademarks of XiaoMa Code, LLC. See [TRADEMARK.md](TRADEMARK.md) for details.
+**XiaoMa** and **XiaoMa-CLI** are trademarks of XiaoMa Code, LLC. See [TRADEMARK.md](TRADEMARK.md) for details.
 
-[![Contributors](https://contrib.rocks/image?repo=xiaoma-code-org/XiaoMa-Cli)](https://github.com/xiaoma-code-org/XiaoMa-Cli/graphs/contributors)
+[![Contributors](https://contrib.rocks/image?repo=zqyl-xiaoma/XiaoMa-CLI)](https://github.com/zqyl-xiaoma/XiaoMa-CLI/graphs/contributors)
 
 See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor information.

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@zeyue0329/xiaoma-cli",
-  "version": "1.6.5",
-  "description": "XiaoMa Cli: Universal AI Agent Framework",
+  "version": "1.8.0",
+  "description": "XiaoMa Universal AI Agent Framework",
   "keywords": [
     "agile",
     "ai",
@@ -17,18 +17,13 @@
     "url": "git+https://github.com/zqyl-xiaoma/xiaoma-cli-release.git"
   },
   "license": "MIT",
-  "author": "zeyue0329 <zeyue0329@gmail.com>",
+  "author": "Zeyue",
   "main": "tools/cli/xiaoma-cli.js",
   "bin": {
     "xiaoma": "tools/xiaoma-npx-wrapper.js",
     "xiaoma-cli": "tools/xiaoma-npx-wrapper.js"
   },
   "scripts": {
-    "docs:build": "node tools/build-docs.mjs",
-    "docs:dev": "astro dev --root website",
-    "docs:fix-links": "node tools/fix-doc-links.js",
-    "docs:preview": "astro preview --root website",
-    "docs:validate-links": "node tools/validate-doc-links.js",
     "flatten": "node tools/flattener/main.js",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
@@ -38,6 +33,7 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run validate:schemas && npm run test:schemas && npm run test:install && npm run validate:refs",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
     "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
@@ -81,13 +77,10 @@
     "semver": "^7.6.3",
     "xml2js": "^0.6.2",
     "yaml": "^2.7.0",
-    "zod": "^3.25.76"
+    "zod": "^3.23.0"
   },
   "devDependencies": {
-    "@astrojs/sitemap": "^3.6.0",
-    "@astrojs/starlight": "^0.37.5",
     "@eslint/js": "^9.33.0",
-    "astro": "^5.16.0",
     "c8": "^10.1.3",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
@@ -100,7 +93,6 @@
     "markdownlint-cli2": "^0.19.1",
     "prettier": "^3.7.4",
     "prettier-plugin-packagejson": "^2.5.19",
-    "sharp": "^0.33.5",
     "yaml-eslint-parser": "^1.2.3",
     "yaml-lint": "^1.7.0"
   },

package/pipeline-optimization-report.md

@@ -0,0 +1,455 @@
+# Pipeline Optimization Report
+
+**Generated:** 2026-03-18
+**Last Updated:** 2026-03-18 (Run #2 — Incremental Analysis)
+**Scope:** auto-requirements-pipeline · auto-story-pipeline
+**Run Type:** Incremental update (previous report found; all prior optimizations verified in-place)
+
+---
+
+## 1. 学习总结 — 项目整体架构
+
+### 1.1 Agent 体系
+
+| Agent | 名称 | 主要职责 | 触发 Pipeline |
+|-------|------|---------|--------------|
+| Analyst (Mary) | 业务分析师 | 需求分析、竞品研究、Requirements 挖掘 | auto-requirements-pipeline (AR) |
+| Architect (Winston) | 架构师 | 架构分析、技术设计、系统决策 | auto-requirements-pipeline |
+| PM (John) | 产品经理 | PRD创建/验证、Epic/Story拆解 | auto-requirements-pipeline |
+| SM (Bob) | Scrum Master | Story创建、Sprint规划、流程协调 | auto-story-pipeline (ASP) |
+| Dev (Amelia) | 开发者 | 代码实现、TDD、Bug修复 | auto-story-pipeline |
+| QA (Quinn) | 质量保障 | 功能测试、E2E测试、验收标准验证 | auto-story-pipeline |
+| UX Designer (Sally) | UX设计师 | 用户体验设计、界面规范 | — |
+| Tech Writer (Paige) | 技术文档 | 文档编写、图表生成 | — |
+| Quick Flow (Barry) | 快速开发 | 轻量级规格+实现一体化 | — |
+
+### 1.2 Core Skill 体系
+
+- **xiaoma-advanced-elicitation** — 高级需求挖掘技术
+- **xiaoma-brainstorming** — 结构化头脑风暴
+- **xiaoma-distillator** — 内容提炼与压缩
+- **xiaoma-editorial-review-prose/structure** — 编辑质量审查（文字风格/文档结构）
+- **xiaoma-review-adversarial-general / edge-case-hunter** — 对抗性代码审查与边界案例发现
+- **xiaoma-shard-doc / xiaoma-index-docs** — 文档分片与索引
+- **xiaoma-party-mode / xiaoma-help** — 协作模式和帮助系统
+
+### 1.3 Workflow 体系（4个阶段）
+
+| 阶段 | 核心工作流 |
+|------|-----------|
+| Phase 1 Analysis | auto-requirements-pipeline, xiaoma-create-product-brief, research |
+| Phase 2 Planning | create-prd, xiaoma-edit-prd, xiaoma-validate-prd, xiaoma-create-ux-design |
+| Phase 3 Solutioning | xiaoma-create-architecture, xiaoma-create-epics-and-stories, xiaoma-check-implementation-readiness |
+| Phase 4 Implementation | auto-story-pipeline, xiaoma-create-story, xiaoma-dev-story, xiaoma-code-review, xiaoma-sprint-planning, xiaoma-sprint-status, xiaoma-correct-course, xiaoma-retrospective |
+| 跨阶段 | xiaoma-document-project, xiaoma-generate-project-context, xiaoma-qa-generate-e2e-tests, xiaoma-quick-flow |
+
+### 1.4 Step-File 架构模式
+
+两个 pipeline 都采用相同的**step-file architecture**：每个步骤读取独立 `.md` 文件，防止长会话中的"上下文丢失"问题。状态通过变量（`{variable_name}`）在步骤间传递，文件 frontmatter 声明 `nextStepFile` 进行步骤链接。
+
+---
+
+## 2. Pipeline 分析
+
+### 2.1 auto-requirements-pipeline 分析
+
+**路径：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/`
+**步骤数：** 8步
+**Agent 角色链：** Mary → Winston → John → John → John → Winston → Orchestrator
+
+#### 步骤概览
+
+| 步骤 | 职责 | Agent | 输出产物 | 质量控制 |
+|------|------|-------|---------|---------|
+| Step 01 | 初始化与验证 | Orchestrator | 无 | 前置条件检查 |
+| Step 02 | 需求分析 | Analyst (Mary) | requirements-analysis.md | 8相分析 + 最多2次自检重试 |
+| Step 03 | 架构分析 | Architect (Winston) | current-architecture-analysis.md | 6项质量标准 + 最多2次重试 |
+| Step 04 | 创建PRD | PM (John) | prd.md | 委托 create-prd workflow (15步) |
+| Step 05 | 验证PRD | PM (John) | prd.md (updated) | 委托 validate-prd workflow，最多3次迭代 |
+| Step 06 | 创建 Epics/Stories | PM (John) | epics.md | 委托 create-epics-and-stories workflow |
+| Step 07 | 创建架构设计 | Architect (Winston) | architecture.md | 委托 create-architecture workflow |
+| Step 08 | 收尾 | Orchestrator | pipeline-status.json | Checklist 验证 |
+
+#### 亮点设计
+- **零跳过策略**：步骤间不允许跳过，通过"Automatically proceed"指令强制连续执行
+- **双架构文档区分**：`current-architecture-analysis.md`（现有系统分析）vs `architecture.md`（新功能设计），设计清晰
+- **Workflow 委托模式**：复杂步骤委托给已验证的子 workflow，保持 pipeline 轻量
+- **Machine-readable 状态**：`pipeline-status.json` 使下游 (auto-story-pipeline) 可以程序化检查完成状态
+
+#### 发现的问题（优化前）
+
+| 问题 ID | 严重性 | 描述 |
+|---------|--------|------|
+| REQ-01 | HIGH | step-06 缺少 PM 角色切换（Switch to PM Role）章节，与其他步骤不一致 |
+| REQ-02 | MEDIUM | workflow.md 状态变量缺少 `{max_validation_iterations}` 的说明（仅在 step-05 内定义） |
+| REQ-03 | MEDIUM | step-08 pipeline-status.json 中迭代次数字段被错误地用字符串引号包裹（应为数字类型） |
+
+---
+
+### 2.2 auto-story-pipeline 分析
+
+**路径：** `src/xmc/workflows/4-implementation/auto-story-pipeline/`
+**步骤数：** 9步
+**Agent 角色链：** Orchestrator → SM (Bob) → PM (John) → Dev (Amelia) → Adversarial Reviewer → QA (Quinn) → Orchestrator
+
+#### 步骤概览
+
+| 步骤 | 职责 | Agent | 主要操作 | 模式 |
+|------|------|-------|---------|------|
+| Step 01 | 初始化 | Orchestrator | 解析 sprint-status，确定 single/batch 模式 | 入口 |
+| Step 02 | 创建 Story | SM (Bob) | 委托 create-story workflow | 可跳过（已存在时） |
+| Step 03 | 验证 Story | PM (John) | 10步验证，最多3次自修复 | 质量门禁 |
+| Step 04 | 开发 Story | Dev (Amelia) | TDD (Red-Green-Refactor)，委托 dev-story | 核心实现 |
+| Step 05 | 代码审查 | Adversarial Reviewer | 委托 code-review，自动修复 HIGH/MEDIUM | 质量门禁 |
+| Step 06 | QA 测试 | QA (Quinn) | 真实数据测试，委托 qa-generate-e2e-tests | 验收测试 |
+| Step 07 | 修复与重测 | Dev (Amelia) | 根源修复 + 回归测试（最多 max_fix_iterations 次） | 修复循环 |
+| Step 08 | 完成 Story | Orchestrator | 更新状态、检查 Epic 完成度、生成摘要 | 收尾 |
+| Step 09 | 循环检查 | Orchestrator | Single模式结束 / Batch模式选下一个 Story | 循环控制 |
+
+#### 亮点设计
+- **状态机驱动**：`backlog → ready-for-dev → in-progress → review → done`，每个状态有明确转换规则
+- **Resume 能力**：step-01 支持 `ASP resume <story-key>` 恢复中断的故事
+- **In-Progress 检查**：针对异常 in-progress 状态（无已完成任务）给出警告而非阻塞
+- **Epic 完成度自动检查**：step-08 自动检测并更新 Epic 完成状态
+- **Batch Progress Checkpoint**：批量模式下每个故事间输出进度摘要
+
+#### 发现的问题（优化前）
+
+| 问题 ID | 严重性 | 描述 |
+|---------|--------|------|
+| STORY-01 | HIGH | step-09 批量进度检查点显示的状态计数是 step-01 初始化时的过期数据，批量处理多个 story 后信息失真 |
+| STORY-02 | HIGH | workflow.md 未文档化 `max_fix_iterations` 的可配置性（仅在 step-07 中提及可通过 config.yaml 配置） |
+| STORY-03 | MEDIUM | step-07 未区分故障来源（代码审查 vs QA 测试），修复后直接跳转 step-08，代码审查触发的修复不经过二次验证 |
+
+---
+
+## 3. 优化清单
+
+### 3.1 已识别的所有优化点
+
+| 优化 ID | 目标 Pipeline | 优先级 | 描述 | 受影响文件 |
+|---------|--------------|--------|------|-----------|
+| OPT-REQ-1 | auto-requirements | HIGH | step-06 缺少"Switch to PM Role"章节，一致性缺失 | step-06-create-epics.md |
+| OPT-REQ-2 | auto-requirements | MEDIUM | workflow.md 缺少 `{max_validation_iterations}` 状态变量文档 | workflow.md |
+| OPT-REQ-3 | auto-requirements | MEDIUM | step-08 JSON 迭代次数字段类型错误（字符串 vs 数字） | step-08-finalize.md |
+| OPT-STORY-1 | auto-story | HIGH | step-09 批量进度检查点使用过期状态计数 | step-09-cycle-check.md |
+| OPT-STORY-2 | auto-story | HIGH | workflow.md 缺少 `{max_fix_iterations}` 状态变量文档 | workflow.md |
+| OPT-STORY-3 | auto-story | MEDIUM | step-07 缺少故障来源区分和基于来源的差异化路由 | step-07-fix-and-retest.md |
+| OPT-REQ-4 | auto-requirements | LOW | step-05 Section 5 中 "Proceed to step 4" 措辞歧义，应为 "Proceed to section 6" | step-05-validate-prd.md |
+| OPT-STORY-4 | auto-story | MEDIUM | step-01 Section 5 将 ready-for-dev 直接路由到 step-04，与批量模式的 step-02→step-03 路径不一致，绕过了验证门禁 | step-01-init-and-validate.md |
+
+---
+
+## 4. 已实施优化
+
+### OPT-REQ-1 — step-06 新增 PM 角色切换章节
+
+**文件：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-06-create-epics.md`
+
+**问题：** step-04（Create PRD）和 step-05（Validate PRD）都有明确的"Switch to PM Role"章节，但 step-06（Create Epics）直接从"Load Required Context"开始，缺少角色切换，导致与同类步骤不一致。
+
+**修改：**
+- 在 `## EXECUTION SEQUENCE` 下新增 `### 1. Switch to PM Role` 章节，包含 John 的角色定义和职责说明
+- 原有章节编号向后推移（原 §1→§2, §2→§3, §3→§4, §4→§5, §5→§6）
+- 新章节明确指向 Epic/Story 拆解的目的："break down the validated PRD into well-structured epics and user stories"
+
+**兼容性：** 纯添加性修改，不影响委托逻辑和文件引用。
+
+---
+
+### OPT-REQ-2 — workflow.md 补充 `{max_validation_iterations}` 状态变量
+
+**文件：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/workflow.md`
+
+**问题：** `{max_validation_iterations}` 变量仅在 step-05 内部定义，其他开发者或 LLM 阅读 workflow.md 顶层时无法了解这个变量的存在和含义。
+
+**修改：**
+- 在 State Variables 章节，紧跟 `{validation_iteration}` 之后新增 `{max_validation_iterations}` 条目
+- 说明其默认值（3）以及为何比 analysis/architecture 的限制（2次）更高（因为委托了完整的 14步 validate-prd workflow）
+
+**兼容性：** 纯文档补充，不影响任何执行逻辑。
+
+---
+
+### OPT-REQ-3 — step-08 JSON 迭代计数字段改为数字类型
+
+**文件：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-08-finalize.md`
+
+**问题：** `pipeline-status.json` 模板中：
+```json
+"iterations": {
+  "analysis": "{analysis_iteration}",   // ❌ 字符串
+  "architecture": "{architecture_iteration}",  // ❌ 字符串
+  "validation": "{validation_iteration}"  // ❌ 字符串
+}
+```
+这些值在运行时会被替换为数字，但被字符串引号包裹，导致下游工具（如 auto-story-pipeline）解析时得到字符串 "1" 而非数字 1，不利于程序化比较。
+
+**修改：** 移除三个迭代次数字段的引号：
+```json
+"iterations": {
+  "analysis": {analysis_iteration},    // ✅ 数字
+  "architecture": {architecture_iteration},  // ✅ 数字
+  "validation": {validation_iteration}   // ✅ 数字
+}
+```
+
+**兼容性：** 修改 JSON 模板格式，运行时生成的 JSON 文件语义更正确。对已生成的历史文件无影响。
+
+---
+
+### OPT-STORY-1 — step-09 批量进度检查点刷新状态计数
+
+**文件：** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-09-cycle-check.md`
+
+**问题：** 在批量模式下处理第 N 个 story 时，section 3.5 的进度检查点输出的 `{backlog_count}`、`{ready_count}` 等计数仍是 step-01 初始化时的值，不反映处理过 N-1 个故事后的实际状态。
+
+例如，初始状态有 5 个 backlog story。处理完第 1 个后，`{backlog_count}` 还是 5，但实际应该是 4。这会使批量运行过程的进度摘要完全失真。
+
+**修改：** 在 section 3.5 "Batch Mode Progress Checkpoint" 的输出前，增加一个三步刷新序列：
+1. 重新加载完整 `{sprint_status}` 文件
+2. 重新计数所有状态类别，更新 5 个计数变量
+3. 输出带 "(refreshed)" 标记的进度摘要
+
+**兼容性：** 与现有批量逻辑完全兼容，仅增加了文件读取和计数步骤。不影响单故事模式。
+
+---
+
+### OPT-STORY-2 — workflow.md 补充 `{max_fix_iterations}` 状态变量
+
+**文件：** `src/xmc/workflows/4-implementation/auto-story-pipeline/workflow.md`
+
+**问题：** State Variables 章节只有 `{fix_iteration}`，但没有说明：
+1. 存在 `{max_fix_iterations}` 作为上限控制变量
+2. 该变量可通过 `config.yaml` 的 `max_fix_iterations` 字段自定义
+3. 各计数变量（`{backlog_count}` 等）何时被刷新
+
+**修改：**
+- 新增 `{max_fix_iterations}` 条目，说明默认值（5）和 config.yaml 配置方式
+- 更新 `{fix_iteration}` 说明，注明被 `{max_fix_iterations}` 控制、每个 story 重置
+- 更新 `{validation_attempt}` 说明，注明在 step-03 开始时重新初始化
+- 更新 5 个状态计数变量的说明，注明刷新时机（step-01 初始化，step-09 批量检查点和最终收尾时刷新）
+
+**兼容性：** 纯文档补充。
+
+---
+
+### OPT-STORY-3 — step-07 区分故障来源并差异化路由
+
+**文件：** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-07-fix-and-retest.md`
+
+**问题：** step-07 在修复后一律跳转 step-08（完成 story），无论问题是来自代码审查（step-05）还是 QA 测试（step-06）。对于代码审查触发的修复，修复后的代码没有经过任何验证即直接标记完成，存在质量风险。
+
+**修改：**
+
+**Section 2 新增故障来源分类：**
+```
+{fix_source} = "code-review" | "qa-testing" | "mixed"
+```
+
+**Section 6 差异化路由逻辑：**
+- `{fix_source}` == "qa-testing"：直接跳转 step-08（QA 已通过代码审查后的测试阶段）
+- `{fix_source}` == "code-review" 或 "mixed"：在跳转前执行**轻量级内联代码复查**（不需完整委托 code-review workflow，只需重新验证修复区域的 HIGH/MEDIUM 问题是否真正解决）。若复查发现新问题则循环回 step-07。
+
+**NEXT STEP 更新：** 新增三个条件化的跳转路径，覆盖所有路由场景。
+
+**兼容性：** 引入新变量 `{fix_source}`，修改了 section 6 逻辑和 NEXT STEP。不改变正常（无问题）执行路径。
+
+---
+
+### OPT-REQ-4 — step-05 Section 5 导航措辞修正
+
+**文件：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-05-validate-prd.md`
+
+**问题：** Section 5（Validation Loop）中，当所有验证检查通过时，文本写的是 "If ALL checks pass: Proceed to step 4"。`step 4` 是歧义引用——它可能被 LLM 误解为：(a) 循环列表中的第4项（不存在），(b) 文件的 Section 4（Execute PRD Validation，即重新触发整个委托流程），或 (c) 下一节（Section 6 Validation Passed，这才是正确意图）。误解为 (b) 会导致无限重委托循环。
+
+**修改：**
+- 将 "Proceed to step 4" 改为 "Proceed to section 6 (Validation Passed)"，明确指向正确的下一节，消除歧义。
+
+**兼容性：** 纯措辞修正，不影响任何执行逻辑结构。
+
+---
+
+### OPT-STORY-4 — step-01 ready-for-dev 路由与批量模式对齐
+
+**文件：** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-01-init-and-validate.md`
+
+**问题：** Section 5（Determine Starting Step）对 `ready-for-dev` 状态的注释是 "story already created and validated"，并将其直接路由到 step-04（develop story），**绕过了 step-03 的验证门禁**。
+
+但是，批量模式下（step-09 批量循环），`ready-for-dev` 的故事会经 step-02 路由到 step-03，再进入 step-04，这正是 step-09 注释明确说明的设计意图：
+> "step-02's section 1 skip logic will detect 'ready-for-dev' stories, skip creation, and route them to step-03 (validate) before development begins"
+
+两条路径不一致：
+- **初始/Resume 模式**（step-01）：ready-for-dev → step-04 ❌ 跳过验证
+- **批量循环**（step-09→step-02→step-03→step-04）：ready-for-dev → step-03 → step-04 ✅ 通过验证
+
+`ready-for-dev` 表示 create-story workflow 已生成故事文件，但**尚未经过 pipeline 的 step-03 质量验证**。跳过该门禁使初始模式与批量模式的质量保障不等同。
+
+**修改：**
+1. Section 5 中将 `ready-for-dev` 路由从 "Skip to step-04" 改为 "Start at step-03 (validate story)"，并更新注释说明原因
+2. NEXT STEP 章节中新增 `ready-for-dev → step-03` 的跳转条目，并将 `in-progress` 的跳转条目从 "step-04 (story status == 'ready-for-dev' or 'in-progress')" 拆分为独立的两个条目
+3. SUCCESS METRICS 更新路由映射说明（backlog→step-02, ready-for-dev→step-03, in-progress→step-04, review→step-05）
+
+**兼容性：** 此修改会让所有通过 resume 或初始 single 模式处理的 `ready-for-dev` 故事额外经过 step-03 验证。这是质量提升，不是破坏性变更。故事文件不受影响；sprint-status.yaml 状态转换顺序不变。
+
+---
+
+## 5. 测试结果
+
+### 5.1 结构完整性测试
+
+| 测试项 | 状态 | 备注 |
+|--------|------|------|
+| auto-requirements-pipeline 全部 8 个 step 文件存在 | ✅ PASS | step-01 至 step-08 全部验证 |
+| auto-story-pipeline 全部 9 个 step 文件存在 | ✅ PASS | step-01 至 step-09 全部验证 |
+| 所有 step 文件 frontmatter 含有 `name` 字段 | ✅ PASS | 两个 pipeline 全部 17 个文件通过 |
+| step-06 section 编号连续（1→2→3→4→5→6） | ✅ PASS | 重编号正确 |
+| workflow.md 新增状态变量拼写正确 | ✅ PASS | max_validation_iterations, max_fix_iterations |
+| step-08 JSON 整数字段无字符串引号 | ✅ PASS | analysis/architecture/validation 三个字段 |
+
+### 5.2 逻辑流程测试
+
+**auto-requirements-pipeline 8步走查：**
+
+| 步骤 | 前置条件 | 后置状态 | 跳转目标 | 状态 |
+|------|---------|---------|---------|------|
+| Step 01 | req.md + config.yaml 存在 | initialized | Step 02 | ✅ |
+| Step 02 | req.md 可读 | requirements-analyzed | Step 03 | ✅ |
+| Step 03 | src/ 目录（可选警告） | architecture-analyzed | Step 04 | ✅ |
+| Step 04 | create-prd workflow 存在 | prd-created | Step 05 | ✅ |
+| Step 05 | validate-prd workflow 存在；最多3次迭代 | prd-validated | Step 06 | ✅ |
+| Step 06 | create-epics workflow 存在；新增 PM 角色切换 | epics-created | Step 07 | ✅ |
+| Step 07 | create-architecture workflow 存在 | architecture-created | Step 08 | ✅ |
+| Step 08 | 5个产物均存在；Checklist 执行；JSON 整数类型 | complete | HALT | ✅ |
+
+**auto-story-pipeline 9步走查（batch 模式）：**
+
+| 步骤 | 前置条件 | 后置状态 | 跳转目标 | 状态 |
+|------|---------|---------|---------|------|
+| Step 01 | sprint-status.yaml + epics.md 存在 | initialized | Step 02/04/05（状态路由） | ✅ |
+| Step 02 | current_story_key 已设置 | story-created | Step 03 | ✅ |
+| Step 03 | story file 可读；validation_attempt 在步骤内重置为1 | story-validated | Step 04 | ✅ |
+| Step 04 | dev-story workflow；TDD 流程 | development-complete | Step 05 | ✅ |
+| Step 05 | code-review workflow；auto-fix HIGH/MEDIUM | code-review-complete | Step 06 或 Step 07 | ✅ |
+| Step 06 | 真实数据测试；no mock | qa-testing-complete/failed | Step 08 或 Step 07 | ✅ |
+| Step 07 | fix_source 已分类；max_fix_iterations 控制 | — | Step 08 或循环 Step 07 | ✅ |
+| Step 08 | 全门禁通过；epic 完成检查 | story-completed | Step 09 | ✅ |
+| Step 09 (batch) | sprint-status 刷新；找下一个 story | — | Step 02（循环）或 HALT | ✅ |
+
+### 5.3 兼容性测试
+
+| 测试项 | 状态 | 备注 |
+|--------|------|------|
+| Agent 菜单引用正确（analyst → AR, sm → ASP） | ✅ PASS | 触发器名称未被修改 |
+| SKILL.md 入口文件完好 | ✅ PASS | 两个 pipeline 均指向 workflow.md |
+| xiaoma-skill-manifest.yaml 未修改 | ✅ PASS | canonicalId 一致性保留 |
+| checklist.md 与实际步骤匹配 | ✅ PASS | 需求 pipeline 8步覆盖，Story pipeline 覆盖全部产物 |
+| 关联 workflow 路径引用未被破坏 | ✅ PASS | create-prd/validate-prd/create-epics/create-architecture 引用路径完整 |
+
+### 5.4 Run #2 增量测试结果（2026-03-18）
+
+**Run #1 优化验证（6项全部确认）：**
+
+| 优化 ID | 验证状态 | 验证方法 |
+|---------|---------|---------|
+| OPT-REQ-1 | ✅ 已实施 | 读取 step-06：Section 1 "Switch to PM Role" 确认存在 |
+| OPT-REQ-2 | ✅ 已实施 | 读取 workflow.md：`{max_validation_iterations}` 条目在 State Variables 第5行 |
+| OPT-REQ-3 | ✅ 已实施 | 读取 step-08：JSON 模板 `analysis/architecture/validation` 三字段无引号 |
+| OPT-STORY-1 | ✅ 已实施 | 读取 step-09：Section 3.5 刷新逻辑 + Section 4.1 Finalization 刷新 |
+| OPT-STORY-2 | ✅ 已实施 | 读取 workflow.md：`{max_fix_iterations}` 及所有状态计数变量的说明 |
+| OPT-STORY-3 | ✅ 已实施 | 读取 step-07：`{fix_source}` 分类 + Section 6 差异化路由 |
+
+**Run #2 新优化验证：**
+
+| 测试项 | 状态 | 备注 |
+|--------|------|------|
+| step-05 Section 5 措辞已改为 "section 6 (Validation Passed)" | ✅ PASS | 读取文件第62行确认 |
+| step-01 Section 5 ready-for-dev 路由已改为 "Start at step-03" | ✅ PASS | 读取文件第124行确认 |
+| step-01 NEXT STEP 已新增 "IF starting at step-03" 独立条目 | ✅ PASS | 读取文件第138-139行确认 |
+| step-01 "in-progress" 路由条目已从组合条目中拆分出来 | ✅ PASS | 读取文件第141-142行确认 |
+| step-01 SUCCESS METRICS 路由映射说明已更新 | ✅ PASS | 读取文件最终确认 |
+
+**全部 auto-requirements-pipeline 步骤完整性（增量确认）：**
+
+| 步骤 | frontmatter `name` | nextStepFile 指向正确 | 状态 |
+|------|--------------------|-----------------------|------|
+| step-01-init-and-validate | ✅ | step-02 | ✅ |
+| step-02-requirements-analysis | ✅ | step-03 | ✅ |
+| step-03-architecture-analysis | ✅ | step-04 | ✅ |
+| step-04-create-prd | ✅ | step-05 | ✅ |
+| step-05-validate-prd（已修正） | ✅ | step-06 | ✅ |
+| step-06-create-epics（已优化） | ✅ | step-07 | ✅ |
+| step-07-create-architecture | ✅ | step-08 | ✅ |
+| step-08-finalize | ✅ | null（终止）| ✅ |
+
+**全部 auto-story-pipeline 步骤路由一致性（增量确认）：**
+
+| 触发状态 | 初始/Resume 模式路由 | 批量循环模式路由 | 一致性 |
+|---------|--------------------|--------------------|--------|
+| backlog | step-02 | step-02（via step-09）| ✅ 一致 |
+| ready-for-dev | step-03（本次修正后）| step-03（via step-02 skip）| ✅ 一致（修正前不一致） |
+| in-progress | step-04 | step-04（via step-09 resume）| ✅ 一致 |
+| review | step-05 | step-05（via step-09 resume）| ✅ 一致 |
+
+---
+
+## 6. 风险评估
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|---------|
+| OPT-STORY-3 引入 `{fix_source}` 新变量，旧版 LLM 可能不识别 | 中 | 轻量级内联复查设计（非强制委托）；若 fix_source 无法确定，默认走最保守路径（code-review 路由） |
+| step-07 的轻量级复查可能被 LLM 简化处理为"一律通过" | 低-中 | 步骤文件明确说明"do a focused inline verification of the fixed areas"，要求针对具体问题复查，非全量审查 |
+| step-09 刷新计数增加一次文件读取开销 | 极低 | 纯文件读取，无网络或计算开销；提升信息准确性的收益远大于成本 |
+| OPT-REQ-3 JSON 类型修改在边缘情况下可能产生语法错误 | 低 | 若 iteration 变量未被正确替换（保持 `{analysis_iteration}` 字符串），JSON 会无效；但这与改变前相同，并非新引入的问题 |
+| OPT-STORY-4 ready-for-dev 故事将额外经过 step-03 验证（Run #2 新增）| 低-极低 | 对于通过标准 create-story workflow 创建的故事，step-03 验证通常会通过（create-story 已内置质量控制）。极端情况下若 step-03 发现严重问题（readiness < 7/10），会增加修复次数，但这正是质量门禁的作用。已有 max 3 次自修复保障不无限阻塞。 |
+
+---
+
+## 7. 后续建议
+
+### 7.1 短期（下一次分析周期）
+
+1. **为 auto-requirements-pipeline 增加可选的 UX 设计步骤**
+   目前 pipeline 在 PRD→Epics 之间没有 UX 设计步骤。对于前端密集型项目，可以在 step-06 之前添加 `step-05b-create-ux-design.md`，当且仅当项目类型为 UI/frontend 时触发，委托给 `xiaoma-create-ux-design` workflow。
+
+2. **为 auto-story-pipeline 增加 sprint-status 一致性验证**
+   batch 模式结束前，建议增加一个"Sprint Consistency Check"：验证 story file 中的状态字段与 sprint-status.yaml 中的状态完全一致，防止部分写入导致的状态漂移。
+
+3. **`pipeline-status.json` 被 auto-story-pipeline 读取的标准化**
+   step-01 in auto-story-pipeline 目前不读取 requirements pipeline 的 `pipeline-status.json`。建议在 step-01 的"Validate Prerequisites"中增加对 `pipeline-status.json` 的可选检查（如果存在，验证 requirements pipeline 已 complete），以防止在需求未完成时误启动 story pipeline。
+
+### 7.2 中期（架构级改进）
+
+4. **状态变量持久化**
+   当前所有状态变量（`{pipeline_status}`, `{steps_completed}` 等）仅存在于 LLM 上下文中，长会话中存在丢失风险。可以考虑将关键状态写入一个轻量的 `pipeline-run-state.json` 文件，支持从中断点恢复（类似 auto-requirements-pipeline 已有的 `pipeline-status.json`，但用于运行时状态而非完成状态）。
+
+5. **批量模式进度持久化**
+   auto-story-pipeline 批量模式处理多个 story 时，若会话意外中断，需要从头重新选择起点。可以在 step-09 循环时将 `{stories_completed}` 和已处理的 story keys 写入状态文件，支持断点续批。
+
+6. **Quality Gate 配置化**
+   目前多个质量门禁（validation score >= 7/10, max 3 validation attempts, max 5 fix iterations）是硬编码或半硬编码的。建议将这些阈值统一移至 `config.yaml`，允许项目级别的自定义。
+
+### 7.3 长期（生态级改进）
+
+7. **Pipeline 间的信号传递标准化**
+   当前两个 pipeline 的连接（requirements → story）是通过文档约定（用户手动运行 ASP）实现的。`pipeline-status.json` 为程序化连接奠定了基础，未来可以考虑一个"Master Pipeline Orchestrator"，自动在 requirements pipeline 完成后触发 sprint planning 和 story pipeline。
+
+8. **实现遥测与历史追踪**
+   目前每次运行都会覆盖输出产物。建议引入带时间戳的运行历史（如 `pipeline-runs/` 目录），记录每次运行的参数、迭代次数、成功/失败状态，支持跨版本的质量趋势分析。
+
+---
+
+---
+
+## 8. 运行历史
+
+| 运行次数 | 日期 | 类型 | 发现问题数 | 实施优化数 | 主要成果 |
+|---------|------|------|----------|----------|---------|
+| Run #1 | 2026-03-18 | 初始全量分析 | 6个 | 6个 | 建立基线：角色一致性、状态变量文档化、JSON类型修正、批量计数刷新、故障来源路由差异化 |
+| Run #2 | 2026-03-18 | 增量分析 | 2个 | 2个 | 导航歧义修正（step-05）、ready-for-dev 路由一致性修正（step-01） |
+
+**累计优化：8个 | 所有优化已验证在文件中实施 | 未发现破坏性变更**
+
+---
+
+*报告最后更新: 2026-03-18 (Run #2) | 下次分析建议: 实施后约2周进行增量分析*

package/src/core/module-help.csv

@@ -1,10 +1,11 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs
-core,anytime,Brainstorming,BSP,,_xiaoma/core/workflows/brainstorming/workflow.md,xiaoma-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,,
-core,anytime,Party Mode,PM,,_xiaoma/core/workflows/party-mode/workflow.md,xiaoma-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
+core,anytime,Brainstorming,BSP,,skill:xiaoma-brainstorming,xiaoma-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,,
+core,anytime,Party Mode,PM,,skill:xiaoma-party-mode,xiaoma-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
 core,anytime,xiaoma-help,BH,,skill:xiaoma-help,xiaoma-help,false,,,"Get unstuck by showing what workflow steps come next or answering XiaoMa Method questions.",,
-core,anytime,Index Docs,ID,,_xiaoma/core/tasks/index-docs.xml,xiaoma-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
-core,anytime,Shard Document,SD,,_xiaoma/core/tasks/shard-doc.xml,xiaoma-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
-core,anytime,Editorial Review - Prose,EP,,_xiaoma/core/tasks/editorial-review-prose.xml,xiaoma-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
-core,anytime,Editorial Review - Structure,ES,,_xiaoma/core/tasks/editorial-review-structure.xml,xiaoma-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
+core,anytime,Index Docs,ID,,skill:xiaoma-index-docs,xiaoma-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
+core,anytime,Shard Document,SD,,skill:xiaoma-shard-doc,xiaoma-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
+core,anytime,Editorial Review - Prose,EP,,skill:xiaoma-editorial-review-prose,xiaoma-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
+core,anytime,Editorial Review - Structure,ES,,skill:xiaoma-editorial-review-structure,xiaoma-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
 core,anytime,Adversarial Review (General),AR,,skill:xiaoma-review-adversarial-general,xiaoma-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
 core,anytime,Edge Case Hunter Review,ECH,,skill:xiaoma-review-edge-case-hunter,xiaoma-review-edge-case-hunter,false,,,"Walk every branching path and boundary condition in code, report only unhandled edge cases. Use alongside adversarial review for orthogonal coverage - method-driven not attitude-driven.",,
+core,anytime,Distillator,DG,,skill:xiaoma-distillator,xiaoma-distillator,false,,,"Lossless LLM-optimized compression of source documents. Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.",adjacent to source document or specified output_path,distillate markdown file(s)

package/src/core/skills/xiaoma-advanced-elicitation/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-advanced-elicitation
+description: 'Push the LLM to reconsider, refine, and improve its recent output.'
+---
+
+Follow the instructions in ./workflow.md.