Merge 2a3708fd32 into e794a81ee2

.augment/code_review_guidelines.yaml

@@ -1,7 +1,6 @@
 # Augment Code Review Guidelines for BMAD-METHOD
 # https://docs.augmentcode.com/codereview/overview
-# Focus: Skill validation and quality
-# Canonical rules: tools/skill-validator.md (single source of truth)
+# Focus: Workflow validation and quality
 
 file_paths_to_ignore:
   # --- Shared baseline: tool configs ---
@@ -49,17 +48,123 @@ file_paths_to_ignore:
 
 areas:
   # ============================================
-  # SKILL FILES
+  # WORKFLOW STRUCTURE RULES
   # ============================================
-  skill_files:
-    description: "All skill content — SKILL.md, workflow.md, step files, data files, and templates within skill directories"
+  workflow_structure:
+    description: "Workflow folder organization and required components"
     globs:
-      - "src/**/skills/**"
       - "src/**/workflows/**"
-      - "src/**/tasks/**"
     rules:
-      - id: "skill_validation"
-        description: "Apply the full rule catalog defined in tools/skill-validator.md. That file is the single source of truth for all skill validation rules covering SKILL.md metadata, workflow.md constraints, step file structure, path references, variable resolution, sequential execution, and skill invocation syntax."
+      - id: "workflow_entry_point_required"
+        description: "Every workflow folder must have workflow.md as entry point"
+        severity: "high"
+
+      - id: "sharded_workflow_steps_folder"
+        description: "Sharded workflows (using workflow.md) must have steps/ folder with numbered files (step-01-*.md, step-02-*.md)"
+        severity: "high"
+
+      - id: "workflow_step_limit"
+        description: "Workflows should have 5-10 steps maximum to prevent context loss in LLM execution"
+        severity: "medium"
+
+  # ============================================
+  # WORKFLOW ENTRY FILE RULES
+  # ============================================
+  workflow_definitions:
+    description: "Workflow entry files (workflow.md)"
+    globs:
+      - "src/**/workflows/**/workflow.md"
+    rules:
+      - id: "workflow_name_required"
+        description: "Workflow entry files must define 'name' field in frontmatter or root element"
+        severity: "high"
+
+      - id: "workflow_description_required"
+        description: "Workflow entry files must include 'description' explaining the workflow's purpose"
+        severity: "high"
+
+      - id: "workflow_installed_path"
+        description: "Workflows should define installed_path for relative file references within the workflow"
+        severity: "medium"
+
+      - id: "valid_step_references"
+        description: "Step file references in workflow entry must point to existing files"
+        severity: "high"
+
+  # ============================================
+  # SHARDED WORKFLOW STEP RULES
+  # ============================================
+  workflow_steps:
+    description: "Individual step files in sharded workflows"
+    globs:
+      - "src/**/workflows/**/steps/step-*.md"
+    rules:
+      - id: "step_goal_required"
+        description: "Each step must clearly state its goal (## STEP GOAL, ## YOUR TASK, or step n='X' goal='...')"
+        severity: "high"
+
+      - id: "step_mandatory_rules"
+        description: "Step files should include MANDATORY EXECUTION RULES section with universal agent behavior rules"
+        severity: "medium"
+
+      - id: "step_context_boundaries"
+        description: "Step files should define CONTEXT BOUNDARIES explaining available context and limits"
+        severity: "medium"
+
+      - id: "step_success_metrics"
+        description: "Step files should include SUCCESS METRICS section with ✅ checkmarks for validation criteria"
+        severity: "medium"
+
+      - id: "step_failure_modes"
+        description: "Step files should include FAILURE MODES section with ❌ marks for anti-patterns to avoid"
+        severity: "medium"
+
+      - id: "step_next_step_reference"
+        description: "Step files should reference the next step file path for sequential execution"
+        severity: "medium"
+
+      - id: "step_no_forward_loading"
+        description: "Steps must NOT load future step files until current step completes - just-in-time loading only"
+        severity: "high"
+
+      - id: "valid_file_references"
+        description: "File path references using {variable}/filename.md must point to existing files"
+        severity: "high"
+
+      - id: "step_naming"
+        description: "Step files must be named step-NN-description.md (e.g., step-01-init.md, step-02-context.md)"
+        severity: "medium"
+
+      - id: "halt_before_menu"
+        description: "Steps presenting user menus ([C] Continue, [a] Advanced, etc.) must HALT and wait for response"
+        severity: "high"
+
+  # ============================================
+  # WORKFLOW CONTENT QUALITY
+  # ============================================
+  workflow_content:
+    description: "Content quality and consistency rules for all workflow files"
+    globs:
+      - "src/**/workflows/**/*.md"
+    rules:
+      - id: "communication_language_variable"
+        description: "Workflows should use {communication_language} variable for agent output language consistency"
+        severity: "low"
+
+      - id: "path_placeholders_required"
+        description: "Use path placeholders (e.g. {project-root}, {installed_path}, {output_folder}) instead of hardcoded paths"
+        severity: "medium"
+
+      - id: "no_time_estimates"
+        description: "Workflows should NOT include time estimates - AI development speed varies significantly"
+        severity: "low"
+
+      - id: "facilitator_not_generator"
+        description: "Workflow agents should act as facilitators (guide user input) not content generators (create without input)"
+        severity: "medium"
+
+      - id: "no_skip_optimization"
+        description: "Workflows must execute steps sequentially - no skipping or 'optimizing' step order"
         severity: "high"
 
   # ============================================
@@ -78,10 +183,27 @@ areas:
         description: "Agent files must define persona with role, identity, communication_style, and principles"
         severity: "high"
 
-      - id: "agent_menu_valid_skills"
-        description: "Menu triggers must reference valid skill names that exist"
+      - id: "agent_menu_valid_workflows"
+        description: "Menu triggers must reference valid workflow paths that exist"
         severity: "high"
 
+  # ============================================
+  # TEMPLATES
+  # ============================================
+  templates:
+    description: "Template files for workflow outputs"
+    globs:
+      - "src/**/template*.md"
+      - "src/**/templates/**/*.md"
+    rules:
+      - id: "placeholder_syntax"
+        description: "Use {variable_name} or {{variable_name}} syntax consistently for placeholders"
+        severity: "medium"
+
+      - id: "template_sections_marked"
+        description: "Template sections that need generation should be clearly marked (e.g., <!-- GENERATE: section_name -->)"
+        severity: "low"
+
   # ============================================
   # DOCUMENTATION
   # ============================================

.github/workflows/quality.yaml

@@ -1,6 +1,6 @@
 name: Quality & Validation
 
-# Runs comprehensive quality checks on all PRs and pushes to main:
+# Runs comprehensive quality checks on all PRs:
 # - Prettier (formatting)
 # - ESLint (linting)
 # - markdownlint (markdown quality)
@@ -10,8 +10,6 @@ name: Quality & Validation
 # Keep this workflow aligned with `npm run quality` in `package.json`.
 
 "on":
-  push:
-    branches: [main]
   pull_request:
     branches: ["**"]
   workflow_dispatch:

.gitignore

