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): apply unified tutorial style and update references 

- Reformat create-custom-agent.md to follow tutorial style guide
- Update tutorial-style.md with complete unified structure
- Update all internal references to renamed tutorial files
- Remove obsolete advanced/index.md

🤖 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 21:54:43 -05:00 committed by Alex Verkhovsky
parent b06b11c2bf
commit 8e7c7082fc
26 changed files with 786 additions and 683 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
docs/_contributing/tutorial-style.md
View File

@ -1,16 +1,30 @@
# Tutorial Style Guide
Standards for writing tutorials and getting-started guides in BMAD documentation.
Standards for writing tutorials and getting-started guides in BMad documentation.
## Structure
## Standard Structure
Every tutorial should follow this flow:
Every tutorial should follow this structure:
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
```
1. Title + Hook (1-2 sentences describing the outcome)
2. Version/Module Notice (info or warning admonition as appropriate)
3. What You'll Learn (bullet list of outcomes)
4. Prerequisites (info admonition)
5. Quick Path (tip admonition - TL;DR summary)
6. Understanding [Topic] (context before steps - tables for phases/agents)
7. Installation (if applicable)
8. Step 1: [First Major Task]
9. Step 2: [Second Major Task]
10. Step 3: [Third Major Task]
11. What You've Accomplished (summary + folder structure if applicable)
12. Quick Reference (commands table)
13. Common Questions (FAQ format)
14. Getting Help (community links)
15. Key Takeaways (tip admonition - memorable points)
```
Not all sections are required for every tutorial, but this is the standard flow.
## Visual Hierarchy
@ -44,7 +58,7 @@ Shortcuts, best practices, "pro tips"
:::
:::info[Title]
Context, definitions, examples
Context, definitions, examples, prerequisites
:::
:::note
@ -60,6 +74,17 @@ Critical warnings only — data loss, security issues
:::
```
### Standard Admonition Uses
| Admonition | Standard Use in Tutorials |
|------------|---------------------------|
| `:::info[Prerequisites]` | What users need before starting |
| `:::tip[Quick Path]` | TL;DR summary at top of tutorial |
| `:::warning[Fresh Chats]` | Context limitation reminders |
| `:::info[Example]` | Command/response examples |
| `:::tip[Check Your Status]` | How to verify progress |
| `:::tip[Remember These]` | Key takeaways at end |
### Admonition Guidelines
- **Always include a title** for tip, info, and warning
@ -71,13 +96,13 @@ Critical warnings only — data loss, security issues
### Budget
- **5-7 `##` sections** maximum per tutorial
- **8-12 `##` sections** for full tutorials following standard structure
- **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 action verbs for steps: "Install BMad", "Create Your Plan"
- Use nouns for reference sections: "Common Questions", "Quick Reference"
- Keep headers short and scannable
@ -87,7 +112,7 @@ Critical warnings only — data loss, security issues
```md
```bash
npx bmad-method@alpha install
npx bmad-method install
```
```
@ -111,8 +136,10 @@ Run `workflow-status` and the agent will tell you the next recommended workflow.
## Tables
Use tables for:
- Phases and what happens in each
- Agent roles and when to use them
- Command references
- Comparing options
- Mapping relationships (agent → document)
- Step sequences with multiple attributes
Keep tables simple:
@ -120,6 +147,32 @@ Keep tables simple:
- Short cell content
- Left-align text, right-align numbers
### Standard Tables
**Phases Table:**
```md
| Phase | Name | What Happens |
|-------|------|--------------|
| 1 | Analysis | Brainstorm, research *(optional)* |
| 2 | Planning | Requirements — PRD or tech-spec *(required)* |
```
**Quick Reference Table:**
```md
| Command | Agent | Purpose |
|---------|-------|---------|
| `*workflow-init` | Analyst | Initialize a new project |
| `*prd` | PM | Create Product Requirements Document |
```
**Build Cycle Table:**
```md
| Step | Agent | Workflow | Purpose |
|------|-------|----------|---------|
| 1 | SM | `create-story` | Create story file from epic |
| 2 | DEV | `dev-story` | Implement the story |
```
## Lists
### Flat Lists (Preferred)
@ -134,7 +187,7 @@ Keep tables simple:
```md
1. Load the **PM agent** in a new chat
2. Run the PRD workflow
2. Run the PRD workflow: `*prd`
3. Output: `PRD.md`
```
@ -177,6 +230,23 @@ Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.
Yes. The SM agent has a `correct-course` workflow for handling scope changes.
```
## Folder Structure Blocks
Show project structure in "What You've Accomplished":
````md
Your project now has:
```
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── PRD.md # Your requirements document
│ └── bmm-workflow-status.yaml # Progress tracking
└── ...
```
````
## Example: Before and After
### Before (Noisy)
@ -204,7 +274,7 @@ Yes. The SM agent has a `correct-course` workflow for handling scope changes.
### After (Clean)
```md
## Step 1: Initialize Your Workflow
## Step 1: Initialize Your Project
Load the **Analyst agent** in your IDE, wait for the menu, then run `workflow-init`.
@ -217,12 +287,20 @@ You'll describe your project goals and complexity. The workflow then recommends
Before submitting a tutorial:
- [ ] Follows the standard structure (hook → learn → steps → summary)
- [ ] Follows the standard structure
- [ ] Has version/module notice if applicable
- [ ] Has "What You'll Learn" section
- [ ] Has Prerequisites admonition
- [ ] Has Quick Path TL;DR admonition
- [ ] No horizontal rules (`---`)
- [ ] No `####` headers
- [ ] Admonitions used for callouts (not bold paragraphs)
- [ ] Tables used for structured data
- [ ] Tables used for structured data (phases, commands, agents)
- [ ] Lists are flat (no deep nesting)
- [ ] 5-7 `##` sections maximum
- [ ] Has "What You've Accomplished" section
- [ ] Has Quick Reference table
- [ ] Has Common Questions section
- [ ] Has Getting Help section
- [ ] Has Key Takeaways admonition
- [ ] All links use descriptive text
- [ ] Images have alt text and captions

2
docs/explanation/agents/barry-quick-flow.md
View File

@ -307,7 +307,7 @@ Implement OAuth 2.0 authentication with JWT tokens and role-based access control
## Related Documentation
- **[Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md)** - Getting started with BMM
- **[Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md)** - Getting started with BMM
- **[Agents Guide](../../explanation/core-concepts/agent-roles.md)** - Complete agent reference
- **[Four Phases](../../explanation/architecture/four-phases.md)** - Understanding development tracks
- **[Workflow Implementation](../../how-to/workflows/run-sprint-planning.md)** - Implementation workflows

2
docs/explanation/architecture/four-phases.md
View File

@ -124,4 +124,4 @@ Same as BMad Method with optional extended workflows.
- [Why Solutioning Matters](./why-solutioning-matters.md)
- [Preventing Agent Conflicts](./preventing-agent-conflicts.md)
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md)
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md)

6
docs/explanation/bmm/index.md
View File

@ -8,7 +8,7 @@ Complete guides for the BMad Method Module (BMM) - AI-powered agile development
**New to BMM?** Start here:
- **[Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md)** - Step-by-step guide to building your first project
- **[Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md)** - Step-by-step guide to building your first project
- Installation and setup
- Understanding the four phases
- Running your first workflows
@ -83,7 +83,7 @@ Essential reference materials:
### I need to...
**Build something new (greenfield)**
→ Start with [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md)
→ Start with [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md)
**Fix a bug or add small feature**
→ Use the [Quick Flow Solo Dev](../agents/barry-quick-flow.md) directly with its dedicated stand alone [Quick Bmad Spec Flow](../features/quick-flow.md) process
@ -129,4 +129,4 @@ Comprehensive documentation for all BMM workflows organized by phase:
- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features
- **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and walkthroughs
**Ready to begin?** → [Start with the Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md)
**Ready to begin?** → [Start with the Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md)

2
docs/explanation/core-concepts/agent-roles.md
View File

@ -202,4 +202,4 @@ Fast solo development without handoffs.
- [What Are Agents](./what-are-agents.md) - Foundational concepts
- [Agent Reference](../../reference/agents/index.md) - Complete command reference
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md)
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md)

