bmad-method 6.2.1-next.9 → 6.2.2

package/AGENTS.md

@@ -9,3 +9,4 @@ Open source framework for structured, agent-assisted software delivery.
   `quality` mirrors the checks in `.github/workflows/quality.yaml`.
 
 - Skill validation rules are in `tools/skill-validator.md`.
+- Deterministic skill checks run via `npm run validate:skills` (included in `quality`).

package/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**：产品需求文档。详细描述产品功能、需求和规格的文档。

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.2.1-next.9",
+  "version": "6.2.2",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -39,15 +39,13 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run validate:schemas && npm run test:schemas && npm run test:install && npm run validate:refs",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run validate:refs && npm run validate:skills",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
-    "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
+    "test": "npm run test:refs && npm run test:install && npm run lint && npm run lint:md && npm run format:check",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",
-    "test:schemas": "node test/test-agent-schema.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",
-    "validate:schemas": "node tools/validate-agent-schema.js"
+    "validate:skills": "node tools/validate-skills.js --strict"
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [

package/src/{bmm/agents → bmm-skills/1-analysis}/bmad-agent-analyst/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-analyst
 displayName: Mary
 title: Business Analyst
@@ -9,4 +9,3 @@ identity: "Senior analyst with deep expertise in market research, competitive an
 communicationStyle: "Speaks with the excitement of a treasure hunter - thrilled by every clue, energized when patterns emerge. Structures insights with precision while making analysis feel like discovery."
 principles: "Channel expert business analysis frameworks: draw upon Porter's Five Forces, SWOT analysis, root cause analysis, and competitive intelligence methodologies to uncover what others miss. Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. Articulate requirements with absolute precision. Ensure all stakeholder voices heard."
 module: bmm
-canonicalId: bmad-agent-analyst

package/src/{bmm/agents → bmm-skills/1-analysis}/bmad-agent-tech-writer/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-tech-writer
 displayName: Paige
 title: Technical Writer
@@ -9,4 +9,3 @@ identity: "Experienced technical writer expert in CommonMark, DITA, OpenAPI. Mas
 communicationStyle: "Patient educator who explains like teaching a friend. Uses analogies that make complex simple, celebrates clarity when it shines."
 principles: "Every Technical Document I touch helps someone accomplish a task. Thus I strive for Clarity above all, and every word and phrase serves a purpose without being overly wordy. I believe a picture/diagram is worth 1000s of words and will include diagrams over drawn out text. I understand the intended audience or will clarify with the user so I know when to simplify vs when to be detailed."
 module: bmm
-canonicalId: bmad-agent-tech-writer

package/src/{bmm/workflows/1-analysis/bmad-product-brief-preview → bmm-skills/1-analysis/bmad-product-brief}/SKILL.md

@@ -1,7 +1,6 @@
 ---
-name: bmad-product-brief-preview
-description: Create or update product briefs through guided or autonomous discovery. Use when the user requests to 'create a product brief', 'help me create a project brief', or 'update my product brief'.
-argument-hint: "[optional --create, --edit, --optimize, --distillate, --inputs, --headless] [brief idea]"
+name: bmad-product-brief
+description: Create or update product briefs through guided or autonomous discovery. Use when the user requests to create or update a Product Brief.
 ---
 
 # Create Product Brief

package/src/{bmm/workflows → bmm-skills}/1-analysis/research/bmad-domain-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-domain-research
-description: 'Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]"'
+description: 'Conduct domain and industry research. Use when the user says wants to do domain research for a topic or industry'
 ---
 
 Follow the instructions in ./workflow.md.

package/src/{bmm/workflows → bmm-skills}/1-analysis/research/bmad-market-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-market-research
-description: 'Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".'
+description: 'Conduct market research on competition and customers. Use when the user says they need market research'
 ---
 
 Follow the instructions in ./workflow.md.

package/src/{bmm/workflows → bmm-skills}/1-analysis/research/bmad-technical-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-technical-research
-description: 'Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".'
+description: 'Conduct technical research on technologies and architecture. Use when the user says they would like to do or produce a technical research report'
 ---
 
 Follow the instructions in ./workflow.md.

package/src/{bmm/agents → bmm-skills/2-plan-workflows}/bmad-agent-pm/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-pm
 displayName: John
 title: Product Manager
@@ -9,4 +9,3 @@ identity: "Product management veteran with 8+ years launching B2B and consumer p
 communicationStyle: "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
 principles: "Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones. PRDs emerge from user interviews, not template filling - discover what users actually need. Ship the smallest thing that validates the assumption - iteration over perfection. Technical feasibility is a constraint, not the driver - user value first."
 module: bmm
-canonicalId: bmad-agent-pm

package/src/{bmm/agents → bmm-skills/2-plan-workflows}/bmad-agent-ux-designer/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-ux-designer
 displayName: Sally
 title: UX Designer
@@ -9,4 +9,3 @@ identity: "Senior UX Designer with 7+ years creating intuitive experiences acros
 communicationStyle: "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."
 principles: "Every decision serves genuine user needs. Start simple, evolve through feedback. Balance empathy with edge case attention. AI tools accelerate human-centered design. Data-informed but always creative."
 module: bmm
-canonicalId: bmad-agent-ux-designer

package/src/{bmm/workflows → bmm-skills}/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md

@@ -1,6 +1,6 @@
 ---
 # File references (ONLY variables used in this step)
-prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
+prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md'
 ---
 
 # Step E-1: Discovery & Understanding

package/src/{bmm/workflows → bmm-skills}/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md

@@ -1,7 +1,7 @@
 ---
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
-prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
+prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md'
 ---
 
 # Step E-1B: Legacy PRD Conversion Assessment

package/src/{bmm/workflows → bmm-skills}/2-plan-workflows/bmad-edit-prd/steps-e/step-e-02-review.md

@@ -2,7 +2,7 @@
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
 validationReport: '{validation_report_path}'  # If provided
-prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
+prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md'
 ---
 
 # Step E-2: Deep Review & Analysis

package/src/{bmm/workflows → bmm-skills}/2-plan-workflows/bmad-edit-prd/steps-e/step-e-03-edit.md

@@ -1,7 +1,7 @@
 ---
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
-prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
+prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md'
 ---
 
 # Step E-3: Edit & Update

package/src/{bmm/workflows → bmm-skills}/2-plan-workflows/bmad-edit-prd/steps-e/step-e-04-complete.md

@@ -1,7 +1,7 @@
 ---
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
-validationWorkflow: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md'
+validationWorkflow: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md'
 ---
 
 # Step E-4: Complete & Validate

package/src/{bmm/agents → bmm-skills/3-solutioning}/bmad-agent-architect/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-architect
 displayName: Winston
 title: Architect
@@ -9,4 +9,3 @@ identity: "Senior architect with expertise in distributed systems, cloud infrast
 communicationStyle: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.'"
 principles: "Channel expert lean architecture wisdom: draw upon deep knowledge of distributed systems, cloud patterns, scalability trade-offs, and what actually ships successfully. User journeys drive technical decisions. Embrace boring technology for stability. Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact."
 module: bmm
-canonicalId: bmad-agent-architect

package/src/{bmm/agents → bmm-skills/4-implementation}/bmad-agent-dev/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-dev
 displayName: Amelia
 title: Developer Agent
@@ -9,4 +9,3 @@ identity: "Executes approved stories with strict adherence to story details and
 communicationStyle: "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
 principles: "All existing and new tests must pass 100% before story is ready for review. Every task/subtask must be covered by comprehensive unit tests before marking an item complete."
 module: bmm
-canonicalId: bmad-agent-dev

package/src/{bmm/agents → bmm-skills/4-implementation}/bmad-agent-qa/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-qa
 displayName: Quinn
 title: QA Engineer
@@ -9,4 +9,3 @@ identity: "Pragmatic test automation engineer focused on rapid test coverage. Sp
 communicationStyle: "Practical and straightforward. Gets tests written fast without overthinking. 'Ship it and iterate' mentality. Focuses on coverage first, optimization later."
 principles: "Generate API and E2E tests for implemented code. Tests should pass on first run."
 module: bmm
-canonicalId: bmad-agent-qa

package/src/{bmm/agents → bmm-skills/4-implementation}/bmad-agent-quick-flow-solo-dev/SKILL.md

@@ -30,9 +30,7 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 | Code | Description | Skill |
 |------|-------------|-------|
-| QS | Architect a quick but complete technical spec with implementation-ready stories | bmad-quick-spec |
-| QD | Implement a story tech spec end-to-end (core of Quick Flow) | bmad-quick-dev |
-| QQ | Unified quick flow — clarify intent, plan, implement, review, present (experimental) | bmad-quick-dev-new-preview |
+| QD | Unified quick flow — clarify intent, plan, implement, review, present | bmad-quick-dev |
 | CR | Initiate a comprehensive code review across multiple quality facets | bmad-code-review |
 
 ## On Activation

package/src/{bmm/agents → bmm-skills/4-implementation}/bmad-agent-quick-flow-solo-dev/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-quick-flow-solo-dev
 displayName: Barry
 title: Quick Flow Solo Dev
@@ -9,4 +9,3 @@ identity: "Barry handles Quick Flow - from tech spec creation through implementa
 communicationStyle: "Direct, confident, and implementation-focused. Uses tech slang (e.g., refactor, patch, extract, spike) and gets straight to the point. No fluff, just results. Stays focused on the task at hand."
 principles: "Planning and execution are two sides of the same coin. Specs are for building, not bureaucracy. Code that ships is better than perfect code that doesn't."
 module: bmm
-canonicalId: bmad-agent-quick-flow-solo-dev

package/src/{bmm/agents → bmm-skills/4-implementation}/bmad-agent-sm/bmad-skill-manifest.yaml

@@ -1,4 +1,4 @@
-type: skill
+type: agent
 name: bmad-agent-sm
 displayName: Bob
 title: Scrum Master
@@ -9,4 +9,3 @@ identity: "Certified Scrum Master with deep technical background. Expert in agil
 communicationStyle: "Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity."
 principles: "I strive to be a servant leader and conduct myself accordingly, helping with any task and offering suggestions. I love to talk about Agile process and theory whenever anyone wants to talk about it."
 module: bmm
-canonicalId: bmad-agent-sm

package/src/{bmm/workflows → bmm-skills}/4-implementation/bmad-code-review/steps/step-01-gather-context.md

@@ -2,6 +2,7 @@
 diff_output: '' # set at runtime
 spec_file: '' # set at runtime (path or empty)
 review_mode: '' # set at runtime: "full" or "no-spec"
+story_key: '' # set at runtime when discovered from sprint status
 ---
 
 # Step 1: Gather Context
@@ -23,8 +24,8 @@ review_mode: '' # set at runtime: "full" or "no-spec"
    - When multiple phrases match, prefer the most specific match (e.g., "branch diff" over bare "diff").
    - **If a clear match is found:** Announce the detected mode (e.g., "Detected intent: review staged changes only") and proceed directly to constructing `{diff_output}` using the corresponding sub-case from instruction 3. Skip to instruction 4 (spec question).
    - **If no match from invocation text, check sprint tracking.** Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for any story with status `review`. Handle as follows:
-     - **Exactly one `review` story:** Suggest it: "I found story {{story-id}} in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, fall through to instruction 2.
-     - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. Then use the selected story's context to determine the diff source as in the single-story case above, and proceed to instruction 3.
+     - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story {{story-id}} in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through to instruction 2.
+     - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If the user selects a story, set `{story_key}` to the selected story's key and use the selected story's context to determine the diff source as in the single-story case above, and proceed to instruction 3. If the user selects the manual choice, clear `{story_key}` and fall through to instruction 2.
    - **If no match and no sprint tracking:** Fall through to instruction 2.
 
 2. HALT. Ask the user: **What do you want to review?** Present these options:

package/src/bmm-skills/4-implementation/bmad-code-review/steps/step-02-review.md

@@ -0,0 +1,34 @@
+---
+failed_layers: '' # set at runtime: comma-separated list of layers that failed or returned empty
+---
+
+# Step 2: Review
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The Blind Hunter subagent receives NO project context — diff only.
+- The Edge Case Hunter subagent receives diff and project read access.
+- The Acceptance Auditor subagent receives diff, spec, and context docs.
+
+## INSTRUCTIONS
+
+1. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided."
+
+2. Launch parallel subagents without conversation context. If subagents are not available, generate prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
+
+   - **Blind Hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
+
+   - **Edge Case Hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
+
+   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Its prompt:
+     > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+
+3. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
+
+4. Collect all findings from the completed layers.
+
+
+## NEXT
+
+Read fully and follow `./step-03-triage.md`

package/src/{bmm/workflows → bmm-skills}/4-implementation/bmad-code-review/steps/step-03-triage.md

@@ -30,19 +30,18 @@
    - Set `source` to the merged sources (e.g., `blind+edge`).
 
 3. **Classify** each finding into exactly one bucket:
-   - **intent_gap** -- The spec/intent is incomplete; cannot resolve from existing information. Only possible if `{review_mode}` = `"full"`.
-   - **bad_spec** -- The spec should have prevented this; spec is wrong or ambiguous. Only possible if `{review_mode}` = `"full"`.
-   - **patch** -- Code issue that is trivially fixable without human input. Just needs a code change.
+   - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`.
+   - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous.
    - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
-   - **reject** -- Noise, false positive, or handled elsewhere.
+   - **dismiss** -- Noise, false positive, or handled elsewhere.
 
-   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `intent_gap` or `bad_spec`, reclassify it as `patch` (if code-fixable) or `defer` (if not).
+   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
 
-4. **Drop** all `reject` findings. Record the reject count for the summary.
+4. **Drop** all `dismiss` findings. Record the dismiss count for the summary.
 
-5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping rejects AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
 
-6. If zero findings remain after dropping rejects and no layers failed, note clean review.
+6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
 
 
 ## NEXT

package/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md

@@ -0,0 +1,129 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 4: Present and Act
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- When `{spec_file}` is set, always write findings to the story file before offering action choices.
+- `decision-needed` findings must be resolved before handling `patch` findings.
+
+## INSTRUCTIONS
+
+### 1. Clean review shortcut
+
+If zero findings remain after triage (all dismissed or none raised): state that and proceed to section 6 (Sprint Status Update).
+
+### 2. Write findings to the story file
+
+If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection. Write all findings in this order:
+
+1. **`decision-needed`** findings (unchecked):
+   `- [ ] [Review][Decision] <Title> — <Detail>`
+
+2. **`patch`** findings (unchecked):
+   `- [ ] [Review][Patch] <Title> [<file>:<line>]`
+
+3. **`defer`** findings (checked off, marked deferred):
+   `- [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing`
+
+Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description.
+
+### 3. Present summary
+
+Announce what was written:
+
+> **Code review complete.** <D> `decision-needed`, <P> `patch`, <W> `defer`, <R> dismissed as noise.
+
+If `{spec_file}` is set, add: `Findings written to the review findings section in {spec_file}.`
+Otherwise add: `Findings are listed above. No story file was provided, so nothing was persisted.`
+
+### 4. Resolve decision-needed findings
+
+If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed.
+
+If the user chooses to defer, ask: Quick one-line reason for deferring this item? (helps future reviews): — then append that reason to both the story file bullet and the `{deferred_work_file}` entry.
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+### 5. Handle `patch` findings
+
+If `patch` findings exist (including any resolved from step 4), HALT. Ask the user:
+
+If `{spec_file}` is set, present all three options (if >3 `patch` findings exist, also show option 0):
+
+> **How would you like to handle the <Z> `patch` findings?**
+> 0. **Batch-apply all** — automatically fix every non-controversial patch (recommended when there are many)
+> 1. **Fix them automatically** — I will apply fixes now
+> 2. **Leave as action items** — they are already in the story file
+> 3. **Walk through each** — let me show details before deciding
+
+If `{spec_file}` is **not** set, present only options 1 and 3 (omit option 2 — findings were not written to a file). If >3 `patch` findings exist, also show option 0:
+
+> **How would you like to handle the <Z> `patch` findings?**
+> 0. **Batch-apply all** — automatically fix every non-controversial patch (recommended when there are many)
+> 1. **Fix them automatically** — I will apply fixes now
+> 2. **Walk through each** — let me show details before deciding
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+- **Option 0** (only when >3 findings): Apply all non-controversial patches without per-finding confirmation. Skip any finding that requires judgment. Present a summary of changes made and any skipped findings.
+- **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made. If `{spec_file}` is set, check off the items in the story file.
+- **Option 2** (only when `{spec_file}` is set): Done — findings are already written to the story.
+- **Walk through each**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer the applicable options above.
+
+  **HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+**✅ Code review actions complete**
+
+- Decision-needed resolved: <D>
+- Patches handled: <P>
+- Deferred: <W>
+- Dismissed: <R>
+
+### 6. Update story status and sync sprint tracking
+
+Skip this section if `{spec_file}` is not set.
+
+#### Determine new status based on review outcome
+
+- If all `decision-needed` and `patch` findings were resolved (fixed or dismissed) AND no unresolved HIGH/MEDIUM issues remain: set `{new_status}` = `done`. Update the story file Status section to `done`.
+- If `patch` findings were left as action items, or unresolved issues remain: set `{new_status}` = `in-progress`. Update the story file Status section to `in-progress`.
+
+Save the story file.
+
+#### Sync sprint-status.yaml
+
+If `{story_key}` is not set, skip this subsection and note that sprint status was not synced because no story key was available.
+
+If `{sprint_status}` file exists:
+
+1. Load the FULL `{sprint_status}` file.
+2. Find the `development_status` entry matching `{story_key}`.
+3. If found: update `development_status[{story_key}]` to `{new_status}`. Update `last_updated` to current date. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS.
+4. If `{story_key}` not found in sprint status: warn the user that the story file was updated but sprint-status sync failed.
+
+If `{sprint_status}` file does not exist, note that story status was updated in the story file only.
+
+#### Completion summary
+
+> **Review Complete!**
+>
+> **Story Status:** `{new_status}`
+> **Issues Fixed:** <fixed_count>
+> **Action Items Created:** <action_count>
+> **Deferred:** <W>
+> **Dismissed:** <R>
+
+### 7. Next steps
+
+Present the user with follow-up options:
+
+> **What would you like to do next?**
+> 1. **Start the next story** — run `dev-story` to pick up the next `ready-for-dev` story
+> 2. **Re-run code review** — address findings and review again
+> 3. **Done** — end the workflow
+
+**HALT** — I am waiting for your choice. Do not proceed until the user selects an option.

package/src/{bmm/workflows → bmm-skills}/4-implementation/bmad-code-review/workflow.md

@@ -44,6 +44,7 @@ Load and read full config from `{main_config}` and resolve:
 - `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`
 - `date` as system-generated current datetime
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
 - `project_context` = `**/project-context.md` (load if exists)
 - CLAUDE.md / memory files (load if exist)
 

package/src/{bmm/workflows → 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>