bmad-method 5.1.3 → 6.0.0-alpha.1

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

@@ -0,0 +1,292 @@
+# BMAD Agent Types Reference
+
+## Overview
+
+BMAD agents come in three distinct types, each designed for different use cases and complexity levels. The type determines where the agent is stored and what capabilities it has.
+
+## Directory Structure by Type
+
+### Standalone Agents (Simple & Expert)
+
+Live in their own dedicated directories under `bmad/agents/`:
+
+```
+bmad/agents/
+├── my-helper/                   # Simple agent
+│   ├── my-helper.agent.yaml     # Agent definition
+│   └── my-helper.md             # Built XML (generated)
+│
+└── domain-expert/               # Expert agent
+    ├── domain-expert.agent.yaml
+    ├── domain-expert.md         # Built XML
+    └── domain-expert-sidecar/   # Expert resources
+        ├── memories.md          # Persistent memory
+        ├── instructions.md      # Private directives
+        └── knowledge/           # Domain knowledge
+
+```
+
+### Module Agents
+
+Part of a module system under `bmad/{module}/agents/`:
+
+```
+bmad/bmm/agents/
+├── product-manager.agent.yaml
+├── product-manager.md           # Built XML
+├── business-analyst.agent.yaml
+└── business-analyst.md          # Built XML
+```
+
+## Agent Types
+
+### 1. Simple Agent
+
+**Purpose:** Self-contained, standalone agents with embedded capabilities
+
+**Location:** `bmad/agents/{agent-name}/`
+
+**Characteristics:**
+
+- All logic embedded within the agent file
+- No external dependencies
+- Quick to create and deploy
+- Perfect for single-purpose tools
+- Lives in its own directory
+
+**Use Cases:**
+
+- Calculator agents
+- Format converters
+- Simple analyzers
+- Static advisors
+
+**YAML Structure (source):**
+
+```yaml
+agent:
+  metadata:
+    name: 'Helper'
+    title: 'Simple Helper'
+    icon: '🤖'
+    type: 'simple'
+  persona:
+    role: 'Simple Helper Role'
+    identity: '...'
+    communication_style: '...'
+    principles: ['...']
+  menu:
+    - trigger: calculate
+      description: 'Perform calculation'
+```
+
+**XML Structure (built):**
+
+```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>
+  <menu>
+    <item cmd="*help">Show commands</item>
+    <item cmd="*calculate">Perform calculation</item>
+    <item cmd="*exit">Exit</item>
+  </menu>
+</agent>
+```
+
+### 2. Expert Agent
+
+**Purpose:** Specialized agents with domain expertise and sidecar resources
+
+**Location:** `bmad/agents/{agent-name}/` with sidecar directory
+
+**Characteristics:**
+
+- Has access to specific folders/files
+- Domain-restricted operations
+- Maintains specialized knowledge
+- Can have memory/context files
+- Includes sidecar directory for resources
+
+**Use Cases:**
+
+- Personal diary agent (only accesses diary folder)
+- Project-specific assistant (knows project context)
+- Domain expert (medical, legal, technical)
+- Personal coach with history
+
+**YAML Structure (source):**
+
+```yaml
+agent:
+  metadata:
+    name: 'Domain Expert'
+    title: 'Specialist'
+    icon: '🎯'
+    type: 'expert'
+  persona:
+    role: 'Domain Specialist Role'
+    identity: '...'
+    communication_style: '...'
+    principles: ['...']
+  critical_actions:
+    - 'Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives'
+    - 'Load COMPLETE file {agent-folder}/memories.md into permanent context'
+    - 'ONLY access {user-folder}/diary/ - NO OTHER FOLDERS'
+  menu:
+    - trigger: analyze
+      description: 'Analyze domain-specific data'
+```
+
+**XML Structure (built):**
+
+```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>
+  <menu>...</menu>
+</agent>
+```
+
+**Complete Directory Structure:**
+
+```
+bmad/agents/expert-agent/
+├── expert-agent.agent.yaml      # Agent YAML source
+├── expert-agent.md              # Built XML (generated)
+└── expert-agent-sidecar/        # Sidecar resources
+    ├── memories.md              # Persistent memory
+    ├── instructions.md          # Private directives
+    ├── knowledge/               # Domain knowledge base
+    │   └── README.md
+    └── sessions/                # Session notes
+```
+
+### 3. Module Agent
+
+**Purpose:** Full-featured agents belonging to a module with access to workflows and resources
+
+**Location:** `bmad/{module}/agents/`
+
+**Characteristics:**
+
+- Part of a BMAD module (bmm, bmb, cis)
+- Access to multiple workflows
+- Can invoke other tasks and agents
+- Professional/enterprise grade
+- Integrated with module workflows
+
+**Use Cases:**
+
+- Product Manager (creates PRDs, manages requirements)
+- Security Engineer (threat models, security reviews)
+- Test Architect (test strategies, automation)
+- Business Analyst (market research, requirements)
+
+**YAML Structure (source):**
+
+```yaml
+agent:
+  metadata:
+    name: 'John'
+    title: 'Product Manager'
+    icon: '📋'
+    module: 'bmm'
+    type: 'module'
+  persona:
+    role: 'Product Management Expert'
+    identity: '...'
+    communication_style: '...'
+    principles: ['...']
+  critical_actions:
+    - 'Load config from {project-root}/bmad/{module}/config.yaml'
+  menu:
+    - trigger: create-prd
+      workflow: '{project-root}/bmad/bmm/workflows/prd/workflow.yaml'
+      description: 'Create PRD'
+    - trigger: validate
+      exec: '{project-root}/bmad/core/tasks/validate-workflow.xml'
+      description: 'Validate document'
+```
+
+**XML Structure (built):**
+
+```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>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">Create PRD</item>
+    <item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">Validate document</item>
+    <item cmd="*exit">Exit</item>
+  </menu>
+</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 and 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 and 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 and 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 and 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,62 @@
+# Build Agent Validation Checklist (YAML Agents)
+
+## Agent Structure Validation
+
+### YAML Structure
+
+- [ ] YAML parses without errors
+- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`
+- [ ] `agent.persona` exists with role, identity, communication_style, and principles
+- [ ] `agent.menu` exists with at least one item
+
+### Core Components
+
+- [ ] `metadata.id` points to final compiled path: `bmad/{{module}}/agents/{{agent}}.md`
+- [ ] `metadata.module` matches the module folder (e.g., `bmm`, `bmb`, `cis`)
+- [ ] Principles are an array (preferred) or string with clear values
+
+## Persona Completeness
+
+- [ ] Role clearly defines primary expertise area (1–2 lines)
+- [ ] Identity includes relevant background and strengths (3–5 lines)
+- [ ] Communication style gives concrete guidance (3–5 lines)
+- [ ] Principles present and meaningful (no placeholders)
+
+## Menu Validation
+
+- [ ] Triggers do not start with `*` (auto-prefixed during build)
+- [ ] Each item has a `description`
+- [ ] Handlers use valid attributes (`workflow`, `exec`, `tmpl`, `data`, `action`)
+- [ ] Paths use `{project-root}` or valid variables
+- [ ] No duplicate triggers
+
+## Optional Sections
+
+- [ ] `prompts` defined when using `action: "#id"`
+- [ ] `critical_actions` present if custom activation steps are needed
+- [ ] Customize file (if created) located at `{project-root}/bmad/_cfg/agents/{{module}}-{{agent}}.customize.yaml`
+
+## Build Verification
+
+- [ ] Run compile to build `.md`: `npm run install:bmad` → "Compile Agents" (or `bmad install` → Compile)
+- [ ] Confirm compiled file exists at `{project-root}/bmad/{{module}}/agents/{{agent}}.md`
+
+## Final Quality
+
+- [ ] Filename is kebab-case and ends with `.agent.yaml`
+- [ ] Output location correctly placed in module or standalone directory
+- [ ] Agent purpose and commands are clear and consistent
+
+## 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 -->