bmad-method 6.0.0-alpha.1 → 6.0.0-alpha.10

package/src/modules/{bmm/workflows/2-plan-workflows → bmgd/workflows/2-design}/gdd/instructions-gdd.md

@@ -2,7 +2,7 @@
 
 <workflow>
 
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
@@ -13,10 +13,29 @@
 <critical>If users mention technical details, append to technical_preferences with timestamp</critical>
 
 <critical>DOCUMENT OUTPUT: Concise, clear, actionable game design specs. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
+<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
+
+## Input Document Discovery
+
+This workflow requires: game brief, and may reference market research or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
 
 <step n="0" goal="Validate workflow and extract project configuration">
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<invoke-workflow path="{project-root}/{bmad_folder}/bmm/workflows/workflow-status">
   <param>mode: data</param>
   <param>data_request: project_config</param>
 </invoke-workflow>
@@ -67,19 +86,27 @@ Use: `prd`
 </check>
 </step>
 
-<step n="0.5" goal="Validate workflow sequencing">
+<step n="0.5" goal="Validate workflow sequencing" tag="workflow-status">
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: validate</param>
-  <param>calling_workflow: gdd</param>
-</invoke-workflow>
+<check if="standalone_mode != true">
+  <action>Check status of "gdd" workflow in loaded status file</action>
+
+  <check if="gdd status is file path (already completed)">
+    <output>⚠️ GDD already completed: {{gdd status}}</output>
+    <ask>Re-running will overwrite the existing GDD. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
 
-<check if="warning != ''">
-  <output>{{warning}}</output>
-  <ask>Continue with GDD anyway? (y/n)</ask>
-  <check if="n">
-    <output>{{suggestion}}</output>
-    <action>Exit workflow</action>
+  <check if="gdd is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. GDD is out of sequence.</output>
+    <ask>Continue with GDD anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
   </check>
 </check>
 </step>
@@ -195,7 +222,6 @@ Get core game concept and vision.
 <action>Guide user to define the primary game mechanics that players will interact with throughout the game</action>
 
 <template-output>primary_mechanics</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 
 <action>Guide user to describe their control scheme and input method (keyboard/mouse, gamepad, touchscreen, etc.), including key bindings or button layouts if known</action>
 
@@ -213,8 +239,6 @@ For each {{placeholder}} in the fragment, elicit and capture that information.
 
 <template-output file="GDD.md">GAME_TYPE_SPECIFIC_SECTIONS</template-output>
 
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-
 </step>
 
 <step n="7" goal="Progression and balance">
@@ -278,7 +302,6 @@ For each {{placeholder}} in the fragment, elicit and capture that information.
 <action>Work with user to translate game features into development epics, following level-appropriate guidelines (Level 1: 1 epic/1-10 stories, Level 2: 1-2 epics/5-15 stories, Level 3: 2-5 epics/12-40 stories, Level 4: 5+ epics/40+ stories)</action>
 
 <template-output>epics</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 
 </step>
 
@@ -298,8 +321,7 @@ For each {{placeholder}} in the fragment, elicit and capture that information.
 
 <for-each epic="epic_list">
 
-<template-output file="epics.md">epic\_{{epic_number}}\_details</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
+<template-output file="epics.md">epic*{{epic_number}}*details</template-output>
 
 </for-each>
 
@@ -328,18 +350,23 @@ For each {{placeholder}} in the fragment, elicit and capture that information.
 
 </step>
 
-<step n="15" goal="Update status and populate story sequence">
+<step n="15" goal="Update status and populate story sequence" tag="workflow-status">
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: update</param>
-  <param>action: complete_workflow</param>
-  <param>workflow_name: gdd</param>
-  <param>populate_stories_from: {epics_output_file}</param>
-</invoke-workflow>
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "gdd"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["gdd"] = "{output_folder}/bmm-gdd-{{game_name}}-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<action>Parse {epics_output_file} to extract all stories</action>
+<action>Populate story_sequence section in status file with story IDs</action>
+<action>Set each story status to "not-started"</action>
+<output>Loaded {{total_stories}} stories from epics into story sequence.</output>
 
