feat: Installation includes a getting started user guide with detailed mermaid diagram
This commit is contained in:
Brian Madison
@@ -1,20 +0,0 @@
|
||||
# BMad Method Guide for Claude Code
|
||||
|
||||
For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
|
||||
|
||||
## Installation
|
||||
|
||||
When running `npx bmad-method install`, select **Claude Code** as your IDE. This creates:
|
||||
|
||||
- `.bmad-core/` folder with all agents, tasks, templates and other data files
|
||||
- `.claude/commands/BMad/agents` folder with agent command files (`.md`)
|
||||
- `.claude/commands/BMad/tasks` folder with stand alone task files (`.md`)
|
||||
|
||||
## Using BMad Agents in Claude Code
|
||||
|
||||
Type `/agent-name` in your chat to activate an agent.
|
||||
|
||||
## Tips for Claude Code Users
|
||||
|
||||
- Commands are auto-suggested as you type `/`
|
||||
- More coming soon...
|
||||
@@ -1,17 +0,0 @@
|
||||
# BMad Method Guide for Cline (VS Code)
|
||||
|
||||
For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
|
||||
|
||||
## Installation
|
||||
|
||||
When running `npx bmad-method install`, select **Cline** as your IDE. This creates:
|
||||
|
||||
- `.bmad-core/` folder with all agents, tasks, templates and other data files
|
||||
- `.clinerules/` directory with numbered agent rule files (`.md`)
|
||||
- Agents ordered by priority (bmad-master first)
|
||||
|
||||
## Using BMad Agents in Cline
|
||||
|
||||
1. **Open Cline panel** in VS Code
|
||||
2. **Type `@agent-name`** in the chat (e.g., `@dev`, `@sm`, `@architect`)
|
||||
3. The agent adopts that persona for the conversation
|
||||
@@ -1,14 +0,0 @@
|
||||
# BMad Method Guide for Cursor
|
||||
|
||||
For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
|
||||
|
||||
## Installation
|
||||
|
||||
When running `npx bmad-method install`, select **Cursor** as your IDE. This creates:
|
||||
|
||||
- `.bmad-core/` folder with all agents, tasks, templates and other data files
|
||||
- `.cursor/rules/` folder with agent rule files (`.mdc`)
|
||||
|
||||
## Using BMad Agents in Cursor
|
||||
|
||||
Type `@agent-name` in chat (Ctrl+L / Cmd+L) to activate an agent. Make sure you select the icon that looks like a small ruler if presented with multiple options in the popup window.
|
||||
@@ -1,32 +0,0 @@
|
||||
# BMad Method Guide for Gemini CLI
|
||||
|
||||
For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
|
||||
|
||||
## Installation
|
||||
|
||||
When running `npx bmad-method install`, select **Gemini CLI** as your IDE. This creates:
|
||||
|
||||
- `.bmad-core/` folder with all agents, tasks, templates and other data files
|
||||
- `.gemini/bmad-method/` directory with all agent context in GEMINI.md file
|
||||
|
||||
## Using BMad Agents with Gemini CLI
|
||||
|
||||
Simply mention the agent in your prompt:
|
||||
|
||||
- "As \*dev, implement the login feature"
|
||||
- "Acting as \*architect, review this system design"
|
||||
- "\*sm, create the next story for our project"
|
||||
|
||||
The Gemini CLI automatically loads the appropriate agent context.
|
||||
|
||||
## Gemini CLI-Specific Features
|
||||
|
||||
- **Context files**: All agents loaded as context in `.gemini/bmad-method/GEMINI.md`
|
||||
- **Automatic loading**: GEMINI.md ensures agents are always available
|
||||
- **Natural language**: No special syntax needed, just mention the agent
|
||||
|
||||
## Tips for Gemini CLI Users
|
||||
|
||||
- Be explicit about which agent you're addressing
|
||||
- You can switch agents mid-conversation by mentioning a different one
|
||||
- The CLI maintains context across your session
|
||||
@@ -1,42 +0,0 @@
|
||||
# BMad Method Guide for GitHub Copilot
|
||||
|
||||
For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
|
||||
|
||||
## Installation
|
||||
|
||||
When running `npx bmad-method install`, select **GitHub Copilot** as your IDE. This command will perform the following actions:
|
||||
|
||||
- `.bmad-core/` folder with all agents, tasks, templates and other data files
|
||||
- Creates the `.vscode/` directory and add a `settings.json` file if it does not already exist, and add the basic configuration to enable GitHub Copilot's agent mode.
|
||||
- Creates a chatmodes file under your .github folder for each specific agent being added
|
||||
|
||||
## Using BMAD Agents in GitHub Copilot
|
||||
|
||||
1. **Open GitHub Copilot chat** in VS Code (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux).
|
||||
2. Select the agent you want to use from the chat input's participant selector (e.g., `@workspace` > `dev`).
|
||||
3. The agent adopts that persona for the conversation.
|
||||
4. Use `*help` to see the commands available for the selected agent.
|
||||
|
||||
## Available Agents
|
||||
|
||||
You can switch between agents using the chat participant selector. The following agents are available for GitHub Copilot:
|
||||
|
||||
- `bmad-master` - Master Task Executor
|
||||
- `dev` - Development expert
|
||||
- `qa` - Quality Assurance specialist
|
||||
- `ux-expert` - UX specialist
|
||||
|
||||
## GitHub Copilot-Specific Features
|
||||
|
||||
- **Settings**: Use the `.vscode/settings.json` file to configure Copilot behavior. The installer can configure these for you.
|
||||
- `chat.agent.maxRequests`: Maximum requests per agent session (recommended: 15).
|
||||
- `github.copilot.chat.agent.runTasks`: Allow agents to run workspace tasks (e.g., from `package.json` scripts).
|
||||
- `github.copilot.chat.agent.autoFix`: Enable automatic error detection and fixing in generated code.
|
||||
- `chat.tools.autoApprove`: Auto-approve ALL tools without confirmation (use with caution).
|
||||
- **VS Code integration**: Works within VS Code's GitHub Copilot chat panel.
|
||||
- **Tool Confirmation**: Copilot will ask for confirmation before running tools that can modify files. You can approve a tool once, for the session, or always.
|
||||
|
||||
## Tips for GitHub Copilot Users
|
||||
|
||||
- You can use a `.github/copilot-instructions.md` file to provide additional context or instructions for your projects that are not covered by the BMAD framework.
|
||||
- BMAD agents can come with a pre-configured set of tools. You can see which tools an agent uses by looking at the `tools` section in its `.github/chatmodes/[agent].chatmode.md` file.
|
||||
@@ -1,15 +0,0 @@
|
||||
# BMad Method Guide for Roo Code
|
||||
|
||||
For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
|
||||
|
||||
## Installation
|
||||
|
||||
When running `npx bmad-method install`, select **Roo Code** as your IDE. This creates:
|
||||
|
||||
- `.bmad-core/` folder with all agents, tasks, templates and other data files
|
||||
- `.roomodes` file in project root with custom modes
|
||||
|
||||
## Roo Code-Specific Features
|
||||
|
||||
- **Mode file**: `.roomodes` in project root
|
||||
- **Mode switching**: Use mode selecto
|
||||
@@ -1,14 +0,0 @@
|
||||
# BMad Method Guide for Trae
|
||||
|
||||
For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
|
||||
|
||||
## Installation
|
||||
|
||||
When running `npx bmad-method install`, select **Trae** as your IDE. This creates:
|
||||
|
||||
- `.bmad-core/` folder with all agents, tasks, templates and other data files
|
||||
- `.trae/rules/` folder with agent rule files (`.md`)
|
||||
|
||||
## Using BMad Agents in Trae
|
||||
|
||||
Type `@agent-name` in chat to activate an agent.
|
||||
@@ -1,14 +0,0 @@
|
||||
# BMad Method Guide for Windsurf
|
||||
|
||||
For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
|
||||
|
||||
## Installation
|
||||
|
||||
When running `npx bmad-method install`, select **Windsurf** as your IDE. This creates:
|
||||
|
||||
- `.bmad-core/` folder with all agents, tasks, templates and other data files
|
||||
- `.windsurf/rules/` folder with agent rule files (`.md`)
|
||||
|
||||
## Using BMad Agents in Windsurf
|
||||
|
||||
Type `@agent-name` in chat to activate an agent.
|
||||
@@ -1,167 +0,0 @@
|
||||
# BMad Method Universal Workflow Guide
|
||||
|
||||
This guide outlines the core BMad workflow that applies regardless of which AI-powered IDE you're using.
|
||||
|
||||
## Overview
|
||||
|
||||
The BMad Method follows a structured approach to AI-assisted software development:
|
||||
|
||||
1. **Install BMad** in your project
|
||||
2. **Plan with Gemini** using team-fullstack
|
||||
3. **Organize with bmad-master** (document sharding)
|
||||
4. **Develop iteratively** with SM → Dev cycles
|
||||
|
||||
## The Complete Workflow
|
||||
|
||||
### Phase 1: Project Setup
|
||||
|
||||
1. **Install BMad in your project**:
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, Trae, Roo Code, or GitHub Copilot)
|
||||
|
||||
2. **Verify installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
### Phase 2: Ideation & Planning (Gemini)
|
||||
|
||||
Use Google's Gemini for collaborative planning with the full team:
|
||||
|
||||
1. **Open [Google Gems](https://gemini.google.com/gems/view)**
|
||||
2. **Create a new Gem**:
|
||||
- Give it a title (e.g., "BMad Team Fullstack")
|
||||
- In the description enter:
|
||||
3. **Load team-fullstack**:
|
||||
- Copy contents of: `web-bundles/teams/team-fullstack.txt` from your project
|
||||
- Paste this content into the Gem setup to configure the team
|
||||
4. **Collaborate with the team**:
|
||||
- Business Analyst: Requirements gathering
|
||||
- Product Manager: Feature prioritization
|
||||
- Solution Architect: Technical design
|
||||
- UX Expert: User experience design
|
||||
|
||||
### Example Gemini Sessions:
|
||||
|
||||
```text
|
||||
"I want to build a [type] application that [core purpose].
|
||||
Help me brainstorm features and create a comprehensive PRD."
|
||||
|
||||
"Based on this PRD, design a scalable technical architecture
|
||||
that can handle [specific requirements]."
|
||||
```
|
||||
|
||||
5. **Export planning documents**:
|
||||
- Copy the PRD output and save as `docs/prd.md` in your project
|
||||
- Copy the architecture output and save as `docs/architecture.md` in your project
|
||||
|
||||
### Phase 3: Document Organization (IDE)
|
||||
|
||||
Switch back to your IDE for document management:
|
||||
|
||||
1. **Load bmad-master agent** (syntax varies by IDE)
|
||||
2. **Shard the PRD**:
|
||||
```
|
||||
*shard-doc docs/prd.md prd
|
||||
```
|
||||
3. **Shard the architecture**:
|
||||
```
|
||||
*shard-doc docs/architecture.md architecture
|
||||
```
|
||||
|
||||
**Result**: Organized folder structure:
|
||||
|
||||
- `docs/prd/` - Broken down PRD sections
|
||||
- `docs/architecture/` - Broken down architecture sections
|
||||
|
||||
### Phase 4: Iterative Development
|
||||
|
||||
Follow the SM → Dev cycle for systematic story development:
|
||||
|
||||
#### Story Creation (Scrum Master)
|
||||
|
||||
1. **Start new chat/conversation**
|
||||
2. **Load SM agent**
|
||||
3. **Execute**: `*create` (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. **Agent asks**: Which story to implement
|
||||
4. **Follow development tasks**
|
||||
5. **Complete implementation**
|
||||
6. **Update status**: Change to "Done"
|
||||
|
||||
#### Repeat Until Complete
|
||||
|
||||
- **SM**: Create next story → Review → Approve
|
||||
- **Dev**: Implement story → Complete → Mark done
|
||||
- **Continue**: Until all features implemented
|
||||
|
||||
## IDE-Specific Syntax
|
||||
|
||||
### Agent Loading Syntax by IDE:
|
||||
|
||||
- **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
|
||||
- **Cursor**: `@agent-name` (e.g., `@bmad-master`)
|
||||
- **Gemini CLI**: `*agent-name` (e.g., `*bmad-master`)
|
||||
- **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
|
||||
- **Trae**: `@agent-name` (e.g., `@bmad-master`)
|
||||
- **Roo Code**: Select mode from mode selector (e.g., `bmad-master`)
|
||||
- **GitHub Copilot**: Open the Chat view (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux) and select **Agent** from the chat mode selector.
|
||||
|
||||
### Chat Management:
|
||||
|
||||
- **Claude Code, Cursor, Windsurf, Trae**: Start new chats when switching agents
|
||||
- **Roo Code**: Switch modes within the same conversation
|
||||
|
||||
## Available Agents
|
||||
|
||||
### Core Development Agents:
|
||||
|
||||
- **bmad-master**: Universal task executor, document management
|
||||
- **sm**: Scrum Master for story creation and agile process
|
||||
- **dev**: Full-stack developer for implementation
|
||||
- **architect**: Solution architect for technical design
|
||||
|
||||
### Specialized Agents:
|
||||
|
||||
- **pm**: Product manager for planning and prioritization
|
||||
- **analyst**: Business analyst for requirements
|
||||
- **qa**: QA specialist for testing strategies
|
||||
- **po**: Product owner for backlog management
|
||||
- **ux-expert**: UX specialist for design
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Agent Specialization**: Each agent has specific expertise and responsibilities
|
||||
2. **Clean Handoffs**: Always start fresh when switching between agents
|
||||
3. **Status Tracking**: Maintain story statuses (Draft → Approved → InProgress → Done)
|
||||
4. **Iterative Development**: Complete one story before starting the next
|
||||
5. **Documentation First**: Always start with solid PRD and architecture
|
||||
|
||||
## Common Commands
|
||||
|
||||
Every agent supports these core commands:
|
||||
|
||||
- `*help` - Show available commands
|
||||
- `*status` - Show current context/progress
|
||||
- `*exit` - Exit the agent mode
|
||||
|
||||
## Success Tips
|
||||
|
||||
- **Use Gemini for big picture planning** - The team-fullstack bundle provides collaborative expertise
|
||||
- **Use bmad-master for document organization** - Sharding creates manageable chunks
|
||||
- **Follow the SM → Dev cycle religiously** - This ensures systematic progress
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
This workflow ensures systematic, AI-assisted development following agile principles with clear separation of concerns and consistent progress tracking.
|
||||
@@ -1,246 +0,0 @@
|
||||
# BMad-Method Agentic Agile Driven Development User Guide
|
||||
|
||||
This comprehensive guide will help you understand and effectively use the BMad Method framework for AI-assisted software development along with many expansion purposes.
|
||||
|
||||
## The BMad Plan and Execute Workflow
|
||||
|
||||
First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but its 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.
|
||||
|
||||
### 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 --> I["PO: Run Master Checklist"]
|
||||
H2 --> I
|
||||
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 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
|
||||
|
||||
### 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 --> B3{"QA: Review Story Draft (Optional)"}
|
||||
B3 -->|Review Requested| B4["QA: Review Story Against Artifacts"]
|
||||
B3 -->|Skip Review| C{"User Approval"}
|
||||
B4 --> C
|
||||
C -->|Approved| D["Dev: Sequential Task Execution"]
|
||||
C -->|Needs Changes| B2
|
||||
D --> E["Dev: Implement Tasks + Tests"]
|
||||
E --> F["Dev: Run All Validations"]
|
||||
F --> G["Dev: Mark Ready for Review + Add Notes"]
|
||||
G --> H{"User Verification"}
|
||||
H -->|Request QA Review| I["QA: Senior Dev Review + Active Refactoring"]
|
||||
H -->|Approve Without QA| M["IMPORTANT: Verify All Regression Tests and Linting are Passing"]
|
||||
I --> J["QA: Review, Refactor Code, Add Tests, Document Notes"]
|
||||
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 --> 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 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 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
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### Optional
|
||||
|
||||
If you want to do the planning in the Web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPT's:
|
||||
|
||||
1. Navigate to `dist/teams/`
|
||||
2. Copy `team-fullstack.txt` content
|
||||
3. Create new Gemini Gem or CustomGPT
|
||||
4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
### IDE Project Setup
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
## Special Agents
|
||||
|
||||
There are two bmad agents - in the future they will be consolidated into the 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 in the web by accessing the knowledge base and explaining anything to you about the process.
|
||||
|
||||
If you dont want to bother switching between different agents aside from the dev, this is the agent for you.
|
||||
|
||||
### BMad-Orchestrator
|
||||
|
||||
This agent should NOT be used within the IDE, it is a heavy weight special purpose agent that utilizes a lot of context and can morph into any other agent. This exists solely to facilitate the team's 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 Ide's, 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, 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
|
||||
|
||||
## 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 it's 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 just the items that the agent makes mistakes at still - must with the better models, they will look at surrounding code in files and not need a rule from that file to guide them.
|
||||
|
||||
## 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.
|
||||
@@ -1,361 +0,0 @@
|
||||
# Working in the Brownfield: A Complete Guide
|
||||
|
||||
> **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation Generation!**
|
||||
>
|
||||
> Gemini Web's 1M+ token context window or Gemini CLI (when its working) can analyze your ENTIRE codebase or critical sections of it all at once (obviously within reason):
|
||||
>
|
||||
> - Upload via GitHub URL or use gemini cli in the project folder
|
||||
> - If in the web: Upload up to 1000 files or the zipped project or just give it the github url
|
||||
|
||||
## 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 him 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
|
||||
|
||||
### 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 codebase uploaded):**
|
||||
|
||||
```bash
|
||||
@pm
|
||||
*create-doc 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
|
||||
@analyst
|
||||
*document-project
|
||||
```
|
||||
|
||||
The analyst 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 analyst creates:
|
||||
|
||||
- **One comprehensive architecture document** following fullstack-architecture template
|
||||
- **Covers all system aspects** in a single file
|
||||
- **Easy to copy and save** as `docs/project-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 up to 1000 files from your src/project folder
|
||||
- **Option C**: Zip your project and upload the archive
|
||||
3. **Load the analyst agent**: Upload `dist/agents/analyst.txt`
|
||||
4. **Run documentation**: Type `*document-project`
|
||||
|
||||
The analyst 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-doc 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-doc 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
|
||||
*brownfield-create-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
|
||||
*brownfield-create-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-master-checklist
|
||||
```
|
||||
|
||||
The PO ensures:
|
||||
|
||||
- Compatibility with existing system
|
||||
- No breaking changes planned
|
||||
- Risk mitigation strategies in place
|
||||
- Clear integration approach
|
||||
|
||||
### Phase 4: Transition to Development
|
||||
|
||||
Follow the enhanced IDE Development Workflow:
|
||||
|
||||
1. **Ensure documents are in project**:
|
||||
|
||||
- Copy `docs/prd.md` (or brownfield-prd.md)
|
||||
- Copy `docs/architecture.md` (or brownfield-architecture.md)
|
||||
|
||||
2. **Shard documents**:
|
||||
|
||||
```bash
|
||||
@po
|
||||
# Ask to shard docs/prd.md
|
||||
```
|
||||
|
||||
3. **Development cycle**:
|
||||
- **SM** creates stories with integration awareness
|
||||
- **Dev** implements with existing code respect
|
||||
- **QA** reviews for compatibility and improvements
|
||||
|
||||
## 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
|
||||
|
||||
Focus testing on:
|
||||
|
||||
- Integration points
|
||||
- Existing functionality (regression)
|
||||
- Performance impact
|
||||
- Data migrations
|
||||
|
||||
### 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. Architecture emphasizes compatibility
|
||||
4. Stories include integration tasks
|
||||
|
||||
### Scenario 2: Modernizing Legacy Code
|
||||
|
||||
1. Extensive documentation phase
|
||||
2. PRD includes migration strategy
|
||||
3. Architecture plans gradual transition
|
||||
4. Stories follow strangler fig pattern
|
||||
|
||||
### Scenario 3: Bug Fix in Complex System
|
||||
|
||||
1. Document relevant subsystems
|
||||
2. Use `brownfield-create-story` for focused fix
|
||||
3. Include regression test requirements
|
||||
4. QA validates no side effects
|
||||
|
||||
### Scenario 4: API Integration
|
||||
|
||||
1. Document existing API patterns
|
||||
2. PRD defines integration requirements
|
||||
3. Architecture ensures consistent patterns
|
||||
4. Stories include API documentation updates
|
||||
|
||||
## 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 `brownfield-create-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
|
||||
@analyst → *document-project
|
||||
|
||||
# Create enhancement PRD
|
||||
@pm → *create-doc brownfield-prd
|
||||
|
||||
# Create architecture with integration focus
|
||||
@architect → *create-doc brownfield-architecture
|
||||
|
||||
# Quick epic creation
|
||||
@pm → *brownfield-create-epic
|
||||
|
||||
# Single story creation
|
||||
@pm → *brownfield-create-story
|
||||
```
|
||||
|
||||
### 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
|
||||
└─ No → Is this more than a simple bug fix?
|
||||
├─ Yes → brownfield-create-epic
|
||||
└─ No → brownfield-create-story
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
Brownfield development with BMad-Method provides structure and safety when modifying existing systems. The key is providing comprehensive context through documentation, using specialized templates that consider integration requirements, and following workflows that respect existing constraints while enabling progress.
|
||||
|
||||
Remember: **Document First, Plan Carefully, Integrate Safely**
|
||||
Reference in New Issue
Block a user