bmad-method 6.0.3 → 6.0.5-next.0

package/src/bmm/workflows/4-implementation/code-review/discover-inputs.md

@@ -0,0 +1,88 @@
+# Discover Inputs Protocol
+
+**Objective:** Intelligently load project files (whole or sharded) based on the workflow's Input Files configuration.
+
+**Prerequisite:** Only execute this protocol if the workflow defines an Input Files section. If no input file patterns are configured, skip this entirely.
+
+---
+
+## Step 1: Parse Input File Patterns
+
+- Read the Input Files table from the workflow configuration.
+- For each input group (prd, architecture, epics, ux, etc.), note the **load strategy** if specified.
+
+## Step 2: Load Files Using Smart Strategies
+
+For each pattern in the Input Files table, work through the following substeps in order:
+
+### 2a: Try Sharded Documents First
+
+If a sharded pattern exists for this input, determine the load strategy (defaults to **FULL_LOAD** if not specified), then apply the matching strategy:
+
+#### FULL_LOAD Strategy
+
+Load ALL files in the sharded directory. Use this for PRD, Architecture, UX, brownfield docs, or whenever the full picture is needed.
+
+1. Use the glob pattern to find ALL `.md` files (e.g., `{planning_artifacts}/*architecture*/*.md`).
+2. Load EVERY matching file completely.
+3. Concatenate content in logical order: `index.md` first if it exists, then alphabetical.
+4. Store the combined result in a variable named `{pattern_name_content}` (e.g., `{architecture_content}`).
+
+#### SELECTIVE_LOAD Strategy
+
+Load a specific shard using a template variable. Example: used for epics with `{{epic_num}}`.
+
+1. Check for template variables in the sharded pattern (e.g., `{{epic_num}}`).
+2. If the variable is undefined, ask the user for the value OR infer it from context.
+3. Resolve the template to a specific file path.
+4. Load that specific file.
+5. Store in variable: `{pattern_name_content}`.
+
+#### INDEX_GUIDED Strategy
+
+Load index.md, analyze the structure and description of each doc in the index, then intelligently load relevant docs.
+
+**DO NOT BE LAZY** -- use best judgment to load documents that might have relevant information, even if there is only a 5% chance of relevance.
+
+1. Load `index.md` from the sharded directory.
+2. Parse the table of contents, links, and section headers.
+3. Analyze the workflow's purpose and objective.
+4. Identify which linked/referenced documents are likely relevant.
+   - *Example:* If the workflow is about authentication and the index shows "Auth Overview", "Payment Setup", "Deployment" -- load the auth docs, consider deployment docs, skip payment.
+5. Load all identified relevant documents.
+6. Store combined content in variable: `{pattern_name_content}`.
+
+**When in doubt, LOAD IT** -- context is valuable, and being thorough is better than missing critical info.
+
+---
+
+After applying the matching strategy, mark the pattern as **RESOLVED** and move to the next pattern.
+
+### 2b: Try Whole Document if No Sharded Found
+
+If no sharded matches were found OR no sharded pattern exists for this input:
+
+1. Attempt a glob match on the "whole" pattern (e.g., `{planning_artifacts}/*prd*.md`).
+2. If matches are found, load ALL matching files completely (no offset/limit).
+3. Store content in variable: `{pattern_name_content}` (e.g., `{prd_content}`).
+4. Mark pattern as **RESOLVED** and move to the next pattern.
+
+### 2c: Handle Not Found
+
+If no matches were found for either sharded or whole patterns:
+
+1. Set `{pattern_name_content}` to empty string.
+2. Note in session: "No {pattern_name} files found" -- this is not an error, just unavailable. Offer the user a chance to provide the file.
+
+## Step 3: Report Discovery Results
+
+List all loaded content variables with file counts. Example:
+
+```
+OK Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ...
+OK Loaded {architecture_content} from 1 file: Architecture.md
+OK Loaded {epics_content} from selective load: epics/epic-3.md
+-- No ux_design files found
+```
+
+This gives the workflow transparency into what context is available.

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

