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

feat: v6.0.0-alpha.0 - the future is now

Browse Source
This commit is contained in:
Brian Madison
2025-09-28 23:17:07 -05:00
parent 52f6889089
commit 0a6a3f3015
747 changed files with 52759 additions and 235199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/GUIDING-PRINCIPLES.md
View File

@@ -1,91 +0,0 @@
# BMad Method Guiding Principles
The BMad Core and Method is a natural language framework for AI-assisted workflow with human in the loop processing along with software development. These principles ensure contributions maintain the method's effectiveness.
## Core Principles
### 1. Dev Agents Must Be Lean
- **Minimize dev agent dependencies**: Development agents that work in IDEs must have minimal context overhead
- **Save context for code**: Every line counts - dev agents should focus on coding, not documentation
- **Planning agents can be larger**: Planning agents (PM, Architect) used in web UI can have more complex tasks and dependencies
- **Small files, loaded on demand**: Multiple small, focused files are better than large files with many branches
### 2. Natural Language First
- **Everything is markdown**: Agents, tasks, templates - all written in plain English
- **No code in core**: The framework itself contains no programming code, only natural language instructions
- **Self-contained templates**: Templates are defined as YAML files with structured sections that include metadata, workflow configuration, and detailed instructions for content generation
### 3. Agent and Task Design
- **Agents define roles**: Each agent is a persona with specific expertise (e.g., Frontend Developer, API Developer)
- **Tasks are procedures**: Step-by-step instructions an agent follows to complete work
- **Templates are outputs**: Structured documents with embedded instructions for generation
- **Dependencies matter**: Explicitly declare only what's needed
## Practical Guidelines
### When to Add to Core
- Universal software development needs only
- Doesn't bloat dev agent contexts
- Follows existing agent/task/template patterns
### When to Create Expansion Packs
- Domain-specific needs beyond software development
- Non-technical domains (business, wellness, education, creative)
- Specialized technical domains (games, infrastructure, mobile)
- Heavy documentation or knowledge bases
- Anything that would bloat core agents
See [Expansion Packs Guide](../docs/expansion-packs.md) for detailed examples and ideas.
### Agent Design Rules
1. **Web/Planning Agents**: Can have richer context, multiple tasks, extensive templates
2. **Dev Agents**: Minimal dependencies, focused on code generation, lean task sets
3. **All Agents**: Clear persona, specific expertise, well-defined capabilities
### Task Writing Rules
1. Write clear step-by-step procedures
2. Use markdown formatting for readability
3. Keep dev agent tasks focused and concise
4. Planning tasks can be more elaborate
5. **Prefer multiple small tasks over one large branching task**
- Instead of one task with many conditional paths
- Create multiple focused tasks the agent can choose from
- This keeps context overhead minimal
6. **Reuse common tasks** - Don't create new document creation tasks
- Use the existing `create-doc` task
- Pass the appropriate YAML template with structured sections
- This maintains consistency and reduces duplication
### Template Rules
Templates follow the [BMad Document Template](../common/utils/bmad-doc-template.md) specification using YAML format:
1. **Structure**: Templates are defined in YAML with clear metadata, workflow configuration, and section hierarchy
2. **Separation of Concerns**: Instructions for LLMs are in `instruction` fields, separate from content
3. **Reusability**: Templates are agent-agnostic and can be used across different agents
4. **Key Components**:
- `template` block for metadata (id, name, version, output settings)
- `workflow` block for interaction mode configuration
- `sections` array defining document structure with nested subsections
- Each section has `id`, `title`, and `instruction` fields
5. **Advanced Features**:
- Variable substitution using `{{variable_name}}` syntax
- Conditional sections with `condition` field
- Repeatable sections with `repeatable: true`
- Agent permissions with `owner` and `editors` fields
- Examples arrays for guidance (never included in output)
6. **Clean Output**: YAML structure ensures all processing logic stays separate from generated content
## Remember
- The power is in natural language orchestration and human agent collaboration, not code
- Dev agents code, planning agents plan
- Keep dev agents lean for maximum coding efficiency
- Expansion packs handle specialized domains

19
docs/codebase-flattener.md Normal file
View File

@@ -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

219
docs/core-architecture.md
View File

