bmad-method 6.0.0-alpha.6 → 6.0.0-alpha.8

package/src/modules/bmm/workflows/4-implementation/code-review/instructions.md

@@ -1,7 +1,7 @@
 # Senior Developer Review - Workflow Instructions
 
 ````xml
-<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>
@@ -16,38 +16,37 @@
 
 <critical>DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content.</critical>
 
-## 📚 Document Discovery - Selective Epic Loading
+<workflow>
 
-**Strategy**: This workflow needs only ONE specific epic and its stories for review context, not all epics. This provides huge efficiency gains when epics are sharded.
+  <step n="1" goal="Find story ready for review" tag="sprint-status">
+    Document Discovery - Selective Epic Loading
 
-**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+    **Strategy**: This workflow needs only ONE specific epic and its stories for review context, not all epics. This provides huge efficiency gains when epics are sharded.
 
-1. **Determine which epic** you need (epic_num from story being reviewed - e.g., story "3-2-feature-name" needs Epic 3)
-2. **Check for sharded version**: Look for `epics/index.md`
-3. **If sharded version found**:
-   - Read `index.md` to understand structure
-   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
-   - DO NOT load all epic files - only the one needed!
-   - This is the key efficiency optimization for large multi-epic projects
-4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+    **Epic Discovery Process (SELECTIVE OPTIMIZATION):**
 
-**Other Documents (architecture, ux-design) - Full Load:**
+    1. **Determine which epic** you need (epic_num from story being reviewed - e.g., story "3-2-feature-name" needs Epic 3)
+    2. **Check for sharded version**: Look for `epics/index.md`
+    3. **If sharded version found**:
+      - Read `index.md` to understand structure
+      - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+      - DO NOT load all epic files - only the one needed!
+      - This is the key efficiency optimization for large multi-epic projects
+    4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
 
-1. **Search for whole document first** - Use fuzzy file matching
-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 structure
-   - Read ALL section files listed in the index
-   - Treat combined content as single document
-4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+    **Other Documents (architecture, ux-design) - Full Load:**
 
-**Priority**: If both whole and sharded versions exist, use the whole document.
+    1. **Search for whole document first** - Use fuzzy file matching
+    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 structure
+      - Read ALL section files listed in the index
+      - Treat combined content as single document
+    4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
 
-**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for reviewing UI-focused stories.
+    **Priority**: If both whole and sharded versions exist, use the whole document.
 
-<workflow>
-
-  <step n="1" goal="Find story ready for review" tag="sprint-status">
+    **UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for reviewing UI-focused stories.
     <check if="{{story_path}} is provided">
       <action>Use {{story_path}} directly</action>
       <action>Read COMPLETE story file and parse sections</action>
@@ -80,17 +79,18 @@
         <check if="option 3 selected">
           <ask>What code would you like me to review?
 
-Provide:
-- File path(s) or directory to review
-- What to review for:
-  • General quality and standards
-  • Requirements compliance
-  • Security concerns
-  • Performance issues
-  • Architecture alignment
-  • Something else (specify)
+          Provide:
+          - File path(s) or directory to review
+          - What to review for:
+            • General quality and standards
+            • Requirements compliance
+            • Security concerns
+            • Performance issues
+            • Architecture alignment
+            • Something else (specify)
 
-Your input:</ask>
+            Your input:?
+          </ask>
 
           <action>Parse user input to extract:
             - {{review_files}}: file paths or directories to review
@@ -363,11 +363,11 @@ Review was saved to story file, but sprint-status.yaml may be out of sync.
       <action if="user confirms or no ask needed">
         Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)".
       </action>
-      <action if="{{persist_action_items}} == true and 'backlog_file' in {{persist_targets}}">
+      <action>
         If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
         Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs.
       </action>
-      <action if="{{persist_action_items}} == true and ('epic_followups' in {{persist_targets}} or {{update_epic_followups}} == true)">
+      <action>
         If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}.
       </action>
       <action>Save modified files.</action>
@@ -376,7 +376,7 @@ Review was saved to story file, but sprint-status.yaml may be out of sync.
   </step>
 
   <step n="10" goal="Validation and completion">