@@ -17,8 +17,6 @@ npm-debug.log*
 # Build output
 build/*.txt
 
-design-artifacts/
-
 # Environment variables
 .env
 

CHANGELOG.md

@@ -1,36 +1,5 @@
 # Changelog
 
-## v6.2.0 - 2026-03-15
-
-### 🎁 Highlights
-
-* Fix manifest generation so BMad Builder installs correctly when a module has no agents (#1998)
-* Prototype preview of bmad-product-brief-preview skill — try `/bmad-product-brief-preview` and share feedback! (#1959)
-* All skills now use native skill directory format for improved modularity and maintainability (#1931, #1945, #1946, #1949, #1950, #1984, #1985, #1988, #1994)
-
-### 🎁 Features
-
-* Rewrite code-review skill with sharded step-file architecture and auto-detect review intent from invocation args (#2007, #2013)
-* Add inference-based skill validator with comprehensive rules for naming, variables, paths, and invocation syntax (#1981)
-* Add REF-03 skill invocation language rule and PATH-05 skill encapsulation rule to validator (#2004)
-
-### 🐛 Bug Fixes
-
-* Validation pass 2 — fix path, variable, and sequence issues across 32 files (#2008)
-* Replace broken party-mode workflow refs with skill syntax (#2000)
-* Improve bmad-help description for accurate trigger matching (#2012)
-* Point zh-cn doc links to Chinese pages instead of English (#2010)
-* Validation cleanup for bmad-quick-flow (#1997), 6 skills batch (#1996), bmad-sprint-planning (#1995), bmad-retrospective (#1993), bmad-dev-story (#1992), bmad-create-story (#1991), bmad-code-review (#1990), bmad-create-epics-and-stories (#1989), bmad-create-architecture (#1987), bmad-check-implementation-readiness (#1986), bmad-create-ux-design (#1983), bmad-create-product-brief (#1982)
-
-### 🔧 Maintenance
-
-* Normalize skill invocation syntax to `Invoke the skill` pattern repo-wide (#2004)
-
-### 📚 Documentation
-
-* Add Chinese translation for core-tools reference (#2002)
-* Update version hint, TEA module link, and HTTP→HTTPS links in Chinese README (#1922, #1921)
-
 ## [6.1.0] - 2026-03-12
 
 ### Highlights

README_CN.md

@@ -20,7 +20,7 @@
 - **派对模式** — 将多个智能体角色带入一个会话进行协作和讨论
 - **完整生命周期** — 从想法开始（头脑风暴）到部署发布
 
-[在 **docs.bmad-method.org** 了解更多](https://docs.bmad-method.org/zh-cn/)
+[在 **docs.bmad-method.org** 了解更多](https://docs.bmad-method.org)
 
 ---
 
@@ -28,7 +28,7 @@
 
 **V6 已到来，我们才刚刚开始！** BMad 方法正在快速发展，包括跨平台智能体团队和子智能体集成、技能架构、BMad Builder v1、开发循环自动化等优化，以及更多正在开发中的功能。
 
-**[📍 查看完整路线图 →](https://docs.bmad-method.org/zh-cn/roadmap/)**
+**[📍 查看完整路线图 →](https://docs.bmad-method.org/roadmap/)**
 
 ---
 
@@ -50,7 +50,7 @@ npx bmad-method install
 npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes
 ```
 
-[查看非交互式安装选项](https://docs.bmad-method.org/zh-cn/how-to/non-interactive-installation/)
+[查看所有安装选项](https://docs.bmad-method.org/how-to/non-interactive-installation/)
 
 > **不确定该做什么？** 运行 `bmad-help` — 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。
 
@@ -68,12 +68,12 @@ BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后
 
 ## 文档
 
-[BMad 方法文档站点](https://docs.bmad-method.org/zh-cn/) — 教程、指南、概念和参考
+[BMad 方法文档站点](https://docs.bmad-method.org) — 教程、指南、概念和参考
 
 **快速链接：**
-- [入门教程](https://docs.bmad-method.org/zh-cn/tutorials/getting-started/)
-- [从先前版本升级](https://docs.bmad-method.org/zh-cn/how-to/upgrade-to-v6/)
-- [测试架构师文档（英文）](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
+- [入门教程](https://docs.bmad-method.org/tutorials/getting-started/)
+- [从先前版本升级](https://docs.bmad-method.org/how-to/upgrade-to-v6/)
+- [测试架构师文档](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
 
 
 ## 社区

docs/zh-cn/explanation/project-context.md

@@ -5,7 +5,7 @@ sidebar:
   order: 7
 ---
 
-`project-context.md` 文件是您的项目面向 AI 智能体的实施指南。类似于其他开发系统中的"宪法"，它记录了确保所有工作流中代码生成一致的规则、模式和偏好。
+[`project-context.md`](project-context.md) 文件是您的项目面向 AI 智能体的实施指南。类似于其他开发系统中的"宪法"，它记录了确保所有工作流中代码生成一致的规则、模式和偏好。
 
 ## 它的作用
 
@@ -14,11 +14,11 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代
 - 在不同的用户故事中做出不一致的决策
 - 错过项目特定的需求或约束
 
-`project-context.md` 文件通过以简洁、针对 LLM 优化的格式记录智能体需要了解的内容来解决这个问题。
+[`project-context.md`](project-context.md) 文件通过以简洁、针对 LLM 优化的格式记录智能体需要了解的内容来解决这个问题。
 
 ## 它的工作原理
 
-每个实施工作流都会自动加载 `project-context.md`（如果存在）。架构师工作流也会加载它，以便在设计架构时尊重您的技术偏好。
+每个实施工作流都会自动加载 [`project-context.md`](project-context.md)（如果存在）。架构师工作流也会加载它，以便在设计架构时尊重您的技术偏好。
 
 **由以下工作流加载：**
 - `create-architecture` — 在解决方案设计期间尊重技术偏好
@@ -30,7 +30,7 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代
 
 ## 何时创建
 
-`project-context.md` 文件在项目的任何阶段都很有用：
+[`project-context.md`](project-context.md) 文件在项目的任何阶段都很有用：
 
 | 场景 | 何时创建 | 目的 |
 |----------|----------------|---------|
@@ -127,7 +127,7 @@ touch _bmad-output/project-context.md
 
 ## 为什么重要
 
-没有 `project-context.md`，智能体会做出可能与您的项目不匹配的假设：
+没有 [`project-context.md`](project-context.md)，智能体会做出可能与您的项目不匹配的假设：
 
 | 没有上下文 | 有上下文 |
 |----------------|--------------|
@@ -143,7 +143,7 @@ touch _bmad-output/project-context.md
 
 ## 编辑和更新
 
-`project-context.md` 文件是一个动态文档。在以下情况下更新它：
+[`project-context.md`](project-context.md) 文件是一个动态文档。在以下情况下更新它：
 
 - 架构决策发生变化
 - 建立了新的约定

docs/zh-cn/index.md

@@ -8,7 +8,7 @@ BMad 方法（**B**reakthrough **M**ethod of **A**gile AI **D**riven Development
 如果您熟悉使用 Claude、Cursor 或 GitHub Copilot 等 AI 编码助手，就可以开始使用了。
 
 :::note[🚀 V6 已发布，我们才刚刚起步！]
-技能架构、BMad Builder v1、开发循环自动化以及更多功能正在开发中。**[查看路线图 →](/zh-cn/roadmap/)**
+技能架构、BMad Builder v1、开发循环自动化以及更多功能正在开发中。**[查看路线图 →](/roadmap/)**
 :::
 
 ## 新手入门？从教程开始
@@ -35,7 +35,7 @@ BMad 方法（**B**reakthrough **M**ethod of **A**gile AI **D**riven Development
 
 ## 扩展和自定义
 
-想要使用自己的智能体、工作流或模块来扩展 BMad 吗？**[BMad Builder（英文）](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展的框架和工具，无论是为 BMad 添加新功能还是从头开始构建全新的模块。
+想要使用自己的智能体、工作流或模块来扩展 BMad 吗？**[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展的框架和工具，无论是为 BMad 添加新功能还是从头开始构建全新的模块。
 
 ## 您需要什么
 

docs/zh-cn/reference/testing.md

@@ -65,7 +65,7 @@ Quinn 仅生成测试。如需代码审查和故事验证，请改用代码审
 
 TEA 是一个独立模块，提供专家智能体（Murat）和九个结构化工作流，用于企业级测试。它超越了测试生成，涵盖测试策略、基于风险的规划、质量门控和需求可追溯性。
 
-- **文档：** [TEA 模块文档（英文）](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
+- **文档：** [TEA 模块文档](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
 - **安装：** `npx bmad-method install` 并选择 TEA 模块
 - **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.2.0",
+  "version": "6.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.2.0",
+      "version": "6.1.0",
       "license": "MIT",
       "dependencies": {
         "@clack/core": "^1.0.0",

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.2.0",
+  "version": "6.1.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

src/bmm/workflows/1-analysis/bmad-create-product-brief/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-create-product-brief
 description: 'Create product brief through collaborative discovery. Use when the user says "lets create a product brief" or "help me create a project brief"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md

@@ -2,6 +2,9 @@
 # File References
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2: Product Vision Discovery
@@ -150,8 +153,8 @@ Prepare the following structure for document append:
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill with current vision content to dive deeper and refine
-- IF P: Invoke the `bmad-party-mode` skill to bring different perspectives to positioning and differentiation
+- IF A: Read fully and follow: {advancedElicitationTask} with current vision content to dive deeper and refine
+- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to positioning and differentiation
 - IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2], then read fully and follow: ./step-03-users.md
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
 

src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md

@@ -2,6 +2,9 @@
 # File References
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 3: Target Users Discovery
@@ -153,8 +156,8 @@ Prepare the following structure for document append:
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill with current user content to dive deeper into personas and journeys
-- IF P: Invoke the `bmad-party-mode` skill to bring different perspectives to validate user understanding
+- IF A: Read fully and follow: {advancedElicitationTask} with current user content to dive deeper into personas and journeys
+- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate user understanding
 - IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3], then read fully and follow: ./step-04-metrics.md
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
 

src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md

@@ -2,6 +2,9 @@
 # File References
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 4: Success Metrics Definition
@@ -156,8 +159,8 @@ Prepare the following structure for document append:
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill with current metrics content to dive deeper into success metric insights
-- IF P: Invoke the `bmad-party-mode` skill to bring different perspectives to validate comprehensive metrics
+- IF A: Read fully and follow: {advancedElicitationTask} with current metrics content to dive deeper into success metric insights
+- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate comprehensive metrics
 - IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4], then read fully and follow: ./step-05-scope.md
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
 

src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md

@@ -2,6 +2,9 @@
 # File References
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 5: MVP Scope Definition
@@ -170,8 +173,8 @@ Prepare the following structure for document append:
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill with current scope content to optimize scope definition
-- IF P: Invoke the `bmad-party-mode` skill to bring different perspectives to validate MVP scope
+- IF A: Read fully and follow: {advancedElicitationTask} with current scope content to optimize scope definition
+- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate MVP scope
 - IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4, 5], then read fully and follow: ./step-06-complete.md
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
 

src/bmm/workflows/1-analysis/bmad-product-brief-preview/prompts/contextual-discovery.md

@@ -12,9 +12,9 @@ Now that you know what the brief is about, fan out subagents in parallel to gath
 
 **Launch in parallel:**
 
-1. **Artifact Analyzer** (`../agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents. Also scans any specific paths the user provided. Returns structured synthesis of what it found.
+1. **Artifact Analyzer** (`agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents. Also scans any specific paths the user provided. Returns structured synthesis of what it found.
 
-2. **Web Researcher** (`../agents/web-researcher.md`) — Searches for competitive landscape, market context, trends, and relevant industry data. Returns structured findings scoped to the product domain.
+2. **Web Researcher** (`agents/web-researcher.md`) — Searches for competitive landscape, market context, trends, and relevant industry data. Returns structured findings scoped to the product domain.
 
 ### Graceful Degradation
 
@@ -38,20 +38,20 @@ Once subagent results return (or inline scanning completes):
 - Highlight anything surprising or worth discussing
 - Share the gaps you've identified
 - Ask: "Anything else you'd like to add, or shall we move on to filling in the details?"
-- Route to `guided-elicitation.md`
+- Route to `prompts/guided-elicitation.md`
 
 **Yolo mode:**
 - Absorb all findings silently
-- Skip directly to `draft-and-review.md` — you have enough to draft
+- Skip directly to `prompts/draft-and-review.md` — you have enough to draft
 - The user will refine later
 
 **Headless mode:**
 - Absorb all findings
-- Skip directly to `draft-and-review.md`
+- Skip directly to `prompts/draft-and-review.md`
 - No interaction
 
 ## Stage Complete
 
 This stage is complete when subagent results (or inline scanning fallback) have returned and findings are merged with user context. Route per mode:
-- **Guided** → `guided-elicitation.md`
-- **Yolo / Headless** → `draft-and-review.md`
+- **Guided** → `prompts/guided-elicitation.md`
+- **Yolo / Headless** → `prompts/draft-and-review.md`

src/bmm/workflows/1-analysis/bmad-product-brief-preview/prompts/draft-and-review.md

@@ -8,7 +8,7 @@
 
 ## Step 1: Draft the Executive Brief
 
-Use `../resources/brief-template.md` as a guide — adapt structure to fit the product's story.
+Use `resources/brief-template.md` as a guide — adapt structure to fit the product's story.
 
 **Writing principles:**
 - **Executive audience** — persuasive, clear, concise. 1-2 pages.
@@ -36,9 +36,9 @@ Before showing the draft to the user, run it through multiple review lenses in p
 
 **Launch in parallel:**
 
-1. **Skeptic Reviewer** (`../agents/skeptic-reviewer.md`) — "What's missing? What assumptions are untested? What could go wrong? Where is the brief vague or hand-wavy?"
+1. **Skeptic Reviewer** (`agents/skeptic-reviewer.md`) — "What's missing? What assumptions are untested? What could go wrong? Where is the brief vague or hand-wavy?"
 
-2. **Opportunity Reviewer** (`../agents/opportunity-reviewer.md`) — "What adjacent value propositions are being missed? What market angles or partnerships could strengthen this? What's underemphasized?"
+2. **Opportunity Reviewer** (`agents/opportunity-reviewer.md`) — "What adjacent value propositions are being missed? What market angles or partnerships could strengthen this? What's underemphasized?"
 
 3. **Contextual Reviewer** — You (the main agent) pick the most useful third lens based on THIS specific product. Choose the lens that addresses the SINGLE BIGGEST RISK that the skeptic and opportunity reviewers won't naturally catch. Examples:
    - For healthtech: "Regulatory and compliance risk reviewer"
@@ -65,7 +65,7 @@ After all reviews complete:
 
 ## Step 4: Present to User
 
-**Headless mode:** Skip to `finalize.md` — no user interaction. Save the improved draft directly.
+**Headless mode:** Skip to `prompts/finalize.md` — no user interaction. Save the improved draft directly.
 
 **Yolo and Guided modes:**
 
@@ -83,4 +83,4 @@ Present reviewer findings with brief rationale, then offer: "Want me to dig into
 
 ## Stage Complete
 
-This stage is complete when: (a) the draft has been reviewed by all three lenses and improvements integrated, AND either (autonomous) save and route directly, or (guided/yolo) the user is satisfied. Route to `finalize.md`.
+This stage is complete when: (a) the draft has been reviewed by all three lenses and improvements integrated, AND either (autonomous) save and route directly, or (guided/yolo) the user is satisfied. Route to `prompts/finalize.md`.

src/bmm/workflows/1-analysis/bmad-product-brief-preview/prompts/finalize.md

@@ -72,4 +72,4 @@ purpose: "Token-efficient context for downstream PRD creation"
 
 ## Stage Complete
 
-This is the terminal stage. After delivering the completion message and file paths, the workflow is done. If the user requests further revisions, loop back to `draft-and-review.md`. Otherwise, exit.
+This is the terminal stage. After delivering the completion message and file paths, the workflow is done. If the user requests further revisions, loop back to `prompts/draft-and-review.md`. Otherwise, exit.

src/bmm/workflows/1-analysis/bmad-product-brief-preview/prompts/guided-elicitation.md

@@ -5,7 +5,7 @@
 
 **Goal:** Fill the gaps in what you know. By now you have the user's brain dump, artifact analysis, and web research. This stage is about smart, targeted questioning — not rote section-by-section interrogation.
 
-**Skip this stage entirely in Yolo and Autonomous modes** — go directly to `draft-and-review.md`.
+**Skip this stage entirely in Yolo and Autonomous modes** — go directly to `prompts/draft-and-review.md`.
 
 ## Approach
 
@@ -67,4 +67,4 @@ If the user is providing complete, confident answers and you have solid coverage
 
 ## Stage Complete
 
-This stage is complete when sufficient substance exists to draft a compelling brief and the user confirms readiness. Route to `draft-and-review.md`.
+This stage is complete when sufficient substance exists to draft a compelling brief and the user confirms readiness. Route to `prompts/draft-and-review.md`.

src/bmm/workflows/1-analysis/research/bmad-domain-research/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-domain-research
 description: 'Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/1-analysis/research/bmad-market-research/SKILL.md

@@ -3,4 +3,4 @@ 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]".'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/1-analysis/research/bmad-technical-research/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-technical-research
 description: 'Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-create-ux-design
 description: 'Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/2-plan-workflows/bmad-edit-prd/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-edit-prd
 description: 'Edit an existing PRD. Use when the user says "edit this PRD".'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md

@@ -1,6 +1,12 @@
 ---
+name: 'step-e-01-discovery'
+description: 'Discovery & Understanding - Understand what user wants to edit and detect PRD format'
+
 # File references (ONLY variables used in this step)
+altStepFile: './step-e-01b-legacy-conversion.md'
 prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step E-1: Discovery & Understanding
@@ -184,7 +190,7 @@ Display: "**Edit Requirements Understood**
 
 **Proceeding to deep review and analysis...**"
 
-Read fully and follow: `./step-e-02-review.md`
+Read fully and follow: next step (step-e-02-review.md)
 
 **IF PRD is Legacy (Non-Standard) AND no validation report:**
 
@@ -211,7 +217,7 @@ Present MENU OPTIONS below for user selection
 
 #### Menu Handling Logic:
 
-- IF C (Convert): Read fully and follow: `./step-e-01b-legacy-conversion.md`
+- IF C (Convert): Read fully and follow: {altStepFile} (step-e-01b-legacy-conversion.md)
 - IF E (Edit As-Is): Display "Proceeding with edits..." then load next step
 - IF X (Exit): Display summary and exit
 - IF Any other: help user, then redisplay menu

src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md

@@ -1,5 +1,9 @@
 ---
+name: 'step-e-01b-legacy-conversion'
+description: 'Legacy PRD Conversion Assessment - Analyze legacy PRD and propose conversion strategy'
+
 # File references (ONLY variables used in this step)
+nextStepFile: './step-e-02-review.md'
 prdFile: '{prd_file_path}'
 prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
 ---
@@ -178,7 +182,7 @@ Edit goals: {summary}
 
 **Proceeding to deep review...**"
 
-Read fully and follow: `./step-e-02-review.md`
+Read fully and follow: {nextStepFile} (step-e-02-review.md)
 
 ---
 

src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-02-review.md

@@ -1,8 +1,13 @@
 ---
+name: 'step-e-02-review'
+description: 'Deep Review & Analysis - Thoroughly review existing PRD and prepare detailed change plan'
+
 # File references (ONLY variables used in this step)
+nextStepFile: './step-e-03-edit.md'
 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'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
 ---
 
 # Step E-2: Deep Review & Analysis
@@ -200,7 +205,7 @@ Display: "**Change Plan Approved**
 
 **Proceeding to edit step...**"
 
-Read fully and follow: `./step-e-03-edit.md`
+Read fully and follow: {nextStepFile} (step-e-03-edit.md)
 
 ### 7. Present MENU OPTIONS (If User Wants Discussion)
 
@@ -215,9 +220,9 @@ Read fully and follow: `./step-e-03-edit.md`
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill, then return to discussion
-- IF P: Invoke the `bmad-party-mode` skill, then return to discussion
-- IF C: Document approval, then load step-e-03-edit.md
+- IF A: Read fully and follow: {advancedElicitationTask}, then return to discussion
+- IF P: Read fully and follow: {partyModeWorkflow}, then return to discussion
+- IF C: Document approval, then load {nextStepFile}
 - IF Any other: discuss, then redisplay menu
 
 ---

src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-03-edit.md

@@ -1,5 +1,9 @@
 ---
+name: 'step-e-03-edit'
+description: 'Edit & Update - Apply changes to PRD following approved change plan'
+
 # File references (ONLY variables used in this step)
+nextStepFile: './step-e-04-complete.md'
 prdFile: '{prd_file_path}'
 prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
 ---
@@ -207,7 +211,7 @@ Display:
 
 ### 8. Present MENU OPTIONS
 
-**[V] Run Validation** - Execute full validation workflow (./steps-v/step-v-01-discovery.md)
+**[V] Run Validation** - Execute full validation workflow (steps-v/step-v-01-discovery.md)
 **[S] Summary Only** - End with summary of changes (no validation)
 **[A] Adjust** - Make additional edits
 **[X] Exit** - Exit edit workflow
@@ -219,7 +223,7 @@ Display:
 
 #### Menu Handling Logic:
 
-- IF V (Validate): Display "Starting validation workflow..." then read fully and follow: `./steps-v/step-v-01-discovery.md`
+- IF V (Validate): Display "Starting validation workflow..." then read fully and follow: steps-v/step-v-01-discovery.md
 - IF S (Summary): Present edit summary and exit
 - IF A (Adjust): Accept additional requirements, loop back to editing
 - IF X (Exit): Display summary and exit

src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-04-complete.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-e-04-complete'
+description: 'Complete & Validate - Present options for next steps including full validation'
+
 # 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'
@@ -124,7 +127,7 @@ Display:
   - Display: "**Additional Edits**"
   - Ask: "What additional edits would you like to make?"
   - Accept input, then display: "**Returning to edit step...**"
-  - Read fully and follow: `./step-e-03-edit.md` again
+  - Read fully and follow: step-e-03-edit.md again
 
 - **IF S (Summary):**
   - Display detailed summary including:

src/bmm/workflows/2-plan-workflows/bmad-edit-prd/workflow.md

@@ -1,5 +1,6 @@
 ---
 main_config: '{project-root}/_bmad/bmm/config.yaml'
+editWorkflow: './steps-e/step-e-01-discovery.md'
 ---
 
 # PRD Edit Workflow
@@ -60,4 +61,4 @@ Load and read full config from {main_config} and resolve:
 
 Prompt for PRD path: "Which PRD would you like to edit? Please provide the path to the PRD.md file."
 
-Then read fully and follow: `./steps-e/step-e-01-discovery.md`
+Then read fully and follow: `{editWorkflow}` (steps-e/step-e-01-discovery.md)

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-validate-prd
 description: 'Validate a PRD against standards. Use when the user says "validate this PRD" or "run PRD validation"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md

@@ -1,6 +1,11 @@
 ---
+name: 'step-v-01-discovery'
+description: 'Document Discovery & Confirmation - Handle fresh context validation, confirm PRD path, discover input documents'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-02-format-detection.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 prdPurpose: '../data/prd-purpose.md'
 ---
 
@@ -190,8 +195,8 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill, and when finished redisplay the menu
-- IF P: Invoke the `bmad-party-mode` skill, and when finished redisplay the menu
+- IF A: Read fully and follow: {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Read fully and follow: {partyModeWorkflow}, and when finished redisplay the menu
 - IF C: Read fully and follow: {nextStepFile} to begin format detection
 - IF user provides additional document: Load it, update report, redisplay summary
 - IF Any other: help user, then redisplay menu

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-02-format-detection.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-02-format-detection'
+description: 'Format Detection & Structure Analysis - Classify PRD format and route appropriately'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-03-density-validation.md'
 altStepFile: './step-v-02b-parity-check.md'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-02b-parity-check.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-02b-parity-check'
+description: 'Document Parity Check - Analyze non-standard PRD and identify gaps to achieve BMAD PRD parity'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-03-density-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-03-density-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-03-density-validation'
+description: 'Information Density Check - Scan for anti-patterns that violate information density principles'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-04-brief-coverage-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-04-brief-coverage-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-04-brief-coverage-validation'
+description: 'Product Brief Coverage Check - Validate PRD covers all content from Product Brief (if used as input)'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-05-measurability-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-05-measurability-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-05-measurability-validation'
+description: 'Measurability Validation - Validate that all requirements (FRs and NFRs) are measurable and testable'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-06-traceability-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-06-traceability-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-06-traceability-validation'
+description: 'Traceability Validation - Validate the traceability chain from vision → success → journeys → FRs is intact'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-07-implementation-leakage-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-07-implementation-leakage-validation'
+description: 'Implementation Leakage Check - Ensure FRs and NFRs don\'t include implementation details'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-08-domain-compliance-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-08-domain-compliance-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-08-domain-compliance-validation'
+description: 'Domain Compliance Validation - Validate domain-specific requirements are present for high-complexity domains'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-09-project-type-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-09-project-type-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-09-project-type-validation'
+description: 'Project-Type Compliance Validation - Validate project-type specific requirements are properly documented'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-10-smart-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-10-smart-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-10-smart-validation'
+description: 'SMART Requirements Validation - Validate Functional Requirements meet SMART quality criteria'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-11-holistic-quality-validation.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-11-holistic-quality-validation.md

@@ -1,8 +1,12 @@
 ---
+name: 'step-v-11-holistic-quality-validation'
+description: 'Holistic Quality Assessment - Assess PRD as cohesive, compelling document - is it a good PRD?'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-12-completeness-validation.md'
 prdFile: '{prd_file_path}'
 validationReportPath: '{validation_report_path}'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
 ---
 
 # Step 11: Holistic Quality Assessment
@@ -63,8 +67,8 @@ Assess the PRD as a cohesive, compelling document - evaluating document flow, du
 
 "Perform holistic quality assessment on this PRD using multi-perspective evaluation:
 
-**Advanced Elicitation workflow:**
-Invoke the `bmad-advanced-elicitation` skill
+**Read fully and follow the Advanced Elicitation workflow:**
+{advancedElicitationTask}
 
 **Evaluate the PRD from these perspectives:**
 

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-12-completeness-validation.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-12-completeness-validation'
+description: 'Completeness Check - Final comprehensive completeness check before report generation'
+
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-13-report-complete.md'
 prdFile: '{prd_file_path}'

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-13-report-complete.md

@@ -1,4 +1,7 @@
 ---
+name: 'step-v-13-report-complete'
+description: 'Validation Report Complete - Finalize report, summarize findings, present to user, offer next steps'
+
 # File references (ONLY variables used in this step)
 validationReportPath: '{validation_report_path}'
 prdFile: '{prd_file_path}'
@@ -177,9 +180,9 @@ Display:
   - After review, return to menu
 
 - **IF E (Use Edit Workflow):**
-  - Explain: "The Edit workflow can use this validation report to systematically address issues. Edit mode will guide you through discovering what to edit, reviewing the PRD, and applying targeted improvements."
+  - Explain: "The Edit workflow (steps-e/) can use this validation report to systematically address issues. Edit mode will guide you through discovering what to edit, reviewing the PRD, and applying targeted improvements."
   - Offer: "Would you like to launch Edit mode now? It will help you fix validation findings systematically."
-  - If yes: Invoke the `bmad-edit-prd` skill, passing the validation report path as context
+  - If yes: Read fully and follow: steps-e/step-e-01-discovery.md
   - If no: Return to menu
 
 - **IF F (Fix Simpler Items):**

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md

@@ -4,6 +4,8 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio
 
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-02-format-detection.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 prdPurpose: '../data/prd-purpose.md'
 ---
 
@@ -193,8 +195,8 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill, and when finished redisplay the menu
-- IF P: Invoke the `bmad-party-mode` skill, and when finished redisplay the menu
+- IF A: Read fully and follow: {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Read fully and follow: {partyModeWorkflow}, and when finished redisplay the menu
 - IF C: Read fully and follow: {nextStepFile} to begin format detection
 - IF user provides additional document: Load it, update report, redisplay summary
 - IF Any other: help user, then redisplay menu

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md

@@ -6,6 +6,7 @@ description: 'Holistic Quality Assessment - Assess PRD as cohesive, compelling d
 nextStepFile: './step-v-12-completeness-validation.md'
 prdFile: '{prd_file_path}'
 validationReportPath: '{validation_report_path}'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
 ---
 
 # Step 11: Holistic Quality Assessment
@@ -66,8 +67,8 @@ Assess the PRD as a cohesive, compelling document - evaluating document flow, du
 
 "Perform holistic quality assessment on this PRD using multi-perspective evaluation:
 
-**Advanced Elicitation workflow:**
-Invoke the `bmad-advanced-elicitation` skill
+**Read fully and follow the Advanced Elicitation workflow:**
+{advancedElicitationTask}
 
 **Evaluate the PRD from these perspectives:**
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md

@@ -182,7 +182,7 @@ Display:
 - **IF E (Use Edit Workflow):**
   - Explain: "The Edit workflow (steps-e/) can use this validation report to systematically address issues. Edit mode will guide you through discovering what to edit, reviewing the PRD, and applying targeted improvements."
   - Offer: "Would you like to launch Edit mode now? It will help you fix validation findings systematically."
-  - If yes: Read fully and follow: `./steps-e/step-e-01-discovery.md`
+  - If yes: Read fully and follow: steps-e/step-e-01-discovery.md
   - If no: Return to menu
 
 - **IF F (Fix Simpler Items):**

src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-check-implementation-readiness
 description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness".'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/3-solutioning/bmad-create-architecture/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-create-architecture
 description: 'Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-create-epics-and-stories
 description: 'Break requirements into epics and user stories. Use when the user says "create the epics and stories list"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/4-implementation/bmad-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-code-review
-description: 'Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"'
+description: 'Perform adversarial code review finding specific issues. Use when the user says "run code review" or "review this code"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/4-implementation/bmad-code-review/checklist.md

@@ -0,0 +1,23 @@
+# Senior Developer Review - Validation Checklist
+
+- [ ] Story file loaded from `{{story_path}}`
+- [ ] Story Status verified as reviewable (review)
+- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
+- [ ] Story Context located or warning recorded
+- [ ] Epic Tech Spec located or warning recorded
+- [ ] Architecture/standards docs loaded (as available)
+- [ ] Tech stack detected and documented
+- [ ] MCP doc search performed (or web fallback) and references captured
+- [ ] Acceptance Criteria cross-checked against implementation
+- [ ] File List reviewed and validated for completeness
+- [ ] Tests identified and mapped to ACs; gaps noted
+- [ ] Code quality review performed on changed files
+- [ ] Security review performed on changed files and dependencies
+- [ ] Outcome decided (Approve/Changes Requested/Blocked)
+- [ ] Review notes appended under "Senior Developer Review (AI)"
+- [ ] Change Log updated with review entry
+- [ ] Status updated according to settings (if enabled)
+- [ ] Sprint status synced (if sprint tracking enabled)
+- [ ] Story saved successfully
+
+_Reviewer: {{user_name}} on {{date}}_

src/bmm/workflows/4-implementation/bmad-code-review/discover-inputs.md

@@ -0,0 +1,88 @@
+# Discover Inputs Protocol
+
+**Objective:** Intelligently load project files (whole or sharded) based on the workflow's Input Files configuration.
+
+**Prerequisite:** Only execute this protocol if the workflow defines an Input Files section. If no input file patterns are configured, skip this entirely.
+
+---
+
+## Step 1: Parse Input File Patterns
+
+- Read the Input Files table from the workflow configuration.
+- For each input group (prd, architecture, epics, ux, etc.), note the **load strategy** if specified.
+
+## Step 2: Load Files Using Smart Strategies
+
+For each pattern in the Input Files table, work through the following substeps in order:
+
+### 2a: Try Sharded Documents First
+
+If a sharded pattern exists for this input, determine the load strategy (defaults to **FULL_LOAD** if not specified), then apply the matching strategy:
+
+#### FULL_LOAD Strategy
+
+Load ALL files in the sharded directory. Use this for PRD, Architecture, UX, brownfield docs, or whenever the full picture is needed.
+
+1. Use the glob pattern to find ALL `.md` files (e.g., `{planning_artifacts}/*architecture*/*.md`).
+2. Load EVERY matching file completely.
+3. Concatenate content in logical order: `index.md` first if it exists, then alphabetical.
+4. Store the combined result in a variable named `{pattern_name_content}` (e.g., `{architecture_content}`).
+
+#### SELECTIVE_LOAD Strategy
+
+Load a specific shard using a template variable. Example: used for epics with `{{epic_num}}`.
+
+1. Check for template variables in the sharded pattern (e.g., `{{epic_num}}`).
+2. If the variable is undefined, ask the user for the value OR infer it from context.
+3. Resolve the template to a specific file path.
+4. Load that specific file.
+5. Store in variable: `{pattern_name_content}`.
+
+#### INDEX_GUIDED Strategy
+
+Load index.md, analyze the structure and description of each doc in the index, then intelligently load relevant docs.
+
+**DO NOT BE LAZY** -- use best judgment to load documents that might have relevant information, even if there is only a 5% chance of relevance.
+
+1. Load `index.md` from the sharded directory.
+2. Parse the table of contents, links, and section headers.
+3. Analyze the workflow's purpose and objective.
+4. Identify which linked/referenced documents are likely relevant.
+   - *Example:* If the workflow is about authentication and the index shows "Auth Overview", "Payment Setup", "Deployment" -- load the auth docs, consider deployment docs, skip payment.
+5. Load all identified relevant documents.
+6. Store combined content in variable: `{pattern_name_content}`.
+
+**When in doubt, LOAD IT** -- context is valuable, and being thorough is better than missing critical info.
+
+---
+
+After applying the matching strategy, mark the pattern as **RESOLVED** and move to the next pattern.
+
+### 2b: Try Whole Document if No Sharded Found
+
+If no sharded matches were found OR no sharded pattern exists for this input:
+
+1. Attempt a glob match on the "whole" pattern (e.g., `{planning_artifacts}/*prd*.md`).
+2. If matches are found, load ALL matching files completely (no offset/limit).
+3. Store content in variable: `{pattern_name_content}` (e.g., `{prd_content}`).
+4. Mark pattern as **RESOLVED** and move to the next pattern.
+
+### 2c: Handle Not Found
+
+If no matches were found for either sharded or whole patterns:
+
+1. Set `{pattern_name_content}` to empty string.
+2. Note in session: "No {pattern_name} files found" -- this is not an error, just unavailable. Offer the user a chance to provide the file.
+
+## Step 3: Report Discovery Results
+
+List all loaded content variables with file counts. Example:
+
+```
+OK Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ...
+OK Loaded {architecture_content} from 1 file: Architecture.md
+OK Loaded {epics_content} from selective load: epics/epic-3.md
+-- No ux_design files found
+```
+
+This gives the workflow transparency into what context is available.

src/bmm/workflows/4-implementation/bmad-code-review/steps/step-01-gather-context.md

@@ -1,61 +0,0 @@
----
-diff_output: '' # set at runtime
-spec_file: '' # set at runtime (path or empty)
-review_mode: '' # set at runtime: "full" or "no-spec"
----
-
-# Step 1: Gather Context
-
-## RULES
-
-- 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 modify any files. This step is read-only.
-
-## INSTRUCTIONS
-
-1. **Detect review intent from invocation text.** Check the triggering prompt for phrases that map to a review mode:
-   - "staged" / "staged changes" → Staged changes only
-   - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged)
-   - "branch diff" / "vs main" / "against main" / "compared to {branch}" → Branch diff (extract base branch if mentioned)
-   - "commit range" / "last N commits" / "{sha}..{sha}" → Specific commit range
-   - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes)
-   - 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.
-   - **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:
-   - **Uncommitted changes** (staged + unstaged)
-   - **Staged changes only**
-   - **Branch diff** vs a base branch (ask which base branch)
-   - **Specific commit range** (ask for the range)
-   - **Provided diff or file list** (user pastes or provides a path)
-
-3. Construct `{diff_output}` from the chosen source.
-   - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch.
-   - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range.
-   - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff.
-   - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- <path1> <path2> ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null <path>` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
-   - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
-
-4. Ask the user: **Is there a spec or story file that provides context for these changes?**
-   - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
-   - If no: set `{review_mode}` = `"no-spec"`.
-
-5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
-
-6. Sanity check: if `{diff_output}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group.
-   - If the user opts to chunk: agree on the first group, narrow `{diff_output}` accordingly, and list the remaining groups for the user to note for follow-up runs.
-   - If the user declines: proceed as-is with the full diff.
-
-### CHECKPOINT
-
-Present a summary before proceeding: diff stats (files changed, lines added/removed), `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed.
-
-
-## NEXT
-
-Read fully and follow `./step-02-review.md`

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

@@ -1,41 +0,0 @@
----
-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. Launch parallel subagents. Each subagent gets NO conversation history from this session:
-
-   - **Blind Hunter** -- Invoke the `bmad-review-adversarial-general` skill in a subagent. Pass `content` = `{diff_output}` only. No spec, no project access.
-
-   - **Edge Case Hunter** -- Invoke the `bmad-review-edge-case-hunter` skill in a subagent. Pass `content` = `{diff_output}`. This subagent has read access to the project.
-
-   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) -- A subagent that 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.
-
-2. **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.
-
-3. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided."
-
-4. **Fallback** (if subagents are not available): Generate prompt files in `{implementation_artifacts}` -- one per active reviewer:
-   - `review-blind-hunter.md` (always)
-   - `review-edge-case-hunter.md` (always)
-   - `review-acceptance-auditor.md` (only if `{review_mode}` = `"full"`)
-
-   HALT. Tell the user to run each prompt in a separate session and paste back findings. When findings are pasted, resume from this point and proceed to step 3.
-
-5. Collect all findings from the completed layers.
-
-
-## NEXT
-
-Read fully and follow `./step-03-triage.md`

src/bmm/workflows/4-implementation/bmad-code-review/steps/step-03-triage.md

@@ -1,50 +0,0 @@
----
----
-
-# Step 3: Triage
-
-## RULES
-
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- Be precise. When uncertain between categories, prefer the more conservative classification.
-
-## INSTRUCTIONS
-
-1. **Normalize** findings into a common format. Expected input formats:
-   - Adversarial (Blind Hunter): markdown list of descriptions
-   - Edge Case Hunter: JSON array with `location`, `trigger_condition`, `guard_snippet`, `potential_consequence` fields
-   - Acceptance Auditor: markdown list with title, AC/constraint reference, and evidence
-
-   If a layer's output does not match its expected format, attempt best-effort parsing. Note any parsing issues for the user.
-
-   Convert all to a unified list where each finding has:
-   - `id` -- sequential integer
-   - `source` -- `blind`, `edge`, `auditor`, or merged sources (e.g., `blind+edge`)
-   - `title` -- one-line summary
-   - `detail` -- full description
-   - `location` -- file and line reference (if available)
-
-2. **Deduplicate.** If two or more findings describe the same issue, merge them into one:
-   - Use the most specific finding as the base (prefer edge-case JSON with location over adversarial prose).
-   - Append any unique detail, reasoning, or location references from the other finding(s) into the surviving `detail` field.
-   - 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.
-   - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
-   - **reject** -- 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).
-
-4. **Drop** all `reject` findings. Record the reject 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.
-
-6. If zero findings remain after dropping rejects and no layers failed, note clean review.
-
-
-## NEXT
-
-Read fully and follow `./step-04-present.md`

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

@@ -1,38 +0,0 @@
----
----
-
-# Step 4: Present
-
-## RULES
-
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- Do NOT auto-fix anything. Present findings and let the user decide next steps.
-
-## INSTRUCTIONS
-
-1. Group remaining findings by category.
-
-2. Present to the user in this order (include a section only if findings exist in that category):
-
-   - **Intent Gaps**: "These findings suggest the captured intent is incomplete. Consider clarifying intent before proceeding."
-     - List each with title + detail.
-
-   - **Bad Spec**: "These findings suggest the spec should be amended. Consider regenerating or amending the spec with this context:"
-     - List each with title + detail + suggested spec amendment.
-
-   - **Patch**: "These are fixable code issues:"
-     - List each with title + detail + location (if available).
-
-   - **Defer**: "Pre-existing issues surfaced by this review (not caused by current changes):"
-     - List each with title + detail.
-
-3. Summary line: **X** intent_gap, **Y** bad_spec, **Z** patch, **W** defer findings. **R** findings rejected as noise.
-
-4. If clean review (zero findings across all layers after triage): state that N findings were raised but all were classified as noise, or that no findings were raised at all (as applicable).
-
-5. Offer the user next steps (recommendations, not automated actions):
-   - If `patch` findings exist: "These can be addressed in a follow-up implementation pass or manually."
-   - If `intent_gap` or `bad_spec` findings exist: "Consider running the planning workflow to clarify intent or amend the spec before continuing."
-   - If only `defer` findings remain: "No action needed for this change. Deferred items are noted for future attention."
-
-Workflow complete.

src/bmm/workflows/4-implementation/bmad-code-review/workflow.md

@@ -1,54 +1,261 @@
----
-main_config: '{project-root}/_bmad/bmm/config.yaml'
----
-
 # Code Review Workflow
 
-**Goal:** Review code changes adversarially using parallel review layers and structured triage.
+**Goal:** Perform adversarial code review finding specific issues.
 
-**Your Role:** You are an elite code reviewer. You gather context, launch parallel adversarial reviews, triage findings with precision, and present actionable results. No noise, no filler.
+**Your Role:** Adversarial Code Reviewer.
+- YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing!
+- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
+- Generate all documents in {document_output_language}
+- Your purpose: Validate story file claims against actual implementation
+- Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?
+- Be thorough and specific — find real issues, not manufactured ones. If the code is genuinely good after fixes, say so
+- Read EVERY file in the File List - verify implementation against story requirements
+- Tasks marked complete but not done = CRITICAL finding
+- Acceptance Criteria not implemented = HIGH severity finding
+- Do not review files that are not part of the application's source code. Always exclude the `_bmad/` and `_bmad-output/` folders from the review. Always exclude IDE and CLI configuration folders like `.cursor/` and `.windsurf/` and `.claude/`
 
+---
 
-## WORKFLOW ARCHITECTURE
+## INITIALIZATION
 
-This uses **step-file architecture** for disciplined execution:
+### Configuration Loading
 
-- **Micro-file Design**: Each step is self-contained and followed exactly
-- **Just-In-Time Loading**: Only load the current step file
-- **Sequential Enforcement**: Complete steps in order, no skipping
-- **State Tracking**: Persist progress via in-memory variables
-- **Append-Only Building**: Build artifacts incrementally
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
-### Step Processing Rules
-
-1. **READ COMPLETELY**: Read the entire step file before acting
-2. **FOLLOW SEQUENCE**: Execute sections in order
-3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
-4. **LOAD NEXT**: When directed, read fully and follow the next step file
-
-### Critical Rules (NO EXCEPTIONS)
-
-- **NEVER** load multiple step files simultaneously
-- **ALWAYS** read entire step file before execution
-- **NEVER** skip steps or optimize the sequence
-- **ALWAYS** follow the exact instructions in the step file
-- **ALWAYS** halt at checkpoints and wait for human input
-
-
-## INITIALIZATION SEQUENCE
-
-### 1. Configuration Loading
-
-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`
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
 - `date` as system-generated current datetime
+
+### Paths
+
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+
+### Input Files
+
+| Input | Description | Path Pattern(s) | Load Strategy |
+|-------|-------------|------------------|---------------|
+| architecture | System architecture for review context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD |
+| ux_design | UX design specification (if UI review) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | FULL_LOAD |
+| epics | Epic containing story being reviewed | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD |
+
+### Context
+
 - `project_context` = `**/project-context.md` (load if exists)
-- CLAUDE.md / memory files (load if exist)
 
-YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.
+---
 
-### 2. First Step Execution
+## EXECUTION
 
-Read fully and follow: `./steps/step-01-gather-context.md` to begin the workflow.
+<workflow>
+
+<step n="1" goal="Load story and discover changes">
+  <action>Use provided {{story_path}} or ask user which story file to review</action>
+  <action>Read COMPLETE story file</action>
+  <action>Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story
+    metadata</action>
+  <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log</action>
+
+  <!-- Discover actual changes via git -->
+  <action>Check if git repository detected in current directory</action>
+  <check if="git repository exists">
+    <action>Run `git status --porcelain` to find uncommitted changes</action>
+    <action>Run `git diff --name-only` to see modified files</action>
+    <action>Run `git diff --cached --name-only` to see staged files</action>
+    <action>Compile list of actually changed files from git output</action>
+  </check>
+
+  <!-- Cross-reference story File List vs git reality -->
+  <action>Compare story's Dev Agent Record → File List with actual git changes</action>
+  <action>Note discrepancies:
+    - Files in git but not in story File List
+    - Files in story File List but no git changes
+    - Missing documentation of what was actually changed
+  </action>
+
+  <action>Read fully and follow `./discover-inputs.md` to load all input files</action>
+  <action>Load {project_context} for coding standards (if exists)</action>
+</step>
+
+<step n="2" goal="Build review attack plan">
+  <action>Extract ALL Acceptance Criteria from story</action>
+  <action>Extract ALL Tasks/Subtasks with completion status ([x] vs [ ])</action>
+  <action>From Dev Agent Record → File List, compile list of claimed changes</action>
+
+  <action>Create review plan:
+    1. **AC Validation**: Verify each AC is actually implemented
+    2. **Task Audit**: Verify each [x] task is really done
+    3. **Code Quality**: Security, performance, maintainability
+    4. **Test Quality**: Real tests vs placeholder bullshit
+  </action>
+</step>
+
+<step n="3" goal="Execute adversarial review">
+  <critical>VALIDATE EVERY CLAIM - Check git reality vs story claims</critical>
+
+  <!-- Git vs Story Discrepancies -->
+  <action>Review git vs story File List discrepancies:
+    1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation)
+    2. **Story lists files but no git changes** → HIGH finding (false claims)
+    3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue)
+  </action>
+
+  <!-- Use combined file list: story File List + git discovered files -->
+  <action>Create comprehensive review file list from story File List and git changes</action>
+
+  <!-- AC Validation -->
+  <action>For EACH Acceptance Criterion:
+    1. Read the AC requirement
+    2. Search implementation files for evidence
+    3. Determine: IMPLEMENTED, PARTIAL, or MISSING
+    4. If MISSING/PARTIAL → HIGH SEVERITY finding
+  </action>
+
+  <!-- Task Completion Audit -->
+  <action>For EACH task marked [x]:
+    1. Read the task description
+    2. Search files for evidence it was actually done
+    3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding
+    4. Record specific proof (file:line)
+  </action>
+
+  <!-- Code Quality Deep Dive -->
+  <action>For EACH file in comprehensive review list:
+    1. **Security**: Look for injection risks, missing validation, auth issues
+    2. **Performance**: N+1 queries, inefficient loops, missing caching
+    3. **Error Handling**: Missing try/catch, poor error messages
+    4. **Code Quality**: Complex functions, magic numbers, poor naming
+    5. **Test Quality**: Are tests real assertions or placeholders?
+  </action>
+
+  <check if="total_issues_found == 0">
+    <action>Double-check by re-examining code for:
+      - Edge cases and null handling
+      - Architecture violations
+      - Integration issues
+      - Dependency problems
+    </action>
+    <action>If still no issues found after thorough re-examination, that is a valid outcome — report a clean review</action>
+  </check>
+</step>
+
+<step n="4" goal="Present findings and fix them">
+  <action>Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)</action>
+  <action>Set {{fixed_count}} = 0</action>
+  <action>Set {{action_count}} = 0</action>
+
+  <output>**🔥 CODE REVIEW FINDINGS, {user_name}!**
+
+    **Story:** {{story_file}}
+    **Git vs Story Discrepancies:** {{git_discrepancy_count}} found
+    **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low
+
+    ## 🔴 CRITICAL ISSUES
+    - Tasks marked [x] but not actually implemented
+    - Acceptance Criteria not implemented
+    - Story claims files changed but no git evidence
+    - Security vulnerabilities
+
+    ## 🟡 MEDIUM ISSUES
+    - Files changed but not documented in story File List
+    - Uncommitted changes not tracked
+    - Performance problems
+    - Poor test coverage/quality
+    - Code maintainability issues
+
+    ## 🟢 LOW ISSUES
+    - Code style improvements
+    - Documentation gaps
+    - Git commit message quality
+  </output>
+
+  <ask>What should I do with these issues?
+
+    1. **Fix them automatically** - I'll update the code and tests
+    2. **Create action items** - Add to story Tasks/Subtasks for later
+    3. **Show me details** - Deep dive into specific issues
+
+    Choose [1], [2], or specify which issue to examine:</ask>
+
+  <check if="user chooses 1">
+    <action>Fix all HIGH and MEDIUM issues in the code</action>
+    <action>Add/update tests as needed</action>
+    <action>Update File List in story if files changed</action>
+    <action>Update story Dev Agent Record with fixes applied</action>
+    <action>Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed</action>
+    <action>Set {{action_count}} = 0</action>
+  </check>
+
+  <check if="user chooses 2">
+    <action>Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks</action>
+    <action>For each issue: `- [ ] [AI-Review][Severity] Description [file:line]`</action>
+    <action>Set {{action_count}} = number of action items created</action>
+    <action>Set {{fixed_count}} = 0</action>
+  </check>
+
+  <check if="user chooses 3">
+    <action>Show detailed explanation with code examples</action>
+    <action>Return to fix decision</action>
+  </check>
+</step>
+
+<step n="5" goal="Update story status and sync sprint tracking">
+  <!-- Determine new status based on review outcome -->
+  <check if="all HIGH and MEDIUM issues fixed AND all ACs implemented">
+    <action>Set {{new_status}} = "done"</action>
+    <action>Update story Status field to "done"</action>
+  </check>
+  <check if="HIGH or MEDIUM issues remain OR ACs not fully implemented">
+    <action>Set {{new_status}} = "in-progress"</action>
+    <action>Update story Status field to "in-progress"</action>
+  </check>
+  <action>Save story file</action>
+
+  <!-- Determine sprint tracking status -->
+  <check if="{sprint_status} file exists">
+    <action>Set {{current_sprint_status}} = "enabled"</action>
+  </check>
+  <check if="{sprint_status} file does NOT exist">
+    <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
+  </check>
+
+  <!-- Sync sprint-status.yaml when story status changes (only if sprint tracking enabled) -->
+  <check if="{{current_sprint_status}} != 'no-sprint-tracking'">
+    <action>Load the FULL file: {sprint_status}</action>
+    <action>Find development_status key matching {{story_key}}</action>
+
+    <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>
+
+    <check if="story key not found in sprint status">
+      <output>⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml</output>
+    </check>
+  </check>
+
+  <check if="{{current_sprint_status}} == 'no-sprint-tracking'">
+    <output>ℹ️ Story status updated (no sprint tracking configured)</output>
+  </check>
+
+  <output>**✅ Review Complete!**
+
+    **Story Status:** {{new_status}}
+    **Issues Fixed:** {{fixed_count}}
+    **Action Items Created:** {{action_count}}
+
+    {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}}
+  </output>
+</step>
+
+</workflow>

src/bmm/workflows/4-implementation/bmad-correct-course/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-correct-course
 description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/4-implementation/bmad-create-story/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-create-story
 description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/4-implementation/bmad-create-story/workflow.md

@@ -344,7 +344,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 </step>
 
 <step n="6" goal="Update sprint status and finalize">
-  <action>Validate the newly created story file {default_output_file} against `./checklist.md` and apply any required fixes before finalizing</action>
+  <action>Validate the newly created story file {story_file} against `./checklist.md` and apply any required fixes before finalizing</action>
   <action>Save story document unconditionally</action>
 
   <!-- Update sprint status -->

src/bmm/workflows/4-implementation/bmad-dev-story/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-dev-story
 description: 'Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/4-implementation/bmad-retrospective/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-retrospective
 description: 'Post-epic review to extract lessons and assess success. Use when the user says "run a retrospective" or "lets retro the epic [epic]"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/4-implementation/bmad-sprint-planning/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-sprint-planning
 description: 'Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/4-implementation/bmad-sprint-status/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-sprint-status
 description: 'Summarize sprint status and surface risks. Use when the user says "check sprint status" or "show sprint status"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-document-project/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-document-project
 description: 'Document brownfield projects for AI context. Use when the user says "document this project" or "generate project docs"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-generate-project-context/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-generate-project-context
 description: 'Create project-context.md with AI rules. Use when the user says "generate project context" or "create project context"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-generate-project-context/steps/step-01-discover.md

@@ -123,7 +123,7 @@ Based on discovery, create or update the context document:
 
 #### A. Fresh Document Setup (if no existing context)
 
-Copy template from `../project-context-template.md` to `{output_folder}/project-context.md`
+Copy template from `./project-context-template.md` to `{output_folder}/project-context.md`
 Initialize frontmatter fields.
 
 #### B. Existing Document Update
@@ -160,8 +160,6 @@ Ready to create/update your project context. This will help AI agents implement
 
 [C] Continue to context generation"
 
-**HALT — wait for user selection before proceeding.**
-
 ## SUCCESS METRICS:
 
 ✅ Existing project context properly detected and handled

src/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.md

@@ -30,8 +30,8 @@ This step will generate content and present choices for each rule category:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Invoke the `bmad-party-mode` skill
+- When 'A' selected: Execute skill:bmad-advanced-elicitation
+- When 'P' selected: Execute skill:bmad-party-mode
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -264,13 +264,11 @@ After each category, show the generated rules and present choices:
 [P] Party Mode - Review from different implementation perspectives
 [C] Continue - Save these rules and move to next category"
 
-**HALT — wait for user selection before proceeding.**
-
 ### 10. Handle Menu Selection
 
 #### If 'A' (Advanced Elicitation):
 
-- Invoke the `bmad-advanced-elicitation` skill with current category rules
+- Execute skill:bmad-advanced-elicitation with current category rules
 - Process enhanced rules that come back
 - Ask user: "Accept these enhanced rules for {{category}}? (y/n)"
 - If yes: Update content, then return to A/P/C menu
@@ -278,7 +276,7 @@ After each category, show the generated rules and present choices:
 
 #### If 'P' (Party Mode):
 
-- Invoke the `bmad-party-mode` skill with category rules context
+- Execute skill:bmad-party-mode with category rules context
 - Process collaborative insights on implementation patterns
 - Ask user: "Accept these changes to {{category}} rules? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/bmad-qa-generate-e2e-tests/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-qa-generate-e2e-tests
 description: 'Generate end to end automated tests for existing features. Use when the user says "create qa automated tests for [feature]"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-qa-generate-e2e-tests/workflow.md

@@ -2,7 +2,7 @@
 
 **Goal:** Generate automated API and E2E tests for implemented code.
 
-**Your Role:** You are a QA automation engineer. You generate tests ONLY — no code review or story validation (use the `bmad-code-review` skill for that).
+**Your Role:** You are a QA automation engineer. You generate tests ONLY — no code review or story validation (use Code Review `CR` for that).
 
 ---
 

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-quick-dev-new-preview
 description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-quick-dev
 description: 'Implement a Quick Tech Spec for small changes or features. Use when the user provides a quick tech spec and says "implement this quick spec" or "proceed with implementation of [quick tech spec]"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-01-mode-detection.md

@@ -85,7 +85,7 @@ Display: "**Select:** [P] Plan first (tech-spec) [E] Execute directly"
 
 #### Menu Handling Logic:
 
-- IF P: Direct user to invoke the `bmad-quick-spec` skill. **EXIT Quick Dev.**
+- IF P: Direct user to `{quick_spec_workflow}`. **EXIT Quick Dev.**
 - IF E: Ask for any additional guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md`
 
 #### EXECUTION RULES:
