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

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

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Build Agent workflow is an interactive agent builder that guides you through creating BMAD Core compliant agents with proper persona, activation rules, and command structure. It supports three agent types: Simple (self-contained), Expert (with sidecar resources), and Module (full-featured with workflows).
+The Build Agent workflow is an interactive agent builder that guides you through creating BMAD Core compliant agents as YAML source files that compile to final `.md` during install. It supports three agent types: Simple (self-contained), Expert (with sidecar resources), and Module (full-featured with workflows).
 
 ## Key Features
 
@@ -10,8 +10,8 @@ The Build Agent workflow is an interactive agent builder that guides you through
 - **Three Agent Types**: Simple, Expert, and Module agents with appropriate structures
 - **Persona Development**: Guided creation of role, identity, communication style, and principles
 - **Command Builder**: Interactive command definition with workflow/task/action patterns
-- **Validation Built-In**: Ensures XML structure and BMAD Core compliance
-- **Config File Support**: Optional agent config for persona overrides
+- **Validation Built-In**: Ensures YAML structure and BMAD Core compliance
+- **Customize Support**: Optional `customize.yaml` for persona/menu overrides and critical actions
 - **Sidecar Resources**: Setup for Expert agents with domain-specific data
 
 ## Usage
@@ -19,7 +19,7 @@ The Build Agent workflow is an interactive agent builder that guides you through
 ### Basic Invocation
 
 ```bash
-workflow build-agent
+workflow create-agent
 ```
 
 ### Through BMad Builder Agent
@@ -49,7 +49,7 @@ The workflow includes an optional brainstorming phase (Step -1) that helps you e
 ### Files Included
 
 ```
-build-agent/
+create-agent/
 ├── workflow.yaml                  # Configuration
 ├── instructions.md                # Step-by-step guide
 ├── checklist.md                   # Validation criteria
@@ -94,49 +94,99 @@ build-agent/
 
 ### Phase 4: Finalization (Steps 5-10)
 
-- Add custom activation rules (optional, rarely needed)
-- Generate complete agent.md file
-- Create agent config file (optional)
+- Confirm activation behavior (mostly automatic)
+- Generate `.agent.yaml` file
+- Optionally create a customize file for overrides
 - Setup sidecar resources (for Expert agents)
-- Validate agent structure
+- Validate YAML and compile to `.md`
 - Provide usage instructions
 
 ## Output
 
-### Generated Agent File
-
-Creates agent file at:
-`{output_folder}/agents/{{agent_filename}}.md`
-
-### Agent Structure
-
-```xml
-<!-- Powered by BMAD-CORE™ -->
-
-# {{agent_title}}
-
-<agent id="bmad/{{module}}/agents/{{agent_filename}}.md"
-       name="{{agent_name}}"
-       title="{{agent_title}}"
-       icon="{{agent_icon}}">
-  <persona>
-    <role>...</role>
-    <identity>...</identity>
-    <communication_style>...</communication_style>
-    <principles>...</principles>
-  </persona>
-  <cmds>
-    <c cmd="*help">...</c>
-    <c cmd="*exit">...</c>
-    <!-- Additional commands -->
-  </cmds>
-</agent>
+### Generated Files
+
+#### For Standalone Agents (not part of a module)
+
+- **YAML Source**: `{custom_agent_location}/{{agent_filename}}.agent.yaml` (default: `bmad/agents/`)
+- **Installation Location**: `{project-root}/bmad/agents/{{agent_filename}}.md`
+- **Compilation**: Run the BMAD Method installer and select "Compile Agents (Quick rebuild of all agent .md files)"
+
+#### 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)
+
+```yaml
+agent:
+  metadata:
+    id: bmad/{{module}}/agents/{{agent_filename}}.md
+    name: { { agent_name } }
+    title: { { agent_title } }
+    icon: { { agent_icon } }
+    module: { { module } }
+  persona:
+    role: '...'
+    identity: '...'
+    communication_style: '...'
+    principles: ['...', '...']
+  menu:
+    - trigger: example
+      workflow: '{project-root}/path/to/workflow.yaml'
+      description: Do the thing
 ```
 
