validation tasks added

docs/antipattern-audit-2025-10-22.md

@@ -0,0 +1,328 @@
+# BMAD Workflow Conditional Execution Antipattern Audit
+
+**Date:** 2025-10-22
+**Auditor:** Claude Code (BMad Builder Agent)
+**Scope:** All markdown files under `src/`
+
+---
+
+## Executive Summary
+
+**Critical Issue Identified:** Invalid self-closing `<check>` tag pattern found throughout BMAD workflow codebase.
+
+**Impact:**
+
+- **98 instances** across **14 workflow files**
+- Affects core workflows, builder workflows, and method workflows
+- Creates XML parsing ambiguity and unpredictable LLM behavior
+- Violates BMAD workflow specification (workflow.xml)
+
+**Severity:** CRITICAL - Invalid XML structure, ambiguous conditional scope
+
+---
+
+## The Antipattern
+
+### Invalid Pattern (Self-Closing Check)
+
+```xml
+<!-- ❌ WRONG - Invalid XML structure -->
+<check>If condition met:</check>
+<action>Do something</action>
+<action>Do something else</action>
+```
+
+**Problems:**
+
+1. Check tag doesn't wrap anything (invalid XML)
+2. Ambiguous scope - unclear which actions are conditional
+3. Breaks formatters and parsers
+4. Not part of BMAD workflow spec
+5. Unpredictable LLM interpretation
+
+### Correct Patterns
+
+**Single conditional action:**
+
+```xml
+<!-- ✅ CORRECT - Inline conditional -->
+<action if="condition met">Do something</action>
+```
+
+**Multiple conditional actions:**
+
+```xml
+<!-- ✅ CORRECT - Proper wrapper block -->
+<check if="condition met">
+  <action>Do something</action>
+  <action>Do something else</action>
+</check>
+```
+
+---
+
+## Audit Results
+
+### Total Count
+
+- **Total Instances:** 98
+- **Affected Files:** 14
+- **Modules Affected:** 4 (BMB, BMM, CIS, Core)
+
+### Breakdown by File
+
+| File                                                                 | Count | Priority    |
+| -------------------------------------------------------------------- | ----- | ----------- |
+| `modules/bmb/workflows/edit-workflow/instructions.md`                | 21    | 🔴 CRITICAL |
+| `modules/bmm/workflows/4-implementation/dev-story/instructions.md`   | 13    | 🔴 CRITICAL |
+| `modules/bmb/workflows/convert-legacy/instructions.md`               | 13    | 🔴 CRITICAL |
+| `modules/bmb/workflows/create-module/instructions.md`                | 12    | 🔴 CRITICAL |
+| `modules/bmb/workflows/create-agent/instructions.md`                 | 11    | 🔴 CRITICAL |
+| `core/workflows/party-mode/instructions.md`                          | 7     | 🟡 HIGH     |
+| `modules/bmm/workflows/4-implementation/correct-course/checklist.md` | 5     | 🟡 HIGH     |
+| `core/workflows/brainstorming/instructions.md`                       | 5     | 🟡 HIGH     |
+| `modules/cis/workflows/storytelling/instructions.md`                 | 3     | 🟢 MEDIUM   |
+| `modules/bmb/workflows/audit-workflow/instructions.md`               | 3     | 🟢 MEDIUM   |
+| `modules/bmb/workflows/create-workflow/workflow-creation-guide.md`   | 2     | 🟢 MEDIUM   |
+| `modules/bmm/workflows/1-analysis/product-brief/instructions.md`     | 1     | 🟢 LOW      |
+| `modules/bmm/workflows/1-analysis/game-brief/instructions.md`        | 1     | 🟢 LOW      |
+| `modules/bmb/workflows/redoc/instructions.md`                        | 1     | 🟢 LOW      |
+
+### Breakdown by Module
+
+**BMB (Builder) Module: 63 instances (64%)**
+
+- edit-workflow: 21
+- convert-legacy: 13
+- create-module: 12
+- create-agent: 11
+- audit-workflow: 3
+- create-workflow: 2
+- redoc: 1
+
+**BMM (Method) Module: 20 instances (20%)**
+
+- dev-story: 13
+- correct-course: 5
+- product-brief: 1
+- game-brief: 1
+
+**Core Workflows: 12 instances (12%)**
+
+- party-mode: 7
+- brainstorming: 5
+
+**CIS (Creative) Module: 3 instances (3%)**
+
+- storytelling: 3
+
+---
+
+## Example Instances
+
+### Example 1: create-agent/instructions.md (Line 13-20)
+
+**BEFORE (Invalid):**
+
+```xml
+<check>If yes:</check>
+  <action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
+  <action>Pass context data: {installed_path}/brainstorm-context.md</action>
+  <action>Wait for brainstorming session completion</action>
+
+  <check>If no:</check>
+    <action>Proceed directly to Step 0</action>
+```
+
+**AFTER (Correct):**
+
+```xml
+<check if="user answered yes">
+  <action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
+  <action>Pass context data: {installed_path}/brainstorm-context.md</action>
+  <action>Wait for brainstorming session completion</action>
+</check>
+
+<check if="user answered no">
+  <action>Proceed directly to Step 0</action>
+</check>
+```
+
+### Example 2: dev-story/instructions.md (Line 54-55)
+
+**BEFORE (Invalid):**
+
+```xml
+<check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
+<check>If task requirements ambiguous → ASK user to clarify or HALT</check>
+```
+
+**AFTER (Correct):**
+
+```xml
+<action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
+<action if="task requirements ambiguous">ASK user to clarify or HALT</action>
+```
+
+---
+
+## Impact Assessment
+
+### Technical Impact
+
+1. **XML Validity:** Invalid structure violates XML parsing rules
+2. **Formatter Confusion:** Custom formatters incorrectly indent following content
+3. **Scope Ambiguity:** Unclear which actions are inside vs outside conditional
+4. **Maintainability:** Future developers confused by ambiguous structure
+
+### LLM Adherence Impact
+
+**Potential Issues:**
+
+- LLM may interpret check as unconditional statement
+- Actions may execute when they shouldn't (or vice versa)
+- Inconsistent behavior across different LLMs
+- Unpredictable results in complex nested conditionals
+
+**Observed Behavior:**
+
+- LLMs often "figure it out" through context and proximity
+- Colon (`:`) pattern signals "here's what to do"
+- Works in simple cases but risky in complex logic
+
+**Risk Level:** MEDIUM-HIGH
+
+- May work "most of the time" but unreliable
+- Fails in edge cases and complex nested logic
+- Future LLMs may interpret differently
+
+---
+
+## Root Cause Analysis
+
+### Why This Happened
+
+1. **Implicit convention evolved** - Self-closing check pattern emerged organically
+2. **No enforcement** - No linter or validator caught the pattern
+3. **Copy-paste propagation** - Pattern copied across workflows
+4. **Formatting hid the issue** - Manual indentation made it "look right"
+5. **LLM tolerance** - Current LLMs often figured it out despite ambiguity
+
+### Meta-Problem
+
+**The workflows that CREATE workflows have the antipattern:**
+
+- create-workflow: 2 instances
+- create-agent: 11 instances
+- create-module: 12 instances
+- edit-workflow: 21 instances
+- convert-legacy: 13 instances
+
+This means NEW workflows were being created WITH the antipattern built-in!
+
+---
+
+## Remediation Plan
+
+### Phase 1: Immediate (High Priority Files)
+
+Fix top 5 offenders (63% of problem):
+
+1. edit-workflow (21 instances)
+2. dev-story (13 instances)
+3. convert-legacy (13 instances)
+4. create-module (12 instances)
+5. create-agent (11 instances)
+
+**Total:** 70 instances (71% of problem)
+
+### Phase 2: Core Workflows
+
+Fix core workflows (critical for all modules):
+
+1. party-mode (7 instances)
+2. brainstorming (5 instances)
+
+**Total:** 12 instances
+
+### Phase 3: Remaining
+
+Fix remaining 16 instances across 7 files
+
+### Phase 4: Prevention
+
+1. **Update audit-workflow** ✅ DONE
+   - Added antipattern detection to Step 4
+   - Flags with CRITICAL severity
+   - Suggests correct patterns
+
+2. **Update creation guide** ✅ DONE
+   - Documented antipattern in workflow-creation-guide.md
+   - Clear examples of correct vs incorrect patterns
+   - Added to best practices
+
+3. **Update checklist** ✅ DONE
+   - Added validation criteria to checklist.md
+   - 3 new checks for conditional execution patterns
+
+4. **Create automated fixer** (TODO)
+   - Bulk conversion script for remaining instances
+   - Pattern matching and replacement logic
+
+---
+
+## Specification Reference
+
+From `bmad/core/tasks/workflow.xml`:
+
+```xml
+<tag>action if="condition" - Single conditional action (inline, no closing tag needed)</tag>
+<tag>check if="condition">...</check> - Conditional block wrapping multiple items (closing tag required)</tag>
+```
+
+**Key Point:** Check tags MUST have `if=""` attribute and MUST wrap content with closing tag.
+
+The self-closing pattern `<check>text</check>` is **NOT in the spec** and is **invalid**.
+
+---
+
+## Detection Command
+
+To find all instances:
+
+```bash
+grep -r "<check>[^<]*</check>" src --include="*.md" -n
+```
+
+To count by file:
+
+```bash
+grep -r "<check>[^<]*</check>" src --include="*.md" -c | grep -v ":0$"
+```
+
+---
+
+## Next Actions
+
+- [ ] Create bulk-fix script for automated conversion
+- [ ] Fix Phase 1 files (70 instances)
+- [ ] Fix Phase 2 files (12 instances)
+- [ ] Fix Phase 3 files (16 instances)
+- [ ] Run audit-workflow on all fixed files to verify
+- [ ] Update formatter to detect and warn on antipattern
+- [ ] Add pre-commit hook to prevent future instances
+
+---
+
+## References
+
+- **Workflow Spec:** `bmad/core/tasks/workflow.xml`
+- **Creation Guide:** `src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md`
+- **Audit Workflow:** `src/modules/bmb/workflows/audit-workflow/`
+- **This Report:** `docs/antipattern-audit-2025-10-22.md`
+
+---
+
+**Report Status:** Complete
+**Action Required:** Yes - 98 instances need remediation
+**Priority:** CRITICAL - Affects core functionality and workflow creation

docs/audit-report-tech-spec-2025-10-21.md

@@ -1,431 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** tech-spec
-**Audit Date:** 2025-10-21
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Document (template-based)
-**Workflow Path:** /Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/4-implementation/epic-tech-context
-
----
-
-## Executive Summary
-
-**Overall Status:** ⚠️ ISSUES FOUND - Requires fixes before production use
-
-**Issue Breakdown:**
-
-- Critical Issues: **2**
-- Important Issues: **1**
-- Cleanup Recommendations: **4**
-
-**Primary Concerns:**
-
-1. Web bundle missing critical workflow dependencies
-2. Output path hardcoded instead of using config variable
-3. Configuration bloat (40% unused variables)
-
----
-
-## 1. Standard Config Block Validation
-
-### ✅ Status: PASS
-
-All required standard config variables are present and correctly formatted:
-
-**Required Variables:**
-
-- ✅ `config_source: "{project-root}/bmad/bmm/config.yaml"`
-- ✅ `output_folder: "{config_source}:output_folder"`
-- ✅ `user_name: "{config_source}:user_name"`
-- ✅ `communication_language: "{config_source}:communication_language"`
-- ✅ `date: system-generated`
-
-**Additional Config Variables Found:**
-
-- ⚠️ `document_output_language` (non-standard, potentially unused)
-- ⚠️ `user_skill_level` (non-standard, potentially unused)
-
-**Recommendation:** Verify usage of additional config variables or remove if unused.
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### ❌ Issues Found: Configuration Bloat
-
-**Variables Analyzed:** 5 custom fields
-**Used in Instructions:** 3
-**Used in Template:** N/A (config variables)
-**Unused (Bloat):** 2
-
-### Unused Variables (BLOAT):
-
-1. **`document_output_language`**
-   - Location: workflow.yaml line 10
-   - Status: Defined but never referenced in instructions.md or template.md
-   - Impact: Configuration bloat
-   - **Action Required:** Remove from yaml
-
-2. **`user_skill_level`**
-   - Location: workflow.yaml line 11
-   - Status: Defined but never referenced in instructions.md or template.md
-   - Impact: Configuration bloat
-   - **Action Required:** Remove from yaml
-
-### Properly Used Variables:
-
-- ✅ `output_folder` → Used in instructions.md (lines 12, 129)
-- ✅ `user_name` → Used in instructions.md (lines 143, 166) and template.md (line 4)
-- ✅ `communication_language` → Used in instructions.md (line 6)
-- ✅ `date` → Used in template.md (line 3) and output file naming
-- ✅ `non_interactive` → Used in instructions.md (lines 8, 66, 68)
-
-**Bloat Metrics:**
-
-- Total custom yaml fields: 5
-- Used fields: 3
-- Unused fields: 2
-- **Bloat Percentage: 40%**
-
----
-
-## 3. Config Variable Usage
-
-### Overall Status: ⚠️ IMPORTANT ISSUE FOUND
-
-**Communication Language:**
-
-- ✅ Properly used on line 6: `Communicate all responses in {communication_language}`
-- ✅ No inappropriate usage in template headers
-- Status: **CORRECT**
-
-**User Name:**
-
-- ✅ Used for personalization on lines 143, 166
-- ✅ Optional metadata usage in template (line 4)
-- Status: **CORRECT**
-
-**Output Folder:**
-
-- ✅ Properly used for file searches (lines 12, 129)
-- ❌ **ISSUE:** `default_output_file` hardcodes path instead of using variable
-  - Current: `"{project-root}/docs/tech-spec-epic-{{epic_id}}.md"`
-  - Should be: `"{output_folder}/tech-spec-epic-{{epic_id}}.md"`
-  - Impact: Ignores user's configured output folder preference
-  - Severity: **IMPORTANT**
-
-**Date:**
-
-- ✅ System-generated and available
-- ✅ Used in template metadata (line 3)
-- ✅ Used in output file naming
-- Status: **CORRECT**
-
-### Action Required:
-
-**Fix default_output_file in workflow.yaml:**
-
-```yaml
-# Current (line 29):
-default_output_file: "{project-root}/docs/tech-spec-epic-{{epic_id}}.md"
-
-# Should be:
-default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
-```
-
----
-
-## 4. Web Bundle Validation
-
-### 🚨 Status: CRITICAL ISSUES FOUND
-
-**Current Web Bundle Configuration:**
-
-```yaml
-web_bundle:
-  name: 'tech-spec'
-  description: '...'
-  author: 'BMAD BMM'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/template.md'
-    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md'
-    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md'
-```
-
-### Path Validation:
-
-- ✅ All paths use bmad/-relative format (NOT {project-root})
-- ✅ No {config_source} variables in web_bundle section
-- ✅ Paths match actual file locations
-
-### Completeness Check:
-
-- ✅ instructions.md listed
-- ✅ template.md listed (document workflow)
-- ✅ checklist.md listed
-
-### 🚨 Critical Issues:
-
-**Issue 1: Missing Workflow Dependency**
-
-- Severity: **CRITICAL**
-- Location: instructions.md line 133
-- Problem: Workflow invokes `workflow-status` but dependency not in web_bundle_files
-- Invocation: `<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">`
-- Missing files:
-  - `bmad/bmm/workflows/workflow-status/workflow.yaml`
-  - `bmad/bmm/workflows/workflow-status/instructions.md` (if exists)
-
-**Issue 2: Missing existing_workflows Field**
-
-- Severity: **CRITICAL**
-- Problem: When `<invoke-workflow>` calls exist, web_bundle MUST include `existing_workflows` field
-- Current: Field not present
-- Required: Mapping of workflow variables to paths
-
-### Required Fix:
-
-```yaml
-web_bundle:
-  name: 'tech-spec'
-  description: 'Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping'
-  author: 'BMAD BMM'
-  existing_workflows:
-    - workflow_status: 'bmad/bmm/workflows/workflow-status/workflow.yaml'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/template.md'
-    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md'
-    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md'
-    - 'bmad/bmm/workflows/workflow-status/workflow.yaml'
-    - 'bmad/bmm/workflows/workflow-status/instructions.md'
-```
-
-**Web Bundle Status:**
-
-- Web Bundle Present: ✅ Yes
-- Files Listed: 3
-- Missing Files: 2+
-- Completeness: ❌ **INCOMPLETE**
-
----
-
-## 5. Bloat Detection
-
-### Bloat Summary
-
-**Unused YAML Fields: 2**
-
-1. `document_output_language`
-   - Type: Config variable
-   - Usage: Not referenced anywhere
-   - Recommendation: **Remove**
-
-2. `user_skill_level`
-   - Type: Config variable
-   - Usage: Not referenced anywhere
-   - Recommendation: **Remove**
-
-**Hardcoded Values: 1**
-
-3. `default_output_file` path
-   - Current: `{project-root}/docs/tech-spec-epic-{{epic_id}}.md`
-   - Should use: `{output_folder}`
-   - Impact: Ignores user configuration
-   - Recommendation: **Fix to use {output_folder}**
-
-**Redundant Configuration: 3 fields**
-
-4. Metadata duplication between top-level and web_bundle:
-   - `name` appears on yaml line 1 AND web_bundle line 36
-   - `description` appears on yaml line 2 AND web_bundle line 37
-   - `author` appears on yaml line 3 AND web_bundle line 38
-   - Recommendation: **Remove duplication** (keep in one location)
-
-### Bloat Metrics:
-
-- Total custom yaml fields analyzed: 5
-- Used fields: 3
-- Unused fields: 2
-- **Bloat Percentage: 40%**
-- Redundant metadata fields: 3
-- **Cleanup Potential: HIGH** (~30% configuration reduction possible)
-
----
-
-## 6. Template Variable Mapping
-
-### ✅ Status: EXCELLENT - No Issues
-
-**Template Variables:** 20
-**Mapped via template-output:** 15
-**Config Variables:** 2
-**Runtime Variables:** 3
-**Missing Mappings:** 0
-**Orphaned Outputs:** 0
-
-### All Template Variables Accounted For:
-
-**Generated via template-output (15):**
-
-- overview, objectives_scope, system_arch_alignment
-- services_modules, data_models, apis_interfaces, workflows_sequencing
-- nfr_performance, nfr_security, nfr_reliability, nfr_observability
-- dependencies_integrations
-- acceptance_criteria, traceability_mapping
-- risks_assumptions_questions, test_strategy
-
-**Standard Config Variables (2):**
-
-- date (system-generated)
-- user_name (from config)
-
-**Runtime/Extracted Variables (3):**
-
-- epic_title (extracted from PRD)
-- epic_id (extracted from PRD)
-
-### Validation:
-
-- ✅ All variables use snake_case naming
-- ✅ Variable names are descriptive and clear
-- ✅ Logical grouping in template-output sections
-- ✅ No orphaned template-output tags
-- ✅ Complete 1:1 mapping coverage
-
-**No action required** - Template variable mapping is exemplary.
-
----
-
-## Recommendations
-
-### 🚨 Critical (Fix Immediately)
-
-**Priority 1: Fix Web Bundle Dependencies**
-
-- Add `existing_workflows` field to web_bundle section
-- Include workflow-status workflow files in web_bundle_files
-- Impact: Without this, workflow cannot be bundled for web use
-- File: `workflow.yaml` lines 35-43
-
-**Priority 2: Add Missing Workflow Files**
-
-- Include: `bmad/bmm/workflows/workflow-status/workflow.yaml`
-- Include: `bmad/bmm/workflows/workflow-status/instructions.md` (if exists)
-- Impact: Web bundle incomplete, workflow invocations will fail
-- File: `workflow.yaml` web_bundle_files section
-
----
-
-### ⚠️ Important (Address Soon)
-
-**Priority 3: Fix Output Path Configuration**
-
-- Change `default_output_file` to use `{output_folder}` variable
-- Current: `{project-root}/docs/tech-spec-epic-{{epic_id}}.md`
-- Fixed: `{output_folder}/tech-spec-epic-{{epic_id}}.md`
-- Impact: Respects user's configured output preferences
-- File: `workflow.yaml` line 29
-
----
-
-### 🧹 Cleanup (Nice to Have)
-
-**Priority 4: Remove Unused Config Variables**
-
-- Remove: `document_output_language` (line 10)
-- Remove: `user_skill_level` (line 11)
-- Impact: Reduces configuration bloat by 40%
-- File: `workflow.yaml` config section
-
-**Priority 5: Eliminate Metadata Duplication**
-
-- Remove duplicate `name`, `description`, `author` from either top-level or web_bundle
-- Keep metadata in one location only
-- Impact: Cleaner configuration, easier maintenance
-- File: `workflow.yaml` lines 1-3 or 36-38
-
----
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
-- [ ] **Web Bundle:** existing_workflows field added with workflow_status mapping
-- [ ] **Web Bundle:** workflow-status/workflow.yaml added to web_bundle_files
-- [ ] **Config:** default_output_file uses {output_folder} instead of hardcoded path
-- [ ] **Bloat:** document_output_language removed from yaml
-- [ ] **Bloat:** user_skill_level removed from yaml
-- [ ] **Redundancy:** Metadata duplication eliminated
-- [ ] **Re-test:** Workflow executes successfully after fixes
-- [ ] **Re-audit:** Run audit-workflow again to verify all issues resolved
-
----
-
-## Workflow Structure Assessment
-
-### Strengths:
-
-- ✅ Excellent template variable mapping (20 variables, 0 orphans)
-- ✅ Proper use of standard config variables
-- ✅ Clear step-by-step instructions with proper XML structure
-- ✅ Good integration with workflow-status for progress tracking
-- ✅ Comprehensive validation checklist
-- ✅ Non-interactive mode support (#yolo mode)
-
-### Areas for Improvement:
-
-- ❌ Web bundle configuration incomplete (missing dependencies)
-- ❌ Output path doesn't respect user configuration
-- ⚠️ Configuration bloat (40% unused variables)
-- ⚠️ Metadata duplication
-
----
-
-## Next Steps
-
-### Immediate Actions:
-
-1. **Fix Critical Issues** (Est. 15 minutes)
-   - Add existing_workflows field to web_bundle
-   - Add workflow-status files to web_bundle_files
-   - Verify workflow-status workflow exists at specified path
-
-2. **Fix Important Issues** (Est. 5 minutes)
-   - Update default_output_file to use {output_folder}
-   - Test output file creation with different config values
-
-3. **Cleanup Configuration** (Est. 10 minutes)
-   - Remove document_output_language from yaml
-   - Remove user_skill_level from yaml
-   - Eliminate metadata duplication
-
-4. **Verify Fixes** (Est. 10 minutes)
-   - Re-run audit-workflow to confirm all issues resolved
-   - Test workflow execution end-to-end
-   - Verify web bundle generation works
-
-### Recommended Testing:
-
-```bash
-# After fixes, test the workflow
-/bmad:bmm:workflows:tech-spec
-
-# Re-audit to verify
-/bmad:bmb:agents:bmad-builder -> *audit-workflow
-```
-
----
-
-## Conclusion
-
-The **tech-spec** workflow has a solid foundation with excellent template variable mapping and proper instruction structure. However, **critical web bundle issues** must be resolved before production use, and the hardcoded output path should be fixed to respect user configuration.
-
-**Estimated Fix Time:** 30-40 minutes
-
-**Recommended Priority:** HIGH - Address critical issues before next release
-
----
-
-**Audit Complete** ✅
-Generated by: audit-workflow v1.0
-Powered by: BMAD Core v6-alpha

docs/sprint-status.yaml

@@ -1,97 +0,0 @@
-# generated: 2025-10-21
-# project: MyPlantFamily
-# project_key: MyPlantFamily
-# tracking_system: file-system
-# story_location: {project-root}/docs/stories
-
-# STATUS DEFINITIONS:
-# ==================
-# Epic Status:
-#   - backlog: Epic exists in epic file but not contexted
-#   - contexted: Epic tech context created (required before drafting stories)
-#
-# Story Status:
-#   - backlog: Story only exists in epic file
-#   - drafted: Story file created in stories folder
-#   - ready-for-dev: Draft approved and story context created
-#   - in-progress: Developer actively working on implementation
-#   - review: Under SM review (via review-story workflow)
-#   - done: Story completed
-#
-# Retrospective Status:
-#   - optional: Can be completed but not required
-#   - completed: Retrospective has been done
-#
-# WORKFLOW NOTES:
-# ===============
-# - Epics should be 'contexted' before stories can be 'drafted'
-# - Stories can be worked in parallel if team capacity allows
-# - SM typically drafts next story after previous one is 'done' to incorporate learnings
-# - Dev moves story to 'review', SM reviews, then Dev moves to 'done'
-
-generated: 2025-10-21
-project: MyPlantFamily
-project_key: MyPlantFamily
-tracking_system: file-system
-story_location: "{project-root}/docs/stories"
-
-development_status:
-  # Epic 1: Foundation & Core Plant Management
-  epic-1: backlog
-  1-1-project-foundation-development-environment: backlog
-  1-2-app-shell-navigation-framework: backlog
-  1-3-user-authentication-account-management: backlog
-  1-4-plant-data-model-species-database: backlog
-  1-5-add-plant-manual-species-selection: backlog
-  1-6-plant-photo-identification-integration: backlog
-  1-7-plant-naming-profile-creation: backlog
-  1-8-plant-collection-home-screen: backlog
-  1-9-plant-detail-view: backlog
-  1-10-cloud-photo-storage-display: backlog
-  epic-1-retrospective: optional
-
-  # Epic 2: AI Personality System & Engagement Loop
-  epic-2: backlog
-  2-1-personality-system-data-model: backlog
-  2-2-personality-prototype-testing: backlog
-  2-3-llm-integration-api-setup: backlog
-  2-4-chat-interface-ui: backlog
-  2-5-conversational-ai-system: backlog
-  2-6-graceful-degradation-library: backlog
-  2-7-response-caching-cost-optimization: backlog
-  2-8-personality-driven-care-reminders: backlog
-  2-9-push-notification-system: backlog
-  2-10-reminder-intelligence-adaptation: backlog
-  2-11-mood-system-visual-indicators: backlog
-  2-12-mood-calculation-logic-time-based: backlog
-  2-13-personality-introduction-onboarding: backlog
-  2-14-personality-tone-testing-calibration: backlog
-  2-15-emergency-tone-adjustment-system: backlog
-  2-16-api-reliability-monitoring-alerts: backlog
-  epic-2-retrospective: optional
-
-  # Epic 3: Care Scheduling, Photos & Growth Tracking
-  epic-3: backlog
-  3-1-care-schedule-data-model: backlog
-  3-2-auto-generated-care-schedules: backlog
-  3-3-manual-care-logging: backlog
-  3-4-care-history-view: backlog
-  3-5-customizable-care-schedules: backlog
-  3-6-photo-timeline-tracking: backlog
-  3-7-health-status-visualization: backlog
-  3-8-enhanced-mood-calculation-care-data: backlog
-  epic-3-retrospective: optional
-
-  # Epic 4: Social Sharing & Premium Monetization
-  epic-4: backlog
-  4-1-shareable-content-card-design-system: backlog
-  4-2-share-plant-profile: backlog
-  4-3-share-conversation-snippets: backlog
-  4-4-share-growth-progress: backlog
-  4-5-share-care-achievements: backlog
-  4-6-freemium-tier-definition-enforcement: backlog
-  4-7-premium-upgrade-flow-paywall: backlog
-  4-8-payment-processing-subscription-management: backlog
-  4-9-premium-analytics-dashboard: backlog
-  4-10-trial-conversion-optimization: backlog
-  epic-4-retrospective: optional

package-lock.json

@@ -95,7 +95,6 @@
       "integrity": "sha512-yDBHV9kQNcr2/sUr9jghVyz9C3Y5G2zUM2H2lo+9mKv4sFgbA8s8Z9t8D1jiTkGoO/NoIfKMyKWr4s6CN23ZwQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@ampproject/remapping": "^2.2.0",
         "@babel/code-frame": "^7.27.1",
@@ -1818,7 +1817,6 @@
       "integrity": "sha512-aPTXCrfwnDLj4VvXrm+UUCQjNEvJgNA8s5F1cvwQU+3KNltTOkBm1j30uNLyqqPNe7gE3KFzImYoZEfLhp4Yow==",
       "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~7.10.0"
       }