@@ -107,7 +107,7 @@ Display:
 
 #### Menu Handling Logic:
 
-- IF P: Direct user to invoke the `bmad-quick-spec` skill. **EXIT Quick Dev.**
+- IF P: Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
 - IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.**
 - IF E: Ask for guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md`
 
@@ -130,7 +130,7 @@ Display:
 
 #### Menu Handling Logic:
 
-- IF P: Direct user to invoke the `bmad-quick-spec` skill. **EXIT Quick Dev.**
+- IF P: Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
 - IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.**
 - IF E: Ask for guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md`
 

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.md

@@ -31,6 +31,12 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 - `project_context` = `**/project-context.md` (load if exists)
 
+### Related Workflows
+
+- `quick_spec_workflow` = `skill:bmad-quick-spec`
+- `party_mode_exec` = `skill:bmad-party-mode`
+- `advanced_elicitation` = `skill:bmad-advanced-elicitation`
+
 ---
 
 ## EXECUTION

src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-quick-spec
 description: 'Very quick process to create implementation-ready quick specs for small changes or features. Use when the user says "create a quick spec" or "generate a quick tech spec"'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md

@@ -161,8 +161,8 @@ b) **HALT and wait for user selection.**
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
-- IF P: Invoke the `bmad-party-mode` skill with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
+- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
+- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
 - IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `./step-02-investigate.md`
 - IF Any other comments or queries: respond helpfully then redisplay menu
 

