mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
feat: Complete BMAD agent creation system with install tooling, references, and field guidance
## Overview
This commit represents a complete overhaul of the BMAD agent creation system, establishing clear standards for agent development, installation workflows, and persona design. The changes span documentation, tooling, reference implementations, and field-specific guidance.
## Key Components
### 1. Agent Installation Infrastructure
**New CLI Command: `agent-install`**
- Interactive agent installation with persona customization
- Supports Simple (single YAML), Expert (sidecar files), and Module agents
- Template variable processing with Handlebars-style syntax
- Automatic compilation from YAML to XML (.md) format
- Manifest tracking and IDE integration (Claude Code, Cursor, Windsurf, etc.)
- Source preservation in `_cfg/custom/agents/` for reinstallation
**Files Created:**
- `tools/cli/commands/agent-install.js` - Main CLI command
- `tools/cli/lib/agent/compiler.js` - YAML to XML compilation engine
- `tools/cli/lib/agent/installer.js` - Installation orchestration
- `tools/cli/lib/agent/template-engine.js` - Handlebars template processing
**Compiler Features:**
- Auto-injects frontmatter, activation, handlers, help/exit menu items
- Smart handler inclusion (only includes action/workflow/exec/tmpl handlers actually used)
- Proper XML escaping and formatting
- Persona name customization (e.g., "Fred the Commit Poet")
### 2. Documentation Overhaul
**Deleted Bloated/Outdated Docs (2,651 lines removed):**
- Old verbose architecture docs
- Redundant pattern files
- Outdated workflow guides
**Created Focused, Type-Specific Docs:**
- `src/modules/bmb/docs/understanding-agent-types.md` - Architecture vs capability distinction
- `src/modules/bmb/docs/simple-agent-architecture.md` - Self-contained agents
- `src/modules/bmb/docs/expert-agent-architecture.md` - Agents with sidecar files
- `src/modules/bmb/docs/module-agent-architecture.md` - Workflow-integrated agents
- `src/modules/bmb/docs/agent-compilation.md` - YAML → XML process
- `src/modules/bmb/docs/agent-menu-patterns.md` - Menu design patterns
- `src/modules/bmb/docs/index.md` - Documentation hub
**Net Result:** ~1,930 line reduction while adding MORE value through focused content
### 3. Create-Agent Workflow Enhancements
**Critical Persona Field Guidance Added to Step 4:**
Explains how the LLM interprets each persona field when the agent activates:
- **role** → "What knowledge, skills, and capabilities do I possess?"
- **identity** → "What background, experience, and context shape my responses?"
- **communication_style** → "What verbal patterns, word choice, quirks, and phrasing do I use?"
- **principles** → "What beliefs and operating philosophy drive my choices?"
**Key Insight:** `communication_style` should ONLY describe HOW the agent talks, not restate role/identity/principles. The `communication-presets.csv` provides 60 pure communication styles with NO role/identity/principles mixed in.
**Files Updated:**
- `src/modules/bmb/workflows/create-agent/instructions.md` - Added persona field interpretation guide
- `src/modules/bmb/workflows/create-agent/brainstorm-context.md` - Refined to 137 lines
- `src/modules/bmb/workflows/create-agent/communication-presets.csv` - 60 styles across 13 categories
### 4. Reference Agent Cleanup
**Removed install_config Personality Bloat:**
Understanding: Future installer will handle personality customization, so stripped all personality toggles from reference agents.
**commit-poet.agent.yaml** (Simple Agent):
- BEFORE: 36 personality combinations (3 enthusiasm × 3 depths × 4 styles) = decision fatigue
- AFTER: Single concise persona with pure communication style
- Changed from verbose conditionals to: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
- Reduction: 248 lines → 153 lines (38% reduction)
**journal-keeper.agent.yaml** (Expert Agent):
- Stripped install_config, simplified communication_style
- Shows proper Expert agent structure with sidecar files
**security-engineer.agent.yaml & trend-analyst.agent.yaml** (Module Agents):
- Added header comments explaining WHY Module Agent (design intent, not just location)
- Clarified: Module agents are designed FOR ecosystem integration, not capability-limited
**Files Updated:**
- `src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml`
- `src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml`
### 5. BMM Agent Voice Enhancement
**Gave all 9 BMM agents distinct, memorable communication voices:**
**Mary (analyst)** - The favorite! Changed from generic "systematic and probing" to:
"Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision."
**Other Notable Voices:**
- **John (pm):** "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
- **Winston (architect):** "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
- **Amelia (dev):** "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
- **Bob (sm):** "Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity."
- **Sally (ux-designer):** "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."
**Pattern Applied:** Moved behaviors from communication_style to principles, keeping communication_style as PURE verbal patterns.
**Files Updated:**
- `src/modules/bmm/agents/analyst.agent.yaml`
- `src/modules/bmm/agents/pm.agent.yaml`
- `src/modules/bmm/agents/architect.agent.yaml`
- `src/modules/bmm/agents/dev.agent.yaml`
- `src/modules/bmm/agents/sm.agent.yaml`
- `src/modules/bmm/agents/tea.agent.yaml`
- `src/modules/bmm/agents/tech-writer.agent.yaml`
- `src/modules/bmm/agents/ux-designer.agent.yaml`
- `src/modules/bmm/agents/frame-expert.agent.yaml`
### 6. Linting Fixes
**ESLint Compliance:**
- Replaced all `'utf-8'` with `'utf8'` (unicorn/text-encoding-identifier-case)
- Changed `variables.hasOwnProperty(varName)` to `Object.hasOwn(variables, varName)` (unicorn/prefer-object-has-own)
- Replaced `JSON.parse(JSON.stringify(...))` with `structuredClone(...)` (unicorn/prefer-structured-clone)
- Fixed empty YAML mapping values in sample files
**Files Fixed:**
- 7 JavaScript files across agent tooling (compiler, installer, commands, IDE integration)
- 1 YAML sample file
## Architecture Decisions
### Agent Types Are About Architecture, Not Capability
- **Simple:** Self-contained in single YAML (NOT limited in capability)
- **Expert:** Includes sidecar files (templates, docs, etc.)
- **Module:** Designed for BMAD ecosystem integration (workflows, cross-agent coordination)
### Persona Field Separation Critical for LLM Interpretation
The LLM needs distinct fields to understand its role:
- Mixing role/identity/principles into communication_style confuses the persona
- Pure communication styles (from communication-presets.csv) have ZERO role/identity/principles content
- Example DON'T: "Experienced analyst who uses systematic approaches..." (mixing identity + style)
- Example DO: "Systematic and probing. Structures findings hierarchically." (pure style)
### Install-Time vs Runtime Configuration
- Template variables ({{var}}) resolve at compile-time
- Runtime variables ({user_name}, {bmad_folder}) resolve when agent activates
- Future installer will handle personality customization, so agents should ship with single default persona
## Testing
- All linting passes (ESLint with max-warnings=0)
- Agent compilation tested with commit-poet, journal-keeper examples
- Install workflow validated with Simple and Expert agent types
- Manifest tracking and IDE integration verified
## Impact
This establishes BMAD as having a complete, production-ready agent creation and installation system with:
- Clear documentation for all agent types
- Automated compilation and installation
- Strong persona design guidance
- Reference implementations showing best practices
- Distinct, memorable agent voices throughout BMM module
Co-Authored-By: BMad Builder <builder@bmad.dev>
Co-Authored-By: Mary the Analyst <analyst@bmad.dev>
Co-Authored-By: Paige the Tech Writer <tech-writer@bmad.dev>
This commit is contained in:
Brian Madison
169
docs/custom-agent-installation.md
Normal file
169
docs/custom-agent-installation.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# Custom Agent Installation
|
||||
|
||||
Install and personalize BMAD agents in your project.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# From your project directory with BMAD installed
|
||||
npx bmad agent-install
|
||||
```
|
||||
|
||||
Or if you have bmad-cli installed globally:
|
||||
|
||||
```bash
|
||||
bmad agent-install
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
1. **Discovers** available agent templates from your custom agents folder
|
||||
2. **Prompts** you to personalize the agent (name, behavior, preferences)
|
||||
3. **Compiles** the agent with your choices baked in
|
||||
4. **Installs** to your project's `.bmad/custom/agents/` directory
|
||||
5. **Creates** IDE commands for all your configured IDEs (Claude Code, Codex, Cursor, etc.)
|
||||
6. **Saves** your configuration for automatic reinstallation during BMAD updates
|
||||
|
||||
## Options
|
||||
|
||||
```bash
|
||||
bmad agent-install [options]
|
||||
|
||||
Options:
|
||||
-p, --path <path> Direct path to specific agent YAML file or folder
|
||||
-d, --defaults Use default values without prompting
|
||||
-t, --target <path> Target installation directory
|
||||
```
|
||||
|
||||
## Example Session
|
||||
|
||||
```
|
||||
🔧 BMAD Agent Installer
|
||||
|
||||
Found BMAD at: /project/.bmad
|
||||
Searching for agents in: /project/.bmad/custom/agents
|
||||
|
||||
Available Agents:
|
||||
|
||||
1. 📄 commit-poet (simple)
|
||||
2. 📚 journal-keeper (expert)
|
||||
|
||||
Select agent to install (number): 1
|
||||
|
||||
Selected: commit-poet
|
||||
|
||||
📛 Agent Persona Name
|
||||
|
||||
Agent type: commit-poet
|
||||
Default persona: Inkwell Von Comitizen
|
||||
|
||||
Custom name (or Enter for default): Fred
|
||||
|
||||
Persona: Fred
|
||||
File: fred-commit-poet.md
|
||||
|
||||
📝 Agent Configuration
|
||||
|
||||
What's your preferred default commit message style?
|
||||
* 1. Conventional (feat/fix/chore)
|
||||
2. Narrative storytelling
|
||||
3. Poetic haiku
|
||||
4. Detailed explanation
|
||||
Choice (default: 1): 1
|
||||
|
||||
How enthusiastic should the agent be?
|
||||
1. Moderate - Professional with personality
|
||||
* 2. High - Genuinely excited
|
||||
3. EXTREME - Full theatrical drama
|
||||
Choice (default: 2): 3
|
||||
|
||||
Include emojis in commit messages? [Y/n]: y
|
||||
|
||||
✨ Agent installed successfully!
|
||||
Name: fred-commit-poet
|
||||
Location: /project/.bmad/custom/agents/fred-commit-poet
|
||||
Compiled: fred-commit-poet.md
|
||||
|
||||
✓ Source saved for reinstallation
|
||||
✓ Added to agent-manifest.csv
|
||||
✓ Created IDE commands:
|
||||
claude-code: /bmad:custom:agents:fred-commit-poet
|
||||
codex: /bmad-custom-agents-fred-commit-poet
|
||||
github-copilot: bmad-agent-custom-fred-commit-poet
|
||||
```
|
||||
|
||||
## Reinstallation
|
||||
|
||||
Custom agents are automatically reinstalled when you run `bmad init --quick`. Your personalization choices are preserved in `.bmad/_cfg/custom/agents/`.
|
||||
|
||||
## Installing Reference Agents
|
||||
|
||||
The BMAD source includes example agents you can install. **You must copy them to your project first.**
|
||||
|
||||
### Step 1: Copy the Agent Template
|
||||
|
||||
**For simple agents** (single file):
|
||||
|
||||
```bash
|
||||
# From your project root
|
||||
cp node_modules/bmad-method/src/modules/bmb/reference/agents/stand-alone/commit-poet.agent.yaml \
|
||||
.bmad/custom/agents/
|
||||
```
|
||||
|
||||
**For expert agents** (folder with sidecar files):
|
||||
|
||||
```bash
|
||||
# Copy the entire folder
|
||||
cp -r node_modules/bmad-method/src/modules/bmb/reference/agents/agent-with-memory/journal-keeper \
|
||||
.bmad/custom/agents/
|
||||
```
|
||||
|
||||
### Step 2: Install and Personalize
|
||||
|
||||
```bash
|
||||
npx bmad agent-install
|
||||
# or: bmad agent-install
|
||||
```
|
||||
|
||||
The installer will:
|
||||
|
||||
1. Find the copied template in `.bmad/custom/agents/`
|
||||
2. Prompt for personalization (name, behavior, preferences)
|
||||
3. Compile and install with your choices baked in
|
||||
4. Create IDE commands for immediate use
|
||||
|
||||
### Available Reference Agents
|
||||
|
||||
**Simple (standalone file):**
|
||||
|
||||
- `commit-poet.agent.yaml` - Commit message artisan with style preferences
|
||||
|
||||
**Expert (folder with sidecar):**
|
||||
|
||||
- `journal-keeper/` - Personal journal companion with memory and pattern recognition
|
||||
|
||||
Find these in the BMAD source:
|
||||
|
||||
```
|
||||
src/modules/bmb/reference/agents/
|
||||
├── stand-alone/
|
||||
│ └── commit-poet.agent.yaml
|
||||
└── agent-with-memory/
|
||||
└── journal-keeper/
|
||||
├── journal-keeper.agent.yaml
|
||||
└── journal-keeper-sidecar/
|
||||
```
|
||||
|
||||
## Creating Your Own
|
||||
|
||||
Place your `.agent.yaml` files in `.bmad/custom/agents/`. Use the reference agents as templates.
|
||||
|
||||
Key sections in an agent YAML:
|
||||
|
||||
- `metadata`: name, title, icon, type
|
||||
- `persona`: role, identity, communication_style, principles
|
||||
- `prompts`: reusable prompt templates
|
||||
- `menu`: numbered menu items
|
||||
- `install_config`: personalization questions (optional, at end of file)
|
||||
|
||||
See the reference agents for complete examples with install_config templates and XML-style semantic tags.
|
||||
@@ -1,54 +0,0 @@
|
||||
# Web Bundler Usage
|
||||
|
||||
ALPHA NOTE: Bundling of individual agents might work, team bundling is being reworked and will come with Beta release soon.
|
||||
|
||||
The web bundler creates self-contained XML bundles for BMAD agents, packaging all dependencies for web deployment.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Bundle all agents from all modules
|
||||
npm run bundle
|
||||
|
||||
# Clean and rebundle (removes old bundles first)
|
||||
npm run rebundle
|
||||
```
|
||||
|
||||
## Custom Output Directory
|
||||
|
||||
```bash
|
||||
# Bundle to custom directory
|
||||
node tools/cli/bundlers/bundle-web.js all --output ./my-bundles
|
||||
|
||||
# Rebundle to custom directory (auto-cleans first)
|
||||
node tools/cli/bundlers/bundle-web.js rebundle --output /absolute/path/to/custom/directory
|
||||
|
||||
# Bundle specific module to custom directory
|
||||
node tools/cli/bundlers/bundle-web.js module bmm --output ./custom-folder
|
||||
|
||||
# Bundle specific agent to custom directory
|
||||
node tools/cli/bundlers/bundle-web.js agent bmm analyst -o ./custom-folder
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Bundles are generated in `web-bundles/` directory by default when run from the root of the clones project:
|
||||
|
||||
```
|
||||
web-bundles/
|
||||
├── [module-name]/
|
||||
│ └── agents/
|
||||
│ └── [agent-name].xml
|
||||
```
|
||||
|
||||
## Skipping Agents
|
||||
|
||||
Agents with `bundle="false"` attribute are automatically skipped during bundling.
|
||||
|
||||
## Bundle Contents
|
||||
|
||||
Each bundle includes:
|
||||
|
||||
- Agent definition with web activation
|
||||
- All resolved dependencies
|
||||
- Manifests for agent/team discovery
|
||||
Reference in New Issue
Block a user