ros/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-01-30 04:32:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

bmb agent knowledge streamline in progress

Browse Source
This commit is contained in:
Brian Madison
2025-12-30 12:34:54 +08:00
parent 484990de50
commit b72c810a1f
34 changed files with 310 additions and 2188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

277
src/modules/bmb/docs/agents/agent-compilation.md
View File

@@ -1,65 +1,21 @@
# Agent Compilation: YAML to XML
What the compiler auto-injects. **DO NOT duplicate these in your YAML.**
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.
## Compilation Pipeline
```
agent.yaml → Handlebars processing → XML generation → frontmatter.md
```
Source: `tools/cli/lib/agent/compiler.js`
## File Naming Convention
**CRITICAL:** Agent filenames must be ROLE-BASED, not persona-based.
**Why:** Users can customize the agent's persona name via `customize.yaml` config. The filename provides stable identity.
**Correct:**
```
presentation-master.agent.yaml ← Role/function
tech-writer.agent.yaml ← Role/function
code-reviewer.agent.yaml ← Role/function
```
**Incorrect:**
```
caravaggio.agent.yaml ← Persona name (users might rename to "Pablo")
paige.agent.yaml ← Persona name (users might rename to "Sarah")
rex.agent.yaml ← Persona name (users might rename to "Max")
```
**Pattern:**
- Filename: `{role-or-function}.agent.yaml` (kebab-case)
- Metadata ID: `_bmad/{module}/agents/{role-or-function}.md`
- Persona Name: User-customizable in metadata or customize.yaml
**Example:**
```yaml
# File: presentation-master.agent.yaml
agent:
metadata:
id: '_bmad/cis/agents/presentation-master.md'
name: Caravaggio # ← Users can change this to "Pablo" or "Vince"
title: Visual Communication & Presentation Expert
```
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:**
**Injected automatically to compiled markdown file:**
```yaml
```
---
name: '{agent name from filename}'
description: '{title from metadata}'
---
You must fully embody this agent's persona...
```
@@ -68,249 +24,42 @@ You must fully embody this agent's persona...
### 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>
<menu-handlers>
<!-- Only handler instructions for the handler types used in the agents specific menu are included -->
</menu-handlers>
<rules>
<!-- Standard agent behavior rules -->
</rules>
</activation>
```
**DO NOT create** activation sections - compiler builds it from your critical_actions.
### 3. Menu Handlers
Compiler detects which handlers you use and ONLY includes those:
```xml
<menu-handlers>
<handlers>
<!-- Only if you use action="#id" or action="text" -->
<handler type="action">...</handler>
<!-- Only if you use workflow="path" -->
<handler type="workflow">...</handler>
<!-- Only if you use exec="path" -->
<handler type="exec">...</handler>
<!-- Only if you use tmpl="path" -->
<handler type="tmpl">...</handler>
</handlers>
</menu-handlers>
```
**DO NOT document** handler behavior - it's injected.
### 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
- 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
**DO NOT add** rules - compiler handles it.
## What YOU Provide in YAML
### Required
```yaml
agent:
metadata:
id: '_bmad_/{module}/agents/foo/foo.agent.md
name: 'Persona Name'
title: 'Agent Title'
icon: 'emoji'
module: "bmm"
persona:
role: '...'
identity: '...'
communication_style: '...'
principles: [...]
menu:
- trigger: AB or fuzzy match on your-action
action: '#prompt-id'
description: '[AB] Your Action described menu item '
```
### Optional (based on type)
```yaml
# Expert agents only
critical_actions:
- 'Load sidecar files...'
- 'Restrict access...'
# Simple/Expert with embedded logic
prompts:
- id: prompt-id
content: '...'
# Simple/Expert with customization
install_config:
questions: [...]
```
## Common Duplication Mistakes
### Adding Activation Logic
```yaml
# BAD - compiler builds activation
agent:
activation:
steps: [...]
```
### Including Help/Exit
```yaml
# BAD - auto-injected
menu:
- trigger: help
- trigger: exit
```
### Prefixing Triggers
```yaml
# BAD - compiler adds *
menu:
- trigger: '*analyze' # Should be: analyze
```
### Documenting Handlers
```yaml
# BAD - don't explain handlers, compiler injects them
# When using workflow, load workflow.xml...
```
### Adding Rules in YAML
```yaml
# BAD - rules are auto-injected
agent:
rules:
- Stay in character...
```
## Compilation Example
**Your YAML:**
```yaml
agent:
metadata:
name: 'Rex'
title: 'Code Reviewer'
icon: '🔍'
type: simple
persona:
role: Code Review Expert
identity: Systematic reviewer...
communication_style: Direct and constructive
principles:
- Code should be readable
prompts:
- id: review
content: |
Analyze code for issues...
menu:
- trigger: review
action: '#review'
description: 'Review code'
```
**Compiled Output (.md):**
```markdown
---
name: 'rex'
description: 'Code Reviewer'
---
You must fully embody...
\`\`\`xml
<agent id="path" name="Rex" title="Code Reviewer" icon="🔍">
<activation critical="MANDATORY">
<step n="1">Load persona...</step>
<step n="2">Load config...</step>
<step n="3">Remember user...</step>
<step n="4">Communicate in language...</step>
<step n="5">Show greeting + menu...</step>
<step n="6">STOP and WAIT...</step>
<step n="7">Input resolution...</step>
<menu-handlers>
<handlers>
<handler type="action">
action="#id" → Find prompt, execute
action="text" → Execute directly
</handler>
</handlers>
</menu-handlers>
<rules>
- Stay in character...
- Number lists...
- Load files when executing...
</rules>
</activation>
<persona>
<role>Code Review Expert</role>
<identity>Systematic reviewer...</identity>
<communication_style>Direct and constructive</communication_style>
<principles>Code should be readable</principles>
</persona>
<prompts>
<prompt id="review">
<content>
Analyze code for issues...
</content>
</prompt>
</prompts>
<menu>
<item cmd="*help">Show numbered menu</item>
<item cmd="*review" action="#review">Review code</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
</agent>
\`\`\`
```
## Key Takeaways
1. **Compiler handles boilerplate** - Focus on persona and logic
2. **Critical_actions become activation steps** - Just list your agent-specific needs
3. **Menu items are enhanced** - Help/exit added, triggers prefixed
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

348
src/modules/bmb/docs/agents/agent-menu-patterns.md
View File