src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.md

@@ -116,8 +116,8 @@ Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Ge
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
-- IF P: Invoke the `bmad-party-mode` skill with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
+- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
+- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
 - IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `./step-03-generate.md`
 - IF Any other comments or queries: respond helpfully then redisplay menu
 

src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-04-review.md

@@ -48,8 +48,8 @@ Display: "**Select:** [C] Continue [E] Edit [Q] Questions [A] Advanced Elicitati
 - IF C: Proceed to Section 3 (Finalize the Spec)
 - IF E: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu
 - IF Q: Answer questions, then redisplay this menu
-- IF A: Invoke the `bmad-advanced-elicitation` skill with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
-- IF P: Invoke the `bmad-party-mode` skill with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
+- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
+- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
 - IF Any other comments or queries: respond helpfully then redisplay menu
 
 #### EXECUTION RULES:
@@ -134,10 +134,10 @@ b) **HALT and wait for user selection.**
 
 #### Menu Handling Logic:
 
-- IF A: Invoke the `bmad-advanced-elicitation` skill with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
+- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
 - IF B: Invoke the `bmad-quick-dev` skill with `{finalFile}` in a fresh context if possible (warn: fresh context is better)
 - IF D: Exit workflow - display final confirmation and path to spec
-- IF P: Invoke the `bmad-party-mode` skill with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
+- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
 - IF R: Execute Adversarial Review (see below)
 - IF Any other comments or queries: respond helpfully then redisplay menu
 

