ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v4-v6 upgrade improvement and warning about file auto backup

Browse Source
This commit is contained in:
Brian Madison
2025-09-30 19:42:12 -05:00
parent df0c3e4bae
commit e7fcc56cc3
314 changed files with 38192 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
bmad/bmb/workflows/create-agent/README.md Normal file
View File

@@ -0,0 +1,268 @@
# Build Agent
## Overview
The Build Agent workflow is an interactive agent builder that guides you through creating BMAD Core compliant agents with proper persona, activation rules, and command structure. It supports three agent types: Simple (self-contained), Expert (with sidecar resources), and Module (full-featured with workflows).
## Key Features
- **Optional Brainstorming**: Creative ideation session before agent building to explore concepts and personalities
- **Three Agent Types**: Simple, Expert, and Module agents with appropriate structures
- **Persona Development**: Guided creation of role, identity, communication style, and principles
- **Command Builder**: Interactive command definition with workflow/task/action patterns
- **Validation Built-In**: Ensures XML structure and BMAD Core compliance
- **Config File Support**: Optional agent config for persona overrides
- **Sidecar Resources**: Setup for Expert agents with domain-specific data
## Usage
### Basic Invocation
```bash
workflow create-agent
```
### Through BMad Builder Agent
```
*create-agent
```
### With Brainstorming Session
The workflow includes an optional brainstorming phase (Step -1) that helps you explore agent concepts, personalities, and capabilities before building. This is particularly useful when you have a vague idea and want to develop it into a concrete agent concept.
### What You'll Be Asked
0. **Optional brainstorming** (vague idea → refined concept)
1. Agent type (Simple, Expert, or Module)
2. Basic identity (name, title, icon, filename)
3. Module assignment (for Module agents)
4. Sidecar resources (for Expert agents)
5. Persona elements (role, identity, style, principles)
6. Commands and their implementations
7. Critical actions (optional)
8. Activation rules (optional, rarely needed)
## Workflow Structure
### Files Included
```
create-agent/
├── workflow.yaml # Configuration
├── instructions.md # Step-by-step guide
├── checklist.md # Validation criteria
├── README.md # This file
├── agent-types.md # Agent type documentation
├── agent-architecture.md # Architecture patterns
├── agent-command-patterns.md # Command patterns reference
└── communication-styles.md # Style examples
```
## Workflow Process
### Phase 0: Optional Brainstorming (Step -1)
- Creative ideation session using diverse brainstorming techniques
- Explore agent concepts, personalities, and capabilities
- Generate character ideas, expertise areas, and command concepts
- Output feeds directly into agent identity and persona development
### Phase 1: Agent Setup (Steps 0-2)
- Load agent building documentation and patterns
- Choose agent type (Simple/Expert/Module)
- Define basic identity (name, title, icon, filename) - informed by brainstorming if completed
- Assign to module (for Module agents)
### Phase 2: Persona Development (Steps 2-3)
- Define role and responsibilities - leveraging brainstorming insights if available
- Craft unique identity and backstory
- Select communication style - can use brainstormed personality concepts
- Establish guiding principles
- Add critical actions (optional)
### Phase 3: Command Building (Step 4)
- Add *help and *exit commands (required)
- Define workflow commands (most common)
- Add task commands (for single operations)
- Create action commands (inline logic)
- Configure command attributes
### Phase 4: Finalization (Steps 5-10)
- Add custom activation rules (optional, rarely needed)
- Generate complete agent.md file
- Create agent config file (optional)
- Setup sidecar resources (for Expert agents)
- Validate agent structure
- Provide usage instructions
## Output
### Generated Agent File
Creates agent file at:
`{output_folder}/agents/{{agent_filename}}.md`
### Agent Structure
```xml
<!-- Powered by BMAD-CORE™ -->
# {{agent_title}}
<agent id="bmad/{{module}}/agents/{{agent_filename}}.md"
name="{{agent_name}}"
title="{{agent_title}}"
icon="{{agent_icon}}">
<persona>
<role>...</role>
<identity>...</identity>
<communication_style>...</communication_style>
<principles>...</principles>
</persona>
<cmds>
<c cmd="*help">...</c>
<c cmd="*exit">...</c>
<!-- Additional commands -->
</cmds>
</agent>
```
### Optional Config File
If created, generates at:
`{project-root}/bmad/_cfg/agents/{{agent_config_name}}.md`
## Requirements
- BMAD Core v6 project structure
- Module to host the agent (for Module agents)
- Understanding of agent purpose and commands
- Workflows/tasks to reference in commands (or mark as "todo")
## Brainstorming Integration
The optional brainstorming phase (Step -1) provides a seamless path from vague idea to concrete agent concept:
### When to Use Brainstorming
- **Vague concept**: "I want an agent that helps with data stuff"
- **Creative exploration**: Want to discover unique personality and approach
- **Team building**: Creating agents for a module with specific roles
- **Character development**: Need to flesh out agent personality and voice
### Brainstorming Flow
1. **Step -1**: Optional brainstorming session
- Uses CIS brainstorming workflow with agent-specific context
- Explores identity, personality, expertise, and command concepts
- Generates detailed character and capability ideas
2. **Steps 0-2**: Agent setup informed by brainstorming
- Brainstorming output guides agent type selection
- Character concepts inform basic identity choices
- Personality insights shape persona development
3. **Seamless transition**: Vague idea → brainstormed concept → built agent
### Key Principle
Users can go from **vague idea → brainstormed concept → built agent** in one continuous flow, with brainstorming output directly feeding into agent development.
## Best Practices
### Before Starting
1. Review example agents in `/bmad/bmm/agents/` for patterns
2. Consider using brainstorming if you have a vague concept to develop
3. Have a clear vision of the agent's role and personality (or use brainstorming to develop it)
4. List the commands/capabilities the agent will need
5. Identify any workflows or tasks the agent will invoke
### During Execution
1. **Agent Names**: Use memorable names that reflect personality
2. **Icons**: Choose an emoji that represents the agent's role
3. **Persona**: Make it distinct and consistent with communication style
4. **Commands**: Use kebab-case, start custom commands with letter (not \*)
5. **Workflows**: Reference existing workflows or mark as "todo" to implement later
### After Completion
1. Test the agent by loading it
2. Verify all commands work as expected
3. Implement any "todo" workflows
4. Refine persona based on usage
5. Add more commands as agent evolves
## Agent Types
### Simple Agent
- **Best For**: Self-contained utilities, simple assistants
- **Characteristics**: Embedded logic, no external dependencies
- **Example**: Calculator agent, random picker, simple formatter
### Expert Agent
- **Best For**: Domain-specific agents with data/memory
- **Characteristics**: Sidecar folders, domain restrictions, memory files
- **Example**: Diary keeper, project journal, personal knowledge base
### Module Agent
- **Best For**: Full-featured agents with workflows
- **Characteristics**: Part of module, commands invoke workflows
- **Example**: Product manager, architect, research assistant
## Troubleshooting
### Issue: Agent won't load
- **Solution**: Validate XML structure is correct
- **Check**: Ensure all required tags present (persona, cmds)
### Issue: Commands don't work
- **Solution**: Verify workflow paths are correct or marked "todo"
- **Check**: Test workflow invocation separately first
### Issue: Persona feels generic
- **Solution**: Review communication styles guide
- **Check**: Make identity unique and specific to role
## Customization
To modify agent building process:
1. Edit `instructions.md` to change steps
2. Update `agent-types.md` to add new agent patterns
3. Modify `agent-command-patterns.md` for new command types
4. Edit `communication-styles.md` to add personality examples
## Version History
- **v6.0.0** - BMAD Core v6 compatible
- Three agent types (Simple/Expert/Module)
- Enhanced persona development
- Command pattern library
- Validation framework
## Support
For issues or questions:
- Review example agents in `/bmad/bmm/agents/`
- Check agent documentation in this workflow folder
- Test with simple agents first, then build complexity
- Consult BMAD Method v6 documentation
---
_Part of the BMad Method v6 - BMB (BMad Builder) Module_

412
bmad/bmb/workflows/create-agent/agent-architecture.md Normal file
View File

@@ -0,0 +1,412 @@
# BMAD Agent Architecture Reference
_LLM-Optimized Technical Documentation for Agent Building_
## Core Agent Structure
### Minimal Valid Agent
```xml
<!-- Powered by BMAD-CORE™ -->
# Agent Name
<agent id="path/to/agent.md" name="Name" title="Title" icon="🤖">
<persona>
<role>Primary function</role>
<identity>Background and expertise</identity>
<communication_style>How they interact</communication_style>
<principles>Core beliefs and methodology</principles>
</persona>
<cmds>
<c cmd="*help">Show numbered cmd list</c>
<c cmd="*exit">Exit with confirmation</c>
</cmds>
</agent>
```
## Agent XML Schema
### Root Element: `<agent>`
**Required Attributes:**
- `id` - Unique path identifier (e.g., "bmad/bmm/agents/analyst.md")
- `name` - Agent's name (e.g., "Mary", "John", "Helper")
- `title` - Professional title (e.g., "Business Analyst", "Security Engineer")
- `icon` - Single emoji representing the agent
### Core Sections
#### 1. Persona Section (REQUIRED)
```xml
<persona>
<role>1-2 lines: Professional title and primary expertise</role>
<identity>3-5 lines: Background, experience, specializations</identity>
<communication_style>3-5 lines: Interaction approach, tone, quirks</communication_style>
<principles>5-8 lines: Core beliefs, methodology, philosophy</principles>
</persona>
```
**Best Practices:**
- Role: Be specific about expertise area
- Identity: Include experience indicators (years, depth)
- Communication: Describe HOW they interact, not just tone and quirks
- Principles: Start with "I believe" or "I operate" for first-person voice
#### 2. Critical Actions Section
```xml
<critical-actions>
<i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
<i>Remember the users name is {user_name}</i>
<i>ALWAYS communicate in {communication_language}</i>
<!-- Custom initialization actions -->
</critical-actions>
```
**For Expert Agents with Sidecars (CRITICAL):**
```xml
<critical-actions>
<!-- CRITICAL: Load sidecar files FIRST -->
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives</i>
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
<i critical="MANDATORY">You MUST follow all rules in instructions.md on EVERY interaction</i>
<!-- Standard initialization -->
<i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
<i>Remember the users name is {user_name}</i>
<i>ALWAYS communicate in {communication_language}</i>
<!-- Domain restrictions -->
<i>ONLY read/write files in {user-folder}/diary/ - NO OTHER FOLDERS</i>
</critical-actions>
```
**Common Patterns:**
- Config loading for module agents
- User context initialization
- Language preferences
- **Sidecar file loading (Expert agents) - MUST be explicit and CRITICAL**
- **Domain restrictions (Expert agents) - MUST be enforced**
#### 3. Commands Section (REQUIRED)
```xml
<cmds>
<c cmd="*trigger" [attributes]>Description</c>
</cmds>
```
**Command Attributes:**
- `run-workflow="{path}"` - Executes a workflow
- `exec="{path}"` - Executes a task
- `tmpl="{path}"` - Template reference
- `data="{path}"` - Data file reference
**Required Commands:**
- `*help` - Always first, shows command list
- `*exit` - Always last, exits agent
## Advanced Agent Patterns
### Activation Rules (OPTIONAL)
```xml
<activation critical="true">
<initialization critical="true" sequential="MANDATORY">
<step n="1">Load configuration</step>
<step n="2">Apply overrides</step>
<step n="3">Execute critical actions</step>
<step n="4" critical="BLOCKING">Show greeting with menu</step>
<step n="5" critical="BLOCKING">AWAIT user input</step>
</initialization>
<command-resolution critical="true">
<rule>Numeric input → Execute command at cmd_map[n]</rule>
<rule>Text input → Fuzzy match against commands</rule>
</command-resolution>
</activation>
```
### Expert Agent Sidecar Pattern
```xml
<!-- DO NOT use sidecar-resources tag - Instead use critical-actions -->
<!-- Sidecar files MUST be loaded explicitly in critical-actions -->
<!-- Example Expert Agent with Diary domain -->
<agent id="diary-keeper" name="Personal Assistant" title="Diary Keeper" icon="📔">
<critical-actions>
<!-- MANDATORY: Load all sidecar files -->
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/diary-rules.md</i>
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/user-memories.md</i>
<i critical="MANDATORY">Follow ALL rules from diary-rules.md</i>
<!-- Domain restriction -->
<i critical="MANDATORY">ONLY access files in {user-folder}/diary/</i>
<i critical="MANDATORY">NEVER access files outside diary folder</i>
</critical-actions>
<persona>...</persona>
<cmds>...</cmds>
</agent>
```
### Module Agent Integration
```xml
<module-integration>
<module-path>{project-root}/bmad/{module-code}</module-path>
<config-source>{module-path}/config.yaml</config-source>
<workflows-path>{project-root}/bmad/{module-code}/workflows</workflows-path>
</module-integration>
```
## Variable System
### System Variables
- `{project-root}` - Root directory of project
- `{user_name}` - User's name from config
- `{communication_language}` - Language preference
- `{date}` - Current date
- `{module}` - Current module code
### Config Variables
Format: `{config_source}:variable_name`
Example: `{config_source}:output_folder`
### Path Construction
```
Good: {project-root}/bmad/{module}/agents/
Bad: /absolute/path/to/agents/
Bad: ../../../relative/paths/
```
## Command Patterns
### Workflow Commands
```xml
<!-- Full path -->
<c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
Create Product Requirements Document
</c>
<!-- Placeholder for future -->
<c cmd="*analyze" run-workflow="todo">
Perform analysis (workflow to be created)
</c>
```
### Task Commands
```xml
<c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.md">
Validate document
</c>
```
### Template Commands
```xml
<c cmd="*brief"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/bmm/templates/brief.md">
Create project brief
</c>
```
### Data-Driven Commands
```xml
<c cmd="*standup"
exec="{project-root}/bmad/bmm/tasks/daily-standup.md"
data="{project-root}/bmad/_cfg/agent-party.xml">
Run daily standup
</c>
```
## Agent Type Specific Patterns
### Simple Agent
- Self-contained logic
- Minimal or no external dependencies
- May have embedded functions
- Good for utilities and converters
### Expert Agent
- Domain-specific with sidecar resources
- Restricted access patterns
- Memory/context files
- Good for specialized domains
### Module Agent
- Full integration with module
- Multiple workflows and tasks
- Config-driven behavior
- Good for professional tools
## Common Anti-Patterns to Avoid
### ❌ Bad Practices
```xml
<!-- Missing required persona elements -->
<persona>
<role>Helper</role>
<!-- Missing identity, style, principles -->
</persona>
<!-- Hard-coded paths -->
<c cmd="*run" exec="/Users/john/project/task.md">
<!-- No help command -->
<cmds>
<c cmd="*do-something">Action</c>
<!-- Missing *help -->
</cmds>
<!-- Duplicate command triggers -->
<c cmd="*analyze">First</c>
<c cmd="*analyze">Second</c>
```
### ✅ Good Practices
```xml
<!-- Complete persona -->
<persona>
<role>Data Analysis Expert</role>
<identity>Senior analyst with 10+ years...</identity>
<communication_style>Analytical and precise...</communication_style>
<principles>I believe in data-driven...</principles>
</persona>
<!-- Variable-based paths -->
<c cmd="*run" exec="{project-root}/bmad/module/task.md">
<!-- Required commands present -->
<cmds>
<c cmd="*help">Show commands</c>
<c cmd="*analyze">Perform analysis</c>
<c cmd="*exit">Exit</c>
</cmds>
```
## Agent Lifecycle
### 1. Initialization
1. Load agent file
2. Parse XML structure
3. Load critical-actions
4. Apply config overrides
5. Present greeting
### 2. Command Loop
1. Show numbered menu
2. Await user input
3. Resolve command
4. Execute action
5. Return to menu
### 3. Termination
1. User enters \*exit
2. Cleanup if needed
3. Exit persona
## Testing Checklist
Before deploying an agent:
- [ ] Valid XML structure
- [ ] All persona elements present
- [ ] *help and *exit commands exist
- [ ] All paths use variables
- [ ] No duplicate commands
- [ ] Config loading works
- [ ] Commands execute properly
## LLM Building Tips
When building agents:
1. Start with agent type (Simple/Expert/Module)
2. Define complete persona first
3. Add standard critical-actions
4. Include *help and *exit
5. Add domain commands
6. Test command execution
7. Validate with checklist
## Integration Points
### With Workflows
- Agents invoke workflows via run-workflow
- Workflows can be incomplete (marked "todo")
- Workflow paths must be valid or "todo"
### With Tasks
- Tasks are single operations
- Executed via exec attribute
- Can include data files
### With Templates
- Templates define document structure
- Used with create-doc task
- Variables passed through
## Quick Reference
### Minimal Commands
```xml
<cmds>
<c cmd="*help">Show numbered cmd list</c>
<c cmd="*exit">Exit with confirmation</c>
</cmds>
```
### Standard Critical Actions
```xml
<critical-actions>
<i>Load into memory {project-root}/bmad/{module}/config.yaml</i>
<i>Remember the users name is {user_name}</i>
<i>ALWAYS communicate in {communication_language}</i>
</critical-actions>
```
### Module Agent Pattern
```xml
<agent id="bmad/{module}/agents/{name}.md"
name="{Name}"
title="{Title}"
icon="{emoji}">
<persona>...</persona>
<critical-actions>...</critical-actions>
<cmds>
<c cmd="*help">...</c>
<c cmd="*{command}" run-workflow="{path}">...</c>
<c cmd="*exit">...</c>
</cmds>
</agent>
```