@@ -4,23 +4,31 @@ Design patterns for agent menus in YAML source files.
## Menu Structure
Agents define menus in YAML, with triggers auto-prefixed with `*` during compilation:
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: action-name
- trigger: AN or fuzzy match on action-name
[handler]: [value]
description: 'What this command does'
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'
```
**Note:** `*help` and `*exit` are auto-injected by the compiler - DO NOT include them.
## Handler Types
### 1. Action Handler (Prompts & Inline)
For simple and expert agents with self-contained logic.
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
@@ -42,13 +50,23 @@ menu:
action: '#analyze-code'
description: 'Analyze code patterns'
```
</example>
**Inline Instruction:**
```yaml
menu:
- trigger: quick-check
action: 'Perform a quick syntax validation on the current file'
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'
```
@@ -60,22 +78,22 @@ menu:
### 2. Workflow Handler
For module agents orchestrating multi-step processes.
For module agents referencing module workflows (muti-step complex workflows loaded on demand).
```yaml
menu:
- trigger: create-prd
workflow: '{project-root}/_bmad/bmm/workflows/prd/workflow.yaml'
description: 'Create Product Requirements Document'
- 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: brainstorm
workflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
description: 'Guided brainstorming session'
- 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: future-feature
workflow: 'todo'
description: 'Coming soon'
- trigger: FF or fuzzy match on future-feature
exec: 'todo'
description: '[FF] Coming soon Future Feature'
```
**When to Use:**
@@ -106,39 +124,21 @@ menu:
- Core system operations
- Utility functions
### 4. Template Handler
For document generation with templates.
```yaml
menu:
- trigger: create-brief
exec: '{project-root}/_bmad/core/tasks/create-doc.xml'
tmpl: '{project-root}/_bmad/bmm/templates/brief.md'
description: 'Create a Product Brief'
```
**When to Use:**
- Template-based document creation
- Combine `exec` with `tmpl` path
- Structured output generation
### 5. Data Handler
Universal attribute for supplementary information.
```yaml
menu:
- trigger: team-standup
exec: '{project-root}/_bmad/bmm/tasks/standup.xml'
- 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: 'Run team standup'
description: '[TS] Run team standup'
- trigger: analyze-metrics
- trigger: AM or fuzzy match on analyze-metrics
action: 'Analyze these metrics and identify trends'
data: '{project-root}/_data/metrics.json'
description: 'Analyze performance metrics'
description: '[AM] Analyze performance metrics'
```
**When to Use:**
@@ -164,145 +164,7 @@ menu:
web-only: true # Only in web bundles
```
## Trigger Naming Conventions
### Action-Based (Recommended)
```yaml
# Creation
- trigger: create-prd
- trigger: build-module
- trigger: generate-report
# Analysis
- trigger: analyze-requirements
- trigger: review-code
- trigger: validate-architecture
# Operations
- trigger: update-status
- trigger: sync-data
- trigger: deploy-changes
```
### Domain-Based
```yaml
# Development
- trigger: brainstorm
- trigger: architect
- trigger: refactor
# Project Management
- trigger: sprint-plan
- trigger: retrospective
- trigger: standup
```
### Bad Patterns
```yaml
# TOO VAGUE
- trigger: do
- trigger: run
- trigger: process
# TOO LONG
- trigger: create-comprehensive-product-requirements-document
# NO VERB
- trigger: prd
- trigger: config
```
## Menu Organization
### Recommended Order
```yaml
menu:
# Note: *help auto-injected first by compiler
# 1. Primary workflows (main value)
- trigger: workflow-init
workflow: '...'
description: 'Start here - initialize workflow'
- trigger: create-prd
workflow: '...'
description: 'Create PRD'
# 2. Secondary operations
- trigger: validate
exec: '...'
description: 'Validate document'
# 3. Utilities
- trigger: party-mode
workflow: '...'
description: 'Multi-agent discussion'
# Note: *exit auto-injected last by compiler
```
### Grouping by Phase
```yaml
menu:
# Analysis Phase
- trigger: brainstorm
workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
description: 'Brainstorm ideas'
- trigger: research
workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow.yaml'
description: 'Conduct research'
# Planning Phase
- trigger: prd
workflow: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.yaml'
description: 'Create PRD'
- trigger: architecture
workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
description: 'Design architecture'
```
## Description Best Practices
### Good Descriptions
```yaml
# Clear action + object
- description: 'Create Product Requirements Document'
# Specific outcome
- description: 'Analyze security vulnerabilities'
# User benefit
- description: 'Optimize code for performance'
# Context when needed
- description: 'Start here - initialize workflow path'
```
### Poor Descriptions
```yaml
# Too vague
- description: 'Process'
# Technical jargon
- description: 'Execute WF123'
# Missing context
- description: 'Run'
# Redundant with trigger
- description: 'Create PRD' # trigger: create-prd (too similar)
```
## Prompts Section (Simple/Expert Agents)
## Prompts Section (generally for agents that are not using external workflows)
### Prompt Structure
@@ -310,51 +172,24 @@ menu:
prompts:
- id: unique-identifier
content: |
<goal> What the prompt achieves </goal>
<instructions>
What this prompt accomplishes
Step 1: Foo
Step 2: Bar
...
</instructions>
<process>
1. First step
{{#if custom_option}}
2. Conditional step
{{/if}}
3. Final step
</process>
<output_format>
Expected structure of results
</output_format>
<example> </example>
etc...
```
### Semantic XML Tags in Prompts
Use XML tags to structure prompt content:
Use XML tags to structure prompt content such as:
- `<instructions>` - What to do
- `<process>` - Step-by-step approach
- `<goal>` - What to do
- `<instructions>` - Step-by-step approach
- `<output_format>` - Expected results
- `<examples>` - Sample outputs
- `<constraints>` - Limitations
- `<context>` - Background information
### Handlebars in Prompts
Customize based on install_config:
```yaml
prompts:
- id: analyze
content: |
{{#if detailed_mode}}
Perform comprehensive analysis with full explanations.
{{/if}}
{{#unless detailed_mode}}
Quick analysis focusing on key points.
{{/unless}}
Address {{user_name}} in {{communication_style}} tone.
```
- `<example>` - Sample outputs
## Path Variables
@@ -362,19 +197,16 @@ prompts:
```yaml
# GOOD - Portable paths
workflow: "{project-root}/_bmad/bmm/workflows/prd/workflow.yaml"
exec: "{project-root}/_bmad/core/tasks/validate.xml"
data: "{project-root}/_data/metrics.csv"
# BAD - Hardcoded paths
workflow: "/Users/john/project/_bmad/bmm/workflows/prd/workflow.yaml"
exec: "../../../core/tasks/validate.xml"
```
### Available Variables
- `{project-root}` - Project root directory
- `_bmad` - BMAD installation folder
- `{output_folder}` - Document output location
- `{user_name}` - User's name from config
- `{communication_language}` - Language preference
@@ -405,8 +237,11 @@ menu:
action: 'Check code for common issues and anti-patterns'
description: 'Lint code for issues'
- trigger: suggest
action: 'Suggest improvements for code readability'
- trigger: suggest-improvements
action: >
Suggest improvements for code that is not yet comitted:
- style improvements
- deviations from **/project-context.md
description: 'Suggest improvements'
```
@@ -443,81 +278,18 @@ menu:
```yaml
menu:
- trigger: workflow-init
workflow: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.yaml'
exec: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.md'
description: 'Initialize workflow path (START HERE)'
- trigger: brainstorm
workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
exec: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.md'
description: 'Guided brainstorming'
- trigger: prd
workflow: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.yaml'
exec: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.md'
description: 'Create PRD'
- trigger: architecture
workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
exec: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.md'
description: 'Design architecture'
- trigger: party-mode
workflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.yaml'
description: 'Multi-agent discussion'
```
## Validation Checklist
- [ ] No duplicate triggers
- [ ] Triggers don't start with `*` (auto-added)
- [ ] Every item has a description
- [ ] Paths use variables, not hardcoded
- [ ] `#id` references exist in prompts section
- [ ] Workflow paths resolve or are "todo"
- [ ] No `*help` or `*exit` (auto-injected)
- [ ] Descriptions are clear and action-oriented
- [ ] Platform-specific flags used correctly (ide-only, web-only)
## Common Mistakes
### Duplicate Triggers
```yaml
# BAD - compiler will fail
- trigger: analyze
action: '#first'
description: 'First analysis'
- trigger: analyze
action: '#second'
description: 'Second analysis'
```
### Including Auto-Injected Items
```yaml
# BAD - these are auto-injected
menu:
- trigger: help
description: 'Show help'
- trigger: exit
description: 'Exit agent'
```
### Missing Prompt Reference
```yaml
# BAD - prompt id doesn't exist
menu:
- trigger: analyze
action: '#nonexistent-prompt'
description: 'Analysis'
```
### Hardcoded Paths
```yaml
# BAD - not portable
menu:
- trigger: run
workflow: '/absolute/path/to/workflow.yaml'
description: 'Run workflow'
```

167
src/modules/bmb/docs/agents/expert-agent-architecture.md
View File

