diff --git a/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md b/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md
index cc63df69..03b64282 100644
--- a/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md
+++ b/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md
@@ -5,33 +5,36 @@
-
- Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
- Find the most recent file (by date in filename: bmm-workflow-status.md)
+
+
+ mode: validate
+ calling_workflow: brainstorm-game
+
-
- Load the status file
- Set status_file_found = true
- Store status_file_path for later updates
+
+
+
+ Set standalone_mode = true
-
- **No workflow status file found.**
+
+ Store {{status_file_path}} for later updates
-This workflow generates brainstorming ideas for game ideation (optional Phase 1 workflow).
+
+
+ Continue with game brainstorming anyway? (y/n)
+
+ Exit 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?
-If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to brainstorm-game"
-If user chooses option 2 → Set standalone_mode = true and continue
-If user chooses option 3 → HALT
-
-
+
Read the game context document from: {game_context}
@@ -63,15 +66,9 @@ What would you like to do?
-
- Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
- Find the most recent file (by date in filename)
-
-
- Load the status file
-
- current_step
- Set to: "brainstorm-game"
+
+
+ Load {{status_file_path}}
current_workflow
Set to: "brainstorm-game - Complete"
@@ -80,21 +77,25 @@ What would you like to do?
Increment by: 5% (optional Phase 1 workflow)
decisions_log
- Add entry:
- ```
- - **{{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.
- ```
+ Add entry: "- **{{date}}**: Completed brainstorm-game workflow. Generated game brainstorming session results. Next: Review game ideas and consider research or game-brief workflows."
-
+
+
-
-
-
-
-
-
+
diff --git a/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md b/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md
index 8d8fb6d8..07f9e6d1 100644
--- a/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md
+++ b/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md
@@ -1,6 +1,6 @@
# Brainstorm Project - Workflow Instructions
-````xml
+```xml
The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml
You MUST have already loaded and processed: {installed_path}/workflow.yaml
Communicate all responses in {communication_language}
@@ -8,30 +8,25 @@
-
- Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
- Find the most recent file (by date in filename: bmm-workflow-status.md)
+
+
+ mode: validate
+ calling_workflow: brainstorm-project
+
-
- Load the status file
- Set status_file_found = true
- Store status_file_path for later updates
+
+
+
+ Set standalone_mode = true
-
- **No workflow status file found.**
+
+ Store {{status_file_path}} for later updates
-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?
- If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to brainstorm-project"
- If user chooses option 2 → Set standalone_mode = true and continue
- If user chooses option 3 → HALT
+
+
+
+
@@ -56,15 +51,9 @@ What would you like to do?
-
- Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
- Find the most recent file (by date in filename)
-
-
- Load the status file
-
- current_step
- Set to: "brainstorm-project"
+
+
+ Load {{status_file_path}}
current_workflow
Set to: "brainstorm-project - Complete"
@@ -73,19 +62,20 @@ What would you like to do?
Increment by: 5% (optional Phase 1 workflow)
decisions_log
- Add entry:
- ```
- - **{{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.
- ```
+ Add entry: "- **{{date}}**: Completed brainstorm-project workflow. Generated brainstorming session results. Next: Review ideas and consider research or product-brief workflows."
-
+
+
-
-
-
-
-
+{{/if}}
+
-````
+```
diff --git a/src/modules/bmm/workflows/1-analysis/document-project/instructions.md b/src/modules/bmm/workflows/1-analysis/document-project/instructions.md
index 29640929..70777b36 100644
--- a/src/modules/bmm/workflows/1-analysis/document-project/instructions.md
+++ b/src/modules/bmm/workflows/1-analysis/document-project/instructions.md
@@ -8,85 +8,47 @@
This router determines workflow mode and delegates to specialized sub-workflows
-
+
-Search {output_folder}/ for files matching pattern: bmm-workflow-status\*.md
-Find the most recent file (by date in filename: bmm-workflow-status.md)
+
+ mode: data
+ data_request: project_config
+
-
- Load the status file
- Extract key information:
-
-- 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
-
-Validate this workflow is in the planned workflow
-Set status_file_path = file path
-Set status_file_found = true
-
-
- **⚠️ 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):
-
-
-
-Exit workflow
-
-
+
+
+
+ Set standalone_mode = true
+ Set status_file_found = false
-
- **ℹ️ No Workflow Status File Found**
+
+ Store {{status_file_path}} for later updates
+ Set status_file_found = true
-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):
-
-
-
-Exit workflow
-
-
-
- Set status_file_found = false
- Set standalone_mode = true
- Continue without status file integration
+
+
+
+ Continue anyway to document planning artifacts? (y/n)
+
+ Exit workflow
+
-
- Exit workflow
+
+
+ mode: validate
+ calling_workflow: document-project
+
+
+
+
+
+ Continue with documentation? (y/n)
+
+
+ Exit workflow
+
@@ -214,34 +176,22 @@ Your choice [1/2/3]:
-
+
- Load the status file from {{status_file_path}}
-
-planned_workflow
-Find "document-project" in the planned_workflow table
-Update Status field from "Planned" or "In Progress" to "Complete"
-
-current_step
-Set to: "document-project"
-
-next_step
-Find next item with Status != "Complete" in planned_workflow table
-Set to: "{{next_workflow_step}} ({{next_workflow_agent}} agent)"
-
-progress_percentage
-Increment by: 10%
+ Load {{status_file_path}}
current_workflow
Set to: "document-project - Complete"
-decisions_log
-Add entry:
+progress_percentage
+Increment by: 10%
-```
-- **{{date}}**: Completed document-project workflow ({{workflow_mode}} mode, {{scan_level}} scan). Generated brownfield documentation in {output_folder}/. Next: {{next_step}}.
-```
+decisions_log
+Add entry: "- **{{date}}**: Completed document-project workflow ({{workflow_mode}} mode). Generated documentation in {output_folder}/."
+
+Save {{status_file_path}}
+
-
-
-
-
-
diff --git a/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md b/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md
index 40fddd08..d321ffa2 100644
--- a/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md
+++ b/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md
@@ -6,31 +6,33 @@
-
-Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
-Find the most recent file (by date in filename: bmm-workflow-status.md)
+
+
+ mode: validate
+ calling_workflow: game-brief
+
-
- Load the status file
- Set status_file_found = true
- Store status_file_path for later updates
+
+
+
+ Set standalone_mode = true
-
- **No workflow status file found.**
+
+ Store {{status_file_path}} for later updates
-This workflow creates a Game Brief document (optional Phase 1 workflow).
+
+
+ Continue with game brief anyway? (y/n)
+
+ Exit 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?
-If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to game-brief"
-If user chooses option 2 → Set standalone_mode = true and continue
-If user chooses option 3 → HALT
+
+
+
+
@@ -303,15 +305,9 @@ This brief will serve as the primary input for creating the Game Design Document
executive_brief
-
-Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
-Find the most recent file (by date in filename)
-
-
- Load the status file
-
-current_step
-Set to: "game-brief"
+
+
+ Load {{status_file_path}}
current_workflow
Set to: "game-brief - Complete"
@@ -320,22 +316,25 @@ This brief will serve as the primary input for creating the Game Design Document
Increment by: 10% (optional Phase 1 workflow)
decisions_log
-Add entry:
+Add entry: "- **{{date}}**: Completed game-brief workflow. Game brief document generated. Next: Proceed to plan-project workflow to create Game Design Document (GDD)."
-```
-- **{{date}}**: Completed game-brief workflow. Game brief document generated and saved. Next: Proceed to plan-project workflow to create Game Design Document (GDD).
-```
+Save {{status_file_path}}
+
-
-
-
-
-
-
+
diff --git a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md
index 7ded6269..6851833f 100644
--- a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md
+++ b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md
@@ -6,31 +6,34 @@
-
-Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
-Find the most recent file (by date in filename: bmm-workflow-status.md)
+
+
+ mode: validate
+ calling_workflow: product-brief
+
-
- Load the status file
- Set status_file_found = true
- Store status_file_path for later updates
+
+
+
+ Set standalone_mode = true
-
- **No workflow status file found.**
+
+ Store {{status_file_path}} for later updates
-This workflow creates a Product Brief document (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?
-If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to product-brief"
-If user chooses option 2 → Set standalone_mode = true and continue
-If user chooses option 3 → HALT
+
+
+ Continue with Product Brief anyway? (y/n)
+
+
+ Exit workflow
+
+
@@ -267,14 +270,8 @@ This brief will serve as the primary input for creating the Product Requirements
-Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
-Find the most recent file (by date in filename)
-
-
- Load the status file
-
-current_step
-Set to: "product-brief"
+
+ Load {{status_file_path}}
current_workflow
Set to: "product-brief - Complete"
@@ -283,22 +280,25 @@ This brief will serve as the primary input for creating the Product Requirements
Increment by: 10% (optional Phase 1 workflow)
decisions_log
-Add entry:
+Add entry: "- **{{date}}**: Completed product-brief workflow. Product brief document generated and saved. Next: Proceed to plan-project workflow to create Product Requirements Document (PRD)."
-```
-- **{{date}}**: Completed product-brief workflow. Product brief document generated and saved. Next: Proceed to plan-project workflow to create Product Requirements Document (PRD).
-```
+Save {{status_file_path}}
+
-
-
-
-
-
-
+
diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-router.md b/src/modules/bmm/workflows/1-analysis/research/instructions-router.md
index 46560ad0..427d698d 100644
--- a/src/modules/bmm/workflows/1-analysis/research/instructions-router.md
+++ b/src/modules/bmm/workflows/1-analysis/research/instructions-router.md
@@ -10,31 +10,26 @@
This is a ROUTER that directs to specialized research instruction sets
-
-Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
-Find the most recent file (by date in filename: bmm-workflow-status.md)
+
+
+ mode: validate
+ calling_workflow: research
+
-
- Load the status file
- Set status_file_found = true
- Store status_file_path for later updates
+
+
+
+ Set standalone_mode = true
-
- **No workflow status file found.**
+
+ Store {{status_file_path}} for status updates in sub-workflows
+ Pass status_file_path to loaded instruction set
-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?
-If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to research"
-If user chooses option 2 → Set standalone_mode = true and continue
-If user chooses option 3 → HALT
+
+
+
+
diff --git a/src/modules/bmm/workflows/1-analysis/workflow-status/INTEGRATION-EXAMPLE.md b/src/modules/bmm/workflows/1-analysis/workflow-status/INTEGRATION-EXAMPLE.md
new file mode 100644
index 00000000..4799eb08
--- /dev/null
+++ b/src/modules/bmm/workflows/1-analysis/workflow-status/INTEGRATION-EXAMPLE.md
@@ -0,0 +1,177 @@
+# Workflow Status Service - Integration Examples
+
+## How Other Workflows Can Use the Enhanced workflow-status Service
+
+### Example 1: Simple Validation (product-brief workflow)
+
+Replace the old Step 0:
+
+```xml
+
+
+Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
+Find the most recent file...
+
+
+```
+
+With the new service call:
+
+```xml
+
+
+
+ mode: validate
+ calling_workflow: product-brief
+
+
+
+
+
+
+
+
+
+ Continue anyway? (y/n)
+
+ Exit workflow
+
+
+
+Store {{status_file_path}} for later updates if needed
+
+```
+
+### Example 2: Getting Story Data (create-story workflow)
+
+Replace the complex Step 2.5:
+
+```xml
+
+
+Read {output_folder}/bmm-workflow-status.md (if exists)
+Navigate to "### Implementation Progress (Phase 4 Only)" section
+Find "#### TODO (Needs Drafting)" section
+
+
+```
+
+With the new service call:
+
+```xml
+
+
+
+ mode: data
+ data_request: next_story
+
+
+
+ Fall back to legacy story discovery
+
+
+
+ Use {{todo_story_id}} as story to draft
+ Use {{todo_story_title}} for validation
+ Create file: {{todo_story_file}}
+
+
+
+```
+
+### Example 3: Getting Project Configuration (solution-architecture workflow)
+
+```xml
+
+
+ mode: data
+ data_request: project_config
+
+
+
+ No status file. Run standalone or create status first?
+
+
+
+ Use {{project_level}} to determine architecture complexity
+ Use {{project_type}} to select appropriate templates
+ Use {{field_type}} to know if brownfield constraints apply
+
+
+```
+
+### Example 4: Quick Init Check (any workflow)
+
+```xml
+
+
+ mode: init-check
+
+
+
+
+
+
+
+```
+
+## Benefits of This Approach
+
+1. **DRY Principle**: No more duplicating status check logic across 50+ workflows
+2. **Centralized Logic**: Bug fixes and improvements happen in one place
+3. **Backward Compatible**: Old workflows continue to work, can migrate gradually
+4. **Advisory Not Blocking**: Workflows can proceed even without status file
+5. **Flexible Data Access**: Get just what you need (next_story, project_config, etc.)
+6. **Cleaner Workflows**: Focus on core logic, not status management
+
+## Available Modes
+
+### `validate` Mode
+
+- **Purpose**: Check if this workflow should run
+- **Returns**:
+ - `status_exists`: true/false
+ - `should_proceed`: true (always - advisory only)
+ - `warning`: Any sequence warnings
+ - `suggestion`: What to do
+ - `project_level`, `project_type`, `field_type`: For workflow decisions
+ - `status_file_path`: For later updates
+
+### `data` Mode
+
+- **Purpose**: Extract specific information
+- **Parameters**: `data_request` = one of:
+ - `next_story`: Get TODO story details
+ - `project_config`: Get project configuration
+ - `phase_status`: Get phase completion status
+ - `all`: Get everything
+- **Returns**: Requested fields as template outputs
+
+### `init-check` Mode
+
+- **Purpose**: Simple existence check
+- **Returns**:
+ - `status_exists`: true/false
+ - `suggestion`: Brief message
+
+### `interactive` Mode (default)
+
+- **Purpose**: User-facing status check
+- **Shows**: Current status, options menu
+- **Returns**: User proceeds with selected action
+
+## Migration Strategy
+
+1. Start with high-value workflows that have complex Step 0s
+2. Test with a few workflows first
+3. Gradually migrate others as they're updated
+4. Old workflows continue to work unchanged
+
+## Next Steps
+
+To integrate into your workflow:
+
+1. Replace your Step 0 with appropriate service call
+2. Remove duplicate status checking logic
+3. Use returned values for workflow decisions
+4. Update status file at completion (if status_exists == true)
diff --git a/src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md b/src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md
index af09951d..02e990d7 100644
--- a/src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md
+++ b/src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md
@@ -1,11 +1,33 @@
-# Workflow Status Check
+# Workflow Status Check - Multi-Mode Service
The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml
You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml
-This is the UNIVERSAL entry point - any agent can ask "what should I do now?"
+This workflow operates in multiple modes: interactive (default), validate, data, init-check
+Other workflows can call this as a service to avoid duplicating status logic
+
+ Check for {{mode}} parameter passed by calling workflow
+ Default mode = "interactive" if not specified
+
+
+ Continue to Step 1 for normal status check flow
+
+
+
+ Jump to Step 10 for workflow validation service
+
+
+
+ Jump to Step 20 for data extraction service
+
+
+
+ Jump to Step 30 for simple init check
+
+
+
Search {output_folder}/ for file: bmm-workflow-status.md
@@ -102,4 +124,143 @@ Your choice:
Handle user selection based on available options
+
+
+
+
+
+Read {output_folder}/bmm-workflow-status.md if exists
+
+
+ status_exists = false
+ should_proceed = true
+ warning = "No status file found. Running without progress tracking."
+ suggestion = "Consider running workflow-init first for progress tracking"
+ Return to calling workflow
+
+
+
+ Parse status file fields
+ Load workflow path file from WORKFLOW_PATH field
+ Check if {{calling_workflow}} matches CURRENT_WORKFLOW or NEXT_COMMAND
+
+status_exists = true
+current_phase = {{CURRENT_PHASE}}
+current_workflow = {{CURRENT_WORKFLOW}}
+next_workflow = {{NEXT_COMMAND}}
+project_level = {{PROJECT_LEVEL}}
+project_type = {{PROJECT_TYPE}}
+field_type = {{FIELD_TYPE}}
+
+
+ should_proceed = true
+ warning = ""
+ suggestion = "Resuming {{current_workflow}}"
+
+
+
+ should_proceed = true
+ warning = ""
+ suggestion = "Proceeding with planned next step"
+
+
+
+ Check if calling_workflow is in optional workflows list
+
+
+ should_proceed = true
+ warning = "Running optional workflow {{calling_workflow}}"
+ suggestion = "This is optional. Expected next: {{next_workflow}}"
+
+
+
+ should_proceed = true
+ warning = "⚠️ Out of sequence: Expected {{next_workflow}}, running {{calling_workflow}}"
+ suggestion = "Consider running {{next_workflow}} instead, or continue if intentional"
+
+
+
+
+status_file_path = {{path to bmm-workflow-status.md}}
+
+
+Return control to calling workflow with all template outputs
+
+
+
+Read {output_folder}/bmm-workflow-status.md if exists
+
+
+ status_exists = false
+ error = "No status file to extract data from"
+ Return to calling workflow
+
+
+
+ Parse status file completely
+ status_exists = true
+
+
+ Extract from Development Queue section
+ todo_story_id = {{TODO_STORY}}
+ todo_story_title = {{TODO_TITLE}}
+ in_progress_story = {{IN_PROGRESS_STORY}}
+ stories_sequence = {{STORIES_SEQUENCE}}
+ stories_done = {{STORIES_DONE}}
+
+ Determine story file path based on ID format
+
+ todo_story_file = "story-{{N}}.{{M}}.md"
+
+
+ todo_story_file = "story-{{slug}}-{{N}}.md"
+
+
+ todo_story_file = "story-{{slug}}.md"
+
+
+
+
+
+ project_name = {{PROJECT_NAME}}
+ project_type = {{PROJECT_TYPE}}
+ project_level = {{PROJECT_LEVEL}}
+ field_type = {{FIELD_TYPE}}
+ workflow_path = {{WORKFLOW_PATH}}
+
+
+
+ current_phase = {{CURRENT_PHASE}}
+ phase_1_complete = {{PHASE_1_COMPLETE}}
+ phase_2_complete = {{PHASE_2_COMPLETE}}
+ phase_3_complete = {{PHASE_3_COMPLETE}}
+ phase_4_complete = {{PHASE_4_COMPLETE}}
+
+
+
+ Return all parsed fields as template outputs
+
+
+status_file_path = {{path to bmm-workflow-status.md}}
+
+
+Return control to calling workflow with requested data
+
+
+
+Check if {output_folder}/bmm-workflow-status.md exists
+
+
+ status_exists = true
+ suggestion = "Status file found. Ready to proceed."
+
+
+
+ status_exists = false
+ suggestion = "No status file. Run workflow-init to create one (optional for progress tracking)"
+
+
+Return immediately to calling workflow
+
+
diff --git a/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md
index 23fd5d14..f372549c 100644
--- a/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md
@@ -11,60 +11,75 @@
Routes to 3-solutioning for architecture (platform-specific decisions handled there)
If users mention technical details, append to technical_preferences with timestamp
-
+
-Check if bmm-workflow-status.md exists in {output_folder}/
+
+ mode: data
+ data_request: project_config
+
-
+
Exit workflow - cannot proceed without status file
-
- Load status file and proceed to Step 1
-
+
+ Store {{status_file_path}} for later updates
+
+
+Exit and redirect to appropriate workflow
+
+
+
+
+
+
+
+ mode: validate
+ calling_workflow: gdd
+
+
+
+
+ Continue with GDD anyway? (y/n)
+
+
+ Exit workflow
+
+
-Load bmm-workflow-status.md
-Confirm project_type == "game"
-
-
- This workflow is for game projects only. Software projects should use PRD or tech-spec workflows.
-
-Exit and redirect user to appropriate software workflow
-
+Use {{project_type}} and {{project_level}} from status data
Load existing GDD.md and check completion status
@@ -306,7 +321,30 @@ For each {{placeholder}} in the fragment, elicit and capture that information.
-
+
+
+Load {{status_file_path}}
+
+current_workflow
+Set to: "gdd - Complete"
+
+phase_2_complete
+Set to: true
+
+progress_percentage
+Increment appropriately based on level
+
+decisions_log
+Add entry: "- **{{date}}**: Completed GDD workflow. Created bmm-GDD.md and bmm-epics.md with full story breakdown."
+
+Populate STORIES_SEQUENCE from epics.md story list
+Count total stories and update story counts
+
+Save {{status_file_path}}
+
+
+
+
Check if game-type fragment contained narrative tags indicating narrative importance
diff --git a/src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md b/src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md
index 8405a45e..157c0251 100644
--- a/src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md
@@ -10,6 +10,23 @@
If users mention gameplay mechanics, note them but keep focus on narrative
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
+
+
+
+ mode: init-check
+
+
+
+ Store {{status_file_path}} for later updates
+ Set tracking_mode = true
+
+
+
+ Set tracking_mode = false
+
+
+
+
Load GDD.md from {output_folder}
@@ -522,4 +539,21 @@ Which would you like?
+
+
+
+ Load {{status_file_path}}
+
+current_workflow
+Set to: "narrative - Complete"
+
+decisions_log
+Add entry: "- **{{date}}**: Completed narrative workflow. Created bmm-narrative-design.md with detailed story and character documentation."
+
+Save {{status_file_path}}
+
+
+
+
+
diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md
index 0d122362..26d3350a 100644
--- a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md
@@ -9,66 +9,76 @@
-
+
-Check if bmm-workflow-status.md exists in {output_folder}/
+
+ mode: data
+ data_request: project_config
+
-
+
Exit workflow - cannot proceed without status file
-
- Load status file: {status_file}
- Proceed to Step 1
+
+ Store {{status_file_path}} for later updates
+
+
+
+Exit and redirect to tech-spec
+
+
+Exit and redirect to gdd
+
+
-
+
-Extract project context from status file
-Verify project_level is 2, 3, or 4
+
+ mode: validate
+ calling_workflow: prd
+
-
- This workflow is for Level 2-4 only. Level 0-1 should use tech-spec workflow.
-
-Exit and redirect user to tech-spec workflow
+
+
+ Continue with PRD anyway? (y/n)
+
+
+ Exit workflow
+
+
-
- This workflow is for software projects. Game projects should use GDD workflow.
-
-Exit and redirect user to gdd workflow
-
+
+Use {{project_level}} from status data
Check for existing PRD.md in {output_folder}
@@ -392,39 +402,53 @@ For each epic from the epic list, expand with full story details:
-
+
-Update {status_file} with completion status
+Load {{status_file_path}}
-prd_completion_update
+current_workflow
+Set to: "prd - Complete"
-**✅ PRD Workflow Complete, {user_name}!**
+phase_2_complete
+Set to: true
+
+decisions_log
+Add entry: "- **{{date}}**: Completed PRD workflow. Created PRD.md and epics.md with full story breakdown."
+
+Populate STORIES_SEQUENCE from epics.md story list
+Count total stories and update story counts
+
+Save {{status_file_path}}
+
+
diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
index 09ff1130..9d7249a0 100644
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
@@ -10,74 +10,90 @@
Project analysis already completed - proceeding directly to technical specification
NO PRD generated - uses tech_spec_template + story templates
-
+
-Check if bmm-workflow-status.md exists in {output_folder}/
+
+ mode: data
+ data_request: project_config
+
-
+
Exit workflow - cannot proceed without status file
-
- Load status file and proceed to Step 1
+
+ Store {{status_file_path}} for later updates
+
+
+
+Exit and redirect to prd
+
+
+Exit and redirect to gdd
+
+
+
+
+
+
+
+ mode: validate
+ calling_workflow: tech-spec
+
+
+
+
+ Continue with tech-spec anyway? (y/n)
+
+
+ Exit workflow
+
+
-Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md
-Verify project_level is 0 or 1
+Use {{project_level}} from status data
-
- This workflow is for Level 0-1 only. Level 2-4 should use PRD workflow.
-
-Exit and redirect user to prd workflow
-
-
-
- This workflow is for software projects. Game projects should use GDD workflow.
-
-Exit and redirect user to gdd workflow
-
-
-Update Workflow Status Tracker:
+Update Workflow Status:
+current_workflow
-Set current_workflow = "tech-spec (Level 0 - generating tech spec)"
+Set to: "tech-spec (Level 0 - generating tech spec)"
-Set current_workflow = "tech-spec (Level 1 - generating tech spec)"
+Set to: "tech-spec (Level 1 - generating tech spec)"
-Set progress_percentage = 20%
-Save bmm-workflow-status.md
+
+progress_percentage
+Set to: 20%
+
+Save {{status_file_path}}
Confirm Level 0 - Single atomic change
@@ -96,9 +112,10 @@ Run: `bmad pm gdd`
Generate tech-spec.md - this is the TECHNICAL SOURCE OF TRUTH
ALL TECHNICAL DECISIONS MUST BE DEFINITIVE - NO AMBIGUITY ALLOWED
-Update progress in bmm-workflow-status.md:
-Set progress_percentage = 40%
-Save bmm-workflow-status.md
+Update progress:
+progress_percentage
+Set to: 40%
+Save {{status_file_path}}
Initialize and write out tech-spec.md using tech_spec_template
@@ -164,7 +181,7 @@ Run cohesion validation? (y/n)
-Load bmm-workflow-status.md to determine project_level
+Use {{project_level}} from status data
Invoke instructions-level0-story.md to generate single user story
diff --git a/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md b/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md
index 78340a16..65367221 100644
--- a/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md
@@ -9,6 +9,23 @@
Uses ux-spec-template.md for structured output generation
Can optionally generate AI Frontend Prompts for tools like Vercel v0, Lovable.ai
+
+
+
+ mode: init-check
+
+
+
+ Store {{status_file_path}} for later updates
+ Set tracking_mode = true
+
+
+
+ Set tracking_mode = false
+
+
+
+
Determine workflow mode (standalone or integrated)
@@ -367,4 +384,21 @@ Select option (1-3):
+
+
+
+ Load {{status_file_path}}
+
+current_workflow
+Set to: "ux - Complete"
+
+decisions_log
+Add entry: "- **{{date}}**: Completed UX workflow. Created bmm-ux-spec.md with comprehensive UX/UI specifications."
+
+Save {{status_file_path}}
+
+
+
+
+
diff --git a/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/README.md b/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/README.md
new file mode 100644
index 00000000..b9ad0641
--- /dev/null
+++ b/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_
diff --git a/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/checklist.md b/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/checklist.md
new file mode 100644
index 00000000..24195338
--- /dev/null
+++ b/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_
diff --git a/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/instructions.md b/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/instructions.md
new file mode 100644
index 00000000..ada2fdb2
--- /dev/null
+++ b/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/instructions.md
@@ -0,0 +1,262 @@
+# Implementation Ready Check - Workflow Instructions
+
+The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml
+You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/3-solutioning/implementation-ready-check/workflow.yaml
+Communicate all findings and analysis in {communication_language} throughout the assessment
+
+
+
+
+
+ mode: data
+ data_request: project_config
+
+
+
+
+Exit workflow - cannot proceed without status file
+
+
+
+ Store {{status_file_path}} for later updates
+ Store {{project_level}}, {{active_path}}, and {{workflow_phase}} for validation context
+
+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
+
+
+The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels
+
+
+project_context
+
+
+
+Search the {output_folder} for relevant planning and solutioning documents based on project level identified in Step 0
+
+For Level 0-1 projects, locate:
+
+- Technical specification document(s)
+- Story/task lists or simple epic breakdowns
+- Any API or interface definitions
+
+
+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
+
+
+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
+
+
+document_inventory
+
+
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+document_analysis
+
+
+
+Systematically validate alignment between all artifacts, adapting validation based on project level
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+alignment_validation
+
+
+
+Identify and categorize all gaps, risks, and potential issues discovered during validation
+
+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
+
+
+Identify Sequencing Issues:
+
+- Dependencies not properly ordered
+- Stories that assume components not yet built
+- Parallel work that should be sequential
+- Missing prerequisite technical tasks
+
+
+Detect Potential Contradictions:
+
+- Conflicts between PRD and architecture approaches
+- Stories with conflicting technical approaches
+- Acceptance criteria that contradict requirements
+- Resource or technology conflicts
+
+
+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
+
+
+gap_risk_analysis
+
+
+
+
+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
+
+
+Validate accessibility and usability coverage:
+
+- Check for accessibility requirement coverage in stories
+- Verify responsive design considerations if applicable
+- Ensure user flow completeness across stories
+
+
+
+ux_validation
+
+
+
+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)
+
+
+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
+
+
+Include positive findings:
+
+- Highlight well-aligned areas
+- Note particularly thorough documentation
+- Recognize good architectural decisions
+- Commend comprehensive story coverage where found
+
+
+readiness_assessment
+
+
+
+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.
+
+
+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
+
+
+
+Acknowledge that the workflow status remains unchanged.
+Remind user they can manually update when ready.
+
+
+status_update_result
+
+
+
diff --git a/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/template.md b/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/template.md
new file mode 100644
index 00000000..17ff9de2
--- /dev/null
+++ b/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)_
diff --git a/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/validation-criteria.yaml b/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/validation-criteria.yaml
new file mode 100644
index 00000000..7bfab81f
--- /dev/null
+++ b/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"
diff --git a/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/workflow.yaml
new file mode 100644
index 00000000..50f4683d
--- /dev/null
+++ b/src/modules/bmm/workflows/3-solutioning/implementation-ready-check/workflow.yaml
@@ -0,0 +1,35 @@
+# 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"
+date: system-generated
+
+# Workflow status integration
+workflow_status_workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml"
+workflow_paths_dir: "{project-root}/bmad/bmm/workflows/1-analysis/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"
diff --git a/src/modules/bmm/workflows/3-solutioning/instructions.md b/src/modules/bmm/workflows/3-solutioning/instructions.md
index 3e79cbf6..5824377c 100644
--- a/src/modules/bmm/workflows/3-solutioning/instructions.md
+++ b/src/modules/bmm/workflows/3-solutioning/instructions.md
@@ -2,78 +2,92 @@
This workflow generates scale-adaptive solution architecture documentation that replaces the legacy HLA workflow.
-```xml
The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml
You MUST have already loaded and processed: {installed_path}/workflow.yaml
Communicate all responses in {communication_language}
-
-
-1. Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
- Find the most recent file (by date in filename: bmm-workflow-status.md)
+OUTPUT OPTIMIZATION FOR LLM CONSUMPTION:
+The architecture document will be consumed primarily by LLMs in subsequent workflows, not just humans.
+Therefore, the output MUST be:
-2. Check if status file exists:
-
- Load the status file
- Set status_file_found = true
- Store status_file_path for later updates
+- CONCISE: Every word should add value. Avoid verbose explanations.
+- STRUCTURED: Use tables, lists, and clear headers over prose
+- SCANNABLE: Key decisions in obvious places, not buried in paragraphs
+- DEFINITIVE: Specific versions and choices, no ambiguity
+- FOCUSED: Technical decisions over rationale (unless beginner level requested)
- Validate workflow sequence:
-
- **⚠️ Workflow Sequence Note**
+Adapt verbosity based on user skill level:
-Status file shows:
-- Current step: {{current_step}}
-- Expected next: {{next_step}}
+- Beginner: Include explanations, but keep them brief and clear
+- Intermediate: Focus on decisions with minimal explanation
+- Expert: Purely technical specifications, no hand-holding
-This workflow (solution-architecture) is typically run after plan-project for Level 3-4 projects.
+Remember: Future LLMs need to quickly extract architectural decisions to implement stories consistently.
+
-Options:
-1. Continue anyway (if you're resuming work)
-2. Exit and run the expected workflow: {{next_step}}
-3. Check status with workflow-status
+
-What would you like to do?
- If user chooses exit → HALT with message: "Run workflow-status to see current state"
-
-
+
+ mode: data
+ data_request: project_config
+
-
- **No workflow status file found.**
+
+
- If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to solution-architecture"
- If user chooses option 2 → Set standalone_mode = true and continue
- If user chooses option 3 → HALT
-
+- Define your project type and level
+- Map out your workflow journey
+- Create the status file
-3. Extract project configuration from status file:
- Path: {{status_file_path}}
+Run: `workflow-init`
- Extract:
- - project_level: {{0|1|2|3|4}}
- - field_type: {{greenfield|brownfield}}
- - project_type: {{web|mobile|embedded|game|library}}
- - has_user_interface: {{true|false}}
- - ui_complexity: {{none|simple|moderate|complex}}
- - ux_spec_path: /docs/ux-spec.md (if exists)
- - prd_status: {{complete|incomplete}}
+After setup, return here to run solution-architecture.
+
+Exit workflow - cannot proceed without status file
+
-4. Validate Prerequisites (BLOCKING):
+
+ Store {{status_file_path}} for later updates
+ Use extracted project configuration:
+ - project_level: {{project_level}}
+ - field_type: {{field_type}}
+ - project_type: {{project_type}}
+ - has_user_interface: {{has_user_interface}}
+ - ui_complexity: {{ui_complexity}}
+ - ux_spec_path: {{ux_spec_path}}
+ - prd_status: {{prd_status}}
- Check 1: PRD complete?
- IF prd_status != complete:
- ❌ STOP WORKFLOW
- Output: "PRD is required before solution architecture.
+
+
+
+
+
+
+ mode: validate
+ calling_workflow: solution-architecture
+
+
+
+
+ Continue with solution-architecture anyway? (y/n)
+
+
+ Exit workflow
+
+
+
+Validate Prerequisites (BLOCKING):
+
+Check 1: PRD complete?
+IF prd_status != complete:
+❌ STOP WORKFLOW
+Output: "PRD is required before solution architecture.
REQUIRED: Complete PRD with FRs, NFRs, epics, and stories.
@@ -82,10 +96,10 @@ What would you like to do?
After PRD is complete, return here to run solution-architecture workflow."
END
- Check 2: UX Spec complete (if UI project)?
- IF has_user_interface == true AND ux_spec_missing:
- ❌ STOP WORKFLOW
- Output: "UX Spec is required before solution architecture for UI projects.
+Check 2: UX Spec complete (if UI project)?
+IF has_user_interface == true AND ux_spec_missing:
+❌ STOP WORKFLOW
+Output: "UX Spec is required before solution architecture for UI projects.
REQUIRED: Complete UX specification before proceeding.
@@ -109,788 +123,333 @@ What would you like to do?
After UX spec is complete at /docs/ux-spec.md, return here to run solution-architecture workflow."
END
- Check 3: All prerequisites met?
- IF all prerequisites met:
- ✅ Prerequisites validated
- - PRD: complete
- - UX Spec: {{complete | not_applicable}}
- Proceeding with solution architecture workflow...
+Check 3: All prerequisites met?
+IF all prerequisites met:
+✅ Prerequisites validated - PRD: complete - UX Spec: {{complete | not_applicable}}
+Proceeding with solution architecture workflow...
5. Determine workflow path:
- IF project_level == 0:
- - Skip solution architecture entirely
- - Output: "Level 0 project - validate/update tech-spec.md only"
- - STOP WORKFLOW
- ELSE:
- - Proceed with full solution architecture workflow
-
-prerequisites_and_scale_assessment
+ IF project_level == 0: - Skip solution architecture entirely - Output: "Level 0 project - validate/update tech-spec.md only" - STOP WORKFLOW
+ ELSE: - Proceed with full solution architecture workflow
+
+ prerequisites_and_scale_assessment
+
+
+
+
+Load and deeply understand the requirements documents (PRD/GDD) and any UX specifications.
+
+Intelligently determine the true nature of this project by analyzing:
+
+- The primary document type (PRD for software, GDD for games)
+- Core functionality and features described
+- Technical constraints and requirements mentioned
+- User interface complexity and interaction patterns
+- Performance and scalability requirements
+- Integration needs with external services
+
+
+Extract and synthesize the essential architectural drivers:
+
+- What type of system is being built (web, mobile, game, library, etc.)
+- What are the critical quality attributes (performance, security, usability)
+- What constraints exist (technical, business, regulatory)
+- What integrations are required
+- What scale is expected
+
+
+If UX specifications exist, understand the user experience requirements and how they drive technical architecture:
+
+- Screen/page inventory and complexity
+- Navigation patterns and user flows
+- Real-time vs. static interactions
+- Accessibility and responsive design needs
+- Performance expectations from a user perspective
+
+
+Identify gaps between requirements and technical specifications:
+
+- What architectural decisions are already made vs. what needs determination
+- Misalignments between UX designs and functional requirements
+- Missing enabler requirements that will be needed for implementation
+
+
+requirements_analysis
+
-
-
-1. Determine requirements document type based on project_type:
- - IF project_type == "game":
- Primary Doc: Game Design Document (GDD)
- Path: {{gdd_path}} OR {{prd_path}}/GDD.md
- - ELSE:
- Primary Doc: Product Requirements Document (PRD)
- Path: {{prd_path}}
+
-2. Read primary requirements document:
- Read: {{determined_path}}
+Engage with the user to understand their technical context and preferences:
- Extract based on document type:
+- Gauge their experience level with the identified project type
+- Learn about any existing technical decisions or constraints
+- Understand team capabilities and preferences
+- Identify any existing infrastructure or systems to integrate with
+
- IF GDD (Game):
- - Game concept and genre
- - Core gameplay mechanics
- - Player progression systems
- - Game world/levels/scenes
- - Characters and entities
- - Win/loss conditions
- - Game modes (single-player, multiplayer, etc.)
- - Technical requirements (platform, performance targets)
- - Art/audio direction
- - Monetization (if applicable)
+Based on the conversation, determine the appropriate level of detail for the architecture document:
- IF PRD (Non-Game):
- - All Functional Requirements (FRs)
- - All Non-Functional Requirements (NFRs)
- - All Epics with user stories
- - Technical constraints mentioned
- - Integrations required (payments, email, etc.)
+- For beginners: Include brief explanations of architectural choices
+- For intermediate: Balance decisions with key rationale
+- For experts: Focus purely on technical specifications
-3. Read UX Spec (if project has UI):
- IF has_user_interface == true:
- Read: {{ux_spec_path}}
-
- Extract:
- - All screens/pages (list every screen defined)
- - Navigation structure (how screens connect, patterns)
- - Key user flows (auth, onboarding, checkout, core features)
- - UI complexity indicators:
- * Complex wizards/multi-step forms
- * Real-time updates/dashboards
- * Complex state machines
- * Rich interactions (drag-drop, animations)
- * Infinite scroll, virtualization needs
- - Component patterns (from design system/wireframes)
- - Responsive requirements (mobile-first, desktop-first, adaptive)
- - Accessibility requirements (WCAG level, screen reader support)
- - Design system/tokens (colors, typography, spacing if specified)
- - Performance requirements (page load times, frame rates)
-
-4. Cross-reference requirements + specs:
- IF GDD + UX Spec (game with UI):
- - Each gameplay mechanic should have UI representation
- - Each scene/level should have visual design
- - Player controls mapped to UI elements
-
- IF PRD + UX Spec (non-game):
- - Each epic should have corresponding screens/flows in UX spec
- - Each screen should support epic stories
- - FRs should have UI manifestation (where applicable)
- - NFRs (performance, accessibility) should inform UX patterns
- - Identify gaps: Epics without screens, screens without epic mapping
-
-5. Detect characteristics:
- - Project type(s): web, mobile, embedded, game, library, desktop
- - UI complexity: simple (CRUD) | moderate (dashboards) | complex (wizards/real-time)
- - Architecture style hints: monolith, microservices, modular, etc.
- - Repository strategy hints: monorepo, polyrepo, hybrid
- - Special needs: real-time, event-driven, batch, offline-first
-
-6. Identify what's already specified vs. unknown
- - Known: Technologies explicitly mentioned in PRD/UX spec
- - Unknown: Gaps that need decisions
-
-Output summary:
-- Project understanding
-- UI/UX summary (if applicable):
- * Screen count: N screens
- * Navigation complexity: simple | moderate | complex
- * UI complexity: simple | moderate | complex
- * Key user flows documented
-- PRD-UX alignment check: Gaps identified (if any)
+Remember the OUTPUT OPTIMIZATION critical - even beginner explanations should be concise.
-prd_and_ux_analysis
+
+user_context
-
-
-What's your experience level with {{project_type}} development?
+
-1. Beginner - Need detailed explanations and guidance
-2. Intermediate - Some explanations helpful
-3. Expert - Concise output, minimal explanations
+Based on the requirements analysis, determine the most appropriate architectural patterns:
-Your choice (1/2/3):
-
+- Consider the scale, complexity, and team size to choose between monolith, microservices, or serverless
+- Evaluate whether a single repository or multiple repositories best serves the project needs
+- Think about deployment and operational complexity vs. development simplicity
+
-
-Set user_skill_level variable for adaptive output:
-- beginner: Verbose explanations, examples, rationale for every decision
-- intermediate: Moderate explanations, key rationale, balanced detail
-- expert: Concise, decision-focused, minimal prose
+Guide the user through architectural pattern selection by discussing trade-offs and implications rather than presenting a menu of options. Help them understand what makes sense for their specific context.
-This affects ALL subsequent output verbosity.
-
-
-
-Any technical preferences or constraints I should know?
-- Preferred languages/frameworks?
-- Required platforms/services?
-- Team expertise areas?
-- Existing infrastructure (brownfield)?
-
-(Press enter to skip if none)
-
-
-
-Record preferences for narrowing recommendations.
-
+architecture_patterns
-
-
-Determine the architectural pattern based on requirements:
+
-1. Architecture style:
- - Monolith (single application)
- - Microservices (multiple services)
- - Serverless (function-based)
- - Other (event-driven, JAMstack, etc.)
+Analyze the epics and requirements to identify natural boundaries for components or services:
-2. Repository strategy:
- - Monorepo (single repo)
- - Polyrepo (multiple repos)
- - Hybrid
+- Group related functionality that changes together
+- Identify shared infrastructure needs (authentication, logging, monitoring)
+- Consider data ownership and consistency boundaries
+- Think about team structure and ownership
+
-3. Pattern-specific characteristics:
- - For web: SSR vs SPA vs API-only
- - For mobile: Native vs cross-platform vs hybrid vs PWA
- - For game: 2D vs 3D vs text-based vs web
- - For backend: REST vs GraphQL vs gRPC vs realtime
- - For data: ETL vs ML vs analytics vs streaming
- - Etc.
-
+Map epics to architectural components, ensuring each epic has a clear home and the overall structure supports the planned functionality.
-
-Based on your requirements, I need to determine the architecture pattern:
-
-1. Architecture style: {{suggested_style}} - Does this sound right? (or specify: monolith/microservices/serverless/other)
-
-2. Repository strategy: {{suggested_repo_strategy}} - Monorepo or polyrepo?
-
-{{project_type_specific_questions}}
-
-
-{project-root}/bmad/core/tasks/adv-elicit.xml
-architecture_pattern
+component_structure
-
-
-1. Analyze each epic from PRD:
- - What domain capabilities does it require?
- - What data does it operate on?
- - What integrations does it need?
+
-2. Identify natural component/service boundaries:
- - Vertical slices (epic-aligned features)
- - Shared infrastructure (auth, logging, etc.)
- - Integration points (external services)
+This is a crucial step where we ensure comprehensive architectural coverage.
-3. Determine architecture style:
- - Single monolith vs. multiple services
- - Monorepo vs. polyrepo
- - Modular monolith vs. microservices
+Load the project type registry from: {{installed_path}}/project-types/project-types.csv
-4. Map epics to proposed components (high-level only)
-
-component_boundaries
+Identify the closest matching project type(s) based on the requirements analysis. Note that projects may be hybrid (e.g., web + mobile, game + backend service).
+
+For each identified project type, load the corresponding questions from: {{installed_path}}/project-types/{{question_file}}
+
+IMPORTANT: Use the question files as a STARTING POINT, not a complete checklist. The questions help ensure we don't miss common decisions, but you must also:
+
+- Think deeply about project-specific needs not covered in the standard questions
+- Consider unique architectural requirements from the PRD/GDD
+- Address specific integrations or constraints mentioned in requirements
+- Add decisions for any specialized functionality or quality attributes
+
+
+Engage with the user to make all necessary technical decisions:
+
+- Use the question files to ensure coverage of common areas
+- Go beyond the standard questions to address project-specific needs
+- Focus on decisions that will affect implementation consistency
+- Get specific versions for all technology choices
+- Document clear rationale for non-obvious decisions
+
+
+Remember: The goal is to make enough definitive decisions that future implementation agents can work autonomously without architectural ambiguity.
+
+technical_decisions
-
-
-1. Load project types registry:
- Read: {{installed_path}}/project-types/project-types.csv
+
-2. Match detected project_type to CSV:
- - Use project_type from Step 1 (e.g., "web", "mobile", "backend")
- - Find matching row in CSV
- - Get question_file path
+Load the template registry from: {{installed_path}}/templates/registry.csv
-3. Load project-type-specific questions:
- Read: {{installed_path}}/project-types/{{question_file}}
+Select the most appropriate template based on:
-4. Ask only UNANSWERED questions (dynamic narrowing):
- - Skip questions already answered by reference architecture
- - Skip questions already specified in PRD
- - Focus on gaps and ambiguities
+- The identified project type(s)
+- The chosen architecture style
+- The repository strategy
+- The primary technologies selected
+
-5. Record all decisions with rationale
+Load the selected template and any associated guides to understand the document structure needed for this type of project.
-NOTE: For hybrid projects (e.g., "web + mobile"), load multiple question files
-
+Generate a comprehensive yet concise architecture document that includes:
-
-{{project_type_specific_questions}}
-
+MANDATORY SECTIONS (all projects):
-{project-root}/bmad/core/tasks/adv-elicit.xml
-architecture_decisions
-
+1. Executive Summary (1-2 paragraphs max)
+2. Technology Decisions Table - SPECIFIC versions for everything
+3. Repository Structure and Source Tree
+4. Component Architecture
+5. Data Architecture (if applicable)
+6. API/Interface Contracts (if applicable)
+7. Key Architecture Decision Records
-
-
-Sub-step 6.1: Load Appropriate Template
+The document MUST be optimized for LLM consumption:
-1. Analyze project to determine:
- - Project type(s): {{web|mobile|embedded|game|library|cli|desktop|data|backend|infra|extension}}
- - Architecture style: {{monolith|microservices|serverless|etc}}
- - Repository strategy: {{monorepo|polyrepo|hybrid}}
- - Primary language(s): {{TypeScript|Python|Rust|etc}}
+- Use tables over prose wherever possible
+- List specific versions, not generic technology names
+- Include complete source tree structure
+- Define clear interfaces and contracts
+- Avoid lengthy explanations unless absolutely necessary
+
-2. Search template registry:
- Read: {{installed_path}}/templates/registry.csv
+Ensure the document provides enough technical specificity that implementation agents can:
- Filter WHERE:
- - project_types = {{project_type}}
- - architecture_style = {{determined_style}}
- - repo_strategy = {{determined_strategy}}
- - languages matches {{language_preference}} (if specified)
- - tags overlap with {{requirements}}
-
-3. Select best matching row:
- Get {{template_path}} and {{guide_path}} from matched CSV row
- Example template: "web-fullstack-architecture.md", "game-engine-architecture.md", etc.
- Example guide: "game-engine-unity-guide.md", "game-engine-godot-guide.md", etc.
-
-4. Load markdown template:
- Read: {{installed_path}}/templates/{{template_path}}
-
- This template contains:
- - Complete document structure with all sections
- - {{placeholder}} variables to fill (e.g., {{project_name}}, {{framework}}, {{database_schema}})
- - Pattern-specific sections (e.g., SSR sections for web, gameplay sections for games)
- - Specialist recommendations (e.g., audio-designer for games, hardware-integration for embedded)
-
-5. Load pattern-specific guide (if available):
- IF {{guide_path}} is not empty:
- Read: {{installed_path}}/templates/{{guide_path}}
-
- This guide contains:
- - Engine/framework-specific questions
- - Technology-specific best practices
- - Common patterns and pitfalls
- - Specialist recommendations for this specific tech stack
- - Pattern-specific ADR examples
-
-6. Present template to user:
-
-
-
-Based on your {{project_type}} {{architecture_style}} project, I've selected the "{{template_path}}" template.
-
-This template includes {{section_count}} sections covering:
-{{brief_section_list}}
-
-I will now fill in all the {{placeholder}} variables based on our previous discussions and requirements.
-
-Options:
-1. Use this template (recommended)
-2. Use a different template (specify which one)
-3. Show me the full template structure first
-
-Your choice (1/2/3):
-
-
-
-Sub-step 6.2: Fill Template Placeholders
-
-6. Parse template to identify all {{placeholders}}
-
-7. Fill each placeholder with appropriate content:
- - Use information from previous steps (PRD, UX spec, tech decisions)
- - Ask user for any missing information
- - Generate appropriate content based on user_skill_level
-
-8. Generate final solution-architecture.md document
-
-CRITICAL REQUIREMENTS:
-- MUST include "Technology and Library Decisions" section with table:
- | Category | Technology | Version | Rationale |
- - ALL technologies with SPECIFIC versions (e.g., "pino 8.17.0")
- - NO vagueness ("a logging library" = FAIL)
-
-- MUST include "Proposed Source Tree" section:
- - Complete directory/file structure
- - For polyrepo: show ALL repo structures
-
-- Design-level only (NO extensive code implementations):
- - ✅ DO: Data model schemas, API contracts, diagrams, patterns
- - ❌ DON'T: 10+ line functions, complete components, detailed implementations
-
-- Adapt verbosity to user_skill_level:
- - Beginner: Detailed explanations, examples, rationale
- - Intermediate: Key explanations, balanced
- - Expert: Concise, decision-focused
-
-Common sections (adapt per project):
-1. Executive Summary
-2. Technology Stack and Decisions (TABLE REQUIRED)
-3. Repository and Service Architecture (mono/poly, monolith/microservices)
-4. System Architecture (diagrams)
-5. Data Architecture
-6. API/Interface Design (adapts: REST for web, protocols for embedded, etc.)
-7. Cross-Cutting Concerns
-8. Component and Integration Overview (NOT epic alignment - that's cohesion check)
-9. Architecture Decision Records
-10. Implementation Guidance
-11. Proposed Source Tree (REQUIRED)
-12-14. Specialist sections (DevOps, Security, Testing) - see Step 7.5
-
-NOTE: Section list is DYNAMIC per project type. Embedded projects have different sections than web apps.
-
+- Set up the development environment correctly
+- Implement features consistently with the architecture
+- Make minor technical decisions within the established framework
+- Understand component boundaries and responsibilities
+
solution_architecture
-
-
-CRITICAL: This is a validation quality gate before proceeding.
+
-Run cohesion check validation inline (NO separate workflow for now):
+Quality gate to ensure the architecture is ready for implementation.
-1. Requirements Coverage:
- - Every FR mapped to components/technology?
- - Every NFR addressed in architecture?
- - Every epic has technical foundation?
- - Every story can be implemented with current architecture?
+Perform a comprehensive validation of the architecture document:
-2. Technology and Library Table Validation:
- - Table exists?
- - All entries have specific versions?
- - No vague entries ("a library", "some framework")?
- - No multi-option entries without decision?
+- Verify every requirement has a technical solution
+- Ensure all technology choices have specific versions
+- Check that the document is free of ambiguous language
+- Validate that each epic can be implemented with the defined architecture
+- Confirm the source tree structure is complete and logical
+
-3. Code vs Design Balance:
- - Any sections with 10+ lines of code? (FLAG for removal)
- - Focus on design (schemas, patterns, diagrams)?
+Generate an Epic Alignment Matrix showing how each epic maps to:
-4. Vagueness Detection:
- - Scan for: "appropriate", "standard", "will use", "some", "a library"
- - Flag all vague statements for specificity
+- Architectural components
+- Data models
+- APIs and interfaces
+- External integrations
+ This matrix helps validate coverage and identify gaps.
-5. Generate Epic Alignment Matrix:
- | Epic | Stories | Components | Data Models | APIs | Integration Points | Status |
+If issues are found, work with the user to resolve them before proceeding. The architecture must be definitive enough for autonomous implementation.
- This matrix is SEPARATE OUTPUT (not in solution-architecture.md)
-
-6. Generate Cohesion Check Report with:
- - Executive summary (READY vs GAPS)
- - Requirements coverage table
- - Technology table validation
- - Epic Alignment Matrix
- - Story readiness (X of Y stories ready)
- - Vagueness detected
- - Over-specification detected
- - Recommendations (critical/important/nice-to-have)
- - Overall readiness score
-
-7. Present report to user
-
-
-cohesion_check_report
-
-
-Cohesion Check Results: {{readiness_score}}% ready
-
-{{if_gaps_found}}
-Issues found:
-{{list_critical_issues}}
-
-Options:
-1. I'll fix these issues now (update solution-architecture.md)
-2. You'll fix them manually
-3. Proceed anyway (not recommended)
-
-Your choice:
-{{/if}}
-
-{{if_ready}}
-✅ Architecture is ready for specialist sections!
-Proceed? (y/n)
-{{/if}}
-
-
-
-Update solution-architecture.md to address critical issues, then re-validate.
-
+cohesion_validation
-
-
-For each specialist area (DevOps, Security, Testing), assess complexity:
+
-DevOps Assessment:
-- Simple: Vercel/Heroku, 1-2 envs, simple CI/CD → Handle INLINE
-- Complex: K8s, 3+ envs, complex IaC, multi-region → Create PLACEHOLDER
+Assess the complexity of specialist areas (DevOps, Security, Testing) based on the project requirements:
-Security Assessment:
-- Simple: Framework defaults, no compliance → Handle INLINE
-- Complex: HIPAA/PCI/SOC2, custom auth, high sensitivity → Create PLACEHOLDER
+- For simple deployments and standard security, include brief inline guidance
+- For complex requirements (compliance, multi-region, extensive testing), create placeholders for specialist workflows
+
-Testing Assessment:
-- Simple: Basic unit + E2E → Handle INLINE
-- Complex: Mission-critical UI, comprehensive coverage needed → Create PLACEHOLDER
+Engage with the user to understand their needs in these specialist areas and determine whether to address them now or defer to specialist agents.
-For INLINE: Add 1-3 paragraph sections to solution-architecture.md
-For PLACEHOLDER: Add handoff section with specialist agent invocation instructions
-
-
-
-{{specialist_area}} Assessment: {{simple|complex}}
-
-{{if_complex}}
-Recommendation: Engage {{specialist_area}} specialist agent after this document.
-
-Options:
-1. Create placeholder, I'll engage specialist later (recommended)
-2. Attempt inline coverage now (may be less detailed)
-3. Skip (handle later)
-
-Your choice:
-{{/if}}
-
-{{if_simple}}
-I'll handle {{specialist_area}} inline with essentials.
-{{/if}}
-
-
-
-Update solution-architecture.md with specialist sections (inline or placeholders) at the END of document.
-
-
-specialist_sections
+specialist_guidance
-
-
-Did cohesion check or architecture design reveal:
-- Missing enabler epics (e.g., "Infrastructure Setup")?
-- Story modifications needed?
-- New FRs/NFRs discovered?
-
+
-
-Architecture design revealed some PRD updates needed:
-{{list_suggested_changes}}
+If the architecture design revealed gaps or needed clarifications in the requirements:
-Should I update the PRD? (y/n)
-
+- Identify missing enabler epics (e.g., infrastructure setup, monitoring)
+- Clarify ambiguous stories based on technical decisions
+- Add any newly discovered non-functional requirements
+
-
-Update PRD with architectural discoveries:
-- Add enabler epics if needed
-- Clarify stories based on architecture
-- Update tech-spec.md with architecture reference
-
+Work with the user to update the PRD if necessary, ensuring alignment between requirements and architecture.
-
-
-For each epic in PRD:
-1. Extract relevant architecture sections:
- - Technology stack (full table)
- - Components for this epic
- - Data models for this epic
- - APIs for this epic
- - Proposed source tree (relevant paths)
- - Implementation guidance
+
-2. Generate tech-spec-epic-{{N}}.md using tech-spec workflow logic:
- Read: {project-root}/bmad/bmm/workflows/3-solutioning/tech-spec/instructions.md
+For each epic, create a focused technical specification that extracts only the relevant parts of the architecture:
- Include:
- - Epic overview (from PRD)
- - Stories (from PRD)
- - Architecture extract (from solution-architecture.md)
- - Component-level technical decisions
- - Implementation notes
- - Testing approach
+- Technologies specific to that epic
+- Component details for that epic's functionality
+- Data models and APIs used by that epic
+- Implementation guidance specific to the epic's stories
+
-3. Save to: /docs/tech-spec-epic-{{N}}.md
-
+These epic-specific specs provide focused context for implementation without overwhelming detail.
-tech_specs
-
-
-Update bmm-workflow-status.md workflow status:
-- [x] Solution architecture generated
-- [x] Cohesion check passed
-- [x] Tech specs generated for all epics
-
+epic_tech_specs
-
-
-Is this a polyrepo project (multiple repositories)?
-
+
-
-For polyrepo projects:
+If this is a polyrepo project, ensure each repository has access to the complete architectural context:
-1. Identify all repositories from architecture:
- Example: frontend-repo, api-repo, worker-repo, mobile-repo
+- Copy the full architecture documentation to each repository
+- This ensures every repo has the complete picture for autonomous development
+
+
-2. Strategy: Copy FULL documentation to ALL repos
- - solution-architecture.md → Copy to each repo
- - tech-spec-epic-X.md → Copy to each repo (full set)
- - cohesion-check-report.md → Copy to each repo
+
-3. Add repo-specific README pointing to docs:
- "See /docs/solution-architecture.md for complete solution architecture"
+Validate that the architecture package is complete:
-4. Later phases extract per-epic and per-story contexts as needed
+- Solution architecture document with all technical decisions
+- Epic-specific technical specifications
+- Cohesion validation report
+- Clear source tree structure
+- Definitive technology choices with versions
+
-Rationale: Full context in every repo, extract focused contexts during implementation.
-
-
-
-For monorepo projects:
-- All docs already in single /docs directory
-- No special strategy needed
-
-
-
-
-
-Final validation checklist:
-
-- [x] solution-architecture.md exists and is complete
-- [x] Technology and Library Decision Table has specific versions
-- [x] Proposed Source Tree section included
-- [x] Cohesion check passed (or issues addressed)
-- [x] Epic Alignment Matrix generated
-- [x] Specialist sections handled (inline or placeholder)
-- [x] Tech specs generated for all epics
-- [x] Analysis template updated
-
-Generate completion summary:
-- Document locations
-- Key decisions made
-- Next steps (engage specialist agents if placeholders, begin implementation)
-
+Prepare the story backlog from the PRD/epics for Phase 4 implementation.
completion_summary
-
-
-Prepare for Phase 4 transition - Populate story backlog:
-
-1. Read PRD from {output_folder}/PRD.md or {output_folder}/epics.md
-2. Extract all epics and their stories
-3. Create ordered backlog list (Epic 1 stories first, then Epic 2, etc.)
-
-For each story in sequence:
-- epic_num: Epic number
-- story_num: Story number within epic
-- story_id: "{{epic_num}}.{{story_num}}" format
-- story_title: Story title from PRD/epics
-- story_file: "story-{{epic_num}}.{{story_num}}.md"
-
-4. Update bmm-workflow-status.md with backlog population:
-
-Open {output_folder}/bmm-workflow-status.md
-
-In "### Implementation Progress (Phase 4 Only)" section:
-
-#### BACKLOG (Not Yet Drafted)
-
-Populate table with ALL stories:
-
-| Epic | Story | ID | Title | File |
-| ---- | ----- | --- | --------------- | ------------ |
-| 1 | 1 | 1.1 | {{story_title}} | story-1.1.md |
-| 1 | 2 | 1.2 | {{story_title}} | story-1.2.md |
-| 1 | 3 | 1.3 | {{story_title}} | story-1.3.md |
-| 2 | 1 | 2.1 | {{story_title}} | story-2.1.md |
-... (all stories)
-
-**Total in backlog:** {{total_story_count}} stories
-
-#### TODO (Needs Drafting)
-
-Initialize with FIRST story:
-
-- **Story ID:** 1.1
-- **Story Title:** {{first_story_title}}
-- **Story File:** `story-1.1.md`
-- **Status:** Not created OR Draft (needs review)
-- **Action:** SM should run `create-story` workflow to draft this story
-
-#### IN PROGRESS (Approved for Development)
-
-Leave empty initially:
-
-(Story will be moved here by SM agent `story-ready` workflow)
-
-#### DONE (Completed Stories)
-
-Initialize empty table:
-
-| Story ID | File | Completed Date | Points |
-| ---------- | ---- | -------------- | ------ |
-| (none yet) | | | |
-
-**Total completed:** 0 stories
-**Total points completed:** 0 points
-
-5. Update "Workflow Status Tracker" section:
-- Set current_phase = "4-Implementation"
-- Set current_workflow = "Ready to begin story implementation"
-- Set progress_percentage = {{calculate based on phase completion}}
-- Check "3-Solutioning" checkbox in Phase Completion Status
-
-6. Update "Next Action Required" section:
-- Set next_action = "Draft first user story"
-- Set next_command = "Load SM agent and run 'create-story' workflow"
-- Set next_agent = "bmad/bmm/agents/sm.md"
-
-7. Update "Artifacts Generated" table:
-Add entries for all generated tech specs
-
-8. Add to Decision Log:
-- **{{date}}**: Phase 3 (Solutioning) complete. Architecture and tech specs generated. Populated story backlog with {{total_story_count}} stories. Ready for Phase 4 (Implementation). Next: SM drafts story 1.1.
-
-9. Save bmm-workflow-status.md
-
-
-
-**Phase 3 (Solutioning) Complete, {user_name}!**
-
-✅ Solution architecture generated
-✅ Cohesion check passed
-✅ {{epic_count}} tech specs generated
-✅ Story backlog populated ({{total_story_count}} stories)
-
-**Documents Generated:**
-- solution-architecture.md
-- cohesion-check-report.md
-- tech-spec-epic-1.md through tech-spec-epic-{{epic_count}}.md
-
-**Ready for Phase 4 (Implementation)**
-
-**Next Steps:**
-1. Load SM agent: `bmad/bmm/agents/sm.md`
-2. Run `create-story` workflow
-3. SM will draft story {{first_story_id}}: {{first_story_title}}
-4. You review drafted story
-5. Run `story-ready` workflow to approve it for development
-
-Would you like to proceed with story drafting now? (y/n)
-
-
-
-Search {output_folder}/ for files matching pattern: bmm-workflow-status.md
-Find the most recent file (by date in filename)
-
+
-
-Load the status file
-
-current_step
-Set to: "solution-architecture"
+Load {{status_file_path}}
current_workflow
Set to: "solution-architecture - Complete"
+phase_3_complete
+Set to: true
+
progress_percentage
Increment by: 15% (solution-architecture is a major workflow)
decisions_log
-Add entry:
-```
+Add entry: "- **{{date}}**: Completed solution-architecture workflow. Generated bmm-solution-architecture.md, bmm-cohesion-check-report.md, and {{epic_count}} tech-spec files. Populated story backlog with {{total_story_count}} stories. Phase 3 complete."
-- **{{date}}**: Completed solution-architecture workflow. Generated solution-architecture.md, cohesion-check-report.md, and {{epic_count}} tech-spec files. Populated story backlog with {{total_story_count}} stories. Phase 3 complete. Next: SM agent should run create-story to draft first story ({{first_story_id}}).
+STORIES_SEQUENCE
+Populate with ordered list of all stories from epics
-```
+TODO_STORY
+Set to: "{{first_story_id}}"
-next_action
-Set to: "Draft first user story ({{first_story_id}})"
+Save {{status_file_path}}
-next_command
-Set to: "Load SM agent and run 'create-story' workflow"
-
-next_agent
-Set to: "bmad/bmm/agents/sm.md"
-
-
-
-
-
-
-```
-
----
-
-## Reference Documentation
-
-For detailed design specification, rationale, examples, and edge cases, see:
-`./arch-plan.md` (when available in same directory)
-
-Key sections:
-
-- Key Design Decisions (15 critical requirements)
-- Step 6 - Architecture Generation (examples, guidance)
-- Step 7 - Cohesion Check (validation criteria, report format)
-- Dynamic Template Section Strategy
-- CSV Registry Examples
-
-This instructions.md is the EXECUTABLE guide.
-arch-plan.md is the REFERENCE specification.