more updates to use ephemeral file location for phase 4 items

src/core/workflows/brainstorming/README.md

@@ -35,7 +35,7 @@ workflow brainstorming --data /path/to/context.md
 
 ### Configuration
 
-The workflow leverages configuration from `/{bmad_folder}/cis/config.yaml`:
+The workflow leverages configuration from `{bmad_folder}/cis/config.yaml`:
 
 - **output_folder**: Where session results are saved
 - **user_name**: Session participant identification
@@ -185,7 +185,7 @@ The workflow includes 36 techniques organized into 7 categories:
 ## Requirements
 
 - No special software requirements
-- Access to the CIS module configuration (`/{bmad_folder}/cis/config.yaml`)
+- Access to the CIS module configuration (`{bmad_folder}/cis/config.yaml`)
 - Active participation and engagement throughout the interactive session
 - Optional: Domain context document for focused brainstorming
 

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

@@ -41,7 +41,7 @@ tech_docs:
   result: "{project-root}/{value}"
 
 dev_ephemeral_location:
-  prompt: "Where should ephemeral development artifacts be stored (stories, epics, temp context, etc...)?"
+  prompt: "Where should ephemeral development artifacts be stored (workflow and sprint status, stories, epics, temp context, etc...)?"
   default: "{bmad_folder}-ephemeral"
   result: "{project-root}/{value}"
 

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

@@ -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
-
-**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.
-
-**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
-
-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
-
-**Other Documents (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 reviewing UI-focused stories.
-
 <workflow>
 
   <step n="1" goal="Find story ready for review" tag="sprint-status">
+    Document Discovery - Selective Epic Loading
+
+    **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.
+
+    **Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+    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
+
+    **Other Documents (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 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:
+          Provide:
-- File path(s) or directory to review
+          - File path(s) or directory to review
-- What to review for:
+          - What to review for:
-  • General quality and standards
+            • General quality and standards
-  • Requirements compliance
+            • Requirements compliance
-  • Security concerns
+            • Security concerns
-  • Performance issues
+            • Performance issues
-  • Architecture alignment
+            • Architecture alignment
-  • Something else (specify)
+            • Something else (specify)
 
-Your input:</ask>
+            Your input:?
+          </ask>
 
           <action>Parse user input to extract:
             - {{review_files}}: file paths or directories to review

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

@@ -12,6 +12,7 @@ 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_folder}/bmm/workflows/4-implementation/code-review"
@@ -36,12 +37,6 @@ variables:
   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
@@ -49,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"
 

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

@@ -7,45 +7,46 @@
 <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_ephemeral_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)
+      2) epics_file (acceptance criteria and breakdown) the specific epic the story will be part of
-      3) prd_file (business requirements and constraints)
+      3) prd_file (business requirements and constraints) whole or sharded
-      4) architecture_file (architecture constraints)
+      4) architecture_file (architecture constraints) whole or sharded
-      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)
     </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>
+    <critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical>
-    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
     <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>

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

@@ -8,7 +8,7 @@ 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"
+story_dir: "{config_source}:dev_ephemeral_location/stories"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story"
@@ -18,6 +18,7 @@ validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
 variables:
+  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
+    - *architecture*.md
-    - infrastructure-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
 

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

@@ -7,43 +7,41 @@
 <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.