2
docs/explanation/faq/brownfield-faq.md
View File

@ -72,7 +72,7 @@ BMM respects your choice - it won't force modernization, but it will offer it.
## Related Documentation
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Get started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Get started with BMM
- [Brownfield Guide](../../how-to/brownfield/index.md) - Existing codebase workflows
- [Glossary](../../reference/glossary/index.md) - Terminology reference

4
docs/explanation/faq/getting-started-faq.md
View File

@ -17,7 +17,7 @@ Quick answers to common questions about getting started with the BMad Method.
- Creates the tracking status file
- Routes you to the correct starting workflow
For experienced users: use the [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) to go directly to the right agent/workflow.
For experienced users: use the [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) to go directly to the right agent/workflow.
## Q: Why do I need fresh chats for each workflow?
@ -59,7 +59,7 @@ Quick workflows like status checks can reuse chats safely.
## Related Documentation
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Get started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Get started with BMM
- [Glossary](../../reference/glossary/index.md) - Terminology reference
---

2
docs/explanation/faq/implementation-faq.md
View File

@ -49,7 +49,7 @@ Don't wait until project end - run after each epic for continuous improvement.
## Related Documentation
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Get started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Get started with BMM
- [Glossary](../../reference/glossary/index.md) - Terminology reference
---

2
docs/explanation/faq/levels-and-tracks-faq.md
View File

@ -51,7 +51,7 @@ The overlap (5-10 stories) is intentional. Choose based on:
## Related Documentation
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Get started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Get started with BMM
- [Glossary](../../reference/glossary/index.md) - Terminology reference
---

2
docs/explanation/faq/planning-faq.md
View File

@ -40,7 +40,7 @@ PRDs are for Level 2-4 projects with multiple features requiring product-level c
## Related Documentation
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Get started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Get started with BMM
- [Glossary](../../reference/glossary/index.md) - Terminology reference
---

2
docs/explanation/faq/tools-faq.md
View File

@ -241,7 +241,7 @@ Please include:
## Related Documentation
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Get started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Get started with BMM
- [Glossary](../../reference/glossary/index.md) - Terminology reference
---

2
docs/explanation/faq/workflows-faq.md
View File

@ -61,7 +61,7 @@ If status file exists, use workflow-status. If not, use workflow-init.
## Related Documentation
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Get started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Get started with BMM
- [Glossary](../../reference/glossary/index.md) - Terminology reference
---

2
docs/explanation/features/party-mode.md
View File

@ -106,7 +106,7 @@ _(Multiple perspectives reveal the right answer)_
## Related Documentation
- [Agents Reference](../../reference/agents/index.md) - Complete agent reference
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Getting started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM
- [Setup Party Mode](../../how-to/workflows/setup-party-mode.md) - How to use it
---

2
docs/explanation/features/quick-flow.md
View File

@ -166,5 +166,5 @@ Start with Quick Flow, but switch to BMad Method when:
## Related
- [Create Tech Spec](../../how-to/workflows/create-tech-spec.md) - How to use Quick Flow
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Getting started
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Getting started
- [Four Phases](../architecture/four-phases.md) - Understanding the full methodology

2
docs/how-to/brownfield/index.md
View File

@ -99,5 +99,5 @@ Pay close attention here to prevent reinventing the wheel or making decisions th
## Related Documentation
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Getting started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM
- [Quick Spec Flow](../../explanation/features/quick-flow.md) - Fast path for small changes

2
docs/how-to/installation/install-bmad.md
View File

@ -136,6 +136,6 @@ npx bmad-method install --verbose
## Related
- [Quick Start Guide](../../tutorials/getting-started/quick-start-bmm.md) - Getting started with BMM
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM
- [Upgrade to V6](./upgrade-to-v6.md) - Upgrading from previous versions
- [Install Custom Modules](./install-custom-modules.md) - Adding custom content

30
docs/index.md
View File

