docs(zh-cn-explanation): normalize admonition syntax

我将 3 篇中文 explanation 文档中的提示块语法统一为仓库约定的 `:::...:::` 形式。此前使用 `::::...::::` 会导致与现有文档规范不一致；现在统一后可减少渲染歧义与后续维护成本。 Feishu: <https://www.feishu.cn/> Made-with: Cursor
docs(zh-cn-explanation): refine epic3 stories 3.1-3.2
2026-03-23 20:00:06 -06:00 · 2026-03-23 20:00:06 -06:00 · 2026-03-23 19:20:03 -06:00 · 2026-03-23 18:28:32 -06:00 · 2026-03-23 15:55:19 -05:00 · 2026-03-23 01:51:53 -06:00
33 changed files with 670 additions and 595 deletions
--- a/README_CN.md
+++ b/README_CN.md
@ -5,20 +5,20 @@
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)

-**突破性敏捷 AI 驱动开发方法** — 简称 “BMAD 方法论” ，BMAD方法论是由多个模块生态构成的AI驱动敏捷开发模块系统，这是最佳且最全面的敏捷 AI 驱动开发框架，具备真正的规模自适应人工智能，可适应快速开发，适应企业规模化开发。
+**筑梦架构（Build More Architect Dreams）** —— 简称 “BMAD 方法”，面向 BMad 模块生态的 AI 驱动敏捷开发方法。它会随项目复杂度调整工作深度，从日常 bug 修复到企业级系统建设都能适配。

-**100% 免费且开源。** 无付费。无内容门槛。无封闭 Discord。我们赋能每个人，我们将为全球现在在人工智能领域发展的普通人提供公平的学习机会。
+**100% 免费且开源。** 没有付费墙，没有封闭内容，也没有封闭 Discord。我们希望每个人都能平等获得高质量的人机协作开发方法。

 ## 为什么选择 BMad 方法？

-传统 AI 工具替你思考，产生平庸的结果。BMad 智能体和辅助工作流充当专家协作者，引导你通过结构化流程，与 AI 的合作发挥最佳思维，产出最有效优秀的结果。
+传统 AI 工具常常替你思考，结果往往止于“能用”。BMad 通过专业智能体和引导式工作流，让 AI 成为协作者：流程有结构，决策有依据，产出更稳定。

- **AI 智能帮助** — 随时使用 `bmad-help` 获取下一步指导
- **规模-领域自适应** — 根据项目复杂度自动调整规划深度
- **结构化工作流** — 基于分析、规划、架构和实施的敏捷最佳实践
- **专业智能体** — 12+ 领域专家（PM、架构师、开发者、UX、Scrum Master 等）
- **派对模式** — 将多个智能体角色带入一个会话进行协作和讨论
- **完整生命周期** — 从想法开始（头脑风暴）到部署发布
+- **AI 智能引导** —— 随时调用 `bmad-help` 获取下一步建议
+- **规模与领域自适应** —— 按项目复杂度自动调整规划深度
+- **结构化工作流** —— 覆盖分析、规划、架构、实施全流程
+- **专业角色智能体** —— 提供 PM、架构师、开发者、UX、Scrum Master 等 12+ 角色
+- **派对模式** —— 多个智能体可在同一会话协作讨论
+- **完整生命周期** —— 从头脑风暴一路到交付上线

 [在 **docs.bmad-method.org** 了解更多](https://docs.bmad-method.org/zh-cn/)

@ -26,7 +26,7 @@

 ## 🚀 BMad 的下一步是什么？

-**V6 已到来，我们才刚刚开始！** BMad 方法正在快速发展，包括跨平台智能体团队和子智能体集成、技能架构、BMad Builder v1、开发循环自动化等优化，以及更多正在开发中的功能。
+**V6 已经上线，而这只是开始。** BMad 仍在快速演进：跨平台智能体团队与子智能体集成、Skills 架构、BMad Builder v1、Dev Loop 自动化等能力都在持续推进。

 **[📍 查看完整路线图 →](https://docs.bmad-method.org/zh-cn/roadmap/)**

@ -40,7 +40,7 @@
 npx bmad-method install
 ```

-> 想要最新的预发布版本？使用 `npx bmad-method@next install`。相比默认安装，可能会有更多变更。
+> 想体验最新预发布版本？可使用 `npx bmad-method@next install`。它比默认版本更新更快，也可能更容易发生变化。

 按照安装程序提示操作，然后在项目文件夹中打开你的 AI IDE（Claude Code、Cursor 等）。

@ -52,19 +52,19 @@ npx bmad-method install --directory /path/to/project --modules bmm --tools claud

 [查看非交互式安装选项](https://docs.bmad-method.org/zh-cn/how-to/non-interactive-installation/)

-> **不确定该做什么？** 运行 `bmad-help` — 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。
+> **不确定下一步？** 直接问 `bmad-help`。它会告诉你“必做什么、可选什么”，例如：`bmad-help 我刚完成架构设计，接下来做什么？`

 ## 模块

-BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后的任何时间使用。
+BMad 可通过官方模块扩展到不同专业场景。你可以在安装时选择，也可以后续随时补装。

-| Module                                                                                                            | Purpose                                           |
-| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)**                                             | 包含 34+ 工作流的核心框架                         |
-| **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)**                                           | 创建自定义 BMad 智能体和工作流                     |
-| **[Test Architect (TEA)](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)**             | 基于风险的测试策略和自动化                         |
-| **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)**                        | 游戏开发工作流（Unity、Unreal、Godot）             |
-| **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 创新、头脑风暴、设计思维                           |
+| 模块                                                                                                                | 用途                           |
+| ----------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)**                                             | 核心框架，内含 34+ 工作流         |
+| **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)**                                           | 创建自定义 BMad 智能体与工作流     |
+| **[Test Architect (TEA)](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)**             | 基于风险的测试策略与自动化         |
+| **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)**                        | 游戏开发工作流（Unity/Unreal/Godot） |
+| **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 创新、头脑风暴、设计思维           |

 ## 文档

@ -72,10 +72,9 @@ BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后

 **快速链接：**
 - [入门教程](https://docs.bmad-method.org/zh-cn/tutorials/getting-started/)
- [从先前版本升级](https://docs.bmad-method.org/zh-cn/how-to/upgrade-to-v6/)
+- [从旧版本升级](https://docs.bmad-method.org/zh-cn/how-to/upgrade-to-v6/)
 - [测试架构师文档（英文）](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)

-
 ## 社区

 - [Discord](https://discord.gg/gk8jAdXWmj) — 获取帮助、分享想法、协作
@ -85,9 +84,9 @@ BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后

 ## 支持 BMad

-BMad 对每个人都是免费的 — 并且永远如此。如果你想支持开发：
+BMad 对所有人免费，而且会一直免费。如果你愿意支持项目发展：

- ⭐ 请点击此页面右上角附近的项目星标图标
+- ⭐ 给仓库点个 Star
 - ☕ [请我喝咖啡](https://buymeacoffee.com/bmad) — 为开发提供动力
 - 🏢 企业赞助 — 在 Discord 上私信
 - 🎤 演讲与媒体 — 可参加会议、播客、采访（在 Discord 上联系 BM）
@ -107,15 +106,3 @@ MIT 许可证 — 详见 [LICENSE](LICENSE)。
 [![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)

 请参阅 [CONTRIBUTORS.md](CONTRIBUTORS.md) 了解贡献者信息。
-
---
-## 术语说明
-
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。
- **CI/CD**：持续集成/持续部署。一种自动化软件开发实践，用于频繁集成代码更改并自动部署。
- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。
- **PM**：产品经理。负责产品规划、需求管理和团队协调的角色。
- **UX**：用户体验。指用户在使用产品或服务过程中的整体感受和交互体验。
- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队遵循 Scrum 流程。
- **PRD**：产品需求文档。详细描述产品功能、需求和规格的文档。
--- a/docs/_STYLE_GUIDE.md
+++ b/docs/_STYLE_GUIDE.md
@ -56,7 +56,7 @@ Critical warnings only — data loss, security issues
 | Phase | Name     | What Happens                                 |
 | ----- | -------- | -------------------------------------------- |
 | 1     | Analysis | Brainstorm, research *(optional)*            |
-| 2     | Planning | Requirements — PRD or tech-spec *(required)* |
+| 2     | Planning | Requirements — PRD or spec *(required)* |
 ```

 **Skills:**
--- a/docs/explanation/established-projects-faq.md
+++ b/docs/explanation/established-projects-faq.md
@ -34,7 +34,7 @@ Yes! Quick Flow works great for established projects. It will:
 - Auto-detect your existing stack
 - Analyze existing code patterns
 - Detect conventions and ask for confirmation
- Generate context-rich tech-spec that respects existing code
+- Generate context-rich spec that respects existing code

 Perfect for bug fixes and small features in existing codebases.

@ -43,7 +43,7 @@ Perfect for bug fixes and small features in existing codebases.
 Quick Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide:

 - **Yes** → Maintain consistency with current codebase
- **No** → Establish new standards (document why in tech-spec)
+- **No** → Establish new standards (document why in spec)

 BMM respects your choice — it won't force modernization, but it will offer it.

--- a/docs/explanation/project-context.md
+++ b/docs/explanation/project-context.md
@ -25,7 +25,7 @@ Every implementation workflow automatically loads `project-context.md` if it exi
 - `bmad-create-story` — informs story creation with project patterns
 - `bmad-dev-story` — guides implementation decisions
 - `bmad-code-review` — validates against project standards
- `bmad-quick-dev` — applies patterns when implementing tech-specs
+- `bmad-quick-dev` — applies patterns when implementing specs
 - `bmad-sprint-planning`, `bmad-retrospective`, `bmad-correct-course` — provides project-wide context

 ## When to Create It
--- a/docs/fr/reference/workflow-map.md
+++ b/docs/fr/reference/workflow-map.md
@ -68,7 +68,7 @@ Sautez les phases 1-3 pour les travaux de faible envergure et bien compris.

 | Workflow         | Objectif                                                                            | Produit               |
 |------------------|-------------------------------------------------------------------------------------|-----------------------|
-| `bmad-quick-dev` | Flux rapide unifié — clarifie l'intention, planifie, implémente, révise et présente | `tech-spec.md` + code |
+| `bmad-quick-dev` | Flux rapide unifié — clarifie l'intention, planifie, implémente, révise et présente | `spec-*.md` + code |

 ## Gestion du Contexte

--- a/docs/fr/tutorials/getting-started.md
+++ b/docs/fr/tutorials/getting-started.md
@ -135,7 +135,7 @@ Créez-le manuellement dans `_bmad-output/project-context.md` ou générez-le ap

 Tous les workflows de cette phase sont optionnels :
 - **brainstorming** (`bmad-brainstorming`) — Idéation guidée
- **research** (`bmad-research`) — Recherche marché et technique
+- **research** (`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`) — Recherche marché, domaine et technique
 - **create-product-brief** (`bmad-create-product-brief`) — Document de base recommandé

 ### Phase 2 : Planification (Requis)
@ -233,13 +233,13 @@ your-project/
 ## Questions fréquentes

 **Ai-je toujours besoin d'une architecture ?**
-Uniquement pour les voies méthode BMad et Enterprise. Quick Dev passe directement de la spécification technique (tech-spec) à l'implémentation.
+Uniquement pour les voies méthode BMad et Enterprise. Quick Dev passe directement de la spécification technique (spec) à l'implémentation.

 **Puis-je modifier mon plan plus tard ?**
 Oui. Utilisez `bmad-correct-course` pour gérer les changements de périmètre.

 **Et si je veux d'abord faire du brainstorming ?**
-Invoquez l'agent Analyst (`bmad-analyst`) et exécutez `bmad-brainstorming` (`bmad-brainstorming`) avant de commencer votre PRD.
+Invoquez l'agent Analyst (`bmad-agent-analyst`) et exécutez `bmad-brainstorming` (`bmad-brainstorming`) avant de commencer votre PRD.

 **Dois-je suivre un ordre strict ?**
 Pas strictement. Une fois que vous maîtrisez le flux, vous pouvez exécuter les workflows directement en utilisant la référence rapide ci-dessus.
--- a/docs/reference/workflow-map.md
+++ b/docs/reference/workflow-map.md
@ -68,7 +68,7 @@ Skip phases 1-3 for small, well-understood work.

 | Workflow           | Purpose                                                                     | Produces               |
 | ------------------ | --------------------------------------------------------------------------- | ---------------------- |
-| `bmad-quick-dev`   | Unified quick flow — clarify intent, plan, implement, review, and present   | `tech-spec.md` + code  |
+| `bmad-quick-dev`   | Unified quick flow — clarify intent, plan, implement, review, and present   | `spec-*.md` + code  |

 ## Context Management

--- a/docs/tutorials/getting-started.md
+++ b/docs/tutorials/getting-started.md
@ -69,7 +69,7 @@ BMad helps you build software through guided workflows with specialized AI agent
 | Phase | Name           | What Happens                                        |
 | ----- | -------------- | --------------------------------------------------- |
 | 1     | Analysis       | Brainstorming, research, product brief *(optional)* |
-| 2     | Planning       | Create requirements (PRD or tech-spec)              |
+| 2     | Planning       | Create requirements (PRD or spec)              |
 | 3     | Solutioning    | Design architecture *(BMad Method/Enterprise only)* |
 | 4     | Implementation | Build epic by epic, story by story                  |

@ -114,7 +114,7 @@ BMad-Help will detect what you've completed and recommend exactly what to do nex
 :::

 :::note[How to Load Agents and Run Workflows]
-Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-create-prd`). Your AI tool will recognize the `bmad-*` name and run it — you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-pm` for the PM agent).
+Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-create-prd`). Your AI tool will recognize the `bmad-*` name and run it — you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-agent-pm` for the PM agent).
 :::

 :::caution[Fresh Chats]
