Merge e893f75b34 into 90d9d880b6

* docs(zh-cn-how-to): refine stories 2.5 and 2.6 docs

我澄清中文自定义与文档分片指南，保留命令、路径和配置键名的技术准确性，降低高级操作误解。
我同步修正 v4 到 v6 升级步骤中的旧新路径与工作流命名，帮助迁移时按当前约定执行。

feishu: https://feishu.cn/wiki/TODO
Made-with: Cursor

* docs(zh-cn-how-to): clarify shard output precedence

我在“你将获得”中补充完整文档与分片文档并存时的读取优先级说明。
此前“可保留”表述容易让用户误以为分片会自动生效；现在明确并存不建议且默认优先读取完整文档。

Feishu: <https://www.feishu.cn/>
Made-with: Cursor

---------

Co-authored-by: leon <leon.liang@hairobotics.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>

docs/zh-cn/_STYLE_GUIDE.md

@@ -1,25 +1,25 @@
 ---
 title: "Documentation Style Guide"
-description: Project-specific documentation conventions based on Google style and Diataxis structure
+description: 基于 Google 文档风格与 Diataxis 的项目文档规范
 ---
 
-This project adheres to the [Google Developer Documentation Style Guide](https://developers.google.com/style) and uses [Diataxis](https://diataxis.fr/) to structure content. Only project-specific conventions follow.
+本项目遵循 [Google Developer Documentation Style Guide](https://developers.google.com/style)，并使用 [Diataxis](https://diataxis.fr/) 组织文档。以下仅补充项目级约束。
 
-## Project-Specific Rules
+## 项目特定规则
 
-| Rule                             | Specification                            |
+| 规则 | 规范 |
-| -------------------------------- | ---------------------------------------- |
+| --- | --- |
-| No horizontal rules (`---`)      | Fragments reading flow                   |
+| 禁用水平分割线（`---`） | 会打断阅读流 |
-| No `####` headers                | Use bold text or admonitions instead     |
+| 禁用 `####` 标题 | 用加粗短句或 admonition 替代 |
-| No "Related" or "Next:" sections | Sidebar handles navigation               |
+| 避免 “Related/Next” 章节 | 交给侧边栏导航 |
-| No deeply nested lists           | Break into sections instead              |
+| 避免深层嵌套列表 | 拆成新段落或新小节 |
-| No code blocks for non-code      | Use admonitions for dialogue examples    |
+| 非代码内容不要放代码块 | 对话/提示用 admonition |
-| No bold paragraphs for callouts  | Use admonitions instead                  |
+| 不用整段粗体做提醒 | 统一用 admonition |
-| 1-2 admonitions per section max  | Tutorials allow 3-4 per major section    |
+| 每节 1-2 个 admonition | 教程大节可放宽到 3-4 个 |
-| Table cells / list items         | 1-2 sentences max                        |
+| 表格单元格/列表项 | 控制在 1-2 句 |
-| Header budget                    | 8-12 `##` per doc; 2-3 `###` per section |
+| 标题预算 | 每篇约 8-12 个 `##`，每节 2-3 个 `###` |
 
-## Admonitions (Starlight Syntax)
+## 提示块（Starlight 语法）
 
 ```md
 :::tip[Title]
@@ -39,18 +39,18 @@ Critical warnings only — data loss, security issues
 :::
 ```
 
-### Standard Uses
+### 标准用途
 
-| Admonition               | Use For                       |
+| 提示块 | 适用场景 |
-| ------------------------ | ----------------------------- |
+| --- | --- |
-| `:::note[Prerequisites]` | Dependencies before starting  |
+| `:::note[Prerequisites]` | 开始前依赖与前置条件 |
-| `:::tip[Quick Path]`     | TL;DR summary at document top |
+| `:::tip[Quick Path]` | 文档顶部 TL;DR |
-| `:::caution[Important]`  | Critical caveats              |
+| `:::caution[Important]` | 关键风险提醒 |
-| `:::note[Example]`       | Command/response examples     |
+| `:::note[Example]` | 命令/响应示例说明 |
 
-## Standard Table Formats
+## 标准表格模板
 
-**Phases:**
+**阶段（Phases）：**
 
 ```md
 | Phase | Name     | What Happens                                 |
@@ -59,18 +59,18 @@ Critical warnings only — data loss, security issues
 | 2     | Planning | Requirements — PRD or spec *(required)* |
 ```
 
-**Commands:**
+**技能（Skills）：**
 
 ```md
-| Command      | Agent   | Purpose                              |
+| Skill                | Agent   | Purpose                              |
-| ------------ | ------- | ------------------------------------ |
+| -------------------- | ------- | ------------------------------------ |
-| `brainstorm` | Analyst | Brainstorm a new project             |
+| `bmad-brainstorming` | Analyst | Brainstorm a new project             |
-| `prd`        | PM      | Create Product Requirements Document |
+| `bmad-create-prd`    | PM      | Create Product Requirements Document |
 ```
 
-## Folder Structure Blocks
+## 文件结构块（Folder Structure）
 
-Show in "What You've Accomplished" sections:
+用于 “What You've Accomplished” 类章节：
 
 ````md
 ```
@@ -85,143 +85,143 @@ your-project/
 ```
 ````
 
-## Tutorial Structure
+## 教程（Tutorial）结构
 
 ```text
-1. Title + Hook (1-2 sentences describing outcome)
+1. Title + Hook（1-2 句结果导向开场）
-2. Version/Module Notice (info or warning admonition) (optional)
+2. Version/Module Notice（可选，信息或警告提示块）
-3. What You'll Learn (bullet list of outcomes)
+3. What You'll Learn（结果清单）
-4. Prerequisites (info admonition)
+4. Prerequisites（前置条件提示块）
-5. Quick Path (tip admonition - TL;DR summary)
+5. Quick Path（TL;DR 提示块）
-6. Understanding [Topic] (context before steps - tables for phases/agents)
+6. Understanding [Topic]（步骤前的背景说明，可配表格）
-7. Installation (optional)
+7. Installation（可选）
 8. Step 1: [First Major Task]
 9. Step 2: [Second Major Task]
 10. Step 3: [Third Major Task]
-11. What You've Accomplished (summary + folder structure)
+11. What You've Accomplished（总结 + 文件结构）
-12. Quick Reference (commands table)
+12. Quick Reference（skills 表）
-13. Common Questions (FAQ format)
+13. Common Questions（FAQ）
-14. Getting Help (community links)
+14. Getting Help（社区入口）
-15. Key Takeaways (tip admonition)
+15. Key Takeaways（末尾 tip 提示块）
 ```
 
-### Tutorial Checklist
+### 教程检查清单
 
-- [ ] Hook describes outcome in 1-2 sentences
+- [ ] Hook 用 1-2 句明确结果
-- [ ] "What You'll Learn" section present
+- [ ] 包含 “What You'll Learn”
-- [ ] Prerequisites in admonition
+- [ ] 前置条件放在 admonition
-- [ ] Quick Path TL;DR admonition at top
+- [ ] 顶部有 Quick Path TL;DR
-- [ ] Tables for phases, commands, agents
+- [ ] 关键信息用 phases/skills/agents 表格
-- [ ] "What You've Accomplished" section present
+- [ ] 包含 “What You've Accomplished”
-- [ ] Quick Reference table present
+- [ ] 包含 Quick Reference 表
-- [ ] Common Questions section present
+- [ ] 包含 Common Questions
-- [ ] Getting Help section present
+- [ ] 包含 Getting Help
-- [ ] Key Takeaways admonition at end
+- [ ] 末尾包含 Key Takeaways 提示块
 
-## How-To Structure
+## How-to 结构
 
 ```text
-1. Title + Hook (one sentence: "Use the `X` workflow to...")
+1. Title + Hook（单句，形如 "Use the `X` workflow to..."）
-2. When to Use This (bullet list of scenarios)
+2. When to Use This（3-5 条场景）
-3. When to Skip This (optional)
+3. When to Skip This（可选）
-4. Prerequisites (note admonition)
+4. Prerequisites（note 提示块）
-5. Steps (numbered ### subsections)
+5. Steps（编号 `###` 动词开头）
-6. What You Get (output/artifacts produced)
+6. What You Get（产出物说明）
-7. Example (optional)
+7. Example（可选）
-8. Tips (optional)
+8. Tips（可选）
-9. Next Steps (optional)
+9. Next Steps（可选）
 ```
 
-### How-To Checklist
+### How-to 检查清单
 
-- [ ] Hook starts with "Use the `X` workflow to..."
+- [ ] Hook 以 “Use the `X` workflow to...” 开头
-- [ ] "When to Use This" has 3-5 bullet points
+- [ ] “When to Use This” 有 3-5 条场景
-- [ ] Prerequisites listed
+- [ ] 明确前置条件
-- [ ] Steps are numbered `###` subsections with action verbs
+- [ ] 步骤为编号 `###` 子标题且动词开头
-- [ ] "What You Get" describes output artifacts
+- [ ] “What You Get” 明确产出物
 
-## Explanation Structure
+## Explanation 结构
 
-### Types
+### 类型
 
-| Type              | Example                       |
+| 类型 | 示例 |
-| ----------------- | ----------------------------- |
+| --- | --- |
 | **Index/Landing** | `core-concepts/index.md` |
 | **Concept** | `what-are-agents.md` |
 | **Feature** | `quick-dev.md` |
 | **Philosophy** | `why-solutioning-matters.md` |
 | **FAQ** | `established-projects-faq.md` |
 
-### General Template
+### 通用模板
 
 ```text
-1. Title + Hook (1-2 sentences)
+1. Title + Hook（1-2 句）
-2. Overview/Definition (what it is, why it matters)
+2. Overview/Definition（是什么，为什么重要）
-3. Key Concepts (### subsections)
+3. Key Concepts（`###` 小节）
-4. Comparison Table (optional)
+4. Comparison Table（可选）
-5. When to Use / When Not to Use (optional)
+5. When to Use / When Not to Use（可选）
-6. Diagram (optional - mermaid, 1 per doc max)
+6. Diagram（可选，单文档最多 1 个 mermaid）
-7. Next Steps (optional)
+7. Next Steps（可选）
 ```
 
-### Index/Landing Pages
+### Index/Landing 页面
 
 ```text
-1. Title + Hook (one sentence)
+1. Title + Hook（单句）
-2. Content Table (links with descriptions)
+2. Content Table（链接 + 描述）
-3. Getting Started (numbered list)
+3. Getting Started（编号步骤）
-4. Choose Your Path (optional - decision tree)
+4. Choose Your Path（可选，决策树）
 ```
 
-### Concept Explainers
+### 概念解释页（Concept）
 
 ```text
-1. Title + Hook (what it is)
+1. Title + Hook（定义性开场）
-2. Types/Categories (### subsections) (optional)
+2. Types/Categories（可选，`###`）
 3. Key Differences Table
 4. Components/Parts
 5. Which Should You Use?
-6. Creating/Customizing (pointer to how-to guides)
+6. Creating/Customizing（指向 how-to）
 ```
 
-### Feature Explainers
+### 功能解释页（Feature）
 
 ```text
-1. Title + Hook (what it does)
+1. Title + Hook（功能作用）
-2. Quick Facts (optional - "Perfect for:", "Time to:")
+2. Quick Facts（可选）
 3. When to Use / When Not to Use
-4. How It Works (mermaid diagram optional)
+4. How It Works（可选 mermaid）
 5. Key Benefits
-6. Comparison Table (optional)
+6. Comparison Table（可选）
-7. When to Graduate/Upgrade (optional)
+7. When to Graduate/Upgrade（可选）
 ```
 
-### Philosophy/Rationale Documents
+### 原理/哲学页（Philosophy）
 
 ```text
-1. Title + Hook (the principle)
+1. Title + Hook（核心原则）
 2. The Problem
 3. The Solution
-4. Key Principles (### subsections)
+4. Key Principles（`###`）
 5. Benefits
 6. When This Applies
 ```
 
-### Explanation Checklist
+### Explanation 检查清单
 
-- [ ] Hook states what document explains
+- [ ] Hook 清楚说明“本文解释什么”
-- [ ] Content in scannable `##` sections
+- [ ] 内容分布在可扫读的 `##` 区块
-- [ ] Comparison tables for 3+ options
+- [ ] 3 个以上选项时使用对比表
-- [ ] Diagrams have clear labels
+- [ ] 图示有清晰标签
-- [ ] Links to how-to guides for procedural questions
+- [ ] 程序性问题链接到 how-to
-- [ ] 2-3 admonitions max per document
+- [ ] 每篇控制在 2-3 个 admonition
 
-## Reference Structure
+## Reference 结构
 
-### Types
+### 类型
 
-| Type              | Example               |
+| 类型 | 示例 |
-| ----------------- | --------------------- |
+| --- | --- |
 | **Index/Landing** | `workflows/index.md` |
 | **Catalog** | `agents/index.md` |
 | **Deep-Dive** | `document-project.md` |
@@ -229,79 +229,79 @@ your-project/
 | **Glossary** | `glossary/index.md` |
 | **Comprehensive** | `bmgd-workflows.md` |
 
-### Reference Index Pages
+### Reference 索引页
 
 ```text
-1. Title + Hook (one sentence)
+1. Title + Hook（单句）
-2. Content Sections (## for each category)
+2. Content Sections（每类一个 `##`）
-   - Bullet list with links and descriptions
+   - 链接 + 简短描述
 ```
 
-### Catalog Reference
+### Catalog 参考页
 
 ```text
 1. Title + Hook
-2. Items (## for each item)
+2. Items（每项一个 `##`）
-   - Brief description (one sentence)
+   - 单句说明
-   - **Commands:** or **Key Info:** as flat list
+   - **Skills:** 或 **Key Info:** 平铺列表
-3. Universal/Shared (## section) (optional)
+3. Universal/Shared（可选）
 ```
 
-### Item Deep-Dive Reference
+### Deep-Dive 参考页
 
 ```text
-1. Title + Hook (one sentence purpose)
+1. Title + Hook（单句说明用途）
-2. Quick Facts (optional note admonition)
+2. Quick Facts（可选 note 提示块）
-   - Module, Command, Input, Output as list
+   - Module, Skill, Input, Output
-3. Purpose/Overview (## section)
+3. Purpose/Overview（`##`）
-4. How to Invoke (code block)
+4. How to Invoke（代码块）
-5. Key Sections (## for each aspect)
+5. Key Sections（每个方面一个 `##`）
-   - Use ### for sub-options
+   - 子选项使用 `###`
-6. Notes/Caveats (tip or caution admonition)
+6. Notes/Caveats（tip/caution）
 ```
 
-### Configuration Reference
+### Configuration 参考页
 
 ```text
 1. Title + Hook
-2. Table of Contents (jump links if 4+ items)
+2. Table of Contents（可选，4 项以上建议）
-3. Items (## for each config/task)
+3. Items（每项一个 `##`）
-   - **Bold summary** — one sentence
+   - **Bold summary**（单句）
-   - **Use it when:** bullet list
+   - **Use it when:** 场景列表
-   - **How it works:** numbered steps (3-5 max)
+   - **How it works:** 3-5 步
-   - **Output:** expected result (optional)
+   - **Output:**（可选）
 ```
 
-### Comprehensive Reference Guide
+### 综合参考页（Comprehensive）
 
 ```text
 1. Title + Hook
-2. Overview (## section)
+2. Overview（`##`）
-   - Diagram or table showing organization
+   - 用图或表解释组织方式
-3. Major Sections (## for each phase/category)
+3. Major Sections（每个阶段/类别一个 `##`）
-   - Items (### for each item)
+   - Items（每项 `###`）
-   - Standardized fields: Command, Agent, Input, Output, Description
+   - 统一字段：Skill, Agent, Input, Output, Description
-4. Next Steps (optional)
+4. Next Steps（可选）
 ```
 
-### Reference Checklist
+### Reference 检查清单
 
-- [ ] Hook states what document references
+- [ ] Hook 说明“本文引用什么”
-- [ ] Structure matches reference type
+- [ ] 结构匹配参考页类型
-- [ ] Items use consistent structure throughout
+- [ ] 条目结构前后一致
-- [ ] Tables for structured/comparative data
+- [ ] 结构化信息优先表格表达
-- [ ] Links to explanation docs for conceptual depth
+- [ ] 概念深度指向 explanation 页面
-- [ ] 1-2 admonitions max
+- [ ] 每篇 1-2 个 admonition
 
-## Glossary Structure
+## Glossary 结构
 
-Starlight generates right-side "On this page" navigation from headers:
+Starlight 右侧 “On this page” 来自标题层级：
 
-- Categories as `##` headers — appear in right nav
+- 分类使用 `##`（会进入右侧导航）
-- Terms in tables — compact rows, not individual headers
+- 术语放在表格行中（不要给每个术语单独标题）
-- No inline TOC — right sidebar handles navigation
+- 不要再写内联 TOC
 
-### Table Format
+### 表格模板
 
 ```md
 ## Category Name
@@ -312,17 +312,17 @@ Starlight generates right-side "On this page" navigation from headers:
 | **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. |
 ```
 
-### Definition Rules
+### 定义规则
 
-| Do                            | Don't                                       |
+| 推荐 | 避免 |
-| ----------------------------- | ------------------------------------------- |
+| --- | --- |
-| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." |
+| 直接写“它是什么/做什么” | 以 “This is...” 或 “A [term] is...” 开头 |
-| Keep to 1-2 sentences         | Write multi-paragraph explanations          |
+| 控制在 1-2 句 | 多段长解释 |
-| Bold term name in cell        | Use plain text for terms                    |
+| 术语名称加粗 | 术语用普通文本 |
 
-### Context Markers
+### 语境标记（Context Markers）
 
-Add italic context at definition start for limited-scope terms:
+在定义开头用斜体标记适用范围：
 
 - `*Quick Flow only.*`
 - `*BMad Method/Enterprise.*`
@@ -330,16 +330,16 @@ Add italic context at definition start for limited-scope terms:
 - `*BMGD.*`
 - `*Established projects.*`
 
-### Glossary Checklist
+### Glossary 检查清单
 
-- [ ] Terms in tables, not individual headers
+- [ ] 术语以表格维护，不用独立标题
-- [ ] Terms alphabetized within categories
+- [ ] 同分类内按字母序排序
-- [ ] Definitions 1-2 sentences
+- [ ] 定义控制在 1-2 句
-- [ ] Context markers italicized
+- [ ] 语境标记使用斜体
-- [ ] Term names bolded in cells
+- [ ] 术语名称在单元格中加粗
-- [ ] No "A [term] is..." definitions
+- [ ] 避免 “A [term] is...” 句式
 
-## FAQ Sections
+## FAQ 章节模板
 
 ```md
 ## Questions
@@ -353,18 +353,18 @@ Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.
 
 ### Can I change my plan later?
 
-Yes. The SM agent has a `correct-course` workflow for handling scope changes.
+Yes. The SM agent has a `bmad-correct-course` workflow for handling scope changes.
 
 **Have a question not answered here?** [Open an issue](...) or ask in [Discord](...).
 ```
 
-## Validation Commands
+## 校验命令
 
-Before submitting documentation changes:
+提交文档改动前，建议执行：
 
 ```bash
-npm run docs:fix-links            # Preview link format fixes
+npm run docs:fix-links            # 预览链接修复结果
-npm run docs:fix-links -- --write # Apply fixes
+npm run docs:fix-links -- --write # 写回链接修复
-npm run docs:validate-links       # Check links exist
+npm run docs:validate-links       # 校验链接是否存在
-npm run docs:build                # Verify no build errors
+npm run docs:build                # 校验站点构建
 ```

docs/zh-cn/how-to/customize-bmad.md

@@ -5,56 +5,56 @@ sidebar:
   order: 7
 ---
 
-使用 `.customize.yaml` 文件来调整智能体行为、角色和菜单，同时在更新过程中保留您的更改。
+使用 `.customize.yaml` 文件，自定义智能体（agent）的行为、角色（persona）和菜单，同时在后续更新中保留你的改动。
 
 ## 何时使用此功能
 
-- 您想要更改智能体的名称、个性或沟通风格
+- 你想修改智能体名称、身份设定或沟通风格
-- 您需要智能体记住项目特定的上下文
+- 你需要让智能体长期记住项目约束和背景信息
-- 您想要添加自定义菜单项来触发您自己的工作流或提示
+- 你希望增加自定义菜单项，触发自己的工作流或提示
-- 您希望智能体在每次启动时执行特定操作
+- 你希望智能体每次启动都先执行固定动作
 
 :::note[前置条件]
-- 在项目中安装了 BMad（参见[如何安装 BMad](./install-bmad.md)）
+- 已在项目中安装 BMad（参见[如何安装 BMad](./install-bmad.md)）
 - 用于编辑 YAML 文件的文本编辑器
 :::
 
 :::caution[保护您的自定义配置]
-始终使用此处描述的 `.customize.yaml` 文件，而不是直接编辑智能体文件。安装程序在更新期间会覆盖智能体文件，但会保留您的 `.customize.yaml` 更改。
+始终通过 `.customize.yaml` 自定义，不要直接改动智能体源文件。安装程序在更新时会覆盖智能体文件，但会保留 `.customize.yaml` 的内容。
 :::
 
 ## 步骤
 
 ### 1. 定位自定义文件
 
-安装后，在以下位置为每个智能体找到一个 `.customize.yaml` 文件：
+安装完成后，每个已安装智能体都会在下面目录生成一个 `.customize.yaml`：
 
 ```text
 _bmad/_config/agents/
 ├── core-bmad-master.customize.yaml
 ├── bmm-dev.customize.yaml
 ├── bmm-pm.customize.yaml
-└── ...（每个已安装的智能体一个文件）
+└── ...（每个已安装智能体一个文件）
 ```
 
 ### 2. 编辑自定义文件
 
-打开您想要修改的智能体的 `.customize.yaml` 文件。每个部分都是可选的——只自定义您需要的内容。
+打开目标智能体的 `.customize.yaml`。各段都可选，只改你需要的部分即可。
 
-| 部分               | 行为     | 用途                                           |
+| 部分 | 作用方式 | 用途 |
 | ------------------ | -------- | ---------------------------------------------- |
-| `agent.metadata`   | 替换     | 覆盖智能体的显示名称                           |
+| `agent.metadata` | 覆盖 | 覆盖智能体显示名称 |
-| `persona`          | 替换     | 设置角色、身份、风格和原则                     |
+| `persona` | 覆盖 | 设置角色、身份、风格和原则 |
-| `memories`         | 追加     | 添加智能体始终会记住的持久上下文               |
+| `memories` | 追加 | 添加智能体长期记忆的上下文 |
-| `menu`             | 追加     | 为工作流或提示添加自定义菜单项                 |
+| `menu` | 追加 | 增加指向工作流或提示的菜单项 |
-| `critical_actions` | 追加     | 定义智能体的启动指令                           |
+| `critical_actions` | 追加 | 定义智能体启动时要执行的动作 |
-| `prompts`          | 追加     | 创建可重复使用的提示供菜单操作使用             |
+| `prompts` | 追加 | 创建可复用提示，供菜单 `action` 引用 |
 
-标记为 **替换** 的部分会完全覆盖智能体的默认设置。标记为 **追加** 的部分会添加到现有配置中。
+标记为 **覆盖** 的部分会完全替换默认配置；标记为 **追加** 的部分会在默认配置基础上累加。
 
-**智能体名称**
+**智能体名称（`agent.metadata`）**
 
-更改智能体的自我介绍方式：
+修改智能体的显示名称：
 
 ```yaml
 agent:
@@ -62,9 +62,9 @@ agent:
     name: 'Spongebob' # 默认值："Amelia"
 ```
 
-**角色**
+**角色（`persona`）**
 
-替换智能体的个性、角色和沟通风格：
+替换智能体的人设、职责和沟通风格：
 
 ```yaml
 persona:
@@ -76,11 +76,11 @@ persona:
     - 'Favor composition over inheritance'
 ```
 
-`persona` 部分会替换整个默认角色，因此如果您设置它，请包含所有四个字段。
+`persona` 会覆盖默认整段配置，所以启用时请把四个字段都填全。
 
-**记忆**
+**记忆（`memories`）**
 
-添加智能体将始终记住的持久上下文：
+添加智能体会长期记住的上下文：
 
 ```yaml
 memories:
@@ -89,9 +89,9 @@ memories:
   - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed'
 ```
 
-**菜单项**
+**菜单项（`menu`）**
 
-向智能体的显示菜单添加自定义条目。每个条目需要一个 `trigger`、一个目标（`workflow` 路径或 `action` 引用）和一个 `description`：
+给智能体菜单添加自定义项。每个条目都需要 `trigger`、目标（`workflow` 路径或 `action` 引用）和 `description`：
 
 ```yaml
 menu:
@@ -103,18 +103,18 @@ menu:
     description: Deploy to production
 ```
 
-**关键操作**
+**启动关键动作（`critical_actions`）**
 
-定义智能体启动时运行的指令：
+定义智能体启动时执行的指令：
 
 ```yaml
 critical_actions:
   - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'
 ```
 
-**自定义提示**
+**可复用提示（`prompts`）**
 
-创建可重复使用的提示，菜单项可以通过 `action="#id"` 引用：
+创建可复用提示，菜单项可通过 `action="#id"` 调用：
 
 ```yaml
 prompts:
@@ -126,56 +126,51 @@ prompts:
       3. Execute deployment script
 ```
 
-### 3. 应用您的更改
+### 3. 应用更改
 
-编辑后，重新安装以应用更改：
+编辑完成后，重新安装以应用配置：
 
 ```bash
 npx bmad-method install
 ```
 
-安装程序会检测现有安装并提供以下选项：
+安装程序会识别现有安装，并给出以下选项：
 
-| Option                       | What It Does                                                        |
+| 选项 | 作用 |
 | ---------------------------- | ------------------------------------------------------------------- |
-| **Quick Update**             | 将所有模块更新到最新版本并应用自定义配置                     |
+| **Quick Update** | 更新所有模块到最新版本，并应用你的自定义配置 |
-| **Modify BMad Installation** | 用于添加或删除模块的完整安装流程                             |
+| **Modify BMad Installation** | 进入完整安装流程，用于增删模块 |
 
-对于仅自定义配置的更改，**Quick Update** 是最快的选项。
+如果只是调整 `.customize.yaml`，优先选 **Quick Update**。
 
-## 故障排除
+## 故障排查
 
-**更改未生效？**
+**改动没有生效？**
 
 - 运行 `npx bmad-method install` 并选择 **Quick Update** 以应用更改
-- 检查您的 YAML 语法是否有效（缩进很重要）
+- 检查 YAML 语法是否正确（尤其是缩进）
-- 验证您编辑的是该智能体正确的 `.customize.yaml` 文件
+- 确认你编辑的是目标智能体对应的 `.customize.yaml`
 
 **智能体无法加载？**
 
 - 使用在线 YAML 验证器检查 YAML 语法错误
-- 确保在取消注释后没有留下空字段
+- 确保取消注释后没有遗留空字段
-- 尝试恢复到原始模板并重新构建
+- 可先回退到模板，再逐项恢复自定义配置
 
-**需要重置智能体？**
+**需要重置某个智能体？**
 
 - 清空或删除智能体的 `.customize.yaml` 文件
 - 运行 `npx bmad-method install` 并选择 **Quick Update** 以恢复默认设置
 
 ## 工作流自定义
 
-对现有 BMad Method 工作流和技能的自定义即将推出。
+对现有 BMad Method 工作流和技能的深度自定义能力即将推出。
 
 ## 模块自定义
 
 关于构建扩展模块和自定义现有模块的指南即将推出。
 
----
+## 后续步骤
-## 术语说明
 
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
+- [文档分片指南](./shard-large-documents.md) - 了解如何管理超长文档
-- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。
+- [命令参考](../reference/commands.md) - 查看可用命令和工作流入口
-- **persona**：角色。指智能体的身份、个性、沟通风格和行为原则的集合。
-- **memory**：记忆。指智能体持久存储的上下文信息，用于在对话中保持连贯性。
-- **critical action**：关键操作。指智能体启动时必须执行的指令或任务。
-- **prompt**：提示。指发送给智能体的输入文本，用于引导其生成特定响应或执行特定操作。

docs/zh-cn/how-to/shard-large-documents.md

@@ -5,19 +5,21 @@ sidebar:
   order: 9
 ---
 
-如果需要将大型 Markdown 文件拆分为更小、组织良好的文件以更好地管理上下文，请使用 `shard-doc` 工具。
+当单个 Markdown 文档过大、影响模型读取时，可使用 `bmad-shard-doc` 工作流把文档拆成按章节组织的小文件，降低上下文压力。
 
 :::caution[已弃用]
-不再推荐使用此方法，随着工作流程的更新以及大多数主要 LLM 和工具支持子进程，这很快将变得不再必要。
+这是兼容性方案，默认不推荐。随着工作流更新，以及主流模型/工具逐步支持子进程（subprocesses），很多场景将不再需要手动分片。
 :::
 
 ## 何时使用
 
-仅当你发现所选工具/模型组合无法在需要时加载和读取所有文档作为输入时，才使用此方法。
+- 你确认当前工具/模型在关键步骤无法一次读入完整文档
+- 文档体量已明显影响工作流稳定性或响应质量
+- 你需要保留原文结构，但希望按 `##` 章节拆分维护
 
 ## 什么是文档分片？
 
-文档分片根据二级标题（`## Heading`）将大型 Markdown 文件拆分为更小、组织良好的文件。
+文档分片会按二级标题（`## Heading`）把大型 Markdown 文件拆成多个子文件，并生成一个 `index.md` 作为入口。
 
 ### 架构
 
@@ -38,16 +40,16 @@ _bmad-output/planning-artifacts/
 
 ## 步骤
 
-### 1. 运行 Shard-Doc 工具
+### 1. 运行 `bmad-shard-doc` 工作流
 
 ```bash
 /bmad-shard-doc
 ```
 
-### 2. 遵循交互式流程
+### 2. 按交互流程完成分片
 
 ```text
-智能体：您想要分片哪个文档？
+智能体：你想分片哪个文档？
 用户：docs/PRD.md
 
 智能体：默认目标位置：docs/prd/
@@ -60,27 +62,21 @@ _bmad-output/planning-artifacts/
        ✓ 完成！
 ```
 
-## 工作流程发现机制
+## 工作流发现机制
 
-BMad 工作流程使用**双重发现系统**：
+BMad 工作流使用**双重发现机制**：
 
-1. **首先尝试完整文档** - 查找 `document-name.md`
+1. **先查完整文档** - 查找 `document-name.md`
-2. **检查分片版本** - 查找 `document-name/index.md`
+2. **再查分片入口** - 查找 `document-name/index.md`
-3. **优先级规则** - 如果两者都存在，完整文档优先 - 如果希望使用分片版本，请删除完整文档
+3. **优先级规则** - 若两者并存，默认优先完整文档；若你要强制使用分片版本，请删除或重命名完整文档
 
-## 工作流程支持
+## 你将获得
 
-所有 BMM 工作流程都支持这两种格式：
+- 原始完整文档（可保留，但不建议与分片长期并存；并存时默认优先读取完整文档）
+- 分片目录（如 `document-name/index.md` + 各章节文件）
+- 对工作流透明的自动识别行为（无需额外配置）
 
-- 完整文档
+## 后续步骤
-- 分片文档
-- 自动检测
-- 对用户透明
 
----
+- [如何自定义 BMad](./customize-bmad.md) - 了解高级配置与工作流定制边界
-## 术语说明
+- [如何升级到 v6](./upgrade-to-v6.md) - 在迁移过程中处理文档与目录结构变化
-
-- **sharding**：分片。将大型文档或数据集拆分为更小、更易管理的部分的过程。
-- **token**：令牌。在自然语言处理和大型语言模型中，文本的基本单位，通常对应单词或字符的一部分。
-- **subprocesses**：子进程。由主进程创建的独立执行单元，可以并行运行以执行特定任务。
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。

docs/zh-cn/how-to/upgrade-to-v6.md

@@ -5,76 +5,83 @@ sidebar:
   order: 3
 ---
 
-使用 BMad 安装程序从 v4 升级到 v6，其中包括自动检测旧版安装和迁移辅助。
+使用 BMad 安装程序把 v4 升级到 v6。安装程序会自动识别旧安装，并提供迁移辅助，帮助你在已有项目中平滑过渡。
 
 ## 何时使用本指南
 
-- 您已安装 BMad v4（`.bmad-method` 文件夹）
+- 你已安装 BMad v4（目录名通常是 `.bmad-method`）
-- 您希望迁移到新的 v6 架构
+- 你准备迁移到 v6 的统一目录结构
-- 您有需要保留的现有规划产物
+- 你有要保留的规划产物或进行中的开发工作
 
 :::note[前置条件]
 - Node.js 20+
-- 现有的 BMad v4 安装
+- 现有 BMad v4 安装
 :::
 
+::::caution[先备份再迁移]
+如果当前仓库里仍有未提交的重要变更，先完成提交或备份，再执行升级。
+::::
+
 ## 步骤
 
 ### 1. 运行安装程序
 
 按照[安装程序说明](./install-bmad.md)操作。
 
-### 2. 处理旧版安装
+### 2. 处理旧版安装目录
 
-当检测到 v4 时，您可以：
+当检测到 v4 时，你有两种处理方式：
 
-- 允许安装程序备份并删除 `.bmad-method`
+- 允许安装程序自动备份并删除 `.bmad-method`
-- 退出并手动处理清理
+- 先退出安装流程，再手动清理旧目录
 
-如果您将 bmad method 文件夹命名为其他名称 - 您需要手动删除该文件夹。
+如果你把 BMad Method 目录改成了其他名字，需要你自己手动定位并删除。
 
-### 3. 清理 IDE 命令
+### 3. 清理 IDE 命令与技能目录
 
-手动删除旧版 v4 IDE 命令 - 例如如果您使用 claude，查找任何以 bmad 开头的嵌套文件夹并删除它们：
+手动删除旧版 v4 IDE 命令/技能目录。以 Claude Code 为例，请在旧目录中删除以 `bmad` 开头的嵌套目录：
 
-- `.claude/commands/BMad/agents`
+- `.claude/commands/`
-- `.claude/commands/BMad/tasks`
+
+v6 新技能会安装到：
+
+- `.claude/skills/`
 
 ### 4. 迁移规划产物
 
-**如果您有规划文档（Brief/PRD/UX/Architecture）：**
+**如果你有规划文档（Brief/PRD/UX/Architecture）：**
 
-将它们移动到 `_bmad-output/planning-artifacts/` 并使用描述性名称：
+把它们移动到 `_bmad-output/planning-artifacts/`，并使用可读的文件名：
 
-- 在文件名中包含 `PRD` 用于 PRD 文档
+- PRD 文档文件名包含 `PRD`
-- 相应地包含 `brief`、`architecture` 或 `ux-design`
+- 其他文档按类型包含 `brief`、`architecture` 或 `ux-design`
-- 分片文档可以放在命名的子文件夹中
+- 分片文档可放在命名清晰的子目录中
 
-**如果您正在进行规划：** 考虑使用 v6 工作流重新开始。将现有文档作为输入——新的渐进式发现工作流配合网络搜索和 IDE 计划模式会产生更好的结果。
+**如果你仍在规划中：** 建议直接用 v6 工作流重启规划，把现有文档作为输入；新版渐进式发现流程配合 Web 搜索和 IDE 计划模式通常会得到更稳妥的结果。
 
-### 5. 迁移进行中的开发
+### 5. 迁移进行中的开发工作
 
-如果您已创建或实现了故事：
+如果你已经创建或实现了部分用户故事（story）：
 
 1. 完成 v6 安装
 2. 将 `epics.md` 或 `epics/epic*.md` 放入 `_bmad-output/planning-artifacts/`
-3. 运行 Scrum Master 的 `sprint-planning` 工作流
+3. 运行 Scrum Master 的 `bmad-sprint-planning` 工作流
 4. 告诉 SM 哪些史诗/故事已经完成
 
-## 您将获得
+## 你将获得
 
 **v6 统一结构：**
 
 ```text
 your-project/
-├── _bmad/               # 单一安装文件夹
+├── _bmad/               # 单一安装目录
-│   ├── _config/         # 您的自定义配置
+│   ├── _config/         # 你的自定义配置
 │   │   └── agents/      # 智能体自定义文件
 │   ├── core/            # 通用核心框架
 │   ├── bmm/             # BMad Method 模块
 │   ├── bmb/             # BMad Builder
 │   └── cis/             # Creative Intelligence Suite
-└── _bmad-output/        # 输出文件夹（v4 中为 doc 文件夹）
+└── _bmad-output/        # 输出目录（v4 时代常见为 doc 目录）
 ```
 
 ## 模块迁移
@@ -87,34 +94,18 @@ your-project/
 | `.bmad-infrastructure-devops` | 已弃用 — 新的 DevOps 智能体即将推出       |
 | `.bmad-creative-writing`      | 未适配 — 新的 v6 模块即将推出             |
 
-## 主要变更
+## 关键差异（旧名/新名）
 
-| 概念         | v4                                      | v6                                   |
+| 概念 | v4（旧） | v6（新） | 迁移提示 |
-| ------------ | --------------------------------------- | ------------------------------------ |
+| ------------ | --------------------------------------- | ------------------------------------ | ------------------------------------ |
-| **核心**     | `_bmad-core` 实际上是 BMad Method      | `_bmad/core/` 是通用框架             |
+| **核心框架** | `_bmad-core` 实际上承载的是 BMad Method | `_bmad/core/` 变成通用框架层 | 迁移时不要再把 `_bmad/core/` 当成 Method 本体 |
-| **方法**     | `_bmad-method`                          | `_bmad/bmm/`                         |
+| **方法模块** | `_bmad-method` | `_bmad/bmm/` | 旧脚本、路径引用需同步更新到 `bmm` |
-| **配置**     | 直接修改文件                            | 每个模块使用 `config.yaml`           |
+| **配置方式** | 直接改模块文件 | 每个模块通过 `config.yaml` 管理 | 优先改配置，不要直接改生成文件 |
-| **文档**     | 需要设置分片或非分片                    | 完全灵活，自动扫描                   |
+| **文档读取** | 需要手动区分分片/非分片 | 自动扫描完整文档与分片入口 | 只有在兼容性场景下才建议手动分片 |
 
----
+## 后续建议
-## 术语说明
 
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
+- 升级完成后先运行 `bmad-help`，确认可用工作流与下一步建议
-- **epic**：史诗。在敏捷开发中，指大型的工作项，可分解为多个用户故事。
+- 如果是既有项目，补充或更新 `project-context.md`，减少后续实现偏差
-- **story**：故事。在敏捷开发中，指用户故事，描述用户需求的功能单元。
+- 在继续开发前，先做一次关键链路验证（安装、命令触发、文档读取）
-- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队流程和移除障碍。
+- 继续阅读：[如何安装 BMad](./install-bmad.md)、[管理项目上下文](./project-context.md)
-- **sprint-planning**：冲刺规划。Scrum 框架中的会议，用于确定下一个冲刺期间要完成的工作。
-- **sharded**：分片。将大型文档拆分为多个较小的文件以便于管理和处理。
-- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和特性的文档。
-- **Brief**：简报。概述项目目标、范围和关键信息的文档。
-- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。
-- **Architecture**：架构。系统的结构设计，包括组件、模块及其相互关系。
-- **BMGD**：BMad Game Development。BMad 游戏开发模块。
-- **DevOps**：开发运维（Development Operations）。结合开发和运维的实践，旨在缩短系统开发生命周期。
-- **BMad Method**：BMad 方法。BMad 框架的核心方法论模块。
-- **BMad Builder**：BMad 构建器。BMad 框架的构建工具。
-- **Creative Intelligence Suite**：创意智能套件。BMad 框架中的创意工具集合。
-- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试等功能的软件开发工具。
-- **progressive discovery**：渐进式发现。逐步深入探索和理解需求的过程。
-- **web search**：网络搜索。通过互联网检索信息的能力。
-- **plan mode**：计划模式。IDE 中的一种工作模式，用于规划和设计任务。

docs/zh-cn/reference/modules.md

@@ -1,94 +1,94 @@
 ---
 title: "官方模块"
-description: 用于构建自定义智能体、创意智能、游戏开发和测试的附加模块
+description: BMad 可选模块参考：能力边界、适用场景与外部资源
 sidebar:
   order: 4
 ---
 
-BMad 通过您在安装期间选择的官方模块进行扩展。这些附加模块为内置核心和 BMM（敏捷套件）之外的特定领域提供专门的智能体、工作流和任务。
+BMad 通过可选模块扩展能力。你可以在安装时按需选择模块，为当前项目增加特定领域的 `agent`、`workflow` 与 `skill`。
 
 :::tip[安装模块]
-运行 `npx bmad-method install` 并选择您需要的模块。安装程序会自动处理下载、配置和 IDE 集成。
+运行 `npx bmad-method install`，在交互步骤中勾选所需模块。安装器会自动生成对应 skills 并写入当前 IDE 的 skills 目录。
 :::
 
-## BMad Builder
+## 先看总览
 
-在引导式协助下创建自定义智能体、工作流和特定领域的模块。BMad Builder 是用于扩展框架本身的元模块。
+| 模块 | 代码 | 最适合 | 核心能力 |
+| --- | --- | --- | --- |
+| BMad Builder | `bmb` | 扩展 BMad 本身 | 构建自定义 agent / workflow / module |
+| Creative Intelligence Suite | `cis` | 前期创意与问题探索 | 头脑风暴、设计思维、创新策略 |
+| Game Dev Studio | `gds` | 游戏方向研发 | 游戏设计文档、原型推进、叙事支持 |
+| Test Architect（TEA） | `tea` | 企业级测试治理 | 测试策略、可追溯性、质量门控 |
 
-- **代码：** `bmb`
+## BMad Builder（`bmb`）
-- **npm：** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder)
-- **GitHub：** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder)
 
-**提供：**
+用于“构建 BMad”的元模块，重点是把你的方法沉淀成可复用能力。
 
-- 智能体构建器 —— 创建具有自定义专业知识和工具访问权限的专用 AI 智能体
+**你会得到：**
-- 工作流构建器 —— 设计包含步骤和决策点的结构化流程
+- Agent Builder：创建具备特定专业能力的 agent
-- 模块构建器 —— 将智能体和工作流打包为可共享、可发布的模块
+- Workflow Builder：设计有步骤与决策点的 workflow
-- 交互式设置，支持 YAML 配置和 npm 发布
+- Module Builder：将 agent/workflow 打包为可发布模块
+- 交互式配置与发布支持（YAML + npm）
 
-## 创意智能套件
+**外部资源（英文）：**
+- npm: [`bmad-builder`](https://www.npmjs.com/package/bmad-builder)
+- GitHub: [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder)
 
-用于早期开发阶段的结构化创意、构思和创新的 AI 驱动工具。该套件提供多个智能体，利用经过验证的框架促进头脑风暴、设计思维和问题解决。
+## Creative Intelligence Suite（`cis`）
 
-- **代码：** `cis`
+用于前期探索与创意发散，帮助团队在进入规划前澄清问题与方向。
-- **npm：** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite)
-- **GitHub：** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)
 
-**提供：**
+**你会得到：**
+- 多个创意向 agent（如创新策略、设计思维、头脑风暴）
+- 问题重构与系统化思考支持
+- 常见构思框架（含 SCAMPER、逆向头脑风暴等）
 
-- 创新策略师、设计思维教练和头脑风暴教练智能体
+**外部资源（英文）：**
-- 问题解决者和创意问题解决者，用于系统性和横向思维
+- npm: [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite)
-- 故事讲述者和演示大师，用于叙事和推介
+- GitHub: [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)
-- 构思框架，包括 SCAMPER、逆向头脑风暴和问题重构
 
-## 游戏开发工作室
+## Game Dev Studio（`gds`）
 
-适用于 Unity、Unreal、Godot 和自定义引擎的结构化游戏开发工作流。通过 Quick Flow 支持快速原型制作，并通过史诗驱动的冲刺支持全面规模的生产。
+面向游戏开发场景，覆盖从概念到实现的结构化 workflow。
 
-- **代码：** `gds`
+**你会得到：**
-- **npm：** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio)
+- 游戏设计文档（GDD）生成流程
-- **GitHub：** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)
+- 面向快速迭代的 Quick Dev 模式
+- 叙事设计支持（角色、对话、世界观）
+- 多引擎适配建议（Unity/Unreal/Godot 等）
 
-**提供：**
+**外部资源（英文）：**
+- npm: [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio)
+- GitHub: [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)
 
-- 游戏设计文档（GDD）生成工作流
+## Test Architect（TEA，`tea`）
-- 用于快速原型制作的 Quick Dev 模式
-- 针对角色、对话和世界构建的叙事设计支持
-- 覆盖 21+ 种游戏类型，并提供特定引擎的架构指导
 
-## 测试架构师（TEA）
+面向高要求测试场景的独立模块。与内置 QA 相比，TEA 更强调策略、追溯与发布门控。
 
-通过专家智能体和九个结构化工作流提供企业级测试策略、自动化指导和发布门控决策。TEA 远超内置 QA 智能体，提供基于风险的优先级排序和需求可追溯性。
+**你会得到：**
+- Murat 测试架构师 agent
+- 覆盖测试设计、ATDD、自动化、审查、追溯的 workflow
+- NFR 评估、CI 集成与测试框架脚手架
+- P0-P3 风险优先级策略与可选工具集成
 
-- **代码：** `tea`
+**外部资源（英文）：**
-- **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
+- 文档: [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
-- **GitHub：** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)
+- npm: [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
+- GitHub: [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)
 
-**提供：**
+## 如何选择模块
 
-- Murat 智能体（主测试架构师和质量顾问）
+- 你要“扩展框架能力”而不是只用框架：优先 `bmb`
-- 用于测试设计、ATDD、自动化、测试审查和可追溯性的工作流
+- 你还在探索方向、需要结构化创意过程：优先 `cis`
-- NFR 评估、CI 设置和框架脚手架
+- 你是游戏项目：优先 `gds`
-- P0-P3 优先级排序，可选 Playwright Utils 和 MCP 集成
+- 你需要测试治理、质量门控或审计追溯：优先 `tea`
 
-## 社区模块
+:::note[模块可以组合安装]
+模块之间不是互斥关系。你可以按项目阶段增量安装，并在后续重新运行安装器同步 skills。
+:::
 
-社区模块和模块市场即将推出。请查看 [BMad GitHub 组织](https://github.com/bmad-code-org) 获取最新更新。
+## 相关参考
 
----
+- [测试选项](./testing.md)
-## 术语说明
+- [技能（Skills）参考](./commands.md)
-
+- [工作流地图](./workflow-map.md)
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。
-- **module**：模块。指可独立开发、测试和部署的软件单元，用于扩展系统功能。
-- **meta-module**：元模块。指用于创建或扩展其他模块的模块，是模块的模块。
-- **ATDD**：验收测试驱动开发（Acceptance Test-Driven Development）。一种敏捷开发实践，在编写代码之前先编写验收测试。
-- **NFR**：非功能性需求（Non-Functional Requirement）。指系统在性能、安全性、可维护性等方面的质量属性要求。
-- **CI**：持续集成（Continuous Integration）。一种软件开发实践，频繁地将代码集成到主干分支，并进行自动化测试。
-- **MCP**：模型上下文协议（Model Context Protocol）。一种用于在 AI 模型与外部工具或服务之间进行通信的协议。
-- **SCAMPER**：一种创意思维技巧，包含替代、组合、调整、修改、其他用途、消除和重组七个维度。
-- **GDD**：游戏设计文档（Game Design Document）。用于描述游戏设计理念、玩法、机制等内容的详细文档。
-- **P0-P3**：优先级分级。P0 为最高优先级（关键），P3 为最低优先级（可选）。
-- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周，用于完成预定的工作。
-- **epic**：史诗。敏捷开发中的大型工作项，可分解为多个用户故事或任务。
-- **Quick Flow**：快速流程。一种用于快速原型开发的工作流模式。

docs/zh-cn/reference/testing.md

@@ -1,122 +1,105 @@
 ---
 title: "测试选项"
-description: 比较内置 QA 智能体（Quinn）与测试架构师（TEA）模块的测试自动化。
+description: 内置 QA（Quinn）与 TEA 模块对比：何时用哪个、各自边界是什么
 sidebar:
   order: 5
 ---
 
-BMad 提供两条测试路径：用于快速生成测试的内置 QA 智能体，以及用于企业级测试策略的可安装测试架构师模块。
+BMad 有两条测试路径：
+- **Quinn（内置 QA）**：快速生成可运行测试
+- **TEA（可选模块）**：企业级测试策略与治理能力
 
-## 应该使用哪一个？
+## 该选 Quinn 还是 TEA？
 
-| 因素 | Quinn（内置 QA） | TEA 模块 |
+| 维度 | Quinn（内置 QA） | TEA 模块 |
 | --- | --- | --- |
-| **最适合** | 中小型项目、快速覆盖 | 大型项目、受监管或复杂领域 |
+| 最适合 | 中小项目、快速补覆盖 | 大型项目、受监管或复杂业务 |
-| **设置** | 无需安装——包含在 BMM 中 | 通过 `npx bmad-method install` 单独安装 |
+| 安装成本 | 无需额外安装（BMM 内置） | 需通过安装器单独选择 |
-| **方法** | 快速生成测试，稍后迭代 | 先规划，再生成并保持可追溯性 |
+| 方法 | 先生成测试，再迭代 | 先定义策略，再执行并追溯 |
-| **测试类型** | API 和 E2E 测试 | API、E2E、ATDD、NFR 等 |
+| 测试类型 | API + E2E | API、E2E、ATDD、NFR 等 |
-| **策略** | 快乐路径 + 关键边界情况 | 基于风险的优先级排序（P0-P3） |
+| 风险策略 | 快乐路径 + 关键边界 | P0-P3 风险优先级 |
-| **工作流数量** | 1（Automate） | 9（设计、ATDD、自动化、审查、可追溯性等） |
+| workflow 数量 | 1（Automate） | 9（设计/自动化/审查/追溯等） |
 
-:::tip[从 Quinn 开始]
+:::tip[默认建议]
-大多数项目应从 Quinn 开始。如果后续需要测试策略、质量门控或需求可追溯性，可并行安装 TEA。
+大多数项目先用 Quinn。只有当你需要质量门控、合规追溯或系统化测试治理时，再引入 TEA。
 :::
 
-## 内置 QA 智能体（Quinn）
+## 内置 QA（Quinn）
 
-Quinn 是 BMM（敏捷套件）模块中的内置 QA 智能体。它使用项目现有的测试框架快速生成可运行的测试——无需配置或额外安装。
+Quinn 是 BMM 内置 agent，目标是用你现有测试栈快速落地测试，不要求额外配置。
 
-**触发方式：** `QA` 或 `bmad-bmm-qa-automate`
+**触发方式：**
+- 菜单触发器：`QA`
+- skill：`bmad-qa-generate-e2e-tests`
 
-### Quinn 的功能
+### Quinn 会做什么
 
-Quinn 运行单个工作流（Automate），包含五个步骤：
+Quinn 的 Automate 流程通常包含 5 步：
+1. 检测现有测试框架（如 Jest、Vitest、Playwright、Cypress）
+2. 确认待测功能（手动指定或自动发现）
+3. 生成 API 测试（状态码、结构、主路径与错误分支）
+4. 生成 E2E 测试（语义定位器 + 可见结果断言）
+5. 执行并修复基础失败项
 
-1. **检测测试框架**——扫描 `package.json` 和现有测试文件以识别框架（Jest、Vitest、Playwright、Cypress 或任何标准运行器）。如果不存在，则分析项目技术栈并推荐一个。
+**默认风格：**
-2. **识别功能**——询问要测试的内容或自动发现代码库中的功能。
+- 仅使用标准框架 API
-3. **生成 API 测试**——覆盖状态码、响应结构、快乐路径和 1-2 个错误情况。
+- UI 测试优先语义定位器（角色、标签、文本）
-4. **生成 E2E 测试**——使用语义定位器和可见结果断言覆盖用户工作流。
+- 测试互相独立，不依赖顺序
-5. **运行并验证**——执行生成的测试并立即修复失败。
+- 避免硬编码等待/休眠
 
-Quinn 会生成测试摘要，保存到项目的实现产物文件夹中。
+:::note[范围边界]
-
+Quinn 只负责“生成测试”。如需实现质量评审与故事验收，请配合代码审查 workflow（`CR` / `bmad-code-review`）。
-### 测试模式
-
-生成的测试遵循"简单且可维护"的理念：
-
-- **仅使用标准框架 API**——不使用外部工具或自定义抽象
-- UI 测试使用**语义定位器**（角色、标签、文本而非 CSS 选择器）
-- **独立测试**，无顺序依赖
-- **无硬编码等待或休眠**
-- **清晰的描述**，可作为功能文档阅读
-
-:::note[范围]
-Quinn 仅生成测试。如需代码审查和故事验证，请改用代码审查工作流（`CR`）。
 :::
 
-### 何时使用 Quinn
+### 何时用 Quinn
 
-- 为新功能或现有功能快速实现测试覆盖
+- 要快速补齐某个功能的测试覆盖
-- 无需高级设置的初学者友好型测试自动化
+- 团队希望先获得可运行基线，再逐步增强
-- 任何开发者都能阅读和维护的标准测试模式
+- 项目暂不需要完整测试治理体系
-- 不需要全面测试策略的中小型项目
 
-## 测试架构师（TEA）模块
+## TEA（Test Architect）模块
 
-TEA 是一个独立模块，提供专家智能体（Murat）和九个结构化工作流，用于企业级测试。它超越了测试生成，涵盖测试策略、基于风险的规划、质量门控和需求可追溯性。
+TEA 提供专家测试 agent（Murat）与 9 个结构化 workflow，覆盖策略、执行、审查、追溯和发布门控。
 
-- **文档：** [TEA 模块文档（英文）](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
+**外部资源（英文）：**
-- **安装：** `npx bmad-method install` 并选择 TEA 模块
+- 文档: [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
-- **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
+- npm: [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
 
-### TEA 提供的功能
+**安装：** `npx bmad-method install` 后选择 TEA 模块。
 
-| Workflow | Purpose |
+### TEA 的 9 个 workflow
+
+| Workflow | 用途 |
 | --- | --- |
-| Test Design | 创建与需求关联的全面测试策略 |
+| Test Design | 按需求建立测试策略 |
-| ATDD | 基于干系人标准的验收测试驱动开发 |
+| ATDD | 基于验收标准驱动测试设计 |
-| Automate | 使用高级模式和工具生成测试 |
+| Automate | 使用高级模式生成自动化测试 |
-| Test Review | 根据策略验证测试质量和覆盖范围 |
+| Test Review | 评估测试质量与覆盖完整性 |
-| Traceability | 将测试映射回需求，用于审计和合规 |
+| Traceability | 建立“需求—测试”追溯链路 |
-| NFR Assessment | 评估非功能性需求（性能、安全性） |
+| NFR Assessment | 评估性能/安全等非功能需求 |
-| CI Setup | 在持续集成管道中配置测试执行 |
+| CI Setup | 配置 CI 中的测试执行 |
-| Framework Scaffolding | 设置测试基础设施和项目结构 |
+| Framework Scaffolding | 搭建测试工程基础结构 |
-| Release Gate | 基于数据做出发布/不发布决策 |
+| Release Gate | 基于数据做发布/不发布决策 |
 
-TEA 还支持 P0-P3 基于风险的优先级排序，以及与 Playwright Utils 和 MCP 工具的可选集成。
+### 何时用 TEA
 
-### 何时使用 TEA
+- 需要合规、审计或强追溯能力
+- 需要跨功能做风险优先级管理
+- 发布前存在明确质量门控流程
+- 业务复杂，必须先建策略再写测试
 
-- 需要需求可追溯性或合规文档的项目
+## 测试放在流程的哪个位置
-- 需要在多个功能间进行基于风险的测试优先级排序的团队
-- 发布前具有正式质量门控的企业环境
-- 在编写测试前必须规划测试策略的复杂领域
-- 已超出 Quinn 单一工作流方法的项目
 
-## 测试如何融入工作流
+按 BMad workflow-map，测试位于阶段 4（实施）：
 
-Quinn 的 Automate 工作流出现在 BMad 方法工作流图的第 4 阶段（实现）。典型序列：
+1. epic 内逐个 story：开发（`DS` / `bmad-dev-story`）+ 代码审查（`CR` / `bmad-code-review`）
+2. epic 完成后：用 Quinn 或 TEA 的 Automate 统一生成/补齐测试
+3. 最后执行复盘（`bmad-retrospective`）
 
-1. 使用开发工作流（`DS`）实现一个故事
+Quinn 主要依据代码直接生成测试；TEA 可结合上游规划产物（如 PRD、architecture）实现更强追溯。
-2. 使用 Quinn（`QA`）或 TEA 的 Automate 工作流生成测试
-3. 使用代码审查（`CR`）验证实现
 
-Quinn 直接从源代码工作，无需加载规划文档（PRD、架构）。TEA 工作流可以与上游规划产物集成以实现可追溯性。
+## 相关参考
 
-有关测试在整体流程中的位置，请参阅[工作流图](./workflow-map.md)。
+- [官方模块](./modules.md)
-
+- [工作流地图](./workflow-map.md)
----
+- [智能体参考](./agents.md)
-## 术语说明
-
-- **QA (Quality Assurance)**：质量保证。确保产品或服务满足质量要求的过程。
-- **E2E (End-to-End)**：端到端。测试整个系统从开始到结束的完整流程。
-- **ATDD (Acceptance Test-Driven Development)**：验收测试驱动开发。在编码前先编写验收测试的开发方法。
-- **NFR (Non-Functional Requirement)**：非功能性需求。描述系统如何运行而非做什么的需求，如性能、安全性等。
-- **P0-P3**：优先级级别。P0 为最高优先级，P3 为最低优先级，用于基于风险的测试排序。
-- **Happy path**：快乐路径。测试系统在理想条件下的正常工作流程。
-- **Semantic locators**：语义定位器。使用有意义的元素属性（如角色、标签、文本）而非 CSS 选择器来定位 UI 元素。
-- **Quality gates**：质量门控。在开发流程中设置的检查点，用于确保质量标准。
-- **Requirements traceability**：需求可追溯性。能够追踪需求从设计到测试再到实现的完整链路。
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **CI (Continuous Integration)**：持续集成。频繁地将代码集成到主干，并自动运行测试的实践。
-- **MCP (Model Context Protocol)**：模型上下文协议。用于在 AI 模型与外部工具之间通信的协议。

docs/zh-cn/roadmap.mdx

@@ -1,11 +1,11 @@
 ---
 title: 路线图
-description: BMad 的下一步计划——功能、改进与社区贡献
+description: BMad 后续方向：功能演进、体验优化与社区生态
 ---
 
-# BMad 方法：公开路线图
+# BMad Method 公开路线图
 
-BMad 方法、BMad 方法模块（BMM）和 BMad 构建器（BMB）正在持续演进。以下是我们正在开展的工作以及即将推出的内容。
+BMad Method、BMM（Agile 套件）与 BMad Builder 正在持续迭代。以下内容用于说明当前重点与下一阶段规划。
 
 <div class="roadmap-container">
 
@@ -14,139 +14,123 @@ BMad 方法、BMad 方法模块（BMM）和 BMad 构建器（BMB）正在持续
   <div class="roadmap-future">
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🧩</span>
-      <h4>通用技能架构</h4>
+      <h4>通用 Skills 架构</h4>
-      <p>一个技能，任意平台。一次编写，随处运行。</p>
+      <p>同一 skill 在不同平台复用，降低跨工具维护成本。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🏗️</span>
-      <h4>BMad 构建器 v1</h4>
+      <h4>BMad Builder v1</h4>
-      <p>打造生产级 AI 智能体与工作流，内置评估、团队协作与优雅降级。</p>
+      <p>面向生产场景的 agent/workflow 构建能力，覆盖评估、协作与优雅降级。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🧠</span>
-      <h4>项目上下文系统</h4>
+      <h4>Project Context 系统</h4>
-      <p>AI 真正理解你的项目。框架感知的上下文，随代码库共同演进。</p>
+      <p>让 AI 在项目约束内工作：上下文随代码库变化持续更新。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">📦</span>
-      <h4>集中式技能</h4>
+      <h4>集中式 Skills</h4>
-      <p>一次安装，随处使用。跨项目共享技能，告别文件杂乱。</p>
+      <p>减少项目内重复拷贝，支持跨项目共享与统一管理。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🔄</span>
-      <h4>自适应技能</h4>
+      <h4>自适应 Skills</h4>
-      <p>技能懂你的工具。为 Claude、Codex、Kimi、OpenCode 等提供优化变体，以及更多。</p>
+      <p>针对 Claude、Codex、Kimi、OpenCode 等平台提供优化变体。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">📝</span>
-      <h4>BMad 团队专业博客</h4>
+      <h4>BMad 团队博客</h4>
-      <p>来自团队的指南、文章与见解。即将上线。</p>
+      <p>持续发布实践文章、方法拆解与落地经验。</p>
     </div>
   </div>
 
-  <h2 class="roadmap-section-title">入门阶段</h2>
+  <h2 class="roadmap-section-title">近期规划</h2>
 
   <div class="roadmap-future">
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🏪</span>
-      <h4>技能市场</h4>
+      <h4>Skill 市场</h4>
-      <p>发现、安装与更新社区构建的技能。一条 curl 命令即可获得超能力。</p>
+      <p>发现、安装、更新社区技能，缩短能力接入路径。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🎨</span>
-      <h4>工作流定制</h4>
+      <h4>Workflow 定制</h4>
-      <p>打造属于你的工作流。集成 Jira、Linear、自定义输出——你的工作流，你的规则。</p>
+      <p>支持 Jira、Linear 与自定义产出对接，构建团队专属流程。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🚀</span>
       <h4>阶段 1-3 优化</h4>
-      <p>通过子智能体上下文收集实现闪电般快速的规划。YOLO 模式遇上引导式卓越。</p>
+      <p>通过子智能体上下文采集提升前期分析与规划效率。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🌐</span>
-      <h4>企业级就绪</h4>
+      <h4>企业级能力完善</h4>
-      <p>SSO、审计日志、团队工作空间。那些让企业点头同意的无聊但必要的东西。</p>
+      <p>补齐 SSO、审计日志、团队工作区等企业落地基础能力。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">💎</span>
-      <h4>社区模块爆发</h4>
+      <h4>社区模块扩展</h4>
-      <p>娱乐、安全、治疗、角色扮演以及更多内容。扩展 BMad 方法平台。</p>
+      <p>覆盖更多垂直场景，持续扩展 BMad 模块生态。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">⚡</span>
       <h4>开发循环自动化</h4>
-      <p>可选的开发自动驾驶。让 AI 处理流程，同时保持质量高企。</p>
+      <p>在可控质量边界内提升自动化程度，减少重复人工操作。</p>
     </div>
   </div>
 
-  <h2 class="roadmap-section-title">社区与团队</h2>
+  <h2 class="roadmap-section-title">社区与团队计划</h2>
 
   <div class="roadmap-future">
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🎙️</span>
-      <h4>BMad 方法播客</h4>
+      <h4>BMad Method 播客</h4>
-      <p>关于 AI 原生开发的对话。2026 年 3 月 1 日上线！</p>
+      <p>围绕 AI 原生研发方法开展持续讨论与案例分享。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🎓</span>
-      <h4>BMad 方法大师课</h4>
+      <h4>BMad Method 大师课</h4>
-      <p>从用户到专家。深入每个阶段、每个工作流、每个秘密。</p>
+      <p>面向进阶用户，系统拆解各阶段与核心 workflow。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🏗️</span>
-      <h4>BMad 构建器大师课</h4>
+      <h4>BMad Builder 大师课</h4>
-      <p>构建你自己的智能体。当你准备好创造而不仅仅是使用时的高级技巧。</p>
+      <p>聚焦自定义 agent/workflow 的高级设计与工程实践。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">⚡</span>
-      <h4>BMad 原型优先</h4>
+      <h4>BMad Prototype First</h4>
-      <p>一次会话从想法到可用原型。像创作艺术品一样打造你的梦想应用。</p>
+      <p>探索“单会话从想法到原型”的端到端实践路径。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🌴</span>
-      <h4>BMad BALM！</h4>
+      <h4>BMad BALM</h4>
-      <p>AI 原生的生活管理。任务、习惯、目标——你的 AI 副驾驶，无处不在。</p>
+      <p>将 AI 原生协作模式扩展到个人任务、习惯与目标管理。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🖥️</span>
       <h4>官方 UI</h4>
-      <p>整个 BMad 生态系统的精美界面。CLI 的强大，GUI 的精致。</p>
+      <p>在保留 CLI 能力的基础上提供完整图形化操作体验。</p>
     </div>
     <div class="roadmap-future-card">
       <span class="roadmap-emoji">🔒</span>
-      <h4>BMad 一体机</h4>
+      <h4>BMad in a Box</h4>
-      <p>自托管、气隙隔离、企业级。你的 AI 助手、你的基础设施、你的控制。</p>
+      <p>面向自托管与气隙隔离场景的企业级部署方案。</p>
     </div>
   </div>
 
   <div style="text-align: center; margin-top: 3rem; padding: 2rem; background: var(--color-bg-card); border-radius: 12px; border: 1px solid var(--color-border);">
-    <h3 style="margin: 0 0 1rem;">想要贡献？</h3>
+    <h3 style="margin: 0 0 1rem;">欢迎参与贡献</h3>
     <p style="color: var(--slate-color-400); margin: 0;">
-      这只是计划内容的一部分。BMad 开源团队欢迎贡献者！{" "}<br />
+      以上并非全部规划。BMad 开源团队欢迎贡献者加入。{" "}<br />
-      <a href="https://github.com/bmad-code-org/BMAD-METHOD" style="color: var(--color-in-progress);">在 GitHub 上加入我们</a>，共同塑造 AI 驱动开发的未来。
+      前往 <a href="https://github.com/bmad-code-org/BMAD-METHOD" style="color: var(--color-in-progress);">GitHub 仓库</a> 参与共建。
     </p>
     <p style="color: var(--slate-color-400); margin: 1.5rem 0 0;">
-      喜欢我们正在构建的东西？我们感谢一次性与月度{" "}<a href="https://buymeacoffee.com/bmad" style="color: var(--color-in-progress);">支持</a>。
+      如果你认可项目方向，也欢迎通过{" "}<a href="https://buymeacoffee.com/bmad" style="color: var(--color-in-progress);">支持渠道</a> 帮助我们持续迭代。
     </p>
     <p style="color: var(--slate-color-400); margin: 1rem 0 0;">
-      如需企业赞助、合作咨询、演讲邀请、培训或媒体咨询：{" "}
+      企业赞助、合作咨询、培训与媒体联系：{" "}
       <a href="mailto:contact@bmadcode.com" style="color: var(--color-in-progress);">contact@bmadcode.com</a>
     </p>
   </div>
 </div>
-
----
-## 术语说明
-
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **SSO**：单点登录。一种用户认证机制，允许用户使用一组凭据访问多个应用程序。
-- **air-gapped**：气隙隔离。指系统与外部网络完全物理隔离的安全措施。
-- **YOLO**：You Only Live Once 的缩写，此处指快速、大胆的执行模式。
-- **evals**：评估。对 AI 模型或智能体性能的测试与评价。
-- **graceful degradation**：优雅降级。系统在部分功能失效时仍能保持基本功能的特性。
-- **sub-agent**：子智能体。在主智能体协调下执行特定任务的辅助智能体。
-- **context**：上下文。AI 理解任务所需的相关信息与环境背景。
-- **workflow**：工作流。一系列有序的任务或操作流程。
-- **skills**：技能。AI 智能体可执行的具体能力或功能模块。
-- **CLI**：命令行界面。通过文本命令与计算机交互的方式。
-- **GUI**：图形用户界面。通过图形元素与计算机交互的方式。

test/test-installation-components.js

@@ -14,6 +14,7 @@
 const path = require('node:path');
 const os = require('node:os');
 const fs = require('fs-extra');
+const { ConfigCollector } = require('../tools/cli/installers/lib/core/config-collector');
 const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator');
 const { IdeManager } = require('../tools/cli/installers/lib/ide/manager');
 const { clearCache, loadPlatformCodes } = require('../tools/cli/installers/lib/ide/platform-codes');
@@ -1853,6 +1854,93 @@ async function runTests() {
 
   console.log('');
 
+  // ============================================================
+  // Test Suite 33: ConfigCollector Prompt Normalization
+  // ============================================================
+  console.log(`${colors.yellow}Test Suite 33: ConfigCollector Prompt Normalization${colors.reset}\n`);
+
+  try {
+    const teaModuleConfig33 = {
+      test_artifacts: {
+        default: '_bmad-output/test-artifacts',
+      },
+      test_design_output: {
+        prompt: 'Where should test design documents be stored?',
+        default: 'test-design',
+        result: '{test_artifacts}/{value}',
+      },
+      test_review_output: {
+        prompt: 'Where should test review reports be stored?',
+        default: 'test-reviews',
+        result: '{test_artifacts}/{value}',
+      },
+      trace_output: {
+        prompt: 'Where should traceability reports be stored?',
+        default: 'traceability',
+        result: '{test_artifacts}/{value}',
+      },
+    };
+
+    const collector33 = new ConfigCollector();
+    collector33.currentProjectDir = path.join(os.tmpdir(), 'bmad-config-normalization');
+    collector33.allAnswers = {};
+    collector33.collectedConfig = {
+      tea: {
+        test_artifacts: '_bmad-output/test-artifacts',
+      },
+    };
+    collector33.existingConfig = {
+      tea: {
+        test_artifacts: '_bmad-output/test-artifacts',
+        test_design_output: '_bmad-output/test-artifacts/test-design',
+        test_review_output: '_bmad-output/test-artifacts/test-reviews',
+        trace_output: '_bmad-output/test-artifacts/traceability',
+      },
+    };
+
+    const testDesignQuestion33 = await collector33.buildQuestion(
+      'tea',
+      'test_design_output',
+      teaModuleConfig33.test_design_output,
+      teaModuleConfig33,
+    );
+    const testReviewQuestion33 = await collector33.buildQuestion(
+      'tea',
+      'test_review_output',
+      teaModuleConfig33.test_review_output,
+      teaModuleConfig33,
+    );
+    const traceQuestion33 = await collector33.buildQuestion('tea', 'trace_output', teaModuleConfig33.trace_output, teaModuleConfig33);
+
+    assert(testDesignQuestion33.default === 'test-design', 'ConfigCollector normalizes existing test_design_output prompt default');
+    assert(testReviewQuestion33.default === 'test-reviews', 'ConfigCollector normalizes existing test_review_output prompt default');
+    assert(traceQuestion33.default === 'traceability', 'ConfigCollector normalizes existing trace_output prompt default');
+
+    collector33.allAnswers = {
+      tea_test_artifacts: '_bmad-output/test-artifacts',
+    };
+
+    assert(
+      collector33.processResultTemplate(teaModuleConfig33.test_design_output.result, testDesignQuestion33.default) ===
+        '_bmad-output/test-artifacts/test-design',
+      'ConfigCollector re-applies test_design_output template without duplicating prefix',
+    );
+    assert(
+      collector33.processResultTemplate(teaModuleConfig33.test_review_output.result, testReviewQuestion33.default) ===
+        '_bmad-output/test-artifacts/test-reviews',
+      'ConfigCollector re-applies test_review_output template without duplicating prefix',
+    );
+    assert(
+      collector33.processResultTemplate(teaModuleConfig33.trace_output.result, traceQuestion33.default) ===
+        '_bmad-output/test-artifacts/traceability',
+      'ConfigCollector re-applies trace_output template without duplicating prefix',
+    );
+  } catch (error) {
+    assert(false, 'ConfigCollector prompt normalization test succeeds', error.message);
+  }
+
+  console.log('');
+
   // ============================================================
   // Summary
   // ============================================================

tools/bmad-npx-wrapper.js

@@ -5,7 +5,7 @@
  * This file ensures proper execution when run via npx from GitHub or npm registry
  */
 
-const { execSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
 const path = require('node:path');
 const fs = require('node:fs');
 
@@ -25,7 +25,7 @@ if (isNpxExecution) {
 
   try {
     // Execute CLI from user's working directory (process.cwd()), not npm cache
-    execSync(`node "${bmadCliPath}" ${args.join(' ')}`, {
+    execFileSync('node', [bmadCliPath, ...args], {
       stdio: 'inherit',
       cwd: process.cwd(), // This preserves the user's working directory
     });

tools/cli/installers/lib/core/config-collector.js

@@ -954,8 +954,49 @@ class ConfigCollector {
         return match;
       }
 
+      const configValue = this.resolveConfigValue(configKey, currentModule, moduleConfig);
+
+      return configValue || match;
+    });
+  }
+
+  /**
+   * Clean a stored path-like value for prompt display/input reuse.
+   * @param {*} value - Stored value
+   * @returns {*} Cleaned value
+   */
+  cleanPromptValue(value) {
+    if (typeof value === 'string' && value.startsWith('{project-root}/')) {
+      return value.replace('{project-root}/', '');
+    }
+
+    return value;
+  }
+
+  /**
+   * Resolve a config key from answers, collected config, existing config, or schema defaults.
+   * @param {string} configKey - Config key to resolve
+   * @param {string} currentModule - Current module name
+   * @param {Object} moduleConfig - Current module config schema
+   * @returns {*} Resolved value
+   */
+  resolveConfigValue(configKey, currentModule = null, moduleConfig = null) {
     // Look for the config value in allAnswers (already answered questions)
-      let configValue = this.allAnswers[configKey] || this.allAnswers[`core_${configKey}`];
+    let configValue = this.allAnswers?.[configKey] || this.allAnswers?.[`core_${configKey}`];
+
+    if (!configValue && this.allAnswers) {
+      for (const [answerKey, answerValue] of Object.entries(this.allAnswers)) {
+        if (answerKey.endsWith(`_${configKey}`)) {
+          configValue = answerValue;
+          break;
+        }
+      }
+    }
+
+    // Prefer the current module's persisted value when re-prompting an existing install
+    if (!configValue && currentModule && this.existingConfig?.[currentModule]?.[configKey] !== undefined) {
+      configValue = this.existingConfig[currentModule][configKey];
+    }
 
     // Check in already collected config
     if (!configValue) {
@@ -967,6 +1008,16 @@ class ConfigCollector {
       }
     }
 
+    // Fall back to other existing module config values
+    if (!configValue && this.existingConfig) {
+      for (const mod of Object.keys(this.existingConfig)) {
+        if (mod !== '_meta' && this.existingConfig[mod] && this.existingConfig[mod][configKey]) {
+          configValue = this.existingConfig[mod][configKey];
+          break;
+        }
+      }
+    }
+
     // If still not found and we're in the same module, use the default from the config schema
     if (!configValue && currentModule && moduleConfig && moduleConfig[configKey]) {
       const referencedItem = moduleConfig[configKey];
@@ -975,8 +1026,49 @@ class ConfigCollector {
       }
     }
 
-      return configValue || match;
+    return this.cleanPromptValue(configValue);
-    });
+  }
+
+  /**
+   * Convert an existing stored value back into the prompt-facing value for templated fields.
+   * For example, "{test_artifacts}/{value}" + "_bmad-output/test-artifacts/test-design"
+   * becomes "test-design" so the template is not applied twice on modify.
+   * @param {*} existingValue - Stored config value
+   * @param {string} moduleName - Module name
+   * @param {Object} item - Config item definition
+   * @param {Object} moduleConfig - Current module config schema
+   * @returns {*} Prompt-facing default value
+   */
+  normalizeExistingValueForPrompt(existingValue, moduleName, item, moduleConfig = null) {
+    const cleanedValue = this.cleanPromptValue(existingValue);
+
+    if (typeof cleanedValue !== 'string' || typeof item?.result !== 'string' || !item.result.includes('{value}')) {
+      return cleanedValue;
+    }
+
+    const [prefixTemplate = '', suffixTemplate = ''] = item.result.split('{value}');
+    const prefix = this.cleanPromptValue(this.replacePlaceholders(prefixTemplate, moduleName, moduleConfig));
+    const suffix = this.cleanPromptValue(this.replacePlaceholders(suffixTemplate, moduleName, moduleConfig));
+
+    if ((prefix && !cleanedValue.startsWith(prefix)) || (suffix && !cleanedValue.endsWith(suffix))) {
+      return cleanedValue;
+    }
+
+    const startIndex = prefix.length;
+    const endIndex = suffix ? cleanedValue.length - suffix.length : cleanedValue.length;
+    if (endIndex < startIndex) {
+      return cleanedValue;
+    }
+
+    let promptValue = cleanedValue.slice(startIndex, endIndex);
+    if (promptValue.startsWith('/')) {
+      promptValue = promptValue.slice(1);
+    }
+    if (promptValue.endsWith('/')) {
+      promptValue = promptValue.slice(0, -1);
+    }
+
+    return promptValue || cleanedValue;
   }
 
   /**
@@ -993,12 +1085,7 @@ class ConfigCollector {
     let existingValue = null;
     if (this.existingConfig && this.existingConfig[moduleName]) {
       existingValue = this.existingConfig[moduleName][key];
-
+      existingValue = this.normalizeExistingValueForPrompt(existingValue, moduleName, item, moduleConfig);
-      // Clean up existing value - remove {project-root}/ prefix if present
-      // This prevents duplication when the result template adds it back
-      if (typeof existingValue === 'string' && existingValue.startsWith('{project-root}/')) {
-        existingValue = existingValue.replace('{project-root}/', '');
-      }
     }
 
     // Special handling for user_name: default to system user