External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs updates

Browse Source
This commit is contained in:
Brian Madison
2025-10-30 11:26:15 -05:00
parent ec111972a0
commit 663b76a072
13 changed files with 1492 additions and 1483 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
src/modules/bmb/workflows/create-agent/README.md
View File

@@ -1,320 +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 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).
## 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 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
## Quick Start
```bash
# Direct workflow
workflow create-agent
```
### Through BMad Builder 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
```
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
```
- 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
- 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`
- Generate .agent.yaml file
- Create customize file (optional)
- Setup sidecar resources (Expert agents)
- Validate and compile
- Provide usage instructions
## Output
## Output Structure
### Generated Files
#### For Standalone Agents (not part of a module)
**Standalone Agents:**
- **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)"
- Source: `bmad/agents/{filename}.agent.yaml`
- Compiled: `bmad/agents/{filename}.md`
#### For Module Agents
**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
- Source: `src/modules/{module}/agents/{filename}.agent.yaml`
- Compiled: `bmad/{module}/agents/{filename}.md`
### YAML Agent Structure (simplified)
### YAML Structure
```yaml
agent:
metadata:
id: bmad/{{module}}/agents/{{agent_filename}}.md
name: { { agent_name } }
title: { { agent_title } }
icon: { { agent_icon } }
module: { { module } }
id: bmad/{module}/agents/{filename}.md
name: Agent Name
title: Agent Title
icon: 🤖
module: module-name
persona:
role: '...'
identity: '...'
communication_style: '...'
principles: ['...', '...']
menu:
- trigger: example
workflow: '{project-root}/path/to/workflow.yaml'
description: Do the thing
- trigger: command-name
workflow: path/to/workflow.yaml
description: Command description
```
### Optional Customize File
If created, generates at:
`{project-root}/bmad/_cfg/agents/{{module}}-{{agent_filename}}.customize.yaml`
Location: `bmad/_cfg/agents/{module}-{filename}.customize.yaml`
## Installation and Compilation
Allows persona and menu overrides that persist through updates.
### Agent Installation Locations
## Installation
Agents are installed to different locations based on their type:
### Compilation Methods
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:
**Quick Rebuild:**
```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
bmad compile-agents
```
### Build Commands
**During Module Install:**
Automatic compilation when installing modules
Additional build commands for agent management:
**Manual Compilation:**
```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
node tools/cli/bmad-cli.js compile-agents
```
## Requirements
## Examples
- 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")
### Creating a Code Review Agent
## Brainstorming Integration
```
User: I need a code review agent
Builder: Let's brainstorm first...
The optional brainstorming phase (Step -1) provides a seamless path from vague idea to concrete agent concept:
[Brainstorming generates ideas for strict vs friendly reviewer]
### When to Use Brainstorming
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
```
- **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
### Creating a Domain Expert
### Brainstorming Flow
```
Type: Expert
Name: Legal Advisor
Sidecar: legal-knowledge/
Commands:
- *contract-review
- *compliance-check
- *risk-assessment
```
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
## Workflow Files
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.
```
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
```
## Best Practices
### Before Starting
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
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
## Related Documentation
### 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_
- [Agent Types](./agent-types.md)
- [Command Patterns](./agent-command-patterns.md)
- [Communication Styles](./communication-styles.md)
- [BMB Module](../../README.md)

329
src/modules/bmb/workflows/create-module/README.md
View File

@@ -1,220 +1,229 @@
# Build Module Workflow
# Create Module Workflow
## Overview
Interactive scaffolding system creating complete BMad modules with agents, workflows, tasks, and installation infrastructure.
The Build Module workflow is an interactive scaffolding system that creates complete BMAD modules with agents, workflows, tasks, and installation infrastructure. It serves as the primary tool for building new modules in the BMAD ecosystem, guiding users through the entire module creation process from concept to deployment-ready structure.
## Table of Contents
## Key Features
- [Quick Start](#quick-start)
- [Workflow Phases](#workflow-phases)
- [Output Structure](#output-structure)
- [Module Components](#module-components)
- [Best Practices](#best-practices)
- **Interactive Module Planning** - Collaborative session to define module concept, scope, and architecture
- **Intelligent Scaffolding** - Automatic creation of proper directory structures and configuration files
- **Component Integration** - Seamless integration with create-agent and create-workflow workflows
- **Installation Infrastructure** - Complete installer setup with configuration templates
- **Module Brief Integration** - Can use existing module briefs as blueprints for accelerated development
- **Validation and Documentation** - Built-in validation checks and comprehensive README generation
## Usage
### Basic Invocation
## Quick Start
```bash
# Basic invocation
workflow create-module
# With module brief input
workflow create-module --input module-brief-{name}-{date}.md
# Via BMad Builder
*create-module
```
### With Module Brief Input
## Workflow Phases
```bash
# If you have a module brief from the module-brief workflow
workflow create-module --input module-brief-my-module-2024-09-26.md
```
### Phase 1: Concept Definition
### Configuration
- Define module purpose and audience
- Establish module code (kebab-case) and name
- Choose category (Domain, Creative, Technical, Business, Personal)
- Plan component architecture
The workflow loads critical variables from the BMB configuration:
**Module Brief Integration:**
- **custom_module_location**: Where custom modules are created (default: `bmad/`)
- **user_name**: Module author information
- **date**: Automatic timestamp for versioning
- Auto-detects existing briefs
- Uses as pre-populated blueprint
- Accelerates planning phase
## Workflow Structure
### Phase 2: Architecture Planning
### Files Included
- Create directory hierarchy
- Setup configuration system
- Define installer structure
- Establish component folders
### Phase 3: Component Creation
- Optional first agent creation
- Optional first workflow creation
- Component placeholder generation
- Integration validation
### Phase 4: Installation Setup
- Create install-config.yaml
- Configure deployment questions
- Setup installer logic
- Post-install messaging
### Phase 5: Documentation
- Generate comprehensive README
- Create development roadmap
- Provide quick commands
- Document next steps
## Output Structure
### Generated Directory
```
create-module/
├── workflow.yaml # Configuration and metadata
├── instructions.md # Step-by-step execution guide
├── checklist.md # Validation criteria
├── module-structure.md # Module architecture guide
├── installer-templates/ # Installation templates
bmad/{module-code}/
├── agents/ # Agent definitions
├── workflows/ # Workflow processes
├── tasks/ # Reusable tasks
├── templates/ # Document templates
├── data/ # Module data files
├── _module-installer/ # Installation logic
│ ├── install-config.yaml
│ └── installer.js
└── README.md # This file
├── README.md # Module documentation
├── TODO.md # Development roadmap
└── config.yaml # Runtime configuration
```
## Workflow Process
### Configuration Files
### Phase 1: Concept Definition (Steps 1-2)
**install-config.yaml** - Installation questions
**Module Vision and Identity**
```yaml
questions:
- id: user_name
prompt: 'Your name?'
default: 'User'
- id: output_folder
prompt: 'Output location?'
default: './output'
```
- Define module concept, purpose, and target audience
- Establish module code (kebab-case) and friendly name
- Choose module category (Domain-Specific, Creative, Technical, Business, Personal)
- Plan component architecture with agent and workflow specifications
**config.yaml** - Generated from user answers during install
**Module Brief Integration**
```yaml
user_name: 'John Doe'
output_folder: './my-output'
```
- Automatically detects existing module briefs in output folder
- Can load and use briefs as pre-populated blueprints
- Accelerates planning when comprehensive brief exists
## Module Components
### Phase 2: Architecture Planning (Steps 3-4)
### Agents
**Directory Structure Creation**
- Full module agents with workflows
- Expert agents with sidecars
- Simple utility agents
- Creates complete module directory hierarchy
- Sets up agent, workflow, task, template, and data folders
- Establishes installer directory with proper configuration
### Workflows
**Module Configuration**
- Multi-step guided processes
- Configuration-driven
- Web bundle support
- Defines configuration questions in install-config.yaml (config.yaml generated during installation)
- Configures component counts and references
- Sets up output and data folder specifications
### Tasks
### Phase 3: Component Creation (Steps 5-6)
- Reusable operations
- Agent-agnostic
- Modular components
**Interactive Component Building**
### Templates
- Optional creation of first agent using create-agent workflow
- Optional creation of first workflow using create-workflow workflow
- Creates placeholders for components to be built later
**Workflow Integration**
- Seamlessly invokes sub-workflows for component creation
- Ensures proper file placement and structure
- Maintains module consistency across components
### Phase 4: Installation and Documentation (Steps 7-9)
**Installer Infrastructure**
- Creates install-config.yaml with configuration questions for deployment
- Sets up optional installer.js for complex installation logic
- Configures post-install messaging and instructions
**Comprehensive Documentation**
- Generates detailed README.md with usage examples
- Creates development roadmap for remaining components
- Provides quick commands for continued development
### Phase 5: Validation and Finalization (Step 10)
**Quality Assurance**
- Validates directory structure and configuration files
- Checks component references and path consistency
- Ensures installer configuration is deployment-ready
- Provides comprehensive module summary and next steps
## Output
### Generated Files
- **Module Directory**: Complete module structure at `{project-root}/bmad/{module_code}/`
- **Configuration Files**:
- Source: install-config.yaml (configuration questions)
- Target: config.yaml (generated from user answers during installation)
- **Documentation**: README.md, TODO.md development roadmap
- **Component Placeholders**: Structured folders for agents, workflows, and tasks
### Output Structure
The workflow creates a complete module ready for development:
1. **Module Identity** - Name, code, version, and metadata
2. **Directory Structure** - Proper BMAD module hierarchy
3. **Configuration System** - Runtime and installation configs
4. **Component Framework** - Ready-to-use agent and workflow scaffolding
5. **Installation Infrastructure** - Deployment-ready installer
6. **Documentation Suite** - README, roadmap, and development guides
## Requirements
- **Module Brief** (optional but recommended) - Use module-brief workflow first for best results
- **BMAD Core Configuration** - Properly configured BMB config.yaml
- **Build Tools Access** - create-agent and create-workflow workflows must be available
- Document structures
- Output formats
- Report templates
## Best Practices
### Before Starting
### Planning
1. **Create a Module Brief** - Run module-brief workflow for comprehensive planning
2. **Review Existing Modules** - Study similar modules in `/bmad/` for patterns and inspiration
3. **Define Clear Scope** - Have a concrete vision of what the module will accomplish
1. **Use module-brief workflow first** - Creates comprehensive blueprint
2. **Define clear scope** - Avoid feature creep
3. **Plan component interactions** - Map agent/workflow relationships
### During Execution
### Structure
1. **Use Module Briefs** - Load existing briefs when prompted for accelerated development
2. **Start Simple** - Create one core agent and workflow, then expand iteratively
3. **Leverage Sub-workflows** - Use create-agent and create-workflow for quality components
4. **Validate Early** - Review generated structure before proceeding to next phases
1. **Follow conventions** - Use established patterns
2. **Keep components focused** - Single responsibility
3. **Document thoroughly** - Clear README and inline docs
### After Completion
### Development
1. **Follow the Roadmap** - Use generated TODO.md for systematic development
2. **Test Installation** - Validate installer with `bmad install {module_code}`
3. **Iterate Components** - Use quick commands to add agents and workflows
4. **Document Progress** - Update README.md as the module evolves
1. **Start with core agent** - Build primary functionality first
2. **Create key workflows** - Essential processes before edge cases
3. **Test incrementally** - Validate as you build
## Troubleshooting
### Installation
### Common Issues
1. **Minimal config questions** - Only essential settings
2. **Smart defaults** - Sensible out-of-box experience
3. **Clear post-install** - Guide users to first steps
**Issue**: Module already exists at target location
## Integration Points
- **Solution**: Choose a different module code or remove existing module
- **Check**: Verify output folder permissions and available space
### With Other Workflows
**Issue**: Sub-workflow invocation fails
- **module-brief** - Strategic planning input
- **create-agent** - Agent component creation
- **create-workflow** - Workflow building
- **redoc** - Documentation maintenance
- **Solution**: Ensure create-agent and create-workflow workflows are available
- **Check**: Validate workflow paths in config.yaml
### With BMad Core
**Issue**: Installation configuration invalid
- Uses core framework capabilities
- Integrates with module system
- Follows BMad conventions
- **Solution**: Review install-config.yaml syntax and paths
- **Check**: Ensure all referenced paths use {project-root} variables correctly
## Examples
## Customization
### Domain-Specific Module
To customize this workflow:
```
Category: Domain-Specific
Code: legal-advisor
Components:
- Contract Review Agent
- Compliance Workflow
- Legal Templates
```
1. **Modify Instructions** - Update instructions.md to adjust scaffolding steps
2. **Extend Templates** - Add new installer templates in installer-templates/
3. **Update Validation** - Enhance checklist.md with additional quality checks
4. **Add Components** - Integrate additional sub-workflows for specialized components
### Creative Module
## Version History
```
Category: Creative
Code: story-builder
Components:
- Narrative Agent
- Plot Workflow
- Character Templates
```
- **v1.0.0** - Initial release
- Interactive module scaffolding
- Component integration with create-agent and create-workflow
- Complete installation infrastructure
- Module brief integration support
### Technical Module
## Support
```
Category: Technical
Code: api-tester
Components:
- Test Runner Agent
- API Validation Workflow
- Test Report Templates
```
For issues or questions:
## Workflow Files
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
- Study module structure patterns at `module-structure.md`
- Validate output using `checklist.md`
- Consult existing modules in `/bmad/` for examples
```
create-module/
├── workflow.yaml # Configuration
├── instructions.md # Step guide
├── checklist.md # Validation
├── module-structure.md # Architecture
├── installer-templates/ # Install files
└── README.md # This file
```
---
## Related Documentation
_Part of the BMad Method v6 - BMB (Builder) Module_
- [Module Structure](./module-structure.md)
- [Module Brief Workflow](../module-brief/README.md)
- [Create Agent](../create-agent/README.md)
- [Create Workflow](../create-workflow/README.md)
- [BMB Module](../../README.md)