mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
research will use the web more, use system date to understand what the read current date is.
This commit is contained in:
Brian Madison
@@ -1,320 +1,203 @@
|
||||
# Build Agent
|
||||
# Create Agent Workflow
|
||||
|
||||
## Overview
|
||||
Interactive agent builder creating BMad Core compliant agents as YAML source files that compile to .md during installation.
|
||||
|
||||
The Build Agent workflow is an interactive agent builder that guides you through creating BMAD Core compliant agents as YAML source files that compile to final `.md` during install. It supports three agent types: Simple (self-contained), Expert (with sidecar resources), and Module (full-featured with workflows).
|
||||
## Table of Contents
|
||||
|
||||
## Key Features
|
||||
- [Quick Start](#quick-start)
|
||||
- [Agent Types](#agent-types)
|
||||
- [Workflow Phases](#workflow-phases)
|
||||
- [Output Structure](#output-structure)
|
||||
- [Installation](#installation)
|
||||
- [Examples](#examples)
|
||||
|
||||
- **Optional Brainstorming**: Creative ideation session before agent building to explore concepts and personalities
|
||||
- **Three Agent Types**: Simple, Expert, and Module agents with appropriate structures
|
||||
- **Persona Development**: Guided creation of role, identity, communication style, and principles
|
||||
- **Command Builder**: Interactive command definition with workflow/task/action patterns
|
||||
- **Validation Built-In**: Ensures YAML structure and BMAD Core compliance
|
||||
- **Customize Support**: Optional `customize.yaml` for persona/menu overrides and critical actions
|
||||
- **Sidecar Resources**: Setup for Expert agents with domain-specific data
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Invocation
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Direct workflow
|
||||
workflow create-agent
|
||||
```
|
||||
|
||||
### Through BMad Builder Agent
|
||||
|
||||
```
|
||||
# Via BMad Builder
|
||||
*create-agent
|
||||
```
|
||||
|
||||
### With Brainstorming Session
|
||||
## Agent Types
|
||||
|
||||
The workflow includes an optional brainstorming phase (Step -1) that helps you explore agent concepts, personalities, and capabilities before building. This is particularly useful when you have a vague idea and want to develop it into a concrete agent concept.
|
||||
### Simple Agent
|
||||
|
||||
### What You'll Be Asked
|
||||
- Self-contained functionality
|
||||
- Basic command structure
|
||||
- No external resources
|
||||
|
||||
0. **Optional brainstorming** (vague idea → refined concept)
|
||||
1. Agent type (Simple, Expert, or Module)
|
||||
2. Basic identity (name, title, icon, filename)
|
||||
3. Module assignment (for Module agents)
|
||||
4. Sidecar resources (for Expert agents)
|
||||
5. Persona elements (role, identity, style, principles)
|
||||
6. Commands and their implementations
|
||||
7. Critical actions (optional)
|
||||
8. Activation rules (optional, rarely needed)
|
||||
### Expert Agent
|
||||
|
||||
## Workflow Structure
|
||||
- Sidecar resources for domain knowledge
|
||||
- Extended capabilities
|
||||
- Knowledge base integration
|
||||
|
||||
### Files Included
|
||||
### Module Agent
|
||||
|
||||
```
|
||||
create-agent/
|
||||
├── workflow.yaml # Configuration
|
||||
├── instructions.md # Step-by-step guide
|
||||
├── checklist.md # Validation criteria
|
||||
├── README.md # This file
|
||||
├── agent-types.md # Agent type documentation
|
||||
├── agent-architecture.md # Architecture patterns
|
||||
├── agent-command-patterns.md # Command patterns reference
|
||||
└── communication-styles.md # Style examples
|
||||
```
|
||||
- Full-featured with workflows
|
||||
- Module-specific commands
|
||||
- Integrated with module structure
|
||||
|
||||
## Workflow Process
|
||||
## Workflow Phases
|
||||
|
||||
### Phase 0: Optional Brainstorming (Step -1)
|
||||
### Phase 0: Optional Brainstorming
|
||||
|
||||
- Creative ideation session using diverse brainstorming techniques
|
||||
- Explore agent concepts, personalities, and capabilities
|
||||
- Generate character ideas, expertise areas, and command concepts
|
||||
- Output feeds directly into agent identity and persona development
|
||||
- Creative ideation session
|
||||
- Explore concepts and personalities
|
||||
- Generate command ideas
|
||||
- Output feeds into persona development
|
||||
|
||||
### Phase 1: Agent Setup (Steps 0-2)
|
||||
### Phase 1: Agent Setup
|
||||
|
||||
- Load agent building documentation and patterns
|
||||
- Choose agent type (Simple/Expert/Module)
|
||||
- Define basic identity (name, title, icon, filename) - informed by brainstorming if completed
|
||||
- Assign to module (for Module agents)
|
||||
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 (Steps 2-3)
|
||||
### Phase 2: Persona Development
|
||||
|
||||
- Define role and responsibilities - leveraging brainstorming insights if available
|
||||
- Craft unique identity and backstory
|
||||
- Select communication style - can use brainstormed personality concepts
|
||||
- Define role and responsibilities
|
||||
- Craft unique identity/backstory
|
||||
- Select communication style
|
||||
- Establish guiding principles
|
||||
- Add critical actions (optional)
|
||||
|
||||
### Phase 3: Command Building (Step 4)
|
||||
### Phase 3: Command Building
|
||||
|
||||
- Add *help and *exit commands (required)
|
||||
- Define workflow commands (most common)
|
||||
- Add task commands (for single operations)
|
||||
- Create action commands (inline logic)
|
||||
- Configure command attributes
|
||||
- Add required commands (*help, *exit)
|
||||
- Define workflow commands
|
||||
- Add task commands
|
||||
- Create action commands
|
||||
- Configure attributes
|
||||
|
||||
### Phase 4: Finalization (Steps 5-10)
|
||||
### Phase 4: Finalization
|
||||
|
||||
- Confirm activation behavior (mostly automatic)
|
||||
- Generate `.agent.yaml` file
|
||||
- Optionally create a customize file for overrides
|
||||
- Setup sidecar resources (for Expert agents)
|
||||
- Validate YAML and compile to `.md`
|
||||
- Generate .agent.yaml file
|
||||
- Create customize file (optional)
|
||||
- Setup sidecar resources (Expert agents)
|
||||
- Validate and compile
|
||||
- Provide usage instructions
|
||||
|
||||
## Output
|
||||
## Output Structure
|
||||
|
||||
### Generated Files
|
||||
|
||||
#### For Standalone Agents (not part of a module)
|
||||
**Standalone Agents:**
|
||||
|
||||
- **YAML Source**: `{custom_agent_location}/{{agent_filename}}.agent.yaml` (default: `bmad/agents/`)
|
||||
- **Installation Location**: `{project-root}/bmad/agents/{{agent_filename}}.md`
|
||||
- **Compilation**: Run the BMAD Method installer and select "Compile Agents (Quick rebuild of all agent .md files)"
|
||||
- Source: `bmad/agents/{filename}.agent.yaml`
|
||||
- Compiled: `bmad/agents/{filename}.md`
|
||||
|
||||
#### For Module Agents
|
||||
**Module Agents:**
|
||||
|
||||
- **YAML Source**: `src/modules/{{target_module}}/agents/{{agent_filename}}.agent.yaml`
|
||||
- **Installation Location**: `{project-root}/bmad/{{module}}/agents/{{agent_filename}}.md`
|
||||
- **Compilation**: Automatic during module installation
|
||||
- Source: `src/modules/{module}/agents/{filename}.agent.yaml`
|
||||
- Compiled: `bmad/{module}/agents/{filename}.md`
|
||||
|
||||
### YAML Agent Structure (simplified)
|
||||
### YAML Structure
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: bmad/{{module}}/agents/{{agent_filename}}.md
|
||||
name: { { agent_name } }
|
||||
title: { { agent_title } }
|
||||
icon: { { agent_icon } }
|
||||
module: { { module } }
|
||||
id: bmad/{module}/agents/{filename}.md
|
||||
name: Agent Name
|
||||
title: Agent Title
|
||||
icon: 🤖
|
||||
module: module-name
|
||||
persona:
|
||||
role: '...'
|
||||
identity: '...'
|
||||
communication_style: '...'
|
||||
principles: ['...', '...']
|
||||
menu:
|
||||
- trigger: example
|
||||
workflow: '{project-root}/path/to/workflow.yaml'
|
||||
description: Do the thing
|
||||
- trigger: command-name
|
||||
workflow: path/to/workflow.yaml
|
||||
description: Command description
|
||||
```
|
||||
|
||||
### Optional Customize File
|
||||
|
||||
If created, generates at:
|
||||
`{project-root}/bmad/_cfg/agents/{{module}}-{{agent_filename}}.customize.yaml`
|
||||
Location: `bmad/_cfg/agents/{module}-{filename}.customize.yaml`
|
||||
|
||||
## Installation and Compilation
|
||||
Allows persona and menu overrides that persist through updates.
|
||||
|
||||
### Agent Installation Locations
|
||||
## Installation
|
||||
|
||||
Agents are installed to different locations based on their type:
|
||||
### Compilation Methods
|
||||
|
||||
1. **Standalone Agents** (not part of a module)
|
||||
- Source: Created in your custom agent location (default: `bmad/agents/`)
|
||||
- Installed to: `{project-root}/bmad/agents/`
|
||||
- Compilation: Run BMAD Method installer and select "Compile Agents"
|
||||
|
||||
2. **Module Agents** (part of BMM, BMB, or custom modules)
|
||||
- Source: Created in `src/modules/{module}/agents/`
|
||||
- Installed to: `{project-root}/bmad/{module}/agents/`
|
||||
- Compilation: Automatic during module installation
|
||||
|
||||
### Compilation Process
|
||||
|
||||
The installer compiles YAML agent definitions to Markdown:
|
||||
**Quick Rebuild:**
|
||||
|
||||
```bash
|
||||
# For standalone agents
|
||||
npm run build:agents
|
||||
|
||||
# For all BMad components (includes agents)
|
||||
npm run install:bmad
|
||||
|
||||
# Using the installer menu
|
||||
npm run installer
|
||||
# Then select: Compile Agents
|
||||
bmad compile-agents
|
||||
```
|
||||
|
||||
### Build Commands
|
||||
**During Module Install:**
|
||||
Automatic compilation when installing modules
|
||||
|
||||
Additional build commands for agent management:
|
||||
**Manual Compilation:**
|
||||
|
||||
```bash
|
||||
# Build specific agent types
|
||||
npx bmad-method build:agents # Build standalone agents
|
||||
npx bmad-method build:modules # Build module agents (with modules)
|
||||
|
||||
# Full rebuild
|
||||
npx bmad-method build:all # Rebuild everything
|
||||
node tools/cli/bmad-cli.js compile-agents
|
||||
```
|
||||
|
||||
## Requirements
|
||||
## Examples
|
||||
|
||||
- BMAD Core v6 project structure
|
||||
- Module to host the agent (for Module agents)
|
||||
- Understanding of agent purpose and commands
|
||||
- Workflows/tasks to reference in commands (or mark as "todo")
|
||||
### Creating a Code Review Agent
|
||||
|
||||
## Brainstorming Integration
|
||||
```
|
||||
User: I need a code review agent
|
||||
Builder: Let's brainstorm first...
|
||||
|
||||
The optional brainstorming phase (Step -1) provides a seamless path from vague idea to concrete agent concept:
|
||||
[Brainstorming generates ideas for strict vs friendly reviewer]
|
||||
|
||||
### When to Use Brainstorming
|
||||
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
|
||||
```
|
||||
|
||||
- **Vague concept**: "I want an agent that helps with data stuff"
|
||||
- **Creative exploration**: Want to discover unique personality and approach
|
||||
- **Team building**: Creating agents for a module with specific roles
|
||||
- **Character development**: Need to flesh out agent personality and voice
|
||||
### Creating a Domain Expert
|
||||
|
||||
### Brainstorming Flow
|
||||
```
|
||||
Type: Expert
|
||||
Name: Legal Advisor
|
||||
Sidecar: legal-knowledge/
|
||||
Commands:
|
||||
- *contract-review
|
||||
- *compliance-check
|
||||
- *risk-assessment
|
||||
```
|
||||
|
||||
1. **Step -1**: Optional brainstorming session
|
||||
- Uses CIS brainstorming workflow with agent-specific context
|
||||
- Explores identity, personality, expertise, and command concepts
|
||||
- Generates detailed character and capability ideas
|
||||
## Workflow Files
|
||||
|
||||
2. **Steps 0-2**: Agent setup informed by brainstorming
|
||||
- Brainstorming output guides agent type selection
|
||||
- Character concepts inform basic identity choices
|
||||
- Personality insights shape persona development
|
||||
|
||||
3. **Seamless transition**: Vague idea → brainstormed concept → built agent
|
||||
|
||||
### Key Principle
|
||||
|
||||
Users can go from **vague idea → brainstormed concept → built agent** in one continuous flow, with brainstorming output directly feeding into agent development.
|
||||
```
|
||||
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
|
||||
|
||||
### Before Starting
|
||||
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
|
||||
|
||||
1. Review example agents in `/bmad/bmm/agents/` for patterns
|
||||
2. Consider using brainstorming if you have a vague concept to develop
|
||||
3. Have a clear vision of the agent's role and personality (or use brainstorming to develop it)
|
||||
4. List the commands/capabilities the agent will need
|
||||
5. Identify any workflows or tasks the agent will invoke
|
||||
## Related Documentation
|
||||
|
||||
### During Execution
|
||||
|
||||
1. **Agent Names**: Use memorable names that reflect personality
|
||||
2. **Icons**: Choose an emoji that represents the agent's role
|
||||
3. **Persona**: Make it distinct and consistent with communication style
|
||||
4. **Commands**: Use kebab-case, start custom commands with letter (not \*)
|
||||
5. **Workflows**: Reference existing workflows or mark as "todo" to implement later
|
||||
|
||||
### After Completion
|
||||
|
||||
1. **Compile the agent**:
|
||||
- For standalone agents: Run `npm run build:agents` or use the installer menu
|
||||
- For module agents: Automatic during module installation
|
||||
2. **Test the agent**: Use the compiled `.md` agent in your IDE
|
||||
3. **Implement placeholders**: Complete any "todo" workflows referenced
|
||||
4. **Refine as needed**: Use customize file for persona adjustments
|
||||
5. **Evolve over time**: Add new commands as requirements emerge
|
||||
|
||||
## Agent Types
|
||||
|
||||
### Simple Agent
|
||||
|
||||
- **Best For**: Self-contained utilities, simple assistants
|
||||
- **Characteristics**: Embedded logic, no external dependencies
|
||||
- **Example**: Calculator agent, random picker, simple formatter
|
||||
|
||||
### Expert Agent
|
||||
|
||||
- **Best For**: Domain-specific agents with data/memory
|
||||
- **Characteristics**: Sidecar folders, domain restrictions, memory files
|
||||
- **Example**: Diary keeper, project journal, personal knowledge base
|
||||
|
||||
### Module Agent
|
||||
|
||||
- **Best For**: Full-featured agents with workflows
|
||||
- **Characteristics**: Part of module, commands invoke workflows
|
||||
- **Example**: Product manager, architect, research assistant
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Agent won't load
|
||||
|
||||
- **Solution**: Validate XML structure is correct
|
||||
- **Check**: Ensure all required tags present (persona, cmds)
|
||||
|
||||
### Issue: Commands don't work
|
||||
|
||||
- **Solution**: Verify workflow paths are correct or marked "todo"
|
||||
- **Check**: Test workflow invocation separately first
|
||||
|
||||
### Issue: Persona feels generic
|
||||
|
||||
- **Solution**: Review communication styles guide
|
||||
- **Check**: Make identity unique and specific to role
|
||||
|
||||
## Customization
|
||||
|
||||
To modify agent building process:
|
||||
|
||||
1. Edit `instructions.md` to change steps
|
||||
2. Update `agent-types.md` to add new agent patterns
|
||||
3. Modify `agent-command-patterns.md` for new command types
|
||||
4. Edit `communication-styles.md` to add personality examples
|
||||
|
||||
## Version History
|
||||
|
||||
- **v6.0.0** - BMAD Core v6 compatible
|
||||
- Three agent types (Simple/Expert/Module)
|
||||
- Enhanced persona development
|
||||
- Command pattern library
|
||||
- Validation framework
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Review example agents in `/bmad/bmm/agents/`
|
||||
- Check agent documentation in this workflow folder
|
||||
- Test with simple agents first, then build complexity
|
||||
- Consult BMAD Method v6 documentation
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMB (BMad Builder) Module_
|
||||
- [Agent Types](./agent-types.md)
|
||||
- [Command Patterns](./agent-command-patterns.md)
|
||||
- [Communication Styles](./communication-styles.md)
|
||||
- [BMB Module](../../README.md)
|
||||
|
||||
@@ -1,412 +0,0 @@
|
||||
# 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>
|
||||
```
|
||||
@@ -1,759 +0,0 @@
|
||||
# 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
|
||||
@@ -20,8 +20,6 @@
|
||||
<check if="user answered no">
|
||||
<action>Proceed directly to Step 0</action>
|
||||
</check>
|
||||
|
||||
<template-output>brainstorming_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="0" goal="Load technical documentation">
|
||||
@@ -103,9 +101,24 @@
|
||||
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
|
||||
**Professional Presets:**
|
||||
|
||||
**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
|
||||
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>
|
||||
|
||||
@@ -352,16 +365,16 @@ Add domain-specific resources here.
|
||||
<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
|
||||
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 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>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user