agentvibes 2.5.0 → 2.7.0

package/.claude/commands/bmad/bmm/workflows/create-ux-design.md

@@ -0,0 +1,13 @@
+---
+description: 'Collaborative UX design facilitation workflow that creates exceptional user experiences through visual exploration and informed decision-making. Unlike template-driven approaches, this workflow facilitates discovery, generates visual options, and collaboratively designs the UX with the user at every step.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/create-wireframe.md

@@ -0,0 +1,13 @@
+---
+description: 'Create website or app wireframes in Excalidraw format'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/frame-expert/create-wireframe/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/frame-expert/create-wireframe/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/dev-story.md

@@ -0,0 +1,13 @@
+---
+description: 'Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/document-project.md

@@ -0,0 +1,13 @@
+---
+description: 'Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/document-project/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/document-project/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/domain-research.md

@@ -0,0 +1,13 @@
+---
+description: 'Collaborative exploration of domain-specific requirements, regulations, and patterns for complex projects'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/1-analysis/domain-research/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/1-analysis/domain-research/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/epic-tech-context.md

@@ -0,0 +1,13 @@
+---
+description: 'Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/implementation-readiness.md

@@ -0,0 +1,13 @@
+---
+description: 'Validate that PRD, UX Design, Architecture, Epics and Stories are complete and aligned before Phase 4 implementation. Ensures all artifacts cover the MVP requirements with no gaps or contradictions.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/3-solutioning/implementation-readiness/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/3-solutioning/implementation-readiness/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/prd.md

@@ -0,0 +1,13 @@
+---
+description: 'Unified PRD workflow for BMad Method and Enterprise Method tracks. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Quick Flow track uses tech-spec workflow.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/product-brief.md

@@ -0,0 +1,13 @@
+---
+description: 'Interactive product brief creation workflow that guides users through defining their product vision with multiple input sources and conversational collaboration'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/research.md

@@ -0,0 +1,13 @@
+---
+description: 'Adaptive research workflow supporting multiple research types: market research, deep research prompt generation, technical/architecture evaluation, competitive intelligence, user research, and domain analysis'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/1-analysis/research/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/1-analysis/research/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/retrospective.md

@@ -0,0 +1,13 @@
+---
+description: 'Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/sprint-planning.md

@@ -0,0 +1,13 @@
+---
+description: 'Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/story-context.md

@@ -0,0 +1,13 @@
+---
+description: 'Assemble a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/4-implementation/story-context/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/4-implementation/story-context/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/story-done.md

@@ -0,0 +1,13 @@
+---
+description: 'Marks a story as done (DoD complete) and moves it from its current status → DONE in the status file. Advances the story queue. Simple status-update workflow with no searching required.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/4-implementation/story-done/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/4-implementation/story-done/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/story-ready.md

@@ -0,0 +1,13 @@
+---
+description: 'Marks a drafted story as ready for development and moves it from TODO → IN PROGRESS in the status file. Simple status-update workflow with no searching required.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/4-implementation/story-ready/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/4-implementation/story-ready/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/tech-spec.md

@@ -0,0 +1,13 @@
+---
+description: 'Technical specification workflow for quick-flow projects. Creates focused tech spec and generates epic + stories (1 story for simple changes, 2-5 stories for features). Tech-spec only - no PRD needed.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/workflow-init.md

@@ -0,0 +1,13 @@
+---
+description: 'Initialize a new BMM project by determining level, type, and creating workflow path'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/workflow-status/init/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/workflow-status/init/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/bmm/workflows/workflow-status.md

@@ -0,0 +1,13 @@
+---
+description: 'Lightweight status checker - answers "what should I do now?" for any agent. Reads YAML status file for workflow tracking. Use workflow-init for new projects.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/bmm/workflows/workflow-status/workflow.yaml
+3. Pass the yaml path .bmad/bmm/workflows/workflow-status/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/core/agents/bmad-master.md

@@ -0,0 +1,14 @@
+---
+name: 'bmad-master'
+description: 'bmad-master agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @.bmad/core/agents/bmad-master.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

package/.claude/commands/bmad/core/tasks/advanced-elicitation.md

@@ -0,0 +1,9 @@
+---
+description: 'When called from workflow'
+---
+
+# Advanced Elicitation
+
+LOAD and execute the task at: .bmad/core/tasks/advanced-elicitation.xml
+
+Follow all instructions in the task file exactly as written.

package/.claude/commands/bmad/core/tasks/index-docs.md

@@ -0,0 +1,9 @@
+---
+description: 'Generates or updates an index.md of all documents in the specified directory'
+---
+
+# Index Docs
+
+LOAD and execute the task at: .bmad/core/tasks/index-docs.xml
+
+Follow all instructions in the task file exactly as written.

package/.claude/commands/bmad/core/tools/shard-doc.md

@@ -0,0 +1,9 @@
+---
+description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections'
+---
+
+# Shard Document
+
+LOAD and execute the tool at: .bmad/core/tools/shard-doc.xml
+
+Follow all instructions in the tool file exactly as written.

package/.claude/commands/bmad/core/workflows/brainstorming.md

