Major restructure for better organization and navigation:
New Structure:
- module-02-overview.md (minimal, just links to lessons)
- lesson-01-github-account/tutorial.md
- lesson-02-create-repository/tutorial.md
- lesson-03-install-ide/tutorial.md
- lesson-04-git-setup/tutorial.md
- lesson-05-clone-and-wds/tutorial.md
- lesson-06-initiate-mimir/tutorial.md
Each Lesson Contains:
- Focused tutorial on one specific task
- Clear time estimate
- Step-by-step instructions
- Troubleshooting section
- Navigation to next lesson
Overview Benefits:
- Minimal and scannable
- Easy to navigate between lessons
- See progress through module
- Jump to specific lesson easily
Lesson Benefits:
- Self-contained tutorials
- Focused on single topic
- Can be referenced individually
- Progressive complexity
- Clear completion criteria
Old tutorial-02.md kept for reference until verified working.
Critical UX improvement: Decision happens at the RIGHT moment.
Changes to Step 2.2 (Repository Settings):
- ADDED: Comprehensive 'Single vs Separate Repo' decision framework
- Decision now happens DURING naming (not after)
- Clear naming convention: 'my-project' vs 'my-project-specs'
Single Repository Use Cases:
✅ Close to development team
✅ Simple, direct communication needed
✅ Building the project yourself
✅ Working closely with other designers
✅ Small team with full ownership
✅ Rapid iteration and feedback
Separate Repository Use Cases:
✅ Corporate or enterprise environment
✅ Specifications serve multiple products/platforms
✅ Development team has many developers
✅ Extensive or complex codebase
✅ Clear handoff boundaries needed
✅ Design and dev have separate workflows
Changes to Step 2.3:
- Acknowledge decision was made
- Remind about implications
Changes to Step 4.1:
- SIMPLIFIED: Just recap the decision made in Step 2
- No longer presenting options (already decided!)
- Cleaner flow
Reasoning:
Repository NAME determines structure. The decision must happen when
naming the repository, not later. This is when GitHub asks 'what do
you want to call this?' - that's the natural decision point.
Benefits:
- Decision at natural moment (when naming)
- Clear naming conventions prevent confusion
- Users understand implications before creating
- No 'oops, I named it wrong' moments
- Professional guidance on when to use each approach
Reorganization for better logical flow:
Changes:
- MOVED: 'One Repo or Two?' decision from Step 2.4 to Step 4.1
- Placed BEFORE Git installation discussion
- Added note in Step 2 pointing forward to Step 4
Reasoning:
- Repository structure decision affects how you'll set up Git workflow
- Makes more sense alongside Git/GitHub Desktop discussion
- GitHub Desktop can help visualize the single vs separate decision
- Users make informed choice before cloning
- Better pedagogical flow: Create repo → Understand structure → Clone it
Benefits:
- Decision happens at the right moment (before cloning)
- Connected to tooling discussion (Git/GitHub Desktop)
- Eliminates duplicate content
- Clearer mental model for beginners
Major UX improvement for complete beginners:
Tutorial Changes (Step 4):
- REMOVED: Manual Git installation steps with command line
- ADDED: Explanation that IDE handles Git automatically
- ADDED: GitHub Desktop as visual alternative for non-technical users
- NEW APPROACH: Let Cursor prompt for Git installation when needed
Key improvements:
- Beginners don't need to manually install Git
- Cursor/VS Code will automatically prompt when cloning
- Optional GitHub Desktop path for visual learners
- Reduces friction and confusion for designers
- Eliminates 'why am I doing this?' questions
Overview Changes:
- Updated lesson descriptions to match tutorial flow
- Clarified Git is handled automatically
- Updated completion checklist
- Improved tutorial description
Reasoning:
Complete beginners don't need to understand Git installation.
Modern IDEs handle this transparently. Let the tools do the work.
Designers can focus on design, not developer tooling.
Complete rewrite of Installation & Setup module targeting designers with
zero technical experience:
Overview Changes:
- Expanded from 30min to 45-60min to accommodate beginners
- Added GitHub account creation as first step
- Added repository setup and naming guidance
- Added IDE installation (Cursor vs VS Code comparison)
- Reduced prerequisites to absolute minimum (just computer + internet)
- New lesson structure: GitHub → Repository → IDE → Clone → WDS → Mimir
Tutorial Changes (8 detailed steps):
1. Create GitHub Account - Username tips, verification
2. Create Project Repository - Naming, public/private, one vs two repos
3. Install IDE - Cursor vs VS Code, first launch setup
4. Install Git - Check, install, configure
5. Clone Repository - URL, location, terminal commands
6. Add WDS to Workspace - Inside vs beside decision
7. Create Docs Structure - 8-phase folders with platform-specific commands
8. Initiate with Mimir - Drag file, first interaction
New Features:
- Screenshot-worthy step-by-step instructions
- Platform-specific commands (Windows/Mac/Linux)
- Troubleshooting section for common beginner issues
- Visual file structure diagrams
- Pro tips for ongoing use
- Quick reference for 'what lives where'
- Encouragement and celebration at each checkpoint
Target: Designer who has never used GitHub, Git, or an IDE before.
- Add training course section to orchestrator with module overview
- Update presentation to suggest training for new users
- Expand Patient Trainer role to include course guidance
- Provide @wds-mimir training invocation example
Users can now be guided through comprehensive WDS training with:
@wds-mimir Take me through the WDS training
- Add mimir-presentation.md introducing the WDS guide/coach/trainer persona
- Create MIMIR-WDS-ORCHESTRATOR.md with complete orchestration logic
- Include initialization sequence: presentation → assessment → environment check → routing
- Add adaptive teaching based on skill levels (beginner to experienced)
- Integrate with existing project-analysis-router.md workflow
- Add @wds-mimir chat invocation instructions
- Fix workflow folder names in MANUAL-INIT-GUIDE.md
Mimir serves as the welcoming entry point, assessing user needs and routing to
specialist agents (Freyja, Idunn, Saga) when appropriate.
- Created DRAG-ME-TO-AI-CHAT-TO-GET-STARTED.md for AI agent context
- AI automatically checks if WDS repo exists
- AI offers to clone WDS if not found
- Zero manual setup required - just drag file to chat
- Supports both workspace and copied setups
AGENTS COMPLETE (3 files):
- Created saga-analyst.agent.yaml (Saga - WDS Analyst)
- Created idunn-pm.agent.yaml (Idunn - WDS PM)
- Created freyja-ux.agent.yaml (Freyja - WDS Designer)
- All agents include presentations, personas, and full menu integration
- Norse mythology theme unified across all agents
DOCUMENTATION UPDATES:
- Updated README with complete 8-phase structure
- Updated folder structure to show
- Added language configuration options for specification and product languages in the workflow setup.
- Updated workflow YAML files to include descriptive metadata for better clarity and organization.
- Enhanced the workflow initialization instructions to guide users in configuring language settings.
- Revised project brief and PRD platform workflows to reflect the latest structural changes and improve usability.
- Documented new features and improvements in the WDS conversion roadmap, emphasizing the completion of Phase 4 workflows.
- Updated the WDS conversion roadmap with the latest phase naming conventions and statuses.
- Introduced a new section detailing key methodology refinements, including scoring systems for feature prioritization and clarifications on the design system's optional and parallel nature.
- Enhanced the PRD platform phase to emphasize technical foundations and proofs of concept.
- Revised phase outputs and documentation structure for improved clarity and organization.
- Completed all phase guides with positive language and unified naming conventions for better integration with design tools.
- Updated the WDS conversion roadmap to include Positive Language Guidelines, emphasizing the use of constructive language in documentation.
- Removed outdated phase documents for Product Exploration, User Research, and Requirements, streamlining the method guide.
- Revised the UX Design phase to focus on UX-Sketches and Usage Scenarios, improving clarity on design processes.
- Finalized the PRD structure in the integration guide, ensuring comprehensive coverage of functional requirements and development priorities.
- Enhanced documentation for the Design System phase, detailing component extraction and integration with design tools.
- Renamed specialized design agents in README and related documents to include "the" in their titles for consistency and clarity.
- Updated references to agents in the WDS conversion roadmap and method guide to reflect the new naming convention.
- Enhanced documentation to improve readability and user understanding of agent roles within the WDS framework.
- Renamed the project from BMad Method to Whiteport Design Studio (WDS)
- Added new badges for WDS and updated project status
- Introduced WDS as a design-focused methodology module complementing BMad Method
- Detailed the folder structure and workflow phases for WDS
- Included information about specialized design agents and their roles
- Enhanced documentation for clarity and organization
This update aligns the README with the current project structure and goals, emphasizing the integration of design workflows into the BMad ecosystem.
## 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.
- Removed all references to Phase 0 (should be Documentation prerequisite)
- Updated phase transitions from 'Phase 3→4' to 'Phase 3 to Phase 4'
- Ensured all phases are numbered 1-4 consistently
- Documentation for brownfield projects is now correctly referred to as 'Documentation prerequisite' rather than Phase 0
- Updated workflows-implementation.md: removed validate workflows, epic-tech-context, story-context
- Updated workflows-analysis.md: removed brainstorm-game, game-brief, added domain-research
- Updated workflows-planning.md: removed gdd, narrative, moved create-epics-and-stories to Phase 3
- Updated workflows-solutioning.md: already correct with create-epics-and-stories in Phase 3
- Removed all Mermaid diagrams and replaced with text descriptions
- Updated quick reference tables to reflect actual workflows
- Fixed flow examples to match current implementation
Copilot was triggering warning or errors in the chatmode files due to some changes in tool names.
- findTestFiles is internal tool, cannot be used.
- Other tools have change names.
- Added new tools: todos and runSubAgents.
Co-authored-by: Brian <bmadcode@gmail.com>
Add explicit radix=10 to parseInt() calls and NaN validation to prevent
unexpected hex parsing and invalid config values.
Changes:
- Line 52: Add radix and NaN check in input validation
- Line 189-192: Add radix and NaN fallback for config parsing
Fixes potential issues:
- Hex input (0x10) now rejected instead of parsed as 16
- Invalid strings return default value instead of NaN→null
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
* 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>
Mårten Angner
Alex Verkhovsky
Brian Madison
Jorge Castillo
Serhii
fikri-kompanion
Paul Preibisch