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

package/src/modules/bmgd/workflows/4-production/dev-story/workflow.yaml

@@ -9,14 +9,39 @@ 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_ephemeral_location"
-run_until_complete: "{config_source}:run_until_complete"
-run_tests_command: "{config_source}:run_tests_command"
+story_dir: "{config_source}:sprint_artifacts"
 date: system-generated
 
 story_file: "" # Explicit story path; auto-discovered if empty
 # Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.xml")
 context_file: "{story_dir}/{{story_key}}.context.xml"
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: Load necessary context for story implementation
+input_file_patterns:
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
+  tech_spec:
+    whole: "{output_folder}/tech-spec*.md"
+    sharded: "{sprint_artifacts}/tech-spec-epic-*.md"
+    load_strategy: "SELECTIVE_LOAD"
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/*.md"
+    load_strategy: "FULL_LOAD"
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+    load_strategy: "SELECTIVE_LOAD"
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+    load_strategy: "INDEX_GUIDED"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/dev-story"

package/src/modules/bmgd/workflows/4-production/epic-tech-context/instructions.md

@@ -7,43 +7,13 @@
 <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">
     <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>
@@ -81,10 +51,15 @@ No epics with status "backlog" found in sprint-status.yaml.
       </check>
     </check>
 
-    <action>Extract {{epic_title}} from PRD based on {{epic_id}}.</action>
     <action>Resolve output file path using workflow variables and initialize by writing the template.</action>
   </step>
 
+  <step n="1.5" goal="Discover and load project documents">
+    <invoke-protocol name="discover_inputs" />
+    <note>After discovery, these content variables are available: {prd_content}, {gdd_content}, {architecture_content}, {ux_design_content}, {epics_content} (will load only epic-{{epic_id}}.md if sharded), {document_project_content}</note>
+    <action>Extract {{epic_title}} from {prd_content} or {epics_content} based on {{epic_id}}.</action>
+  </step>
+
   <step n="2" goal="Validate epic exists in sprint status" tag="sprint-status">
     <action>Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1)</action>
     <action>Get current status value if epic exists</action>
@@ -160,7 +135,7 @@ Continuing to regenerate tech spec...
     <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>
+    <action>Load the FULL file: {sprint_status}</action>
     <action>Find development_status key "epic-{{epic_id}}"</action>
     <action>Verify current status is "backlog" (expected previous state)</action>
     <action>Update development_status["epic-{{epic_id}}"] = "contexted"</action>

package/src/modules/bmgd/workflows/4-production/epic-tech-context/workflow.yaml

@@ -8,15 +8,8 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
-
-# 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
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
@@ -24,27 +17,28 @@ recommended_inputs:
 input_file_patterns:
   prd:
     whole: "{output_folder}/*prd*.md"
-    sharded: "{output_folder}/*prd*/index.md"
-
+    sharded: "{output_folder}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
   gdd:
     whole: "{output_folder}/*gdd*.md"
-    sharded: "{output_folder}/*gdd*/index.md"
-
+    sharded: "{output_folder}/*gdd*/*.md"
+    load_strategy: "FULL_LOAD"
   architecture:
     whole: "{output_folder}/*architecture*.md"
-    sharded: "{output_folder}/*architecture*/index.md"
-
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
   ux_design:
     whole: "{output_folder}/*ux*.md"
-    sharded: "{output_folder}/*ux*/index.md"
-
+    sharded: "{output_folder}/*ux*/*.md"
+    load_strategy: "FULL_LOAD"
   epics:
     whole: "{output_folder}/*epic*.md"
     sharded_index: "{output_folder}/*epic*/index.md"
     sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
-
+    load_strategy: "SELECTIVE_LOAD"
   document_project:
-    sharded: "{output_folder}/docs/index.md"
+    sharded: "{output_folder}/index.md"
+    load_strategy: "INDEX_GUIDED"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/epic-tech-context"
@@ -53,8 +47,6 @@ instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
 # Output configuration
-default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
-
+default_output_file: "{sprint_artifacts}/tech-spec-epic-{{epic_id}}.md"
 standalone: true
-
 web_bundle: false

package/src/modules/bmgd/workflows/4-production/retrospective/instructions.md

@@ -6,7 +6,7 @@
 <critical>Generate all documents in {document_output_language}</critical>
 
 <critical>
-DOCUMENT OUTPUT: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content.
+  DOCUMENT OUTPUT: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content.
 
 FACILITATION NOTES:
 
@@ -26,29 +26,6 @@ PARTY MODE PROTOCOL:
 - Show disagreements, diverse perspectives, authentic team dynamics
   </critical>
 
