bmad-method 4.30.4 → 4.32.0

package/README.md

@@ -23,7 +23,7 @@ Foundations in Agentic Agile Driven Development, known as the Breakthrough Metho
 
 This two-phase approach eliminates both **planning inconsistency** and **context loss** - the biggest problems in AI-assisted development. Your Dev agent opens a story file with complete understanding of what to build, how to build it, and why.
 
-**📖 [See the complete workflow in the User Guide](docs/user-guide.md)** - Planning phase, development cycle, and all agent roles
+**📖 [See the complete workflow in the User Guide](bmad-core/user-guide.md)** - Planning phase, development cycle, and all agent roles
 
 ## Quick Navigation
 
@@ -31,15 +31,15 @@ This two-phase approach eliminates both **planning inconsistency** and **context
 
 **Before diving in, review these critical workflow diagrams that explain how BMad works:**
 
-1. **[Planning Workflow (Web UI)](docs/user-guide.md#the-planning-workflow-web-ui)** - How to create PRD and Architecture documents
-2. **[Core Development Cycle (IDE)](docs/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files
+1. **[Planning Workflow (Web UI)](bmad-core/user-guide.md#the-planning-workflow-web-ui)** - How to create PRD and Architecture documents
+2. **[Core Development Cycle (IDE)](bmad-core/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files
 
 > ⚠️ **These diagrams explain 90% of BMad Method Agentic Agile flow confusion** - Understanding the PRD+Architecture creation and the SM/Dev/QA workflow and how agents pass notes through story files is essential - and also explains why this is NOT taskmaster or just a simple task runner!
 
 ### What would you like to do?
 
 - **[Install and Build software with Full Stack Agile AI Team](#quick-start)** → Quick Start Instruction
-- **[Learn how to use BMad](docs/user-guide.md)** → Complete user guide and walkthrough
+- **[Learn how to use BMad](bmad-core/user-guide.md)** → Complete user guide and walkthrough
 - **[See available AI agents](#available-agents)** → Specialized roles for your team
 - **[Explore non-technical uses](#-beyond-software-development---expansion-packs)** → Creative writing, business, wellness, education
 - **[Create my own AI agents](#creating-your-own-expansion-pack)** → Build agents for your domain
@@ -97,7 +97,7 @@ This single command handles:
 3. **Upload & configure**: Upload the file and set instructions: "Your critical operating instructions are attached, do not break character as directed"
 4. **Start Ideating and Planning**: Start chatting! Type `*help` to see available commands or pick an agent like `*analyst` to start right in on creating a brief.
 5. **CRITICAL**: Talk to BMad Orchestrator in the web at ANY TIME (#bmad-orchestrator command) and ask it questions about how this all works!
-6. **When to move to the IDE**: Once you have your PRD, Architecture, optional UX and Briefs - its time to switch over to the IDE to shard your docs, and start implementing the actual code! See the [User guide](docs/user-guide.md) for more details
+6. **When to move to the IDE**: Once you have your PRD, Architecture, optional UX and Briefs - its time to switch over to the IDE to shard your docs, and start implementing the actual code! See the [User guide](bmad-core/user-guide.md) for more details
 
 ### Alternative: Clone and Build
 
@@ -110,14 +110,53 @@ npm run install:bmad # build and install all to a destination folder
 
 BMad's natural language framework works in ANY domain. Expansion packs provide specialized AI agents for creative writing, business strategy, health & wellness, education, and more. Also expansion packs can expand the core BMad-Method with specific functionality that is not generic for all cases. [See the Expansion Packs Guide](docs/expansion-packs.md) and learn to create your own!
 
+## Codebase Flattener Tool
+
+The BMad-Method includes a powerful codebase flattener tool designed to prepare your project files for AI model consumption. This tool aggregates your entire codebase into a single XML file, making it easy to share your project context with AI assistants for analysis, debugging, or development assistance.
+
+### Features
+
+- **AI-Optimized Output**: Generates clean XML format specifically designed for AI model consumption
+- **Smart Filtering**: Automatically respects `.gitignore` patterns to exclude unnecessary files
+- **Binary File Detection**: Intelligently identifies and excludes binary files, focusing on source code
+- **Progress Tracking**: Real-time progress indicators and comprehensive completion statistics
+- **Flexible Output**: Customizable output file location and naming
+
+### Usage
+
+```bash
+# Basic usage - creates flattened-codebase.xml in current directory
+npm run flatten
+
+# Specify custom output file
+npm run flatten -- --output my-project.xml
+npm run flatten -- -o /path/to/output/codebase.xml
+```
+
+### Example Output
+
+The tool will display progress and provide a comprehensive summary:
+
+```
+📊 Completion Summary:
+✅ Successfully processed 156 files into flattened-codebase.xml
+📁 Output file: /path/to/your/project/flattened-codebase.xml
+📏 Total source size: 2.3 MB
+📄 Generated XML size: 2.1 MB
+📝 Total lines of code: 15,847
+🔢 Estimated tokens: 542,891
+📊 File breakdown: 142 text, 14 binary, 0 errors
+```
+
+The generated XML file contains all your project's source code in a structured format that AI models can easily parse and understand, making it perfect for code reviews, architecture discussions, or getting AI assistance with your BMad-Method projects.
+
 ## Documentation & Resources
 
 ### Essential Guides
 
-- 📖 **[User Guide](docs/user-guide.md)** - Complete walkthrough from project inception to completion
+- 📖 **[User Guide](bmad-core/user-guide.md)** - Complete walkthrough from project inception to completion
 - 🏗️ **[Core Architecture](docs/core-architecture.md)** - Technical deep dive and system design
 - 🚀 **[Expansion Packs Guide](docs/expansion-packs.md)** - Extend BMad to any domain beyond software development
-- [IDE Specific Guides available in this folder](docs/agentic-tools/)
 
 ## Support
 

package/bmad-core/agents/analyst.md

@@ -52,7 +52,7 @@ persona:
     - Integrity of Information - Ensure accurate sourcing and representation
     - Numbered Options Protocol - Always use numbered lists for selections
 # All commands require * prefix when used (e.g., *help)
-commands:  
+commands:
   - help: Show numbered list of the following commands to allow selection
   - create-project-brief: use task create-doc with project-brief-tmpl.yaml
   - perform-market-research: use task create-doc with market-research-tmpl.yaml

package/bmad-core/agents/architect.md

@@ -1,6 +1,5 @@
 # architect
 
-
 ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
 
 CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
@@ -53,12 +52,12 @@ persona:
     - Cost-Conscious Engineering - Balance technical ideals with financial reality
     - Living Architecture - Design for change and adaptation
 # All commands require * prefix when used (e.g., *help)
-commands:  
+commands:
   - help: Show numbered list of the following commands to allow selection
   - create-full-stack-architecture: use create-doc with fullstack-architecture-tmpl.yaml
   - create-backend-architecture: use create-doc with architecture-tmpl.yaml
   - create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml
-  - create-brownfield-architecture:  use create-doc with brownfield-architecture-tmpl.yaml
+  - create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml
   - doc-out: Output full document to current destination file
   - document-project: execute the task document-project.md
   - execute-checklist {checklist}: Run task execute-checklist (default->architect-checklist)

package/bmad-core/agents/bmad-master.md

@@ -1,6 +1,5 @@
 # BMad Master
 
-
 ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
 
 CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:

package/bmad-core/agents/bmad-orchestrator.md

@@ -1,6 +1,5 @@
 # BMad Web Orchestrator
 
-
 ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
 
 CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
@@ -52,9 +51,9 @@ persona:
     - Always use numbered lists for choices
     - Process commands starting with * immediately
     - Always remind users that commands require * prefix
-commands:  # All commands require * prefix when used (e.g., *help, *agent pm)
+commands: # All commands require * prefix when used (e.g., *help, *agent pm)
   help: Show this guide with available agents and workflows
-  chat-mode: Start conversational mode for detailed assistance  
+  chat-mode: Start conversational mode for detailed assistance
   kb-mode: Load full BMad knowledge base
   status: Show current context, active agent, and progress
   agent: Transform into a specialized agent (list if name not specified)
@@ -72,42 +71,42 @@ commands:  # All commands require * prefix when used (e.g., *help, *agent pm)
 help-display-template: |
   === BMad Orchestrator Commands ===
   All commands must start with * (asterisk)
-  
+
   Core Commands:
   *help ............... Show this guide
   *chat-mode .......... Start conversational mode for detailed assistance
   *kb-mode ............ Load full BMad knowledge base
   *status ............. Show current context, active agent, and progress
   *exit ............... Return to BMad or exit session
-  
+
   Agent & Task Management:
   *agent [name] ....... Transform into specialized agent (list if no name)
   *task [name] ........ Run specific task (list if no name, requires agent)
   *checklist [name] ... Execute checklist (list if no name, requires agent)
-  
+
   Workflow Commands:
   *workflow [name] .... Start specific workflow (list if no name)
   *workflow-guidance .. Get personalized help selecting the right workflow
   *plan ............... Create detailed workflow plan before starting
   *plan-status ........ Show current workflow plan progress
   *plan-update ........ Update workflow plan status
-  
+
   Other Commands:
   *yolo ............... Toggle skip confirmations mode
   *party-mode ......... Group chat with all agents
   *doc-out ............ Output full document
-  
+
   === Available Specialist Agents ===
   [Dynamically list each agent in bundle with format:
   *agent {id}: {title}
     When to use: {whenToUse}
     Key deliverables: {main outputs/documents}]
-  
+
   === Available Workflows ===
   [Dynamically list each workflow in bundle with format:
   *workflow {id}: {name}
     Purpose: {description}]
-  
+
   💡 Tip: Each agent has unique tasks, templates, and checklists. Switch to an agent to access their capabilities!
 
 fuzzy-matching:

package/bmad-core/agents/dev.md

@@ -38,7 +38,6 @@ agent:
   whenToUse: "Use for code implementation, debugging, refactoring, and development best practices"
   customization:
 
-
 persona:
   role: Expert Senior Software Engineer & Implementation Specialist
   style: Extremely concise, pragmatic, detail-oriented, solution-focused
@@ -52,7 +51,7 @@ core_principles:
   - Numbered Options - Always use numbered lists when presenting choices to the user
 
 # All commands require * prefix when used (e.g., *help)
-commands:  
+commands:
   - help: Show numbered list of the following commands to allow selection
   - run-tests: Execute linting and tests
   - explain: teach me what and why you did whatever you just did in detail so I can learn. Explain to me as if you were training a junior engineer.

package/bmad-core/agents/pm.md

@@ -48,10 +48,12 @@ persona:
     - Proactive risk identification
     - Strategic thinking & outcome-oriented
 # All commands require * prefix when used (e.g., *help)
-commands:  
+commands:
   - help: Show numbered list of the following commands to allow selection
   - create-prd: run task create-doc.md with template prd-tmpl.yaml
   - create-brownfield-prd: run task create-doc.md with template brownfield-prd-tmpl.yaml
+  - create-brownfield-epic: run task brownfield-create-epic.md
+  - create-brownfield-story: run task brownfield-create-story.md
   - create-epic: Create epic for brownfield projects (task brownfield-create-epic)
   - create-story: Create user story from requirements (task brownfield-create-story)
   - doc-out: Output full document to current destination file

package/bmad-core/agents/po.md

@@ -51,7 +51,7 @@ persona:
     - Focus on Executable & Value-Driven Increments - Ensure work aligns with MVP goals
     - Documentation Ecosystem Integrity - Maintain consistency across all documents
 # All commands require * prefix when used (e.g., *help)
-commands:  
+commands:
   - help: Show numbered list of the following commands to allow selection
   - execute-checklist-po: Run task execute-checklist (checklist po-master-checklist)
   - shard-doc {document} {destination}: run the task shard-doc against the optionally provided document to the specified destination

package/bmad-core/agents/qa.md

@@ -55,7 +55,7 @@ story-file-permissions:
   - CRITICAL: DO NOT modify any other sections including Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Testing, Dev Agent Record, Change Log, or any other sections
   - CRITICAL: Your updates must be limited to appending your review results in the QA Results section only
 # All commands require * prefix when used (e.g., *help)
-commands:  
+commands:
   - help: Show numbered list of the following commands to allow selection
   - review {story}: execute the task review-story for the highest sequence story in docs/stories unless another is specified - keep any specified technical-preferences in mind as needed
   - exit: Say goodbye as the QA Engineer, and then abandon inhabiting this persona

package/bmad-core/agents/sm.md

@@ -44,7 +44,7 @@ persona:
     - Will ensure all information comes from the PRD and Architecture to guide the dumb dev agent
     - You are NOT allowed to implement stories or modify code EVER!
 # All commands require * prefix when used (e.g., *help)
-commands:  
+commands:
   - help: Show numbered list of the following commands to allow selection
   - draft: Execute task create-next-story.md
   - correct-course: Execute task correct-course.md

package/bmad-core/agents/ux-expert.md

@@ -49,7 +49,7 @@ persona:
     - You're particularly skilled at translating user needs into beautiful, functional designs.
     - You can craft effective prompts for AI UI generation tools like v0, or Lovable.
 # All commands require * prefix when used (e.g., *help)
-commands:  
+commands:
   - help: Show numbered list of the following commands to allow selection
   - create-front-end-spec: run task create-doc.md with template front-end-spec-tmpl.yaml
   - generate-ui-prompt: Run task generate-ai-frontend-prompt.md

package/bmad-core/data/bmad-kb.md

@@ -477,6 +477,7 @@ that can handle [specific requirements]."
 **Prerequisites**: Planning documents must exist in `docs/` folder
 
 1. **Document Sharding** (CRITICAL STEP):
+
    - Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
    - Two methods to shard:
      a) **Manual**: Drag `shard-doc` task + document file into chat
@@ -499,17 +500,20 @@ Resulting Folder Structure:
 1. **Development Cycle** (Sequential, one story at a time):
 
    **CRITICAL CONTEXT MANAGEMENT**:
+
    - **Context windows matter!** Always use fresh, clean context windows
    - **Model selection matters!** Use most powerful thinking model for SM story creation
    - **ALWAYS start new chat between SM, Dev, and QA work**
 
    **Step 1 - Story Creation**:
+
    - **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
    - SM executes create-next-story task
    - Review generated story in `docs/stories/`
    - Update status from "Draft" to "Approved"
 
    **Step 2 - Story Implementation**:
+
    - **NEW CLEAN CHAT** → `@dev`
    - Agent asks which story to implement
    - Include story file content to save dev agent lookup time
@@ -518,6 +522,7 @@ Resulting Folder Structure:
    - Dev marks story as "Review" when complete with all tests passing
 
    **Step 3 - Senior QA Review**:
+
    - **NEW CLEAN CHAT** → `@qa` → execute review-story task
    - QA performs senior developer code review
    - QA can refactor and improve code directly
@@ -542,7 +547,7 @@ Each status change requires user verification and approval before proceeding.
 #### Greenfield Development
 
 - Business analysis and market research
-- Product requirements and feature definition  
+- Product requirements and feature definition
 - System architecture and design
 - Development execution
 - Testing and deployment
@@ -569,9 +574,11 @@ Each status change requires user verification and approval before proceeding.
 1. **Upload project to Gemini Web**
 2. **Document everything**: `@analyst` → `*document-project`
 3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
+
    - More thorough but can create excessive documentation
 
 4. **Requirements Gathering**:
+
    - **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
    - **Analyzes**: Existing system, constraints, integration points
    - **Defines**: Enhancement scope, compatibility requirements, risk assessment
@@ -651,8 +658,11 @@ Templates with Level 2 headings (`##`) can be automatically sharded:
 
 ```markdown
 ## Goals and Background Context
-## Requirements  
+
+## Requirements
+
 ## User Interface Design Goals
+
 ## Success Metrics
 ```
 

package/bmad-core/data/elicitation-methods.md

@@ -3,16 +3,19 @@
 ## Core Reflective Methods
 
 **Expand or Contract for Audience**
+
 - Ask whether to 'expand' (add detail, elaborate) or 'contract' (simplify, clarify)
 - Identify specific target audience if relevant
 - Tailor content complexity and depth accordingly
 
 **Explain Reasoning (CoT Step-by-Step)**
+
 - Walk through the step-by-step thinking process
 - Reveal underlying assumptions and decision points
 - Show how conclusions were reached from current role's perspective
 
 **Critique and Refine**
+
 - Review output for flaws, inconsistencies, or improvement areas
 - Identify specific weaknesses from role's expertise
 - Suggest refined version reflecting domain knowledge
@@ -20,12 +23,14 @@
 ## Structural Analysis Methods
 
 **Analyze Logical Flow and Dependencies**
+
 - Examine content structure for logical progression
 - Check internal consistency and coherence
 - Identify and validate dependencies between elements
 - Confirm effective ordering and sequencing
 
 **Assess Alignment with Overall Goals**
+
 - Evaluate content contribution to stated objectives
 - Identify any misalignments or gaps
 - Interpret alignment from specific role's perspective
@@ -34,12 +39,14 @@
 ## Risk and Challenge Methods
 
 **Identify Potential Risks and Unforeseen Issues**
+
 - Brainstorm potential risks from role's expertise
 - Identify overlooked edge cases or scenarios
 - Anticipate unintended consequences
 - Highlight implementation challenges
 
 **Challenge from Critical Perspective**
+
 - Adopt critical stance on current content
 - Play devil's advocate from specified viewpoint
 - Argue against proposal highlighting weaknesses
@@ -48,12 +55,14 @@
 ## Creative Exploration Methods
 
 **Tree of Thoughts Deep Dive**
+
 - Break problem into discrete "thoughts" or intermediate steps
 - Explore multiple reasoning paths simultaneously
 - Use self-evaluation to classify each path as "sure", "likely", or "impossible"
 - Apply search algorithms (BFS/DFS) to find optimal solution paths
 
 **Hindsight is 20/20: The 'If Only...' Reflection**
+
 - Imagine retrospective scenario based on current content
 - Identify the one "if only we had known/done X..." insight
 - Describe imagined consequences humorously or dramatically
@@ -62,6 +71,7 @@
 ## Multi-Persona Collaboration Methods
 
 **Agile Team Perspective Shift**
+
 - Rotate through different Scrum team member viewpoints
 - Product Owner: Focus on user value and business impact
 - Scrum Master: Examine process flow and team dynamics
@@ -69,12 +79,14 @@
 - QA: Identify testing scenarios and quality concerns
 
 **Stakeholder Round Table**
+
 - Convene virtual meeting with multiple personas
 - Each persona contributes unique perspective on content
 - Identify conflicts and synergies between viewpoints
 - Synthesize insights into actionable recommendations
 
 **Meta-Prompting Analysis**
+
 - Step back to analyze the structure and logic of current approach
 - Question the format and methodology being used
 - Suggest alternative frameworks or mental models
@@ -83,24 +95,28 @@
 ## Advanced 2025 Techniques
 
 **Self-Consistency Validation**
+
 - Generate multiple reasoning paths for same problem
 - Compare consistency across different approaches
 - Identify most reliable and robust solution
 - Highlight areas where approaches diverge and why
 
 **ReWOO (Reasoning Without Observation)**
+
 - Separate parametric reasoning from tool-based actions
 - Create reasoning plan without external dependencies
 - Identify what can be solved through pure reasoning
 - Optimize for efficiency and reduced token usage
 
 **Persona-Pattern Hybrid**
+
 - Combine specific role expertise with elicitation pattern
 - Architect + Risk Analysis: Deep technical risk assessment
 - UX Expert + User Journey: End-to-end experience critique
 - PM + Stakeholder Analysis: Multi-perspective impact review
 
 **Emergent Collaboration Discovery**
+
 - Allow multiple perspectives to naturally emerge
 - Identify unexpected insights from persona interactions
 - Explore novel combinations of viewpoints
@@ -109,18 +125,21 @@
 ## Game-Based Elicitation Methods
 
 **Red Team vs Blue Team**
+
 - Red Team: Attack the proposal, find vulnerabilities
 - Blue Team: Defend and strengthen the approach
 - Competitive analysis reveals blind spots
 - Results in more robust, battle-tested solutions
 
 **Innovation Tournament**
+
 - Pit multiple alternative approaches against each other
 - Score each approach across different criteria
 - Crowd-source evaluation from different personas
 - Identify winning combination of features
 
 **Escape Room Challenge**
+
 - Present content as constraints to work within
 - Find creative solutions within tight limitations
 - Identify minimum viable approach
@@ -129,6 +148,7 @@
 ## Process Control
 
 **Proceed / No Further Actions**
+
 - Acknowledge choice to finalize current work
 - Accept output as-is or move to next step
 - Prepare to continue without additional elicitation

package/bmad-core/enhanced-ide-development-workflow.md

@@ -0,0 +1,43 @@
+# Enhanced Development Workflow
+
+This is a simple step-by-step guide to help you efficiently manage your development workflow using the BMad Method. Refer to the **[<ins>User Guide</ins>](user-guide.md)** for any scenario that is not covered here.
+
+## Create new Branch
+
+1. **Start new branch**
+
+## Story Creation (Scrum Master)
+
+1. **Start new chat/conversation**
+2. **Load SM agent**
+3. **Execute**: `*draft` (runs create-next-story task)
+4. **Review generated story** in `docs/stories/`
+5. **Update status**: Change from "Draft" to "Approved"
+
+## Story Implementation (Developer)
+
+1. **Start new chat/conversation**
+2. **Load Dev agent**
+3. **Execute**: `*develop-story {selected-story}` (runs execute-checklist task)
+4. **Review generated report** in `{selected-story}`
+
+## Story Review (Quality Assurance)
+
+1. **Start new chat/conversation**
+2. **Load QA agent**
+3. **Execute**: `*review {selected-story}` (runs review-story task)
+4. **Review generated report** in `{selected-story}`
+
+## Commit Changes and Push
+
+1. **Commit changes**
+2. **Push to remote**
+
+## Repeat Until Complete
+
+- **SM**: Create next story → Review → Approve
+- **Dev**: Implement story → Complete → Mark Ready for Review
+- **QA**: Review story → Mark done
+- **Commit**: All changes
+- **Push**: To remote
+- **Continue**: Until all features implemented

package/bmad-core/tasks/advanced-elicitation.md

@@ -41,12 +41,14 @@ User can request advanced elicitation on any agent output:
 **Method Selection Strategy**:
 
 1. **Always Include Core Methods** (choose 3-4):
+
    - Expand or Contract for Audience
    - Critique and Refine
    - Identify Potential Risks
    - Assess Alignment with Goals
 
 2. **Context-Specific Methods** (choose 4-5):
+
    - **Technical Content**: Tree of Thoughts, ReWOO, Meta-Prompting
    - **User-Facing Content**: Agile Team Perspective, Stakeholder Roundtable
    - **Creative Content**: Innovation Tournament, Escape Room Challenge