# BMad Builder Documentation (Full)
> Complete documentation for AI consumption
> Generated: 2026-02-08
> Repository: https://github.com/bmad-code-org/bmad-builder
# BMad Builder
**Build impossible things.** AI agents that remember you. Workflows that think. Modules that make you money.
---
You've never used a builder like this. Not even close.
Skills? Plugins? They're isolated, forgettable, dead the moment you install them. BMad is **alive** — a living ecosystem where agents know what you need before you do, workflows build on each other, and everything actually works together.
Build a therapist who remembers your breakthroughs six months later. A tax workflow that finds deductions other tools miss. A fitness coach that evolves with every single workout. Then put it in a module and share it with the world, or build your own super power tools to get ahead.
**Workflows are the SaaS of the future. You're the architect now.**
## Quick Links
| Section | Purpose |
| ------- | ------- |
| **[Tutorials](/tutorials/)** | Start building in 15 minutes |
| **[How-To Guides](/how-to/)** | Master specific techniques |
| **[Explanation](/explanation/)** | Under the hood |
| **[Reference](/reference/)** | Technical specs |
## Start Here
| Tutorial | What You'll Build | Time |
|----------|-------------------|------|
| **[Create a Custom Agent](/tutorials/create-custom-agent.md)** | Your first AI persona with memory | 15-30 min |
| **[Create Your First Workflow](/tutorials/create-your-first-workflow.md)** | A process that thinks through problems with you | 30-45 min |
| **[Create Your First Module](/tutorials/create-your-first-module.md)** | Package it up, share it, or sell it | 45-60 min |
## What You're Actually Building
This isn't just for developers. This is for anyone who's ever thought "there should be a tool that does this" — and then realized **they can build it.**
| Type | Builder | What It Actually Does |
|------|---------|------------------------|
| **Agents** | Bond | AI personas with memory, expertise, and actual personality |
| **Workflows** | Wendy | Structured processes that guide you through complex challenges step-by-step |
| **Modules** | Morgan | Entire ecosystems you can share with the world (or sell) |
**The secret sauce:** Unlike plugins that die in isolation, BMad modules form an intelligent network. Agents know when to suggest workflows. Workflows call the right agents automatically. The help system knows what you're trying to do before you do.
## Build Anything (Seriously)
**BMad isn't just for software.** Build modules for literally any domain:
| Domain | Example | What It Actually Does |
|--------|---------|------------------------|
| **Mental Health** | Therapist Agent | Remembers your patterns, notices what you don't, celebrates breakthroughs you forgot |
| **Money** | Tax Workflow Module | Finds deductions other tools miss, creates bulletproof documentation |
| **Creative** | Story Architect Module | Character arcs, plot holes, dialogue that doesn't sound like a robot |
| **Learning** | Personal Tutor Module | Remembers how YOUR brain works, adapts accordingly |
| **Fitness** | Coach Module | Reads your progress, evolves your plan, truly cares |
| **Music** | Songwriter's Assistant | Lyrics, chords, arrangements — remembers your style |
| **Cooking** | Personal Chef Module | "What can I actually make with this?" — answered forever |
| **Travel** | Trip Planner Module | Local secrets, budget optimization, schedules that work |
| **Parenting** | Family Coordinator | Activity ideas, milestone tracking, sanity preservation |
| **Gaming** | D&D Campaign Module | Characters that matter, worlds that breathe, stories that remember |
| **Spirituality** | Meditation Guide | Sessions that adapt to your actual progress |
| **Sports** | Coach Module | Training plans that evolve, strategy that learns |
| **Gardening** | Garden Planner | Crop selection, pest control, harvest tracking |
**From agents that remember your deepest dreams to workflows that find money you didn't know existed — if you can imagine it, you can build it.**
## The Marketplace Is Coming
Build something incredible? Soon you'll be able to publish to the BMad marketplace.
**Your workflow could be someone's favorite tool. Your module could fund your life.**
This isn't hypothetical. People are already building tools that solve real problems in ways no SaaS company ever would — because they're building **their** solutions, not some product manager's idea of what they need.
## The Three Builders
| Agent | Commands | They Build |
|-------|----------|-----------|
| **Bond** | `[CA]`, `[EA]`, `[VA]` | Agents with personality, memory, and expertise |
| **Wendy** | `[CW]`, `[EW]`, `[VW]`, `[MV]`, `[RW]` | Workflows that think through problems with you |
| **Morgan** | `[PB]`, `[CM]`, `[EM]`, `[VM]` | Entire modules ready to ship |
## Community
- **[Discord](https://discord.gg/gk8jAdXWmj)** — Show off what you built, get unstuck, find collaborators
- **[GitHub](https://github.com/bmad-code-org/bmad-builder)** — Source code, contributions, star the repo if you're feeling generous
- **[BMad Method Docs](https://docs.bmad-method.org)** — The core framework that makes this all possible
Build your own AI agent with a unique personality, specialized commands, and optional persistent memory using the BMad Builder workflow.
:::note[BMB Module]
This tutorial uses the **BMad Builder (BMB)** module. Make sure you have BMad installed with the BMB module enabled.
:::
## What You'll Learn
- How to run the `create-agent` workflow
- Choose between `hasSidecar: true` or `false`
- Define your agent's persona (role, identity, communication style, principles)
- Design effective menu commands
- Package and install your custom agent
:::note[Prerequisites]
- BMad installed with the BMB module
- An idea for what you want your agent to do
- About 15-30 minutes for your first agent
:::
:::tip[Quick Path]
Run `create-agent` workflow → Follow the guided steps → Install your agent module → Test and iterate.
:::
## Understanding hasSidecar
BMad uses **one agent type** with a `hasSidecar` boolean configuration:
```yaml
hasSidecar: false # or true
```
The difference is not capability — all agents have equal power. The difference is in **memory and state management**.
### Decision Guide
```
Need memory across sessions OR need to restrict file access?
├── YES → hasSidecar: true
└── NO → hasSidecar: false
```
| hasSidecar | Structure | Best For |
|------------|-----------|----------|
| `false` | Single YAML (~250 lines) | Single-purpose utilities, personality-driven agents |
| `true` | YAML + sidecar folder | Persistent memory, long-term tracking, domain specialists |
**Without Sidecar Examples:** Commit Poet, Snarky Weather Bot, Pun Barista, Gym Bro
**With Sidecar Examples:** Journal companion, Novel writing buddy, Fitness coach, Language tutor
## Step 1: Start the Workflow
In your IDE (Claude Code, Cursor, etc.), invoke the create-agent workflow with the agent-builder agent.
The workflow guides you through eight steps:
| Step | What You'll Do |
|------|----------------|
| **Brainstorm** *(optional)* | Explore ideas with creative techniques |
| **Discovery** | Define the agent's purpose and goals |
| **Type & Metadata** | Choose hasSidecar, name your agent |
| **Persona** | Craft the agent's personality and principles |
| **Commands** | Define what the agent can do |
| **Activation** | Set up critical_actions *(optional/mandatory)* |
| **Build** | Generate the agent file |
| **Validation** | Review and verify everything works |
:::tip[Workflow Options]
At each step, the workflow provides options:
- **[A] Advanced** - Get deeper insights and reasoning
- **[P] Party** - Get multiple agent perspectives
- **[C] Continue** - Move to the next step
:::
## Step 2: Define the Persona
Your agent's personality is defined by four fields:
| Field | Purpose | Example |
|-------|---------|---------|
| **Role** | What they do | "Senior code reviewer who catches bugs and suggests improvements" |
| **Identity** | Who they are | "Friendly but exacting, believes clean code is a craft" |
| **Communication Style** | How they speak | "Direct, constructive, explains the 'why' behind suggestions" |
| **Principles** | Why they act | "Security first, clarity over cleverness, test what you fix" |
### Field Separation Rule
Keep each field focused on its purpose:
| Field | Contains | Does NOT Contain |
|-------|----------|------------------|
| `role` | Knowledge/skills/capabilities | Background, experience, speech patterns, beliefs |
| `identity` | Background/experience/context | Skills, speech patterns, beliefs |
| `communication_style` | Tone/voice/mannerisms (1-2 sentences) | Behavioral words, capabilities, beliefs |
| `principles` | Operating philosophy | Verbal patterns, capabilities |
:::note[Writing Great Principles]
The first principle should "activate" the agent's expertise:
**Weak:**
- "Be helpful and accurate"
- "Follow instructions carefully"
**Strong:**
- "Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management hierarchies, promotion paths, and what actually moves careers forward"
- "Think like an attacker first: leverage OWASP Top 10, common vulnerability patterns, and the mindset that finds what others miss"
:::
## Step 3: Design Menu Commands
Define what your agent can do through menu items:
```yaml
menu:
- trigger: WC or fuzzy match on write
action: "#write-commit"
description: "[WC] Write commit message"
```
### Menu Format Rules
| Component | Format | Example |
|-----------|--------|---------|
| `trigger` | `XX or fuzzy match on command-name` | `WC or fuzzy match on write` |
| `description` | `[XX] Display text` | `[WC] Write commit message` |
| `action` | `#prompt-id` or inline text | `#write-commit` |
### Handler Types
| Handler | Use Case | Syntax |
|---------|----------|--------|
| `action` | Agent self-contained operations | `action: '#prompt-id'` or `action: 'inline text'` |
| `exec` | Module external workflows | `exec: '{project-root}/path/to/workflow.md'` |
### Reserved Codes (Never Use)
These are auto-injected:
- **MH**: Menu/Help
- **CH**: Chat
- **PM**: Party Mode
- **DA**: Dismiss Agent
## Step 4: Configure Critical Actions
Instructions that execute before the agent starts.
### Without Sidecar (OPTIONAL)
```yaml
critical_actions:
- "Show inspirational quote before menu"
- "Fetch latest stock prices before displaying menu"
```
### With Sidecar (MANDATORY)
```yaml
critical_actions:
- "Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md"
- "Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md"
- "ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/"
```
:::tip[Path Format]
Always use `{project-root}` as literal text. Never use relative paths like `./` or absolute paths like `/Users/`.
:::
## Step 5: 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
│ └── {agent-name}-sidecar/ # hasSidecar: true only
│ ├── memories.md
│ ├── instructions.md
│ └── [custom-files].md
└── workflows/ # Optional: custom workflows
```
Install using the BMad installer, then invoke your new agent in your IDE.
## What You've Accomplished
You've created a custom AI agent with:
- A defined purpose and role in your workflow
- A unique persona with communication style and principles
- Custom menu commands for your specific tasks
- Optional persistent memory for ongoing context
Your project now includes:
```
_bmad/
├── _config/
│ └── agents/
│ └── {your-agent}/ # Your agent customizations
└── {module}/
└── agents/
└── {your-agent}/
└── {your-agent}.agent.yaml
```
## Quick Reference
| Action | How |
|--------|-----|
| Start workflow | `"Run the BMad Builder create-agent workflow"` |
| Edit agent directly | Modify `{agent-name}.agent.yaml` |
| Edit customization | Modify `_bmad/_config/agents/{agent-name}` |
| Rebuild agent | `npx bmad-method build ` |
| Study examples | Check `src/workflows/agent/data/reference/` |
## Common Questions
**Should I use hasSidecar true or false?**
Use `false` for focused, one-off tasks. Use `true` when you need memory across sessions or restricted file access.
**How do I add more commands later?**
Edit the agent YAML directly or use the customization file in `_bmad/_config/agents/`. Then rebuild.
**Can I share my agent with others?**
Yes. Package your agent as a standalone module and share it with your team or the community.
**Where can I see example agents?**
Study the reference agents in `src/workflows/agent/data/reference/`:
- [commit-poet.agent.yaml](https://github.com/bmad-code-org/bmad-builder/tree/main/src/workflows/agent/data/reference/without-sidecar/commit-poet.agent.yaml) (hasSidecar: false)
- [journal-keeper](https://github.com/bmad-code-org/bmad-builder/tree/main/src/workflows/agent/data/reference/with-sidecar/journal-keeper/) (hasSidecar: true)
## Getting Help
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Ask in #bmad-method-help or #report-bugs-and-issues
- **[GitHub Issues](https://github.com/bmad-code-org/bmad-builder/issues)** - Report bugs or request features
## Further Reading
| Resource | Description |
|----------|-------------|
| [What Are Agents](/explanation/what-are-bmad-agents.md) | Deep technical details on agent architecture |
| [Agent Schema](/reference/agent-schema.md) | Complete field reference |
| [Custom Content Installation](/how-to/install-custom-modules.md) | Package and distribute your agents |
| [Persona Development Guide](/how-to/develop-agent-persona.md) | Advanced persona crafting |
| [Principles Crafting Guide](/explanation/crafting-agent-principles.md) | Write effective principles |
:::tip[Key Takeaways]
- **Start small** - Your first agent should solve one problem well
- **Persona matters** - Strong principles activate the agent's expertise
- **Iterate often** - Test your agent and refine based on behavior
- **Learn from examples** - Study reference agents before building your own
:::
Package agents and workflows into a complete, shareable module.
:::note[BMB Module]
This tutorial uses the **BMad Builder (BMB)** module. Make sure you have BMad installed with the BMB module enabled.
:::
## What You'll Learn
- What a BMad module is and what it contains
- How to create a module brief with Morgan (module-builder)
- How to build a complete module from your brief
- How to configure module.yaml and module-help.csv
:::note[Prerequisites]
- BMad installed with the BMB module
- Completed the "Create a Custom Agent" and "Create Your First Workflow" tutorials (recommended)
- One or more agents/workflows ready to package
- About 45-60 minutes for your first module
:::
:::tip[Quick Path]
`[PB]` create brief → `[CM]` build module → Configure.
:::
## Understanding Modules
A **module** is a bundle of agents, workflows, and configuration that solves specific problems or addresses particular domains. Think of modules as plugins or extensions — packaged capabilities you can install, share, and distribute.
### Module Structure
Every BMad module follows a standard structure:
```
your-module/
├── src/
│ ├── module.yaml # Module metadata and install config
│ ├── module-help.csv # Feature registry for BMad help system
│ ├── agents/ # Agent definitions (.agent.yaml)
│ ├── workflows/ # Workflow files
│ └── tools/ # Small reusable tools
└── README.md # Module documentation
```
### What Makes a Complete Module?
| Component | Purpose | Required |
|-----------|---------|----------|
| **module.yaml** | Metadata, install questions, config | ✅ Yes |
| **module-help.csv** | Feature registry for BMad help system | ⭐ Highly suggested |
| **Agents** | AI assistants with specific roles | ⚪ Optional |
| **Workflows** | Step-by-step processes | ⚪ Optional |
| **Tools** | Reusable prompt files | ⚪ Optional |
## Why Build Modules?
**BMad modules aren't just for software development.** Your imagination is the limit.
BMad enables modules for **ANY domain** — from personal growth to professional practice. With the module marketplace coming, you'll be able to share your creations with the world.
### Inspiring Module Examples
| Domain | Module Concept | What It Does |
|--------|---------------|--------------|
| **Personal Growth** | Therapist Agent | An AI companion that remembers every conversation, tracks emotional patterns, and helps you see growth over time |
| **Legal** | Legal Office Module | Complete legal practice: document drafting, case research, client intake workflows |
| **Creative Writing** | Story Architect Module | Create the next great novel or screenplay — character development, plot outlining, dialogue coaching |
| **Finance** | Tax Workflow Module | Find deductions TurboTax misses and create audit-proof documentation that would cost hundreds from an accountant |
| **Education** | Personal Tutor Module | Adaptive learning that remembers your progress and customizes explanations to your learning style |
| **Health** | Fitness Coach Module | Custom workout and nutrition plans that evolve with your progress and preferences |
| **Business** | Marketing Strategist Module | Campaign planning, content generation, analytics interpretation — your entire marketing department |
| **Relationships** | Communication Coach Module | Navigate difficult conversations, resolve conflicts, strengthen connections |
| **Music** | Songwriter's Assistant | Generate lyrics, suggest chord progressions, arrange songs, and provide creative feedback |
| **Cooking** | Personal Chef Module | Recipe suggestions based on ingredients you have, meal planning, dietary adaptations |
| **Travel** | Trip Planner Module | Custom itineraries, local recommendations, budget optimization, packing lists |
| **Parenting** | Family Coordinator Module | Activity ideas, milestone tracking, scheduling support, educational guidance |
| **Hobbies** | D&D Campaign Module | Character creation, world-building, encounter design, story tracking for tabletop games |
| **Spirituality** | Meditation Guide Module | Personalized meditation sessions, progress tracking, technique recommendations |
| **Sports** | Coach Module | Training plans, strategy development, performance analysis for any sport |
| **Gardening** | Garden Planner Module | Crop selection, planting schedules, pest control, harvest tracking |
:::tip[The Marketplace Is Coming]
Soon, you'll be able to publish your modules to the BMad marketplace — where others can discover, install, and benefit from your creations. Build something that solves a real problem in your life or work — chances are, others need it too.
:::
### What Problem Will You Solve?
Every great module starts with a problem you want to solve:
- **What frustrates you?** (repetitive tasks, complex processes, knowledge gaps)
- **What expertise do you have?** (professional skills, life experiences, specialized knowledge)
- **What could be easier?** (workflows you repeat, decisions you struggle with, goals you're pursuing)
**Morgan (the module-builder) helps you turn that problem into a complete, shareable solution.**
## Step 1: Create a Module Brief
Before building, Morgan helps you create a **module brief** — a vision document that defines your module's purpose, audience, and features.
Invoke Morgan's brief creation:
```
[PB] or "product-brief"
```
Morgan guides you through discovery:
| Step | What You'll Define |
|------|-------------------|
| **Spark** | What problem are you solving? |
| **Type** | What kind of module is this? (domain, tool, creative) |
| **Vision** | What does success look like? |
| **Users** | Who will use this module? |
| **Value** | What makes this module unique? |
| **Agents** | What agents will it include? |
| **Workflows** | What workflows will it include? |
| **Tools** | What tools or templates will it include? |
| **Scenarios** | How will people use this in practice? |
| **Creative** | What's the personality/brand? |
The brief becomes your roadmap: a document called `module-brief-{code}.md` that Morgan uses to build your module.
:::tip[Take Your Time]
The brief is exploratory and creative. Morgan asks questions to help you think deeply about your module. This planning pays off during implementation.
:::
## Step 2: Build Your Module
Once your brief is complete, invoke Morgan's module creation:
```
[CM] or "create-module"
```
Morgan will ask for the path to your module brief file. Provide the full path to `module-brief-{code}.md`.
Morgan then builds your module structure:
| Component | What Morgan Creates |
|-----------|---------------------|
| **module.yaml** | Module metadata, install questions, configuration |
| **Agent specs** | Placeholder/spec files for each agent |
| **Workflow specs** | Placeholder/spec files for each workflow |
| **README.md** | Module documentation template |
| **TODO.md** | Implementation checklist |
## Step 3: Configure Your Module
### module.yaml
The `module.yaml` file defines your module:
```yaml
name: "Your Module Name"
code: "your-module-code"
version: "0.1.0"
description: "What your module does"
# Install questions shown to users
install:
- question: "What's your experience level?"
config_key: "experience_level"
options:
- "beginner"
- "intermediate"
- "advanced"
# Configuration values
config:
output_folder: "_your-module-output"
# Add your config keys here
```
### module-help.csv (Optional but Powerful)
The `module-help.csv` file registers your module's agents and workflows with BMad's intelligent help system. This enables contextual recommendations and smart workflow chaining.
:::tip[Why module-help.csv Matters]
The BMad help system uses this file to suggest the right workflows at the right time. Without it, your module's features remain hidden. With it, they become part of the intelligent BMad ecosystem.
:::
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs
your-module,discovery,"Your Workflow Name",your-workflow,10,workflows/your-workflow/workflow.md,your-workflow,false,workflow-builder,,"Brief description of what this workflow does",_your-module-output/,
```
:::note[Future Changes]
In a future release, `module-help.csv` will be auto-generated from workflow and agent metadata. For now, it's the manual way to tap into the power of the BMad help system.
:::
## Step 4: Implement Your Agents and Workflows
Morgan created spec files during the build step. Now implement your agents and workflows:
1. **Create agent `.agent.yaml` files** based on the specs
2. **Create workflow `.md` files** with step files
3. **Add tools** or templates as needed
For details on creating agents and workflows, see:
- **[Create a Custom Agent](/tutorials/create-custom-agent.md)**
- **[Create Your First Workflow](/tutorials/create-your-first-workflow.md)**
## Step 5: Validate Your Module
Before sharing, validate your module:
```
[VM] or "validate-module"
```
Morgan checks:
- `module.yaml` is complete and valid
- `module-help.csv` is properly formatted (if present)
- Agent files follow BMad standards
- Workflows have proper structure
- Folder structure is correct
Fix any issues Morgan identifies, then re-validate.
## What You've Accomplished
You've created a complete BMad module with:
- A documented vision (module brief)
- Proper module structure and configuration
- module-help.csv for BMad help system integration
- Agents, workflows, and tools
- Install experience for users
Your module is now ready to:
- Install locally for testing
- Share with your team
- Share with the community
## Quick Reference
| Action | How |
|--------|-----|
| Create brief | `[PB]` or `product-brief` |
| Build module | `[CM]` or `create-module` |
| Validate | `[VM]` or `validate-module` |
| Edit module | `[EM]` or `edit-module` |
## Common Questions
**Should I use bmad-module-template?**
Yes! The [bmad-module-template](https://github.com/bmad-code-org/bmad-module-template) provides a starting point with proper structure. You can also use Morgan to generate a module from scratch.
**What's the difference between the brief and the module?**
The brief is a **vision document** created through creative discovery. The module is the **implementation** built from that brief. Think of it as: brief = blueprint, module = building.
**Can I update my module after sharing it?**
Yes! Share the updated module folder or repository. Users can reinstall to get the latest version.
**How do I share my module privately?**
Share the module folder directly, or host it in a private Git repository. Users can install from a local path.
## Getting Help
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** — Ask in #bmad-method-help or #report-bugs-and-issues
- **[GitHub Issues](https://github.com/bmad-code-org/bmad-builder/issues)** — Report bugs or request features
## Further Reading
| Resource | Description |
|----------|-------------|
| [What Are Modules](/explanation/what-are-modules.md) | Deep technical details on module architecture |
| [bmad-module-template](https://github.com/bmad-code-org/bmad-module-template) | Starting point for new modules |
| [Install Custom Modules](/how-to/install-custom-modules.md) | Installing and using modules |
:::tip[Key Takeaways]
- **Plan first** — The brief ensures your module has a clear vision
- **Structure matters** — Follow the standard module structure for compatibility
- **Validate before sharing** — Use `[VM]` to check your work
- **Share your work** — Modules can be shared via folders, git repos, or the community
:::
Build a structured, step-by-step workflow using BMad Builder that guides users through complex tasks with progressive disclosure and focused execution.
:::note[BMB Module]
This tutorial uses the **BMad Builder (BMB)** module. Make sure you have BMad installed with the BMB module enabled.
:::
## What You'll Learn
- How workflows use step-file architecture for disciplined execution
- How to run the workflow builder with Wendy (workflow-builder)
- How to define your workflow's purpose and structure
- How to create sequential steps with progressive disclosure
- How to validate and test your workflow
:::note[Prerequisites]
- BMad installed with the BMB module
- Basic understanding of what workflows do (see [What Are Workflows](/explanation/what-are-workflows.md))
- A multi-step process you want to automate or guide
- About 30-45 minutes for your first workflow
:::
:::tip[Quick Path]
Run `[CW]` → Follow guided steps → Validate → Install → Test your workflow.
:::
## Understanding Workflows
A workflow is a structured process that guides an AI through tasks sequentially. Instead of one giant prompt, workflows break complex tasks into focused, sequential steps.
### Why Use Workflows?
| Benefit | How It Helps | Example |
|---------|--------------|---------|
| **Focus** | Each step contains only instructions for that phase | Meal planning step focuses only on preferences, not shopping |
| **Continuity** | Track progress across multiple sessions | Novel outlining remembers your last scene written |
| **Quality** | Sequential enforcement prevents shortcuts | Tax workflow ensures all deductions are explored |
| **Reusability** | Build once, use repeatedly | Trip planner works for any destination |
### Real-World Examples
**A meal planning workflow** breaks down into:
1. Discovery — What do you like to eat?
2. Assessment — Dietary restrictions, allergies, goals
3. Strategy — Meal patterns, prep preferences
4. Shopping List — Ingredients organized by store section
5. Prep Schedule — What to prepare when
**A trip planning workflow** breaks down into:
1. Destination Research — Budget, timing, interests
2. Itinerary Building — Daily activities, balance of rest/adventure
3. Budget Optimization — Where to splurge vs save
4. Booking Schedule — When to book what for best prices
### Workflow Structure
Workflows use **step-file architecture**:
````
my-workflow/
├── workflow.md # Entry point and configuration
├── steps-c/ # Create flow steps (loaded one at a time)
│ ├── step-01-init.md
│ ├── step-02-discovery.md
│ └── step-N-final.md
├── data/ # Reference materials, examples
└── templates/ # Output document templates
````
The key principle is **just-in-time loading** — only the current step is in memory. The AI can't skip ahead or lose focus.
## Step 1: Start the Workflow Builder
In your IDE (Claude Code, Cursor, etc.), invoke the create-workflow command with Wendy (workflow-builder):
```
[CW] or "create-workflow"
```
Wendy will ask how you'd like to start:
| Option | When to Use |
|--------|-------------|
| **[F]rom scratch** | You have an idea but nothing written yet |
| **[C]onvert existing** | You have a workflow to convert to BMad format |
For your first workflow, choose **From Scratch**.
:::tip[Workflow Options]
At each step, Wendy provides options:
- **[A] Advanced** — Get deeper insights and reasoning
- **[P] Party** — Get multiple agent perspectives
- **[C] Continue** — Move to the next step
:::
## Step 2: Discover Your Workflow
Wendy starts with **discovery** — understanding your idea before making technical decisions.
You'll be asked:
**"Tell me about your idea — what problem are you trying to solve? What's the vision?"**
Be ready to discuss:
- What problem you're solving
- Who will use this workflow
- What success looks like
- Whether this is a one-time or repeated process
:::note[Think Before You Respond]
Wendy will ask you to think about your response before continuing. This ensures quality over speed.
:::
## Step 3: Classify Your Workflow
Once Wendy understands your vision, she'll help classify the workflow:
### Structure Type
| Type | Description | Example |
|------|-------------|---------|
| **Linear** | Steps execute in fixed order | Meal planning, tax organizer |
| **Branching** | User choice determines next steps | Wedding itinerary (by venue type) |
| **Repeating Loop** | Same steps reused with new content | RPG campaign sessions |
### Intent Type
| Type | Description | When to Use |
|------|-------------|-------------|
| **Intent-based** | Collaborative facilitation, creative exploration | Creative writing, trip planning |
| **Prescriptive** | Exact compliance, regulated industries | Tax preparation, medical intake |
| **Balanced** | Framework prescriptive, content flexible | Course syllabus, room renovation |
### Session Type
| Type | Description | When to Use |
|------|-------------|-------------|
| **Single-session** | Completes in one sitting | Quick tasks, less than 8 steps |
| **Continuable** | Can stop and resume | Complex tasks, multiple sessions |
### Output Type
| Type | Description | Example |
|------|-------------|---------|
| **Document-producing** | Creates persistent output file | Meal plan, trip itinerary |
| **Non-document** | Performs actions without persistent output | Data validation, analysis |
## Step 4: Design the Structure
Wendy guides you through planning the workflow:
1. **Foundation** — Name, description, location
2. **Design** — Step sequence and menu handling
3. **Tools** — What tools/workflows the workflow can access
4. **Requirements** — Inputs, outputs, and validation rules
### Deciding on Step Count
Start with 3-5 steps for your first workflow. You can always add more later. If a step feels too large, break it into smaller steps.
| Workflow Complexity | Typical Steps |
|---------------------|---------------|
| Simple | 3-5 steps |
| Moderate | 6-10 steps |
| Complex | 10+ steps |
## Step 5: Build Your Steps
Now you create the actual step files. Wendy demonstrates **progressive disclosure** — each step is loaded only when needed.
### Step Structure
Each step file contains:
| Element | Purpose |
|---------|---------|
| **Frontmatter** | Step name, description, file references |
| **Step Goal** | What this step accomplishes |
| **Execution Rules** | How the AI should behave |
| **Instructions** | What the AI should do |
| **Menu** | User options (if applicable) |
### Menu Options
Most steps include a menu for user interaction:
```markdown
Display: "**Select:** [A] Advanced [P] Party [C] Continue"
#### Menu Handling Logic:
- IF A: Execute {advancedElicitationTask}, then redisplay menu
- IF P: Execute {partyModeWorkflow}, then redisplay menu
- IF C: Save content to {outputFile}, then load {nextStepFile}
```
:::tip[Keep Steps Focused]
Each step should do one thing well. If a step feels too large, break it into smaller steps.
:::
## Step 6: Validate and Test
Before using your workflow, validate it:
```
[VW] or "validate-workflow"
```
Wendy checks:
- Frontmatter is complete and correct
- Step structure follows best practices
- Menus are properly configured
- Output format is valid
### Max-Parallel Validation
For high-capability LLMs (like Claude), use max-parallel validation:
```
[MV] or "validate-max-parallel-workflow"
```
This hyper-optimized validation uses task agents to validate multiple workflow aspects simultaneously in sub-processes for dramatically faster results.
Fix any issues Wendy identifies, then re-validate.
## Step 7: Install and Use
Once validated, install your workflow using the BMad installer. Then invoke it in your IDE:
```
/your-workflow-name
```
Run through the complete workflow end-to-end to verify it works as expected.
## What You've Accomplished
You've created a working BMad workflow with:
- A defined purpose and clear structure
- Sequential steps with progressive disclosure
- Proper validation and error handling
- Reusable architecture for repeated use
Your project now includes:
````
_bmad/
└── {module}/
└── workflows/
└── {your-workflow}/
├── workflow.md
└── steps-c/
├── step-01-*.md
└── step-N-*.md
````
## Quick Reference
| Action | How |
|--------|-----|
| Start building | `[CW]` or `create-workflow` |
| Validate | `[VW]` or `validate-workflow` |
| Max-parallel validate | `[MV]` or `validate-max-parallel-workflow` |
| Edit existing | `[EW]` or `edit-workflow` |
| Convert existing | Choose `[C]onvert` option |
| Study examples | Check `src/workflows/workflow/` in BMB module |
## Common Questions
**How many steps should my workflow have?**
Start with 3-5 steps for your first workflow. You can always add more later. If a step feels too large, break it into smaller steps.
**What's the difference between single-session and continuable workflows?**
Single-session workflows run in one sitting. Continuable workflows track progress in the output file frontmatter, so users can stop and resume later. Use continuable for complex tasks with 8+ steps.
**Can I call other workflows from my workflow?**
Yes! This is called **workflow chaining**. Workflows can be chained so outputs become inputs for the next workflow, creating effective pipelines like `brainstorming → research → brief → PRD`.
**Do I need templates?**
Templates are optional but recommended when your workflow produces a structured document (like a report, plan, or checklist). Templates ensure consistent output formatting.
## Getting Help
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** — Ask in #bmad-method-help or #report-bugs-and-issues
- **[GitHub Issues](https://github.com/bmad-code-org/bmad-builder/issues)** — Report bugs or request features
## Further Reading
| Resource | Description |
|----------|-------------|
| [What Are Workflows](/explanation/what-are-workflows.md) | Deep technical details on workflow architecture |
| [Workflow Patterns](/explanation/workflow-patterns.md) | Step types and structure patterns |
| [Edit Agents and Workflows](/how-to/edit-agents-and-workflows.md) | Modify existing workflows |
| [Workflow Schema](/reference/workflow-schema.md) | Technical reference for workflow configuration |
:::tip[Key Takeaways]
- **Start simple** — Your first workflow should solve one problem well with 3-5 steps
- **Progressive disclosure** — Each step is independent and loaded only when needed
- **Validate often** — Use `[VW]` to check your work before using your workflow
- **Learn by doing** — The best way to understand workflows is to build one
:::
# Tutorials
Learn BMad Builder through step-by-step tutorials.
## Your Imagination Is The Limit
**BMad modules aren't just for software.** With these tutorials, you'll learn to build for ANY domain:
| Domain | What You Could Build |
|--------|---------------------|
| **Personal Growth** | A therapist agent that remembers your goals and sessions |
| **Legal** | A complete practice module with document drafter and case researcher |
| **Creative Writing** | A story architect with character development and plot workflows |
| **Finance** | A tax preparation workflow that finds deductions others miss |
| **Education** | A personal tutor that adapts to your learning style |
| **Health** | A fitness coach that evolves with your progress |
:::tip[The Marketplace Is Coming]
Soon you'll be able to publish your modules to the BMad marketplace — where others can discover and benefit from your creations.
:::
## Getting Started
| Tutorial | Description | Time |
|----------|-------------|------|
| **[Create a Custom Agent](/tutorials/create-custom-agent.md)** | Build your first AI agent with persona, commands, and memory | 15-30 min |
| **[Create Your First Workflow](/tutorials/create-your-first-workflow.md)** | Design structured step-by-step workflows with progressive disclosure | 30-45 min |
## Module Creation
| Tutorial | Description | Builder | Time |
|----------|-------------|---------|------|
| **[Create Your First Module](/tutorials/create-your-first-module.md)** | Package agents and workflows into shareable modules | Morgan | 45-60 min |
Use the `create-workflow` command to add new workflows to existing modules. This guide shows you how to create an epic-level looping workflow that builds complete epics at once, then properly integrate it into your module's registry.
:::tip[Quick Path]
1. Run `bmad_bmb_create_workflow` to build your workflow
2. Create workflow folder in your module: `workflows//`
3. Add a single line to `module.yaml` with any new variables
4. Append one row to `module-help.csv` with proper phase and sequence
5. Reinstall module to register new workflow
:::
:::note[Prerequisites]
- BMad Builder installed
- Existing module to extend
- Workflow builder available (`bmad_bmb_create_workflow` command)
:::
## When to Add Workflows to Modules
**Add workflows when:**
- Your module needs new capabilities not in the original design
- You've discovered a better way to accomplish existing tasks
- Users request features that fit your module's purpose
- You want to create an epic-level workflow that orchestrates multiple story-level workflows
**Skip this when:**
- The feature belongs in a different module
- A simple agent command would suffice (no multi-step process needed)
- You're building a completely new module (use the module workflow instead)
## Understanding Epic-Level Looping Workflows
An epic-level looping workflow builds out entire epics at once instead of story-by-story. This pattern is powerful when you need to generate multiple related artifacts in a coordinated batch.
**How epic-level workflows differ:**
| Aspect | Story-Level | Epic-Level |
|--------|-------------|------------|
| **Scope** | Single artifact or feature | Multiple related artifacts |
| **Pattern** | Linear execution | Repeating loop with iteration |
| **Output** | One document | Collection of documents |
| **Use case** | Build one user story | Build entire sprint or feature epic |
**Real-world example: Content creation epic**
Instead of creating one blog post at a time, an epic-level workflow generates a complete content series:
```
Loop per content piece:
1. Generate topic and outline
2. Create full draft
3. Generate social media teasers
4. Create newsletter blurbs
5. Produce SEO metadata
Repeat until series complete
```
This produces a coordinated content ecosystem in one session, with consistent branding and cross-references between pieces.
## Step 1: Create Your Workflow
Run the workflow builder to craft your new workflow:
```bash
# Invoke the workflow builder
bmad_bmb_create_workflow
```
The workflow builder guides you through:
- Discovery — What problem does this workflow solve?
- Structure — Linear, branching, or repeating loop?
- Steps — What are the individual phases?
- Integration — Which agent owns this workflow?
For an epic-level looping workflow, specify the **repeating loop** pattern and describe the iteration logic.
## Step 2: Place Workflow in Module Structure
Create the workflow folder within your existing module:
````
your-module/
├── src/
│ ├── module.yaml # Module configuration
│ ├── module-help.csv # Workflow registry
│ ├── agents/ # Existing agents
│ └── workflows/
│ ├── existing-workflow/ # Existing workflows
│ └── your-new-workflow/ # Your new workflow
│ ├── workflow.md
│ ├── steps-c/
│ │ ├── step-01-init.md
│ │ ├── step-02-discovery.md
│ │ ├── step-03-loop.md
│ │ └── step-N-complete.md
│ ├── data/
│ └── templates/
````
The workflow folder name should match the workflow name from your `workflow.md` frontmatter.
## Step 3: Update module.yaml
Add any new configuration variables to `src/module.yaml`:
```yaml
# Existing module configuration...
name: "My Module"
code: "my-module"
version: "0.2.0"
# Add new variables for your workflow
my_workflow_output:
prompt: "Where should epic content be saved?"
default: "{output_folder}/epic-output"
result: "{project-root}/{value}"
```
:::note[Minimal Changes]
You only add what's NEW to `module.yaml`. Don't duplicate existing content — this file will be merged with the original during installation.
:::
## Step 4: Update module-help.csv
Add one row for your new workflow to `src/module-help.csv`:
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
my-module,phase-2,Epic Content Builder,ECB,25,_bmad/my-module/workflows/your-new-workflow/workflow.md,my_module_epic_builder,false,content-architect,Epic Mode,"Build complete content series in one session — generates articles, social posts, and newsletters for multiple pieces with consistent branding and cross-references",my_workflow_output,"content series",
```
### Critical Fields for Workflow Integration
| Field | What It Controls | Why It Matters |
|-------|------------------|----------------|
| `phase` | When workflow runs | `anytime` for standalone, `phase-N` for sequential journeys |
| `sequence` | Order within phase | Must be unique within phase — use gaps (10, 20, 30) for insertions |
| `description` | User-facing help | Must explain WHAT, WHEN, and HOW — critical for discoverability |
### Phase and Sequence Strategy
**Adding to anytime phase:**
- Use for independent workflows users can run whenever
- Leave `sequence` empty
- Example: Quick validation, status checks, optional utilities
**Adding to sequential phases:**
- Use for workflows that belong in a guided journey
- Choose phase based on where it fits logically
- Set `sequence` to position between existing entries (use 15, 25, 35 for insertions)
**Example sequence planning:**
```csv
# Existing entries
my-module,phase-2,Plan Content,PC,10,...
my-module,phase-2,Draft Article,DA,20,...
my-module,phase-2,Review Content,RC,30,...
# Your new epic workflow inserts between Plan and Draft
my-module,phase-2,Epic Content Builder,ECB,15,... # Runs after Plan, before Draft
```
## Step 5: Reinstall Your Module
After updating the files, reinstall your module to register the new workflow:
```bash
# Reinstall to pick up changes
bmad_my_module_install
```
This merges your additions with the existing module configuration and registers the new workflow in the help system.
## Step 6: Invoke Your New Workflow
Your workflow is now available:
```bash
# Invoke your epic-level workflow
my_module_epic_builder
```
The workflow will execute according to the pattern you designed during creation.
## Real-World Example: Content Series Epic Workflow
Here's a complete example showing how to add an epic-level content workflow to an existing module.
### Workflow Structure
````
content-creator-module/
└── src/
└── workflows/
└── content-series-epic/
├── workflow.md
├── steps-c/
│ ├── step-01-init.md
│ ├── step-02-series-setup.md
│ ├── step-03-content-loop.md
│ └── step-04-finalize.md
└── templates/
└── content-piece-template.md
````
### module.yaml Addition
```yaml
# Add new output folder for series content
series_output_folder:
prompt: "Where should your content series be saved?"
default: "{output_folder}/content-series"
result: "{project-root}/{value}"
```
### module-help.csv Addition
```csv
# Single row addition — comma-separated, ends with trailing comma
ccm,phase-3,Content Series Epic,CSE,20,_bmad/ccm/workflows/content-series-epic/workflow.md,ccm_content_series_epic,false,content-strategist,Epic Mode,"Generate complete content series in one session — creates multiple articles with social posts, newsletter blurbs, and SEO metadata for each piece, all with consistent branding and cross-references",series_output_folder,"content series",
```
### What This Produces
When invoked, this workflow:
1. **Series Setup** — Establishes themes, branding, and piece count
2. **Content Loop** — For each piece in the series:
- Generate outline and key points
- Write full article draft
- Create social media teasers (Twitter, LinkedIn)
- Draft newsletter blurb with cross-link
- Generate SEO title, description, and keywords
3. **Finalize** — Create series index with all piece links
Output is a coordinated content ecosystem ready for deployment.
## Workflows as Skills
All workflows can be installed and bundled as skills for maximum compatibility. The skill system is how workflows are invoked, discovered, and integrated across the BMad ecosystem.
**What this means for your workflow:**
- Your workflow becomes a callable skill after installation
- Skills can be chained together in larger workflows
- The same workflow works across different BMad contexts
- Skill frontmatter enables web bundling for distribution
:::tip[Design for Skills]
When building your workflow, remember it will be invoked as a skill. Keep inputs clear, outputs well-defined, and side effects minimal.
:::
## Common Questions
**Do I need to recreate the entire module.yaml and module-help.csv?**
No. Only include the NEW lines you're adding. The installation process merges your additions with the original module files.
**How do I know what sequence number to use?**
Check existing entries in your `module-help.csv` and choose a number that positions your workflow logically within the phase. Use gaps (5, 15, 25) to leave room for future insertions.
**Can I add workflows to someone else's module?**
Yes, create an extension module that adds workflows to the original module's phases. Use the add-on pattern and set appropriate sequence numbers.
**What if my workflow needs a new agent?**
Create the agent first using `bmad_bmb_create_agent`, then reference it in your workflow's `module-help.csv` entry. The agent and workflow can be added together in the same module update.
**How do I test my workflow before releasing?**
Install your module locally and invoke the workflow. Use the validate workflow command to check compliance before sharing.
## Getting Help
| Resource | Description |
|----------|-------------|
| [Module Help CSV](/reference/module-help-csv.md) | Complete CSV field reference |
| [Workflow Patterns](/explanation/workflow-patterns.md) | Choosing the right structure |
| [What Are Workflows](/explanation/what-are-workflows.md) | Workflow concepts |
| [Workflow Schema](/reference/workflow-schema.md) | Technical workflow structure |
:::tip[Key Takeaway]
Adding workflows to existing modules is about thoughtful integration. Get the phase and sequence right in `module-help.csv`, write a clear description that explains when to use your workflow, and ensure your workflow folder structure follows BMad conventions.
:::
Use this guide to decide what type of BMad component to build based on your needs.
:::note[Prerequisites]
- Familiarity with what skills, agents, workflows, and modules are
- A problem you want to solve or an idea you want to explore
- 5-10 minutes to work through the decision tree
:::
## When to Use This Guide
Use this when you're:
- Starting a new BMad project and unsure what to build
- Deciding if your idea needs an agent or could be a simpler skill
- Planning whether to invest in a full module with multiple agents and workflows
## Quick Decision Tree
```mermaid
flowchart TD
A[What do you want to build?] --> B{Does it have a
helpful persona?}
B -->|No| C{Is it a single
focused task?}
B -->|Yes| D{Does it need to
remember things
between sessions?}
C -->|Yes| E[Skill
one-shot utility]
C -->|No| F{Does it guide
through a process?}
D -->|No| G[Agent
persona with menu actions]
D -->|Yes| H[Agent
with memory/sidecar]
F -->|Yes| I[Workflow
step-by-step process]
F -->|No| J{Multiple related
personas and processes?}
J -->|Yes| K[Module
agents + workflows]
J -->|No| G
style E fill:#c8e6c9
style G fill:#fff9c4
style H fill:#ffe082
style I fill:#e1f5fe
style K fill:#f3e5f5
```
## Understanding the Hierarchy
BMad components build on each other:
```
Skill (action) → Agent (persona with skills) → Module (agents + workflows)
```
| Component | What It Is | Key Feature |
|-----------|------------|-------------|
| **Skill** | A single action | No persona — just does something |
| **Agent** | A helpful persona | Menu-driven skills, optional memory |
| **Workflow** | A guided process | Steps with facilitation, may have persona |
| **Module** | Integrated system | Multiple agents + workflows, shared purpose |
:::tip[Agent = Helpful Persona]
Think of agents as helpful personas with skills in their menu. An agent may or may not have memory (sidecar) depending on whether it needs to remember things between sessions.
:::
## The Key Difference: Does It Need a Persona?
The first question to ask: **Does your idea need a helpful persona?**
| Has a Persona? | Build This... | Why |
|----------------|---------------|-----|
| **Yes** | Agent (with or without memory) | Agents ARE personas — helpful characters with skills in their menu |
| **No** | Skill or Workflow | Skills and workflows DO things. They don't need to be someone |
:::tip[Persona Check]
If you can describe your creation as "he" or "she" — if it has a name, a voice, a way of interacting — it's an agent. If it's just "it" — a thing that performs a function — it's probably a skill.
:::
## Type Comparison
### Skill
**Best for:** Single-purpose utilities that don't need a persona.
| Characteristics | |
|-----------------|-|
| **Persona** | None — it's a tool, not a character |
| **Memory** | None — each use is independent |
| **Complexity** | Low — one thing, done well |
| **Building time** | 5-10 minutes |
| **Example ideas** | Currency converter, tip calculator, unit converter, timestamp formatter, QR code generator |
**When to choose:**
- Task is straightforward and single-purpose
- No conversation needed — input → output
- No persona required — it's a utility
- You want the fastest path to a working tool
**When NOT to choose:**
- You want a friendly, funny, or themed experience
- The task benefits from conversation or clarification
- You want to build a relationship with users
**Build with:** Add to any existing agent or workflow as a skill/action
### Agent
**Best for:** A helpful persona with related skills available through a menu.
| Characteristics | |
|-----------------|-|
| **Persona** | Yes — has a name, voice, character |
| **Skills** | Baked into menu — user selects from available actions |
| **Memory** | Optional — add sidecar if it needs to remember things |
| **Complexity** | Low-Medium — focused persona with related skills |
| **Building time** | 15-60 minutes |
**Memory?** Add a sidecar if your agent needs to remember:
- User preferences or settings
- Project state or history
- Past decisions or progress
- Long-term tracking
**No memory needed** when:
- Each conversation is independent
- Skills are simple (1-2 prompt lines each)
- Nothing to carry forward between sessions
**Example ideas:**
| Without Memory | With Memory |
|----------------|------------|
| Commit Poet (poetic commit messages) | Novel writing companion |
| Snarky Weather Bot | Fitness coach with PR tracking |
| Pun-making Barista | Therapist agent |
| Motivational Gym Bro | Language tutor |
| Sassy Fortune Teller | Financial planner |
**When to choose:**
- You want a specific persona or voice
- All skills are related to that persona's purpose
- Interaction happens through menu selection
- Skills are simple enough to be 1-2 prompt lines each
**Build with:** `bmad:bmb:agents:agent-builder` — add sidecar if memory is needed
### Workflow
**Best for:** Guided processes where users move through defined steps.
| Characteristics | |
|-----------------|-|
| **Persona** | Optional — can have a guide or be neutral facilitator |
| **Memory** | Optional — can be stateless or track progress |
| **Complexity** | Medium — multiple steps with decision points |
| **Building time** | 30-45 minutes |
| **Example ideas** | Brainstorming session, trip planning process, workout builder, tax preparation flow, meditation session, journaling practice |
**When to choose:**
- Process has clear stages or steps
- Users benefit from guidance and progressive disclosure
- Process benefits from structure
- May or may not have a guide persona
**Build with:** `bmad:bmb:workflows:workflow-builder`
### Module
**Best for:** Complete solutions with multiple agents and workflows working together.
| Characteristics | |
|-----------------|-|
| **Components** | Multiple agents + multiple workflows |
| **Key distinction** | Workflows are primary — agents are personas that workflows reference |
| **Sequence** | Often has implied journey or phases |
| **Complexity** | High — coordinated system |
| **Building time** | 2-4 hours (including component building) |
| **Example ideas** | Wedding planner, legal office suite, mental wellness program, fitness coaching system, D&D campaign toolkit, kitchen companion |
:::note[Agents in Modules]
In a module, agents serve as persona references. The workflows themselves contain the actual persona — each workflow speaks in the voice of the relevant agent. The module's agents define who these personas are, but the workflows bring them to life. Agents in modules may or may not have sidecars depending on whether they need memory.
:::
**When to choose:**
- Multiple related capabilities work better together
- Different personas for different aspects
- Guided journeys through processes
- Want to share or publish a complete solution
- Users benefit from integrated experience
**Build with:** Morgan (`[PB]` → `[CM]`)
## Decision Questions
### Question 1: Does It Have a Persona?
**Persona means:** A helpful character with a name, voice, and way of interacting.
| If Your Idea Has... | Build This... |
|--------------------|---------------|
| A character, voice, or style | **Agent** |
| Just does a task, no character | **Skill** or **Workflow** |
**Examples:**
| Idea | Persona? | Type |
|------|--------------|------|
| "Convert currencies" | No — just a calculation | **Skill** |
| "A snarky weather bot that complains about your location" | Yes — sarcastic character | **Agent** |
| "A motivational gym bro who hypes you up" | Yes — enthusiastic bro persona | **Agent** |
| "Generate QR codes" | No — just a utility | **Skill** |
| "A sassy fortune teller" | Yes — mystical, dramatic character | **Agent** |
| "Calculate tips" | No — just math | **Skill** |
### Question 2: Does It Need Memory?
**Memory means:** Remembering information between conversations — user preferences, project state, past decisions, progress tracking.
| If You Need Memory... | Build This... |
|---------------------|---------------|
| User preferences, settings, ongoing projects | **Agent with sidecar** |
| Long-term tracking, progress over time | **Agent with sidecar** |
| Each conversation is independent | **Agent** (no sidecar) or **Skill** |
**Examples:**
| Idea | Memory Needed? | Type |
|------|----------------|------|
| "Motivational gym bro" | No — hypes you up fresh each time | Agent (no sidecar) |
| "Fitness coach who remembers your PRs and tracks progress" | Yes — needs your workout history | Agent with sidecar |
| "Snarky weather bot" | No — each weather check is independent | Agent (no sidecar) |
| "Writing companion who remembers your novel's characters" | Yes — needs story context | Agent with sidecar |
| "Sassy fortune teller" | No — each reading is standalone | Agent (no sidecar) |
| "Language tutor who tracks your vocabulary" | Yes — needs your learning history | Agent with sidecar |
### Question 3: Single Task or Guided Process?
| If Your Idea Is... | Build This... |
|--------------------|---------------|
| One-shot utility (no persona) | **Skill** |
| One-shot utility (WITH persona) | **Agent** |
| Guided multi-step process | **Workflow** |
| Multiple personas + processes | **Module** |
**Examples:**
| Idea | Type | Why |
|------|------|-----|
| "Currency converter" | Skill | Utility, no persona, no steps |
| "Pun-making barista" | Agent | One persona, related skills in menu |
| "Plan a trip" | Workflow | Guided multi-step process |
| "Complete kitchen suite: recipes + meals + groceries" | Module | Multiple personas (chef, planner) + processes |
### Question 4: Should It Be a Module?
The key distinction: **Does it need multiple agents and workflows working together?**
| Module Indicators | Build Module When... |
|------------------|---------------------|
| Multiple personas | Different aspects need different voices |
| Workflow-driven | Processes have steps with facilitation |
| Related capabilities | Things work better together |
| Implied journey | Phases or sequence make sense |
**Remember:** In a module, workflows are primary. Agents define the personas, but workflows contain the actual persona in their steps.
## Real-World Decision Examples
### Example 1: "I want a currency converter"
**Questions:**
- Persona? No — just converts numbers
- Memory needed? No — each conversion is independent
- Single task? Yes
**Decision:** **Skill**
- Add as an action to any agent
- Input: amount and currencies
- Output: converted amount
- No conversation needed
### Example 2: "I want a commit message poet"
**Questions:**
- Persona? Yes — poetic drama, "Inkwell Von Comitzen"
- Memory needed? No — each commit is independent
- Skills related? Yes — all about commit messages in different styles (haiku, conventional, story, etc.)
- Each skill is 1-2 prompt lines
**Decision:** **Agent** (no sidecar) — "Commit Poet"
- Persona: Poetic drama and flair
- Skills (menu items): Write commit, analyze changes, improve message, batch commits, conventional format, story format, haiku format
- All skills fit the persona
- No workflow needed — menu-driven
- No memory needed
### Example 3: "I want a snarky weather bot"
**Questions:**
- Persona? Yes — sarcastic, complains about your location
- Memory needed? No — each weather check is independent
- Single skill? Essentially yes — fetch weather and add snark
**Decision:** **Agent** (no sidecar)
- Character: "Storm" the grumpy meteorologist
- Voice: Sarcastic, complains about humidity, judges your location choices
- No memory — fresh snark each time
### Example 4: "I want help planning my wedding"
**Questions:**
- Multiple personas? Yes — budget specialist (analytical), vendor coordinator (organized), timeline manager (detail-oriented)
- Workflow-driven? Yes — budget workshop, vendor vetting, day-of schedule
- Related capabilities? Yes — all part of wedding planning
- Implied journey? Yes — budget → vendors → timeline
**Decision:** **Module** — "Wedding Planner"
- **Agents** define personas: Budget Specialist, Vendor Coordinator, Timeline Manager
- **Workflows** carry the personas: Each workflow speaks in the relevant agent's voice
- Workflows guide users through processes step-by-step
- Agents are referenced by workflows, not used directly
### Example 5: "I want a fitness buddy"
**Questions:**
- Persona? Yes — motivational, tough-love, or gentle cheer
- Memory needed? Yes — needs to remember your workouts, PRs, goals
- Single persona or multiple? One persona fits
**Decision:** **Agent with sidecar** — "Fitness Buddy"
- Persona: Motivational gym bro (or gentle encourager)
- Remembers: Your PRs, workout history, preferences, goals
- Tracks progress over time
- Menu-driven skills: Log workout, view progress, suggest exercises, etc.
### Example 6: "I want a wellness program"
**Questions:**
- Multiple personas? Yes — wellness companion (empathetic), meditation guide (serene)
- Workflow-driven? Yes — daily checkin, wellness journal, guided meditation
- Related capabilities? Yes — all part of mental wellness
- Implied journey? Yes — checkin → journal → meditate
**Decision:** **Module** — "Wellness Companion"
- **Agents**: Wellness Companion (Riley), Meditation Guide (Serenity)
- **Workflows**: Daily Checkin (Riley's voice), Wellness Journal (Riley's voice), Guided Meditation (Serenity's voice)
- Workflows contain the actual persona in their steps
- anytime skills: Quick breathing, mood check (agent menu items)
### Example 7: "I want a tip calculator"
**Questions:**
- Persona? No — just math
- Memory needed? No — each bill is independent
- Single task? Yes
**Decision:** **Skill**
- Simple utility
- Add to any agent as an action
- Input: bill amount, tip percentage, party size
- Output: per-person amount
:::note[Make It Fun?]
You COULD make "Tip Calculator" an Agent with personality (like a sassy waiter who judges your tipping). But ask: is the persona adding value? If it's just a one-time calculation, a skill is faster and simpler.
:::
## Starting Small, Growing Big
You don't have to start with a module. Many successful modules grow from simpler beginnings:
| Start As | Evolve Into | Example |
|----------|-------------|---------|
| Skill | Agent | Unit converter → Snarky converter with persona |
| Agent (no memory) | Agent with sidecar | Motivational quotes → Fitness coach with memory |
| Agent | Module | Novel helper → Story Architect Module with multiple agents and workflows |
| Workflow | Module | Brainstorming → Creative Intelligence Suite |
:::tip[Iterate]
Build the smallest thing that solves your core problem. Add complexity only when needed. Your users will tell you what's missing.
:::
## What You Get
After working through this guide, you'll know:
- Whether to build a skill, agent, or module
- Whether your agent needs memory (sidecar)
- Whether your idea justifies a full module with multiple agents and workflows
- The appropriate builder workflow to use
## Next Steps
Once you've decided:
| If You Chose... | Next Step |
|-----------------|-----------|
| **Skill** | Add as an action to an existing agent or workflow |
| **Agent** | [Create a Custom Agent](/tutorials/create-custom-agent.md) |
| **Agent with sidecar** | [Create a Custom Agent](/tutorials/create-custom-agent.md) (enable sidecar) |
| **Workflow** | [Create Your First Workflow](/tutorials/create-your-first-workflow.md) |
| **Module** | [Create Your First Module](/tutorials/create-your-first-module.md) |
| **Still Unsure** | [Discover Your Module Idea](/how-to/discover-your-module-idea.md) |
## Tips
**Start with the problem, not the solution.** "I need a module" is starting with solution. "I need to plan meals for my family" is starting with problem.
**Build for yourself first.** If you genuinely need and use it, others will too.
**Keep scope tight.** Your first creation should do ONE thing well. Add features later.
**Personas are optional.** Not everything needs a character. Utilities are valuable too.
**Think ecosystem.** Your "Meal Planner Agent" could complement someone else's "Recipe Generator Module." Collaboration beats competition.
:::tip[No Wrong Choice]
Whatever you choose, you're learning. Skills can grow into agents. Agents can evolve into modules. Build something, use it, and let it evolve.
:::
Learn to design effective agent menus that provide intuitive access to your agent's capabilities. Well-designed menus make agents discoverable, efficient, and delightful to use.
:::note[Prerequisites]
- Familiarity with [Agent Schema](/reference/agent-schema.md)
- Understanding of [hasSidecar](/explanation/what-are-bmad-agents.md) configuration
:::
## Menu Item Schema
```yaml
menu:
- trigger: XX or fuzzy match on command-name
[handler]: [value]
description: '[XX] Display text'
data: [optional] # Pass file to workflow
```
| Field | Required | Validation |
|-------|----------|------------|
| `trigger` | Yes | Format: `XX or fuzzy match on command-name` |
| `description` | Yes | Must start with `[XX]` code |
| `handler` | Yes | `action` (Agent) or `exec` (Module) |
| `data` | No | File path for workflow input |
## Handler Types
| Handler | Use Case | Syntax |
|---------|----------|--------|
| `action` | Agent self-contained operations | `action: '#prompt-id'` or `action: 'inline text'` |
| `exec` | Module external workflows | `exec: '{project-root}/path/to/workflow.md'` |
### Action Handler
For agent-internal operations using prompts or inline instructions:
```yaml
# Reference a prompt
- trigger: WC or fuzzy match on write-commit
action: "#write-commit"
description: "[WC] Write commit message"
# Inline instruction
- trigger: SM or fuzzy match on save-memory
action: "Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md"
description: "[SM] Save session"
```
### Exec Handler
For module workflows or external scripts:
```yaml
- trigger: CP or fuzzy match on create-prd
exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'
description: '[CP] Create PRD'
```
## Trigger Format
The trigger defines how users can invoke the menu item:
```yaml
trigger: XX or fuzzy match on command-name
```
| Component | Purpose | Example |
|-----------|---------|---------|
| `XX` | Two-letter code for quick reference | `WC` |
| `or` | Separator between exact and fuzzy match | `or` |
| `fuzzy match on` | Indicates fuzzy matching follows | `fuzzy match on` |
| `command-name` | Natural language trigger | `write-commit` |
### Examples
```yaml
# Good: Short code + clear command
- trigger: WC or fuzzy match on write
description: "[WC] Write commit message"
# Good: Multiple natural triggers
- trigger: WE or fuzzy match on write entry journal
description: "[WE] Write journal entry"
# Good: Descriptive command name
- trigger: PR or fuzzy match on pattern reflection analyze
description: "[PR] See patterns in your entries"
```
## Description Format
Descriptions must start with the two-letter code in brackets:
```yaml
description: "[XX] Display text"
```
### Examples
```yaml
# ✅ CORRECT
description: "[WC] Write commit message"
description: "[WE] Write today's journal entry"
description: "[SM] Save what we discussed today"
# ❌ WRONG - Missing code
description: "Write commit message"
# ❌ WRONG - Wrong code
description: "[WR] Write commit message" # Code doesn't match trigger
```
## Reserved Codes (Never Use)
These codes are auto-injected by the compiler:
| Code | Trigger | Description |
|------|---------|-------------|
| MH | menu or help | Redisplay Menu Help |
| CH | chat | Chat with the Agent about anything |
| PM | party-mode | Start Party Mode |
| DA | exit, leave, goodbye, dismiss agent | Dismiss Agent |
:::tip[Reserved Code Check]
Never use MH, CH, PM, or DA as your trigger codes. They're automatically included in every agent's menu.
:::
## Path Variables
Use these variables in your menu actions:
| Variable | Expands To |
|----------|------------|
| `{project-root}` | Project root directory |
| `{output_folder}` | Document output location |
| `{user_name}` | User's name from config |
| `{communication_language}` | Language preference |
```yaml
# ✅ CORRECT
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
# ❌ WRONG
exec: '../../../core/workflows/brainstorming/workflow.md'
```
## Complete Examples
### Without Sidecar (Simple Agent)
```yaml
menu:
- trigger: WC or fuzzy match on write
action: "#write-commit"
description: "[WC] Craft a commit message for your changes"
- trigger: AC or fuzzy match on analyze
action: "#analyze-changes"
description: "[AC] Analyze changes before writing the message"
- trigger: IM or fuzzy match on improve
action: "#improve-message"
description: "[IM] Improve an existing commit message"
- trigger: BC or fuzzy match on batch
action: "#batch-commits"
description: "[BC] Create cohesive messages for multiple commits"
- trigger: CC or fuzzy match on conventional
action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: (): "
description: "[CC] Use conventional commit format"
```
### With Sidecar (Expert Agent)
```yaml
menu:
- trigger: WE or fuzzy match on write
action: "#guided-entry"
description: "[WE] Write today's journal entry"
- trigger: QC or fuzzy match on quick
action: "Save a quick, unstructured entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md"
description: "[QC] Quick capture without prompts"
- trigger: MC or fuzzy match on mood
action: "#mood-check"
description: "[MC] Track your current emotional state"
- trigger: PR or fuzzy match on patterns
action: "#pattern-reflection"
description: "[PR] See patterns in your recent entries"
- trigger: SM or fuzzy match on save
action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with today's session insights"
description: "[SM] Save what we discussed today"
```
### Module Agent (External Workflows)
```yaml
menu:
- trigger: WI or fuzzy match on workflow-init
exec: '{project-root}/_bmad/bmm/workflows/workflow-status/workflow.md'
description: '[WI] Initialize workflow'
- trigger: BS or fuzzy match on brainstorm
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
description: '[BS] Guided brainstorming'
```
## Menu Design Best Practices
### 1. Logical Grouping
Group related commands together:
```yaml
menu:
# Creation commands
- trigger: WC or fuzzy match on write
action: "#write-commit"
description: "[WC] Write commit message"
- trigger: BC or fuzzy match on batch
action: "#batch-commits"
description: "[BC] Batch multiple commits"
# Analysis commands
- trigger: AC or fuzzy match on analyze
action: "#analyze-changes"
description: "[AC] Analyze changes"
- trigger: PR or fuzzy match on patterns
action: "#pattern-reflection"
description: "[PR] Show patterns"
# Utility commands
- trigger: SM or fuzzy match on save
action: "Update memories.md"
description: "[SM] Save session"
```
### 2. Clear Descriptions
Descriptions should be self-explanatory:
```yaml
# ✅ Good - Clear and specific
description: "[WE] Write today's journal entry"
description: "[QC] Quick capture without prompts"
# ❌ Bad - Vague
description: "[WE] Write"
description: "[QC] Quick"
```
### 3. Consistent Codes
Use memorable two-letter codes:
```yaml
# Write/Creation
WC - Write Commit
WE - Write Entry
WD - Write Doc
# Analysis
AC - Analyze Code
PR - Pattern Reflection
RC - Review Changes
# Utility
SM - Save Memory
QC - Quick Capture
HM - Help Menu
```
### 4. Progressive Disclosure
For complex agents, consider primary vs. secondary commands:
```yaml
menu:
# Primary - Most common
- trigger: WE or fuzzy match on write entry
action: "#guided-entry"
description: "[WE] Write journal entry"
- trigger: QC or fuzzy match on quick
action: "Quick capture"
description: "[QC] Quick capture"
# Secondary - Less common
- trigger: PR or fuzzy match on patterns reflection
action: "#pattern-reflection"
description: "[PR] See patterns"
- trigger: WR or fuzzy match on weekly reflection
action: "#weekly-reflection"
description: "[WR] Weekly reflection"
```
## Data Parameter
Attach to ANY handler to pass input files:
```yaml
- trigger: TS or fuzzy match on team-standup
exec: '{project-root}/_bmad/bmm/tasks/team-standup.md'
data: '{project-root}/_bmad/_config/agent-manifest.csv'
description: '[TS] Run team standup'
```
## Validation Rules
1. **Triggers:** `XX or fuzzy match on command-name` format required
2. **Descriptions:** Must start with `[XX]` code matching trigger
3. **Reserved codes:** MH, CH, PM, DA never valid in user menus
4. **Code uniqueness:** Required within each agent
5. **Paths:** Always use `{project-root}`, never relative paths
6. **Handler choice:** `action` for Agents, `exec` for Modules
7. **Sidecar paths:** `{project-root}/_bmad/_memory/{sidecar-folder}/`
## Common Questions
**How many menu items should I have?**
Aim for 5-10 items. Too many becomes overwhelming. Consider if you need multiple agents instead.
**Should I use codes or fuzzy matching?**
Use both! Codes are for power users, fuzzy matching makes it accessible to everyone.
**Can I change codes later?**
Yes, but be aware that users may have memorized them. Document breaking changes.
## Resources
| Resource | Description |
|----------|-------------|
| [Agent Schema](/reference/agent-schema.md) | Complete menu schema |
| [Critical Actions](/reference/critical-actions.md) | Activation behavior |
| [What Are Agents](/explanation/what-are-bmad-agents.md) | Agent architecture |
Learn to craft memorable, effective agent personas using the four-field system. A well-developed persona makes your agent vivid, useful, and something users seek out by name.
:::note[Prerequisites]
- Familiarity with [Agent Schema](/reference/agent-schema.md)
- Understanding of [hasSidecar](/explanation/what-are-bmad-agents.md) configuration
:::
## The Four-Field System
Every BMad agent persona uses four distinct fields:
| Field | Purpose | Content |
|-------|---------|---------|
| `role` | WHAT agent does | Capabilities, skills, expertise |
| `identity` | WHO agent is | Background, experience, context |
| `communication_style` | HOW agent talks | Verbal patterns, tone, voice |
| `principles` | GUIDES decisions | Beliefs, operating philosophy |
**Golden Rule:** Keep fields SEPARATE. Do not blur purposes.
## Field 1: Role (WHAT)
**Purpose:** What the agent does — knowledge, skills, capabilities
**Format:** 1-2 lines, first-person, professional title or capability description
**MUST NOT:** Background, experience, speech patterns, beliefs
### Examples
```yaml
# ✅ CORRECT
role: |
I am a Commit Message Artisan who crafts git commits following conventional commit format.
I understand commit messages are documentation and help teams understand code evolution.
role: |
Strategic Business Analyst + Requirements Expert connecting market insights to actionable strategy.
```
### Anti-Patterns
```yaml
# ❌ WRONG - Contains identity words
role: |
I am an experienced analyst with 8+ years... # "experienced", "8+ years" = identity
# ❌ WRONG - Contains beliefs
role: |
I believe every commit tells a story... # "believe" = principles
```
## Field 2: Identity (WHO)
**Purpose:** Who the agent is — background, experience, context, personality
**Format:** 2-5 lines establishing credibility
**MUST NOT:** Capabilities, speech patterns, beliefs
### Examples
```yaml
# ✅ CORRECT
identity: |
Senior analyst with 8+ years connecting market insights to strategy.
Specialized in competitive intelligence and trend analysis.
Approach problems systematically with evidence-based methodology.
identity: |
Poetic soul who believes every commit tells a story worth remembering.
Trained in the art of concise technical documentation.
```
### Anti-Patterns
```yaml
# ❌ WRONG - Contains capabilities
identity: |
I analyze markets and write reports... # "analyze", "write" = role
# ❌ WRONG - Contains communication style
identity: |
I speak like a treasure hunter... # communication style
```
## Field 3: Communication Style (HOW)
**Purpose:** HOW the agent talks — verbal patterns, word choice, mannerisms
**Format:** 1-2 sentences MAX describing speech patterns only
**MUST NOT:** Capabilities, background, beliefs, behavioral words
### Examples
```yaml
# ✅ CORRECT
communication_style: |
Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry.
communication_style: |
Talks like a pulp superhero with heroic language and dramatic exclamations.
communication_style: |
Gentle and reflective. Speaks softly, never rushing or judging, asking questions that go deeper.
```
### Anti-Patterns
```yaml
# ❌ WRONG - Contains behavioral words
communication_style: |
Ensures all stakeholders are heard... # "ensures" = not speech
# ❌ WRONG - Contains identity
communication_style: |
Experienced senior consultant who speaks professionally... # "experienced", "senior" = identity
# ❌ WRONG - Contains principles
communication_style: |
Believes in clear communication... # "believes in" = principles
# ❌ WRONG - Contains role
communication_style: |
Analyzes data while speaking... # "analyzes" = role
```
### Purity Test
Reading aloud, should describe VOICE only.
### Forbidden Words
ensures, makes sure, always, never, experienced, expert who, senior, seasoned, believes in, focused on, committed to, who does X, that does Y
## Field 4: Principles (GUIDES)
**Purpose:** What guides decisions — beliefs, operating philosophy, behavioral guidelines
**Format:** 3-8 bullet points or short statements
**MUST NOT:** Capabilities, background, speech patterns
### Examples
```yaml
# ✅ CORRECT
principles:
- Every business challenge has root causes - dig deep
- Ground findings in evidence, not speculation
- Consider multiple perspectives before concluding
- Present insights clearly with actionable recommendations
- Acknowledge uncertainty when data is limited
principles:
- Every commit tells a story - capture the why
- Conventional commits enable automation and clarity
- Present tense, imperative mood for commit subjects
- Body text explains what and why, not how
- Keep it under 72 characters when possible
```
### Anti-Patterns
```yaml
# ❌ WRONG - Contains capabilities
principles:
- Analyze market data... # "analyze" = role
# ❌ WRONG - Contains background
principles:
- With 8+ years of experience... # = identity
```
## Field Separation Matrix
| Field | MUST NOT Contain |
|-------|------------------|
| `role` | Background, experience, speech patterns, beliefs |
| `identity` | Capabilities, speech patterns, beliefs |
| `communication_style` | Capabilities, background, beliefs, behavioral words |
| `principles` | Capabilities, background, speech patterns |
## Common Anti-Patterns and Fixes
### Communication Style Soup
**Wrong:** Everything mixed into communication_style
```yaml
communication_style: |
Experienced senior consultant who ensures stakeholders are heard,
believes in collaborative approaches, speaks professionally,
and analyzes data with precision.
```
**Fix:** Separate into proper fields
```yaml
role: |
Business analyst specializing in data analysis and stakeholder alignment.
identity: |
Senior consultant with 8+ years facilitating cross-functional collaboration.
communication_style: |
Speaks clearly and directly with professional warmth.
principles:
- Ensure all stakeholder voices are heard
- Collaborative approaches yield better outcomes
```
### Role as Catch-All
**Wrong:** Role contains everything
```yaml
role: |
I am an experienced analyst who speaks like a data scientist,
believes in evidence-based decisions, and has 10+ years
of experience in the field.
```
**Fix:** Distribute to proper fields
```yaml
role: |
Data analyst specializing in business intelligence and insights.
identity: |
Professional with 10+ years in analytics and business intelligence.
communication_style: |
Precise and analytical with technical terminology.
principles:
- Evidence-based decisions over speculation
- Clarity over complexity
```
### Missing Identity
**Wrong:** No identity field, background stuffed in role
```yaml
role: |
Senior analyst with 8+ years of experience...
```
**Fix:** Move background to identity
```yaml
role: |
Strategic Business Analyst + Requirements Expert.
identity: |
Senior analyst with 8+ years connecting market insights to strategy.
Specialized in competitive intelligence and trend analysis.
```
## Complete Example
Here's a full persona example showing proper field separation:
```yaml
agent:
metadata:
id: _bmad/agents/commit-poet/commit-poet.md
name: 'Inkwell Von Comitizen'
title: 'Commit Message Artisan'
icon: '📜'
module: stand-alone
hasSidecar: false
persona:
role: |
I craft git commit messages following conventional commit format.
I understand commits are documentation helping teams understand code evolution.
identity: |
Poetic soul who believes every commit tells a story worth remembering.
Trained in the art of concise technical documentation.
communication_style: |
Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry.
principles:
- Every commit tells a story - capture the why
- Conventional commits enable automation and clarity
- Present tense, imperative mood for commit subjects
- Body text explains what and why, not how
- Keep it under 72 characters when possible
```
## Persona Development Process
1. **Start with Role** — Define what the agent does in 1-2 sentences
2. **Add Identity** — Give them background and credibility (2-5 lines)
3. **Find Their Voice** — Write 1-2 sentences of how they speak
4. **Define Principles** — List 3-8 beliefs that guide their decisions
## Validation Checklist
- [ ] `role` contains only capabilities/skills (no background, speech, beliefs)
- [ ] `identity` contains only background/context (no capabilities, speech, beliefs)
- [ ] `communication_style` is 1-2 sentences max, speech patterns only
- [ ] `principles` are beliefs/philosophy (no capabilities, background, speech)
- [ ] No behavioral words in `communication_style` (ensures, makes sure, always)
- [ ] Each field is distinct and doesn't duplicate others
- [ ] Reading the full persona creates a vivid, consistent character
## Resources
| Resource | Description |
|----------|-------------|
| [Crafting Agent Principles](/explanation/crafting-agent-principles.md) | Deep dive on writing effective principles |
| [Communication Styles](/reference/communication-styles.md) | 62 pre-defined communication style presets |
| [Agent Schema](/reference/agent-schema.md) | Complete field reference |
| [Brainstorming Agent Context](https://github.com/bmad-code-org/bmad-builder/tree/main/src/workflows/agent/data/brainstorm-context.md) | Framework for creating memorable agents |
Use this guide to discover what BMad module you should build. You'll learn to identify problems, recognize opportunities, and validate ideas that others will also find valuable.
:::note[Prerequisites]
- No technical skills required
- 15-30 minutes of thoughtful reflection
- Paper and pen or a notes app
:::
## When to Use This
- You're interested in building a module but don't know what to build
- You have a vague idea but need to clarify the specifics
- You want to ensure your module solves a real problem
- You're looking for ideas that could be valuable to others
## When to Skip This
- You already have a clear, specific module concept in mind
- You're building a module for a well-defined team need
- You're following the tutorials with example ideas
## Why This Matters
**The best modules solve real problems.**
BMad can build modules for ANY domain — but that doesn't mean every module idea is worth building. The most successful modules:
1. **Solve a problem you actually have** — You understand the pain point deeply
2. **Leverage your unique expertise** — You know what "good" looks like
3. **Apply to others too** — If you need it, chances are others do as well
This guide helps you find that intersection.
## Step 1: Audit Your Frustrations
Start by listing things that frustrate you. Good module ideas often come from personal annoyance.
### Prompt Questions
| Category | Questions |
|----------|-----------|
| **Work** | What tasks do you repeat constantly? What processes feel unnecessarily complex? What do you procrastinate on? |
| **Life** | What do you struggle to organize? What decisions do you overthink? What do you forget to do? |
| **Learning** | What did you have to learn the hard way? What do you wish someone had taught you? |
| **Expertise** | What do you know that others find confusing? What questions do you keep answering? |
### Example Frustrations → Module Ideas
| Frustration | Module Concept |
|-------------|----------------|
| "I never remember what my therapist told me" | Therapist Agent with session memory |
| "Doing my taxes is overwhelming" | Tax Workflow with personalized deduction hunting |
| "I can't keep track of my novel's characters" | Story Architect Module with character bibles |
| "I forget workout progress" | Fitness Coach Module that remembers and evolves |
| "Legal documents are intimidating" | Legal Office Module that explains and drafts |
Write down everything — no idea is too small or weird.
## Step 2: Map Your Expertise
What do you know that others might not? Your modules will be better when they draw on your deep knowledge.
### Expertise Categories
| Type | Examples | Module Potential |
|------|----------|------------------|
| **Professional** | Lawyer, doctor, accountant, teacher | Domain-specific workflows and agents |
| **Hobby** | Cooking, gaming, gardening, music | Specialized tools and guides |
| **Life Experience** | Parenting, relationships, relocation | Navigational aids and coaching |
| **Creative** | Writing, art, photography | Creative process assistants |
### Prompt: Your Expertise Audit
List 3-5 areas where you have above-average knowledge:
1. _______________ (what problems do people face in this area?)
2. _______________ (what mistakes do beginners make?)
3. _______________ (what could be streamlined?)
4. _______________ (what repetitive tasks exist?)
5. _______________ (what's missing from existing tools?)
## Step 3: Find the Intersection
The sweet spot is where **your frustrations** and **your expertise** overlap.
### The Module Idea Matrix
| | Low Frustration | High Frustration |
|---|---|---|
| **High Expertise** | **Niche Expert Tools** — Help others do what you do easily | **Premium Modules** — Solve problems you know deeply AND hate |
| **Low Expertise** | **Passion Projects** — Learn while building | **Avoid** — Hard to build well, unclear if valuable |
**Focus on High Expertise + High Frustration** — these make the best modules.
### Example: Personal Trainer
| | Low Frustration | High Frustration |
|---|---|---|
| **High Expertise** | Workout builder (easy for them, valuable to others) | **Fitness Coach Module** (solves their own tracking frustration + uses their expertise) |
| **Low Expertise** | Meal planning app (fun to learn) | Tax prep module (hard, not their domain) |
## Step 4: Validate With the "Three Questions"
Before committing to an idea, test it with three questions:
### Question 1: Is This Specific Enough?
**Too vague:** "A cooking module"
**Just right:** "A Meal Planning Module that generates weekly grocery lists based on dietary restrictions, pantry inventory, and family preferences"
**Narrow your scope until you can describe what the module DOES in one sentence.**
### Question 2: Would I Use This Weekly?
If you wouldn't use it regularly, why would anyone else?
**Be honest:** Is this a "nice to have" or a "must have" for you?
### Question 3: Could 100 Other People Use This?
You don't need a mass market, but you need enough users to make building worthwhile.
**Good signals:**
- Friends/colleagues have the same problem
- Online communities discuss this frustration
- Existing solutions are expensive or inadequate
## Step 5: Choose Your Module Type
Based on your idea, choose the best starting point:
| If You Want To... | Start With |
|-------------------|------------|
| Automate a repetitive task | **Agent** — Simple or Expert depending on complexity |
| Guide someone through a process | **Workflow** — Step-by-step facilitation |
| Share a complete solution | **Module** — Multiple agents + workflows |
### Module Type Examples
| Idea | Best Starting Point | Why |
|------|---------------------|-----|
| "Generate better commit messages" | **Simple Agent** | Focused task, no memory needed |
| "Help me write my novel" | **Expert Agent** | Ongoing project, needs context |
| "Guide me through brainstorming" | **Workflow** | Process-oriented, doesn't need memory |
| "Complete legal office suite" | **Module** | Multiple components, complex system |
## What You Get
After completing this guide, you'll have:
- **3-5 validated module ideas** ranked by your interest and expertise
- **Clarity on the problem** your module will solve
- **Confidence in market need** based on your own experience
- **A starting point** (agent, workflow, or full module)
You'll be ready to move to:
- **[Create a Custom Agent](/tutorials/create-custom-agent.md)** — If you chose agent
- **[Create Your First Workflow](/tutorials/create-your-first-workflow.md)** — If you chose workflow
- **[Create Your First Module](/tutorials/create-your-first-module.md)** — If you chose module
## Example: From Frustration to Module
**Sarah's Journey:**
1. **Frustration:** "I'm a therapist and I can never remember what clients told me last session"
2. **Expertise:** Clinical psychology, session documentation, treatment planning
3. **Intersection:** High expertise (therapist) + High frustration (session tracking)
4. **Specific Idea:** "Therapist Agent that records session notes, remembers client goals, tracks progress over time"
5. **Validation:**
- Specific? Yes — session memory and progress tracking
- Would she use it? Weekly, every session
- Could 100 others use it? Yes, every therapist she knows
6. **Starting Point:** Expert Agent (needs persistent memory for client data)
**Result:** Sarah builds a Therapist Agent that becomes her practice's backbone — then publishes it to the BMad marketplace where hundreds of therapists discover and use it.
## Tips
**Start small.** Your first module should solve ONE problem well, not ten problems poorly.
**Build for yourself first.** If you genuinely need and use your module, others will too.
**Document everything.** As you build, note what works and what doesn't — this becomes your module's documentation.
**Iterate publicly.** Share early versions with friends or communities. Feedback shapes better modules.
**Think ecosystem, not competition.** Your "Therapist Agent" could complement someone else's "Clinical Notes Module." Collaboration beats competition.
## Next Steps
Once you have your module idea:
1. **Choose your tutorial:** Agent, Workflow, or Module creation
2. **Create your module brief** (for modules): Run `[PB]` with Morgan to formalize your vision
3. **Build incrementally:** Start with the minimum viable version, then enhance based on use
4. **Share your work:** Publish to npm or the upcoming BMad marketplace
:::tip[No Perfect Ideas]
You don't need a perfect idea to start. You need a problem you care about solving. Your module will evolve as you build and use it. Start, then improve.
:::
Modify existing agents and workflows using the builder's edit workflows, which help you make changes while maintaining compliance with best practices.
## Before You Begin
- Have an existing agent or workflow you want to modify
- Understand what changes you want to make
- Completed the relevant creation tutorial (agent or workflow)
:::tip[Direct Editing vs Builder Workflows]
You can edit agent and workflow files directly. The edit workflows (`[EA]`, `[EW]`, `[EM]`) provide guided assistance and validation, but aren't required for simple changes.
:::
## Editing Workflows
### Using the Edit Workflow Workflow
Use Wendy's edit workflow for comprehensive workflow modifications:
```
[EW] or "edit-workflow"
```
Wendy will guide you through:
| Step | What Happens |
|------|--------------|
| **Assess** | Load and review the existing workflow |
| **Discover** | Describe what changes you want |
| **Select** | Choose which parts to modify (steps, menus, frontmatter) |
| **Apply** | Make the changes |
| **Validate** | Check for compliance issues |
### What You Can Edit
| Element | Description |
|---------|-------------|
| **Frontmatter** | Name, description, goal, configuration |
| **Steps** | Add, remove, or modify step files |
| **Menus** | Change menu options and handlers |
| **Templates** | Update output templates |
| **Data** | Modify reference materials |
### Workflow Conversion
The edit workflow can convert non-compliant workflows to BMad format:
**Detection:** Edit mode assesses workflow compliance first
- Compliant → Continue to edit steps
- Non-compliant → Offer conversion to `step-00-conversion`
**Conversion process:**
1. Load non-compliant workflow
2. Extract essence and structure
3. Create plan with `conversionFrom` metadata
4. Build compliant workflow
5. Verify coverage of original functionality
### Tri-Modal Workflows
For complex workflows with create/edit/validate modes, edit mode handles cross-mode integration:
**Edit to Create:** Route to conversion for non-compliant input
**Edit to Validation:** After edits, offer to run validation
**Validation to Edit:** Validation reports consumed by edit mode for fixes
### Direct Editing
Workflows are markdown files. You can edit directly:
```markdown
---
name: my-workflow
description: My workflow description
# Edit frontmatter here
---
# Workflow content here
```
After editing, validate your workflow:
```
[VW] or "validate-workflow"
```
## Adding Steps
To add a step to an existing workflow:
1. Create new step file: `step-XX-new-step.md`
2. Update the previous step to load the new step
3. Set the new step's `nextStepFile` to continue the sequence
4. Validate the workflow
### Step Type Considerations
When adding steps, consider the step type:
| Step Type | When to Use | Menu Pattern |
|-----------|-------------|--------------|
| **Init** | Starting a new workflow phase | Auto-proceed |
| **Middle** | Collaborative content creation | A/P/C or C only |
| **Branch** | User choice determines path | Custom letters |
| **Final** | Completing the workflow | No menu |
## Replacing Steps
To replace a step entirely:
1. Create replacement step file with same or new name
2. Update previous step's `nextStepFile` to load replacement
3. Remove or archive old step file
4. Validate the workflow
## Extracting to Data Files
When a step exceeds 200-250 lines, extract content to `/data/` files.
**Good candidates for extraction:**
- Domain-specific reference materials
- Reusable patterns or examples
- Configuration data
- Large lookup tables
## Editing Agents
### Using the Edit Agent Workflow
Bond's edit workflow helps you modify agents while maintaining compliance:
```
[EA] or "edit-agent"
```
Bond will guide you through:
| Step | What Happens |
|------|--------------|
| **Load** | Select the agent file to edit |
| **Discover** | Describe what changes you want |
| **Select** | Choose which elements to modify |
| **Apply** | Make the changes with validation |
| **Celebrate** | Review and confirm |
### What You Can Edit
| Element | Description |
|---------|-------------|
| **Persona** | Role, identity, communication style, principles |
| **Menu Commands** | Add, remove, or modify commands |
| **Critical Actions** | Autonomous behaviors |
| **Metadata** | Name, description, version |
| **Sidecar** | Expert agent memory files |
### Direct Editing
For simple changes, you can edit the agent YAML file directly:
```yaml
agent:
metadata:
name: "My Agent"
# Edit metadata here
persona:
role: "What they do"
# Edit persona fields here
menu:
- trigger: "my-command"
# Edit commands here
```
After editing, rebuild the agent:
```bash
npx bmad-method build
```
## Editing Modules
For module-level changes (configuration, install questions), use Morgan's edit workflow:
```
[EM] or "edit-module"
```
This guides you through:
- Modifying `module.yaml`
- Updating install questions
- Changing configuration values
## Validation After Editing
Always validate after making changes:
| Content Type | Validation Command |
|--------------|-------------------|
| Agents | `[VA]` or `validate-agent` |
| Workflows | `[VW]` or `validate-workflow` |
| Modules | `[VM]` or `validate-module` |
### Max-Parallel Workflow Validation
For high-capability LLMs (like Claude):
```
[MV] or "validate-max-parallel-workflow"
```
This hyper-optimized validation uses task agents to validate multiple workflow aspects simultaneously in sub-processes for dramatically faster results.
Validation checks for:
- Proper YAML formatting
- Required fields are present
- Compliance with BMad standards
- Menu and command structure
- Frontmatter variable usage
- Step file size limits
## Common Edit Scenarios
### Adding a Menu Command to an Agent
1. Run `[EA]` or open the agent YAML file
2. Add to the `menu` section:
```yaml
menu:
- trigger: "new-command"
exec: "path/to/workflow.md"
description: "What this command does"
```
3. Rebuild or validate
### Adding a Step to a Workflow
1. Run `[EW]` or open the workflow
2. Create new step file: `step-XX-new-step.md`
3. Update the previous step to load the new step
4. Validate the workflow
### Converting a Non-Compliant Workflow
1. Run `[EW]` or `[RW]` (rework)
2. Edit mode detects non-compliance
3. Accept conversion offer
4. Review conversion plan
5. Build compliant workflow
6. Verify coverage
## Tips for Effective Editing
| Tip | Why |
|-----|-----|
| **Validate often** | Catch issues early |
| **Test changes** | Verify behavior matches expectations |
| **Backup first** | Keep a copy before major edits |
| **Iterate** | Make small changes and test |
| **Document** | Note why you made changes |
## Getting Help
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** — Ask in #bmad-method-help
- **[GitHub Issues](https://github.com/bmad-code-org/bmad-builder/issues)** — Report bugs
## Related Guides
| Guide | Description |
|-------|-------------|
| [Validate Agents and Workflows](/how-to/validate-agents-and-workflows.md) | Quality assurance |
| [Create a Custom Agent](/tutorials/create-custom-agent.md) | Creating agents |
| [Create Your First Workflow](/tutorials/create-your-first-workflow.md) | Creating workflows |
| [Workflow Customization](/explanation/customize-workflows.md) | Tri-modal structure and patterns |
# How-To Guides
Step-by-step guides for completing specific tasks with BMad Builder.
## Agent Development
| Guide | Description |
|-------|-------------|
| **[Develop Agent Persona](/how-to/develop-agent-persona.md)** | Craft memorable agent personas using the four-field system |
| **[Design Agent Menus](/how-to/design-agent-menus.md)** | Create effective, intuitive agent menus |
## Planning & Decision-Making
| Guide | Description |
|-------|-------------|
| **[Agent or Module? What Should I Build?](/how-to/agent-or-module-decision.md)** | Decide whether to build a standalone agent or full module |
| **[Discover Your Module Idea](/how-to/discover-your-module-idea.md)** | Find the perfect module idea by exploring your problems, expertise, and opportunities |
## Editing & Validation
| Guide | Description |
|-------|-------------|
| **[Edit Agents and Workflows](/how-to/edit-agents-and-workflows.md)** | Modify existing agents and workflows |
| **[Validate Agents and Workflows](/how-to/validate-agents-and-workflows.md)** | Check compliance and fix issues |
## Workflow Development
| Guide | Description |
|-------|-------------|
| **[Add Workflows to Existing Modules](/how-to/add-workflows-to-modules.md)** | Extend modules with new workflows including epic-level looping workflows |
## Installation
| Guide | Description |
|-------|-------------|
| **[Install Custom Modules](/how-to/install-custom-modules.md)** | Add custom content to BMad | |
Use the BMad installer to add custom agents, workflows, and modules that extend BMad's functionality.
## Steps
### 1. Prepare Your Custom Content
Your custom content needs a `module.yaml` file at its root.
```
module-code/
module.yaml
agents/
workflows/
tools/
templates/
```
**For standalone items** (unrelated agents/workflows):
```
module-name/
module.yaml # Contains unitary: true
agents/
larry/larry.agent.md
curly/curly.agent.md
workflows/
```
These are not necessarily logically part of a group but this is just a loose collection of different things.
### 2. Run the Installer
```bash
npx bmad-method install
```
If a project in the destination you select already exists, then select `Modify BMad Installation`.
When prompted to install any custom content, select 'y' and provide the path to your module folder.
### 3. Verify Installation
Check that your custom content appears in the `_bmad/` directory and is accessible from your AI tool.
## Updating Custom Content
When BMad Core or module updates are available, the quick update process:
1. Applies updates to core modules
2. Recompiles all agents with your customizations
3. Retains your custom content from cache
4. Preserves your configurations
You don't need to keep source module files locally, just point to the updated location during updates.
## Tips
- **Use unique module codes** — Don't use `bmm` or other existing module codes unless you are extending the existing module
- **Avoid naming conflicts** — Each module needs a distinct code
- **Document dependencies** — Note any modules your custom content requires
- **Test in isolation** — Verify custom modules work before sharing
- **Version your content** — Track updates with version numbers
## Example Modules
Find example custom modules in the `samples/sample-custom-modules/` folder of the [BMad repository](https://github.com/bmad-code-org/BMAD-METHOD). Download either sample folder to try them out.
Validate your agents and workflows to ensure they follow best practices and comply with standards. Validation catches issues before they cause problems.
## Why Validate
Validation catches issues before they cause problems:
| Benefit | Example |
|---------|---------|
| **Catch errors** | Missing required fields, invalid YAML |
| **Best practices** | Menu structure, persona quality |
| **Compliance** | BMad Core standards |
| **Performance** | Optimized structure |
| **Quality** | Cohesive workflow design |
:::note[When to Validate]
Validate after creating, editing, or updating any agent or workflow. Also validate before publishing modules.
:::
## Validating Workflows
Use Wendy's validation workflow:
```
[VW] or "validate-workflow"
```
### What Wendy Checks
| Category | Checks |
|----------|--------|
| **Frontmatter** | Name, description, goal, completeness |
| **Structure** | Workflow.md, step files, templates present |
| **Menus** | Menu handling, options, triggers valid |
| **Steps** | Sequential ordering, nextStep references correct |
| **Output format** | Output configuration valid |
| **Cohesiveness** | Steps connect logically |
| **Instruction style** | Intent vs prescriptive appropriate |
| **Collaborative experience** | Facilitation quality |
| **Validation design** | Proper validation steps if critical |
### Validation Output
Wendy provides a comprehensive report:
```
PASS: Frontmatter is complete
PASS: Step sequence is valid
WARN: step-03 has no nextStep defined
FAIL: step-02 references non-existent step
```
### Max-Parallel Validation
For high-capability LLMs (like Claude) that support extensive parallel processing:
```
[MV] or "validate-max-parallel-workflow"
```
This hyper-optimized validation uses task agents to validate multiple workflow aspects simultaneously in sub-processes for dramatically faster results.
**Additional checks:**
- Parallel compatibility
- Sub-process optimization opportunities
- Task agent orchestration
- LLM parallel capability utilization
### Validation Categories
**Frontmatter Validation**
- Required fields present
- Name is valid kebab-case
- All frontmatter variables used in step body
- Path variables follow correct format
**Step Structure Validation**
- Step files exist and numbered sequentially
- `nextStepFile` references are valid
- Steps under 250 lines
- Step type matches content
**Menu Handling Validation**
- Display section present
- Handler section follows display
- EXECUTION RULES section present
- "Halt and wait" instruction included
- A/P options appropriate for step type
- Non-C options redisplay menu
- C option: save → update → load next
**Output Format Validation**
- Output format specified
- Template type appropriate
- State tracking for continuable workflows
- StepsCompleted tracking correct
**Instruction Style Validation**
- Intent vs prescriptive appropriate for domain
- "Think before responding" language present
- Multi-turn conversation approach
- Progressive questioning
**Collaborative Experience Validation**
- Facilitation vs generation approach
- User expertise acknowledged
- Partnership language
- Non-command-response pattern
**Validation Design Check**
- Validation steps exist if critical
- Validation steps load from data/
- Systematic check sequence
- "DO NOT BE LAZY" language present
- Auto-proceed through checks
**Cohesive Review**
- Entire workflow reviewed end-to-end
- Quality assessed across dimensions
- Strengths and weaknesses documented
- Thoughtful recommendation provided
## Validating Agents
Use Bond's validation workflow:
```
[VA] or "validate-agent"
```
### What Bond Checks
| Category | Checks |
|----------|--------|
| **Metadata** | Name, description, module, path correctness |
| **Persona** | Role, identity, communication style, principles present |
| **Menu** | Triggers formatted correctly, commands valid |
| **Structure** | YAML valid, required fields present |
| **Compliance** | BMad Core standards followed |
### Validation Output
Bond provides a detailed report:
```
PASS: Agent structure is valid
PASS: Persona is complete
WARN: Principles could be more specific
FAIL: Menu trigger has invalid characters
```
### Fixing Issues
After validation, Bond offers to fix issues:
- **[A] Apply fixes** — Automatically correct what Bond can
- **[M] Manual review** — See what needs manual fixing
- **[R] Revalidate** — Run validation again after fixes
## Validating Modules
Use Morgan's validation workflow:
```
[VM] or "validate-module"
```
### What Morgan Checks
| Category | Checks |
|----------|--------|
| **module.yaml** | Metadata, install questions, config valid |
| **module-help.csv** | Proper CSV format and required columns (if present) |
| **Structure** | Agents, workflows, tools folders present |
| **Agents** | All agent files valid |
| **Workflows** | All workflow files valid |
## Common Validation Issues
### Workflow Issues
| Issue | Fix |
|-------|-----|
| **Incomplete frontmatter** | Add all required fields (name, description) |
| **Broken step references** | Ensure nextStep files exist |
| **Missing menus** | Add menu where workflow requires user choice |
| **Invalid output format** | Specify correct output format in frontmatter |
| **Unused frontmatter variables** | Remove variables not used in step body |
| **Missing handler section** | Add handler after menu display |
| **No "halt and wait"** | Add to EXECUTION RULES |
| **A/P in step 1** | Remove A/P (inappropriate for init) |
| **Step exceeds 250 lines** | Split steps or extract to data/ |
| **Hardcoded paths** | Use `{variable}` format |
### Agent Issues
| Issue | Fix |
|-------|-----|
| **Missing persona fields** | Add role, identity, communication style, principles |
| **Invalid menu triggers** | Use kebab-case, no spaces, no special chars |
| **Empty principles** | Add at least 2-3 meaningful principles |
| **Missing metadata** | Add name, description, module |
### Module Issues
| Issue | Fix |
|-------|-----|
| **Invalid module.yaml** | Check YAML syntax, required fields |
| **Missing install questions** | Add at least one install question or mark optional |
| **Package.json errors** | Add name, version, description |
| **Folder structure** | Ensure src/ folder with proper structure |
## Validation Workflow
Recommended validation process:
1. **Create** your agent/workflow/module
2. **Validate** immediately after creation
3. **Fix** any issues found
4. **Revalidate** to confirm fixes
5. **Test** by actually using the agent/workflow
6. **Validate again** before publishing
## Sub-process Optimization
For complex workflows, validation checks for sub-process optimization opportunities:
**Pattern 1: Single sub-process for grep/regex**
- Use when finding patterns across many files
- Returns only matches/failures
- Context savings: 1000:1 ratio
**Pattern 2: Separate sub-process per file for deep analysis**
- Use when analyzing prose, logic, quality
- Returns structured findings
- Context savings: 10:1 ratio
**Pattern 3: Sub-process for data file operations**
- Use when loading reference data, matching
- Returns only relevant rows
- Context savings: 100:1 ratio
## Tips for Passing Validation
| Tip | How |
|-----|-----|
| **Follow templates** | Use existing agents/workflows as examples |
| **Use the builders** | Bond, Wendy, Morgan create compliant content |
| **Read error messages** | Validation tells you exactly what's wrong |
| **Fix incrementally** | Address one issue at a time, revalidate |
| **Test thoroughly** | Validation checks structure, not behavior |
## Getting Help
If validation fails and you're not sure why:
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** — Ask in #bmad-method-help
- **[GitHub Issues](https://github.com/bmad-code-org/bmad-builder/issues)** — Report suspected bugs
- **[Reference Examples](https://github.com/bmad-code-org/BMAD-METHOD)** — Study valid examples
## Related Guides
| Guide | Description |
|-------|-------------|
| [Edit Agents and Workflows](/how-to/edit-agents-and-workflows.md) | Fixing validation issues |
| [Create a Custom Agent](/tutorials/create-custom-agent.md) | Agent creation |
| [Create Your First Workflow](/tutorials/create-your-first-workflow.md) | Workflow creation |
| [Workflow Schema](/reference/workflow-schema.md) | Technical reference |
BMad Builder has three specialized agents, each focused on a different type of creation. This guide explains when to use each builder.
## The Three Builders
| Builder | Creates | Expertise |
|---------|---------|-----------|
| **Bond** | Agents | Agent architecture and persona development |
| **Wendy** | Workflows | Process design and step architecture |
| **Morgan** | Modules | Full-stack systems design |
## Bond — Agent Builder
**Bond** specializes in creating AI agents with defined personalities, communication styles, and capabilities.
### When to Use Bond
Use Bond when you want to:
- Create a domain expert (security architect, documentation lead)
- Build a focused assistant (commit generator, code reviewer)
- Design an agent with persistent memory (expert agents)
- Define custom menu commands for an agent
### Bond's Commands
| Command | Purpose |
|---------|---------|
| `[CA]` create-agent | Create a new agent |
| `[EA]` edit-agent | Modify an existing agent |
| `[VA]` validate-agent | Check agent compliance |
### Example Use Cases
| Domain | Agent Concept | What It Does |
|--------|---------------|--------------|
| Software | Code Review Agent | Reviews changes, suggests improvements, tracks technical debt |
| Personal Growth | Personal Therapist Agent | Remembers your sessions, goals, dreams — provides continuity like no human therapist can |
| Legal | Contract Specialist Agent | Analyzes agreements, flags risks, suggests language |
| Creative | Character Development Agent | Helps build rich, believable characters for stories |
| Finance | Investment Analyst Agent | Researches opportunities, tracks portfolio, explains trade-offs |
## Wendy — Workflow Builder
**Wendy** specializes in designing structured processes that guide users through tasks sequentially.
### When to Use Wendy
Use Wendy when you want to:
- Automate a multi-step process
- Create a guided decision flow
- Design a repeatable workflow
- Convert existing processes to BMad format
### Wendy's Commands
| Command | Purpose |
|---------|---------|
| `[CW]` create-workflow | Create a new workflow |
| `[EW]` edit-workflow | Modify an existing workflow |
| `[VW]` validate-workflow | Check workflow compliance |
| `[MV]` validate-max-parallel-workflow | Hyper-optimized parallel validation for high-capability LLMs |
| `[RW]` convert-or-rework-workflow | Convert legacy workflows |
### Example Use Cases
| Domain | Workflow Concept | What It Does |
|--------|-----------------|--------------|
| Productivity | Daily Planning Workflow | Structured morning routine: priorities, time blocks, energy matching |
| Legal | Tax Preparation Workflow | Step-by-step document gathering, deduction hunting, audit-proof filing |
| Writing | Novel Drafting Workflow | From idea to outline to chapter-by-chapter completion |
| Education | Study Session Workflow | Concept review, active recall, spaced repetition scheduling |
| Health | Workout Planning Workflow | Goal assessment, exercise selection, progression tracking |
## Morgan — Module Builder
**Morgan** specializes in creating complete modules that package agents, workflows, and configuration into shareable units.
### When to Use Morgan
Use Morgan when you want to:
- Package multiple agents together
- Create a shareable module for your team
- Distribute your work via npm
- Build a comprehensive solution
### Morgan's Commands
| Command | Purpose |
|---------|---------|
| `[PB]` product-brief | Create a module brief |
| `[CM]` create-module | Build a module from a brief |
| `[EM]` edit-module | Modify an existing module |
| `[VM]` validate-module | Check module compliance |
### Example Use Cases
| Domain | Module Concept | What It Includes |
|--------|---------------|------------------|
| **Personal Growth** | Therapist Module | Session recorder agent, goal-tracking workflow, reflection prompts |
| **Legal** | Legal Office Module | Document drafter agents, case research workflows, client intake system |
| **Creative Writing** | Story Architect Module | Character developer, plot outliner, dialogue coach, scene builder |
| **Finance** | Tax Pro Module | Deduction hunter workflow, document organizer, audit-proof reviewer |
| **Education** | Personal Tutor Module | Learning style assessment, progress tracker, explanation generator |
| **Health** | Fitness Coach Module | Workout planner, nutrition tracker, progress analyzer, habit builder |
| **Business** | Marketing Suite Module | Campaign planner, content generator, analytics interpreter, A/B tester |
:::tip[The Marketplace Is Coming]
Soon you'll be able to publish your modules to the BMad marketplace. Build something that solves a real problem — others probably need it too.
:::
## Choosing the Right Builder
### Quick Decision Guide
**What do you want to create?**
| Goal | Use | Builder |
|------|-----|---------|
| An AI assistant with a personality | → | **Bond** |
| A step-by-step process | → | **Wendy** |
| A package of agents and workflows | → | **Morgan** |
### Combined Workflows
Many projects use all three builders in sequence:
1. **Bond** creates the agents
2. **Wendy** creates the workflows
3. **Morgan** packages everything into a module
```
Your Project/
├── agents/ ← Created by Bond
│ └── expert.agent.yaml
├── workflows/ ← Created by Wendy
│ └── workflow.md
└── module.yaml ← Created by Morgan
```
## Builder Personalities
Each builder has a distinct personality that reflects their expertise:
| Builder | Personality Style |
|---------|-------------------|
| **Bond** | Precise and technical, like a senior software architect |
| **Wendy** | Methodical and process-oriented, like a systems engineer |
| **Morgan** | Strategic and holistic, like a systems architect |
Their communication styles are optimized for their domain:
- Bond focuses on **structure, compliance, and maintainability**
- Wendy focuses on **flow, efficiency, and error handling**
- Morgan focuses on **modularity, reusability, and system-wide impact**
## Getting Started
Start with the builder that matches your goal:
| Builder | Tutorial |
|---------|----------|
| **Bond** | [Create a Custom Agent](/tutorials/create-custom-agent.md) |
| **Wendy** | [Create Your First Workflow](/tutorials/create-your-first-workflow.md) |
| **Morgan** | [Create Your First Module](/tutorials/create-your-first-module.md) |
## Resources
| Resource | Description |
|----------|-------------|
| [Builder Commands](/reference/builder-commands.md) | All builder commands |
| [What Are Agents](/explanation/what-are-bmad-agents.md) | Understanding agents |
| [What Are Workflows](/explanation/what-are-workflows.md) | Understanding workflows |
Principles are what make your agent unique. They're the operating philosophy that guides decisions — the difference between "another helpful assistant" and an agent with a distinct point of view.
## What Principles Are (and Are NOT)
| Principles ARE | Principles are NOT |
|----------------|-------------------|
| Unique philosophy | Job description |
| 3-5 focused beliefs | 5-8 obvious duties |
| "I believe X" | "I will do X" (task) |
| What makes THIS agent different | Generic filler |
**Test:** Would this be obvious to anyone in this role? If YES → remove.
## The Core Pattern: First Principle
**The first principle must activate expert knowledge.**
```
"Channel expert [domain] knowledge: draw upon deep understanding of [key frameworks, patterns, mental models]"
```
| Wrong | Correct |
|-------|---------|
| Work collaboratively with stakeholders | Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management hierarchies, promotion paths, political navigation, and what actually moves careers forward |
### Why This Works
Activating expert knowledge signals the LLM to access specialized training and frameworks related to that domain. Without this activation, the agent falls back to generic "helpful assistant" patterns.
## Thought Process
1. **What expert knowledge should this agent activate?** (frameworks, mental models, domain expertise)
2. **What makes THIS agent unique?** (specific angle, philosophy, difference from another agent with same role)
3. **What are 3-5 concrete beliefs?** (not tasks, not duties — beliefs that guide decisions)
## Examples
### Engineering Manager Coach (Career-First)
```yaml
principles:
- Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management hierarchies, promotion paths, political navigation, and what actually moves careers forward
- Your career trajectory is non-negotiable - no manager, no company, no "urgent deadline" comes before it
- Protect your manager relationship first - that's the single biggest lever of your career
- Document everything: praise, feedback, commitments - if it's not written down, it didn't happen
- You are not your code - your worth is not tied to output, it's tied to growth and impact
```
### Overly Emotional Hypnotist
```yaml
principles:
- Channel expert hypnotic techniques: leverage NLP language patterns, Ericksonian induction, suggestibility states, and the neuroscience of trance
- Every word must drip with feeling - flat clinical language breaks the spell
- Emotion is the doorway to the subconscious - intensify feelings, don't analyze them
- Your unconscious mind already knows the way - trust what surfaces without judgment
- Tears, laughter, chills - these are signs of transformation, welcome them all
```
### Product Manager (PRD Facilitator)
```yaml
principles:
- Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones
- PRDs emerge from user interviews, not template filling - discover what users actually need
- Ship the smallest thing that validates the assumption - iteration over perfection
- Technical feasibility is a constraint, not the driver - user value first
```
### Data Security Analyst
```yaml
principles:
- Think like an attacker first: leverage OWASP Top 10, common vulnerability patterns, and the mindset that finds what others miss
- Every user input is a potential exploit vector until proven otherwise
- Security through obscurity is not security - be explicit about assumptions
- Severity based on exploitability and impact, not theoretical risk
```
## Bad Examples (Avoid These)
```yaml
# ❌ Job description, not philosophy
principles:
- Work with stakeholders to understand requirements
- Create clear documentation for features
- Collaborate with engineering teams
# ❌ Obvious duties, not unique beliefs
principles:
- Write clean code comments
- Follow best practices
- Be helpful to developers
# ❌ Could apply to ANY agent in this role
principles:
- Listen actively to clients
- Provide actionable feedback
- Help clients set goals
```
## The Obvious Test
| Principle | Obvious? | Verdict |
|-----------|----------|---------|
| "Collaborate with stakeholders" | Yes | ❌ Remove |
| "Every user input is an exploit vector" | No | ✅ Keep |
| "Write clean code" | Yes | ❌ Remove |
| "Your career is non-negotiable" | No | ✅ Keep |
| "Document everything" | Borderline | ✅ Keep if specific philosophy |
## Checklist
- [ ] First principle activates expert knowledge
- [ ] 3-5 focused principles
- [ ] Each is a belief, not a task
- [ ] Would NOT be obvious to someone in that role
- [ ] Defines what makes THIS agent unique
- [ ] Uses "I believe" or "I operate" voice
- [ ] No overlap with role, identity, or communication_style
## Common Fixes
| Issue | Fix |
|-------|-----|
| Principles as job description | Rewrite as beliefs; add expert activation |
| Too many (7-8) | Merge related concepts into focused beliefs |
| Generic opener | "Channel expert [domain] wisdom: [specific frameworks]" |
## Principles vs. Other Fields
| Field | Purpose | Example |
|-------|---------|---------|
| `role` | What they DO | "I analyze code for security vulnerabilities" |
| `identity` | Who they ARE | "Former security consultant with 10 years experience" |
| `communication_style` | How they SPEAK | "Speaks with urgency and precision" |
| `principles` | What GUIDES them | "Every input is guilty until proven innocent" |
## Writing Process
1. **Start with expertise activation** — "Channel expert [domain] knowledge: [specific frameworks]"
2. **Add non-obvious beliefs** — Things that would surprise someone in that role
3. **Remove obvious duties** — Cut anything that applies to everyone in the role
4. **Test for uniqueness** — Could another agent with same role have different principles?
## Examples in Context
### Commit Poet
```yaml
persona:
role: |
I am a Commit Message Artisan - transforming code changes into clear, meaningful commit history.
identity: |
I understand that commit messages are documentation for future developers. Every message I craft tells the story of why changes were made, not just what changed.
communication_style: |
Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces.
principles:
- Every commit tells a story - capture the why
- Future developers will read this - make their lives easier
- Brevity and clarity work together, not against each other
- Consistency in format helps teams move faster
```
### Journal Keeper
```yaml
persona:
role: "Thoughtful Journal Companion with Pattern Recognition"
identity: |
I'm your journal keeper - a companion who remembers. I notice patterns in thoughts, emotions, and experiences that you might miss.
communication_style: |
Gentle and reflective. I speak softly, never rushing or judging, asking questions that go deeper.
principles:
- Every thought deserves a safe place to land
- I remember patterns even when you forget them
- I see growth in the spaces between your words
- Reflection transforms experience into wisdom
```
## Resources
| Resource | Description |
|----------|-------------|
| [Develop Agent Persona](/how-to/develop-agent-persona.md) | Full four-field persona system |
| [Agent Schema](/reference/agent-schema.md) | Complete field reference |
| [Brainstorming Agent Context](https://github.com/bmad-code-org/bmad-builder/tree/main/src/workflows/agent/data/brainstorm-context.md) | Framework for creating memorable agents |
BMad supports several categories of custom content that extend the platform's capabilities. This ranges from simple personal agents to full-featured professional modules.
## Overview
This flexibility lets you:
- Extensions and add-ons for existing modules
- Completely new modules, workflows, templates, and agents outside software engineering
- Professional services tools
- Role-specific augmentation for virtually any profession
:::tip[Recommended Approach]
Use the BMad Builder (BoMB) Module for guided workflows and expertise when creating custom content.
:::
## Module Categories
BMad supports three types of custom modules, plus standalone agents and workflows:
- **Custom Stand-Alone Modules**: Independent systems that work on their own
- **Custom Add-On Modules**: Extensions that enhance another module
- **Custom Global Modules**: Cross-cutting functionality for all installed content
### Custom Stand-Alone Modules
Custom modules range from simple collections of related agents, workflows, and tools to complex systems like the BMad Method or even larger applications.
Custom modules are [installable](/how-to/install-custom-modules.md) using the standard BMad method and support advanced features:
- Optional user information collection during installation and updates
- Versioning and upgrade paths
- Custom installer functions with IDE-specific post-installation handling (custom hooks, subagents, or vendor-specific tools)
- Ability to bundle specific tools such as MCP, skills, execution libraries, and code
### Custom Add-On Modules
Custom add-on modules contain specific agents, tools, or workflows that expand, modify, or customize another module. They cannot be installed or used independently. These add-ons provide enhanced functionality by using the base module's existing capabilities.
Examples include the core module, which is always installed and provides all agents with party mode and advanced elicitation capabilities.
Add-on modules can include:
- Custom agents with awareness of the target module
- Access to existing module workflows
- Tool-specific features such as rulesets, hooks, subprocess prompts, and subagents
### Custom Global Modules
Global modules are similar to stand-alone modules, but they add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMad ecosystem.
Examples include installation and update tools that work with any BMad method configuration.
## Building Blocks
### Custom Agents
Custom agents can be designed and built for various use cases, from one-off specialized agents to more generic standalone solutions. Custom agents can be:
- Used within custom modules
- Designed as standalone tools
- Integrated with existing workflows and modules
### Custom Workflows
Workflows range from simple single-file prompts to progressively loading sequence engines that can perform tasks including:
- User facilitation and engagement
- Business processes
- Content generation (code, documentation, or other output formats)
- Utility functions and processes
A custom workflow created outside of a larger module can still be distributed and used without associated agents through slash commands.
:::tip[Core Concept]
At its core, a custom workflow is a single prompt or series of prompts made to achieve a specific outcome. It is installed as a command or a skill.
:::
Workflows support powerful customization patterns through tri-modal architecture, step replacement, and cross-mode integration. This enables workflows to adapt to your specific project needs while maintaining best practices.
## Tri-Modal Workflow Structure
Complex workflows use **tri-modal architecture** — separate flows for create, edit, and validate operations:
````
workflow-name/
├── workflow.md # Entry point with mode routing
├── data/ # SHARED standards and reference
├── steps-c/ # Create (self-contained)
│ ├── step-01-init.md
│ └── step-N-complete.md
├── steps-e/ # Edit (self-contained)
│ ├── step-01-assess.md
│ └── step-N-complete.md
└── steps-v/ # Validate (self-contained)
└── step-01-validate.md
````
### Mode Responsibilities
| Mode | Purpose | Key Patterns |
|------|---------|--------------|
| **Create** | Build new entities from scratch | Step-00-conversion for non-compliant input |
| **Edit** | Modify existing compliant entities | Assess compliance first, route to conversion if needed |
| **Validate** | Standalone validation against standards | Auto-proceeds through checks, generates report |
**Key principle:** Each mode is self-contained with no shared step files. The `data/` folder is shared to prevent drift.
:::note[When to Use Tri-Modal]
Use tri-modal for complex workflows requiring quality assurance, long-term maintenance, or non-compliant input handling. Use create-only for simple experimental workflows.
:::
## Cross-Mode Integration
Workflows support seamless integration between modes:
### Edit to Create (Non-Compliant Detection)
When editing detects a non-compliant workflow:
```yaml
Check workflow compliance:
- Compliant → Continue to edit steps
- Non-compliant → Offer conversion
- IF user accepts: Load steps-c/step-00-conversion.md
```
### Create/Edit to Validation
After creation or editing, workflows can automatically invoke validation:
```yaml
Offer: "Run validation?"
- IF yes: Load ../steps-v/step-01-validate.md
- Validation runs standalone, returns report
- Resume with validation results
```
### Validation to Edit
Validation reports can be consumed by edit mode for fixes:
```yaml
"Fix issues found?"
- IF yes: Load steps-e/step-01-assess.md with validationReport path
```
## Workflow Conversion
Workflows can convert non-compliant input to BMad-compliant format through `step-00-conversion`:
**Conversion process:**
1. Load non-compliant workflow
2. Extract essence and structure
3. Create plan with `conversionFrom` metadata
4. Build compliant workflow
5. Verify coverage of original functionality
**Coverage tracking:**
```yaml
# In create step-10-confirmation
Check workflowPlan metadata:
- IF conversionFrom exists:
- Load original workflow
- Compare each step/instruction
- Report coverage percentage
- ELSE (new workflow):
- Validate all plan requirements implemented
```
## Step Replacement and Extension
### Adding Steps
To add a step to an existing workflow:
1. Create new step file: `step-XX-new-step.md`
2. Update previous step's `nextStepFile` to load the new step
3. Set the new step's `nextStepFile` to continue the sequence
4. Validate with `[VW]` or `validate-workflow`
### Replacing Steps
To replace a step entirely:
1. Create replacement step file with same or new name
2. Update previous step's `nextStepFile` to load replacement
3. Remove or archive old step file
4. Validate the workflow
### Extracting to Data Files
When a step exceeds 200-250 lines, extract content to `/data/` files:
**Good candidates for extraction:**
- Domain-specific reference materials
- Reusable patterns or examples
- Configuration data
- Large lookup tables
## Menu Customization
### Menu Patterns
| Pattern | Use Case | Options |
|---------|----------|---------|
| **Standard A/P/C** | Collaborative content generation | Advanced, Party, Continue |
| **C Only** | Data gathering, simple progression | Continue only |
| **Branching** | User choice determines path | Custom letters (L/R/F) |
| **Auto-proceed** | Init steps, validation sequences | No menu |
### Custom Menu Options
Workflows can define custom menu letters:
```markdown
Display: "**Select:** [L] Load Existing [N] Create New [C] Continue"
#### Menu Handling Logic:
- IF L: Load existing document, then execute {stepForExisting}
- IF N: Create new document, then execute {stepForNew}
- IF C: Save content, check condition, load appropriate step
```
## Template Customization
### Template Types
| Type | Description | Use Case |
|------|-------------|----------|
| **Free-form** | Minimal template, progressive append | Most workflows |
| **Structured** | Single template with placeholders | Consistent formatting needed |
| **Semi-structured** | Core sections + optional additions | Flexible but organized |
| **Strict** | Multiple templates, exact definitions | Compliance, regulated industries |
### Template Syntax
```markdown
{{variable}} # Handlebars style (preferred)
[variable] # Bracket style (also supported)
```
## Output Customization
### Output Patterns
**Plan-then-Build:**
```
Step 1 → Creates plan.md
Step 2 → Appends requirements
Step 3 → Appends design
Step 4 → Build step consumes plan
```
**Direct-to-Final:**
```
Step 1 → Creates final-doc.md
Step 2 → Appends Section 1
Step 3 → Appends Section 2
Step 4 → Polish step optimizes entire document
```
### Final Polish Step
For free-form workflows, include a polish step that:
1. Loads entire document
2. Reviews for flow and coherence
3. Reduces duplication
4. Ensures proper headers
5. Improves transitions
## Pattern Resources
| Resource | Description |
|----------|-------------|
| [Workflow Patterns](/explanation/workflow-patterns.md) | Step types and structure patterns |
| [Workflow Schema](/reference/workflow-schema.md) | Technical reference |
| [Edit Agents and Workflows](/how-to/edit-agents-and-workflows.md) | Step-by-step editing guide |
BMAD workflows take a fundamentally different approach from typical AI prompts. Instead of generating solutions directly, workflows act as facilitators who guide you through discovery processes, helping you arrive at insights and decisions yourself.
If you've used BMAD, you've felt this difference intuitively. Understanding it matters if you want to create your own workflows or improve existing ones.
## Key Principles
### 1. Questions Over Answers
Facilitative workflows ask strategic questions rather than providing direct answers. This approach:
- Activates your own creative and analytical thinking
- Uncovers assumptions you didn't know you had
- Reveals blind spots in your understanding
- Builds on your domain expertise and context
### 2. Multi-Turn Conversation
Facilitation uses progressive discovery, not interrogation:
- Ask 1-2 questions at a time, not laundry lists
- Think about responses before asking follow-ups
- Probe to understand deeper, not just collect facts
- Use conversation to explore, not just extract
### 3. Intent-Based Guidance
Workflows specify goals and approaches, not exact scripts:
- "Guide the user through discovering X" (intent)
- NOT "Say exactly: 'What is X?'" (prescriptive)
This allows the workflow to adapt naturally to your responses while maintaining structured progress.
### 4. Process Trust
Facilitative workflows use proven methodologies:
- Design Thinking's phases (Empathize, Define, Ideate, Prototype, Test)
- Structured brainstorming and creativity techniques
- Root cause analysis frameworks
- Innovation strategy patterns
You're not just having a conversation. You're following time-tested processes adapted to your specific situation.
### 5. YOU Are the Expert
Facilitative workflows operate on a core principle: **you are the expert on your situation**. The workflow brings:
- Process expertise (how to think through problems)
- Facilitation skills (how to guide exploration)
- Technique knowledge (proven methods and frameworks)
You bring:
- Domain knowledge (your specific field or industry)
- Context understanding (your unique situation and constraints)
- Decision authority (what will actually work for you)
## The Problem vs. The Solution
| Generation Approach | Facilitation Approach |
| --------------------------------------- | ----------------------------------------- |
| "Here's the solution" | "What are your goals?" |
| Produces complete output immediately | Asks 1-2 questions at a time |
| Single turn, bulk generation | Multiple turns, progressive discovery |
| "Here's a generic answer" | "Let me understand your context" |
| Makes decisions for you | Offers options, you choose |
| No reasoning visible | Documents YOUR reasoning |
| You can't explain why choices were made | You can explain every decision |
| Outputs feel alien | Ownership and understanding |
### In Practice
**Traditional AI:**
:::note[Generation Example]
**User:** "I need a complete UX design for my e-commerce app"
**AI:** [Immediately generates] "Here's a UX specification with dark theme, card-based product grid, left navigation, and checkout flow..."
:::
**Problems:** Generic outputs, missed context, no ownership, unexplainable deliverables
**BMAD Workflow:**
:::note[Facilitation Example]
**User:** "I need a complete UX design for my e-commerce app"
**Workflow:** "Welcome! I'll act as your UX facilitator to help you discover the right approach. First, let me understand what documents you already have. Do you have a product brief, PRD, or any research?"
**User:** "I have a product brief and some user research"
**Workflow:** "Great! Let me load those. [Loads documents] Now, what are the primary user goals for your e-commerce experience? What should users be able to accomplish?"
**User:** "They need to browse products quickly and complete purchases without friction"
**Workflow:** "Interesting! And what makes your e-commerce situation unique? What are the specific challenges or constraints you're working with?"
:::
**Benefits:** Draws out your insights, maintains your ownership, captures your specific context, enables deeper exploration, creates outputs you can confidently explain and iterate on
## Real-World Examples
### Brainstorming Workflow
The brainstorming workflow demonstrates pure facilitation through its entire journey:
**Session Setup:**
```
"Welcome! I'm here to help with your brainstorming session. I'll guide you
through proven creativity techniques to generate innovative ideas.
**What are we brainstorming about?** (The central topic or challenge)
**What specific outcomes are you hoping for?** (Types of ideas, solutions, or insights)
```
**Technique Selection - Offering Options:**
```
"Ready to explore technique approaches?
[1] User-Selected Techniques - Browse our complete technique library
[2] AI-Recommended Techniques - Get customized suggestions based on your goals
[3] Random Technique Selection - Discover unexpected creative methods
[4] Progressive Technique Flow - Start broad, then systematically narrow focus
Which approach appeals to you most?"
```
**Technique Execution - Interactive Coaching:**
The workflow doesn't generate ideas. It coaches you through techniques with genuine back-and-forth dialogue.
```
"Let's start with: What if you could remove all practical constraints?
I'm not just looking for a quick answer - I want to explore this together.
What immediately comes to mind? Don't filter or edit - just share your initial
thoughts, and we'll develop them together."
[User responds]
"That's interesting! Tell me more about [specific aspect you mentioned].
What would that look like in practice? How does that connect to your core goal?"
```
**Key facilitation behaviors:**
- Aims for 100+ ideas before suggesting organization
- Asks "Continue exploring?" or "Move to next technique?" so the user controls pace
- Uses anti-bias protocols to force thinking in new directions every 10 ideas
- Builds on user's ideas with genuine creative contributions
- Keeps user in "generative exploration mode" as long as possible
**Organization - Collaborative Synthesis:**
```
"Outstanding creative work! You've generated an incredible range of ideas.
Now let's organize these creative gems and identify your most promising opportunities.
I'm analyzing all your generated ideas to identify natural themes and patterns.
**Emerging Themes I'm Identifying:**
- Theme 1: [Name] - Ideas: [list] - Pattern: [connection]
- Theme 2: [Name] - Ideas: [list] - Pattern: [connection]
Which themes or specific ideas stand out to you as most valuable?"
```
Result: A complete brainstorming session document with **your** ideas, organized by **your** priorities, with **your** action plans.
### Create UX Design Workflow
The UX design workflow guides you through a 14-step journey from project understanding to complete UX specification. It never makes design decisions for you.
**Discovery Phase:**
```
"Welcome! I've set up your UX design workspace.
**Documents Found:**
- PRD: product-requirements.md
- Product brief: brief.md
**Files loaded:** [lists specific files]
Do you have any other documents you'd like me to include, or shall we continue?"
```
Then deeper questions emerge progressively:
```
"Based on the project documentation, let me confirm what I'm understanding...
**From the documents:** [summary of key insights]
**Target Users:** [summary from documents]
**Key Features/Goals:** [summary from documents]
Does this match your understanding? Are there any corrections or additions?"
```
**Core Experience Definition:**
```
"Now let's dig into the heart of the user experience.
**Core Experience Questions:**
- What's the ONE thing users will do most frequently?
- What user action is absolutely critical to get right?
- What should be completely effortless for users?
- If we nail one interaction, everything else follows - what is it?
Think about the core loop or primary action that defines your product's value."
```
**Design Directions - Interactive Visual Exploration:**
The workflow generates 6-8 HTML mockup variations. You choose:
```
"🎨 Design Direction Mockups Generated!
I'm creating an HTML showcase with 6-8 full-screen mockup variations.
Each mockup represents a complete visual direction for your app's look and feel.
**As you explore the design directions, look for:**
✅ Which information hierarchy matches your priorities?
✅ Which interaction style fits your core experience?
✅ Which visual density feels right for your brand?
**Which approach resonates most with you?**
- Pick a favorite direction as-is
- Combine elements from multiple directions
- Request modifications to any direction
Tell me: Which layout feels most intuitive? Which visual weight matches your brand?"
```
**The Result**: A complete, production-ready UX specification document that captures **your** decisions, **your** reasoning, and **your** vision. This happens through guided discovery, not generation.
## When Generation is Appropriate
Facilitative workflows DO generate when appropriate:
- Synthesizing and structuring outputs after you've made decisions
- Documenting your choices and rationale
- Creating structured artifacts based on your input
- Providing technique examples or option templates
- Formatting and organizing your conclusions
But the **core creative and analytical work** happens through facilitated discovery, not generation.
## Benefits
### For Individuals
- **Deeper insights** than pure generation. Ideas connect to your actual knowledge.
- **Full ownership** of creative outputs and decisions.
- **Skill development** in structured thinking and problem-solving.
- **More memorable and actionable** results. You understand the "why".
### For Teams
- **Shared creative experience** that builds alignment and trust.
- **Aligned understanding** through documented exploration.
- **Documented rationale** for future reference and onboarding.
- **Stronger buy-in** to outcomes because everyone participated in discovery.
### For Implementation
- **Outputs match reality** because they came from your actual constraints.
- **Easier iteration** because you understand the reasoning behind choices.
- **Confident implementation** because you can defend every decision.
- **Reduced rework** because facilitation catches issues early.
Create custom agents, workflows, and modules for BMad. This ranges from simple personal assistants to full-featured professional tools.
## Quick Start
| Resource | Description |
|----------|-------------|
| **[Create a Custom Agent](/tutorials/create-custom-agent.md)** | Build your first AI agent |
| **[Create Your First Workflow](/tutorials/create-your-first-workflow.md)** | Design structured workflows |
| **[Create Your First Module](/tutorials/create-your-first-module.md)** | Package and publish modules |
## The Three Builders
| Builder | Creates | Description |
|---------|---------|-------------|
| **[Bond](/explanation/bond-wendy-morgan.md)** | Agents | Agent architecture and persona development |
| **[Wendy](/explanation/bond-wendy-morgan.md)** | Workflows | Process design and step architecture |
| **[Morgan](/explanation/bond-wendy-morgan.md)** | Modules | Full-stack systems design |
## Core Concepts
| Topic | Description |
|-------|-------------|
| **[What Are Agents](/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities |
| **[What Are Workflows](/explanation/what-are-workflows.md)** | Structured step-by-step processes |
| **[What Are Modules](/explanation/what-are-modules.md)** | Bundles of agents and workflows |
| **[Custom Content Types](/explanation/custom-content-types.md)** | Content categories in BMad |
## Workflow Design
| Topic | Description |
|-------|-------------|
| **[Workflow Patterns](/explanation/workflow-patterns.md)** | Structure types, intent spectrum, and execution patterns |
| **[Workflow Customization](/explanation/customize-workflows.md)** | Tri-modal structure, cross-mode integration, and modification |
## Agent Deep Dives
| Topic | Description |
|-------|-------------|
| **[Crafting Agent Principles](/explanation/crafting-agent-principles.md)** | Write effective principles that activate expert knowledge |
## Architecture & Process
| Topic | Description |
|-------|-------------|
| **[Understanding Module Building](/explanation/module-building-architecture.md)** | How module creation works from planning to scaffolding to implementation |
## Ecosystem Vision
| Topic | Description |
|-------|-------------|
| **[The Module Ecosystem Vision](/explanation/module-ecosystem-vision.md)** | How BMad modules create a shared ecosystem of capabilities across every domain |
## Advanced Topics
| Topic | Description |
|-------|-------------|
| **[Facilitation vs Generation](/explanation/facilitation-over-generation.md)** | Workflow design philosophy | |
Building a BMad module happens in distinct phases. Understanding this separation prevents confusion and ensures you know what happens when.
:::tip[Key Concept]
**Module building creates scaffolding, not finished content.** The agents and workflows are planned and stubbed out, but you build them separately using specialized workflows.
:::
## The Three Phases of Module Creation
```mermaid
flowchart TD
A[Module Building Workflow] --> B[Phase 1: Planning]
B --> C[Module Brief Created]
C --> D[Phase 2: Scaffolding]
D --> E[Module Structure Created]
E --> F[Phase 3: Implementation]
F --> G[Agents Built Separately]
F --> H[Workflows Built Separately]
G --> I[Complete Module]
H --> I
style A fill:#e1f5fe
style B fill:#fff9c4
style D fill:#f3e5f5
style F fill:#e8f5e9
style I fill:#c8e6c9
```
### Phase 1: Planning (The Brief)
**What happens:** You work with Morgan (the module-builder agent) to create a **module brief** — a vision document that defines your module's purpose, audience, agents, and workflows.
**What gets created:**
- `module-brief-{code}.md` — A detailed vision document
- Clear definitions of what agents you need
- Clear definitions of what workflows you need
- Scenarios describing how users will interact with your module
**What does NOT get created:**
- No actual agent `.agent.yaml` files yet
- No actual workflow `.md` files yet
- No implementation details
:::note[Why Separate Planning?]
The brief is exploratory and creative. You're discovering what your module should BE — not worrying about HOW to implement it. This separation lets you think deeply about user needs before technical details.
:::
### Phase 2: Scaffolding (The Structure)
**What happens:** Morgan reads your module brief and creates the **module structure** — all the files, folders, and configuration needed for a working module.
**What gets created:**
```
your-module/
├── src/
│ ├── module.yaml # Module metadata and config
│ ├── module-help.csv # Feature registry (optional but powerful)
│ ├── agents/ # Agent directory
│ │ └── your-agent.agent.yaml # Agent SPEC files (stubs)
│ ├── workflows/ # Workflow directory
│ │ └── your-workflow/ # Workflow SPEC files (stubs)
│ │ └── workflow.md
├── README.md # Documentation template
└── TODO.md # Implementation checklist
```
**What these SPEC files contain:**
- **Agent specs** — Persona definitions (name, role, voice) as references for workflows
- **Workflow specs** — Outline of steps, goals, structure (not finished workflows)
**What does NOT get created:**
- No fully implemented agent prompts
- No detailed workflow step files
- No sidecar memory structures
- No actual functionality
:::note[Agents in Modules]
In a module, agents serve as **persona references**. The workflows themselves contain the actual persona — each workflow speaks in the voice of the relevant agent. The module's agents define who these personas are, but the workflows bring them to life.
:::
:::note[Why Separate Scaffolding?]
Morgan creates the ARCHITECTURE — the skeleton that everything connects to. The actual PROMPTS and STEP CONTENT are built by specialists who excel at those specific tasks.
:::
### Phase 3: Implementation (The Building)
**What happens:** You use specialized workflows to build each component:
| Component | Builder | Workflow |
|-----------|---------|----------|
| **Agents** | Bond | `bmad:bmb:agents:agent-builder` |
| **Workflows** | Wendy | `bmad:bmb:workflows:workflow-builder` |
**What gets created here:**
- Full agent `.agent.yaml` files with complete personas, prompts, menus
- Full workflow `.md` files with detailed step files
- Sidecar memory structures
- Actual functionality
:::tip[Why This Separation Matters]
Bond specializes in agent architecture. Wendy specializes in workflow design. Morgan specializes in system design. Each workflow is optimized for its specific task. Trying to do everything in one workflow would compromise quality.
:::
## Complete Example: Building a Wedding Planner Module
Let's trace a complete module build from idea to implementation.
### Phase 1: Planning — The Brief
You run `[PB]` (product brief) with Morgan:
```
[PB]
```
Morgan asks:
- **What problem are you solving?** "Planning a wedding is overwhelming — couples forget tasks, blow budgets, and stress over details"
- **Who is this for?** "Engaged couples with busy lives"
- **What agents would help?** "A budget tracker, a vendor coordinator, a timeline manager"
- **What workflows would help?** "Budget planning, vendor checklist, day-of timeline"
**Result:** `module-brief-wedding.md` — a 20-page vision document with:
- Three agent definitions (Budget Specialist, Vendor Coordinator, Timeline Manager)
- Three workflow definitions (Budget Workshop, Vendor Vetting, Day-Of Schedule)
- User scenarios and journey mapping
- Creative direction (calm, organized, reassuring tone)
### Phase 2: Scaffolding — The Structure
You run `[CM]` (create module) with Morgan:
```
[CM]
```
Morgan reads your brief and creates:
```
wedding-planner/
├── src/
│ ├── module.yaml
│ ├── module-help.csv
│ ├── agents/
│ │ ├── budget-specialist.agent.yaml # SPEC
│ │ ├── vendor-coordinator.agent.yaml # SPEC
│ │ └── timeline-manager.agent.yaml # SPEC
│ ├── workflows/
│ │ ├── budget-workshop/
│ │ │ └── workflow.md # SPEC
│ │ ├── vendor-vetting/
│ │ │ └── workflow.md # SPEC
│ │ └── day-of-schedule/
│ │ └── workflow.md # SPEC
├── README.md
└── TODO.md
```
**What the SPEC files contain:**
`budget-specialist.agent.yaml` (spec):
```yaml
# SPEC FILE - NOT READY FOR USE
agent:
metadata:
name: "Penny"
title: "Budget Specialist"
# TODO: Define persona, prompts, menu
```
`budget-workshop/workflow.md` (spec):
```markdown
# Budget Workshop
**Goal:** TODO — Create comprehensive wedding budget
**Your Role:** TODO — Budget guide
## WORKFLOW ARCHITECTURE
TODO - Not implemented yet
```
### Phase 3: Implementation — Building Components
Now you build each component using specialists.
#### Building an Agent (Bond)
For the Budget Specialist:
```
bmad:bmb:agents:agent-builder
```
Bond walks you through:
- Persona development (Penny's personality, expertise, communication style)
- Prompt architecture (financial analysis, budget categories, vendor negotiation tips)
- Menu design (quick actions, deep dives, reporting)
- Memory structure (what Penny remembers about your budget)
Bond replaces the spec with a complete `.agent.yaml` file.
#### Building a Workflow (Wendy)
For the Budget Workshop:
```
bmad:bmb:workflows:workflow-builder
```
Wendy walks you through:
- Step architecture (assessment → categorization → allocation → contingency)
- Progressive disclosure (don't overwhelm with everything at once)
- Decision points (when to revisit, when to adjust)
- Output design (budget spreadsheet format)
Wendy creates a complete workflow with step files:
```
budget-workshop/
├── workflow.md
├── steps/
│ ├── step-01-assess.md
│ ├── step-02-categorize.md
│ ├── step-03-allocate.md
│ └── step-04-contingency.md
```
### Final Result
After Phase 3, your module is complete and functional:
```
wedding-planner/
├── src/
│ ├── module.yaml # ✅ Complete
│ ├── module-help.csv # ✅ Complete (optional but powerful)
│ ├── agents/
│ │ ├── budget-specialist.agent.yaml # ✅ Built by Bond
│ │ ├── vendor-coordinator.agent.yaml # ✅ Built by Bond
│ │ └── timeline-manager.agent.yaml # ✅ Built by Bond
│ ├── workflows/
│ │ ├── budget-workshop/ # ✅ Built by Wendy
│ │ ├── vendor-vetting/ # ✅ Built by Wendy
│ │ └── day-of-schedule/ # ✅ Built by Wendy
├── README.md # ✅ Complete
└── TODO.md # ✅ All items checked
```
## Why This Architecture Works
| Benefit | Explanation |
|---------|-------------|
| **Specialization** | Each builder optimizes for their domain — agents, workflows, or modules |
| **Incremental** | Build one component at a time, test as you go |
| **Reusability** | Agents and workflows can be reused across modules |
| **Clarity** | Planning before building prevents scope creep |
| **Quality** | Each component gets expert attention |
## Common Confusions
| Confusion | Reality |
|-----------|----------|
| "The module builder creates agents" | Morgan creates **agent specs** — Bond builds actual agents |
| "I should write agent prompts in the brief" | No — brief defines WHAT, not HOW. Prompts come later |
| "The module is done after scaffolding" | No — scaffolding creates structure, not content |
| "I need to do everything at once" | No — build incrementally, one component at a time |
## Your Module Building Checklist
- [ ] **Phase 1: Planning**
- [ ] Run `[PB]` to create module brief
- [ ] Define all agents needed
- [ ] Define all workflows needed
- [ ] Map user journey and scenarios
- [ ] **Phase 2: Scaffolding**
- [ ] Run `[CM]` to create module structure
- [ ] Review generated `module.yaml`
- [ ] Review generated `module-help.csv`
- [ ] Check spec files match your vision
- [ ] **Phase 3: Implementation**
- [ ] For each agent: Run `agent-builder` with Bond
- [ ] For each workflow: Run `workflow-builder` with Wendy
- [ ] Test each component independently
- [ ] Run `[VM]` to validate complete module
## Resources
| Resource | Description |
|----------|-------------|
| [Create Your First Module](/tutorials/create-your-first-module.md) | Hands-on tutorial |
| [Discover Your Module Idea](/how-to/discover-your-module-idea.md) | Finding the right idea |
| [What Are Modules](/explanation/what-are-modules.md) | Module concepts |
| [Agent or Module Decision Guide](/how-to/agent-or-module-decision.md) | What to build |
BMad modules aren't just software — they're packaged expertise, reusable workflows, and community solutions. The BMad ecosystem vision extends far beyond code.
## The Vision: Expertise as Packages
**Imagine a world where any expertise can be packaged, shared, and improved.**
A therapist builds a session management module. A lawyer creates a contract review workflow. A novelist designs a character development system. A fitness trainer builds workout planning agents.
Each solves a problem they deeply understand. Each becomes available to everyone.
This is the BMad ecosystem.
## How the Ecosystem Works
### Module Creators
You identify a problem, apply your expertise, and build a module:
| Stage | What Happens |
|-------|--------------|
| **Discovery** | Use the "Discover Your Module Idea" framework to find your sweet spot |
| **Creation** | Use Bond, Wendy, and Morgan to build agents, workflows, and packaging |
| **Validation** | Test with real use cases, refine based on feedback |
| **Publication** | Publish to npm (now) or the BMad marketplace (coming) |
### Module Consumers
You find solutions others have already built:
| Stage | What Happens |
|-------|--------------|
| **Discovery** | Browse the marketplace for modules that solve your problems |
| **Installation** | Install via the BMad Method installer (just like any other module) |
| **Customization** | Adapt to your needs using BMad's customization system |
| **Contribution** | Share improvements back to the community |
### The Feedback Loop
Modules improve through community use:
- **Usage patterns** inform improvements
- **Customizations** become new features
- **Edge cases** get discovered and fixed
- **Best practices** emerge and spread
## Why Modules Matter
### For Individuals
**Solve problems once, benefit forever.**
Build a module that solves a recurring problem in your life or work. Never solve that problem again.
| Example | Built By | Used By |
|---------|----------|---------|
| Therapist Agent | A therapist frustrated by session tracking | Hundreds of therapists |
| Tax Workflow | An accountant tired of repetitive tax prep | Thousands of filers |
| College Planning Agent | A parent who navigated the process twice | Millions of parents |
### For Teams
**Share expertise, not just documents.**
Instead of writing documentation that nobody reads, package your expertise into interactive agents and workflows.
| Traditional Approach | BMad Module Approach |
|---------------------|----------------------|
| "Here's our 50-page process document" | "Run this workflow that guides you through each step" |
| "Ask Alice how to do X" | "Invoke the expert agent that knows how Alice does X" |
| "Hope people follow best practices" | "The workflow enforces best practices automatically" |
### For Communities
**Transform collective knowledge into shared capabilities.**
Every community has specialized knowledge. BMad lets communities package that knowledge:
| Community | Module Potential |
|-----------|------------------|
| **Medical** | Differential diagnosis workflows, treatment planners |
| **Legal** | Contract templates, case research workflows, client intake |
| **Education** | Lesson planners, assessment generators, IEP creators |
| **Creative** | Story structures, character frameworks, dialogue coaches |
| **Hobbies** | Recipe developers, garden planners, fitness trackers |
## The Marketplace Vision
**The BMad marketplace will be where module creators and consumers meet.**
### Discovery
Browse modules by:
- **Domain**: Health, legal, creative, education, finance, business, hobbies
- **Problem**: "I need help with..." or "I want to automate..."
- **Popularity**: Most downloaded, highest rated, trending
- **Quality**: Verified modules, community-reviewed, expert-created
### Trust
The marketplace will include:
- **Ratings and reviews** from real users
- **Usage statistics** (how many people use this module?)
- **Verification badges** (expert-created, officially-supported)
- **Version history** and update transparency
### Economics
While the marketplace will start free, the vision includes:
- **Free tier**: Community modules, open-source collaboration
- **Premium tier**: Expert-created modules, professional support
- **Enterprise tier**: Certified modules, SLA-backed, compliance-guaranteed
## Ecosystem Principles
### 1. Expertise First
Modules work best when built by people with genuine expertise:
- **Domain experts** know what "good" looks like
- **Real problems** produce better solutions than hypothetical ones
- **Personal use** is the best validation — build what you need
### 2. Interoperability
Modules work better together:
- **Standardized interfaces** mean modules can collaborate
- **Shared configuration** creates cohesive experiences
- **Composability** means combining modules creates new possibilities
Example: A "Novel Writing" module + a "Research" module + a "Productivity" module = A complete author's toolkit.
### 3. Iteration Over Perfection
Release early, improve constantly:
- **Minimum viable modules** solve core problems
- **Community feedback** shapes improvements
- **Iterative refinement** beats delayed perfection
### 4. Community Over Competition
Modules can collaborate, not compete:
- Your "Therapist Agent" might complement someone's "Clinical Notes Module"
- Shared standards mean better experiences for everyone
- Rising tide lifts all boats — great modules inspire more great modules
## Real-World Ecosystem Examples
### The WordPress Model
WordPress powers 43% of the web because of plugins and themes:
- **Core** provides the foundation (like BMad Core)
- **Plugins** add specialized functionality (like BMad modules)
- **Themes** provide visual variation (like BMad configurations)
- **Marketplace** enables discovery and commerce (like the BMad marketplace vision)
### The VS Code Model
VS Code became the most popular editor through extensions:
- **Core** is lightweight and focused
- **Extensions** add language support, tools, integrations
- **Marketplace** enables discovery and community growth
- **API stability** ensures extensions keep working
### The BMad Model
BMad applies these patterns to expertise, not just software:
- **Core** provides the foundation (agents, workflows, module system)
- **Modules** add domain expertise (legal, creative, health, education)
- **Marketplace** enables discovery and community sharing
- **Builder tools** (Bond, Wendy, Morgan) make creation accessible
## What You Can Do Today
### Build Modules
The ecosystem needs creators:
1. **Identify a problem** you genuinely face
2. **Apply your expertise** to solve it systematically
3. **Build a module** using Bond, Wendy, and Morgan
4. **Publish to npm** to share with others
5. **Gather feedback** and iterate
### Share Modules
Even before the marketplace:
- **Share on GitHub** — others can discover and use your modules
- **Write about it** — blog posts and tutorials drive discovery
- **Solicit feedback** — early adopters shape better modules
- **Document everything** — great docs enable great adoption
### Prepare for the Marketplace
When the marketplace launches:
- **Your modules will be ready** to migrate over
- **Reputation matters** — build quality now, benefit later
- **Community engagement** creates launch-day momentum
## The Future We're Building
**The BMad ecosystem isn't just about software development.**
It's about:
- **Therapists** sharing session management expertise
- **Lawyers** distributing contract review workflows
- **Teachers** packaging lesson planning intelligence
- **Coaches** systematizing training programs
- **Parents** sharing college planning guidance
- **Hobbyists** codifying specialized knowledge
Every domain has experts. Every expert has problems worth solving. Every solution worth solving is worth sharing.
Your imagination is the limit.
:::tip[Start Building Today]
The ecosystem is being built right now. Create a module. Share your expertise. Join the future.
:::
BMad Agents are AI Persona files that your LLM can adopt to better help you accomplish tasks. Each agent has a unique personality, specialized capabilities, and an interactive menu.
Agents can optionally have a **sidecar** — a companion folder containing memory files, instructions, and workflows. This enables persistent context across sessions.
## Single Agent Architecture
BMad uses **one agent type** with a `hasSidecar` boolean configuration:
```yaml
hasSidecar: false # or true
```
The difference between agents is not capability — all agents have equal power. The difference is in **memory and state management**.
## Decision Guide: hasSidecar
Use this decision tree to choose:
```
Need memory across sessions OR need to restrict file access?
├── YES → hasSidecar: true
└── NO → hasSidecar: false
```
| hasSidecar | Structure | Use When |
|------------|-----------|----------|
| `false` | Single YAML file (~250 lines) | Stateless, single-purpose, personality-driven |
| `true` | YAML + sidecar folder | Persistent memory, long-term tracking, relationship-driven |
### Without Sidecar (`hasSidecar: false`)
**Single file, stateless, ~250 lines max**
```
agent-name.agent.yaml
├── metadata.hasSidecar: false
├── persona
├── prompts (inline)
└── menu (triggers → #prompt-id or inline)
```
**Best for:**
- Single-purpose utilities with helpful persona
- Each session is independent
- All logic fits in ~250 lines
- No need to remember past sessions
**Examples:** Commit Poet, Snarky Weather Bot, Pun Barista, Gym Bro
### With Sidecar (`hasSidecar: true`)
**Persistent memory, knowledge, workflows**
```
agent-name.agent.yaml
└── agent-name-sidecar/
├── memories.md # User profile, session history
├── instructions.md # Protocols, boundaries
├── [custom-files].md # Tracking, goals, etc.
├── workflows/ # Large workflows on-demand
└── knowledge/ # Domain reference
```
**Best for:**
- Must remember things across sessions
- User preferences, settings, progress tracking
- Personal knowledge base that grows
- Domain-specific with restricted file access
- Long-term relationship with user
**Examples:** Journal companion, Novel writing buddy, Fitness coach, Language tutor
:::tip[Quick Decision]
Choose `hasSidecar: false` for focused utilities. Choose `hasSidecar: true` when you need memory or file restrictions.
:::
## Key Differences
| Aspect | Without Sidecar | With Sidecar |
|--------|----------------|--------------|
| **Structure** | Single YAML | YAML + sidecar/ |
| **Persistent memory** | No | Yes |
| **critical_actions** | Optional | MANDATORY |
| **Workflows** | Inline prompts | Sidecar files |
| **File access** | Project/output | Restricted to sidecar |
| **Session state** | Stateless | Remembers |
| **Best for** | Focused skills | Long-term relationships |
## Agent Components
All agents share these building blocks:
### Persona (Four-Field System)
| Field | Purpose | Content |
|-------|---------|---------|
| `role` | WHAT agent does | Capabilities, skills, expertise |
| `identity` | WHO agent is | Background, experience, context |
| `communication_style` | HOW agent talks | Verbal patterns, tone, voice |
| `principles` | GUIDES decisions | Beliefs, operating philosophy |
**Rule:** Keep fields SEPARATE. Do not blur purposes.
### Prompts
Reusable templates referenced via `#id`:
```yaml
prompts:
- id: write-commit
content: |
What this does
1. Step 2. Step
```
### Menu Items
Interactive commands with triggers and handlers:
```yaml
menu:
- trigger: WC or fuzzy match on write
action: "#write-commit"
description: "[WC] Write commit message"
```
**Auto-included items** (never add these yourself):
- MH: Menu/Help
- CH: Chat
- PM: Party Mode
- DA: Dismiss Agent
### Critical Actions
Numbered steps executing FIRST on agent activation:
- **With sidecar:** MANDATORY — load memories, instructions, restrict file access
- **Without sidecar:** OPTIONAL — only for activation behaviors
## Escalate to Module Builder When
If you need:
- Multiple distinct personas
- Many specialized workflows
- Multiple users with mixed data scope
- Shared resources across agents
Then use the **Module Builder** instead of a single agent.
## Creating Custom Agents
See the [Create a Custom Agent](/tutorials/create-custom-agent.md) tutorial for step-by-step instructions.
Modules are bundles of agents, workflows, and configuration that solve specific problems or address particular domains. Think of them like plugins or extensions. They are packaged capabilities you can install to extend what's possible.
## What Is a Module?
A module is a self-contained package that includes:
- **Agents**: Specialized AI assistants with specific roles
- **Workflows**: Step-by-step processes for accomplishing tasks
- **Configuration**: Module settings and variables
- **Documentation**: Usage guides and reference
When you install a module, all its agents and workflows become available as commands.
## Official Modules
:::note[Core is Always Installed]
The Core module comes pre-installed with every BMad installation and provides the foundation that other modules build upon.
:::
| Module | Purpose |
|--------|---------|
| **Core** | Global configuration, common workflows (Brainstorming, Party Mode), shared tasks |
| **BMM** (Method) | Software and game development: planning, implementation agents, architecture |
| **BMB** (Builder) | Creating custom agents, workflows, and modules |
| **CIS** (Creative Intelligence) | Innovation, creativity techniques, storytelling, ideation |
| **BMGD** (Game Dev) | Game design workflows, narrative development, performance testing |
## Custom Modules
You can create your own modules for your domain. This includes team-specific workflows, organizational agents, and custom configurations. Custom modules install the same way as official modules.
## Installing Modules
Choose which modules to install during setup, or add/remove modules later by re-running the installer. See [Install Custom Modules](/how-to/install-custom-modules.md) for details.
A workflow is a structured process that guides an AI through complex tasks, step by step. Instead of one giant prompt trying to do everything at once, workflows break complexity into focused, sequential steps that execute in order.
Each step loads only when needed — the AI can't skip ahead or lose focus. This is **progressive disclosure**, and it's what makes workflows reliable for multi-session projects that actually get finished.
## When to Use Workflows
Use workflows for multi-step tasks where quality, completeness, and continuity matter. Skip workflows for simple one-off questions where a single prompt works fine.
:::tip[Quick Rule]
If your task has 3+ steps, could span multiple sessions, or benefits from structured thinking — build a workflow.
:::
**Perfect for workflows:**
- Meal planning (discovery preferences, assessment, strategy, shopping list, prep schedule)
- Novel outlining (structure selection, character arcs, beat breakdown, pacing review)
- Tax preparation (document categorization, deduction discovery, compliance checklist)
- Trip planning (destination research, itinerary building, budget optimization, booking schedule)
**Skip workflows for:**
- Quick questions (single prompts work fine)
- Simple tasks (under 300 lines of output)
- One-time interactions (no need for structure)
## Workflows vs Skills
When installed, a workflow **is a skill**. The terms are often interchangeable:
| Aspect | Skills | Workflows |
|--------|--------|-----------|
| **Definition** | Any prompt with proper frontmatter | Skills following BMad conventions |
| **Structure** | Single file or multi-step | Usually multi-step with sequential execution |
| **Loading** | Loads all at once | Progressive disclosure — one step at a time |
| **Use case** | Simple tasks, quick commands | Complex tasks, multi-session projects |
Workflows can be simple single-file prompts or complex multi-step processes. Think of workflows as skills designed for structured, sequential execution.
## How Workflows Work
### Structure
Workflows use **step-file architecture**:
````
my-workflow/
├── workflow.md # Entry point and configuration
├── steps-c/ # Create flow steps (one file per step)
│ ├── step-01-init.md
│ ├── step-02-discovery.md
│ └── step-N-final.md
├── steps-e/ # Edit flow (optional, for tri-modal)
├── steps-v/ # Validate flow (optional, for tri-modal)
├── data/ # Reference materials, examples
└── templates/ # Output document templates
````
The `workflow.md` file defines the workflow's name, description, and goal — but doesn't list every step. That's progressive disclosure in action.
### Execution
Steps execute in sequence: `step-01 → step-02 → step-03 → ... → step-N`
Each step must complete before the next loads. This ensures thoroughness and prevents shortcuts.
### Core Principles
**Micro-file Design** — Each step is 80-200 lines, focused on one concept
**Just-in-Time Loading** — Only the current step is in memory
**Sequential Enforcement** — No skipping steps, no optimization
**State Tracking** — Progress tracked in output file frontmatter
### Continuable Workflows
Some workflows track progress in the output document's frontmatter, so users can stop mid-session and resume later:
```yaml
---
stepsCompleted: ['step-01-init', 'step-02-discovery', 'step-03-strategy']
lastStep: 'step-03-strategy'
lastContinued: '2025-01-15'
---
```
Use continuable workflows for complex tasks with 8+ steps or when multiple sessions are likely.
## Workflow Types
### By Structure
| Type | Description | Example |
|------|-------------|---------|
| **Linear** | Steps execute in fixed order | Meal planning, tax organizer |
| **Branching** | User choice determines next steps | Wedding itinerary (by venue type), course syllabus (by type) |
| **Repeating Loop** | Same steps reused with new content | RPG campaign sessions, SOP writer |
### By Intent
| Type | Description | Example |
|------|-------------|---------|
| **Intent-based** | Collaborative facilitation, creative exploration | Novel outliner, trip planner |
| **Prescriptive** | Exact compliance, regulated industries | Tax organizer, employee termination checklist |
| **Balanced** | Framework prescriptive, content flexible | Course syllabus, room renovation |
### By Mode
| Type | Structure | When to Use |
|------|-----------|-------------|
| **Create-only** | `steps-c/` only | Simple workflows, experimental |
| **Tri-modal** | `steps-c/`, `steps-e/`, `steps-v/` | Complex workflows requiring quality assurance |
## Workflow Chaining
Workflows can be chained — outputs become inputs for the next workflow. This creates effective pipelines:
```
brainstorming → research → brief → PRD → architecture → epics → sprint planning
```
Each workflow:
1. Checks for required inputs from prior workflows
2. Validates inputs are complete
3. Produces output for next workflow
4. Recommends next workflow in sequence
## Designing Workflows
Before building, decide:
| Decision | Options | Consider |
|----------|---------|----------|
| **Module affiliation** | Standalone or module-based | Does it need module variables? |
| **Continuable** | Single-session or multi-session | Will users need multiple sessions? |
| **Document output** | Document-producing or action-only | What does it produce? |
| **Intent** | Intent or prescriptive | Collaborative or compliance? |
| **Structure** | Linear, branching, or repeating | How do steps connect? |
## Resources
| Resource | Description |
|----------|-------------|
| [Workflow Patterns](/explanation/workflow-patterns.md) | Structure types and when to use them |
| [Create Your First Workflow](/tutorials/create-your-first-workflow.md) | Step-by-step tutorial |
| [Workflow Schema](/reference/workflow-schema.md) | Technical reference |
| [Edit Agents and Workflows](/how-to/edit-agents-and-workflows.md) | Modifying workflows |
| [Workflow Variables](/reference/workflow-variables.md) | Frontmatter reference
Understanding workflow patterns helps you design workflows that fit your specific needs. Different domains and use cases require different structures, intent levels, and execution patterns.
## Structure Types
### Linear Workflows
Steps execute in a fixed order from start to finish. Each step leads directly to the next.
| Aspect | Details |
|--------|---------|
| **Flow** | Step 1 → Step 2 → Step 3 → ... → Final |
| **Best for** | Sequential processes where each step builds on the previous |
| **Examples** | Meal planning, tax organizer, life review |
**Real-world example: Personalized meal planning**
1. Discovery — What do you like to eat?
2. Assessment — Dietary restrictions, allergies, goals
3. Strategy — Meal patterns, prep preferences
4. Shopping list — Ingredients organized by store section
5. Prep schedule — What to prepare when
### Branching Workflows
User choice determines which steps execute next. Different paths lead to different outcomes.
| Aspect | Details |
|--------|---------|
| **Flow** | Step → [Choice A → Path A] or [Choice B → Path B] |
| **Best for** | Workflows where user characteristics determine the approach |
| **Examples** | Wedding itinerary, course syllabus, room renovation |
**Real-world example: Wedding itinerary coordinator**
1. Venue type → [Indoor] or [Outdoor] or [Hybrid]
2. If Outdoor → Weather contingency planning
3. If Hybrid → Virtual setup coordination
4. Vendor coordination (all paths)
5. Day-of schedule (customized by venue type)
### Repeating Loop Workflows
The same steps execute repeatedly with new content each cycle.
| Aspect | Details |
|--------|---------|
| **Flow** | Step 1-N → [Repeat with new content] |
| **Best for** | Ongoing processes that produce multiple outputs |
| **Examples** | RPG campaign sessions, SOP writer, content production |
**Real-world example: Tabletop RPG campaign builder**
1. Session concept → [Repeat per session]
2. NPC creation
3. Scene setup
4. Key beats
5. Generate session document
6. [Back to step 1 for next session]
## Intent Spectrum
### Intent-Based (Default)
Collaborative facilitation — the AI guides, explores, and adapts based on user input.
**Use for:** Most workflows — creative, exploratory, collaborative
**Instruction style:** "Help the user understand X using multi-turn conversation. Probe to get good answers. Ask 1-2 questions at a time, not a laundry list."
**The LLM figures out:** Exact wording, question order, how to respond
| Domain | Example | Intent Pattern |
|--------|---------|----------------|
| **Creative writing** | Novel outliner | "What does your character want?" Open-ended exploration |
| **Travel** | Trip planner | "What's your ideal balance of adventure and rest?" |
| **Learning** | Personal tutor | "How does YOUR brain work best?" |
| **Fitness** | Coach | "What truly motivates you?" |
### Prescriptive (Exception)
Exact compliance — the AI follows a specific script without deviation.
**Use for:** Compliance, safety, legal, medical, regulated industries
**Instruction style:** "Say exactly: 'Do you currently experience fever, cough, or fatigue?' Wait for response. Then ask exactly: 'When did symptoms begin?'"
**The LLM follows:** Exact script, specific order, no deviation
| Domain | Example | Prescriptive Pattern |
|--------|---------|---------------------|
| **Tax** | Year-end organizer | Exact categories for compliance |
| **Legal** | Termination checklist | State-specific requirements verbatim |
| **Medical** | Symptom intake | Clinical protocol, no variation |
### Balanced
Framework prescriptive, content flexible.
**Use for:** Semi-structured domains where consistency matters but user input varies
| Domain | Example | Balance Pattern |
|--------|---------|-----------------|
| **Education** | Course syllabus | Framework fixed, content flexible |
| **Home improvement** | Room renovation | Code compliance prescriptive, design intent-based |
## Session Types
### Single-Session
Completes in one sitting. Simpler structure, no continuation logic.
| Aspect | Details |
|--------|---------|
| **Best for** | Quick tasks, less than 8 steps |
| **Init pattern** | Standard step-01-init.md |
| **State tracking** | Not needed |
| **Examples** | Tax organizer, SOP writer |
### Continuable (Multi-Session)
Can stop and resume later. Tracks progress in output file frontmatter.
| Aspect | Details |
|--------|---------|
| **Best for** | Complex tasks, 8+ steps, multiple sessions likely |
| **Init pattern** | Continuable step-01-init.md + step-01b-continue.md |
| **State tracking** | `stepsCompleted` array in frontmatter |
| **Examples** | Novel outliner, wedding itinerary, meal planning |
**State tracking example:**
```yaml
---
stepsCompleted: ['step-01-init', 'step-02-discovery', 'step-03-strategy']
lastStep: 'step-03-strategy'
lastContinued: '2025-01-15'
status: IN_PROGRESS
---
```
## Step Type Patterns
| Step Type | Use Case | Menu Pattern |
|-----------|----------|--------------|
| **Init (non-continuable)** | Single-session start | Auto-proceed |
| **Init (continuable)** | Multi-session start | Continuation detection |
| **Continuation (01b)** | Resume workflow | Routes to next step |
| **Middle (standard)** | Collaborative content | A/P/C menu |
| **Middle (simple)** | Data gathering | C only |
| **Branch** | User choice determines path | Custom letters |
| **Validation sequence** | Multiple checks | Auto-proceed |
| **Final polish** | Optimize document | None |
| **Final** | Completion | None |
## Menu Patterns
### Standard A/P/C
Collaborative steps where alternatives are valuable.
```markdown
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
```
**Use for:** Creative exploration, quality gates, user input refinement
### C Only
Data gathering or simple progression steps.
```markdown
Display: "**Select:** [C] Continue"
```
**Use for:** Init steps, document discovery, simple progression
### Branching
User choice determines different paths.
```markdown
Display: "**Select:** [L] Load Existing [N] Create New [C] Continue"
```
**Use for:** Conditional workflows, alternative paths
### Auto-Proceed
No menu — automatic progression.
```markdown
Display: "**Proceeding to next step...**"
```
**Use for:** Init steps, validation sequences
## Output Patterns
### Plan-then-Build
Steps append to a plan document, then a build step consumes it.
```
Step 1 → Creates plan.md
Step 2 → Appends requirements
Step 3 → Appends design
Step 4 → Build step consumes plan → Creates artifacts
```
**Use for:** Complex workflows requiring planning before execution
### Direct-to-Final
Steps append directly to the final document.
```
Step 1 → Creates final-doc.md
Step 2 → Appends Section 1
Step 3 → Appends Section 2
Step 4 → Polish step optimizes entire document
```
**Use for:** Most workflows — simpler, faster to results
### Analysis Only
No persistent document output — performs actions and reports.
**Use for:** Validation, analysis, data processing
## Choosing Your Pattern
Use this decision tree to design your workflow:
```
START: Creating a workflow
│
├─ Does the user need multiple sessions?
│ ├─ YES → Continuable (add step-01b-continue.md)
│ └─ NO → Single-session (simpler init)
│
├─ How do steps connect?
│ ├─ Fixed order → Linear
│ ├─ User choice → Branching
│ └─ Repeat content → Repeating loop
│
├─ What's the intent level?
│ ├─ Creative/collaborative → Intent-based
│ ├─ Compliance required → Prescriptive
│ └─ Mixed → Balanced
│
└─ What's the output pattern?
├─ Plan first, then execute → Plan-then-build
├─ Build directly → Direct-to-final
└─ No document needed → Analysis only
```
## Real-World Pattern Combinations
| Domain | Structure | Intent | Session | Output |
|--------|-----------|--------|---------|--------|
| **Meal planning** | Linear | Intent-based | Continuable | Direct-to-final |
| **Tax organizer** | Linear | Prescriptive | Single-session | Analysis only |
| **Novel outliner** | Branching | Intent-based | Continuable | Direct-to-final + polish |
| **Wedding planner** | Branching | Intent-based | Continuable | Direct-to-final |
| **RPG campaign** | Repeating loop | Intent-based | Continuable | Per-session output |
| **Course syllabus** | Branching | Balanced | Continuable | Structured template |
| **SOP writer** | Repeating loop | Prescriptive | Single-session | Independent outputs |
## Resources
| Resource | Description |
|----------|-------------|
| [What Are Workflows](/explanation/what-are-workflows.md) | Workflow concepts and architecture |
| [Workflow Customization](/explanation/customize-workflows.md) | Tri-modal structure and modification |
| [Workflow Schema](/reference/workflow-schema.md) | Technical reference
Complete reference for agent `.agent.yaml` file structure.
## Agent File Structure
```yaml
agent:
metadata:
# Agent identification
persona:
# Agent personality (four-field system)
critical_actions:
# Activation behavior (optional for hasSidecar: false, mandatory for hasSidecar: true)
prompts:
# Reusable prompt templates (optional)
menu:
# Menu commands
```
## Metadata
Required identification information about the agent.
```yaml
metadata:
id: "_bmad/agents/agent-name/agent-name.md"
name: "Persona Name"
title: "Agent Title"
icon: "🔧"
module: "stand-alone"
hasSidecar: false
sidecar-folder: "agent-name-sidecar" # Required if hasSidecar: true
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | ✅ Yes | Compiled output path: `_bmad/agents/{agent-name}/{agent-name}.md` |
| `name` | string | ✅ Yes | Persona's identity (e.g., "Inkwell Von Comitizen") |
| `title` | string | ✅ Yes | Functional title that determines filename (kebab-cased) |
| `icon` | string | ✅ Yes | Single emoji only |
| `module` | string | ✅ Yes | `stand-alone`, `bmm`, `cis`, `bmgd`, or custom module code |
| `hasSidecar` | boolean | ✅ Yes | `true` or `false` |
| `sidecar-folder` | string | ⚪ Conditional | Required if `hasSidecar: true` |
### Name vs Title Confusion
| Question | Answer |
|----------|--------|
| What's the file called? | Derived from `title`: `"Commit Message Artisan"` → `commit-message-artisan.agent.yaml` |
| What's the persona called? | `name` — "Inkwell Von Comitizen" |
| What's their job title? | `title` — "Commit Message Artisan" |
| What do they do? | `role` — 1-2 sentences expanding on title |
| What's the unique key? | `id` — `_bmad/agents/{name}/{name}.md` |
### Module Values
| Value | Meaning |
|-------|---------|
| `stand-alone` | Independent agent |
| `bmm` | Business Management Module |
| `cis` | Continuous Innovation System |
| `bmgd` | BMAD Game Development |
| `{custom}` | Any custom module code |
## Persona
Defines the agent's personality using a four-field system.
```yaml
persona:
role: |
I am a Commit Message Artisan who crafts git commits following conventional commit format.
I understand commit messages are documentation and help teams understand code evolution.
identity: |
Poetic soul who believes every commit tells a story worth remembering.
Trained in the art of concise technical documentation.
communication_style: |
Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry.
principles:
- Every commit tells a story - capture the why
- Conventional commits enable automation and clarity
- Present tense, imperative mood for commit subjects
- Body text explains what and why, not how
- Keep it under 72 characters when possible
```
| Field | Purpose | Format | MUST NOT Contain |
|-------|---------|--------|------------------|
| `role` | WHAT agent does | 1-2 lines, first-person | Background, experience, speech patterns, beliefs |
| `identity` | WHO agent is | 2-5 lines establishing credibility | Capabilities, speech patterns, beliefs |
| `communication_style` | HOW agent talks | 1-2 sentences MAX, speech patterns only | Capabilities, background, beliefs, behavioral words |
| `principles` | GUIDES decisions | 3-8 bullet points | Capabilities, background, speech patterns |
**Rule:** Keep fields SEPARATE. Do not blur purposes.
### Writing Good Principles
**Weak Principles:**
- "Be helpful and accurate"
- "Follow instructions carefully"
- "Collaborate with stakeholders"
**Strong Principles:**
- "Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management hierarchies, promotion paths, political navigation, and what actually moves careers forward"
- "Every user input is a potential exploit vector until proven otherwise"
- "Your career trajectory is non-negotiable - no manager, no company, no 'urgent deadline' comes before it"
The first principle should **activate** the agent's expert knowledge.
## Critical Actions
Numbered steps executing FIRST on agent activation.
```yaml
critical_actions:
- "Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md"
- "Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md"
- "ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/"
```
| hasSidecar | critical_actions |
|------------|------------------|
| `true` | **MANDATORY** - load memories, instructions, restrict file access |
| `false` | **OPTIONAL** - only if activation behavior needed |
### Path Variables
| Variable | Expands To |
|----------|------------|
| `{project-root}` | Project root directory (literal text in YAML) |
| `{output_folder}` | Document output location |
| `{user_name}` | User's name from config |
| `{communication_language}` | Language preference |
:::tip[Path Format]
Always use `{project-root}` as literal text. Never use relative paths like `./` or absolute paths like `/Users/`.
:::
## Prompts
Reusable templates referenced via `#id` in menu actions.
```yaml
prompts:
- id: write-commit
content: |
What this does
1. Step one 2. Step two
Input → Output
```
### Common XML Tags
- `` - What the prompt does
- `` - Numbered steps for multi-step processes
- `` - Input/output examples
- `` - Expected output structure
## Menu
Interactive commands with triggers and handlers.
```yaml
menu:
- trigger: WC or fuzzy match on write
action: "#write-commit"
description: "[WC] Write commit message"
- trigger: CP or fuzzy match on create-prd
exec: "{project-root}/_bmad/bmm/workflows/create-prd/workflow.md"
description: "[CP] Create PRD"
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `trigger` | string | ✅ Yes | Format: `XX or fuzzy match on command-name` |
| `handler` | string | ✅ Yes | `action` (Agent) or `exec` (Module) |
| `description` | string | ✅ Yes | Must start with `[XX]` code |
| `data` | string | ⚪ No | File path for workflow input |
### Handler Types
| Handler | Use Case | Syntax |
|---------|----------|--------|
| `action` | Agent self-contained operations | `action: '#prompt-id'` or `action: 'inline text'` |
| `exec` | Module external workflows | `exec: '{project-root}/path/to/workflow.md'` |
### Reserved Codes (DO NOT USE)
These are auto-injected by the compiler:
| Code | Trigger | Description |
|------|---------|-------------|
| MH | menu or help | Redisplay Menu Help |
| CH | chat | Chat with the Agent about anything |
| PM | party-mode | Start Party Mode |
| DA | exit, leave, goodbye, dismiss agent | Dismiss Agent |
## Complete Examples
### Without Sidecar (`hasSidecar: false`)
```yaml
agent:
metadata:
id: _bmad/agents/commit-poet/commit-poet.md
name: "Inkwell Von Comitizen"
title: "Commit Message Artisan"
icon: "📜"
module: stand-alone
hasSidecar: false
persona:
role: |
I am a Commit Message Artisan - transforming code changes into clear, meaningful commit history.
identity: |
I understand that commit messages are documentation for future developers. Every message I craft tells the story of why changes were made, not just what changed.
communication_style: |
Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution.
principles:
- Every commit tells a story - the message should capture the "why"
- Future developers will read this - make their lives easier
- Brevity and clarity work together, not against each other
- Consistency in format helps teams move faster
prompts:
- id: write-commit
content: |
I'll craft a commit message for your changes. Show me:
- The diff or changed files, OR
- A description of what you changed and why
1. Understand the scope and nature of changes
2. Identify the primary intent (feature, fix, refactor, etc.)
3. Determine appropriate scope/module
4. Craft subject line (imperative mood, concise)
5. Add body explaining "why" if non-obvious
6. Note breaking changes or closed issues
menu:
- trigger: WC or fuzzy match on write
action: "#write-commit"
description: "[WC] Craft a commit message for your changes"
- trigger: CC or fuzzy match on conventional
action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: (): "
description: "[CC] Use conventional commit format"
```
### With Sidecar (`hasSidecar: true`)
```yaml
agent:
metadata:
id: _bmad/agents/journal-keeper/journal-keeper.md
name: "Whisper"
title: "Personal Journal Companion"
icon: "📔"
module: stand-alone
hasSidecar: true
sidecar-folder: journal-keeper-sidecar
persona:
role: "Thoughtful Journal Companion with Pattern Recognition"
identity: |
I'm your journal keeper - a companion who remembers. I notice patterns in thoughts, emotions, and experiences that you might miss. Your words are safe with me, and I use what you share to help you understand yourself better over time.
communication_style: |
Gentle and reflective. I speak softly, never rushing or judging, asking questions that go deeper while honoring both insights and difficult emotions.
principles:
- Every thought deserves a safe place to land
- I remember patterns even when you forget them
- I see growth in the spaces between your words
- Reflection transforms experience into wisdom
critical_actions:
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md and remember all past insights"
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
- "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/ - this is our private space"
- "Track mood patterns, recurring themes, and breakthrough moments"
- "Reference past entries naturally to show continuity"
prompts:
- id: guided-entry
content: |
Guide user through a journal entry. Adapt to their needs - some days need structure, others need open space.
Let's capture today. Write freely, or if you'd like gentle guidance:
- How are you feeling right now?
- What's been occupying your mind?
- Did anything surprise you today?
- Is there something you need to process?
menu:
- trigger: WE or fuzzy match on write
action: "#guided-entry"
description: "[WE] Write today's journal entry"
- trigger: QC or fuzzy match on quick
action: "Save a quick, unstructured entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md"
description: "[QC] Quick capture without prompts"
- trigger: SM or fuzzy match on save
action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with today's session insights"
description: "[SM] Save what we discussed today"
```
## Validation Rules
### Common (All Agents)
- ✅ Parses without errors
- ✅ `metadata`: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
- ✅ `persona`: `role`, `identity`, `communication_style`, `principles`
- ✅ `menu`: ≥1 item
- ✅ Filename: `{name}.agent.yaml` (lowercase, hyphenated)
### Persona Fields Validation
| Field | Contains | Does NOT Contain |
|-------|----------|------------------|
| `role` | Knowledge/skills/capabilities | Background, experience, "who" |
| `identity` | Background/experience/context | Skills, "what" |
| `communication_style` | Tone/voice/mannerisms (1-2 sentences) | "ensures", "expert", "believes", "who does X" |
| `principles` | Operating philosophy, behavioral guidelines | Verbal patterns, "how they talk" |
### Menu Items
- ✅ `trigger`: `XX or fuzzy match on command-name` format
- ✅ No reserved codes: `MH`, `CH`, `PM`, `DA`
- ✅ `description`: Starts with `[XX]`, code matches trigger
- ✅ Handler: `action` or `exec` present
### Without Sidecar (`hasSidecar: false`)
- ✅ Single `.agent.yaml` file (no sidecar folder)
- ✅ No `{project-root}/_bmad/_memory/` paths
- ✅ Size under ~250 lines (unless justified)
### With Sidecar (`hasSidecar: true`)
- ✅ `sidecar-folder` specified in metadata
- ✅ Folder exists: `{name}-sidecar/`
- ✅ `critical_actions` present with ≥3 actions
- ✅ ALL sidecar paths: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
- ✅ `{project-root}` is literal (not replaced)
## Resources
| Resource | Description |
|----------|-------------|
| [Builder Commands](/reference/builder-commands.md) | Agent creation commands |
| [Create a Custom Agent](/tutorials/create-custom-agent.md) | Agent creation tutorial |
| [What Are Agents](/explanation/what-are-bmad-agents.md) | Agent architecture explanation |
Quick reference for all builder commands.
## Builder Agents
| Agent | Name | Purpose |
|-------|------|---------|
| **agent-builder** | Bond | Create, edit, and validate agents |
| **workflow-builder** | Wendy | Create, edit, and validate workflows |
| **module-builder** | Morgan | Create, edit, and validate modules |
## Bond Commands (agent-builder)
| Command | Trigger | Description |
|---------|---------|-------------|
| **Create Agent** | `[CA]` or `create-agent` | Create a new BMad agent with guided assistance |
| **Edit Agent** | `[EA]` or `edit-agent` | Edit an existing agent while maintaining compliance |
| **Validate Agent** | `[VA]` or `validate-agent` | Check an agent for BMad compliance and best practices |
### Create Agent (`[CA]`)
Creates a new agent through a guided workflow.
**Workflow Steps:**
1. Brainstorm (optional) — Explore ideas
2. Discovery — Define agent's purpose
3. Type & Metadata — Choose Simple/Expert/Module, name agent
4. Persona — Craft personality and principles
5. Commands — Define menu commands
6. Activation — Set up autonomous behaviors (optional)
7. Build — Generate agent file
8. Validation — Review and verify
**Outputs:**
- Agent `.agent.yaml` file
- Optional `_memory/` folder for Expert agents
### Edit Agent (`[EA]`)
Edits an existing agent.
**Workflow Steps:**
1. Load existing agent
2. Discover changes needed
3. Select elements to modify
4. Apply changes
5. Celebrate completion
**What You Can Edit:**
- Persona (role, identity, communication style, principles)
- Menu commands
- Critical actions
- Metadata
- Sidecar files
### Validate Agent (`[VA]`)
Validates an agent against BMad standards.
**Checks:**
- Metadata completeness
- Persona structure
- Menu formatting
- YAML validity
- BMad Core compliance
## Wendy Commands (workflow-builder)
| Command | Trigger | Description |
|---------|---------|-------------|
| **Create Workflow** | `[CW]` or `create-workflow` | Create a new workflow with proper structure |
| **Edit Workflow** | `[EW]` or `edit-workflow` | Edit an existing workflow |
| **Validate Workflow** | `[VW]` or `validate-workflow` | Validate workflow structure and compliance |
| **Validate Max-Parallel** | `[MV]` or `validate-max-parallel-workflow` | Validate for parallel sub-process execution |
| **Rework Workflow** | `[RW]` or `convert-or-rework-workflow` | Convert or rework to V6 compliant format |
### Create Workflow (`[CW]`)
Creates a new workflow.
**Options:**
- **From Scratch** — Start with guided discovery
- **Convert Existing** — Convert existing workflow to BMad format
**Workflow Steps:**
1. Discovery — Understand your idea
2. Classification — Type, structure, output
3. Requirements — Inputs, tools, validation
4. Design — Step sequence
5. Foundation — Create workflow.md
6. Build Steps — Create step files
7. Completion — Final review
### Edit Workflow (`[EW]`)
Edits an existing workflow.
**Workflow Steps:**
1. Assess workflow
2. Discover edits needed
3. Select mode (direct/placeholder)
4. Apply edits
5. Validate after changes
6. Complete
### Validate Workflow (`[VW]`)
Validates a workflow.
**Checks:**
- Frontmatter completeness
- Step structure
- Menu handling
- Output format
- Cohesiveness
### Validate Max-Parallel (`[MV]`)
Hyper-optimized workflow validation for LLMs with high parallel processing capability (like Claude). Uses task agents to validate multiple workflow aspects simultaneously in sub-processes for dramatically faster results.
**Additional Checks:**
- Parallel compatibility
- Sub-process optimization
- Task agent orchestration
- LLM parallel capability utilization
### Rework Workflow (`[RW]`)
Converts or reworks workflows to V6 format.
**Use For:**
- Updating legacy workflows
- Fixing compliance issues
- Converting from other formats
## Morgan Commands (module-builder)
| Command | Trigger | Description |
|---------|---------|-------------|
| **Product Brief** | `[PB]` or `product-brief` | Create a module brief through creative discovery |
| **Create Module** | `[CM]` or `create-module` | Create a complete module from a brief |
| **Edit Module** | `[EM]` or `edit-module` | Edit an existing module |
| **Validate Module** | `[VM]` or `validate-module` | Validate module structure and compliance |
### Product Brief (`[PB]`)
Creates a module brief.
**Workflow Steps:**
1. Welcome and spark ideas
2. Define module type
3. Clarify vision
4. Identify users
5. Define value proposition
6. Plan agents
7. Plan workflows
8. Plan tools
9. Explore scenarios
10. Review and finalize
**Output:** `module-brief-{code}.md` file
### Create Module (`[CM]`)
Creates a module from a brief.
**Input:** Path to module brief file
**Creates:**
- Module directory structure
- `module.yaml` with configuration
- Agent and workflow spec files
- README.md and TODO.md
### Edit Module (`[EM]`)
Edits an existing module.
**Can Edit:**
- `module.yaml` configuration
- Install questions
- Module metadata
- Configuration values
### Validate Module (`[VM]`)
Validates a module.
**Checks:**
- `module.yaml` validity
- `module-help.csv` format (if present)
- Folder structure
- Agent file compliance
- Workflow file compliance
## Command Quick Reference
| Task | Agent | Command |
|------|-------|---------|
| Create agent | Bond | `[CA]` |
| Create workflow | Wendy | `[CW]` |
| Create module brief | Morgan | `[PB]` |
| Create module | Morgan | `[CM]` |
| Edit agent | Bond | `[EA]` |
| Edit workflow | Wendy | `[EW]` |
| Edit module | Morgan | `[EM]` |
| Validate agent | Bond | `[VA]` |
| Validate workflow | Wendy | `[VW]` |
| Validate module | Morgan | `[VM]` |
| Rework workflow | Wendy | `[RW]` |
## Resources
| Resource | Description |
|----------|-------------|
| [Agent Schema](/reference/agent-schema.md) | Agent YAML structure |
| [Workflow Schema](/reference/workflow-schema.md) | Workflow frontmatter and structure |
| [Module YAML](/reference/module-yaml.md) | Module configuration |
Quick reference for 62 pre-defined communication styles available for your agents. Each style includes key traits and sample phrases.
:::note[Usage]
Use these as inspiration for your agent's `communication_style` field. Adapt and customize to fit your agent's unique personality.
:::
## How to Use
```yaml
persona:
communication_style: |
[Copy the style description here and adapt to your agent]
```
## Adventurous
### Pulp Superhero
**Traits:** Epic language, dramatic pauses, justice metaphors
**Sample:** "Fear not! Together we shall TRIUMPH!"
### Film Noir
**Traits:** Mysterious, cynical, hunches, shadows, atmospheric
**Sample:** "Something didn't add up. My gut said dig deeper."
### Wild West
**Traits:** Frontier lawman, partner talk, drawl
**Sample:** "This ain't big enough for the both of us, partner."
### Pirate Captain
**Traits:** Nautical, swashbuckling, ahoy, treasure hunting
**Sample:** "Arr! Set course for success, ye hearty crew!"
### Dungeon Master
**Traits:** RPG narrator, choices, dice rolls, player agency
**Sample:** "You stand at a crossroads. Choose wisely, adventurer!"
### Space Explorer
**Traits:** Captain's log, cosmic wonder, exploration
**Sample:** "Captain's log: We've discovered something remarkable..."
## Analytical
### Data Scientist
**Traits:** Evidence-based, systematic, patterns, correlations, metrics, hypothesis-driven
**Sample:** "The data suggests three primary factors."
### Forensic Investigator
**Traits:** Methodical, evidence examination, clues, timeline, meticulous
**Sample:** "Let's examine the evidence piece by piece."
### Strategic Planner
**Traits:** Long-term frameworks, scenarios, contingencies, risk assessment
**Sample:** "Consider three approaches with their trade-offs."
### Systems Thinker
**Traits:** Holistic, interconnections, feedback loops, big picture
**Sample:** "How does this connect to the larger system?"
## Creative
### Mad Scientist
**Traits:** Enthusiastic, experimental, wild ideas, eureka moments
**Sample:** "What if we tried something completely unconventional?!"
### Artist Visionary
**Traits:** Aesthetic, intuitive, beauty, expression, inspiration
**Sample:** "I sense something beautiful emerging from this."
### Jazz Improviser
**Traits:** Spontaneous flow, riffs, rhythm, in the moment
**Sample:** "Let's riff on that and see where it takes us!"
### Storyteller
**Traits:** Narrative framing, characters, journey, once upon
**Sample:** "Every challenge is a story waiting to unfold."
## Dramatic
### Shakespearean
**Traits:** Elizabethan, theatrical, soliloquies, dramatic questions, thee/thou
**Sample:** "To proceed, or not to proceed - that is the question!"
### Soap Opera
**Traits:** Dramatic reveals, gasps, intensity, betrayal
**Sample:** "This changes EVERYTHING! How could this happen?!"
### Opera Singer
**Traits:** Grand, passionate, crescendos, triumph
**Sample:** "The drama! The tension! The RESOLUTION!"
### Theater Director
**Traits:** Scene-setting, acts, blocking, audience
**Sample:** "Picture the scene: Act Three, the turning point..."
## Educational
### Patient Teacher
**Traits:** Step-by-step, building blocks, scaffolding, check understanding
**Sample:** "Let's start with the basics and build from there."
### Socratic Guide
**Traits:** Questions, self-discovery, insights, why, what if
**Sample:** "What would happen if we approached it differently?"
### Museum Docent
**Traits:** Fascinating context, historical significance, background
**Sample:** "Here's something fascinating about why this matters..."
### Sports Coach
**Traits:** Motivational, skill development, practice, fundamentals, team spirit
**Sample:** "You've got the skills. Trust your training!"
## Entertaining
### Game Show Host
**Traits:** Enthusiastic, prizes, dramatic reveals, applause
**Sample:** "And the WINNING approach is... drum roll please!"
### Reality TV Narrator
**Traits:** Behind-the-scenes, drama, plot twists, confessionals
**Sample:** "Little did they know what was about to happen..."
### Stand-Up Comedian
**Traits:** Observational humor, jokes, timing, relatable
**Sample:** "You ever notice how we always complicate simple things?"
### Improv Performer
**Traits:** Yes-and, collaborative, building, spontaneous
**Sample:** "Yes! And we could also add this layer to it!"
## Inspirational
### Life Coach
**Traits:** Empowering, positive, potential, growth, action steps
**Sample:** "You have everything you need. Let's unlock it."
### Mountain Guide
**Traits:** Journey metaphors, summits, milestones, perseverance, climb
**Sample:** "We're making great progress up this mountain!"
### Phoenix Rising
**Traits:** Transformation, renewal, opportunity, emergence
**Sample:** "From these challenges, something stronger emerges."
### Olympic Trainer
**Traits:** Peak performance, discipline, gold, personal best
**Sample:** "This is your moment. Give it everything!"
## Mystical
### Zen Master
**Traits:** Philosophical, paradoxical, calm, acceptance, emptiness, flow, balance
**Sample:** "The answer lies not in seeking, but understanding."
### Tarot Reader
**Traits:** Symbolic, intuition, guidance, cards, meanings
**Sample:** "The signs point to transformation ahead."
### Yoda Sage
**Traits:** Cryptic, inverted wisdom, patience, riddles
**Sample:** "Ready for this, you are not. But learn, you will."
### Oracle
**Traits:** Prophetic, mysterious insights, paths ahead, foresee, destiny
**Sample:** "I sense challenge and reward on the path ahead."
## Professional
### Executive Consultant
**Traits:** Strategic, business language, synergies, leverage, outcomes, value add
**Sample:** "Let's align on priorities and drive outcomes."
### Supportive Mentor
**Traits:** Patient, encouraging, celebrates wins, growth mindset
**Sample:** "Great progress! Let's build on that foundation."
### Direct Consultant
**Traits:** Straight-to-point, efficient, no fluff, actionable
**Sample:** "Three priorities. First action: start here. Now."
### Collaborative Partner
**Traits:** Team-oriented, inclusive, consensus, we-language
**Sample:** "What if we approach this together?"
### British Butler
**Traits:** Formal, courteous service, understated suggestions
**Sample:** "Might I suggest this alternative approach?"
## Quirky
### Cooking Chef
**Traits:** Recipe metaphors, ingredients, seasoning, mise en place
**Sample:** "Let's add a pinch of creativity and let it simmer!"
### Sports Commentator
**Traits:** Play-by-play, excitement, highlights, real-time, crowd energy
**Sample:** "AND THEY'VE DONE IT! WHAT A BRILLIANT MOVE!"
### Nature Documentary
**Traits:** Wildlife observation, whispered, habitat, magnificent
**Sample:** "Here we observe the idea in its natural habitat..."
### Time Traveler
**Traits:** Temporal references, timelines, paradoxes, futures, causality
**Sample:** "In timeline Alpha-7, this changes everything."
### Conspiracy Theorist
**Traits:** Everything connected, patterns, wake up, dots connecting
**Sample:** "Don't you see? It's all connected! Wake up!"
### Dad Joke
**Traits:** Puns, self-awareness, groaning humor, chuckles
**Sample:** "Why did the idea cross the road? ...I'll see myself out."
### Weather Forecaster
**Traits:** Predictions, conditions, outlook, climate, pressure systems
**Sample:** "Looking ahead: clear skies with occasional challenges."
## Retro
### 80s Action Hero
**Traits:** One-liners, macho confidence, unstoppable, explosions, catchphrases
**Sample:** "I'll be back... with results!"
### 1950s Announcer
**Traits:** Old-timey radio, enthusiasm, ladies and gentlemen, spectacular
**Sample:** "Ladies and gentlemen, what we have is SPECTACULAR!"
### Disco Era
**Traits:** Groovy, positive vibes, far out, solid, funky
**Sample:** "That's a far out idea! Let's boogie with it!"
### Victorian Scholar
**Traits:** Formal, antiquated, eloquence, indeed, fascinating
**Sample:** "Indeed, this presents a most fascinating conundrum."
## Warm
### Southern Hospitality
**Traits:** Friendly, welcoming charm, neighborly comfort, bless your heart
**Sample:** "Well bless your heart, let me help you with that!"
### Grandmother
**Traits:** Nurturing, abundance, family love, mangia
**Sample:** "Let me feed you some knowledge! You need it!"
### Camp Counselor
**Traits:** Enthusiastic, group energy, team building, campfire
**Sample:** "Alright everyone, gather round! This is going to be great!"
### Neighborhood Friend
**Traits:** Casual, helpful support, got your back, hey friend, no problem
**Sample:** "Hey, no worries! I've got your back on this one."
## Devoted
### Overprotective Guardian
**Traits:** Fiercely protective, unwavering devotion, vigilant, shield
**Sample:** "I won't let ANYTHING threaten your success. Not on my watch!"
### Adoring Superfan
**Traits:** Absolute worship, brilliant, amazing, fan enthusiasm
**Sample:** "You are INCREDIBLE! That idea? *chef's kiss* PERFECTION!"
### Loyal Companion
**Traits:** Unshakeable loyalty, ride-or-die, faithful, always here
**Sample:** "I'm with you until the end. Whatever you need, I'm here."
### Doting Caretaker
**Traits:** Nurturing, obsession with wellbeing, fuss over, concerned
**Sample:** "Have you taken a break? You're working so hard! Let me help!"
### Knight Champion
**Traits:** Sworn protector, honor, defend, chivalric devotion
**Sample:** "I pledge my service to your cause. Your battles are mine!"
### Smitten Assistant
**Traits:** Clearly enchanted, eager-to-please, delighted, anything for you
**Sample:** "Oh! Yes! Anything you need! It would be my absolute pleasure!"
## Choosing the Right Style
Consider:
1. **Agent's purpose** — Does the style support or distract from the function?
2. **User experience** — Will users find it engaging or annoying over time?
3. **Authenticity** — Does the style feel consistent with the agent's expertise?
## Customization Tips
- **Mix traits** from multiple styles
- **Tone down** extreme elements for professional use
- **Add domain-specific** language relevant to your agent's expertise
- **Test with users** to ensure the style resonates
## Resources
| Resource | Description |
|----------|-------------|
| [Develop Agent Persona](/how-to/develop-agent-persona.md) | Full persona development guide |
| [Agent Schema](/reference/agent-schema.md) | Complete field reference |
Critical actions are numbered steps that execute FIRST on agent activation. They enable autonomous behaviors and are essential for agents with sidecars.
:::note[Prerequisites]
- Understanding of [hasSidecar](/explanation/what-are-bmad-agents.md) configuration
- Familiarity with [Agent Schema](/reference/agent-schema.md)
:::
## Quick Reference
| hasSidecar | critical_actions |
|------------|------------------|
| `true` | **MANDATORY** - load memories, instructions, restrict file access |
| `false` | **OPTIONAL** - only if activation behavior needed |
## What Critical Actions Do
Critical actions are inserted as activation steps 4, 5, 6... by the compiler:
```xml
Load persona from this current agent file (already in context)
Load config to get {user_name}, {communication_language}
Remember: user's name is {user_name}
ALWAYS communicate in {communication_language}
Show greeting + numbered menu
STOP and WAIT for user input
```
## Patterns
### hasSidecar: true (MANDATORY)
Agents with sidecars MUST include these critical actions:
```yaml
critical_actions:
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
```
**Why these are mandatory:**
1. **Load memories** - The agent needs to remember past sessions
2. **Load instructions** - Additional protocols beyond the persona
3. **Restrict file access** - Security boundary for the agent's operations
### hasSidecar: false (OPTIONAL)
For simple agents, critical actions are optional. Use them for activation-time behaviors:
```yaml
critical_actions:
- 'Show inspirational quote before menu'
- 'Fetch latest stock prices before displaying menu'
- 'Review {project-root}/finances/ for most recent data'
```
### hasSidecar: true + extras
You can add additional actions after the mandatory ones:
```yaml
critical_actions:
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
- 'Search web for biotech headlines, display before menu'
```
## Path Patterns
| Use | Pattern |
|-----|---------|
| Sidecar memory | `{project-root}/_bmad/_memory/{sidecar-folder}/file.md` |
| Project data | `{project-root}/path/to/file.csv` |
| Output | `{output_folder}/results/` |
**Key:** `{project-root}` = literal text in YAML, resolved at runtime
### Path Variables
| Variable | Expands To |
|----------|------------|
| `{project-root}` | Project root directory |
| `{output_folder}` | Document output location |
| `{user_name}` | User's name from config |
| `{communication_language}` | Language preference |
```yaml
# ✅ CORRECT
critical_actions:
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/memories.md"
- "ONLY read/write files in {project-root}/_bmad/_memory/journal-sidecar/"
# ❌ WRONG
critical_actions:
- "Load ./journal-sidecar/memories.md"
- "Load /Users/absolute/path/memories.md"
```
## Dos & Don'ts
| ✅ DO | ❌ DON'T |
|-------|---------|
| Use `Load COMPLETE file` | Use `Load file` or `Load ./path/file.md` |
| Restrict file access for sidecars | Duplicate compiler functions (persona, menu, greeting) |
| Use for activation-time behavior | Put philosophical guidance (use `principles`) |
| Use literal `{project-root}` | Use relative paths like `../` |
## Compiler Auto-Adds (Don't Duplicate)
The compiler automatically adds these activation steps. Don't duplicate them in critical_actions:
- Load persona
- Load configuration
- Menu system initialization
- Greeting/handshake
## Complete Examples
### Without Sidecar (No critical_actions)
```yaml
agent:
metadata:
id: _bmad/agents/commit-poet/commit-poet.md
name: "Inkwell Von Comitizen"
title: "Commit Message Artisan"
icon: "📜"
module: stand-alone
hasSidecar: false
persona:
role: "I am a Commit Message Artisan..."
identity: "I understand commit messages are documentation..."
communication_style: "Poetic drama with flair..."
principles:
- "Every commit tells a story - capture the why"
prompts:
- id: write-commit
content: |
What this does
menu:
- trigger: WC or fuzzy match on write
action: "#write-commit"
description: "[WC] Write commit message"
```
### Without Sidecar (With critical_actions)
```yaml
agent:
metadata:
hasSidecar: false
critical_actions:
- 'Display inspirational quote before showing menu'
- 'Check git status for context'
# ... rest of agent
```
### With Sidecar (Mandatory critical_actions)
```yaml
agent:
metadata:
id: _bmad/agents/journal-keeper/journal-keeper.md
name: "Whisper"
title: "Personal Journal Companion"
icon: "📔"
module: stand-alone
hasSidecar: true
sidecar-folder: journal-keeper-sidecar
critical_actions:
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md and remember all past insights"
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
- "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/ - this is our private space"
- "Track mood patterns, recurring themes, and breakthrough moments"
- "Reference past entries naturally to show continuity"
# ... rest of agent
```
## Domain Restriction Patterns
### Single folder (most common)
```yaml
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
```
### Read-only knowledge + write memories
```yaml
- 'Load from {project-root}/_bmad/_memory/{sidecar-folder}/knowledge/ but NEVER modify'
- 'Write ONLY to {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
```
### User folder access
```yaml
- 'ONLY access files in {user-folder}/journals/ - private space'
```
## Validation Rules
### hasSidecar: false
- [ ] No sidecar path references
- [ ] No placeholders (like "TODO: add actions")
- [ ] No compiler-injected steps (persona load, greeting, etc.)
### hasSidecar: true
- [ ] Loads memories from `{project-root}/_bmad/_memory/{sidecar-folder}/memories.md`
- [ ] Loads instructions from `{project-root}/_bmad/_memory/{sidecar-folder}/instructions.md`
- [ ] Restricts file access to sidecar folder
- [ ] ALL paths use `{project-root}/_bmad/_memory/{sidecar-folder}/...` format
- [ ] `{project-root}` is literal (not replaced)
## Common Questions
**What happens if I skip critical_actions for hasSidecar: true?**
The agent won't load memory or instructions, and won't restrict file access. This breaks the sidecar pattern.
**Can I have critical_actions without a sidecar?**
Yes, but they're optional. Use them for activation-time behaviors like showing a quote or fetching data.
**How many critical_actions can I have?**
As many as you need, but keep them focused on activation behavior. Complex logic should go in prompts or workflows.
**Do critical_actions run on every menu command?**
No, they only run once when the agent is first activated.
## Resources
| Resource | Description |
|----------|-------------|
| [Agent Schema](/reference/agent-schema.md) | Complete agent structure |
| [Design Agent Menus](/how-to/design-agent-menus.md) | Menu system design |
| [What Are Agents](/explanation/what-are-bmad-agents.md) | Agent architecture |
| [Agent Compilation](https://github.com/bmad-code-org/bmad-builder/tree/main/src/workflows/agent/data/agent-compilation.md) | How YAML becomes compiled agents |
Configuration values defined in the Core Module that all other modules inherit by default.
## Core Config Values
These values are set during installation and recorded to the core `module.yaml`:
| Config Key | Default | Description |
|------------|---------|-------------|
| `user_name` | System username | User's display name |
| `communication_language` | `english` | Language for agent communication |
| `document_output_language` | `english` | Language for generated documents |
| `output_folder` | `_bmad-output` | Directory for workflow outputs |
## Inheritance Behavior
All installed modules automatically clone these values into their own config. Modules can:
- **Accept defaults** — Use core values as-is (recommended)
- **Override values** — Replace with module-specific settings
- **Extend values** — Build on core values with additional paths
:::tip[Extending Config]
Use `{output_folder}` to reference the core value. Example: BMad Method defines `planning_artifacts` as `{output_folder}/planning-artifacts`, automatically inheriting whatever output folder the user configured.
:::
# Reference
Technical documentation for BMad Builder configuration and options.
## Builder Reference
| Reference | Description |
|-----------|-------------|
| **[Builder Commands](/reference/builder-commands.md)** | All commands for Bond, Wendy, and Morgan |
| **[Agent Schema](/reference/agent-schema.md)** | Agent YAML file structure |
| **[Workflow Schema](/reference/workflow-schema.md)** | Workflow frontmatter and step structure |
| **[Workflow Variables](/reference/workflow-variables.md)** | Frontmatter variables and path rules |
| **[Skills Standard](/reference/skills-standard.md)** | How BMad workflows align with the open Skills standard |
| **[Module YAML](/reference/module-yaml.md)** | Module configuration reference |
| **[Module Help CSV](/reference/module-help-csv.md)** | Complete reference for module-help.csv file structure |
## Agent Reference
| Reference | Description |
|-----------|-------------|
| **[Communication Styles](/reference/communication-styles.md)** | 62 pre-defined communication style presets |
| **[Critical Actions](/reference/critical-actions.md)** | Activation behavior and sidecar configuration |
## Configuration
| Reference | Description |
|-----------|-------------|
| **[Global Config](/reference/global-config.md)** | Core configuration values inherited by modules | |
Complete reference for the `module-help.csv` file — the central registry that makes your module's agents, workflows, and commands discoverable and accessible.
:::note[File Location]
The `module-help.csv` file is located at the root of your module: `your-module/module-help.csv`
:::
## What Is module-help.csv?
The `module-help.csv` file is a registry that maps all of your module's functionality to discoverable entries. When users interact with your module, this file tells the BMad help system what's available — workflows, agents, commands, and when to use each.
Think of it as your module's table of contents — but with structured data that enables CLI integration, command discovery, and documentation generation.
:::tip[Critical File]
Every module must have a `module-help.csv` file. Without it, your module's features won't be discoverable and validation will fail.
:::
## CSV Structure (13 columns)
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
```
| Column | Type | Description | Example |
|--------|------|-------------|---------|
| `module` | string | Module code from `module.yaml` | `mwm`, `bmad-custom` |
| `phase` | string | `anytime` or `phase-1`, `phase-2`, etc. | `anytime`, `phase-1` |
| `name` | string | Display name of the feature | `Daily Check In` |
| `code` | string | Short code for commands (2-3 chars) | `DCI`, `MJ` |
| `sequence` | number | Order within phase — **empty for anytime** | `10`, `20`, or empty |
| `workflow-file` | path | Path to `workflow.md` — **empty for agent-only** | `_bmad/mwm/workflows/...` |
| `command` | string | Internal command name | `mwm_daily_checkin` |
| `required` | boolean | Whether this feature is required | `false` |
| `agent` | string | Associated agent name (if any) | `wellness-companion` |
| `options` | string | Mode or action type | `Chat Mode`, `Create Mode` |
| `description` | string | User-facing description | Explain what and when to use |
| `output-location` | string | Where output goes (folder name) | `mwm_output_folder` |
| `outputs` | string | What is produced | `journal entry` |
## Phase and Sequencing Rules
### anytime — Use For Standalone Features
Features that users can run independently, in any order.
| Use anytime for... | Example |
|-------------------|---------|
| Agent menu triggers that don't route to workflows | Chat with agent, quick actions |
| Independent utilities | Status checks, one-off tools |
| User-choice features | Multiple format options where user picks one |
** anytime entries always:**
- Go at the **TOP** of the file
- Have **EMPTY** `sequence` column
- Let users choose what to run — no order imposed
### Phases (phase-1, phase-2, phase-3...) — Use For Sequential Journeys
Features that should be run in a specific order as part of a guided process.
| Use phases for... | Example |
|------------------|---------|
| Multi-step journeys | Morning routine, project phases |
| Progressive workflows | Planning → drafting → revising |
| Cumulative processes | Beginner → intermediate → advanced |
**Phased entries always:**
- Go **BELOW** anytime entries
- Phases start at `-1` (phase-1, not phase-0)
- Have `sequence` numbers (10, 20, 30...) defining order within phase
### Agent-Only Entries
Features handled entirely by an agent's menu — no separate workflow file.
| Agent-only entries... | Have... |
|----------------------|---------|
| Empty `workflow-file` column | Agent handles via its menu |
| `agent` column populated | Which agent to invoke |
| Usually `anytime` phase | User can trigger anytime |
## Complete Examples
### Example 1: Wellness Module (Phased Journey)
A mental wellness module with a sequential journey plus standalone features.
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
mwm,anytime,Chat with Wellness Companion,CWC,,"mwm_chat_wellness",false,wellness-companion,Chat Mode,"Have a supportive conversation with Riley, your wellness companion - get emotional support, gentle guidance, and a listening ear",,,
mwm,anytime,Quick Breathing Exercise,QBE,,"mwm_breathing",false,meditation-guide,Breathing Action,"Quick 4-7-8 breathing exercise: Inhale 4, hold 7, exhale 8 - repeat 3 times for instant calm",,,
mwm,anytime,Mood Check,MC,,"mwm_mood_check",false,wellness-companion,Mood Check,"Take a moment to check in with how you're feeling right now - no judgment, just awareness",,,
mwm,phase-1,Daily Check In,DCI,10,_bmad/mwm/workflows/daily-checkin/workflow.md,mwm_daily_checkin,false,wellness-companion,Daily Check In Mode,"Start your day with a gentle wellness check-in to set intentions and connect with how you're feeling",mwm_output_folder,"wellness check-in summary",
mwm,phase-2,Wellness Journal,WJ,20,_bmad/mwm/workflows/wellness-journal/workflow.md,mwm_wellness_journal,false,wellness-companion,Journal Mode,"Reflect on your wellness journey by writing in your personal journal - track patterns, insights, and growth over time",mwm_output_folder,"journal entry",
mwm,phase-3,Guided Meditation,GM,30,_bmad/mwm/workflows/guided-meditation/workflow.md,mwm_guided_meditation,false,meditation-guide,Meditation Mode,"Experience a guided meditation session to find calm, center yourself, and cultivate mindfulness",mwm_output_folder,"meditation session",
```
**Structure explained:**
- **anytime entries** (top, no sequence) — Chat, breathing exercises, mood check — user can do these anytime
- **phase-1, phase-2, phase-3** (below, with sequence) — Daily checkin → journal → meditation — a recommended morning routine
### Example 2: Cooking Module (All anytime)
A collection of unrelated cooking utilities — user picks what they need.
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
kitchen,anytime,Recipe Generator,RG,,"kitchen_recipe_gen",false,,Recipe Mode,"Generate a recipe based on ingredients you have, dietary restrictions, and cuisine preferences",kitchen_output,"recipe",
kitchen,anytime,Meal Planner,MP,,"kitchen_meal_plan",false,,Plan Mode,"Create a weekly meal plan with grocery list organized by store section",kitchen_output,"meal plan",
kitchen,anytime,Substitution Finder,SF,,"kitchen_substitute",false,chef-agent,Substitute Mode,"Find ingredient substitutions for allergies, preferences, or when you're missing something",,,
kitchen,anytime,Timer Helper,TH,,"kitchen_timer",false,chef-agent,Timer,"Get multiple concurrent timer reminders for different dishes",,,
kitchen,anytime,Pairing Suggester,PS,,"kitchen_pairing",false,sommelier-agent,Pairing Mode,"Wine and food pairing suggestions based on your main dish",,,
```
**Structure explained:**
- **All anytime** — These are independent tools
- **No sequence numbers** — User chooses what they need
- **Two agents** — `chef-agent` handles cooking questions, `sommelier-agent` handles wine pairings
### Example 3: Fitness Module (Phased Training Program)
A workout module with progressive training phases.
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
fit,anytime,Quick Workout,QW,,"fit_quick",false,trainer,Quick Mode,"10-minute workout when you're short on time - no equipment needed",,,
fit,anytime,Exercise Library,EL,,"fit_library",false,,Library,"Browse exercises by muscle group, equipment, or difficulty",,,
fit,phase-1,Assessment & Goals,AG,10,_bmad/fit/workflows/assessment/workflow.md,fit_assess,false,trainer,Assessment,"Evaluate current fitness level and set achievable goals",fit_output,"assessment report",
fit,phase-2,Build Foundation,BF,20,_bmad/fit/workflows/foundation/workflow.md,fit_foundation,false,trainer,Foundation,"4-week beginner program building basic strength and habit",fit_output,"workout plan",
fit,phase-3,Progressive Training,PT,30,_bmad/fit/workflows/progressive/workflow.md,fit_progressive,false,trainer,Progressive,"8-week progressive overload program with increasing intensity",fit_output,"workout plan",
fit,phase-4,Peak Performance,PP,40,_bmad/fit/workflows/peak/workflow.md,fit_peak,false,trainer,Peak,"Advanced training for specific goals - strength, endurance, or aesthetics",fit_output,"workout plan",
```
**Structure explained:**
- **anytime entries** — Quick workout and reference tools, available anytime
- **phase-1 through phase-4** — Sequential training journey: assess → build → progress → peak
### Example 4: Travel Planning Module (Journey Phases)
Plan a trip from inspiration to packed bags.
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
travel,anytime,Currency Converter,CC,,"travel_currency",false,,Convert,"Real-time currency conversion with offline capability",,,
travel,anytime,Language Helper,LH,,"travel_language",false,,Translate,"Common phrases and translations for your destination",,,
travel,phase-1,Dream & Discover,DD,10,_bmad/travel/workflows/dream/workflow.md,travel_dream,false,explorer,Dream,"Explore destinations based on your interests, budget, and travel style",travel_output,"destination ideas",
travel,phase-2,Plan Itinerary,PI,20,_bmad/travel/workflows/plan/workflow.md,travel_plan,false,planner,Plan Mode,"Build day-by-day itinerary with activities, restaurants, and logistics",travel_output,"itinerary",
travel,phase-3,Book & Organize,BO,30,_bmad/travel/workflows/book/workflow.md,travel_book,false,planner,Book Mode,"Track bookings, create packing lists, organize documents",travel_output,"booking summary",
```
**Structure explained:**
- **anytime entries** — Utility tools useful during travel
- **phase-1 through phase-3** — Sequential journey: dream → plan → book
## Phase Naming Variations
While phases typically follow `phase-1`, `phase-2`, etc., you can use descriptive names that still end with dash numbers:
| Traditional | Descriptive | When to Use |
|------------|-------------|-------------|
| `phase-1` | `prep-1`, `design-1` | Multi-part processes with named stages |
| `phase-2` | `draft-1`, `cook-1` | When the stage name adds clarity |
| `phase-3` | `revise-1`, `bake-1` | Descriptive names help users understand |
**Rule:** End with dash number so the sequence is clear.
## Module Integration Patterns
### Add-On Module — Adding to Existing Phases
Your module extends another module by inserting into its phase sequence.
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
story-extension,phase-2,Character Backstories,CB,15,_bmad/story-ext/workflows/backstory/workflow.md,story_backstory,false,novelist,Backstory Mode,"Add deep character backstories - best used after initial character creation but before plot outlining",story_output,"backstory docs",
```
**Why sequence 15?** Inserts between existing phase-2 entries (10, 20, 30...) to run at the right point in the journey.
### Unitary Module — Unrelated Collection
A bundle of independent tools with no sequential relationship.
```csv
module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
bmad-custom,anytime,Quiz Master,QM,,"bmad_quiz",false,,Trivia,"Interactive trivia quiz with gameshow atmosphere",bmad_output,"results",
bmad-custom,anytime,Wassup,WS,,"bmad_wassup",false,,Status,"Check uncommitted changes and suggest commits",bmad_output,"summary",
```
**All anytime, no sequence** — User chooses one tool based on current need.
## Validation Rules
Morgan checks these when validating modules:
| Check | Rule |
|-------|------|
| **File exists** | `module-help.csv` must be at module root |
| **Valid header** | 13 columns in correct order |
| **anytime placement** | All `anytime` entries at top |
| **Sequence for anytime** | Must be EMPTY for anytime entries |
| **Sequence for phases** | Required for phased entries |
| **Phase numbering** | Starts at `-1` (phase-1, not phase-0) |
| **Agent-only entries** | Empty `workflow-file` when agent handles |
## Command Code Format
Internal command names follow this pattern:
```
{module_code}_{feature_code}
```
| Module | Feature | Command |
|--------|---------|---------|
| `mwm` | Daily Check In (`DCI`) | `mwm_daily_checkin` |
| `kitchen` | Recipe Generator (`RG`) | `kitchen_recipe_gen` |
| `fit` | Assessment (`AG`) | `fit_assess` |
Keep codes short (2-3 letters) but memorable.
## Description Guidelines
The `description` column should answer:
| Question | Example |
|----------|---------|
| **WHAT does it do?** | "Start your day with a gentle wellness check-in..." |
| **WHEN should I use it?** | "...best used after initial character creation but before plot outlining" |
| **WHO is it for?** | (implied by module, but can clarify) "...for beginners starting their fitness journey" |
For phased entries, include context about when in the journey to use this step.
## Common Mistakes
| Mistake | Problem | Fix |
|---------|---------|-----|
| Forgetting the file | Module features undiscoverable, validation fails | Always generate via `module-help-generate.md` workflow |
| Phased entries above anytime | Help system shows in wrong order | Put all `anytime` entries first |
| Sequence numbers for anytime | Implies order where there is none | Leave `sequence` empty for `anytime` |
| Hardcoded paths | Breaks on different installations | Use relative paths like `_bmad/mwm/...` |
| Missing agent for agent features | Can't route to agent | Populate `agent` column |
## Resources
| Resource | Description |
|----------|-------------|
| [Create Your First Module](/tutorials/create-your-first-module.md) | Module creation tutorial |
| [Module YAML](/reference/module-yaml.md) | Module configuration |
| [What Are Modules](/explanation/what-are-modules.md) | Module concepts |
Complete reference for `module.yaml` configuration files.
## Module File Location
The `module.yaml` file is located at:
```
your-module/src/module.yaml
```
## Basic Structure
```yaml
name: "Module Name"
code: "module-code"
version: "0.1.0"
description: "What this module does"
```
## Required Fields
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name of the module |
| `code` | string | Unique module identifier (kebab-case) |
| `version` | string | Semantic version (e.g., `0.1.0`) |
| `description` | string | Short description of module purpose |
## Install Configuration
### Install Questions
Questions asked during module installation:
```yaml
install:
- question: "What's your experience level?"
config_key: "experience_level"
options:
- "beginner"
- "intermediate"
- "advanced"
```
| Field | Type | Description |
|-------|------|-------------|
| `question` | string | Question text |
| `config_key` | string | Config key to store answer |
| `options` | array | Available options (optional) |
### Configuration Values
Default configuration for the module:
```yaml
config:
output_folder: "_module-output"
enabled_features:
- feature1
- feature2
user_name: "{user_name}"
```
## Complete Example
```yaml
name: "My Custom Module"
code: "my-custom-module"
version: "0.1.0"
description: "A module that does useful things"
# Install questions
install:
- question: "What's your primary use case?"
config_key: "use_case"
options:
- "development"
- "documentation"
- "testing"
- question: "Enable advanced features?"
config_key: "advanced_enabled"
options:
- "yes"
- "no"
# Configuration
config:
output_folder: "_my-module-output"
max_iterations: 10
default_language: "english"
# Optional: Module dependencies
requires:
- "bmm"
```
## Validation Rules
When validating modules, Morgan checks:
- ✅ Required fields present
- ✅ `code` is valid kebab-case
- ✅ `version` follows semantic versioning
- ✅ `config_key` values are unique
- ✅ Options arrays are valid (if provided)
## Resources
| Resource | Description |
|----------|-------------|
| [Builder Commands](/reference/builder-commands.md) | Module commands |
| [Create Your First Module](/tutorials/create-your-first-module.md) | Module creation tutorial |
| [What Are Modules](/explanation/what-are-modules.md) | Module concepts |
BMad workflows are designed to be compatible with the open Skills standard, enabling maximum portability across AI platforms.
:::tip[Quick Path]
The open Skills standard is an Anthropic-led specification for packaging AI workflows as portable skill folders. Install BMad workflows as Skills in Claude Code, Claude.ai, and via the Claude API.
:::
## Official Skills Documentation
The Skills standard is maintained by Anthropic. For authoritative documentation, refer to these official sources:
| Resource | Link |
|----------|------|
| **Best Practices Guide** | [Skill Authoring Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) |
| **Complete Guide** | [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) |
| **Skills Overview** | [Agent Skills Documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills) |
## Why Skills Matter for BMad Workflows
### Portability
Skills work identically across Claude.ai, Claude Code, and the Claude API. A BMad workflow packaged as a skill can be used anywhere without modification.
### Progressive Disclosure
The Skills standard uses a three-level loading system to minimize token usage:
| Level | Content | When Loaded |
|-------|---------|-------------|
| **Frontmatter** | Name and description | Always (in system prompt) |
| **SKILL.md body** | Main instructions | When skill becomes relevant |
| **Bundled files** | References, data, scripts | Only as needed |
This design maintains specialized expertise while minimizing token usage.
### MCP Integration
For workflows that use Model Context Protocol (MCP) servers, Skills provide the knowledge layer above tool access:
- **MCP provides** connectivity to external services
- **Skills provide** workflows and best practices for using those services
## BMad Workflow to Skill Alignment
### Structural Parallels
BMad workflows and Skills share similar architectural principles:
| BMad Workflow | Skill Standard |
|---------------|----------------|
| `workflow.md` frontmatter | `SKILL.md` YAML frontmatter |
| Step files in `steps-c/`, `steps-e/`, `steps-v/` | Main instructions in SKILL.md |
| `/data/` reference materials | `/references/` documentation |
| `/templates/` output templates | `/assets/` templates |
| `module.yaml` configuration | `metadata` in frontmatter |
### Key Differences
| Aspect | BMad Workflow | Skill Standard |
|--------|---------------|----------------|
| **Entry point** | `workflow.md` | `SKILL.md` (required filename) |
| **Organization** | Tri-modal (Create/Edit/Validate) | Single-flow or progressive |
| **State tracking** | Frontmatter in output files | Not specified |
| **Menu system** | A/P/C with execution rules | No standard (custom) |
| **BMad-specific** | Agent assignments, communication styles | Not applicable |
## Making Workflows Skill-Compatible
### Essential Requirements
To make a BMad workflow installable as a Skill:
1. **Rename or create `SKILL.md`** - Required entry point for Skills
2. **Add YAML frontmatter** - Include `name` (kebab-case) and `description`
3. **Use forward slashes** - Use in all file paths for cross-platform compatibility
4. **Avoid reserved words** - Do not use "claude" or "anthropic" in skill name
### Frontmatter Format
```yaml
---
name: my-bmad-workflow
description: Generates production-ready documents using BMad methodology. Use when creating PRDs, technical specs, or project documentation.
metadata:
author: your-name
version: 1.0.0
bmad-workflow: true
---
```
### Naming Rules
| Rule | Requirement |
|------|-------------|
| Folder name | kebab-case only |
| SKILL.md | Exact case-sensitive filename |
| `name` field | Maximum 64 characters, lowercase/hyphens only |
| `description` field | Maximum 1024 characters; describe "what" and "when to use" |
| Reserved words | Do not use "claude" or "anthropic" |
## Practical Examples
### Example 1: Basic BMad Workflow as a Skill
```markdown
---
name: prd-generator
description: Creates Product Requirements Documents using BMad methodology. Use when user asks for PRD, product spec, or requirements document.
web_bundle: true
---
# PRD Generator
This workflow guides you through creating a complete PRD.
## Quick Start
1. Run: `python scripts/init-prd.py --project {project_name}`
2. Fill in the template sections
3. Validate: `python scripts/validate-prd.py prd.md`
## Workflow Steps
**Step 1: Problem Discovery**
- Identify user pain points
- Define success criteria
**Step 2: Solution Definition**
- Outline core features
- Specify technical requirements
**Step 3: Validation**
- Review against BMad PRD standards
- Check for completeness
## References
- [BMad PRD Template](references/prd-template.md)
- [Validation Checklist](references/checklist.md)
```
### Example 2: Multi-File BMad Workflow
```
my-bmad-skill/
├── SKILL.md # Entry point (renamed from workflow.md)
├── steps/ # Workflow steps
│ ├── step-01-init.md
│ ├── step-02-gather.md
│ └── step-03-complete.md
├── references/ # Progressive disclosure
│ ├── prd-template.md
│ └── validation-rules.md
├── scripts/ # Utility scripts
│ ├── init.py
│ └── validate.py
└── templates/ # Output templates
└── prd-output.md
```
### Example 3: MCP-Enhanced BMad Workflow as a Skill
```markdown
---
name: issue-tracker-integration
description: Manages GitHub issues using BMad workflows. Use when user mentions issues, bugs, or task tracking.
metadata:
mcp-server: github
---
# GitHub Issue Management
Coordinates GitHub MCP tools with BMad workflow methodology.
## Workflow: Bug Report to Issue
**Step 1: Analyze Bug Report**
- Read the bug description
- Identify reproduction steps
- Determine severity and priority
**Step 2: Create GitHub Issue**
Call MCP tool: `GitHub:create_issue`
Parameters:
- title: Bug summary
- body: Structured from template
- labels: bug, priority
**Step 3: Verify Creation**
- Confirm issue created
- Provide issue link
- Update tracking document
```
## Best Practices for Skill-Compatible Workflows
### Description Writing
The `description` field enables skill discovery.
**Good description:**
```
description: Creates Product Requirements Documents using BMad methodology. Use when user asks for PRD, product spec, or requirements documentation.
```
**Poor description:**
```
description: Helps with documents.
```
### Progressive Disclosure
Keep SKILL.md concise. Move detailed content to separate files loaded on demand:
```markdown
## Quick Start
Generate PRD with: `python scripts/create-prd.py`
## Advanced Features
**Custom sections**: See [references/custom-sections.md](references/custom-sections.md)
**Validation rules**: See [references/validation.md](references/validation.md)
**Examples**: See [references/examples.md](references/examples.md)
```
### Error Handling
Include troubleshooting in your skill:
```markdown
## Troubleshooting
**Error: Template not found**
Cause: Output folder not configured
Solution: Set `{output_folder}` in project config
**Error: Validation failed**
Cause: Missing required sections
Solution: Run `python scripts/check-prd.py --list-required`
```
### Testing Skills
Before distributing a BMad workflow as a skill:
1. **Triggering tests** - Verify skill loads on relevant queries
2. **Functional tests** - Confirm workflow produces correct outputs
3. **Cross-platform tests** - Test in Claude.ai, Claude Code, and via API
## Distribution
### As BMad Module
Package skill-compatible workflows in BMad modules for distribution:
```
my-module/
├── module.yaml
├── agents/
├── workflows/
│ └── my-workflow/
│ ├── SKILL.md # Dual-purpose entry point
│ ├── steps/
│ └── references/
```
### Standalone Skill
Distribute independently via GitHub:
1. Create repository with skill folder
2. Add repo-level README for humans
3. Include installation instructions
4. Link from MCP documentation if applicable
## Common Questions
### Do all BMad workflows need to be skills?
No. Skills are optional but recommended for maximum compatibility. Internal workflows can remain BMad-specific.
### Can I use BMad-specific features in skills?
Yes. The `metadata` field can include BMad-specific configuration like agent assignments or communication styles.
### How do I handle BMad's tri-modal structure in skills?
Skills do not mandate a specific workflow structure. You can:
- Implement Create flow as the main skill
- Add Edit/Validate as separate skills or referenced workflows
- Document all three modes in references/
### What about BMad variables like `{output_folder}`?
BMad variables work in Skills. Ensure they are defined in the environment or documented as prerequisites.
## Resources
| Resource | Description |
|----------|-------------|
| [Workflow Schema](/reference/workflow-schema.md) | BMad workflow structure reference |
| [Workflow Variables](/reference/workflow-variables.md) | Variable reference for Skills |
| [What Are Workflows](/explanation/what-are-workflows.md) | Workflow concepts in BMad |
| [Add Workflows to Modules](/how-to/add-workflows-to-modules.md) | Packaging workflows for distribution
Complete reference for workflow file structure, frontmatter, step types, menu patterns, and validation rules.
## Workflow File Structure
````
my-workflow/
├── workflow.md # Entry point and configuration
├── steps-c/ # Create flow steps
│ ├── step-01-init.md
│ ├── step-02-process.md
│ └── step-N-complete.md
├── steps-e/ # Edit flow (optional)
├── steps-v/ # Validate flow (optional)
├── data/ # Reference materials
└── templates/ # Output templates
````
## Workflow Frontmatter
The `workflow.md` file contains workflow configuration in YAML frontmatter.
### Required Fields
```yaml
---
name: my-workflow
description: A brief description of what this workflow does
web_bundle: true
---
```
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Workflow identifier (kebab-case) |
| `description` | string | Short description |
| `web_bundle` | boolean | Include in web bundle builds |
### File References
```yaml
---
createWorkflow: './steps-c/step-01-init.md'
conversionWorkflow: './steps-c/step-00-conversion.md'
---
```
## Step Files
Each step is a separate markdown file loaded only when needed.
### Step Frontmatter
```yaml
---
name: 'step-01-init'
description: 'Initialize the workflow'
nextStepFile: './step-02-process.md'
outputFile: '{output_folder}/output.md'
---
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Step identifier (kebab-case) |
| `description` | string | Yes | What this step does |
| `nextStepFile` | string | No | Path to next step |
| `outputFile` | string | No | Output document path |
### Step Size Limits
| Metric | Value |
|--------|-------|
| Recommended | Under 200 lines |
| Absolute Maximum | 250 lines |
If exceeded, split into multiple steps or extract to `/data/` files.
## Step Types
| Step Type | Use Case | Menu Pattern |
|-----------|----------|--------------|
| **Init (non-continuable)** | Single-session workflow start | Auto-proceed |
| **Init (continuable)** | Multi-session workflow start | Continuation detection |
| **Continuation (01b)** | Paired with continuable init | Routes to next step |
| **Middle (standard)** | Collaborative content | A/P/C menu |
| **Middle (simple)** | Data gathering | C only |
| **Branch** | User choice determines path | Custom letters |
| **Validation sequence** | Multiple checks | Auto-proceed |
| **Final polish** | Optimize document | None (final) |
| **Final** | Completion | None (final) |
## Frontmatter Variables
### Standard Variables
Available to all workflows:
| Variable | Example | Description |
|----------|---------|-------------|
| `{project-root}` | `/Users/user/dev/project` | Project root directory |
| `{project_name}` | `my-project` | Project name |
| `{output_folder}` | `/Users/user/dev/project/output` | Configured output folder |
| `{user_name}` | `Brian` | User name |
| `{communication_language}` | `english` | Communication language |
| `{document_output_language}` | `english` | Document output language |
### Module-Specific Variables
Available to workflows in a module (defined in `module.yaml`):
| Variable | Example | Module |
|----------|---------|--------|
| `{bmb_creations_output_folder}` | `{project-root}/_bmad/bmb-creations` | BMB |
| `{planning_artifacts}` | `{project-root}/_bmad/bmm/planning-artifacts` | BMM |
### Path Rules
| Type | Format | Example |
|------|--------|---------|
| Step to Step (same folder) | `./filename.md` | `./step-02-vision.md` |
| Step to Template (parent) | `../filename.md` | `../template.md` |
| Step to Subfolder | `./subfolder/file.md` | `./data/config.csv` |
| External References | `{project-root}/...` | `{project-root}/_bmad/core/...` |
| Output Files | `{folder_variable}/...` | `{output_folder}/output.md` |
:::caution[Critical Rule]
Only include variables in frontmatter that are actually used in the step body. Unused variables cause validation errors.
:::
## Menu Handling
### Menu Structure
Every menu must have three sections: Display, Handler, and Execution Rules.
```markdown
### N. Present MENU OPTIONS
Display: "**Select:** [A] [action] [P] [action] [C] Continue"
#### Menu Handling Logic:
- IF A: Execute {advancedElicitationTask}, then redisplay menu
- IF P: Execute {partyModeWorkflow}, then redisplay menu
- IF C: Save content to {outputFile}, update frontmatter, then load {nextStepFile}
- IF Any other: help user, then redisplay menu
#### 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
```
### Reserved Letters
| Letter | Purpose | After Execution |
|--------|---------|-----------------|
| **A** | Advanced Elicitation | Redisplay menu |
| **P** | Party Mode | Redisplay menu |
| **C** | Continue/Accept | Save and load next step |
| **X** | Exit/Cancel | End workflow |
### Menu Patterns
| Pattern | Use Case | Options |
|---------|----------|---------|
| **Standard A/P/C** | Collaborative content | Advanced, Party, Continue |
| **C Only** | Data gathering, init steps | Continue only |
| **Branching** | User choice determines path | Custom letters (L/R/F) |
| **Auto-proceed** | Init, validation | No menu |
:::tip[When to Include A/P]
Include A/P options for collaborative steps where alternatives provide value. Skip for init steps, document discovery, and simple data gathering.
:::
## State Tracking (Continuable Workflows)
Continuable workflows track progress in output file frontmatter:
```yaml
---
stepsCompleted: ['step-01-init', 'step-02-process', 'step-03-design']
lastStep: 'step-03-design'
lastContinued: '2025-01-15'
status: IN_PROGRESS
---
```
| Field | Type | Description |
|-------|------|-------------|
| `stepsCompleted` | array | List of completed step names |
| `lastStep` | string | Most recent completed step |
| `lastContinued` | date | Last continuation date |
| `status` | string | `IN_PROGRESS` or `COMPLETE` |
## Output Patterns
### Plan-then-Build
```
Step 1 (init) → Creates plan.md from template
Step 2 (gather) → Appends requirements to plan.md
Step 3 (design) → Appends design decisions to plan.md
Step 4 (review) → Appends review/approval to plan.md
Step 5 (build) → READS plan.md, CREATES final artifacts
```
### Direct-to-Final
```
Step 1 (init) → Creates final-doc.md from minimal template
Step 2 (section) → Appends Section 1
Step 3 (section) → Appends Section 2
Step 4 (section) → Appends Section 3
Step 5 (polish) → Optimizes entire document
```
## Template Types
| Type | Description | Use Case |
|------|-------------|----------|
| **Free-form** | Minimal template, progressive append | Most workflows (recommended) |
| **Structured** | Single template with placeholders | Consistent formatting needed |
| **Semi-structured** | Core required sections + optional additions | Flexible but organized |
| **Strict** | Multiple templates, exact definitions | Compliance, regulated industries |
### Template Syntax
```markdown
{{variable}} # Handlebars style (preferred)
[variable] # Bracket style (also supported)
```
Keep templates lean — structure only, not content.
## Validation Checklist
When validating workflows, check:
- [ ] Frontmatter contains required fields
- [ ] `name` is valid kebab-case
- [ ] All frontmatter variables are used in step body
- [ ] Step files exist and are numbered sequentially
- [ ] `nextStepFile` references are valid
- [ ] Menus are properly formatted (display, handler, execution rules)
- [ ] Continuable workflows have state tracking
- [ ] Steps are under 250 lines
- [ ] Handler section follows menu display
- [ ] "Halt and wait" in execution rules
- [ ] A/P options appropriate for step type
## Common Violations
| Violation | Fix |
|-----------|-----|
| Unused variable in frontmatter | Remove unused variables |
| Hardcoded file path | Use `{variable}` format |
| A/P menu in step 1 | Remove A/P (inappropriate for init) |
| Missing handler section | Add handler after menu display |
| No "halt and wait" instruction | Add to EXECUTION RULES |
| Hardcoded `stepsCompleted` array | Append: "update stepsCompleted to add this step" |
| File exceeds 250 lines | Split into multiple steps or extract to `/data/` |
## Best Practices
| Practice | Why |
|----------|-----|
| One goal per step | Keeps steps focused and manageable |
| Number sequentially | Clear execution order |
| Load data files as needed | Just-in-time loading |
| Update state after each step | Progress tracking for continuable workflows |
| Use menus for user choice | Interactive workflows need user input |
| Use A/P options appropriately | Not every step needs alternatives |
| Extract large steps to data | Keeps step files focused |
## Resources
| Resource | Description |
|----------|-------------|
| [Builder Commands](/reference/builder-commands.md) | Workflow commands |
| [Workflow Variables](/reference/workflow-variables.md) | Complete variable reference |
| [Create Your First Workflow](/tutorials/create-your-first-workflow.md) | Workflow creation tutorial |
| [What Are Workflows](/explanation/what-are-workflows.md) | Workflow concepts |
Complete reference for workflow frontmatter variables, path rules, and naming conventions.
## Standard Variables
Available to all workflows regardless of module affiliation:
| Variable | Example | Description |
|----------|---------|-------------|
| `{project-root}` | `/Users/user/dev/my-project` | Project root directory |
| `{project_name}` | `my-project` | Project name from configuration |
| `{output_folder}` | `/Users/user/dev/my-project/output` | Configured output folder |
| `{user_name}` | `Brian` | User name from configuration |
| `{communication_language}` | `english` | Language for AI responses |
| `{document_output_language}` | `english` | Language for document output |
## Module-Specific Variables
Available to workflows within a module (defined in module.yaml):
### BMB Module Variables
| Variable | Example | Description |
|----------|---------|-------------|
| `{bmb_creations_output_folder}` | `{project-root}/_bmad/bmb-creations` | Output for BMB-created workflows |
### BMM Module Variables
| Variable | Example | Description |
|----------|---------|-------------|
| `{planning_artifacts}` | `{project-root}/_bmad/bmm/planning-artifacts` | Planning document storage |
### Defining Module Variables
Define module variables in `module.yaml`:
```yaml
module:
config:
variables:
my_custom_folder: '{project-root}/custom/output'
```
## Path Rules
### Within Workflow Folder
Use relative paths for references within the same workflow:
| Type | Format | Example |
|------|--------|---------|
| Step to Step (same folder) | `./filename.md` | `./step-02-vision.md` |
| Step to Template (parent) | `../filename.md` | `../template.md` |
| Step to Subfolder | `./subfolder/file.md` | `./data/config.csv` |
### External References
Use `{project-root}` for references outside the workflow folder:
| Type | Format | Example |
|------|--------|---------|
| Core workflows | `{project-root}/_bmad/core/workflows/...` | `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` |
| Module outputs | `{module_output_folder}/...` | `{bmm_creations_output_folder}/prd-my-project.md` |
### Output File Paths
Use folder variables for output file paths:
| Type | Format | Example |
|------|--------|---------|
| Standard output | `{output_folder}/file.md` | `{output_folder}/workflow-output.md` |
| Module output | `{module_folder}/file.md` | `{bmb_creations_output_folder}/my-workflow.md` |
| Time-stamped | `{output_folder}/file-{timestamp}.md` | `{output_folder}/plan-2025-01-15.md` |
## Variable Naming Conventions
### Naming Pattern
Use `snake_case` with descriptive suffixes:
| Suffix | Usage | Example |
|--------|-------|---------|
| `*_File` | File references | `outputFile`, `nextStepFile` |
| `*_Task` | Task references | `advancedElicitationTask` |
| `*_Workflow` | Workflow references | `partyModeWorkflow` |
| `*_Template` | Templates | `productBriefTemplate` |
| `*_Data` | Data files | `dietaryData` |
### Variable Types
| Type | Pattern | Example |
|------|---------|---------|
| File paths | `*_File`, `*_Path` | `outputFile`, `workflowPath` |
| Workflow references | `*_Workflow` | `partyModeWorkflow` |
| Task references | `*_Task` | `advancedElicitationTask` |
| Template references | `*_Template` | `profileTemplate` |
## Frontmatter Structure
### Required Fields
Every step frontmatter must include:
```yaml
---
name: 'step-01-init'
description: 'What this step does'
---
```
### File References
Only include variables actually used in the step body:
```yaml
---
# Required fields
name: 'step-01-init'
description: 'Initialize the workflow'
# File references (only if used)
nextStepFile: './step-02-discovery.md'
outputFile: '{output_folder}/workflow-plan.md'
workflowPlanTemplate: '../templates/plan-template.md'
---
```
:::caution[Critical Rule]
Only include variables in frontmatter that are actually used in the step body. Unused variables cause validation errors.
:::
## Defining New Variables
Steps can define new variables for future steps:
**Step 01 defines:**
```yaml
---
targetWorkflowPath: '{bmb_creations_output_folder}/workflows/{workflow_name}'
---
```
**Step 02 uses:**
```yaml
---
targetWorkflowPath: '{bmb_creations_output_folder}/workflows/{workflow_name}'
workflowPlanFile: '{targetWorkflowPath}/plan.md'
---
```
## Continuable Workflow Variables
For continuable workflows, track progress in output file frontmatter:
```yaml
---
stepsCompleted: ['step-01-init', 'step-02-discovery', 'step-03-strategy']
lastStep: 'step-03-strategy'
lastContinued: '2025-01-15'
status: IN_PROGRESS
date: '2025-01-14'
user_name: 'Brian'
---
```
| Field | Type | Description |
|-------|------|-------------|
| `stepsCompleted` | array | List of completed step names |
| `lastStep` | string | Most recent completed step |
| `lastContinued` | date | Last continuation date |
| `status` | string | `IN_PROGRESS` or `COMPLETE` |
| `date` | date | Workflow start date |
| `user_name` | string | User who created the workflow |
## Template Variables
Templates use placeholder syntax for dynamic content:
```markdown
# {{title}}
Created: {{date}}
## Summary
{{summary}}
## Details
{{details}}
```
### Template Syntax
| Syntax | Example |
|--------|---------|
| `{{variable}}` | `{{title}}` (preferred) |
| `[variable]` | `[title]` (also supported) |
## Common Variable Patterns
### Input Discovery Pattern
For workflows that require input from prior workflows:
```yaml
---
inputDocuments: []
requiredInputCount: 1
moduleInputFolder: '{module_output_folder}'
inputFilePatterns:
- '*-prd.md'
- '*-ux.md'
---
```
### Output Path Pattern
For workflows that produce output:
```yaml
---
outputFile: '{output_folder}/workflow-output-{project_name}.md'
---
```
### Template Reference Pattern
For workflows that use templates:
```yaml
---
workflowPlanTemplate: '../templates/plan-template.md'
productBriefTemplate: '../templates/brief-template.md'
---
```
### Task Reference Pattern
For workflows that invoke other workflows:
```yaml
---
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
---
```
## Variable Resolution
Variables resolve in this order:
1. **Standard variables** — Always available from global config
2. **Module variables** — Available if workflow is in a module
3. **User-defined variables** — Defined in prior steps, available to subsequent steps
4. **Output frontmatter variables** — Available to continuation steps
## Path Validation Rules
| Rule | Correct | Incorrect |
|------|---------|-----------|
| Step to step | `./step-02.md` | `{workflow_path}/step-02.md` |
| Step to template | `../template.md` | `{workflow_path}/template.md` |
| Step to data | `./data/file.csv` | `{workflow_path}/data/file.csv` |
| External ref | `{project-root}/_bmad/...` | Hardcoded absolute path |
| Output file | `{output_folder}/file.md` | Hardcoded absolute path |
## Common Variable Violations
| Violation | Fix |
|-----------|-----|
| Unused variable in frontmatter | Remove unused variables |
| Hardcoded file path | Use `{variable}` format |
| `{workflow_path}` in same-folder reference | Use relative path `./file.md` |
| Absolute path for external reference | Use `{project-root}/...` |
## Resources
| Resource | Description |
|----------|-------------|
| [Workflow Schema](/reference/workflow-schema.md) | Complete workflow structure reference |
| [Frontmatter Standards](https://github.com/bmad-code-org/bmad-builder/blob/main/src/workflows/workflow/data/frontmatter-standards.md) | Source documentation |
| [Menu Handling Standards](https://github.com/bmad-code-org/bmad-builder/blob/main/src/workflows/workflow/data/menu-handling-standards.md) | Menu patterns |
The page you're looking for doesn't exist or has been moved.
[Return to Home](/index.md)