-
-**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
-
-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
-
-**Other Documents (prd, gdd, 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 epics and stories.
-
 <workflow>
   <step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
+    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 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
+
+    **Other Documents (prd, gdd, 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 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>
+    <critical>MUST read COMPLETE {sprint-status} file to discover next epic</critical>
-    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
     <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>

src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml

@@ -8,16 +8,8 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
-context_dir: "{config_source}:dev_ephemeral_location"
+context_dir: "{config_source}:dev_ephemeral_location/stories"
-
+sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
-# Inputs expected (check output_folder or ask user if missing)
-recommended_inputs:
-  - prd
-  - gdd
-  - architecture
-  - ux_design
-  - epics (only the specific epic needed for this tech spec)
-  - prior epic tech-specs for model, style and consistency reference
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
@@ -26,26 +18,21 @@ input_file_patterns:
   prd:
     whole: "{output_folder}/*prd*.md"
     sharded: "{output_folder}/*prd*/index.md"
-
   gdd:
     whole: "{output_folder}/*gdd*.md"
     sharded: "{output_folder}/*gdd*/index.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"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/epic-tech-context"

src/modules/bmm/workflows/4-implementation/retrospective/instructions.md

@@ -32,7 +32,7 @@ PARTY MODE PROTOCOL:
 
 **Epic Discovery (SELECTIVE LOAD):**
 
-1. Determine completed epic number (from sprint-status or user)
+1. Determine completed epic number (from {sprint_status_file} or user)
 2. If sharded: Load ONLY `epic-{epic_num}.md`
 3. If whole: Load complete epics file and extract relevant epic
 
@@ -59,7 +59,7 @@ PARTY MODE PROTOCOL:
 Bob (Scrum Master): "Welcome to the retrospective, {user_name}. Let me help you identify which epic we just completed. I'll check sprint-status first, but you're the ultimate authority on what we're reviewing today."
 </output>
 
-<action>PRIORITY 1: Check sprint-status.yaml first</action>
+<action>PRIORITY 1: Check {sprint_status_file} first</action>
 
 <action>Load the FULL file: {sprint_status_file}</action>
 <action>Read ALL development_status entries</action>
@@ -71,7 +71,7 @@ Bob (Scrum Master): "Welcome to the retrospective, {user_name}. Let me help you
   <action>Present finding to user with context</action>
 
   <output>
-Bob (Scrum Master): "Based on sprint-status.yaml, it looks like Epic {{detected_epic}} was recently completed. Is that the epic you want to review today, {user_name}?"
+Bob (Scrum Master): "Based on {sprint_status_file}, it looks like Epic {{detected_epic}} was recently completed. Is that the epic you want to review today, {user_name}?"
   </output>
 
 <action>WAIT for {user_name} to confirm or correct</action>
@@ -92,7 +92,7 @@ Bob (Scrum Master): "Got it, we're reviewing Epic {{epic_number}}. Let me gather
   <action>PRIORITY 2: Ask user directly</action>
 
   <output>
-Bob (Scrum Master): "I'm having trouble detecting the completed epic from sprint-status.yaml. {user_name}, which epic number did you just complete?"
+Bob (Scrum Master): "I'm having trouble detecting the completed epic from {sprint_status_file}. {user_name}, which epic number did you just complete?"
   </output>
 
 <action>WAIT for {user_name} to provide epic number</action>
@@ -116,7 +116,7 @@ Bob (Scrum Master): "I found stories for Epic {{detected_epic}} in the stories f
 
 <action>Once {{epic_number}} is determined, verify epic completion status</action>
 
-<action>Find all stories for epic {{epic_number}} in sprint-status.yaml:
+<action>Find all stories for epic {{epic_number}} in {sprint_status_file}:
 
 - Look for keys starting with "{{epic_number}}-" (e.g., "1-1-", "1-2-", etc.)
 - Exclude epic key itself ("epic-{{epic_number}}")
@@ -1346,7 +1346,7 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!"
 ✅ Retrospective document saved: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md
 </output>
 
-<action>Update sprint-status.yaml to mark retrospective as completed</action>
+<action>Update {sprint_status_file} to mark retrospective as completed</action>
 
 <action>Load the FULL file: {sprint_status_file}</action>
 <action>Find development_status key "epic-{{epic_number}}-retrospective"</action>
@@ -1356,7 +1356,7 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!"
 
 <check if="update successful">
   <output>
-✅ Retrospective marked as completed in sprint-status.yaml
+✅ Retrospective marked as completed in {sprint_status_file}
 
 Retrospective key: epic-{{epic_number}}-retrospective
 Status: {{previous_status}} → done
@@ -1365,9 +1365,9 @@ Status: {{previous_status}} → done
 
 <check if="retrospective key not found">
   <output>
-⚠️ Could not update retrospective status: epic-{{epic_number}}-retrospective not found in sprint-status.yaml
+⚠️ Could not update retrospective status: epic-{{epic_number}}-retrospective not found in {sprint_status_file}
 
-Retrospective document was saved successfully, but sprint-status.yaml may need manual update.
+Retrospective document was saved successfully, but {sprint_status_file} may need manual update.
 </output>
 </check>
 

src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml

@@ -30,23 +30,19 @@ input_file_patterns:
     whole: "{output_folder}/*epic*.md"
     sharded_index: "{output_folder}/*epic*/index.md"
     sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
-
   previous_retrospective:
     pattern: "{ephemeral_files}/retrospectives/epic-{{prev_epic_num}}-retro-*.md"
-
   architecture:
     whole: "{output_folder}/*architecture*.md"
     sharded: "{output_folder}/*architecture*/index.md"
-
   prd:
     whole: "{output_folder}/*prd*.md"
     sharded: "{output_folder}/*prd*/index.md"
-
   document_project:
     sharded: "{output_folder}/docs/index.md"
 
 # Required files
-sprint_status_file: "{ephemeral_files}/sprint-status.yaml"
+sprint_status_file: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 story_directory: "{ephemeral_files}/stories"
 retrospectives_folder: "{ephemeral_files}/retrospectives"
 

src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -141,8 +141,6 @@ development_status:
 ```
 
 <action>Write the complete sprint status YAML to {status_file}</action>
-<action>CRITICAL: For story_location field, write the variable value EXACTLY as defined in workflow.yaml: "{project-root}/docs/stories"</action>
-<action>CRITICAL: Do NOT resolve {project-root} to an absolute path - keep it as the literal string "{project-root}/docs/stories"</action>
 <action>CRITICAL: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing</action>
 <action>Ensure all items are ordered: epic, its stories, its retrospective, next epic...</action>
 </step>
@@ -150,10 +148,10 @@ development_status:
 <step n="5" goal="Validate and report">
 <action>Perform validation checks:</action>
 
-- [ ] Every epic in epic files appears in sprint-status.yaml
+- [ ] Every epic in epic files appears in {status_file}
-- [ ] Every story in epic files appears in sprint-status.yaml
+- [ ] Every story in epic files appears in {status_file}
 - [ ] Every epic has a corresponding retrospective entry
-- [ ] No items in sprint-status.yaml that don't exist in epic files
+- [ ] No items in {status_file} that don't exist in epic files
 - [ ] All status values are legal (match state machine definitions)
 - [ ] File is valid YAML syntax
 
@@ -178,7 +176,7 @@ development_status:
 
 **Next Steps:**
 
-1. Review the generated sprint-status.yaml
+1. Review the generated {status_file}
 2. Use this file to track development progress
 3. Agents will update statuses as they work
 4. Re-run this workflow to refresh auto-detected statuses
@@ -229,10 +227,3 @@ optional ↔ completed
 3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows
 4. **Review Before Done**: Stories should pass through `review` before `done`
 5. **Learning Transfer**: SM typically drafts next story after previous one is `done` to incorporate learnings
-
-### Error Handling
-
-- If epic file can't be parsed, report specific file and continue with others
-- If existing status file is malformed, backup and regenerate
-- Log warnings for duplicate story IDs across epics
-- Validate status transitions are legal (can't go from `backlog` to `done`)

src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -32,7 +32,7 @@ variables:
   epics_pattern: "epic*.md" # Pattern to find epic files
 
   # Output configuration
-  status_file: "{output_folder}/sprint-status.yaml"
+  status_file: "{ephemeral_files}/sprint-status.yaml"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version

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

@@ -6,7 +6,7 @@
 <critical>Communicate all responses in {communication_language}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow assembles a Story Context file for a single drafted story by extracting acceptance criteria, tasks, relevant docs/code, interfaces, constraints, and testing guidance.</critical>
-<critical>If story_path is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT.</critical>
+<critical>If {story_path} is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT.</critical>
 <critical>Check if context file already exists. If it does, ask user if they want to replace it, verify it, or cancel.</critical>
 
 <critical>DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only.</critical>
@@ -63,18 +63,17 @@
 
       <check if="no story with status 'drafted' found">
         <output>📋 No drafted stories found in sprint-status.yaml
+          All stories are either still in backlog or already marked ready/in-progress/done.
 
-All stories are either still in backlog or already marked ready/in-progress/done.
+          **Next Steps:**
-
+          1. Run `create-story` to draft more stories
-**Next Steps:**
+          2. Run `sprint-planning` to refresh story tracking
-1. Run `create-story` to draft more stories
-2. Run `sprint-planning` to refresh story tracking
         </output>
         <action>HALT</action>
       </check>
 
       <action>Use the first drafted story found</action>
-      <action>Find matching story file in {{story_dir}} using story_key pattern</action>
+      <action>Find matching story file in {{story_path}} using story_key pattern</action>
       <action>Read the COMPLETE story file</action>
     </check>
 

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

@@ -9,9 +9,10 @@ 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"
-story_path: "{config_source}:dev_ephemeral_location"
+story_path: "{config_source}:dev_ephemeral_location/stories"
 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_folder}/bmm/workflows/4-implementation/story-context"
@@ -19,11 +20,6 @@ template: "{installed_path}/context-template.xml"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
-# Variables and inputs
-variables:
-  story_path: "" # Optional: Explicit story path. If not provided, finds first story with status "drafted"
-  story_dir: "{config_source}:dev_ephemeral_location"
-
 # 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
@@ -31,29 +27,24 @@ 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"
 
 # Output configuration
 # Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
-default_output_file: "{story_dir}/{{story_key}}.context.xml"
+default_output_file: "{story_path}/{{story_key}}.context.xml"
 
 standalone: true
 

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

@@ -9,6 +9,7 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
+sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-done"
@@ -16,8 +17,7 @@ instructions: "{installed_path}/instructions.md"
 
 # Variables and inputs
 variables:
-  story_path: "" # Explicit path to story file
+  story_dir: "{config_source}:dev_ephemeral_location/stories" # Directory where stories are stored
-  story_dir: "{config_source}:dev_ephemeral_location" # Directory where stories are stored
 
 # Output configuration - no output file, just status updates
 default_output_file: ""

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

@@ -9,6 +9,7 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
+sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-ready"
@@ -16,8 +17,7 @@ instructions: "{installed_path}/instructions.md"
 
 # Variables and inputs
 variables:
-  story_path: "" # Explicit path to story file
+  story_dir: "{config_source}:dev_ephemeral_location/stories" # Directory where stories are stored
-  story_dir: "{config_source}:dev_ephemeral_location" # Directory where stories are stored
 
 # Output configuration - no output file, just status updates
 default_output_file: ""

src/modules/bmm/workflows/workflow-status/init/instructions.md

@@ -25,9 +25,10 @@
 
 **Check for implementation artifacts:**
 
-- Story files: {output_folder}/stories/\*.md
+- The following could be in or nested under {output_folder} OR {ephemeral_location} - CHECK BOTH LOCATIONS
-- Sprint status: {output*folder}/\_sprint*.yaml or {output_folder}/sprint-status.yaml
+  - Story files: {output*folder}/stories/*.md or {ephemeral*location}/stories/*.md
-- Existing workflow status: {output_folder}/bmm-workflow-status.yaml
+  - Sprint status: {output_folder}/sprint-status.yaml or {ephemeral_location}/sprint-status.yaml
+  - Existing workflow status: {output_folder}/bmm-workflow-status.yaml or {ephemeral_location}/bmm-workflow-status.yaml
 
 **Check for codebase:**
 

src/modules/bmm/workflows/workflow-status/init/workflow.yaml

@@ -6,6 +6,7 @@ author: "BMad"
 # Critical variables from config
 config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
+ephemeral_location: "{config_source}:dev_ephemeral_location"
 user_name: "{config_source}:user_name"
 project_name: "{config_source}:project_name"
 communication_language: "{config_source}:communication_language"