agentvibes 2.10.0 → 2.12.0

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

@@ -47,7 +47,7 @@ Set a prefix word/phrase for all TTS messages
 - `/agent-vibes:set-pretext "Project Alpha"` - Custom phrase
 - `/agent-vibes:set-pretext ""` - Clear pretext
 
-Saved locally in `.claude/config/agentvibes.json`
+Saved locally in `.agentvibes/config/agentvibes.json`
 
 ## Getting Voice IDs
 

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

@@ -119,7 +119,7 @@ Quickly change voice for specific agent.
 - `personality` (optional): Personality to apply (default: normal)
 
 ### `edit`
-Opens `.claude/config/bmad-voices.md` for manual editing.
+Opens `.agentvibes/bmad/bmad-voices.md` for manual editing.
 
 **Example:**
 ```
@@ -132,8 +132,8 @@ Edit the markdown table directly to change voice mappings.
 ## How It Works
 
 ### Voice Assignment
-1. **Plugin File**: `.claude/config/bmad-voices.md` contains voice-to-agent mappings
-2. **Activation Flag**: `.claude/config/bmad-voices-enabled.flag` enables/disables the plugin
+1. **Plugin File**: `.agentvibes/bmad/bmad-voices.md` contains voice-to-agent mappings
+2. **Activation Flag**: `.agentvibes/bmad/bmad-voices-enabled.flag` enables/disables the plugin
 
 ### TTS Injection (Automatic)
 When you run `/agent-vibes:bmad enable`, the system automatically:

package/.claude/commands/agent-vibes/set-pretext.md

@@ -35,10 +35,10 @@ When a pretext is set:
 - **Without pretext**: "I'll do the task"
 - **With pretext**: "AgentVibes: I'll do the task"
 
-The pretext is saved locally in `.claude/config/agentvibes.json` and persists across sessions.
+The pretext is saved locally in `.agentvibes/config/agentvibes.json` and persists across sessions.
 
 !bash
-CONFIG_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/config"
+CONFIG_DIR="${CLAUDE_PROJECT_DIR:-.}/.agentvibes/config"
 CONFIG_FILE="$CONFIG_DIR/agentvibes.json"
 
 # Get the pretext from arguments

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

@@ -38,7 +38,7 @@ If you prefer party mode without voice switching:
 /agent-vibes:bmad-party disable
 ```
 
-This creates `.claude/plugins/bmad-party-mode-disabled.flag` to opt-out.
+This creates `.agentvibes/bmad/bmad-party-mode-disabled.flag` to opt-out.
 
 ## How It Works
 
@@ -51,7 +51,7 @@ The integration detects agent responses in the format:
 When detected, it:
 1. Extracts the agent's display name (e.g., "Winston", "John")
 2. Maps it to their agent ID using `.bmad/_cfg/agent-manifest.csv`
-3. Looks up their voice from `.claude/config/bmad-voices.md`
+3. Looks up their voice from `.agentvibes/bmad/bmad-voices.md`
 4. Speaks their dialogue with that specific voice
 
 ## Example
@@ -79,7 +79,7 @@ See current agent-to-voice mappings:
 
 Edit voice assignments in:
 ```
-.claude/config/bmad-voices.md
+.agentvibes/bmad/bmad-voices.md
 ```
 
 ## Requirements
@@ -93,8 +93,8 @@ Edit voice assignments in:
 **Party mode voices not working?**
 
 1. Check BMAD is installed: `ls .bmad/_cfg/agent-manifest.csv`
-2. Check voice plugin enabled: `ls .claude/config/bmad-voices-enabled.flag`
-3. Check party mode not disabled: `ls .claude/plugins/bmad-party-mode-disabled.flag`
+2. Check voice plugin enabled: `ls .agentvibes/bmad/bmad-voices-enabled.flag`
+3. Check party mode not disabled: `ls .agentvibes/bmad/bmad-party-mode-disabled.flag`
 4. View status: `/agent-vibes:bmad-party status`
 
 **Wrong voices playing?**

package/.claude/hooks/bmad-speak.sh

@@ -29,7 +29,7 @@ DIALOGUE="${DIALOGUE//\\!/!}"
 DIALOGUE="${DIALOGUE//\\\$/\$}"
 
 # Check if party mode is enabled
-if [[ -f "$PROJECT_ROOT/.claude/plugins/bmad-party-mode-disabled.flag" ]]; then
+if [[ -f "$PROJECT_ROOT/.agentvibes/bmad/bmad-party-mode-disabled.flag" ]]; then
   exit 0
 fi
 

