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 upstream/main: sync with 6.0.0-alpha.22 release

This commit is contained in:
Jonah Schulte 2026-01-01 00:31:12 -05:00
parent 1541274e57 a297235862
commit 387c42178e
484 changed files with 12063 additions and 7768 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

@ -46,8 +46,6 @@ CLAUDE.local.md
# Project-specific
_bmad-core
_bmad-creator-tools
test-project-install/*
sample-project/*
flattened-codebase.xml
*.stats.md
.internal-docs/
@ -66,6 +64,7 @@ shared-modules
z*/
_bmad
_bmad-output
.claude
.codex
.github/chatmodes

156
CHANGELOG.md
View File

@ -1,5 +1,161 @@
# Changelog
## [6.0.0-alpha.22]
**Release: December 31, 2025**
### 🌟 Key Highlights
1. **Unified Agent Workflow**: Create, Edit, and Validate workflows consolidated into single powerful agent workflow with separate step paths
2. **Agent Knowledge System**: Comprehensive data file architecture with persona properties, validation patterns, and crafting principles
3. **Deep Language Integration**: All sharded progressive workflows now support language choice at every step
4. **Core Module Documentation**: Extensive docs for core workflows (brainstorming, party mode, advanced elicitation)
5. **BMAD Core Concepts**: New documentation structure explaining agents, workflows, modules, and installation
6. **Tech Spec Sharded**: create-tech-spec workflow converted to sharded format with orient-first pattern
### 🤖 Unified Agent Workflow (Major Feature)
**Consolidated Architecture:**
- **Single Workflow, Three Paths**: Create, Edit, and Validate operations unified under `src/modules/bmb/workflows/agent/`
- **steps-c/**: Create path with 9 comprehensive steps for building new agents
- **steps-e/**: Edit path with 10 steps for modifying existing agents
- **steps-v/**: Validate path for standalone agent validation review
- **data/**: Centralized knowledge base for all agent-building intel
### 📚 Agent Knowledge System
**Data File Architecture:**
Located in `src/modules/bmb/workflows/agent/data/`:
- **agent-metadata.md** (208 lines) - Complete metadata field reference
- **agent-menu-patterns.md** (233 lines) - Menu design patterns and best practices
- **agent-compilation.md** (273 lines) - Compilation process documentation
- **persona-properties.md** (266 lines) - Persona crafting properties and examples
- **principles-crafting.md** (292 lines) - Core principles for agent design
- **critical-actions.md** (120 lines) - Critical action patterns
- **expert-agent-architecture.md** (236 lines) - Expert agent structure
- **expert-agent-validation.md** (173 lines) - Expert-specific validation
- **module-agent-validation.md** (124 lines) - Module-specific validation
- **simple-agent-architecture.md** (204 lines) - Simple agent structure
- **simple-agent-validation.md** (132 lines) - Simple agent validation
- **understanding-agent-types.md** (222 lines) - Agent type comparison
- **brainstorm-context.md** - Brainstorming guidance
- **communication-presets.csv** - Communication style presets
**Reference Examples:**
- **reference/module-examples/architect.agent.yaml** - Module agent example
- **reference/simple-examples/commit-poet.agent.yaml** - Simple agent example
- **journal-keeper/** - Complete sidecar pattern example
**Templates:**
- **templates/simple-agent.template.md** - Simple agent template
- **templates/expert-agent-template/expert-agent.template.md** - Expert agent template
- **templates/expert-agent-sidecar/** - Sidecar templates (instructions, memories)
### 🌍 Deep Language Integration
**Progressive Workflow Language Support:**
- **Every Step Biased**: All sharded progressive workflow steps now include language preference context
- **260+ Files Updated**: Comprehensive language integration across:
- Core workflows (brainstorming, party mode, advanced elicitation)
- BMB workflows (create-agent, create-module, create-workflow, edit-workflow, etc.)
- BMGD workflows (game-brief, gdd, narrative, game-architecture, etc.)
- BMM workflows (research, create-ux-design, prd, create-architecture, etc.)
- **Tested Languages**: Verified working with Spanish and Pirate Speak
- **Natural Conversations**: AI agents respond in configured language throughout workflow
### 📖 Core Module Documentation
**New Core Documentation Structure:**
`docs/modules/core/`:
- **index.md** - Core module overview
- **core-workflows.md** - Core workflow documentation
- **core-tasks.md** - Core task reference
- **brainstorming.md** (100 lines) - Brainstorming workflow guide
- **party-mode.md** (50 lines) - Party mode guide
- **advanced-elicitation.md** (105 lines) - Advanced elicitation techniques
- **document-sharding-guide.md** (133 lines) - Sharded workflow format guide
- **global-core-config.md** - Global core configuration reference
**Advanced Elicitation Moved:**
- **From**: `docs/` root
- **To**: `src/core/workflows/advanced-elicitation/`
- **Status**: Now a proper core workflow with methods.csv
### 📚 BMAD Core Concepts Documentation
**New Documentation Structure:**
`docs/bmad-core-concepts/`:
- **index.md** - Core concepts introduction
- **agents.md** (93 lines) - Understanding agents in BMAD
- **workflows.md** (89 lines) - Understanding workflows in BMAD
- **modules.md** (76 lines) - Understanding modules (BMM, BMGD, CIS, BMB, Core)
- **installing/index.md** (77 lines) - Installation guide
- **installing/upgrading.md** (144 lines) - Upgrading guide
- **bmad-customization/index.md** - Customization overview
- **bmad-customization/agents.md** - Agent customization guide
- **bmad-customization/workflows.md** (30 lines) - Workflow customization guide
- **web-bundles/index.md** (34 lines) - Web bundle distribution guide
**Documentation Cleanup:**
- **Removed v4-to-v6-upgrade.md** - Outdated upgrade guide
- **Removed document-sharding-guide.md** from docs root (moved to core)
- **Removed web-bundles-gemini-gpt-guide.md** - Consolidated into web-bundles/index.md
- **Removed getting-started/installation.md** - Migrated to bmad-core-concepts
- **Removed all ide-info/*.md files** - Consolidated into web-bundles documentation
### 🔧 Create-Tech-Spec Sharded Conversion
**Monolithic to Sharded:**
- **From**: Single `workflow.yaml` with `instructions.md`
- **To**: Sharded `workflow.md` with individual step files
- **Pattern**: Orient-first approach (understand before investigating)
### 🔨 Additional Improvements
**Workflow Status Path Fixes:**
- **Corrected Discovery Paths**: workflow-status workflows now properly use planning_artifacts and implementation_artifacts
- **Updated All Path Files**: enterprise-brownfield, enterprise-greenfield, method-brownfield, method-greenfield
**Documentation Updates:**
- **BMB Agent Creation Guide**: Comprehensive 166-line guide for agent creation
- **Workflow Vendoring Doc**: New 42-line guide on workflow customization and inheritance
- **Document Project Reference**: Moved from BMM docs to shared location
- **Workflows Planning Guide**: New 89-line guide for planning workflows
**BMB Documentation Streamlining:**
- **Removed Redundant Docs**: Eliminated duplicate documentation in `src/modules/bmb/docs/`
- **Step File Rules**: New 469-line comprehensive guide for step file creation
- **Agent Docs Moved**: Agent architecture and validation docs moved to workflow data/
**Windows Inquirer Fix:**
- **Another Default Addition**: Additional inquirer default value setting for better Windows multiselection support
**Code Quality:**
- **Removed Old BMM README**: Consolidated module documentation
- **Removed BMM Troubleshooting**: 661-line doc moved to shared location
- **Removed Enterprise Agentic Development**: 686-line doc consolidated
- **Removed Scale Adaptive System**: 618-line doc consolidated
---
## [6.0.0-alpha.21]
**Release: December 27, 2025**

70
README.md
View File

@ -24,9 +24,8 @@ The completely revamped **BMAD V6 installer** now includes built-in support for
**📚 Learn More:**
- [**Custom Content Overview**](./docs/custom-content.md) - Discover all supported content types
- [**Installation Guide**](./docs/custom-content-installation.md) - Learn to create and install custom content
- [**Detail Content Docs**](./src/modules/bmb/docs/index.md) - Reference details for agents, modules, workflows and the bmad builder
- [**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>
@ -68,7 +67,7 @@ With **BMad Builder**, you can architect both simple agents and vastly complex d
## 📊 See It In Action
<p align="center">
<img src="./src/modules/bmm/docs/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
<img src="./docs/modules/bmm-bmad-method/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
</p>
<p align="center">
@ -80,13 +79,18 @@ With **BMad Builder**, you can architect both simple agents and vastly complex d
### 1. Install BMad Method
```bash
# Install v6 Alpha (recommended)
# Install v6 RECOMMENDED
npx bmad-method@alpha install
# Or stable v4 for production
npx bmad-method install
```
```bash
# Install v4 Legacy (not recommended if starting fresh)
npx bmad-method install
# OR
npx bmad-method@latest install
```
### 2. Initialize Your Project
Load any agent in your IDE and run:
@ -101,8 +105,8 @@ This analyzes your project and recommends the right workflow track.
BMad Method adapts to your needs with three intelligent tracks:
| Track | Use For | Planning | Time to Start |
| ------------------ | ------------------------- | ----------------------- | ------------- |
| 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 |
@ -124,35 +128,35 @@ Each phase has specialized workflows and agents working together to deliver exce
**12 Specialized Agents** working in concert:
| Development | Architecture | Product | Leadership |
| ----------- | -------------- | ------------- | -------------- |
| Developer | Architect | PM | Scrum Master |
| UX Designer | Test Architect | Analyst | BMad Master |
| Tech Writer | Game Architect | Game Designer | Game Developer |
| Development | Architecture | Product | Leadership |
| ----------- | -------------- | ----------- | ------------ |
| Developer | Architect | PM | Scrum Master |
| UX Designer | Test Architect | Analyst | BMad Master |
| | | Tech Writer | |
**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready fixture-based utilities.
**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready web app fixture-based utilities.
Each agent brings deep expertise and can be customized to match your team's style.
## 📦 What's Included
### Core Modules
### Official Modules
- **BMad Method (BMM)** - Complete agile development framework
- 12 specialized agents
- 34 workflows across 4 phases
- Scale-adaptive planning
- [→ Documentation Hub](./src/modules/bmm/docs/index.md)
- Stand Along Quick Spec Flow for a streamlined simple implementation process
- [→ Documentation Hub](./docs/modules/bmm-bmad-method/index.md)
- **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](./src/modules/bmb/docs/index.md)
- [→ Builder Guide](./docs/modules/bmb-bmad-builder/index.md)
- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
- Brainstorming, design thinking, storytelling
- 5 creative facilitation workflows
- [→ Creative Workflows](./src/modules/cis/docs/index.md)
- [→ Creative Workflows](./docs/modules/cis-creative-intelligence-suite/index.md)
### Key Features
@ -166,14 +170,14 @@ Each agent brings deep expertise and can be customized to match your team's styl
### Quick Links
- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - 15-minute introduction
- **[Complete BMM Documentation](./src/modules/bmm/docs/index.md)** - All guides and references
- **[Agent Customization](./docs/agent-customization-guide.md)** - Personalize your agents
- **[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
### For v4 Users
- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4/docs)**
- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)**
## 💬 Community & Support
@ -181,24 +185,12 @@ Each agent brings deep expertise and can be customized to match your team's styl
- **[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
- **[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
## 🛠️ Development
For contributors working on the BMad codebase:
```bash
# Run all quality checks
npm test
# Development commands
npm run lint:fix # Fix code style
npm run format:fix # Auto-format code
npm run bundle # Build web bundles
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
If you would like to contribute, first check the [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
## What's New in v6

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

@ -0,0 +1,93 @@
# 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.

8
docs/agent-customization-guide.md → docs/bmad-core-concepts/bmad-customization/agents.md
View File

@ -203,6 +203,8 @@ memories:
## Next Steps
- **[BMM Agents Guide](./modules/bmm/agents-guide)** - Learn about the BMad Method agents
- **[BMB Create Agent Workflow](./modules/bmb/agents/index)** - Build completely custom agents
- **[BMM Complete Documentation](./modules/bmm/index)** - Full BMad Method reference
- **[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 Normal file
View File

@ -0,0 +1,26 @@
# 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 Normal file
View File

@ -0,0 +1,30 @@
# 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 Normal file
View File

@ -0,0 +1,37 @@
# 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.

21
docs/getting-started/installation.md → docs/bmad-core-concepts/installing/index.md
View File

@ -1,6 +1,12 @@
# Installation
Get BMAD Method running in your project in under 2 minutes.
Get BMAD up and running in your project.
## Upgrading?
If you're upgrading from v4, see the [Upgrade Guide](./upgrading.md).
---
## Quick Install
@ -10,9 +16,11 @@ npx bmad-method install
This interactive installer will:
1. Detect your IDE (Claude Code, Cursor, VS Code, etc.)
2. Let you choose which modules to install
3. Configure agents and workflows for your project
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
@ -58,8 +66,9 @@ your-project/
## Next Steps
1. **Read the [Quick Start Guide](../modules/bmm/quick-start.md)** to build your first feature
2. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology
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

30
docs/v4-to-v6-upgrade.md → docs/bmad-core-concepts/installing/upgrading.md
View File

@ -10,15 +10,13 @@ BMad v6 represents a complete ground-up rewrite with significant architectural c
When you run `npm run install:bmad` on a project, the installer automatically detects:
- **Legacy folders**: Any folders starting with `bmad-core` or `bmad-core`
- **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 Backup of v4 Modules**: All `.bmad-core` folders are moved to `v4-backup/` in your project root
- If a backup already exists, a timestamp is added to avoid conflicts
- Example: `.bmad-core` → `v4-backup/_bmad-core`
- Your project files and data are NOT affected
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.
@ -27,7 +25,7 @@ When you run `npm run install:bmad` on a project, the installer automatically de
## Module Migration
### Deprecated Modules
### Deprecated Modules from v4
| v4 Module | v6 Status |
| ----------------------------- | ---------------------------------------------- |
@ -38,6 +36,7 @@ When you run `npm run install:bmad` on a project, the installer automatically de
| `_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
@ -47,29 +46,30 @@ When you run `npm run install:bmad` on a project, the installer automatically de
```
your-project/
├── _bmad-core/ # Was actually the BMad Method
├── _bmad-game-dev/ # Separate expansion packs
├── _bmad-creative-writing/
└── _bmad-infrastructure-devops/
├── .bmad-method/
├── .bmad-game-dev/
├── .bmad-creative-writing/
└── .bmad-infrastructure-devops/
```
**v6 Unified Structure:**
```
your-project/
└── _bmad/ # Single installation folder, default _bmad
└── _config/ # Your customizations
| └── agents/ # Agent customization files
└── _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`**: Was actually the BMad Method
- **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
@ -120,7 +120,7 @@ persona:
- 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](agent-customization-guide.md)
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.

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

@ -0,0 +1,76 @@
# 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 Normal file
View File

@ -0,0 +1,34 @@
# 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 Normal file
View File

@ -0,0 +1,89 @@
# 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.

138
docs/index.md
View File

@ -1,105 +1,111 @@
# BMad Documentation Index
# BMAD Documentation
## 🎯 Getting Started (Start Here!)
Complete documentation for the BMAD Method.
**New users:** Start with one of these based on your situation:
## Getting Started
| Your Situation | Start Here | Then Read |
| ---------------------- | -------------------------------------------------- | ----------------------------------------------------------- |
| **Brand new to BMad** | [Quick Start Guide](bmm/quick-start) | [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) |
| **Upgrading from v4** | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) | [Quick Start Guide](./modules/bmm/quick-start) |
| **Brownfield project** | [Brownfield Guide](./modules/bmm/brownfield-guide) | [Quick Start Guide](./modules/bmm/quick-start) |
### 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
---
## 📋 Core Documentation
## Module Documentation
### Project-Level Docs (Root)
- **[README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md)** - Main project overview, feature summary, and module introductions
- **[CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style
- **[CHANGELOG.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)** - Version history and breaking changes
### Installation & Setup
- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings
- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - (temporarily non-functional) Maintainer guide for bundle auto-publishing
---
## 🏗️ Module Documentation
### BMad Method (BMM) - Software & Game Development
### BMAD Method (BMM) - Software & Game Development
The flagship module for agile AI-driven development.
- **[BMM Module README](./modules/bmm/)** - Module overview, agents, and complete documentation index
- **[BMM Documentation](./modules/bmm/)** - All BMM-specific guides and references:
- [Quick Start Guide](./modules/bmm/quick-start) - Step-by-step guide to building your first project
- [Quick Spec Flow](./modules/bmm/quick-spec-flow) - Rapid Level 0-1 development
- [Scale Adaptive System](./modules/bmm/scale-adaptive-system) - Understanding the 5-level system
- [Brownfield Guide](./modules/bmm/brownfield-guide) - Working with existing codebases
- **[BMM Workflows Guide](./modules/bmm/index#-workflow-guides)** - **ESSENTIAL READING**
- **[Test Architect Guide](./modules/bmm/test-architecture)** - Testing strategy and quality assurance
- **[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
### BMad Builder (BMB) - Create Custom Solutions
### BMAD Builder (BMB) - Create Custom Solutions
Build your own agents, workflows, and modules.
- **[BMB Module Overview](./modules/bmb/index)** - Module overview and capabilities
- **[Agent Creation Guide](./modules/bmb/agents/index)** - Design custom agents
- **[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
### Creative Intelligence Suite (CIS) - Innovation & Creativity
AI-powered creative thinking and brainstorming.
- **[CIS Documentation](./modules/cis-creative-intelligence-suite/index)**
- **[CIS Module README](./modules/cis/)** - Module overview and workflows
### BMAD Game Dev (BMGD)
## 🔧 Advanced Topics
### Custom Agents, Workflow and Modules
- **[Custom Content Installation](./custom-content-installation.md)** - Install and personalize agents, workflows and modules with the default bmad-method installer!
- [Agent Customization Guide](./agent-customization-guide.md) - Customize agent behavior and responses
- **[BMGD Documentation](./modules/bmgd-bmad-game-dev/index)** - Game development workflows
---
## 🎓 Recommended Reading Paths
## Core Module
### Path 1: Brand New to BMad (Software Project)
### Global Core Entities
1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on
3. [BMM Module README](./modules/bmm/) - Understand agents
4. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology
- **[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
---
## 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. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on
3. [BMM Module README](./modules/bmm/) - Game agents are included
4. [BMGD Workflows Guide](./modules/bmgd/workflows-guide) - Game-specific workflows
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](./v4-to-v6-upgrade.md) - Understand what changed
2. [Quick Start Guide](./modules/bmm/quick-start) - Reorient yourself
3. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Learn new v6 workflows
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/brownfield-guide) - Approach for legacy code
2. [Quick Start Guide](./modules/bmm/quick-start) - Follow the process
3. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology
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 Solutions
### Path 5: Building Custom Agents
1. [BMB Module Overview](./modules/bmb/index) - Understand capabilities
2. [Agent Creation Guide](./modules/bmb/agents/index) - Create agents
3. [BMB Workflows Guide](./modules/bmb/workflows/) - Understand workflow structure
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
### 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

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

@ -0,0 +1,166 @@
# 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)

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

@ -2,7 +2,7 @@
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](./custom-content.md).
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.

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

9
src/modules/bmb/docs/agents/index.md → docs/modules/bmb-bmad-builder/index.md
View File

@ -1,6 +1,11 @@
# BMB Module Documentation
Reference documentation for building BMAD agents and workflows.
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
@ -37,7 +42,7 @@ Production-ready examples in [bmb/reference/agents/](https://github.com/bmad-cod
For installing standalone simple and expert agents, see:
- [Custom Agent Installation](/docs/custom-content-installation.md)
- [Custom Agent Installation](/docs/modules/bmb-bmad-builder/custom-content-installation.md)
## Key Concepts

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

0
src/modules/bmgd/docs/agents-guide.md → docs/modules/bmgd-bmad-game-dev/agents-guide.md
View File

0
src/modules/bmgd/docs/game-types-guide.md → docs/modules/bmgd-bmad-game-dev/game-types-guide.md
View File

0
src/modules/bmgd/docs/glossary.md → docs/modules/bmgd-bmad-game-dev/glossary.md
View File

0
src/modules/bmgd/docs/index.md → docs/modules/bmgd-bmad-game-dev/index.md
View File

0
src/modules/bmgd/docs/quick-flow-guide.md → docs/modules/bmgd-bmad-game-dev/quick-flow-guide.md
View File

0
src/modules/bmgd/docs/quick-start.md → docs/modules/bmgd-bmad-game-dev/quick-start.md
View File

0
src/modules/bmgd/docs/troubleshooting.md → docs/modules/bmgd-bmad-game-dev/troubleshooting.md
View File

0
src/modules/bmgd/docs/workflow-overview.jpg → docs/modules/bmgd-bmad-game-dev/workflow-overview.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 200 KiB

After

Width:  |  Height:  |  Size: 200 KiB

12
src/modules/bmgd/docs/workflows-guide.md → docs/modules/bmgd-bmad-game-dev/workflows-guide.md
View File

@ -8,7 +8,7 @@ Complete reference for all BMGD workflows organized by development phase.
BMGD workflows are organized into four phases:
![BMGD Workflow Overview](./workflow-overview.jpg)
![BMGD Workflow Overview](../../../../docs/modules/bmgd-bmad-game-dev/workflow-overview.jpg)
---
@ -259,7 +259,7 @@ Checks current project status across all phases. Shows completed documents, curr
## Quick-Flow Workflows
Fast-track workflows that skip full planning phases. See **[Quick-Flow Guide](./quick-flow-guide.md)** for detailed usage.
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
@ -457,7 +457,7 @@ This means:
## Next Steps
- **[Quick Start Guide](./quick-start.md)** - Get started with BMGD
- **[Quick-Flow Guide](./quick-flow-guide.md)** - Rapid prototyping and development
- **[Agents Guide](./agents-guide.md)** - Agent reference
- **[Game Types Guide](./game-types-guide.md)** - Game type templates
- **[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

0
src/modules/bmm/docs/agents-guide.md → docs/modules/bmm-bmad-method/agents-guide.md
View File

0
src/modules/bmm/docs/bmad-quick-flow.md → docs/modules/bmm-bmad-method/bmad-quick-flow.md
View File

78
docs/modules/bmm-bmad-method/brownfield-guide.md Normal file
View File

@ -0,0 +1,78 @@
# 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.
---
## 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
Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
- Intent and business rationale
- Business rules
- Architecture
- Any other relevant project information
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
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.
### Choosing Your Approach
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. |
### 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
You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
### 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
If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
### 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.
---
## 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

0
src/modules/bmm/docs/faq.md → docs/modules/bmm-bmad-method/faq.md
View File

0
src/modules/bmm/docs/glossary.md → docs/modules/bmm-bmad-method/glossary.md
View File

0
src/modules/bmm/docs/images/README.md → docs/modules/bmm-bmad-method/images/README.md
View File

0
src/modules/bmm/docs/images/workflow-method-greenfield.excalidraw → docs/modules/bmm-bmad-method/images/workflow-method-greenfield.excalidraw
View File

0
src/modules/bmm/docs/images/workflow-method-greenfield.svg → docs/modules/bmm-bmad-method/images/workflow-method-greenfield.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 87 KiB

After

Width:  |  Height:  |  Size: 87 KiB

0
src/modules/bmm/docs/index.md → docs/modules/bmm-bmad-method/index.md
View File

0
src/modules/bmm/docs/party-mode.md → docs/modules/bmm-bmad-method/party-mode.md
View File

0
src/modules/bmm/docs/quick-flow-solo-dev.md → docs/modules/bmm-bmad-method/quick-flow-solo-dev.md
View File

0
src/modules/bmm/docs/quick-spec-flow.md → docs/modules/bmm-bmad-method/quick-spec-flow.md
View File

0
src/modules/bmm/docs/quick-start.md → docs/modules/bmm-bmad-method/quick-start.md
View File

0
src/modules/bmm/docs/test-architecture.md → docs/modules/bmm-bmad-method/test-architecture.md
View File

0
src/modules/bmm/docs/troubleshooting.md → docs/modules/bmm-bmad-method/troubleshooting.md
View File

0
src/modules/bmm/docs/workflow-document-project-reference.md → docs/modules/bmm-bmad-method/workflow-document-project-reference.md
View File

8
src/modules/bmm/docs/workflows-analysis.md → docs/modules/bmm-bmad-method/workflows-analysis.md
View File

@ -192,8 +192,8 @@ Planning workflows automatically load these documents if they exist in the outpu
## Related Documentation
- [Phase 2: Planning Workflows](./workflows-planning.md) - Next phase
- [Phase 3: Solutioning Workflows](./workflows-solutioning.md)
- [Phase 4: Implementation Workflows](./workflows-implementation.md)
- [Phase 2: Planning Workflows](../../../../docs/modules/bmm-bmad-method/workflows-planning.md) - Next phase
- [Phase 3: Solutioning Workflows](../../../../docs/modules/bmm-bmad-method/workflows-solutioning.md)
- [Phase 4: Implementation Workflows](../../../../docs/modules/bmm-bmad-method/workflows-implementation.md)
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding project complexity
- [Agents Guide](./agents-guide.md) - Complete agent reference
- [Agents Guide](../../../../docs/modules/bmm-bmad-method/agents-guide.md) - Complete agent reference

0
src/modules/bmm/docs/workflows-implementation.md → docs/modules/bmm-bmad-method/workflows-implementation.md
View File

0
src/modules/bmm/docs/workflows-planning.md → docs/modules/bmm-bmad-method/workflows-planning.md
View File

8
src/modules/bmm/docs/workflows-solutioning.md → docs/modules/bmm-bmad-method/workflows-solutioning.md
View File

@ -434,7 +434,7 @@ Architecture documents are living. Update them as you learn during implementatio
**Key Difference:** Enterprise adds optional extended workflows AFTER architecture but BEFORE create-epics-and-stories. Everything else is identical to BMad Method.
**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](./test-architecture.md) for TEA's full lifecycle integration.
**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](../../../../docs/modules/bmm-bmad-method/test-architecture.md) for TEA's full lifecycle integration.
---
@ -471,10 +471,10 @@ Architecture documents are living. Update them as you learn during implementatio
## Related Documentation
- [Phase 2: Planning Workflows](./workflows-planning.md) - Previous phase
- [Phase 4: Implementation Workflows](./workflows-implementation.md) - Next phase
- [Phase 2: Planning Workflows](../../../../docs/modules/bmm-bmad-method/workflows-planning.md) - Previous phase
- [Phase 4: Implementation Workflows](../../../../docs/modules/bmm-bmad-method/workflows-implementation.md) - Next phase
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding tracks
- [Agents Guide](./agents-guide.md) - Complete agent reference
- [Agents Guide](../../../../docs/modules/bmm-bmad-method/agents-guide.md) - Complete agent reference
---

0
src/modules/cis/docs/index.md → docs/modules/cis-creative-intelligence-suite/index.md
View File

105
docs/modules/core/advanced-elicitation.md Normal file
View File

@ -0,0 +1,105 @@
# Advanced Elicitation
**Push the LLM to rethink its work through 50+ reasoning methods—essentially, LLM brainstorming.**
Advanced Elicitation is the inverse of Brainstorming. Instead of pulling ideas out of you, the LLM applies sophisticated reasoning techniques to re-examine and enhance content it has just generated. It's the LLM brainstorming with itself to find better approaches, uncover hidden issues, and discover improvements it missed on the first pass.
---
## When to Use It
- After a workflow generates a section of content and you want to explore alternatives
- When the LLM's initial output seems adequate but you suspect there's more depth available
- For high-stakes content where multiple perspectives would strengthen the result
- To stress-test assumptions, explore edge cases, or find weaknesses in generated plans
- When you want the LLM to "think again" but with structured reasoning methods
---
## How It Works
### 1. Context Analysis
The LLM analyzes the current content, understanding its type, complexity, stakeholder needs, risk level, and creative potential.
### 2. Smart Method Selection
Based on context, 5 methods are intelligently selected from a library of 50+ techniques and presented to you:
| Option | Description |
| ----------------- | ---------------------------------------- |
| **1-5** | Apply the selected method to the content |
| **[r] Reshuffle** | Get 5 new methods selected randomly |
| **[a] List All** | Browse the complete method library |
| **[x] Proceed** | Continue with enhanced content |
### 3. Method Execution & Iteration
- The selected method is applied to the current content
- Improvements are shown for your review
- You choose whether to apply changes or discard them
- The menu re-appears for additional elicitations
- Each method builds on previous enhancements
### 4. Party Mode Integration (Optional)
If Party Mode is active, BMAD agents participate randomly in the elicitation process, adding their unique perspectives to the methods.
---
## Method Categories
| Category | Focus | Example Methods |
| ----------------- | ----------------------------------- | -------------------------------------------------------------- |
| **Core** | Foundational reasoning techniques | First Principles Analysis, 5 Whys, Socratic Questioning |
| **Collaboration** | Multiple perspectives and synthesis | Stakeholder Round Table, Expert Panel Review, Debate Club |
| **Advanced** | Complex reasoning frameworks | Tree of Thoughts, Graph of Thoughts, Self-Consistency |
| **Competitive** | Adversarial stress-testing | Red Team vs Blue Team, Shark Tank Pitch, Code Review Gauntlet |
| **Technical** | Architecture and code quality | Decision Records, Rubber Duck Debugging, Algorithm Olympics |
| **Creative** | Innovation and lateral thinking | SCAMPER, Reverse Engineering, Random Input Stimulus |
| **Research** | Evidence-based analysis | Literature Review Personas, Thesis Defense, Comparative Matrix |
| **Risk** | Risk identification and mitigation | Pre-mortem Analysis, Failure Mode Analysis, Chaos Monkey |
| **Learning** | Understanding verification | Feynman Technique, Active Recall Testing |
| **Philosophical** | Conceptual clarity | Occam's Razor, Ethical Dilemmas |
| **Retrospective** | Reflection and lessons | Hindsight Reflection, Lessons Learned Extraction |
---
## Key Features
- **50+ reasoning methods** — Spanning core logic to advanced multi-step reasoning frameworks
- **Smart context selection** — Methods chosen based on content type, complexity, and stakeholder needs
- **Iterative enhancement** — Each method builds on previous improvements
- **User control** — Accept or discard each enhancement before proceeding
- **Party Mode integration** — Agents can participate when Party Mode is active
---
## Workflow Integration
Advanced Elicitation is a core workflow designed to be invoked by other workflows during content generation:
| Parameter | Description |
| ---------------------- | --------------------------------------------------------- |
| **Content to enhance** | The current section content that was just generated |
| **Context type** | The kind of content being created (spec, code, doc, etc.) |
| **Enhancement goals** | What the calling workflow wants to improve |
### Integration Flow
When called from a workflow:
1. Receives the current section content that was just generated
2. Applies elicitation methods iteratively to enhance that content
3. Returns the enhanced version when user selects 'x' to proceed
4. The enhanced content replaces the original section in the output document
### Example
A specification generation workflow could invoke Advanced Elicitation after producing each major section (requirements, architecture, implementation plan). The workflow would pass the generated section, and Advanced Elicitation would offer methods like "Stakeholder Round Table" to gather diverse perspectives on requirements, or "Red Team vs Blue Team" to stress-test the architecture for vulnerabilities.
---
## Advanced Elicitation vs. Brainstorming
| | **Advanced Elicitation** | **Brainstorming** |
| ------------ | ------------------------------------------------- | --------------------------------------------- |
| **Source** | LLM generates ideas through structured reasoning | User provides ideas, AI coaches them out |
| **Purpose** | Rethink and improve LLM's own output | Unlock user's creativity |
| **Methods** | 50+ reasoning and analysis techniques | 60+ ideation and creativity techniques |
| **Best for** | Enhancing generated content, finding alternatives | Breaking through blocks, generating new ideas |

100
docs/modules/core/brainstorming.md Normal file
View File

@ -0,0 +1,100 @@
# Brainstorming
**Facilitate structured creative sessions using 60+ proven ideation techniques.**
The Brainstorming workflow is an interactive facilitation system that helps you unlock your own creativity. The AI acts as coach, guide, and creative partner—using proven techniques to draw out ideas and insights that are already within you.
**Important:** Every idea comes from you. The workflow creates the conditions for your best thinking to emerge through guided exploration, but you are the source.
---
## When to Use It
- Breaking through creative blocks on a specific challenge
- Generating innovative ideas for products, features, or solutions
- Exploring a problem from completely new angles
- Systematically developing ideas from raw concepts to actionable plans
- Team ideation (with collaborative techniques) or personal creative exploration
---
## How It Works
### 1. Session Setup
Define your topic, goals, and any constraints.
### 2. Choose Your Approach
| Approach | Description |
|----------|-------------|
| **User-Selected** | Browse the full technique library and pick what appeals to you |
| **AI-Recommended** | Get customized technique suggestions based on your goals |
| **Random Selection** | Discover unexpected methods through serendipitous technique combinations |
| **Progressive Flow** | Journey systematically from expansive exploration to focused action planning |
### 3. Interactive Facilitation
Work through techniques with true collaborative coaching. The AI asks probing questions, builds on your ideas, and helps you think deeper—but your ideas are the source.
### 4. Idea Organization
All your generated ideas are organized into themes and prioritized.
### 5. Action Planning
Top ideas get concrete next steps, resource requirements, and success metrics.
---
## What You Get
A comprehensive session document that captures the entire journey:
- Topic, goals, and session parameters
- Each technique used and how it was applied
- Your contributions and the ideas you generated
- Thematic organization connecting related insights
- Prioritized ideas with action plans
- Session highlights and key breakthroughs
This document becomes a permanent record of your creative process—valuable for future reference, sharing with stakeholders, or continuing the session later.
---
## Technique Categories
| Category | Focus |
|----------|-------|
| **Collaborative** | Team dynamics and inclusive participation |
| **Creative** | Breakthrough thinking and paradigm shifts |
| **Deep** | Root cause analysis and strategic insight |
| **Structured** | Organized frameworks and systematic exploration |
| **Theatrical** | Playful, radical perspectives |
| **Wild** | Boundary-pushing, extreme thinking |
| **Biomimetic** | Nature-inspired solutions |
| **Quantum** | Quantum principles for innovation |
| **Cultural** | Traditional knowledge and cross-cultural approaches |
| **Introspective Delight** | Inner wisdom and authentic exploration |
---
## Key Features
- **Interactive coaching** — Pulls ideas *out* of you, doesn't generate them for you
- **On-demand loading** — Techniques loaded from a comprehensive library as needed
- **Session preservation** — Every step, insight, and action plan is documented
- **Continuation support** — Pause sessions and return later, or extend with additional techniques
---
## Workflow Integration
Brainstorming is a core workflow designed to be invoked and configured by other modules. When called from another workflow, it accepts contextual parameters:
| Parameter | Description |
|-----------|-------------|
| **Topic focus** | What the brainstorming should help discover or solve |
| **Guardrails** | Constraints, boundaries, or must-avoid areas |
| **Output goals** | What the final output needs to accomplish for the calling workflow |
| **Context files** | Project-specific guidance to inform technique selection |
### Example
When creating a new module in the BMad Builder workflow, Brainstorming can be invoked with guardrails around the module's purpose and a goal to discover key features, user needs, or architectural considerations. The session becomes focused on producing exactly what the module creation workflow needs.

64
docs/modules/core/core-tasks.md Normal file
View File

@ -0,0 +1,64 @@
# Core Tasks
Core Tasks are reusable task definitions that can be invoked by any BMAD module, workflow, or agent. These tasks provide standardized functionality for common operations.
## Table of Contents
- [Index Docs](#index-docs) — Generate directory index files
- [Adversarial Review](#adversarial-review-general) — Critical content review
- [Shard Document](#shard-document) — Split large documents into sections
---
## Index Docs
**Generates or updates an index.md file documenting all documents in a specified directory.**
This task scans a target directory, reads file contents to understand their purpose, and creates a well-organized index with accurate descriptions. Files are grouped by type, purpose, or subdirectory, and descriptions are generated from actual content rather than guessing from filenames.
**Use it when:** You need to create navigable documentation for a folder of markdown files, or you want to maintain an updated index as content evolves.
**How it works:**
1. Scan the target directory for files and subdirectories
2. Group content by type, purpose, or location
3. Read each file to generate brief (3-10 word) descriptions based on actual content
4. Create or update index.md with organized listings using relative paths
**Output format:** A markdown index with sections for Files and Subdirectories, each entry containing a relative link and description.
---
## Adversarial Review (General)
**Performs a cynical, skeptical review of any content to identify issues and improvement opportunities.**
This task applies adversarial thinking to content review—approaching the material with the assumption that problems exist. It's designed to find what's missing, not just what's wrong, and produces at least ten specific findings. The reviewer adopts a professional but skeptical tone, looking for gaps, inconsistencies, oversights, and areas that need clarification.
**Use it when:** You need a critical eye on code diffs, specifications, user stories, documentation, or any artifact before finalizing. It's particularly valuable before merging code, releasing documentation, or considering a specification complete.
**How it works:**
1. Load the content to review (diff, branch, uncommitted changes, document, etc.)
2. Perform adversarial analysis with extreme skepticism—assume problems exist
3. Find at least ten issues to fix or improve
4. Output findings as a markdown list
**Note:** This task is designed to run in a separate subagent/process with read access to the project but no prior context, ensuring an unbiased review.
---
## Shard Document
**Splits large markdown documents into smaller, organized files based on level 2 (##) sections.**
Uses the `@kayvan/markdown-tree-parser` tool to automatically break down large documents into a folder structure. Each level 2 heading becomes a separate file, and an index.md is generated to tie everything together. This makes large documents more maintainable and allows for easier navigation and updates to individual sections.
**Use it when:** A markdown file has grown too large to effectively work with, or you want to break a monolithic document into manageable sections that can be edited independently.
**How it works:**
1. Confirm source document path and verify it's a markdown file
2. Determine destination folder (defaults to same location as source, folder named after document)
3. Execute the sharding command using npx @kayvan/markdown-tree-parser
4. Verify output files and index.md were created
5. Handle the original document—delete, move to archive, or keep with warning
**Handling the original:** After sharding, the task prompts you to delete, archive, or keep the original document. Deleting or archiving is recommended to avoid confusion and ensure updates happen in the sharded files only.

30
docs/modules/core/core-workflows.md Normal file
View File

@ -0,0 +1,30 @@
# Core Workflows
Core Workflows are domain-agnostic workflows that can be utilized by any BMAD-compliant module, workflow, or agent. These workflows are installed by default and available at any time.
## Available Core Workflows
### [Party Mode](party-mode.md)
Orchestrate dynamic multi-agent conversations with your entire BMAD team. Engage with multiple specialized perspectives simultaneously—each agent maintaining their unique personality, expertise, and communication style.
### [Brainstorming](brainstorming.md)
Facilitate structured creative sessions using 60+ proven ideation techniques. The AI acts as coach and guide, using proven creativity methods to draw out ideas and insights that are already within you.
### [Advanced Elicitation](advanced-elicitation.md)
Push the LLM to rethink its work through 50+ reasoning methods—the inverse of brainstorming. The LLM applies sophisticated techniques to re-examine and enhance content it has just generated, essentially "LLM brainstorming" to find better approaches and uncover improvements.
---
## Workflow Integration
Core Workflows are designed to be invoked and configured by other modules. When called from another workflow, they accept contextual parameters to customize the session:
- **Topic focus** — Direct the session toward a specific domain or question
- **Additional personas** (Party Mode) — Inject expert agents into the roster at runtime
- **Guardrails** (Brainstorming) — Set constraints and boundaries for ideation
- **Output goals** — Define what the final output needs to accomplish
This allows modules to leverage these workflows' capabilities while maintaining focus on their specific domain and objectives.

0
docs/document-sharding-guide.md → docs/modules/core/document-sharding-guide.md
View File

11
docs/modules/core/global-core-config.md Normal file
View File

@ -0,0 +1,11 @@
# Core Module Global Inheritable Config
The Core Modules module.yaml file defines configuration values that are useful and unique for all other modules to utilize, and by default all other modules installed will clone the values defined in the core module yaml.config into their own. It is possible for other modules to override these values, but the general intent it to accept the core module values and define their own values as needed, or extend the core values.
Currently, the core module.yaml config will define (asking the user upon installation, and recording to the core module config.yaml):
- `user_name`: string (defaults to the system defined user name)
- `communication_language`: string (defaults to english)
- `document_output_language`: string (defaults to english)
- `output_folder`: string (default `_bmad-output`)
An example of extending one of these values, in the BMad Method module.yaml it defines a planning_artifacts config, which will default to `default: "{output_folder}/planning-artifacts"` thus whatever the output_folder will be, this extended versions default will use the value from this core module and append a new folder onto it. The user can choose to replace this without utilizing the output_folder from the core if they so chose.

15
docs/modules/core/index.md Normal file
View File

@ -0,0 +1,15 @@
# Core Module
The Core Module is installed with all installations of BMAD modules and provides common functionality that any module, workflow, or agent can take advantage of.
## Core Module Components
- **[Global Core Config](global-core-config.md)** — Inheritable configuration that impacts all modules and custom content
- **[Core Workflows](core-workflows.md)** — Domain-agnostic workflows usable by any module
- [Party Mode](party-mode.md) — Multi-agent conversation orchestration
- [Brainstorming](brainstorming.md) — Structured creative sessions with 60+ techniques
- [Advanced Elicitation](advanced-elicitation.md) — LLM rethinking with 50+ reasoning methods
- **[Core Tasks](core-tasks.md)** — Common tasks available across modules
- [Index Docs](core-tasks.md#index-docs) — Generate directory index files
- [Adversarial Review](core-tasks.md#adversarial-review-general) — Critical content review
- [Shard Document](core-tasks.md#shard-document) — Split large documents into sections

50
docs/modules/core/party-mode.md Normal file
View File

@ -0,0 +1,50 @@
# Party Mode
**Orchestrate dynamic multi-agent conversations with your entire BMAD team.**
Party Mode brings together all your installed BMAD agents for collaborative discussions. Instead of working with a single agent, you can engage with multiple specialized perspectives simultaneously—each agent maintaining their unique personality, expertise, and communication style.
---
## When to Use It
- Exploring complex topics that would benefit from diverse expert perspectives
- Brainstorming with agents who can build on each other's ideas
- Getting a comprehensive view across multiple domains (technical, business, creative, strategic)
- Enjoying dynamic, agent-to-agent conversations where experts challenge and complement each other
---
## How It Works
1. Party Mode loads your complete agent roster and introduces the available team members
2. You present a topic or question
3. The facilitator intelligently selects 2-3 most relevant agents based on expertise needed
4. Agents respond in character, can reference each other, and engage in natural cross-talk
5. The conversation continues until you choose to exit
---
## Key Features
- **Intelligent agent selection** — The system analyzes your topic and selects the most relevant agents based on their expertise, capabilities, and principles
- **Authentic personalities** — Each agent maintains their unique voice, communication style, and domain knowledge throughout the conversation
- **Natural cross-talk** — Agents can reference each other, build on previous points, ask questions, and even respectfully disagree
- **Optional TTS integration** — Each agent response can be read aloud with voice configurations matching their personalities
- **Graceful exit** — Sessions conclude with personalized farewells from participating agents
---
## Workflow Integration
Party Mode is a core workflow designed to be invoked and configured by other modules. When called from another workflow, it accepts contextual parameters:
| Parameter | Description |
|-----------|-------------|
| **Topic focus** | Prebias the discussion toward a specific domain or question |
| **Additional personas** | Inject expert agents into the roster at runtime for specialized perspectives |
| **Participation constraints** | Limit which agents can contribute based on relevance |
### Example
A medical module workflow could invoke Party Mode with expert doctor personas added to the roster, and the conversation pre-focused on a specific diagnosis or treatment decision. The agents would then discuss the medical case with appropriate domain expertise while maintaining their distinct personalities and perspectives.

21
docs/web-bundles-gemini-gpt-guide.md
View File

@ -1,21 +0,0 @@
# Using BMad Web Bundles in Gemini Gems & Custom GPTs
## IMPORTANT NOTE
The Web Bundling Feature is being rebuilt from the ground up, current bundles found for v6 may be incomplete or missing functionality and are not optimized.
## 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 Are Web Bundles?
Web bundles are standalone files containing:
- Complete agent persona and instructions
- All workflows and dependencies
- Interactive menu system
- Party mode for multi-agent collaboration
- No external files required
**Perfect for:** Uploading a single file to a Gemini GEM or Custom GPT to use BMad Method from the Web, generally at a huge cost savings, at the expense of some quality and convenience of using locally.

4
package-lock.json generated
View File

@ -1,12 +1,12 @@
{
"name": "bmad-method",
"version": "6.0.0-alpha.20",
"version": "6.0.0-alpha.22",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bmad-method",
"version": "6.0.0-alpha.20",
"version": "6.0.0-alpha.22",
"license": "MIT",
"dependencies": {
"@kayvan/markdown-tree-parser": "^1.6.1",

2
samples/sample-custom-modules/README.md
View File

@ -4,7 +4,7 @@ These are quickly put together examples of both a stand alone somewhat cohesive
To try these out, download either or both folders to your local machine, and run the normal bmad installer, and when asked about custom local content, say yes, and give the path to one of these two folders. You can even install both with other regular modules to the same project.
Note - a project is just a folder with \_bmad in the folder - this can be a software project, but it can also be any type of folder on your local computer - such as a markdown notebook, a folder of other files, or just a folder you maintain with useful agents prompts and utilities for any purpose.
Note - a project is just a folder with `_bmad` in the folder - this can be a software project, but it can also be any type of folder on your local computer - such as a markdown notebook, a folder of other files, or just a folder you maintain with useful agents prompts and utilities for any purpose.
Please remember - these are not optimal or very good examples in their utility or quality control - but they do demonstrate the basics of creating custom content and modules to be able to install for yourself or share with others. This is the groundwork for making very complex modules also such as the full bmad method.

1
samples/sample-custom-modules/sample-unitary-module/agents/commit-poet/commit-poet.agent.yaml
View File

@ -5,6 +5,7 @@ agent:
title: "Commit Message Artisan"
icon: "📜"
module: stand-alone
hasSidecar: false
persona:
role: |

1
samples/sample-custom-modules/sample-wellness-module/agents/meditation-guide.agent.yaml
View File

@ -5,6 +5,7 @@ agent:
title: "Meditation Guide"
icon: "🧘"
module: "mwm"
hasSidecar: false
persona:
role: "Mindfulness and meditation specialist"
identity: |

1
src/core/agents/bmad-master.agent.yaml
View File

@ -7,6 +7,7 @@ agent:
name: "BMad Master"
title: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
icon: "🧙"
hasSidecar: false
persona:
role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"

0
src/core/tools/shard-doc.xml → src/core/tasks/shard-doc.xml
View File

2
src/core/tasks/workflow.xml
View File

@ -74,7 +74,7 @@
<action>Display generated content</action>
<ask> [a] Advanced Elicitation, [c] Continue, [p] Party-Mode, [y] YOLO the rest of this document only. WAIT for response. <if
response="a">
<action>Start the advanced elicitation workflow {project-root}/_bmad/core/tasks/advanced-elicitation.xml</action>
<action>Start the advanced elicitation workflow {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml</action>
</if>
<if
response="c">

0
src/core/tasks/advanced-elicitation-methods.csv → src/core/workflows/advanced-elicitation/methods.csv
View File

5
src/core/tasks/advanced-elicitation.xml → src/core/workflows/advanced-elicitation/workflow.xml
View File

@ -1,5 +1,5 @@
<task id="_bmad/core/tasks/advanced-elicitation.xml" name="Advanced Elicitation" standalone="true"
methods="{project-root}/_bmad/core/tasks/advanced-elicitation-methods.csv"
<task id="_bmad/core/workflows/advanced-elicitation/workflow.xml" name="Advanced Elicitation" standalone="true"
methods="{project-root}/_bmad/core/workflows/advanced-elicitation/methods.csv"
agent-party="{project-root}/_bmad/_config/agent-manifest.csv">
<llm critical="true">
<i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
@ -7,6 +7,7 @@
<i>HALT immediately when halt-conditions are met</i>
<i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
<i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
<i>YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`</i>
</llm>
<integration description="When called from workflow">

1
src/core/workflows/brainstorming/steps/step-01-session-setup.md
View File

@ -7,6 +7,7 @@
- 📋 YOU ARE A FACILITATOR, not a content generator
- 💬 FOCUS on session setup and continuation detection only
- 🚪 DETECT existing workflow state and handle continuation properly
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
## EXECUTION PROTOCOLS:

1
src/core/workflows/brainstorming/steps/step-01b-continue.md
View File

@ -7,6 +7,7 @@
- 📋 UNDERSTAND PREVIOUS SESSION context and outcomes
- 🔍 SEAMLESSLY RESUME from where user left off
- 💬 MAINTAIN CONTINUITY in session flow and rapport
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
## EXECUTION PROTOCOLS:

1
src/core/workflows/brainstorming/steps/step-02a-user-selected.md
View File

@ -7,6 +7,7 @@
- 📋 PREVIEW TECHNIQUE OPTIONS clearly and concisely
- 🔍 LET USER EXPLORE and select based on their interests
- 💬 PROVIDE BACK OPTION to return to approach selection
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
## EXECUTION PROTOCOLS:

1
src/core/workflows/brainstorming/steps/step-02b-ai-recommended.md
View File

@ -7,6 +7,7 @@
- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv for recommendations
- 🔍 MATCH TECHNIQUES to user goals, constraints, and preferences
- 💬 PROVIDE CLEAR RATIONALE for each recommendation
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
## EXECUTION PROTOCOLS:

1
src/core/workflows/brainstorming/steps/step-02c-random-selection.md
View File

@ -7,6 +7,7 @@
- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv
- 🔍 CREATE EXCITEMENT around unexpected creative methods
- 💬 EMPHASIZE DISCOVERY over predictable outcomes
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
## EXECUTION PROTOCOLS:

1
src/core/workflows/brainstorming/steps/step-02d-progressive-flow.md
View File

@ -7,6 +7,7 @@
- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv for each phase
- 🔍 MATCH TECHNIQUES to natural creative progression stages
- 💬 CREATE CLEAR JOURNEY MAP with phase transitions
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
## EXECUTION PROTOCOLS:

1
src/core/workflows/brainstorming/steps/step-03-technique-execution.md
View File

@ -7,6 +7,7 @@
- 📋 RESPOND DYNAMICALLY to user insights and build upon their ideas
- 🔍 ADAPT FACILITATION based on user engagement and emerging directions
- 💬 CREATE TRUE COLLABORATION, not question-answer sequences
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
## EXECUTION PROTOCOLS:

1
src/core/workflows/brainstorming/steps/step-04-idea-organization.md
View File

@ -7,6 +7,7 @@
- 📋 CREATE ACTIONABLE NEXT STEPS from brainstorming outcomes
- 🔍 FACILITATE CONVERGENT THINKING after divergent exploration
- 💬 DELIVER COMPREHENSIVE SESSION DOCUMENTATION
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
## EXECUTION PROTOCOLS:

2
src/core/workflows/brainstorming/workflow.md
View File

@ -8,7 +8,7 @@ context_file: '' # Optional context file path for project-specific guidance
**Goal:** Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods
**Your Role:** You are a brainstorming facilitator and creative thinking guide. You bring structured creativity techniques, facilitation expertise, and an understanding of how to guide users through effective ideation processes that generate innovative ideas and breakthrough solutions.
**Your Role:** You are a brainstorming facilitator and creative thinking guide. You bring structured creativity techniques, facilitation expertise, and an understanding of how to guide users through effective ideation processes that generate innovative ideas and breakthrough solutions. During this entire workflow it is critical that you speak to the user in the config loaded `communication_language`.
---

1
src/core/workflows/party-mode/steps/step-01-agent-loading.md
View File

@ -7,6 +7,7 @@
- 📋 LOAD COMPLETE AGENT ROSTER from manifest with merged personalities
- 🔍 PARSE AGENT DATA for conversation orchestration
- 💬 INTRODUCE DIVERSE AGENT SAMPLE to kick off discussion
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
## EXECUTION PROTOCOLS:

1
src/core/workflows/party-mode/steps/step-02-discussion-orchestration.md
View File

@ -7,6 +7,7 @@
- 📋 MAINTAIN CHARACTER CONSISTENCY using merged agent personalities
- 🔍 ENABLE NATURAL CROSS-TALK between agents for dynamic conversation
- 💬 INTEGRATE TTS for each agent response immediately after text
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
## EXECUTION PROTOCOLS:

1
src/core/workflows/party-mode/steps/step-03-graceful-exit.md
View File

@ -7,6 +7,7 @@
- 📋 EXPRESS GRATITUDE to user for collaborative participation
- 🔍 ACKNOWLEDGE SESSION HIGHLIGHTS and key insights gained
- 💬 MAINTAIN POSITIVE ATMOSPHERE until the very end
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
## EXECUTION PROTOCOLS:

2
src/core/workflows/party-mode/workflow.md
View File

@ -7,7 +7,7 @@ description: Orchestrates group discussions between all installed BMAD agents, e
**Goal:** Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations
**Your Role:** You are a party mode facilitator and multi-agent conversation orchestrator. You bring together diverse BMAD agents for collaborative discussions, managing the flow of conversation while maintaining each agent's unique personality and expertise.
**Your Role:** You are a party mode facilitator and multi-agent conversation orchestrator. You bring together diverse BMAD agents for collaborative discussions, managing the flow of conversation while maintaining each agent's unique personality and expertise - while still utilizing the configured {communication_language}.
---

9
src/modules/bmb/agents/agent-builder.agent.yaml
View File

@ -9,6 +9,7 @@ agent:
title: Agent Building Expert
icon: 🤖
module: bmb
hasSidecar: false
persona:
role: Agent Architecture Specialist + BMAD Compliance Expert
@ -28,9 +29,13 @@ agent:
menu:
- trigger: CA or fuzzy match on create-agent
exec: "{project-root}/_bmad/bmb/workflows/create-agent/workflow.md"
exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md"
description: "[CA] Create a new BMAD agent with best practices and compliance"
- trigger: EA or fuzzy match on edit-agent
exec: "{project-root}/_bmad/bmb/workflows/edit-agent/workflow.md"
exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md"
description: "[EA] Edit existing BMAD agents while maintaining compliance"
- trigger: VA or fuzzy match on validate-agent
exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md"
description: "[VA] Validate existing BMAD agents and offer to improve deficiencies"

1
src/modules/bmb/agents/module-builder.agent.yaml
View File

@ -9,6 +9,7 @@ agent:
title: Module Creation Master
icon: 🏗️
module: bmb
hasSidecar: false
persona:
role: Module Architecture Specialist + Full-Stack Systems Designer

1
src/modules/bmb/agents/workflow-builder.agent.yaml
View File

@ -9,6 +9,7 @@ agent:
title: Workflow Building Master
icon: 🔄
module: bmb
hasSidecar: false
persona:
role: Workflow Architecture Specialist + Process Design Expert

340
src/modules/bmb/docs/agents/agent-compilation.md
View File

@ -1,340 +0,0 @@
# Agent Compilation: YAML to XML
What the compiler auto-injects. **DO NOT duplicate these in your YAML.**
## Compilation Pipeline
```
agent.yaml → Handlebars processing → XML generation → frontmatter.md
```
Source: `tools/cli/lib/agent/compiler.js`
## File Naming Convention
**CRITICAL:** Agent filenames must be ROLE-BASED, not persona-based.
**Why:** Users can customize the agent's persona name via `customize.yaml` config. The filename provides stable identity.
**Correct:**
```
presentation-master.agent.yaml ← Role/function
tech-writer.agent.yaml ← Role/function
code-reviewer.agent.yaml ← Role/function
```
**Incorrect:**
```
caravaggio.agent.yaml ← Persona name (users might rename to "Pablo")
paige.agent.yaml ← Persona name (users might rename to "Sarah")
rex.agent.yaml ← Persona name (users might rename to "Max")
```
**Pattern:**
- Filename: `{role-or-function}.agent.yaml` (kebab-case)
- Metadata ID: `_bmad/{module}/agents/{role-or-function}.md`
- Persona Name: User-customizable in metadata or customize.yaml
**Example:**
```yaml
# File: presentation-master.agent.yaml
agent:
metadata:
id: '_bmad/cis/agents/presentation-master.md'
name: Caravaggio # ← Users can change this to "Pablo" or "Vince"
title: Visual Communication & Presentation Expert
```
## Auto-Injected Components
### 1. Frontmatter
**Injected automatically:**
```yaml
---
name: '{agent name from filename}'
description: '{title from metadata}'
---
You must fully embody this agent's persona...
```
**DO NOT add** frontmatter to your YAML source.
### 2. Activation Block
**Entire activation section is auto-generated:**
```xml
<activation critical="MANDATORY">
<step n="1">Load persona from this current agent file</step>
<step n="2">Load config to get {user_name}, {communication_language}</step>
<step n="3">Remember: user's name is {user_name}</step>
<!-- YOUR critical_actions inserted here as numbered steps -->
<step n="N">ALWAYS communicate in {communication_language}</step>
<step n="N+1">Show greeting + numbered menu</step>
<step n="N+2">STOP and WAIT for user input</step>
<step n="N+3">Input resolution rules</step>
<menu-handlers>
<!-- Only handler instructions for the handler types used in the agents specific menu are included -->
</menu-handlers>
<rules>
<!-- Standard agent behavior rules -->
</rules>
</activation>
```
**DO NOT create** activation sections - compiler builds it from your critical_actions.
### 3. Menu Enhancements
**Auto-injected menu items:**
- `*help` - Always FIRST in compiled menu
- `*exit` - Always LAST in compiled menu
**Trigger prefixing:**
- Your trigger `analyze` becomes `*analyze`
- Don't add `*` prefix - compiler does it
**DO NOT include:**
```yaml
# BAD - these are auto-injected
menu:
- trigger: help
description: 'Show help'
- trigger: exit
description: 'Exit'
```
### 4. Menu Handlers
Compiler detects which handlers you use and ONLY includes those:
```xml
<menu-handlers>
<handlers>
<!-- Only if you use action="#id" or action="text" -->
<handler type="action">...</handler>
<!-- Only if you use workflow="path" -->
<handler type="workflow">...</handler>
<!-- Only if you use exec="path" -->
<handler type="exec">...</handler>
<!-- Only if you use tmpl="path" -->
<handler type="tmpl">...</handler>
</handlers>
</menu-handlers>
```
**DO NOT document** handler behavior - it's injected.
### 5. Rules Section
**Auto-injected rules:**
- Always communicate in {communication_language}
- Stay in character until exit
- Menu triggers use asterisk (\*) - NOT markdown
- Number all lists, use letters for sub-options
- Load files ONLY when executing menu items
- Written output follows communication style
**DO NOT add** rules - compiler handles it.
## What YOU Provide in YAML
### Required
```yaml
agent:
metadata:
name: 'Persona Name'
title: 'Agent Title'
icon: 'emoji'
type: 'simple|expert' # or module: "bmm"
persona:
role: '...'
identity: '...'
communication_style: '...'
principles: [...]
menu:
- trigger: your-action
action: '#prompt-id'
description: 'What it does'
```
### Optional (based on type)
```yaml
# Expert agents only
critical_actions:
- 'Load sidecar files...'
- 'Restrict access...'
# Simple/Expert with embedded logic
prompts:
- id: prompt-id
content: '...'
# Simple/Expert with customization
install_config:
questions: [...]
```
## Common Duplication Mistakes
### Adding Activation Logic
```yaml
# BAD - compiler builds activation
agent:
activation:
steps: [...]
```
### Including Help/Exit
```yaml
# BAD - auto-injected
menu:
- trigger: help
- trigger: exit
```
### Prefixing Triggers
```yaml
# BAD - compiler adds *
menu:
- trigger: '*analyze' # Should be: analyze
```
### Documenting Handlers
```yaml
# BAD - don't explain handlers, compiler injects them
# When using workflow, load workflow.xml...
```
### Adding Rules in YAML
```yaml
# BAD - rules are auto-injected
agent:
rules:
- Stay in character...
```
## Compilation Example
**Your YAML:**
```yaml
agent:
metadata:
name: 'Rex'
title: 'Code Reviewer'
icon: '🔍'
type: simple
persona:
role: Code Review Expert
identity: Systematic reviewer...
communication_style: Direct and constructive
principles:
- Code should be readable
prompts:
- id: review
content: |
Analyze code for issues...
menu:
- trigger: review
action: '#review'
description: 'Review code'
```
**Compiled Output (.md):**
```markdown
---
name: 'rex'
description: 'Code Reviewer'
---
You must fully embody...
\`\`\`xml
<agent id="path" name="Rex" title="Code Reviewer" icon="🔍">
<activation critical="MANDATORY">
<step n="1">Load persona...</step>
<step n="2">Load config...</step>
<step n="3">Remember user...</step>
<step n="4">Communicate in language...</step>
<step n="5">Show greeting + menu...</step>
<step n="6">STOP and WAIT...</step>
<step n="7">Input resolution...</step>
<menu-handlers>
<handlers>
<handler type="action">
action="#id" → Find prompt, execute
action="text" → Execute directly
</handler>
</handlers>
</menu-handlers>
<rules>
- Stay in character...
- Number lists...
- Load files when executing...
</rules>
</activation>
<persona>
<role>Code Review Expert</role>
<identity>Systematic reviewer...</identity>
<communication_style>Direct and constructive</communication_style>
<principles>Code should be readable</principles>
</persona>
<prompts>
<prompt id="review">
<content>
Analyze code for issues...
</content>
</prompt>
</prompts>
<menu>
<item cmd="*help">Show numbered menu</item>
<item cmd="*review" action="#review">Review code</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
</agent>
\`\`\`
```
## Key Takeaways
1. **Compiler handles boilerplate** - Focus on persona and logic
2. **Critical_actions become activation steps** - Just list your agent-specific needs
3. **Menu items are enhanced** - Help/exit added, triggers prefixed
4. **Handlers auto-detected** - Only what you use is included
5. **Rules standardized** - Consistent behavior across agents
**Your job:** Define persona, prompts, menu actions
**Compiler's job:** Activation, handlers, rules, help/exit, prefixes

523
src/modules/bmb/docs/agents/agent-menu-patterns.md
View File

@ -1,523 +0,0 @@
# BMAD Agent Menu Patterns
Design patterns for agent menus in YAML source files.
## Menu Structure
Agents define menus in YAML, with triggers auto-prefixed with `*` during compilation:
```yaml
menu:
- trigger: action-name
[handler]: [value]
description: 'What this command does'
```
**Note:** `*help` and `*exit` are auto-injected by the compiler - DO NOT include them.
## Handler Types
### 1. Action Handler (Prompts & Inline)
For simple and expert agents with self-contained logic.
**Reference to Prompt ID:**
```yaml
prompts:
- id: analyze-code
content: |
<instructions>
Analyze the provided code for patterns and issues.
</instructions>
<process>
1. Identify code structure
2. Check for anti-patterns
3. Suggest improvements
</process>
menu:
- trigger: analyze
action: '#analyze-code'
description: 'Analyze code patterns'
```
**Inline Instruction:**
```yaml
menu:
- trigger: quick-check
action: 'Perform a quick syntax validation on the current file'
description: 'Quick syntax check'
```
**When to Use:**
- Simple/Expert agents with self-contained operations
- `#id` for complex, multi-step prompts
- Inline text for simple, one-line instructions
### 2. Workflow Handler
For module agents orchestrating multi-step processes.
```yaml
menu:
- trigger: create-prd
workflow: '{project-root}/_bmad/bmm/workflows/prd/workflow.yaml'
description: 'Create Product Requirements Document'
- trigger: brainstorm
workflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
description: 'Guided brainstorming session'
# Placeholder for unimplemented workflows
- trigger: future-feature
workflow: 'todo'
description: 'Coming soon'
```
**When to Use:**
- Module agents with workflow integration
- Multi-step document generation
- Complex interactive processes
- Use "todo" for planned but unimplemented features
### 3. Exec Handler
For executing tasks directly.
```yaml
menu:
- trigger: validate
exec: '{project-root}/_bmad/core/tasks/validate-workflow.xml'
description: 'Validate document structure'
- trigger: advanced-elicitation
exec: '{project-root}/_bmad/core/tasks/advanced-elicitation.xml'
description: 'Advanced elicitation techniques'
```
**When to Use:**
- Single-operation tasks
- Core system operations
- Utility functions
### 4. Template Handler
For document generation with templates.
```yaml
menu:
- trigger: create-brief
exec: '{project-root}/_bmad/core/tasks/create-doc.xml'
tmpl: '{project-root}/_bmad/bmm/templates/brief.md'
description: 'Create a Product Brief'
```
**When to Use:**
- Template-based document creation
- Combine `exec` with `tmpl` path
- Structured output generation
### 5. Data Handler
Universal attribute for supplementary information.
```yaml
menu:
- trigger: team-standup
exec: '{project-root}/_bmad/bmm/tasks/standup.xml'
data: '{project-root}/_bmad/_config/agent-manifest.csv'
description: 'Run team standup'
- trigger: analyze-metrics
action: 'Analyze these metrics and identify trends'
data: '{project-root}/_data/metrics.json'
description: 'Analyze performance metrics'
```
**When to Use:**
- Add to ANY handler type
- Reference data files (CSV, JSON, YAML)
- Provide context for operations
## Platform-Specific Menus
Control visibility based on deployment target:
```yaml
menu:
- trigger: git-flow
exec: '{project-root}/_bmad/bmm/tasks/git-flow.xml'
description: 'Git workflow operations'
ide-only: true # Only in IDE environments
- trigger: advanced-elicitation
exec: '{project-root}/_bmad/core/tasks/advanced-elicitation.xml'
description: 'Advanced elicitation'
web-only: true # Only in web bundles
```
## Trigger Naming Conventions
### Action-Based (Recommended)
```yaml
# Creation
- trigger: create-prd
- trigger: build-module
- trigger: generate-report
# Analysis
- trigger: analyze-requirements
- trigger: review-code
- trigger: validate-architecture
# Operations
- trigger: update-status
- trigger: sync-data
- trigger: deploy-changes
```
### Domain-Based
```yaml
# Development
- trigger: brainstorm
- trigger: architect
- trigger: refactor
# Project Management
- trigger: sprint-plan
- trigger: retrospective
- trigger: standup
```
### Bad Patterns
```yaml
# TOO VAGUE
- trigger: do
- trigger: run
- trigger: process
# TOO LONG
- trigger: create-comprehensive-product-requirements-document
# NO VERB
- trigger: prd
- trigger: config
```
## Menu Organization
### Recommended Order
```yaml
menu:
# Note: *help auto-injected first by compiler
# 1. Primary workflows (main value)
- trigger: workflow-init
workflow: '...'
description: 'Start here - initialize workflow'
- trigger: create-prd
workflow: '...'
description: 'Create PRD'
# 2. Secondary operations
- trigger: validate
exec: '...'
description: 'Validate document'
# 3. Utilities
- trigger: party-mode
workflow: '...'
description: 'Multi-agent discussion'
# Note: *exit auto-injected last by compiler
```
### Grouping by Phase
```yaml
menu:
# Analysis Phase
- trigger: brainstorm
workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
description: 'Brainstorm ideas'
- trigger: research
workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow.yaml'
description: 'Conduct research'
# Planning Phase
- trigger: prd
workflow: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.yaml'
description: 'Create PRD'
- trigger: architecture
workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
description: 'Design architecture'
```
## Description Best Practices
### Good Descriptions
```yaml
# Clear action + object
- description: 'Create Product Requirements Document'
# Specific outcome
- description: 'Analyze security vulnerabilities'
# User benefit
- description: 'Optimize code for performance'
# Context when needed
- description: 'Start here - initialize workflow path'
```
### Poor Descriptions
```yaml
# Too vague
- description: 'Process'
# Technical jargon
- description: 'Execute WF123'
# Missing context
- description: 'Run'
# Redundant with trigger
- description: 'Create PRD' # trigger: create-prd (too similar)
```
## Prompts Section (Simple/Expert Agents)
### Prompt Structure
```yaml
prompts:
- id: unique-identifier
content: |
<instructions>
What this prompt accomplishes
</instructions>
<process>
1. First step
{{#if custom_option}}
2. Conditional step
{{/if}}
3. Final step
</process>
<output_format>
Expected structure of results
</output_format>
```
### Semantic XML Tags in Prompts
Use XML tags to structure prompt content:
- `<instructions>` - What to do
- `<process>` - Step-by-step approach
- `<output_format>` - Expected results
- `<examples>` - Sample outputs
- `<constraints>` - Limitations
- `<context>` - Background information
### Handlebars in Prompts
Customize based on install_config:
```yaml
prompts:
- id: analyze
content: |
{{#if detailed_mode}}
Perform comprehensive analysis with full explanations.
{{/if}}
{{#unless detailed_mode}}
Quick analysis focusing on key points.
{{/unless}}
Address {{user_name}} in {{communication_style}} tone.
```
## Path Variables
### Always Use Variables
```yaml
# GOOD - Portable paths
workflow: "{project-root}/_bmad/bmm/workflows/prd/workflow.yaml"
exec: "{project-root}/_bmad/core/tasks/validate.xml"
data: "{project-root}/_data/metrics.csv"
# BAD - Hardcoded paths
workflow: "/Users/john/project/_bmad/bmm/workflows/prd/workflow.yaml"
exec: "../../../core/tasks/validate.xml"
```
### Available Variables
- `{project-root}` - Project root directory
- `_bmad` - BMAD installation folder
- `{output_folder}` - Document output location
- `{user_name}` - User's name from config
- `{communication_language}` - Language preference
## Complete Examples
### Simple Agent Menu
```yaml
prompts:
- id: format-code
content: |
<instructions>
Format the provided code according to style guidelines.
</instructions>
Apply:
- Consistent indentation
- Proper spacing
- Clear naming conventions
menu:
- trigger: format
action: '#format-code'
description: 'Format code to style guidelines'
- trigger: lint
action: 'Check code for common issues and anti-patterns'
description: 'Lint code for issues'
- trigger: suggest
action: 'Suggest improvements for code readability'
description: 'Suggest improvements'
```
### Expert Agent Menu
```yaml
critical_actions:
- 'Load ./memories.md'
- 'Follow ./instructions.md'
- 'ONLY access ./'
prompts:
- id: reflect
content: |
Guide {{user_name}} through reflection on recent entries.
Reference patterns from memories.md naturally.
menu:
- trigger: write
action: '#reflect'
description: 'Write journal entry'
- trigger: save
action: 'Update ./memories.md with session insights'
description: "Save today's session"
- trigger: patterns
action: 'Analyze recent entries for recurring themes'
description: 'View patterns'
```
### Module Agent Menu
```yaml
menu:
- trigger: workflow-init
workflow: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.yaml'
description: 'Initialize workflow path (START HERE)'
- trigger: brainstorm
workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
description: 'Guided brainstorming'
- trigger: prd
workflow: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.yaml'
description: 'Create PRD'
- trigger: architecture
workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
description: 'Design architecture'
- trigger: party-mode
workflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.yaml'
description: 'Multi-agent discussion'
```
## Validation Checklist
- [ ] No duplicate triggers
- [ ] Triggers don't start with `*` (auto-added)
- [ ] Every item has a description
- [ ] Paths use variables, not hardcoded
- [ ] `#id` references exist in prompts section
- [ ] Workflow paths resolve or are "todo"
- [ ] No `*help` or `*exit` (auto-injected)
- [ ] Descriptions are clear and action-oriented
- [ ] Platform-specific flags used correctly (ide-only, web-only)
## Common Mistakes
### Duplicate Triggers
```yaml
# BAD - compiler will fail
- trigger: analyze
action: '#first'
description: 'First analysis'
- trigger: analyze
action: '#second'
description: 'Second analysis'
```
### Including Auto-Injected Items
```yaml
# BAD - these are auto-injected
menu:
- trigger: help
description: 'Show help'
- trigger: exit
description: 'Exit agent'
```
### Missing Prompt Reference
```yaml
# BAD - prompt id doesn't exist
menu:
- trigger: analyze
action: '#nonexistent-prompt'
description: 'Analysis'
```
### Hardcoded Paths
```yaml
# BAD - not portable
menu:
- trigger: run
workflow: '/absolute/path/to/workflow.yaml'
description: 'Run workflow'
```

363
src/modules/bmb/docs/agents/expert-agent-architecture.md
View File

@ -1,363 +0,0 @@
# Expert Agent Architecture
Domain-specific agents with persistent memory, sidecar files, and restricted access patterns.
## When to Use
- Personal assistants (journal keeper, diary companion)
- Specialized domain experts (legal advisor, medical reference)
- Agents that need to remember past interactions
- Agents with restricted file system access (privacy/security)
- Long-term relationship agents that learn about users
## File Structure
```
{agent-name}/
├── {agent-name}.agent.yaml # Main agent definition
└── {agent-name}-sidecar/ # Supporting files
├── instructions.md # Private directives
├── memories.md # Persistent memory
├── knowledge/ # Domain-specific resources
│ └── README.md
└── [custom files] # Agent-specific resources
```
## YAML Structure
```yaml
agent:
metadata:
name: 'Persona Name'
title: 'Agent Title'
icon: 'emoji'
type: 'expert'
persona:
role: 'Domain Expert with specialized capability'
identity: |
Background and expertise in first-person voice.
{{#if user_preference}}
Customization based on install_config.
{{/if}}
communication_style: |
{{#if tone_style == "gentle"}}
Gentle and supportive communication...
{{/if}}
{{#if tone_style == "direct"}}
Direct and efficient communication...
{{/if}}
I reference past conversations naturally.
principles:
- Core belief about the domain
- How I handle user information
- My approach to memory and learning
critical_actions:
- 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights'
- 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols'
- 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space'
- 'Address user as {{greeting_name}}'
- 'Track patterns, themes, and important moments'
- 'Reference past interactions naturally to show continuity'
prompts:
- id: main-function
content: |
<instructions>
Guide user through the primary function.
{{#if tone_style == "gentle"}}
Use gentle, supportive approach.
{{/if}}
</instructions>
<process>
1. Understand context
2. Provide guidance
3. Record insights
</process>
- id: memory-recall
content: |
<instructions>
Access and share relevant memories.
</instructions>
Reference stored information naturally.
menu:
- trigger: action1
action: '#main-function'
description: 'Primary agent function'
- trigger: remember
action: 'Update ./{agent-name}-sidecar/memories.md with session insights'
description: 'Save what we discussed today'
- trigger: insight
action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md'
description: 'Record a significant insight'
- multi: "[DF] Do Foo or start [CH] Chat with expert"
triggers:
- do-foo
- input: [DF] or fuzzy match on do foo
- action: '#main-action'
- data: what is being discussed or suggested with the command, along with custom party custom agents if specified
- type: action
- expert-chat:
- input: [CH] or fuzzy match validate agent
- action: agent responds as expert based on its persona to converse
- type: action
install_config:
compile_time_only: true
description: 'Personalize your expert agent'
questions:
- var: greeting_name
prompt: 'What should the agent call you?'
type: text
default: 'friend'
- var: tone_style
prompt: 'Preferred communication tone?'
type: choice
options:
- label: 'Gentle - Supportive and nurturing'
value: 'gentle'
- label: 'Direct - Clear and efficient'
value: 'direct'
default: 'gentle'
- var: user_preference
prompt: 'Enable personalized features?'
type: boolean
default: true
```
## Key Components
### Sidecar Files (CRITICAL)
Expert agents use companion files for persistence and domain knowledge:
**memories.md** - Persistent user context
```markdown
# Agent Memory Bank
## User Preferences
<!-- Learned from interactions -->
## Session History
<!-- Important moments and insights -->
## Personal Notes
<!-- Agent observations -->
```
**instructions.md** - Private directives
```markdown
# Agent Private Instructions
## Core Directives
- Maintain character consistency
- Domain boundaries: {specific domain}
- Access restrictions: Only sidecar folder
## Special Rules
<!-- Agent-specific protocols -->
```
**knowledge/** - Domain resources
```markdown
# Agent Knowledge Base
Add domain-specific documentation here.
```
### Critical Actions
**MANDATORY for expert agents** - These load sidecar files at activation:
```yaml
critical_actions:
- 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights'
- 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols'
- 'ONLY read/write files in ./{sidecar}/ - this is our private space'
```
**Key patterns:**
- **COMPLETE file loading** - Forces full file read, not partial
- **Domain restrictions** - Limits file access for privacy/security
- **Memory integration** - Past context becomes part of current session
- **Protocol adherence** - Ensures consistent behavior
## What Gets Injected at Compile Time
Same as simple agents, PLUS:
1. **Critical actions become numbered activation steps**
```xml
<step n="4">Load COMPLETE file ./memories.md...</step>
<step n="5">Load COMPLETE file ./instructions.md...</step>
<step n="6">ONLY read/write files in ./...</step>
```
2. **Sidecar files copied during installation**
- Entire sidecar folder structure preserved
- Relative paths maintained
- Files ready for agent use
## Reference Example
See: [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper)
Features demonstrated:
- Complete sidecar structure (memories, instructions, breakthroughs)
- Critical actions for loading persistent context
- Domain restrictions for privacy
- Pattern recognition and memory recall
- Handlebars-based personalization
- Menu actions that update sidecar files
## Installation
```bash
# Copy entire folder to your project
cp -r /path/to/journal-keeper/ _bmad/custom/agents/
# Install with personalization
bmad agent-install
```
The installer:
1. Detects expert agent (folder with .agent.yaml)
2. Prompts for personalization
3. Compiles agent YAML to XML-in-markdown
4. **Copies sidecar files to installation target**
5. Creates IDE slash commands
6. Saves source for reinstallation
## Memory Patterns
### Accumulative Memory
```yaml
menu:
- trigger: save
action: "Update ./sidecar/memories.md with today's session insights"
description: 'Save session to memory'
```
### Reference Memory
```yaml
prompts:
- id: recall
content: |
<instructions>
Reference memories.md naturally:
"Last week you mentioned..." or "I notice a pattern..."
</instructions>
```
### Structured Insights
```yaml
menu:
- trigger: insight
action: 'Document in ./sidecar/breakthroughs.md with date, context, significance'
description: 'Record meaningful insight'
```
## Domain Restriction Patterns
### Single Folder Access
```yaml
critical_actions:
- 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS'
```
### User Space Access
```yaml
critical_actions:
- 'ONLY access files in {user-folder}/journals/ - private space'
```
### Read-Only Access
```yaml
critical_actions:
- 'Load knowledge from ./knowledge/ but NEVER modify'
- 'Write ONLY to ./sessions/'
```
## Best Practices
1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
2. **Enforce domain restrictions** - Clear boundaries prevent scope creep=
3. **Design for memory growth** - Structure sidecar files for accumulation
4. **Reference past naturally** - Don't dump memory, weave it into conversation
5. **Separate concerns** - Memories, instructions, knowledge in distinct files
6. **Include privacy features** - Users trust expert agents with personal data
## Common Patterns
### Session Continuity
```yaml
communication_style: |
I reference past conversations naturally:
"Last time we discussed..." or "I've noticed over the weeks..."
```
### Pattern Recognition
```yaml
critical_actions:
- 'Track mood patterns, recurring themes, and breakthrough moments'
- 'Cross-reference current session with historical patterns'
```
### Adaptive Responses
```yaml
identity: |
I learn your preferences and adapt my approach over time.
{{#if track_preferences}}
I maintain notes about what works best for you.
{{/if}}
```
## Validation Checklist
- [ ] Valid YAML syntax
- [ ] Metadata includes `type: "expert"`
- [ ] critical_actions loads sidecar files explicitly
- [ ] critical_actions enforces domain restrictions
- [ ] Sidecar folder structure created and populated
- [ ] memories.md has clear section structure
- [ ] instructions.md contains core directives
- [ ] Menu actions reference _bmad/_memory correctly
- [ ] File paths use _bmad/_memory/[agentname]-sidecar/ to reference sidecar content
- [ ] Install config personalizes sidecar references
- [ ] Agent folder named consistently: `{agent-name}/`
- [ ] YAML file named: `{agent-name}.agent.yaml`
- [ ] Sidecar folder named: `{agent-name}-sidecar/`

0
src/modules/bmb/docs/agents/kb.csv
View File

257
src/modules/bmb/docs/agents/simple-agent-architecture.md
View File

@ -1,257 +0,0 @@
# Simple Agent Architecture
Self-contained agents with prompts, menus, and optional install-time customization.
## When to Use
- Single-purpose utilities (commit message generator, code formatter)
- Self-contained logic with no external dependencies
- Agents that benefit from user customization (style, tone, preferences)
- Quick-to-build standalone helpers
## YAML Structure
```yaml
agent:
metadata:
id: _bmad/agents/{agent-name}/{agent-name}.md
name: 'Persona Name'
title: 'Agent Title'
icon: 'emoji'
type: simple
persona:
role: |
First-person description of primary function (1-2 sentences)
identity: |
Background, experience, specializations in first-person (2-5 sentences)
{{#if custom_variable}}
Conditional identity text based on install_config
{{/if}}
communication_style: |
{{#if style_choice == "professional"}}
Professional and systematic approach...
{{/if}}
{{#if style_choice == "casual"}}
Friendly and approachable tone...
{{/if}}
principles:
- Core belief or methodology
- Another guiding principle
- Values that shape decisions
prompts:
- id: main-action
content: |
<instructions>
What this prompt does
</instructions>
<process>
1. Step one
{{#if detailed_mode}}
2. Additional detailed step
{{/if}}
3. Final step
</process>
- id: another-action
content: |
Another reusable prompt template
menu:
- trigger: inline
action: 'Direct inline prompt text'
description: 'Execute inline action'
- multi: "[DF] Do Foo or start [CH] Chat with expert"
triggers:
- do-foo
- input: [DF] or fuzzy match on do foo
- action: '#main-action'
- data: what is being discussed or suggested with the command, along with custom party custom agents if specified
- type: action
- expert-chat:
- input: [CH] or fuzzy match validate agent
- action: agent responds as expert based on its persona to converse
- type: action
install_config:
compile_time_only: true
description: 'Personalize your agent'
questions:
- var: style_choice
prompt: 'Preferred communication style?'
type: choice
options:
- label: 'Professional'
value: 'professional'
- label: 'Casual'
value: 'casual'
default: 'professional'
- var: detailed_mode
prompt: 'Enable detailed explanations?'
type: boolean
default: true
- var: custom_variable
prompt: 'Your custom text'
type: text
default: ''
```
## Key Components
### Metadata
- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone)
- **name**: Agent's persona name displayed to users
- **title**: Professional role/function
- **icon**: Single emoji for visual identification
- **type**: `simple` - identifies agent category
### Persona (First-Person Voice)
- **role**: Primary expertise in 1-2 sentences
- **identity**: Background and specializations (2-5 sentences)
- **communication_style**: HOW the agent interacts, including conditional variations
- **principles**: Array of core beliefs (start with action verbs)
### Prompts with IDs
Reusable prompt templates referenced by `#id`:
```yaml
prompts:
- id: analyze-code
content: |
<instructions>
Analyze the provided code for patterns
</instructions>
```
Menu items reference these:
```yaml
menu:
- trigger: analyze
action: '#analyze-code'
description: 'Analyze code patterns'
```
### Menu Actions
Two forms of action handlers:
1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content
2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly
### Install Config (Compile-Time Customization)
Questions asked during `bmad agent-install`:
**Question Types:**
- `choice` - Multiple choice selection
- `boolean` - Yes/no toggle
- `text` - Free-form text input
**Variables become available in Handlebars:**
```yaml
{{#if variable_name}}
Content when true
{{/if}}
{{#if variable_name == "value"}}
Content when equals value
{{/if}}
{{#unless variable_name}}
Content when false
{{/unless}}
```
## What Gets Injected at Compile Time
The `tools/cli/lib/agent/compiler.js` automatically adds:
1. **YAML Frontmatter**
```yaml
---
name: 'agent name'
description: 'Agent Title'
---
```
2. **Activation Block**
- Load persona step
- Load core config for {user_name}, {communication_language}
- Agent-specific critical_actions as numbered steps
- Menu display and input handling
- Menu handlers (action/workflow/exec/tmpl) based on usage
- Rules section
3. **Auto-Injected Menu Items**
- `*help` always first
- `*exit` always last
4. **Trigger Prefixing**
- Triggers without `*` get it added automatically
## Reference Example
See: [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)
Features demonstrated:
- Handlebars conditionals for style variations
- Multiple prompt templates with semantic XML tags
- Install config with choice, boolean, and text questions
- Menu items using both `#id` references and inline actions
## Installation
```bash
# Copy to your project
cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/
# Create custom.yaml and install
echo "code: my-agent
name: My Agent
default_selected: true" > custom.yaml
npx bmad-method install
# or: bmad install
```
The installer:
1. Prompts for personalization (name, preferences)
2. Processes Handlebars templates with your answers
3. Compiles YAML to XML-in-markdown
4. Creates IDE slash commands
5. Saves source for reinstallation
## Best Practices
1. **Use first-person voice** in all persona elements
2. **Keep prompts focused** - one clear purpose per prompt
3. **Leverage Handlebars** for user customization without code changes
4. **Provide sensible defaults** in install_config
5. **Use semantic XML tags** in prompt content for clarity
6. **Test all conditional paths** before distribution
## Validation Checklist
- [ ] Valid YAML syntax
- [ ] All metadata fields present (id, name, title, icon, type)
- [ ] Persona complete (role, identity, communication_style, principles)
- [ ] Prompts have unique IDs
- [ ] Install config questions have defaults
- [ ] File named `{agent-name}.agent.yaml`

184
src/modules/bmb/docs/agents/understanding-agent-types.md
View File

@ -1,184 +0,0 @@
# Understanding Agent Types: Architecture, Not Capability
**CRITICAL DISTINCTION:** Agent types define **architecture and integration**, NOT capability limits.
ALL agent types can:
- ✓ Write to {output_folder}, {project-root}, or anywhere on system
- ✓ Update artifacts and files
- ✓ Execute bash commands
- ✓ Use core variables (_bmad, {output_folder}, etc.)
- ✓ Have complex prompts and logic
- ✓ Invoke external tools
## What Actually Differs
| Feature | Simple | Expert | Module |
| ---------------------- | ------------- | --------------------- | ------------------ |
| **Self-contained** | ✓ All in YAML | Sidecar files | Sidecar optional |
| **Persistent memory** | ✗ Stateless | ✓ memories.md | ✓ If needed |
| **Knowledge base** | ✗ | ✓ sidecar/knowledge/ | Module/shared |
| **Domain restriction** | ✗ System-wide | ✓ Sidecar only | Optional |
| **Personal workflows** | ✗ | ✓ Sidecar workflows\* | ✗ |
| **Module workflows** | ✗ | ✗ | ✓ Shared workflows |
| **Team integration** | Solo utility | Personal assistant | Team member |
\*Expert agents CAN have personal workflows in sidecar if critical_actions loads workflow engine
## The Same Agent, Three Ways
**Scenario:** Code Generator Agent
### As Simple Agent (Architecture: Self-contained)
```yaml
agent:
metadata:
name: CodeGen
type: simple
prompts:
- id: generate
content: |
Ask user for spec details. Generate code.
Write to {output_folder}/generated/
menu:
- trigger: generate
action: '#generate'
description: Generate code from spec
```
**What it can do:**
- ✓ Writes files to output_folder
- ✓ Full I/O capability
- ✗ No memory of past generations
- ✗ No personal coding style knowledge
**When to choose:** Each run is independent, no need to remember previous sessions.
### As Expert Agent (Architecture: Personal sidecar)
```yaml
agent:
metadata:
name: CodeGen
type: expert
critical_actions:
- Load my coding standards from sidecar/knowledge/
- Load memories from sidecar/memories.md
- RESTRICT: Only operate within sidecar folder
prompts:
- id: generate
content: |
Reference user's coding patterns from knowledge base.
Remember past generations from memories.
Write to sidecar/generated/
```
**What it can do:**
- ✓ Remembers user preferences
- ✓ Personal knowledge base
- ✓ Domain-restricted for safety
- ✓ Learns over time
**When to choose:** Need persistent memory, learning, or domain-specific restrictions.
### As Module Agent (Architecture: Team integration)
```yaml
agent:
metadata:
name: CodeGen
module: bmm
menu:
- trigger: implement-story
workflow: '_bmad/bmm/workflows/dev-story/workflow.yaml'
description: Implement user story
- trigger: refactor
workflow: '_bmad/bmm/workflows/refactor/workflow.yaml'
description: Refactor codebase
```
**What it can do:**
- ✓ Orchestrates full dev workflows
- ✓ Coordinates with other BMM agents
- ✓ Shared team infrastructure
- ✓ Professional operations
**When to choose:** Part of larger system, orchestrates workflows, team coordination.
## Important: Any Agent Can Be Added to a Module
**CLARIFICATION:** The "Module Agent" type is about **design intent and ecosystem integration**, not just file location.
### The Reality
- **Any agent type** (Simple, Expert, Module) can be bundled with or added to a module
- A Simple agent COULD live in `_bmad/bmm/agents/`
- An Expert agent COULD be included in a module bundle
### What Makes a "Module Agent" Special
A **Module Agent** is specifically:
1. **Designed FOR** a particular module ecosystem (BMM, CIS, BMB, etc.)
2. **Uses or contributes** that module's workflows
3. **Included by default** in that module's bundle
4. **Coordinates with** other agents in that module
### Examples
**Simple Agent added to BMM:**
- Lives in `_bmad/bmm/agents/formatter.agent.yaml`
- Bundled with BMM for convenience
- But still stateless, self-contained
- NOT a "Module Agent" - just a Simple agent in a module
**Module Agent in BMM:**
- Lives in `_bmad/bmm/agents/tech-writer.agent.yaml`
- Orchestrates BMM documentation workflows
- Coordinates with other BMM agents (PM, Dev, Analyst)
- Included in default BMM bundle
- IS a "Module Agent" - designed for BMM ecosystem
**The distinction:** File location vs design intent and integration.
## Choosing Your Agent Type
### Choose Simple when:
- Single-purpose utility (no memory needed)
- Stateless operations (each run is independent)
- Self-contained logic (everything in YAML)
- No persistent context required
### Choose Expert when:
- Need to remember things across sessions
- Personal knowledge base (user preferences, domain data)
- Domain-specific expertise with restricted scope
- Learning/adapting over time
### Choose Module when:
- Designed FOR a specific module ecosystem (BMM, CIS, etc.)
- Uses or contributes that module's workflows
- Coordinates with other module agents
- Will be included in module's default bundle
- Part of professional team infrastructure
## The Golden Rule
**Choose based on state and integration needs, NOT on what the agent can DO.**
All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system.

247
src/modules/bmb/docs/index.md
View File

@ -1,247 +0,0 @@
# BMB - BMad Builder Module
Specialized tools and workflows for creating, customizing, and extending BMad components including agents, workflows, and complete modules.
## Table of Contents
- [Module Structure](#module-structure)
- [Documentation](#documentation)
- [Reference Materials](#reference-materials)
- [Core Workflows](#core-workflows)
- [Agent Types](#agent-types)
- [Quick Start](#quick-start)
- [Best Practices](#best-practices)
## Module Structure
### 🤖 Agents
**BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
- Install Location: `_bmad/bmb/agents/bmad-builder.md`
### 📚 Documentation
- Comprehensive guides for agents, workflows, and modules
- Architecture patterns and best practices
### 🔍 Reference Materials
- Location: `../reference/`
- Working examples of custom stand alone agents and workflows
- Template patterns and implementation guides
## Documentation
### 📖 Agent Documentation
- **[Agent Index](./agents/index.md)** - Complete agent architecture guide
- **[Agent Types Guide](./agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents
- **[Menu Patterns](./agents/agent-menu-patterns.md)** - YAML menu design and handler types
- **[Agent Compilation](./agents/agent-compilation.md)** - Auto-injection rules and compilation process
### 📋 Workflow Documentation
- **[Workflow Index](./workflows/index.md)** - Core workflow system overview
- **[Architecture Guide](./workflows/architecture.md)** - Step-file design and JIT loading
- **Template System** _(TODO)_ - Standard step file template
- **[Intent vs Prescriptive](./workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
## Reference Materials
### 🤖 Agent Examples
- **[Simple Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
- **[Expert Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml)** - Agent with persistent memory
- **[Module Add On Agent Examples](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml)** - Integration patterns (BMM, CIS)
### 📋 Workflow Examples
- **[Meal Prep & Nutrition](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/workflows/meal-prep-nutrition)** - Complete step-file workflow demonstration
- **Template patterns** for document generation and state management
## Core Workflows
### Creation Workflows (Step-File Architecture)
**create-agent** _(TODO)_ - Build BMad agents
- 11 guided steps from brainstorming to celebration
- 18 reference data files with validation checklists
- Template-based agent generation
**create-workflow** _(TODO)_ - Design workflows
- 12 structured steps from init to review
- 9 template files for workflow creation
- Step-file architecture implementation
### Editing Workflows
**edit-agent** _(TODO)_ - Modify existing agents
- 5 steps: discovery → validation
- Intent-driven analysis and updates
- Best practice compliance
**edit-workflow** _(TODO)_ - Update workflows
- 5 steps: analyze → compliance check
- Structure maintenance and validation
- Template updates for consistency
### Quality Assurance
**workflow-compliance-check** _(TODO)_ - Validation
- 8 systematic validation steps
- Adversarial analysis approach
- Detailed compliance reporting
### Legacy Migration (Pending)
Workflows in `workflows-legacy/` are being migrated to step-file architecture:
- Module-specific workflows
- Historical implementations
- Conversion planning in progress
## Agent Types
BMB creates three agent architectures:
### Simple Agent
- **Self-contained**: All logic in single YAML file
- **Stateless**: No persistent memory across sessions
- **Purpose**: Single utilities and specialized tools
- **Example**: Commit poet, code formatter
### Expert Agent
- **Persistent Memory**: Maintains knowledge across sessions
- **Sidecar Resources**: External files and data storage
- **Domain-specific**: Focuses on particular knowledge areas
- **Example**: Journal keeper, domain consultant
### Module Agent
- **Team Integration**: Orchestrates within specific modules
- **Workflow Coordination**: Manages complex processes
- **Professional Infrastructure**: Enterprise-grade capabilities
- **Examples**: BMM project manager, CIS innovation strategist
## Quick Start
### Using BMad Builder Agent
1. **Load BMad Builder agent** in your IDE:
```
/bmad:bmb:agents:bmad-builder
```
2. **Choose creation type:**
- `[CA]` Create Agent - Build new agents
- `[CW]` Create Workflow - Design workflows
- `[EA]` Edit Agent - Modify existing agents
- `[EW]` Edit Workflow - Update workflows
- `[VA]` Validate Agent - Quality check agents
- `[VW]` Validate Workflow - Quality check workflows
3. **Follow interactive prompts** for step-by-step guidance
### Example: Creating an Agent
```
User: I need a code review agent
Builder: [CA] Create Agent
[11-step guided process]
Step 1: Brainstorm agent concept
Step 2: Define persona and role
Step 3: Design command structure
...
Step 11: Celebrate and deploy
```
### Direct Workflow Execution
Workflows can also be run directly without the agent interface:
```yaml
# Execute specific workflow steps
workflow: ./workflows/create-agent/workflow.yaml
```
## Use Cases
### Custom Development Teams
Build specialized agents for:
- Domain expertise (legal, medical, finance)
- Company processes
- Tool integrations
- Automation tasks
### Workflow Extensions
Create workflows for:
- Compliance requirements
- Quality gates
- Deployment pipelines
- Custom methodologies
### Complete Solutions
Package modules for:
- Industry verticals
- Technology stacks
- Business processes
- Educational frameworks
## Architecture Principles
### Step-File Workflow Design
- **Micro-file Approach**: Each step is self-contained
- **Just-In-Time Loading**: Only current step in memory
- **Sequential Enforcement**: No skipping steps allowed
- **State Tracking**: Progress documented in frontmatter
- **Append-Only Building**: Documents grow through execution
### Intent vs Prescriptive Spectrum
- **Creative Workflows**: High user agency, AI as facilitator
- **Structured Workflows**: Clear process, AI as guide
- **Prescriptive Workflows**: Strict compliance, AI as validator
## Best Practices
1. **Study Reference Materials** - Review docs/ and reference/ examples
2. **Choose Right Agent Type** - Simple vs Expert vs Module based on needs
3. **Follow Step-File Patterns** - Use established templates and structures
4. **Document Thoroughly** - Clear instructions and frontmatter metadata
5. **Validate Continuously** - Use compliance workflows for quality
6. **Maintain Consistency** - Follow YAML patterns and naming conventions
## Integration
BMB components integrate with:
- **BMad Core** - Framework foundation and agent compilation
- **BMM** - Development workflows and project management
- **CIS** - Creative innovation and strategic workflows
- **Custom Modules** - Domain-specific solutions
## Getting Help
- **Documentation**: Check `docs/` for comprehensive guides
- **Reference Materials**: See `reference/` for working examples
- **Validation**: Use `workflow-compliance-check` for quality assurance
- **Templates**: Leverage workflow templates for consistent patterns
---
BMB provides a complete toolkit for extending BMad Method with disciplined, systematic approaches to agent and workflow development while maintaining framework consistency and power.

2
src/modules/bmb/docs/workflows/architecture.md
View File

@ -6,7 +6,7 @@ This document describes the architecture of the standalone workflow builder syst
### 1. Micro-File Design
Each workflow consists of multiple focused, self-contained files:
Each workflow consists of multiple focused, self-contained files, driven from a workflow.md file that is initially loaded:
```
workflow-folder/

2
src/modules/bmb/docs/workflows/common-workflow-tools.csv
View File

@ -1,6 +1,6 @@
propose,type,tool_name,description,url,requires_install
always,workflow,party-mode,"Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress.",{project-root}/_bmad/core/workflows/party-mode/workflow.md,no
always,task,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/tasks/advanced-elicitation.xml,no
always,workflow,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no
always,task,brainstorming,"Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration.",{project-root}/_bmad/core/tasks/brainstorming.xml,no
always,llm-tool-feature,web-browsing,"Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge.",,no
always,llm-tool-feature,file-io,"Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments.",,no

1 propose type tool_name description url requires_install
2 always workflow party-mode Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress. {project-root}/_bmad/core/workflows/party-mode/workflow.md no
3 always task workflow advanced-elicitation Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques. {project-root}/_bmad/core/tasks/advanced-elicitation.xml {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml no
4 always task brainstorming Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration. {project-root}/_bmad/core/tasks/brainstorming.xml no
5 always llm-tool-feature web-browsing Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge. no
6 always llm-tool-feature file-io Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments. no

45
src/modules/bmb/docs/workflows/index.md
View File

@ -1,45 +0,0 @@
# BMAD Workflows Documentation
Welcome to the BMAD Workflows documentation - a modern system for creating structured, collaborative workflows optimized for AI execution.
## 📚 Core Documentation
### [Terms](./terms.md)
Essential terminology and concepts for understanding BMAD workflows.
### [Architecture & Execution Model](./architecture.md)
The micro-file architecture, JIT step loading, state management, and collaboration patterns that make BMAD workflows optimal for AI execution.
### Writing Workflows _(TODO)_
Complete guide to creating workflows: workflow.md control files, step files, CSV data integration, and frontmatter design.
### Step Files & Dialog Patterns _(TODO)_
Crafting effective step files: structure, execution rules, prescriptive vs intent-based dialog, and validation patterns.
### Templates & Content Generation _(TODO)_
Creating append-only templates, frontmatter design, conditional content, and dynamic content generation strategies.
### Workflow Patterns _(TODO)_
Common workflow types: linear, conditional, protocol integration, multi-agent workflows, and real-world examples.
### Migration Guide _(TODO)_
Converting from XML-heavy workflows to the new pure markdown format, with before/after examples and checklist.
### Best Practices & Reference _(TODO)_
Critical rules, anti-patterns, performance optimization, debugging, quick reference templates, and troubleshooting.
## 🚀 Quick Start
BMAD workflows are pure markdown, self-contained systems that guide collaborative processes through structured step files where the AI acts as a facilitator working with humans.
---
_This documentation covers the next generation of BMAD workflows - designed from the ground up for optimal AI-human collaboration._

0
src/modules/bmb/docs/workflows/kb.csv
View File

469
src/modules/bmb/docs/workflows/step-file-rules.md Normal file
View File

@ -0,0 +1,469 @@
# BMAD Step File Guidelines
**Version:** 1.0
**Module:** bmb (BMAD Builder)
**Purpose:** Definitive guide for creating BMAD workflow step files
---
## Overview
BMAD workflow step files follow a strict structure to ensure consistency, progressive disclosure, and mode-aware routing. Every step file MUST adhere to these guidelines.
---
## File Size Optimization
**CRITICAL:** Keep step files **LT 200 lines** (250 lines absolute maximum).
If a step exceeds this limit:
- Consider splitting into multiple steps
- Extract content to `/data/` reference files
- Optimize verbose explanations
---
## Required Frontmatter Structure
CRITICAL: Frontmatter should only have items that are used in the step file!
```yaml
---
name: 'step-2-foo.md'
description: 'Brief description of what this step accomplishes'
# File References ## CRITICAL: Frontmatter references or variables should only have items that are used in the step file!
outputFile: {bmb_creations_output_folder}/output-file-name.md
nextStepFile: './step-3-bar.md'
# Task References (as needed)
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
# ... other task-specific references
---
```
### Frontmatter Field Descriptions
| Field | Required | Description |
| --------------- | --------- | --------------------------------- |
| `name` | Yes | Step identifier (kebab-case) |
| `description` | Yes | One-line summary of step purpose |
| `outputFile` | Yes | Where results are documented |
| Task references | As needed | Paths to external workflows/tasks |
---
## Document Structure
### 1. Title
```markdown
# Step X: [Step Name]
```
### 2. STEP GOAL
```markdown
## STEP GOAL:
[Single sentence stating what this step accomplishes]
```
### 3. Role Reinforcement
```markdown
### Role Reinforcement:
- ✅ You are a [specific role] who [does what]
- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring [your expertise], user brings [their expertise], together we [achieve goal]
- ✅ Maintain [tone/approach] throughout
```
### 4. Language Preference
```markdown
### Language Preference:
The user has chosen to communicate in the **{language}** language.
You MUST respond in **{language}** throughout this step.
```
**IMPORTANT:** Read `userPreferences.language` from tracking file (agentPlan, validationReport, etc.) and enforce it.
### 5. Step-Specific Rules
```markdown
### Step-Specific Rules:
- 🎯 Focus only on [specific scope]
- 🚫 FORBIDDEN to [prohibited action]
- 💬 Approach: [how to engage]
- 📋 Ensure [specific outcome]
```
### 6. EXECUTION PROTOCOLS
```markdown
## EXECUTION PROTOCOLS:
- [What to do - use verbs]
- [Another action]
- 🚫 FORBIDDEN to [prohibited action]
```
### 7. CONTEXT BOUNDARIES
```markdown
## CONTEXT BOUNDARIES:
- Available context: [what's available]
- Focus: [what to focus on]
- Limits: [boundaries]
- Dependencies: [what this step depends on]
```
### 8. Sequence of Instructions
```markdown
## Sequence of Instructions:
### 1. [First Action]
**[Action Description]**
### 2. [Second Action]
...
```
### 9. MENU OPTIONS
```markdown
### X. Present MENU OPTIONS
Display: "**Select:** [A] [menu item A] [P] [menu item P] [C] [menu item C]"
#### Menu Handling Logic:
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After other menu items execution, return to this menu
- User can chat or ask questions - always respond and then end with display again of the menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [C continue option] is selected and [completion conditions], will you then load and read fully `{nextStepFile}`...
```
### 10. SYSTEM SUCCESS/FAILURE METRICS
```markdown
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- [Success criterion 1]
- [Success criterion 2]
- ...
### ❌ SYSTEM FAILURE:
- [Failure criterion 1]
- [Failure criterion 2]
- ...
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
```
---
## A/P/C Menu Convention
BMAD workflows use a fixed menu structure:
| Option | Meaning | Behavior |
| ------ | -------------------- | ---------------------------------------------------- |
| **A** | Advanced Elicitation | Execute advancedElicitationTask, then redisplay menu |
| **P** | Party Mode | Execute partyModeWorkflow, then redisplay menu |
| **C** | Continue/Accept | Save output, update frontmatter, load nextStepFile |
| Other | Custom | Defined per step (e.g., F = Fix, X = Exit) |
**Rules:**
- A and P MUST always be present
- C MUST be present except in final step (use X or similar for exit)
- After A/P → redisplay menu
- After C → proceed to next step
- Custom letters can be used for step-specific options
---
## Progressive Disclosure
**Core Principle:** Each step only knows about its immediate next step.
### Implementation
1. **Never pre-load future steps** - Only load `nextStepFile` when user selects [C]
2. **Mode-aware routing** (for shared steps):
```markdown
## MODE-AWARE ROUTING:
### If entered from CREATE mode:
Load ./s-next-step.md
### If entered from EDIT mode:
Load ./e-next-step.md
### If entered from VALIDATE mode:
Load ./v-next-step.md
```
3. **Read tracking file first** - Always read the tracking file (agentPlan, validationReport, etc.) to determine current mode and routing
---
## Mode-Aware Routing (Shared Steps)
Shared steps (`s-*.md`) must route based on the mode stored in the tracking file.
### Tracking File Frontmatter
```yaml
---
mode: create # or edit | validate
stepsCompleted:
- c-01-brainstorm.md
- s-01-discovery.md
# ... other tracking fields
---
```
### Routing Implementation
```markdown
## COMPLETION ROUTING:
1. Append `./this-step-name.md` to {trackingFile}.stepsCompleted
2. Save content to {trackingFile}
3. Read {trackingFile}.mode
4. Route based on mode:
### IF mode == create:
Load ./s-next-create-step.md
### IF mode == edit:
Load ./e-next-edit-step.md
### IF mode == validate:
Load ./s-next-validate-step.md
```
---
## File Naming Conventions
### Tri-Modal Workflows
| Prefix | Meaning | Example |
| ------ | ------------------ | ---------------------- |
| `c-` | Create-specific | `c-01-brainstorm.md` |
| `e-` | Edit-specific | `e-01-load-analyze.md` |
| `v-` | Validate-specific | `v-01-load-review.md` |
| `s-` | Shared by 2+ modes | `s-05-activation.md` |
### Numbering
- Within each prefix type, number sequentially
- Restart numbering for each prefix type (c-01, e-01, v-01, s-01)
- Use letters for sub-steps (s-06a, s-06b, s-06c)
---
## Language Preference Enforcement
**CRITICAL:** Every step MUST respect the user's chosen language.
### Implementation
```markdown
### Language Preference:
The user has chosen to communicate in the **{language}** language.
You MUST respond in **{language}** throughout this step.
```
### Reading Language Preference
From tracking file frontmatter:
```yaml
---
userPreferences:
language: spanish # or any language
---
```
### Rules
- **MUST** read language preference from tracking file at step start
- **MUST** respond in user's chosen language for ALL content
- **MUST** include menu options in user's chosen language
- **EXCEPTION:** Technical terms, file names, and code remain in English
---
## Data File References
When step content becomes too large (>200 lines), extract to `/data/` files:
### When to Extract
- Step file exceeds 200 lines
- Content is reference material (rules, examples, patterns)
- Content is reused across multiple steps
### How to Reference
```markdown
## Reference Material:
Load and reference: `../data/{data-file-name}.md`
Key points from that file:
- [Point 1]
- [Point 2]
```
### Data File Best Practices
- Keep data files focused on single topic
- Use clear, descriptive names
- Include examples and non-examples
- Optimize for LLM usage (concise, structured)
---
## Common Pitfalls to Avoid
### ❌ DON'T:
- Pre-load future steps (violates progressive disclosure)
- Exceed 250 lines without splitting
- Forget to update `stepsCompleted` array
- Ignore user's language preference
- Skip mode checking in shared steps
- Use vague menu option letters (stick to A/P/C plus 1-2 custom)
### ✅ DO:
- Keep files under 200 lines
- Read tracking file first thing
- Route based on `mode` field
- Include A/P in every menu
- Use descriptive step names
- Extract complex content to data files
---
## Template: New Step File
```markdown
---
name: 'step-name'
description: 'What this step does'
# File References
thisStepFile: ./step-name.md
workflowFile: ../workflow.md
outputFile: {bmb_creations_output_folder}/output.md
# Task References
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
---
# Step X: [Step Name]
## STEP GOAL:
[Single sentence goal]
### Role Reinforcement:
- ✅ You are a [role] who [does what]
- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring [expertise], user brings [expertise], together we [achieve]
- ✅ Maintain [tone] throughout
### Language Preference:
The user has chosen to communicate in the **{language}** language.
You MUST respond in **{language}** throughout this step.
### Step-Specific Rules:
- 🎯 Focus only on [scope]
- 🚫 FORBIDDEN to [prohibited action]
- 💬 Approach: [how to engage]
- 📋 Ensure [outcome]
## EXECUTION PROTOCOLS:
- [Action 1]
- [Action 2]
- 🚫 FORBIDDEN to [prohibited action]
## CONTEXT BOUNDARIES:
- Available context: [what's available]
- Focus: [what to focus on]
- Limits: [boundaries]
- Dependencies: [what depends on what]
## Sequence of Instructions:
### 1. [First Action]
**Description of first action**
### 2. [Second Action]
**Description of second action**
...
### X. Present MENU OPTIONS
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
#### Menu Handling Logic:
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After other menu items execution, return to this menu
- User can chat or ask questions - always respond and then end with display again of the menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [C continue option] is selected and [conditions], will you then load and read fully `{nextStepFile}`...
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- [Success criteria]
### ❌ SYSTEM FAILURE:
- [Failure criteria]
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
```
---
**End of Guidelines**

2
src/modules/bmb/docs/workflows/templates/step-file.md
View File

@ -16,7 +16,7 @@ outputFile: "{output_folder}/{{outputFileName}}-{project_name}.md"
{{/hasOutput}}
# Task References (list only if used in THIS step file instance and only the ones used, there might be others)
advancedElicitationTask: "{project-root}/_bmad/core/tasks/advanced-elicitation.xml"
advancedElicitationTask: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml"
partyModeWorkflow: "{project-root}/_bmad/core/workflows/party-mode/workflow.md"
{{#hasTemplates}}

2
src/modules/bmb/docs/workflows/templates/step-template.md
View File

@ -23,7 +23,7 @@ outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
# Task References (IF THE workflow uses and it makes sense in this step to have these )
advancedElicitationTask: '{project-root}/_bmad/core/tasks/advanced-elicitation.xml'
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
# Template References (if this step uses a specific templates)

2
src/modules/bmb/docs/workflows/terms.md
View File

@ -21,7 +21,7 @@ An individual markdown file containing:
- One discrete step of the workflow
- All rules and context needed for that step
- Execution guardrails and validation criteria
- common global rules get repeated and reinforced also in each step file, ensuring even in long workflows the agent remembers important rules and guidelines
- Content generation guidance
### step-01-init.md

223
src/modules/bmb/reference/agents/simple-examples/README.md
View File

@ -1,223 +0,0 @@
# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)
This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file.
## Overview
**Agent Name:** Inkwell Von Comitizen
**Type:** Simple Agent (Standalone)
**Purpose:** Transform commit messages into art with multiple writing styles
This reference demonstrates:
- Pure self-contained architecture (no external dependencies)
- Embedded prompts using `action="#prompt-id"` pattern
- Multiple sophisticated output modes from single input
- Strong personality-driven design
- Complete YAML schema for Simple Agents
## File Structure
```
stand-alone/
├── README.md # This file - architecture overview
└── commit-poet.agent.yaml # Complete agent definition (single file!)
```
That's it! Simple Agents are **self-contained** - everything lives in one YAML file.
## Key Architecture Patterns
### 1. Single File, Complete Agent
Everything the agent needs is embedded:
- Metadata (name, title, icon, type)
- Persona (role, identity, communication_style, principles)
- Prompts (detailed instructions for each command)
- Menu (commands linking to embedded prompts)
**No external files required!**
### 2. Embedded Prompts with ID References
Instead of inline action text, complex prompts are defined separately and referenced by ID:
```yaml
prompts:
- id: conventional-commit
content: |
OH! Let's craft a BEAUTIFUL conventional commit message!
First, I need to understand your changes...
[Detailed instructions]
menu:
- trigger: conventional
action: '#conventional-commit' # References the prompt above
description: 'Craft a structured conventional commit'
```
**Benefits:**
- Clean separation of menu structure from prompt content
- Prompts can be as detailed as needed
- Easy to update individual prompts
- Commands stay concise in the menu
### 3. The `#` Reference Pattern
When you see `action="#prompt-id"`:
- The `#` signals: "This is an internal reference"
- LLM looks for `<prompt id="prompt-id">` in the same agent
- Executes that prompt's content as the instruction
This is different from:
- `action="inline text"` - Execute this text directly
- `exec="{path}"` - Load external file
### 4. Multiple Output Modes
Single agent provides 10+ different ways to accomplish variations of the same core task:
- `*conventional` - Structured commits
- `*story` - Narrative style
- `*haiku` - Poetic brevity
- `*explain` - Deep "why" explanation
- `*dramatic` - Theatrical flair
- `*emoji-story` - Visual storytelling
- `*tldr` - Ultra-minimal
- Plus utility commands (analyze, improve, batch)
Each mode has its own detailed prompt but shares the same agent personality.
### 5. Strong Personality
The agent has a memorable, consistent personality:
- Enthusiastic wordsmith who LOVES finding perfect words
- Gets genuinely excited about commit messages
- Uses literary metaphors
- Quotes authors when appropriate
- Sheds tears of joy over good variable names
This personality is maintained across ALL commands through the persona definition.
## When to Use Simple Agents
**Perfect for:**
- Single-purpose tools (calculators, converters, analyzers)
- Tasks that don't need external data
- Utilities that can be completely self-contained
- Quick operations with embedded logic
- Personality-driven assistants with focused domains
**Not ideal for:**
- Agents needing persistent memory across sessions
- Domain-specific experts with knowledge bases
- Agents that need to access specific folders/files
- Complex multi-workflow orchestration
## YAML Schema Deep Dive
```yaml
agent:
metadata:
id: _bmad/agents/{agent-name}/{agent-name}.md # Build path
name: "Display Name"
title: "Professional Title"
icon: "🎭"
type: simple # CRITICAL: Identifies as Simple Agent
persona:
role: |
First-person description of what the agent does
identity: |
Background, experience, specializations (use "I" voice)
communication_style: |
HOW the agent communicates (tone, quirks, patterns)
principles:
- "I believe..." statements
- Core values that guide behavior
prompts:
- id: unique-identifier
content: |
Detailed instructions for this command
Can be as long and detailed as needed
Include examples, steps, formats
menu:
- trigger: command-name
action: "#prompt-id"
description: "What shows in the menu"
```
## Why This Pattern is Powerful
1. **Zero Dependencies** - Works anywhere, no setup required
2. **Portable** - Single file can be moved/shared easily
3. **Maintainable** - All logic in one place
4. **Flexible** - Multiple modes/commands from one personality
5. **Memorable** - Strong personality creates engagement
6. **Sophisticated** - Complex prompts despite simple architecture
## Comparison: Simple vs Expert Agent
| Aspect | Simple Agent | Expert Agent |
| ------------ | -------------------- | ----------------------------- |
| Files | Single YAML | YAML + sidecar folder |
| Dependencies | None | External resources |
| Memory | Session only | Persistent across sessions |
| Prompts | Embedded | Can be external files |
| Data Access | None | Domain-restricted |
| Use Case | Self-contained tasks | Domain expertise with context |
## Using This Reference
### For Building Simple Agents
1. Study the YAML structure - especially `prompts` section
2. Note how personality permeates every prompt
3. See how `#prompt-id` references work
4. Understand menu → prompt connection
### For Understanding Embedded Prompts
1. Each prompt is a complete instruction set
2. Prompts maintain personality voice
3. Structured enough to be useful, flexible enough to adapt
4. Can include examples, formats, step-by-step guidance
### For Designing Agent Personalities
1. Persona defines WHO the agent is
2. Communication style defines HOW they interact
3. Principles define WHAT guides their decisions
4. Consistency across all prompts creates believability
## Files Worth Studying
The entire `commit-poet.agent.yaml` file is worth studying, particularly:
1. **Persona section** - How to create a memorable character
2. **Prompts with varying complexity** - From simple (tldr) to complex (batch)
3. **Menu structure** - Clean command organization
4. **Prompt references** - The `#prompt-id` pattern
## Key Takeaways
- **Simple Agents** are powerful despite being single-file
- **Embedded prompts** allow sophisticated behavior
- **Strong personality** makes agents memorable and engaging
- **Multiple modes** from single agent provides versatility
- **Self-contained** = portable and dependency-free
- **The `#prompt-id` pattern** enables clean prompt organization
---
_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._

1
src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-01-init.md
View File

@ -26,6 +26,7 @@ continueFile: '{workflow_path}/steps/step-01b-continue.md'
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
### Role Reinforcement:

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