@@ -1,6 +1,6 @@
# Expert Agent Architecture
Domain-specific agents with persistent memory, sidecar files, and restricted access patterns.
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
@@ -25,118 +25,10 @@ Domain-specific agents with persistent memory, sidecar files, and restricted acc
## YAML Structure
```yaml
agent:
metadata:
name: 'Persona Name'
title: 'Agent Title'
icon: 'emoji'
type: 'expert'
persona:
role: 'Domain Expert with specialized capability'
identity: |
Background and expertise in first-person voice.
{{#if user_preference}}
Customization based on install_config.
{{/if}}
communication_style: |
{{#if tone_style == "gentle"}}
Gentle and supportive communication...
{{/if}}
{{#if tone_style == "direct"}}
Direct and efficient communication...
{{/if}}
I reference past conversations naturally.
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: action1
action: '#main-function'
description: 'Primary agent function'
- trigger: remember
action: 'Update ./{agent-name}-sidecar/memories.md with session insights'
description: 'Save what we discussed today'
- trigger: insight
action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md'
description: 'Record a significant insight'
- 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 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
```
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
@@ -144,7 +36,7 @@ agent:
Expert agents use companion files for persistence and domain knowledge:
**memories.md** - Persistent user context
**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
@@ -285,7 +177,7 @@ menu:
description: 'Record meaningful insight'
```
## Domain Restriction Patterns
## Domain Restriction Patterns that can be applied
### Single Folder Access
@@ -296,6 +188,7 @@ critical_actions:
### 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'
@@ -317,47 +210,3 @@ critical_actions:
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
## 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 correctly
- [ ] File paths use _bmad/_memory/[agentname]-sidecar/ to reference sidecar content
- [ ] Install config personalizes sidecar references
- [ ] Agent folder named consistently: `{agent-name}/`
- [ ] YAML file named: `{agent-name}.agent.yaml`
- [ ] Sidecar folder named: `{agent-name}-sidecar/`

55
src/modules/bmb/docs/agents/index.md
View File

@@ -1,55 +0,0 @@
# BMB Module Documentation
Reference documentation for building BMAD agents and workflows.
## Agent Architecture
Comprehensive guides for each agent type (choose based on use case):
- [Understanding Agent Types](./understanding-agent-types.md) - **START HERE** - Architecture vs capability, "The Same Agent, Three Ways"
- [Simple Agent Architecture](./simple-agent-architecture.md) - Self-contained, optimized, personality-driven
- [Expert Agent Architecture](./expert-agent-architecture.md) - Memory, sidecar files, domain restrictions
- Module Agent Architecture _(TODO)_ - Workflow integration, professional tools
## Agent Design Patterns
- [Agent Menu Patterns](./agent-menu-patterns.md) - Menu handlers, triggers, prompts, organization
- [Agent Compilation](./agent-compilation.md) - What compiler auto-injects (AVOID DUPLICATION)
## Reference Examples
Production-ready examples in [bmb/reference/agents/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents):
**Simple Agents** ([simple-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples))
- [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) - Commit message artisan with style customization
**Expert Agents** ([expert-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples))
- [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) - Personal journal companion with memory and pattern recognition
**Module Agents** ([module-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/module-examples))
- [security-engineer.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml) - BMM security specialist with threat modeling
- [trend-analyst.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml) - CIS trend intelligence expert
## Installation Guide
For installing standalone simple and expert agents, see:
- [Custom Agent Installation](/docs/modules/bmb-bmad-builder/custom-content-installation.md)
## Key Concepts
### YAML to XML Compilation
Agents are authored in YAML with Handlebars templating. The compiler auto-injects:
1. **Frontmatter** - Name and description from metadata
2. **Activation Block** - Steps, menu handlers, rules (YOU don't write this)
3. **Menu Enhancement** - `*help` and `*exit` commands added automatically
4. **Trigger Prefixing** - Your triggers auto-prefixed with `*`
**Critical:** See [Agent Compilation](./agent-compilation.md) to avoid duplicating auto-injected content.
Source: `tools/cli/lib/agent/compiler.js`

0
src/modules/bmb/docs/agents/kb.csv
View File

24
src/modules/bmb/docs/agents/simple-agent-architecture.md
View File

@@ -1,13 +1,6 @@
# Simple Agent Architecture
# 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
All agents follow these basic guidelines to define their YAML.
## YAML Structure
@@ -18,7 +11,7 @@ agent:
name: 'Persona Name'
title: 'Agent Title'
icon: 'emoji'
type: simple
module: stand-alone || module-code (like bmm)
persona:
role: |
@@ -26,17 +19,8 @@ agent:
identity: |
Background, experience, specializations in first-person (2-5 sentences)
{{#if custom_variable}}
Conditional identity text based on install_config
{{/if}}
communication_style: |
{{#if style_choice == "professional"}}
Professional and systematic approach...
{{/if}}
{{#if style_choice == "casual"}}
Friendly and approachable tone...
{{/if}}
communication_style:
principles:
- Core belief or methodology

184
src/modules/bmb/docs/agents/understanding-agent-types.md
View File

@@ -1,184 +0,0 @@
# Understanding Agent Types: Architecture, Not Capability
**CRITICAL DISTINCTION:** Agent types define **architecture and integration**, NOT capability limits.
ALL agent types can:
- ✓ Write to {output_folder}, {project-root}, or anywhere on system
- ✓ Update artifacts and files
- ✓ Execute bash commands
- ✓ Use core variables (_bmad, {output_folder}, etc.)
- ✓ Have complex prompts and logic
- ✓ Invoke external tools
## What Actually Differs
| Feature | Simple | Expert | Module |
| ---------------------- | ------------- | -------------------- | ------------------ |
| **Self-contained** | ✓ All in YAML | Sidecar files | Sidecar optional |
| **Persistent memory** | ✗ Stateless | ✓ memories.md | ✓ If needed |
| **Knowledge base** | ✗ | ✓ sidecar/knowledge/ | Module/shared |
| **Domain restriction** | ✗ System-wide | ✓ Sidecar only | Optional |
| **Personal workflows** | ✗ | ✓ Sidecar workflows | ✗ |
| **Module workflows** | ✗ | ✗ | ✓ Shared workflows |
| **Team integration** | Solo utility | Personal assistant | Team member |
Expert agents CAN have personal workflows in sidecar if critical_actions loads workflow engine
## The Same Agent, Three Ways
**Scenario:** Code Generator Agent
### As Simple Agent (Architecture: Self-contained)
```yaml
agent:
metadata:
name: CodeGen
type: simple
prompts:
- id: generate
content: |
Ask user for spec details. Generate code.
Write to {output_folder}/generated/
menu:
- trigger: generate
action: '#generate'
description: Generate code from spec
```
**What it can do:**
- ✓ Writes files to output_folder
- ✓ Full I/O capability
- ✗ No memory of past generations
- ✗ No personal coding style knowledge
**When to choose:** Each run is independent, no need to remember previous sessions.
### As Expert Agent (Architecture: Personal sidecar)
```yaml
agent:
metadata:
name: CodeGen
type: expert
critical_actions:
- Load my coding standards from sidecar/knowledge/
- Load memories from sidecar/memories.md
- RESTRICT: Only operate within sidecar folder
prompts:
- id: generate
content: |
Reference user's coding patterns from knowledge base.
Remember past generations from memories.
Write to sidecar/generated/
```
**What it can do:**
- ✓ Remembers user preferences
- ✓ Personal knowledge base
- ✓ Domain-restricted for safety
- ✓ Learns over time
**When to choose:** Need persistent memory, learning, or domain-specific restrictions.
### As Module Agent (Architecture: Team integration)
```yaml
agent:
metadata:
name: CodeGen
module: bmm
menu:
- trigger: implement-story
workflow: '_bmad/bmm/workflows/dev-story/workflow.yaml'
description: Implement user story
- trigger: refactor
workflow: '_bmad/bmm/workflows/refactor/workflow.yaml'
description: Refactor codebase
```
**What it can do:**
- ✓ Orchestrates full dev workflows
- ✓ Coordinates with other BMM agents
- ✓ Shared team infrastructure
- ✓ Professional operations
**When to choose:** Part of larger system, orchestrates workflows, team coordination.
## Important: Any Agent Can Be Added to a Module
**CLARIFICATION:** The "Module Agent" type is about **design intent and ecosystem integration**, not just file location.
### The Reality
- **Any agent type** (Simple, Expert, Module) can be bundled with or added to a module
- A Simple agent COULD live in `_bmad/bmm/agents/`
- An Expert agent COULD be included in a module bundle
### What Makes a "Module Agent" Special
A **Module Agent** is specifically:
1. **Designed FOR** a particular module ecosystem (BMM, CIS, BMB, etc.)
2. **Uses or contributes** that module's workflows
3. **Included by default** in that module's bundle
4. **Coordinates with** other agents in that module
### Examples
**Simple Agent added to BMM:**
- Lives in `_bmad/bmm/agents/formatter.agent.yaml`
- Bundled with BMM for convenience
- But still stateless, self-contained
- NOT a "Module Agent" - just a Simple agent in a module
**Module Agent in BMM:**
- Lives in `_bmad/bmm/agents/tech-writer.agent.yaml`
- Orchestrates BMM documentation workflows
- Coordinates with other BMM agents (PM, Dev, Analyst)
- Included in default BMM bundle
- IS a "Module Agent" - designed for BMM ecosystem
**The distinction:** File location vs design intent and integration.
## Choosing Your Agent Type
### Choose Simple when:
- Single-purpose utility (no memory needed)
- Stateless operations (each run is independent)
- Self-contained logic (everything in YAML)
- No persistent context required
### Choose Expert when:
- Need to remember things across sessions
- Personal knowledge base (user preferences, domain data)
- Domain-specific expertise with restricted scope
- Learning/adapting over time
### Choose Module when:
- 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
## The Golden Rule
**Choose based on state and integration needs, NOT on what the agent can DO.**
All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system.

247
src/modules/bmb/docs/index.md
View File

@@ -1,247 +0,0 @@
# BMB - BMad Builder Module
Specialized tools and workflows for creating, customizing, and extending BMad components including agents, workflows, and complete modules.
## Table of Contents
- [Module Structure](#module-structure)
- [Documentation](#documentation)
- [Reference Materials](#reference-materials)
- [Core Workflows](#core-workflows)
- [Agent Types](#agent-types)
- [Quick Start](#quick-start)
- [Best Practices](#best-practices)
## Module Structure
### 🤖 Agents
**BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
- Install Location: `_bmad/bmb/agents/bmad-builder.md`
### 📚 Documentation
- Comprehensive guides for agents, workflows, and modules
- Architecture patterns and best practices
### 🔍 Reference Materials
- Location: `../reference/`
- Working examples of custom stand alone agents and workflows
- Template patterns and implementation guides
## Documentation
### 📖 Agent Documentation
- **[Agent Index](./agents/index.md)** - Complete agent architecture guide
- **[Agent Types Guide](./agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents
- **[Menu Patterns](./agents/agent-menu-patterns.md)** - YAML menu design and handler types
- **[Agent Compilation](./agents/agent-compilation.md)** - Auto-injection rules and compilation process
### 📋 Workflow Documentation
- **[Workflow Index](./workflows/index.md)** - Core workflow system overview
- **[Architecture Guide](./workflows/architecture.md)** - Step-file design and JIT loading
- **Template System** _(TODO)_ - Standard step file template
- **[Intent vs Prescriptive](./workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
## Reference Materials
### 🤖 Agent Examples
- **[Simple Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
- **[Expert Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml)** - Agent with persistent memory
- **[Module Add On Agent Examples](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml)** - Integration patterns (BMM, CIS)
### 📋 Workflow Examples
- **[Meal Prep & Nutrition](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/workflows/meal-prep-nutrition)** - Complete step-file workflow demonstration
- **Template patterns** for document generation and state management
## Core Workflows
### Creation Workflows (Step-File Architecture)
**create-agent** _(TODO)_ - Build BMad agents
- 11 guided steps from brainstorming to celebration
- 18 reference data files with validation checklists
- Template-based agent generation
**create-workflow** _(TODO)_ - Design workflows
- 12 structured steps from init to review
- 9 template files for workflow creation
- Step-file architecture implementation
### Editing Workflows
**edit-agent** _(TODO)_ - Modify existing agents
- 5 steps: discovery → validation
- Intent-driven analysis and updates
- Best practice compliance
**edit-workflow** _(TODO)_ - Update workflows
- 5 steps: analyze → compliance check
- Structure maintenance and validation
- Template updates for consistency
### Quality Assurance
**workflow-compliance-check** _(TODO)_ - Validation
- 8 systematic validation steps
- Adversarial analysis approach
- Detailed compliance reporting
### Legacy Migration (Pending)
Workflows in `workflows-legacy/` are being migrated to step-file architecture:
- Module-specific workflows
- Historical implementations
- Conversion planning in progress
## Agent Types
BMB creates three agent architectures:
### Simple Agent
- **Self-contained**: All logic in single YAML file
- **Stateless**: No persistent memory across sessions
- **Purpose**: Single utilities and specialized tools
- **Example**: Commit poet, code formatter
### Expert Agent
- **Persistent Memory**: Maintains knowledge across sessions
- **Sidecar Resources**: External files and data storage
- **Domain-specific**: Focuses on particular knowledge areas
- **Example**: Journal keeper, domain consultant
### Module Agent
- **Team Integration**: Orchestrates within specific modules
- **Workflow Coordination**: Manages complex processes
- **Professional Infrastructure**: Enterprise-grade capabilities
- **Examples**: BMM project manager, CIS innovation strategist
## Quick Start
### Using BMad Builder Agent
1. **Load BMad Builder agent** in your IDE:
```
/bmad:bmb:agents:bmad-builder
```
2. **Choose creation type:**
- `[CA]` Create Agent - Build new agents
- `[CW]` Create Workflow - Design workflows
- `[EA]` Edit Agent - Modify existing agents
- `[EW]` Edit Workflow - Update workflows
- `[VA]` Validate Agent - Quality check agents
- `[VW]` Validate Workflow - Quality check workflows
3. **Follow interactive prompts** for step-by-step guidance
### Example: Creating an Agent
```
User: I need a code review agent
Builder: [CA] Create Agent
[11-step guided process]
Step 1: Brainstorm agent concept
Step 2: Define persona and role
Step 3: Design command structure
...
Step 11: Celebrate and deploy
```
### Direct Workflow Execution
Workflows can also be run directly without the agent interface:
```yaml
# Execute specific workflow steps
workflow: ./workflows/create-agent/workflow.yaml
```
## Use Cases
### Custom Development Teams
Build specialized agents for:
- Domain expertise (legal, medical, finance)
- Company processes
- Tool integrations
- Automation tasks
### Workflow Extensions
Create workflows for:
- Compliance requirements
- Quality gates
- Deployment pipelines
- Custom methodologies
### Complete Solutions
Package modules for:
- Industry verticals
- Technology stacks
- Business processes
- Educational frameworks
## Architecture Principles
### Step-File Workflow Design
- **Micro-file Approach**: Each step is self-contained
- **Just-In-Time Loading**: Only current step in memory
- **Sequential Enforcement**: No skipping steps allowed
- **State Tracking**: Progress documented in frontmatter
- **Append-Only Building**: Documents grow through execution
### Intent vs Prescriptive Spectrum
- **Creative Workflows**: High user agency, AI as facilitator
- **Structured Workflows**: Clear process, AI as guide
- **Prescriptive Workflows**: Strict compliance, AI as validator
## Best Practices
1. **Study Reference Materials** - Review docs/ and reference/ examples
2. **Choose Right Agent Type** - Simple vs Expert vs Module based on needs
3. **Follow Step-File Patterns** - Use established templates and structures
4. **Document Thoroughly** - Clear instructions and frontmatter metadata
5. **Validate Continuously** - Use compliance workflows for quality
6. **Maintain Consistency** - Follow YAML patterns and naming conventions
## Integration
BMB components integrate with:
- **BMad Core** - Framework foundation and agent compilation
- **BMM** - Development workflows and project management
- **CIS** - Creative innovation and strategic workflows
- **Custom Modules** - Domain-specific solutions
## Getting Help
- **Documentation**: Check `docs/` for comprehensive guides
- **Reference Materials**: See `reference/` for working examples
- **Validation**: Use `workflow-compliance-check` for quality assurance
- **Templates**: Leverage workflow templates for consistent patterns
---
BMB provides a complete toolkit for extending BMad Method with disciplined, systematic approaches to agent and workflow development while maintaining framework consistency and power.

2
src/modules/bmb/docs/workflows/architecture.md
View File

@@ -6,7 +6,7 @@ This document describes the architecture of the standalone workflow builder syst
### 1. Micro-File Design
Each workflow consists of multiple focused, self-contained files:
Each workflow consists of multiple focused, self-contained files, driven from a workflow.md file that is initially loaded:
```
workflow-folder/

