bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.2

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

@@ -0,0 +1,178 @@
+#!/bin/bash
+#
+# File: .claude/hooks/piper-installer.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Piper TTS Installer - Installs Piper TTS via pipx and downloads initial voice models
+# @context Automated installation script for free offline Piper TTS on WSL/Linux systems
+# @architecture Helper script for AgentVibes installer, invoked manually or from provider switcher
+# @dependencies pipx (Python package installer), apt-get/brew/dnf/pacman (for pipx installation)
+# @entrypoints Called by src/installer.js or manually by users during setup
+# @patterns Platform detection (WSL/Linux only), package manager abstraction, guided voice download
+# @related piper-download-voices.sh, provider-manager.sh, src/installer.js
+#
+
+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 doesn't have a --version flag, just check if it exists
+  echo "✅ Piper TTS is already installed!"
+  echo "   Location: $(which piper)"
+  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
+
+if ! command -v piper &> /dev/null; then
+  echo ""
+  echo "❌ Installation completed but piper command not found in PATH"
+  echo ""
+  echo "   Try running: pipx ensurepath"
+  echo "   Then restart your terminal"
+  exit 1
+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/piper-multispeaker-registry.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+#
+# File: .claude/hooks/piper-multispeaker-registry.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Multi-Speaker Voice Registry - Maps speaker names to ONNX models and speaker IDs
+# @context Enables individual speaker selection from multi-speaker Piper models (e.g., 16Speakers)
+# @architecture Static registry mapping speaker names to model files and numeric speaker IDs
+# @dependencies piper-voice-manager.sh (voice storage), play-tts-piper.sh (TTS with speaker ID)
+# @entrypoints Sourced by voice-manager.sh for multi-speaker voice switching
+# @patterns Registry pattern, speaker ID mapping, model-to-speaker association
+# @related voice-manager.sh, play-tts-piper.sh, 16Speakers.onnx.json (speaker_id_map)
+#
+
+# Registry of multi-speaker models and their speaker names
+# Format: "SpeakerName:model_file:speaker_id:description"
+#
+# 16Speakers Model (12 US + 4 UK voices):
+# Source: LibriVox Public Domain recordings
+# Model: 16Speakers.onnx (77MB)
+#
+MULTISPEAKER_VOICES=(
+  # US English Speakers (0-11)
+  "Cori_Samuel:16Speakers:0:US English Female"
+  "Kara_Shallenberg:16Speakers:1:US English Female"
+  "Kristin_Hughes:16Speakers:2:US English Female"
+  "Maria_Kasper:16Speakers:3:US English Female"
+  "Mike_Pelton:16Speakers:4:US English Male"
+  "Mark_Nelson:16Speakers:5:US English Male"
+  "Michael_Scherer:16Speakers:6:US English Male"
+  "James_K_White:16Speakers:7:US English Male"
+  "Rose_Ibex:16Speakers:8:US English Female"
+  "progressingamerica:16Speakers:9:US English Male"
+  "Steve_C:16Speakers:10:US English Male"
+  "Owlivia:16Speakers:11:US English Female"
+
+  # UK English Speakers (12-15)
+  "Paul_Hampton:16Speakers:12:UK English Male"
+  "Jennifer_Dorr:16Speakers:13:UK English Female"
+  "Emily_Cripps:16Speakers:14:UK English Female"
+  "Martin_Clifton:16Speakers:15:UK English Male"
+)
+
+# @function get_multispeaker_info
+# @intent Get model and speaker ID for a speaker name
+# @why Enables users to select individual speakers from multi-speaker models by name
+# @param $1 {string} speaker_name - Speaker name (e.g., "Cori_Samuel", "Rose_Ibex")
+# @returns Echoes "model:speaker_id" (e.g., "16Speakers:0") to stdout
+# @exitcode 0=speaker found, 1=speaker not found
+# @sideeffects None (read-only lookup)
+# @edgecases Case-insensitive matching
+# @calledby voice-manager.sh switch command
+# @calls None (pure bash array iteration)
+get_multispeaker_info() {
+  local speaker_name="$1"
+  for entry in "${MULTISPEAKER_VOICES[@]}"; do
+    name="${entry%%:*}"
+    rest="${entry#*:}"
+    model="${rest%%:*}"
+    rest="${rest#*:}"
+    speaker_id="${rest%%:*}"
+
+    if [[ "${name,,}" == "${speaker_name,,}" ]]; then
+      echo "$model:$speaker_id"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# @function list_multispeaker_voices
+# @intent Display all available multi-speaker voices with descriptions
+# @why Help users discover individual speakers within multi-speaker models
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Writes formatted list to stdout
+# @edgecases None
+# @calledby voice-manager.sh list command, /agent-vibes:list
+# @calls None (pure bash array iteration)
+list_multispeaker_voices() {
+  echo "🎭 Multi-Speaker Voices (16Speakers Model):"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  local current_model=""
+  for entry in "${MULTISPEAKER_VOICES[@]}"; do
+    name="${entry%%:*}"
+    rest="${entry#*:}"
+    model="${rest%%:*}"
+    rest="${rest#*:}"
+    speaker_id="${rest%%:*}"
+    description="${rest#*:}"
+
+    # Print section header when model changes
+    if [[ "$model" != "$current_model" ]]; then
+      if [[ -n "$current_model" ]]; then
+        echo ""
+      fi
+      echo "  Model: $model.onnx"
+      current_model="$model"
+    fi
+
+    echo "    • $name (ID: $speaker_id) - $description"
+  done
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Usage: /agent-vibes:switch Cori_Samuel"
+  echo "       /agent-vibes:switch Rose_Ibex"
+}
+
+# @function get_multispeaker_description
+# @intent Get description for a speaker name
+# @why Provide user-friendly info about speaker characteristics
+# @param $1 {string} speaker_name - Speaker name
+# @returns Echoes description (e.g., "US English Female") to stdout
+# @exitcode 0=speaker found, 1=speaker not found
+# @sideeffects None (read-only lookup)
+# @edgecases Case-insensitive matching
+# @calledby voice-manager.sh switch command (for confirmation message)
+# @calls None (pure bash array iteration)
+get_multispeaker_description() {
+  local speaker_name="$1"
+  for entry in "${MULTISPEAKER_VOICES[@]}"; do
+    name="${entry%%:*}"
+    rest="${entry#*:}"
+    rest="${rest#*:}"
+    rest="${rest#*:}"
+    description="${rest}"
+
+    if [[ "${name,,}" == "${speaker_name,,}" ]]; then
+      echo "$description"
+      return 0
+    fi
+  done
+  return 1
+}

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

@@ -0,0 +1,293 @@
+#!/bin/bash
+#
+# File: .claude/hooks/piper-voice-manager.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Piper Voice Model Management - Downloads, caches, and validates Piper ONNX voice models
+# @context Voice model lifecycle management for free offline Piper TTS provider
+# @architecture HuggingFace repository integration with local caching, global storage for voice models
+# @dependencies curl (downloads), piper binary (TTS synthesis)
+# @entrypoints Sourced by play-tts-piper.sh, piper-download-voices.sh, and provider management commands
+# @patterns HuggingFace model repository integration, file-based caching (~25MB per voice), global storage
+# @related play-tts-piper.sh, piper-download-voices.sh, provider-manager.sh, GitHub Issue #25
+#
+
+# Base URL for Piper voice models on HuggingFace
+PIPER_VOICES_BASE_URL="https://huggingface.co/rhasspy/piper-voices/resolve/main"
+
+# AI NOTE: Voice storage precedence order:
+# 1. PIPER_VOICES_DIR environment variable (highest priority)
+# 2. Project-local .claude/piper-voices-dir.txt
+# 3. Directory tree search for .claude/piper-voices-dir.txt
+# 4. Global ~/.claude/piper-voices-dir.txt
+# 5. Default ~/.claude/piper-voices (fallback)
+# This allows per-project voice isolation while defaulting to shared global storage.
+
+# @function get_voice_storage_dir
+# @intent Determine directory for storing Piper voice models with precedence chain
+# @why Voice models are large (~25MB each) and should be shared globally by default, but allow per-project overrides
+# @param None
+# @returns Echoes path to voice storage directory
+# @exitcode Always 0
+# @sideeffects Creates directory if it doesn't exist
+# @edgecases Searches up directory tree for .claude/ folder, supports custom paths via env var or config files
+# @calledby All voice management functions (verify_voice, get_voice_path, download_voice, list_downloaded_voices)
+# @calls mkdir, cat, dirname
+get_voice_storage_dir() {
+  local voice_dir
+
+  # Check for custom path in environment or config file
+  if [[ -n "$PIPER_VOICES_DIR" ]]; then
+    voice_dir="$PIPER_VOICES_DIR"
+  else
+    # Check for config file (project-local first, then global)
+    local config_file
+    if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -f "$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt" ]]; then
+      config_file="$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt"
+    else
+      # Search up directory tree for .claude/
+      local current_dir="$PWD"
+      while [[ "$current_dir" != "/" ]]; do
+        if [[ -f "$current_dir/.claude/piper-voices-dir.txt" ]]; then
+          config_file="$current_dir/.claude/piper-voices-dir.txt"
+          break
+        fi
+        current_dir=$(dirname "$current_dir")
+      done
+
+      # Check global config
+      if [[ -z "$config_file" ]] && [[ -f "$HOME/.claude/piper-voices-dir.txt" ]]; then
+        config_file="$HOME/.claude/piper-voices-dir.txt"
+      fi
+    fi
+
+    if [[ -n "$config_file" ]]; then
+      voice_dir=$(cat "$config_file" | tr -d '[:space:]')
+    fi
+  fi
+
+  # Fallback to default global storage
+  if [[ -z "$voice_dir" ]]; then
+    voice_dir="$HOME/.claude/piper-voices"
+  fi
+
+  mkdir -p "$voice_dir"
+  echo "$voice_dir"
+}
+
+# @function verify_voice
+# @intent Check if voice model files exist locally (both .onnx and .onnx.json)
+# @why Avoid redundant downloads, detect missing models, ensure model integrity
+# @param $1 {string} voice_name - Voice model name (e.g., en_US-lessac-medium)
+# @returns None
+# @exitcode 0=voice exists and complete, 1=voice missing or incomplete
+# @sideeffects None (read-only check)
+# @edgecases Requires both ONNX model and JSON config to return success
+# @calledby download_voice, piper-download-voices.sh
+# @calls get_voice_storage_dir
+verify_voice() {
+  local voice_name="$1"
+  local voice_dir
+  voice_dir=$(get_voice_storage_dir)
+
+  local onnx_file="$voice_dir/${voice_name}.onnx"
+  local json_file="$voice_dir/${voice_name}.onnx.json"
+
+  [[ -f "$onnx_file" ]] && [[ -f "$json_file" ]]
+}
+
+# @function get_voice_path
+# @intent Get absolute path to voice model ONNX file for Piper binary
+# @why Piper binary requires full absolute path to model file, not just voice name
+# @param $1 {string} voice_name - Voice model name
+# @returns Echoes absolute path to .onnx file to stdout
+# @exitcode 0=success, 1=voice not found
+# @sideeffects Writes error message to stderr if voice not found
+# @edgecases Returns error if voice not downloaded yet
+# @calledby play-tts-piper.sh for TTS synthesis
+# @calls get_voice_storage_dir
+get_voice_path() {
+  local voice_name="$1"
+  local voice_dir
+  voice_dir=$(get_voice_storage_dir)
+
+  local onnx_file="$voice_dir/${voice_name}.onnx"
+
+  if [[ ! -f "$onnx_file" ]]; then
+    echo "❌ Voice model not found: $voice_name" >&2
+    return 1
+  fi
+
+  echo "$onnx_file"
+}
+
+# AI NOTE: Voice name format is: lang_LOCALE-speaker-quality
+# Example: en_US-lessac-medium
+#   - lang: en (language code)
+#   - LOCALE: US (locale/country code)
+#   - speaker: lessac (speaker/voice name)
+#   - quality: medium (model quality: low/medium/high)
+# HuggingFace repository structure: {lang}/{lang}_{LOCALE}/{speaker}/{quality}/
+
+# @function parse_voice_components
+# @intent Extract language, locale, speaker, quality components from voice name
+# @why HuggingFace uses structured directory paths based on these components
+# @param $1 {string} voice_name - Voice name (e.g., en_US-lessac-medium)
+# @returns None (sets global variables)
+# @exitcode Always 0
+# @sideeffects Sets global variables: LANG, LOCALE, SPEAKER, QUALITY
+# @edgecases Expects specific format: lang_LOCALE-speaker-quality
+# @calledby download_voice
+# @calls None (pure string manipulation)
+parse_voice_components() {
+  local voice_name="$1"
+
+  # Extract components from voice name
+  # Format: en_US-lessac-medium
+  #         lang_LOCALE-speaker-quality
+
+  local lang_locale="${voice_name%%-*}"  # en_US
+  local speaker_quality="${voice_name#*-}"  # lessac-medium
+
+  LANG="${lang_locale%%_*}"  # en
+  LOCALE="${lang_locale#*_}"  # US
+  SPEAKER="${speaker_quality%%-*}"  # lessac
+  QUALITY="${speaker_quality#*-}"  # medium
+}
+
+# @function download_voice
+# @intent Download Piper voice model from HuggingFace repository
+# @why Provide free offline TTS voices without requiring API keys
+# @param $1 {string} voice_name - Voice model name (e.g., en_US-lessac-medium)
+# @param $2 {string} lang_code - Language code (optional, inferred from voice_name, unused)
+# @returns None
+# @exitcode 0=success (already downloaded or newly downloaded), 1=download failed
+# @sideeffects Downloads .onnx and .onnx.json files (~25MB total), removes partial downloads on failure
+# @edgecases Handles network failures, validates file integrity (non-zero size), skips if already downloaded
+# @calledby piper-download-voices.sh, manual voice download commands
+# @calls parse_voice_components, verify_voice, get_voice_storage_dir, curl, rm
+download_voice() {
+  local voice_name="$1"
+  local lang_code="${2:-}"
+
+  local voice_dir
+  voice_dir=$(get_voice_storage_dir)
+
+  # Check if already downloaded
+  if verify_voice "$voice_name"; then
+    echo "✅ Voice already downloaded: $voice_name"
+    return 0
+  fi
+
+  # Parse voice components
+  parse_voice_components "$voice_name"
+
+  # Construct download URLs
+  # Path format: {language}/{language}_{locale}/{speaker}/{quality}/{speaker}-{quality}.onnx
+  local model_path="${LANG}/${LANG}_${LOCALE}/${SPEAKER}/${QUALITY}/${voice_name}"
+  local onnx_url="${PIPER_VOICES_BASE_URL}/${model_path}.onnx"
+  local json_url="${PIPER_VOICES_BASE_URL}/${model_path}.onnx.json"
+
+  echo "📥 Downloading Piper voice: $voice_name"
+  echo "   Source: HuggingFace (rhasspy/piper-voices)"
+  echo "   Size: ~25MB"
+  echo ""
+
+  # Download ONNX model
+  echo "   Downloading model file..."
+  if ! curl -L --progress-bar -o "$voice_dir/${voice_name}.onnx" "$onnx_url"; then
+    echo "❌ Failed to download voice model"
+    rm -f "$voice_dir/${voice_name}.onnx"
+    return 1
+  fi
+
+  # Download JSON config
+  echo "   Downloading config file..."
+  if ! curl -L -s -o "$voice_dir/${voice_name}.onnx.json" "$json_url"; then
+    echo "❌ Failed to download voice config"
+    rm -f "$voice_dir/${voice_name}.onnx" "$voice_dir/${voice_name}.onnx.json"
+    return 1
+  fi
+
+  # Verify file integrity (basic check - file size > 0)
+  if [[ ! -s "$voice_dir/${voice_name}.onnx" ]]; then
+    echo "❌ Downloaded file is empty or corrupt"
+    rm -f "$voice_dir/${voice_name}.onnx" "$voice_dir/${voice_name}.onnx.json"
+    return 1
+  fi
+
+  echo "✅ Voice downloaded successfully: $voice_name"
+  echo "   Location: $voice_dir/${voice_name}.onnx"
+}
+
+# @function list_downloaded_voices
+# @intent Display all locally cached voice models with file sizes
+# @why Help users see what voices they have available and storage usage
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Writes formatted list to stdout
+# @edgecases Handles empty voice directory gracefully, uses nullglob to avoid literal *.onnx
+# @calledby Voice management commands, /agent-vibes:list
+# @calls get_voice_storage_dir, basename, du
+list_downloaded_voices() {
+  local voice_dir
+  voice_dir=$(get_voice_storage_dir)
+
+  echo "📦 Downloaded Piper Voices:"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  local count=0
+  shopt -s nullglob
+  for onnx_file in "$voice_dir"/*.onnx; do
+    if [[ -f "$onnx_file" ]]; then
+      local voice_name
+      voice_name=$(basename "$onnx_file" .onnx)
+      local file_size
+      file_size=$(du -h "$onnx_file" | cut -f1)
+      echo "  • $voice_name ($file_size)"
+      ((count++))
+    fi
+  done
+  shopt -u nullglob
+
+  if [[ $count -eq 0 ]]; then
+    echo "  (No voices downloaded yet)"
+  fi
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "Total: $count voices"
+}
+
+# AI NOTE: This file manages the lifecycle of Piper voice models
+# Voice models are ONNX files (~20-30MB each) downloaded from HuggingFace
+# Files are cached locally to avoid repeated downloads
+# Project-local storage preferred over global for isolation