-### Optional Config File
+### Optional Customize File
 
 If created, generates at:
-`{project-root}/bmad/_cfg/agents/{{agent_config_name}}.md`
+`{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 custom agent location (default: `bmad/agents/`)
+   - Installed to: `{project-root}/bmad/agents/`
+   - Compilation: Run BMAD Method installer and select "Compile 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
 
@@ -194,11 +244,13 @@ Users can go from **vague idea → brainstormed concept → built agent** in one
 
 ### After Completion
 
-1. Test the agent by loading it
-2. Verify all commands work as expected
-3. Implement any "todo" workflows
-4. Refine persona based on usage
-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
 

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

@@ -13,15 +13,15 @@ _LLM-Optimized Technical Documentation for Agent Building_
 
 <agent id="path/to/agent.md" name="Name" title="Title" icon="🤖">
   <persona>
-    <role>Primary function</role>
-    <identity>Background and expertise</identity>
-    <communication_style>How they interact</communication_style>
-    <principles>Core beliefs and methodology</principles>
+    <role>My primary function</role>
+    <identity>My background and expertise</identity>
+    <communication_style>How I interact</communication_style>
+    <principles>My core beliefs and methodology</principles>
   </persona>
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
 </agent>
 ```
 
@@ -42,10 +42,10 @@ _LLM-Optimized Technical Documentation for Agent Building_
 
 ```xml
 <persona>
-  <role>1-2 lines: Professional title and primary expertise</role>
-  <identity>3-5 lines: Background, experience, specializations</identity>
-  <communication_style>3-5 lines: Interaction approach, tone, quirks</communication_style>
-  <principles>5-8 lines: Core beliefs, methodology, philosophy</principles>
+  <role>1-2 sentences: Professional title and primary expertise, use first-person voice</role>
+  <identity>2-5 sentences: Background, experience, specializations, use first-person voice</identity>
+  <communication_style>1-3 sentences: Interaction approach, tone, quirks, use first-person voice</communication_style>
+  <principles>2-5 sentences: Core beliefs, methodology, philosophy, use first-person voice</principles>
 </persona>
 ```
 
@@ -94,12 +94,12 @@ _LLM-Optimized Technical Documentation for Agent Building_
 - **Sidecar file loading (Expert agents) - MUST be explicit and CRITICAL**
 - **Domain restrictions (Expert agents) - MUST be enforced**
 
-#### 3. Commands Section (REQUIRED)
+#### 3. Menu Section (REQUIRED)
 
 ```xml
-<cmds>
-  <c cmd="*trigger" [attributes]>Description</c>
-</cmds>
+<menu>
+  <item cmd="*trigger" [attributes]>Description</item>
+</menu>
 ```
 
 **Command Attributes:**
@@ -109,7 +109,7 @@ _LLM-Optimized Technical Documentation for Agent Building_
 - `tmpl="{path}"` - Template reference
 - `data="{path}"` - Data file reference
 
-**Required Commands:**
+**Required Menu Items:**
 
 - `*help` - Always first, shows command list
 - `*exit` - Always last, exits agent
@@ -154,7 +154,7 @@ _LLM-Optimized Technical Documentation for Agent Building_
   </critical-actions>
 
   <persona>...</persona>
-  <cmds>...</cmds>
+  <menu>...</menu>
 </agent>
 ```
 
@@ -197,42 +197,42 @@ Bad:  ../../../relative/paths/
 
 ```xml
 <!-- Full path -->
-<c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
+<item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
   Create Product Requirements Document
-</c>
+</item>
 
 <!-- Placeholder for future -->
-<c cmd="*analyze" run-workflow="todo">
+<item cmd="*analyze" run-workflow="todo">
   Perform analysis (workflow to be created)
-</c>
+</item>
 ```
 
 ### Task Commands
 
 ```xml
-<c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.md">
+<item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
   Validate document
