From f7846fd5ebd2aa81c7c79c0b3a327c56988d6abf Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Fri, 6 Mar 2026 19:21:28 -0700 Subject: [PATCH 1/5] feat(skills): add edge case hunter as parallel review layer in PR review (#1791) * feat(skills): add edge case hunter as parallel review layer in PR review Wire review-edge-case-hunter.xml into bmad-os-review-pr as a second review layer running in parallel with the adversarial review. Both subagents receive the same PR diff concurrently. Findings are merged, deduplicated, and tagged by source before tone transformation. * fix(core): resolve contradictions in edge case hunter task spec - Show array wrapper [{}] in output-format example to match JSON array contract, and document empty array [] as valid output - Consolidate empty-content handling: step 1 now defers to halt-conditions instead of defining separate "ask and abort" behavior - Zero-findings halt no longer contradicts JSON contract: re-analyze once, then return [] instead of ambiguous "HALT or re-analyze" - Soften "Execute ALL steps" to acknowledge halt-conditions can interrupt * fix(review): address PR #1791 review feedback - Remove "Task tool" reference per maintainer; use generic "subagents" - Fix nested triple-backtick fencing with four-tick outer fence - Widen location format to support multi-line ranges and hunk refs - Add JSON-safety constraint to guard_snippet field - Tighten input loading to "strictly from provided input" - Replace vague "unreadable" with "cannot be decoded as text" - Replace vague "increased scrutiny" with concrete re-analysis checklist - Resolve HALT-immediately vs re-analysis conflict in LLM instructions Co-Authored-By: Claude Opus 4.6 --------- Co-authored-by: Claude Opus 4.6 --- .claude/skills/bmad-os-review-pr/SKILL.md | 2 +- .../bmad-os-review-pr/prompts/instructions.md | 69 +++++++++++++++++-- src/core/tasks/review-edge-case-hunter.xml | 29 +++++--- 3 files changed, 82 insertions(+), 18 deletions(-) diff --git a/.claude/skills/bmad-os-review-pr/SKILL.md b/.claude/skills/bmad-os-review-pr/SKILL.md index 67bb05bd5..8adc6d031 100644 --- a/.claude/skills/bmad-os-review-pr/SKILL.md +++ b/.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. diff --git a/.claude/skills/bmad-os-review-pr/prompts/instructions.md b/.claude/skills/bmad-os-review-pr/prompts/instructions.md index 12d150049..74512128e 100644 --- a/.claude/skills/bmad-os-review-pr/prompts/instructions.md +++ b/.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] diff --git a/src/core/tasks/review-edge-case-hunter.xml b/src/core/tasks/review-edge-case-hunter.xml index f312e1b2e..dfe75ce34 100644 --- a/src/core/tasks/review-edge-case-hunter.xml +++ b/src/core/tasks/review-edge-case-hunter.xml @@ -15,18 +15,18 @@ Ignore the rest of the codebase unless the provided content explicitly reference 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. +}] +No extra text, no explanations, no markdown wrapping. An empty array [] is valid when no unhandled paths are found. - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER + MANDATORY: Execute steps in the flow section IN EXACT ORDER DO NOT skip steps or change the sequence - HALT immediately when halt-conditions are met + When a halt-condition triggers, follow its specific instruction exactly Each action xml tag within step xml tag is a REQUIRED action to complete that step Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition @@ -38,8 +38,8 @@ No extra text, no explanations, no markdown wrapping. - Load the content to review from provided input or context - If content to review is empty, ask for clarification and abort task + Load the content to review strictly from provided input + If content is empty, or cannot be decoded as text, return empty array [] and stop Identify content type (diff, full file, or function) to determine scope rules @@ -51,13 +51,20 @@ No extra text, no explanations, no markdown wrapping. Collect only the unhandled paths as findings - discard handled ones silently - + + Recheck every conditional for missing else/default + Recheck every input for null/empty/wrong-type + Recheck loop bounds for off-by-one and empty-collection + Add any newly found unhandled paths to findings; discard confirmed-handled ones + + + Output findings as a JSON array following the output-format specification exactly - HALT if content is empty or unreadable + If content is empty or cannot be decoded as text, return empty array [] and stop From ed76f57a192d22a2b219deed973be6331a53fc9c Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Fri, 6 Mar 2026 19:21:43 -0700 Subject: [PATCH 2/5] feat(i18n): add zh-CN locale support (#1822) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(i18n): add zh-cn locale support with Starlight routing Reorganize Chinese translations from docs_cn/ into docs/zh-cn/ following Starlight's i18n content structure. Configure Starlight with root locale (en, unprefixed) and zh-cn (/zh-cn/ prefix). - Move 28 files from docs_cn/*_cn.md to docs/zh-cn/*.md - Fix 21 internal links to remove _cn suffixes - Add defaultLocale + locales config to astro.config.mjs - Add .gitignore exception for docs/zh-cn/ (overrides z*/ rule) - Language switcher activates automatically via existing Header - hreflang tags auto-generated by Starlight on all pages * feat(i18n): add zh-CN UI translations and sidebar labels - Add website/src/content/i18n/zh-CN.json with Starlight UI strings - Add sidebar group label translations (欢迎, 路线图, 教程, etc.) - Register i18n collection in content config to fix deprecation warning * fix(i18n): exclude 404 pages from sitemap Custom 404 pages (root and zh-cn) were indexed as regular content in the sitemap. Add a filter to the @astrojs/sitemap integration that matches the /404 path segment precisely via regex on the URL pathname. --- .gitignore | 1 + docs_cn/404_cn.md => docs/zh-cn/404.md | 2 +- {docs_cn => docs/zh-cn}/_STYLE_GUIDE.md | 0 .../zh-cn/explanation/advanced-elicitation.md | 0 .../zh-cn/explanation/adversarial-review.md | 0 .../zh-cn/explanation/brainstorming.md | 0 .../explanation/established-projects-faq.md | 0 .../zh-cn/explanation/party-mode.md | 0 .../explanation/preventing-agent-conflicts.md | 0 .../zh-cn/explanation/project-context.md | 0 .../zh-cn/explanation/quick-flow.md | 0 .../explanation/why-solutioning-matters.md | 0 .../zh-cn/how-to/customize-bmad.md | 2 +- .../zh-cn/how-to/established-projects.md | 6 ++-- .../zh-cn/how-to/get-answers-about-bmad.md | 0 .../zh-cn/how-to/install-bmad.md | 4 +-- .../how-to/non-interactive-installation.md | 0 .../zh-cn/how-to/project-context.md | 4 +-- .../zh-cn/how-to/quick-fixes.md | 2 +- .../zh-cn/how-to/shard-large-documents.md | 0 .../zh-cn/how-to/upgrade-to-v6.md | 2 +- docs_cn/index_cn.md => docs/zh-cn/index.md | 6 ++-- .../zh-cn/reference/agents.md | 0 .../zh-cn/reference/commands.md | 6 ++-- .../zh-cn/reference/modules.md | 0 .../zh-cn/reference/testing.md | 2 +- .../zh-cn/reference/workflow-map.md | 2 +- .../roadmap_cn.mdx => docs/zh-cn/roadmap.mdx | 0 .../zh-cn/tutorials/getting-started.md | 4 +-- website/astro.config.mjs | 27 ++++++++++++++++-- website/src/content/config.ts | 3 +- website/src/content/i18n/zh-CN.json | 28 +++++++++++++++++++ 32 files changed, 76 insertions(+), 25 deletions(-) rename docs_cn/404_cn.md => docs/zh-cn/404.md (76%) rename {docs_cn => docs/zh-cn}/_STYLE_GUIDE.md (100%) rename docs_cn/explanation/advanced-elicitation_cn.md => docs/zh-cn/explanation/advanced-elicitation.md (100%) rename docs_cn/explanation/adversarial-review_cn.md => docs/zh-cn/explanation/adversarial-review.md (100%) rename docs_cn/explanation/brainstorming_cn.md => docs/zh-cn/explanation/brainstorming.md (100%) rename docs_cn/explanation/established-projects-faq_cn.md => docs/zh-cn/explanation/established-projects-faq.md (100%) rename docs_cn/explanation/party-mode_cn.md => docs/zh-cn/explanation/party-mode.md (100%) rename docs_cn/explanation/preventing-agent-conflicts_cn.md => docs/zh-cn/explanation/preventing-agent-conflicts.md (100%) rename docs_cn/explanation/project-context_cn.md => docs/zh-cn/explanation/project-context.md (100%) rename docs_cn/explanation/quick-flow_cn.md => docs/zh-cn/explanation/quick-flow.md (100%) rename docs_cn/explanation/why-solutioning-matters_cn.md => docs/zh-cn/explanation/why-solutioning-matters.md (100%) rename docs_cn/how-to/customize-bmad_cn.md => docs/zh-cn/how-to/customize-bmad.md (99%) rename docs_cn/how-to/established-projects_cn.md => docs/zh-cn/how-to/established-projects.md (96%) rename docs_cn/how-to/get-answers-about-bmad_cn.md => docs/zh-cn/how-to/get-answers-about-bmad.md (100%) rename docs_cn/how-to/install-bmad_cn.md => docs/zh-cn/how-to/install-bmad.md (96%) rename docs_cn/how-to/non-interactive-installation_cn.md => docs/zh-cn/how-to/non-interactive-installation.md (100%) rename docs_cn/how-to/project-context_cn.md => docs/zh-cn/how-to/project-context.md (95%) rename docs_cn/how-to/quick-fixes_cn.md => docs/zh-cn/how-to/quick-fixes.md (99%) rename docs_cn/how-to/shard-large-documents_cn.md => docs/zh-cn/how-to/shard-large-documents.md (100%) rename docs_cn/how-to/upgrade-to-v6_cn.md => docs/zh-cn/how-to/upgrade-to-v6.md (98%) rename docs_cn/index_cn.md => docs/zh-cn/index.md (93%) rename docs_cn/reference/agents_cn.md => docs/zh-cn/reference/agents.md (100%) rename docs_cn/reference/commands_cn.md => docs/zh-cn/reference/commands.md (96%) rename docs_cn/reference/modules_cn.md => docs/zh-cn/reference/modules.md (100%) rename docs_cn/reference/testing_cn.md => docs/zh-cn/reference/testing.md (99%) rename docs_cn/reference/workflow-map_cn.md => docs/zh-cn/reference/workflow-map.md (99%) rename docs_cn/roadmap_cn.mdx => docs/zh-cn/roadmap.mdx (100%) rename docs_cn/tutorials/getting-started_cn.md => docs/zh-cn/tutorials/getting-started.md (98%) create mode 100644 website/src/content/i18n/zh-CN.json diff --git a/.gitignore b/.gitignore index a1229c93d..99f1b1ad7 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,7 @@ CLAUDE.local.md .agents/ z*/ +!docs/zh-cn/ _bmad _bmad-output diff --git a/docs_cn/404_cn.md b/docs/zh-cn/404.md similarity index 76% rename from docs_cn/404_cn.md rename to docs/zh-cn/404.md index a417d2e00..bb835ceea 100644 --- a/docs_cn/404_cn.md +++ b/docs/zh-cn/404.md @@ -6,4 +6,4 @@ template: splash 您查找的页面不存在或已被移动。 -[返回首页](./index_cn.md) +[返回首页](./index.md) diff --git a/docs_cn/_STYLE_GUIDE.md b/docs/zh-cn/_STYLE_GUIDE.md similarity index 100% rename from docs_cn/_STYLE_GUIDE.md rename to docs/zh-cn/_STYLE_GUIDE.md diff --git a/docs_cn/explanation/advanced-elicitation_cn.md b/docs/zh-cn/explanation/advanced-elicitation.md similarity index 100% rename from docs_cn/explanation/advanced-elicitation_cn.md rename to docs/zh-cn/explanation/advanced-elicitation.md diff --git a/docs_cn/explanation/adversarial-review_cn.md b/docs/zh-cn/explanation/adversarial-review.md similarity index 100% rename from docs_cn/explanation/adversarial-review_cn.md rename to docs/zh-cn/explanation/adversarial-review.md diff --git a/docs_cn/explanation/brainstorming_cn.md b/docs/zh-cn/explanation/brainstorming.md similarity index 100% rename from docs_cn/explanation/brainstorming_cn.md rename to docs/zh-cn/explanation/brainstorming.md diff --git a/docs_cn/explanation/established-projects-faq_cn.md b/docs/zh-cn/explanation/established-projects-faq.md similarity index 100% rename from docs_cn/explanation/established-projects-faq_cn.md rename to docs/zh-cn/explanation/established-projects-faq.md diff --git a/docs_cn/explanation/party-mode_cn.md b/docs/zh-cn/explanation/party-mode.md similarity index 100% rename from docs_cn/explanation/party-mode_cn.md rename to docs/zh-cn/explanation/party-mode.md diff --git a/docs_cn/explanation/preventing-agent-conflicts_cn.md b/docs/zh-cn/explanation/preventing-agent-conflicts.md similarity index 100% rename from docs_cn/explanation/preventing-agent-conflicts_cn.md rename to docs/zh-cn/explanation/preventing-agent-conflicts.md diff --git a/docs_cn/explanation/project-context_cn.md b/docs/zh-cn/explanation/project-context.md similarity index 100% rename from docs_cn/explanation/project-context_cn.md rename to docs/zh-cn/explanation/project-context.md diff --git a/docs_cn/explanation/quick-flow_cn.md b/docs/zh-cn/explanation/quick-flow.md similarity index 100% rename from docs_cn/explanation/quick-flow_cn.md rename to docs/zh-cn/explanation/quick-flow.md diff --git a/docs_cn/explanation/why-solutioning-matters_cn.md b/docs/zh-cn/explanation/why-solutioning-matters.md similarity index 100% rename from docs_cn/explanation/why-solutioning-matters_cn.md rename to docs/zh-cn/explanation/why-solutioning-matters.md diff --git a/docs_cn/how-to/customize-bmad_cn.md b/docs/zh-cn/how-to/customize-bmad.md similarity index 99% rename from docs_cn/how-to/customize-bmad_cn.md rename to docs/zh-cn/how-to/customize-bmad.md index b131579f9..55396ac6e 100644 --- a/docs_cn/how-to/customize-bmad_cn.md +++ b/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 文件的文本编辑器 ::: diff --git a/docs_cn/how-to/established-projects_cn.md b/docs/zh-cn/how-to/established-projects.md similarity index 96% rename from docs_cn/how-to/established-projects_cn.md rename to docs/zh-cn/how-to/established-projects.md index 86e472891..ec7b9d787 100644 --- a/docs_cn/how-to/established-projects_cn.md +++ b/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)** - 关于在既有项目上工作的常见问题 --- ## 术语说明 diff --git a/docs_cn/how-to/get-answers-about-bmad_cn.md b/docs/zh-cn/how-to/get-answers-about-bmad.md similarity index 100% rename from docs_cn/how-to/get-answers-about-bmad_cn.md rename to docs/zh-cn/how-to/get-answers-about-bmad.md diff --git a/docs_cn/how-to/install-bmad_cn.md b/docs/zh-cn/how-to/install-bmad.md similarity index 96% rename from docs_cn/how-to/install-bmad_cn.md rename to docs/zh-cn/how-to/install-bmad.md index 1b2c8f101..f0e2d436c 100644 --- a/docs_cn/how-to/install-bmad_cn.md +++ b/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 指向正确的来源。 --- ## 术语说明 diff --git a/docs_cn/how-to/non-interactive-installation_cn.md b/docs/zh-cn/how-to/non-interactive-installation.md similarity index 100% rename from docs_cn/how-to/non-interactive-installation_cn.md rename to docs/zh-cn/how-to/non-interactive-installation.md diff --git a/docs_cn/how-to/project-context_cn.md b/docs/zh-cn/how-to/project-context.md similarity index 95% rename from docs_cn/how-to/project-context_cn.md rename to docs/zh-cn/how-to/project-context.md index d1cf8dfce..89ce6af15 100644 --- a/docs_cn/how-to/project-context_cn.md +++ b/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) — 查看哪些工作流程加载项目上下文 --- ## 术语说明 diff --git a/docs_cn/how-to/quick-fixes_cn.md b/docs/zh-cn/how-to/quick-fixes.md similarity index 99% rename from docs_cn/how-to/quick-fixes_cn.md rename to docs/zh-cn/how-to/quick-fixes.md index 89bc9d69d..166a10a50 100644 --- a/docs_cn/how-to/quick-fixes_cn.md +++ b/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： - 更改影响多个系统或需要在许多文件中进行协调更新 - 你不确定范围，需要规范来理清思路 diff --git a/docs_cn/how-to/shard-large-documents_cn.md b/docs/zh-cn/how-to/shard-large-documents.md similarity index 100% rename from docs_cn/how-to/shard-large-documents_cn.md rename to docs/zh-cn/how-to/shard-large-documents.md diff --git a/docs_cn/how-to/upgrade-to-v6_cn.md b/docs/zh-cn/how-to/upgrade-to-v6.md similarity index 98% rename from docs_cn/how-to/upgrade-to-v6_cn.md rename to docs/zh-cn/how-to/upgrade-to-v6.md index 616a928f2..b833d360c 100644 --- a/docs_cn/how-to/upgrade-to-v6_cn.md +++ b/docs/zh-cn/how-to/upgrade-to-v6.md @@ -22,7 +22,7 @@ sidebar: ### 1. 运行安装程序 -按照[安装程序说明](./install-bmad_cn.md)操作。 +按照[安装程序说明](./install-bmad.md)操作。 ### 2. 处理旧版安装 diff --git a/docs_cn/index_cn.md b/docs/zh-cn/index.md similarity index 93% rename from docs_cn/index_cn.md rename to docs/zh-cn/index.md index b6d0f5e33..6e643c34b 100644 --- a/docs_cn/index_cn.md +++ b/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)** 并构建您的第一个项目。 --- ## 术语说明 diff --git a/docs_cn/reference/agents_cn.md b/docs/zh-cn/reference/agents.md similarity index 100% rename from docs_cn/reference/agents_cn.md rename to docs/zh-cn/reference/agents.md diff --git a/docs_cn/reference/commands_cn.md b/docs/zh-cn/reference/commands.md similarity index 96% rename from docs_cn/reference/commands_cn.md rename to docs/zh-cn/reference/commands.md index 8f35371cd..617e557af 100644 --- a/docs_cn/reference/commands_cn.md +++ b/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--` | 工作流命令 | `bmad-bmm-create-prd` | | `bmad-` | 核心任务或工具 | `bmad-help` | -模块代码：`bmm`（敏捷套件）、`bmb`（构建器）、`tea`（测试架构师）、`cis`（创意智能）、`gds`（游戏开发工作室）。参见[模块](./modules_cn.md)获取描述。 +模块代码：`bmm`（敏捷套件）、`bmb`（构建器）、`tea`（测试架构师）、`cis`（创意智能）、`gds`（游戏开发工作室）。参见[模块](./modules.md)获取描述。 ## 故障排除 diff --git a/docs_cn/reference/modules_cn.md b/docs/zh-cn/reference/modules.md similarity index 100% rename from docs_cn/reference/modules_cn.md rename to docs/zh-cn/reference/modules.md diff --git a/docs_cn/reference/testing_cn.md b/docs/zh-cn/reference/testing.md similarity index 99% rename from docs_cn/reference/testing_cn.md rename to docs/zh-cn/reference/testing.md index 013e277e6..ffa6e87c3 100644 --- a/docs_cn/reference/testing_cn.md +++ b/docs/zh-cn/reference/testing.md @@ -103,7 +103,7 @@ Quinn 的 Automate 工作流出现在 BMad 方法工作流图的第 4 阶段（ Quinn 直接从源代码工作，无需加载规划文档（PRD、架构）。TEA 工作流可以与上游规划产物集成以实现可追溯性。 -有关测试在整体流程中的位置，请参阅[工作流图](./workflow-map_cn.md)。 +有关测试在整体流程中的位置，请参阅[工作流图](./workflow-map.md)。 --- ## 术语说明 diff --git a/docs_cn/reference/workflow-map_cn.md b/docs/zh-cn/reference/workflow-map.md similarity index 99% rename from docs_cn/reference/workflow-map_cn.md rename to docs/zh-cn/reference/workflow-map.md index f90799a70..23ae70b5b 100644 --- a/docs_cn/reference/workflow-map_cn.md +++ b/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) --- ## 术语说明 diff --git a/docs_cn/roadmap_cn.mdx b/docs/zh-cn/roadmap.mdx similarity index 100% rename from docs_cn/roadmap_cn.mdx rename to docs/zh-cn/roadmap.mdx diff --git a/docs_cn/tutorials/getting-started_cn.md b/docs/zh-cn/tutorials/getting-started.md similarity index 98% rename from docs_cn/tutorials/getting-started_cn.md rename to docs/zh-cn/tutorials/getting-started.md index f220f13f9..31a765b33 100644 --- a/docs_cn/tutorials/getting-started_cn.md +++ b/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：分析（可选） diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 565b81565..1b987d7f1 100644 --- a/website/astro.config.mjs +++ b/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' }, }, diff --git a/website/src/content/config.ts b/website/src/content/config.ts index 31b747625..02ea2ac07 100644 --- a/website/src/content/config.ts +++ b/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() }), }; diff --git a/website/src/content/i18n/zh-CN.json b/website/src/content/i18n/zh-CN.json new file mode 100644 index 000000000..35c916a62 --- /dev/null +++ b/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 构建" +} From d81220547067a65d58e3ecf6a9780c5483427365 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Fri, 6 Mar 2026 19:22:56 -0700 Subject: [PATCH 3/5] fix(quick-flow): add input trust guardrail to step 1 clarify-and-route (#1825) Prevent the agent from treating detailed, plan-like input as a validated plan and short-circuiting the workflow. The new rule ensures the full workflow is followed regardless of input specificity. --- .../quick-dev-new-preview/steps/step-01-clarify-and-route.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md b/src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md index 9ba926cca..1d84cbf22 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md +++ b/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 From e3ffdf9c9029c4505eeda9757e26c22d0033f8a9 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Fri, 6 Mar 2026 19:24:13 -0700 Subject: [PATCH 4/5] fix(create-story): replace missing validate-workflow invoke with explicit checklist action (#1837) Co-authored-by: Brian --- .../workflows/4-implementation/create-story/instructions.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml index f9433371f..30d9ce3c0 100644 --- a/src/bmm/workflows/4-implementation/create-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/create-story/instructions.xml @@ -311,7 +311,7 @@ - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.xml + Validate the newly created story file {story_file} against {installed_path}/checklist.md and apply any required fixes before finalizing Save story document unconditionally From 09ce8559f28da9961cc02eb78f46dcf130565a66 Mon Sep 17 00:00:00 2001 From: Chandan Veerabhadrappa <2203146+chandanv89@users.noreply.github.com> Date: Sat, 7 Mar 2026 02:25:59 +0000 Subject: [PATCH 5/5] fix: use last_updated instead of generated for sprint-status staleness check (#1836) The staleness warning in sprint-status always fired after 7 days because it checked the 'generated' timestamp, which is only set once during sprint-planning. Other workflows (dev-story, create-story, code-review, retrospective) update statuses but never touched 'generated'. This adds a 'last_updated' field that is: - Set initially alongside 'generated' during sprint-planning - Bumped to current date by every workflow that modifies sprint-status.yaml - Used by the staleness check (with fallback to 'generated' for backward compatibility) Fixes bmad-code-org/BMAD-METHOD#1820 Co-authored-by: Oz --- .../workflows/4-implementation/code-review/instructions.xml | 2 ++ .../4-implementation/create-story/instructions.xml | 1 + .../workflows/4-implementation/dev-story/instructions.xml | 2 ++ .../4-implementation/retrospective/instructions.md | 1 + .../4-implementation/sprint-planning/instructions.md | 2 ++ .../sprint-planning/sprint-status-template.yaml | 1 + .../4-implementation/sprint-status/instructions.md | 6 +++--- 7 files changed, 12 insertions(+), 3 deletions(-) diff --git a/src/bmm/workflows/4-implementation/code-review/instructions.xml b/src/bmm/workflows/4-implementation/code-review/instructions.xml index e5649559d..37b3eb63f 100644 --- a/src/bmm/workflows/4-implementation/code-review/instructions.xml +++ b/src/bmm/workflows/4-implementation/code-review/instructions.xml @@ -195,12 +195,14 @@ Update development_status[{{story_key}}] = "done" + Update last_updated field to current date Save file, preserving ALL comments and structure ✅ Sprint status synced: {{story_key}} → done Update development_status[{{story_key}}] = "in-progress" + Update last_updated field to current date Save file, preserving ALL comments and structure 🔄 Sprint status synced: {{story_key}} → in-progress diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml index 30d9ce3c0..efdc87c0e 100644 --- a/src/bmm/workflows/4-implementation/create-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/create-story/instructions.xml @@ -321,6 +321,7 @@ Find development_status key matching {{story_key}} Verify current status is "backlog" (expected previous state) Update development_status[{{story_key}}] = "ready-for-dev" + Update last_updated field to current date Save file, preserving ALL comments and structure including STATUS DEFINITIONS diff --git a/src/bmm/workflows/4-implementation/dev-story/instructions.xml b/src/bmm/workflows/4-implementation/dev-story/instructions.xml index 3c4989f39..c39c35f2e 100644 --- a/src/bmm/workflows/4-implementation/dev-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/dev-story/instructions.xml @@ -195,6 +195,7 @@ Update the story in the sprint status report to = "in-progress" + Update last_updated field to current date 🚀 Starting work on story {{story_key}} Status updated: ready-for-dev → in-progress @@ -348,6 +349,7 @@ Find development_status key matching {{story_key}} Verify current status is "in-progress" (expected previous state) Update development_status[{{story_key}}] = "review" + Update last_updated field to current date Save file, preserving ALL comments and structure including STATUS DEFINITIONS ✅ Story status updated to "review" in sprint-status.yaml diff --git a/src/bmm/workflows/4-implementation/retrospective/instructions.md b/src/bmm/workflows/4-implementation/retrospective/instructions.md index 018ef6ee3..d2bf7e390 100644 --- a/src/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/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!" Find development_status key "epic-{{epic_number}}-retrospective" Verify current status (typically "optional" or "pending") Update development_status["epic-{{epic_number}}-retrospective"] = "done" +Update last_updated field to current date Save file, preserving ALL comments and structure including STATUS DEFINITIONS diff --git a/src/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/bmm/workflows/4-implementation/sprint-planning/instructions.md index 316d2fec3..04492088b 100644 --- a/src/bmm/workflows/4-implementation/sprint-planning/instructions.md +++ b/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 } diff --git a/src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml b/src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml index 80d404310..6725b206c 100644 --- a/src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml +++ b/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 diff --git a/src/bmm/workflows/4-implementation/sprint-status/instructions.md b/src/bmm/workflows/4-implementation/sprint-status/instructions.md index 4182e1f25..b37bff9a5 100644 --- a/src/bmm/workflows/4-implementation/sprint-status/instructions.md +++ b/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 Read the FULL file: {sprint_status_file} - Parse fields: generated, project, project_key, tracking_system, story_location + Parse fields: generated, last_updated, project, project_key, tracking_system, story_location Parse development_status map. Classify keys: - 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" @@ -195,7 +195,7 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted. Read and parse {sprint_status_file} -Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location +Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location (last_updated is optional for backward compatibility) is_valid = false error = "Missing required field(s): {{missing_fields}}"