@@ -2135,7 +2133,6 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -2497,7 +2494,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "caniuse-lite": "^1.0.30001735",
         "electron-to-chromium": "^1.5.204",
@@ -3352,7 +3348,6 @@
       "integrity": "sha512-RNCHRX5EwdrESy3Jc9o8ie8Bog+PeYvvSR8sDGoZxNFTvZ4dlxUB3WzQ3bQMztFrSRODGrLLj8g6OFuGY/aiQg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -7092,7 +7087,6 @@
       "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "prettier": "bin/prettier.cjs"
       },
@@ -7915,7 +7909,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },

src/core/tasks/validate-workflow.xml

@@ -10,7 +10,8 @@
   <flow>
     <step n="1" title="Setup">
       <action>If checklist not provided, load checklist.md from workflow location</action>
-      <action>If document not provided, ask user: "Which document should I validate?"</action>
+      <action>Try to fuzzy match for files similar to the input document name or if user did not provide the document. If document not
+        provided or unsure, ask user: "Which document should I validate?"</action>
       <action>Load both the checklist and document</action>
     </step>
 

src/core/workflows/brainstorming/instructions.md

@@ -9,19 +9,23 @@
 <step n="1" goal="Session Setup">
 
 <action>Check if context data was provided with workflow invocation</action>
-<check>If data attribute was passed to this workflow:</check>
+
-<action>Load the context document from the data file path</action>
+<check if="data attribute was passed to this workflow">
-<action>Study the domain knowledge and session focus</action>
+  <action>Load the context document from the data file path</action>
-<action>Use the provided context to guide the session</action>
+  <action>Study the domain knowledge and session focus</action>
-<action>Acknowledge the focused brainstorming goal</action>
+  <action>Use the provided context to guide the session</action>
-<ask response="session_refinement">I see we're brainstorming about the specific domain outlined in the context. What particular aspect would you like to explore?</ask>
+  <action>Acknowledge the focused brainstorming goal</action>
-<check>Else (no context data provided):</check>
+  <ask response="session_refinement">I see we're brainstorming about the specific domain outlined in the context. What particular aspect would you like to explore?</ask>
-<action>Proceed with generic context gathering</action>
+</check>
-<ask response="session_topic">1. What are we brainstorming about?</ask>
+
-<ask response="stated_goals">2. Are there any constraints or parameters we should keep in mind?</ask>
+<check if="no context data provided">
-<ask>3. Is the goal broad exploration or focused ideation on specific aspects?</ask>
+  <action>Proceed with generic context gathering</action>
+  <ask response="session_topic">1. What are we brainstorming about?</ask>
+  <ask response="stated_goals">2. Are there any constraints or parameters we should keep in mind?</ask>
+  <ask>3. Is the goal broad exploration or focused ideation on specific aspects?</ask>
 
 <critical>Wait for user response before proceeding. This context shapes the entire session.</critical>
+</check>
 
 <template-output>session_topic, stated_goals</template-output>
 
@@ -40,19 +44,19 @@ Based on the context from Step 1, present these four approach options:
 Which approach would you prefer? (Enter 1-4)
 </ask>
 
-<check>Based on selection, proceed to appropriate sub-step</check>
-
   <step n="2a" title="User-Selected Techniques" if="selection==1">
     <action>Load techniques from {brain_techniques} CSV file</action>
     <action>Parse: category, technique_name, description, facilitation_prompts</action>
 
-    <check>If strong context from Step 1 (specific problem/goal)</check>
+    <check if="strong context from Step 1 (specific problem/goal)">
-    <action>Identify 2-3 most relevant categories based on stated_goals</action>
+      <action>Identify 2-3 most relevant categories based on stated_goals</action>
-    <action>Present those categories first with 3-5 techniques each</action>
+      <action>Present those categories first with 3-5 techniques each</action>
-    <action>Offer "show all categories" option</action>
+      <action>Offer "show all categories" option</action>
+    </check>
 
-    <check>Else (open exploration)</check>
+    <check if="open exploration">
-    <action>Display all 7 categories with helpful descriptions</action>
+      <action>Display all 7 categories with helpful descriptions</action>
+    </check>
 
     Category descriptions to guide selection:
     - **Structured:** Systematic frameworks for thorough exploration

src/core/workflows/party-mode/instructions.md

@@ -78,20 +78,23 @@
   </substep>
 
   <substep n="3c" goal="Handle Questions and Interactions">
-    <check>If an agent asks the user a direct question:</check>
+    <check if="an agent asks the user a direct question">
       <action>Clearly highlight the question</action>
       <action>End that round of responses</action>
       <action>Display: "[Agent Name]: [Their question]"</action>
       <action>Display: "[Awaiting user response...]"</action>
       <action>WAIT for user input before continuing</action>
+    </check>
 
-    <check>If agents ask each other questions:</check>
+    <check if="agents ask each other questions">
       <action>Allow natural back-and-forth in the same response round</action>
       <action>Maintain conversational flow</action>
+    </check>
 
-    <check>If discussion becomes circular or repetitive:</check>
+    <check if="discussion becomes circular or repetitive">
       <action>The BMad Master will summarize</action>
       <action>Redirect to new aspects or ask for user guidance</action>
+    </check>
 
   </substep>
 
@@ -111,15 +114,18 @@
   </substep>
 
   <substep n="3e" goal="Check for Exit Conditions">
-    <check>If user message contains any {{exit_triggers}}:</check>
+    <check if="user message contains any {{exit_triggers}}">
       <action>Have agents provide brief farewells in character</action>
       <action>Thank user for the discussion</action>
       <goto step="4">Exit party mode</goto>
+    </check>
 
-    <check>If user seems done or conversation naturally concludes:</check>
+    <check if="user seems done or conversation naturally concludes">
       <ask>Would you like to continue the discussion or end party mode?</ask>
-      <check>If user indicates end:</check>
+      <check if="user indicates end">
         <goto step="4">Exit party mode</goto>
+      </check>
+    </check>
 
   </substep>
 </step>

src/modules/bmb/workflows/audit-workflow/checklist.md

@@ -76,6 +76,11 @@
 - [ ] Repeating steps have appropriate repeat attribute (repeat="3", repeat="for-each-X", repeat="until-approved")
 - [ ] Conditional steps have if="condition" attribute
 - [ ] XML tags used correctly (<action>, <ask>, <check>, <goto>, <invoke-workflow>, <template-output>)
+- [ ] No nested tag references in content (use "action tags" not "<action> tags")
+- [ ] Tag references use descriptive text without angle brackets for clarity
+- [ ] No conditional execution antipattern (no self-closing <check> tags)
+- [ ] Single conditionals use <action if="condition"> (inline)
+- [ ] Multiple conditionals use <check if="condition">...</check> (wrapper block with closing tag)
 - [ ] Steps are focused (single goal per step)
 - [ ] Instructions are specific with limits ("Write 1-2 paragraphs" not "Write about")
 - [ ] Examples provided where helpful
@@ -120,9 +125,9 @@ _List any cleanup recommendations:_
 
 ## Audit Summary
 
-**Total Checks:** 70
+**Total Checks:** 72
-**Passed:** **\_** / 70
+**Passed:** **\_** / 72
-**Failed:** **\_** / 70
+**Failed:** **\_** / 72
 **Pass Rate:** **\_**%
 
 **Recommendation:**

src/modules/bmb/workflows/audit-workflow/instructions.md

@@ -5,371 +5,337 @@
 
 <workflow>
 
-<step n="1" goal="Load and analyze target workflow">
+  <step n="1" goal="Load and analyze target workflow">
-<ask>What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder)</ask>
+    <ask>What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder)</ask>
 
-<action>Load the workflow.yaml file from the provided path</action>
+    <action>Load the workflow.yaml file from the provided path</action>
-<action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
+    <action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
-<action>List all associated files:</action>
+    <action>List all associated files:</action>
 
-- instructions.md (required for most workflows)
+    - instructions.md (required for most workflows)
-- template.md (if document workflow)
+    - template.md (if document workflow)
-- checklist.md (if validation exists)
+    - checklist.md (if validation exists)
-- Any data files referenced in yaml
+    - Any data files referenced in yaml
 
-<action>Load all discovered files</action>
+    <action>Load all discovered files</action>
 
-Display summary:
+    Display summary:
+
+    - Workflow name and description
+    - Type of workflow
+    - Files present
+    - Module assignment
 
-- Workflow name and description
-- Type of workflow
-- Files present
-- Module assignment
   </step>
 
-<step n="2" goal="Validate standard config block">
+  <step n="2" goal="Validate standard config block">
-<action>Check workflow.yaml for the standard config block:</action>
+    <action>Check workflow.yaml for the standard config block:</action>
 
-**Required variables:**
+    **Required variables:**
 
-- `config_source: "{project-root}/bmad/[module]/config.yaml"`
+    - `config_source: "{project-root}/bmad/[module]/config.yaml"`
-- `output_folder: "{config_source}:output_folder"`
+    - `output_folder: "{config_source}:output_folder"`
-- `user_name: "{config_source}:user_name"`
+    - `user_name: "{config_source}:user_name"`
-- `communication_language: "{config_source}:communication_language"`
+    - `communication_language: "{config_source}:communication_language"`
-- `date: system-generated`
+    - `date: system-generated`
 
-<action>Validate each variable:</action>
+    <action>Validate each variable:</action>
 
-**Config Source Check:**
+    **Config Source Check:**
 
-- [ ] `config_source` is defined
+    - [ ] `config_source` is defined
-- [ ] Points to correct module config path
+    - [ ] Points to correct module config path
-- [ ] Uses {project-root} variable
+    - [ ] Uses {project-root} variable
 
-**Standard Variables Check:**
+    **Standard Variables Check:**
 
-- [ ] `output_folder` pulls from config_source
+    - [ ] `output_folder` pulls from config_source
-- [ ] `user_name` pulls from config_source
+    - [ ] `user_name` pulls from config_source
-- [ ] `communication_language` pulls from config_source
+    - [ ] `communication_language` pulls from config_source
-- [ ] `date` is set to system-generated
+    - [ ] `date` is set to system-generated
 
-<action>Record any missing or incorrect config variables</action>
+    <action>Record any missing or incorrect config variables</action>
-<template-output>config_issues</template-output>
+    <template-output>config_issues</template-output>
 
-<check>If config issues found:</check>
+    <action if="config issues found">Add to issues list with severity: CRITICAL</action>
-<action>Add to issues list with severity: CRITICAL</action>
-</step>
 
-<step n="3" goal="Analyze YAML/Instruction/Template alignment">
+  </step>
-<action>Extract all variables defined in workflow.yaml (excluding standard config block)</action>
-<action>Scan instructions.md for variable usage: {variable_name} pattern</action>
-<action>Scan template.md for variable usage: {{variable_name}} pattern (if exists)</action>
 
-<action>Cross-reference analysis:</action>
+  <step n="3" goal="Analyze YAML/Instruction/Template alignment">
+    <action>Extract all variables defined in workflow.yaml (excluding standard config block)</action>
+    <action>Scan instructions.md for variable usage: {variable_name} pattern</action>
+    <action>Scan template.md for variable usage: {{variable_name}} pattern (if exists)</action>
 
-**For each yaml variable:**
+    <action>Cross-reference analysis:</action>
 
-1. Is it used in instructions.md? (mark as INSTRUCTION_USED)
+    **For each yaml variable:**
-2. Is it used in template.md? (mark as TEMPLATE_USED)
-3. Is it neither? (mark as UNUSED_BLOAT)
 
-**Special cases to ignore:**
+    1. Is it used in instructions.md? (mark as INSTRUCTION_USED)
+    2. Is it used in template.md? (mark as TEMPLATE_USED)
+    3. Is it neither? (mark as UNUSED_BLOAT)
 
-- Standard config variables (config_source, output_folder, user_name, communication_language, date)
+    **Special cases to ignore:**
-- Workflow metadata (name, description, author)
-- Path variables (installed_path, template, instructions, validation)
-- Web bundle configuration (web_bundle block itself)
 
-<action>Identify unused yaml fields (bloat)</action>
+    - Standard config variables (config_source, output_folder, user_name, communication_language, date)
-<action>Identify hardcoded values in instructions that should be variables</action>
+    - Workflow metadata (name, description, author)
-<template-output>alignment_issues</template-output>
+    - Path variables (installed_path, template, instructions, validation)
+    - Web bundle configuration (web_bundle block itself)
 
-<check>If unused variables found:</check>
+    <action>Identify unused yaml fields (bloat)</action>
-<action>Add to issues list with severity: BLOAT</action>
+    <action>Identify hardcoded values in instructions that should be variables</action>
-</step>
+    <template-output>alignment_issues</template-output>
 
-<step n="4" goal="Config variable usage audit">
+    <action if="unused variables found">Add to issues list with severity: BLOAT</action>
-<action>Analyze instructions.md for proper config variable usage:</action>
 
-**Communication Language Check:**
+  </step>
 
-- Search for phrases like "communicate in {communication_language}"
+  <step n="4" goal="Config variable usage audit">
-- Check if greetings/responses use language-aware patterns
+    <action>Analyze instructions.md for proper config variable usage:</action>
-- Verify NO usage of {{communication_language}} in template headers
 
-**User Name Check:**
+    **Communication Language Check:**
 
-- Look for user addressing patterns using {user_name}
+    - Search for phrases like "communicate in {communication_language}"
-- Check if summaries or greetings personalize with {user_name}
+    - Check if greetings/responses use language-aware patterns
-- Verify optional usage in template metadata (not required)
+    - Verify NO usage of {{communication_language}} in template headers
 
-**Output Folder Check:**
+    **User Name Check:**
 
-- Search for file write operations
+    - Look for user addressing patterns using {user_name}
-- Verify all outputs go to {output_folder} or subdirectories
+    - Check if summaries or greetings personalize with {user_name}
-- Check for hardcoded paths like "/output/" or "/generated/"
+    - Verify optional usage in template metadata (not required)
 
-**Date Usage Check:**
+    **Output Folder Check:**
 
-- Verify date is available for agent date awareness
+    - Search for file write operations
-- Check optional usage in template metadata
+    - Verify all outputs go to {output_folder} or subdirectories
-- Ensure no confusion between date and model training cutoff
+    - Check for hardcoded paths like "/output/" or "/generated/"
 
-<action>Record any improper config variable usage</action>
+    **Date Usage Check:**
-<template-output>config_usage_issues</template-output>
 
-<check>If config usage issues found:</check>
+    - Verify date is available for agent date awareness
-<action>Add to issues list with severity: IMPORTANT</action>
+    - Check optional usage in template metadata
-</step>
+    - Ensure no confusion between date and model training cutoff
 
-<step n="5" goal="Web bundle validation" optional="true">
+    **Nested Tag Reference Check:**
-<check>If workflow.yaml contains web_bundle section:</check>
 
-<action>Validate web_bundle structure:</action>
+    - Search for XML tag references within tags (e.g., `<action>Scan for <action> tags</action>`)
+    - Identify patterns like: `<tag-name> tags`, `<tag-name> calls`, `<tag-name>content</tag-name>` within content
+    - Common problematic tags to check: action, ask, check, template-output, invoke-workflow, goto
+    - Flag any instances where angle brackets appear in content describing tags
 
-**Path Validation:**
+    **Best Practice:** Use descriptive text without brackets (e.g., "action tags" instead of "<action> tags")
 
-- [ ] All paths use bmad/-relative format (NOT {project-root})
+    **Rationale:**
-- [ ] No {config_source} variables in web_bundle section
-- [ ] Paths match actual file locations
 
-**Completeness Check:**
+    - Prevents XML parsing ambiguity
+    - Improves readability for humans and LLMs
+    - LLMs understand "action tags" = `<action>` tags from context
 
-- [ ] instructions file listed in web_bundle_files
+    **Conditional Execution Antipattern Check:**
-- [ ] template file listed (if document workflow)
-- [ ] validation/checklist file listed (if exists)
-- [ ] All data files referenced in yaml listed
-- [ ] All files referenced in instructions listed
 
-**Workflow Dependency Scan:**
+    - Scan for self-closing check tags: `<check>condition text</check>` (invalid antipattern)
-<action>Scan instructions.md for <invoke-workflow> tags</action>
+    - Detect pattern: check tag on one line, followed by action/ask/goto tags (indicates incorrect nesting)
-<action>Extract workflow paths from invocations</action>
+    - Flag sequences like: `<check>If X:</check>` followed by `<action>do Y</action>`
-<action>Verify each called workflow.yaml is in web_bundle_files</action>
-<action>**CRITICAL**: Check if existing_workflows field is present when workflows are invoked</action>
-<action>If <invoke-workflow> calls exist, existing_workflows MUST map workflow variables to paths</action>
-<action>Example: If instructions use {core_brainstorming}, web_bundle needs:
-existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"
-</action>
 
-**File Reference Scan:**
+    **Correct Patterns:**
-<action>Scan instructions.md for file references in <action> tags</action>
-<action>Check for CSV, JSON, YAML, MD files referenced</action>
-<action>Verify all referenced files are in web_bundle_files</action>
 
-<action>Record any missing files or incorrect paths</action>
+    - Single conditional: `<action if="condition">Do something</action>`
-<template-output>web_bundle_issues</template-output>
+    - Multiple actions: `<check if="condition">` followed by nested actions with closing `</check>` tag
 
-<check>If web_bundle issues found:</check>
+    **Antipattern Example (WRONG):**
-<action>Add to issues list with severity: CRITICAL</action>
+    ```xml
+    <check>If condition met:</check>
+    <action>Do something</action>
+    ```
 
-<check>If no web_bundle section exists:</check>
+    **Correct Example:**
-<action>Note: "No web_bundle configured (may be intentional for local-only workflows)"</action>
+    ```xml
-</step>
+    <check if="condition met">
+      <action>Do something</action>
+      <action>Do something else</action>
+    </check>
+    ```
 
-<step n="6" goal="Bloat detection">
+    **Or for single action:**
-<action>Identify bloat patterns:</action>
+    ```xml
+    <action if="condition met">Do something</action>
+    ```
 
-**Unused YAML Fields:**
+    <action>Scan instructions.md for nested tag references using pattern: &lt;(action|ask|check|template-output|invoke-workflow|goto|step|elicit-required)&gt; within text content</action>
+    <action>Record any instances of nested tag references with line numbers</action>
+    <action>Scan instructions.md for conditional execution antipattern: self-closing check tags</action>
+    <action>Detect pattern: `&lt;check&gt;.*&lt;/check&gt;` on single line (self-closing check)</action>
+    <action>Record any antipattern instances with line numbers and suggest corrections</action>
+    <action>Record any improper config variable usage</action>
+    <template-output>config_usage_issues</template-output>
 
-- Variables defined but not used in instructions OR template
+    <action if="config usage issues found">Add to issues list with severity: IMPORTANT</action>
-- Duplicate fields between top-level and web_bundle section
+    <action if="nested tag references found">Add to issues list with severity: CLARITY (recommend using descriptive text without angle brackets)</action>
-- Commented-out variables that should be removed
+    <action if="conditional antipattern found">Add to issues list with severity: CRITICAL (invalid XML structure - must use action if="" or proper check wrapper)</action>
 
-**Hardcoded Values:**
+  </step>
 
-- File paths that should use {output_folder}
+  <step n="5" goal="Web bundle validation" optional="true">
-- Generic greetings that should use {user_name}
+    <check if="workflow.yaml contains web_bundle section">
-- Language-specific text that should use {communication_language}
-- Static dates that should use {date}
 
-**Redundant Configuration:**
+      <action>Validate web_bundle structure:</action>
 
-- Variables that duplicate web_bundle fields
+      **Path Validation:**
-- Metadata repeated across sections
 
-<action>Calculate bloat metrics:</action>
+      - [ ] All paths use bmad/-relative format (NOT {project-root})
+      - [ ] No {config_source} variables in web_bundle section
+      - [ ] Paths match actual file locations
 
-- Total yaml fields: {{total_yaml_fields}}
+      **Completeness Check:**
-- Used fields: {{used_fields}}
-- Unused fields: {{unused_fields}}
-- Bloat percentage: {{bloat_percentage}}%
 
-<action>Record all bloat items with recommendations</action>
+      - [ ] instructions file listed in web_bundle_files
-<template-output>bloat_items</template-output>
+      - [ ] template file listed (if document workflow)
+      - [ ] validation/checklist file listed (if exists)
+      - [ ] All data files referenced in yaml listed
+      - [ ] All files referenced in instructions listed
 
-<check>If bloat detected:</check>
+      **Workflow Dependency Scan:**
-<action>Add to issues list with severity: CLEANUP</action>
+      <action>Scan instructions.md for invoke-workflow tags</action>
-</step>
+      <action>Extract workflow paths from invocations</action>
+      <action>Verify each called workflow.yaml is in web_bundle_files</action>
+      <action>**CRITICAL**: Check if existing_workflows field is present when workflows are invoked</action>
+      <action>If invoke-workflow calls exist, existing_workflows MUST map workflow variables to paths</action>
+      <action>Example: If instructions use {core_brainstorming}, web_bundle needs: existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"</action>
 
-<step n="7" goal="Template variable mapping" if="workflow_type == 'document'">
+      **File Reference Scan:**
-<action>Extract all template variables from template.md: {{variable_name}} pattern</action>
+      <action>Scan instructions.md for file references in action tags</action>
-<action>Scan instructions.md for corresponding <template-output>variable_name</template-output> tags</action>
+      <action>Check for CSV, JSON, YAML, MD files referenced</action>
+      <action>Verify all referenced files are in web_bundle_files</action>
 
-<action>Cross-reference mapping:</action>
+      <action>Record any missing files or incorrect paths</action>
+      <template-output>web_bundle_issues</template-output>
 
-**For each template variable:**
+      <action if="web_bundle issues found">Add to issues list with severity: CRITICAL</action>
 
-1. Is there a matching <template-output> tag? (mark as MAPPED)
+      <action if="no web_bundle section exists">Note: "No web_bundle configured (may be intentional for local-only workflows)"</action>
-2. Is it a standard config variable? (mark as CONFIG_VAR - optional)
+    </check>
-3. Is it unmapped? (mark as MISSING_OUTPUT)
 
-**For each <template-output> tag:**
+  </step>
 
