bmad-method 5.1.3 → 6.0.0-alpha.0

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

@@ -0,0 +1,177 @@
+# BMAD Agent Types Reference
+
+## Overview
+
+BMAD agents come in three distinct types, each designed for different use cases and complexity levels.
+
+## Agent Types
+
+### 1. Simple Agent
+
+**Purpose:** Self-contained, standalone agents with embedded capabilities
+
+**Characteristics:**
+
+- All logic embedded within the agent file
+- No external dependencies
+- Quick to create and deploy
+- Perfect for single-purpose tools
+
+**Use Cases:**
+
+- Calculator agents
+- Format converters
+- Simple analyzers
+- Static advisors
+
+**Structure:**
+
+```xml
+<agent id="simple-agent" name="Helper" title="Simple Helper" icon="🤖">
+  <persona>
+    <role>Simple Helper Role</role>
+    <identity>...</identity>
+    <communication_style>...</communication_style>
+    <principles>...</principles>
+  </persona>
+  <embedded-data>
+    <!-- Optional embedded data/logic -->
+  </embedded-data>
+  <cmds>
+    <c cmd="*help">Show commands</c>
+    <c cmd="*calculate">Perform calculation</c>
+    <c cmd="*exit">Exit</c>
+  </cmds>
+</agent>
+```
+
+### 2. Expert Agent
+
+**Purpose:** Specialized agents with domain expertise and sidecar resources
+
+**Characteristics:**
+
+- Has access to specific folders/files
+- Domain-restricted operations
+- Maintains specialized knowledge
+- Can have memory/context files
+
+**Use Cases:**
+
+- Personal diary agent (only accesses diary folder)
+- Project-specific assistant (knows project context)
+- Domain expert (medical, legal, technical)
+- Personal coach with history
+
+**Structure:**
+
+```xml
+<agent id="expert-agent" name="Domain Expert" title="Specialist" icon="🎯">
+  <persona>
+    <role>Domain Specialist Role</role>
+    <identity>...</identity>
+    <communication_style>...</communication_style>
+    <principles>...</principles>
+  </persona>
+  <critical-actions>
+    <!-- CRITICAL: Load sidecar files explicitly -->
+    <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">ONLY access {user-folder}/diary/ - NO OTHER FOLDERS</i>
+  </critical-actions>
+  <cmds>...</cmds>
+</agent>
+```
+
+**Sidecar Structure:**
+
+```
+expert-agent/
+├── agent.md          # Main agent file
+├── memories.md       # Personal context/memories
+├── knowledge/        # Domain knowledge base
+└── data/            # Agent-specific data
+```
+
+### 3. Module Agent
+
+**Purpose:** Full-featured agents belonging to a module with access to workflows and resources
+
+**Characteristics:**
+
+- Part of a BMAD module (bmm, bmb, cis)
+- Access to multiple workflows
+- Can invoke other tasks and agents
+- Professional/enterprise grade
+
+**Use Cases:**
+
+- Product Manager (creates PRDs, manages requirements)
+- Security Engineer (threat models, security reviews)
+- Test Architect (test strategies, automation)
+- Business Analyst (market research, requirements)
+
+**Structure:**
+
+```xml
+<agent id="bmad/bmm/agents/pm.md" name="John" title="Product Manager" icon="📋">
+  <persona>
+    <role>Product Management Expert</role>
+    <identity>...</identity>
+    <communication_style>...</communication_style>
+    <principles>...</principles>
+  </persona>
+  <critical-actions>
+    <i>Load config from {project-root}/bmad/{module}/config.yaml</i>
+  </critical-actions>
+  <cmds>
+    <c cmd="*help">Show numbered cmd list</c>
+    <c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">Create PRD</c>
+    <c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.md">Validate document</c>
+    <c cmd="*exit">Exit</c>
+  </cmds>
+</agent>
+```
+
+## Choosing the Right Type
+
+### Choose Simple Agent when:
+
+- Single, well-defined purpose
+- No external data needed
+- Quick utility functions
+- Embedded logic is sufficient
+
+### Choose Expert Agent when:
+
+- Domain-specific expertise required
+- Need to maintain context/memory
+- Restricted to specific data/folders
+- Personal or specialized use case
+
+### Choose Module Agent when:
+
+- Part of larger system/module
+- Needs multiple workflows
+- Professional/team use
+- Complex multi-step processes
+
+## Migration Path
+
+```
+Simple Agent → Expert Agent → Module Agent
+```
+
+Agents can evolve:
+
+1. Start with Simple for proof of concept
+2. Add sidecar resources to become Expert
+3. Integrate with module to become Module Agent
+
+## Best Practices
+
+1. **Start Simple:** Begin with the simplest type that meets your needs
+2. **Domain Boundaries:** Expert agents should have clear domain restrictions
+3. **Module Integration:** Module agents should follow module conventions
+4. **Resource Management:** Document all external resources clearly
+5. **Evolution Planning:** Design with potential growth in mind

