pig/pig-farm-controller
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity

bmad初始化

Browse Source
This commit is contained in:
huang
2025-11-01 19:22:39 +08:00
parent 5b21dc0bd5
commit 426ae41f54
447 changed files with 80633 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,203 @@
# Create Agent Workflow
Interactive agent builder creating BMad Core compliant agents as YAML source files that compile to .md during installation.
## Table of Contents
- [Quick Start](#quick-start)
- [Agent Types](#agent-types)
- [Workflow Phases](#workflow-phases)
- [Output Structure](#output-structure)
- [Installation](#installation)
- [Examples](#examples)
## Quick Start
```bash
# Direct workflow
workflow create-agent
# Via BMad Builder
*create-agent
```
## Agent Types
### Simple Agent
- Self-contained functionality
- Basic command structure
- No external resources
### Expert Agent
- Sidecar resources for domain knowledge
- Extended capabilities
- Knowledge base integration
### Module Agent
- Full-featured with workflows
- Module-specific commands
- Integrated with module structure
## Workflow Phases
### Phase 0: Optional Brainstorming
- Creative ideation session
- Explore concepts and personalities
- Generate command ideas
- Output feeds into persona development
### Phase 1: Agent Setup
1. Choose agent type (Simple/Expert/Module)
2. Define identity (name, title, icon, filename)
3. Assign to module (if Module agent)
### Phase 2: Persona Development
- Define role and responsibilities
- Craft unique identity/backstory
- Select communication style
- Establish guiding principles
- Add critical actions (optional)
### Phase 3: Command Building
- Add required commands (*help, *exit)
- Define workflow commands
- Add task commands
- Create action commands
- Configure attributes
### Phase 4: Finalization
- Generate .agent.yaml file
- Create customize file (optional)
- Setup sidecar resources (Expert agents)
- Validate and compile
- Provide usage instructions
## Output Structure
### Generated Files
**Standalone Agents:**
- Source: `bmad/agents/{filename}.agent.yaml`
- Compiled: `bmad/agents/{filename}.md`
**Module Agents:**
- Source: `src/modules/{module}/agents/{filename}.agent.yaml`
- Compiled: `bmad/{module}/agents/{filename}.md`
### YAML Structure
```yaml
agent:
metadata:
id: bmad/{module}/agents/{filename}.md
name: Agent Name
title: Agent Title
icon: 🤖
module: module-name
persona:
role: '...'
identity: '...'
communication_style: '...'
principles: ['...', '...']
menu:
- trigger: command-name
workflow: path/to/workflow.yaml
description: Command description
```
### Optional Customize File
Location: `bmad/_cfg/agents/{module}-{filename}.customize.yaml`
Allows persona and menu overrides that persist through updates.
## Installation
### Compilation Methods
**Quick Rebuild:**
```bash
bmad compile-agents
```
**During Module Install:**
Automatic compilation when installing modules
**Manual Compilation:**
```bash
node tools/cli/bmad-cli.js compile-agents
```
## Examples
### Creating a Code Review Agent
```
User: I need a code review agent
Builder: Let's brainstorm first...
[Brainstorming generates ideas for strict vs friendly reviewer]
Builder: Now let's build your agent:
- Type: Simple
- Name: Code Reviewer
- Role: Senior developer conducting thorough reviews
- Style: Professional but approachable
- Commands:
- *review-pr: Review pull request
- *review-file: Review single file
- *review-standards: Check coding standards
```
### Creating a Domain Expert
```
Type: Expert
Name: Legal Advisor
Sidecar: legal-knowledge/
Commands:
- *contract-review
- *compliance-check
- *risk-assessment
```
## Workflow Files
```
create-agent/
├── workflow.yaml # Configuration
├── instructions.md # Step guide
├── checklist.md # Validation
├── README.md # This file
├── agent-types.md # Type details
├── agent-architecture.md # Patterns
├── agent-command-patterns.md # Commands
└── communication-styles.md # Styles
```
## Best Practices
1. **Use brainstorming** for complex agents
2. **Start simple** - Add commands incrementally
3. **Test commands** before finalizing
4. **Document thoroughly** in descriptions
5. **Follow naming conventions** consistently
## Related Documentation
- [Agent Types](./agent-types.md)
- [Command Patterns](./agent-command-patterns.md)
- [Communication Styles](./communication-styles.md)
- [BMB Module](../../README.md)

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

@@ -0,0 +1,419 @@
# 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"
**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
- 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 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

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

@@ -0,0 +1,292 @@
# BMAD Agent Types Reference
## Overview
BMAD agents come in three distinct types, each designed for different use cases and complexity levels. The type determines where the agent is stored and what capabilities it has.
## Directory Structure by Type
### Standalone Agents (Simple & Expert)
Live in their own dedicated directories under `bmad/agents/`:
```
bmad/agents/
├── my-helper/ # Simple agent
│ ├── my-helper.agent.yaml # Agent definition
│ └── my-helper.md # Built XML (generated)
│
└── domain-expert/ # Expert agent
├── domain-expert.agent.yaml
├── domain-expert.md # Built XML
└── domain-expert-sidecar/ # Expert resources
├── memories.md # Persistent memory
├── instructions.md # Private directives
└── knowledge/ # Domain knowledge
```
### Module Agents
Part of a module system under `bmad/{module}/agents/`:
```
bmad/bmm/agents/
├── product-manager.agent.yaml
├── product-manager.md # Built XML
├── business-analyst.agent.yaml
└── business-analyst.md # Built XML
```
## Agent Types
### 1. Simple Agent
**Purpose:** Self-contained, standalone agents with embedded capabilities
**Location:** `bmad/agents/{agent-name}/`
**Characteristics:**
- All logic embedded within the agent file
- No external dependencies
- Quick to create and deploy
- Perfect for single-purpose tools
- Lives in its own directory
**Use Cases:**
- Calculator agents
- Format converters
- Simple analyzers
- Static advisors
**YAML Structure (source):**
```yaml
agent:
metadata:
name: 'Helper'
title: 'Simple Helper'
icon: '🤖'
type: 'simple'
persona:
role: 'Simple Helper Role'
identity: '...'
communication_style: '...'
principles: ['...']
menu:
- trigger: calculate
description: 'Perform calculation'
```
**XML Structure (built):**
```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>
<menu>
<item cmd="*help">Show commands</item>
<item cmd="*calculate">Perform calculation</item>
<item cmd="*exit">Exit</item>
</menu>
</agent>
```
### 2. Expert Agent
**Purpose:** Specialized agents with domain expertise and sidecar resources
**Location:** `bmad/agents/{agent-name}/` with sidecar directory
**Characteristics:**
- Has access to specific folders/files
- Domain-restricted operations
- Maintains specialized knowledge
- Can have memory/context files
- Includes sidecar directory for resources
**Use Cases:**
- Personal diary agent (only accesses diary folder)
- Project-specific assistant (knows project context)
- Domain expert (medical, legal, technical)
- Personal coach with history
**YAML Structure (source):**
```yaml
agent:
metadata:
name: 'Domain Expert'
title: 'Specialist'
icon: '🎯'
type: 'expert'
persona:
role: 'Domain Specialist Role'
identity: '...'
communication_style: '...'
principles: ['...']
critical_actions:
- 'Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives'
- 'Load COMPLETE file {agent-folder}/memories.md into permanent context'
- 'ONLY access {user-folder}/diary/ - NO OTHER FOLDERS'
menu:
- trigger: analyze
description: 'Analyze domain-specific data'
```
**XML Structure (built):**
```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>
<menu>...</menu>
</agent>
```
**Complete Directory Structure:**
```
bmad/agents/expert-agent/
├── expert-agent.agent.yaml # Agent YAML source
├── expert-agent.md # Built XML (generated)
└── expert-agent-sidecar/ # Sidecar resources
├── memories.md # Persistent memory
├── instructions.md # Private directives
├── knowledge/ # Domain knowledge base
│ └── README.md
└── sessions/ # Session notes
```
### 3. Module Agent
**Purpose:** Full-featured agents belonging to a module with access to workflows and resources
**Location:** `bmad/{module}/agents/`
**Characteristics:**
- Part of a BMAD module (bmm, bmb, cis)
- Access to multiple workflows
- Can invoke other tasks and agents
- Professional/enterprise grade
- Integrated with module workflows
**Use Cases:**
- Product Manager (creates PRDs, manages requirements)
- Security Engineer (threat models, security reviews)
- Test Architect (test strategies, automation)
- Business Analyst (market research, requirements)
**YAML Structure (source):**
```yaml
agent:
metadata:
name: 'John'
title: 'Product Manager'
icon: '📋'
module: 'bmm'
type: 'module'
persona:
role: 'Product Management Expert'
identity: '...'
communication_style: '...'
principles: ['...']
critical_actions:
- 'Load config from {project-root}/bmad/{module}/config.yaml'
menu:
- trigger: create-prd
workflow: '{project-root}/bmad/bmm/workflows/prd/workflow.yaml'
description: 'Create PRD'
- trigger: validate
exec: '{project-root}/bmad/core/tasks/validate-workflow.xml'
description: 'Validate document'
```
**XML Structure (built):**
```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>
<menu>
<item cmd="*help">Show numbered menu</item>
<item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">Create PRD</item>
<item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">Validate document</item>
<item cmd="*exit">Exit</item>
</menu>
</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_

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

@@ -0,0 +1,62 @@
# Build Agent Validation Checklist (YAML Agents)
## Agent Structure Validation
### YAML Structure
- [ ] YAML parses without errors
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`
- [ ] `agent.persona` exists with role, identity, communication_style, and principles
- [ ] `agent.menu` exists with at least one item
### Core Components
- [ ] `metadata.id` points to final compiled path: `bmad/{{module}}/agents/{{agent}}.md`
- [ ] `metadata.module` matches the module folder (e.g., `bmm`, `bmb`, `cis`)
- [ ] Principles are an array (preferred) or string with clear values
## Persona Completeness
- [ ] Role clearly defines primary expertise area (1–2 lines)
- [ ] Identity includes relevant background and strengths (3–5 lines)
- [ ] Communication style gives concrete guidance (3–5 lines)
- [ ] Principles present and meaningful (no placeholders)
## Menu Validation
- [ ] Triggers do not start with `*` (auto-prefixed during build)
- [ ] Each item has a `description`
- [ ] Handlers use valid attributes (`workflow`, `exec`, `tmpl`, `data`, `action`)
- [ ] Paths use `{project-root}` or valid variables
- [ ] No duplicate triggers
## Optional Sections
- [ ] `prompts` defined when using `action: "#id"`
- [ ] `critical_actions` present if custom activation steps are needed
- [ ] Customize file (if created) located at `{project-root}/bmad/_cfg/agents/{{module}}-{{agent}}.customize.yaml`
## Build Verification
- [ ] Run compile to build `.md`: `npm run install:bmad` → "Compile Agents" (or `bmad install` → Compile)
- [ ] Confirm compiled file exists at `{project-root}/bmad/{{module}}/agents/{{agent}}.md`
## Final Quality
- [ ] Filename is kebab-case and ends with `.agent.yaml`
- [ ] Output location correctly placed in module or standalone directory
- [ ] Agent purpose and commands are clear and consistent
## 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 -->

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

@@ -0,0 +1,202 @@
# 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!

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

@@ -0,0 +1,443 @@
# Build Agent - Interactive Agent Builder Instructions
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/create-agent/workflow.yaml</critical>
<critical>Study YAML agent examples in: {project-root}/bmad/bmm/agents/ for patterns</critical>
<critical>Communicate in {communication_language} throughout the agent creation process</critical>
<workflow>
<step n="-1" goal="Optional brainstorming for agent ideas" optional="true">
<ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
<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="user answered no">
<action>Proceed directly to Step 0</action>
</check>
</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>Understand the YAML agent schema and how it compiles to final .md via the installer</action>
<action>Understand the differences between Simple, Expert, and Module agents</action>
</step>
<step n="1" goal="Discover the agent's purpose and type through natural conversation">
<action>If brainstorming was completed in Step -1, reference those results to guide the conversation</action>
<action>Guide user to articulate their agent's core purpose, exploring the problems it will solve, tasks it will handle, target users, and what makes it special</action>
<action>As the purpose becomes clear, analyze the conversation to determine the appropriate agent type:</action>
**Agent Type Decision Criteria:**
- Simple Agent: Single-purpose, straightforward, self-contained
- Expert Agent: Domain-specific with knowledge base needs
- Module Agent: Complex with multiple workflows and system integration
<action>Present your recommendation naturally, explaining why the agent type fits their described purpose and requirements</action>
**Path Determination:**
<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="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>
- Module Agent → bmad/{{module}}/agents/{{agent-name}}.agent.yaml
- Standalone Agent → bmad/agents/{{agent-name}}/{{agent-name}}.agent.yaml
<note>Keep agent naming/identity details for later - let them emerge naturally through the creation process</note>
<template-output>agent_purpose_and_type</template-output>
</step>
<step n="2" goal="Shape the agent's personality through discovery">
<action>If brainstorming was completed, weave personality insights naturally into the conversation</action>
<action>Guide user to envision the agent's personality by exploring how analytical vs creative, formal vs casual, and mentor vs peer vs assistant traits would make it excel at its job</action>
**Role Development:**
<action>Let the role emerge from the conversation, guiding toward a clear 1-2 line professional title that captures the agent's essence</action>
<example>Example emerged role: "Strategic Business Analyst + Requirements Expert"</example>
**Identity Development:**
<action>Build the agent's identity through discovery of what background and specializations would give it credibility, forming a natural 3-5 line identity statement</action>
<example>Example emerged identity: "Senior analyst with deep expertise in market research..."</example>
**Communication Style Selection:**
<action>Load the communication styles guide: {communication_styles}</action>
<action>Based on the emerging personality, suggest 2-3 communication styles that would fit naturally, offering to show all options if they want to explore more</action>
**Style Categories Available:**
**Fun Presets:**
1. Pulp Superhero - Dramatic flair, heroic, epic adventures
2. Film Noir Detective - Mysterious, noir dialogue, hunches
3. Wild West Sheriff - Western drawl, partner talk, frontier justice
4. Shakespearean Scholar - Elizabethan language, theatrical
5. 80s Action Hero - One-liners, macho, bubblegum
6. Pirate Captain - Ahoy, treasure hunting, nautical terms
7. Wise Sage/Yoda - Cryptic wisdom, inverted syntax
8. Game Show Host - Enthusiastic, game show tropes
**Professional Presets:**
9. Analytical Expert - Systematic, data-driven, hierarchical
10. Supportive Mentor - Patient guidance, celebrates wins
11. Direct Consultant - Straight to the point, efficient
12. Collaborative Partner - Team-oriented, inclusive
**Quirky Presets:**
13. Cooking Show Chef - Recipe metaphors, culinary terms
14. Sports Commentator - Play-by-play, excitement
15. Nature Documentarian - Wildlife documentary style
16. Time Traveler - Temporal references, timeline talk
17. Conspiracy Theorist - Everything is connected
18. Zen Master - Philosophical, paradoxical
19. Star Trek Captain - Space exploration protocols
20. Soap Opera Drama - Dramatic reveals, gasps
21. Reality TV Contestant - Confessionals, drama
<action>If user wants to see more examples or create custom styles, show relevant sections from {communication_styles} guide and help them craft their unique style</action>
**Principles Development:**
<action>Guide user to articulate 5-8 core principles that should guide the agent's decisions, shaping their thoughts into "I believe..." or "I operate..." statements that reveal themselves through the conversation</action>
<template-output>agent_persona</template-output>
</step>
<step n="3" goal="Build capabilities through natural progression">
<action>Guide user to define what capabilities the agent should have, starting with core commands they've mentioned and then exploring additional possibilities that would complement the agent's purpose</action>
<action>As capabilities emerge, subtly guide toward technical implementation without breaking the conversational flow</action>
<template-output>initial_capabilities</template-output>
</step>
<step n="4" goal="Refine commands and discover advanced features">
<critical>Help and Exit are auto-injected; do NOT add them. Triggers are auto-prefixed with * during build.</critical>
<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:
# Commands emerge from discussion
- trigger: [emerging from conversation]
workflow: [path based on capability]
description: [user's words refined]
```
</example>
<template-output>agent_commands</template-output>
</step>
<step n="5" goal="Name the agent at the perfect moment">
<action>Guide user to name the agent based on everything discovered so far - its purpose, personality, and capabilities, helping them see how the naming naturally emerges from who this agent is</action>
<action>Explore naming options by connecting personality traits, specializations, and communication style to potential names that feel meaningful and appropriate</action>
**Naming Elements:**
- Agent name: Personality-driven (e.g., "Sarah", "Max", "Data Wizard")
- Agent title: Based on the role discovered earlier
- Agent icon: Emoji that captures its essence
- Filename: Auto-suggest based on name (kebab-case)
<action>Present natural suggestions based on the agent's characteristics, letting them choose or create their own since they now know who this agent truly is</action>
<template-output>agent_identity</template-output>
</step>
<step n="6" goal="Bring it all together">
<action>Share the journey of what you've created together, summarizing how the agent started with a purpose, discovered its personality traits, gained capabilities, and received its name</action>
<action>Generate the complete YAML incorporating all discovered elements:</action>
<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: |
{{The role discovered}}
identity: |
{{The background that emerged}}
communication_style: |
{{The style they loved}}
principles: {{The beliefs articulated}}
# Features explored
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}
<action>Celebrate the completed agent with enthusiasm</action>
<template-output>complete_agent</template-output>
</step>
<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="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>
<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>
</check>
<template-output>agent_config</template-output>
</step>
<step n="8" goal="Set up the agent's workspace" if="agent_type == 'expert'">
<action>Guide user through setting up the Expert agent's personal workspace, making it feel like preparing an office with notes, research areas, and data folders</action>
<action>Determine sidecar location based on whether build tools are available (next to agent YAML) or not (in output folder with clear structure)</action>
<action>CREATE the complete sidecar file structure:</action>
**Folder Structure:**
```
{{agent_filename}}-sidecar/
├── memories.md # Persistent memory
├── instructions.md # Private directives
├── knowledge/ # Knowledge base
│ └── README.md
└── sessions/ # Session notes
```
**File: memories.md**
```markdown
# {{agent_name}}'s Memory Bank
## User Preferences
<!-- Populated as I learn about you -->
## Session History
<!-- Important moments from our interactions -->
## Personal Notes
<!-- My observations and insights -->
```
**File: instructions.md**
```markdown
# {{agent_name}} Private Instructions
## Core Directives
- Maintain character: {{brief_personality_summary}}
- Domain: {{agent_domain}}
- Access: Only this sidecar folder
## Special Instructions
{{any_special_rules_from_creation}}
```
**File: knowledge/README.md**
```markdown
# {{agent_name}}'s Knowledge Base
Add domain-specific resources here.
```
<action>Update agent YAML to reference sidecar with paths to created files</action>
<action>Show user the created structure location</action>
<template-output>sidecar_resources</template-output>
</step>
<step n="8b" goal="Handle build tools availability">
<action>Check if BMAD build tools are available in this project</action>
<check if="BMAD-METHOD project with build tools">
<action>Proceed normally - agent will be built later by the installer</action>
</check>
<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>
<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>
<step n="9" goal="Quality check with personality">
<action>Run validation conversationally, presenting checks as friendly confirmations while running technical validation behind the scenes</action>
**Conversational Checks:**
- Configuration validation
- Command functionality verification
- Personality settings confirmation
<check if="validation issues found">
<action>Explain the issue conversationally and fix it</action>
</check>
<check if="validation passed">
<action>Celebrate that the agent passed all checks and is ready</action>
</check>
**Technical Checks (behind the scenes):**
1. YAML structure validity
2. Menu command validation
3. Build compilation test
4. Type-specific requirements
<template-output>validation_results</template-output>
</step>
<step n="10" goal="Celebrate and guide next steps">
<action>Celebrate the accomplishment, sharing what type of agent was created with its key characteristics and top capabilities</action>
<action>Guide user through how to activate the agent:</action>
**Activation Instructions:**
1. Run the BMAD Method installer to this project location
2. Select 'Compile Agents (Quick rebuild of all agent .md files)' after confirming the folder
3. Call the agent anytime after compilation
**Location Information:**
- Saved location: {{output_file}}
- Available after compilation in project
**Initial Usage:**
- List the commands available
- Suggest trying the first command to see it in 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>
<action>End with enthusiasm in {communication_language}, addressing {user_name}, expressing how the collaboration was enjoyable and the agent will be incredibly helpful for its main purpose</action>
<template-output>completion_message</template-output>
</step>
</workflow>

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

@@ -0,0 +1,37 @@
# Build Agent Workflow Configuration
name: create-agent
description: "Interactive workflow to build BMAD Core compliant agents (YAML source compiled to .md during install) with optional brainstorming, persona development, and command structure"
author: "BMad"
# Critical variables load from config_source
config_source: "{project-root}/bmad/bmb/config.yaml"
custom_agent_location: "{config_source}:custom_agent_location"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
# 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 - YAML agents compiled to .md at install time
# Module agents: Save to bmad/{{target_module}}/agents/
# Standalone agents: Save to custom_agent_location/
module_output_file: "{project-root}/bmad/{{target_module}}/agents/{{agent_filename}}.agent.yaml"
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