-    <invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml</invoke-task>
     <action>Report workflow completion.</action>
 
     <check if="ad_hoc_review_mode == true">

package/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -4,16 +4,18 @@ description: "Perform a Senior Developer code review on a completed story flagge
 author: "BMad"
 
 # Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
 document_output_language: "{config_source}:document_output_language"
 date: system-generated
+ephemeral_files: "{config_source}:dev_ephemeral_location"
+sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/code-review"
+installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/code-review"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
@@ -22,8 +24,8 @@ template: false
 
 # Variables (can be provided by caller)
 variables:
-  story_path: "" # Optional: Explicit path to story file. If not provided, finds first story with status "review"
-  story_dir: "{config_source}:dev_story_location" # Directory containing story files
+  story_path: "{ephemeral_files}/stories" # Optional: Explicit path to story file. If not provided, finds first story with status "review"
+  story_dir: "{ephemeral_files}/stories" # Directory containing story files
   tech_spec_search_dir: "{project-root}/docs"
   tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
   arch_docs_search_dirs: |
@@ -31,26 +33,10 @@ variables:
     - "{output_folder}"
   arch_docs_file_names: |
     - architecture.md
-  enable_mcp_doc_search: true # Prefer enabled MCP servers for doc/best-practice lookup
-  enable_web_fallback: true # Fallback to web search/read-url if MCP not available
-  # Persistence controls for review action items and notes
-  persist_action_items: true
-  # Valid targets: story_tasks, story_review_section, backlog_file, epic_followups
-  persist_targets: |
-    - story_review_section
-    - story_tasks
-    - backlog_file
-    - epic_followups
   backlog_file: "{project-root}/docs/backlog.md"
   update_epic_followups: true
   epic_followups_section_title: "Post-Review Follow-ups"
 
-# Recommended inputs
-recommended_inputs:
-  - story: "Path to the story file (auto-discovered if omitted - finds first story with status 'review')"
-  - tech_spec: "Epic technical specification document (auto-discovered)"
-  - story_context_file: "Story context file (.context.xml) (auto-discovered)"
-
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
 # Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review
@@ -58,16 +44,13 @@ input_file_patterns:
   architecture:
     whole: "{output_folder}/*architecture*.md"
     sharded: "{output_folder}/*architecture*/index.md"
-
   ux_design:
     whole: "{output_folder}/*ux*.md"
     sharded: "{output_folder}/*ux*/index.md"
-
   epics:
     whole: "{output_folder}/*epic*.md"
     sharded_index: "{output_folder}/*epic*/index.md"
     sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
-
   document_project:
     sharded: "{output_folder}/docs/index.md"
 

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

@@ -1,6 +1,6 @@
 # Change Navigation Checklist
 
-<critical>This checklist is executed as part of: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>This checklist is executed as part of: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
 <critical>Work through each section systematically with the user, recording findings and impacts</critical>
 
 <checklist>

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

@@ -1,7 +1,7 @@
 # Correct Course - Sprint Change Management Instructions
 
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</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: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/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>
 

package/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml

@@ -3,7 +3,7 @@ name: "correct-course"
 description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation"
 author: "BMad Method"
 
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
@@ -11,7 +11,7 @@ user_skill_level: "{config_source}:user_skill_level"
 document_output_language: "{config_source}:document_output_language"
 date: system-generated
 
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
+installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course"
 template: false
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"

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

@@ -1,51 +1,52 @@
 # Create Story - Workflow Instructions (Spec-compliant, non-interactive by default)
 
 ````xml
-<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>Generate all documents in {document_output_language}</critical>
 <critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
 <critical>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks.</critical>
 
-## 📚 Document Discovery - Selective Epic Loading
-
-**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
-
-**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
-
-1. **Determine which epic** you need (epic_num from story context - e.g., story "3-2-feature-name" needs Epic 3)
-2. **Check for sharded version**: Look for `epics/index.md`
-3. **If sharded version found**:
-   - Read `index.md` to understand structure
-   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
-   - DO NOT load all epic files - only the one needed!
-   - This is the key efficiency optimization for large multi-epic projects
-4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
-
-**Other Documents (prd, architecture, ux-design) - Full Load:**
-
-1. **Search for whole document first** - Use fuzzy file matching
-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 structure
-   - Read ALL section files listed in the index
-   - Treat combined content as single document
-4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
-
-**Priority**: If both whole and sharded versions exist, use the whole document.
-
-**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
-
 <workflow>
 
   <step n="1" goal="Load config and initialize">