-## 📚 Document Discovery - Selective Epic Loading
-
-**Strategy**: This workflow needs the completed epic, previous retrospective, and potentially architecture/PRD for context.
-
-**Epic Discovery (SELECTIVE LOAD):**
-
-1. Determine completed epic number (from sprint-status or user)
-2. If sharded: Load ONLY `epic-{epic_num}.md`
-3. If whole: Load complete epics file and extract relevant epic
-
-**Retrospective History:**
-
-1. Load previous epic's retrospective to check if lessons were applied
-2. Pattern: `retrospectives/epic-{prev_num}-retro-*.md`
-
-**Supporting Documents (Full Load if needed):**
-
-1. Architecture: Check for whole document first, then sharded index + all sections
-2. PRD: Same pattern as architecture
-3. These provide additional context for understanding epic execution
-
-**Priority**: Whole document first, then sharded version.
-
 <workflow>
 
 <step n="1" goal="Epic Discovery - Find Completed Epic with Priority Logic">
@@ -59,7 +36,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 +48,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 +69,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 +93,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}}")
@@ -179,6 +156,11 @@ Bob (Scrum Master): "Perfect. Epic {{epic_number}} is complete and ready for ret
 
 </step>
 
+<step n="0.5" goal="Discover and load project documents">
+  <invoke-protocol name="discover_inputs" />
+  <note>After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content}</note>
+</step>
+
 <step n="2" goal="Deep Story Analysis - Extract Lessons from Implementation">
 
 <output>
@@ -382,7 +364,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what
 <action>Attempt to load next epic using selective loading strategy:</action>
 
 **Try sharded first (more specific):**
-<action>Check if file exists: {output*folder}/\_epic*/epic-{{next_epic_num}}.md</action>
+<action>Check if file exists: {output_folder}/epic\*/epic-{{next_epic_num}}.md</action>
 
 <check if="sharded epic file found">
   <action>Load {output_folder}/*epic*/epic-{{next_epic_num}}.md</action>
@@ -391,7 +373,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what
 
 **Fallback to whole document:**
 <check if="sharded epic not found">
-<action>Check if file exists: {output*folder}/\_epic*.md</action>
+<action>Check if file exists: {output_folder}/epic\*.md</action>
 
   <check if="whole epic file found">
     <action>Load entire epics document</action>
@@ -1346,7 +1328,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 +1338,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 +1347,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>
 

package/src/modules/bmgd/workflows/4-production/retrospective/workflow.yaml

@@ -10,14 +10,12 @@ 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
+sprint_artifacts: "{config_source}:sprint_artifacts"
 
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/retrospective"
 template: false
 instructions: "{installed_path}/instructions.md"
 
-mode: interactive
-trigger: "Run AFTER completing an epic"
-
 required_inputs:
   - agent_manifest: "{project-root}/{bmad_folder}/_cfg/agent-manifest.csv"
 
@@ -29,45 +27,26 @@ input_file_patterns:
     whole: "{output_folder}/*epic*.md"
     sharded_index: "{output_folder}/*epic*/index.md"
     sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
-
+    load_strategy: "SELECTIVE_LOAD"
   previous_retrospective:
-    pattern: "{output_folder}/retrospectives/epic-{{prev_epic_num}}-retro-*.md"
-
+    pattern: "{sprint_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md"
+    load_strategy: "SELECTIVE_LOAD"
   architecture:
     whole: "{output_folder}/*architecture*.md"
-    sharded: "{output_folder}/*architecture*/index.md"
-
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
   prd:
     whole: "{output_folder}/*prd*.md"
-    sharded: "{output_folder}/*prd*/index.md"
-
+    sharded: "{output_folder}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
   document_project:
-    sharded: "{output_folder}/docs/index.md"
+    sharded: "{output_folder}/*.md"
+    load_strategy: "INDEX_GUIDED"
 
 # Required files
-sprint_status_file: "{output_folder}/sprint-status.yaml"
-story_directory: "{config_source}:dev_ephemeral_location"
-retrospectives_folder: "{output_folder}/retrospectives"
-
-output_artifacts:
-  - retrospective_summary: "Comprehensive review of what went well and what could improve"
-  - lessons_learned: "Key insights for future epics"
-  - action_items: "Specific improvements with ownership"
-  - next_epic_preparation: "Dependencies, gaps, and preparation tasks for next epic"
-  - critical_path: "Blockers or prerequisites that must be addressed"
-
-facilitation:
-  facilitator: "Bob (Scrum Master)"
-  tone: "Psychological safety - no blame, focus on systems and processes"
-  format: "Two-part: (1) Review completed epic + (2) Preview next epic preparation"
-
-validation_required:
-  - testing_complete: "Has full regression testing been completed?"
-  - deployment_status: "Has epic been deployed to production?"
-  - business_validation: "Have stakeholders reviewed and accepted deliverables?"
-  - technical_health: "Is codebase in stable, maintainable state?"
-  - blocker_resolution: "Any unresolved blockers that will impact next epic?"
+sprint_status_file: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+story_directory: "{sprint_artifacts}"
+retrospectives_folder: "{sprint_artifacts}"
 
 standalone: true
