487 lines
20 KiB
Markdown
487 lines
20 KiB
Markdown
# BMAD Knowledge Base
|
|
|
|
## Overview
|
|
|
|
BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework that combines AI agents with Agile development methodologies. The v4 system introduces a modular architecture with improved dependency management, bundle optimization, and support for both web and IDE environments.
|
|
|
|
### Key Features
|
|
|
|
- **Modular Agent System**: Specialized AI agents for each Agile role
|
|
- **Build System**: Automated dependency resolution and optimization
|
|
- **Dual Environment Support**: Optimized for both web UIs and IDEs
|
|
- **Reusable Resources**: Portable templates, tasks, and checklists
|
|
- **Slash Command Integration**: Quick agent switching and control
|
|
|
|
### When to Use BMAD
|
|
|
|
- **New Projects (Greenfield)**: Complete end-to-end development
|
|
- **Existing Projects (Brownfield)**: Feature additions and enhancements
|
|
- **Team Collaboration**: Multiple roles working together
|
|
- **Quality Assurance**: Structured testing and validation
|
|
- **Documentation**: Professional PRDs, architecture docs, user stories
|
|
|
|
## Getting Started
|
|
|
|
### Quick Start Options
|
|
|
|
#### Option 1: Web UI
|
|
**Best for**: ChatGPT, Claude, Gemini users who want to start immediately
|
|
|
|
1. Navigate to `dist/teams/`
|
|
2. Copy `team-fullstack.txt` content
|
|
3. Create new Gemini Gem or CustomGPT
|
|
4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
|
|
5. Type `/help` to see available commands
|
|
|
|
#### Option 2: IDE Integration
|
|
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
|
|
|
```bash
|
|
# Interactive installation (recommended)
|
|
npx bmad-method install
|
|
```
|
|
|
|
**Installation Steps**:
|
|
- Choose "Complete installation"
|
|
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
|
|
|
**Verify Installation**:
|
|
- `.bmad-core/` folder created with all agents
|
|
- IDE-specific integration files created
|
|
- All agent commands/rules/modes available
|
|
|
|
### Environment Selection Guide
|
|
|
|
**Use Web UI for**:
|
|
- Initial planning and documentation (PRD, architecture)
|
|
- Cost-effective document creation (especially with Gemini)
|
|
- Brainstorming and analysis phases
|
|
- Multi-agent consultation and planning
|
|
|
|
**Use IDE for**:
|
|
- Active development and coding
|
|
- File operations and project integration
|
|
- Document sharding and story management
|
|
- Implementation workflow (SM/Dev cycles)
|
|
|
|
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
|
|
|
## Core Configuration (core-config.yml)
|
|
|
|
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
|
|
|
### What is core-config.yml?
|
|
|
|
This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
|
|
|
|
- **Version Flexibility**: Work with V3, V4, or custom document structures
|
|
- **Custom Locations**: Define where your documents and shards live
|
|
- **Developer Context**: Specify which files the dev agent should always load
|
|
- **Debug Support**: Built-in logging for troubleshooting
|
|
|
|
### Key Configuration Areas
|
|
|
|
#### PRD Configuration
|
|
- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
|
|
- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
|
|
- **prdShardedLocation**: Where to find sharded epic files
|
|
- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
|
|
|
|
#### Architecture Configuration
|
|
- **architectureVersion**: v3 (monolithic) or v4 (sharded)
|
|
- **architectureSharded**: Whether architecture is split into components
|
|
- **architectureShardedLocation**: Where sharded architecture files live
|
|
|
|
#### Developer Files
|
|
- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
|
|
- **devDebugLog**: Where dev agent logs repeated failures
|
|
- **agentCoreDump**: Export location for chat conversations
|
|
|
|
### Why It Matters
|
|
|
|
1. **No Forced Migrations**: Keep your existing document structure
|
|
2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
|
|
3. **Custom Workflows**: Configure BMAD to match your team's process
|
|
4. **Intelligent Agents**: Agents automatically adapt to your configuration
|
|
|
|
### Common Configurations
|
|
|
|
**Legacy V3 Project**:
|
|
```yaml
|
|
prdVersion: v3
|
|
prdSharded: false
|
|
architectureVersion: v3
|
|
architectureSharded: false
|
|
```
|
|
|
|
**V4 Optimized Project**:
|
|
```yaml
|
|
prdVersion: v4
|
|
prdSharded: true
|
|
prdShardedLocation: docs/prd
|
|
architectureVersion: v4
|
|
architectureSharded: true
|
|
architectureShardedLocation: docs/architecture
|
|
```
|
|
|
|
## Core Philosophy
|
|
|
|
### Vibe CEO'ing
|
|
|
|
You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a singular vision. Your AI agents are your high-powered team, and your role is to:
|
|
|
|
- **Direct**: Provide clear instructions and objectives
|
|
- **Refine**: Iterate on outputs to achieve quality
|
|
- **Oversee**: Maintain strategic alignment across all agents
|
|
|
|
### Core Principles
|
|
|
|
1. **MAXIMIZE_AI_LEVERAGE**: Push the AI to deliver more. Challenge outputs and iterate.
|
|
2. **QUALITY_CONTROL**: You are the ultimate arbiter of quality. Review all outputs.
|
|
3. **STRATEGIC_OVERSIGHT**: Maintain the high-level vision and ensure alignment.
|
|
4. **ITERATIVE_REFINEMENT**: Expect to revisit steps. This is not a linear process.
|
|
5. **CLEAR_INSTRUCTIONS**: Precise requests lead to better outputs.
|
|
6. **DOCUMENTATION_IS_KEY**: Good inputs (briefs, PRDs) lead to good outputs.
|
|
7. **START_SMALL_SCALE_FAST**: Test concepts, then expand.
|
|
8. **EMBRACE_THE_CHAOS**: Adapt and overcome challenges.
|
|
|
|
### Key Workflow Principles
|
|
|
|
1. **Agent Specialization**: Each agent has specific expertise and responsibilities
|
|
2. **Clean Handoffs**: Always start fresh when switching between agents
|
|
3. **Status Tracking**: Maintain story statuses (Draft → Approved → InProgress → Done)
|
|
4. **Iterative Development**: Complete one story before starting the next
|
|
5. **Documentation First**: Always start with solid PRD and architecture
|
|
|
|
## Agent System
|
|
|
|
### Core Development Team
|
|
|
|
| Agent | Role | Primary Functions | When to Use |
|
|
| ----------- | ------------------ | --------------------------------------- | -------------------------------------- |
|
|
| `analyst` | Business Analyst | Market research, requirements gathering | Project planning, competitive analysis |
|
|
| `pm` | Product Manager | PRD creation, feature prioritization | Strategic planning, roadmaps |
|
|
| `architect` | Solution Architect | System design, technical architecture | Complex systems, scalability planning |
|
|
| `dev` | Developer | Code implementation, debugging | All development tasks |
|
|
| `qa` | QA Specialist | Test planning, quality assurance | Testing strategies, bug validation |
|
|
| `ux-expert` | UX Designer | UI/UX design, prototypes | User experience, interface design |
|
|
| `po` | Product Owner | Backlog management, story validation | Story refinement, acceptance criteria |
|
|
| `sm` | Scrum Master | Sprint planning, story creation | Project management, workflow |
|
|
|
|
### Meta Agents
|
|
|
|
| Agent | Role | Primary Functions | When to Use |
|
|
| ------------------- | ---------------- | ------------------------------------- | --------------------------------- |
|
|
| `bmad-orchestrator` | Team Coordinator | Multi-agent workflows, role switching | Complex multi-role tasks |
|
|
| `bmad-master` | Universal Expert | All capabilities without switching | Single-session comprehensive work |
|
|
|
|
### Agent Interaction Commands
|
|
|
|
#### IDE-Specific Syntax
|
|
|
|
**Agent Loading by IDE**:
|
|
- **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
|
|
- **Cursor**: `@agent-name` (e.g., `@bmad-master`)
|
|
- **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
|
|
- **Roo Code**: Select mode from mode selector (e.g., `bmad-bmad-master`)
|
|
|
|
**Chat Management Guidelines**:
|
|
- **Claude Code, Cursor, Windsurf**: Start new chats when switching agents
|
|
- **Roo Code**: Switch modes within the same conversation
|
|
|
|
**Common Task Commands**:
|
|
- `*help` - Show available commands
|
|
- `*status` - Show current context/progress
|
|
- `*exit` - Exit the agent mode
|
|
- `*shard-doc docs/prd.md prd` - Shard PRD into manageable pieces
|
|
- `*shard-doc docs/architecture.md architecture` - Shard architecture document
|
|
- `*create` - Run create-next-story task (SM agent)
|
|
|
|
**In Web UI**:
|
|
```text
|
|
/pm create-doc prd
|
|
/architect review system design
|
|
/dev implement story 1.2
|
|
/help - Show available commands
|
|
/switch agent-name - Change active agent (if orchestrator available)
|
|
```
|
|
|
|
## Team Configurations
|
|
|
|
### Pre-Built Teams
|
|
|
|
#### Team All
|
|
- **Includes**: All 10 agents + orchestrator
|
|
- **Use Case**: Complete projects requiring all roles
|
|
- **Bundle**: `team-all.txt`
|
|
|
|
#### Team Fullstack
|
|
- **Includes**: PM, Architect, Developer, QA, UX Expert
|
|
- **Use Case**: End-to-end web/mobile development
|
|
- **Bundle**: `team-fullstack.txt`
|
|
|
|
#### Team No-UI
|
|
- **Includes**: PM, Architect, Developer, QA (no UX Expert)
|
|
- **Use Case**: Backend services, APIs, system development
|
|
- **Bundle**: `team-no-ui.txt`
|
|
|
|
## Core Architecture
|
|
|
|
### System Overview
|
|
|
|
The BMAD-Method is built around a modular architecture centered on the `bmad-core` directory, which serves as the brain of the entire system. This design enables the framework to operate effectively in both IDE environments (like Cursor, VS Code) and web-based AI interfaces (like ChatGPT, Gemini).
|
|
|
|
### Key Architectural Components
|
|
|
|
#### 1. Agents (`bmad-core/agents/`)
|
|
- **Purpose**: Each markdown file defines a specialized AI agent for a specific Agile role (PM, Dev, Architect, etc.)
|
|
- **Structure**: Contains YAML headers specifying the agent's persona, capabilities, and dependencies
|
|
- **Dependencies**: Lists of tasks, templates, checklists, and data files the agent can use
|
|
- **Startup Instructions**: Can load project-specific documentation for immediate context
|
|
|
|
#### 2. Agent Teams (`bmad-core/agent-teams/`)
|
|
- **Purpose**: Define collections of agents bundled together for specific purposes
|
|
- **Examples**: `team-all.yml` (comprehensive bundle), `team-fullstack.yml` (full-stack development)
|
|
- **Usage**: Creates pre-packaged contexts for web UI environments
|
|
|
|
#### 3. Workflows (`bmad-core/workflows/`)
|
|
- **Purpose**: YAML files defining prescribed sequences of steps for specific project types
|
|
- **Types**: Greenfield (new projects) and Brownfield (existing projects) for UI, service, and fullstack development
|
|
- **Structure**: Defines agent interactions, artifacts created, and transition conditions
|
|
|
|
#### 4. Reusable Resources
|
|
- **Templates** (`bmad-core/templates/`): Markdown templates for PRDs, architecture specs, user stories
|
|
- **Tasks** (`bmad-core/tasks/`): Instructions for specific repeatable actions like "shard-doc" or "create-next-story"
|
|
- **Checklists** (`bmad-core/checklists/`): Quality assurance checklists for validation and review
|
|
- **Data** (`bmad-core/data/`): Core knowledge base and technical preferences
|
|
|
|
### Dual Environment Architecture
|
|
|
|
#### IDE Environment
|
|
|
|
- Users interact directly with agent markdown files
|
|
- Agents can access all dependencies dynamically
|
|
- Supports real-time file operations and project integration
|
|
- Optimized for development workflow execution
|
|
|
|
#### Web UI Environment
|
|
|
|
- Uses pre-built bundles from `dist/teams` for stand alone 1 upload files for all agents and their assest with an orchestrating agent
|
|
- Single text files containing all agent dependencies are in `dist/agents/` - these are unnecessary unless you want to create a web agent that is only a single agent and not a team
|
|
- Created by the web-builder tool for upload to web interfaces
|
|
- Provides complete context in one package
|
|
|
|
### Template Processing System
|
|
|
|
BMAD employs a sophisticated template system with three key components:
|
|
|
|
1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
|
|
2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
|
|
3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
|
|
|
|
**Template Features**:
|
|
|
|
- **Self-contained**: Templates embed both output structure and processing instructions
|
|
- **Variable Substitution**: `{{placeholders}}` for dynamic content
|
|
- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
|
|
- **Interactive Refinement**: Built-in elicitation processes for quality improvement
|
|
|
|
### Technical Preferences Integration
|
|
|
|
The `technical-preferences.md` file serves as a persistent technical profile that:
|
|
- Ensures consistency across all agents and projects
|
|
- Eliminates repetitive technology specification
|
|
- Provides personalized recommendations aligned with user preferences
|
|
- Evolves over time with lessons learned
|
|
|
|
### Build and Delivery Process
|
|
|
|
The `web-builder.js` tool creates web-ready bundles by:
|
|
1. Reading agent or team definition files
|
|
2. Recursively resolving all dependencies
|
|
3. Concatenating content into single text files with clear separators
|
|
4. Outputting ready-to-upload bundles for web AI interfaces
|
|
|
|
This architecture enables seamless operation across environments while maintaining the rich, interconnected agent ecosystem that makes BMAD powerful.
|
|
|
|
## Complete Development Workflow
|
|
|
|
### Planning Phase (Web UI Recommended)
|
|
|
|
**Ideal for cost efficiency, especially with Gemini:**
|
|
|
|
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
|
2. **Project Brief**: Create foundation document (Analyst or user)
|
|
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
|
4. **Architecture Design**: `/architect create-doc architecture` - Technical foundation
|
|
5. **Validation & Alignment**: `/po` run master checklist to ensure document consistency
|
|
6. **Document Preparation**: Copy final documents to project as `docs/prd.md` and `docs/architecture.md`
|
|
|
|
#### Example Planning Prompts
|
|
|
|
**For PRD Creation**:
|
|
```text
|
|
"I want to build a [type] application that [core purpose].
|
|
Help me brainstorm features and create a comprehensive PRD."
|
|
```
|
|
|
|
**For Architecture Design**:
|
|
```text
|
|
"Based on this PRD, design a scalable technical architecture
|
|
that can handle [specific requirements]."
|
|
```
|
|
|
|
### Critical Transition: Web UI to IDE
|
|
|
|
**Once planning is complete, you MUST switch to IDE for development:**
|
|
|
|
- **Why**: Development workflow requires file operations, real-time project integration, and document sharding
|
|
- **Cost Benefit**: Web UI is more cost-effective for large document creation; IDE is optimized for development tasks
|
|
- **Required Files**: Ensure `docs/prd.md` and `docs/architecture.md` exist in your project
|
|
|
|
### IDE Development Workflow
|
|
|
|
**Prerequisites**: Planning documents must exist in `docs/` folder
|
|
|
|
1. **Document Sharding**:
|
|
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
|
- If architecture exists, shard to `docs/architecture/` folder
|
|
- Results in multiple manageable documents and epic files
|
|
|
|
2. **Verify Sharded Content**:
|
|
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
|
- Source tree document and coding standards for dev agent reference
|
|
- Sharded docs for SM agent story creation
|
|
|
|
**Resulting Folder Structure**:
|
|
- `docs/prd/` - Broken down PRD sections
|
|
- `docs/architecture/` - Broken down architecture sections
|
|
- `docs/stories/` - Generated user stories
|
|
|
|
3. **Development Cycle** (Sequential, one story at a time):
|
|
|
|
**Step 1 - Story Creation**: New chat window → `@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 chat window → `@dev`
|
|
- Agent asks which story to implement
|
|
- Include story file content to save dev agent lookup time
|
|
- Dev follows tasks/subtasks, marking completion
|
|
- Dev leaves notes for SM about any deviations
|
|
- Update status to "Done"
|
|
|
|
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
|
|
|
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
|
|
|
### Status Tracking Workflow
|
|
|
|
Stories progress through defined statuses:
|
|
- **Draft** → **Approved** → **InProgress** → **Done**
|
|
|
|
Each status change requires user verification and approval before proceeding.
|
|
|
|
### Workflow Types
|
|
|
|
#### Greenfield Development
|
|
- Business analysis and market research
|
|
- Product requirements and feature definition
|
|
- System architecture and design
|
|
- Development execution
|
|
- Testing and deployment
|
|
|
|
#### Brownfield Enhancement
|
|
- Current system analysis
|
|
- Enhancement planning
|
|
- Impact assessment
|
|
- Incremental development
|
|
- Integration testing
|
|
|
|
## Document Creation Best Practices
|
|
|
|
### Required File Naming for Framework Integration
|
|
|
|
- `docs/prd.md` - Product Requirements Document
|
|
- `docs/architecture.md` - System Architecture Document
|
|
|
|
**Why These Names Matter**:
|
|
- Agents automatically reference these files during development
|
|
- Sharding tasks expect these specific filenames
|
|
- Workflow automation depends on standard naming
|
|
|
|
### Cost-Effective Document Creation Workflow
|
|
|
|
**Recommended for Large Documents (PRD, Architecture):**
|
|
|
|
1. **Use Web UI**: Create documents in web interface for cost efficiency
|
|
2. **Copy Final Output**: Save complete markdown to your project
|
|
3. **Standard Names**: Save as `docs/prd.md` and `docs/architecture.md`
|
|
4. **Switch to IDE**: Use IDE agents for development and smaller documents
|
|
|
|
### Document Sharding
|
|
|
|
Templates with Level 2 headings (`##`) can be automatically sharded:
|
|
|
|
**Original PRD**:
|
|
```markdown
|
|
## Goals and Background Context
|
|
## Requirements
|
|
## User Interface Design Goals
|
|
## Success Metrics
|
|
```
|
|
|
|
**After Sharding**:
|
|
- `docs/prd/goals-and-background-context.md`
|
|
- `docs/prd/requirements.md`
|
|
- `docs/prd/user-interface-design-goals.md`
|
|
- `docs/prd/success-metrics.md`
|
|
|
|
Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sharding.
|
|
|
|
## Usage Patterns and Best Practices
|
|
|
|
### Environment-Specific Usage
|
|
|
|
**Web UI Best For**:
|
|
- Initial planning and documentation phases
|
|
- Cost-effective large document creation
|
|
- Agent consultation and brainstorming
|
|
- Multi-agent workflows with orchestrator
|
|
|
|
**IDE Best For**:
|
|
- Active development and implementation
|
|
- File operations and project integration
|
|
- Story management and development cycles
|
|
- Code review and debugging
|
|
|
|
### Quality Assurance
|
|
|
|
- Use appropriate agents for specialized tasks
|
|
- Follow Agile ceremonies and review processes
|
|
- Maintain document consistency with PO agent
|
|
- Regular validation with checklists and templates
|
|
|
|
### Performance Optimization
|
|
|
|
- Use specific agents vs. `bmad-master` for focused tasks
|
|
- Choose appropriate team size for project needs
|
|
- Leverage technical preferences for consistency
|
|
- Regular context management and cache clearing
|
|
|
|
## Success Tips
|
|
|
|
- **Use Gemini for big picture planning** - The team-fullstack bundle provides collaborative expertise
|
|
- **Use bmad-master for document organization** - Sharding creates manageable chunks
|
|
- **Follow the SM → Dev cycle religiously** - This ensures systematic progress
|
|
- **Keep conversations focused** - One agent, one task per conversation
|
|
- **Review everything** - Always review and approve before marking complete
|
|
|
|
## Getting Help
|
|
|
|
- **Commands**: Use `/help` in any environment to see available commands
|
|
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
|
- **Documentation**: Check `docs/` folder for project-specific context
|
|
- **Community**: Discord and GitHub resources available for support
|