-    <action>Resolve variables from config_source: story_dir (dev_story_location), output_folder, user_name, communication_language. If story_dir missing and {{non_interactive}} == false → ASK user to provide a stories directory and update variable. If {{non_interactive}} == true and missing, HALT with a clear message.</action>
+    <action>Resolve variables from config_source: story_dir (dev_ephemeral_location), output_folder, user_name, communication_language. If story_dir missing → ASK user to provide a stories directory and update variable.</action>
     <action>Create {{story_dir}} if it does not exist</action>
     <action>Resolve installed component paths from workflow.yaml: template, instructions, validation</action>
     <action>Resolve recommended inputs if present: epics_file, prd_file, architecture_file</action>
   </step>
 
   <step n="2" goal="Discover and load source documents">
+    <action>
+      Selective Epic Loading
+
+      **Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+
+      **Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+      1. **Determine which epic** you need (epic_num from story context - e.g., story "3-2-feature-name" needs Epic 3)
+      2. **Check for sharded version**: Look for `epics/*n*.md` where n is the epic number such as epics/epic-3-foo.md
+      3. **If sharded version found**:
+        - Read `index.md` to understand structure
+        - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+        - DO NOT load all epic files - only the one needed!
+        - This is the key efficiency optimization for large multi-epic projects
+      4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+      **Other Documents (prd, architecture, ux-design) - Full Load:**
+
+      1. **Search for whole document first** - Use fuzzy file matching
+      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 structure
+        - Read ALL section files listed in the index
+        - Treat combined content as single document
+      4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+      **Priority**: If both whole and sharded versions exist, use the whole document.
+
+      **UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
+    </action>
     <critical>PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development</critical>
 
     <action>Find the previous completed story to extract dev agent learnings and review findings:
@@ -115,19 +116,17 @@
     </action>
 
     <action>If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time.</action>
-    <action>Build a prioritized document set for this epic:
+    <action>Build a prioritized document set for this epic - search and load from {input_file_patterns} list of potential locations:
       1) tech_spec_file (epic-scoped)
-      2) epics_file (acceptance criteria and breakdown)
-      3) prd_file (business requirements and constraints)
-      4) architecture_file (architecture constraints)
-      5) Architecture docs under docs/ and output_folder/: tech-stack.md, unified-project-structure.md, coding-standards.md, testing-strategy.md, backend-architecture.md, frontend-architecture.md, data-models.md, database-schema.md, rest-api-spec.md, external-apis.md (include if present)
+      2) epics_file (acceptance criteria and breakdown) the specific epic the story will be part of
+      3) prd_file (business requirements and constraints) whole or sharded
+      4) architecture_file (architecture constraints) whole or sharded
     </action>
     <action>READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation.</action>
   </step>
 
   <step n="3" goal="Find next backlog story to draft" tag="sprint-status">
-    <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
-    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical>
     <action>Read ALL lines from beginning to end - do not skip any content</action>
     <action>Parse the development_status section completely to understand story order</action>
 
@@ -164,7 +163,6 @@ All stories are either already drafted or completed.
     <action>Check if story file already exists at expected path in {{story_dir}}</action>
     <check if="story file exists">
       <output>ℹ️ Story file already exists: {{story_file_path}}
-
 Will update existing story file rather than creating new one.
       </output>
       <action>Set update_mode = true</action>
@@ -240,7 +238,7 @@ Will update existing story file rather than creating new one.
   </step>
 
   <step n="8" goal="Validate, save, and mark story drafted" tag="sprint-status">
-    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml</invoke-task>
     <action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
 
     <!-- Mark story as drafted in sprint status -->

package/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -3,21 +3,22 @@ description: "Create the next user story markdown from epics/PRD and architectur
 author: "BMad"
 
 # Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