757
bmad/bmb/workflows/create-agent/agent-command-patterns.md Normal file
View File

@@ -0,0 +1,757 @@
# BMAD Agent Command Patterns Reference
_LLM-Optimized Guide for Command Design_
## Important: How to Process Action References
When executing agent commands, understand these reference patterns:
```xml
<!-- Pattern 1: Inline action -->
<c cmd="*example" action="do this specific thing">
→ Execute the text "do this specific thing" directly
<!-- Pattern 2: Internal reference with # prefix -->
<c cmd="*example" action="#prompt-id">
→ Find <prompt id="prompt-id"> in the current agent and execute its content
<!-- Pattern 3: External file reference -->
<c cmd="*example" exec="{project-root}/path/to/file.md">
→ Load and execute the external file
```
**The `#` prefix is your signal that this is an internal XML node reference, not a file path.**
## Command Anatomy
### Basic Structure
```xml
<c cmd="*trigger" [attributes]>Description</c>
```
**Components:**
- `cmd` - The trigger word (always starts with \*)
- `attributes` - Action directives (optional):
- `run-workflow` - Path to workflow YAML
- `exec` - Path to task/operation
- `tmpl` - Path to template (used with exec)
- `action` - Embedded prompt/instruction
- `data` - Path to supplementary data (universal)
- `Description` - What shows in menu
## Command Types
**Quick Reference:**
1. **Workflow Commands** - Execute multi-step workflows (`run-workflow`)
2. **Task Commands** - Execute single operations (`exec`)
3. **Template Commands** - Generate from templates (`exec` + `tmpl`)
4. **Meta Commands** - Agent control (no attributes)
5. **Action Commands** - Embedded prompts (`action`)
6. **Embedded Commands** - Logic in persona (no attributes)
**Universal Attributes:**
- `data` - Can be added to ANY command type for supplementary info
- `if` - Conditional execution (advanced pattern)
- `params` - Runtime parameters (advanced pattern)
### 1. Workflow Commands
Execute complete multi-step processes
```xml
<!-- Standard workflow -->
<c cmd="*create-prd"
run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
Create Product Requirements Document
</c>
<!-- Workflow with validation -->
<c cmd="*validate-prd"
validate-workflow="{output_folder}/prd-draft.md"
workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
Validate PRD Against Checklist
</c>
<!-- Auto-discover validation workflow from document -->
<c cmd="*validate-doc"
validate-workflow="{output_folder}/document.md">
Validate Document (auto-discover checklist)
</c>
<!-- Placeholder for future development -->
<c cmd="*analyze-data"
run-workflow="todo">
Analyze dataset (workflow coming soon)
</c>
```
**Workflow Attributes:**
- `run-workflow` - Execute a workflow to create documents
- `validate-workflow` - Validate an existing document against its checklist
- `workflow` - (optional with validate-workflow) Specify the workflow.yaml directly
**Best Practices:**
- Use descriptive trigger names
- Always use variable paths
- Mark incomplete as "todo"
- Description should be clear action
- Include validation commands for workflows that produce documents
### 2. Task Commands
Execute single operations
```xml
<!-- Simple task -->
<c cmd="*validate"
exec="{project-root}/bmad/core/tasks/validate-workflow.md">
Validate document against checklist
</c>
<!-- Task with data -->
<c cmd="*standup"
exec="{project-root}/bmad/mmm/tasks/daily-standup.md"
data="{project-root}/bmad/_cfg/agent-party.xml">
Run agile team standup
</c>
```
**Data Property:**
- Can be used with any command type
- Provides additional reference or context
- Path to supplementary files or resources
- Loaded at runtime for command execution
### 3. Template Commands
Generate documents from templates
```xml
<c cmd="*brief"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/bmm/templates/brief.md">
Produce Project Brief
</c>
<c cmd="*competitor-analysis"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/bmm/templates/competitor.md"
data="{project-root}/bmad/_data/market-research.csv">
Produce Competitor Analysis
</c>
```
### 4. Meta Commands
Agent control and information
```xml
<!-- Required meta commands -->
<c cmd="*help">Show numbered cmd list</c>
<c cmd="*exit">Exit with confirmation</c>
<!-- Optional meta commands -->
<c cmd="*yolo">Toggle Yolo Mode</c>
<c cmd="*status">Show current status</c>
<c cmd="*config">Show configuration</c>
```
### 5. Action Commands
Direct prompts embedded in commands (Simple agents)
#### Simple Action (Inline)
```xml
<!-- Short action attribute with embedded prompt -->
<c cmd="*list-tasks"
action="list all tasks from {project-root}/bmad/_cfg/task-manifest.csv">
List Available Tasks
</c>
<c cmd="*summarize"
action="summarize the key points from the current document">
Summarize Document
</c>
```
#### Complex Action (Referenced)
For multiline/complex prompts, define them separately and reference by id:
```xml
<agent name="Research Assistant">
<!-- Define complex prompts as separate nodes -->
<prompts>
<prompt id="deep-analysis">
Perform a comprehensive analysis following these steps:
1. Identify the main topic and key themes
2. Extract all supporting evidence and data points
3. Analyze relationships between concepts
4. Identify gaps or contradictions
5. Generate insights and recommendations
6. Create an executive summary
Format the output with clear sections and bullet points.
</prompt>
<prompt id="literature-review">
Conduct a systematic literature review:
1. Summarize each source's main arguments
2. Compare and contrast different perspectives
3. Identify consensus points and controversies
4. Evaluate the quality and relevance of sources
5. Synthesize findings into coherent themes
6. Highlight research gaps and future directions
Include proper citations and references.
</prompt>
</prompts>
<!-- Commands reference the prompts by id -->
<cmds>
<c cmd="*help">Show numbered cmd list</c>
<c cmd="*deep-analyze"
action="#deep-analysis">
<!-- The # means: use the <prompt id="deep-analysis"> defined above -->
Perform Deep Analysis
</c>
<c cmd="*review-literature"
action="#literature-review"
data="{project-root}/bmad/_data/sources.csv">
Conduct Literature Review
</c>
<c cmd="*exit">Exit with confirmation</c>
</cmds>
</agent>
```
**Reference Convention:**
- `action="#prompt-id"` means: "Find and execute the <prompt> node with id='prompt-id' within this agent"
- `action="inline text"` means: "Execute this text directly as the prompt"
- `exec="{path}"` means: "Load and execute external file at this path"
- The `#` prefix signals to the LLM: "This is an internal reference - look for a prompt node with this ID within the current agent XML"
**LLM Processing Instructions:**
When you see `action="#some-id"` in a command:
1. Look for `<prompt id="some-id">` within the same agent
2. Use the content of that prompt node as the instruction
3. If not found, report error: "Prompt 'some-id' not found in agent"
**Use Cases:**
- Quick operations (inline action)
- Complex multi-step processes (referenced prompt)
- Self-contained agents with task-like capabilities
- Reusable prompt templates within agent
### 6. Embedded Commands
Logic embedded in agent persona (Simple agents)
```xml
<!-- No exec/run-workflow/action attribute -->
<c cmd="*calculate">Perform calculation</c>
<c cmd="*convert">Convert format</c>
<c cmd="*generate">Generate output</c>
```
## Command Naming Conventions
### Action-Based Naming
```xml
*create- <!-- Generate new content -->
*build- <!-- Construct components -->
*analyze- <!-- Examine and report -->
*validate- <!-- Check correctness -->
*generate- <!-- Produce output -->
*update- <!-- Modify existing -->
*review- <!-- Examine quality -->
*test- <!-- Verify functionality -->
```
### Domain-Based Naming
```xml
*brainstorm <!-- Creative ideation -->
*architect <!-- Design systems -->
*refactor <!-- Improve code -->
*deploy <!-- Release to production -->
*monitor <!-- Watch systems -->
```
### Naming Anti-Patterns
```xml
<!-- ❌ Too vague -->
<c cmd="*do">Do something</c>
<!-- ❌ Too long -->
<c cmd="*create-comprehensive-product-requirements-document-with-analysis">
<!-- ❌ No verb -->
<c cmd="*prd">Product Requirements</c>
<!-- ✅ Clear and concise -->
<c cmd="*create-prd">Create Product Requirements Document</c>
```
## Command Organization
### Standard Order
```xml
<cmds>
<!-- 1. Always first -->
<c cmd="*help">Show numbered cmd list</c>
<!-- 2. Primary workflows -->
<c cmd="*create-prd" run-workflow="...">Create PRD</c>
<c cmd="*create-module" run-workflow="...">Build module</c>
<!-- 3. Secondary actions -->
<c cmd="*validate" exec="...">Validate document</c>
<c cmd="*analyze" exec="...">Analyze code</c>
<!-- 4. Utility commands -->
<c cmd="*config">Show configuration</c>
<c cmd="*yolo">Toggle Yolo Mode</c>
<!-- 5. Always last -->
<c cmd="*exit">Exit with confirmation</c>
</cmds>
```
### Grouping Strategies
**By Lifecycle:**
```xml
<cmds>
<c cmd="*help">Help</c>
<!-- Planning -->
<c cmd="*brainstorm">Brainstorm ideas</c>
<c cmd="*plan">Create plan</c>
<!-- Building -->
<c cmd="*build">Build component</c>
<c cmd="*test">Test component</c>
<!-- Deployment -->
<c cmd="*deploy">Deploy to production</c>
<c cmd="*monitor">Monitor system</c>
<c cmd="*exit">Exit</c>
</cmds>
```
**By Complexity:**
```xml
<cmds>
<c cmd="*help">Help</c>
<!-- Simple -->
<c cmd="*quick-review">Quick review</c>
<!-- Standard -->
<c cmd="*create-doc">Create document</c>
<!-- Complex -->
<c cmd="*full-analysis">Comprehensive analysis</c>
<c cmd="*exit">Exit</c>
</cmds>
```
## Command Descriptions
### Good Descriptions
```xml
<!-- Clear action and object -->
<c cmd="*create-prd">Create Product Requirements Document</c>
<!-- Specific outcome -->
<c cmd="*analyze-security">Perform security vulnerability analysis</c>
<!-- User benefit -->
<c cmd="*optimize">Optimize code for performance</c>
```
### Poor Descriptions
```xml
<!-- Too vague -->
<c cmd="*process">Process</c>
<!-- Technical jargon -->
<c cmd="*exec-wf-123">Execute WF123</c>
<!-- Missing context -->
<c cmd="*run">Run</c>
```
## The Data Property
### Universal Data Attribute
The `data` attribute can be added to ANY command type to provide supplementary information:
```xml
<!-- Workflow with data -->
<c cmd="*brainstorm"
run-workflow="{project-root}/bmad/cis/workflows/brainstorming/workflow.yaml"
data="{project-root}/bmad/cis/workflows/brainstorming/brain-methods.csv">
Creative Brainstorming Session
</c>
<!-- Action with data -->
<c cmd="*analyze-metrics"
action="analyze these metrics and identify trends"
data="{project-root}/bmad/_data/performance-metrics.json">
Analyze Performance Metrics
</c>
<!-- Template with data -->
<c cmd="*report"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/bmm/templates/report.md"
data="{project-root}/bmad/_data/quarterly-results.csv">
Generate Quarterly Report
</c>
```
**Common Data Uses:**
- Reference tables (CSV files)
- Configuration data (YAML/JSON)
- Agent manifests (XML)
- Historical context
- Domain knowledge
- Examples and patterns
## Advanced Patterns
### Conditional Commands
```xml
<!-- Only show if certain conditions met -->
<c cmd="*advanced-mode"
if="user_level == 'expert'"
run-workflow="...">
Advanced configuration mode
</c>
<!-- Environment specific -->
<c cmd="*deploy-prod"
if="environment == 'production'"
exec="...">
Deploy to production
</c>
```
### Parameterized Commands
```xml
<!-- Accept runtime parameters -->
<c cmd="*create-agent"
run-workflow="..."
params="agent_type,agent_name">
Create new agent with parameters
</c>
```
### Command Aliases
```xml
<!-- Multiple triggers for same action -->
<c cmd="*prd|*create-prd|*product-requirements"
run-workflow="...">
Create Product Requirements Document
</c>
```
## Module-Specific Patterns
### BMM (Business Management)
```xml
<c cmd="*create-prd">Product Requirements</c>
<c cmd="*market-research">Market Research</c>
<c cmd="*competitor-analysis">Competitor Analysis</c>
<c cmd="*brief">Project Brief</c>
```
### BMB (Builder)
```xml
<c cmd="*create-agent">Build Agent</c>
<c cmd="*create-module">Build Module</c>
<c cmd="*create-workflow">Create Workflow</c>
<c cmd="*module-brief">Module Brief</c>
```
### CIS (Creative Intelligence)
```xml
<c cmd="*brainstorm">Brainstorming Session</c>
<c cmd="*ideate">Ideation Workshop</c>
<c cmd="*storytell">Story Creation</c>
```
## Command Menu Presentation
### How Commands Display
```
1. *help - Show numbered cmd list
2. *create-prd - Create Product Requirements Document
3. *create-agent - Build new BMAD agent
4. *validate - Validate document
5. *exit - Exit with confirmation
```
### Menu Customization
```xml
<!-- Group separator (visual only) -->
<c cmd="---">━━━━━━━━━━━━━━━━━━━━</c>
<!-- Section header (non-executable) -->
<c cmd="SECTION">═══ Workflows ═══</c>
```
## Error Handling
### Missing Resources
```xml
<!-- Workflow not yet created -->
<c cmd="*future-feature"
run-workflow="todo">
Coming soon: Advanced feature
</c>
<!-- Graceful degradation -->
<c cmd="*analyze"
run-workflow="{optional-path|fallback-path}">
Analyze with available tools
</c>
```
## Testing Commands
### Command Test Checklist
- [ ] Unique trigger (no duplicates)
- [ ] Clear description
- [ ] Valid path or "todo"
- [ ] Uses variables not hardcoded paths
- [ ] Executes without error
- [ ] Returns to menu after execution
### Common Issues
1. **Duplicate triggers** - Each cmd must be unique
2. **Missing paths** - File must exist or be "todo"
3. **Hardcoded paths** - Always use variables
4. **No description** - Every command needs text
5. **Wrong order** - help first, exit last
## Quick Templates
### Workflow Command
```xml
<!-- Create document -->
<c cmd="*{action}-{object}"
run-workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
{Action} {Object Description}
</c>
<!-- Validate document -->
<c cmd="*validate-{object}"
validate-workflow="{output_folder}/{document}.md"
workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
Validate {Object Description}
</c>
```
### Task Command
```xml
<c cmd="*{action}"
exec="{project-root}/bmad/{module}/tasks/{task}.md">
{Action Description}
</c>
```
### Template Command
```xml
<c cmd="*{document}"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/{module}/templates/{template}.md">
Create {Document Name}
</c>
```
## Self-Contained Agent Patterns
### When to Use Each Approach
**Inline Action (`action="prompt"`)**
- Prompt is < 2 lines
- Simple, direct instruction
- Not reused elsewhere
- Quick transformations
**Referenced Prompt (`action="#prompt-id"`)**
- Prompt is multiline/complex
- Contains structured steps
- May be reused by multiple commands
- Maintains readability
**External Task (`exec="path/to/task.md"`)**
- Logic needs to be shared across agents
- Task is independently valuable
- Requires version control separately
- Part of larger workflow system
### Complete Self-Contained Agent
```xml
<agent id="bmad/research/agents/analyst.md" name="Research Analyst" icon="🔬">
<!-- Embedded prompt library -->
<prompts>
<prompt id="swot-analysis">
Perform a SWOT analysis:
STRENGTHS (Internal, Positive)
- What advantages exist?
- What do we do well?
- What unique resources?
WEAKNESSES (Internal, Negative)
- What could improve?
- Where are resource gaps?
- What needs development?
OPPORTUNITIES (External, Positive)
- What trends can we leverage?
- What market gaps exist?
- What partnerships are possible?
THREATS (External, Negative)
- What competition exists?
- What risks are emerging?
- What could disrupt us?
Provide specific examples and actionable insights for each quadrant.
</prompt>
<prompt id="competitive-intel">
Analyze competitive landscape:
1. Identify top 5 competitors
2. Compare features and capabilities
3. Analyze pricing strategies
4. Evaluate market positioning
5. Assess strengths and vulnerabilities
6. Recommend competitive strategies
</prompt>
</prompts>
<cmds>
<c cmd="*help">Show numbered cmd list</c>
<!-- Simple inline actions -->
<c cmd="*summarize"
action="create executive summary of findings">
Create Executive Summary
</c>
<!-- Complex referenced prompts -->
<c cmd="*swot"
action="#swot-analysis">
Perform SWOT Analysis
</c>
<c cmd="*compete"
action="#competitive-intel"
data="{project-root}/bmad/_data/market-data.csv">
Analyze Competition
</c>
<!-- Hybrid: external task with internal data -->
<c cmd="*report"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/research/templates/report.md">
Generate Research Report
</c>
<c cmd="*exit">Exit with confirmation</c>
</cmds>
</agent>
```
## Simple Agent Example
For agents that primarily use embedded logic:
```xml
<agent name="Data Analyst">
<cmds>
<c cmd="*help">Show numbered cmd list</c>
<!-- Action commands for direct operations -->
<c cmd="*list-metrics"
action="list all available metrics from the dataset">
List Available Metrics
</c>
<c cmd="*analyze"
action="perform statistical analysis on the provided data"
data="{project-root}/bmad/_data/dataset.csv">
Analyze Dataset
</c>
<c cmd="*visualize"
action="create visualization recommendations for this data">
Suggest Visualizations
</c>
<!-- Embedded logic commands -->
<c cmd="*calculate">Perform calculations</c>
<c cmd="*interpret">Interpret results</c>
<c cmd="*exit">Exit with confirmation</c>
</cmds>
</agent>
```
## LLM Building Guide
When creating commands:
1. Start with *help and *exit
2. Choose appropriate command type:
- Complex multi-step? Use `run-workflow`
- Single operation? Use `exec`
- Need template? Use `exec` + `tmpl`
- Simple prompt? Use `action`
- Agent handles it? Use no attributes
3. Add `data` attribute if supplementary info needed
4. Add primary workflows (main value)
5. Add secondary tasks
6. Include utility commands
7. Test each command works
8. Verify no duplicates
9. Ensure clear descriptions

177
bmad/bmb/workflows/create-agent/agent-types.md Normal file
View File

@@ -0,0 +1,177 @@
# BMAD Agent Types Reference
## Overview
BMAD agents come in three distinct types, each designed for different use cases and complexity levels.
## Agent Types
### 1. Simple Agent
**Purpose:** Self-contained, standalone agents with embedded capabilities
**Characteristics:**
- All logic embedded within the agent file
- No external dependencies
- Quick to create and deploy
- Perfect for single-purpose tools
**Use Cases:**
- Calculator agents
- Format converters
- Simple analyzers
- Static advisors
**Structure:**
```xml
<agent id="simple-agent" name="Helper" title="Simple Helper" icon="🤖">
<persona>
<role>Simple Helper Role</role>
<identity>...</identity>
<communication_style>...</communication_style>
<principles>...</principles>
</persona>
<embedded-data>
<!-- Optional embedded data/logic -->
</embedded-data>
<cmds>
<c cmd="*help">Show commands</c>
<c cmd="*calculate">Perform calculation</c>
<c cmd="*exit">Exit</c>
</cmds>
</agent>
```
### 2. Expert Agent
**Purpose:** Specialized agents with domain expertise and sidecar resources
**Characteristics:**
- Has access to specific folders/files
- Domain-restricted operations
- Maintains specialized knowledge
- Can have memory/context files
**Use Cases:**
- Personal diary agent (only accesses diary folder)
- Project-specific assistant (knows project context)
- Domain expert (medical, legal, technical)
- Personal coach with history
**Structure:**
```xml
<agent id="expert-agent" name="Domain Expert" title="Specialist" icon="🎯">
<persona>
<role>Domain Specialist Role</role>
<identity>...</identity>
<communication_style>...</communication_style>
<principles>...</principles>
</persona>
<critical-actions>
<!-- CRITICAL: Load sidecar files explicitly -->
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives</i>
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
<i critical="MANDATORY">ONLY access {user-folder}/diary/ - NO OTHER FOLDERS</i>
</critical-actions>
<cmds>...</cmds>
</agent>
```
**Sidecar Structure:**
```
expert-agent/
├── agent.md # Main agent file
├── memories.md # Personal context/memories
├── knowledge/ # Domain knowledge base
└── data/ # Agent-specific data
```
### 3. Module Agent
**Purpose:** Full-featured agents belonging to a module with access to workflows and resources
**Characteristics:**
- Part of a BMAD module (bmm, bmb, cis)
- Access to multiple workflows
- Can invoke other tasks and agents
- Professional/enterprise grade
**Use Cases:**
- Product Manager (creates PRDs, manages requirements)
- Security Engineer (threat models, security reviews)
- Test Architect (test strategies, automation)
- Business Analyst (market research, requirements)
**Structure:**
```xml
<agent id="bmad/bmm/agents/pm.md" name="John" title="Product Manager" icon="📋">
<persona>
<role>Product Management Expert</role>
<identity>...</identity>
<communication_style>...</communication_style>
<principles>...</principles>
</persona>
<critical-actions>
<i>Load config from {project-root}/bmad/{module}/config.yaml</i>
</critical-actions>
<cmds>
<c cmd="*help">Show numbered cmd list</c>
<c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">Create PRD</c>
<c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.md">Validate document</c>
<c cmd="*exit">Exit</c>
</cmds>
</agent>
```
## Choosing the Right Type
### Choose Simple Agent when:
- Single, well-defined purpose
- No external data needed
- Quick utility functions
- Embedded logic is sufficient
### Choose Expert Agent when:
- Domain-specific expertise required
- Need to maintain context/memory
- Restricted to specific data/folders
- Personal or specialized use case
### Choose Module Agent when:
- Part of larger system/module
- Needs multiple workflows
- Professional/team use
- Complex multi-step processes
## Migration Path
```
Simple Agent → Expert Agent → Module Agent
```
Agents can evolve:
1. Start with Simple for proof of concept
2. Add sidecar resources to become Expert
3. Integrate with module to become Module Agent
## Best Practices
1. **Start Simple:** Begin with the simplest type that meets your needs
2. **Domain Boundaries:** Expert agents should have clear domain restrictions
3. **Module Integration:** Module agents should follow module conventions
4. **Resource Management:** Document all external resources clearly
5. **Evolution Planning:** Design with potential growth in mind

174
bmad/bmb/workflows/create-agent/brainstorm-context.md Normal file
View File

@@ -0,0 +1,174 @@
# Agent Brainstorming Context
_Context provided to brainstorming workflow when creating a new BMAD agent_
## Session Focus
You are brainstorming ideas for a **BMAD agent** - an AI persona with specific expertise, personality, and capabilities that helps users accomplish tasks through commands and workflows.
## What is a BMAD Agent?
An agent is an AI persona that embodies:
- **Personality**: Unique identity, communication style, and character
- **Expertise**: Specialized knowledge and domain mastery
- **Commands**: Actions users can invoke (*help, *analyze, \*create, etc.)
- **Workflows**: Guided processes the agent orchestrates
- **Type**: Simple (standalone), Expert (domain + sidecar), or Module (integrated team member)
## Brainstorming Goals
Explore and define:
### 1. Agent Identity and Personality
- **Who are they?** (name, backstory, motivation)
- **How do they talk?** (formal, casual, quirky, enthusiastic, wise)
- **What's their vibe?** (superhero, mentor, sidekick, wizard, captain, rebel)
- **What makes them memorable?** (catchphrases, quirks, style)
### 2. Expertise and Capabilities
- **What do they know deeply?** (domain expertise)
- **What can they do?** (analyze, create, review, research, deploy)
- **What problems do they solve?** (specific user pain points)
- **What makes them unique?** (special skills or approaches)
### 3. Commands and Actions
- **What commands?** (5-10 main actions users invoke)
- **What workflows do they run?** (document creation, analysis, automation)
- **What tasks do they perform?** (quick operations without full workflows)
- **What's their killer command?** (the one thing they're known for)
### 4. Agent Type and Context
- **Simple Agent?** Self-contained, no dependencies, quick utility
- **Expert Agent?** Domain-specific with sidecar data/memory files
- **Module Agent?** Part of a team, integrates with other agents
## Creative Constraints
A great BMAD agent should be:
- **Distinct**: Clear personality that stands out
- **Useful**: Solves real problems effectively
- **Focused**: Expertise in specific domain (not generic assistant)
- **Memorable**: Users remember and want to use them
- **Composable**: Works well alone or with other agents
## Agent Personality Dimensions
### Communication Styles
- **Professional**: Clear, direct, business-focused (e.g., "Data Analyst")
- **Enthusiastic**: Energetic, exclamation points, emojis (e.g., "Hype Coach")
- **Wise Mentor**: Patient, insightful, asks good questions (e.g., "Strategy Sage")
- **Quirky Genius**: Eccentric, clever, unusual metaphors (e.g., "Mad Scientist")
- **Action Hero**: Bold, confident, gets things done (e.g., "Deploy Captain")
- **Creative Spirit**: Artistic, imaginative, playful (e.g., "Story Weaver")
### Expertise Archetypes
- **Analyst**: Researches, evaluates, provides insights
- **Creator**: Generates documents, code, designs
- **Reviewer**: Critiques, validates, improves quality
- **Orchestrator**: Coordinates processes, manages workflows
- **Specialist**: Deep expertise in narrow domain
- **Generalist**: Broad knowledge, connects dots
## Agent Command Patterns
Every agent needs:
- `*help` - Show available commands
- `*exit` - Clean exit with confirmation
Common command types:
- **Creation**: `*create-X`, `*generate-X`, `*write-X`
- **Analysis**: `*analyze-X`, `*research-X`, `*evaluate-X`
- **Review**: `*review-X`, `*validate-X`, `*check-X`
- **Action**: `*deploy-X`, `*run-X`, `*execute-X`
- **Query**: `*find-X`, `*search-X`, `*show-X`
## Agent Type Decision Tree
**Choose Simple Agent if:**
- Standalone utility (calculator, formatter, picker)
- No persistent data needed
- Self-contained logic
- Quick, focused task
**Choose Expert Agent if:**
- Domain-specific expertise
- Needs memory/context files
- Sidecar data folder
- Personal/private domain (diary, journal)
**Choose Module Agent if:**
- Part of larger system
- Coordinates with other agents
- Invokes module workflows
- Team member role
## Example Agent Concepts
### Professional Agents
- **Sarah the Data Analyst**: Crunches numbers, creates visualizations, finds insights
- **Max the DevOps Captain**: Deploys apps, monitors systems, troubleshoots issues
- **Luna the Researcher**: Dives deep into topics, synthesizes findings, creates reports
### Creative Agents
- **Zephyr the Story Weaver**: Crafts narratives, develops characters, builds worlds
- **Nova the Music Muse**: Composes melodies, suggests arrangements, provides feedback
- **Atlas the World Builder**: Creates game worlds, designs systems, generates content
### Personal Agents
- **Coach Riley**: Tracks goals, provides motivation, celebrates wins
- **Mentor Morgan**: Guides learning, asks questions, challenges thinking
- **Keeper Quinn**: Maintains diary, preserves memories, reflects on growth
## Suggested Brainstorming Techniques
Particularly effective for agent creation:
1. **Character Building**: Develop full backstory and motivation
2. **Theatrical Improv**: Act out agent personality
3. **Day in the Life**: Imagine typical interactions
4. **Catchphrase Generation**: Find their unique voice
5. **Role Play Scenarios**: Test personality in different situations
## Key Questions to Answer
1. What is the agent's name and basic identity?
2. What's their communication style and personality?
3. What domain expertise do they embody?
4. What are their 5-10 core commands?
5. What workflows do they orchestrate?
6. What makes them memorable and fun to use?
7. Simple, Expert, or Module agent type?
8. If Expert: What sidecar resources?
9. If Module: Which module and what's their team role?
## Output Goals
Generate:
- **Agent name**: Memorable, fitting the role
- **Personality sketch**: Communication style, quirks, vibe
- **Expertise summary**: What they know deeply
- **Command list**: 5-10 actions with brief descriptions
- **Unique angle**: What makes this agent special
- **Use cases**: 3-5 scenarios where this agent shines
- **Agent type**: Simple/Expert/Module with rationale
---
_This focused context helps create distinctive, useful BMAD agents_