package/.claude/hooks/migrate-to-agentvibes.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/migrate-to-agentvibes.sh
+#
+# AgentVibes - Migration Script for v2.10.0+
+# Migrates configuration from .claude/config/ and .claude/plugins/ to .agentvibes/
+#
+# This script is automatically run by the installer if old config is detected.
+# Can also be run manually: .claude/hooks/migrate-to-agentvibes.sh
+#
+
+set -euo pipefail
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🔄 AgentVibes Configuration Migration${NC}"
+echo ""
+echo "Migrating from .claude/config/ and .claude/plugins/ to .agentvibes/"
+echo ""
+
+# Determine project root
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+    PROJECT_ROOT="$CLAUDE_PROJECT_DIR"
+else
+    PROJECT_ROOT="$(pwd)"
+fi
+
+cd "$PROJECT_ROOT"
+
+# Track if any migrations happened
+MIGRATED=false
+
+# Create target directories
+echo -e "${BLUE}📁 Creating .agentvibes/ directory structure...${NC}"
+mkdir -p .agentvibes/bmad
+mkdir -p .agentvibes/config
+echo -e "${GREEN}✓ Directories created${NC}"
+echo ""
+
+# Migrate BMAD files from .claude/plugins/
+echo -e "${BLUE}🔍 Checking for BMAD files in .claude/plugins/...${NC}"
+
+if [[ -f ".claude/plugins/bmad-voices-enabled.flag" ]]; then
+    echo -e "${YELLOW}  Found: bmad-voices-enabled.flag${NC}"
+    mv .claude/plugins/bmad-voices-enabled.flag .agentvibes/bmad/
+    echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    MIGRATED=true
+fi
+
+if [[ -f ".claude/plugins/bmad-party-mode-disabled.flag" ]]; then
+    echo -e "${YELLOW}  Found: bmad-party-mode-disabled.flag${NC}"
+    mv .claude/plugins/bmad-party-mode-disabled.flag .agentvibes/bmad/
+    echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    MIGRATED=true
+fi
+
+if [[ -f ".claude/plugins/.bmad-previous-settings" ]]; then
+    echo -e "${YELLOW}  Found: .bmad-previous-settings${NC}"
+    mv .claude/plugins/.bmad-previous-settings .agentvibes/bmad/
+    echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    MIGRATED=true
+fi
+
+echo ""
+
+# Migrate BMAD files from .claude/config/
+echo -e "${BLUE}🔍 Checking for BMAD files in .claude/config/...${NC}"
+
+if [[ -f ".claude/config/bmad-voices.md" ]]; then
+    echo -e "${YELLOW}  Found: bmad-voices.md${NC}"
+    mv .claude/config/bmad-voices.md .agentvibes/bmad/
+    echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    MIGRATED=true
+fi
+
+if [[ -f ".claude/config/bmad-voices-enabled.flag" ]]; then
+    echo -e "${YELLOW}  Found: bmad-voices-enabled.flag${NC}"
+    # Check if already exists in new location
+    if [[ -f ".agentvibes/bmad/bmad-voices-enabled.flag" ]]; then
+        echo -e "${BLUE}  (Already exists in .agentvibes/bmad/ - removing duplicate)${NC}"
+        rm .claude/config/bmad-voices-enabled.flag
+    else
+        mv .claude/config/bmad-voices-enabled.flag .agentvibes/bmad/
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    fi
+    MIGRATED=true
+fi
+
+echo ""
+
+# Migrate AgentVibes config files
+echo -e "${BLUE}🔍 Checking for AgentVibes config in .claude/config/...${NC}"
+
+if [[ -f ".claude/config/agentvibes.json" ]]; then
+    echo -e "${YELLOW}  Found: agentvibes.json${NC}"
+    mv .claude/config/agentvibes.json .agentvibes/config/
+    echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}"
+    MIGRATED=true
+fi
+
+if [[ -f ".claude/config/personality-voice-defaults.default.json" ]]; then
+    echo -e "${YELLOW}  Found: personality-voice-defaults.default.json${NC}"
+    mv .claude/config/personality-voice-defaults.default.json .agentvibes/config/
+    echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}"
+    MIGRATED=true
+fi
+
+if [[ -f ".claude/config/personality-voice-defaults.json" ]]; then
+    echo -e "${YELLOW}  Found: personality-voice-defaults.json${NC}"
+    mv .claude/config/personality-voice-defaults.json .agentvibes/config/
+    echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}"
+    MIGRATED=true
+fi
+
+if [[ -f ".claude/config/README-personality-defaults.md" ]]; then
+    echo -e "${YELLOW}  Found: README-personality-defaults.md${NC}"
+    mv .claude/config/README-personality-defaults.md .agentvibes/config/
+    echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}"
+    MIGRATED=true
+fi
+
+echo ""
+
+# Clean up empty directories
+echo -e "${BLUE}🧹 Cleaning up...${NC}"
+
+if [[ -d ".claude/plugins" ]] && [[ -z "$(ls -A .claude/plugins 2>/dev/null)" ]]; then
+    rmdir .claude/plugins
+    echo -e "${GREEN}✓ Removed empty .claude/plugins/ directory${NC}"
+fi
+
+# Note: We don't remove .claude/config/ because it may contain runtime state files
+# like tts-speech-rate.txt that should stay there
+
+echo ""
+
+if [[ "$MIGRATED" == "true" ]]; then
+    echo -e "${GREEN}✅ Migration complete!${NC}"
+    echo ""
+    echo "Your AgentVibes configuration has been moved to:"
+    echo "  .agentvibes/bmad/    - BMAD voice mappings and state"
+    echo "  .agentvibes/config/  - AgentVibes settings"
+    echo ""
+    echo "Old locations are no longer used:"
+    echo "  .claude/plugins/     - (removed if empty)"
+    echo "  .claude/config/      - (AgentVibes files removed)"
+    echo ""
+    echo -e "${BLUE}ℹ️  Note: .claude/config/ still exists for runtime state files${NC}"
+    echo "   (like tts-speech-rate.txt - these belong to Claude Code)"
+else
+    echo -e "${GREEN}✓ No migration needed${NC}"
+    echo ""
+    echo "All configuration is already in .agentvibes/"
+fi
+
+echo ""
+echo -e "${GREEN}🎉 Ready to use AgentVibes!${NC}"

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

