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

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

@@ -1,55 +1,171 @@
 # Create Story - Workflow Instructions (Spec-compliant, non-interactive by default)
 
-```xml
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+````xml
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
-<critical>Default execution mode: #yolo (minimal prompts). Only elicit if absolutely required and {{non_interactive}} == false.</critical>
+<critical>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks.</critical>
 
 <workflow>
 
   <step n="1" goal="Load config and initialize">
-    <action>Resolve variables from config_source: story_dir (dev_story_location), output_folder, user_name, communication_language. If story_dir missing and {{non_interactive}} == false → ASK user to provide a stories directory and update variable. If {{non_interactive}} == true and missing, HALT with a clear message.</action>
+    <action>Resolve variables from config_source: story_dir (sprint_artifacts), 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, hla_file</action>
+    <action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns.</action>
   </step>
 
-  <step n="2" goal="Discover and load source documents">
+  <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}, {document_project_content}</note>
+  </step>
+
+  <step n="2" goal="Discover previous story context">
+    <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:
+      1. Load {{output_folder}}/sprint-status.yaml COMPLETELY
+      2. Find current {{story_key}} in development_status section
+      3. Identify the story entry IMMEDIATELY ABOVE current story (previous row in file order)
+      4. If previous story exists:
+         - Extract {{previous_story_key}}
+         - Check previous story status (done, in-progress, review, etc.)
+         - If status is "done", "review", or "in-progress" (has some completion):
+           * Construct path: {{story_dir}}/{{previous_story_key}}.md
+           * Load the COMPLETE previous story file
+           * Parse ALL sections comprehensively:
+
+             A) Dev Agent Record → Completion Notes List:
+                - New patterns/services created (to reuse, not recreate)
+                - Architectural deviations or decisions made
+                - Technical debt deferred to future stories
+                - Warnings or recommendations for next story
+                - Interfaces/methods created for reuse
+
+             B) Dev Agent Record → Debug Log References:
+                - Issues encountered and solutions
+                - Gotchas or unexpected challenges
+                - Workarounds applied
+
+             C) Dev Agent Record → File List:
+                - Files created (NEW) - understand new capabilities
+                - Files modified (MODIFIED) - track evolving components
+                - Files deleted (DELETED) - removed functionality
+
+             D) Dev Notes:
+                - Any "future story" notes or TODOs
+                - Patterns established
+                - Constraints discovered
+
+             E) Senior Developer Review (AI) section (if present):
+                - Review outcome (Approve/Changes Requested/Blocked)
+                - Unresolved action items (unchecked [ ] items)
+                - Key findings that might affect this story
+                - Architectural concerns raised
+
+             F) Senior Developer Review → Action Items (if present):
+                - Check for unchecked [ ] items still pending
+                - Note any systemic issues that apply to multiple stories
+
+             G) Review Follow-ups (AI) tasks (if present):
+                - Check for unchecked [ ] review tasks still pending
+                - Determine if they're epic-wide concerns
+
+             H) Story Status:
+                - If "review" or "in-progress" - incomplete, note what's pending
+                - If "done" - confirmed complete
+           * Store ALL findings as {{previous_story_learnings}} with structure:
+             - new_files: [list]
+             - modified_files: [list]
+             - new_services: [list with descriptions]
+             - architectural_decisions: [list]
+             - technical_debt: [list]
+             - warnings_for_next: [list]
+             - review_findings: [list if review exists]
+             - pending_items: [list of unchecked action items]
+         - If status is "backlog" or "drafted":
+           * Set {{previous_story_learnings}} = "Previous story not yet implemented"
+      5. If no previous story exists (first story in epic):
+         - Set {{previous_story_learnings}} = "First story in epic - no predecessor context"
+    </action>
+
     <action>If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time.</action>
-    <action>Build a prioritized document set for this epic:
+    <action>Build a prioritized document set for this epic - search and load from {input_file_patterns} list of potential locations:
       1) tech_spec_file (epic-scoped)
-      2) epics_file (acceptance criteria and breakdown)
-      3) prd_file (business requirements and constraints)
-      4) hla_file (architecture constraints)
-      5) Architecture docs under docs/ and output_folder/: tech-stack.md, unified-project-structure.md, coding-standards.md, testing-strategy.md, backend-architecture.md, frontend-architecture.md, data-models.md, database-schema.md, rest-api-spec.md, external-apis.md (include if present)
+      2) epics_file (acceptance criteria and breakdown) the specific epic the story will be part of
+      3) prd_file (business requirements and constraints) whole or sharded
+      4) architecture_file (architecture constraints) whole or sharded
     </action>
     <action>READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation.</action>
   </step>
 
-  <step n="3" goal="Determine target story (do not prompt in #yolo)">
-    <action>List existing story markdown files in {{story_dir}} matching pattern: "story-<epic>.<story>.md"</action>
-    <check>If none found → Set {{epic_num}}=1 and {{story_num}}=1</check>
-    <check>If files found → Parse epic_num and story_num; pick the highest pair</check>
-    <action>Open the latest story (if exists) and read Status</action>
-    <check>If Status != Done/Approved and {{non_interactive}} == true → TARGET the latest story for update (do not create a new one)</check>
-    <check>If Status == Done/Approved → Candidate next story is {{epic_num}}.{{story_num+1}}</check>
-    <action>If creating a new story candidate: VERIFY planning in {{epics_file}}. Confirm that epic {{epic_num}} explicitly enumerates a next story matching {{story_num+1}} (or an equivalent next planned story entry). If epics.md is missing or does not enumerate another story for this epic, HALT with message:</action>
-    <action>"No planned next story found in epics.md for epic {{epic_num}}. Please load either PM (Product Manager) agent at {project-root}/bmad/bmm/agents/pm.md or SM (Scrum Master) agent at {project-root}/bmad/bmm/agents/sm.md and run `*correct-course` to add/modify epic stories, then rerun create-story."</action>
-    <check>If verification passes → Set {{story_num}} = {{story_num}} + 1</check>
-    <ask optional="true" if="{{non_interactive}} == false">If starting a new epic and {{non_interactive}} == false, ASK for {{epic_num}} and reset {{story_num}} to 1. In {{non_interactive}} == true, do NOT auto-advance epic; stay within current epic and continue incrementing story_num.</ask>
+  <step n="3" goal="Find next backlog story to draft" tag="sprint-status">
+    <critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical>
+    <action>Read ALL lines from beginning to end - do not skip any content</action>
+    <action>Parse the development_status section completely to understand story order</action>
+
+    <action>Find the FIRST story (by 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 "backlog"
+    </action>
+
+    <check if="no backlog story found">
+      <output>📋 No backlog stories found in sprint-status.yaml
+
+        All stories are either already drafted or completed.
+
+        **Options:**
+        1. Run sprint-planning to refresh story tracking
+        2. Load PM agent and run correct-course to add more stories
+        3. Check if current sprint is complete
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <action>Extract from found story key (e.g., "1-2-user-authentication"):
+      - epic_num: first number before dash (e.g., "1")
+      - story_num: second number after first dash (e.g., "2")
+      - story_title: remainder after second dash (e.g., "user-authentication")
+    </action>
+    <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
+    <action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
+
+    <action>Verify story is enumerated in {{epics_file}}. If not found, HALT with message:</action>
+    <action>"Story {{story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story."</action>
+
+    <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>
+    </check>
   </step>
 
   <step n="4" goal="Extract requirements and derive story statement">
     <action>From tech_spec_file (preferred) or epics_file: extract epic {{epic_num}} title/summary, acceptance criteria for the next story, and any component references. If not present, fall back to PRD sections mapping to this epic/story.</action>
-    <action>From hla and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story.</action>
+    <action>From architecture and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story.</action>
     <action>Derive a clear user story statement (role, action, benefit) grounded strictly in the above sources. If ambiguous and {{non_interactive}} == false → ASK user to clarify. If {{non_interactive}} == true → generate the best grounded statement WITHOUT inventing domain facts.</action>
     <template-output file="{default_output_file}">requirements_context_summary</template-output>
   </step>
 
   <step n="5" goal="Project structure alignment and lessons learned">
-    <action>If a previous story exists, scan its "Dev Agent Record" for completion notes and known deviations; summarize any carry-overs relevant to this story.</action>
+    <action>Review {{previous_story_learnings}} and extract actionable intelligence:
+      - New patterns/services created → Note for reuse (DO NOT recreate)
+      - Architectural deviations → Understand and maintain consistency
+      - Technical debt items → Assess if this story should address them
+      - Files modified → Understand current state of evolving components
+      - Warnings/recommendations → Apply to this story's approach
+      - Review findings → Learn from issues found in previous story
+      - Pending action items → Determine if epic-wide concerns affect this story
+    </action>
+
     <action>If unified-project-structure.md present: align expected file paths, module names, and component locations; note any potential conflicts.</action>
+
+    <action>Cross-reference {{previous_story_learnings}}.new_files with project structure to understand where new capabilities are located.</action>
+
     <template-output file="{default_output_file}">structure_alignment_summary</template-output>
   </step>
 
@@ -67,15 +183,74 @@
     <template-output file="{default_output_file}">story_header</template-output>
     <template-output file="{default_output_file}">story_body</template-output>
     <template-output file="{default_output_file}">dev_notes_with_citations</template-output>
+
+    <action>If {{previous_story_learnings}} contains actionable items (not "First story" or "not yet implemented"):
+      - Add "Learnings from Previous Story" subsection to Dev Notes
+      - Include relevant completion notes, new files/patterns, deviations
+      - Cite previous story file as reference [Source: stories/{{previous_story_key}}.md]
+      - Highlight interfaces/services to REUSE (not recreate)
+      - Note any technical debt to address in this story
+      - List pending review items that affect this story (if any)
+      - Reference specific files created: "Use {{file_path}} for {{purpose}}"
+      - Format example:
+        ```
+        ### Learnings from Previous Story
+
+        **From Story {{previous_story_key}} (Status: {{previous_status}})**
+
+        - **New Service Created**: `AuthService` base class available at `src/services/AuthService.js` - use `AuthService.register()` method
+        - **Architectural Change**: Switched from session-based to JWT authentication
+        - **Schema Changes**: User model now includes `passwordHash` field, migration applied
+        - **Technical Debt**: Email verification skipped, should be included in this or subsequent story
+        - **Testing Setup**: Auth test suite initialized at `tests/integration/auth.test.js` - follow patterns established there
+        - **Pending Review Items**: Rate limiting mentioned in review - consider for this story
+
+        [Source: stories/{{previous_story_key}}.md#Dev-Agent-Record]
+        ```
+    </action>
+
     <template-output file="{default_output_file}">change_log</template-output>
   </step>
 
-  <step n="8" goal="Validate, save, and optionally generate context">
-    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.md</invoke-task>
+  <step n="8" goal="Validate, save, and mark story drafted" tag="sprint-status">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml</invoke-task>
     <action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
-    <check>If {{auto_run_context}} == true → <invoke-workflow path="{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml">Pass {{story_path}} = {default_output_file}</invoke-workflow></check>
+
+    <!-- Mark story as drafted in sprint status -->
+    <action>Update {{output_folder}}/sprint-status.yaml</action>
+    <action>Load the FULL file and read all development_status entries</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "backlog" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "drafted"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Could not update story status: {{story_key}} not found in sprint-status.yaml
+
+Story file was created successfully, but sprint-status.yaml was not updated.
+You may need to run sprint-planning to refresh tracking, or manually set the story row status to `drafted`.
+      </output>
+    </check>
+
     <action>Report created/updated story path</action>
+    <output>**✅ Story Created Successfully, {user_name}!**
+
+**Story Details:**
+
+- Story ID: {{story_id}}
+- Story Key: {{story_key}}
+- File: {{story_file}}
+- Status: drafted (was backlog)
+
+**⚠️ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command.
+
+**Next Steps:**
+
+1. Review the drafted story in {{story_file}}
+2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step)
+3. Or run `story-ready` to manually mark the story ready without generating technical context
+    </output>
   </step>
 
 </workflow>
-```
+````

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

@@ -1,6 +1,6 @@
 # Story {{epic_num}}.{{story_num}}: {{story_title}}
 
-Status: Draft
+Status: drafted
 
 ## Story
 
@@ -34,17 +34,11 @@ so that {{benefit}}.
 
 - Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
 
-## Change Log
-
-| Date     | Version | Description   | Author        |
-| -------- | ------- | ------------- | ------------- |
-| {{date}} | 0.1     | Initial draft | {{user_name}} |
-
 ## Dev Agent Record
 
 ### Context Reference
 
-<!-- Path(s) to story context XML/JSON will be added here by context workflow -->
+<!-- Path(s) to story context XML will be added here by context workflow -->
 
 ### Agent Model Used
 

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

@@ -3,24 +3,26 @@ description: "Create the next user story markdown from epics/PRD and architectur
 author: "BMad"
 
 # Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
+sprint_artifacts: "{config_source}:sprint_artifacts"
+story_dir: "{sprint_artifacts}"
 
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/create-story"
+installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
 variables:
-  story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
+  sprint_status: "{sprint_artifacts}/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
-  hla_file: "{output_folder}/high-level-architecture.md" # Optional architecture context
+  prd_file: "{output_folder}/PRD.md" # Fallback for requirements
+  architecture_file: "{output_folder}/architecture.md" # Optional architecture context
   tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md
   tech_spec_search_dir: "{project-root}/docs"
   tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
@@ -28,45 +30,44 @@ variables:
     - "{project-root}/docs"
     - "{output_folder}"
   arch_docs_file_names: |
-    - 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
+    - *architecture*.md
   story_title: "" # Will be elicited if not derivable
-  epic_num: 1
-  story_num: 1
-  auto_run_context: true # Optionally run story-context after creation
-  non_interactive: true # Generate without elicitation; avoid interactive prompts
 
-# Output configuration
-default_output_file: "{story_dir}/story-{{epic_num}}.{{story_num}}.md"
+default_output_file: "{story_dir}/{{story_key}}.md"
 
-required_tools:
-  - list_files
-  - file_info
-  - read_file
-  - write_file
-  - create_directory
-  - search_repo
-  - glob
+# 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
+input_file_patterns:
+  prd:
+    description: "Product requirements (optional)"
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
+  tech_spec:
+    description: "Technical specification (Quick Flow track)"
+    whole: "{output_folder}/tech-spec.md"
+    load_strategy: "FULL_LOAD"
+  architecture:
+    description: "System architecture and decisions"
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
+  ux_design:
+    description: "UX design specification (if UI)"
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/*.md"
+    load_strategy: "FULL_LOAD"
+  epics:
+    description: "Epic containing this story"
+    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}/index.md"
+    load_strategy: "INDEX_GUIDED"
 
-recommended_inputs:
-  - epics: "Epic breakdown (epic-list.md)"
-  - prd: "PRD document"
-  - hla: "High-Level Architecture (optional)"
+standalone: true
 
-tags:
-  - story-generation
-  - planning
-  - bmad-v6
-
-execution_hints:
-  interactive: false
-  autonomous: true
-  iterative: true
+web_bundle: false

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

@@ -17,7 +17,7 @@ validation-rules:
 - [ ] All tasks and subtasks for this story are marked complete with [x]
 - [ ] Implementation aligns with every Acceptance Criterion in the story
 
-## Tests & Quality
+## Tests and Quality
 
 - [ ] Unit tests added/updated for core functionality changed by this story
 - [ ] Integration tests added/updated when component interactions are affected