BMAD-METHOD/bmad-agent/commands.md

# BMAD Method Command Reference Guide

## Core Orchestrator Commands

| Command | Description |
|---------|-------------|
| `*help` / `/help` | Display list of commands or help with workflows |
| `*agents` / `/agent-list` | List all available agent personas with their tasks |
| `*{agent}` / `/{agent}` | Switch to specified agent (e.g., *Dev, *Analyst) |
| `*exit` / `/exit` | Return to base BMAD Orchestrator from any agent |
| `*tasks` / `/tasks` | List tasks available to current agent |
| `*party` / `/party-mode` | Enter group chat mode with all available agents |
| `*yolo` / `/yolo` | Toggle between interactive and YOLO mode |
| `*core-dump` | Save current state and progress to debug log |
| `*mpcs` / `/mpcs` | List available Machine-Powered Capabilities |

## Web-Specific Commands

| Command | Description |
|---------|-------------|
| `/doc-out` | Output the full document being discussed without truncation |
| `/load-{agent}` | Immediately switch to the specified agent and greet the user |
| `/bmad {query}` | Direct a query to the BMAD Orchestrator while in another agent |
| `/{agent} {query}` | Direct a query to a specific agent while in another agent |

## Knowledge Management Commands

| Command | Description |
|---------|-------------|
| `*update-knowledge` / `/update-knowledge` | Update all agents with current project knowledge |
| `*generate-knowledge-map` / `/knowledge-map` | Create visual representation of project knowledge |
| `*knowledge-request {topic}` / `/knowledge-request {topic}` | Flag a knowledge gap for future resolution |
| `*validate-knowledge` / `/validate-knowledge` | Validate consistency and completeness of knowledge base |

## Project Workflow Commands

### Project Initialization

| Command | Description |
|---------|-------------|
| `*Analyst Create Project Brief` | Start a new project with initial research |
| `*PM Create PRD` | Create Product Requirements Document from brief |
| `*Architect Create Architecture` | Design system architecture based on PRD |
| `*Design Architect Create Frontend Architecture` | Design UI/UX and frontend architecture |

### Story Management

| Command | Description |
|---------|-------------|
| `*SM create` | Create next implementation story |
| `*SM pivot` | Run course correction for project direction |
| `*SM checklist` | Run story validation checklist |
| `*SM doc-shard` | Break down large documents into manageable pieces |

### Development

| Command | Description |
|---------|-------------|
| `*Dev run-tests` | Execute all tests for current implementation |
| `*Dev lint` | Find and fix code style issues |
| `*Dev explain {concept}` | Get explanation of technical concept |
| `*QA create-test-plan` | Create comprehensive test plan for story |
| `*QA run-tests` | Execute tests and report results |
| `*DevOps deploy` | Deploy to specified environment |
| `*DevOps infra-plan` | Plan infrastructure changes |
| `*Data Scientist analyze` | Analyze data patterns and create insights |

## Machine-Powered Capabilities

| Command | Description |
|---------|-------------|
| `*perplexity {query}` / `/perplexity {query}` | Web search with summarization |
| `*github {query}` / `/github {query}` | Search code repositories and documentation |
| `*firecrawl {query}` / `/firecrawl {query}` | Advanced data extraction and analysis |
| `*dalle {prompt}` / `/dalle {prompt}` | Generate images for UI mockups or concepts |

## Project Extension Workflows

### Adding a New Module

1. `*Architect module-design {module-name}` - Design new module architecture
2. `*PM update-prd {module-name}` - Update PRD with new module requirements
3. `*SM create` - Create implementation stories for the module
4. `*Dev` - Implement the module stories
5. `*QA create-test-plan` - Create test plan for the new module

## File Organization Guidelines

### Directory Structure Overview

The BMAD Method uses a **hybrid file organization system** that evolved from earlier versions:

| Directory | Purpose | Contents | Auto-Generated |
|-----------|---------|----------|----------------|
| `docs/` | **Human Deliverables** | Project Briefs, PRDs, Architecture docs, Stories, API docs | ❌ Manual |
| `.ai/` | **Agent Knowledge & Logs** | Project context, tech stack, data models, agent logs | ✅ Auto-created |
| `bmad-agent/` | **BMAD System Files** | Personas, tasks, templates, configuration | ❌ Manual |

### What Goes Where

**`docs/` Directory - Project Documentation:**
- Project Briefs (from Analyst)
- Product Requirements Documents (from PM)
- Architecture Documents (from Architect)
- UX/UI Specifications (from Design Architect)
- User Stories (in `docs/stories/`)
- API Reference documentation
- Sharded documents (broken down from large docs)

### Standard File Naming Convention

**All BMAD Method core documents MUST use lowercase filenames with hyphens:**

| Document Type | Standard Filename | Agent Responsible |
|---------------|-------------------|-------------------|
| Project Brief | `project-brief.md` | Analyst |
| Product Requirements | `prd.md` | PM |
| Architecture | `architecture.md` | Architect |
| Frontend Architecture | `frontend-architecture.md` | Design Architect |
| UX/UI Specification | `uxui-spec.md` | Design Architect |
| Technology Stack | `tech-stack.md` | Architect |
| Data Models | `data-models.md` | Architect/Data Scientist |
| API Reference | `api-reference.md` | Architect |
| Deployment Guide | `deployment-guide.md` | DevOps |
| Platform Architecture | `platform-architecture.md` | Platform Engineer |
| Platform Guidelines | `platform-guidelines.md` | Platform Engineer |
| Test Plan | `test-plan.md` | QA |
| User Stories | `{epic-num}.{story-num}.story.md` | SM |
| Epic Files | `epic-{id}.md` | SM (from sharding) |

### Date Generation Standards

**All agents MUST use actual current dates, not placeholders:**
- Use format: `YYYY-MM-DD` for dates (e.g., `2024-01-15`)
- Use format: `YYYY-MM-DD HH:MM` for timestamps (e.g., `2024-01-15 14:30`)
- **NEVER use placeholders** like `{DATE}`, `[DATE]`, or `TBD`
- **ALWAYS generate actual current date** when creating documents

**`.ai/` Directory - Agent Intelligence:**
- `project-context.md` - Project goals, terminology, domain knowledge
- `tech-stack.md` - Technologies, frameworks, patterns in use
- `data-models.md` - Data structures and analytics approaches
- `deployment-info.md` - Infrastructure and deployment details
- `knowledge-versions.md` - Version history of knowledge updates
- Agent working files (test-issues.md, deployment-history.md, etc.)

### System Evolution Note

**If your project only has `docs/`:** You're likely using an older configuration or haven't run the knowledge update task yet. The current system automatically creates and manages the `.ai/` directory when you run `*BMAD Update Agent Knowledge`.

### Updating Agent Knowledge

#### When to Run Knowledge Updates

**Required Updates (Major Phases):**
- After Project Brief completion
- After PRD creation or major updates
- After Architecture design or significant changes
- After adding new modules or major features
- After tech stack changes

**Frequency Guidelines:**
- **New Projects**: 3-4 times during initial setup
- **Active Development**: Every 2-4 weeks or when major changes occur
- **Mature Projects**: Monthly or when adding significant features

**DON'T Update After:**
- Individual story completions
- Small bug fixes
- Routine development tasks
- Individual test runs

#### Running the Update

1. Complete a project phase (Brief, PRD, Architecture)
2. `*BMAD Update Agent Knowledge` - Extract and distribute knowledge
3. **Automatic Results:**
   - Creates `.ai/` directory if it doesn't exist
   - Generates knowledge files from your `docs/` content
   - Updates agent customization strings
   - Uses semantic versioning (Major.Minor.Patch) to track changes
   - Agents automatically read from `.ai/` for project context

