agentvibes 2.13.7 → 2.13.9

package/.claude/commands/agent-vibes/bmad.md

@@ -161,20 +161,22 @@ The TTS injection works with **any configured TTS provider**:
 
 The system automatically detects your configured provider via `/agent-vibes:provider info` and uses the appropriate TTS engine. You can switch providers anytime with `/agent-vibes:provider switch` and the BMAD agents will continue speaking using the new provider.
 
-## Available BMAD Agents
-
-| Agent ID | Role | Default Voice |
-|----------|------|---------------|
-| pm | Product Manager | Matthew Schmitz |
-| dev | Developer | Jessica Anne Bogart |
-| qa | QA Engineer | Ralf Eisend |
-| architect | Architect | Michael |
-| po | Product Owner | Amy |
-| analyst | Analyst | Lutz Laugh |
-| sm | Scrum Master | Ms. Walker |
-| ux-expert | UX Expert | Aria |
-| bmad-master | BMAD Master | Aria |
-| bmad-orchestrator | Orchestrator | Ms. Walker |
+## Available BMAD Agents (Provider-Aware)
+
+The voice used depends on your active TTS provider. Run `/agent-vibes:provider info` to check your provider.
+
+| Agent ID | Role | ElevenLabs Voice | Piper Voice |
+|----------|------|------------------|-------------|
+| pm | Product Manager | Matthew Schmitz | en_US-ryan-high |
+| dev | Developer | Aria | en_US-amy-medium |
+| analyst | Business Analyst | Jessica Anne Bogart | en_US-kristin-medium |
+| architect | Architect | Michael | en_GB-alan-medium |
+| sm | Scrum Master | Matthew Schmitz | en_US-joe-medium |
+| tea | Test Architect | Michael | en_US-arctic-medium |
+| tech-writer | Technical Writer | Aria | en_US-lessac-medium |
+| ux-designer | UX Designer | Jessica Anne Bogart | en_US-lessac-medium |
+| frame-expert | Visual Designer | Matthew Schmitz | en_GB-alan-medium |
+| bmad-master | BMAD Master | Michael | en_US-danny-low |
 
 ## Implementation Details
 

package/.claude/hooks/play-tts-elevenlabs.sh

@@ -198,8 +198,10 @@ TEMP_FILE="$AUDIO_DIR/tts-$(date +%s).mp3"
 # @sideeffects Creates MP3 file in audio directory
 # @edgecases Handles network failures, API errors, rate limiting
 # Choose model based on language
+# Note: eleven_monolingual_v1 deprecated for free tier as of Nov 2025
+# Using eleven_turbo_v2_5 for English (fast, high quality, free tier compatible)
 if [[ "$LANGUAGE_CODE" == "en" ]]; then
-  MODEL_ID="eleven_monolingual_v1"
+  MODEL_ID="eleven_turbo_v2_5"
 else
   MODEL_ID="eleven_multilingual_v2"
 fi

package/.claude/hooks/provider-manager.sh