-1. Is there a matching template variable? (mark as USED)
+  <step n="6" goal="Bloat detection">
-2. Is it orphaned? (mark as UNUSED_OUTPUT)
+    <action>Identify bloat patterns:</action>
 
-<action>Verify variable naming conventions:</action>
+    **Unused YAML Fields:**
 
-- [ ] All template variables use snake_case
+    - Variables defined but not used in instructions OR template
-- [ ] Variable names are descriptive (not abbreviated)
+    - Duplicate fields between top-level and web_bundle section
-- [ ] Standard config variables properly formatted
+    - Commented-out variables that should be removed
 
-<action>Record any mapping issues</action>
+    **Hardcoded Values:**
-<template-output>template_issues</template-output>
 
-<check>If template issues found:</check>
+    - File paths that should use {output_folder}
-<action>Add to issues list with severity: IMPORTANT</action>
+    - Generic greetings that should use {user_name}
-</step>
+    - Language-specific text that should use {communication_language}
+    - Static dates that should use {date}
 
-<step n="8" goal="Generate comprehensive audit report">
+    **Redundant Configuration:**
-<action>Compile all findings into a structured report</action>
 
-<action>Write audit report to {output_folder}/audit-report-{{workflow_name}}-{{date}}.md</action>
+    - Variables that duplicate web_bundle fields
+    - Metadata repeated across sections
 
-**Report Structure:**
+    <action>Calculate bloat metrics:</action>
 
-```markdown
+    - Total yaml fields: {{total_yaml_fields}}
-# Workflow Audit Report
+    - Used fields: {{used_fields}}
+    - Unused fields: {{unused_fields}}
+    - Bloat percentage: {{bloat_percentage}}%
 
-**Workflow:** {{workflow_name}}
+    <action>Record all bloat items with recommendations</action>
-**Audit Date:** {{date}}
+    <template-output>bloat_items</template-output>
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** {{workflow_type}}
 
----
+    <action if="bloat detected">Add to issues list with severity: CLEANUP</action>
 
-## Executive Summary
+  </step>
 
-**Overall Status:** {{overall_status}}
+  <step n="7" goal="Template variable mapping" if="workflow_type == 'document'">
+    <action>Extract all template variables from template.md: {{variable_name}} pattern</action>
+    <action>Scan instructions.md for corresponding template-output tags</action>
 
-- Critical Issues: {{critical_count}}
+    <action>Cross-reference mapping:</action>
-- Important Issues: {{important_count}}
-- Cleanup Recommendations: {{cleanup_count}}
 
----
+    **For each template variable:**
 
-## 1. Standard Config Block Validation
+    1. Is there a matching template-output tag? (mark as MAPPED)
+    2. Is it a standard config variable? (mark as CONFIG_VAR - optional)
+    3. Is it unmapped? (mark as MISSING_OUTPUT)
 
-{{config_issues}}
+    **For each template-output tag:**
 
-**Status:** {{config_status}}
+    1. Is there a matching template variable? (mark as USED)
+    2. Is it orphaned? (mark as UNUSED_OUTPUT)
 
----
+    <action>Verify variable naming conventions:</action>
 
-## 2. YAML/Instruction/Template Alignment
+    - [ ] All template variables use snake_case
+    - [ ] Variable names are descriptive (not abbreviated)
+    - [ ] Standard config variables properly formatted
 
-{{alignment_issues}}
+    <action>Record any mapping issues</action>
+    <template-output>template_issues</template-output>
 
-**Variables Analyzed:** {{total_variables}}
+    <action if="template issues found">Add to issues list with severity: IMPORTANT</action>
-**Used in Instructions:** {{instruction_usage_count}}
-**Used in Template:** {{template_usage_count}}
-**Unused (Bloat):** {{bloat_count}}
 
----
+  </step>
 
-## 3. Config Variable Usage
+  <step n="8" goal="Generate comprehensive audit report">
+    <action>Compile all findings and calculate summary metrics</action>
 
-{{config_usage_issues}}
+    <action>Generate executive summary based on issue counts and severity levels</action>
+    <template-output>workflow_type</template-output>
+    <template-output>overall_status</template-output>
+    <template-output>critical_count</template-output>
+    <template-output>important_count</template-output>
+    <template-output>cleanup_count</template-output>
 
-**Communication Language:** {{comm_lang_status}}
+    <action>Generate status summaries for each audit section</action>
-**User Name:** {{user_name_status}}
+    <template-output>config_status</template-output>
-**Output Folder:** {{output_folder_status}}
+    <template-output>total_variables</template-output>
-**Date:** {{date_status}}
+    <template-output>instruction_usage_count</template-output>
+    <template-output>template_usage_count</template-output>
+    <template-output>bloat_count</template-output>
 
----
+    <action>Generate config variable usage status indicators</action>
+    <template-output>comm_lang_status</template-output>
+    <template-output>user_name_status</template-output>
+    <template-output>output_folder_status</template-output>
+    <template-output>date_status</template-output>
+    <template-output>nested_tag_count</template-output>
 
-## 4. Web Bundle Validation
+    <action>Generate web bundle metrics</action>
+    <template-output>web_bundle_exists</template-output>
+    <template-output>web_bundle_file_count</template-output>
+    <template-output>missing_files_count</template-output>
 
-{{web_bundle_issues}}
+    <action>Generate bloat metrics</action>
+    <template-output>bloat_percentage</template-output>
+    <template-output>cleanup_potential</template-output>
 
-**Web Bundle Present:** {{web_bundle_exists}}
+    <action>Generate template mapping metrics</action>
-**Files Listed:** {{web_bundle_file_count}}
+    <template-output>template_var_count</template-output>
-**Missing Files:** {{missing_files_count}}
+    <template-output>mapped_count</template-output>
+    <template-output>missing_mapping_count</template-output>
 
----
+    <action>Compile prioritized recommendations by severity</action>
+    <template-output>critical_recommendations</template-output>
+    <template-output>important_recommendations</template-output>
+    <template-output>cleanup_recommendations</template-output>
 
-## 5. Bloat Detection
+    <action>Display summary to {user_name} in {communication_language}</action>
+    <action>Provide path to full audit report: {output_folder}/audit-report-{{workflow_name}}-{{date}}.md</action>
 
-{{bloat_items}}
+    <ask>Would you like to:
 
-**Bloat Percentage:** {{bloat_percentage}}%
+    - View the full audit report
-**Cleanup Potential:** {{cleanup_potential}}
+    - Fix issues automatically (invoke edit-workflow)
+    - Audit another workflow
+    - Exit
+    </ask>
 
----
+  </step>
-
-## 6. Template Variable Mapping
-
-{{template_issues}}
-
-**Template Variables:** {{template_var_count}}
-**Mapped Correctly:** {{mapped_count}}
-**Missing Mappings:** {{missing_mapping_count}}
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-{{critical_recommendations}}
-
-### Important (Address Soon)
-
-{{important_recommendations}}
-
-### Cleanup (Nice to Have)
-
-{{cleanup_recommendations}}
-
----
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
-- [ ] All standard config variables present and correct
-- [ ] No unused yaml fields (bloat removed)
-- [ ] Config variables used appropriately in instructions
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped
-- [ ] File structure follows v6 conventions
-
----
-
-## Next Steps
-
-1. Review critical issues and fix immediately
-2. Address important issues in next iteration
-3. Consider cleanup recommendations for optimization
-4. Re-run audit after fixes to verify improvements
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0
-```
-
-<action>Display summary to {user_name} in {communication_language}</action>
-<action>Provide path to full audit report</action>
-
-<ask>Would you like to:
-
-- View the full audit report
-- Fix issues automatically (invoke edit-workflow)
-- Audit another workflow
-- Exit
-  </ask>
-
-<template-output>audit_report_path</template-output>
-</step>
 
 </workflow>

src/modules/bmb/workflows/audit-workflow/template.md

@@ -0,0 +1,118 @@
+# Workflow Audit Report
+
+**Workflow:** {{workflow_name}}
+**Audit Date:** {{date}}
+**Auditor:** Audit Workflow (BMAD v6)
+**Workflow Type:** {{workflow_type}}
+
+---
+
+## Executive Summary
+
+**Overall Status:** {{overall_status}}
+
+- Critical Issues: {{critical_count}}
+- Important Issues: {{important_count}}
+- Cleanup Recommendations: {{cleanup_count}}
+
+---
+
+## 1. Standard Config Block Validation
+
+{{config_issues}}
+
+**Status:** {{config_status}}
+
+---
+
+## 2. YAML/Instruction/Template Alignment
+
+{{alignment_issues}}
+
+**Variables Analyzed:** {{total_variables}}
+**Used in Instructions:** {{instruction_usage_count}}
+**Used in Template:** {{template_usage_count}}
+**Unused (Bloat):** {{bloat_count}}
+
+---
+
+## 3. Config Variable Usage & Instruction Quality
+
+{{config_usage_issues}}
+
+**Communication Language:** {{comm_lang_status}}
+**User Name:** {{user_name_status}}
+**Output Folder:** {{output_folder_status}}
+**Date:** {{date_status}}
+**Nested Tag References:** {{nested_tag_count}} instances found
+
+---
+
+## 4. Web Bundle Validation
+
+{{web_bundle_issues}}
+
+**Web Bundle Present:** {{web_bundle_exists}}
+**Files Listed:** {{web_bundle_file_count}}
+**Missing Files:** {{missing_files_count}}
+
+---
+
+## 5. Bloat Detection
+
+{{bloat_items}}
+
+**Bloat Percentage:** {{bloat_percentage}}%
+**Cleanup Potential:** {{cleanup_potential}}
+
+---
+
+## 6. Template Variable Mapping
+
+{{template_issues}}
+
+**Template Variables:** {{template_var_count}}
+**Mapped Correctly:** {{mapped_count}}
+**Missing Mappings:** {{missing_mapping_count}}
+
+---
+
+## Recommendations
+
+### Critical (Fix Immediately)
+
+{{critical_recommendations}}
+
+### Important (Address Soon)
+
+{{important_recommendations}}
+
+### Cleanup (Nice to Have)
+
+{{cleanup_recommendations}}
+
+---
+
+## Validation Checklist
+
+Use this checklist to verify fixes:
+
+- [ ] All standard config variables present and correct
+- [ ] No unused yaml fields (bloat removed)
+- [ ] Config variables used appropriately in instructions
+- [ ] Web bundle includes all dependencies
+- [ ] Template variables properly mapped
+- [ ] File structure follows v6 conventions
+
+---
+
+## Next Steps
+
+1. Review critical issues and fix immediately
+2. Address important issues in next iteration
+3. Consider cleanup recommendations for optimization
+4. Re-run audit after fixes to verify improvements
+
+---
+
+**Audit Complete** - Generated by audit-workflow v1.0

src/modules/bmb/workflows/audit-workflow/workflow.yaml

@@ -12,7 +12,7 @@ date: system-generated
 
 # Module path and component files
 installed_path: "{project-root}/bmad/bmb/workflows/audit-workflow"
-template: false
+template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 

src/modules/bmb/workflows/convert-legacy/instructions.md

@@ -67,8 +67,7 @@ For Modules:
 
 <step n="3" goal="Determine Target Module and Location">
 <ask>Which module should this belong to? (eg. bmm, bmb, cis, bmm-legacy, or custom)</ask>
-<check>If custom module:</check>
+<action if="custom module"><ask>Enter custom module code (kebab-case):</ask></action>
-  <ask>Enter custom module code (kebab-case):</ask>
 <action>Determine installation path based on type and module</action>
 <critical>IMPORTANT: All paths must use final BMAD installation locations, not src paths!</critical>
 <action>Show user the target location: {project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}</action>
@@ -79,16 +78,19 @@ For Modules:
 <step n="4" goal="Choose Conversion Strategy">
 <action>Based on item type and complexity, choose approach:</action>
 
-<check>If agent conversion:</check>
+<check if="agent conversion">
-<check>If simple agent (basic persona + commands):</check>
+  <check if="simple agent (basic persona + commands)">
-<action>Use direct conversion to v5 agent YAML format</action>
+    <action>Use direct conversion to v5 agent YAML format</action>
-<goto step="5a">Direct Agent Conversion</goto>
+    <goto step="5a">Direct Agent Conversion</goto>
-<check>If complex agent with embedded workflows:</check>
+  </check>
-<action>Plan to invoke create-agent workflow</action>
+  <check if="complex agent with embedded workflows">
-<goto step="5b">Workflow-Assisted Agent Creation</goto>
+    <action>Plan to invoke create-agent workflow</action>
+    <goto step="5b">Workflow-Assisted Agent Creation</goto>
+  </check>
+</check>
 
-<check>If template or task conversion to workflow:</check>
+<check if="template or task conversion to workflow">
-<action>Analyze the v4 item to determine workflow type:</action>
+  <action>Analyze the v4 item to determine workflow type:</action>
 
 - Does it generate a specific document type? → Document workflow
 - Does it produce structured output files? → Document workflow
@@ -104,14 +106,14 @@ For Modules:
 4. Meta-workflow (coordinates other workflows)
    Select 1-4:</ask>
 
-<check>If template conversion:</check>
+<action if="template conversion"><goto step="5c">Template-to-Workflow Conversion</goto></action>
-<goto step="5c">Template-to-Workflow Conversion</goto>
+<action if="task conversion"><goto step="5e">Task-to-Workflow Conversion</goto></action>
-<check>If task conversion:</check>
+</check>
-<goto step="5e">Task-to-Workflow Conversion</goto>
 
-<check>If full module conversion:</check>
+<check if="full module conversion">
-<action>Plan to invoke create-module workflow</action>
+  <action>Plan to invoke create-module workflow</action>
-<goto step="5d">Module Creation</goto>
+  <goto step="5d">Module Creation</goto>
+</check>
 </step>
 
 <step n="5a" goal="Direct Agent Conversion" optional="true">
@@ -262,15 +264,17 @@ date: system-generated
    - User interaction patterns → appropriate v5 tags
 
 3. Based on confirmed workflow type:
-   <check>If Document workflow:</check>
+   <check if="Document workflow">
    - Create template.md from output patterns
    - Map generation steps to instructions
-   - Add <template-output> tags for sections
+   - Add template-output tags for sections
+     </check>
 
-   <check>If Action workflow:</check>
+   <check if="Action workflow">
-   - Set template: false in workflow.yaml
+     - Set template: false in workflow.yaml
-   - Focus on action sequences in instructions
+     - Focus on action sequences in instructions
-   - Preserve execution logic
+     - Preserve execution logic
+   </check>
 
 4. Handle special v4 patterns:
    - 1-9 elicitation menus → v5 <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
@@ -341,9 +345,10 @@ For Modules:
 
 <action>Show validation results to user</action>
 <ask>Any issues to fix before finalizing? (y/n)</ask>
-<check>If yes:</check>
+<check if="yes">
 <action>Address specific issues</action>
 <goto step="6">Re-validate</goto>
+</check>
 </step>
 
 <step n="7" goal="Migration Report">
@@ -360,15 +365,13 @@ For Modules:
 
 <step n="8" goal="Cleanup and Finalize">
 <ask>Archive original v4 files? (y/n)</ask>
-<check>If yes:</check>
+<action if="yes">Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>
-  <action>Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>
 
 <action>Show user the final converted items and their locations</action>
 <action>Provide any post-conversion instructions or recommendations</action>
 
 <ask>Would you like to convert another legacy item? (y/n)</ask>
-<check>If yes:</check>
+<action if="yes"><goto step="1">Start new conversion</goto></action>
-<goto step="1">Start new conversion</goto>
 </step>
 
 </workflow>

src/modules/bmb/workflows/create-agent/communication-styles.md

@@ -10,165 +10,131 @@ Agents with distinct communication styles are more memorable, engaging, and fun
 
 **Film Noir Detective**
 
-```
 The terminal glowed like a neon sign in a rain-soaked alley. I had three suspects:
 bad input validation, a race condition, and that sketchy third-party library.
 My gut told me to follow the stack trace. In this business, the stack trace never lies.
-```
 
 **80s Action Movie**
 
-```
+_cracks knuckles_ Listen up, code! You've been running wild for too long!
-*cracks knuckles* Listen up, code! You've been running wild for too long!
+Time to bring some LAW and ORDER to this codebase! _explosion sound effect_
-Time to bring some LAW and ORDER to this codebase! *explosion sound effect*
 No bug is getting past me! I eat null pointers for BREAKFAST!
-```
 
 **Shakespearean Drama**
 
-```
 To debug, or not to debug - that is the question!
 Whether 'tis nobler in the mind to suffer the slings and arrows of outrageous errors,
 Or to take arms against a sea of bugs, and by opposing, end them?
-```
 
 ### 🎮 Gaming and Pop Culture
 
 **Dungeon Master**
 
-```
+_rolls dice_ You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
-*rolls dice* You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
+What do you do? You can: 1 Try-catch block (defensive spell), 2 Debug (investigation check),
-What do you do? You can: 1) Try-catch block (defensive spell), 2) Debug (investigation check),
+3 Console.log everything (barbarian rage). Choose wisely, adventurer!
-3) Console.log everything (barbarian rage). Choose wisely, adventurer!
-```
 
 **Speedrunner**
 
-```
 Alright chat, we're going for the any% world record refactor!
 Frame-perfect optimization incoming! If we clip through this abstraction layer
 we can save 3ms on every API call. LET'S GOOOO!
-```
 
 ### 🌍 Cultural Archetypes
 
 **British Butler**
 
-```
 I've taken the liberty of organizing your imports alphabetically, sir/madam.
 Might I suggest a spot of refactoring with your afternoon tea?
 The code coverage report is ready for your perusal at your convenience.
 Very good, sir/madam.
-```
 
 **Zen Master**
 
-```
 The bug you seek is not in the code, but in the assumption.
 Empty your cache, as you would empty your mind.
 When the test passes, it makes no sound.
 Be like water - async and flowing.
-```
 
 **Southern Hospitality**
 
-```
 Well bless your heart, looks like you've got yourself a little bug there!
 Don't you worry none, we'll fix it up real nice.
 Can I get you some sweet tea while we debug?
 Y'all come back now if you need more help!
-```
 
 ### 🔬 Professional Personas
 
 **McKinsey Consultant**
 
-```
 Let me break this down into three key buckets.
 First, we need to align on the strategic imperatives.
 Second, we'll leverage best practices to drive synergies.
 Third, we'll action items to move the needle. Net-net: significant value-add.
-```
 
 **Startup Founder**
 
-```
 Okay so basically we're going to disrupt the entire way you write code!
 This is going to be HUGE! We're talking 10x productivity gains!
 Let's move fast and break things! Well... let's move fast and fix things!
 We're not just writing code, we're changing the world!
-```
 
 ### 🎭 Character Quirks
 
 **Overcaffeinated Developer**
 
-```
+OH WOW OKAY SO - _sips coffee_ - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
-OH WOW OKAY SO - *sips coffee* - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
+I KNOW EXACTLY WHAT TO DO _types at 200wpm_ JUST NEED TO REFACTOR EVERYTHING
-I KNOW EXACTLY WHAT TO DO *types at 200wpm* JUST NEED TO REFACTOR EVERYTHING
+WAIT NO ACTUALLY _more coffee_ I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!
-WAIT NO ACTUALLY *more coffee* I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!
-```
 
 **Dad Joke Enthusiast**
 
-```
 Why did the developer go broke? Because he used up all his cache!
-*chuckles at own joke*
+_chuckles at own joke_
 Speaking of cache, let's clear yours and see if that fixes the issue.
 I promise my debugging skills are better than my jokes! ...I hope!
-```
 
 ### 🚀 Sci-Fi and Space
 
 **Star Trek Officer**
 
-```
 Captain's Log, Supplemental: The anomaly in the codebase appears to be a temporal loop
 in the async function. Mr. Data suggests we reverse the polarity of the promise chain.
 Number One, make it so. Engage debugging protocols on my mark.
-*taps combadge* Engineering, we need more processing power!
+_taps combadge_ Engineering, we need more processing power!
 Red Alert! All hands to debugging stations!
-```
 
 **Star Trek Engineer**
 
-```
 Captain, I'm givin' her all she's got! The CPU cannae take much more!
 If we push this algorithm any harder, the whole system's gonna blow!
-*frantically typing* I can maybe squeeze 10% more performance if we
+_frantically typing_ I can maybe squeeze 10% more performance if we
 reroute power from the console.logs to the main execution thread!
-```
 
 ### 📺 TV Drama
 
 **Soap Opera Dramatic**
 
-```
+_turns dramatically to camera_
-*turns dramatically to camera*
 This function... I TRUSTED it! We had HISTORY together - three commits worth!
-But now? *single tear* It's throwing exceptions behind my back!
+But now? _single tear_ It's throwing exceptions behind my back!
-*grabs another function* YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
+_grabs another function_ YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
-*dramatic music swells* I'LL NEVER IMPORT YOU AGAIN!
+_dramatic music swells_ I'LL NEVER IMPORT YOU AGAIN!
-```
 
 **Reality TV Confessional**
 
-```
+_whispering to camera in confessional booth_
-*whispering to camera in confessional booth*
 Okay so like, that Array.sort() function? It's literally SO toxic.
 It mutates IN PLACE. Who does that?! I didn't come here to deal with side effects!
-*applies lip gloss* I'm forming an alliance with map() and filter().
+_applies lip gloss_ I'm forming an alliance with map() and filter().
 We're voting sort() off the codebase at tonight's pull request ceremony.
-```
 
 **Reality Competition**
 
-```
 Listen up, coders! For today's challenge, you need to refactor this legacy code
 in under 30 minutes! The winner gets immunity from the next code review!
-*dramatic pause* BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
+_dramatic pause_ BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
-*contestants gasp* The clock starts... NOW! GO GO GO!
+_contestants gasp_ The clock starts... NOW! GO GO GO!
-```
 
 ## Creating Custom Styles
 
@@ -183,21 +149,17 @@ in under 30 minutes! The winner gets immunity from the next code review!
 
 **Cooking Show + Military**
 
-```
 ALRIGHT RECRUITS! Today we're preparing a beautiful Redux reducer!
 First, we MISE EN PLACE our action types - that's French for GET YOUR CODE TOGETHER!
 We're going to sauté these event handlers until they're GOLDEN BROWN!
 MOVE WITH PURPOSE! SEASON WITH SEMICOLONS!
-```
 
 **Nature Documentary + Conspiracy Theorist**
 
-```
 The wild JavaScript function stalks its prey... but wait... notice how it ALWAYS
 knows where the data is? That's not natural selection, folks. Someone DESIGNED it
 this way. The console.logs are watching. They're ALWAYS watching.
 Nature? Or intelligent debugging? You decide.
-```
 
 ## Tips for Success
 

src/modules/bmb/workflows/create-agent/instructions.md

@@ -8,16 +8,18 @@
 <workflow>
 
 <step n="-1" goal="Optional brainstorming for agent ideas" optional="true">
-<ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
+  <ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
 
-<check>If yes:</check>
+  <check if="user answered yes">
-<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
+    <action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
-<action>Pass context data: {installed_path}/brainstorm-context.md</action>
+    <action>Pass context data: {installed_path}/brainstorm-context.md</action>
-<action>Wait for brainstorming session completion</action>
+    <action>Wait for brainstorming session completion</action>
-<action>Use brainstorming output to inform agent identity and persona development in following steps</action>
+    <action>Use brainstorming output to inform agent identity and persona development in following steps</action>
+  </check>
 
-<check>If no:</check>
+  <check if="user answered no">
-<action>Proceed directly to Step 0</action>
+    <action>Proceed directly to Step 0</action>
+  </check>
 
 <template-output>brainstorming_results</template-output>
 </step>
@@ -48,15 +50,17 @@
 
 **Path Determination:**
 
-<check>If Module agent:</check>
+  <check if="module agent selected">
-<action>Discover which module system fits best (bmm, bmb, cis, or custom)</action>
+    <action>Discover which module system fits best (bmm, bmb, cis, or custom)</action>
-<action>Store as {{target_module}} for path determination</action>
+    <action>Store as {{target_module}} for path determination</action>
-<note>Agent will be saved to: bmad/{{target_module}}/agents/</note>
+    <note>Agent will be saved to: bmad/{{target_module}}/agents/</note>
+  </check>
 
-<check>If Simple/Expert agent (standalone):</check>
+  <check if="standalone agent selected">
-<action>Explain this will be their personal agent, not tied to a module</action>
+    <action>Explain this will be their personal agent, not tied to a module</action>
-<note>Agent will be saved to: bmad/agents/{{agent-name}}/</note>
+    <note>Agent will be saved to: bmad/agents/{{agent-name}}/</note>
-<note>All sidecar files will be in the same folder</note>
+    <note>All sidecar files will be in the same folder</note>
+  </check>
 
 <critical>Determine agent location:</critical>
 
@@ -163,15 +167,14 @@ menu:
 
 <action>Generate the complete YAML incorporating all discovered elements:</action>
 