@ -135,13 +135,13 @@ Create it manually at `_bmad-output/project-context.md` or generate it after arc

 All workflows in this phase are optional:
 - **brainstorming** (`bmad-brainstorming`) — Guided ideation
- **research** (`bmad-research`) — Market and technical research
+- **research** (`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`) — Market, domain, and technical research
 - **create-product-brief** (`bmad-create-product-brief`) — Recommended foundation document

 ### Phase 2: Planning (Required)

 **For BMad Method and Enterprise tracks:**
-1. Invoke the **PM agent** (`bmad-pm`) in a new chat
+1. Invoke the **PM agent** (`bmad-agent-pm`) in a new chat
 2. Run the `bmad-create-prd` workflow (`bmad-create-prd`)
 3. Output: `PRD.md`

@ -149,13 +149,13 @@ All workflows in this phase are optional:
 - Run `bmad-quick-dev` — it handles planning and implementation in a single workflow, skip to implementation

 :::note[UX Design (Optional)]
-If your project has a user interface, invoke the **UX-Designer agent** (`bmad-ux-designer`) and run the UX design workflow (`bmad-create-ux-design`) after creating your PRD.
+If your project has a user interface, invoke the **UX-Designer agent** (`bmad-agent-ux-designer`) and run the UX design workflow (`bmad-create-ux-design`) after creating your PRD.
 :::

 ### Phase 3: Solutioning (BMad Method/Enterprise)

 **Create Architecture**
-1. Invoke the **Architect agent** (`bmad-architect`) in a new chat
+1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat
 2. Run `bmad-create-architecture` (`bmad-create-architecture`)
 3. Output: Architecture document with technical decisions