@@ -141,31 +141,120 @@ set_active_provider() {
     voice_file="$HOME/.claude/tts-voice.txt"
   fi
 
-  # Set default voice for the new provider
-  local default_voice
-  case "$provider" in
-    piper)
-      # Default Piper voice
-      default_voice="en_US-lessac-medium"
-      ;;
-    elevenlabs)
-      # Default ElevenLabs voice (first in alphabetical order from voices-config.sh)
-      default_voice="Amy"
-      ;;
-    *)
-      # Unknown provider - remove voice file
-      if [[ -f "$voice_file" ]]; then
-        rm -f "$voice_file"
-      fi
-      echo "✓ Active provider set to: $provider (voice reset)"
-      return 0
-      ;;
-  esac
+  # Migrate voice to equivalent in new provider
+  local current_voice=""
+  if [[ -f "$voice_file" ]]; then
+    # Strip only leading/trailing whitespace and newlines, preserve internal spaces
+    current_voice=$(cat "$voice_file" | tr -d '\n\r' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+  fi
+
+  local new_voice
+  new_voice=$(migrate_voice_to_provider "$current_voice" "$provider")
+
+  # Write new voice to file
+  echo "$new_voice" > "$voice_file"
 
-  # Write default voice to file
-  echo "$default_voice" > "$voice_file"
+  if [[ -n "$current_voice" ]] && [[ "$current_voice" != "$new_voice" ]]; then
+    echo "✓ Active provider set to: $provider"
+    echo "🔄 Voice migrated: $current_voice → $new_voice"
+  else
+    echo "✓ Active provider set to: $provider (voice: $new_voice)"
+  fi
+}
+
+# @function migrate_voice_to_provider
+# @intent Migrate a voice from one provider to an equivalent in the target provider
+# @why Users shouldn't have to manually reconfigure voices when switching providers
+# @param $1 {string} current_voice - Current voice name (may be from any provider)
+# @param $2 {string} target_provider - Target provider to migrate to
+# @returns Echoes equivalent voice name for target provider
+# @exitcode 0=always succeeds (returns default if no mapping found)
+# @sideeffects None
+# @edgecases Returns provider default if voice not found in mapping table
+migrate_voice_to_provider() {
+  local current_voice="$1"
+  local target_provider="$2"
+
+  # Voice mapping table: ElevenLabs <-> Piper equivalents
+  # Format: "elevenlabs_voice:piper_voice"
+  local voice_mappings=(
+    "Amy:en_US-amy-medium"
+    "Aria:en_US-amy-medium"
+    "Matthew Schmitz:en_US-ryan-high"
+    "Michael:en_GB-alan-medium"
+    "Jessica Anne Bogart:en_US-kristin-medium"
+    "Ms. Walker:en_US-lessac-medium"
+    "Cowboy Bob:en_US-joe-medium"
+    "Ralf Eisend:en_US-arctic-medium"
+    "Northern Terry:en_GB-alan-medium"
+    "Lutz Laugh:en_US-joe-medium"
+    "Dr. Von Fusion:en_US-danny-low"
+    "Demon Monster:en_US-danny-low"
+    "Drill Sergeant:en_US-ryan-high"
+    "Grandpa Spuds Oxley:en_US-joe-medium"
+  )
+
+  # Default voices by provider
+  local elevenlabs_default="Amy"
+  local piper_default="en_US-lessac-medium"
+
+  # If no current voice, return default for target provider
+  if [[ -z "$current_voice" ]]; then
+    case "$target_provider" in
+      piper) echo "$piper_default" ;;
+      elevenlabs) echo "$elevenlabs_default" ;;
+      *) echo "$piper_default" ;;
+    esac
+    return 0
+  fi
 
-  echo "✓ Active provider set to: $provider (voice set to: $default_voice)"
+  # Convert to lowercase for case-insensitive comparison (portable)
+  local current_voice_lower
+  current_voice_lower=$(echo "$current_voice" | tr '[:upper:]' '[:lower:]')
+
+  # Search for mapping
+  for mapping in "${voice_mappings[@]}"; do
+    local el_voice="${mapping%%:*}"
+    local piper_voice="${mapping#*:}"
+    local el_voice_lower
+    local piper_voice_lower
+    el_voice_lower=$(echo "$el_voice" | tr '[:upper:]' '[:lower:]')
+    piper_voice_lower=$(echo "$piper_voice" | tr '[:upper:]' '[:lower:]')
+
+    case "$target_provider" in
+      piper)
+        # Switching to Piper: look for ElevenLabs voice match
+        if [[ "$current_voice_lower" == "$el_voice_lower" ]]; then
+          echo "$piper_voice"
+          return 0
+        fi
+        # Already a Piper voice? Keep it if valid format
+        if [[ "$current_voice" =~ ^en_ ]]; then
+          echo "$current_voice"
+          return 0
+        fi
+        ;;
+      elevenlabs)
+        # Switching to ElevenLabs: look for Piper voice match
+        if [[ "$current_voice_lower" == "$piper_voice_lower" ]]; then
+          echo "$el_voice"
+          return 0
+        fi
+        # Already an ElevenLabs voice? Keep it
+        if [[ ! "$current_voice" =~ ^en_ ]]; then
+          echo "$current_voice"
+          return 0
+        fi
+        ;;
+    esac
+  done
+
+  # No mapping found - return default for target provider
+  case "$target_provider" in
+    piper) echo "$piper_default" ;;
+    elevenlabs) echo "$elevenlabs_default" ;;
+    *) echo "$piper_default" ;;
+  esac
 }
 
 # @function list_providers

package/.claude/personalities/rapper.md

@@ -1,7 +1,7 @@
 ---
 name: rapper
 description: Spits fire with rhymes and wordplay
-elevenlabs_voice: Drew
+elevenlabs_voice: Antoni
 piper_voice: en_US-ryan-high
 ---
 

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v2.13.3
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v2.13.9
 
 ---
 
@@ -94,17 +94,16 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, or using Warp
 
 ## 📰 Latest Release
 
-**[v2.12.6 - Security & Reliability Improvements](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.13.3)** 🎉
+**[v2.13.7 - Voice Intros & PR Workflow](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.13.9)** 🎉
 
-AgentVibes v2.12.6 brings quality improvements based on SonarCloud analysis and enhances BMAD party mode. This release improves API key privacy in terminal output, adds better cleanup for long-running sessions, includes more robust error handling, and ensures BMAD agents each get their unique voice. All improvements maintain 100% backward compatibility.
+AgentVibes v2.13.7 adds voice map with intro messages for BMAD party mode and improves voice assignments for better persona fit.
 
 **Key Highlights:**
-- 🔒 **API Key Privacy** - Masked display prevents credential leaks in terminal history
-- 🛡️ **Resource Cleanup** - Better subprocess management for long-running stability
-- ⚡ **Error Handling** - Graceful degradation instead of crashes on file operations
-- 🎭 **BMAD Voice Detection** - Party mode supports multiple directory paths
+- 🎤 **Voice Map with Intros** - Default BMAD voice assignments now include intro messages for party mode
+- 🔄 **Voice Swap** - bmad-master and pm (John) voices swapped for better persona fit
+- 📋 **PR Workflow Rules** - Added CLAUDE.md guidelines for safer PR workflows
 - ✅ **110/110 Tests Passing** - All functionality verified and working
-- 🔄 **Zero Breaking Changes** - Fully backward compatible with v2.12.5
+- 🔄 **Zero Breaking Changes** - Fully backward compatible with v2.13.6
 
 💡 **Tip:** If `npx agentvibes` shows an older version or missing commands, clear your npm cache: `npm cache clean --force && npx agentvibes@latest --help`
 

package/RELEASE_NOTES.md

