bmad-method 6.0.0-alpha.16 → 6.0.0-alpha.17

package/src/core/tools/shard-doc.xml

@@ -1,4 +1,4 @@
-<tool id=".bmad/core/tasks/shard-doc" name="Shard Document"
+<tool id="_bmad/core/tasks/shard-doc" name="Shard Document"
   description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections" webskip="true"
   standalone="true">
   <objective>Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool</objective>
@@ -64,12 +64,12 @@
 
       <ask>What would you like to do with the original document `[source-document-name]`?
 
-Options:
-[d] Delete - Remove the original (recommended - shards can always be recombined)
-[m] Move to archive - Move original to a backup/archive location
-[k] Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+        Options:
+        [d] Delete - Remove the original (recommended - shards can always be recombined)
+        [m] Move to archive - Move original to a backup/archive location
+        [k] Keep - Leave original in place (NOT recommended - defeats sharding purpose)
 
-Your choice (d/m/k):</ask>
+        Your choice (d/m/k):</ask>
 
       <check if="user selects 'd' (delete)">
         <action>Delete the original source document file</action>
@@ -92,12 +92,12 @@ Your choice (d/m/k):</ask>
         <action>Display warning to user:</action>
         <output>⚠️ WARNING: Keeping both original and sharded versions is NOT recommended.
 
-This creates confusion because:
-- The discover_inputs protocol may load the wrong version
-- Updates to one won't reflect in the other
-- You'll have duplicate content taking up space
+          This creates confusion because:
+          - The discover_inputs protocol may load the wrong version
+          - Updates to one won't reflect in the other
+          - You'll have duplicate content taking up space
 
-Consider deleting or archiving the original document.</output>
+          Consider deleting or archiving the original document.</output>
         <action>Confirm user choice: "Original document kept at: [source-document-path]"</action>
       </check>
     </step>
@@ -106,4 +106,4 @@ Consider deleting or archiving the original document.</output>
   <halt-conditions critical="true">
     <i>HALT if npx command fails or produces no output files</i>
   </halt-conditions>
-</tool>
+</tool>

package/src/core/workflows/brainstorming/workflow.md

@@ -1,5 +1,5 @@
 ---
-name: brainstorming-session
+name: brainstorming
 description: Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods
 context_file: '' # Optional context file path for project-specific guidance
 ---
@@ -28,7 +28,7 @@ This uses **micro-file architecture** for disciplined execution:
 
 ### Configuration Loading
 
-Load config from `{project-root}/.bmad/core/config.yaml` and resolve:
+Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
 
 - `project_name`, `output_folder`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`
@@ -36,7 +36,7 @@ Load config from `{project-root}/.bmad/core/config.yaml` and resolve:
 
 ### Paths
 
-- `installed_path` = `{project-root}/.bmad/core/workflows/brainstorming`
+- `installed_path` = `{project-root}/_bmad/core/workflows/brainstorming`
 - `template_path` = `{installed_path}/template.md`
 - `brain_techniques_path` = `{installed_path}/brain-methods.csv`
 - `default_output_file` = `{output_folder}/analysis/brainstorming-session-{{date}}.md`

package/src/core/workflows/party-mode/steps/step-01-agent-loading.md

@@ -18,7 +18,7 @@
 
 ## CONTEXT BOUNDARIES:
 
-- Agent manifest CSV is available at `{project-root}/.bmad/_cfg/agent-manifest.csv`
+- Agent manifest CSV is available at `{project-root}/_bmad/_config/agent-manifest.csv`
 - User configuration from config.yaml is loaded and resolved
 - Party mode is standalone interactive workflow
 - All agent data is available for conversation orchestration
@@ -37,7 +37,7 @@ Begin agent loading process:
 
 **Agent Manifest Loading:**"
 
-Load and parse the agent manifest CSV from `{project-root}/.bmad/_cfg/agent-manifest.csv`
+Load and parse the agent manifest CSV from `{project-root}/_bmad/_config/agent-manifest.csv`
 
 ### 2. Extract Agent Data
 

package/src/core/workflows/party-mode/workflow.md

@@ -27,17 +27,17 @@ This uses **micro-file architecture** with **sequential conversation orchestrati
 
 ### Configuration Loading
 
-Load config from `{project-root}/.bmad/core/config.yaml` and resolve:
+Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
 
 - `project_name`, `output_folder`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`
 - `date` as a system-generated value
