Merge branch 'main' into refactor/all-is-skills

.claude/skills/bmad-os-review-pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-os-review-pr
-description: Adversarial PR review tool (Raven's Verdict). Cynical deep review transformed into professional engineering findings. Use when user asks to 'review a PR' and provides a PR url or id.
+description: Dual-layer PR review tool (Raven's Verdict). Runs adversarial cynical review and edge case hunter in parallel, merges and deduplicates findings into professional engineering output. Use when user asks to 'review a PR' and provides a PR url or id.
 ---
 
 Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-review-pr/prompts/instructions.md

@@ -93,13 +93,17 @@ gh pr diff {PR_NUMBER} [--repo {REPO}] --name-only | grep -E '\.(png|jpg|jpeg|gi
 
 Store list of binary files to skip. Note them in final output.
 
-## Adversarial Review
+## Review Layers
 
-### 1.1 Run Cynical Review
+**Launch steps 1.1 and 1.2 as parallel subagents.** Both receive the same PR diff and run concurrently. Wait for both to complete before proceeding to step 1.3.
+
+### 1.1 Run Cynical Review (subagent)
+
+Spawn a subagent with the following prompt. Pass the full PR diff as context.
 
 **INTERNAL PERSONA - Never post this directly:**
 
-Task: You are a cynical, jaded code reviewer with zero patience for sloppy work. This PR was submitted by a clueless weasel and you expect to find problems. Find at least five issues to fix or improve in it. Number them. Be skeptical of everything. Ultrathink.
+Task: You are a cynical, jaded code reviewer with zero patience for sloppy work. This PR was submitted by a clueless weasel and you expect to find problems. Find at least five issues to fix or improve in it. Number them. Be skeptical of everything.
 
 Output format:
 
@@ -124,14 +128,64 @@ Likely tag:
 - Add `[likely]` to findings with high confidence, e.g. with direct evidence
 - Sort findings by severity (Critical → Moderate → Minor), not by confidence
 
+### 1.2 Run Edge Case Hunter (subagent)
+
+Spawn a subagent that executes the task defined in `_bmad/core/tasks/review-edge-case-hunter.xml`. Pass the full PR diff as the `content` input. Omit `also_consider` unless the user specified extra focus areas.
+
+The task returns a JSON array of objects, each with: `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`.
+
+**Map each JSON finding to the standard finding format:**
+
+````markdown
+### [NUMBER]. [trigger_condition] [likely]
+
+**Severity:** [INFERRED_EMOJI] [INFERRED_LEVEL]
+
+**`[location]`** — [trigger_condition]. [potential_consequence].
+
+**Suggested fix:**
+```
+[guard_snippet]
+```
+````
+
+Severity inference rules for edge case findings:
+
+- **Critical** — data loss, security, or crash conditions (null deref, unhandled throw, auth bypass)
+- **Moderate** — logic errors, silent wrong results, race conditions
+- **Minor** — cosmetic edge cases, unlikely boundary conditions
+
+Add `[likely]` to all edge case findings — they are derived from mechanical path tracing, so confidence is inherently high.
+
+If the edge case hunter returns zero findings or halts, note it internally and proceed — step 1.1 findings still stand.
+
+### 1.3 Merge and Deduplicate
+
+Combine the findings from step 1.1 (adversarial) and step 1.2 (edge case hunter) into a single list.
+
+**Deduplication rules:**
+
+1. Compare each edge case finding against each adversarial finding
+2. Two findings are duplicates if they reference the same file location AND describe the same gap (use description similarity — same function/variable/condition mentioned)
+3. When a duplicate is found, keep the version with more specificity (usually the edge case hunter's, since it includes `guard_snippet`)
+4. Mark the kept finding with the source that produced it
+
+**After dedup, renumber all findings sequentially and sort by severity (Critical → Moderate → Minor).**
+
+Tag each finding with its source:
+
+- `[Adversarial]` — from step 1.1 only
+- `[Edge Case]` — from step 1.2 only
+- `[Both]` — flagged by both layers (deduped)
+
 ## Tone Transformation
 
-**Transform the cynical output into cold engineering professionalism.**
+**Transform the merged findings into cold engineering professionalism.**
 
 **Transformation rules:**
 
 1. Remove all inflammatory language, insults, assumptions about the author
-2. Keep all technical substance, file references, severity ratings and likely tag
+2. Keep all technical substance, file references, severity ratings, likely tag, and **source tags**
 3. Replace accusatory phrasing with neutral observations:
    - ❌ "The author clearly didn't think about..."
    - ✅ "This implementation may not account for..."
@@ -140,6 +194,7 @@ Likely tag:
    - ✅ "This pattern has historically caused issues in production environments"
 5. Add the suggested fixes.
 6. Keep suggestions actionable and specific
+7. Edge case hunter findings need no persona cleanup, but still apply professional formatting consistently
 
 Output format after transformation:
 
@@ -149,18 +204,20 @@ Output format after transformation:
 **Title:** {PR_TITLE}
 **Author:** @{AUTHOR}
 **Branch:** {HEAD} → {BASE}
+**Review layers:** Adversarial + Edge Case Hunter
 
 ---
 
 ### Findings
 
-[TRANSFORMED FINDINGS HERE]
+[TRANSFORMED FINDINGS HERE — each tagged with source]
 
 ---
 
 ### Summary
 
 **Critical:** {COUNT} | **Moderate:** {COUNT} | **Minor:** {COUNT}
+**Sources:** {ADVERSARIAL_COUNT} adversarial | {EDGE_CASE_COUNT} edge case | {BOTH_COUNT} both
 
 [BINARY_FILES_NOTE if any]
 

.gitignore

@@ -40,6 +40,7 @@ CLAUDE.local.md
 .agents/
 
 z*/
+!docs/zh-cn/
 
 _bmad
 _bmad-output

docs/zh-cn/404.md

@@ -6,4 +6,4 @@ template: splash
 
 您查找的页面不存在或已被移动。
 
-[返回首页](./index_cn.md)
+[返回首页](./index.md)

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

@@ -15,7 +15,7 @@ sidebar:
 - 您希望智能体在每次启动时执行特定操作
 
 :::note[前置条件]
-- 在项目中安装了 BMad（参见[如何安装 BMad](./install-bmad_cn.md)）
+- 在项目中安装了 BMad（参见[如何安装 BMad](./install-bmad.md)）
 - 用于编辑 YAML 文件的文本编辑器
 :::
 

docs/zh-cn/how-to/established-projects.md

@@ -44,7 +44,7 @@ sidebar:
 
 你可以查看和完善生成的文件，或者如果你更喜欢，可以在 `_bmad-output/project-context.md` 手动创建它。
 
-[了解更多关于项目上下文](../explanation/project-context_cn.md)
+[了解更多关于项目上下文](../explanation/project-context.md)
 
 ## 步骤 3：维护高质量项目文档
 
@@ -113,8 +113,8 @@ UX 工作是可选的。决定不取决于你的项目是否有 UX，而取决
 
 ## 更多信息
 
-- **[快速修复](./quick-fixes_cn.md)** - 错误修复和临时变更
-- **[既有项目 FAQ](../explanation/established-projects-faq_cn.md)** - 关于在既有项目上工作的常见问题
+- **[快速修复](./quick-fixes.md)** - 错误修复和临时变更
+- **[既有项目 FAQ](../explanation/established-projects-faq.md)** - 关于在既有项目上工作的常见问题
 
 ---
 ## 术语说明

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

@@ -7,7 +7,7 @@ sidebar:
 
 使用 `npx bmad-method install` 命令在项目中设置 BMad，并选择你需要的模块和 AI 工具。
 
-如果你想使用非交互式安装程序并在命令行中提供所有安装选项，请参阅[本指南](./non-interactive-installation_cn.md)。
+如果你想使用非交互式安装程序并在命令行中提供所有安装选项，请参阅[本指南](./non-interactive-installation.md)。
 
 ## 何时使用
 
@@ -94,7 +94,7 @@ your-project/
 
 **安装程序抛出错误**——将输出复制粘贴到你的 AI 助手中，让它来解决问题。
 
-**安装程序工作正常但后续出现问题**——你的 AI 需要 BMad 上下文才能提供帮助。请参阅[如何获取关于 BMad 的答案](./get-answers-about-bmad_cn.md)了解如何将你的 AI 指向正确的来源。
+**安装程序工作正常但后续出现问题**——你的 AI 需要 BMad 上下文才能提供帮助。请参阅[如何获取关于 BMad 的答案](./get-answers-about-bmad.md)了解如何将你的 AI 指向正确的来源。
 
 ---
 ## 术语说明

docs/zh-cn/how-to/project-context.md

@@ -132,8 +132,8 @@ sections_completed: ['technology_stack', 'critical_rules']
 
 ## 后续步骤
 
-- [**项目上下文说明**](../explanation/project-context_cn.md) — 了解其工作原理
-- [**工作流程图**](../reference/workflow-map_cn.md) — 查看哪些工作流程加载项目上下文
+- [**项目上下文说明**](../explanation/project-context.md) — 了解其工作原理
+- [**工作流程图**](../reference/workflow-map.md) — 查看哪些工作流程加载项目上下文
 
 ---
 ## 术语说明

docs/zh-cn/how-to/quick-fixes.md

@@ -115,7 +115,7 @@ DEV 智能体也适用于探索不熟悉的代码。在新的聊天中加载它
 
 ## 何时升级到正式规划
 
-在以下情况下考虑使用 [Quick Flow](../explanation/quick-flow_cn.md) 或完整的 BMad Method：
+在以下情况下考虑使用 [Quick Flow](../explanation/quick-flow.md) 或完整的 BMad Method：
 
 - 更改影响多个系统或需要在许多文件中进行协调更新
 - 你不确定范围，需要规范来理清思路

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

@@ -22,7 +22,7 @@ sidebar:
 
 ### 1. 运行安装程序
 
-按照[安装程序说明](./install-bmad_cn.md)操作。
+按照[安装程序说明](./install-bmad.md)操作。
 
 ### 2. 处理旧版安装
 

docs/zh-cn/index.md

@@ -15,8 +15,8 @@ BMad 方法（**B**reakthrough **M**ethod of **A**gile AI **D**riven Development
 
 理解 BMad 的最快方式是亲自尝试。
 
-- **[BMad 入门指南](./tutorials/getting-started_cn.md)** — 安装并了解 BMad 的工作原理
-- **[工作流地图](./reference/workflow-map_cn.md)** — BMM 阶段、工作流和上下文管理的可视化概览
+- **[BMad 入门指南](./tutorials/getting-started.md)** — 安装并了解 BMad 的工作原理
+- **[工作流地图](./reference/workflow-map.md)** — BMM 阶段、工作流和上下文管理的可视化概览
 
 :::tip[只想直接上手？]
 安装 BMad 并运行 `/bmad-help` — 它会根据您的项目和已安装的模块引导您完成所有操作。
@@ -57,7 +57,7 @@ BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码
 
 ## 下一步
 
-准备开始了吗？**[BMad 入门指南](./tutorials/getting-started_cn.md)** 并构建您的第一个项目。
+准备开始了吗？**[BMad 入门指南](./tutorials/getting-started.md)** 并构建您的第一个项目。
 
 ---
 ## 术语说明

docs/zh-cn/reference/commands.md

@@ -83,7 +83,7 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
 | `/bmad-agent-bmm-architect` | Winston（架构师） | 设计系统架构 |
 | `/bmad-agent-bmm-sm` | Bob（Scrum Master） | 管理冲刺和故事 |
 
-参见[智能体](./agents_cn.md)获取默认智能体及其触发器的完整列表。
+参见[智能体](./agents.md)获取默认智能体及其触发器的完整列表。
 
 ### 工作流命令
 
@@ -97,7 +97,7 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
 | `/bmad-bmm-code-review` | 运行代码审查 |
 | `/bmad-bmm-quick-spec` | 定义临时更改（快速流程） |
 
-参见[工作流地图](./workflow-map_cn.md)获取按阶段组织的完整工作流参考。
+参见[工作流地图](./workflow-map.md)获取按阶段组织的完整工作流参考。
 
 ### 任务和工具命令
 
@@ -140,7 +140,7 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
 | `bmad-<module>-<workflow>` | 工作流命令 | `bmad-bmm-create-prd` |
 | `bmad-<name>` | 核心任务或工具 | `bmad-help` |
 
-模块代码：`bmm`（敏捷套件）、`bmb`（构建器）、`tea`（测试架构师）、`cis`（创意智能）、`gds`（游戏开发工作室）。参见[模块](./modules_cn.md)获取描述。
+模块代码：`bmm`（敏捷套件）、`bmb`（构建器）、`tea`（测试架构师）、`cis`（创意智能）、`gds`（游戏开发工作室）。参见[模块](./modules.md)获取描述。
 
 ## 故障排除
 

docs/zh-cn/reference/testing.md

@@ -103,7 +103,7 @@ Quinn 的 Automate 工作流出现在 BMad 方法工作流图的第 4 阶段（
 
 Quinn 直接从源代码工作，无需加载规划文档（PRD、架构）。TEA 工作流可以与上游规划产物集成以实现可追溯性。
 
-有关测试在整体流程中的位置，请参阅[工作流图](./workflow-map_cn.md)。
+有关测试在整体流程中的位置，请参阅[工作流图](./workflow-map.md)。
 
 ---
 ## 术语说明

docs/zh-cn/reference/workflow-map.md

@@ -86,7 +86,7 @@ BMad Method（BMM）是 BMad 生态系统中的一个模块，旨在遵循上下
 - **手动** — 使用您的技术栈和实施规则创建 `_bmad-output/project-context.md`
 - **生成它** — 运行 `/bmad-bmm-generate-project-context` 以从您的架构或代码库自动生成
 
-[**了解更多关于 project-context.md**](../explanation/project-context_cn.md)
+[**了解更多关于 project-context.md**](../explanation/project-context.md)
 
 ---
 ## 术语说明

docs/zh-cn/tutorials/getting-started.md

@@ -73,7 +73,7 @@ BMad 通过带有专门 AI 智能体的引导工作流帮助你构建软件。
 | 3    | 解决方案设计   | 设计架构 *（仅限 BMad Method/Enterprise only）*         |
 | 4    | 实现           | 逐个史诗、逐个故事地构建                           |
 
-**[打开工作流地图](../reference/workflow-map_cn.md)** 以探索阶段、工作流和上下文管理。
+**[打开工作流地图](../reference/workflow-map.md)** 以探索阶段、工作流和上下文管理。
 
 根据项目的复杂性，BMad 提供三种规划路径：
 
@@ -126,7 +126,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么
 :::tip[项目上下文（可选）]
 在开始之前，考虑创建 `project-context.md` 来记录你的技术偏好和实现规则。这确保所有 AI 智能体在整个项目中遵循你的约定。
 
-在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `/bmad-bmm-generate-project-context` 生成它。[了解更多](../explanation/project-context_cn.md)。
+在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `/bmad-bmm-generate-project-context` 生成它。[了解更多](../explanation/project-context.md)。
 :::
 
 ### 阶段 1：分析（可选）

src/bmm/workflows/4-implementation/code-review/instructions.xml

@@ -195,12 +195,14 @@
 
       <check if="{{new_status}} == 'done'">
         <action>Update development_status[{{story_key}}] = "done"</action>
+        <action>Update last_updated field to current date</action>
         <action>Save file, preserving ALL comments and structure</action>
         <output>✅ Sprint status synced: {{story_key}} → done</output>
       </check>
 
       <check if="{{new_status}} == 'in-progress'">
         <action>Update development_status[{{story_key}}] = "in-progress"</action>
+        <action>Update last_updated field to current date</action>
         <action>Save file, preserving ALL comments and structure</action>
         <output>🔄 Sprint status synced: {{story_key}} → in-progress</output>
       </check>

src/bmm/workflows/4-implementation/create-story/instructions.xml

@@ -311,7 +311,7 @@
   </step>
 
   <step n="6" goal="Update sprint status and finalize">
-    <invoke-task>Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <action>Validate the newly created story file {story_file} against {installed_path}/checklist.md and apply any required fixes before finalizing</action>
     <action>Save story document unconditionally</action>
 
     <!-- Update sprint status -->
@@ -321,6 +321,7 @@
       <action>Find development_status key matching {{story_key}}</action>
       <action>Verify current status is "backlog" (expected previous state)</action>
       <action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+      <action>Update last_updated field to current date</action>
       <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
     </check>
 

src/bmm/workflows/4-implementation/dev-story/instructions.xml

@@ -195,6 +195,7 @@
 
       <check if="current status == 'ready-for-dev' OR review_continuation == true">
         <action>Update the story in the sprint status report to = "in-progress"</action>
+        <action>Update last_updated field to current date</action>
         <output>🚀 Starting work on story {{story_key}}
           Status updated: ready-for-dev → in-progress
         </output>
@@ -348,6 +349,7 @@
       <action>Find development_status key matching {{story_key}}</action>
       <action>Verify current status is "in-progress" (expected previous state)</action>
       <action>Update development_status[{{story_key}}] = "review"</action>
+      <action>Update last_updated field to current date</action>
       <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
       <output>✅ Story status updated to "review" in sprint-status.yaml</output>
     </check>

src/bmm/workflows/4-implementation/retrospective/instructions.md

@@ -1336,6 +1336,7 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!"
 <action>Find development_status key "epic-{{epic_number}}-retrospective"</action>
 <action>Verify current status (typically "optional" or "pending")</action>
 <action>Update development_status["epic-{{epic_number}}-retrospective"] = "done"</action>
+<action>Update last_updated field to current date</action>
 <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
 <check if="update successful">

src/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -95,6 +95,7 @@ development_status:
 
 ```yaml
 # generated: {date}
+# last_updated: {date}
 # project: {project_name}
 # project_key: {project_key}
 # tracking_system: {tracking_system}
@@ -130,6 +131,7 @@ development_status:
 # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
 
 generated: { date }
+last_updated: { date }
 project: { project_name }
 project_key: { project_key }
 tracking_system: { tracking_system }

src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml

@@ -35,6 +35,7 @@
 # EXAMPLE STRUCTURE (your actual epics/stories will replace these):
 
 generated: 05-06-2-2025 21:30
+last_updated: 05-06-2-2025 21:30
 project: My Awesome Project
 project_key: NOKEY
 tracking_system: file-system

src/bmm/workflows/4-implementation/sprint-status/instructions.md

@@ -36,7 +36,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat
 
 <step n="2" goal="Read and parse sprint-status.yaml">
   <action>Read the FULL file: {sprint_status_file}</action>
-  <action>Parse fields: generated, project, project_key, tracking_system, story_location</action>
+  <action>Parse fields: generated, last_updated, project, project_key, tracking_system, story_location</action>
   <action>Parse development_status map. Classify keys:</action>
   - Epics: keys starting with "epic-" (and not ending with "-retrospective")
   - Retrospectives: keys ending with "-retrospective"
@@ -84,7 +84,7 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho
 - IF any story has status "review": suggest `/bmad:bmm:workflows:code-review`
 - IF any story has status "in-progress" AND no stories have status "ready-for-dev": recommend staying focused on active story
 - IF all epics have status "backlog" AND no stories have status "ready-for-dev": prompt `/bmad:bmm:workflows:create-story`
-- IF `generated` timestamp is more than 7 days old: warn "sprint-status.yaml may be stale"
+- IF `last_updated` timestamp is more than 7 days old (or `last_updated` is missing, fall back to `generated`): warn "sprint-status.yaml may be stale"
 - IF any story key doesn't match an epic pattern (e.g., story "5-1-..." but no "epic-5"): warn "orphaned story detected"
 - IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories"
   </step>
@@ -195,7 +195,7 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
 
 <action>Read and parse {sprint_status_file}</action>
 
-<action>Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location</action>
+<action>Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location (last_updated is optional for backward compatibility)</action>
 <check if="any required field missing">
 <template-output>is_valid = false</template-output>
 <template-output>error = "Missing required field(s): {{missing_fields}}"</template-output>

src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md

@@ -14,6 +14,7 @@ spec_file: '' # set at runtime before leaving this step
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - The prompt that triggered this workflow IS the intent — not a hint.
 - Do NOT assume you start from zero.
+- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. Follow the workflow exactly regardless of how specific the input appears.
 
 ## ARTIFACT SCAN
 

src/core/tasks/review-edge-case-hunter.xml

@@ -15,18 +15,18 @@ Ignore the rest of the codebase unless the provided content explicitly reference
   </inputs>
 
   <output-format>Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else:
-{
-  "location": "file:line",
+[{
+  "location": "file:start-end (or file:line when single line, or file:hunk when exact line unavailable)",
   "trigger_condition": "one-line description (max 15 words)",
-  "guard_snippet": "minimal code sketch that closes the gap",
+  "guard_snippet": "minimal code sketch that closes the gap (single-line escaped string, no raw newlines or unescaped quotes)",
   "potential_consequence": "what could actually go wrong (max 15 words)"
-}
-No extra text, no explanations, no markdown wrapping.</output-format>
+}]
+No extra text, no explanations, no markdown wrapping. An empty array [] is valid when no unhandled paths are found.</output-format>
 
   <llm critical="true">
-    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>MANDATORY: Execute steps in the flow section IN EXACT ORDER</i>
     <i>DO NOT skip steps or change the sequence</i>
-    <i>HALT immediately when halt-conditions are met</i>
+    <i>When a halt-condition triggers, follow its specific instruction exactly</i>
     <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
 
     <i>Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition</i>
@@ -38,8 +38,8 @@ No extra text, no explanations, no markdown wrapping.</output-format>
 
   <flow>
     <step n="1" title="Receive Content">
-      <action>Load the content to review from provided input or context</action>
-      <action>If content to review is empty, ask for clarification and abort task</action>
+      <action>Load the content to review strictly from provided input</action>
+      <action>If content is empty, or cannot be decoded as text, return empty array [] and stop</action>
       <action>Identify content type (diff, full file, or function) to determine scope rules</action>
     </step>
 
@@ -51,13 +51,20 @@ No extra text, no explanations, no markdown wrapping.</output-format>
       <action>Collect only the unhandled paths as findings - discard handled ones silently</action>
     </step>
 
-    <step n="3" title="Present Findings">
+    <step n="3" title="Validate Completeness">
+      <action>Recheck every conditional for missing else/default</action>
+      <action>Recheck every input for null/empty/wrong-type</action>
+      <action>Recheck loop bounds for off-by-one and empty-collection</action>
+      <action>Add any newly found unhandled paths to findings; discard confirmed-handled ones</action>
+    </step>
+
+    <step n="4" title="Present Findings">
       <action>Output findings as a JSON array following the output-format specification exactly</action>
     </step>
   </flow>
 
   <halt-conditions>
-    <condition>HALT if content is empty or unreadable</condition>
+    <condition>If content is empty or cannot be decoded as text, return empty array [] and stop</condition>
   </halt-conditions>
 
 </task>

website/astro.config.mjs

@@ -36,11 +36,28 @@ export default defineConfig({
   },
 
   integrations: [
-    sitemap(),
+    // Exclude custom 404 pages (all locales) from the sitemap — they are
+    // treated as normal content docs by Starlight even with disable404Route.
+    sitemap({
+      filter: (page) => !/\/404(\/|$)/.test(new URL(page).pathname),
+    }),
     starlight({
       title: 'BMAD Method',
       tagline: 'AI-driven agile development with specialized agents and workflows that scale from bug fixes to enterprise platforms.',
 
+      // i18n: English as root (no URL prefix), Chinese at /zh-cn/
+      defaultLocale: 'root',
+      locales: {
+        root: {
+          label: 'English',
+          lang: 'en',
+        },
+        'zh-cn': {
+          label: '简体中文',
+          lang: 'zh-CN',
+        },
+      },
+
       logo: {
         light: './public/img/bmad-light.png',
         dark: './public/img/bmad-dark.png',
@@ -89,25 +106,29 @@ export default defineConfig({
 
       // Sidebar configuration (Diataxis structure)
       sidebar: [
-        { label: 'Welcome', slug: 'index' },
-        { label: 'Roadmap', slug: 'roadmap' },
+        { label: 'Welcome', translations: { 'zh-CN': '欢迎' }, slug: 'index' },
+        { label: 'Roadmap', translations: { 'zh-CN': '路线图' }, slug: 'roadmap' },
         {
           label: 'Tutorials',
+          translations: { 'zh-CN': '教程' },
           collapsed: false,
           autogenerate: { directory: 'tutorials' },
         },
         {
           label: 'How-To Guides',
+          translations: { 'zh-CN': '操作指南' },
           collapsed: true,
           autogenerate: { directory: 'how-to' },
         },
         {
           label: 'Explanation',
+          translations: { 'zh-CN': '概念说明' },
           collapsed: true,
           autogenerate: { directory: 'explanation' },
         },
         {
           label: 'Reference',
+          translations: { 'zh-CN': '参考' },
           collapsed: true,
           autogenerate: { directory: 'reference' },
         },

website/src/content/config.ts

@@ -1,6 +1,7 @@
 import { defineCollection } from 'astro:content';
-import { docsSchema } from '@astrojs/starlight/schema';
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
 
 export const collections = {
   docs: defineCollection({ schema: docsSchema() }),
+  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
 };

website/src/content/i18n/zh-CN.json

@@ -0,0 +1,28 @@
+{
+  "skipLink.label": "跳转到内容",
+  "search.label": "搜索",
+  "search.ctrlKey": "Ctrl",
+  "search.cancelLabel": "取消",
+  "themeSelect.accessibleLabel": "选择主题",
+  "themeSelect.dark": "深色",
+  "themeSelect.light": "浅色",
+  "themeSelect.auto": "自动",
+  "languageSelect.accessibleLabel": "选择语言",
+  "menuButton.accessibleLabel": "菜单",
+  "sidebarNav.accessibleLabel": "主导航",
+  "tableOfContents.onThisPage": "本页内容",
+  "tableOfContents.overview": "概述",
+  "i18n.untranslatedContent": "此内容尚未提供中文翻译。",
+  "page.editLink": "编辑页面",
+  "page.lastUpdated": "最后更新：",
+  "page.previousLink": "上一页",
+  "page.nextLink": "下一页",
+  "page.draft": "此内容为草稿，不会包含在正式版本中。",
+  "404.text": "页面未找到。请检查 URL 或尝试使用搜索。",
+  "aside.note": "注意",
+  "aside.tip": "提示",
+  "aside.caution": "警告",
+  "aside.danger": "危险",
+  "fileTree.directory": "目录",
+  "builtWithStarlight.label": "使用 Starlight 构建"
+}