opensource/BMAD-METHOD
3
0
Fork 0
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-09-24 23:10:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): Diataxis restructure + Astro/Starlight migration (#1263)

Browse Source 
* feat(docs): add Diataxis folder structure and update sidebar styling

- Create tutorials, how-to, explanation, reference directories with subdirectories
- Add index.md files for each main Diataxis section
- Update homepage with Diataxis card navigation layout
- Implement clean React Native-inspired sidebar styling
- Convert sidebar to autogenerated for both Diataxis and legacy sections
- Update docusaurus config with dark mode default and navbar changes

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(docs): migrate Phase 1 files to Diataxis structure

Move 21 files to new locations:
- Tutorials: quick-start guides, agent creation guide
- How-To: installation, customization, workflows
- Explanation: core concepts, features, game-dev, builder
- Reference: merged glossary from BMM and BMGD

Also:
- Copy images to new locations
- Update internal links via migration script (73 links updated)
- Build verified successfully

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(docs): add category labels for sidebar folders

Add _category_.json files to control display labels and position
for autogenerated sidebar categories.

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* style(docs): improve welcome page and visual styling

- Rewrite index.md with React Native-inspired welcoming layout
- Add Diataxis section cards with descriptions
- Remove sidebar separator, add spacing instead
- Increase navbar padding with responsive breakpoints
- Add rounded admonitions without left border bar
- Use system font stack for better readability
- Add lighter chevron styling in sidebar
- Constrain max-width to 1600px for wide viewports

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use baseUrl in meta tag paths for correct deployment URLs

* feat(docs): complete Phase 2 - split files and fix broken links

Phase 2 of Diataxis migration:
- Split 16 large legacy files into 42+ focused documents
- Created FAQ section with 7 topic-specific files
- Created brownfield how-to guides (3 files)
- Created workflow how-to guides (15+ files)
- Created architecture explanation files (3 files)
- Created TEA/testing explanation files
- Moved remaining legacy module files to proper Diataxis locations

Link fixes:
- Fixed ~50 broken internal links across documentation
- Updated relative paths for new file locations
- Created missing index files for installation, advanced tutorials
- Simplified TOC anchors to fix Docusaurus warnings

Cleanup:
- Removed legacy sidebar entries for deleted folders
- Deleted duplicate and empty placeholder files
- Moved workflow diagram assets to tutorials/images

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(build): use file glob instead of sidebar parsing for llms-full.txt

Replace brittle sidebar.js regex parsing with recursive file glob.
The old approach captured non-file strings like 'autogenerated' and
category labels, resulting in only 5 files being processed.

Now correctly processes all 86+ markdown files (~95k tokens).

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(seo): use absolute URLs in AI meta tags for agent discoverability

AI web-browsing agents couldn't follow relative paths in meta tags due to
URL security restrictions. Changed llms-full.txt and llms.txt meta tag
URLs from relative (baseUrl) to absolute (urlParts.origin + baseUrl).

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor(docs): recategorize misplaced files per Diataxis analysis

Phase 2.5 categorization fixes based on post-migration analysis:

Moved to correct Diataxis categories:
- tutorials/installation.md → deleted (duplicate of how-to/install-bmad.md)
- tutorials/brownfield-onboarding.md → how-to/brownfield/index.md
- reference/faq/* (8 files) → explanation/faq/
- reference/agents/barry-quick-flow.md → explanation/agents/
- reference/agents/bmgd-agents.md → explanation/game-dev/agents.md

Created:
- explanation/agents/index.md

Fixed all broken internal links (14 total)

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(docs): add Getting Started tutorial and simplify build script

- Add comprehensive Getting Started tutorial with installation as Step 1
- Simplify build-docs.js to read directly from docs/ (no consolidation)
- Remove backup/restore dance that could corrupt docs folder on build failure
- Remove ~150 lines of unused consolidation code

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(css): use fixed width layout to prevent content shifting

Apply React Native docs approach: set both width and max-width at
largest breakpoint (1400px) so content area maintains consistent
size regardless of content length. Switches to fluid 100% below
1416px breakpoint.

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor(docs): restructure tutorials with renamed entry point

- Rename index.md to bmad-tutorial.md for clearer navigation
- Remove redundant tutorials/index.md
- Update sidebar and config references

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

* feat(docs): add markdown demo page and UI refinements

- Add comprehensive markdown-demo.md for style testing
- Remove doc category links from navbar (use sidebar instead)
- Remove card buttons from welcome page
- Add dark mode styling for announcement bar
- Clean up index.md card layout

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

* refactor(docs): migrate from Docusaurus to Astro+Starlight

Replace Docusaurus with Astro and the Starlight documentation theme
for improved performance, better customization, and modern tooling.

Build pipeline changes:
- New build-docs.js orchestrates link checking, artifact generation,
  and Astro build in sequence
- Add check-doc-links.js for validating internal links and anchors
- Generate llms.txt and llms-full.txt for LLM-friendly documentation
- Create downloadable source bundles (bmad-sources.zip, bmad-prompts.zip)
- Suppress MODULE_TYPELESS_PACKAGE_JSON warning in Astro build
- Output directly to build/site for cleaner deployment

Website architecture:
- Add rehype-markdown-links.js plugin to transform .md links to routes
- Add site-url.js helper for GitHub Pages URL resolution with strict
  validation (throws on invalid GITHUB_REPOSITORY format)
- Custom Astro components: Banner, Header, MobileMenuFooter
- Symlink docs/ into website/src/content/docs for Starlight

Documentation cleanup:
- Remove Docusaurus _category_.json files (Starlight uses frontmatter)
- Convert all docs to use YAML frontmatter with title field
- Move downloads.md from website/src/pages to docs/
- Consolidate style guide and workflow diagram docs
- Add 404.md and tutorials/index.md

---------

Co-authored-by: forcetrainer <bryan@inagaki.us>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alex Verkhovsky
2026-01-07 14:42:15 +08:00
committed by GitHub
co-authored by forcetrainer Claude Opus 4.5
parent dc7a7f8c43
commit 2e16650067
134 changed files with 12848 additions and 20193 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tutorials/advanced/create-custom-agent.md
+171
View File
@@ -0,0 +1,171 @@
---
title: "Create a Custom Agent"
---
Build your own AI agent with a unique personality, specialized commands, and optional persistent memory using the BMad Builder workflow.
:::note[BMB Module]
This tutorial uses the **BMad Builder (BMB)** module. Make sure you have BMAD installed with the BMB module enabled.
:::
## What You'll Learn
- 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
:::note[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
:::
:::tip[Quick Path]
Run `create-agent` workflow → Follow the guided steps → Install your agent module → Test and iterate.
:::
## Understanding Agent Types
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.
The workflow guides you through eight steps:
| 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
:::
## 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.
:::note[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:
```
my-custom-stuff/
├── module.yaml # Contains: unitary: true
├── agents/
│ └── {agent-name}/
│ ├── {agent-name}.agent.yaml
│ └── _memory/ # Expert agents only
│ └── {sidecar-folder}/
└── workflows/ # Optional: custom workflows
```
Install using the BMAD installer, then invoke your new agent in your IDE.
## What You've Accomplished
You've created a custom AI agent with:
- 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
Your project now includes:
```
_bmad/
├── _config/
│ └── agents/
│ └── {your-agent}/ # Your agent customizations
└── {module}/
└── agents/
└── {your-agent}/
└── {your-agent}.agent.yaml
```
## Quick Reference
| 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/` |
## Common Questions
**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.
**How do I add more commands later?**
Edit the agent YAML directly or use the customization file in `_bmad/_config/agents/`. Then rebuild.
**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/`:
- [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)
## Getting Help
- **[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
- **[What Are Agents](../../explanation/core-concepts/what-are-agents.md)** - Deep technical details on agent types
- **[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
:::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
:::
docs/tutorials/getting-started/getting-started-bmadv4.md
+247
View File
@@ -0,0 +1,247 @@
---
title: "Getting Started with BMad v4"
description: Install BMad and create your first planning document
---
Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
:::note[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
:::note[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.
:::caution[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.
:::note[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.
docs/tutorials/getting-started/getting-started-bmadv6.md
+247
View File
@@ -0,0 +1,247 @@
---
title: "Getting Started with BMad v6 Alpha"
description: Install BMad v6 Alpha and build your first project
---
Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
:::caution[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](./getting-started-bmadv4.md) instead.
:::
## What You'll Learn
- 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
:::note[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`
**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 | Brainstorming, research, product brief *(optional)* |
| 2 | Planning | Create requirements (PRD or tech-spec) |
| 3 | Solutioning | Design architecture *(BMad Method/Enterprise only)* |
| 4 | Implementation | Build epic by epic, story by story |
![BMad Method Workflow - Standard Greenfield](./images/workflow-method-greenfield.svg)
*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.
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, wait for the menu, then run `workflow-init`.
:::note[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.
:::
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.
:::caution[Fresh Chats]
Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
:::
## 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.
:::
### Phase 1: Analysis (Optional)
All workflows in this phase are optional:
- **brainstorm-project** — Guided ideation
- **research** — Market and technical research
- **product-brief** — Recommended foundation document
### Phase 2: Planning (Required)
**For BMad Method and Enterprise tracks:**
1. Load the **PM agent** in a new chat
2. Run the PRD workflow: `*prd`
3. Output: `PRD.md`
**For Quick Flow track:**
- Use `tech-spec` instead of PRD, then skip to implementation
:::note[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 (BMad Method/Enterprise)
**Create Architecture**
1. Load the **Architect agent** in a new chat
2. Run `create-architecture`
3. Output: Architecture document with technical decisions
**Create Epics and Stories**
:::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
2. Run `create-epics-and-stories`
3. The workflow uses both PRD and Architecture to create technically-informed stories
**Implementation Readiness Check** *(Highly Recommended)*
1. Load the **Architect agent** in a new chat
2. Run `implementation-readiness`
3. Validates cohesion across all planning documents
## Step 3: Build Your Project
Once planning is complete, move to implementation. **Each workflow should run in a fresh chat.**
### 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 | TEA | `automate` | Generate guardrail tests *(optional)* |
| 4 | 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, Epics & Stories)
- 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
│ ├── epics/ # Epic and story files
│ ├── bmm-workflow-status.yaml # Phase progress tracking
│ └── sprint-status.yaml # Sprint 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 |
| `*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
**Do I always need architecture?**
Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
**Can I change my plan later?**
Yes. The SM agent has a `correct-course` workflow for handling scope changes.
**What if I want to brainstorm first?**
Load the Analyst agent and run `brainstorm-project` before `workflow-init`.
**Can I skip workflow-init and workflow-status?**
Yes, once you learn the flow. Use the Quick Reference to go directly to needed workflows.
## Getting Help
- **During workflows** — Agents guide you with questions and explanations
- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#general-dev, #bugs-issues)
- **Documentation** — [BMM Workflow Reference](../../reference/workflows/index.md)
- **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.
docs/tutorials/getting-started/images/workflow-method-greenfield.excalidraw
+5034
View File
File diff suppressed because it is too large Load Diff
docs/tutorials/getting-started/images/workflow-method-greenfield.svg
+4
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 87 KiB

docs/tutorials/getting-started/images/workflow-overview.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 200 KiB

docs/tutorials/getting-started/quick-start-bmgd.md
+260
View File
@@ -0,0 +1,260 @@
---
title: "Getting Started with BMad Game Development"
description: Build games with BMad's Game Development Module
---
Build games faster using AI-powered workflows with specialized game development agents that guide you through preproduction, design, architecture, and implementation.
:::note[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.
:::
## What You'll Learn
- 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
:::note[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
If you haven't installed BMad yet:
```bash
npx bmad-method install
```
Or add BMGD to an existing installation:
```bash
npx bmad-method install --add-module bmgd
```
Verify your installation:
```
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)
```
## Step 1: Create Your Game Brief (Preproduction)
Load the **Game Designer** agent in your IDE, wait for the menu, then start with your game concept.
### Optional: Brainstorm First
If you have a vague idea and want help developing it:
```
Run brainstorm-game
```
The agent guides you through game-specific ideation techniques to refine your concept.
### Create the Game Brief
```
Run create-game-brief
```
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
When complete, you'll have `game-brief.md` in your `_bmad-output/` folder.
:::caution[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.
```
Run create-gdd
```
The agent guides you through mechanics, systems, and game-type-specific sections. BMGD offers 24 game type templates that provide genre-specific structure.
When complete, you'll have `gdd.md` (or sharded into `gdd/` for large documents).
:::note[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.
```
Run create-architecture
```
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
When complete, you'll have `game-architecture.md`.
## 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:
```
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
└── ...
```
## Quick Reference
| 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 |
## Common Questions
**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.
**What game types are supported?**
BMGD includes 24 game type templates (RPG, platformer, puzzle, strategy, etc.) that provide genre-specific GDD sections.
**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.
## Getting Help
- **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)
## 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
:::
Ready to start? Load the **Game Designer** agent and run `create-game-brief` to capture your game vision.
docs/tutorials/getting-started/workflow-overview.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 200 KiB

docs/tutorials/index.md
+21
View File
@@ -0,0 +1,21 @@
---
title: "Tutorials"
---
Learning-oriented guides that walk you through building something real with BMad. Perfect for getting hands-on experience.
## Getting Started
Start your journey with BMad by choosing a version that fits your needs:
- [Get Started with v4 (Stable)](./getting-started/getting-started-bmadv4.md) — Production-ready version with battle-tested workflows
- [Try v6 (Alpha)](./getting-started/getting-started-bmadv6.md) — Latest features, still in active development
## First Project
Your first end-to-end project with BMad.
## Advanced
More complex scenarios and advanced patterns.