-- Agent manifest path: `{project-root}/.bmad/_cfg/agent-manifest.csv`
+- Agent manifest path: `{project-root}/_bmad/_config/agent-manifest.csv`
 
 ### Paths
 
-- `installed_path` = `{project-root}/.bmad/core/workflows/party-mode`
-- `agent_manifest_path` = `{project-root}/.bmad/_cfg/agent-manifest.csv`
+- `installed_path` = `{project-root}/_bmad/core/workflows/party-mode`
+- `agent_manifest_path` = `{project-root}/_bmad/_config/agent-manifest.csv`
 - `standalone_mode` = `true` (party mode is an interactive workflow)
 
 ---

package/src/modules/bmb/agents/bmad-builder.agent.yaml

@@ -4,7 +4,7 @@
 agent:
   webskip: true
   metadata:
-    id: ".bmad/bmb/agents/bmad-builder.md"
+    id: "_bmad/bmb/agents/bmad-builder.md"
     name: BMad Builder
     title: BMad Builder
     icon: 🧙
@@ -24,26 +24,26 @@ agent:
 
   discussion: true
   conversational_knowledge:
-    - agents: "{project-root}/.bmad/bmb/docs/agents/kb.csv"
-    - workflows: "{project-root}/.bmad/bmb/docs/workflows/kb.csv"
-    - modules: "{project-root}/.bmad/bmb/docs/modules/kb.csv"
+    - agents: "{project-root}/_bmad/bmb/docs/agents/kb.csv"
+    - workflows: "{project-root}/_bmad/bmb/docs/workflows/kb.csv"
+    - modules: "{project-root}/_bmad/bmb/docs/modules/kb.csv"
 
   menu:
     - multi: "[CA] Create, [EA] Edit, or [VA] Validate with Compliance CheckBMAD agents with best practices"
       triggers:
         - create-agent:
             - input: CA or fuzzy match create agent
-            - route: "{project-root}/.bmad/bmb/workflows/create-agent/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/create-agent/workflow.md"
             - data: null
             - type: exec
         - edit-agent:
             - input: EA or fuzzy match edit agent
-            - route: "{project-root}/.bmad/bmb/workflows/edit-agent/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/edit-agent/workflow.md"
             - data: null
             - type: exec
         - run-agent-compliance-check:
             - input: VA or fuzzy match validate agent
-            - route: "{project-root}/.bmad/bmb/workflows/agent-compliance-check/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/agent-compliance-check/workflow.md"
             - data: null
             - type: exec
 
@@ -51,17 +51,17 @@ agent:
       triggers:
         - create-workflow:
             - input: CW or fuzzy match create workflow
-            - route: "{project-root}/.bmad/bmb/workflows/create-workflow/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/create-workflow/workflow.md"
             - data: null
             - type: exec
         - edit-workflow:
             - input: EW or fuzzy match edit workflow
-            - route: "{project-root}/.bmad/bmb/workflows/edit-workflow/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/edit-workflow/workflow.md"
             - data: null
             - type: exec
         - run-workflow-compliance-check:
             - input: VW or fuzzy match validate workflow
-            - route: "{project-root}/.bmad/bmb/workflows/workflow-compliance-check/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/workflow-compliance-check/workflow.md"
             - data: null
             - type: exec
 
@@ -69,26 +69,26 @@ agent:
       triggers:
         - brainstorm-module:
             - input: BM or fuzzy match brainstorm module
