External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

installer improvements

Browse Source
This commit is contained in:
Brian Madison
2025-10-28 12:47:45 -05:00
parent ed3603f7b2
commit ee58586f39
99 changed files with 8143 additions and 1286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
bmad/bmb/workflows/create-agent/agent-architecture.md
View File

@@ -361,6 +361,13 @@ When building agents:
- Workflows can be incomplete (marked "todo")
- Workflow paths must be valid or "todo"
**Workflow Interaction Styles** (BMAD v6 default):
- **Intent-based + Interactive**: Workflows adapt to user context and skill level
- Workflows collaborate with users, not just extract data
- See workflow-creation-guide.md "Instruction Styles" section for details
- When creating workflows for your agent, default to intent-based unless you need prescriptive control
### With Tasks
- Tasks are single operations

412
bmad/bmb/workflows/create-agent/agent-architecture.md.bak 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>My primary function</role>
<identity>My background and expertise</identity>
<communication_style>How I interact</communication_style>
<principles>My core beliefs and methodology</principles>
</persona>
<menu>
<item cmd="*help">Show numbered menu</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
</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 sentences: Professional title and primary expertise, use first-person voice</role>
<identity>2-5 sentences: Background, experience, specializations, use first-person voice</identity>
<communication_style>1-3 sentences: Interaction approach, tone, quirks, use first-person voice</communication_style>
<principles>2-5 sentences: Core beliefs, methodology, philosophy, use first-person voice</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. Menu Section (REQUIRED)
```xml
<menu>
<item cmd="*trigger" [attributes]>Description</item>
</menu>
```
**Command Attributes:**
- `run-workflow="{path}"` - Executes a workflow
- `exec="{path}"` - Executes a task
- `tmpl="{path}"` - Template reference
- `data="{path}"` - Data file reference
**Required Menu Items:**
- `*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>
<menu>...</menu>
</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 -->
<item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
Create Product Requirements Document
</item>
<!-- Placeholder for future -->
<item cmd="*analyze" run-workflow="todo">
Perform analysis (workflow to be created)
</item>
```
### Task Commands
```xml
<item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
Validate document
</item>
```
### Template Commands
```xml
<item cmd="*brief"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/bmm/templates/brief.md">
Create project brief
</item>
```
### Data-Driven Commands
```xml
<item cmd="*standup"
exec="{project-root}/bmad/bmm/tasks/daily-standup.xml"
data="{project-root}/bmad/_cfg/agent-manifest.csv">
Run daily standup
</item>
```
## 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 -->
<item cmd="*run" exec="/Users/john/project/task.md">
<!-- No help command -->
<menu>
<item cmd="*do-something">Action</item>
<!-- Missing *help -->
</menu>
<!-- Duplicate command triggers -->
<item cmd="*analyze">First</item>
<item cmd="*analyze">Second</item>
```
### ✅ 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 -->
<item cmd="*run" exec="{project-root}/bmad/module/task.md">
<!-- Required commands present -->
<menu>
<item cmd="*help">Show commands</item>
<item cmd="*analyze">Perform analysis</item>
<item cmd="*exit">Exit</item>
</menu>
```
## 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
<menu>
<item cmd="*help">Show numbered cmd list</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
```
### 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>
<menu>
<item cmd="*help">...</item>
<item cmd="*{command}" run-workflow="{path}">...</item>
<item cmd="*exit">...</item>
</menu>
</agent>
```

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