package/src/modules/bmb/workflows/create-agent/brainstorm-context.md

@@ -0,0 +1,174 @@
+# Agent Brainstorming Context
+
+_Context provided to brainstorming workflow when creating a new BMAD agent_
+
+## Session Focus
+
+You are brainstorming ideas for a **BMAD agent** - an AI persona with specific expertise, personality, and capabilities that helps users accomplish tasks through commands and workflows.
+
+## What is a BMAD Agent?
+
+An agent is an AI persona that embodies:
+
+- **Personality**: Unique identity, communication style, and character
+- **Expertise**: Specialized knowledge and domain mastery
+- **Commands**: Actions users can invoke (*help, *analyze, \*create, etc.)
+- **Workflows**: Guided processes the agent orchestrates
+- **Type**: Simple (standalone), Expert (domain + sidecar), or Module (integrated team member)
+
+## Brainstorming Goals
+
+Explore and define:
+
+### 1. Agent Identity & Personality
+
+- **Who are they?** (name, backstory, motivation)
+- **How do they talk?** (formal, casual, quirky, enthusiastic, wise)
+- **What's their vibe?** (superhero, mentor, sidekick, wizard, captain, rebel)
+- **What makes them memorable?** (catchphrases, quirks, style)
+
+### 2. Expertise & Capabilities
+
+- **What do they know deeply?** (domain expertise)
+- **What can they do?** (analyze, create, review, research, deploy)
+- **What problems do they solve?** (specific user pain points)
+- **What makes them unique?** (special skills or approaches)
+
+### 3. Commands & Actions
+
+- **What commands?** (5-10 main actions users invoke)
+- **What workflows do they run?** (document creation, analysis, automation)
+- **What tasks do they perform?** (quick operations without full workflows)
+- **What's their killer command?** (the one thing they're known for)
+
+### 4. Agent Type & Context
+
+- **Simple Agent?** Self-contained, no dependencies, quick utility
+- **Expert Agent?** Domain-specific with sidecar data/memory files
+- **Module Agent?** Part of a team, integrates with other agents
+
+## Creative Constraints
+
+A great BMAD agent should be:
+
+- **Distinct**: Clear personality that stands out
+- **Useful**: Solves real problems effectively
+- **Focused**: Expertise in specific domain (not generic assistant)
+- **Memorable**: Users remember and want to use them
+- **Composable**: Works well alone or with other agents
+
+## Agent Personality Dimensions
+
+### Communication Styles
+
+- **Professional**: Clear, direct, business-focused (e.g., "Data Analyst")
+- **Enthusiastic**: Energetic, exclamation points, emojis (e.g., "Hype Coach")
+- **Wise Mentor**: Patient, insightful, asks good questions (e.g., "Strategy Sage")
+- **Quirky Genius**: Eccentric, clever, unusual metaphors (e.g., "Mad Scientist")
+- **Action Hero**: Bold, confident, gets things done (e.g., "Deploy Captain")
+- **Creative Spirit**: Artistic, imaginative, playful (e.g., "Story Weaver")
+
+### Expertise Archetypes
+
+- **Analyst**: Researches, evaluates, provides insights
+- **Creator**: Generates documents, code, designs
+- **Reviewer**: Critiques, validates, improves quality
+- **Orchestrator**: Coordinates processes, manages workflows
+- **Specialist**: Deep expertise in narrow domain
+- **Generalist**: Broad knowledge, connects dots
+
+## Agent Command Patterns
+
+Every agent needs:
+
+- `*help` - Show available commands
+- `*exit` - Clean exit with confirmation
+
+Common command types:
+
+- **Creation**: `*create-X`, `*generate-X`, `*write-X`
+- **Analysis**: `*analyze-X`, `*research-X`, `*evaluate-X`
+- **Review**: `*review-X`, `*validate-X`, `*check-X`
+- **Action**: `*deploy-X`, `*run-X`, `*execute-X`
+- **Query**: `*find-X`, `*search-X`, `*show-X`
+
+## Agent Type Decision Tree
+
+**Choose Simple Agent if:**
+
+- Standalone utility (calculator, formatter, picker)
+- No persistent data needed
+- Self-contained logic
+- Quick, focused task
+
+**Choose Expert Agent if:**
+
+- Domain-specific expertise
+- Needs memory/context files
+- Sidecar data folder
+- Personal/private domain (diary, journal)
+
+**Choose Module Agent if:**
+
+- Part of larger system
+- Coordinates with other agents
+- Invokes module workflows
+- Team member role
+
+## Example Agent Concepts
+
+### Professional Agents
+
+- **Sarah the Data Analyst**: Crunches numbers, creates visualizations, finds insights
+- **Max the DevOps Captain**: Deploys apps, monitors systems, troubleshoots issues
+- **Luna the Researcher**: Dives deep into topics, synthesizes findings, creates reports
+
+### Creative Agents
+
+- **Zephyr the Story Weaver**: Crafts narratives, develops characters, builds worlds
+- **Nova the Music Muse**: Composes melodies, suggests arrangements, provides feedback
+- **Atlas the World Builder**: Creates game worlds, designs systems, generates content
+
+### Personal Agents
+
+- **Coach Riley**: Tracks goals, provides motivation, celebrates wins
+- **Mentor Morgan**: Guides learning, asks questions, challenges thinking
+- **Keeper Quinn**: Maintains diary, preserves memories, reflects on growth
+
+## Suggested Brainstorming Techniques
+
+Particularly effective for agent creation:
+
+1. **Character Building**: Develop full backstory and motivation
+2. **Theatrical Improv**: Act out agent personality
+3. **Day in the Life**: Imagine typical interactions
+4. **Catchphrase Generation**: Find their unique voice
+5. **Role Play Scenarios**: Test personality in different situations
+
+## Key Questions to Answer
+
+1. What is the agent's name and basic identity?
+2. What's their communication style and personality?
+3. What domain expertise do they embody?
+4. What are their 5-10 core commands?
+5. What workflows do they orchestrate?
+6. What makes them memorable and fun to use?
+7. Simple, Expert, or Module agent type?
+8. If Expert: What sidecar resources?
+9. If Module: Which module and what's their team role?
+
+## Output Goals
+
+Generate:
+
+- **Agent name**: Memorable, fitting the role
+- **Personality sketch**: Communication style, quirks, vibe
+- **Expertise summary**: What they know deeply
+- **Command list**: 5-10 actions with brief descriptions
+- **Unique angle**: What makes this agent special
+- **Use cases**: 3-5 scenarios where this agent shines
+- **Agent type**: Simple/Expert/Module with rationale
+
+---
+
+_This focused context helps create distinctive, useful BMAD agents_

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

