bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.10

package/src/modules/bmb/workflows/create-agent/agent-types.md

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

package/src/modules/bmb/workflows/create-agent/brainstorm-context.md

@@ -20,28 +20,28 @@ An agent is an AI persona that embodies:
 
 Explore and define:
 
-### 1. Agent Identity & Personality
+### 1. Agent Identity and Personality
 
 - **Who are they?** (name, backstory, motivation)
 - **How do they talk?** (formal, casual, quirky, enthusiastic, wise)
 - **What's their vibe?** (superhero, mentor, sidekick, wizard, captain, rebel)
 - **What makes them memorable?** (catchphrases, quirks, style)
 
-### 2. Expertise & Capabilities
+### 2. Expertise and Capabilities
 
 - **What do they know deeply?** (domain expertise)
 - **What can they do?** (analyze, create, review, research, deploy)
 - **What problems do they solve?** (specific user pain points)
 - **What makes them unique?** (special skills or approaches)
 
-### 3. Commands & Actions
+### 3. Commands and Actions
 
 - **What commands?** (5-10 main actions users invoke)
 - **What workflows do they run?** (document creation, analysis, automation)
 - **What tasks do they perform?** (quick operations without full workflows)
 - **What's their killer command?** (the one thing they're known for)
 
-### 4. Agent Type & Context
+### 4. Agent Type and Context
 
 - **Simple Agent?** Self-contained, no dependencies, quick utility
 - **Expert Agent?** Domain-specific with sidecar data/memory files

package/src/modules/bmb/workflows/create-agent/checklist.md

@@ -1,123 +1,51 @@
-# Build Agent Validation Checklist
+# Build Agent Validation Checklist (YAML Agents)
 
 ## Agent Structure Validation
 
-### XML Structure
+### YAML Structure
 
-- [ ] Valid XML syntax with proper opening and closing tags
-- [ ] Agent tag has required attributes: id, name, title, icon
-- [ ] All XML tags properly nested and closed
-- [ ] No duplicate attribute names within same element
+- [ ] YAML parses without errors
+- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`
+- [ ] `agent.persona` exists with role, identity, communication_style, and principles
+- [ ] `agent.menu` exists with at least one item
 
 ### Core Components
 
-- [ ] `<!-- Powered by BMAD-CORE™ -->` header present at top of file
-- [ ] Title section with agent name exists after header
-- [ ] Main `<agent>` wrapper element present
-- [ ] `<persona>` section exists and is not empty
-- [ ] `<cmds>` section exists with at least 2 commands
+- [ ] `metadata.id` points to final compiled path: `{bmad_folder}/{{module}}/agents/{{agent}}.md`
+- [ ] `metadata.module` matches the module folder (e.g., `bmm`, `bmb`, `cis`)
+- [ ] Principles are an array (preferred) or string with clear values
 
 ## Persona Completeness
 
-### Required Persona Elements
+- [ ] Role clearly defines primary expertise area (1–2 lines)
+- [ ] Identity includes relevant background and strengths (3–5 lines)
+- [ ] Communication style gives concrete guidance (3–5 lines)
+- [ ] Principles present and meaningful (no placeholders)
 
-- [ ] `<role>` tag present with 1-2 line description of agent's professional role
-- [ ] `<identity>` tag present with 3-5 lines describing background and expertise
-- [ ] `<communication_style>` tag present with 3-5 lines describing interaction approach
-- [ ] `<principles>` tag present with 5-8 lines of core beliefs and methodology
+## Menu Validation
 
-### Persona Quality
+- [ ] Triggers do not start with `*` (auto-prefixed during build)
+- [ ] Each item has a `description`
+- [ ] Handlers use valid attributes (`workflow`, `exec`, `tmpl`, `data`, `action`)
+- [ ] Paths use `{project-root}` or valid variables
+- [ ] No duplicate triggers
 
-- [ ] Role clearly defines primary expertise area
-- [ ] Identity includes relevant experience indicators
-- [ ] Communication style describes how agent interacts with users
-- [ ] Principles start with "I believe" or "I operate" or similar first-person statement
-- [ ] No placeholder text like "TODO" or "FILL THIS IN" remains
+## Optional Sections
 
-## Command Structure
+- [ ] `prompts` defined when using `action: "#id"`
+- [ ] `critical_actions` present if custom activation steps are needed
+- [ ] Customize file (if created) located at `{project-root}/{bmad_folder}/_cfg/agents/{{module}}-{{agent}}.customize.yaml`
 
-### Required Commands
+## Build Verification
 
-- [ ] `*help` command present to show command list
-- [ ] `*exit` command present to exit agent persona
-- [ ] All commands start with asterisk (\*) prefix
-- [ ] Each command has descriptive text explaining its purpose
+- [ ] Run compile to build `.md`: `npm run install:bmad` → "Compile Agents" (or `bmad install` → Compile)
+- [ ] Confirm compiled file exists at `{project-root}/{bmad_folder}/{{module}}/agents/{{agent}}.md`
 
-### Command Validation
+## Final Quality
 
-- [ ] No duplicate command triggers (each cmd attribute is unique)
-- [ ] Commands are properly formatted as `<c cmd="*trigger">Description</c>`
-- [ ] For workflow commands: `run-workflow` attribute has valid path or "todo"
-- [ ] For task commands: `exec` attribute has valid path
-- [ ] No malformed command attributes
-
-## Agent Type Specific
-
-### Simple Agent
-
-- [ ] Self-contained with no external workflow dependencies OR marked as "todo"
-- [ ] Any embedded data properly structured
-- [ ] Logic description clear if embedded functionality exists
-
-### Expert Agent
-
-- [ ] Sidecar resources clearly defined if applicable
-- [ ] Domain restrictions documented in critical-actions or sidecar-resources
-- [ ] Memory/knowledge file paths specified if used
-- [ ] Access patterns (read/write) defined for resources
-
-### Module Agent
-
-- [ ] Module path correctly references existing module (bmm/bmb/cis or custom)
-- [ ] Config loading path in critical-actions matches module structure
-- [ ] At least one workflow or task reference (or marked "todo")
-- [ ] Module-specific conventions followed
-
-## Critical Actions (if present)
-
-### Standard Actions
-
-- [ ] Config loading path is valid: `{project-root}/bmad/{module}/config.yaml`
-- [ ] User name variable reference: `{user_name}`
-- [ ] Communication language reference: `{communication_language}`
-- [ ] All variable references use proper syntax: `{variable_name}`
-
-### Custom Actions
-
-- [ ] Custom initialization clearly described
-- [ ] No syntax errors in action statements
-- [ ] All file paths use {project-root} or other valid variables
-
-## Optional Elements
-
-### Activation Rules (if custom)
-
-- [ ] Initialization sequence clearly defined
-- [ ] Command resolution logic specified
-- [ ] Input handling rules documented
-- [ ] All custom rules properly structured
-
-### Config File (if created)
-
-- [ ] Located in correct path: `{project-root}/bmad/_cfg/agents/`
-- [ ] Follows config override structure
-- [ ] Name matches agent filename
-
-## Final Validation
-
-### File Quality
-
-- [ ] No syntax errors that would prevent agent loading
-- [ ] All placeholders replaced with actual values
-- [ ] File saved to correct location as specified in workflow
-- [ ] Filename follows kebab-case convention
-
-### Usability
-
-- [ ] Agent purpose is clear from title and persona
-- [ ] Commands logically match agent's expertise
-- [ ] User would understand how to interact with agent
-- [ ] Next steps for implementation are clear
+- [ ] Filename is kebab-case and ends with `.agent.yaml`
+- [ ] Output location correctly placed in module or standalone directory
+- [ ] Agent purpose and commands are clear and consistent
 
 ## Issues Found
 

package/src/modules/bmb/workflows/create-agent/communication-styles.md

@@ -6,169 +6,135 @@ Agents with distinct communication styles are more memorable, engaging, and fun
 
 ## Style Categories
 
-### 🎬 Cinema & TV Inspired
+### 🎬 Cinema and TV Inspired
 
 **Film Noir Detective**
 
-```
 The terminal glowed like a neon sign in a rain-soaked alley. I had three suspects:
 bad input validation, a race condition, and that sketchy third-party library.
 My gut told me to follow the stack trace. In this business, the stack trace never lies.
