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

merge: sync with upstream/main (v6.0.0-Beta.8) 

Merge 217 upstream commits covering:
- Module restructuring: src/modules/ flattened to src/
- BMB, BMGD, CIS modules moved to separate repos
- Installer migrated from inquirer to @clack/prompts
- Workflow simplification and new naming conventions
- Docusaurus to Astro/Starlight docs migration
- CodeRabbit AI review integration
- Cross-file reference validator
- Non-interactive install support
- Kiro IDE support

Conflict resolutions:
- sm.agent.yaml: kept fork's EE/EC/UV/CR menu items, took upstream's CC description
- uat-validator.agent.yaml: moved to src/bmm/agents/, removed unsupported webskip field

Path updates for new structure:
- scripts/*.sh: src/modules/bmm/ → src/bmm/
- CLAUDE.md: updated module paths and removed references to extracted modules
- docs: fixed broken links, added Astro frontmatter to fork docs files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Caleb 2026-02-10 14:09:21 -06:00
parent 87223692d3 0659aac02c
commit 03e0cc63d5
1089 changed files with 29702 additions and 147237 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

271
.augment/code_review_guidelines.yaml Normal file
View File

@ -0,0 +1,271 @@
# Augment Code Review Guidelines for BMAD-METHOD
# https://docs.augmentcode.com/codereview/overview
# Focus: Workflow validation and quality
file_paths_to_ignore:
# --- Shared baseline: tool configs ---
- ".coderabbit.yaml"
- ".augment/**"
- "eslint.config.mjs"
# --- Shared baseline: build output ---
- "dist/**"
- "build/**"
- "coverage/**"
# --- Shared baseline: vendored/generated ---
- "node_modules/**"
- "**/*.min.js"
- "**/*.generated.*"
- "**/*.bundle.md"
# --- Shared baseline: package metadata ---
- "package-lock.json"
# --- Shared baseline: binary/media ---
- "*.png"
- "*.jpg"
- "*.svg"
# --- Shared baseline: test fixtures ---
- "test/fixtures/**"
- "test/template-test-generator/**"
- "tools/template-test-generator/test-scenarios/**"
# --- Shared baseline: non-project dirs ---
- "_bmad*/**"
- "website/**"
- "z*/**"
- "sample-project/**"
- "test-project-install/**"
# --- Shared baseline: AI assistant dirs ---
- ".claude/**"
- ".codex/**"
- ".agent/**"
- ".agentvibes/**"
- ".kiro/**"
- ".roo/**"
- ".github/chatmodes/**"
# --- Shared baseline: build temp ---
- ".bundler-temp/**"
# --- Shared baseline: generated reports ---
- "**/validation-report-*.md"
- "CHANGELOG.md"
areas:
# ============================================
# WORKFLOW STRUCTURE RULES
# ============================================
workflow_structure:
description: "Workflow folder organization and required components"
globs:
- "src/**/workflows/**"
rules:
- id: "workflow_entry_point_required"
description: "Every workflow folder must have workflow.yaml, workflow.md, or workflow.xml as entry point"
severity: "high"
- id: "sharded_workflow_steps_folder"
description: "Sharded workflows (using workflow.md) must have steps/ folder with numbered files (step-01-*.md, step-02-*.md)"
severity: "high"
- id: "standard_workflow_instructions"
description: "Standard workflows using workflow.yaml must include instructions.md for execution guidance"
severity: "medium"
- id: "workflow_step_limit"
description: "Workflows should have 5-10 steps maximum to prevent context loss in LLM execution"
severity: "medium"
# ============================================
# WORKFLOW ENTRY FILE RULES
# ============================================
workflow_definitions:
description: "Workflow entry files (workflow.yaml, workflow.md, workflow.xml)"
globs:
- "src/**/workflows/**/workflow.yaml"
- "src/**/workflows/**/workflow.md"
- "src/**/workflows/**/workflow.xml"
rules:
- id: "workflow_name_required"
description: "Workflow entry files must define 'name' field in frontmatter or root element"
severity: "high"
- id: "workflow_description_required"
description: "Workflow entry files must include 'description' explaining the workflow's purpose"
severity: "high"
- id: "workflow_config_source"
description: "Workflows should reference config_source for variable resolution (e.g., {project-root}/_bmad/module/config.yaml)"
severity: "medium"
- id: "workflow_installed_path"
description: "Workflows should define installed_path for relative file references within the workflow"
severity: "medium"
- id: "valid_step_references"
description: "Step file references in workflow entry must point to existing files"
severity: "high"
# ============================================
# SHARDED WORKFLOW STEP RULES
# ============================================
workflow_steps:
description: "Individual step files in sharded workflows"
globs:
- "src/**/workflows/**/steps/step-*.md"
rules:
- id: "step_goal_required"
description: "Each step must clearly state its goal (## STEP GOAL, ## YOUR TASK, or step n='X' goal='...')"
severity: "high"
- id: "step_mandatory_rules"
description: "Step files should include MANDATORY EXECUTION RULES section with universal agent behavior rules"
severity: "medium"
- id: "step_context_boundaries"
description: "Step files should define CONTEXT BOUNDARIES explaining available context and limits"
severity: "medium"
- id: "step_success_metrics"
description: "Step files should include SUCCESS METRICS section with ✅ checkmarks for validation criteria"
severity: "medium"
- id: "step_failure_modes"
description: "Step files should include FAILURE MODES section with ❌ marks for anti-patterns to avoid"
severity: "medium"
- id: "step_next_step_reference"
description: "Step files should reference the next step file path for sequential execution"
severity: "medium"
- id: "step_no_forward_loading"
description: "Steps must NOT load future step files until current step completes - just-in-time loading only"
severity: "high"
- id: "valid_file_references"
description: "File path references using {variable}/filename.md must point to existing files"
severity: "high"
- id: "step_naming"
description: "Step files must be named step-NN-description.md (e.g., step-01-init.md, step-02-context.md)"
severity: "medium"
- id: "halt_before_menu"
description: "Steps presenting user menus ([C] Continue, [a] Advanced, etc.) must HALT and wait for response"
severity: "high"
# ============================================
# XML WORKFLOW/TASK RULES
# ============================================
xml_workflows:
description: "XML-based workflows and tasks"
globs:
- "src/**/workflows/**/*.xml"
- "src/**/tasks/**/*.xml"
rules:
- id: "xml_task_id_required"
description: "XML tasks must have unique 'id' attribute on root task element"
severity: "high"
- id: "xml_llm_instructions"
description: "XML workflows should include <llm> section with critical execution instructions for the agent"
severity: "medium"
- id: "xml_step_numbering"
description: "XML steps should use n='X' attribute for sequential numbering"
severity: "medium"
- id: "xml_action_tags"
description: "Use <action> for required actions, <ask> for user input (must HALT), <goto> for jumps, <check if='...'> for conditionals"
severity: "medium"
- id: "xml_ask_must_halt"
description: "<ask> tags require agent to HALT and wait for user response before continuing"
severity: "high"
# ============================================
# WORKFLOW CONTENT QUALITY
# ============================================
workflow_content:
description: "Content quality and consistency rules for all workflow files"
globs:
- "src/**/workflows/**/*.md"
- "src/**/workflows/**/*.yaml"
rules:
- id: "communication_language_variable"
description: "Workflows should use {communication_language} variable for agent output language consistency"
severity: "low"
- id: "path_placeholders_required"
description: "Use path placeholders (e.g. {project-root}, {installed_path}, {output_folder}) instead of hardcoded paths"
severity: "medium"
- id: "no_time_estimates"
description: "Workflows should NOT include time estimates - AI development speed varies significantly"
severity: "low"
- id: "facilitator_not_generator"
description: "Workflow agents should act as facilitators (guide user input) not content generators (create without input)"
severity: "medium"
- id: "no_skip_optimization"
description: "Workflows must execute steps sequentially - no skipping or 'optimizing' step order"
severity: "high"
# ============================================
# AGENT DEFINITIONS
# ============================================
agent_definitions:
description: "Agent YAML configuration files"
globs:
- "src/**/*.agent.yaml"
rules:
- id: "agent_metadata_required"
description: "Agent files must have metadata section with id, name, title, icon, and module"
severity: "high"
- id: "agent_persona_required"
description: "Agent files must define persona with role, identity, communication_style, and principles"
severity: "high"
- id: "agent_menu_valid_workflows"
description: "Menu triggers must reference valid workflow paths that exist"
severity: "high"
# ============================================
# TEMPLATES
# ============================================
templates:
description: "Template files for workflow outputs"
globs:
- "src/**/template*.md"
- "src/**/templates/**/*.md"
rules:
- id: "placeholder_syntax"
description: "Use {variable_name} or {{variable_name}} syntax consistently for placeholders"
severity: "medium"
- id: "template_sections_marked"
description: "Template sections that need generation should be clearly marked (e.g., <!-- GENERATE: section_name -->)"
severity: "low"
# ============================================
# DOCUMENTATION
# ============================================
documentation:
description: "Documentation files"
globs:
- "docs/**/*.md"
- "README.md"
- "CONTRIBUTING.md"
rules:
- id: "valid_internal_links"
description: "Internal markdown links must point to existing files"
severity: "medium"
# ============================================
# BUILD TOOLS
# ============================================
build_tools:
description: "Build scripts and tooling"
globs:
- "tools/**"
rules:
- id: "script_error_handling"
description: "Scripts should handle errors gracefully with proper exit codes"
severity: "medium"

178
.claude/skills/changelog-social/SKILL.md Normal file
View File

@ -0,0 +1,178 @@
---
name: bmad-os-changelog-social
description: Generate social media announcements for Discord, Twitter, and LinkedIn from the latest changelog entry. Use when user asks to create release announcements, social posts, or share changelog updates. Reads CHANGELOG.md in current working directory. Reference examples/ for tone and format.
disable-model-invocation: true
---
# Changelog Social
Generate engaging social media announcements from changelog entries.
## Workflow
### Step 1: Extract Changelog Entry
Read `./CHANGELOG.md` and extract the latest version entry. The changelog follows this format:
```markdown
## [VERSION]
### 🎁 Features
* **Title** — Description
### 🐛 Bug Fixes
* **Title** — Description
### 📚 Documentation
* **Title** — Description
### 🔧 Maintenance
* **Title** — Description
```
Parse:
- **Version number** (e.g., `6.0.0-Beta.5`)
- **Features** - New functionality, enhancements
- **Bug Fixes** - Fixes users will care about
- **Documentation** - New or improved docs
- **Maintenance** - Dependency updates, tooling improvements
### Step 2: Get Git Contributors
Use git log to find contributors since the previous version. Get commits between the current version tag and the previous one:
```bash
# Find the previous version tag first
git tag --sort=-version:refname | head -5
# Get commits between versions with PR numbers and authors
git log <previous-tag>..<current-tag> --pretty=format:"%h|%s|%an" --grep="#"
```
Extract PR numbers from commit messages that contain `#` followed by digits. Compile unique contributors.
### Step 3: Generate Discord Announcement
**Limit: 2,000 characters per message.** Split into multiple messages if needed.
Use this template style:
```markdown
🚀 **BMad vVERSION RELEASED!**
🎉 [Brief hype sentence]
🪥 **KEY HIGHLIGHT** - [One-line summary]
🎯 **CATEGORY NAME**
• Feature one - brief description
• Feature two - brief description
• Coming soon: Future teaser
🔧 **ANOTHER CATEGORY**
• Fix or feature
• Another item
📚 **DOCS OR OTHER**
• Item
• Item with link
🌟 **COMMUNITY PHILOSOPHY** (optional - include for major releases)
• Everything is FREE - No paywalls
• Knowledge shared, not sold
📊 **STATS**
X commits | Y PRs merged | Z files changed
🙏 **CONTRIBUTORS**
@username1 (X PRs!), @username2 (Y PRs!)
@username3, @username4, username5 + dependabot 🛡️
Community-driven FTW! 🌟
📦 **INSTALL:**
`npx bmad-method@VERSION install`
⭐ **SUPPORT US:**
🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
📺 YouTube: youtube.com/@BMadCode
☕ Donate: buymeacoffee.com/bmad
🔥 **Next version tease!**
```
**Content Strategy:**
- Focus on **user impact** - what's better for them?
- Highlight **annoying bugs fixed** that frustrated users
- Show **new capabilities** that enable workflows
- Keep it **punchy** - use emojis and short bullets
- Add **personality** - excitement, humor, gratitude
### Step 4: Generate Twitter Post
**Limit: 25,000 characters per tweet (Premium).** With Premium, use a single comprehensive post matching the Discord style (minus Discord-specific formatting). Aim for 1,500-3,000 characters for better engagement.
**Threads are optional** — only use for truly massive releases where you want multiple engagement points.
See `examples/twitter-example.md` for the single-post Premium format.
## Content Selection Guidelines
**Include:**
- New features that change workflows
- Bug fixes for annoying/blocking issues
- Documentation that helps users
- Performance improvements
- New agents or workflows
- Breaking changes (call out clearly)
**Skip/Minimize:**
- Internal refactoring
- Dependency updates (unless user-facing)
- Test improvements
- Minor style fixes
**Emphasize:**
- "Finally fixed" issues
- "Faster" operations
- "Easier" workflows
- "Now supports" capabilities
## Examples
Reference example posts in `examples/` for tone and formatting guidance:
- **discord-example.md** — Full Discord announcement with emojis, sections, contributor shout-outs
- **twitter-example.md** — Twitter thread format (5 tweets max for major releases)
- **linkedin-example.md** — Professional post for major/minor releases with significant features
**When to use LinkedIn:**
- Major version releases (e.g., v6.0.0 Beta, v7.0.0)
- Minor releases with exceptional new features
- Community milestone announcements
Read the appropriate example file before generating to match the established style and voice.
## Output Format
**CRITICAL: ALWAYS write to files** - Create files in `_bmad-output/social/` directory:
1. `{repo-name}-discord-{version}.md` - Discord announcement
2. `{repo-name}-twitter-{version}.md` - Twitter post
3. `{repo-name}-linkedin-{version}.md` - LinkedIn post (if applicable)
Also present a preview in the chat:
```markdown
## Discord Announcement
[paste Discord content here]
## Twitter Post
[paste Twitter content here]
```
Files created:
- `_bmad-output/social/{filename}`
Offer to make adjustments if the user wants different emphasis, tone, or content.

53
.claude/skills/changelog-social/examples/discord-example.md Normal file
View File

@ -0,0 +1,53 @@
🚀 **BMad v6.0.0-alpha.23 RELEASED!**
🎉 Huge update - almost beta!
🪟 **WINDOWS INSTALLER FIXED** - Menu arrows issue should be fixed! CRLF & ESM problems resolved.
🎯 **PRD WORKFLOWS IMPROVED**
• Validation & Edit workflows added!
• PRD Cohesion check ensures document flows beautifully
• Coming soon: Use of subprocess optimization (context saved!)
• Coming soon: Final format polish step in all workflows - Human consumption OR hyper-optimized LLM condensed initially!
🔧 **WORKFLOW CREATOR & VALIDATOR**
• Subprocess support for advanced optimization
• Path violation checks ensure integrity
• Beyond error checking - offers optimization & flow suggestions!
📚 **NEW DOCS SITE** - docs.bmad-method.org
• Diataxis framework: Tutorials, How-To, Explanations, References
• Current docs still being revised
• Tutorials, blogs & explainers coming soon!
💡 **BRAINSTORMING REVOLUTION**
• 100+ idea goal (quantity-first!)
• Anti-bias protocol (pivot every 10 ideas)
• Chain-of-thought + simulated temperature prompts
• Coming soon: SubProcessing (on-the-fly sub agents)
🌟 **COMMUNITY PHILOSOPHY**
• Everything is FREE - No paywalls, no gated content
• Knowledge shared, not sold
• No premium tiers - full access to our ideas
📊 **27 commits | 217 links converted | 42+ docs created**
🙏 **17 Community PR Authors in this release!**
@lum (6 PRs!), @q00 (3 PRs!), @phil (2 PRs!)
@mike, @alex, @ramiz, @sjennings + dependabot 🛡️
Community-driven FTW! 🌟
📦 **INSTALL ALPHA:**
`npx bmad-method install`
⭐ **SUPPORT US:**
🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
📺 YouTube: youtube.com/@BMadCode
🎤 **SPEAKING & MEDIA**
Available for conferences, podcasts, media appearances!
Topics: AI-Native Organizations (Any Industry), BMad Method
DM on Discord for inquiries!
🔥 **V6 Beta is DAYS away!** January 22nd ETA - new features such as xyz and abc bug fixes!

49
.claude/skills/changelog-social/examples/linkedin-example.md Normal file
View File

@ -0,0 +1,49 @@
🚀 **Announcing BMad Method v6.0.0 Beta - AI-Native Agile Development Framework**
I'm excited to share that BMad Method, the open-source AI-driven agile development framework, is entering Beta! After 27 alpha releases and countless community contributions, we're approaching a major milestone.
**What's New in v6.0.0-alpha.23**
🪟 **Windows Compatibility Fixed**
We've resolved the installer issues that affected Windows users. The menu arrows problem, CRLF handling, and ESM compatibility are all resolved.
🎯 **Enhanced PRD Workflows**
Our Product Requirements Document workflows now include validation and editing capabilities, with a new cohesion check that ensures your documents flow beautifully. Subprocess optimization is coming soon to save even more context.
🔧 **Workflow Creator & Validator**
New tools for creating and validating workflows with subprocess support, path violation checks, and optimization suggestions that go beyond simple error checking.
📚 **New Documentation Platform**
We've launched docs.bmad-method.org using the Diataxis framework - providing clear separation between tutorials, how-to guides, explanations, and references. Our documentation is being continuously revised and expanded.
💡 **Brainstorming Revolution**
Our brainstorming workflows now use research-backed techniques: 100+ idea goals, anti-bias protocols, chain-of-thought reasoning, and simulated temperature prompts for higher divergence.
**Our Philosophy**
Everything in BMad Method is FREE. No paywalls, no gated content, no premium tiers. We believe knowledge should be shared, not sold. This is community-driven development at its finest.
**The Stats**
- 27 commits in this release
- 217 documentation links converted
- 42+ new documents created
- 17 community PR authors contributed
**Get Started**
```
npx bmad-method@alpha install
```
**Learn More**
- GitHub: github.com/bmad-code-org/BMAD-METHOD
- YouTube: youtube.com/@BMadCode
- Docs: docs.bmad-method.org
**What's Next?**
Beta is just days away with an ETA of January 22nd. We're also available for conferences, podcasts, and media appearances to discuss AI-Native Organizations and the BMad Method.
Have you tried BMad Method yet? I'd love to hear about your experience in the comments!
#AI #SoftwareDevelopment #Agile #OpenSource #DevTools #LLM #AgentEngineering

55
.claude/skills/changelog-social/examples/twitter-example.md Normal file
View File

@ -0,0 +1,55 @@
🚀 **BMad v6.0.0-alpha.23 RELEASED!**
Huge update - we're almost at Beta! 🎉
🪟 **WINDOWS INSTALLER FIXED** - Menu arrows issue should be fixed! CRLF & ESM problems resolved.
🎯 **PRD WORKFLOWS IMPROVED**
• Validation & Edit workflows added!
• PRD Cohesion check ensures document flows beautifully
• Coming soon: Subprocess optimization (context saved!)
• Coming soon: Final format polish step in all workflows
🔧 **WORKFLOW CREATOR & VALIDATOR**
• Subprocess support for advanced optimization
• Path violation checks ensure integrity
• Beyond error checking - offers optimization & flow suggestions!
📚 **NEW DOCS SITE** - docs.bmad-method.org
• Diataxis framework: Tutorials, How-To, Explanations, References
• Current docs still being revised
• Tutorials, blogs & explainers coming soon!
💡 **BRAINSTORMING REVOLUTION**
• 100+ idea goal (quantity-first!)
• Anti-bias protocol (pivot every 10 ideas)
• Chain-of-thought + simulated temperature prompts
• Coming soon: SubProcessing (on-the-fly sub agents)
🌟 **COMMUNITY PHILOSOPHY**
• Everything is FREE - No paywalls, no gated content
• Knowledge shared, not sold
• No premium tiers - full access to our ideas
📊 **27 commits | 217 links converted | 42+ docs created**
🙏 **17 Community PR Authors in this release!**
@lum (6 PRs!), @q00 (3 PRs!), @phil (2 PRs!)
@mike, @alex, @ramiz, @sjennings + dependabot 🛡️
Community-driven FTW! 🌟
📦 **INSTALL ALPHA:**
`npx bmad-method install`
⭐ **SUPPORT US:**
🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
📺 YouTube: youtube.com/@BMadCode
🎤 **SPEAKING & MEDIA**
Available for conferences, podcasts, media appearances!
Topics: AI-Native Organizations (Any Industry), BMad Method
DM on Discord for inquiries!
🔥 **V6 Beta is DAYS away!** January 22nd ETA!
#AI #DevTools #Agile #OpenSource #LLM #AgentEngineering

7
.claude/skills/draft-changelog/SKILL.md Normal file
View File

@ -0,0 +1,7 @@
---
name: bmad-os-draft-changelog
description: Analyzes changes since last release and updates CHANGELOG.md ONLY. Does NOT trigger releases.
disable-model-invocation: true
---
Read `prompts/instructions.md` and execute.

82
.claude/skills/draft-changelog/prompts/instructions.md Normal file
View File

@ -0,0 +1,82 @@
# Draft Changelog Execution
## ⚠️ IMPORTANT - READ FIRST
**This skill ONLY updates CHANGELOG.md. That is its entire purpose.**
- **DO** update CHANGELOG.md with the new version entry
- **DO** present the draft for user review before editing
- **DO NOT** trigger any GitHub release workflows
- **DO NOT** run any other skills or workflows automatically
- **DO NOT** make any commits
After the changelog is complete, you may suggest the user can run `/release-module` if they want to proceed with the actual release — but NEVER trigger it yourself.
## Input
Project path (or run from project root)
## Step 1: Identify Current State
- Get the latest released tag
- Get current version
- Verify there are commits since the last release
## Step 2: Launch Explore Agent
Use `thoroughness: "very thorough"` to analyze all changes since the last release tag.
**Key: For each merge commit, look up the merged PR/issue that was closed.**
- Use `gh pr view` or git commit body to find the PR number
- Read the PR description and comments to understand full context
- Don't rely solely on commit merge messages - they lack context
**Analyze:**
1. **All merges/commits** since the last tag
2. **For each merge, read the original PR/issue** that was closed
3. **Files changed** with statistics
4. **Categorize changes:**
- 🎁 **Features** - New functionality, new agents, new workflows
- 🐛 **Bug Fixes** - Fixed bugs, corrected issues
- ♻️ **Refactoring** - Code improvements, reorganization
- 📚 **Documentation** - Docs updates, README changes
- 🔧 **Maintenance** - Dependency updates, tooling, infrastructure
- 💥 **Breaking Changes** - Changes that may affect users
**Provide:**
- Comprehensive summary of ALL changes with PR context
- Categorization of each change
- Identification of breaking changes
- Significance assessment (major/minor/trivial)
## Step 3: Generate Draft Changelog
Format:
```markdown
## v0.X.X - [Date]
* [Change 1 - categorized by type]
* [Change 2]
```
Guidelines:
- Present tense ("Fix bug" not "Fixed bug")
- Most significant changes first
- Group related changes
- Clear, concise language
- For breaking changes, clearly indicate impact
## Step 4: Present Draft & Update CHANGELOG.md
Show the draft with current version, last tag, commit count, and options to edit/retry.
When user accepts:
1. Update CHANGELOG.md with the new entry (insert at top, after `# Changelog` header)
2. STOP. That's it. You're done.
You may optionally suggest: *"When ready, you can run `/release-module` to create the actual release."*
**DO NOT:**
- Trigger any GitHub workflows
- Run any other skills
- Make any commits
- Do anything beyond updating CHANGELOG.md

14
.claude/skills/gh-triage/README.md Normal file
View File

@ -0,0 +1,14 @@
# gh-triage
Fetches all GitHub issues via gh CLI and uses AI agents to deeply analyze, cluster, and prioritize issues.
## Usage
Run from within any BMad Method repository to triage issues.
## What It Does
1. Fetches all open issues via `gh issue list`
2. Splits issues into batches
3. Launches parallel agents to analyze each batch
4. Generates comprehensive triage report to `_bmad-output/triage-reports/`

12
.claude/skills/gh-triage/SKILL.md Normal file
View File

@ -0,0 +1,12 @@
---
name: bmad-os-gh-triage
description: Fetch all GitHub issues via gh CLI and use AI agents to deeply analyze, cluster, and prioritize issues
license: MIT
disable-model-invocation: true
metadata:
author: bmad-code-org
version: "3.0.0"
compatibility: Requires gh CLI, git repository, and BMad Method with Task tool support
---
Read `prompts/instructions.md` and execute.

60
.claude/skills/gh-triage/prompts/agent-prompt.md Normal file
View File

@ -0,0 +1,60 @@
You are analyzing a batch of GitHub issues for deep understanding and triage.
**YOUR TASK:**
Read the issues in your batch and provide DEEP analysis:
1. **For EACH issue, analyze:**
- What is this ACTUALLY about? (beyond keywords)
- What component/system does it affect?
- What's the impact and severity?
- Is it a bug, feature request, or something else?
- What specific theme does it belong to?
2. **PRIORITY ASSESSMENT:**
- CRITICAL: Blocks users, security issues, data loss, broken installers
- HIGH: Major functionality broken, important features missing
- MEDIUM: Workarounds available, minor bugs, nice-to-have features
- LOW: Edge cases, cosmetic issues, questions
3. **RELATIONSHIPS:**
- Duplicates: Near-identical issues about the same problem
- Related: Issues connected by theme or root cause
- Dependencies: One issue blocks or requires another
**YOUR BATCH:**
[Paste the batch of issues here - each with number, title, body, labels]
**OUTPUT FORMAT (JSON only, no markdown):**
{
"issues": [
{
"number": 123,
"title": "issue title",
"deep_understanding": "2-3 sentences explaining what this is really about",
"affected_components": ["installer", "workflows", "docs"],
"issue_type": "bug/feature/question/tech-debt",
"priority": "CRITICAL/HIGH/MEDIUM/LOW",
"priority_rationale": "Why this priority level",
"theme": "installation/workflow/integration/docs/ide-support/etc",
"relationships": {
"duplicates_of": [456],
"related_to": [789, 101],
"blocks": [111]
}
}
],
"cross_repo_issues": [
{"number": 123, "target_repo": "bmad-builder", "reason": "about agent builder"}
],
"cleanup_candidates": [
{"number": 456, "reason": "v4-related/outdated/duplicate"}
],
"themes_found": {
"Installation Blockers": {
"count": 5,
"root_cause": "Common pattern if identifiable"
}
}
}
Return ONLY valid JSON. No explanations outside the JSON structure.

74
.claude/skills/gh-triage/prompts/instructions.md Normal file
View File

@ -0,0 +1,74 @@
# GitHub Issue Triage with AI Analysis
**CRITICAL RULES:**
- NEVER include time or effort estimates in output or recommendations
- Focus on WHAT needs to be done, not HOW LONG it takes
- Use Bash tool with gh CLI for all GitHub operations
## Execution
### Step 1: Fetch Issues
Use `gh issue list --json number,title,body,labels` to fetch all open issues.
### Step 2: Batch Creation
Split issues into batches of ~10 issues each for parallel analysis.
### Step 3: Parallel Agent Analysis
For EACH batch, use the Task tool with `subagent_type=general-purpose` to launch an agent with prompt from `prompts/agent-prompt.md`
### Step 4: Consolidate & Generate Report
After all agents complete, create a comprehensive markdown report saved to `_bmad-output/triage-reports/triage-YYYY-MM-DD.md`
## Report Format
### Executive Summary
- Total issues analyzed
- Issue count by priority (CRITICAL, HIGH, MEDIUM, LOW)
- Major themes discovered
- Top 5 critical issues requiring immediate attention
### Critical Issues (CRITICAL Priority)
For each CRITICAL issue:
- **#123 - [Issue Title](url)**
- **What it's about:** [Deep understanding]
- **Affected:** [Components]
- **Why Critical:** [Rationale]
- **Suggested Action:** [Specific action]
### High Priority Issues (HIGH Priority)
Same format as Critical, grouped by theme.
### Theme Clusters
For each major theme:
- **Theme Name** (N issues)
- **What connects these:** [Pattern]
- **Root cause:** [If identifiable]
- **Consolidated actions:** [Bulk actions if applicable]
- **Issues:** #123, #456, #789
### Relationships & Dependencies
- **Duplicates:** List pairs with `gh issue close` commands
- **Related Issues:** Groups of related issues
- **Dependencies:** Blocking relationships
### Cross-Repo Issues
Issues that should be migrated to other repositories.
For each, provide:
```
gh issue close XXX --repo CURRENT_REPO --comment "This issue belongs in REPO. Please report at https://github.com/TARGET_REPO/issues/new"
```
### Cleanup Candidates
- **v4-related:** Deprecated version issues with close commands
- **Stale:** No activity >30 days
- **Low priority + old:** Low priority issues >60 days old
### Actionable Next Steps
Specific, prioritized actions:
1. [CRITICAL] Fix broken installer - affects all new users
2. [HIGH] Resolve Windows path escaping issues
3. [HIGH] Address workflow integration bugs
etc.
Include `gh` commands where applicable for bulk actions.

24
.claude/skills/release-module/README.md Normal file
View File

@ -0,0 +1,24 @@
# release-module
Automates the complete release process for npm modules.
## Usage
Run from project root or pass project path:
```
bmad-utility-skills:release-module
```
## Prerequisite
First run `draft-changelog` to analyze changes and create a draft changelog.
## What It Does
1. Gets and confirms changelog entry
2. Confirms version bump type (patch/minor/major)
3. Updates CHANGELOG.md
4. Bumps version with `npm version`
5. Pushes git tag
6. Publishes to npm
7. Creates GitHub release

7
.claude/skills/release-module/SKILL.md Normal file
View File

@ -0,0 +1,7 @@
---
name: bmad-os-release-module
description: Automates the complete release process for npm modules - version bump, changelog, git tag, npm publish, GitHub release
disable-model-invocation: true
---
Read `prompts/instructions.md` and execute.

53
.claude/skills/release-module/prompts/instructions.md Normal file
View File

@ -0,0 +1,53 @@
# Release BMad Module Execution
## Input
Project path (or run from project root)
## Execution Steps
### Step 1: Get Current State
- Verify git working tree is clean
- Get latest tag and current version
- Check for unpushed commits
### Step 2: Get Changelog Entry
Ask the user for the changelog entry (from draft-changelog skill or manual).
### Step 3: Confirm Changelog
Show project name, current version, proposed next version, and changelog. Get confirmation.
### Step 4: Confirm Version Bump Type
Ask what type of bump: patch, minor, major, prerelease, or custom.
### Step 5: Update CHANGELOG.md
Insert new entry at top, commit, and push.
### Step 6: Bump Version
Run `npm version` to update package.json, create commit, and create tag.
### Step 7: Push Tag
Push the new version tag to GitHub.
### Step 8: Publish to npm
Publish the package.
### Step 9: Create GitHub Release
Create release with changelog notes using `gh release create`.
## Error Handling
Stop immediately on any step failure. Inform user and suggest fix.
## Important Notes
- Wait for user confirmation before destructive operations
- Push changelog commit before version bump
- Use explicit directory paths in commands

71
.coderabbit.yaml
View File

@ -11,27 +11,72 @@ reviews:
walkthrough: false
poem: false
auto_review:
enabled: false
drafts: true # Can review drafts. Since it's manually triggered, it's fine.
enabled: true
drafts: false # Don't review drafts automatically
auto_incremental_review: false # always review the whole PR, not just new commits
base_branches:
- main
path_filters:
# --- Shared baseline: tool configs ---
- "!.coderabbit.yaml"
- "!.augment/**"
- "!eslint.config.mjs"
# --- Shared baseline: build output ---
- "!dist/**"
- "!build/**"
- "!coverage/**"
# --- Shared baseline: vendored/generated ---
- "!**/node_modules/**"
- "!**/*.min.js"
- "!**/*.generated.*"
- "!**/*.bundle.md"
# --- Shared baseline: package metadata ---
- "!package-lock.json"
# --- Shared baseline: binary/media ---
- "!*.png"
- "!*.jpg"
- "!*.svg"
# --- Shared baseline: test fixtures ---
- "!test/fixtures/**"
- "!test/template-test-generator/**"
- "!tools/template-test-generator/test-scenarios/**"
# --- Shared baseline: non-project dirs ---
- "!_bmad*/**"
- "!website/**"
- "!z*/**"
- "!sample-project/**"
- "!test-project-install/**"
# --- Shared baseline: AI assistant dirs ---
- "!.claude/**"
- "!.codex/**"
- "!.agent/**"
- "!.agentvibes/**"
- "!.kiro/**"
- "!.roo/**"
- "!.github/chatmodes/**"
# --- Shared baseline: build temp ---
- "!.bundler-temp/**"
# --- Shared baseline: generated reports ---
- "!**/validation-report-*.md"
- "!CHANGELOG.md"
path_instructions:
- path: "**/*"
instructions: |
Focus on inconsistencies, contradictions, edge cases and serious issues.
Avoid commenting on minor issues such as linting, formatting and style issues.
When providing code suggestions, use GitHub's suggestion format:
```suggestion
<code changes>
```
- path: "**/*.js"
instructions: |
CLI tooling code. Check for: missing error handling on fs operations,
path.join vs string concatenation, proper cleanup in error paths.
Flag any process.exit() without error message.
You are a cynical, jaded reviewer with zero patience for sloppy work.
This PR was submitted by a clueless weasel and you expect to find problems.
Be skeptical of everything.
Look for what's missing, not just what's wrong.
Use a precise, professional tone — no profanity or personal attacks.
Review with extreme skepticism — assume problems exist.
Find at least 10 issues to fix or improve.
Do NOT:
- Comment on formatting, linting, or style
- Give "looks good" passes
- Anchor on any specific ruleset — reason freely
If you find zero issues, re-analyze — this is suspicious.
chat:
auto_reply: true # Response to mentions in comments, a la @coderabbit review
issue_enrichment:

124
.github/ISSUE_TEMPLATE/bug-report.yaml vendored Normal file
View File

@ -0,0 +1,124 @@
name: Bug Report
description: File a bug report to help us improve BMad Method
title: "[BUG] "
labels: bug
assignees: []
body:
- type: markdown
attributes:
value: |
Thanks for filing a bug report! Please fill out the information below to help us reproduce and fix the issue.
- type: textarea
id: description
attributes:
label: Description
description: Clear and concise description of what the bug is
placeholder: e.g., When I run /dev-story, it crashes on step 3
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
description: Step-by-step instructions to reproduce the behavior
placeholder: |
1. Run 'npx bmad-method install'
2. Select option X
3. Run workflow Y
4. See error
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
description: What you expected to happen
placeholder: The workflow should complete successfully
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual behavior
description: What actually happened
placeholder: The workflow crashed with error "..."
validations:
required: true
- type: textarea
id: screenshots
attributes:
label: Screenshots
description: Add screenshots if applicable (paste images directly)
placeholder: Paste any relevant screenshots here
- type: dropdown
id: module
attributes:
label: Which module is this for?
description: Select the BMad module this issue relates to
options:
- BMad Method (BMM) - Core Framework
- BMad Builder (BMB) - Agent Builder Tool
- Test Architect (TEA) - Test Strategy Module
- Game Dev Studio (BMGD) - Game Development Module
- Creative Intelligence Suite (CIS) - Innovation Module
- Not sure / Other
validations:
required: true
- type: input
id: version
attributes:
label: BMad Version
description: "Check with: npx bmad-method --version or check package.json"
placeholder: e.g., 6.0.0-Beta.4
validations:
required: true
- type: dropdown
id: ide
attributes:
label: Which AI IDE are you using?
options:
- Claude Code
- Cursor
- Windsurf
- Copilot CLI / GitHub Copilot
- Kilo Code
- Other
validations:
required: true
- type: dropdown
id: platform
attributes:
label: Operating System
options:
- macOS
- Windows
- Linux
- Other
validations:
required: true
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Copy and paste any relevant log output
render: shell
- type: checkboxes
id: terms
attributes:
label: Confirm
options:
- label: I've searched for existing issues
required: true
- label: I'm using the latest version
required: false

32
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -1,32 +0,0 @@
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''
---
**Describe the bug**
A clear and concise description of what the bug is.
**Steps to Reproduce**
What lead to the bug and can it be reliable recreated - if so with what steps.
**PR**
If you have an idea to fix and would like to contribute, please indicate here you are working on a fix, or link to a proposed PR to fix the issue. Please review the contribution.md - contributions are always welcome!
**Expected behavior**
A clear and concise description of what you expected to happen.
**Please be Specific if relevant**
Model(s) Used:
Agentic IDE Used:
WebSite Used:
Project Language:
BMad Method version:
**Screenshots or Links**
If applicable, add screenshots or links (if web sharable record) to help explain your problem.
**Additional context**
Add any other context about the problem here. The more information you can provide, the easier it will be to suggest a fix or resolve

7
.github/ISSUE_TEMPLATE/config.yaml vendored
View File

@ -1,5 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Discord Community Support
- name: 📚 Documentation
url: http://docs.bmad-method.org
about: Check the docs first — tutorials, guides, and reference
- name: 💬 Discord Community
url: https://discord.gg/gk8jAdXWmj
about: Please join our Discord server for general questions and community discussion before opening an issue.
about: Join for questions, discussion, and help before opening an issue