@@ -0,0 +1,13 @@
+---
+description: 'Facilitate interactive brainstorming sessions using diverse creative techniques. This workflow facilitates interactive brainstorming sessions using diverse creative techniques. The session is highly interactive, with the AI acting as a facilitator to guide the user through various ideation methods to generate and refine creative solutions.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/core/workflows/brainstorming/workflow.yaml
+3. Pass the yaml path .bmad/core/workflows/brainstorming/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/commands/bmad/core/workflows/party-mode.md

@@ -0,0 +1,13 @@
+---
+description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @.bmad/core/workflows/party-mode/workflow.yaml
+3. Pass the yaml path .bmad/core/workflows/party-mode/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20251116
+20251118

package/.claude/hooks/README-TTS-QUEUE.md

@@ -0,0 +1,135 @@
+# TTS Queue System for Party Mode
+
+## Overview
+
+The TTS Queue System enables BMAD party mode agents to speak sequentially without blocking Claude Code's response generation. This provides the best of both worlds:
+
+- ✅ **Non-blocking**: Claude Code continues generating agent responses immediately
+- ✅ **Sequential playback**: Agents speak one at a time in order, with correct voices
+- ✅ **No audio overlap**: The queue ensures voices don't talk over each other
+
+## How It Works
+
+### Architecture
+
+```
+bmad-speak.sh → tts-queue.sh → Queue Directory → tts-queue-worker.sh → play-tts.sh → Audio
+     ↓               ↓                                       ↓
+  Returns        Returns                              Processes queue
+immediately    immediately                            sequentially
+```
+
+### Components
+
+1. **`tts-queue.sh`** - Queue manager (adds requests, shows status, clears queue)
+2. **`tts-queue-worker.sh`** - Background worker process (plays audio sequentially)
+3. **`bmad-speak.sh`** - Updated to use queue system with `&` for non-blocking
+4. **Queue directory**: `/tmp/agentvibes-tts-queue/` - Stores pending TTS requests
+
+### Flow
+
+1. Party mode agent generates response
+2. `bmad-speak.sh` adds TTS request to queue and returns immediately (`&`)
+3. Queue worker automatically starts if needed
+4. Worker processes queue items sequentially (oldest first)
+5. Each audio file plays to completion before next one starts
+6. Worker auto-exits after 5 seconds of idle time
+
+## Usage
+
+### Normal Usage (Automatic)
+
+Party mode automatically uses the queue system. No manual intervention needed.
+
+### Manual Queue Management
+
+```bash
+# Check queue status
+bash .claude/hooks/tts-queue.sh status
+
+# Clear all pending TTS (emergency stop)
+bash .claude/hooks/tts-queue.sh clear
+
+# Manually add to queue
+bash .claude/hooks/tts-queue.sh add "Hello world" "en_US-ryan-high"
+```
+
+## Performance Benefits
+
+### Before (Sequential Blocking):
+```
+Agent 1 text output → [WAIT 3s for audio] → Agent 2 text → [WAIT 3s] → Agent 3 text
+Total time: ~9+ seconds
+```
+
+### After (Queue System):
+```
+Agent 1 text → Agent 2 text → Agent 3 text (all immediate)
+                         ↓
+            [Audio plays sequentially in background]
+Total text output time: <1 second
+Total audio time: ~9 seconds (plays while Claude continues working)
+```
+
+## Technical Details
+
+### Queue File Format
+
+Each queue item is a timestamped file containing escaped bash variables:
+
+```bash
+TEXT='First\ message\ from\ John'
+VOICE='en_US-ryan-high'
+```
+
+### Worker Lifecycle
+
+- **Start**: Automatically launched when first item added to empty queue
+- **Processing**: Continues while queue has items
+- **Idle timeout**: Exits after 5 seconds with no new items
+- **Auto-restart**: Next queue addition spawns new worker
+
+### Thread Safety
+
+- Queue items use nanosecond timestamps for uniqueness
+- Worker processes oldest items first (sorted by filename)
+- Audio lock mechanism in `play-tts.sh` prevents actual audio overlap
+- Worker PID tracked in `/tmp/agentvibes-tts-queue/worker.pid`
+
+## Troubleshooting
+
+### Queue stuck or voices not playing
+
+```bash
+# Check status
+bash .claude/hooks/tts-queue.sh status
+
+# Clear queue and restart
+bash .claude/hooks/tts-queue.sh clear
+```
+
+### Worker not starting
+
+Check for errors in the worker script:
+```bash
+bash .claude/hooks/tts-queue-worker.sh
+```
+
+### Audio still overlapping
+
+Verify the lock file mechanism is working:
+```bash
+ls -la /tmp/agentvibes-audio.lock
+```
+
+## Files Modified
+
+- `.claude/hooks/bmad-speak.sh` - Now uses queue system with `&` for non-blocking
+- `.claude/hooks/tts-queue.sh` - New queue manager (added)
+- `.claude/hooks/tts-queue-worker.sh` - New background worker (added)
+
+## Compatibility
+
+- Works with both Piper and ElevenLabs TTS providers
+- Compatible with all existing BMAD voice mappings
+- No changes needed to party mode workflow instructions