+story_dir: "{config_source}:dev_ephemeral_location/stories"
 
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/create-story"
+installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
 variables:
-  story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
+  sprint_status: "{config_source}:dev_ephemeral_location/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Primary source for story tracking
   epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
   prd_file: "{output_folder}/PRD.md" # Fallback for requirements
   architecture_file: "{output_folder}/architecture.md" # Optional architecture context
@@ -28,22 +29,13 @@ variables:
     - "{project-root}/docs"
     - "{output_folder}"
   arch_docs_file_names: |
-    - architecture.md
-    - infrastructure-architecture.md
+    - *architecture*.md
   story_title: "" # Will be elicited if not derivable
-  epic_num: 1
-  story_num: 1
-  non_interactive: true # Generate without elicitation; avoid interactive prompts
 
 # Output configuration
 # Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
 default_output_file: "{story_dir}/{{story_key}}.md"
 
-recommended_inputs:
-  - epics: "Epic breakdown (epics.md)"
-  - prd: "PRD document"
-  - architecture: "Architecture (optional)"
-
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
 # Strategy: SELECTIVE LOAD - only load the specific epic needed for this story
@@ -51,25 +43,20 @@ input_file_patterns:
   prd:
     whole: "{output_folder}/*prd*.md"
     sharded: "{output_folder}/*prd*/index.md"
-
   tech_spec:
     whole: "{output_folder}/tech-spec.md"
-
   architecture:
     whole: "{output_folder}/*architecture*.md"
     sharded: "{output_folder}/*architecture*/index.md"
-
   ux_design:
     whole: "{output_folder}/*ux*.md"
     sharded: "{output_folder}/*ux*/index.md"
-
   epics:
     whole: "{output_folder}/*epic*.md"
     sharded_index: "{output_folder}/*epic*/index.md"
     sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
-
   document_project:
-    sharded: "{output_folder}/docs/index.md"
+    sharded: "{output_folder}/index.md"
 
 standalone: true
 

package/src/modules/bmm/workflows/4-implementation/dev-story/AUDIT-REPORT.md

@@ -26,7 +26,7 @@ The dev-story workflow is well-structured and follows most BMAD v6 standards. Th
 
 The workflow.yaml contains all required standard config variables:
 
-- ✓ `config_source: "{project-root}/bmad/bmm/config.yaml"` - Correctly defined
+- ✓ `config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"` - Correctly defined
 - ✓ `output_folder: "{config_source}:output_folder"` - Pulls from config_source
 - ✓ `user_name: "{config_source}:user_name"` - Pulls from config_source
 - ✓ `communication_language: "{config_source}:communication_language"` - Pulls from config_source
@@ -67,7 +67,7 @@ These variables appear to be pulling from config.yaml but are not explicitly def
 
 ### Unused Variables (Bloat)
 
-1. **context_path** - Defined as `"{config_source}:dev_story_location"` but never used. This duplicates `story_dir` functionality.
+1. **context_path** - Defined as `"{config_source}:dev_ephemeral_location"` but never used. This duplicates `story_dir` functionality.
 
 ---
 
@@ -140,7 +140,7 @@ The workflow correctly sets `web_bundle: false`. This is the expected configurat
 ### Unused YAML Fields
 
 1. **context_path** (line 11 in workflow.yaml)
-   - Defined as: `"{config_source}:dev_story_location"`
+   - Defined as: `"{config_source}:dev_ephemeral_location"`
    - Never referenced in instructions.md
    - Duplicates functionality of `story_dir` variable
    - **Recommendation:** Remove this variable as `story_dir` serves the same purpose

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