-<check if="success == true">
-  <output>Status updated! Next: {{next_workflow}} ({{next_agent}} agent)</output>
-  <output>Loaded {{total_stories}} stories from epics.</output>
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
+<output>Next workflow: {{next_workflow}} ({{next_agent}} agent)</output>
 </check>
 
 </step>
@@ -372,7 +399,7 @@ Your choice:</ask>
 </check>
 
 <check if="user selects option 1 or fuzzy indicates wanting to create the narrative design document">
-  <invoke-workflow>{project-root}/bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml</invoke-workflow>
+  <invoke-workflow>{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/narrative/workflow.yaml</invoke-workflow>
   <action>Pass GDD context to narrative workflow</action>
   <action>Exit current workflow (narrative will hand off to solutioning when done)</action>
 
@@ -466,7 +493,7 @@ Which would you like to proceed with?</ask>
 </check>
 
 <check if="user selects narrative option">
-  <invoke-workflow>{project-root}/bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml</invoke-workflow>
+  <invoke-workflow>{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/narrative/workflow.yaml</invoke-workflow>
   <action>Pass GDD context to narrative workflow</action>
 </check>
 

package/src/modules/bmgd/workflows/2-design/gdd/workflow.yaml

@@ -0,0 +1,81 @@
+# Game Design Document (GDD) Workflow
+name: gdd
+description: "Game Design Document workflow for all game project levels - from small prototypes to full AAA games. Generates comprehensive GDD with game mechanics, systems, progression, and implementation guidance."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+game_dev_experience: "{config_source}:game_dev_experience"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/{bmad_folder}/bmgd/workflows/2-design/gdd"
+instructions: "{installed_path}/instructions-gdd.md"
+template: "{installed_path}/gdd-template.md"
+game_types_csv: "{installed_path}/game-types.csv"
+
+# Output configuration
+default_output_file: "{output_folder}/GDD.md"
+
+# Game type references (loaded based on game type selection)
+game_type_guides: "{installed_path}/game-types/"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  game_brief:
+    description: "Game vision and core concept (optional)"
+    whole: "{output_folder}/*game-brief*.md"
+    sharded: "{output_folder}/*game-brief*/index.md"
+    load_strategy: "INDEX_GUIDED"
+
+  research:
+    description: "Market or domain research (optional)"
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+    load_strategy: "FULL_LOAD"
+
+  document_project:
+    description: "Brownfield project documentation (optional)"
+    sharded: "{output_folder}/index.md"
+    load_strategy: "INDEX_GUIDED"
+
+standalone: true
+
+web_bundle:
+  name: "gdd"
+  description: "Game Design Document workflow for all game project levels - from small prototypes to full AAA games. Generates comprehensive GDD with game mechanics, systems, progression, and implementation guidance."
+  author: "BMad"
+  instructions: "{bmad_folder}/bmgd/workflows/2-design/gdd/instructions-gdd.md"
+  web_bundle_files:
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/instructions-gdd.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/gdd-template.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types.csv"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/action-platformer.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/adventure.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/card-game.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/fighting.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/horror.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/idle-incremental.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/metroidvania.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/moba.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/party-game.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/puzzle.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/racing.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/rhythm.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/roguelike.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/rpg.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/sandbox.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/shooter.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/simulation.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/sports.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/strategy.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/survival.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/text-based.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/tower-defense.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/turn-based-tactics.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/gdd/game-types/visual-novel.md"

package/src/modules/{bmm/workflows/2-plan-workflows → bmgd/workflows/2-design}/narrative/instructions-narrative.md

@@ -2,28 +2,49 @@
 
 <workflow>
 
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
 <critical>You MUST have already completed the GDD workflow</critical>
 <critical>Communicate all responses in {communication_language}</critical>
 <critical>This workflow creates detailed narrative content for story-driven games</critical>
 <critical>Uses narrative_template for output</critical>
 <critical>If users mention gameplay mechanics, note them but keep focus on narrative</critical>
 <critical>Facilitate good brainstorming techniques throughout with the user, pushing them to come up with much of the narrative you will help weave together. The goal is for the user to feel that they crafted the narrative and story arc unless they push you to do it all or indicate YOLO</critical>
+<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
 
-<step n="0" goal="Check for workflow status">
+<step n="0" goal="Check for workflow status" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: init-check</param>
-</invoke-workflow>
-
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Set tracking_mode = true</action>
+<check if="status file not found">
+  <output>No workflow status file found. Narrative workflow is optional - you can continue without status tracking.</output>
+  <action>Set standalone_mode = true</action>
 </check>
 
-<check if="status_exists == false">
-  <action>Set tracking_mode = false</action>
-  <output>Note: Running without workflow tracking. Run `workflow-init` to enable progress tracking.</output>
+<check if="status file found">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "narrative" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+  <check if="narrative status is file path (already completed)">
+    <output>⚠️ Narrative Design Document already completed: {{narrative status}}</output>
+    <ask>Re-running will overwrite the existing narrative document. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+  <check if="narrative is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Narrative is out of sequence.</output>
+    <ask>Continue with Narrative Design anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
 </check>
 </step>
 
@@ -123,7 +144,6 @@ For 3-Act:
 Describe each act/section for your game:</ask>
 
 <template-output>act_breakdown</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 
 </step>
 
@@ -142,7 +162,6 @@ Format:
 Your story beats:</ask>
 
 <template-output>story_beats</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 
 <ask>Describe the pacing and flow of your narrative.
 
@@ -175,7 +194,6 @@ For each protagonist include:
 Your protagonist(s):</ask>
 
 <template-output>protagonists</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 
 </step>
 
@@ -213,7 +231,6 @@ For each character include:
 Your supporting characters:</ask>
 
 <template-output>supporting_characters</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 
 </step>
 
@@ -261,7 +278,6 @@ Your world:</ask>
 Your history:</ask>
 
 <template-output>history_backstory</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 
 </step>
 
@@ -539,19 +555,50 @@ Which would you like?</ask>
 
 </step>
 
-<step n="17" goal="Update status if tracking enabled">
+<step n="17" goal="Update status if tracking enabled" tag="workflow-status">
 
-<check if="tracking_mode == true">
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: narrative</param>
-  </invoke-workflow>
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "narrative"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["narrative"] = "{output_folder}/bmm-narrative-{{game_name}}-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-  <check if="success == true">
-    <output>✅ Status updated! Next: {{next_workflow}}</output>
-  </check>
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
 </check>
-</step>
+
+<output>**✅ Narrative Design Complete, {user_name}!**
+
+**Narrative Document:**
+
+- Narrative design saved to {output_folder}/bmm-narrative-{{game_name}}-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: narrative marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- **Optional:** Review narrative with writing team or stakeholders
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Review narrative design with team
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+  </step>
 
 </workflow>

package/src/modules/{bmm/workflows/2-plan-workflows → bmgd/workflows/2-design}/narrative/workflow.yaml

@@ -4,35 +4,29 @@ description: "Narrative design workflow for story-driven games and applications.
 author: "BMad"
 
 # Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 document_output_language: "{config_source}:document_output_language"
-user_skill_level: "{config_source}:user_skill_level"
+game_dev_experience: "{config_source}:game_dev_experience"
 date: system-generated
 
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/narrative"
+installed_path: "{project-root}/{bmad_folder}/bmgd/workflows/2-design/narrative"
 instructions: "{installed_path}/instructions-narrative.md"
 template: "{installed_path}/narrative-template.md"
 
 # Output configuration
 default_output_file: "{output_folder}/narrative-design.md"
 
-# Recommended input documents
-recommended_inputs:
-  - game_brief: "{output_folder}/game-brief.md"
-  - gdd: "{output_folder}/GDD.md"
-  - product_brief: "{output_folder}/product-brief.md"
-
 standalone: true
 
 web_bundle:
   name: "narrative"
   description: "Narrative design workflow for story-driven games and applications. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance."
   author: "BMad"
-  instructions: "bmad/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md"
+  instructions: "{bmad_folder}/bmgd/workflows/2-design/narrative/instructions-narrative.md"
   web_bundle_files:
-    - "bmad/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md"
-    - "bmad/bmm/workflows/2-plan-workflows/narrative/narrative-template.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/narrative/instructions-narrative.md"
+    - "{bmad_folder}/bmgd/workflows/2-design/narrative/narrative-template.md"