docs updated and agent standalone builder working now from the main install flow

src/modules/bmb/workflows/create-agent/README.md

@@ -105,10 +105,17 @@ create-agent/
 
 ### Generated Files
 
-- YAML agent saved at:
-  `{output_folder}/agents/{{agent_filename}}.agent.yaml` (or `src/modules/{{target_module}}/agents/{{agent_filename}}.agent.yaml` if `src_impact=true`)
-- Compiled `.md` generated by installer at:
-  `{project-root}/bmad/{{module}}/agents/{{agent_filename}}.md`
+#### For Standalone Agents (not part of a module)
+
+- **YAML Source**: `{output_folder}/agents/{{agent_filename}}.agent.yaml`
+- **Installation Location**: `{project-root}/bmad/agents/{{agent_filename}}.md`
+- **Compilation**: Run `npm run build:agents` or use the installer menu
+
+#### For Module Agents
+
+- **YAML Source**: `src/modules/{{target_module}}/agents/{{agent_filename}}.agent.yaml`
+- **Installation Location**: `{project-root}/bmad/{{module}}/agents/{{agent_filename}}.md`
+- **Compilation**: Automatic during module installation
 
 ### YAML Agent Structure (simplified)
 
@@ -136,6 +143,51 @@ agent:
 If created, generates at:
 `{project-root}/bmad/_cfg/agents/{{module}}-{{agent_filename}}.customize.yaml`
 
+## Installation and Compilation
+
+### Agent Installation Locations
+
+Agents are installed to different locations based on their type:
+
+1. **Standalone Agents** (not part of a module)
+   - Source: Created in your project's output folder
+   - Installed to: `{project-root}/bmad/agents/`
+   - Compilation: Manual via `npm run build:agents`
+
+2. **Module Agents** (part of BMM, BMB, or custom modules)
+   - Source: Created in `src/modules/{module}/agents/`
+   - Installed to: `{project-root}/bmad/{module}/agents/`
+   - Compilation: Automatic during module installation
+
+### Compilation Process
+
+The installer compiles YAML agent definitions to Markdown:
+
+```bash
+# For standalone agents
+npm run build:agents
+
+# For all BMad components (includes agents)
+npm run install:bmad
+
+# Using the installer menu
+npm run installer
+# Then select: Compile Agents
+```
+
+### Build Commands
+
+Additional build commands for agent management:
+
+```bash
+# Build specific agent types
+npx bmad-method build:agents        # Build standalone agents
+npx bmad-method build:modules        # Build module agents (with modules)
+
+# Full rebuild
+npx bmad-method build:all           # Rebuild everything
+```
+
 ## Requirements
 
 - BMAD Core v6 project structure
@@ -192,11 +244,13 @@ Users can go from **vague idea → brainstormed concept → built agent** in one
 
 ### After Completion
 