-
 web_bundle: false

package/src/modules/bmgd/workflows/4-production/sprint-planning/instructions.md

@@ -43,6 +43,11 @@
 <action>Build complete inventory of all epics and stories from all epic files</action>
 </step>
 
+  <step n="0.5" goal="Discover and load project documents">
+    <invoke-protocol name="discover_inputs" />
+    <note>After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy)</note>
+  </step>
+
 <step n="2" goal="Build sprint status structure">
 <action>For each epic found, create entries in this order:</action>
 
@@ -141,8 +146,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 +153,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 story in epic files appears in sprint-status.yaml
+- [ ] Every epic in epic files appears in {status_file}
+- [ ] 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 +181,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 +232,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`)

package/src/modules/bmgd/workflows/4-production/sprint-planning/sprint-status-template.yaml

@@ -38,7 +38,7 @@ generated: 05-06-2-2025 21:30
 project: My Awesome Project
 project_key: jira-1234
 tracking_system: file-system
-story_location: "{project-root}/docs/stories"
+story_location: "{story_location}"
 
 development_status:
   epic-1: contexted

package/src/modules/bmgd/workflows/4-production/sprint-planning/workflow.yaml

@@ -8,6 +8,7 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
+sprint_artifacts: "{config_source}:sprint_artifacts"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/sprint-planning"
@@ -19,19 +20,18 @@ validation: "{installed_path}/checklist.md"
 variables:
   # Project identification
   project_name: "{config_source}:project_name"
-  project_key: "{config_source}:project_name" # Future: Jira project key, Linear workspace ID, etc.
 
   # Tracking system configuration
   tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
-  story_location: "{project-root}/docs/stories" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
-  story_location_absolute: "{config_source}:dev_ephemeral_location" # Absolute path for file operations
+  story_location: "{config_source}:sprint_artifacts" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
+  story_location_absolute: "{config_source}:sprint_artifacts" # Absolute path for file operations
 
   # Source files (file-system only)
   epics_location: "{output_folder}" # Directory containing epic*.md files
   epics_pattern: "epic*.md" # Pattern to find epic files
 
   # Output configuration
-  status_file: "{output_folder}/sprint-status.yaml"
+  status_file: "{sprint_artifacts}/sprint-status.yaml"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
@@ -39,7 +39,8 @@ variables:
 input_file_patterns:
   epics:
     whole: "{output_folder}/*epic*.md"
-    sharded: "{output_folder}/*epic*/index.md"
+    sharded: "{output_folder}/*epic*/*.md"
+    load_strategy: "FULL_LOAD"
 
 # Output configuration
 default_output_file: "{status_file}"

package/src/modules/bmgd/workflows/4-production/story-context/instructions.md

@@ -6,40 +6,11 @@
 <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>
 
-## 📚 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 key - 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="Find drafted story and check for existing context" tag="sprint-status">
     <check if="{{story_path}} is provided">
@@ -63,18 +34,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
-2. Run `sprint-planning` to refresh story tracking
+          **Next Steps:**
+          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>
 
@@ -90,10 +60,10 @@ All stories are either still in backlog or already marked ready/in-progress/done
     <check if="context file already exists">
       <output>⚠️ Context file already exists: {default_output_file}
 
-**What would you like to do?**
-1. **Replace** - Generate new context file (overwrites existing)
-2. **Verify** - Validate existing context file
-3. **Cancel** - Exit without changes
+        **What would you like to do?**
+        1. **Replace** - Generate new context file (overwrites existing)
+        2. **Verify** - Validate existing context file
+        3. **Cancel** - Exit without changes
       </output>
       <ask>Choose action (replace/verify/cancel):</ask>
 
@@ -118,10 +88,15 @@ All stories are either still in backlog or already marked ready/in-progress/done
     <template-output file="{default_output_file}">so_that</template-output>
   </step>
 
+  <step n="1.5" goal="Discover and load project documents">
+    <invoke-protocol name="discover_inputs" />
+    <note>After discovery, these content variables are available: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {epics_content} (loads only epic for this story if sharded), {document_project_content}</note>
+  </step>
+
   <step n="2" goal="Collect relevant documentation">
-    <action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks.</action>
-    <action>Prefer authoritative sources: PRD, Tech-Spec, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
-    <action>Note: Tech-Spec is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance.</action>
+    <action>Review loaded content from Step 1.5 for items relevant to this story's domain (use keywords from story title, ACs, and tasks).</action>
+    <action>Extract relevant sections from: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {document_project_content}</action>
+    <action>Note: Tech-Spec ({tech_spec_content}) is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance.</action>
     <action>For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md").</action>
     <template-output file="{default_output_file}">
       Add artifacts.docs entries with {path, title, section, snippet}: