- Add markdownlint-cli2 as dev dependency
- Add lint:md script to package.json
- Add markdownlint job to CI workflow
- Configure 5 rules: heading-increment, no-duplicate-heading,
no-trailing-punctuation, no-bare-urls, no-space-in-emphasis
- Fix existing violations across 19 markdown files
- No auto-fix to prevent destructive changes
Closes#1034🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
## Major Features Added
- **Step-file workflow architecture**: Transform monolithic workflows into granular step files for improved LLM adherence and consistency
- **Multi-menu handler system**: New `handler-multi.xml` enables grouped menu items with fuzzy matching
- **Workflow compliance checker**: Added automated compliance validation for all workflows
- **Create/edit agent workflows**: New structured workflows for agent creation and editing
## Workflow Enhancements
- **Create-workflow**: Expanded from 6 to 14 detailed steps covering tools, design, compliance
- **Granular step execution**: Each workflow step now has dedicated files for focused execution
- **New documentation**: Added CSV data standards, intent vs prescriptive spectrum, and common tools reference
## Complete Migration Status
- **4 workflows fully migrated**: `create-agent`, `edit-agent`, `create-workflow`, and `edit-workflow` now use the new granular step-file architecture
- **Legacy transformation**: `edit-workflow` includes built-in capability to transform legacy single-file workflows into the new improved granular format
- **Future cleanup**: Legacy versions will be removed in a future commit after validation
## Schema Updates
- **Multi-menu support**: Updated agent schema to support `triggers` array for grouped menu items
- **Legacy compatibility**: Maintains backward compatibility with single `trigger` field
- **Discussion enhancements**: Added conversational_knowledge recommendation for discussion agents
## File Structure Changes
- Added: `create-agent/`, `edit-agent/`, `edit-workflow/`, `workflow-compliance-check/` workflows
- Added: Documentation standards and CSV reference files
- Refactored: `create-workflow/steps/` with detailed granular step files
## Handler Improvements
- Enhanced `handler-exec.xml` with clearer execution instructions
- Improved data passing context for executed files
- Better error handling and user guidance
This architectural change significantly improves workflow execution consistency across all LLM models by breaking complex processes into manageable, focused steps. The edit-workflow transformation tool ensures smooth migration of existing workflows to the new format.
- Add deployment-aware handler generation (filters web-only/ide-only commands)
- Remove unused run-workflow handler type (ghost handler cleanup)
- Implement missing validate-workflow and data handler generation
- Update schema validation to support exactly 6 active handler types
- Clean up activation templates and web bundler logic
- Prevent generation of unused handler instructions for better performance
- All 62 tests pass with backward compatibility maintained
Major Changes:
- Add sample custom agents demonstrating installable agent system
- commit-poet: Generates semantic commit messages (BMAD Method repo sample)
- toolsmith: Development tooling expert with knowledge base covering bundlers, deployment, docs, installers, modules, and tests (BMAD Method repo sample)
- Both agents demonstrate custom agent architecture and are installable to projects via BMAD installer system
- Include comprehensive installation guides and sidecar knowledge bases
- Add bmad-quick-flow methodology for rapid development
- create-tech-spec: Direct technical specification workflow
- quick-dev: Flexible execution workflow supporting both tech-spec-driven and direct instruction development
- quick-flow-solo-dev (Barry): 1 man show agent specialized in bmad-quick-flow methodology
- Comprehensive documentation for quick-flow approach and solo development
- Remove deprecated tech-spec workflow track
- Delete entire tech-spec workflow directory and templates
- Remove quick-spec-flow.md documentation (replaced by quick-flow docs)
- Clean up unused epic and story templates
- Fix custom agent installation across IDE installers
- Repair antigravity and multiple IDE installers to properly support custom agents
- Enable custom agent installation via quick installer, agent installer, regular installer, and special agent installer
- All installation methods now accessible via npx with full documentation
Infrastructure:
- Update BMM module configurations and team setups
- Modify workflow status paths to support quick-flow integration
- Reorganize documentation with new agent and workflow guides
- Add custom/ directory for user customizations
- Update platform codes and installer configurations
- Remove verbose explanations and marketing language
- Keep only essential commands and process steps
- Reduce from verbose guide to concise reference
- Focus on what users need to know, not explanations
- Change --path → --source (much clearer purpose)
- Change --target → --destination (more intuitive)
- Update all code references and documentation
- Add advanced parameter examples to installation guide
- Keep short aliases: -s for --source, -t for --destination
Parameters are now much more self-explanatory:
- --source: where to find the agent YAML
- --destination: where to install the compiled agent
- Add npx bmad-method agent-install option for users without cloned repo
- Show both local and npx commands side by side
- Clarify when to use each installation option
- Update automatic updates section with npx option
- Add prominent note about npx capability
Users can now install custom agents without needing to clone the BMAD repository.
## Overview
Major enhancement to edit-agent workflow to match create-agent quality standards, plus critical addition of Expert agent sidecar file support and consolidation of validation checklists into single source of truth.
## 1. edit-agent Workflow Comprehensive Enhancement
### Documentation Reference Updates (workflow.yaml)
**Fixed all broken references** - replaced deleted docs with new comprehensive guides:
- ❌ Removed: agent-types.md, agent-architecture.md, agent-command-patterns.md, communication-styles.md
- ✅ Added structured references:
* Core Concepts: understanding_agent_types, agent_compilation
* Architecture Guides: simple_architecture, expert_architecture, module_architecture
* Design Patterns: menu_patterns, communication_presets, brainstorm_context
* Reference Agents: commit-poet, journal-keeper, module examples, BMM agents
### Critical Persona Field Guidance Added (instructions.md +59 lines)
**The #1 issue in legacy agents** - comprehensive guidance on persona field separation:
- Explains how LLMs interpret each field:
* role → "What knowledge/skills/capabilities do I possess?"
* identity → "What background/experience/context shapes my responses?"
* communication_style → "What verbal patterns/word choice do I use?"
* principles → "What beliefs/philosophy drive my choices?"
- BEFORE/AFTER examples showing common mistakes
- Red flag word detection guide (ensures, experienced, believes in, etc.)
- Pure communication style examples from reference agents
### Enhanced Step 1: Analysis (instructions.md +57 lines)
- References all new comprehensive documentation
- **CRITICAL: Persona field separation analysis**
* Checks for behaviors/role/identity mixed into communication_style
* Compares against communication_presets for purity
* Compares against reference agents for quality
- Warm, conversational feedback explaining issues found
### Massive Step 3 Enhancement: Communication Style Refinement (+122 lines)
**7-step prescriptive pattern for fixing the #1 quality issue:**
1. Diagnose Current Communication Style - red flag word detection
2. Extract Non-Style Content - working copy methodology
3. Discover TRUE Communication Style - interview questions + preset exploration
4. Craft Pure Communication Style - good/bad examples from references
5. Show Before/After With Full Context - complete transformation
6. Validate Against Standards - zero red flags, compare to presets/references
7. Confirm With User - explain changes, read dramatically, refine
Examples from actual reference agents:
- "Treats analysis like a treasure hunt - excited by every clue" (Mary/analyst)
- "Ultra-succinct. Speaks in file paths and AC IDs" (Amelia/dev)
- "Poetic drama and flair with every turn of a phrase" (commit-poet)
### Legacy Type Migration Pattern (+42 lines)
**Comprehensive guide for full/hybrid/standalone → Simple/Expert/Module migration:**
- Clear explanations of modern types (architecture, NOT capability)
- Migration patterns with decision tree
- Structural conversion guides (Simple ↔ Expert)
- Module = design intent clarification
### Enhanced Validation (Step 4)
- Persona field separation validation emphasized
- Updated success message with all quality standards
- Comprehensive checklist validation
### Complete README Documentation (200 lines created)
- Purpose emphasizing persona field separation as #1 issue
- 14 common editing scenarios (persona separation listed FIRST)
- Complete doc reference listing by category
- Dedicated "Critical: Persona Field Separation" section
- Red flag words guide
- 3 detailed usage scenarios
- Quality standards checklist
## 2. Expert Agent Sidecar File Support (NEW)
### Step 1: Smart Path Detection and Loading (+35 lines)
**Automatically detects and loads based on path type:**
```yaml
If path is .agent.yaml → Simple Agent (load single file)
If path is folder → Expert Agent:
- Load .agent.yaml from inside folder
- Load ALL sidecar files (*.md, *.txt, *.csv, *.json, *.yaml)
- Create inventory for reference
- Present: "Loaded agent.yaml + 5 sidecar files: [list]"
```
**Sidecar analysis:**
- Maps which menu items reference which sidecar files (tmpl="path", data="path")
- Checks if all sidecar references actually exist
- Identifies unused/orphaned sidecar files
- Assesses sidecar organization
**Warm expert agent feedback:**
"This is beautifully organized as an Expert agent! The sidecar files include 3 journal templates (daily, weekly, breakthrough) and a mood-patterns knowledge file. Your menu items reference them nicely. I do notice 'old-template.md' isn't referenced anywhere - we could clean that up."
### Step 3: Sidecar Editing Patterns (+47 lines)
**5 complete sidecar editing scenarios:**
1. **Updating templates** - Edit content, verify references work, test variables
2. **Adding new sidecar files** - Create file + add menu item with reference
3. **Removing unused sidecar files** - Confirm unused, ask to delete, clean references
4. **Reorganizing sidecar structure** - Move files, update ALL YAML references
5. **Updating knowledge base files** - Edit .csv/.json/.yaml data directly
**Critical mindset:** "Sidecar files are as much a part of the agent as the YAML!"
### Step 4: Sidecar Validation (+16 lines)
**Conversational validation:**
- "Your menu item 'daily-journal' references 'templates/daily.md'... checking... ✓ exists!"
- Check for orphaned files not referenced anywhere
- Verify sidecar file formats (YAML parses, CSV has headers, markdown well-formed)
- Success message: "✓ All sidecar file references valid - 5 sidecar files, all referenced correctly!"
### README Updates
- "What You'll Need" distinguishes Simple vs Expert paths
- Scenario 2b: Complete Expert agent editing example (journal-keeper template update)
- Updated common scenarios list
## 3. Unified Validation Checklist (Single Source of Truth)
### Problem Solved
- create-agent had outdated checklist (62 lines, no persona field separation)
- edit-agent had enhanced checklist (112 lines, with our improvements)
- Risk of drift and inconsistency between workflows
### Solution: agent-validation-checklist.md (160 lines)
**Canonical location:** `/src/modules/bmb/workflows/create-agent/`
**Comprehensive coverage combining best of both:**
- YAML structure validation
- **Persona field separation** (field separation check, purity check, quality benchmarking)
- Menu validation (including sidecar file path validation)
- Type-specific validation (Simple/Expert/Module)
- Compilation validation
- Common issues and fixes section
**Key sections:**
- Persona Validation (CRITICAL - #1 Quality Issue)
* Field Separation Check (what belongs where)
* Communication Style Purity Check (red flag word detection)
* Quality Benchmarking (compare to presets and references)
- Expert Agent validation (9 sidecar-specific checks)
- Module Agent validation (design intent verification)
- Common Issues and Fixes (real examples with solutions)
### References Updated
**create-agent/workflow.yaml:**
```yaml
validation: "{installed_path}/agent-validation-checklist.md"
```
**edit-agent/workflow.yaml:**
```yaml
# Shared validation checklist (canonical location in create-agent folder)
validation: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/agent-validation-checklist.md"
```
**edit-agent/instructions.md:**
```xml
<note>The validation checklist is shared between create-agent and edit-agent workflows to ensure consistent quality standards.</note>
```
### Files Changed
- ✅ Created: agent-validation-checklist.md (160 lines)
- ❌ Deleted: create-agent/checklist.md (62 lines)
- ❌ Deleted: edit-agent/checklist.md (112 lines)
- Updated: Both workflow.yaml files to reference unified checklist
## Statistics
**Overall changes:** 6 files changed, +553 insertions, -264 deletions
**edit-agent enhancements:**
- instructions.md: +396 lines (comprehensive guidance)
- README.md: +213 lines (complete documentation)
- workflow.yaml: +32 lines (proper doc references)
**Validation unification:**
- Net result: Better quality, less duplication, easier maintenance
- Single source of truth for all agent validation
## Impact
### For Users Editing Agents
- Automatically detects and handles Expert agents with sidecar files
- Clear guidance on fixing #1 issue (persona field separation)
- 7-step prescriptive pattern for communication style refinement
- Warm, educational feedback throughout
- Validates against same standards as create-agent
### For Agent Quality
- Both create and edit workflows use same validation standards
- Persona field separation gets proper attention
- Expert agent sidecar files treated as first-class citizens
- Legacy agents can be migrated to modern standards
- All agents validated against reference implementations
### For Maintenance
- ONE checklist to maintain instead of two
- Consistent quality standards across workflows
- Documentation properly linked to new comprehensive guides
- No risk of checklist drift
This brings edit-agent to the same quality level as create-agent while adding critical Expert agent support and establishing single source of truth for validation.
## 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 extracts game development functionality from BMM into a standalone
BMGD (BMad Game Development) module and implements workflow vendoring to enable
module independence.
BMGD Module Creation:
- Moved agents: game-designer, game-dev, game-architect from BMM to BMGD
- Moved team config: team-gamedev
- Created new Game Dev Scrum Master agent using workflow vendoring pattern
- Reorganized workflows into industry-standard game dev phases:
* Phase 1 (Preproduction): brainstorm-game, game-brief
* Phase 2 (Design): gdd, narrative
* Phase 3 (Technical): game-architecture
* Phase 4 (Production): vendored from BMM workflows
- Updated all module metadata and config_source references
Workflow Vendoring Feature:
- Enables modules to copy workflows from other modules during installation
- Build-time process that updates config_source in vendored workflows
- New agent YAML attribute: workflow-install (build-time metadata)
- Final compiled agents use workflow-install value for workflow attribute
- Implementation in module manager: vendorCrossModuleWorkflows()
- Allows standalone module installation without forced dependencies
Technical Changes:
- tools/cli/lib/yaml-xml-builder.js: Use workflow-install for workflow attribute
- tools/cli/installers/lib/modules/manager.js: Add vendoring functions
- tools/schema/agent.js: Add workflow-install to menu item schema
- Updated 3 documentation files with workflow vendoring details
BMM Workflow Updates:
- workflow-status/init: Added game detection checkpoint
- workflow-status/paths/game-design.yaml: Redirect to BMGD module
- prd/instructions.md: Route game projects to BMGD
- research/instructions-market.md: Reference BMGD for game development
Documentation:
- Created comprehensive BMGD module README
- Added workflow vendoring documentation
- Updated BMB agent creation and module creation guides
Alex Verkhovsky
Brian Madison