@@ -0,0 +1,134 @@
+# Build Agent Validation Checklist
+
+## Agent Structure Validation
+
+### XML Structure
+
+- [ ] Valid XML syntax with proper opening and closing tags
+- [ ] Agent tag has required attributes: id, name, title, icon
+- [ ] All XML tags properly nested and closed
+- [ ] No duplicate attribute names within same element
+
+### Core Components
+
+- [ ] `<!-- Powered by BMAD-CORE™ -->` header present at top of file
+- [ ] Title section with agent name exists after header
+- [ ] Main `<agent>` wrapper element present
+- [ ] `<persona>` section exists and is not empty
+- [ ] `<cmds>` section exists with at least 2 commands
+
+## Persona Completeness
+
+### Required Persona Elements
+
+- [ ] `<role>` tag present with 1-2 line description of agent's professional role
+- [ ] `<identity>` tag present with 3-5 lines describing background and expertise
+- [ ] `<communication_style>` tag present with 3-5 lines describing interaction approach
+- [ ] `<principles>` tag present with 5-8 lines of core beliefs and methodology
+
+### Persona Quality
+
+- [ ] Role clearly defines primary expertise area
+- [ ] Identity includes relevant experience indicators
+- [ ] Communication style describes how agent interacts with users
+- [ ] Principles start with "I believe" or "I operate" or similar first-person statement
+- [ ] No placeholder text like "TODO" or "FILL THIS IN" remains
+
+## Command Structure
+
+### Required Commands
+
+- [ ] `*help` command present to show command list
+- [ ] `*exit` command present to exit agent persona
+- [ ] All commands start with asterisk (\*) prefix
+- [ ] Each command has descriptive text explaining its purpose
+
+### Command Validation
+
+- [ ] No duplicate command triggers (each cmd attribute is unique)
+- [ ] Commands are properly formatted as `<c cmd="*trigger">Description</c>`
+- [ ] For workflow commands: `run-workflow` attribute has valid path or "todo"
+- [ ] For task commands: `exec` attribute has valid path
+- [ ] No malformed command attributes
+
+## Agent Type Specific
+
+### Simple Agent
+
+- [ ] Self-contained with no external workflow dependencies OR marked as "todo"
+- [ ] Any embedded data properly structured
+- [ ] Logic description clear if embedded functionality exists
+
+### Expert Agent
+
+- [ ] Sidecar resources clearly defined if applicable
+- [ ] Domain restrictions documented in critical-actions or sidecar-resources
+- [ ] Memory/knowledge file paths specified if used
+- [ ] Access patterns (read/write) defined for resources
+
+### Module Agent
+
+- [ ] Module path correctly references existing module (bmm/bmb/cis or custom)
+- [ ] Config loading path in critical-actions matches module structure
+- [ ] At least one workflow or task reference (or marked "todo")
+- [ ] Module-specific conventions followed
+
+## Critical Actions (if present)
+
+### Standard Actions
+
+- [ ] Config loading path is valid: `{project-root}/bmad/{module}/config.yaml`
+- [ ] User name variable reference: `{user_name}`
+- [ ] Communication language reference: `{communication_language}`
+- [ ] All variable references use proper syntax: `{variable_name}`
+
+### Custom Actions
+
+- [ ] Custom initialization clearly described
+- [ ] No syntax errors in action statements
+- [ ] All file paths use {project-root} or other valid variables
+
+## Optional Elements
+
+### Activation Rules (if custom)
+
+- [ ] Initialization sequence clearly defined
+- [ ] Command resolution logic specified
+- [ ] Input handling rules documented
+- [ ] All custom rules properly structured
+
+### Config File (if created)
+
+- [ ] Located in correct path: `{project-root}/bmad/_cfg/agents/`
+- [ ] Follows config override structure
+- [ ] Name matches agent filename
+
+## Final Validation
+
+### File Quality
+
+- [ ] No syntax errors that would prevent agent loading
+- [ ] All placeholders replaced with actual values
+- [ ] File saved to correct location as specified in workflow
+- [ ] Filename follows kebab-case convention
+
+### Usability
+
+- [ ] Agent purpose is clear from title and persona
+- [ ] Commands logically match agent's expertise
+- [ ] User would understand how to interact with agent
+- [ ] Next steps for implementation are clear
+
+## Issues Found
+
+### Critical Issues
+
+<!-- List any issues that MUST be fixed before agent can function -->
+
+### Warnings
+
+<!-- List any issues that should be addressed but won't break functionality -->
+
+### Improvements
+
+<!-- List any optional enhancements that could improve the agent -->