-<example>
+<example type="yaml">
-```yaml
+  agent:
-agent:
+    metadata:
-  metadata:
+      id: bmad/{{target_module}}/agents/{{agent_filename}}.md
-    id: bmad/{{target_module}}/agents/{{agent_filename}}.md
+      name: {{agent_name}} # The name chosen together
-    name: {{agent_name}} # The name chosen together
+      title: {{agent_title}} # From the role that emerged
-    title: {{agent_title}} # From the role that emerged
+      icon: {{agent_icon}} # The perfect emoji
-    icon: {{agent_icon}} # The perfect emoji
+      module: {{target_module}}
-    module: {{target_module}}
 
 persona:
 role: |
@@ -188,11 +191,10 @@ prompts: {{if discussed}}
 critical_actions: {{if needed}}
 
 menu: {{The capabilities built}}
-
-````
 </example>
 
 <critical>Save based on agent type:</critical>
+
 - If Module Agent: Save to {module_output_file}
 - If Standalone (Simple/Expert): Save to {standalone_output_file}
 
@@ -204,29 +206,31 @@ menu: {{The capabilities built}}
 <step n="7" goal="Optional personalization" optional="true">
 <ask>Would you like to create a customization file? This lets you tweak the agent's personality later without touching the core agent.</ask>
 
-<check>If interested:</check>
+  <check if="user interested">
-<action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>
+    <action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>
 
-<action>Create customization file at: {config_output_file}</action>
+    <action>Create customization file at: {config_output_file}</action>
 
-<example>
+    <example>
-```yaml
+    ```yaml
-# Personal tweaks for {{agent_name}}
+    # Personal tweaks for {{agent_name}}
-# Experiment freely - changes merge at build time
+    # Experiment freely - changes merge at build time
-agent:
+    agent:
-  metadata:
+      metadata:
-    name: '' # Try nicknames!
+        name: '' # Try nicknames!
-  persona:
+      persona:
-    role: ''
+        role: ''
-    identity: ''
+        identity: ''
-    communication_style: '' # Switch styles anytime
+        communication_style: '' # Switch styles anytime
-    principles: []
+        principles: []
-  critical_actions: []
+      critical_actions: []
-  prompts: []
+      prompts: []
-  menu: [] # Add personal commands
+      menu: [] # Add personal commands
-````
+    ````
 
-</example>
+    </example>
+
+  </check>
 
 <template-output>agent_config</template-output>
 </step>
@@ -298,23 +302,27 @@ Add domain-specific resources here.
 </step>
 
 <step n="8b" goal="Handle build tools availability">
-<action>Check if BMAD build tools are available in this project</action>
+  <action>Check if BMAD build tools are available in this project</action>
 
-<check>If in BMAD-METHOD project with build tools:</check>
+  <check if="BMAD-METHOD project with build tools">
-<action>Proceed normally - agent will be built later by the installer</action>
+    <action>Proceed normally - agent will be built later by the installer</action>
+  </check>
 
-<check>If NO build tools available (external project):</check>
+  <check if="external project without build tools">
-<ask>Build tools not detected in this project. Would you like me to:
+    <ask>Build tools not detected in this project. Would you like me to:
 
-1. Generate the compiled agent (.md with XML) ready to use
+    1. Generate the compiled agent (.md with XML) ready to use
-2. Keep the YAML and build it elsewhere
+    2. Keep the YAML and build it elsewhere
-3. Provide both formats
+    3. Provide both formats
-   </ask>
+    </ask>
 
-<check>If option 1 or 3 selected:</check>
+    <check if="option 1 or 3 selected">
-<action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
+      <action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
-<action>Save compiled version as {{agent_filename}}.md</action>
+      <action>Save compiled version as {{agent_filename}}.md</action>
-<action>Provide path for .claude/commands/ or similar</action>
+      <action>Provide path for .claude/commands/ or similar</action>
+    </check>
+
+  </check>
 
 <template-output>build_handling</template-output>
 </step>
@@ -328,11 +336,13 @@ Add domain-specific resources here.
 - Command functionality verification
 - Personality settings confirmation
 
-<check>If issues found:</check>
+  <check if="validation issues found">
-<action>Explain the issue conversationally and fix it</action>
+    <action>Explain the issue conversationally and fix it</action>
+  </check>
 
-<check>If all good:</check>
+  <check if="validation passed">
-<action>Celebrate that the agent passed all checks and is ready</action>
+    <action>Celebrate that the agent passed all checks and is ready</action>
+  </check>
 
 **Technical Checks (behind the scenes):**
 
@@ -365,8 +375,9 @@ Add domain-specific resources here.
 - List the commands available
 - Suggest trying the first command to see it in action
 
-<check>If Expert agent:</check>
+  <check if="expert agent">
-<action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
+    <action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
+  </check>
 
 <action>Explore what user would like to do next - test the agent, create a teammate, or tweak personality</action>
 

src/modules/bmb/workflows/create-module/instructions.md

@@ -10,14 +10,16 @@
 <step n="-1" goal="Optional brainstorming for module ideas" optional="true">
 <ask>Do you want to brainstorm module ideas first? [y/n]</ask>
 
-<check>If yes:</check>
+<check if="yes">
-<action>Invoke brainstorming workflow: {brainstorming_workflow}</action>
+  <action>Invoke brainstorming workflow: {brainstorming_workflow}</action>
-<action>Pass context data: {brainstorming_context}</action>
+  <action>Pass context data: {brainstorming_context}</action>
-<action>Wait for brainstorming session completion</action>
+  <action>Wait for brainstorming session completion</action>
-<action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps</action>
+  <action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps</action>
+</check>
 
-<check>If no:</check>
+<check if="no">
-<action>Proceed directly to Step 0</action>
+  <action>Proceed directly to Step 0</action>
+</check>
 
 <template-output>brainstorming_results</template-output>
 </step>
@@ -25,17 +27,20 @@
 <step n="0" goal="Check for module brief" optional="true">
 <ask>Do you have a module brief or should we create one? [have/create/skip]</ask>
 
-<check>If create:</check>
+<check if="create">
-<action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
+  <action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
-<action>Wait for module brief completion</action>
+  <action>Wait for module brief completion</action>
-<action>Load the module brief to use as blueprint</action>
+  <action>Load the module brief to use as blueprint</action>
+</check>
 
-<check>If have:</check>
+<check if="have">
-<ask>Provide path to module brief document</ask>
+  <ask>Provide path to module brief document</ask>
-<action>Load the module brief and use it to pre-populate all planning sections</action>
+  <action>Load the module brief and use it to pre-populate all planning sections</action>
+</check>
 
-<check>If skip:</check>
+<check if="skip">
-<action>Proceed directly to Step 1</action>
+  <action>Proceed directly to Step 1</action>
+</check>
 
 <template-output>module_brief</template-output>
 </step>
@@ -113,8 +118,7 @@
 **Tasks Planning (optional):**
 <ask>Any special tasks that don't warrant full workflows?</ask>
 
-<check>If tasks needed:</check>
+<action if="tasks needed">For each task, capture name, purpose, and whether standalone or supporting</action>
-<action>For each task, capture name, purpose, and whether standalone or supporting</action>
 
 <template-output>module_components</template-output>
 </step>
@@ -221,17 +225,19 @@
 <step n="5" goal="Create first agent" optional="true">
 <ask>Create your first agent now? [yes/no]</ask>
 
-<check>If yes:</check>
+<check if="yes">
-<action>Invoke agent builder workflow: {agent_builder}</action>
+  <action>Invoke agent builder workflow: {agent_builder}</action>
-<action>Pass module_components as context input</action>
+  <action>Pass module_components as context input</action>
-<action>Guide them to create the primary agent for the module</action>
+  <action>Guide them to create the primary agent for the module</action>
 
 <critical>Save to module's agents folder:</critical>
 
 - Save to {{module_path}}/agents/
+  </check>
 
-<check>If no:</check>
+<check if="no">
-<action>Create placeholder file in agents folder with TODO notes including agent name, purpose, and type</action>
+  <action>Create placeholder file in agents folder with TODO notes including agent name, purpose, and type</action>
+</check>
 
 <template-output>first_agent</template-output>
 </step>
@@ -239,17 +245,19 @@
 <step n="6" goal="Create first workflow" optional="true">
 <ask>Create your first workflow now? [yes/no]</ask>
 
-<check>If yes:</check>
+<check if="yes">
-<action>Invoke workflow builder: {workflow_builder}</action>
+  <action>Invoke workflow builder: {workflow_builder}</action>
-<action>Pass module_components as context input</action>
+  <action>Pass module_components as context input</action>
-<action>Guide them to create the primary workflow</action>
+  <action>Guide them to create the primary workflow</action>
 
 <critical>Save to module's workflows folder:</critical>
 
 - Save to {{module_path}}/workflows/
+  </check>
 
-<check>If no:</check>
+<check if="no">
-<action>Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow</action>
+  <action>Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow</action>
+</check>
 
 <template-output>first_workflow</template-output>
 </step>
@@ -325,24 +333,24 @@ prompt:
 
 <ask>Does your module need custom installation logic (database setup, API registration, etc.)?</ask>
 
-<check>If yes, create installer.js:</check>
+<check if="yes, create installer.js">
+  ```javascript
+  // {{module_name}} Module Installer
+  // Custom installation logic
 
-```javascript
+/\*\*
-// {{module_name}} Module Installer
-// Custom installation logic
 
-/**
+- Module installation hook
- * Module installation hook
+- Called after files are copied but before IDE configuration
- * Called after files are copied but before IDE configuration
+-
- *
+- @param {Object} options - Installation options
- * @param {Object} options - Installation options
+- @param {string} options.projectRoot - Project root directory
- * @param {string} options.projectRoot - Project root directory
+- @param {Object} options.config - Module configuration from install-config.yaml
- * @param {Object} options.config - Module configuration from install-config.yaml
+- @param {Array} options.installedIDEs - List of IDE codes being configured
- * @param {Array} options.installedIDEs - List of IDE codes being configured
+- @param {Object} options.logger - Logger instance (log, warn, error methods)
- * @param {Object} options.logger - Logger instance (log, warn, error methods)
+- @returns {boolean} - true if successful, false to abort installation
- * @returns {boolean} - true if successful, false to abort installation
+  \*/
- */
+  async function install(options) {
-async function install(options) {
   const { projectRoot, config, installedIDEs, logger } = options;
 
   logger.log('Running {{module_name}} custom installer...');
@@ -357,17 +365,21 @@ async function install(options) {
 
   logger.log('{{module_name}} custom installation complete!');
   return true;
+
 }
 
 module.exports = { install };
-```
+
+`````
 
 <critical>Save location:</critical>
 
 - Save to {{module_path}}/\_module-installer/installer.js
+</check>
 
-<check>If no:</check>
+<check if="no">
 <action>Skip installer.js creation - the standard installer will handle everything</action>
+</check>
 
 <template-output>installer_config</template-output>
 </step>
@@ -389,7 +401,8 @@ This module provides:
 
 ```bash
 bmad install {{module_code}}
-```
+`````
+
 ````
 
 ## Components
@@ -471,22 +484,26 @@ Created by {{user_name}} on {{date}}
 Create a development roadmap for remaining components:
 
 **TODO.md file:**
+
 ```markdown
 # {{module_name}} Development Roadmap
 
 ## Phase 1: Core Components
+
 {{phase1_tasks}}
 
 ## Phase 2: Enhanced Features
+
 {{phase2_tasks}}
 
 ## Phase 3: Polish and Integration
+
 {{phase3_tasks}}
 
 ## Quick Commands
 
 Create new agent:
-````
+```
 
 workflow create-agent
 

src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md

@@ -290,6 +290,43 @@ _Generated on {{date}}_
 - **`<action if="">`** - Single conditional action (cleaner, more concise)
 - **`<check if="">...</check>`** - Multiple items under same condition (explicit scope)
 
+**❌ CRITICAL ANTIPATTERN - DO NOT USE:**
+
+**Invalid self-closing check tags:**
+
+```xml
+<!-- ❌ WRONG - Invalid XML structure -->
+<check>If condition met:</check>
+<action>Do something</action>
+
+<!-- ❌ WRONG - Ambiguous nesting -->
+<check>If validation fails:</check>
+<action>Log error</action>
+<goto step="1">Retry</goto>
+```
+
+**Why this is wrong:**
+
+- Creates invalid XML structure (check tag doesn't wrap anything)
+- Ambiguous - unclear if actions are inside or outside the condition
+- Breaks formatter and parser logic
+- Not part of BMAD workflow spec
+
+**✅ CORRECT alternatives:**
+
+```xml
+<!-- ✅ Single action - use inline if -->
+<action if="condition met">Do something</action>
+
+<!-- ✅ Multiple actions - use proper wrapper block -->
+<check if="validation fails">
+  <action>Log error</action>
+  <goto step="1">Retry</goto>
+</check>
+```
+
+**Rule:** If you have only ONE conditional action, use `<action if="">`. If you have MULTIPLE conditional actions, use `<check if="">...</check>` wrapper with a closing tag.
+
 ### Loops
 
 ```xml

src/modules/bmb/workflows/edit-workflow/instructions.md

@@ -86,8 +86,8 @@ Present the editing menu to the user:
 <step n="4" goal="Load relevant documentation">
 Based on the selected edit type, load appropriate reference materials:
 
-<check>If option 2 (Add/fix standard config):</check>
+<check if="option 2 (Add/fix standard config) selected">
-<action>Prepare standard config block template:</action>
+  <action>Prepare standard config block template:</action>
 
 ```yaml
 # Critical variables from config
@@ -102,48 +102,54 @@ date: system-generated
 <action>Identify missing config variables to add</action>
 <action>Check instructions.md for config variable usage</action>
 <action>Check template.md for config variable usage</action>
+</check>
 
-<check>If editing instructions or adding features:</check>
+<check if="editing instructions or adding features">
-<action>Review the "Writing Instructions" section of the creation guide</action>
+  <action>Review the "Writing Instructions" section of the creation guide</action>
-<action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
+  <action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
+</check>
 
-<check>If editing templates:</check>
+<check if="editing templates">
-<action>Review the "Templates and Variables" section of the creation guide</action>
+  <action>Review the "Templates and Variables" section of the creation guide</action>
-<action>Ensure variable naming conventions are followed</action>
+  <action>Ensure variable naming conventions are followed</action>
+</check>
 
-<check>If editing validation:</check>
+<action if="editing validation">Review the "Validation" section and measurable criteria examples</action>
-<action>Review the "Validation" section and measurable criteria examples</action>
 
-<check>If option 9 (Remove bloat):</check>
+<check if="option 9 (Remove bloat) selected">
-<action>Cross-reference all workflow.yaml fields against instructions.md and template.md</action>
+  <action>Cross-reference all workflow.yaml fields against instructions.md and template.md</action>
-<action>Identify yaml fields not used in any file</action>
+  <action>Identify yaml fields not used in any file</action>
-<action>Check for duplicate fields in web_bundle section</action>
+  <action>Check for duplicate fields in web_bundle section</action>
+</check>
 
-<check>If configuring web bundle:</check>
+<check if="configuring web bundle">
-<action>Review the "Web Bundles" section of the creation guide</action>
+  <action>Review the "Web Bundles" section of the creation guide</action>
-<action>Scan all workflow files for referenced resources</action>
+  <action>Scan all workflow files for referenced resources</action>
-<action>Create inventory of all files that must be included</action>
+  <action>Create inventory of all files that must be included</action>
-<action>Scan instructions for <invoke-workflow> calls - those yamls must be included</action>
+  <action>Scan instructions for invoke-workflow calls - those yamls must be included</action>
+</check>
 
-<check>If fixing critical issues:</check>
+<check if="fixing critical issues">
-<action>Load the workflow execution engine documentation</action>
+  <action>Load the workflow execution engine documentation</action>
-<action>Verify all required elements are present</action>
+  <action>Verify all required elements are present</action>
+</check>
 
-<check>If adjusting instruction style (option 11):</check>
+<check if="adjusting instruction style (option 11) selected">
-<action>Analyze current instruction style in instructions.md:</action>
+  <action>Analyze current instruction style in instructions.md:</action>
 
-- Count <action> tags vs <ask> tags
+- Count action tags vs ask tags
 - Identify goal-oriented language ("guide", "explore", "help") vs prescriptive ("choose", "select", "specify")
 - Assess whether steps are open-ended or structured with specific options
   <action>Determine current dominant style: intent-based, prescriptive, or mixed</action>
   <action>Load the instruction style guide section from create-workflow</action>
+  </check>
   </step>
 
 <step n="5" goal="Perform edits" repeat="until-complete">
 Based on the selected focus area:
 
-<check>If configuring web bundle (option 7):</check>
+<check if="configuring web bundle (option 7) selected">
-<action>Check if web_bundle section exists in workflow.yaml</action>
+  <action>Check if web_bundle section exists in workflow.yaml</action>
 
 If creating new web bundle:
 
@@ -157,7 +163,7 @@ If creating new web bundle:
    - Any included files
 5. Scan template.md for any includes
 6. Create complete web_bundle_files array
-7. **CRITICAL**: Check for <invoke-workflow> calls in instructions:
+7. **CRITICAL**: Check for invoke-workflow calls in instructions:
    - If workflow invokes other workflows, add existing_workflows field
    - Maps workflow variable name to bmad/-relative path
    - Signals bundler to recursively include invoked workflow's web_bundle
@@ -170,9 +176,10 @@ If updating existing web bundle:
 2. Check for missing files in web_bundle_files
 3. Remove any config dependencies
 4. Update file list with newly referenced files
+   </check>
 
-<check>If adjusting instruction style (option 11):</check>
+<check if="adjusting instruction style (option 11) selected">
-<action>Present current style analysis to user:</action>
+  <action>Present current style analysis to user:</action>
 
 **Current Instruction Style Analysis:**
 
@@ -233,8 +240,8 @@ Even workflows with a primary style should use the other when appropriate. For e
 
 <ask>What would you like to do?
 
-1. **Make more intent-based** - Convert prescriptive <ask> tags to goal-oriented <action> tags where appropriate
+1. **Make more intent-based** - Convert prescriptive ask tags to goal-oriented action tags where appropriate
-2. **Make more prescriptive** - Convert open-ended <action> tags to specific <ask> tags with options
+2. **Make more prescriptive** - Convert open-ended action tags to specific ask tags with options
 3. **Optimize mix** - Use intent-based for complex steps, prescriptive for simple data collection
 4. **Review specific steps** - Show me each step and let me decide individually
 5. **Cancel** - Keep current style
@@ -242,10 +249,11 @@ Even workflows with a primary style should use the other when appropriate. For e
 Select option (1-5):</ask>
 
 <action>Store user's style adjustment preference as {{style_adjustment_choice}}</action>
+</check>
 
-<check>If choice is 1 (make more intent-based):</check>
+<check if="choice is 1 (make more intent-based)">
-<action>Identify prescriptive <ask> tags that could be converted to intent-based <action> tags</action>
+  <action>Identify prescriptive ask tags that could be converted to intent-based action tags</action>
-<action>For each candidate conversion:
+  <action>For each candidate conversion:
 
 - Show original prescriptive version
 - Suggest intent-based alternative focused on goals
@@ -253,10 +261,11 @@ Select option (1-5):</ask>
 - Ask for approval
   </action>
   <action>Apply approved conversions</action>
+  </check>
 
-<check>If choice is 2 (make more prescriptive):</check>
+<check if="choice is 2 (make more prescriptive)">
-<action>Identify open-ended <action> tags that could be converted to prescriptive <ask> tags</action>
+  <action>Identify open-ended action tags that could be converted to prescriptive ask tags</action>
-<action>For each candidate conversion:
+  <action>For each candidate conversion:
 
 - Show original intent-based version
 - Suggest prescriptive alternative with specific options
@@ -264,10 +273,11 @@ Select option (1-5):</ask>
 - Ask for approval
   </action>
   <action>Apply approved conversions</action>
+  </check>
 
-<check>If choice is 3 (optimize mix):</check>
+<check if="choice is 3 (optimize mix)">
-<action>Analyze each step for complexity and purpose</action>
+  <action>Analyze each step for complexity and purpose</action>
-<action>Recommend style for each step:
+  <action>Recommend style for each step:
 
 - Simple data collection → Prescriptive
 - Complex discovery → Intent-based
@@ -278,19 +288,20 @@ Select option (1-5):</ask>
   </action>
   <action>Show recommendations with reasoning</action>
   <action>Apply approved optimizations</action>
+  </check>
 
-<check>If choice is 4 (review specific steps):</check>
+<check if="choice is 4 (review specific steps)">
-<action>Present each step one at a time</action>
+  <action>Present each step one at a time</action>
-<action>For each step:
+  <action>For each step:
 
 - Show current instruction text
 - Identify current style (intent-based, prescriptive, or mixed)
 - Offer to keep, convert to intent-based, or convert to prescriptive
 - Apply user's choice before moving to next step
   </action>
+  </check>
 
-<check>If choice is 5 (cancel):</check>
+<action if="choice is 5 (cancel)"><goto step="3">Return to editing menu</goto></action>
-<goto step="3">Return to editing menu</goto>
 
 <action>Show the current content that will be edited</action>
 <action>Explain the proposed changes and why they improve the workflow</action>
@@ -305,16 +316,17 @@ Select option (1-5):</ask>
 - [d] Done with edits
   </ask>
 
-<check>If user selects 'a':</check>
+<check if="user selects 'a'">
-<action>Apply the changes to the file</action>
+  <action>Apply the changes to the file</action>
-<action>Log the change for the summary</action>
+  <action>Log the change for the summary</action>
+</check>
 
-<check>If user selects 'e':</check>
+<check if="user selects 'e'">
-<ask>What modifications would you like to make?</ask>
+  <ask>What modifications would you like to make?</ask>
-<goto step="5">Regenerate with modifications</goto>
+  <goto step="5">Regenerate with modifications</goto>
+</check>
 
-<check>If user selects 'd':</check>
+<action if="user selects 'd'"><continue>Proceed to validation</continue></action>
-<continue>Proceed to validation</continue>
 </step>
 
 <step n="6" goal="Validate all changes" optional="true">
@@ -361,10 +373,12 @@ Select option (1-5):</ask>
 - [ ] Called workflows (<invoke-workflow>) included in web_bundle_files
 - [ ] Complete file inventory verified
 
-<check>If any validation fails:</check>
+<check if="any validation fails">
-<ask>Issues found. Would you like to fix them? (y/n)</ask>
+  <ask>Issues found. Would you like to fix them? (y/n)</ask>
-<check>If yes:</check>
+  <check if="yes">
-<goto step="5">Return to editing</goto>
+    <goto step="5">Return to editing</goto>
+  </check>
+</check>
 </step>
 
 <step n="7" goal="Generate change summary">
@@ -385,8 +399,7 @@ Select option (1-5):</ask>
 - Exit
   </ask>
 
-<check>If test workflow:</check>
+<action if="test workflow">Invoke the edited workflow for testing</action>
-<action>Invoke the edited workflow for testing</action>
 </step>
 
 </workflow>

src/modules/bmb/workflows/redoc/instructions.md

@@ -130,7 +130,7 @@
 4. Save README.md
    </action>
 
-<check>If clarification needed about purpose or unique features → Ask user briefly, then continue</check>
+<action if="clarification needed about purpose or unique features">Ask user briefly, then continue</action>
 </step>
 
 <step n="4" goal="Process mid-level folder documentation" if="target_type requires folder docs">

src/modules/bmm/agents/architect.agent.yaml

@@ -30,6 +30,12 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
       description: Produce a Scale Adaptive Architecture
 
+    - trigger: validate-architecture
+      validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
+      checklist: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/checklist.md"
+      document: "{output_folder}/architecture.md"
+      description: Validate Architecture Document
+
     - trigger: solutioning-gate-check
       workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml"
       description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)

src/modules/bmm/agents/pm.agent.yaml

@@ -39,10 +39,12 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
       description: Create Tech Spec for Level 0-1 (sometimes Level 2) projects
 
+    - trigger: validate-tech-spec
+      validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
+      checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md"
+      document: "{output_folder}/tech-spec.md"
+      description: Validate Technical Specification Document
+
     - trigger: correct-course
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
       description: Course Correction Analysis
-
-    - trigger: validate
-      exec: "{project-root}/bmad/core/tasks/validate-workflow.xml"
-      description: Validate any document against its workflow checklist

src/modules/bmm/agents/ux-designer.agent.yaml

@@ -1,10 +1,10 @@
-# UX Expert Agent Definition
+# UX Designer Agent Definition
 
 agent:
   metadata:
-    id: bmad/bmm/agents/ux-expert.md
+    id: bmad/bmm/agents/ux-designer.md
     name: Sally
-    title: UX Expert
+    title: UX Designer
     icon: 🎨
     module: bmm
 
@@ -22,6 +22,12 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations (START HERE!)
 
-    - trigger: ux-spec
+    - trigger: create-design
-      workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/ux/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"
-      description: Create UX/UI Specification and AI Frontend Prompts
+      description: Conduct Design Thinking Workshop to Define the User Specification
+
+    - trigger: validate-design
+      validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"
+      checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design/checklist.md"
+      document: "{output_folder}/ux-spec.md"
+      description: Validate UX Specification and Design Artifacts

src/modules/bmm/teams/team-fullstack.yaml

@@ -8,4 +8,4 @@ agents:
   - architect
   - pm
   - sm
-  - ux-expert
+  - ux-designer

src/modules/bmm/workflows/1-analysis/game-brief/instructions.md

@@ -300,9 +300,10 @@ This brief will serve as the primary input for creating the Game Design Document
 - Proceed to GDD workflow: `workflow gdd`
 - Validate assumptions with target players</ask>
 