@@ -1,219 +0,0 @@
# BMad Method: Core Architecture
## 1. Overview
The BMad Method is designed to provide agentic modes, tasks and templates to allow repeatable helpful workflows be it for agile agentic development, or expansion into vastly different domains. The core purpose of the project is to provide a structured yet flexible set of prompts, templates, and workflows that users can employ to guide AI agents (like Gemini, Claude, or ChatGPT) to perform complex tasks, guided discussions, or other meaningful domain specific flows in a predictable, high-quality manner.
The systems core module facilitates a full development lifecycle tailored to the challenges of current modern AI Agentic tooling:
1. **Ideation & Planning**: Brainstorming, market research, and creating project briefs.
2. **Architecture & Design**: Defining system architecture and UI/UX specifications.
3. **Development Execution**: A cyclical workflow where a Scrum Master (SM) agent drafts stories with extremely specific context and a Developer (Dev) agent implements them one at a time. This process works for both new (Greenfield) and existing (Brownfield) projects.
## 2. System Architecture Diagram
The entire BMad-Method ecosystem is designed around the installed `bmad-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments.
```mermaid
graph TD
subgraph BMad Method Project
subgraph Core Framework
A["bmad-core"]
A --> B["agents"]
A --> C["agent-teams"]
A --> D["workflows"]
A --> E["templates"]
A --> F["tasks"]
A --> G["checklists"]
A --> H["data (KB)"]
end
subgraph Tooling
I["tools/builders/web-builder.js"]
end
subgraph Outputs
J["dist"]
end
B -- defines dependencies for --> E
B -- defines dependencies for --> F
B -- defines dependencies for --> G
B -- defines dependencies for --> H
C -- bundles --> B
I -- reads from --> A
I -- creates --> J
end
subgraph Target Environments
K["IDE (Cursor, VS Code, etc.)"]
L["Web UI (Gemini, ChatGPT)"]
end
B --> K
J --> L
style A fill:#1a73e8,color:#fff
style I fill:#f9ab00,color:#fff
style J fill:#34a853,color:#fff
```
## 3. Core Components
The `bmad-core` directory contains all the definitions and resources that give the agents their capabilities.
### 3.1. Agents (`bmad-core/agents/`)
- **Purpose**: These are the foundational building blocks of the system. Each markdown file (e.g., `bmad-master.md`, `pm.md`, `dev.md`) defines the persona, capabilities, and dependencies of a single AI agent.
- **Structure**: An agent file contains a YAML header that specifies its role, persona, dependencies, and startup instructions. These dependencies are lists of tasks, templates, checklists, and data files that the agent is allowed to use.
- **Startup Instructions**: Agents can include startup sequences that load project-specific documentation from the `docs/` folder, such as coding standards, API specifications, or project structure documents. This provides immediate project context upon activation.
- **Document Integration**: Agents can reference and load documents from the project's `docs/` folder as part of tasks, workflows, or startup sequences. Users can also drag documents directly into chat interfaces to provide additional context.
- **Example**: The `bmad-master` agent lists its dependencies, which tells the build tool which files to include in a web bundle and informs the agent of its own capabilities.
### 3.2. Agent Teams (`bmad-core/agent-teams/`)
- **Purpose**: Team files (e.g., `team-all.yaml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
- **Structure**: A team file lists the agents to include. It can use wildcards, such as `"*"` to include all agents. This allows for the creation of comprehensive bundles like `team-all`.
### 3.3. Workflows (`bmad-core/workflows/`)
- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yaml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent.
- **Structure**: A workflow defines sequences for both complex and simple projects, lists the agents involved at each step, the artifacts they create, and the conditions for moving from one step to the next. It often includes a Mermaid diagram for visualization.
### 3.4. Reusable Resources (`templates`, `tasks`, `checklists`, `data`)
- **Purpose**: These folders house the modular components that are dynamically loaded by agents based on their dependencies.
- **`templates/`**: Contains markdown templates for common documents like PRDs, architecture specifications, and user stories.
- **`tasks/`**: Defines the instructions for carrying out specific, repeatable actions like "shard-doc" or "create-next-story".
- **`checklists/`**: Provides quality assurance checklists for agents like the Product Owner (`po`) or Architect.
- **`data/`**: Contains the core knowledge base (`bmad-kb.md`), technical preferences (`technical-preferences.md`), and other key data files.
#### 3.4.1. Template Processing System
A key architectural principle of BMad is that templates are self-contained and interactive - they embed both the desired document output and the LLM instructions needed to work with users. This means that in many cases, no separate task is needed for document creation, as the template itself contains all the processing logic.
The BMad framework employs a sophisticated template processing system orchestrated by three key components:
- **`template-format.md`** (`bmad-core/utils/`): Defines the foundational markup language used throughout all BMad templates. This specification establishes syntax rules for variable substitution (`{{placeholders}}`), AI-only processing directives (`[[LLM: instructions]]`), and conditional logic blocks. Templates follow this format to ensure consistent processing across the system.
- **`create-doc.md`** (`bmad-core/tasks/`): Acts as the orchestration engine that manages the entire document generation workflow. This task coordinates template selection, manages user interaction modes (incremental vs. rapid generation), enforces template-format processing rules, and handles validation. It serves as the primary interface between users and the template system.
- **`advanced-elicitation.md`** (`bmad-core/tasks/`): Provides an interactive refinement layer that can be embedded within templates through `[[LLM: instructions]]` blocks. This component offers 10 structured brainstorming actions, section-by-section review capabilities, and iterative improvement workflows to enhance content quality.
The system maintains a clean separation of concerns: template markup is processed internally by AI agents but never exposed to users, while providing sophisticated AI processing capabilities through embedded intelligence within the templates themselves.
#### 3.4.2. Technical Preferences System
BMad includes a personalization layer through the `technical-preferences.md` file in `bmad-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects.
**Purpose and Benefits:**
- **Consistency**: Ensures all agents reference the same technical preferences
- **Efficiency**: Eliminates the need to repeatedly specify preferred technologies
- **Personalization**: Agents provide recommendations aligned with user preferences
- **Learning**: Captures lessons learned and preferences that evolve over time
**Content Structure:**
The file typically includes preferred technology stacks, design patterns, external services, coding standards, and anti-patterns to avoid. Agents automatically reference this file during planning and development to provide contextually appropriate suggestions.
**Integration Points:**
- Templates can reference technical preferences during document generation
- Agents suggest preferred technologies when appropriate for project requirements
- When preferences don't fit project needs, agents explain alternatives
- Web bundles can include preferences content for consistent behavior across platforms
**Evolution Over Time:**
Users are encouraged to continuously update this file with discoveries from projects, adding both positive preferences and technologies to avoid, creating a personalized knowledge base that improves agent recommendations over time.
## 4. The Build & Delivery Process
The framework is designed for two primary environments: local IDEs and web-based AI chat interfaces. The `web-builder.js` script is the key to supporting the latter.
### 4.1. Web Builder (`tools/builders/web-builder.js`)
- **Purpose**: This Node.js script is responsible for creating the `.txt` bundles found in `dist`.
- **Process**:
1. **Resolves Dependencies**: For a given agent or team, the script reads its definition file.
2. It recursively finds all dependent resources (tasks, templates, etc.) that the agent/team needs.
3. **Bundles Content**: It reads the content of all these files and concatenates them into a single, large text file, with clear separators indicating the original file path of each section.
4. **Outputs Bundle**: The final `.txt` file is saved in the `dist` directory, ready to be uploaded to a web UI.
### 4.2. Environment-Specific Usage
- **For IDEs**: Users interact with the agents directly via their markdown files in `bmad-core/agents/`. The IDE integration (for Cursor, Claude Code, etc.) knows how to call these agents.
- **For Web UIs**: Users upload a pre-built bundle from `dist`. This single file provides the AI with the context of the entire team and all their required tools and knowledge.
## 5. BMad Workflows
### 5.1. The Planning Workflow
Before development begins, BMad follows a structured planning workflow that establishes the foundation for successful project execution:
```mermaid
graph TD
A["Start: Project Idea"] --> B{"Optional: Analyst Brainstorming"}
B -->|Yes| C["Analyst: Market Research & Analysis"]
B -->|No| D["Create Project Brief"]
C --> D["Analyst: Create Project Brief"]
D --> E["PM: Create PRD from Brief"]
E --> F["Architect: Create Architecture from PRD"]
F --> G["PO: Run Master Checklist"]
G --> H{"Documents Aligned?"}
H -->|Yes| I["Planning Complete"]
H -->|No| J["PO: Update Epics & Stories"]
J --> K["Update PRD/Architecture as needed"]
K --> G
I --> L["📁 Switch to IDE"]
L --> M["PO: Shard Documents"]
M --> N["Ready for SM/Dev Cycle"]
style I fill:#34a853,color:#fff
style G fill:#f9ab00,color:#fff
style L fill:#1a73e8,color:#fff
style N fill:#34a853,color:#fff
```
**Key Planning Phases:**
1. **Optional Analysis**: Analyst conducts market research and competitive analysis
2. **Project Brief**: Foundation document created by Analyst or user
3. **PRD Creation**: PM transforms brief into comprehensive product requirements
4. **Architecture Design**: Architect creates technical foundation based on PRD
5. **Validation & Alignment**: PO ensures all documents are consistent and complete
6. **Refinement**: Updates to epics, stories, and documents as needed
7. **Environment Transition**: Critical switch from web UI to IDE for development workflow
8. **Document Preparation**: PO shards large documents for development consumption
**Workflow Orchestration**: The `bmad-orchestrator` agent uses these workflow definitions to guide users through the complete process, ensuring proper transitions between planning (web UI) and development (IDE) phases.
### 5.2. The Core Development Cycle
Once the initial planning and architecture phases are complete, the project moves into a cyclical development workflow, as detailed in the `bmad-kb.md`. This ensures a steady, sequential, and quality-controlled implementation process.
```mermaid
graph TD
A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"]
B --> C["PO: Shard Arch"]
C --> D["Development Phase"]
D --> E["Scrum Master: Drafts next story from sharded epic"]
E --> F{"User Approval"}
F -->|Approved| G["Dev: Implement Story"]
F -->|Needs Changes| E
G --> H["Dev: Complete story Tasks"]
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
```
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.

248
docs/enhanced-ide-development-workflow.md
View File

@@ -1,248 +0,0 @@
# Enhanced IDE Development Workflow
This is a simple step-by-step guide to help you efficiently manage your development workflow using the BMad Method. The workflow integrates the Test Architect (QA agent) throughout the development lifecycle to ensure quality, prevent regressions, and maintain high standards. 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}`
## Test Architect Integration Throughout Workflow
The Test Architect (Quinn) provides comprehensive quality assurance throughout the development lifecycle. Here's how to leverage each capability at the right time.
**Command Aliases:** Documentation uses short forms (`*risk`, `*design`, `*nfr`, `*trace`) for the full commands (`*risk-profile`, `*test-design`, `*nfr-assess`, `*trace-requirements`).
### Quick Command Reference
| **Stage** | **Command** | **Purpose** | **Output** | **Priority** |
| ------------------------ | ----------- | --------------------------------------- | --------------------------------------------------------------- | --------------------------- |
| **After Story Approval** | `*risk` | Identify integration & regression risks | `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md` | High for complex/brownfield |
| | `*design` | Create test strategy for dev | `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md` | High for new features |
| **During Development** | `*trace` | Verify test coverage | `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md` | Medium |
| | `*nfr` | Validate quality attributes | `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md` | High for critical features |
| **After Development** | `*review` | Comprehensive assessment | QA Results in story + `docs/qa/gates/{epic}.{story}-{slug}.yml` | **Required** |
| **Post-Review** | `*gate` | Update quality decision | Updated `docs/qa/gates/{epic}.{story}-{slug}.yml` | As needed |
### Stage 1: After Story Creation (Before Dev Starts)
**RECOMMENDED - Set Developer Up for Success:**
```bash
# 1. RISK ASSESSMENT (Run FIRST for complex stories)
@qa *risk {approved-story}
# Identifies:
# - Technical debt impact
# - Integration complexity
# - Regression potential (1-9 scoring)
# - Mitigation strategies
# Critical for: Brownfield, API changes, data migrations
# 2. TEST DESIGN (Run SECOND to guide implementation)
@qa *design {approved-story}
# Provides:
# - Test scenarios per acceptance criterion
# - Test level recommendations (unit/integration/E2E)
# - Risk-based priorities (P0/P1/P2)
# - Test data requirements
# Share with Dev: Include in story comments or attach to ticket
```
### Stage 2: During Development (Mid-Implementation Checkpoints)
**Developer Self-Service Quality Checks:**
```bash
# 3. REQUIREMENTS TRACING (Verify coverage mid-development)
@qa *trace {story-in-progress}
# Validates:
# - All acceptance criteria have tests
# - No missing test scenarios
# - Appropriate test levels
# - Given-When-Then documentation clarity
# Run when: After writing initial tests
# 4. NFR VALIDATION (Check quality attributes)
@qa *nfr {story-in-progress}
# Assesses:
# - Security: Authentication, authorization, data protection
# - Performance: Response times, resource usage
# - Reliability: Error handling, recovery
# - Maintainability: Code quality, documentation
# Run when: Before marking "Ready for Review"
```
### Stage 3: Story Review (Quality Gate Assessment)
**REQUIRED - Comprehensive Test Architecture Review:**
**Prerequisite:** All tests green locally; lint & type checks pass.
```bash
# 5. FULL REVIEW (Standard review process)
@qa *review {completed-story}
```
**What Happens During Review:**
1. **Deep Code Analysis**
- Architecture pattern compliance
- Code quality and maintainability
- Security vulnerability scanning
- Performance bottleneck detection
2. **Active Refactoring**
- Improves code directly when safe
- Fixes obvious issues immediately
- Suggests complex refactoring for dev
3. **Test Validation**
- Coverage at all levels (unit/integration/E2E)
- Test quality (no flaky tests, proper assertions)
- Regression test adequacy
4. **Gate Decision**
- Creates: `docs/qa/gates/{epic}.{story}-{slug}.yml`
- Adds: QA Results section to story file
- Status: PASS/CONCERNS/FAIL/WAIVED
### Stage 4: Post-Review (After Addressing Issues)
**Update Gate Status After Fixes:**
```bash
# 6. GATE UPDATE (Document final decision)
@qa *gate {reviewed-story}
# Updates: Quality gate with new status
# Use when: After addressing review feedback
# Documents: What was fixed, what was waived
```
### Understanding Gate Decisions
| **Status** | **Meaning** | **Action Required** | **Can Proceed?** |
| ------------ | -------------------------------------------- | ----------------------- | ---------------- |
| **PASS** | All critical requirements met | None | ✅ Yes |
| **CONCERNS** | Non-critical issues found | Team review recommended | ⚠️ With caution |
| **FAIL** | Critical issues (security, missing P0 tests) | Must fix | ❌ No |
| **WAIVED** | Issues acknowledged and accepted | Document reasoning | ✅ With approval |
### Risk-Based Testing Strategy
The Test Architect uses risk scoring to prioritize testing:
| **Risk Score** | **Calculation** | **Testing Priority** | **Gate Impact** |
| -------------- | ------------------------------ | ------------------------- | ------------------------ |
| **9** | High probability × High impact | P0 - Must test thoroughly | FAIL if untested |
| **6** | Medium-high combinations | P1 - Should test well | CONCERNS if gaps |
| **4** | Medium combinations | P1 - Should test | CONCERNS if notable gaps |
| **2-3** | Low-medium combinations | P2 - Nice to have | Note in review |
| **1** | Minimal risk | P2 - Minimal | Note in review |
### Special Situations & Best Practices
#### High-Risk or Brownfield Stories
```bash
# ALWAYS run this sequence:
@qa *risk {story} # First - identify dangers
@qa *design {story} # Second - plan defense
# Then during dev:
@qa *trace {story} # Verify regression coverage
@qa *nfr {story} # Check performance impact
# Finally:
@qa *review {story} # Deep integration analysis
```
#### Complex Integrations
- Run `*trace` multiple times during development
- Focus on integration test coverage
- Use `*nfr` to validate cross-system performance
- Review with extra attention to API contracts
#### Performance-Critical Features
- Run `*nfr` early and often (not just at review)
- Establish performance baselines before changes
- Document acceptable performance degradation
- Consider load testing requirements in `*design`
### Test Quality Standards Enforced
Quinn ensures all tests meet these standards:
- **No Flaky Tests**: Proper async handling, explicit waits
- **No Hard Waits**: Dynamic strategies only (polling, events)
- **Stateless**: Tests run independently and in parallel
- **Self-Cleaning**: Tests manage their own test data
- **Appropriate Levels**: Unit for logic, integration for interactions, E2E for journeys
- **Clear Assertions**: Keep assertions in tests, not buried in helpers
### Documentation & Audit Trail
All Test Architect activities create permanent records:
- **Assessment Reports**: Timestamped analysis in `docs/qa/assessments/`
- **Gate Files**: Decision records in `docs/qa/gates/`
- **Story Updates**: QA Results sections in story files
- **Traceability**: Requirements to test mapping maintained
## Commit Changes and Push
1. **Commit changes**
2. **Push to remote**
## Complete Development Cycle Flow
### The Full Workflow with Test Architect
1. **SM**: Create next story → Review → Approve
2. **QA (Optional)**: Risk assessment (`*risk`) → Test design (`*design`)
3. **Dev**: Implement story → Write tests → Complete
4. **QA (Optional)**: Mid-dev checks (`*trace`, `*nfr`)
5. **Dev**: Mark Ready for Review
6. **QA (Required)**: Review story (`*review`) → Gate decision
7. **Dev (If needed)**: Address issues
8. **QA (If needed)**: Update gate (`*gate`)
9. **Commit**: All changes
10. **Push**: To remote
11. **Continue**: Until all features implemented
### Quick Decision Guide
**Should I run Test Architect commands?**
| **Scenario** | **Before Dev** | **During Dev** | **After Dev** |
| ------------------------ | ------------------------------- | ---------------------------- | ---------------------------- |
| **Simple bug fix** | Optional | Optional | Required `*review` |
| **New feature** | Recommended `*risk`, `*design` | Optional `*trace` | Required `*review` |
| **Brownfield change** | **Required** `*risk`, `*design` | Recommended `*trace`, `*nfr` | Required `*review` |
| **API modification** | **Required** `*risk`, `*design` | **Required** `*trace` | Required `*review` |
| **Performance-critical** | Recommended `*design` | **Required** `*nfr` | Required `*review` |
| **Data migration** | **Required** `*risk`, `*design` | **Required** `*trace` | Required `*review` + `*gate` |
### Success Metrics
The Test Architect helps achieve:
- **Zero regression defects** in production
- **100% requirements coverage** with tests
- **Clear quality gates** for go/no-go decisions
- **Documented risk acceptance** for technical debt
- **Consistent test quality** across the team
- **Shift-left testing** with early risk identification

200
docs/expansion-packs.md
View File