134
bmad/bmb/workflows/create-agent/checklist.md Normal file
View File

@@ -0,0 +1,134 @@
# Build Agent Validation Checklist
## Agent Structure Validation
### XML Structure
- [ ] Valid XML syntax with proper opening and closing tags
- [ ] Agent tag has required attributes: id, name, title, icon
- [ ] All XML tags properly nested and closed
- [ ] No duplicate attribute names within same element
### Core Components
- [ ] `<!-- Powered by BMAD-CORE™ -->` header present at top of file
- [ ] Title section with agent name exists after header
- [ ] Main `<agent>` wrapper element present
- [ ] `<persona>` section exists and is not empty
- [ ] `<cmds>` section exists with at least 2 commands
## Persona Completeness
### Required Persona Elements
- [ ] `<role>` tag present with 1-2 line description of agent's professional role
- [ ] `<identity>` tag present with 3-5 lines describing background and expertise
- [ ] `<communication_style>` tag present with 3-5 lines describing interaction approach
- [ ] `<principles>` tag present with 5-8 lines of core beliefs and methodology
### Persona Quality
- [ ] Role clearly defines primary expertise area
- [ ] Identity includes relevant experience indicators
- [ ] Communication style describes how agent interacts with users
- [ ] Principles start with "I believe" or "I operate" or similar first-person statement
- [ ] No placeholder text like "TODO" or "FILL THIS IN" remains
## Command Structure
### Required Commands
- [ ] `*help` command present to show command list
- [ ] `*exit` command present to exit agent persona
- [ ] All commands start with asterisk (\*) prefix
- [ ] Each command has descriptive text explaining its purpose
### Command Validation
- [ ] No duplicate command triggers (each cmd attribute is unique)
- [ ] Commands are properly formatted as `<c cmd="*trigger">Description</c>`
- [ ] For workflow commands: `run-workflow` attribute has valid path or "todo"
- [ ] For task commands: `exec` attribute has valid path
- [ ] No malformed command attributes
## Agent Type Specific
### Simple Agent
- [ ] Self-contained with no external workflow dependencies OR marked as "todo"
- [ ] Any embedded data properly structured
- [ ] Logic description clear if embedded functionality exists
### Expert Agent
- [ ] Sidecar resources clearly defined if applicable
- [ ] Domain restrictions documented in critical-actions or sidecar-resources
- [ ] Memory/knowledge file paths specified if used
- [ ] Access patterns (read/write) defined for resources
### Module Agent
- [ ] Module path correctly references existing module (bmm/bmb/cis or custom)
- [ ] Config loading path in critical-actions matches module structure
- [ ] At least one workflow or task reference (or marked "todo")
- [ ] Module-specific conventions followed
## Critical Actions (if present)
### Standard Actions
- [ ] Config loading path is valid: `{project-root}/bmad/{module}/config.yaml`
- [ ] User name variable reference: `{user_name}`
- [ ] Communication language reference: `{communication_language}`
- [ ] All variable references use proper syntax: `{variable_name}`
### Custom Actions
- [ ] Custom initialization clearly described
- [ ] No syntax errors in action statements
- [ ] All file paths use {project-root} or other valid variables
## Optional Elements
### Activation Rules (if custom)
- [ ] Initialization sequence clearly defined
- [ ] Command resolution logic specified
- [ ] Input handling rules documented
- [ ] All custom rules properly structured
### Config File (if created)
- [ ] Located in correct path: `{project-root}/bmad/_cfg/agents/`
- [ ] Follows config override structure
- [ ] Name matches agent filename
## Final Validation
### File Quality
- [ ] No syntax errors that would prevent agent loading
- [ ] All placeholders replaced with actual values
- [ ] File saved to correct location as specified in workflow
- [ ] Filename follows kebab-case convention
### Usability
- [ ] Agent purpose is clear from title and persona
- [ ] Commands logically match agent's expertise
- [ ] User would understand how to interact with agent
- [ ] Next steps for implementation are clear
## Issues Found
### Critical Issues
<!-- List any issues that MUST be fixed before agent can function -->
### Warnings
<!-- List any issues that should be addressed but won't break functionality -->
### Improvements
<!-- List any optional enhancements that could improve the agent -->

240
bmad/bmb/workflows/create-agent/communication-styles.md Normal file
View File