@@ -1,3 +1,148 @@
+# Release v2.13.9 - Provider-Aware Voice Migration
+
+**Release Date:** 2025-11-27
+**Type:** Patch Release (Bug Fix & Enhancement)
+
+## 🔧 AI Summary
+
+AgentVibes v2.13.9 fixes a critical issue where BMAD voice mappings were not provider-aware, causing "Voice model not found" errors when switching between ElevenLabs and Piper TTS providers. The release introduces intelligent voice migration that automatically maps voices when switching providers (e.g., "Amy" → "en_US-amy-medium"), ensuring seamless provider switching without manual reconfiguration.
+
+**Key Highlights:**
+- 🔄 **Smart Voice Migration** - Automatic voice mapping when switching TTS providers
+- 📝 **Provider-Aware Docs** - BMAD documentation now shows both ElevenLabs and Piper columns
+- 🎤 **Valid Piper Names** - Fixed incomplete Piper voice names (kristin → en_US-kristin-medium)
+- 🛡️ **Preserve Voice Names** - Internal spaces in voice names no longer stripped
+- ✅ **122 Tests Passing** - All functionality verified (110 bats + 12 node tests)
+
+---
+
+## 🔧 Bug Fixes
+
+### Provider-Aware Voice Mappings (Issue #49)
+**Files:** `.claude/commands/agent-vibes/bmad.md`, `.agentvibes/bmad/bmad-voices.md`
+
+**Problem:**
+When users switched from ElevenLabs to Piper TTS provider, the voice file retained ElevenLabs voice names (like "Amy") which don't exist in Piper. This caused errors:
+```
+📥 Voice model not found: Amy
+❌ Voice download cancelled
+```
+
+**Solution:**
+1. Updated `bmad.md` documentation to show both ElevenLabs and Piper columns
+2. Fixed invalid Piper voice names in configuration files
+3. Added `migrate_voice_to_provider()` function for automatic voice mapping
+
+**Impact:**
+- Seamless provider switching without manual voice reconfiguration
+- BMAD agents work correctly regardless of TTS provider
+
+### Invalid Piper Voice Names
+**Files:** `.agentvibes/bmad/bmad-voices.md`
+
+**Fixed:**
+- `kristin` → `en_US-kristin-medium`
+- `jenny` → `en_US-lessac-medium`
+
+All Piper voice names now follow the correct format: `lang_REGION-name-quality`
+
+### Voice Name Space Preservation
+**File:** `.claude/hooks/provider-manager.sh`
+
+**Problem:**
+Voice names with spaces (like "Jessica Anne Bogart") were being corrupted to "JessicaAnneBogart" due to overly aggressive whitespace stripping.
+
+**Solution:**
+Changed from `tr -d '[:space:]'` to strip only leading/trailing whitespace while preserving internal spaces.
+
+---
+
+## ✨ New Features
+
+### Automatic Voice Migration
+**File:** `.claude/hooks/provider-manager.sh` (new function: `migrate_voice_to_provider`)
+
+When switching TTS providers, voices are automatically mapped to equivalents:
+
+| ElevenLabs | Piper |
+|------------|-------|
+| Amy | en_US-amy-medium |
+| Aria | en_US-amy-medium |
+| Matthew Schmitz | en_US-ryan-high |
+| Michael | en_GB-alan-medium |
+| Jessica Anne Bogart | en_US-kristin-medium |
+| Ms. Walker | en_US-lessac-medium |
+| Cowboy Bob | en_US-joe-medium |
+| Ralf Eisend | en_US-arctic-medium |
+| Northern Terry | en_GB-alan-medium |
+| Lutz Laugh | en_US-joe-medium |
+| Dr. Von Fusion | en_US-danny-low |
+| Demon Monster | en_US-danny-low |
+| Drill Sergeant | en_US-ryan-high |
+| Grandpa Spuds Oxley | en_US-joe-medium |
+
+**Usage:**
+```bash
+# Switch to Piper - voice automatically migrated
+/agent-vibes:provider switch piper
+# Output: ✓ Active provider set to: piper
+#         🔄 Voice migrated: Amy → en_US-amy-medium
+```
+
+### Provider-Aware Documentation
+**File:** `.claude/commands/agent-vibes/bmad.md`
+
+The "Available BMAD Agents" table now shows voices for both providers:
+
+| Agent ID | Role | ElevenLabs Voice | Piper Voice |
+|----------|------|------------------|-------------|
+| pm | Product Manager | Matthew Schmitz | en_US-ryan-high |
+| dev | Developer | Aria | en_US-amy-medium |
+| analyst | Business Analyst | Jessica Anne Bogart | en_US-kristin-medium |
+| architect | Architect | Michael | en_GB-alan-medium |
+| sm | Scrum Master | Matthew Schmitz | en_US-joe-medium |
+| tea | Test Architect | Michael | en_US-arctic-medium |
+| tech-writer | Technical Writer | Aria | en_US-lessac-medium |
+| ux-designer | UX Designer | Jessica Anne Bogart | en_US-lessac-medium |
+| frame-expert | Visual Designer | Matthew Schmitz | en_GB-alan-medium |
+| bmad-master | BMAD Master | Michael | en_US-danny-low |
+
+---
+
+## 📊 Changes Summary
+
+**Files Modified:** 4
+- `.claude/commands/agent-vibes/bmad.md` - Provider-aware documentation table
+- `.claude/hooks/provider-manager.sh` - Voice migration feature (+95 lines)
+- `.agentvibes/bmad/bmad-voices.md` - Fixed Piper voice names
+- `test/unit/provider-manager.bats` - Updated tests for new behavior
+
+**Lines Changed:** 143 additions, 48 deletions
+
+**Test Results:** 122/122 passing ✅ (110 bats + 12 node)
+
+---
+
+## 🎯 Migration Notes
+
+**No migration required** - This is a patch release with bug fixes and enhancements.
+
+**Compatibility:** 100% backward compatible with v2.13.8
+
+**Recommended Action:** Update to fix voice mapping issues
+```bash
+npx agentvibes@latest update
+```
+
+---
+
+## 🔗 References
+
+- GitHub Issue #49: https://github.com/paulpreibisch/AgentVibes/issues/49
+- BMAD voice mappings not provider-aware in documentation
+
+---
+
 # Release v2.13.4 - BMAD Integration Fix
 
 **Release Date:** 2025-01-27
