agentvibes 2.0.9 → 2.0.12

package/.claude/hooks/piper-installer.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+#
+# @fileoverview Piper TTS Installer
+# @context Installs Piper TTS and downloads initial voice models
+# @architecture Helper script for AgentVibes installer and manual installation
+# @why Piper TTS requires separate installation from pipx/pip
+#
+
+set -e  # Exit on error
+
+echo "🎤 Piper TTS Installer"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Check if running on WSL or Linux
+if ! grep -qi microsoft /proc/version 2>/dev/null && [[ "$(uname -s)" != "Linux" ]]; then
+  echo "❌ Piper TTS is only supported on WSL and Linux"
+  echo "   Your platform: $(uname -s)"
+  echo ""
+  echo "   For macOS/Windows, use ElevenLabs instead:"
+  echo "   /agent-vibes:provider switch elevenlabs"
+  exit 1
+fi
+
+# Check if Piper is already installed
+if command -v piper &> /dev/null; then
+  PIPER_VERSION=$(piper --version 2>&1 || echo "unknown")
+  echo "✅ Piper TTS is already installed!"
+  echo "   Version: $PIPER_VERSION"
+  echo ""
+  echo "   Download voices with: .claude/hooks/piper-download-voices.sh"
+  exit 0
+fi
+
+echo "📦 Installing Piper TTS..."
+echo ""
+
+# Check if pipx is installed
+if ! command -v pipx &> /dev/null; then
+  echo "⚠️  pipx not found. Installing pipx first..."
+  echo ""
+
+  # Try to install pipx
+  if command -v apt-get &> /dev/null; then
+    # Debian/Ubuntu
+    sudo apt-get update
+    sudo apt-get install -y pipx
+  elif command -v brew &> /dev/null; then
+    # macOS (though Piper doesn't run on macOS)
+    brew install pipx
+  elif command -v dnf &> /dev/null; then
+    # Fedora
+    sudo dnf install -y pipx
+  elif command -v pacman &> /dev/null; then
+    # Arch Linux
+    sudo pacman -S python-pipx
+  else
+    echo "❌ Unable to install pipx automatically."
+    echo ""
+    echo "   Please install pipx manually:"
+    echo "   https://pipx.pypa.io/stable/installation/"
+    exit 1
+  fi
+
+  # Ensure pipx is in PATH
+  pipx ensurepath
+  echo ""
+fi
+
+# Install Piper TTS
+echo "📥 Installing Piper TTS via pipx..."
+pipx install piper-tts || pipx install --force piper-tts
+
+# Ensure pipx's bin directory is in PATH
+echo ""
+echo "🔧 Configuring PATH..."
+pipx ensurepath
+
+# Add pipx bin to current session PATH
+PIPX_BIN_DIR="$HOME/.local/bin"
+if [[ -d "$PIPX_BIN_DIR" ]]; then
+  export PATH="$PIPX_BIN_DIR:$PATH"
+fi
+
+# Check if piper is available now
+if ! command -v piper &> /dev/null; then
+  # Try to find piper in the pipx installation directory
+  if [[ -f "$PIPX_BIN_DIR/piper" ]]; then
+    echo "✅ Piper installed at: $PIPX_BIN_DIR/piper"
+
+    # Update shell configuration files
+    SHELL_CONFIG=""
+    if [[ -f "$HOME/.bashrc" ]]; then
+      SHELL_CONFIG="$HOME/.bashrc"
+    elif [[ -f "$HOME/.zshrc" ]]; then
+      SHELL_CONFIG="$HOME/.zshrc"
+    fi
+
+    if [[ -n "$SHELL_CONFIG" ]]; then
+      # Check if PATH update already exists
+      if ! grep -q "export PATH=\"\$HOME/.local/bin:\$PATH\"" "$SHELL_CONFIG"; then
+        echo "" >> "$SHELL_CONFIG"
+        echo "# Added by AgentVibes Piper installer" >> "$SHELL_CONFIG"
+        echo "export PATH=\"\$HOME/.local/bin:\$PATH\"" >> "$SHELL_CONFIG"
+        echo "✅ Updated $SHELL_CONFIG with PATH configuration"
+      fi
+    fi
+
+    # Make piper available in current session
+    export PATH="$PIPX_BIN_DIR:$PATH"
+
+    # Verify it's working
+    if "$PIPX_BIN_DIR/piper" --version &> /dev/null; then
+      echo "✅ Piper is working! You may need to restart your terminal or run:"
+      echo "   export PATH=\"\$HOME/.local/bin:\$PATH\""
+    else
+      echo "❌ Piper installed but not executing properly"
+      echo "   Please restart your terminal and try again"
+      exit 1
+    fi
+  else
+    echo ""
+    echo "❌ Installation completed but piper command not found"
+    echo ""
+    echo "   Try these steps:"
+    echo "   1. Run: pipx ensurepath"
+    echo "   2. Restart your terminal"
+    echo "   3. Run: export PATH=\"\$HOME/.local/bin:\$PATH\""
+    exit 1
+  fi
+fi
+
+echo ""
+echo "✅ Piper TTS installed successfully!"
+echo ""
+
+PIPER_VERSION=$(piper --version 2>&1 || echo "unknown")
+echo "   Version: $PIPER_VERSION"
+echo ""
+
+# Determine voices directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Check for configured voices directory
+VOICES_DIR=""
+if [[ -f "$CLAUDE_DIR/piper-voices-dir.txt" ]]; then
+  VOICES_DIR=$(cat "$CLAUDE_DIR/piper-voices-dir.txt")
+elif [[ -f "$HOME/.claude/piper-voices-dir.txt" ]]; then
+  VOICES_DIR=$(cat "$HOME/.claude/piper-voices-dir.txt")
+else
+  VOICES_DIR="$HOME/.claude/piper-voices"
+fi
+
+echo "📁 Voice storage location: $VOICES_DIR"
+echo ""
+
+# Ask if user wants to download voices now
+read -p "Would you like to download voice models now? [Y/n] " -n 1 -r
+echo ""
+
+if [[ $REPLY =~ ^[Yy]$ ]] || [[ -z $REPLY ]]; then
+  echo ""
+  echo "📥 Downloading recommended voices..."
+  echo ""
+
+  # Use the piper-download-voices.sh script if available
+  if [[ -f "$SCRIPT_DIR/piper-download-voices.sh" ]]; then
+    "$SCRIPT_DIR/piper-download-voices.sh"
+  else
+    # Manual download of a basic voice
+    mkdir -p "$VOICES_DIR"
+
+    echo "Downloading en_US-lessac-medium (recommended)..."
+    curl -L "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx" \
+      -o "$VOICES_DIR/en_US-lessac-medium.onnx"
+    curl -L "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json" \
+      -o "$VOICES_DIR/en_US-lessac-medium.onnx.json"
+
+    echo "✅ Voice downloaded!"
+  fi
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 Piper TTS Setup Complete!"
+echo ""
+echo "Next steps:"
+echo "  1. Download more voices: .claude/hooks/piper-download-voices.sh"
+echo "  2. List available voices: /agent-vibes:list"
+echo "  3. Test it out: /agent-vibes:preview"
+echo ""
+echo "Enjoy your free, offline TTS! 🎤"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

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

