bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.2

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

@@ -1,31 +1,104 @@
 <!-- BMAD BMM Story Context Assembly Instructions (v6) -->
 
 ```xml
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>This workflow assembles a Story Context XML for a single user story by extracting ACs, tasks, relevant docs/code, interfaces, constraints, and testing guidance to support implementation.</critical>
-<critical>Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery fails, HALT and request 'story_path' or 'story_dir'.</critical>
+<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>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>
 
 <workflow>
-  <step n="1" goal="Locate story and initialize output">
-    <action>If {{story_path}} provided and valid → use it; else auto-discover from {{story_dir}}.</action>
-    <action>Auto-discovery: read {{story_dir}} (dev_story_location). If invalid/missing or contains no .md files, ASK for a story file path or directory to scan.</action>
-    <action>If a directory is provided, list markdown files named "story-*.md" recursively; sort by last modified time; display top {{story_selection_limit}} with index, filename, path, modified time.</action>
-    <ask optional="true" if="{{non_interactive}} == false">"Select a story (1-{{story_selection_limit}}) or enter a path:"</ask>
-    <action>If {{non_interactive}} == true: choose the most recently modified story automatically. If none found, HALT with a clear message to provide 'story_path' or 'story_dir'. Else resolve selection into {{story_path}} and READ COMPLETE file.</action>
-    <action>Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content; parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes.</action>
-    <action>Extract user story fields (asA, iWant, soThat).</action>
-    <action>Initialize output by writing template to {default_output_file}.</action>
+  <step n="1" goal="Find drafted story and check for existing context" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file and parse sections</action>
+      <action>Extract story_key from filename or story metadata</action>
+      <action>Verify Status is "drafted" - if not, HALT with message: "Story status must be 'drafted' to generate context"</action>
+    </check>
+
+    <check if="{{story_path}} is NOT provided">
+      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the development_status section completely</action>
+
+      <action>Find FIRST story (reading in order from top to bottom) where:
+        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+        - Status value equals "drafted"
+      </action>
+
+      <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.
+
+**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>Read the COMPLETE story file</action>
+    </check>
+
+    <action>Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content</action>
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes</action>
+    <action>Extract user story fields (asA, iWant, soThat)</action>
+    <template-output file="{default_output_file}">story_tasks</template-output>
+    <template-output file="{default_output_file}">acceptance_criteria</template-output>
+
+    <!-- Check if context file already exists -->
+    <action>Check if file exists at {default_output_file}</action>
+
+    <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
+      </output>
+      <ask>Choose action (replace/verify/cancel):</ask>
+
+      <check if="user chooses verify">
+        <action>GOTO validation_step</action>
+      </check>
+
+      <check if="user chooses cancel">
+        <action>HALT with message: "Context generation cancelled"</action>
+      </check>
+
+      <check if="user chooses replace">
+        <action>Continue to generate new context file</action>
+      </check>
+    </check>
+
+    <action>Store project root path for relative path conversion: extract from {project-root} variable</action>
+    <action>Define path normalization function: convert any absolute path to project-relative by removing project root prefix</action>
+    <action>Initialize output by writing template to {default_output_file}</action>
     <template-output file="{default_output_file}">as_a</template-output>
     <template-output file="{default_output_file}">i_want</template-output>
     <template-output file="{default_output_file}">so_that</template-output>
   </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>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, Architecture, Front-end Spec, Testing standards, module-specific docs.</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} (NO invention)
+      Add artifacts.docs entries with {path, title, section, snippet}:
+      - path: PROJECT-RELATIVE path only (strip {project-root} prefix)
+      - title: Document title
+      - section: Relevant section name
+      - snippet: Brief excerpt (2-3 sentences max, NO invention)
     </template-output>
   </step>
 
@@ -33,10 +106,24 @@
     <action>Search source tree for modules, files, and symbols matching story intent and AC keywords (controllers, services, components, tests).</action>
     <action>Identify existing interfaces/APIs the story should reuse rather than recreate.</action>
     <action>Extract development constraints from Dev Notes and architecture (patterns, layers, testing requirements).</action>
+    <action>For all discovered code artifacts: convert absolute paths to project-relative format (strip {project-root} prefix).</action>
     <template-output file="{default_output_file}">
-      Add artifacts.code entries with {path, kind, symbol, lines, reason}; include a brief reason explaining relevance to the story
-      Populate interfaces with any API/interface signatures that the developer must call (name, kind, signature, path)
-      Populate constraints with development rules extracted from Dev Notes and architecture (e.g., patterns, layers, testing requirements)
+      Add artifacts.code entries with {path, kind, symbol, lines, reason}:
+      - path: PROJECT-RELATIVE path only (e.g., "src/services/api.js" not full path)
+      - kind: file type (controller, service, component, test, etc.)
+      - symbol: function/class/interface name
+      - lines: line range if specific (e.g., "45-67")
+      - reason: brief explanation of relevance to this story
+
+      Populate interfaces with API/interface signatures:
+      - name: Interface or API name
+      - kind: REST endpoint, GraphQL, function signature, class interface
+      - signature: Full signature or endpoint definition
+      - path: PROJECT-RELATIVE path to definition
+
+      Populate constraints with development rules:
+      - Extract from Dev Notes and architecture
+      - Include: required patterns, layer restrictions, testing requirements, coding standards
     </template-output>
   </step>
 
@@ -62,14 +149,52 @@
   </step>
 
   <step n="6" goal="Validate and save">
-    <action>Validate output XML structure and content.</action>
-    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.md</invoke-task>
+    <anchor id="validation_step" />
+    <action>Validate output context file structure and content</action>
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
   </step>
 
-  <step n="7" goal="Update story status and context reference">
-    <action>Open {{story_path}}; if Status == 'Draft' then set to 'ContextReadyDraft'; otherwise leave unchanged.</action>
+  <step n="7" goal="Update story file and mark ready for dev" tag="sprint-status">
+    <action>Open {{story_path}}</action>
+    <action>Find the "Status:" line (usually at the top)</action>
+    <action>Update story file: Change Status to "ready-for-dev"</action>
     <action>Under 'Dev Agent Record' → 'Context Reference' (create if missing), add or update a list item for {default_output_file}.</action>
     <action>Save the story file.</action>
+
+    <!-- Update sprint status to mark ready-for-dev -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "drafted" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Story file updated, but could not update sprint-status: {{story_key}} not found
+
+You may need to run sprint-planning to refresh tracking.
+      </output>
+    </check>
+
+    <output>✅ Story context generated successfully, {user_name}!
+
+**Story Details:**
+- Story: {{epic_id}}.{{story_id}} - {{story_title}}
+- Story Key: {{story_key}}
+- Context File: {default_output_file}
+- Status: drafted → ready-for-dev
+
+**Context Includes:**
+- Documentation artifacts and references
+- Existing code and interfaces
+- Dependencies and frameworks
+- Testing standards and ideas
+- Development constraints
+
+**Next Steps:**
+1. Review the context file: {default_output_file}
+2. Run `dev-story` to implement the story
+3. Generate context for more drafted stories if needed
+    </output>
   </step>
 
 </workflow>

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

@@ -8,49 +8,25 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+story_path: "{config_source}:dev_story_location"
 date: system-generated
 
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/story-context"
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/story-context"
 template: "{installed_path}/context-template.xml"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
 variables:
-  story_path: "" # Explicit story path; auto-discovered if empty
-  auto_update_status: false
+  story_path: "" # Optional: Explicit story path. If not provided, finds first story with status "drafted"
   story_dir: "{config_source}:dev_story_location"
-  story_selection_limit: 10
-  tech_spec_search_dir: "{project-root}/docs"
-  tech_spec_glob_template: "tech-spec-epic-{{epic_id}}*.md"
-  non_interactive: true
 
 # Output configuration
-default_output_file: "{output_folder}/story-context-{{epic_id}}.{{story_id}}.xml"
+# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
+default_output_file: "{story_dir}/{{story_key}}.context.xml"
 
-# Recommended inputs
-recommended_inputs:
-  - story_markdown: "Path to a story markdown file to build context for"
+standalone: true
 
-# Required tools
-required_tools:
-  - list_files
-  - file_info
-  - read_file
-  - write_file
-  - create_directory
-  - glob
-  - search_repo
-  - parse_markdown
-
-tags:
-  - context
-  - story
-  - planning
-  - bmad-v6
-
-execution_hints:
-  interactive: false
-  autonomous: true
-  iterative: true
+web_bundle: false

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

@@ -0,0 +1,111 @@
+# Story Approved Workflow Instructions (DEV Agent)
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
+<critical>Workflow: Update story file status to Done</critical>
+
+<step n="1" goal="Find reviewed story to mark done" tag="sprint-status">
+
+<check if="{story_path} is provided">
+  <action>Use {story_path} directly</action>
+  <action>Read COMPLETE story file and parse sections</action>
+  <action>Extract story_key from filename or story metadata</action>
+  <action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done"</action>
+</check>
+
+<check if="{story_path} is NOT provided">
+  <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+  <action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+  <action>Read ALL lines from beginning to end - do not skip any content</action>
+  <action>Parse the development_status section completely</action>
+
+<action>Find FIRST story (reading in order from top to bottom) where: - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - Status value equals "review"
+</action>
+
+  <check if="no story with status 'review' found">
+    <output>📋 No stories with status "review" found
+
+All stories are either still in development or already done.
+
+**Next Steps:**
+
+1. Run `dev-story` to implement stories
+2. Run `code-review` if stories need review first
+3. Check sprint-status.yaml for current story states
+   </output>
+   <action>HALT</action>
+   </check>
+
+<action>Use the first reviewed story found</action>
+<action>Find matching story file in {story_dir} using story_key pattern</action>
+<action>Read the COMPLETE story file</action>
+</check>
+
+<action>Extract story_id and story_title from the story file</action>
+
+<action>Find the "Status:" line (usually at the top)</action>
+<action>Update story file: Change Status to "done"</action>
+
+<action>Add completion notes to Dev Agent Record section:</action>
+<action>Find "## Dev Agent Record" section and add:
+
+```
+### Completion Notes
+**Completed:** {date}
+**Definition of Done:** All acceptance criteria met, code reviewed, tests passing
+```
+
+</action>
+
+<action>Save the story file</action>
+</step>
+
+<step n="2" goal="Update sprint status to done" tag="sprint-status">
+<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+<action>Find development_status key matching {story_key}</action>
+<action>Verify current status is "review" (expected previous state)</action>
+<action>Update development_status[{story_key}] = "done"</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<check if="story key not found in file">
+  <output>⚠️ Story file updated, but could not update sprint-status: {story_key} not found
+
+Story is marked Done in file, but sprint-status.yaml may be out of sync.
+</output>
+</check>
+
+</step>
+
+<step n="3" goal="Confirm completion to user">
+
+<output>**Story Approved and Marked Done, {user_name}!**
+
+✅ Story file updated → Status: done
+✅ Sprint status updated: review → done
+
+**Completed Story:**
+
+- **ID:** {story_id}
+- **Key:** {story_key}
+- **Title:** {story_title}
+- **Completed:** {date}
+
+**Next Steps:**
+
+1. Continue with next story in your backlog
+   - Run `create-story` for next backlog story
+   - Or run `dev-story` if ready stories exist
+2. Check epic completion status
+   - Run `retrospective` workflow to check if epic is complete
+   - Epic retrospective will verify all stories are done
+     </output>
+
+</step>
+
+</workflow>
+```

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