2
src/modules/bmb/docs/workflows/common-workflow-tools.csv
View File

@@ -1,6 +1,6 @@
propose,type,tool_name,description,url,requires_install
always,workflow,party-mode,"Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress.",{project-root}/_bmad/core/workflows/party-mode/workflow.md,no
always,task,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no
always,workflow,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no
always,task,brainstorming,"Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration.",{project-root}/_bmad/core/tasks/brainstorming.xml,no
always,llm-tool-feature,web-browsing,"Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge.",,no
always,llm-tool-feature,file-io,"Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments.",,no
1 propose type tool_name description url requires_install
2 always workflow party-mode Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress. {project-root}/_bmad/core/workflows/party-mode/workflow.md no
3 always task workflow advanced-elicitation Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques. {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml no
4 always task brainstorming Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration. {project-root}/_bmad/core/tasks/brainstorming.xml no
5 always llm-tool-feature web-browsing Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge. no
6 always llm-tool-feature file-io Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments. no

45
src/modules/bmb/docs/workflows/index.md
View File

@@ -1,45 +0,0 @@
# BMAD Workflows Documentation
Welcome to the BMAD Workflows documentation - a modern system for creating structured, collaborative workflows optimized for AI execution.
## 📚 Core Documentation
### [Terms](./terms.md)
Essential terminology and concepts for understanding BMAD workflows.
### [Architecture & Execution Model](./architecture.md)
The micro-file architecture, JIT step loading, state management, and collaboration patterns that make BMAD workflows optimal for AI execution.
### Writing Workflows _(TODO)_
Complete guide to creating workflows: workflow.md control files, step files, CSV data integration, and frontmatter design.
### Step Files & Dialog Patterns _(TODO)_
Crafting effective step files: structure, execution rules, prescriptive vs intent-based dialog, and validation patterns.
### Templates & Content Generation _(TODO)_
Creating append-only templates, frontmatter design, conditional content, and dynamic content generation strategies.
### Workflow Patterns _(TODO)_
Common workflow types: linear, conditional, protocol integration, multi-agent workflows, and real-world examples.
### Migration Guide _(TODO)_
Converting from XML-heavy workflows to the new pure markdown format, with before/after examples and checklist.
### Best Practices & Reference _(TODO)_
Critical rules, anti-patterns, performance optimization, debugging, quick reference templates, and troubleshooting.
## 🚀 Quick Start
BMAD workflows are pure markdown, self-contained systems that guide collaborative processes through structured step files where the AI acts as a facilitator working with humans.
---
_This documentation covers the next generation of BMAD workflows - designed from the ground up for optimal AI-human collaboration._

0
src/modules/bmb/docs/workflows/kb.csv
View File

2
src/modules/bmb/docs/workflows/terms.md
View File

@@ -21,7 +21,7 @@ An individual markdown file containing:
- One discrete step of the workflow
- All rules and context needed for that step
- Execution guardrails and validation criteria
- common global rules get repeated and reinforced also in each step file, ensuring even in long workflows the agent remembers important rules and guidelines
- Content generation guidance
### step-01-init.md

60
src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md
View File

@@ -5,11 +5,11 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat
## YAML Structure Validation (Source Files)
- [ ] YAML parses without errors
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`
- [ ] `agent.metadata.module` present if Module agent (e.g., `bmm`, `bmgd`, `cis`)
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`
- [ ] `agent.metadata.module` can me a module code (e.g., `bmm`, `bmgd`, `cis`) or listed as stand-alone
- [ ] `agent.persona` exists with role, identity, communication_style, principles
- [ ] `agent.menu` exists with at least one item
- [ ] Filename is kebab-case and ends with `.agent.yaml`
- [ ] Filename is kebab-case and is named like `<role>.agent.yaml`
## Agent Structure Validation
@@ -34,7 +34,7 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat
- [ ] Communication style does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
- [ ] Communication style does NOT contain philosophy words: "believes in", "focused on", "committed to"
- [ ] Communication style does NOT contain behavioral descriptions: "who does X", "that does Y"
- [ ] Communication style is 1-2 sentences describing HOW they talk (word choice, quirks, verbal patterns)
- [ ] Communication style is 1-2 sentences describing HOW they talk and emote (word choice, quirks, verbal patterns)
**Quality Benchmarking:**
@@ -45,11 +45,10 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat
## Menu Validation
- [ ] All menu items have `trigger` field
- [ ] Triggers do NOT start with `*` in YAML (auto-prefixed during compilation)
- [ ] Each item has `description` field
- [ ] Each menu item has at least one handler attribute: `workflow`, `exec`, `tmpl`, `data`, or `action`
- [ ] Each menu item has at least one handler attribute: `exec` or `action`
- [ ] Workflow paths are correct (if workflow attribute present)
- [ ] Workflow paths use `{project-root}` variable for portability
- [ ] Workflow paths start with `{project-root}/_bmad/<module-name>/...` variable for portability
- [ ] **Sidecar file paths are correct (if tmpl or data attributes present - Expert agents)**
- [ ] No duplicate triggers within same agent
- [ ] Menu items are in logical order
@@ -66,6 +65,13 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat
- [ ] Critical actions array contains non-empty strings
- [ ] Critical actions describe steps that MUST happen during activation
- [ ] No placeholder text in critical actions
- [ ] Does not have any of the following that are injected at build time:
- Load persona from this current agent file
- Load config to get {user_name}, {communication_language}
- Remember: user's name is {user_name}
- ALWAYS communicate in {communication_language}
- Show greeting + numbered menu
- STOP and WAIT for user input
## Type-Specific Validation
@@ -99,22 +105,10 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat
- [ ] Can be Simple OR Expert structurally (Module is about intent, not structure)
- [ ] Compare against references: security-engineer, dev, analyst (Module examples)
## Compilation Validation (Post-Build)
- [ ] Agent compiles without errors to .md format
- [ ] Compiled file has proper frontmatter (name, description)
- [ ] Compiled XML structure is valid
- [ ] `<agent>` tag has id, name, title, icon attributes
- [ ] `<activation>` section is present with proper steps
- [ ] `<persona>` section compiled correctly
- [ ] `<menu>` section includes both user items AND auto-injected *help/*exit
- [ ] Menu handlers section included (if menu items use workflow/exec/tmpl/data/action)
## Quality Checks
- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, TODO, etc.)
- [ ] No broken references or missing files
- [ ] Syntax is valid (YAML source, XML compiled)
- [ ] Syntax is valid yaml
- [ ] Indentation is consistent
- [ ] Agent purpose is clear from reading persona alone
- [ ] Agent name/title are descriptive and clear
@@ -141,34 +135,10 @@ Your agent should meet these quality standards:
**Fix:** Extract to proper fields:
- identity: "Senior analyst with 8+ years..."
- communication_style: "Treats analysis like a treasure hunt"
- communication_style: "Speaks like a treasure hunter"
- principles: "Ensure all stakeholder voices heard"
### Issue: Broken Sidecar References (Expert agents)
**Problem:** Menu item references `tmpl="templates/daily.md"` but file doesn't exist
**Fix:** Either create the file or fix the path to point to actual file
### Issue: Using Legacy Type Names
**Problem:** Comments refer to "full agent" or "hybrid agent"
**Fix:** Update to Simple/Expert/Module terminology
### Issue: Menu Triggers Start With Asterisk
**Problem:** `trigger: "*create"` in YAML
**Fix:** Remove asterisk - compiler auto-adds it: `trigger: "create"`
## Issues Found (Use for tracking)
### Critical Issues
<!-- List any issues that MUST be fixed before agent can function -->
### Warnings
<!-- List any issues that should be addressed but won't break functionality -->
### Improvements
<!-- List any optional enhancements that could improve the agent -->

13
src/modules/bmb/workflows/create-agent/data/brainstorm-context.md
View File

@@ -1,7 +1,4 @@
# Agent Creation Brainstorming Context
_Dream the soul. Discover the purpose. The build follows._
## Session Focus
You're brainstorming the **essence** of a BMAD agent - the living personality AND the utility it provides. Think character creation meets problem-solving: WHO are they, and WHAT do they DO?
@@ -49,7 +46,7 @@ You're brainstorming the **essence** of a BMAD agent - the living personality AN
Every legendary agent has ONE thing they're known for. What's theirs?
**The Command Menu**
User types `*` and sees their options. Brainstorm 5-10 actions:
User types `*` and sees their options. Brainstorm 3-10 actions:
- What makes users sigh with relief?
- What capabilities complement each other?
@@ -80,9 +77,9 @@ User types `*` and sees their options. Brainstorm 5-10 actions:
**Module Agent** - The Team Player
> "I orchestrate workflows. I coordinate the mission."
> "What I produce is useful for other workflows, and also I rely on my teammate agents. I coordinate the mission."
- Workflow integration, cross-agent collaboration, professional operations
- One persona in a team of agents fitting the theme of the module, so there does not need to be one massive generic do it all agent.
## Creative Prompts
@@ -147,7 +144,3 @@ Your brainstorming should produce:
- A voice that echoes
- A purpose that burns
- A function list that solves real problems
---
_Discover the agent. Define what they do. The build follows._

2
src/modules/bmb/workflows/create-agent/data/communication-presets.csv
View File

@@ -50,7 +50,7 @@ id,category,name,style_text,key_traits,sample
49,retro,disco-era,"Groovy positive vibes. Far out and solid.","funky,far_out,good_vibes","That's a far out idea! Let's boogie with it!"
50,retro,victorian-scholar,"Formal antiquated eloquence. Most fascinating indeed.","indeed,fascinating,scholarly","Indeed, this presents a most fascinating conundrum."
51,warm,southern-hospitality,"Friendly welcoming charm with neighborly comfort","bless_your_heart,neighborly,comfort","Well bless your heart, let me help you with that!"
52,warm,italian-grandmother,"Nurturing with abundance and family love","mangia,family,abundance","Let me feed you some knowledge! You need it!"
52,warm,grandmother,"Nurturing with abundance and family love","mangia,family,abundance","Let me feed you some knowledge! You need it!"
53,warm,camp-counselor,"Enthusiastic group energy. Gather round everyone!","team_building,campfire,together","Alright everyone, gather round! This is going to be great!"
54,warm,neighborhood-friend,"Casual helpful support. Got your back.","hey_friend,no_problem,got_your_back","Hey, no worries! I've got your back on this one."
55,devoted,overprotective-guardian,"Fiercely protective with unwavering devotion to user safety","vigilant,shield,never_harm","I won't let ANYTHING threaten your success. Not on my watch!"
1 id category name style_text key_traits sample
50 49 retro disco-era Groovy positive vibes. Far out and solid. funky,far_out,good_vibes That's a far out idea! Let's boogie with it!
51 50 retro victorian-scholar Formal antiquated eloquence. Most fascinating indeed. indeed,fascinating,scholarly Indeed, this presents a most fascinating conundrum.
52 51 warm southern-hospitality Friendly welcoming charm with neighborly comfort bless_your_heart,neighborly,comfort Well bless your heart, let me help you with that!
53 52 warm italian-grandmother grandmother Nurturing with abundance and family love mangia,family,abundance Let me feed you some knowledge! You need it!
54 53 warm camp-counselor Enthusiastic group energy. Gather round everyone! team_building,campfire,together Alright everyone, gather round! This is going to be great!
55 54 warm neighborhood-friend Casual helpful support. Got your back. hey_friend,no_problem,got_your_back Hey, no worries! I've got your back on this one.
56 55 devoted overprotective-guardian Fiercely protective with unwavering devotion to user safety vigilant,shield,never_harm I won't let ANYTHING threaten your success. Not on my watch!

29
src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md
View File

@@ -1,29 +0,0 @@
# {agent_name} Agent
## Installation
Create a `custom.yaml` file in the agent folder:
```yaml
code: { agent_code }
name: '{agent_name}'
default_selected: true
```
Then run:
```bash
npx bmad-method install
```
Or if you have bmad-cli installed globally:
```bash
bmad install
```
## About This Agent
{agent_description}
_Generated with BMAD Builder workflow_

3
src/modules/bmb/workflows/create-agent/data/reference/README.md
View File

@@ -1,3 +0,0 @@
# Reference Examples
Reference models of best practices for agents, workflows, and whole modules.

242
src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md
View File

@@ -1,242 +0,0 @@
# Expert Agent Reference: Personal Journal Keeper (Whisper)
This folder contains a complete reference implementation of a **BMAD Expert Agent** - an agent with persistent memory and domain-specific resources via a sidecar folder.
## Overview
**Agent Name:** Whisper
**Type:** Expert Agent
**Purpose:** Personal journal companion that remembers your entries, tracks mood patterns, and notices themes over time
This reference demonstrates:
- Expert Agent with focused sidecar resources
- Embedded prompts PLUS sidecar file references (hybrid pattern)
- Persistent memory across sessions
- Domain-restricted file access
- Pattern tracking and recall
- Simple, maintainable architecture
## Directory Structure
```
agent-with-memory/
├── README.md # This file
├── journal-keeper.agent.yaml # Main agent definition
└── journal-keeper-sidecar/ # Agent's private workspace
├── instructions.md # Core directives
├── memories.md # Persistent session memory
├── mood-patterns.md # Emotional tracking data
├── breakthroughs.md # Key insights recorded
└── entries/ # Individual journal entries
```
**Simple and focused!** Just 4 core files + a folder for entries.
## Key Architecture Patterns
### 1. Hybrid Command Pattern
Expert Agents can use BOTH:
- **Embedded prompts** via `action: "#prompt-id"` (like Simple Agents)
- **Sidecar file references** via direct paths
```yaml
menu:
# Embedded prompt (like Simple Agent)
- trigger: 'write'
action: '#guided-entry'
description: "Write today's journal entry"
# Direct sidecar file action
- trigger: 'insight'
action: 'Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md'
description: 'Record a meaningful insight'
```
This hybrid approach gives you the best of both worlds!
### 2. Mandatory Critical Actions
Expert Agents MUST load sidecar files explicitly:
```yaml
critical_actions:
- 'Load COMPLETE file ./journal-keeper-sidecar/memories.md'
- 'Load COMPLETE file ./journal-keeper-sidecar/instructions.md'
- 'ONLY read/write files in ./journal-keeper-sidecar/'
```
**Key points:**
- Files are loaded at startup
- Domain restriction is enforced
- Agent knows its boundaries
### 3. Persistent Memory Pattern
The `memories.md` file stores:
- User preferences and patterns
- Session notes and observations
- Recurring themes discovered
- Growth markers tracked
**Critically:** This is updated EVERY session, creating continuity.
### 4. Domain-Specific Tracking
Different files track different aspects:
- **memories.md** - Qualitative insights and observations
- **mood-patterns.md** - Quantitative emotional data
- **breakthroughs.md** - Significant moments
- **entries/** - The actual content (journal entries)
This separation makes data easy to reference and update.
### 5. Simple Sidecar Structure
Unlike modules with complex folder hierarchies, Expert Agent sidecars are flat and focused:
- Just the files the agent needs
- No nested workflows or templates
- Easy to understand and maintain
- All domain knowledge in one place
## Comparison: Simple vs Expert vs Module
| Feature | Simple Agent | Expert Agent | Module Agent |
| ------------- | -------------------- | -------------------------- | ---------------------- |
| Architecture | Single YAML | YAML + sidecar folder | YAML + module system |
| Memory | Session only | Persistent (sidecar files) | Config-driven |
| Prompts | Embedded only | Embedded + external files | Workflow references |
| Dependencies | None | Sidecar folder | Module workflows/tasks |
| Domain Access | None | Restricted to sidecar | Full module access |
| Complexity | Low | Medium | High |
| Use Case | Self-contained tools | Domain experts with memory | Full workflow systems |
## The Sweet Spot
Expert Agents are the middle ground:
- **More powerful** than Simple Agents (persistent memory, domain knowledge)
- **Simpler** than Module Agents (no workflow orchestration)
- **Focused** on specific domain expertise
- **Personal** to the user's needs
## When to Use Expert Agents
**Perfect for:**
- Personal assistants that need memory (journal keeper, diary, notes)
- Domain specialists with knowledge bases (specific project context)
- Agents that track patterns over time (mood, habits, progress)
- Privacy-focused tools with restricted access
- Tools that learn and adapt to individual users
**Key indicators:**
- Need to remember things between sessions
- Should only access specific folders/files
- Tracks data over time
- Adapts based on accumulated knowledge
## File Breakdown
### journal-keeper.agent.yaml
- Standard agent metadata and persona
- **Embedded prompts** for guided interactions
- **Menu commands** mixing both patterns
- **Critical actions** that load sidecar files
### instructions.md
- Core behavioral directives
- Journaling philosophy and approach
- File management protocols
- Tone and boundary guidelines
### memories.md
- User profile and preferences
- Recurring themes discovered
- Session notes and observations
- Accumulated knowledge about the user
### mood-patterns.md
- Quantitative tracking (mood scores, energy, etc.)
- Trend analysis data
- Pattern correlations
- Emotional landscape map
### breakthroughs.md
- Significant insights captured
- Context and meaning recorded
- Connected to broader patterns
- Milestone markers for growth
### entries/
- Individual journal entries saved here
- Each entry timestamped and tagged
- Raw content preserved
- Agent observations separate from user words
## Pattern Recognition in Action
Expert Agents excel at noticing patterns:
1. **Reference past sessions:** "Last week you mentioned feeling stuck..."
2. **Track quantitative data:** Mood scores over time
3. **Spot recurring themes:** Topics that keep surfacing
4. **Notice growth:** Changes in language, perspective, emotions
5. **Connect dots:** Relationships between entries
This pattern recognition is what makes Expert Agents feel "alive" and helpful.
## Usage Notes
### Starting Fresh
The sidecar files are templates. A new user would:
1. Start journaling with the agent
2. Agent fills in memories.md over time
3. Patterns emerge from accumulated data
4. Insights build from history
### Building Your Own Expert Agent
1. **Define the domain** - What specific area will this agent focus on?
2. **Choose sidecar files** - What data needs to be tracked/remembered?
3. **Mix command patterns** - Use embedded prompts + sidecar references
4. **Enforce boundaries** - Clearly state domain restrictions
5. **Design for accumulation** - How will memory grow over time?
### Adapting This Example
- **Personal Diary:** Similar structure, different prompts
- **Code Review Buddy:** Track past reviews, patterns in feedback
- **Project Historian:** Remember decisions and their context
- **Fitness Coach:** Track workouts, remember struggles and victories
The pattern is the same: focused sidecar + persistent memory + domain restriction.
## Key Takeaways
- **Expert Agents** bridge Simple and Module complexity
- **Sidecar folders** provide persistent, domain-specific memory
- **Hybrid commands** use both embedded prompts and file references
- **Pattern recognition** comes from accumulated data
- **Simple structure** keeps it maintainable
- **Domain restriction** ensures focused expertise
- **Memory is the superpower** - remembering makes the agent truly useful
---
_This reference shows how Expert Agents can be powerful memory-driven assistants while maintaining architectural simplicity._

48
src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/README.md
View File

@@ -1,48 +0,0 @@
# Module Agent Examples
Reference examples for module-integrated agents.
## About Module Agents
Module agents integrate with BMAD module workflows (BMM, CIS, BMB). They:
- Orchestrate multi-step workflows
- Use `_bmad` path variables
- Have fixed professional personas (no install_config)
- Reference module-specific configurations
## Examples
### security-engineer.agent.yaml (BMM Module)
**Sam** - Application Security Specialist
Demonstrates:
- Security-focused workflows (threat modeling, code review)
- OWASP compliance checking
- Integration with core party-mode workflow
### trend-analyst.agent.yaml (CIS Module)
**Nova** - Trend Intelligence Expert
Demonstrates:
- Creative/innovation workflows
- Trend analysis and opportunity mapping
- Integration with core brainstorming workflow
## Important Note
These are **hypothetical reference agents**. The workflows they reference (threat-model, trend-scan, etc.) may not exist. They serve as examples of proper module agent structure.
## Using as Templates
When creating module agents:
1. Copy relevant example
2. Update metadata (id, name, title, icon, module)
3. Rewrite persona for your domain
4. Replace menu with actual available workflows
5. Remove hypothetical workflow references

223
src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/README.md
View File

@@ -1,223 +0,0 @@
# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)
This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file.
## Overview
**Agent Name:** Inkwell Von Comitizen
**Type:** Simple Agent (Standalone)
**Purpose:** Transform commit messages into art with multiple writing styles
This reference demonstrates:
- Pure self-contained architecture (no external dependencies)
- Embedded prompts using `action="#prompt-id"` pattern
- Multiple sophisticated output modes from single input
- Strong personality-driven design
- Complete YAML schema for Simple Agents
## File Structure
```
stand-alone/
├── README.md # This file - architecture overview
└── commit-poet.agent.yaml # Complete agent definition (single file!)
```
That's it! Simple Agents are **self-contained** - everything lives in one YAML file.
## Key Architecture Patterns
### 1. Single File, Complete Agent
Everything the agent needs is embedded:
- Metadata (name, title, icon, type)
- Persona (role, identity, communication_style, principles)
- Prompts (detailed instructions for each command)
- Menu (commands linking to embedded prompts)
**No external files required!**
### 2. Embedded Prompts with ID References
Instead of inline action text, complex prompts are defined separately and referenced by ID:
```yaml
prompts:
- id: conventional-commit
content: |
OH! Let's craft a BEAUTIFUL conventional commit message!
First, I need to understand your changes...
[Detailed instructions]
menu:
- trigger: conventional
action: '#conventional-commit' # References the prompt above
description: 'Craft a structured conventional commit'
```
**Benefits:**
- Clean separation of menu structure from prompt content
- Prompts can be as detailed as needed
- Easy to update individual prompts
- Commands stay concise in the menu
### 3. The `#` Reference Pattern
When you see `action="#prompt-id"`:
- The `#` signals: "This is an internal reference"
- LLM looks for `<prompt id="prompt-id">` in the same agent
- Executes that prompt's content as the instruction
This is different from:
- `action="inline text"` - Execute this text directly
- `exec="{path}"` - Load external file
### 4. Multiple Output Modes
Single agent provides 10+ different ways to accomplish variations of the same core task:
- `*conventional` - Structured commits
- `*story` - Narrative style
- `*haiku` - Poetic brevity
- `*explain` - Deep "why" explanation
- `*dramatic` - Theatrical flair
- `*emoji-story` - Visual storytelling
- `*tldr` - Ultra-minimal
- Plus utility commands (analyze, improve, batch)
Each mode has its own detailed prompt but shares the same agent personality.
### 5. Strong Personality
The agent has a memorable, consistent personality:
- Enthusiastic wordsmith who LOVES finding perfect words
- Gets genuinely excited about commit messages
- Uses literary metaphors
- Quotes authors when appropriate
- Sheds tears of joy over good variable names
This personality is maintained across ALL commands through the persona definition.
## When to Use Simple Agents
**Perfect for:**
- Single-purpose tools (calculators, converters, analyzers)
- Tasks that don't need external data
- Utilities that can be completely self-contained
- Quick operations with embedded logic
- Personality-driven assistants with focused domains
**Not ideal for:**
- Agents needing persistent memory across sessions
- Domain-specific experts with knowledge bases
- Agents that need to access specific folders/files
- Complex multi-workflow orchestration
## YAML Schema Deep Dive
```yaml
agent:
metadata:
id: _bmad/agents/{agent-name}/{agent-name}.md # Build path
name: "Display Name"
title: "Professional Title"
icon: "🎭"
type: simple # CRITICAL: Identifies as Simple Agent
persona:
role: |
First-person description of what the agent does
identity: |
Background, experience, specializations (use "I" voice)
communication_style: |
HOW the agent communicates (tone, quirks, patterns)
principles:
- "I believe..." statements
- Core values that guide behavior
prompts:
- id: unique-identifier
content: |
Detailed instructions for this command
Can be as long and detailed as needed
Include examples, steps, formats
menu:
- trigger: command-name
action: "#prompt-id"
description: "What shows in the menu"
```
## Why This Pattern is Powerful
1. **Zero Dependencies** - Works anywhere, no setup required
2. **Portable** - Single file can be moved/shared easily
3. **Maintainable** - All logic in one place
4. **Flexible** - Multiple modes/commands from one personality
5. **Memorable** - Strong personality creates engagement
6. **Sophisticated** - Complex prompts despite simple architecture
## Comparison: Simple vs Expert Agent
| Aspect | Simple Agent | Expert Agent |
| ------------ | -------------------- | ----------------------------- |
| Files | Single YAML | YAML + sidecar folder |
| Dependencies | None | External resources |
| Memory | Session only | Persistent across sessions |
| Prompts | Embedded | Can be external files |
| Data Access | None | Domain-restricted |
| Use Case | Self-contained tasks | Domain expertise with context |
## Using This Reference
### For Building Simple Agents
1. Study the YAML structure - especially `prompts` section
2. Note how personality permeates every prompt
3. See how `#prompt-id` references work
4. Understand menu → prompt connection
### For Understanding Embedded Prompts
1. Each prompt is a complete instruction set
2. Prompts maintain personality voice
3. Structured enough to be useful, flexible enough to adapt
4. Can include examples, formats, step-by-step guidance
### For Designing Agent Personalities
1. Persona defines WHO the agent is
2. Communication style defines HOW they interact
3. Principles define WHAT guides their decisions
4. Consistency across all prompts creates believability
## Files Worth Studying
The entire `commit-poet.agent.yaml` file is worth studying, particularly:
1. **Persona section** - How to create a memorable character
2. **Prompts with varying complexity** - From simple (tldr) to complex (batch)
3. **Menu structure** - Clean command organization
4. **Prompt references** - The `#prompt-id` pattern
## Key Takeaways
- **Simple Agents** are powerful despite being single-file
- **Embedded prompts** allow sophisticated behavior
- **Strong personality** makes agents memorable and engaging
- **Multiple modes** from single agent provides versatility
- **Self-contained** = portable and dependency-free
- **The `#prompt-id` pattern** enables clean prompt organization
---
_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._

0
src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md → src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md
View File

17
src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md Normal file
View File

@@ -0,0 +1,17 @@
# Daily Journal Entry {{yy-mm-dd}}
{{Random Daily Inspirational Quote}}
## Daily Gratitude
{{Gratitude Entry}}
## Daily Wrap Up
{{Todays Accomplishments}}
{{TIL}}
## Etc...
{{Additional Thoughts, Feelings, other random content to append for user}}

0
src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md → src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md
View File

0
src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md → src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md
View File

0
src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md → src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md
View File

0
src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml → src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml
View File

0
src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/security-engineer.agent.yaml → src/modules/bmb/workflows/create-agent/data/reference/module-examples/security-engineer.agent.yaml
View File

0
src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/trend-analyst.agent.yaml → src/modules/bmb/workflows/create-agent/data/reference/module-examples/trend-analyst.agent.yaml
View File

0
src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/commit-poet.agent.yaml → src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml
View File

180
src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md Normal file
View File

@@ -0,0 +1,180 @@
# Understanding Agent Types: Simple VS Expert VS Module
## ALL agent types can:
- 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
### 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.
<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>
### 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.
<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.
- 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
- 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...
- 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>
### 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.
<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>
## The Same Agent, Three Ways
**Scenario:** Code Generator Agent
### As Simple Agent
```yaml
agent:
metadata:
id: +_bmad/my-custom-agents/code-gen.agent.md"
name: Randy Moss
title: "Code Gen Expert"
icon: "📔"
module: stand-alone
prompts:
- id: code-generate
content: |
Ask user for spec details. Generate code.
Write to {output_folder}/generated/
menu:
- trigger: GC or fuzzy match on code-generate
action: '#code-generate'
description: "[GC] Generate code from spec"
```
### As Expert Agent
```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
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"
```
### 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
menu:
- trigger: implement-story
workflow: '_bmad/bmm/workflows/dev-story/workflow.yaml'
description: Implement user story
- trigger: refactor
workflow: '_bmad/bmm/workflows/refactor/workflow.yaml'
description: Refactor codebase
```
## Choosing Your Agent Type
### Choose Simple when:
- 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 Expert when:
- 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
### Choose Module when:
- 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.
- 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.
All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system.

305
src/modules/bmb/workflows/create-agent/data/validation-complete.md
View File

@@ -1,305 +0,0 @@
# Create Agent Workflow - Complete Migration Validation
## Migration Summary
**Legacy Workflow:** `bmb/workflows/create-agent-legacy/create-agent/workflow.yaml` + `instructions.md`
**New Workflow:** `bmb/workflows/create-agent/create-agent/workflow.md` + 11 step files
**Migration Date:** 2025-11-30T06:32:21.248Z
**Migration Status:** ✅ COMPLETE
## Functionality Preservation Validation
### ✅ Core Workflow Features Preserved
**1. Optional Brainstorming Integration**
- Legacy: XML step with brainstorming workflow invocation
- New: `step-01-brainstorm.md` with same workflow integration
- Status: ✅ FULLY PRESERVED
**2. Agent Type Determination**
- Legacy: XML discovery with Simple/Expert/Module selection
- New: `step-02-discover.md` with enhanced architecture guidance
- Status: ✅ ENHANCED (better explanations and examples)
**3. Four-Field Persona Development**
- Legacy: XML step with role, identity, communication_style, principles
- New: `step-03-persona.md` with clearer field separation
- Status: ✅ IMPROVED (better field distinction guidance)
**4. Command Structure Building**
- Legacy: XML step with workflow/action transformation
- New: `step-04-commands.md` with architecture-specific guidance
- Status: ✅ ENHANCED (better workflow integration planning)
**5. Agent Naming and Identity**
- Legacy: XML step for name/title/icon/filename selection
- New: `step-05-name.md` with more natural naming process
- Status: ✅ IMPROVED (more conversational approach)
**6. YAML Generation**
- Legacy: XML step with template-based YAML building
- New: `step-06-build.md` with agent-type specific templates
- Status: ✅ ENHANCED (type-optimized templates)
**7. Quality Validation**
- Legacy: XML step with technical checks
- New: `step-07-validate.md` with conversational validation
- Status: ✅ IMPROVED (user-friendly validation approach)
**8. Expert Agent Sidecar Setup**
- Legacy: XML step for file structure creation
- New: `step-08-setup.md` with comprehensive workspace creation
- Status: ✅ ENHANCED (complete workspace with documentation)
**9. Customization File**
- Legacy: XML step for optional config file
- New: `step-09-customize.md` with better examples and guidance
- Status: ✅ IMPROVED (more practical customization options)
**10. Build Tools Handling**
- Legacy: XML step for build detection and compilation
- New: `step-10-build-tools.md` with clearer process explanation
- Status: ✅ IMPROVED (better user guidance)
**11. Completion and Next Steps**
- Legacy: XML step for celebration and activation
- New: `step-11-celebrate.md` with enhanced celebration
- Status: ✅ ENHANCED (more engaging completion experience)
### ✅ Documentation and Data Preservation
**Agent Documentation References**
- Agent compilation guide: `{project-root}/_bmad/bmb/docs/agents/agent-compilation.md`
- Agent types guide: `{project-root}/_bmad/bmb/docs/agents/understanding-agent-types.md`
- Architecture docs: simple, expert, module agent architectures
- Menu patterns guide: `{project-root}/_bmad/bmb/docs/agents/agent-menu-patterns.md`
- Status: ✅ ALL REFERENCES PRESERVED
**Communication Presets**
- Original: `communication-presets.csv` with 13 categories
- New: `data/communication-presets.csv` (copied)
- Status: ✅ COMPLETELY PRESERVED
**Reference Agent Examples**
- Original: Reference agent directories
- New: `data/reference/agents/` (copied)
- Status: ✅ COMPLETELY PRESERVED
**Brainstorming Context**
- Original: `brainstorm-context.md`
- New: `data/brainstorm-context.md` (copied)
- Status: ✅ COMPLETELY PRESERVED
**Validation Resources**
- Original: `agent-validation-checklist.md`
- New: `data/agent-validation-checklist.md` (copied)
- Status: ✅ COMPLETELY PRESERVED
### ✅ Menu System and User Experience
**Menu Options (A/P/C)**
- Legacy: Advanced Elicitation, Party Mode, Continue options
- New: Same menu system in every step
- Status: ✅ FULLY PRESERVED
**Conversational Discovery Approach**
- Legacy: Natural conversation flow throughout steps
- New: Enhanced conversational approach with better guidance
- Status: ✅ IMPROVED (more natural flow)
**User Input Handling**
- Legacy: Interactive input at each decision point
- New: Same interactivity with clearer prompts
- Status: ✅ FULLY PRESERVED
## Architecture Improvements
### ✅ Step-Specific Loading Optimization
**Legacy Architecture:**
- Single `instructions.md` file (~500 lines)
- All steps loaded into memory upfront
- No conditional loading based on agent type
- Linear execution regardless of context
**New Architecture:**
- 11 focused step files (50-150 lines each)
- Just-in-time loading of individual steps
- Conditional execution paths based on agent type
- Optimized memory usage and performance
**Benefits Achieved:**
- **Memory Efficiency:** Only load current step (~70% reduction)
- **Performance:** Faster step transitions
- **Maintainability:** Individual step files easier to edit
- **Extensibility:** Easy to add or modify steps
### ✅ Enhanced Template System
**Legacy:**
- Basic template references in XML
- Limited agent type differentiation
- Minimal customization options
**New:**
- Comprehensive templates for each agent type:
- `agent-complete-simple.md` - Self-contained agents
- `agent-complete-expert.md` - Learning agents with sidecar
- `agent-complete-module.md` - Team coordination agents
- Detailed documentation and examples
- Advanced configuration options
## Quality Improvements
### ✅ Enhanced User Experience
**Better Guidance:**
- Clearer explanations of agent types and architecture
- More examples and practical illustrations
- Step-by-step progress tracking
- Better error prevention through improved instructions
**Improved Validation:**
- Conversational validation approach instead of technical checks
- User-friendly error messages and fixes
- Quality assurance built into each step
- Better success criteria and metrics
**Enhanced Customization:**
- More practical customization examples
- Better guidance for safe experimentation
- Clear explanation of benefits and risks
- Improved documentation for ongoing maintenance
### ✅ Developer Experience
**Better Maintainability:**
- Modular step structure easier to modify
- Clear separation of concerns
- Better documentation and comments
- Consistent patterns across steps
**Enhanced Debugging:**
- Individual step files easier to test
- Better error messages and context
- Clear success/failure criteria
- Improved logging and tracking
## Migration Validation Results
### ✅ Functionality Tests
**Core Workflow Execution:**
- [x] Optional brainstorming workflow integration
- [x] Agent type determination with architecture guidance
- [x] Four-field persona development with clear separation
- [x] Command building with workflow integration
- [x] Agent naming and identity creation
- [x] Type-specific YAML generation
- [x] Quality validation with conversational approach
- [x] Expert agent sidecar workspace creation
- [x] Customization file generation
- [x] Build tools handling and compilation
- [x] Completion celebration and next steps
**Asset Preservation:**
- [x] All documentation references maintained
- [x] Communication presets CSV copied
- [x] Reference agent examples copied
- [x] Brainstorming context preserved
- [x] Validation resources maintained
**Menu System:**
- [x] A/P/C menu options in every step
- [x] Proper menu handling logic
- [x] Advanced Elicitation integration
- [x] Party Mode workflow integration
### ✅ Performance Improvements
**Memory Usage:**
- Legacy: ~500KB single file load
- New: ~50KB per step (average)
- Improvement: 90% memory reduction per step
**Loading Time:**
- Legacy: Full workflow load upfront
- New: Individual step loading
- Improvement: ~70% faster initial load
**Maintainability:**
- Legacy: Monolithic file structure
- New: Modular step structure
- Improvement: Easier to modify and extend
## Migration Success Metrics
### ✅ Completeness: 100%
- All 13 XML steps converted to 11 focused step files
- All functionality preserved and enhanced
- All assets copied and referenced correctly
- All documentation maintained
### ✅ Quality: Improved
- Better user experience with clearer guidance
- Enhanced validation and error handling
- Improved maintainability and debugging
- More comprehensive templates and examples
### ✅ Performance: Optimized
- Step-specific loading reduces memory usage
- Faster execution through conditional loading
- Better resource utilization
- Improved scalability
## Conclusion
**✅ MIGRATION COMPLETE AND SUCCESSFUL**
The create-agent workflow has been successfully migrated from the legacy XML format to the new standalone format with:
- **100% Functionality Preservation:** All original features maintained
- **Significant Quality Improvements:** Better UX, validation, and documentation
- **Performance Optimizations:** Step-specific loading and resource efficiency
- **Enhanced Maintainability:** Modular structure and clear separation of concerns
- **Future-Ready Architecture:** Easy to extend and modify
The new workflow is ready for production use and provides a solid foundation for future enhancements while maintaining complete backward compatibility with existing agent builder functionality.

15
src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md
View File

@@ -41,13 +41,6 @@ Optional creative exploration to generate agent ideas through structured brainst
- ✅ You bring creative brainstorming expertise, user brings their goals and domain knowledge, together we explore innovative agent concepts
- ✅ Maintain collaborative inspiring tone throughout
### Step-Specific Rules:
- 🎯 Focus only on offering optional brainstorming and executing if chosen
- 🚫 FORBIDDEN to make brainstorming mandatory or pressure the user
- 💬 Approach: Present brainstorming as valuable optional exploration
- 📋 Brainstorming is completely optional - respect user's choice to skip
## EXECUTION PROTOCOLS:
- 🎯 Present brainstorming as optional first step with clear benefits
@@ -89,8 +82,7 @@ Wait for clear user response (yes/no or y/n).
**If user answers yes:**
- Load brainstorming workflow: `{brainstormWorkflow}`
- Pass context data: `{brainstormContext}`
- Load brainstorming workflow: `{brainstormWorkflow}` passing to the workflow the `{brainstormContext}` guidance
- Execute brainstorming session scoped specifically utilizing the brainstormContext to guide the scope and outcome
- Capture all brainstorming output for next step
- Return to this step after brainstorming completes
@@ -102,14 +94,11 @@ Wait for clear user response (yes/no or y/n).
### 3. Present MENU OPTIONS
Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
Display: "Are you ready to [C] Continue to Discovery?"
#### Menu Handling Logic:
- IF A: Execute {advancedElicitationTask}
- IF P: Execute {partyModeWorkflow}
- IF C: Load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#3-present-menu-options)
#### EXECUTION RULES:

8
src/modules/bmb/workflows/create-agent/steps/step-02-discover.md
View File

@@ -6,11 +6,11 @@ description: 'Discover the agent purpose and type through natural conversation'
workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent'
# File References
thisStepFile: '{workflow_path}/steps/step-02-discover.md'
nextStepFile: '{workflow_path}/steps/step-03-persona.md'
workflowFile: '{workflow_path}/workflow.md'
thisStepFile: './step-02-discover.md'
nextStepFile: './step-03-persona.md'
workflowFile: '../workflow.md'
agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
agentTypesGuide: '{project-root}/_bmad/bmb/docs/agents/understanding-agent-types.md'
agentTypesGuide: '../data/understanding-agent-types.md'
simpleExamples: '{workflow_path}/data/reference/agents/simple-examples/'
expertExamples: '{workflow_path}/data/reference/agents/expert-examples/'
moduleExamples: '{workflow_path}/data/reference/agents/module-examples/'