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

package/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md

@@ -6,47 +6,53 @@
 
 <workflow>
 
-<step n="0" goal="Initialize and understand project context">
-<invoke-workflow path="{workflow_status_workflow}">
-  <param>mode: data</param>
-  <param>data_request: project_config</param>
-</invoke-workflow>
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
+
+<check if="status file not found">
+  <output>No workflow status file found. Implementation Ready Check can run standalone or as part of BMM workflow path.</output>
+  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
+  <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
+  <check if="continue">
+    <action>Set standalone_mode = true</action>
+  </check>
+  <check if="exit">
+    <action>Exit workflow</action>
+  </check>
+</check>
 
-<check if="status_exists == false">
-  <output>**Note: No Workflow Status File Found**
+<check if="status file found">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "solutioning-gate-check" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
-The Implementation Ready Check can run standalone or as part of the BMM workflow path.
+<action>Based on the project_level, understand what artifacts should exist: - Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning) - Level 2: PRD, tech spec, epics/stories (no separate architecture doc) - Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
+</action>
 
-**Recommended:** Run `workflow-init` first for:
+  <check if="solutioning-gate-check status is file path (already completed)">
+    <output>⚠️ Gate check already completed: {{solutioning-gate-check status}}</output>
+    <ask>Re-running will create a new validation report. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
 
-- Project context tracking
-- Workflow sequencing guidance
-- Progress monitoring across workflows
+  <check if="solutioning-gate-check is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Gate check is out of sequence.</output>
+    <ask>Continue with gate check anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
 
-**Or continue standalone** without progress tracking.
-</output>
-<ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
-<check if="continue">
-<action>Set standalone_mode = true</action>
+<action>Set standalone_mode = false</action>
 </check>
-<check if="exit">
-<action>Exit workflow</action>
-</check>
-</check>
-
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Store {{project_level}}, {{active_path}}, and {{workflow_phase}} for validation context</action>
-
-<action>Based on the project_level, understand what artifacts should exist:
-
-- Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning)
-- Level 2: PRD, tech spec, epics/stories (no separate architecture doc)
-- Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
-  </action>
 
 <critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
-</check>
 
 <template-output>project_context</template-output>
 </step>
@@ -249,23 +255,48 @@ The Implementation Ready Check can run standalone or as part of the BMM workflow
 <template-output>readiness_assessment</template-output>
 </step>
 
-<step n="7" goal="Workflow status update offer" optional="true">
-<ask>The readiness assessment is complete. Would you like to update the workflow status to proceed to the next phase? [yes/no]
+<step n="7" goal="Update status and complete" tag="workflow-status">
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "solutioning-gate-check"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["solutioning-gate-check"] = "{output_folder}/bmm-readiness-assessment-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-Note: This will advance the project workflow to the next phase in your current path.</ask>
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
+</check>
 
-<action if="user_response == 'yes'">
-Determine the next workflow phase based on current status:
-- If Level 0-1: Advance to implementation phase
-- If Level 2-4 in solutioning: Advance to Phase 4 (Implementation)
-- Update the workflow status configuration accordingly
-- Confirm the update with the user
-</action>
+<output>**✅ Implementation Ready Check Complete!**
 
-<action if="user_response == 'no'">
-Acknowledge that the workflow status remains unchanged.
-Remind user they can manually update when ready.
-</action>
+**Assessment Report:**
+
+- Readiness assessment saved to: {output_folder}/bmm-readiness-assessment-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: solutioning-gate-check marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- Review the assessment report and address any critical issues before proceeding
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
 
 <template-output>status_update_result</template-output>
 </step>

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

@@ -1,129 +1,146 @@
----
-last-redoc-date: 2025-10-01
----
-
 # Create Story Workflow
 
-The create-story workflow is the entry point for v6's just-in-time story generation approach, run exclusively by the Scrum Master (SM) agent. Unlike batch processing methodologies, this workflow generates exactly ONE story at a time based on the current epic backlog state, ensuring stories are created only when needed and with the most current context. The SM analyzes the epic's progress, identifies what needs to be built next based on epics.md enumeration, and generates a complete story specification including acceptance criteria, technical approach, and implementation guidance pulled directly from tech specs, PRD, and architecture documentation.
+Just-in-time story generation creating one story at a time based on epic backlog state. Run by Scrum Master (SM) agent to ensure planned stories align with approved epics.
 
-This workflow represents a fundamental shift from traditional upfront planning to adaptive story generation. By creating stories one at a time and enforcing strict verification against epics.md, the SM ensures that only planned and approved stories are created. The workflow operates in non-interactive "#yolo" mode by default, minimizing prompts while maintaining quality through rigorous source document grounding. It will HALT if epics.md doesn't explicitly enumerate the next story, forcing proper planning through the correct-course workflow rather than allowing ad-hoc story creation.
+## Table of Contents
 