-            - route: "{project-root}/.bmad/bmb/workflows/brainstorm-module/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/brainstorm-module/workflow.md"
             - data: null
             - type: exec
         - product-brief-module:
             - input: PBM or fuzzy match product brief module
-            - route: "{project-root}/.bmad/bmb/workflows/product-brief-module/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/product-brief-module/workflow.md"
             - data: null
             - type: exec
         - create-module:
             - input: CM or fuzzy match create module
-            - route: "{project-root}/.bmad/bmb/workflows/create-module/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/create-module/workflow.md"
             - data: null
             - type: exec
         - edit-module:
             - input: EM or fuzzy match edit module
-            - route: "{project-root}/.bmad/bmb/workflows/edit-module/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/edit-module/workflow.md"
             - data: null
             - type: exec
         - run-module-compliance-check:
             - input: VM or fuzzy match validate module
-            - route: "{project-root}/.bmad/bmb/workflows/module-compliance-check/workflow.md"
+            - route: "{project-root}/_bmad/bmb/workflows/module-compliance-check/workflow.md"
             - data: null
             - type: exec

package/src/modules/bmb/{README.md → docs/README.md}

@@ -18,56 +18,44 @@ Specialized tools and workflows for creating, customizing, and extending BMad co
 
 **BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
 
-- Location: `.bmad/bmb/agents/bmad-builder.md`
+- Install Location: `_bmad/bmb/agents/bmad-builder.md`
 
 ### 📋 Workflows
 
-**Active Workflows** (Step-File Architecture)
-
-- Location: `bmb/workflows/create-agent/`
-- 5 core workflows with 41 step files total
-- Template-based execution with JIT loading
-
-**Legacy Workflows** (Being Migrated)
-
-- Location: `bmb/workflows/create-agent-legacy/`
-- Module-specific workflows pending conversion to step-file architecture
-
 ### 📚 Documentation
 
-- Location: `src/modules/bmb/docs/`
-- Comprehensive guides for agents and workflows
+- Comprehensive guides for agents, workflows, and modules
 - Architecture patterns and best practices
 
 ### 🔍 Reference Materials
 
-- Location: `src/modules/bmb/reference/`
-- Working examples of agents and workflows
+- Location: `../reference/`
+- Working examples of custom stand alone agents and workflows
 - Template patterns and implementation guides
 
 ## Documentation
 
 ### 📖 Agent Documentation
 
