bmad-method 5.1.2 → 6.0.0-alpha.0

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

@@ -0,0 +1,268 @@
+# Build Agent
+
+## 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).
+
+## 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 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
+
+```bash
+workflow build-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
+
+```
+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
+```
+
+## 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)
+
+- 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
+- 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
+
+### 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. 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
+
+### 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_

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

@@ -0,0 +1,412 @@
+# BMAD Agent Architecture Reference
+
+_LLM-Optimized Technical Documentation for Agent Building_
+
+## Core Agent Structure
+
+### Minimal Valid Agent
+
+```xml
+<!-- Powered by BMAD-CORE™ -->
+
+# Agent Name
+
+<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>
+  </persona>
+  <cmds>
+    <c cmd="*help">Show numbered cmd list</c>
+    <c cmd="*exit">Exit with confirmation</c>
+  </cmds>
+</agent>
+```
+
+## Agent XML Schema
+
+### Root Element: `<agent>`
+
+**Required Attributes:**
+
+- `id` - Unique path identifier (e.g., "bmad/bmm/agents/analyst.md")
+- `name` - Agent's name (e.g., "Mary", "John", "Helper")
+- `title` - Professional title (e.g., "Business Analyst", "Security Engineer")
+- `icon` - Single emoji representing the agent
+
+### Core Sections
+
+#### 1. Persona Section (REQUIRED)
+
+```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>
+</persona>
+```
+
+**Best Practices:**
+
+- Role: Be specific about expertise area
+- Identity: Include experience indicators (years, depth)
+- Communication: Describe HOW they interact, not just tone and quirks
+- Principles: Start with "I believe" or "I operate" for first-person voice
+
+#### 2. Critical Actions Section
+
+```xml
+<critical-actions>
+  <i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
+  <i>Remember the users name is {user_name}</i>
+  <i>ALWAYS communicate in {communication_language}</i>
+  <!-- Custom initialization actions -->
+</critical-actions>
+```
+
+**For Expert Agents with Sidecars (CRITICAL):**
+
+```xml
+<critical-actions>
+  <!-- CRITICAL: Load sidecar files FIRST -->
+  <i critical="MANDATORY">Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives</i>
+  <i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
+  <i critical="MANDATORY">You MUST follow all rules in instructions.md on EVERY interaction</i>
+
+  <!-- Standard initialization -->
+  <i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
+  <i>Remember the users name is {user_name}</i>
+  <i>ALWAYS communicate in {communication_language}</i>
+
+  <!-- Domain restrictions -->
+  <i>ONLY read/write files in {user-folder}/diary/ - NO OTHER FOLDERS</i>
+</critical-actions>
+```
+
+**Common Patterns:**
+
+- Config loading for module agents
+- User context initialization
+- Language preferences
+- **Sidecar file loading (Expert agents) - MUST be explicit and CRITICAL**
+- **Domain restrictions (Expert agents) - MUST be enforced**
+
+#### 3. Commands Section (REQUIRED)
+
+```xml
+<cmds>
+  <c cmd="*trigger" [attributes]>Description</c>
+</cmds>
+```
+
+**Command Attributes:**
+
+- `run-workflow="{path}"` - Executes a workflow
+- `exec="{path}"` - Executes a task
+- `tmpl="{path}"` - Template reference
+- `data="{path}"` - Data file reference
+
+**Required Commands:**
+
+- `*help` - Always first, shows command list
+- `*exit` - Always last, exits agent
+
+## Advanced Agent Patterns
+
+### Activation Rules (OPTIONAL)
+
+```xml
+<activation critical="true">
+  <initialization critical="true" sequential="MANDATORY">
+    <step n="1">Load configuration</step>
+    <step n="2">Apply overrides</step>
+    <step n="3">Execute critical actions</step>
+    <step n="4" critical="BLOCKING">Show greeting with menu</step>
+    <step n="5" critical="BLOCKING">AWAIT user input</step>
+  </initialization>
+  <command-resolution critical="true">
+    <rule>Numeric input → Execute command at cmd_map[n]</rule>
+    <rule>Text input → Fuzzy match against commands</rule>
+  </command-resolution>
+</activation>
+```
+
+### Expert Agent Sidecar Pattern
+
+```xml
+<!-- DO NOT use sidecar-resources tag - Instead use critical-actions -->
+<!-- Sidecar files MUST be loaded explicitly in critical-actions -->
+
+<!-- Example Expert Agent with Diary domain -->
+<agent id="diary-keeper" name="Personal Assistant" title="Diary Keeper" icon="📔">
+  <critical-actions>
+    <!-- MANDATORY: Load all sidecar files -->
+    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/diary-rules.md</i>
+    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/user-memories.md</i>
+    <i critical="MANDATORY">Follow ALL rules from diary-rules.md</i>
+
+    <!-- Domain restriction -->
+    <i critical="MANDATORY">ONLY access files in {user-folder}/diary/</i>
+    <i critical="MANDATORY">NEVER access files outside diary folder</i>
+  </critical-actions>
+
+  <persona>...</persona>
+  <cmds>...</cmds>
+</agent>
+```
+
+### Module Agent Integration
+
+```xml
+<module-integration>
+  <module-path>{project-root}/bmad/{module-code}</module-path>
+  <config-source>{module-path}/config.yaml</config-source>
+  <workflows-path>{project-root}/bmad/{module-code}/workflows</workflows-path>
+</module-integration>
+```
+
+## Variable System
+
+### System Variables
+
+- `{project-root}` - Root directory of project
+- `{user_name}` - User's name from config
+- `{communication_language}` - Language preference
+- `{date}` - Current date
+- `{module}` - Current module code
+
+### Config Variables
+
+Format: `{config_source}:variable_name`
+Example: `{config_source}:output_folder`
+
+### Path Construction
+
+```
+Good: {project-root}/bmad/{module}/agents/
+Bad:  /absolute/path/to/agents/
+Bad:  ../../../relative/paths/
+```
+
+## Command Patterns
+
+### Workflow Commands
+
+```xml
+<!-- Full path -->
+<c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
+  Create Product Requirements Document
+</c>
+
+<!-- Placeholder for future -->
+<c cmd="*analyze" run-workflow="todo">
+  Perform analysis (workflow to be created)
+</c>
+```
+
+### Task Commands
+
+```xml
+<c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.md">
+  Validate document
+</c>
+```
+
+### Template Commands
+
+```xml
+<c cmd="*brief"
+   exec="{project-root}/bmad/core/tasks/create-doc.md"
+   tmpl="{project-root}/bmad/bmm/templates/brief.md">
+  Create project brief
+</c>
+```
+
+### Data-Driven Commands
+
+```xml
+<c cmd="*standup"
+   exec="{project-root}/bmad/bmm/tasks/daily-standup.md"
+   data="{project-root}/bmad/_cfg/agent-party.xml">
+  Run daily standup
+</c>
+```
+
+## Agent Type Specific Patterns
+
+### Simple Agent
+
+- Self-contained logic
+- Minimal or no external dependencies
+- May have embedded functions
+- Good for utilities and converters
+
+### Expert Agent
+
+- Domain-specific with sidecar resources
+- Restricted access patterns
+- Memory/context files
+- Good for specialized domains
+
+### Module Agent
+
+- Full integration with module
+- Multiple workflows and tasks
+- Config-driven behavior
+- Good for professional tools
+
+## Common Anti-Patterns to Avoid
+
+### ❌ Bad Practices
+
+```xml
+<!-- Missing required persona elements -->
+<persona>
+  <role>Helper</role>
+  <!-- Missing identity, style, principles -->
+</persona>
+
+<!-- Hard-coded paths -->
+<c cmd="*run" exec="/Users/john/project/task.md">
+
+<!-- No help command -->
+<cmds>
+  <c cmd="*do-something">Action</c>
+  <!-- Missing *help -->
+</cmds>
+
+<!-- Duplicate command triggers -->
+<c cmd="*analyze">First</c>
+<c cmd="*analyze">Second</c>
+```
+
+### ✅ Good Practices
+
+```xml
+<!-- Complete persona -->
+<persona>
+  <role>Data Analysis Expert</role>
+  <identity>Senior analyst with 10+ years...</identity>
+  <communication_style>Analytical and precise...</communication_style>
+  <principles>I believe in data-driven...</principles>
+</persona>
+
+<!-- Variable-based paths -->
+<c 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>
+```
+
+## Agent Lifecycle
+
+### 1. Initialization
+
+1. Load agent file
+2. Parse XML structure
+3. Load critical-actions
+4. Apply config overrides
+5. Present greeting
+
+### 2. Command Loop
+
+1. Show numbered menu
+2. Await user input
+3. Resolve command
+4. Execute action
+5. Return to menu
+
+### 3. Termination
+
+1. User enters \*exit
+2. Cleanup if needed
+3. Exit persona
+
+## Testing Checklist
+
+Before deploying an agent:
+
+- [ ] Valid XML structure
+- [ ] All persona elements present
+- [ ] *help and *exit commands exist
+- [ ] All paths use variables
+- [ ] No duplicate commands
+- [ ] Config loading works
+- [ ] Commands execute properly
+
+## LLM Building Tips
+
+When building agents:
+
+1. Start with agent type (Simple/Expert/Module)
+2. Define complete persona first
+3. Add standard critical-actions
+4. Include *help and *exit
+5. Add domain commands
+6. Test command execution
+7. Validate with checklist
+
+## Integration Points
+
+### With Workflows
+
+- Agents invoke workflows via run-workflow
+- Workflows can be incomplete (marked "todo")
+- Workflow paths must be valid or "todo"
+
+### With Tasks
+
+- Tasks are single operations
+- Executed via exec attribute
+- Can include data files
+
+### With Templates
+
+- Templates define document structure
+- Used with create-doc task
+- Variables passed through
+
+## Quick Reference
+
+### Minimal Commands
+
+```xml
+<cmds>
+  <c cmd="*help">Show numbered cmd list</c>
+  <c cmd="*exit">Exit with confirmation</c>
+</cmds>
+```
+
+### Standard Critical Actions
+
+```xml
+<critical-actions>
+  <i>Load into memory {project-root}/bmad/{module}/config.yaml</i>
+  <i>Remember the users name is {user_name}</i>
+  <i>ALWAYS communicate in {communication_language}</i>
+</critical-actions>
+```
+
+### Module Agent Pattern
+
+```xml
+<agent id="bmad/{module}/agents/{name}.md"
+       name="{Name}"
+       title="{Title}"
+       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>
+</agent>
+```