-The workflow's intelligent document discovery system automatically finds the relevant tech spec for the current epic (using pattern `tech-spec-epic-{epic_num}-*.md`), loads all architecture documents from both docs/ and output folders, and synthesizes requirements from multiple sources in priority order. After story creation, it can optionally trigger the story-context workflow to generate just-in-time technical expertise for the developer.
+- [Usage](#usage)
+- [Key Features](#key-features)
+- [Inputs & Outputs](#inputs--outputs)
+- [Workflow Behavior](#workflow-behavior)
+- [Integration](#integration)
 
 ## Usage
 
 ```bash
-# SM initiates story creation for the next piece of work
+# SM initiates next story creation
 bmad sm *create-story
 ```
 
-The SM runs this workflow when:
+**When to run:**
+
+- Sprint has capacity for new work
+- Previous story is Done/Approved
+- Team ready for next planned story
 
-- The current sprint has capacity for new work
-- The previous story status is "Done" or "Approved"
-- The team is ready for the next planned story in the epic
-- Story preparation is needed before development
+## Key Features
 
-## Inputs
+### Strict Planning Enforcement
 
-**Required Context Files:**
+- **Only creates stories enumerated in epics.md**
+- Halts if story not found in epic plan
+- Prevents scope creep through validation
 
-- **epics.md**: MANDATORY - Must explicitly enumerate the next story or workflow halts
-- **tech-spec-epic-{N}-\*.md**: Epic-specific technical specification (auto-discovered)
-- **PRD.md**: Product requirements document (fallback for requirements)
-- **Architecture Documents**: Automatically discovered from docs/ and output folders:
-  - 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
+### Intelligent Document Discovery
 
-**Workflow Variables:**
+- Auto-finds tech spec: `tech-spec-epic-{N}-*.md`
+- Discovers architecture docs across directories
+- Builds prioritized requirement sources
 
-- `story_dir`: From config `dev_story_location` - where stories are saved
-- `epic_num`: Current epic number (auto-detected from existing stories)
-- `story_num`: Next story number (incremented from last completed story)
-- `auto_run_context`: Default true - runs story-context workflow after creation
-- `non_interactive`: Default true - operates in "#yolo" mode with minimal prompts
+### Source Document Grounding
 
-## Outputs
+- Every requirement traced to source
+- No invention of domain facts
+- Citations included in output
 
-**Primary Deliverable:**
+### Non-Interactive Mode
 
-- **Story Document** (`{story_dir}/story-{epic_num}.{story_num}.md`): Complete story specification including:
-  - User story statement (role, action, benefit)
-  - Acceptance criteria extracted from tech spec or epics.md
-  - Tasks and subtasks mapped to ACs
-  - Testing requirements per testing strategy
-  - Dev notes with source citations
-  - Status: "Draft" (requires approval before development)
+- Default "#yolo" mode minimizes prompts
+- Smooth automated story preparation
+- Only prompts when critical
 
-**Validation Safeguards:**
+## Inputs & Outputs
 
-- **Epic Enumeration Check**: If epics.md doesn't list the next story, workflow HALTS with:
-  ```
-  "No planned next story found in epics.md for epic {epic_num}.
-  Please load either PM or SM agent and run *correct-course to add/modify epic stories."
-  ```
-- **Status Check**: Won't create new story if current story isn't Done/Approved
-- **Document Grounding**: All requirements traced to source documents (no invention)
+### Required Files
 
-## Key Features
+| File                     | Purpose                       | Priority |
+| ------------------------ | ----------------------------- | -------- |
+| epics.md                 | Story enumeration (MANDATORY) | Critical |
+| tech-spec-epic-{N}-\*.md | Epic technical spec           | High     |
+| PRD.md                   | Product requirements          | Medium   |
+| Architecture docs        | Technical constraints         | Low      |
 
-**Strict Planning Enforcement**: The workflow will NOT create stories that aren't explicitly planned in epics.md. This prevents scope creep and ensures all work is properly approved through the planning process.
+### Auto-Discovered Docs
 
-**Intelligent Document Discovery**: Automatically finds the latest tech spec for the epic using glob patterns, discovers all architecture documents across multiple directories, and builds a prioritized document set for requirement extraction.
+- `tech-stack.md`, `unified-project-structure.md`
+- `testing-strategy.md`, `backend/frontend-architecture.md`
+- `data-models.md`, `database-schema.md`, `api-specs.md`
 
-**Source Document Grounding**: Every requirement, acceptance criterion, and technical constraint is traced to a specific source document. The workflow explicitly forbids inventing domain facts not present in source materials.
+### Output
 
-**Non-Interactive by Default**: Operates in "#yolo" mode to minimize interruptions, only prompting when absolutely necessary (like missing critical configuration). This enables smooth automated story preparation.
+**Story Document:** `{story_dir}/story-{epic}.{story}.md`
 
-**Automatic Context Generation**: When `auto_run_context` is true (default), automatically triggers the story-context workflow to generate developer expertise injection for the newly created story.
+- User story statement (role, action, benefit)
+- Acceptance criteria from tech spec/epics
+- Tasks mapped to ACs
+- Testing requirements
+- Dev notes with sources
+- Status: "Draft"
 
-## Integration with v6 Flow
+## Workflow Behavior
 
-The create-story workflow is step 1 in the v6 implementation cycle:
+### Story Number Management
 
-1. **SM: create-story** ← You are here
-2. SM: story-context (adds JIT technical expertise)
-3. DEV: dev-story (implements with generated context)
-4. DEV/SR: code-review (validates completion)
-5. If needed: correct-course (adjusts direction)
-6. After epic: retrospective (captures learnings)
+- Auto-detects next story number
+- No duplicates or skipped numbers
+- Maintains epic.story convention
 
-This workflow establishes the "what" that needs to be built, strictly based on planned epics. The story-context workflow will later add the "how" through just-in-time technical expertise injection.
+### Update vs Create
 
-## Document Priority Order
+- **If current story not Done:** Updates existing
+- **If current story Done:** Creates next (if planned)
 
-The workflow uses this priority for extracting requirements:
+### Validation Safeguards
 
-1. **tech_spec_file**: Epic-scoped technical specification (highest priority)
-2. **epics_file**: Acceptance criteria and story breakdown
-3. **prd_file**: Business requirements and constraints
-4. **Architecture docs**: Constraints, patterns, and technical guidance
+**No Story Found:**
 
-## Workflow Behavior
+```
+"No planned next story found in epics.md for epic {N}.
+Run *correct-course to add/modify epic stories."
+```
 
-**Story Number Management:**
+**Missing Config:**
+Ensure `dev_story_location` set in config.yaml
 
-- Automatically detects next story number from existing files
-- Won't skip numbers or create duplicates
-- Maintains epic.story numbering convention
+## Integration
 
-**Update vs Create:**
+### v6 Implementation Cycle
 
-- If latest story status != Done/Approved: Updates existing story
-- If latest story status == Done/Approved: Creates next story (if enumerated in epics.md)
+1. **create-story** ← Current step (defines "what")
+2. story-context (adds technical "how")
+3. dev-story (implementation)
+4. code-review (validation)
+5. correct-course (if needed)
+6. retrospective (after epic)
 
-**Epic Advancement:**
+### Document Priority
 
-- In non-interactive mode: Stays within current epic
-- Interactive mode: Can prompt for new epic number
+1. **tech_spec_file** - Epic-specific spec
+2. **epics_file** - Story breakdown
+3. **prd_file** - Business requirements
+4. **architecture_docs** - Technical guidance
 
-## Troubleshooting
+## Configuration
+
+```yaml
+# bmad/bmm/config.yaml
+dev_story_location: ./stories
+output_folder: ./output
 
-**"No planned next story found in epics.md"**: The next story isn't enumerated in epics.md. Run SM or PM agent's `*correct-course` to properly plan and add the story to the epic.
+# workflow.yaml defaults
+non_interactive: true
+auto_run_context: true
+```
+
+## Troubleshooting
 
-**Missing story_dir Configuration**: Ensure `dev_story_location` is set in bmad/bmm/config.yaml
+| Issue                   | Solution                                   |
+| ----------------------- | ------------------------------------------ |
+| "No planned next story" | Run `*correct-course` to add story to epic |
+| Missing story_dir       | Set `dev_story_location` in config         |
+| Tech spec not found     | Use naming: `tech-spec-epic-{N}-*.md`      |
+| No architecture docs    | Add docs to docs/ or output/ folder        |
 
-**Tech Spec Not Found**: The workflow looks for `tech-spec-epic-{N}-*.md` pattern. Ensure tech specs follow this naming convention.
+---
 
-**Architecture Documents Missing**: While not fatal, missing architecture docs reduce story context quality. Ensure key docs exist in docs/ or output folder.
+For workflow details, see [instructions.md](./instructions.md) and [checklist.md](./checklist.md).

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

@@ -234,6 +234,7 @@ You may need to run sprint-planning to refresh tracking, or manually set the sto
     <output>**✅ Story Created Successfully, {user_name}!**
 
 **Story Details:**
+
 - Story ID: {{story_id}}
 - Story Key: {{story_key}}
 - File: {{story_file}}
@@ -242,6 +243,7 @@ You may need to run sprint-planning to refresh tracking, or manually set the sto
 **⚠️ 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

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

@@ -178,12 +178,14 @@ You may need to run sprint-planning to refresh tracking.
     <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
@@ -191,6 +193,7 @@ You may need to run sprint-planning to refresh tracking.
 - 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