### Creating Custom Agents

1. Copy existing persona file from `bmad-agent/personas/`
2. Modify for specialized role
3. Add to `ide-bmad-orchestrator.cfg.md` with:

```
## Title: {Custom Agent Name}
- Name: {Nickname}
- Customize: "{Specialization details}"
- Description: "{Role description}"
- Persona: "{base-persona-file.md}"
- Tasks:
  - [Task Name](task-file.md)
```

## Common Scenarios

### 1. Complete Project Initialization Flow
**Purpose:** Start a new project from scratch through to development

| Step | Agent | Command | Description |
|------|-------|---------|-------------|
| 1 | Analyst | `*Analyst Create Project Brief` | Brainstorm and research project concept |
| 2 | PM | `*PM Create PRD` | Create Product Requirements Document with epics and stories |
| 3 | Architect | `*Architect Create Architecture` | Design system architecture based on PRD |
| 4 | Platform Engineer | `*Platform Engineer Create Platform Architecture` | Design platform infrastructure (for complex projects) |
| 5 | Design Architect | `*Design Architect Create Frontend Architecture` | Design UI/UX architecture (if applicable) |
| 6 | Design Architect | `*Design Architect Create UXUI Spec` | Create detailed UI/UX specifications |
| 7 | BMAD | `*BMAD Update Agent Knowledge` | Update all agents with project knowledge |
| 7 | PO | `*PO organize` | Organize and validate all documentation |
| 8 | SM | `*SM doc-shard` | Break down large documents into manageable pieces |
| 9 | SM | `*SM create` | Create first implementation story |
| 10 | Dev | `*Dev` | Implement the story |
| 11 | QA | `*QA create-test-plan` | Create test plan for the story |
| 12 | QA | `*QA run-tests` | Execute tests for the implementation |
| 13 | DevOps | `*DevOps deploy` | Deploy the implementation |

**Special Considerations:**
- Run `*BMAD Update Agent Knowledge` after each major phase
- Consider using `*perplexity` during research phases
- For UI-heavy projects, add `*dalle` for mockup generation after step 6
- **Include Platform Engineer (step 4)** for complex infrastructure, microservices, or enterprise projects
- **Skip Platform Engineer** for simple applications with basic infrastructure needs

### 2. Brownfield Project Takeover
**Purpose:** Integrate BMAD Method into an existing project

| Step | Agent | Command | Description |
|------|-------|---------|-------------|
| 1 | Analyst | `*Analyst Analyze Existing Project` | Document current state and challenges |
| 2 | PM | `*PM Reverse Engineer PRD` | Create PRD based on existing functionality |
| 3 | Architect | `*Architect Document Current Architecture` | Map out existing architecture |
| 4 | SM | `*SM doc-shard` | Break down documentation into manageable pieces |
| 5 | BMAD | `*BMAD Update Agent Knowledge` | Update all agents with project knowledge |
| 6 | PO | `*PO audit` | Identify documentation gaps |
| 7 | SM | `*SM create` | Create first enhancement story |
| 8 | Dev | `*Dev` | Implement the enhancement |

**Special Considerations:**
- Use `*github` to search for patterns in the existing codebase
- Consider `*SM pivot` if significant course correction is needed
- Create a project structure document if one doesn't exist

### 3. Adding New Module to Existing Project
**Purpose:** Extend a project beyond original PRD scope

| Step | Agent | Command | Description |
|------|-------|---------|-------------|
| 1 | Analyst | `*Analyst Research Module Requirements` | Research requirements for new module |
| 2 | PM | `*PM update-prd {module-name}` | Update PRD with new module requirements |
| 3 | Architect | `*Architect module-design {module-name}` | Design new module architecture |
| 4 | Design Architect | `*Design Architect Update Frontend Architecture` | Update UI/UX for new module (if applicable) |
| 5 | BMAD | `*BMAD Update Agent Knowledge` | Update all agents with new module knowledge |
| 6 | SM | `*SM doc-shard` | Break down module documentation |
| 7 | SM | `*SM create` | Create first module implementation story |
| 8 | Dev | `*Dev` | Implement the module story |
| 9 | QA | `*QA create-test-plan` | Create test plan for the module |
| 10 | Platform Engineer | `*Platform Engineer platform-change-management` | Plan platform infrastructure for complex modules |
| 11 | DevOps | `*DevOps infra-plan` | Plan basic infrastructure changes for new module |

