diff --git a/src/modules/bmb/docs/agents/agent-compilation.md b/src/modules/bmb/docs/agents/agent-compilation.md
index 28b949ef..51651de5 100644
--- a/src/modules/bmb/docs/agents/agent-compilation.md
+++ b/src/modules/bmb/docs/agents/agent-compilation.md
@@ -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
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
Input resolution rules
-
-
-
-
-
-
-
-
```
-**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
-
-
-
- ...
-
-
- ...
-
-
- ...
-
-
- ...
-
-
-```
-
-**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
-
-
-Load persona...
-Load config...
-Remember user...
-Communicate in language...
-Show greeting + menu...
-STOP and WAIT...
-Input resolution...
-
-
-
-
- action="#id" → Find prompt, execute
- action="text" → Execute directly
-
-
-
-
-
- - Stay in character...
- - Number lists...
- - Load files when executing...
-
-
-
- Code Review Expert
- Systematic reviewer...
- Direct and constructive
- Code should be readable
-
-
-
-
-Analyze code for issues...
-
-
-
-
-
-\`\`\`
-```
-
## 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. - [MH] Redisplay Menu Help
+ 2. - [CH] Chat with the Agent about anything
+ 3. - [PM] Start Party Mode
+ 4. - [DA] Dismiss Agent
4. **Handlers auto-detected** - Only what you use is included
5. **Rules standardized** - Consistent behavior across agents
diff --git a/src/modules/bmb/docs/agents/agent-menu-patterns.md b/src/modules/bmb/docs/agents/agent-menu-patterns.md
index effbee44..b32788f2 100644
--- a/src/modules/bmb/docs/agents/agent-menu-patterns.md
+++ b/src/modules/bmb/docs/agents/agent-menu-patterns.md
@@ -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.
+
**Reference to Prompt ID:**
```yaml
@@ -42,13 +50,23 @@ menu:
action: '#analyze-code'
description: 'Analyze code patterns'
```
+
**Inline Instruction:**
```yaml
menu:
- trigger: quick-check
- action: 'Perform a quick syntax validation on the current file'
+ action: |
+
+ Analyze the provided code for patterns and issues.
+
+
+
+ 1. Identify code structure
+ 2. Check for anti-patterns
+ 3. Suggest improvements
+
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: |
+ What the prompt achieves
- What this prompt accomplishes
+ Step 1: Foo
+ Step 2: Bar
+ ...
-
-
- 1. First step
- {{#if custom_option}}
- 2. Conditional step
- {{/if}}
- 3. Final step
-
-
-
- Expected structure of results
-
+
+ etc...
```
### Semantic XML Tags in Prompts
-Use XML tags to structure prompt content:
+Use XML tags to structure prompt content such as:
-- `` - What to do
-- `` - Step-by-step approach
+- `` - What to do
+- `` - Step-by-step approach
- `` - Expected results
-- `` - Sample outputs
-- `` - Limitations
-- `` - 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.
-```
+- `` - 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'
```
diff --git a/src/modules/bmb/docs/agents/expert-agent-architecture.md b/src/modules/bmb/docs/agents/expert-agent-architecture.md
index ad50ca9d..4f9fd970 100644
--- a/src/modules/bmb/docs/agents/expert-agent-architecture.md
+++ b/src/modules/bmb/docs/agents/expert-agent-architecture.md
@@ -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: |
-
- Guide user through the primary function.
- {{#if tone_style == "gentle"}}
- Use gentle, supportive approach.
- {{/if}}
-
-
-
- 1. Understand context
- 2. Provide guidance
- 3. Record insights
-
-
- - id: memory-recall
- content: |
-
- Access and share relevant memories.
-
-
- 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/`
diff --git a/src/modules/bmb/docs/agents/index.md b/src/modules/bmb/docs/agents/index.md
deleted file mode 100644
index 059ba0bf..00000000
--- a/src/modules/bmb/docs/agents/index.md
+++ /dev/null
@@ -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`
diff --git a/src/modules/bmb/docs/agents/kb.csv b/src/modules/bmb/docs/agents/kb.csv
deleted file mode 100644
index e69de29b..00000000
diff --git a/src/modules/bmb/docs/agents/simple-agent-architecture.md b/src/modules/bmb/docs/agents/simple-agent-architecture.md
index b1ae901b..44cfddfc 100644
--- a/src/modules/bmb/docs/agents/simple-agent-architecture.md
+++ b/src/modules/bmb/docs/agents/simple-agent-architecture.md
@@ -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
diff --git a/src/modules/bmb/docs/agents/understanding-agent-types.md b/src/modules/bmb/docs/agents/understanding-agent-types.md
deleted file mode 100644
index c33f7147..00000000
--- a/src/modules/bmb/docs/agents/understanding-agent-types.md
+++ /dev/null
@@ -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.
diff --git a/src/modules/bmb/docs/index.md b/src/modules/bmb/docs/index.md
deleted file mode 100644
index 7826d159..00000000
--- a/src/modules/bmb/docs/index.md
+++ /dev/null
@@ -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.
diff --git a/src/modules/bmb/docs/workflows/architecture.md b/src/modules/bmb/docs/workflows/architecture.md
index ae3db202..d4ccac4e 100644
--- a/src/modules/bmb/docs/workflows/architecture.md
+++ b/src/modules/bmb/docs/workflows/architecture.md
@@ -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/
diff --git a/src/modules/bmb/docs/workflows/common-workflow-tools.csv b/src/modules/bmb/docs/workflows/common-workflow-tools.csv
index 63718b6f..cc68b7ed 100644
--- a/src/modules/bmb/docs/workflows/common-workflow-tools.csv
+++ b/src/modules/bmb/docs/workflows/common-workflow-tools.csv
@@ -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
diff --git a/src/modules/bmb/docs/workflows/index.md b/src/modules/bmb/docs/workflows/index.md
deleted file mode 100644
index ecc13bbf..00000000
--- a/src/modules/bmb/docs/workflows/index.md
+++ /dev/null
@@ -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._
diff --git a/src/modules/bmb/docs/workflows/kb.csv b/src/modules/bmb/docs/workflows/kb.csv
deleted file mode 100644
index e69de29b..00000000
diff --git a/src/modules/bmb/docs/workflows/terms.md b/src/modules/bmb/docs/workflows/terms.md
index 78eb8167..71477ede 100644
--- a/src/modules/bmb/docs/workflows/terms.md
+++ b/src/modules/bmb/docs/workflows/terms.md
@@ -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
diff --git a/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md b/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md
index 56ba23c1..376d34e0 100644
--- a/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md
+++ b/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md
@@ -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 `.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//...` 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
-- [ ] `` tag has id, name, title, icon attributes
-- [ ] `` section is present with proper steps
-- [ ] `` section compiled correctly
-- [ ] `