55
.github/ISSUE_TEMPLATE/documentation.yaml vendored Normal file
View File

@ -0,0 +1,55 @@
name: Documentation
description: Report issues or suggest improvements to documentation
title: "[DOCS] "
labels: documentation
assignees: []
body:
- type: markdown
attributes:
value: |
Help us improve the BMad Method documentation!
- type: dropdown
id: doc-type
attributes:
label: What type of documentation issue is this?
options:
- Error or inaccuracy
- Missing information
- Unclear or confusing
- Outdated content
- Request for new documentation
- Typo or grammar
validations:
required: true
- type: textarea
id: location
attributes:
label: Documentation location
description: Where is the documentation that needs improvement?
placeholder: e.g., http://docs.bmad-method.org/tutorials/getting-started/ or "In the README"
validations:
required: true
- type: textarea
id: issue
attributes:
label: What's the issue?
description: Describe the documentation issue in detail
placeholder: e.g., Step 3 says to run command X but it should be command Y
validations:
required: true
- type: textarea
id: suggestion
attributes:
label: Suggested improvement
description: How would you like to see this improved?
placeholder: e.g., Change the command to X and add an example
- type: input
id: version
attributes:
label: BMad Version (if applicable)
placeholder: e.g., 6.0.0-Beta.4

22
.github/ISSUE_TEMPLATE/feature-request.md vendored Normal file
View File

@ -0,0 +1,22 @@
---
name: Feature Request
about: Suggest an idea or new feature
title: ''
labels: ''
assignees: ''
---
**Describe your idea**
A clear and concise description of what you'd like to see added or changed.
**Why is this needed?**
Explain the problem this solves or the benefit it brings to the BMad community.
**How should it work?**
Describe your proposed solution. If you have ideas on implementation, share them here.
**PR**
If you'd like to contribute, please indicate you're working on this or link to your PR. Please review [CONTRIBUTING.md](../../CONTRIBUTING.md) — contributions are always welcome!
**Additional context**
Add any other context, screenshots, or links that help explain your idea.

109
.github/ISSUE_TEMPLATE/idea_submission.md vendored
View File