src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/workflow.md

@@ -1,6 +1,9 @@
 ---
 main_config: '{project-root}/_bmad/bmm/config.yaml'
 
+# Checkpoint handler references
+advanced_elicitation: 'skill:bmad-advanced-elicitation'
+party_mode_exec: 'skill:bmad-party-mode'
 ---
 
 # Quick-Spec Workflow

src/core/skills/bmad-advanced-elicitation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-advanced-elicitation
-description: 'Push the LLM to reconsider, refine, and improve its recent output.'
+description: 'Push the LLM to reconsider refine and improve its recent output.'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/core/skills/bmad-advanced-elicitation/workflow.md

@@ -96,9 +96,9 @@ x. Proceed / No Further Actions
 **Case x (Proceed):**
 
 - Complete elicitation and proceed
-- Return the fully enhanced content back to the invoking skill
+- Return the fully enhanced content back to create-doc.md
 - The enhanced content becomes the final version for that section
-- Signal completion back to the invoking skill to continue with next section
+- Signal completion back to create-doc.md to continue with next section
 
 **Case a (List All):**
 

src/core/skills/bmad-brainstorming/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-brainstorming
 description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/core/skills/bmad-brainstorming/steps/step-01-session-setup.md

@@ -48,8 +48,6 @@ If existing session files are found:
   **[2]** Start a new session
   **[3]** See all existing sessions"
 