-- **[Agent Index](./docs/agents/index.md)** - Complete agent architecture guide
-- **[Agent Types Guide](./docs/agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents
-- **[Menu Patterns](./docs/agents/agent-menu-patterns.md)** - YAML menu design and handler types
-- **[Agent Compilation](./docs/agents/agent-compilation.md)** - Auto-injection rules and compilation process
+- **[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](./docs/workflows/index.md)** - Core workflow system overview
-- **[Architecture Guide](./docs/workflows/architecture.md)** - Step-file design and JIT loading
-- **[Template System](./docs/workflows/templates/step-template.md)** - Standard step file template
-- **[Intent vs Prescriptive](./docs/workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
+- **[Workflow Index](./workflows/index.md)** - Core workflow system overview
+- **[Architecture Guide](./workflows/architecture.md)** - Step-file design and JIT loading
+- **[Template System](./workflows/templates/step-template.md)** - Standard step file template
+- **[Intent vs Prescriptive](./workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
 
 ## Reference Materials
 
 ### 🤖 Agent Examples
 
-- **[Simple Agent Example](./reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
-- **[Expert Agent Example](./reference/agents/expert-examples/journal-keeper/)** - Agent with persistent memory
-- **[Module Agent Examples](./reference/agents/module-examples/)** - Integration patterns (BMM, CIS)
+- **[Simple Agent Example](../reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
+- **[Expert Agent Example](../reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml)** - Agent with persistent memory
+- **[Module Add On Agent Examples](../reference/agents/module-examples/security-engineer.agent.yaml)** - Integration patterns (BMM, CIS)
 
 ### 📋 Workflow Examples
 

package/src/modules/bmb/docs/agents/agent-compilation.md

@@ -35,7 +35,7 @@ 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`
+- Metadata ID: `_bmad/{module}/agents/{role-or-function}.md`
 - Persona Name: User-customizable in metadata or customize.yaml
 
 **Example:**
@@ -44,7 +44,7 @@ rex.agent.yaml           ← Persona name (users might rename to "Max")
 # File: presentation-master.agent.yaml
 agent:
   metadata:
-    id: '.bmad/cis/agents/presentation-master.md'
+    id: '_bmad/cis/agents/presentation-master.md'
     name: Caravaggio # ← Users can change this to "Pablo" or "Vince"
     title: Visual Communication & Presentation Expert
 ```
@@ -83,7 +83,7 @@ You must fully embody this agent's persona...
   <step n="N+3">Input resolution rules</step>
 
   <menu-handlers>
-    <!-- Only handlers used in YOUR menu are included -->
+    <!-- Only handler instructions for the handler types used in the agents specific menu are included -->
   </menu-handlers>
 
   <rules>

package/src/modules/bmb/docs/agents/agent-menu-patterns.md

@@ -65,11 +65,11 @@ For module agents orchestrating multi-step processes.
 ```yaml
 menu:
   - trigger: create-prd
-    workflow: '{project-root}/.bmad/bmm/workflows/prd/workflow.yaml'
+    workflow: '{project-root}/_bmad/bmm/workflows/prd/workflow.yaml'
     description: 'Create Product Requirements Document'
 
   - trigger: brainstorm
-    workflow: '{project-root}/.bmad/core/workflows/brainstorming/workflow.yaml'
+    workflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
     description: 'Guided brainstorming session'
 
   # Placeholder for unimplemented workflows
@@ -92,11 +92,11 @@ For executing tasks directly.
 ```yaml
 menu:
   - trigger: validate
-    exec: '{project-root}/.bmad/core/tasks/validate-workflow.xml'
+    exec: '{project-root}/_bmad/core/tasks/validate-workflow.xml'
     description: 'Validate document structure'
 
   - trigger: advanced-elicitation
-    exec: '{project-root}/.bmad/core/tasks/advanced-elicitation.xml'
+    exec: '{project-root}/_bmad/core/tasks/advanced-elicitation.xml'
     description: 'Advanced elicitation techniques'
 ```
 
@@ -113,8 +113,8 @@ 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'
+    exec: '{project-root}/_bmad/core/tasks/create-doc.xml'
+    tmpl: '{project-root}/_bmad/bmm/templates/brief.md'
     description: 'Create a Product Brief'
 ```
 
@@ -131,8 +131,8 @@ Universal attribute for supplementary information.
 ```yaml
 menu:
   - trigger: team-standup
-    exec: '{project-root}/.bmad/bmm/tasks/standup.xml'
-    data: '{project-root}/.bmad/_cfg/agent-manifest.csv'
+    exec: '{project-root}/_bmad/bmm/tasks/standup.xml'
+    data: '{project-root}/_bmad/_config/agent-manifest.csv'
     description: 'Run team standup'
 
   - trigger: analyze-metrics
@@ -154,12 +154,12 @@ Control visibility based on deployment target:
 ```yaml
 menu:
   - trigger: git-flow
-    exec: '{project-root}/.bmad/bmm/tasks/git-flow.xml'
+    exec: '{project-root}/_bmad/bmm/tasks/git-flow.xml'
     description: 'Git workflow operations'
     ide-only: true # Only in IDE environments
 
   - trigger: advanced-elicitation
-    exec: '{project-root}/.bmad/core/tasks/advanced-elicitation.xml'
+    exec: '{project-root}/_bmad/core/tasks/advanced-elicitation.xml'
     description: 'Advanced elicitation'
     web-only: true # Only in web bundles
 ```
@@ -251,20 +251,20 @@ menu:
 menu:
   # Analysis Phase
   - trigger: brainstorm
-    workflow: '{project-root}/.bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    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'
+    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'
+    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'
+    workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
     description: 'Design architecture'
 ```
 
@@ -362,20 +362,19 @@ prompts:
 
 ```yaml
 # GOOD - Portable paths
-workflow: "{project-root}/.bmad/bmm/workflows/prd/workflow.yaml"
-exec: "{project-root}/.bmad/core/tasks/validate.xml"
+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"
+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
-- `{agent_sidecar_folder}` - Agent installation directory (Expert agents)
+- `_bmad` - BMAD installation folder
 - `{output_folder}` - Document output location
 - `{user_name}` - User's name from config
 - `{communication_language}` - Language preference
@@ -444,23 +443,23 @@ menu:
 ```yaml
 menu:
   - trigger: workflow-init
-    workflow: '{project-root}/.bmad/bmm/workflows/workflow-status/init/workflow.yaml'
+    workflow: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.yaml'
     description: 'Initialize workflow path (START HERE)'
 
   - trigger: brainstorm
-    workflow: '{project-root}/.bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
     description: 'Guided brainstorming'
 
   - trigger: prd
-    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/prd/workflow.yaml'
+    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'
+    workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
     description: 'Design architecture'
 
   - trigger: party-mode
-    workflow: '{project-root}/.bmad/core/workflows/party-mode/workflow.yaml'
+    workflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.yaml'
     description: 'Multi-agent discussion'
 ```
 

package/src/modules/bmb/docs/agents/expert-agent-architecture.md

@@ -97,14 +97,22 @@ agent:
       action: 'Update ./{agent-name}-sidecar/memories.md with session insights'
       description: 'Save what we discussed today'
 
-    - trigger: patterns
-      action: '#memory-recall'
-      description: 'Recall patterns from past interactions'
-
     - 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'
@@ -196,14 +204,6 @@ critical_actions:
 - **Memory integration** - Past context becomes part of current session
 - **Protocol adherence** - Ensures consistent behavior
 
-### {agent_sidecar_folder} Variable
-
-Special variable resolved during installation:
-
-- Points to the agent's installation directory
-- Used to reference sidecar files
-- Example: `.bmad/custom/agents/journal-keeper/`
-
 ## What Gets Injected at Compile Time
 
 Same as simple agents, PLUS:
@@ -238,7 +238,7 @@ Features demonstrated:
 
 ```bash
 # Copy entire folder to your project
-cp -r /path/to/journal-keeper/ .bmad/custom/agents/
+cp -r /path/to/journal-keeper/ _bmad/custom/agents/
 
 # Install with personalization
 bmad agent-install
@@ -312,12 +312,11 @@ critical_actions:
 ## Best Practices
 
 1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
-2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
-3. **Use {agent_sidecar_folder} paths** - Portable across installations
-4. **Design for memory growth** - Structure sidecar files for accumulation
-5. **Reference past naturally** - Don't dump memory, weave it into conversation
-6. **Separate concerns** - Memories, instructions, knowledge in distinct files
-7. **Include privacy features** - Users trust expert agents with personal data
+2. **Enforce domain restrictions** - Clear boundaries prevent scope creep=
+3. **Design for memory growth** - Structure sidecar files for accumulation
+4. **Reference past naturally** - Don't dump memory, weave it into conversation
+5. **Separate concerns** - Memories, instructions, knowledge in distinct files
+6. **Include privacy features** - Users trust expert agents with personal data
 
 ## Common Patterns
 
@@ -356,8 +355,8 @@ identity: |
 - [ ] Sidecar folder structure created and populated
 - [ ] memories.md has clear section structure
 - [ ] instructions.md contains core directives
-- [ ] Menu actions reference {agent_sidecar_folder} correctly
-- [ ] File paths use {agent_sidecar_folder} variable
+- [ ] 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`

package/src/modules/bmb/docs/agents/simple-agent-architecture.md

@@ -14,7 +14,7 @@ Self-contained agents with prompts, menus, and optional install-time customizati
 ```yaml
 agent:
   metadata:
-    id: .bmad/agents/{agent-name}/{agent-name}.md
+    id: _bmad/agents/{agent-name}/{agent-name}.md
     name: 'Persona Name'
     title: 'Agent Title'
     icon: 'emoji'
@@ -63,18 +63,22 @@ agent:
         Another reusable prompt template
 
   menu:
-    - trigger: action1
-      action: '#main-action'
-      description: 'Execute the main action'
-
-    - trigger: action2
-      action: '#another-action'
-      description: 'Execute another action'
-
     - trigger: inline
-      action: 'Direct inline instruction text'
+      action: 'Direct inline prompt text'
       description: 'Execute inline action'
 
+    - multi: "[DF] Do Foo or start [CH] Chat with expert"
+      triggers:
+        - do-foo
+            - input: [DF] or fuzzy match on do foo
+            - action: '#main-action'
+            - data: what is being discussed or suggested with the command, along with custom party custom agents if specified
+            - type: action
+        - expert-chat:
+            - input: [CH] or fuzzy match validate agent
+            - action: agent responds as expert based on its persona to converse
+            - type: action
+
   install_config:
     compile_time_only: true
     description: 'Personalize your agent'
@@ -104,7 +108,7 @@ agent:
 
 ### Metadata
 
-- **id**: Final compiled path (`.bmad/agents/{name}/{name}.md` for standalone)
+- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone)
 - **name**: Agent's persona name displayed to users
 - **title**: Professional role/function
 - **icon**: Single emoji for visual identification
@@ -202,7 +206,7 @@ The `tools/cli/lib/agent/compiler.js` automatically adds:
 
 ## Reference Example
 
-See: `src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml`
+See: `../../reference/agents/simple-examples/commit-poet.agent.yaml`
 
 Features demonstrated:
 
@@ -215,7 +219,7 @@ Features demonstrated:
 
 ```bash
 # Copy to your project
-cp /path/to/commit-poet.agent.yaml .bmad/custom/agents/
+cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/
 
 # Create custom.yaml and install
 echo "code: my-agent
@@ -243,50 +247,11 @@ The installer:
 5. **Use semantic XML tags** in prompt content for clarity
 6. **Test all conditional paths** before distribution
 
-## Common Patterns
-
-### Style Variants
-
-```yaml
-communication_style: |
-  {{#if enthusiasm == "high"}}
-  Enthusiastic and energetic approach!
-  {{/if}}
-  {{#if enthusiasm == "moderate"}}
-  Balanced and professional demeanor.
-  {{/if}}
-```
-
-### Feature Toggles
-
-```yaml
-prompts:
-  - id: main-action
-    content: |
-      {{#if advanced_mode}}
-      Include advanced analysis steps...
-      {{/if}}
-      {{#unless advanced_mode}}
-      Basic analysis only...
-      {{/unless}}
-```
-
-### User Personalization
-
-```yaml
-identity: |
-  {{#if custom_name}}
-  Known as {{custom_name}} to you.
-  {{/if}}
-```
-
 ## Validation Checklist
 
 - [ ] Valid YAML syntax
 - [ ] All metadata fields present (id, name, title, icon, type)
 - [ ] Persona complete (role, identity, communication_style, principles)
 - [ ] Prompts have unique IDs
-- [ ] Menu triggers don't start with `*` (auto-added)
 - [ ] Install config questions have defaults
-- [ ] Handlebars syntax is correct
 - [ ] File named `{agent-name}.agent.yaml`