@ -165,12 +165,12 @@ If your project has a user interface, invoke the **UX-Designer agent** (`bmad-ux
 Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
 :::

-1. Invoke the **PM agent** (`bmad-pm`) in a new chat
+1. Invoke the **PM agent** (`bmad-agent-pm`) in a new chat
 2. Run `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`)
 3. The workflow uses both PRD and Architecture to create technically-informed stories

 **Implementation Readiness Check** *(Highly Recommended)*
-1. Invoke the **Architect agent** (`bmad-architect`) in a new chat
+1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat
 2. Run `bmad-check-implementation-readiness` (`bmad-check-implementation-readiness`)
 3. Validates cohesion across all planning documents

@ -180,7 +180,7 @@ Once planning is complete, move to implementation. **Each workflow should run in

 ### Initialize Sprint Planning

-Invoke the **SM agent** (`bmad-sm`) and run `bmad-sprint-planning` (`bmad-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
+Invoke the **SM agent** (`bmad-agent-sm`) and run `bmad-sprint-planning` (`bmad-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.

 ### The Build Cycle

@ -192,7 +192,7 @@ For each story, repeat this cycle with fresh chats:
 | 2    | DEV   | `bmad-dev-story`    | `bmad-dev-story`     | Implement the story                |
 | 3    | DEV   | `bmad-code-review`  | `bmad-code-review`   | Quality validation *(recommended)* |

-After completing all stories in an epic, invoke the **SM agent** (`bmad-sm`) and run `bmad-retrospective` (`bmad-retrospective`).
+After completing all stories in an epic, invoke the **SM agent** (`bmad-agent-sm`) and run `bmad-retrospective` (`bmad-retrospective`).

 ## What You've Accomplished

@ -237,13 +237,13 @@ your-project/
 ## Common Questions

 **Do I always need architecture?**
-Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
+Only for BMad Method and Enterprise tracks. Quick Flow skips from spec to implementation.

 **Can I change my plan later?**
 Yes. The SM agent has a `bmad-correct-course` workflow (`bmad-correct-course`) for handling scope changes.

 **What if I want to brainstorm first?**
-Invoke the Analyst agent (`bmad-analyst`) and run `bmad-brainstorming` (`bmad-brainstorming`) before starting your PRD.
+Invoke the Analyst agent (`bmad-agent-analyst`) and run `bmad-brainstorming` (`bmad-brainstorming`) before starting your PRD.

 **Do I need to follow a strict order?**
 Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above.
--- a/docs/zh-cn/404.md
+++ b/docs/zh-cn/404.md
@ -4,6 +4,6 @@ template: splash
 ---


-您查找的页面不存在或已被移动。
+你访问的页面不存在，或已被移动。

-[返回首页](./index.md)
+[返回中文首页](./index.md)
--- a/docs/zh-cn/_STYLE_GUIDE.md
+++ b/docs/zh-cn/_STYLE_GUIDE.md
@ -56,7 +56,7 @@ Critical warnings only — data loss, security issues
 | Phase | Name     | What Happens                                 |
 | ----- | -------- | -------------------------------------------- |
 | 1     | Analysis | Brainstorm, research *(optional)*            |
-| 2     | Planning | Requirements — PRD or tech-spec *(required)* |
+| 2     | Planning | Requirements — PRD or spec *(required)* |
 ```

 **Commands:**
--- a/docs/zh-cn/how-to/customize-bmad.md
+++ b/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`   | 替换     | 覆盖智能体的显示名称                           |
-| `persona`          | 替换     | 设置角色、身份、风格和原则                     |
-| `memories`         | 追加     | 添加智能体始终会记住的持久上下文               |
-| `menu`             | 追加     | 为工作流或提示添加自定义菜单项                 |
-| `critical_actions` | 追加     | 定义智能体的启动指令                           |
-| `prompts`          | 追加     | 创建可重复使用的提示供菜单操作使用             |
+| `agent.metadata` | 覆盖 | 覆盖智能体显示名称 |
+| `persona` | 覆盖 | 设置角色、身份、风格和原则 |
+| `memories` | 追加 | 添加智能体长期记忆的上下文 |
+| `menu` | 追加 | 增加指向工作流或提示的菜单项 |
+| `critical_actions` | 追加 | 定义智能体启动时要执行的动作 |
+| `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**             | 将所有模块更新到最新版本并应用自定义配置                     |
-| **Modify BMad Installation** | 用于添加或删除模块的完整安装流程                             |
+| **Quick Update** | 更新所有模块到最新版本，并应用你的自定义配置 |
+| **Modify BMad Installation** | 进入完整安装流程，用于增删模块 |

-对于仅自定义配置的更改，**Quick Update** 是最快的选项。
+如果只是调整 `.customize.yaml`，优先选 **Quick Update**。

-## 故障排除
+## 故障排查

-**更改未生效？**
+**改动没有生效？**

 - 运行 `npx bmad-method install` 并选择 **Quick Update** 以应用更改
- 检查您的 YAML 语法是否有效（缩进很重要）
- 验证您编辑的是该智能体正确的 `.customize.yaml` 文件
+- 检查 YAML 语法是否正确（尤其是缩进）
+- 确认你编辑的是目标智能体对应的 `.customize.yaml`

 **智能体无法加载？**

 - 使用在线 YAML 验证器检查 YAML 语法错误
- 确保在取消注释后没有留下空字段
- 尝试恢复到原始模板并重新构建
+- 确保取消注释后没有遗留空字段
+- 可先回退到模板，再逐项恢复自定义配置

-**需要重置智能体？**
+**需要重置某个智能体？**

 - 清空或删除智能体的 `.customize.yaml` 文件
 - 运行 `npx bmad-method install` 并选择 **Quick Update** 以恢复默认设置

 ## 工作流自定义

-对现有 BMad Method 工作流和技能的自定义即将推出。
+对现有 BMad Method 工作流和技能的深度自定义能力即将推出。

 ## 模块自定义

 关于构建扩展模块和自定义现有模块的指南即将推出。

---
-## 术语说明
+## 后续步骤

- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。
- **persona**：角色。指智能体的身份、个性、沟通风格和行为原则的集合。
- **memory**：记忆。指智能体持久存储的上下文信息，用于在对话中保持连贯性。
- **critical action**：关键操作。指智能体启动时必须执行的指令或任务。
- **prompt**：提示。指发送给智能体的输入文本，用于引导其生成特定响应或执行特定操作。
+- [文档分片指南](./shard-large-documents.md) - 了解如何管理超长文档
+- [命令参考](../reference/commands.md) - 查看可用命令和工作流入口
--- a/docs/zh-cn/how-to/established-projects.md
+++ b/docs/zh-cn/how-to/established-projects.md
@ -5,9 +5,9 @@ sidebar:
  order: 6
 ---

-在现有项目和遗留代码库上工作时，有效使用 BMad Method。
+当你在现有项目或遗留代码库上工作时，本指南帮助你更稳妥地使用 BMad Method。

-本指南涵盖了使用 BMad Method 接入现有项目的核心工作流程。
+如果你是从零开始的新项目，建议先看[快速入门](../tutorials/getting-started.md)；本文主要面向既有项目接入场景。

 :::note[前置条件]
 - 已安装 BMad Method（`npx bmad-method install`）
@ -23,16 +23,16 @@ sidebar:
 - `_bmad-output/planning-artifacts/`
 - `_bmad-output/implementation-artifacts/`

-## 步骤 2：创建项目上下文
+## 步骤 2：创建项目上下文（project context）

 :::tip[推荐用于既有项目]
-生成 `project-context.md` 以捕获你现有代码库的模式和约定。这确保 AI 智能体在实施变更时遵循你既定的实践。
+生成 `project-context.md`，梳理现有代码库的模式与约定，确保 AI 智能体在实施变更时遵循你既有的工程实践。
 :::

-运行生成项目上下文工作流程：
+运行生成项目上下文工作流：

 ```bash
-/bmad-bmm-generate-project-context
+bmad-generate-project-context
 ```

 这将扫描你的代码库以识别：
@ -40,9 +40,10 @@ sidebar:
 - 代码组织模式
 - 命名约定
 - 测试方法
- 框架特定模式
+- 框架相关模式

-你可以查看和完善生成的文件，或者如果你更喜欢，可以在 `_bmad-output/project-context.md` 手动创建它。
+你可以先审阅并完善生成内容；如果更希望手动维护，也可以直接在
+`_bmad-output/project-context.md` 创建并编辑。

 [了解更多关于项目上下文](../explanation/project-context.md)

@ -55,80 +56,63 @@ sidebar:
 - 架构
 - 任何其他相关的项目信息

-对于复杂项目，考虑使用 `document-project` 工作流程。它提供运行时变体，将扫描你的整个项目并记录其实际当前状态。
+对于复杂项目，可考虑使用 `bmad-document-project` 工作流。它会扫描整个项目并记录当前真实状态。

-## 步骤 3：获取帮助
+## 步骤 4：获取帮助

-### BMad-Help：你的起点
+### BMad-Help：默认起点

-**随时运行 `bmad-help`，当你不确定下一步该做什么时。** 这个智能指南：
+**当你不确定下一步做什么时，随时运行 `bmad-help`。** 这个智能指南会：

- 检查你的项目以查看已经完成了什么
- 根据你安装的模块显示选项
+- 检查项目当前状态，识别哪些工作已经完成
+- 根据你安装的模块给出可行选项
 - 理解自然语言查询

 ```
 bmad-help 我有一个现有的 Rails 应用，我应该从哪里开始？
-bmad-help quick-flow 和完整方法有什么区别？
-bmad-help 显示我有哪些可用的工作流程
+bmad-help Quick Flow 和完整方法有什么区别？
+bmad-help 显示我当前有哪些可用工作流
 ```

-BMad-Help 还会在**每个工作流程结束时自动运行**，提供关于下一步该做什么的清晰指导。
+BMad-Help 还会在**每个工作流结束时自动运行**，明确告诉你下一步该做什么。

 ### 选择你的方法

 根据变更范围，你有两个主要选项：

-| 范围                          | 推荐方法                                                                                                          |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| **小型更新或添加** | 运行 `bmad-quick-dev` 在单个工作流中澄清意图、规划、实现和审查。完整的四阶段 BMad Method 可能有些过度。 |
-| **重大变更或添加** | 从 BMad Method 开始，根据需要应用或多或少的严谨性。                                                    |
+| 范围 | 推荐方法 |
+| --- | --- |
+| **小型更新或新增** | 运行 `bmad-quick-dev`，在单个工作流中完成意图澄清、规划、实现与审查。完整四阶段 BMad Method 往往过重。 |
+| **重大变更或新增** | 从完整 BMad Method 开始，再按项目风险和协作需求调整流程严谨度。 |

 ### 在创建 PRD 期间

 在创建简报或直接进入 PRD 时，确保智能体：

 - 查找并分析你现有的项目文档
- 阅读关于你当前系统的适当上下文
+- 读取与你当前系统匹配的项目上下文（project context）

-你可以明确地指导智能体，但目标是确保新功能与你的现有系统良好集成。
+你可以显式补充指令，但核心目标是让新功能与现有 architecture 和代码约束自然融合。

 ### UX 考量

-UX 工作是可选的。决定不取决于你的项目是否有 UX，而取决于：
+UX 工作是可选项。是否需要进入 UX 流程，不取决于“项目里有没有 UX”，而取决于：

- 你是否将处理 UX 变更
- 是否需要重要的新 UX 设计或模式
+- 你是否真的在做 UX 层面的变更
+- 是否需要新增重要的 UX 设计或交互模式

-如果你的变更只是对你满意的现有屏幕进行简单更新，则不需要完整的 UX 流程。
+如果本次只是对现有页面做小幅调整，通常不需要完整 UX 流程。

-### 架构考量
+### 架构考量（architecture）

 在进行架构工作时，确保架构师：

- 使用适当的已记录文件
- 扫描现有代码库
+- 使用正确且最新的文档输入
+- 扫描并理解现有代码库

-在此处要密切注意，以防止重新发明轮子或做出与你现有架构不一致的决定。
+这一点非常关键：可避免“重复造轮子”，也能减少与现有架构冲突的设计决策。

 ## 更多信息

 - **[快速修复](./quick-fixes.md)** - 错误修复和临时变更
 - **[既有项目 FAQ](../explanation/established-projects-faq.md)** - 关于在既有项目上工作的常见问题
-
---
-## 术语说明
-
- **BMad Method**：BMad 方法。一种结构化的软件开发方法论，用于指导从分析到实施的完整流程。
- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。
- **epic**：史诗。大型功能或用户故事的集合，通常需要较长时间完成。
- **story**：用户故事。描述用户需求的简短陈述，通常遵循"作为...我想要...以便于..."的格式。
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试、构建等功能的软件工具。
- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。
- **tech-spec**：技术规范（Technical Specification）。描述技术实现细节、架构设计和开发标准的文档。
- **quick-flow**：快速流程。BMad Method 中的一种简化工作流程，适用于小型变更或快速迭代。
- **legacy codebase**：遗留代码库。指历史遗留的、可能缺乏文档或使用过时技术的代码集合。
- **project context**：项目上下文。描述项目技术栈、约定、模式等背景信息的文档。
- **artifact**：产物。在开发过程中生成的文档、代码或其他输出物。
- **runtime variant**：运行时变体。在程序运行时可选择或切换的不同实现方式或配置。
--- a/docs/zh-cn/how-to/get-answers-about-bmad.md
+++ b/docs/zh-cn/how-to/get-answers-about-bmad.md
@ -5,108 +5,109 @@ sidebar:
  order: 4
 ---

-## 从这里开始：BMad-Help
+## 先从 BMad-Help 开始

-**获取关于 BMad 答案的最快方式是 `bmad-help`。** 这个智能指南可以回答超过 80% 的问题，并且直接在您的 IDE 中可用，方便您工作时使用。
+**获取 BMad 相关答案最快的方式是 `bmad-help` 技能。** 这个智能向导可以覆盖 80% 以上的常见问题，并且你在 IDE 里随时可用。

-BMad-Help 不仅仅是一个查询工具——它：
- **检查您的项目**以查看已完成的内容
- **理解自然语言**——用简单的英语提问
- **根据您安装的模块变化**——显示相关选项
- **在工作流后自动运行**——告诉您接下来该做什么
- **推荐第一个必需任务**——无需猜测从哪里开始
+BMad-Help 不只是查表工具，它还能：
+- **检查你的项目状态**，判断哪些步骤已经完成
+- **理解自然语言问题**，直接按日常表达提问即可
+- **根据已安装模块给出选项**，只展示与你当前场景相关的内容
+- **在工作流结束后自动运行**，明确告诉你下一步做什么
+- **指出第一个必做任务**，避免猜流程起点

 ### 如何使用 BMad-Help

-只需使用斜杠命令运行它：
+在 AI 会话里直接输入：

 ```
 bmad-help
 ```

-或者结合自然语言查询：
+:::tip
+按平台不同，你也可以使用 `/bmad-help` 或 `$bmad-help`。但大多数情况下直接输入 `bmad-help` 就能工作。
+:::
+
+也可以结合自然语言问题一起调用：

 ```
-bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？
-bmad-help 我在 UX 设计方面有哪些选择？
-bmad-help 我在 PRD 工作流上卡住了
-bmad-help 向我展示到目前为止已完成的内容
+bmad-help 我有一个 SaaS 想法并且已经知道主要功能，我该从哪里开始？
+bmad-help 我在 UX 设计方面有哪些选项？
+bmad-help 我卡在 PRD 工作流了
+bmad-help 帮我看看目前完成了什么
 ```

-BMad-Help 会回应：
- 针对您情况的建议
- 第一个必需任务是什么
- 流程的其余部分是什么样的
+BMad-Help 通常会返回：
+- 针对你当前情况的建议路径
+- 第一个必做任务
+- 后续整体流程概览

---
+## 何时使用这篇指南

-## 何时使用本指南
-
-在以下情况下使用本节：
- 您想了解 BMad 的架构或内部机制
- 您需要 BMad-Help 提供范围之外的答案
- 您在安装前研究 BMad
- 您想直接探索源代码
+当你遇到以下情况时，可用本指南补充：
+- 想理解 BMad 的架构设计或内部机制
+- 需要超出 BMad-Help 覆盖范围的答案
+- 在安装前做技术调研
+- 想直接基于源码进行追问

 ## 步骤

-### 1. 选择您的来源
+### 1. 选择信息来源

-| 来源               | 最适合用于                                  | 示例                     |
-| -------------------- | ----------------------------------------- | ---------------------------- |
-| **`_bmad` 文件夹**   | BMad 如何工作——智能体、工作流、提示词 | "PM 智能体做什么？" |
-| **完整的 GitHub 仓库** | 历史、安装程序、架构          | "v6 中有什么变化？"        |
-| **`llms-full.txt`**  | 来自文档的快速概述                  | "解释 BMad 的四个阶段" |
+| 来源 | 适合回答的问题 | 示例 |
+| --- | --- | --- |
+| **`_bmad` 文件夹** | 智能体、工作流、提示词如何工作 | “PM 智能体具体做什么？” |
+| **完整 GitHub 仓库** | 版本历史、安装器、整体架构 | “v6 主要改了什么？” |
+| **`llms-full.txt`** | 文档层面的快速全景理解 | “解释 BMad 的四个阶段” |

-`_bmad` 文件夹在您安装 BMad 时创建。如果您还没有它，请改为克隆仓库。
+安装 BMad 后会生成 `_bmad` 文件夹；如果你还没有安装，可先克隆仓库。

-### 2. 将您的 AI 指向来源
+### 2. 让 AI 读取来源

-**如果您的 AI 可以读取文件（Claude Code、Cursor 等）：**
+**如果你的 AI 可以直接读文件（如 Claude Code、Cursor）：**

- **已安装 BMad：** 指向 `_bmad` 文件夹并直接提问
- **想要更深入的上下文：** 克隆[完整仓库](https://github.com/bmad-code-org/BMAD-METHOD)
+- **已安装 BMad：** 直接让它读取 `_bmad` 并提问
+- **想看更深上下文：** 克隆[完整仓库](https://github.com/bmad-code-org/BMAD-METHOD)

-**如果您使用 ChatGPT 或 Claude.ai：**
+**如果你使用 ChatGPT 或 Claude.ai：**

-将 `llms-full.txt` 获取到您的会话中：
+把 `llms-full.txt` 加入会话上下文：

 ```text
 https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
 ```


-### 3. 提出您的问题
+### 3. 直接提问

 :::note[示例]
-**问：** "告诉我用 BMad 构建某物的最快方式"
+**问：** “用 BMad 做一个需求到实现的最短路径是什么？”

-**答：** 使用快速流程：运行 `bmad-quick-dev` — 它在单个工作流中澄清意图、规划、实现、审查和呈现结果，跳过完整的规划阶段。
+**答：** 使用 Quick Flow，运行 `bmad-quick-dev`。它会在一个工作流里完成意图澄清、计划、实现、审查与结果呈现，跳过完整规划阶段。
 :::

-## 您将获得什么
+## 你将获得什么

-关于 BMad 的直接答案——智能体如何工作、工作流做什么、为什么事物以这种方式构建——无需等待其他人回应。
+你可以快速拿到直接、可执行的答案：智能体怎么工作、工作流做什么、为什么这样设计，而不需要等待外部回复。

 ## 提示

- **验证令人惊讶的答案**——LLM 偶尔会出错。检查源文件或在 Discord 上询问。
- **具体化**——"PRD 工作流的第 3 步做什么？"比"PRD 如何工作？"更好
+- **对“意外答案”做二次核验**：LLM 偶尔会答偏，建议回看源码或到 Discord 确认
+- **问题越具体越好**：例如“PRD 工作流第 3 步在做什么？”比“PRD 怎么用？”更高效

-## 仍然卡住了？
+## 仍然卡住？

-尝试了 LLM 方法但仍需要帮助？您现在有一个更好的问题可以问。
+如果你已经试过 LLM 方案但还需要协助，现在你通常已经能提出一个更清晰的问题。

-| 频道                   | 用于                                     |
-| ------------------------- | ------------------------------------------- |
-| `#bmad-method-help`       | 快速问题（实时聊天）            |
-| `help-requests` 论坛     | 详细问题（可搜索、持久） |
-| `#suggestions-feedback`   | 想法和功能请求                  |
-| `#report-bugs-and-issues` | 错误报告                                 |
+| 频道 | 适用场景 |
+| --- | --- |
+| `#bmad-method-help` | 快速问题（实时聊天） |
+| `help-requests` forum | 复杂问题（可检索、可沉淀） |
+| `#suggestions-feedback` | 建议与功能诉求 |
+| `#report-bugs-and-issues` | Bug 报告 |

-**Discord：** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
-
-**GitHub Issues：** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)（用于明确的错误）
+**Discord：** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)  
+**GitHub Issues：** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)（用于可复现问题）

 *你！*
        *卡住*
@ -132,13 +133,3 @@ https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
                         *今天？*

 *—Claude*
-
---
-## 术语说明
-
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **LLM**：大语言模型。基于深度学习的自然语言处理模型，能够理解和生成人类语言。
- **SaaS**：软件即服务。一种通过互联网提供软件应用的交付模式。
- **UX**：用户体验。用户在使用产品或服务过程中建立的主观感受和评价。
- **PRD**：产品需求文档。详细描述产品功能、特性和需求的正式文档。
- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。
--- a/docs/zh-cn/how-to/install-bmad.md
+++ b/docs/zh-cn/how-to/install-bmad.md
@ -5,9 +5,9 @@ sidebar:
  order: 1
 ---

-使用 `npx bmad-method install` 命令在项目中设置 BMad，并选择你需要的模块和 AI 工具。
+使用 `npx bmad-method install` 在项目中安装 BMad，并按需选择模块和 AI 工具。

-如果你想使用非交互式安装程序并在命令行中提供所有安装选项，请参阅[本指南](./non-interactive-installation.md)。
+如果你需要在命令行里一次性传入全部安装参数（例如 CI/CD 场景），请阅读[非交互式安装指南](./non-interactive-installation.md)。

 ## 何时使用

@ -29,7 +29,16 @@ sidebar:
 npx bmad-method install
 ```

-:::tip[最新版本]
+:::tip[想要最新预发布版本？]
+使用 `next` 发布标签：
+```bash
+npx bmad-method@next install
+```
+
+这会更早拿到新改动，但相比默认安装通道，出现变动的概率也更高。
+:::
+
+:::tip[前沿版本]
 要从主分支安装最新版本（可能不稳定）：
 ```bash
 npx github:bmad-code-org/BMAD-METHOD install
@ -51,7 +60,11 @@ npx github:bmad-code-org/BMAD-METHOD install
 - Cursor
 - 其他

-每个工具都有自己的命令集成方式。安装程序会创建微小的提示文件来激活工作流和智能体——它只是将它们放在工具期望找到的位置。
+每种工具都有自己的 skills 集成方式。安装程序会生成用于激活工作流和智能体的轻量提示文件，并放到该工具约定的位置。
+
+:::note[启用 Skills]
+某些平台需要你在设置中手动启用 skills 才会显示。如果你已经安装 BMad 但看不到 skills，请检查平台设置，或直接询问你的 AI 助手如何启用 skills。
+:::

 ### 4. 选择模块

@ -63,16 +76,25 @@ npx github:bmad-code-org/BMAD-METHOD install

 ## 你将获得

+以下目录结构仅作示例。工具相关目录会随你选择的平台变化（例如可能是
+`.claude/skills`、`.cursor/skills` 或 `.kiro/skills`），并不一定会同时出现。
+
 ```text
 your-project/
 ├── _bmad/
 │   ├── bmm/            # 你选择的模块
-│   │   └── config.yaml # 模块设置（如果你需要更改它们）
-│   ├── core/           # 必需的核心模块
+│   │   └── config.yaml # 模块设置（后续如需可修改）
+│   ├── core/           # 必需核心模块
 │   └── ...
-├── _bmad-output/       # 生成的工件
-├── .claude/            # Claude Code 命令（如果使用 Claude Code）
-└── .kiro/              # Kiro 引导文件（如果使用 Kiro）
+├── _bmad-output/       # 生成产物
+├── .claude/            # Claude Code skills（如使用 Claude Code）
+│   └── skills/
+│       ├── bmad-help/
+│       ├── bmad-persona/
+│       └── ...
+└── .cursor/            # Cursor skills（如使用 Cursor）
+    └── skills/
+        └── ...
 ```

 ## 验证安装
@ -96,10 +118,3 @@ bmad-help 对于 SaaS 项目我有哪些选项？

 **安装程序工作正常但后续出现问题**——你的 AI 需要 BMad 上下文才能提供帮助。请参阅[如何获取关于 BMad 的答案](./get-answers-about-bmad.md)了解如何将你的 AI 指向正确的来源。

---
-## 术语说明
-
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。
- **module**：模块。指软件系统中可独立开发、测试和维护的功能单元。
- **artifact**：工件。指在软件开发过程中生成的任何输出，如文档、代码、配置文件等。
--- a/docs/zh-cn/how-to/non-interactive-installation.md
+++ b/docs/zh-cn/how-to/non-interactive-installation.md
@ -1,11 +1,11 @@
 ---
 title: "非交互式安装"
-description: 使用命令行标志安装 BMad，适用于 CI/CD 流水线和自动化部署
+description: 使用命令行参数安装 BMad，适用于 CI/CD 流水线和自动化部署
 sidebar:
  order: 2
 ---

-使用命令行标志以非交互方式安装 BMad。这适用于：
+使用命令行参数（flags）以非交互方式安装 BMad。适用于以下场景：

 ## 使用场景

@ -18,11 +18,11 @@ sidebar:
 需要 [Node.js](https://nodejs.org) v20+ 和 `npx`（随 npm 附带）。
 :::

-## 可用标志
+## 可用参数（Flags）

 ### 安装选项

-| 标志 | 描述 | 示例 |
+| 参数 | 描述 | 示例 |
 |------|-------------|---------|
 | `--directory <path>` | 安装目录 | `--directory ~/projects/myapp` |
 | `--modules <modules>` | 逗号分隔的模块 ID | `--modules bmm,bmb` |
@ -32,7 +32,7 @@ sidebar:

 ### 核心配置

-| 标志 | 描述 | 默认值 |
+| 参数 | 描述 | 默认值 |
 |------|-------------|---------|
 | `--user-name <name>` | 智能体使用的名称 | 系统用户名 |
 | `--communication-language <lang>` | 智能体通信语言 | 英语 |
@ -41,14 +41,14 @@ sidebar:

 ### 其他选项

-| 标志 | 描述 |
+| 参数 | 描述 |
 |------|-------------|
 | `-y, --yes` | 接受所有默认值并跳过提示 |
 | `-d, --debug` | 启用清单生成的调试输出 |

 ## 模块 ID

-`--modules` 标志可用的模块 ID：
+`--modules` 参数可用的模块 ID：

 - `bmm` — BMad Method Master
 - `bmb` — BMad Builder
@ -57,7 +57,7 @@ sidebar:

 ## 工具/IDE ID

-`--tools` 标志可用的工具 ID：
+`--tools` 参数可用的工具 ID：

 **推荐：** `claude-code`、`cursor`

@ -67,8 +67,8 @@ sidebar:

 | 模式 | 描述 | 示例 |
 |------|-------------|---------|
-| 完全非交互式 | 提供所有标志以跳过所有提示 | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` |
-| 半交互式 | 提供部分标志；BMad 提示其余部分 | `npx bmad-method install --directory . --modules bmm` |
+| 完全非交互式 | 提供所有参数以跳过所有提示 | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` |
+| 半交互式 | 提供部分参数；BMad 提示其余部分 | `npx bmad-method install --directory . --modules bmm` |
 | 仅使用默认值 | 使用 `-y` 接受所有默认值 | `npx bmad-method install --yes` |
 | 不包含工具 | 跳过工具/IDE 配置 | `npx bmad-method install --modules bmm --tools none` |

@ -124,9 +124,9 @@ npx bmad-method install \
 - 为所选模块和工具配置的智能体和工作流
 - 用于生成产物的 `_bmad-output/` 文件夹

-## 验证和错误处理
+## 参数校验与错误处理

-BMad 会验证所有提供的标志：
+BMad 会验证你提供的所有参数：

 - **目录** — 必须是具有写入权限的有效路径
 - **模块** — 对无效的模块 ID 发出警告（但不会失败）
@ -141,14 +141,14 @@ BMad 会验证所有提供的标志：

 :::tip[最佳实践]
 - 为 `--directory` 使用绝对路径以避免歧义
- 在 CI/CD 流水线中使用前先在本地测试标志
+- 在 CI/CD 流水线中使用前先在本地测试参数
 - 结合 `-y` 实现真正的无人值守安装
 - 如果在安装过程中遇到问题，使用 `--debug`
 :::

 ## 故障排除

-### 安装失败，提示"Invalid directory"
+### 安装失败，提示 `Invalid directory`

 - 目录路径必须存在（或其父目录必须存在）
 - 您需要写入权限
@ -167,15 +167,6 @@ BMad 会验证所有提供的标志：
 - 在 `module.yaml` 中有 `code` 字段

 :::note[仍然卡住了？]
-使用 `--debug` 运行以获取详细输出，尝试交互模式以隔离问题，或在 <https://github.com/bmad-code-org/BMAD-METHOD/issues> 报告。
+使用 `--debug` 获取详细输出，尝试交互模式定位问题，或在 <https://github.com/bmad-code-org/BMAD-METHOD/issues> 提交反馈。
 :::

---
-## 术语说明
-
- **CI/CD**：持续集成/持续部署。一种自动化软件开发流程的实践，用于频繁集成代码更改并自动部署到生产环境。
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **module**：模块。软件系统中可独立开发、测试和维护的功能单元。
- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。
- **npx**：Node Package eXecute。npm 包执行器，用于直接执行 npm 包而无需全局安装。
- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。
--- a/docs/zh-cn/how-to/project-context.md
+++ b/docs/zh-cn/how-to/project-context.md
@ -5,27 +5,30 @@ sidebar:
  order: 8
 ---

-使用 `project-context.md` 文件确保 AI 智能体在所有工作流程中遵循项目的技术偏好和实现规则。
+使用 `project-context.md`，确保 AI 智能体在各类工作流中遵循项目的技术偏好与实现规则。
+为了保证这份上下文始终可见，你也可以在工具上下文或 always-rules 文件（如 `AGENTS.md`）
+中加入这句：
+`Important project context and conventions are located in [path to project context]/project-context.md`

 :::note[前置条件]
 - 已安装 BMad Method
- 了解项目的技术栈和约定
+- 了解项目的技术栈与团队约定
 :::

 ## 何时使用

- 在开始架构设计之前有明确的技术偏好
- 已完成架构设计并希望为实施捕获决策
- 正在处理具有既定模式的现有代码库
- 注意到智能体在不同用户故事中做出不一致的决策
+- 在开始架构（architecture）前，你已有明确的技术偏好
+- 已完成架构设计，希望把关键决策沉淀到实施阶段
+- 正在处理具有既定模式的既有代码库
+- 发现智能体在不同用户故事（story）之间决策不一致

-## 步骤 1：选择方法
+## 步骤 1：选择路径

-**手动创建** — 当您确切知道要记录哪些规则时最佳
+**手动创建** — 适合你已经明确知道要沉淀哪些规则

-**架构后生成** — 最适合捕获解决方案制定过程中所做的决策
+**架构后生成** — 适合把 solutioning 阶段形成的架构决策沉淀下来

-**为现有项目生成** — 最适合在现有代码库中发现模式
+**为既有项目生成** — 适合从现有代码库中自动发现团队约定与模式

 ## 步骤 2：创建文件

@ -38,17 +41,17 @@ mkdir -p _bmad-output
 touch _bmad-output/project-context.md
 ```

-添加技术栈和实现规则：
+然后补充技术栈与实现规则：

 ```markdown
 ---
-project_name: 'MyProject'
-user_name: 'YourName'
+project_name: '我的项目'
+user_name: '你的名字'
 date: '2026-02-15'
 sections_completed: ['technology_stack', 'critical_rules']
 ---

-# AI 智能体的项目上下文
+# AI 智能体项目上下文

 ## 技术栈与版本

@ -60,93 +63,70 @@ sections_completed: ['technology_stack', 'critical_rules']
 ## 关键实现规则

 **TypeScript：**
- 启用严格模式，不使用 `any` 类型
- 公共 API 使用 `interface`，联合类型使用 `type`
+- 开启严格模式，禁止使用 `any` 类型
+- 对外 API 使用 `interface`，联合类型使用 `type`

 **代码组织：**
- 组件位于 `/src/components/` 并附带同位置测试
- API 调用使用 `apiClient` 单例 — 绝不直接使用 fetch
+- 组件放在 `/src/components/`，并与测试文件同目录（co-located）
+- API 调用统一使用 `apiClient` 单例，不要直接使用 `fetch`

 **测试：**
- 单元测试专注于业务逻辑
- 集成测试使用 MSW 进行 API 模拟
+- 单元测试聚焦业务逻辑
+- 集成测试使用 MSW 模拟 API
 ```

 ### 选项 B：架构后生成

-在新的聊天中运行工作流程：
+在新的会话中运行：

 ```bash
-/bmad-bmm-generate-project-context
+bmad-generate-project-context
 ```

-工作流程扫描架构文档和项目文件，生成捕获所做决策的上下文文件。
+该工作流会扫描架构文档和项目文件，生成能够反映已做决策的上下文文件。

-### 选项 C：为现有项目生成
+### 选项 C：为既有项目生成

-对于现有项目，运行：
+对于既有项目，运行：

 ```bash
-/bmad-bmm-generate-project-context
+bmad-generate-project-context
 ```

-工作流程分析代码库以识别约定，然后生成上下文文件供您审查和完善。
+该工作流会分析代码库中的约定，然后生成可供你审阅和完善的上下文文件。

 ## 步骤 3：验证内容

-审查生成的文件并确保它捕获了：
+审查生成文件，并确认它覆盖了：

 - 正确的技术版本
- 实际约定（而非通用最佳实践）
- 防止常见错误的规则
- 框架特定的模式
+- 你的真实约定（不是通用最佳实践）
+- 能预防常见错误的规则
+- 框架相关模式

-手动编辑以添加任何缺失内容或删除不准确之处。
+如果有缺漏或误判，直接手动补充和修正。

-## 您将获得
+## 你将获得

-一个 `project-context.md` 文件，它：
+一个 `project-context.md` 文件，它可以：

- 确保所有智能体遵循相同的约定
- 防止在不同用户故事中做出不一致的决策
- 为实施捕获架构决策
- 作为项目模式和规则的参考
+- 确保所有智能体遵循相同约定
+- 避免在不同用户故事（story）中出现不一致决策
+- 为实施阶段保留架构决策
+- 作为项目模式与规则的长期参考

 ## 提示

-:::tip[关注非显而易见的内容]
-记录智能体可能遗漏的模式，例如"在每个公共类、函数和变量上使用 JSDoc 风格注释"，而不是像"使用有意义的变量名"这样的通用实践，因为 LLM 目前已经知道这些。
-:::
-
-:::tip[保持精简]
-此文件由每个实施工作流程加载。长文件会浪费上下文。不要包含仅适用于狭窄范围或特定用户故事或功能的内容。
-:::
-
-:::tip[根据需要更新]
-当模式发生变化时手动编辑，或在重大架构更改后重新生成。
-:::
-
-:::tip[适用于所有项目类型]
-对于快速流程和完整的 BMad Method 项目同样有用。
+:::tip[最佳实践]
+- **聚焦“不明显但重要”的规则**：优先记录智能体容易漏掉的项目约束，而不是
+  “变量要有意义”这类通用建议。
+- **保持精简**：此文件会被多数实现工作流加载，过长会浪费上下文窗口。避免写入
+  只适用于单一 story 的细节。
+- **按需更新**：当团队约定变化时手动更新，或在架构发生较大变化后重新生成。
+- **适用于 Quick Flow 与完整 BMad Method**：两种模式都可共享同一份项目上下文。
 :::

 ## 后续步骤

- [**项目上下文说明**](../explanation/project-context.md) — 了解其工作原理
- [**工作流程图**](../reference/workflow-map.md) — 查看哪些工作流程加载项目上下文
-
---
-## 术语说明
-
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **workflow**：工作流程。指完成特定任务的一系列步骤或过程。
- **codebase**：代码库。指项目的所有源代码和资源的集合。
- **implementation**：实施。指将设计或架构转化为实际代码的过程。
- **architecture**：架构。指系统的整体结构和设计。
- **stack**：技术栈。指项目使用的技术组合，如编程语言、框架、工具等。
- **convention**：约定。指团队或项目中遵循的编码规范和最佳实践。
- **singleton**：单例。一种设计模式，确保类只有一个实例。
- **co-located**：同位置。指相关文件（如测试文件）与主文件放在同一目录中。
- **mocking**：模拟。在测试中用模拟对象替代真实对象的行为。
- **context**：上下文。指程序运行时的环境信息或背景信息。
- **LLM**：大语言模型。Large Language Model 的缩写，指大型语言模型。
+- [**项目上下文说明**](../explanation/project-context.md) - 了解其工作原理
+- [**工作流程图**](../reference/workflow-map.md) - 查看哪些工作流会加载项目上下文
--- a/docs/zh-cn/how-to/quick-fixes.md
+++ b/docs/zh-cn/how-to/quick-fixes.md
@ -5,9 +5,9 @@ sidebar:
  order: 5
 ---

-使用 **Quick Dev** 进行 bug 修复、重构或小型针对性更改，这些操作不需要完整的 BMad Method。
+对于 bug 修复、重构或小范围改动，使用 **Quick Dev** 即可，不必走完整的 BMad Method。

-## 何时使用此方法
+## 何时使用本指南

 - 原因明确且已知的 bug 修复
 - 包含在少数文件中的小型重构（重命名、提取、重组）
@ -21,13 +21,13 @@ sidebar:

 ## 步骤

-### 1. 启动新的聊天
+### 1. 开启新会话

-在 AI IDE 中打开一个**新的聊天会话**。重用之前工作流的会话可能导致上下文冲突。
+在 AI IDE 中开启一个**全新的聊天会话**。复用之前工作流留下的会话，容易引发上下文冲突。

 ### 2. 提供你的意图

-Quick Dev 接受自由形式的意图——可以在调用之前、同时或之后提供。示例：
+Quick Dev 支持自由表达意图，你可以在调用前、调用时或调用后补充说明。示例：

 ```text
 run quick-dev — 修复允许空密码的登录验证 bug。
@ -53,20 +53,20 @@ run quick-dev
 重构 UserService 以使用 async/await 而不是回调。
 ```

-纯文本、文件路径、GitHub issue URL、bug 跟踪器链接——任何 LLM 能解析为具体意图的内容都可以。
+纯文本、文件路径、GitHub issue 链接、缺陷跟踪地址都可以，只要 LLM 能解析成明确意图。

 ### 3. 回答问题并批准

-Quick Dev 可能会提出澄清问题，或在实现之前呈现简短的规范供你批准。回答它的问题，并在你对计划满意时批准。
+Quick Dev 可能会先问澄清问题，或在实现前给出一份简短方案供你确认。回答问题后，在你认可方案时再批准继续。

 ### 4. 审查和推送

-Quick Dev 实现更改、审查自己的工作、修复问题，并在本地提交。完成后，它会在编辑器中打开受影响的文件。
+Quick Dev 会实现改动、执行自检并修补问题，然后在本地提交。完成后，它会在编辑器中打开受影响文件。

- 浏览 diff 以确认更改符合你的意图
- 如果看起来有问题，告诉智能体需要修复什么——它可以在同一会话中迭代
+- 快速浏览 diff，确认改动符合你的意图
+- 如果有偏差，直接告诉智能体要改什么，它可以在同一会话里继续迭代

-满意后，推送提交。Quick Dev 会提供推送和创建 PR 的选项。
+确认无误后推送提交。Quick Dev 会提供推送和创建 PR 的选项。

 :::caution[如果出现问题]
 如果推送的更改导致意外问题，请使用 `git revert HEAD` 干净地撤销最后一次提交。然后启动新聊天并再次运行 Quick Dev 以尝试不同的方法。
@ -80,9 +80,9 @@ Quick Dev 实现更改、审查自己的工作、修复问题，并在本地提

 ## 延迟工作

-Quick Dev 保持每次运行聚焦于单一目标。如果你的请求包含多个独立目标，或者审查发现了与你的更改无关的已有问题，Quick Dev 会将它们延迟到一个文件中（实现产物目录中的 `deferred-work.md`），而不是试图一次解决所有问题。
+Quick Dev 每次只聚焦一个目标。如果你的请求包含多个独立目标，或审查过程中发现与你本次改动无关的存量问题，Quick Dev 会把它们记录到 `deferred-work.md`（位于实现产物目录），而不是一次性全都处理。

-运行后检查此文件——它是你的待办事项积压。每个延迟项目都可以稍后输入到新的 Quick Dev 运行中。
+每次运行后都建议看一下这个文件，它就是你的后续待办清单。你可以把其中任何一项在后续新的 Quick Dev 会话里单独处理。

 ## 何时升级到正式规划

@ -92,16 +92,4 @@ Quick Dev 保持每次运行聚焦于单一目标。如果你的请求包含多
 - 你不确定范围，需要先进行需求发现
 - 你需要为团队记录文档或架构决策

-参见 [Quick Dev](../explanation/quick-dev.md) 了解 Quick Dev 如何融入 BMad Method。
-
---
-## 术语说明
-
- **Quick Dev**：快速开发。BMad Method 中的快速工作流，用于小型更改的完整实现周期。
- **refactoring**：重构。在不改变代码外部行为的情况下改进其内部结构的过程。
- **breaking changes**：破坏性更改。可能导致现有代码或功能不再正常工作的更改。
- **test suite**：测试套件。一组用于验证软件功能的测试用例集合。
- **CI pipeline**：CI 流水线。持续集成流水线，用于自动化构建、测试和部署代码。
- **diff**：差异。文件或代码更改前后的对比。
- **commit**：提交。将更改保存到版本控制系统的操作。
- **conventional commit**：约定式提交。遵循标准格式的提交消息。
+参见 [Quick Dev](../explanation/quick-dev.md) 了解 Quick Dev 在 BMad Method 中的位置与边界。
--- a/docs/zh-cn/how-to/shard-large-documents.md
+++ b/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`
-2. **检查分片版本** - 查找 `document-name/index.md`
-3. **优先级规则** - 如果两者都存在，完整文档优先 - 如果希望使用分片版本，请删除完整文档
+1. **先查完整文档** - 查找 `document-name.md`
+2. **再查分片入口** - 查找 `document-name/index.md`
+3. **优先级规则** - 若两者并存，默认优先完整文档；若你要强制使用分片版本，请删除或重命名完整文档

-## 工作流程支持
+## 你将获得

-所有 BMM 工作流程都支持这两种格式：
+- 原始完整文档（可保留，但不建议与分片长期并存；并存时默认优先读取完整文档）
+- 分片目录（如 `document-name/index.md` + 各章节文件）
+- 对工作流透明的自动识别行为（无需额外配置）

- 完整文档
- 分片文档
- 自动检测
- 对用户透明
+## 后续步骤

---
-## 术语说明
-
- **sharding**：分片。将大型文档或数据集拆分为更小、更易管理的部分的过程。
- **token**：令牌。在自然语言处理和大型语言模型中，文本的基本单位，通常对应单词或字符的一部分。
- **subprocesses**：子进程。由主进程创建的独立执行单元，可以并行运行以执行特定任务。
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
+- [如何自定义 BMad](./customize-bmad.md) - 了解高级配置与工作流定制边界
+- [如何升级到 v6](./upgrade-to-v6.md) - 在迁移过程中处理文档与目录结构变化
--- a/docs/zh-cn/how-to/upgrade-to-v6.md
+++ b/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` 文件夹）
- 您希望迁移到新的 v6 架构
- 您有需要保留的现有规划产物
+- 你已安装 BMad v4（目录名通常是 `.bmad-method`）
+- 你准备迁移到 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/BMad/tasks`
+- `.claude/commands/`
+
+v6 新技能会安装到：
+
+- `.claude/skills/`

 ### 4. 迁移规划产物

-**如果您有规划文档（Brief/PRD/UX/Architecture）：**
+**如果你有规划文档（Brief/PRD/UX/Architecture）：**

-将它们移动到 `_bmad-output/planning-artifacts/` 并使用描述性名称：
+把它们移动到 `_bmad-output/planning-artifacts/`，并使用可读的文件名：

- 在文件名中包含 `PRD` 用于 PRD 文档
- 相应地包含 `brief`、`architecture` 或 `ux-design`
- 分片文档可以放在命名的子文件夹中
+- PRD 文档文件名包含 `PRD`
+- 其他文档按类型包含 `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/               # 单一安装文件夹
-│   ├── _config/         # 您的自定义配置
+├── _bmad/               # 单一安装目录
+│   ├── _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                                   |
-| ------------ | --------------------------------------- | ------------------------------------ |
-| **核心**     | `_bmad-core` 实际上是 BMad Method      | `_bmad/core/` 是通用框架             |
-| **方法**     | `_bmad-method`                          | `_bmad/bmm/`                         |
-| **配置**     | 直接修改文件                            | 每个模块使用 `config.yaml`           |
-| **文档**     | 需要设置分片或非分片                    | 完全灵活，自动扫描                   |
+| 概念 | v4（旧） | v6（新） | 迁移提示 |
+| ------------ | --------------------------------------- | ------------------------------------ | ------------------------------------ |
+| **核心框架** | `_bmad-core` 实际上承载的是 BMad Method | `_bmad/core/` 变成通用框架层 | 迁移时不要再把 `_bmad/core/` 当成 Method 本体 |
+| **方法模块** | `_bmad-method` | `_bmad/bmm/` | 旧脚本、路径引用需同步更新到 `bmm` |
+| **配置方式** | 直接改模块文件 | 每个模块通过 `config.yaml` 管理 | 优先改配置，不要直接改生成文件 |
+| **文档读取** | 需要手动区分分片/非分片 | 自动扫描完整文档与分片入口 | 只有在兼容性场景下才建议手动分片 |

---
-## 术语说明
+## 后续建议

- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **epic**：史诗。在敏捷开发中，指大型的工作项，可分解为多个用户故事。
- **story**：故事。在敏捷开发中，指用户故事，描述用户需求的功能单元。
- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队流程和移除障碍。
- **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 中的一种工作模式，用于规划和设计任务。
+- 升级完成后先运行 `bmad-help`，确认可用工作流与下一步建议
+- 如果是既有项目，补充或更新 `project-context.md`，减少后续实现偏差
+- 在继续开发前，先做一次关键链路验证（安装、命令触发、文档读取）
+- 继续阅读：[如何安装 BMad](./install-bmad.md)、[管理项目上下文](./project-context.md)
--- a/docs/zh-cn/index.md
+++ b/docs/zh-cn/index.md
@ -1,55 +1,55 @@
 ---
 title: 欢迎使用 BMad 方法
-description: 具备专业智能体、引导式工作流和智能规划的 AI 驱动开发框架
+description: 具备专业智能体、引导式工作流与智能规划的 AI 驱动开发框架
 ---

-BMad 方法（**B**reakthrough **M**ethod of **A**gile AI **D**riven Development，敏捷 AI 驱动开发的突破性方法）是 BMad 方法生态系统中的一个 AI 驱动开发框架模块，帮助您完成从构思和规划到智能体实现的整个软件开发过程。它提供专业的 AI 智能体、引导式工作流和智能规划，能够根据您项目的复杂度进行调整，无论是修复错误还是构建企业平台。
+BMad 方法（**B**uild **M**ore **A**rchitect **D**reams）是 BMad 方法生态中的 AI 驱动开发框架模块，覆盖从构思、规划到智能体实施的完整软件交付流程。它提供专业智能体、引导式工作流和可随项目复杂度调整的智能规划，无论是修复 bug 还是构建企业级平台都适用。

-如果您熟悉使用 Claude、Cursor 或 GitHub Copilot 等 AI 编码助手，就可以开始使用了。
+如果你已经习惯使用 Claude、Cursor 或 GitHub Copilot 这类 AI 编码助手，现在就可以开始。

 :::note[🚀 V6 已发布，我们才刚刚起步！]
 技能架构、BMad Builder v1、开发循环自动化以及更多功能正在开发中。**[查看路线图 →](/zh-cn/roadmap/)**
 :::

-## 新手入门？从教程开始
+## 新手入门？先从教程开始

 理解 BMad 的最快方式是亲自尝试。

- **[BMad 入门指南](./tutorials/getting-started.md)** — 安装并了解 BMad 的工作原理
- **[工作流地图](./reference/workflow-map.md)** — BMM 阶段、工作流和上下文管理的可视化概览
+- **[BMad 入门教程](./tutorials/getting-started.md)** — 安装并理解 BMad 如何工作
+- **[工作流地图](./reference/workflow-map.md)** — BMM 阶段、工作流与上下文管理的全景视图

 :::tip[只想直接上手？]
-安装 BMad 并运行 `bmad-help` — 它会根据您的项目和已安装的模块引导您完成所有操作。
+安装 BMad 后运行 `bmad-help`，它会根据你的项目状态和已安装模块给出下一步建议。
 :::

-## 如何使用本文档
+## 如何使用这些文档

-本文档根据您的目标分为四个部分：
+这些文档按你的目标分成四个部分：

-| 部分           | 用途                                                                                                    |
-| ----------------- | ---------------------------------------------------------------------------------------------------------- |
-| **教程**     | 以学习为导向。通过分步指南引导您构建内容。如果您是新手，请从这里开始。 |
-| **操作指南** | 以任务为导向。解决特定问题的实用指南。"如何自定义智能体？"等内容位于此处。  |
-| **说明**   | 以理解为导向。深入探讨概念和架构。当您想知道*为什么*时阅读。       |
-| **参考**     | 以信息为导向。智能体、工作流和配置的技术规范。                   |
+| 部分 | 用途 |
+| --- | --- |
+| **教程** | 学习导向。通过分步引导带你做成一件事。第一次使用建议从这里开始。 |
+| **操作指南** | 任务导向。解决具体问题的实用文档，例如“如何自定义智能体”。 |
+| **说明** | 理解导向。深入讲解概念与架构，适合回答“为什么”。 |
+| **参考** | 信息导向。提供智能体、工作流和配置项的技术规格。 |

-## 扩展和自定义
+## 扩展与自定义

-想要使用自己的智能体、工作流或模块来扩展 BMad 吗？**[BMad Builder（英文）](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展的框架和工具，无论是为 BMad 添加新功能还是从头开始构建全新的模块。
+想用自己的智能体、工作流或模块扩展 BMad？**[BMad Builder（英文）](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展所需的框架与工具，无论是给 BMad 添加能力，还是从零构建新模块都可以。

-## 您需要什么
+## 你需要准备什么

-BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码助手配合使用。热门选项包括：
+BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码助手配合使用，常见选择包括：

 - **[Claude Code](https://code.claude.com)** — Anthropic 的 CLI 工具（推荐）
 - **[Cursor](https://cursor.sh)** — AI 优先的代码编辑器
 - **[Codex CLI](https://github.com/openai/codex)** — OpenAI 的终端编码智能体

-您应该熟悉版本控制、项目结构和敏捷工作流等基本软件开发概念。无需具备 BMad 风格智能体系统的先验经验——这正是本文档的作用。
+你需要了解一些基础软件工程概念，例如版本控制、项目结构和敏捷工作流。即使没有使用过 BMad 风格智能体系统，也可以从这些文档开始上手。

 ## 加入社区

-获取帮助、分享您的构建内容，或为 BMad 做出贡献：
+获取帮助、分享成果，或参与贡献：

 - **[Discord](https://discord.gg/gk8jAdXWmj)** — 与其他 BMad 用户聊天、提问、分享想法
 - **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — 源代码、问题和贡献
@ -57,13 +57,4 @@ BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码

 ## 下一步

-准备开始了吗？**[BMad 入门指南](./tutorials/getting-started.md)** 并构建您的第一个项目。
-
---
-## 术语说明
-
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **AI-driven**：AI 驱动。指由人工智能技术主导或驱动的系统或方法。
- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。
- **prompt**：提示词。指输入给 AI 模型的指令或问题，用于引导其生成特定输出。
- **context**：上下文。指在特定场景下理解信息所需的背景信息或环境。
+准备好开始了吗？**[从 BMad 入门教程开始](./tutorials/getting-started.md)**，构建你的第一个项目。
--- a/docs/zh-cn/reference/workflow-map.md
+++ b/docs/zh-cn/reference/workflow-map.md
@ -68,7 +68,7 @@ BMad Method（BMM）是 BMad 生态系统中的一个模块，旨在遵循上下

 | 工作流程              | 目的                                                                     | 产出                        |
 | --------------------- | --------------------------------------------------------------------------- | --------------------------- |
-| `bmad-bmm-quick-dev`  | 统一快速流程 — 澄清意图、规划、实现、审查和呈现   | `tech-spec.md` + 代码  |
+| `bmad-bmm-quick-dev`  | 统一快速流程 — 澄清意图、规划、实现、审查和呈现   | `spec-*.md` + 代码  |

 ## 上下文管理

--- a/docs/zh-cn/tutorials/getting-started.md
+++ b/docs/zh-cn/tutorials/getting-started.md
@ -37,13 +37,13 @@ description: 安装 BMad 并构建你的第一个项目

 ### 如何使用 BMad-Help

-只需在 AI IDE 中使用斜杠命令运行它：
+在你的 AI IDE 中直接调用技能名：

 ```
 bmad-help
 ```

-或者结合问题以获得上下文感知的指导：
+也可以带着问题一起调用，获得更贴合上下文的建议：

 ```
 bmad-help 我有一个 SaaS 产品的想法，我已经知道我想要的所有功能。我应该从哪里开始？
@ -70,7 +70,7 @@ BMad 通过带有专门 AI 智能体的引导工作流帮助你构建软件。
 | ---- | -------------- | -------------------------------------------------- |
 | 1    | 分析           | 头脑风暴、研究、产品简报 *（可选）*                |
 | 2    | 规划           | 创建需求（PRD 或技术规范）                         |
-| 3    | 解决方案设计   | 设计架构 *（仅限 BMad Method/Enterprise only）*         |
+| 3    | 解决方案设计   | 设计架构 *（仅适用于 BMad Method/Enterprise）*          |
 | 4    | 实现           | 逐个史诗、逐个故事地构建                           |

 **[打开工作流地图](../reference/workflow-map.md)** 以探索阶段、工作流和上下文管理。
@ -95,6 +95,8 @@ BMad 通过带有专门 AI 智能体的引导工作流帮助你构建软件。
 npx bmad-method install
 ```

+如果你想使用最新预发布版本（而不是默认发布通道），可以改用 `npx bmad-method@next install`。
+
 当提示选择模块时，选择 **BMad Method**。

 安装程序会创建两个文件夹：
@ -112,7 +114,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么
 :::

 :::note[如何加载智能体和运行工作流]
-每个工作流都有一个你在 IDE 中运行的**斜杠命令**（例如 `bmad-bmm-create-prd`）。运行工作流命令会自动加载相应的智能体 —— 你不需要单独加载智能体。你也可以直接加载智能体进行一般对话（例如，加载 PM 智能体使用 `bmad-agent-bmm-pm`）。
+每个工作流都可以通过技能名直接调用（例如 `bmad-create-prd`）。你的 AI IDE 会识别 `bmad-*` 技能并执行，无需额外单独加载智能体。你也可以直接调用智能体技能进行通用对话（例如 PM 智能体用 `bmad-agent-pm`）。
 :::

 :::caution[新对话]
@ -126,35 +128,35 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么
 :::tip[项目上下文（可选）]
 在开始之前，考虑创建 `project-context.md` 来记录你的技术偏好和实现规则。这确保所有 AI 智能体在整个项目中遵循你的约定。

-在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `bmad-bmm-generate-project-context` 生成它。[了解更多](../explanation/project-context.md)。
+在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `bmad-generate-project-context` 生成它。[了解更多](../explanation/project-context.md)。
 :::

 ### 阶段 1：分析（可选）

 此阶段中的所有工作流都是可选的：
 - **头脑风暴**（`bmad-brainstorming`） — 引导式构思
- **研究**（`bmad-bmm-research`） — 市场和技术研究
- **创建产品简报**（`bmad-bmm-create-product-brief`） — 推荐的基础文档
+- **研究**（`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`） — 市场、领域和技术研究
+- **创建产品简报**（`bmad-create-product-brief`） — 推荐的基础文档

 ### 阶段 2：规划（必需）

 **对于 BMad Method 和 Enterprise 路径：**
-1. 在新对话中加载 **PM 智能体**（`bmad-agent-bmm-pm`）
-2. 运行 `prd` 工作流（`bmad-bmm-create-prd`）
+1. 在新对话中调用 **PM 智能体**（`bmad-agent-pm`）
+2. 运行 `bmad-create-prd` 工作流（`bmad-create-prd`）
 3. 输出：`PRD.md`

 **对于 Quick Flow 路径：**
- 运行 `bmad-bmm-quick-dev` — 它在单个工作流中处理规划和实现，跳转到实现
+- 运行 `bmad-quick-dev` —— 它会在一个工作流里同时处理规划与实现，可直接进入实现阶段

 :::note[UX 设计（可选）]
-如果你的项目有用户界面，在创建 PRD 后加载 **UX-Designer 智能体**（`bmad-agent-bmm-ux-designer`）并运行 UX 设计工作流（`bmad-bmm-create-ux-design`）。
+如果你的项目有用户界面，在创建 PRD 后调用 **UX-Designer 智能体**（`bmad-agent-ux-designer`），然后运行 UX 设计工作流（`bmad-create-ux-design`）。
 :::

 ### 阶段 3：解决方案设计（BMad Method/Enterprise）

 **创建架构**
-1. 在新对话中加载 **Architect 智能体**（`bmad-agent-bmm-architect`）
-2. 运行 `create-architecture`（`bmad-bmm-create-architecture`）
+1. 在新对话中调用 **Architect 智能体**（`bmad-agent-architect`）
+2. 运行 `bmad-create-architecture`（`bmad-create-architecture`）
 3. 输出：包含技术决策的架构文档

 **创建史诗和故事**
@ -163,13 +165,13 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么
 史诗和故事现在在架构*之后*创建。这会产生更高质量的故事，因为架构决策（数据库、API 模式、技术栈）直接影响工作应该如何分解。
 :::

-1. 在新对话中加载 **PM 智能体**（`bmad-agent-bmm-pm`）
-2. 运行 `create-epics-and-stories`（`bmad-bmm-create-epics-and-stories`）
+1. 在新对话中调用 **PM 智能体**（`bmad-agent-pm`）
+2. 运行 `bmad-create-epics-and-stories`（`bmad-create-epics-and-stories`）
 3. 工作流使用 PRD 和架构来创建技术信息丰富的故事

 **实现就绪检查** *（强烈推荐）*
-1. 在新对话中加载 **Architect 智能体**（`bmad-agent-bmm-architect`）
-2. 运行 `check-implementation-readiness`（`bmad-bmm-check-implementation-readiness`）
+1. 在新对话中调用 **Architect 智能体**（`bmad-agent-architect`）
+2. 运行 `bmad-check-implementation-readiness`（`bmad-check-implementation-readiness`）
 3. 验证所有规划文档之间的一致性

 ## 步骤 2：构建你的项目
@ -178,7 +180,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么

 ### 初始化冲刺规划

-加载 **SM 智能体**（`bmad-agent-bmm-sm`）并运行 `sprint-planning`（`bmad-bmm-sprint-planning`）。这将创建 `sprint-status.yaml` 来跟踪所有史诗和故事。
+调用 **SM 智能体**（`bmad-agent-sm`）并运行 `bmad-sprint-planning`（`bmad-sprint-planning`）。这会创建 `sprint-status.yaml` 来跟踪所有史诗和故事。

 ### 构建周期

@ -186,11 +188,11 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么

 | 步骤 | 智能体 | 工作流       | 命令                    | 目的                            |
 | ---- | ------ | ------------ | ----------------------- | ------------------------------- |
-| 1    | SM     | `create-story` | `bmad-bmm-create-story`  | 从史诗创建故事文件              |
-| 2    | DEV    | `dev-story`    | `bmad-bmm-dev-story`     | 实现故事                        |
-| 3    | DEV    | `code-review`  | `bmad-bmm-code-review`   | 质量验证 *（推荐）*             |
+| 1    | SM     | `bmad-create-story` | `bmad-create-story` | 从史诗创建故事文件              |
+| 2    | DEV    | `bmad-dev-story`    | `bmad-dev-story`    | 实现故事                        |
+| 3    | DEV    | `bmad-code-review`  | `bmad-code-review`  | 质量验证 *（推荐）*             |

-完成史诗中的所有故事后，加载 **SM 智能体**（`bmad-agent-bmm-sm`）并运行 `retrospective`（`bmad-bmm-retrospective`）。
+完成史诗中的所有故事后，调用 **SM 智能体**（`bmad-agent-sm`）并运行 `bmad-retrospective`（`bmad-retrospective`）。

 ## 你已完成的工作

@ -221,16 +223,16 @@ your-project/

 | 工作流                              | 命令                                    | 智能体   | 目的                                         |
 | ----------------------------------- | --------------------------------------- | -------- | -------------------------------------------- |
-| **`help`** ⭐                       | `bmad-help`                            | 任意     | **你的智能向导 —— 随时询问任何问题！**        |
-| `prd`                               | `bmad-bmm-create-prd`                  | PM       | 创建产品需求文档                             |
-| `create-architecture`               | `bmad-bmm-create-architecture`         | Architect | 创建架构文档                                 |
-| `generate-project-context`          | `bmad-bmm-generate-project-context`    | Analyst  | 创建项目上下文文件                           |
-| `create-epics-and-stories`          | `bmad-bmm-create-epics-and-stories`    | PM       | 将 PRD 分解为史诗                            |
-| `check-implementation-readiness`    | `bmad-bmm-check-implementation-readiness` | Architect | 验证规划一致性                               |
-| `sprint-planning`                   | `bmad-bmm-sprint-planning`             | SM       | 初始化冲刺跟踪                               |
-| `create-story`                      | `bmad-bmm-create-story`                | SM       | 创建故事文件                                 |
-| `dev-story`                         | `bmad-bmm-dev-story`                   | DEV      | 实现故事                                     |
-| `code-review`                       | `bmad-bmm-code-review`                 | DEV      | 审查已实现的代码                             |
+| **`bmad-help`** ⭐                  | `bmad-help`                            | 任意     | **你的智能向导 —— 随时询问任何问题！**        |
+| `bmad-create-prd`                   | `bmad-create-prd`                      | PM       | 创建产品需求文档                             |
+| `bmad-create-architecture`          | `bmad-create-architecture`             | Architect | 创建架构文档                                |
+| `bmad-generate-project-context`     | `bmad-generate-project-context`        | Analyst  | 创建项目上下文文件                           |
+| `bmad-create-epics-and-stories`     | `bmad-create-epics-and-stories`        | PM       | 将 PRD 分解为史诗                            |
+| `bmad-check-implementation-readiness` | `bmad-check-implementation-readiness` | Architect | 验证规划一致性                              |
+| `bmad-sprint-planning`              | `bmad-sprint-planning`                 | SM       | 初始化冲刺跟踪                               |
+| `bmad-create-story`                 | `bmad-create-story`                    | SM       | 创建故事文件                                 |
+| `bmad-dev-story`                    | `bmad-dev-story`                       | DEV      | 实现故事                                     |
+| `bmad-code-review`                  | `bmad-code-review`                     | DEV      | 审查已实现的代码                             |

 ## 常见问题

@ -238,10 +240,10 @@ your-project/
 仅对于 BMad Method 和 Enterprise 路径。Quick Flow 从技术规范跳转到实现。

 **我可以稍后更改我的计划吗？**
-可以。SM 智能体有一个 `correct-course` 工作流（`bmad-bmm-correct-course`）用于处理范围变更。
+可以。SM 智能体提供 `bmad-correct-course` 工作流（`bmad-correct-course`）来处理范围变化。

 **如果我想先进行头脑风暴怎么办？**
-在开始 PRD 之前，加载 Analyst 智能体（`bmad-agent-bmm-analyst`）并运行 `brainstorming`（`bmad-brainstorming`）。
+在开始 PRD 之前，调用 Analyst 智能体（`bmad-agent-analyst`）并运行 `bmad-brainstorming`（`bmad-brainstorming`）。

 **我需要遵循严格的顺序吗？**
 不一定。一旦你了解了流程，你可以使用上面的快速参考直接运行工作流。
@ -271,30 +273,3 @@ BMad-Help 检查你的项目，检测你已完成的内容，并确切地告诉
 :::

 准备好开始了吗？安装 BMad，运行 `bmad-help`，让你的智能向导为你引路。
-
---
-## 术语说明
-
- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **epic**：史诗。软件开发中用于组织和管理大型功能或用户需求的高级工作项。
- **story**：故事。敏捷开发中的用户故事，描述用户需求的小型工作项。
- **PRD**：产品需求文档（Product Requirements Document）。详细描述产品功能、需求和目标的文档。
- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定目标。
- **sprint**：冲刺。敏捷开发中的固定时间周期，用于完成预定的工作。
- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试等功能的软件工具。
- **artifact**：工件。软件开发过程中产生的文档、代码或其他可交付成果。
- **retrospective**：回顾。敏捷开发中的会议，用于反思和改进团队工作流程。
- **tech-spec**：技术规范（Technical Specification）。描述系统技术实现细节的文档。
- **UX**：用户体验（User Experience）。用户在使用产品过程中的整体感受和交互体验。
- **PM**：产品经理（Product Manager）。负责产品规划、需求管理和团队协调的角色。
- **SM**：Scrum Master。敏捷开发中的角色，负责促进 Scrum 流程和团队协作。
- **DEV**：开发者（Developer）。负责编写代码和实现功能的角色。
- **Architect**：架构师。负责系统架构设计和技术决策的角色。
- **Analyst**：分析师。负责需求分析、市场研究等工作的角色。
- **npx**：Node Package eXecute。Node.js 包执行器，用于运行 npm 包而无需安装。
- **Node.js**：基于 Chrome V8 引擎的 JavaScript 运行时环境。
- **Git**：分布式版本控制系统。
- **SaaS**：软件即服务（Software as a Service）。通过互联网提供软件服务的模式。
- **DevOps**：开发运维（Development and Operations）。强调开发和运维协作的实践和方法。
- **multi-tenant**：多租户。一种软件架构，允许单个实例为多个客户（租户）提供服务。
- **compliance**：合规性。遵守法律、法规和行业标准的要求。
--- a/src/bmm-skills/4-implementation/bmad-correct-course/workflow.md
+++ b/src/bmm-skills/4-implementation/bmad-correct-course/workflow.md
@ -36,7 +36,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 | Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/*epic*/*.md` (sharded) | FULL_LOAD |
 | Architecture | `{planning_artifacts}/*architecture*.md` (whole) or `{planning_artifacts}/*architecture*/*.md` (sharded) | FULL_LOAD |
 | UX Design | `{planning_artifacts}/*ux*.md` (whole) or `{planning_artifacts}/*ux*/*.md` (sharded) | FULL_LOAD |
-| Tech Spec | `{planning_artifacts}/*tech-spec*.md` (whole) | FULL_LOAD |
+| Spec | `{planning_artifacts}/*spec-*.md` (whole) | FULL_LOAD |
 | Document Project | `{project_knowledge}/index.md` (sharded) | INDEX_GUIDED |

 ### Context
@ -51,9 +51,9 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:

 **Strategy**: Course correction needs broad project context to assess change impact accurately. Load all available planning artifacts.

-**Discovery Process for FULL_LOAD documents (PRD, Epics, Architecture, UX Design, Tech Spec):**
+**Discovery Process for FULL_LOAD documents (PRD, Epics, Architecture, UX Design, Spec):**

-1. **Search for whole document first** - Look for files matching the whole-document pattern (e.g., `*prd*.md`, `*epic*.md`, `*architecture*.md`, `*ux*.md`, `*tech-spec*.md`)
+1. **Search for whole document first** - Look for files matching the whole-document pattern (e.g., `*prd*.md`, `*epic*.md`, `*architecture*.md`, `*ux*.md`, `*spec-*.md`)
 2. **Check for sharded version** - If whole document not found, look for a directory with `index.md` (e.g., `prd/index.md`, `epics/index.md`)
 3. **If sharded version found**:
   - Read `index.md` to understand the document structure
@ -70,7 +70,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:

 **Fuzzy matching**: Be flexible with document names — users may use variations like `prd.md`, `bmm-prd.md`, `product-requirements.md`, etc.

-**Missing documents**: Not all documents may exist. PRD and Epics are essential; Architecture, UX Design, Tech Spec, and Document Project are loaded if available. HALT if PRD or Epics cannot be found.
+**Missing documents**: Not all documents may exist. PRD and Epics are essential; Architecture, UX Design, Spec, and Document Project are loaded if available. HALT if PRD or Epics cannot be found.

 <workflow>

--- a/src/bmm-skills/4-implementation/bmad-quick-dev/tech-spec-template.md
+++ b/src/bmm-skills/4-implementation/bmad-quick-dev/tech-spec-template.md
@ -11,8 +11,6 @@ context: [] # optional: max 3 project-wide standards/docs. NO source code files.
     Cohesive cross-layer stories (DB+BE+UI) stay in ONE file.
     IMPORTANT: Remove all HTML comments when filling this template. -->

-# {title}
-
 <frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">

 ## Intent
--- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md
+++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md
@ -1,5 +1,5 @@
 ---
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+wipFile: '{implementation_artifacts}/spec-wip.md'
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 spec_file: '' # set at runtime for plan-code-review before leaving this step
 ---
@ -15,13 +15,27 @@ spec_file: '' # set at runtime for plan-code-review before leaving this step
 - The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them.
 - **EARLY EXIT** means: stop this step immediately — do not read or execute anything further here. Read and fully follow the target file instead. Return here ONLY if a later step explicitly says to loop back.

-## ARTIFACT SCAN
+## Intent check (do this first)

- `{wipFile}` exists? → Offer resume or archive.
- Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
-  - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `./step-03-implement.md`
-  - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./step-04-review.md`
- Unformatted spec or intent file lacking `status` frontmatter in `{implementation_artifacts}`? → Suggest to the user to treat its contents as the starting intent for this workflow. DO NOT attempt to infer a state and resume it.
+Before listing artifacts or prompting the user, check whether you already know the intent. Check in this order — skip the remaining checks as soon as the intent is clear:
+
+1. Explicit argument
+   Did the user pass a specific file path, spec name, or clear instruction this message?
+   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: ready-for-dev, in-progress, or in-review) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-03 for ready/in-progress, step-04 for review).
+   - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it.
+
+2. Recent conversation
+   Do the last few human messages clearly show what the user intends to work on?
+   Use the same routing as above.
+
+3. Otherwise — scan artifacts and ask
+   - `{wipFile}` exists? → Offer resume or archive.
+   - Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `./step-03-implement.md`
+     - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./step-04-review.md`
+   - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
+
+Never ask extra questions if you already understand what the user intends.

 ## INSTRUCTIONS

@ -42,7 +56,7 @@ spec_file: '' # set at runtime for plan-code-review before leaving this step
   **EARLY EXIT** → `./step-oneshot.md`

   **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
-   1. Derive a valid kebab-case slug from the clarified intent. If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`.
+   1. Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.


 ## NEXT
--- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md
+++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md
@ -1,5 +1,5 @@
 ---
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+wipFile: '{implementation_artifacts}/spec-wip.md'
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ---

@ -13,7 +13,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ## INSTRUCTIONS

 1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
-2. Read `./tech-spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`.
+2. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`.
 3. Self-review against READY FOR DEVELOPMENT standard.
 4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
 5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
--- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md
+++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md
@ -28,6 +28,10 @@ Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents ar

 **Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.

+### Self-Check
+
+Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding.
+
 ## NEXT

 Read fully and follow `./step-04-review.md`
--- a/src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md
+++ b/src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md
@ -72,7 +72,7 @@ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `

 ### 2. Paths

- `wipFile` = `{implementation_artifacts}/tech-spec-wip.md`
+- `wipFile` = `{implementation_artifacts}/spec-wip.md`

 ### 3. First Step Execution

--- a/src/bmm-skills/module-help.csv
+++ b/src/bmm-skills/module-help.csv
@ -1,7 +1,7 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
 bmm,anytime,Document Project,DP,,skill:bmad-document-project,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*,
-bmm,anytime,Generate Project Context,GPC,,skill:bmad-generate-project-context,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects and quick-flow.",output_folder,"project context",
-bmm,anytime,Quick Dev,QQ,,skill:bmad-quick-dev,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Unified quick flow: clarify intent plan implement review and present in a single workflow",implementation_artifacts,"tech spec and project implementation",
+bmm,anytime,Generate Project Context,GPC,,skill:bmad-generate-project-context,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects.",output_folder,"project context",
+bmm,anytime,Quick Dev,QQ,,skill:bmad-quick-dev,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Unified intent-in code-out workflow: clarify plan implement review and present",implementation_artifacts,"spec and project implementation",
 bmm,anytime,Correct Course,CC,,skill:bmad-correct-course,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal",
 bmm,anytime,Write Document,WD,,skill:bmad-agent-tech-writer,,false,tech-writer,,"Describe in detail what you want, and the agent will follow the documentation best practices defined in agent memory. Multi-turn conversation with subprocess for research/review.",project-knowledge,"document",
 bmm,anytime,Update Standards,US,,skill:bmad-agent-tech-writer,,false,tech-writer,,"Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.",_bmad/_memory/tech-writer-sidecar,"standards",
--- a/test/test-installation-components.js
+++ b/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
  // ============================================================
--- a/tools/bmad-npx-wrapper.js
+++ b/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
    });
--- a/tools/cli/installers/lib/core/config-collector.js
+++ b/tools/cli/installers/lib/core/config-collector.js
@ -954,31 +954,123 @@ class ConfigCollector {
        return match;
      }

-      // Look for the config value in allAnswers (already answered questions)
-      let configValue = this.allAnswers[configKey] || this.allAnswers[`core_${configKey}`];
-
-      // Check in already collected config
-      if (!configValue) {
-        for (const mod of Object.keys(this.collectedConfig)) {
-          if (mod !== '_meta' && this.collectedConfig[mod] && this.collectedConfig[mod][configKey]) {
-            configValue = this.collectedConfig[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];
-        if (referencedItem && referencedItem.default !== undefined) {
-          configValue = referencedItem.default;
-        }
-      }
+      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}`];
+
+    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) {
+      for (const mod of Object.keys(this.collectedConfig)) {
+        if (mod !== '_meta' && this.collectedConfig[mod] && this.collectedConfig[mod][configKey]) {
+          configValue = this.collectedConfig[mod][configKey];
+          break;
+        }
+      }
+    }
+
+    // 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];
+      if (referencedItem && referencedItem.default !== undefined) {
+        configValue = referencedItem.default;
+      }
+    }
+
+    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;
+  }
+
  /**
   * Build a prompt question from a config item
   * @param {string} moduleName - Module name
@ -993,12 +1085,7 @@ class ConfigCollector {
    let existingValue = null;
    if (this.existingConfig && this.existingConfig[moduleName]) {
      existingValue = this.existingConfig[moduleName][key];
-
-      // 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}/', '');
-      }
+      existingValue = this.normalizeExistingValueForPrompt(existingValue, moduleName, item, moduleConfig);
    }

    // Special handling for user_name: default to system user
--- a/website/src/content/i18n/zh-CN.json
+++ b/website/src/content/i18n/zh-CN.json
@ -1,5 +1,5 @@
 {
-  "skipLink.label": "跳转到内容",
+  "skipLink.label": "跳到正文",
  "search.label": "搜索",
  "search.ctrlKey": "Ctrl",
  "search.cancelLabel": "取消",
@ -9,20 +9,20 @@
  "themeSelect.auto": "自动",
  "languageSelect.accessibleLabel": "选择语言",
  "menuButton.accessibleLabel": "菜单",
-  "sidebarNav.accessibleLabel": "主导航",
-  "tableOfContents.onThisPage": "本页内容",
-  "tableOfContents.overview": "概述",
-  "i18n.untranslatedContent": "此内容尚未提供中文翻译。",
-  "page.editLink": "编辑页面",
+  "sidebarNav.accessibleLabel": "侧边导航",
+  "tableOfContents.onThisPage": "本页目录",
+  "tableOfContents.overview": "概览",
+  "i18n.untranslatedContent": "这部分内容暂未提供中文版本。",
+  "page.editLink": "编辑此页",
  "page.lastUpdated": "最后更新：",
  "page.previousLink": "上一页",
  "page.nextLink": "下一页",
-  "page.draft": "此内容为草稿，不会包含在正式版本中。",
-  "404.text": "页面未找到。请检查 URL 或尝试使用搜索。",
+  "page.draft": "此内容为草稿，不会出现在正式版本中。",
+  "404.text": "页面未找到。请检查地址，或使用站内搜索。",
  "aside.note": "注意",
  "aside.tip": "提示",
  "aside.caution": "警告",
  "aside.danger": "危险",
-  "fileTree.directory": "目录",
-  "builtWithStarlight.label": "使用 Starlight 构建"
+  "fileTree.directory": "文件夹",
+  "builtWithStarlight.label": "由 Starlight 构建"
 }
Author	SHA1	Message	Date
leon	fe95fda9f6	docs(zh-cn-explanation): normalize admonition syntax 我将 3 篇中文 explanation 文档中的提示块语法统一为仓库约定的 `:::...:::` 形式。此前使用 `::::...::::` 会导致与现有文档规范不一致；现在统一后可减少渲染歧义与后续维护成本。 Feishu: <https://www.feishu.cn/> Made-with: Cursor	2026-03-23 20:00:06 -06:00
leon	b2dbae5ea4	docs(zh-cn-explanation): refine epic3 stories 3.1-3.2 我统一 solutioning、project context 与 established projects 的中文术语和叙述边界，避免 explanation 页面混入 how-to 语气导致误判。我补齐中文优先跳转并更新关键 workflow 命名，使多智能体协作与既有项目 FAQ 的说明更可执行。 feishu: https://feishu.cn/wiki/TODO Made-with: Cursor	2026-03-23 20:00:06 -06:00
梁山河	90d9d880b6	docs(zh-cn): refine story 2.5 and 2.6 how-to guides (#2097 ) * 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>	2026-03-23 19:20:03 -06:00
lif	0c245474c4	fix: use execFileSync to preserve spaces in CLI arguments (#2088 ) Replace execSync with execFileSync in npx wrapper so that argument values containing spaces (e.g. --user-name "CI Bot") are passed as discrete array elements instead of being split by the shell. Fixes #2066 Signed-off-by: majiayu000 <1835304752@qq.com> Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>	2026-03-23 18:28:32 -06:00
Murat K Ozcan	303e7ae290	fix: issue 55 config paths (#2113 ) * fix: issue 55 config paths * Fix: ci test failure	2026-03-23 15:55:19 -05:00
Alex Verkhovsky	48152507e2	fix(quick-dev): remove redundant H1 title from spec template (#2111 ) The frontmatter `title` field is the single source of truth. The duplicate `# {title}` H1 heading was redundant and has been removed. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-23 01:51:53 -06:00
Alex Verkhovsky	b3cf338118	refactor(quick-dev): rename tech-spec prefix to spec (#2109 ) * refactor(quick-dev): rename tech-spec prefix to spec * docs: update tech-spec references to spec	2026-03-23 00:09:05 -06:00
Alex Verkhovsky	fc2b253ab5	fix(quick-dev): preserve tracking identifiers in spec slug derivation (#2108 ) Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-22 23:40:44 -06:00
Alex Verkhovsky	ac5cb9de5c	refactor(quick-dev): replace unconditional artifact scan with intent cascade (#2105 ) Short-circuit evaluation in step-01: explicit argument → conversation context → full artifact scan. Stops prompting as soon as intent is unambiguous. All existing scan behaviors preserved in tier 3. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-22 22:40:04 -06:00
Alex Verkhovsky	980d2904f4	fix(quick-dev): add self-check gate for task completion tracking (#2104 ) Adds a Self-Check subsection at the end of step-03 that forces the implementing agent to verify all tasks are complete and mark checkboxes before handing off to the review step. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-22 16:46:54 -06:00
梁山河	76fb7e067b	docs(zh-cn): refine established project guides (#2096 ) * docs(zh-cn): refine established project guides clarify the boundary between new-project and established-project usage so zh-cn readers can choose the right workflow path. align project context terminology and command references with current conventions while keeping guidance concise and executable. Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): fix project-context syntax and wording 我将 project-context 文档中的提示块语法统一回项目规范的 `:::...:::` 形式，避免与文档风格约定不一致。我同时把“在不同用户故事（story）间决策不一致”调整为“之间决策不一致”，提升中文表达的自然度与可读性。 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>	2026-03-22 10:27:41 -06:00
梁山河	ad2eb0e127	docs(zh-cn): refine install and non-interactive guides (#2094 ) * docs(zh-cn): refine install and non-interactive guides 我统一中文安装文档中的术语和参数说明，补齐预发布安装与 skills 启用提示，并保持交互式与非交互式安装路径和英文源文一致，减少安装场景下的理解偏差。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): align install guide review wording 我在安装指南中补充目录结构示例说明，明确工具相关目录会随所选平台变化，避免读者误以为 .claude/.cursor 一定同时存在。我同时统一非交互式安装文档里残留的“标志”表述为“参数”，让术语在全文保持一致并降低理解成本。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com>	2026-03-22 10:24:31 -06:00
Alex Verkhovsky	7e97b7e7f3	fix(docs): correct skill names in getting-started tutorials (#2103 ) Agent skills referenced with shortened names (bmad-pm, bmad-architect, etc.) that don't match installed skill names. Fixed to use actual names (bmad-agent-pm, bmad-agent-architect, etc.) across EN, ZH-CN, and FR. Also fixed bmad-research to three specific research skills (EN, FR) and bmad-product-brief to bmad-create-product-brief (ZH-CN). Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-22 10:22:29 -06:00
梁山河	ba2a5cc6a0	docs(zh-cn): align getting-started tutorial workflows (#2093 ) * docs(zh-cn): align getting-started tutorial workflows 我按英文源文更新中文入门教程中的命令、工作流和智能体调用方式，并统一步骤叙述与导航语义，减少术语漂移和旧命令误导。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): fix tutorial skill names 我将入门教程阶段 1 中过时或不可用的技能名替换为当前可调用的技能名。此前 `bmad-research` 与 `bmad-create-product-brief` 可能导致新用户执行受阻；现在改为具体研究技能与 `bmad-product-brief`，提升教程可执行性。 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>	2026-03-22 10:09:23 -06:00
梁山河	347f459d5d	docs(zh-cn): refine entry copy and navigation (#2092 ) * docs(zh-cn): refine entry copy and navigation 我统一中文入口层文案语气，减少机翻腔并保持与英文语义一致，让读者从 README、首页到 404 与界面文案都保持同一术语和导航预期。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): align non-interactive install link label 我把 README_CN 中“查看完整安装选项”改为“查看非交互式安装选项”。此前文案范围大于目标页面内容，容易让读者误以为是安装总览；现在文案与链接目标保持一致，减少理解偏差。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com>	2026-03-22 10:08:35 -06:00
梁山河	eb72361720	docs(zh-cn): refine help and quick-fixes guides (#2095 ) * docs(zh-cn): refine help and quick-fixes guides improve zh-cn troubleshooting guidance so users can quickly choose the right support path and self-recover from common issues. align bmad-help and quick-dev usage wording with current invocation conventions and remove glossary-style appendices to keep the pages action-oriented. Feishu: N/A Made-with: Cursor * docs(zh-cn): fix tip admonition fence syntax 我把 get-answers-about-bmad 文档中的 `::::tip` 语法改为仓库统一使用的 `:::tip`。此前四冒号写法与项目文档约定不一致，可能导致提示块渲染异常；现在与现有 Starlight 写法保持一致。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com>	2026-03-22 10:06:58 -06:00