@@ -0,0 +1,27 @@
+# Story Done Workflow (DEV Agent)
+name: story-done
+description: "Marks a story as done (DoD complete) and moves it from its current status → DONE in the status file. Advances the story queue. Simple status-update workflow with no searching required."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/story-done"
+instructions: "{installed_path}/instructions.md"
+
+# Variables and inputs
+variables:
+  story_path: "" # Explicit path to story file
+  story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
+
+# Output configuration - no output file, just status updates
+default_output_file: ""
+
+standalone: true
+
+web_bundle: false

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

@@ -0,0 +1,117 @@
+# Story Ready Workflow Instructions (SM Agent)
+
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<workflow>
+
+<critical>This workflow is run by SM agent AFTER user reviews a drafted story and confirms it's ready for development</critical>
+<critical>Simple workflow: Update story file status to Ready</critical>
+
+<step n="1" goal="Find drafted story to mark ready" tag="sprint-status">
+
+<action>If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_ready</action>
+
+<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<action>Read ALL lines from beginning to end - do not skip any content</action>
+<action>Parse the development_status section completely</action>
+
+<action>Find ALL stories (reading in order from top to bottom) where:
+
+- Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+- NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+- Status value equals "drafted"
+  </action>
+
+<action>Collect up to 10 drafted story keys in order (limit for display purposes)</action>
+<action>Count total drafted stories found</action>
+
+<check if="no drafted stories found">
+  <output>📋 No drafted stories found in sprint-status.yaml
+
+All stories are either still in backlog or already marked ready/in-progress/done.
+
+**Options:**
+
+1. Run `create-story` to draft more stories
+2. Run `sprint-planning` to refresh story tracking
+   </output>
+   <action>HALT</action>
+   </check>
+
+<action>Display available drafted stories:
+
+**Drafted Stories Available ({{drafted_count}} found):**
+
+{{list_of_drafted_story_keys}}
+
+</action>
+
+<ask if="{{non_interactive}} == false">Select the drafted story to mark as Ready (enter story key or number):</ask>
+<action if="{{non_interactive}} == true">Auto-select first story from the list</action>
+
+<action>Resolve selected story_key from user input or auto-selection</action>
+<action>Find matching story file in {{story_dir}} using story_key pattern</action>
+
+<anchor id="mark_ready" />
+
+<action>Read the story file from resolved path</action>
+<action>Extract story_id and story_title from the file</action>
+
+<action>Find the "Status:" line (usually at the top)</action>
+<action>Update story file: Change Status to "ready-for-dev"</action>
+<action>Save the story file</action>
+</step>
+
+<step n="2" goal="Update sprint status to ready-for-dev" tag="sprint-status">
+<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<action>Find development_status key matching {{story_key}}</action>
+<action>Verify current status is "drafted" (expected previous state)</action>
+<action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<check if="story key not found in file">
+  <output>⚠️ Story file updated, but could not update sprint-status: {{story_key}} not found
+
+You may need to run sprint-planning to refresh tracking.
+</output>
+</check>
+
+</step>
+
+<step n="3" goal="Confirm completion to user">
+
+<output>**Story Marked Ready for Development, {user_name}!**
+
+✅ Story file updated: `{{story_file}}` → Status: ready-for-dev
+✅ Sprint status updated: drafted → ready-for-dev
+
+**Story Details:**
+
+- **ID:** {{story_id}}
+- **Key:** {{story_key}}
+- **Title:** {{story_title}}
+- **File:** `{{story_file}}`
+- **Status:** ready-for-dev
+
+**Next Steps:**
+
+1. **Recommended:** Run `story-context` workflow to generate implementation context
+   - This creates a comprehensive context XML for the DEV agent
+   - Includes relevant architecture, dependencies, and existing code
+
+2. **Alternative:** Skip context generation and go directly to `dev-story` workflow
+   - Faster, but DEV agent will have less context
+   - Only recommended for simple, well-understood stories
+
+**To proceed:**
+
+- For context generation: Stay with SM agent and run `story-context` workflow
+- For direct implementation: Load DEV agent and run `dev-story` workflow
+
+</step>
+
+</workflow>

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

@@ -0,0 +1,27 @@
+# Story Ready Workflow (SM Agent)
+name: story-ready
+description: "Marks a drafted story as ready for development and moves it from TODO → IN PROGRESS in the status file. Simple status-update workflow with no searching required."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/story-ready"
+instructions: "{installed_path}/instructions.md"
+
+# Variables and inputs
+variables:
+  story_path: "" # Explicit path to story file
+  story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
+
+# Output configuration - no output file, just status updates
+default_output_file: ""
+
+standalone: true
+
+web_bundle: false