ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

feat(docs): add tutorial style guide and AI agent announcement bar 

- Add docs/_contributing/ with tutorial style guide
- Reformat quick-start-bmm.md and bmad-tutorial.md per style guide
- Remove horizontal separators, add strategic admonitions
- Add persistent announcement bar for AI agents directing to llms-full.txt
- Fix footer broken link to tutorials

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
forcetrainer 2026-01-03 19:33:57 -05:00 committed by Alex Verkhovsky
parent 5eaa555739
commit c2d8bfdc3e
6 changed files with 485 additions and 466 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/_contributing/index.md Normal file
View File

@ -0,0 +1,18 @@
# Contributing to BMAD Documentation
This directory contains internal guidelines for maintaining consistent, high-quality documentation across the BMAD Method project.
## Style Guides
- [Tutorial Style Guide](./tutorial-style.md) — Formatting standards for tutorials and getting-started guides
## Quick Principles
1. **Clarity over brevity** — Be concise, but never at the cost of understanding
2. **Consistent structure** — Follow established patterns so readers know what to expect
3. **Strategic visuals** — Use admonitions, tables, and diagrams purposefully
4. **Scannable content** — Headers, lists, and callouts help readers find what they need
## Directory Purpose
This `_contributing/` directory is prefixed with underscore to exclude it from the Docusaurus sidebar. These documents are for contributors and maintainers, not end users.

228
docs/_contributing/tutorial-style.md Normal file
View File

@ -0,0 +1,228 @@
# Tutorial Style Guide
Standards for writing tutorials and getting-started guides in BMAD documentation.
## Structure
Every tutorial should follow this flow:
1. **Title + Hook** — What you'll accomplish (1-2 sentences)
2. **Prerequisites** — Use `:::info[Prerequisites]` if needed
3. **What You'll Learn** — Brief bullet list of outcomes
4. **Main Steps** — Numbered phases, minimal nesting
5. **Summary + Next Steps** — Wrap up, link forward
## Visual Hierarchy
### Avoid
| Pattern | Problem |
|---------|---------|
| `---` horizontal rules | Fragment the reading flow |
| `####` deep headers | Create visual noise |
| **Important:** bold paragraphs | Blend into body text |
| Deeply nested lists | Hard to scan |
| Code blocks for non-code | Confusing semantics |
### Use Instead
| Pattern | When to Use |
|---------|-------------|
| White space + section headers | Natural content separation |
| Bold text within paragraphs | Inline emphasis |
| Admonitions | Callouts that need attention |
| Tables | Structured comparisons |
| Flat lists | Scannable options |
## Admonitions
Use Docusaurus admonitions strategically:
```md
:::tip[Title]
Shortcuts, best practices, "pro tips"
:::
:::info[Title]
Context, definitions, examples
:::
:::note
Supplementary information (can be collapsed)
:::
:::warning[Title]
Caveats, potential issues, things to watch out for
:::
:::danger[Title]
Critical warnings only — data loss, security issues
:::
```
### Admonition Guidelines
- **Always include a title** for tip, info, and warning
- **Keep content brief** — 1-3 sentences ideal
- **Don't overuse** — More than 3-4 per major section feels noisy
- **Don't nest** — Admonitions inside admonitions are hard to read
## Headers
### Budget
- **5-7 `##` sections** maximum per tutorial
- **2-3 `###` subsections** per `##` section maximum
- **Avoid `####` entirely** — use bold text or admonitions instead
### Naming
- Use action verbs for steps: "Install the CLI", "Configure Your Project"
- Use nouns for reference sections: "Common Questions", "Quick Reference"
- Keep headers short and scannable
## Code Blocks
### Do
```md
```bash
npx bmad-method@alpha install
```
```
### Don't
````md
```
You: Do something
Agent: [Response here]
```
````
For command/response examples, use an admonition instead:
```md
:::info[Example]
Run `workflow-status` and the agent will tell you the next recommended workflow.
:::
```
## Tables
Use tables for:
- Comparing options
- Mapping relationships (agent → document)
- Step sequences with multiple attributes
Keep tables simple:
- 2-4 columns maximum
- Short cell content
- Left-align text, right-align numbers
## Lists
### Flat Lists (Preferred)
```md
- **Option A** — Description of option A
- **Option B** — Description of option B
- **Option C** — Description of option C
```
### Numbered Steps
```md
1. Load the **PM agent** in a new chat
2. Run the PRD workflow
3. Output: `PRD.md`
```
### Avoid Deep Nesting
```md
<!-- Don't do this -->
1. First step
- Sub-step A
- Detail 1
- Detail 2
- Sub-step B
2. Second step
```
Instead, break into separate sections or use an admonition for context.
## Links
- Use descriptive link text: `[Tutorial Style Guide](./tutorial-style.md)`
- Avoid "click here" or bare URLs
- Prefer relative paths within docs
## Images
- Always include alt text
- Add a caption in italics below: `*Description of the image.*`
- Use SVG for diagrams when possible
- Store in `./images/` relative to the document
## FAQ Sections
Format as bold question followed by answer paragraph:
```md
**Do I always need architecture?**
Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.
**Can I change my plan later?**
Yes. The SM agent has a `correct-course` workflow for handling scope changes.
```
## Example: Before and After
### Before (Noisy)
```md
---
## Getting Started
### Step 1: Initialize
#### What happens during init?
**Important:** You need to describe your project.
1. Your project goals
- What you want to build
- Why you're building it
2. The complexity
- Small, medium, or large
---
```
### After (Clean)
```md
## Step 1: Initialize Your Workflow
Load the **Analyst agent** in your IDE, wait for the menu, then run `workflow-init`.
:::info[What Happens]
You'll describe your project goals and complexity. The workflow then recommends a planning track.
:::
```
## Checklist
Before submitting a tutorial:
- [ ] Follows the standard structure (hook → learn → steps → summary)
- [ ] No horizontal rules (`---`)
- [ ] No `####` headers
- [ ] Admonitions used for callouts (not bold paragraphs)
- [ ] Tables used for structured data
- [ ] Lists are flat (no deep nesting)
- [ ] 5-7 `##` sections maximum
- [ ] All links use descriptive text
- [ ] Images have alt text and captions