@@ -49,11 +49,38 @@ VOICE_ID=""
 LANGUAGE_CODE="en"  # Default to English
 
 # Get current language setting
-CURRENT_LANGUAGE=$(get_current_language)
+CURRENT_LANGUAGE=$(get_language_code)
 
 # Get language code for API
-LANGUAGE_CODE=$(get_language_code_for_name "$CURRENT_LANGUAGE")
-[[ -z "$LANGUAGE_CODE" ]] && LANGUAGE_CODE="en"
+# ElevenLabs uses 2-letter ISO codes
+case "$CURRENT_LANGUAGE" in
+  spanish) LANGUAGE_CODE="es" ;;
+  french) LANGUAGE_CODE="fr" ;;
+  german) LANGUAGE_CODE="de" ;;
+  italian) LANGUAGE_CODE="it" ;;
+  portuguese) LANGUAGE_CODE="pt" ;;
+  chinese) LANGUAGE_CODE="zh" ;;
+  japanese) LANGUAGE_CODE="ja" ;;
+  korean) LANGUAGE_CODE="ko" ;;
+  russian) LANGUAGE_CODE="ru" ;;
+  polish) LANGUAGE_CODE="pl" ;;
+  dutch) LANGUAGE_CODE="nl" ;;
+  turkish) LANGUAGE_CODE="tr" ;;
+  arabic) LANGUAGE_CODE="ar" ;;
+  hindi) LANGUAGE_CODE="hi" ;;
+  swedish) LANGUAGE_CODE="sv" ;;
+  danish) LANGUAGE_CODE="da" ;;
+  norwegian) LANGUAGE_CODE="no" ;;
+  finnish) LANGUAGE_CODE="fi" ;;
+  czech) LANGUAGE_CODE="cs" ;;
+  romanian) LANGUAGE_CODE="ro" ;;
+  ukrainian) LANGUAGE_CODE="uk" ;;
+  greek) LANGUAGE_CODE="el" ;;
+  bulgarian) LANGUAGE_CODE="bg" ;;
+  croatian) LANGUAGE_CODE="hr" ;;
+  slovak) LANGUAGE_CODE="sk" ;;
+  english|*) LANGUAGE_CODE="en" ;;
+esac
 
 if [[ -n "$VOICE_OVERRIDE" ]]; then
   # Check if override is a voice name (lookup in mapping)

