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

package/src/modules/bmm/README.md

@@ -1,141 +1,144 @@
 # BMM - BMad Method Module
 
-The BMM (BMad Method Module) is the core orchestration system for the BMad Method, providing comprehensive software development lifecycle management through specialized agents, workflows, teams, and tasks.
+Core orchestration system for AI-driven agile development, providing comprehensive lifecycle management through specialized agents and workflows.
 
-## 📚 Essential Reading
+## Table of Contents
 
-**Before using BMM, you MUST read the [BMM v6 Workflows Guide](./workflows/README.md).** This document explains the revolutionary v6a workflow system and how all components work together.
+- [Essential Reading](#essential-reading)
+- [Module Structure](#module-structure)
+- [Quick Start](#quick-start)
+- [Key Concepts](#key-concepts)
+- [Scale Levels](#scale-levels)
+- [Story Lifecycle](#story-lifecycle)
+- [Best Practices](#best-practices)
+
+## Essential Reading
+
+**[📖 BMM v6 Workflows Guide](./workflows/README.md)** - Required reading before using BMM. Explains the revolutionary workflow system and component integration.
 
 ## Module Structure
 
-### 🤖 `/agents`
+### 🤖 Agents
 
-Specialized AI agents for different development roles:
+**Core Development Roles:**
 
-- **PM** (Product Manager) - Product planning and requirements
+- **PM** - Product Manager for planning and requirements
 - **Analyst** - Business analysis and research
 - **Architect** - Technical architecture and design
-- **SM** (Scrum Master) - Sprint and story management
-- **DEV** (Developer) - Code implementation
-- **TEA** (Test Architect) - Test Architect
+- **SM** - Scrum Master for sprint and story management
+- **DEV** - Developer for implementation
+- **TEA** - Test Architect for quality assurance
 - **UX** - User experience design
-- And more specialized roles
 
-**Game Development Agents** (Optional):
-During installation, you can optionally include game development specialists:
+**Game Development** (Optional):
 
-- **Game Designer** - Creative vision and game design documents (GDD)
+- **Game Designer** - Creative vision and GDD creation
 - **Game Developer** - Game-specific implementation
-- **Game Architect** - Game systems and technical infrastructure
+- **Game Architect** - Game systems and infrastructure
 
-These agents come with specialized workflows (`brainstorm-game`, `game-brief`, `gdd`) and are only installed if you select "Include Game Planning Agents and Workflows" during BMM installation.
+### 📋 Workflows
 
-### 📋 `/workflows`
+Four-phase methodology adapting to project complexity:
 
-The heart of BMM - structured workflows for the four development phases:
+**1. Analysis** (Optional)
 
-1. **Analysis Phase** (Optional)
-   - `brainstorm-project` - Project ideation
-   - `research` - Market/technical research
-   - `product-brief` - Product strategy
+- `brainstorm-project` - Project ideation
+- `research` - Market/technical research
+- `product-brief` - Product strategy
 
-2. **Planning Phase** (Required)
-   - `prd` - Scale-adaptive project planning
-   - Routes to appropriate documentation based on project complexity
+**2. Planning** (Required)
 
-3. **Solutioning Phase** (Level 3-4 projects)
-   - `3-solutioning` - Architecture design
-   - `tech-spec` - Epic-specific technical specifications
+- `prd` - Scale-adaptive planning
+- Routes to appropriate documentation level
 
-4. **Implementation Phase** (Iterative)
-   - `create-story` - Story drafting (SM agent)
-   - `story-ready` - Approve story for development (SM agent)
-   - `story-context` - Expertise injection (SM agent)
-   - `dev-story` - Implementation (DEV agent)
-   - `story-done` - Mark story done (DEV agent)
-   - `code-review` - Quality validation (DEV/SR agent)
-   - `correct-course` - Issue resolution
-   - `retrospective` - Continuous improvement
+**3. Solutioning** (Level 3-4)
 
-### 👥 `/teams`
+- `architecture` - System design
+- `tech-spec` - Epic technical specifications
 
-Pre-configured agent teams for different project types and phases. Teams coordinate multiple agents working together on complex tasks.
+**4. Implementation** (Iterative)
 
-### 📝 `/tasks`
+- `create-story` - Draft stories
+- `story-context` - Inject expertise
+- `dev-story` - Implement
+- `code-review` - Validate quality
 
-Reusable task definitions that agents execute within workflows. These are the atomic units of work that compose into larger workflows.
+### 👥 Teams
 
-### 🔧 `/sub-modules`
+Pre-configured agent groups for coordinated complex tasks.
 
-Extension modules that add specialized capabilities to BMM.
+### 📝 Tasks
 
-### 🏗️ `/testarch`
+Atomic work units composing into larger workflows.
 
-Test architecture and quality assurance components. The **[Test Architect (TEA) Guide](./testarch/README.md)** provides comprehensive testing strategy across 9 workflows: framework setup, CI/CD, test design, ATDD, automation, traceability, NFR assessment, quality gates, and test review.
+### 🏗️ Test Architecture
+
+**[TEA Guide](./testarch/README.md)** - Comprehensive testing strategy across 9 specialized workflows.
 
 ## Quick Start
 
-```bash
-# Load the PM agent - either via slash command or drag and drop or @ the agent file.
-# Once loaded, the agent should greet you and offer a menu of options. You can enter:
-`*prd`
-```
+1. **Load PM agent** in your IDE
+2. **Wait for menu** to appear
+3. **Run workflow:**
+   ```
+   *prd
+   ```
 
-## Key Concepts
+**IDE Instructions:**
 
-### Scale Levels
+- [Claude Code](../../docs/ide-info/claude-code.md)
+- [Cursor](../../docs/ide-info/cursor.md)
+- [VS Code](../../docs/ide-info/windsurf.md)
+- [Others](../../docs/ide-info/)
 
-BMM automatically adapts to project complexity:
+## Key Concepts
 
-- **Level 0**: Single atomic change
-- **Level 1**: 1-10 stories, minimal documentation
-- **Level 2**: 5-15 stories, focused PRD
-- **Level 3**: 12-40 stories, full architecture
-- **Level 4**: 40+ stories, enterprise scale
+### Scale Levels
 
-### Just-In-Time Design
+BMM automatically adapts complexity:
 
-Technical specifications are created one epic at a time during implementation, not all upfront, allowing for learning and adaptation.
+| Level | Stories       | Documentation     |
+| ----- | ------------- | ----------------- |
+| 0     | Single change | Minimal           |
+| 1     | 1-10          | Light PRD         |
+| 2     | 5-15          | Focused PRD       |
+| 3     | 12-40         | Full architecture |
+| 4     | 40+           | Enterprise scale  |
 
-### Story State Machine
+### Story Lifecycle
 
-Stories flow through a 4-state lifecycle tracked in the status file:
+Four-state machine tracked in status file:
 
 ```
 BACKLOG → TODO → IN PROGRESS → DONE
 ```
 
-- **BACKLOG**: Ordered list of stories to be drafted (populated at phase transition)
-- **TODO**: Single story ready for SM to draft (or drafted, awaiting approval)
-- **IN PROGRESS**: Single story approved for DEV to implement
-- **DONE**: Completed stories with dates and points
+- **BACKLOG** - Ordered stories to draft
+- **TODO** - Ready for SM drafting
+- **IN PROGRESS** - Approved for DEV
+- **DONE** - Completed with metrics
+
+### Just-In-Time Design
 
-Agents never search for "next story" - they always read the exact story from the status file. Simple workflows (`story-ready`, `story-done`) advance the queue automatically.
+Technical specifications created per epic during implementation, enabling learning and adaptation.
 
 ### Context Injection
 
-Story-specific technical guidance is generated dynamically, providing developers with exactly the expertise needed for each task.
-
-## Integration with BMad Core
+Dynamic technical guidance generated for each story, providing exact expertise when needed.
 
-BMM integrates seamlessly with the BMad Core framework, leveraging:
+## Best Practices
 
-- The agent execution engine
-- Workflow orchestration
-- Task management
-- Team coordination
+1. **Start with workflows** - Let process guide you
+2. **Respect scale** - Don't over-document small projects
+3. **Trust the process** - Methodology carefully designed
+4. **Use status file** - Single source of truth for stories
 
 ## Related Documentation
 
-- [BMM Workflows Guide](./workflows/README.md) - **Start here!**
-- [Test Architect (TEA) Guide](./testarch/README.md) - Quality assurance and testing strategy
-
-## Best Practices
-
-1. **Always start with the workflows** - Let workflows guide your process
-2. **Respect the scale** - Don't over-document small projects
-3. **Trust the process** - The methodology has been carefully designed
+- **[Workflows Guide](./workflows/README.md)** - Complete workflow reference
+- **[Test Architect Guide](./testarch/README.md)** - Testing strategy
+- **[IDE Setup](../../docs/ide-info/)** - Environment configuration
 
 ---
 
-For detailed information about the complete BMad Method workflow system, see the [BMM Workflows README](./workflows/README.md).
+For complete BMad Method workflow system details, see the [BMM Workflows README](./workflows/README.md).

package/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md

@@ -5,20 +5,20 @@
 
 <workflow>
 
-  <step n="1" goal="Validate workflow readiness">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-      <param>mode: validate</param>
-      <param>calling_workflow: brainstorm-game</param>
-    </invoke-workflow>
+  <step n="1" goal="Validate workflow readiness" tag="workflow-status">
+    <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-    <check if="status_exists == false">
-      <output>{{suggestion}}</output>
-      <output>Note: Game brainstorming is optional. Continuing without progress tracking.</output>
+    <check if="status file not found">
+      <output>No workflow status file found. Game brainstorming is optional - you can continue without status tracking.</output>
       <action>Set standalone_mode = true</action>
     </check>
 
-    <check if="status_exists == true">
-      <action>Store {{status_file_path}} for later updates</action>
+    <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 "brainstorm-game" workflow</action>
+      <action>Get project_level from YAML metadata</action>
+      <action>Find first non-completed workflow (next expected workflow)</action>
 
       <check if="project_type != 'game'">
         <output>Note: This is a {{project_type}} project. Game brainstorming is designed for game projects.</output>
@@ -28,10 +28,25 @@
         </check>
       </check>
 
-      <check if="warning != ''">
-        <output>{{warning}}</output>
-        <output>Note: Game brainstorming can be valuable at any project stage.</output>
+      <check if="brainstorm-game status is file path (already completed)">
+        <output>⚠️ Game brainstorming session already completed: {{brainstorm-game status}}</output>
+        <ask>Re-running will create a new session. Continue? (y/n)</ask>
+        <check if="n">
+          <output>Exiting. Use workflow-status to see your next step.</output>
+          <action>Exit workflow</action>
+        </check>
+      </check>
+
+      <check if="brainstorm-game is not the next expected workflow (latter items are completed already in the list)">
+        <output>⚠️ Next expected workflow: {{next_workflow}}. Game brainstorming is out of sequence.</output>
+        <ask>Continue with game brainstorming anyway? (y/n)</ask>
+        <check if="n">
+          <output>Exiting. Run {{next_workflow}} instead.</output>
+          <action>Exit workflow</action>
+        </check>
       </check>
+
+      <action>Set standalone_mode = false</action>
     </check>
 
   </step>
@@ -66,17 +81,16 @@
     </invoke-workflow>
   </step>
 
-  <step n="4" goal="Update status and complete">
+  <step n="4" goal="Update status and complete" tag="workflow-status">
     <check if="standalone_mode != true">
-      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-        <param>mode: update</param>
-        <param>action: complete_workflow</param>
-        <param>workflow_name: brainstorm-game</param>
-      </invoke-workflow>
-
-      <check if="success == true">
-        <output>Status updated! Next: {{next_workflow}}</output>
-      </check>
+      <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+      <action>Find workflow_status key "brainstorm-game"</action>
+      <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+      <action>Update workflow_status["brainstorm-game"] = "{output_folder}/bmm-brainstorming-session-{{date}}.md"</action>
+      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+      <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>
 
     <output>**✅ Game Brainstorming Session Complete, {user_name}!**
@@ -88,16 +102,21 @@
 {{#if standalone_mode != true}}
 **Status Updated:**
 
-- Progress tracking updated
+- Progress tracking updated: brainstorm-game marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
 
 **Next Steps:**
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** You can run other analysis workflows (research, game-brief) before proceeding
 
 Check status anytime with: `workflow-status`
 {{else}}
-**Next Steps:**
 Since no workflow is in progress:
 
 - Refer to the BMM workflow guide if unsure what to do next

package/src/modules/bmm/workflows/1-analysis/brainstorm-project/README.md

@@ -1,29 +1,113 @@
----
-last-redoc-date: 2025-10-01
----
-
 # Project Brainstorming Workflow
 
-This workflow facilitates structured ideation for non-game software projects through systematic exploration of problem spaces, architectures, and implementation strategies. Unlike traditional requirement gathering, it employs creative techniques to uncover non-obvious approaches and identify innovative solutions that address core business needs while considering technical constraints and organizational capabilities.
+Structured ideation for software projects exploring problem spaces, architectures, and innovative solutions beyond traditional requirements gathering.
+
+## Table of Contents
 
-The workflow operates through a project-specific context framework that captures business objectives, technical environment, stakeholder needs, and organizational constraints. It generates multiple solution vectors through parallel ideation tracks: architectural approaches, user experience paradigms, integration patterns, and value delivery mechanisms. Each track produces concrete proposals that are evaluated against feasibility, impact, and alignment with strategic objectives.
+- [Purpose](#purpose)
+- [Usage](#usage)
+- [Process](#process)
+- [Inputs & Outputs](#inputs--outputs)
+- [Integration](#integration)
 
-Critical differentiators include its focus on solution innovation rather than requirement enumeration, emphasis on technical-business alignment from inception, and structured approach to surfacing hidden assumptions. The workflow produces actionable outputs that directly feed into Product Brief development, ensuring that creative exploration translates into concrete planning artifacts.
+## Purpose
+
+Generate multiple solution approaches for software projects through:
+
+- Parallel ideation tracks (architecture, UX, integration, value delivery)
+- Technical-business alignment from inception
+- Hidden assumption discovery
+- Innovation beyond obvious solutions
 
 ## Usage
 
 ```bash
-bmad bmm 1-analysis brainstorm-project
+# Run brainstorming session
+bmad bmm *brainstorm-project
+
+# Or via Analyst agent
+*brainstorm-project
+```
+
+## Process
+
+### 1. Context Capture
+
+- Business objectives and constraints
+- Technical environment
+- Stakeholder needs
+- Success criteria
+
+### 2. Parallel Ideation
+
+- **Architecture Track**: Technical approaches with trade-offs
+- **UX Track**: Interface paradigms and user journeys
+- **Integration Track**: System connection patterns
+- **Value Track**: Feature prioritization and delivery
+
+### 3. Solution Synthesis
+
+- Evaluate feasibility and impact
+- Align with strategic objectives
+- Surface hidden assumptions
+- Generate recommendations
+
+## Inputs & Outputs
+
+### Inputs
+
+| Input             | Type     | Purpose                                       |
+| ----------------- | -------- | --------------------------------------------- |
+| Project Context   | Document | Business objectives, environment, constraints |
+| Problem Statement | Optional | Core challenge or opportunity                 |
+
+### Outputs
+
+| Output                   | Content                                     |
+| ------------------------ | ------------------------------------------- |
+| Architecture Proposals   | Multiple approaches with trade-off analysis |
+| Value Framework          | Prioritized features aligned to objectives  |
+| Risk Analysis            | Dependencies, challenges, opportunities     |
+| Strategic Recommendation | Synthesized direction with rationale        |
+
+## Integration
+
+### Workflow Chain
+
+1. **brainstorm-project** ← Current step
+2. research (optional deep dive)
+3. product-brief (strategic document)
+4. Phase 2 planning (PRD/tech-spec)
+
+### Feed Into
+
+- Product Brief development
+- Architecture decisions
+- PRD requirements
+- Epic prioritization
+
+## Best Practices
+
+1. **Prepare context** - Gather business and technical background
+2. **Think broadly** - Explore non-obvious approaches
+3. **Document assumptions** - Capture implicit beliefs
+4. **Consider constraints** - Technical, organizational, resource
+5. **Focus on value** - Align to business objectives
+
+## Configuration
+
+```yaml
+# bmad/bmm/config.yaml
+output_folder: ./output
+project_name: Your Project
 ```
 
-## Inputs
+## Related Workflows
 
-- **Project Context Document**: Business objectives, technical environment, stakeholder landscape, organizational constraints, success criteria, and known pain points
-- **Problem Statement** (optional): Core business challenge or opportunity driving the project
+- [Research](../research/README.md) - Deep investigation
+- [Product Brief](../product-brief/README.md) - Strategic planning
+- [PRD](../../2-plan-workflows/prd/README.md) - Requirements document
 
-## Outputs
+---
 
-- **Architecture Proposals**: Multiple technical approaches with trade-off analysis and feasibility assessments
-- **Value Delivery Framework**: Prioritized feature concepts aligned with business objectives and user needs
-- **Risk and Opportunity Analysis**: Identified technical dependencies, integration challenges, and innovation opportunities
-- **Strategic Recommendation**: Synthesized direction with rationale and implementation considerations
+Part of BMad Method v6 - Phase 1 Analysis workflows

package/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md

@@ -8,25 +8,40 @@
 
 <workflow>
 
-  <step n="1" goal="Validate workflow readiness">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-      <param>mode: validate</param>
-      <param>calling_workflow: brainstorm-project</param>
-    </invoke-workflow>
+  <step n="1" goal="Validate workflow readiness" tag="workflow-status">
+    <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-    <check if="status_exists == false">
-      <output>{{suggestion}}</output>
-      <output>Note: Brainstorming is optional. Continuing without progress tracking.</output>
+    <check if="status file not found">
+      <output>No workflow status file found. Brainstorming is optional - you can continue without status tracking.</output>
       <action>Set standalone_mode = true</action>
     </check>
 
-    <check if="status_exists == true">
-      <action>Store {{status_file_path}} for later updates</action>
+    <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 "brainstorm-project" workflow</action>
+      <action>Get project_level from YAML metadata</action>
+      <action>Find first non-completed workflow (next expected workflow)</action>
+
+      <check if="brainstorm-project status is file path (already completed)">
+        <output>⚠️ Brainstorming session already completed: {{brainstorm-project status}}</output>
+        <ask>Re-running will create a new session. Continue? (y/n)</ask>
+        <check if="n">
+          <output>Exiting. Use workflow-status to see your next step.</output>
+          <action>Exit workflow</action>
+        </check>
+      </check>
 
-      <check if="warning != ''">
-        <output>{{warning}}</output>
-        <output>Note: Brainstorming can be valuable at any project stage.</output>
+      <check if="brainstorm-project is not the next expected workflow (anything after brainstorm-project is completed already)">
+        <output>⚠️ Next expected workflow: {{next_workflow}}. Brainstorming is out of sequence.</output>
+        <ask>Continue with brainstorming anyway? (y/n)</ask>
+        <check if="n">
+          <output>Exiting. Run {{next_workflow}} instead.</output>
+          <action>Exit workflow</action>
+        </check>
       </check>
+
+      <action>Set standalone_mode = false</action>
     </check>
   </step>
 
@@ -51,36 +66,40 @@
     </invoke-workflow>
   </step>
 
-  <step n="4" goal="Update status and complete">
+  <step n="4" goal="Update status and complete" tag="workflow-status">
     <check if="standalone_mode != true">
-      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-        <param>mode: update</param>
-        <param>action: complete_workflow</param>
-        <param>workflow_name: brainstorm-project</param>
-      </invoke-workflow>
-
-      <check if="success == true">
-        <output>Status updated! Next: {{next_workflow}}</output>
-      </check>
+      <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+      <action>Find workflow_status key "brainstorm-project"</action>
+      <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+      <action>Update workflow_status["brainstorm-project"] = "{output_folder}/bmm-brainstorming-session-{{date}}.md"</action>
+      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+      <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>
 
     <output>**✅ Brainstorming Session Complete, {user_name}!**
 
 **Session Results:**
+
 - Brainstorming results saved to: {output_folder}/bmm-brainstorming-session-{{date}}.md
 
 {{#if standalone_mode != true}}
 **Status Updated:**
+
 - Progress tracking updated
 
 **Next Steps:**
+
 - **Next required:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** You can run other analysis workflows (research, product-brief) before proceeding
 
 Check status anytime with: `workflow-status`
 {{else}}
 **Next Steps:**
+
 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}}