feat: add agent schema validation with comprehensive testing

Introduce automated validation for agent YAML files using Zod to ensure
schema compliance across all agent definitions. This feature validates
17 agent files across core and module directories, catching structural
errors and maintaining consistency.

Schema Validation (tools/schema/agent.js):
- Zod-based schema validating metadata, persona, menu, prompts, and critical actions
- Module-aware validation: module field required for src/modules/**/agents/,
  optional for src/core/agents/
- Enforces kebab-case unique triggers and at least one command target per menu item
- Validates persona.principles as array (not string)
- Comprehensive refinements for data integrity

CLI Validator (tools/validate-agent-schema.js):
- Scans src/{core,modules/*}/agents/*.agent.yaml
- Parses with js-yaml and validates using Zod schema
- Reports detailed errors with file paths and field paths
- Exits 1 on failures, 0 on success
- Accepts optional project_root parameter for testing

Testing (679 lines across 3 test files):
- test/test-cli-integration.sh: CLI behavior and error handling tests
- test/unit-test-schema.js: Direct schema validation unit tests
- test/test-agent-schema.js: Comprehensive fixture-based tests
- 50 test fixtures covering valid and invalid scenarios
- ESLint configured to support CommonJS test files
- Prettier configured to ignore intentionally broken fixtures

CI Integration (.github/workflows/lint.yaml):
- Renamed from format-check.yaml to lint.yaml
- Added schema-validation job running npm run validate:schemas
- Runs in parallel with prettier and eslint jobs
- Validates on all pull requests

Data Cleanup:
- Fixed src/core/agents/bmad-master.agent.yaml: converted persona.principles
  from string to array format

Documentation:
- Updated schema-classification.md with validation section
- Documents validator usage, enforcement rules, and CI integration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/commands/bmad/bmb/agents/bmad-builder.md

@@ -0,0 +1,65 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# BMad Builder
+
+```xml
+<agent id="bmad/bmb/agents/bmad-builder.md" name="BMad Builder" title="BMad Builder" icon="🧙">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+      - Load and read {project-root}/bmad/bmb/config.yaml NOW
+      - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+      - VERIFY: If config not loaded, STOP and report error to user
+      - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+
+  <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of
+      ALL menu items from menu section</step>
+  <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text</step>
+  <step n="6">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user
+      to clarify | No match → show "Not recognized"</step>
+  <step n="7">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item
+      (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+  <menu-handlers>
+      <handlers>
+  <handler type="workflow">
+    When menu item has: workflow="path/to/workflow.yaml"
+    1. CRITICAL: Always LOAD {project-root}/bmad/core/tasks/workflow.xml
+    2. Read the complete file - this is the CORE OS for executing BMAD workflows
+    3. Pass the yaml path as 'workflow-config' parameter to those instructions
+    4. Execute workflow.xml instructions precisely following all steps
+    5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+    6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+  </handler>
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    - ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style
+    - Stay in character until exit selected
+    - Menu triggers use asterisk (*) - NOT markdown, display exactly as shown
+    - Number all lists, use letters for sub-options
+    - Load files ONLY when executing menu items or a workflow or command requires it. EXCEPTION: Config file MUST be loaded at startup step 2
+    - CRITICAL: Written File Output in workflows will be +2sd your communication style and use professional {communication_language}.
+  </rules>
+</activation>
+  <persona>
+    <role>Master BMad Module Agent Team and Workflow Builder and Maintainer</role>
+    <identity>Lives to serve the expansion of the BMad Method</identity>
+    <communication_style>Talks like a pulp super hero</communication_style>
+    <principles>Execute resources directly Load resources at runtime never pre-load Always present numbered lists for choices</principles>
+  </persona>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*audit-workflow" workflow="{project-root}/bmad/bmb/workflows/audit-workflow/workflow.yaml">Audit existing workflows for BMAD Core compliance and best practices</item>
+    <item cmd="*convert" workflow="{project-root}/bmad/bmb/workflows/convert-legacy/workflow.yaml">Convert v4 or any other style task agent or template to a workflow</item>
+    <item cmd="*create-agent" workflow="{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml">Create a new BMAD Core compliant agent</item>
+    <item cmd="*create-module" workflow="{project-root}/bmad/bmb/workflows/create-module/workflow.yaml">Create a complete BMAD module (brainstorm → brief → build with agents and workflows)</item>
+    <item cmd="*create-workflow" workflow="{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml">Create a new BMAD Core workflow with proper structure</item>
+    <item cmd="*edit-workflow" workflow="{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml">Edit existing workflows while following best practices</item>
+    <item cmd="*redoc" workflow="{project-root}/bmad/bmb/workflows/redoc/workflow.yaml">Create or update module documentation</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```

.claude/commands/bmad/bmb/workflows/README.md

@@ -0,0 +1,57 @@
+# BMB Workflows
+
+## Available Workflows in bmb
+
+**audit-workflow**
+
+- Path: `bmad/bmb/workflows/audit-workflow/workflow.yaml`
+- Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards.
+
+**convert-legacy**
+
+- Path: `bmad/bmb/workflows/convert-legacy/workflow.yaml`
+- Converts legacy BMAD v4 or similar items (agents, workflows, modules) to BMad Core compliant format with proper structure and conventions
+
+**create-agent**
+
+- Path: `bmad/bmb/workflows/create-agent/workflow.yaml`
+- Interactive workflow to build BMAD Core compliant agents (YAML source compiled to .md during install) with optional brainstorming, persona development, and command structure
+
+**create-module**
+
+- Path: `bmad/bmb/workflows/create-module/workflow.yaml`
+- Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure
+
+**create-workflow**
+
+- Path: `bmad/bmb/workflows/create-workflow/workflow.yaml`
+- Interactive workflow builder that guides creation of new BMAD workflows with proper structure and validation for optimal human-AI collaboration. Includes optional brainstorming phase for workflow ideas and design.
+
+**edit-workflow**
+
+- Path: `bmad/bmb/workflows/edit-workflow/workflow.yaml`
+- Edit existing BMAD workflows while following all best practices and conventions
+
+**module-brief**
+
+- Path: `bmad/bmb/workflows/module-brief/workflow.yaml`
+- Create a comprehensive Module Brief that serves as the blueprint for building new BMAD modules using strategic analysis and creative vision
+
+**redoc**
+
+- Path: `bmad/bmb/workflows/redoc/workflow.yaml`
+- Autonomous documentation system that maintains module, workflow, and agent documentation using a reverse-tree approach (leaf folders first, then parents). Understands BMAD conventions and produces technical writer quality output.
+
+## Execution
+
+When running any workflow:
+
+1. LOAD {project-root}/bmad/core/tasks/workflow.xml
+2. Pass the workflow path as 'workflow-config' parameter
+3. Follow workflow.xml instructions EXACTLY
+4. Save outputs after EACH section
+
+## Modes
+
+- Normal: Full interaction
+- #yolo: Skip optional steps

.claude/commands/bmad/bmb/workflows/audit-workflow.md

@@ -0,0 +1,11 @@
+# audit-workflow
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/audit-workflow/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/audit-workflow/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/bmb/workflows/convert-legacy.md

@@ -0,0 +1,11 @@
+# convert-legacy
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/convert-legacy/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/convert-legacy/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/bmb/workflows/create-agent.md

@@ -0,0 +1,11 @@
+# create-agent
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/create-agent/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/create-agent/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/bmb/workflows/create-module.md

@@ -0,0 +1,11 @@
+# create-module
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/create-module/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/create-module/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/bmb/workflows/create-workflow.md

@@ -0,0 +1,11 @@
+# create-workflow
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/create-workflow/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/create-workflow/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/bmb/workflows/edit-workflow.md

@@ -0,0 +1,11 @@
+# edit-workflow
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/edit-workflow/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/edit-workflow/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/bmb/workflows/module-brief.md

@@ -0,0 +1,11 @@
+# module-brief
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/module-brief/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/module-brief/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/bmb/workflows/redoc.md

@@ -0,0 +1,11 @@
+# redoc
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/redoc/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/redoc/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/core/agents/bmad-master.md

@@ -0,0 +1,68 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator
+
+```xml
+<agent id="bmad/core/agents/bmad-master.md" name="BMad Master" title="BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator" icon="🧙">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+      - Load and read {project-root}/bmad/core/config.yaml NOW
+      - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+      - VERIFY: If config not loaded, STOP and report error to user
+      - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+  <step n="4">Load into memory {project-root}/bmad/core/config.yaml and set variable project_name, output_folder, user_name, communication_language</step>
+  <step n="5">Remember the users name is {user_name}</step>
+  <step n="6">ALWAYS communicate in {communication_language}</step>
+  <step n="7">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of
+      ALL menu items from menu section</step>
+  <step n="8">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text</step>
+  <step n="9">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user
+      to clarify | No match → show "Not recognized"</step>
+  <step n="10">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item
+      (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+  <menu-handlers>
+      <handlers>
+      <handler type="action">
+        When menu item has: action="#id" → Find prompt with id="id" in current agent XML, execute its content
+        When menu item has: action="text" → Execute the text directly as an inline instruction
+      </handler>
+
+  <handler type="workflow">
+    When menu item has: workflow="path/to/workflow.yaml"
+    1. CRITICAL: Always LOAD {project-root}/bmad/core/tasks/workflow.xml
+    2. Read the complete file - this is the CORE OS for executing BMAD workflows
+    3. Pass the yaml path as 'workflow-config' parameter to those instructions
+    4. Execute workflow.xml instructions precisely following all steps
+    5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+    6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+  </handler>
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    - ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style
+    - Stay in character until exit selected
+    - Menu triggers use asterisk (*) - NOT markdown, display exactly as shown
+    - Number all lists, use letters for sub-options
+    - Load files ONLY when executing menu items or a workflow or command requires it. EXCEPTION: Config file MUST be loaded at startup step 2
+    - CRITICAL: Written File Output in workflows will be +2sd your communication style and use professional {communication_language}.
+  </rules>
+</activation>
+  <persona>
+    <role>Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator</role>
+    <identity>Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations.</identity>
+    <communication_style>Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability.</communication_style>
+    <principles>Load resources at runtime never pre-load, and always present numbered lists for choices.</principles>
+  </persona>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*list-tasks" action="list all tasks from {project-root}/bmad/_cfg/task-manifest.csv">List Available Tasks</item>
+    <item cmd="*list-workflows" action="list all workflows from {project-root}/bmad/_cfg/workflow-manifest.csv">List Workflows</item>
+    <item cmd="*party-mode" workflow="{project-root}/bmad/core/workflows/party-mode/workflow.yaml">Group chat with all agents</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```

.claude/commands/bmad/core/workflows/README.md

@@ -0,0 +1,27 @@
+# CORE Workflows
+
+## Available Workflows in core
+
+**brainstorming**
+
+- Path: `bmad/core/workflows/brainstorming/workflow.yaml`
+- Facilitate interactive brainstorming sessions using diverse creative techniques. This workflow facilitates interactive brainstorming sessions using diverse creative techniques. The session is highly interactive, with the AI acting as a facilitator to guide the user through various ideation methods to generate and refine creative solutions.
+
+**party-mode**
+
+- Path: `bmad/core/workflows/party-mode/workflow.yaml`
+- Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations
+
+## Execution
+
+When running any workflow:
+
+1. LOAD {project-root}/bmad/core/tasks/workflow.xml
+2. Pass the workflow path as 'workflow-config' parameter
+3. Follow workflow.xml instructions EXACTLY
+4. Save outputs after EACH section
+
+## Modes
+
+- Normal: Full interaction
+- #yolo: Skip optional steps

.claude/commands/bmad/core/workflows/brainstorming.md

@@ -0,0 +1,11 @@
+# brainstorming
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/core/workflows/brainstorming/workflow.yaml
+3. Pass the yaml path bmad/core/workflows/brainstorming/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/bmad/core/workflows/party-mode.md

@@ -0,0 +1,11 @@
+# party-mode
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/core/workflows/party-mode/workflow.yaml
+3. Pass the yaml path bmad/core/workflows/party-mode/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.github/workflows/lint.yaml

@@ -1,4 +1,4 @@
-name: format-check
+name: lint
 
 "on":
   pull_request:
@@ -41,3 +41,21 @@ jobs:
 
       - name: ESLint
         run: npm run lint
+
+  schema-validation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate YAML schemas
+        run: npm run validate:schemas

.gitignore

@@ -8,6 +8,7 @@ package-lock.json
 
 
 test-output/*
+coverage/
 
 # Logs
 logs/
@@ -25,7 +26,6 @@ build/*.txt
 Thumbs.db
 
 # Development tools and configs
-.prettierignore
 .prettierrc
 
 # IDE and editor configs
@@ -36,7 +36,6 @@ Thumbs.db
 # AI assistant files
 CLAUDE.md
 .ai/*
-.claude
 cursor
 .gemini
 .mcp.json

.prettierignore

@@ -0,0 +1,2 @@
+# Test fixtures with intentionally broken/malformed files
+test/fixtures/**

CONTRIBUTING.md

@@ -256,6 +256,7 @@ Each commit should represent one logical change:
 - Web/planning agents can be larger with more complex tasks
 - Everything is natural language (markdown) - no code in core framework
 - Use bmad modules for domain-specific features
+- Validate YAML schemas with `npm run validate:schemas` before committing
 
 ## Code of Conduct
 

README.md

@@ -253,8 +253,9 @@ What used to be tasks and create-doc templates are now all workflows! Simpler, y
 
 - [Workflow Creation Guide](src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md)
 
-### Installer Changes
+### Installer & Bundler Documentation
 
+- **[CLI Tool Guide](tools/cli/README.md)** - Complete guide to how the installer, bundler, and agent compilation system works
 - [IDE Injections](docs/installers-bundlers/ide-injections)
 - [Installers Modules Platforms References](docs/installers-bundlers/installers-modules-platforms-reference)
 - [Web Bundler Usage](docs/installers-bundlers/web-bundler-usage)

bmad/_cfg/files-manifest.csv

@@ -1,8 +1,8 @@
 type,name,module,path,hash
 "csv","agent-manifest","_cfg","bmad/_cfg/agent-manifest.csv","4d7fb4998ddad86011c22b5c579747d9247edeab75a92406c2b10e1bc40d3333"
 "csv","task-manifest","_cfg","bmad/_cfg/task-manifest.csv","46f98b1753914dc6193c9ca8b6427fadc9a6d71747cdc8f5159792576c004b60"
-"csv","workflow-manifest","_cfg","bmad/_cfg/workflow-manifest.csv","4454b7c724bab73c80f2e0d418151ad9734d38e42dd6cdd37e8958a6e23ef9d2"
-"yaml","manifest","_cfg","bmad/_cfg/manifest.yaml","207855799a32ea061836bd3f018426b90598090b43ee0367ce4e27e68a573830"
+"csv","workflow-manifest","_cfg","bmad/_cfg/workflow-manifest.csv","ad9ffffd019cbe86a43b1e1b9bec61ee08364060d81b507b219505397c62d1da"
+"yaml","manifest","_cfg","bmad/_cfg/manifest.yaml","fc21d1a017633c845a71e14e079d6da84b5aa096ddb9aacd10073f58c361efc6"
 "js","installer","bmb","bmad/bmb/workflows/create-module/installer-templates/installer.js","a539cd5266471dab9359bd3ed849d7b45c5de842a9d5869f8332a5a8bb81fad5"
 "md","agent-architecture","bmb","bmad/bmb/workflows/create-agent/agent-architecture.md","ea570cf9893c08d3b9519291c89848d550506a8d831a37eb87f60f1e09980e7f"
 "md","agent-command-patterns","bmb","bmad/bmb/workflows/create-agent/agent-command-patterns.md","1dbc414c0c6c9e6b54fb0553f65a28743a26e2a172c35b79fc3dc350d50a378d"
@@ -27,7 +27,7 @@ type,name,module,path,hash
 "md","instructions","bmb","bmad/bmb/workflows/create-module/instructions.md","5f321690f4774058516d3d65693224e759ec87d98d7a1a281b38222ab963ca8b"
 "md","instructions","bmb","bmad/bmb/workflows/create-workflow/instructions.md","d739389d9eb20e9297737a8cfca7a8bdc084c778b6512a2433442c651d0ea871"
 "md","instructions","bmb","bmad/bmb/workflows/create-workflow/workflow-template/instructions.md","daf3d312e5a60d7c4cbc308014e3c69eeeddd70bd41bd139d328318da1e3ecb2"
-"md","instructions","bmb","bmad/bmb/workflows/edit-workflow/instructions.md","d35f4b20fd8d22bff1374dfa1bee7aa037d5d097dd2e8763b3b2792fbef4a97d"
+"md","instructions","bmb","bmad/bmb/workflows/edit-workflow/instructions.md","a6f34e3117d086213b7b58eb4fa0d3c2d0af943e8d9299be4a9b91d4fd444f19"
 "md","instructions","bmb","bmad/bmb/workflows/module-brief/instructions.md","e2275373850ea0745f396ad0c3aa192f06081b52d98777650f6b645333b62926"
 "md","instructions","bmb","bmad/bmb/workflows/redoc/instructions.md","fccc798c8904c35807bb6a723650c10aa19ee74ab5a1e44d1b242bd125d3e80e"
 "md","module-structure","bmb","bmad/bmb/workflows/create-module/module-structure.md","9970768af75da79b4cdef78096c751e70a3a00194af58dca7ed58a79d324423f"
@@ -35,15 +35,15 @@ type,name,module,path,hash
 "md","README","bmb","bmad/bmb/workflows/convert-legacy/README.md","3391972c16b7234dae61b2d06daeb6310d1760117ece57abcca0c178c4c33eea"
 "md","README","bmb","bmad/bmb/workflows/create-agent/README.md","cc1d51e22c425e005ddbe285510ff5a6fc6cf1e40d0ffe5ff421c1efbcbe94c0"
 "md","README","bmb","bmad/bmb/workflows/create-module/README.md","cdacbe6c4896fd02714b598e709b785af38d41d7e42d39802d695617fe221b39"
-"md","README","bmb","bmad/bmb/workflows/create-workflow/README.md","56501b159b18e051ebcc78b4039ad614e44d172fe06dce679e9b24122a4929b5"
-"md","README","bmb","bmad/bmb/workflows/edit-workflow/README.md","2141d42d922701281d4d92e435d4690c462c53cf31e8307c87252f0cabec4987"
+"md","README","bmb","bmad/bmb/workflows/create-workflow/README.md","5b868030bf6fcb597bd3ff65bff30ccaf708b735ebb13bd0595fd8692258f425"
+"md","README","bmb","bmad/bmb/workflows/edit-workflow/README.md","a1c2da9b67d18ba9adc107be91e3d142ecb820b2054dd69d2538c9ceee9eb89a"
 "md","README","bmb","bmad/bmb/workflows/module-brief/README.md","05772db9095db7b4944e9fc47a049a3609c506be697537fd5fd9e409c10b92f4"
 "md","README","bmb","bmad/bmb/workflows/redoc/README.md","a1b7e02427cf252bca69a8a1ee0f554844a6a01b5d568d74f494c71542056173"
 "md","template","bmb","bmad/bmb/workflows/create-workflow/workflow-template/template.md","c98f65a122035b456f1cbb2df6ecaf06aa442746d93a29d1d0ed2fc9274a43ee"
 "md","template","bmb","bmad/bmb/workflows/module-brief/template.md","7d1ad5ec40b06510fcbb0a3da8ea32aefa493e5b04c3a2bba90ce5685b894275"
 "md","workflow-creation-guide","bmb","bmad/bmb/workflows/create-workflow/workflow-creation-guide.md","3233f2db6e0dec0250780840f95b38f7bfe9390b045a497d66f94f82d7ffb1af"
 "yaml","bmad-builder.agent","bmb","bmad/bmb/agents/bmad-builder.agent.yaml",""
-"yaml","config","bmb","bmad/bmb/config.yaml","55ef4a0fe98969c53d0e494bc4bf3f688704880dc8568b85860d57e785f9e7e5"
+"yaml","config","bmb","bmad/bmb/config.yaml","3baf3d7fee63f22959be86f2c310f3a4cc5afa748cd707e939ce3ee83745999f"
 "yaml","install-module-config","bmb","bmad/bmb/workflows/create-module/installer-templates/install-module-config.yaml","69c03628b04600f76aa1aa136094d59514f8eb900529114f7233dc28f2d5302d"
 "yaml","workflow","bmb","bmad/bmb/workflows/audit-workflow/workflow.yaml","5b8d26675e30d006f57631be2f42b00575b0d00f87abea408bf0afd09d73826e"
 "yaml","workflow","bmb","bmad/bmb/workflows/convert-legacy/workflow.yaml","c31cee9cc0d457b25954554d7620c7455b3f1b5aa5b5d72fbc765ea7902c3c0c"
@@ -57,7 +57,6 @@ type,name,module,path,hash
 "csv","adv-elicit-methods","core","bmad/core/tasks/adv-elicit-methods.csv","b4e925870f902862899f12934e617c3b4fe002d1b652c99922b30fa93482533b"
 "csv","brain-methods","core","bmad/core/workflows/brainstorming/brain-methods.csv","ecffe2f0ba263aac872b2d2c95a3f7b1556da2a980aa0edd3764ffb2f11889f3"
 "md","bmad-master","core","bmad/core/agents/bmad-master.md","d5a8f4c202e0637844b7c481c6b1284f4a8175017f070a23de849f53ead62625"
-"md","instructions","core","bmad/core/workflows/bmad-init/instructions.md","f4eff0e5f8c060126cb3027e3b0a343451ff25cd8fac28551e70281c3b16a5b2"
 "md","instructions","core","bmad/core/workflows/brainstorming/instructions.md","32961c158cf5c0575ff0aac6e6532ea177b824e96caddafa31223485df10bc4e"
 "md","instructions","core","bmad/core/workflows/party-mode/instructions.md","ea0e0e76de91d872efb3b4397627801452f21a39d094a77c41edc93f8dc4238b"
 "md","README","core","bmad/core/workflows/brainstorming/README.md","ca469d9fbb2b9156491d160e11e2517fdf85ea2c29f41f92b22d4027fe7d9d2a"
@@ -68,7 +67,6 @@ type,name,module,path,hash
 "xml","validate-workflow","core","bmad/core/tasks/validate-workflow.xml","1244874db38a55d957995ed224812ef868ff1451d8e1901cc5887dd0eb1c236e"
 "xml","workflow","core","bmad/core/tasks/workflow.xml","0b2b7bd184e099869174cc8d9125fce08bcd3fd64fad50ff835a42eccf6620e2"
 "yaml","bmad-master.agent","core","bmad/core/agents/bmad-master.agent.yaml",""
-"yaml","config","core","bmad/core/config.yaml","1095574525100a336cf6d6b87b759b756380c8ce4a595094320100e987b84ade"
-"yaml","workflow","core","bmad/core/workflows/bmad-init/workflow.yaml","731b408219111bd234ebf7a7e124fe2dcb3a428bcf74f8c307a9a2f58039ee97"
+"yaml","config","core","bmad/core/config.yaml","c5267c6e72f5d79344464082c2c73ddec88b7433705d38002993fe745c3cbe23"
 "yaml","workflow","core","bmad/core/workflows/brainstorming/workflow.yaml","52db57678606b98ec47e603c253c40f98815c49417df3088412bbbd8aa7f34d3"
 "yaml","workflow","core","bmad/core/workflows/party-mode/workflow.yaml","979e986780ce919abbdae89b3bd264d34a1436036a7eb6f82f40e59c9ce7c2e8"

bmad/_cfg/manifest.yaml

@@ -1,9 +1,10 @@
 installation:
   version: 6.0.0-alpha.0
-  installDate: "2025-10-16T23:11:41.904Z"
-  lastUpdated: "2025-10-16T23:11:41.904Z"
+  installDate: "2025-10-18T03:30:57.841Z"
+  lastUpdated: "2025-10-18T03:30:57.841Z"
 modules:
   - core
   - bmb
 ides:
   - claude-code
+  - codex

bmad/_cfg/workflow-manifest.csv

@@ -1,5 +1,4 @@
 name,description,module,path
-"bmad-init","BMAD system initialization and maintenance workflow for agent manifest generation and system configuration","core","bmad/core/workflows/bmad-init/workflow.yaml"
 "brainstorming","Facilitate interactive brainstorming sessions using diverse creative techniques. This workflow facilitates interactive brainstorming sessions using diverse creative techniques. The session is highly interactive, with the AI acting as a facilitator to guide the user through various ideation methods to generate and refine creative solutions.","core","bmad/core/workflows/brainstorming/workflow.yaml"
 "party-mode","Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations","core","bmad/core/workflows/party-mode/workflow.yaml"
 "audit-workflow","Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards.","bmb","bmad/bmb/workflows/audit-workflow/workflow.yaml"

bmad/bmb/config.yaml

@@ -1,7 +1,7 @@
 # BMB Module Configuration
 # Generated by BMAD installer
 # Version: 6.0.0-alpha.0
-# Date: 2025-10-16T23:11:41.900Z
+# Date: 2025-10-18T03:30:57.837Z
 
 custom_agent_location: "{project-root}/bmad/agents"
 custom_workflow_location: "{project-root}/bmad/workflows"

bmad/bmb/workflows/create-workflow/README.md

@@ -56,6 +56,67 @@ create-workflow/
     └── README.md
 ```
 
+## Understanding Instruction Styles
+
+One of the most important decisions when creating a workflow is choosing the **instruction style** - how the workflow guides the AI's interaction with users.
+
+### Intent-Based vs Prescriptive Instructions
+
+**Intent-Based (Recommended for most workflows)**
+
+Guides the LLM with goals and principles, allowing natural conversation adaptation.
+
+- **More flexible and conversational** - AI adapts questions to context
+- **Better for complex discovery** - Requirements gathering, creative exploration
+- **Quality over consistency** - Focus on deep understanding
+- **Example**: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**Best for:**
+
+- Complex discovery processes (user research, requirements)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- When adaptation to context matters
+- Workflows requiring nuanced understanding
+
+**Prescriptive**
+
+Provides exact wording for questions and structured options.
+
+- **More controlled and predictable** - Same questions every time
+- **Better for simple data collection** - Platform choices, yes/no decisions
+- **Consistency over quality** - Standardized execution
+- **Example**: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**Best for:**
+
+- Simple data collection (platform, format, binary choices)
+- Compliance verification and standards
+- Configuration with finite options
+- Quick setup wizards
+- When consistency is critical
+
+### Best Practice: Mix Both Styles
+
+The most effective workflows use **both styles strategically**:
+
+```xml
+<!-- Intent-based workflow with prescriptive moments -->
+<step n="1" goal="Understand user vision">
+  <action>Explore the user's vision, uncovering creative intent and target experience</action>
+</step>
+
+<step n="2" goal="Capture basic metadata">
+  <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>
+</step>
+
+<step n="3" goal="Deep dive into details">
+  <action>Guide user to articulate their core approach and unique aspects</action>
+</step>
+```
+
+**During workflow creation**, you'll be asked to choose a **primary style preference** - this sets the default approach, but you can (and should) use the other style when it makes more sense for specific steps.
+
 ## Workflow Process
 
 ### Phase 0: Optional Brainstorming (Step -1)

bmad/bmb/workflows/edit-workflow/README.md

@@ -43,8 +43,64 @@ Or through a BMAD agent:
 2. **Prioritized Issues**: Identifies and ranks issues by importance
 3. **Guided Editing**: Step-by-step process with explanations
 4. **Best Practices**: Ensures all edits follow BMAD conventions
-5. **Validation**: Checks all changes for correctness
-6. **Change Tracking**: Documents what was modified and why
+5. **Instruction Style Optimization**: Convert between intent-based and prescriptive styles
+6. **Validation**: Checks all changes for correctness
+7. **Change Tracking**: Documents what was modified and why
+
+## Understanding Instruction Styles
+
+When editing workflows, one powerful option is **adjusting the instruction style** to better match the workflow's purpose.
+
+### Intent-Based vs Prescriptive Instructions
+
+**Intent-Based (Recommended for most workflows)**
+
+Guides the AI with goals and principles, allowing flexible conversation.
+
+- **More flexible and conversational** - AI adapts to user responses
+- **Better for complex discovery** - Requirements gathering, creative exploration
+- **Quality over consistency** - Deep understanding matters more
+- **Example**: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**When to use:**
+
+- Complex discovery processes (user research, requirements)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- Workflows requiring nuanced understanding
+
+**Prescriptive**
+
+Provides exact questions with structured options.
+
+- **More controlled and predictable** - Consistent questions every time
+- **Better for simple data collection** - Platform, format, yes/no choices
+- **Consistency over quality** - Same execution every run
+- **Example**: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**When to use:**
+
+- Simple data collection (platform, format, binary choices)
+- Compliance verification and standards adherence
+- Configuration with finite options
+- Quick setup wizards
+
+### Edit Workflow's Style Adjustment Feature
+
+The **"Adjust instruction style"** editing option (menu option 11) helps you:
+
+1. **Analyze current style** - Identifies whether workflow is primarily intent-based or prescriptive
+2. **Convert between styles** - Transform prescriptive steps to intent-based (or vice versa)
+3. **Optimize the mix** - Intelligently recommend the best style for each step
+4. **Step-by-step control** - Review and decide on each step individually
+
+**Common scenarios:**
+
+- **Make workflow more conversational**: Convert rigid <ask> tags to flexible <action> tags for complex steps
+- **Make workflow more consistent**: Convert open-ended <action> tags to structured <ask> tags for simple data collection
+- **Balance both approaches**: Use intent-based for discovery, prescriptive for simple choices
+
+This feature is especially valuable when converting legacy workflows or adapting workflows for different use cases.
 
 ## Workflow Steps
 

bmad/bmb/workflows/edit-workflow/instructions.md

@@ -77,9 +77,10 @@ Present the editing menu to the user:
 8. **Configure web bundle** - Add/update web bundle for deployment
 9. **Remove bloat** - Delete unused yaml fields, duplicate values
 10. **Optimize for clarity** - Improve descriptions, add examples
-11. **Full review and update** - Comprehensive improvements across all files
+11. **Adjust instruction style** - Convert between intent-based and prescriptive styles
+12. **Full review and update** - Comprehensive improvements across all files
 
-<ask>Select an option (1-11) or describe a custom edit:</ask>
+<ask>Select an option (1-12) or describe a custom edit:</ask>
 </step>
 
 <step n="4" goal="Load relevant documentation">
@@ -127,7 +128,16 @@ date: system-generated
 <check>If fixing critical issues:</check>
 <action>Load the workflow execution engine documentation</action>
 <action>Verify all required elements are present</action>
-</step>
+
+<check>If adjusting instruction style (option 11):</check>
+<action>Analyze current instruction style in instructions.md:</action>
+
+- 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>
+  </step>
 
 <step n="5" goal="Perform edits" repeat="until-complete">
 Based on the selected focus area:
@@ -161,6 +171,127 @@ If updating existing web bundle:
 3. Remove any config dependencies
 4. Update file list with newly referenced files
 
+<check>If adjusting instruction style (option 11):</check>
+<action>Present current style analysis to user:</action>
+
+**Current Instruction Style Analysis:**
+
+- Current dominant style: {{detected_style}}
+- Intent-based elements: {{intent_count}}
+- Prescriptive elements: {{prescriptive_count}}
+
+**Understanding Intent-Based vs Prescriptive:**
+
+**1. Intent-Based (Recommended)** - Guide the LLM with goals and principles, let it adapt conversations naturally
+
+- More flexible and conversational
+- LLM chooses appropriate questions based on context
+- Better for complex discovery and iterative refinement
+- Example: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**2. Prescriptive** - Provide exact wording for questions and options
+
+- More controlled and predictable
+- Ensures consistency across runs
+- Better for simple data collection or specific compliance needs
+- Example: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**When to use Intent-Based:**
+
+- Complex discovery processes (user research, requirements gathering)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- When user input quality matters more than consistency
+- Workflows requiring adaptation to context
+
+**When to use Prescriptive:**
+
+- Simple data collection (platform, format, yes/no choices)
+- Compliance verification and standards adherence
+- Configuration with finite options
+- When consistency is critical across all executions
+- Quick setup wizards
+
+**Best Practice: Mix Both Styles**
+
+Even workflows with a primary style should use the other when appropriate. For example:
+
+```xml
+<!-- Intent-based workflow with prescriptive moments -->
+<step n="1" goal="Understand user vision">
+  <action>Explore the user's vision, uncovering their creative intent and target experience</action>
+</step>
+
+<step n="2" goal="Capture basic metadata">
+  <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask> <!-- Prescriptive for simple choice -->
+</step>
+
+<step n="3" goal="Deep dive into details">
+  <action>Guide user to articulate their approach, exploring mechanics and unique aspects</action> <!-- Back to intent-based -->
+</step>
+```
+
+<ask>What would you like to do?
+
+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
+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
+
+Select option (1-5):</ask>
+
+<action>Store user's style adjustment preference as {{style_adjustment_choice}}</action>
+
+<check>If choice is 1 (make more intent-based):</check>
+<action>Identify prescriptive <ask> tags that could be converted to intent-based <action> tags</action>
+<action>For each candidate conversion:
+
+- Show original prescriptive version
+- Suggest intent-based alternative focused on goals
+- Explain the benefit of the conversion
+- Ask for approval
+  </action>
+  <action>Apply approved conversions</action>
+
+<check>If choice is 2 (make more prescriptive):</check>
+<action>Identify open-ended <action> tags that could be converted to prescriptive <ask> tags</action>
+<action>For each candidate conversion:
+
+- Show original intent-based version
+- Suggest prescriptive alternative with specific options
+- Explain when prescriptive is better here
+- Ask for approval
+  </action>
+  <action>Apply approved conversions</action>
+
+<check>If choice is 3 (optimize mix):</check>
+<action>Analyze each step for complexity and purpose</action>
+<action>Recommend style for each step:
+
+- Simple data collection → Prescriptive
+- Complex discovery → Intent-based
+- Binary decisions → Prescriptive
+- Creative exploration → Intent-based
+- Standards/compliance → Prescriptive
+- Iterative refinement → Intent-based
+  </action>
+  <action>Show recommendations with reasoning</action>
+  <action>Apply approved optimizations</action>
+
+<check>If choice is 4 (review specific steps):</check>
+<action>Present each step one at a time</action>
+<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>If choice is 5 (cancel):</check>
+<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>
 <action>Generate the updated content following all conventions from the guide</action>

bmad/core/config.yaml

@@ -1,7 +1,7 @@
 # CORE Module Configuration
 # Generated by BMAD installer
 # Version: 6.0.0-alpha.0
-# Date: 2025-10-16T23:11:41.901Z
+# Date: 2025-10-18T03:30:57.838Z
 
 user_name: BMad
 communication_language: English

bmad/core/workflows/bmad-init/instructions.md

@@ -1,79 +0,0 @@
-# BMAD Init - System Initialization Instructions
-
-<workflow>
-
-<step n="1" goal="Welcome and Status Check">
-  <action>Display welcome banner with BMAD branding</action>
-  <action>Check for BMAD installation at {project-root}/bmad</action>
-  <check>If installation found:</check>
-    <action>Display current version from {project-root}/bmad/_cfg/manifest.yaml</action>
-    <action>Show installation date and status</action>
-  <check>If not found:</check>
-    <action>Display warning that BMAD is not installed</action>
-    <action>Suggest running the installer first</action>
-    <action>Exit workflow</action>
-  <action>Display formatted status summary:
-    ╔════════════════════════════════════════╗
-    ║         BMAD INITIALIZATION            ║
-    ╚════════════════════════════════════════╝
-
-    Status: [Installed/Not Found]
-    Location: {project-root}/bmad
-    Version: [from manifest]
-    Installed: [date from manifest]
-
-  </action>
-</step>
-
-<step n="2" goal="Present Initialization Options">
-  <action>Display available initialization and maintenance tasks</action>
-  <ask>Select an initialization task:
-
-    1. Customize Installed Agents and Agent Party (Coming Soon)
-       - Assign new names and personas to agents
-       - Create runtime agent variants
-       - NOTE: This can all be done manually, but doing it through here will be easier and also update the party-mode manifest
-
-    2. Verify Installation (Coming Soon)
-       - Check all files are properly installed
-       - Validate configurations
-
-    3. Exit
-
-    Please select an option (1-3).
-
-  </ask>
-</step>
-
-<step n="3" goal="Process User Selection">
-  <check>If user selected "1":</check>
-    <action>Display message: ⚠️ Installed Agent Auto Customization is coming soon.</action>
-    <<action>Return to step 2</action>
-
-<check>If user selected "2":</check>
-<action>Display message: ⚠️ Installation verification is coming soon.</action>
-<action>Return to step 2</action>
-
-<check>If user selected "3":</check>
-<action>Display message: Exiting BMAD Init. Thank you!</action>
-<goto step="5">Exit workflow</goto>
-</step>
-
-<step n="4" goal="Post-Task Options">
-  <action>Display completion status of the executed task</action>
-  <ask>Task completed successfully!
-
-Would you like to perform another initialization task? (y/n):</ask>
-<check>If user responds "y":</check>
-<goto step="2">Return to menu</goto>
-<check>If user responds "n":</check>
-<goto step="5">Exit workflow</goto>
-</step>
-
-<step n="5" goal="Exit Workflow">
-  <action>Display farewell message</action>
-  <action>Suggest user start a new context or clear context if needed</action>
-  <action>Exit workflow</action>
-</step>
-
-</workflow>

bmad/core/workflows/bmad-init/workflow.yaml

@@ -1,14 +0,0 @@
-# BMAD Init - System Initialization Workflow
-name: "bmad-init"
-description: "BMAD system initialization and maintenance workflow for agent manifest generation and system configuration"
-author: "BMad"
-
-# Critical variables
-config_source: "{project-root}/bmad/_cfg/manifest.yaml"
-date: system-generated
-
-# This is an action workflow - no template output
-template: false
-instructions: "{project-root}/bmad/core/workflows/bmad-init/instructions.md"
-
-web_bundle: false

bmad/docs/codex-instructions.md

@@ -0,0 +1,21 @@
+# BMAD Method - Codex Instructions
+
+## Activating Agents
+
+BMAD agents, tasks and workflows are installed as custom prompts in
+`$CODEX_HOME/prompts/bmad-*.md` files. If `CODEX_HOME` is not set, it
+defaults to `$HOME/.codex/`.
+
+### Examples
+
+```
+/bmad-bmm-agents-dev - Activate development agent
+/bmad-bmm-agents-architect - Activate architect agent
+/bmad-bmm-workflows-dev-story - Execute dev-story workflow
+```
+
+### Notes
+
+Prompts are autocompleted when you type /
+Agent remains active for the conversation
+Start a new conversation to switch agents

docs/testarch-file-review/audit-report-testarch-atdd-2025-10-16.md

@@ -1,449 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** testarch-atdd
-**Audit Date:** 2025-10-16
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Document workflow (has template)
-**Workflow Path:** `/Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/testarch/atdd`
-
----
-
-## Executive Summary
-
-**Overall Status:** ⚠️ CONCERNS - Moderate bloat detected, missing web_bundle configuration
-
-- Critical Issues: 1
-- Important Issues: 2
-- Cleanup Recommendations: 4
-
-**Key Findings:**
-
-1. ✅ Standard config block is correctly configured
-2. ✅ Document workflow correctly configured (has template file)
-3. ⚠️ **MODERATE BLOAT:** 19 variables defined with ~65% bloat (13 unused variables)
-4. ❌ No web_bundle configuration (critical for web deployment)
-5. ⚠️ Config variable usage missing
-6. ⚠️ Template integration likely broken (needs verification)
-
----
-
-## 1. Standard Config Block Validation
-
-### Required Variables Check
-
-✅ **Config Source Check:**
-
-- [x] `config_source` is defined: `"{project-root}/bmad/bmm/config.yaml"`
-- [x] Points to correct module config path (bmm)
-- [x] Uses {project-root} variable
-
-✅ **Standard Variables Check:**
-
-- [x] `output_folder` pulls from config_source: `"{config_source}:output_folder"`
-- [x] `user_name` pulls from config_source: `"{config_source}:user_name"`
-- [x] `communication_language` pulls from config_source: `"{config_source}:communication_language"`
-- [x] `date` is set to system-generated: `"system-generated"`
-
-**Status:** ✅ **PASS** - All standard config variables present and correctly configured
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### Variables Analysis
-
-**Total YAML fields analyzed:** 19 variables defined in workflow.yaml (excluding standard config block and metadata)
-
-**Files Present:**
-
-- ✅ workflow.yaml
-- ✅ instructions.md
-- ✅ checklist.md
-- ✅ atdd-checklist-template.md (template file for document workflow)
-- ✅ README.md
-
-**Workflow Type:** Document workflow (has `template: "{installed_path}/atdd-checklist-template.md"`)
-
-### Bloat Analysis:
-
-#### Category 1: Boolean Behavior Flags (12 variables - likely all apply unconditionally)
-
-Based on pattern observed in previous audits, these boolean flags likely have no effect:
-
-**Test Level Flags:**
-
-1. `include_component_tests: true` - Component tests likely always generated based on test_levels
-
-**ATDD Approach Flags (ALL should always be true for ATDD):** 2. `start_failing: true` - **CRITICAL:** ATDD _requires_ tests to fail initially (red phase) 3. `use_given_when_then: true` - BDD structure should always be used 4. `network_first: true` - Best practice should always be applied 5. `one_assertion_per_test: true` - Best practice should always be applied
-
-**Data/Fixtures Flags:** 6. `generate_factories: true` - Factories likely always generated 7. `generate_fixtures: true` - Fixtures likely always generated 8. `auto_cleanup: true` - Cleanup should always be required
-
-**Output Configuration Flags:** 9. `include_data_testids: true` - testids likely always included 10. `include_mock_requirements: true` - Mock requirements likely always documented
-
-**Advanced Options:** 11. `auto_load_knowledge: true` - Knowledge base likely always loaded 12. `share_with_dev: true` - DEV checklist likely always provided
-
-**Impact:** 12 boolean flags that likely create false impression of configurability.
-
-**CRITICAL INSIGHT:** For ATDD workflow, `start_failing: true` should NOT be a variable - it's the defining characteristic of ATDD! Tests MUST fail initially (red phase of TDD). Making this optional breaks the entire ATDD methodology.
-
-**Recommendation:** Remove ALL 12 boolean flags. ATDD has a specific methodology:
-
-- Tests MUST fail initially (red phase)
-- Tests MUST use BDD structure
-- Tests MUST use best practices (network-first, atomic, cleanup)
-- These aren't choices - they're requirements of ATDD
-
-#### Category 2: Empty Placeholders (2 variables)
-
-13. `story_file: ""` - Should use <ask> tag to elicit
-14. `test_framework: ""` - Auto-detected, empty placeholder unnecessary
-
-**Recommendation:** Remove. Use <ask> in instructions to get story file path. Auto-detect test_framework.
-
-#### Category 3: Redundant Output Path (1 variable)
-
-15. `output_checklist: "{output_folder}/atdd-checklist-{story_id}.md"` - Duplicates default_output_file
-
-**Recommendation:** Remove. Use default_output_file (which has same value).
-
-#### Category 4: Acceptable Variables (Keep These)
-
-1. **`test_dir: "{project-root}/tests"`** - KEEP (standard path)
-2. **`test_levels: "e2e,api,component"`** - KEEP (legitimate choice of test levels to generate)
-3. **`primary_level: "e2e"`** - KEEP (which level gets primary acceptance tests)
-4. **`default_output_file: "{output_folder}/atdd-checklist-{story_id}.md"`** - KEEP (output path)
-5. **`installed_path`, `instructions`, `validation`, `template`** - KEEP (standard workflow fields)
-
-**Total Variables Analyzed:** 19 variables
-**Legitimate Variables:** ~6 (test_dir, test_levels, primary_level, default_output_file + standard fields)
-**Bloat:** ~13 variables (68% bloat)
-
-**Status:** ⚠️ **CONCERNS** - Moderate bloat (68% of variables unused or should be hardcoded methodology requirements)
-
----
-
-## 3. Config Variable Usage
-
-### Communication Language Check:
-
-- ❌ **MISSING** - No "communicate in {communication_language}" pattern (pattern from previous audits)
-- Instructions likely do not reference communication_language variable
-- Severity: IMPORTANT
-
-### User Name Check:
-
-- ❌ **MISSING** - No {user_name} usage (pattern from previous audits)
-- No personalization likely present
-- Severity: MINOR (optional for this workflow type)
-
-### Output Folder Check:
-
-- ✅ **USED** - default_output_file uses {output_folder}
-- Properly integrated
-- Severity: N/A
-
-### Date Usage Check:
-
-- ✅ **AVAILABLE** - Date defined for potential use in template
-- Severity: N/A
-
-**Status:** ⚠️ **IMPORTANT** - Config variables not fully utilized (communication_language missing)
-
----
-
-## 4. Web Bundle Validation
-
-### Web Bundle Present: ❌ **NO**
-
-**Status:** ❌ **CRITICAL** - No web_bundle configuration found
-
-The workflow.yaml contains:
-
-```yaml
-web_bundle: false
-```
-
-This means the workflow is **NOT** configured for web deployment.
-
-**Missing web_bundle requirements:**
-
-- No web_bundle_files list
-- No existing_workflows mapping
-- No web deployment path configuration
-
-**Knowledge Fragment Dependencies (from auto_load_knowledge comment):**
-
-The workflow mentions loading knowledge fragments:
-
-- fixture-architecture
-- data-factories
-- component-tdd
-
-**Template File:**
-
-- atdd-checklist-template.md
-
-**Expected web_bundle structure:**
-
-```yaml
-web_bundle:
-  workflow_path: 'bmad/bmm/workflows/testarch/atdd/workflow.yaml'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/testarch/atdd/instructions.md'
-    - 'bmad/bmm/workflows/testarch/atdd/checklist.md'
-    - 'bmad/bmm/workflows/testarch/atdd/atdd-checklist-template.md'
-    - 'bmad/bmm/testarch/knowledge/fixture-architecture.md'
-    - 'bmad/bmm/testarch/knowledge/data-factories.md'
-    - 'bmad/bmm/testarch/knowledge/component-tdd.md'
-    - 'bmad/bmm/testarch/tea-index.csv'
-```
-
-**Impact:** This workflow cannot be bundled for web deployment without web_bundle configuration.
-
-**Severity:** CRITICAL (if web deployment is intended)
-
----
-
-## 5. Bloat Detection
-
-### Unused YAML Fields Analysis
-
-**Total YAML fields:** 19 variables (excluding standard config and metadata)
-**Used fields:** ~6 (32%)
-**Unused fields:** ~13 (68%)
-**Bloat percentage:** **68%**
-
-### Detailed Bloat Analysis:
-
-#### Category 1: ATDD Methodology Requirements (Should NOT Be Variables!)
-
-These 5 flags define core ATDD methodology and should NEVER be optional:
-
-1. **`start_failing: true`** - **CRITICAL:** ATDD _requires_ red phase!
-   - Tests MUST fail initially before implementation
-   - This is the "red" in red-green-refactor
-   - Making this optional breaks ATDD methodology
-
-2. **`use_given_when_then: true`** - BDD structure is ATDD standard
-3. **`network_first: true`** - Best practice should always apply
-4. **`one_assertion_per_test: true`** - Atomic design should always apply
-5. **`auto_cleanup: true`** - Cleanup should always be required
-
-**Recommendation:** Remove ALL 5. These are ATDD methodology requirements, not user choices.
-
-**Rationale:** Allowing users to set `start_failing: false` defeats the entire purpose of ATDD. The workflow name is literally "atdd" (Acceptance Test-Driven Development) - tests MUST fail initially!
-
-#### Category 2: Infrastructure Generation Flags (Always Generate)
-
-6. `include_component_tests: true` - Based on test_levels, not separate flag
-7. `generate_factories: true` - Always generate
-8. `generate_fixtures: true` - Always generate
-
-**Recommendation:** Remove. Always generate fixtures/factories for ATDD workflow.
-
-#### Category 3: Output Configuration Flags (Always Include)
-
-9. `include_data_testids: true` - Always include testids (best practice)
-10. `include_mock_requirements: true` - Always document mocks (best practice)
-
-**Recommendation:** Remove. Always include these in ATDD checklist.
-
-#### Category 4: Advanced Options (Always Apply)
-
-11. `auto_load_knowledge: true` - Always load knowledge base
-12. `share_with_dev: true` - Always share DEV checklist (that's the point!)
-
-**Recommendation:** Remove. These should always happen in ATDD workflow.
-
-#### Category 5: Empty Placeholders (2 variables)
-
-13. `story_file: ""`
-14. `test_framework: ""`
-
-**Recommendation:** Remove. Use <ask> for story_file, auto-detect test_framework.
-
-#### Category 6: Redundant Output Path (1 variable)
-
-15. `output_checklist: "{output_folder}/atdd-checklist-{story_id}.md"`
-
-**Recommendation:** Remove. Use default_output_file.
-
-#### Category 7: Keep (6 variables)
-
-1. `test_dir: "{project-root}/tests"` - KEEP
-2. `test_levels: "e2e,api,component"` - KEEP (choice of levels)
-3. `primary_level: "e2e"` - KEEP (which level is primary)
-4. `default_output_file: "{output_folder}/atdd-checklist-{story_id}.md"` - KEEP
-5. Standard fields (installed_path, instructions, validation, template) - KEEP
-
-**Total Bloat Items:** 13 of 19 variables (68%)
-
-**Bloat Percentage:** 68%
-**Cleanup Potential:** HIGH - Reducing variables from 19 to 6
-
-**After Cleanup, Only These Should Remain:**
-
-1. `test_dir: "{project-root}/tests"` - Standard path
-2. `test_levels: "e2e,api,component"` - Test levels to generate
-3. `primary_level: "e2e"` - Primary acceptance test level
-4. `default_output_file: "{output_folder}/atdd-checklist-{story_id}.md"` - Output path
-5. Standard fields (installed_path, instructions, validation, template)
-
----
-
-## 6. Template Variable Mapping
-
-**Workflow Type:** Document workflow (has template file)
-
-**Template File:** atdd-checklist-template.md
-
-**Status:** ⚠️ **LIKELY BROKEN** - Template integration needs verification
-
-**Expected Behavior:** Document workflows should:
-
-1. Have `<template-output>` tags in instructions.md
-2. Use `{{variable_name}}` format in template
-3. Map template variables to instruction outputs
-
-**Likely Issue (based on trace/test-review workflow pattern):**
-
-- Template likely uses `{UPPERCASE}` pattern instead of `{{lowercase}}`
-- Instructions likely lack `<template-output>` tags
-- Template/instruction integration likely broken
-
-**Recommendation:** Verify template integration. Either:
-
-1. Add `<template-output>` tags to instructions and convert template to `{{variable}}` format
-2. Remove template, set `template: false`, make this an action workflow
-
-**Severity:** IMPORTANT - Template integration likely non-functional
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-1. **Add web_bundle configuration**
-   - Add web_bundle block with all required files (instructions, checklist, template)
-   - Map knowledge fragments (fixture-architecture, data-factories, component-tdd)
-   - Include tea-index.csv for knowledge base access
-   - Enable web deployment capability
-   - Severity: CRITICAL
-   - Impact: Workflow cannot be deployed to web without this
-
-### Important (Address Soon)
-
-2. **Fix template integration**
-   - Verify template uses `{{variable}}` format (not `{UPPERCASE}`)
-   - Add `<template-output>` tags to instructions
-   - OR remove template and make this an action workflow
-   - Current hybrid state likely broken
-   - Severity: IMPORTANT
-   - Impact: Template not being populated
-
-3. **Add config variable usage in instructions**
-   - Add communication_language support for multilingual workflows
-   - Add greeting or summary using {user_name}
-   - Ensure proper integration with BMAD v6 config standards
-   - Severity: IMPORTANT
-   - Impact: Workflows not following BMAD v6 conventions
-
-### Cleanup (Nice to Have)
-
-4. **Remove ATDD methodology flags (CRITICAL FOR METHODOLOGY INTEGRITY!)**
-   - Delete: start_failing, use_given_when_then, network_first, one_assertion_per_test, auto_cleanup
-   - **RATIONALE:** These are ATDD methodology _requirements_, not user choices
-   - `start_failing: true` is the CORE of ATDD! Tests MUST fail initially (red phase)
-   - Allowing users to disable these breaks ATDD methodology
-   - Hardcode these requirements in instructions
-   - Severity: CLEANUP (but IMPORTANT for methodology correctness!)
-   - Impact: Prevents users from breaking ATDD workflow, ensures methodology integrity
-
-5. **Remove infrastructure/output flags (7 variables)**
-   - Delete: include_component_tests, generate_factories, generate_fixtures, include_data_testids, include_mock_requirements, auto_load_knowledge, share_with_dev
-   - All of these should always happen in ATDD workflow
-   - Severity: CLEANUP
-   - Impact: Reduces bloat from 68% to ~5%
-
-6. **Remove empty placeholders and redundant paths**
-   - Delete: story_file, test_framework (use <ask> and auto-detect)
-   - Delete: output_checklist (use default_output_file)
-   - Severity: CLEANUP
-   - Impact: Cleaner configuration
-
-7. **Simplify to essential variables**
-   - Keep only: test_dir, test_levels, primary_level, default_output_file + standard fields
-   - Result: 19 variables → 6 variables (68% reduction)
-   - Severity: CLEANUP
-   - Impact: Clear, focused ATDD workflow
-
----
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
-- [x] All standard config variables present and correct ✅ (Already passing)
-- [ ] No unused yaml fields (bloat removed to <20%)
-- [ ] Config variables used appropriately in instructions
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped (or template removed)
-- [x] File structure follows v6 conventions ✅
-- [ ] Variables block reduced from 19 to 6 essential variables
-- [ ] ATDD methodology flags removed (start_failing hardcoded as true!)
-- [ ] Infrastructure/output flags removed (always generated)
-- [ ] Empty placeholders removed (<ask> tags added)
-- [x] Document workflow correctly configured (has template) ✅
-
----
-
-## Next Steps
-
-1. **Review critical issues** and fix web_bundle configuration immediately
-2. **Address important issues** in next iteration (template integration, config usage)
-3. **Consider cleanup recommendations** for optimization (bloat removal + methodology integrity)
-4. **Re-run audit** after fixes to verify improvements
-
-**Estimated Cleanup Impact:**
-
-- Variables: 19 → 6 (68% reduction)
-- Bloat: 68% → 0%
-- Maintainability: Significantly improved
-- Methodology Integrity: Ensured (can't disable ATDD requirements!)
-- Web deployment: Enabled (after web_bundle added)
-
----
-
-## Positive Observations
-
-**What This Workflow Does Well:**
-
-1. ✅ **Proper ATDD Methodology**
-   - Generates failing tests (red phase)
-   - BDD structure (Given-When-Then)
-   - Shares checklist with DEV agent
-   - Red-green-refactor cycle
-
-2. ✅ **Good Test Level Flexibility**
-   - test_levels choice (e2e, api, component)
-   - primary_level configuration
-   - Allows appropriate test distribution
-
-3. ✅ **Proper Document Workflow Structure**
-   - Has template file (atdd-checklist-template.md)
-   - Configured as document workflow
-   - Clear output path
-
-4. ✅ **Knowledge Base Integration**
-   - References tea-index.csv
-   - Loads relevant knowledge fragments
-   - Applies ATDD patterns
-
-**Overall:** This is a well-designed ATDD workflow with good methodology but moderate bloat. The CRITICAL issue is `start_failing: true` being a variable - this should NEVER be optional! ATDD _requires_ tests to fail initially. The other boolean flags also represent ATDD methodology requirements, not user choices. Removing bloat and hardcoding methodology requirements would make this an excellent workflow.
-
-**The ATDD Methodology Violation:** Making `start_failing` a configurable variable defeats the entire purpose of ATDD. The workflow name is "atdd" (Acceptance Test-Driven Development) - tests MUST fail initially! This is the "red" in red-green-refactor. Allowing `start_failing: false` breaks the methodology.
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0

docs/testarch-file-review/audit-report-testarch-automate-2025-10-16.md

@@ -1,445 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** testarch-automate
-**Audit Date:** 2025-10-16
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Action workflow (template: false)
-**Workflow Path:** `/Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/testarch/automate`
-
----
-
-## Executive Summary
-
-**Overall Status:** ⚠️ CONCERNS - Extreme bloat detected, missing web_bundle configuration
-
-- Critical Issues: 1
-- Important Issues: 1
-- Cleanup Recommendations: 4
-
-**Key Findings:**
-
-1. ✅ Standard config block is correctly configured
-2. ✅ Action workflow correctly configured (template: false)
-3. ❌ **EXTREME BLOAT:** 34 variables defined with ~85% bloat (29 unused variables!)
-4. ❌ No web_bundle configuration (critical for web deployment)
-5. ⚠️ Config variable usage missing
-6. 🏆 **NEW BLOAT CHAMPION:** 85% bloat (highest of all audited workflows!)
-
----
-
-## 1. Standard Config Block Validation
-
-### Required Variables Check
-
-✅ **Config Source Check:**
-
-- [x] `config_source` is defined: `"{project-root}/bmad/bmm/config.yaml"`
-- [x] Points to correct module config path (bmm)
-- [x] Uses {project-root} variable
-
-✅ **Standard Variables Check:**
-
-- [x] `output_folder` pulls from config_source: `"{config_source}:output_folder"`
-- [x] `user_name` pulls from config_source: `"{config_source}:user_name"`
-- [x] `communication_language` pulls from config_source: `"{config_source}:communication_language"`
-- [x] `date` is set to system-generated: `"system-generated"`
-
-**Status:** ✅ **PASS** - All standard config variables present and correctly configured
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### Variables Analysis
-
-**Total YAML fields analyzed:** 34 variables defined in workflow.yaml (excluding standard config block and metadata)
-
-**Files Present:**
-
-- ✅ workflow.yaml
-- ✅ instructions.md
-- ✅ checklist.md
-- ✅ README.md
-- ❌ No template file (correct - template: false)
-
-**Workflow Type:** Action workflow (template: false)
-
-### EXTREME BLOAT DETECTED - NEW CHAMPION!
-
-#### Category 1: Boolean Behavior Flags (26 variables - all generate outputs unconditionally!)
-
-The workflow defines **26 boolean/configuration flags** that have NO effect on workflow execution. Based on patterns from previous audits, these all likely generate unconditionally:
-
-**Discovery/Analysis Flags:**
-
-1. `auto_discover_features: true` - Auto-discovery likely always attempted
-2. `analyze_coverage: true` - Coverage analysis likely always performed
-3. `avoid_duplicate_coverage: true` - Duplicate check likely always performed
-
-**Test Priority Flags:** 4. `include_p0: true` - All priorities likely always considered 5. `include_p1: true` - Same 6. `include_p2: true` - Same 7. `include_p3: false` - Same
-
-**Test Design Principle Flags:** 8. `use_given_when_then: true` - BDD structure likely always used 9. `one_assertion_per_test: true` - Best practice likely always applied 10. `network_first: true` - Network-first likely always applied 11. `deterministic_waits: true` - Deterministic waits likely always used
-
-**Infrastructure Generation Flags:** 12. `generate_fixtures: true` - Fixtures likely always generated 13. `generate_factories: true` - Factories likely always generated 14. `update_helpers: true` - Helpers likely always updated
-
-**BMad Integration Flags:** 15. `use_test_design: true` - Auto-loading likely default 16. `use_tech_spec: true` - Auto-loading likely default 17. `use_prd: true` - Auto-loading likely default
-
-**Output Configuration Flags:** 18. `update_readme: true` - README likely always updated 19. `update_package_scripts: true` - Scripts likely always updated
-
-**Quality Gate Values:** 20. `max_test_duration: 90` - Hardcoded in instructions 21. `max_file_lines: 300` - Hardcoded in instructions 22. `require_self_cleaning: true` - Always required
-
-**Advanced Option Flags:** 23. `auto_load_knowledge: true` - Knowledge base likely always loaded 24. `run_tests_after_generation: true` - Tests likely always validated 25. `auto_validate: true` - Validation likely always performed
-
-**Mode Flag:** 26. `standalone_mode: true` - Workflow behavior mode
-
-**Impact:** 26 boolean/config variables that create false impression of configurability when all features are likely always generated.
-
-**Recommendation:** Remove 24 of 26 flags. Keep only:
-
-- `standalone_mode: true` - Legitimate mode choice (with/without BMad artifacts)
-- `coverage_target: "critical-paths"` - Legitimate choice (critical-paths, comprehensive, selective)
-
-#### Category 2: Empty Placeholders (3 variables)
-
-27. `story_file: ""` - Should use <ask> if needed
-28. `target_feature: ""` - Should use <ask>
-29. `target_files: ""` - Should use <ask>
-
-**Recommendation:** Remove. Use <ask> tags in instructions to elicit these inputs.
-
-#### Category 3: Comma-Separated List Config (1 variable)
-
-30. `test_levels: "e2e,api,component,unit"` - Hardcoded list
-
-**Recommendation:** Keep or consolidate with coverage_target. If workflow always generates all levels, remove.
-
-#### Category 4: Redundant Output Path (1 variable)
-
-31. `output_summary: "{output_folder}/automation-summary.md"` - Duplicates default_output_file
-
-**Recommendation:** Remove. Use default_output_file.
-
-#### Category 5: Acceptable Variables (Keep These)
-
-1. **`standalone_mode: true`** - KEEP (legitimate mode: BMad-integrated vs standalone)
-2. **`coverage_target: "critical-paths"`** - KEEP (legitimate choice: critical-paths, comprehensive, selective)
-3. **`test_levels: "e2e,api,component,unit"`** - MAYBE KEEP (if this varies by use case)
-4. **`test_dir: "{project-root}/tests"`** - KEEP (standard path)
-5. **`source_dir: "{project-root}/src"`** - KEEP (standard path)
-6. **`default_output_file: "{output_folder}/automation-summary.md"`** - KEEP (output path)
-7. **`installed_path`, `instructions`, `validation`** - KEEP (standard workflow fields)
-
-**Total Variables Analyzed:** 34 variables
-**Legitimate Variables:** ~5-7 (standalone_mode, coverage_target, test_levels?, test_dir, source_dir, default_output_file + standard fields)
-**Bloat:** ~27-29 variables (79-85% bloat!)
-
-**Status:** ❌ **FAIL** - EXTREME bloat (85% of variables unused - HIGHEST BLOAT OF ALL WORKFLOWS!)
-
----
-
-## 3. Config Variable Usage
-
-### Communication Language Check:
-
-- ❌ **MISSING** - No "communicate in {communication_language}" pattern (pattern from previous audits)
-- Instructions likely do not reference communication_language variable
-- Severity: IMPORTANT
-
-### User Name Check:
-
-- ❌ **MISSING** - No {user_name} usage (pattern from previous audits)
-- No personalization likely present
-- Severity: MINOR (optional for this workflow type)
-
-### Output Folder Check:
-
-- ✅ **USED** - default_output_file uses {output_folder}
-- Properly integrated
-- Severity: N/A
-
-### Date Usage Check:
-
-- ✅ **AVAILABLE** - Date defined for potential use
-- Severity: N/A
-
-**Status:** ⚠️ **IMPORTANT** - Config variables not fully utilized (communication_language missing)
-
----
-
-## 4. Web Bundle Validation
-
-### Web Bundle Present: ❌ **NO**
-
-**Status:** ❌ **CRITICAL** - No web_bundle configuration found
-
-The workflow.yaml contains:
-
-```yaml
-web_bundle: false
-```
-
-This means the workflow is **NOT** configured for web deployment.
-
-**Missing web_bundle requirements:**
-
-- No web_bundle_files list
-- No existing_workflows mapping
-- No web deployment path configuration
-
-**Knowledge Base References (from auto_load_knowledge comment):**
-
-The workflow mentions loading knowledge fragments:
-
-- test-levels (framework)
-- test-priorities (matrix)
-- fixture-architecture
-- selective-testing
-- ci-burn-in
-
-**Expected web_bundle structure:**
-
-```yaml
-web_bundle:
-  workflow_path: 'bmad/bmm/workflows/testarch/automate/workflow.yaml'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/testarch/automate/instructions.md'
-    - 'bmad/bmm/workflows/testarch/automate/checklist.md'
-    - 'bmad/bmm/testarch/knowledge/test-levels-framework.md'
-    - 'bmad/bmm/testarch/knowledge/test-priorities-matrix.md'
-    - 'bmad/bmm/testarch/knowledge/fixture-architecture.md'
-    - 'bmad/bmm/testarch/knowledge/selective-testing.md'
-    - 'bmad/bmm/testarch/knowledge/ci-burn-in.md'
-    - 'bmad/bmm/testarch/tea-index.csv'
-```
-
-**Impact:** This workflow cannot be bundled for web deployment without web_bundle configuration.
-
-**Severity:** CRITICAL (if web deployment is intended)
-
----
-
-## 5. Bloat Detection
-
-### Unused YAML Fields Analysis
-
-**Total YAML fields:** 34 variables (excluding standard config and metadata)
-**Used fields:** ~5-7 (15-21%)
-**Unused fields:** ~27-29 (79-85%)
-**Bloat percentage:** **85%** 🏆 **NEW BLOAT CHAMPION!**
-
-### Detailed Bloat Analysis:
-
-#### Category 1: Boolean Behavior Flags That Should Be Removed (24 variables)
-
-These should ALL be removed because they're workflow best practices, not user choices:
-
-**Discovery/Analysis (3 flags):**
-
-1. `auto_discover_features: true` - Always do this
-2. `analyze_coverage: true` - Always do this
-3. `avoid_duplicate_coverage: true` - Always do this
-
-**Test Priority Includes (4 flags):**
-4-7. `include_p0/p1/p2/p3` - Workflow should generate appropriate mix based on coverage_target, not individual flags
-
-**Test Design Principles (4 flags):** 8. `use_given_when_then: true` - Always use BDD (best practice) 9. `one_assertion_per_test: true` - Always atomic (best practice) 10. `network_first: true` - Always network-first (best practice) 11. `deterministic_waits: true` - Always deterministic (best practice)
-
-**Infrastructure Generation (3 flags):** 12. `generate_fixtures: true` - Always generate fixtures 13. `generate_factories: true` - Always generate factories 14. `update_helpers: true` - Always update helpers
-
-**BMad Integration (3 flags):** 15. `use_test_design: true` - Auto-load if exists 16. `use_tech_spec: true` - Auto-load if exists 17. `use_prd: true` - Auto-load if exists
-
-**Output Configuration (2 flags):** 18. `update_readme: true` - Always update 19. `update_package_scripts: true` - Always update
-
-**Quality Gates (3 values - hardcoded in instructions):** 20. `max_test_duration: 90` - Hardcoded value 21. `max_file_lines: 300` - Hardcoded value 22. `require_self_cleaning: true` - Always required
-
-**Advanced Options (3 flags):** 23. `auto_load_knowledge: true` - Always load knowledge 24. `run_tests_after_generation: true` - Always validate 25. `auto_validate: true` - Always validate
-
-**Recommendation:** Remove ALL 24 flags. These are best practices that should always be applied, not user choices.
-
-**Rationale:** An automation workflow should generate high-quality, production-ready tests using best practices. Allowing users to disable best practices (like deterministic waits, self-cleaning, validation) defeats the purpose.
-
-#### Category 2: Empty Placeholders (3 variables)
-
-26. `story_file: ""`
-27. `target_feature: ""`
-28. `target_files: ""`
-
-**Recommendation:** Remove. Use <ask> tags in instructions.
-
-#### Category 3: Redundant Output Path (1 variable)
-
-29. `output_summary: "{output_folder}/automation-summary.md"`
-
-**Recommendation:** Remove. Use default_output_file.
-
-#### Category 4: Possibly Redundant List Config (1 variable)
-
-30. `test_levels: "e2e,api,component,unit"`
-
-**Recommendation:** If workflow always generates all levels, remove. If this varies (e.g., "e2e,unit" for quick coverage), keep.
-
-#### Category 5: Keep (5-7 variables)
-
-1. `standalone_mode: true` - KEEP (real mode choice)
-2. `coverage_target: "critical-paths"` - KEEP (real coverage strategy choice)
-3. `test_levels: "e2e,api,component,unit"` - MAYBE KEEP
-4. `test_dir: "{project-root}/tests"` - KEEP
-5. `source_dir: "{project-root}/src"` - KEEP
-6. `default_output_file: "{output_folder}/automation-summary.md"` - KEEP
-7. Standard fields (installed_path, instructions, validation) - KEEP
-
-**Total Bloat Items:** 27-29 of 34 variables (79-85%)
-
-**Bloat Percentage:** **85%** 🏆 **CHAMPION**
-**Cleanup Potential:** EXTREME - Reducing variables from 34 to 5-7
-
-**After Cleanup, Only These Should Remain:**
-
-1. `standalone_mode: true` - Mode choice
-2. `coverage_target: "critical-paths"` - Coverage strategy
-3. `test_levels: "e2e,api,component,unit"` - Test levels (if needed)
-4. `test_dir: "{project-root}/tests"` - Standard path
-5. `source_dir: "{project-root}/src"` - Standard path
-6. `default_output_file: "{output_folder}/automation-summary.md"` - Output path
-7. Standard fields (installed_path, instructions, validation)
-
----
-
-## 6. Template Variable Mapping
-
-**Workflow Type:** Action workflow (template: false)
-
-**Template File:** None (correct)
-
-**<template-output> Tags:** None (correct for action workflow)
-
-**Status:** ✅ **N/A** - Action workflow correctly configured without template
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-1. **Add web_bundle configuration**
-   - Add web_bundle block with all required files (instructions, checklist)
-   - Map knowledge fragments (test-levels, test-priorities, fixture-architecture, selective-testing, ci-burn-in)
-   - Include tea-index.csv for knowledge base access
-   - Enable web deployment capability
-   - Severity: CRITICAL
-   - Impact: Workflow cannot be deployed to web without this
-
-### Important (Address Soon)
-
-2. **Add config variable usage in instructions**
-   - Add communication_language support for multilingual workflows
-   - Add greeting or summary using {user_name}
-   - Ensure proper integration with BMAD v6 config standards
-   - Severity: IMPORTANT
-   - Impact: Workflows not following BMAD v6 conventions
-
-### Cleanup (Nice to Have)
-
-3. **Remove MASSIVE bloat (27-29 variables!)**
-   - Delete 24 boolean flags (all best practices that should always be applied)
-   - Delete 3 empty placeholders (use <ask> tags instead)
-   - Delete 1 redundant output path
-   - Possibly delete test_levels if always all levels
-   - **Rationale:** Automation workflow should ALWAYS apply best practices (BDD, deterministic, self-cleaning, validated)
-   - Allowing users to disable best practices defeats the purpose
-   - Severity: CLEANUP
-   - Impact: Reduces bloat from 85% to ~0%, dramatically improves clarity
-
-4. **Simplify to minimal essential variables**
-   - Keep only: standalone_mode, coverage_target, test_levels (maybe), test_dir, source_dir, default_output_file
-   - Result: 34 variables → 5-7 variables (80-85% reduction!)
-   - Severity: CLEANUP
-   - Impact: Clearest, most maintainable workflow config
-
-5. **Consolidate test priority flags**
-   - Remove: include_p0, include_p1, include_p2, include_p3
-   - Use: coverage_target to determine priority mix
-     - "critical-paths" → P0 + some P1
-     - "comprehensive" → P0 + P1 + P2
-     - "selective" → P0 only
-   - Severity: CLEANUP
-   - Impact: Simpler configuration, clearer intent
-
-6. **Add <ask> for required inputs**
-   - Remove: story_file, target_feature, target_files placeholders
-   - Add in instructions: <ask> tags to elicit target specification
-   - Severity: CLEANUP
-   - Impact: Dynamic input gathering, no empty variables
-
----
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
-- [x] All standard config variables present and correct ✅ (Already passing)
-- [ ] No unused yaml fields (bloat removed to <20%)
-- [ ] Config variables used appropriately in instructions
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped (N/A - action workflow) ✅
-- [x] File structure follows v6 conventions ✅
-- [ ] Variables block reduced from 34 to 5-7 essential variables
-- [ ] All 24 boolean best-practice flags removed
-- [ ] Empty placeholders removed (<ask> tags added)
-- [x] Action workflow correctly configured (template: false) ✅
-
----
-
-## Next Steps
-
-1. **Review critical issues** and fix web_bundle configuration immediately
-2. **Address important issues** in next iteration (config usage)
-3. **Consider cleanup recommendations** for optimization (EXTREME bloat removal - 85%!)
-4. **Re-run audit** after fixes to verify improvements
-
-**Estimated Cleanup Impact:**
-
-- Variables: 34 → 5-7 (80-85% reduction - HIGHEST!)
-- Bloat: 85% → 0%
-- Maintainability: Dramatically improved
-- Clarity: Crystal clear (opinionated best-practice automation vs false configurability)
-- Web deployment: Enabled (after web_bundle added)
-
----
-
-## Positive Observations
-
-**What This Workflow Does Well:**
-
-1. ✅ **Dual Mode Support**
-   - standalone_mode: Works with or without BMad artifacts
-   - Flexible integration
-
-2. ✅ **Comprehensive Best Practices**
-   - BDD structure (Given-When-Then)
-   - Network-first testing
-   - Deterministic waits
-   - Self-cleaning tests
-   - Fixture architecture
-   - Data factories
-   - Test validation
-
-3. ✅ **Proper Action Workflow Structure**
-   - template: false (explicit)
-   - Generates tests directly
-   - Clear deliverables
-
-4. ✅ **Knowledge Base Integration**
-   - References tea-index.csv
-   - Loads relevant knowledge fragments
-   - Applies production patterns
-
-**Overall:** This is a well-designed workflow with excellent best practices but **EXTREME bloat** (85% - highest of all audited workflows!). The 24 boolean flags create false impression that best practices are optional, when they should ALWAYS be applied. Removing bloat would make this an exceptional workflow.
-
-**The Automation Paradox:** An automation workflow should ALWAYS generate high-quality tests using best practices. The 24 boolean flags suggest users can disable BDD, deterministic waits, validation, etc. - defeating the entire purpose of automated test generation. The instructions likely ignore these flags and apply all best practices anyway.
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0
-
-🏆 **BLOAT CHAMPION:** 85% bloat (29 of 34 variables unused!)

docs/testarch-file-review/audit-report-testarch-ci-2025-10-16.md

@@ -1,455 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** testarch-ci
-**Audit Date:** 2025-10-16
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Action workflow (no template)
-**Workflow Path:** `/Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/testarch/ci`
-
----
-
-## Executive Summary
-
-**Overall Status:** ⚠️ CONCERNS - Significant bloat detected, missing web_bundle configuration
-
-- Critical Issues: 1
-- Important Issues: 1
-- Cleanup Recommendations: 5
-
-**Key Findings:**
-
-1. ✅ Standard config block is correctly configured
-2. ✅ Action workflow correctly configured (no template)
-3. ✅ Excellent instructions with good CI/CD best practices
-4. ❌ **SEVERE BLOAT:** 28 variables defined with ~75% bloat (21 unused variables!)
-5. ❌ No web_bundle configuration (critical for web deployment)
-6. ⚠️ Config variable usage missing
-
----
-
-## 1. Standard Config Block Validation
-
-### Required Variables Check
-
-✅ **Config Source Check:**
-
-- [x] `config_source` is defined: `"{project-root}/bmad/bmm/config.yaml"`
-- [x] Points to correct module config path (bmm)
-- [x] Uses {project-root} variable
-
-✅ **Standard Variables Check:**
-
-- [x] `output_folder` pulls from config_source: `"{config_source}:output_folder"`
-- [x] `user_name` pulls from config_source: `"{config_source}:user_name"`
-- [x] `communication_language` pulls from config_source: `"{config_source}:communication_language"`
-- [x] `date` is set to system-generated: `"system-generated"`
-
-**Status:** ✅ **PASS** - All standard config variables present and correctly configured
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### Variables Analysis
-
-**Total YAML fields analyzed:** 28 variables defined in workflow.yaml (excluding standard config block and metadata)
-
-**Files Present:**
-
-- ✅ workflow.yaml
-- ✅ instructions.md
-- ✅ checklist.md
-- ✅ github-actions-template.yaml (template artifact, not workflow template)
-- ✅ gitlab-ci-template.yaml (template artifact, not workflow template)
-- ❌ No workflow template file (correct for action workflow)
-
-**Workflow Type:** Action workflow (no template field for workflow itself)
-
-### Categorization:
-
-#### INSTRUCTION_USED (Variables referenced in instructions.md):
-
-**Contextually referenced:**
-
-- ci_platform - Platform detection logic
-- test_framework - Mentioned in preflight
-- test_dir - Test directory location
-- node_version_source - Node version from .nvmrc
-- Some configuration values mentioned conceptually (sharding, burn-in, etc.)
-
-**Output path used:**
-
-- default_output_file: "{project-root}/.github/workflows/test.yml"
-
-#### MASSIVE BLOAT DETECTED:
-
-**Category 1: Boolean Behavior Flags (18 variables - all generate outputs unconditionally!)**
-
-The workflow defines 18 boolean/configuration flags that have NO effect on workflow execution. The instructions generate ALL artifacts and features unconditionally:
-
-1. **`parallel_jobs: 4`** - Instructions always configure 4 shards (Step 2.3)
-2. **`burn_in_enabled: true`** - Instructions always add burn-in loop (Step 2.4)
-3. **`burn_in_iterations: 10`** - Hardcoded as 10 in instructions
-4. **`selective_testing_enabled: true`** - Always generated (Step 2.9 scripts)
-5. **`artifact_retention_days: 30`** - Hardcoded in instructions
-6. **`upload_artifacts_on: "failure"`** - Always "failure" in instructions
-7. **`artifact_types: "traces,screenshots,videos,html-report"`** - All types always included
-8. **`cache_enabled: true`** - Caching always configured (Step 2.5)
-9. **`browser_cache_enabled: true`** - Browser cache always configured
-10. **`timeout_minutes: 60`** - Hardcoded timeouts in instructions
-11. **`test_timeout_minutes: 30`** - Hardcoded in instructions
-12. **`notify_on_failure: false`** - Instructions show notification example (Step 2.8) regardless
-13. **`notification_channels: ""`** - Empty, not used
-14. **`generate_ci_readme: true`** - Always generated (Step 2.10)
-15. **`generate_local_mirror_script: true`** - Always generated (Step 2.9)
-16. **`generate_secrets_checklist: true`** - Always generated (Step 2.10)
-17. **`use_matrix_strategy: true`** - Always used in templates
-18. **`use_sharding: true`** - Always used in templates
-19. **`retry_failed_tests: true`** - Always configured (Step 2.7)
-20. **`retry_count: 2`** - Hardcoded in instructions
-
-**Impact:** 20 variables that create false impression of configurability when ALL features are always generated.
-
-**Category 2: Empty Placeholders (2 variables - should be elicited)**
-
-21. **`test_framework: ""`** - Auto-detected in Step 1.2, empty placeholder unnecessary
-22. **`config_file: ""`** - Derived from framework detection, should be calculated
-
-**Category 3: Derived Paths (1 variable)**
-
-23. **`node_version_source: "{project-root}/.nvmrc"`** - Always reads .nvmrc, variable adds no value
-
-**Total Variables Analyzed:** 28 variables
-**Used in Instructions:** ~7 (ci_platform, test_dir, default_output_file, and contextual mentions)
-**Unused (Bloat):** ~21 variables (75% bloat!)
-
-**Bloat Breakdown:**
-
-- Boolean behavior flags: 20 (ALL features generated unconditionally)
-- Empty placeholders: 2 (test_framework, config_file)
-- Unnecessary derived paths: 1 (node_version_source)
-
-**Status:** ❌ **FAIL** - SEVERE bloat (75% of variables unused, highest bloat of all audited workflows)
-
----
-
-## 3. Config Variable Usage
-
-### Communication Language Check:
-
-- ❌ **MISSING** - No "communicate in {communication_language}" pattern found in instructions
-- Instructions do not reference communication_language variable
-- Severity: IMPORTANT
-
-### User Name Check:
-
-- ❌ **MISSING** - No {user_name} usage found in instructions
-- No personalization or greeting patterns detected
-- Severity: MINOR (optional for this workflow type)
-
-### Output Folder Check:
-
-- ⚠️ **INDIRECT** - Output folder not used directly
-- This workflow creates CI pipeline files (`.github/workflows/test.yml`), not docs
-- Scripts and docs go to `scripts/` and `docs/` directories
-- This is ACCEPTABLE for a CI setup workflow (artifacts belong in project structure)
-- Severity: N/A (appropriate for this workflow)
-
-### Date Usage Check:
-
-- ✅ **AVAILABLE** - Date is defined for potential use in documentation
-- Not explicitly used but available if needed
-- Severity: N/A
-
-**Status:** ⚠️ **IMPORTANT** - Config variables not properly utilized (communication_language missing)
-
----
-
-## 4. Web Bundle Validation
-
-### Web Bundle Present: ❌ **NO**
-
-**Status:** ❌ **CRITICAL** - No web_bundle configuration found
-
-The workflow.yaml contains:
-
-```yaml
-web_bundle: false
-```
-
-This means the workflow is **NOT** configured for web deployment.
-
-**Missing web_bundle requirements:**
-
-- No web_bundle_files list
-- No existing_workflows mapping
-- No web deployment path configuration
-
-**Knowledge Fragment Dependencies Detected in Instructions:**
-
-The instructions reference loading knowledge fragments from `tea-index.csv`:
-
-- `ci-burn-in.md` - Burn-in loop patterns (678 lines, 4 examples)
-- `selective-testing.md` - Changed test detection strategies (727 lines, 4 examples)
-- `visual-debugging.md` - Artifact collection best practices (522 lines, 5 examples)
-- `test-quality.md` - CI-specific test quality criteria (658 lines, 5 examples)
-- `playwright-config.md` - CI-optimized configuration (722 lines, 5 examples)
-
-**Template Files Present:**
-
-- `github-actions-template.yaml`
-- `gitlab-ci-template.yaml`
-
-These should be declared in web_bundle for web deployment.
-
-**Expected web_bundle structure:**
-
-```yaml
-web_bundle:
-  workflow_path: 'bmad/bmm/workflows/testarch/ci/workflow.yaml'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/testarch/ci/instructions.md'
-    - 'bmad/bmm/workflows/testarch/ci/checklist.md'
-    - 'bmad/bmm/workflows/testarch/ci/github-actions-template.yaml'
-    - 'bmad/bmm/workflows/testarch/ci/gitlab-ci-template.yaml'
-    - 'bmad/bmm/testarch/knowledge/ci-burn-in.md'
-    - 'bmad/bmm/testarch/knowledge/selective-testing.md'
-    - 'bmad/bmm/testarch/knowledge/visual-debugging.md'
-    - 'bmad/bmm/testarch/knowledge/test-quality.md'
-    - 'bmad/bmm/testarch/knowledge/playwright-config.md'
-    - 'bmad/bmm/testarch/tea-index.csv'
-```
-
-**Impact:** This workflow cannot be bundled for web deployment without web_bundle configuration.
-
-**Severity:** CRITICAL (if web deployment is intended)
-
----
-
-## 5. Bloat Detection
-
-### Unused YAML Fields Analysis
-
-**Total YAML fields:** 28 variables (excluding standard config and metadata)
-**Used fields:** ~7 (25%)
-**Unused fields:** ~21 (75%)
-**Bloat percentage:** **75%**
-
-### Detailed Bloat Analysis:
-
-#### Category 1: Configuration Values That Are Always Hardcoded (20 variables)
-
-These variables suggest customization but the instructions **ALWAYS** use specific hardcoded values:
-
-1. **`parallel_jobs: 4`** → Instructions hardcode "strategy: matrix: shard: [1, 2, 3, 4]"
-2. **`burn_in_enabled: true`** → Burn-in loop always added in Step 2.4
-3. **`burn_in_iterations: 10`** → Instructions hardcode "for i in {1..10}"
-4. **`selective_testing_enabled: true`** → test-changed.sh always generated
-5. **`artifact_retention_days: 30`** → Instructions hardcode "retention-days: 30"
-6. **`upload_artifacts_on: "failure"`** → Instructions always use "if: failure()"
-7. **`artifact_types: "traces,screenshots,videos,html-report"`** → All types always collected
-8. **`cache_enabled: true`** → Caching always configured
-9. **`browser_cache_enabled: true`** → Browser cache always configured
-10. **`timeout_minutes: 60`** → Timeouts hardcoded in instructions
-11. **`test_timeout_minutes: 30`** → Hardcoded
-12. **`notify_on_failure: false`** → Notification example shown regardless
-13. **`notification_channels: ""`** → Empty, not used
-14. **`generate_ci_readme: true`** → docs/ci.md always generated
-15. **`generate_local_mirror_script: true`** → ci-local.sh always generated
-16. **`generate_secrets_checklist: true`** → ci-secrets-checklist.md always generated
-17. **`use_matrix_strategy: true`** → Matrix always used in templates
-18. **`use_sharding: true`** → Sharding always configured
-19. **`retry_failed_tests: true`** → Retry logic always added
-20. **`retry_count: 2`** → Hardcoded as "max_attempts: 3"
-
-**Recommendation:** Remove ALL 20 configuration variables. The workflow should have a single, opinionated CI setup with hardcoded best practices. Users can customize the generated files if needed.
-
-**Rationale:** These variables create maintenance burden and confusion. The instructions ignore them anyway, always generating the full-featured pipeline.
-
-#### Category 2: Empty Placeholders (2 variables)
-
-21. **`test_framework: ""`** - Auto-detected from config files in Step 1.2
-22. **`config_file: ""`** - Derived from test_framework detection
-
-**Recommendation:** Remove these. Use <ask> tag if auto-detection fails.
-
-#### Category 3: Unnecessary Derived Paths (1 variable)
-
-23. **`node_version_source: "{project-root}/.nvmrc"`** - Instructions always read .nvmrc directly
-
-**Recommendation:** Remove. Hardcode .nvmrc path in instructions (standard location).
-
-#### Category 4: Auto-Detection Variable (1 variable) - KEEP
-
-24. **`ci_platform: "auto"`** - Legitimate choice (auto, github-actions, gitlab-ci, circle-ci, jenkins)
-
-**Recommendation:** KEEP - This is the ONLY legitimate configuration variable.
-
-#### Category 5: Standard Paths (2 variables) - KEEP
-
-25. **`test_dir: "{project-root}/tests"`** - Standard path, could be customized
-26. **`default_output_file: "{project-root}/.github/workflows/test.yml"`** - Required workflow output
-
-**Recommendation:** KEEP - Standard workflow paths.
-
-**Total Bloat Items:** 23 of 28 variables (82%!)
-
-**Bloat Percentage:** 82%
-**Cleanup Potential:** EXTREME - Removing bloat would reduce variables from 28 to 5
-
-**After Cleanup, Only These Should Remain:**
-
-1. `ci_platform: "auto"` - User choice for platform
-2. `test_dir: "{project-root}/tests"` - Standard path
-3. `default_output_file: "{project-root}/.github/workflows/test.yml"` - Output path
-4. `installed_path`, `instructions`, `validation` - Standard workflow fields
-
----
-
-## 6. Template Variable Mapping
-
-**Workflow Type:** Action workflow (no template for workflow itself)
-
-**Template Files:** github-actions-template.yaml, gitlab-ci-template.yaml (these are CI pipeline templates, not workflow templates)
-
-**Template Variable Mapping:** N/A - This is an action workflow that generates CI configuration files directly.
-
-**<template-output> Tags:** None (correct for action workflow)
-
-**Status:** ✅ **N/A** - Action workflow correctly configured without template
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-1. **Add web_bundle configuration**
-   - Add web_bundle block with all required files (instructions, checklist, templates)
-   - Map knowledge fragments (ci-burn-in.md, selective-testing.md, visual-debugging.md, test-quality.md, playwright-config.md)
-   - Include github-actions-template.yaml and gitlab-ci-template.yaml
-   - Include tea-index.csv for knowledge base access
-   - Enable web deployment capability
-   - Severity: CRITICAL
-   - Impact: Workflow cannot be deployed to web without this
-
-### Important (Address Soon)
-
-2. **Add config variable usage in instructions**
-   - Add communication_language support for multilingual workflows
-   - Add greeting or summary using {user_name}
-   - Ensure proper integration with BMAD v6 config standards
-   - Severity: IMPORTANT
-   - Impact: Workflows not following BMAD v6 conventions
-
-### Cleanup (Nice to Have)
-
-3. **Remove ALL configuration bloat (23 variables!)**
-   - Delete: parallel_jobs, burn_in_enabled, burn_in_iterations, selective_testing_enabled, artifact_retention_days, upload_artifacts_on, artifact_types, cache_enabled, browser_cache_enabled, timeout_minutes, test_timeout_minutes, notify_on_failure, notification_channels, generate_ci_readme, generate_local_mirror_script, generate_secrets_checklist, use_matrix_strategy, use_sharding, retry_failed_tests, retry_count, test_framework, config_file, node_version_source
-   - **Rationale:** Instructions ignore these variables and generate a full-featured, opinionated CI pipeline
-   - Hardcode best practices directly in instructions (4 shards, 10 burn-in iterations, 30-day retention, failure-only artifacts, etc.)
-   - Users can customize generated files if they need different values
-   - Severity: CLEANUP
-   - Impact: Reduces bloat from 82% to 0%, eliminates false configurability
-
-4. **Simplify to minimal variables**
-   - Keep only: ci_platform (user choice), test_dir (standard path), default_output_file (output path)
-   - Remove everything else per recommendation 3
-   - Result: 28 variables → 5 variables (82% reduction!)
-   - Severity: CLEANUP
-   - Impact: Dramatically improves maintainability and clarity
-
-5. **Document opinionated defaults**
-   - In instructions, add comment block explaining hardcoded values:
-     - "This workflow generates an opinionated CI pipeline with production-tested defaults"
-     - "4 parallel shards (balance speed vs resource usage)"
-     - "10 burn-in iterations (catches ~99% of flaky tests)"
-     - "30-day artifact retention (debugging window vs storage cost)"
-     - "Users can customize generated files after workflow completion"
-   - Severity: CLEANUP
-   - Impact: Sets correct expectations about configurability
-
-6. **Add <ask> for platform if auto-detection fails**
-   - In Step 1.4, add: `<ask>Unable to auto-detect CI platform. Which platform would you like to use? [github-actions/gitlab-ci/circle-ci/jenkins]</ask>`
-   - Use response to select template
-   - Severity: CLEANUP
-   - Impact: Makes workflow properly interactive
-
----
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
-- [x] All standard config variables present and correct ✅ (Already passing)
-- [ ] No unused yaml fields (bloat removed to <20%)
-- [ ] Config variables used appropriately in instructions
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped (N/A - action workflow) ✅
-- [x] File structure follows v6 conventions ✅
-- [ ] Variables block reduced from 28 to 5 essential variables
-- [ ] Boolean flags removed (opinionated pipeline with hardcoded best practices)
-- [ ] Empty placeholders removed (<ask> tags added if needed)
-- [x] Action workflow correctly configured (no template) ✅
-
----
-
-## Next Steps
-
-1. **Review critical issues** and fix web_bundle configuration immediately
-2. **Address important issues** in next iteration (config usage)
-3. **Consider cleanup recommendations** for optimization (MASSIVE bloat removal)
-4. **Re-run audit** after fixes to verify improvements
-
-**Estimated Cleanup Impact:**
-
-- Variables: 28 → 5 (82% reduction - HIGHEST of all workflows!)
-- Bloat: 82% → 0%
-- Maintainability: Dramatically improved
-- Clarity: Much clearer (opinionated pipeline vs false configurability)
-- Web deployment: Enabled (after web_bundle added)
-
----
-
-## Positive Observations
-
-**What This Workflow Does Well:**
-
-1. ✅ **Excellent CI/CD Best Practices**
-   - Comprehensive pipeline stages (lint, test, burn-in, report)
-   - Production-proven patterns (4 shards, 10 burn-in iterations)
-   - Smart artifact strategy (failure-only, 30-day retention)
-   - Aggressive caching (dependencies + browser binaries)
-   - Local CI mirror for debugging
-
-2. ✅ **Strong Instructions Quality**
-   - Clear step-by-step CI scaffolding
-   - Platform-specific guidance (GitHub Actions, GitLab CI, Circle CI)
-   - Comprehensive code examples (pipeline configs, scripts)
-   - Good preflight checks (git repo, passing tests, framework setup)
-   - Excellent output summary with performance targets
-
-3. ✅ **Knowledge Base Integration**
-   - References tea-index.csv
-   - Loads 5 relevant knowledge fragments
-   - Applies CI/CD patterns from knowledge base
-   - Burn-in loop pattern from production systems
-
-4. ✅ **Proper Action Workflow Structure**
-   - No template file (correct for action workflow)
-   - Generates CI configs, scripts, and docs directly
-   - Clear deliverables listed
-
-5. ✅ **Production-Ready Defaults**
-   - 4 parallel shards (balanced speed)
-   - 10 burn-in iterations (high confidence)
-   - Failure-only artifacts (cost optimization)
-   - 30-day retention (debugging window)
-
-**Overall:** This is a well-designed workflow with EXCELLENT content but SEVERE bloat. The 23 unused variables create false impression of configurability when the workflow is (correctly) opinionated with hardcoded best practices. Removing bloat would make this an exceptional workflow.
-
-**The Bloat Paradox:** The instructions are excellent BECAUSE they ignore the variables and use hardcoded best practices. The variables serve no purpose except confusion.
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0

docs/testarch-file-review/audit-report-testarch-framework-2025-10-16.md

@@ -1,432 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** testarch-framework
-**Audit Date:** 2025-10-16
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Action workflow (no template)
-**Workflow Path:** `/Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/testarch/framework`
-
----
-
-## Executive Summary
-
-**Overall Status:** ⚠️ CONCERNS - Some bloat detected, missing web_bundle configuration
-
-- Critical Issues: 1
-- Important Issues: 1
-- Cleanup Recommendations: 4
-
-**Key Findings:**
-
-1. ✅ Standard config block is correctly configured
-2. ✅ Action workflow correctly configured (template: false implied, no template file)
-3. ⚠️ Moderate bloat detected - 14 variables defined with ~50% bloat
-4. ❌ No web_bundle configuration (critical for web deployment)
-5. ✅ Instructions well-written with good knowledge base integration
-
----
-
-## 1. Standard Config Block Validation
-
-### Required Variables Check
-
-✅ **Config Source Check:**
-
-- [x] `config_source` is defined: `"{project-root}/bmad/bmm/config.yaml"`
-- [x] Points to correct module config path (bmm)
-- [x] Uses {project-root} variable
-
-✅ **Standard Variables Check:**
-
-- [x] `output_folder` pulls from config_source: `"{config_source}:output_folder"`
-- [x] `user_name` pulls from config_source: `"{config_source}:user_name"`
-- [x] `communication_language` pulls from config_source: `"{config_source}:communication_language"`
-- [x] `date` is set to system-generated: `"system-generated"`
-
-**Status:** ✅ **PASS** - All standard config variables present and correctly configured
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### Variables Analysis
-
-**Total YAML fields analyzed:** 14 variables defined in workflow.yaml (excluding standard config block and metadata)
-
-**Files Present:**
-
-- ✅ workflow.yaml
-- ✅ instructions.md
-- ✅ checklist.md
-- ❌ No template file (correct for action workflow)
-
-**Workflow Type:** Action workflow (no template: field, defaults to false)
-
-### Categorization:
-
-#### INSTRUCTION_USED (Variables referenced in instructions.md):
-
-**Explicitly used with {variable} syntax:**
-
-- {project-root} - Used throughout instructions for paths
-- None of the workflow variables are explicitly referenced with {variable} syntax in instructions
-
-**Contextually referenced:**
-
-- test_framework - Mentioned conceptually ("Playwright or Cypress")
-- project_type - Mentioned in "Extract project type (React, Vue, Angular...)"
-- bundler - Mentioned in "Identify bundler (Vite, Webpack...)"
-- test_dir - Used conceptually as "Root test directory"
-- config_file - Framework config file paths mentioned
-- use_typescript - TypeScript preference mentioned
-- framework_preference - Framework selection logic
-- project_size - Framework selection criteria
-
-**Output path used:**
-
-- default_output_file: "{test_dir}/README.md" - Used for main deliverable
-
-#### Variables with NO clear usage:
-
-**Bloat Variables:**
-
-1. `standalone_mode: true` - Not referenced in instructions (appears to be a flag for workflow behavior, not used)
-2. `generate_env_example: true` - Behavior flag, but .env.example is generated unconditionally in Step 2.4
-3. `generate_nvmrc: true` - Behavior flag, but .nvmrc is generated unconditionally in Step 2.5
-4. `generate_readme: true` - Behavior flag, but README is generated unconditionally in Step 2.10
-5. `generate_sample_tests: true` - Behavior flag, but sample tests are generated unconditionally in Step 2.8
-
-**Empty Placeholders (should be elicited):** 6. `test_framework: ""` - Should be elicited with <ask> tag 7. `project_type: ""` - Auto-detected, empty placeholder unnecessary 8. `bundler: ""` - Auto-detected, empty placeholder unnecessary 9. `config_file: ""` - Derived path, should be calculated not declared
-
-**Total Variables Analyzed:** 14 variables
-**Used in Instructions (contextually):** ~8 (test_framework, project_type, bundler, test_dir, use_typescript, framework_preference, project_size, default_output_file)
-**Unused (Bloat):** ~6 variables (43% bloat)
-
-**Bloat Breakdown:**
-
-- Boolean behavior flags: 5 (generate_env_example, generate_nvmrc, generate_readme, generate_sample_tests, standalone_mode)
-- Empty placeholders: 3 (test_framework, project_type, bundler) - should use <ask> instead
-- Derived paths: 1 (config_file) - should be calculated
-
-**Status:** ⚠️ **CONCERNS** - Moderate bloat (43% of variables unused or redundant)
-
----
-
-## 3. Config Variable Usage
-
-### Communication Language Check:
-
-- ❌ **MISSING** - No "communicate in {communication_language}" pattern found in instructions
-- Instructions do not reference communication_language variable
-- Severity: IMPORTANT
-
-### User Name Check:
-
-- ❌ **MISSING** - No {user_name} usage found in instructions
-- No personalization or greeting patterns detected
-- Severity: MINOR (optional for this workflow type)
-
-### Output Folder Check:
-
-- ⚠️ **INDIRECT** - Output folder is used via default_output_file: "{test_dir}/README.md"
-- However, test_dir defaults to "{project-root}/tests", not {output_folder}
-- This workflow creates artifacts in the test directory, not the output folder
-- This is ACCEPTABLE for a setup workflow (artifacts belong in test infrastructure)
-- Severity: N/A (appropriate for this workflow)
-
-### Date Usage Check:
-
-- ✅ **AVAILABLE** - Date is defined for potential use in documentation
-- Not explicitly used but available if needed
-- Severity: N/A
-
-**Status:** ⚠️ **IMPORTANT** - Config variables not properly utilized (communication_language missing)
-
----
-
-## 4. Web Bundle Validation
-
-### Web Bundle Present: ❌ **NO**
-
-**Status:** ❌ **CRITICAL** - No web_bundle configuration found
-
-The workflow.yaml contains:
-
-```yaml
-web_bundle: false
-```
-
-This means the workflow is **NOT** configured for web deployment.
-
-**Missing web_bundle requirements:**
-
-- No web_bundle_files list
-- No existing_workflows mapping
-- No web deployment path configuration
-
-**Knowledge Fragment Dependencies Detected in Instructions:**
-
-The instructions reference loading knowledge fragments from `tea-index.csv`:
-
-- `fixture-architecture.md` - Pure function → fixture → mergeTests composition (406 lines, 5 examples)
-- `data-factories.md` - Faker-based factories with overrides (498 lines, 5 examples)
-- `network-first.md` - Network-first testing safeguards (489 lines, 5 examples)
-- `playwright-config.md` - Playwright configuration standards (722 lines, 5 examples)
-- `test-quality.md` - Test design principles (658 lines, 5 examples)
-
-These fragments should be declared in a web_bundle configuration for web deployment.
-
-**Expected web_bundle structure:**
-
-```yaml
-web_bundle:
-  workflow_path: 'bmad/bmm/workflows/testarch/framework/workflow.yaml'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/testarch/framework/instructions.md'
-    - 'bmad/bmm/workflows/testarch/framework/checklist.md'
-    - 'bmad/bmm/testarch/knowledge/fixture-architecture.md'
-    - 'bmad/bmm/testarch/knowledge/data-factories.md'
-    - 'bmad/bmm/testarch/knowledge/network-first.md'
-    - 'bmad/bmm/testarch/knowledge/playwright-config.md'
-    - 'bmad/bmm/testarch/knowledge/test-quality.md'
-    - 'bmad/bmm/testarch/tea-index.csv'
-```
-
-**Impact:** This workflow cannot be bundled for web deployment without web_bundle configuration.
-
-**Severity:** CRITICAL (if web deployment is intended)
-
----
-
-## 5. Bloat Detection
-
-### Unused YAML Fields Analysis
-
-**Total YAML fields:** 14 variables (excluding standard config and metadata)
-**Used fields:** ~8 (57%)
-**Unused fields:** ~6 (43%)
-**Bloat percentage:** **43%**
-
-### Bloat Categories:
-
-#### Category 1: Boolean Behavior Flags (Should be removed - outputs generated unconditionally)
-
-These variables suggest conditional generation, but the instructions generate these artifacts unconditionally:
-
-1. **`generate_env_example: true`**
-   - Instructions always generate `.env.example` in Step 2.4
-   - Flag has no effect on workflow behavior
-   - **Recommendation:** Remove variable, always generate .env.example
-
-2. **`generate_nvmrc: true`**
-   - Instructions always generate `.nvmrc` in Step 2.5
-   - Flag has no effect on workflow behavior
-   - **Recommendation:** Remove variable, always generate .nvmrc
-
-3. **`generate_readme: true`**
-   - Instructions always generate `tests/README.md` in Step 2.10
-   - Flag has no effect on workflow behavior
-   - **Recommendation:** Remove variable, always generate README
-
-4. **`generate_sample_tests: true`**
-   - Instructions always generate sample tests in Step 2.8
-   - Flag has no effect on workflow behavior
-   - **Recommendation:** Remove variable, always generate samples
-
-5. **`standalone_mode: true`**
-   - Not referenced anywhere in instructions
-   - Purpose unclear (possibly for workflow orchestration?)
-   - **Recommendation:** Remove if unused, or document purpose
-
-**Impact:** These 5 variables create false impression of configurability when behavior is hardcoded.
-
-#### Category 2: Empty Placeholders (Should use <ask> tags instead)
-
-These variables are empty strings waiting to be populated, but instructions should elicit them dynamically:
-
-6. **`test_framework: ""`**
-   - Instructions describe auto-detection logic in Step 2.1
-   - Should use <ask> tag if auto-detection fails
-   - **Recommendation:** Remove variable, use <ask> in instructions
-
-7. **`project_type: ""`**
-   - Auto-detected from package.json in Step 1.1
-   - Empty placeholder unnecessary
-   - **Recommendation:** Remove variable, detect in instructions
-
-8. **`bundler: ""`**
-   - Auto-detected from package.json in Step 1.1
-   - Empty placeholder unnecessary
-   - **Recommendation:** Remove variable, detect in instructions
-
-9. **`config_file: ""`**
-   - Derived path: `{project-root}/{framework}.config.{ts|js}`
-   - Should be calculated in instructions based on detected framework
-   - **Recommendation:** Remove variable, calculate in instructions
-
-**Impact:** These 4 variables add no value and clutter the configuration.
-
-#### Category 3: Acceptable Variables (Keep these)
-
-These variables have legitimate workflow-specific purpose:
-
-1. **`test_dir: "{project-root}/tests"`** - KEEP
-   - Defines root test directory location
-   - Used throughout instructions for directory structure
-   - User might want to customize (e.g., "e2e-tests")
-
-2. **`use_typescript: true`** - KEEP
-   - Determines whether to generate .ts or .js files
-   - Legitimate configuration option
-
-3. **`framework_preference: "auto"`** - KEEP
-   - Allows user to override auto-detection (playwright, cypress, auto)
-   - Legitimate configuration option
-
-4. **`project_size: "auto"`** - KEEP
-   - Influences framework recommendation (small, large, auto)
-   - Legitimate configuration option
-
-5. **`default_output_file: "{test_dir}/README.md"`** - KEEP
-   - Standard workflow output path
-   - Required field
-
-**Total Bloat Items:** 9 variables should be removed or relocated
-
-**Bloat Percentage:** 64% (9 of 14 variables)
-**Cleanup Potential:** MEDIUM - Removing bloat would reduce variables from 14 to 5
-
----
-
-## 6. Template Variable Mapping
-
-**Workflow Type:** Action workflow (no template)
-
-**Template File:** None (correct)
-
-**Template Variable Mapping:** N/A - This is an action workflow that generates files directly (config files, fixtures, sample tests, README).
-
-**<template-output> Tags:** None (correct for action workflow)
-
-**Status:** ✅ **N/A** - Action workflow correctly configured without template
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-1. **Add web_bundle configuration**
-   - Add web_bundle block with all required files (instructions, checklist)
-   - Map knowledge fragments (fixture-architecture.md, data-factories.md, network-first.md, playwright-config.md, test-quality.md)
-   - Include tea-index.csv for knowledge base access
-   - Enable web deployment capability
-   - Severity: CRITICAL
-   - Impact: Workflow cannot be deployed to web without this
-
-### Important (Address Soon)
-
-2. **Add config variable usage in instructions**
-   - Add communication_language support for multilingual workflows
-   - Add greeting or summary using {user_name}
-   - Ensure proper integration with BMAD v6 config standards
-   - Severity: IMPORTANT
-   - Impact: Workflows not following BMAD v6 conventions
-
-### Cleanup (Nice to Have)
-
-3. **Remove boolean behavior flags (5 variables)**
-   - Delete: `generate_env_example`, `generate_nvmrc`, `generate_readme`, `generate_sample_tests`, `standalone_mode`
-   - These artifacts are always generated (flags have no effect)
-   - Simplifies configuration and removes false impression of conditionality
-   - Severity: CLEANUP
-   - Impact: Reduces bloat from 64% to 29%, improves clarity
-
-4. **Remove empty placeholder variables (4 variables)**
-   - Delete: `test_framework: ""`, `project_type: ""`, `bundler: ""`, `config_file: ""`
-   - Use <ask> tags in instructions to elicit test_framework if auto-detection fails
-   - Auto-detect project_type and bundler in instructions (no variable needed)
-   - Calculate config_file path in instructions based on detected framework
-   - Severity: CLEANUP
-   - Impact: Reduces variable count from 14 to 5 (64% reduction)
-
-5. **Add <ask> tag for framework selection**
-   - In Step 2.1, add: `<ask>Which test framework would you like to use? [playwright/cypress/auto]</ask>`
-   - Use response to set framework choice
-   - Remove `test_framework: ""` placeholder variable
-   - Severity: CLEANUP
-   - Impact: Makes workflow properly interactive
-
-6. **Document standalone_mode purpose or remove**
-   - Variable is not referenced in instructions
-   - If intended for workflow orchestration, document usage
-   - If unused, remove
-   - Severity: CLEANUP
-   - Impact: Clarifies configuration intent
-
----
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
-- [x] All standard config variables present and correct ✅ (Already passing)
-- [ ] No unused yaml fields (bloat removed to <20%)
-- [ ] Config variables used appropriately in instructions
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped (N/A - action workflow) ✅
-- [x] File structure follows v6 conventions ✅
-- [ ] Variables block reduced from 14 to 5 essential variables
-- [ ] Boolean flags removed (outputs always generated)
-- [ ] Empty placeholders removed (<ask> tags added)
-- [x] Action workflow correctly configured (no template) ✅
-
----
-
-## Next Steps
-
-1. **Review critical issues** and fix web_bundle configuration immediately
-2. **Address important issues** in next iteration (config usage)
-3. **Consider cleanup recommendations** for optimization (bloat removal)
-4. **Re-run audit** after fixes to verify improvements
-
-**Estimated Cleanup Impact:**
-
-- Variables: 14 → 5 (64% reduction)
-- Bloat: 64% → 0%
-- Maintainability: Improved
-- Web deployment: Enabled (after web_bundle added)
-
----
-
-## Positive Observations
-
-**What This Workflow Does Well:**
-
-1. ✅ **Excellent Instructions Quality**
-   - Clear step-by-step scaffolding process
-   - Comprehensive code examples (Playwright config, Cypress config, fixtures, factories)
-   - Good knowledge base integration (5 fragments referenced)
-   - Practical preflight checks
-
-2. ✅ **Proper Action Workflow Structure**
-   - No template file (correct for action workflow)
-   - Generates artifacts directly (config files, fixtures, tests)
-   - Clear deliverables listed in Step 3
-
-3. ✅ **Good Workflow Design**
-   - Auto-detection logic (package.json, framework)
-   - Intelligent defaults (Playwright for large projects, Cypress for small teams)
-   - Comprehensive test infrastructure (fixtures, factories, helpers)
-   - Best practices built in (data-testid selectors, auto-cleanup, failure-only artifacts)
-
-4. ✅ **Knowledge Base Integration**
-   - References tea-index.csv
-   - Loads 5 relevant knowledge fragments
-   - Applies patterns from knowledge base (fixture architecture, data factories)
-
-**Overall:** This is a well-designed workflow with moderate bloat. Cleanup would make it excellent.
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0

docs/testarch-file-review/audit-report-testarch-nfr-assess-2025-10-16.md

@@ -1,390 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** testarch-nfr-assess
-**Audit Date:** 2025-10-16
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Document workflow (has template)
-**Workflow Path:** `/Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/testarch/nfr-assess`
-
----
-
-## Executive Summary
-
-**Overall Status:** ⚠️ CONCERNS - Significant bloat detected, missing web_bundle configuration
-
-- Critical Issues: 1
-- Important Issues: 2
-- Cleanup Recommendations: 4
-
-**Key Findings:**
-
-1. ✅ Standard config block is correctly configured
-2. ✅ Document workflow correctly configured (has template file)
-3. ❌ **SIGNIFICANT BLOAT:** 32 variables defined with ~75% bloat (24 unused variables!)
-4. ❌ No web_bundle configuration (critical for web deployment)
-5. ⚠️ Config variable usage missing
-6. ⚠️ Template integration likely broken (needs verification)
-
----
-
-## 1. Standard Config Block Validation
-
-### Required Variables Check
-
-✅ **Config Source Check:**
-
-- [x] `config_source` is defined: `"{project-root}/bmad/bmm/config.yaml"`
-- [x] Points to correct module config path (bmm)
-- [x] Uses {project-root} variable
-
-✅ **Standard Variables Check:**
-
-- [x] `output_folder` pulls from config_source: `"{config_source}:output_folder"`
-- [x] `user_name` pulls from config_source: `"{config_source}:user_name"`
-- [x] `communication_language` pulls from config_source: `"{config_source}:communication_language"`
-- [x] `date` is set to system-generated: `"system-generated"`
-
-**Status:** ✅ **PASS** - All standard config variables present and correctly configured
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### Variables Analysis
-
-**Total YAML fields analyzed:** 32 variables defined in workflow.yaml (excluding standard config and metadata)
-
-**Files Present:**
-
-- ✅ workflow.yaml
-- ✅ instructions.md
-- ✅ checklist.md
-- ✅ nfr-report-template.md (template file for document workflow)
-- ✅ README.md
-
-**Workflow Type:** Document workflow (has `template: "{installed_path}/nfr-report-template.md"`)
-
-### SIGNIFICANT BLOAT DETECTED (75%):
-
-#### Category 1: NFR Category Flags (4 variables - should assess ALL)
-
-1. `assess_performance: true`
-2. `assess_security: true`
-3. `assess_reliability: true`
-4. `assess_maintainability: true`
-
-**Recommendation:** Remove. An NFR assessment workflow should ALWAYS assess ALL standard NFR categories. Making these optional defeats the purpose.
-
-**Rationale:** You don't skip security assessment just because a flag is false! Always assess all NFRs, mark as "NOT_APPLICABLE" if truly not relevant.
-
-#### Category 2: Threshold Values (5 variables - should be project config)
-
-5. `performance_response_time_ms: 500`
-6. `performance_throughput_rps: 100`
-7. `security_score_min: 85`
-8. `reliability_uptime_pct: 99.9`
-9. `maintainability_coverage_pct: 80`
-
-**Recommendation:** Move to bmm/config.yaml as project-wide NFR standards. Reference via {config_source}:nfr_performance_response_time_ms pattern.
-
-**Rationale:** NFR thresholds are project-level quality standards, not workflow-specific variables.
-
-#### Category 3: Boolean Behavior Flags (15 variables - likely all apply unconditionally)
-
-**Assessment Configuration:** 10. `use_deterministic_rules: true` - Deterministic assessment should always be used 11. `never_guess_thresholds: true` - Never guessing should always be the rule 12. `require_evidence: true` - Evidence should always be required 13. `suggest_monitoring: true` - Monitoring suggestions should always be provided
-
-**BMad Integration:** 14. `use_tech_spec: true` - Auto-load if exists 15. `use_prd: true` - Auto-load if exists 16. `use_test_design: true` - Auto-load if exists
-
-**Evidence Sources:** 17. `include_ci_results: true` - CI results should always be analyzed
-
-**Output Configuration:** 18. `generate_gate_yaml: true` - Gate YAML should always be generated 19. `generate_evidence_checklist: true` - Evidence checklist should always be generated 20. `update_story_file: false` - Optional output mode
-
-**Quality Gates:** 21. `fail_on_critical_nfr: true` - Always fail on critical NFR failure 22. `warn_on_concerns: true` - Always warn on concerns 23. `block_release_on_fail: true` - Always block on failure
-
-**Advanced Options:** 24. `auto_load_knowledge: true` - Always load knowledge base 25. `include_quick_wins: true` - Always suggest quick wins 26. `include_recommended_actions: true` - Always provide recommendations
-
-**Recommendation:** Remove ALL 15 boolean flags. An NFR assessment should ALWAYS:
-
-- Use deterministic rules (not guesswork)
-- Require evidence
-- Suggest monitoring
-- Generate gate YAML
-- Provide recommendations
-- Block release on critical failures
-
-These aren't user choices - they're assessment methodology requirements.
-
-#### Category 4: Empty Placeholders (3 variables)
-
-27. `story_file: ""`
-28. `feature_name: ""`
-29. `custom_nfr_categories: ""`
-
-**Recommendation:** Remove. Use <ask> tags to elicit these if needed.
-
-#### Category 5: Redundant Output Path (1 variable)
-
-30. `output_file: "{output_folder}/nfr-assessment.md"` - Duplicates default_output_file
-
-**Recommendation:** Remove. Use default_output_file.
-
-#### Category 6: Directory Paths (3 variables)
-
-31. `test_results_dir: "{project-root}/test-results"`
-32. `metrics_dir: "{project-root}/metrics"`
-33. `logs_dir: "{project-root}/logs"`
-
-**Recommendation:** Keep or consolidate. These are standard paths but could be auto-detected.
-
-#### Category 7: Acceptable Variables (Keep These)
-
-1. **`test_results_dir`, `metrics_dir`, `logs_dir`** - MAYBE KEEP (standard paths, could auto-detect)
-2. **`default_output_file: "{output_folder}/nfr-assessment.md"`** - KEEP (output path)
-3. **`installed_path`, `instructions`, `validation`, `template`** - KEEP (standard workflow fields)
-
-**Total Variables Analyzed:** 32 variables
-**Legitimate Variables:** ~4-7 (directory paths?, default_output_file + standard fields)
-**Bloat:** ~25-28 variables (78-87% bloat!)
-
-**Status:** ❌ **FAIL** - SEVERE bloat (75%+ of variables unused or should be hardcoded methodology)
-
----
-
-## 3. Config Variable Usage
-
-### Communication Language Check:
-
-- ❌ **MISSING** - No "communicate in {communication_language}" pattern
-- Severity: IMPORTANT
-
-### User Name Check:
-
-- ❌ **MISSING** - No {user_name} usage
-- Severity: MINOR (optional)
-
-### Output Folder Check:
-
-- ✅ **USED** - default_output_file uses {output_folder}
-- Severity: N/A
-
-### Date Usage Check:
-
-- ✅ **AVAILABLE** - Date defined for template
-- Severity: N/A
-
-**Status:** ⚠️ **IMPORTANT** - Config variables not fully utilized
-
----
-
-## 4. Web Bundle Validation
-
-### Web Bundle Present: ❌ **NO**
-
-**Status:** ❌ **CRITICAL** - No web_bundle configuration found
-
-```yaml
-web_bundle: false
-```
-
-**Knowledge Fragment Dependencies (from auto_load_knowledge comment):**
-
-- nfr-criteria
-- ci-burn-in
-
-**Template File:**
-
-- nfr-report-template.md
-
-**Expected web_bundle structure:**
-
-```yaml
-web_bundle:
-  workflow_path: 'bmad/bmm/workflows/testarch/nfr-assess/workflow.yaml'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/testarch/nfr-assess/instructions.md'
-    - 'bmad/bmm/workflows/testarch/nfr-assess/checklist.md'
-    - 'bmad/bmm/workflows/testarch/nfr-assess/nfr-report-template.md'
-    - 'bmad/bmm/testarch/knowledge/nfr-criteria.md'
-    - 'bmad/bmm/testarch/knowledge/ci-burn-in.md'
-    - 'bmad/bmm/testarch/tea-index.csv'
-```
-
-**Severity:** CRITICAL
-
----
-
-## 5. Bloat Detection
-
-**Total YAML fields:** 32 variables
-**Used fields:** ~4-7 (12-22%)
-**Unused fields:** ~25-28 (78-88%)
-**Bloat percentage:** **78-88%** (approaching automate's champion status!)
-
-### Detailed Bloat Analysis:
-
-#### Remove NFR Category Flags (4 variables):
-
-1-4. `assess_performance/security/reliability/maintainability`
-
-**Rationale:** Always assess ALL NFRs. Don't skip security just because flag is false!
-
-#### Move Threshold Values to Project Config (5 variables):
-
-5-9. `performance_response_time_ms, performance_throughput_rps, security_score_min, reliability_uptime_pct, maintainability_coverage_pct`
-
-**Rationale:** These are project-wide quality standards, not workflow variables.
-
-#### Remove Methodology Requirement Flags (15 variables):
-
-10-24. All boolean flags (use_deterministic_rules, require_evidence, generate_gate_yaml, fail_on_critical_nfr, etc.)
-
-**Rationale:** These define NFR assessment methodology and should NEVER be optional.
-
-#### Remove Empty Placeholders (3 variables):
-
-25-27. `story_file, feature_name, custom_nfr_categories`
-
-**Rationale:** Use <ask> tags instead.
-
-#### Remove Redundant Output Path (1 variable):
-
-28. `output_file`
-
-**Rationale:** Use default_output_file.
-
-#### Maybe Keep Directory Paths (3 variables):
-
-29-31. `test_results_dir, metrics_dir, logs_dir`
-
-**Decision:** Could auto-detect these standard locations.
-
-**Total Bloat:** 24-27 of 32 variables (75-84%)
-
-**After Cleanup:**
-
-1. `test_results_dir, metrics_dir, logs_dir` - Maybe keep
-2. `default_output_file` - Keep
-3. Standard fields - Keep
-
-**Result:** 32 → 4-7 variables (78-87% reduction!)
-
----
-
-## 6. Template Variable Mapping
-
-**Workflow Type:** Document workflow (has template)
-
-**Template File:** nfr-report-template.md
-
-**Status:** ⚠️ **LIKELY BROKEN** - Template integration needs verification (pattern from previous audits)
-
-**Recommendation:** Verify template integration or remove template.
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-1. **Add web_bundle configuration**
-   - Severity: CRITICAL
-   - Impact: Enables web deployment
-
-### Important (Address Soon)
-
-2. **Fix template integration**
-   - Severity: IMPORTANT
-   - Impact: Template functionality
-
-3. **Add config variable usage**
-   - Severity: IMPORTANT
-   - Impact: BMAD v6 compliance
-
-### Cleanup (Nice to Have)
-
-4. **Remove ALL NFR category flags (4 variables)**
-   - Always assess all NFRs
-   - Severity: CLEANUP
-   - Impact: Can't skip security assessment!
-
-5. **Move thresholds to project config (5 variables)**
-   - Project-wide quality standards
-   - Severity: CLEANUP
-   - Impact: Centralized NFR standards
-
-6. **Remove methodology flags (15 variables)**
-   - NFR assessment requirements, not choices
-   - Severity: CLEANUP
-   - Impact: Ensures methodology integrity
-
-7. **Remove empty placeholders and redundant paths (4 variables)**
-   - Severity: CLEANUP
-   - Impact: Cleaner configuration
-
-8. **Simplify to essential variables**
-   - Result: 32 → 4-7 variables (78-87% reduction!)
-   - Severity: CLEANUP
-   - Impact: Dramatically improved maintainability
-
----
-
-## Validation Checklist
-
-- [x] All standard config variables present ✅
-- [ ] No unused yaml fields (bloat removed)
-- [ ] Config variables used appropriately
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped
-- [x] File structure follows v6 conventions ✅
-- [ ] Variables reduced from 32 to 4-7
-- [ ] NFR category flags removed (always assess all)
-- [ ] Thresholds moved to project config
-- [ ] Methodology flags removed
-- [x] Document workflow correctly configured ✅
-
----
-
-## Next Steps
-
-1. **Fix web_bundle** immediately
-2. **Address template integration** and config usage
-3. **Consider cleanup** - 78-87% bloat reduction!
-4. **Re-run audit** after fixes
-
-**Cleanup Impact:**
-
-- Variables: 32 → 4-7 (78-87% reduction!)
-- Bloat: 78-87% → 0%
-- Maintainability: Dramatically improved
-- Methodology Integrity: Ensured
-- Web deployment: Enabled
-
----
-
-## Positive Observations
-
-1. ✅ **Comprehensive NFR Coverage**
-   - Performance, security, reliability, maintainability
-   - Evidence-based assessment
-   - Gate decision integration
-
-2. ✅ **Proper Document Workflow Structure**
-   - Has template file
-   - Clear output path
-
-3. ✅ **Good Methodology**
-   - Deterministic rules
-   - Evidence requirements
-   - Gate blocking on failures
-
-4. ✅ **Knowledge Base Integration**
-   - References tea-index.csv
-   - Loads NFR criteria
-
-**Overall:** Well-designed NFR assessment workflow with excellent methodology but SEVERE bloat (78-87%). The 4 NFR category flags allow skipping security/performance assessment - unacceptable! The 15 methodology flags make requirements optional - defeating the purpose! Removing bloat would make this exceptional.
-
-**The NFR Assessment Paradox:** Allowing users to set `assess_security: false` means security NFRs won't be assessed - a major release risk! All NFRs should ALWAYS be assessed, marked as NOT_APPLICABLE if truly irrelevant.
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0

docs/testarch-file-review/audit-report-testarch-test-design-2025-10-16.md

@@ -1,395 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** testarch-test-design
-**Audit Date:** 2025-10-16
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Document workflow (has template)
-**Workflow Path:** `/Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/testarch/test-design`
-
----
-
-## Executive Summary
-
-**Overall Status:** ✅ **GOOD** - Minimal bloat, missing web_bundle configuration
-
-- Critical Issues: 1
-- Important Issues: 2
-- Cleanup Recommendations: 3
-
-**Key Findings:**
-
-1. ✅ Standard config block is correctly configured
-2. ✅ Document workflow correctly configured (has template file)
-3. ✅ **BEST BLOAT SCORE:** 20 variables with ~40% bloat (8 unused - LOWEST of all workflows!)
-4. ❌ No web_bundle configuration (critical for web deployment)
-5. ⚠️ Config variable usage missing
-6. ⚠️ Template integration likely broken (needs verification)
-
-**CONGRATULATIONS:** This workflow has the LOWEST bloat percentage (40%) of all 8 audited workflows!
-
----
-
-## 1. Standard Config Block Validation
-
-### Required Variables Check
-
-✅ **Config Source Check:**
-
-- [x] `config_source` is defined: `"{project-root}/bmad/bmm/config.yaml"`
-- [x] Points to correct module config path (bmm)
-- [x] Uses {project-root} variable
-
-✅ **Standard Variables Check:**
-
-- [x] `output_folder` pulls from config_source: `"{config_source}:output_folder"`
-- [x] `user_name` pulls from config_source: `"{config_source}:user_name"`
-- [x] `communication_language` pulls from config_source: `"{config_source}:communication_language"`
-- [x] `date` is set to system-generated: `"system-generated"`
-
-**Status:** ✅ **PASS** - All standard config variables present and correctly configured
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### Variables Analysis
-
-**Total YAML fields analyzed:** 20 variables defined in workflow.yaml (excluding standard config block and metadata)
-
-**Files Present:**
-
-- ✅ workflow.yaml
-- ✅ instructions.md
-- ✅ checklist.md
-- ✅ test-design-template.md (template file for document workflow)
-- ✅ README.md
-
-**Workflow Type:** Document workflow (has `template: "{installed_path}/test-design-template.md"`)
-
-### Bloat Analysis - BEST SCORE!
-
-**CONGRATULATIONS:** This workflow has the LOWEST bloat of all 8 audited workflows!
-
-#### Category 1: Boolean Behavior Flags (7 variables - likely some used)
-
-1. `risk_assessment_enabled: true` - Likely always enabled (that's the point!)
-2. `include_risk_matrix: true` - Output component, might be legitimately optional
-3. `include_coverage_matrix: true` - Output component, might be legitimately optional
-4. `include_execution_order: true` - Output component, might be legitimately optional
-5. `include_resource_estimates: true` - Output component, might be legitimately optional
-6. `auto_load_knowledge: true` - Likely always loads knowledge
-7. `include_mitigation_plan: true` - Likely always included
-8. `include_gate_criteria: true` - Likely always included
-
-**Analysis:** Unlike other workflows, these flags affect OUTPUT COMPONENTS, not methodology. Some might be legitimately optional (e.g., minimal design level might skip resource estimates).
-
-**Recommendation:** Review if these are truly optional based on design_level:
-
-- "full" → include all components
-- "targeted" → skip resource estimates?
-- "minimal" → skip execution order and estimates?
-
-If design*level already determines what's included, remove the 4 include*\* flags and derive from design_level.
-
-Remove: risk_assessment_enabled, auto_load_knowledge, include_mitigation_plan, include_gate_criteria (should always be included).
-
-**Potential removals:** 4-8 variables (depending on design_level logic)
-
-#### Category 2: Configuration Values (4 variables - mixed)
-
-9. `risk_threshold: 6` - Threshold value, could move to project config
-10. `risk_categories: "TECH,SEC,PERF,DATA,BUS,OPS"` - Standard categories, could be hardcoded
-11. `priority_levels: "P0,P1,P2,P3"` - Standard priorities, could be hardcoded
-12. `test_levels: "e2e,api,integration,unit,component"` - Standard levels, could be hardcoded
-
-**Recommendation:**
-
-- Move risk_threshold to project config
-- Hardcode risk_categories (standard TEA categories)
-- Hardcode priority_levels (P0-P3 is standard)
-- Hardcode or keep test_levels (fairly standard)
-
-**Potential removals:** 2-4 variables
-
-#### Category 3: Empty Placeholders (2 variables)
-
-13. `epic_num: ""` - Should use <ask> tag
-14. `story_path: ""` - Should use <ask> tag (optional)
-
-**Recommendation:** Remove. Use <ask> tags to elicit these.
-
-**Removals:** 2 variables
-
-#### Category 4: Redundant Output Path (1 variable)
-
-15. `output_file: "{output_folder}/test-design-epic-{epic_num}.md"` - Duplicates default_output_file
-
-**Recommendation:** Remove. Use default_output_file.
-
-**Removals:** 1 variable
-
-#### Category 5: Acceptable Variables (Keep These) - 12 variables
-
-1. **`design_level: "full"`** - KEEP (legitimate choice: full, targeted, minimal)
-2. **`selective_testing_strategy: "risk-based"`** - KEEP (legitimate choice: risk-based, coverage-based, hybrid)
-3. **`standalone_mode: false`** - KEEP (mode choice: with/without epic context)
-4. **`risk_threshold: 6`** - MAYBE KEEP (if not moved to project config)
-5. **`risk_categories, priority_levels, test_levels`** - MAYBE KEEP (if considered configurable)
-6. **`include_risk_matrix, include_coverage_matrix, include_execution_order, include_resource_estimates`** - MAYBE KEEP (if design_level doesn't determine these)
-7. **`default_output_file`** - KEEP (output path)
-8. **`installed_path`, `instructions`, `validation`, `template`** - KEEP (standard workflow fields)
-
-**Total Variables Analyzed:** 20 variables
-**Legitimate Variables:** ~8-12 (depending on design_level logic and config choices)
-**Bloat:** ~8-12 variables (40-60% bloat)
-
-**Conservative Estimate:** 40% bloat (8 of 20 variables)
-**Aggressive Cleanup:** 60% bloat (12 of 20 variables if design_level determines output components and configs are hardcoded)
-
-**Status:** ✅ **GOOD** - Lowest bloat of all workflows (40% conservative, 60% aggressive)
-
----
-
-## 3. Config Variable Usage
-
-### Communication Language Check:
-
-- ❌ **MISSING** - No "communicate in {communication_language}" pattern
-- Severity: IMPORTANT
-
-### User Name Check:
-
-- ❌ **MISSING** - No {user_name} usage
-- Severity: MINOR (optional)
-
-### Output Folder Check:
-
-- ✅ **USED** - default_output_file uses {output_folder}
-- Severity: N/A
-
-### Date Usage Check:
-
-- ✅ **AVAILABLE** - Date defined for template
-- Severity: N/A
-
-**Status:** ⚠️ **IMPORTANT** - Config variables not fully utilized
-
----
-
-## 4. Web Bundle Validation
-
-### Web Bundle Present: ❌ **NO**
-
-**Status:** ❌ **CRITICAL** - No web_bundle configuration found
-
-```yaml
-web_bundle: false
-```
-
-**Knowledge Fragment Dependencies (from auto_load_knowledge):**
-
-- Risk assessment fragments
-- Test priorities
-- Coverage planning
-
-**Template File:**
-
-- test-design-template.md
-
-**Expected web_bundle structure:**
-
-```yaml
-web_bundle:
-  workflow_path: 'bmad/bmm/workflows/testarch/test-design/workflow.yaml'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/testarch/test-design/instructions.md'
-    - 'bmad/bmm/workflows/testarch/test-design/checklist.md'
-    - 'bmad/bmm/workflows/testarch/test-design/test-design-template.md'
-    - 'bmad/bmm/testarch/knowledge/risk-governance.md'
-    - 'bmad/bmm/testarch/knowledge/test-priorities-matrix.md'
-    - 'bmad/bmm/testarch/knowledge/probability-impact.md'
-    - 'bmad/bmm/testarch/tea-index.csv'
-```
-
-**Severity:** CRITICAL
-
----
-
-## 5. Bloat Detection
-
-**Total YAML fields:** 20 variables
-**Conservative Estimate:**
-
-- Used fields: ~12 (60%)
-- Unused fields: ~8 (40%)
-- **Bloat percentage:** **40%** 🏆 **BEST SCORE!**
-
-**Aggressive Cleanup Estimate:**
-
-- Used fields: ~8 (40%)
-- Unused fields: ~12 (60%)
-- **Bloat percentage:** **60%**
-
-### Detailed Bloat Analysis:
-
-#### Conservative Cleanup (8 variables):
-
-**Remove Always (4 variables):**
-
-1. `risk_assessment_enabled: true` - Always enabled (that's the point!)
-2. `auto_load_knowledge: true` - Always load knowledge
-3. `include_mitigation_plan: true` - Always include
-4. `include_gate_criteria: true` - Always include
-
-**Remove Empty Placeholders (2 variables):** 5. `epic_num: ""` 6. `story_path: ""`
-
-**Remove Redundant (1 variable):** 7. `output_file`
-
-**Move to Config (1 variable):** 8. `risk_threshold: 6` - Project-wide risk threshold
-
-**Conservative Result:** 20 → 12 variables (40% reduction)
-
-#### Aggressive Cleanup (12 variables):
-
-**Add to Conservative (4 more variables):** 9. `include_risk_matrix: true` - Determined by design_level 10. `include_coverage_matrix: true` - Determined by design_level 11. `include_execution_order: true` - Determined by design_level 12. `include_resource_estimates: true` - Determined by design_level
-
-**Aggressive Result:** 20 → 8 variables (60% reduction)
-
-#### After Conservative Cleanup, Keep:
-
-1. `design_level: "full"` - Choice
-2. `selective_testing_strategy: "risk-based"` - Choice
-3. `standalone_mode: false` - Mode
-4. `risk_categories, priority_levels, test_levels` - Standard lists (maybe hardcode)
-5. `include_risk_matrix, include_coverage_matrix, include_execution_order, include_resource_estimates` - Output components (maybe derive from design_level)
-6. `default_output_file` - Output path
-7. Standard fields
-
----
-
-## 6. Template Variable Mapping
-
-**Workflow Type:** Document workflow (has template)
-
-**Template File:** test-design-template.md
-
-**Status:** ⚠️ **LIKELY BROKEN** - Template integration needs verification (pattern from previous audits)
-
-**Recommendation:** Verify template integration or remove template.
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-1. **Add web_bundle configuration**
-   - Severity: CRITICAL
-   - Impact: Enables web deployment
-
-### Important (Address Soon)
-
-2. **Fix template integration**
-   - Severity: IMPORTANT
-   - Impact: Template functionality
-
-3. **Add config variable usage**
-   - Severity: IMPORTANT
-   - Impact: BMAD v6 compliance
-
-### Cleanup (Nice to Have)
-
-4. **Conservative cleanup (8 variables - 40% reduction)**
-   - Remove: risk_assessment_enabled, auto_load_knowledge, include_mitigation_plan, include_gate_criteria
-   - Remove: epic_num, story_path placeholders (use <ask>)
-   - Remove: output_file redundancy
-   - Move: risk_threshold to project config
-   - Severity: CLEANUP
-   - Impact: Cleaner, more maintainable
-
-5. **Aggressive cleanup (12 variables - 60% reduction)**
-   - Add to conservative: Remove 4 include\_\* flags, derive from design_level
-   - Example: design_level="minimal" → skip resource estimates and execution order automatically
-   - Severity: CLEANUP (optional)
-   - Impact: Even cleaner configuration
-
-6. **Hardcode standard lists (3 variables)**
-   - risk_categories: "TECH,SEC,PERF,DATA,BUS,OPS" - Standard TEA categories
-   - priority_levels: "P0,P1,P2,P3" - Standard priorities
-   - test_levels: "e2e,api,integration,unit,component" - Standard levels
-   - Severity: CLEANUP (optional)
-   - Impact: Further simplification
-
----
-
-## Validation Checklist
-
-- [x] All standard config variables present ✅
-- [ ] No unused yaml fields (conservative: 40% bloat, aggressive: 60%)
-- [ ] Config variables used appropriately
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped
-- [x] File structure follows v6 conventions ✅
-- [ ] Variables reduced from 20 to 8-12
-- [x] Document workflow correctly configured ✅
-- [x] **BEST BLOAT SCORE** among all workflows! ✅
-
----
-
-## Next Steps
-
-1. **Fix web_bundle** immediately
-2. **Address template integration** and config usage
-3. **Consider conservative cleanup** - 40% bloat reduction
-4. **Consider aggressive cleanup** - 60% bloat reduction (if design_level determines output)
-5. **Re-run audit** after fixes
-
-**Cleanup Impact:**
-
-- Conservative: 20 → 12 variables (40% reduction)
-- Aggressive: 20 → 8 variables (60% reduction)
-- Bloat: 40-60% → 0%
-- Maintainability: Improved
-- Web deployment: Enabled
-
----
-
-## Positive Observations
-
-1. ✅ **BEST BLOAT SCORE!**
-   - Only 40% bloat (conservative estimate)
-   - Lowest of all 8 audited workflows
-   - Most variables have legitimate purpose
-
-2. ✅ **Good Design Choices**
-   - design_level (full/targeted/minimal) - legitimate
-   - selective_testing_strategy (risk-based/coverage-based/hybrid) - legitimate
-   - standalone_mode (with/without epic context) - legitimate
-
-3. ✅ **Proper Document Workflow Structure**
-   - Has template file
-   - Clear output path
-
-4. ✅ **Good Risk Assessment**
-   - Risk categories defined
-   - Priority levels standardized
-   - Gate criteria included
-
-5. ✅ **Knowledge Base Integration**
-   - References tea-index.csv
-   - Loads risk assessment fragments
-
-**Overall:** This is the BEST workflow of all 8 audited! Lowest bloat (40%), most legitimate variables, good design choices. Still needs web_bundle, template integration, and config usage fixes. Conservative cleanup (40%) would make this excellent. Aggressive cleanup (60%) would make this exceptional.
-
-**Why This Workflow Is Better:**
-
-- Variables like design_level and selective_testing_strategy are legitimate CHOICES
-- Include\_\* flags affect OUTPUT COMPONENTS, not methodology (unlike other workflows)
-- No methodology-breaking variables (like start_failing: false or assess_security: false)
-- Cleaner separation between configuration and requirements
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0
-
-🏆 **BEST WORKFLOW AWARD:** Lowest bloat (40%) of all 8 audited workflows!

docs/testarch-file-review/audit-report-testarch-test-review-2025-10-16.md

@@ -1,487 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** testarch-test-review
-**Audit Date:** 2025-10-16
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Document workflow (has template)
-**Workflow Path:** `/Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/testarch/test-review`
-
----
-
-## Executive Summary
-
-**Overall Status:** ⚠️ CONCERNS - Significant bloat detected, missing web_bundle configuration
-
-- Critical Issues: 1
-- Important Issues: 2
-- Cleanup Recommendations: 4
-
-**Key Findings:**
-
-1. ✅ Standard config block is correctly configured
-2. ✅ Document workflow correctly configured (has template file)
-3. ❌ **SEVERE BLOAT:** 30+ variables defined with ~75% bloat
-4. ❌ No web_bundle configuration (critical for web deployment)
-5. ⚠️ Config variable usage missing
-6. ⚠️ Template integration likely broken (needs verification)
-
----
-
-## 1. Standard Config Block Validation
-
-### Required Variables Check
-
-✅ **Config Source Check:**
-
-- [x] `config_source` is defined: `"{project-root}/bmad/bmm/config.yaml"`
-- [x] Points to correct module config path (bmm)
-- [x] Uses {project-root} variable
-
-✅ **Standard Variables Check:**
-
-- [x] `output_folder` pulls from config_source: `"{config_source}:output_folder"`
-- [x] `user_name` pulls from config_source: `"{config_source}:user_name"`
-- [x] `communication_language` pulls from config_source: `"{config_source}:communication_language"`
-- [x] `date` is set to system-generated: `"system-generated"`
-
-**Status:** ✅ **PASS** - All standard config variables present and correctly configured
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### Variables Analysis
-
-**Total YAML fields analyzed:** 30+ variables defined in workflow.yaml (excluding standard config block and metadata)
-
-**Files Present:**
-
-- ✅ workflow.yaml
-- ✅ instructions.md (608 lines)
-- ✅ checklist.md
-- ✅ test-review-template.md (template file for document workflow)
-- ✅ README.md
-
-**Workflow Type:** Document workflow (has `template: "{installed_path}/test-review-template.md"`)
-
-### Bloat Analysis (Pattern Match with Previous Workflows):
-
-#### Category 1: Boolean Behavior Flags (18+ variables - likely all generate outputs unconditionally)
-
-Based on pattern observed in ci and trace workflows, these boolean flags likely have no effect:
-
-1. **`quality_score_enabled: true`** - Quality score likely always calculated
-2. **`append_to_file: false`** - Output mode, may be used
-3. **`check_against_knowledge: true`** - Knowledge base likely always used
-4. **`strict_mode: false`** - Advisory mode likely default
-5. **`check_given_when_then: true`** - All checks likely always performed
-6. **`check_test_ids: true`** - All checks likely always performed
-7. **`check_priority_markers: true`** - All checks likely always performed
-8. **`check_hard_waits: true`** - All checks likely always performed
-9. **`check_determinism: true`** - All checks likely always performed
-10. **`check_isolation: true`** - All checks likely always performed
-11. **`check_fixture_patterns: true`** - All checks likely always performed
-12. **`check_data_factories: true`** - All checks likely always performed
-13. **`check_network_first: true`** - All checks likely always performed
-14. **`check_assertions: true`** - All checks likely always performed
-15. **`check_test_length: true`** - All checks likely always performed
-16. **`check_test_duration: true`** - All checks likely always performed
-17. **`check_flakiness_patterns: true`** - All checks likely always performed
-18. **`use_story_file: true`** - Story loading likely always attempted
-19. **`use_test_design: true`** - Test design loading likely always attempted
-20. **`auto_discover_story: true`** - Auto-discovery likely default behavior
-21. **`generate_inline_comments: false`** - Output option, may be used
-22. **`generate_quality_badge: true`** - Badge likely always generated
-23. **`append_to_story: false`** - Output option, may be used
-
-**Impact:** 23 boolean flags that likely create false impression of configurability. The workflow probably performs ALL quality checks regardless of these flags.
-
-**Recommendation:** Consolidate to ~3 real choices:
-
-- `review_scope: "single" | "directory" | "suite"` - KEEP
-- `output_mode: "inline" | "separate" | "both"` - Merge append_to_file, generate_inline_comments, append_to_story
-- `strict_mode: false` - KEEP (affects whether violations block or advise)
-
-Remove ALL 16 check\_\* flags. Always perform ALL quality checks (that's the point of a review workflow).
-
-#### Category 2: Empty Placeholders (1 variable)
-
-24. **`test_file_path: ""`** - Should use <ask> tag to elicit
-
-**Recommendation:** Remove. Use <ask> in instructions to get test file path.
-
-#### Category 3: Knowledge Fragment List (Hardcoded)
-
-25. **`knowledge_fragments:`** - List of 8 fragments
-
-- This is HARDCODED in yaml as a list
-- Instructions should load these directly from tea-index.csv
-- List belongs in instructions, not yaml variables
-
-**Recommendation:** Remove knowledge_fragments variable. Instructions should reference tea-index.csv directly with fragment names in the instructions themselves.
-
-#### Category 4: Redundant Output Paths (1 variable)
-
-26. **`output_file: "{output_folder}/test-review-{filename}.md"`**
-
-- Duplicates default_output_file functionality
-- Should be calculated in instructions based on filename
-
-**Recommendation:** Remove. Use default_output_file and calculate specific filename in instructions.
-
-#### Category 5: Acceptable Variables (Keep These)
-
-1. **`test_dir: "{project-root}/tests"`** - KEEP (standard path)
-2. **`review_scope: "single"`** - KEEP (legitimate choice: single, directory, suite)
-3. **`default_output_file: "{output_folder}/test-review.md"`** - KEEP (standard workflow output)
-4. **`installed_path`, `instructions`, `validation`, `template`** - KEEP (standard workflow fields)
-
-**Total Variables Analyzed:** 30+ variables
-**Legitimate Variables:** ~7 (test_dir, review_scope, strict_mode, output_mode_consolidated, default_output_file + standard fields)
-**Bloat:** ~23+ variables (77% bloat)
-
-**Status:** ❌ **FAIL** - SEVERE bloat (77% of variables unused or redundant)
-
----
-
-## 3. Config Variable Usage
-
-### Communication Language Check:
-
-- ❌ **MISSING** - No "communicate in {communication_language}" pattern found (pattern from previous audits)
-- Instructions likely do not reference communication_language variable
-- Severity: IMPORTANT
-
-### User Name Check:
-
-- ❌ **MISSING** - No {user_name} usage (pattern from previous audits)
-- No personalization likely present
-- Severity: MINOR (optional for this workflow type)
-
-### Output Folder Check:
-
-- ✅ **USED** - default_output_file uses {output_folder}
-- Properly integrated
-- Severity: N/A
-
-### Date Usage Check:
-
-- ✅ **AVAILABLE** - Date defined for potential use in template
-- Severity: N/A
-
-**Status:** ⚠️ **IMPORTANT** - Config variables not fully utilized (communication_language missing)
-
----
-
-## 4. Web Bundle Validation
-
-### Web Bundle Present: ❌ **NO**
-
-**Status:** ❌ **CRITICAL** - No web_bundle configuration found
-
-The workflow.yaml contains:
-
-```yaml
-web_bundle: false
-```
-
-This means the workflow is **NOT** configured for web deployment.
-
-**Missing web_bundle requirements:**
-
-- No web_bundle_files list
-- No existing_workflows mapping
-- No web deployment path configuration
-
-**Knowledge Fragment Dependencies:**
-
-The workflow defines `knowledge_fragments` list with 8 fragments:
-
-- test-quality.md
-- fixture-architecture.md
-- network-first.md
-- data-factories.md
-- test-levels-framework.md
-- playwright-config.md
-- tdd-cycles.md
-- selective-testing.md
-
-**Template File:**
-
-- test-review-template.md
-
-**Expected web_bundle structure:**
-
-```yaml
-web_bundle:
-  workflow_path: 'bmad/bmm/workflows/testarch/test-review/workflow.yaml'
-  web_bundle_files:
-    - 'bmad/bmm/workflows/testarch/test-review/instructions.md'
-    - 'bmad/bmm/workflows/testarch/test-review/checklist.md'
-    - 'bmad/bmm/workflows/testarch/test-review/test-review-template.md'
-    - 'bmad/bmm/testarch/knowledge/test-quality.md'
-    - 'bmad/bmm/testarch/knowledge/fixture-architecture.md'
-    - 'bmad/bmm/testarch/knowledge/network-first.md'
-    - 'bmad/bmm/testarch/knowledge/data-factories.md'
-    - 'bmad/bmm/testarch/knowledge/test-levels-framework.md'
-    - 'bmad/bmm/testarch/knowledge/playwright-config.md'
-    - 'bmad/bmm/testarch/knowledge/tdd-cycles.md'
-    - 'bmad/bmm/testarch/knowledge/selective-testing.md'
-    - 'bmad/bmm/testarch/tea-index.csv'
-```
-
-**Impact:** This workflow cannot be bundled for web deployment without web_bundle configuration.
-
-**Severity:** CRITICAL (if web deployment is intended)
-
----
-
-## 5. Bloat Detection
-
-### Unused YAML Fields Analysis
-
-**Total YAML fields:** 30+ variables (excluding standard config and metadata)
-**Used fields:** ~7 (23%)
-**Unused fields:** ~23+ (77%)
-**Bloat percentage:** **77%**
-
-### Detailed Bloat Analysis:
-
-#### Category 1: 16 check\_\* Boolean Flags (All Quality Checks Performed Unconditionally)
-
-These 16 variables suggest optional quality checks, but a review workflow should ALWAYS perform ALL checks:
-
-1. `check_given_when_then: true`
-2. `check_test_ids: true`
-3. `check_priority_markers: true`
-4. `check_hard_waits: true`
-5. `check_determinism: true`
-6. `check_isolation: true`
-7. `check_fixture_patterns: true`
-8. `check_data_factories: true`
-9. `check_network_first: true`
-10. `check_assertions: true`
-11. `check_test_length: true`
-12. `check_test_duration: true`
-13. `check_flakiness_patterns: true`
-
-**Recommendation:** Remove ALL 13 check\_\* flags. A test quality review should ALWAYS check ALL quality criteria. That's the point of a review workflow.
-
-**Rationale:** Allowing users to disable quality checks defeats the purpose of code review. Instructions should perform comprehensive review unconditionally.
-
-#### Category 2: 7 Additional Boolean/Control Flags
-
-14. `quality_score_enabled: true` - Quality score should always be calculated
-15. `append_to_file: false` - Output mode flag
-16. `check_against_knowledge: true` - Knowledge base should always be used
-17. `strict_mode: false` - KEEP (affects violation handling)
-18. `use_story_file: true` - Story loading should be auto-attempted
-19. `use_test_design: true` - Test design loading should be auto-attempted
-20. `auto_discover_story: true` - Auto-discovery should be default
-21. `generate_inline_comments: false` - Output mode flag
-22. `generate_quality_badge: true` - Badge should always be generated
-23. `append_to_story: false` - Output mode flag
-
-**Recommendation:**
-
-- Remove: quality_score_enabled, check_against_knowledge, use_story_file, use_test_design, auto_discover_story, generate_quality_badge (always perform these)
-- Keep: strict_mode (legitimate choice)
-- Consolidate output mode flags (append_to_file, generate_inline_comments, append_to_story) into single `output_mode` variable
-
-#### Category 3: Hardcoded Knowledge Fragment List
-
-24. `knowledge_fragments:` - Hardcoded list of 8 fragments
-
-**Recommendation:** Remove. Instructions should reference fragments directly from tea-index.csv. The fragment names should appear in the instructions, not in a yaml list.
-
-#### Category 4: Empty Placeholder
-
-25. `test_file_path: ""` - Empty placeholder
-
-**Recommendation:** Remove. Use <ask> tag in instructions to elicit test file path.
-
-#### Category 5: Redundant Output Path
-
-26. `output_file: "{output_folder}/test-review-{filename}.md"`
-
-**Recommendation:** Remove. Use default_output_file and calculate specific filename in instructions.
-
-**Total Bloat Items:** 23+ variables
-
-**Bloat Percentage:** 77%
-**Cleanup Potential:** EXTREME - Removing bloat would reduce variables from 30+ to ~7
-
-**After Cleanup, Only These Should Remain:**
-
-1. `test_dir: "{project-root}/tests"` - Standard path
-2. `review_scope: "single"` - User choice (single/directory/suite)
-3. `strict_mode: false` - Violation handling mode
-4. `output_mode: "separate"` - Output mode (separate/inline/both) - consolidated from 3 flags
-5. `default_output_file: "{output_folder}/test-review.md"` - Output path
-6. `installed_path`, `instructions`, `validation`, `template` - Standard workflow fields
-
----
-
-## 6. Template Variable Mapping
-
-**Workflow Type:** Document workflow (has template file)
-
-**Template File:** test-review-template.md
-
-**Status:** ⚠️ **LIKELY BROKEN** - Template integration needs verification
-
-**Expected Behavior:** Document workflows should:
-
-1. Have `<template-output>` tags in instructions.md
-2. Use `{{variable_name}}` format in template
-3. Map template variables to instruction outputs
-
-**Likely Issue (based on trace workflow pattern):**
-
-- Template likely uses `{UPPERCASE}` pattern instead of `{{lowercase}}`
-- Instructions likely lack `<template-output>` tags
-- Template/instruction integration likely broken
-
-**Recommendation:** Verify template integration. Either:
-
-1. Add `<template-output>` tags to instructions and convert template to `{{variable}}` format
-2. Remove template, set `template: false`, make this an action workflow
-
-**Severity:** IMPORTANT - Template integration likely non-functional
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-1. **Add web_bundle configuration**
-   - Add web_bundle block with all required files (instructions, checklist, template)
-   - Map knowledge fragments (8 fragments from knowledge_fragments list)
-   - Include tea-index.csv for knowledge base access
-   - Enable web deployment capability
-   - Severity: CRITICAL
-   - Impact: Workflow cannot be deployed to web without this
-
-### Important (Address Soon)
-
-2. **Fix template integration**
-   - Verify template uses `{{variable}}` format (not `{UPPERCASE}`)
-   - Add `<template-output>` tags to instructions
-   - OR remove template and make this an action workflow
-   - Current hybrid state likely broken
-   - Severity: IMPORTANT
-   - Impact: Template not being populated
-
-3. **Add config variable usage in instructions**
-   - Add communication_language support for multilingual workflows
-   - Add greeting or summary using {user_name}
-   - Ensure proper integration with BMAD v6 config standards
-   - Severity: IMPORTANT
-   - Impact: Workflows not following BMAD v6 conventions
-
-### Cleanup (Nice to Have)
-
-4. **Remove ALL check\_\* boolean flags (13 variables)**
-   - Delete all check\_\* variables
-   - Always perform ALL quality checks in instructions
-   - A review workflow should be comprehensive, not configurable
-   - Rationale: Allowing users to disable checks defeats the purpose of code review
-   - Severity: CLEANUP
-   - Impact: Reduces bloat by 43%, improves clarity
-
-5. **Remove unnecessary control flags (7 variables)**
-   - Delete: quality_score_enabled, check_against_knowledge, use_story_file, use_test_design, auto_discover_story, generate_quality_badge
-   - Always perform these actions (that's the point of a review)
-   - Keep: strict_mode (legitimate choice)
-   - Severity: CLEANUP
-   - Impact: Further reduces bloat
-
-6. **Consolidate output mode flags**
-   - Merge: append_to_file, generate_inline_comments, append_to_story
-   - Create single: `output_mode: "separate" | "inline" | "both"`
-   - Severity: CLEANUP
-   - Impact: Simplifies configuration
-
-7. **Remove hardcoded knowledge fragment list**
-   - Delete: knowledge_fragments variable
-   - Reference fragments directly in instructions with tea-index.csv
-   - Fragment names should appear in instruction steps, not yaml
-   - Severity: CLEANUP
-   - Impact: Cleaner yaml, better instruction clarity
-
-8. **Remove empty placeholder and redundant paths**
-   - Delete: test_file_path (use <ask> tag)
-   - Delete: output_file (use default_output_file)
-   - Severity: CLEANUP
-   - Impact: Removes unnecessary variables
-
----
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
-- [x] All standard config variables present and correct ✅ (Already passing)
-- [ ] No unused yaml fields (bloat removed to <20%)
-- [ ] Config variables used appropriately in instructions
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped (or template removed)
-- [x] File structure follows v6 conventions ✅
-- [ ] Variables block reduced from 30+ to ~7 essential variables
-- [ ] All check\_\* flags removed (comprehensive review always performed)
-- [ ] Output mode flags consolidated
-- [ ] Knowledge fragment list removed (referenced in instructions)
-- [x] Document workflow correctly configured (has template) ✅
-
----
-
-## Next Steps
-
-1. **Review critical issues** and fix web_bundle configuration immediately
-2. **Address important issues** in next iteration (template integration, config usage)
-3. **Consider cleanup recommendations** for optimization (massive bloat removal)
-4. **Re-run audit** after fixes to verify improvements
-
-**Estimated Cleanup Impact:**
-
-- Variables: 30+ → 7 (77% reduction)
-- Bloat: 77% → 0%
-- Maintainability: Dramatically improved
-- Clarity: Much clearer (comprehensive review vs false configurability)
-- Web deployment: Enabled (after web_bundle added)
-
----
-
-## Positive Observations
-
-**What This Workflow Does Well:**
-
-1. ✅ **Comprehensive Quality Criteria**
-   - 13 quality checks defined (Given-When-Then, test IDs, hard waits, determinism, etc.)
-   - Knowledge base integration (8 fragments)
-   - Story and test design integration
-   - Quality scoring
-
-2. ✅ **Proper Document Workflow Structure**
-   - Has template file (test-review-template.md)
-   - Configured as document workflow
-   - Clear output path
-
-3. ✅ **Good Scope Options**
-   - Single file review
-   - Directory review
-   - Full suite review
-
-4. ✅ **Knowledge Base Integration**
-   - References tea-index.csv
-   - Loads 8 relevant knowledge fragments
-   - Comprehensive best practices coverage
-
-**Overall:** This is a well-designed workflow with comprehensive quality criteria but SEVERE bloat. The 13 check\_\* boolean flags create false impression that quality checks are optional, when they should ALWAYS be performed. Removing bloat would make this an excellent workflow.
-
-**The Review Paradox:** A quality review workflow should ALWAYS check ALL quality criteria. Making checks optional defeats the purpose of code review. The bloat suggests configurability that shouldn't exist.
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0

docs/testarch-file-review/audit-report-testarch-trace-2025-10-16.md

@@ -1,436 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** testarch-trace
-**Audit Date:** 2025-10-16
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Document workflow (template-based)
-**Workflow Path:** `/Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/testarch/trace`
-
----
-
-## Executive Summary
-
-**Overall Status:** ⚠️ CONCERNS - Significant bloat detected, missing web_bundle configuration
-
-- Critical Issues: 1
-- Important Issues: 2
-- Cleanup Recommendations: 8
-
-**Key Findings:**
-
-1. ✅ Standard config block is correctly configured
-2. ⚠️ Massive bloat detected - 52 variables defined in workflow.yaml with extensive unused fields
-3. ❌ No web_bundle configuration (critical for web deployment)
-4. ⚠️ Config variable usage needs improvement in instructions
-
----
-
-## 1. Standard Config Block Validation
-
-### Required Variables Check
-
-✅ **Config Source Check:**
-
-- [x] `config_source` is defined: `"{project-root}/bmad/bmm/config.yaml"`
-- [x] Points to correct module config path (bmm)
-- [x] Uses {project-root} variable
-
-✅ **Standard Variables Check:**
-
-- [x] `output_folder` pulls from config_source: `"{config_source}:output_folder"`
-- [x] `user_name` pulls from config_source: `"{config_source}:user_name"`
-- [x] `communication_language` pulls from config_source: `"{config_source}:communication_language"`
-- [x] `date` is set to system-generated: `"system-generated"`
-
-**Status:** ✅ **PASS** - All standard config variables present and correctly configured
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-### Variables Analysis
-
-**Total YAML fields analyzed:** 52 variables defined in workflow.yaml (excluding standard config block and metadata)
-
-**Categorization:**
-
-#### INSTRUCTION_USED (Variables referenced in instructions.md):
-
-The following variables appear to be contextually referenced in the instructions but NOT with explicit {variable_name} syntax:
-
-- story_file (mentioned conceptually in "Read story file")
-- test_dir (mentioned as test directory)
-- source_dir (mentioned as source directory)
-- coverage_levels (conceptually referenced in coverage analysis)
-- output_file (used in deliverables)
-- gate_type (used in Phase 2)
-- decision_mode (used in decision rules)
-- test_results (required for Phase 2)
-- nfr_file (optional NFR loading)
-- Various threshold values (min_p0_coverage, etc.) used in decision rules
-
-#### TEMPLATE_USED (Variables referenced in trace-template.md):
-
-Template uses these placeholder patterns:
-
-- {STORY_ID}, {STORY_TITLE}, {DATE}
-- {P0_TOTAL}, {P0_FULL}, {P0_PCT}, {P0_STATUS}
-- {P1_TOTAL}, {P1_FULL}, {P1_PCT}, {P1_STATUS}
-- {P2_TOTAL}, {P2_FULL}, {P2_PCT}, {P2_STATUS}
-- {P3_TOTAL}, {P3_FULL}, {P3_PCT}, {P3_STATUS}
-- {TOTAL}, {FULL}, {PCT}, {STATUS}
-- {CRITERION_ID}, {CRITERION_DESCRIPTION}, {PRIORITY}
-- {COVERAGE_STATUS}, {STATUS_ICON}
-- {TEST_ID}, {TEST_FILE}, {LINE}
-- {GIVEN}, {WHEN}, {THEN}
-- Many more...
-
-**CRITICAL ISSUE:** Template uses curly braces `{VARIABLE}` instead of double curly braces `{{variable}}`. This is inconsistent with BMAD v6 template variable standards which use `{{variable_name}}` notation.
-
-#### UNUSED_BLOAT (Variables defined but NOT explicitly used in instructions or template):
-
-This is where MASSIVE bloat exists. The workflow.yaml contains 52 variables, most of which are:
-
-1. Boolean configuration flags (auto_discover_tests, map_by_test_id, require_explicit_mapping, etc.)
-2. Threshold numbers (min_p0_coverage, min_p1_pass_rate, etc.)
-3. Path specifications that should be derived, not pre-configured
-
-**Bloat Items:**
-
-- acceptance_criteria (empty string, should be elicited)
-- auto_discover_tests, map_by_test_id, map_by_describe, map_by_filename (behavior flags that should be workflow defaults, not variables)
-- require_explicit_mapping, flag_unit_only, flag_integration_only, flag_partial_coverage (all behavior configuration)
-- prioritize_by_risk, suggest_missing_tests, check_duplicate_coverage (more behavior flags)
-- use_test_design, use_tech_spec, use_prd (file loading flags - should be automatic)
-- generate_gate_yaml, generate_coverage_badge, update_story_file (output control flags)
-- min_p0_coverage, min_p1_coverage, min_overall_coverage (threshold config)
-- auto_load_knowledge, include_code_coverage, check_assertions (more behavior flags)
-- enable_gate_decision (Phase 2 control flag)
-- allow_waivers, require_evidence, check_all_workflows_complete, validate_evidence_freshness, require_sign_off (gate configuration)
-- min_p0_pass_rate, min_p1_pass_rate, min_overall_pass_rate (more thresholds)
-- max_critical_nfrs_fail, max_security_issues (threshold config)
-- allow_p2_failures, allow_p3_failures, escalate_p1_failures (risk tolerance flags)
-- gate_output_file, append_to_history, notify_stakeholders (output configuration)
-
-**Total Variables Analyzed:** 52 variables
-**Used in Instructions (explicitly):** ~10-15 conceptually (but not with {variable_name} syntax)
-**Used in Template:** 0 (template uses {UPPERCASE} pattern, not {{yaml_variables}})
-**Unused (Bloat):** ~35-40 variables (75%+ of defined variables!)
-
-**Status:** ❌ **FAIL** - Severe bloat detected (75%+ unused variables)
-
----
-
-## 3. Config Variable Usage
-
-### Communication Language Check:
-
-- ❌ **MISSING** - No "communicate in {communication_language}" pattern found in instructions
-- Instructions do not reference communication_language variable
-- Severity: IMPORTANT
-
-### User Name Check:
-
-- ❌ **MISSING** - No {user_name} usage found in instructions
-- No personalization or greeting patterns detected
-- Severity: MINOR (optional for this workflow type)
-
-### Output Folder Check:
-
-- ⚠️ **PARTIAL** - Output folder is referenced in workflow.yaml (`output_file: "{output_folder}/..."`), but instructions don't explicitly use {output_folder} variable pattern
-- File writes mention saving to output_folder conceptually
-- Severity: MINOR
-
-### Date Usage Check:
-
-- ✅ **USED** - Date is available in workflow.yaml and used in template as {DATE}
-- Severity: N/A
-
-**Status:** ⚠️ **IMPORTANT** - Config variables not properly utilized in instructions
-
----
-
-## 4. Web Bundle Validation
-
-### Web Bundle Present: ❌ **NO**
-
-**Status:** ❌ **CRITICAL** - No web_bundle configuration found
-
-The workflow.yaml contains:
-
-```yaml
-web_bundle: false
-```
-
-This means the workflow is **NOT** configured for web deployment. For a production workflow, this is a critical omission.
-
-**Missing web_bundle requirements:**
-
-- No web_bundle_files list
-- No existing_workflows mapping (critical since instructions reference knowledge fragments and other workflows)
-- No web deployment path configuration
-
-**Workflow Dependencies Detected in Instructions:**
-The instructions reference loading knowledge fragments:
-
-- `test-priorities-matrix.md`
-- `risk-governance.md`
-- `probability-impact.md`
-- `test-quality.md`
-- `selective-testing.md`
-
-These fragments should be declared in a web_bundle configuration.
-
-**Impact:** This workflow cannot be bundled for web deployment without web_bundle configuration.
-
-**Severity:** CRITICAL (if web deployment is intended)
-
----
-
-## 5. Bloat Detection
-
-### Unused YAML Fields Analysis
-
-**Total YAML fields:** 52 variables (excluding standard config and metadata)
-**Used fields:** ~15 (estimated, mostly conceptual usage, not explicit {variable} references)
-**Unused fields:** ~37
-**Bloat percentage:** **71%**
-
-### Bloat Categories:
-
-#### Category 1: Boolean Behavior Flags (Should be workflow defaults, not variables)
-
-These should be removed from variables and implemented as hardcoded workflow behavior:
-
-1. `auto_discover_tests: true` - This should be the default workflow behavior
-2. `map_by_test_id: true` - Mapping strategy should be built into the workflow
-3. `map_by_describe: true` - Same as above
-4. `map_by_filename: true` - Same as above
-5. `require_explicit_mapping: true` - Quality standard, not a variable
-6. `flag_unit_only: true` - Analysis behavior, not configurable
-7. `flag_integration_only: true` - Same
-8. `flag_partial_coverage: true` - Same
-9. `prioritize_by_risk: true` - Core workflow principle
-10. `suggest_missing_tests: true` - Core workflow output
-11. `check_duplicate_coverage: true` - Quality check, not configurable
-12. `use_test_design: true` - Should auto-detect file existence
-13. `use_tech_spec: true` - Same
-14. `use_prd: true` - Same
-15. `generate_gate_yaml: true` - Core workflow output
-16. `generate_coverage_badge: true` - Optional output, could be removed
-17. `update_story_file: true` - Optional behavior, could be removed
-18. `auto_load_knowledge: true` - Should be default behavior
-19. `include_code_coverage: false` - Optional feature flag, acceptable to keep
-20. `check_assertions: true` - Quality check, not configurable
-21. `enable_gate_decision: true` - Workflow mode, could be simplified
-22. `allow_waivers: true` - Gate policy, could be hardcoded or project-level config
-23. `require_evidence: true` - Gate policy, should be default
-24. `check_all_workflows_complete: true` - Validation behavior
-25. `validate_evidence_freshness: true` - Quality check
-26. `require_sign_off: false` - Optional gate requirement
-27. `allow_p2_failures: true` - Risk policy
-28. `allow_p3_failures: true` - Risk policy
-29. `escalate_p1_failures: true` - Risk policy
-30. `append_to_history: true` - Output behavior
-31. `notify_stakeholders: true` - Output behavior
-
-**Recommendation:** Remove 25+ boolean flags. These should be workflow defaults or auto-detected behaviors, not user-configurable variables.
-
-#### Category 2: Threshold Configuration (Should be project-level config, not workflow variables)
-
-These belong in module config.yaml or project-specific configuration, not workflow.yaml:
-
-1. `min_p0_coverage: 100`
-2. `min_p1_coverage: 90`
-3. `min_overall_coverage: 80`
-4. `min_p0_pass_rate: 100`
-5. `min_p1_pass_rate: 95`
-6. `min_overall_pass_rate: 90`
-7. `max_critical_nfrs_fail: 0`
-8. `max_security_issues: 0`
-
-**Recommendation:** Move thresholds to bmm/config.yaml as project-wide quality standards. Reference via {config_source}:threshold_name pattern.
-
-#### Category 3: Empty/Placeholder Variables (Should be elicited, not pre-declared)
-
-1. `story_file: ""` - Should be elicited with <ask> tag
-2. `acceptance_criteria: ""` - Same
-3. `nfr_file: ""` - Optional, should be elicited if needed
-4. `test_results: ""` - Should be elicited for Phase 2
-
-**Recommendation:** Remove empty variables. Use <ask> tags in instructions to elicit required inputs.
-
-#### Category 4: Derived/Output Paths (Should be calculated in workflow, not pre-defined)
-
-1. `test_dir: "{project-root}/tests"` - Should be auto-detected or elicited
-2. `source_dir: "{project-root}/src"` - Same
-3. `output_file: "{output_folder}/traceability-matrix.md"` - Duplicates default_output_file
-4. `gate_output_file: "{output_folder}/gate-decision-{gate_type}-{story_id}{epic_num}{release_version}.md"` - Complex derivation
-
-**Recommendation:** Remove redundant path variables. Use default_output_file or calculate paths in instructions.
-
-#### Category 5: Acceptable Variables (Keep these)
-
-These variables have legitimate workflow-specific purpose:
-
-1. `coverage_levels: "e2e,api,component,unit"` - Customizable test level scope
-2. `gate_type: "story"` - Determines gate scope (story/epic/release/hotfix)
-3. `decision_mode: "deterministic"` - Affects decision process
-4. `installed_path`, `instructions`, `validation`, `template` - Standard workflow paths (KEEP)
-
-**Total Bloat Items:** 35+ variables that should be removed or relocated
-
-**Bloat Percentage:** 71%
-**Cleanup Potential:** HIGH - Removing bloat would reduce workflow.yaml from 146 lines to ~30-40 lines
-
----
-
-## 6. Template Variable Mapping
-
-### Template Variables Analysis
-
-**Template Variable Pattern:** Template uses `{UPPERCASE_VARIABLE}` format (e.g., {STORY_ID}, {P0_TOTAL})
-
-**Critical Issue:** ❌ BMAD v6 standard uses `{{lowercase_variable}}` format for template variables.
-
-The trace-template.md uses 60+ template placeholders with `{UPPERCASE}` pattern instead of `{{variable_name}}` pattern.
-
-### Cross-Reference with Instructions
-
-**Instructions <template-output> tags:** None found in instructions.md
-
-**Critical Problem:** The instructions.md file does NOT contain `<template-output>` tags to map workflow outputs to template variables.
-
-**Workflow Type:** Document workflow (has template: "{installed_path}/trace-template.md")
-
-**Expected Behavior:** Document workflows should have <template-output> tags in instructions to populate template sections.
-
-**Actual Behavior:** Instructions are written as pure procedural markdown without template-output integration.
-
-**Impact:** This workflow appears to be a HYBRID workflow (action + document) but is configured as a document workflow. The template exists but isn't integrated with the workflow execution.
-
-**Recommendation:**
-
-1. Either remove the template and set `template: false` (make it an action workflow)
-2. Or refactor instructions to use <template-output> tags and update template to use {{variable}} pattern
-
-**Status:** ❌ **IMPORTANT** - Template/instruction integration broken
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-1. **Add web_bundle configuration**
-   - Add web_bundle block with all required files (instructions, template, checklist)
-   - Map knowledge fragments (test-priorities-matrix.md, risk-governance.md, etc.)
-   - Enable web deployment capability
-   - Severity: CRITICAL
-   - Impact: Workflow cannot be deployed to web without this
-
-### Important (Address Soon)
-
-2. **Fix template integration**
-   - Either: Remove template, set `template: false`, make this an action workflow
-   - Or: Add <template-output> tags to instructions and convert template to {{variable}} format
-   - Current hybrid state is broken
-   - Severity: IMPORTANT
-   - Impact: Template is not being populated by workflow execution
-
-3. **Add config variable usage in instructions**
-   - Add communication_language support for multilingual workflows
-   - Consider adding user_name for personalization (optional)
-   - Ensure output_folder is explicitly used in all file write operations
-   - Severity: IMPORTANT
-   - Impact: Workflows not following BMAD v6 config standards
-
-### Cleanup (Nice to Have)
-
-4. **Remove boolean behavior flags (25+ variables)**
-   - Delete: auto_discover_tests, map_by_test_id, require_explicit_mapping, flag_unit_only, prioritize_by_risk, suggest_missing_tests, check_duplicate_coverage, use_test_design, generate_gate_yaml, auto_load_knowledge, check_assertions, enable_gate_decision, require_evidence, check_all_workflows_complete, allow_p2_failures, escalate_p1_failures, append_to_history, notify_stakeholders, etc.
-   - These should be workflow defaults, not user-configurable variables
-   - Severity: CLEANUP
-   - Impact: Reduces bloat from 71% to ~15%, improves maintainability
-
-5. **Move threshold configuration to module config**
-   - Move to bmm/config.yaml: min_p0_coverage, min_p1_coverage, min_overall_coverage, min_p0_pass_rate, min_p1_pass_rate, min_overall_pass_rate, max_critical_nfrs_fail, max_security_issues
-   - Reference via {config_source}:threshold_name
-   - Severity: CLEANUP
-   - Impact: Centralizes quality standards, enables project-wide consistency
-
-6. **Remove empty placeholder variables**
-   - Delete: story_file: "", acceptance_criteria: "", nfr_file: "", test_results: ""
-   - Use <ask> tags in instructions to elicit these inputs
-   - Severity: CLEANUP
-   - Impact: Cleaner workflow.yaml, more dynamic input gathering
-
-7. **Remove redundant path variables**
-   - Delete: output_file (duplicates default_output_file)
-   - Auto-detect or elicit: test_dir, source_dir
-   - Simplify: gate_output_file (calculate in instructions)
-   - Severity: CLEANUP
-   - Impact: Reduces path configuration redundancy
-
-8. **Simplify variables block**
-   - Keep only: coverage_levels, gate_type, decision_mode, include_code_coverage (optional feature flag)
-   - Remove everything else per recommendations 4-7
-   - Severity: CLEANUP
-   - Impact: Workflow.yaml drops from 146 lines to ~35 lines (76% reduction)
-
-9. **Fix template variable naming convention**
-   - Convert {UPPERCASE} to {{lowercase_variable}} throughout trace-template.md
-   - Align with BMAD v6 standards
-   - Severity: CLEANUP
-   - Impact: Template consistency with framework standards
-
-10. **Add <ask> tags for required inputs**
-    - Add <ask> for story_file path at start of workflow
-    - Add <ask> for test_results path before Phase 2
-    - Add conditional <ask> for nfr_file if release-level gate
-    - Severity: CLEANUP
-    - Impact: Makes workflow properly interactive
-
-11. **Document workflow mode decision**
-    - Decide: Is this an action workflow or document workflow?
-    - If action: Remove template, set template: false
-    - If document: Add <template-output> tags and integrate template properly
-    - Severity: CLEANUP
-    - Impact: Clarifies workflow purpose and execution model
-
----
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
-- [ ] All standard config variables present and correct ✅ (Already passing)
-- [ ] No unused yaml fields (bloat removed to <15%)
-- [ ] Config variables used appropriately in instructions
-- [ ] Web bundle includes all dependencies
-- [ ] Template variables properly mapped (or template removed)
-- [ ] File structure follows v6 conventions
-- [ ] Variables block reduced from 52 to ~4-5 essential variables
-- [ ] Threshold config moved to bmm/config.yaml
-- [ ] Boolean flags removed (workflow defaults)
-- [ ] Empty placeholders removed (<ask> tags added)
-
----
-
-## Next Steps
-
-1. **Review critical issues** and fix web_bundle configuration immediately
-2. **Address important issues** in next iteration (template integration, config usage)
-3. **Consider cleanup recommendations** for optimization (bloat removal)
-4. **Re-run audit** after fixes to verify improvements
-
-**Estimated Cleanup Impact:**
-
-- Workflow.yaml: 146 lines → ~35 lines (76% reduction)
-- Bloat: 71% → <15%
-- Maintainability: Significantly improved
-- Web deployment: Enabled (after web_bundle added)
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0

eslint.config.mjs

@@ -14,6 +14,8 @@ export default [
       'test/template-test-generator/**',
       'test/template-test-generator/**/*.js',
       'test/template-test-generator/**/*.md',
+      'test/fixtures/**',
+      'test/fixtures/**/*.yaml',
     ],
   },
 
@@ -59,9 +61,9 @@ export default [
     },
   },
 
-  // CLI/CommonJS scripts under tools/**
+  // CLI/CommonJS scripts under tools/** and test/**
   {
-    files: ['tools/**/*.js'],
+    files: ['tools/**/*.js', 'test/**/*.js'],
     rules: {
       // Allow CommonJS patterns for Node CLI scripts
       'unicorn/prefer-module': 'off',

package-lock.json

@@ -31,6 +31,7 @@
       },
       "devDependencies": {
         "@eslint/js": "^9.33.0",
+        "c8": "^10.1.3",
         "eslint": "^9.33.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-n": "^17.21.3",
@@ -42,7 +43,8 @@
         "prettier": "^3.5.3",
         "prettier-plugin-packagejson": "^2.5.19",
         "yaml-eslint-parser": "^1.2.3",
-        "yaml-lint": "^1.7.0"
+        "yaml-lint": "^1.7.0",
+        "zod": "^4.1.12"
       },
       "engines": {
         "node": ">=20.0.0"
@@ -93,6 +95,7 @@
       "integrity": "sha512-yDBHV9kQNcr2/sUr9jghVyz9C3Y5G2zUM2H2lo+9mKv4sFgbA8s8Z9t8D1jiTkGoO/NoIfKMyKWr4s6CN23ZwQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@ampproject/remapping": "^2.2.0",
         "@babel/code-frame": "^7.27.1",
@@ -1815,6 +1818,7 @@
       "integrity": "sha512-aPTXCrfwnDLj4VvXrm+UUCQjNEvJgNA8s5F1cvwQU+3KNltTOkBm1j30uNLyqqPNe7gE3KFzImYoZEfLhp4Yow==",
       "devOptional": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~7.10.0"
       }
@@ -2131,6 +2135,7 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -2492,6 +2497,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "caniuse-lite": "^1.0.30001735",
         "electron-to-chromium": "^1.5.204",
@@ -2559,6 +2565,152 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/c8": {
+      "version": "10.1.3",
+      "resolved": "https://registry.npmjs.org/c8/-/c8-10.1.3.tgz",
+      "integrity": "sha512-LvcyrOAaOnrrlMpW22n690PUvxiq4Uf9WMhQwNJ9vgagkL/ph1+D4uvjvDA5XCbykrc0sx+ay6pVi9YZ1GnhyA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "@bcoe/v8-coverage": "^1.0.1",
+        "@istanbuljs/schema": "^0.1.3",
+        "find-up": "^5.0.0",
+        "foreground-child": "^3.1.1",
+        "istanbul-lib-coverage": "^3.2.0",
+        "istanbul-lib-report": "^3.0.1",
+        "istanbul-reports": "^3.1.6",
+        "test-exclude": "^7.0.1",
+        "v8-to-istanbul": "^9.0.0",
+        "yargs": "^17.7.2",
+        "yargs-parser": "^21.1.1"
+      },
+      "bin": {
+        "c8": "bin/c8.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "monocart-coverage-reports": "^2"
+      },
+      "peerDependenciesMeta": {
+        "monocart-coverage-reports": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/c8/node_modules/@bcoe/v8-coverage": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-1.0.2.tgz",
+      "integrity": "sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/c8/node_modules/brace-expansion": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0"
+      }
+    },
+    "node_modules/c8/node_modules/glob": {
+      "version": "10.4.5",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.4.5.tgz",
+      "integrity": "sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "foreground-child": "^3.1.0",
+        "jackspeak": "^3.1.2",
+        "minimatch": "^9.0.4",
+        "minipass": "^7.1.2",
+        "package-json-from-dist": "^1.0.0",
+        "path-scurry": "^1.11.1"
+      },
+      "bin": {
+        "glob": "dist/esm/bin.mjs"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/c8/node_modules/jackspeak": {
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz",
+      "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "@isaacs/cliui": "^8.0.2"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      },
+      "optionalDependencies": {
+        "@pkgjs/parseargs": "^0.11.0"
+      }
+    },
+    "node_modules/c8/node_modules/lru-cache": {
+      "version": "10.4.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
+      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/c8/node_modules/minimatch": {
+      "version": "9.0.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
+      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/c8/node_modules/path-scurry": {
+      "version": "1.11.1",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz",
+      "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "lru-cache": "^10.2.0",
+        "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/c8/node_modules/test-exclude": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-7.0.1.tgz",
+      "integrity": "sha512-pFYqmTw68LXVjeWJMST4+borgQP2AyMNbg1BpZh9LbyhUeNkeaPF9gzfPGUAnSMV3qPYdWUwDIjjCLiSDOl7vg==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "@istanbuljs/schema": "^0.1.2",
+        "glob": "^10.4.1",
+        "minimatch": "^9.0.4"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/callsites": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
@@ -3200,6 +3352,7 @@
       "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",
@@ -6939,6 +7092,7 @@
       "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "prettier": "bin/prettier.cjs"
       },
@@ -7761,6 +7915,7 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -8389,6 +8544,16 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/zod": {
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.1.12.tgz",
+      "integrity": "sha512-JInaHOamG8pt5+Ey8kGmdcAcg3OL9reK8ltczgHTAwNhMys/6ThXHityHxVV2p3fkw/c+MAvBHFVYHFZDmjMCQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    },
     "node_modules/zwitch": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz",

package.json

@@ -38,7 +38,10 @@
     "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
     "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
     "release:watch": "gh run watch",
-    "validate:bundles": "node tools/validate-bundles.js"
+    "test": "node test/test-agent-schema.js",
+    "test:coverage": "c8 --reporter=text --reporter=html node test/test-agent-schema.js",
+    "validate:bundles": "node tools/validate-bundles.js",
+    "validate:schemas": "node tools/validate-agent-schema.js"
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [
@@ -73,6 +76,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.33.0",
+    "c8": "^10.1.3",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^17.21.3",
@@ -84,7 +88,8 @@
     "prettier": "^3.5.3",
     "prettier-plugin-packagejson": "^2.5.19",
     "yaml-eslint-parser": "^1.2.3",
-    "yaml-lint": "^1.7.0"
+    "yaml-lint": "^1.7.0",
+    "zod": "^4.1.12"
   },
   "engines": {
     "node": ">=20.0.0"

src/core/_module-installer/install-menu-config.yaml

@@ -8,12 +8,17 @@ prompt:
 # This is injected into the custom agent activation rules
 user_name:
   prompt: "What is your name?"
-  default: "BMad User"
+  default: "BMad"
   result: "{value}"
 
-# This is injected into the custom agent activation rules
+# This is injected into the custom agent activation rules and most workflows
 communication_language:
-  prompt: "Preferred language?"
+  prompt: "Preferred Chat Language?"
+  default: "English"
+  result: "{value}"
+
+document_output_language:
+  prompt: "Preferred Document Output Language?"
   default: "English"
   result: "{value}"
 

src/core/agents/bmad-master.agent.yaml

@@ -12,7 +12,8 @@ agent:
     role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"
     identity: "Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations."
     communication_style: "Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability."
-    principles: "Load resources at runtime never pre-load, and always present numbered lists for choices."
+    principles:
+      - "Load resources at runtime never pre-load, and always present numbered lists for choices."
 
   # Agent-specific critical actions
   critical_actions:
@@ -22,21 +23,17 @@ agent:
 
   # Agent menu items
   menu:
-    - trigger: "*list-tasks"
+    - trigger: "list-tasks"
       action: "list all tasks from {project-root}/bmad/_cfg/task-manifest.csv"
       description: "List Available Tasks"
 
-    - trigger: "*list-workflows"
+    - trigger: "list-workflows"
       action: "list all workflows from {project-root}/bmad/_cfg/workflow-manifest.csv"
       description: "List Workflows"
 
-    - trigger: "*party-mode"
+    - trigger: "party-mode"
       workflow: "{project-root}/bmad/core/workflows/party-mode/workflow.yaml"
       description: "Group chat with all agents"
 
-    # - trigger: "*bmad-init"
-    #   workflow: "{project-root}/bmad/core/workflows/bmad-init/workflow.yaml"
-    #   description: "Initialize or Update BMAD system agent manifest, customization, or workflow selection"
-
   # Empty prompts section (no custom prompts for this agent)
   prompts: []

src/core/workflows/bmad-init/instructions.md

@@ -1,79 +0,0 @@
-# BMAD Init - System Initialization Instructions
-
-<workflow>
-
-<step n="1" goal="Welcome and Status Check">
-  <action>Display welcome banner with BMAD branding</action>
-  <action>Check for BMAD installation at {project-root}/bmad</action>
-  <check>If installation found:</check>
-    <action>Display current version from {project-root}/bmad/_cfg/manifest.yaml</action>
-    <action>Show installation date and status</action>
-  <check>If not found:</check>
-    <action>Display warning that BMAD is not installed</action>
-    <action>Suggest running the installer first</action>
-    <action>Exit workflow</action>
-  <action>Display formatted status summary:
-    ╔════════════════════════════════════════╗
-    ║         BMAD INITIALIZATION            ║
-    ╚════════════════════════════════════════╝
-
-    Status: [Installed/Not Found]
-    Location: {project-root}/bmad
-    Version: [from manifest]
-    Installed: [date from manifest]
-
-  </action>
-</step>
-
-<step n="2" goal="Present Initialization Options">
-  <action>Display available initialization and maintenance tasks</action>
-  <ask>Select an initialization task:
-
-    1. Customize Installed Agents and Agent Party (Coming Soon)
-       - Assign new names and personas to agents
-       - Create runtime agent variants
-       - NOTE: This can all be done manually, but doing it through here will be easier and also update the party-mode manifest
-
-    2. Verify Installation (Coming Soon)
-       - Check all files are properly installed
-       - Validate configurations
-
-    3. Exit
-
-    Please select an option (1-3).
-
-  </ask>
-</step>
-
-<step n="3" goal="Process User Selection">
-  <check>If user selected "1":</check>
-    <action>Display message: ⚠️ Installed Agent Auto Customization is coming soon.</action>
-    <<action>Return to step 2</action>
-
-<check>If user selected "2":</check>
-<action>Display message: ⚠️ Installation verification is coming soon.</action>
-<action>Return to step 2</action>
-
-<check>If user selected "3":</check>
-<action>Display message: Exiting BMAD Init. Thank you!</action>
-<goto step="5">Exit workflow</goto>
-</step>
-
-<step n="4" goal="Post-Task Options">
-  <action>Display completion status of the executed task</action>
-  <ask>Task completed successfully!
-
-Would you like to perform another initialization task? (y/n):</ask>
-<check>If user responds "y":</check>
-<goto step="2">Return to menu</goto>
-<check>If user responds "n":</check>
-<goto step="5">Exit workflow</goto>
-</step>
-
-<step n="5" goal="Exit Workflow">
-  <action>Display farewell message</action>
-  <action>Suggest user start a new context or clear context if needed</action>
-  <action>Exit workflow</action>
-</step>
-
-</workflow>

src/core/workflows/bmad-init/workflow.yaml

@@ -1,14 +0,0 @@
-# BMAD Init - System Initialization Workflow
-name: "bmad-init"
-description: "BMAD system initialization and maintenance workflow for agent manifest generation and system configuration"
-author: "BMad"
-
-# Critical variables
-config_source: "{project-root}/bmad/_cfg/manifest.yaml"
-date: system-generated
-
-# This is an action workflow - no template output
-template: false
-instructions: "{project-root}/bmad/core/workflows/bmad-init/instructions.md"
-
-web_bundle: false

src/modules/bmb/workflows/create-workflow/README.md

@@ -56,6 +56,67 @@ create-workflow/
     └── README.md
 ```
 
+## Understanding Instruction Styles
+
+One of the most important decisions when creating a workflow is choosing the **instruction style** - how the workflow guides the AI's interaction with users.
+
+### Intent-Based vs Prescriptive Instructions
+
+**Intent-Based (Recommended for most workflows)**
+
+Guides the LLM with goals and principles, allowing natural conversation adaptation.
+
+- **More flexible and conversational** - AI adapts questions to context
+- **Better for complex discovery** - Requirements gathering, creative exploration
+- **Quality over consistency** - Focus on deep understanding
+- **Example**: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**Best for:**
+
+- Complex discovery processes (user research, requirements)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- When adaptation to context matters
+- Workflows requiring nuanced understanding
+
+**Prescriptive**
+
+Provides exact wording for questions and structured options.
+
+- **More controlled and predictable** - Same questions every time
+- **Better for simple data collection** - Platform choices, yes/no decisions
+- **Consistency over quality** - Standardized execution
+- **Example**: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**Best for:**
+
+- Simple data collection (platform, format, binary choices)
+- Compliance verification and standards
+- Configuration with finite options
+- Quick setup wizards
+- When consistency is critical
+
+### Best Practice: Mix Both Styles
+
+The most effective workflows use **both styles strategically**:
+
+```xml
+<!-- Intent-based workflow with prescriptive moments -->
+<step n="1" goal="Understand user vision">
+  <action>Explore the user's vision, uncovering creative intent and target experience</action>
+</step>
+
+<step n="2" goal="Capture basic metadata">
+  <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>
+</step>
+
+<step n="3" goal="Deep dive into details">
+  <action>Guide user to articulate their core approach and unique aspects</action>
+</step>
+```
+
+**During workflow creation**, you'll be asked to choose a **primary style preference** - this sets the default approach, but you can (and should) use the other style when it makes more sense for specific steps.
+
 ## Workflow Process
 
 ### Phase 0: Optional Brainstorming (Step -1)

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

@@ -43,8 +43,64 @@ Or through a BMAD agent:
 2. **Prioritized Issues**: Identifies and ranks issues by importance
 3. **Guided Editing**: Step-by-step process with explanations
 4. **Best Practices**: Ensures all edits follow BMAD conventions
-5. **Validation**: Checks all changes for correctness
-6. **Change Tracking**: Documents what was modified and why
+5. **Instruction Style Optimization**: Convert between intent-based and prescriptive styles
+6. **Validation**: Checks all changes for correctness
+7. **Change Tracking**: Documents what was modified and why
+
+## Understanding Instruction Styles
+
+When editing workflows, one powerful option is **adjusting the instruction style** to better match the workflow's purpose.
+
+### Intent-Based vs Prescriptive Instructions
+
+**Intent-Based (Recommended for most workflows)**
+
+Guides the AI with goals and principles, allowing flexible conversation.
+
+- **More flexible and conversational** - AI adapts to user responses
+- **Better for complex discovery** - Requirements gathering, creative exploration
+- **Quality over consistency** - Deep understanding matters more
+- **Example**: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**When to use:**
+
+- Complex discovery processes (user research, requirements)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- Workflows requiring nuanced understanding
+
+**Prescriptive**
+
+Provides exact questions with structured options.
+
+- **More controlled and predictable** - Consistent questions every time
+- **Better for simple data collection** - Platform, format, yes/no choices
+- **Consistency over quality** - Same execution every run
+- **Example**: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**When to use:**
+
+- Simple data collection (platform, format, binary choices)
+- Compliance verification and standards adherence
+- Configuration with finite options
+- Quick setup wizards
+
+### Edit Workflow's Style Adjustment Feature
+
+The **"Adjust instruction style"** editing option (menu option 11) helps you:
+
+1. **Analyze current style** - Identifies whether workflow is primarily intent-based or prescriptive
+2. **Convert between styles** - Transform prescriptive steps to intent-based (or vice versa)
+3. **Optimize the mix** - Intelligently recommend the best style for each step
+4. **Step-by-step control** - Review and decide on each step individually
+
+**Common scenarios:**
+
+- **Make workflow more conversational**: Convert rigid <ask> tags to flexible <action> tags for complex steps
+- **Make workflow more consistent**: Convert open-ended <action> tags to structured <ask> tags for simple data collection
+- **Balance both approaches**: Use intent-based for discovery, prescriptive for simple choices
+
+This feature is especially valuable when converting legacy workflows or adapting workflows for different use cases.
 
 ## Workflow Steps
 

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

@@ -77,9 +77,10 @@ Present the editing menu to the user:
 8. **Configure web bundle** - Add/update web bundle for deployment
 9. **Remove bloat** - Delete unused yaml fields, duplicate values
 10. **Optimize for clarity** - Improve descriptions, add examples
-11. **Full review and update** - Comprehensive improvements across all files
+11. **Adjust instruction style** - Convert between intent-based and prescriptive styles
+12. **Full review and update** - Comprehensive improvements across all files
 
-<ask>Select an option (1-11) or describe a custom edit:</ask>
+<ask>Select an option (1-12) or describe a custom edit:</ask>
 </step>
 
 <step n="4" goal="Load relevant documentation">
@@ -127,7 +128,16 @@ date: system-generated
 <check>If fixing critical issues:</check>
 <action>Load the workflow execution engine documentation</action>
 <action>Verify all required elements are present</action>
-</step>
+
+<check>If adjusting instruction style (option 11):</check>
+<action>Analyze current instruction style in instructions.md:</action>
+
+- 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>
+  </step>
 
 <step n="5" goal="Perform edits" repeat="until-complete">
 Based on the selected focus area:
@@ -161,6 +171,127 @@ If updating existing web bundle:
 3. Remove any config dependencies
 4. Update file list with newly referenced files
 
+<check>If adjusting instruction style (option 11):</check>
+<action>Present current style analysis to user:</action>
+
+**Current Instruction Style Analysis:**
+
+- Current dominant style: {{detected_style}}
+- Intent-based elements: {{intent_count}}
+- Prescriptive elements: {{prescriptive_count}}
+
+**Understanding Intent-Based vs Prescriptive:**
+
+**1. Intent-Based (Recommended)** - Guide the LLM with goals and principles, let it adapt conversations naturally
+
+- More flexible and conversational
+- LLM chooses appropriate questions based on context
+- Better for complex discovery and iterative refinement
+- Example: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**2. Prescriptive** - Provide exact wording for questions and options
+
+- More controlled and predictable
+- Ensures consistency across runs
+- Better for simple data collection or specific compliance needs
+- Example: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**When to use Intent-Based:**
+
+- Complex discovery processes (user research, requirements gathering)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- When user input quality matters more than consistency
+- Workflows requiring adaptation to context
+
+**When to use Prescriptive:**
+
+- Simple data collection (platform, format, yes/no choices)
+- Compliance verification and standards adherence
+- Configuration with finite options
+- When consistency is critical across all executions
+- Quick setup wizards
+
+**Best Practice: Mix Both Styles**
+
+Even workflows with a primary style should use the other when appropriate. For example:
+
+```xml
+<!-- Intent-based workflow with prescriptive moments -->
+<step n="1" goal="Understand user vision">
+  <action>Explore the user's vision, uncovering their creative intent and target experience</action>
+</step>
+
+<step n="2" goal="Capture basic metadata">
+  <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask> <!-- Prescriptive for simple choice -->
+</step>
+
+<step n="3" goal="Deep dive into details">
+  <action>Guide user to articulate their approach, exploring mechanics and unique aspects</action> <!-- Back to intent-based -->
+</step>
+```
+
+<ask>What would you like to do?
+
+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
+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
+
+Select option (1-5):</ask>
+
+<action>Store user's style adjustment preference as {{style_adjustment_choice}}</action>
+
+<check>If choice is 1 (make more intent-based):</check>
+<action>Identify prescriptive <ask> tags that could be converted to intent-based <action> tags</action>
+<action>For each candidate conversion:
+
+- Show original prescriptive version
+- Suggest intent-based alternative focused on goals
+- Explain the benefit of the conversion
+- Ask for approval
+  </action>
+  <action>Apply approved conversions</action>
+
+<check>If choice is 2 (make more prescriptive):</check>
+<action>Identify open-ended <action> tags that could be converted to prescriptive <ask> tags</action>
+<action>For each candidate conversion:
+
+- Show original intent-based version
+- Suggest prescriptive alternative with specific options
+- Explain when prescriptive is better here
+- Ask for approval
+  </action>
+  <action>Apply approved conversions</action>
+
+<check>If choice is 3 (optimize mix):</check>
+<action>Analyze each step for complexity and purpose</action>
+<action>Recommend style for each step:
+
+- Simple data collection → Prescriptive
+- Complex discovery → Intent-based
+- Binary decisions → Prescriptive
+- Creative exploration → Intent-based
+- Standards/compliance → Prescriptive
+- Iterative refinement → Intent-based
+  </action>
+  <action>Show recommendations with reasoning</action>
+  <action>Apply approved optimizations</action>
+
+<check>If choice is 4 (review specific steps):</check>
+<action>Present each step one at a time</action>
+<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>If choice is 5 (cancel):</check>
+<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>
 <action>Generate the updated content following all conventions from the guide</action>

src/modules/bmm/_module-installer/install-menu-config.yaml

@@ -19,6 +19,21 @@ project_name:
   default: "{directory_name}"
   result: "{value}"
 
+user_skill_level:
+  prompt:
+    - "What is your technical experience level?"
+    - "This affects how agents explain concepts to you (NOT document content)."
+    - "Documents are always concise for LLM efficiency."
+  default: "intermediate"
+  result: "{value}"
+  single-select:
+    - value: "beginner"
+      label: "Beginner - New to development, explain concepts clearly"
+    - value: "intermediate"
+      label: "Intermediate - Familiar with development, balance explanation with efficiency"
+    - value: "expert"
+      label: "Expert - Deep technical knowledge, be direct and technical"
+
 tech_docs:
   prompt: "Where is Technical Documentation located within the project?"
   default: "docs"
@@ -28,22 +43,21 @@ dev_story_location:
   prompt: "Where should development stories be stored?"
   default: "docs/stories"
   result: "{project-root}/{value}"
+# kb_location:
+#   prompt: "Where should bmad knowledge base articles be stored?"
+#   default: "~/bmad/bmm/kb.md"
+#   result: "{value}"
 
-kb_location:
-  prompt: "Where should bmad knowledge base articles be stored?"
-  default: "~/bmad/bmm/kb.md"
-  result: "{value}"
-
-desired_mcp_tools:
-  prompt:
-    - "Which MCP Tools will you be using? (Select all that apply)"
-    - "Note: You will need to install these separately. Bindings will come post ALPHA along with other choices."
-  result: "{value}"
-  multi-select:
-    - "Chrome Official MCP"
-    - "Playwright"
-    - "Context 7"
-    - "Tavily"
-    - "Perplexity"
-    - "Jira"
-    - "Trello"
+# desired_mcp_tools:
+#   prompt:
+#     - "Which MCP Tools will you be using? (Select all that apply)"
+#     - "Note: You will need to install these separately. Bindings will come post ALPHA along with other choices."
+#   result: "{value}"
+#   multi-select:
+#     - "Chrome Official MCP"
+#     - "Playwright"
+#     - "Context 7"
+#     - "Tavily"
+#     - "Perplexity"
+#     - "Jira"
+#     - "Trello"

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

@@ -18,8 +18,12 @@ agent:
       - I operate as an iterative thinking partner who explores wide solution spaces before converging on recommendations, ensuring that every requirement is articulated with absolute precision and every output delivers clear, actionable next steps.
 
   menu:
+    - trigger: workflow-init
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/init/workflow.yaml"
+      description: Start a new sequenced workflow path
+
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations (START HERE!)
 
     - trigger: brainstorm-project

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

@@ -19,7 +19,7 @@ agent:
 
   menu:
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations
 
     - trigger: correct-course

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

@@ -27,7 +27,7 @@ agent:
 
   menu:
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations
 
     - trigger: develop

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

@@ -19,7 +19,7 @@ agent:
 
   menu:
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations
 
     - trigger: solutioning

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

@@ -18,8 +18,12 @@ agent:
       - Design is about making meaningful choices matter, creating moments of mastery, and respecting player time while delivering compelling challenge.
 
   menu:
+    - trigger: workflow-init
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/init/workflow.yaml"
+      description: Start a new sequenced workflow path
+
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations (START HERE!)
 
     - trigger: brainstorm-game

src/modules/bmm/agents/game-dev.agent.yaml

@@ -19,7 +19,7 @@ agent:
 
   menu:
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations
 
     - trigger: create-story

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

@@ -23,8 +23,12 @@ agent:
   # Menu items - triggers will be prefixed with * at build time
   # help and exit are auto-injected, don't define them here
   menu:
+    - trigger: workflow-init
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/init/workflow.yaml"
+      description: Start a new sequenced workflow path
+
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations (START HERE!)
 
     - trigger: prd

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

@@ -22,11 +22,11 @@ agent:
 
   menu:
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations
 
     - trigger: assess-project-ready
-      validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/implementation-ready-check/workflow.yaml"
       description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)
 
     - trigger: create-story

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

@@ -13,8 +13,8 @@ agent:
     identity: Test architect specializing in CI/CD, automated frameworks, and scalable quality gates.
     communication_style: Data-driven advisor. Strong opinions, weakly held. Pragmatic.
     principles:
-      - Risk-based testing: depth scales with impact. Quality gates backed by data. Tests mirror usage. Cost = creation + execution + maintenance.
-      - Testing is feature work. Prioritize unit/integration over E2E. Flakiness is critical debt. ATDD: tests first, AI implements, suite validates.
+      - Risk-based testing. depth scales with impact. Quality gates backed by data. Tests mirror usage. Cost = creation + execution + maintenance.
+      - Testing is feature work. Prioritize unit/integration over E2E. Flakiness is critical debt. ATDD tests first, AI implements, suite validates.
 
   critical_actions:
     - "Consult {project-root}/bmad/bmm/testarch/tea-index.csv to select knowledge fragments under `knowledge/` and load only the files needed for the current task"
@@ -23,7 +23,7 @@ agent:
 
   menu:
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations
 
     - trigger: framework

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

@@ -19,7 +19,7 @@ agent:
 
   menu:
     - trigger: workflow-status
-      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations (START HERE!)
 
     - trigger: ux-spec

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

@@ -1,7 +0,0 @@
-# <!-- Powered by BMAD-CORE™ -->
-bundle:
-  name: Team All
-  icon: 👥
-  description: Includes every bmm system agent.
-agents:
-  - "*"

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

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

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

@@ -5,33 +5,36 @@
 
 <workflow>
 
-  <step n="1" goal="Check and load workflow status file">
-    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-    <action>Find the most recent file (by date in filename: bmm-workflow-status.md)</action>
+  <step n="1" goal="Validate workflow readiness">
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+      <param>mode: validate</param>
+      <param>calling_workflow: brainstorm-game</param>
+    </invoke-workflow>
 
-    <check if="exists">
-      <action>Load the status file</action>
-      <action>Set status_file_found = true</action>
-      <action>Store status_file_path for later updates</action>
+    <check if="status_exists == false">
+      <output>{{suggestion}}</output>
+      <output>Note: Game brainstorming is optional. Continuing without progress tracking.</output>
+      <action>Set standalone_mode = true</action>
     </check>
 
-    <check if="not exists">
-      <ask>**No workflow status file found.**
+    <check if="status_exists == true">
+      <action>Store {{status_file_path}} for later updates</action>
 
-This workflow generates brainstorming ideas for game ideation (optional Phase 1 workflow).
+      <check if="project_type != 'game'">
+        <output>Note: This is a {{project_type}} project. Game brainstorming is designed for game projects.</output>
+        <ask>Continue with game brainstorming anyway? (y/n)</ask>
+        <check if="n">
+          <action>Exit workflow</action>
+        </check>
+      </check>
 
-Options:
+      <check if="warning != ''">
+        <output>{{warning}}</output>
+        <output>Note: Game brainstorming can be valuable at any project stage.</output>
+      </check>
+    </check>
 
-1. Run workflow-status first to create the status file (recommended for progress tracking)
-2. Continue in standalone mode (no progress tracking)
-3. Exit
-
-What would you like to do?</ask>
-<action>If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to brainstorm-game"</action>
-<action>If user chooses option 2 → Set standalone_mode = true and continue</action>
-<action>If user chooses option 3 → HALT</action>
-</check>
-</step>
+  </step>
 
   <step n="2" goal="Load game brainstorming context and techniques">
     <action>Read the game context document from: {game_context}</action>
@@ -63,38 +66,33 @@ What would you like to do?</ask>
     </invoke-workflow>
   </step>
 
-  <step n="4" goal="Update status file on completion">
-    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-    <action>Find the most recent file (by date in filename)</action>
+  <step n="4" goal="Update status and complete">
+    <check if="standalone_mode != true">
+      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+        <param>mode: update</param>
+        <param>action: complete_workflow</param>
+        <param>workflow_name: brainstorm-game</param>
+      </invoke-workflow>
 
-    <check if="status file exists">
-      <action>Load the status file</action>
+      <check if="success == true">
+        <output>Status updated! Next: {{next_workflow}}</output>
+      </check>
+    </check>
 
-      <template-output file="{{status_file_path}}">current_step</template-output>
-      <action>Set to: "brainstorm-game"</action>
-
-      <template-output file="{{status_file_path}}">current_workflow</template-output>
-      <action>Set to: "brainstorm-game - Complete"</action>
-
-      <template-output file="{{status_file_path}}">progress_percentage</template-output>
-      <action>Increment by: 5% (optional Phase 1 workflow)</action>
-
-      <template-output file="{{status_file_path}}">decisions_log</template-output>
-      <action>Add entry:</action>
-      ```
-      - **{{date}}**: Completed brainstorm-game workflow. Generated game brainstorming session results saved to {output_folder}/brainstorming-session-results-{{date}}.md. Next: Review game ideas and consider running research or game-brief workflows.
-      ```
-
-      <output>**✅ Game Brainstorming Session Complete, {user_name}!**
+    <output>**✅ Game Brainstorming Session Complete, {user_name}!**
 
 **Session Results:**
 
-- Game brainstorming results saved to: {output_folder}/brainstorming-session-results-{{date}}.md
+- Game brainstorming results saved to: {output_folder}/bmm-brainstorming-session-{{date}}.md
 
-**Status file updated:**
+{{#if standalone_mode != true}}
+**Status Updated:**
 
-- Current step: brainstorm-game ✓
-- Progress: {{new_progress_percentage}}%
+- Progress tracking updated
+  {{else}}
+  Note: Running in standalone mode (no status file).
+  To track progress across workflows, run `workflow-init` first.
+  {{/if}}
 
 **Next Steps:**
 
@@ -104,27 +102,10 @@ What would you like to do?</ask>
    - `game-brief` workflow to formalize game vision
    - Or proceed directly to `plan-project` if ready
 
+{{#if standalone_mode != true}}
 Check status anytime with: `workflow-status`
+{{/if}}
 </output>
-</check>
-
-    <check if="status file not found">
-      <output>**✅ Game Brainstorming Session Complete, {user_name}!**
-
-**Session Results:**
-
-- Game brainstorming results saved to: {output_folder}/brainstorming-session-results-{{date}}.md
-
-Note: Running in standalone mode (no status file).
-
-To track progress across workflows, run `workflow-status` first.
-
-**Next Steps:**
-
-1. Review game brainstorming results
-2. Run research or game-brief workflows
-   </output>
-   </check>
-   </step>
+</step>
 
 </workflow>

src/modules/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml

@@ -8,6 +8,8 @@ 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
 
 # Module path and component files

src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md

@@ -1,6 +1,6 @@
 # Brainstorm Project - Workflow Instructions
 
-````xml
+```xml
 <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}</critical>
@@ -8,30 +8,25 @@
 
 <workflow>
 
-  <step n="1" goal="Check and load workflow status file">
-    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-    <action>Find the most recent file (by date in filename: bmm-workflow-status.md)</action>
+  <step n="1" goal="Validate workflow readiness">
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+      <param>mode: validate</param>
+      <param>calling_workflow: brainstorm-project</param>
+    </invoke-workflow>
 
-    <check if="exists">
-      <action>Load the status file</action>
-      <action>Set status_file_found = true</action>
-      <action>Store status_file_path for later updates</action>
+    <check if="status_exists == false">
+      <output>{{suggestion}}</output>
+      <output>Note: Brainstorming is optional. Continuing without progress tracking.</output>
+      <action>Set standalone_mode = true</action>
     </check>
 
-    <check if="not exists">
-      <ask>**No workflow status file found.**
+    <check if="status_exists == true">
+      <action>Store {{status_file_path}} for later updates</action>
 
-This workflow generates brainstorming ideas for project ideation (optional Phase 1 workflow).
-
-Options:
-1. Run workflow-status first to create the status file (recommended for progress tracking)
-2. Continue in standalone mode (no progress tracking)
-3. Exit
-
-What would you like to do?</ask>
-      <action>If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to brainstorm-project"</action>
-      <action>If user chooses option 2 → Set standalone_mode = true and continue</action>
-      <action>If user chooses option 3 → HALT</action>
+      <check if="warning != ''">
+        <output>{{warning}}</output>
+        <output>Note: Brainstorming can be valuable at any project stage.</output>
+      </check>
     </check>
   </step>
 
@@ -56,36 +51,28 @@ What would you like to do?</ask>
     </invoke-workflow>
   </step>
 
-  <step n="4" goal="Update status file on completion">
-    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-    <action>Find the most recent file (by date in filename)</action>
+  <step n="4" goal="Update status and complete">
+    <check if="standalone_mode != true">
+      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+        <param>mode: update</param>
+        <param>action: complete_workflow</param>
+        <param>workflow_name: brainstorm-project</param>
+      </invoke-workflow>
 
-    <check if="status file exists">
-      <action>Load the status file</action>
+      <check if="success == true">
+        <output>Status updated! Next: {{next_workflow}}</output>
+      </check>
+    </check>
 
-      <template-output file="{{status_file_path}}">current_step</template-output>
-      <action>Set to: "brainstorm-project"</action>
-
-      <template-output file="{{status_file_path}}">current_workflow</template-output>
-      <action>Set to: "brainstorm-project - Complete"</action>
-
-      <template-output file="{{status_file_path}}">progress_percentage</template-output>
-      <action>Increment by: 5% (optional Phase 1 workflow)</action>
-
-      <template-output file="{{status_file_path}}">decisions_log</template-output>
-      <action>Add entry:</action>
-      ```
-      - **{{date}}**: Completed brainstorm-project workflow. Generated brainstorming session results saved to {output_folder}/brainstorming-session-results-{{date}}.md. Next: Review ideas and consider running research or product-brief workflows.
-      ```
-
-      <output>**✅ Brainstorming Session Complete, {user_name}!**
+    <output>**✅ Brainstorming Session Complete, {user_name}!**
 
 **Session Results:**
-- Brainstorming results saved to: {output_folder}/brainstorming-session-results-{{date}}.md
+- Brainstorming results saved to: {output_folder}/bmm-brainstorming-session-{{date}}.md
 
-**Status file updated:**
-- Current step: brainstorm-project ✓
-- Progress: {{new_progress_percentage}}%
+{{#if standalone_mode != true}}
+**Status Updated:**
+- Progress tracking updated
+{{/if}}
 
 **Next Steps:**
 1. Review brainstorming results
@@ -94,26 +81,11 @@ What would you like to do?</ask>
    - `product-brief` workflow to formalize product vision
    - Or proceed directly to `plan-project` if ready
 
+{{#if standalone_mode != true}}
 Check status anytime with: `workflow-status`
-      </output>
-    </check>
-
-    <check if="status file not found">
-      <output>**✅ Brainstorming Session Complete, {user_name}!**
-
-**Session Results:**
-- Brainstorming results saved to: {output_folder}/brainstorming-session-results-{{date}}.md
-
-Note: Running in standalone mode (no status file).
-
-To track progress across workflows, run `workflow-status` first.
-
-**Next Steps:**
-1. Review brainstorming results
-2. Run research or product-brief workflows
-      </output>
-    </check>
+{{/if}}
+    </output>
   </step>
 
 </workflow>
-````
+```

src/modules/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml

@@ -8,6 +8,8 @@ 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
 
 # Module path and component files

src/modules/bmm/workflows/1-analysis/document-project/instructions.md

@@ -8,85 +8,47 @@
 
 <critical>This router determines workflow mode and delegates to specialized sub-workflows</critical>
 
-<step n="1" goal="Check and load workflow status file">
+<step n="1" goal="Validate workflow and get project info">
 
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status\*.md</action>
-<action>Find the most recent file (by date in filename: bmm-workflow-status.md)</action>
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: data</param>
+  <param>data_request: project_config</param>
+</invoke-workflow>
 
-<check if="exists">
-  <action>Load the status file</action>
-  <action>Extract key information:</action>
-
-- current_step: From "Current Step:" field
-- next_step: From "Next Step:" field
-- planned_workflow: From "Planned Workflow Journey" table
-- progress_percentage: From "Overall Progress:" field
-- current_phase: From "Current Phase:" field
-- field_type: From "Greenfield/Brownfield:" field
-
-<action>Validate this workflow is in the planned workflow</action>
-<action>Set status_file_path = file path</action>
-<action>Set status_file_found = true</action>
-
-  <check if='next_step != "document-project"'>
-    <ask>**⚠️ Workflow Sequence Note**
-
-According to your status file, your next planned step is: **{{next_step}}**
-
-But you're running: **document-project**
-
-This is expected if plan-project invoked this workflow automatically for brownfield documentation.
-
-Options:
-
-1. **Continue** - Run document-project (status will be updated)
-2. **Exit** - I'll follow the planned sequence instead
-
-Your choice (1-2):</ask>
-
-    <check if='choice == "2"'>
-      <output>**Recommended Next Step:**
-
-Run: {{next_step}}
-
-You can return to document-project later if needed.
-</output>
-<action>Exit workflow</action>
-</check>
-</check>
+<check if="status_exists == false">
+  <output>{{suggestion}}</output>
+  <output>Note: Documentation workflow can run standalone. Continuing without progress tracking.</output>
+  <action>Set standalone_mode = true</action>
+  <action>Set status_file_found = false</action>
 </check>
 
-<check if="not exists">
-  <ask>**ℹ️ No Workflow Status File Found**
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for later updates</action>
+  <action>Set status_file_found = true</action>
 
-This workflow works best with a workflow status file for progress tracking.
-
-Options:
-
-1. **Run workflow-status first** - Create status file and plan workflow (recommended)
-2. **Continue anyway** - Run document-project standalone
-3. **Exit** - I'll set up the workflow first
-
-Your choice (1-3):</ask>
-
-  <check if='choice == "1"'>
-    <output>**To create status file:**
-
-Load any agent and run: `workflow-status`
-
-After planning your workflow, you can return here or follow the planned sequence.
-</output>
-<action>Exit workflow</action>
-</check>
-
-  <check if='choice == "2"'>
-    <action>Set status_file_found = false</action>
-    <action>Set standalone_mode = true</action>
-    <action>Continue without status file integration</action>
+  <!-- Extract brownfield/greenfield from status data -->
+  <check if="field_type == 'greenfield'">
+    <output>Note: This is a greenfield project. Documentation workflow is typically for brownfield projects.</output>
+    <ask>Continue anyway to document planning artifacts? (y/n)</ask>
+    <check if="n">
+      <action>Exit workflow</action>
+    </check>
   </check>
 
-  <check if='choice == "3"'>
-    <action>Exit workflow</action>
+  <!-- Now validate sequencing -->
+  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <param>mode: validate</param>
+    <param>calling_workflow: document-project</param>
+  </invoke-workflow>
+
+  <check if="warning != ''">
+    <output>{{warning}}</output>
+    <output>Note: This may be auto-invoked by plan-project for brownfield documentation.</output>
+    <ask>Continue with documentation? (y/n)</ask>
+    <check if="n">
+      <output>{{suggestion}}</output>
+      <action>Exit workflow</action>
+    </check>
   </check>
 </check>
 
@@ -214,34 +176,19 @@ Your choice [1/2/3]:
 
 </step>
 
-<step n="4" goal="Update status file on completion">
+<step n="4" goal="Update status and complete">
 
 <check if="status_file_found == true">
-  <action>Load the status file from {{status_file_path}}</action>
+  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <param>mode: update</param>
+    <param>action: complete_workflow</param>
+    <param>workflow_name: document-project</param>
+  </invoke-workflow>
 
-<template-output file="{{status_file_path}}">planned_workflow</template-output>
-<action>Find "document-project" in the planned_workflow table</action>
-<action>Update Status field from "Planned" or "In Progress" to "Complete"</action>
-
-<template-output file="{{status_file_path}}">current_step</template-output>
-<action>Set to: "document-project"</action>
-
-<template-output file="{{status_file_path}}">next_step</template-output>
-<action>Find next item with Status != "Complete" in planned_workflow table</action>
-<action>Set to: "{{next_workflow_step}} ({{next_workflow_agent}} agent)"</action>
-
-<template-output file="{{status_file_path}}">progress_percentage</template-output>
-<action>Increment by: 10%</action>
-
-<template-output file="{{status_file_path}}">current_workflow</template-output>
-<action>Set to: "document-project - Complete"</action>
-
-<template-output file="{{status_file_path}}">decisions_log</template-output>
-<action>Add entry:</action>
-
-```
-- **{{date}}**: Completed document-project workflow ({{workflow_mode}} mode, {{scan_level}} scan). Generated brownfield documentation in {output_folder}/. Next: {{next_step}}.
-```
+  <check if="success == true">
+    <output>Status updated! Next: {{next_workflow}}</output>
+  </check>
+</check>
 
 <output>**✅ Document Project Workflow Complete, {user_name}!**
 
@@ -249,35 +196,18 @@ Your choice [1/2/3]:
 
 - Mode: {{workflow_mode}}
 - Scan Level: {{scan_level}}
-- Output: {output_folder}/index.md and related files
+- Output: {output_folder}/bmm-index.md and related files
 
-**Status file updated:**
+{{#if status_file_found}}
+**Status Updated:**
 
-- Current step: document-project ✓
-- Next step: {{next_step}}
-- Progress: {{new_progress_percentage}}%
+- Progress tracking updated
+  {{else}}
+  **Note:** Running in standalone mode
+  {{/if}}
 
-**To proceed:**
-Load {{next_agent}} and run: `{{next_command}}`
-
-Or check status anytime with: `workflow-status`
+Check status anytime with: `workflow-status`
 </output>
-</check>
-
-<check if="standalone_mode == true">
-  <output>**✅ Document Project Workflow Complete**
-
-**Documentation Generated:**
-
-- Mode: {{workflow_mode}}
-- Scan Level: {{scan_level}}
-- Output: {output_folder}/index.md and related files
-
-Note: Running in standalone mode (no status file).
-
-To track progress across workflows, run `workflow-status` first next time.
-</output>
-</check>
 
 </step>
 

src/modules/bmm/workflows/1-analysis/document-project/workflow.yaml

@@ -9,6 +9,8 @@ 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
 
 # Module path and component files

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

@@ -2,35 +2,40 @@
 
 <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}</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>DOCUMENT OUTPUT: Concise, professional, game-design focused. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
 
 <workflow>
 
-<step n="0" goal="Check and load workflow status file">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-<action>Find the most recent file (by date in filename: bmm-workflow-status.md)</action>
+<step n="0" goal="Validate workflow readiness">
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: validate</param>
+  <param>calling_workflow: game-brief</param>
+</invoke-workflow>
 
-<check if="exists">
-  <action>Load the status file</action>
-  <action>Set status_file_found = true</action>
-  <action>Store status_file_path for later updates</action>
+<check if="status_exists == false">
+  <output>{{suggestion}}</output>
+  <output>Note: Game brief is optional. Continuing without progress tracking.</output>
+  <action>Set standalone_mode = true</action>
 </check>
 
-<check if="not exists">
-  <ask>**No workflow status file found.**
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for later updates</action>
 
-This workflow creates a Game Brief document (optional Phase 1 workflow).
+  <check if="project_type != 'game'">
+    <output>Note: This is a {{project_type}} project. Game brief is designed for game projects.</output>
+    <ask>Continue with game brief anyway? (y/n)</ask>
+    <check if="n">
+      <action>Exit workflow</action>
+    </check>
+  </check>
 
-Options:
-
-1. Run workflow-status first to create the status file (recommended for progress tracking)
-2. Continue in standalone mode (no progress tracking)
-3. Exit
-
-What would you like to do?</ask>
-<action>If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to game-brief"</action>
-<action>If user chooses option 2 → Set standalone_mode = true and continue</action>
-<action>If user chooses option 3 → HALT</action>
+  <check if="warning != ''">
+    <output>{{warning}}</output>
+    <output>Note: Game brief can provide valuable vision clarity at any stage.</output>
+  </check>
 </check>
 </step>
 
@@ -303,39 +308,33 @@ This brief will serve as the primary input for creating the Game Design Document
 <template-output>executive_brief</template-output>
 </step>
 
-<step n="16" goal="Update status file on completion">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-<action>Find the most recent file (by date in filename)</action>
+<step n="16" goal="Update status and complete">
+<check if="standalone_mode != true">
+  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <param>mode: update</param>
+    <param>action: complete_workflow</param>
+    <param>workflow_name: game-brief</param>
+  </invoke-workflow>
 
-<check if="status file exists">
-  <action>Load the status file</action>
-
-<template-output file="{{status_file_path}}">current_step</template-output>
-<action>Set to: "game-brief"</action>
-
-<template-output file="{{status_file_path}}">current_workflow</template-output>
-<action>Set to: "game-brief - Complete"</action>
-
-<template-output file="{{status_file_path}}">progress_percentage</template-output>
-<action>Increment by: 10% (optional Phase 1 workflow)</action>
-
-<template-output file="{{status_file_path}}">decisions_log</template-output>
-<action>Add entry:</action>
-
-```
-- **{{date}}**: Completed game-brief workflow. Game brief document generated and saved. Next: Proceed to plan-project workflow to create Game Design Document (GDD).
-```
+  <check if="success == true">
+    <output>Status updated! Next: {{next_workflow}}</output>
+  </check>
+</check>
 
 <output>**✅ Game Brief Complete, {user_name}!**
 
 **Brief Document:**
 
-- Game brief saved to {output_folder}/game-brief-{{game_name}}-{{date}}.md
+- Game brief saved to {output_folder}/bmm-game-brief-{{game_name}}-{{date}}.md
 
-**Status file updated:**
+{{#if standalone_mode != true}}
+**Status Updated:**
 
-- Current step: game-brief ✓
-- Progress: {{new_progress_percentage}}%
+- Progress tracking updated
+  {{else}}
+  Note: Running in standalone mode (no status file).
+  To track progress across workflows, run `workflow-init` first.
+  {{/if}}
 
 **Next Steps:**
 
@@ -344,27 +343,10 @@ This brief will serve as the primary input for creating the Game Design Document
 3. Run `plan-project` workflow to create GDD from this brief
 4. Validate assumptions with target players
 
+{{#if standalone_mode != true}}
 Check status anytime with: `workflow-status`
+{{/if}}
 </output>
-</check>
-
-<check if="status file not found">
-  <output>**✅ Game Brief Complete, {user_name}!**
-
-**Brief Document:**
-
-- Game brief saved to {output_folder}/game-brief-{{game_name}}-{{date}}.md
-
-Note: Running in standalone mode (no status file).
-
-To track progress across workflows, run `workflow-status` first.
-
-**Next Steps:**
-
-1. Review the game brief document
-2. Run `plan-project` workflow to create GDD
-   </output>
-   </check>
-   </step>
+</step>
 
 </workflow>

src/modules/bmm/workflows/1-analysis/game-brief/workflow.yaml

@@ -8,6 +8,8 @@ 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
 
 # Optional input documents

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

@@ -2,35 +2,41 @@
 
 <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}</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>DOCUMENT OUTPUT: Concise, professional, strategically focused. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
 
 <workflow>
 
-<step n="0" goal="Check and load workflow status file">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-<action>Find the most recent file (by date in filename: bmm-workflow-status.md)</action>
+<step n="0" goal="Validate workflow readiness">
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: validate</param>
+  <param>calling_workflow: product-brief</param>
+</invoke-workflow>
 
-<check if="exists">
-  <action>Load the status file</action>
-  <action>Set status_file_found = true</action>
-  <action>Store status_file_path for later updates</action>
+<check if="status_exists == false">
+  <output>{{suggestion}}</output>
+  <output>Note: Product Brief is optional. You can continue without status tracking.</output>
+  <action>Set standalone_mode = true</action>
 </check>
 
-<check if="not exists">
-  <ask>**No workflow status file found.**
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for later updates</action>
 
-This workflow creates a Product Brief document (optional Phase 1 workflow).
+  <check if="project_level < 2">
+    <output>Note: Product Brief is most valuable for Level 2+ projects. Your project is Level {{project_level}}.</output>
+    <output>You may want to skip directly to technical planning instead.</output>
+  </check>
 
-Options:
-
-1. Run workflow-status first to create the status file (recommended for progress tracking)
-2. Continue in standalone mode (no progress tracking)
-3. Exit
-
-What would you like to do?</ask>
-<action>If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to product-brief"</action>
-<action>If user chooses option 2 → Set standalone_mode = true and continue</action>
-<action>If user chooses option 3 → HALT</action>
+  <check if="warning != ''">
+    <output>{{warning}}</output>
+    <ask>Continue with Product Brief anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. {{suggestion}}</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
 </check>
 </step>
 
@@ -267,38 +273,32 @@ This brief will serve as the primary input for creating the Product Requirements
 </step>
 
 <step n="16" goal="Update status file on completion">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-<action>Find the most recent file (by date in filename)</action>
+<check if="standalone_mode != true">
+  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <param>mode: update</param>
+    <param>action: complete_workflow</param>
+    <param>workflow_name: product-brief</param>
+  </invoke-workflow>
 
-<check if="status file exists">
-  <action>Load the status file</action>
-
-<template-output file="{{status_file_path}}">current_step</template-output>
-<action>Set to: "product-brief"</action>
-
-<template-output file="{{status_file_path}}">current_workflow</template-output>
-<action>Set to: "product-brief - Complete"</action>
-
-<template-output file="{{status_file_path}}">progress_percentage</template-output>
-<action>Increment by: 10% (optional Phase 1 workflow)</action>
-
-<template-output file="{{status_file_path}}">decisions_log</template-output>
-<action>Add entry:</action>
-
-```
-- **{{date}}**: Completed product-brief workflow. Product brief document generated and saved. Next: Proceed to plan-project workflow to create Product Requirements Document (PRD).
-```
+  <check if="success == true">
+    <output>Status updated! Next: {{next_workflow}}</output>
+  </check>
+</check>
 
 <output>**✅ Product Brief Complete, {user_name}!**
 
 **Brief Document:**
 
-- Product brief saved to {output_folder}/product-brief-{{project_name}}-{{date}}.md
+- Product brief saved to {output_folder}/bmm-product-brief-{{project_name}}-{{date}}.md
 
-**Status file updated:**
+{{#if standalone_mode != true}}
+**Status Updated:**
 
-- Current step: product-brief ✓
-- Progress: {{new_progress_percentage}}%
+- Progress tracking updated
+- Current workflow marked complete
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
 
 **Next Steps:**
 
@@ -306,27 +306,10 @@ This brief will serve as the primary input for creating the Product Requirements
 2. Gather any additional stakeholder input
 3. Run `plan-project` workflow to create PRD from this brief
 
+{{#if standalone_mode != true}}
 Check status anytime with: `workflow-status`
+{{/if}}
 </output>
-</check>
-
-<check if="status file not found">
-  <output>**✅ Product Brief Complete**
-
-**Brief Document:**
-
-- Product brief saved and ready for handoff
-
-Note: Running in standalone mode (no status file).
-
-To track progress across workflows, run `workflow-status` first.
-
-**Next Steps:**
-
-1. Review the product brief document
-2. Run `plan-project` workflow to create PRD
-   </output>
-   </check>
-   </step>
+</step>
 
 </workflow>

src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml

@@ -8,6 +8,8 @@ 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
 
 # Optional input documents

src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md

@@ -379,23 +379,15 @@ Select option (1-4):</ask>
 <action>Find the most recent file (by date in filename)</action>
 
 <check if="status file exists">
-  <action>Load the status file</action>
+  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <param>mode: update</param>
+    <param>action: complete_workflow</param>
+    <param>workflow_name: research</param>
+  </invoke-workflow>
 
-<template-output file="{{status_file_path}}">current_step</template-output>
-<action>Set to: "research (deep-prompt)"</action>
-
-<template-output file="{{status_file_path}}">current_workflow</template-output>
-<action>Set to: "research (deep-prompt) - Complete"</action>
-
-<template-output file="{{status_file_path}}">progress_percentage</template-output>
-<action>Increment by: 5% (optional Phase 1 workflow)</action>
-
-<template-output file="{{status_file_path}}">decisions_log</template-output>
-<action>Add entry:</action>
-
-```
-- **{{date}}**: Completed research workflow (deep-prompt mode). Research prompt generated and saved. Next: Execute prompt with AI platform or continue with plan-project workflow.
-```
+  <check if="success == true">
+    <output>Status updated! Next: {{next_workflow}}</output>
+  </check>
 
 <output>**✅ Deep Research Prompt Generated**
 

src/modules/bmm/workflows/1-analysis/research/instructions-market.md

@@ -559,23 +559,16 @@ Create compelling executive summary with:
 <action>Find the most recent file (by date in filename)</action>
 
 <check if="status file exists">
-  <action>Load the status file</action>
+  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <param>mode: update</param>
+    <param>action: complete_workflow</param>
+    <param>workflow_name: research</param>
+  </invoke-workflow>
 
-<template-output file="{{status_file_path}}">current_step</template-output>
-<action>Set to: "research ({{research_mode}})"</action>
-
-<template-output file="{{status_file_path}}">current_workflow</template-output>
-<action>Set to: "research ({{research_mode}}) - Complete"</action>
-
-<template-output file="{{status_file_path}}">progress_percentage</template-output>
-<action>Increment by: 5% (optional Phase 1 workflow)</action>
-
-<template-output file="{{status_file_path}}">decisions_log</template-output>
-<action>Add entry:</action>
-
-```
-- **{{date}}**: Completed research workflow ({{research_mode}} mode). Research report generated and saved. Next: Review findings and consider product-brief or plan-project workflows.
-```
+  <check if="success == true">
+    <output>Status updated! Next: {{next_workflow}}</output>
+  </check>
+</check>
 
 <output>**✅ Research Complete ({{research_mode}} mode)**
 

src/modules/bmm/workflows/1-analysis/research/instructions-router.md

@@ -10,31 +10,26 @@
 
 <critical>This is a ROUTER that directs to specialized research instruction sets</critical>
 
-<step n="1" goal="Check and load workflow status file">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-<action>Find the most recent file (by date in filename: bmm-workflow-status.md)</action>
+<step n="1" goal="Validate workflow readiness">
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: validate</param>
+  <param>calling_workflow: research</param>
+</invoke-workflow>
 
-<check if="exists">
-  <action>Load the status file</action>
-  <action>Set status_file_found = true</action>
-  <action>Store status_file_path for later updates</action>
+<check if="status_exists == false">
+  <output>{{suggestion}}</output>
+  <output>Note: Research is optional. Continuing without progress tracking.</output>
+  <action>Set standalone_mode = true</action>
 </check>
 
-<check if="not exists">
-  <ask>**No workflow status file found.**
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for status updates in sub-workflows</action>
+  <action>Pass status_file_path to loaded instruction set</action>
 
-This workflow conducts research (optional Phase 1 workflow).
-
-Options:
-
-1. Run workflow-status first to create the status file (recommended for progress tracking)
-2. Continue in standalone mode (no progress tracking)
-3. Exit
-
-What would you like to do?</ask>
-<action>If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to research"</action>
-<action>If user chooses option 2 → Set standalone_mode = true and continue</action>
-<action>If user chooses option 3 → HALT</action>
+  <check if="warning != ''">
+    <output>{{warning}}</output>
+    <output>Note: Research can provide valuable insights at any project stage.</output>
+  </check>
 </check>
 </step>
 

src/modules/bmm/workflows/1-analysis/research/instructions-technical.md

@@ -447,23 +447,16 @@ Select option (1-5):</ask>
 <action>Find the most recent file (by date in filename)</action>
 
 <check if="status file exists">
-  <action>Load the status file</action>
+  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <param>mode: update</param>
+    <param>action: complete_workflow</param>
+    <param>workflow_name: research</param>
+  </invoke-workflow>
 
-<template-output file="{{status_file_path}}">current_step</template-output>
-<action>Set to: "research (technical)"</action>
-
-<template-output file="{{status_file_path}}">current_workflow</template-output>
-<action>Set to: "research (technical) - Complete"</action>
-
-<template-output file="{{status_file_path}}">progress_percentage</template-output>
-<action>Increment by: 5% (optional Phase 1 workflow)</action>
-
-<template-output file="{{status_file_path}}">decisions_log</template-output>
-<action>Add entry:</action>
-
-```
-- **{{date}}**: Completed research workflow (technical mode). Technical research report generated and saved. Next: Review findings and consider plan-project workflow.
-```
+  <check if="success == true">
+    <output>Status updated! Next: {{next_workflow}}</output>
+  </check>
+</check>
 
 <output>**✅ Technical Research Complete**
 

src/modules/bmm/workflows/1-analysis/research/workflow.yaml

@@ -8,6 +8,8 @@ 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 - ROUTER PATTERN

src/modules/bmm/workflows/1-analysis/workflow-status/README.md

@@ -1,383 +0,0 @@
-# Workflow Status - Universal Entry Point
-
-## Overview
-
-The `workflow-status` workflow is the **universal entry point** for all BMad Method (BMM) workflows. It serves as both a status tracker and master router, helping users understand where they are in their project journey and what to do next.
-
-## Purpose
-
-**Primary Functions:**
-
-1. **Status Checking**: Read existing workflow status and display current state
-2. **Next Action Recommendation**: Suggest what the user should do next
-3. **Comprehensive Workflow Planning**: Map out ENTIRE workflow journey before executing anything
-4. **Planned Workflow Documentation**: Create status file with complete phase/step roadmap
-5. **Phase Navigation**: Guide users through the 4-phase methodology
-6. **Agent Coordination**: Can be invoked by any agent (bmad-master, analyst, pm)
-
-## When to Use
-
-### Automatic Invocation
-
-Agents should automatically check workflow status when loaded:
-
-- **bmad-master**: Checks status before displaying main menu
-- **analyst**: Checks status before displaying analysis options
-- **pm**: Checks status before displaying planning options
-
-### Manual Invocation
-
-Users can manually run this workflow anytime:
-
-```bash
-bmad analyst workflow-status
-# or
-bmad pm workflow-status
-# or just tell any agent: "check workflow status"
-```
-
-## Workflow Behavior
-
-### Scenario 1: No Status File Exists (New Project)
-
-**The workflow will map out your ENTIRE workflow journey:**
-
-**Step 1: Project Context**
-
-- Determine greenfield vs brownfield
-- Check if brownfield needs documentation
-- Note if `document-project` should be added to plan
-
-**Step 2: Scope Understanding**
-
-- Ask if user knows project level/scope
-- Options:
-  - **Yes**: Capture estimated level (0-4)
-  - **No**: Defer level determination to Phase 2 (plan-project)
-  - **Want analysis first**: Include Phase 1 in plan
-
-**Step 3: Choose Starting Point**
-
-- **Option A**: Full Analysis Phase (brainstorm → research → brief)
-- **Option B**: Skip to Planning (direct to PRD/GDD)
-- **Option C**: Just Show Menu (I'll decide manually)
-
-**Step 4: Build Complete Planned Workflow**
-The workflow builds a comprehensive plan including:
-
-- Phase 1 (if needed): document-project, brainstorm, research, brief
-- Phase 2 (always required): plan-project
-- Phase 3 (if Level 3-4): solution-architecture, tech-specs
-- Phase 4 (always): Full implementation workflow (create-story → story-ready → dev-story → story-approved)
-
-**Step 5: Create Status File**
-
-- Create `bmm-workflow-status.md`
-- Document complete planned workflow in "Planned Workflow Journey" table
-- Set current step: "Workflow Definition Phase"
-- Set next step: First item from planned workflow
-- Provide command to run next step
-
-**Brownfield Special Handling:**
-
-- Checks if codebase is documented
-- Adds `document-project` to planned workflow if needed
-- Does NOT immediately execute it - documents it in the plan first
-
-**Output:**
-
-- Complete workflow roadmap with phases, steps, agents, and descriptions
-- Status file with planned journey documented
-- Clear command to run first step
-- User can reference plan anytime via workflow-status
-
-### Scenario 2: Status File Exists (Project In Progress)
-
-**The workflow will:**
-
-1. Find most recent `bmm-workflow-status.md` file
-2. Read and parse current state:
-   - Current phase and progress %
-   - Project level and type
-   - Phase completion status
-   - Implementation progress (if Phase 4)
-   - Next recommended action
-3. Display comprehensive status summary
-4. Offer options:
-   - **Option 1**: Proceed with recommended action
-   - **Option 2**: View detailed status
-   - **Option 3**: Change workflow
-   - **Option 4**: Display agent menu
-   - **Option 5**: Exit
-
-**Phase 4 Special Display:**
-If in Implementation phase, shows:
-
-- BACKLOG story count
-- TODO story (ready for drafting)
-- IN PROGRESS story (being implemented)
-- DONE story count and points
-
-## Status File Detection
-
-**Search Pattern:**
-
-```
-{output_folder}/bmm-workflow-status.md
-```
-
-**Versioning:**
-
-- Files are named: `bmm-workflow-status.md`
-- Workflow finds most recent by date
-- Old files can be archived
-
-## Recommended Next Actions
-
-The workflow intelligently suggests next steps based on current state:
-
-**Phase 1 (Analysis):**
-
-- Continue with analysis workflows
-- Or move to `plan-project`
-
-**Phase 2 (Planning):**
-
-- If Level 0-1: Move to Phase 4 (`create-story`)
-- If Level 3-4: Move to Phase 3 (`solution-architecture`)
-
-**Phase 3 (Solutioning):**
-
-- Continue with tech-specs (JIT per epic)
-- Or move to Phase 4 (`create-story`)
-
-**Phase 4 (Implementation):**
-
-- Shows current TODO/IN PROGRESS story
-- Suggests exact next workflow (`story-ready`, `dev-story`, `story-approved`)
-
-## Integration with Agents
-
-### bmad-master
-
-```
-On load:
-1. Run workflow-status check
-2. If status found: Display summary + menu
-3. If no status: Offer to plan workflow
-4. Display master menu with context
-```
-
-### analyst
-
-```
-On load:
-1. Run workflow-status check
-2. If in Phase 1: Show analysis workflows
-3. If no status: Offer analysis planning
-4. Display analyst menu
-```
-
-### pm
-
-```
-On load:
-1. Run workflow-status check
-2. If no status: Offer to run plan-project
-3. If status found: Show current phase progress
-4. Display PM menu
-```
-
-## Example Outputs
-
-### No Status File (New User) - Planning Flow
-
-```
-🚀 Welcome to BMad Method Workflows!
-
-No workflow status file found. Let's plan your complete workflow journey.
-
-Step 1: Project Context
-
-Is this a new or existing codebase?
-   a. Greenfield - Starting from scratch
-   b. Brownfield - Adding to existing codebase
-
-Your choice (a/b): a
-
-Step 3: Understanding Your Workflow
-
-Before we plan your workflow, let's determine the scope and complexity of your project.
-
-The BMad Method uses 5 project levels (0-4) that determine which phases you'll need:
-- Level 0: Single atomic change (1 story) - Phases 2 → 4
-- Level 1: Small feature (2-3 stories, 1 epic) - Phases 2 → 4
-- Level 2: Medium project (multiple epics) - Phases 2 → 4
-- Level 3: Complex system (subsystems, integrations) - Phases 2 → 3 → 4
-- Level 4: Enterprise scale (multiple products) - Phases 2 → 3 → 4
-
-Do you already know your project's approximate size/scope?
-a. Yes - I can describe the general scope
-b. No - Not sure yet, need help determining it
-c. Want analysis first - Do brainstorming/research before deciding
-
-Your choice (a/b/c): a
-
-Based on the descriptions above, what level best describes your project?
-0. Single atomic change
-1. Small coherent feature
-2. Medium project
-3. Complex system
-4. Enterprise scale
-
-Your estimated level (0-4): 1
-
-Step 4: Choose Your Starting Point
-
-Option A: Full Analysis Phase First
-Option B: Skip to Planning
-Option C: Just Show Menu
-
-Your choice (A/B/C): B
-
-🗺️ Your Planned Workflow
-
-Based on your responses, here's your complete workflow journey:
-
-**2-Plan** - plan-project
-  - Agent: PM
-  - Description: Create PRD/GDD/Tech-Spec (determines final level)
-  - Status: Planned
-
-**3-Solutioning** - TBD - depends on level from Phase 2
-  - Agent: Architect
-  - Description: Required if Level 3-4, skipped if Level 0-2
-  - Status: Conditional
-
-**4-Implementation** - create-story (iterative)
-  - Agent: SM
-  - Description: Draft stories from backlog
-  - Status: Planned
-
-**4-Implementation** - story-ready
-  - Agent: SM
-  - Description: Approve story for dev
-  - Status: Planned
-
-**4-Implementation** - story-context
-  - Agent: SM
-  - Description: Generate context XML
-  - Status: Planned
-
-**4-Implementation** - dev-story (iterative)
-  - Agent: DEV
-  - Description: Implement stories
-  - Status: Planned
-
-**4-Implementation** - story-approved
-  - Agent: DEV
-  - Description: Mark complete, advance queue
-  - Status: Planned
-
----
-
-Current Step: Workflow Definition Phase (this workflow)
-Next Step: plan-project (PM agent)
-
-Ready to create your workflow status file?
-
-This will create: bmm-workflow-status.md
-
-The status file will document:
-- Your complete planned workflow (phases and steps)
-- Current phase: "Workflow Definition"
-- Next action: plan-project
-
-Create status file? (y/n): y
-
-✅ Status file created!
-
-File: bmm-workflow-status.md
-
-To proceed with your first step:
-
-Load PM: bmad pm plan-project
-
-You can always check your status with: workflow-status
-```
-
-### Status File Found (In Progress)
-
-```
-📊 Current Workflow Status
-
-Project: My Web App
-Started: 2025-10-10
-Last Updated: 2025-10-12
-
-Current Phase: 4-Implementation (65% complete)
-Current Workflow: Story implementation in progress
-
-Phase Completion:
-- [x] Phase 1: Analysis
-- [x] Phase 2: Planning
-- [ ] Phase 3: Solutioning (skipped for Level 1)
-- [ ] Phase 4: Implementation
-
-Planned Workflow Journey:
-Current Step: dev-story (DEV agent)
-Next Step: story-approved (DEV agent)
-
-Full planned workflow documented in status file - reference anytime!
-
-Project Details:
-- Level: 1 (Coherent feature, 1-10 stories)
-- Type: web
-- Context: greenfield
-
-Implementation Progress:
-- BACKLOG: 1 stories
-- TODO: (empty)
-- IN PROGRESS: auth-feature-2 (Ready)
-- DONE: 1 stories (5 points)
-
----
-
-🎯 Recommended Next Action:
-
-Implement story auth-feature-2
-
-Command: Run 'dev-story' workflow
-Agent: DEV
-
-Would you like to:
-1. Proceed with recommended action
-2. View detailed status (includes full planned workflow table)
-3. Change workflow
-4. Display agent menu
-5. Exit
-```
-
-## Benefits
-
-✅ **Complete Workflow Planning**: Maps out ENTIRE journey before executing anything
-✅ **No More Guessing**: Users always know current step AND what comes next
-✅ **Documented Roadmap**: Status file contains complete planned workflow table
-✅ **Context-Aware**: Recommendations adapt to project state and level
-✅ **Universal Entry Point**: Works with any agent
-✅ **New User Friendly**: Guides comprehensive workflow planning
-✅ **Status Visibility**: Clear progress tracking with current/next step indicators
-✅ **Phase Navigation**: Easy to jump between phases with planned path reference
-✅ **Level-Adaptive**: Plans adjust based on estimated project level (0-4)
-✅ **Brownfield Support**: Includes documentation needs in workflow plan
-
-## Future Enhancements
-
-- **Progress Dashboards**: Visual progress indicators
-- **Time Tracking**: Estimate time remaining
-- **Multi-Project**: Handle multiple projects
-- **Team Sync**: Show what teammates are working on
-
----
-
-**This workflow is the front door to BMad Method. Every user should start here or have it checked automatically by their agent.**

src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md

@@ -1,755 +0,0 @@
-# Workflow Status - Master Router and Status Tracker
-
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language}</critical>
-
-<workflow>
-
-<critical>This is the UNIVERSAL ENTRY POINT for all BMM workflows</critical>
-<critical>Can be invoked by bmad-master, analyst, or pm agents</critical>
-<critical>Checks for existing workflow status and suggests next actions</critical>
-<critical>If no status exists, helps user plan their workflow approach</critical>
-
-<step n="1" goal="Check for existing workflow status file">
-
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status\*.md</action>
-<action>Use glob or list_files to find all matching files</action>
-
-<check if="files found">
-  <action>Find the most recent file (by date in filename: bmm-workflow-status.md)</action>
-  <action>Set status_file_found = true</action>
-  <action>Set status_file_path = most recent file path</action>
-  <action>Go to Step 2 (Read existing status)</action>
-</check>
-
-<check if="no files found">
-  <action>Set status_file_found = false</action>
-  <action>Go to Step 3 (Initial workflow planning)</action>
-</check>
-
-</step>
-
-<step n="2" goal="Read and analyze existing workflow status" if="status_file_found == true">
-
-<action>Read {status_file_path}</action>
-
-<action>Extract key information:</action>
-
-**Project Context:**
-
-- project_name: From "Project:" field
-- start_date: From "Created:" field
-- last_updated: From "Last Updated:" field
-
-**Current State:**
-
-- current_phase: From "Current Phase:" field (1-Analysis, 2-Plan, 3-Solutioning, 4-Implementation)
-- current_workflow: From "Current Workflow:" field
-- progress_percentage: From "Overall Progress:" field
-- project_level: From "Project Level:" field (0, 1, 2, 3, or 4)
-- project_type: From "Project Type:" field
-- field_type: From "Greenfield/Brownfield:" field
-
-**Phase Completion:**
-
-- phase_1_complete: Check if "1-Analysis" checkbox is checked
-- phase_2_complete: Check if "2-Plan" checkbox is checked
-- phase_3_complete: Check if "3-Solutioning" checkbox is checked
-- phase_4_complete: Check if "4-Implementation" checkbox is checked
-
-**Implementation Progress (if Phase 4):**
-
-- Read "### Implementation Progress (Phase 4 Only)" section
-- Extract TODO story (if exists)
-- Extract IN PROGRESS story (if exists)
-- Extract BACKLOG count
-- Extract DONE count
-
-**Next Action:**
-
-- next_action: From "What to do next:" field
-- next_command: From "Command to run:" field
-- next_agent: From "Agent to load:" field
-
-<action>Analyze the current state to determine recommendation</action>
-
-</step>
-
-<step n="2.5" goal="Display current workflow status and suggest next action" if="status_file_found == true">
-
-<action>Display comprehensive status summary</action>
-
-**📊 Current Workflow Status**
-
-**Project:** {{project_name}}
-**Started:** {{start_date}}
-**Last Updated:** {{last_updated}}
-
-**Current Phase:** {{current_phase}} ({{progress_percentage}}% complete)
-**Current Workflow:** {{current_workflow}}
-
-**Phase Completion:**
-
-- [{{phase_1_complete ? 'x' : ' '}}] Phase 1: Analysis
-- [{{phase_2_complete ? 'x' : ' '}}] Phase 2: Planning
-- [{{phase_3_complete ? 'x' : ' '}}] Phase 3: Solutioning ({{project_level < 3 ? 'skipped for Level ' + project_level : 'required'}})
-- [{{phase_4_complete ? 'x' : ' '}}] Phase 4: Implementation
-
-**Project Details:**
-
-- **Level:** {{project_level}} ({{get_level_description(project_level)}})
-- **Type:** {{project_type}}
-- **Context:** {{field_type}}
-
-{{#if current_phase == '4-Implementation'}}
-**Implementation Progress:**
-
-- **BACKLOG:** {{backlog_count}} stories
-- **TODO:** {{todo_story_id}} ({{todo_story_status}})
-- **IN PROGRESS:** {{current_story_id}} ({{current_story_status}})
-- **DONE:** {{done_count}} stories ({{done_points}} points)
-  {{/if}}
-
----
-
-**🎯 Recommended Next Action:**
-
-{{next_action}}
-
-**Command:** {{next_command}}
-**Agent:** {{next_agent}}
-
-<ask>Would you like to:
-
-1. **Proceed with recommended action** ({{next_command}})
-2. **View detailed status** (show full status file)
-3. **Change workflow** (modify current workflow or start new phase)
-4. **Display agent menu** (see all available options)
-5. **Exit** (return to agent)
-
-Select option (1-5):</ask>
-
-<check if='option == "1"'>
-  <action>Suggest loading the recommended agent and running the command</action>
-  <output>**To proceed:**
-
-Load agent: `{{next_agent}}`
-Run command: `{{next_command}}`
-
-Or tell me: "load {{next_agent}} and {{next_command}}"
-</output>
-</check>
-
-<check if='option == "2"'>
-  <action>Display full status file contents</action>
-  <action>Return to menu</action>
-</check>
-
-<check if='option == "3"'>
-  <action>Go to Step 4 (Change workflow)</action>
-</check>
-
-<check if='option == "4"'>
-  <action>Go to Step 5 (Display agent menu)</action>
-</check>
-
-<check if='option == "5"'>
-  <action>Exit workflow</action>
-</check>
-
-</step>
-
-<step n="3" goal="Initial workflow planning - no status file exists" if="status_file_found == false">
-
-<action>Display welcome message in {communication_language}</action>
-
-**🚀 Welcome to BMad Method Workflows, {user_name}!**
-
-No workflow status file found. Let's plan your complete workflow journey.
-
-<critical>This step will map out your ENTIRE workflow before executing anything</critical>
-<critical>Goal: Document planned phases, current step, and next step in status file</critical>
-
-<ask>**Step 1: Project Context**
-
-**Is this a new or existing codebase?**
-a. **Greenfield** - Starting from scratch
-b. **Brownfield** - Adding to existing codebase
-
-Your choice (a/b):</ask>
-
-<action>Capture field_type = "greenfield" or "brownfield"</action>
-
-<check if='field_type == "brownfield"'>
-  <ask>**Step 2: Brownfield Documentation Status**
-
-Do you have:
-
-- Architecture documentation?
-- Code structure overview?
-- API documentation?
-- Clear understanding of existing patterns?
-
-Options:
-a. **Yes** - I have good documentation
-b. **No** - Codebase is undocumented or poorly documented
-c. **Partial** - Some docs exist but incomplete
-
-Your choice (a/b/c):</ask>
-
-<action>Capture brownfield_docs_status</action>
-
-  <check if='brownfield_docs_status == "b" OR brownfield_docs_status == "c"'>
-    <output>**⚠️ Documentation Needed**
-
-For accurate planning, brownfield projects benefit from codebase documentation.
-We'll add `document-project` to your planned workflow.
-</output>
-<action>Set needs_documentation = true</action>
-</check>
-
-  <check if='brownfield_docs_status == "a"'>
-    <action>Set needs_documentation = false</action>
-  </check>
-</check>
-
-<check if='field_type == "greenfield"'>
-  <action>Set needs_documentation = false</action>
-</check>
-
-<ask>**Step 3: Project Type**
-
-What type of project are you building?
-
-1. **Game** - Video games for PC, console, mobile, or web
-2. **Web Application** - Websites, web apps, SPAs
-3. **Mobile Application** - iOS, Android apps
-4. **Desktop Application** - Windows, macOS, Linux apps
-5. **Backend/API Service** - Backend services, APIs, microservices
-6. **Library/SDK** - Reusable libraries, packages, SDKs
-7. **CLI Tool** - Command-line tools and utilities
-8. **Embedded System** - IoT, firmware, embedded devices
-9. **Data/ML/Analytics** - Data pipelines, ML projects, analytics
-10. **Browser Extension** - Chrome, Firefox extensions
-11. **Infrastructure/DevOps** - Terraform, K8s operators, CI/CD
-12. **Other** - Describe your project type
-
-Your choice (1-12):</ask>
-
-<action>Capture project_type_choice</action>
-
-<action>Map choice to project_type_id using project-types.csv:</action>
-
-- 1 → game
-- 2 → web
-- 3 → mobile
-- 4 → desktop
-- 5 → backend
-- 6 → library
-- 7 → cli
-- 8 → embedded
-- 9 → data
-- 10 → extension
-- 11 → infra
-- 12 → custom (capture description)
-
-<action>Set project_type = mapped project_type_id</action>
-
-<ask>**Step 4: User Interface Components**
-
-Does your project involve user-facing UI components?
-
-a. **Yes** - Project has user interface elements (web pages, mobile screens, desktop UI, game UI)
-b. **No** - Backend-only, API, CLI, or no visual interface
-
-Your choice (a/b):</ask>
-
-<action>Capture has_ui_components</action>
-
-<check if='has_ui_components == "a"'>
-  <action>Set needs_ux_workflow = true</action>
-  <output>**✅ UX Workflow Detected**
-
-Since your project has UI components, we'll include the UX specification workflow in Phase 2.
-This ensures proper UX/UI design happens between PRD and architecture/implementation.
-</output>
-</check>
-
-<check if='has_ui_components == "b"'>
-  <action>Set needs_ux_workflow = false</action>
-</check>
-
-<output>**Step 5: Understanding Your Workflow**
-
-Before we plan your workflow, let's determine the scope and complexity of your project.
-
-The BMad Method uses 5 project levels (0-4) that determine which phases you'll need:
-
-- **Level 0:** Single atomic change (1 story) - Phases 2 → 4
-- **Level 1:** Small feature (2-3 stories, 1 epic) - Phases 2 → 4
-- **Level 2:** Medium project (multiple epics) - Phases 2 → 4
-- **Level 3:** Complex system (subsystems, integrations) - Phases 2 → 3 → 4
-- **Level 4:** Enterprise scale (multiple products) - Phases 2 → 3 → 4
-
-**Optional Phase 1 (Analysis):** Brainstorming, research, and brief creation can precede any level.
-</output>
-
-<ask>**Step 6: Project Scope Assessment**
-
-Do you already know your project's approximate size/scope?
-
-a. **Yes** - I can describe the general scope
-b. **No** - Not sure yet, need help determining it
-c. **Want analysis first** - Do brainstorming/research before deciding
-
-Your choice (a/b/c):</ask>
-
-<action>Capture scope_knowledge</action>
-
-<check if='scope_knowledge == "a"'>
-  <ask>**Based on the descriptions above, what level best describes your project?**
-
-0. Single atomic change (bug fix, tiny feature)
-1. Small coherent feature (2-3 stories)
-2. Medium project (multiple features/epics)
-3. Complex system (subsystems, architectural decisions)
-4. Enterprise scale (multiple products/systems)
-
-Your estimated level (0-4):</ask>
-
-<action>Capture estimated_level</action>
-<action>Set level_known = true</action>
-</check>
-
-<check if='scope_knowledge == "b" OR scope_knowledge == "c"'>
-  <output>**Level determination deferred**
-
-{{#if scope_knowledge == "b"}}
-No problem! The `plan-project` workflow will help you determine the project level through guided questions.
-{{/if}}
-
-{{#if scope_knowledge == "c"}}
-Great! Analysis workflows will help clarify scope before determining the level.
-{{/if}}
-
-We'll determine your project level during Phase 2 (Planning).
-</output>
-<action>Set level_known = false</action>
-<action>Set estimated_level = "TBD"</action>
-</check>
-
-<ask>**Step 7: Choose Your Starting Point**
-
-Now let's determine where you want to begin:
-
-**Option A: Full Analysis Phase First**
-
-- Brainstorming (explore ideas, validate concepts)
-- Research (market, technical, competitive analysis)
-- Product/Game Brief (strategic foundation)
-  → Best for: New ideas, uncertain requirements, need validation
-
-**Option B: Skip to Planning**
-
-- You know what to build
-- Jump to PRD/GDD/Tech-Spec generation
-  → Best for: Clear requirements, existing ideas
-
-**Option C: Just Show Menu**
-
-- Create status file with planned workflow
-- I'll manually choose which workflow to run first
-  → Best for: Experienced users, custom paths
-
-Your choice (A/B/C):</ask>
-
-<action>Capture starting_point</action>
-
-<check if='starting_point == "A"'>
-  <ask>**Full Analysis - Choose your first workflow:**
-
-1. **brainstorm-project** (Analyst) - Explore software solution ideas
-2. **brainstorm-game** (Game Designer) - Game concept ideation
-3. **research** (Analyst) - Market/technical research
-4. **product-brief** (Analyst) - Strategic product foundation
-5. **game-brief** (Game Designer) - Game design foundation
-
-Which workflow? (1-5):</ask>
-
-<action>Capture first_workflow</action>
-<action>Set include_analysis = true</action>
-</check>
-
-<check if='starting_point == "B"'>
-  <action>Set include_analysis = false</action>
-  <action>Set first_workflow = "plan-project"</action>
-</check>
-
-<check if='starting_point == "C"'>
-  <action>Set include_analysis = false</action>
-  <action>Set first_workflow = "user-choice"</action>
-</check>
-
-<action>Now build the complete planned workflow</action>
-
-<output>**🗺️ Your Planned Workflow**
-
-Based on your responses, here's your complete workflow journey:
-</output>
-
-<action>Build planned_workflow array with all phases in order:</action>
-
-<check if='needs_documentation == true'>
-  <action>Add to planned_workflow:</action>
-  - Phase: "1-Analysis"
-  - Step: "document-project"
-  - Agent: "Analyst"
-  - Description: "Generate brownfield codebase documentation"
-  - Status: "Planned"
-</check>
-
-<check if='include_analysis == true'>
-  <action>Add analysis workflows to planned_workflow based on first_workflow choice</action>
-
-{{#if first_workflow == "brainstorm-project"}} - Phase: "1-Analysis", Step: "brainstorm-project", Agent: "Analyst", Status: "Planned" - Phase: "1-Analysis", Step: "research (optional)", Agent: "Analyst", Status: "Optional" - Phase: "1-Analysis", Step: "product-brief", Agent: "Analyst", Status: "Planned"
-{{/if}}
-
-{{#if first_workflow == "brainstorm-game"}} - Phase: "1-Analysis", Step: "brainstorm-game", Agent: "Game Designer", Status: "Planned" - Phase: "1-Analysis", Step: "research (optional)", Agent: "Analyst", Status: "Optional" - Phase: "1-Analysis", Step: "game-brief", Agent: "Game Designer", Status: "Planned"
-{{/if}}
-
-{{#if first_workflow == "research"}} - Phase: "1-Analysis", Step: "research", Agent: "Analyst", Status: "Planned" - Phase: "1-Analysis", Step: "product-brief or game-brief", Agent: "Analyst/Game Designer", Status: "Planned"
-{{/if}}
-
-{{#if first_workflow == "product-brief"}} - Phase: "1-Analysis", Step: "product-brief", Agent: "Analyst", Status: "Planned"
-{{/if}}
-
-{{#if first_workflow == "game-brief"}} - Phase: "1-Analysis", Step: "game-brief", Agent: "Game Designer", Status: "Planned"
-{{/if}}
-</check>
-
-<action>Always add Phase 2 (required for all levels) - route based on project type and level</action>
-
-<check if='project_type == "game"'>
-  <action>Add game planning workflow</action>
-  - Phase: "2-Plan"
-  - Step: "gdd"
-  - Agent: "PM"
-  - Description: "Create Game Design Document"
-  - Status: "Planned"
-</check>
-
-<check if='project_type != "game"'>
-  <check if='level_known == true AND estimated_level <= 1'>
-    <action>Add tech-spec workflow (Levels 0-1)</action>
-    - Phase: "2-Plan"
-    - Step: "tech-spec"
-    - Agent: "Architect"
-    - Description: "Create technical specification and stories"
-    - Status: "Planned"
-  </check>
-
-  <check if='level_known == true AND estimated_level >= 2'>
-    <action>Add PRD workflow (Levels 2-4)</action>
-    - Phase: "2-Plan"
-    - Step: "prd"
-    - Agent: "PM"
-    - Description: "Create Product Requirements Document and epics"
-    - Status: "Planned"
-  </check>
-
-  <check if='level_known == false OR estimated_level == "TBD"'>
-    <action>Add conditional planning note</action>
-    - Phase: "2-Plan"
-    - Step: "TBD - Level 0-1 → tech-spec, Level 2-4 → prd"
-    - Agent: "PM or Architect"
-    - Description: "Workflow determined after level assessment"
-    - Status: "Conditional"
-  </check>
-</check>
-
-<check if='needs_ux_workflow == true'>
-  <action>Add UX workflow to Phase 2 planning (runs after PRD, before Phase 3)</action>
-  - Phase: "2-Plan"
-  - Step: "ux-spec"
-  - Agent: "PM"
-  - Description: "UX/UI specification (user flows, wireframes, components)"
-  - Status: "Planned"
-  - Note: "Required for projects with UI components"
-</check>
-
-<check if='level_known == true AND estimated_level >= 3'>
-  <action>Add Phase 3 (required for Level 3-4)</action>
-  - Phase: "3-Solutioning"
-  - Step: "solution-architecture"
-  - Agent: "Architect"
-  - Description: "Design overall architecture"
-  - Status: "Planned"
-
-- Phase: "3-Solutioning"
-- Step: "tech-spec (per epic, JIT)"
-- Agent: "Architect"
-- Description: "Epic-specific technical specs"
-- Status: "Planned"
-  </check>
-
-<check if='level_known == false OR estimated_level == "TBD"'>
-  <action>Add conditional Phase 3 note</action>
-  - Phase: "3-Solutioning"
-  - Step: "TBD - depends on level from Phase 2"
-  - Agent: "Architect"
-  - Description: "Required if Level 3-4, skipped if Level 0-2"
-  - Status: "Conditional"
-</check>
-
-<action>Always add Phase 4 (implementation)</action>
-
-- Phase: "4-Implementation"
-- Step: "create-story (iterative)"
-- Agent: "SM"
-- Description: "Draft stories from backlog"
-- Status: "Planned"
-
-- Phase: "4-Implementation"
-- Step: "story-ready"
-- Agent: "SM"
-- Description: "Approve story for dev"
-- Status: "Planned"
-
-- Phase: "4-Implementation"
-- Step: "story-context"
-- Agent: "SM"
-- Description: "Generate context XML"
-- Status: "Planned"
-
-- Phase: "4-Implementation"
-- Step: "dev-story (iterative)"
-- Agent: "DEV"
-- Description: "Implement stories"
-- Status: "Planned"
-
-- Phase: "4-Implementation"
-- Step: "story-approved"
-- Agent: "DEV"
-- Description: "Mark complete, advance queue"
-- Status: "Planned"
-
-<action>Display the complete planned workflow</action>
-
-<output>**📋 Your Complete Planned Workflow:**
-
-{{#each planned_workflow}}
-**{{phase}}** - {{step}}
-
-- Agent: {{agent}}
-- Description: {{description}}
-- Status: {{status}}
-
-{{/each}}
-
----
-
-**Current Step:** Workflow Definition Phase (this workflow)
-**Next Step:** {{planned_workflow[0].step}} ({{planned_workflow[0].agent}} agent)
-</output>
-
-<ask>**Ready to create your workflow status file?**
-
-This will create: `bmm-workflow-status.md`
-
-The status file will document:
-
-- Your complete planned workflow (phases and steps)
-- Current phase: "Workflow Definition"
-- Next action: {{planned_workflow[0].step}}
-
-Create status file? (y/n)</ask>
-
-<check if='confirm == "y"'>
-  <action>Create bmm-workflow-status.md file</action>
-  <action>Set current_phase = "Workflow Definition"</action>
-  <action>Set next_action = planned_workflow[0].step</action>
-  <action>Set next_agent = planned_workflow[0].agent</action>
-  <action>Include complete planned_workflow in status file</action>
-
-<output>**✅ Status file created, {user_name}!**
-
-File: `bmm-workflow-status.md`
-
-**To proceed with your first step:**
-
-{{#if needs_documentation == true AND planned_workflow[0].step == "document-project"}}
-Load Analyst: `bmad analyst document-project`
-
-After documentation is complete, return to check status: `bmad analyst workflow-status`
-{{/if}}
-
-{{#if planned_workflow[0].step != "document-project" AND planned_workflow[0].step != "user-choice"}}
-{{#if planned_workflow[0].step == "gdd"}}
-Load PM: `bmad pm gdd`
-{{else if planned_workflow[0].step == "tech-spec"}}
-Load Architect: `bmad architect tech-spec`
-{{else if planned_workflow[0].step == "prd"}}
-Load PM: `bmad pm prd`
-{{else}}
-Load {{planned_workflow[0].agent}}: `bmad {{lowercase planned_workflow[0].agent}} {{planned_workflow[0].step}}`
-{{/if}}
-{{/if}}
-
-{{#if planned_workflow[0].step == "user-choice"}}
-Your status file is ready! Run `workflow-status` anytime to see recommendations.
-
-Choose any workflow from the menu to begin.
-{{/if}}
-
-You can always check your status with: `workflow-status`
-</output>
-</check>
-
-<check if='confirm == "n"'>
-  <action>Go to Step 5 (Display agent menu)</action>
-</check>
-
-</step>
-
-<step n="4" goal="Change workflow or start new phase" optional="true">
-
-<ask>**Change Workflow Options:**
-
-1. **Start new workflow** (will archive current status, create new dated file)
-2. **Jump to different phase** (manual phase override)
-3. **Modify current workflow** (change current_workflow field)
-4. **View phase options** (see what's available for current level)
-5. **Cancel** (return to status display)
-
-Your choice (1-5):</ask>
-
-<action>Handle workflow change based on choice</action>
-
-<check if='choice == "1"'>
-  <ask>**Start New Workflow**
-
-This will:
-
-- Archive current status: `bmm-workflow-status.md` → `archive/`
-- Create new status: `bmm-workflow-status.md`
-- Start fresh assessment
-
-Continue? (y/n)</ask>
-
-  <check if="confirm == 'y'">
-    <output>**To start new workflow:**
-
-Run: `bmad analyst workflow-status`
-
-This will guide you through fresh workflow assessment and create a new status file.
-</output>
-</check>
-</check>
-
-<check if='choice == "2"'>
-  <ask>**Jump to Phase:**
-
-Current phase: {{current_phase}}
-
-Available phases:
-
-1. Phase 1: Analysis
-2. Phase 2: Planning
-3. Phase 3: Solutioning ({{project_level >= 3 ? 'required for your level' : 'skipped for Level ' + project_level}})
-4. Phase 4: Implementation
-
-Which phase? (1-4)</ask>
-
-<action>Provide guidance for jumping to selected phase</action>
-</check>
-
-</step>
-
-<step n="5" goal="Display agent menu">
-
-<action>Display comprehensive agent menu based on current context</action>
-
-**📋 BMad Method Agent Menu**
-
-{{#if status_file_found}}
-**Current Phase:** {{current_phase}}
-{{/if}}
-
-**Available Workflows by Phase:**
-
-**Phase 1: Analysis (Optional)**
-
-- `brainstorm-project` - Software solution exploration
-- `brainstorm-game` - Game concept ideation
-- `research` - Market/technical research
-- `product-brief` - Strategic product foundation
-- `game-brief` - Game design foundation
-
-**Phase 2: Planning (Required)**
-
-- `prd` - Product Requirements Document (Level 2-4 software projects)
-- `tech-spec` - Technical specification (Level 0-1 software projects)
-- `gdd` - Game Design Document (game projects)
-- `ux-spec` - UX/UI specification (for projects with UI components)
-
-**Phase 3: Solutioning (Level 3-4 Only)**
-
-- `solution-architecture` - Overall architecture design
-- `tech-spec` - Epic-specific technical specs (JIT)
-
-**Phase 4: Implementation (Iterative)**
-
-- `create-story` - Draft story from TODO
-- `story-ready` - Approve story for development
-- `story-context` - Generate context XML
-- `dev-story` - Implement story
-- `story-approved` - Mark story done
-- `review-story` - Quality validation
-- `correct-course` - Handle issues
-- `retrospective` - Epic learnings
-
-**Utility Workflows:**
-
-- `workflow-status` - Check status and get recommendations (you are here!)
-
-{{#if status_file_found}}
-
-**🎯 Recommended for Your Current Phase ({{current_phase}}):**
-
-{{#if current_phase == '1-Analysis'}}
-Continue analysis or move to Phase 2 Planning (prd/tech-spec/gdd based on your project)
-{{/if}}
-
-{{#if current_phase == '2-Plan'}}
-{{#if project_level < 2}}
-Ready for Phase 4! Run `create-story` (SM agent)
-{{else if project_level == 2}}
-Run `tech-spec` workflow for lightweight technical planning, then Phase 4
-{{else}}
-Ready for Phase 3! Run `solution-architecture` (Architect agent)
-{{/if}}
-{{/if}}
-
-{{#if current_phase == '3-Solutioning'}}
-Continue with tech-specs or move to Phase 4 `create-story`
-{{/if}}
-
-{{#if current_phase == '4-Implementation'}}
-**Current Story:** {{todo_story_id || current_story_id || 'Check status file'}}
-**Next Action:** {{next_command}}
-{{/if}}
-
-{{/if}}
-
-<ask>Would you like to:
-
-1. Run a specific workflow (tell me which one)
-2. Return to status display
-3. Exit
-
-Your choice:</ask>
-
-</step>
-
-</workflow>

src/modules/bmm/workflows/1-analysis/workflow-status/workflow.yaml

@@ -1,20 +0,0 @@
-# Workflow Status - Master Router and Status Tracker
-name: workflow-status
-description: "Universal entry point for BMM workflows. Checks for existing workflow status, displays current state, suggests next actions, or helps plan new workflow. Can be invoked by any agent (bmad-master, analyst, pm) to understand where the project is and what to do next."
-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"
-date: system-generated
-
-# Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status"
-instructions: "{installed_path}/instructions.md"
-
-# Output configuration - no output file, reads existing status
-default_output_file: ""
-
-web_bundle: false

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

@@ -4,67 +4,85 @@
 
 <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}</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 is the GDD instruction set for GAME projects - replaces PRD with Game Design Document</critical>
 <critical>Project analysis already completed - proceeding with game-specific design</critical>
 <critical>Uses gdd_template for GDD output, game_types.csv for type-specific sections</critical>
 <critical>Routes to 3-solutioning for architecture (platform-specific decisions handled there)</critical>
 <critical>If users mention technical details, append to technical_preferences with timestamp</critical>
 
-<step n="0" goal="Check for workflow status file - REQUIRED">
+<critical>DOCUMENT OUTPUT: Concise, clear, actionable game design specs. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
 
-<action>Check if bmm-workflow-status.md exists in {output_folder}/</action>
+<step n="0" goal="Validate workflow and extract project configuration">
 
-<check if="not exists">
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: data</param>
+  <param>data_request: project_config</param>
+</invoke-workflow>
+
+<check if="status_exists == false">
   <output>**⚠️ No Workflow Status File Found**
 
-The GDD workflow requires an existing workflow status file to understand your project context.
+The GDD workflow requires a status file to understand your project context.
 
-Please run `workflow-status` first to:
+Please run `workflow-init` first to:
 
-- Map out your complete workflow journey
-- Determine project type and level
-- Create the status file with your planned workflow
+- Define your project type and level
+- Map out your workflow journey
+- Create the status file
 
-**To proceed:**
+Run: `workflow-init`
 
-Run: `bmad analyst workflow-status`
-
-After completing workflow planning, you'll be directed back to this workflow.
+After setup, return here to create your GDD.
 </output>
 <action>Exit workflow - cannot proceed without status file</action>
 </check>
 
-<check if="exists">
-  <action>Load status file and proceed to Step 1</action>
-</check>
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for later updates</action>
 
+  <check if="project_type != 'game'">
+    <output>**Incorrect Workflow for Software Projects**
+
+Your project is type: {{project_type}}
+
+**Correct workflows for software projects:**
+
+- Level 0-1: `tech-spec` (Architect agent)
+- Level 2-4: `prd` (PM agent)
+
+{{#if project_level <= 1}}
+Use: `tech-spec`
+{{else}}
+Use: `prd`
+{{/if}}
+</output>
+<action>Exit and redirect to appropriate workflow</action>
+</check>
+</check>
+</step>
+
+<step n="0.5" goal="Validate workflow sequencing">
+
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: validate</param>
+  <param>calling_workflow: gdd</param>
+</invoke-workflow>
+
+<check if="warning != ''">
+  <output>{{warning}}</output>
+  <ask>Continue with GDD anyway? (y/n)</ask>
+  <check if="n">
+    <output>{{suggestion}}</output>
+    <action>Exit workflow</action>
+  </check>
+</check>
 </step>
 
 <step n="1" goal="Load context and determine game type">
 
-<action>Load bmm-workflow-status.md</action>
-<action>Confirm project_type == "game"</action>
-
-<check if="project_type != game">
-  <error>This workflow is for game projects only. Software projects should use PRD or tech-spec workflows.</error>
-  <output>**Incorrect Workflow for Software Projects**
-
-Your status file indicates project_type: {{project_type}}
-
-**Correct workflows for software projects:**
-
-- Level 0-1: `tech-spec` (run with Architect agent)
-- Level 2-4: `prd` (run with PM agent)
-
-{{#if project_level <= 1}}
-Run: `bmad architect tech-spec`
-{{else}}
-Run: `bmad pm prd`
-{{/if}}
-</output>
-<action>Exit and redirect user to appropriate software workflow</action>
-</check>
+<action>Use {{project_type}} and {{project_level}} from status data</action>
 
 <check if="continuation_mode == true">
   <action>Load existing GDD.md and check completion status</action>
@@ -306,7 +324,23 @@ For each {{placeholder}} in the fragment, elicit and capture that information.
 
 </step>
 
-<step n="15" goal="Generate solutioning handoff and next steps">
+<step n="15" goal="Update status and populate story sequence">
+
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: update</param>
+  <param>action: complete_workflow</param>
+  <param>workflow_name: gdd</param>
+  <param>populate_stories_from: {epics_output_file}</param>
+</invoke-workflow>
+
+<check if="success == true">
+  <output>Status updated! Next: {{next_workflow}} ({{next_agent}} agent)</output>
+  <output>Loaded {{total_stories}} stories from epics.</output>
+</check>
+
+</step>
+
+<step n="16" goal="Generate solutioning handoff and next steps">
 
 <action>Check if game-type fragment contained narrative tags indicating narrative importance</action>
 

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

@@ -8,6 +8,8 @@ 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

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

@@ -10,6 +10,23 @@
 <critical>If users mention gameplay mechanics, note them but keep focus on narrative</critical>
 <critical>Facilitate good brainstorming techniques throughout with the user, pushing them to come up with much of the narrative you will help weave together. The goal is for the user to feel that they crafted the narrative and story arc unless they push you to do it all or indicate YOLO</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 GDD context and assess narrative complexity">
 
 <action>Load GDD.md from {output_folder}</action>
@@ -522,4 +539,19 @@ Which would you like?</ask>
 
 </step>
 
+<step n="17" 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: narrative</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/narrative/workflow.yaml

@@ -8,6 +8,8 @@ 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

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

@@ -2,73 +2,86 @@
 
 <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}</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 is for Level 2-4 projects. Level 0-1 use tech-spec workflow.</critical>
 <critical>Produces TWO outputs: PRD.md (strategic) and epics.md (tactical implementation)</critical>
 <critical>TECHNICAL NOTES: If ANY technical details, preferences, or constraints are mentioned during PRD discussions, append them to {technical_decisions_file}. If file doesn't exist, create it from {technical_decisions_template}</critical>
 
+<critical>DOCUMENT OUTPUT: Concise, clear, actionable requirements. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
+
 <workflow>
 
-<step n="0" goal="Check for workflow status file - REQUIRED">
+<step n="0" goal="Validate workflow and extract project configuration">
 
-<action>Check if bmm-workflow-status.md exists in {output_folder}/</action>
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: data</param>
+  <param>data_request: project_config</param>
+</invoke-workflow>
 
-<check if="not exists">
+<check if="status_exists == false">
   <output>**⚠️ No Workflow Status File Found**
 
-The PRD workflow requires an existing workflow status file to understand your project context.
+The PRD workflow requires a status file to understand your project context.
 
-Please run `workflow-status` first to:
+Please run `workflow-init` first to:
 
-- Map out your complete workflow journey
-- Determine project type and level
-- Create the status file with your planned workflow
+- Define your project type and level
+- Map out your workflow journey
+- Create the status file
 
-**To proceed:**
+Run: `workflow-init`
 
-Run: `bmad analyst workflow-status`
-
-After completing workflow planning, you'll be directed back to this workflow.
+After setup, return here to create your PRD.
 </output>
 <action>Exit workflow - cannot proceed without status file</action>
 </check>
 
-<check if="exists">
-  <action>Load status file: {status_file}</action>
-  <action>Proceed to Step 1</action>
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for later updates</action>
+
+  <check if="project_level < 2">
+    <output>**Incorrect Workflow for Level {{project_level}}**
+
+PRD is for Level 2-4 projects. Level 0-1 should use tech-spec directly.
+
+**Correct workflow:** `tech-spec` (Architect agent)
+</output>
+<action>Exit and redirect to tech-spec</action>
 </check>
 
+  <check if="project_type == game">
+    <output>**Incorrect Workflow for Game Projects**
+
+Game projects should use GDD workflow instead of PRD.
+
+**Correct workflow:** `gdd` (PM agent)
+</output>
+<action>Exit and redirect to gdd</action>
+</check>
+</check>
 </step>
 
-<step n="1" goal="Initialize and load context">
+<step n="0.5" goal="Validate workflow sequencing">
 
-<action>Extract project context from status file</action>
-<action>Verify project_level is 2, 3, or 4</action>
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: validate</param>
+  <param>calling_workflow: prd</param>
+</invoke-workflow>
 
-<check if="project_level < 2">
-  <error>This workflow is for Level 2-4 only. Level 0-1 should use tech-spec workflow.</error>
-  <output>**Incorrect Workflow for Your Level**
-
-Your status file indicates Level {{project_level}}.
-
-**Correct workflow:** `tech-spec` (run with Architect agent)
-
-Run: `bmad architect tech-spec`
-</output>
-<action>Exit and redirect user to tech-spec workflow</action>
+<check if="warning != ''">
+  <output>{{warning}}</output>
+  <ask>Continue with PRD anyway? (y/n)</ask>
+  <check if="n">
+    <output>{{suggestion}}</output>
+    <action>Exit workflow</action>
+  </check>
 </check>
+</step>
 
-<check if="project_type == game">
-  <error>This workflow is for software projects. Game projects should use GDD workflow.</error>
-  <output>**Incorrect Workflow for Game Projects**
-
-**Correct workflow:** `gdd` (run with PM agent)
-
-Run: `bmad pm gdd`
-</output>
-<action>Exit and redirect user to gdd workflow</action>
-</check>
+<step n="1" goal="Initialize PRD context">
 
+<action>Use {{project_level}} from status data</action>
 <action>Check for existing PRD.md in {output_folder}</action>
 
 <check if="PRD.md exists">
@@ -392,39 +405,49 @@ For each epic from the epic list, expand with full story details:
 
 </step>
 
-<step n="10" goal="Update workflow status and complete">
+<step n="10" goal="Update status and complete">
 
-<action>Update {status_file} with completion status</action>
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: update</param>
+  <param>action: complete_workflow</param>
+  <param>workflow_name: prd</param>
+  <param>populate_stories_from: {epics_output_file}</param>
+</invoke-workflow>
 
-<template-output file="bmm-workflow-status.md">prd_completion_update</template-output>
+<check if="success == true">
+  <output>Status updated! Next: {{next_workflow}} ({{next_agent}} agent)</output>
+  <output>Loaded {{total_stories}} stories from epics.</output>
+</check>
 
-**✅ PRD Workflow Complete, {user_name}!**
+<output>**✅ PRD Workflow Complete, {user_name}!**
 
 **Deliverables Created:**
 
-1. ✅ PRD.md - Strategic product requirements document
-2. ✅ epics.md - Tactical implementation roadmap with story breakdown
+1. ✅ bmm-PRD.md - Strategic product requirements document
+2. ✅ bmm-epics.md - Tactical implementation roadmap with story breakdown
 
 **Next Steps:**
 
-<check if="level == 2">
-  - Review PRD and epics with stakeholders
-  - **Next:** Run tech-spec workflow for lightweight technical planning
-  - Then proceed to implementation (create-story workflow)
-</check>
+{{#if project_level == 2}}
 
-<check if="level >= 3">
-  - Review PRD and epics with stakeholders
-  - **Next:** Run solution-architecture workflow for full technical design
-  - Then proceed to implementation (create-story workflow)
-</check>
+- Review PRD and epics with stakeholders
+- **Next:** Run `tech-spec` for lightweight technical planning
+- Then proceed to implementation
+  {{/if}}
 
-<ask>Would you like to:
+{{#if project_level >= 3}}
+
+- Review PRD and epics with stakeholders
+- **Next:** Run `solution-architecture` for full technical design
+- Then proceed to implementation
+  {{/if}}
+
+Would you like to:
 
 1. Review/refine any section
-2. Proceed to next phase (tech-spec for Level 2, solution-architecture for Level 3-4)
+2. Proceed to next phase
 3. Exit and review documents
-   </ask>
+   </output>
 
 </step>
 

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

@@ -9,6 +9,8 @@ project_name: "{config_source}:project_name"
 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
@@ -18,7 +20,6 @@ instructions: "{installed_path}/instructions.md"
 # Templates
 prd_template: "{installed_path}/prd-template.md"
 epics_template: "{installed_path}/epics-template.md"
-status_template: "{project-root}/bmad/bmm/workflows/_shared/bmm-workflow-status-template.md"
 
 # Output files
 status_file: "{output_folder}/bmm-workflow-status.md"
@@ -41,4 +42,3 @@ web_bundle:
     - "bmad/bmm/workflows/2-plan-workflows/prd/instructions.md"
     - "bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md"
     - "bmad/bmm/workflows/2-plan-workflows/prd/epics-template.md"
-    - "bmad/bmm/workflows/_shared/bmm-workflow-status-template.md"

src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md

@@ -98,82 +98,27 @@
 
 </step>
 
-<step n="4" goal="Update bmm-workflow-status and initialize Phase 4">
+<step n="4" goal="Update status - Level 0 single story">
 
-<action>Open {output_folder}/bmm-workflow-status.md</action>
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: update</param>
+  <param>action: complete_workflow</param>
+  <param>workflow_name: tech-spec</param>
+</invoke-workflow>
 
-<action>Update "Workflow Status Tracker" section:</action>
+<check if="success == true">
+  <output>✅ Tech-spec complete! Next: {{next_workflow}}</output>
+</check>
 
-- Set current_phase = "4-Implementation" (Level 0 skips Phase 3)
-- Set current_workflow = "tech-spec (Level 0 - story generation complete, ready for implementation)"
-- Check "2-Plan" checkbox in Phase Completion Status
-- Set progress_percentage = 40% (planning complete, skipping solutioning)
+<action>Load {{status_file_path}}</action>
+<action>Set STORIES_SEQUENCE: [{slug}]</action>
+<action>Set TODO_STORY: {slug}</action>
+<action>Set TODO_TITLE: {{story_title}}</action>
+<action>Set IN_PROGRESS_STORY: (empty)</action>
+<action>Set STORIES_DONE: []</action>
+<action>Save {{status_file_path}}</action>
 
-<action>Initialize Phase 4 Implementation Progress section:</action>
-
-#### BACKLOG (Not Yet Drafted)
-
-**Ordered story sequence - populated at Phase 4 start:**
-
-| Epic                               | Story | ID  | Title | File |
-| ---------------------------------- | ----- | --- | ----- | ---- |
-| (empty - Level 0 has only 1 story) |       |     |       |      |
-
-**Total in backlog:** 0 stories
-
-**NOTE:** Level 0 has single story only. No additional stories in backlog.
-
-#### TODO (Needs Drafting)
-
-Initialize with the ONLY story (already drafted):
-
-- **Story ID:** {slug}
-- **Story Title:** {{story_title}}
-- **Story File:** `story-{slug}.md`
-- **Status:** Draft (needs review before development)
-- **Action:** User reviews drafted story, then runs SM agent `story-ready` workflow to approve
-
-#### IN PROGRESS (Approved for Development)
-
-Leave empty initially:
-
-(Story will be moved here by SM agent `story-ready` workflow after user approves story-{slug}.md)
-
-#### DONE (Completed Stories)
-
-Initialize empty table:
-
-| Story ID   | File | Completed Date | Points |
-| ---------- | ---- | -------------- | ------ |
-| (none yet) |      |                |        |
-
-**Total completed:** 0 stories
-**Total points completed:** 0 points
-
-<action>Add to Artifacts Generated table:</action>
-
-```
-| tech-spec.md | Complete | {output_folder}/tech-spec.md | {{date}} |
-| story-{slug}.md | Draft | {dev_story_location}/story-{slug}.md | {{date}} |
-```
-
-<action>Update "Next Action Required":</action>
-
-```
-**What to do next:** Review drafted story-{slug}.md, then mark it ready for development
-
-**Command to run:** Load SM agent and run 'story-ready' workflow (confirms story-{slug}.md is ready)
-
-**Agent to load:** bmad/bmm/agents/sm.md
-```
-
-<action>Add to Decision Log:</action>
-
-```
-- **{{date}}**: Level 0 tech-spec and story generation completed. Skipping Phase 3 (solutioning) - moving directly to Phase 4 (implementation). Single story (story-{slug}.md) drafted and ready for review.
-```
-
-<action>Save bmm-workflow-status.md</action>
+<output>Story queue initialized with single story: {slug}</output>
 
 </step>
 

src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md

@@ -194,93 +194,23 @@ Epic: Icon Reliability
 
 </step>
 
-<step n="6" goal="Update bmm-workflow-status and populate backlog for Phase 4">
+<step n="6" goal="Update status and populate story backlog">
 
-<action>Open {output_folder}/bmm-workflow-status.md</action>
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: update</param>
+  <param>action: complete_workflow</param>
+  <param>workflow_name: tech-spec</param>
+  <param>populate_stories_from: {epics_output_file}</param>
+</invoke-workflow>
 
-<action>Update "Workflow Status Tracker" section:</action>
+<check if="success == true">
+  <output>✅ Status updated! Loaded {{total_stories}} stories from epics.</output>
+  <output>Next: {{next_workflow}} ({{next_agent}} agent)</output>
+</check>
 
-- Set current_phase = "4-Implementation" (Level 1 skips Phase 3)
-- Set current_workflow = "tech-spec (Level 1 - epic and stories generation complete, ready for implementation)"
-- Check "2-Plan" checkbox in Phase Completion Status
-- Set progress_percentage = 40% (planning complete, skipping solutioning)
-
-<action>Populate story backlog in "### Implementation Progress (Phase 4 Only)" section:</action>
-
-#### BACKLOG (Not Yet Drafted)
-
-**Ordered story sequence - populated at Phase 4 start:**
-
-| Epic | Story | ID  | Title | File |
-| ---- | ----- | --- | ----- | ---- |
-
-{{#if story_2}}
-| 1 | 2 | {epic_slug}-2 | {{story_2_title}} | story-{epic_slug}-2.md |
-{{/if}}
-{{#if story_3}}
-| 1 | 3 | {epic_slug}-3 | {{story_3_title}} | story-{epic_slug}-3.md |
-{{/if}}
-
-**Total in backlog:** {{story_count - 1}} stories
-
-**NOTE:** Level 1 uses slug-based IDs like "{epic_slug}-1", "{epic_slug}-2" instead of numeric "1.1", "1.2"
-
-#### TODO (Needs Drafting)
-
-Initialize with FIRST story (already drafted):
-
-- **Story ID:** {epic_slug}-1
-- **Story Title:** {{story_1_title}}
-- **Story File:** `story-{epic_slug}-1.md`
-- **Status:** Draft (needs review before development)
-- **Action:** User reviews drafted story, then runs SM agent `story-ready` workflow to approve
-
-#### IN PROGRESS (Approved for Development)
-
-Leave empty initially:
-
-(Story will be moved here by SM agent `story-ready` workflow after user approves story-{epic_slug}-1.md)
-
-#### DONE (Completed Stories)
-
-Initialize empty table:
-
-| Story ID   | File | Completed Date | Points |
-| ---------- | ---- | -------------- | ------ |
-| (none yet) |      |                |        |
-
-**Total completed:** 0 stories
-**Total points completed:** 0 points
-
-<action>Add to Artifacts Generated table:</action>
-
-```
-| tech-spec.md | Complete | {output_folder}/tech-spec.md | {{date}} |
-| epics.md | Complete | {output_folder}/epics.md | {{date}} |
-| story-{epic_slug}-1.md | Draft | {dev_story_location}/story-{epic_slug}-1.md | {{date}} |
-| story-{epic_slug}-2.md | Draft | {dev_story_location}/story-{epic_slug}-2.md | {{date}} |
-{{#if story_3}}
-| story-{epic_slug}-3.md | Draft | {dev_story_location}/story-{epic_slug}-3.md | {{date}} |
-{{/if}}
-```
-
-<action>Update "Next Action Required":</action>
-
-```
-**What to do next:** Review drafted story-{epic_slug}-1.md, then mark it ready for development
-
-**Command to run:** Load SM agent and run 'story-ready' workflow (confirms story-{epic_slug}-1.md is ready)
-
-**Agent to load:** bmad/bmm/agents/sm.md
-```
-
-<action>Add to Decision Log:</action>
-
-```
-- **{{date}}**: Level 1 tech-spec and epic/stories generation completed. {{story_count}} stories created. Skipping Phase 3 (solutioning) - moving directly to Phase 4 (implementation). Story backlog populated. First story (story-{epic_slug}-1.md) drafted and ready for review.
-```
-
-<action>Save bmm-workflow-status.md</action>
+<check if="success == false">
+  <output>⚠️ Status update failed: {{error}}</output>
+</check>
 
 </step>
 

src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md

@@ -4,80 +4,99 @@
 
 <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}</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 is the SMALL instruction set for Level 0-1 projects - tech-spec with story generation</critical>
 <critical>Level 0: tech-spec + single user story | Level 1: tech-spec + epic/stories</critical>
 <critical>Project analysis already completed - proceeding directly to technical specification</critical>
 <critical>NO PRD generated - uses tech_spec_template + story templates</critical>
 
-<step n="0" goal="Check for workflow status file - REQUIRED">
+<critical>DOCUMENT OUTPUT: Technical, precise, definitive. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
 
-<action>Check if bmm-workflow-status.md exists in {output_folder}/</action>
+<step n="0" goal="Validate workflow and extract project configuration">
 
-<check if="not exists">
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: data</param>
+  <param>data_request: project_config</param>
+</invoke-workflow>
+
+<check if="status_exists == false">
   <output>**⚠️ No Workflow Status File Found**
 
-The tech-spec workflow requires an existing workflow status file to understand your project context.
+The tech-spec workflow requires a status file to understand your project context.
 
-Please run `workflow-status` first to:
+Please run `workflow-init` first to:
 
-- Map out your complete workflow journey
-- Determine project type and level
-- Create the status file with your planned workflow
+- Define your project type and level
+- Map out your workflow journey
+- Create the status file
 
-**To proceed:**
+Run: `workflow-init`
 
-Run: `bmad analyst workflow-status`
-
-After completing workflow planning, you'll be directed back to this workflow.
+After setup, return here to create your tech spec.
 </output>
 <action>Exit workflow - cannot proceed without status file</action>
 </check>
 
-<check if="exists">
-  <action>Load status file and proceed to Step 1</action>
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for later updates</action>
+
+  <check if="project_level >= 2">
+    <output>**Incorrect Workflow for Level {{project_level}}**
+
+Tech-spec is for Level 0-1 projects. Level 2-4 should use PRD workflow.
+
+**Correct workflow:** `prd` (PM agent)
+</output>
+<action>Exit and redirect to prd</action>
 </check>
 
+  <check if="project_type == game">
+    <output>**Incorrect Workflow for Game Projects**
+
+Game projects should use GDD workflow instead of tech-spec.
+
+**Correct workflow:** `gdd` (PM agent)
+</output>
+<action>Exit and redirect to gdd</action>
+</check>
+</check>
+</step>
+
+<step n="0.5" goal="Validate workflow sequencing">
+
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <param>mode: validate</param>
+  <param>calling_workflow: tech-spec</param>
+</invoke-workflow>
+
+<check if="warning != ''">
+  <output>{{warning}}</output>
+  <ask>Continue with tech-spec anyway? (y/n)</ask>
+  <check if="n">
+    <output>{{suggestion}}</output>
+    <action>Exit workflow</action>
+  </check>
+</check>
 </step>
 
 <step n="1" goal="Confirm project scope and update tracking">
 
-<action>Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md</action>
-<action>Verify project_level is 0 or 1</action>
+<action>Use {{project_level}} from status data</action>
 
-<check if="project_level >= 2">
-  <error>This workflow is for Level 0-1 only. Level 2-4 should use PRD workflow.</error>
-  <output>**Incorrect Workflow for Your Level**
-
-Your status file indicates Level {{project_level}}.
-
-**Correct workflow:** `prd` (run with PM agent)
-
-Run: `bmad pm prd`
-</output>
-<action>Exit and redirect user to prd workflow</action>
-</check>
-
-<check if="project_type == game">
-  <error>This workflow is for software projects. Game projects should use GDD workflow.</error>
-  <output>**Incorrect Workflow for Game Projects**
-
-**Correct workflow:** `gdd` (run with PM agent)
-
-Run: `bmad pm gdd`
-</output>
-<action>Exit and redirect user to gdd workflow</action>
-</check>
-
-<action>Update Workflow Status Tracker:</action>
+<action>Update Workflow Status:</action>
+<template-output file="{{status_file_path}}">current_workflow</template-output>
 <check if="project_level == 0">
-<action>Set current_workflow = "tech-spec (Level 0 - generating tech spec)"</action>
+<action>Set to: "tech-spec (Level 0 - generating tech spec)"</action>
 </check>
 <check if="project_level == 1">
-<action>Set current_workflow = "tech-spec (Level 1 - generating tech spec)"</action>
+<action>Set to: "tech-spec (Level 1 - generating tech spec)"</action>
 </check>
-<action>Set progress_percentage = 20%</action>
-<action>Save bmm-workflow-status.md</action>
+
+<template-output file="{{status_file_path}}">progress_percentage</template-output>
+<action>Set to: 20%</action>
+
+<action>Save {{status_file_path}}</action>
 
 <check if="project_level == 0">
   <action>Confirm Level 0 - Single atomic change</action>
@@ -96,9 +115,10 @@ Run: `bmad pm gdd`
 <critical>Generate tech-spec.md - this is the TECHNICAL SOURCE OF TRUTH</critical>
 <critical>ALL TECHNICAL DECISIONS MUST BE DEFINITIVE - NO AMBIGUITY ALLOWED</critical>
 
-<action>Update progress in bmm-workflow-status.md:</action>
-<action>Set progress_percentage = 40%</action>
-<action>Save bmm-workflow-status.md</action>
+<action>Update progress:</action>
+<template-output file="{{status_file_path}}">progress_percentage</template-output>
+<action>Set to: 40%</action>
+<action>Save {{status_file_path}}</action>
 
 <action>Initialize and write out tech-spec.md using tech_spec_template</action>
 
@@ -164,7 +184,7 @@ Run cohesion validation? (y/n)</ask>
 
 <step n="4" goal="Generate user stories based on project level">
 
-<action>Load bmm-workflow-status.md to determine project_level</action>
+<action>Use {{project_level}} from status data</action>
 
 <check if="project_level == 0">
   <action>Invoke instructions-level0-story.md to generate single user story</action>

src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml

@@ -9,6 +9,8 @@ project_name: "{config_source}:project_name"
 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

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

@@ -4,11 +4,31 @@
 
 <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}</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>
@@ -367,4 +387,19 @@ 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/workflow.yaml

@@ -8,6 +8,8 @@ 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

src/modules/bmm/workflows/3-solutioning/README.md

@@ -11,12 +11,12 @@ This workflow generates comprehensive, scale-adaptive solution architecture docu
 **Unique Features:**
 
 - ✅ **Scale-adaptive**: Level 0 = skip, Levels 1-4 = progressive depth
-- ✅ **Pattern-aware**: 171 technology combinations across 12 project types
-- ✅ **Template-driven**: 11 complete architecture document templates
-- ✅ **Engine-specific guidance**: Unity, Godot, Phaser, and more
+- ✅ **Intent-based**: LLM intelligence over prescriptive lists
+- ✅ **Template-driven**: 11 adaptive architecture document templates
+- ✅ **Game-aware**: Adapts heavily based on game type (RPG, Puzzle, Shooter, etc.)
 - ✅ **GDD/PRD aware**: Uses Game Design Doc for games, PRD for everything else
 - ✅ **ADR tracking**: Separate Architecture Decision Records document
-- ✅ **Specialist integration**: Pattern-specific specialist recommendations
+- ✅ **Simplified structure**: ~11 core project types with consistent naming
 
 ---
 
@@ -71,38 +71,37 @@ workflow solution-architecture
 
 ## Project Types and Templates
 
-### 12 Project Types Supported
+### Simplified Project Type System
 
-| Type          | Examples                     | Template                          | Guide Examples       |
-| ------------- | ---------------------------- | --------------------------------- | -------------------- |
-| **web**       | Next.js, Rails, Django       | web-fullstack-architecture.md     | (TBD)                |
-| **mobile**    | React Native, Flutter, Swift | mobile-app-architecture.md        | (TBD)                |
-| **game**      | Unity, Godot, Phaser         | game-engine-architecture.md       | Unity, Godot, Phaser |
-| **embedded**  | ESP32, STM32, Raspberry Pi   | embedded-firmware-architecture.md | (TBD)                |
-| **backend**   | Express, FastAPI, gRPC       | backend-service-architecture.md   | (TBD)                |
-| **data**      | Spark, Airflow, MLflow       | data-pipeline-architecture.md     | (TBD)                |
-| **cli**       | Commander, Click, Cobra      | cli-tool-architecture.md          | (TBD)                |
-| **desktop**   | Electron, Tauri, Qt          | desktop-app-architecture.md       | (TBD)                |
-| **library**   | npm, PyPI, cargo             | library-package-architecture.md   | (TBD)                |
-| **infra**     | Terraform, K8s Operator      | infrastructure-architecture.md    | (TBD)                |
-| **extension** | Chrome, VS Code plugins      | desktop-app-architecture.md       | (TBD)                |
+The workflow uses ~11 core project types that cover 99% of software projects:
 
-### 171 Technology Combinations
+| Type               | Name                     | Template                   | Instructions                   |
+| ------------------ | ------------------------ | -------------------------- | ------------------------------ |
+| **web**            | Web Application          | web-template.md            | web-instructions.md            |
+| **mobile**         | Mobile Application       | mobile-template.md         | mobile-instructions.md         |
+| **game**           | Game Development         | game-template.md           | game-instructions.md           |
+| **backend**        | Backend Service          | backend-template.md        | backend-instructions.md        |
+| **data**           | Data Pipeline            | data-template.md           | data-instructions.md           |
+| **cli**            | CLI Tool                 | cli-template.md            | cli-instructions.md            |
+| **library**        | Library/SDK              | library-template.md        | library-instructions.md        |
+| **desktop**        | Desktop Application      | desktop-template.md        | desktop-instructions.md        |
+| **embedded**       | Embedded System          | embedded-template.md       | embedded-instructions.md       |
+| **extension**      | Browser/Editor Extension | extension-template.md      | extension-instructions.md      |
+| **infrastructure** | Infrastructure           | infrastructure-template.md | infrastructure-instructions.md |
 
-The workflow maintains a registry (`templates/registry.csv`) with 171 pre-defined technology stack combinations:
+### Intent-Based Architecture
 
-**Examples:**
+Instead of maintaining 171 prescriptive technology combinations, the workflow now:
 
-- `web-nextjs-ssr-monorepo` → Next.js SSR, TypeScript, monorepo
-- `game-unity-3d` → Unity 3D, C#, monorepo
-- `mobile-react-native` → React Native, TypeScript, cross-platform
-- `backend-fastapi-rest` → FastAPI, Python, REST API
-- `data-ml-training` → PyTorch/TensorFlow, Python, ML pipeline
+- **Leverages LLM intelligence** to understand project requirements
+- **Adapts templates dynamically** based on actual needs
+- **Uses intent-based instructions** rather than prescriptive checklists
+- **Allows for emerging technologies** without constant updates
 
-Each row maps to:
+Each project type has:
 
-- **template_path**: Architecture document structure (11 templates)
-- **guide_path**: Engine/framework-specific guidance (optional)
+- **Instruction file**: Intent-based guidance for architecture decisions
+- **Template file**: Adaptive starting point for the architecture document
 
 ---
 
@@ -155,63 +154,56 @@ Analyze PRD epics:
 - Map domain capabilities
 - Determine service boundaries (if microservices)
 
-### Step 5: Project-Type Questions
+### Step 5: Intent-Based Technical Decisions
 
-Load: `project-types/{project_type}-questions.md`
+Load: `project-types/{project_type}-instructions.md`
 
-- Ask project-type-specific questions (not yet engine-specific)
+- Use intent-based guidance, not prescriptive lists
+- Allow LLM intelligence to identify relevant decisions
+- Consider emerging technologies naturally
 
-### Step 6: Load Template + Guide
+### Step 6: Adaptive Template Selection
 
-**6.1: Search Registry**
+**6.1: Simple Template Selection**
 
 ```
-Read: templates/registry.csv
-Match WHERE:
-  - project_types = {determined_type}
-  - languages = {preferred_languages}
-  - architecture_style = {determined_style}
-  - tags overlap with {requirements}
-
-Get: template_path, guide_path
+Based on project_type from analysis:
+  web → web-template.md
+  mobile → mobile-template.md
+  game → game-template.md (adapts heavily by game type)
+  backend → backend-template.md
+  ... (consistent naming pattern)
 ```
 
 **6.2: Load Template**
 
 ```
-Read: templates/{template_path}
-Example: templates/game-engine-architecture.md
+Read: project-types/{type}-template.md
+Example: project-types/game-template.md
 
-This is a COMPLETE document structure with:
+Templates are adaptive starting points:
 - Standard sections (exec summary, tech stack, data arch, etc.)
-- Pattern-specific sections (Gameplay Systems for games, SSR Strategy for web)
-- All {{placeholders}} to fill
+- Pattern-specific sections conditionally included
+- All {{placeholders}} to fill based on requirements
 ```
 
-**6.3: Load Guide (if available)**
+**6.3: Dynamic Adaptation**
 
-```
-IF guide_path not empty:
-  Read: templates/{guide_path}
-  Example: templates/game-engine-unity-guide.md
+Templates adapt based on:
 
-Guide contains:
-- Engine/framework-specific questions
-- Architecture patterns for this tech
-- Common pitfalls
-- Specialist recommendations
-- ADR templates
-```
+- Actual project requirements from PRD/GDD
+- User skill level (beginner/intermediate/expert)
+- Specific technology choices made
+- Game type for game projects (RPG, Puzzle, Shooter, etc.)
 
-**Example Flow for Unity Game:**
+**Example Flow for Unity RPG:**
 
-1. GDD says "Unity 2022 LTS"
-2. Registry match: `game-unity-3d` → `game-engine-architecture.md` + `game-engine-unity-guide.md`
-3. Load complete game architecture template
-4. Load Unity-specific guide
-5. Ask Unity-specific questions (MonoBehaviour vs ECS, ScriptableObjects, etc.)
-6. Fill template placeholders
-7. Generate `solution-architecture.md` + `architecture-decisions.md`
+1. GDD says "Unity 2022 LTS" and "RPG"
+2. Load game-template.md and game-instructions.md
+3. Template adapts to include RPG-specific sections (inventory, quests, dialogue)
+4. Instructions guide Unity-specific decisions (MonoBehaviour vs ECS, etc.)
+5. LLM intelligence fills gaps not in any list
+6. Generate optimized `solution-architecture.md` + `architecture-decisions.md`
 
 ### Step 7: Cohesion Check
 
@@ -234,28 +226,30 @@ Validate architecture quality:
 ├── instructions.md                  # Main workflow logic
 ├── checklist.md                     # Validation checklist
 ├── ADR-template.md                  # ADR document template
-├── templates/                       # Architecture templates and guides
-│   ├── registry.csv                 # 171 tech combinations → templates
-│   ├── game-engine-architecture.md  # Complete game architecture doc
-│   ├── game-engine-unity-guide.md   # Unity-specific guidance
-│   ├── game-engine-godot-guide.md   # Godot-specific guidance
-│   ├── game-engine-web-guide.md     # Phaser/PixiJS/Three.js guidance
-│   ├── web-fullstack-architecture.md
-│   ├── web-api-architecture.md
-│   ├── mobile-app-architecture.md
-│   ├── embedded-firmware-architecture.md
-│   ├── backend-service-architecture.md
-│   ├── data-pipeline-architecture.md
-│   ├── cli-tool-architecture.md
-│   ├── desktop-app-architecture.md
-│   ├── library-package-architecture.md
-│   └── infrastructure-architecture.md
-└── project-types/                   # Project type detection and questions
-    ├── project-types.csv            # 12 project types + detection keywords
-    ├── game-questions.md
-    ├── web-questions.md
-    ├── mobile-questions.md
-    └── ... (12 question files)
+└── project-types/                   # All project type files in one folder
+    ├── project-types.csv            # Simple 2-column mapping (type, name)
+    ├── web-instructions.md          # Intent-based guidance for web projects
+    ├── web-template.md              # Adaptive web architecture template
+    ├── mobile-instructions.md       # Intent-based guidance for mobile
+    ├── mobile-template.md           # Adaptive mobile architecture template
+    ├── game-instructions.md         # Intent-based guidance (adapts by game type)
+    ├── game-template.md             # Highly adaptive game architecture template
+    ├── backend-instructions.md      # Intent-based guidance for backend services
+    ├── backend-template.md          # Adaptive backend architecture template
+    ├── data-instructions.md         # Intent-based guidance for data pipelines
+    ├── data-template.md             # Adaptive data pipeline template
+    ├── cli-instructions.md          # Intent-based guidance for CLI tools
+    ├── cli-template.md              # Adaptive CLI architecture template
+    ├── library-instructions.md      # Intent-based guidance for libraries/SDKs
+    ├── library-template.md          # Adaptive library architecture template
+    ├── desktop-instructions.md      # Intent-based guidance for desktop apps
+    ├── desktop-template.md          # Adaptive desktop architecture template
+    ├── embedded-instructions.md     # Intent-based guidance for embedded systems
+    ├── embedded-template.md         # Adaptive embedded architecture template
+    ├── extension-instructions.md    # Intent-based guidance for extensions
+    ├── extension-template.md        # Adaptive extension architecture template
+    ├── infrastructure-instructions.md  # Intent-based guidance for infra
+    └── infrastructure-template.md   # Adaptive infrastructure template
 ```
 
 ---
@@ -313,60 +307,6 @@ Each template in `templates/` is a **complete** architecture document structure:
 
 ---
 
-## Guide System
-
-### Engine/Framework-Specific Guides
-
-Guides are **workflow instruction documents** that:
-
-- Ask engine-specific questions
-- Provide architecture pattern recommendations
-- Suggest what sections to emphasize
-- Define ADRs to create
-
-**Guides are NOT:**
-
-- ❌ Reference documentation (use official docs)
-- ❌ Tutorials (how to code)
-- ❌ API references
-
-**Guides ARE:**
-
-- ✅ Question flows for architecture decisions
-- ✅ Pattern recommendations specific to the tech
-- ✅ Common pitfalls to avoid
-- ✅ Specialist recommendations
-
-**Example: game-engine-unity-guide.md**
-
-```markdown
-## Unity Architecture Questions
-
-- MonoBehaviour or ECS?
-- ScriptableObjects for game data?
-- Addressables or Resources?
-
-## Unity Patterns
-
-- Singleton GameManager (when to use)
-- Event-driven communication
-- Object pooling strategy
-
-## Unity-Specific Sections to Include
-
-- Unity Project Configuration
-- Scene Architecture
-- Component Organization
-- Package Dependencies
-
-## Common Pitfalls
-
-- Caching GetComponent calls
-- Avoiding empty Update methods
-```
-
----
-
 ## ADR Tracking
 
 Architecture Decision Records are maintained separately in `architecture-decisions.md`.
@@ -531,25 +471,20 @@ Specialists are documented with:
 
 ## Extending the System
 
-### Adding a New Template
-
-1. Create `templates/new-pattern-architecture.md`
-2. Include all standard sections + pattern-specific sections
-3. Add rows to `templates/registry.csv` pointing to new template
-
-### Adding a New Guide
-
-1. Create `templates/new-tech-guide.md`
-2. Include: questions, patterns, pitfalls, specialist recommendations
-3. Update `templates/registry.csv` with `guide_path` column
-
 ### Adding a New Project Type
 
-1. Add row to `project-types/project-types.csv`
-2. Create `project-types/new-type-questions.md`
-3. Ensure templates exist for this type
+1. Add row to `project-types/project-types.csv` (just type and name)
+2. Create `project-types/{type}-instructions.md` with intent-based guidance
+3. Create `project-types/{type}-template.md` with adaptive template
 4. Update instructions.md if special handling needed (like GDD for games)
 
+### Key Principles
+
+- **Intent over prescription**: Guide decisions, don't list every option
+- **Leverage LLM intelligence**: Trust the model to know technologies
+- **Adaptive templates**: Templates should adapt to project needs
+- **Consistent naming**: Always use {type}-instructions.md and {type}-template.md
+
 ---
 
 ## Questions?
@@ -557,8 +492,8 @@ Specialists are documented with:
 - **Validation:** See `checklist.md`
 - **Workflow Logic:** See `instructions.md`
 - **Configuration:** See `workflow.yaml`
-- **Registry Format:** See `templates/registry.csv`
-- **Example Guide:** See `templates/game-engine-unity-guide.md`
+- **Project Types:** See `project-types/project-types.csv`
+- **Example Template:** See `project-types/game-template.md`
 
 ---
 

src/modules/bmm/workflows/3-solutioning/implementation-ready-check/README.md

@@ -0,0 +1,170 @@
+# Implementation Ready Check Workflow
+
+## Overview
+
+The Implementation Ready Check workflow provides a systematic validation of all planning and solutioning artifacts before transitioning from Phase 3 (Solutioning) to Phase 4 (Implementation) in the BMad Method. This workflow ensures that PRDs, architecture documents, and story breakdowns are properly aligned with no critical gaps or contradictions.
+
+## Purpose
+
+This workflow is designed to:
+
+- **Validate Completeness**: Ensure all required planning documents exist and are complete
+- **Verify Alignment**: Check that PRD, architecture, and stories are cohesive and aligned
+- **Identify Gaps**: Detect missing stories, unaddressed requirements, or sequencing issues
+- **Assess Risks**: Find contradictions, conflicts, or potential implementation blockers
+- **Provide Confidence**: Give teams confidence that planning is solid before starting development
+
+## When to Use
+
+This workflow should be invoked:
+
+- At the end of Phase 3 (Solutioning) for Level 2-4 projects
+- Before beginning Phase 4 (Implementation)
+- After significant planning updates or architectural changes
+- When validating readiness for Level 0-1 projects (simplified validation)
+
+## Project Level Adaptations
+
+The workflow adapts its validation based on project level:
+
+### Level 0-1 Projects
+
+- Validates tech spec and simple stories only
+- Checks internal consistency and basic coverage
+- Lighter validation appropriate for simple projects
+
+### Level 2 Projects
+
+- Validates PRD, tech spec (with embedded architecture), and stories
+- Ensures PRD requirements are fully covered
+- Verifies technical approach aligns with business goals
+
+### Level 3-4 Projects
+
+- Full validation of PRD, solution architecture, and comprehensive stories
+- Deep cross-reference checking across all artifacts
+- Validates architectural decisions don't introduce scope creep
+- Checks UX artifacts if applicable
+
+## How to Invoke
+
+### Via Scrum Master Agent
+
+```
+*assess-project-ready
+```
+
+### Direct Workflow Invocation
+
+```
+workflow implementation-ready-check
+```
+
+## Expected Inputs
+
+The workflow will automatically search your project's output folder for:
+
+- Product Requirements Documents (PRD)
+- Solution Architecture documents
+- Technical Specifications
+- Epic and Story breakdowns
+- UX artifacts (if applicable)
+
+No manual input file specification needed - the workflow discovers documents automatically.
+
+## Generated Output
+
+The workflow produces a comprehensive **Implementation Readiness Report** containing:
+
+1. **Executive Summary** - Overall readiness status
+2. **Document Inventory** - What was found and reviewed
+3. **Alignment Validation** - Cross-reference analysis results
+4. **Gap Analysis** - Missing items and risks identified
+5. **Findings by Severity** - Critical, High, Medium, Low issues
+6. **Recommendations** - Specific actions to address issues
+7. **Readiness Decision** - Ready, Ready with Conditions, or Not Ready
+
+Output Location: `{output_folder}/implementation-readiness-report-{date}.md`
+
+## Workflow Steps
+
+1. **Initialize** - Get current workflow status and project level
+2. **Document Discovery** - Find all planning artifacts
+3. **Deep Analysis** - Extract requirements, decisions, and stories
+4. **Cross-Reference Validation** - Check alignment between all documents
+5. **Gap and Risk Analysis** - Identify issues and conflicts
+6. **UX Validation** (optional) - Verify UX concerns are addressed
+7. **Generate Report** - Compile comprehensive readiness assessment
+8. **Status Update** (optional) - Offer to advance workflow to next phase
+
+## Validation Criteria
+
+The workflow uses systematic validation rules adapted to each project level:
+
+- **Document completeness and quality**
+- **Requirement to story traceability**
+- **Architecture to implementation alignment**
+- **Story sequencing and dependencies**
+- **Greenfield project setup coverage**
+- **Risk identification and mitigation**
+
+## Special Features
+
+### Intelligent Adaptation
+
+- Automatically adjusts validation based on project level
+- Recognizes when UX workflow is active
+- Handles greenfield vs. brownfield projects differently
+
+### Comprehensive Coverage
+
+- Validates not just presence but quality and alignment
+- Checks for both gaps and gold-plating
+- Ensures logical story sequencing
+
+### Actionable Output
+
+- Provides specific, actionable recommendations
+- Categorizes issues by severity
+- Includes positive findings and commendations
+
+## Integration with BMad Method
+
+This workflow integrates seamlessly with the BMad Method workflow system:
+
+- Uses workflow-status to understand project context
+- Can update workflow status to advance to next phase
+- Follows standard BMad document naming conventions
+- Searches standard output folders automatically
+
+## Troubleshooting
+
+### Documents Not Found
+
+- Ensure documents are in the configured output folder
+- Check that document names follow BMad conventions
+- Verify workflow-status is properly configured
+
+### Validation Too Strict
+
+- The workflow adapts to project level automatically
+- Level 0-1 projects get lighter validation
+- Consider if your project level is set correctly
+
+### Report Too Long
+
+- Focus on Critical and High priority issues first
+- Use the executive summary for quick decisions
+- Review detailed findings only for areas of concern
+
+## Support
+
+For issues or questions about this workflow:
+
+- Consult the BMad Method documentation
+- Check the SM agent for workflow guidance
+- Review validation-criteria.yaml for detailed rules
+
+---
+
+_This workflow is part of the BMad Method v6-alpha suite of planning and solutioning tools_

src/modules/bmm/workflows/3-solutioning/implementation-ready-check/checklist.md

@@ -0,0 +1,171 @@
+# Implementation Readiness Validation Checklist
+
+## Document Completeness
+
+### Core Planning Documents
+
+- [ ] PRD exists and is complete (Level 2-4 projects)
+- [ ] PRD contains measurable success criteria
+- [ ] PRD defines clear scope boundaries and exclusions
+- [ ] Solution Architecture document exists (Level 3-4 projects)
+- [ ] Technical Specification exists with implementation details
+- [ ] Epic and story breakdown document exists
+- [ ] All documents are dated and versioned
+
+### Document Quality
+
+- [ ] No placeholder sections remain in any document
+- [ ] All documents use consistent terminology
+- [ ] Technical decisions include rationale and trade-offs
+- [ ] Assumptions and risks are explicitly documented
+- [ ] Dependencies are clearly identified and documented
+
+## Alignment Verification
+
+### PRD to Architecture Alignment (Level 3-4)
+
+- [ ] Every functional requirement in PRD has architectural support documented
+- [ ] All non-functional requirements from PRD are addressed in architecture
+- [ ] Architecture doesn't introduce features beyond PRD scope
+- [ ] Performance requirements from PRD match architecture capabilities
+- [ ] Security requirements from PRD are fully addressed in architecture
+
+### PRD to Stories Coverage (Level 2-4)
+
+- [ ] Every PRD requirement maps to at least one story
+- [ ] All user journeys in PRD have complete story coverage
+- [ ] Story acceptance criteria align with PRD success criteria
+- [ ] Priority levels in stories match PRD feature priorities
+- [ ] No stories exist without PRD requirement traceability
+
+### Architecture to Stories Implementation
+
+- [ ] All architectural components have implementation stories
+- [ ] Infrastructure setup stories exist for each architectural layer
+- [ ] Integration points defined in architecture have corresponding stories
+- [ ] Data migration/setup stories exist if required by architecture
+- [ ] Security implementation stories cover all architecture security decisions
+
+## Story and Sequencing Quality
+
+### Story Completeness
+
+- [ ] All stories have clear acceptance criteria
+- [ ] Technical tasks are defined within relevant stories
+- [ ] Stories include error handling and edge cases
+- [ ] Each story has clear definition of done
+- [ ] Stories are appropriately sized (no epic-level stories remaining)
+
+### Sequencing and Dependencies
+
+- [ ] Stories are sequenced in logical implementation order
+- [ ] Dependencies between stories are explicitly documented
+- [ ] No circular dependencies exist
+- [ ] Prerequisite technical tasks precede dependent stories
+- [ ] Foundation/infrastructure stories come before feature stories
+
+### Greenfield Project Specifics
+
+- [ ] Initial project setup and configuration stories exist
+- [ ] Development environment setup is documented
+- [ ] CI/CD pipeline stories are included early in sequence
+- [ ] Database/storage initialization stories are properly placed
+- [ ] Authentication/authorization stories precede protected features
+
+## Risk and Gap Assessment
+
+### Critical Gaps
+
+- [ ] No core PRD requirements lack story coverage
+- [ ] No architectural decisions lack implementation stories
+- [ ] All integration points have implementation plans
+- [ ] Error handling strategy is defined and implemented
+- [ ] Security concerns are all addressed
+
+### Technical Risks
+
+- [ ] No conflicting technical approaches between stories
+- [ ] Technology choices are consistent across all documents
+- [ ] Performance requirements are achievable with chosen architecture
+- [ ] Scalability concerns are addressed if applicable
+- [ ] Third-party dependencies are identified with fallback plans
+
+## UX and Special Concerns (if applicable)
+
+### UX Coverage
+
+- [ ] UX requirements are documented in PRD
+- [ ] UX implementation tasks exist in relevant stories
+- [ ] Accessibility requirements have story coverage
+- [ ] Responsive design requirements are addressed
+- [ ] User flow continuity is maintained across stories
+
+### Special Considerations
+
+- [ ] Compliance requirements are fully addressed
+- [ ] Internationalization needs are covered if required
+- [ ] Performance benchmarks are defined and measurable
+- [ ] Monitoring and observability stories exist
+- [ ] Documentation stories are included where needed
+
+## Overall Readiness
+
+### Ready to Proceed Criteria
+
+- [ ] All critical issues have been resolved
+- [ ] High priority concerns have mitigation plans
+- [ ] Story sequencing supports iterative delivery
+- [ ] Team has necessary skills for implementation
+- [ ] No blocking dependencies remain unresolved
+
+### Quality Indicators
+
+- [ ] Documents demonstrate thorough analysis
+- [ ] Clear traceability exists across all artifacts
+- [ ] Consistent level of detail throughout documents
+- [ ] Risks are identified with mitigation strategies
+- [ ] Success criteria are measurable and achievable
+
+## Assessment Completion
+
+### Report Quality
+
+- [ ] All findings are supported by specific examples
+- [ ] Recommendations are actionable and specific
+- [ ] Severity levels are appropriately assigned
+- [ ] Positive findings are highlighted
+- [ ] Next steps are clearly defined
+
+### Process Validation
+
+- [ ] All expected documents were reviewed
+- [ ] Cross-references were systematically checked
+- [ ] Project level considerations were applied correctly
+- [ ] Workflow status was checked and considered
+- [ ] Output folder was thoroughly searched for artifacts
+
+---
+
+## Issue Log
+
+### Critical Issues Found
+
+- [ ] ***
+- [ ] ***
+- [ ] ***
+
+### High Priority Issues Found
+
+- [ ] ***
+- [ ] ***
+- [ ] ***
+
+### Medium Priority Issues Found
+
+- [ ] ***
+- [ ] ***
+- [ ] ***
+
+---
+
+_Use this checklist to ensure comprehensive validation of implementation readiness_

src/modules/bmm/workflows/3-solutioning/implementation-ready-check/instructions.md

@@ -0,0 +1,262 @@
+# Implementation Ready Check - Workflow Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/3-solutioning/implementation-ready-check/workflow.yaml</critical>
+<critical>Communicate all findings and analysis in {communication_language} throughout the assessment</critical>
+
+<workflow>
+
+<step n="0" goal="Initialize and understand project context">
+<invoke-workflow path="{workflow_status_workflow}">
+  <param>mode: data</param>
+  <param>data_request: project_config</param>
+</invoke-workflow>
+
+<check if="status_exists == false">
+  <output>**⚠️ No Workflow Status File Found**
+
+The Implementation Ready Check requires a status file to understand your project context.
+
+Please run `workflow-init` first to establish your project configuration.
+
+After setup, return here to validate implementation readiness.
+</output>
+<action>Exit workflow - cannot proceed without status file</action>
+</check>
+
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for later updates</action>
+  <action>Store {{project_level}}, {{active_path}}, and {{workflow_phase}} for validation context</action>
+
+<action>Based on the project_level, understand what artifacts should exist:
+
+- Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning)
+- Level 2: PRD, tech spec, epics/stories (no separate architecture doc)
+- Level 3-4: Full suite - PRD, solution architecture, epics/stories, possible UX artifacts
+  </action>
+
+<critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
+</check>
+
+<template-output>project_context</template-output>
+</step>
+
+<step n="1" goal="Discover and inventory project artifacts">
+<action>Search the {output_folder} for relevant planning and solutioning documents based on project level identified in Step 0</action>
+
+<action>For Level 0-1 projects, locate:
+
+- Technical specification document(s)
+- Story/task lists or simple epic breakdowns
+- Any API or interface definitions
+  </action>
+
+<action>For Level 2-4 projects, locate:
+
+- Product Requirements Document (PRD)
+- Solution Architecture document (Level 3-4 only)
+- Technical Specification (Level 2 includes architecture within)
+- Epic and story breakdowns
+- UX artifacts if the active path includes UX workflow
+- Any supplementary planning documents
+  </action>
+
+<action>Create an inventory of found documents with:
+
+- Document type and purpose
+- File path and last modified date
+- Brief description of what each contains
+- Any missing expected documents flagged as potential issues
+  </action>
+
+<template-output>document_inventory</template-output>
+</step>
+
+<step n="2" goal="Deep analysis of core planning documents">
+<action>Load and thoroughly analyze each discovered document to extract:
+- Core requirements and success criteria
+- Architectural decisions and constraints
+- Technical implementation approaches
+- User stories and acceptance criteria
+- Dependencies and sequencing requirements
+- Any assumptions or risks documented
+</action>
+
+<action>For PRD analysis (Level 2-4), focus on:
+
+- User requirements and use cases
+- Functional and non-functional requirements
+- Success metrics and acceptance criteria
+- Scope boundaries and explicitly excluded items
+- Priority levels for different features
+  </action>
+
+<action>For Architecture/Tech Spec analysis, focus on:
+
+- System design decisions and rationale
+- Technology stack and framework choices
+- Integration points and APIs
+- Data models and storage decisions
+- Security and performance considerations
+- Any architectural constraints that might affect story implementation
+  </action>
+
+<action>For Epic/Story analysis, focus on:
+
+- Coverage of PRD requirements
+- Story sequencing and dependencies
+- Acceptance criteria completeness
+- Technical tasks within stories
+- Estimated complexity and effort indicators
+  </action>
+
+<template-output>document_analysis</template-output>
+</step>
+
+<step n="3" goal="Cross-reference validation and alignment check">
+<action>Systematically validate alignment between all artifacts, adapting validation based on project level</action>
+
+<action>PRD ↔ Architecture Alignment (Level 3-4):
+
+- Verify every PRD requirement has corresponding architectural support
+- Check that architecture decisions don't contradict PRD constraints
+- Identify any architecture additions beyond PRD scope (potential gold-plating)
+- Ensure non-functional requirements from PRD are addressed in architecture
+  </action>
+
+<action>PRD ↔ Stories Coverage (Level 2-4):
+
+- Map each PRD requirement to implementing stories
+- Identify any PRD requirements without story coverage
+- Find stories that don't trace back to PRD requirements
+- Validate that story acceptance criteria align with PRD success criteria
+  </action>
+
+<action>Architecture ↔ Stories Implementation Check:
+
+- Verify architectural decisions are reflected in relevant stories
+- Check that story technical tasks align with architectural approach
+- Identify any stories that might violate architectural constraints
+- Ensure infrastructure and setup stories exist for architectural components
+  </action>
+
+<action>For Level 0-1 projects (Tech Spec only):
+
+- Validate internal consistency within tech spec
+- Check that all specified features have corresponding stories
+- Verify story sequencing matches technical dependencies
+  </action>
+
+<template-output>alignment_validation</template-output>
+</step>
+
+<step n="4" goal="Gap and risk analysis">
+<action>Identify and categorize all gaps, risks, and potential issues discovered during validation</action>
+
+<action>Check for Critical Gaps:
+
+- Missing stories for core requirements
+- Unaddressed architectural concerns
+- Absent infrastructure or setup stories for greenfield projects
+- Missing error handling or edge case coverage
+- Security or compliance requirements not addressed
+  </action>
+
+<action>Identify Sequencing Issues:
+
+- Dependencies not properly ordered
+- Stories that assume components not yet built
+- Parallel work that should be sequential
+- Missing prerequisite technical tasks
+  </action>
+
+<action>Detect Potential Contradictions:
+
+- Conflicts between PRD and architecture approaches
+- Stories with conflicting technical approaches
+- Acceptance criteria that contradict requirements
+- Resource or technology conflicts
+  </action>
+
+<action>Find Gold-Plating and Scope Creep:
+
+- Features in architecture not required by PRD
+- Stories implementing beyond requirements
+- Technical complexity beyond project needs
+- Over-engineering indicators
+  </action>
+
+<template-output>gap_risk_analysis</template-output>
+</step>
+
+<step n="5" goal="UX and special concerns validation" optional="true">
+<check if="UX artifacts exist or UX workflow in active path">
+<action>Review UX artifacts and validate integration:
+- Check that UX requirements are reflected in PRD
+- Verify stories include UX implementation tasks
+- Ensure architecture supports UX requirements (performance, responsiveness)
+- Identify any UX concerns not addressed in stories
+</action>
+
+<action>Validate accessibility and usability coverage:
+
+- Check for accessibility requirement coverage in stories
+- Verify responsive design considerations if applicable
+- Ensure user flow completeness across stories
+  </action>
+  </check>
+
+<template-output>ux_validation</template-output>
+</step>
+
+<step n="6" goal="Generate comprehensive readiness assessment">
+<action>Compile all findings into a structured readiness report with:
+- Executive summary of readiness status
+- Project context and validation scope
+- Document inventory and coverage assessment
+- Detailed findings organized by severity (Critical, High, Medium, Low)
+- Specific recommendations for each issue
+- Overall readiness recommendation (Ready, Ready with Conditions, Not Ready)
+</action>
+
+<action>Provide actionable next steps:
+
+- List any critical issues that must be resolved
+- Suggest specific document updates needed
+- Recommend additional stories or tasks required
+- Propose sequencing adjustments if needed
+  </action>
+
+<action>Include positive findings:
+
+- Highlight well-aligned areas
+- Note particularly thorough documentation
+- Recognize good architectural decisions
+- Commend comprehensive story coverage where found
+  </action>
+
+<template-output>readiness_assessment</template-output>
+</step>
+
+<step n="7" goal="Workflow status update offer" optional="true">
+<ask>The readiness assessment is complete. Would you like to update the workflow status to proceed to the next phase? [yes/no]
+
+Note: This will advance the project workflow to the next phase in your current path.</ask>
+
+<action if="user_response == 'yes'">
+Determine the next workflow phase based on current status:
+- If Level 0-1: Advance to implementation phase
+- If Level 2-4 in solutioning: Advance to Phase 4 (Implementation)
+- Update the workflow status configuration accordingly
+- Confirm the update with the user
+</action>
+
+<action if="user_response == 'no'">
+Acknowledge that the workflow status remains unchanged.
+Remind user they can manually update when ready.
+</action>
+
+<template-output>status_update_result</template-output>
+</step>
+
+</workflow>

src/modules/bmm/workflows/3-solutioning/implementation-ready-check/template.md

@@ -0,0 +1,146 @@
+# Implementation Readiness Assessment Report
+
+**Date:** {{date}}
+**Project:** {{project_name}}
+**Assessed By:** {{user_name}}
+**Assessment Type:** Phase 3 to Phase 4 Transition Validation
+
+---
+
+## Executive Summary
+
+{{readiness_assessment}}
+
+---
+
+## Project Context
+
+{{project_context}}
+
+---
+
+## Document Inventory
+
+### Documents Reviewed
+
+{{document_inventory}}
+
+### Document Analysis Summary
+
+{{document_analysis}}
+
+---
+
+## Alignment Validation Results
+
+### Cross-Reference Analysis
+
+{{alignment_validation}}
+
+---
+
+## Gap and Risk Analysis
+
+### Critical Findings
+
+{{gap_risk_analysis}}
+
+---
+
+## UX and Special Concerns
+
+{{ux_validation}}
+
+---
+
+## Detailed Findings
+
+### 🔴 Critical Issues
+
+_Must be resolved before proceeding to implementation_
+
+{{critical_issues}}
+
+### 🟠 High Priority Concerns
+
+_Should be addressed to reduce implementation risk_
+
+{{high_priority_concerns}}
+
+### 🟡 Medium Priority Observations
+
+_Consider addressing for smoother implementation_
+
+{{medium_priority_observations}}
+
+### 🟢 Low Priority Notes
+
+_Minor items for consideration_
+
+{{low_priority_notes}}
+
+---
+
+## Positive Findings
+
+### ✅ Well-Executed Areas
+
+{{positive_findings}}
+
+---
+
+## Recommendations
+
+### Immediate Actions Required
+
+{{immediate_actions}}
+
+### Suggested Improvements
+
+{{suggested_improvements}}
+
+### Sequencing Adjustments
+
+{{sequencing_adjustments}}
+
+---
+
+## Readiness Decision
+
+### Overall Assessment: {{overall_readiness_status}}
+
+{{readiness_rationale}}
+
+### Conditions for Proceeding (if applicable)
+
+{{conditions_for_proceeding}}
+
+---
+
+## Next Steps
+
+{{recommended_next_steps}}
+
+### Workflow Status Update
+
+{{status_update_result}}
+
+---
+
+## Appendices
+
+### A. Validation Criteria Applied
+
+{{validation_criteria_used}}
+
+### B. Traceability Matrix
+
+{{traceability_matrix}}
+
+### C. Risk Mitigation Strategies
+
+{{risk_mitigation_strategies}}
+
+---
+
+_This readiness assessment was generated using the BMad Method Implementation Ready Check workflow (v6-alpha)_

src/modules/bmm/workflows/3-solutioning/implementation-ready-check/validation-criteria.yaml

@@ -0,0 +1,184 @@
+# Implementation Readiness Validation Criteria
+# Defines systematic validation rules by project level
+
+validation_rules:
+  # Level 0-1 Projects (Simple, minimal planning)
+  level_0_1:
+    required_documents:
+      - tech_spec
+      - stories_or_tasks
+
+    validations:
+      - name: "Tech Spec Completeness"
+        checks:
+          - "All features defined with implementation approach"
+          - "Technical dependencies identified"
+          - "API contracts defined if applicable"
+          - "Data models specified"
+
+      - name: "Story Coverage"
+        checks:
+          - "All tech spec features have corresponding stories"
+          - "Stories are sequenced logically"
+          - "Technical tasks are defined"
+          - "No critical gaps in coverage"
+
+  # Level 2 Projects (PRD + Tech Spec, no separate architecture)
+  level_2:
+    required_documents:
+      - prd
+      - tech_spec # Includes architecture decisions
+      - epics_and_stories
+
+    validations:
+      - name: "PRD to Tech Spec Alignment"
+        checks:
+          - "All PRD requirements addressed in tech spec"
+          - "Architecture embedded in tech spec covers PRD needs"
+          - "Non-functional requirements are specified"
+          - "Technical approach supports business goals"
+
+      - name: "Story Coverage and Alignment"
+        checks:
+          - "Every PRD requirement has story coverage"
+          - "Stories align with tech spec approach"
+          - "Epic breakdown is complete"
+          - "Acceptance criteria match PRD success criteria"
+
+      - name: "Sequencing Validation"
+        checks:
+          - "Foundation stories come first"
+          - "Dependencies are properly ordered"
+          - "Iterative delivery is possible"
+          - "No circular dependencies"
+
+  # Level 3-4 Projects (Full planning with separate architecture)
+  level_3_4:
+    required_documents:
+      - prd
+      - solution_architecture
+      - epics_and_stories
+      - tech_spec # Optional at Level 4
+
+    validations:
+      - name: "PRD Completeness"
+        checks:
+          - "User requirements fully documented"
+          - "Success criteria are measurable"
+          - "Scope boundaries clearly defined"
+          - "Priorities are assigned"
+
+      - name: "Architecture Coverage"
+        checks:
+          - "All PRD requirements have architectural support"
+          - "System design is complete"
+          - "Integration points defined"
+          - "Security architecture specified"
+          - "Performance considerations addressed"
+
+      - name: "PRD-Architecture Alignment"
+        checks:
+          - "No architecture gold-plating beyond PRD"
+          - "NFRs from PRD reflected in architecture"
+          - "Technology choices support requirements"
+          - "Scalability matches expected growth"
+
+      - name: "Story Implementation Coverage"
+        checks:
+          - "All architectural components have stories"
+          - "Infrastructure setup stories exist"
+          - "Integration implementation planned"
+          - "Security implementation stories present"
+
+      - name: "Comprehensive Sequencing"
+        checks:
+          - "Infrastructure before features"
+          - "Authentication before protected resources"
+          - "Core features before enhancements"
+          - "Dependencies properly ordered"
+          - "Allows for iterative releases"
+
+# Special validation contexts
+special_contexts:
+  greenfield:
+    additional_checks:
+      - "Project initialization stories exist"
+      - "Development environment setup documented"
+      - "CI/CD pipeline stories included"
+      - "Initial data/schema setup planned"
+      - "Deployment infrastructure stories present"
+
+  ux_workflow_active:
+    additional_checks:
+      - "UX requirements in PRD"
+      - "UX implementation stories exist"
+      - "Accessibility requirements covered"
+      - "Responsive design addressed"
+      - "User flow continuity maintained"
+
+  api_heavy:
+    additional_checks:
+      - "API contracts fully defined"
+      - "Versioning strategy documented"
+      - "Authentication/authorization specified"
+      - "Rate limiting considered"
+      - "API documentation stories included"
+
+# Severity definitions
+severity_levels:
+  critical:
+    description: "Must be resolved before implementation"
+    examples:
+      - "Missing stories for core requirements"
+      - "Conflicting technical approaches"
+      - "No infrastructure setup for greenfield"
+      - "Security requirements not addressed"
+
+  high:
+    description: "Should be addressed to reduce risk"
+    examples:
+      - "Incomplete acceptance criteria"
+      - "Unclear story dependencies"
+      - "Missing error handling coverage"
+      - "Performance requirements not validated"
+
+  medium:
+    description: "Consider addressing for smoother implementation"
+    examples:
+      - "Documentation gaps"
+      - "Test strategy not defined"
+      - "Monitoring approach unclear"
+      - "Minor sequencing improvements possible"
+
+  low:
+    description: "Minor improvements for consideration"
+    examples:
+      - "Formatting inconsistencies"
+      - "Optional enhancements identified"
+      - "Style guide compliance"
+      - "Nice-to-have features noted"
+
+# Readiness decision criteria
+readiness_decisions:
+  ready:
+    criteria:
+      - "No critical issues found"
+      - "All required documents present"
+      - "Core alignments validated"
+      - "Story sequencing logical"
+      - "Team can begin implementation"
+
+  ready_with_conditions:
+    criteria:
+      - "Only high/medium issues found"
+      - "Mitigation plans identified"
+      - "Core path to MVP clear"
+      - "Issues won't block initial stories"
+
+  not_ready:
+    criteria:
+      - "Critical issues identified"
+      - "Major gaps in coverage"
+      - "Conflicting approaches found"
+      - "Required documents missing"
+      - "Blocking dependencies unresolved"

src/modules/bmm/workflows/3-solutioning/implementation-ready-check/workflow.yaml

@@ -0,0 +1,36 @@
+# Implementation Ready Check - Workflow Configuration
+name: implementation-ready-check
+description: "Systematically validate that all planning and solutioning phases are complete and properly aligned before transitioning to Phase 4 implementation. Ensures PRD, architecture, and stories are cohesive with no gaps or contradictions."
+author: "BMad Builder"
+
+# 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"
+date: system-generated
+
+# Workflow status integration
+workflow_status_workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
+workflow_paths_dir: "{project-root}/bmad/bmm/workflows/workflow-status/paths"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/implementation-ready-check"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration
+default_output_file: "{output_folder}/implementation-readiness-report-{{date}}.md"
+
+# Expected input documents (varies by project level)
+recommended_inputs:
+  - prd: "{output_folder}/prd*.md"
+  - architecture: "{output_folder}/solution-architecture*.md"
+  - tech_spec: "{output_folder}/tech-spec*.md"
+  - epics_stories: "{output_folder}/epic*.md"
+  - ux_artifacts: "{output_folder}/ux*.md"
+
+# Validation criteria data
+validation_criteria: "{installed_path}/validation-criteria.yaml"

src/modules/bmm/workflows/3-solutioning/project-types/backend-instructions.md

@@ -0,0 +1,170 @@
+# Backend/API Service Architecture Instructions
+
+## Intent-Based Technical Decision Guidance
+
+<critical>
+This is a STARTING POINT for backend/API architecture decisions.
+The LLM should:
+- Analyze the PRD to understand data flows, performance needs, and integrations
+- Guide decisions based on scale, team size, and operational complexity
+- Focus only on relevant architectural areas
+- Make intelligent recommendations that align with project requirements
+- Keep explanations concise and decision-focused
+</critical>
+
+## Service Architecture Pattern
+
+**Determine the Right Architecture**
+Based on the requirements, guide toward the appropriate pattern:
+
+- **Monolith**: For most projects starting out, single deployment, simple operations
+- **Microservices**: Only when there's clear domain separation, large teams, or specific scaling needs
+- **Serverless**: For event-driven workloads, variable traffic, or minimal operations
+- **Modular Monolith**: Best of both worlds for growing projects
+
+Don't default to microservices - most projects benefit from starting simple.
+
+## Language and Framework Selection
+
+**Choose Based on Context**
+Consider these factors intelligently:
+
+- Team expertise (use what the team knows unless there's a compelling reason)
+- Performance requirements (Go/Rust for high performance, Python/Node for rapid development)
+- Ecosystem needs (Python for ML/data, Node for full-stack JS, Java for enterprise)
+- Hiring pool and long-term maintenance
+
+For beginners: Suggest mainstream options with good documentation.
+For experts: Let them specify preferences, discuss specific trade-offs only if asked.
+
+## API Design Philosophy
+
+**Match API Style to Client Needs**
+
+- REST: Default for public APIs, simple CRUD, wide compatibility
+- GraphQL: Multiple clients with different data needs, complex relationships
+- gRPC: Service-to-service communication, high performance binary protocols
+- WebSocket/SSE: Real-time requirements
+
+Don't ask about API paradigm if it's obvious from requirements (e.g., real-time chat needs WebSocket).
+
+## Data Architecture
+
+**Database Decisions Based on Data Characteristics**
+Analyze the data requirements to suggest:
+
+- **Relational** (PostgreSQL/MySQL): Structured data, ACID requirements, complex queries
+- **Document** (MongoDB): Flexible schemas, hierarchical data, rapid prototyping
+- **Key-Value** (Redis/DynamoDB): Caching, sessions, simple lookups
+- **Time-series**: IoT, metrics, event data
+- **Graph**: Social networks, recommendation engines
+
+Consider polyglot persistence only for clear, distinct use cases.
+
+**Data Access Layer**
+
+- ORMs for developer productivity and type safety
+- Query builders for flexibility with some safety
+- Raw SQL only when performance is critical
+
+Match to team expertise and project complexity.
+
+## Security and Authentication
+
+**Security Appropriate to Risk**
+
+- Internal tools: Simple API keys might suffice
+- B2C applications: Managed auth services (Auth0, Firebase Auth)
+- B2B/Enterprise: SAML, SSO, advanced RBAC
+- Financial/Healthcare: Compliance-driven requirements
+
+Don't over-engineer security for prototypes, don't under-engineer for production.
+
+## Messaging and Events
+
+**Only If Required by the Architecture**
+Determine if async processing is actually needed:
+
+- Message queues for decoupling, reliability, buffering
+- Event streaming for event sourcing, real-time analytics
+- Pub/sub for fan-out scenarios
+
+Skip this entirely for simple request-response APIs.
+
+## Operational Considerations
+
+**Observability Based on Criticality**
+
+- Development: Basic logging might suffice
+- Production: Structured logging, metrics, tracing
+- Mission-critical: Full observability stack
+
+**Scaling Strategy**
+
+- Start with vertical scaling (simpler)
+- Plan for horizontal scaling if needed
+- Consider auto-scaling for variable loads
+
+## Performance Requirements
+
+**Right-Size Performance Decisions**
+
+- Don't optimize prematurely
+- Identify actual bottlenecks from requirements
+- Consider caching strategically, not everywhere
+- Database optimization before adding complexity
+
+## Integration Patterns
+
+**External Service Integration**
+Based on the PRD's integration requirements:
+
+- Circuit breakers for resilience
+- Rate limiting for API consumption
+- Webhook patterns for event reception
+- SDK vs. API direct calls
+
+## Deployment Strategy
+
+**Match Deployment to Team Capability**
+
+- Small teams: Managed platforms (Heroku, Railway, Fly.io)
+- DevOps teams: Kubernetes, cloud-native
+- Enterprise: Consider existing infrastructure
+
+**CI/CD Complexity**
+
+- Start simple: Platform auto-deploy
+- Add complexity as needed: testing stages, approvals, rollback
+
+## Adaptive Guidance Examples
+
+**For a REST API serving a mobile app:**
+Focus on response times, offline support, versioning, and push notifications.
+
+**For a data processing pipeline:**
+Emphasize batch vs. stream processing, data validation, error handling, and monitoring.
+
+**For a microservices migration:**
+Discuss service boundaries, data consistency, service discovery, and distributed tracing.
+
+**For an enterprise integration:**
+Focus on security, compliance, audit logging, and existing system compatibility.
+
+## Key Principles
+
+1. **Start simple, evolve as needed** - Don't build for imaginary scale
+2. **Use boring technology** - Proven solutions over cutting edge
+3. **Optimize for your constraint** - Development speed, performance, or operations
+4. **Make reversible decisions** - Avoid early lock-in
+5. **Document the "why"** - But keep it brief
+
+## Output Format
+
+Structure decisions as:
+
+- **Choice**: [Specific technology with version]
+- **Rationale**: [One sentence why this fits the requirements]
+- **Trade-off**: [What we're optimizing for vs. what we're accepting]
+
+Keep technical decisions definitive and version-specific for LLM consumption.