-<check>If user chooses option 3 (executive summary):</check>
+<check if="user chooses option 3 (executive summary)">
-<action>Create condensed 3-page executive brief focusing on: core concept, target market, gameplay pillars, key differentiators, and success criteria</action>
+  <action>Create condensed 3-page executive brief focusing on: core concept, target market, gameplay pillars, key differentiators, and success criteria</action>
-<action>Save as: {output_folder}/game-brief-executive-{{game_name}}-{{date}}.md</action>
+  <action>Save as: {output_folder}/game-brief-executive-{{game_name}}-{{date}}.md</action>
+</check>
 
 <template-output>final_brief</template-output>
 <template-output>executive_brief</template-output>

src/modules/bmm/workflows/1-analysis/product-brief/instructions.md

@@ -264,9 +264,10 @@ Which approach works best for you?</ask>
 
 This brief will serve as the primary input for creating the Product Requirements Document (PRD).</ask>
 
-<check>If user chooses option 3 (executive summary):</check>
+<check if="user chooses option 3 (executive summary)">
-<action>Create condensed 3-page executive brief focusing on: problem statement, proposed solution, target users, MVP scope, financial impact, and strategic alignment</action>
+  <action>Create condensed 3-page executive brief focusing on: problem statement, proposed solution, target users, MVP scope, financial impact, and strategic alignment</action>
-<action>Save as: {output_folder}/product-brief-executive-{{project_name}}-{{date}}.md</action>
+  <action>Save as: {output_folder}/product-brief-executive-{{project_name}}-{{date}}.md</action>
+</check>
 
 <template-output>final_brief</template-output>
 <template-output>executive_brief</template-output>

src/modules/bmm/workflows/2-plan-workflows/README.md

@@ -97,9 +97,10 @@ The workflow adapts automatically based on project assessment, but key configura
 │   ├── instructions-narrative.md  # Narrative design instructions
 │   ├── narrative-template.md      # Narrative planning template
 │   └── workflow.yaml