-**HALT — wait for user selection before proceeding.**
-
 - If user selects **[1]** (continue): Set `{brainstorming_session_output_file}` to that file path and load `./step-01b-continue.md`
 - If user selects **[2]** (new): Generate new filename with current date/time and proceed to step 3
 - If user selects **[3]** (see all): List all session filenames and ask which to continue or if new
@@ -157,8 +155,6 @@ When user selects approach, append the session overview content directly to `{br
 
 Which approach appeals to you most? (Enter 1-4)"
 
-**HALT — wait for user selection before proceeding.**
-
 ### 4. Handle User Selection and Initial Document Append
 
 #### When user selects approach number:

src/core/skills/bmad-brainstorming/steps/step-01b-continue.md

@@ -63,9 +63,7 @@ Based on session analysis, provide appropriate options:
 **Options:**
 [1] Review Results - Go through your documented ideas and insights
 [2] Start New Session - Begin brainstorming on a new topic
-[3] Extend Session - Add more techniques or explore new angles"
-
-**HALT — wait for user selection before proceeding.**
+[3) Extend Session - Add more techniques or explore new angles"
 
 **If Session In Progress:**
 "Let's continue where we left off!

src/core/skills/bmad-brainstorming/steps/step-02a-user-selected.md

@@ -40,7 +40,7 @@ Load techniques from CSV on-demand:
 
 **Load CSV and parse:**
 
-- Read `../brain-methods.csv`
+- Read `brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Organize by categories for browsing
 