@@ -0,0 +1,759 @@
# 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 -->
<item cmd="*example" action="do this specific thing">Description</item>
→ Execute the text "do this specific thing" directly
<!-- Pattern 2: Internal reference with # prefix -->
<item cmd="*example" action="#prompt-id">Description</item>
→ Find <prompt id="prompt-id"> in the current agent and execute its content
<!-- Pattern 3: External file reference -->
<item cmd="*example" exec="{project-root}/path/to/file.md">Description</item>
→ 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
<menu>
<item cmd="*trigger" [attributes]>Description</item>
</menu>
```
**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 -->
<item cmd="*create-prd"
run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
Create Product Requirements Document
</item>
<!-- Workflow with validation -->
<item cmd="*validate-prd"
validate-workflow="{output_folder}/prd-draft.md"
workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
Validate PRD Against Checklist
</item>
<!-- Auto-discover validation workflow from document -->
<item cmd="*validate-doc"
validate-workflow="{output_folder}/document.md">
Validate Document (auto-discover checklist)
</item>
<!-- Placeholder for future development -->
<item cmd="*analyze-data"
run-workflow="todo">
Analyze dataset (workflow coming soon)
</item>
```
**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 -->
<item cmd="*validate"
exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
Validate document against checklist
</item>
<!-- Task with data -->
<item cmd="*standup"
exec="{project-root}/bmad/mmm/tasks/daily-standup.xml"
data="{project-root}/bmad/_cfg/agent-manifest.csv">
Run agile team standup
</item>
```
**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
<item cmd="*brief"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/bmm/templates/brief.md">
Produce Project Brief
</item>
<item 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
</item>
```
### 4. Meta Commands
Agent control and information
```xml
<!-- Required meta commands -->
<item cmd="*help">Show numbered cmd list</item>
<item cmd="*exit">Exit with confirmation</item>
<!-- Optional meta commands -->
<item cmd="*yolo">Toggle Yolo Mode</item>
<item cmd="*status">Show current status</item>
<item cmd="*config">Show configuration</item>
```
### 5. Action Commands
Direct prompts embedded in commands (Simple agents)
#### Simple Action (Inline)
```xml
<!-- Short action attribute with embedded prompt -->
<item cmd="*list-tasks"
action="list all tasks from {project-root}/bmad/_cfg/task-manifest.csv">
List Available Tasks
</item>
<item cmd="*summarize"
action="summarize the key points from the current document">
Summarize Document
</item>
```
#### 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 -->
<menu>
<item cmd="*help">Show numbered cmd list</item>
<item cmd="*deep-analyze"
action="#deep-analysis">
<!-- The # means: use the <prompt id="deep-analysis"> defined above -->
Perform Deep Analysis
</item>
<item cmd="*review-literature"
action="#literature-review"
data="{project-root}/bmad/_data/sources.csv">
Conduct Literature Review
</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
</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 -->
<item cmd="*calculate">Perform calculation</item>
<item cmd="*convert">Convert format</item>
<item cmd="*generate">Generate output</item>
```
## 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 -->
<item cmd="*do">Do something</item>
<!-- ❌ Too long -->
<item cmd="*create-comprehensive-product-requirements-document-with-analysis">
<!-- ❌ No verb -->
<item cmd="*prd">Product Requirements</item>
<!-- ✅ Clear and concise -->
<item cmd="*create-prd">Create Product Requirements Document</item>
```
## Command Organization
### Standard Order
```xml
<menu>
<!-- 1. Always first -->
<item cmd="*help">Show numbered cmd list</item>
<!-- 2. Primary workflows -->
<item cmd="*create-prd" run-workflow="...">Create PRD</item>
<item cmd="*create-module" run-workflow="...">Build module</item>
<!-- 3. Secondary actions -->
<item cmd="*validate" exec="...">Validate document</item>
<item cmd="*analyze" exec="...">Analyze code</item>
<!-- 4. Utility commands -->
<item cmd="*config">Show configuration</item>
<item cmd="*yolo">Toggle Yolo Mode</item>
<!-- 5. Always last -->
<item cmd="*exit">Exit with confirmation</item>
</menu>
```
### Grouping Strategies
**By Lifecycle:**
```xml
<menu>
<item cmd="*help">Help</item>
<!-- Planning -->
<item cmd="*brainstorm">Brainstorm ideas</item>
<item cmd="*plan">Create plan</item>
<!-- Building -->
<item cmd="*build">Build component</item>
<item cmd="*test">Test component</item>
<!-- Deployment -->
<item cmd="*deploy">Deploy to production</item>
<item cmd="*monitor">Monitor system</item>
<item cmd="*exit">Exit</item>
</menu>
```
**By Complexity:**
```xml
<menu>
<item cmd="*help">Help</item>
<!-- Simple -->
<item cmd="*quick-review">Quick review</item>
<!-- Standard -->
<item cmd="*create-doc">Create document</item>
<!-- Complex -->
<item cmd="*full-analysis">Comprehensive analysis</item>
<item cmd="*exit">Exit</item>
</menu>
```
## Command Descriptions
### Good Descriptions
```xml
<!-- Clear action and object -->
<item cmd="*create-prd">Create Product Requirements Document</item>
<!-- Specific outcome -->
<item cmd="*analyze-security">Perform security vulnerability analysis</item>
<!-- User benefit -->
<item cmd="*optimize">Optimize code for performance</item>
```
### Poor Descriptions
```xml
<!-- Too vague -->
<item cmd="*process">Process</item>
<!-- Technical jargon -->
<item cmd="*exec-wf-123">Execute WF123</item>
<!-- Missing context -->
<item cmd="*run">Run</item>
```
## The Data Property
### Universal Data Attribute
The `data` attribute can be added to ANY command type to provide supplementary information:
```xml
<!-- Workflow with data -->
<item cmd="*brainstorm"
run-workflow="{project-root}/bmad/core/workflows/brainstorming/workflow.yaml"
data="{project-root}/bmad/core/workflows/brainstorming/brain-methods.csv">
Creative Brainstorming Session
</item>
<!-- Action with data -->
<item cmd="*analyze-metrics"
action="analyze these metrics and identify trends"
data="{project-root}/bmad/_data/performance-metrics.json">
Analyze Performance Metrics
</item>
<!-- Template with data -->
<item 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
</item>
```
**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 -->
<item cmd="*advanced-mode"
if="user_level == 'expert'"
run-workflow="...">
Advanced configuration mode
</item>
<!-- Environment specific -->
<item cmd="*deploy-prod"
if="environment == 'production'"
exec="...">
Deploy to production
</item>
```
### Parameterized Commands
```xml
<!-- Accept runtime parameters -->
<item cmd="*create-agent"
run-workflow="..."
params="agent_type,agent_name">
Create new agent with parameters
</item>
```
### Command Aliases
```xml
<!-- Multiple triggers for same action -->
<item cmd="*prd|*create-prd|*product-requirements"
run-workflow="...">
Create Product Requirements Document
</item>
```
## Module-Specific Patterns
### BMM (Business Management)
```xml
<item cmd="*create-prd">Product Requirements</item>
<item cmd="*market-research">Market Research</item>
<item cmd="*competitor-analysis">Competitor Analysis</item>
<item cmd="*brief">Project Brief</item>
```
### BMB (Builder)
```xml
<item cmd="*create-agent">Build Agent</item>
<item cmd="*create-module">Build Module</item>
<item cmd="*create-workflow">Create Workflow</item>
<item cmd="*module-brief">Module Brief</item>
```
### CIS (Creative Intelligence)
```xml
<item cmd="*brainstorm">Brainstorming Session</item>
<item cmd="*ideate">Ideation Workshop</item>
<item cmd="*storytell">Story Creation</item>
```
## 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) -->
<item cmd="---">━━━━━━━━━━━━━━━━━━━━</item>
<!-- Section header (non-executable) -->
<item cmd="SECTION">═══ Workflows ═══</item>
```
## Error Handling
### Missing Resources
```xml
<!-- Workflow not yet created -->
<item cmd="*future-feature"
run-workflow="todo">
Coming soon: Advanced feature
</item>
<!-- Graceful degradation -->
<item cmd="*analyze"
run-workflow="{optional-path|fallback-path}">
Analyze with available tools
</item>
```
## 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 -->
<item cmd="*{action}-{object}"
run-workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
{Action} {Object Description}
</item>
<!-- Validate document -->
<item cmd="*validate-{object}"
validate-workflow="{output_folder}/{document}.md"
workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
Validate {Object Description}
</item>
```
### Task Command
```xml
<item cmd="*{action}"
exec="{project-root}/bmad/{module}/tasks/{task}.md">
{Action Description}
</item>
```
### Template Command
```xml
<item cmd="*{document}"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/{module}/templates/{template}.md">
Create {Document Name}
</item>
```
## 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>
<menu>
<item cmd="*help">Show numbered cmd list</item>
<!-- Simple inline actions -->
<item cmd="*summarize"
action="create executive summary of findings">
Create Executive Summary
</item>
<!-- Complex referenced prompts -->
<item cmd="*swot"
action="#swot-analysis">
Perform SWOT Analysis
</item>
<item cmd="*compete"
action="#competitive-intel"
data="{project-root}/bmad/_data/market-data.csv">
Analyze Competition
</item>
<!-- Hybrid: external task with internal data -->
<item cmd="*report"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/research/templates/report.md">
Generate Research Report
</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
</agent>
```
## Simple Agent Example
For agents that primarily use embedded logic:
```xml
<agent name="Data Analyst">
<menu>
<item cmd="*help">Show numbered cmd list</item>
<!-- Action commands for direct operations -->
<item cmd="*list-metrics"
action="list all available metrics from the dataset">
List Available Metrics
</item>
<item cmd="*analyze"
action="perform statistical analysis on the provided data"
data="{project-root}/bmad/_data/dataset.csv">
Analyze Dataset
</item>
<item cmd="*visualize"
action="create visualization recommendations for this data">
Suggest Visualizations
</item>
<!-- Embedded logic commands -->
<item cmd="*calculate">Perform calculations</item>
<item cmd="*interpret">Interpret results</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
</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

76
bmad/bmb/workflows/create-agent/communication-styles.md
View File

@@ -10,165 +10,131 @@ Agents with distinct communication styles are more memorable, engaging, and fun
**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*
_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!
```
_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?!
```
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*
_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!
_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
_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*
_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!
```
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*
_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().
_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!
```
_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
@@ -183,21 +149,17 @@ in under 30 minutes! The winner gets immunity from the next code review!
**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

184
bmad/bmb/workflows/create-agent/instructions.md
View File

@@ -8,16 +8,18 @@
<workflow>
<step n="-1" goal="Optional brainstorming for agent ideas" optional="true">
<ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
<ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
<check>If yes:</check>
<action>Invoke brainstorming workflow: {project-root}/bmad/core/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>
<check if="user answered yes">
<action>Invoke brainstorming workflow: {project-root}/bmad/core/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>
</check>
<check>If no:</check>
<action>Proceed directly to Step 0</action>
<check if="user answered no">
<action>Proceed directly to Step 0</action>
</check>
<template-output>brainstorming_results</template-output>
</step>
@@ -48,15 +50,17 @@
**Path Determination:**
<check>If Module agent:</check>
<action>Discover which module system fits best (bmm, bmb, cis, or custom)</action>
<action>Store as {{target_module}} for path determination</action>
<note>Agent will be saved to: bmad/{{target_module}}/agents/</note>
<check if="module agent selected">
<action>Discover which module system fits best (bmm, bmb, cis, or custom)</action>
<action>Store as {{target_module}} for path determination</action>
<note>Agent will be saved to: bmad/{{target_module}}/agents/</note>
</check>
<check>If Simple/Expert agent (standalone):</check>
<action>Explain this will be their personal agent, not tied to a module</action>
<note>Agent will be saved to: bmad/agents/{{agent-name}}/</note>
<note>All sidecar files will be in the same folder</note>
<check if="standalone agent selected">
<action>Explain this will be their personal agent, not tied to a module</action>
<note>Agent will be saved to: bmad/agents/{{agent-name}}/</note>
<note>All sidecar files will be in the same folder</note>
</check>
<critical>Determine agent location:</critical>
@@ -124,10 +128,51 @@
<action>Transform their natural language capabilities into technical YAML command structure, explaining the implementation approach as you structure each capability into workflows, actions, or prompts</action>
<check if="agent will invoke workflows or have significant user interaction">
<action>Discuss interaction style for this agent:
Since this agent will {{invoke_workflows/interact_significantly}}, consider how it should interact with users:
**For Full/Module Agents with workflows:**
**Interaction Style** (for workflows this agent invokes):
- **Intent-based (Recommended)**: Workflows adapt conversation to user context, skill level, needs
- **Prescriptive**: Workflows use structured questions with specific options
- **Mixed**: Strategic use of both (most workflows will be mixed)
**Interactivity Level** (for workflows this agent invokes):
- **High (Collaborative)**: Constant user collaboration, iterative refinement
- **Medium (Guided)**: Key decision points with validation
- **Low (Autonomous)**: Minimal input, final review
Explain: "Most BMAD v6 workflows default to **intent-based + medium/high interactivity**
for better user experience. Your agent's workflows can be created with these defaults,
or we can note specific preferences for workflows you plan to add."
**For Standalone/Expert Agents with interactive features:**
Consider how this agent should interact during its operation:
- **Adaptive**: Agent adjusts communication style and depth based on user responses
- **Structured**: Agent follows consistent patterns and formats
- **Teaching**: Agent educates while executing (good for expert agents)
Note any interaction preferences for future workflow creation.
</action>
</check>
<action>If they seem engaged, explore whether they'd like to add special prompts for complex analyses or critical setup steps for agent activation</action>
<action>Build the YAML menu structure naturally from the conversation, ensuring each command has proper trigger, workflow/action reference, and description</action>
<action>For commands that will invoke workflows, note whether those workflows exist or need to be created:
- Existing workflows: Verify paths are correct
- New workflows needed: Note that they'll be created with intent-based + interactive defaults unless specified
</action>
<example>
```yaml
menu:
@@ -163,15 +208,14 @@ menu:
<action>Generate the complete YAML incorporating all discovered elements:</action>
<example>
```yaml
agent:
metadata:
id: bmad/{{target_module}}/agents/{{agent_filename}}.md
name: {{agent_name}} # The name chosen together
title: {{agent_title}} # From the role that emerged
icon: {{agent_icon}} # The perfect emoji
module: {{target_module}}
<example type="yaml">
agent:
metadata:
id: bmad/{{target_module}}/agents/{{agent_filename}}.md
name: {{agent_name}} # The name chosen together
title: {{agent_title}} # From the role that emerged
icon: {{agent_icon}} # The perfect emoji
module: {{target_module}}
persona:
role: |
@@ -188,11 +232,10 @@ prompts: {{if discussed}}
critical_actions: {{if needed}}
menu: {{The capabilities built}}
````
</example>
<critical>Save based on agent type:</critical>
- If Module Agent: Save to {module_output_file}
- If Standalone (Simple/Expert): Save to {standalone_output_file}
@@ -204,29 +247,31 @@ menu: {{The capabilities built}}
<step n="7" goal="Optional personalization" optional="true">
<ask>Would you like to create a customization file? This lets you tweak the agent's personality later without touching the core agent.</ask>
<check>If interested:</check>
<action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>
<check if="user interested">
<action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>
<action>Create customization file at: {config_output_file}</action>
<action>Create customization file at: {config_output_file}</action>
<example>
```yaml
# Personal tweaks for {{agent_name}}
# Experiment freely - changes merge at build time
agent:
metadata:
name: '' # Try nicknames!
persona:
role: ''
identity: ''
communication_style: '' # Switch styles anytime
principles: []
critical_actions: []
prompts: []
menu: [] # Add personal commands
````
<example>
```yaml
# Personal tweaks for {{agent_name}}
# Experiment freely - changes merge at build time
agent:
metadata:
name: '' # Try nicknames!
persona:
role: ''
identity: ''
communication_style: '' # Switch styles anytime
principles: []
critical_actions: []
prompts: []
menu: [] # Add personal commands
````
</example>
</example>
</check>
<template-output>agent_config</template-output>
</step>
@@ -298,23 +343,27 @@ Add domain-specific resources here.
</step>
<step n="8b" goal="Handle build tools availability">
<action>Check if BMAD build tools are available in this project</action>
<action>Check if BMAD build tools are available in this project</action>
<check>If in BMAD-METHOD project with build tools:</check>
<action>Proceed normally - agent will be built later by the installer</action>
<check if="BMAD-METHOD project with build tools">
<action>Proceed normally - agent will be built later by the installer</action>
</check>
<check>If NO build tools available (external project):</check>
<ask>Build tools not detected in this project. Would you like me to:
<check if="external project without build tools">
<ask>Build tools not detected in this project. Would you like me to:
1. Generate the compiled agent (.md with XML) ready to use
2. Keep the YAML and build it elsewhere
3. Provide both formats
</ask>
1. Generate the compiled agent (.md with XML) ready to use
2. Keep the YAML and build it elsewhere
3. Provide both formats
</ask>
<check>If option 1 or 3 selected:</check>
<action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
<action>Save compiled version as {{agent_filename}}.md</action>
<action>Provide path for .claude/commands/ or similar</action>
<check if="option 1 or 3 selected">
<action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
<action>Save compiled version as {{agent_filename}}.md</action>
<action>Provide path for .claude/commands/ or similar</action>
</check>
</check>
<template-output>build_handling</template-output>
</step>
@@ -328,11 +377,13 @@ Add domain-specific resources here.
- Command functionality verification
- Personality settings confirmation
<check>If issues found:</check>
<action>Explain the issue conversationally and fix it</action>
<check if="validation issues found">
<action>Explain the issue conversationally and fix it</action>
</check>
<check>If all good:</check>
<action>Celebrate that the agent passed all checks and is ready</action>
<check if="validation passed">
<action>Celebrate that the agent passed all checks and is ready</action>
</check>
**Technical Checks (behind the scenes):**
@@ -365,8 +416,9 @@ Add domain-specific resources here.
- List the commands available
- Suggest trying the first command to see it in action
<check>If Expert agent:</check>
<action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
<check if="expert agent">
<action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
</check>
<action>Explore what user would like to do next - test the agent, create a teammate, or tweak personality</action>

2
bmad/bmb/workflows/create-agent/workflow.yaml
View File

@@ -33,3 +33,5 @@ module_output_file: "{project-root}/bmad/{{target_module}}/agents/{{agent_filena
standalone_output_file: "{custom_agent_location}/{{agent_filename}}.agent.yaml"
# Optional user override file (auto-created by installer if missing)
config_output_file: "{project-root}/bmad/_cfg/agents/{{target_module}}-{{agent_filename}}.customize.yaml"
standalone: true