**Special Considerations:**
- Ensure integration points with existing modules are clearly defined
- Consider impact on existing architecture and data models
- Update knowledge files to include new module terminology
- **Use Platform Engineer** for modules requiring service mesh, advanced monitoring, or complex infrastructure
- **Use DevOps Engineer** for modules with standard deployment and infrastructure needs

### 4. UI Redesign Workflow
**Purpose:** Implement frontend changes with minimal backend modifications

| Step | Agent | Command | Description |
|------|-------|---------|-------------|
| 1 | Design Architect | `*Design Architect Analyze Current UI` | Document current UI state and issues |
| 2 | PM | `*PM Create UI PRD` | Create UI-focused requirements document |
| 3 | Design Architect | `*Design Architect Create UXUI Spec` | Create detailed UI/UX specifications |
| 4 | Design Architect | `*Design Architect Create Frontend Architecture` | Update frontend architecture |
| 5 | Design Architect | `*Design Architect Create AI Frontend Prompt` | Create prompt for AI UI generation |
| 6 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with UI knowledge |
| 7 | SM | `*SM create` | Create UI implementation story |
| 8 | Dev | `*Dev` | Implement UI changes |
| 9 | QA | `*QA create-test-plan` | Create UI-focused test plan |

**Special Considerations:**
- Use `*dalle` for UI mockup generation
- Focus on component-based architecture for reusability
- Consider accessibility requirements in specifications

### 5. API Integration Project
**Purpose:** Integrate external APIs into an existing project

| Step | Agent | Command | Description |
|------|-------|---------|-------------|
| 1 | Analyst | `*Analyst Research API` | Research API capabilities and limitations |
| 2 | PM | `*PM Create API Integration PRD` | Document API integration requirements |
| 3 | Architect | `*Architect Design API Integration` | Design integration architecture |
| 4 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with API knowledge |
| 5 | SM | `*SM create` | Create API integration story |
| 6 | Dev | `*Dev` | Implement API integration |
| 7 | QA | `*QA create-test-plan` | Create API testing plan |
| 8 | DevOps | `*DevOps update-env` | Update environment with API credentials |

**Special Considerations:**
- Use `*perplexity` to research API best practices
- Create mock API responses for testing
- Document rate limits and fallback strategies

### 6. Database Migration Project
**Purpose:** Migrate from one database technology to another

| Step | Agent | Command | Description |
|------|-------|---------|-------------|
| 1 | Analyst | `*Analyst Research Database Options` | Research database technologies |
| 2 | Architect | `*Architect Design Database Migration` | Design migration architecture |
| 3 | Data Scientist | `*Data Scientist analyze` | Analyze data patterns and migration challenges |
| 4 | PM | `*PM Create Migration PRD` | Document migration requirements and phases |
| 5 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with database knowledge |
| 6 | SM | `*SM create` | Create database migration story |
| 7 | Dev | `*Dev` | Implement migration code |
| 8 | QA | `*QA create-test-plan` | Create data validation test plan |
| 9 | DevOps | `*DevOps infra-plan` | Plan infrastructure changes for new database |

**Special Considerations:**
- Create data validation strategies for before and after migration
- Plan for rollback scenarios
- Consider performance testing with representative data volumes

### 7. Performance Optimization Project
**Purpose:** Improve performance of an existing application

