mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-17 09:45:25 +00:00
5702195ef7
* feat: Add provider-agnostic TTS integration via injection point system
Implements comprehensive Text-to-Speech integration for BMAD agents using a generic
TTS_INJECTION marker system. When AgentVibes (or any compatible TTS provider) is
installed, all BMAD agents can speak their responses with unique AI voices.
## Key Features
**Provider-Agnostic Architecture**
- Uses generic `TTS_INJECTION` markers instead of vendor-specific naming
- Future-proof for multiple TTS providers beyond AgentVibes
- Clean separation - BMAD stays TTS-agnostic, providers handle injection
**Installation Flow**
- BMAD → AgentVibes: TTS instructions injected when AgentVibes detects existing BMAD installation
- AgentVibes → BMAD: TTS instructions injected during BMAD installation when AgentVibes detected
- User must manually create voice assignment file when AgentVibes installs first (documented limitation)
**Party Mode Voice Support**
- Each agent speaks with unique assigned voice in multi-agent discussions
- PM, Architect, Developer, Analyst, UX Designer, etc. - all with distinct voices
**Zero Breaking Changes**
- Fully backward compatible - works without any TTS provider
- `TTS_INJECTION` markers are benign HTML comments if not processed
- No changes to existing agent behavior or non-TTS workflows
## Implementation Details
**Files Modified:**
- `tools/cli/installers/lib/core/installer.js` - TTS injection processing logic
- `tools/cli/lib/ui.js` - AgentVibes detection and installation prompts
- `tools/cli/commands/install.js` - Post-install guidance for AgentVibes setup
- `src/utility/models/fragments/activation-rules.xml` - TTS_INJECTION marker for agents
- `src/core/workflows/party-mode/instructions.md` - TTS_INJECTION marker for party mode
**Injection Point System:**
```xml
<rules>
- ALWAYS communicate in {communication_language}
<!-- TTS_INJECTION:agent-tts -->
- Stay in character until exit selected
</rules>
```
When AgentVibes is detected, the installer replaces this marker with:
```
- When responding to user messages, speak your responses using TTS:
Call: `.claude/hooks/bmad-speak.sh '{agent-id}' '{response-text}'` after each response
IMPORTANT: Use single quotes - do NOT escape special characters like ! or $
```
**Special Character Handling:**
- Explicit guidance to use single quotes without escaping
- Prevents "backslash exclamation" artifacts in speech
**User Experience:**
```
User: "How should we architect this feature?"
Architect: [Text response] + 🔊 [Professional voice explains architecture]
```
Party Mode:
```
PM (John): "I'll focus on user value..." 🔊 [Male professional voice]
UX Designer (Sara): "From a user perspective..." 🔊 [Female voice]
Architect (Marcus): "The technical approach..." 🔊 [Male technical voice]
```
## Testing
**Unit Tests:** ✅ 62/62 passing
- 49/49 schema validation tests
- 13/13 installation component tests
**Integration Testing:**
- ✅ BMAD → AgentVibes (automatic injection)
- ✅ AgentVibes → BMAD (automatic injection)
- ✅ No TTS provider (markers remain as comments)
## Documentation
Comprehensive testing guide created with:
- Both installation scenario walkthroughs
- Verification commands and expected outputs
- Troubleshooting guidance
## Known Limitations
**AgentVibes → BMAD Installation Order:**
When AgentVibes installs first, voice assignment file must be created manually:
```bash
mkdir -p .bmad/_cfg
cat > .bmad/_cfg/agent-voice-map.csv << 'EOF'
agent_id,voice_name
pm,en_US-ryan-high
architect,en_US-danny-low
dev,en_US-joe-medium
EOF
```
This limitation exists to prevent false legacy v4 detection warnings from BMAD installer.
**Recommended:** Install BMAD first, then AgentVibes for automatic voice assignment.
## Related Work
**Companion Implementation:**
- Repository: paulpreibisch/AgentVibes
- Commits: 6 commits implementing injection processing and voice routing
- Features: Retroactive injection, file path extraction, escape stripping
**GitHub Issues:**
- paulpreibisch/AgentVibes#36 - BMAD agent ID support
## Breaking Changes
None. Feature is opt-in and requires separate TTS provider installation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Enforce project hooks over global hooks in party mode
before, claude would sometimes favor global agent vibes hooks over project specific
* feat: Automate AgentVibes installer invocation after BMAD install
Instead of showing manual installation instructions, the installer now:
- Prompts "Press Enter to start AgentVibes installer..."
- Automatically runs npx agentvibes@latest install
- Handles errors gracefully with fallback instructions
This provides a seamless installation flow matching the test script's
interactive approach.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: Add automated testing script and guide for PR #934
Added comprehensive testing tools for AgentVibes party mode integration:
- test-bmad-pr.sh: Fully automated installation and verification script
- Interactive mode selection (official PR or custom fork)
- Automatic BMAD CLI setup and linking
- AgentVibes installation with guided prompts
- Built-in verification checks for voice maps and hooks
- Saved configuration for quick re-testing
- TESTING.md: Complete testing documentation
- Quick start with one-line npx command
- Manual installation alternative
- Troubleshooting guide
- Cleanup instructions
Testers can now run a single command to test the full AgentVibes integration
without needing to understand the complex setup process.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Add shell: true to npx execSync to prevent permission denied error
The execSync call for 'npx agentvibes@latest install' was failing with
'Permission denied' because the shell was trying to execute 'agentvibes@latest'
directly instead of passing it as an argument to npx.
Adding shell: true ensures the command runs in a proper shell context
where npx can correctly interpret the @latest version syntax.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Remove duplicate AgentVibes installation step from test script
The test script was calling AgentVibes installer twice:
1. BMAD installer now automatically runs AgentVibes (new feature)
2. Test script had a separate Step 6 that also ran AgentVibes
This caused the installer to run twice, with the second call failing
because it was already installed.
Changes:
- Removed redundant Step 6 (AgentVibes installation)
- Updated Step 5 to indicate it includes AgentVibes
- Updated step numbers from 7 to 6 throughout
- Added guidance that AgentVibes runs automatically
Now the flow is cleaner: BMAD installer handles everything!
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Address bmadcode review - preserve variables and move TTS logic to injection
Fixes requested changes from PR review:
1. Preserve {bmad_folder} variable placeholder
- Changed: {project_root}/.bmad/core/tasks/workflow.xml
- To: {project_root}/{bmad_folder}/core/tasks/workflow.xml
- Allows users to choose custom BMAD folder names during installation
2. Move TTS-specific hook guidance to injection system
- Removed hardcoded hook enforcement from source files
- Added hook guidance to processTTSInjectionPoints() in installer.js
- Now only appears when AgentVibes is installed (via TTS_INJECTION)
3. Maintain TTS-agnostic source architecture
- Source files remain clean of TTS-specific instructions
- TTS details injected at install-time only when needed
- Preserves provider-agnostic design principle
Changes made:
- src/core/workflows/party-mode/instructions.md
- Reverted .bmad to {bmad_folder} variable
- Replaced hardcoded hook guidance with <!-- TTS_INJECTION:party-mode -->
- Removed <note> about play-tts.sh hook location
- tools/cli/installers/lib/core/installer.js
- Added hook enforcement to party-mode injection replacement
- Guidance now injected only when enableAgentVibes is true
Addresses review comments from bmadcode:
- "needs to remain the variable. it will get set in the file at the install destination."
- "items like this we will need to inject if user is using claude and TTS"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Change 'claude-code' to 'claude' in test script instructions
The correct command to start Claude is 'claude', not 'claude-code'.
Updated line 362-363 in test-bmad-pr.sh to show the correct command.
* fix: Remove npm link from test script to avoid global namespace pollution
- Removed 'npm link' command that was installing BMAD globally
- Changed 'bmad install' to direct node execution using local clone
- Updated success message to reflect no global installation
This keeps testing fully isolated and prevents conflicts with:
- Existing BMAD installations
- Future official BMAD installs
- Orphaned symlinks when test directory is deleted
The test script now runs completely self-contained without modifying
the user's global npm environment.
---------
Co-authored-by: Claude Code <claude@anthropic.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Paul Preibisch <paul@paulpreibisch.com>
Co-authored-by: Brian <bmadcode@gmail.com>
BMad Method & BMad Core
AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
Build More, Architect Dreams (BMAD) with 19 specialized AI agents and 50+ guided workflows that adapt to your project's complexity—from quick bug fixes to enterprise platforms.
🚀 v6 is a MASSIVE upgrade from v4! Complete architectural overhaul, scale-adaptive intelligence, visual workflows, and the powerful BMad Core framework. v4 users: this changes everything. See what's new →
📌 v6 Alpha Status: Near-beta quality with vastly improved stability. Documentation is being finalized. New videos coming soon to BMadCode YouTube.
🎯 Why BMad Method?
Unlike generic AI coding assistants, BMad Method provides structured, battle-tested workflows powered by specialized agents who understand agile development. Each agent has deep domain expertise—from product management to architecture to testing—working together seamlessly.
✨ Key Benefits:
- Scale-Adaptive Intelligence - Automatically adjusts planning depth from bug fixes to enterprise systems
- Complete Development Lifecycle - Analysis → Planning → Architecture → Implementation
- Specialized Expertise - 19 agents with specific roles (PM, Architect, Developer, UX Designer, etc.)
- Proven Methodologies - Built on agile best practices with AI amplification
- IDE Integration - Works with Claude Code, Cursor, Windsurf, VS Code
🏗️ The Power of BMad Core
BMad Method is actually a sophisticated module built on top of BMad Core (Collaboration Optimized Reflection Engine). This revolutionary architecture means:
- BMad Core provides the universal framework for human-AI collaboration
- BMad Method leverages Core to deliver agile development workflows
- BMad Builder lets YOU create custom modules as powerful as BMad Method itself
With BMad Builder, you can architect both simple agents and vastly complex domain-specific modules (legal, medical, finance, education, creative) that will soon be sharable in an official community marketplace. Imagine building and sharing your own specialized AI team!
📊 See It In Action
Complete BMad Method workflow showing all phases, agents, and decision points
🚀 Get Started in 3 Steps
1. Install BMad Method
# Install v6 Alpha (recommended)
npx bmad-method@alpha install
# Or stable v4 for production
npx bmad-method install
2. Initialize Your Project
Load any agent in your IDE and run:
*workflow-init
This analyzes your project and recommends the right workflow track.
3. Choose Your Track
BMad Method adapts to your needs with three intelligent tracks:
| Track | Use For | Planning | Time to Start |
|---|---|---|---|
| ⚡ Quick Flow | Bug fixes, small features | Tech spec only | < 5 minutes |
| 📋 BMad Method | Products, platforms | PRD + Architecture + UX | < 15 minutes |
| 🏢 Enterprise | Compliance, scale | Full governance suite | < 30 minutes |
Not sure? Run
*workflow-initand let BMad analyze your project goal.
🔄 How It Works: 4-Phase Methodology
BMad Method guides you through a proven development lifecycle:
- 📊 Analysis (Optional) - Brainstorm, research, and explore solutions
- 📝 Planning - Create PRDs, tech specs, or game design documents
- 🏗️ Solutioning - Design architecture, UX, and technical approach
- ⚡ Implementation - Story-driven development with continuous validation
Each phase has specialized workflows and agents working together to deliver exceptional results.
🤖 Meet Your Team
12 Specialized Agents working in concert:
| Development | Architecture | Product | Leadership |
|---|---|---|---|
| Developer | Architect | PM | Scrum Master |
| UX Designer | Test Architect | Analyst | BMad Master |
| Tech Writer | Game Architect | Game Designer | Game Developer |
Test Architect integrates with @seontechnologies/playwright-utils for production-ready fixture-based utilities.
Each agent brings deep expertise and can be customized to match your team's style.
📦 What's Included
Core Modules
-
BMad Method (BMM) - Complete agile development framework
- 12 specialized agents
- 34 workflows across 4 phases
- Scale-adaptive planning
- → Documentation Hub
-
BMad Builder (BMB) - Create custom agents and workflows
- Build anything from simple agents to complex modules
- Create domain-specific solutions (legal, medical, finance, education)
- Share your creations in the upcoming community marketplace
- → Builder Guide
-
Creative Intelligence Suite (CIS) - Innovation & problem-solving
- Brainstorming, design thinking, storytelling
- 5 creative facilitation workflows
- → Creative Workflows
Key Features
- 🎨 Customizable Agents - Modify personalities, expertise, and communication styles
- 🌐 Multi-Language Support - Separate settings for communication and code output
- 📄 Document Sharding - 90% token savings for large projects
- 🔄 Update-Safe - Your customizations persist through updates
- 🚀 Web Bundles - Use in ChatGPT, Claude Projects, or Gemini Gems
📚 Documentation
Quick Links
- Quick Start Guide - 15-minute introduction
- Complete BMM Documentation - All guides and references
- Agent Customization - Personalize your agents
- All Documentation - Complete documentation index
For v4 Users
💬 Community & Support
- Discord Community - Get help, share projects
- GitHub Issues - Report bugs, request features
- YouTube Channel - Video tutorials and demos
- Web Bundles - Pre-built agent bundles
🛠️ Development
For contributors working on the BMad codebase:
# Run all quality checks
npm test
# Development commands
npm run lint:fix # Fix code style
npm run format:fix # Auto-format code
npm run bundle # Build web bundles
See CONTRIBUTING.md for full development guidelines.
What's New in v6
v6 represents a complete architectural revolution from v4:
🚀 Major Upgrades
- BMad Core Framework - Modular architecture enabling custom domain solutions
- Scale-Adaptive Intelligence - Automatic adjustment from bug fixes to enterprise
- Visual Workflows - Beautiful SVG diagrams showing complete methodology
- BMad Builder Module - Create and share your own AI agent teams
- 50+ Workflows - Up from 20 in v4, covering every development scenario
- 19 Specialized Agents - Enhanced with customizable personalities and expertise
- Update-Safe Customization - Your configs persist through all updates
- Web Bundles - Use agents in ChatGPT, Claude, and Gemini
- Multi-Language Support - Separate settings for communication and code
- Document Sharding - 90% token savings for large projects
🔄 For v4 Users
- Comprehensive Upgrade Guide - Step-by-step migration
- v4 Documentation Archive - Legacy reference
- Backwards compatibility where possible
- Smooth migration path with installer detection
📄 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