@@ -43,7 +43,7 @@ VOICE_OVERRIDE="$2"  # Optional: voice name or direct voice ID
 API_KEY="${ELEVENLABS_API_KEY}"
 
 # Check for project-local pretext configuration
-CONFIG_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/config"
+CONFIG_DIR="${CLAUDE_PROJECT_DIR:-.}/.agentvibes/config"
 CONFIG_FILE="$CONFIG_DIR/agentvibes.json"
 
 if [[ -f "$CONFIG_FILE" ]] && command -v jq &> /dev/null; then

package/.claude/output-styles/agent-vibes.md

@@ -133,8 +133,8 @@ You: "✅ That bug be walkin' the plank now, arr!"
 When a BMAD agent is activated (e.g., `/BMad:agents:pm`), AgentVibes will automatically:
 
 1. **Detect BMAD agent from command/context**
-2. **Check if BMAD plugin is enabled** (`.claude/plugins/bmad-voices-enabled.flag`)
-3. **Look up voice mapping** from `.claude/plugins/bmad-voices.md`
+2. **Check if BMAD plugin is enabled** (`.agentvibes/bmad/bmad-voices-enabled.flag`)
+3. **Look up voice mapping** from `.agentvibes/bmad/bmad-voices.md`
 4. **Apply agent's assigned voice** for all TTS acknowledgments/completions
 5. **Apply agent's personality** from the mapping (if specified)
 
@@ -153,7 +153,7 @@ fi
 # Note: This detection happens automatically when BMAD agent activates
 
 # If BMAD agent detected and plugin enabled, use mapped voice
-if [[ -n "$BMAD_AGENT_ID" ]] && [[ -f ".claude/plugins/bmad-voices-enabled.flag" ]]; then
+if [[ -n "$BMAD_AGENT_ID" ]] && [[ -f ".agentvibes/bmad/bmad-voices-enabled.flag" ]]; then
     MAPPED_VOICE=$(.claude/hooks/bmad-voice-manager.sh get-voice "$BMAD_AGENT_ID")
     MAPPED_PERSONALITY=$(.claude/hooks/bmad-voice-manager.sh get-personality "$BMAD_AGENT_ID")
 

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.8.0
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v2.12.0
 
 ---
 
@@ -94,14 +94,17 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, or using Warp
 
 ## 📰 Latest Release
 
