bmad-method 5.1.3 → 6.0.0-alpha.0

package/CONTRIBUTING.md

@@ -1,65 +1,90 @@
-# Contributing to this project
+# Contributing to BMad
 
-Thank you for considering contributing to this project! This document outlines the process for contributing and some guidelines to follow.
-
-🆕 **New to GitHub or pull requests?** Check out our [beginner-friendly Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) first!
-
-📋 **Before contributing**, please read our [Guiding Principles](docs/GUIDING-PRINCIPLES.md) to understand the BMad Method's core philosophy and architectural decisions.
-
-Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements.
+Thank you for considering contributing to the BMad project! We believe in **Human Amplification, Not Replacement** - bringing out the best thinking in both humans and AI through guided collaboration.
 
 💬 **Discord Community**: Join our [Discord server](https://discord.gg/gk8jAdXWmj) for real-time discussions:
 
 - **#general-dev** - Technical discussions, feature ideas, and development questions
 - **#bugs-issues** - Bug reports and issue discussions
 
-## Code of Conduct
+## Our Philosophy
+
+### BMad Core™: Universal Foundation
+
+BMad Core empowers humans and AI agents working together in true partnership across any domain through our **C.O.R.E. Framework** (Collaboration Optimized Reflection Engine):
+
+- **Collaboration**: Human-AI partnership where both contribute unique strengths
+- **Optimized**: The collaborative process refined for maximum effectiveness
+- **Reflection**: Guided thinking that helps discover better solutions and insights
+- **Engine**: The powerful framework that orchestrates specialized agents and workflows
+
+### BMad Method™: Agile AI-Driven Development
+
+The BMad Method is the flagship bmad module for agile AI-driven software development. It emphasizes thorough planning and solid architectural foundations to provide detailed context for developer agents, mirroring real-world agile best practices.
+
+### Core Principles
+
+**Partnership Over Automation** - AI agents act as expert coaches, mentors, and collaborators who amplify human capability rather than replace it.
+
+**Bidirectional Guidance** - Agents guide users through structured workflows while users push agents with advanced prompting. Both sides actively work to extract better information from each other.
+
+**Systems of Workflows** - BMad Core builds comprehensive systems of guided workflows with specialized agent teams for any domain.
 
-By participating in this project, you agree to abide by our Code of Conduct. Please read it before participating.
+**Tool-Agnostic Foundation** - BMad Core remains tool-agnostic, providing stable, extensible groundwork that adapts to any domain.
 
-## How to Contribute
+## What Makes a Good Contribution?
+
+Every contribution should strengthen human-AI collaboration. Ask yourself: **"Does this make humans and AI better together?"**
+
+**✅ Contributions that align:**
+
+- Enhance universal collaboration patterns
+- Improve agent personas and workflows
+- Strengthen planning and context continuity
+- Increase cross-domain accessibility
+- Add domain-specific modules leveraging BMad Core
+
+**❌ What detracts from our mission:**
+
+- Purely automated solutions that sideline humans
+- Tools that don't improve the partnership
+- Complexity that creates barriers to adoption
+- Features that fragment BMad Core's foundation
+
+## Before You Contribute
 
 ### Reporting Bugs
 
 1. **Check existing issues** first to avoid duplicates
-2. **Use the bug report template** when creating a new issue - it will guide you through providing:
+2. **Consider discussing in Discord** (#bugs-issues channel) for quick help
+3. **Use the bug report template** when creating a new issue - it guides you through providing:
    - Clear bug description
    - Steps to reproduce
    - Expected vs actual behavior
    - Model/IDE/BMad version details
    - Screenshots or links if applicable
-3. **Consider discussing in Discord** (#bugs-issues channel) for quick help
 4. **Indicate if you're working on a fix** to avoid duplicate efforts
 
-### Suggesting Features
+### Suggesting Features or New Modules
 
 1. **Discuss first in Discord** (#general-dev channel) - the feature request template asks if you've done this
 2. **Check existing issues and discussions** to avoid duplicates
-3. **Use the feature request template** when creating an issue - it will guide you through:
-   - Confirming Discord discussion
-   - Describing the problem it solves
-   - Explaining your solution
-   - Listing alternatives considered
-4. **Be specific** about why this feature would benefit the BMad community
+3. **Use the feature request template** when creating an issue
+4. **Be specific** about why this feature would benefit the BMad community and strengthen human-AI collaboration
 
-### Pull Request Process
+### Before Starting Work
 
-⚠️ **Before starting work:**
+⚠️ **Required before submitting PRs:**
 
 1. **For bugs**: Check if an issue exists (create one using the bug template if not)
-2. **For features**: Ensure you've discussed in Discord (#general-dev) AND created a feature request issue
+2. **For features**: Discuss in Discord (#general-dev) AND create a feature request issue
 3. **For large changes**: Always open an issue first to discuss alignment
 
-Please only propose small granular commits! If its large or significant, please discuss in the discussions tab and open up an issue first. I do not want you to waste your time on a potentially very large PR to have it rejected because it is not aligned or deviates from other planned changes. Communicate and lets work together to build and improve this great community project!
-
-**Important**: All contributions must align with our [Guiding Principles](docs/GUIDING-PRINCIPLES.md). Key points:
+Please propose small, granular changes! For large or significant changes, discuss in Discord and open an issue first. This prevents wasted effort on PRs that may not align with planned changes.
 
-- Keep dev agents lean - they need context for coding, not documentation
-- Web/planning agents can be larger with more complex tasks
-- Everything is natural language (markdown) - no code in core framework
-- Use expansion packs for domain-specific features
+## Pull Request Guidelines
 
-#### Which Branch for Your PR?
+### Which Branch?
 
 **Submit to `next` branch** (most contributions):
 
@@ -69,7 +94,7 @@ Please only propose small granular commits! If its large or significant, please
 - ♻️ Code refactoring
 - ⚡ Performance improvements
 - 🧪 New tests
-- 🎁 New expansion packs
+- 🎁 New bmad modules
 
 **Submit to `main` branch** (critical only):
 
@@ -80,7 +105,7 @@ Please only propose small granular commits! If its large or significant, please
 
 **When in doubt, submit to `next`**. We'd rather test changes thoroughly before they hit stable.
 
-#### PR Size Guidelines
+### PR Size Guidelines
 
 - **Ideal PR size**: 200-400 lines of code changes
 - **Maximum PR size**: 800 lines (excluding generated files)
@@ -88,7 +113,7 @@ Please only propose small granular commits! If its large or significant, please
 - **If your change is larger**: Break it into multiple smaller PRs that can be reviewed independently
 - **Related changes**: Even related changes should be separate PRs if they deliver independent value
 
-#### Breaking Down Large PRs
+### Breaking Down Large PRs
 
 If your change exceeds 800 lines, use this checklist to split it:
 
@@ -107,30 +132,30 @@ Example breakdown:
 3. PR #3: Implement new feature using refactored code (300 lines)
 4. PR #4: Add comprehensive tests (200 lines)
 
-**Note**: PRs #1 and #4 could be submitted simultaneously since they deliver independent value and don't depend on each other's merge order.
-
-#### Pull Request Steps
+**Note**: PRs #1 and #4 could be submitted simultaneously since they deliver independent value.
 
-1. Fork the repository
-2. Create a new branch (`git checkout -b feature/your-feature-name`)
-3. Make your changes
-4. Run any tests or linting to ensure quality
-5. Commit your changes with clear, descriptive messages following our commit message convention
-6. Push to your branch (`git push origin feature/your-feature-name`)
-7. Open a Pull Request against the main branch
-
-## Issue Templates
-
-We use GitHub issue templates to ensure all necessary information is provided:
-
-- **Bug Reports**: Automatically guides you through providing reproduction steps, environment details, and expected behavior
-- **Feature Requests**: Requires Discord discussion confirmation and asks for problem/solution descriptions
-
-Using these templates helps maintainers understand and address your contribution faster.
-
-## Pull Request Description Guidelines
+### Pull Request Process
 
-Keep PR descriptions short and to the point following this template:
+#### New to Pull Requests?
+
+If you're new to GitHub or pull requests, here's a quick guide:
+
+1. **Fork the repository** - Click the "Fork" button on GitHub to create your own copy
+2. **Clone your fork** - `git clone https://github.com/YOUR-USERNAME/bmad-method.git`
+3. **Create a new branch** - Never work on `main` directly!
+   ```bash
+   git checkout -b fix/description
+   # or
+   git checkout -b feature/description
+   ```
+4. **Make your changes** - Edit files, keeping changes small and focused
+5. **Commit your changes** - Use clear, descriptive commit messages
+   ```bash
+   git add .
+   git commit -m "fix: correct typo in README"
+   ```
+6. **Push to your fork** - `git push origin fix/description`
+7. **Create the Pull Request** - Go to your fork on GitHub and click "Compare & pull request"
 
 ### PR Description Template
 
@@ -148,9 +173,8 @@ Fixes #[issue number] (if applicable)
 
 ## How
 
-[2-3 bullets listing HOW you implemented it]
+## [2-3 bullets listing HOW you implemented it]
 
--
 -
 -
 
@@ -165,7 +189,7 @@ Fixes #[issue number] (if applicable)
 
 ❌ **Bad Example:**
 
-> This revolutionary PR introduces a paradigm-shifting enhancement to the system's architecture by implementing a state-of-the-art solution that leverages cutting-edge methodologies to optimize performance metrics and deliver unprecedented value to stakeholders through innovative approaches...
+> This revolutionary PR introduces a paradigm-shifting enhancement to the system's architecture by implementing a state-of-the-art solution that leverages cutting-edge methodologies to optimize performance metrics...
 
 ✅ **Good Example:**
 
@@ -177,7 +201,7 @@ Fixes #[issue number] (if applicable)
 > - Throws clear error with dependency chain
 >   **Testing:** Tested with circular deps between 3 agents
 
-## Commit Message Convention
+### Commit Message Convention
 
 Use conventional commits format:
 
@@ -199,10 +223,56 @@ Each commit should represent one logical change:
 - **Don't:** Mix refactoring with bug fixes
 - **Don't:** Combine unrelated changes
 
+## What Makes a Good Pull Request?
+
+✅ **Good PRs:**
+
+- Change one thing at a time
+- Have clear, descriptive titles
+- Explain what and why in the description
+- Include only the files that need to change
+- Reference related issue numbers
+
+❌ **Avoid:**
+
+- Changing formatting of entire files
+- Multiple unrelated changes in one PR
+- Copying your entire project/repo into the PR
+- Changes without explanation
+- Working directly on `main` branch
+
+## Common Mistakes to Avoid
+
+1. **Don't reformat entire files** - only change what's necessary
+2. **Don't include unrelated changes** - stick to one fix/feature per PR
+3. **Don't paste code in issues** - create a proper PR instead
+4. **Don't submit your whole project** - contribute specific improvements
+
 ## Code Style
 
 - Follow the existing code style and conventions
 - Write clear comments for complex logic
+- Keep dev agents lean - they need context for coding, not documentation
+- Web/planning agents can be larger with more complex tasks
+- Everything is natural language (markdown) - no code in core framework
+- Use bmad modules for domain-specific features
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by our Code of Conduct. We foster a collaborative, respectful environment focused on building better human-AI partnerships.
+
+## Need Help?
+
+- 💬 Join our [Discord Community](https://discord.gg/gk8jAdXWmj):
+  - **#general-dev** - Technical questions and feature discussions
+  - **#bugs-issues** - Get help with bugs before filing issues
+- 🐛 Report bugs using the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md)
+- 💡 Suggest features using the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md)
+- 📖 Browse the [GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions)
+
+---
+
+**Remember**: We're here to help! Don't be afraid to ask questions. Every expert was once a beginner. Together, we're building a future where humans and AI work better together.
 
 ## License
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Brian AKA BMad AKA BMad Code
+Copyright (c) 2025 BMad Code, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,8 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+TRADEMARK NOTICE:
+BMAD™, BMAD-CORE™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. The use of these 
+trademarks in this software does not grant any rights to use the trademarks 
+for any other purpose.

package/docs/codebase-flattener.md

@@ -0,0 +1,19 @@
+# Codebase Flattener Tool
+
+BMad-Core includes a powerful codebase flattener for preparing existing projects to the web for AI Analysis
+
+```bash
+# Basic usage - creates flattened-codebase.xml
+npx bmad-method flatten
+
+# Custom input/output
+npx bmad-method flatten --input /path/to/source --output project.xml
+```
+
+Features:
+
+- AI-optimized XML output format
+- Smart filtering with .gitignore respect
+- Binary file detection and exclusion
+- Real-time progress tracking
+- Comprehensive completion statistics

package/docs/ide-info/auggie.md

@@ -0,0 +1,31 @@
+# BMAD Method - Auggie CLI Instructions
+
+## Activating Agents
+
+BMAD agents can be installed in multiple locations based on your setup.
+
+### Common Locations
+
+- User Home: `~/.auggie/commands/`
+- Project: `.auggie/commands/`
+- Custom paths you selected
+
+### How to Use
+
+1. **Type Trigger**: Use `@{agent-name}` in your prompt
+2. **Activate**: Agent persona activates
+3. **Tasks**: Use `@task-{task-name}` for tasks
+
+### Examples
+
+```
+@dev - Activate development agent
+@architect - Activate architect agent
+@task-setup - Execute setup task
+```
+
+### Notes
+
+- Agents can be in multiple locations
+- Check your installation paths
+- Activation syntax same across all locations

package/docs/ide-info/claude-code.md

@@ -0,0 +1,25 @@
+# BMAD Method - Claude Code Instructions
+
+## Activating Agents
+
+BMAD agents are installed as slash commands in `.claude/commands/bmad/`.
+
+### How to Use
+
+1. **Type Slash Command**: Start with `/` to see available commands
+2. **Select Agent**: Type `/bmad-{agent-name}` (e.g., `/bmad-dev`)
+3. **Execute**: Press Enter to activate that agent persona
+
+### Examples
+
+```
+/bmad-dev - Activate development agent
+/bmad-architect - Activate architect agent
+/bmad-task-setup - Execute setup task
+```
+
+### Notes
+
+- Commands are autocompleted when you type `/`
+- Agent remains active for the conversation
+- Start new conversation to switch agents

package/docs/ide-info/cline.md

@@ -0,0 +1,31 @@
+# BMAD Method - Cline Instructions
+
+## Activating Agents
+
+BMAD agents are installed as **toggleable rules** in `.clinerules/` directory.
+
+### Important: Rules are OFF by default
+
+- Rules are NOT automatically loaded to avoid context pollution
+- You must manually enable the agent you want to use
+
+### How to Use
+
+1. **Open Rules Panel**: Click the rules icon below the chat input
+2. **Enable an Agent**: Toggle ON the specific agent rule you need (e.g., `01-core-dev`)
+3. **Activate in Chat**: Type `@{agent-name}` to activate that persona
+4. **Disable When Done**: Toggle OFF to free up context
+
+### Best Practices
+
+- Only enable 1-2 agents at a time to preserve context
+- Disable agents when switching tasks
+- Rules are numbered (01-, 02-) for organization, not priority
+
+### Example
+
+```
+Toggle ON: 01-core-dev.md
+In chat: "@dev help me refactor this code"
+When done: Toggle OFF the rule
+```

package/docs/ide-info/codex.md

@@ -0,0 +1,32 @@
+# BMAD Method - Codex Instructions
+
+## Activating Agents
+
+BMAD agents are documented in `AGENTS.md` file in project root.
+
+### CLI Mode
+
+1. **Reference Agent**: Type `@{agent-name}` in prompt
+2. **Execute Task**: Type `@task-{task-name}`
+3. **Active Session**: Agent remains active for conversation
+
+### Web Mode
+
+1. **Navigate**: Go to Agents section in web interface
+2. **Select Agent**: Click to activate agent persona
+3. **Session**: Agent active for browser session
+
+### Examples
+
+```
+@dev - Activate development agent
+@architect - Activate architect agent
+@task-setup - Execute setup task
+```
+
+### Notes
+
+- All agents documented in AGENTS.md
+- CLI: Reference with @ syntax
+- Web: Use interface to select
+- One agent active at a time

package/docs/ide-info/crush.md

@@ -0,0 +1,30 @@
+# BMAD Method - Crush Instructions
+
+## Activating Agents
+
+BMAD agents are installed as commands in `.crush/commands/bmad/`.
+
+### How to Use
+
+1. **Open Command Palette**: Use Crush command interface
+2. **Navigate**: Browse to `bmad/{module}/agents/`
+3. **Select Agent**: Choose the agent command
+4. **Execute**: Run to activate agent persona
+
+### Command Structure
+
+```
+.crush/commands/bmad/
+├── agents/          # All agents
+├── tasks/           # All tasks
+├── core/            # Core module
+│   ├── agents/
+│   └── tasks/
+└── {module}/        # Other modules
+```
+
+### Notes
+
+- Commands organized by module
+- Can browse hierarchically
+- Agent activates for session

package/docs/ide-info/cursor.md

@@ -0,0 +1,25 @@
+# BMAD Method - Cursor Instructions
+
+## Activating Agents
+
+BMAD agents are installed in `.cursor/rules/bmad/` as MDC rules.
+
+### How to Use
+
+1. **Reference in Chat**: Use `@bmad/{module}/agents/{agent-name}`
+2. **Include Entire Module**: Use `@bmad/{module}`
+3. **Reference Index**: Use `@bmad/index` for all available agents
+
+### Examples
+
+```
+@bmad/core/agents/dev - Activate dev agent
+@bmad/bmm/agents/architect - Activate architect agent
+@bmad/core - Include all core agents/tasks
+```
+
+### Notes
+
+- Rules are Manual type - only loaded when explicitly referenced
+- No automatic context pollution
+- Can combine multiple agents: `@bmad/core/agents/dev @bmad/core/agents/test`

package/docs/ide-info/gemini.md

@@ -0,0 +1,25 @@
+# BMAD Method - Gemini CLI Instructions
+
+## Activating Agents
+
+BMAD agents are concatenated in `.gemini/bmad-method/GEMINI.md`.
+
+### How to Use
+
+1. **Type Trigger**: Use `*{agent-name}` in your prompt
+2. **Activate**: Agent persona activates from the concatenated file
+3. **Continue**: Agent remains active for conversation
+
+### Examples
+
+```
+*dev - Activate development agent
+*architect - Activate architect agent
+*test - Activate test agent
+```
+
+### Notes
+
+- All agents loaded from single GEMINI.md file
+- Triggers with asterisk: `*{agent-name}`
+- Context includes all agents (may be large)

package/docs/ide-info/github-copilot.md

@@ -0,0 +1,26 @@
+# BMAD Method - GitHub Copilot Instructions
+
+## Activating Agents
+
+BMAD agents are installed as chat modes in `.github/chatmodes/`.
+
+### How to Use
+
+1. **Open Chat View**: Click Copilot icon in VS Code sidebar
+2. **Select Mode**: Click mode selector (top of chat)
+3. **Choose Agent**: Select the BMAD agent from dropdown
+4. **Chat**: Agent is now active for this session
+
+### VS Code Settings
+
+Configured in `.vscode/settings.json`:
+
+- Max requests per session
+- Auto-fix enabled
+- MCP discovery enabled
+
+### Notes
+
+- Modes persist for the chat session
+- Switch modes anytime via dropdown
+- Multiple agents available in mode selector

package/docs/ide-info/iflow.md

@@ -0,0 +1,33 @@
+# BMAD Method - iFlow CLI Instructions
+
+## Activating Agents
+
+BMAD agents are installed as commands in `.iflow/commands/bmad/`.
+
+### How to Use
+
+1. **Access Commands**: Use iFlow command interface
+2. **Navigate**: Browse to `bmad/agents/` or `bmad/tasks/`
+3. **Select**: Choose the agent or task command
+4. **Execute**: Run to activate
+
+### Command Structure
+
+```
+.iflow/commands/bmad/
+├── agents/     # Agent commands
+└── tasks/      # Task commands
+```
+
+### Examples
+
+```
+/bmad/agents/core-dev - Activate dev agent
+/bmad/tasks/core-setup - Execute setup task
+```
+
+### Notes
+
+- Commands organized by type (agents/tasks)
+- Agent activates for session
+- Similar to Crush command structure

package/docs/ide-info/kilo.md

@@ -0,0 +1,24 @@
+# BMAD Method - KiloCode Instructions
+
+## Activating Agents
+
+BMAD agents are installed as custom modes in `.kilocodemodes`.
+
+### How to Use
+
+1. **Open Project**: Modes auto-load when project opens
+2. **Select Mode**: Use mode selector in KiloCode interface
+3. **Choose Agent**: Pick `bmad-{module}-{agent}` mode
+4. **Activate**: Mode is now active
+
+### Mode Format
+
+- Mode name: `bmad-{module}-{agent}`
+- Display: `{icon} {title}`
+- Example: `bmad-core-dev` shows as `🤖 Dev`
+
+### Notes
+
+- Modes persist until changed
+- Similar to Roo Code mode system
+- Icon shows in mode selector

package/docs/ide-info/qwen.md

@@ -0,0 +1,25 @@
+# BMAD Method - Qwen Code Instructions
+
+## Activating Agents
+
+BMAD agents are concatenated in `.qwen/bmad-method/QWEN.md`.
+
+### How to Use
+
+1. **Type Trigger**: Use `*{agent-name}` in your prompt
+2. **Activate**: Agent persona activates from the concatenated file
+3. **Continue**: Agent remains active for conversation
+
+### Examples
+
+```
+*dev - Activate development agent
+*architect - Activate architect agent
+*test - Activate test agent
+```
+
+### Notes
+
+- All agents loaded from single QWEN.md file
+- Triggers with asterisk: `*{agent-name}`
+- Similar to Gemini CLI setup

package/docs/ide-info/roo.md

@@ -0,0 +1,27 @@
+# BMAD Method - Roo Code Instructions
+
+## Activating Agents
+
+BMAD agents are installed as custom modes in `.roomodes`.
+
+### How to Use
+
+1. **Open Project**: Modes auto-load when project opens
+2. **Select Mode**: Use mode selector in Roo interface
+3. **Choose Agent**: Pick `bmad-{module}-{agent}` mode
+4. **Activate**: Mode is now active with configured permissions
+
+### Permission Levels
+
+Modes are configured with file edit permissions:
+
+- Development files only
+- Configuration files only
+- Documentation files only
+- All files (if configured)
+
+### Notes
+
+- Modes persist until changed
+- Each mode has specific file access rights
+- Icon shows in mode selector for easy identification