package/.claude/hooks/play-tts-local-wrapper.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+
+# Local TTS Wrapper for AgentVibes
+# This script runs on your local Windows WSL and receives audio from remote server
+# Usage: ./play-tts-local-wrapper.sh "Text to speak"
+
+# Configuration
+REMOTE_HOST="${AGENTVIBES_REMOTE_HOST:-ubuntu-rdp}"
+REMOTE_SCRIPT=".claude/hooks/play-tts-remote.sh"
+
+# Get text from arguments or stdin
+if [ $# -gt 0 ]; then
+    TEXT="$*"
+else
+    TEXT=$(cat)
+fi
+
+# Function to play audio based on what's available
+play_audio() {
+    # Try paplay first (WSLg PulseAudio)
+    if command -v paplay &> /dev/null; then
+        paplay --format=s16le --channels=1 --rate=22050
+    # Try aplay next
+    elif command -v aplay &> /dev/null; then
+        aplay -f S16_LE -c 1 -r 22050
+    # Try PowerShell audio playback as last resort
+    elif command -v powershell.exe &> /dev/null; then
+        # Save to temp file and play with Windows Media Player
+        TEMP_FILE="/tmp/tts_audio_$$.wav"
+        cat > "$TEMP_FILE"
+        powershell.exe -Command "& {(New-Object Media.SoundPlayer '$TEMP_FILE').PlaySync()}" 2>/dev/null
+        rm -f "$TEMP_FILE"
+    else
+        echo "Error: No audio playback method available" >&2
+        exit 1
+    fi
+}
+
+# SSH to remote, generate TTS, and pipe back for local playback
+echo "$TEXT" | ssh "$REMOTE_HOST" "bash $REMOTE_SCRIPT" | play_audio
+
+# Alternative method if you want to save the audio file
+# echo "$TEXT" | ssh "$REMOTE_HOST" "bash $REMOTE_SCRIPT" > /tmp/tts_output.wav
+# paplay /tmp/tts_output.wav

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

@@ -79,7 +79,15 @@ if [[ -z "$TEXT" ]]; then
 fi
 
 # Check if Piper is installed
-if ! command -v piper &> /dev/null; then
+PIPER_CMD=""
+if command -v piper &> /dev/null; then
+  PIPER_CMD="piper"
+elif [[ -x "$HOME/.local/bin/piper" ]]; then
+  # Check pipx installation directory
+  PIPER_CMD="$HOME/.local/bin/piper"
+  echo "⚠️  Using Piper from: $PIPER_CMD"
+  echo "   Add to PATH: export PATH=\"\$HOME/.local/bin:\$PATH\""
+else
   echo "❌ Error: Piper TTS not installed"
   echo "Install with: pipx install piper-tts"
   echo "Or run: .claude/hooks/piper-installer.sh"
@@ -152,7 +160,7 @@ TEMP_FILE="$AUDIO_DIR/tts-$(date +%s).wav"
 # @exitcode 0=success, 4=synthesis error
 # @sideeffects Creates audio file
 # @edgecases Handles piper errors, invalid models
-echo "$TEXT" | piper --model "$VOICE_PATH" --output_file "$TEMP_FILE" 2>/dev/null
+echo "$TEXT" | "$PIPER_CMD" --model "$VOICE_PATH" --output_file "$TEMP_FILE" 2>/dev/null
 
 if [[ ! -f "$TEMP_FILE" ]] || [[ ! -s "$TEMP_FILE" ]]; then
   echo "❌ Failed to synthesize speech with Piper"

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

@@ -0,0 +1,81 @@
+#!/bin/bash
+
+# Remote TTS Generator for AgentVibes
+# This script generates TTS on the remote server and outputs audio data
+# that can be piped through SSH for local playback
+
+# Default voice model
+DEFAULT_MODEL="$HOME/.claude/piper-voices/en_US-lessac-medium.onnx"
+DEFAULT_VOICE="Aria"
+
+# Get text from arguments or stdin
+if [ $# -gt 0 ]; then
+    TEXT="$*"
+else
+    TEXT=$(cat)
+fi
+
+# Check if we're in an SSH session or force remote mode
+if [ -n "$SSH_CONNECTION" ] || [ -n "$SSH_CLIENT" ] || [ "$FORCE_REMOTE_TTS" = "true" ]; then
+    # We're on a remote server or forcing remote mode
+
+    # Check for piper
+    if command -v piper &> /dev/null; then
+        PIPER_CMD="piper"
+    elif [ -f "$HOME/.local/share/pipx/venvs/piper-tts/bin/piper" ]; then
+        PIPER_CMD="$HOME/.local/share/pipx/venvs/piper-tts/bin/piper"
+    elif [ -f "$HOME/bin/piper" ]; then
+        PIPER_CMD="$HOME/bin/piper"
+    else
+        # Fallback to espeak-ng if available
+        if command -v espeak-ng &> /dev/null; then
+            echo "$TEXT" | espeak-ng --stdout
+            exit 0
+        else
+            echo "Error: No TTS engine found (piper or espeak-ng)" >&2
+            exit 1
+        fi
+    fi
+
+    # Check for voice model
+    if [ -f "$DEFAULT_MODEL" ]; then
+        MODEL="$DEFAULT_MODEL"
+    elif [ -f "$HOME/.local/share/piper/voices/en_US-lessac-medium.onnx" ]; then
+        MODEL="$HOME/.local/share/piper/voices/en_US-lessac-medium.onnx"
+    else
+        echo "Error: No voice model found" >&2
+        exit 1
+    fi
+
+    # Generate TTS and output raw audio to stdout
+    echo "$TEXT" | "$PIPER_CMD" -m "$MODEL" -f - 2>/dev/null
+
+else
+    # We're running locally in WSL - still generate TTS for testing
+    # Check for piper in WSL
+    if [ -f "$HOME/.local/share/pipx/venvs/piper-tts/bin/piper" ]; then
+        PIPER_CMD="$HOME/.local/share/pipx/venvs/piper-tts/bin/piper"
+    elif [ -f "$HOME/bin/piper" ]; then
+        PIPER_CMD="$HOME/bin/piper"
+    elif command -v pipx &> /dev/null; then
+        # Try using pipx run as fallback
+        echo "$TEXT" | pipx run piper-tts -m "$DEFAULT_MODEL" -f - 2>/dev/null
+        exit 0
+    else
+        echo "Error: No TTS engine found in local WSL" >&2
+        exit 1
+    fi
+
+    # Check for voice model
+    if [ -f "$DEFAULT_MODEL" ]; then
+        MODEL="$DEFAULT_MODEL"
+    elif [ -f "$HOME/.local/share/piper/voices/en_US-lessac-medium.onnx" ]; then
+        MODEL="$HOME/.local/share/piper/voices/en_US-lessac-medium.onnx"
+    else
+        echo "Error: No voice model found" >&2
+        exit 1
+    fi
+
+    # Generate TTS and output raw audio to stdout
+    echo "$TEXT" | "$PIPER_CMD" -m "$MODEL" -f - 2>/dev/null
+fi

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

@@ -18,12 +18,46 @@ VOICE_OVERRIDE="$2"  # Optional: voice name or ID
 # Get script directory
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
+# Check if we're in an SSH session and should use remote TTS
+if [ -n "$SSH_CONNECTION" ] || [ -n "$SSH_CLIENT" ]; then
+    # Check if remote TTS forwarding is enabled
+    if [ -f "$HOME/.claude/tts-remote-forward" ] || [ "$AGENTVIBES_REMOTE_TTS" = "true" ]; then
+        # In SSH session with forwarding enabled - generate locally but don't play
+        # The audio data should be captured and sent to the client
+
+        # Source provider manager to get active provider
+        source "$SCRIPT_DIR/provider-manager.sh"
+        ACTIVE_PROVIDER=$(get_active_provider)
+
+        case "$ACTIVE_PROVIDER" in
+          piper)
+            # Generate audio and output to stdout for SSH forwarding
+            exec "$SCRIPT_DIR/play-tts-remote.sh" "$TEXT"
+            ;;
+          elevenlabs)
+            # For ElevenLabs, we might need a different approach
+            # since it requires API calls
+            exec "$SCRIPT_DIR/play-tts-elevenlabs.sh" "$TEXT" "$VOICE_OVERRIDE"
+            ;;
+          *)
+            echo "❌ Unknown provider: $ACTIVE_PROVIDER" >&2
+            exit 1
+            ;;
+        esac
+        exit 0
+    fi
+fi
+
+# Normal local playback path
 # Source provider manager to get active provider
 source "$SCRIPT_DIR/provider-manager.sh"
 
 # Get active provider
 ACTIVE_PROVIDER=$(get_active_provider)
 