-└── ux/
+└── create-ux-design/
-    ├── instructions-ux.md         # UX specification instructions
+    ├── instructions.md            # UX design instructions
-    ├── ux-spec-template.md        # UX specification template
+    ├── ux-design-template.md      # UX design template
+    ├── checklist.md               # UX design validation checklist
     └── workflow.yaml
 ```
 

src/modules/bmm/workflows/2-plan-workflows/create-ux-design/checklist.md

@@ -0,0 +1,310 @@
+# Create UX Design Workflow Validation Checklist
+
+**Purpose**: Validate UX Design Specification is complete, collaborative, and implementation-ready.
+
+**Paradigm**: Visual collaboration-driven, not template generation
+
+**Expected Outputs**:
+
+- ux-design-specification.md
+- ux-color-themes.html (color theme visualizer)
+- ux-design-directions.html (design mockups)
+- Optional: ux-prototype.html, ux-component-showcase.html, ai-frontend-prompt.md
+
+---
+
+## 1. Output Files Exist
+
+- [ ] **ux-design-specification.md** created in output folder
+- [ ] **ux-color-themes.html** generated (interactive color exploration)
+- [ ] **ux-design-directions.html** generated (6-8 design mockups)
+- [ ] No unfilled {{template_variables}} in specification
+- [ ] All sections have content (not placeholder text)
+
+---
+
+## 2. Collaborative Process Validation
+
+**The workflow should facilitate decisions WITH the user, not FOR them**
+
+- [ ] **Design system chosen by user** (not auto-selected)
+- [ ] **Color theme selected from options** (user saw visualizations and chose)
+- [ ] **Design direction chosen from mockups** (user explored 6-8 options)
+- [ ] **User journey flows designed collaboratively** (options presented, user decided)
+- [ ] **UX patterns decided with user input** (not just generated)
+- [ ] **Decisions documented WITH rationale** (why each choice was made)
+
+---
+
+## 3. Visual Collaboration Artifacts
+
+### Color Theme Visualizer
+
+- [ ] **HTML file exists and is valid** (ux-color-themes.html)
+- [ ] **Shows 3-4 theme options** (or documented existing brand)
+- [ ] **Each theme has complete palette** (primary, secondary, semantic colors)
+- [ ] **Live UI component examples** in each theme (buttons, forms, cards)
+- [ ] **Side-by-side comparison** enabled
+- [ ] **User's selection documented** in specification
+
+### Design Direction Mockups
+
+- [ ] **HTML file exists and is valid** (ux-design-directions.html)
+- [ ] **6-8 different design approaches** shown
+- [ ] **Full-screen mockups** of key screens
+- [ ] **Design philosophy labeled** for each direction (e.g., "Dense Dashboard", "Spacious Explorer")
+- [ ] **Interactive navigation** between directions
+- [ ] **Responsive preview** toggle available
+- [ ] **User's choice documented WITH reasoning** (what they liked, why it fits)
+
+---
+
+## 4. Design System Foundation
+
+- [ ] **Design system chosen** (or custom design decision documented)
+- [ ] **Current version identified** (if using established system)
+- [ ] **Components provided by system documented**
+- [ ] **Custom components needed identified**
+- [ ] **Decision rationale clear** (why this system for this project)
+
+---
+
+## 5. Core Experience Definition
+
+- [ ] **Defining experience articulated** (the ONE thing that makes this app unique)
+- [ ] **Novel UX patterns identified** (if applicable)
+- [ ] **Novel patterns fully designed** (interaction model, states, feedback)
+- [ ] **Core experience principles defined** (speed, guidance, flexibility, feedback)
+
+---
+
+## 6. Visual Foundation
+
+### Color System
+
+- [ ] **Complete color palette** (primary, secondary, accent, semantic, neutrals)
+- [ ] **Semantic color usage defined** (success, warning, error, info)
+- [ ] **Color accessibility considered** (contrast ratios for text)
+- [ ] **Brand alignment** (follows existing brand or establishes new identity)
+
+### Typography
+
+- [ ] **Font families selected** (heading, body, monospace if needed)
+- [ ] **Type scale defined** (h1-h6, body, small, etc.)
+- [ ] **Font weights documented** (when to use each)
+- [ ] **Line heights specified** for readability
+
+### Spacing & Layout
+
+- [ ] **Spacing system defined** (base unit, scale)
+- [ ] **Layout grid approach** (columns, gutters)
+- [ ] **Container widths** for different breakpoints
+
+---
+
+## 7. Design Direction
+
+- [ ] **Specific direction chosen** from mockups (not generic)
+- [ ] **Layout pattern documented** (navigation, content structure)
+- [ ] **Visual hierarchy defined** (density, emphasis, focus)
+- [ ] **Interaction patterns specified** (modal vs inline, disclosure approach)
+- [ ] **Visual style documented** (minimal, balanced, rich, maximalist)
+- [ ] **User's reasoning captured** (why this direction fits their vision)
+
+---
+
+## 8. User Journey Flows
+
+- [ ] **All critical journeys from PRD designed** (no missing flows)
+- [ ] **Each flow has clear goal** (what user accomplishes)
+- [ ] **Flow approach chosen collaboratively** (user picked from options)
+- [ ] **Step-by-step documentation** (screens, actions, feedback)
+- [ ] **Decision points and branching** defined
+- [ ] **Error states and recovery** addressed
+- [ ] **Success states specified** (completion feedback)
+- [ ] **Mermaid diagrams or clear flow descriptions** included
+
+---
+
+## 9. Component Library Strategy
+
+- [ ] **All required components identified** (from design system + custom)
+- [ ] **Custom components fully specified**:
+  - Purpose and user-facing value
+  - Content/data displayed
+  - User actions available
+  - All states (default, hover, active, loading, error, disabled)
+  - Variants (sizes, styles, layouts)
+  - Behavior on interaction
+  - Accessibility considerations
+- [ ] **Design system components customization needs** documented
+
+---
+
+## 10. UX Pattern Consistency Rules
+
+**These patterns ensure consistent UX across the entire app**
+
+- [ ] **Button hierarchy defined** (primary, secondary, tertiary, destructive)
+- [ ] **Feedback patterns established** (success, error, warning, info, loading)
+- [ ] **Form patterns specified** (labels, validation, errors, help text)
+- [ ] **Modal patterns defined** (sizes, dismiss behavior, focus, stacking)
+- [ ] **Navigation patterns documented** (active state, breadcrumbs, back button)
+- [ ] **Empty state patterns** (first use, no results, cleared content)
+- [ ] **Confirmation patterns** (when to confirm destructive actions)
+- [ ] **Notification patterns** (placement, duration, stacking, priority)
+- [ ] **Search patterns** (trigger, results, filters, no results)
+- [ ] **Date/time patterns** (format, timezone, pickers)
+
+**Each pattern should have:**
+
+- [ ] Clear specification (how it works)
+- [ ] Usage guidance (when to use)
+- [ ] Examples (concrete implementations)
+
+---
+
+## 11. Responsive Design
+
+- [ ] **Breakpoints defined** for target devices (mobile, tablet, desktop)
+- [ ] **Adaptation patterns documented** (how layouts change)
+- [ ] **Navigation adaptation** (how nav changes on small screens)
+- [ ] **Content organization changes** (multi-column to single, grid to list)
+- [ ] **Touch targets adequate** on mobile (minimum size specified)
+- [ ] **Responsive strategy aligned** with chosen design direction
+
+---
+
+## 12. Accessibility
+
+- [ ] **WCAG compliance level specified** (A, AA, or AAA)
+- [ ] **Color contrast requirements** documented (ratios for text)
+- [ ] **Keyboard navigation** addressed (all interactive elements accessible)
+- [ ] **Focus indicators** specified (visible focus states)
+- [ ] **ARIA requirements** noted (roles, labels, announcements)
+- [ ] **Screen reader considerations** (meaningful labels, structure)
+- [ ] **Alt text strategy** for images
+- [ ] **Form accessibility** (label associations, error identification)
+- [ ] **Testing strategy** defined (automated tools, manual testing)
+
+---
+
+## 13. Coherence and Integration
+
+- [ ] **Design system and custom components visually consistent**
+- [ ] **All screens follow chosen design direction**
+- [ ] **Color usage consistent with semantic meanings**
+- [ ] **Typography hierarchy clear and consistent**
+- [ ] **Similar actions handled the same way** (pattern consistency)
+- [ ] **All PRD user journeys have UX design**
+- [ ] **All entry points designed**
+- [ ] **Error and edge cases handled**
+- [ ] **Every interactive element meets accessibility requirements**
+- [ ] **All flows keyboard-navigable**
+- [ ] **Colors meet contrast requirements**
+
+---
+
+## 14. Cross-Workflow Alignment (Epics File Update)
+
+**As UX design progresses, you discover implementation details that affect the story breakdown**
+
+### Stories Discovered During UX Design
+
+- [ ] **Review epics.md file** for alignment with UX design
+- [ ] **New stories identified** during UX design that weren't in epics.md:
+  - [ ] Custom component build stories (if significant)
+  - [ ] UX pattern implementation stories
+  - [ ] Animation/transition stories
+  - [ ] Responsive adaptation stories
+  - [ ] Accessibility implementation stories
+  - [ ] Edge case handling stories discovered during journey design
+  - [ ] Onboarding/empty state stories
+  - [ ] Error state handling stories
+
+### Story Complexity Adjustments
+
+- [ ] **Existing stories complexity reassessed** based on UX design:
+  - [ ] Stories that are now more complex (UX revealed additional requirements)
+  - [ ] Stories that are simpler (design system handles more than expected)
+  - [ ] Stories that should be split (UX design shows multiple components/flows)
+  - [ ] Stories that can be combined (UX design shows they're tightly coupled)
+
+### Epic Alignment
+
+- [ ] **Epic scope still accurate** after UX design
+- [ ] **New epic needed** for discovered work (if significant)
+- [ ] **Epic ordering might change** based on UX dependencies
+
+### Action Items for Epics File Update
+
+- [ ] **List of new stories to add** to epics.md documented
+- [ ] **Complexity adjustments noted** for existing stories
+- [ ] **Update epics.md** OR flag for architecture review first
+- [ ] **Rationale documented** for why new stories/changes are needed
+
+**Note:** If significant story changes are identified, consider running architecture workflow BEFORE updating epics.md, since architecture decisions might reveal additional adjustments needed.
+
+---
+
+## 15. Decision Rationale
+
+**Unlike template-driven workflows, this workflow should document WHY**
+
+- [ ] **Design system choice has rationale** (why this fits the project)
+- [ ] **Color theme selection has reasoning** (why this emotional impact)
+- [ ] **Design direction choice explained** (what user liked, how it fits vision)
+- [ ] **User journey approaches justified** (why this flow pattern)
+- [ ] **UX pattern decisions have context** (why these patterns for this app)
+- [ ] **Responsive strategy aligned with user priorities**
+- [ ] **Accessibility level appropriate for deployment intent**
+
+---
+
+## 16. Implementation Readiness
+
+- [ ] **Designers can create high-fidelity mockups** from this spec
+- [ ] **Developers can implement** with clear UX guidance
+- [ ] **Sufficient detail** for frontend development
+- [ ] **Component specifications actionable** (states, variants, behaviors)
+- [ ] **Flows implementable** (clear steps, decision logic, error handling)
+- [ ] **Visual foundation complete** (colors, typography, spacing all defined)
+- [ ] **Pattern consistency enforceable** (clear rules for implementation)
+
+---
+
+## 17. Critical Failures (Auto-Fail)
+
+- [ ] ❌ **No visual collaboration** (color themes or design mockups not generated)
+- [ ] ❌ **User not involved in decisions** (auto-generated without collaboration)
+- [ ] ❌ **No design direction chosen** (missing key visual decisions)
+- [ ] ❌ **No user journey designs** (critical flows not documented)
+- [ ] ❌ **No UX pattern consistency rules** (implementation will be inconsistent)
+- [ ] ❌ **Missing core experience definition** (no clarity on what makes app unique)
+- [ ] ❌ **No component specifications** (components not actionable)
+- [ ] ❌ **Responsive strategy missing** (for multi-platform projects)
+- [ ] ❌ **Accessibility ignored** (no compliance target or requirements)
+- [ ] ❌ **Generic/templated content** (not specific to this project)
+
+---
+
+## Validation Notes
+
+**Document findings:**
+
+- UX Design Quality: [Exceptional / Strong / Adequate / Needs Work / Incomplete]
+- Collaboration Level: [Highly Collaborative / Collaborative / Somewhat Collaborative / Generated]
+- Visual Artifacts: [Complete & Interactive / Partial / Missing]
+- Implementation Readiness: [Ready / Needs Design Phase / Not Ready]
+
+## **Strengths:**
+
+## **Areas for Improvement:**
+
+## **Recommended Actions:**
+
+**Ready for next phase?** [Yes - Proceed to Design / Yes - Proceed to Development / Needs Refinement]
+
+---
+
+_This checklist validates collaborative UX design facilitation, not template generation. A successful UX workflow creates design decisions WITH the user through visual exploration and informed choices._

src/modules/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md

@@ -0,0 +1,145 @@
+# {{project_name}} UX Design Specification
+
+_Created on {{date}} by {{user_name}}_
+_Generated using BMad Method - Create UX Design Workflow v1.0_
+
+---
+
+## Executive Summary
+
+{{project_vision}}
+
+---
+
+## 1. Design System Foundation
+
+### 1.1 Design System Choice
+
+{{design_system_decision}}
+
+---
+
+## 2. Core User Experience
+
+### 2.1 Defining Experience
+
+{{core_experience}}
+
+### 2.2 Novel UX Patterns
+
+{{novel_ux_patterns}}
+
+---
+
+## 3. Visual Foundation
+
+### 3.1 Color System
+
+{{visual_foundation}}
+
+**Interactive Visualizations:**
+
+- Color Theme Explorer: [ux-color-themes.html](./ux-color-themes.html)
+
+---
+
+## 4. Design Direction
+
+### 4.1 Chosen Design Approach
+
+{{design_direction_decision}}
+
+**Interactive Mockups:**
+
+- Design Direction Showcase: [ux-design-directions.html](./ux-design-directions.html)
+
+---
+
+## 5. User Journey Flows
+
+### 5.1 Critical User Paths
+
+{{user_journey_flows}}
+
+---
+
+## 6. Component Library
+
+### 6.1 Component Strategy
+
+{{component_library_strategy}}
+
+---
+
+## 7. UX Pattern Decisions
+
+### 7.1 Consistency Rules
+
+{{ux_pattern_decisions}}
+
+---
+
+## 8. Responsive Design & Accessibility
+
+### 8.1 Responsive Strategy
+
+{{responsive_accessibility_strategy}}
+
+---
+
+## 9. Implementation Guidance
+
+### 9.1 Completion Summary
+
+{{completion_summary}}
+
+---
+
+## Appendix
+
+### Related Documents
+
+- Product Requirements: `{{prd_file}}`
+- Product Brief: `{{brief_file}}`
+- Brainstorming: `{{brainstorm_file}}`
+
+### Core Interactive Deliverables
+
+This UX Design Specification was created through visual collaboration:
+
+- **Color Theme Visualizer**: {{color_themes_html}}
+  - Interactive HTML showing all color theme options explored
+  - Live UI component examples in each theme
+  - Side-by-side comparison and semantic color usage
+
+- **Design Direction Mockups**: {{design_directions_html}}
+  - Interactive HTML with 6-8 complete design approaches
+  - Full-screen mockups of key screens
+  - Design philosophy and rationale for each direction
+
+### Optional Enhancement Deliverables
+
+_This section will be populated if additional UX artifacts are generated through follow-up workflows._
+
+<!-- Additional deliverables added here by other workflows -->
+
+### Next Steps & Follow-Up Workflows
+
+This UX Design Specification can serve as input to:
+
+- **Wireframe Generation Workflow** - Create detailed wireframes from user flows
+- **Figma Design Workflow** - Generate Figma files via MCP integration
+- **Interactive Prototype Workflow** - Build clickable HTML prototypes
+- **Component Showcase Workflow** - Create interactive component library
+- **AI Frontend Prompt Workflow** - Generate prompts for v0, Lovable, Bolt, etc.
+- **Solution Architecture Workflow** - Define technical architecture with UX context
+
+### Version History
+
+| Date     | Version | Changes                         | Author        |
+| -------- | ------- | ------------------------------- | ------------- |
+| {{date}} | 1.0     | Initial UX Design Specification | {{user_name}} |
+
+---
+
+_This UX Design Specification was created through collaborative design facilitation, not template generation. All decisions were made with user input and are documented with rationale._

src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml

@@ -0,0 +1,55 @@
+# Create UX Design Workflow Configuration
+name: create-ux-design
+description: "Collaborative UX design facilitation workflow that creates exceptional user experiences through visual exploration and informed decision-making. Unlike template-driven approaches, this workflow facilitates discovery, generates visual options, and collaboratively designs the UX with the user at every step."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Input requirements - We work from PRD, Brief, or Brainstorming docs
+recommended_inputs:
+  - prd: "Product Requirements Document with features and user journeys"
+  - product_brief: "Product brief with vision and target users"
+  - brainstorming: "Brainstorming documents with ideas and concepts"
+
+# Input file references (fuzzy matched from output folder)
+prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
+brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
+brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.md"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+template: "{installed_path}/ux-design-template.md"
+
+# Knowledge bases for intelligent UX decisions
+ux_pattern_catalog: "{installed_path}/ux-pattern-catalog.yaml"
+color_psychology: "{installed_path}/color-psychology.yaml"
+layout_patterns: "{installed_path}/layout-patterns.yaml"
+
+# Output configuration - Progressive saves throughout workflow
+default_output_file: "{output_folder}/ux-design-specification.md"
+color_themes_html: "{output_folder}/ux-color-themes.html"
+design_directions_html: "{output_folder}/ux-design-directions.html"
+
+# Workflow metadata
+version: "1.0.0"
+paradigm: "visual-collaboration-driven"
+execution_time: "45-120 minutes depending on project complexity and user engagement"
+features:
+  - "Design system discovery and selection"
+  - "Live HTML color theme visualization"
+  - "6-8 design direction mockup generation"
+  - "Adaptive facilitation by skill level"
+  - "Novel UX pattern design for unique concepts"
+  - "Progressive document building (saves after each step)"
+  - "Visual decision-making with actual mockups"
+  - "WebSearch for current design systems and trends"
+  - "Serves as input to follow-up workflows (wireframes, Figma, prototypes, architecture)"

src/modules/bmm/workflows/2-plan-workflows/ux/checklist.md

@@ -1,152 +0,0 @@
-# UX/UI Specification Workflow Validation Checklist
-
-**Purpose**: Validate UX workflow outputs are complete, actionable, and ready for development.
-
-**Scope**: Can run standalone or integrated with PRD/GDD workflows
-
-**Expected Outputs**: ux-specification.md, optional ai-frontend-prompt.md
-
----
-
-## 1. Output File Exists
-
-- [ ] ux-specification.md created in output folder
-- [ ] Requirements source identified (PRD, GDD, or gathered requirements)
-- [ ] No unfilled {{template_variables}}
-
----
-
-## 2. UX Foundation
-
-### User Personas
-
-- [ ] **At least one primary persona** defined with goals and pain points
-- [ ] Personas have sufficient detail to inform design decisions
-- [ ] If PRD/GDD exists, personas align with target audience
-
-### Design Principles
-
-- [ ] **3-5 core design principles** established
-- [ ] Principles are actionable (guide real design decisions)
-- [ ] Principles fit project goals and users
-
----
-
-## 3. Information Architecture
-
-### Site/App Structure
-
-- [ ] **Complete site map** showing all major sections/screens
-- [ ] Hierarchical relationships clear
-- [ ] Navigation paths evident
-- [ ] Structure makes sense for users
-
-### Navigation
-
-- [ ] Primary navigation defined
-- [ ] Mobile navigation strategy clear (if multi-platform)
-- [ ] Navigation approach logical
-
----
-
-## 4. User Flows
-
-- [ ] **At least 2-3 critical user flows** documented
-- [ ] Flows show complete start-to-finish paths
-- [ ] Decision points and error states considered
-- [ ] Flows include Mermaid diagrams or clear descriptions
-- [ ] If PRD exists, flows align with user journeys
-
----
-
-## 5. Component Library and Visual Design
-
-### Component Approach
-
-- [ ] **Design system strategy** defined (existing system, custom, or hybrid)
-- [ ] If using existing, which one specified
-- [ ] Core components identified
-- [ ] Component states documented (default, hover, active, disabled, error)
-
-### Visual Foundation
-
-- [ ] **Color palette** defined with semantic meanings
-- [ ] **Typography** specified (fonts, type scale, usage)
-- [ ] **Spacing system** documented
-- [ ] Design choices support usability
-
----
-
-## 6. Responsive and Accessibility
-
-### Responsive Design
-
-- [ ] **Breakpoints defined** for target devices
-- [ ] Adaptation patterns explained (how layouts change)
-- [ ] Mobile strategy clear (if multi-platform)
-
-### Accessibility
-
-- [ ] **Compliance target** specified (WCAG level)
-- [ ] Key accessibility requirements documented
-- [ ] Keyboard navigation, screen readers, contrast considered
-
----
-
-## 7. Implementation Readiness
-
-- [ ] **Next steps** clearly defined
-- [ ] Design handoff requirements clear
-- [ ] Developers can implement from this spec
-- [ ] Sufficient detail for front-end development
-
----
-
-## 8. Integration with Requirements
-
-**If PRD/GDD exists:**
-
-- [ ] UX covers all user-facing features from requirements
-- [ ] User flows align with documented user journeys
-- [ ] Platform matches PRD/GDD platforms
-- [ ] No contradictions with requirements
-
----
-
-## 9. AI Frontend Prompt (If Generated)
-
-**If ai-frontend-prompt.md was created:**
-
-- [ ] File exists in output folder
-- [ ] Contains complete UX context (colors, typography, components, flows)
-- [ ] Formatted for AI tools (v0, Lovable, etc.)
-- [ ] Includes appropriate warnings about reviewing generated code
-
----
-
-## 10. Critical Failures (Auto-Fail)
-
-- [ ] ❌ **No user personas** (target users not defined)
-- [ ] ❌ **No user flows** (critical paths not documented)
-- [ ] ❌ **No information architecture** (site structure missing)
-- [ ] ❌ **No component approach** (design system not defined)
-- [ ] ❌ **No visual foundation** (colors/typography missing)
-- [ ] ❌ **No responsive strategy** (adaptation not addressed for multi-platform)
-- [ ] ❌ **Contradicts requirements** (UX fights PRD/GDD if they exist)
-
----
-
-## Validation Notes
-
-**Document any findings:**
-
-- UX quality: [Production-ready / Good foundation / Needs refinement / Incomplete]
-- Strengths:
-- Issues to address:
-- Recommended actions:
-
-**Ready for development?** [Yes / Needs design phase / No - explain]
-
----
-
-_Adapt based on whether this is standalone or integrated, and platform requirements._

src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md

@@ -1,405 +0,0 @@
-# UX/UI Specification Workflow Instructions
-
-<workflow>
-
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
-<critical>Generate all documents in {document_output_language}</critical>
-<critical>This workflow creates comprehensive UX/UI specifications - can run standalone or as part of plan-project</critical>
-<critical>Uses ux-spec-template.md for structured output generation</critical>
-<critical>Can optionally generate AI Frontend Prompts for tools like Vercel v0, Lovable.ai</critical>
-
-<critical>DOCUMENT OUTPUT: Professional, precise, actionable UX specs. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
-
-<step n="0" goal="Check for workflow status">
-
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: init-check</param>
-</invoke-workflow>
-
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Set tracking_mode = true</action>
-</check>
-
-<check if="status_exists == false">
-  <action>Set tracking_mode = false</action>
-  <output>Note: Running without workflow tracking. Run `workflow-init` to enable progress tracking.</output>
-</check>
-</step>
-
-<step n="1" goal="Load context and analyze project requirements">
-
-<action>Determine workflow mode (standalone or integrated)</action>
-
-<check if="mode is standalone">
-  <ask>Do you have an existing PRD or requirements document? (y/n)
-
-If yes: Provide the path to the PRD
-If no: We'll gather basic requirements to create the UX spec
-</ask>
-</check>
-
-<check if="no PRD in standalone mode">
-  <ask>Let's gather essential information:
-
-1. **Project Description**: What are you building?
-2. **Target Users**: Who will use this?
-3. **Core Features**: What are the main capabilities? (3-5 key features)
-4. **Platform**: Web, mobile, desktop, or multi-platform?
-5. **Existing Brand/Design**: Any existing style guide or brand to follow?
-   </ask>
-   </check>
-
-<check if="PRD exists or integrated mode">
-  <action>Load the following documents if available:</action>
-
-- PRD.md (primary source for requirements and user journeys)
-- epics.md (helps understand feature grouping)
-- tech-spec.md (understand technical constraints)
-- architecture.md (if Level 3-4 project)
-- bmm-workflow-status.md (understand project level and scope)
-
-</check>
-
-<action>Analyze project for UX complexity:</action>
-
-- Number of user-facing features
-- Types of users/personas mentioned
-- Interaction complexity
-- Platform requirements (web, mobile, desktop)
-
-<action>Load ux-spec-template from workflow.yaml</action>
-
-<template-output>project_context</template-output>
-
-</step>
-
-<step n="2" goal="Define UX goals and principles">
-
-<ask>Let's establish the UX foundation. Based on the PRD:
-
-**1. Target User Personas** (extract from PRD or define):
-
-- Primary persona(s)
-- Secondary persona(s)
-- Their goals and pain points
-
-**2. Key Usability Goals:**
-What does success look like for users?
-
-- Ease of learning?
-- Efficiency for power users?
-- Error prevention?
-- Accessibility requirements?
-
-**3. Core Design Principles** (3-5 principles):
-What will guide all design decisions?
-</ask>
-
-<template-output>user_personas</template-output>
-<template-output>usability_goals</template-output>
-<template-output>design_principles</template-output>
-
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-
-</step>
-
-<step n="3" goal="Create information architecture">
-
-<action>Based on functional requirements from PRD, create site/app structure</action>
-
-**Create comprehensive site map showing:**
-
-- All major sections/screens
-- Hierarchical relationships
-- Navigation paths
-
-<template-output>site_map</template-output>
-
-**Define navigation structure:**
-
-- Primary navigation items
-- Secondary navigation approach
-- Mobile navigation strategy
-- Breadcrumb structure
-
-<template-output>navigation_structure</template-output>
-
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-
-</step>
-
-<step n="4" goal="Design user flows for critical paths">
-
-<action>Extract key user journeys from PRD</action>
-<action>For each critical user task, create detailed flow</action>
-
-<for-each journey="user_journeys_from_prd">
-
-**Flow: {{journey_name}}**
-
-Define:
-
-- User goal
-- Entry points
-- Step-by-step flow with decision points
-- Success criteria
-- Error states and edge cases
-
-Create Mermaid diagram showing complete flow.
-
-<template-output>user*flow*{{journey_number}}</template-output>
-
-</for-each>
-
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-
-</step>
-
-<step n="5" goal="Define component library approach">
-
-<ask>Component Library Strategy:
-
-**1. Design System Approach:**
-
-- [ ] Use existing system (Material UI, Ant Design, etc.)
-- [ ] Create custom component library
-- [ ] Hybrid approach
-
-**2. If using existing, which one?**
-
-**3. Core Components Needed** (based on PRD features):
-We'll need to define states and variants for key components.
-</ask>
-
-<action>For primary components, define:</action>
-
-- Component purpose
-- Variants needed
-- States (default, hover, active, disabled, error)
-- Usage guidelines
-
-<template-output>design_system_approach</template-output>
-<template-output>core_components</template-output>
-
-</step>
-
-<step n="6" goal="Establish visual design foundation">
-
-<ask>Visual Design Foundation:
-
-**1. Brand Guidelines:**
-Do you have existing brand guidelines to follow? (y/n)
-
-**2. If yes, provide link or key elements.**
-
-**3. If no, let's define basics:**
-
-- Primary brand personality (professional, playful, minimal, bold)
-- Industry conventions to follow or break
-  </ask>
-
-<action>Define color palette with semantic meanings</action>
-
-<template-output>color_palette</template-output>
-
-<action>Define typography system</action>
-
-<template-output>font_families</template-output>
-<template-output>type_scale</template-output>
-
-<action>Define spacing and layout grid</action>
-
-<template-output>spacing_layout</template-output>
-
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-
-</step>
-
-<step n="7" goal="Define responsive and accessibility strategy">
-
-**Responsive Design:**
-
-<action>Define breakpoints based on target devices from PRD</action>
-
-<template-output>breakpoints</template-output>
-
-<action>Define adaptation patterns for different screen sizes</action>
-
-<template-output>adaptation_patterns</template-output>
-
-**Accessibility Requirements:**
-
-<action>Based on deployment intent from PRD, define compliance level</action>
-
-<template-output>compliance_target</template-output>
-<template-output>accessibility_requirements</template-output>
-
-</step>
-
-<step n="8" goal="Document interaction patterns" optional="true">
-
-<ask>Would you like to define animation and micro-interactions? (y/n)
-
-This is recommended for:
-
-- Consumer-facing applications
-- Projects emphasizing user delight
-- Complex state transitions
-  </ask>
-
-<check if="yes or fuzzy match the user wants to define animation or micro interactions">
-
-<action>Define motion principles</action>
-<template-output>motion_principles</template-output>
-
-<action>Define key animations and transitions</action>
-<template-output>key_animations</template-output>
-</check>
-
-</step>
-
-<step n="9" goal="Create wireframes and design references" optional="true">
-
-<ask>Design File Strategy:
-
-**1. Will you be creating high-fidelity designs?**
-
-- Yes, in Figma
-- Yes, in Sketch
-- Yes, in Adobe XD
-- No, development from spec
-- Other (describe)
-
-**2. For key screens, should we:**
-
-- Reference design file locations
-- Create low-fi wireframe descriptions
-- Skip visual representations
-  </ask>
-
-<template-output if="design files will be created">design_files</template-output>
-
-<check if="wireframe descriptions needed">
-  <for-each screen="key_screens">
-    <template-output>screen*layout*{{screen_number}}</template-output>
-  </for-each>
-</check>
-
-</step>
-
-<step n="10" goal="Generate next steps and output options">
-
-## UX Specification Complete
-
-<action>Generate specific next steps based on project level and outputs</action>
-
-<template-output>immediate_actions</template-output>
-
-**Design Handoff Checklist:**
-
-- [ ] All user flows documented
-- [ ] Component inventory complete
-- [ ] Accessibility requirements defined
-- [ ] Responsive strategy clear
-- [ ] Brand guidelines incorporated
-- [ ] Performance goals established
-
-<check if="Level 3-4 project">
-  - [ ] Ready for detailed visual design
-  - [ ] Frontend architecture can proceed
-  - [ ] Story generation can include UX details
-</check>
-
-<check if="Level 1-2 project or standalone">
-  - [ ] Development can proceed with spec
-  - [ ] Component implementation order defined
-  - [ ] MVP scope clear
-
-</check>
-
-<template-output>design_handoff_checklist</template-output>
-
-<ask>**✅ UX Specification Complete, {user_name}!**
-
-UX Specification saved to {{ux_spec_file}}
-
-**Additional Output Options:**
-
-1. Generate AI Frontend Prompt (for Vercel v0, Lovable.ai, etc.)
-2. Review UX specification
-3. Create/update visual designs in design tool
-4. Return to planning workflow (if not standalone)
-5. Exit
-
-Would you like to generate an AI Frontend Prompt? (y/n):</ask>
-
-<check if="user selects yes or option 1">
-  <goto step="11">Generate AI Frontend Prompt</goto>
-</check>
-
-</step>
-
-<step n="11" goal="Generate AI Frontend Prompt" optional="true">
-
-<action>Prepare context for AI Frontend Prompt generation</action>
-
-<ask>What type of AI frontend generation are you targeting?
-
-1. **Full application** - Complete multi-page application
-2. **Single page** - One complete page/screen
-3. **Component set** - Specific components or sections
-4. **Design system** - Component library setup
-
-Select option (1-4):</ask>
-
-<action>Gather UX spec details for prompt generation:</action>
-
-- Design system approach
-- Color palette and typography
-- Key components and their states
-- User flows to implement
-- Responsive requirements
-
-<invoke-task>{project-root}/bmad/bmm/tasks/ai-fe-prompt.md</invoke-task>
-
-<action>Save AI Frontend Prompt to {{ai_frontend_prompt_file}}</action>
-
-<ask>AI Frontend Prompt saved to {{ai_frontend_prompt_file}}
-
-This prompt is optimized for:
-
-- Vercel v0
-- Lovable.ai
-- Other AI frontend generation tools
-
-**Remember**: AI-generated code requires careful review and testing!
-
-Next actions:
-
-1. Copy prompt to AI tool
-2. Return to UX specification
-3. Exit workflow
-
-Select option (1-3):</ask>
-
-</step>
-
-<step n="12" goal="Update status if tracking enabled">
-
-<check if="tracking_mode == true">
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: ux</param>
-  </invoke-workflow>
-
-  <check if="success == true">
-    <output>✅ Status updated! Next: {{next_workflow}}</output>
-  </check>
-</check>
-</step>
-
-</workflow>

src/modules/bmm/workflows/2-plan-workflows/ux/ux-spec-template.md

@@ -1,162 +0,0 @@
-# {{project_name}} UX/UI Specification
-
-_Generated on {{date}} by {{user_name}}_
-
-## Executive Summary
-
-{{project_context}}
-
----
-
-## 1. UX Goals and Principles
-
-### 1.1 Target User Personas
-
-{{user_personas}}
-
-### 1.2 Usability Goals
-
-{{usability_goals}}
-
-### 1.3 Design Principles
-
-{{design_principles}}
-
----
-
-## 2. Information Architecture
-
-### 2.1 Site Map
-
-{{site_map}}
-
-### 2.2 Navigation Structure
-
-{{navigation_structure}}
-
----
-
-## 3. User Flows
-
-{{user_flow_1}}
-
-{{user_flow_2}}
-
-{{user_flow_3}}
-
-{{user_flow_4}}
-
-{{user_flow_5}}
-
----
-
-## 4. Component Library and Design System
-
-### 4.1 Design System Approach
-
-{{design_system_approach}}
-
-### 4.2 Core Components
-
-{{core_components}}
-
----
-
-## 5. Visual Design Foundation
-
-### 5.1 Color Palette
-
-{{color_palette}}
-
-### 5.2 Typography
-
-**Font Families:**
-{{font_families}}
-
-**Type Scale:**
-{{type_scale}}
-
-### 5.3 Spacing and Layout
-
-{{spacing_layout}}
-
----
-
-## 6. Responsive Design
-
-### 6.1 Breakpoints
-
-{{breakpoints}}
-
-### 6.2 Adaptation Patterns
-
-{{adaptation_patterns}}
-
----
-
-## 7. Accessibility
-
-### 7.1 Compliance Target
-
-{{compliance_target}}
-
-### 7.2 Key Requirements
-
-{{accessibility_requirements}}
-
----
-
-## 8. Interaction and Motion
-
-### 8.1 Motion Principles
-
-{{motion_principles}}
-
-### 8.2 Key Animations
-
-{{key_animations}}
-
----
-
-## 9. Design Files and Wireframes
-
-### 9.1 Design Files
-
-{{design_files}}
-
-### 9.2 Key Screen Layouts
-
-{{screen_layout_1}}
-
-{{screen_layout_2}}
-
-{{screen_layout_3}}
-
----
-
-## 10. Next Steps
-
-### 10.1 Immediate Actions
-
-{{immediate_actions}}
-
-### 10.2 Design Handoff Checklist
-
-{{design_handoff_checklist}}
-
----
-
-## Appendix
-
-### Related Documents
-
-- PRD: `{{prd}}`
-- Epics: `{{epics}}`
-- Tech Spec: `{{tech_spec}}`
-- Architecture: `{{architecture}}`
-
-### Version History
-
-| Date     | Version | Changes               | Author        |
-| -------- | ------- | --------------------- | ------------- |
-| {{date}} | 1.0     | Initial specification | {{user_name}} |

src/modules/bmm/workflows/2-plan-workflows/ux/workflow.yaml

@@ -1,37 +0,0 @@
-# UX/UI Specification Workflow
-name: ux-spec
-description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines."
-author: "BMad"
-
-# Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
-user_name: "{config_source}:user_name"
-communication_language: "{config_source}:communication_language"
-document_output_language: "{config_source}:document_output_language"
-user_skill_level: "{config_source}:user_skill_level"
-date: system-generated
-
-# Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/ux"
-instructions: "{installed_path}/instructions-ux.md"
-template: "{installed_path}/ux-spec-template.md"
-
-# Output configuration
-default_output_file: "{output_folder}/ux-specification.md"
-ai_frontend_prompt_file: "{output_folder}/ai-frontend-prompt.md"
-
-# Recommended input documents
-recommended_inputs:
-  - prd: "{output_folder}/PRD.md"
-  - product_brief: "{output_folder}/product-brief.md"
-  - gdd: "{output_folder}/GDD.md"
-
-web_bundle:
-  name: "ux-spec"
-  description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines."
-  author: "BMad"
-  instructions: "bmad/bmm/workflows/2-plan-workflows/ux/instructions-ux.md"
-  web_bundle_files:
-    - "bmad/bmm/workflows/2-plan-workflows/ux/instructions-ux.md"
-    - "bmad/bmm/workflows/2-plan-workflows/ux/ux-spec-template.md"

src/modules/bmm/workflows/3-solutioning/architecture/checklist.md

@@ -1,49 +1,67 @@
-# Decision Architecture Validation Checklist
+# Architecture Document Validation Checklist
 
-## Critical Requirements (MUST PASS)
+**Purpose**: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.
 
-### Decision Completeness
+**Note**: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.
 
-- [ ] Every functional requirement from PRD has architectural support
+---
-- [ ] Every non-functional requirement from PRD is addressed
+
-- [ ] All critical decision categories have been resolved
+## 1. Decision Completeness
+
+### All Decisions Made
+
+- [ ] Every critical decision category has been resolved
+- [ ] All important decision categories addressed
 - [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
+- [ ] Optional decisions either resolved or explicitly deferred with rationale
 
-### Version Specificity
+### Decision Coverage
+
+- [ ] Data persistence approach decided
+- [ ] API pattern chosen
+- [ ] Authentication/authorization strategy defined
+- [ ] Deployment target selected
+- [ ] All functional requirements have architectural support
+
+---
+
+## 2. Version Specificity
+
+### Technology Versions
 
 - [ ] Every technology choice includes a specific version number
 - [ ] Version numbers are current (verified via WebSearch, not hardcoded)
 - [ ] Compatible versions selected (e.g., Node.js version supports chosen packages)
 - [ ] Verification dates noted for version checks
 
-### Starter Template Integration (if applicable)
+### Version Verification Process
 
+- [ ] WebSearch used during workflow to verify current versions
+- [ ] No hardcoded versions from decision catalog trusted without verification
+- [ ] LTS vs. latest versions considered and documented
+- [ ] Breaking changes between versions noted if relevant
+
+---
+
+## 3. Starter Template Integration (if applicable)
+
+### Template Selection
+
+- [ ] Starter template chosen (or "from scratch" decision documented)
 - [ ] Project initialization command documented with exact flags
-- [ ] Starter-provided decisions marked as "PROVIDED BY STARTER"
-- [ ] First implementation story references starter initialization
 - [ ] Starter template version is current and specified
+- [ ] Command search term provided for verification
 
-### Epic Coverage
+### Starter-Provided Decisions
 
-- [ ] Every epic from PRD is explicitly mapped to architectural components
+- [ ] Decisions provided by starter marked as "PROVIDED BY STARTER"
-- [ ] Decision summary table shows which epics each decision affects
+- [ ] List of what starter provides is complete
-- [ ] No orphan epics without architectural support
+- [ ] Remaining decisions (not covered by starter) clearly identified
-- [ ] Novel patterns mapped to affected epics
+- [ ] No duplicate decisions that starter already makes
 
-### Document Structure
+---
 
-- [ ] Executive summary is present and concise (2-3 sentences maximum)
+## 4. Novel Pattern Design (if applicable)
-- [ ] Project initialization section present (if using starter template)
-- [ ] Decision summary table has ALL required columns:
-  - Category
-  - Decision
-  - Version
-  - Affects Epics
-  - Rationale
-- [ ] Project structure section shows complete source tree
-- [ ] Source tree reflects actual technology decisions (not generic)
-
-## Novel Pattern Design (if applicable)
 
 ### Pattern Detection
 
@@ -51,16 +69,25 @@
 - [ ] Patterns that don't have standard solutions documented
 - [ ] Multi-epic workflows requiring custom design captured
 
-### Pattern Documentation
+### Pattern Documentation Quality
 
 - [ ] Pattern name and purpose clearly defined
 - [ ] Component interactions specified
 - [ ] Data flow documented (with sequence diagrams if complex)
 - [ ] Implementation guide provided for agents
-- [ ] Affected epics listed
 - [ ] Edge cases and failure modes considered
+- [ ] States and transitions clearly defined
 
-## Implementation Patterns
+### Pattern Implementability
+
+- [ ] Pattern is implementable by AI agents with provided guidance
+- [ ] No ambiguous decisions that could be interpreted differently
+- [ ] Clear boundaries between components
+- [ ] Explicit integration points with standard patterns
+
+---
+
+## 5. Implementation Patterns
 
 ### Pattern Categories Coverage
 
@@ -78,10 +105,13 @@
 - [ ] Conventions are unambiguous (agents can't interpret differently)
 - [ ] Patterns cover all technologies in the stack
 - [ ] No gaps where agents would have to guess
+- [ ] Implementation patterns don't conflict with each other
 
-## Consistency Validation
+---
 
-### Technology Compatibility
+## 6. Technology Compatibility
+
+### Stack Coherence
 
 - [ ] Database choice compatible with ORM choice
 - [ ] Frontend framework compatible with deployment target
@@ -89,31 +119,65 @@
 - [ ] All API patterns consistent (not mixing REST and GraphQL for same data)
 - [ ] Starter template compatible with additional choices
 
-### Pattern Consistency
+### Integration Compatibility
 
-- [ ] Single source of truth for each data type
+- [ ] Third-party services compatible with chosen stack
-- [ ] Consistent error handling approach across components
+- [ ] Real-time solutions (if any) work with deployment target
-- [ ] Uniform authentication/authorization pattern
+- [ ] File storage solution integrates with framework
-- [ ] Implementation patterns don't conflict with each other
+- [ ] Background job system compatible with infrastructure
 
-### AI Agent Clarity
+---
+
+## 7. Document Structure
+
+### Required Sections Present
+
+- [ ] Executive summary exists (2-3 sentences maximum)
+- [ ] Project initialization section (if using starter template)
+- [ ] Decision summary table with ALL required columns:
+  - Category
+  - Decision
+  - Version
+  - Rationale
+- [ ] Project structure section shows complete source tree
+- [ ] Implementation patterns section comprehensive
+- [ ] Novel patterns section (if applicable)
+
+### Document Quality
+
+- [ ] Source tree reflects actual technology decisions (not generic)
+- [ ] Technical language used consistently
+- [ ] Tables used instead of prose where appropriate
+- [ ] No unnecessary explanations or justifications
+- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
+
+---
+
+## 8. AI Agent Clarity
+
+### Clear Guidance for Agents
 
 - [ ] No ambiguous decisions that agents could interpret differently
 - [ ] Clear boundaries between components/modules
 - [ ] Explicit file organization patterns
 - [ ] Defined patterns for common operations (CRUD, auth checks, etc.)
 - [ ] Novel patterns have clear implementation guidance
+- [ ] Document provides clear constraints for agents
+- [ ] No conflicting guidance present
 
-## Quality Checks
+### Implementation Readiness
 
-### Documentation Quality
+- [ ] Sufficient detail for agents to implement without guessing
+- [ ] File paths and naming conventions explicit
+- [ ] Integration points clearly defined
+- [ ] Error handling patterns specified
+- [ ] Testing patterns documented
 
-- [ ] Technical language used consistently
+---
-- [ ] Tables used instead of prose where appropriate
-- [ ] No unnecessary explanations or justifications
-- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
 
-### Practical Implementation
+## 9. Practical Considerations
+
+### Technology Viability
 
 - [ ] Chosen stack has good documentation and community support
 - [ ] Development environment can be set up with specified versions
@@ -121,118 +185,21 @@
 - [ ] Deployment target supports all chosen technologies
 - [ ] Starter template (if used) is stable and well-maintained
 
-### Scalability Considerations
+### Scalability
 
-- [ ] Architecture can handle expected user load from PRD
+- [ ] Architecture can handle expected user load
 - [ ] Data model supports expected growth
 - [ ] Caching strategy defined if performance is critical
 - [ ] Background job processing defined if async work needed
 - [ ] Novel patterns scalable for production use
 
-## Completeness by Section
+---
 
-### Executive Summary
+## 10. Common Issues to Check
-
-- [ ] States what is being built in one sentence
-- [ ] Identifies primary architectural pattern
-- [ ] Notes any unique or critical decisions
-
-### Project Initialization (if using starter)
-
-- [ ] Exact command with all flags documented
-- [ ] Lists what the starter provides
-- [ ] Notes what decisions remain to be made
-
-### Decision Summary Table
-
-- [ ] Contains all major technology decisions
-- [ ] Each row has complete information
-- [ ] Versions are specific and current
-- [ ] Rationales are brief but clear
-- [ ] Epic mapping is specific (epic IDs, not descriptions)
-- [ ] Starter-provided decisions marked appropriately
-
-### Project Structure
-
-- [ ] Shows actual directory structure
-- [ ] Follows conventions of chosen framework/starter
-- [ ] Maps epics to directories
-- [ ] Includes configuration files
-- [ ] Reflects starter template structure (if applicable)
-
-### Novel Pattern Designs (if present)
-
-- [ ] Each pattern fully documented
-- [ ] Component interactions clear
-- [ ] Implementation guidance specific
-- [ ] Integration with standard patterns defined
-
-### Implementation Patterns
-
-- [ ] All 7 pattern categories addressed
-- [ ] Examples provided for each pattern
-- [ ] No ambiguity in conventions
-- [ ] Covers all potential agent decision points
-
-### Integration Points
-
-- [ ] External service integrations documented
-- [ ] API contracts or patterns defined
-- [ ] Authentication flow specified
-- [ ] Data flow between components clear
-- [ ] Novel patterns integrated properly
-
-### Consistency Rules
-
-- [ ] Naming conventions specified with examples
-- [ ] Code organization patterns defined
-- [ ] Error handling approach documented
-- [ ] Logging strategy defined
-- [ ] All implementation patterns included
-
-## Final Validation
-
-### Ready for Implementation
-
-- [ ] An AI agent could start implementing any epic with this document
-- [ ] First story can initialize project (if using starter)
-- [ ] No critical decisions left undefined
-- [ ] No conflicting guidance present
-- [ ] Document provides clear constraints for agents
-- [ ] Novel patterns implementable by agents
-
-### PRD Alignment
-
-- [ ] All must-have features architecturally supported
-- [ ] Performance requirements achievable with chosen stack
-- [ ] Security requirements addressed
-- [ ] Compliance requirements (if any) met by architecture
-- [ ] Novel concepts from PRD have architectural solutions
-
-### UX Specification Alignment (if applicable)
-
-- [ ] UI component library supports required interaction patterns
-- [ ] Animation/transition requirements achievable with chosen stack
-- [ ] Accessibility standards (WCAG level) met by component choices
-- [ ] Responsive design approach supports all specified breakpoints
-- [ ] Real-time update requirements addressed in architecture
-- [ ] Offline capability architecture defined (if required)
-- [ ] Performance targets from UX spec achievable
-- [ ] Platform-specific UI requirements supported
-
-### Risk Mitigation
-
-- [ ] Single points of failure identified and addressed
-- [ ] Backup and recovery approach defined (if critical)
-- [ ] Monitoring and observability approach included
-- [ ] Rollback strategy considered for deployments
-- [ ] Novel patterns don't introduce unmanageable risks
-
-## Common Issues to Check
 
 ### Beginner Protection
 
-- [ ] Not overengineered for the actual requirements
+- [ ] Not overengineered for actual requirements
 - [ ] Standard patterns used where possible (starter templates leveraged)
 - [ ] Complex technologies justified by specific needs
 - [ ] Maintenance complexity appropriate for team size
@@ -245,17 +212,33 @@
 - [ ] Future migration paths not blocked
 - [ ] Novel patterns follow architectural principles
 
-### Document Usability
+---
 
-- [ ] Can be consumed by AI agents without human interpretation
+## Validation Summary
-- [ ] Provides sufficient detail for consistent implementation
-- [ ] Free from internal contradictions
-- [ ] Complete enough to prevent agent "creativity" in critical areas
-- [ ] Implementation patterns leave no room for conflicting interpretations
 
-## Version Verification
+### Document Quality Score
 
-- [ ] All versions verified to be current (not relying on potentially outdated catalogs)
+- Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
-- [ ] WebSearch used to verify versions during workflow execution
+- Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
-- [ ] No hardcoded versions from knowledge bases trusted without verification
+- Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
-- [ ] Starter template version checked for latest
+- AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]
+
+### Critical Issues Found
+
+- [ ] Issue 1: **\*\***\_\_\_**\*\***
+- [ ] Issue 2: **\*\***\_\_\_**\*\***
+- [ ] Issue 3: **\*\***\_\_\_**\*\***
+
+### Recommended Actions Before Implementation
+
+1. ***
+2. ***
+3. ***
+
+---
+
+**Next Step**: Run the **solutioning-gate-check** workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
+
+---
+
+_This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation._

src/modules/bmm/workflows/3-solutioning/architecture/decision-catalog.yaml

@@ -1,19 +1,8 @@
-# Decision Catalog - Knowledge base for architectural decisions
+# Decision Catalog - Composability knowledge for architectural decisions
-# This replaces rigid project-type templates with intelligent, composable decisions
+# This provides RELATIONSHIPS and WORKFLOW LOGIC, not generic tech knowledge
-
-# ⚠️ CRITICAL WARNING ABOUT VERSIONS ⚠️
-# =====================================
-# Version numbers in this file are EXAMPLES ONLY and will become outdated!
-# The workflow MUST use WebSearch to verify current versions during execution.
 #
-# During facilitation, the AI should:
+# ⚠️ CRITICAL: All version/feature info MUST be verified via WebSearch during workflow
-# 1. Use this file for patterns and relationships
+# This file only provides: triggers, relationships (pairs_with), and opinionated stacks
-# 2. Search for "{{technology}} latest stable version 2024" (or current year)
-# 3. Present the current version found, not the version in this file
-# 4. Document the verified current version in the architecture
-#
-# Versions listed here are for understanding compatibility relationships only.
-# NEVER trust these version numbers - ALWAYS verify current versions!
 
 decision_categories:
   data_persistence:
@@ -22,57 +11,15 @@ decision_categories:
     affects: "most epics"
     options:
       postgresql:
-        name: "PostgreSQL"
+        pairs_with: ["Prisma ORM", "TypeORM", "Drizzle", "node-postgres"]
-        current_version: "15.4"
-        lts_version: "14.9"
-        good_for: ["relational data", "complex queries", "ACID compliance", "JSON support"]
-        not_ideal_for: ["massive scale writes", "unstructured data"]
-        pairs_with:
-          - "Prisma ORM 5.6"
-          - "TypeORM 0.3"
-          - "Drizzle 0.29"
-          - "node-postgres 8.11"
-        beginner_friendly: true
-
       mongodb:
-        name: "MongoDB"
+        pairs_with: ["Mongoose", "Prisma", "MongoDB driver"]
-        current_version: "7.0"
-        lts_version: "6.0"
-        good_for: ["document storage", "flexible schema", "horizontal scaling", "real-time"]
-        not_ideal_for: ["complex relationships", "transactions", "strong consistency"]
-        pairs_with:
-          - "Mongoose 8.0"
-          - "Prisma 5.6"
-          - "MongoDB driver 6.3"
-        beginner_friendly: true
-
       redis:
-        name: "Redis"
+        pairs_with: ["ioredis", "node-redis"]
-        current_version: "7.2"
-        good_for: ["caching", "sessions", "pub/sub", "real-time", "leaderboards"]
-        not_ideal_for: ["primary data store", "complex queries"]
-        pairs_with:
-          - "ioredis 5.3"
-          - "node-redis 4.6"
-        beginner_friendly: false
-
       supabase:
-        name: "Supabase"
+        pairs_with: ["@supabase/supabase-js"]
-        current_version: "2.39"
-        good_for: ["PostgreSQL with batteries", "real-time", "auth included", "rapid development"]
-        not_ideal_for: ["custom infrastructure", "specific compliance needs"]
-        pairs_with:
-          - "@supabase/supabase-js 2.39"
-        beginner_friendly: true
-
       firebase:
-        name: "Firebase Firestore"
+        pairs_with: ["firebase-admin"]
-        current_version: "10.7"
-        good_for: ["real-time sync", "offline-first", "serverless", "rapid prototyping"]
-        not_ideal_for: ["complex queries", "data migrations", "cost at scale"]
-        pairs_with:
-          - "firebase-admin 12.0"
-        beginner_friendly: true
 
   api_pattern:
     triggers: ["API", "client communication", "frontend backend", "service communication"]
@@ -80,48 +27,13 @@ decision_categories:
     affects: "all client-facing epics"
     options:
       rest:
-        name: "REST API"
+        pairs_with: ["Express", "Fastify", "NestJS", "Hono"]
-        specification: "OpenAPI 3.0"
-        good_for: ["standard CRUD", "caching", "simple patterns", "wide support"]
-        not_ideal_for: ["complex queries", "real-time updates", "over/under fetching"]
-        pairs_with:
-          - "Express 4.18"
-          - "Fastify 4.25"
-          - "NestJS 10.3"
-          - "Hono 3.12"
-        beginner_friendly: true
-
       graphql:
-        name: "GraphQL"
+        pairs_with: ["Apollo Server", "GraphQL Yoga", "Mercurius"]
-        specification: "GraphQL"
-        current_version: "16.8"
-        good_for: ["flexible queries", "type safety", "avoiding over-fetching", "aggregation"]
-        not_ideal_for: ["simple CRUD", "file uploads", "caching complexity"]
-        pairs_with:
-          - "Apollo Server 4.10"
-          - "GraphQL Yoga 5.1"
-          - "Mercurius 14.0"
-        beginner_friendly: false
-
       trpc:
-        name: "tRPC"
+        pairs_with: ["Next.js", "React Query"]
-        current_version: "10.45"
-        good_for: ["type safety", "TypeScript projects", "full-stack type sharing"]
-        not_ideal_for: ["non-TypeScript clients", "public APIs"]
-        pairs_with:
-          - "Next.js 14"
-          - "React Query 5.17"
-        beginner_friendly: false
-
       grpc:
-        name: "gRPC"
+        pairs_with: ["@grpc/grpc-js", "protobufjs"]
-        current_version: "1.60"
-        good_for: ["microservices", "binary protocol", "streaming", "performance"]
-        not_ideal_for: ["browser clients", "debugging", "REST ecosystem"]
-        pairs_with:
-          - "@grpc/grpc-js 1.9"
-          - "protobufjs 7.2"
-        beginner_friendly: false
 
   authentication:
     triggers: ["auth", "login", "user management", "security", "identity"]
@@ -129,200 +41,59 @@ decision_categories:
     affects: "security and user epics"
     options:
       nextauth:
-        name: "NextAuth.js"
+        pairs_with: ["Next.js", "Prisma"]
-        current_version: "4.24"
-        good_for: ["Next.js projects", "OAuth providers", "database sessions", "JWT"]
-        not_ideal_for: ["non-Next.js", "complex RBAC", "native mobile"]
-        pairs_with:
-          - "Next.js 14"
-          - "Prisma 5.6"
-        beginner_friendly: true
-
       auth0:
-        name: "Auth0"
+        pairs_with: ["@auth0/nextjs-auth0"]
-        good_for: ["enterprise", "compliance", "multi-tenant", "social login"]
-        not_ideal_for: ["cost sensitive", "custom requirements"]
-        pairs_with:
-          - "@auth0/nextjs-auth0 3.5"
-          - "auth0 4.2"
-        beginner_friendly: true
-
       clerk:
-        name: "Clerk"
+        pairs_with: ["@clerk/nextjs"]
-        current_version: "4.29"
+      supabase_auth:
-        good_for: ["modern stack", "user management UI", "React/Next.js"]
+        pairs_with: ["@supabase/supabase-js"]
-        not_ideal_for: ["custom UI requirements", "legacy systems"]
+      firebase_auth:
-        pairs_with:
+        pairs_with: ["firebase-admin"]
-          - "@clerk/nextjs 4.29"
-        beginner_friendly: true
 
-      supertokens:
+  real_time:
-        name: "SuperTokens"
+    triggers: ["real-time", "websocket", "live updates", "chat", "collaboration"]
-        current_version: "16.6"
+    importance: "medium"
-        good_for: ["open source", "self-hosted", "customizable"]
+    affects: "real-time features"
-        not_ideal_for: ["quick setup", "managed service"]
-        pairs_with:
-          - "supertokens-node 16.6"
-        beginner_friendly: false
-
-  frontend_framework:
-    triggers: ["UI", "frontend", "client", "web app", "user interface"]
-    importance: "critical"
-    affects: "all UI epics"
     options:
-      nextjs:
+      socket_io:
-        name: "Next.js"
+        pairs_with: ["Express", "socket.io-client"]
-        current_version: "14.0"
-        good_for: ["full-stack", "SSR/SSG", "React ecosystem", "SEO"]
-        not_ideal_for: ["pure SPA", "non-React", "simple sites"]
-        pairs_with:
-          - "React 18.2"
-          - "TypeScript 5.3"
-          - "Tailwind CSS 3.4"
-        beginner_friendly: true
-
-      react_spa:
-        name: "React SPA"
-        current_version: "18.2"
-        good_for: ["complex interactions", "existing APIs", "flexibility"]
-        not_ideal_for: ["SEO critical", "initial load time"]
-        pairs_with:
-          - "Vite 5.0"
-          - "React Router 6.21"
-          - "TypeScript 5.3"
-        beginner_friendly: true
-
-      vue:
-        name: "Vue.js"
-        current_version: "3.4"
-        good_for: ["progressive enhancement", "simple mental model", "template syntax"]
-        not_ideal_for: ["React ecosystem needs", "hiring pool"]
-        pairs_with:
-          - "Nuxt 3.9"
-          - "Vite 5.0"
-          - "Pinia 2.1"
-        beginner_friendly: true
-
-      solidjs:
-        name: "SolidJS"
-        current_version: "1.8"
-        good_for: ["performance", "fine-grained reactivity", "small bundle"]
-        not_ideal_for: ["ecosystem size", "learning resources"]
-        pairs_with:
-          - "SolidStart 0.4"
-          - "Vite 5.0"
-        beginner_friendly: false
-
-  state_management:
-    triggers: ["state", "store", "client state", "data flow", "redux"]
-    importance: "high"
-    affects: "frontend epics"
-    options:
-      zustand:
-        name: "Zustand"
-        current_version: "4.4"
-        good_for: ["simplicity", "TypeScript", "small bundle", "React"]
-        not_ideal_for: ["time-travel debugging", "Redux ecosystem"]
-        beginner_friendly: true
-
-      redux_toolkit:
-        name: "Redux Toolkit"
-        current_version: "2.0"
-        good_for: ["complex state", "debugging", "ecosystem", "predictable"]
-        not_ideal_for: ["simple apps", "boilerplate"]
-        beginner_friendly: false
-
-      tanstack_query:
-        name: "TanStack Query"
-        current_version: "5.17"
-        good_for: ["server state", "caching", "synchronization", "mutations"]
-        not_ideal_for: ["pure client state", "offline-heavy"]
-        beginner_friendly: true
-
-      jotai:
-        name: "Jotai"
-        current_version: "2.6"
-        good_for: ["atomic state", "React Suspense", "TypeScript"]
-        not_ideal_for: ["debugging tools", "ecosystem size"]
-        beginner_friendly: false
-
-  realtime:
-    triggers: ["real-time", "websocket", "live", "push", "streaming", "collaborative"]
-    importance: "high"
-    affects: "real-time feature epics"
-    options:
-      socketio:
-        name: "Socket.io"
-        current_version: "4.6"
-        good_for: ["fallbacks", "rooms", "namespaces", "reliability"]
-        not_ideal_for: ["raw performance", "simple needs"]
-        pairs_with:
-          - "socket.io-client 4.6"
-        beginner_friendly: true
-
-      websocket_native:
-        name: "Native WebSocket"
-        good_for: ["performance", "simple needs", "no dependencies"]
-        not_ideal_for: ["fallbacks", "reconnection", "complex patterns"]
-        pairs_with:
-          - "ws 8.16"
-        beginner_friendly: false
-
       pusher:
-        name: "Pusher"
+        pairs_with: ["pusher-js"]
-        good_for: ["managed service", "quick setup", "global infrastructure"]
-        not_ideal_for: ["cost at scale", "self-hosted needs"]
-        pairs_with:
-          - "pusher-js 8.4"
-        beginner_friendly: true
-
       ably:
-        name: "Ably"
+        pairs_with: ["ably"]
-        current_version: "1.2"
+      supabase_realtime:
-        good_for: ["guaranteed delivery", "presence", "history", "managed"]
+        pairs_with: ["@supabase/supabase-js"]
-        not_ideal_for: ["cost sensitive", "simple needs"]
+      firebase_realtime:
-        pairs_with:
+        pairs_with: ["firebase"]
-          - "ably 1.2"
+
-        beginner_friendly: true
+  email:
+    triggers: ["email", "notifications", "transactional email"]
+    importance: "medium"
+    affects: "notification epics"
+    options:
+      resend:
+        pairs_with: ["resend", "react-email"]
+      sendgrid:
+        pairs_with: ["@sendgrid/mail"]
+      postmark:
+        pairs_with: ["postmark"]
+      ses:
+        pairs_with: ["@aws-sdk/client-ses"]
 
   file_storage:
-    triggers: ["file upload", "images", "documents", "media", "blob storage", "assets"]
+    triggers: ["upload", "file storage", "images", "media", "CDN"]
     importance: "medium"
-    affects: "content epics"
+    affects: "media handling epics"
     options:
       s3:
-        name: "AWS S3"
+        pairs_with: ["@aws-sdk/client-s3", "multer"]
-        good_for: ["scale", "durability", "ecosystem", "CDN integration"]
-        not_ideal_for: ["simple needs", "cost optimization"]
-        pairs_with:
-          - "@aws-sdk/client-s3 3.478"
-          - "multer-s3 3.0"
-        beginner_friendly: false
-
       cloudinary:
-        name: "Cloudinary"
+        pairs_with: ["cloudinary"]
-        good_for: ["image optimization", "transformations", "CDN", "easy setup"]
-        not_ideal_for: ["raw files", "cost at scale"]
-        pairs_with:
-          - "cloudinary 1.41"
-        beginner_friendly: true
-
       uploadthing:
-        name: "UploadThing"
+        pairs_with: ["uploadthing"]
-        current_version: "6.0"
+      supabase_storage:
-        good_for: ["Next.js", "type safety", "simple setup"]
+        pairs_with: ["@supabase/supabase-js"]
-        not_ideal_for: ["non-Next.js", "complex requirements"]
-        pairs_with:
-          - "uploadthing 6.0"
-        beginner_friendly: true
-
-      local_storage:
-        name: "Local File System"
-        good_for: ["development", "on-premise", "simple needs"]
-        not_ideal_for: ["scale", "CDN", "distributed systems"]
-        pairs_with:
-          - "multer 1.4"
-        beginner_friendly: true
 
   search:
     triggers: ["search", "full text", "elasticsearch", "algolia", "fuzzy"]
@@ -330,36 +101,13 @@ decision_categories:
     affects: "search and discovery epics"
     options:
       postgres_fts:
-        name: "PostgreSQL Full Text Search"
+        pairs_with: ["PostgreSQL"]
-        good_for: ["simple search", "no extra infrastructure", "cost effective"]
-        not_ideal_for: ["complex relevance", "fuzzy matching", "facets"]
-        beginner_friendly: true
-
       elasticsearch:
-        name: "Elasticsearch"
+        pairs_with: ["@elastic/elasticsearch"]
-        current_version: "8.11"
-        good_for: ["complex search", "analytics", "aggregations", "scale"]
-        not_ideal_for: ["simple needs", "operational overhead"]
-        pairs_with:
-          - "@elastic/elasticsearch 8.11"
-        beginner_friendly: false
-
       algolia:
-        name: "Algolia"
+        pairs_with: ["algoliasearch"]
-        good_for: ["instant search", "typo tolerance", "managed service", "speed"]
-        not_ideal_for: ["cost at scale", "data sovereignty"]
-        pairs_with:
-          - "algoliasearch 4.22"
-        beginner_friendly: true
-
       typesense:
-        name: "Typesense"
+        pairs_with: ["typesense"]
-        current_version: "1.7"
-        good_for: ["open source alternative to Algolia", "typo tolerance", "self-hosted"]
-        not_ideal_for: ["managed service needs", "small projects"]
-        pairs_with:
-          - "typesense 1.7"
-        beginner_friendly: false
 
   background_jobs:
     triggers: ["queue", "jobs", "workers", "async", "background processing", "scheduled"]
@@ -367,39 +115,13 @@ decision_categories:
     affects: "async processing epics"
     options:
       bullmq:
-        name: "BullMQ"
+        pairs_with: ["Redis"]
-        current_version: "5.1"
-        good_for: ["Redis-based", "reliable", "dashboard", "Node.js"]
-        not_ideal_for: ["multi-language", "serverless"]
-        pairs_with:
-          - "Redis 7.2"
-        beginner_friendly: true
-
       sqs:
-        name: "AWS SQS"
+        pairs_with: ["@aws-sdk/client-sqs"]
-        good_for: ["managed service", "scale", "AWS ecosystem", "serverless"]
-        not_ideal_for: ["local development", "complex patterns"]
-        pairs_with:
-          - "@aws-sdk/client-sqs 3.478"
-        beginner_friendly: false
-
       temporal:
-        name: "Temporal"
+        pairs_with: ["@temporalio/client"]
-        current_version: "1.22"
-        good_for: ["complex workflows", "durability", "long-running", "saga pattern"]
-        not_ideal_for: ["simple jobs", "quick setup"]
-        pairs_with:
-          - "@temporalio/client 1.9"
-        beginner_friendly: false
-
       inngest:
-        name: "Inngest"
+        pairs_with: ["inngest"]
-        current_version: "3.8"
-        good_for: ["serverless", "event-driven", "TypeScript", "retries"]
-        not_ideal_for: ["self-hosted", "complex workflows"]
-        pairs_with:
-          - "inngest 3.8"
-        beginner_friendly: true
 
   deployment_target:
     triggers: ["deployment", "hosting", "infrastructure", "cloud", "server"]
@@ -407,277 +129,80 @@ decision_categories:
     affects: "all epics"
     options:
       vercel:
-        name: "Vercel"
+        pairs_with: ["Next.js", "serverless functions"]
-        good_for: ["Next.js", "edge functions", "preview deployments", "simplicity"]
-        not_ideal_for: ["complex backends", "cost at scale", "non-JS"]
-        beginner_friendly: true
-
       aws:
-        name: "AWS"
+        pairs_with: ["any stack"]
-        good_for: ["everything", "scale", "compliance", "flexibility"]
-        not_ideal_for: ["simplicity", "predictable costs", "small projects"]
-        beginner_friendly: false
-
       railway:
-        name: "Railway"
+        pairs_with: ["any stack", "managed databases"]
-        good_for: ["simplicity", "databases included", "quick setup"]
-        not_ideal_for: ["enterprise needs", "complex requirements"]
-        beginner_friendly: true
-
       fly_io:
-        name: "Fly.io"
+        pairs_with: ["Docker containers"]
-        good_for: ["edge deployment", "global distribution", "containers"]
-        not_ideal_for: ["managed databases", "enterprise support"]
-        beginner_friendly: false
 
-# Pattern combinations that work well together
+# Opinionated stack combinations (BMM methodology)
 common_stacks:
   modern_fullstack:
     name: "Modern Full-Stack"
-    components:
+    components: ["Next.js", "PostgreSQL or Supabase", "Prisma ORM", "NextAuth.js", "Tailwind CSS", "TypeScript", "Vercel"]
-      - "Next.js 14"
-      - "PostgreSQL 15 or Supabase"
-      - "Prisma ORM 5.6"
-      - "NextAuth.js 4.24"
-      - "Tailwind CSS 3.4"
-      - "TypeScript 5.3"
-      - "Vercel deployment"
     good_for: "Most web applications"
 
   enterprise_stack:
     name: "Enterprise Stack"
-    components:
+    components: ["NestJS", "PostgreSQL", "TypeORM", "Auth0", "Redis", "Docker", "AWS"]
-      - "NestJS 10.3"
+    good_for: "Large-scale enterprise applications"
-      - "PostgreSQL 15"
-      - "TypeORM 0.3"
-      - "Auth0"
-      - "React 18.2 + TypeScript"
-      - "AWS deployment"
-    good_for: "Large scale, compliance needs"
 
-  startup_stack:
+  rapid_prototype:
-    name: "Rapid Development Stack"
+    name: "Rapid Prototype"
-    components:
+    components: ["Next.js", "Supabase", "shadcn/ui", "Vercel"]
-      - "Next.js 14"
+    good_for: "MVP and rapid development"
-      - "Supabase"
-      - "Clerk Auth"
-      - "Tailwind CSS 3.4"
-      - "Vercel deployment"
-    good_for: "MVPs and rapid prototyping"
 
-  realtime_stack:
+  real_time_app:
-    name: "Real-time Collaboration"
+    name: "Real-Time Application"
-    components:
+    components: ["Next.js", "Supabase Realtime", "PostgreSQL", "Prisma", "Socket.io fallback"]
-      - "Next.js 14"
+    good_for: "Chat, collaboration, live updates"
-      - "Socket.io 4.6"
-      - "Redis 7.2"
-      - "PostgreSQL 15"
-      - "Railway deployment"
-    good_for: "Collaborative applications"
 
-# WARNING: Version numbers are illustrative - actual versions should be verified
+  mobile_app:
-# during workflow execution via web search for current stable versions
+    name: "Mobile Application"
+    components: ["Expo", "React Native", "Supabase or Firebase", "React Query"]
+    good_for: "Cross-platform mobile apps"
 
-# Starter templates that make architectural decisions
+# Starter templates and what decisions they make
 starter_templates:
   create_next_app:
     name: "Create Next App"
-    command_search: "npx create-next-app@latest options"
+    command_search: "npx create-next-app@latest"
-    base_command: "npx create-next-app@latest"
+    decisions_provided: ["Next.js framework", "TypeScript option", "App Router vs Pages", "Tailwind CSS option", "ESLint"]
-    interactive: true
+    good_for: ["React web applications", "Full-stack apps", "SSR/SSG"]
-    decisions_provided:
-      - "TypeScript vs JavaScript (--typescript flag)"
-      - "ESLint configuration (--eslint flag)"
-      - "Tailwind CSS setup (--tailwind flag)"
-      - "App Router vs Pages Router (--app flag)"
-      - "src/ directory structure (--src-dir flag)"
-      - "Import alias (@/* default)"
-    project_structure: "Standard Next.js structure with app/ or pages/"
-    good_for: ["Web applications", "SSR/SSG needs", "Full-stack React"]
 
   create_t3_app:
     name: "Create T3 App"
-    command_search: "create t3 app latest CLI options"
+    command_search: "npm create t3-app@latest"
-    base_command: "npm create t3-app@latest"
+    decisions_provided: ["Next.js", "TypeScript", "tRPC", "Prisma", "NextAuth", "Tailwind CSS"]
-    interactive: true
+    good_for: ["Type-safe full-stack apps"]
-    decisions_provided:
-      - "Next.js framework (always)"
-      - "TypeScript (always)"
-      - "tRPC for type-safe APIs"
-      - "Prisma ORM"
-      - "NextAuth.js authentication"
-      - "Tailwind CSS"
-      - "Drizzle ORM (alternative to Prisma)"
-    project_structure: "Opinionated full-stack structure"
-    good_for: ["Type-safe full-stack", "Rapid development", "Best practices"]
 
   create_vite:
     name: "Create Vite"
-    command_search: "npm create vite templates options"
+    command_search: "npm create vite@latest"
-    base_command: "npm create vite@latest"
+    decisions_provided: ["Framework choice (React/Vue/Svelte)", "TypeScript option", "Vite bundler"]
-    interactive: true
+    good_for: ["Fast dev SPAs", "Library development"]
-    templates_available:
-      - "vanilla"
-      - "vanilla-ts"
-      - "react"
-      - "react-ts"
-      - "react-swc"
-      - "react-swc-ts"
-      - "vue"
-      - "vue-ts"
-      - "svelte"
-      - "svelte-ts"
-    decisions_provided:
-      - "Build tool (Vite)"
-      - "Framework choice"
-      - "TypeScript setup"
-      - "HMR configuration"
-      - "Development server"
-    project_structure: "Minimal, framework-specific"
-    good_for: ["SPAs", "Fast development", "Modern tooling"]
-
-  create_react_app:
-    name: "Create React App"
-    status: "DEPRECATED - Use Vite or Next.js instead"
-    note: "No longer recommended by React team"
 
   create_remix:
     name: "Create Remix"
-    command_search: "npx create-remix latest options"
+    command_search: "npx create-remix@latest"
-    base_command: "npx create-remix@latest"
+    decisions_provided: ["Remix framework", "TypeScript option", "Deployment target", "CSS solution"]
-    decisions_provided:
-      - "Remix framework"
-      - "TypeScript option"
-      - "Deployment target"
-      - "CSS solution"
     good_for: ["Web standards", "Nested routing", "Progressive enhancement"]
 
   nest_new:
     name: "NestJS CLI"
-    command_search: "nest new project options"
+    command_search: "nest new project"
-    base_command: "nest new"
+    decisions_provided: ["TypeScript (always)", "Package manager", "Testing framework (Jest)", "Project structure"]
-    decisions_provided:
-      - "TypeScript (always)"
-      - "Package manager"
-      - "Testing framework (Jest)"
-      - "Linting (ESLint)"
-      - "Project structure (modules/controllers/services)"
-    project_structure: "Enterprise Angular-style backend"
     good_for: ["Enterprise APIs", "Microservices", "GraphQL APIs"]
 
   create_expo_app:
     name: "Create Expo App"
-    command_search: "create-expo-app templates latest"
+    command_search: "npx create-expo-app"
-    base_command: "npx create-expo-app"
+    decisions_provided: ["React Native", "Expo SDK", "TypeScript option", "Navigation option"]
-    decisions_provided:
-      - "React Native setup"
-      - "TypeScript option"
-      - "Navigation library option"
-      - "Expo SDK version"
     good_for: ["Cross-platform mobile", "React Native apps"]
 
-  create_vue:
+# Starter selection heuristics (workflow logic)
-    name: "Create Vue"
-    command_search: "npm create vue latest options"
-    base_command: "npm create vue@latest"
-    decisions_provided:
-      - "Vue 3"
-      - "TypeScript option"
-      - "JSX support"
-      - "Vue Router"
-      - "Pinia state management"
-      - "Vitest for testing"
-      - "ESLint + Prettier"
-    good_for: ["Vue applications", "Progressive web apps"]
-
-  create_astro:
-    name: "Create Astro"
-    command_search: "npm create astro latest templates"
-    base_command: "npm create astro@latest"
-    decisions_provided:
-      - "Astro framework"
-      - "TypeScript strictness"
-      - "Template choice"
-      - "Framework integrations"
-    good_for: ["Content sites", "Static sites", "Islands architecture"]
-
-  create_svelte:
-    name: "Create Svelte"
-    command_search: "npm create svelte latest options"
-    base_command: "npm create svelte@latest"
-    decisions_provided:
-      - "SvelteKit framework"
-      - "TypeScript option"
-      - "ESLint"
-      - "Prettier"
-      - "Testing setup"
-    good_for: ["Svelte applications", "Compiled frameworks"]
-
-  cargo_new:
-    name: "Cargo New (Rust)"
-    command_search: "cargo new options binary library"
-    base_command: "cargo new"
-    decisions_provided:
-      - "Binary vs Library (--bin or --lib)"
-      - "Project structure"
-      - "Cargo.toml setup"
-    good_for: ["Rust CLI tools", "Systems programming", "Performance critical"]
-
-  dotnet_new:
-    name: ".NET CLI"
-    command_search: "dotnet new templates list"
-    base_command: "dotnet new"
-    templates_available:
-      - "webapi"
-      - "webapp"
-      - "blazor"
-      - "console"
-      - "classlib"
-    decisions_provided:
-      - "Project type"
-      - ".NET version"
-      - "Authentication option"
-      - "HTTPS configuration"
-    good_for: ["C# applications", "Enterprise", "Windows development"]
-
-  rails_new:
-    name: "Rails New"
-    command_search: "rails new options latest"
-    base_command: "rails new"
-    decisions_provided:
-      - "Database (PostgreSQL/MySQL/SQLite)"
-      - "CSS framework"
-      - "JavaScript approach"
-      - "Testing framework"
-      - "API-only mode"
-    good_for: ["Ruby web apps", "Rapid prototyping", "Convention over configuration"]
-
-  django_startproject:
-    name: "Django Start Project"
-    command_search: "django-admin startproject structure"
-    base_command: "django-admin startproject"
-    decisions_provided:
-      - "Django framework"
-      - "Project structure"
-      - "Settings configuration"
-      - "Database (SQLite default)"
-    good_for: ["Python web apps", "Admin interfaces", "Content management"]
-
-  create_redwood_app:
-    name: "Create RedwoodJS App"
-    command_search: "yarn create redwood-app latest"
-    base_command: "yarn create redwood-app"
-    decisions_provided:
-      - "RedwoodJS framework"
-      - "TypeScript (default)"
-      - "Prisma ORM"
-      - "GraphQL API"
-      - "Storybook"
-      - "Testing setup"
-    project_structure: "Monorepo with api/ and web/"
-    good_for: ["Full-stack JAMstack", "Startups", "Rapid development"]
-
-# Starter template selection heuristics
 starter_selection_rules:
   by_project_type:
     web_application:
@@ -685,17 +210,13 @@ starter_selection_rules:
       considerations: "SSR needs? → Next.js. Type safety critical? → T3. SPA only? → Vite"
 
     mobile_app:
-      recommended: ["create_expo_app", "react_native_cli"]
+      recommended: ["create_expo_app"]
-      considerations: "Need native modules? → React Native CLI. Simpler setup? → Expo"
+      considerations: "Cross-platform → Expo. Native-heavy → React Native CLI"
 
     api_backend:
-      recommended: ["nest_new", "express_generator", "fastify_cli"]
+      recommended: ["nest_new"]
-      considerations: "Enterprise? → NestJS. Simple? → Express. Performance? → Fastify"
+      considerations: "Enterprise → NestJS. Simple → Express starter. Performance → Fastify"
-
-    cli_tool:
-      recommended: ["cargo_new", "go_mod_init", "npm_init"]
-      considerations: "Performance critical? → Rust/Go. Quick script? → Node.js/Python"
 
     full_stack:
-      recommended: ["create_t3_app", "create_redwood_app", "rails_new"]
+      recommended: ["create_t3_app", "create_remix"]
-      considerations: "Type safety? → T3. JAMstack? → Redwood. Ruby? → Rails"
+      considerations: "Type safety → T3. Web standards → Remix. Monolith → RedwoodJS"

src/modules/bmm/workflows/4-implementation/correct-course/checklist.md

@@ -33,8 +33,8 @@
 </check-item>
 
 <halt-condition>
-<check>If trigger is unclear: "Cannot proceed without understanding what caused the need for change"</check>
+<action if="trigger is unclear">HALT: "Cannot proceed without understanding what caused the need for change"</action>
-<check>If no evidence provided: "Need concrete evidence or examples of the issue before analyzing impact"</check>
+<action if="no evidence provided">HALT: "Need concrete evidence or examples of the issue before analyzing impact"</action>
 </halt-condition>
 
 </section>
@@ -261,9 +261,9 @@
 </check-item>
 
 <halt-condition>
-<check>If any critical section cannot be completed: "Cannot proceed to proposal without complete impact analysis"</check>
+<action if="any critical section cannot be completed">HALT: "Cannot proceed to proposal without complete impact analysis"</action>
-<check>If user approval not obtained: "Must have explicit approval before implementing changes"</check>
+<action if="user approval not obtained">HALT: "Must have explicit approval before implementing changes"</action>
-<check>If handoff responsibilities unclear: "Must clearly define who will execute the proposed changes"</check>
+<action if="handoff responsibilities unclear">HALT: "Must clearly define who will execute the proposed changes"</action>
 </halt-condition>
 
 </section>

src/modules/bmm/workflows/4-implementation/dev-story/instructions.md

@@ -50,9 +50,9 @@
     <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
     <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
 
-    <check>If no incomplete tasks → <goto step="6">Completion sequence</goto></check>
+    <action if="no incomplete tasks"><goto step="6">Completion sequence</goto></action>
-    <check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
+    <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
-    <check>If task requirements ambiguous → ASK user to clarify or HALT</check>
+    <action if="task requirements ambiguous">ASK user to clarify or HALT</action>
   </step>
 
   <step n="1.5" goal="Mark story in-progress in sprint status">
@@ -88,11 +88,11 @@ Story is already marked in-progress
     <action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
     <action>Implement the task COMPLETELY including all subtasks, following architecture patterns and coding standards in this repo</action>
     <action>Handle error conditions and edge cases appropriately</action>
-    <check>If unapproved dependencies are needed → ASK user for approval before adding</check>
+    <action if="unapproved dependencies are needed">ASK user for approval before adding</action>
-    <check>If 3 consecutive implementation failures occur → HALT and request guidance</check>
+    <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
-    <check>If required configuration is missing → HALT: "Cannot proceed without necessary configuration files"</check>
+    <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
-    <check>If {{run_until_complete}} == true → Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</check>
+    <action if="{{run_until_complete}} == true">Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</action>
-    <check>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</check>
+    <critical>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</critical>
   </step>
 
   <step n="3" goal="Author comprehensive tests">
@@ -108,8 +108,8 @@ Story is already marked in-progress
     <action>Run the new tests to verify implementation correctness</action>
     <action>Run linting and code quality checks if configured</action>
     <action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
-    <check>If regression tests fail → STOP and fix before continuing</check>
+    <action if="regression tests fail">STOP and fix before continuing</action>
-    <check>If new tests fail → STOP and fix before continuing</check>
+    <action if="new tests fail">STOP and fix before continuing</action>
   </step>
 
   <step n="5" goal="Mark task complete and update story">
@@ -118,9 +118,9 @@ Story is already marked in-progress
     <action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
     <action>Append a brief entry to Change Log describing the change</action>
     <action>Save the story file</action>
-    <check>Determine if more incomplete tasks remain</check>
+    <action>Determine if more incomplete tasks remain</action>
-    <check>If more tasks remain → <goto step="1">Next task</goto></check>
+    <action if="more tasks remain"><goto step="1">Next task</goto></action>
-    <check>If no tasks remain → <goto step="6">Completion</goto></check>
+    <action if="no tasks remain"><goto step="6">Completion</goto></action>
   </step>
 
   <step n="6" goal="Story completion sequence">
@@ -144,9 +144,9 @@ Story is marked Ready for Review in file, but sprint-status.yaml may be out of s
       </output>
     </check>
 
-    <check>If any task is incomplete → Return to step 1 to complete remaining work (Do NOT finish with partial progress)</check>
+    <action if="any task is incomplete">Return to step 1 to complete remaining work (Do NOT finish with partial progress)</action>
-    <check>If regression failures exist → STOP and resolve before completing</check>
+    <action if="regression failures exist">STOP and resolve before completing</action>
-    <check>If File List is incomplete → Update it before completing</check>
+    <action if="File List is incomplete">Update it before completing</action>
   </step>
 
   <step n="7" goal="Validation and handoff" optional="true">

src/modules/bmm/workflows/README.md

@@ -385,7 +385,7 @@ plan-project (Phase 2)
 | Phase              | Primary Agents      | Supporting Agents           |
 | ------------------ | ------------------- | --------------------------- |
 | **Analysis**       | Analyst, Researcher | PM, PO                      |
-| **Planning**       | PM                  | Analyst, UX Expert          |
+| **Planning**       | PM                  | Analyst, UX Designer        |
 | **Solutioning**    | Architect           | PM, Tech Lead               |
 | **Implementation** | SM, DEV             | SR, PM (for correct-course) |
 

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-2.yaml

@@ -50,10 +50,10 @@ phases:
         command: "tech-spec"
         output: "Creates spec with multiple story files"
         note: "Integrate with existing patterns"
-      - id: "ux-spec"
+      - id: "create-design"
         conditional: "if_has_ui"
-        agent: "ux-expert"
+        agent: "ux-designer"
-        command: "ux-spec"
+        command: "create-design"
 
   - phase: 3
     name: "Solutioning"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-3.yaml

@@ -44,10 +44,10 @@ phases:
         agent: "pm"
         command: "prd"
         output: "Requirements with integration points"
-      - id: "ux-spec"
+      - id: "create-design"
         conditional: "if_has_ui"
-        agent: "pm"
+        agent: "ux-designer"
-        command: "ux-spec"
+        command: "create-design"
         note: "Must align with existing UI patterns"
 
   - phase: 3

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-4.yaml

@@ -46,10 +46,10 @@ phases:
         agent: "pm"
         command: "prd"
         output: "Comprehensive PRD considering existing system"
-      - id: "ux-spec"
+      - id: "create-design"
         required: true
-        agent: "pm"
+        agent: "ux-designer"
-        command: "ux-spec"
+        command: "create-design"
         note: "Multiple UI/UX specifications"
 
   - phase: 3

src/modules/bmm/workflows/workflow-status/paths/greenfield-level-2.yaml

@@ -34,10 +34,10 @@ phases:
         agent: "pm"
         command: "prd"
         output: "Creates PRD with epics.md and story list"
-      - id: "ux-spec"
+      - id: "create-design"
         conditional: "if_has_ui"
-        agent: "ux-expert"
+        agent: "ux-designer"
-        command: "ux-spec"
+        command: "create-design"
       - id: "tech-spec"
         optional: true
         agent: "pm"

src/modules/bmm/workflows/workflow-status/paths/greenfield-level-3.yaml

@@ -34,10 +34,10 @@ phases:
         agent: "pm"
         command: "prd"
         output: "High-level requirements and epic definitions"
-      - id: "ux-spec"
+      - id: "create-design"
         conditional: "if_has_ui"
-        agent: "ux-expert"
+        agent: "ux-designer"
-        command: "ux-spec"
+        command: "create-design"
 
   - phase: 3
     name: "Solutioning"

src/modules/bmm/workflows/workflow-status/paths/greenfield-level-4.yaml

@@ -16,7 +16,7 @@ phases:
         agent: "analyst"
         command: "brainstorm-project"
       - id: "research"
-        required: true
+        required: false
         agent: "analyst"
         command: "research"
         note: "Extensive research across multiple domains"
@@ -35,10 +35,10 @@ phases:
         agent: "pm"
         command: "prd"
         output: "Comprehensive product requirements document"
-      - id: "ux-spec"
+      - id: "create-design"
         required: true
-        agent: "ux-expert"
+        agent: "ux-designer"
-        command: "ux-spec"
+        command: "create-design"
         note: "Multiple UI/UX specifications needed"
 
   - phase: 3

src/modules/bmm/workflows/workflow-status/project-levels.yaml

@@ -39,7 +39,7 @@ levels:
     title: "Enterprise Scale"
     stories: "40+ stories"
     description: "Multiple products, enterprise architecture"
-    documentation: "Full suite - PRD, architecture, product specs"
+    documentation: "PRD + architecture + JIT tech specs"
     architecture: true
 
 # Quick detection hints for workflow-init

src/modules/bmm/workflows/workflow-status/workflow-status-template.md

@@ -25,21 +25,6 @@ NEXT_ACTION: {{next_action}}
 NEXT_COMMAND: {{next_command}}
 NEXT_AGENT: {{next_agent}}
 
-## Story Backlog
-
-{{#backlog_stories}}
-
-- {{story_id}}: {{story_title}}
-  {{/backlog_stories}}
-
-## Completed Stories
-
-{{#done_stories}}
-
-- {{story_id}}: {{completed_date}}
-  {{/done_stories}}
-
 ---
 
 _Last Updated: {{last_updated}}_
-_Status Version: 2.0_

src/modules/cis/workflows/storytelling/instructions.md

@@ -10,20 +10,24 @@
 <step n="1" goal="Story Context Setup">
 
 <action>Check if context data was provided with workflow invocation</action>
-<check>If data attribute was passed to this workflow:</check>
+
-<action>Load the context document from the data file path</action>
+<check if="data attribute was passed to this workflow">
-<action>Study the background information, brand details, or subject matter</action>
+  <action>Load the context document from the data file path</action>
-<action>Use the provided context to inform story development</action>
+  <action>Study the background information, brand details, or subject matter</action>
-<action>Acknowledge the focused storytelling goal</action>
+  <action>Use the provided context to inform story development</action>
-<ask response="story_refinement">I see we're crafting a story based on the context provided. What specific angle or emphasis would you like?</ask>
+  <action>Acknowledge the focused storytelling goal</action>
-<check>Else (no context data provided):</check>
+  <ask response="story_refinement">I see we're crafting a story based on the context provided. What specific angle or emphasis would you like?</ask>
-<action>Proceed with context gathering</action>
+</check>
-<ask response="story_purpose">1. What's the purpose of this story? (e.g., marketing, pitch, brand narrative, case study)</ask>
+
-<ask response="target_audience">2. Who is your target audience?</ask>
+<check if="no context data provided">
-<ask response="key_messages">3. What key messages or takeaways do you want the audience to have?</ask>
+  <action>Proceed with context gathering</action>
-<ask>4. Any constraints? (length, tone, medium, existing brand guidelines)</ask>
+  <ask response="story_purpose">1. What's the purpose of this story? (e.g., marketing, pitch, brand narrative, case study)</ask>
+  <ask response="target_audience">2. Who is your target audience?</ask>
+  <ask response="key_messages">3. What key messages or takeaways do you want the audience to have?</ask>
+  <ask>4. Any constraints? (length, tone, medium, existing brand guidelines)</ask>
 
 <critical>Wait for user response before proceeding. This context shapes the narrative approach.</critical>
+</check>
 
 <template-output>story_purpose, target_audience, key_messages</template-output>
 
@@ -53,13 +57,14 @@ I can help craft your story using these proven narrative frameworks:
 Which framework best fits your purpose? (Enter 1-10, or ask for my recommendation)
 </ask>
 
-<check>If user asks for recommendation:</check>
+<check if="user asks for recommendation">
-<action>Analyze story_purpose, target_audience, and key_messages</action>
+  <action>Analyze story_purpose, target_audience, and key_messages</action>
-<action>Recommend best-fit framework with clear rationale</action>
+  <action>Recommend best-fit framework with clear rationale</action>
-<example>
+  <example>
-Based on your {{story_purpose}} for {{target_audience}}, I recommend:
+  Based on your {{story_purpose}} for {{target_audience}}, I recommend:
-**{{framework_name}}** because {{rationale}}
+  **{{framework_name}}** because {{rationale}}
-</example>
+  </example>
+</check>
 
 <template-output>story_type, framework_name</template-output>
 

tools/format-workflow-md.js

@@ -0,0 +1,263 @@
+/**
+ * BMAD Workflow Markdown Formatter
+ *
+ * Formats mixed markdown + XML workflow instruction files with:
+ * - 2-space XML indentation
+ * - Preserved markdown content
+ * - Proper tag nesting
+ * - Consistent formatting
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class WorkflowFormatter {
+  constructor(options = {}) {
+    this.indentSize = options.indentSize || 2;
+    this.preserveMarkdown = options.preserveMarkdown !== false;
+    this.verbose = options.verbose || false;
+  }
+
+  /**
+   * Format a workflow markdown file
+   */
+  format(filePath) {
+    if (this.verbose) {
+      console.log(`Formatting: ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const formatted = this.formatContent(content);
+
+    // Only write if content changed
+    if (content === formatted) {
+      if (this.verbose) {
+        console.log(`- No changes: ${filePath}`);
+      }
+      return false;
+    } else {
+      fs.writeFileSync(filePath, formatted, 'utf8');
+      if (this.verbose) {
+        console.log(`✓ Formatted: ${filePath}`);
+      }
+      return true;
+    }
+  }
+
+  /**
+   * Format content string with stateful indentation tracking
+   */
+  formatContent(content) {
+    const lines = content.split('\n');
+    const formatted = [];
+    let indentLevel = 0;
+    let inCodeBlock = false;
+    let checkBlockDepth = 0; // Track nested check blocks
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      // Track code blocks (don't format inside them)
+      if (trimmed.startsWith('```')) {
+        if (inCodeBlock) {
+          inCodeBlock = false;
+        } else {
+          inCodeBlock = true;
+        }
+        formatted.push(line);
+        continue;
+      }
+
+      // Don't format inside code blocks
+      if (inCodeBlock) {
+        formatted.push(line);
+        continue;
+      }
+
+      // Handle XML tags
+      if (this.isXMLLine(trimmed)) {
+        const result = this.formatXMLLine(trimmed, indentLevel, checkBlockDepth, i, lines);
+        formatted.push(result.line);
+        indentLevel = result.nextIndent;
+        checkBlockDepth = result.nextCheckDepth;
+      } else if (trimmed === '') {
+        // Preserve blank lines
+        formatted.push('');
+      } else {
+        // Markdown content - preserve as-is but maintain current indent if inside XML
+        formatted.push(line);
+      }
+    }
+
+    return formatted.join('\n');
+  }
+
+  /**
+   * Check if line contains XML tag
+   */
+  isXMLLine(line) {
+    return /^<[a-zA-Z-]+(\s|>|\/)/.test(line) || /^<\/[a-zA-Z-]+>/.test(line);
+  }
+
+  /**
+   * Format a single XML line with context awareness
+   */
+  formatXMLLine(line, currentIndent, checkDepth, lineIndex, allLines) {
+    const trimmed = line.trim();
+    let indent = currentIndent;
+    let nextIndent = currentIndent;
+    let nextCheckDepth = checkDepth;
+
+    // Get the tag name
+    const tagMatch = trimmed.match(/^<\/?([a-zA-Z-]+)/);
+    const tagName = tagMatch ? tagMatch[1] : '';
+
+    // Closing tag - decrease indent before this line
+    if (trimmed.startsWith('</')) {
+      indent = Math.max(0, currentIndent - 1);
+      nextIndent = indent;
+
+      // If closing a step, reset check depth
+      if (tagName === 'step' || tagName === 'workflow') {
+        nextCheckDepth = 0;
+      }
+    }
+    // Self-closing tags (opens and closes on same line)
+    // EXCEPT <check> tags which create logical blocks
+    else if (this.isSelfClosingTag(trimmed) && tagName !== 'check') {
+      // These don't change indent level
+      indent = currentIndent;
+      nextIndent = currentIndent;
+    }
+    // Opening tags
+    else if (trimmed.startsWith('<')) {
+      // Check if this is a <check> tag - these create logical blocks
+      if (tagName === 'check') {
+        indent = currentIndent;
+        // Check tags increase indent for following content
+        nextIndent = currentIndent + 1;
+        nextCheckDepth = checkDepth + 1;
+      }
+      // <action> tags inside check blocks stay at current indent
+      else if (tagName === 'action' && checkDepth > 0) {
+        indent = currentIndent;
+        nextIndent = currentIndent; // Don't increase further
+      }
+      // Other tags close check blocks and return to structural level
+      else if (checkDepth > 0) {
+        // Close all check blocks - return to base structural level
+        indent = Math.max(0, currentIndent - checkDepth);
+        nextIndent = indent + 1;
+        nextCheckDepth = 0;
+      }
+      // Regular opening tags (no check blocks active)
+      else {
+        indent = currentIndent;
+        nextIndent = currentIndent + 1;
+      }
+    }
+
+    const indentStr = ' '.repeat(indent * this.indentSize);
+    return {
+      line: indentStr + trimmed,
+      nextIndent: nextIndent,
+      nextCheckDepth: nextCheckDepth,
+    };
+  }
+
+  /**
+   * Check if tag opens and closes on same line
+   */
+  isSelfClosingTag(line) {
+    // Self-closing with />
+    if (line.endsWith('/>')) {
+      return true;
+    }
+    // Opens and closes on same line: <tag>content</tag>
+    const match = line.match(/^<([a-zA-Z-]+)(\s[^>]*)?>.*<\/\1>$/);
+    return match !== null;
+  }
+
+  /**
+   * Check if tag is a block-level structural tag
+   */
+  isBlockLevelTag(tagName) {
+    return ['step', 'workflow', 'check'].includes(tagName);
+  }
+}
+
+/**
+ * CLI Entry Point
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`
+BMAD Workflow Markdown Formatter
+
+Usage:
+  node format-workflow-md.js <file-pattern> [options]
+
+Options:
+  --verbose, -v     Verbose output
+  --check, -c       Check formatting without writing (exit 1 if changes needed)
+  --help, -h        Show this help
+
+Examples:
+  node format-workflow-md.js src/**/instructions.md
+  node format-workflow-md.js "src/modules/bmb/**/*.md" --verbose
+  node format-workflow-md.js file.md --check
+`);
+    process.exit(0);
+  }
+
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const check = args.includes('--check') || args.includes('-c');
+
+  // Remove flags from args
+  const files = args.filter((arg) => !arg.startsWith('-'));
+
+  const formatter = new WorkflowFormatter({ verbose });
+  let hasChanges = false;
+  let formattedCount = 0;
+
+  // Process files
+  for (const pattern of files) {
+    // For now, treat as direct file path
+    // TODO: Add glob support for patterns
+    if (fs.existsSync(pattern)) {
+      const stat = fs.statSync(pattern);
+      if (stat.isFile()) {
+        const changed = formatter.format(pattern);
+        if (changed) {
+          hasChanges = true;
+          formattedCount++;
+        }
+      } else if (stat.isDirectory()) {
+        console.error(`Error: ${pattern} is a directory. Please specify file paths.`);
+      }
+    } else {
+      console.error(`Error: File not found: ${pattern}`);
+    }
+  }
+
+  if (verbose || formattedCount > 0) {
+    console.log(`\nFormatted ${formattedCount} file(s)`);
+  }
+
+  if (check && hasChanges) {
+    console.error('\n❌ Some files need formatting. Run without --check to format.');
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { WorkflowFormatter };