@@ -1,7 +1,7 @@
 # Develop Story - Workflow Instructions
 
 ```xml
-<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>
@@ -227,7 +227,7 @@ Story is marked Ready for Review in file, but sprint-status.yaml may be out of s
   </step>
 
   <step n="7" goal="Completion communication and user support">
-    <action>Optionally run the workflow validation task against the story using {project-root}/bmad/core/tasks/validate-workflow.xml</action>
+    <action>Optionally run the workflow validation task against the story using {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml</action>
     <action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
 
     <action>Communicate to {user_name} that story implementation is complete and ready for review</action>

package/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml

@@ -3,13 +3,13 @@ description: "Execute a story by implementing tasks/subtasks, writing tests, val
 author: "BMad"
 
 # Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
 document_output_language: "{config_source}:document_output_language"
-story_dir: "{config_source}:dev_story_location"
+story_dir: "{config_source}:dev_ephemeral_location"
 run_until_complete: "{config_source}:run_until_complete"
 run_tests_command: "{config_source}:run_tests_command"
 date: system-generated
@@ -19,7 +19,7 @@ story_file: "" # Explicit story path; auto-discovered if empty
 context_file: "{story_dir}/{{story_key}}.context.xml"
 
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story"
+installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/dev-story"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 

package/src/modules/bmm/workflows/4-implementation/epic-tech-context/checklist.md

@@ -1,7 +1,7 @@
 # Tech Spec Validation Checklist
 
 ```xml
-<checklist id="bmad/bmm/workflows/4-implementation/epic-tech-context/checklist">
+<checklist id="{bmad_folder}/bmm/workflows/4-implementation/epic-tech-context/checklist">
   <item>Overview clearly ties to PRD goals</item>
   <item>Scope explicitly lists in-scope and out-of-scope</item>
   <item>Design lists all services/modules with responsibilities</item>

package/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md

@@ -1,49 +1,47 @@
 <!-- BMAD BMM Tech Spec Workflow Instructions (v6) -->
 
 ```xml
-<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}</critical>
 <critical>This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping.</critical>
 <critical>If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed.</critical>
 
-## 📚 Document Discovery - Selective Epic Loading
-
-**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+<workflow>
+  <step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
+    Document Discovery - Selective Epic Loading
 
-**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+    **Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
 
-1. **Determine which epic** you need (epic_num from workflow context or user input)
-2. **Check for sharded version**: Look for `epics/index.md`
-3. **If sharded version found**:
-   - Read `index.md` to understand structure
-   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
-   - DO NOT load all epic files - only the one needed!
-   - This is the key efficiency optimization for large multi-epic projects
-4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+    **Epic Discovery Process (SELECTIVE OPTIMIZATION):**
 
-**Other Documents (prd, gdd, architecture, ux-design) - Full Load:**
+    1. **Determine which epic** you need (epic_num from workflow context or user input)
+    2. **Check for sharded version**: Look for `epics/index.md`
+    3. **If sharded version found**:
+      - Read `index.md` to understand structure
+      - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+      - DO NOT load all epic files - only the one needed!
+      - This is the key efficiency optimization for large multi-epic projects
+    4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
 
-1. **Search for whole document first** - Use fuzzy file matching
-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 structure
-   - Read ALL section files listed in the index
-   - Treat combined content as single document
-4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+    **Other Documents (prd, gdd, architecture, ux-design) - Full Load:**
 
-**Priority**: If both whole and sharded versions exist, use the whole document.
+    1. **Search for whole document first** - Use fuzzy file matching
+    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 structure
+      - Read ALL section files listed in the index
+      - Treat combined content as single document
+    4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
 
-**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused epics and stories.
+    **Priority**: If both whole and sharded versions exist, use the whole document.
 
-<workflow>
-  <step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
+    **UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused epics and stories.
     <action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>
     <ask if="inputs are missing">ask the user for file paths. HALT and wait for docs to proceed</ask>
 
     <!-- Intelligent Epic Discovery -->
-    <critical>MUST read COMPLETE sprint-status.yaml file to discover next epic</critical>
-    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <critical>MUST read COMPLETE {sprint-status} file to discover next epic</critical>
     <action>Read ALL development_status entries</action>
     <action>Find all epics with status "backlog" (not yet contexted)</action>
     <action>Identify the FIRST backlog epic as the suggested default</action>
@@ -157,7 +155,7 @@ Continuing to regenerate tech spec...
   </step>
 
   <step n="9" goal="Validate and mark epic contexted" tag="sprint-status">
-    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml</invoke-task>
 
     <!-- Mark epic as contexted -->
     <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>