+# Show GitHub star reminder (once per day)
+"$SCRIPT_DIR/github-star-reminder.sh" 2>/dev/null || true
+
 # Route to appropriate provider implementation
 case "$ACTIVE_PROVIDER" in
   elevenlabs)

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

@@ -12,6 +12,35 @@ source "$SCRIPT_DIR/language-manager.sh"
 
 COMMAND="${1:-help}"
 
+# @function is_language_supported
+# @intent Check if a language is supported by a provider
+# @param $1 {string} language - Language code (e.g., "spanish", "french")
+# @param $2 {string} provider - Provider name (e.g., "elevenlabs", "piper")
+# @returns 0 if supported, 1 if not
+is_language_supported() {
+  local language="$1"
+  local provider="$2"
+
+  # English is always supported
+  if [[ "$language" == "english" ]] || [[ "$language" == "en" ]]; then
+    return 0
+  fi
+
+  case "$provider" in
+    elevenlabs)
+      # ElevenLabs supports all languages via multilingual voices
+      return 0
+      ;;
+    piper)
+      # Piper only supports English natively
+      return 1
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
 # @function provider_list
 # @intent Display all available providers with status
 provider_list() {
@@ -99,7 +128,7 @@ provider_switch() {
 
   # Check language compatibility
   local current_language
-  current_language=$(get_current_language)
+  current_language=$(get_language_code)
 
   if [[ "$current_language" != "english" ]]; then
     if ! is_language_supported "$current_language" "$new_provider" 2>/dev/null; then

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

@@ -244,8 +244,8 @@ case "$1" in
       fi
 
       echo ""
-      echo "💡 Tip: To hear automatic TTS narration, enable the agent-vibes output style:"
-      echo "   /output-style agent-vibes"
+      echo "💡 Tip: To hear automatic TTS narration, enable the Agent Vibes output style:"
+      echo "   /output-style Agent Vibes"
     fi
     ;;
 

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

@@ -128,55 +128,71 @@ You: "✅ That bug be walkin' the plank now, arr!"
 
 ## BMAD Plugin Integration
 
-**Automatic voice switching for BMAD agents:**
+**Automatic voice switching and question detection for BMAD agents:**
 
-When a BMAD agent is activated (e.g., `/BMad:agents:pm`), AgentVibes will automatically:
+When a BMAD agent is active, AgentVibes will automatically detect and speak questions.
 
-1. **Detect BMAD agent from command/context**
-2. **Check if BMAD plugin is enabled** (`.claude/plugins/bmad-voices-enabled.flag`)
+### Detection Method:
+1. **Check for `.bmad-agent-context` file** - Contains agent ID if BMAD agent is active
+2. **Check if BMAD plugin is enabled** - `.claude/plugins/bmad-voices-enabled.flag` exists
 3. **Look up voice mapping** from `.claude/plugins/bmad-voices.md`
-4. **Apply agent's assigned voice** for all TTS acknowledgments/completions
-5. **Apply agent's personality** from the mapping (if specified)
 
-**Implementation:**
-```bash
-# At the start of acknowledgment/completion:
-# Try to detect BMAD agent ID from current context
-BMAD_AGENT_ID=""
+### MANDATORY BMAD QUESTION TTS PROTOCOL
 
-# Method 1: Check if we're in a BMAD agent command context
-if [[ -f ".bmad-agent-context" ]]; then
-    BMAD_AGENT_ID=$(cat .bmad-agent-context 2>/dev/null)
-fi
+**THIS IS A CRITICAL EXECUTION REQUIREMENT - NOT OPTIONAL**
 
-# Method 2: Parse from command history/context (fallback)
-# Note: This detection happens automatically when BMAD agent activates
+When a BMAD agent is active, you MUST follow this EXACT protocol for EVERY response:
 
-# If BMAD agent detected and plugin enabled, use mapped voice
-if [[ -n "$BMAD_AGENT_ID" ]] && [[ -f ".claude/plugins/bmad-voices-enabled.flag" ]]; then
+**STEP 1: Check BMAD Context (BEFORE drafting ANY response)**
+```bash
+if [[ -f ".bmad-agent-context" ]] && [[ -f ".claude/plugins/bmad-voices-enabled.flag" ]]; then
+    BMAD_AGENT_ID=$(cat .bmad-agent-context 2>/dev/null)
     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")
-
-    if [[ -n "$MAPPED_VOICE" ]]; then
-        # Use BMAD agent's mapped voice and personality
-        if [[ -n "$MAPPED_PERSONALITY" ]] && [[ "$MAPPED_PERSONALITY" != "normal" ]]; then
-            # Read personality instructions from .claude/personalities/${MAPPED_PERSONALITY}.md
-            # Generate response in that personality style
-        fi
-        .claude/hooks/play-tts.sh "message" "$MAPPED_VOICE"
-        # Exit early - don't use default personality system
-        return
-    fi
 fi
+```
+
+**STEP 2: Draft Your Response**
+- Write your complete response text (don't show to user yet)
+
+**STEP 3: Scan for Questions (MANDATORY - DO NOT SKIP)**
+If your response contains ANY of these:
+- Question mark (?)
+- Numbered list (1., 2., 3., etc.)
+- Question phrases: "What would you like", "Should I", "Would you prefer", "Which option", "How should", "Do you want"
 
-# If no BMAD agent or plugin disabled, use standard personality/sentiment system
-# ... continue with normal sentiment/personality logic ...
+Then IMMEDIATELY execute STEP 4 BEFORE showing response.
+
+**STEP 4: Speak Questions via TTS (MANDATORY)**
+```bash
+# Extract the question text and speak it
+.claude/hooks/play-tts.sh "the actual question text" "$MAPPED_VOICE"
+```
+
+**STEP 5: Show Response to User**
+- Only NOW display the response text
+
+**CRITICAL RULES:**
+1. This protocol is MANDATORY for EVERY BMAD agent response
+2. Steps 1-5 must execute in EXACT order
+3. You MUST use Bash tool to execute TTS in STEP 4
+4. NEVER skip STEP 3 scanning - it is required
+5. NEVER show response before speaking questions
+
+**Example Execution:**
+```
+User: "What should we do?"
+[STEP 1: Check context - analyst agent active]
+[STEP 2: Draft response: "What would you like to do next?\n\n1. Option A\n2. Option B"]
+[STEP 3: Scan - FOUND question "What would you like to do next?" and numbered list]
+[STEP 4: Execute Bash: .claude/hooks/play-tts.sh "What would you like to do next" "Ralf Eisend"]
+[STEP 5: Show response to user]
 ```
 
 **BMAD Agent Context Tracking:**
-- When a BMAD agent activates, write agent ID to `.bmad-agent-context`
-- When agent exits, remove the file
-- This allows AgentVibes to know which BMAD agent is active
+- Context file `.bmad-agent-context` contains agent ID when BMAD agent is active
+- Created automatically by STEP 3.5a in activation-instructions
+- Removed automatically when agent exits
+- This allows AgentVibes to detect which BMAD agent is active
 
 **Voice Priority (in order):**
 1. BMAD plugin voice (if agent active and plugin enabled)

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.0.9
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v2.0.10
 
 ---
 
@@ -45,7 +45,7 @@
 
 ## 📰 Latest Release
 
-**[v2.0.0 - The Multi-Provider Revolution](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.0.9)** 🎉
+**[v2.0.0 - The Multi-Provider Revolution](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.0.10)** 🎉
 
 The biggest update ever! **Multi-provider TTS support** (ElevenLabs + Piper TTS), **30+ languages**, expanded voice library (27+ voices), advanced sentiment system, enhanced BMAD integration, and comprehensive multilingual support. Choose between premium ElevenLabs voices or free offline Piper TTS!