- Add persistent warning loop when no tools selected in installer
- Users must press spacebar to select, not just highlight
- Red warning explains the issue and offers to go back
- Only way to proceed without tools is explicit "No" confirmation
- Promote Google Antigravity to preferred/recommended IDE section
## 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>
Implements installer for Google Antigravity IDE with flattened slash command
naming to match Antigravity's namespace requirements.
Key features:
- Flattened file naming (bmad-module-agents-name.md) for proper slash commands
- Subagent installation support (project-level or user-level)
- Module-specific injection configuration
- Agent, workflow, task, and tool command generation
Implementation:
- Added AntigravitySetup class extending BaseIdeSetup
- Extracted flattenFilename() to BaseIdeSetup for reuse across IDE handlers
- Uses .agent/workflows directory structure
- Supports both interactive and non-interactive configuration
Fixes:
- Proper namespace isolation: /bmad-module-agents-dev instead of /dev
- Prevents conflicts between modules with same agent names
Note: This installer shares 95% of its code with claude-code.js.
Future refactoring could extract common patterns to IdeWithSlashCommandsSetup
base class (see design documents for details).
Add support for choosing between global and project-specific installation
locations for Codex CLI prompts with CODEX_HOME configuration instructions.
Changes:
- Add collectConfiguration() to prompt for installation location (default: global)
- Support global (~/.codex/prompts) and project-specific (<project>/.codex/prompts)
- Display OS-specific CODEX_HOME setup instructions before user confirms
- Update detect() and cleanup() to handle both installation locations
Installation options:
- Global: Simple, works immediately, but prompts reference specific .bmad path
- Project-specific: Requires CODEX_HOME, better for multi-project workflows
- Unix/Mac: alias codex='CODEX_HOME="$PWD/.codex" codex'
- Windows: codex.cmd wrapper with %~dp0
- Add merging logic for customizeYaml.prompts and customizeYaml.memories in loadAndMergeAgent()
- Implement buildMemoriesXml() method to output memories XML section
- Update buildPromptsXml() to use <content> wrapper instead of CDATA for better compatibility
- Integrate memories output into convertToXml() between persona and prompts sections
Changes:
1. Line 123-131: Added prompts and memories append logic in loadAndMergeAgent()
2. Line 215-218: Added memories XML output in convertToXml()
3. Line 286-301: New buildMemoriesXml() method
4. Line 312-315: Updated prompts to use <content> wrapper for consistency
This allows users to customize agents via bmad/_cfg/agents/*.customize.yaml with:
- prompts: Array of {id, content} objects for action handlers
- memories: Array of strings for persistent agent memories
## Summary
- Add ide-only and web-only boolean fields to agent menu schema
- Filter menu items based on build target (web bundle vs local IDE)
- Update BMM agent definitions with platform restrictions and improved descriptions
- Update frame-expert agent icon to 📐 and add webskip flag
## Changes
### Schema & Bundler Updates
- tools/schema/agent.js: Add ide-only and web-only optional boolean fields
- tools/cli/lib/yaml-xml-builder.js: Filter ide-only items from web bundles
- tools/cli/lib/xml-handler.js: Pass forWebBundle flag through build chain
### Agent Updates
- frame-expert: Change icon to 📐, add webskip flag, improve principle formatting
- pm: Mark workflow-init and correct-course as ide-only, advanced-elicitation as web-only
- ux-designer: Rename trigger to create-ux-design, mark advanced-elicitation as web-only
- sm: Rename triggers for consistency (story-context → create-story-context)
- analyst: Add research workflow after brainstorm, mark advanced-elicitation as web-only
- architect: Remove document field from validate-architecture, add web-only flag
- dev: Update persona and critical actions for clarity
- tech-writer: Add party-mode workflow, mark advanced-elicitation as web-only
- tea: Mark advanced-elicitation as web-only
- All agents: Standardize party-mode description
This enables platform-specific functionality where some commands only make sense
in IDE environments (workflow-init) or web interfaces (advanced-elicitation).
Remove hardcoded .bmad folder references throughout documentation and source files, replacing them with the configurable {bmad_folder} placeholder. This change enables users to customize the BMAD installation folder name via configuration, improving flexibility and reducing coupling to a specific directory structure.
Changes include:
- Update all documentation to reference {bmad_folder} instead of .bmad
- Remove legacy configuration files from .bmad and .claude directories
- Update workflow.xml and CLI documentation with new placeholder syntax
- Installation path is now fully configurable, allowing users to specify custom installation directories during setup
- Default installation location changed to .bmad (hidden directory) for cleaner project root organization
Web Bundle Improvements:
- All web bundles (single agent and team) now include party mode support for multi-agent collaboration!
- Advanced elicitation capabilities integrated into standalone agents
- All bundles enhanced with party mode agent manifests
- Added default-party.csv files to bmm, bmgd, and cis module teams
- The default party file is what will be used with single agent bundles. teams can customize for different party configurations before web bundling through a setting in the team yaml file
- New web bundle outputs for all agents (analyst, architect, dev, pm, sm, tea, tech-writer, ux-designer, game-*, creative-squad)
Phase 4 Workflow Updates (In Progress):
- Initiated shift to separate phase 4 implementation artifacts from documentation
- Phase 4 implementation artifacts (stories, code review, sprint plan, context files) will move to dedicated location outside docs folder
- Installer questions and configuration added for artifact path selection
- Updated workflow.yaml files for code-review, sprint-planning, story-context, epic-tech-context, and retrospective workflows to support this, but still might require some udpates
Additional Changes:
- New agent and action command header models for standardization
- Enhanced web-bundle-activation-steps fragment
- Updated web-bundler.js to support new structure
- VS Code settings updated for new .bmad directory
- Party mode instructions and workflow enhanced for better orchestration
IDE Installer Updates:
- Show version number of installer in cli
- improved Installer UX
- Gemini TOML Improved to have clear loading instructions with @ commands
- All tools agent launcher mds improved to use a central file template critical indication isntead of hardcoding in 2 different locations.
- Deduplicate module lists in manifest generator using Set to prevent duplicate entries in installed manifests
- Update GitHub Copilot tool names to match official VS Code documentation (November 2025)
- Clean up legacy bmad/, bmd/, and web-bundles directories
Enhanced removeSkippedWorkflowCommands() to properly remove all menu item
formats that reference workflows with web_bundle: false:
1. <item> tags with workflow attribute
2. <item> tags with run-workflow attribute
3. <c> tags with run-workflow attribute (legacy)
This ensures that workflows not designed for web bundles (like workflow-status
which requires filesystem access) are completely excluded from web bundles,
including their menu items.
Verified:
- workflow-status menu item removed from SM agent
- workflow-status YAML not included in bundle dependencies
Instead of displaying an empty "⚠ Missing Dependencies by Agent:" section
when all dependencies are resolved, now shows a positive message:
"✓ No missing dependencies"
This improves the user experience by providing clear feedback that workflow
vendoring successfully resolved all dependencies.
The web bundler now performs workflow vendoring before bundling agents,
similar to the module installer. This ensures that workflows referenced
via workflow-install attributes are copied from their source locations
to their destination locations before the bundler attempts to resolve
and bundle them.
Changes:
- Added vendorCrossModuleWorkflows() method to WebBundler class
- Added updateWorkflowConfigSource() helper method
- Integrated vendoring into bundleAll(), bundleModule(), and bundleAgent()
- Workflows are vendored before agent discovery and bundling
- Config_source is updated in vendored workflows to reference target module
This fixes missing dependency warnings for BMGD agents that vendor
BMM workflows for Phase 4 (Production) workflows.
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
- Add final newline check to YAML config generation
- Add final newline check to YAML manifest generation
- Add final newline check to agent .md file generation
- Ensures all text files end with \n per POSIX standard
- Fixes 'No newline at end of file' git warnings
When preserving CSV rows from existing manifest files during module updates,
rows from older schema versions (without the 'standalone' column) were being
added to CSVs with new schema headers, causing "Invalid Record Length" errors
during parsing.
Added schema upgrade logic to detect old column structure and upgrade preserved
rows by adding missing columns with appropriate default values. This ensures all
CSV rows match the header column count, fixing installation errors.
Fixes column count mismatch in:
- workflow-manifest.csv (added standalone column)
- task-manifest.csv (added standalone column)
- tool-manifest.csv (added standalone column)
- agent-manifest.csv (schema validation for future-proofing)
- Added docs/ide-info/opencode.md
- Added tool/cli/installers/lib/ide/opencode.js
- Modified tools/installers/lib/ide/core/detector.js to include
detection for opencode command dir
- Modified tools/cli/platform-codes.yaml to include opencode config
- Modified tools/cli/installers/lib/ide/workflow-command-template.md to
include frontmatter with description as opencode requires this for
commands and adding it to the template by default does not seem to
impact other IDEs
- Modified src/modules/bmm/workflows/workflow-status/workflow.yaml
description so that it properly escapes quotes when interpolated in the
teplate
- Unify BMad directory name from 'BMad' to lowercase 'bmad'
- Use shared utility functions [getAgentsFromBmad] and [getTasksFromBmad] to fetch agents and tasks
- Create independent subdirectory structures (agents, tasks) for each module
- Update file writing paths to store TOML files by module classification
- Remove legacy QWEN.md merged documentation generation logic
- Add TOML metadata header support (not available in previous versions)
- Clean up old version configuration directories (including uppercase BMad and bmad-method)
Previously, the installer created empty tasks/ directories under
.claude/commands/bmad/{module}/ and attempted to copy task files.
Since getTasksFromDir() filters for .md files only and all actual
tasks are .xml files, these directories remained empty.
Tasks are utility files referenced by agents via exec attributes
(e.g., exec="{project-root}/bmad/core/tasks/workflow.xml") and
should remain in the bmad/ directory - they are not slash commands.
Changes:
- Removed tasks directory creation in module setup
- Removed tasks copying logic (15 lines)
- Removed taskCount from console output
- Removed tasks property from return value
- Removed unused getTasksFromBmad and getTasksFromDir imports
- Updated comment to clarify agents-only installation
Verified: No tasks/ directories created in .claude/commands/bmad/
while task files remain accessible in bmad/core/tasks/
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