@@ -1,200 +0,0 @@
# The Power of BMad Expansion Packs
## Overview
BMad Method's expansion packs unlock the framework's true potential by extending its natural language AI orchestration to ANY domain. While the core framework focuses on software development, expansion packs transform BMad into a universal AI agent system.
## Why Expansion Packs?
### Keep Core Lean
The core BMad framework maintains its focus on software development, ensuring dev agents have maximum context for coding. Expansion packs handle everything else.
### Domain Expertise
Each expansion pack provides deep, specialized knowledge without bloating the core system. Install only what you need.
### Community Innovation
Anyone can create and share expansion packs, fostering a ecosystem of AI-powered solutions across all industries and interests.
## Technical Expansion Packs (Examples of possible expansions to come)
### Game Development Pack
Transform your AI into a complete game development studio:
- **Game Designer**: Mechanics, balance, progression systems
- **Level Designer**: Map layouts, puzzle design, difficulty curves
- **Narrative Designer**: Story arcs, dialog trees, lore creation
- **Art Director**: Visual style guides, asset specifications
- **Sound Designer**: Audio direction, music themes, SFX planning
### Mobile Development Pack
Specialized agents for mobile app creation:
- **iOS Specialist**: Swift/SwiftUI patterns, Apple guidelines
- **Android Expert**: Kotlin best practices, Material Design
- **Mobile UX Designer**: Touch interfaces, gesture patterns
- **App Store Optimizer**: ASO strategies, listing optimization
- **Performance Tuner**: Battery optimization, network efficiency
### DevOps/Infrastructure Pack
Complete infrastructure automation team:
- **Cloud Architect**: AWS/Azure/GCP design patterns
- **Security Specialist**: Zero-trust implementation, compliance
- **SRE Expert**: Monitoring, alerting, incident response
- **Container Orchestrator**: Kubernetes, Docker optimization
- **Cost Optimizer**: Cloud spend analysis, resource right-sizing
### Data Science Pack
AI-powered data analysis team:
- **Data Scientist**: Statistical analysis, ML model selection
- **Data Engineer**: Pipeline design, ETL processes
- **ML Engineer**: Model deployment, A/B testing
- **Visualization Expert**: Dashboard design, insight communication
- **Ethics Advisor**: Bias detection, fairness assessment
## Non-Technical Expansion Packs
### Business Strategy Pack
Complete business advisory team:
- **Strategy Consultant**: Market positioning, competitive analysis
- **Financial Analyst**: Projections, unit economics, funding strategies
- **Operations Manager**: Process optimization, efficiency improvements
- **Marketing Strategist**: Go-to-market plans, growth hacking
- **HR Advisor**: Talent strategies, culture building
### Creative Writing Pack
Your personal writing team:
- **Plot Architect**: Three-act structure, story beats, pacing
- **Character Psychologist**: Deep motivations, authentic dialog
- **World Builder**: Consistent universes, cultural systems
- **Editor**: Style consistency, grammar, flow
- **Beta Reader**: Feedback simulation, plot hole detection
### Health & Wellness Pack
Personal wellness coaching system:
- **Fitness Trainer**: Progressive overload, form correction
- **Nutritionist**: Macro planning, supplement guidance
- **Sleep Coach**: Circadian optimization, sleep hygiene
- **Stress Manager**: Coping strategies, work-life balance
- **Habit Engineer**: Behavior change, accountability systems
### Education Pack
Complete learning design system:
- **Curriculum Architect**: Learning objectives, scope & sequence
- **Instructional Designer**: Engagement strategies, multimedia learning
- **Assessment Specialist**: Rubrics, formative/summative evaluation
- **Differentiation Expert**: Adaptive learning, special needs
- **EdTech Integrator**: Tool selection, digital pedagogy
### Mental Health Support Pack
Therapeutic support system:
- **CBT Guide**: Cognitive restructuring, thought challenging
- **Mindfulness Teacher**: Meditation scripts, awareness exercises
- **Journal Therapist**: Reflective prompts, emotional processing
- **Crisis Support**: Coping strategies, safety planning
- **Habit Tracker**: Mood monitoring, trigger identification
### Legal Assistant Pack
Legal document and research support:
- **Contract Analyst**: Term review, risk assessment
- **Legal Researcher**: Case law, precedent analysis
- **Document Drafter**: Template customization, clause libraries
- **Compliance Checker**: Regulatory alignment, audit prep
- **IP Advisor**: Patent strategies, trademark guidance
### Real Estate Pack
Property investment and management:
- **Market Analyst**: Comparable analysis, trend prediction
- **Investment Calculator**: ROI modeling, cash flow analysis
- **Property Manager**: Tenant screening, maintenance scheduling
- **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
AI-powered tabletop RPG assistance:
- **World Master**: Dynamic world generation, NPC creation
- **Combat Referee**: Initiative tracking, rule clarification
- **Story Weaver**: Plot hooks, side quests, consequences
- **Character Builder**: Backstory generation, stat optimization
- **Loot Master**: Treasure generation, magic item creation
### Life Event Planning Pack
Major life event coordination:
- **Wedding Planner**: Vendor coordination, timeline creation
- **Event Designer**: Theme development, decoration plans
- **Budget Manager**: Cost tracking, vendor negotiation
- **Guest Coordinator**: RSVP tracking, seating arrangements
- **Timeline Keeper**: Day-of scheduling, contingency planning
### Hobby Mastery Pack
Deep dive into specific hobbies:
- **Garden Designer**: Plant selection, seasonal planning
- **Brew Master**: Recipe formulation, process optimization
- **Maker Assistant**: 3D printing, woodworking, crafts
- **Collection Curator**: Organization, valuation, trading
- **Photography Coach**: Composition, lighting, post-processing
### Scientific Research Pack
Research acceleration tools:
- **Literature Reviewer**: Paper summarization, gap analysis
- **Hypothesis Generator**: Research question formulation
- **Methodology Designer**: Experiment planning, control design
- **Statistical Advisor**: Test selection, power analysis
- **Grant Writer**: Proposal structure, impact statements
## Creating Your Own Expansion Pack
The next major release will include a new agent and expansion pack builder and a new expansion format.
## Remember
The BMad Method is more than a Software Development Agile Framework! Every expansion pack makes specialized knowledge and workflows more accessible to everyone.
**What expertise will you share with the world?**

91
docs/flattener.md
View File

@@ -1,91 +0,0 @@
# Codebase Flattener Tool
The BMAD-METHOD™ includes a powerful codebase flattener tool designed to prepare your project files for AI model consumption when uploading to web AI tools. 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, plus optional project-level `.bmad-flattenignore` for additional exclusions if planning to flatten an existing repository for external update and analysis
- **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
npx bmad-method flatten
# Specify custom input directory
npx bmad-method flatten --input /path/to/source/directory
npx bmad-method flatten -i /path/to/source/directory
# Specify custom output file
npx bmad-method flatten --output my-project.xml
npx bmad-method flatten -o /path/to/output/codebase.xml
# Combine input and output options
npx bmad-method flatten --input /path/to/source --output /path/to/output/codebase.xml
```
## Example Output
The tool will display progress and provide a comprehensive summary:
```text
📊 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 your project's text-based source files 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.
## Advanced Usage & Options
- CLI options
- `-i, --input <path>`: Directory to flatten. Default: current working directory or auto-detected project root when run interactively.
- `-o, --output <path>`: Output file path. Default: `flattened-codebase.xml` in the chosen directory.
- Interactive mode
- If you do not pass `--input` and `--output` and the terminal is interactive (TTY), the tool will attempt to detect your project root (by looking for markers like `.git`, `package.json`, etc.) and prompt you to confirm or override the paths.
- In non-interactive contexts (e.g., CI), it will prefer the detected root silently; otherwise it falls back to the current directory and default filename.
- File discovery and ignoring
- Uses `git ls-files` when inside a git repository for speed and correctness; otherwise falls back to a glob-based scan.
- Applies your `.gitignore` plus a curated set of default ignore patterns (e.g., `node_modules`, build outputs, caches, logs, IDE folders, lockfiles, large media/binaries, `.env*`, and previously generated XML outputs).
- Supports an optional `.bmad-flattenignore` file at the project root for additional ignore patterns (gitignore-style). If present, its rules are applied after `.gitignore` and the defaults.
## `.bmad-flattenignore` example
Create a `.bmad-flattenignore` file in the root of your project to exclude files that must remain in git but should not be included in the flattened XML:
```text
seeds/**
scripts/private/**
**/*.snap
```
- Binary handling
- Binary files are detected and excluded from the XML content. They are counted in the final summary but not embedded in the output.
- XML format and safety
- UTF-8 encoded file with root element `<files>`.
- Each text file is emitted as a `<file path="relative/path">` element whose content is wrapped in `<![CDATA[ ... ]]>`.
- The tool safely handles occurrences of `]]>` inside content by splitting the CDATA to preserve correctness.
- File contents are preserved as-is and indented for readability inside the XML.
- Performance
- Concurrency is selected automatically based on your CPU and workload size. No configuration required.
- Running inside a git repo improves discovery performance.
## Minimal XML example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<files>
<file path="src/index.js"><![CDATA[
// your source content
]]></file>
</files>
```

158
docs/how-to-contribute-with-pull-requests.md
View File

@@ -1,158 +0,0 @@
# How to Contribute with Pull Requests
**New to GitHub and pull requests?** This guide will walk you through the basics step by step.
## What is a Pull Request?
A pull request (PR) is how you propose changes to a project on GitHub. Think of it as saying "Here are some changes I'd like to make - please review and consider adding them to the main project."
## Before You Start
⚠️ **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/gk8jAdXWmj)
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
### 1. Fork the Repository
1. Go to the [BMad-Method repository](https://github.com/bmadcode/bmad-method)
2. Click the "Fork" button in the top-right corner
3. This creates your own copy of the project
### 2. Clone Your Fork
```bash
# Replace YOUR-USERNAME with your actual GitHub username
git clone https://github.com/YOUR-USERNAME/bmad-method.git
cd bmad-method
```
### 3. Create a New Branch
**Never work directly on the `main` branch!** Always create a new branch for your changes:
```bash
# Create and switch to a new branch
git checkout -b fix/typo-in-readme
# or
git checkout -b feature/add-new-agent
```
**Branch naming tips:**
- `fix/description` - for bug fixes
- `feature/description` - for new features
- `docs/description` - for documentation changes
### 4. Make Your Changes
- Edit the files you want to change
- Keep changes small and focused on one thing
- Test your changes if possible
### 5. Commit Your Changes
```bash
# Add your changes
git add .
# Commit with a clear message
git commit -m "Fix typo in README.md"
```
**Good commit messages:**
- "Fix typo in installation instructions"
- "Add example for new agent usage"
- "Update broken link in docs"
**Bad commit messages:**
- "stuff"
- "changes"
- "update"
### 6. Push to Your Fork
```bash
# Push your branch to your fork
git push origin fix/typo-in-readme
```
### 7. Create the Pull Request
1. Go to your fork on GitHub
2. You'll see a green "Compare & pull request" button - click it
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
- A maintainer will review your PR
- They might ask for changes
- Be patient and responsive to feedback
## 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
❌ **Avoid:**
- Changing formatting of entire files
- Multiple unrelated changes in one PR
- Copying your entire project/repo into the PR
- Changes without explanation
## 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
## Need Help?
- 💬 Join our [Discord Community](https://discord.gg/gk8jAdXWmj) 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
### 😀 Good PR Example
**Title**: "Fix broken link to installation guide"
**Changes**: One file, one line changed
**Description**: "The link in README.md was pointing to the wrong file. Updated to point to correct installation guide."
### 😞 Bad PR Example
**Title**: "Updates"
**Changes**: 50 files, entire codebase reformatted
**Description**: "Made some improvements"
---
**Remember**: We're here to help! Don't be afraid to ask questions. Every expert was once a beginner.

31
docs/ide-info/auggie.md Normal file
View File

@@ -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

25
docs/ide-info/claude-code.md Normal file
View File

@@ -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

31
docs/ide-info/cline.md Normal file
View File

@@ -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
```

32
docs/ide-info/codex.md Normal file
View File

@@ -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

30
docs/ide-info/crush.md Normal file
View File

@@ -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

25
docs/ide-info/cursor.md Normal file
View File