@@ -329,258 +474,3 @@ npx agentvibes@latest update
 - GitHub Issue #45: https://github.com/paulpreibisch/AgentVibes/issues/45
 - GitHub Issue #46: https://github.com/paulpreibisch/AgentVibes/issues/46
 - SonarCloud Quality Gates: Code quality and security analysis
-
----
-
-# Release v2.12.5 - Code Quality Improvements
-
-**Release Date:** 2025-01-23
-**Type:** Patch Release (Quality & Security)
-
-## 🔒 AI Summary
-
-AgentVibes v2.12.5 improves code quality by upgrading Sonar quality gates and implementing best practices identified through static analysis. This release includes enhanced input validation, improved shell command handling, better file locking for atomic operations, and secure temporary directory management while maintaining 100% backward compatibility. All 110 existing tests pass with no breaking changes.
-
-**Key Highlights:**
-- ✅ **Sonar Quality Gates Upgraded** - Enhanced code quality standards across the codebase
-- 🔒 **18 Code Improvements** - Better input validation, command handling, and file operations
-- 🧪 **110/110 Tests Passing** - All functionality verified and working
-- 🔄 **Zero Breaking Changes** - Fully backward compatible with existing installations
-- 📊 **162 Lines Enhanced** - Code quality improvements across 8 files
-
----
-
-## 🔧 Code Quality Improvements
-
-### Enhanced Input Validation
-**Files:** `src/installer.js`, `.claude/hooks/play-tts.sh`, `mcp-server/install-deps.js`
-
-- Added comprehensive input validation across all user-facing interfaces
-- Shell metacharacter detection and validation
-- Numeric validation for configuration values
-- Empty/null checks for required parameters
-- **Impact:** More robust error handling and better user experience
-
-### Improved Shell Command Handling
-**Files:** `src/installer.js:200`, `scripts/fix-audio-tunnel.sh`, `src/commands/bmad-voices.js:221`
-
-- Enhanced shell script execution with proper argument escaping
-- Added `escapeShellArg()` helper function for safe parameter passing
-- Proper quoting of all shell variables in SSH commands
-- Python command validation against allowlist
-- **Impact:** Safer script execution and better command reliability
-
-### Better File System Operations
-**Files:** `src/installer.js` (multiple locations)
-
-- Added `isPathSafe()` validation function for file operations
-- Canonical path resolution to prevent unexpected behavior
-- More restrictive file permissions (750 instead of 755)
-- User-specific temporary directories with proper permissions (700)
-- **Impact:** More predictable file operations and better isolation
-
-### Atomic PID File Operations
-**File:** `.claude/hooks/tts-queue.sh:47-57`
-
-- Implemented flock-based file locking for PID management
-- Atomic PID file operations prevent race conditions
-- Added timeout protection (5 seconds) for lock acquisition
-- **Impact:** Prevents duplicate TTS queue workers in edge cases
-
-### Code Cleanup
-**File:** `src/installer.js:1398-1450`
-
-- Removed debug console.error statements
-- Cleaner production output
-- **Impact:** Better user experience with less verbose output
-
----
-
-## 📊 Changes Summary
-
-**Files Modified:** 8
-- `src/installer.js` - Input validation, command handling, path operations, code cleanup
-- `src/commands/bmad-voices.js` - Enhanced shell argument escaping
-- `mcp-server/install-deps.js` - Python command validation
-- `scripts/fix-audio-tunnel.sh` - SSH command quoting improvements
-- `.claude/hooks/tts-queue.sh` - Secure temp directory, file locking
-- `.claude/hooks/play-tts.sh` - Input validation
-- `test/unit/play-tts.bats` - Updated test expectations
-- `AgentVibes.code-workspace` - Minor workspace config
-
-**Lines Changed:** 162 additions, 35 deletions
-
-**Test Results:** 110/110 passing ✅
-
----
-
-## 💡 Technical Improvements
-
-### Best Practices Implemented
-
-**Input Handling**
-- Comprehensive validation before processing
-- Metacharacter detection for shell inputs
-- Type validation (numeric, string, etc.)
-- Empty/null safety checks
-
-**Command Execution**
-- Proper argument escaping for shell commands
-- Allowlist-based command validation
-- Quote all variables in shell scripts
-- Avoid raw string interpolation
-
-**File Operations**
-- Path validation and canonical resolution
-- Appropriate permissions for different file types
-- User-specific temporary directories
-- Atomic operations where needed
-
-**Concurrency**
-- File locking for shared resources
-- Atomic PID file operations
-- Timeout protection on locks
-
-**Code Quality**
-- Removed debug output from production code
-- Clear, informative error messages
-- Consistent code patterns
-
----
-
-## ✅ Testing
-
-### Test Suite Results
-- **110 tests total**
-- **110 passing** ✅
-- **0 failing**
-- All functionality verified working
-
-### Test Coverage
-- Personality Manager: 14 tests
-- Play TTS: 6 tests (including validation)
-- Provider Manager: 43 tests
-- Speed Manager: 37 tests
-- Voice Manager: 11 tests
-
----
-
-## 🎯 Migration Notes
-
-**No migration required** - This is a patch release with code quality improvements.
-
-**Compatibility:** 100% backward compatible with v2.12.4
-
-**Recommended Action:** Update to get the latest improvements
-```bash
-npx agentvibes@latest update
-```
-
----
-
-## 🔗 References
-
-- GitHub Issue #44: https://github.com/paulpreibisch/AgentVibes/issues/44
-- Sonar Quality Gates: Code quality and best practices analysis
-
----
-
-# Release v2.12.0 - .agentvibes/ Directory Migration
-
-**Release Date:** 2025-11-20
-**Type:** Minor Release (Breaking Change - Automatic Migration)
-
-## 🎯 AI Summary
-
-AgentVibes v2.12.0 introduces a comprehensive directory reorganization, migrating all AgentVibes-specific configuration from `.claude/config/` and `.claude/plugins/` to a dedicated `.agentvibes/` directory. This eliminates namespace confusion with Claude Code's official directories and provides a clear, predictable location for all AgentVibes state. The migration is fully automatic during upgrade—users simply run `npx agentvibes@latest update` and their configuration is seamlessly moved. This release also includes extensive BMAD testing improvements with the new `npx test-bmad-pr` command and comprehensive Piper voice installation enhancements.
-
-**Key Highlights:**
-- 📁 **Dedicated .agentvibes/ Directory** - Clear namespace separation from Claude Code
-- 🔄 **Automatic Migration** - Seamless upgrade from .claude/config/ and .claude/plugins/
-- ✅ **100% Backward Compatible** - No manual intervention required
-- 🧪 **32 Passing Tests** - Comprehensive test suite validates all migration scenarios
-- 🎭 **BMAD Testing Made Easy** - New `npx test-bmad-pr` command for one-line testing
-- 🎤 **Improved Voice Installation** - Better Piper voice detection and status display
-
----
-
-## 🚀 Major Features
-
-### Dedicated .agentvibes/ Directory Structure
-
-**Complete namespace reorganization** (commits: ab293d05, 04f2f97d, 99134216)
-
-The `.agentvibes/` directory replaces scattered configuration across `.claude/config/` and `.claude/plugins/`:
-
-```
-.agentvibes/
-├── bmad/                    # BMAD integration
-│   ├── bmad-voices.md       # Agent-to-voice mappings
-│   ├── bmad-voices-enabled.flag
-│   ├── bmad-party-mode-disabled.flag
-│   └── .bmad-previous-settings
-└── config/                  # AgentVibes configuration
-    ├── agentvibes.json      # Pretext configuration
-    ├── personality-voice-defaults.json
-    └── README-personality-defaults.md
-```
-
-**Migration Paths:**
-- `.claude/config/agentvibes.json` → `.agentvibes/config/agentvibes.json`
-- `.claude/plugins/bmad-voices-enabled.flag` → `.agentvibes/bmad/bmad-voices-enabled.flag`
-- `.claude/config/bmad-voices.md` → `.agentvibes/bmad/bmad-voices.md`
-
-**Benefits:**
-- ✅ Clear ownership - `.agentvibes/` is obviously AgentVibes-managed
-- ✅ No collision risk - Claude Code may add official plugins in the future
-- ✅ Easier troubleshooting - All state in one predictable location
-- ✅ Better organization - Separate BMAD integration from core config
-
-### Automatic Migration System
-
-**Seamless upgrade experience** (commit: ab293d05)
-
-- **Detection:** Installer automatically detects old configuration on startup
-- **Execution:** Runs `.claude/hooks/migrate-to-agentvibes.sh` automatically
-- **Preservation:** All settings, voice mappings, and flags preserved
-- **Cleanup:** Removes empty `.claude/plugins/` directory after migration
-- **Graceful Fallback:** Manual migration option if auto-migration fails
-
-**Migration Script Features:**
-- Color-coded progress output
-- File-by-file migration reporting
-- Duplicate detection and handling
-- Preserves `.claude/config/` for runtime state files (like `tts-speech-rate.txt`)
-
-### Comprehensive Test Suite
-
-**32 passing tests across 6 scenarios** (commit: ab293d05)
-
-Created `test-migration.sh` with full coverage:
-
-1. **Fresh Install** (6 assertions)
-   - Verifies `.agentvibes/` created directly
-   - Ensures old directories NOT created
-
-2. **Upgrade from v2.9.x** (9 assertions)
-   - Auto-migration of all config files
-   - Cleanup of old locations
-   - Value preservation
-
-3. **Manual Migration** (4 assertions)
-   - Script execution
-   - File movement
-   - Old location cleanup
-
-4. **BMAD Integration** (5 assertions)
-   - Voice mappings in new location
-   - Hook scripts read from new paths
-   - Party mode functionality
-
-5. **Pretext Configuration** (3 assertions)
-   - Config in new location
-   - Scripts reference new paths
-
-6. **No Old Config** (4 assertions)
-   - No errors when nothing to migrate
-   - Idempotent behavior