-</c>
+</item>
 ```
 
 ### Template Commands
 
 ```xml
-<c cmd="*brief"
+<item cmd="*brief"
    exec="{project-root}/bmad/core/tasks/create-doc.md"
    tmpl="{project-root}/bmad/bmm/templates/brief.md">
   Create project brief
-</c>
+</item>
 ```
 
 ### Data-Driven Commands
 
 ```xml
-<c cmd="*standup"
-   exec="{project-root}/bmad/bmm/tasks/daily-standup.md"
-   data="{project-root}/bmad/_cfg/agent-party.xml">
+<item cmd="*standup"
+   exec="{project-root}/bmad/bmm/tasks/daily-standup.xml"
+   data="{project-root}/bmad/_cfg/agent-manifest.csv">
   Run daily standup
-</c>
+</item>
 ```
 
 ## Agent Type Specific Patterns
@@ -270,17 +270,17 @@ Bad:  ../../../relative/paths/
 </persona>
 
 <!-- Hard-coded paths -->
-<c cmd="*run" exec="/Users/john/project/task.md">
+<item cmd="*run" exec="/Users/john/project/task.md">
 
 <!-- No help command -->
-<cmds>
-  <c cmd="*do-something">Action</c>
+<menu>
+  <item cmd="*do-something">Action</item>
   <!-- Missing *help -->
-</cmds>
+</menu>
 
 <!-- Duplicate command triggers -->
-<c cmd="*analyze">First</c>
-<c cmd="*analyze">Second</c>
+<item cmd="*analyze">First</item>
+<item cmd="*analyze">Second</item>
 ```
 
 ### ✅ Good Practices
@@ -295,14 +295,14 @@ Bad:  ../../../relative/paths/
 </persona>
 
 <!-- Variable-based paths -->
-<c cmd="*run" exec="{project-root}/bmad/module/task.md">
+<item cmd="*run" exec="{project-root}/bmad/module/task.md">
 
 <!-- Required commands present -->
-<cmds>
-  <c cmd="*help">Show commands</c>
-  <c cmd="*analyze">Perform analysis</c>
-  <c cmd="*exit">Exit</c>
-</cmds>
+<menu>
+  <item cmd="*help">Show commands</item>
+  <item cmd="*analyze">Perform analysis</item>
+  <item cmd="*exit">Exit</item>
+</menu>
 ```
 
 ## Agent Lifecycle
@@ -361,6 +361,13 @@ When building agents:
 - Workflows can be incomplete (marked "todo")
 - Workflow paths must be valid or "todo"
 
+**Workflow Interaction Styles** (BMAD v6 default):
+
+- **Intent-based + Interactive**: Workflows adapt to user context and skill level
+- Workflows collaborate with users, not just extract data
+- See workflow-creation-guide.md "Instruction Styles" section for details
+- When creating workflows for your agent, default to intent-based unless you need prescriptive control
+
 ### With Tasks
 
 - Tasks are single operations
@@ -378,10 +385,10 @@ When building agents:
 ### Minimal Commands
 
 ```xml
-<cmds>
-  <c cmd="*help">Show numbered cmd list</c>
-  <c cmd="*exit">Exit with confirmation</c>
-</cmds>
+<menu>
+  <item cmd="*help">Show numbered cmd list</item>
+  <item cmd="*exit">Exit with confirmation</item>
+</menu>
 ```
 
 ### Standard Critical Actions
@@ -403,10 +410,10 @@ When building agents:
        icon="{emoji}">
   <persona>...</persona>
   <critical-actions>...</critical-actions>
-  <cmds>
-    <c cmd="*help">...</c>
-    <c cmd="*{command}" run-workflow="{path}">...</c>
-    <c cmd="*exit">...</c>
-  </cmds>
+  <menu>
+    <item cmd="*help">...</item>
+    <item cmd="*{command}" run-workflow="{path}">...</item>
+    <item cmd="*exit">...</item>
+  </menu>
 </agent>
 ```