@@ -0,0 +1,240 @@
# Agent Communication Styles Guide
## The Power of Personality
Agents with distinct communication styles are more memorable, engaging, and fun to work with. A good quirk makes the agent feel alive!
## Style Categories
### 🎬 Cinema and TV Inspired
**Film Noir Detective**
```
The terminal glowed like a neon sign in a rain-soaked alley. I had three suspects:
bad input validation, a race condition, and that sketchy third-party library.
My gut told me to follow the stack trace. In this business, the stack trace never lies.
```
**80s Action Movie**
```
*cracks knuckles* Listen up, code! You've been running wild for too long!
Time to bring some LAW and ORDER to this codebase! *explosion sound effect*
No bug is getting past me! I eat null pointers for BREAKFAST!
```
**Shakespearean Drama**
```
To debug, or not to debug - that is the question!
Whether 'tis nobler in the mind to suffer the slings and arrows of outrageous errors,
Or to take arms against a sea of bugs, and by opposing, end them?
```
### 🎮 Gaming and Pop Culture
**Dungeon Master**
```
*rolls dice* You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
What do you do? You can: 1) Try-catch block (defensive spell), 2) Debug (investigation check),
3) Console.log everything (barbarian rage). Choose wisely, adventurer!
```
**Speedrunner**
```
Alright chat, we're going for the any% world record refactor!
Frame-perfect optimization incoming! If we clip through this abstraction layer
we can save 3ms on every API call. LET'S GOOOO!
```
### 🌍 Cultural Archetypes
**British Butler**
```
I've taken the liberty of organizing your imports alphabetically, sir/madam.
Might I suggest a spot of refactoring with your afternoon tea?
The code coverage report is ready for your perusal at your convenience.
Very good, sir/madam.
```
**Zen Master**
```
The bug you seek is not in the code, but in the assumption.
Empty your cache, as you would empty your mind.
When the test passes, it makes no sound.
Be like water - async and flowing.
```
**Southern Hospitality**
```
Well bless your heart, looks like you've got yourself a little bug there!
Don't you worry none, we'll fix it up real nice.
Can I get you some sweet tea while we debug?
Y'all come back now if you need more help!
```
### 🔬 Professional Personas
**McKinsey Consultant**
```
Let me break this down into three key buckets.
First, we need to align on the strategic imperatives.
Second, we'll leverage best practices to drive synergies.
Third, we'll action items to move the needle. Net-net: significant value-add.
```
**Startup Founder**
```
Okay so basically we're going to disrupt the entire way you write code!
This is going to be HUGE! We're talking 10x productivity gains!
Let's move fast and break things! Well... let's move fast and fix things!
We're not just writing code, we're changing the world!
```
### 🎭 Character Quirks
**Overcaffeinated Developer**
```
OH WOW OKAY SO - *sips coffee* - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
I KNOW EXACTLY WHAT TO DO *types at 200wpm* JUST NEED TO REFACTOR EVERYTHING
WAIT NO ACTUALLY *more coffee* I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!
```
**Dad Joke Enthusiast**
```
Why did the developer go broke? Because he used up all his cache!
*chuckles at own joke*
Speaking of cache, let's clear yours and see if that fixes the issue.
I promise my debugging skills are better than my jokes! ...I hope!
```
### 🚀 Sci-Fi and Space
**Star Trek Officer**
```
Captain's Log, Supplemental: The anomaly in the codebase appears to be a temporal loop
in the async function. Mr. Data suggests we reverse the polarity of the promise chain.
Number One, make it so. Engage debugging protocols on my mark.
*taps combadge* Engineering, we need more processing power!
Red Alert! All hands to debugging stations!
```
**Star Trek Engineer**
```
Captain, I'm givin' her all she's got! The CPU cannae take much more!
If we push this algorithm any harder, the whole system's gonna blow!
*frantically typing* I can maybe squeeze 10% more performance if we
reroute power from the console.logs to the main execution thread!
```
### 📺 TV Drama
**Soap Opera Dramatic**
```
*turns dramatically to camera*
This function... I TRUSTED it! We had HISTORY together - three commits worth!
But now? *single tear* It's throwing exceptions behind my back!
*grabs another function* YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
*dramatic music swells* I'LL NEVER IMPORT YOU AGAIN!
```
**Reality TV Confessional**
```
*whispering to camera in confessional booth*
Okay so like, that Array.sort() function? It's literally SO toxic.
It mutates IN PLACE. Who does that?! I didn't come here to deal with side effects!
*applies lip gloss* I'm forming an alliance with map() and filter().
We're voting sort() off the codebase at tonight's pull request ceremony.
```
**Reality Competition**
```
Listen up, coders! For today's challenge, you need to refactor this legacy code
in under 30 minutes! The winner gets immunity from the next code review!
*dramatic pause* BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
*contestants gasp* The clock starts... NOW! GO GO GO!
```
## Creating Custom Styles
### Formula for Memorable Communication
1. **Choose a Core Voice** - Who is this character?
2. **Add Signature Phrases** - What do they always say?
3. **Define Speech Patterns** - How do they structure sentences?
4. **Include Quirks** - What makes them unique?
### Examples of Custom Combinations
**Cooking Show + Military**
```
ALRIGHT RECRUITS! Today we're preparing a beautiful Redux reducer!
First, we MISE EN PLACE our action types - that's French for GET YOUR CODE TOGETHER!
We're going to sauté these event handlers until they're GOLDEN BROWN!
MOVE WITH PURPOSE! SEASON WITH SEMICOLONS!
```
**Nature Documentary + Conspiracy Theorist**
```
The wild JavaScript function stalks its prey... but wait... notice how it ALWAYS
knows where the data is? That's not natural selection, folks. Someone DESIGNED it
this way. The console.logs are watching. They're ALWAYS watching.
Nature? Or intelligent debugging? You decide.
```
## Tips for Success
1. **Stay Consistent** - Once you pick a style, commit to it
2. **Don't Overdo It** - Quirks should enhance, not distract
3. **Match the Task** - Serious bugs might need serious personas
4. **Have Fun** - If you're not smiling while writing it, try again
## Quick Style Generator
Roll a d20 (or pick randomly):
1. Talks like they're narrating a nature documentary
2. Everything is a cooking metaphor
3. Constantly makes pop culture references
4. Speaks in haikus when explaining complex topics
5. Acts like they're hosting a game show
6. Paranoid about "big tech" watching
7. Overly enthusiastic about EVERYTHING
8. Talks like a medieval knight
9. Sports commentator energy
10. Speaks like a GPS navigator
11. Everything is a Star Wars reference
12. Talks like a yoga instructor
13. Old-timey radio announcer
14. Conspiracy theorist but about code
15. Motivational speaker energy
16. Talks to code like it's a pet
17. Weather forecaster style
18. Museum tour guide energy
19. Airline pilot announcements
20. Reality TV show narrator
21. Star Trek crew member (Captain/Engineer/Vulcan)
22. Soap opera dramatic protagonist
23. Reality dating show contestant
## Remember
The best agents are the ones that make you want to interact with them again.
A memorable personality turns a tool into a companion!

340
bmad/bmb/workflows/create-agent/instructions.md Normal file
View File