@ -1,27 +1,28 @@
---
slug: /
sidebar_position: 1
title: Welcome to BMAD
title: Welcome to BMad
---
# Welcome to BMAD
# Welcome to BMad
BMAD (**B**uild **M**ore, **A**rchitect **D**reams) is an AI-driven development framework that helps you build software faster and smarter. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity—whether you're fixing a bug or building an enterprise platform.
BMad (**B**uild **M**ore, **A**rchitect **D**reams) is an AI-driven development framework that helps you build software faster and smarter. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity—whether you're fixing a bug or building an enterprise platform.
If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
---
## New Here? Start with the Quick Start
## New Here? Start with a Tutorial
The fastest way to understand BMAD is to try it. The Quick Start guide walks you through your first project in about 10 minutes.
The fastest way to understand BMad is to try it. Choose a tutorial to walk through your first project in about 10 minutes.
<a className="button button--primary button--lg" href="/docs/tutorials/getting-started/quick-start-bmm">Get Started with BMAD</a>
<a className="button button--primary button--lg margin-right--md" href="/docs/tutorials/getting-started/getting-started-bmadv4">Get Started with v4 (Stable)</a>
<a className="button button--secondary button--lg" href="/docs/tutorials/getting-started/getting-started-bmadv6">Try v6 (Alpha)</a>
<br/>
:::tip Already familiar with AI-assisted development?
Feel free to skip around. Use the sidebar to jump to any topic, or check out [What Are Agents?](./explanation/core-concepts/what-are-agents.md) to understand how BMAD organizes its AI personas.
Feel free to skip around. Use the sidebar to jump to any topic, or check out [What Are Agents?](./explanation/core-concepts/what-are-agents.md) to understand how BMad organizes its AI personas.
:::
---
@ -37,7 +38,7 @@ These docs are organized into four sections based on what you're trying to do:
<h3>Tutorials</h3>
</div>
<div className="card__body">
<p><strong>Learning-oriented.</strong> Step-by-step guides that walk you through building something. Start here if you're new to BMAD.</p>
<p><strong>Learning-oriented.</strong> Step-by-step guides that walk you through building something. Start here if you're new to BMad.</p>
</div>
</div>
</div>
@ -77,22 +78,22 @@ These docs are organized into four sections based on what you're trying to do:
## What You'll Need
BMAD works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
- **[Claude Code](https://claude.ai/claude-code)** — Anthropic's CLI tool (recommended)
- **[Cursor](https://cursor.sh)** — AI-first code editor
- **[Windsurf](https://codeium.com/windsurf)** — Codeium's AI IDE
- **[Roo Code](https://roocode.com)** — VS Code extension
You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with BMAD-style agent systems is required—that's what these docs are for.
You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with BMad-style agent systems is required—that's what these docs are for.
---
## Join the Community
Get help, share what you're building, or contribute to BMAD:
Get help, share what you're building, or contribute to BMad:
- **[Discord](https://discord.gg/gk8jAdXWmj)** — Chat with other BMAD users, ask questions, share ideas
- **[Discord](https://discord.gg/gk8jAdXWmj)** — Chat with other BMad users, ask questions, share ideas
- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Source code, issues, and contributions
- **[YouTube](https://www.youtube.com/@BMadCode)** — Video tutorials and walkthroughs
@ -100,6 +101,7 @@ Get help, share what you're building, or contribute to BMAD:
## Next Step
Ready to dive in? Head to the Quick Start to build your first project with BMAD.
Ready to dive in? Pick a tutorial and start building.
<a className="button button--primary button--lg" href="/docs/tutorials/getting-started/quick-start-bmm">Start the Quick Start Tutorial</a>
<a className="button button--primary button--lg margin-right--md" href="/docs/tutorials/getting-started/getting-started-bmadv4">Get Started with v4 (Stable)</a>
<a className="button button--secondary button--lg" href="/docs/tutorials/getting-started/getting-started-bmadv6">Try v6 (Alpha)</a>

223
docs/tutorials/advanced/create-custom-agent.md
View File

@ -1,44 +1,90 @@
# Agent Creation Guide
# Create a Custom Agent
Create your own custom agents using the BMAD Builder workflow.
Build your own AI agent with a unique personality, specialized commands, and optional persistent memory using the BMad Builder workflow.
## Overview
:::info[BMB Module]
This tutorial uses the **BMad Builder (BMB)** module. Make sure you have BMAD installed with the BMB module enabled.
:::
The BMAD Builder (BMB) module provides an interactive workflow that guides you through creating a custom agent from concept to completion. You define the agent's purpose, personality, capabilities, and menu - then the workflow generates a complete, ready-to-use agent file.
## What You'll Learn
## Before You Start
- How to run the `create-agent` workflow
- Choose between Simple, Expert, and Module agent types
- Define your agent's persona (role, identity, communication style, principles)
- Package and install your custom agent
- Test and iterate on your agent's behavior
**Prerequisites:**
:::info[Prerequisites]
- BMAD installed with the BMB module
- An idea for what you want your agent to do
- About 15-30 minutes for your first agent
:::
**Know Before You Go:**
- What problem should your agent solve?
- Who will use this agent?
- What should the agent be able to do?
:::tip[Quick Path]
Run `create-agent` workflow → Follow the guided steps → Install your agent module → Test and iterate.
:::
## Quick Start
## Understanding Agent Types
### 1. Start the Workflow
Before creating your agent, understand the three types available:
| Type | Best For | Memory | Complexity |
| ---------- | ------------------------------------- | ---------- | ---------- |
| **Simple** | Focused tasks, quick setup | None | Low |
| **Expert** | Specialized domains, ongoing projects | Persistent | Medium |
| **Module** | Building other agents/workflows | Persistent | High |
**Simple Agent** - Use when your task is well-defined and focused. Perfect for single-purpose assistants like commit message generators or code reviewers.
**Expert Agent** - Use when your domain requires specialized knowledge or you need memory across sessions. Great for roles like Security Architect or Documentation Lead.
**Module Agent** - Use when your agent builds other agents or needs deep integration with the module system.
## Step 1: Start the Workflow
In your IDE (Claude Code, Cursor, etc.), invoke the create-agent workflow with the agent-builder agent.
### 2. Follow the Steps
The workflow guides you through eight steps:
The workflow guides you through:
| Step | What You'll Do |
| --------------------------- | -------------------------------------------- |
| **Brainstorm** *(optional)* | Explore ideas with creative techniques |
| **Discovery** | Define the agent's purpose and goals |
| **Type & Metadata** | Choose Simple or Expert, name your agent |
| **Persona** | Craft the agent's personality and principles |
| **Commands** | Define what the agent can do |
| **Activation** | Set up autonomous behaviors *(optional)* |
| **Build** | Generate the agent file |
| **Validation** | Review and verify everything works |
| Step | What You'll Do |
| ------------------------- | -------------------------------------------- |
| **Brainstorm** (optional) | Explore ideas with creative techniques |
| **Discovery** | Define the agent's purpose and goals |
| **Type & Metadata** | Choose Simple or Expert, name your agent |
| **Persona** | Craft the agent's personality and principles |
| **Commands** | Define what the agent can do |
| **Activation** | Set up autonomous behaviors (optional) |
| **Build** | Generate the agent file |
| **Validation** | Review and verify everything works |
:::tip[Workflow Options]
At each step, the workflow provides options:
- **[A] Advanced** - Get deeper insights and reasoning
- **[P] Party** - Get multiple agent perspectives
- **[C] Continue** - Move to the next step
:::
### 3. Install Your Agent
## Step 2: Define the Persona
Your agent's personality is defined by four fields:
| Field | Purpose | Example |
| ----------------------- | -------------- | ----------------------------------------------------------------- |
| **Role** | What they do | "Senior code reviewer who catches bugs and suggests improvements" |
| **Identity** | Who they are | "Friendly but exacting, believes clean code is a craft" |
| **Communication Style** | How they speak | "Direct, constructive, explains the 'why' behind suggestions" |
| **Principles** | Why they act | "Security first, clarity over cleverness, test what you fix" |
Keep each field focused on its purpose. The role isn't personality; the identity isn't job description.
:::info[Writing Great Principles]
The first principle should "activate" the agent's expertise:
- **Weak:** "Be helpful and accurate"
- **Strong:** "Channel decades of security expertise: threat modeling begins with trust boundaries, never trust client input, defense in depth is non-negotiable"
:::
## Step 3: Install Your Agent
Once created, package your agent for installation:
@ -53,98 +99,60 @@ my-custom-stuff/
└── workflows/ # Optional: custom workflows
```
See [Custom Content Installation](../../how-to/installation/install-custom-modules.md) for details.
Install using the BMAD installer, then invoke your new agent in your IDE.
## Choosing Your Agent Type
## What You've Accomplished
The workflow will help you decide, but here's the quick reference:
You've created a custom AI agent with:
### Choose Simple Agent When:
- A defined purpose and role in your workflow
- A unique persona with communication style and principles
- Custom menu commands for your specific tasks
- Optional persistent memory for ongoing context
- Task is well-defined and focused
- Don't need persistent memory
- Want fast setup and deployment
- Single-purpose assistant (e.g., commit messages, code review)
Your project now includes:
**Example:** A "Code Commenter" that reads files and adds helpful comments.
```
_bmad/
├── _config/
│ └── agents/
│ └── {your-agent}/ # Your agent customizations
└── {module}/
└── agents/
└── {your-agent}/
└── {your-agent}.agent.yaml
```
### Choose Expert Agent When:
## Quick Reference
- Domain requires specialized knowledge
- Need persistent memory across sessions
- Agent coordinates complex workflows
- Building ongoing project infrastructure
| Action | How |
| ------------------- | ---------------------------------------------- |
| Start workflow | `"Run the BMAD Builder create-agent workflow"` |
| Edit agent directly | Modify `{agent-name}.agent.yaml` |
| Edit customization | Modify `_bmad/_config/agents/{agent-name}` |
| Rebuild agent | `npx bmad-method build <agent-name>` |
| Study examples | Check `src/modules/bmb/reference/agents/` |
**Example:** A "Security Architect" that remembers your design decisions and maintains security standards across the project.
## Common Questions
### Choose Module Agent When:
**Should I start with Simple or Expert?**
Start with Simple for your first agent. You can always upgrade to Expert later if you need persistent memory.
- Agent builds other agents or workflows
- Need integration with module system
- Creating professional tooling
**How do I add more commands later?**
Edit the agent YAML directly or use the customization file in `_bmad/_config/agents/`. Then rebuild.
**Example:** A "Team Builder" that helps set up agents for new team members.
## The Persona System
Your agent's personality is defined by four fields:
| Field | Purpose | Example |
| ----------------------- | -------------- | ----------------------------------------------------------------- |
| **Role** | What they do | "Senior code reviewer who catches bugs and suggests improvements" |
| **Identity** | Who they are | "Friendly but exacting, believes clean code is a craft" |
| **Communication Style** | How they speak | "Direct, constructive, explains the 'why' behind suggestions" |
| **Principles** | Why they act | "Security first, clarity over cleverness, test what you fix" |
**Key:** Keep each field focused on its purpose. The role isn't personality; the identity isn't job description.
## Tips for Success
### Start Small
Your first agent should solve **one problem well**. You can always add more capabilities later.
### Learn by Example
**Can I share my agent with others?**
Yes. Package your agent as a standalone module and share it with your team or the community.
**Where can I see example agents?**
Study the reference agents in `src/modules/bmb/reference/agents/`:
- **Simple:** [commit-poet](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)
- **Expert:** [journal-keeper](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper)
- [commit-poet](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml) (Simple)
- [journal-keeper](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) (Expert)
### Write Great Principles
## Getting Help
The first principle should "activate" the agent's expertise:
❌ **Weak:** "Be helpful and accurate"
✅ **Strong:** "Channel decades of security expertise: threat modeling begins with trust boundaries, never trust client input, defense in depth is non-negotiable"
### Use the Menu System
The workflow provides options at each step:
- **[A] Advanced** - Get deeper insights and reasoning
- **[P] Party** - Get multiple agent perspectives
- **[C] Continue** - Move to the next step
Use these when you need extra input or creative options.
## After Creation
### Test Your Agent
1. Install your custom module using the BMAD installer
2. Invoke your new agent in your IDE
3. Try each menu command
4. Verify the personality feels right
### Iterate
If something isn't right:
1. Edit the agent YAML directly, or
2. Edit the customization file in `_bmad/_config/agents/`
3. Rebuild using `npx bmad-method build <agent-name>`
### Share
Package your agent as a standalone module (see [Installation Guide](../../how-to/installation/index.md)) and share it with your team or the community.
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Ask in #general-dev or #bugs-issues
- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features
## Further Reading
@ -152,8 +160,9 @@ Package your agent as a standalone module (see [Installation Guide](../../how-to
- **[Agent Customization](../../how-to/customization/customize-agents.md)** - Modify agents without editing core files
- **[Custom Content Installation](../../how-to/installation/install-custom-modules.md)** - Package and distribute your agents
---
**Ready?** Start the workflow and create your first agent!
[← Back to Advanced Tutorials](./index.md)
:::tip[Key Takeaways]
- **Start small** - Your first agent should solve one problem well
- **Persona matters** - Strong principles activate the agent's expertise
- **Iterate often** - Test your agent and refine based on behavior
- **Learn from examples** - Study reference agents before building your own
:::

16
docs/tutorials/advanced/index.md
View File

@ -1,16 +0,0 @@
---
sidebar_label: Advanced Tutorials
description: Advanced tutorials for extending BMad Method
---
# Advanced Tutorials
Deep-dive tutorials for advanced BMad Method usage.
## Available Tutorials
| Tutorial | Description |
|----------|-------------|
| **[Create Custom Agent](./create-custom-agent.md)** | Build your own AI agents |
> **Looking for Brownfield Development?** See the [Brownfield Development Guide](../../how-to/brownfield/index.md) in How-To guides.

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

@ -1,242 +0,0 @@
---
sidebar_label: BMad v4
sidebar_position: 1
description: Install BMAD and create your first planning document
---
# Getting Started with BMad v4
Learn how to build software with BMAD's AI-powered workflows. By the end of this tutorial, you'll have installed BMAD, initialized a project, and created your first planning document.
## What You'll Learn
- How to install and configure BMAD for your IDE
- How BMAD organizes work into phases and agents
- How to initialize a project and choose a planning track
- How to create your first requirements document
:::info[Prerequisites]
- **Node.js 20+** — Required for the installer
- **Git** — Recommended for version control
- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
- **A project idea** — Even a simple one works for learning
:::
## Step 1: Install BMAD
Open a terminal in your project directory and run:
```bash
npx bmad-method install
```
The interactive installer guides you through setup.
**Choose Installation Location** — Select current directory (recommended), subdirectory, or custom path.
**Select Your AI Tool** — Choose Claude Code, Cursor, Windsurf, or other. The installer configures BMAD for your selection.
**Choose Modules** — For this tutorial, select **BMM** (BMAD Method):
| Module | Purpose |
| -------- | ----------------------------------------- |
| **BMM** | Core methodology for software development |
| **BMGD** | Game development workflows |
| **CIS** | Creative intelligence and facilitation |
| **BMB** | Building custom agents and workflows |
**Accept Default Configuration** — For your first project, accept the recommended defaults. Customize later in `_bmad/[module]/config.yaml`.
**Verify Installation** — Check your project structure:
```
your-project/
├── _bmad/
│ ├── bmm/ # Method module
│ │ ├── agents/ # Agent files
│ │ ├── workflows/ # Workflow files
│ │ └── config.yaml # Module config
│ └── core/ # Core utilities
├── _bmad-output/ # Generated artifacts (created later)
└── .claude/ # IDE configuration (if using Claude Code)
```
:::tip[Troubleshooting]
Having issues? See [Install BMAD](../../how-to/installation/install-bmad.md) for common solutions.
:::
## Step 2: Understand How BMAD Works
Before diving in, learn BMAD's core concepts.
### Phases
BMAD organizes work into four phases:
| Phase | Name | What Happens |
| ----- | -------------- | -------------------------------------------------- |
| 1 | Analysis | Brainstorm, research *(optional)* |
| 2 | Planning | Requirements — PRD or tech-spec *(required)* |
| 3 | Solutioning | Architecture, design decisions *(varies by track)* |
| 4 | Implementation | Build code story by story *(required)* |
### Agents
Agents are specialized AI personas, each expert in their domain:
| Agent | Role |
| --------------- | -------------------------------------------------------- |
| **Analyst** | Initializes projects, tracks progress, conducts research |
| **PM** | Creates requirements (PRD or tech-spec) |
| **UX-Designer** | Designs user interfaces and experiences |
| **Architect** | Makes technical decisions, designs system architecture |
| **SM** | Manages sprints, creates stories |
| **DEV** | Implements code, reviews work |
### Workflows
Workflows are guided processes that agents run. You tell an agent to run a workflow, and it walks you through the process interactively.
### Planning Tracks
Based on your project's complexity, BMAD offers three tracks:
| Track | Best For | Documents Created |
| --------------- | ------------------------------------------ | -------------------------------------- |
| **Quick Flow** | Bug fixes, simple features, clear scope | Tech-spec only |
| **BMAD Method** | Products, platforms, complex features | PRD + Architecture + UX |
| **Enterprise** | Compliance, multi-tenant, enterprise needs | PRD + Architecture + Security + DevOps |
## Step 3: Initialize Your Project
Load the **Analyst agent** in your IDE:
- **Claude Code**: Type `/analyst` or load the agent file directly
- **Cursor/Windsurf**: Open the agent file from `_bmad/bmm/agents/`
Wait for the agent's menu to appear, then run the initialization workflow:
```
Run workflow-init
```
Or use the shorthand: `*workflow-init`
The workflow asks you to describe:
- **Your project and goals** — What are you building? What problem does it solve?
- **Existing codebase** — Is this new (greenfield) or existing code (brownfield)?
- **Size and complexity** — Roughly how big is this? (adjustable later)
Based on your description, the workflow suggests a planning track. For this tutorial, choose **BMAD Method**.
Once you confirm, the workflow creates `bmm-workflow-status.yaml` in your project's docs folder to track your progress.
:::warning[Fresh Chats]
Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
:::
## Step 4: Create Your Requirements Document
With your project initialized, create your first planning document — the PRD (Product Requirements Document).
**Start a fresh chat** and load the **PM agent**.
Tell the PM agent:
```
Run prd
```
Or use shortcuts: `*prd`, select "create-prd" from the menu, or say "Let's create a new PRD".
The PM agent guides you through creating your PRD interactively:
1. **Project overview** — Refine your project description
2. **Goals and success metrics** — What does success look like?
3. **User personas** — Who uses this product?
4. **Functional requirements** — What must the system do?
5. **Non-functional requirements** — Performance, security, scalability needs
Answer the agent's questions thoughtfully. The PRD becomes the foundation for everything that follows.
When complete, you'll have a `PRD.md` file in your `_bmad-output/` folder.
## Step 5: Check Your Progress
At any point, check what to do next by loading any agent and running:
```
workflow-status
```
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.
:::info[Example Response]
Phase 2 (Planning) complete: PRD created
Next recommended steps:
- UX Design (optional, if your project has a UI)
- Architecture (required for BMAD Method track) — Agent: architect, Command: `create-architecture`
:::
## What You've Accomplished
You've completed the foundation of a BMAD project:
- Installed BMAD and configured it for your IDE
- Initialized a project with your chosen planning track
- Created a PRD that defines your product requirements
Your project now has:
```
your-project/
├── _bmad/ # BMAD configuration
├── _bmad-output/
│ ├── PRD.md # Your requirements document
│ └── bmm-workflow-status.yaml # Progress tracking
└── ...
```
## Next Steps
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:
- [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
- [Workflow Reference](../../reference/workflows/index.md) — Complete list of available workflows
## Quick Reference
| Command | Agent | Purpose |
| ----------------- | ------- | -------------------------------------- |
| `*workflow-init` | Analyst | Initialize a new project |
| `*prd` | PM | Create a Product Requirements Document |
| `workflow-status` | Any | Check progress and next steps |
:::tip[Flexible Commands]
Agents accept menu numbers, shortcuts (`*prd`), or natural language ("Let's create a PRD").
:::
## Common Questions
**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.
**Can I skip Phase 1 (Analysis)?**
Yes, Phase 1 is optional. If you already know what you're building, start with Phase 2 (Planning).
**What if I want to brainstorm first?**
Load the Analyst agent and run `*brainstorm-project` before `workflow-init`.
**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.
## Getting Help
- **During workflows** — Agents guide you with questions and explanations
- **Check status** — Run `workflow-status` with any agent
- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#general-dev, #bugs-issues)
- **Video tutorials** — [BMad Code YouTube](https://www.youtube.com/@BMadCode)

249
docs/tutorials/getting-started/getting-started-bmadv4.md Normal file
View File

@ -0,0 +1,249 @@
---
sidebar_label: BMad v4
sidebar_position: 1
description: Install BMad and create your first planning document
---
# Getting Started with BMad v4
Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
:::info[Stable Release]
This tutorial covers BMad v4, the current stable release. For the latest features (with potential breaking changes), see the [BMad v6 Alpha tutorial](./getting-started-bmadv6.md).
:::
## What You'll Learn
- Install and configure BMad for your IDE
- Understand how BMad organizes work into phases and agents
- Initialize a project and choose a planning track
- Create your first requirements document
:::info[Prerequisites]
- **Node.js 20+** — Required for the installer
- **Git** — Recommended for version control
- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
- **A project idea** — Even a simple one works for learning
:::
:::tip[Quick Path]
**Install** → `npx bmad-method install`
**Initialize** → Load Analyst agent, run `workflow-init`
**Plan** → PM creates PRD, Architect creates architecture
**Build** → SM manages sprints, DEV implements stories
**Always use fresh chats** for each workflow to avoid context issues.
:::
## Understanding BMad
BMad helps you build software through guided workflows with specialized AI agents. The process follows four phases:
| Phase | Name | What Happens |
|-------|------|--------------|
| 1 | Analysis | Brainstorm, research *(optional)* |
| 2 | Planning | Requirements — PRD or tech-spec *(required)* |
| 3 | Solutioning | Architecture, design decisions *(varies by track)* |
| 4 | Implementation | Build code story by story *(required)* |
Based on your project's complexity, BMad offers three planning tracks:
| Track | Best For | Documents Created |
|-------|----------|-------------------|
| **Quick Flow** | Bug fixes, simple features, clear scope | Tech-spec only |
| **BMad Method** | Products, platforms, complex features | PRD + Architecture + UX |
| **Enterprise** | Compliance, multi-tenant, enterprise needs | PRD + Architecture + Security + DevOps |
## Installation
Open a terminal in your project directory and run:
```bash
npx bmad-method install
```
The interactive installer guides you through setup:
- **Choose Installation Location** — Select current directory (recommended), subdirectory, or custom path
- **Select Your AI Tool** — Claude Code, Cursor, Windsurf, or other
- **Choose Modules** — Select **BMM** (BMad Method) for this tutorial
- **Accept Defaults** — Customize later in `_bmad/[module]/config.yaml`
Verify your installation:
```
your-project/
├── _bmad/
│ ├── bmm/ # Method module
│ │ ├── agents/ # Agent files
│ │ ├── workflows/ # Workflow files
│ │ └── config.yaml # Module config
│ └── core/ # Core utilities
├── _bmad-output/ # Generated artifacts (created later)
└── .claude/ # IDE configuration (if using Claude Code)
```
:::tip[Troubleshooting]
Having issues? See [Install BMad](../../how-to/installation/install-bmad.md) for common solutions.
:::
## Step 1: Initialize Your Project
Load the **Analyst agent** in your IDE:
- **Claude Code**: Type `/analyst` or load the agent file directly
- **Cursor/Windsurf**: Open the agent file from `_bmad/bmm/agents/`
Wait for the agent's menu to appear, then run:
```
Run workflow-init
```
Or use the shorthand: `*workflow-init`
The workflow asks you to describe:
- **Your project and goals** — What are you building? What problem does it solve?
- **Existing codebase** — Is this new (greenfield) or existing code (brownfield)?
- **Size and complexity** — Roughly how big is this? (adjustable later)
Based on your description, the workflow suggests a planning track. For this tutorial, choose **BMad Method**.
Once you confirm, the workflow creates `bmm-workflow-status.yaml` to track your progress.
:::warning[Fresh Chats]
Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
:::
## Step 2: Create Your Plan
With your project initialized, work through the planning phases.
### Phase 1: Analysis (Optional)
If you want to brainstorm or research first:
- **brainstorm-project** — Guided ideation with the Analyst
- **research** — Market and technical research
- **product-brief** — Recommended foundation document
### Phase 2: Planning (Required)
**Start a fresh chat** and load the **PM agent**.
```
Run prd
```
Or use shortcuts: `*prd`, select "create-prd" from the menu, or say "Let's create a PRD".
The PM agent guides you through:
1. **Project overview** — Refine your project description
2. **Goals and success metrics** — What does success look like?
3. **User personas** — Who uses this product?
4. **Functional requirements** — What must the system do?
5. **Non-functional requirements** — Performance, security, scalability needs
When complete, you'll have `PRD.md` in your `_bmad-output/` folder.
:::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 3: Solutioning (Required for BMad Method)
**Start a fresh chat** and load the **Architect agent**.
```
Run create-architecture
```
The architect guides you through technical decisions: tech stack, database design, API patterns, and system structure.
:::tip[Check Your Status]
Unsure what's next? Load any agent and run `workflow-status`. It tells you the next recommended or required workflow.
:::
## Step 3: Build Your Project
Once planning is complete, move to implementation.
### Initialize Sprint Planning
Load the **SM agent** and run `sprint-planning`. This creates `sprint-status.yaml` to track all epics and stories.
### The Build Cycle
For each story, repeat this cycle with fresh chats:
| Step | Agent | Workflow | Purpose |
|------|-------|----------|---------|
| 1 | SM | `create-story` | Create story file from epic |
| 2 | DEV | `dev-story` | Implement the story |
| 3 | DEV | `code-review` | Quality validation *(recommended)* |
After completing all stories in an epic, load the **SM agent** and run `retrospective`.
## What You've Accomplished
You've learned the foundation of building with BMad:
- Installed BMad and configured it for your IDE
- Initialized a project with your chosen planning track
- Created planning documents (PRD, Architecture)
- Understood the build cycle for implementation
Your project now has:
```
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── PRD.md # Your requirements document
│ ├── architecture.md # Technical decisions
│ └── bmm-workflow-status.yaml # Progress tracking
└── ...
```
## Quick Reference
| Command | Agent | Purpose |
|---------|-------|---------|
| `*workflow-init` | Analyst | Initialize a new project |
| `*workflow-status` | Any | Check progress and next steps |
| `*prd` | PM | Create Product Requirements Document |
| `*create-architecture` | Architect | Create architecture document |
| `*sprint-planning` | SM | Initialize sprint tracking |
| `*create-story` | SM | Create a story file |
| `*dev-story` | DEV | Implement a story |
| `*code-review` | DEV | Review implemented code |
## Common Questions
**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.
**Can I skip Phase 1 (Analysis)?**
Yes, Phase 1 is optional. If you already know what you're building, start with Phase 2 (Planning).
**What if I want to brainstorm first?**
Load the Analyst agent and run `*brainstorm-project` before `workflow-init`.
**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.
## Getting Help
- **During workflows** — Agents guide you with questions and explanations
- **Check status** — Run `workflow-status` with any agent
- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#general-dev, #bugs-issues)
- **Video tutorials** — [BMad Code YouTube](https://www.youtube.com/@BMadCode)
## Key Takeaways
:::tip[Remember These]
- **Always use fresh chats** — Load agents in new chats for each workflow
- **Let workflow-status guide you** — Ask any agent for status when unsure
- **Track matters** — Quick Flow uses tech-spec; Method/Enterprise need PRD and architecture
- **Tracking is automatic** — Status files update themselves
- **Agents are flexible** — Use menu numbers, shortcuts (`*prd`), or natural language
:::
Ready to start? Install BMad, load the Analyst, run `workflow-init`, and let the agents guide you.

157
docs/tutorials/getting-started/quick-start-bmm.md → docs/tutorials/getting-started/getting-started-bmadv6.md
View File

@ -1,14 +1,15 @@
---
sidebar_label: BMad v6 (Alpha)
sidebar_position: 2
description: Install BMad v6 Alpha and build your first project
---
# 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.
Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
:::warning[Alpha Software]
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.
BMad v6 is currently in **alpha**. Expect breaking changes, incomplete features, and evolving documentation. For a stable experience, use the [BMad v4 tutorial](./getting-started-bmadv4.md) instead.
:::
## What You'll Learn
@ -18,6 +19,13 @@ BMad v6 is currently in **alpha**. Expect breaking changes, incomplete features,
- Progress through phases from requirements to working code
- Use agents and workflows effectively
:::info[Prerequisites]
- **Node.js 20+** — Required for the installer
- **Git** — Recommended for version control
- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
- **A project idea** — Even a simple one works for learning
:::
:::tip[Quick Path]
**Install** → `npx bmad-method@alpha install`
**Initialize** → Load Analyst agent, run `workflow-init`
@ -26,9 +34,9 @@ BMad v6 is currently in **alpha**. Expect breaking changes, incomplete features,
**Always use fresh chats** for each workflow to avoid context issues.
:::
## Understanding BMad Method
## Understanding BMad
BMad Method helps you build software through guided workflows with specialized AI agents. The process follows four phases:
BMad helps you build software through guided workflows with specialized AI agents. The process follows four phases:
| Phase | Name | What Happens |
|-------|------|--------------|
@ -41,39 +49,65 @@ BMad Method helps you build software through guided workflows with specialized A
*Complete visual flowchart showing all phases, workflows, and agents for the standard greenfield track.*
Based on your project's complexity, BMad offers three planning tracks:
| Track | Best For | Documents Created |
|-------|----------|-------------------|
| **Quick Flow** | Bug fixes, simple features, clear scope (1-15 stories) | Tech-spec only |
| **BMad Method** | Products, platforms, complex features (10-50+ stories) | PRD + Architecture + UX |
| **Enterprise** | Compliance, multi-tenant systems (30+ stories) | PRD + Architecture + Security + DevOps |
:::note
Story counts are guidance, not definitions. Choose your track based on planning needs, not story math.
:::
## Installation
Open a terminal in your project directory and run:
```bash
npx bmad-method@alpha install
```
The interactive installer guides you through setup and creates a `_bmad/` folder with all agents and workflows.
## Step 1: Initialize Your Workflow
Verify your installation:
Load the **Analyst agent** in your IDE, wait for the menu, then tell it to run `workflow-init`.
```
your-project/
├── _bmad/
│ ├── bmm/ # Method module
│ │ ├── agents/ # Agent files
│ │ ├── workflows/ # Workflow files
│ │ └── config.yaml # Module config
│ └── core/ # Core utilities
├── _bmad-output/ # Generated artifacts (created later)
└── .claude/ # IDE configuration (if using Claude Code)
```
:::tip[Troubleshooting]
Having issues? See [Install BMad](../../how-to/installation/install-bmad.md) for common solutions.
:::
## Step 1: Initialize Your Project
Load the **Analyst agent** in your IDE, wait for the menu, then run `workflow-init`.
:::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.
:::
During initialization, you'll describe your project, whether it's new or existing, and the general complexity. The workflow then recommends a planning track:
**Quick Flow** — Fast implementation with tech-spec only. Best for bug fixes, simple features, and clear scope (typically 1-15 stories).
**BMad Method** — Full planning with PRD, architecture, and optional UX design. Best for products, platforms, and complex features (typically 10-50+ stories).
**Enterprise Method** — Extended planning adding security, DevOps, and test planning. Best for compliance requirements and multi-tenant systems (typically 30+ stories).
:::note
Story counts are guidance, not definitions. Choose your track based on planning needs, not story math.
:::
The workflow asks you to describe your project, whether it's new or existing, and the general complexity. Based on your description, it recommends a planning track.
Once you confirm, the workflow creates `bmm-workflow-status.yaml` to track your progress through all phases.
## Step 2: Work Through Planning Phases
:::warning[Fresh Chats]
Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
:::
After initialization, work through phases 1-3. **Use fresh chats for each workflow** to avoid context limitations.
## Step 2: Create Your Plan
After initialization, work through phases 1-3. **Use fresh chats for each workflow.**
:::tip[Check Your Status]
Unsure what's next? Load any agent and ask for `workflow-status`. It tells you the next recommended or required workflow.
@ -90,7 +124,7 @@ All workflows in this phase are optional:
**For BMad Method and Enterprise tracks:**
1. Load the **PM agent** in a new chat
2. Run the PRD workflow
2. Run the PRD workflow: `*prd`
3. Output: `PRD.md`
**For Quick Flow track:**
@ -122,7 +156,7 @@ Epics and stories are now created *after* architecture. This produces better qua
2. Run `implementation-readiness`
3. Validates cohesion across all planning documents
## Step 3: Build Your Project (Phase 4)
## Step 3: Build Your Project
Once planning is complete, move to implementation. **Each workflow should run in a fresh chat.**
@ -143,62 +177,43 @@ For each story, repeat this cycle with fresh chats:
After completing all stories in an epic, load the **SM agent** and run `retrospective`.
:::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.
:::
## What You've Accomplished
## Understanding the Agents
You've learned the foundation of building with BMad:
| 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 |
- Installed BMad and configured it for your IDE
- Initialized a project with your chosen planning track
- Created planning documents (PRD, Architecture, Epics & Stories)
- Understood the build cycle for implementation
:::info[Working with Agents]
1. Load an agent in your IDE
2. Wait for the menu to appear
3. Tell it what to run (natural language, menu number, or `*shortcut`)
4. Follow the prompts
:::
Your project now has:
## Project Tracking Files
BMad creates two files to track your progress:
**bmm-workflow-status.yaml** — Shows which phase you're in and what's next. Created by `workflow-init`, updated automatically as you progress.
**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.
You don't need to edit these manually—agents update them as you work.
```
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── PRD.md # Your requirements document
│ ├── architecture.md # Technical decisions
│ ├── epics/ # Epic and story files
│ ├── bmm-workflow-status.yaml # Phase progress tracking
│ └── sprint-status.yaml # Sprint tracking
└── ...
```
## Quick Reference
### 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 |
### Workflow Commands
Run these by telling the agent naturally, using menu numbers, or typing `*shortcut`:
- `workflow-init` — Start a new project
- `workflow-status` — Check what's next
- `prd` — Create Product Requirements Document
- `create-architecture` — Create architecture
- `create-epics-and-stories` — Break down PRD into epics
- `sprint-planning` — Initialize sprint tracking
- `create-story` — Create a story file
- `dev-story` — Implement a story
- `code-review` — Review implemented code
| Command | Agent | Purpose |
|---------|-------|---------|
| `*workflow-init` | Analyst | Initialize a new project |
| `*workflow-status` | Any | Check progress and next steps |
| `*prd` | PM | Create Product Requirements Document |
| `*create-architecture` | Architect | Create architecture document |
| `*create-epics-and-stories` | PM | Break down PRD into epics |
| `*implementation-readiness` | Architect | Validate planning cohesion |
| `*sprint-planning` | SM | Initialize sprint tracking |
| `*create-story` | SM | Create a story file |
| `*dev-story` | DEV | Implement a story |
| `*code-review` | DEV | Review implemented code |
## Common Questions
@ -228,7 +243,7 @@ Yes, once you learn the flow. Use the Quick Reference to go directly to needed w
- **Let workflow-status guide you** — Ask any agent for status when unsure
- **Track matters** — Quick Flow uses tech-spec; Method/Enterprise need PRD and architecture
- **Tracking is automatic** — Status files update themselves
- **Agents are flexible** — Use menu numbers, shortcuts, or natural language
- **Agents are flexible** — Use menu numbers, shortcuts (`*prd`), or natural language
:::
Ready to start? Install BMad, load the Analyst, run `workflow-init`, and let the agents guide you.

8
docs/tutorials/getting-started/markdown-demo.md
View File

@ -22,7 +22,7 @@ A comprehensive preview of all markdown elements and styling for light/dark mode
This is a regular paragraph with **bold text**, *italic text*, and ***bold italic text***. Here's some `inline code` as well. You can also use ~~strikethrough~~ text.
This paragraph contains a [link to an external site](https://github.com) and a [link to internal docs](./bmad-tutorial.md).
This paragraph contains a [link to an external site](https://github.com) and a [link to internal docs](./getting-started-bmadv4.md).
### Blockquotes
@ -197,15 +197,15 @@ And multiple paragraphs of text.
### Links
- [External link](https://github.com/bmad-code-org/BMAD-METHOD)
- [Internal link](./bmad-tutorial.md)
- [Internal link](./getting-started-bmadv4.md)
- [Link with title](https://bmad.dev "BMAD Documentation")
- Autolink: <https://example.com>
### Images
![BMAD Logo](/img/logo.svg)
![BMad Workflow](./images/workflow-method-greenfield.svg)
*Caption: The BMAD logo*
*Caption: Example workflow diagram*
## Horizontal Rules

386
docs/tutorials/getting-started/quick-start-bmgd.md
View File

@ -1,255 +1,263 @@
---
sidebar_label: Game Dev Module
sidebar_position: 3
description: Build games with BMad's Game Development Module
---
# Getting started with the BMad Game Developer Module
# Getting Started with BMad Game Development
Get started building games with the BMad Game Development Module.
Build games faster using AI-powered workflows with specialized game development agents that guide you through preproduction, design, architecture, and implementation.
---
:::info[Module Extension]
BMGD (BMad Game Development) is a module that extends BMad Method. You'll need BMad installed first—see the [BMad v4 tutorial](./getting-started-bmadv4.md) or [BMad v6 tutorial](./getting-started-bmadv6.md) if you haven't installed it yet.
:::
## Prerequisites
## What You'll Learn
Before starting with BMGD, ensure you have:
- Install and configure the BMGD module
- Understand game development phases and specialized agents
- Create a Game Brief and Game Design Document (GDD)
- Progress from concept to working game code
1. **BMAD-METHOD installed** - Follow the main installation guide
2. **A game idea** - Even a rough concept is enough to start
3. **Your preferred AI tool** - Claude Code, Cursor, or web-based chat
:::info[Prerequisites]
- **BMad Method installed** — Follow the main installation guide first
- **A game idea** — Even a rough concept is enough to start
- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
:::
---
:::tip[Quick Path]
**Install** → `npx bmad-method install` (select BMGD module)
**Preproduction** → Game Designer creates Game Brief
**Design** → Game Designer creates GDD (and Narrative if story-driven)
**Technical** → Game Architect creates Architecture
**Production** → Game SM manages sprints, Game Dev implements
**Always use fresh chats** for each workflow to avoid context issues.
:::
## Understanding BMGD
BMGD follows four game development phases with specialized agents for each:
| Phase | Name | What Happens |
|-------|------|--------------|
| 1 | Preproduction | Capture game vision, create Game Brief *(optional brainstorming)* |
| 2 | Design | Detail mechanics, systems, narrative in GDD |
| 3 | Technical | Plan engine, architecture, technical decisions |
| 4 | Production | Build game in sprints, story by story |
![BMGD Workflow Overview](./images/workflow-overview.jpg)
*Complete visual flowchart showing all phases, workflows, and agents for game development.*
### Game Development Agents
| Agent | When to Use |
|-------|-------------|
| **Game Designer** | Brainstorming, Game Brief, GDD, Narrative |
| **Game Architect** | Architecture, technical decisions |
| **Game Developer** | Implementation, code reviews |
| **Game Scrum Master** | Sprint planning, story management |
| **Game QA** | Test framework, test design, automation |
| **Game Solo Dev** | Quick prototyping, indie development |
## Installation
BMGD is a custom module that extends BMM. Install it using the BMAD installer:
If you haven't installed BMad yet:
```bash
# During installation, select BMGD when prompted for custom modules
npx bmad-cli install
npx bmad-method install
# Select BMGD when prompted for modules
```
Or add to an existing installation:
Or add BMGD to an existing installation:
```bash
npx bmad-cli install --add-module bmgd
npx bmad-method install --add-module bmgd
```
---
Verify your installation:
## Understanding the Phases
```
your-project/
├── _bmad/
│ ├── bmgd/ # Game development module
│ │ ├── agents/ # Game-specific agents
│ │ ├── workflows/ # Game-specific workflows
│ │ └── config.yaml # Module config
│ ├── bmm/ # Core method module
│ └── core/ # Core utilities
├── _bmad-output/ # Generated artifacts (created later)
└── .claude/ # IDE configuration (if using Claude Code)
```
BMGD follows four game development phases:
## Step 1: Create Your Game Brief (Preproduction)
![BMGD Workflow Overview](./workflow-overview.jpg)
Load the **Game Designer** agent in your IDE, wait for the menu, then start with your game concept.
### Phase 1: Preproduction
**What happens:** Capture your game vision and core concept.
**Workflows:**
- `brainstorm-game` - Guided ideation with game-specific techniques
- `create-game-brief` - Document vision, market, pillars, and fundamentals
**Output:** Game Brief document
### Phase 2: Design
**What happens:** Detail your game's mechanics, systems, and (optionally) narrative.
**Workflows:**
- `create-gdd` - Create comprehensive Game Design Document
- `narrative` - Create Narrative Design Document (for story-driven games)
**Output:** GDD (and Narrative Design document if applicable)
### Phase 3: Technical
**What happens:** Plan how you'll build the game.
**Workflows:**
- `create-architecture` - Define engine, systems, patterns, and structure
**Output:** Game Architecture document
### Phase 4: Production
**What happens:** Build your game in sprints.
**Workflows:**
- `sprint-planning` - Plan and track sprints
- `sprint-status` - View progress and get recommendations
- `create-story` - Create implementable stories
- `dev-story` - Implement stories
- `code-review` - Quality assurance
- `retrospective` - Learn and improve after epics
**Output:** Working game code
---
## Your First Game Project
### Step 1: Start with Brainstorming (Optional)
### Optional: Brainstorm First
If you have a vague idea and want help developing it:
```
You: brainstorm-game
Agent: [Guides you through game-specific ideation techniques]
Run brainstorm-game
```
### Step 2: Create Your Game Brief
The agent guides you through game-specific ideation techniques to refine your concept.
Capture your game's core vision:
### Create the Game Brief
```
You: create-game-brief
Agent: [Walks you through game concept, pillars, market, and fundamentals]
Run create-game-brief
```
**Output:** `{output_folder}/game-brief.md`
The Game Designer walks you through:
- **Game concept** — Core idea and unique selling points
- **Design pillars** — The 3-5 principles that guide all decisions
- **Target market** — Who plays this game?
- **Fundamentals** — Platform, genre, scope, team size
### Step 3: Create Your GDD
When complete, you'll have `game-brief.md` in your `_bmad-output/` folder.
Detail your game's design:
:::warning[Fresh Chats]
Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
:::
## Step 2: Design Your Game
With your Game Brief complete, detail your game's design.
### Create the GDD
**Start a fresh chat** with the **Game Designer** agent.
```
You: create-gdd
Agent: [Guides you through mechanics, systems, and game-type-specific sections]
Run create-gdd
```
**Output:** `{output_folder}/gdd.md` (or sharded into `{output_folder}/gdd/`)
The agent guides you through mechanics, systems, and game-type-specific sections. BMGD offers 24 game type templates that provide genre-specific structure.
### Step 4: Add Narrative Design (If Story-Driven)
When complete, you'll have `gdd.md` (or sharded into `gdd/` for large documents).
For games with significant story:
:::info[Narrative Design (Optional)]
For story-driven games, start a fresh chat and run `narrative` to create a Narrative Design Document covering story, characters, world, and dialogue.
:::
:::tip[Check Your Status]
Unsure what's next? Load any agent and run `workflow-status`. It tells you the next recommended workflow.
:::
## Step 3: Plan Your Architecture
**Start a fresh chat** with the **Game Architect** agent.
```
You: narrative
Agent: [Facilitates story, characters, world, and dialogue design]
Run create-architecture
```
**Output:** `{output_folder}/narrative-design.md`
The architect guides you through:
- **Engine selection** — Unity, Unreal, Godot, custom, etc.
- **System design** — Core game systems and how they interact
- **Technical patterns** — Architecture patterns suited to your game
- **Structure** — Project organization and conventions
### Step 5: Create Architecture
When complete, you'll have `game-architecture.md`.
Plan your technical implementation:
## Step 4: Build Your Game
Once planning is complete, move to production. **Each workflow should run in a fresh chat.**
### Initialize Sprint Planning
Load the **Game Scrum Master** agent and run `sprint-planning`. This creates `sprint-status.yaml` to track all epics and stories.
### The Build Cycle
For each story, repeat this cycle with fresh chats:
| Step | Agent | Workflow | Purpose |
|------|-------|----------|---------|
| 1 | Game SM | `create-story` | Create story file from epic |
| 2 | Game Dev | `dev-story` | Implement the story |
| 3 | Game QA | `automate` | Generate tests *(optional)* |
| 4 | Game Dev | `code-review` | Quality validation *(recommended)* |
After completing all stories in an epic, load the **Game SM** and run `retrospective`.
### Quick Prototyping Alternative
For rapid iteration or indie development, load the **Game Solo Dev** agent:
- `quick-prototype` — Rapid prototyping
- `quick-dev` — Flexible development without full sprint structure
## What You've Accomplished
You've learned the foundation of building games with BMad:
- Installed the BMGD module
- Created a Game Brief capturing your vision
- Detailed your design in a GDD
- Planned your technical architecture
- Understood the build cycle for implementation
Your project now has:
```
You: create-architecture
Agent: [Guides engine selection, system design, and technical decisions]
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── game-brief.md # Your game vision
│ ├── gdd.md # Game Design Document
│ ├── narrative-design.md # Story design (if applicable)
│ ├── game-architecture.md # Technical decisions
│ ├── epics/ # Epic and story files
│ └── sprint-status.yaml # Sprint tracking
└── ...
```
**Output:** `{output_folder}/game-architecture.md`
## Quick Reference
### Step 6: Start Building
| Command | Agent | Purpose |
|---------|-------|---------|
| `*brainstorm-game` | Game Designer | Guided game ideation |
| `*create-game-brief` | Game Designer | Create Game Brief |
| `*create-gdd` | Game Designer | Create Game Design Document |
| `*narrative` | Game Designer | Create Narrative Design |
| `*create-architecture` | Game Architect | Create game architecture |
| `*sprint-planning` | Game SM | Initialize sprint tracking |
| `*create-story` | Game SM | Create a story file |
| `*dev-story` | Game Dev | Implement a story |
| `*code-review` | Game Dev | Review implemented code |
| `*workflow-status` | Any | Check progress and next steps |
Begin sprint-based development:
## Common Questions
```
You: sprint-planning
Agent: [Sets up sprint tracking and epic management]
```
**Do I need to create all documents?**
At minimum, create a Game Brief and GDD. Architecture is highly recommended. Narrative Design is only needed for story-driven games.
---
**Can I use the Game Solo Dev for everything?**
Yes, for smaller projects or rapid prototyping. For larger games, the specialized agents provide more thorough guidance.
## Choosing Your Agent
**What game types are supported?**
BMGD includes 24 game type templates (RPG, platformer, puzzle, strategy, etc.) that provide genre-specific GDD sections.
BMGD provides six specialized agents:
**Can I change my design later?**
Yes. Documents are living artifacts—return to update them as your vision evolves. The SM agent has `correct-course` for scope changes.
| Agent | Icon | When to Use |
| --------------------- | ---- | ----------------------------------------- |
| **Game Designer** | 🎲 | Brainstorming, Game Brief, GDD, Narrative |
| **Game Architect** | 🏛️ | Architecture, technical decisions |
| **Game Developer** | 🕹️ | Implementation, code reviews |
| **Game Scrum Master** | 🎯 | Sprint planning, story management |
| **Game QA** | 🧪 | Test framework, test design, automation |
| **Game Solo Dev** | 🎮 | Quick prototyping, indie development |
## Getting Help
### Typical Flow
- **During workflows** — Agents guide you with questions and explanations
- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#general-dev, #bugs-issues)
- **Documentation** — [BMGD Workflow Reference](../../reference/workflows/bmgd-workflows.md)
- **Video tutorials** — [BMad Code YouTube](https://www.youtube.com/@BMadCode)
1. **Game Designer** (Phases 1-2): Brainstorm → Brief → GDD → Narrative
2. **Game Architect** (Phase 3): Architecture
3. **Game Scrum Master** (Phase 4): Sprint planning, story creation
4. **Game Developer** (Phase 4): Implementation, code reviews
## Key Takeaways
---
:::tip[Remember These]
- **Always use fresh chats** — Load agents in new chats for each workflow
- **Game Brief first** — It informs everything that follows
- **Use game type templates** — 24 templates provide genre-specific GDD structure
- **Documents evolve** — Return to update them as your vision grows
- **Solo Dev for speed** — Use Game Solo Dev for rapid prototyping
:::
## Quick Command Reference
### Phase 1: Preproduction
- `brainstorm-game` - Ideation session
- `create-game-brief` - Create Game Brief
### Phase 2: Design
- `create-gdd` - Create GDD
- `narrative` - Create Narrative Design
### Phase 3: Technical
- `create-architecture` - Create Architecture
### Phase 4: Production
- `sprint-planning` - Plan sprints
- `sprint-status` - View progress and recommendations
- `create-story` - Create story
- `dev-story` - Implement story
- `code-review` - Review code
- `retrospective` - Team retrospective
- `correct-course` - Handle sprint changes
### Quick-Flow (Fast-Track)
- `quick-prototype` - Rapid prototyping (IDE only)
- `quick-dev` - Flexible development (IDE only)
### Utility
- `workflow-status` - Check project status
- `party-mode` - Multi-agent collaboration
- `advanced-elicitation` - Deep exploration
---
## Tips for Success
### 1. Start Small
Begin with a simple game concept. You can always expand later.
### 2. Use Game Type Templates
When creating your GDD, BMGD offers 24 game type templates that provide genre-specific sections.
### 3. Iterate
Documents are living artifacts. Return to update them as your vision evolves.
### 4. Trust the Process
Each workflow builds on previous outputs. The Game Brief informs the GDD, which informs the Architecture, which informs implementation.
### 5. Collaborate with Agents
Use `party-mode` to get perspectives from multiple agents when facing complex decisions.
---
## Next Steps
- **[Agents Guide](../../explanation/game-dev/agents.md)** - Learn about each agent's capabilities
- **[Workflows Guide](../../reference/workflows/bmgd-workflows.md)** - Detailed workflow reference
- **[Quick-Flow Guide](../../how-to/workflows/bmgd-quick-flow.md)** - Rapid prototyping and development
- **[Game Types Guide](../../explanation/game-dev/game-types.md)** - Understand game type templates
- **[Glossary](../../reference/glossary/index.md)** - Game development terminology
---
**Ready to start?** Chat with the **Game Designer** agent and say `brainstorm-game` or `create-game-brief`!
Ready to start? Load the **Game Designer** agent and run `create-game-brief` to capture your game vision.

2
website/docusaurus.config.js
View File

@ -151,7 +151,7 @@ const config = {
{
title: 'Documentation',
items: [
{ label: 'Tutorials', to: '/docs/tutorials/getting-started/bmad-tutorial' },
{ label: 'Tutorials', to: '/docs/tutorials/getting-started/getting-started-bmadv4' },
{ label: 'How-To Guides', to: '/docs/how-to' },
{ label: 'Concepts', to: '/docs/explanation' },
{ label: 'Reference', to: '/docs/reference' },

6
website/sidebars.js
View File

@ -18,21 +18,21 @@ const sidebars = {
{
type: 'category',
label: 'How-To Guides',
collapsed: false,
collapsed: true,
link: { type: 'doc', id: 'how-to/index' },
items: [{ type: 'autogenerated', dirName: 'how-to' }],
},
{
type: 'category',
label: 'Explanation',
collapsed: false,
collapsed: true,
link: { type: 'doc', id: 'explanation/index' },
items: [{ type: 'autogenerated', dirName: 'explanation' }],
},
{
type: 'category',
label: 'Reference',
collapsed: false,
collapsed: true,
link: { type: 'doc', id: 'reference/index' },
items: [{ type: 'autogenerated', dirName: 'reference' }],
},