-**[v2.8.0 - Piper Installer Fix](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.8.0)** 🎉
+**[v2.12.0 - .agentvibes/ Directory Migration](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.12.0)** 🎉
 
-AgentVibes v2.8.0 fixes the Piper installer double prompt bug! This minor release resolves an issue where the Piper voice installer would prompt twice for confirmation, causing failures when running through npx due to stdin issues. The installer now automatically downloads recommended voices after the initial confirmation.
+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. Migration is fully automatic during upgrade—users simply run `npx agentvibes@latest update` and their configuration is seamlessly moved.
 
 **Key highlights:**
-- 🔧 **Piper Installer Fix** - Resolves double prompt bug that prevented voice downloads on Linux/npx installations
-- ✅ **Auto Voice Download** - Recommended voices now download automatically after initial confirmation
-- 🐧 **Linux Compatibility** - Improved installation experience for Linux users
+- 📁 **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
+- 🎭 **npx test-bmad-pr** - New one-line command for BMAD PR testing
+- 🎤 **Enhanced Voice Installation** - Better Piper voice detection and status display
 
 [→ View All Releases](https://github.com/paulpreibisch/AgentVibes/releases)
 

package/RELEASE_NOTES.md

@@ -1,3 +1,344 @@
+# 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
+
+**Test Results:**
+```
+Total Tests:  32
+Passed:       32
+Failed:       0
+Success Rate: 100%
+```
+
+### BMAD Testing Command
+
+**One-line BMAD PR testing** (commits: c86b0cd2, fc70b5c5)
+
+Added `npx test-bmad-pr` command for effortless BMAD integration testing:
+
+```bash
+# Test default PR #934
+npx agentvibes@latest test-bmad-pr
+
+# Test specific PR
+npx agentvibes@latest test-bmad-pr 935
+```
+
+**Features:**
+- Downloads and runs automated test script
+- Supports testing any BMAD PR by number
+- Handles both fork and official repo scenarios
+- Zero manual downloads or git cloning required
+- Fallback to official repo if fork unavailable
+- Complete setup validation and environment checks
+
+**Testing Flow:**
+1. Clone BMAD PR into temporary directory
+2. Setup test environment with proper permissions
+3. Run BMAD installer (includes AgentVibes)
+4. Validate party mode and voice assignments
+5. Test agent activation and TTS integration
+6. Cleanup on completion
+
+### Enhanced Voice Installation
+
+**Better Piper voice detection and status** (commits: 5f5eb30b, 9e6b2423, 4dd39606)
+
+- **Verbose Output:** Shows complete list of installed vs missing voices
+- **Status Display:** Clear indication of which voices need downloading
+- **Error Handling:** Graceful handling of broken symlinks (commit: 30c72a05)
+- **Voice Detection:** Fixed fsSync usage for file system operations (commit: 3e9d8769)
+- **Default Voice:** Set ryan-high as default with correct gender labels (commit: de9744d7)
+
+**Example Output:**
+```
+📊 Piper Voice Installation Status
+
+Installed (5/10):
+  ✅ en_US-lessac-medium
+  ✅ en_US-ryan-high
+  ✅ en_US-amy-medium
+  ✅ en_US-joe-medium
+  ✅ en_GB-alan-medium
+
+Missing (5/10):
+  ❌ en_US-hfc_female-medium
+  ❌ en_US-kristin-medium
+  ❌ en_US-kusal-medium
+  ❌ en_US-l2arctic-medium
+  ❌ en_US-libritts-high
+```
+
+---
+
+## 🐛 Bug Fixes
+
+### BMAD Configuration Packaging
+
+**Fixed bmad-voices.md npm packaging** (commits: 8cb250d2, a7209e39)
+- Added exception to `.npmignore` to include `bmad-voices.md`
+- Previously excluded because `.claude/config/` was ignored
+- Essential for party mode agent intros to work
+- Without this, `copyBmadConfigFiles()` had nothing to copy
+
+### BMAD Config Installation
+
+**Added BMAD config file copying** (commits: 8e0c9c1a, 1e1bc623)
+- Copies `bmad-voices.md` to project during installation
+- Contains agent intro text and voice mappings
+- Fixes party mode agents not speaking intros
+- Called in both main install and quick update flows
+
+### Test Script Improvements
+
+**User experience enhancements** (commits: 0532ac5d, d0e67624, 5f7e4d97)
+- Accept '1' as yes in test script prompts (0532ac5d)
+- Changed 'claude-code' command to correct 'claude' (d0e67624)
+- Removed duplicate AgentVibes installation step (5f7e4d97)
+- Fixed npx command syntax in documentation (967ab67e)
+
+### Voice Detection Fixes
+
+**Robustness improvements** (commits: 30c72a05, 3e9d8769)
+- Error handling for broken symlinks in voice file detection
+- Use fsSync methods for file system checks
+- Prevents crashes during voice scanning
+
+---
+
+## 📚 Documentation
+
+### Updated All Path References
+
+**Comprehensive documentation updates** (commit: ab293d05)
+
+Updated 24 files to reference new `.agentvibes/` paths:
+
+**Command Files (4):**
+- `.claude/commands/agent-vibes-bmad-voices.md`
+- `.claude/commands/agent-vibes/agent-vibes.md`
+- `.claude/commands/agent-vibes/bmad.md`
+- `.claude/commands/agent-vibes/set-pretext.md`
+
+**Hook Scripts (3):**
+- `.claude/hooks/bmad-speak.sh`
+- `.claude/hooks/bmad-voice-manager.sh`
+- `.claude/hooks/play-tts-elevenlabs.sh`
+
+**Documentation Files (5):**
+- `docs/architecture/provider-system.md`
+- `docs/bmad-v6-support.md`
+- `docs/installation-structure.md`
+- `docs/technical-deep-dive.md`
+- `docs/voice-mapping-format.md`
+
+**Configuration Files (3):**
+- `.gitignore`
+- `.npmignore`
+- `README.md`
+
+**New Documentation:**
+- `.agentvibes/README.md` - Complete guide to directory structure
+- `BMAD_PR_TESTING_INSTRUCTIONS.md` - Testing guide for BMAD PRs
+
+---
+
+## 🔧 Migration Guide
+
+### Automatic Migration (Recommended)
+
+**For users upgrading from v2.9.x:**
+
+```bash
+# Simply update - migration happens automatically
+npx agentvibes@latest update
+```
+
+**What happens:**
+1. Installer detects old configuration in `.claude/config/` or `.claude/plugins/`
+2. Runs migration script automatically
+3. Moves all files to `.agentvibes/`
+4. Preserves all settings and mappings
+5. Cleans up empty old directories
+6. Shows migration summary
+
+### Manual Migration (If Needed)
+
+**If automatic migration fails:**
+
+```bash
+# Run migration script manually
+.claude/hooks/migrate-to-agentvibes.sh
+```
+
+### Fresh Installations
+
+**New installations create `.agentvibes/` directly:**
+
+```bash
+npx agentvibes@latest install
+```
+
+No migration needed - everything goes to `.agentvibes/` from the start.
+
+### Verification
+
+**Check migration success:**
+
+```bash
+# Should exist
+ls -la .agentvibes/bmad/
+ls -la .agentvibes/config/
+
+# Should be empty or removed
+ls -la .claude/plugins/  # Should not exist
+ls -la .claude/config/   # May exist for runtime files
+```
+
+---
+
+## ⚠️ Breaking Changes
+
+### Directory Structure Reorganization
+
+**BREAKING CHANGE: Configuration locations changed**
+
+While migration is automatic, scripts or tools that directly reference old paths will need updates:
+
+**Old Paths (Deprecated):**
+- `.claude/config/agentvibes.json`
+- `.claude/plugins/bmad-voices-enabled.flag`
+- `.claude/config/bmad-voices.md`
+
+**New Paths (Current):**
+- `.agentvibes/config/agentvibes.json`
+- `.agentvibes/bmad/bmad-voices-enabled.flag`
+- `.agentvibes/bmad/bmad-voices.md`
+
+**Impact:**
+- Custom scripts reading these paths need updates
+- All official AgentVibes code updated automatically
+- BMAD integration updated in AgentVibes hooks
+
+**Mitigation:**
+- Update any custom scripts to use new paths
+- Check `.agentvibes/README.md` for path mapping
+
+---
+
+## 📊 Release Statistics
+
+- **Commits:** 26
+- **Files Changed:** 24 (in migration alone)
+- **Lines Added:** 829
+- **Lines Removed:** 363
+- **Test Coverage:** 32 tests, 100% pass rate
+- **Documentation Updated:** 17 files
+
+---
+
+## 🙏 Acknowledgments
+
+Thanks to the AgentVibes community for feedback on directory organization and namespace concerns that led to this improvement!
+
+---
+
 # Release v2.9.5 - Legacy Output Styles Cleanup
 
 **Release Date:** TBD