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

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

@@ -1,268 +1,203 @@
-# Build Agent
+# Create Agent Workflow
 
-## Overview
+Interactive agent builder creating BMad Core compliant agents as YAML source files that compile to .md during installation.
 
-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).
+## Table of Contents
 
-## Key Features
+- [Quick Start](#quick-start)
+- [Agent Types](#agent-types)
+- [Workflow Phases](#workflow-phases)
+- [Output Structure](#output-structure)
+- [Installation](#installation)
+- [Examples](#examples)
 
-- **Optional Brainstorming**: Creative ideation session before agent building to explore concepts and personalities
-- **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
-- **Sidecar Resources**: Setup for Expert agents with domain-specific data
-
-## Usage
-
-### Basic Invocation
+## Quick Start
 
 ```bash
-workflow build-agent
-```
-
-### Through BMad Builder Agent
+# Direct workflow
+workflow create-agent
 
-```
+# Via BMad Builder
 *create-agent
 ```
 
-### With Brainstorming Session
+## Agent Types
 
-The workflow includes an optional brainstorming phase (Step -1) that helps you explore agent concepts, personalities, and capabilities before building. This is particularly useful when you have a vague idea and want to develop it into a concrete agent concept.
+### Simple Agent
 
-### What You'll Be Asked
+- Self-contained functionality
+- Basic command structure
+- No external resources
 
-0. **Optional brainstorming** (vague idea → refined concept)
-1. Agent type (Simple, Expert, or Module)
-2. Basic identity (name, title, icon, filename)
-3. Module assignment (for Module agents)
-4. Sidecar resources (for Expert agents)
-5. Persona elements (role, identity, style, principles)
-6. Commands and their implementations
-7. Critical actions (optional)
-8. Activation rules (optional, rarely needed)
+### Expert Agent
 
-## Workflow Structure
+- Sidecar resources for domain knowledge
+- Extended capabilities
+- Knowledge base integration
 
-### Files Included
+### Module Agent
 
-```
-build-agent/
-├── workflow.yaml                  # Configuration
-├── instructions.md                # Step-by-step guide
-├── checklist.md                   # Validation criteria
-├── README.md                      # This file
-├── agent-types.md                 # Agent type documentation
-├── agent-architecture.md          # Architecture patterns
-├── agent-command-patterns.md      # Command patterns reference
-└── communication-styles.md        # Style examples
-```
+- Full-featured with workflows
+- Module-specific commands
+- Integrated with module structure
 
-## Workflow Process
+## Workflow Phases
 
-### Phase 0: Optional Brainstorming (Step -1)
+### Phase 0: Optional Brainstorming
 
-- Creative ideation session using diverse brainstorming techniques
-- Explore agent concepts, personalities, and capabilities
-- Generate character ideas, expertise areas, and command concepts
-- Output feeds directly into agent identity and persona development
+- Creative ideation session
+- Explore concepts and personalities
+- Generate command ideas
+- Output feeds into persona development
 
-### Phase 1: Agent Setup (Steps 0-2)
+### Phase 1: Agent Setup
 
-- Load agent building documentation and patterns
-- Choose agent type (Simple/Expert/Module)
-- Define basic identity (name, title, icon, filename) - informed by brainstorming if completed
-- Assign to module (for Module agents)
+1. Choose agent type (Simple/Expert/Module)
+2. Define identity (name, title, icon, filename)
+3. Assign to module (if Module agent)
 
-### Phase 2: Persona Development (Steps 2-3)
+### Phase 2: Persona Development
 
-- Define role and responsibilities - leveraging brainstorming insights if available
-- Craft unique identity and backstory
-- Select communication style - can use brainstormed personality concepts
+- Define role and responsibilities
+- Craft unique identity/backstory
+- Select communication style
 - Establish guiding principles
 - Add critical actions (optional)
 
-### Phase 3: Command Building (Step 4)
+### Phase 3: Command Building
 
-- Add *help and *exit commands (required)
-- Define workflow commands (most common)
-- Add task commands (for single operations)
-- Create action commands (inline logic)
-- Configure command attributes
+- Add required commands (*help, *exit)
+- Define workflow commands
+- Add task commands
+- Create action commands
+- Configure attributes
 
-### Phase 4: Finalization (Steps 5-10)
+### Phase 4: Finalization
 
-- Add custom activation rules (optional, rarely needed)
-- Generate complete agent.md file
-- Create agent config file (optional)
-- Setup sidecar resources (for Expert agents)
-- Validate agent structure
+- Generate .agent.yaml file
+- Create customize file (optional)
+- Setup sidecar resources (Expert agents)
+- Validate and compile
 - 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>
-```
-
-### Optional Config File
-
-If created, generates at:
-`{project-root}/bmad/_cfg/agents/{{agent_config_name}}.md`
-
-## Requirements
-
-- BMAD Core v6 project structure
-- Module to host the agent (for Module agents)
-- Understanding of agent purpose and commands
-- Workflows/tasks to reference in commands (or mark as "todo")
-
-## Brainstorming Integration
-
-The optional brainstorming phase (Step -1) provides a seamless path from vague idea to concrete agent concept:
-
-### When to Use Brainstorming
-
-- **Vague concept**: "I want an agent that helps with data stuff"
-- **Creative exploration**: Want to discover unique personality and approach
-- **Team building**: Creating agents for a module with specific roles
-- **Character development**: Need to flesh out agent personality and voice
+## Output Structure
 
-### Brainstorming Flow
+### Generated Files
 
-1. **Step -1**: Optional brainstorming session
-   - Uses CIS brainstorming workflow with agent-specific context
-   - Explores identity, personality, expertise, and command concepts
-   - Generates detailed character and capability ideas
+**Standalone Agents:**
 
-2. **Steps 0-2**: Agent setup informed by brainstorming
-   - Brainstorming output guides agent type selection
-   - Character concepts inform basic identity choices
-   - Personality insights shape persona development
+- Source: `{bmad_folder}/agents/{filename}.agent.yaml`
+- Compiled: `{bmad_folder}/agents/{filename}.md`
 
-3. **Seamless transition**: Vague idea → brainstormed concept → built agent
+**Module Agents:**
 
-### Key Principle
+- Source: `src/modules/{module}/agents/{filename}.agent.yaml`
+- Compiled: `{bmad_folder}/{module}/agents/{filename}.md`
 
-Users can go from **vague idea → brainstormed concept → built agent** in one continuous flow, with brainstorming output directly feeding into agent development.
+### YAML Structure
 
-## Best Practices
-
-### Before Starting
-
-1. Review example agents in `/bmad/bmm/agents/` for patterns
-2. Consider using brainstorming if you have a vague concept to develop
-3. Have a clear vision of the agent's role and personality (or use brainstorming to develop it)
-4. List the commands/capabilities the agent will need
-5. Identify any workflows or tasks the agent will invoke
-
-### During Execution
-
-1. **Agent Names**: Use memorable names that reflect personality
-2. **Icons**: Choose an emoji that represents the agent's role
-3. **Persona**: Make it distinct and consistent with communication style
-4. **Commands**: Use kebab-case, start custom commands with letter (not \*)
-5. **Workflows**: Reference existing workflows or mark as "todo" to implement later
-
-### 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
-
-## Agent Types
-
-### Simple Agent
-
-- **Best For**: Self-contained utilities, simple assistants
-- **Characteristics**: Embedded logic, no external dependencies
-- **Example**: Calculator agent, random picker, simple formatter
+```yaml
+agent:
+  metadata:
+    id: {bmad_folder}/{module}/agents/{filename}.md
+    name: Agent Name
+    title: Agent Title
+    icon: 🤖
+    module: module-name
+  persona:
+    role: '...'
+    identity: '...'
+    communication_style: '...'
+    principles: ['...', '...']
+  menu:
+    - trigger: command-name
+      workflow: path/to/workflow.yaml
+      description: Command description
+```
 
-### Expert Agent
+### Optional Customize File
 
-- **Best For**: Domain-specific agents with data/memory
-- **Characteristics**: Sidecar folders, domain restrictions, memory files
-- **Example**: Diary keeper, project journal, personal knowledge base
+Location: `{bmad_folder}/_cfg/agents/{module}-{filename}.customize.yaml`
 
-### Module Agent
+Allows persona and menu overrides that persist through updates.
 
-- **Best For**: Full-featured agents with workflows
-- **Characteristics**: Part of module, commands invoke workflows
-- **Example**: Product manager, architect, research assistant
+## Installation
 
-## Troubleshooting
+### Compilation Methods
 
-### Issue: Agent won't load
+**Quick Rebuild:**
 
-- **Solution**: Validate XML structure is correct
-- **Check**: Ensure all required tags present (persona, cmds)
+```bash
+bmad compile-agents
+```
 
-### Issue: Commands don't work
+**During Module Install:**
+Automatic compilation when installing modules
 
-- **Solution**: Verify workflow paths are correct or marked "todo"
-- **Check**: Test workflow invocation separately first
+**Manual Compilation:**
 
-### Issue: Persona feels generic
+```bash
+node tools/cli/bmad-cli.js compile-agents
+```
 
-- **Solution**: Review communication styles guide
-- **Check**: Make identity unique and specific to role
+## Examples
 
-## Customization
+### Creating a Code Review Agent
 
-To modify agent building process:
+```
+User: I need a code review agent
+Builder: Let's brainstorm first...
+
+[Brainstorming generates ideas for strict vs friendly reviewer]
+
+Builder: Now let's build your agent:
+- Type: Simple
+- Name: Code Reviewer
+- Role: Senior developer conducting thorough reviews
+- Style: Professional but approachable
+- Commands:
+  - *review-pr: Review pull request
+  - *review-file: Review single file
+  - *review-standards: Check coding standards
+```
 
-1. Edit `instructions.md` to change steps
-2. Update `agent-types.md` to add new agent patterns
-3. Modify `agent-command-patterns.md` for new command types
-4. Edit `communication-styles.md` to add personality examples
+### Creating a Domain Expert
 
-## Version History
+```
+Type: Expert
+Name: Legal Advisor
+Sidecar: legal-knowledge/
+Commands:
+  - *contract-review
+  - *compliance-check
+  - *risk-assessment
+```
 
-- **v6.0.0** - BMAD Core v6 compatible
-  - Three agent types (Simple/Expert/Module)
-  - Enhanced persona development
-  - Command pattern library
-  - Validation framework
+## Workflow Files
 
-## Support
+```
+create-agent/
+├── workflow.yaml              # Configuration
+├── instructions.md            # Step guide
+├── checklist.md              # Validation
+├── README.md                 # This file
+├── agent-types.md            # Type details
+├── agent-architecture.md     # Patterns
+├── agent-command-patterns.md # Commands
+└── communication-styles.md   # Styles
+```
 
-For issues or questions:
+## Best Practices
 
-- Review example agents in `/bmad/bmm/agents/`
-- Check agent documentation in this workflow folder
-- Test with simple agents first, then build complexity
-- Consult BMAD Method v6 documentation
+1. **Use brainstorming** for complex agents
+2. **Start simple** - Add commands incrementally
+3. **Test commands** before finalizing
+4. **Document thoroughly** in descriptions
+5. **Follow naming conventions** consistently
 
----
+## Related Documentation
 
-_Part of the BMad Method v6 - BMB (BMad Builder) Module_
+- [Agent Types](./agent-types.md)
+- [Command Patterns](./agent-command-patterns.md)
+- [Communication Styles](./communication-styles.md)
+- [BMB Module](../../README.md)