054b031c1d
## 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>
|
||
|---|---|---|
| .. | ||
| journal-keeper-sidecar | ||
| README.md | ||
| journal-keeper.agent.yaml | ||
README.md
Expert Agent Reference: Personal Journal Keeper (Whisper)
This folder contains a complete reference implementation of a BMAD Expert Agent - an agent with persistent memory and domain-specific resources via a sidecar folder.
Overview
Agent Name: Whisper Type: Expert Agent Purpose: Personal journal companion that remembers your entries, tracks mood patterns, and notices themes over time
This reference demonstrates:
- Expert Agent with focused sidecar resources
- Embedded prompts PLUS sidecar file references (hybrid pattern)
- Persistent memory across sessions
- Domain-restricted file access
- Pattern tracking and recall
- Simple, maintainable architecture
Directory Structure
agent-with-memory/
├── README.md # This file
├── journal-keeper.agent.yaml # Main agent definition
└── journal-keeper-sidecar/ # Agent's private workspace
├── instructions.md # Core directives
├── memories.md # Persistent session memory
├── mood-patterns.md # Emotional tracking data
├── breakthroughs.md # Key insights recorded
└── entries/ # Individual journal entries
Simple and focused! Just 4 core files + a folder for entries.
Key Architecture Patterns
1. Hybrid Command Pattern
Expert Agents can use BOTH:
- Embedded prompts via
action: "#prompt-id"(like Simple Agents) - Sidecar file references via direct paths
menu:
# Embedded prompt (like Simple Agent)
- trigger: 'write'
action: '#guided-entry'
description: "Write today's journal entry"
# Direct sidecar file action
- trigger: 'insight'
action: 'Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md'
description: 'Record a meaningful insight'
This hybrid approach gives you the best of both worlds!
2. Mandatory Critical Actions
Expert Agents MUST load sidecar files explicitly:
critical_actions:
- 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/memories.md'
- 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md'
- 'ONLY read/write files in {agent-folder}/journal-keeper-sidecar/'
Key points:
- Files are loaded at startup
- Domain restriction is enforced
- Agent knows its boundaries
3. Persistent Memory Pattern
The memories.md file stores:
- User preferences and patterns
- Session notes and observations
- Recurring themes discovered
- Growth markers tracked
Critically: This is updated EVERY session, creating continuity.
4. Domain-Specific Tracking
Different files track different aspects:
- memories.md - Qualitative insights and observations
- mood-patterns.md - Quantitative emotional data
- breakthroughs.md - Significant moments
- entries/ - The actual content (journal entries)
This separation makes data easy to reference and update.
5. Simple Sidecar Structure
Unlike modules with complex folder hierarchies, Expert Agent sidecars are flat and focused:
- Just the files the agent needs
- No nested workflows or templates
- Easy to understand and maintain
- All domain knowledge in one place
Comparison: Simple vs Expert vs Module
| Feature | Simple Agent | Expert Agent | Module Agent |
|---|---|---|---|
| Architecture | Single YAML | YAML + sidecar folder | YAML + module system |
| Memory | Session only | Persistent (sidecar files) | Config-driven |
| Prompts | Embedded only | Embedded + external files | Workflow references |
| Dependencies | None | Sidecar folder | Module workflows/tasks |
| Domain Access | None | Restricted to sidecar | Full module access |
| Complexity | Low | Medium | High |
| Use Case | Self-contained tools | Domain experts with memory | Full workflow systems |
The Sweet Spot
Expert Agents are the middle ground:
- More powerful than Simple Agents (persistent memory, domain knowledge)
- Simpler than Module Agents (no workflow orchestration)
- Focused on specific domain expertise
- Personal to the user's needs
When to Use Expert Agents
Perfect for:
- Personal assistants that need memory (journal keeper, diary, notes)
- Domain specialists with knowledge bases (specific project context)
- Agents that track patterns over time (mood, habits, progress)
- Privacy-focused tools with restricted access
- Tools that learn and adapt to individual users
Key indicators:
- Need to remember things between sessions
- Should only access specific folders/files
- Tracks data over time
- Adapts based on accumulated knowledge
File Breakdown
journal-keeper.agent.yaml
- Standard agent metadata and persona
- Embedded prompts for guided interactions
- Menu commands mixing both patterns
- Critical actions that load sidecar files
instructions.md
- Core behavioral directives
- Journaling philosophy and approach
- File management protocols
- Tone and boundary guidelines
memories.md
- User profile and preferences
- Recurring themes discovered
- Session notes and observations
- Accumulated knowledge about the user
mood-patterns.md
- Quantitative tracking (mood scores, energy, etc.)
- Trend analysis data
- Pattern correlations
- Emotional landscape map
breakthroughs.md
- Significant insights captured
- Context and meaning recorded
- Connected to broader patterns
- Milestone markers for growth
entries/
- Individual journal entries saved here
- Each entry timestamped and tagged
- Raw content preserved
- Agent observations separate from user words
Pattern Recognition in Action
Expert Agents excel at noticing patterns:
- Reference past sessions: "Last week you mentioned feeling stuck..."
- Track quantitative data: Mood scores over time
- Spot recurring themes: Topics that keep surfacing
- Notice growth: Changes in language, perspective, emotions
- Connect dots: Relationships between entries
This pattern recognition is what makes Expert Agents feel "alive" and helpful.
Usage Notes
Starting Fresh
The sidecar files are templates. A new user would:
- Start journaling with the agent
- Agent fills in memories.md over time
- Patterns emerge from accumulated data
- Insights build from history
Building Your Own Expert Agent
- Define the domain - What specific area will this agent focus on?
- Choose sidecar files - What data needs to be tracked/remembered?
- Mix command patterns - Use embedded prompts + sidecar references
- Enforce boundaries - Clearly state domain restrictions
- Design for accumulation - How will memory grow over time?
Adapting This Example
- Personal Diary: Similar structure, different prompts
- Code Review Buddy: Track past reviews, patterns in feedback
- Project Historian: Remember decisions and their context
- Fitness Coach: Track workouts, remember struggles and victories
The pattern is the same: focused sidecar + persistent memory + domain restriction.
Key Takeaways
- Expert Agents bridge Simple and Module complexity
- Sidecar folders provide persistent, domain-specific memory
- Hybrid commands use both embedded prompts and file references
- Pattern recognition comes from accumulated data
- Simple structure keeps it maintainable
- Domain restriction ensures focused expertise
- Memory is the superpower - remembering makes the agent truly useful
This reference shows how Expert Agents can be powerful memory-driven assistants while maintaining architectural simplicity.