bmad-method 5.1.3 → 6.0.0-alpha.1

package/bmad/bmb/workflows/create-agent/README.md

@@ -0,0 +1,320 @@
+# Build Agent
+
+## Overview
+
+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
+
+- **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 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
+
+### Basic Invocation
+
+```bash
+workflow create-agent
+```
+
+### Through BMad Builder Agent
+
+```
+*create-agent
+```
+
+### With Brainstorming Session
+
+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.
+
+### What You'll Be Asked
+
+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)
+
+## Workflow Structure
+
+### Files Included
+
+```
+create-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
+```
+
+## Workflow Process
+
+### Phase 0: Optional Brainstorming (Step -1)
+
+- 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
+
+### Phase 1: Agent Setup (Steps 0-2)
+
+- 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)
+
+### Phase 2: Persona Development (Steps 2-3)
+
+- Define role and responsibilities - leveraging brainstorming insights if available
+- Craft unique identity and backstory
+- Select communication style - can use brainstormed personality concepts
+- Establish guiding principles
+- Add critical actions (optional)
+
+### Phase 3: Command Building (Step 4)
+
+- 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
+
+### Phase 4: Finalization (Steps 5-10)
+
+- Confirm activation behavior (mostly automatic)
+- Generate `.agent.yaml` file
+- Optionally create a customize file for overrides
+- Setup sidecar resources (for Expert agents)
+- Validate YAML and compile to `.md`
+- Provide usage instructions
+
+## Output
+
+### 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 Customize File
+
+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 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
+
+- 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
+
+### Brainstorming Flow
+
+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
+
+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
+
+3. **Seamless transition**: Vague idea → brainstormed concept → built agent
+
+### Key Principle
+
+Users can go from **vague idea → brainstormed concept → built agent** in one continuous flow, with brainstorming output directly feeding into agent development.
+
+## 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. **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
+
+### Simple Agent
+
+- **Best For**: Self-contained utilities, simple assistants
+- **Characteristics**: Embedded logic, no external dependencies
+- **Example**: Calculator agent, random picker, simple formatter
+
+### Expert Agent
+
+- **Best For**: Domain-specific agents with data/memory
+- **Characteristics**: Sidecar folders, domain restrictions, memory files
+- **Example**: Diary keeper, project journal, personal knowledge base
+
+### Module Agent
+
+- **Best For**: Full-featured agents with workflows
+- **Characteristics**: Part of module, commands invoke workflows
+- **Example**: Product manager, architect, research assistant
+
+## Troubleshooting
+
+### Issue: Agent won't load
+
+- **Solution**: Validate XML structure is correct
+- **Check**: Ensure all required tags present (persona, cmds)
+
+### Issue: Commands don't work
+
+- **Solution**: Verify workflow paths are correct or marked "todo"
+- **Check**: Test workflow invocation separately first
+
+### Issue: Persona feels generic
+
+- **Solution**: Review communication styles guide
+- **Check**: Make identity unique and specific to role
+
+## Customization
+
+To modify agent building process:
+
+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
+
+## Version History
+
+- **v6.0.0** - BMAD Core v6 compatible
+  - Three agent types (Simple/Expert/Module)
+  - Enhanced persona development
+  - Command pattern library
+  - Validation framework
+
+## Support
+
+For issues or questions:
+
+- 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
+
+---
+
+_Part of the BMad Method v6 - BMB (BMad Builder) Module_