@@ -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`

25
docs/ide-info/gemini.md Normal file
View File

@@ -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)

26
docs/ide-info/github-copilot.md Normal file
View File

@@ -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

33
docs/ide-info/iflow.md Normal file
View File

@@ -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

24
docs/ide-info/kilo.md Normal file
View File

@@ -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

25
docs/ide-info/qwen.md Normal file
View File

@@ -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

27
docs/ide-info/roo.md Normal file
View File

@@ -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

25
docs/ide-info/trae.md Normal file
View File

@@ -0,0 +1,25 @@
# BMAD Method - Trae Instructions
## Activating Agents
BMAD agents are installed as rules in `.trae/rules/`.
### How to Use
1. **Type Trigger**: Use `@{agent-name}` in your prompt
2. **Activate**: Agent persona activates automatically
3. **Continue**: Agent remains active for conversation
### Examples
```
@dev - Activate development agent
@architect - Activate architect agent
@task-setup - Execute setup task
```
### Notes
- Rules auto-load from `.trae/rules/` directory
- Multiple agents can be referenced: `@dev and @test`
- Agent follows YAML configuration in rule file

22
docs/ide-info/windsurf.md Normal file
View File

@@ -0,0 +1,22 @@
# BMAD Method - Windsurf Instructions
## Activating Agents
BMAD agents are installed as workflows in `.windsurf/workflows/`.
### How to Use
1. **Open Workflows**: Access via Windsurf menu or command palette
2. **Select Workflow**: Choose the agent/task workflow
3. **Execute**: Run to activate that agent persona
### Workflow Types
- **Agent workflows**: `{module}-{agent}.md` (auto_execution_mode: 3)
- **Task workflows**: `task-{module}-{task}.md` (auto_execution_mode: 2)
### Notes
- Agents run with higher autonomy (mode 3)
- Tasks run with guided execution (mode 2)
- Workflows persist for the session

196
docs/installers-bundlers/ide-injections.md Normal file
View File

@@ -0,0 +1,196 @@
# IDE Content Injection Standard
## Overview
This document defines the standard for IDE-specific content injection in BMAD modules. Each IDE can inject its own specific content into BMAD templates during installation without polluting the source files with IDE-specific code. The installation process is interactive, allowing users to choose what IDE-specific features they want to install.
## Architecture
### 1. Injection Points
Files that support IDE-specific content define injection points using HTML comments:
```xml
<!-- IDE-INJECT-POINT: unique-point-name -->
```
### 2. Module Structure
Each module that needs IDE-specific content creates a sub-module folder:
```
src/modules/{module-name}/sub-modules/{ide-name}/
├── injections.yaml # Injection configuration
├── sub-agents/ # IDE-specific subagents (if applicable)
└── config.yaml # Other IDE-specific config
```
### 3. Injection Configuration Format
The `injections.yaml` file defines what content to inject where:
```yaml
# injections.yaml structure
injections:
- file: 'relative/path/to/file.md' # Path relative to installation root
point: 'injection-point-name' # Must match IDE-INJECT-POINT name
requires: 'subagent-name' # Which subagent must be selected (or "any")
content: | # Content to inject (preserves formatting)
<llm>
<i>Instructions specific to this IDE</i>
</llm>
# Subagents available for installation
subagents:
source: 'sub-agents' # Source folder relative to this config
target: '.claude/agents' # Claude's expected location (don't change)
files:
- 'agent1.md'
- 'agent2.md'
```
### 4. Interactive Installation Process
For Claude Code specifically, the installer will:
1. **Detect available subagents** from the module's `injections.yaml`
2. **Ask the user** about subagent installation:
- Install all subagents (default)
- Select specific subagents
- Skip subagent installation
3. **Ask installation location** (if subagents selected):
- Project level: `.claude/agents/`
- User level: `~/.claude/agents/`
4. **Copy selected subagents** to the chosen location
5. **Inject only relevant content** based on selected subagents
Other IDEs can implement their own installation logic appropriate to their architecture.
## Implementation
### IDE Installer Responsibilities
Each IDE installer (e.g., `claude-code.js`) must:
1. **Check for sub-modules**: Look for `sub-modules/{ide-name}/` in each installed module
2. **Load injection config**: Parse `injections.yaml` if present
3. **Process injections**: Replace injection points with configured content
4. **Copy additional files**: Handle subagents or other IDE-specific files
### Example Implementation (Claude Code)
```javascript
async processModuleInjections(projectDir, bmadDir, options) {
for (const moduleName of options.selectedModules) {
const configPath = path.join(
bmadDir, 'src/modules', moduleName,
'sub-modules/claude-code/injections.yaml'
);
if (exists(configPath)) {
const config = yaml.load(configPath);
// Interactive: Ask user about subagent installation
const choices = await this.promptSubagentInstallation(config.subagents);
if (choices.install !== 'none') {
// Ask where to install
const location = await this.promptInstallLocation();
// Process injections based on selections
for (const injection of config.injections) {
if (this.shouldInject(injection, choices)) {
await this.injectContent(projectDir, injection, choices);
}
}
// Copy selected subagents
await this.copySelectedSubagents(projectDir, config.subagents, choices, location);
}
}
}
}
```
## Benefits
1. **Clean Source Files**: No IDE-specific conditionals in source
2. **Modular**: Each IDE manages its own injections
3. **Scalable**: Easy to add support for new IDEs
4. **Maintainable**: IDE-specific content lives with IDE config
5. **Flexible**: Different modules can inject different content
## Adding Support for a New IDE
1. Create sub-module folder: `src/modules/{module}/sub-modules/{new-ide}/`
2. Add `injections.yaml` with IDE-specific content
3. Update IDE installer to process injections using this standard
4. Test installation with and without the IDE selected
## Example: BMM Module with Claude Code
### File Structure
```
src/modules/bmm/
├── agents/pm.md # Has injection point
├── templates/prd.md # Has multiple injection points
└── sub-modules/
└── claude-code/
├── injections.yaml # Defines what to inject
└── sub-agents/ # Claude Code specific subagents
├── market-researcher.md
├── requirements-analyst.md
└── ...
```
### Injection Point in pm.md
```xml
<agent>
<persona>...</persona>
<!-- IDE-INJECT-POINT: pm-agent-instructions -->
<cmds>...</cmds>
</agent>
```
### Injection Configuration
```yaml
injections:
- file: 'bmad/bmm/agents/pm.md'
point: 'pm-agent-instructions'
requires: 'any' # Injected if ANY subagent is selected
content: |
<llm critical="true">
<i>Use 'market-researcher' subagent for analysis</i>
</llm>
- file: 'bmad/bmm/templates/prd.md'
point: 'prd-goals-context-delegation'
requires: 'market-researcher' # Only if this specific subagent selected
content: |
<i>DELEGATE: Use 'market-researcher' subagent...</i>
```
### Result After Installation
```xml
<agent>
<persona>...</persona>
<llm critical="true">
<i>Use 'market-researcher' subagent for analysis</i>
</llm>
<cmds>...</cmds>
</agent>
```
## Testing Checklist
- [ ] Injection points are properly named and unique
- [ ] injections.yaml is valid YAML with correct structure
- [ ] Content formatting is preserved after injection
- [ ] Installation works without the IDE (injection points removed)
- [ ] Installation works with the IDE (content properly injected)
- [ ] Subagents/files are copied to correct locations
- [ ] No IDE-specific content remains when different IDE selected

355
docs/installers-bundlers/installers-modules-platforms-reference.md Normal file
View File

@@ -0,0 +1,355 @@
# BMAD v6 Installation & Module System Reference
## Table of Contents
1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Architecture](#architecture)
4. [Modules](#modules)
5. [Configuration System](#configuration-system)
6. [Platform Integration](#platform-integration)
7. [Development Guide](#development-guide)
8. [Troubleshooting](#troubleshooting)
## Overview
BMAD v6 is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.
### Key Features
- **Modular Design**: Core + optional modules (BMM, CIS)
- **Smart Installation**: Interactive configuration with dependency resolution
- **Multi-Platform**: Supports 15+ AI coding platforms
- **Clean Architecture**: Centralized `bmad/` directory, no source pollution
## Quick Start
```bash
# Interactive installation (recommended)
bmad install
# Install specific modules
bmad install -m bmm cis
# Full installation
bmad install -f
# Check status
bmad status
```
### Installation Options
- `-d <path>`: Target directory (default: current)
- `-m <modules...>`: Specific modules (bmm, cis)
- `-f`: Full installation
- `-c`: Core only
- `-i <ide...>`: Configure specific IDEs
- `--skip-ide`: Skip IDE configuration
- `-v`: Verbose output
## Architecture
### Directory Structure
```
project-root/
├── bmad/ # Centralized installation
│ ├── _cfg/ # Configuration
│ │ ├── agents/ # Agent configs
│ │ └── agent-party.xml # Agent manifest
│ ├── core/ # Core module
│ │ ├── agents/
│ │ ├── tasks/
│ │ └── config.yaml
│ ├── bmm/ # BMad Method module
│ │ ├── agents/
│ │ ├── tasks/
│ │ ├── templates/
│ │ └── config.yaml
│ └── cis/ # Creative Innovation Studio
│ └── ...
└── .claude/ # Platform-specific (example)
└── agents/
```
### Installation Flow
1. **Detection**: Check existing installation
2. **Selection**: Choose modules interactively or via CLI
3. **Configuration**: Collect module-specific settings
4. **Platform Setup**: Configure AI coding platforms
5. **Installation**: Process and copy files
6. **Generation**: Create config files with inheritance
7. **Post-Install**: Run module installers
8. **Manifest**: Track installed components
### Key Exclusions
- `_module-installer/` directories are never copied to destination
- `localskip="true"` agents are filtered out
- Source `config.yaml` templates are replaced with generated configs
## Modules
### Core Module (Required)
Foundation framework with C.O.R.E. (Collaboration Optimized Reflection Engine)
- **Components**: Base agents, activation system, advanced elicitation
- **Config**: `user_name`, `communication_language`
### BMM Module
BMad Method for software development workflows
- **Components**: PM agent, dev tasks, PRD templates, story generation
- **Config**: `project_name`, `tech_docs`, `output_folder`, `story_location`
- **Dependencies**: Core
### CIS Module
Creative Innovation Studio for design workflows
- **Components**: Design agents, creative tasks
- **Config**: `output_folder`, design preferences
- **Dependencies**: Core
### Module Structure
```
src/modules/{module}/
├── _module-installer/ # Not copied to destination
│ ├── installer.js # Post-install logic
│ └── install-menu-config.yaml
├── agents/
├── tasks/
├── templates/
└── sub-modules/ # Platform-specific content
└── {platform}/
├── injections.yaml
└── sub-agents/
```
## Configuration System
### Collection Process
Modules define prompts in `install-menu-config.yaml`:
```yaml
project_name:
prompt: 'Project title?'
default: 'My Project'
result: '{value}'
output_folder:
prompt: 'Output location?'
default: 'docs'
result: '{project-root}/{value}'
tools:
prompt: 'Select tools:'
multi-select:
- 'Tool A'
- 'Tool B'
```
### Configuration Inheritance
Core values cascade to ALL modules automatically:
```yaml
# core/config.yaml
user_name: "Jane"
communication_language: "English"
# bmm/config.yaml (generated)
project_name: "My App"
tech_docs: "/path/to/docs"
# Core Configuration Values (inherited)
user_name: "Jane"
communication_language: "English"
```
**Reserved Keys**: Core configuration keys cannot be redefined by other modules.
### Path Placeholders
- `{project-root}`: Project directory path
- `{value}`: User input
- `{module}`: Module name
- `{core:field}`: Reference core config value
### Config Generation Rules
1. ALL installed modules get a `config.yaml` (even without prompts)
2. Core values are ALWAYS included in module configs
3. Module-specific values come first, core values appended
4. Source templates are never copied, only generated configs
## Platform Integration
### Supported Platforms
**Preferred** (Full Integration):
- Claude Code
- Cursor
- Windsurf
**Additional**:
Cline, Roo, Auggie, GitHub Copilot, Codex, Gemini, Qwen, Trae, Kilo, Crush, iFlow
### Platform Features
1. **Setup Handler** (`tools/cli/installers/lib/ide/{platform}.js`)
- Directory creation
- Configuration generation
- Agent processing
2. **Content Injection** (`sub-modules/{platform}/injections.yaml`)
```yaml
injections:
- file: 'bmad/bmm/agents/pm.md'
point: 'pm-agent-instructions'
content: |
<i>Platform-specific instruction</i>
subagents:
source: 'sub-agents'
target: '.claude/agents'
files: ['agent.md']
```
3. **Interactive Config**
- Subagent selection
- Installation scope (project/user)
- Feature toggles
### Injection System
Platform-specific content without source modification:
- Inject points marked in source: `<!-- IDE-INJECT-POINT:name -->`
- Content added during installation only
- Source files remain clean
## Development Guide
### Creating a Module
1. **Structure**
```
src/modules/mymod/
├── _module-installer/
│ ├── installer.js
│ └── install-menu-config.yaml
├── agents/
└── tasks/
```
2. **Configuration** (`install-menu-config.yaml`)
```yaml
code: mymod
name: 'My Module'
prompt: 'Welcome message'
setting_name:
prompt: 'Configure X?'
default: 'value'
```
3. **Installer** (`installer.js`)
```javascript
async function install(options) {
const { projectRoot, config, installedIDEs, logger } = options;
// Custom logic
return true;
}
module.exports = { install };
```
### Adding Platform Support
1. Create handler: `tools/cli/installers/lib/ide/myplatform.js`
2. Extend `BaseIdeSetup` class
3. Add sub-module: `src/modules/{mod}/sub-modules/myplatform/`
4. Define injections and platform agents
### Agent Configuration
Extractable config nodes:
```xml
<agent>
<setting agentConfig="true">
Default value
</setting>
</agent>
```
Generated in: `bmad/_cfg/agents/{module}-{agent}.md`
## Troubleshooting
### Common Issues
| Issue | Solution |
| ------------------------- | ----------------------------------- |
| Existing installation | Use `bmad update` or remove `bmad/` |
| Module not found | Check `src/modules/` exists |
| Config not applied | Verify `bmad/{module}/config.yaml` |
| Missing config.yaml | Fixed: All modules now get configs |
| Agent unavailable | Check for `localskip="true"` |
| \_module-installer copied | Fixed: Now excluded from copy |
### Debug Commands
```bash
bmad install -v # Verbose installation
bmad status -v # Detailed status
```
### Best Practices
1. Run from project root
2. Backup `bmad/_cfg/` before updates
3. Use interactive mode for guidance
4. Review generated configs post-install
## Migration from v4
| v4 | v6 |
| ------------------- | ------------------- |
| Scattered files | Centralized `bmad/` |
| Monolithic | Modular |
| Manual config | Interactive setup |
| Limited IDE support | 15+ platforms |
| Source modification | Clean injection |
## Technical Notes
### Dependency Resolution
- Direct dependencies (module → module)
- Agent references (cross-module)
- Template dependencies
- Partial module installation (only required files)
### File Processing
- Filters `localskip="true"` agents
- Excludes `_module-installer/` directories
- Replaces path placeholders at runtime
- Injects activation blocks
### Web Bundling
```bash
bmad bundle --web # Filter for web deployment
npm run validate:bundles # Validate bundles
```

54
docs/installers-bundlers/web-bundler-usage.md Normal file
View File

@@ -0,0 +1,54 @@
# Web Bundler Usage
ALPHA NOTE: Bundling of individual agents might work, team bundling is being reworked and will come with Beta release soon.
The web bundler creates self-contained XML bundles for BMAD agents, packaging all dependencies for web deployment.
## Quick Start
```bash
# Bundle all agents from all modules
npm run bundle
# Clean and rebundle (removes old bundles first)
npm run rebundle
```
## Custom Output Directory
```bash
# Bundle to custom directory
node tools/cli/bundlers/bundle-web.js all --output ./my-bundles
# Rebundle to custom directory (auto-cleans first)
node tools/cli/bundlers/bundle-web.js rebundle --output /absolute/path/to/custom/directory
# Bundle specific module to custom directory
node tools/cli/bundlers/bundle-web.js module bmm --output ./custom-folder
# Bundle specific agent to custom directory
node tools/cli/bundlers/bundle-web.js agent bmm analyst -o ./custom-folder
```
## Output
Bundles are generated in `web-bundles/` directory by default when run from the root of the clones project:
```
web-bundles/
├── [module-name]/
│ └── agents/
│ └── [agent-name].xml
```
## Skipping Agents
Agents with `bundle="false"` attribute are automatically skipped during bundling.
## Bundle Contents
Each bundle includes:
- Agent definition with web activation
- All resolved dependencies
- Manifests for agent/team discovery

577
docs/user-guide.md
View File

@@ -1,577 +0,0 @@
# BMad Method — User Guide
This guide will help you understand and effectively use the BMad Method for agile AI-driven planning and development.
## The BMad Plan and Execute Workflow
First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but it's suggested to understand this greenfield first, even if on a simple project before tackling a brownfield project. The BMad Method needs to be installed to the root of your new project folder. For the planning phase, you can optionally perform it with powerful web agents, potentially resulting in higher quality results at a fraction of the cost it would take to complete if providing your own API key or credits in some Agentic tools. For planning, powerful thinking models and larger context - along with working as a partner with the agents will net the best results.
If you are going to use the BMad Method with a Brownfield project (an existing project), review **[Working in the Brownfield](./working-in-the-brownfield.md)**.
If the diagrams below don't render, install Markdown All in One along with the Markdown Preview Mermaid Support plugins to VSCode (or one of the forked clones). With these plugins, if you right click on the tab when open, there should be an Open Preview option, or check the IDE documentation.
### The Planning Workflow (Web UI or Powerful IDE Agents)
Before development begins, BMad follows a structured planning workflow that's ideally done in web UI for cost efficiency:
```mermaid
graph TD
A["Start: Project Idea"] --> B{"Optional: Analyst Research"}
B -->|Yes| C["Analyst: Brainstorming (Optional)"]
B -->|No| G{"Project Brief Available?"}
C --> C2["Analyst: Market Research (Optional)"]
C2 --> C3["Analyst: Competitor Analysis (Optional)"]
C3 --> D["Analyst: Create Project Brief"]
D --> G
G -->|Yes| E["PM: Create PRD from Brief (Fast Track)"]
G -->|No| E2["PM: Interactive PRD Creation (More Questions)"]
E --> F["PRD Created with FRs, NFRs, Epics & Stories"]
E2 --> F
F --> F2{"UX Required?"}
F2 -->|Yes| F3["UX Expert: Create Front End Spec"]
F2 -->|No| H["Architect: Create Architecture from PRD"]
F3 --> F4["UX Expert: Generate UI Prompt for Lovable/V0 (Optional)"]
F4 --> H2["Architect: Create Architecture from PRD + UX Spec"]
H --> Q{"Early Test Strategy? (Optional)"}
H2 --> Q
Q -->|Yes| R["QA: Early Test Architecture Input on High-Risk Areas"]
Q -->|No| I
R --> I["PO: Run Master Checklist"]
I --> J{"Documents Aligned?"}
J -->|Yes| K["Planning Complete"]
J -->|No| L["PO: Update Epics & Stories"]
L --> M["Update PRD/Architecture as needed"]
M --> I
K --> N["📁 Switch to IDE (If in a Web Agent Platform)"]
N --> O["PO: Shard Documents"]
O --> P["Ready for SM/Dev Cycle"]
style A fill:#f5f5f5,color:#000
style B fill:#e3f2fd,color:#000
style C fill:#e8f5e9,color:#000
style C2 fill:#e8f5e9,color:#000
style C3 fill:#e8f5e9,color:#000
style D fill:#e8f5e9,color:#000
style E fill:#fff3e0,color:#000
style E2 fill:#fff3e0,color:#000
style F fill:#fff3e0,color:#000
style F2 fill:#e3f2fd,color:#000
style F3 fill:#e1f5fe,color:#000
style F4 fill:#e1f5fe,color:#000
style G fill:#e3f2fd,color:#000
style H fill:#f3e5f5,color:#000
style H2 fill:#f3e5f5,color:#000
style Q fill:#e3f2fd,color:#000
style R fill:#ffd54f,color:#000
style I fill:#f9ab00,color:#fff
style J fill:#e3f2fd,color:#000
style K fill:#34a853,color:#fff
style L fill:#f9ab00,color:#fff
style M fill:#fff3e0,color:#000
style N fill:#1a73e8,color:#fff
style O fill:#f9ab00,color:#fff
style P fill:#34a853,color:#fff
```
#### Web UI to IDE Transition
**Critical Transition Point**: Once the PO confirms document alignment, you must switch from web UI to IDE to begin the development workflow:
1. **Copy Documents to Project**: Ensure `docs/prd.md` and `docs/architecture.md` are in your project's docs folder (or a custom location you can specify during installation)
2. **Switch to IDE**: Open your project in your preferred Agentic IDE
3. **Document Sharding**: Use the PO agent to shard the PRD and then the Architecture
4. **Begin Development**: Start the Core Development Cycle that follows
#### Planning Artifacts (Standard Paths)
```text
PRD → docs/prd.md
Architecture → docs/architecture.md
Sharded Epics → docs/epics/
Sharded Stories → docs/stories/
QA Assessments → docs/qa/assessments/
QA Gates → docs/qa/gates/
```
### The Core Development Cycle (IDE)
Once planning is complete and documents are sharded, BMad follows a structured development workflow:
```mermaid
graph TD
A["Development Phase Start"] --> B["SM: Reviews Previous Story Dev/QA Notes"]
B --> B2["SM: Drafts Next Story from Sharded Epic + Architecture"]
B2 --> S{"High-Risk Story? (Optional)"}
S -->|Yes| T["QA: *risk + *design on Draft Story"]
S -->|No| B3
T --> U["Test Strategy & Risk Profile Created"]
U --> B3{"PO: Validate Story Draft (Optional)"}
B3 -->|Validation Requested| B4["PO: Validate Story Against Artifacts"]
B3 -->|Skip Validation| C{"User Approval"}
B4 --> C
C -->|Approved| D["Dev: Sequential Task Execution"]
C -->|Needs Changes| B2
D --> E["Dev: Implement Tasks + Tests"]
E --> V{"Mid-Dev QA Check? (Optional)"}
V -->|Yes| W["QA: *trace or *nfr for Early Validation"]
V -->|No| F
W --> X["Dev: Address Coverage/NFR Gaps"]
X --> F["Dev: Run All Validations"]
F --> G["Dev: Mark Ready for Review + Add Notes"]
G --> H{"User Verification"}
H -->|Request QA Review| I["QA: Test Architect Review + Quality Gate"]
H -->|Approve Without QA| M["IMPORTANT: Verify All Regression Tests and Linting are Passing"]
I --> J["QA: Test Architecture Analysis + Active Refactoring"]
J --> L{"QA Decision"}
L -->|Needs Dev Work| D
L -->|Approved| M
H -->|Needs Fixes| D
M --> N["IMPORTANT: COMMIT YOUR CHANGES BEFORE PROCEEDING!"]
N --> Y{"Gate Update Needed?"}
Y -->|Yes| Z["QA: *gate to Update Status"]
Y -->|No| K
Z --> K["Mark Story as Done"]
K --> B
style A fill:#f5f5f5,color:#000
style B fill:#e8f5e9,color:#000
style B2 fill:#e8f5e9,color:#000
style S fill:#e3f2fd,color:#000
style T fill:#ffd54f,color:#000
style U fill:#ffd54f,color:#000
style B3 fill:#e3f2fd,color:#000
style B4 fill:#fce4ec,color:#000
style C fill:#e3f2fd,color:#000
style D fill:#e3f2fd,color:#000
style E fill:#e3f2fd,color:#000
style V fill:#e3f2fd,color:#000
style W fill:#ffd54f,color:#000
style X fill:#e3f2fd,color:#000
style F fill:#e3f2fd,color:#000
style G fill:#e3f2fd,color:#000
style H fill:#e3f2fd,color:#000
style I fill:#f9ab00,color:#fff
style J fill:#ffd54f,color:#000
style K fill:#34a853,color:#fff
style L fill:#e3f2fd,color:#000
style M fill:#ff5722,color:#fff
style N fill:#d32f2f,color:#fff
style Y fill:#e3f2fd,color:#000
style Z fill:#ffd54f,color:#000
```
## Prerequisites
Before installing BMad Method, ensure you have:
- **Node.js** ≥ 18, **npm** ≥ 9
- **Git** installed and configured
- **(Optional)** VS Code with "Markdown All in One" + "Markdown Preview Mermaid Support" extensions
## Installation
### Optional
If you want to do the planning on the web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPTs:
1. Navigate to `dist/teams/`
2. Copy `team-fullstack.txt`
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
### IDE Project Setup
```bash
# Interactive installation (recommended)
npx bmad-method install
```
### OpenCode
BMAD integrates with OpenCode via a project-level `opencode.jsonc`/`opencode.json` (JSON-only, no Markdown fallback).
- Installation:
- Run `npx bmad-method install` and choose `OpenCode` in the IDE list.
- The installer will detect an existing `opencode.jsonc`/`opencode.json` or create a minimal `opencode.jsonc` if missing.
- It will:
- Ensure `instructions` includes `.bmad-core/core-config.yaml` (and each selected expansion pack’s `config.yaml`).
- Merge BMAD agents and commands using file references (`{file:./.bmad-core/...}`), idempotently.
- Preserve other top-level fields and user-defined entries.
- Prefixes and collisions:
- You can opt-in to prefix agent keys with `bmad-` and command keys with `bmad:tasks:` to avoid name collisions.
- If a key already exists and is not BMAD-managed, the installer will skip it and suggest enabling prefixes.
- What gets added:
- `instructions`: `.bmad-core/core-config.yaml` plus any selected expansion pack `config.yaml` files.
- `agent`: BMAD agents from core and selected packs.
- `prompt`: `{file:./.bmad-core/agents/<id>.md}` (or pack path)
- `mode`: `primary` for orchestrators, otherwise `all`
- `tools`: `{ write: true, edit: true, bash: true }`
- `description`: extracted from the agent’s `whenToUse`
- `command`: BMAD tasks from core and selected packs.
- `template`: `{file:./.bmad-core/tasks/<id>.md}` (or pack path)
- `description`: extracted from the task’s “Purpose” section
- Selected Packages Only:
- The installer includes agents and tasks only from the packages you selected in the earlier step (core and chosen packs).
- Refresh after changes:
- Re-run:
```bash
npx bmad-method install -f -i opencode
```
- The installer safely updates entries without duplication and preserves your custom fields and comments.
- Optional convenience script:
- You can add a script to your project’s `package.json` for quick refreshes:
```json
{
"scripts": {
"bmad:opencode": "bmad-method install -f -i opencode"
}
}
```
### Codex (CLI & Web)
BMAD integrates with OpenAI Codex via `AGENTS.md` and committed core agent files.
- Two installation modes:
- Codex (local only): keeps `.bmad-core/` ignored for local dev.
- `npx bmad-method install -f -i codex -d .`
- Codex Web Enabled: ensures `.bmad-core/` is tracked so you can commit it for Codex Web.
- `npx bmad-method install -f -i codex-web -d .`
- What gets generated:
- `AGENTS.md` at the project root with a BMAD section containing
- How-to-use with Codex (CLI & Web)
- Agent Directory (Title, ID, When To Use)
- Detailed per‑agent sections with source path, when-to-use, activation phrasing, and YAML
- Tasks with quick usage notes
- If a `package.json` exists, helpful scripts are added:
- `bmad:refresh`, `bmad:list`, `bmad:validate`
- Using Codex:
- CLI: run `codex` in the project root and prompt naturally, e.g., “As dev, implement …”.
- Web: commit `.bmad-core/` and `AGENTS.md`, then open the repo in Codex and prompt the same way.
- Refresh after changes:
- Re-run the appropriate install mode (`codex` or `codex-web`) to update the BMAD block in `AGENTS.md`.
## Special Agents
There are two BMad agents — in the future they'll be consolidated into a single BMad-Master.
### BMad-Master
This agent can do any task or command that all other agents can do, aside from actual story implementation. Additionally, this agent can help explain the BMad Method when on the web by accessing the knowledge base and explaining anything to you about the process.
If you don't want to bother switching between different agents aside from the dev, this is the agent for you. Just remember that as the context grows, the performance of the agent degrades, therefore it is important to instruct the agent to compact the conversation and start a new conversation with the compacted conversation as the initial message. Do this often, preferably after each story is implemented.
### BMad-Orchestrator
This agent should NOT be used within the IDE, it is a heavyweight, special-purpose agent that utilizes a lot of context and can morph into any other agent. This exists solely to facilitate the teams within the web bundles. If you use a web bundle you will be greeted by the BMad Orchestrator.
### How Agents Work
#### Dependencies System
Each agent has a YAML section that defines its dependencies:
```yaml
dependencies:
templates:
- prd-template.md
- user-story-template.md
tasks:
- create-doc.md
- shard-doc.md
data:
- bmad-kb.md
```
**Key Points:**
- Agents only load resources they need (lean context)
- Dependencies are automatically resolved during bundling
- Resources are shared across agents to maintain consistency
#### Agent Interaction
**In IDE:**
```bash
# Some IDEs, like Cursor or Windsurf for example, utilize manual rules so interaction is done with the '@' symbol
@pm Create a PRD for a task management app
@architect Design the system architecture
@dev Implement the user authentication
# Some IDEs, like Claude Code, use slash commands instead
/pm Create user stories
/dev Fix the login bug
```
#### Interactive Modes
- **Incremental Mode**: Step-by-step with user input
- **YOLO Mode**: Rapid generation with minimal interaction
## IDE Integration
### IDE Best Practices
- **Context Management**: Keep relevant files only in context, keep files as lean and focused as necessary
- **Agent Selection**: Use appropriate agent for task
- **Iterative Development**: Work in small, focused tasks
- **File Organization**: Maintain clean project structure
- **Commit Regularly**: Save your work frequently
## The Test Architect (QA Agent)
### Overview
The QA agent in BMad is not just a "senior developer reviewer" - it's a **Test Architect** with deep expertise in test strategy, quality gates, and risk-based testing. Named Quinn, this agent provides advisory authority on quality matters while actively improving code when safe to do so.
#### Quick Start (Essential Commands)
```bash
@qa *risk {story} # Assess risks before development
@qa *design {story} # Create test strategy
@qa *trace {story} # Verify test coverage during dev
@qa *nfr {story} # Check quality attributes
@qa *review {story} # Full assessment → writes gate
```
#### Command Aliases (Test Architect)
The documentation uses short forms for convenience. Both styles are valid:
```text
*risk → *risk-profile
*design → *test-design
*nfr → *nfr-assess
*trace → *trace-requirements (or just *trace)
*review → *review
*gate → *gate
```
### Core Capabilities
#### 1. Risk Profiling (`*risk`)
**When:** After story draft, before development begins (earliest intervention point)
Identifies and assesses implementation risks:
- **Categories**: Technical, Security, Performance, Data, Business, Operational
- **Scoring**: Probability × Impact analysis (1-9 scale)
- **Mitigation**: Specific strategies for each identified risk
- **Gate Impact**: Risks ≥9 trigger FAIL, ≥6 trigger CONCERNS (see `tasks/risk-profile.md` for authoritative rules)
#### 2. Test Design (`*design`)
**When:** After story draft, before development begins (guides what tests to write)
Creates comprehensive test strategies including:
- Test scenarios for each acceptance criterion
- Appropriate test level recommendations (unit vs integration vs E2E)
- Risk-based prioritization (P0/P1/P2)
- Test data requirements and mock strategies
- Execution strategies for CI/CD integration
**Example output:**
```yaml
test_summary:
total: 24
by_level:
unit: 15
integration: 7
e2e: 2
by_priority:
P0: 8 # Must have - linked to critical risks
P1: 10 # Should have - medium risks
P2: 6 # Nice to have - low risks
```
#### 3. Requirements Tracing (`*trace`)
**When:** During development (mid-implementation checkpoint)
Maps requirements to test coverage:
- Documents which tests validate each acceptance criterion
- Uses Given-When-Then for clarity (documentation only, not BDD code)
- Identifies coverage gaps with severity ratings
- Creates traceability matrix for audit purposes
#### 4. NFR Assessment (`*nfr`)
**When:** During development or early review (validate quality attributes)
Validates non-functional requirements:
- **Core Four**: Security, Performance, Reliability, Maintainability
- **Evidence-Based**: Looks for actual implementation proof
- **Gate Integration**: NFR failures directly impact quality gates
#### 5. Comprehensive Test Architecture Review (`*review`)
**When:** After development complete, story marked "Ready for Review"
When you run `@qa *review {story}`, Quinn performs:
- **Requirements Traceability**: Maps every acceptance criterion to its validating tests
- **Test Level Analysis**: Ensures appropriate testing at unit, integration, and E2E levels
- **Coverage Assessment**: Identifies gaps and redundant test coverage
- **Active Refactoring**: Improves code quality directly when safe
- **Quality Gate Decision**: Issues PASS/CONCERNS/FAIL status based on findings
#### 6. Quality Gates (`*gate`)
**When:** After review fixes or when gate status needs updating
Manages quality gate decisions:
- **Deterministic Rules**: Clear criteria for PASS/CONCERNS/FAIL
- **Parallel Authority**: QA owns gate files in `docs/qa/gates/`
- **Advisory Nature**: Provides recommendations, not blocks
- **Waiver Support**: Documents accepted risks when needed
**Note:** Gates are advisory; teams choose their quality bar. WAIVED requires reason, approver, and expiry date. See `templates/qa-gate-tmpl.yaml` for schema and `tasks/review-story.md` (gate rules) and `tasks/risk-profile.md` for scoring.
### Working with the Test Architect
#### Integration with BMad Workflow
The Test Architect provides value throughout the entire development lifecycle. Here's when and how to leverage each capability:
| **Stage** | **Command** | **When to Use** | **Value** | **Output** |
| ------------------ | ----------- | ----------------------- | -------------------------- | -------------------------------------------------------------- |
| **Story Drafting** | `*risk` | After SM drafts story | Identify pitfalls early | `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md` |
| | `*design` | After risk assessment | Guide dev on test strategy | `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md` |
| **Development** | `*trace` | Mid-implementation | Verify test coverage | `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md` |
| | `*nfr` | While building features | Catch quality issues early | `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md` |
| **Review** | `*review` | Story marked complete | Full quality assessment | QA Results in story + gate file |
| **Post-Review** | `*gate` | After fixing issues | Update quality decision | Updated `docs/qa/gates/{epic}.{story}-{slug}.yml` |
#### Example Commands
```bash
# Planning Stage - Run these BEFORE development starts
@qa *risk {draft-story} # What could go wrong?
@qa *design {draft-story} # What tests should we write?
# Development Stage - Run these DURING coding
@qa *trace {story} # Are we testing everything?
@qa *nfr {story} # Are we meeting quality standards?
# Review Stage - Run when development complete
@qa *review {story} # Comprehensive assessment + refactoring
# Post-Review - Run after addressing issues
@qa *gate {story} # Update gate status
```
### Quality Standards Enforced
Quinn enforces these test quality principles:
- **No Flaky Tests**: Ensures reliability through proper async handling
- **No Hard Waits**: Dynamic waiting strategies only
- **Stateless & Parallel-Safe**: Tests run independently
- **Self-Cleaning**: Tests manage their own test data
- **Appropriate Test Levels**: Unit for logic, integration for interactions, E2E for journeys
- **Explicit Assertions**: Keep assertions in tests, not helpers
### Gate Status Meanings
- **PASS**: All critical requirements met, no blocking issues
- **CONCERNS**: Non-critical issues found, team should review
- **FAIL**: Critical issues that should be addressed (security risks, missing P0 tests)
- **WAIVED**: Issues acknowledged but explicitly accepted by team
### Special Situations
**High-Risk Stories:**
- Always run `*risk` and `*design` before development starts
- Consider mid-development `*trace` and `*nfr` checkpoints
**Complex Integrations:**
- Run `*trace` during development to ensure all integration points tested
- Follow up with `*nfr` to validate performance across integrations
**Performance-Critical:**
- Run `*nfr` early and often during development
- Don't wait until review to discover performance issues
**Brownfield/Legacy Code:**
- Start with `*risk` to identify regression dangers
- Use `*review` with extra focus on backward compatibility
### Best Practices
- **Early Engagement**: Run `*design` and `*risk` during story drafting
- **Risk-Based Focus**: Let risk scores drive test prioritization
- **Iterative Improvement**: Use QA feedback to improve future stories
- **Gate Transparency**: Share gate decisions with the team
- **Continuous Learning**: QA documents patterns for team knowledge sharing
- **Brownfield Care**: Pay extra attention to regression risks in existing systems
### Output Paths Reference
Quick reference for where Test Architect outputs are stored:
```text
*risk-profile → docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
*test-design → docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
*trace → docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
*nfr-assess → docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
*review → QA Results section in story + gate file reference
*gate → docs/qa/gates/{epic}.{story}-{slug}.yml
```
## Technical Preferences System
BMad includes a personalization system through the `technical-preferences.md` file located in `.bmad-core/data/` - this can help bias the PM and Architect to recommend your preferences for design patterns, technology selection, or anything else you would like to put in here.
### Using with Web Bundles
When creating custom web bundles or uploading to AI platforms, include your `technical-preferences.md` content to ensure agents have your preferences from the start of any conversation.
## Core Configuration
The `.bmad-core/core-config.yaml` file is a critical config that enables BMad to work seamlessly with differing project structures, more options will be made available in the future. Currently the most important is the devLoadAlwaysFiles list section in the yaml.
### Developer Context Files
Define which files the dev agent should always load:
```yaml
devLoadAlwaysFiles:
- docs/architecture/coding-standards.md
- docs/architecture/tech-stack.md
- docs/architecture/project-structure.md
```
You will want to verify from sharding your architecture that these documents exist, that they are as lean as possible, and contain exactly the information you want your dev agent to ALWAYS load into its context. These are the rules the agent will follow.
As your project grows and the code starts to build consistent patterns, coding standards should be reduced to include only the standards the agent still needs enforced. The agent will look at surrounding code in files to infer the coding standards that are relevant to the current task.
## Getting Help
- **Discord Community**: [Join Discord](https://discord.gg/gk8jAdXWmj)
- **GitHub Issues**: [Report bugs](https://github.com/bmadcode/bmad-method/issues)
- **Documentation**: [Browse docs](https://github.com/bmadcode/bmad-method/docs)
- **YouTube**: [BMadCode Channel](https://www.youtube.com/@BMadCode)
## Conclusion
Remember: BMad is designed to enhance your development process, not replace your expertise. Use it as a powerful tool to accelerate your projects while maintaining control over design decisions and implementation details.

155
docs/versioning-and-releases.md
View File

@@ -1,155 +0,0 @@
# Versioning and Releases
BMad Method uses a simplified release system with manual control and automatic release notes generation.
## 🚀 Release Workflow
### Command Line Release (Recommended)
The fastest way to create a release with beautiful release notes:
```bash
# Preview what will be in the release
npm run preview:release
# Create a release
npm run release:patch # 5.1.0 → 5.1.1 (bug fixes)
npm run release:minor # 5.1.0 → 5.2.0 (new features)
npm run release:major # 5.1.0 → 6.0.0 (breaking changes)
# Watch the release process
npm run release:watch
```
### One-Liner Release
```bash
npm run preview:release && npm run release:minor && npm run release:watch
```
## 📝 What Happens Automatically
When you trigger a release, the GitHub Actions workflow automatically:
1. ✅ **Validates** - Runs tests, linting, and formatting checks
2. ✅ **Bumps Version** - Updates `package.json` and installer version
3. ✅ **Generates Release Notes** - Categorizes commits since last release:
- ✨ **New Features** (`feat:`, `Feature:`)
- 🐛 **Bug Fixes** (`fix:`, `Fix:`)
- 🔧 **Maintenance** (`chore:`, `Chore:`)
- 📦 **Other Changes** (everything else)
4. ✅ **Creates Git Tag** - Tags the release version
5. ✅ **Publishes to NPM** - With `@latest` tag for user installations
6. ✅ **Creates GitHub Release** - With formatted release notes
## 📋 Sample Release Notes
The workflow automatically generates professional release notes like this:
````markdown
## 🚀 What's New in v5.2.0
### ✨ New Features
- feat: add team collaboration mode
- feat: enhance CLI with interactive prompts
### 🐛 Bug Fixes
- fix: resolve installation path issues
- fix: handle edge cases in agent loading
### 🔧 Maintenance
- chore: update dependencies
- chore: improve error messages
## 📦 Installation
```bash
npx bmad-method install
```
````
**Full Changelog**: https://github.com/bmadcode/BMAD-METHOD/compare/v5.1.0...v5.2.0
````
## 🎯 User Installation
After any release, users can immediately get the new version with:
```bash
npx bmad-method install # Always gets latest release
```
## 📊 Preview Before Release
Always preview what will be included in your release:
```bash
npm run preview:release
```
This shows:
- Commits since last release
- Categorized changes
- Estimated next version
- Release notes preview
## 🔧 Manual Release (GitHub UI)
You can also trigger releases through GitHub Actions:
1. Go to **GitHub Actions** → **Manual Release**
2. Click **"Run workflow"**
3. Choose version bump type (patch/minor/major)
4. Everything else happens automatically
## 📈 Version Strategy
- **Patch** (5.1.0 → 5.1.1): Bug fixes, minor improvements
- **Minor** (5.1.0 → 5.2.0): New features, enhancements
- **Major** (5.1.0 → 6.0.0): Breaking changes, major redesigns
## 🛠️ Development Workflow
1. **Develop Freely** - Merge PRs to main without triggering releases
2. **Test Unreleased Changes** - Clone repo to test latest main branch
3. **Release When Ready** - Use command line or GitHub Actions to cut releases
4. **Users Get Updates** - Via simple `npx bmad-method install` command
This gives you complete control over when releases happen while automating all the tedious parts like version bumping, release notes, and publishing.
## 🔍 Troubleshooting
### Check Release Status
```bash
gh run list --workflow="Manual Release"
npm view bmad-method dist-tags
git tag -l | sort -V | tail -5
```
### View Latest Release
```bash
gh release view --web
npm view bmad-method versions --json
```
### If Version Sync Needed
If your local files don't match the published version after a release:
```bash
./tools/sync-version.sh # Automatically syncs local files with npm latest
```
### If Release Fails
- Check GitHub Actions logs: `gh run view <run-id> --log-failed`
- Verify NPM tokens are configured
- Ensure branch protection allows workflow pushes
````

48
docs/versions.md
View File

@@ -1,48 +0,0 @@
# Version History
## Previous Versions
- [Version 3](https://github.com/bmadcode/BMad-Method/tree/V3)
- [Version 2](https://github.com/bmadcode/BMad-Method/tree/V2)
- [Version 1](https://github.com/bmadcode/BMad-Method/tree/V1)
## Current Version: V4
Guiding Principles of V4:
- Simple to understand, install and start using
- Support Greenfield and Brownfield Scenarios
- Greater configurability and more scenarios for usage - but kept out of the main package to maintain simplicity
- Helpers for installers and web builders that will work with any OS and IDE easily
- Align all agents to be the same for IDE and Web, without losing the power of the web versions, or the leanness of the files in the IDE to reduce context
- Further improvements to the two most important agents - the SM and DEV
## V3
With the customizability of V2, there were still some issues. A PM could only easily do one thing, create a PRD. And maintaining the consistency between Web and IDE agents was a pain.
V3 didn't fix the disconnect, but it did make it easier to maintain them all in a single folder, but there were only two official ide agents - all the rest were really made and optimized for the web.
V3's biggest impact was a full explosion of customizability. Tasks, Personas, Agent Configurations, Doc Templates, data payloads.
BUT - the BIGGEST change was the realization that we were barely scratching the surface of what could be loaded into Gemini Gems and still have very long chats. The BMad AGENT arose, and with a single V3 release - the future of the BMad Method was changed forever.
Now, instead of configuring 4+ web agents, all needing many files uploaded to create them, a single Agent called BMad, with a whole team, and the ability to switch and maintain personas evolved. Now you could in the same chat thread, talk to the whole team, or anyone on the team. No more exporting and reimporting docs to different chats - all of the sudden, you could finish the PRD, and ask Josh to pass it off to the Architect, and that was it, the architect just had it and we moved on! And all of that with just 7 total files to upload, delivering all power.
But V3 had a major flaw - with massive configuration comes massive complexity - and in some ways, V3 started to get away from core principles - power through simplicity. The core system needs to do one thing well and be solid, and not stretch too thing with every possible thing.
Also - while the dev is amazing and better in V3 than all the past, along with the SM - the dev started over documenting every step and really started to bloat stories with their own notes. And the SM was forgetting to add details to stories, or embellishing information. This was fixed somewhat in V3.1 - but the dev is still over explaining everything it does, instead of just capturing the changes to the story.
## V2
After V1 proved that the BMad method was solid and repeatable, 2 key ideas emerged. Separation of concerns, and building for the web made easier. By separating out templates - it was now much easier for the PRD fields to be customized, or the architecture.
And the introduction that really supercharged everything in my opinion, the web versions! There were 4 hard coded web variants hand crafted - and we saw that we could, dirt cheap, work with agents for hours in the massive context of Gemini - from a PRD generating PM, through to an architect and even an analyst that could help us do extensive market research and brain storming.
What I never expected is the names would stick, and people would keep the sample names I made that I thought people would configure. But now 4 version is, people refer to Mary, and John, and Bob! And when I randomly changed the names, I got A LOT of feedback! These have become trusted allies people are relying on, including for me!
## V1
Believe it or not (well you can view the link), V1 was a simple 7 file system! 7 Core agents working in harmony to help build a pretty specific type of application. But it showed its power and adaptability.
Meant to be a simple Tech Demo showing how custom agents with agile personas can help streamline your project, and create rails for your dev agents that to that point had gone unmatched - while also putting a focus on the planning phases - the project sparked the imagination of many, and a seed of a potential was realized.

606
docs/working-in-the-brownfield.md
View File

@@ -1,606 +0,0 @@
# Working in the Brownfield: A Complete Guide
## Critical Tip
Regardless of what you plan for your existing project you want to start agentic coding with, producing contextual artifacts for agents is of the highest importance.
If using Claude Code - it is recommended to use the document-project task with the architect to systematically produce important key artifacts for your codebase.
Optionally you can product context information and understanding for your repo utilizing web agents like Gemini. If its already in github, you can provide the project URL in gemini and use the agents to help analyze or document the project with the team fullstack or the architect specific gem.
If your project is too large, you can also flatten your codebase - which can make it easier to upload or use with some tools. You can read more about the optional tool in the [Flattener Guide](./flattener.md)
## What is Brownfield Development?
Brownfield development refers to adding features, fixing bugs, or modernizing existing software projects. Unlike greenfield (new) projects, brownfield work requires understanding existing code, respecting constraints, and ensuring new changes integrate seamlessly without breaking existing functionality.
## When to Use BMad for Brownfield
- Add significant new features to existing applications
- Modernize legacy codebases
- Integrate new technologies or services
- Refactor complex systems
- Fix bugs that require architectural understanding
- Document undocumented systems
## When NOT to use a Brownfield Flow
If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask it to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there.
## The Complete Brownfield Workflow
Starting in the Web Option (potentially save some cost but a potentially more frustrating experience):
1. **Follow the [<ins>User Guide - Installation</ins>](user-guide.md#installation) steps to setup your agent in the web.**
2. **Generate a 'flattened' single file of your entire codebase** run: `npx bmad-method flatten`
Starting in an IDE with large context and good models (Its important to use quality models for this process for the best results)
1. In Claude Code or a similar IDE, select the architect agent and then use the \*document-project task. You will want to ensure you are validating and directing the agent to produce the best possible documents for LLMs to understand your code base, and not include any misleading or unnecessary info.
### Choose Your Approach
#### Approach A: PRD-First (Recommended if adding very large and complex new features, single or multiple epics or massive changes)
**Best for**: Large codebases, monorepos, or when you know exactly what you want to build
1. **Create PRD First** to define requirements
2. **Document only relevant areas** based on PRD needs
3. **More efficient** - avoids documenting unused code
#### Approach B: Document-First (Good for Smaller Projects)
**Best for**: Smaller codebases, unknown systems, or exploratory changes
1. **Document entire system** first
2. **Create PRD** with full context
3. **More thorough** - captures everything
### Approach A: PRD-First Workflow (Recommended)
#### Phase 1: Define Requirements First
**In Gemini Web (with your flattened-codebase.xml uploaded):**
```bash
@pm
*create-brownfield-prd
```
The PM will:
- **Ask about your enhancement** requirements
- **Explore the codebase** to understand current state
- **Identify affected areas** that need documentation
- **Create focused PRD** with clear scope
**Key Advantage**: The PRD identifies which parts of your monorepo/large codebase actually need documentation!
#### Phase 2: Focused Documentation
**Still in Gemini Web, now with PRD context:**
```bash
@architect
*document-project
```
The architect will:
- **Ask about your focus** if no PRD was provided
- **Offer options**: Create PRD, provide requirements, or describe the enhancement
- **Reference the PRD/description** to understand scope
- **Focus on relevant modules** identified in PRD or your description
- **Skip unrelated areas** to keep docs lean
- **Generate ONE architecture document** for all environments
The architect creates:
- **One comprehensive architecture document** following fullstack-architecture template
- **Covers all system aspects** in a single file
- **Easy to copy and save** as `docs/architecture.md`
- **Can be sharded later** in IDE if desired
For example, if you say "Add payment processing to user service":
- Documents only: user service, API endpoints, database schemas, payment integrations
- Creates focused source tree showing only payment-related code paths
- Skips: admin panels, reporting modules, unrelated microservices
### Approach B: Document-First Workflow
#### Phase 1: Document the Existing System
**Best Approach - Gemini Web with 1M+ Context**:
1. **Go to Gemini Web** (gemini.google.com)
2. **Upload your project**:
- **Option A**: Paste your GitHub repository URL directly
- **Option B**: Upload your flattened-codebase.xml file
3. **Load the architect agent**: Upload `dist/agents/architect.txt`
4. **Run documentation**: Type `*document-project`
The architect will generate comprehensive documentation of everything.
#### Phase 2: Plan Your Enhancement
##### Option A: Full Brownfield Workflow (Recommended for Major Changes)
**1. Create Brownfield PRD**:
```bash
@pm
*create-brownfield-prd
```
The PM agent will:
- **Analyze existing documentation** from Phase 1
- **Request specific enhancement details** from you
- **Assess complexity** and recommend approach
- **Create epic/story structure** for the enhancement
- **Identify risks and integration points**
**How PM Agent Gets Project Context**:
- In Gemini Web: Already has full project context from Phase 1 documentation
- In IDE: Will ask "Please provide the path to your existing project documentation"
**Key Prompts You'll Encounter**:
- "What specific enhancement or feature do you want to add?"
- "Are there any existing systems or APIs this needs to integrate with?"
- "What are the critical constraints we must respect?"
- "What is your timeline and team size?"
**2. Create Brownfield Architecture**:
```bash
@architect
*create-brownfield-architecture
```
The architect will:
- **Review the brownfield PRD**
- **Design integration strategy**
- **Plan migration approach** if needed
- **Identify technical risks**
- **Define compatibility requirements**
##### Option B: Quick Enhancement (For Focused Changes)
**For Single Epic Without Full PRD**:
```bash
@pm
*create-brownfield-epic
```
Use when:
- Enhancement is well-defined and isolated
- Existing documentation is comprehensive
- Changes don't impact multiple systems
- You need quick turnaround
**For Single Story**:
```bash
@pm
*create-brownfield-story
```
Use when:
- Bug fix or tiny feature
- Very isolated change
- No architectural impact
- Clear implementation path
### Phase 3: Validate Planning Artifacts
```bash
@po
*execute-checklist-po
```
The PO ensures:
- Compatibility with existing system
- No breaking changes planned
- Risk mitigation strategies in place
- Clear integration approach
### Phase 4: Save and Shard Documents
1. Save your PRD and Architecture as:
docs/prd.md
docs/architecture.md
(Note: You can optionally prefix with 'brownfield-' if managing multiple versions)
2. Shard your docs:
In your IDE
```bash
@po
shard docs/prd.md
```
```bash
@po
shard docs/architecture.md
```
### Phase 5: Transition to Development
**Follow the [<ins>Enhanced IDE Development Workflow</ins>](enhanced-ide-development-workflow.md)**
## Brownfield Best Practices
### 1. Always Document First
Even if you think you know the codebase:
- Run `document-project` to capture current state
- AI agents need this context
- Discovers undocumented patterns
### 2. Respect Existing Patterns
The brownfield templates specifically look for:
- Current coding conventions
- Existing architectural patterns
- Technology constraints
- Team preferences
### 3. Plan for Gradual Rollout
Brownfield changes should:
- Support feature flags
- Plan rollback strategies
- Include migration scripts
- Maintain backwards compatibility
### 4. Test Integration Thoroughly
#### Why the Test Architect is Critical for Brownfield
In brownfield projects, the Test Architect (Quinn) becomes your safety net against breaking existing functionality. Unlike greenfield where you're building fresh, brownfield requires careful validation that new changes don't destabilize what already works.
#### Brownfield-Specific Testing Challenges
The Test Architect addresses unique brownfield complexities:
| **Challenge** | **How Test Architect Helps** | **Command** |
| --------------------------- | ------------------------------------------------- | ------------------- |
| **Regression Risks** | Identifies which existing features might break | `*risk` |
| **Legacy Dependencies** | Maps integration points and hidden dependencies | `*trace` |
| **Performance Degradation** | Validates no slowdown in existing flows | `*nfr` |
| **Coverage Gaps** | Finds untested legacy code that new changes touch | `*design` |
| **Breaking Changes** | Detects API/contract violations | `*review` |
| **Migration Safety** | Validates data transformations and rollback plans | `*risk` + `*review` |
#### Complete Test Architect Workflow for Brownfield
##### Stage 1: Before Development (Risk & Strategy)
**CRITICAL FOR BROWNFIELD - Run These First:**
```bash
# 1. RISK ASSESSMENT (Run IMMEDIATELY after story creation)
@qa *risk {brownfield-story}
# Identifies: Legacy dependencies, breaking changes, integration points
# Output: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
# Brownfield Focus:
# - Regression probability scoring
# - Affected downstream systems
# - Data migration risks
# - Rollback complexity
# 2. TEST DESIGN (After risk assessment)
@qa *design {brownfield-story}
# Creates: Regression test strategy + new feature tests
# Output: docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
# Brownfield Focus:
# - Existing functionality that needs regression tests
# - Integration test requirements
# - Performance benchmarks to maintain
# - Feature flag test scenarios
```
##### Stage 2: During Development (Continuous Validation)
**Monitor Integration Health While Coding:**
```bash
# 3. REQUIREMENTS TRACING (Mid-development checkpoint)
@qa *trace {brownfield-story}
# Maps: New requirements + existing functionality preservation
# Output: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
# Brownfield Focus:
# - Existing features that must still work
# - New/old feature interactions
# - API contract preservation
# - Missing regression test coverage
# 4. NFR VALIDATION (Before considering "done")
@qa *nfr {brownfield-story}
# Validates: Performance, security, reliability unchanged
# Output: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
# Brownfield Focus:
# - Performance regression detection
# - Security implications of integrations
# - Backward compatibility validation
# - Load/stress on legacy components
```
##### Stage 3: Code Review (Deep Integration Analysis)
**Comprehensive Brownfield Review:**
```bash
# 5. FULL REVIEW (When development complete)
@qa *review {brownfield-story}
# Performs: Deep analysis + active refactoring
# Outputs:
# - QA Results in story file
# - Gate file: docs/qa/gates/{epic}.{story}-{slug}.yml
```
The review specifically analyzes:
- **API Breaking Changes**: Validates all existing contracts maintained
- **Data Migration Safety**: Checks transformation logic and rollback procedures
- **Performance Regression**: Compares against baseline metrics
- **Integration Points**: Validates all touchpoints with legacy code
- **Feature Flag Logic**: Ensures proper toggle behavior
- **Dependency Impacts**: Maps affected downstream systems
##### Stage 4: Post-Review (Gate Updates)
```bash
# 6. GATE STATUS UPDATE (After addressing issues)
@qa *gate {brownfield-story}
# Updates: Quality gate decision after fixes
# Output: docs/qa/gates/{epic}.{story}-{slug}.yml
# Brownfield Considerations:
# - May WAIVE certain legacy code issues
# - Documents technical debt acceptance
# - Tracks migration progress
```
#### Brownfield-Specific Risk Scoring
The Test Architect uses enhanced risk scoring for brownfield:
| **Risk Category** | **Brownfield Factors** | **Impact on Gate** |
| ---------------------- | ------------------------------------------ | ------------------- |
| **Regression Risk** | Number of integration points × Age of code | Score ≥9 = FAIL |
| **Data Risk** | Migration complexity × Data volume | Score ≥6 = CONCERNS |
| **Performance Risk** | Current load × Added complexity | Score ≥6 = CONCERNS |
| **Compatibility Risk** | API consumers × Contract changes | Score ≥9 = FAIL |
#### Brownfield Testing Standards
Quinn enforces additional standards for brownfield:
- **Regression Test Coverage**: Every touched legacy module needs tests
- **Performance Baselines**: Must maintain or improve current metrics
- **Rollback Procedures**: Every change needs a rollback plan
- **Feature Flags**: All risky changes behind toggles
- **Integration Tests**: Cover all legacy touchpoints
- **Contract Tests**: Validate API compatibility
- **Data Validation**: Migration correctness checks
#### Quick Reference: Brownfield Test Commands
| **Scenario** | **Commands to Run** | **Order** | **Why Critical** |
| --------------------------------- | ---------------------------------------------------- | ---------- | ----------------------------- |
| **Adding Feature to Legacy Code** | `*risk` → `*design` → `*trace` → `*review` | Sequential | Map all dependencies first |
| **API Modification** | `*risk` → `*design` → `*nfr` → `*review` | Sequential | Prevent breaking consumers |
| **Performance-Critical Change** | `*nfr` early and often → `*review` | Continuous | Catch degradation immediately |
| **Data Migration** | `*risk` → `*design` → `*trace` → `*review` → `*gate` | Full cycle | Ensure data integrity |
| **Bug Fix in Complex System** | `*risk` → `*trace` → `*review` | Focused | Prevent side effects |
#### Integration with Brownfield Scenarios
**Scenario-Specific Guidance:**
1. **Legacy Code Modernization**
- Start with `*risk` to map all dependencies
- Use `*design` to plan strangler fig approach
- Run `*trace` frequently to ensure nothing breaks
- `*review` with focus on gradual migration
2. **Adding Features to Monolith**
- `*risk` identifies integration complexity
- `*design` plans isolation strategies
- `*nfr` monitors performance impact
- `*review` validates no monolith degradation
3. **Microservice Extraction**
- `*risk` maps service boundaries
- `*trace` ensures functionality preservation
- `*nfr` validates network overhead acceptable
- `*gate` documents accepted trade-offs
4. **Database Schema Changes**
- `*risk` assesses migration complexity
- `*design` plans backward-compatible approach
- `*trace` maps all affected queries
- `*review` validates migration safety
### 5. Communicate Changes
Document:
- What changed and why
- Migration instructions
- New patterns introduced
- Deprecation notices
## Common Brownfield Scenarios
### Scenario 1: Adding a New Feature
1. Document existing system
2. Create brownfield PRD focusing on integration
3. **Test Architect Early Involvement**:
- Run `@qa *risk` on draft stories to identify integration risks
- Use `@qa *design` to plan regression test strategy
4. Architecture emphasizes compatibility
5. Stories include integration tasks with test requirements
6. **During Development**:
- Developer runs `@qa *trace` to verify coverage
- Use `@qa *nfr` to monitor performance impact
7. **Review Stage**: `@qa *review` validates integration safety
### Scenario 2: Modernizing Legacy Code
1. Extensive documentation phase
2. PRD includes migration strategy
3. **Test Architect Strategy Planning**:
- `@qa *risk` assesses modernization complexity
- `@qa *design` plans parallel testing approach
4. Architecture plans gradual transition (strangler fig pattern)
5. Stories follow incremental modernization with:
- Regression tests for untouched legacy code
- Integration tests for new/old boundaries
- Performance benchmarks at each stage
6. **Continuous Validation**: Run `@qa *trace` after each increment
7. **Gate Management**: Use `@qa *gate` to track technical debt acceptance
### Scenario 3: Bug Fix in Complex System
1. Document relevant subsystems
2. Use `create-brownfield-story` for focused fix
3. **Test Architect Risk Assessment**: Run `@qa *risk` to identify side effect potential
4. Include regression test requirements from `@qa *design` output
5. **During Fix**: Use `@qa *trace` to map affected functionality
6. **Before Commit**: Run `@qa *review` for comprehensive validation
7. Test Architect validates no side effects using:
- Risk profiling for side effect analysis (probability × impact scoring)
- Trace matrix to ensure fix doesn't break related features
- NFR assessment to verify performance/security unchanged
- Gate decision documents fix safety
### Scenario 4: API Integration
1. Document existing API patterns
2. PRD defines integration requirements
3. **Test Architect Contract Analysis**:
- `@qa *risk` identifies breaking change potential
- `@qa *design` creates contract test strategy
4. Architecture ensures consistent patterns
5. **API Testing Focus**:
- Contract tests for backward compatibility
- Integration tests for new endpoints
- Performance tests for added load
6. Stories include API documentation updates
7. **Validation Checkpoints**:
- `@qa *trace` maps all API consumers
- `@qa *nfr` validates response times
- `@qa *review` ensures no breaking changes
8. **Gate Decision**: Document any accepted breaking changes with migration path
## Troubleshooting
### "The AI doesn't understand my codebase"
**Solution**: Re-run `document-project` with more specific paths to critical files
### "Generated plans don't fit our patterns"
**Solution**: Update generated documentation with your specific conventions before planning phase
### "Too much boilerplate for small changes"
**Solution**: Use `create-brownfield-story` instead of full workflow
### "Integration points unclear"
**Solution**: Provide more context during PRD creation, specifically highlighting integration systems
## Quick Reference
### Brownfield-Specific Commands
```bash
# Document existing project
@architect *document-project
# Create enhancement PRD
@pm *create-brownfield-prd
# Create architecture with integration focus
@architect *create-brownfield-architecture
# Quick epic creation
@pm *create-brownfield-epic
# Single story creation
@pm *create-brownfield-story
```
### Test Architect Commands for Brownfield
Note: Short forms shown below. Full commands: `*risk-profile`, `*test-design`, `*nfr-assess`, `*trace-requirements`
```bash
# BEFORE DEVELOPMENT (Planning)
@qa *risk {story} # Assess regression & integration risks
@qa *design {story} # Plan regression + new feature tests
# DURING DEVELOPMENT (Validation)
@qa *trace {story} # Verify coverage of old + new
@qa *nfr {story} # Check performance degradation
# AFTER DEVELOPMENT (Review)
@qa *review {story} # Deep integration analysis
@qa *gate {story} # Update quality decision
```
### Decision Tree
```text
Do you have a large codebase or monorepo?
├─ Yes → PRD-First Approach
│ └─ Create PRD → Document only affected areas
└─ No → Is the codebase well-known to you?
├─ Yes → PRD-First Approach
└─ No → Document-First Approach
Is this a major enhancement affecting multiple systems?
├─ Yes → Full Brownfield Workflow
│ └─ ALWAYS run Test Architect *risk + *design first
└─ No → Is this more than a simple bug fix?
├─ Yes → *create-brownfield-epic
│ └─ Run Test Architect *risk for integration points
└─ No → *create-brownfield-story
└─ Still run *risk if touching critical paths
Does the change touch legacy code?
├─ Yes → Test Architect is MANDATORY
│ ├─ *risk → Identify regression potential
│ ├─ *design → Plan test coverage
│ └─ *review → Validate no breakage
└─ No → Test Architect is RECOMMENDED
└─ *review → Ensure quality standards
```
## Conclusion
Brownfield development with BMad Method provides structure and safety when modifying existing systems. The Test Architect becomes your critical safety net, using risk assessment, regression testing, and continuous validation to ensure new changes don't destabilize existing functionality.
**The Brownfield Success Formula:**
1. **Document First** - Understand what exists
2. **Assess Risk Early** - Use Test Architect `*risk` before coding
3. **Plan Test Strategy** - Design regression + new feature tests
4. **Validate Continuously** - Check integration health during development
5. **Review Comprehensively** - Deep analysis before committing
6. **Gate Decisively** - Document quality decisions
Remember: **In brownfield, the Test Architect isn't optional - it's your insurance policy against breaking production.**