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>
|
||
|---|---|---|
| .github | ||
| .husky | ||
| .vscode | ||
| docs | ||
| src | ||
| test | ||
| tools | ||
| .gitignore | ||
| .npmrc | ||
| .nvmrc | ||
| .prettierignore | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| README.md | ||
| eslint.config.mjs | ||
| package-lock.json | ||
| package.json | ||
| prettier.config.mjs | ||
| v6-open-items.md | ||
README.md
BMad CORE + BMad Method
🚨 Alpha Version Notice
v6-alpha is near-beta quality—stable and vastly improved over v4, but documentation is still being refined. New videos coming soon to the BMadCode YouTube channel—subscribe for updates! (There is no v5).
Getting Started:
- Install v6 Alpha:
npx bmad-method install- Install stable v4:
npx bmad-method@latest install- Not sure what to do? Load any agent and run
*workflow-initfor guided setup- v4 Users: View v4 documentation or upgrade guide
Universal Human-AI Collaboration Platform
BMad-CORE (Collaboration Optimized Reflection Engine) amplifies human potential through specialized AI agents. Unlike tools that replace thinking, BMad-CORE guides reflective workflows that bring out your best ideas and AI's full capabilities.
The BMad-CORE powers the BMad Method (probably why you're here!), but you can also use BMad Builder to create custom agents, workflows, and modules for any domain—software development, business strategy, creativity, learning, and more.
🎯 Human Amplification • 🎨 Domain Agnostic • ⚡ Agent-Powered
Table of Contents
- BMad CORE + BMad Method
What is BMad-CORE?
Foundation framework powering all BMad modules:
- Agent Orchestration - Specialized AI personas with domain expertise
- Workflow Engine - Guided multi-step processes with built-in best practices
- Modular Architecture - Extend with domain-specific modules (BMM, BMB, CIS, custom)
- IDE Integration - Works with Claude Code, Cursor, Windsurf, VS Code, and more
- Update-Safe Customization - Your configs persist through all updates
v6 Core Enhancements
- 🎨 Agent Customization - Modify names, roles, personalities via
{bmad_folder}/_cfg/agents/→ Customization Guide - 🌐 Multi-Language - Independent language settings for communication and output
- 👤 Personalization - Agents adapt to your name, skill level, and preferences
- 🔄 Persistent Config - Customizations survive module updates
- ⚙️ Flexible Settings - Configure per-module or globally
- 📦 Web Bundles - Share agents in Gemini Gems and Custom GPTs → Web Bundles Guide
C.O.R.E. Philosophy
- Collaboration: Human-AI partnership leveraging complementary strengths
- Optimized: Battle-tested processes for maximum effectiveness
- Reflection: Strategic questioning that unlocks breakthrough solutions
- Engine: Framework orchestrating 19+ specialized agents and 50+ workflows
BMad-CORE doesn't give you answers—it helps you discover better solutions through guided reflection.
Modules
BMad Method (BMM) - AI-Driven Agile Development
Revolutionary AI-driven agile framework for software and game development. Automatically adapts from single bug fixes to enterprise-scale systems.
v6 Highlights
🎯 Scale-Adaptive Intelligence (3 Planning Tracks)
Automatically adjusts planning depth and documentation based on project needs:
- Quick Flow Track: Fast implementation (tech-spec only) - bug fixes, small features, clear scope
- BMad Method Track: Full planning (PRD + Architecture + UX) - products, platforms, complex features
- Enterprise Method Track: Extended planning (BMad Method + Security/DevOps/Test) - enterprise requirements, compliance
🏗️ Four-Phase Methodology
- Phase 1: Analysis (Optional) - Brainstorming, research, product briefs
- Phase 2: Planning (Required) - Scale-adaptive PRD/tech-spec/GDD
- Phase 3: Solutioning (Track-dependent) - Architecture, (Coming soon: security, DevOps, test strategy)
- Phase 4: Implementation (Iterative) - Story-centric development with just-in-time context
🤖 12 Specialized Agents
PM • Analyst • Architect • Scrum Master • Developer • Test Architect (TEA) • UX Designer • Technical Writer • Game Designer • Game Developer • Game Architect • BMad Master (Orchestrator)
📚 Documentation
- Complete Documentation Hub - Start here for all BMM guides
- Quick Start Guide - Get building in 15 minutes
- Agents Guide - Meet all 12 agents (45 min read)
- 34 Workflow Guides - Complete phase-by-phase reference
- BMM Module Overview - Module structure and quick links
🚀 Quick Start
After installation (see Installation below), choose your path:
Three Planning Tracks:
-
⚡ Quick Flow Track - Bug fixes and small features
- 🐛 Bug fixes in minutes
- ✨ Small features (2-3 related changes)
- 🚀 Rapid prototyping
- → Quick Spec Flow Guide
-
📋 BMad Method Track - Products and platforms
- Complete planning (PRD/GDD)
- Architecture decisions
- Story-centric implementation
- → Complete Quick Start Guide
-
🏢 Brownfield Projects - Add to existing codebases
- Document existing code first
- Then choose Quick Flow or BMad Method
- → Brownfield Guide
Not sure which path? Run *workflow-init and let BMM analyze your project goal and recommend the right track.
📚 Learn More: Scale Adaptive System - How BMM adapts across three planning tracks
BMad Builder (BMB) - Create Custom Solutions
Build your own agents, workflows, and modules using the BMad-CORE framework.
What You Can Build:
- Custom Agents - Domain experts with specialized knowledge
- Guided Workflows - Multi-step processes for any task
- Complete Modules - Full solutions for specific domains
- Three Agent Types - Full module, hybrid, or standalone
Perfect For: Creating domain-specific solutions (legal, medical, finance, education, creative, etc.) or extending BMM with custom development workflows.
Install Custom Agents:
# Install and personalize standalone agents
npx bmad agent-install
Includes reference agents you can copy, customize, and install with personalized behavior. → Custom Agent Installation Guide
Documentation:
- BMB Module Overview - Complete reference
- Custom Agent Installation - Install standalone simple and expert agents
- Create Agent Workflow - Build custom agents
- Create Workflow - Design guided processes
- Create Module - Package complete solutions
Creative Intelligence Suite (CIS) - Innovation & Creativity
AI-powered creative facilitation using proven methodologies and techniques.
5 Interactive Workflows:
- Brainstorming - Generate and refine ideas with 30+ techniques
- Design Thinking - Human-centered problem solving
- Problem Solving - Systematic breakthrough techniques
- Innovation Strategy - Disruptive business model thinking
- Storytelling - Compelling narrative frameworks
5 Specialized Agents: Each with unique facilitation styles and domain expertise
Shared Resource: CIS workflows are used by other modules (BMM's brainstorm-project uses CIS brainstorming)
Documentation:
- CIS Module Overview - Complete reference
- CIS Workflows Guide - All 5 creative workflows
Installation
Prerequisites: Node.js v20+ (Download)
# v6 Alpha (recommended for new projects)
npx bmad-method@alpha install
# Stable v4 (production)
npx bmad-method install
The installer provides:
- Module Selection - Choose BMM, BMB, CIS (or all)
- Configuration - Your name, language preferences, game dev options
- IDE Integration - Automatic setup for your IDE
Installation creates:
your-project/
└── {bmad_folder}/
├── core/ # Core framework + BMad Master agent
├── bmm/ # BMad Method (12 agents, 34 workflows)
├── bmb/ # BMad Builder (1 agent, 7 workflows)
├── cis/ # Creative Intelligence (5 agents, 5 workflows)
└── _cfg/ # Your customizations (survives updates)
└── agents/ # Agent customization files
Next Steps:
- Load any agent in your IDE
- Run
*workflow-initto set up your project workflow path - Follow the Quick Start guide above to choose your planning track
Alternative: Web Bundles - Download pre-built agent bundles for use in Claude Projects, ChatGPT, or Gemini without installation (automatically updated on every commit to main)
🎯 Working with Agents & Commands
Multiple Ways to Execute Workflows:
BMad is flexible - you can execute workflows in several ways depending on your preference and IDE:
Method 1: Agent Menu (Recommended for Beginners)
- Load an agent in your IDE (see IDE-specific instructions)
- Wait for the menu to appear showing available workflows
- Tell the agent what to run using natural language or shortcuts:
- Natural: "Run workflow-init"
- Shortcut:
*workflow-init - Menu number: "Run option 2"
Method 2: Direct Slash Commands
Execute workflows directly using slash commands:
/bmad:bmm:workflows:workflow-init
/bmad:bmm:workflows:prd
/bmad:bmm:workflows:dev-story
Tip: While you can run these without loading an agent first, loading an agent is still recommended - it can make a difference with certain workflows.
Benefits:
- ✅ Mix and match any agent with any workflow
- ✅ Run workflows not in the loaded agent's menu
- ✅ Faster access for experienced users who know the command names
Method 3: Party Mode Execution
Run workflows with multi-agent collaboration:
- Start party mode:
/bmad:core:workflows:party-mode - Execute any workflow - the entire team collaborates on it
- Get diverse perspectives from multiple specialized agents
Perfect for: Strategic decisions, complex workflows, cross-functional tasks
📌 IDE-Specific Note:
Slash command format varies by IDE:
- Claude Code:
/bmad:bmm:workflows:prd- Cursor/Windsurf: May use different syntax - check your IDE's documentation
- VS Code with Copilot Chat: Syntax may differ
See IDE Integration Guides for your specific IDE's command format.
Key Features
🎨 Update-Safe Customization
Modify agents without touching core files:
- Override agent names, personalities, expertise via
{bmad_folder}/_cfg/agents/ - Customizations persist through all updates
- Multi-language support (communication + output)
- Module-level or global configuration
🚀 Intelligent Installation
Smart setup that adapts to your environment:
- Auto-detects v4 installations for smooth upgrades
- Configures IDE integrations (Claude Code, Cursor, Windsurf, VS Code)
- Resolves cross-module dependencies
- Generates unified agent/workflow manifests
📁 Clean Architecture
Everything in one place:
- Single
{bmad_folder}/folder (no scattered files, default folder name is .bmad) - Modules live side-by-side (core, bmm, bmb, cis)
- Your configs in
_cfg/(survives updates) - Easy to version control or exclude
📄 Document Sharding (Advanced)
Optional optimization for large projects (BMad Method and Enterprise tracks):
- Massive Token Savings - Phase 4 workflows load only needed sections (90%+ reduction)
- Automatic Support - All workflows handle whole or sharded documents seamlessly
- Easy Setup - Built-in tool splits documents by headings
- Smart Discovery - Workflows auto-detect format
Documentation
Module Documentation:
- BMM Complete Documentation Hub - All BMM guides, FAQs, troubleshooting
- BMB Module Reference - Build custom agents and workflows
- CIS Workflows Guide - Creative facilitation workflows
Customization & Sharing:
- Agent Customization Guide - Customize agent names, personas, and behaviors
- Web Bundles for Gemini & GPT - Use BMad agents in Gemini Gems and Custom GPTs
Additional Resources:
- Documentation Index - All project documentation
- v4 to v6 Upgrade Guide - Migration instructions
- CLI Tool Guide - Installer and build tool reference
- Contributing Guide - How to contribute
Community & Support
- 💬 Discord Community - Get help, share projects (#general-dev, #bugs-issues)
- 🐛 GitHub Issues - Report bugs, request features
- 🎥 YouTube Channel - Video tutorials and walkthroughs
- ⭐ Star this repo - Stay updated on releases
Development & Quality Checks
For contributors working on the BMAD codebase:
Requirements: Node.js 22+ (see .nvmrc). Run nvm use to switch to the correct version.
Testing & Validation
# Run all quality checks (comprehensive - use before pushing)
npm test
# Individual test suites
npm run test:schemas # Agent schema validation (fixture-based)
npm run test:install # Installation component tests (compilation)
npm run validate:schemas # YAML schema validation
npm run validate:bundles # Web bundle integrity
Code Quality
# Lint check
npm run lint
# Auto-fix linting issues
npm run lint:fix
# Format check
npm run format:check
# Auto-format all files
npm run format:fix
Build & Development
# Bundle for web deployment
npm run bundle
# Test local installation
npm run install:bmad
Pre-commit Hook: Auto-fixes changed files (lint-staged) + validates everything (npm test) CI: GitHub Actions runs all quality checks in parallel on every PR
Contributing
We welcome contributions! See CONTRIBUTING.md for:
- Code contribution guidelines
- Documentation improvements
- Module development
- Issue reporting
License
MIT License - See LICENSE for details
Trademarks: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
Built with ❤️ for the human-AI collaboration community