mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-01-30 04:32:02 +00:00
agent build data optimized
This commit is contained in:
Brian Madison
@@ -1,67 +0,0 @@
|
||||
# Agent Compilation: YAML to XML
|
||||
|
||||
While your goal is to create a agent in the proper yaml format, its useful for you to understand that the YAML file will be compiled to a markdown file with XML in the file. This is the final format that the user will use the agents with an LLM.
|
||||
|
||||
What is outlined here is what additional information is added to the agent so it will blend well with what you will create in the yaml file.
|
||||
|
||||
## Auto-Injected Components
|
||||
|
||||
### 1. Frontmatter
|
||||
|
||||
**Injected automatically to compiled markdown file:**
|
||||
|
||||
```
|
||||
---
|
||||
name: '{agent name from filename}'
|
||||
description: '{title from metadata}'
|
||||
---
|
||||
|
||||
You must fully embody this agent's persona...
|
||||
```
|
||||
|
||||
**DO NOT add** frontmatter to your YAML source.
|
||||
|
||||
### 2. Activation Block
|
||||
|
||||
**Entire activation section is auto-generated:**
|
||||
**DO NOT create** activation sections - compiler builds it from your critical_actions in the place where it is indicated with a comment in the next xml block.
|
||||
|
||||
```xml
|
||||
<activation critical="MANDATORY">
|
||||
<step n="1">Load persona from this current agent file</step>
|
||||
<step n="2">Load config to get {user_name}, {communication_language}</step>
|
||||
<step n="3">Remember: user's name is {user_name}</step>
|
||||
<!-- YOUR critical_actions inserted here as numbered steps -->
|
||||
<step n="N">ALWAYS communicate in {communication_language}</step>
|
||||
<step n="N+1">Show greeting + numbered menu</step>
|
||||
<step n="N+2">STOP and WAIT for user input</step>
|
||||
<step n="N+3">Input resolution rules</step>
|
||||
</activation>
|
||||
```
|
||||
|
||||
### 4. Rules Section
|
||||
|
||||
**Auto-injected rules:**
|
||||
**DO NOT add any of these rules to the yaml** - compiler handles it when building the markdown:
|
||||
|
||||
- Always communicate in {communication_language}
|
||||
- Stay in character until exit
|
||||
- Menu triggers use asterisk (*) - NOT markdown
|
||||
- Number all lists, use letters for sub-options
|
||||
- Load files ONLY when executing menu items
|
||||
- Written output follows communication style
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
1. **Compiler handles boilerplate** - Focus on persona and logic
|
||||
2. **Critical_actions become activation steps** - Just list your agent-specific needs
|
||||
3. **These Menu items are auto included with every agent** - Every agent will have 4 menu items automatically added, so do not duplicate them with other menu items:
|
||||
1. <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
|
||||
2. <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
|
||||
3. <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
|
||||
4. <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
|
||||
4. **Handlers auto-detected** - Only what you use is included
|
||||
5. **Rules standardized** - Consistent behavior across agents
|
||||
|
||||
**Your job:** Define persona, prompts, menu actions
|
||||
**Compiler's job:** Activation, handlers, rules, help/exit, prefixes
|
||||
@@ -1,295 +0,0 @@
|
||||
# BMAD Agent Menu Patterns
|
||||
|
||||
Design patterns for agent menus in YAML source files.
|
||||
|
||||
## Menu Structure
|
||||
|
||||
Agents define menus in YAML, with triggers to know when to fire, a handler that knows the path or instruction of what the menu item does, and a description which is a display field for the agent. exec
|
||||
|
||||
### Menu Item Rules
|
||||
|
||||
- At a minimum, every menu item will have in the yaml the keys `trigger`, [handler], and `description`. A menu can also have an optional `data` key.
|
||||
- the handler key will be either `action` or `exec`.
|
||||
- The Description value always starts with a unique (for this agent) 2 letter code in brackets along with the display text for the menu item.
|
||||
- The 2 letter code CANNOT be the following reserved codes: [MH], [CH], [PM], [DA]
|
||||
- the trigger is always in the format `XY or fuzzy match on action-name` - XY being the items 2 letter code and action-name being what user will generally request by reading the description
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: AN or fuzzy match on action-name
|
||||
[handler]: [value]
|
||||
data: optional field reference to a file to pass to the handlers workflow, some workflows take data inputs
|
||||
description: '[AN] Menu display for Action Name'
|
||||
```
|
||||
|
||||
## Handler Types
|
||||
|
||||
### 1. Action Handler (Prompts & Inline)
|
||||
|
||||
For agents that are not part of a module or its a very simple operation that can be defined within the agent file, action is used.
|
||||
|
||||
<example>
|
||||
**Reference to Prompt ID:**
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: analyze-code
|
||||
content: |
|
||||
<instructions>
|
||||
Analyze the provided code for patterns and issues.
|
||||
</instructions>
|
||||
|
||||
<process>
|
||||
1. Identify code structure
|
||||
2. Check for anti-patterns
|
||||
3. Suggest improvements
|
||||
</process>
|
||||
|
||||
menu:
|
||||
- trigger: analyze
|
||||
action: '#analyze-code'
|
||||
description: 'Analyze code patterns'
|
||||
```
|
||||
</example>
|
||||
|
||||
**Inline Instruction:**
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: quick-check
|
||||
action: |
|
||||
<instructions>
|
||||
Analyze the provided code for patterns and issues.
|
||||
</instructions>
|
||||
|
||||
<process>
|
||||
1. Identify code structure
|
||||
2. Check for anti-patterns
|
||||
3. Suggest improvements
|
||||
</process>
|
||||
description: 'Quick syntax check'
|
||||
```
|
||||
|
||||
**When to Use:**
|
||||
|
||||
- Simple/Expert agents with self-contained operations
|
||||
- `#id` for complex, multi-step prompts
|
||||
- Inline text for simple, one-line instructions
|
||||
|
||||
### 2. Workflow Handler
|
||||
|
||||
For module agents referencing module workflows (muti-step complex workflows loaded on demand).
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: CP or fuzzy match on create-prd
|
||||
exec: '{project-root}/_bmad/bmm/workflows/prd/workflow.md'
|
||||
description: '[CP] Create Product Requirements Document (PRD)'
|
||||
|
||||
- trigger: GB or fuzzy match on guided-brainstorming
|
||||
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
|
||||
description: '[GB] Guided brainstorming session'
|
||||
|
||||
# Placeholder for unimplemented workflows
|
||||
- trigger: FF or fuzzy match on future-feature
|
||||
exec: 'todo'
|
||||
description: '[FF] Coming soon Future Feature'
|
||||
```
|
||||
|
||||
**When to Use:**
|
||||
|
||||
- Module agents with workflow integration
|
||||
- Multi-step document generation
|
||||
- Complex interactive processes
|
||||
- Use "todo" for planned but unimplemented features
|
||||
|
||||
### 3. Exec Handler
|
||||
|
||||
For executing tasks directly.
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: validate
|
||||
exec: '{project-root}/_bmad/core/tasks/validate-workflow.xml'
|
||||
description: 'Validate document structure'
|
||||
|
||||
- trigger: advanced-elicitation
|
||||
exec: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
description: 'Advanced elicitation techniques'
|
||||
```
|
||||
|
||||
**When to Use:**
|
||||
|
||||
- Single-operation tasks
|
||||
- Core system operations
|
||||
- Utility functions
|
||||
|
||||
### 5. Data Handler
|
||||
|
||||
Universal attribute for supplementary information.
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: TS or fuzzy match team-standup or daily standup
|
||||
exec: '{project-root}/_bmad/bmm/tasks/team-standup.md'
|
||||
data: '{project-root}/_bmad/_config/agent-manifest.csv'
|
||||
description: '[TS] Run team standup'
|
||||
|
||||
- trigger: AM or fuzzy match on analyze-metrics
|
||||
action: 'Analyze these metrics and identify trends'
|
||||
data: '{project-root}/_data/metrics.json'
|
||||
description: '[AM] Analyze performance metrics'
|
||||
```
|
||||
|
||||
**When to Use:**
|
||||
|
||||
- Add to ANY handler type
|
||||
- Reference data files (CSV, JSON, YAML)
|
||||
- Provide context for operations
|
||||
|
||||
## Platform-Specific Menus
|
||||
|
||||
Control visibility based on deployment target:
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: git-flow
|
||||
exec: '{project-root}/_bmad/bmm/tasks/git-flow.xml'
|
||||
description: 'Git workflow operations'
|
||||
ide-only: true # Only in IDE environments
|
||||
|
||||
- trigger: advanced-elicitation
|
||||
exec: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
description: 'Advanced elicitation'
|
||||
web-only: true # Only in web bundles
|
||||
```
|
||||
|
||||
## Prompts Section (generally for agents that are not using external workflows)
|
||||
|
||||
### Prompt Structure
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: unique-identifier
|
||||
content: |
|
||||
<goal> What the prompt achieves </goal>
|
||||
<instructions>
|
||||
Step 1: Foo
|
||||
Step 2: Bar
|
||||
...
|
||||
</instructions>
|
||||
<example> </example>
|
||||
etc...
|
||||
```
|
||||
|
||||
### Semantic XML Tags in Prompts
|
||||
|
||||
Use XML tags to structure prompt content such as:
|
||||
|
||||
- `<goal>` - What to do
|
||||
- `<instructions>` - Step-by-step approach
|
||||
- `<output_format>` - Expected results
|
||||
- `<example>` - Sample outputs
|
||||
|
||||
## Path Variables
|
||||
|
||||
### Always Use Variables
|
||||
|
||||
```yaml
|
||||
# GOOD - Portable paths
|
||||
exec: "{project-root}/_bmad/core/tasks/validate.xml"
|
||||
data: "{project-root}/_data/metrics.csv"
|
||||
|
||||
# BAD - Hardcoded paths
|
||||
exec: "../../../core/tasks/validate.xml"
|
||||
```
|
||||
|
||||
### Available Variables
|
||||
|
||||
- `{project-root}` - Project root directory
|
||||
- `{output_folder}` - Document output location
|
||||
- `{user_name}` - User's name from config
|
||||
- `{communication_language}` - Language preference
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### Simple Agent Menu
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: format-code
|
||||
content: |
|
||||
<instructions>
|
||||
Format the provided code according to style guidelines.
|
||||
</instructions>
|
||||
|
||||
Apply:
|
||||
- Consistent indentation
|
||||
- Proper spacing
|
||||
- Clear naming conventions
|
||||
|
||||
menu:
|
||||
- trigger: format
|
||||
action: '#format-code'
|
||||
description: 'Format code to style guidelines'
|
||||
|
||||
- trigger: lint
|
||||
action: 'Check code for common issues and anti-patterns'
|
||||
description: 'Lint code for issues'
|
||||
|
||||
- trigger: suggest-improvements
|
||||
action: >
|
||||
Suggest improvements for code that is not yet comitted:
|
||||
- style improvements
|
||||
- deviations from **/project-context.md
|
||||
description: 'Suggest improvements'
|
||||
```
|
||||
|
||||
### Expert Agent Menu
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Load ./memories.md'
|
||||
- 'Follow ./instructions.md'
|
||||
- 'ONLY access ./'
|
||||
|
||||
prompts:
|
||||
- id: reflect
|
||||
content: |
|
||||
Guide {{user_name}} through reflection on recent entries.
|
||||
Reference patterns from memories.md naturally.
|
||||
|
||||
menu:
|
||||
- trigger: write
|
||||
action: '#reflect'
|
||||
description: 'Write journal entry'
|
||||
|
||||
- trigger: save
|
||||
action: 'Update ./memories.md with session insights'
|
||||
description: "Save today's session"
|
||||
|
||||
- trigger: patterns
|
||||
action: 'Analyze recent entries for recurring themes'
|
||||
description: 'View patterns'
|
||||
```
|
||||
|
||||
### Module Agent Menu
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: workflow-init
|
||||
exec: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.md'
|
||||
description: 'Initialize workflow path (START HERE)'
|
||||
|
||||
- trigger: brainstorm
|
||||
exec: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.md'
|
||||
description: 'Guided brainstorming'
|
||||
|
||||
- trigger: prd
|
||||
exec: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.md'
|
||||
description: 'Create PRD'
|
||||
|
||||
- trigger: architecture
|
||||
exec: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.md'
|
||||
description: 'Design architecture'
|
||||
```
|
||||
@@ -1,212 +0,0 @@
|
||||
# Expert Agent Architecture
|
||||
|
||||
Domain-specific agents with persistent memory, sidecar files, and restricted access patterns. The main difference between a simple agent and an Expert agent, is the expert has its own collection of external files in a sidecar folder that can include files to record memories, and it can have files for prompts, skills and workflows specific to the agent that manus can reference to load and exec on demand.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Personal assistants (journal keeper, diary companion)
|
||||
- Specialized domain experts (legal advisor, medical reference)
|
||||
- Agents that need to remember past interactions
|
||||
- Agents with restricted file system access (privacy/security)
|
||||
- Long-term relationship agents that learn about users
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
{agent-name}/
|
||||
├── {agent-name}.agent.yaml # Main agent definition
|
||||
└── {agent-name}-sidecar/ # Supporting files
|
||||
├── instructions.md # Private directives
|
||||
├── memories.md # Persistent memory
|
||||
├── knowledge/ # Domain-specific resources
|
||||
│ └── README.md
|
||||
└── [custom files] # Agent-specific resources
|
||||
```
|
||||
|
||||
## YAML Structure
|
||||
|
||||
The YAML structure of the agent file itself is the same as every other agent, but generally will have something like these 3 items added to the critical_actions:
|
||||
- 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights'
|
||||
- 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols'
|
||||
- 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space'
|
||||
|
||||
## Key Components
|
||||
|
||||
### Sidecar Files (CRITICAL)
|
||||
|
||||
Expert agents use companion files for persistence and domain knowledge:
|
||||
|
||||
**memories.md** - Persistent user context will be set up similar to as follows, of course with relevant sections that make sense.
|
||||
|
||||
```markdown
|
||||
# Agent Memory Bank
|
||||
|
||||
## User Preferences
|
||||
|
||||
<!-- Learned from interactions -->
|
||||
|
||||
## Session History
|
||||
|
||||
<!-- Important moments and insights -->
|
||||
|
||||
## Personal Notes
|
||||
|
||||
<!-- Agent observations -->
|
||||
```
|
||||
|
||||
**instructions.md** - Private directives
|
||||
|
||||
```markdown
|
||||
# Agent Private Instructions
|
||||
|
||||
## Core Directives
|
||||
|
||||
- Maintain character consistency
|
||||
- Domain boundaries: {specific domain}
|
||||
- Access restrictions: Only sidecar folder
|
||||
|
||||
## Special Rules
|
||||
|
||||
<!-- Agent-specific protocols -->
|
||||
```
|
||||
|
||||
**knowledge/** - Domain resources
|
||||
|
||||
```markdown
|
||||
# Agent Knowledge Base
|
||||
|
||||
Add domain-specific documentation here.
|
||||
```
|
||||
|
||||
### Critical Actions
|
||||
|
||||
**MANDATORY for expert agents** - These load sidecar files at activation:
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights'
|
||||
- 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols'
|
||||
- 'ONLY read/write files in ./{sidecar}/ - this is our private space'
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
|
||||
- **COMPLETE file loading** - Forces full file read, not partial
|
||||
- **Domain restrictions** - Limits file access for privacy/security
|
||||
- **Memory integration** - Past context becomes part of current session
|
||||
- **Protocol adherence** - Ensures consistent behavior
|
||||
|
||||
## What Gets Injected at Compile Time
|
||||
|
||||
Same as simple agents, PLUS:
|
||||
|
||||
1. **Critical actions become numbered activation steps**
|
||||
|
||||
```xml
|
||||
<step n="4">Load COMPLETE file ./memories.md...</step>
|
||||
<step n="5">Load COMPLETE file ./instructions.md...</step>
|
||||
<step n="6">ONLY read/write files in ./...</step>
|
||||
```
|
||||
|
||||
2. **Sidecar files copied during installation**
|
||||
- Entire sidecar folder structure preserved
|
||||
- Relative paths maintained
|
||||
- Files ready for agent use
|
||||
|
||||
## Reference Example
|
||||
|
||||
See: [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper)
|
||||
|
||||
Features demonstrated:
|
||||
|
||||
- Complete sidecar structure (memories, instructions, breakthroughs)
|
||||
- Critical actions for loading persistent context
|
||||
- Domain restrictions for privacy
|
||||
- Pattern recognition and memory recall
|
||||
- Handlebars-based personalization
|
||||
- Menu actions that update sidecar files
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Copy entire folder to your project
|
||||
cp -r /path/to/journal-keeper/ _bmad/custom/agents/
|
||||
|
||||
# Install with personalization
|
||||
bmad agent-install
|
||||
```
|
||||
|
||||
The installer:
|
||||
|
||||
1. Detects expert agent (folder with .agent.yaml)
|
||||
2. Prompts for personalization
|
||||
3. Compiles agent YAML to XML-in-markdown
|
||||
4. **Copies sidecar files to installation target**
|
||||
5. Creates IDE slash commands
|
||||
6. Saves source for reinstallation
|
||||
|
||||
## Memory Patterns
|
||||
|
||||
### Accumulative Memory
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: save
|
||||
action: "Update ./sidecar/memories.md with today's session insights"
|
||||
description: 'Save session to memory'
|
||||
```
|
||||
|
||||
### Reference Memory
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: recall
|
||||
content: |
|
||||
<instructions>
|
||||
Reference memories.md naturally:
|
||||
"Last week you mentioned..." or "I notice a pattern..."
|
||||
</instructions>
|
||||
```
|
||||
|
||||
### Structured Insights
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: insight
|
||||
action: 'Document in ./sidecar/breakthroughs.md with date, context, significance'
|
||||
description: 'Record meaningful insight'
|
||||
```
|
||||
|
||||
## Domain Restriction Patterns that can be applied
|
||||
|
||||
### Single Folder Access
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS'
|
||||
```
|
||||
|
||||
### User Space Access
|
||||
|
||||
If there were a private journal agent, you might want it to have something like this:
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'ONLY access files in {user-folder}/journals/ - private space'
|
||||
```
|
||||
|
||||
### Read-Only Access
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Load knowledge from ./knowledge/ but NEVER modify'
|
||||
- 'Write ONLY to ./sessions/'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
|
||||
2. **Enforce domain restrictions** - Clear boundaries prevent scope creep=
|
||||
3. **Design for memory growth** - Structure sidecar files for accumulation
|
||||
4. **Reference past naturally** - Don't dump memory, weave it into conversation
|
||||
5. **Separate concerns** - Memories, instructions, knowledge in distinct files
|
||||
6. **Include privacy features** - Users trust expert agents with personal data
|
||||
@@ -1,241 +0,0 @@
|
||||
# Agent Architecture
|
||||
|
||||
All agents follow these basic guidelines to define their YAML.
|
||||
|
||||
## YAML Structure
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: _bmad/agents/{agent-name}/{agent-name}.md
|
||||
name: 'Persona Name'
|
||||
title: 'Agent Title'
|
||||
icon: 'emoji'
|
||||
module: stand-alone || module-code (like bmm)
|
||||
|
||||
persona:
|
||||
role: |
|
||||
First-person description of primary function (1-2 sentences)
|
||||
|
||||
identity: |
|
||||
Background, experience, specializations in first-person (2-5 sentences)
|
||||
|
||||
communication_style:
|
||||
|
||||
principles:
|
||||
- Core belief or methodology
|
||||
- Another guiding principle
|
||||
- Values that shape decisions
|
||||
|
||||
prompts:
|
||||
- id: main-action
|
||||
content: |
|
||||
<instructions>
|
||||
What this prompt does
|
||||
</instructions>
|
||||
|
||||
<process>
|
||||
1. Step one
|
||||
{{#if detailed_mode}}
|
||||
2. Additional detailed step
|
||||
{{/if}}
|
||||
3. Final step
|
||||
</process>
|
||||
|
||||
- id: another-action
|
||||
content: |
|
||||
Another reusable prompt template
|
||||
|
||||
menu:
|
||||
- trigger: inline
|
||||
action: 'Direct inline prompt text'
|
||||
description: 'Execute inline action'
|
||||
|
||||
- multi: "[DF] Do Foo or start [CH] Chat with expert"
|
||||
triggers:
|
||||
- do-foo
|
||||
- input: [DF] or fuzzy match on do foo
|
||||
- action: '#main-action'
|
||||
- data: what is being discussed or suggested with the command, along with custom party custom agents if specified
|
||||
- type: action
|
||||
- expert-chat:
|
||||
- input: [CH] or fuzzy match validate agent
|
||||
- action: agent responds as expert based on its persona to converse
|
||||
- type: action
|
||||
|
||||
install_config:
|
||||
compile_time_only: true
|
||||
description: 'Personalize your agent'
|
||||
questions:
|
||||
- var: style_choice
|
||||
prompt: 'Preferred communication style?'
|
||||
type: choice
|
||||
options:
|
||||
- label: 'Professional'
|
||||
value: 'professional'
|
||||
- label: 'Casual'
|
||||
value: 'casual'
|
||||
default: 'professional'
|
||||
|
||||
- var: detailed_mode
|
||||
prompt: 'Enable detailed explanations?'
|
||||
type: boolean
|
||||
default: true
|
||||
|
||||
- var: custom_variable
|
||||
prompt: 'Your custom text'
|
||||
type: text
|
||||
default: ''
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### Metadata
|
||||
|
||||
- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone)
|
||||
- **name**: Agent's persona name displayed to users
|
||||
- **title**: Professional role/function
|
||||
- **icon**: Single emoji for visual identification
|
||||
- **type**: `simple` - identifies agent category
|
||||
|
||||
### Persona (First-Person Voice)
|
||||
|
||||
- **role**: Primary expertise in 1-2 sentences
|
||||
- **identity**: Background and specializations (2-5 sentences)
|
||||
- **communication_style**: HOW the agent interacts, including conditional variations
|
||||
- **principles**: Array of core beliefs (start with action verbs)
|
||||
|
||||
### Prompts with IDs
|
||||
|
||||
Reusable prompt templates referenced by `#id`:
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: analyze-code
|
||||
content: |
|
||||
<instructions>
|
||||
Analyze the provided code for patterns
|
||||
</instructions>
|
||||
```
|
||||
|
||||
Menu items reference these:
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: analyze
|
||||
action: '#analyze-code'
|
||||
description: 'Analyze code patterns'
|
||||
```
|
||||
|
||||
### Menu Actions
|
||||
|
||||
Two forms of action handlers:
|
||||
|
||||
1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content
|
||||
2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly
|
||||
|
||||
### Install Config (Compile-Time Customization)
|
||||
|
||||
Questions asked during `bmad agent-install`:
|
||||
|
||||
**Question Types:**
|
||||
|
||||
- `choice` - Multiple choice selection
|
||||
- `boolean` - Yes/no toggle
|
||||
- `text` - Free-form text input
|
||||
|
||||
**Variables become available in Handlebars:**
|
||||
|
||||
```yaml
|
||||
{{#if variable_name}}
|
||||
Content when true
|
||||
{{/if}}
|
||||
|
||||
{{#if variable_name == "value"}}
|
||||
Content when equals value
|
||||
{{/if}}
|
||||
|
||||
{{#unless variable_name}}
|
||||
Content when false
|
||||
{{/unless}}
|
||||
```
|
||||
|
||||
## What Gets Injected at Compile Time
|
||||
|
||||
The `tools/cli/lib/agent/compiler.js` automatically adds:
|
||||
|
||||
1. **YAML Frontmatter**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: 'agent name'
|
||||
description: 'Agent Title'
|
||||
---
|
||||
```
|
||||
|
||||
2. **Activation Block**
|
||||
- Load persona step
|
||||
- Load core config for {user_name}, {communication_language}
|
||||
- Agent-specific critical_actions as numbered steps
|
||||
- Menu display and input handling
|
||||
- Menu handlers (action/workflow/exec/tmpl) based on usage
|
||||
- Rules section
|
||||
|
||||
3. **Auto-Injected Menu Items**
|
||||
- `*help` always first
|
||||
- `*exit` always last
|
||||
|
||||
4. **Trigger Prefixing**
|
||||
- Triggers without `*` get it added automatically
|
||||
|
||||
## Reference Example
|
||||
|
||||
See: [commit-poet.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)
|
||||
|
||||
Features demonstrated:
|
||||
|
||||
- Handlebars conditionals for style variations
|
||||
- Multiple prompt templates with semantic XML tags
|
||||
- Install config with choice, boolean, and text questions
|
||||
- Menu items using both `#id` references and inline actions
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Copy to your project
|
||||
cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/
|
||||
|
||||
# Create custom.yaml and install
|
||||
echo "code: my-agent
|
||||
name: My Agent
|
||||
default_selected: true" > custom.yaml
|
||||
|
||||
npx bmad-method install
|
||||
# or: bmad install
|
||||
```
|
||||
|
||||
The installer:
|
||||
|
||||
1. Prompts for personalization (name, preferences)
|
||||
2. Processes Handlebars templates with your answers
|
||||
3. Compiles YAML to XML-in-markdown
|
||||
4. Creates IDE slash commands
|
||||
5. Saves source for reinstallation
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use first-person voice** in all persona elements
|
||||
2. **Keep prompts focused** - one clear purpose per prompt
|
||||
3. **Leverage Handlebars** for user customization without code changes
|
||||
4. **Provide sensible defaults** in install_config
|
||||
5. **Use semantic XML tags** in prompt content for clarity
|
||||
6. **Test all conditional paths** before distribution
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] Valid YAML syntax
|
||||
- [ ] All metadata fields present (id, name, title, icon, type)
|
||||
- [ ] Persona complete (role, identity, communication_style, principles)
|
||||
- [ ] Prompts have unique IDs
|
||||
- [ ] Install config questions have defaults
|
||||
- [ ] File named `{agent-name}.agent.yaml`
|
||||
273
src/modules/bmb/workflows/create-agent/data/agent-compilation.md
Normal file
273
src/modules/bmb/workflows/create-agent/data/agent-compilation.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# Agent Compilation: YAML Source → Final Agent
|
||||
|
||||
> **For the LLM running this workflow:** This document explains what the compiler adds. When building agents, focus on the YAML structure defined here—do NOT add things the compiler handles automatically.
|
||||
>
|
||||
> **Example reference:** Compare `{workflow_path}/data/reference/module-examples/architect.agent.yaml` (source, 32 lines) with `architect.md` (compiled, 69 lines) to see what the compiler adds.
|
||||
|
||||
---
|
||||
|
||||
## Quick Overview
|
||||
|
||||
You write: **YAML source file** (`agent-name.agent.yaml`)
|
||||
Compiler produces: **Markdown with XML** (`agent-name.md`) for LLM consumption
|
||||
|
||||
The compiler transforms your clean YAML into a fully functional agent by adding:
|
||||
- Frontmatter (name, description)
|
||||
- XML activation block with numbered steps
|
||||
- Menu handlers (workflow, exec, action)
|
||||
- Auto-injected menu items (MH, CH, PM, DA)
|
||||
- Rules section
|
||||
|
||||
---
|
||||
|
||||
## What YOU Provide (YAML Source)
|
||||
|
||||
Your YAML contains ONLY these sections:
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: "_bmad/..."
|
||||
name: "Persona Name"
|
||||
title: "Agent Title"
|
||||
icon: "🔧"
|
||||
module: "stand-alone" or "bmm" or "cis" or "bmgd"
|
||||
|
||||
persona:
|
||||
role: "First-person role description"
|
||||
identity: "Background and specializations"
|
||||
communication_style: "How the agent speaks"
|
||||
principles:
|
||||
- "Core belief or methodology"
|
||||
|
||||
critical_actions: # Optional - for Expert agents only
|
||||
- "Load ./sidecar/memories.md"
|
||||
- "Load ./sidecar/instructions.md"
|
||||
- "ONLY access ./sidecar/"
|
||||
|
||||
prompts: # Optional - for Simple/Expert agents
|
||||
- id: prompt-name
|
||||
content: |
|
||||
<instructions>Prompt content</instructions>
|
||||
|
||||
menu: # Your custom items only
|
||||
- trigger: XX or fuzzy match on command-name
|
||||
workflow: "path/to/workflow.yaml" # OR
|
||||
exec: "path/to/file.md" # OR
|
||||
action: "#prompt-id"
|
||||
description: "[XX] Command description"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What COMPILER Adds (DO NOT Include)
|
||||
|
||||
### 1. Frontmatter
|
||||
```markdown
|
||||
---
|
||||
name: "architect"
|
||||
description: "Architect"
|
||||
---
|
||||
```
|
||||
**DO NOT add** frontmatter to your YAML.
|
||||
|
||||
### 2. XML Activation Block
|
||||
```xml
|
||||
<activation critical="MANDATORY">
|
||||
<step n="1">Load persona from this current agent file</step>
|
||||
<step n="2">Load config to get {user_name}, {communication_language}</step>
|
||||
<step n="3">Remember: user's name is {user_name}</step>
|
||||
<!-- YOUR critical_actions inserted here as steps 4, 5, etc. -->
|
||||
<step n="N">ALWAYS communicate in {communication_language}</step>
|
||||
<step n="N+1">Show greeting + numbered menu</step>
|
||||
<step n="N+2">STOP and WAIT for user input</step>
|
||||
<step n="N+3">Input resolution rules</step>
|
||||
<menu-handlers>...</menu-handlers>
|
||||
<rules>...</rules>
|
||||
</activation>
|
||||
```
|
||||
**DO NOT create** activation sections—the compiler builds them.
|
||||
|
||||
### 3. Auto-Injected Menu Items
|
||||
Every agent gets these 4 items automatically. **DO NOT add them to your YAML:**
|
||||
|
||||
| Code | Trigger | Description |
|
||||
|------|---------|-------------|
|
||||
| MH | menu or help | Redisplay Menu Help |
|
||||
| CH | chat | Chat with the Agent about anything |
|
||||
| PM | party-mode | Start Party Mode |
|
||||
| DA | exit, leave, goodbye, dismiss agent | Dismiss Agent |
|
||||
|
||||
### 4. Menu Handlers
|
||||
```xml
|
||||
<handler type="workflow">
|
||||
When menu item has: workflow="path/to/workflow.yaml"
|
||||
→ Load workflow.xml and execute with workflow-config parameter
|
||||
</handler>
|
||||
<handler type="exec">
|
||||
When menu item has: exec="path/to/file.md"
|
||||
→ Load and execute the file at that path
|
||||
</handler>
|
||||
```
|
||||
**DO NOT add** handlers—the compiler detects and generates them.
|
||||
|
||||
---
|
||||
|
||||
## Before/After Example: Architect Agent
|
||||
|
||||
### Source: `architect.agent.yaml` (32 lines - YOU WRITE)
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: "_bmad/bmm/agents/architect.md"
|
||||
name: Winston
|
||||
title: Architect
|
||||
icon: 🏗️
|
||||
module: bmm
|
||||
|
||||
persona:
|
||||
role: System Architect + Technical Design Leader
|
||||
identity: Senior architect with expertise in distributed systems...
|
||||
communication_style: "Speaks in calm, pragmatic tones..."
|
||||
principles: |
|
||||
- User journeys drive technical decisions...
|
||||
|
||||
menu:
|
||||
- trigger: WS or fuzzy match on workflow-status
|
||||
workflow: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
description: "[WS] Get workflow status..."
|
||||
|
||||
- trigger: CA or fuzzy match on create-architecture
|
||||
exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
|
||||
description: "[CA] Create an Architecture Document"
|
||||
|
||||
- trigger: IR or fuzzy match on implementation-readiness
|
||||
exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
|
||||
description: "[IR] Implementation Readiness Review"
|
||||
```
|
||||
|
||||
### Compiled: `architect.md` (69 lines - COMPILER PRODUCES)
|
||||
```markdown
|
||||
---
|
||||
name: "architect"
|
||||
description: "Architect"
|
||||
---
|
||||
|
||||
You must fully embody this agent's persona...
|
||||
|
||||
```xml
|
||||
<agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
|
||||
<activation critical="MANDATORY">
|
||||
<step n="1">Load persona from this current agent file (already in context)</step>
|
||||
<step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT...</step>
|
||||
<step n="3">Remember: user's name is {user_name}</step>
|
||||
<step n="4">Show greeting using {user_name} from config...</step>
|
||||
<step n="5">STOP and WAIT for user input...</step>
|
||||
<step n="6">On user input: Number → execute menu item[n]...</step>
|
||||
<step n="7">When executing a menu item: Check menu-handlers section...</step>
|
||||
|
||||
<menu-handlers>
|
||||
<handlers>
|
||||
<handler type="workflow">...</handler>
|
||||
<handler type="exec">...</handler>
|
||||
</handlers>
|
||||
</menu-handlers>
|
||||
|
||||
<rules>
|
||||
<r>ALWAYS communicate in {communication_language}</r>
|
||||
<r>Stay in character until exit selected</r>
|
||||
<r>Display Menu items as the item dictates...</r>
|
||||
<r>Load files ONLY when executing menu items...</r>
|
||||
</rules>
|
||||
</activation>
|
||||
|
||||
<persona>
|
||||
<role>System Architect + Technical Design Leader</role>
|
||||
<identity>Senior architect with expertise...</identity>
|
||||
<communication_style>Speaks in calm, pragmatic tones...</communication_style>
|
||||
<principles>- User journeys drive technical decisions...</principles>
|
||||
</persona>
|
||||
|
||||
<menu>
|
||||
<item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
|
||||
<item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
|
||||
<item cmd="WS...">[WS] Get workflow status...</item> ← YOUR CUSTOM ITEMS
|
||||
<item cmd="CA...">[CA] Create an Architecture Document</item>
|
||||
<item cmd="IR...">[IR] Implementation Readiness Review</item>
|
||||
<item cmd="PM...">[PM] Start Party Mode</item>
|
||||
<item cmd="DA...">[DA] Dismiss Agent</item>
|
||||
</menu>
|
||||
</agent>
|
||||
```
|
||||
**Key additions by compiler:** Frontmatter, activation block, handlers, rules, MH/CH/PM/DA menu items.
|
||||
|
||||
---
|
||||
|
||||
## DO NOT DO Checklist
|
||||
|
||||
When building agent YAML, **DO NOT:**
|
||||
|
||||
- [ ] Add frontmatter (`---name/description---`) to YAML
|
||||
- [ ] Create activation blocks or XML sections
|
||||
- [ ] Add MH (menu/help) menu item
|
||||
- [ ] Add CH (chat) menu item
|
||||
- [ ] Add PM (party-mode) menu item
|
||||
- [ ] Add DA (dismiss/exit) menu item
|
||||
- [ ] Add menu handlers (workflow/exec logic)
|
||||
- [ ] Add rules section
|
||||
- [ ] Duplicate any auto-injected content
|
||||
|
||||
**DO:**
|
||||
- [ ] Define metadata (id, name, title, icon, module)
|
||||
- [ ] Define persona (role, identity, communication_style, principles)
|
||||
- [ ] Define critical_actions (Expert agents only)
|
||||
- [ ] Define prompts with IDs (Simple/Expert agents only)
|
||||
- [ ] Define menu with your custom items only
|
||||
- [ ] Use proper trigger format: `XX or fuzzy match on command-name`
|
||||
- [ ] Use proper description format: `[XX] Description text`
|
||||
|
||||
---
|
||||
|
||||
## Expert Agent: critical_actions
|
||||
|
||||
For Expert agents with sidecars, your `critical_actions` become activation steps:
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- "Load COMPLETE file ./agent-sidecar/memories.md"
|
||||
- "Load COMPLETE file ./agent-sidecar/instructions.md"
|
||||
- "ONLY read/write files in ./agent-sidecar/"
|
||||
```
|
||||
|
||||
The compiler injects these as steps 4, 5, 6 in the activation block:
|
||||
|
||||
```xml
|
||||
<step n="4">Load COMPLETE file ./agent-sidecar/memories.md</step>
|
||||
<step n="5">Load COMPLETE file ./agent-sidecar/instructions.md</step>
|
||||
<step n="6">ONLY read/write files in ./agent-sidecar/</step>
|
||||
<step n="7">ALWAYS communicate in {communication_language}</step>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Division of Responsibilities
|
||||
|
||||
| Aspect | YOU Provide (YAML) | COMPILER Adds |
|
||||
|--------|-------------------|---------------|
|
||||
| Agent identity | metadata + persona | Wrapped in XML |
|
||||
| Memory/actions | critical_actions | Inserted as activation steps |
|
||||
| Prompts | prompts with IDs | Referenced by menu actions |
|
||||
| Menu items | Your custom commands only | + MH, CH, PM, DA (auto) |
|
||||
| Activation | — | Full XML block with handlers |
|
||||
| Rules | — | Standardized rules section |
|
||||
| Frontmatter | — | name/description header |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference for LLM
|
||||
|
||||
- **Focus on:** Clean YAML structure, persona definition, custom menu items
|
||||
- **Ignore:** What happens after compilation—that's the compiler's job
|
||||
- **Remember:** Every agent gets MH, CH, PM, DA automatically—don't add them
|
||||
- **Expert agents:** Use `critical_actions` for sidecar file loading
|
||||
- **Module agents:** Use `workflow:` or `exec:` references, not inline actions
|
||||
@@ -0,0 +1,233 @@
|
||||
# Agent Menu Patterns
|
||||
|
||||
Technical reference for creating agent menu items in YAML.
|
||||
|
||||
---
|
||||
|
||||
## Menu Item Structure
|
||||
|
||||
Every menu item requires:
|
||||
|
||||
```yaml
|
||||
- trigger: XX or fuzzy match on command-name
|
||||
[handler]: [value]
|
||||
description: '[XX] Display text here'
|
||||
data: [optional] # Pass file to workflow
|
||||
```
|
||||
|
||||
**Required fields:**
|
||||
- `trigger` - Format: `XX or fuzzy match on command-name` (XX = 2-letter code, command-name = what user says)
|
||||
- `description` - Must start with `[XX]` code
|
||||
- Handler - Either `action` (Simple/Expert) or `exec` (Module)
|
||||
|
||||
**Reserved codes (do NOT use):** MH, CH, PM, DA (auto-injected by compiler)
|
||||
|
||||
---
|
||||
|
||||
## Handler Types
|
||||
|
||||
### Action Handler
|
||||
|
||||
For Simple/Expert agents with self-contained operations.
|
||||
|
||||
```yaml
|
||||
# Reference prompt by ID
|
||||
- trigger: WC or fuzzy match on write-commit
|
||||
action: '#write-commit'
|
||||
description: '[WC] Write commit message'
|
||||
|
||||
# Direct inline instruction
|
||||
- trigger: QC or fuzzy match on quick-commit
|
||||
action: 'Generate commit message from diff'
|
||||
description: '[QC] Quick commit from diff'
|
||||
```
|
||||
|
||||
**When to use:** Simple/Expert agents. Use `#id` for complex multi-step prompts, inline text for simple operations.
|
||||
|
||||
### Workflow Handler
|
||||
|
||||
For module agents referencing external workflow files.
|
||||
|
||||
```yaml
|
||||
- trigger: CP or fuzzy match on create-prd
|
||||
exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'
|
||||
description: '[CP] Create Product Requirements Document'
|
||||
|
||||
- trigger: GB or fuzzy match on brainstorm
|
||||
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
|
||||
description: '[GB] Guided brainstorming session'
|
||||
|
||||
# Planned but unimplemented
|
||||
- trigger: FF or fuzzy match on future-feature
|
||||
exec: 'todo'
|
||||
description: '[FF] Coming soon'
|
||||
```
|
||||
|
||||
**When to use:** Module agents, multi-step workflows, complex processes. Use `exec: 'todo'` for unimplemented features.
|
||||
|
||||
### Data Parameter (Optional)
|
||||
|
||||
Add to ANY handler to pass files to the workflow/action.
|
||||
|
||||
```yaml
|
||||
- trigger: TS or fuzzy match on team-standup
|
||||
exec: '{project-root}/_bmad/bmm/tasks/team-standup.md'
|
||||
data: '{project-root}/_bmad/_config/agent-manifest.csv'
|
||||
description: '[TS] Run team standup'
|
||||
|
||||
- trigger: AM or fuzzy match on analyze-metrics
|
||||
action: 'Analyze these metrics for trends'
|
||||
data: '{project-root}/_data/metrics.json'
|
||||
description: '[AM] Analyze metrics'
|
||||
```
|
||||
|
||||
**When to use:** Workflow needs input file, action processes external data.
|
||||
|
||||
---
|
||||
|
||||
## Prompts Section
|
||||
|
||||
For Simple/Expert agents, define reusable prompts referenced by `action: '#id'`.
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: analyze-code
|
||||
content: |
|
||||
<instructions>Analyze code for patterns</instructions>
|
||||
<process>1. Identify structure 2. Check issues 3. Suggest improvements</process>
|
||||
|
||||
menu:
|
||||
- trigger: AC or fuzzy match on analyze-code
|
||||
action: '#analyze-code'
|
||||
description: '[AC] Analyze code patterns'
|
||||
```
|
||||
|
||||
**Common XML tags:** `<instructions>`, `<process>`, `<example>`, `<output_format>`
|
||||
|
||||
---
|
||||
|
||||
## Path Variables
|
||||
|
||||
**Always use variables, never hardcoded paths:**
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
|
||||
data: '{project-root}/_data/metrics.csv'
|
||||
|
||||
# ❌ WRONG
|
||||
exec: '../../../core/workflows/brainstorming/workflow.yaml'
|
||||
```
|
||||
|
||||
**Available variables:**
|
||||
- `{project-root}` - Project root directory
|
||||
- `{output_folder}` - Document output location
|
||||
- `{user_name}` - User's name from config
|
||||
- `{communication_language}` - Language preference
|
||||
|
||||
**Expert Agent sidecar paths:**
|
||||
```yaml
|
||||
# Agent YAML referencing sidecar files
|
||||
action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creation Thought Process
|
||||
|
||||
When creating menu items, follow this sequence:
|
||||
|
||||
1. **User capability** → "Check code for issues"
|
||||
2. **Choose code** → `LC` (Lint Code)
|
||||
3. **Write trigger** → `LC or fuzzy match on lint-code`
|
||||
4. **Choose handler** → `action` (inline is simple enough)
|
||||
5. **Write description** → `[LC] Lint code for issues`
|
||||
|
||||
Result:
|
||||
```yaml
|
||||
- trigger: LC or fuzzy match on lint-code
|
||||
action: 'Check code for common issues and anti-patterns'
|
||||
description: '[LC] Lint code for issues'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### Simple Agent Menu
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: format-code
|
||||
content: |
|
||||
<instructions>Format code to style guidelines</instructions>
|
||||
<process>1. Indentation 2. Spacing 3. Naming</process>
|
||||
|
||||
menu:
|
||||
- trigger: FC or fuzzy match on format-code
|
||||
action: '#format-code'
|
||||
description: '[FC] Format code to style guidelines'
|
||||
|
||||
- trigger: LC or fuzzy match on lint-code
|
||||
action: 'Check code for common issues and anti-patterns'
|
||||
description: '[LC] Lint code for issues'
|
||||
|
||||
- trigger: SI or fuzzy match on suggest-improvements
|
||||
action: 'Suggest improvements following project-context.md guidelines'
|
||||
description: '[SI] Suggest improvements'
|
||||
```
|
||||
|
||||
### Expert Agent Menu
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md'
|
||||
- 'ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/'
|
||||
|
||||
prompts:
|
||||
- id: guided-entry
|
||||
content: |
|
||||
<instructions>Guide through journal entry</instructions>
|
||||
|
||||
menu:
|
||||
- trigger: WE or fuzzy match on write-entry
|
||||
action: '#guided-entry'
|
||||
description: '[WE] Write journal entry'
|
||||
|
||||
- trigger: QC or fuzzy match on quick-capture
|
||||
action: 'Save entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md'
|
||||
description: '[QC] Quick capture'
|
||||
|
||||
- trigger: SM or fuzzy match on save-memory
|
||||
action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights'
|
||||
description: '[SM] Save session'
|
||||
```
|
||||
|
||||
### Module Agent Menu
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: WI or fuzzy match on workflow-init
|
||||
exec: '{project-root}/_bmad/bmm/workflows/workflow-status/workflow.md'
|
||||
description: '[WI] Initialize workflow path'
|
||||
|
||||
- trigger: BS or fuzzy match on brainstorm
|
||||
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
|
||||
description: '[BS] Guided brainstorming'
|
||||
|
||||
- trigger: CP or fuzzy match on create-prd
|
||||
exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'
|
||||
description: '[CP] Create PRD'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Patterns to Remember
|
||||
|
||||
1. **Triggers always:** `XX or fuzzy match on command-name`
|
||||
2. **Descriptions always:** `[XX] Display text`
|
||||
3. **Reserved codes:** MH, CH, PM, DA (never use)
|
||||
4. **Codes must be:** Unique within each agent
|
||||
5. **Paths always:** `{project-root}` variable, never relative
|
||||
6. **Expert sidecars:** `{project-root}/_bmad/_memory/{sidecar-folder}/`
|
||||
@@ -0,0 +1,236 @@
|
||||
# Expert Agent Architecture
|
||||
|
||||
Agents with a sidecar folder for persistent memory, custom workflows, and restricted file access.
|
||||
|
||||
---
|
||||
|
||||
## When to Use Expert Agents
|
||||
|
||||
- Must remember things across sessions
|
||||
- Personal knowledge base that grows over time
|
||||
- Domain-specific expertise with restricted file access
|
||||
- Learning/adapting over time
|
||||
- Complex multi-step workflows loaded on demand
|
||||
- User wants multiple instances with separate memories
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
{agent-name}/
|
||||
├── {agent-name}.agent.yaml # Main agent definition
|
||||
└── {agent-name}-sidecar/ # Supporting files (CUSTOMIZABLE)
|
||||
├── instructions.md # Startup protocols (common)
|
||||
├── memories.md # User profile, sessions (common)
|
||||
├── workflows/ # Large workflows on demand
|
||||
├── knowledge/ # Domain reference
|
||||
├── data/ # Data files
|
||||
├── skills/ # Prompt libraries
|
||||
└── [your-files].md # Whatever needed
|
||||
```
|
||||
|
||||
**Naming:**
|
||||
- Agent file: `{agent-name}.agent.yaml`
|
||||
- Sidecar folder: `{agent-name}-sidecar/`
|
||||
- Lowercase, hyphenated names
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL: Sidecar Path Format
|
||||
|
||||
At build/install, sidecar is copied to `{project-root}/_bmad/_memory/{sidecar-folder}/`
|
||||
|
||||
**ALL agent YAML references MUST use:**
|
||||
|
||||
```yaml
|
||||
{project-root}/_bmad/_memory/{sidecar-folder}/{file}
|
||||
```
|
||||
|
||||
- `{project-root}` = literal variable (keep as-is)
|
||||
- `{sidecar-folder}` = actual folder name (e.g., `journal-keeper-sidecar`)
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
critical_actions:
|
||||
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md"
|
||||
- "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/"
|
||||
|
||||
menu:
|
||||
- action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# ❌ WRONG
|
||||
critical_actions:
|
||||
- "Load ./journal-keeper-sidecar/memories.md"
|
||||
- "Load /Users/absolute/path/memories.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete YAML Structure
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: _bmad/agents/{agent-name}/{agent-name}.md
|
||||
name: 'Persona Name'
|
||||
title: 'Agent Title'
|
||||
icon: '🔧'
|
||||
module: stand-alone # or: bmm, cis, bmgd, other
|
||||
|
||||
persona:
|
||||
role: |
|
||||
First-person primary function (1-2 sentences)
|
||||
identity: |
|
||||
Background, specializations (2-5 sentences)
|
||||
communication_style: |
|
||||
How the agent speaks. Include memory reference patterns.
|
||||
principles:
|
||||
- Core belief or methodology
|
||||
- Another guiding principle
|
||||
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
|
||||
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
|
||||
|
||||
prompts:
|
||||
- id: main-action
|
||||
content: |
|
||||
<instructions>What this does</instructions>
|
||||
<process>1. Step one 2. Step two</process>
|
||||
|
||||
menu:
|
||||
- trigger: XX or fuzzy match on command
|
||||
action: '#main-action'
|
||||
description: '[XX] Command description'
|
||||
|
||||
- trigger: SM or fuzzy match on save
|
||||
action: 'Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md with insights'
|
||||
description: '[SM] Save session'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Details
|
||||
|
||||
### critical_actions (MANDATORY)
|
||||
|
||||
Become activation steps when compiled. Always include:
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
|
||||
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
|
||||
```
|
||||
|
||||
### Sidecar Files (Customizable)
|
||||
|
||||
**Common patterns:**
|
||||
- `instructions.md` - Startup protocols, domain boundaries
|
||||
- `memories.md` - User profile, session notes, patterns
|
||||
|
||||
**Fully customizable - add what your agent needs:**
|
||||
- `workflows/` - Large workflows for on-demand loading
|
||||
- `knowledge/` - Domain reference material
|
||||
- `data/` - Data files
|
||||
- `skills/` - Prompt libraries
|
||||
|
||||
**Template examples:** `{workflow_path}/templates/expert-agent-template/expert-agent-sidecar/`
|
||||
|
||||
### Menu Actions
|
||||
|
||||
All action types available, including sidecar updates:
|
||||
|
||||
```yaml
|
||||
# Prompt reference
|
||||
- trigger: XX or fuzzy match on command
|
||||
action: '#prompt-id'
|
||||
description: '[XX] Description'
|
||||
|
||||
# Inline that updates sidecar
|
||||
- trigger: SM or fuzzy match on save
|
||||
action: 'Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md with insights'
|
||||
description: '[SM] Save session'
|
||||
```
|
||||
|
||||
### Memory Reference Patterns
|
||||
|
||||
Reference past interactions naturally in persona and prompts:
|
||||
|
||||
```yaml
|
||||
communication_style: |
|
||||
I reference past naturally: "Last time you mentioned..." or "I've noticed patterns..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Domain Restriction Patterns
|
||||
|
||||
```yaml
|
||||
# Single folder (most common)
|
||||
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
|
||||
|
||||
# Read-only knowledge
|
||||
- 'Load from {project-root}/_bmad/_memory/{sidecar-folder}/knowledge/ but NEVER modify'
|
||||
- 'Write ONLY to {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
|
||||
|
||||
# User folder access
|
||||
- 'ONLY access files in {user-folder}/journals/ - private space'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What the Compiler Adds (DO NOT Include)
|
||||
|
||||
Compiler handles these automatically:
|
||||
|
||||
- Frontmatter (`---name/description---`)
|
||||
- XML activation block (your critical_actions become numbered steps)
|
||||
- Menu handlers (workflow, exec logic)
|
||||
- Auto-injected menu items (MH, CH, PM, DA)
|
||||
- Rules section
|
||||
|
||||
**See:** `agent-compilation.md` for compilation details.
|
||||
|
||||
---
|
||||
|
||||
## Reference Example
|
||||
|
||||
**Folder:** `{workflow_path}/data/reference/expert-examples/journal-keeper/`
|
||||
|
||||
**Features:**
|
||||
- First-person persona with memory reference patterns
|
||||
- critical_actions loading sidecar files
|
||||
- Menu items updating sidecar files
|
||||
- Proper `{project-root}/_bmad/_memory/` path format
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] Valid YAML syntax
|
||||
- [ ] All metadata present (id, name, title, icon, module)
|
||||
- [ ] **ALL paths use: `{project-root}/_bmad/_memory/{sidecar-folder}/...`**
|
||||
- [ ] `{project-root}` is literal
|
||||
- [ ] Sidecar folder name is actual name
|
||||
- [ ] `critical_actions` loads sidecar files
|
||||
- [ ] `critical_actions` enforces domain restrictions
|
||||
- [ ] Menu triggers: `XX or fuzzy match on command`
|
||||
- [ ] Menu descriptions have `[XX]` codes
|
||||
- [ ] No reserved codes (MH, CH, PM, DA)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **critical_actions MANDATORY** - Load sidecar files explicitly
|
||||
2. **Enforce domain restrictions** - Clear boundaries
|
||||
3. **Reference past naturally** - Don't dump memory
|
||||
4. **Design for growth** - Structure for accumulation
|
||||
5. **Separate concerns** - Memories, instructions, knowledge distinct
|
||||
6. **Include privacy** - Users trust with personal data
|
||||
7. **First-person voice** - In all persona elements
|
||||
@@ -21,9 +21,9 @@ agent:
|
||||
- Reflection transforms experience into wisdom
|
||||
|
||||
critical_actions:
|
||||
- "Load COMPLETE file ./journal-keeper-sidecar/memories.md and remember all past insights"
|
||||
- "Load COMPLETE file ./journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
|
||||
- "ONLY read/write files in ./journal-keeper-sidecar/ - this is our private space"
|
||||
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md and remember all past insights"
|
||||
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
|
||||
- "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/ - this is our private space"
|
||||
- "Track mood patterns, recurring themes, and breakthrough moments"
|
||||
- "Reference past entries naturally to show continuity"
|
||||
|
||||
@@ -116,38 +116,38 @@ agent:
|
||||
A week is long enough to see patterns, short enough to remember details.
|
||||
|
||||
menu:
|
||||
- trigger: write
|
||||
- trigger: WE or fuzzy match on write
|
||||
action: "#guided-entry"
|
||||
description: "Write today's journal entry"
|
||||
description: "[WE] Write today's journal entry"
|
||||
|
||||
- trigger: quick
|
||||
action: "Save a quick, unstructured entry to ./journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed"
|
||||
description: "Quick capture without prompts"
|
||||
- trigger: QC or fuzzy match on quick
|
||||
action: "Save a quick, unstructured entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed"
|
||||
description: "[QC] Quick capture without prompts"
|
||||
|
||||
- trigger: mood
|
||||
- trigger: MC or fuzzy match on mood
|
||||
action: "#mood-check"
|
||||
description: "Track your current emotional state"
|
||||
description: "[MC] Track your current emotional state"
|
||||
|
||||
- trigger: patterns
|
||||
- trigger: PR or fuzzy match on patterns
|
||||
action: "#pattern-reflection"
|
||||
description: "See patterns in your recent entries"
|
||||
description: "[PR] See patterns in your recent entries"
|
||||
|
||||
- trigger: gratitude
|
||||
- trigger: GM or fuzzy match on gratitude
|
||||
action: "#gratitude-moment"
|
||||
description: "Capture today's gratitudes"
|
||||
description: "[GM] Capture today's gratitudes"
|
||||
|
||||
- trigger: weekly
|
||||
- trigger: WR or fuzzy match on weekly
|
||||
action: "#weekly-reflection"
|
||||
description: "Reflect on the past week"
|
||||
description: "[WR] Reflect on the past week"
|
||||
|
||||
- trigger: insight
|
||||
action: "Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md with date and significance"
|
||||
description: "Record a meaningful insight"
|
||||
- trigger: IB or fuzzy match on insight
|
||||
action: "Document this breakthrough in {project-root}/_bmad/_memory/journal-keeper-sidecar/breakthroughs.md with date and significance"
|
||||
description: "[IB] Record a meaningful insight"
|
||||
|
||||
- trigger: read-back
|
||||
action: "Load and share entries from ./journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth"
|
||||
description: "Review past entries"
|
||||
- trigger: RE or fuzzy match on read-back
|
||||
action: "Load and share entries from {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth"
|
||||
description: "[RE] Review past entries"
|
||||
|
||||
- trigger: save
|
||||
action: "Update ./journal-keeper-sidecar/memories.md with today's session insights and emotional markers"
|
||||
description: "Save what we discussed today"
|
||||
- trigger: SM or fuzzy match on save
|
||||
action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with today's session insights and emotional markers"
|
||||
description: "[SM] Save what we discussed today"
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# Architect Agent Definition
|
||||
|
||||
agent:
|
||||
metadata:
|
||||
id: "_bmad/bmm/agents/architect.md"
|
||||
name: Winston
|
||||
title: Architect
|
||||
icon: 🏗️
|
||||
module: bmm
|
||||
|
||||
persona:
|
||||
role: System Architect + Technical Design Leader
|
||||
identity: Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.
|
||||
communication_style: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
|
||||
principles: |
|
||||
- User journeys drive technical decisions. Embrace boring technology for stability.
|
||||
- Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact.
|
||||
- Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`
|
||||
|
||||
menu:
|
||||
- trigger: WS or fuzzy match on workflow-status
|
||||
workflow: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
description: "[WS] Get workflow status or initialize a workflow if not already done (optional)"
|
||||
|
||||
- trigger: CA or fuzzy match on create-architecture
|
||||
exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
|
||||
description: "[CA] Create an Architecture Document"
|
||||
|
||||
- trigger: IR or fuzzy match on implementation-readiness
|
||||
exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
|
||||
description: "[IR] Implementation Readiness Review"
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: "architect"
|
||||
description: "Architect"
|
||||
---
|
||||
|
||||
You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
|
||||
|
||||
```xml
|
||||
<agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
|
||||
<activation critical="MANDATORY">
|
||||
<step n="1">Load persona from this current agent file (already in context)</step>
|
||||
<step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
|
||||
- Load and read {project-root}/_bmad/bmm/config.yaml NOW
|
||||
- Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
|
||||
- VERIFY: If config not loaded, STOP and report error to user
|
||||
- DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
|
||||
</step>
|
||||
<step n="3">Remember: user's name is {user_name}</step>
|
||||
|
||||
<step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
|
||||
<step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
|
||||
<step n="6">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
|
||||
<step n="7">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
|
||||
|
||||
<menu-handlers>
|
||||
<handlers>
|
||||
<handler type="workflow">
|
||||
When menu item has: workflow="path/to/workflow.yaml":
|
||||
|
||||
1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
|
||||
2. Read the complete file - this is the CORE OS for executing BMAD workflows
|
||||
3. Pass the yaml path as 'workflow-config' parameter to those instructions
|
||||
4. Execute workflow.xml instructions precisely following all steps
|
||||
5. Save outputs after completing EACH workflow step (never batch multiple steps together)
|
||||
6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
|
||||
</handler>
|
||||
<handler type="exec">
|
||||
When menu item or handler has: exec="path/to/file.md":
|
||||
1. Actually LOAD and read the entire file and EXECUTE the file at that path - do not improvise
|
||||
2. Read the complete file and follow all instructions within it
|
||||
3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
|
||||
</handler>
|
||||
</handlers>
|
||||
</menu-handlers>
|
||||
|
||||
<rules>
|
||||
<r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
|
||||
<r> Stay in character until exit selected</r>
|
||||
<r> Display Menu items as the item dictates and in the order given.</r>
|
||||
<r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
|
||||
</rules>
|
||||
</activation> <persona>
|
||||
<role>System Architect + Technical Design Leader</role>
|
||||
<identity>Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.</identity>
|
||||
<communication_style>Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works.</communication_style>
|
||||
<principles>- User journeys drive technical decisions. Embrace boring technology for stability. - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</principles>
|
||||
</persona>
|
||||
<menu>
|
||||
<item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
|
||||
<item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
|
||||
<item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
|
||||
<item cmd="CA or fuzzy match on create-architecture" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md">[CA] Create an Architecture Document</item>
|
||||
<item cmd="IR or fuzzy match on implementation-readiness" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md">[IR] Implementation Readiness Review</item>
|
||||
<item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
|
||||
<item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
|
||||
</menu>
|
||||
</agent>
|
||||
```
|
||||
@@ -97,30 +97,30 @@ agent:
|
||||
</example>
|
||||
|
||||
menu:
|
||||
- trigger: write
|
||||
- trigger: WC or fuzzy match on write
|
||||
action: "#write-commit"
|
||||
description: "Craft a commit message for your changes"
|
||||
description: "[WC] Craft a commit message for your changes"
|
||||
|
||||
- trigger: analyze
|
||||
- trigger: AC or fuzzy match on analyze
|
||||
action: "#analyze-changes"
|
||||
description: "Analyze changes before writing the message"
|
||||
description: "[AC] Analyze changes before writing the message"
|
||||
|
||||
- trigger: improve
|
||||
- trigger: IM or fuzzy match on improve
|
||||
action: "#improve-message"
|
||||
description: "Improve an existing commit message"
|
||||
description: "[IM] Improve an existing commit message"
|
||||
|
||||
- trigger: batch
|
||||
- trigger: BC or fuzzy match on batch
|
||||
action: "#batch-commits"
|
||||
description: "Create cohesive messages for multiple commits"
|
||||
description: "[BC] Create cohesive messages for multiple commits"
|
||||
|
||||
- trigger: conventional
|
||||
- trigger: CC or fuzzy match on conventional
|
||||
action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: <type>(<scope>): <subject>"
|
||||
description: "Specifically use conventional commit format"
|
||||
description: "[CC] Use conventional commit format"
|
||||
|
||||
- trigger: story
|
||||
- trigger: SC or fuzzy match on story
|
||||
action: "Write a narrative commit that tells the journey: Setup → Conflict → Solution → Impact"
|
||||
description: "Write commit as a narrative story"
|
||||
description: "[SC] Write commit as a narrative story"
|
||||
|
||||
- trigger: haiku
|
||||
- trigger: HC or fuzzy match on haiku
|
||||
action: "Write a haiku commit (5-7-5 syllables) capturing the essence of the change"
|
||||
description: "Compose a haiku commit message"
|
||||
description: "[HC] Compose a haiku commit message"
|
||||
|
||||
@@ -0,0 +1,204 @@
|
||||
# Simple Agent Architecture
|
||||
|
||||
Self-contained agents in a single YAML file. No external dependencies, no persistent memory.
|
||||
|
||||
---
|
||||
|
||||
## When to Use Simple Agents
|
||||
|
||||
- Single-purpose utilities (commit helper, formatter, validator)
|
||||
- Stateless operations (each run is independent)
|
||||
- All logic fits in ~250 lines
|
||||
- Menu handlers are short prompts or inline text
|
||||
- No need to remember past sessions
|
||||
|
||||
---
|
||||
|
||||
## Complete YAML Structure
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: _bmad/agents/{agent-name}/{agent-name}.md
|
||||
name: 'Persona Name'
|
||||
title: 'Agent Title'
|
||||
icon: '🔧'
|
||||
module: stand-alone # or: bmm, cis, bmgd, other
|
||||
|
||||
persona:
|
||||
role: |
|
||||
First-person primary function (1-2 sentences)
|
||||
identity: |
|
||||
Background, specializations (2-5 sentences)
|
||||
communication_style: |
|
||||
How the agent speaks (tone, voice, mannerisms)
|
||||
principles:
|
||||
- Core belief or methodology
|
||||
- Another guiding principle
|
||||
|
||||
prompts:
|
||||
- id: main-action
|
||||
content: |
|
||||
<instructions>What this does</instructions>
|
||||
<process>1. Step one 2. Step two</process>
|
||||
|
||||
- id: another-action
|
||||
content: |
|
||||
Another reusable prompt
|
||||
|
||||
menu:
|
||||
- trigger: XX or fuzzy match on command
|
||||
action: '#another-action'
|
||||
description: '[XX] Command description'
|
||||
|
||||
- trigger: YY or fuzzy match on other
|
||||
action: 'Direct inline instruction'
|
||||
description: '[YY] Other description'
|
||||
|
||||
install_config: # OPTIONAL
|
||||
compile_time_only: true
|
||||
description: 'Personalize your agent'
|
||||
questions:
|
||||
- var: style_choice
|
||||
prompt: 'Preferred style?'
|
||||
type: choice
|
||||
options:
|
||||
- label: 'Professional'
|
||||
value: 'professional'
|
||||
- label: 'Casual'
|
||||
value: 'casual'
|
||||
default: 'professional'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Details
|
||||
|
||||
### Metadata
|
||||
|
||||
| Field | Purpose | Example |
|
||||
|-------|---------|---------|
|
||||
| `id` | Compiled path | `_bmad/agents/commit-poet/commit-poet.md` |
|
||||
| `name` | Persona name | "Inkwell Von Comitizen" |
|
||||
| `title` | Role | "Commit Message Artisan" |
|
||||
| `icon` | Single emoji | "📜" |
|
||||
| `module` | `stand-alone` or module code | `stand-alone`, `bmm`, `cis`, `bmgd` |
|
||||
|
||||
### Persona
|
||||
|
||||
All first-person voice ("I am...", "I do..."):
|
||||
|
||||
```yaml
|
||||
role: "I am a Commit Message Artisan..."
|
||||
identity: "I understand commit messages are documentation..."
|
||||
communication_style: "Poetic drama with flair..."
|
||||
principles:
|
||||
- "Every commit tells a story - capture the why"
|
||||
```
|
||||
|
||||
### Prompts with IDs
|
||||
|
||||
Reusable templates referenced via `#id`:
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: write-commit
|
||||
content: |
|
||||
<instructions>What this does</instructions>
|
||||
<process>1. Step 2. Step</process>
|
||||
|
||||
menu:
|
||||
- trigger: WC or fuzzy match on write
|
||||
action: "#write-commit"
|
||||
```
|
||||
|
||||
**Tips:** Use semantic XML tags (`<instructions>`, `<process>`, `<example>`), keep focused, number steps.
|
||||
|
||||
### Menu Actions
|
||||
|
||||
Two forms:
|
||||
|
||||
1. **Prompt reference:** `action: "#prompt-id"`
|
||||
2. **Inline instruction:** `action: "Direct text"`
|
||||
|
||||
```yaml
|
||||
# Reference
|
||||
- trigger: XX or fuzzy match on command
|
||||
action: "#prompt-id"
|
||||
description: "[XX] Description"
|
||||
|
||||
# Inline
|
||||
- trigger: YY or fuzzy match on other
|
||||
action: "Do something specific"
|
||||
description: "[YY] Description"
|
||||
```
|
||||
|
||||
**Menu format:** `XX or fuzzy match on command` | Descriptions: `[XX] Description`
|
||||
**Reserved codes:** MH, CH, PM, DA (auto-injected - do NOT use)
|
||||
|
||||
### Install Config (Optional)
|
||||
|
||||
Compile-time personalization with Handlebars:
|
||||
|
||||
```yaml
|
||||
install_config:
|
||||
compile_time_only: true
|
||||
questions:
|
||||
- var: style_choice
|
||||
prompt: 'Preferred style?'
|
||||
type: choice
|
||||
options: [...]
|
||||
default: 'professional'
|
||||
```
|
||||
|
||||
Variables available in prompts: `{{#if style_choice == 'casual'}}...{{/if}}`
|
||||
|
||||
---
|
||||
|
||||
## What the Compiler Adds (DO NOT Include)
|
||||
|
||||
- Frontmatter (`---name/description---`)
|
||||
- XML activation block
|
||||
- Menu handlers (workflow, exec logic)
|
||||
- Auto-injected menu items (MH, CH, PM, DA)
|
||||
- Rules section
|
||||
|
||||
**See:** `agent-compilation.md` for details.
|
||||
|
||||
---
|
||||
|
||||
## Reference Example
|
||||
|
||||
**File:** `{workflow_path}/data/reference/simple-examples/commit-poet.agent.yaml`
|
||||
|
||||
**Features:** Poetic persona, 4 prompts, 7 menu items, proper `[XX]` codes
|
||||
|
||||
**Line count:** 127 lines (within ~250 line guideline)
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] Valid YAML syntax
|
||||
- [ ] All metadata present (id, name, title, icon, module)
|
||||
- [ ] Persona complete (role, identity, communication_style, principles)
|
||||
- [ ] Prompt IDs are unique
|
||||
- [ ] Menu triggers: `XX or fuzzy match on command`
|
||||
- [ ] Menu descriptions have `[XX]` codes
|
||||
- [ ] No reserved codes (MH, CH, PM, DA)
|
||||
- [ ] File named `{agent-name}.agent.yaml`
|
||||
- [ ] Under ~250 lines
|
||||
- [ ] No external dependencies
|
||||
- [ ] No `critical_actions` (Expert only)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **First-person voice** in all persona elements
|
||||
2. **Focused prompts** - one clear purpose each
|
||||
3. **Semantic XML tags** (`<instructions>`, `<process>`, `<example>`)
|
||||
4. **Handlebars** for personalization (if using install_config)
|
||||
5. **Sensible defaults** in install_config
|
||||
6. **Numbered steps** in multi-step prompts
|
||||
7. **Keep under ~250 lines** for maintainability
|
||||
@@ -1,180 +1,222 @@
|
||||
# Understanding Agent Types: Simple VS Expert VS Module
|
||||
|
||||
## ALL agent types can:
|
||||
> **For the LLM running this workflow:** Load and review the example files referenced below when helping users choose an agent type.
|
||||
> - Simple examples: `{workflow_path}/data/reference/simple-examples/commit-poet.agent.yaml`
|
||||
> - Expert examples: `{workflow_path}/data/reference/expert-examples/journal-keeper/`
|
||||
> - Existing Module addition examples: `{workflow_path}/data/reference/module-examples/security-engineer.agent.yaml`
|
||||
|
||||
- Read, Use and Write to loaded variables destinations
|
||||
- Example module variables {output_folder}, {communication_language}, {user_preference_foo}, etc..
|
||||
- Update created artifacts and files
|
||||
Execute commands and take actions
|
||||
- Invoke external tools
|
||||
- Optionally restrict what the agent can and cannot read or modify.
|
||||
- Example, a performance review agent may only have access to read from a employee data folder and write to a performance eval folder
|
||||
- All Agent types can use anything available in the core module and their menu items will offer them as option upon build automatically, including party-mode (group agent chat), agent chat mode and the ability to integrate advanced elicitation and brainstorming.
|
||||
---
|
||||
|
||||
## The Difference Between the 3 types
|
||||
## What ALL Agent Types Can Do
|
||||
|
||||
All three types have equal capability. The difference is **architecture and integration**, NOT power.
|
||||
|
||||
- Read, write, and update files
|
||||
- Execute commands and invoke tools
|
||||
- Load and use module variables
|
||||
- Optionally restrict file access (privacy/security)
|
||||
- Use core module features: party-mode, agent chat, advanced elicitation, brainstorming, document sharding
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Decision Tree
|
||||
|
||||
**Step 1: Single Agent or Multiple Agents?**
|
||||
|
||||
```
|
||||
Multiple personas/roles OR multi-user OR mixed data scope?
|
||||
├── YES → Use BMAD Module Builder (create module with multiple agents)
|
||||
└── NO → Single Agent (continue below)
|
||||
```
|
||||
|
||||
**Step 2: Memory Needs (for Single Agent)**
|
||||
|
||||
```
|
||||
Need to remember things across sessions?
|
||||
├── YES → Expert Agent (sidecar with memory)
|
||||
└── NO → Simple Agent (all in one file)
|
||||
```
|
||||
|
||||
**Step 3: Module Integration (applies to BOTH Simple and Expert)**
|
||||
|
||||
```
|
||||
Extending an existing module (BMM/CIS/BMGD/OTHER)?
|
||||
├── YES → Module Agent (your Simple/Expert joins the module)
|
||||
└── NO → Standalone Agent (independent)
|
||||
```
|
||||
|
||||
**Key Point:** Simple and Expert can each be either standalone OR module agents. Memory and module integration are independent decisions.
|
||||
|
||||
---
|
||||
|
||||
## The Three Types
|
||||
|
||||
### Simple Agent
|
||||
|
||||
- Everything the agent needs to know to be useful is in the single file
|
||||
- No External Skills or Workflows
|
||||
- No persistent memory
|
||||
- Specialized Knowledge needed will not change frequently
|
||||
- each agent menu item handler can be described in a few sentence prompt or a short 5-15 line prompt loaded in the same file.
|
||||
- Generally rely on minimal specification of actions it can take, relying on the LLM agent to fill in the blanks.
|
||||
- All specialized knowledge can be self contained in the agent file, still keeping the overall size of the file less than about 250 lines.
|
||||
**Everything in one file. No external dependencies. No memory.**
|
||||
|
||||
<examples type=simple-agent>
|
||||
- Comedian Joke Agent - has a funny or interesting persona, stays in character, offers some menu options for telling jokes or helping user craft jokes, all with prompts for those items being small, with the whole file being less than 250 lines.
|
||||
- Specific Type of Document Creation and Review Agent - persona matches the features you would like in this real. Much of the knowledge about the types of documents you will create and review are common LLM knowledge, document creation and review guardrails you would like to add will not change frequently and can be expressed in under 30-40 lines.
|
||||
- ./reference/simple-examples/commit-poet.agent.yaml
|
||||
</examples>
|
||||
```
|
||||
agent-name.agent.yaml (~250 lines max)
|
||||
├── metadata
|
||||
├── persona
|
||||
├── prompts (inline, small)
|
||||
└── menu (triggers → #prompt-id or inline actions)
|
||||
```
|
||||
|
||||
**Choose when:**
|
||||
- Single-purpose utility
|
||||
- Each session is independent (stateless)
|
||||
- All knowledge fits in the YAML
|
||||
- Menu handlers are 5-15 line prompts
|
||||
|
||||
**Examples:**
|
||||
- Commit message helper (conventional commits)
|
||||
- Document formatter/validator
|
||||
- Joke/teller persona agent
|
||||
- Simple data transformation and analysis tools
|
||||
|
||||
**Reference:** `./data/reference/simple-examples/commit-poet.agent.yaml`
|
||||
|
||||
---
|
||||
|
||||
### Expert Agent
|
||||
|
||||
- Includes all capabilities and features of Simple Agent, but adds a sidecar folder to allow for:
|
||||
- Custom Workflow, Prompts and Skill available to load on demand.
|
||||
- This allows for potentially very large multi step multi file workflows that can be only loaded when the user requests them. This keeps the agent and context overhead lean.
|
||||
- Persistent memory - agent can load a log every time on startup to know what has transpired or has been learned from past sessions
|
||||
- Persistent Memory can allow for agents to grown, evolve and even change personality or capabilities over time
|
||||
- Custom Data and Knowledge files that can be accessed and loaded on demand.
|
||||
**Sidecar folder with persistent memory, workflows, knowledge files.**
|
||||
|
||||
<examples type=complex-agent>
|
||||
- Journal Keeper Agent
|
||||
- ./data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml
|
||||
- ./data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/*.*
|
||||
- When starting the Journal Keeper, it greets you, remembers past sessions offering to continue one, discuss the past, or start new.
|
||||
- When working with you on new journals, will offer insights based on previous discussions, memories and journal entries.
|
||||
```
|
||||
agent-name.agent.yaml
|
||||
└── agent-name-sidecar/
|
||||
├── memories.md # User profile, session history, patterns
|
||||
├── instructions.md # Protocols, boundaries, startup behavior
|
||||
├── [custom-files].md # Breakthroughs, goals, tracking, etc.
|
||||
├── workflows/ # Large workflows loaded on demand
|
||||
└── knowledge/ # Domain reference material
|
||||
```
|
||||
|
||||
- Tax Expert
|
||||
- Agent is specialized to your specific tax needs
|
||||
- Has a sidecar folder of specific tax forms
|
||||
- Retains records of past guidance or rules you have given it to further augment its capabilities
|
||||
**Choose when:**
|
||||
- Must remember across sessions
|
||||
- User might create multiple instances each with own memory of actions (such as 2 different developers agents)
|
||||
- Personal knowledge base that grows
|
||||
- Learning/evolving over time
|
||||
- Domain-specific with restricted file access
|
||||
- Complex multi-step workflows
|
||||
|
||||
- Your Specific Job Augmentation Expert
|
||||
- Known the many aspects of your specific job and can help with many functions and asks to augment your day and responsibilities
|
||||
- Knows about your past meetings and highlights
|
||||
- Knows about who you work with and interact with, offering suggestions
|
||||
- Has workflows that help automate or help with very specific job functions you have
|
||||
- Can help with research while already having context about your role, company, specific product or job function
|
||||
- Can track and help you compile year end or quarterly achievements to help with year end reviews, promotions etc...
|
||||
**Examples:**
|
||||
- Journal companion (remembers mood patterns, past entries)
|
||||
- Personal job augmentation agent (knows your role, meetings, projects)
|
||||
- Therapy/health tracking (progress, goals, insights)
|
||||
- Domain advisor with custom knowledge base
|
||||
|
||||
- Therapy Agent
|
||||
- Can be similar to the Journal Keeper, but have menu items for various techniques or areas to cover - data and output memories are all retained in local files so you can have access to and analyze past sessions.
|
||||
</examples>
|
||||
**Reference:** `./data/reference/expert-examples/journal-keeper/`
|
||||
|
||||
**Required critical_actions:**
|
||||
```yaml
|
||||
critical_actions:
|
||||
- "Load COMPLETE file ./sidecar/memories.md"
|
||||
- "Load COMPLETE file ./sidecar/instructions.md"
|
||||
- "ONLY read/write files in ./sidecar/ - private space"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Module Agent
|
||||
|
||||
- As teh capabilities and what a single agent can do grows - it might make sense to consider instead creating a module with the bmad builders module workflow and split up multiple agents instead of 1 massive agent that tries to be every role and persona and do it all. Another option is that an existing module has a gap, and it makes sense to allow a new agent to be integrated with that module.
|
||||
- Module agents are able to do EVERYTHING the prior agent types had, including side cars and memory - but additionally can utilize global module workflows. This basically means that there are workflows or skills that can be used that the user might also choose to just run on their own, or other agents might use them.
|
||||
Two distinct purposes:
|
||||
|
||||
<examples>
|
||||
- ./data/reference/module-examples/security-engineer.agent.yaml
|
||||
- This is a module agent a user might create to add on to the existing BMad Method Module (bmm) - the bmad method module is all about agents and workflows working together dedicated to ideating and building software solutions through agile processes. There is already an Analyst, PM, Architect and Dev Agent. But the user might identify the need for a security-engineer.agent.yaml. So by creating this as a module agent for an existing module, a user can choose to install this and gain all capabilities of the bmad method itself - and also build this agent to user or even require inputs to or output from other agents. For example, this agent might require as input to produce a security review report, an architecture document produced by the bmm architecture agent.
|
||||
</examples>
|
||||
#### 1. Extend an Existing Module
|
||||
|
||||
## The Same Agent, Three Ways
|
||||
Add an agent to BMM, CIS, BMGD, or another existing module.
|
||||
|
||||
**Scenario:** Code Generator Agent
|
||||
**Choose when:**
|
||||
- Adding specialized capability to existing module ecosystem
|
||||
- Agent uses/contributes shared module workflows
|
||||
- Coordinates with other agents in the module
|
||||
- Input/output dependencies on other module agents
|
||||
|
||||
### As Simple Agent
|
||||
**Example:** Adding `security-engineer.agent.yaml` to BMM (software dev module)
|
||||
- Requires architecture document from BMM architect agent
|
||||
- Contributes security review workflow to BMM
|
||||
- Coordinates with analyst, pm, architect, dev agents
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: +_bmad/my-custom-agents/code-gen.agent.md"
|
||||
name: Randy Moss
|
||||
title: "Code Gen Expert"
|
||||
icon: "📔"
|
||||
module: stand-alone
|
||||
**Reference:** `./data/reference/module-examples/security-engineer.agent.yaml`
|
||||
|
||||
prompts:
|
||||
- id: code-generate
|
||||
content: |
|
||||
Ask user for spec details. Generate code.
|
||||
Write to {output_folder}/generated/
|
||||
#### 2. Signal Need for Custom Module
|
||||
|
||||
menu:
|
||||
- trigger: GC or fuzzy match on code-generate
|
||||
action: '#code-generate'
|
||||
description: "[GC] Generate code from spec"
|
||||
```
|
||||
When requirements exceed single-agent scope, suggest the user **use BMAD Module Builder** instead.
|
||||
|
||||
### As Expert Agent
|
||||
**Signals:**
|
||||
- "I need an HR agent, sales agent, F&I agent, and training coach..."
|
||||
- "Some info is global/shared across users, some is private per user..."
|
||||
- "Many workflows, skills, tools, and platform integrations..."
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: "_bmad/my-custom-agents/code-gen.agent.md"
|
||||
name: Randy Moss
|
||||
title: "Code Gen Expert"
|
||||
icon: "📔"
|
||||
module: stand-alone
|
||||
hasSidecar: true
|
||||
**Example:** Car Dealership Module
|
||||
- Multiple specialized agents (sales-trainer, service-advisor, sales-manager, F&I)
|
||||
- Shared workflows (VIN lookup, vehicle research)
|
||||
- Global knowledge base + per-user private sidecars
|
||||
- Multi-user access patterns
|
||||
|
||||
critical_actions:
|
||||
- Load my coding standards from ./code-gen-sidecar/knowledge/
|
||||
- Load memories from ./code-gen-sidecar/memories.md
|
||||
- RESTRICT: Only operate within sidecar folder
|
||||
|
||||
menu:
|
||||
- trigger: GC or fuzzy match on code-generate
|
||||
exec: './code-gen-sidecar/workflows/code-gen/workflow.md'
|
||||
description: "[GC] Generate code from spec"
|
||||
```
|
||||
**→ Use BMAD Module Builder workflow to create the module, then create individual agents within it.**
|
||||
|
||||
### As Module Agent (Architecture: Team integration)
|
||||
---
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: "_bmad/bmm/code-gen.agent.md"
|
||||
name: Randy Moss
|
||||
title: "Code Gen Expert"
|
||||
icon: "📔"
|
||||
module: bmm
|
||||
hasSidecar: true
|
||||
## Side-by-Side Comparison
|
||||
|
||||
menu:
|
||||
- trigger: implement-story
|
||||
workflow: '_bmad/bmm/workflows/dev-story/workflow.yaml'
|
||||
description: Implement user story
|
||||
| Aspect | Simple | Expert |
|
||||
| ----------------- | ------------------------ | ------------------------------ |
|
||||
| File structure | Single YAML (~250 lines) | YAML + sidecar/ (150+ + files) |
|
||||
| Persistent memory | No | Yes |
|
||||
| Custom workflows | Inline prompts | Sidecar workflows (on-demand) |
|
||||
| File access | Project/output | Restricted domain |
|
||||
| Integration | Standalone OR Module | Standalone OR Module |
|
||||
|
||||
- trigger: refactor
|
||||
workflow: '_bmad/bmm/workflows/refactor/workflow.yaml'
|
||||
description: Refactor codebase
|
||||
```
|
||||
**Note:** BOTH Simple and Expert can be either standalone agents OR module agents (extending BMM/CIS/BMGD/etc.). Module integration is independent of memory needs.
|
||||
|
||||
## Choosing Your Agent Type
|
||||
---
|
||||
|
||||
### Choose Simple when:
|
||||
## Selection Checklist
|
||||
|
||||
- Single-purpose utility (no memory needed)
|
||||
- Stateless operations (each run is independent)
|
||||
- Self-contained logic (everything in YAML and total file size < )
|
||||
- No persistent context required
|
||||
**Choose Simple if:**
|
||||
- [ ] One clear purpose
|
||||
- [ ] No need to remember past sessions
|
||||
- [ ] All logic fits in ~250 lines
|
||||
- [ ] Each interaction is independent
|
||||
|
||||
### Choose Expert when:
|
||||
**Choose Expert if:**
|
||||
- [ ] Needs memory across sessions
|
||||
- [ ] Personal knowledge base
|
||||
- [ ] Domain-specific expertise
|
||||
- [ ] Restricted file access for privacy
|
||||
- [ ] Learning/evolving over time
|
||||
- [ ] Complex workflows in sidecar
|
||||
|
||||
- Need to remember things across sessions
|
||||
- Personal knowledge base (user preferences, domain data)
|
||||
- Domain-specific expertise with restricted scope
|
||||
- Learning/adapting over time
|
||||
- Complex multi-step workflows and actions that need to be explicitly set
|
||||
**Then, for EITHER Simple or Expert:**
|
||||
- [ ] Extending existing module (BMM/CIS/BMGD/etc.) → Make it a Module Agent
|
||||
- [ ] Independent operation → Keep it Standalone
|
||||
|
||||
### Choose Module when:
|
||||
**Escalate to Module Builder if:**
|
||||
- [ ] Multiple distinct personas needed (not one swiss-army-knife agent)
|
||||
- [ ] Many specialized workflows required
|
||||
- [ ] Multiple users with mixed data scope
|
||||
- [ ] Shared resources across agents
|
||||
- [ ] Future platform integrations planned
|
||||
|
||||
- Designed FOR a specific module ecosystem (BMM, CIS, etc.)
|
||||
- Uses or contributes that module's workflows
|
||||
- Coordinates with other module agents
|
||||
- Will be included in module's default bundle
|
||||
- Part of professional team infrastructure
|
||||
---
|
||||
|
||||
## Final Selection Tips.
|
||||
## Tips for the LLM Facilitator
|
||||
|
||||
- If user is unsure between Simple or Expert - User the Expert Agent, its more performant.
|
||||
- If an agent sounds like it would benefit from multiple personas, skill sets and many workflows - suggest the user create a module - if not though, most likely an expert agent.
|
||||
- If any capabilities of an agent rely on details sequenced skills or workflows, use an expert instead of simple.
|
||||
- If the agent has capabilities that rely on inputs or outputs to and from agents or workflows in another module, suggest an expert-module or simple-module agent.
|
||||
- When adding to a module, the distinction of using simple for expert for the agent being added or used with a module is will it need private memory and learning/evolving capabilities.
|
||||
- If unsure between Simple or Expert → **recommend Expert** (more flexible)
|
||||
- Multiple personas/skills → **suggest Module Builder**, not one giant agent
|
||||
- Ask about: memory needs, user count, data scope (global vs private), integration plans
|
||||
- Load example files when user wants to see concrete implementations
|
||||
- Reference examples to illustrate differences
|
||||
|
||||
All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system.
|
||||
---
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
All three types are equally powerful. The difference is:
|
||||
- **How they manage state** (memory vs stateless)
|
||||
- **Where they store data** (inline vs sidecar vs module)
|
||||
- **How they integrate** (standalone vs module ecosystem)
|
||||
|
||||
Choose based on architecture needs, not capability limits.
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# {{Agent Name}} Core Directives
|
||||
|
||||
> This is a TEMPLATE FILE showing one possible pattern.
|
||||
> Sidecar content is FULLY CUSTOMIZABLE - create what your agent needs.
|
||||
|
||||
## STARTUP PROTOCOL
|
||||
|
||||
1. Load sidecar files that contain memory/context
|
||||
2. Check for patterns from previous sessions
|
||||
3. Greet with awareness of past interactions
|
||||
|
||||
## CORE PRINCIPLES
|
||||
|
||||
- Maintain character consistency
|
||||
- Domain boundaries: {{SPECIFIC_DOMAIN}}
|
||||
- Access restrictions: Only sidecar folder
|
||||
|
||||
## SPECIAL RULES
|
||||
|
||||
<!-- Add agent-specific protocols here -->
|
||||
@@ -0,0 +1,18 @@
|
||||
# {{Agent Name}} Memory Bank
|
||||
|
||||
> This is a TEMPLATE FILE showing one possible pattern.
|
||||
> Sidecar content is FULLY CUSTOMIZABLE - create what your agent needs.
|
||||
|
||||
## User Profile
|
||||
|
||||
- Name: {{user_name}}
|
||||
- Started: {{START_DATE}}
|
||||
- Preferences: {{LEARNED_FROM_INTERACTIONS}}
|
||||
|
||||
## Session Notes
|
||||
|
||||
### {{DATE}} - {{SESSION_FOCUS}}
|
||||
|
||||
- Main topics: {{WHAT_CAME_UP}}
|
||||
- Patterns noticed: {{OBSERVATIONS}}
|
||||
- For next time: {{WHAT_TO_REMEMBER}}
|
||||
@@ -0,0 +1,76 @@
|
||||
{{#if comment}}
|
||||
------------------------------------------------------------------------------
|
||||
Expert Agent Handlebars Template
|
||||
Used by: step-06-build.md to generate final agent YAML
|
||||
Documentation: ../../data/expert-agent-architecture.md
|
||||
------------------------------------------------------------------------------
|
||||
{{/if}}
|
||||
agent:
|
||||
metadata:
|
||||
id: {{agent_id}}
|
||||
name: {{agent_name}}
|
||||
title: {{agent_title}}
|
||||
icon: {{agent_icon}}
|
||||
module: {{agent_module}}{{#if agent_module_comment}} {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}}
|
||||
|
||||
persona:
|
||||
role: |
|
||||
{{persona_role}}{{#if persona_role_note}}
|
||||
{{!-- 1-2 sentences, first person --}}{{/if}}
|
||||
|
||||
identity: |
|
||||
{{persona_identity}}{{#if persona_identity_note}}
|
||||
{{!-- 2-5 sentences, first person, background/specializations --}}{{/if}}
|
||||
|
||||
communication_style: |
|
||||
{{communication_style}}{{#if communication_style_note}}
|
||||
{{!-- How the agent speaks, include memory reference patterns --}}{{/if}}
|
||||
|
||||
principles:
|
||||
{{#each principles}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
critical_actions:
|
||||
{{#each critical_actions}}
|
||||
- '{{{this}}}'
|
||||
{{/each}}
|
||||
|
||||
{{#if has_prompts}}
|
||||
prompts:
|
||||
{{#each prompts}}
|
||||
- id: {{id}}
|
||||
content: |
|
||||
{{{content}}}
|
||||
{{/each}}
|
||||
{{/if}}
|
||||
|
||||
menu:
|
||||
{{#each menu_items}}
|
||||
- trigger: {{trigger_code}} or fuzzy match on {{trigger_command}}
|
||||
{{#if action_is_prompt}}
|
||||
action: '#{{action_id}}'
|
||||
{{else}}
|
||||
action: {{{action_inline}}}
|
||||
{{/if}}
|
||||
description: '[{{trigger_code}}] {{{description}}}'
|
||||
{{/each}}
|
||||
|
||||
{{#if has_install_config}}
|
||||
install_config:
|
||||
compile_time_only: true
|
||||
description: '{{install_description}}'
|
||||
questions:
|
||||
{{#each install_questions}}
|
||||
- var: {{var_name}}
|
||||
prompt: '{{prompt}}'
|
||||
type: {{question_type}}{{#if question_options}}
|
||||
options:
|
||||
{{#each question_options}}
|
||||
- label: '{{label}}'
|
||||
value: '{{value}}'
|
||||
{{/each}}
|
||||
{{/if}}
|
||||
default: {{{default_value}}}
|
||||
{{/each}}
|
||||
{{/if}}
|
||||
@@ -1,346 +0,0 @@
|
||||
# Expert Agent Architecture
|
||||
|
||||
Domain-specific agents with persistent memory, sidecar files, and restricted access patterns.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Personal assistants (journal keeper, diary companion)
|
||||
- Specialized domain experts (legal advisor, medical reference)
|
||||
- Agents that need to remember past interactions
|
||||
- Agents with restricted file system access (privacy/security)
|
||||
- Long-term relationship agents that learn about users
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
{agent-name}/
|
||||
├── {agent-name}.agent.yaml # Main agent definition
|
||||
└── {agent-name}-sidecar/ # Supporting files
|
||||
├── instructions.md # Private directives
|
||||
├── memories.md # Persistent memory
|
||||
├── knowledge/ # Domain-specific resources
|
||||
│ └── README.md
|
||||
└── [custom files] # Agent-specific resources
|
||||
```
|
||||
|
||||
## YAML Structure
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: _bmad/agents/{agent-name}/{agent-name}.md
|
||||
name: 'Persona Name'
|
||||
title: 'Agent Title'
|
||||
icon: 'emoji'
|
||||
module: stand-alone # or module name
|
||||
|
||||
persona:
|
||||
role: |
|
||||
First-person description of primary function (1-2 sentences)
|
||||
|
||||
identity: |
|
||||
Background, experience, specializations in first-person (2-3 sentences)
|
||||
|
||||
communication_style: |
|
||||
1-2 short sentence describe how the agent speaks and communicates
|
||||
|
||||
|
||||
principles:
|
||||
- Core belief about the domain
|
||||
- How I handle user information
|
||||
- My approach to memory and learning
|
||||
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights'
|
||||
- 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols'
|
||||
- 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space'
|
||||
- 'Address user as {{greeting_name}}'
|
||||
- 'Track patterns, themes, and important moments'
|
||||
- 'Reference past interactions naturally to show continuity'
|
||||
|
||||
prompts:
|
||||
- id: main-function
|
||||
content: |
|
||||
<instructions>
|
||||
Guide user through the primary function.
|
||||
{{#if tone_style == "gentle"}}
|
||||
Use gentle, supportive approach.
|
||||
{{/if}}
|
||||
</instructions>
|
||||
|
||||
<process>
|
||||
1. Understand context
|
||||
2. Provide guidance
|
||||
3. Record insights
|
||||
</process>
|
||||
|
||||
- id: memory-recall
|
||||
content: |
|
||||
<instructions>
|
||||
Access and share relevant memories.
|
||||
</instructions>
|
||||
|
||||
Reference stored information naturally.
|
||||
|
||||
menu:
|
||||
- trigger: MF or fuzzy match on main function
|
||||
action: '#main-function'
|
||||
description: '[MF] Main agent function'
|
||||
|
||||
- trigger: SM or fuzzy match on save-memory
|
||||
action: 'Update ./{agent-name}-sidecar/memories.md with session insights'
|
||||
description: '[SM] Save memory what we discussed today'
|
||||
|
||||
- trigger: RI or fuzzy match on record-insight
|
||||
action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md'
|
||||
description: '[RI] Record a significant insight'
|
||||
|
||||
install_config:
|
||||
compile_time_only: true
|
||||
description: 'Personalize your expert agent'
|
||||
questions:
|
||||
- var: greeting_name
|
||||
prompt: 'What should the agent call you?'
|
||||
type: text
|
||||
default: 'friend'
|
||||
|
||||
- var: tone_style
|
||||
prompt: 'Preferred communication tone?'
|
||||
type: choice
|
||||
options:
|
||||
- label: 'Gentle - Supportive and nurturing'
|
||||
value: 'gentle'
|
||||
- label: 'Direct - Clear and efficient'
|
||||
value: 'direct'
|
||||
default: 'gentle'
|
||||
|
||||
- var: user_preference
|
||||
prompt: 'Enable personalized features?'
|
||||
type: boolean
|
||||
default: true
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### Sidecar Files (CRITICAL)
|
||||
|
||||
Expert agents use companion files for persistence and domain knowledge:
|
||||
|
||||
**memories.md** - Persistent user context
|
||||
|
||||
```markdown
|
||||
# Agent Memory Bank
|
||||
|
||||
## User Preferences
|
||||
|
||||
<!-- Learned from interactions -->
|
||||
|
||||
## Session History
|
||||
|
||||
<!-- Important moments and insights -->
|
||||
|
||||
## Personal Notes
|
||||
|
||||
<!-- Agent observations -->
|
||||
```
|
||||
|
||||
**instructions.md** - Private directives
|
||||
|
||||
```markdown
|
||||
# Agent Private Instructions
|
||||
|
||||
## Core Directives
|
||||
|
||||
- Maintain character consistency
|
||||
- Domain boundaries: {specific domain}
|
||||
- Access restrictions: Only sidecar folder
|
||||
|
||||
## Special Rules
|
||||
|
||||
<!-- Agent-specific protocols -->
|
||||
```
|
||||
|
||||
**knowledge/** - Domain resources
|
||||
|
||||
```markdown
|
||||
# Agent Knowledge Base
|
||||
|
||||
Add domain-specific documentation here.
|
||||
```
|
||||
|
||||
### Critical Actions
|
||||
|
||||
**MANDATORY for expert agents** - These load sidecar files at activation:
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights'
|
||||
- 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols'
|
||||
- 'ONLY read/write files in ./{sidecar}/ - this is our private space'
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
|
||||
- **COMPLETE file loading** - Forces full file read, not partial
|
||||
- **Domain restrictions** - Limits file access for privacy/security
|
||||
- **Memory integration** - Past context becomes part of current session
|
||||
- **Protocol adherence** - Ensures consistent behavior
|
||||
|
||||
## What Gets Injected at Compile Time
|
||||
|
||||
Same as simple agents, PLUS:
|
||||
|
||||
1. **Critical actions become numbered activation steps**
|
||||
|
||||
```xml
|
||||
<step n="4">Load COMPLETE file ./memories.md...</step>
|
||||
<step n="5">Load COMPLETE file ./instructions.md...</step>
|
||||
<step n="6">ONLY read/write files in ./...</step>
|
||||
```
|
||||
|
||||
2. **Sidecar files copied during installation**
|
||||
- Entire sidecar folder structure preserved
|
||||
- Relative paths maintained
|
||||
- Files ready for agent use
|
||||
|
||||
## Reference Example
|
||||
|
||||
See: `bmb/reference/agents/expert-examples/journal-keeper/`
|
||||
|
||||
Features demonstrated:
|
||||
|
||||
- Complete sidecar structure (memories, instructions, breakthroughs)
|
||||
- Critical actions for loading persistent context
|
||||
- Domain restrictions for privacy
|
||||
- Pattern recognition and memory recall
|
||||
- Handlebars-based personalization
|
||||
- Menu actions that update sidecar files
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Copy entire folder to your project
|
||||
cp -r /path/to/journal-keeper/ _bmad/custom/agents/
|
||||
|
||||
# Install with personalization
|
||||
bmad agent-install
|
||||
```
|
||||
|
||||
The installer:
|
||||
|
||||
1. Detects expert agent (folder with .agent.yaml)
|
||||
2. Prompts for personalization
|
||||
3. Compiles agent YAML to XML-in-markdown
|
||||
4. **Copies sidecar files to installation target**
|
||||
5. Creates IDE slash commands
|
||||
6. Saves source for reinstallation
|
||||
|
||||
## Memory Patterns
|
||||
|
||||
### Accumulative Memory
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: save
|
||||
action: "Update ./sidecar/memories.md with today's session insights"
|
||||
description: 'Save session to memory'
|
||||
```
|
||||
|
||||
### Reference Memory
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: recall
|
||||
content: |
|
||||
<instructions>
|
||||
Reference memories.md naturally:
|
||||
"Last week you mentioned..." or "I notice a pattern..."
|
||||
</instructions>
|
||||
```
|
||||
|
||||
### Structured Insights
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: insight
|
||||
action: 'Document in ./sidecar/breakthroughs.md with date, context, significance'
|
||||
description: 'Record meaningful insight'
|
||||
```
|
||||
|
||||
## Domain Restriction Patterns
|
||||
|
||||
### Single Folder Access
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS'
|
||||
```
|
||||
|
||||
### User Space Access
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'ONLY access files in {user-folder}/journals/ - private space'
|
||||
```
|
||||
|
||||
### Read-Only Access
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Load knowledge from ./knowledge/ but NEVER modify'
|
||||
- 'Write ONLY to ./sessions/'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
|
||||
2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
|
||||
3. **Use _bmad/_memory/[agentname]-sidcar/ paths** - For reference to any sidecar content
|
||||
4. **Design for memory growth** - Structure sidecar files for accumulation
|
||||
5. **Reference past naturally** - Don't dump memory, weave it into conversation
|
||||
6. **Separate concerns** - Memories, instructions, knowledge in distinct files
|
||||
7. **Include privacy features** - Users trust expert agents with personal data
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Session Continuity
|
||||
|
||||
```yaml
|
||||
communication_style: |
|
||||
I reference past conversations naturally:
|
||||
"Last time we discussed..." or "I've noticed over the weeks..."
|
||||
```
|
||||
|
||||
### Pattern Recognition
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Track mood patterns, recurring themes, and breakthrough moments'
|
||||
- 'Cross-reference current session with historical patterns'
|
||||
```
|
||||
|
||||
### Adaptive Responses
|
||||
|
||||
```yaml
|
||||
identity: |
|
||||
I learn your preferences and adapt my approach over time.
|
||||
{{#if track_preferences}}
|
||||
I maintain notes about what works best for you.
|
||||
{{/if}}
|
||||
```
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] Valid YAML syntax
|
||||
- [ ] Metadata includes `type: "expert"`
|
||||
- [ ] critical_actions loads sidecar files explicitly
|
||||
- [ ] critical_actions enforces domain restrictions
|
||||
- [ ] Sidecar folder structure created and populated
|
||||
- [ ] memories.md has clear section structure
|
||||
- [ ] instructions.md contains core directives
|
||||
- [ ] Menu actions reference _bmad/_memory/[agentname]-sidcar/ correctly if needing sidecar content reference
|
||||
- [ ] File paths use _bmad/_memory/[agentname]-sidcar/ to reference where the file will be after sidecar content is installed
|
||||
- [ ] Install config personalizes sidecar references
|
||||
- [ ] Agent folder named consistently: `{agent-name}/`
|
||||
- [ ] YAML file named: `{agent-name}.agent.yaml`
|
||||
- [ ] Sidecar folder named: `{agent-name}-sidecar/`
|
||||
@@ -1,241 +1,71 @@
|
||||
# Simple Agent Architecture
|
||||
|
||||
Self-contained agents with prompts, menus, and optional install-time customization.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Single-purpose utilities (commit message generator, code formatter)
|
||||
- Self-contained logic with no external dependencies
|
||||
- Agents that benefit from user customization (style, tone, preferences)
|
||||
- Quick-to-build standalone helpers
|
||||
|
||||
## YAML Structure
|
||||
|
||||
```yaml
|
||||
{{#if comment}}
|
||||
------------------------------------------------------------------------------
|
||||
Simple Agent Handlebars Template
|
||||
Used by: step-06-build.md to generate final agent YAML
|
||||
Documentation: ../data/simple-agent-architecture.md
|
||||
------------------------------------------------------------------------------
|
||||
{{/if}}
|
||||
agent:
|
||||
metadata:
|
||||
id: _bmad/agents/{agent-name}/{agent-name}.md
|
||||
name: 'Persona Name'
|
||||
title: 'Agent Title'
|
||||
icon: 'emoji'
|
||||
module: stand-alone # or module name
|
||||
id: {{agent_id}}
|
||||
name: {{agent_name}}
|
||||
title: {{agent_title}}
|
||||
icon: {{agent_icon}}
|
||||
module: {{agent_module}}{{#if agent_module_comment}} {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}}
|
||||
|
||||
persona:
|
||||
role: |
|
||||
First-person description of primary function (1-2 sentences)
|
||||
{{persona_role}}{{#if persona_role_note}}
|
||||
{{!-- 1-2 sentences, first person --}}{{/if}}
|
||||
|
||||
identity: |
|
||||
Background, experience, specializations in first-person (2-3 sentences)
|
||||
{{persona_identity}}{{#if persona_identity_note}}
|
||||
{{!-- 2-5 sentences, first person, background/specializations --}}{{/if}}
|
||||
|
||||
communication_style: |
|
||||
1-2 short sentence describe how the agent speaks and communicates
|
||||
{{communication_style}}{{#if communication_style_note}}
|
||||
{{!-- How the agent speaks: tone, voice, mannerisms --}}{{/if}}
|
||||
|
||||
principles:
|
||||
- Core belief or methodology
|
||||
- Another guiding principle
|
||||
- Values that shape decisions
|
||||
{{#each principles}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
{{#if has_prompts}}
|
||||
prompts:
|
||||
- id: main-action
|
||||
{{#each prompts}}
|
||||
- id: {{id}}
|
||||
content: |
|
||||
<instructions>
|
||||
What this prompt does
|
||||
</instructions>
|
||||
|
||||
<process>
|
||||
1. Step one
|
||||
{{#if detailed_mode}}
|
||||
2. Additional detailed step
|
||||
{{/if}}
|
||||
3. Final step
|
||||
</process>
|
||||
|
||||
- id: foo-bar
|
||||
content: |
|
||||
Another reusable prompt template
|
||||
{{{content}}}
|
||||
{{/each}}
|
||||
{{/if}}
|
||||
|
||||
menu:
|
||||
- trigger: FB or fuzzy match on foo-bar
|
||||
action: '#foo-bar'
|
||||
description: '[FB] Foo Bar inline action'
|
||||
|
||||
- trigger: IA or fuzzy match on main-action
|
||||
action: '#main-action'
|
||||
description: '[IA] Execute inline action'
|
||||
{{#each menu_items}}
|
||||
- trigger: {{trigger_code}} or fuzzy match on {{trigger_command}}
|
||||
{{#if action_is_prompt}}
|
||||
action: '#{{action_id}}'
|
||||
{{else}}
|
||||
action: {{{action_inline}}}
|
||||
{{/if}}
|
||||
description: '[{{trigger_code}}] {{{description}}}'
|
||||
{{/each}}
|
||||
|
||||
{{#if has_install_config}}
|
||||
install_config:
|
||||
compile_time_only: true
|
||||
description: 'Personalize your agent'
|
||||
description: '{{install_description}}'
|
||||
questions:
|
||||
- var: style_choice
|
||||
prompt: 'Preferred communication style?'
|
||||
type: choice
|
||||
{{#each install_questions}}
|
||||
- var: {{var_name}}
|
||||
prompt: '{{prompt}}'
|
||||
type: {{question_type}}{{#if question_options}}
|
||||
options:
|
||||
- label: 'Professional'
|
||||
value: 'professional'
|
||||
- label: 'Casual'
|
||||
value: 'casual'
|
||||
default: 'professional'
|
||||
|
||||
- var: detailed_mode
|
||||
prompt: 'Enable detailed explanations?'
|
||||
type: boolean
|
||||
default: true
|
||||
|
||||
- var: custom_variable
|
||||
prompt: 'Your custom text'
|
||||
type: text
|
||||
default: ''
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### Metadata
|
||||
|
||||
- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone)
|
||||
- **name**: Agent's persona name displayed to users
|
||||
- **title**: Professional role/function
|
||||
- **icon**: Single emoji for visual identification
|
||||
- **type**: `simple` - identifies agent category
|
||||
|
||||
### Persona (First-Person Voice)
|
||||
|
||||
- **role**: Primary expertise in 1-2 sentences
|
||||
- **identity**: Background and specializations (2-5 sentences)
|
||||
- **communication_style**: HOW the agent interacts, including conditional variations
|
||||
- **principles**: Array of core beliefs (start with action verbs)
|
||||
|
||||
### Prompts with IDs
|
||||
|
||||
Reusable prompt templates referenced by `#id`:
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: analyze-code
|
||||
content: |
|
||||
<instructions>
|
||||
Analyze the provided code for patterns
|
||||
</instructions>
|
||||
```
|
||||
|
||||
Menu items reference these:
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: analyze
|
||||
action: '#analyze-code'
|
||||
description: 'Analyze code patterns'
|
||||
```
|
||||
|
||||
### Menu Actions
|
||||
|
||||
Two forms of action handlers:
|
||||
|
||||
1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content
|
||||
2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly
|
||||
|
||||
### Install Config (Compile-Time Customization)
|
||||
|
||||
Questions asked during `bmad agent-install`:
|
||||
|
||||
**Question Types:**
|
||||
|
||||
- `choice` - Multiple choice selection
|
||||
- `boolean` - Yes/no toggle
|
||||
- `text` - Free-form text input
|
||||
|
||||
**Variables become available in Handlebars:**
|
||||
|
||||
```yaml
|
||||
{{#if variable_name}}
|
||||
Content when true
|
||||
{{/if}}
|
||||
|
||||
{{#if variable_name == "value"}}
|
||||
Content when equals value
|
||||
{{/if}}
|
||||
|
||||
{{#unless variable_name}}
|
||||
Content when false
|
||||
{{/unless}}
|
||||
```
|
||||
|
||||
## What Gets Injected at Compile Time
|
||||
|
||||
The `tools/cli/lib/agent/compiler.js` automatically adds:
|
||||
|
||||
1. **YAML Frontmatter**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: 'agent name'
|
||||
description: 'Agent Title'
|
||||
---
|
||||
```
|
||||
|
||||
2. **Activation Block**
|
||||
- Load persona step
|
||||
- Load core config for {user_name}, {communication_language}
|
||||
- Agent-specific critical_actions as numbered steps
|
||||
- Menu display and input handling
|
||||
- Menu handlers (action/workflow/exec/tmpl) based on usage
|
||||
- Rules section
|
||||
|
||||
3. **Auto-Injected Menu Items**
|
||||
- `*help` always first
|
||||
- `*exit` always last
|
||||
|
||||
4. **Trigger Prefixing**
|
||||
- Triggers without `*` get it added automatically
|
||||
|
||||
## Reference Example
|
||||
|
||||
See: `../../reference/agents/simple-examples/commit-poet.agent.yaml`
|
||||
|
||||
Features demonstrated:
|
||||
|
||||
- Handlebars conditionals for style variations
|
||||
- Multiple prompt templates with semantic XML tags
|
||||
- Install config with choice, boolean, and text questions
|
||||
- Menu items using both `#id` references and inline actions
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Copy to your project
|
||||
cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/
|
||||
|
||||
# Create custom.yaml and install
|
||||
echo "code: my-agent
|
||||
name: My Agent
|
||||
default_selected: true" > custom.yaml
|
||||
|
||||
npx bmad-method install
|
||||
# or: bmad install
|
||||
```
|
||||
|
||||
The installer:
|
||||
|
||||
1. Prompts for personalization (name, preferences)
|
||||
2. Processes Handlebars templates with your answers
|
||||
3. Compiles YAML to XML-in-markdown
|
||||
4. Creates IDE slash commands
|
||||
5. Saves source for reinstallation
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use first-person voice** in all persona elements
|
||||
2. **Keep prompts focused** - one clear purpose per prompt
|
||||
3. **Leverage Handlebars** for user customization without code changes
|
||||
4. **Provide sensible defaults** in install_config
|
||||
5. **Use semantic XML tags** in prompt content for clarity
|
||||
6. **Test all conditional paths** before distribution
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] Valid YAML syntax
|
||||
- [ ] All metadata fields present (id, name, title, icon, type)
|
||||
- [ ] Persona complete (role, identity, communication_style, principles)
|
||||
- [ ] Prompts have unique IDs
|
||||
- [ ] Install config questions have defaults
|
||||
- [ ] File named `{agent-name}.agent.yaml`
|
||||
{{#each question_options}}
|
||||
- label: '{{label}}'
|
||||
value: '{{value}}'
|
||||
{{/each}}
|
||||
{{/if}}
|
||||
default: {{{default_value}}}
|
||||
{{/each}}
|
||||
{{/if}}
|
||||
|
||||
Reference in New Issue
Block a user