| Step | Agent | Command | Description |
|------|-------|---------|-------------|
| 1 | Analyst | `*Analyst Performance Analysis` | Identify performance bottlenecks |
| 2 | Architect | `*Architect Performance Optimization Plan` | Design optimization strategy |
| 3 | PM | `*PM Create Optimization PRD` | Document optimization requirements |
| 4 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with performance knowledge |
| 5 | SM | `*SM create` | Create optimization story |
| 6 | Dev | `*Dev` | Implement optimizations |
| 7 | QA | `*QA create-performance-test-plan` | Create performance test plan |
| 8 | Data Scientist | `*Data Scientist analyze-metrics` | Analyze performance metrics |

**Special Considerations:**
- Establish performance baselines before changes
- Use `*github` to research optimization patterns
- Consider both frontend and backend optimizations

### 8. Platform Infrastructure Setup
**Purpose:** Establish comprehensive platform infrastructure for complex projects

| Step | Agent | Command | Description |
|------|-------|---------|-------------|
| 1 | Analyst | `*Analyst Research Platform Requirements` | Research platform needs and constraints |
| 2 | Architect | `*Architect Create Architecture` | Design overall system architecture |
| 3 | Platform Engineer | `*Platform Engineer Create Platform Architecture` | Design platform infrastructure and services |
| 4 | Platform Engineer | `*Platform Engineer platform-change-management` | Implement platform infrastructure |
| 5 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with platform knowledge |
| 6 | DevOps | `*DevOps deploy` | Set up basic deployment pipelines |
| 7 | QA | `*QA create-test-plan` | Create platform testing and validation plan |

**Special Considerations:**
- **Use for**: Microservices, service mesh, complex monitoring, developer platforms
- **Focus on**: Developer experience, self-service capabilities, observability
- **Include**: Security scanning, compliance frameworks, cost optimization
- **Document**: Platform APIs, developer onboarding, troubleshooting guides

### Best Practices for Scenario Execution

**Documentation First:** Complete documentation phases before implementation

**Knowledge Updates:** Run `*BMAD Update Agent Knowledge` after each major phase

**Incremental Implementation:** Create and implement stories one at a time

**Regular Testing:** Integrate QA testing throughout the process

**Feedback Loops:** Use `*SM pivot` if significant course correction is needed

**MPC Integration:** Leverage appropriate MPCs for each scenario:
- Research: `*perplexity`
- Code patterns: `*github`
- Data analysis: `*firecrawl`
- UI visualization: `*dalle`

## Documentation Management

| Command | Description |
|---------|-------------|
| `*doc-out` / `/doc-out` | Output full document without truncation |
| `*PO organize` | Organize project documentation |
| `*PO audit` | Audit documentation for completeness |

## Best Practices

### Project Initialization Flow:
**Standard Projects**: Analyst → PM → Architect → Design Architect → PO → SM → Dev → QA → DevOps
**Complex Projects**: Analyst → PM → Architect → Platform Engineer → Design Architect → PO → SM → Dev → QA → DevOps

### Infrastructure Role Selection:
**Use DevOps Engineer for**:
- Basic deployment and CI/CD
- Standard monitoring and logging
- Simple infrastructure management
- Single-team projects

**Use Platform Engineer for**:
- Complex infrastructure (microservices, service mesh)
- Developer experience platforms
- Multi-team environments
- Advanced observability and monitoring
- Internal tooling and self-service platforms

### Knowledge Updates:
Run `*BMAD Update Agent Knowledge` after completing each major phase

### Story Development:
- Use SM to create stories
- Use Dev to implement
- Use QA to validate
- Use DevOps to deploy

### MPC Usage:
- Use `*perplexity` during research phases
- Use `*github` during implementation
- Use `*firecrawl` for data analysis
- Use `*dalle` for UI concept visualization

### Agent Switching:
- Use `*{agent}` for temporary switches
- Start new chat for major workflow transitions

---

This reference guide covers the core commands and workflows for effectively using the BMAD Method in your projects.