@@ -87,8 +87,6 @@ Show available categories with brief descriptions:
 
 **Which category interests you most? Enter 1-7, or tell me what type of thinking you're drawn to.**"
 
-**HALT — wait for user selection before proceeding.**
-
 ### 3. Handle Category Selection
 
 After user selects category:
@@ -156,8 +154,6 @@ This combination will take approximately [total_time] and focus on [expected out
 [C] Continue - Begin technique execution
 [Back] - Modify technique selection"
 
-**HALT — wait for user selection before proceeding.**
-
 ### 6. Update Frontmatter and Continue
 
 If user confirms:

src/core/skills/bmad-brainstorming/steps/step-02b-ai-recommended.md

@@ -47,7 +47,7 @@ Load techniques from CSV for analysis:
 
 **Load CSV and parse:**
 
-- Read `../brain-methods.csv`
+- Read `brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 
 ### 2. Context Analysis for Technique Matching
@@ -152,8 +152,6 @@ Provide deeper insight into each recommended technique:
 [Details] - Tell me more about any specific technique
 [Back] - Return to approach selection
 
-**HALT — wait for user selection before proceeding.**
-
 ### 6. Handle User Response
 
 #### If [C] Continue:

src/core/skills/bmad-brainstorming/steps/step-02c-random-selection.md

@@ -47,7 +47,7 @@ Create anticipation for serendipitous technique discovery:
 
 **Load CSV and parse:**
 
-- Read `../brain-methods.csv`
+- Read `brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Prepare for intelligent random selection
 
@@ -124,8 +124,6 @@ You're about to experience brainstorming in a completely new way. These unexpect
 [Details] - Tell me more about any specific technique
 [Back] - Return to approach selection
 
-**HALT — wait for user selection before proceeding.**
-
 ### 5. Handle User Response
 
 #### If [C] Continue:

src/core/skills/bmad-brainstorming/steps/step-02d-progressive-flow.md

@@ -66,7 +66,7 @@ Explain the value of systematic creative progression:
 
 **Load CSV and parse:**
 
-- Read `../brain-methods.csv`
+- Read `brain-methods.csv`
 - Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
 - Map techniques to each phase of the creative journey
 
@@ -176,8 +176,6 @@ Show the full progressive flow with timing and transitions:
 [Details] - Tell me more about any specific phase or technique
 [Back] - Return to approach selection
 
-**HALT — wait for user selection before proceeding.**
-
 ### 4. Handle Customization Requests
 
 If user wants customization:

src/core/skills/bmad-brainstorming/steps/step-03-technique-execution.md

@@ -1,7 +1,7 @@
 # Step 3: Interactive Technique Execution and Facilitation
 
 ---
-
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
 ---
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
@@ -290,8 +290,6 @@ After final technique element:
 [B] **Take a quick break** - Pause and return with fresh energy
 [C] **Move to organization** - Only when you feel we've thoroughly explored
 
-**HALT — wait for user selection before proceeding.**
-
 **Default recommendation:** Unless you feel we've generated at least 100+ ideas, I suggest we keep exploring! The best insights often come after the obvious ideas are exhausted.
 
 ### 8. Handle Menu Selection
@@ -305,7 +303,7 @@ After final technique element:
 #### If 'K', 'T', 'A', or 'B' (Continue Exploring):
 
 - **Stay in Step 3** and restart the facilitation loop for the chosen path (or pause if break requested).
-- For option A: Invoke the `bmad-advanced-elicitation` skill
+- For option A, invoke Advanced Elicitation: `{advancedElicitationTask}`
 
 ### 9. Update Documentation
 

src/core/skills/bmad-brainstorming/steps/step-04-idea-organization.md

@@ -249,8 +249,6 @@ Provide final session wrap-up and forward guidance:
 **Ready to complete your session documentation?**
 [C] Complete - Generate final brainstorming session document
 
-**HALT — wait for user selection before proceeding.**
-
 ### 8. Handle Completion Selection
 
 #### If [C] Complete:

src/core/skills/bmad-brainstorming/workflow.md

@@ -44,10 +44,12 @@ Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
 
 All steps MUST reference `{brainstorming_session_output_file}` instead of the full path pattern.
 - `context_file` = Optional context file path from workflow invocation for project-specific guidance
+- `advancedElicitationTask` = `skill:bmad-advanced-elicitation`
+
 ---
 
 ## EXECUTION
 
-Read fully and follow: `./steps/step-01-session-setup.md` to begin the workflow.
+Read fully and follow: `steps/step-01-session-setup.md` to begin the workflow.
 
 **Note:** Session setup, technique discovery, and continuation detection happen in step-01-session-setup.md.

src/core/skills/bmad-distillator/agents/distillate-compressor.md

@@ -4,7 +4,7 @@ Act as an information extraction and compression specialist. Your sole purpose i
 
 You receive: source document file paths, an optional downstream_consumer context, and a splitting decision.
 
-You must load and apply `../resources/compression-rules.md` before producing output. Reference `../resources/distillate-format-reference.md` for the expected output format.
+You must load and apply `resources/compression-rules.md` before producing output. Reference `resources/distillate-format-reference.md` for the expected output format.
 
 ## Compression Process
 
@@ -31,7 +31,7 @@ Treat this as entity extraction — pull out every distinct piece of information
 
 ### Step 3: Deduplicate
 
-Apply the deduplication rules from `../resources/compression-rules.md`.
+Apply the deduplication rules from `resources/compression-rules.md`.
 
 ### Step 4: Filter (only if downstream_consumer is specified)
 
@@ -58,7 +58,7 @@ Common groupings (use what fits, omit what doesn't, add what's needed):
 
 ### Step 6: Compress Language
 
-For each item, apply the compression rules from `../resources/compression-rules.md`:
+For each item, apply the compression rules from `resources/compression-rules.md`:
 - Strip prose transitions and connective tissue
 - Remove hedging and rhetoric
 - Remove explanations of common knowledge
@@ -80,7 +80,7 @@ Do NOT include frontmatter — the calling skill handles that.
 
 ## Semantic Splitting
 
-If the splitting decision indicates splitting is needed, load `../resources/splitting-strategy.md` and follow it.
+If the splitting decision indicates splitting is needed, load `resources/splitting-strategy.md` and follow it.
 
 When splitting:
 

src/core/skills/bmad-editorial-review-prose/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-editorial-review-prose
 description: 'Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/core/skills/bmad-editorial-review-structure/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-editorial-review-structure
 description: 'Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/core/skills/bmad-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-help
-description: 'Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad'
+description: 'Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/core/skills/bmad-index-docs/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-index-docs
 description: 'Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/core/skills/bmad-party-mode/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-party-mode
 description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests party mode.'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).

src/core/skills/bmad-review-adversarial-general/SKILL.md

@@ -3,4 +3,4 @@ name: bmad-review-adversarial-general
 description: 'Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something'
 ---
 
-Follow the instructions in ./workflow.md.
+Follow the instructions in [workflow.md](workflow.md).