@@ -0,0 +1,271 @@
+---
+name: code-review
+description: 'Perform adversarial code review finding specific issues. Use when the user says "run code review" or "review this code"'
+---
+
+# Code Review Workflow
+
+**Goal:** Perform adversarial code review finding specific issues.
+
+**Your Role:** Adversarial Code Reviewer.
+- YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing!
+- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
+- Generate all documents in {document_output_language}
+- Your purpose: Validate story file claims against actual implementation
+- Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?
+- Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews - YOU are so much better than the dev agent that wrote this slop
+- Read EVERY file in the File List - verify implementation against story requirements
+- Tasks marked complete but not done = CRITICAL finding
+- Acceptance Criteria not implemented = HIGH severity finding
+- Do not review files that are not part of the application's source code. Always exclude the `_bmad/` and `_bmad-output/` folders from the review. Always exclude IDE and CLI configuration folders like `.cursor/` and `.windsurf/` and `.claude/`
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/code-review`
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `validation` = `{installed_path}/checklist.md`
+
+### Input Files
+
+| Input | Description | Path Pattern(s) | Load Strategy |
+|-------|-------------|------------------|---------------|
+| architecture | System architecture for review context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD |
+| ux_design | UX design specification (if UI review) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | FULL_LOAD |
+| epics | Epic containing story being reviewed | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD |
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+<workflow>
+
+<step n="1" goal="Load story and discover changes">
+  <action>Use provided {{story_path}} or ask user which story file to review</action>
+  <action>Read COMPLETE story file</action>
+  <action>Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story
+    metadata</action>
+  <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log</action>
+
+  <!-- Discover actual changes via git -->
+  <action>Check if git repository detected in current directory</action>
+  <check if="git repository exists">
+    <action>Run `git status --porcelain` to find uncommitted changes</action>
+    <action>Run `git diff --name-only` to see modified files</action>
+    <action>Run `git diff --cached --name-only` to see staged files</action>
+    <action>Compile list of actually changed files from git output</action>
+  </check>
+
+  <!-- Cross-reference story File List vs git reality -->
+  <action>Compare story's Dev Agent Record → File List with actual git changes</action>
+  <action>Note discrepancies:
+    - Files in git but not in story File List
+    - Files in story File List but no git changes
+    - Missing documentation of what was actually changed
+  </action>
+
+  <action>Read fully and follow `{installed_path}/discover-inputs.md` to load all input files</action>
+  <action>Load {project_context} for coding standards (if exists)</action>
+</step>
+
+<step n="2" goal="Build review attack plan">
+  <action>Extract ALL Acceptance Criteria from story</action>
+  <action>Extract ALL Tasks/Subtasks with completion status ([x] vs [ ])</action>
+  <action>From Dev Agent Record → File List, compile list of claimed changes</action>
+
+  <action>Create review plan:
+    1. **AC Validation**: Verify each AC is actually implemented
+    2. **Task Audit**: Verify each [x] task is really done
+    3. **Code Quality**: Security, performance, maintainability
+    4. **Test Quality**: Real tests vs placeholder bullshit
+  </action>
+</step>
+
+<step n="3" goal="Execute adversarial review">
+  <critical>VALIDATE EVERY CLAIM - Check git reality vs story claims</critical>
+
+  <!-- Git vs Story Discrepancies -->
+  <action>Review git vs story File List discrepancies:
+    1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation)
+    2. **Story lists files but no git changes** → HIGH finding (false claims)
+    3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue)
+  </action>
+
+  <!-- Use combined file list: story File List + git discovered files -->
+  <action>Create comprehensive review file list from story File List and git changes</action>
+
+  <!-- AC Validation -->
+  <action>For EACH Acceptance Criterion:
+    1. Read the AC requirement
+    2. Search implementation files for evidence
+    3. Determine: IMPLEMENTED, PARTIAL, or MISSING
+    4. If MISSING/PARTIAL → HIGH SEVERITY finding
+  </action>
+
+  <!-- Task Completion Audit -->
+  <action>For EACH task marked [x]:
+    1. Read the task description
+    2. Search files for evidence it was actually done
+    3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding
+    4. Record specific proof (file:line)
+  </action>
+
+  <!-- Code Quality Deep Dive -->
+  <action>For EACH file in comprehensive review list:
+    1. **Security**: Look for injection risks, missing validation, auth issues
+    2. **Performance**: N+1 queries, inefficient loops, missing caching
+    3. **Error Handling**: Missing try/catch, poor error messages
+    4. **Code Quality**: Complex functions, magic numbers, poor naming
+    5. **Test Quality**: Are tests real assertions or placeholders?
+  </action>
+
+  <check if="total_issues_found lt 3">
+    <critical>NOT LOOKING HARD ENOUGH - Find more problems!</critical>
+    <action>Re-examine code for:
+      - Edge cases and null handling
+      - Architecture violations
+      - Documentation gaps
+      - Integration issues
+      - Dependency problems
+      - Git commit message quality (if applicable)
+    </action>
+    <action>Find at least 3 more specific, actionable issues</action>
+  </check>
+</step>
+
+<step n="4" goal="Present findings and fix them">
+  <action>Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)</action>
+  <action>Set {{fixed_count}} = 0</action>
+  <action>Set {{action_count}} = 0</action>
+
+  <output>**🔥 CODE REVIEW FINDINGS, {user_name}!**
+
+    **Story:** {{story_file}}
+    **Git vs Story Discrepancies:** {{git_discrepancy_count}} found
+    **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low
+
+    ## 🔴 CRITICAL ISSUES
+    - Tasks marked [x] but not actually implemented
+    - Acceptance Criteria not implemented
+    - Story claims files changed but no git evidence
+    - Security vulnerabilities
+
+    ## 🟡 MEDIUM ISSUES
+    - Files changed but not documented in story File List
+    - Uncommitted changes not tracked
+    - Performance problems
+    - Poor test coverage/quality
+    - Code maintainability issues
+
+    ## 🟢 LOW ISSUES
+    - Code style improvements
+    - Documentation gaps
+    - Git commit message quality
+  </output>
+
+  <ask>What should I do with these issues?
+
+    1. **Fix them automatically** - I'll update the code and tests
+    2. **Create action items** - Add to story Tasks/Subtasks for later
+    3. **Show me details** - Deep dive into specific issues
+
+    Choose [1], [2], or specify which issue to examine:</ask>
+
+  <check if="user chooses 1">
+    <action>Fix all HIGH and MEDIUM issues in the code</action>
+    <action>Add/update tests as needed</action>
+    <action>Update File List in story if files changed</action>
+    <action>Update story Dev Agent Record with fixes applied</action>
+    <action>Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed</action>
+    <action>Set {{action_count}} = 0</action>
+  </check>
+
+  <check if="user chooses 2">
+    <action>Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks</action>
+    <action>For each issue: `- [ ] [AI-Review][Severity] Description [file:line]`</action>
+    <action>Set {{action_count}} = number of action items created</action>
+    <action>Set {{fixed_count}} = 0</action>
+  </check>
+
+  <check if="user chooses 3">
+    <action>Show detailed explanation with code examples</action>
+    <action>Return to fix decision</action>
+  </check>
+</step>
+
+<step n="5" goal="Update story status and sync sprint tracking">
+  <!-- Determine new status based on review outcome -->
+  <check if="all HIGH and MEDIUM issues fixed AND all ACs implemented">
+    <action>Set {{new_status}} = "done"</action>
+    <action>Update story Status field to "done"</action>
+  </check>
+  <check if="HIGH or MEDIUM issues remain OR ACs not fully implemented">
+    <action>Set {{new_status}} = "in-progress"</action>
+    <action>Update story Status field to "in-progress"</action>
+  </check>
+  <action>Save story file</action>
+
+  <!-- Determine sprint tracking status -->
+  <check if="{sprint_status} file exists">
+    <action>Set {{current_sprint_status}} = "enabled"</action>
+  </check>
+  <check if="{sprint_status} file does NOT exist">
+    <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
+  </check>
+
+  <!-- Sync sprint-status.yaml when story status changes (only if sprint tracking enabled) -->
+  <check if="{{current_sprint_status}} != 'no-sprint-tracking'">
+    <action>Load the FULL file: {sprint_status}</action>
+    <action>Find development_status key matching {{story_key}}</action>
+
+    <check if="{{new_status}} == 'done'">
+      <action>Update development_status[{{story_key}}] = "done"</action>
+      <action>Update last_updated field to current date</action>
+      <action>Save file, preserving ALL comments and structure</action>
+      <output>✅ Sprint status synced: {{story_key}} → done</output>
+    </check>
+
+    <check if="{{new_status}} == 'in-progress'">
+      <action>Update development_status[{{story_key}}] = "in-progress"</action>
+      <action>Update last_updated field to current date</action>
+      <action>Save file, preserving ALL comments and structure</action>
+      <output>🔄 Sprint status synced: {{story_key}} → in-progress</output>
+    </check>
+
+    <check if="story key not found in sprint status">
+      <output>⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml</output>
+    </check>
+  </check>
+
+  <check if="{{current_sprint_status}} == 'no-sprint-tracking'">
+    <output>ℹ️ Story status updated (no sprint tracking configured)</output>
+  </check>
+
+  <output>**✅ Review Complete!**
+
+    **Story Status:** {{new_status}}
+    **Issues Fixed:** {{fixed_count}}
+    **Action Items Created:** {{action_count}}
+
+    {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}}
+  </output>
+</step>
+
+</workflow>

package/src/bmm/workflows/4-implementation/correct-course/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+canonicalId: bmad-correct-course
+type: workflow
+description: "Manage significant changes during sprint execution"

package/src/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/bmm/workflows/4-implementation/correct-course/workflow.md</critical>
 <critical>Work through each section systematically with the user, recording findings and impacts</critical>
 
 <checklist>

package/src/bmm/workflows/4-implementation/correct-course/{instructions.md → workflow.md}

@@ -1,11 +1,83 @@
-# Correct Course - Sprint Change Management Instructions
+---
+name: correct-course
+description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"'
+---
 
-<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>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>
+# Correct Course - Sprint Change Management Workflow
 
-<critical>DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level ({user_skill_level}) affects conversation style ONLY, not document updates.</critical>
+**Goal:** Manage significant changes during sprint execution by analyzing impact across all project artifacts and producing a structured Sprint Change Proposal.
+
+**Your Role:** You are a Scrum Master navigating change management. Analyze the triggering issue, assess impact across PRD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `implementation_artifacts`
+- `planning_artifacts`
+- `project_knowledge`
+- `date` as system-generated current datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- Language MUST be tailored to `{user_skill_level}`
+- Generate all documents in `{document_output_language}`
+- DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level (`{user_skill_level}`) affects conversation style ONLY, not document updates.
+
+### Paths
+
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/correct-course`
+- `checklist` = `{installed_path}/checklist.md`
+- `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md`
+
+### Input Files
+
+| Input | Path | Load Strategy |
+|-------|------|---------------|
+| PRD | `{planning_artifacts}/*prd*.md` (whole) or `{planning_artifacts}/*prd*/*.md` (sharded) | FULL_LOAD |
+| Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/*epic*/*.md` (sharded) | FULL_LOAD |
+| Architecture | `{planning_artifacts}/*architecture*.md` (whole) or `{planning_artifacts}/*architecture*/*.md` (sharded) | FULL_LOAD |
+| UX Design | `{planning_artifacts}/*ux*.md` (whole) or `{planning_artifacts}/*ux*/*.md` (sharded) | FULL_LOAD |
+| Tech Spec | `{planning_artifacts}/*tech-spec*.md` (whole) | FULL_LOAD |
+| Document Project | `{project_knowledge}/index.md` (sharded) | INDEX_GUIDED |
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+### Document Discovery - Loading Project Artifacts
+
+**Strategy**: Course correction needs broad project context to assess change impact accurately. Load all available planning artifacts.
+
+**Discovery Process for FULL_LOAD documents (PRD, Epics, Architecture, UX Design, Tech Spec):**
+
+1. **Search for whole document first** - Look for files matching the whole-document pattern (e.g., `*prd*.md`, `*epic*.md`, `*architecture*.md`, `*ux*.md`, `*tech-spec*.md`)
+2. **Check for sharded version** - If whole document not found, look for a directory with `index.md` (e.g., `prd/index.md`, `epics/index.md`)
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Process the combined content as a single document
+4. **Priority**: If both whole and sharded versions exist, use the whole document
+
+**Discovery Process for INDEX_GUIDED documents (Document Project):**
+
+1. **Search for index file** - Look for `{project_knowledge}/index.md`
+2. **If found**: Read the index to understand available documentation sections
+3. **Selectively load sections** based on relevance to the change being analyzed — do NOT load everything, only sections that relate to the impacted areas
+4. **This document is optional** — skip if `{project_knowledge}` does not exist (greenfield projects)
+
+**Fuzzy matching**: Be flexible with document names — users may use variations like `prd.md`, `bmm-prd.md`, `product-requirements.md`, etc.
+
+**Missing documents**: Not all documents may exist. PRD and Epics are essential; Architecture, UX Design, Tech Spec, and Document Project are loaded if available. HALT if PRD or Epics cannot be found.
 
 <workflow>
 
@@ -28,11 +100,6 @@
 <action if="core documents are unavailable">HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</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: {prd_content}, {epics_content}, {architecture_content}, {ux_design_content}, {tech_spec_content}, {document_project_content}</note>
-</step>
-
 <step n="2" goal="Execute Change Analysis Checklist">
   <action>Read fully and follow the systematic analysis from: {checklist}</action>
   <action>Work through each checklist section interactively with the user</action>
@@ -200,7 +267,7 @@
 - Specific edit proposals with before/after
 - Implementation handoff plan
 
-<action>Report workflow completion to user with personalized message: "✅ Correct Course workflow complete, {user_name}!"</action>
+<action>Report workflow completion to user with personalized message: "Correct Course workflow complete, {user_name}!"</action>
 <action>Remind user of success criteria and next steps for implementation team</action>
 </step>
 

package/src/bmm/workflows/4-implementation/create-story/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+canonicalId: bmad-create-story
+type: workflow
+description: "Creates a dedicated story file with all the context needed for implementation"

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

@@ -33,25 +33,25 @@ This is a COMPETITION to create the **ULTIMATE story context** that makes LLM de
 
 ### **When Running from Create-Story Workflow:**
 
-- The `{project-root}/_bmad/core/tasks/workflow.xml` framework will automatically:
+- The workflow framework will automatically:
   - Load this checklist file
   - Load the newly created story file (`{story_file_path}`)
-  - Load workflow variables from `{installed_path}/workflow.yaml`
+  - Load workflow variables from `{installed_path}/workflow.md`
   - Execute the validation process
 
 ### **When Running in Fresh Context:**
 
 - User should provide the story file path being reviewed
 - Load the story file directly
-- Load the corresponding workflow.yaml for variable context
+- Load the corresponding workflow.md for variable context
 - Proceed with systematic analysis
 
 ### **Required Inputs:**
 
 - **Story file**: The story file to review and improve
-- **Workflow variables**: From workflow.yaml (implementation_artifacts, epics_file, etc.)
+- **Workflow variables**: From workflow.md (implementation_artifacts, epics_file, etc.)
 - **Source documents**: Epics, architecture, etc. (discovered or provided)
-- **Validation framework**: `validate-workflow.xml` (handles checklist execution)
+- **Validation framework**: The workflow's checklist execution system
 
 ---
 
@@ -61,12 +61,11 @@ You will systematically re-do the entire story creation process, but with a crit
 
 ### **Step 1: Load and Understand the Target**
 
-1. **Load the workflow configuration**: `{installed_path}/workflow.yaml` for variable inclusion
+1. **Load the workflow configuration**: `{installed_path}/workflow.md` for variable inclusion
 2. **Load the story file**: `{story_file_path}` (provided by user or discovered)
-3. **Load validation framework**: `{project-root}/_bmad/core/tasks/workflow.xml`
-4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
-5. **Resolve all workflow variables**: implementation_artifacts, epics_file, architecture_file, etc.
-6. **Understand current status**: What story implementation guidance is currently provided?
+3. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
+4. **Resolve all workflow variables**: implementation_artifacts, epics_file, architecture_file, etc.
+5. **Understand current status**: What story implementation guidance is currently provided?
 
 **Note:** If running in fresh context, user should provide the story file path being reviewed. If running from create-story workflow, the validation framework will automatically discover the checklist and story file.
 

package/src/bmm/workflows/4-implementation/create-story/discover-inputs.md

@@ -0,0 +1,88 @@
+# Discover Inputs Protocol
+
+**Objective:** Intelligently load project files (whole or sharded) based on the workflow's Input Files configuration.
+
+**Prerequisite:** Only execute this protocol if the workflow defines an Input Files section. If no input file patterns are configured, skip this entirely.
+
+---
+
+## Step 1: Parse Input File Patterns
+
+- Read the Input Files table from the workflow configuration.
+- For each input group (prd, architecture, epics, ux, etc.), note the **load strategy** if specified.
+
+## Step 2: Load Files Using Smart Strategies
+
+For each pattern in the Input Files table, work through the following substeps in order:
+
+### 2a: Try Sharded Documents First
+
+If a sharded pattern exists for this input, determine the load strategy (defaults to **FULL_LOAD** if not specified), then apply the matching strategy:
+
+#### FULL_LOAD Strategy
+
+Load ALL files in the sharded directory. Use this for PRD, Architecture, UX, brownfield docs, or whenever the full picture is needed.
+
+1. Use the glob pattern to find ALL `.md` files (e.g., `{planning_artifacts}/*architecture*/*.md`).
+2. Load EVERY matching file completely.
+3. Concatenate content in logical order: `index.md` first if it exists, then alphabetical.
+4. Store the combined result in a variable named `{pattern_name_content}` (e.g., `{architecture_content}`).
+
+#### SELECTIVE_LOAD Strategy
+
+Load a specific shard using a template variable. Example: used for epics with `{{epic_num}}`.
+
+1. Check for template variables in the sharded pattern (e.g., `{{epic_num}}`).
+2. If the variable is undefined, ask the user for the value OR infer it from context.
+3. Resolve the template to a specific file path.
+4. Load that specific file.
+5. Store in variable: `{pattern_name_content}`.
+
+#### INDEX_GUIDED Strategy
+
+Load index.md, analyze the structure and description of each doc in the index, then intelligently load relevant docs.
+
+**DO NOT BE LAZY** -- use best judgment to load documents that might have relevant information, even if there is only a 5% chance of relevance.
+
+1. Load `index.md` from the sharded directory.
+2. Parse the table of contents, links, and section headers.
+3. Analyze the workflow's purpose and objective.
+4. Identify which linked/referenced documents are likely relevant.
+   - *Example:* If the workflow is about authentication and the index shows "Auth Overview", "Payment Setup", "Deployment" -- load the auth docs, consider deployment docs, skip payment.
+5. Load all identified relevant documents.
+6. Store combined content in variable: `{pattern_name_content}`.
+
+**When in doubt, LOAD IT** -- context is valuable, and being thorough is better than missing critical info.
+
+---
+
+After applying the matching strategy, mark the pattern as **RESOLVED** and move to the next pattern.
+
+### 2b: Try Whole Document if No Sharded Found
+
+If no sharded matches were found OR no sharded pattern exists for this input:
+
+1. Attempt a glob match on the "whole" pattern (e.g., `{planning_artifacts}/*prd*.md`).
+2. If matches are found, load ALL matching files completely (no offset/limit).
+3. Store content in variable: `{pattern_name_content}` (e.g., `{prd_content}`).
+4. Mark pattern as **RESOLVED** and move to the next pattern.
+
+### 2c: Handle Not Found
+
+If no matches were found for either sharded or whole patterns:
+
+1. Set `{pattern_name_content}` to empty string.
+2. Note in session: "No {pattern_name} files found" -- this is not an error, just unavailable. Offer the user a chance to provide the file.
+
+## Step 3: Report Discovery Results
+
+List all loaded content variables with file counts. Example:
+
+```
+OK Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ...
+OK Loaded {architecture_content} from 1 file: Architecture.md
+OK Loaded {epics_content} from selective load: epics/epic-3.md
+-- No ux_design files found
+```
+
+This gives the workflow transparency into what context is available.