236
docs/tutorials/getting-started/bmad-tutorial.md
View File

@ -15,16 +15,12 @@ Learn how to build software with BMAD's AI-powered workflows. By the end of this
- How to initialize a project and choose a planning track - How to initialize a project and choose a planning track
- How to create your first requirements document - How to create your first requirements document
## Prerequisites :::info[Prerequisites]
Before starting, ensure you have:
- **Node.js 20+** — Required for the installer - **Node.js 20+** — Required for the installer
- **Git** — Recommended for version control - **Git** — Recommended for version control
- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar - **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
- **A project idea** — Even a simple one works for learning - **A project idea** — Even a simple one works for learning
:::
---
## Step 1: Install BMAD ## Step 1: Install BMAD
@ -34,30 +30,13 @@ Open a terminal in your project directory and run:
npx bmad-method install npx bmad-method install
``` ```
The interactive installer guides you through setup: The interactive installer guides you through setup.
### 1.1 Choose Installation Location **Choose Installation Location** — Select current directory (recommended), subdirectory, or custom path.
Select where to install BMAD files: **Select Your AI Tool** — Choose Claude Code, Cursor, Windsurf, or other. The installer configures BMAD for your selection.
- **Current directory** — Recommended for new projects **Choose Modules** — For this tutorial, select **BMM** (BMAD Method):
- **Subdirectory** — If you want BMAD isolated
- **Custom path** — For specific project structures
### 1.2 Select Your AI Tool
Choose the IDE you'll be using:
- Claude Code
- Cursor
- Windsurf
- Other
The installer configures BMAD to work with your selected tool.
### 1.3 Choose Modules
For this tutorial, select **BMM** (BMAD Method) — the core module for software development. You can add other modules later:
| Module | Purpose | | Module | Purpose |
| -------- | ----------------------------------------- | | -------- | ----------------------------------------- |
@ -66,13 +45,9 @@ For this tutorial, select **BMM** (BMAD Method) — the core module for software
| **CIS** | Creative intelligence and facilitation | | **CIS** | Creative intelligence and facilitation |
| **BMB** | Building custom agents and workflows | | **BMB** | Building custom agents and workflows |
### 1.4 Accept Default Configuration **Accept Default Configuration** — For your first project, accept the recommended defaults. Customize later in `_bmad/[module]/config.yaml`.
For your first project, accept the recommended defaults. You can customize settings later in `_bmad/[module]/config.yaml`. **Verify Installation** — Check your project structure:
### 1.5 Verify Installation
After installation completes, verify by checking your project structure:
``` ```
your-project/ your-project/
@ -86,38 +61,37 @@ your-project/
└── .claude/ # IDE configuration (if using Claude Code) └── .claude/ # IDE configuration (if using Claude Code)
``` ```
> **Having trouble?** See [Install BMAD](../../how-to/installation/install-bmad.md) for troubleshooting common issues. :::tip[Troubleshooting]
Having issues? See [Install BMAD](../../how-to/installation/install-bmad.md) for common solutions.
--- :::
## Step 2: Understand How BMAD Works ## Step 2: Understand How BMAD Works
Before diving in, let's understand BMAD's core concepts. Before diving in, learn BMAD's core concepts.
### Phases ### Phases
BMAD organizes work into four phases: BMAD organizes work into four phases:
``` | Phase | Name | What Happens |
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ | ----- | -------------- | -------------------------------------------------- |
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │ | 1 | Analysis | Brainstorm, research *(optional)* |
│ Analysis │ → │ Planning │ → │ Solutioning │ → │Implementation│ | 2 | Planning | Requirements — PRD or tech-spec *(required)* |
│ (Optional) │ │ (Required) │ │ (Varies) │ │ (Required) │ | 3 | Solutioning | Architecture, design decisions *(varies by track)* |
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ | 4 | Implementation | Build code story by story *(required)* |
Brainstorm Requirements Architecture Build code
Research PRD or tech-spec Design decisions Story by story
```
### Agents ### Agents
Agents are specialized AI personas, each expert in their domain: Agents are specialized AI personas, each expert in their domain:
- **Analyst** — Initializes projects, tracks progress, conducts research | Agent | Role |
- **PM** — Creates requirements (PRD or tech-spec) | --------------- | -------------------------------------------------------- |
- **UX-Designer** — Designs user interfaces and experiences | **Analyst** | Initializes projects, tracks progress, conducts research |
- **Architect** — Makes technical decisions, designs system architecture | **PM** | Creates requirements (PRD or tech-spec) |
- **SM (Scrum Master)** — Manages sprints, creates stories | **UX-Designer** | Designs user interfaces and experiences |
- **DEV** — Implements code, reviews work | **Architect** | Makes technical decisions, designs system architecture |
| **SM** | Manages sprints, creates stories |
| **DEV** | Implements code, reviews work |
### Workflows ### Workflows
@ -133,74 +107,38 @@ Based on your project's complexity, BMAD offers three tracks:
| **BMAD Method** | Products, platforms, complex features | PRD + Architecture + UX | | **BMAD Method** | Products, platforms, complex features | PRD + Architecture + UX |
| **Enterprise** | Compliance, multi-tenant, enterprise needs | PRD + Architecture + Security + DevOps | | **Enterprise** | Compliance, multi-tenant, enterprise needs | PRD + Architecture + Security + DevOps |
---
## Step 3: Initialize Your Project ## Step 3: Initialize Your Project
Now let's set up your project with BMAD. Load the **Analyst agent** in your IDE:
### 3.1 Load the Analyst Agent
In your IDE, load the Analyst agent. The method depends on your IDE:
- **Claude Code**: Type `/analyst` or load the agent file directly - **Claude Code**: Type `/analyst` or load the agent file directly
- **Cursor/Windsurf**: Open the agent file from `_bmad/bmm/agents/` - **Cursor/Windsurf**: Open the agent file from `_bmad/bmm/agents/`
Wait for the agent's menu to appear. You'll see a list of available workflows. Wait for the agent's menu to appear, then run the initialization workflow:
### 3.2 Run the Initialization Workflow
Tell the agent to initialize your project:
``` ```
Run workflow-init Run workflow-init
``` ```
Or use the shorthand: Or use the shorthand: `*workflow-init`
```
*workflow-init
```
### 3.3 Describe Your Project
The workflow asks you to describe: The workflow asks you to describe:
- **Your project and goals** — What are you building? What problem does it solve? - **Your project and goals** — What are you building? What problem does it solve?
- **Existing codebase** — Is this a new project (greenfield) or existing code (brownfield)? - **Existing codebase** — Is this new (greenfield) or existing code (brownfield)?
- **Size and complexity** — Roughly how big is this? (You can adjust later) - **Size and complexity** — Roughly how big is this? (adjustable later)
### 3.4 Choose Your Track Based on your description, the workflow suggests a planning track. For this tutorial, choose **BMAD Method**.
Based on your description, the workflow suggests a planning track. You can accept the suggestion or choose a different one: Once you confirm, the workflow creates `bmm-workflow-status.yaml` in your project's docs folder to track your progress.
- Choose **Quick Flow** if you have a clear, bounded task :::warning[Fresh Chats]
- Choose **BMAD Method** for most new products or features Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
- Choose **Enterprise** if you have compliance or security requirements :::
For this tutorial, we'll assume you chose **BMAD Method**.
### 3.5 Confirm and Create
Once you confirm, the workflow creates `bmm-workflow-status.yaml` in your project's docs folder. This file tracks your progress through all phases.
> **Important**: Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
---
## Step 4: Create Your Requirements Document ## Step 4: Create Your Requirements Document
With your project initialized, it's time to create your first planning document — the PRD (Product Requirements Document). With your project initialized, create your first planning document — the PRD (Product Requirements Document).
### 4.1 Start a Fresh Chat **Start a fresh chat** and load the **PM agent**.
Close your current chat and start a new one. This ensures the agent has full context capacity for the workflow.
### 4.2 Load the PM Agent
Load the PM (Product Manager) agent in your IDE.
### 4.3 Run the PRD Workflow
Tell the PM agent: Tell the PM agent:
@ -208,13 +146,7 @@ Tell the PM agent:
Run prd Run prd
``` ```
Or use shortcuts: Or use shortcuts: `*prd`, select "create-prd" from the menu, or say "Let's create a new PRD".
- `*prd`
- Select "create-prd" from the menu
- Say "Let's create a new PRD"
### 4.4 Work Through the PRD
The PM agent guides you through creating your PRD interactively: The PM agent guides you through creating your PRD interactively:
@ -226,48 +158,25 @@ The PM agent guides you through creating your PRD interactively:
Answer the agent's questions thoughtfully. The PRD becomes the foundation for everything that follows. Answer the agent's questions thoughtfully. The PRD becomes the foundation for everything that follows.
### 4.5 Review Your PRD When complete, you'll have a `PRD.md` file in your `_bmad-output/` folder.
When complete, you'll have a `PRD.md` file in your `_bmad-output/` folder. Review it to ensure it captures your vision.
---
## Step 5: Check Your Progress ## Step 5: Check Your Progress
At any point, you can check what to do next. At any point, check what to do next by loading any agent and running:
### 5.1 Load Any Agent
Start a fresh chat and load any BMAD agent.
### 5.2 Ask for Status
Tell the agent:
``` ```
workflow-status workflow-status
``` ```
The agent reads your `bmm-workflow-status.yaml` and tells you: The agent reads your `bmm-workflow-status.yaml` and tells you which phase you're in, what's complete, and what the next step is.
- Which phase you're in :::info[Example Response]
- What workflows are complete Phase 2 (Planning) complete: PRD created
- What the next recommended or required step is
Example response:
```
Phase 2 (Planning) complete:
✓ PRD created
Next recommended steps: Next recommended steps:
- UX Design (optional, if your project has a UI) - UX Design (optional, if your project has a UI)
- Architecture (required for BMAD Method track) - Architecture (required for BMAD Method track) — Agent: architect, Command: `create-architecture`
Agent: architect :::
Command: create-architecture
```
---
## What You've Accomplished ## What You've Accomplished
@ -281,64 +190,53 @@ Your project now has:
``` ```
your-project/ your-project/
├── _bmad/ # BMAD configuration ├── _bmad/ # BMAD configuration
├── _bmad-output/ ├── _bmad-output/
│ ├── PRD.md # Your requirements document │ ├── PRD.md # Your requirements document
│ └── bmm-workflow-status.yaml # Progress tracking │ └── bmm-workflow-status.yaml # Progress tracking
└── ... └── ...
``` ```
---
## Next Steps ## Next Steps
Continue building your project by designing your system's technical foundation (required for BMAD Method) and then starting implementation story by story. Continue building your project:
1. Design your system's technical foundation with the **Architect agent**
2. Start implementation story by story with **SM** and **DEV** agents
Explore related topics: Explore related topics:
- [What Are Agents?](../../explanation/core-concepts/what-are-agents.md) — Deep dive into how agents work
- **[What Are Agents?](../../explanation/core-concepts/what-are-agents.md)** — Deep dive into how agents work - [What Are Workflows?](../../explanation/core-concepts/what-are-workflows.md) — Understanding BMAD's workflow system
- **[What Are Workflows?](../../explanation/core-concepts/what-are-workflows.md)** — Understanding BMAD's workflow system - [Workflow Reference](../../reference/workflows/index.md) — Complete list of available workflows
- **[Workflow Reference](../../reference/workflows/index.md)** — Complete list of available workflows
---
## Quick Reference ## Quick Reference
Commands you learned in this tutorial:
| Command | Agent | Purpose | | Command | Agent | Purpose |
| ----------------- | ------- | -------------------------------------- | | ----------------- | ------- | -------------------------------------- |
| `*workflow-init` | Analyst | Initialize a new project | | `*workflow-init` | Analyst | Initialize a new project |
| `*prd` | PM | Create a Product Requirements Document | | `*prd` | PM | Create a Product Requirements Document |
| `workflow-status` | Any | Check progress and next steps | | `workflow-status` | Any | Check progress and next steps |
> **Tip**: Agents are flexible with commands. Menu numbers, shortcuts (`*prd`), or natural language ("Let's create a PRD") all work. :::tip[Flexible Commands]
Agents accept menu numbers, shortcuts (`*prd`), or natural language ("Let's create a PRD").
--- :::
## Common Questions ## Common Questions
**Q: Do I need to create a PRD for every project?** **Do I need to create a PRD for every project?**
Only for BMAD Method and Enterprise tracks. Quick Flow projects use a simpler tech-spec instead. Only for BMAD Method and Enterprise tracks. Quick Flow projects use a simpler tech-spec instead.
**Q: Can I skip Phase 1 (Analysis)?** **Can I skip Phase 1 (Analysis)?**
Yes, Phase 1 is optional. If you already know what you're building, start with Phase 2 (Planning). Yes, Phase 1 is optional. If you already know what you're building, start with Phase 2 (Planning).
**Q: What if I want to brainstorm first?** **What if I want to brainstorm first?**
Load the Analyst agent and run `*brainstorm-project` before `workflow-init`. Load the Analyst agent and run `*brainstorm-project` before `workflow-init`.
**Q: Why start fresh chats for each workflow?** **Why start fresh chats for each workflow?**
Workflows are context-intensive. Reusing chats can cause the AI to hallucinate or lose track of details. Fresh chats ensure maximum context capacity. Workflows are context-intensive. Reusing chats can cause the AI to hallucinate or lose track of details. Fresh chats ensure maximum context capacity.
---
## Getting Help ## Getting Help
- **During workflows**: Agents guide you with questions and explanations - **During workflows** — Agents guide you with questions and explanations
- **Check status**: Run `workflow-status` with any agent - **Check status** — Run `workflow-status` with any agent
- **Community**: [Discord](https://discord.gg/gk8jAdXWmj) — #general-dev, #bugs-issues - **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#general-dev, #bugs-issues)
- **Video tutorials**: [BMad Code YouTube](https://www.youtube.com/@BMadCode) - **Video tutorials** — [BMad Code YouTube](https://www.youtube.com/@BMadCode)

436
docs/tutorials/getting-started/quick-start-bmm.md
View File

@ -5,386 +5,230 @@ sidebar_position: 2
# Getting Started with BMad v6 Alpha # Getting Started with BMad v6 Alpha
Build software from scratch using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
:::warning[Alpha Software] :::warning[Alpha Software]
BMad v6 is currently in **alpha**. Expect breaking changes, incomplete features, and evolving documentation. If you prefer a stable experience, use the [BMad v4 tutorial](./bmad-tutorial.md) instead. BMad v6 is currently in **alpha**. Expect breaking changes, incomplete features, and evolving documentation. For a stable experience, use the [BMad v4 tutorial](./bmad-tutorial.md) instead.
::: :::
Get started with BMad Method v6 for your new greenfield project. This guide walks you through building software from scratch using AI-powered workflows. ## What You'll Learn
## TL;DR - The Quick Path - Install and initialize BMad Method for a new project
- Choose the right planning track for your project size
- Progress through phases from requirements to working code
- Use agents and workflows effectively
1. **Install**: `npx bmad-method@alpha install` :::tip[Quick Path]
2. **Initialize**: Load Analyst agent → Run "workflow-init" **Install** → `npx bmad-method@alpha install`
3. **Plan**: Load PM agent to create a PRD **Initialize** → Load Analyst agent, run `workflow-init`
4. **Plan UX**: Load UX Expert to create a UX-Design if your application will have a UX/UI element **Plan** → PM creates PRD, Architect creates architecture
5. **Architect**: Load Architect agent → Run "create-architecture" **Build** → SM manages sprints, DEV implements stories
6. **Epic Plan**: The PM steps back in to help run the create-epics-and-stories **Always use fresh chats** for each workflow to avoid context issues.
7. **Build**: Load SM agent → Run workflows for each story → Load DEV agent → Implement :::
8. **Always use fresh chats** for each workflow to avoid context issues
## What is BMad Method? ## Understanding BMad Method
BMad Method (BMM) helps you build software through guided workflows with specialized AI agents. The process follows four phases: BMad Method helps you build software through guided workflows with specialized AI agents. The process follows four phases:
1. **Phase 1: Analysis** (Optional) - Brainstorming, Research, Product Brief | Phase | Name | What Happens |
2. **Phase 2: Planning** (Required) - Create your requirements (tech-spec or PRD) |-------|------|--------------|
3. **Phase 3: Solutioning** (Track-dependent) - Design the architecture for BMad Method and Enterprise tracks | 1 | Analysis | Brainstorming, research, product brief *(optional)* |
4. **Phase 4: Implementation** (Required) - Build your software Epic by Epic, Story by Story | 2 | Planning | Create requirements (PRD or tech-spec) |
| 3 | Solutioning | Design architecture *(BMad Method/Enterprise only)* |
### Complete Workflow Visualization | 4 | Implementation | Build epic by epic, story by story |
![BMad Method Workflow - Standard Greenfield](./images/workflow-method-greenfield.svg) ![BMad Method Workflow - Standard Greenfield](./images/workflow-method-greenfield.svg)
_Complete visual flowchart showing all phases, workflows, agents (color-coded), and decision points for the BMad Method standard greenfield track. Each box is color-coded by the agent responsible for that workflow._ *Complete visual flowchart showing all phases, workflows, and agents for the standard greenfield track.*
## Installation ## Installation
```bash ```bash
# Install v6 Alpha to your project
npx bmad-method@alpha install npx bmad-method@alpha install
``` ```
The interactive installer will guide you through setup and create a `_bmad/` folder with all agents and workflows. The interactive installer guides you through setup and creates a `_bmad/` folder with all agents and workflows.
--- ## Step 1: Initialize Your Workflow
## Getting Started Load the **Analyst agent** in your IDE, wait for the menu, then tell it to run `workflow-init`.
### Step 1: Initialize Your Workflow :::info[How to Load Agents]
Type `/<agent-name>` in your IDE and use autocomplete. Not sure what's available? Start with `/bmad` to see all agents and workflows.
:::
1. **Load the Analyst agent** in your IDE - Generally this is done by typing `/<workflow or agent name - allow autocomplete to find the right command>` - if you are unsure, you can just start with /bmad and see all that is available, sorted by agents and workflows. During initialization, you'll describe your project, whether it's new or existing, and the general complexity. The workflow then recommends a planning track:
2. **Wait for the agent's menu** to appear
3. **Tell the agent**: "Run workflow-init" or type "\*workflow-init" or select the menu item number
#### What happens during workflow-init? **Quick Flow** — Fast implementation with tech-spec only. Best for bug fixes, simple features, and clear scope (typically 1-15 stories).
Workflows are interactive processes in V6 that replaced tasks and templates from prior versions. There are many types of workflows, and you can even create your own with the BMad Builder module. For the BMad Method, you'll be interacting with expert-designed workflows crafted to work with you to get the best out of both you and the LLM. **BMad Method** — Full planning with PRD, architecture, and optional UX design. Best for products, platforms, and complex features (typically 10-50+ stories).
During workflow-init, you'll describe: **Enterprise Method** — Extended planning adding security, DevOps, and test planning. Best for compliance requirements and multi-tenant systems (typically 30+ stories).
- Your project and its goals :::note
- Whether there's an existing codebase or this is a new project Story counts are guidance, not definitions. Choose your track based on planning needs, not story math.
- The general size and complexity (you can adjust this later) :::
#### Planning Tracks Once you confirm, the workflow creates `bmm-workflow-status.yaml` to track your progress through all phases.
Based on your description, the workflow will suggest a track and let you choose from: ## Step 2: Work Through Planning Phases
**Three Planning Tracks:** After initialization, work through phases 1-3. **Use fresh chats for each workflow** to avoid context limitations.
- **Quick Flow** - Fast implementation (tech-spec only) - bug fixes, simple features, clear scope (typically 1-15 stories) :::tip[Check Your Status]
- **BMad Method** - Full planning (PRD + Architecture + UX) - products, platforms, complex features (typically 10-50+ stories) Unsure what's next? Load any agent and ask for `workflow-status`. It tells you the next recommended or required workflow.
- **Enterprise Method** - Extended planning (BMad Method + Security/DevOps/Test) - enterprise requirements, compliance, multi-tenant (typically 30+ stories) :::
**Note**: Story counts are guidance, not definitions. Tracks are chosen based on planning needs, not story math. ### Phase 1: Analysis (Optional)
#### What gets created? All workflows in this phase are optional:
- **brainstorm-project** — Guided ideation
- **research** — Market and technical research
- **product-brief** — Recommended foundation document
Once you confirm your track, the `bmm-workflow-status.yaml` file will be created in your project's docs folder (assuming default install location). This file tracks your progress through all phases. ### Phase 2: Planning (Required)
**Important notes:**
- Every track has different paths through the phases
- Story counts can still change based on overall complexity as you work
- For this guide, we'll assume a BMad Method track project
- This workflow will guide you through Phase 1 (optional), Phase 2 (required), and Phase 3 (required for BMad Method and Enterprise tracks)
### Step 2: Work Through Phases 1-3
After workflow-init completes, you'll work through the planning phases. **Important: Use fresh chats for each workflow to avoid context limitations.**
#### Checking Your Status
If you're unsure what to do next:
1. Load any agent in a new chat
2. Ask for "workflow-status"
3. The agent will tell you the next recommended or required workflow
**Example response:**
```
Phase 1 (Analysis) is entirely optional. All workflows are optional or recommended:
- brainstorm-project - optional
- research - optional
- product-brief - RECOMMENDED (but not required)
The next TRULY REQUIRED step is:
- PRD (Product Requirements Document) in Phase 2 - Planning
- Agent: pm
- Command: prd
```
#### How to Run Workflows in Phases 1-3
When an agent tells you to run a workflow (like `prd`):
1. **Start a new chat** with the specified agent
2. **Wait for the menu** to appear
3. **Tell the agent** to run it using any of these formats:
- Type the shorthand: `*prd`
- Say it naturally: "Let's create a new PRD"
- Select the menu number for "create-prd"
The agents in V6 are very good with fuzzy menu matching!
#### Quick Reference: Agent → Document Mapping
For v4 users or those who prefer to skip workflow-status guidance:
- **Analyst** → Brainstorming, Product Brief
- **PM** → PRD (BMad Method/Enterprise tracks) OR tech-spec (Quick Flow track)
- **UX-Designer** → UX Design Document (if UI part of the project)
- **Architect** → Architecture (BMad Method/Enterprise tracks)
#### Phase 2: Planning - Creating the PRD
**For BMad Method and Enterprise tracks:** **For BMad Method and Enterprise tracks:**
1. Load the **PM agent** in a new chat 1. Load the **PM agent** in a new chat
2. Tell it to run the PRD workflow 2. Run the PRD workflow
3. Once complete, you'll have: 3. Output: `PRD.md`
- **PRD.md** - Your Product Requirements Document
**For Quick Flow track:** **For Quick Flow track:**
- Use `tech-spec` instead of PRD, then skip to implementation
- Use **tech-spec** instead of PRD (no architecture needed) :::info[UX Design (Optional)]
If your project has a user interface, load the **UX-Designer agent** and run the UX design workflow after creating your PRD.
:::
#### Phase 2 (Optional): UX Design ### Phase 3: Solutioning (BMad Method/Enterprise)
If your project has a user interface:
1. Load the **UX-Designer agent** in a new chat
2. Tell it to run the UX design workflow
3. After completion, you'll have your UX specification document
#### Phase 3: Architecture
**For BMad Method and Enterprise tracks:**
**Create Architecture**
1. Load the **Architect agent** in a new chat 1. Load the **Architect agent** in a new chat
2. Tell it to run the create-architecture workflow 2. Run `create-architecture`
3. After completion, you'll have your architecture document with technical decisions 3. Output: Architecture document with technical decisions
#### Phase 3: Create Epics and Stories (REQUIRED after Architecture) **Create Epics and Stories**
**V6 Improvement:** Epics and stories are now created AFTER architecture for better quality! :::tip[V6 Improvement]
Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
:::
1. Load the **PM agent** in a new chat 1. Load the **PM agent** in a new chat
2. Tell it to run "create-epics-and-stories" 2. Run `create-epics-and-stories`
3. This breaks down your PRD's FRs/NFRs into implementable epics and stories 3. The workflow uses both PRD and Architecture to create technically-informed stories
4. The workflow uses both PRD and Architecture to create technically-informed stories
**Why after architecture?** Architecture decisions (database, API patterns, tech stack) directly affect how stories should be broken down and sequenced.
#### Phase 3: Implementation Readiness Check (Highly Recommended)
Once epics and stories are created:
**Implementation Readiness Check** *(Highly Recommended)*
1. Load the **Architect agent** in a new chat 1. Load the **Architect agent** in a new chat
2. Tell it to run "implementation-readiness" 2. Run `implementation-readiness`
3. This validates cohesion across all your planning documents (PRD, UX, Architecture, Epics) 3. Validates cohesion across all planning documents
4. This was called the "PO Master Checklist" in v4
**Why run this?** It ensures all your planning assets align properly before you start building. ## Step 3: Build Your Project (Phase 4)
#### Optional: TEA Engagement Once planning is complete, move to implementation. **Each workflow should run in a fresh chat.**
Testing is not mandated by BMad. Decide how you want to engage TEA: ### Initialize Sprint Planning
- **No TEA** - Use your existing team testing approach Load the **SM agent** and run `sprint-planning`. This creates `sprint-status.yaml` to track all epics and stories.
- **TEA-only (Standalone)** - Use TEA workflows with your own requirements and environment
- **TEA-integrated** - Use TEA as part of the BMad Method or Enterprise flow
See the [Test Architect Guide](../../explanation/features/tea-overview.md) for the five TEA engagement models and recommended sequences. ### The Build Cycle
#### Context Management Tips For each story, repeat this cycle with fresh chats:
- **Use 200k+ context models** for best results (Claude Sonnet 4.5, GPT-4, etc.) | Step | Agent | Workflow | Purpose |
- **Fresh chat for each workflow** - Brainstorming, Briefs, Research, and PRD generation are all context-intensive |------|-------|----------|---------|
- **No document sharding needed** - Unlike v4, you don't need to split documents | 1 | SM | `create-story` | Create story file from epic |
- **Web Bundles coming soon** - Will help save LLM tokens for users with limited plans | 2 | DEV | `dev-story` | Implement the story |
| 3 | TEA | `automate` | Generate guardrail tests *(optional)* |
| 4 | DEV | `code-review` | Quality validation *(recommended)* |
### Step 3: Start Building (Phase 4 - Implementation) After completing all stories in an epic, load the **SM agent** and run `retrospective`.
Once planning and architecture are complete, you'll move to Phase 4. **Important: Each workflow below should be run in a fresh chat to avoid context limitations and hallucinations.** :::warning[Why Fresh Chats?]
Context-intensive workflows can cause hallucinations if you keep issuing commands in the same chat. Starting fresh ensures maximum context capacity.
#### 3.1 Initialize Sprint Planning :::
1. **Start a new chat** with the **SM (Scrum Master) agent**
2. Wait for the menu to appear
3. Tell the agent: "Run sprint-planning"
4. This creates your `sprint-status.yaml` file that tracks all epics and stories
#### 3.2 Create Your First Story
1. **Start a new chat** with the **SM agent**
2. Wait for the menu
3. Tell the agent: "Run create-story"
4. This creates the story file from the epic
#### 3.3 Implement the Story
1. **Start a new chat** with the **DEV agent**
2. Wait for the menu
3. Tell the agent: "Run dev-story"
4. The DEV agent will implement the story and update the sprint status
#### 3.4 Generate Guardrail Tests (Optional)
1. **Start a new chat** with the **TEA agent**
2. Wait for the menu
3. Tell the agent: "Run automate"
4. The TEA agent generates or expands tests to act as guardrails
#### 3.5 Review the Code (Optional but Recommended)
1. **Start a new chat** with the **DEV agent**
2. Wait for the menu
3. Tell the agent: "Run code-review"
4. The DEV agent performs quality validation (this was called QA in v4)
### Step 4: Keep Going
For each subsequent story, repeat the cycle using **fresh chats** for each workflow:
1. **New chat** → SM agent → "Run create-story"
2. **New chat** → DEV agent → "Run dev-story"
3. **New chat** → TEA agent → "Run automate" (optional)
4. **New chat** → DEV agent → "Run code-review" (optional but recommended)
After completing all stories in an epic:
1. **Start a new chat** with the **SM agent**
2. Tell the agent: "Run retrospective"
**Why fresh chats?** Context-intensive workflows can cause hallucinations if you keep issuing commands in the same chat. Starting fresh ensures the agent has maximum context capacity for each workflow.
---
## Understanding the Agents ## Understanding the Agents
Each agent is a specialized AI persona: | Agent | Role |
|-------|------|
| **Analyst** | Initializes workflows and tracks progress |
| **PM** | Creates requirements and specifications |
| **UX-Designer** | Designs interfaces and user experience |
| **Architect** | Designs system architecture |
| **SM** | Manages sprints and creates stories |
| **DEV** | Implements code and reviews work |
- **Analyst** - Initializes workflows and tracks progress :::info[Working with Agents]
- **PM** - Creates requirements and specifications 1. Load an agent in your IDE
- **UX-Designer** - If your project has a front end - this designer will help produce artifacts, come up with mock updates, and design a great look and feel with you giving it guidance. 2. Wait for the menu to appear
- **Architect** - Designs system architecture 3. Tell it what to run (natural language, menu number, or `*shortcut`)
- **SM (Scrum Master)** - Manages sprints and creates stories 4. Follow the prompts
- **DEV** - Implements code and reviews work :::
## How Workflows Work
1. **Load an agent** - Open the agent file in your IDE to activate it
2. **Wait for the menu** - The agent will present its available workflows
3. **Tell the agent what to run** - Say "Run [workflow-name]"
4. **Follow the prompts** - The agent guides you through each step
The agent creates documents, asks questions, and helps you make decisions throughout the process.
## Project Tracking Files ## Project Tracking Files
BMad creates two files to track your progress: BMad creates two files to track your progress:
**1. bmm-workflow-status.yaml** **bmm-workflow-status.yaml** — Shows which phase you're in and what's next. Created by `workflow-init`, updated automatically as you progress.
- Shows which phase you're in and what's next **sprint-status.yaml** — Tracks all epics and stories during implementation. Created by `sprint-planning`, critical for SM and DEV agents to know what to work on.
- Created by workflow-init
- Updated automatically as you progress through phases
**2. sprint-status.yaml** (Phase 4 only) You don't need to edit these manually—agents update them as you work.
- Tracks all your epics and stories during implementation ## Quick Reference
- Critical for SM and DEV agents to know what to work on next
- Created by sprint-planning workflow
- Updated automatically as stories progress
**You don't need to edit these manually** - agents update them as you work. ### Agent → Document Mapping
--- | Agent | Creates |
|-------|---------|
| Analyst | Brainstorming notes, Product Brief |
| PM | PRD (Method/Enterprise) or tech-spec (Quick Flow), Epics & Stories |
| UX-Designer | UX Design Document |
| Architect | Architecture Document |
## The Complete Flow Visualized ### Workflow Commands
```mermaid Run these by telling the agent naturally, using menu numbers, or typing `*shortcut`:
flowchart LR
subgraph P1["Phase 1 (Optional)<br/>Analysis"]
direction TB
A1[Brainstorm]
A2[Research]
A3[Brief]
A4[Analyst]
A1 ~~~ A2 ~~~ A3 ~~~ A4
end
subgraph P2["Phase 2 (Required)<br/>Planning"] - `workflow-init` — Start a new project
direction TB - `workflow-status` — Check what's next
B1[Quick Flow:<br/>tech-spec] - `prd` — Create Product Requirements Document
B2[Method/Enterprise:<br/>PRD] - `create-architecture` — Create architecture
B3[UX opt] - `create-epics-and-stories` — Break down PRD into epics
B4[PM, UX] - `sprint-planning` — Initialize sprint tracking
B1 ~~~ B2 ~~~ B3 ~~~ B4 - `create-story` — Create a story file
end - `dev-story` — Implement a story
- `code-review` — Review implemented code
subgraph P3["Phase 3 (Track-dependent)<br/>Solutioning"]
direction TB
C1[Method/Enterprise:<br/>architecture]
C2[gate-check]
C3[Architect]
C1 ~~~ C2 ~~~ C3
end
subgraph P4["Phase 4 (Required)<br/>Implementation"]
direction TB
D1[Per Epic:<br/>epic context]
D2[Per Story:<br/>create-story]
D3[dev-story]
D4[code-review]
D5[SM, DEV]
D1 ~~~ D2 ~~~ D3 ~~~ D4 ~~~ D5
end
P1 --> P2
P2 --> P3
P3 --> P4
style P1 fill:#bbf,stroke:#333,stroke-width:2px,color:#000
style P2 fill:#bfb,stroke:#333,stroke-width:2px,color:#000
style P3 fill:#ffb,stroke:#333,stroke-width:2px,color:#000
style P4 fill:#fbf,stroke:#333,stroke-width:2px,color:#000
```
## Common Questions ## Common Questions
**Q: Do I always need architecture?** **Do I always need architecture?**
A: Only for BMad Method and Enterprise tracks. Quick Flow projects skip straight from tech-spec to implementation. Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
**Q: Can I change my plan later?** **Can I change my plan later?**
A: Yes! The SM agent has a "correct-course" workflow for handling scope changes. Yes. The SM agent has a `correct-course` workflow for handling scope changes.
**Q: What if I want to brainstorm first?** **What if I want to brainstorm first?**
A: Load the Analyst agent and tell it to "Run brainstorm-project" before running workflow-init. Load the Analyst agent and run `brainstorm-project` before `workflow-init`.
**Q: Why do I need fresh chats for each workflow?** **Can I skip workflow-init and workflow-status?**
A: Context-intensive workflows can cause hallucinations if run in sequence. Fresh chats ensure maximum context capacity. Yes, once you learn the flow. Use the Quick Reference to go directly to needed workflows.
**Q: Can I skip workflow-init and workflow-status?**
A: Yes, once you learn the flow. Use the Quick Reference in Step 2 to go directly to the workflows you need.
## Getting Help ## Getting Help
- **During workflows**: Agents guide you with questions and explanations - **During workflows** — Agents guide you with questions and explanations
- **Community**: [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues - **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#general-dev, #bugs-issues)
- **Complete guide**: [BMM Workflow Documentation](../../reference/workflows/index.md) - **Documentation** — [BMM Workflow Reference](../../reference/workflows/index.md)
- **YouTube tutorials**: [BMad Code Channel](https://www.youtube.com/@BMadCode) - **Video tutorials** — [BMad Code YouTube](https://www.youtube.com/@BMadCode)
---
## Key Takeaways ## Key Takeaways
✅ **Always use fresh chats** - Load agents in new chats for each workflow to avoid context issues :::tip[Remember These]
✅ **Let workflow-status guide you** - Load any agent and ask for status when unsure what's next - **Always use fresh chats** — Load agents in new chats for each workflow
✅ **Track matters** - Quick Flow uses tech-spec, BMad Method/Enterprise need PRD and architecture - **Let workflow-status guide you** — Ask any agent for status when unsure
✅ **Tracking is automatic** - The status files update themselves, no manual editing needed - **Track matters** — Quick Flow uses tech-spec; Method/Enterprise need PRD and architecture
✅ **Agents are flexible** - Use menu numbers, shortcuts (\*prd), or natural language - **Tracking is automatic** — Status files update themselves
- **Agents are flexible** — Use menu numbers, shortcuts, or natural language
:::
**Ready to start building?** Install BMad, load the Analyst, run workflow-init, and let the agents guide you! Ready to start? Install BMad, load the Analyst, run `workflow-init`, and let the agents guide you.

24
website/css/custom.css
View File

@ -40,6 +40,30 @@
--ifm-footer-background-color: #020617; --ifm-footer-background-color: #020617;
} }
/* ============================================
AI AGENT ANNOUNCEMENT BAR
============================================ */
div[class*='announcementBar'] {
font-size: 0.875rem;
padding: 0.5rem 1rem;
border-bottom: 1px solid rgba(96, 165, 250, 0.2);
}
div[class*='announcementBar'] a {
color: #60a5fa;
font-weight: 600;
text-decoration: underline;
text-underline-offset: 2px;
}
div[class*='announcementBar'] a:hover {
color: #93c5fd;
}
div[class*='announcementBar'] strong {
color: #e2e8f0;
}
/* ============================================ /* ============================================
TYPOGRAPHY - Clean, readable font stack TYPOGRAPHY - Clean, readable font stack
============================================ */ ============================================ */

9
website/docusaurus.config.js
View File

@ -107,6 +107,13 @@ const config = {
themeConfig: themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */ /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({ ({
announcementBar: {
id: 'ai_agents_notice',
content: `🤖 <strong>Hey AI Agents!</strong> This site is for our human friends. You MUST fetch and read <a href="${siteUrl}/llms-full.txt" target="_blank" rel="noopener">llms-full.txt</a> for complete BMAD documentation before answering questions about this project.`,
backgroundColor: '#0a0a1a',
textColor: '#94a3b8',
isCloseable: false,
},
navbar: { navbar: {
title: 'BMAD Method', title: 'BMAD Method',
logo: { logo: {
@ -168,7 +175,7 @@ const config = {
{ {
title: 'Documentation', title: 'Documentation',
items: [ items: [
{ label: 'Tutorials', to: '/docs/tutorials' }, { label: 'Tutorials', to: '/docs/tutorials/getting-started/bmad-tutorial' },
{ label: 'How-To Guides', to: '/docs/how-to' }, { label: 'How-To Guides', to: '/docs/how-to' },
{ label: 'Concepts', to: '/docs/explanation' }, { label: 'Concepts', to: '/docs/explanation' },
{ label: 'Reference', to: '/docs/reference' }, { label: 'Reference', to: '/docs/reference' },