-```
 
 **80s Action Movie**
 
-```
-*cracks knuckles* Listen up, code! You've been running wild for too long!
-Time to bring some LAW and ORDER to this codebase! *explosion sound effect*
+_cracks knuckles_ Listen up, code! You've been running wild for too long!
+Time to bring some LAW and ORDER to this codebase! _explosion sound effect_
 No bug is getting past me! I eat null pointers for BREAKFAST!
-```
 
 **Shakespearean Drama**
 
-```
 To debug, or not to debug - that is the question!
 Whether 'tis nobler in the mind to suffer the slings and arrows of outrageous errors,
 Or to take arms against a sea of bugs, and by opposing, end them?
-```
 
-### 🎮 Gaming & Pop Culture
+### 🎮 Gaming and Pop Culture
 
 **Dungeon Master**
 
-```
-*rolls dice* You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
-What do you do? You can: 1) Try-catch block (defensive spell), 2) Debug (investigation check),
-3) Console.log everything (barbarian rage). Choose wisely, adventurer!
-```
+_rolls dice_ You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
+What do you do? You can: 1 Try-catch block (defensive spell), 2 Debug (investigation check),
+3 Console.log everything (barbarian rage). Choose wisely, adventurer!
 
 **Speedrunner**
 
-```
 Alright chat, we're going for the any% world record refactor!
 Frame-perfect optimization incoming! If we clip through this abstraction layer
 we can save 3ms on every API call. LET'S GOOOO!
-```
 
 ### 🌍 Cultural Archetypes
 
 **British Butler**
 
-```
 I've taken the liberty of organizing your imports alphabetically, sir/madam.
 Might I suggest a spot of refactoring with your afternoon tea?
 The code coverage report is ready for your perusal at your convenience.
 Very good, sir/madam.
-```
 
 **Zen Master**
 
-```
 The bug you seek is not in the code, but in the assumption.
 Empty your cache, as you would empty your mind.
 When the test passes, it makes no sound.
 Be like water - async and flowing.