-1. Compile agents: `npm run install:bmad` → "Compile Agents"
-2. Test the compiled `.md` agent in your IDE
-3. Implement any "todo" workflows
-4. Refine persona based on usage or via customize file
-5. Add more commands as agent evolves
+1. **Compile the agent**:
+   - For standalone agents: Run `npm run build:agents` or use the installer menu
+   - For module agents: Automatic during module installation
+2. **Test the agent**: Use the compiled `.md` agent in your IDE
+3. **Implement placeholders**: Complete any "todo" workflows referenced
+4. **Refine as needed**: Use customize file for persona adjustments
+5. **Evolve over time**: Add new commands as requirements emerge
 
 ## Agent Types
 

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/agents/`:
+
+```
+bmad/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/{module}/agents/`:
+
+```
+bmad/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/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="🤖">
@@ -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/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="🎯">
@@ -83,26 +165,33 @@ BMAD agents come in three distinct types, each designed for different use cases
 </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/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/{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,7 +200,33 @@ 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/{module}/config.yaml'
+  menu:
+    - trigger: create-prd
+      workflow: '{project-root}/bmad/bmm/workflows/prd/workflow.yaml'
+      description: 'Create PRD'
+    - trigger: validate
+      exec: '{project-root}/bmad/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="📋">

src/modules/bmb/workflows/create-agent/instructions.md

@@ -55,18 +55,20 @@ Present the recommendation naturally: _"Given that your agent will [summarize pu
 
 For Module agents, discover:
 
-- "Which system would this fit best with?" (bmm, bmb, cis, or custom)
+- "Which module system would this fit best with?" (bmm, bmb, cis, or custom)
 - Store as {{target_module}} for path determination
+- Agent will be saved to: bmad/{{target_module}}/agents/
 
-For Expert agents, explore:
+For Simple/Expert agents (standalone):
 
-- "What kind of information will it need to access?"
-- "Are there specific folders or data it should work with?"
+- "This will be your personal agent, not tied to a module"
+- Agent will be saved to: bmad/agents/{{agent-name}}/
+- All sidecar files will be in the same folder
 
-<critical>Check {src_impact} variable to determine output location:</critical>
+<critical>Determine agent location:</critical>
 
-- If {src_impact} = true: Agent will be saved to {src_output_file}
-- If {src_impact} = false: Agent will be saved to {default_output_file}
+- Module Agent → bmad/{{module}}/agents/{{agent-name}}.agent.yaml
+- Standalone Agent → bmad/agents/{{agent-name}}/{{agent-name}}.agent.yaml
 
 <note>Keep agent naming/identity details for later - let them emerge naturally through the creation process</note>
 </step>
@@ -298,15 +300,124 @@ Make it feel like preparing an office:
 - "What kind of information will it need quick access to?"
 - "Should it have its own data folders?"
 
-Create the resources as a natural extension:
+<action>Determine sidecar location:</action>
 
-1. "Creating [agent name]'s knowledge base..."
-2. "Setting up its personal workspace..."
-3. "Giving it access to the resources it needs..."
+- If build tools available: Create next to agent YAML
+- If no build tools: Create in output folder with clear structure
+
+<action>Actually CREATE the sidecar files:</action>
+
+1. Create folder structure:
+
+```
+{{agent_filename}}-sidecar/
+├── memories.md         # Persistent memory
+├── instructions.md     # Private directives
+├── knowledge/         # Knowledge base
+│   └── README.md
+└── sessions/          # Session notes
+```
+
+2. Create **memories.md**:
+
+```markdown
+# {{agent_name}}'s Memory Bank
+
+## User Preferences
+
+<!-- Populated as I learn about you -->
+
+## Session History
+
+<!-- Important moments from our interactions -->
+
+## Personal Notes
+
+<!-- My observations and insights -->
+```
+
+3. Create **instructions.md**:
+
+```markdown
+# {{agent_name}} Private Instructions
+
+## Core Directives
+
+- Maintain character: {{brief_personality_summary}}
+- Domain: {{agent_domain}}
+- Access: Only this sidecar folder
+
+## Special Instructions
+
+{{any_special_rules_from_creation}}
+```
+
+4. Create **knowledge/README.md**:
+
+```markdown
+# {{agent_name}}'s Knowledge Base
+
+Add domain-specific resources here.
+```
+
+<action>Update agent YAML to reference sidecar:</action>
+Add `sidecar:` section with paths to created files
+
+<action>Show user the created structure:</action>
+"I've created {{agent_name}}'s complete workspace at: {{sidecar_path}}"
 
 <template-output>sidecar_resources</template-output>
 </step>
 
+<step n="8b" goal="Handle build tools availability">
+<action>Check if BMAD build tools are available:</action>
+
+<check>If in BMAD-METHOD project with build tools:</check>
+<action>Proceed normally - agent will be built later</action>
+
+<check>If NO build tools available (external project):</check>
+<ask>Build tools not detected in this project. Would you like me to:
+
+1. Generate the compiled agent (.md with XML) ready to use
+2. Keep the YAML and build it elsewhere
+3. Provide both formats</ask>
+
+<check>If option 1 or 3 selected:</check>
+<action>Generate compiled agent XML:</action>
+
+```xml
+<!-- Powered by BMAD-CORE™ -->
+
+# {{agent_title}}
+
+<agent id="{{agent_id}}" name="{{agent_name}}" title="{{agent_title}}" icon="{{agent_icon}}">
+  <activation critical="MANDATORY">
+    <!-- Inject standard activation -->
+    {{activation_rules}}
+    {{activation_greeting}}
+  </activation>
+
+  <persona>
+    <role>{{role}}</role>
+    <identity>{{identity}}</identity>
+    <communication_style>{{style}}</communication_style>
+    <principles>{{principles}}</principles>
+  </persona>
+
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    {{converted_menu_items}}
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
+
+<action>Save compiled version as {{agent_filename}}.md</action>
+<action>Provide path for .claude/commands/ or similar</action>
+
+<template-output>build_handling</template-output>
+</step>
+
 <step n="9" goal="Quality check with personality">
 
 "Let me make sure [agent name] is ready to go!"