ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

remove v3 docs, clarify contribution guidlines, fix teams to use proper bmad agent.

Browse Source
This commit is contained in:
Brian Madison
2025-06-12 19:47:38 -05:00
parent 576f05a9d0
commit 70db485a10
9 changed files with 13 additions and 614 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/CONTRIBUTING.md
View File

@@ -22,6 +22,8 @@ By participating in this project, you agree to abide by our Code of Conduct. Ple
### Pull Request Process
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!
1. Fork the repository
2. Create a new branch (`git checkout -b feature/your-feature-name`)
3. Make your changes
@@ -32,13 +34,12 @@ By participating in this project, you agree to abide by our Code of Conduct. Ple
## Commit Message Convention
[Commit Convention](./docs/commit.md)
PRs with a wall of AI Generated marketing hype that is unclear in what is being proposed will be closed and rejected. Your best change to contribute is with a small clear PR description explaining, what is the issue being solved or gap in the system being filled. Also explain how it leads to the core guiding principles of the project.
## Code Style
- Follow the existing code style and conventions
- Write clear comments for complex logic
- Ensure all tests pass before submitting
## License

123
docs/ide-setup.md
View File

@@ -1,123 +0,0 @@
# IDE Instructions for Agent Configuration
The Uber Orchestrating BMad Agent is mainly recommended for use in Gemini Web, especially for working on the brief, PRD, high level Epics, Stories, Web Deign and Prompt Output. BUT - Everything can also be done in the IDE if desired, see the BMad Agent setup section below.
## Single Agent
Create a custom mode following the docs, and paste in any of the agents that end with .ide.md from the personas folder.
## Tasks
As cursor currently limits the total number of allowed custom modes - you can utilize tasks to handle 1 off actions you might want an agent to perform. Just drag the task into any agent chat window and ask the agent to complete the task.
## BMad Agent
The BMad Agent requires the full bmad agent folder to be at the root of your project. Set up of the orchestrator simply requires copy of the markdown content of ide-bmad-orchestrator.md the same way you would do the Single Agent.
## Setting Up Custom Modes in Cursor
To use custom agent modes - review the docs here: https://docs.cursor.com/chat/custom-modes.
- Specifically you will need to enable Custom Modes in: Settings → Features → Chat → Custom modes
- Custom Agents can be created and configured with specific tools, models, and custom prompts
- Cursor allows creating custom agents through a GUI interface
NOTE from Cursor: "We’re considering adding a .cursor/modes.json file to your project to make it easier to create and share custom modes."
## Windsurf
### Setting Up Custom Modes in Windsurf
1. **Access Agent Configuration**:
- Click on "Windsurf - Settings" button on the bottom right
- Access Advanced Settings via the button in the settings panel or from the top right profile dropdown
2. **Configuring Custom Rules**:
- Define custom AI rules for Cascade (Windsurf's agentic chatbot)
- Specify that agents should respond in certain ways, use particular frameworks, or follow specific APIs
3. **Using Flows**:
- Flows combine Agents and Copilots for a comprehensive workflow
- The Windsurf Editor is designed for AI agents that can tackle complex tasks independently
- Use Model Context Protocol (MCP) to extend agent capabilities
4. **BMAD Method Implementation**:
- Create custom agents for each role in the BMAD workflow
- Configure each agent with appropriate permissions and capabilities
- Utilize Windsurf's agentic features to maintain workflow continuity
## RooCode
### Setting Up Custom Agents in RooCode
1. **Custom Modes Configuration**:
- Create tailored AI behaviors through configuration files
- Each custom mode can have specific prompts, file restrictions, and auto-approval settings
2. **Creating BMAD Method Agents**:
- Create distinct modes for each BMAD role (Analyst, PM, Architect, Design Architect, PO, SM, Dev, etc...)
- Customize each mode with tailored prompts specific to their role
- Configure file restrictions appropriate to each role (e.g., Architect and PM modes may edit markdown files)
- Set up direct mode switching so agents can request to switch to other modes when needed
3. **Model Configuration**:
- Configure different models per mode (e.g., advanced model for architecture vs. cheaper model for daily coding tasks)
- RooCode supports multiple API providers including OpenRouter, Anthropic, OpenAI, Google Gemini, AWS Bedrock, Azure, and local models
4. **Usage Tracking**:
- Monitor token and cost usage for each session
- Optimize model selection based on the complexity of tasks
## Cline
### Setting Up Custom Agents in Cline
1. **Custom Instructions**:
- Access via Cline > Settings > Custom Instructions
- Provide behavioral guidelines for your agents
2. **Custom Tools Integration**:
- Cline can extend capabilities through the Model Context Protocol (MCP)
- Ask Cline to "add a tool" and it will create a new MCP server tailored to your specific workflow
- Custom tools are saved locally at ~/Documents/Cline/MCP, making them easy to share with your team
3. **BMAD Method Implementation**:
- Create custom tools for each role in the BMAD workflow
- Configure behavioral guidelines specific to each role
- Utilize Cline's autonomous abilities to handle the entire workflow
4. **Model Selection**:
- Configure Cline to use different models based on the role and task complexity
## GitHub Copilot
### Custom Agent Configuration (Coming Soon)
https://github.com/microsoft/vscode-copilot-release/issues/9452
GitHub Copilot is currently developing its Copilot Extensions system, which will allow for custom agent/mode creation:
1. **Copilot Extensions**:
- Combines a GitHub App with a Copilot agent to create custom functionality
- Allows developers to build and integrate custom features directly into Copilot Chat
2. **Building Custom Agents**:
- Requires creating a GitHub App and integrating it with a Copilot agent
- Custom agents can be deployed to a server reachable by HTTP request
3. **Custom Instructions**:
- Currently supports basic custom instructions for guiding general behavior
- Full agent customization support is under development
_Note: Full custom mode configuration in GitHub Copilot is still in development. Check GitHub's documentation for the latest updates._

BIN
docs/images/gem-setup.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 99 KiB

315
docs/instruction.md
View File

@@ -1,315 +0,0 @@
# Instructions
> **📚 Note:** This documentation covers both legacy v3 and modern v4 systems. For new projects, use the v4 system with `bmad-core/` resources and the new build CLI.
- [V4 Build System (Recommended)](#v4-build-system-recommended)
- [Setting up Web Agent Orchestrator (V3 Legacy)](#setting-up-web-agent-orchestrator-v3-legacy)
- [IDE Agent Setup and Usage](#ide-agent-setup-and-usage)
- [Tasks Setup and Usage](#tasks)
## V4 Build System (Recommended)
The v4 system uses modular configurations and optimized dependency resolution:
```bash
# Build all web bundles
node tools/cli.js build:web
# List available agents
node tools/cli.js list:agents
# Build specific bundle
node tools/cli.js build:bundle --name "planning"
```
**Key Resources:**
- `bmad-core/`: Portable resources for copying to your projects
- `agents/`: Individual agent configurations
- `bundles/`: Bundle configurations for different use cases
- `dist/`: Optimized build outputs
## Setting up Web Agent Orchestrator
The BMAD v4 build system provides a powerful, modular approach to creating agent bundles for web-based AI platforms. It features automatic dependency resolution, resource optimization, and support for both team bundles and individual agents.
### Overview
The v4 build process is managed by the CLI tool in `tools/cli.js`. This uses a modular architecture with dependency resolution and bundle optimization to create web-compatible agent bundles.
### Quick Start Options
1. **Use Pre-built Bundles** (No installation required)
- Find ready-to-use bundles in `/web-bundles/`
- Upload directly to Gemini or ChatGPT
2. **Build Custom Bundles** (Requires Node.js)
- Clone the repository
- Run `npm install`
- Run `npm run build`
### Prerequisites (For Custom Builds Only)
- **Node.js**: Version 14 or higher
- **npm**: Comes with Node.js
### Configuration (YAML-based)
Agents are configured using YAML files in the `/agents/` directory:
```yaml
agent:
name: John # Display name
id: pm # Unique identifier
title: Product Manager # Role title
persona: pm # References bmad-core/personas/pm.md
dependencies:
tasks: # From bmad-core/tasks/
- create-prd
- correct-course
templates: # From bmad-core/templates/
- prd-tmpl
checklists: # From bmad-core/checklists/
- pm-checklist
```
Team bundles are defined in the `/agent-teams/` directory as `team-*.yml` files:
```yaml
bundle:
name: Full Team Bundle
agents:
- bmad
- analyst
- pm
- architect
- po
- sm
- dev
- qa
```
### Directory Structure
The BMAD v4 system uses this structure:
```
BMAD-METHOD/
├── agents/ # Individual agent YAML configurations
├── agent-teams/ # Team bundle YAML configurations
├── bmad-core/ # Core resources
│ ├── personas/ # Agent personality definitions
│ ├── tasks/ # Reusable task instructions
│ ├── templates/ # Document templates
│ ├── checklists/ # Quality checklists
│ └── data/ # Knowledge bases
├── tools/ # Build tooling
├── dist/ # Build output (gitignored)
└── web-bundles/ # Pre-built bundles (in source control)
```
### Running the Build
From the BMAD-METHOD repository root:
```bash
# Build all bundles and agents
npm run build
# Build with sample update (also outputs to web-bundles)
npm run build:sample-update
# List available agents
npm run list:agents
# Validate configurations
npm run validate
```
The build system automatically:
- Resolves all dependencies
- Optimizes shared resources
- Validates configurations
- Creates self-contained bundles
### Build Output
The build creates files in `/dist/`:
- **`/dist/teams/`**: Team bundle files
- `full-organization-team-bundle.txt`
- `development-team-bundle.txt`
- etc.
- **`/dist/agents/`**: Individual agent files
- `pm.txt`
- `architect.txt`
- `dev.txt`
- etc.
Each file is self-contained and ready to upload to your AI platform.
### Uploading to AI Platforms
#### For Gemini:
1. Create a new Gem
2. Upload the bundle file from `/dist/teams/` or `/dist/agents/`
3. The bundle contains everything needed - no additional files required
#### For ChatGPT:
1. Create a custom GPT
2. Attach the bundle file as knowledge
3. The GPT will have access to all agents and resources
### How the Orchestrator Works
The BMAD Orchestrator can transform into any agent defined in your bundle. It uses:
- The BMAD persona as its base personality
- Slash commands for agent switching (`/pm`, `/architect`, etc.)
- Access to all bundled resources (tasks, templates, checklists)
### Customizing Agents
To create or modify agents:
1. **Create/Edit YAML Configuration** in `/agents/`:
```yaml
agent:
name: YourAgentName
id: your-agent
title: Your Agent Title
description: What this agent does
persona: your-persona # References bmad-core/personas/your-persona.md
customize: "Optional personality tweaks"
dependencies:
tasks:
- task-name
templates:
- template-name
checklists:
- checklist-name
data:
- data-file
```
2. **Create Required Resources** in `bmad-core/`:
- Add persona file to `personas/`
- Add any new tasks to `tasks/`
- Add templates to `templates/`
3. **Build and Test**:
```bash
npm run validate
npm run build
```
## IDE Agent Setup and Usage
The IDE Agents in V3 are designed for optimal performance within IDE environments like Windsurf and Cursor, with a focus on smaller agent sizes and efficient context management.
### Standalone IDE Agents
You can use specialized standalone IDE agents, such as the `sm.ide.md` (Scrum Master) and `dev.ide.md` (Developer), for specific roles like story generation or development tasks. These, or any general IDE agent, can also directly reference and execute tasks by providing the agent with the task definition from your `docs/tasks/` folder.
### IDE Agent Orchestrator (`ide-bmad-orchestrator.md`)
A powerful alternative is the `ide-bmad-orchestrator.md`. This agent provides the flexibility of the web orchestrator—allowing a single IDE agent to embody multiple personas—but **without requiring any build step.** It dynamically loads its configuration and all associated resources.
#### How the IDE Orchestrator Works
1. **Configuration (`ide-bmad-orchestrator.cfg.md`):**
The orchestrator's behavior is primarily driven by a Markdown configuration file (e.g., `bmad-core/ide-bmad-orchestrator.cfg.md`, the path to which is specified within the `ide-bmad-orchestrator.md` itself). This config file has two main parts:
- **Data Resolution:**
Located at the top of the config file, this section defines key-value pairs for base paths. These paths tell the orchestrator where to find different types of asset files (personas, tasks, checklists, templates, data).
```markdown
# Configuration for IDE Agents
## Data Resolution
agent-root: (project-root)/bmad-core
checklists: (agent-root)/checklists
data: (agent-root)/data
personas: (agent-root)/personas
tasks: (agent-root)/tasks
templates: (agent-root)/templates
NOTE: All Persona references and task markdown style links assume these data resolution paths unless a specific path is given.
Example: If above cfg has `agent-root: root/foo/` and `tasks: (agent-root)/tasks`, then below [Create PRD](create-prd.md) would resolve to `root/foo/tasks/create-prd.md`
```
The `(project-root)` placeholder is typically interpreted as the root of your current workspace.
- **Agent Definitions:**
Following the `Data Resolution` section, the file lists definitions for each specialized agent the orchestrator can become. Each agent is typically introduced with a `## Title:` Markdown heading.
Key attributes for each agent include:
- `Name`: The specific name of the agent (e.g., `- Name: Larry`).
- `Customize`: A string providing specific personality traits or behavioral overrides for the agent (e.g., `- Customize: "You are a bit of a know-it-all..."`).
- `Description`: A brief summary of the agent's role and capabilities.
- `Persona`: The filename of the Markdown file containing the agent's core persona definition (e.g., `- Persona: "analyst.md"`). This file is located using the `personas:` path from the `Data Resolution` section.
- `Tasks`: A list of tasks the agent can perform. Each task is a Markdown link:
- The link text is the user-friendly task name (e.g., `[Create PRD]`).
- The link target is either a Markdown filename for an external task definition (e.g., `(create-prd.md)`), resolved using the `tasks:` path, or a special string like `(In Analyst Memory Already)` indicating the task logic is part of the persona's main definition.
Example:
```markdown
## Title: Product Owner AKA PO
- Name: Curly
- Persona: "po.md"
- Tasks:
- [Create PRD](create-prd.md)
- [Create Next Story](create-next-story.md)
```
2. **Operational Workflow (inside `ide-bmad-orchestrator.md`):**
- **Initialization:** Upon activation in your IDE, the `ide-bmad-orchestrator.md` first loads and parses its specified configuration file (`ide-bmad-orchestrator.cfg.md`). If this fails, it will inform you and halt.
- **Greeting & Persona Listing:** It will greet you. If your initial instruction isn't clear or if you ask, it will list the available specialist personas (by `Title`, `Name`, and `Description`) and the `Tasks` each can perform, all derived from the loaded configuration.
- **Persona Activation:** When you request a specific persona (e.g., "Become the Analyst" or "I need Larry to help with research"), the orchestrator:
- Finds the persona in its configuration.
- Loads the corresponding persona file (e.g., `analyst.md`).
- Applies any `Customize:` instructions.
- Announces the activation (e.g., "Activating Analyst (Larry)...").
- **The orchestrator then fully embodies the chosen agent.** Its original orchestrator persona becomes dormant.
- **Task Execution:** Once a persona is active, it will try to match your request to one of its configured `Tasks`.
- If the task references an external file (e.g., `create-prd.md`), that file is loaded and its instructions are followed. The active persona will use the `Data Resolution` paths from the main config to find any dependent files like templates or checklists mentioned in the task file.
- If a task is marked as "In Memory" (or similar), the active persona executes it based on its internal definition.
- **Context and Persona Switching:** The orchestrator embodies only one persona at a time. If you ask to switch to a different persona while one is active, it will typically advise starting a new chat session to maintain clear context. However, it allows an explicit "override safety protocol" command if you insist on switching personas within the same chat. This terminates the current persona and re-initializes with the new one.
#### Usage Instructions for IDE Orchestrator
1. **Set up your configuration (`ide-bmad-orchestrator.cfg.md`):**
- Ensure you have an `ide-bmad-orchestrator.cfg.md` file. You can use the one located in `bmad-core/` as a template or starting point.
- Verify that the `Data Resolution` paths at the top correctly point to your asset folders (personas, tasks, templates, checklists, data) relative to your project structure.
- Define your desired agents with their `Title`, `Name`, `Customize` instructions, `Persona` file, and `Tasks`. Ensure the referenced persona and task files exist in the locations specified by your `Data Resolution` paths.
2. **Set up your persona and task files:**
- Create the Markdown files for each persona (e.g., `analyst.md`, `po.md`) in your `personas` directory.
- Create the Markdown files for each task (e.g., `create-prd.md`) in your `tasks` directory.
3. **Activate the Orchestrator:**
- In your IDE (e.g., Cursor), select the `ide-bmad-orchestrator.md` file/agent as your active AI assistant.
4. **Interact with the Orchestrator:**
- **Initial Interaction:**
- The orchestrator will greet you and confirm it has loaded its configuration.
- You can ask: "What agents are available?" or "List personas and tasks."
- **Activating a Persona:**
- Tell the orchestrator which persona you want: "I want to work with the Product Owner," or "Activate Curly," or "Become the PO."
- **Performing a Task:**
- Once a persona is active, state the task: "Create a PRD," or if the persona is "Curly" (the PO), you might say "Curly, create the next story."
- You can also combine persona activation and task request: "Curly, I need you to create a PRD."
- **Switching Personas:**
- If you need to switch: "I need to talk to the Architect now."
- The orchestrator will advise a new chat. If you want to switch in the current chat, you'll need to give an explicit override command when prompted (e.g., "Override safety protocol and switch to Architect").
- **Follow Persona Instructions:** Once a persona is active, it will guide you based on its definition and the task it's performing. Remember that resource files like templates or checklists referenced by a task will be resolved using the global `Data Resolution` paths in the `ide-bmad-orchestrator.cfg.md`.
This setup allows for a highly flexible and dynamically configured multi-persona agent directly within your IDE, streamlining various development and project management workflows.
## Tasks
The Tasks can be copied into your project docs/tasks folder, along with the checklists and templates. The tasks are meant to reduce the amount of 1 off IDE agents - you can just drop a task into chat with any agent and it will perform the 1 off task. There will be full workflow + task coming post V3 that will expand on this - but tasks and workflows are a powerful concept that will allow us to build in a lot of capabilities for our agents, without having to bloat their overall programming and context in the IDE - especially useful for tasks that are not used frequently - similar to seldom used ide rules files.

141
docs/readme.md
View File

@@ -1,141 +0,0 @@
# Expanded Documentation
## Quick Start Guide
Choose your path based on what you want to do:
### 🚀 Path 1: Use Pre-built Web Bundles (Easiest - No Installation)
Want to use BMAD agents with Gemini or ChatGPT? Just grab a pre-built bundle:
1. **Navigate to `/web-bundles/`** in this repository
- Team bundles: `/web-bundles/teams/` (full agile teams)
- Individual agents: `/web-bundles/agents/` (specific roles)
2. **Upload to your AI platform**
- Gemini: Create a new Gem, upload the bundle file
- ChatGPT: Create a custom GPT, attach the bundle file
3. **Start using immediately!**
**No Node.js, no npm, no build process needed!**
### 💻 Path 2: IDE-Only Usage (No Installation)
Just need agents in your IDE (Cursor, Windsurf)?
1. **Copy the bmad-core folder** to your project root:
```bash
cp -r /path/to/BMAD-METHOD/bmad-core /your-project-root/
```
2. **Use IDE agents directly**:
- Most common: `sm.ide.md` (story generation) and `dev.ide.md` (development)
- Find them in `bmad-core/ide-agents/`
- Copy content into your IDE's custom agent settings
**That's it! No build process required.**
### 🛠️ Path 3: Customize & Build Your Own (Installation Required)
Want to modify agents or create custom bundles?
1. **Copy bmad-core** to your project
2. **Install dependencies**: `npm install`
3. **Customize** agents in `/agents/`, team bundles in `/agent-teams/`, or resources in `/bmad-core/`
4. **Build**: `npm run build`
## When Do You Need npm install?
**You DON'T need it if:**
- Using pre-built bundles from `/web-bundles/`
- Only using IDE agents as-is
- Not modifying configurations
**You DO need it if:**
- Customizing agent YAML files
- Creating new team bundles
- Modifying bmad-core and rebuilding
## IDE Project Quickstart
For the fastest IDE setup:
1. Copy `bmad-core` to your project root
2. Set up `sm.ide.md` and `dev.ide.md` as custom agents
3. Start building!
The agents expect:
- Docs in `(project-root)/docs/`
- Stories in `(project-root)/docs/stories/`
For other agents, use the [IDE orchestrator](../bmad-core/utils/agent-switcher.ide.md) - one agent that can become any role!
[Detailed Setup Instructions](./instruction.md) | [IDE Setup Guide](./ide-setup.md)
## Advancing AI-Driven Development
Welcome to the BMAD Method v4! This latest version represents a complete architectural redesign with powerful new features while maintaining the ease of use you expect.
## What's New in v4?
### 🏗️ Complete Architectural Redesign
- **Modular build system** with dependency resolution and optimization
- **Pre-built bundles** ready to use - no installation required
- **Dual environment support** - optimized for both web UIs and IDEs
- **Bundle optimization** automatically deduplicates shared resources
### 🤖 Enhanced Agent System
- All IDE agents optimized to under 6K characters (Windsurf compatible)
- **BMAD Orchestrator** - one agent that can transform into any role
- **Slash commands** for quick agent switching (`/pm`, `/architect`, etc.)
- **Configurable agents** - customize who does what in your workflow
### 📈 Advanced Features
- **Dependency graphs** to visualize agent relationships
- **Validation system** ensures all configurations are correct
- **YAML-based configuration** for easy customization
- **Task system** keeps agents lean while providing on-demand functionality
### 🚀 Improved Workflow
- **Pre-built web bundles** in `/web-bundles/` - just upload and use
- **Better prompting techniques** for more accurate artifacts
- **Flexible methodology** - define Agile your way
Get started with the default setup or customize everything - the choice is yours! See the [detailed instructions](./instruction.md) for configuration options.
## What is the BMad Method?
The BMad Method is a revolutionary approach that elevates "vibe coding" to advanced project planning to ensure your developer agents can start and completed advanced projects with very explicit guidance. It provides a structured yet flexible framework to plan, execute, and manage software projects using a team of specialized AI agents.
This method and tooling is so much more than just a task runner - this is a refined tool that will help you bring out your best ideas, define what you really are to build, and execute on it! From ideation, to PRD creation, to the technical decision making - this will help you do it all with the power of advanced LLM guidance.
The method is designed to be tool-agnostic in principle, with agent instructions and workflows adaptable to various AI platforms and IDEs.
## Agile Agents
Agents are programmed either directly self contained to drop right into an agent config in the ide - or they can be configured as programmable entities the orchestrating agent can become.
### Web Agents
Gemini 2.5 or Open AI customGPTs are created by running the node build script to generate output to a build folder. This output is the full package to create the orchestrator web agent.
See the detailed [Web Orchestration Setup and Usage Instructions](./instruction.md#setting-up-web-agent-orchestrator)
### IDE Agents
There are dedicated self contained agents that are stand alone, and also an IDE version of an orchestrator. For there standalone, there are:
- [Dev IDE Agent](../bmad-core/personas/dev.ide.md)
- [Story Generating SM Agent](../bmad-core/personas/sm.ide.md)
If you want to use the other agents, you can use the other agents from that folder - but some will be larger than Windsurf allows - and there are many agents. So its recommended to either use 1 off tasks - OR even better - use the IDE Orchestrator Agent. See these [set up and Usage instructions for IDE Orchestrator](./instruction.md#ide-agent-setup-and-usage).
## Tasks
Located in `bmad-core/tasks/`, these self-contained instruction sets allow IDE agents or the orchestrators configured agents to perform specific jobs. These also can be used as one off commands with a vanilla agent in the ide by just referencing the task and asking the agent to perform it.
**Purpose:**
- **Reduce Agent Bloat:** Avoid adding rarely used instructions to primary agents.
- **On-Demand Functionality:** Instruct any capable IDE agent to execute a task by providing the task file content.
- **Versatility:** Handles specific functions like running checklists, creating stories, sharding documents, indexing libraries, etc.
Think of tasks as specialized mini-agents callable by your main IDE agents.