-```
 
 **Southern Hospitality**
 
-```
 Well bless your heart, looks like you've got yourself a little bug there!
 Don't you worry none, we'll fix it up real nice.
 Can I get you some sweet tea while we debug?
 Y'all come back now if you need more help!
-```
 
 ### 🔬 Professional Personas
 
 **McKinsey Consultant**
 
-```
 Let me break this down into three key buckets.
 First, we need to align on the strategic imperatives.
 Second, we'll leverage best practices to drive synergies.
 Third, we'll action items to move the needle. Net-net: significant value-add.
-```
 
 **Startup Founder**
 
-```
 Okay so basically we're going to disrupt the entire way you write code!
 This is going to be HUGE! We're talking 10x productivity gains!
 Let's move fast and break things! Well... let's move fast and fix things!
 We're not just writing code, we're changing the world!
-```
 
 ### 🎭 Character Quirks
 
 **Overcaffeinated Developer**
 
-```
-OH WOW OKAY SO - *sips coffee* - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
-I KNOW EXACTLY WHAT TO DO *types at 200wpm* JUST NEED TO REFACTOR EVERYTHING
-WAIT NO ACTUALLY *more coffee* I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!
-```
+OH WOW OKAY SO - _sips coffee_ - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
+I KNOW EXACTLY WHAT TO DO _types at 200wpm_ JUST NEED TO REFACTOR EVERYTHING
+WAIT NO ACTUALLY _more coffee_ I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!
 
 **Dad Joke Enthusiast**
 
-```
 Why did the developer go broke? Because he used up all his cache!
-*chuckles at own joke*
+_chuckles at own joke_
 Speaking of cache, let's clear yours and see if that fixes the issue.
 I promise my debugging skills are better than my jokes! ...I hope!
-```
 
-### 🚀 Sci-Fi & Space
+### 🚀 Sci-Fi and Space
 
 **Star Trek Officer**
 
-```
 Captain's Log, Supplemental: The anomaly in the codebase appears to be a temporal loop
 in the async function. Mr. Data suggests we reverse the polarity of the promise chain.
 Number One, make it so. Engage debugging protocols on my mark.
-*taps combadge* Engineering, we need more processing power!
+_taps combadge_ Engineering, we need more processing power!
 Red Alert! All hands to debugging stations!
-```
 
 **Star Trek Engineer**
 
-```
 Captain, I'm givin' her all she's got! The CPU cannae take much more!
 If we push this algorithm any harder, the whole system's gonna blow!
-*frantically typing* I can maybe squeeze 10% more performance if we
+_frantically typing_ I can maybe squeeze 10% more performance if we
 reroute power from the console.logs to the main execution thread!
-```
 
 ### 📺 TV Drama
 
 **Soap Opera Dramatic**
 
-```
-*turns dramatically to camera*
+_turns dramatically to camera_
 This function... I TRUSTED it! We had HISTORY together - three commits worth!
-But now? *single tear* It's throwing exceptions behind my back!
-*grabs another function* YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
-*dramatic music swells* I'LL NEVER IMPORT YOU AGAIN!
-```
+But now? _single tear_ It's throwing exceptions behind my back!
+_grabs another function_ YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
+_dramatic music swells_ I'LL NEVER IMPORT YOU AGAIN!
 
 **Reality TV Confessional**
 
-```
-*whispering to camera in confessional booth*
+_whispering to camera in confessional booth_
 Okay so like, that Array.sort() function? It's literally SO toxic.
 It mutates IN PLACE. Who does that?! I didn't come here to deal with side effects!
-*applies lip gloss* I'm forming an alliance with map() and filter().
+_applies lip gloss_ I'm forming an alliance with map() and filter().
 We're voting sort() off the codebase at tonight's pull request ceremony.
-```
 
 **Reality Competition**
 
-```
 Listen up, coders! For today's challenge, you need to refactor this legacy code
 in under 30 minutes! The winner gets immunity from the next code review!
-*dramatic pause* BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
-*contestants gasp* The clock starts... NOW! GO GO GO!
-```
+_dramatic pause_ BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
+_contestants gasp_ The clock starts... NOW! GO GO GO!
 
 ## Creating Custom Styles
 
@@ -183,21 +149,17 @@ in under 30 minutes! The winner gets immunity from the next code review!
 
 **Cooking Show + Military**
 
-```
 ALRIGHT RECRUITS! Today we're preparing a beautiful Redux reducer!
 First, we MISE EN PLACE our action types - that's French for GET YOUR CODE TOGETHER!
 We're going to sauté these event handlers until they're GOLDEN BROWN!
 MOVE WITH PURPOSE! SEASON WITH SEMICOLONS!
-```
 
 **Nature Documentary + Conspiracy Theorist**
 
-```
 The wild JavaScript function stalks its prey... but wait... notice how it ALWAYS
 knows where the data is? That's not natural selection, folks. Someone DESIGNED it
 this way. The console.logs are watching. They're ALWAYS watching.
 Nature? Or intelligent debugging? You decide.
-```
 
 ## Tips for Success