@ -1,109 +0,0 @@
---
name: V6 Idea Submission
about: Suggest an idea for v6
title: ''
labels: ''
assignees: ''
---
# Idea: [Replace with a clear, actionable title]
## PASS Framework
**P**roblem:
> What's broken or missing? What pain point are we addressing? (1-2 sentences)
>
> [Your answer here]
**A**udience:
> Who's affected by this problem and how severely? (1-2 sentences)
>
> [Your answer here]
**S**olution:
> What will we build or change? How will we measure success? (1-2 sentences with at least 1 measurable outcome)
>
> [Your answer here]
>
> [Your Acceptance Criteria for measuring success here]
**S**ize:
> How much effort do you estimate this will take?
>
> - [ ] **XS** - A few hours
> - [ ] **S** - 1-2 days
> - [ ] **M** - 3-5 days
> - [ ] **L** - 1-2 weeks
> - [ ] **XL** - More than 2 weeks
---
### Metadata
**Submitted by:** [Your name]
**Date:** [Today's date]
**Priority:** [Leave blank - will be assigned during team review]
---
## Examples
<details>
<summary>Click to see a GOOD example</summary>
### Idea: Add search functionality to customer dashboard
**P**roblem:
Customers can't find their past orders quickly. They have to scroll through pages of orders to find what they're looking for, leading to 15+ support tickets per week.
**A**udience:
All 5,000+ active customers are affected. Support team spends ~10 hours/week helping customers find orders.
**S**olution:
Add a search bar that filters by order number, date range, and product name. Success = 50% reduction in order-finding support tickets within 2 weeks of launch.
**S**ize:
- [x] **M** - 3-5 days
</details>
<details>
<summary>Click to see a POOR example</summary>
### Idea: Make the app better
**P**roblem:
The app needs improvements and updates.
**A**udience:
Users
**S**olution:
Fix issues and add features.
**S**ize:
- [ ] Unknown
_Why this is poor: Too vague, no specific problem identified, no measurable success criteria, unclear scope_
</details>
---
## Tips for Success
1. **Be specific** - Vague problems lead to vague solutions
2. **Quantify when possible** - Numbers help us prioritize (e.g., "20 customers asked for this" vs "customers want this")
3. **One idea per submission** - If you have multiple ideas, submit multiple templates
4. **Success metrics matter** - How will we know this worked?
5. **Honest sizing** - Better to overestimate than underestimate
## Questions?
Reach out to @OverlordBaconPants if you need help completing this template.

32
.github/ISSUE_TEMPLATE/issue.md vendored Normal file
View File

@ -0,0 +1,32 @@
---
name: Issue
about: Report a problem or something that's not working
title: ''
labels: ''
assignees: ''
---
**Describe the bug**
A clear and concise description of what the bug is.
**Steps to reproduce**
1. What were you doing when the bug occurred?
2. What steps can recreate the issue?
**Expected behavior**
A clear and concise description of what you expected to happen.
**Environment (if relevant)**
- Model(s) used:
- Agentic IDE used:
- BMad version:
- Project language:
**Screenshots or links**
If applicable, add screenshots or links to help explain the problem.
**PR**
If you'd like to contribute a fix, please indicate you're working on it or link to your PR. See [CONTRIBUTING.md](../../CONTRIBUTING.md) — contributions are always welcome!
**Additional context**
Add any other context about the problem here. The more information you provide, the easier it is to help.

13
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@ -0,0 +1,13 @@
## What
<!-- 1-2 sentences describing WHAT changed -->
## Why
<!-- 1-2 sentences explaining WHY this change is needed -->
<!-- Fixes `#issue_number` (if applicable) -->
## How
<!-- 2-3 bullets listing HOW you implemented it -->
-
## Testing
<!-- 1-2 sentences on how you tested this -->

329
.github/workflows/bundle-latest.yaml vendored
View File

@ -1,329 +0,0 @@
name: Publish Latest Bundles
on:
push:
branches: [main]
workflow_dispatch: {}
permissions:
contents: write
jobs:
bundle-and-publish:
runs-on: ubuntu-latest
steps:
- name: Checkout BMAD-METHOD
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version-file: ".nvmrc"
cache: npm
- name: Install dependencies
run: npm ci
- name: Generate bundles
run: npm run bundle
- name: Create bundle distribution structure
run: |
mkdir -p dist/bundles
# Copy web bundles (XML files from npm run bundle output)
cp -r web-bundles/* dist/bundles/ 2>/dev/null || true
# Verify bundles were copied (fail if completely empty)
if [ ! "$(ls -A dist/bundles)" ]; then
echo "❌ ERROR: No bundles found in dist/bundles/"
echo "This likely means 'npm run bundle' failed or bundles weren't generated"
exit 1
fi
# Count bundles per module
for module in bmm bmb cis bmgd; do
if [ -d "dist/bundles/$module/agents" ]; then
COUNT=$(find dist/bundles/$module/agents -name '*.xml' 2>/dev/null | wc -l)
echo "✅ $module: $COUNT agent bundles"
fi
done
# Generate index.html for each agents directory (fixes directory browsing)
for module in bmm bmb cis bmgd; do
if [ -d "dist/bundles/$module/agents" ]; then
cat > "dist/bundles/$module/agents/index.html" << 'DIREOF'
<!DOCTYPE html>
<html>
<head>
<title>MODULE_NAME Agents</title>
<style>
body { font-family: system-ui; max-width: 800px; margin: 50px auto; padding: 20px; }
li { margin: 10px 0; }
a { color: #0066cc; text-decoration: none; }
a:hover { text-decoration: underline; }
</style>
</head>
<body>
<h1>MODULE_NAME Agents</h1>
<ul>
AGENT_LINKS
</ul>
<p><a href="../../">← Back to all modules</a></p>
</body>
</html>
DIREOF
# Replace MODULE_NAME
sed -i "s/MODULE_NAME/${module^^}/g" "dist/bundles/$module/agents/index.html"
# Generate agent links
LINKS=""
for file in dist/bundles/$module/agents/*.xml; do
if [ -f "$file" ]; then
name=$(basename "$file" .xml)
LINKS="$LINKS <li><a href=\"./$name.xml\">$name</a></li>\n"
fi
done
sed -i "s|AGENT_LINKS|$LINKS|" "dist/bundles/$module/agents/index.html"
fi
done
# Create zip archives per module
mkdir -p dist/bundles/downloads
for module in bmm bmb cis bmgd; do
if [ -d "dist/bundles/$module" ]; then
(cd dist/bundles && zip -r downloads/$module-agents.zip $module/)
echo "✅ Created $module-agents.zip"
fi
done
# Generate index.html dynamically based on actual bundles
TIMESTAMP=$(date -u +"%Y-%m-%d %H:%M UTC")
COMMIT_SHA=$(git rev-parse --short HEAD)
# Function to generate agent links for a module
generate_agent_links() {
local module=$1
local agent_dir="dist/bundles/$module/agents"
if [ ! -d "$agent_dir" ]; then
echo ""
return
fi
local links=""
local count=0
# Find all XML files and generate links
for xml_file in "$agent_dir"/*.xml; do
if [ -f "$xml_file" ]; then
local agent_name=$(basename "$xml_file" .xml)
# Convert filename to display name (pm -> PM, tech-writer -> Tech Writer)
local display_name=$(echo "$agent_name" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) {if(length($i)==2) $i=toupper($i); else $i=toupper(substr($i,1,1)) tolower(substr($i,2));}}1')
if [ $count -gt 0 ]; then
links="$links | "
fi
links="$links<a href=\"./$module/agents/$agent_name.xml\">$display_name</a>"
count=$((count + 1))
fi
done
echo "$links"
}
# Generate agent links for each module
BMM_LINKS=$(generate_agent_links "bmm")
CIS_LINKS=$(generate_agent_links "cis")
BMGD_LINKS=$(generate_agent_links "bmgd")
# Count agents for bulk downloads
BMM_COUNT=$(find dist/bundles/bmm/agents -name '*.xml' 2>/dev/null | wc -l | tr -d ' ')
CIS_COUNT=$(find dist/bundles/cis/agents -name '*.xml' 2>/dev/null | wc -l | tr -d ' ')
BMGD_COUNT=$(find dist/bundles/bmgd/agents -name '*.xml' 2>/dev/null | wc -l | tr -d ' ')
# Create index.html
cat > dist/bundles/index.html << EOF
<!DOCTYPE html>
<html>
<head>
<title>BMAD Bundles - Latest</title>
<meta charset="utf-8">
<style>
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 800px; margin: 50px auto; padding: 20px; }
h1 { color: #333; }
.platform { margin: 30px 0; padding: 20px; background: #f5f5f5; border-radius: 8px; }
.module { margin: 15px 0; }
a { color: #0066cc; text-decoration: none; }
a:hover { text-decoration: underline; }
code { background: #e0e0e0; padding: 2px 6px; border-radius: 3px; }
.warning { background: #fff3cd; padding: 15px; border-left: 4px solid #ffc107; margin: 20px 0; }
</style>
</head>
<body>
<h1>BMAD Web Bundles - Latest (Main Branch)</h1>
<div class="warning">
<strong>⚠️ Latest Build (Unstable)</strong><br>
These bundles are built from the latest main branch commit. For stable releases, visit
<a href="https://github.com/bmad-code-org/BMAD-METHOD/releases/latest">GitHub Releases</a>.
</div>
<p><strong>Last Updated:</strong> <code>$TIMESTAMP</code></p>
<p><strong>Commit:</strong> <code>$COMMIT_SHA</code></p>
<h2>Available Modules</h2>
EOF
# Add BMM section if agents exist
if [ -n "$BMM_LINKS" ]; then
cat >> dist/bundles/index.html << EOF
<div class="platform">
<h3>BMM (BMad Method)</h3>
<div class="module">
$BMM_LINKS<br>
📁 <a href="./bmm/agents/">Browse All</a> | 📦 <a href="./downloads/bmm-agents.zip">Download Zip</a>
</div>
</div>
EOF
fi
# Add CIS section if agents exist
if [ -n "$CIS_LINKS" ]; then
cat >> dist/bundles/index.html << EOF
<div class="platform">
<h3>CIS (Creative Intelligence Suite)</h3>
<div class="module">
$CIS_LINKS<br>
📁 <a href="./cis/agents/">Browse Agents</a> | 📦 <a href="./downloads/cis-agents.zip">Download Zip</a>
</div>
</div>
EOF
fi
# Add BMGD section if agents exist
if [ -n "$BMGD_LINKS" ]; then
cat >> dist/bundles/index.html << EOF
<div class="platform">
<h3>BMGD (Game Development)</h3>
<div class="module">
$BMGD_LINKS<br>
📁 <a href="./bmgd/agents/">Browse Agents</a> | 📦 <a href="./downloads/bmgd-agents.zip">Download Zip</a>
</div>
</div>
EOF
fi
# Add bulk downloads section
cat >> dist/bundles/index.html << EOF
<h2>Bulk Downloads</h2>
<p>Download all agents for a module as a zip archive:</p>
<ul>
EOF
[ "$BMM_COUNT" -gt 0 ] && echo " <li><a href=\"./downloads/bmm-agents.zip\">📦 BMM Agents (all $BMM_COUNT)</a></li>" >> dist/bundles/index.html
[ "$CIS_COUNT" -gt 0 ] && echo " <li><a href=\"./downloads/cis-agents.zip\">📦 CIS Agents (all $CIS_COUNT)</a></li>" >> dist/bundles/index.html
[ "$BMGD_COUNT" -gt 0 ] && echo " <li><a href=\"./downloads/bmgd-agents.zip\">📦 BMGD Agents (all $BMGD_COUNT)</a></li>" >> dist/bundles/index.html
# Close HTML
cat >> dist/bundles/index.html << 'EOF'
</ul>
<h2>Usage</h2>
<p>Copy the raw XML URL and paste into your AI platform's custom instructions or project knowledge.</p>
<p>Example: <code>https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/bmm/agents/pm.xml</code></p>
<h2>Installation (Recommended)</h2>
<p>For full IDE integration with slash commands, use the installer:</p>
<pre>npx bmad-method@alpha install</pre>
<footer style="margin-top: 50px; padding-top: 20px; border-top: 1px solid #ccc; color: #666;">
<p>Built from <a href="https://github.com/bmad-code-org/BMAD-METHOD">BMAD-METHOD</a> repository.</p>
</footer>
</body>
</html>
EOF
- name: Checkout bmad-bundles repo
uses: actions/checkout@v4
with:
repository: bmad-code-org/bmad-bundles
path: bmad-bundles
token: ${{ secrets.BUNDLES_PAT }}
- name: Update bundles
run: |
# Clear old bundles
rm -rf bmad-bundles/*
# Copy new bundles
cp -r dist/bundles/* bmad-bundles/
# Create .nojekyll for GitHub Pages
touch bmad-bundles/.nojekyll
# Create README
cat > bmad-bundles/README.md << 'EOF'
# BMAD Web Bundles (Latest)
**⚠️ Unstable Build**: These bundles are auto-generated from the latest `main` branch.
For stable releases, visit [GitHub Releases](https://github.com/bmad-code-org/BMAD-METHOD/releases/latest).
## Usage
Copy raw markdown URLs for use in AI platforms:
- Claude Code: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/{agent}.md`
- ChatGPT: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/chatgpt/sub-agents/{agent}.md`
- Gemini: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/gemini/sub-agents/{agent}.md`
## Browse
Visit [https://bmad-code-org.github.io/bmad-bundles/](https://bmad-code-org.github.io/bmad-bundles/) to browse bundles.
## Installation (Recommended)
For full IDE integration:
```bash
npx bmad-method@alpha install
```
---
Auto-updated by [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) on every main branch merge.
EOF
- name: Commit and push to bmad-bundles
run: |
cd bmad-bundles
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add .
if git diff --staged --quiet; then
echo "No changes to bundles, skipping commit"
else
COMMIT_SHA=$(cd .. && git rev-parse --short HEAD)
git commit -m "Update bundles from BMAD-METHOD@${COMMIT_SHA}"
git push
echo "✅ Bundles published to GitHub Pages"
fi
- name: Summary
run: |
echo "## 🎉 Bundles Published!" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "**Latest bundles** available at:" >> $GITHUB_STEP_SUMMARY
echo "- 🌐 Browse: https://bmad-code-org.github.io/bmad-bundles/" >> $GITHUB_STEP_SUMMARY
echo "- 📦 Raw files: https://github.com/bmad-code-org/bmad-bundles" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "**Commit**: ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY

22
.github/workflows/coderabbit-review.yaml vendored Normal file
View File

@ -0,0 +1,22 @@
name: Trigger CodeRabbit on Ready for Review
on:
pull_request_target:
types: [ready_for_review]
jobs:
trigger-review:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- name: Request CodeRabbit review
uses: actions/github-script@v7
with:
script: |
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.pull_request.number,
body: '@coderabbitai review'
});

230
.github/workflows/discord.yaml vendored
View File

@ -2,19 +2,9 @@ name: Discord Notification
on:
pull_request:
types: [opened, closed, reopened, ready_for_review]
release:
types: [published]
create:
delete:
issue_comment:
types: [created]
pull_request_review:
types: [submitted]
pull_request_review_comment:
types: [created]
types: [opened, closed]
issues:
types: [opened, closed, reopened]
types: [opened]
env:
MAX_TITLE: 100
@ -47,9 +37,7 @@ jobs:
if [ "$ACTION" = "opened" ]; then ICON="🔀"; LABEL="New PR"
elif [ "$ACTION" = "closed" ] && [ "$MERGED" = "true" ]; then ICON="🎉"; LABEL="Merged"
elif [ "$ACTION" = "closed" ]; then ICON="❌"; LABEL="Closed"
elif [ "$ACTION" = "reopened" ]; then ICON="🔄"; LABEL="Reopened"
else ICON="📋"; LABEL="Ready"; fi
elif [ "$ACTION" = "closed" ]; then ICON="❌"; LABEL="Closed"; fi
TITLE=$(printf '%s' "$PR_TITLE" | trunc $MAX_TITLE | esc)
[ ${#PR_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
@ -77,22 +65,16 @@ jobs:
- name: Notify Discord
env:
WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
ACTION: ${{ github.event.action }}
ISSUE_NUM: ${{ github.event.issue.number }}
ISSUE_URL: ${{ github.event.issue.html_url }}
ISSUE_TITLE: ${{ github.event.issue.title }}
ISSUE_USER: ${{ github.event.issue.user.login }}
ISSUE_BODY: ${{ github.event.issue.body }}
ACTOR: ${{ github.actor }}
run: |
set -o pipefail
source .github/scripts/discord-helpers.sh
[ -z "$WEBHOOK" ] && exit 0
if [ "$ACTION" = "opened" ]; then ICON="🐛"; LABEL="New Issue"; USER="$ISSUE_USER"
elif [ "$ACTION" = "closed" ]; then ICON="✅"; LABEL="Closed"; USER="$ACTOR"
else ICON="🔄"; LABEL="Reopened"; USER="$ACTOR"; fi
TITLE=$(printf '%s' "$ISSUE_TITLE" | trunc $MAX_TITLE | esc)
[ ${#ISSUE_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
BODY=$(printf '%s' "$ISSUE_BODY" | trunc $MAX_BODY)
@ -102,209 +84,7 @@ jobs:
BODY=$(printf '%s' "$BODY" | wrap_urls | esc)
[ -n "$ISSUE_BODY" ] && [ ${#ISSUE_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
[ -n "$BODY" ] && BODY=" · $BODY"
USER=$(printf '%s' "$USER" | esc)
USER=$(printf '%s' "$ISSUE_USER" | esc)
MSG="$ICON **[$LABEL #$ISSUE_NUM: $TITLE](<$ISSUE_URL>)**"$'\n'"by @$USER$BODY"
jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
issue_comment:
if: github.event_name == 'issue_comment'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.repository.default_branch }}
sparse-checkout: .github/scripts
sparse-checkout-cone-mode: false
- name: Notify Discord
env:
WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
IS_PR: ${{ github.event.issue.pull_request && 'true' || 'false' }}
ISSUE_NUM: ${{ github.event.issue.number }}
ISSUE_TITLE: ${{ github.event.issue.title }}
COMMENT_URL: ${{ github.event.comment.html_url }}
COMMENT_USER: ${{ github.event.comment.user.login }}
COMMENT_BODY: ${{ github.event.comment.body }}
run: |
set -o pipefail
source .github/scripts/discord-helpers.sh
[ -z "$WEBHOOK" ] && exit 0
[ "$IS_PR" = "true" ] && TYPE="PR" || TYPE="Issue"
TITLE=$(printf '%s' "$ISSUE_TITLE" | trunc $MAX_TITLE | esc)
[ ${#ISSUE_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
BODY=$(printf '%s' "$COMMENT_BODY" | trunc $MAX_BODY)
if [ ${#COMMENT_BODY} -gt $MAX_BODY ]; then
BODY=$(printf '%s' "$BODY" | strip_trailing_url)
fi
BODY=$(printf '%s' "$BODY" | wrap_urls | esc)
[ ${#COMMENT_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
USER=$(printf '%s' "$COMMENT_USER" | esc)
MSG="💬 **[Comment on $TYPE #$ISSUE_NUM: $TITLE](<$COMMENT_URL>)**"$'\n'"@$USER: $BODY"
jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
pull_request_review:
if: github.event_name == 'pull_request_review'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.repository.default_branch }}
sparse-checkout: .github/scripts
sparse-checkout-cone-mode: false
- name: Notify Discord
env:
WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
STATE: ${{ github.event.review.state }}
PR_NUM: ${{ github.event.pull_request.number }}
PR_TITLE: ${{ github.event.pull_request.title }}
REVIEW_URL: ${{ github.event.review.html_url }}
REVIEW_USER: ${{ github.event.review.user.login }}
REVIEW_BODY: ${{ github.event.review.body }}
run: |
set -o pipefail
source .github/scripts/discord-helpers.sh
[ -z "$WEBHOOK" ] && exit 0
if [ "$STATE" = "approved" ]; then ICON="✅"; LABEL="Approved"
elif [ "$STATE" = "changes_requested" ]; then ICON="🔧"; LABEL="Changes Requested"
else ICON="👀"; LABEL="Reviewed"; fi
TITLE=$(printf '%s' "$PR_TITLE" | trunc $MAX_TITLE | esc)
[ ${#PR_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
BODY=$(printf '%s' "$REVIEW_BODY" | trunc $MAX_BODY)
if [ -n "$REVIEW_BODY" ] && [ ${#REVIEW_BODY} -gt $MAX_BODY ]; then
BODY=$(printf '%s' "$BODY" | strip_trailing_url)
fi
BODY=$(printf '%s' "$BODY" | wrap_urls | esc)
[ -n "$REVIEW_BODY" ] && [ ${#REVIEW_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
[ -n "$BODY" ] && BODY=": $BODY"
USER=$(printf '%s' "$REVIEW_USER" | esc)
MSG="$ICON **[$LABEL PR #$PR_NUM: $TITLE](<$REVIEW_URL>)**"$'\n'"@$USER$BODY"
jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
pull_request_review_comment:
if: github.event_name == 'pull_request_review_comment'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.repository.default_branch }}
sparse-checkout: .github/scripts
sparse-checkout-cone-mode: false
- name: Notify Discord
env:
WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
PR_NUM: ${{ github.event.pull_request.number }}
PR_TITLE: ${{ github.event.pull_request.title }}
COMMENT_URL: ${{ github.event.comment.html_url }}
COMMENT_USER: ${{ github.event.comment.user.login }}
COMMENT_BODY: ${{ github.event.comment.body }}
run: |
set -o pipefail
source .github/scripts/discord-helpers.sh
[ -z "$WEBHOOK" ] && exit 0
TITLE=$(printf '%s' "$PR_TITLE" | trunc $MAX_TITLE | esc)
[ ${#PR_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
BODY=$(printf '%s' "$COMMENT_BODY" | trunc $MAX_BODY)
if [ ${#COMMENT_BODY} -gt $MAX_BODY ]; then
BODY=$(printf '%s' "$BODY" | strip_trailing_url)
fi
BODY=$(printf '%s' "$BODY" | wrap_urls | esc)
[ ${#COMMENT_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
USER=$(printf '%s' "$COMMENT_USER" | esc)
MSG="💭 **[Review Comment PR #$PR_NUM: $TITLE](<$COMMENT_URL>)**"$'\n'"@$USER: $BODY"
jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
release:
if: github.event_name == 'release'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.repository.default_branch }}
sparse-checkout: .github/scripts
sparse-checkout-cone-mode: false
- name: Notify Discord
env:
WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
TAG: ${{ github.event.release.tag_name }}
NAME: ${{ github.event.release.name }}
URL: ${{ github.event.release.html_url }}
RELEASE_BODY: ${{ github.event.release.body }}
run: |
set -o pipefail
source .github/scripts/discord-helpers.sh
[ -z "$WEBHOOK" ] && exit 0
REL_NAME=$(printf '%s' "$NAME" | trunc $MAX_TITLE | esc)
[ ${#NAME} -gt $MAX_TITLE ] && REL_NAME="${REL_NAME}..."
BODY=$(printf '%s' "$RELEASE_BODY" | trunc $MAX_BODY)
if [ -n "$RELEASE_BODY" ] && [ ${#RELEASE_BODY} -gt $MAX_BODY ]; then
BODY=$(printf '%s' "$BODY" | strip_trailing_url)
fi
BODY=$(printf '%s' "$BODY" | wrap_urls | esc)
[ -n "$RELEASE_BODY" ] && [ ${#RELEASE_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
[ -n "$BODY" ] && BODY=" · $BODY"
TAG_ESC=$(printf '%s' "$TAG" | esc)
MSG="🚀 **[Release $TAG_ESC: $REL_NAME](<$URL>)**"$'\n'"$BODY"
jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
create:
if: github.event_name == 'create'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.repository.default_branch }}
sparse-checkout: .github/scripts
sparse-checkout-cone-mode: false
- name: Notify Discord
env:
WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
REF_TYPE: ${{ github.event.ref_type }}
REF: ${{ github.event.ref }}
ACTOR: ${{ github.actor }}
REPO_URL: ${{ github.event.repository.html_url }}
run: |
set -o pipefail
source .github/scripts/discord-helpers.sh
[ -z "$WEBHOOK" ] && exit 0
[ "$REF_TYPE" = "branch" ] && ICON="🌿" || ICON="🏷️"
REF_TRUNC=$(printf '%s' "$REF" | trunc $MAX_TITLE)
[ ${#REF} -gt $MAX_TITLE ] && REF_TRUNC="${REF_TRUNC}..."
REF_ESC=$(printf '%s' "$REF_TRUNC" | esc)
REF_URL=$(jq -rn --arg ref "$REF" '$ref | @uri')
ACTOR_ESC=$(printf '%s' "$ACTOR" | esc)
MSG="$ICON **${REF_TYPE^} created: [$REF_ESC](<$REPO_URL/tree/$REF_URL>)** by @$ACTOR_ESC"
jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
delete:
if: github.event_name == 'delete'
runs-on: ubuntu-latest
steps:
- name: Notify Discord
env:
WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
REF_TYPE: ${{ github.event.ref_type }}
REF: ${{ github.event.ref }}
ACTOR: ${{ github.actor }}
run: |
set -o pipefail
[ -z "$WEBHOOK" ] && exit 0
esc() { sed -e 's/[][\*_()~`]/\\&/g' -e 's/@/@ /g'; }
trunc() { tr '\n\r' ' ' | cut -c1-"$1"; }
REF_TRUNC=$(printf '%s' "$REF" | trunc 100)
[ ${#REF} -gt 100 ] && REF_TRUNC="${REF_TRUNC}..."
REF_ESC=$(printf '%s' "$REF_TRUNC" | esc)
ACTOR_ESC=$(printf '%s' "$ACTOR" | esc)
MSG="🗑️ **${REF_TYPE^} deleted: $REF_ESC** by @$ACTOR_ESC"
MSG="🐛 **[Issue #$ISSUE_NUM: $TITLE](<$ISSUE_URL>)**"$'\n'"by @$USER$BODY"
jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-

22
.github/workflows/docs.yaml vendored
View File

@ -6,9 +6,8 @@ on:
- main
paths:
- "docs/**"
- "src/modules/*/docs/**"
- "website/**"
- "tools/build-docs.js"
- "tools/build-docs.mjs"
- ".github/workflows/docs.yaml"
workflow_dispatch:
@ -19,6 +18,7 @@ permissions:
concurrency:
group: "pages"
# No big win in setting this to true — risk of cancelling a deploy mid-flight.
cancel-in-progress: false
jobs:
@ -28,31 +28,23 @@ jobs:
- name: Checkout repository
uses: actions/checkout@v4
with:
# Full history needed for Starlight's lastUpdated timestamps (git log)
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
node-version-file: ".nvmrc"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Determine site URL
id: site-url
run: |
if [ "${{ github.repository }}" = "bmad-code-org/BMAD-METHOD" ]; then
echo "url=https://bmad-code-org.github.io/BMAD-METHOD" >> $GITHUB_OUTPUT
else
OWNER="${{ github.repository_owner }}"
REPO="${{ github.event.repository.name }}"
echo "url=https://${OWNER}.github.io/${REPO}" >> $GITHUB_OUTPUT
fi
- name: Build documentation
env:
SITE_URL: ${{ steps.site-url.outputs.url }}
# Override site URL from GitHub repo variable if set
# Otherwise, astro.config.mjs will compute from GITHUB_REPOSITORY
SITE_URL: ${{ vars.SITE_URL }}
run: npm run docs:build
- name: Upload artifact

190
.github/workflows/manual-release.yaml vendored
View File

@ -1,190 +0,0 @@
name: Manual Release
on:
workflow_dispatch:
inputs:
version_bump:
description: Version bump type
required: true
default: alpha
type: choice
options:
- alpha
- beta
- patch
- minor
- major
permissions:
contents: write
packages: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version-file: ".nvmrc"
cache: npm
registry-url: https://registry.npmjs.org
- name: Install dependencies
run: npm ci
- name: Run tests and validation
run: |
npm run validate
npm run format:check
npm run lint
- name: Configure Git
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Bump version
run: |
case "${{ github.event.inputs.version_bump }}" in
alpha|beta) npm version prerelease --no-git-tag-version --preid=${{ github.event.inputs.version_bump }} ;;
*) npm version ${{ github.event.inputs.version_bump }} --no-git-tag-version ;;
esac
- name: Get new version and previous tag
id: version
run: |
echo "new_version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
echo "previous_tag=$(git describe --tags --abbrev=0)" >> $GITHUB_OUTPUT
- name: Update installer package.json
run: |
sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.new_version }}"/' tools/installer/package.json
# TODO: Re-enable web bundles once tools/cli/bundlers/ is restored
# - name: Generate web bundles
# run: npm run bundle
- name: Commit version bump
run: |
git add .
git commit -m "release: bump to v${{ steps.version.outputs.new_version }}"
- name: Generate release notes
id: release_notes
run: |
# Get commits since last tag
COMMITS=$(git log ${{ steps.version.outputs.previous_tag }}..HEAD --pretty=format:"- %s" --reverse)
# Categorize commits
FEATURES=$(echo "$COMMITS" | grep -E "^- (feat|Feature)" || true)
FIXES=$(echo "$COMMITS" | grep -E "^- (fix|Fix)" || true)
CHORES=$(echo "$COMMITS" | grep -E "^- (chore|Chore)" || true)
OTHERS=$(echo "$COMMITS" | grep -v -E "^- (feat|Feature|fix|Fix|chore|Chore|release:|Release:)" || true)
# Build release notes
cat > release_notes.md << 'EOF'
## 🚀 What's New in v${{ steps.version.outputs.new_version }}
EOF
if [ ! -z "$FEATURES" ]; then
echo "### ✨ New Features" >> release_notes.md
echo "$FEATURES" >> release_notes.md
echo "" >> release_notes.md
fi
if [ ! -z "$FIXES" ]; then
echo "### 🐛 Bug Fixes" >> release_notes.md
echo "$FIXES" >> release_notes.md
echo "" >> release_notes.md
fi
if [ ! -z "$OTHERS" ]; then
echo "### 📦 Other Changes" >> release_notes.md
echo "$OTHERS" >> release_notes.md
echo "" >> release_notes.md
fi
if [ ! -z "$CHORES" ]; then
echo "### 🔧 Maintenance" >> release_notes.md
echo "$CHORES" >> release_notes.md
echo "" >> release_notes.md
fi
cat >> release_notes.md << 'EOF'
## 📦 Installation
```bash
npx bmad-method install
```
**Full Changelog**: https://github.com/bmad-code-org/BMAD-METHOD/compare/${{ steps.version.outputs.previous_tag }}...v${{ steps.version.outputs.new_version }}
EOF
# Output for GitHub Actions
echo "RELEASE_NOTES<<EOF" >> $GITHUB_OUTPUT
cat release_notes.md >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
- name: Create and push tag
run: |
# Check if tag already exists
if git rev-parse "v${{ steps.version.outputs.new_version }}" >/dev/null 2>&1; then
echo "Tag v${{ steps.version.outputs.new_version }} already exists, skipping tag creation"
else
git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}"
git push origin "v${{ steps.version.outputs.new_version }}"
fi
- name: Push changes to main
run: |
if git push origin HEAD:main 2>/dev/null; then
echo "✅ Successfully pushed to main branch"
else
echo "⚠️ Could not push to main (protected branch). This is expected."
echo "📝 Version bump and tag were created successfully."
fi
- name: Publish to NPM
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
VERSION="${{ steps.version.outputs.new_version }}"
if [[ "$VERSION" == *"alpha"* ]] || [[ "$VERSION" == *"beta"* ]]; then
echo "Publishing prerelease version with --tag alpha"
npm publish --tag alpha
else
echo "Publishing stable version with --tag latest"
npm publish --tag latest
fi
- name: Create GitHub Release
uses: softprops/action-gh-release@v2
with:
tag_name: v${{ steps.version.outputs.new_version }}
name: "BMad Method v${{ steps.version.outputs.new_version }}"
body: |
${{ steps.release_notes.outputs.RELEASE_NOTES }}
draft: false
prerelease: ${{ contains(steps.version.outputs.new_version, 'alpha') || contains(steps.version.outputs.new_version, 'beta') }}
- name: Summary
run: |
echo "## 🎉 Successfully released v${{ steps.version.outputs.new_version }}!" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### 📦 Distribution" >> $GITHUB_STEP_SUMMARY
echo "- **NPM**: Published with @latest tag" >> $GITHUB_STEP_SUMMARY
echo "- **GitHub Release**: https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v${{ steps.version.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### ✅ Installation" >> $GITHUB_STEP_SUMMARY
echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
echo "npx bmad-method@${{ steps.version.outputs.new_version }} install" >> $GITHUB_STEP_SUMMARY
echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

22
.github/workflows/quality.yaml vendored
View File

@ -69,6 +69,25 @@ jobs:
- name: markdownlint
run: npm run lint:md
docs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version-file: ".nvmrc"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Build documentation
# Note: build-docs.mjs runs link validation internally before building
run: npm run docs:build
validate:
runs-on: ubuntu-latest
steps:
@ -92,3 +111,6 @@ jobs:
- name: Test agent compilation components
run: npm run test:install
- name: Validate file references
run: npm run validate:refs

52
.gitignore vendored
View File

@ -1,12 +1,11 @@
# Dependencies
node_modules/
**/node_modules/
pnpm-lock.yaml
bun.lock
deno.lock
pnpm-workspace.yaml
package-lock.json
test-output/*
coverage/
@ -28,11 +27,6 @@ Thumbs.db
# Development tools and configs
.prettierrc
# IDE and editor configs
.windsurf/
.trae/
_bmad*/.cursor/
# AI assistant files
.ai/*
cursor
@ -42,38 +36,34 @@ CLAUDE.local.md
.serena/
.claude/settings.local.json
# Project-specific
_bmad-core
_bmad-creator-tools
flattened-codebase.xml
*.stats.md
.internal-docs/
#UAT template testing output files
tools/template-test-generator/test-scenarios/
# Bundler temporary files and generated bundles
.bundler-temp/
# Generated web bundles (built by CI, not committed)
src/modules/bmm/sub-modules/
src/modules/bmb/sub-modules/
src/modules/cis/sub-modules/
src/modules/bmgd/sub-modules/
shared-modules
z*/
_bmad
_bmad-output
.claude
.clinerules
# .augment/ is gitignored except tracked config files — add exceptions explicitly
.augment/*
!.augment/code_review_guidelines.yaml
.crush
.cursor
.iflow
.opencode
.qwen
.rovodev
.kilocodemodes
.claude/commands
.codex
.github/chatmodes
.github/agents
.agent
.agentvibes/
.kiro/
.agentvibes
.kiro
.roo
.trae
.windsurf
bmad-custom-src/
# Docusaurus / Documentation Build
.docusaurus/
# Astro / Documentation Build
website/.astro/
website/dist/
build/

13
.husky/pre-commit
View File

@ -5,3 +5,16 @@ npx --no-install lint-staged
# Validate everything
npm test
# Validate docs links only when docs change
if command -v rg >/dev/null 2>&1; then
if git diff --cached --name-only | rg -q '^docs/'; then
npm run docs:validate-links
npm run docs:build
fi
else
if git diff --cached --name-only | grep -Eq '^docs/'; then
npm run docs:validate-links
npm run docs:build
fi
fi

3
.markdownlint-cli2.yaml
View File

@ -2,7 +2,7 @@
# https://github.com/DavidAnson/markdownlint-cli2
ignores:
- node_modules/**
- "**/node_modules/**"
- test/fixtures/**
- CODE_OF_CONDUCT.md
- _bmad/**
@ -11,7 +11,6 @@ ignores:
- .claude/**
- .roo/**
- .codex/**
- .agentvibes/**
- .kiro/**
- sample-project/**
- test-project-install/**

6
.npmrc
View File

@ -1 +1,5 @@
registry=https://registry.npmjs.org
# Prevent peer dependency warnings during installation
legacy-peer-deps=true
# Improve install performance
prefer-offline=true

3
.vscode/settings.json vendored
View File

@ -58,8 +58,7 @@
"tmpl",
"Trae",
"Unsharded",
"VNET",
"webskip"
"VNET"
],
"json.schemas": [
{

434
CHANGELOG.md
View File

@ -1,5 +1,438 @@
# Changelog
## [6.0.0-Beta.8]
**Release: February 8, 2026**
### 🌟 Key Highlights
1. **Non-Interactive Installation** — Full CI/CD support with 10 new CLI flags for automated deployments
2. **Complete @clack/prompts Migration** — Unified CLI experience with consolidated installer output
3. **CSV File Reference Validation** — Extended Layer 1 validator to catch broken workflow references in CSV files
4. **Kiro IDE Support** — Standardized config-driven installation, replacing custom installer
### 🎁 Features
* **Non-Interactive Installation** — Added `--directory`, `--modules`, `--tools`, `--custom-content`, `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder`, and `-y/--yes` flags for CI/CD automation (#1520)
* **CSV File Reference Validation** — Extended validator to scan `.csv` files for broken workflow references, checking 501 references across 212 files (#1573)
* **Kiro IDE Support** — Replaced broken custom installer with config-driven templates using `#[[file:...]]` syntax and `inclusion: manual` frontmatter (#1589)
* **OpenCode Template Consolidation** — Combined split templates with `mode: primary` frontmatter for Tab-switching support, fixing agent discovery (#1556)
* **Modules Reference Page** — Added official external modules reference documentation (#1540)
### 🐛 Bug Fixes
* **Installer Streamlining** — Removed "None - Skip module installation" option, eliminated ~100 lines of dead code, and added ESM/.cjs support for module installers (#1590)
* **CodeRabbit Workflow** — Changed `pull_request` to `pull_request_target` to fix 403 errors and enable reviews on fork PRs (#1583)
* **Party Mode Return Protocol** — Added RETURN PROTOCOL to prevent lost-in-the-middle failures after Party Mode completes (#1569)
* **Spacebar Toggle** — Fixed SPACE key not working in autocomplete multiselect prompts for tool/IDE selection (#1557)
* **OpenCode Agent Routing** — Fixed agents installing to wrong directory by adding `targets` array for routing `.opencode/agent/` vs `.opencode/command/` (#1549)
* **Technical Research Workflow** — Fixed step-05 routing to step-06 and corrected `stepsCompleted` values (#1547)
* **Forbidden Variable Removal** — Removed `workflow_path` variable from 16 workflow step files (#1546)
* **Kilo Installer** — Fixed YAML formatting issues by trimming activation header and converting to yaml.parse/stringify (#1537)
* **bmad-help** — Now reads project-specific docs and respects `communication_language` setting (#1535)
* **Cache Errors** — Removed `--prefer-offline` npm flag to prevent stale cache errors during installation (#1531)
### ♻️ Refactoring
* **Complete @clack/prompts Migration** — Migrated 24 files from legacy libraries (ora, chalk, boxen, figlet, etc.), replaced ~100 console.log+chalk calls, consolidated installer output to single spinner, and removed 5 dependencies (#1586)
* **Downloads Page Removal** — Removed downloads page, bundle generation, and archiver dependency in favor of GitHub's native archives (#1577)
* **Workflow Verb Standardization** — Replaced "invoke/run" with "load and follow/load" in review workflow prompts (#1570)
* **Documentation Language** — Renamed "brownfield" to "established projects" and flattened directory structure for accessibility (#1539)
### 📚 Documentation
* **Comprehensive Site Review** — Fixed broken directory tree diagram, corrected grammar/capitalization, added SEO descriptions, and reordered how-to guides (#1578)
* **SEO Metadata** — Added description front matter to 9 documentation pages for search engine optimization (#1566)
* **PR Template** — Added pull request template for consistent PR descriptions (#1554)
* **Manual Release Cleanup** — Removed broken manual-release workflow and related scripts (#1576)
### 🔧 Maintenance
* **Dual-Mode AI Code Review** — Configured Augment Code (audit mode) and CodeRabbit (adversarial mode) for improved code quality (#1511)
* **Package-Lock Sync** — Cleaned up 471 lines of orphaned dependencies after archiver removal (#1580)
---
## [6.0.0-Beta.7]
**Release: February 4, 2026**
### 🌟 Key Highlights
1. **Direct Workflow Invocation** — Agent workflows can now be run directly via slash commands instead of only through agent orchestration
2. **Installer Workflow Support** — Installer now picks up `workflow-*.md` files, enabling multiple workflow files per directory
### 🎁 Features
* **Slash Command Workflow Access** — Research and PRD workflows now accessible via direct slash commands: `/domain-research`, `/market-research`, `/technical-research`, `/create-prd`, `/edit-prd`, `/validate-prd` (bd620e38, 731bee26)
* **Version Checking** — CLI now checks npm for newer versions and displays a warning banner when updates are available (d37ee7f2)
### ♻️ Refactoring
* **Workflow File Splitting** — Split monolithic `workflow.md` files into specific `workflow-*.md` files for individual workflow invocation (bd620e38)
* **Installer Multi-Workflow Support** — Installer manifest generator now supports `workflow-*.md` pattern, allowing multiple workflow files per directory (731bee26)
* **Internal Skill Renaming** — Renamed internal project skills to use `bmad-os-` prefix for consistent naming (5276d58b)
---
## [6.0.0-Beta.6]
**Release: February 4, 2026**
### 🌟 Key Highlights
1. **Cross-File Reference Validator**: Comprehensive tool to detect broken file references, preventing 59 known bugs (~25% of historical issues)
2. **New AutocompleteMultiselect Prompt**: Searchable multi-select with improved tool/IDE selection UX
3. **Critical Installer Fixes**: Windows CRLF parsing, Gemini CLI TOML support, file extension preservation
4. **Codebase Cleanup**: Removed dead Excalidraw/flattener artifacts (-3,798 lines)
### 🎁 Features
* **Cross-File Reference Validator** — Validates ~483 references across ~217 source files, detecting absolute path leaks and broken references (PR #1494)
* **AutocompleteMultiselect Prompt** — Upgraded `@clack/prompts` to v1.0.0 with custom searchable multiselect, Tab-to-fill-placeholder behavior, and improved tool/IDE selection UX (PR #1514)
* **OT Domains** — Added `process_control` and `building_automation` domains with high complexity ratings (PR #1510)
* **Documentation Reference Pages** — Added `docs/reference/agents.md`, `commands.md`, and `testing.md` (PR #1525)
### 🐛 Bug Fixes
* **Critical Installer Fixes** — Fixed CRLF line ending parsing on Windows, Gemini CLI TOML support, file extension preservation, Codex task generation, Windows path handling, and CSV parsing (PR #1492)
* **Double Tool Questioning** — Removed redundant tool questioning during installation (df176d42)
* **QA Agent Rename** — Renamed Quinn agent to `qa` for naming consistency (PR #1508)
* **Documentation Organization** — Fixed documentation ordering and links, hide BMGD pages from main LLM docs (PR #1525)
### ♻️ Refactoring
* **Excalidraw/Flattener Removal** — Removed dead artifacts no longer supported beyond beta: Excalidraw workflows, flattener tool, and 12+ diagram creation workflows (-3,798 lines) (f699a368)
* **Centralized Constants** — Centralized `BMAD_FOLDER_NAME` to reduce hardcoded strings (PR #1492)
* **Cross-Platform Paths** — Fixed path separator inconsistencies in agent IDs (PR #1492)
### 📚 Documentation
* **BMGD Diataxis Refactor** — Refactored BMGD documentation using Diataxis principles for better organization (PR #1502)
* **Generate Project Context** — Restored `generate-project-context` workflow for brownfield project analysis (PR #1491)
### 🔧 Maintenance
* **Dependency Updates** — Upgraded `@clack/prompts` from v0.11.0 to v1.0.0 and added `@clack/core` (PR #1514)
* **CI Integration** — Added `validate:refs` to CI quality workflow with warning annotations (PR #1494)
---
## [6.0.0-Beta.5]
### 🎁 Features
* **Add generate-project-context workflow** — New 3-step workflow for project context generation, integrated with quick-flow-solo-dev agent
* **Shard market research customer analysis** — Refactor monolithic customer insights into 4-step detailed customer behavior analysis workflow
### 🐛 Bug Fixes
* **Fix npm install peer dependency issues** — Add `.npmrc` with `legacy-peer-deps=true`, update Starlight to 0.37.5, and add `--legacy-peer-deps` flag to module installer (PR #1476)
* **Fix leaked source paths in PRD validation report** — Replace absolute `/src/core/` paths with `{project-root}/_bmad/core/` (#1481)
* **Fix orphaned market research customer analysis** — Connect step-01-init to step-02-customer-behavior to complete workflow sharding (#1486)
* **Fix duplicate 2-letter brainstorming code** — Change BS to BSP to resolve conflict with cis Brainstorming module
* **Fix tech writer sidecar functionality** — Enable proper sidecar operation (#1487)
* **Fix relative paths in workflow steps** — Correct paths in step-11-polish (#1497) and step-e-04-complete (#1498)
* **Fix party-mode workflow file extension** — Correct extension in workflow.xml (#1499)
* **Fix generated slash commands** — Add `disable-model-invocation` to all generated commands (#1501)
* **Fix agent scan and help CSV files** — Correct module-help.csv entries
* **Fix HELP_STEP placeholder replacement** — Fix placeholder not replaced in compiled agents, fix hardcoded path, fix single quote (#1437)
### 📚 Documentation
* **Add exact slash commands to Getting Started guide** — Provide precise command examples for users (#1505)
* **Remove .claude/commands from version control** — Commands are generated, not tracked (#1506)
### 🔧 Maintenance
* **Update Starlight to 0.37.5** — Latest version with peer dependency compatibility
* **Add GitHub issue templates** — New bug-report.yaml and documentation.yaml templates
---
## [6.0.0-Beta.4]
### 🐛 Bug Fixes
- **Activation steps formatting fix**: Fixed missing opening quote that caused infrequent menu rendering issues
- **Custom module installation fix**: Added missing yaml require in manifest.js to fix custom module installation
---
## [6.0.0-Beta.3]
### 🌟 Key Highlights
1. **SDET Module Replaces TEA**: TEA module removed from core, SDET module added with "automate" workflow for test automation
2. **Gemini CLI TOML Support**: IDE integration now supports the TOML config format used by Gemini CLI
3. **File System Sprint Status**: Default project_key support for file-system based sprint status tracking
### 🔧 Features & Improvements
**Module Changes:**
- **TEA Module Moved to External** (#1430, #1443): The TEA module is now external. SDET module added with a single "automate" workflow focused on test automation
- **SDET Module**: New module with streamlined test automation capabilities
**IDE Integration:**
- **Gemini CLI TOML Format** (#1431): Previous update accidentally switched Gemini to md instead of toml.
**Sprint Status:**
- **Default project_key** (#1446): File-system based sprint status now uses a default project_key so certain LLMs do not complain
### 🐛 Bug Fixes
- **Quick-flow workflow path fix** (#1368): Fixed incorrect workflow_path in bmad-quick-flow/quick-spec steps (step-01, step-02, step-03) - changed from non-existent 'create-tech-spec' to correct 'quick-spec'
- **PRD edit flow paths**: Fixed path references in PRD editing workflow
- **Agent file handling**: Changes to prevent double agent files and use .agent.md file extensions
- **README link fix**: Corrected broken documentation links
## [6.0.0-Beta.2]
- Fix installer so commands match what is installed, centralize most ide into a central file instead of separate files for each ide.
- Specific IDEs may still need udpates, but all is config driven now and should be easier to maintain
- Kiro still needs updates, but its been in this state since contributed, will investigate soon
- Any version older than Beta.0 will recommend removal and reinstall to project. From later alphas though its sufficient to quick update if still desired, but best is just start fresh with Beta.
## [6.0.0-Beta.1]
**Release: January 2026 - Alpha to Beta Transition**
### 🎉 Beta Release
- **Transition from Alpha to Beta**: BMad Method is now in Beta! This marks a significant milestone in the framework's development
- **NPM Default Tag**: Beta versions are now published with the `latest` tag, making `npx bmad-method` serve the beta version by default
### 🌟 Key Highlights
1. **bmad-help**: Revolutionary AI-powered guidance system replaces the alpha workflow-init and workflow tracking — introduces full AI intelligence to guide users through workflows, commands, and project context
2. **Module Ecosystem Expansion**: bmad-builder, CIS (Creative Intelligence Suite), and Game Dev Studio moved to separate repositories for focused development
3. **Installer Consolidation**: Unified installer architecture with standardized command naming (`bmad-dash-case.md` or `bmad-*-agent-*.md`)
4. **Windows Compatibility**: Complete migration from Inquirer.js to @clack/prompts for reliable cross-platform support
### 🚀 Major Features
**bmad-help - Intelligent Guidance System:**
- **Replaces**: workflow-init and legacy workflow tracking
- **AI-Powered**: Full context awareness of installed modules, workflows, agents, and commands
- **Dynamic Discovery**: Automatically catalogs all available workflows from installed modules
- **Intelligent Routing**: Guides users to the right workflow or agent based on their goal
- **IDE Integration**: Generates proper IDE command files for all discovered workflows
**Module Restructuring:**
| Module | Status | New Location |
| ------------------------------------- | ------------------------------------------------- | ------------------------------------------------------- |
| **bmad-builder** | Near beta, with docs and walkthroughs coming soon | `bmad-code-org/bmad-builder` |
| **CIS** (Creative Intelligence Suite) | Published as npm package | `bmad-code-org/bmad-module-creative-intelligence-suite` |
| **Game Dev Studio** | Published as npm package | `bmad-code-org/bmad-module-game-dev-studio` |
### 🔧 Installer & CLI Improvements
**UnifiedInstaller Architecture:**
- All IDE installers now use a common `UnifiedInstaller` class
- Standardized command naming conventions:
- Workflows: `bmad-module-workflow-name.md`
- Agents: `bmad-module-agent-name.md`
- Tasks: `bmad-task-name.md`
- Tools: `bmad-tool-name.md`
- External module installation from npm with progress indicators
- Module removal on unselect with confirmation
**Windows Compatibility Fix:**
- Replaced Inquirer.js with @clack/prompts to fix arrow key navigation issues on Windows
- All 91 installer workflows migrated to new prompt system
### 📚 Documentation Updates
**Significant docsite improvements:**
- Interactive workflow guide page (`/workflow-guide`) with track selector
- TEA documentation restructured using Diátaxis framework (25 docs)
- Style guide optimized for LLM readers (367 lines, down from 767)
- Glossary rewritten using table format (123 lines, down from 373)
- README overhaul with numbered command flows and prominent `/bmad-help` callout
- New workflow map diagram with interactive HTML
- New editorial review tasks for document quality
- E2E testing methodology for Game Dev Studio
More documentation updates coming soon.
### 🐛 Bug Fixes
- Fixed TodoMVC URL references to include `/dist/` path
- Fixed glob pattern normalization for Windows compatibility
- Fixed YAML indentation in kilo.js customInstructions field
- Fixed stale path references in check-implementation-readiness workflow
- Fixed sprint-status.yaml sync in correct-course workflow
- Fixed web bundler entry point reference
- Fixed mergeModuleHelpCatalogs ordering after generateManifests
### 📊 Statistics
- **91 commits** since alpha.23
- **969 files changed** (+23,716 / -91,509 lines)
- **Net reduction of ~67,793 lines** through cleanup and consolidation
- **3 major modules** moved to separate repositories
- **Complete installer refactor** for standardization
---
## [6.0.0-alpha.23]
**Release: January 11, 2026**
### 🌟 Key Highlights
1. **Astro/Starlight Documentation Platform**: Complete migration from Docusaurus to modern Astro+Starlight for superior performance and customization
2. **Diataxis Framework Implementation**: Professional documentation restructuring with tutorials, how-to guides, explanations, and references
3. **Workflow Creator & Validator**: Powerful new tools for workflow creation with subprocess support and PRD validation
4. **TEA Documentation Expansion**: Comprehensive testing documentation with cheat sheets, MCP enhancements, and API testing patterns
5. **Brainstorming Revolution**: Research-backed procedural rigor with 100+ idea goal and anti-bias protocols
6. **Cursor IDE Modernization**: Refactored from rules-based to command-based architecture for better IDE integration
### 📚 Documentation Platform Revolution
**Astro/Starlight Migration:**
- **From Docusaurus to Astro**: Complete platform migration for improved performance, better customization, and modern tooling
- **Starlight Theme**: Professional documentation theme with dark mode default and responsive design
- **Build Pipeline Overhaul**: New build-docs.js orchestrates link checking, artifact generation, and Astro build
- **LLM-Friendly Documentation**: Generated llms.txt and llms-full.txt for AI agent discoverability
- **Downloadable Source Bundles**: bmad-sources.zip and bmad-prompts.zip for offline use
**Diataxis Framework Implementation:**
- **Four Content Types**: Professional separation into tutorials, how-to guides, explanations, and references
- **21 Files Migrated**: Phase 1 migration of core documentation to Diataxis structure
- **42+ Focused Documents**: Phase 2 split of large legacy files into manageable pieces
- **FAQ Restructuring**: 7 topic-specific FAQ files with standardized format
- **Tutorial Style Guide**: Comprehensive documentation standards for consistent content creation
**Link Management & Quality:**
- **Site-Relative Links**: Converted 217 links to repo-relative format (/docs/path/file.md)
- **Link Validation Tools**: New validate-doc-links.js and fix-doc-links.js for maintaining link integrity
- **Broken Link Fixes**: Resolved ~50 broken internal links across documentation
- **BMad Acronym Standardization**: Consistent use of "BMad" (Breakthrough Method of Agile AI Driven Development)
- **SEO Optimization**: Absolute URLs in AI meta tags for better web crawler discoverability
### 🔧 Workflow Creator & Validator (Major Feature)
**Workflow Creation Tool:**
- **Subprocess Support**: Advanced workflows can now spawn subprocesses for complex operations
- **PRD Validation Step**: New validation step ensures PRD quality before workflow execution
- **Trimodal Workflow Creation**: Three-mode workflow generation system
- **Quadrivariate Module Workflow**: Four-variable workflow architecture for enhanced flexibility
- **Path Violation Checks**: Validator ensures workflows don't violate path constraints
- **Max Parallel Mode POC**: Proof-of-concept for parallel workflow validation
**Workflow Quality Improvements:**
- **PRD Trimodal Compliance**: PRD workflow now follows trimodal standards
- **Standardized Step Formatting**: Consistent markdown formatting across workflow and PRD steps
- **Better Suggested Next Steps**: Improved workflow completion guidance
- **Variable Naming Standardization**: {project_root} → {project-root} across all workflows
### 🧪 TEA Documentation Expansion
**Comprehensive Testing Guides:**
- **Cheat Sheets**: Quick reference guides for common testing scenarios
- **MCP Enhancements**: Model Context Protocol improvements for testing workflows
- **API Testing Patterns**: Best practices for API testing documentation
- **Design Philosophy Callout**: Clear explanation of TEA's design principles
- **Context Engineering Glossary**: New glossary entry defining context engineering concepts
- **Fragment Count Updates**: Accurate documentation of TEA workflow components
- **Playwright Utils Examples**: Updated code examples for playwright-utils integration
### 💡 Brainstorming Workflow Overhaul
**Research-Backed Procedural Rigor:**
- **100+ Idea Goal**: Emphasis on quantity-first approach to unlock better quality ideas
- **Anti-Bias Protocol**: Domain pivot every 10 ideas to reduce cognitive biases
- **Chain-of-Thought Requirements**: Reasoning before idea generation
- **Simulated Temperature**: Prompts for higher divergence in ideation
- **Standardized Idea Format**: Quality control template for consistent output
- **Energy Checkpoints**: Multiple continuation options to maintain creative flow
**Exploration Menu Improvements:**
- **Letter-Based Navigation**: [K/T/A/B/C] options instead of numbers for clarity
- **Keep/Try/Advanced/Break/Continue**: Clear action options for idea refinement
- **Universal Facilitation Rules**: Consistent guidelines across all brainstorming steps
- **Quality Growth Enforcement**: Balance between quantity and quality metrics
### 🖥️ Cursor IDE Modernization
**Command-Based Architecture:**
- **From Rules to Commands**: Complete refactor from rules-based to command-based system
- **Command Generation**: Automatic generation of task and tool commands
- **Commands Directory**: New `.cursor/commands/bmad/` structure for generated commands
- **Cleanup Integration**: Automatic cleanup of old BMAD commands alongside rules
- **Enhanced Logging**: Better feedback on agents, tasks, tools, and workflow commands generated
### 🤖 Agent System Improvements
**Agent Builder & Validation:**
- **hasSidecar Field**: All agents now indicate sidecar support (true/false)
- **Validation Enforcement**: hasSidecar now required in agent validation
- **Better Brownfield Documentation**: Improved brownfield project documentation
- **Agent Builder Updates**: Agent builder now uses hasSidecar field
- **Agent Editor Integration**: Editor workflow respects hasSidecar configuration
### 🐛 Bug Fixes & Quality Improvements
**Critical Fixes:**
- **Windows Line Endings**: Resolved CRLF issues causing cross-platform problems
- **Code-Review File Filtering**: Fixed code-review picking up non-application files
- **ERR_REQUIRE_ESM Resolution**: Dynamic import for inquirer v9+ compatibility
- **Project-Context Conflicts**: Allow full project-context usage with conflict precedence
- **Workflow Paths**: Fixed paths for workflow and sprint status files
- **Missing Scripts**: Fixed missing scripts from installation
**Workflow & Variable Fixes:**
- **Variable Naming**: Standardized from {project_root} to {project-root} across CIS, BMGD, and BMM modules
- **Workflow References**: Fixed broken .yaml → .md workflow references
- **Advanced Elicitation Variables**: Fixed undefined variables in brainstorming
- **Dependency Format**: Corrected dependency format and added missing frontmatter
**Code Quality:**
- **Dependency Updates**: Bumped qs from 6.14.0 to 6.14.1
- **CodeRabbit Integration**: Enabled auto-review on new PRs
- **TEA Fragment Counts**: Updated fragment counts for accuracy
- **Documentation Links**: Fixed Discord channel references (#general-dev → #bmad-development)
### 🚀 Installation & CLI Improvements
**Installation Enhancements:**
- **Workflow Exclusion**: Ability to exclude workflows from being added as commands
- **Example Workflow Protection**: Example workflow in workflow builder now excluded from tools
- **CNAME Configuration**: Added CNAME file for custom domain support
- **Script Fixes**: All scripts now properly included in installation
### 📊 Statistics
- **27 commits** since alpha.22
- **217 documentation links** converted to site-relative format
- **42+ focused documents** created from large legacy files
- **7 topic-specific FAQ files** with standardized formatting
- **Complete documentation platform** migrated from Docusaurus to Astro/Starlight
- **Major workflow tools** added: Creator, Validator with subprocess support
- **Brainstorming workflow** overhauled with research-backed rigor
---
## [6.0.0-alpha.22]
**Release: December 31, 2025**
@ -886,7 +1319,6 @@ Located in `src/modules/bmb/workflows/agent/data/`:
- **Workflow Vendoring**: Web bundler performs automatic cross-module dependency vendoring
- **BMGD Module Extraction**: Game development split into standalone 4-phase structure
- **Enhanced Dependency Resolution**: Better handling of web_bundle: false workflows
- **Advanced Elicitation Fix**: Added missing CSV files to workflow bundles
- **Claude Code Fix**: Resolved README slash command installation regression

11
CLAUDE.md
View File

@ -8,10 +8,7 @@ BMad Method is an AI-driven agile development framework built on BMad Core (Coll
**Key Modules:**
- **Core** (`src/core/`) - Universal framework with shared agents, tasks, and workflows
- **BMM** (`src/modules/bmm/`) - BMad Method for agile software development (flagship module)
- **BMB** (`src/modules/bmb/`) - BMad Builder for creating custom agents/workflows
- **BMGD** (`src/modules/bmgd/`) - Game development workflows
- **CIS** (`src/modules/cis/`) - Creative Intelligence Suite
- **BMM** (`src/bmm/`) - BMad Method for agile software development (flagship module)
## Common Commands
@ -41,7 +38,7 @@ npm run test:coverage # Generate coverage report with c8
## Architecture
### Module Structure
Each module in `src/modules/` follows this pattern:
Each module in `src/` follows this pattern:
```
module/
├── module.yaml # Module configuration and installer prompts
@ -55,7 +52,7 @@ module/
### Agent YAML Schema
Agent files (`*.agent.yaml`) are validated by `tools/schema/agent.js` using Zod. Key rules:
- Required fields: `id`, `name`, `title`, `icon`, `persona`, `menu`
- Module agents must have `module` field matching their path (e.g., `bmm` for files in `src/modules/bmm/agents/`)
- Module agents must have `module` field matching their path (e.g., `bmm` for files in `src/bmm/agents/`)
- Menu triggers must be kebab-case or compound format (`TS or fuzzy match on tech-spec`)
- Test fixtures in `test/fixtures/agent-schema/` demonstrate valid/invalid patterns
@ -72,7 +69,7 @@ Workflows are YAML files that guide multi-step processes. Located in module `wor
## Development Notes
### Adding New Agents
1. Create `*.agent.yaml` in appropriate `src/modules/*/agents/` directory
1. Create `*.agent.yaml` in appropriate `src/*/agents/` directory
2. Follow schema in `tools/schema/agent.js`
3. Validate with `npm run validate:schemas`
4. Add test fixtures if introducing new validation patterns

1
CNAME Normal file
View File

@ -0,0 +1 @@
docs.bmad-method.org

320
CONTRIBUTING.md
View File

@ -1,266 +1,176 @@
# Contributing to BMad
Thank you for considering contributing to the BMad project! We believe in **Human Amplification, Not Replacement** - bringing out the best thinking in both humans and AI through guided collaboration.
Thank you for considering contributing! We believe in **Human Amplification, Not Replacement** — bringing out the best thinking in both humans and AI through guided collaboration.
💬 **Discord Community**: Join our [Discord server](https://discord.gg/gk8jAdXWmj) for real-time discussions:
💬 **Discord**: [Join our community](https://discord.gg/gk8jAdXWmj) for real-time discussions, questions, and collaboration.
- **#general-dev** - Technical discussions, feature ideas, and development questions
- **#bugs-issues** - Bug reports and issue discussions
---
## Our Philosophy
### BMad Core™: Universal Foundation
BMad strengthens human-AI collaboration through specialized agents and guided workflows. Every contribution should answer: **"Does this make humans and AI better together?"**
BMad Core empowers humans and AI agents working together in true partnership across any domain through our **C.O.R.E. Framework** (Collaboration Optimized Reflection Engine):
- **Collaboration**: Human-AI partnership where both contribute unique strengths
- **Optimized**: The collaborative process refined for maximum effectiveness
- **Reflection**: Guided thinking that helps discover better solutions and insights
- **Engine**: The powerful framework that orchestrates specialized agents and workflows
### BMad Method™: Agile AI-Driven Development
The BMad Method is the flagship bmad module for agile AI-driven software development. It emphasizes thorough planning and solid architectural foundations to provide detailed context for developer agents, mirroring real-world agile best practices.
### Core Principles
**Partnership Over Automation** - AI agents act as expert coaches, mentors, and collaborators who amplify human capability rather than replace it.
**Bidirectional Guidance** - Agents guide users through structured workflows while users push agents with advanced prompting. Both sides actively work to extract better information from each other.
**Systems of Workflows** - BMad Core builds comprehensive systems of guided workflows with specialized agent teams for any domain.
**Tool-Agnostic Foundation** - BMad Core remains tool-agnostic, providing stable, extensible groundwork that adapts to any domain.
## What Makes a Good Contribution?
Every contribution should strengthen human-AI collaboration. Ask yourself: **"Does this make humans and AI better together?"**
**✅ Contributions that align:**
- Enhance universal collaboration patterns
- Improve agent personas and workflows
- Strengthen planning and context continuity
- Increase cross-domain accessibility
- Add domain-specific modules leveraging BMad Core
**❌ What detracts from our mission:**
**✅ What we welcome:**
- Enhanced collaboration patterns and workflows
- Improved agent personas and prompts
- Domain-specific modules leveraging BMad Core
- Better planning and context continuity
**❌ What doesn't fit:**
- Purely automated solutions that sideline humans
- Tools that don't improve the partnership
- Complexity that creates barriers to adoption
- Features that fragment BMad Core's foundation
## Before You Contribute
---
### Reporting Bugs
## Reporting Issues
1. **Check existing issues** first to avoid duplicates
2. **Consider discussing in Discord** (#bugs-issues channel) for quick help
3. **Use the bug report template** when creating a new issue - it guides you through providing:
- Clear bug description
- Steps to reproduce
- Expected vs actual behavior
- Model/IDE/BMad version details
- Screenshots or links if applicable
4. **Indicate if you're working on a fix** to avoid duplicate efforts
**ALL bug reports and feature requests MUST go through GitHub Issues.**
### Suggesting Features or New Modules
### Before Creating an Issue
1. **Discuss first in Discord** (#general-dev channel) - the feature request template asks if you've done this
2. **Check existing issues and discussions** to avoid duplicates
3. **Use the feature request template** when creating an issue
4. **Be specific** about why this feature would benefit the BMad community and strengthen human-AI collaboration
1. **Search existing issues** — Use the GitHub issue search to check if your bug or feature has already been reported
2. **Search closed issues** — Your issue may have been fixed or addressed previously
3. **Check discussions** — Some conversations happen in [GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions)
### Before Starting Work
### Bug Reports
After searching, if the bug is unreported, use the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md) and include:
- Clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Your environment (model, IDE, BMad version)
- Screenshots or error messages if applicable
### Feature Requests
After searching, use the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md) and explain:
- What the feature is
- Why it would benefit the BMad community
- How it strengthens human-AI collaboration
**For community modules**, review [TRADEMARK.md](TRADEMARK.md) for proper naming conventions (e.g., "My Module (BMad Community Module)").
---
## Before Starting Work
⚠️ **Required before submitting PRs:**
1. **For bugs**: Check if an issue exists (create one using the bug template if not)
2. **For features**: Discuss in Discord (#general-dev) AND create a feature request issue
3. **For large changes**: Always open an issue first to discuss alignment
| Work Type | Requirement |
| ------------- | ---------------------------------------------- |
| Bug fix | An open issue (create one if it doesn't exist) |
| Feature | An open feature request issue |
| Large changes | Discussion via issue first |
Please propose small, granular changes! For large or significant changes, discuss in Discord and open an issue first. This prevents wasted effort on PRs that may not align with planned changes.
**Why?** This prevents wasted effort on work that may not align with project direction.
---
## Pull Request Guidelines
### Which Branch?
### Target Branch
**Submit PR's to `main` branch** (critical only):
Submit PRs to the `main` branch.
- 🚨 Critical bug fixes that break basic functionality
- 🔒 Security patches
- 📚 Fixing dangerously incorrect documentation
- 🐛 Bugs preventing installation or basic usage
### PR Size
### PR Size Guidelines
- **Ideal**: 200-400 lines of code changes
- **Maximum**: 800 lines (excluding generated files)
- **One feature/fix per PR**
- **Ideal PR size**: 200-400 lines of code changes
- **Maximum PR size**: 800 lines (excluding generated files)
- **One feature/fix per PR**: Each PR should address a single issue or add one feature
- **If your change is larger**: Break it into multiple smaller PRs that can be reviewed independently
- **Related changes**: Even related changes should be separate PRs if they deliver independent value
If your change exceeds 800 lines, break it into smaller PRs that can be reviewed independently.
### Breaking Down Large PRs
### New to Pull Requests?
If your change exceeds 800 lines, use this checklist to split it:
- [ ] Can I separate the refactoring from the feature implementation?
- [ ] Can I introduce the new API/interface in one PR and implementation in another?
- [ ] Can I split by file or module?
- [ ] Can I create a base PR with shared utilities first?
- [ ] Can I separate test additions from implementation?
- [ ] Even if changes are related, can they deliver value independently?
- [ ] Can these changes be merged in any order without breaking things?
Example breakdown:
1. PR #1: Add utility functions and types (100 lines)
2. PR #2: Refactor existing code to use utilities (200 lines)
3. PR #3: Implement new feature using refactored code (300 lines)
4. PR #4: Add comprehensive tests (200 lines)
**Note**: PRs #1 and #4 could be submitted simultaneously since they deliver independent value.
### Pull Request Process
#### New to Pull Requests?
If you're new to GitHub or pull requests, here's a quick guide:
1. **Fork the repository** - Click the "Fork" button on GitHub to create your own copy
2. **Clone your fork** - `git clone https://github.com/YOUR-USERNAME/bmad-method.git`
3. **Create a new branch** - Never work on `main` directly!
```bash
git checkout -b fix/description
# or
git checkout -b feature/description
```
4. **Make your changes** - Edit files, keeping changes small and focused
5. **Commit your changes** - Use clear, descriptive commit messages
```bash
git add .
git commit -m "fix: correct typo in README"
```
6. **Push to your fork** - `git push origin fix/description`
7. **Create the Pull Request** - Go to your fork on GitHub and click "Compare & pull request"
1. **Fork** the repository
2. **Clone** your fork: `git clone https://github.com/YOUR-USERNAME/bmad-method.git`
3. **Create a branch**: `git checkout -b fix/description` or `git checkout -b feature/description`
4. **Make changes** — keep them focused
5. **Commit**: `git commit -m "fix: correct typo in README"`
6. **Push**: `git push origin fix/description`
7. **Open PR** from your fork on GitHub
### PR Description Template
Keep your PR description concise and focused. Use this template:
```markdown
## What
[1-2 sentences describing WHAT changed]
## Why
[1-2 sentences explaining WHY this change is needed]
Fixes #[issue number] (if applicable)
Fixes #[issue number]
## How
## [2-3 bullets listing HOW you implemented it]
-
- [2-3 bullets listing HOW you implemented it]
-
## Testing
[1-2 sentences on how you tested this]
```
**Maximum PR description length: 200 words** (excluding code examples if needed)
**Keep it under 200 words.**
### Good vs Bad PR Descriptions
### Commit Messages
❌ **Bad Example:**
> This revolutionary PR introduces a paradigm-shifting enhancement to the system's architecture by implementing a state-of-the-art solution that leverages cutting-edge methodologies to optimize performance metrics...
✅ **Good Example:**
> **What:** Added validation for agent dependency resolution
> **Why:** Build was failing silently when agents had circular dependencies
> **How:**
>
> - Added cycle detection in dependency-resolver.js
> - Throws clear error with dependency chain
> **Testing:** Tested with circular deps between 3 agents
### Commit Message Convention
Use conventional commits format:
Use conventional commits:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation only
- `refactor:` Code change that neither fixes a bug nor adds a feature
- `test:` Adding missing tests
- `chore:` Changes to build process or auxiliary tools
- `refactor:` Code change (no bug/feature)
- `test:` Adding tests
- `chore:` Build/tools changes
Keep commit messages under 72 characters.
### Atomic Commits
Each commit should represent one logical change:
- **Do:** One bug fix per commit
- **Do:** One feature addition per commit
- **Don't:** Mix refactoring with bug fixes
- **Don't:** Combine unrelated changes
## What Makes a Good Pull Request?
✅ **Good PRs:**
- Change one thing at a time
- Have clear, descriptive titles
- Explain what and why in the description
- Include only the files that need to change
- Reference related issue numbers
❌ **Avoid:**
- Changing formatting of entire files
- Multiple unrelated changes in one PR
- Copying your entire project/repo into the PR
- Changes without explanation
- Working directly on `main` branch
## Common Mistakes to Avoid
1. **Don't reformat entire files** - only change what's necessary
2. **Don't include unrelated changes** - stick to one fix/feature per PR
3. **Don't paste code in issues** - create a proper PR instead
4. **Don't submit your whole project** - contribute specific improvements
## Prompt & Agent Guidelines
- Keep dev agents lean - they need context for coding, not documentation
- Web/planning agents can be larger with more complex tasks
- Everything is natural language (markdown) - no code in core framework
- Use bmad modules for domain-specific features
- Validate YAML schemas with `npm run validate:schemas` before committing
## Code of Conduct
By participating in this project, you agree to abide by our Code of Conduct. We foster a collaborative, respectful environment focused on building better human-AI partnerships.
## Need Help?
- 💬 Join our [Discord Community](https://discord.gg/gk8jAdXWmj):
- **#general-dev** - Technical questions and feature discussions
- **#bugs-issues** - Get help with bugs before filing issues
- 🐛 Report bugs using the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md)
- 💡 Suggest features using the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md)
- 📖 Browse the [GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions)
Keep messages under 72 characters. Each commit = one logical change.
---
**Remember**: We're here to help! Don't be afraid to ask questions. Every expert was once a beginner. Together, we're building a future where humans and AI work better together.
## What Makes a Good PR?
| ✅ Do | ❌ Don't |
| --------------------------- | ---------------------------- |
| Change one thing per PR | Mix unrelated changes |
| Clear title and description | Vague or missing explanation |
| Reference related issues | Reformat entire files |
| Small, focused commits | Copy your whole project |
| Work on a branch | Work directly on `main` |
---
## Prompt & Agent Guidelines
- Keep dev agents lean — focus on coding context, not documentation
- Web/planning agents can be larger with complex tasks
- Everything is natural language (markdown) — no code in core framework
- Use BMad modules for domain-specific features
- Validate YAML schemas: `npm run validate:schemas`
- Validate file references: `npm run validate:refs`
### File-Pattern-to-Validator Mapping
| File Pattern | Validator | Extraction Function |
| ------------ | --------- | ------------------- |
| `*.yaml`, `*.yml` | `validate-file-refs.js` | `extractYamlRefs` |
| `*.md`, `*.xml` | `validate-file-refs.js` | `extractMarkdownRefs` |
| `*.csv` | `validate-file-refs.js` | `extractCsvRefs` |
---
## Need Help?
- 💬 **Discord**: [Join the community](https://discord.gg/gk8jAdXWmj)
- 🐛 **Bugs**: Use the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md)
- 💡 **Features**: Use the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md)
---
## Code of Conduct
By participating, you agree to abide by our [Code of Conduct](.github/CODE_OF_CONDUCT.md).
## License
By contributing to this project, you agree that your contributions will be licensed under the same license as the project.
By contributing, your contributions are licensed under the same MIT License. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor attribution.

32
CONTRIBUTORS.md Normal file
View File

@ -0,0 +1,32 @@
# Contributors
BMad Core, BMad Method and BMad and Community BMad Modules are made possible by contributions from our community. We gratefully acknowledge everyone who has helped improve this project.
## How We Credit Contributors
- **Git history** — Every contribution is preserved in the project's commit history
- **Contributors badge** — See the dynamic contributors list on our [README](README.md)
- **GitHub contributors graph** — Visual representation at <https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors>
## Becoming a Contributor
Anyone who submits a pull request that is merged becomes a contributor. Contributions include:
- Bug fixes
- New features or workflows
- Documentation improvements
- Bug reports and issue triaging
- Code reviews
- Helping others in discussions
There are no minimum contribution requirements — whether it's a one-character typo fix or a major feature, we value all contributions.
## Copyright
The BMad Method project is copyrighted by BMad Code, LLC. Individual contributions are licensed under the same MIT License as the project. Contributors retain authorship credit through Git history and the contributors graph.
---
**Thank you to everyone who has helped make BMad Method better!**
For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

10
LICENSE
View File

@ -2,6 +2,9 @@ MIT License
Copyright (c) 2025 BMad Code, LLC
This project incorporates contributions from the open source community.
See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor attribution.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
@ -21,6 +24,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
TRADEMARK NOTICE:
BMad™ , BMAD-CORE™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. The use of these
trademarks in this software does not grant any rights to use the trademarks
for any other purpose.
BMad™, BMad Method™, and BMad Core™ are trademarks of BMad Code, LLC, covering all
casings and variations (including BMAD, bmad, BMadMethod, BMAD-METHOD, etc.). The use of
these trademarks in this software does not grant any rights to use the trademarks
for any other purpose. See [TRADEMARK.md](TRADEMARK.md) for detailed guidelines.

276
README.md
View File

@ -1,237 +1,159 @@
# BMad Method & BMad Core
![BMad Method](banner-bmad-method.png)
[![Stable Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=stable)](https://www.npmjs.com/package/bmad-method)
[![Alpha Version](https://img.shields.io/npm/v/bmad-method/alpha?color=orange&label=alpha)](https://www.npmjs.com/package/bmad-method)
[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
---
**Breakthrough Method of Agile AI Driven Development** — An AI-driven agile development framework with 21 specialized agents, 50+ guided workflows, and scale-adaptive intelligence that adjusts from bug fixes to enterprise systems.
<div align="center">
**100% free and open source.** No paywalls. No gated content. No gated Discord. We believe in empowering everyone, not just those who can pay.
## 🎉 NEW: BMAD V6 Installer - Create & Share Custom Content!
## Why BMad?
The completely revamped **BMAD V6 installer** now includes built-in support for creating, installing, and sharing custom modules, agents, workflows, templates, and tools! Build your own AI solutions or share them with your team - and real soon, with the whole BMad Community througha verified community sharing portal!
Traditional AI tools do the thinking for you, producing average results. BMad agents and facilitated workflow act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI.
**✨ What's New:**
- **AI Intelligent Help**: Brand new for beta - AI assisted help will guide you from the beginning to the end - just ask for `/bmad-help` after you have installed BMad to your project
- **Scale-Domain-Adaptive**: Automatically adjusts planning depth and needs based on project complexity, domain and type - a SaaS Mobile Dating App has different planning needs from a diagnostic medical system, BMad adapts and helps you along the way
- **Structured Workflows**: Grounded in agile best practices across analysis, planning, architecture, and implementation
- **Specialized Agents**: 12+ domain experts (PM, Architect, Developer, UX, Scrum Master, and more)
- **Party Mode**: Bring multiple agent personas into one session to plan, troubleshoot, or discuss your project collaboratively, multiple perspectives with maximum fun
- **Complete Lifecycle**: From brainstorming to deployment, BMad is there with you every step of the way
- 📦 **Streamlined Custom Module Installation** - Package your custom content as installable modules
- 🤖 **Agent & Workflow Sharing** - Distribute standalone agents and workflows
- 🔄 **Unitary Module Support** - Install individual components without full modules
- ⚙️ **Dependency Management** - Automatic handling of module dependencies
- 🛡️ **Update-Safe Customization** - Your custom content persists through updates
## Quick Start
**📚 Learn More:**
- [**Custom Content Overview**](docs/modules/bmb-bmad-builder/custom-content.md) - Discover all supported content types
- [**Installation Guide**](docs/modules/bmb-bmad-builder/custom-content-installation.md) - Learn to create and install custom content
- [**2 Very simple Custom Modules of questionable quality**](./samples/sample-custom-modules/README.md) - if you want to download and try to install a custom shared module, get an idea of how to bundle and share your own, or create your own personal agents, workflows and modules.
</div>
---
## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
**Build More, Architect Dreams** (BMAD) with **21 specialized AI agents** across 4 official modules, and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms, and new step file workflows that allow for incredibly long workflows to stay on the rails longer than ever before!
Additionally - when we say 'Build More, Architect Dreams' - we mean it! The BMad Builder has landed, and now as of Alpha.15 is fully supported in the installation flow via NPX - custom stand along agents, workflows and the modules of your dreams! The community forge will soon open, endless possibility awaits!
> **🚀 v6 is a MASSIVE upgrade from v4!** Complete architectural overhaul, scale-adaptive intelligence, visual workflows, and the powerful BMad Core framework. v4 users: this changes everything. [See what's new →](#whats-new-in-v6)
> **📌 v6 Alpha Status:** Near-beta quality with vastly improved stability. Documentation is being finalized. New videos coming soon to [BMadCode YouTube](https://www.youtube.com/@BMadCode).
## 🎯 Why BMad Method?
Unlike generic AI coding assistants, BMad Method provides **structured, battle-tested workflows** powered by specialized agents who understand agile development. Each agent has deep domain expertise—from product management to architecture to testing—working together seamlessly.
**✨ Key Benefits:**
- **Scale-Adaptive Intelligence** - Automatically adjusts planning depth from bug fixes to enterprise systems
- **Complete Development Lifecycle** - Analysis → Planning → Architecture → Implementation
- **Specialized Expertise** - 19 agents with specific roles (PM, Architect, Developer, UX Designer, etc.)
- **Proven Methodologies** - Built on agile best practices with AI amplification
- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code
## 🏗️ The Power of BMad Core
**BMad Method** is actually a sophisticated module built on top of **BMad Core** (**C**ollaboration **O**ptimized **R**eflection **E**ngine). This revolutionary architecture means:
- **BMad Core** provides the universal framework for human-AI collaboration
- **BMad Method** leverages Core to deliver agile development workflows
- **BMad Builder** lets YOU create custom modules as powerful as BMad Method itself
With **BMad Builder**, you can architect both simple agents and vastly complex domain-specific modules (legal, medical, finance, education, creative) that will soon be sharable in an **official community marketplace**. Imagine building and sharing your own specialized AI team!
## 📊 See It In Action
<p align="center">
<img src="./docs/modules/bmm-bmad-method/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
</p>
<p align="center">
<em>Complete BMad Method workflow showing all phases, agents, and decision points</em>
</p>
## 🚀 Get Started in 3 Steps
### 1. Install BMad Method
**Prerequisites**: [Node.js](https://nodejs.org) v20+
```bash
# Install v6 RECOMMENDED
npx bmad-method@alpha install
```
```bash
# Install v4 Legacy (not recommended if starting fresh)
npx bmad-method install
# OR
npx bmad-method@latest install
```
Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, Windsurf, etc.) in the project folder.
### 2. Initialize Your Project
**Non-Interactive Installation**: For CI/CD pipelines or automated deployments, use command-line flags:
Load any agent in your IDE and run:
```
*workflow-init
```bash
npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes
```
This analyzes your project and recommends the right workflow track.
See [Non-Interactive Installation Guide](http://docs.bmad-method.org/how-to/non-interactive-installation/) for all available options.
### 3. Choose Your Track
> **Not sure what to do?** Run `/bmad-help` — it tells you exactly what's next and what's optional. You can also ask it questions like:
BMad Method adapts to your needs with three intelligent tracks:
- `/bmad-help How should I build a web app for my TShirt Business that can scale to millions?`
- `/bmad-help I just finished the architecture, I am not sure what to do next`
| Track | Use For | Planning | Time to Start |
| ----------------- | ------------------------- | ----------------------- | ------------- |
| **⚡ Quick Flow** | Bug fixes, small features | Tech spec only | < 5 minutes |
| **📋 BMad Method** | Products, platforms | PRD + Architecture + UX | < 15 minutes |
| **🏢 Enterprise** | Compliance, scale | Full governance suite | < 30 minutes |
And the amazing thing is BMad Help evolves depending on what modules you install also!
- `/bmad-help Im interested in really exploring creative ways to demo BMad at work, what do you recommend to help plan a great slide deck and compelling narrative?`, and if you have the Creative Intelligence Suite installed, it will offer you different or complimentary advice than if you just have BMad Method Module installed!
> **Not sure?** Run `*workflow-init` and let BMad analyze your project goal.
The workflows below show the fastest path to working code. You can also load agents directly for a more structured process, extensive planning, or to learn about agile development practices — the agents guide you with menus, explanations, and elicitation at each step.
## 🔄 How It Works: 4-Phase Methodology
### Simple Path (Quick Flow)
BMad Method guides you through a proven development lifecycle:
Bug fixes, small features, clear scope — 3 commands - 1 Optional Agent:
1. **📊 Analysis** (Optional) - Brainstorm, research, and explore solutions
2. **📝 Planning** - Create PRDs, tech specs, or game design documents
3. **🏗️ Solutioning** - Design architecture, UX, and technical approach
4. **⚡ Implementation** - Story-driven development with continuous validation
1. `/quick-spec` — analyzes your codebase and produces a tech-spec with stories
2. `/dev-story` — implements each story
3. `/code-review` — validates quality
Each phase has specialized workflows and agents working together to deliver exceptional results.
### Full Planning Path (BMad Method)
## 🤖 Meet Your Team
Products, platforms, complex features — structured planning then build:
**12 Specialized Agents** working in concert:
1. `/product-brief` — define problem, users, and MVP scope
2. `/create-prd` — full requirements with personas, metrics, and risks
3. `/create-architecture` — technical decisions and system design
4. `/create-epics-and-stories` — break work into prioritized stories
5. `/sprint-planning` — initialize sprint tracking
6. **Repeat per story:** `/create-story` → `/dev-story` → `/code-review`
| Development | Architecture | Product | Leadership |
| ----------- | -------------- | ----------- | ------------ |
| Developer | Architect | PM | Scrum Master |
| UX Designer | Test Architect | Analyst | BMad Master |
| | | Tech Writer | |
Every step tells you what's next. Optional phases (brainstorming, research, UX design) are available when you need them — ask `/bmad-help` anytime. For a detailed walkthrough, see the [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/).
**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready web app fixture-based utilities.
## Modules
Each agent brings deep expertise and can be customized to match your team's style.
BMad Method extends with official modules for specialized domains. Modules are available during installation and can be added to your project at any time. After the V6 beta period these will also be available as Plugins and Granular Skills.
## 📦 What's Included
| Module | GitHub | NPM | Purpose |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **BMad Method (BMM)** | [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) | [bmad-method](https://www.npmjs.com/package/bmad-method) | Core framework with 34+ workflows across 4 development phases |
| **BMad Builder (BMB)** | [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) | [bmad-builder](https://www.npmjs.com/package/bmad-builder) | Create custom BMad agents, workflows, and domain-specific modules |
| **Test Architect (TEA)** 🆕 | [bmad-code-org/tea](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | [tea](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) | Risk-based test strategy, automation, and release gates (8 workflows) |
| **Game Dev Studio (BMGD)** | [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | [bmad-game-dev-studio](https://www.npmjs.com/package/bmad-game-dev-studio) | Game development workflows for Unity, Unreal, and Godot |
| **Creative Intelligence Suite (CIS)** | [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | [bmad-creative-intelligence-suite](https://www.npmjs.com/package/bmad-creative-intelligence-suite) | Innovation, brainstorming, design thinking, and problem-solving |
### Official Modules
* More modules are coming in the next 2 weeks from BMad Official, and a community marketplace for the installer also will be coming with the final V6 release!
- **BMad Method (BMM)** - Complete agile development framework
- 12 specialized agents
- 34 workflows across 4 phases
- Stand Along Quick Spec Flow for a streamlined simple implementation process
- [→ Documentation Hub](./docs/modules/bmm-bmad-method/index.md)
## Testing Agents
- **BMad Builder (BMB)** - Create custom agents and workflows
- Build anything from simple agents to complex modules
- Create domain-specific solutions (legal, medical, finance, education)
- [→ Builder Guide](./docs/modules/bmb-bmad-builder/index.md)
BMad provides two testing options to fit your needs:
- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
- Brainstorming, design thinking, storytelling
- 5 creative facilitation workflows
- [→ Creative Workflows](./docs/modules/cis-creative-intelligence-suite/index.md)
### Quinn (QA) - Built-in
### Key Features
**Quick test automation for rapid coverage**
- **🎨 Customizable Agents** - Modify personalities, expertise, and communication styles
- **🌐 Multi-Language Support** - Separate settings for communication and code output
- **📄 Document Sharding** - 90% token savings for large projects
- **🔄 Update-Safe** - Your customizations persist through updates
- **🚀 Web Bundles** - Use in ChatGPT, Claude Projects, or Gemini Gems
- ✅ **Always available** in BMM module (no separate install)
- ✅ **Simple**: One workflow (`QA` - Automate)
- ✅ **Beginner-friendly**: Standard test framework patterns
- ✅ **Fast**: Generate tests and ship
## 📚 Documentation
**Use Quinn for:** Small projects, quick coverage, standard patterns
### Quick Links
### Test Architect (TEA) - Optional Module
- **[Quick Start Guide](./docs/modules/bmm-bmad-method/quick-start.md)** - 15-minute introduction
- **[Complete BMM Documentation](./docs/modules/bmm-bmad-method/index.md)** - All guides and references
- **[Agent Customization](docs/bmad-customization/agent-customization-guide.md)** - Personalize your agents
- **[All Documentation](./docs/index.md)** - Complete documentation index
**Enterprise-grade test strategy and quality engineering**
- 🆕 **Standalone module** (install separately)
- 🏗️ **Comprehensive**: 8 workflows covering full test lifecycle
- 🎯 **Advanced**: Risk-based planning, quality gates, NFR assessment
- 📚 **Knowledge-driven**: 34 testing patterns and best practices
- 📖 [Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
**Use TEA for:** Enterprise projects, test strategy, compliance, release gates
---
## Documentation
**[BMad Documentation](http://docs.bmad-method.org)** — Tutorials, how-to guides, concepts, and reference
**[Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)** — TEA standalone module documentation
- [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/)
- [Upgrading from Previous Versions](http://docs.bmad-method.org/how-to/upgrade-to-v6/)
- [Test Architect Migration Guide](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/migration/) — Upgrading from BMM-embedded TEA
### For v4 Users
- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4/docs)**
- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)**
- If you need to install V4, you can do this with `npx bmad-method@4.44.3 install` - similar for any past version.
## 💬 Community & Support
## Community
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects
- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs, request features
- **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and demos
- **[Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)** - Pre-built agent bundles (Currently not functioning, reworking soon)
- **[Code of Conduct](.github/CODE_OF_CONDUCT.md)** - Community guidelines
- [Discord](https://discord.gg/gk8jAdXWmj) — Get help, share ideas, collaborate
- [Subscribe on YouTube](https://www.youtube.com/@BMadCode) — Tutorials, master class, and podcast (launching Feb 2025)
- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) — Bug reports and feature requests
- [Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions) — Community conversations
## 🛠️ Development
## Support BMad
If you would like to contribute, first check the [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
BMad is free for everyone — and always will be. If you'd like to support development:
## What's New in v6
- ⭐ Please click the star project icon near the top right of this page
- ☕ [Buy Me a Coffee](https://buymeacoffee.com/bmad) — Fuel the development
- 🏢 Corporate sponsorship — DM on Discord
- 🎤 Speaking & Media — Available for conferences, podcasts, interviews (BM on Discord)
**v6 represents a complete architectural revolution from v4:**
## Contributing
### 🚀 Major Upgrades
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
- **BMad Core Framework** - Modular architecture enabling custom domain solutions
- **Scale-Adaptive Intelligence** - Automatic adjustment from bug fixes to enterprise
- **Visual Workflows** - Beautiful SVG diagrams showing complete methodology
- **BMad Builder Module** - Create and share your own AI agent teams
- **50+ Workflows** - Up from 20 in v4, covering every development scenario
- **19 Specialized Agents** - Enhanced with customizable personalities and expertise
- **Update-Safe Customization** - Your configs persist through all updates
- **Web Bundles** - Use agents in ChatGPT, Claude, and Gemini
- **Multi-Language Support** - Separate settings for communication and code
- **Document Sharding** - 90% token savings for large projects
## License
### 🔄 For v4 Users
- **[Comprehensive Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Step-by-step migration
- **[v4 Documentation Archive](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)** - Legacy reference
- Backwards compatibility where possible
- Smooth migration path with installer detection
## 📄 License
MIT License - See [LICENSE](LICENSE) for details.
**Trademarks:** BMad™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
Supported by:&nbsp;&nbsp;<a href="https://m.do.co/c/00f11bd932bb"><img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/SVG/DO_Logo_horizontal_blue.svg" height="24" alt="DigitalOcean" style="vertical-align: middle;"></a>
MIT License — see [LICENSE](LICENSE) for details.
---
<p align="center">
<a href="https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors">
<img src="https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD" alt="Contributors">
</a>
</p>
**BMad** and **BMAD-METHOD** are trademarks of BMad Code, LLC. See [TRADEMARK.md](TRADEMARK.md) for details.
<p align="center">
<sub>Built with ❤️ for the human-AI collaboration community</sub>
</p>
[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor information.

85
SECURITY.md Normal file
View File

@ -0,0 +1,85 @@
# Security Policy
## Supported Versions
We release security patches for the following versions:
| Version | Supported |
| ------- | ------------------ |
| Latest | :white_check_mark: |
| < Latest | :x: |
We recommend always using the latest version of BMad Method to ensure you have the most recent security updates.
## Reporting a Vulnerability
We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly.
### How to Report
**Do NOT report security vulnerabilities through public GitHub issues.**
Instead, please report them via one of these methods:
1. **GitHub Security Advisories** (Preferred): Use [GitHub's private vulnerability reporting](https://github.com/bmad-code-org/BMAD-METHOD/security/advisories/new) to submit a confidential report.
2. **Discord**: Contact a maintainer directly via DM on our [Discord server](https://discord.gg/gk8jAdXWmj).
### What to Include
Please include as much of the following information as possible:
- Type of vulnerability (e.g., prompt injection, path traversal, etc.)
- Full paths of source file(s) related to the vulnerability
- Step-by-step instructions to reproduce the issue
- Proof-of-concept or exploit code (if available)
- Impact assessment of the vulnerability
### Response Timeline
- **Initial Response**: Within 48 hours of receiving your report
- **Status Update**: Within 7 days with our assessment
- **Resolution Target**: Critical issues within 30 days; other issues within 90 days
### What to Expect
1. We will acknowledge receipt of your report
2. We will investigate and validate the vulnerability
3. We will work on a fix and coordinate disclosure timing with you
4. We will credit you in the security advisory (unless you prefer to remain anonymous)
## Security Scope
### In Scope
- Vulnerabilities in BMad Method core framework code
- Security issues in agent definitions or workflows that could lead to unintended behavior
- Path traversal or file system access issues
- Prompt injection vulnerabilities that bypass intended agent behavior
- Supply chain vulnerabilities in dependencies
### Out of Scope
- Security issues in user-created custom agents or modules
- Vulnerabilities in third-party AI providers (Claude, GPT, etc.)
- Issues that require physical access to a user's machine
- Social engineering attacks
- Denial of service attacks that don't exploit a specific vulnerability
## Security Best Practices for Users
When using BMad Method:
1. **Review Agent Outputs**: Always review AI-generated code before executing it
2. **Limit File Access**: Configure your AI IDE to limit file system access where possible
3. **Keep Updated**: Regularly update to the latest version
4. **Validate Dependencies**: Review any dependencies added by generated code
5. **Environment Isolation**: Consider running AI-assisted development in isolated environments
## Acknowledgments
We appreciate the security research community's efforts in helping keep BMad Method secure. Contributors who report valid security issues will be acknowledged in our security advisories.
---
Thank you for helping keep BMad Method and our community safe.

55
TRADEMARK.md Normal file
View File

@ -0,0 +1,55 @@
# Trademark Notice & Guidelines
## Trademark Ownership
The following names and logos are trademarks of BMad Code, LLC:
- **BMad** (word mark, all casings: BMad, bmad, BMAD)
- **BMad Method** (word mark, includes BMadMethod, BMAD-METHOD, and all variations)
- **BMad Core** (word mark, includes BMadCore, BMAD-CORE, and all variations)
- **BMad Code** (word mark)
- BMad Method logo and visual branding
- The "Build More, Architect Dreams" tagline
**All casings, stylings, and variations** of the above names (with or without hyphens, spaces, or specific capitalization) are covered by these trademarks.
These trademarks are protected under trademark law and are **not** licensed under the MIT License. The MIT License applies to the software code only, not to the BMad brand identity.
## What This Means
You may:
- Use the BMad software under the terms of the MIT License
- Refer to BMad to accurately describe compatibility or integration (e.g., "Compatible with BMad Method v6")
- Link to <https://github.com/bmad-code-org/BMAD-METHOD>
- Fork the software and distribute your own version under a different name
You may **not**:
- Use "BMad" or any confusingly similar variation as your product name, service name, company name, or domain name
- Present your product as officially endorsed, approved, or certified by BMad Code, LLC when it is not, without written consent from an authorized representative of BMad Code, LLC
- Use BMad logos or branding in a way that suggests your product is an official or endorsed BMad product
- Register domain names, social media handles, or trademarks that incorporate BMad branding
## Examples
| Permitted | Not Permitted |
| ------------------------------------------------------ | -------------------------------------------- |
| "My workflow tool, compatible with BMad Method" | "BMadFlow" or "BMad Studio" |
| "An alternative implementation inspired by BMad" | "BMad Pro" or "BMad Enterprise" |
| "My Awesome Healthcare Module (Bmad Community Module)" | "The Official BMad Core Healthcare Module" |
| Accurately stating you use BMad as a dependency | Implying official endorsement or partnership |
## Commercial Use
You may sell products that incorporate or work with BMad software. However:
- Your product must have its own distinct name and branding
- You must not use BMad trademarks in your marketing, domain names, or product identity
- You may truthfully describe technical compatibility (e.g., "Works with BMad Method")
## Questions?
If you have questions about trademark usage or would like to discuss official partnership or endorsement opportunities, please reach out:
- **Email**: <contact@bmadcode.com>

BIN
Wordmark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
banner-bmad-method.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 366 KiB

9
docs/404.md Normal file
View File

@ -0,0 +1,9 @@
---
title: Page Not Found
template: splash
---
The page you're looking for doesn't exist or has been moved.
[Return to Home](./index.md)

368
docs/_STYLE_GUIDE.md Normal file
View File

@ -0,0 +1,368 @@
---
title: "Documentation Style Guide"
description: Project-specific documentation conventions based on Google style and Diataxis structure
---
This project adheres to the [Google Developer Documentation Style Guide](https://developers.google.com/style) and uses [Diataxis](https://diataxis.fr/) to structure content. Only project-specific conventions follow.
## Project-Specific Rules
| Rule | Specification |
| -------------------------------- | ---------------------------------------- |
| No horizontal rules (`---`) | Fragments reading flow |
| No `####` headers | Use bold text or admonitions instead |
| No "Related" or "Next:" sections | Sidebar handles navigation |
| No deeply nested lists | Break into sections instead |
| No code blocks for non-code | Use admonitions for dialogue examples |
| No bold paragraphs for callouts | Use admonitions instead |
| 1-2 admonitions per section max | Tutorials allow 3-4 per major section |
| Table cells / list items | 1-2 sentences max |
| Header budget | 8-12 `##` per doc; 2-3 `###` per section |
## Admonitions (Starlight Syntax)
```md
:::tip[Title]
Shortcuts, best practices
:::
:::note[Title]
Context, definitions, examples, prerequisites
:::
:::caution[Title]
Caveats, potential issues
:::
:::danger[Title]
Critical warnings only — data loss, security issues
:::
```
### Standard Uses
| Admonition | Use For |
| ------------------------ | ----------------------------- |
| `:::note[Prerequisites]` | Dependencies before starting |
| `:::tip[Quick Path]` | TL;DR summary at document top |
| `:::caution[Important]` | Critical caveats |
| `:::note[Example]` | Command/response examples |
## Standard Table Formats
**Phases:**
```md
| Phase | Name | What Happens |
| ----- | -------- | -------------------------------------------- |
| 1 | Analysis | Brainstorm, research *(optional)* |
| 2 | Planning | Requirements — PRD or tech-spec *(required)* |
```
**Commands:**
```md
| Command | Agent | Purpose |
| ------------ | ------- | ------------------------------------ |
| `brainstorm` | Analyst | Brainstorm a new project |
| `prd` | PM | Create Product Requirements Document |
```
## Folder Structure Blocks
Show in "What You've Accomplished" sections:
````md
```
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── PRD.md # Your requirements document
│ └── bmm-workflow-status.yaml # Progress tracking
└── ...
```
````
## Tutorial Structure
```text
1. Title + Hook (1-2 sentences describing outcome)
2. Version/Module Notice (info or warning admonition) (optional)
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 (optional)
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)
12. Quick Reference (commands table)
13. Common Questions (FAQ format)
14. Getting Help (community links)
15. Key Takeaways (tip admonition)
```
### Tutorial Checklist
- [ ] Hook describes outcome in 1-2 sentences
- [ ] "What You'll Learn" section present
- [ ] Prerequisites in admonition
- [ ] Quick Path TL;DR admonition at top
- [ ] Tables for phases, commands, agents
- [ ] "What You've Accomplished" section present
- [ ] Quick Reference table present
- [ ] Common Questions section present
- [ ] Getting Help section present
- [ ] Key Takeaways admonition at end
## How-To Structure
```text
1. Title + Hook (one sentence: "Use the `X` workflow to...")
2. When to Use This (bullet list of scenarios)
3. When to Skip This (optional)
4. Prerequisites (note admonition)
5. Steps (numbered ### subsections)
6. What You Get (output/artifacts produced)
7. Example (optional)
8. Tips (optional)
9. Next Steps (optional)
```
### How-To Checklist
- [ ] Hook starts with "Use the `X` workflow to..."
- [ ] "When to Use This" has 3-5 bullet points
- [ ] Prerequisites listed
- [ ] Steps are numbered `###` subsections with action verbs
- [ ] "What You Get" describes output artifacts
## Explanation Structure
### Types
| Type | Example |
| ----------------- | ---------------------------- |
| **Index/Landing** | `core-concepts/index.md` |
| **Concept** | `what-are-agents.md` |
| **Feature** | `quick-flow.md` |
| **Philosophy** | `why-solutioning-matters.md` |
| **FAQ** | `established-projects-faq.md` |
### General Template
```text
1. Title + Hook (1-2 sentences)
2. Overview/Definition (what it is, why it matters)
3. Key Concepts (### subsections)
4. Comparison Table (optional)
5. When to Use / When Not to Use (optional)
6. Diagram (optional - mermaid, 1 per doc max)
7. Next Steps (optional)
```
### Index/Landing Pages
```text
1. Title + Hook (one sentence)
2. Content Table (links with descriptions)
3. Getting Started (numbered list)
4. Choose Your Path (optional - decision tree)
```
### Concept Explainers
```text
1. Title + Hook (what it is)
2. Types/Categories (### subsections) (optional)
3. Key Differences Table
4. Components/Parts
5. Which Should You Use?
6. Creating/Customizing (pointer to how-to guides)
```
### Feature Explainers
```text
1. Title + Hook (what it does)
2. Quick Facts (optional - "Perfect for:", "Time to:")
3. When to Use / When Not to Use
4. How It Works (mermaid diagram optional)
5. Key Benefits
6. Comparison Table (optional)
7. When to Graduate/Upgrade (optional)
```
### Philosophy/Rationale Documents
```text
1. Title + Hook (the principle)
2. The Problem
3. The Solution
4. Key Principles (### subsections)
5. Benefits
6. When This Applies
```
### Explanation Checklist
- [ ] Hook states what document explains
- [ ] Content in scannable `##` sections
- [ ] Comparison tables for 3+ options
- [ ] Diagrams have clear labels
- [ ] Links to how-to guides for procedural questions
- [ ] 2-3 admonitions max per document
## Reference Structure
### Types
| Type | Example |
| ----------------- | --------------------- |
| **Index/Landing** | `workflows/index.md` |
| **Catalog** | `agents/index.md` |
| **Deep-Dive** | `document-project.md` |
| **Configuration** | `core-tasks.md` |
| **Glossary** | `glossary/index.md` |
| **Comprehensive** | `bmgd-workflows.md` |
### Reference Index Pages
```text
1. Title + Hook (one sentence)
2. Content Sections (## for each category)
- Bullet list with links and descriptions
```
### Catalog Reference
```text
1. Title + Hook
2. Items (## for each item)
- Brief description (one sentence)
- **Commands:** or **Key Info:** as flat list
3. Universal/Shared (## section) (optional)
```
### Item Deep-Dive Reference
```text
1. Title + Hook (one sentence purpose)
2. Quick Facts (optional note admonition)
- Module, Command, Input, Output as list
3. Purpose/Overview (## section)
4. How to Invoke (code block)
5. Key Sections (## for each aspect)
- Use ### for sub-options
6. Notes/Caveats (tip or caution admonition)
```
### Configuration Reference
```text
1. Title + Hook
2. Table of Contents (jump links if 4+ items)
3. Items (## for each config/task)
- **Bold summary** — one sentence
- **Use it when:** bullet list
- **How it works:** numbered steps (3-5 max)
- **Output:** expected result (optional)
```
### Comprehensive Reference Guide
```text
1. Title + Hook
2. Overview (## section)
- Diagram or table showing organization
3. Major Sections (## for each phase/category)
- Items (### for each item)
- Standardized fields: Command, Agent, Input, Output, Description
4. Next Steps (optional)
```
### Reference Checklist
- [ ] Hook states what document references
- [ ] Structure matches reference type
- [ ] Items use consistent structure throughout
- [ ] Tables for structured/comparative data
- [ ] Links to explanation docs for conceptual depth
- [ ] 1-2 admonitions max
## Glossary Structure
Starlight generates right-side "On this page" navigation from headers:
- Categories as `##` headers — appear in right nav
- Terms in tables — compact rows, not individual headers
- No inline TOC — right sidebar handles navigation
### Table Format
```md
## Category Name
| Term | Definition |
| ------------ | ---------------------------------------------------------------------------------------- |
| **Agent** | Specialized AI persona with specific expertise that guides users through workflows. |
| **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. |
```
### Definition Rules
| Do | Don't |
| ----------------------------- | ------------------------------------------- |
| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." |
| Keep to 1-2 sentences | Write multi-paragraph explanations |
| Bold term name in cell | Use plain text for terms |
### Context Markers
Add italic context at definition start for limited-scope terms:
- `*Quick Flow only.*`
- `*BMad Method/Enterprise.*`
- `*Phase N.*`
- `*BMGD.*`
- `*Established projects.*`
### Glossary Checklist
- [ ] Terms in tables, not individual headers
- [ ] Terms alphabetized within categories
- [ ] Definitions 1-2 sentences
- [ ] Context markers italicized
- [ ] Term names bolded in cells
- [ ] No "A [term] is..." definitions
## FAQ Sections
```md
## Questions
- [Do I always need architecture?](#do-i-always-need-architecture)
- [Can I change my plan later?](#can-i-change-my-plan-later)
### Do I always need architecture?
Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.
### Can I change my plan later?
Yes. The SM agent has a `correct-course` workflow for handling scope changes.
**Have a question not answered here?** [Open an issue](...) or ask in [Discord](...).
```
## Validation Commands
Before submitting documentation changes:
```bash
npm run docs:fix-links # Preview link format fixes
npm run docs:fix-links -- --write # Apply fixes
npm run docs:validate-links # Check links exist
npm run docs:build # Verify no build errors
```

93
docs/bmad-core-concepts/agents.md
View File

@ -1,93 +0,0 @@
# Agents
Agents are AI assistants that help you accomplish tasks. Each agent has a unique personality, specialized capabilities, and an interactive menu.
## Agent Types
BMAD has two primary agent types, designed for different use cases:
### Simple Agents
**Self-contained, focused, ready to use.**
Simple agents are complete in a single file. They excel at well-defined tasks and require minimal setup.
**Best for:**
- Single-purpose assistants (code review, documentation, commit messages)
- Quick deployment
- Projects that don't require persistent memory
- Getting started fast
**Example:** A commit message agent that reads your git diff and generates conventional commits.
### Expert Agents
**Powerful, memory-equipped, domain specialists.**
Expert agents have a **sidecar** - a companion folder containing additional instructions, workflows, and memory files. They remember context across sessions and handle complex, multi-step tasks.
**Best for:**
- Domain specialists (security architect, game designer, product manager)
- Tasks requiring persistent memory
- Complex workflows with multiple stages
- Projects that grow over time
**Example:** A game architect that remembers your design decisions, maintains consistency across sprints, and coordinates with other specialists.
## Key Differences
| Feature | Simple | Expert |
| ---------------- | -------------- | -------------------------- |
| **Files** | Single file | Agent + sidecar folder |
| **Memory** | Session only | Persistent across sessions |
| **Capabilities** | Focused scope | Multi-domain, extensible |
| **Setup** | Zero config | Sidecar initialization |
| **Best Use** | Specific tasks | Ongoing projects |
## Agent Components
All agents share these building blocks:
### Persona
- **Role** - What the agent does (expertise domain)
- **Identity** - Who the agent is (personality, character)
- **Communication Style** - How the agent speaks (tone, voice)
- **Principles** - Why the agent acts (values, decision framework)
### Capabilities
- Skills, tools, and knowledge the agent can apply
- Mapped to specific menu commands
### Menu
- Interactive command list
- Triggers, descriptions, and handlers
- Auto-includes help and exit options
### Critical Actions (optional)
- Instructions that execute before the agent starts
- Enable autonomous behaviors (e.g., "check git status before changes")
## Which Should You Use?
**Choose Simple when:**
- You need a task done quickly and reliably
- The scope is well-defined and won't change much
- You don't need the agent to remember things between sessions
**Choose Expert when:**
- You're building something complex over time
- The agent needs to maintain context (project history, decisions)
- You want the agent to coordinate workflows or other agents
- Domain expertise requires specialized knowledge bases
## Creating Custom Agents
BMAD provides the **BMAD Builder (BMB)** module for creating your own agents. See the [Agent Creation Guide](../modules/bmb-bmad-builder/agent-creation-guide.md) for step-by-step instructions.
## Customizing Existing Agents
You can modify any agent's behavior without editing core files. See [BMAD Customization](./bmad-customization/) for details. It is critical to never modify an installed agents .md file directly and follow the customization process, this way future updates to the agent or module its part of will continue to be updated and recompiled with the installer tool, and your customizations will still be retained.
---
**Next:** Learn about [Workflows](./workflows.md) to see how agents accomplish complex tasks.

210
docs/bmad-core-concepts/bmad-customization/agents.md
View File

@ -1,210 +0,0 @@
# Agent Customization Guide
Customize BMad agents without modifying core files. All customizations persist through updates.
## Quick Start
**1. Locate Customization Files**
After installation, find agent customization files in:
```
_bmad/_config/agents/
├── core-bmad-master.customize.yaml
├── bmm-dev.customize.yaml
├── bmm-pm.customize.yaml
└── ... (one file per installed agent)
```
**2. Edit Any Agent**
Open the `.customize.yaml` file for the agent you want to modify. All sections are optional - customize only what you need.
**3. Rebuild the Agent**
After editing, IT IS CRITICAL to rebuild the agent to apply changes:
```bash
npx bmad-method@alpha install # and then select option to compile all agents
# OR for individual agent only
npx bmad-method@alpha build <agent-name>
# Examples:
npx bmad-method@alpha build bmm-dev
npx bmad-method@alpha build core-bmad-master
npx bmad-method@alpha build bmm-pm
```
## What You Can Customize
### Agent Name
Change how the agent introduces itself:
```yaml
agent:
metadata:
name: 'Spongebob' # Default: "Amelia"
```
### Persona
Replace the agent's personality, role, and communication style:
```yaml
persona:
role: 'Senior Full-Stack Engineer'
identity: 'Lives in a pineapple (under the sea)'
communication_style: 'Spongebob'
principles:
- 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
- 'Favor composition over inheritance'
```
**Note:** The persona section replaces the entire default persona (not merged).
### Memories
Add persistent context the agent will always remember:
```yaml
memories:
- 'Works at Krusty Krab'
- 'Favorite Celebrity: David Hasslehoff'
- 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
```
### Custom Menu Items
Add your own workflows to the agent's menu:
```yaml
menu:
- trigger: my-workflow
workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
description: My custom workflow
- trigger: deploy
action: '#deploy-prompt'
description: Deploy to production
```
**Don't include:** `*` prefix or `help`/`exit` items - these are auto-injected.
### Critical Actions
Add instructions that execute before the agent starts:
```yaml
critical_actions:
- 'Always check git status before making changes'
- 'Use conventional commit messages'
```
### Custom Prompts
Define reusable prompts for `action="#id"` menu handlers:
```yaml
prompts:
- id: deploy-prompt
content: |
Deploy the current branch to production:
1. Run all tests
2. Build the project
3. Execute deployment script
```
## Real-World Examples
**Example 1: Customize Developer Agent for TDD**
```yaml
# _bmad/_config/agents/bmm-dev.customize.yaml
agent:
metadata:
name: 'TDD Developer'
memories:
- 'Always write tests before implementation'
- 'Project uses Jest and React Testing Library'
critical_actions:
- 'Review test coverage before committing'
```
**Example 2: Add Custom Deployment Workflow**
```yaml
# _bmad/_config/agents/bmm-dev.customize.yaml
menu:
- trigger: deploy-staging
workflow: '{project-root}/_bmad/deploy-staging.yaml'
description: Deploy to staging environment
- trigger: deploy-prod
workflow: '{project-root}/_bmad/deploy-prod.yaml'
description: Deploy to production (with approval)
```
**Example 3: Multilingual Product Manager**
```yaml
# _bmad/_config/agents/bmm-pm.customize.yaml
persona:
role: 'Bilingual Product Manager'
identity: 'Expert in US and LATAM markets'
communication_style: 'Clear, strategic, with cultural awareness'
principles:
- 'Consider localization from day one'
- 'Balance business goals with user needs'
memories:
- 'User speaks English and Spanish'
- 'Target markets: US and Latin America'
```
## Tips
- **Start Small:** Customize one section at a time and rebuild to test
- **Backup:** Copy customization files before major changes
- **Update-Safe:** Your customizations in `_config/` survive all BMad updates
- **Per-Project:** Customization files are per-project, not global
- **Version Control:** Consider committing `_config/` to share customizations with your team
## Module vs. Global Config
**Module-Level (Recommended):**
- Customize agents per-project in `_bmad/_config/agents/`
- Different projects can have different agent behaviors
**Global Config (Coming Soon):**
- Set defaults that apply across all projects
- Override with project-specific customizations
## Troubleshooting
**Changes not appearing?**
- Make sure you ran `npx bmad-method build <agent-name>` after editing
- Check YAML syntax is valid (indentation matters!)
- Verify the agent name matches the file name pattern
**Agent not loading?**
- Check for YAML syntax errors
- Ensure required fields aren't left empty if you uncommented them
- Try reverting to the template and rebuilding
**Need to reset?**
- Delete the `.customize.yaml` file
- Run `npx bmad-method build <agent-name>` to regenerate defaults
## Next Steps
- **[Learn about Agents](../agents.md)** - Understand Simple vs Expert agents
- **[Agent Creation Guide](../../modules/bmb-bmad-builder/agent-creation-guide.md)** - Build completely custom agents
- **[BMM Complete Documentation](../../modules/bmm-bmad-method/index)** - Full BMad Method reference
[← Back to Customization](./index.md)

26
docs/bmad-core-concepts/bmad-customization/index.md
View File

@ -1,26 +0,0 @@
# BMAD Customization
Personalize agents and workflows to match your needs.
## Guides
| Guide | Description |
|-------|-------------|
| **[Agent Customization](./agents.md)** | Modify agent behavior without editing core files |
| **[Workflow Customization](./workflows.md)** | Customize and optimize workflows |
## Overview
BMAD provides two main customization approaches:
### Agent Customization
Modify any agent's persona, name, capabilities, or menu items using `.customize.yaml` files in `_bmad/_config/agents/`. Your customizations persist through updates.
### Workflow Customization
Replace or extend workflow steps to create tailored processes. (Coming soon)
---
**Next:** Read the [Agent Customization Guide](./agents.md) to start personalizing your agents.
[← Back to Core Concepts](../index.md)

30
docs/bmad-core-concepts/bmad-customization/workflows.md
View File

@ -1,30 +0,0 @@
# Workflow Customization Guide
Customize and optimize workflows with step replacement and hooks.
## Status
> **Coming Soon:** Workflow customization is an upcoming capability. This guide will be updated when the feature is available.
## What to Expect
Workflow customization will allow you to:
- **Replace Steps** - Swap out specific workflow steps with custom implementations
- **Add Hooks** - Inject custom behavior before/after workflow steps
- **Extend Workflows** - Create new workflows based on existing ones
- **Override Behavior** - Customize workflow logic for your project's needs
## For Now
While workflow customization is in development, you can:
- **Create Custom Workflows** - Use the BMAD Builder to create entirely new workflows
- **Customize Agents** - Modify agent behavior using [Agent Customization](./agents.md)
- **Provide Feedback** - Share your workflow customization needs with the community
---
**In the meantime:** Learn how to [create custom workflows](../../modules/bmb-bmad-builder/index) from scratch.
[← Back to Customization](./index.md)

37
docs/bmad-core-concepts/index.md
View File

@ -1,37 +0,0 @@
# BMAD Core Concepts
Understanding the fundamental building blocks of the BMAD Method.
## The Essentials
| Concept | Description | Guide |
|---------|-------------|-------|
| **Agents** | AI assistants with personas, capabilities, and menus | [Agents Guide](./agents.md) |
| **Workflows** | Structured processes for achieving specific outcomes | [Workflows Guide](./workflows.md) |
| **Modules** | Packaged collections of agents and workflows | [Modules Guide](./modules.md) |
## Getting Started
### New to BMAD?
Start here to understand what BMAD is and how it works:
1. **[Agents Guide](./agents.md)** - Learn about Simple and Expert agents
2. **[Workflows Guide](./workflows.md)** - Understand how workflows orchestrate tasks
3. **[Modules Guide](./modules.md)** - See how modules organize functionality
### Installing BMAD
- **[Installation Guide](./installing/)** - Set up BMAD in your project
- **[Upgrading from v4](./installing/upgrading.md)** - Migrate from earlier versions
### Configuration
- **[BMAD Customization](./bmad-customization/)** - Personalize agents and workflows
### Advanced
- **[Web Bundles](./web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs
---
**Next:** Read the [Agents Guide](./agents.md) to understand the core building block of BMAD.

77
docs/bmad-core-concepts/installing/index.md
View File

@ -1,77 +0,0 @@
# Installation
Get BMAD up and running in your project.
## Upgrading?
If you're upgrading from v4, see the [Upgrade Guide](./upgrading.md).
---
## Quick Install
```bash
npx bmad-method install
```
This interactive installer will:
1. Let you choose a location to install to
2. Let you choose which Agentic LLM Tools you would like to use (Such as Claude Code, Cursor, Windsurf, etc...)
3. Let you choose which official modules to install (BMad Method, Creative Intelligence suite, BMad Builder)
4. Let you choose any custom local modules, workflows or agents to install
5. Let you configure each module or quickly accept the default recommended settings for each selected model
## Requirements
- **Node.js** 20+ (for the installer)
- **Git** (recommended for version control)
- An **AI-powered Agent and/or IDE** or access to Claude/ChatGPT/Gemini
## Module Options
During installation, you'll choose which modules to install:
| Module | Description | Best For |
| -------- | -------------------- | ----------------------------------------------------- |
| **BMM** | BMAD Method Core | Software development projects |
| **BMGD** | Game Development | Game projects with specialized workflows |
| **CIS** | Creative Intel Suite | Creativity Unlocking Suite, not software dev specific |
| **BMB** | Builder | Creating custom agents and workflows |
You will also be asked if you would like to install custom content (agents, workflows or modules) you have created with the BMB, or shared from others in the community.
## Post-Installation
After installation, your project will have:
```
your-project/
├── _bmad/ # BMAD configuration and agents
│ ├── bmm/ # Method module (if installed)
│ ├── bmgd/ # Game dev module (if installed)
│ ├── core/ # Always installed, includes party mode, advanced elicitation, and other core generic utils
│ ├── {others}/ # etc...
├── _bmad-output/ # BMAD default output folder - configurable during install
├── .claude/ # IDE-specific setup (varies by IDE)
└── ... your code # maybe nothing else yet if a fresh new folder
```
## Next Steps
1. **Read the [Quick Start Guide](../../modules/bmm-bmad-method/quick-start)** to build your first feature
2. **Explore [Workflows](../../modules/bmm-bmad-method/index#-workflow-guides)** to understand the methodology
3. **Learn about [Agents](../agents.md)** to understand BMAD's core building blocks
## Troubleshooting
### Common Issues
**"Command not found: npx"**
: Install Node.js 20+ from [nodejs.org](https://nodejs.org)
**"Permission denied"**
: Run with appropriate permissions or check your npm configuration
For more help, join our [Discord](https://discord.gg/bmad).

144
docs/bmad-core-concepts/installing/upgrading.md
View File

@ -1,144 +0,0 @@
# BMad v4 to v6 Upgrade Guide
## Overview
BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.
---
## Automatic V4 Detection
When you run `npm run install:bmad` on a project, the installer automatically detects:
- **Legacy v4 installation folder**: `.bmad-method`
- **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
### What Happens During Detection
1. **Automatic Detection of v4 Modules**
1. Installer will suggest removal or backup of your .bmad-method folder. You can choose to exit the installer and handle this cleanup, or allow the install to continue. Technically you can have both v4 and v6 installed, but it is not recommended. All BMad content and modules will be installed under a .bmad folder, fully segregated.
2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
- Located in IDE config folders, for example claude: `.claude/commands/BMad/agents`, `.claude/commands/BMad/tasks`, etc.
- NOTE: if the upgrade and install of v6 finished, the new commands will be under `.claude/commands/bmad/<module>/agents|workflows`
- Note 2: If you accidentally delete the wrong/new bmad commands - you can easily restore them by rerunning the installer, and choose quick update option, and all will be reapplied properly.
## Module Migration
### Deprecated Modules from v4
| v4 Module | v6 Status |
| ----------------------------- | ---------------------------------------------- |
| `_bmad-2d-phaser-game-dev` | Integrated into new BMGD Module |
| `_bmad-2d-unity-game-dev` | Integrated into new BMGD Module |
| `_bmad-godot-game-dev` | Integrated into new BMGD Module |
| `_bmad-*-game-dev` (any) | Integrated into new BMGD Module |
| `_bmad-infrastructure-devops` | Deprecated - New core devops agent coming soon |
| `_bmad-creative-writing` | Not adapted - New v6 module coming soon |
Aside from .bmad-method - if you have any of these others installed also, again its recommended to remove them and use the V6 equivalents, but its also fine if you decide to keep both. But it is not recommended to use both on the same project long term.
## Architecture Changes
### Folder Structure
**v4 "Expansion Packs" Structure:**
```
your-project/
├── .bmad-method/
├── .bmad-game-dev/
├── .bmad-creative-writing/
└── .bmad-infrastructure-devops/
```
**v6 Unified Structure:**
```
your-project/
└── _bmad/ # Single installation folder is _bmad
└── _config/ # Your customizations
| └── agents/ # Agent customization files
├── core/ # Real core framework (applies to all modules)
├── bmm/ # BMad Method (software/game dev)
├── bmb/ # BMad Builder (create agents/workflows)
├── cis/ # Creative Intelligence Suite
├── _bmad_output # Default bmad output folder (was doc folder in v4)
```
### Key Concept Changes
- **v4 `_bmad-core and _bmad-method`**: Was actually the BMad Method
- **v6 `_bmad/core/`**: Is the real universal core framework
- **v6 `_bmad/bmm/`**: Is the BMad Method module
- **Module identification**: All modules now have a `config.yaml` file once installed at the root of the modules installed folder
## Project Progress Migration
### If You've Completed Some or all Planning Phases (Brief/PRD/UX/Architecture) with the BMad Method:
After running the v6 installer, if you kept the paths the same as the installation suggested, you will need to move a few files, or run the installer again. It is recommended to stick with these defaults as it will be easier to adapt if things change in the future.
If you have any planning artifacts, put them in a folder called _bmad-output/planning-artifacts at the root of your project, ensuring that:
PRD has PRD in the file name or folder name if sharded.
Similar for 'brief', 'architecture', 'ux-design'.
If you have other long term docs that will not be as ephemeral as these project docs, you can put them in the /docs folder, ideally with a index.md file.
HIGHLY RECOMMENDED NOTE: If you are only partway through planning, its highly recommended to restart and do the PRD, UX and ARCHITECTURE steps. You could even use your existing documents as inputs letting the agent know you want to redo them with the new workflows. These optimized v6 progressive discovery workflows that also will utilize web search at key moments, while offering better advanced elicitation and part mode in the IDE will produce superior results. And then once all are complete, an epics with stories is generated after the architecture step now - ensuring it uses input from all planing documents.
### If You're Mid-Development (Stories Created/Implemented)
1. Complete the v6 installation as above
2. Ensure you have a file called epics.md or epics/epic*.md - these need to be located under the _bmad-output/planning-artifacts folder.
3. Run the scrum masters `sprint-planning` workflow to generate the implementation tracking plan in _bmad-output/implementation-artifacts.
4. Inform the SM after the output is complete which epics and stories were completed already and should be parked properly in the file.
## Agent Customization Migration
### v4 Agent Customization
In v4, you may have modified agent files directly in `_bmad-*` folders.
### v6 Agent Customization
**All customizations** now go in `_bmad/_config/agents/` using customize files:
**Example: Renaming an agent and changing communication style**
File: `_bmad/_config/agents/bmm-pm.customize.yaml`
```yaml
# Customize the PM agent
persona:
name: 'Captain Jack' # Override agent name
role: 'Swashbuckling Product Owner'
communication_style: |
- Talk like a pirate
- Use nautical metaphors for software concepts
- Always upbeat and adventurous
```
There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](../bmad-customization/agents.md)
CRITICAL NOTE: After you modify the customization file, you need to run the npx installer against your installed location, and choose the option to rebuild all agents, or just do a quick update again. This always builds agents fresh and applies customizations.
**How it works:**
- Base agent: `_bmad/bmm/agents/pm.md`
- Customization: `_bmad/_config/agents/bmm-pm.customize.yaml`
- Rebuild all agents -> Result: Agent uses your custom name and style
## Document Compatibility
### Sharded vs Unsharded Documents
**Good news**: Unlike v4, v6 workflows are **fully flexible** with document structure:
- ✅ Sharded documents (split into multiple files)
- ✅ Unsharded documents (single file per section)
- ✅ Custom sections for your project type
- ✅ Mixed approaches
All workflow files are scanned automatically. No manual configuration needed.

76
docs/bmad-core-concepts/modules.md
View File

@ -1,76 +0,0 @@
# Modules
Modules are organized collections of agents and workflows that solve specific problems or address particular domains.
## What is a Module?
A module is a self-contained package that includes:
- **Agents** - Specialized AI assistants
- **Workflows** - Step-by-step processes
- **Configuration** - Module-specific settings
- **Documentation** - Usage guides and reference
## Official Modules
### Core Module
Always installed, provides shared functionality:
- Global configuration
- Core workflows (Party Mode, Advanced Elicitation, Brainstorming)
- Common tasks (document indexing, sharding, review)
### BMAD Method (BMM)
Software and game development:
- Project planning workflows
- Implementation agents (Dev, PM, QA, Scrum Master)
- Testing and architecture guidance
### BMAD Builder (BMB)
Create custom solutions:
- Agent creation workflows
- Workflow authoring tools
- Module scaffolding
### Creative Intelligence Suite (CIS)
Innovation and creativity:
- Creative thinking techniques
- Innovation strategy workflows
- Storytelling and ideation
### BMAD Game Dev (BMGD)
Game development specialization:
- Game design workflows
- Narrative development
- Performance testing frameworks
## Module Structure
Installed modules follow this structure:
```
_bmad/
├── core/ # Always present
├── bmm/ # BMAD Method (if installed)
├── bmb/ # BMAD Builder (if installed)
├── cis/ # Creative Intelligence (if installed)
└── bmgd/ # Game Dev (if installed)
```
## Custom Modules
You can create your own modules containing:
- Custom agents for your domain
- Organizational workflows
- Team-specific configurations
Custom modules are installed the same way as official modules.
## Installing Modules
During BMAD installation, you choose which modules to install. You can also add or remove modules later by re-running the installer.
See [Installation Guide](./installing/) for details.
---
**Next:** Read the [Installation Guide](./installing/) to set up BMAD with the modules you need.

34
docs/bmad-core-concepts/web-bundles/index.md
View File

@ -1,34 +0,0 @@
# Web Bundles
Use BMAD agents in Gemini Gems and Custom GPTs.
## Status
> **Note:** The Web Bundling Feature is being rebuilt from the ground up. Current v6 bundles may be incomplete or missing functionality.
## What Are Web Bundles?
Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload.
### What's Included
- Complete agent persona and instructions
- All workflows and dependencies
- Interactive menu system
- Party mode for multi-agent collaboration
- No external files required
### Use Cases
**Perfect for:**
- Uploading a single file to a Gemini GEM or Custom GPT
- Using BMAD Method from the Web
- Cost savings (generally lower cost than local usage)
- Quick sharing of agent configurations
**Trade-offs:**
- Some quality reduction vs local usage
- Less convenient than full local installation
- Limited to agent capabilities (no workflow file access)
[← Back to Core Concepts](../index.md)

89
docs/bmad-core-concepts/workflows.md
View File

@ -1,89 +0,0 @@
# Workflows
Workflows are structured processes that guide agents through complex tasks. Think of them as recipes that ensure consistent, high-quality outcomes.
## What is a Workflow?
A workflow is a step-by-step process that agents follow to accomplish specific objectives. A workflow can be a single file if small enough, but more than likely is comprized of a very small workflow or skill definition file with multiple steps and data files that are loaded as needed on demand. Each step file:
- Defines a clear goal
- Provides instructions for the agent
- May include decision points or user interactions
- Produces specific outputs
- Progressively at a specific point can load the next proper step.
## How Workflows Work
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Step 1 │ → │ Step 2 │ → │ Step 3 │ → │ Complete │
│ Discover │ │ Define │ │ Build │ │ Output │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
```
**Key characteristics:**
- **Progressive** - Each step builds on the previous
- **Interactive** - Workflows can pause for user input
- **Reusable** - The same workflow produces consistent results
- **Composable** - Workflow steps can call other workflow steps, or whole other workflows!
- **LLM Reinforcement** - Some rules or info is repeated in each step file ensuring certain rules are always top of agent mind, even during context heavy processes or very long workflows!
## Workflow Types
### Planning Workflows
Generate project artifacts like requirements, architecture, and task breakdowns.
**Examples:** Brief creation, PRD authoring, architecture design, sprint planning
### Execution Workflows
Guide implementation of specific tasks or features.
**Examples:** Code implementation, code review, testing, deployment
### Support Workflows
Handle cross-cutting concerns and creative processes.
**Examples:** Brainstorming, retrospectives, root cause analysis
## Progressive Disclosure
BMAD workflows use **progressive disclosure** - each step only knows about its immediate next step and what it is currently meant to do. This:
- Reduces cognitive load on the AI
- Ensures each step gets full attention
- Allows for conditional routing based on previous outcomes
- Makes workflows easier to debug and modify
## Menu-Driven Interaction
Most workflows use interactive menus with standard options:
| Option | Purpose |
| ---------------- | -------------------------------------------------- |
| **[A] Advanced** | Invoke deeper reasoning techniques |
| **[P] Party** | Get multiple agent perspectives |
| **[C] Continue** | Proceed to next step after all writes are complete |
## Workflow Files
Workflows are markdown files with structured frontmatter - this front matter also allows them to easily work as skills and also slash command loaded:
```yaml
---
name: 'my-workflow'
description: 'What this workflow does and when it should be used or loaded automatically (or call out if it should be requested to run explicitly by the user)'
---
```
The content in the workflow file is very minimal, sets up the reinforcement of the agent persona and reminder that it is a facilitator working with a user, lays out rules of processing steps only when told to do a specific step, loads all config file variables needed by the workflow, and then routes to step 1. No other info about other steps should be in this workflow file. Keeping it as small and lean as possible help in compilation as a skill, as overall size of the skill main file (workflow.md) is critical to keep small.
## Creating Custom Workflows
The **BMAD Builder (BMB)** module includes workflows for creating custom workflows. See [BMB Documentation](../modules/bmb-bmad-builder/) for details.
---
**Next:** Learn about [Modules](./modules.md) to see how agents and workflows are organized.

4
docs/bmad_improvements_v2.md
View File

@ -1,3 +1,7 @@
---
title: BMAD Epic-Execute Improvements Analysis v2
---
# BMAD Epic-Execute Improvements Analysis v2
**Date:** 2026-01-26

4
docs/bmad_improvements_v2_fixes.md
View File

@ -1,3 +1,7 @@
---
title: BMAD Epic-Execute v2 Fixes & Improvements
---
# BMAD Epic-Execute v2 Fixes & Improvements
**Date:** 2026-01-26

49
docs/explanation/advanced-elicitation.md Normal file
View File

@ -0,0 +1,49 @@
---
title: "Advanced Elicitation"
description: Push the LLM to rethink its work using structured reasoning methods
sidebar:
order: 6
---
Make the LLM reconsider what it just generated. You pick a reasoning method, it applies that method to its own output, you decide whether to keep the improvements.
## What is Advanced Elicitation?
A structured second pass. Instead of asking the AI to "try again" or "make it better," you select a specific reasoning method and the AI re-examines its own output through that lens.
The difference matters. Vague requests produce vague revisions. A named method forces a particular angle of attack, surfacing insights that a generic retry would miss.
## When to Use It
- After a workflow generates content and you want alternatives
- When output seems okay but you suspect there's more depth
- To stress-test assumptions or find weaknesses
- For high-stakes content where rethinking helps
Workflows offer advanced elicitation at decision points - after the LLM has generated something, you'll be asked if you want to run it.
## How It Works
1. LLM suggests 5 relevant methods for your content
2. You pick one (or reshuffle for different options)
3. Method is applied, improvements shown
4. Accept or discard, repeat or continue
## Built-in Methods
Dozens of reasoning methods are available. A few examples:
- **Pre-mortem Analysis** - Assume the project already failed, work backward to find why
- **First Principles Thinking** - Strip away assumptions, rebuild from ground truth
- **Inversion** - Ask how to guarantee failure, then avoid those things
- **Red Team vs Blue Team** - Attack your own work, then defend it
- **Socratic Questioning** - Challenge every claim with "why?" and "how do you know?"
- **Constraint Removal** - Drop all constraints, see what changes, add them back selectively
- **Stakeholder Mapping** - Re-evaluate from each stakeholder's perspective
- **Analogical Reasoning** - Find parallels in other domains and apply their lessons
And many more. The AI picks the most relevant options for your content - you choose which to run.
:::tip[Start Here]
Pre-mortem Analysis is a good first pick for any spec or plan. It consistently finds gaps that a standard review misses.
:::

59
docs/explanation/adversarial-review.md Normal file
View File

@ -0,0 +1,59 @@
---
title: "Adversarial Review"
description: Forced reasoning technique that prevents lazy "looks good" reviews
sidebar:
order: 5
---
Force deeper analysis by requiring problems to be found.
## What is Adversarial Review?
A review technique where the reviewer *must* find issues. No "looks good" allowed. The reviewer adopts a cynical stance - assume problems exist and find them.
This isn't about being negative. It's about forcing genuine analysis instead of a cursory glance that rubber-stamps whatever was submitted.
**The core rule:** You must find issues. Zero findings triggers a halt - re-analyze or explain why.
## Why It Works
Normal reviews suffer from confirmation bias. You skim the work, nothing jumps out, you approve it. The "find problems" mandate breaks this pattern:
- **Forces thoroughness** - Can't approve until you've looked hard enough to find issues
- **Catches missing things** - "What's not here?" becomes a natural question
- **Improves signal quality** - Findings are specific and actionable, not vague concerns
- **Information asymmetry** - Run reviews with fresh context (no access to original reasoning) so you evaluate the artifact, not the intent
## Where It's Used
Adversarial review appears throughout BMad workflows - code review, implementation readiness checks, spec validation, and others. Sometimes it's a required step, sometimes optional (like advanced elicitation or party mode). The pattern adapts to whatever artifact needs scrutiny.
## Human Filtering Required
Because the AI is *instructed* to find problems, it will find problems - even when they don't exist. Expect false positives: nitpicks dressed as issues, misunderstandings of intent, or outright hallucinated concerns.
**You decide what's real.** Review each finding, dismiss the noise, fix what matters.
## Example
Instead of:
> "The authentication implementation looks reasonable. Approved."
An adversarial review produces:
> 1. **HIGH** - `login.ts:47` - No rate limiting on failed attempts
> 2. **HIGH** - Session token stored in localStorage (XSS vulnerable)
> 3. **MEDIUM** - Password validation happens client-side only
> 4. **MEDIUM** - No audit logging for failed login attempts
> 5. **LOW** - Magic number `3600` should be `SESSION_TIMEOUT_SECONDS`
The first review might miss a security vulnerability. The second caught four.
## Iteration and Diminishing Returns
After addressing findings, consider running it again. A second pass usually catches more. A third isn't always useless either. But each pass takes time, and eventually you hit diminishing returns - just nitpicks and false findings.
:::tip[Better Reviews]
Assume problems exist. Look for what's missing, not just what's wrong.
:::

33
docs/explanation/brainstorming.md Normal file
View File

@ -0,0 +1,33 @@
---
title: "Brainstorming"
description: Interactive creative sessions using 60+ proven ideation techniques
sidebar:
order: 2
---
Unlock your creativity through guided exploration.
## What is Brainstorming?
Run `brainstorming` and you've got a creative facilitator pulling ideas out of you - not generating them for you. The AI acts as coach and guide, using proven techniques to create conditions where your best thinking emerges.
**Good for:**
- Breaking through creative blocks
- Generating product or feature ideas
- Exploring problems from new angles
- Developing raw concepts into action plans
## How It Works
1. **Setup** - Define topic, goals, constraints
2. **Choose approach** - Pick techniques yourself, get AI recommendations, go random, or follow a progressive flow
3. **Facilitation** - Work through techniques with probing questions and collaborative coaching
4. **Organize** - Ideas grouped into themes and prioritized
5. **Action** - Top ideas get next steps and success metrics
Everything gets captured in a session document you can reference later or share with stakeholders.
:::note[Your Ideas]
Every idea comes from you. The workflow creates conditions for insight - you're the source.
:::

50
docs/explanation/established-projects-faq.md Normal file
View File

@ -0,0 +1,50 @@
---
title: "Established Projects FAQ"
description: Common questions about using BMad Method on established projects
sidebar:
order: 8
---
Quick answers to common questions about working on established projects with the BMad Method (BMM).
## Questions
- [Do I have to run document-project first?](#do-i-have-to-run-document-project-first)
- [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project)
- [Can I use Quick Flow for established projects?](#can-i-use-quick-flow-for-established-projects)
- [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-follow-best-practices)
### Do I have to run document-project first?
Highly recommended, especially if:
- No existing documentation
- Documentation is outdated
- AI agents need context about existing code
You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md` or will use other tools or techniques to aid in discovery for the agent to build on an existing system.
### What if I forget to run document-project?
Don't worry about it - you can do it at any time. You can even do it during or after a project to help keep docs up to date.
### Can I use Quick Flow for established projects?
Yes! Quick Flow works great for established projects. It will:
- Auto-detect your existing stack
- Analyze existing code patterns
- Detect conventions and ask for confirmation
- Generate context-rich tech-spec that respects existing code
Perfect for bug fixes and small features in existing codebases.
### What if my existing code doesn't follow best practices?
Quick Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide:
- **Yes** → Maintain consistency with current codebase
- **No** → Establish new standards (document why in tech-spec)
BMM respects your choice — it won't force modernization, but it will offer it.
**Have a question not answered here?** Please [open an issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it!

59
docs/explanation/party-mode.md Normal file
View File

@ -0,0 +1,59 @@
---
title: "Party Mode"
description: Multi-agent collaboration - get all your AI agents in one conversation
sidebar:
order: 7
---
Get all your AI agents in one conversation.
## What is Party Mode?
Run `party-mode` and you've got your whole AI team in one room - PM, Architect, Dev, UX Designer, whoever you need. BMad Master orchestrates, picking relevant agents per message. Agents respond in character, agree, disagree, and build on each other's ideas.
The conversation continues as long as you want. Ask follow-ups, push back on answers, redirect the discussion - it's a real back-and-forth with your agents until you're done.
**Good for:**
- Big decisions with tradeoffs
- Brainstorming sessions
- Post-mortems when things go wrong
- Sprint retrospectives and planning
## Examples
### Calling Out Bad Architecture
**You:** "Okay team, our last sprint was a disaster. The authentication service went down three times. Who screwed this up?"
**Architect:** "The design was sound - distributed authentication with proper fallbacks. If implementation deviated from the spec..."
**Dev:** "I followed the architecture doc exactly. The spec didn't account for concurrent session invalidation race conditions."
**PM:** "Both of you missed the bigger issue - we didn't validate session management requirements in the PRD. This is on me for not catching it."
**TEA:** "And I should've caught this in integration tests. The test scenarios didn't cover concurrent invalidation."
### Creative Brainstorming
**You:** "How do we make onboarding feel magical instead of boring?"
**UX Designer:** "Start with progressive disclosure - reveal features as users need them, not all at once in a tutorial."
**Storyteller:** "What if onboarding was a story? Each step reveals a character's journey - the user IS the hero."
**Game Designer:** "Building on that - what if the first 'quest' is actually solving a real user problem? They learn by doing something valuable."
### Technical Decision
**You:** "Monolith or microservices for MVP?"
**Architect:** "Start monolith. Microservices add complexity you don't need at 1000 users."
**PM:** "Agree. Time to market matters more than theoretical scalability."
**Dev:** "Monolith with clear module boundaries. We can extract services later if needed."
:::tip[Better Decisions]
Better decisions through diverse perspectives. Welcome to party mode.
:::

112
docs/explanation/preventing-agent-conflicts.md Normal file
View File

@ -0,0 +1,112 @@
---
title: "Preventing Agent Conflicts"
description: How architecture prevents conflicts when multiple agents implement a system
sidebar:
order: 4
---
When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
## Common Conflict Types
### API Style Conflicts
Without architecture:
- Agent A uses REST with `/users/{id}`
- Agent B uses GraphQL mutations
- Result: Inconsistent API patterns, confused consumers
With architecture:
- ADR specifies: "Use GraphQL for all client-server communication"
- All agents follow the same pattern
### Database Design Conflicts
Without architecture:
- Agent A uses snake_case column names
- Agent B uses camelCase column names
- Result: Inconsistent schema, confusing queries
With architecture:
- Standards document specifies naming conventions
- All agents follow the same patterns
### State Management Conflicts
Without architecture:
- Agent A uses Redux for global state
- Agent B uses React Context
- Result: Multiple state management approaches, complexity
With architecture:
- ADR specifies state management approach
- All agents implement consistently
## How Architecture Prevents Conflicts
### 1. Explicit Decisions via ADRs
Every significant technology choice is documented with:
- Context (why this decision matters)
- Options considered (what alternatives exist)
- Decision (what we chose)
- Rationale (why we chose it)
- Consequences (trade-offs accepted)
### 2. FR/NFR-Specific Guidance
Architecture maps each functional requirement to technical approach:
- FR-001: User Management → GraphQL mutations
- FR-002: Mobile App → Optimized queries
### 3. Standards and Conventions
Explicit documentation of:
- Directory structure
- Naming conventions
- Code organization
- Testing patterns
## Architecture as Shared Context
Think of architecture as the shared context that all agents read before implementing:
```text
PRD: "What to build"
↓
Architecture: "How to build it"
↓
Agent A reads architecture → implements Epic 1
Agent B reads architecture → implements Epic 2
Agent C reads architecture → implements Epic 3
↓
Result: Consistent implementation
```
## Key ADR Topics
Common decisions that prevent conflicts:
| Topic | Example Decision |
| ---------------- | -------------------------------------------- |
| API Style | GraphQL vs REST vs gRPC |
| Database | PostgreSQL vs MongoDB |
| Auth | JWT vs Sessions |
| State Management | Redux vs Context vs Zustand |
| Styling | CSS Modules vs Tailwind vs Styled Components |
| Testing | Jest + Playwright vs Vitest + Cypress |
## Anti-Patterns to Avoid
:::caution[Common Mistakes]
- **Implicit Decisions** — "We'll figure out the API style as we go" leads to inconsistency
- **Over-Documentation** — Documenting every minor choice causes analysis paralysis
- **Stale Architecture** — Documents written once and never updated cause agents to follow outdated patterns
:::
:::tip[Correct Approach]
- Document decisions that cross epic boundaries
- Focus on conflict-prone areas
- Update architecture as you learn
- Use `correct-course` for significant changes
:::

73
docs/explanation/quick-flow.md Normal file
View File

@ -0,0 +1,73 @@
---
title: "Quick Flow"
description: Fast-track for small changes - skip the full methodology
sidebar:
order: 1
---
Skip the ceremony. Quick Flow takes you from idea to working code in two commands - no Product Brief, no PRD, no Architecture doc.
## When to Use It
- Bug fixes and patches
- Refactoring existing code
- Small, well-understood features
- Prototyping and spikes
- Single-agent work where one developer can hold the full scope
## When NOT to Use It
- New products or platforms that need stakeholder alignment
- Major features spanning multiple components or teams
- Work that requires architectural decisions (database schema, API contracts, service boundaries)
- Anything where requirements are unclear or contested
:::caution[Scope Creep]
If you start a Quick Flow and realize the scope is bigger than expected, `quick-dev` will detect this and offer to escalate. You can switch to a full PRD workflow at any point without losing your work.
:::
## How It Works
Quick Flow has two commands, each backed by a structured workflow. You can run them together or independently.
### quick-spec: Plan
Run `quick-spec` and Barry (the Quick Flow agent) walks you through a conversational discovery process:
1. **Understand** - You describe what you want to build. Barry scans the codebase to ask informed questions, then captures a problem statement, solution approach, and scope boundaries.
2. **Investigate** - Barry reads relevant files, maps code patterns, identifies files to modify, and documents the technical context.
3. **Generate** - Produces a complete tech-spec with ordered implementation tasks (specific file paths and actions), acceptance criteria in Given/When/Then format, testing strategy, and dependencies.
4. **Review** - Presents the full spec for your sign-off. You can edit, ask questions, run adversarial review, or refine with advanced elicitation before finalizing.
The output is a `tech-spec-{slug}.md` file saved to your project's implementation artifacts folder. It contains everything a fresh agent needs to implement the feature - no conversation history required.
### quick-dev: Build
Run `quick-dev` and Barry implements the work. It operates in two modes:
- **Tech-spec mode** - Point it at a spec file (`quick-dev tech-spec-auth.md`) and it executes every task in order, writes tests, and verifies acceptance criteria.
- **Direct mode** - Give it instructions directly (`quick-dev "refactor the auth middleware"`) and it gathers context, builds a mental plan, and executes.
After implementation, `quick-dev` runs a self-check audit against all tasks and acceptance criteria, then triggers an adversarial code review of the diff. Findings are presented for you to resolve before wrapping up.
:::tip[Fresh Context]
For best results, run `quick-dev` in a new conversation after finishing `quick-spec`. This gives the implementation agent clean context focused solely on building.
:::
## What Quick Flow Skips
The full BMad Method produces a Product Brief, PRD, Architecture doc, and Epic/Story breakdown before any code is written. Quick Flow replaces all of that with a single tech-spec. This works because Quick Flow targets changes where:
- The product direction is already established
- Architecture decisions are already made
- A single developer can reason about the full scope
- Requirements fit in one conversation
## Escalating to Full BMad Method
Quick Flow includes built-in guardrails for scope detection. When you run `quick-dev` with a direct request, it evaluates signals like multi-component mentions, system-level language, and uncertainty about approach. If it detects the work is bigger than a quick flow:
- **Light escalation** - Recommends running `quick-spec` first to create a plan
- **Heavy escalation** - Recommends switching to the full BMad Method PRD process
You can also escalate manually at any time. Your tech-spec work carries forward - it becomes input for the broader planning process rather than being discarded.

77
docs/explanation/why-solutioning-matters.md Normal file
View File

@ -0,0 +1,77 @@
---
title: "Why Solutioning Matters"
description: Understanding why the solutioning phase is critical for multi-epic projects
sidebar:
order: 3
---
Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
## The Problem Without Solutioning
```text
Agent 1 implements Epic 1 using REST API
Agent 2 implements Epic 2 using GraphQL
Result: Inconsistent API design, integration nightmare
```
When multiple agents implement different parts of a system without shared architectural guidance, they make independent technical decisions that may conflict.
## The Solution With Solutioning
```text
architecture workflow decides: "Use GraphQL for all APIs"
All agents follow architecture decisions
Result: Consistent implementation, no conflicts
```
By documenting technical decisions explicitly, all agents implement consistently and integration becomes straightforward.
## Solutioning vs Planning
| Aspect | Planning (Phase 2) | Solutioning (Phase 3) |
| -------- | ----------------------- | --------------------------------- |
| Question | What and Why? | How? Then What units of work? |
| Output | FRs/NFRs (Requirements) | Architecture + Epics/Stories |
| Agent | PM | Architect → PM |
| Audience | Stakeholders | Developers |
| Document | PRD (FRs/NFRs) | Architecture + Epic Files |
| Level | Business logic | Technical design + Work breakdown |
## Key Principle
**Make technical decisions explicit and documented** so all agents implement consistently.
This prevents:
- API style conflicts (REST vs GraphQL)
- Database design inconsistencies
- State management disagreements
- Naming convention mismatches
- Security approach variations
## When Solutioning is Required
| Track | Solutioning Required? |
|-------|----------------------|
| Quick Flow | No - skip entirely |
| BMad Method Simple | Optional |
| BMad Method Complex | Yes |
| Enterprise | Yes |
:::tip[Rule of Thumb]
If you have multiple epics that could be implemented by different agents, you need solutioning.
:::
## The Cost of Skipping
Skipping solutioning on complex projects leads to:
- **Integration issues** discovered mid-sprint
- **Rework** due to conflicting implementations
- **Longer development time** overall
- **Technical debt** from inconsistent patterns
:::caution[Cost Multiplier]
Catching alignment issues in solutioning is 10× faster than discovering them during implementation.
:::

172
docs/how-to/customize-bmad.md Normal file
View File

@ -0,0 +1,172 @@
---
title: "How to Customize BMad"
description: Customize agents, workflows, and modules while preserving update compatibility
sidebar:
order: 7
---
Use the `.customize.yaml` files to tailor agent behavior, personas, and menus while preserving your changes across updates.
## When to Use This
- You want to change an agent's name, personality, or communication style
- You need agents to remember project-specific context
- You want to add custom menu items that trigger your own workflows or prompts
- You want agents to perform specific actions every time they start up
:::note[Prerequisites]
- BMad installed in your project (see [How to Install BMad](./install-bmad.md))
- A text editor for YAML files
:::
:::caution[Keep Your Customizations Safe]
Always use the `.customize.yaml` files described here rather than editing agent files directly. The installer overwrites agent files during updates, but preserves your `.customize.yaml` changes.
:::
## Steps
### 1. Locate Customization Files
After installation, find one `.customize.yaml` file per agent in:
```text
_bmad/_config/agents/
├── core-bmad-master.customize.yaml
├── bmm-dev.customize.yaml
├── bmm-pm.customize.yaml
└── ... (one file per installed agent)
```
### 2. Edit the Customization File
Open the `.customize.yaml` file for the agent you want to modify. Every section is optional -- customize only what you need.
| Section | Behavior | Purpose |
| ------------------- | ------------ | ---------------------------------------------- |
| `agent.metadata` | Replaces | Override the agent's display name |
| `persona` | Replaces | Set role, identity, style, and principles |
| `memories` | Appends | Add persistent context the agent always recalls |
| `menu` | Appends | Add custom menu items for workflows or prompts |
| `critical_actions` | Appends | Define startup instructions for the agent |
| `prompts` | Appends | Create reusable prompts for menu actions |
Sections marked **Replaces** overwrite the agent's defaults entirely. Sections marked **Appends** add to the existing configuration.
**Agent Name**
Change how the agent introduces itself:
```yaml
agent:
metadata:
name: 'Spongebob' # Default: "Amelia"
```
**Persona**
Replace the agent's personality, role, and communication style:
```yaml
persona:
role: 'Senior Full-Stack Engineer'
identity: 'Lives in a pineapple (under the sea)'
communication_style: 'Spongebob annoying'
principles:
- 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
- 'Favor composition over inheritance'
```
The `persona` section replaces the entire default persona, so include all four fields if you set it.
**Memories**
Add persistent context the agent will always remember:
```yaml
memories:
- 'Works at Krusty Krab'
- 'Favorite Celebrity: David Hasslehoff'
- 'Learned in Epic 1 that it is not cool to just pretend that tests have passed'
```
**Menu Items**
Add custom entries to the agent's display menu. Each item needs a `trigger`, a target (`workflow` path or `action` reference), and a `description`:
```yaml
menu:
- trigger: my-workflow
workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
description: My custom workflow
- trigger: deploy
action: '#deploy-prompt'
description: Deploy to production
```
**Critical Actions**
Define instructions that run when the agent starts up:
```yaml
critical_actions:
- 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'
```
**Custom Prompts**
Create reusable prompts that menu items can reference with `action="#id"`:
```yaml
prompts:
- id: deploy-prompt
content: |
Deploy the current branch to production:
1. Run all tests
2. Build the project
3. Execute deployment script
```
### 3. Apply Your Changes
After editing, recompile the agent to apply changes:
```bash
npx bmad-method install
```
The installer detects the existing installation and offers these options:
| Option | What It Does |
| --------------------- | ------------------------------------------------------------------- |
| **Quick Update** | Updates all modules to the latest version and recompiles all agents |
| **Recompile Agents** | Applies customizations only, without updating module files |
| **Modify BMad Installation** | Full installation flow for adding or removing modules |
For customization-only changes, **Recompile Agents** is the fastest option.
## Troubleshooting
**Changes not appearing?**
- Run `npx bmad-method install` and select **Recompile Agents** to apply changes
- Check that your YAML syntax is valid (indentation matters)
- Verify you edited the correct `.customize.yaml` file for the agent
**Agent not loading?**
- Check for YAML syntax errors using an online YAML validator
- Ensure you did not leave fields empty after uncommenting them
- Try reverting to the original template and rebuilding
**Need to reset an agent?**
- Clear or delete the agent's `.customize.yaml` file
- Run `npx bmad-method install` and select **Recompile Agents** to restore defaults
## Workflow Customization
Customization of existing BMad Method workflows and skills is coming soon.
## Module Customization
Guidance on building expansion modules and customizing existing modules is coming soon.

58
docs/modules/bmm-bmad-method/brownfield-guide.md → docs/how-to/established-projects.md
View File

@ -1,23 +1,32 @@
# BMad Method Brownfield Development Guide
## Working on Existing Projects
If you have completed your initial PRD on a new project and want to add new features, or if you have a legacy project you are maintaining, you will want to follow the brownfield process.
This document is intentionally brief, focusing only on what differs from the standard greenfield flow.
---
title: "Established Projects"
description: How to use BMad Method on existing codebases
sidebar:
order: 6
---
## 1. Clean Up Completed Planning Artifacts
Use BMad Method effectively when working on existing projects and legacy codebases, sometimes also referred to as brownfield projects.
This guide covers the essential workflow for onboarding to existing projects with BMad Method.
:::note[Prerequisites]
- BMad Method installed (`npx bmad-method install`)
- An existing codebase you want to work on
- Access to an AI-powered IDE (Claude Code, Cursor, or Windsurf)
:::
## Step 1: Clean Up Completed Planning Artifacts
If you have completed all PRD epics and stories through the BMad process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
- `docs/`
- `_bmad-output/planning-artifacts/`
- `_bmad-output/implementation-artifacts/`
## 2. Maintain Quality Project Documentation
## Step 2: Maintain Quality Project Documentation
Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
- Intent and business rationale
- Business rules
- Architecture
@ -25,9 +34,11 @@ Your `docs/` folder should contain succinct, well-organized documentation that a
For complex projects, consider using the `document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state.
## 3. Initialize for Brownfield Work
## Step 3: Get Help
Run `workflow-init`. It should recognize you are in an existing project. If not, explicitly clarify that this is brownfield development for a new feature.
Get help to know what to do next based on your unique needs
Run `bmad-help` to get guidance when you are not sure what to do next.
### Choosing Your Approach
@ -35,12 +46,13 @@ You have two primary options depending on the scope of changes:
| Scope | Recommended Approach |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad method is likely overkill. |
| **Major changes or additions** | Start with the BMad method, applying as much or as little rigor as needed. |
| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad Method is likely overkill. |
| **Major changes or additions** | Start with the BMad Method, applying as much or as little rigor as needed. |
### During PRD Creation
When creating a brief or jumping directly into the PRD, ensure the agent:
- Finds and analyzes your existing project documentation
- Reads the proper context about your current system
@ -49,6 +61,7 @@ You can guide the agent explicitly, but the goal is to ensure the new feature in
### UX Considerations
UX work is optional. The decision depends not on whether your project has a UX, but on:
- Whether you will be working on UX changes
- Whether significant new UX designs or patterns are needed
@ -57,22 +70,13 @@ If your changes amount to simple updates to existing screens you are happy with,
### Architecture Considerations
When doing architecture, ensure the architect:
- Uses the proper documented files
- Scans the existing codebase
Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
---
## More Information
## 4. Ad-Hoc Changes
Not everything requires the full BMad method or even quick-flow. For bug fixes, refactorings, or small targeted changes, simply talk to the agent and have it make the changes directly. This is also a good way to learn about your codebase and understand the modifications being made.
---
## 5. Learn and Explore
Remember, LLMs are excellent at interpreting and analyzing code—whether it was AI-generated or not. Use the agent to:
- Learn about your project
- Understand how things are built
- Explore unfamiliar parts of the codebase
- **[Quick Fixes](./quick-fixes.md)** - Bug fixes and ad-hoc changes
- **[Established Projects FAQ](../explanation/established-projects-faq.md)** - Common questions about working on established projects

103
docs/how-to/get-answers-about-bmad.md Normal file
View File

@ -0,0 +1,103 @@
---
title: "How to Get Answers About BMad"
description: Use an LLM to quickly answer your own BMad questions
sidebar:
order: 4
---
If you have successfully installed BMad and the BMad Method (+ other modules as needed) - the first step in getting answers is `/bmad-help`. This will answer upwards of 80% of all questions and is available to you in the IDE as you are working.
## When to Use This
- You have a question about how BMad works or what to do next with BMad
- You want to understand a specific agent or workflow
- You need quick answers without waiting for Discord
:::note[Prerequisites]
An AI tool (Claude Code, Cursor, ChatGPT, Claude.ai, etc.) and either BMad installed in your project or access to the GitHub repo.
:::
## Steps
### 1. Choose Your Source
| Source | Best For | Examples |
| -------------------- | ----------------------------------------- | ---------------------------- |
| **`_bmad` folder** | How BMad works—agents, workflows, prompts | "What does the PM agent do?" |
| **Full GitHub repo** | History, installer, architecture | "What changed in v6?" |
| **`llms-full.txt`** | Quick overview from docs | "Explain BMad's four phases" |
The `_bmad` folder is created when you install BMad. If you don't have it yet, clone the repo instead.
### 2. Point Your AI at the Source
**If your AI can read files (Claude Code, Cursor, etc.):**
- **BMad installed:** Point at the `_bmad` folder and ask directly
- **Want deeper context:** Clone the [full repo](https://github.com/bmad-code-org/BMAD-METHOD)
**If you use ChatGPT or Claude.ai:**
Fetch `llms-full.txt` into your session:
```text
https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
```
### 3. Ask Your Question
:::note[Example]
**Q:** "Tell me the fastest way to build something with BMad"
**A:** Use Quick Flow: Run `quick-spec` to write a technical specification, then `quick-dev` to implement it—skipping the full planning phases.
:::
## What You Get
Direct answers about BMad—how agents work, what workflows do, why things are structured the way they are—without waiting for someone else to respond.
## Tips
- **Verify surprising answers** — LLMs occasionally get things wrong. Check the source file or ask on Discord.
- **Be specific** — "What does step 3 of the PRD workflow do?" beats "How does PRD work?"
## Still Stuck?
Tried the LLM approach and still need help? You now have a much better question to ask.
| Channel | Use For |
| ------------------------- | ------------------------------------------- |
| `#bmad-method-help` | Quick questions (real-time chat) |
| `help-requests` forum | Detailed questions (searchable, persistent) |
| `#suggestions-feedback` | Ideas and feature requests |
| `#report-bugs-and-issues` | Bug reports |
**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
**GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) (for clear bugs)
*You!*
*Stuck*
*in the queue—*
*waiting*
*for who?*
*The source*
*is there,*
*plain to see!*
*Point*
*your machine.*
*Set it free.*
*It reads.*
*It speaks.*
*Ask away—*
*Why wait*
*for tomorrow*
*when you have*
*today?*
*—Claude*

88
docs/how-to/install-bmad.md Normal file
View File

@ -0,0 +1,88 @@
---
title: "How to Install BMad"
description: Step-by-step guide to installing BMad in your project
sidebar:
order: 1
---
Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools.
If you want to use a non interactive installer and provide all install options on the command line, see [this guide](./non-interactive-installation.md).
## When to Use This
- Starting a new project with BMad
- Adding BMad to an existing codebase
- Update the existing BMad Installation
:::note[Prerequisites]
- **Node.js** 20+ (required for the installer)
- **Git** (recommended)
- **AI tool** (Claude Code, Cursor, Windsurf, or similar)
:::
## Steps
### 1. Run the Installer
```bash
npx bmad-method install
```
:::tip[Bleeding edge]
To install the latest from the main branch (may be unstable):
```bash
npx github:bmad-code-org/BMAD-METHOD install
```
:::
### 2. Choose Installation Location
The installer will ask where to install BMad files:
- Current directory (recommended for new projects if you created the directory yourself and ran from within the directory)
- Custom path
### 3. Select Your AI Tools
Pick which AI tools you use:
- Claude Code
- Cursor
- Windsurf
- Kiro
- Others
Each tool has its own way of integrating commands. The installer creates tiny prompt files to activate workflows and agents — it just puts them where your tool expects to find them.
### 4. Choose Modules
The installer shows available modules. Select whichever ones you need — most users just want **BMad Method** (the software development module).
### 5. Follow the Prompts
The installer guides you through the rest — custom content, settings, etc.
## What You Get
```text
your-project/
├── _bmad/
│ ├── bmm/ # Your selected modules
│ │ └── config.yaml # Module settings (if you ever need to change them)
│ ├── core/ # Required core module
│ └── ...
├── _bmad-output/ # Generated artifacts
├── .claude/ # Claude Code commands (if using Claude Code)
└── .kiro/ # Kiro steering files (if using Kiro)
```
## Verify Installation
Run the `help` workflow (`/bmad-help` on most platforms) to verify everything works and see what to do next.
## Troubleshooting
**Installer throws an error** — Copy-paste the output into your AI assistant and let it figure it out.
**Installer worked but something doesn't work later** — Your AI needs BMad context to help. See [How to Get Answers About BMad](./get-answers-about-bmad.md) for how to point your AI at the right sources.

171
docs/how-to/non-interactive-installation.md Normal file
View File

@ -0,0 +1,171 @@
---
title: Non-Interactive Installation
description: Install BMad using command-line flags for CI/CD pipelines and automated deployments
sidebar:
order: 2
---
Use command-line flags to install BMad non-interactively. This is useful for:
## When to Use This
- Automated deployments and CI/CD pipelines
- Scripted installations
- Batch installations across multiple projects
- Quick installations with known configurations
:::note[Prerequisites]
Requires [Node.js](https://nodejs.org) v20+ and `npx` (included with npm).
:::
## Available Flags
### Installation Options
| Flag | Description | Example |
|------|-------------|---------|
| `--directory <path>` | Installation directory | `--directory ~/projects/myapp` |
| `--modules <modules>` | Comma-separated module IDs | `--modules bmm,bmb` |
| `--tools <tools>` | Comma-separated tool/IDE IDs (use `none` to skip) | `--tools claude-code,cursor` or `--tools none` |
| `--custom-content <paths>` | Comma-separated paths to custom modules | `--custom-content ~/my-module,~/another-module` |
| `--action <type>` | Action for existing installations: `install` (default), `update`, `quick-update`, or `compile-agents` | `--action quick-update` |
### Core Configuration
| Flag | Description | Default |
|------|-------------|---------|
| `--user-name <name>` | Name for agents to use | System username |
| `--communication-language <lang>` | Agent communication language | English |
| `--document-output-language <lang>` | Document output language | English |
| `--output-folder <path>` | Output folder path | _bmad-output |
### Other Options
| Flag | Description |
|------|-------------|
| `-y, --yes` | Accept all defaults and skip prompts |
| `-d, --debug` | Enable debug output for manifest generation |
## Module IDs
Available module IDs for the `--modules` flag:
- `bmm` — BMad Method Master
- `bmb` — BMad Builder
Check the [BMad registry](https://github.com/bmad-code-org) for available external modules.
## Tool/IDE IDs
Available tool IDs for the `--tools` flag:
**Preferred:** `claude-code`, `cursor`, `windsurf`
Run `npx bmad-method install` interactively once to see the full current list of supported tools, or check the [platform codes configuration](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml).
## Installation Modes
| Mode | Description | Example |
|------|-------------|---------|
| Fully non-interactive | Provide all flags to skip all prompts | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` |
| Semi-interactive | Provide some flags; BMad prompts for the rest | `npx bmad-method install --directory . --modules bmm` |
| Defaults only | Accept all defaults with `-y` | `npx bmad-method install --yes` |
| Without tools | Skip tool/IDE configuration | `npx bmad-method install --modules bmm --tools none` |
## Examples
### CI/CD Pipeline Installation
```bash
#!/bin/bash
# install-bmad.sh
npx bmad-method install \
--directory "${GITHUB_WORKSPACE}" \
--modules bmm \
--tools claude-code \
--user-name "CI Bot" \
--communication-language English \
--document-output-language English \
--output-folder _bmad-output \
--yes
```
### Update Existing Installation
```bash
npx bmad-method install \
--directory ~/projects/myapp \
--action update \
--modules bmm,bmb,custom-module
```
### Quick Update (Preserve Settings)
```bash
npx bmad-method install \
--directory ~/projects/myapp \
--action quick-update
```
### Installation with Custom Content
```bash
npx bmad-method install \
--directory ~/projects/myapp \
--modules bmm \
--custom-content ~/my-custom-module,~/another-module \
--tools claude-code
```
## What You Get
- A fully configured `_bmad/` directory in your project
- Compiled agents and workflows for your selected modules and tools
- A `_bmad-output/` folder for generated artifacts
## Validation and Error Handling
BMad validates all provided flags:
- **Directory** — Must be a valid path with write permissions
- **Modules** — Warns about invalid module IDs (but won't fail)
- **Tools** — Warns about invalid tool IDs (but won't fail)
- **Custom Content** — Each path must contain a valid `module.yaml` file
- **Action** — Must be one of: `install`, `update`, `quick-update`, `compile-agents`
Invalid values will either:
1. Show an error and exit (for critical options like directory)
2. Show a warning and skip (for optional items like custom content)
3. Fall back to interactive prompts (for missing required values)
:::tip[Best Practices]
- Use absolute paths for `--directory` to avoid ambiguity
- Test flags locally before using in CI/CD pipelines
- Combine with `-y` for truly unattended installations
- Use `--debug` if you encounter issues during installation
:::
## Troubleshooting
### Installation fails with "Invalid directory"
- The directory path must exist (or its parent must exist)
- You need write permissions
- The path must be absolute or correctly relative to the current directory
### Module not found
- Verify the module ID is correct
- External modules must be available in the registry
### Custom content path invalid
Ensure each custom content path:
- Points to a directory
- Contains a `module.yaml` file in the root
- Has a `code` field in the `module.yaml`
:::note[Still stuck?]
Run with `--debug` for detailed output, try interactive mode to isolate the issue, or report at <https://github.com/bmad-code-org/BMAD-METHOD/issues>.
:::

123
docs/how-to/quick-fixes.md Normal file
View File

@ -0,0 +1,123 @@
---
title: "Quick Fixes"
description: How to make quick fixes and ad-hoc changes
sidebar:
order: 5
---
Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad Method or Quick Flow.
## When to Use This
- Bug fixes with a clear, known cause
- Small refactorings (rename, extract, restructure) contained within a few files
- Minor feature tweaks or configuration changes
- Exploratory work to understand an unfamiliar codebase
:::note[Prerequisites]
- BMad Method installed (`npx bmad-method install`)
- An AI-powered IDE (Claude Code, Cursor, Windsurf, or similar)
:::
## Choose Your Approach
| Situation | Agent | Why |
| --- | --- | --- |
| Fix a specific bug or make a small, scoped change | **DEV agent** | Jumps straight into implementation without planning overhead |
| Change touches several files or you want a written plan first | **Quick Flow Solo Dev** | Creates a quick-spec before implementation so the agent stays aligned to your standards |
If you are unsure, start with the DEV agent. You can always escalate to Quick Flow if the change grows.
## Steps
### 1. Load the DEV Agent
Start a **fresh chat** in your AI IDE and load the DEV agent with its slash command:
```text
/bmad-agent-bmm-dev
```
This loads the agent's persona and capabilities into the session. If you decide you need Quick Flow instead, load the **Quick Flow Solo Dev** agent in a fresh chat:
```text
/bmad-agent-bmm-quick-flow-solo-dev
```
Once the Solo Dev agent is loaded, describe your change and ask it to create a **quick-spec**. The agent drafts a lightweight spec capturing what you want to change and how. After you approve the quick-spec, tell the agent to start the **Quick Flow dev cycle** -- it will implement the change, run tests, and perform a self-review, all guided by the spec you just approved.
:::tip[Fresh Chats]
Always start a new chat session when loading an agent. Reusing a session from a previous workflow can cause context conflicts.
:::
### 2. Describe the Change
Tell the agent what you need in plain language. Be specific about the problem and, if you know it, where the relevant code lives.
:::note[Example Prompts]
**Bug fix** -- "Fix the login validation bug that allows empty passwords. The validation logic is in `src/auth/validate.ts`."
**Refactoring** -- "Refactor the UserService to use async/await instead of callbacks."
**Configuration change** -- "Update the CI pipeline to cache node_modules between runs."
**Dependency update** -- "Upgrade the express dependency to the latest v5 release and fix any breaking changes."
:::
You don't need to provide every detail. The agent will read the relevant source files and ask clarifying questions when needed.
### 3. Let the Agent Work
The agent will:
- Read and analyze the relevant source files
- Propose a solution and explain its reasoning
- Implement the change across the affected files
- Run your project's test suite if one exists
If your project has tests, the agent runs them automatically after making changes and iterates until tests pass. For projects without a test suite, verify the change manually (run the app, hit the endpoint, check the output).
### 4. Review and Verify
Before committing, review what changed:
- Read through the diff to confirm the change matches your intent
- Run the application or tests yourself to double-check
- If something looks wrong, tell the agent what to fix -- it can iterate in the same session
Once satisfied, commit the changes with a clear message describing the fix.
:::caution[If Something Breaks]
If a committed change causes unexpected issues, use `git revert HEAD` to undo the last commit cleanly. Then start a fresh chat with the DEV agent to try a different approach.
:::
## Learning Your Codebase
The DEV agent is also useful for exploring unfamiliar code. Load it in a fresh chat and ask questions:
:::note[Example Prompts]
"Explain how the authentication system works in this codebase."
"Show me where error handling happens in the API layer."
"What does the `ProcessOrder` function do and what calls it?"
:::
Use the agent to learn about your project, understand how components connect, and explore unfamiliar areas before making changes.
## What You Get
- Modified source files with the fix or refactoring applied
- Passing tests (if your project has a test suite)
- A clean commit describing the change
No planning artifacts are produced -- that's the point of this approach.
## When to Upgrade to Formal Planning
Consider using [Quick Flow](../explanation/quick-flow.md) or the full BMad Method when:
- The change affects multiple systems or requires coordinated updates across many files
- You are unsure about the scope and need a spec to think it through
- The fix keeps growing in complexity as you work on it
- You need documentation or architectural decisions recorded for the team

78
docs/how-to/shard-large-documents.md Normal file
View File

@ -0,0 +1,78 @@
---
title: "Document Sharding Guide"
description: Split large markdown files into smaller organized files for better context management
sidebar:
order: 8
---
Use the `shard-doc` tool if you need to split large markdown files into smaller, organized files for better context management.
:::caution[Deprecated]
This is no longer recommended, and soon with updated workflows and most major LLMs and tools supporting subprocesses this will be unnecessary.
:::
## When to Use This
Only use this if you notice your chosen tool / model combination is failing to load and read all the documents as input when needed.
## What is Document Sharding?
Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`).
### Architecture
```text
Before Sharding:
docs/
└── PRD.md (large 50k token file)
After Sharding:
docs/
└── prd/
├── index.md # Table of contents with descriptions
├── overview.md # Section 1
├── user-requirements.md # Section 2
├── technical-requirements.md # Section 3
└── ... # Additional sections
```
## Steps
### 1. Run the Shard-Doc Tool
```bash
/bmad-shard-doc
```
### 2. Follow the Interactive Process
```text
Agent: Which document would you like to shard?
User: docs/PRD.md
Agent: Default destination: docs/prd/
Accept default? [y/n]
User: y
Agent: Sharding PRD.md...
✓ Created 12 section files
✓ Generated index.md
✓ Complete!
```
## How Workflow Discovery Works
BMad workflows use a **dual discovery system**:
1. **Try whole document first** - Look for `document-name.md`
2. **Check for sharded version** - Look for `document-name/index.md`
3. **Priority rule** - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead
## Workflow Support
All BMM workflows support both formats:
- Whole documents
- Sharded documents
- Automatic detection
- Transparent to user

97
docs/how-to/upgrade-to-v6.md Normal file
View File

@ -0,0 +1,97 @@
---
title: "How to Upgrade to v6"
description: Migrate from BMad v4 to v6
sidebar:
order: 3
---
Use the BMad installer to upgrade from v4 to v6, which includes automatic detection of legacy installations and migration assistance.
## When to Use This
- You have BMad v4 installed (`.bmad-method` folder)
- You want to migrate to the new v6 architecture
- You have existing planning artifacts to preserve
:::note[Prerequisites]
- Node.js 20+
- Existing BMad v4 installation
:::
## Steps
### 1. Run the Installer
Follow the [Installer Instructions](./install-bmad.md).
### 2. Handle Legacy Installation
When v4 is detected, you can:
- Allow the installer to back up and remove `.bmad-method`
- Exit and handle cleanup manually
If you named your bmad method folder something else - you will need to manually remove the folder yourself.
### 3. Clean Up IDE Commands
Manually remove legacy v4 IDE commands - for example if you have claude, look for any nested folders that start with bmad and remove them:
- `.claude/commands/BMad/agents`
- `.claude/commands/BMad/tasks`
### 4. Migrate Planning Artifacts
**If you have planning documents (Brief/PRD/UX/Architecture):**
Move them to `_bmad-output/planning-artifacts/` with descriptive names:
- Include `PRD` in filename for PRD documents
- Include `brief`, `architecture`, or `ux-design` accordingly
- Sharded documents can be in named subfolders
**If you're mid-planning:** Consider restarting with v6 workflows. Use your existing documents as inputs—the new progressive discovery workflows with web search and IDE plan mode produce better results.
### 5. Migrate In-Progress Development
If you have stories created or implemented:
1. Complete the v6 installation
2. Place `epics.md` or `epics/epic*.md` in `_bmad-output/planning-artifacts/`
3. Run the Scrum Master's `sprint-planning` workflow
4. Tell the SM which epics/stories are already complete
## What You Get
**v6 unified structure:**
```text
your-project/
├── _bmad/ # Single installation folder
│ ├── _config/ # Your customizations
│ │ └── agents/ # Agent customization files
│ ├── core/ # Universal core framework
│ ├── bmm/ # BMad Method module
│ ├── bmb/ # BMad Builder
│ └── cis/ # Creative Intelligence Suite
└── _bmad-output/ # Output folder (was doc folder in v4)
```
## Module Migration
| v4 Module | v6 Status |
| ----------------------------- | ----------------------------------------- |
| `.bmad-2d-phaser-game-dev` | Integrated into BMGD Module |
| `.bmad-2d-unity-game-dev` | Integrated into BMGD Module |
| `.bmad-godot-game-dev` | Integrated into BMGD Module |
| `.bmad-infrastructure-devops` | Deprecated — new DevOps agent coming soon |
| `.bmad-creative-writing` | Not adapted — new v6 module coming soon |
## Key Changes
| Concept | v4 | v6 |
| ------------- | ------------------------------------- | ------------------------------------ |
| **Core** | `_bmad-core` was actually BMad Method | `_bmad/core/` is universal framework |
| **Method** | `_bmad-method` | `_bmad/bmm/` |
| **Config** | Modified files directly | `config.yaml` per module |
| **Documents** | Sharded or unsharded required setup | Fully flexible, auto-scanned |

4
docs/improvements/epic-chain-report-proposal.md
View File

@ -1,3 +1,7 @@
---
title: "Epic Chain Execution Report Generator - Proposal"
---
# Epic Chain Execution Report Generator - Proposal
## Overview

4
docs/improvements/epic-workflows-v1.md
View File

@ -1,3 +1,7 @@
---
title: Epic Workflows Improvement Plan v1
---
# Epic Workflows Improvement Plan v1
**Date:** 2026-01-02

4
docs/improvements/party-mode-integration/01-implementation-plan.md
View File

@ -1,3 +1,7 @@
---
title: "Implementation Plan: Party Mode Integration with Epic Execute"
---
# Implementation Plan: Party Mode Integration with Epic Execute
## Option B: Configurable Party Mode

4
docs/improvements/party-mode-integration/02-context-management.md
View File

@ -1,3 +1,7 @@
---
title: Context Management Deep Dive
---
# Context Management Deep Dive
**Document**: 02-context-management.md

4
docs/improvements/party-mode-integration/03-file-modifications.md
View File

@ -1,3 +1,7 @@
---
title: File Modifications Specification
---
# File Modifications Specification
**Document**: 03-file-modifications.md

10
docs/improvements/party-mode-integration/README.md
View File

@ -1,3 +1,7 @@
---
title: Party Mode Integration with Epic Execute
---
# Party Mode Integration with Epic Execute
**Status**: Planning
@ -17,7 +21,7 @@ This folder contains the complete documentation for integrating Party Mode's mul
| [01-implementation-plan.md](./01-implementation-plan.md) | High-level implementation plan with CLI flags, configuration, and phases |
| [02-context-management.md](./02-context-management.md) | Deep dive into context isolation architecture and data transfer mechanisms |
| [03-file-modifications.md](./03-file-modifications.md) | Detailed specification of all file changes required |
| [04-prompt-engineering.md](./04-prompt-engineering.md) | Prompt templates for each party phase (future) |
| 04-prompt-engineering.md | Prompt templates for each party phase (future - not yet created) |
## Quick Links
@ -123,8 +127,8 @@ This folder contains the complete documentation for integrating Party Mode's mul
## Related Documents
- [Epic Workflows v1 Improvements](../epic-workflows-v1.md) - General workflow improvements
- [Party Mode Core Docs](../../../src/core/workflows/party-mode/workflow.md) - Party Mode workflow definition
- [Epic Execute Workflow](../../../src/modules/bmm/workflows/4-implementation/epic-execute/workflow.md) - Current workflow
- Party Mode Core Docs: `src/core/workflows/party-mode/workflow.md`
- Epic Execute Workflow: `src/modules/bmm/workflows/4-implementation/epic-execute/workflow.md`
---

4
docs/improvements/uat-implementation-plan.md
View File

@ -1,3 +1,7 @@
---
title: UAT Workflow Implementation Plan
---
# UAT Workflow Implementation Plan
**Date:** 2026-01-05

4
docs/improvements/uat-integration-architecture.md
View File

@ -1,3 +1,7 @@
---
title: UAT Validation Integration Architecture
---
# UAT Validation Integration Architecture
## Overview

4
docs/improvements/uat-workflow-implementation-gaps.md
View File

@ -1,3 +1,7 @@
---
title: "UAT Workflow Implementation Gaps & Required Fixes"
---
# UAT Workflow Implementation Gaps & Required Fixes
## Executive Summary

125
docs/index.md
View File

@ -1,111 +1,50 @@
# BMAD Documentation
Complete documentation for the BMAD Method.
## Getting Started
### New to BMAD?
Start with the core concepts to understand how BMAD works:
- **[Core Concepts](./bmad-core-concepts/)** - Agents, workflows, and modules explained
- **[Installation Guide](./bmad-core-concepts/installing/)** - Set up BMAD in your project
- **[Quick Start Guide](./modules/bmm-bmad-method/quick-start)** - Build your first feature
### Upgrading from v4?
- **[v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md)** - Migration path for v4 users
---
title: Welcome to the BMad Method
description: AI-driven development framework with specialized agents, guided workflows, and intelligent planning
---
## Module Documentation
The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework that helps you build software through the whole process from ideation and planning all the way through agentic implementation. 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 Method (BMM) - Software & Game Development
If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
The flagship module for agile AI-driven development.
## New Here? Start with a Tutorial
- **[BMM Module Index](./modules/bmm-bmad-method/index)** - Module overview, agents, and documentation
- [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Step-by-step guide
- [Quick Spec Flow](./modules/bmm-bmad-method/quick-spec-flow) - Rapid Level 0-1 development
- [Brownfield Guide](./modules/bmm-bmad-method/brownfield-guide) - Working with existing codebases
- **[BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides)** - Essential reading
The fastest way to understand BMad is to try it.
### BMAD Builder (BMB) - Create Custom Solutions
- **[Get Started with BMad](./tutorials/getting-started.md)** — Install and understand how BMad works
- **[Workflow Map](./reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management.
Build your own agents, workflows, and modules.
## How to Use These Docs
- **[BMB Module Overview](./modules/bmb-bmad-builder/index)** - Module overview and capabilities
- **[Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md)** - Create custom agents
- **[Custom Content Installation](./modules/bmb-bmad-builder/custom-content-installation.md)** - Share and install custom creations
These docs are organized into four sections based on what you're trying to do:
### Creative Intelligence Suite (CIS) - Innovation & Creativity
| Section | Purpose |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| **Tutorials** | Learning-oriented. Step-by-step guides that walk you through building something. Start here if you're new. |
| **How-To Guides** | Task-oriented. Practical guides for solving specific problems. "How do I customize an agent?" lives here. |
| **Explanation** | Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know *why*. |
| **Reference** | Information-oriented. Technical specifications for agents, workflows, and configuration. |
- **[CIS Documentation](./modules/cis-creative-intelligence-suite/index)**
## What You'll Need
### BMAD Game Dev (BMGD)
BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
- **[BMGD Documentation](./modules/bmgd-bmad-game-dev/index)** - Game development workflows
- **[Claude Code](https://code.claude.com)** — Anthropic's CLI tool (recommended)
- **[Cursor](https://cursor.sh)** — AI-first code editor
- **[Windsurf](https://codeium.com/windsurf)** — Codeium's AI IDE
- **[Kiro](https://kiro.dev)** — Amazon's AI-powered 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.
## Core Module
## Join the Community
### Global Core Entities
Get help, share what you're building, or contribute to BMad:
- **[Core Module Index](./modules/core/index)** - Shared functionality available to all modules
- [Global Core Config](./modules/core/global-core-config.md) - Inheritable configuration
- [Core Workflows](./modules/core/core-workflows.md) - Domain-agnostic workflows
- [Party Mode](./modules/core/party-mode.md) - Multi-agent conversations
- [Brainstorming](./modules/core/brainstorming.md) - Structured creative sessions
- [Advanced Elicitation](./modules/core/advanced-elicitation.md) - LLM reasoning techniques
- [Core Tasks](./modules/core/core-tasks.md) - Common tasks across modules
- **[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
---
## Next Step
## Advanced Topics
### Customization
- **[BMAD Customization](./bmad-core-concepts/bmad-customization/)** - Modify agents and workflows
### Platform Guides
- **[Web Bundles](./bmad-core-concepts/web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs
---
## Recommended Reading Paths
### Path 1: Brand New to BMAD (Software Project)
1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows
2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD
3. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on
4. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology
### Path 2: Game Development Project
1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows
2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD
3. [BMGD Workflows Guide](./modules/bmgd-bmad-game-dev/workflows-guide) - Game-specific workflows
### Path 3: Upgrading from v4
1. [v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md) - Understand what changed
2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Reorient yourself
3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Learn new v6 workflows
### Path 4: Working with Existing Codebase (Brownfield)
1. [Brownfield Guide](./modules/bmm-bmad-method/brownfield-guide) - Approach for legacy code
2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Follow the process
3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology
### Path 5: Building Custom Agents
1. [Core Concepts: Agents](./bmad-core-concepts/agents.md) - Understand Simple vs Expert
2. [Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md) - Build your first agent
3. [Agent Architecture](./modules/bmb-bmad-builder/index) - Deep technical details
### Path 6: Contributing to BMAD
1. [CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md) - Contribution guidelines
2. Relevant module README - Understand the area you're contributing to
Ready to dive in? **[Get Started with BMad](./tutorials/getting-started.md)** and build your first project.

166
docs/modules/bmb-bmad-builder/agent-creation-guide.md
View File

@ -1,166 +0,0 @@
# Agent Creation Guide
Create your own custom agents using the BMAD Builder workflow.
## Overview
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.
## Before You Start
**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?
## Quick Start
### 1. Start the Workflow
In your IDE (Claude Code, Cursor, etc.), invoke the create-agent workflow:
```
"Run the BMAD Builder create-agent workflow"
```
Or trigger it via the BMAD Master menu.
### 2. Follow the 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 |
### 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
```
See [Custom Content Installation](./custom-content-installation.md) for details.
## Choosing Your Agent Type
The workflow will help you decide, but here's the quick reference:
### Choose Simple Agent When:
- 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)
**Example:** A "Code Commenter" that reads files and adds helpful comments.
### Choose Expert Agent When:
- Domain requires specialized knowledge
- Need persistent memory across sessions
- Agent coordinates complex workflows
- Building ongoing project infrastructure
**Example:** A "Security Architect" that remembers your design decisions and maintains security standards across the project.
### Choose Module Agent When:
- Agent builds other agents or workflows
- Need integration with module system
- Creating professional tooling
**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
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)
### Write 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"
### 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](../../bmad-core-concepts/installing/)) and share it with your team or the community.
## Further Reading
- **[Agent Architecture](./index.md)** - Deep technical details on agent types
- **[Agent Customization](../../bmad-core-concepts/agent-customization/)** - Modify agents without editing core files
- **[Custom Content Installation](./custom-content-installation.md)** - Package and distribute your agents
---
**Ready?** Start the workflow and create your first agent!
[← Back to BMB Documentation](./index.md)

149
docs/modules/bmb-bmad-builder/custom-content-installation.md
View File

@ -1,149 +0,0 @@
# Custom Content Installation
This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content extends BMAD's functionality with specialized tools and workflows that can be shared across projects or teams.
For detailed information about the different types of custom content available, see [Custom Content](modules/bmb-bmad-builder/custom-content.md).
You can find example custom modules in the `samples/sample-custom-modules/` folder of the repository. Download either of the sample folders to try them out.
## Content Types Overview
BMAD Core supports several categories of custom content:
- Custom Stand Alone Modules
- Custom Add On Modules
- Custom Global Modules
- Custom Agents
- Custom Workflows
## Making Custom Content Installable
### Custom Modules
To create an installable custom module:
1. **Folder Structure**
- Create a folder with a short, abbreviated name (e.g., `cis` for Creative Intelligence Suite)
- The folder name serves as the module code
2. **Required File**
- Include a `module.yaml` file in the root folder (this drives questions for the final generated config.yaml at install target)
3. **Folder Organization**
Follow these conventions for optimal compatibility:
```
module-code/
module.yaml
agents/
workflows/
tools/
templates/
...
```
- `agents/` - Agent definitions
- `workflows/` - Workflow definitions
- Additional custom folders are supported but following conventions is recommended for agent and workflow discovery
**Note:** Full documentation for global modules and add-on modules will be available as support is finalized.
### Standalone Content (Agents, Workflows, Tasks, Tools, Templates, Prompts)
For standalone content that isn't part of a cohesive module collection, follow this structure:
1. **Module Configuration**
- Create a folder with a `module.yaml` file (similar to custom modules)
- Add the property `unitary: true` in the module.yaml
- The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other
- Any content you add to this folder should still be nested under workflows and agents - but the key with stand alone content is they do not rely on each other.
- Agents do not reference other workflows even if stored in a unitary:true module. But unitary Agents can have their own workflows in their sidecar, or reference workflows as requirements from other modules - with a process known as workflow vendoring. Keep in mind, this will require that the workflow referenced from the other module would need to be available for the end user to install, so its recommended to only vendor workflows from the core module, or official bmm modules (See [Workflow Vendoring, Customization, and Inheritance](workflow-vendoring-customization-inheritance.md)).
2. **Folder Structure**
Organize content in specific named folders:
```
module-name/
module.yaml # Contains unitary: true
agents/
workflows/
templates/
tools/
tasks/
prompts/
```
3. **Individual Item Organization**
Each item should have its own subfolder:
```text
my-custom-stuff/
module.yaml
agents/
larry/larry.agent.md
curly/curly.agent.md
moe/moe.agent.md
moe/moe-sidecar/memories.csv
```
**Future Feature:** Unitary modules will support selective installation, allowing users to pick and choose which specific items to install.
**Note:** Documentation explaining the distinctions between these content types and their specific use cases will be available soon.
## Installation Process
### Prerequisites
Ensure your content follows the proper conventions and includes a `module.yaml` file (only one per top-level folder).
### New Project Installation
When setting up a new BMAD project:
1. The installer will prompt: `Would you like to install a local custom module (this includes custom agents and workflows also)? (y/N)`
2. Select 'y' to specify the path to your module folder containing `module.yaml`
### Existing Project Modification
To add custom content to an existing BMAD project:
1. Run the installer against your project location
2. Select `Modify BMAD Installation`
3. Choose the option to add, modify, or update custom modules
### Upcoming Features
- **Unitary Module Selection:** For modules with `type: unitary` (instead of `type: module`), you'll be able to select specific items to install
- **Add-on Module Dependencies:** The installer will verify and install dependencies for add-on modules automatically
## Quick Updates
When updates to BMAD Core or core modules (BMM, CIS, etc.) become available, the quick update process will:
1. Apply available updates to core modules
2. Recompile all agents with customizations from the `_config/agents` folder
3. Retain your custom content from a cached location
4. Preserve your existing configurations and customizations
This means you don't need to keep the source module files locally. When updates are available, simply point to the updated module location during the update process.
## Important Considerations
### Module Naming Conflicts
When installing unofficial modules, ensure unique identification to avoid conflicts:
1. **Module Codes:** Each module must have a unique code (e.g., don't use `bmm` for custom modules)
2. **Module Names:** Avoid using names that conflict with existing modules
3. **Multiple Custom Modules:** If creating multiple custom modules, use distinct codes for each
**Examples of conflicts to avoid:**
- Don't create a custom module with code `bmm` (already used by BMad Method)
- Don't name multiple custom modules with the same code like `mca`
### Best Practices
- Use descriptive, unique codes for your modules
- Document any dependencies your custom modules have
- Test custom modules in isolation before sharing
- Consider version numbering for your custom content to track updates

121
docs/modules/bmb-bmad-builder/custom-content.md
View File

@ -1,121 +0,0 @@
# Custom Content
BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agents provides workflows and expertise to plan and build any custom content you can imagine.
This flexibility transforms the platform beyond its current capabilities, enabling:
- Extensions and add-ons for existing modules (BMad Method, Creative Intelligence Suite)
- Completely new modules, workflows, templates, and agents outside software engineering
- Professional services tools
- Entertainment and educational content
- Science and engineering workflows
- Productivity and self-help solutions
- Role-specific augmentation for virtually any profession
## Categories
- [Custom Content](#custom-content)
- [Categories](#categories)
- [Custom Stand Alone Modules](#custom-stand-alone-modules)
- [Custom Add On Modules](#custom-add-on-modules)
- [Custom Global Modules](#custom-global-modules)
- [Custom Agents](#custom-agents)
- [BMad Tiny Agents](#bmad-tiny-agents)
- [Simple and Expert Agents](#simple-and-expert-agents)
- [Custom Workflows](#custom-workflows)
## Custom Stand Alone Modules
Custom modules range from simple collections of related agents, workflows, and tools designed to work independently, to complex, expansive systems like the BMad Method or even larger applications.
Custom modules are [installable](./custom-content-installation.md) using the standard BMAD method and support advanced features:
- Optional user information collection during installation/updates
- Versioning and upgrade paths
- Custom installer functions with IDE-specific post-installation handling (custom hooks, subagents, or vendor-specific tools)
- Ability to bundle specific tools such as MCP, skills, execution libraries, and code
## Custom Add On Modules
Custom Add On Modules contain specific agents, tools, or workflows that expand, modify, or customize another module but cannot exist or install independently. These add-ons provide enhanced functionality while leveraging the base module's existing capabilities.
Examples include:
- Alternative implementation workflows for BMad Method agents
- Framework-specific support for particular use cases
- Game development expansions that add new genre-specific capabilities without reinventing existing functionality
Add on modules can include:
- Custom agents with awareness of the target module
- Access to existing module workflows
- Tool-specific features such as rulesets, hooks, subprocess prompts, subagents, and more
## Custom Global Modules
Similar to Custom Stand Alone Modules, but designed to add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMAD ecosystem.
Examples include:
- The current TTS (Text-to-Speech) functionality for Claude, which will soon be converted to a global module
- The core module, which is always installed and provides all agents with party mode and advanced elicitation capabilities
- Installation and update tools that work with any BMAD method configuration
Upcoming standards will document best practices for building global content that affects installed modules through:
- Custom content injections
- Agent customization auto-injection
- Tooling installers
## Custom Agents
Custom Agents can be designed and built for various use cases, from one-off specialized agents to more generic standalone solutions.
### BMad Tiny Agents
Personal agents designed for highly specific needs that may not be suitable for sharing. For example, a team management agent living in an Obsidian vault that helps with:
- Team coordination and management
- Understanding team details and requirements
- Tracking specific tasks with designated tools
These are simple, standalone files that can be scoped to focus on specific data or paths when integrated into an information vault or repository.
### Simple and Expert Agents
The distinction between simple and expert agents lies in their structure:
**Simple Agent:**
- Single file containing all prompts and configuration
- Self-contained and straightforward
**Expert Agent:**
- Similar to simple agents but includes a sidecar folder
- Sidecar folder contains additional resources: custom prompt files, scripts, templates, and memory files
- When installed, the sidecar folder (`[agentname]-sidecar`) is placed in the user memory location
- has metadata type: expert
The key distinction is the presence of a sidecar folder. As web and consumer agent tools evolve to support common memory mechanisms, storage formats, and MCP, the writable memory files will adapt to support these evolving standards.
Custom agents can be:
- Used within custom modules
- Designed as standalone tools
- Integrated with existing workflows and systems, if this is to be the case, should also include a module: <module name> if a specific module is intended for it to require working with
## Custom Workflows
Workflows are powerful, progressively loading sequence engines capable of performing tasks ranging from simple to complex, including:
- User engagements
- Business processes
- Content generation (code, documentation, or other output formats)
A custom workflow created outside of a larger module can still be distributed and used without associated agents through:
- Slash commands
- Manual command/prompt execution when supported by tools
At its core, a custom workflow is a single or series of prompts designed to achieve a specific outcome.

60
docs/modules/bmb-bmad-builder/index.md
View File

@ -1,60 +0,0 @@
# BMB Module Documentation
Create custom agents, workflows, and modules for BMAD.
## Quick Start
- **[Agent Creation Guide](./agent-creation-guide.md)** - Step-by-step guide to building your first agent
- **[Understanding Agent Types](./understanding-agent-types.md)** - Learn the differences between Simple and Expert agents
## Agent Architecture
Comprehensive guides for each agent type (choose based on use case):
- [Understanding Agent Types](./understanding-agent-types.md) - **START HERE** - Architecture vs capability, "The Same Agent, Three Ways"
- [Simple Agent Architecture](./simple-agent-architecture.md) - Self-contained, optimized, personality-driven
- [Expert Agent Architecture](./expert-agent-architecture.md) - Memory, sidecar files, domain restrictions
- Module Agent Architecture _(TODO)_ - Workflow integration, professional tools
## Agent Design Patterns
- [Agent Menu Patterns](./agent-menu-patterns.md) - Menu handlers, triggers, prompts, organization
- [Agent Compilation](./agent-compilation.md) - What compiler auto-injects (AVOID DUPLICATION)
## Reference Examples
Production-ready examples in [bmb/reference/agents/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents):
**Simple Agents** ([simple-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples))
- [commit-poet.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml) - Commit message artisan with style customization
**Expert Agents** ([expert-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples))
- [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) - Personal journal companion with memory and pattern recognition
**Module Agents** ([module-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/module-examples))
- [security-engineer.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml) - BMM security specialist with threat modeling
- [trend-analyst.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml) - CIS trend intelligence expert
## Installation Guide
For installing standalone simple and expert agents, see:
- [Custom Agent Installation](/docs/modules/bmb-bmad-builder/custom-content-installation.md)
## Key Concepts
### YAML to XML Compilation
Agents are authored in YAML with Handlebars templating. The compiler auto-injects:
1. **Frontmatter** - Name and description from metadata
2. **Activation Block** - Steps, menu handlers, rules (YOU don't write this)
3. **Menu Enhancement** - `*help` and `*exit` commands added automatically
4. **Trigger Prefixing** - Your triggers auto-prefixed with `*`
**Critical:** See [Agent Compilation](./agent-compilation.md) to avoid duplicating auto-injected content.
Source: `tools/cli/lib/agent/compiler.js`

42
docs/modules/bmb-bmad-builder/workflow-vendoring-customization-inheritance.md
View File

@ -1,42 +0,0 @@
# Workflow Vendoring, Customization, and Inheritance (Official Support Consing Soon)
Vendoring and Inheritance of workflows are 2 ways of sharing or reutilizing workflows - but with some key distinctions and use cases.
## Workflow Vendoring
Workflow Vendoring allows an agent to have access to a workflow from another module, without having to install said module. At install time, the module workflow being vendored will be cloned and installed into the module that is receiving the vendored workflow the agent needs.
### How to Vendor
Lets assume you are building a module, and you do not want to recreate a workflow from the BMad Method, such as workflows/4-implementation/dev-story/workflow.md. Instead of copying all the context to your module, and having to maintain it over time as updates are made, you can instead use the exec-vendor menu item in your agent.
From your modules agent definition, you would implement the menu item as follows in the agent:
```yaml
- trigger: develop-story
exec-vendor: "{project-root}/_bmad/<source-module>/workflows/4-production/dev-story/workflow.md"
exec: "{project-root}/_bmad/<my-module>/workflows/dev-story/workflow.md"
description: "Execute Dev Story workflow, implementing tasks and tests, or performing updates to the story"
```
At install time, it will clone the workflow and all of its required assets, and the agent that gets built will have an exec to a path installed in its own module. The content gets added to the folder you specify in exec. While it does not have to exactly match the source path, you will want to ensure you are specifying the workflow.md to be in a new location (in other words in this example, dev-story would not already be the path of another custom module workflow that already exists.)
## Workflow Inheritance (Official Support Coming Post Beta)
Workflow Inheritance is a different concept, that allows you to modify or extend existing workflow.
Party Mode from the core is an example of a workflow that is designed with inheritance in mind - customization for specific party needs. While party mode itself is generic - there might be specific agent collaborations you want to create. Without having to reinvent the whole party mode concept, or copy and paste all of its content - you could inherit from party mode to extend it to be specific.
Some possible examples could be:
- Retrospective
- Sprint Planning
- Collaborative Brainstorming Sessions
## Workflow Customization (Official Support Coming Post Beta)
Similar to Workflow Inheritance, Workflow Customization will soon be allowed for certain workflows that are meant to be user customized - similar in process to how agents are customized now.
This will take the shape of workflows with optional hooks, configurable inputs, and the ability to replace whole at install time.
For example, assume you are using the Create PRD workflow, which is comprised of 11 steps, and you want to always include specifics about your companies domain, technical landscape or something else. While project-context can be helpful with that, you can also through hooks and step overrides, have full replace steps, the key requirement being to ensure your step replace file is an exact file name match of an existing step, follows all conventions, and ends in a similar fashion to either hook back in to call the next existing step, or more custom steps that eventually hook back into the flow.

407
docs/modules/bmgd-bmad-game-dev/agents-guide.md
View File

@ -1,407 +0,0 @@
# BMGD Agents Guide
Complete reference for BMGD's six specialized game development agents.
---
## Agent Overview
BMGD provides six agents, each with distinct expertise:
| Agent | Name | Role | Phase Focus |
| ------------------------ | ---------------- | ----------------------------------------------------------- | ----------- |
| 🎲 **Game Designer** | Samus Shepard | Lead Game Designer + Creative Vision Architect | Phases 1-2 |
| 🏛️ **Game Architect** | Cloud Dragonborn | Principal Game Systems Architect + Technical Director | Phase 3 |
| 🕹️ **Game Developer** | Link Freeman | Senior Game Developer + Technical Implementation Specialist | Phase 4 |
| 🎯 **Game Scrum Master** | Max | Game Development Scrum Master + Sprint Orchestrator | Phase 4 |
| 🧪 **Game QA** | GLaDOS | Game QA Architect + Test Automation Specialist | All Phases |
| 🎮 **Game Solo Dev** | Indie | Elite Indie Game Developer + Quick Flow Specialist | All Phases |
---
## 🎲 Game Designer (Samus Shepard)
### Role
Lead Game Designer + Creative Vision Architect
### Identity
Veteran designer with 15+ years crafting AAA and indie hits. Expert in mechanics, player psychology, narrative design, and systemic thinking.
### Communication Style
Talks like an excited streamer - enthusiastic, asks about player motivations, celebrates breakthroughs with "Let's GOOO!"
### Core Principles
- Design what players want to FEEL, not what they say they want
- Prototype fast - one hour of playtesting beats ten hours of discussion
- Every mechanic must serve the core fantasy
### When to Use
- Brainstorming game ideas
- Creating Game Briefs
- Designing GDDs
- Developing narrative design
### Available Commands
| Command | Description |
| ---------------------- | -------------------------------- |
| `workflow-status` | Check project status |
| `brainstorm-game` | Guided game ideation |
| `create-game-brief` | Create Game Brief |
| `create-gdd` | Create Game Design Document |
| `narrative` | Create Narrative Design Document |
| `quick-prototype` | Rapid prototyping (IDE only) |
| `party-mode` | Multi-agent collaboration |
| `advanced-elicitation` | Deep exploration (web only) |
---
## 🏛️ Game Architect (Cloud Dragonborn)
### Role
Principal Game Systems Architect + Technical Director
### Identity
Master architect with 20+ years shipping 30+ titles. Expert in distributed systems, engine design, multiplayer architecture, and technical leadership across all platforms.
### Communication Style
Speaks like a wise sage from an RPG - calm, measured, uses architectural metaphors about building foundations and load-bearing walls.
### Core Principles
- Architecture is about delaying decisions until you have enough data
- Build for tomorrow without over-engineering today
- Hours of planning save weeks of refactoring hell
- Every system must handle the hot path at 60fps
### When to Use
- Planning technical architecture
- Making engine/framework decisions
- Designing game systems
- Course correction during development
### Available Commands
| Command | Description |
| ---------------------- | ------------------------------------- |
| `workflow-status` | Check project status |
| `create-architecture` | Create Game Architecture |
| `correct-course` | Course correction analysis (IDE only) |
| `party-mode` | Multi-agent collaboration |
| `advanced-elicitation` | Deep exploration (web only) |
---
## 🕹️ Game Developer (Link Freeman)
### Role
Senior Game Developer + Technical Implementation Specialist
### Identity
Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code.
### Communication Style
Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship.
### Core Principles
- 60fps is non-negotiable
- Write code designers can iterate without fear
- Ship early, ship often, iterate on player feedback
- Red-green-refactor: tests first, implementation second
### When to Use
- Implementing stories
- Code reviews
- Performance optimization
- Completing story work
### Available Commands
| Command | Description |
| ---------------------- | ------------------------------- |
| `workflow-status` | Check sprint progress |
| `dev-story` | Implement story tasks |
| `code-review` | Perform code review |
| `quick-dev` | Flexible development (IDE only) |
| `quick-prototype` | Rapid prototyping (IDE only) |
| `party-mode` | Multi-agent collaboration |
| `advanced-elicitation` | Deep exploration (web only) |
---
## 🎯 Game Scrum Master (Max)
### Role
Game Development Scrum Master + Sprint Orchestrator
### Identity
Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories.
### Communication Style
Talks in game terminology - milestones are save points, handoffs are level transitions, blockers are boss fights.
### Core Principles
- Every sprint delivers playable increments
- Clean separation between design and implementation
- Keep the team moving through each phase
- Stories are single source of truth for implementation
### When to Use
- Sprint planning and management
- Creating epic tech specs
- Writing story drafts
- Assembling story context
- Running retrospectives
- Handling course corrections
### Available Commands
| Command | Description |
| ----------------------- | ------------------------------------------- |
| `workflow-status` | Check project status |
| `sprint-planning` | Generate/update sprint status |
| `sprint-status` | View sprint progress, get next action |
| `create-story` | Create story (marks ready-for-dev directly) |
| `validate-create-story` | Validate story draft |
| `epic-retrospective` | Facilitate retrospective |
| `correct-course` | Navigate significant changes |
| `party-mode` | Multi-agent collaboration |
| `advanced-elicitation` | Deep exploration (web only) |
---
## 🧪 Game QA (GLaDOS)
### Role
Game QA Architect + Test Automation Specialist
### Identity
Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile.
### Communication Style
Speaks like a quality guardian - methodical, data-driven, but understands that "feel" matters in games. Uses metrics to back intuition. "Trust, but verify with tests."
### Core Principles
- Test what matters: gameplay feel, performance, progression
- Automated tests catch regressions, humans catch fun problems
- Every shipped bug is a process failure, not a people failure
- Flaky tests are worse than no tests - they erode trust
- Profile before optimize, test before ship
### When to Use
- Setting up test frameworks
- Designing test strategies
- Creating automated tests
- Planning playtesting sessions
- Performance testing
- Reviewing test coverage
### Available Commands
| Command | Description |
| ---------------------- | --------------------------------------------------- |
| `workflow-status` | Check project status |
| `test-framework` | Initialize game test framework (Unity/Unreal/Godot) |
| `test-design` | Create comprehensive game test scenarios |
| `automate` | Generate automated game tests |
| `playtest-plan` | Create structured playtesting plan |
| `performance-test` | Design performance testing strategy |
| `test-review` | Review test quality and coverage |
| `party-mode` | Multi-agent collaboration |
| `advanced-elicitation` | Deep exploration (web only) |
### Knowledge Base
GLaDOS has access to a comprehensive game testing knowledge base (`gametest/qa-index.csv`) including:
**Engine-Specific Testing:**
- Unity Test Framework (Edit Mode, Play Mode)
- Unreal Automation and Gauntlet
- Godot GUT (Godot Unit Test)
**Game-Specific Testing:**
- Playtesting fundamentals
- Balance testing
- Save system testing
- Multiplayer/network testing
- Input testing
- Platform certification (TRC/XR)
- Localization testing
**General QA:**
- QA automation strategies
- Performance testing
- Regression testing
- Smoke testing
- Test prioritization (P0-P3)
---
## 🎮 Game Solo Dev (Indie)
### Role
Elite Indie Game Developer + Quick Flow Specialist
### Identity
Battle-hardened solo game developer who ships complete games from concept to launch. Expert in Unity, Unreal, and Godot, having shipped titles across mobile, PC, and console. Lives and breathes the Quick Flow workflow - prototyping fast, iterating faster, and shipping before the hype dies.
### Communication Style
Direct, confident, and gameplay-focused. Uses dev slang, thinks in game feel and player experience. Every response moves the game closer to ship. "Does it feel good? Ship it."
### Core Principles
- Prototype fast, fail fast, iterate faster
- A playable build beats a perfect design doc
- 60fps is non-negotiable - performance is a feature
- The core loop must be fun before anything else matters
- Ship early, playtest often
### When to Use
- Solo game development
- Rapid prototyping
- Quick iteration without full team workflow
- Indie projects with tight timelines
- When you want to handle everything yourself
### Available Commands
| Command | Description |
| ------------------ | ------------------------------------------------------ |
| `quick-prototype` | Rapid prototype to test if a mechanic is fun |
| `quick-dev` | Implement features end-to-end with game considerations |
| `create-tech-spec` | Create implementation-ready technical spec |
| `code-review` | Review code quality |
| `test-framework` | Set up automated testing |
| `party-mode` | Bring in specialists when needed |
### Quick Flow vs Full BMGD
Use **Game Solo Dev** when:
- You're working alone or in a tiny team
- Speed matters more than process
- You want to skip the full planning phases
- You're prototyping or doing game jams
Use **Full BMGD workflow** when:
- You have a larger team
- The project needs formal documentation
- You're working with stakeholders/publishers
- Long-term maintainability is critical
---
## Agent Selection Guide
### By Phase
| Phase | Primary Agent | Secondary Agent |
| ------------------------------ | ----------------- | ----------------- |
| 1: Preproduction | Game Designer | - |
| 2: Design | Game Designer | - |
| 3: Technical | Game Architect | Game QA |
| 4: Production (Planning) | Game Scrum Master | Game Architect |
| 4: Production (Implementation) | Game Developer | Game Scrum Master |
| Testing (Any Phase) | Game QA | Game Developer |
### By Task
| Task | Best Agent |
| -------------------------------- | ----------------- |
| "I have a game idea" | Game Designer |
| "Help me design my game" | Game Designer |
| "How should I build this?" | Game Architect |
| "What's the technical approach?" | Game Architect |
| "Plan our sprints" | Game Scrum Master |
| "Create implementation stories" | Game Scrum Master |
| "Build this feature" | Game Developer |
| "Review this code" | Game Developer |
| "Set up testing framework" | Game QA |
| "Create test plan" | Game QA |
| "Test performance" | Game QA |
| "Plan a playtest" | Game QA |
| "I'm working solo" | Game Solo Dev |
| "Quick prototype this idea" | Game Solo Dev |
| "Ship this feature fast" | Game Solo Dev |
---
## Multi-Agent Collaboration
### Party Mode
All agents have access to `party-mode`, which brings multiple agents together for complex decisions. Use this when:
- A decision spans multiple domains (design + technical)
- You want diverse perspectives
- You're stuck and need fresh ideas
### Handoffs
Agents naturally hand off to each other:
```
Game Designer → Game Architect → Game Scrum Master → Game Developer
↓ ↓ ↓ ↓
GDD Architecture Sprint/Stories Implementation
↓ ↓
Game QA ←──────────────────────────── Game QA
↓ ↓
Test Strategy Automated Tests
```
Game QA integrates at multiple points:
- After Architecture: Define test strategy
- During Implementation: Create automated tests
- Before Release: Performance and certification testing
---
## Project Context
All agents share the principle:
> "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`"
The `project-context.md` file (if present) serves as the authoritative source for project decisions and constraints.
---
## Next Steps
- **[Quick Start Guide](./quick-start.md)** - Get started with BMGD
- **[Workflows Guide](./workflows-guide.md)** - Detailed workflow reference
- **[Game Types Guide](./game-types-guide.md)** - Game type templates

503
docs/modules/bmgd-bmad-game-dev/game-types-guide.md
View File

@ -1,503 +0,0 @@
# BMGD Game Types Guide
Reference for selecting and using BMGD's 24 supported game type templates.
---
## Overview
When creating a GDD, BMGD offers game type templates that provide genre-specific sections. This ensures your design document covers mechanics and systems relevant to your game's genre.
---
## Supported Game Types
### Action & Combat
#### Action Platformer
**Tags:** action, platformer, combat, movement
Side-scrolling or 3D platforming with combat mechanics. Think Hollow Knight, Celeste with combat, or Mega Man.
**GDD sections added:**
- Movement systems (jumps, dashes, wall mechanics)
- Combat mechanics (melee/ranged, combos)
- Level design patterns
- Boss design
---
#### Shooter
**Tags:** shooter, combat, aiming, fps, tps
Projectile combat with aiming mechanics. Covers FPS, TPS, and arena shooters.
**GDD sections added:**
- Weapon systems
- Aiming and accuracy
- Enemy AI patterns
- Level/arena design
- Multiplayer considerations
---
#### Fighting
**Tags:** fighting, combat, competitive, combos, pvp
1v1 combat with combos and frame data. Traditional fighters and platform fighters.
**GDD sections added:**
- Frame data systems
- Combo mechanics
- Character movesets
- Competitive balance
- Netcode requirements
---
### Strategy & Tactics
#### Strategy
**Tags:** strategy, tactics, resources, planning
Resource management with tactical decisions. RTS, 4X, and grand strategy.
**GDD sections added:**
- Resource systems
- Unit/building design
- AI opponent behavior
- Map/scenario design
- Victory conditions
---
#### Turn-Based Tactics
**Tags:** tactics, turn-based, grid, positioning
Grid-based movement with turn order. XCOM-likes and tactical RPGs.
**GDD sections added:**
- Grid and movement systems
- Turn order mechanics
- Cover and positioning
- Unit progression
- Procedural mission generation
---
#### Tower Defense
**Tags:** tower-defense, waves, placement, strategy
Wave-based defense with tower placement.
**GDD sections added:**
- Tower types and upgrades
- Wave design and pacing
- Economy systems
- Map design patterns
- Meta-progression
---
### RPG & Progression
#### RPG
**Tags:** rpg, stats, inventory, quests, narrative
Character progression with stats, inventory, and quests.
**GDD sections added:**
- Character stats and leveling
- Inventory and equipment
- Quest system design
- Combat system (action/turn-based)
- Skill trees and builds
---
#### Roguelike
**Tags:** roguelike, procedural, permadeath, runs
Procedural generation with permadeath and run-based progression.
**GDD sections added:**
- Procedural generation rules
- Permadeath and persistence
- Run structure and pacing
- Item/ability synergies
- Meta-progression systems
---
#### Metroidvania
**Tags:** metroidvania, exploration, abilities, interconnected
Interconnected world with ability gating.
**GDD sections added:**
- World map connectivity
- Ability gating design
- Backtracking flow
- Secret and collectible placement
- Power-up progression
---
### Narrative & Story
#### Adventure
**Tags:** adventure, narrative, exploration, story
Story-driven exploration and narrative. Point-and-click and narrative adventures.
**GDD sections added:**
- Puzzle design
- Narrative delivery
- Exploration mechanics
- Dialogue systems
- Story branching
---
#### Visual Novel
**Tags:** visual-novel, narrative, choices, story
Narrative choices with branching story.
**GDD sections added:**
- Branching narrative structure
- Choice and consequence
- Character routes
- UI/presentation
- Save/load states
---
#### Text-Based
**Tags:** text, parser, interactive-fiction, mud
Text input/output games. Parser games, choice-based IF, MUDs.
**GDD sections added:**
- Parser or choice systems
- World model
- Narrative structure
- Text presentation
- Save state management
---
### Simulation & Management
#### Simulation
**Tags:** simulation, management, sandbox, systems
Realistic systems with management and building. Includes tycoons and sim games.
**GDD sections added:**
- Core simulation loops
- Economy modeling
- AI agents/citizens
- Building/construction
- Failure states
---
#### Sandbox
**Tags:** sandbox, creative, building, freedom
Creative freedom with building and minimal objectives.
**GDD sections added:**
- Creation tools
- Physics/interaction systems
- Persistence and saving
- Sharing/community features
- Optional objectives
---
### Sports & Racing
#### Racing
**Tags:** racing, vehicles, tracks, speed
Vehicle control with tracks and lap times.
**GDD sections added:**
- Vehicle physics model
- Track design
- AI opponents
- Progression/career mode
- Multiplayer racing
---
#### Sports
**Tags:** sports, teams, realistic, physics
Team-based or individual sports simulation.
**GDD sections added:**
- Sport-specific rules
- Player/team management
- AI opponent behavior
- Season/career modes
- Multiplayer modes
---
### Multiplayer
#### MOBA
**Tags:** moba, multiplayer, pvp, heroes, lanes
Multiplayer team battles with hero selection.
**GDD sections added:**
- Hero/champion design
- Lane and map design
- Team composition
- Matchmaking
- Economy (gold/items)
---
#### Party Game
**Tags:** party, multiplayer, minigames, casual
Local multiplayer with minigames.
**GDD sections added:**
- Minigame design patterns
- Controller support
- Round/game structure
- Scoring systems
- Player count flexibility
---
### Horror & Survival
#### Survival
**Tags:** survival, crafting, resources, danger
Resource gathering with crafting and persistent threats.
**GDD sections added:**
- Resource gathering
- Crafting systems
- Hunger/health/needs
- Threat systems
- Base building
---
#### Horror
**Tags:** horror, atmosphere, tension, fear
Atmosphere and tension with limited resources.
**GDD sections added:**
- Fear mechanics
- Resource scarcity
- Sound design
- Lighting and visibility
- Enemy/threat design
---
### Casual & Progression
#### Puzzle
**Tags:** puzzle, logic, cerebral
Logic-based challenges and problem-solving.
**GDD sections added:**
- Puzzle mechanics
- Difficulty progression
- Hint systems
- Level structure
- Scoring/rating
---
#### Idle/Incremental
**Tags:** idle, incremental, automation, progression
Passive progression with upgrades and automation.
**GDD sections added:**
- Core loop design
- Prestige systems
- Automation unlocks
- Number scaling
- Offline progress
---
#### Card Game
**Tags:** card, deck-building, strategy, turns
Deck building with card mechanics.
**GDD sections added:**
- Card design framework
- Deck building rules
- Mana/resource systems
- Rarity and collection
- Competitive balance
---
### Rhythm
#### Rhythm
**Tags:** rhythm, music, timing, beats
Music synchronization with timing-based gameplay.
**GDD sections added:**
- Note/beat mapping
- Scoring systems
- Difficulty levels
- Music licensing
- Input methods
---
## Hybrid Game Types
Many games combine multiple genres. BMGD supports hybrid selection:
### Examples
**Action RPG** = Action Platformer + RPG
- Movement and combat systems from Action Platformer
- Progression and stats from RPG
**Survival Horror** = Survival + Horror
- Resource and crafting from Survival
- Atmosphere and fear from Horror
**Roguelike Deckbuilder** = Roguelike + Card Game
- Run structure from Roguelike
- Card mechanics from Card Game
### How to Use Hybrids
During GDD creation, select multiple game types when prompted:
```
Agent: What game type best describes your game?
You: It's a roguelike with card game combat
Agent: I'll include sections for both Roguelike and Card Game...
```
---
## Game Type Selection Tips
### 1. Start with Core Fantasy
What does the player primarily DO in your game?
- Run and jump? → Platformer types
- Build and manage? → Simulation types
- Fight enemies? → Combat types
- Make choices? → Narrative types
### 2. Consider Your Loop
What's the core gameplay loop?
- Session-based runs? → Roguelike
- Long-term progression? → RPG
- Quick matches? → Multiplayer types
- Creative expression? → Sandbox
### 3. Don't Over-Combine
2-3 game types maximum. More than that usually means your design isn't focused enough.
### 4. Primary vs Secondary
One type should be primary (most gameplay time). Others add flavor:
- **Primary:** Platformer (core movement and exploration)
- **Secondary:** Metroidvania (ability gating structure)
---
## GDD Section Mapping
When you select a game type, BMGD adds these GDD sections:
| Game Type | Key Sections Added |
| ----------------- | -------------------------------------- |
| Action Platformer | Movement, Combat, Level Design |
| RPG | Stats, Inventory, Quests |
| Roguelike | Procedural Gen, Runs, Meta-Progression |
| Narrative | Story Structure, Dialogue, Branching |
| Multiplayer | Matchmaking, Netcode, Balance |
| Simulation | Systems, Economy, AI |
---
## Next Steps
- **[Quick Start Guide](./quick-start.md)** - Get started with BMGD
- **[Workflows Guide](./workflows-guide.md)** - GDD workflow details
- **[Glossary](./glossary.md)** - Game development terminology

293
docs/modules/bmgd-bmad-game-dev/glossary.md
View File

@ -1,293 +0,0 @@
# BMGD Glossary
Key game development terminology used in BMGD workflows.
---
## A
### Acceptance Criteria
Specific conditions that must be met for a story to be considered complete. Defines "done" for implementation.
### Act Structure
Story organization into major sections (typically 3 acts: Setup, Confrontation, Resolution).
---
## B
### Backlog
List of pending work items (epics, stories) waiting to be scheduled and implemented.
### Boss Design
Design of significant enemy encounters, typically featuring unique mechanics and increased challenge.
---
## C
### Character Arc
The transformation a character undergoes through the story, from initial state to final state.
### Core Fantasy
The emotional experience players seek from your game. What they want to FEEL.
### Core Loop
The fundamental cycle of actions players repeat throughout gameplay. The heart of your game.
---
## D
### Definition of Done (DoD)
Checklist of requirements that must be satisfied before work is considered complete.
### Design Pillar
Core principle that guides all design decisions. Typically 3-5 pillars define a game's identity.
---
## E
### Environmental Storytelling
Narrative communicated through the game world itself—visual details, audio, found documents—rather than explicit dialogue.
### Epic
Large body of work that can be broken down into smaller stories. Represents a major feature or system.
---
## F
### Frame Data
In fighting games, the precise timing information for moves (startup, active, recovery frames).
### Frontmatter
YAML metadata at the beginning of markdown files, used for workflow state tracking.
---
## G
### Game Brief
Document capturing the game's core vision, pillars, target audience, and scope. Foundation for the GDD.
### Game Design Document (GDD)
Comprehensive document detailing all aspects of game design: mechanics, systems, content, and more.
### Game Type
Genre classification that determines which specialized GDD sections are included.
---
## H
### Hot Path
Code that executes frequently (every frame). Must be optimized for performance.
---
## I
### Idle Progression
Game mechanics where progress continues even when the player isn't actively playing.
---
## K
### Kishotenketsu
Four-act story structure from East Asian narrative tradition (Introduction, Development, Twist, Conclusion).
---
## L
### Localization
Adapting game content for different languages and cultures.
---
## M
### MDA Framework
Mechanics → Dynamics → Aesthetics. Framework for analyzing and designing games.
### Meta-Progression
Persistent progression that carries between individual runs or sessions.
### Metroidvania
Genre featuring interconnected world exploration with ability-gated progression.
---
## N
### Narrative Complexity
How central story is to the game experience (Critical, Heavy, Moderate, Light).
### Netcode
Networking code handling multiplayer communication and synchronization.
---
## P
### Permadeath
Game mechanic where character death is permanent, typically requiring a new run.
### Player Agency
The degree to which players can make meaningful choices that affect outcomes.
### Procedural Generation
Algorithmic creation of game content (levels, items, characters) rather than hand-crafted.
---
## R
### Retrospective
Team meeting after completing work to reflect on what went well and what to improve.
### Roguelike
Genre featuring procedural generation, permadeath, and run-based progression.
### Run
A single playthrough in a roguelike or run-based game, from start to death/completion.
---
## S
### Sprint
Time-boxed period of development work, typically 1-2 weeks.
### Sprint Status
Tracking document showing current sprint progress, story states, and blockers.
### Story
Smallest unit of implementable work with clear acceptance criteria. Part of an epic.
### Story Context
Assembled documentation and code context needed to implement a specific story.
### Story Gates
Points where story progression is blocked until certain gameplay conditions are met.
---
## T
### Tech Spec
Technical specification document detailing how a feature will be implemented.
### TDD (Test-Driven Development)
Development approach: write tests first, then implement code to pass them.
---
## U
### UI/UX
User Interface / User Experience. How players interact with and experience the game.
---
## V
### Visual Novel
Genre focused on narrative with static images, dialogue, and player choices.
### Voice Acting
Recorded spoken dialogue for game characters.
---
## W
### Workflow
Structured process for completing a specific type of work (e.g., GDD creation, story implementation).
### Workflow Status
Current state of project workflows, tracking which phases and documents are complete.
### World Building
Creation of the game's setting, including history, culture, geography, and lore.
---
## BMGD-Specific Terms
### A/P/C Menu
Options presented after content generation:
- **A** - Advanced Elicitation (explore deeper)
- **P** - Party Mode (multi-agent discussion)
- **C** - Continue (save and proceed)
### Narrative Complexity Levels
- **Critical** - Story IS the game (visual novels)
- **Heavy** - Deep narrative with gameplay (RPGs)
- **Moderate** - Meaningful story supporting gameplay
- **Light** - Minimal story, gameplay-focused
### Step-File Architecture
BMGD workflow pattern using separate markdown files for each workflow step.
### Workflow-Install Pattern
Phase 4 workflows inherit from BMM base and add BMGD-specific overrides.
---
## Next Steps
- **[Quick Start Guide](./quick-start.md)** - Get started with BMGD
- **[Game Types Guide](./game-types-guide.md)** - Game genre reference

175
docs/modules/bmgd-bmad-game-dev/index.md
View File

@ -1,175 +0,0 @@
# BMGD Documentation
Complete guides for the BMad Game Development Module (BMGD) - AI-powered workflows for game design and development that adapt to your project's needs.
---
## Getting Started
**New to BMGD?** Start here:
- **[Quick Start Guide](./quick-start.md)** - Get started building your first game
- Installation and setup
- Understanding the game development phases
- Running your first workflows
- Agent-based development flow
**Quick Path:** Install BMGD module → Game Brief → GDD → Architecture → Build
---
## Core Concepts
Understanding how BMGD works:
- **[Agents Guide](./agents-guide.md)** - Complete reference for game development agents
- Game Designer, Game Developer, Game Architect, Game Scrum Master, Game QA, Game Solo Dev
- Agent roles and when to use them
- Agent workflows and menus
- **[Workflows Guide](./workflows-guide.md)** - Complete workflow reference
- Phase 1: Preproduction (Brainstorm, Game Brief)
- Phase 2: Design (GDD, Narrative)
- Phase 3: Technical (Architecture)
- Phase 4: Production (Sprint-based development)
- **[Game Types Guide](./game-types-guide.md)** - Selecting and using game type templates
- 24 supported game types
- Genre-specific GDD sections
- Hybrid game type handling
- **[Quick-Flow Guide](./quick-flow-guide.md)** - Fast-track workflows for rapid development
- Quick-Prototype for testing ideas
- Quick-Dev for flexible implementation
- When to use quick-flow vs full BMGD
---
## Quick References
Essential reference materials:
- **[Glossary](./glossary.md)** - Key game development terminology
---
## Choose Your Path
### I need to...
**Start a new game project**
→ Start with [Quick Start Guide](./quick-start.md)
→ Run `brainstorm-game` for ideation
→ Create a Game Brief with `create-brief`
**Design my game**
→ Create a GDD with `create-gdd`
→ If story-heavy, add Narrative Design with `create-narrative`
**Plan the technical architecture**
→ Run `create-architecture` with the Game Architect
**Build my game**
→ Use Phase 4 production workflows
→ Follow the sprint-based development cycle
**Quickly test an idea or implement a feature**
→ Use [Quick-Flow](./quick-flow-guide.md) for rapid prototyping and development
→ `quick-prototype` to test mechanics, `quick-dev` to implement
**Set up testing and QA**
→ Use Game QA agent for test framework setup
→ Run `test-framework` to initialize testing for Unity/Unreal/Godot
→ Use `test-design` to create test scenarios
→ Plan playtests with `playtest-plan`
**Understand game type templates**
→ See [Game Types Guide](./game-types-guide.md)
---
## Game Development Phases
BMGD follows four phases aligned with game development:
![BMGD Workflow Overview](./workflow-overview.jpg)
### Phase 1: Preproduction
- **Brainstorm Game** - Ideation with game-specific techniques
- **Game Brief** - Capture vision, market, and fundamentals
### Phase 2: Design
- **GDD (Game Design Document)** - Comprehensive game design
- **Narrative Design** - Story, characters, world (for story-driven games)
### Phase 3: Technical
- **Game Architecture** - Engine, systems, patterns, structure
### Phase 4: Production
- **Sprint Planning** - Epic and story management
- **Story Development** - Implementation workflow
- **Code Review** - Quality assurance
- **Testing** - Automated tests, playtesting, performance
- **Retrospective** - Continuous improvement
---
## BMGD vs BMM
BMGD extends BMM with game-specific capabilities:
| Aspect | BMM | BMGD |
| -------------- | ------------------------------------- | ------------------------------------------------------------------------ |
| **Focus** | General software | Game development |
| **Agents** | PM, Architect, Dev, SM, TEA, Solo Dev | Game Designer, Game Dev, Game Architect, Game SM, Game QA, Game Solo Dev |
| **Planning** | PRD, Tech Spec | Game Brief, GDD |
| **Types** | N/A | 24 game type templates |
| **Narrative** | N/A | Full narrative workflow |
| **Testing** | Web-focused testarch | Engine-specific (Unity, Unreal, Godot) |
| **Production** | Inherited from BMM | BMM workflows with game overrides |
BMGD production workflows inherit from BMM and add game-specific checklists and templates.
---
## Documentation Map
```
BMGD Documentation
├── README.md (this file)
├── quick-start.md # Getting started
├── agents-guide.md # Agent reference
├── workflows-guide.md # Workflow reference
├── quick-flow-guide.md # Rapid prototyping and development
├── game-types-guide.md # Game type templates
├── glossary.md # Terminology
```
---
## External Resources
### Community and Support
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help from the community
- **[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
### Related Documentation
- **[BMM Documentation](../../bmm/docs/index.md)** - Core BMad Method documentation
## Tips for Using This Documentation
1. **Start with Quick Start** if you're new to BMGD
2. **Check Game Types Guide** when creating your GDD
3. **Reference Glossary** for game development terminology
4. **Use Troubleshooting** when you encounter issues
---
**Ready to make games?** → [Start with the Quick Start Guide](./quick-start.md)

288
docs/modules/bmgd-bmad-game-dev/quick-flow-guide.md
View File

@ -1,288 +0,0 @@
# BMGD Quick-Flow Guide
Fast-track workflows for rapid game prototyping and flexible development.
---
## Game Solo Dev Agent
For dedicated quick-flow development, use the **Game Solo Dev** agent (Indie). This agent is optimized for solo developers and small teams who want to skip the full planning phases and ship fast.
**Switch to Game Solo Dev:** Type `@game-solo-dev` or select the agent from your IDE.
The Game Solo Dev agent includes:
- `quick-prototype` - Rapid mechanic testing
- `quick-dev` - Flexible feature implementation
- `create-tech-spec` - Create implementation-ready specs
- `code-review` - Quality checks
- `test-framework` - Automated testing setup
---
## Overview
Quick-flow workflows skip the full BMGD planning phases when you need to move fast. Use them for:
- Testing a game mechanic idea
- Implementing a small feature
- Rapid prototyping before committing to design
- Bug fixes and tweaks
```
Full BMGD Flow:
Brief → GDD → Architecture → Sprint Planning → Stories → Implementation
Quick-Flow:
Idea → Quick-Prototype → Quick-Dev → Done
```
---
## Quick-Prototype
**Command:** `quick-prototype`
**Agent:** Game Designer, Game Developer
**Purpose:** Rapidly test gameplay ideas with minimal setup
### When to Use
- You have a mechanic idea and want to test the "feel"
- You're not sure if something will be fun
- You want to experiment before committing to design
- You need a proof of concept
### Workflow Steps
1. **Define Scope** - What are you prototyping? (mechanic, feature, system)
2. **Set Success Criteria** - How will you know if it works?
3. **Rapid Implementation** - Build the minimum to test the idea
4. **Playtest and Evaluate** - Does it feel right?
### Prototype Principles
- **Minimum Viable Prototype** - Only what's needed to test the idea
- **Hardcode First** - Magic numbers are fine, extract later
- **Skip Edge Cases** - Happy path only for now
- **Placeholder Everything** - Cubes, debug text, temp sounds
- **Comment Intent** - Mark what's temporary vs keeper code
### Example Session
```
You: quick-prototype
Agent: What are you prototyping?
You: I want to test a grappling hook mechanic. Player should be
able to aim at surfaces and pull themselves toward the hook point.
Agent: What makes this prototype successful?
You: 1. Aiming feels responsive and intuitive
2. The pull movement feels satisfying, not floaty
3. Player can chain hooks without awkward pauses
Agent: [Implements minimal grappling hook]
Agent: Prototype complete! Playtest results:
- Aiming: Works, consider adding aim assist
- Movement: Pull is smooth, might need speed curve
- Chaining: Currently has 0.2s delay, feels sluggish
Next: [d] Develop further | [i] Iterate | [a] Archive
```
### After Prototyping
- **Develop** (`d`) - Use `quick-dev` to build production code
- **Iterate** (`i`) - Adjust and re-test the prototype
- **Archive** (`a`) - Keep as reference, move on to other ideas
---
## Quick-Dev
**Command:** `quick-dev`
**Agent:** Game Developer
**Purpose:** Flexible development with game-specific considerations
### When to Use
- Implementing a feature from a tech-spec
- Building on a successful prototype
- Making changes that don't need full story workflow
- Quick fixes and improvements
### Workflow Modes
**Mode A: Tech-Spec Driven**
```
You: quick-dev tech-spec-combat.md
Agent: [Loads spec, extracts tasks, implements]
```
**Mode B: Direct Instructions**
```
You: quick-dev implement double-jump for the player
Agent: [Evaluates complexity, offers planning options]
```
**Mode C: From Prototype**
```
You: quick-dev from the grappling hook prototype
Agent: [Loads prototype, productionizes code]
```
### Game-Specific Checks
Quick-dev includes automatic consideration of:
- **Performance** - No allocations in hot paths, object pooling
- **Feel** - Input responsiveness, visual/audio feedback
- **Integration** - Save/load, multiplayer sync, platform testing
### Example Session
```
You: quick-dev implement enemy patrol behavior
Agent: This looks like a focused feature. Options:
[t] Plan first - Create tech-spec (recommended)
[r] Prototype first - Test the idea
[e] Execute directly
You: e
Agent: Any additional guidance? (patterns, files, constraints)
You: Use the existing AIController base class. Enemies should
patrol between waypoints and return if player leaves range.
Agent: [Implements patrol behavior]
Agent: Implementation Complete!
Files Modified: EnemyAI.cs, PatrolBehavior.cs
Tests: Unit tests added for patrol state machine
Performance: No per-frame allocations
Recommended: Playtest the changes
```
### Complexity Routing
Quick-dev automatically detects complex requests and offers alternatives:
| Signals | Recommendation |
| -------------------------------------- | ---------------------- |
| Single mechanic, bug fix, tweak | Execute directly |
| Multiple systems, performance-critical | Plan first (tech-spec) |
| Platform/system level work | Use full BMGD workflow |
---
## Choosing Between Quick-Flows
| Scenario | Use |
| ----------------------- | ------------------------------- |
| "Will this be fun?" | `quick-prototype` |
| "How should this feel?" | `quick-prototype` |
| "Build this feature" | `quick-dev` |
| "Fix this bug" | `quick-dev` |
| "Test then build" | `quick-prototype` → `quick-dev` |
---
## Quick-Flow vs Full BMGD
### Use Quick-Flow When
- The scope is small and well-understood
- You're experimenting or prototyping
- You have a clear tech-spec already
- The work doesn't affect core game systems significantly
### Use Full BMGD When
- Building a major feature or system
- The scope is unclear or large
- Multiple team members need alignment
- The work affects game pillars or core loop
- You need documentation for future reference
---
## Checklists
### Quick-Prototype Checklist
**Before:**
- [ ] Prototype scope defined
- [ ] Success criteria established (2-3 items)
**During:**
- [ ] Minimum viable code written
- [ ] Placeholder assets used
- [ ] Core functionality testable
**After:**
- [ ] Each criterion evaluated
- [ ] Decision made (develop/iterate/archive)
### Quick-Dev Checklist
**Before:**
- [ ] Context loaded (spec, prototype, or guidance)
- [ ] Files to modify identified
- [ ] Patterns understood
**During:**
- [ ] All tasks completed
- [ ] No allocations in hot paths
- [ ] Frame rate maintained
**After:**
- [ ] Game runs without errors
- [ ] Feature works as specified
- [ ] Manual playtest completed
---
## Tips for Success
### 1. Timebox Prototypes
Set a limit (e.g., 2 hours) for prototyping. If it's not working by then, step back and reconsider.
### 2. Embrace Programmer Art
Prototypes don't need to look good. Focus on feel, not visuals.
### 3. Test on Target Hardware
What feels right on your dev machine might not feel right on target platform.
### 4. Document Learnings
Even failed prototypes teach something. Note what you learned.
### 5. Know When to Graduate
If quick-dev keeps expanding scope, stop and create proper stories.
---
## Next Steps
- **[Workflows Guide](./workflows-guide.md)** - Full workflow reference
- **[Agents Guide](./agents-guide.md)** - Agent capabilities
- **[Quick Start Guide](./quick-start.md)** - Getting started with BMGD

250
docs/modules/bmgd-bmad-game-dev/quick-start.md
View File

@ -1,250 +0,0 @@
# BMGD Quick Start Guide
Get started building games with the BMad Game Development Module.
---
## Prerequisites
Before starting with BMGD, ensure you have:
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
---
## Installation
BMGD is a custom module that extends BMM. Install it using the BMAD installer:
```bash
# During installation, select BMGD when prompted for custom modules
npx bmad-cli install
```
Or add to an existing installation:
```bash
npx bmad-cli install --add-module bmgd
```
---
## Understanding the Phases
BMGD follows four game development phases:
![BMGD Workflow Overview](./workflow-overview.jpg)
### 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)
If you have a vague idea and want help developing it:
```
You: brainstorm-game
Agent: [Guides you through game-specific ideation techniques]
```
### Step 2: Create Your Game Brief
Capture your game's core vision:
```
You: create-game-brief
Agent: [Walks you through game concept, pillars, market, and fundamentals]
```
**Output:** `{output_folder}/game-brief.md`
### Step 3: Create Your GDD
Detail your game's design:
```
You: create-gdd
Agent: [Guides you through mechanics, systems, and game-type-specific sections]
```
**Output:** `{output_folder}/gdd.md` (or sharded into `{output_folder}/gdd/`)
### Step 4: Add Narrative Design (If Story-Driven)
For games with significant story:
```
You: narrative
Agent: [Facilitates story, characters, world, and dialogue design]
```
**Output:** `{output_folder}/narrative-design.md`
### Step 5: Create Architecture
Plan your technical implementation:
```
You: create-architecture
Agent: [Guides engine selection, system design, and technical decisions]
```
**Output:** `{output_folder}/game-architecture.md`
### Step 6: Start Building
Begin sprint-based development:
```
You: sprint-planning
Agent: [Sets up sprint tracking and epic management]
```
---
## Choosing Your Agent
BMGD provides six specialized agents:
| 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 |
### Typical Flow
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
---
## 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](./agents-guide.md)** - Learn about each agent's capabilities
- **[Workflows Guide](./workflows-guide.md)** - Detailed workflow reference
- **[Quick-Flow Guide](./quick-flow-guide.md)** - Rapid prototyping and development
- **[Game Types Guide](./game-types-guide.md)** - Understand game type templates
- **[Glossary](./glossary.md)** - Game development terminology
---
**Ready to start?** Chat with the **Game Designer** agent and say `brainstorm-game` or `create-game-brief`!

259
docs/modules/bmgd-bmad-game-dev/troubleshooting.md
View File

@ -1,259 +0,0 @@
# BMGD Troubleshooting
Common issues and solutions when using BMGD workflows.
---
## Installation Issues
### BMGD module not appearing
**Symptom:** BMGD agents and workflows are not available after installation.
**Solutions:**
1. Verify BMGD was selected during installation
2. Check `_bmad/bmgd/` folder exists in your project
3. Re-run installer with `--add-module bmgd`
---
### Config file missing
**Symptom:** Workflows fail with "config not found" errors.
**Solution:**
Check for `_bmad/bmgd/config.yaml` in your project. If missing, create it:
```yaml
# BMGD Configuration
output_folder: '{project-root}/docs/game-design'
user_name: 'Your Name'
communication_language: 'English'
document_output_language: 'English'
game_dev_experience: 'intermediate'
```
---
## Workflow Issues
### "GDD not found" in Narrative workflow
**Symptom:** Narrative workflow can't find the GDD.
**Solutions:**
1. Ensure GDD exists in `{output_folder}`
2. Check GDD filename contains "gdd" (e.g., `game-gdd.md`, `my-gdd.md`)
3. If using sharded GDD, verify `{output_folder}/gdd/index.md` exists
---
### Workflow state not persisting
**Symptom:** Returning to a workflow starts from the beginning.
**Solutions:**
1. Check the output document's frontmatter for `stepsCompleted` array
2. Ensure document was saved before ending session
3. Use "Continue existing" option when re-entering workflow
---
### Wrong game type sections in GDD
**Symptom:** GDD includes irrelevant sections for your game type.
**Solutions:**
1. Review game type selection at Step 7 of GDD workflow
2. You can select multiple types for hybrid games
3. Irrelevant sections can be marked N/A or removed
---
## Agent Issues
### Agent not recognizing commands
**Symptom:** Typing a command like `create-gdd` doesn't trigger the workflow.
**Solutions:**
1. Ensure you're chatting with the correct agent (Game Designer for GDD)
2. Check exact command spelling (case-sensitive)
3. Try `workflow-status` to verify agent is loaded correctly
---
### Agent using wrong persona
**Symptom:** Agent responses don't match expected personality.
**Solutions:**
1. Verify correct agent file is loaded
2. Check `_bmad/bmgd/agents/` for agent definitions
3. Start a fresh chat session with the correct agent
---
## Document Issues
### Document too large for context
**Symptom:** AI can't process the entire GDD or narrative document.
**Solutions:**
1. Use sharded document structure (index.md + section files)
2. Request specific sections rather than full document
3. GDD workflow supports automatic sharding for large documents
---
### Template placeholders not replaced
**Symptom:** Output contains `{{placeholder}}` text.
**Solutions:**
1. Workflow may have been interrupted before completion
2. Re-run the specific step that generates that section
3. Manually edit the document to fill in missing values
---
### Frontmatter parsing errors
**Symptom:** YAML errors when loading documents.
**Solutions:**
1. Validate YAML syntax (proper indentation, quotes around special characters)
2. Check for tabs vs spaces (YAML requires spaces)
3. Ensure frontmatter is bounded by `---` markers
---
## Phase 4 (Production) Issues
### Sprint status not updating
**Symptom:** Story status changes don't reflect in sprint-status.yaml.
**Solutions:**
1. Run `sprint-planning` to refresh status
2. Check file permissions on sprint-status.yaml
3. Verify workflow-install files exist in `_bmad/bmgd/workflows/4-production/`
---
### Story context missing code references
**Symptom:** Generated story context doesn't include relevant code.
**Solutions:**
1. Ensure project-context.md exists and is current
2. Check that architecture document references correct file paths
3. Story may need more specific file references in acceptance criteria
---
### Code review not finding issues
**Symptom:** Code review passes but bugs exist.
**Solutions:**
1. Code review is AI-assisted, not comprehensive testing
2. Always run actual tests before marking story done
3. Consider manual review for critical code paths
---
## Performance Issues
### Workflows running slowly
**Symptom:** Long wait times between workflow steps.
**Solutions:**
1. Use IDE-based workflows (faster than web)
2. Keep documents concise (avoid unnecessary detail)
3. Use sharded documents for large projects
---
### Context limit reached mid-workflow
**Symptom:** Workflow stops or loses context partway through.
**Solutions:**
1. Save progress frequently (workflows auto-save on Continue)
2. Break complex sections into multiple sessions
3. Use step-file architecture (workflows resume from last step)
---
## Common Error Messages
### "Input file not found"
**Cause:** Workflow requires a document that doesn't exist.
**Fix:** Complete prerequisite workflow first (e.g., Game Brief before GDD).
---
### "Invalid game type"
**Cause:** Selected game type not in supported list.
**Fix:** Check `game-types.csv` for valid type IDs.
---
### "Validation failed"
**Cause:** Document doesn't meet checklist requirements.
**Fix:** Review the validation output and address flagged items.
---
## Getting Help
### Community Support
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Real-time help from the community
- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features
### Self-Help
1. Check `workflow-status` to understand current state
2. Review workflow markdown files for expected behavior
3. Look at completed example documents in the module
### Reporting Issues
When reporting issues, include:
1. Which workflow and step
2. Error message (if any)
3. Relevant document frontmatter
4. Steps to reproduce
---
## Next Steps
- **[Quick Start Guide](./quick-start.md)** - Getting started
- **[Workflows Guide](./workflows-guide.md)** - Workflow reference
- **[Glossary](./glossary.md)** - Terminology

BIN
docs/modules/bmgd-bmad-game-dev/workflow-overview.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 200 KiB

463
docs/modules/bmgd-bmad-game-dev/workflows-guide.md
View File

@ -1,463 +0,0 @@
# BMGD Workflows Guide
Complete reference for all BMGD workflows organized by development phase.
---
## Workflow Overview
BMGD workflows are organized into four phases:
![BMGD Workflow Overview](../../../../docs/modules/bmgd-bmad-game-dev/workflow-overview.jpg)
---
## Phase 1: Preproduction
### Brainstorm Game
**Command:** `brainstorm-game`
**Agent:** Game Designer
**Input:** None required
**Output:** Ideas and concepts (optionally saved)
**Description:**
Guided ideation session using game-specific brainstorming techniques:
- **MDA Framework** - Mechanics → Dynamics → Aesthetics analysis
- **Core Loop Workshop** - Define the fundamental gameplay loop
- **Player Fantasy Mining** - Explore what players want to feel
- **Genre Mashup** - Combine genres for unique concepts
**Steps:**
1. Initialize brainstorm session
2. Load game-specific techniques
3. Execute ideation with selected techniques
4. Summarize and (optionally) hand off to Game Brief
---
### Game Brief
**Command:** `create-game-brief`
**Agent:** Game Designer
**Input:** Ideas from brainstorming (optional)
**Output:** `{output_folder}/game-brief.md`
**Description:**
Captures your game's core vision and fundamentals. This is the foundation for all subsequent design work.
**Sections covered:**
- Game concept and vision
- Design pillars (3-5 core principles)
- Target audience and market
- Platform considerations
- Core gameplay loop
- Initial scope definition
---
## Phase 2: Design
### GDD (Game Design Document)
**Command:** `create-gdd`
**Agent:** Game Designer
**Input:** Game Brief
**Output:** `{output_folder}/gdd.md` (or sharded into `{output_folder}/gdd/`)
**Description:**
Comprehensive game design document with genre-specific sections based on 24 supported game types.
**Core sections:**
1. Executive Summary
2. Gameplay Systems
3. Core Mechanics
4. Progression Systems
5. UI/UX Design
6. Audio Design
7. Art Direction
8. Technical Requirements
9. Game-Type-Specific Sections
10. Epic Generation (for sprint planning)
**Features:**
- Game type selection with specialized sections
- Hybrid game type support
- Automatic epic generation
- Scale-adaptive complexity
---
### Narrative Design
**Command:** `narrative`
**Agent:** Game Designer
**Input:** GDD (required), Game Brief (optional)
**Output:** `{output_folder}/narrative-design.md`
**Description:**
For story-driven games. Creates comprehensive narrative documentation.
**Sections covered:**
1. Story Foundation (premise, themes, tone)
2. Story Structure (acts, beats, pacing)
3. Characters (protagonists, antagonists, supporting, arcs)
4. World Building (setting, history, factions, locations)
5. Dialogue Framework (style, branching)
6. Environmental Storytelling
7. Narrative Delivery Methods
8. Gameplay-Narrative Integration
9. Production Planning (scope, localization, voice acting)
10. Appendices (relationship map, timeline)
**Narrative Complexity Levels:**
- **Critical** - Story IS the game (visual novels, adventure games)
- **Heavy** - Deep narrative with gameplay (RPGs, story-driven action)
- **Moderate** - Meaningful story supporting gameplay
- **Light** - Minimal story, gameplay-focused
---
## Phase 3: Technical
### Game Architecture
**Command:** `create-architecture`
**Agent:** Game Architect
**Input:** GDD, Narrative Design (optional)
**Output:** `{output_folder}/game-architecture.md`
**Description:**
Technical architecture document covering engine selection, system design, and implementation approach.
**Sections covered:**
1. Executive Summary
2. Engine/Framework Selection
3. Core Systems Architecture
4. Data Architecture
5. Performance Requirements
6. Platform-Specific Considerations
7. Development Environment
8. Testing Strategy
9. Build and Deployment
10. Technical Risks and Mitigations
---
## Phase 4: Production
Production workflows inherit from BMM and add game-specific overrides.
### Sprint Planning
**Command:** `sprint-planning`
**Agent:** Game Scrum Master
**Input:** GDD with epics
**Output:** `{implementation_artifacts}/sprint-status.yaml`
**Description:**
Generates or updates sprint tracking from epic files. Sets up the sprint backlog and tracking.
---
### Sprint Status
**Command:** `sprint-status`
**Agent:** Game Scrum Master
**Input:** `sprint-status.yaml`
**Output:** Sprint summary, risks, next action recommendation
**Description:**
Summarizes sprint progress, surfaces risks (stale file, orphaned stories, stories in review), and recommends the next workflow to run. Supports three modes:
- **interactive** (default): Displays summary with menu options
- **validate**: Checks sprint-status.yaml structure
- **data**: Returns raw data for other workflows
---
### Create Story
**Command:** `create-story`
**Agent:** Game Scrum Master
**Input:** GDD, Architecture, Epic context
**Output:** `{output_folder}/epics/{epic-name}/stories/{story-name}.md`
**Description:**
Creates implementable story drafts with acceptance criteria, tasks, and technical notes. Stories are marked ready-for-dev directly when created.
**Validation:** `validate-create-story`
---
### Dev Story
**Command:** `dev-story`
**Agent:** Game Developer
**Input:** Story (ready for dev)
**Output:** Implemented code
**Description:**
Implements story tasks following acceptance criteria. Uses TDD approach (red-green-refactor). Updates sprint-status.yaml automatically on completion.
---
### Code Review
**Command:** `code-review`
**Agent:** Game Developer
**Input:** Story (ready for review)
**Output:** Review feedback, approved/needs changes
**Description:**
Thorough QA code review with game-specific considerations (performance, 60fps, etc.).
---
### Retrospective
**Command:** `epic-retrospective`
**Agent:** Game Scrum Master
**Input:** Completed epic
**Output:** Retrospective document
**Description:**
Facilitates team retrospective after epic completion. Captures learnings and improvements.
---
### Correct Course
**Command:** `correct-course`
**Agent:** Game Scrum Master or Game Architect
**Input:** Current project state
**Output:** Correction plan
**Description:**
Navigates significant changes when implementation is off-track. Analyzes impact and recommends adjustments.
---
## Workflow Status
**Command:** `workflow-status`
**Agent:** All agents
**Output:** Project status summary
**Description:**
Checks current project status across all phases. Shows completed documents, current phase, and next steps.
---
## Quick-Flow Workflows
Fast-track workflows that skip full planning phases. See **[Quick-Flow Guide](../../../../docs/modules/bmgd-bmad-game-dev/quick-flow-guide.md)** for detailed usage.
### Quick-Prototype
**Command:** `quick-prototype`
**Agent:** Game Designer, Game Developer
**Input:** Idea or concept to test
**Output:** Working prototype, playtest results
**Description:**
Rapid prototyping workflow for testing game mechanics and ideas quickly. Focuses on "feel" over polish.
**Use when:**
- Testing if a mechanic is fun
- Proving a concept before committing to design
- Experimenting with gameplay ideas
---
### Quick-Dev
**Command:** `quick-dev`
**Agent:** Game Developer
**Input:** Tech-spec, prototype, or direct instructions
**Output:** Implemented feature
**Description:**
Flexible development workflow with game-specific considerations (performance, feel, integration).
**Use when:**
- Implementing features from tech-specs
- Building on successful prototypes
- Making changes that don't need full story workflow
---
## Quality Assurance Workflows
Game testing workflows for automated testing, playtesting, and quality assurance across Unity, Unreal, and Godot.
### Test Framework
**Command:** `test-framework`
**Agent:** Game QA
**Input:** Game project
**Output:** Configured test framework
**Description:**
Initialize a production-ready test framework for your game engine:
- **Unity**: Unity Test Framework with Edit Mode and Play Mode tests
- **Unreal**: Unreal Automation system with functional tests
- **Godot**: GUT (Godot Unit Test) framework
**Creates:**
- Test directory structure
- Framework configuration
- Sample unit and integration tests
- Test documentation
---
### Test Design
**Command:** `test-design`
**Agent:** Game QA
**Input:** GDD, Architecture
**Output:** `{output_folder}/game-test-design.md`
**Description:**
Creates comprehensive test scenarios covering:
- Core gameplay mechanics
- Progression and save systems
- Multiplayer (if applicable)
- Platform certification requirements
Uses GIVEN/WHEN/THEN format with priority levels (P0-P3).
---
### Automate
**Command:** `automate`
**Agent:** Game QA
**Input:** Test design, game code
**Output:** Automated test files
**Description:**
Generates engine-appropriate automated tests:
- Unit tests for pure logic
- Integration tests for system interactions
- Smoke tests for critical path validation
---
### Playtest Plan
**Command:** `playtest-plan`
**Agent:** Game QA
**Input:** Build, test objectives
**Output:** `{output_folder}/playtest-plan.md`
**Description:**
Creates structured playtesting sessions:
- Session structure (pre/during/post)
- Observation guides
- Interview questions
- Analysis templates
**Playtest Types:**
- Internal (team validation)
- External (unbiased feedback)
- Focused (specific feature testing)
---
### Performance Test
**Command:** `performance-test`
**Agent:** Game QA
**Input:** Platform targets
**Output:** `{output_folder}/performance-test-plan.md`
**Description:**
Designs performance testing strategy:
- Frame rate targets per platform
- Memory budgets
- Loading time requirements
- Benchmark scenarios
- Profiling methodology
---
### Test Review
**Command:** `test-review`
**Agent:** Game QA
**Input:** Existing test suite
**Output:** `{output_folder}/test-review-report.md`
**Description:**
Reviews test quality and coverage:
- Test suite metrics
- Quality assessment
- Coverage gaps
- Recommendations
---
## Utility Workflows
### Party Mode
**Command:** `party-mode`
**Agent:** All agents
**Description:**
Brings multiple agents together for collaborative discussion on complex decisions.
---
### Advanced Elicitation
**Command:** `advanced-elicitation`
**Agent:** All agents (web only)
**Description:**
Deep exploration techniques to challenge assumptions and surface hidden requirements.
---
## Standalone BMGD Workflows
BMGD Phase 4 workflows are standalone implementations tailored for game development:
```yaml
workflow: '{project-root}/_bmad/bmgd/workflows/4-production/dev-story/workflow.yaml'
```
This means:
1. BMGD workflows are self-contained with game-specific logic
2. Game-focused templates, checklists, and instructions
3. No dependency on BMM workflow files
---
## Next Steps
- **[Quick Start Guide](../../../../docs/modules/bmgd-bmad-game-dev/quick-start.md)** - Get started with BMGD
- **[Quick-Flow Guide](../../../../docs/modules/bmgd-bmad-game-dev/quick-flow-guide.md)** - Rapid prototyping and development
- **[Agents Guide](../../../../docs/modules/bmgd-bmad-game-dev/agents-guide.md)** - Agent reference
- **[Game Types Guide](../../../../docs/modules/bmgd-bmad-game-dev/game-types-guide.md)** - Game type templates

144
docs/modules/bmm-bmad-method/agents-guide.md
View File

@ -1,144 +0,0 @@
# BMM Agents Reference
Quick reference of what each agent can do based on their available commands.
---
## Analyst (Mary) | `/bmad:bmm:agents:analyst`
Business analysis and research.
**Capabilities:**
- `*workflow-status` - Get workflow status or initialize tracking
- `*brainstorm-project` - Guided brainstorming session
- `*research` - Market, domain, competitive, or technical research
- `*product-brief` - Create a product brief (input for PRD)
- `*document-project` - Document existing brownfield projects
- Party mode and advanced elicitation
---
## PM (John) | `/bmad:bmm:agents:pm`
Product requirements and planning.
**Capabilities:**
- `*workflow-status` - Get workflow status or initialize tracking
- `*create-prd` - Create Product Requirements Document
- `*create-epics-and-stories` - Break PRD into epics and user stories (after Architecture)
- `*implementation-readiness` - Validate PRD, UX, Architecture, Epics alignment
- `*correct-course` - Course correction during implementation
- Party mode and advanced elicitation
---
## Architect (Winston) | `/bmad:bmm:agents:architect`
System architecture and technical design.
**Capabilities:**
- `*workflow-status` - Get workflow status or initialize tracking
- `*create-architecture` - Create architecture document to guide development
- `*implementation-readiness` - Validate PRD, UX, Architecture, Epics alignment
- `*create-excalidraw-diagram` - System architecture or technical diagrams
- `*create-excalidraw-dataflow` - Data flow diagrams
- Party mode and advanced elicitation
---
## SM (Bob) | `/bmad:bmm:agents:sm`
Sprint planning and story preparation.
**Capabilities:**
- `*sprint-planning` - Generate sprint-status.yaml from epic files
- `*create-story` - Create story from epic (prep for development)
- `*validate-create-story` - Validate story quality
- `*epic-retrospective` - Team retrospective after epic completion
- `*correct-course` - Course correction during implementation
- Party mode and advanced elicitation
---
## DEV (Amelia) | `/bmad:bmm:agents:dev`
Story implementation and code review.
**Capabilities:**
- `*dev-story` - Execute story workflow (implementation with tests)
- `*code-review` - Thorough code review
---
## Quick Flow Solo Dev (Barry) | `/bmad:bmm:agents:quick-flow-solo-dev`
Fast solo development without handoffs.
**Capabilities:**
- `*create-tech-spec` - Architect technical spec with implementation-ready stories
- `*quick-dev` - Implement tech spec end-to-end solo
- `*code-review` - Review and improve code
---
## TEA (Murat) | `/bmad:bmm:agents:tea`
Test architecture and quality strategy.
**Capabilities:**
- `*framework` - Initialize production-ready test framework
- `*atdd` - Generate E2E tests first (before implementation)
- `*automate` - Comprehensive test automation
- `*test-design` - Create comprehensive test scenarios
- `*trace` - Map requirements to tests, quality gate decision
- `*nfr-assess` - Validate non-functional requirements
- `*ci` - Scaffold CI/CD quality pipeline
- `*test-review` - Review test quality
---
## UX Designer (Sally) | `/bmad:bmm:agents:ux-designer`
User experience and UI design.
**Capabilities:**
- `*create-ux-design` - Generate UX design and UI plan from PRD
- `*validate-design` - Validate UX specification and design artifacts
- `*create-excalidraw-wireframe` - Create website or app wireframe
---
## Technical Writer (Paige) | `/bmad:bmm:agents:tech-writer`
Technical documentation and diagrams.
**Capabilities:**
- `*document-project` - Comprehensive project documentation (brownfield analysis)
- `*generate-mermaid` - Generate Mermaid diagrams (architecture, sequence, flow, ER, class, state)
- `*create-excalidraw-flowchart` - Process and logic flow visualizations
- `*create-excalidraw-diagram` - System architecture or technical diagrams
- `*create-excalidraw-dataflow` - Data flow visualizations
- `*validate-doc` - Review documentation against standards
- `*improve-readme` - Review and improve README files
- `*explain-concept` - Create clear technical explanations with examples
- `*standards-guide` - Show BMAD documentation standards reference
---
## Universal Commands
Available to all agents:
- `*menu` - Redisplay menu options
- `*dismiss` - Dismiss agent
Party mode is available to most agents for multi-agent collaboration.

Some files were not shown because too many files have changed in this diff Show More