bmad-method 4.19.2 → 4.21.0

package/docs/agentic-tools/roo-code-guide.md

@@ -0,0 +1,46 @@
+# BMAD Method Guide for Roo Code
+
+This guide covers Roo Code-specific setup and usage with BMAD Method. For the complete workflow, see the [BMAD Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Roo Code** as your IDE. This creates:
+
+- `.bmad-core/` folder with all agents
+- `.roomodes` file in project root with custom modes
+
+## Using BMAD Agents in Roo Code
+
+Select mode from the mode selector (usually in status bar):
+
+- `bmad-bmad-master` - 🧙 Universal task executor
+- `bmad-sm` - 🏃 Scrum Master
+- `bmad-dev` - 💻 Full-stack developer
+- `bmad-architect` - 🏗️ Solution architect
+- `bmad-pm` - 📋 Product manager
+- `bmad-analyst` - 📊 Business analyst
+- `bmad-qa` - 🧪 QA specialist
+- `bmad-po` - 🎯 Product owner
+- `bmad-ux-expert` - 🎨 UX specialist
+
+## Roo Code-Specific Features
+
+- **Mode file**: `.roomodes` in project root
+- **Mode switching**: Use mode selector instead of starting new chats
+- **Context preservation**: Maintains context across mode switches
+- **File permissions**: Each agent has specific file access:
+
+### File Permission Summary
+
+- **Documentation agents** (analyst, pm, po, sm): `.md`, `.txt` only
+- **bmad-architect**: `.md`, `.txt`, `.yml`, `.yaml`, `.json`
+- **bmad-qa**: Test files (`.test.*`, `.spec.*`) and `.md`
+- **bmad-ux-expert**: `.md`, `.css`, `.scss`, `.html`, `.jsx`, `.tsx`
+- **Full access**: `bmad-dev`, `bmad-bmad-master`, `bmad-orchestrator`
+
+## Tips for Roo Code Users
+
+- Switch modes instead of starting new chats
+- Each mode supports `*help` to see available commands
+- Agents respect file permission boundaries
+- Context persists across mode switches

package/docs/agentic-tools/windsurf-guide.md

@@ -0,0 +1,37 @@
+# BMAD Method Guide for Windsurf
+
+This guide covers Windsurf-specific setup and usage with BMAD Method. For the complete workflow, see the [BMAD Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Windsurf** as your IDE. This creates:
+
+- `.bmad-core/` folder with all agents
+- `.windsurf/rules/` folder with agent rule files (`.md`)
+
+## Using BMAD Agents in Windsurf
+
+Type `@agent-name` in chat to activate an agent:
+
+- `@bmad-master` - Universal task executor
+- `@sm` - Scrum Master
+- `@dev` - Full-stack developer
+- `@architect` - Solution architect
+- `@pm` - Product manager
+- `@analyst` - Business analyst
+- `@qa` - QA specialist
+- `@po` - Product owner
+- `@ux-expert` - UX specialist
+
+## Windsurf-Specific Features
+
+- **Rule files**: Stored in `.windsurf/rules/` as `.md` files
+- **Activation**: Use `@` prefix to mention agents
+- **Collaborative features**: Works well with BMAD's agent-switching pattern
+- **Project context**: Agents have access to your full project context
+
+## Tips for Windsurf Users
+
+- Start new chats when switching agents
+- Each agent supports `*help` to see available commands
+- Leverage Windsurf's collaboration features for team reviews

package/docs/core-architecture.md

@@ -204,12 +204,180 @@ graph TD
     F -->|Approved| G["Dev: Implement Story"]
     F -->|Needs Changes| E
     G --> H["Dev: Complete story Tasks"]
-    H --> I{"User Verification"}
-    I -->|Verified Complete| J["Mark Story as Done"]
-    I -->|Needs Fixes| G
-    J --> E
+    H --> I["Dev: Mark Ready for Review"]
+    I --> J{"User Verification"}
+    J -->|Request QA Review| K["QA: Run review-story task"]
+    J -->|Approve Without QA| M["Mark Story as Done"]
+    K --> L{"QA Review Results"}
+    L -->|Needs Work| G
+    L -->|Approved| M["Mark Story as Done"]
+    J -->|Needs Fixes| G
+    M --> E
+
+    style M fill:#34a853,color:#fff
+    style K fill:#f9ab00,color:#fff
+```
 
-    style J fill:#34a853,color:#fff
+This cycle continues, with the Scrum Master, Developer, and optionally QA agents working together. The QA agent provides senior developer review capabilities through the `review-story` task, offering code refactoring, quality improvements, and knowledge transfer. This ensures high code quality while maintaining development velocity.
+
+## 8. Complete Source Tree
+
+The BMAD-METHOD project structure is designed for clarity, modularity, and extensibility. Here's the complete source tree with explanations:
+
+```plaintext
+bmad-method/
+├── .bmad-core/                    # Core framework (installed in user projects)
+│   ├── agents/                    # Individual agent definitions
+│   │   ├── analyst.md            # Business analyst agent
+│   │   ├── architect.md          # Solution architect agent
+│   │   ├── bmad-master.md        # Universal expert agent
+│   │   ├── bmad-orchestrator.md  # Multi-agent coordinator
+│   │   ├── dev.md                # Full-stack developer agent
+│   │   ├── pm.md                 # Product manager agent
+│   │   ├── po.md                 # Product owner agent
+│   │   ├── qa.md                 # QA specialist agent
+│   │   ├── sm.md                 # Scrum master agent
+│   │   └── ux-expert.md          # UX designer agent
+│   ├── agent-teams/              # Pre-configured agent teams
+│   │   ├── team-all.yml          # All agents bundle
+│   │   ├── team-fullstack.yml    # Full-stack development team
+│   │   ├── team-ide-minimal.yml  # Minimal IDE-focused team
+│   │   └── team-no-ui.yml        # Backend-only team
+│   ├── checklists/               # Quality assurance checklists
+│   │   ├── architect-checklist.md
+│   │   ├── po-master-checklist.md
+│   │   └── story-dod-checklist.md
+│   ├── data/                     # Knowledge base and preferences
+│   │   ├── bmad-kb.md            # Core knowledge base
+│   │   └── technical-preferences.md  # User tech preferences
+│   ├── tasks/                    # Reusable task definitions
+│   │   ├── advanced-elicitation.md   # Deep diving techniques
+│   │   ├── create-doc.md         # Document creation task
+│   │   ├── create-next-story.md  # Story generation task
+│   │   ├── doc-migration-task.md # V3 to V4 migration
+│   │   ├── execute-checklist.md  # Checklist runner
+│   │   └── shard-doc.md          # Document sharding task
+│   ├── templates/                # Document templates
+│   │   ├── full-stack-architecture-tmpl.md
+│   │   ├── prd-tmpl.md
+│   │   ├── project-brief-tmpl.md
+│   │   ├── story-tmpl.md
+│   │   └── [other templates...]
+│   ├── utils/                    # Utility components
+│   │   ├── agent-switcher.web    # Web UI agent switching
+│   │   ├── template-format.md    # Template markup spec
+│   │   └── workflow-management.md # Workflow helpers
+│   ├── workflows/                # Development workflows
+│   │   ├── brownfield-enhancement.yml
+│   │   ├── greenfield-fullstack.yml
+│   │   ├── greenfield-service.yml
+│   │   └── greenfield-simple.yml
+│   └── core-config.yml           # V4 configuration system
+│
+├── dist/                         # Pre-built bundles (generated)
+│   ├── agents/                   # Individual agent bundles
+│   │   ├── analyst.txt
+│   │   ├── architect.txt
+│   │   └── [other agents...]
+│   ├── teams/                    # Team bundles for web UI
+│   │   ├── team-all.txt
+│   │   ├── team-fullstack.txt
+│   │   └── [other teams...]
+│   └── expansion-packs/          # Expansion pack bundles
+│
+├── docs/                         # Documentation
+│   ├── agentic-tools/           # IDE-specific guides
+│   │   ├── claude-code-guide.md
+│   │   ├── cursor-guide.md
+│   │   ├── cline-guide.md
+│   │   ├── gemini-cli-guide.md
+│   │   ├── roo-code-guide.md
+│   │   └── windsurf-guide.md
+│   ├── bmad-workflow-guide.md    # Universal workflow guide
+│   ├── core-architecture.md      # This document
+│   ├── expansion-packs.md        # Expansion pack guide
+│   ├── user-guide.md            # Comprehensive user guide
+│   └── [other docs...]
+│
+├── expansion-packs/              # Domain-specific extensions
+│   ├── bmad-2d-phaser-game-dev/ # Game development pack
+│   ├── bmad-creator-tools/      # Agent creation tools
+│   ├── bmad-infrastructure-devops/ # DevOps pack
+│   └── README.md
+│
+├── tools/                        # Build and installation tools
+│   ├── builders/                 # Build system
+│   │   └── web-builder.js       # Bundle generator
+│   ├── cli.js                   # Main CLI tool
+│   ├── installer/               # NPX installer
+│   │   ├── index.js             # Installer entry point
+│   │   ├── config/              # Installation configs
+│   │   ├── lib/                 # Installer utilities
+│   │   └── templates/           # IDE template files
+│   └── lib/                     # Shared libraries
+│       ├── bundle-utils.js
+│       ├── dependency-resolver.js
+│       └── file-processor.js
+│
+├── .github/                     # GitHub configuration
+│   ├── workflows/               # GitHub Actions
+│   └── ISSUE_TEMPLATE/         # Issue templates
+│
+├── common/                      # Shared resources
+│   ├── tasks/                   # Common tasks
+│   └── utils/                   # Common utilities
+│
+├── bmad-core/                   # Source for .bmad-core
+│   └── [mirrors .bmad-core structure]
+│
+├── package.json                 # Node.js configuration
+├── README.md                    # Project readme
+├── CONTRIBUTING.md              # Contribution guidelines
+├── GUIDING-PRINCIPLES.md        # Core principles
+└── LICENSE                      # MIT license
 ```
 
-This cycle continues, with the Scrum Master and Developer agents working in tandem, until all stories in the epic are completed.
+### Directory Purposes
+
+#### Core Framework (.bmad-core/)
+
+- **agents/**: Individual AI agent personalities and capabilities
+- **agent-teams/**: Bundles of agents for specific workflows
+- **checklists/**: Quality assurance and validation steps
+- **data/**: Knowledge base and user preferences
+- **tasks/**: Reusable procedures agents can execute
+- **templates/**: Document templates with embedded AI instructions
+- **utils/**: Helper components for agents
+- **workflows/**: Structured development processes
+
+#### Generated Bundles (dist/)
+
+- Pre-built text files ready for web UI upload
+- Automatically generated by the build system
+- Includes resolved dependencies for each agent/team
+
+#### Tools (tools/)
+
+- **cli.js**: Main build tool for creating bundles
+- **installer/**: NPX-based installer for projects
+- **builders/**: Bundle generation logic
+- **lib/**: Shared utilities for build system
+
+#### Expansion Packs (expansion-packs/)
+
+- Domain-specific agent collections
+- Extend BMAD beyond software development
+- Each pack is self-contained with its own agents, tasks, and templates
+
+#### Documentation (docs/)
+
+- Comprehensive guides for users
+- Technical architecture documentation
+- IDE-specific setup instructions
+
+### Key Files
+
+- **core-config.yml**: V4's flexible configuration system
+- **bmad-kb.md**: Central knowledge base loaded by most agents
+- **template-format.md**: Specification for BMAD's template markup
+- **dependency-resolver.js**: Manages agent resource loading

package/docs/expansion-packs.md

@@ -132,6 +132,21 @@ Property investment and management:
 - **Flip Strategist**: Renovation ROI, project planning
 - **Agent Assistant**: Listing optimization, showing prep
 
+### Personal Development Pack
+
+Complete personal growth system:
+
+- **Life Coach**: Guides personal growth and transformation
+- **Goal Strategist**: Helps achieve objectives with SMART goals
+- **Habit Builder**: Creates lasting habits with accountability
+- **Mindset Mentor**: Develops positive thinking patterns
+
+Key tasks include:
+
+- `goal-setting`: Defines SMART goals with action plans
+- `habit-tracking`: Monitors habit formation progress
+- `reflection-exercise`: Facilitates deep self-reflection
+
 ## Unique & Innovative Packs
 
 ### Role-Playing Game Master Pack

package/docs/how-to-contribute-with-pull-requests.md

@@ -8,7 +8,15 @@ A pull request (PR) is how you propose changes to a project on GitHub. Think of
 
 ## Before You Start
 
-⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change. If you're planning something big, please [open an issue](https://github.com/bmadcode/bmad-method/issues) or start a [discussion](https://github.com/bmadcode/bmad-method/discussions) first.
+⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change.
+
+**Required before submitting PRs:**
+
+- **For bug fixes**: Create an issue using the [bug report template](https://github.com/bmadcode/bmad-method/issues/new?template=bug_report.md)
+- **For new features**:
+  1. Discuss in Discord [#general-dev channel](https://discord.gg/g6ypHytrCB)
+  2. Create an issue using the [feature request template](https://github.com/bmadcode/bmad-method/issues/new?template=feature_request.md)
+- **For large changes**: Always open an issue first to discuss alignment
 
 ## Step-by-Step Guide
 
@@ -82,9 +90,15 @@ git push origin fix/typo-in-readme
 
 1. Go to your fork on GitHub
 2. You'll see a green "Compare & pull request" button - click it
-3. Fill out the PR template:
-   - **Title**: Clear, descriptive title
-   - **Description**: Explain what you changed and why
+3. Select the correct target branch:
+   - **`next` branch** for most contributions (features, docs, enhancements)
+   - **`main` branch** only for critical fixes
+4. Fill out the PR description using the template in CONTRIBUTING.md:
+   - **What**: 1-2 sentences describing what changed
+   - **Why**: 1-2 sentences explaining why
+   - **How**: 2-3 bullets on implementation
+   - **Testing**: How you tested
+5. Reference the related issue number (e.g., "Fixes #123")
 
 ### 8. Wait for Review
 
@@ -117,9 +131,12 @@ git push origin fix/typo-in-readme
 
 ## Need Help?
 
-- 💬 Join our [Discord Community](https://discord.gg/g6ypHytrCB) for real-time help
-- 💬 Ask questions in [Discussions](https://github.com/bmadcode/bmad-method/discussions)
-- 🐛 Report bugs in [Issues](https://github.com/bmadcode/bmad-method/issues)
+- 💬 Join our [Discord Community](https://discord.gg/g6ypHytrCB) for real-time help:
+  - **#general-dev** - Technical questions and feature discussions
+  - **#bugs-issues** - Get help with bugs before filing issues
+- 💬 Ask questions in [GitHub Discussions](https://github.com/bmadcode/bmad-method/discussions)
+- 🐛 Report bugs using the [bug report template](https://github.com/bmadcode/bmad-method/issues/new?template=bug_report.md)
+- 💡 Suggest features using the [feature request template](https://github.com/bmadcode/bmad-method/issues/new?template=feature_request.md)
 - 📖 Read the full [Contributing Guidelines](../CONTRIBUTING.md)
 
 ## Example: Good vs Bad PRs