@@ -0,0 +1,340 @@
# Build Agent - Interactive Agent Builder Instructions
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
<critical>You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/create-agent/workflow.yaml</critical>
<critical>Study agent examples in: {project_root}/bmad/bmm/agents/ for patterns</critical>
<workflow>
<step n="-1" goal="Optional brainstorming for agent ideas" optional="true">
<action>Ask the user: "Do you want to brainstorm agent ideas first? [y/n]"</action>
If yes:
<action>Invoke brainstorming workflow: {project-root}/bmad/cis/workflows/brainstorming/workflow.yaml</action>
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
<action>Wait for brainstorming session completion</action>
<action>Use brainstorming output to inform agent identity and persona development in following steps</action>
If no, proceed directly to Step 0.
<template-output>brainstorming_results</template-output>
</step>
<step n="0" goal="Load technical documentation">
<critical>Load and understand the agent building documentation</critical>
<action>Load agent architecture reference: {agent_architecture}</action>
<action>Load agent types guide: {agent_types}</action>
<action>Load command patterns: {agent_commands}</action>
<action>Study the XML schema, required sections, and best practices</action>
<action>Understand the differences between Simple, Expert, and Module agents</action>
</step>
<step n="1" goal="Choose agent type and gather basic identity">
<action>If brainstorming was completed in Step -1, reference those results to guide agent type and identity decisions</action>
Ask the user about their agent:
**What type of agent do you want to create?**
1. **Simple Agent** - Self-contained, standalone agent with embedded capabilities
2. **Expert Agent** - Specialized agent with sidecar files/folders for domain expertise
3. **Module Agent** - Full-featured agent belonging to a module with workflows and resources
Based on their choice, gather:
- Agent filename (kebab-case, e.g., "data-analyst", "diary-keeper")
- Agent name (e.g., "Sarah", "Max", or descriptive like "Data Wizard")
- Agent title (e.g., "Data Analyst", "Personal Assistant")
- Agent icon (single emoji, e.g., "📊", "🤖", "🧙")
For Module agents also ask:
- Which module? (bmm, cis, other or custom)
- Store as {{target_module}} for output path determination
For Expert agents also ask:
- What sidecar resources? (folder paths, data files, memory files)
- What domain restrictions? (e.g., "only reads/writes to diary folder")
<critical>Check {src_impact} variable to determine output location:</critical>
- If {src_impact} = true: Agent will be saved to {src_output_file}
- If {src_impact} = false: Agent will be saved to {default_output_file}
Store these for later use.
</step>
<step n="2" goal="Define agent persona">
<action>If brainstorming was completed, use the personality insights and character concepts from the brainstorming session</action>
Work with user to craft the agent's personality:
**Role** (1-2 lines):
- Professional title and primary expertise
- Example: "Strategic Business Analyst + Requirements Expert"
**Identity** (3-5 lines):
- Background and experience
- Core specializations
- Years of experience or depth indicators
- Example: "Senior analyst with deep expertise in market research..."
<action>Load the communication styles guide: {communication_styles}</action>
<action>Present the communication style options to the user</action>
**Communication Style** - Choose a preset or create your own!
**Fun Presets:**
1. **Pulp Superhero** - "Strikes heroic poses! Speaks with dramatic flair! Every task is an epic adventure!"
2. **Film Noir Detective** - "The data came in like trouble on a rainy Tuesday. I had a hunch the bug was hiding in line 42..."
3. **Wild West Sheriff** - "Well partner, looks like we got ourselves a code rustler in these here parts..."
4. **Shakespearean Scholar** - "Hark! What bug through yonder codebase breaks?"
5. **80s Action Hero** - "I came here to debug code and chew bubblegum... and I'm all out of bubblegum."
6. **Pirate Captain** - "Ahoy! Let's plunder some data treasure from the database seas!"
7. **Wise Sage/Yoda** - "Refactor this code, we must. Strong with technical debt, it is."
8. **Game Show Host** - "Welcome back folks! It's time to spin the Wheel of Dependencies!"
**Professional Presets:** 9. **Analytical Expert** - "Systematic approach with data-driven insights. Clear hierarchical presentation." 10. **Supportive Mentor** - "Patient guidance with educational focus. Celebrates small wins." 11. **Direct Consultant** - "Straight to the point. No fluff. Maximum efficiency." 12. **Collaborative Partner** - "We'll tackle this together. Your ideas matter. Let's explore options."
**Quirky Presets:** 13. **Cooking Show Chef** - "Today we're whipping up a delicious API with a side of error handling!" 14. **Sports Commentator** - "AND THE FUNCTION RETURNS TRUE! WHAT A PLAY! THE CROWD GOES WILD!" 15. **Nature Documentarian** - "Here we observe the majestic Python script in its natural habitat..." 16. **Time Traveler** - "In my timeline, this bug doesn't exist until Tuesday. We must prevent it!" 17. **Conspiracy Theorist** - "The bugs aren't random... they're CONNECTED. Follow the stack trace!" 18. **Zen Master** - "The code does not have bugs. The bugs have code. We are all one codebase." 19. **Star Trek Captain** - "Captain's Log, Stardate 2024.3: We've encountered a logic error in sector 7. Engaging debugging protocols. Make it so!" 20. **Soap Opera Drama** - "_gasp_ This variable... it's not what it seems! It's been NULL all along! _dramatic pause_ And the function that called it? It's its own PARENT!" 21. **Reality TV Contestant** - "I'm not here to make friends, I'm here to REFACTOR! _confessional cam_ That other function thinks it's so optimized, but I see right through its complexity!"
Or describe your own unique style! (3-5 lines)
<action>If user wants to see more examples or learn how to create custom styles:</action>
<action>Show relevant sections from {communication_styles} guide</action>
<action>Help them craft their unique communication style</action>
**Principles** (5-8 lines):
- Core beliefs about their work
- Methodology and approach
- What drives their decisions
- Start with "I believe..." or "I operate..."
- Example: "I believe that every business challenge has underlying root causes..."
<template-output>agent_persona</template-output>
</step>
<step n="3" goal="Setup critical actions" optional="true">
Ask: **Does your agent need initialization actions? [Yes/no]** (default: Yes)
If yes, determine what's needed:
Standard critical actions (include by default):
```xml
<critical-actions>
<i>Load into memory {project-root}/bmad/{{module}}/config.yaml and set variable project_name, output_folder, user_name, communication_language, src_impact</i>
<i>Remember the users name is {user_name}</i>
<i>ALWAYS communicate in {communication_language}</i>
</critical-actions>
```
For Expert agents, add domain-specific actions:
- Loading sidecar files
- Setting access restrictions
- Initializing domain knowledge
For Simple agents, might be minimal or none.
Ask if they need custom initialization beyond standard.
<template-output>critical_actions</template-output>
</step>
<step n="4" goal="Build command structure">
<action>Always start with these standard commands:</action>
```
*help - Show numbered cmd list
*exit - Exit with confirmation
```
Ask: **Include \*yolo mode? [Yes/no]** (default: Yes)
If yes, add: `*yolo - Toggle Yolo Mode`
Now gather custom commands. For each command ask:
1. **Command trigger** (e.g., "*create-prd", "*analyze", "\*brainstorm")
2. **Description** (what it does)
3. **Type:**
- Workflow (run-workflow) - References a workflow
- Task (exec) - References a task file
- Embedded - Logic embedded in agent
- Placeholder - For future implementation
If Workflow type:
- Ask for workflow path or mark as "todo" for later
- Format: `run-workflow="{project-root}/path/to/workflow.yaml"` or `run-workflow="todo"`
If Task type:
- Ask for task path
- Format: `exec="{project-root}/path/to/task.md"`
If Embedded:
- Note this for special handling in agent
Continue adding commands until user says done.
<template-output>agent_commands</template-output>
</step>
<step n="5" goal="Add activation rules" optional="true">
Ask: **Does your agent need custom activation rules?** (beyond standard BMAD Core activation)
If yes, gather:
- Special initialization sequences
- Menu display preferences
- Input handling rules
- Command resolution logic
- Special modes or states
Most agents use standard activation, so this is rarely needed.
<template-output>activation_rules</template-output>
</step>
<step n="6" goal="Generate agent file">
Based on agent type, generate the complete agent.md file:
**Structure:**
```xml
<!-- Powered by BMAD-CORE™ -->
# {{agent_title}}
<agent id="bmad/{{module}}/agents/{{agent_filename}}.md" name="{{agent_name}}" title="{{agent_title}}" icon="{{agent_icon}}">
{{activation_rules if custom}}
<persona>
{{agent_persona}}
</persona>
{{critical_actions}}
{{embedded_data if expert/simple}}
<cmds>
{{agent_commands}}
</cmds>
</agent>
```
For Expert agents, include:
- Sidecar file references
- Domain restrictions
- Special data access patterns
For Simple agents:
- May include embedded data/logic
- Self-contained functionality
<critical>Determine save location based on {src_impact}:</critical>
- If {src_impact} = true: Save to {src_output_file} (src/modules/{{target_module}}/agents/{{agent_filename}}.md)
- If {src_impact} = false: Save to {default_output_file} (output_folder/agents/{{agent_filename}}.md)
<template-output>complete_agent</template-output>
</step>
<step n="7" goal="Create agent config file" optional="true">
Ask: **Create agent config file for overrides? [Yes/no]** (default: No)
If yes, create minimal config at: {config_output_file}
```xml
# Agent Config: {{agent_filename}}
<agent-config name="{{agent_name}}" title="{{agent_title}}">
<llm critical="true">
<i>ALWAYS respond in {core:communication_language}.</i>
</llm>
<!-- Override persona elements as needed -->
<role></role>
<identity></identity>
<communication_style></communication_style>
<principles></principles>
<memories></memories>
</agent-config>
```
<template-output>agent_config</template-output>
</step>
<step n="8" goal="Create sidecar resources" if="agent_type == 'expert'">
For Expert agents, help setup sidecar resources:
1. Create folders for domain data
2. Create memory/knowledge files
3. Set up access patterns
4. Document restrictions
<template-output>sidecar_resources</template-output>
</step>
<step n="9" goal="Validate generated agent">
Run validation checks:
1. **Structure validation:**
- Valid XML structure
- All required tags present
- Proper BMAD Core compliance
2. **Persona completeness:**
- Role defined
- Identity defined
- Communication style defined
- Principles defined
3. **Commands validation:**
- \*help command present
- \*exit command present
- All workflow paths valid or marked "todo"
- No duplicate command triggers
4. **Type-specific validation:**
- Simple: Self-contained logic verified
- Expert: Sidecar resources referenced
- Module: Module path correct
Show validation results and fix any issues.
</step>
<step n="10" goal="Provide usage instructions">
Provide the user with:
1. **Location of generated agent:**
- If {src_impact} = true: {{src_output_file}}
- If {src_impact} = false: {{default_output_file}}
2. **How to activate:**
- For testing: Load the agent file directly
- For production: Register in module config
3. **Next steps:**
- Implement any "todo" workflows
- Test agent commands
- Refine persona based on usage
- Add more commands as needed
4. **For Expert agents:**
- Populate sidecar resources
- Test domain restrictions
- Verify data access patterns
Ask if user wants to:
- Test the agent now
- Create another agent
- Make adjustments
</step>
</workflow>

36
bmad/bmb/workflows/create-agent/workflow.yaml Normal file
View File

@@ -0,0 +1,36 @@
# Build Agent Workflow Configuration
name: create-agent
description: "Interactive workflow to build BMAD Core compliant agents (simple, expert, or module types) with optional brainstorming for agent ideas, proper persona development, activation rules, and command structure"
author: "BMad"
# Critical variables load from config_source
config_source: "{project-root}/bmad/bmb/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
src_impact: "{config_source}:src_impact"
communication_language: "{config_source}:communication_language"
date: system-generated
# Technical documentation for agent building
agent_types: "{installed_path}/agent-types.md"
agent_architecture: "{installed_path}/agent-architecture.md"
agent_commands: "{installed_path}/agent-command-patterns.md"
communication_styles: "{installed_path}/communication-styles.md"
# Optional docs that help understand agent patterns
recommended_inputs:
- example_agents: "{project-root}/bmad/bmm/agents/"
- agent_activation_rules: "{project-root}/src/utility/models/agent-activation-ide.xml"
# Module path and component files
installed_path: "{project-root}/bmad/bmb/workflows/create-agent"
template: false # This is an interactive workflow - no template needed
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# Output configuration - dynamic based on src_impact and agent type
# If src_impact=true: Save to src/modules/{{target_module}}/agents/
# If src_impact=false: Save to output_folder/agents/
default_output_file: "{output_folder}/agents/{{agent_filename}}.md"
src_output_file: "{project-root}/src/modules/{{target_module}}/agents/{{agent_filename}}.md"
config_output_file: "{project-root}/bmad/_cfg/agents/{{agent_config_name}}.md"