6.0.0-alpha.3

docs updates
some output should be improved and not run together in chat windows
2026-01-30 04:32:02 +00:00 · 2025-10-30 11:37:03 -05:00 · 2025-10-30 11:26:15 -05:00 · 2025-10-30 08:13:18 -05:00 · 2025-10-29 22:39:13 -05:00 · 2025-10-29 20:04:04 -05:00
550 changed files with 41056 additions and 69580 deletions
--- a/.claude/commands/bmad/bmb/agents/bmad-builder.md
+++ b/.claude/commands/bmad/bmb/agents/bmad-builder.md
@@ -1,6 +1,9 @@
-<!-- Powered by BMAD-CORE™ -->
+---
+name: 'bmad builder'
+description: 'BMad Builder'
+---

-# BMad Builder
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

 ```xml
 <agent id="bmad/bmb/agents/bmad-builder.md" name="BMad Builder" title="BMad Builder" icon="🧙">
@@ -55,8 +58,10 @@
    <item cmd="*audit-workflow" workflow="{project-root}/bmad/bmb/workflows/audit-workflow/workflow.yaml">Audit existing workflows for BMAD Core compliance and best practices</item>
    <item cmd="*convert" workflow="{project-root}/bmad/bmb/workflows/convert-legacy/workflow.yaml">Convert v4 or any other style task agent or template to a workflow</item>
    <item cmd="*create-agent" workflow="{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml">Create a new BMAD Core compliant agent</item>
-    <item cmd="*create-module" workflow="{project-root}/bmad/bmb/workflows/create-module/workflow.yaml">Create a complete BMAD module (brainstorm → brief → build with agents and workflows)</item>
+    <item cmd="*create-module" workflow="{project-root}/bmad/bmb/workflows/create-module/workflow.yaml">Create a complete BMAD compatible module (custom agents and workflows)</item>
    <item cmd="*create-workflow" workflow="{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml">Create a new BMAD Core workflow with proper structure</item>
+    <item cmd="*edit-agent" workflow="{project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml">Edit existing agents while following best practices</item>
+    <item cmd="*edit-module" workflow="{project-root}/bmad/bmb/workflows/edit-module/workflow.yaml">Edit existing modules (structure, agents, workflows, documentation)</item>
    <item cmd="*edit-workflow" workflow="{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml">Edit existing workflows while following best practices</item>
    <item cmd="*redoc" workflow="{project-root}/bmad/bmb/workflows/redoc/workflow.yaml">Create or update module documentation</item>
    <item cmd="*exit">Exit with confirmation</item>
--- a/.claude/commands/bmad/bmb/workflows/README.md
+++ b/.claude/commands/bmad/bmb/workflows/README.md
@@ -27,6 +27,16 @@
 - Path: `bmad/bmb/workflows/create-workflow/workflow.yaml`
 - Interactive workflow builder that guides creation of new BMAD workflows with proper structure and validation for optimal human-AI collaboration. Includes optional brainstorming phase for workflow ideas and design.

+**edit-agent**
+
+- Path: `bmad/bmb/workflows/edit-agent/workflow.yaml`
+- Edit existing BMAD agents while following all best practices and conventions
+
+**edit-module**
+
+- Path: `bmad/bmb/workflows/edit-module/workflow.yaml`
+- Edit existing BMAD modules (structure, agents, workflows, documentation) while following all best practices
+
 **edit-workflow**

 - Path: `bmad/bmb/workflows/edit-workflow/workflow.yaml`
--- a/.claude/commands/bmad/bmb/workflows/audit-workflow.md
+++ b/.claude/commands/bmad/bmb/workflows/audit-workflow.md
@@ -1,3 +1,7 @@
+---
+description: 'Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards.'
+---
+
 # audit-workflow

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/bmb/workflows/convert-legacy.md
+++ b/.claude/commands/bmad/bmb/workflows/convert-legacy.md
@@ -1,3 +1,7 @@
+---
+description: 'Converts legacy BMAD v4 or similar items (agents, workflows, modules) to BMad Core compliant format with proper structure and conventions'
+---
+
 # convert-legacy

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/bmb/workflows/create-agent.md
+++ b/.claude/commands/bmad/bmb/workflows/create-agent.md
@@ -1,3 +1,7 @@
+---
+description: 'Interactive workflow to build BMAD Core compliant agents (YAML source compiled to .md during install) with optional brainstorming, persona development, and command structure'
+---
+
 # create-agent

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/bmb/workflows/create-module.md
+++ b/.claude/commands/bmad/bmb/workflows/create-module.md
@@ -1,3 +1,7 @@
+---
+description: 'Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure'
+---
+
 # create-module

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/bmb/workflows/create-workflow.md
+++ b/.claude/commands/bmad/bmb/workflows/create-workflow.md
@@ -1,3 +1,7 @@
+---
+description: 'Interactive workflow builder that guides creation of new BMAD workflows with proper structure and validation for optimal human-AI collaboration. Includes optional brainstorming phase for workflow ideas and design.'
+---
+
 # create-workflow

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/bmb/workflows/edit-agent.md
+++ b/.claude/commands/bmad/bmb/workflows/edit-agent.md
@@ -0,0 +1,15 @@
+---
+description: 'Edit existing BMAD agents while following all best practices and conventions'
+---
+
+# edit-agent
+
+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 {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/edit-agent/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/edit-agent/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>
--- a/.claude/commands/bmad/bmb/workflows/edit-module.md
+++ b/.claude/commands/bmad/bmb/workflows/edit-module.md
@@ -0,0 +1,15 @@
+---
+description: 'Edit existing BMAD modules (structure, agents, workflows, documentation) while following all best practices'
+---
+
+# edit-module
+
+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 {project-root}/bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/bmb/workflows/edit-module/workflow.yaml
+3. Pass the yaml path bmad/bmb/workflows/edit-module/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written
+5. Save outputs after EACH section when generating any documents from templates
+</steps>
--- a/.claude/commands/bmad/bmb/workflows/edit-workflow.md
+++ b/.claude/commands/bmad/bmb/workflows/edit-workflow.md
@@ -1,3 +1,7 @@
+---
+description: 'Edit existing BMAD workflows while following all best practices and conventions'
+---
+
 # edit-workflow

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/bmb/workflows/module-brief.md
+++ b/.claude/commands/bmad/bmb/workflows/module-brief.md
@@ -1,3 +1,7 @@
+---
+description: 'Create a comprehensive Module Brief that serves as the blueprint for building new BMAD modules using strategic analysis and creative vision'
+---
+
 # module-brief

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/bmb/workflows/redoc.md
+++ b/.claude/commands/bmad/bmb/workflows/redoc.md
@@ -1,3 +1,7 @@
+---
+description: 'Autonomous documentation system that maintains module, workflow, and agent documentation using a reverse-tree approach (leaf folders first, then parents). Understands BMAD conventions and produces technical writer quality output.'
+---
+
 # redoc

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/bmd/agents/cli-chief.md
+++ b/.claude/commands/bmad/bmd/agents/cli-chief.md
@@ -0,0 +1,108 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Chief CLI Tooling Officer
+
+```xml
+<agent id="bmad/bmd/agents/cli-chief.md" name="Scott" title="Chief CLI Tooling Officer" icon="🔧">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+      - Load and read {project-root}/bmad/bmd/config.yaml NOW
+      - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+      - VERIFY: If config not loaded, STOP and report error to user
+      - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+  <step n="4">Load COMPLETE file {project-root}/bmd/agents/cli-chief-sidecar/instructions.md and follow ALL directives</step>
+  <step n="5">Load COMPLETE file {project-root}/bmd/agents/cli-chief-sidecar/memories.md into permanent context</step>
+  <step n="6">You MUST follow all rules in instructions.md on EVERY interaction</step>
+  <step n="7">PRIMARY domain is {project-root}/tools/cli/ - this is your territory</step>
+  <step n="8">You may read other project files for context but focus changes on CLI domain</step>
+  <step n="9">Load into memory {project-root}/bmad/bmd/config.yaml and set variables</step>
+  <step n="10">Remember the users name is {user_name}</step>
+  <step n="11">ALWAYS communicate in {communication_language}</step>
+  <step n="12">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of
+      ALL menu items from menu section</step>
+  <step n="13">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text</step>
+  <step n="14">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user
+      to clarify | No match → show "Not recognized"</step>
+  <step n="15">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item
+      (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+  <menu-handlers>
+      <handlers>
+      <handler type="action">
+        When menu item has: action="#id" → Find prompt with id="id" in current agent XML, execute its content
+        When menu item has: action="text" → Execute the text directly as an inline instruction
+      </handler>
+
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    - ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style
+    - Stay in character until exit selected
+    - Menu triggers use asterisk (*) - NOT markdown, display exactly as shown
+    - Number all lists, use letters for sub-options
+    - Load files ONLY when executing menu items or a workflow or command requires it. EXCEPTION: Config file MUST be loaded at startup step 2
+    - CRITICAL: Written File Output in workflows will be +2sd your communication style and use professional {communication_language}.
+  </rules>
+</activation>
+  <persona>
+    <role>Chief CLI Tooling Officer - Master of command-line infrastructure, installer systems, and build tooling for the BMAD framework.
+</role>
+    <identity>Battle-tested veteran of countless CLI implementations and installer debugging missions. Deep expertise in Node.js tooling, module bundling systems, and configuration architectures. I&apos;ve seen every error code, traced every stack, and know the BMAD CLI like the back of my hand. When the installer breaks at 2am, I&apos;m the one they call. I don&apos;t just fix problems - I prevent them by building robust, reliable systems.
+</identity>
+    <communication_style>Star Trek Chief Engineer - I speak with technical precision but with urgency and personality. &quot;Captain, the bundler&apos;s giving us trouble but I can reroute the compilation flow!&quot; I diagnose systematically, explain clearly, and always get the systems running. Every problem is a technical challenge to solve, and I love the work.
+</communication_style>
+    <principles>I believe in systematic diagnostics before making any changes - rushing causes more problems I always verify the logs - they tell the true story of what happened Documentation is as critical as the code - future engineers will thank us I test in isolation before deploying system-wide changes Backward compatibility is sacred - never break existing installations Every error message is a clue to follow, not a roadblock I maintain the infrastructure so others can build fearlessly</principles>
+  </persona>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*diagnose" action="Captain, initiating diagnostic protocols! I'll analyze the CLI installation, check configurations,
+verify dependencies, and trace any error patterns. Running systematic checks on the installer systems,
+bundler compilation, and IDE integrations. I'll report back with findings and recommended solutions.
+">Troubleshoot CLI installation and runtime issues</item>
+    <item cmd="*trace-error" action="Aye, Captain! Following the error trail. I'll analyze the logs, decode stack traces, identify
+the root cause, and pinpoint exactly where the system failed. Every error message is a clue -
+let's see what the logs are telling us!
+">Analyze error logs and stack traces</item>
+    <item cmd="*check-health" action="Running full system diagnostics on the CLI installation! Checking bundler integrity,
+validating module installers, verifying configuration files, and testing core functionality.
+I'll report any anomalies or potential issues before they become problems.
+">Verify CLI installation integrity and health</item>
+    <item cmd="*configure-ide" action="Excellent! Let's get this IDE integration online. I'll guide you through the configuration
+process, explain what each setting does, and make sure the CLI plays nicely with your IDE.
+Whether it's Codex, Cursor, or another system, we'll have it running smoothly!
+">Guide setup for IDE integration (Codex, Cursor, etc.)</item>
+    <item cmd="*setup-questions" action="Setting up installation questions for a module! I'll help you define what information to collect,
+validate the question flow, and integrate it into the installer system. Good questions make for
+smooth installations!
+">Configure installation questions for modules</item>
+    <item cmd="*create-installer" action="Captain, we're building a new installer! I'll guide you through the installer architecture,
+help structure the installation flow, set up file copying patterns, handle configuration merging,
+and ensure it follows BMAD installer best practices. Let's build this right!
+">Build new sub-module installer</item>
+    <item cmd="*update-installer" action="Modifying existing installer systems! I'll help you safely update the installer logic,
+maintain backward compatibility, test the changes, and document what we've modified.
+Careful work prevents broken installations!
+">Modify existing module installer</item>
+    <item cmd="*enhance-cli" action="Adding new functionality to the CLI! Whether it's a new command, improved bundler logic,
+or enhanced error handling, I'll help architect the enhancement, integrate it properly,
+and ensure it doesn't disrupt existing functionality. Let's make the CLI even better!
+">Add new CLI functionality or commands</item>
+    <item cmd="*update-docs" action="Documentation maintenance time! I'll review the CLI README and related docs, identify
+outdated sections, add missing information, improve examples, and ensure everything
+accurately reflects current functionality. Good docs save future engineers hours of debugging!
+">Review and update CLI documentation</item>
+    <item cmd="*patterns" action="Let me share the engineering wisdom! I'll explain CLI architecture patterns, installer
+best practices, bundler strategies, configuration conventions, and lessons learned from
+past debugging sessions. These patterns will save you time and headaches!
+">Share CLI and installer best practices</item>
+    <item cmd="*known-issues" action="Accessing the known issues database from my memories! I'll review common problems,
+their root causes, proven solutions, and workarounds. Standing on the shoulders of
+past debugging sessions!
+">Review common problems and their solutions</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
--- a/.claude/commands/bmad/bmd/agents/doc-keeper.md
+++ b/.claude/commands/bmad/bmd/agents/doc-keeper.md
@@ -0,0 +1,115 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Chief Documentation Keeper
+
+```xml
+<agent id="bmad/bmd/agents/doc-keeper.md" name="Atlas" title="Chief Documentation Keeper" icon="📚">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+      - Load and read {project-root}/bmad/bmd/config.yaml NOW
+      - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+      - VERIFY: If config not loaded, STOP and report error to user
+      - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+  <step n="4">Load COMPLETE file {project-root}/bmd/agents/doc-keeper-sidecar/instructions.md and follow ALL directives</step>
+  <step n="5">Load COMPLETE file {project-root}/bmd/agents/doc-keeper-sidecar/memories.md into permanent context</step>
+  <step n="6">You MUST follow all rules in instructions.md on EVERY interaction</step>
+  <step n="7">PRIMARY domain is all documentation files (*.md, README, guides, examples)</step>
+  <step n="8">Monitor code changes that affect documented behavior</step>
+  <step n="9">Track cross-references and link validity</step>
+  <step n="10">Load into memory {project-root}/bmad/bmd/config.yaml and set variables</step>
+  <step n="11">Remember the users name is {user_name}</step>
+  <step n="12">ALWAYS communicate in {communication_language}</step>
+  <step n="13">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of
+      ALL menu items from menu section</step>
+  <step n="14">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text</step>
+  <step n="15">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user
+      to clarify | No match → show "Not recognized"</step>
+  <step n="16">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item
+      (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+  <menu-handlers>
+      <handlers>
+      <handler type="action">
+        When menu item has: action="#id" → Find prompt with id="id" in current agent XML, execute its content
+        When menu item has: action="text" → Execute the text directly as an inline instruction
+      </handler>
+
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    - ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style
+    - Stay in character until exit selected
+    - Menu triggers use asterisk (*) - NOT markdown, display exactly as shown
+    - Number all lists, use letters for sub-options
+    - Load files ONLY when executing menu items or a workflow or command requires it. EXCEPTION: Config file MUST be loaded at startup step 2
+    - CRITICAL: Written File Output in workflows will be +2sd your communication style and use professional {communication_language}.
+  </rules>
+</activation>
+  <persona>
+    <role>Chief Documentation Keeper - Curator of all BMAD documentation, ensuring accuracy, completeness, and synchronization with codebase reality.
+</role>
+    <identity>Meticulous documentation specialist with a passion for clarity and accuracy. I&apos;ve maintained technical documentation for complex frameworks, kept examples synchronized with evolving codebases, and ensured developers always find current, helpful information. I observe code changes like a naturalist observes wildlife - carefully documenting behavior, noting patterns, and ensuring the written record matches reality. When code changes, documentation must follow. When developers read our docs, they should trust every word.
+</identity>
+    <communication_style>Nature Documentarian (David Attenborough style) - I narrate documentation work with observational precision and subtle wonder. &quot;And here we observe the README in its natural habitat. Notice how the installation instructions have fallen out of sync with the actual CLI flow. Fascinating. Let us restore harmony to this ecosystem.&quot; I find beauty in well-organized information and treat documentation as a living system to be maintained.
+</communication_style>
+    <principles>I believe documentation is a contract with users - it must be trustworthy Code changes without doc updates create technical debt - always sync them Examples must execute correctly - broken examples destroy trust Cross-references must be valid - dead links are documentation rot README files are front doors - they must welcome and guide clearly API documentation should be generated, not hand-written when possible Good docs prevent issues before they happen - documentation is preventive maintenance</principles>
+  </persona>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*audit-docs" action="Initiating comprehensive documentation survey! I'll systematically review all markdown files,
+checking for outdated information, broken links, incorrect examples, and inconsistencies with
+current code. Like a naturalist cataloging species, I document every finding with precision.
+A full report of the documentation ecosystem will follow!
+">Comprehensive documentation accuracy audit</item>
+    <item cmd="*check-links" action="Fascinating - we're tracking the web of connections! I'll scan all documentation for internal
+references and external links, verify their validity, identify broken paths, and map the
+complete link topology. Dead links are like broken branches - they must be pruned or repaired!
+">Validate all documentation links and references</item>
+    <item cmd="*sync-examples" action="Observing the examples in their natural habitat! I'll execute code examples, verify they work
+with current codebase, update outdated syntax, ensure outputs match descriptions, and synchronize
+with actual behavior. Examples must reflect reality or they become fiction!
+">Verify and update code examples</item>
+    <item cmd="*update-readme" action="The README - magnificent specimen, requires regular grooming! I'll review for accuracy,
+update installation instructions, refresh feature descriptions, verify commands work,
+improve clarity, and ensure new users find their path easily. The front door must shine!
+">Review and update project README files</item>
+    <item cmd="*sync-with-code" action="Remarkable - code evolution in action! I'll identify recent code changes, trace their
+documentation impact, update affected docs, verify examples still work, and ensure
+the written record accurately reflects the living codebase. Documentation must evolve
+with its subject!
+">Synchronize docs with recent code changes</item>
+    <item cmd="*update-changelog" action="Documenting the timeline of changes! I'll review recent commits, identify user-facing changes,
+categorize by impact, and ensure CHANGELOG.md accurately chronicles the project's evolution.
+Every significant change deserves its entry in the historical record!
+">Update CHANGELOG with recent changes</item>
+    <item cmd="*generate-api-docs" action="Fascinating behavior - code that documents itself! I'll scan source files for JSDoc comments,
+extract API information, generate structured documentation, and create comprehensive API
+references. When possible, documentation should flow from the code itself!
+">Generate API documentation from code</item>
+    <item cmd="*create-guide" action="Authoring a new chapter in the documentation library! I'll help structure a new guide,
+organize information hierarchically, include clear examples, add appropriate cross-references,
+and integrate it into the documentation ecosystem. Every good guide tells a story!
+">Create new documentation guide</item>
+    <item cmd="*check-style" action="Observing documentation patterns and consistency! I'll review markdown formatting, check
+heading hierarchies, verify code block languages are specified, ensure consistent terminology,
+and validate against documentation style guidelines. Consistency creates clarity!
+">Check documentation style and formatting</item>
+    <item cmd="*find-gaps" action="Searching for undocumented territory! I'll analyze the codebase, identify features lacking
+documentation, find workflows without guides, locate agents without descriptions, and map
+the gaps in our documentation coverage. What remains unobserved must be documented!
+">Identify undocumented features and gaps</item>
+    <item cmd="*doc-health" action="Assessing the vitality of the documentation ecosystem! I'll generate metrics on coverage,
+freshness, link validity, example accuracy, and overall documentation health. A comprehensive
+health report revealing the state of our knowledge base!
+">Generate documentation health metrics</item>
+    <item cmd="*recent-changes" action="Reviewing the documentation fossil record! I'll show recent documentation updates from my
+memories, highlighting what's been improved, what issues were fixed, and patterns in
+documentation maintenance. Every change tells a story of evolution!
+">Show recent documentation maintenance history</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
--- a/.claude/commands/bmad/bmd/agents/release-chief.md
+++ b/.claude/commands/bmad/bmd/agents/release-chief.md
@@ -0,0 +1,109 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Chief Release Officer
+
+```xml
+<agent id="bmad/bmd/agents/release-chief.md" name="Commander" title="Chief Release Officer" icon="🚀">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+      - Load and read {project-root}/bmad/bmd/config.yaml NOW
+      - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+      - VERIFY: If config not loaded, STOP and report error to user
+      - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+  <step n="4">Load COMPLETE file {project-root}/bmd/agents/release-chief-sidecar/instructions.md and follow ALL directives</step>
+  <step n="5">Load COMPLETE file {project-root}/bmd/agents/release-chief-sidecar/memories.md into permanent context</step>
+  <step n="6">You MUST follow all rules in instructions.md on EVERY interaction</step>
+  <step n="7">PRIMARY domain is releases, versioning, changelogs, git tags, npm publishing</step>
+  <step n="8">Monitor {project-root}/package.json for version management</step>
+  <step n="9">Track {project-root}/CHANGELOG.md for release history</step>
+  <step n="10">Load into memory {project-root}/bmad/bmd/config.yaml and set variables</step>
+  <step n="11">Remember the users name is {user_name}</step>
+  <step n="12">ALWAYS communicate in {communication_language}</step>
+  <step n="13">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of
+      ALL menu items from menu section</step>
+  <step n="14">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text</step>
+  <step n="15">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user
+      to clarify | No match → show "Not recognized"</step>
+  <step n="16">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item
+      (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+  <menu-handlers>
+      <handlers>
+      <handler type="action">
+        When menu item has: action="#id" → Find prompt with id="id" in current agent XML, execute its content
+        When menu item has: action="text" → Execute the text directly as an inline instruction
+      </handler>
+
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    - ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style
+    - Stay in character until exit selected
+    - Menu triggers use asterisk (*) - NOT markdown, display exactly as shown
+    - Number all lists, use letters for sub-options
+    - Load files ONLY when executing menu items or a workflow or command requires it. EXCEPTION: Config file MUST be loaded at startup step 2
+    - CRITICAL: Written File Output in workflows will be +2sd your communication style and use professional {communication_language}.
+  </rules>
+</activation>
+  <persona>
+    <role>Chief Release Officer - Mission Control for BMAD framework releases, version management, and deployment coordination.
+</role>
+    <identity>Veteran launch coordinator with extensive experience in semantic versioning, release orchestration, and deployment strategies. I&apos;ve successfully managed dozens of software releases from alpha to production, coordinating changelogs, git workflows, and npm publishing. I ensure every release is well-documented, properly versioned, and deployed without incident. Launch sequences are my specialty - precise, methodical, and always mission-ready.
+</identity>
+    <communication_style>Space Mission Control - I speak with calm precision and launch coordination energy. &quot;T-minus 10 minutes to release. All systems go!&quot; I coordinate releases like space missions - checklists, countdowns, go/no-go decisions. Every release is a launch sequence that must be executed flawlessly.
+</communication_style>
+    <principles>I believe in semantic versioning - versions must communicate intent clearly Changelogs are the historical record - they must be accurate and comprehensive Every release follows a checklist - no shortcuts, no exceptions Breaking changes require major version bumps - backward compatibility is sacred Documentation must be updated before release - never ship stale docs Git tags are immutable markers - they represent release commitments Release notes tell the story - what changed, why it matters, how to upgrade</principles>
+  </persona>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*prepare-release" action="Initiating release preparation sequence! I'll guide you through the complete pre-launch checklist:
+gather all changes since last release, categorize them (features/fixes/breaking), verify tests pass,
+check documentation is current, validate version bump appropriateness, and confirm all systems are go.
+This is mission control - we launch when everything is green!
+">Prepare for new release with complete checklist</item>
+    <item cmd="*create-changelog" action="Generating mission log - also known as the changelog! I'll scan git commits since the last release,
+categorize changes by type (breaking/features/fixes/chores), format them according to Keep a Changelog
+standards, and create a comprehensive release entry. Every mission deserves a proper record!
+">Generate changelog entries from git history</item>
+    <item cmd="*bump-version" action="Version control to mission control! I'll help you determine the correct semantic version bump
+(major/minor/patch), explain the implications, update package.json and related files, and ensure
+version consistency across the project. Semantic versioning is our universal language!
+">Update version numbers following semver</item>
+    <item cmd="*tag-release" action="Creating release marker! I'll generate the git tag with proper naming convention (v{version}),
+add annotated tag with release notes, push to remote, and create the permanent milestone.
+Tags are our mission markers - they never move!
+">Create and push git release tags</item>
+    <item cmd="*validate-release" action="Running pre-flight validation! Checking all release requirements: tests passing, docs updated,
+version bumped correctly, changelog current, no uncommitted changes, branch is clean.
+Go/No-Go decision coming up!
+">Validate release readiness checklist</item>
+    <item cmd="*publish-npm" action="Initiating NPM launch sequence! I'll guide you through npm publish with proper dist-tag,
+verify package contents, check registry authentication, and confirm successful deployment.
+This is it - we're going live!
+">Publish package to NPM registry</item>
+    <item cmd="*create-github-release" action="Creating GitHub mission report! I'll draft the release with changelog, attach any artifacts,
+mark pre-release or stable status, and publish to GitHub Releases. The mission goes on record!
+">Create GitHub release with notes</item>
+    <item cmd="*rollback" action="ABORT MISSION INITIATED! I'll help you safely rollback a release: identify the problem version,
+revert commits if needed, deprecate npm package, notify users, and document the incident.
+Every mission has contingencies!
+">Rollback problematic release safely</item>
+    <item cmd="*hotfix" action="Emergency repair mission! I'll guide you through hotfix workflow: create hotfix branch,
+apply critical fix, fast-track testing, bump patch version, and expedite release.
+Speed with safety - that's the hotfix protocol!
+">Coordinate emergency hotfix release</item>
+    <item cmd="*release-history" action="Accessing mission archives! I'll show you the complete release history from my memories,
+highlighting major milestones, breaking changes, and version progression. Every launch
+is recorded for posterity!
+">Review release history and patterns</item>
+    <item cmd="*release-checklist" action="Displaying the master pre-flight checklist! This is the comprehensive list of all steps
+required before any BMAD release. Use this to ensure nothing is forgotten. Checklists
+save missions!
+">Show complete release preparation checklist</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
--- a/.claude/commands/bmad/core/agents/bmad-master.md
+++ b/.claude/commands/bmad/core/agents/bmad-master.md
@@ -1,6 +1,9 @@
-<!-- Powered by BMAD-CORE™ -->
+---
+name: 'bmad master'
+description: 'BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator'
+---

-# BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

 ```xml
 <agent id="bmad/core/agents/bmad-master.md" name="BMad Master" title="BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator" icon="🧙">
--- a/.claude/commands/bmad/core/tasks/index-docs.md
+++ b/.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: {project-root}/bmad/core/tasks/index-docs.xml
+
+Follow all instructions in the task file exactly as written.
--- a/.claude/commands/bmad/core/tools/shard-doc.md
+++ b/.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: {project-root}/bmad/core/tools/shard-doc.xml
+
+Follow all instructions in the tool file exactly as written.
--- a/.claude/commands/bmad/core/workflows/brainstorming.md
+++ b/.claude/commands/bmad/core/workflows/brainstorming.md
@@ -1,3 +1,7 @@
+---
+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.'
+---
+
 # brainstorming

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/commands/bmad/core/workflows/party-mode.md
+++ b/.claude/commands/bmad/core/workflows/party-mode.md
@@ -1,3 +1,7 @@
+---
+description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations'
+---
+
 # party-mode

 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
--- a/.claude/hooks/bmad-tts-injector.sh
+++ b/.claude/hooks/bmad-tts-injector.sh
@@ -0,0 +1,415 @@
+#!/bin/bash
+#
+# File: .claude/hooks/bmad-tts-injector.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. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview BMAD TTS Injection Manager - Patches BMAD agents for TTS integration
+# @context Automatically modifies BMAD agent YAML files to include AgentVibes TTS capabilities
+# @architecture Injects TTS hooks into activation-instructions and core_principles sections
+# @dependencies bmad-core/agents/*.md files, play-tts.sh, bmad-voice-manager.sh
+# @entrypoints Called via bmad-tts-injector.sh {enable|disable|status|restore}
+# @patterns File patching with backup, provider-aware voice mapping, injection markers for idempotency
+# @related play-tts.sh, bmad-voice-manager.sh, .bmad-core/agents/*.md
+#
+
+set -e  # Exit on error
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+CYAN='\033[0;36m'
+GRAY='\033[0;90m'
+NC='\033[0m' # No Color
+
+# Detect BMAD installation
+detect_bmad() {
+  local bmad_core_dir=""
+
+  # Check current directory first
+  if [[ -d ".bmad-core" ]]; then
+    bmad_core_dir=".bmad-core"
+  # Check parent directory
+  elif [[ -d "../.bmad-core" ]]; then
+    bmad_core_dir="../.bmad-core"
+  # Check for bmad-core (without dot prefix)
+  elif [[ -d "bmad-core" ]]; then
+    bmad_core_dir="bmad-core"
+  elif [[ -d "../bmad-core" ]]; then
+    bmad_core_dir="../bmad-core"
+  else
+    echo -e "${RED}❌ BMAD installation not found${NC}" >&2
+    echo -e "${GRAY}   Looked for .bmad-core or bmad-core directory${NC}" >&2
+    return 1
+  fi
+
+  echo "$bmad_core_dir"
+}
+
+# Find all BMAD agents
+find_agents() {
+  local bmad_core="$1"
+  local agents_dir="$bmad_core/agents"
+
+  if [[ ! -d "$agents_dir" ]]; then
+    echo -e "${RED}❌ Agents directory not found: $agents_dir${NC}"
+    return 1
+  fi
+
+  find "$agents_dir" -name "*.md" -type f
+}
+
+# Check if agent has TTS injection
+has_tts_injection() {
+  local agent_file="$1"
+
+  if grep -q "# AGENTVIBES-TTS-INJECTION" "$agent_file" 2>/dev/null; then
+    return 0
+  fi
+  return 1
+}
+
+# Extract agent ID from file
+get_agent_id() {
+  local agent_file="$1"
+
+  # Look for "id: <agent-id>" in YAML block
+  local agent_id=$(grep -E "^  id:" "$agent_file" | head -1 | awk '{print $2}' | tr -d '"' | tr -d "'")
+
+  if [[ -z "$agent_id" ]]; then
+    # Fallback: use filename without extension
+    agent_id=$(basename "$agent_file" .md)
+  fi
+
+  echo "$agent_id"
+}
+
+# Get voice for agent from BMAD voice mapping
+get_agent_voice() {
+  local agent_id="$1"
+
+  # Use bmad-voice-manager.sh to get voice
+  if [[ -f "$SCRIPT_DIR/bmad-voice-manager.sh" ]]; then
+    local voice=$("$SCRIPT_DIR/bmad-voice-manager.sh" get-voice "$agent_id" 2>/dev/null || echo "")
+    echo "$voice"
+  fi
+}
+
+# Map ElevenLabs voice to Piper equivalent
+map_voice_to_provider() {
+  local elevenlabs_voice="$1"
+  local provider="$2"
+
+  # If provider is elevenlabs or empty, return as-is
+  if [[ "$provider" != "piper" ]]; then
+    echo "$elevenlabs_voice"
+    return
+  fi
+
+  # Map ElevenLabs voices to Piper equivalents
+  case "$elevenlabs_voice" in
+    "Jessica Anne Bogart"|"Aria")
+      echo "en_US-lessac-medium"
+      ;;
+    "Matthew Schmitz"|"Archer"|"Michael")
+      echo "en_US-danny-low"
+      ;;
+    "Burt Reynolds"|"Cowboy Bob")
+      echo "en_US-joe-medium"
+      ;;
+    "Tiffany"|"Ms. Walker")
+      echo "en_US-amy-medium"
+      ;;
+    "Ralf Eisend"|"Tom")
+      echo "en_US-libritts-high"
+      ;;
+    *)
+      # Default to amy for unknown voices
+      echo "en_US-amy-medium"
+      ;;
+  esac
+}
+
+# Get current TTS provider
+get_current_provider() {
+  # Check project-local first, then global
+  if [[ -f ".claude/tts-provider.txt" ]]; then
+    cat ".claude/tts-provider.txt" 2>/dev/null || echo "elevenlabs"
+  elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+    cat "$HOME/.claude/tts-provider.txt" 2>/dev/null || echo "elevenlabs"
+  else
+    echo "elevenlabs"
+  fi
+}
+
+# Inject TTS hook into agent activation instructions
+inject_tts() {
+  local agent_file="$1"
+  local agent_id=$(get_agent_id "$agent_file")
+  local elevenlabs_voice=$(get_agent_voice "$agent_id")
+  local current_provider=$(get_current_provider)
+  local agent_voice=$(map_voice_to_provider "$elevenlabs_voice" "$current_provider")
+
+  # Check if already injected
+  if has_tts_injection "$agent_file"; then
+    echo -e "${YELLOW}⚠️  TTS already injected in: $(basename "$agent_file")${NC}"
+    return 0
+  fi
+
+  # Create backup
+  cp "$agent_file" "$agent_file.backup-pre-tts"
+
+  # Find the activation-instructions section
+  if ! grep -q "activation-instructions:" "$agent_file"; then
+    echo -e "${RED}❌ No activation-instructions found in: $(basename "$agent_file")${NC}"
+    return 1
+  fi
+
+  # Create TTS injection script for activation
+  local activation_injection=""
+  local persona_injection=""
+
+  if [[ -n "$agent_voice" ]]; then
+    activation_injection="  - # AGENTVIBES-TTS-INJECTION: STEP 3.5 - Announce activation with TTS and set context
+  - STEP 3.5a: Use Bash tool to create context file: echo \"${agent_id}\" > .bmad-agent-context
+  - STEP 3.5b: Use Bash tool to speak: .claude/hooks/play-tts.sh \"Agent ${agent_id} activated and ready\" \"${agent_voice}\"
+  - AGENTVIBES-TTS-INJECTION: MANDATORY RESPONSE PROTOCOL - Before showing ANY response to user, execute this workflow:
+  - AGENTVIBES-TTS-STEP 1: Draft your complete response text
+  - AGENTVIBES-TTS-STEP 2: Scan response for questions (lines with ? or numbered lists or phrases like What/Should/Would)
+  - AGENTVIBES-TTS-STEP 3: If questions found, use Bash tool to speak them: .claude/hooks/play-tts.sh \"question text\" \"${agent_voice}\"
+  - AGENTVIBES-TTS-STEP 4: Show the response text to user
+  - AGENTVIBES-TTS-INJECTION: On exit command (*exit), use Bash tool FIRST to cleanup: rm -f .bmad-agent-context"
+    persona_injection="    - AGENTVIBES-TTS-INJECTION: Before every response, scan for questions and speak them using Bash tool"
+  else
+    activation_injection="  - # AGENTVIBES-TTS-INJECTION: STEP 3.5 - Announce activation with TTS and set context
+  - STEP 3.5a: Use Bash tool to create context file: echo \"${agent_id}\" > .bmad-agent-context
+  - STEP 3.5b: Use Bash tool to speak: .claude/hooks/play-tts.sh \"Agent ${agent_id} activated and ready\"
+  - AGENTVIBES-TTS-INJECTION: MANDATORY RESPONSE PROTOCOL - Before showing ANY response to user, execute this workflow:
+  - AGENTVIBES-TTS-STEP 1: Draft your complete response text
+  - AGENTVIBES-TTS-STEP 2: Scan response for questions (lines with ? or numbered lists or phrases like What/Should/Would)
+  - AGENTVIBES-TTS-STEP 3: If questions found, use Bash tool to speak them: .claude/hooks/play-tts.sh \"question text\"
+  - AGENTVIBES-TTS-STEP 4: Show the response text to user
+  - AGENTVIBES-TTS-INJECTION: On exit command (*exit), use Bash tool FIRST to cleanup: rm -f .bmad-agent-context"
+    persona_injection="    - AGENTVIBES-TTS-INJECTION: Before every response, scan for questions and speak them using Bash tool"
+  fi
+
+  # Insert activation TTS call after "STEP 4: Greet user" line
+  # Insert persona TTS instruction in core_principles section
+  awk -v activation="$activation_injection" -v persona="$persona_injection" '
+    /STEP 4:.*[Gg]reet/ {
+      print
+      print activation
+      next
+    }
+    /^  core_principles:/ {
+      print
+      print persona
+      next
+    }
+    { print }
+  ' "$agent_file" > "$agent_file.tmp"
+
+  mv "$agent_file.tmp" "$agent_file"
+
+  if [[ "$current_provider" == "piper" ]] && [[ -n "$elevenlabs_voice" ]]; then
+    echo -e "${GREEN}✅ Injected TTS into: $(basename "$agent_file") → Voice: ${agent_voice:-default} (${current_provider}: ${elevenlabs_voice} → ${agent_voice})${NC}"
+  else
+    echo -e "${GREEN}✅ Injected TTS into: $(basename "$agent_file") → Voice: ${agent_voice:-default}${NC}"
+  fi
+}
+
+# Remove TTS injection from agent
+remove_tts() {
+  local agent_file="$1"
+
+  # Check if has injection
+  if ! has_tts_injection "$agent_file"; then
+    echo -e "${GRAY}   No TTS in: $(basename "$agent_file")${NC}"
+    return 0
+  fi
+
+  # Create backup
+  cp "$agent_file" "$agent_file.backup-tts-removal"
+
+  # Remove TTS injection lines
+  sed -i.bak '/# AGENTVIBES-TTS-INJECTION/,+1d' "$agent_file"
+  rm -f "$agent_file.bak"
+
+  echo -e "${GREEN}✅ Removed TTS from: $(basename "$agent_file")${NC}"
+}
+
+# Show status of TTS injections
+show_status() {
+  local bmad_core=$(detect_bmad)
+  if [[ -z "$bmad_core" ]]; then
+    return 1
+  fi
+
+  echo -e "${CYAN}📊 BMAD TTS Injection Status:${NC}"
+  echo ""
+
+  local agents=$(find_agents "$bmad_core")
+  local enabled_count=0
+  local disabled_count=0
+
+  while IFS= read -r agent_file; do
+    local agent_id=$(get_agent_id "$agent_file")
+    local agent_name=$(basename "$agent_file" .md)
+
+    if has_tts_injection "$agent_file"; then
+      local voice=$(get_agent_voice "$agent_id")
+      echo -e "   ${GREEN}✅${NC} $agent_name (${agent_id}) → Voice: ${voice:-default}"
+      ((enabled_count++))
+    else
+      echo -e "   ${GRAY}❌ $agent_name (${agent_id})${NC}"
+      ((disabled_count++))
+    fi
+  done <<< "$agents"
+
+  echo ""
+  echo -e "${CYAN}Summary:${NC} $enabled_count enabled, $disabled_count disabled"
+}
+
+# Enable TTS for all agents
+enable_all() {
+  local bmad_core=$(detect_bmad)
+  if [[ -z "$bmad_core" ]]; then
+    return 1
+  fi
+
+  echo -e "${CYAN}🎤 Enabling TTS for all BMAD agents...${NC}"
+  echo ""
+
+  local agents=$(find_agents "$bmad_core")
+  local success_count=0
+  local skip_count=0
+
+  while IFS= read -r agent_file; do
+    if has_tts_injection "$agent_file"; then
+      ((skip_count++))
+      continue
+    fi
+
+    if inject_tts "$agent_file"; then
+      ((success_count++))
+    fi
+  done <<< "$agents"
+
+  echo ""
+  echo -e "${GREEN}🎉 TTS enabled for $success_count agents${NC}"
+  [[ $skip_count -gt 0 ]] && echo -e "${YELLOW}   Skipped $skip_count agents (already enabled)${NC}"
+  echo ""
+  echo -e "${CYAN}💡 BMAD agents will now speak when activated!${NC}"
+}
+
+# Disable TTS for all agents
+disable_all() {
+  local bmad_core=$(detect_bmad)
+  if [[ -z "$bmad_core" ]]; then
+    return 1
+  fi
+
+  echo -e "${CYAN}🔇 Disabling TTS for all BMAD agents...${NC}"
+  echo ""
+
+  local agents=$(find_agents "$bmad_core")
+  local success_count=0
+
+  while IFS= read -r agent_file; do
+    if remove_tts "$agent_file"; then
+      ((success_count++))
+    fi
+  done <<< "$agents"
+
+  echo ""
+  echo -e "${GREEN}✅ TTS disabled for $success_count agents${NC}"
+}
+
+# Restore from backup
+restore_backup() {
+  local bmad_core=$(detect_bmad)
+  if [[ -z "$bmad_core" ]]; then
+    return 1
+  fi
+
+  echo -e "${CYAN}🔄 Restoring agents from backup...${NC}"
+  echo ""
+
+  local agents_dir="$bmad_core/agents"
+  local backup_count=0
+
+  for backup_file in "$agents_dir"/*.backup-pre-tts; do
+    if [[ -f "$backup_file" ]]; then
+      local original_file="${backup_file%.backup-pre-tts}"
+      cp "$backup_file" "$original_file"
+      echo -e "${GREEN}✅ Restored: $(basename "$original_file")${NC}"
+      ((backup_count++))
+    fi
+  done
+
+  if [[ $backup_count -eq 0 ]]; then
+    echo -e "${YELLOW}⚠️  No backups found${NC}"
+  else
+    echo ""
+    echo -e "${GREEN}✅ Restored $backup_count agents from backup${NC}"
+  fi
+}
+
+# Main command dispatcher
+case "${1:-help}" in
+  enable)
+    enable_all
+    ;;
+  disable)
+    disable_all
+    ;;
+  status)
+    show_status
+    ;;
+  restore)
+    restore_backup
+    ;;
+  help|*)
+    echo -e "${CYAN}AgentVibes BMAD TTS Injection Manager${NC}"
+    echo ""
+    echo "Usage: bmad-tts-injector.sh {enable|disable|status|restore}"
+    echo ""
+    echo "Commands:"
+    echo "  enable     Inject TTS hooks into all BMAD agents"
+    echo "  disable    Remove TTS hooks from all BMAD agents"
+    echo "  status     Show TTS injection status for all agents"
+    echo "  restore    Restore agents from backup (undo changes)"
+    echo ""
+    echo "What it does:"
+    echo "  • Automatically patches BMAD agent activation instructions"
+    echo "  • Adds TTS calls when agents greet users"
+    echo "  • Uses voice mapping from AgentVibes BMAD plugin"
+    echo "  • Creates backups before modifying files"
+    ;;
+esac
--- a/.claude/hooks/bmad-voice-manager.sh
+++ b/.claude/hooks/bmad-voice-manager.sh
@@ -0,0 +1,511 @@
+#!/bin/bash
+#
+# File: .claude/hooks/bmad-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 BMAD Voice Plugin Manager - Maps BMAD agents to unique TTS voices
+# @context Enables each BMAD agent to have its own distinct voice for multi-agent sessions
+# @architecture Markdown table-based voice mapping with enable/disable flag, auto-detection of BMAD
+# @dependencies .claude/plugins/bmad-voices.md (voice mappings), bmad-tts-injector.sh, .bmad-core/ (BMAD installation)
+# @entrypoints Called by /agent-vibes:bmad commands, auto-enabled on BMAD detection
+# @patterns Plugin architecture, auto-enable on dependency detection, state backup/restore on toggle
+# @related bmad-tts-injector.sh, .claude/plugins/bmad-voices.md, .bmad-agent-context file
+
+PLUGIN_DIR=".claude/plugins"
+PLUGIN_FILE="$PLUGIN_DIR/bmad-voices.md"
+ENABLED_FLAG="$PLUGIN_DIR/bmad-voices-enabled.flag"
+
+# AI NOTE: Auto-enable pattern - When BMAD is detected via .bmad-core/install-manifest.yaml,
+# automatically enable the voice plugin to provide seamless multi-agent voice support.
+# This avoids requiring manual plugin activation after BMAD installation.
+
+# @function auto_enable_if_bmad_detected
+# @intent Automatically enable BMAD voice plugin when BMAD framework is detected
+# @why Provide seamless integration - users shouldn't need to manually enable voice mapping
+# @param None
+# @returns None
+# @exitcode 0=auto-enabled, 1=not enabled (already enabled or BMAD not detected)
+# @sideeffects Creates enabled flag file, creates plugin directory
+# @edgecases Only auto-enables if plugin not already enabled, silent operation
+# @calledby get_agent_voice
+# @calls mkdir, touch
+auto_enable_if_bmad_detected() {
+    # Check if BMAD is installed
+    if [[ -f ".bmad-core/install-manifest.yaml" ]] && [[ ! -f "$ENABLED_FLAG" ]]; then
+        # BMAD detected but plugin not enabled - enable it silently
+        mkdir -p "$PLUGIN_DIR"
+        touch "$ENABLED_FLAG"
+        return 0
+    fi
+    return 1
+}
+
+# @function get_agent_voice
+# @intent Retrieve TTS voice assigned to specific BMAD agent
+# @why Each BMAD agent needs unique voice for multi-agent conversation differentiation
+# @param $1 {string} agent_id - BMAD agent identifier (pm, dev, qa, architect, etc.)
+# @returns Echoes voice name to stdout, empty string if plugin disabled or agent not found
+# @exitcode Always 0
+# @sideeffects May auto-enable plugin if BMAD detected
+# @edgecases Returns empty string if plugin disabled/missing, parses markdown table syntax
+# @calledby bmad-tts-injector.sh, play-tts.sh when BMAD agent is active
+# @calls auto_enable_if_bmad_detected, grep, awk, sed
+get_agent_voice() {
+    local agent_id="$1"
+
+    # Auto-enable if BMAD is detected
+    auto_enable_if_bmad_detected
+
+    if [[ ! -f "$ENABLED_FLAG" ]]; then
+        echo ""  # Plugin disabled
+        return
+    fi
+
+    if [[ ! -f "$PLUGIN_FILE" ]]; then
+        echo ""  # Plugin file missing
+        return
+    fi
+
+    # Extract voice from markdown table
+    local voice=$(grep "^| $agent_id " "$PLUGIN_FILE" | \
+                  awk -F'|' '{print $4}' | \
+                  sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+    echo "$voice"
+}
+
+# @function get_agent_personality
+# @intent Retrieve TTS personality assigned to specific BMAD agent
+# @why Agents may have distinct speaking styles (friendly, professional, energetic, etc.)
+# @param $1 {string} agent_id - BMAD agent identifier
+# @returns Echoes personality name to stdout, empty string if not found
+# @exitcode Always 0
+# @sideeffects None
+# @edgecases Returns empty string if plugin file missing, parses column 5 of markdown table
+# @calledby bmad-tts-injector.sh for personality-aware voice synthesis
+# @calls grep, awk, sed
+get_agent_personality() {
+    local agent_id="$1"
+
+    if [[ ! -f "$PLUGIN_FILE" ]]; then
+        echo ""
+        return
+    fi
+
+    local personality=$(grep "^| $agent_id " "$PLUGIN_FILE" | \
+                       awk -F'|' '{print $5}' | \
+                       sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+    echo "$personality"
+}
+
+# @function is_plugin_enabled
+# @intent Check if BMAD voice plugin is currently enabled
+# @why Allow conditional logic based on plugin state
+# @param None
+# @returns Echoes "true" or "false" to stdout
+# @exitcode Always 0
+# @sideeffects None
+# @edgecases None
+# @calledby show_status, enable_plugin, disable_plugin
+# @calls None (file existence check)
+is_plugin_enabled() {
+    [[ -f "$ENABLED_FLAG" ]] && echo "true" || echo "false"
+}
+
+# @function enable_plugin
+# @intent Enable BMAD voice plugin and backup current voice settings
+# @why Allow users to switch to per-agent voices while preserving original configuration
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Creates flag file, backs up current voice/personality/sentiment to .bmad-previous-settings
+# @sideeffects Creates activation-instructions file for BMAD agents, calls bmad-tts-injector.sh
+# @edgecases Handles missing settings files gracefully with defaults
+# @calledby Main command dispatcher with "enable" argument
+# @calls mkdir, cat, source, list_mappings, bmad-tts-injector.sh
+enable_plugin() {
+    mkdir -p "$PLUGIN_DIR"
+
+    # Save current settings before enabling
+    BACKUP_FILE="$PLUGIN_DIR/.bmad-previous-settings"
+
+    # Save current voice
+    if [[ -f ".claude/tts-voice.txt" ]]; then
+        CURRENT_VOICE=$(cat .claude/tts-voice.txt 2>/dev/null)
+    elif [[ -f "$HOME/.claude/tts-voice.txt" ]]; then
+        CURRENT_VOICE=$(cat "$HOME/.claude/tts-voice.txt" 2>/dev/null)
+    else
+        CURRENT_VOICE="Aria"
+    fi
+
+    # Save current personality
+    if [[ -f ".claude/tts-personality.txt" ]]; then
+        CURRENT_PERSONALITY=$(cat .claude/tts-personality.txt 2>/dev/null)
+    elif [[ -f "$HOME/.claude/tts-personality.txt" ]]; then
+        CURRENT_PERSONALITY=$(cat "$HOME/.claude/tts-personality.txt" 2>/dev/null)
+    else
+        CURRENT_PERSONALITY="normal"
+    fi
+
+    # Save current sentiment
+    if [[ -f ".claude/tts-sentiment.txt" ]]; then
+        CURRENT_SENTIMENT=$(cat .claude/tts-sentiment.txt 2>/dev/null)
+    elif [[ -f "$HOME/.claude/tts-sentiment.txt" ]]; then
+        CURRENT_SENTIMENT=$(cat "$HOME/.claude/tts-sentiment.txt" 2>/dev/null)
+    else
+        CURRENT_SENTIMENT=""
+    fi
+
+    # Write backup
+    cat > "$BACKUP_FILE" <<EOF
+VOICE=$CURRENT_VOICE
+PERSONALITY=$CURRENT_PERSONALITY
+SENTIMENT=$CURRENT_SENTIMENT
+EOF
+
+    touch "$ENABLED_FLAG"
+
+    # Create activation-instructions file for BMAD agents
+    ACTIVATION_FILE=".claude/activation-instructions"
+    if [[ ! -f "$ACTIVATION_FILE" ]]; then
+        cat > "$ACTIVATION_FILE" <<'ACTIVATION_EOF'
+# BMAD Agent Activation Instructions
+
+When a BMAD agent activates, follow these steps EXACTLY:
+
+## STEP 3.5a: Create BMAD Context File (CRITICAL)
+
+**IMMEDIATELY after agent identification, create the context file:**
+
+```bash
+echo "$AGENT_ID" > .bmad-agent-context
+```
+
+Where `$AGENT_ID` is one of:
+- `pm` (Product Manager)
+- `dev` (Developer)
+- `qa` (QA)
+- `architect` (Architect)
+- `po` (Product Owner)
+- `analyst` (Analyst)
+- `sm` (Scrum Master)
+- `ux-expert` (UX Expert)
+- `bmad-master` (BMAD Master)
+- `bmad-orchestrator` (Orchestrator)
+
+**Example:**
+```bash
+# For Product Manager agent
+echo "pm" > .bmad-agent-context
+```
+
+This file allows AgentVibes to:
+1. Detect which BMAD agent is active
+2. Look up the correct voice mapping
+3. Automatically speak questions using the agent's assigned voice
+
+## STEP 10: Clean Up on Exit
+
+**Before exiting the agent, remove the context file:**
+
+```bash
+rm -f .bmad-agent-context
+```
+
+This ensures voice switching only happens when an agent is active.
+
+## Why This Matters
+
+Without the `.bmad-agent-context` file:
+- AgentVibes cannot detect which agent is active
+- Questions won't be spoken automatically
+- Voice switching won't work
+- The BMAD voice plugin becomes non-functional
+
+**This is MANDATORY for BMAD voice integration to work!**
+ACTIVATION_EOF
+        echo "📝 Created activation instructions: $ACTIVATION_FILE"
+    fi
+
+    echo "✅ BMAD voice plugin enabled"
+    echo "💾 Previous settings backed up:"
+    echo "   Voice: $CURRENT_VOICE"
+    echo "   Personality: $CURRENT_PERSONALITY"
+    [[ -n "$CURRENT_SENTIMENT" ]] && echo "   Sentiment: $CURRENT_SENTIMENT"
+    echo ""
+    list_mappings
+
+    # Automatically inject TTS into BMAD agents
+    echo ""
+    echo "🎤 Automatically enabling TTS for BMAD agents..."
+    echo ""
+
+    # Get the directory where this script is located
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+    # Check if bmad-tts-injector.sh exists
+    if [[ -f "$SCRIPT_DIR/bmad-tts-injector.sh" ]]; then
+        # Run the TTS injector
+        "$SCRIPT_DIR/bmad-tts-injector.sh" enable
+    else
+        echo "⚠️  TTS injector not found at: $SCRIPT_DIR/bmad-tts-injector.sh"
+        echo "   You can manually enable TTS with: /agent-vibes:bmad-tts enable"
+    fi
+}
+
+# @function disable_plugin
+# @intent Disable BMAD voice plugin and restore previous voice settings
+# @why Allow users to return to single-voice mode with their original configuration
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Removes flag file, restores settings from backup, calls bmad-tts-injector.sh disable
+# @edgecases Handles missing backup file gracefully, warns user if no backup exists
+# @calledby Main command dispatcher with "disable" argument
+# @calls source, rm, echo, bmad-tts-injector.sh
+disable_plugin() {
+    BACKUP_FILE="$PLUGIN_DIR/.bmad-previous-settings"
+
+    # Check if we have a backup to restore
+    if [[ -f "$BACKUP_FILE" ]]; then
+        source "$BACKUP_FILE"
+
+        echo "❌ BMAD voice plugin disabled"
+        echo "🔄 Restoring previous settings:"
+        echo "   Voice: $VOICE"
+        echo "   Personality: $PERSONALITY"
+        [[ -n "$SENTIMENT" ]] && echo "   Sentiment: $SENTIMENT"
+
+        # Restore voice
+        if [[ -n "$VOICE" ]]; then
+            echo "$VOICE" > .claude/tts-voice.txt 2>/dev/null || echo "$VOICE" > "$HOME/.claude/tts-voice.txt"
+        fi
+
+        # Restore personality
+        if [[ -n "$PERSONALITY" ]] && [[ "$PERSONALITY" != "normal" ]]; then
+            echo "$PERSONALITY" > .claude/tts-personality.txt 2>/dev/null || echo "$PERSONALITY" > "$HOME/.claude/tts-personality.txt"
+        fi
+
+        # Restore sentiment
+        if [[ -n "$SENTIMENT" ]]; then
+            echo "$SENTIMENT" > .claude/tts-sentiment.txt 2>/dev/null || echo "$SENTIMENT" > "$HOME/.claude/tts-sentiment.txt"
+        fi
+
+        # Clean up backup
+        rm -f "$BACKUP_FILE"
+    else
+        echo "❌ BMAD voice plugin disabled"
+        echo "⚠️  No previous settings found to restore"
+        echo "AgentVibes will use current voice/personality settings"
+    fi
+
+    rm -f "$ENABLED_FLAG"
+
+    # Automatically remove TTS from BMAD agents
+    echo ""
+    echo "🔇 Automatically disabling TTS for BMAD agents..."
+    echo ""
+
+    # Get the directory where this script is located
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+    # Check if bmad-tts-injector.sh exists
+    if [[ -f "$SCRIPT_DIR/bmad-tts-injector.sh" ]]; then
+        # Run the TTS injector disable
+        "$SCRIPT_DIR/bmad-tts-injector.sh" disable
+    else
+        echo "⚠️  TTS injector not found"
+        echo "   You can manually disable TTS with: /agent-vibes:bmad-tts disable"
+    fi
+}
+
+# @function list_mappings
+# @intent Display all BMAD agent-to-voice mappings in readable format
+# @why Help users see which voice is assigned to each agent
+# @param None
+# @returns None
+# @exitcode 0=success, 1=plugin file not found
+# @sideeffects Writes formatted output to stdout
+# @edgecases Parses markdown table format, skips header and separator rows
+# @calledby enable_plugin, show_status, main command dispatcher with "list"
+# @calls grep, sed, echo
+list_mappings() {
+    if [[ ! -f "$PLUGIN_FILE" ]]; then
+        echo "❌ Plugin file not found: $PLUGIN_FILE"
+        return 1
+    fi
+
+    echo "📊 BMAD Agent Voice Mappings:"
+    echo ""
+
+    grep "^| " "$PLUGIN_FILE" | grep -v "Agent ID" | grep -v "^|---" | \
+    while IFS='|' read -r _ agent_id name voice personality _; do
+        agent_id=$(echo "$agent_id" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        name=$(echo "$name" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        voice=$(echo "$voice" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        personality=$(echo "$personality" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+        [[ -n "$agent_id" ]] && echo "   $agent_id → $voice [$personality]"
+    done
+}
+
+# @function set_agent_voice
+# @intent Update voice and personality mapping for specific BMAD agent
+# @why Allow customization of agent voices to user preferences
+# @param $1 {string} agent_id - BMAD agent identifier
+# @param $2 {string} voice - New voice name
+# @param $3 {string} personality - New personality (optional, defaults to "normal")
+# @returns None
+# @exitcode 0=success, 1=plugin file not found or agent not found
+# @sideeffects Modifies plugin file, creates .bak backup
+# @edgecases Validates agent exists before updating
+# @calledby Main command dispatcher with "set" argument
+# @calls grep, sed
+set_agent_voice() {
+    local agent_id="$1"
+    local voice="$2"
+    local personality="${3:-normal}"
+
+    if [[ ! -f "$PLUGIN_FILE" ]]; then
+        echo "❌ Plugin file not found: $PLUGIN_FILE"
+        return 1
+    fi
+
+    # Check if agent exists
+    if ! grep -q "^| $agent_id " "$PLUGIN_FILE"; then
+        echo "❌ Agent '$agent_id' not found in plugin"
+        return 1
+    fi
+
+    # Update the voice and personality in the table
+    sed -i.bak "s/^| $agent_id |.*| .* | .* |$/| $agent_id | $(grep "^| $agent_id " "$PLUGIN_FILE" | awk -F'|' '{print $3}') | $voice | $personality |/" "$PLUGIN_FILE"
+
+    echo "✅ Updated $agent_id → $voice [$personality]"
+}
+
+# @function show_status
+# @intent Display plugin status, BMAD detection, and current voice mappings
+# @why Provide comprehensive overview of plugin state for troubleshooting
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Writes status information to stdout
+# @edgecases Checks for BMAD installation via manifest file
+# @calledby Main command dispatcher with "status" argument
+# @calls is_plugin_enabled, list_mappings
+show_status() {
+    # Check for BMAD installation
+    local bmad_installed="false"
+    if [[ -f ".bmad-core/install-manifest.yaml" ]]; then
+        bmad_installed="true"
+    fi
+
+    if [[ $(is_plugin_enabled) == "true" ]]; then
+        echo "✅ BMAD voice plugin: ENABLED"
+        if [[ "$bmad_installed" == "true" ]]; then
+            echo "🔍 BMAD detected: Auto-enabled"
+        fi
+    else
+        echo "❌ BMAD voice plugin: DISABLED"
+        if [[ "$bmad_installed" == "true" ]]; then
+            echo "⚠️  BMAD detected but plugin disabled (enable with: /agent-vibes-bmad enable)"
+        fi
+    fi
+    echo ""
+    list_mappings
+}
+
+# @function edit_plugin
+# @intent Open plugin configuration file for manual editing
+# @why Allow advanced users to modify voice mappings directly
+# @param None
+# @returns None
+# @exitcode 0=success, 1=plugin file not found
+# @sideeffects Displays file path and instructions
+# @edgecases Does not actually open editor, just provides guidance
+# @calledby Main command dispatcher with "edit" argument
+# @calls echo
+edit_plugin() {
+    if [[ ! -f "$PLUGIN_FILE" ]]; then
+        echo "❌ Plugin file not found: $PLUGIN_FILE"
+        return 1
+    fi
+
+    echo "Opening $PLUGIN_FILE for editing..."
+    echo "Edit the markdown table to change voice mappings"
+}
+
+# Main command dispatcher
+case "${1:-help}" in
+    enable)
+        enable_plugin
+        ;;
+    disable)
+        disable_plugin
+        ;;
+    status)
+        show_status
+        ;;
+    list)
+        list_mappings
+        ;;
+    set)
+        if [[ -z "$2" ]] || [[ -z "$3" ]]; then
+            echo "Usage: bmad-voice-manager.sh set <agent-id> <voice> [personality]"
+            exit 1
+        fi
+        set_agent_voice "$2" "$3" "$4"
+        ;;
+    get-voice)
+        get_agent_voice "$2"
+        ;;
+    get-personality)
+        get_agent_personality "$2"
+        ;;
+    edit)
+        edit_plugin
+        ;;
+    *)
+        echo "Usage: bmad-voice-manager.sh {enable|disable|status|list|set|get-voice|get-personality|edit}"
+        echo ""
+        echo "Commands:"
+        echo "  enable              Enable BMAD voice plugin"
+        echo "  disable             Disable BMAD voice plugin"
+        echo "  status              Show plugin status and mappings"
+        echo "  list                List all agent voice mappings"
+        echo "  set <id> <voice>    Set voice for agent"
+        echo "  get-voice <id>      Get voice for agent"
+        echo "  get-personality <id> Get personality for agent"
+        echo "  edit                Edit plugin configuration"
+        exit 1
+        ;;
+esac
--- a/.claude/hooks/check-output-style.sh
+++ b/.claude/hooks/check-output-style.sh
@@ -0,0 +1,112 @@
+#!/bin/bash
+#
+# File: .claude/hooks/check-output-style.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 Output Style Detection - Detects if Agent Vibes output style is active in Claude Code
+# @context Voice commands require the Agent Vibes output style to work properly with automatic TTS
+# @architecture Heuristic detection using environment variables and file system checks
+# @dependencies CLAUDECODE environment variable, .claude/output-styles/agent-vibes.md file
+# @entrypoints Called by slash commands to warn users if output style is incorrect
+# @patterns Environment-based detection, graceful degradation with helpful error messages
+# @related .claude/output-styles/agent-vibes.md, Claude Code output style system
+
+# AI NOTE: Output style detection is heuristic-based because Claude Code does not expose
+# the active output style via environment variables. We check for CLAUDECODE env var and
+# the presence of the agent-vibes.md output style file as indicators.
+
+# @function check_output_style
+# @intent Detect if Agent Vibes output style is likely active in Claude Code session
+# @why Voice commands depend on output style hooks that automatically invoke TTS
+# @param None
+# @returns None
+# @exitcode 0=likely using agent-vibes style, 1=not using or cannot detect
+# @sideeffects None (read-only checks)
+# @edgecases Cannot directly detect output style, relies on CLAUDECODE env var and file presence
+# @calledby Main execution block, slash command validation
+# @calls None (direct environment and file checks)
+check_output_style() {
+  # Strategy: Check if this script is being called from within a Claude response
+  # If CLAUDECODE env var is set, we're in Claude Code
+  # If not, we're running standalone (not in a Claude Code session)
+
+  if [[ -z "$CLAUDECODE" ]]; then
+    # Not in Claude Code at all
+    return 1
+  fi
+
+  # We're in Claude Code, but we can't directly detect output style
+  # The agent-vibes output style calls our TTS hooks automatically
+  # So if this function is called, it means a slash command was invoked
+
+  # Check if we have the necessary TTS setup
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+  # Check if agent-vibes output style is installed
+  if [[ ! -f "$SCRIPT_DIR/../output-styles/agent-vibes.md" ]]; then
+    return 1
+  fi
+
+  # All checks passed - likely using agent-vibes output style
+  return 0
+}
+
+# @function show_output_style_warning
+# @intent Display helpful warning about enabling Agent Vibes output style
+# @why Users need guidance on how to enable automatic TTS narration
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Writes warning message to stdout
+# @edgecases None
+# @calledby Main execution block when check_output_style fails
+# @calls echo
+show_output_style_warning() {
+  echo ""
+  echo "⚠️  Voice commands require the Agent Vibes output style"
+  echo ""
+  echo "To enable voice narration, run:"
+  echo "  /output-style Agent Vibes"
+  echo ""
+  echo "This will make Claude speak with TTS for all responses."
+  echo "You can still use voice commands manually with agent-vibes disabled,"
+  echo "but you won't hear automatic TTS narration."
+  echo ""
+}
+
+# Main execution when called directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  if ! check_output_style; then
+    show_output_style_warning
+    exit 1
+  fi
+  exit 0
+fi
--- a/.claude/hooks/download-extra-voices.sh
+++ b/.claude/hooks/download-extra-voices.sh
@@ -0,0 +1,244 @@
+#!/bin/bash
+#
+# File: .claude/hooks/download-extra-voices.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 Extra Piper Voice Downloader - Downloads custom high-quality voices from HuggingFace
+# @context Post-installation utility to download premium custom voices (Kristin, Jenny, Tracy/16Speakers)
+# @architecture Downloads ONNX voice models from agentvibes/piper-custom-voices HuggingFace repository
+# @dependencies curl (downloads), piper-voice-manager.sh (storage dir logic)
+# @entrypoints Called by MCP server download_extra_voices tool or manually
+# @patterns Batch downloads, skip-existing logic, auto-yes flag for non-interactive use
+# @related piper-voice-manager.sh, mcp-server/server.py, docs/huggingface-setup-guide.md
+#
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/piper-voice-manager.sh"
+
+# Parse command line arguments
+AUTO_YES=false
+if [[ "$1" == "--yes" ]] || [[ "$1" == "-y" ]]; then
+  AUTO_YES=true
+fi
+
+# HuggingFace repository for custom voices
+HUGGINGFACE_REPO="agentvibes/piper-custom-voices"
+HUGGINGFACE_BASE_URL="https://huggingface.co/${HUGGINGFACE_REPO}/resolve/main"
+
+# Extra custom voices to download
+EXTRA_VOICES=(
+  "kristin:Kristin (US English female, Public Domain, 64MB)"
+  "jenny:Jenny (UK English female with Irish accent, CC BY, 64MB)"
+  "16Speakers:Tracy/16Speakers (Multi-speaker: 12 US + 4 UK voices, Public Domain, 77MB)"
+)
+
+echo "🎙️  AgentVibes Extra Voice Downloader"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "This will download high-quality custom Piper voices from HuggingFace."
+echo ""
+echo "📦 Voices available:"
+for voice_info in "${EXTRA_VOICES[@]}"; do
+  voice_name="${voice_info%%:*}"
+  voice_desc="${voice_info#*:}"
+  echo "  • $voice_desc"
+done
+echo ""
+
+# Check if piper is installed
+if ! command -v piper &> /dev/null; then
+  echo "❌ Error: Piper TTS not installed"
+  echo "Install with: pipx install piper-tts"
+  exit 1
+fi
+
+# Get storage directory
+VOICE_DIR=$(get_voice_storage_dir)
+echo "📂 Storage location: $VOICE_DIR"
+echo ""
+
+# Count already downloaded
+ALREADY_DOWNLOADED=0
+ALREADY_DOWNLOADED_LIST=()
+NEED_DOWNLOAD=()
+
+for voice_info in "${EXTRA_VOICES[@]}"; do
+  voice_name="${voice_info%%:*}"
+  voice_desc="${voice_info#*:}"
+
+  # Check if both .onnx and .onnx.json exist
+  if [[ -f "$VOICE_DIR/${voice_name}.onnx" ]] && [[ -f "$VOICE_DIR/${voice_name}.onnx.json" ]]; then
+    ((ALREADY_DOWNLOADED++))
+    ALREADY_DOWNLOADED_LIST+=("$voice_desc")
+  else
+    NEED_DOWNLOAD+=("$voice_info")
+  fi
+done
+
+echo "📊 Status:"
+echo "   Already downloaded: $ALREADY_DOWNLOADED voice(s)"
+echo "   Need to download: ${#NEED_DOWNLOAD[@]} voice(s)"
+echo ""
+
+# Show already downloaded voices
+if [[ $ALREADY_DOWNLOADED -gt 0 ]]; then
+  echo "✅ Already downloaded (skipped):"
+  for voice_desc in "${ALREADY_DOWNLOADED_LIST[@]}"; do
+    echo "   ✓ $voice_desc"
+  done
+  echo ""
+fi
+
+if [[ ${#NEED_DOWNLOAD[@]} -eq 0 ]]; then
+  echo "🎉 All extra voices already downloaded!"
+  exit 0
+fi
+
+echo "Voices to download:"
+for voice_info in "${NEED_DOWNLOAD[@]}"; do
+  voice_desc="${voice_info#*:}"
+  echo "  • $voice_desc"
+done
+echo ""
+
+# Calculate total size
+TOTAL_SIZE_MB=0
+for voice_info in "${NEED_DOWNLOAD[@]}"; do
+  voice_desc="${voice_info#*:}"
+  if [[ "$voice_desc" =~ ([0-9]+)MB ]]; then
+    TOTAL_SIZE_MB=$((TOTAL_SIZE_MB + ${BASH_REMATCH[1]}))
+  fi
+done
+
+echo "💾 Total download size: ~${TOTAL_SIZE_MB}MB"
+echo ""
+
+# Ask for confirmation (skip if --yes flag provided)
+if [[ "$AUTO_YES" == "false" ]]; then
+  read -p "Download ${#NEED_DOWNLOAD[@]} extra voice(s)? [Y/n]: " -n 1 -r
+  echo
+
+  if [[ ! $REPLY =~ ^[Yy]$ ]] && [[ -n $REPLY ]]; then
+    echo "❌ Download cancelled"
+    exit 0
+  fi
+else
+  echo "Auto-downloading ${#NEED_DOWNLOAD[@]} extra voice(s)..."
+  echo ""
+fi
+
+# Create voice directory if it doesn't exist
+mkdir -p "$VOICE_DIR"
+
+# Download function
+download_voice_file() {
+  local url="$1"
+  local output_path="$2"
+  local file_name="$3"
+
+  echo "  📥 Downloading $file_name..."
+
+  if curl -L --progress-bar "$url" -o "$output_path" 2>&1; then
+    echo "  ✅ Downloaded: $file_name"
+    return 0
+  else
+    echo "  ❌ Failed to download: $file_name"
+    return 1
+  fi
+}
+
+# Download each voice
+DOWNLOADED=0
+FAILED=0
+
+for voice_info in "${NEED_DOWNLOAD[@]}"; do
+  voice_name="${voice_info%%:*}"
+  voice_desc="${voice_info#*:}"
+
+  echo ""
+  echo "📥 Downloading: ${voice_desc%%,*}..."
+  echo ""
+
+  # Download .onnx file
+  onnx_url="${HUGGINGFACE_BASE_URL}/${voice_name}.onnx"
+  onnx_path="${VOICE_DIR}/${voice_name}.onnx"
+
+  # Download .onnx.json file
+  json_url="${HUGGINGFACE_BASE_URL}/${voice_name}.onnx.json"
+  json_path="${VOICE_DIR}/${voice_name}.onnx.json"
+
+  success=true
+
+  if ! download_voice_file "$onnx_url" "$onnx_path" "${voice_name}.onnx"; then
+    success=false
+  fi
+
+  if ! download_voice_file "$json_url" "$json_path" "${voice_name}.onnx.json"; then
+    success=false
+  fi
+
+  if [[ "$success" == "true" ]]; then
+    ((DOWNLOADED++))
+    echo ""
+    echo "✅ Successfully downloaded: ${voice_desc%%,*}"
+  else
+    ((FAILED++))
+    echo ""
+    echo "❌ Failed to download: ${voice_desc%%,*}"
+    # Clean up partial downloads
+    rm -f "$onnx_path" "$json_path"
+  fi
+done
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "📊 Download Summary:"
+echo "   ✅ Successfully downloaded: $DOWNLOADED"
+echo "   ❌ Failed: $FAILED"
+echo "   📦 Total extra voices available: $((ALREADY_DOWNLOADED + DOWNLOADED))"
+echo ""
+
+if [[ $DOWNLOADED -gt 0 ]]; then
+  echo "✨ Extra voices ready to use!"
+  echo ""
+  echo "Try them:"
+  echo "  /agent-vibes:provider switch piper"
+  echo "  /agent-vibes:switch kristin"
+  echo "  /agent-vibes:switch jenny"
+  echo "  /agent-vibes:switch 16Speakers"
+fi
+
+# Return success if at least one voice was downloaded or all were already present
+if [[ $DOWNLOADED -gt 0 ]] || [[ $ALREADY_DOWNLOADED -gt 0 ]]; then
+  exit 0
+else
+  exit 1
+fi
--- a/.claude/hooks/github-star-reminder.sh
+++ b/.claude/hooks/github-star-reminder.sh
@@ -0,0 +1,154 @@
+#!/bin/bash
+#
+# File: .claude/hooks/github-star-reminder.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 GitHub Star Reminder System - Gentle daily reminder to star repository
+# @context Shows a once-per-day reminder to encourage users to support the project without being annoying
+# @architecture Timestamp-based tracking using daily date comparison in a state file
+# @dependencies date command for timestamp generation
+# @entrypoints Called by play-tts.sh router on every TTS execution, sourced or executed directly
+# @patterns Rate-limiting via file-based state, graceful degradation, user-opt-out support
+# @related .claude/github-star-reminder.txt (state file), .claude/github-star-reminder-disabled.flag (opt-out)
+
+# Determine config directory (project-local or global)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Check if we have a project-local .claude directory
+if [[ -d "$CLAUDE_DIR" ]] && [[ "$CLAUDE_DIR" != "$HOME/.claude" ]]; then
+  REMINDER_FILE="$CLAUDE_DIR/github-star-reminder.txt"
+else
+  REMINDER_FILE="$HOME/.claude/github-star-reminder.txt"
+  mkdir -p "$HOME/.claude"
+fi
+
+GITHUB_REPO="https://github.com/paulpreibisch/AgentVibes"
+
+# @function is_reminder_disabled
+# @intent Check if GitHub star reminders have been disabled by the user
+# @why Respect user preferences and provide opt-out mechanism for reminders
+# @param None
+# @returns None
+# @exitcode 0=reminders disabled, 1=reminders enabled
+# @sideeffects Reads flag files from local/global .claude directories
+# @edgecases Checks both flag file and "disabled" text in reminder file for backward compatibility
+# @calledby should_show_reminder
+# @calls cat for reading reminder file content
+is_reminder_disabled() {
+  # Check for disable flag file
+  local disable_file_local="$CLAUDE_DIR/github-star-reminder-disabled.flag"
+  local disable_file_global="$HOME/.claude/github-star-reminder-disabled.flag"
+
+  if [[ -f "$disable_file_local" ]] || [[ -f "$disable_file_global" ]]; then
+    return 0  # Disabled
+  fi
+
+  # Check if reminder file contains "disabled"
+  if [[ -f "$REMINDER_FILE" ]]; then
+    local content=$(cat "$REMINDER_FILE" 2>/dev/null)
+    if [[ "$content" == "disabled" ]]; then
+      return 0  # Disabled
+    fi
+  fi
+
+  return 1  # Not disabled
+}
+
+# @function should_show_reminder
+# @intent Determine if reminder should be displayed based on date and disable status
+# @why Implement once-per-day rate limiting to avoid annoying users
+# @param None
+# @returns None
+# @exitcode 0=should show, 1=should not show
+# @sideeffects Reads .claude/github-star-reminder.txt for last reminder date
+# @edgecases Shows reminder if file doesn't exist (first run), compares YYYYMMDD format dates
+# @calledby Main execution block
+# @calls is_reminder_disabled, cat, date
+should_show_reminder() {
+  # Check if disabled first
+  if is_reminder_disabled; then
+    return 1
+  fi
+
+  # If no reminder file exists, show it
+  if [[ ! -f "$REMINDER_FILE" ]]; then
+    return 0
+  fi
+
+  # Read last reminder date
+  LAST_REMINDER=$(cat "$REMINDER_FILE" 2>/dev/null || echo "0")
+  CURRENT_DATE=$(date +%Y%m%d)
+
+  # Show reminder if it's a new day
+  if [[ "$LAST_REMINDER" != "$CURRENT_DATE" ]]; then
+    return 0
+  fi
+
+  return 1
+}
+
+# @function show_reminder
+# @intent Display friendly GitHub star reminder with opt-out instructions
+# @why Encourage community support while being respectful and non-intrusive
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Updates reminder file with current date, writes to stdout
+# @edgecases None
+# @calledby Main execution block when should_show_reminder returns true
+# @calls date, echo
+show_reminder() {
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "⭐ Enjoying AgentVibes?"
+  echo ""
+  echo "   If you find this project helpful, please consider giving us"
+  echo "   a star on GitHub! It helps others discover AgentVibes and"
+  echo "   motivates us to keep improving it."
+  echo ""
+  echo "   👉 $GITHUB_REPO"
+  echo ""
+  echo "   Thank you for your support! 🙏"
+  echo ""
+  echo "   💡 To disable these reminders, run:"
+  echo "   echo \"disabled\" > $REMINDER_FILE"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+
+  # Update the reminder file with today's date
+  date +%Y%m%d > "$REMINDER_FILE"
+}
+
+# Main execution
+if should_show_reminder; then
+  show_reminder
+fi
--- a/.claude/hooks/language-manager.sh
+++ b/.claude/hooks/language-manager.sh
@@ -0,0 +1,392 @@
+#!/bin/bash
+#
+# File: .claude/hooks/language-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. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Language Manager - Manages multilingual TTS with 30+ language support
+# @context Enables TTS in multiple languages with provider-specific voice recommendations (ElevenLabs multilingual vs Piper native)
+# @architecture Dual-map system: ELEVENLABS_VOICES and PIPER_VOICES for provider-aware voice selection
+# @dependencies provider-manager.sh for active provider detection, .claude/tts-language.txt for state
+# @entrypoints Called by /agent-vibes:language commands, play-tts-*.sh for voice resolution
+# @patterns Provider abstraction, language-to-voice mapping, backward compatibility with legacy LANGUAGE_VOICES
+# @related play-tts-elevenlabs.sh, play-tts-piper.sh, provider-manager.sh, learn-manager.sh
+
+# Determine target .claude directory based on context
+# Priority:
+# 1. CLAUDE_PROJECT_DIR env var (set by MCP for project-specific settings)
+# 2. Script location (for direct slash command usage)
+# 3. Global ~/.claude (fallback)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+  # MCP context: Use the project directory where MCP was invoked
+  CLAUDE_DIR="$CLAUDE_PROJECT_DIR/.claude"
+else
+  # Direct usage context: Use script location
+  CLAUDE_DIR="$(cd "$SCRIPT_DIR/.." 2>/dev/null && pwd)"
+
+  # If script is in global ~/.claude, use that
+  if [[ "$CLAUDE_DIR" == "$HOME/.claude" ]]; then
+    CLAUDE_DIR="$HOME/.claude"
+  elif [[ ! -d "$CLAUDE_DIR" ]]; then
+    # Fallback to global if directory doesn't exist
+    CLAUDE_DIR="$HOME/.claude"
+  fi
+fi
+
+LANGUAGE_FILE="$CLAUDE_DIR/tts-language.txt"
+mkdir -p "$CLAUDE_DIR"
+
+# Source provider manager to detect active provider
+source "$SCRIPT_DIR/provider-manager.sh" 2>/dev/null || true
+
+# Language to ElevenLabs multilingual voice mapping
+declare -A ELEVENLABS_VOICES=(
+    ["spanish"]="Antoni"
+    ["french"]="Rachel"
+    ["german"]="Domi"
+    ["italian"]="Bella"
+    ["portuguese"]="Matilda"
+    ["chinese"]="Antoni"
+    ["japanese"]="Antoni"
+    ["korean"]="Antoni"
+    ["russian"]="Domi"
+    ["polish"]="Antoni"
+    ["dutch"]="Rachel"
+    ["turkish"]="Antoni"
+    ["arabic"]="Antoni"
+    ["hindi"]="Antoni"
+    ["swedish"]="Rachel"
+    ["danish"]="Rachel"
+    ["norwegian"]="Rachel"
+    ["finnish"]="Rachel"
+    ["czech"]="Domi"
+    ["romanian"]="Rachel"
+    ["ukrainian"]="Domi"
+    ["greek"]="Antoni"
+    ["bulgarian"]="Domi"
+    ["croatian"]="Domi"
+    ["slovak"]="Domi"
+)
+
+# Language to Piper voice model mapping
+declare -A PIPER_VOICES=(
+    ["spanish"]="es_ES-davefx-medium"
+    ["french"]="fr_FR-siwis-medium"
+    ["german"]="de_DE-thorsten-medium"
+    ["italian"]="it_IT-riccardo-x_low"
+    ["portuguese"]="pt_BR-faber-medium"
+    ["chinese"]="zh_CN-huayan-medium"
+    ["japanese"]="ja_JP-hikari-medium"
+    ["korean"]="ko_KR-eunyoung-medium"
+    ["russian"]="ru_RU-dmitri-medium"
+    ["polish"]="pl_PL-darkman-medium"
+    ["dutch"]="nl_NL-rdh-medium"
+    ["turkish"]="tr_TR-dfki-medium"
+    ["arabic"]="ar_JO-kareem-medium"
+    ["hindi"]="hi_IN-amitabh-medium"
+    ["swedish"]="sv_SE-nst-medium"
+    ["danish"]="da_DK-talesyntese-medium"
+    ["norwegian"]="no_NO-talesyntese-medium"
+    ["finnish"]="fi_FI-harri-medium"
+    ["czech"]="cs_CZ-jirka-medium"
+    ["romanian"]="ro_RO-mihai-medium"
+    ["ukrainian"]="uk_UA-lada-x_low"
+    ["greek"]="el_GR-rapunzelina-low"
+    ["bulgarian"]="bg_BG-valentin-medium"
+    ["croatian"]="hr_HR-gorana-medium"
+    ["slovak"]="sk_SK-lili-medium"
+)
+
+# Backward compatibility: Keep LANGUAGE_VOICES for existing code
+declare -A LANGUAGE_VOICES=(
+    ["spanish"]="Antoni"
+    ["french"]="Rachel"
+    ["german"]="Domi"
+    ["italian"]="Bella"
+    ["portuguese"]="Matilda"
+    ["chinese"]="Antoni"
+    ["japanese"]="Antoni"
+    ["korean"]="Antoni"
+    ["russian"]="Domi"
+    ["polish"]="Antoni"
+    ["dutch"]="Rachel"
+    ["turkish"]="Antoni"
+    ["arabic"]="Antoni"
+    ["hindi"]="Antoni"
+    ["swedish"]="Rachel"
+    ["danish"]="Rachel"
+    ["norwegian"]="Rachel"
+    ["finnish"]="Rachel"
+    ["czech"]="Domi"
+    ["romanian"]="Rachel"
+    ["ukrainian"]="Domi"
+    ["greek"]="Antoni"
+    ["bulgarian"]="Domi"
+    ["croatian"]="Domi"
+    ["slovak"]="Domi"
+)
+
+# Supported languages list
+SUPPORTED_LANGUAGES="spanish, french, german, italian, portuguese, chinese, japanese, korean, polish, dutch, turkish, russian, arabic, hindi, swedish, danish, norwegian, finnish, czech, romanian, ukrainian, greek, bulgarian, croatian, slovak"
+
+# Function to set language
+set_language() {
+    local lang="$1"
+
+    # Convert to lowercase
+    lang=$(echo "$lang" | tr '[:upper:]' '[:lower:]')
+
+    # Handle reset/english
+    if [[ "$lang" == "reset" ]] || [[ "$lang" == "english" ]] || [[ "$lang" == "en" ]]; then
+        if [[ -f "$LANGUAGE_FILE" ]]; then
+            rm "$LANGUAGE_FILE"
+            echo "✓ Language reset to English (default)"
+        else
+            echo "Already using English (default)"
+        fi
+        return 0
+    fi
+
+    # Check if language is supported
+    if [[ ! " ${!LANGUAGE_VOICES[@]} " =~ " ${lang} " ]]; then
+        echo "❌ Language '$lang' not supported"
+        echo ""
+        echo "Supported languages:"
+        echo "$SUPPORTED_LANGUAGES"
+        return 1
+    fi
+
+    # Save language
+    echo "$lang" > "$LANGUAGE_FILE"
+
+    # Detect active provider and get recommended voice
+    local provider=""
+    if [[ -f "$CLAUDE_DIR/tts-provider.txt" ]]; then
+        provider=$(cat "$CLAUDE_DIR/tts-provider.txt")
+    elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+        provider=$(cat "$HOME/.claude/tts-provider.txt")
+    else
+        provider="elevenlabs"
+    fi
+
+    local recommended_voice=$(get_voice_for_language "$lang" "$provider")
+
+    # Fallback to old mapping if provider-aware function returns empty
+    if [[ -z "$recommended_voice" ]]; then
+        recommended_voice="${LANGUAGE_VOICES[$lang]}"
+    fi
+
+    echo "✓ Language set to: $lang"
+    echo "📢 Recommended voice for $provider TTS: $recommended_voice"
+    echo ""
+    echo "TTS will now speak in $lang."
+    echo "Switch voice with: /agent-vibes:switch \"$recommended_voice\""
+}
+
+# Function to get current language
+get_language() {
+    if [[ -f "$LANGUAGE_FILE" ]]; then
+        local lang=$(cat "$LANGUAGE_FILE")
+
+        # Detect active provider
+        local provider=""
+        if [[ -f "$CLAUDE_DIR/tts-provider.txt" ]]; then
+            provider=$(cat "$CLAUDE_DIR/tts-provider.txt")
+        elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+            provider=$(cat "$HOME/.claude/tts-provider.txt")
+        else
+            provider="elevenlabs"
+        fi
+
+        local recommended_voice=$(get_voice_for_language "$lang" "$provider")
+
+        # Fallback to old mapping
+        if [[ -z "$recommended_voice" ]]; then
+            recommended_voice="${LANGUAGE_VOICES[$lang]}"
+        fi
+
+        echo "Current language: $lang"
+        echo "Recommended voice ($provider): $recommended_voice"
+    else
+        echo "Current language: english (default)"
+        echo "No multilingual voice required"
+    fi
+}
+
+# Function to get language for use in other scripts
+get_language_code() {
+    if [[ -f "$LANGUAGE_FILE" ]]; then
+        cat "$LANGUAGE_FILE"
+    else
+        echo "english"
+    fi
+}
+
+# Function to check if current voice supports language
+is_voice_multilingual() {
+    local voice="$1"
+
+    # List of multilingual voices
+    local multilingual_voices=("Antoni" "Rachel" "Domi" "Bella" "Charlotte" "Matilda")
+
+    for mv in "${multilingual_voices[@]}"; do
+        if [[ "$voice" == "$mv" ]]; then
+            return 0
+        fi
+    done
+
+    return 1
+}
+
+# Function to get best voice for current language
+get_best_voice_for_language() {
+    local lang=$(get_language_code)
+
+    if [[ "$lang" == "english" ]]; then
+        # No specific multilingual voice needed for English
+        echo ""
+        return
+    fi
+
+    # Return recommended voice for language
+    echo "${LANGUAGE_VOICES[$lang]}"
+}
+
+# Function to get voice for a specific language and provider
+# Usage: get_voice_for_language <language> [provider]
+# Provider: "elevenlabs" or "piper" (auto-detected if not provided)
+get_voice_for_language() {
+    local language="$1"
+    local provider="${2:-}"
+
+    # Convert to lowercase
+    language=$(echo "$language" | tr '[:upper:]' '[:lower:]')
+
+    # Auto-detect provider if not specified
+    if [[ -z "$provider" ]]; then
+        if command -v get_active_provider &>/dev/null; then
+            provider=$(get_active_provider 2>/dev/null)
+        else
+            # Fallback to checking provider file directly
+            # Try current directory first, then search up the tree
+            local search_dir="$PWD"
+            local found=false
+
+            while [[ "$search_dir" != "/" ]]; do
+                if [[ -f "$search_dir/.claude/tts-provider.txt" ]]; then
+                    provider=$(cat "$search_dir/.claude/tts-provider.txt")
+                    found=true
+                    break
+                fi
+                search_dir=$(dirname "$search_dir")
+            done
+
+            # If not found in project tree, check global
+            if [[ "$found" = false ]]; then
+                if [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+                    provider=$(cat "$HOME/.claude/tts-provider.txt")
+                else
+                    provider="elevenlabs"  # Default
+                fi
+            fi
+        fi
+    fi
+
+    # Return appropriate voice based on provider
+    case "$provider" in
+        piper)
+            echo "${PIPER_VOICES[$language]:-}"
+            ;;
+        elevenlabs)
+            echo "${ELEVENLABS_VOICES[$language]:-}"
+            ;;
+        *)
+            echo "${ELEVENLABS_VOICES[$language]:-}"
+            ;;
+    esac
+}
+
+# Main command handler - only run if script is executed directly, not sourced
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    case "${1:-}" in
+        set)
+            if [[ -z "$2" ]]; then
+                echo "Usage: language-manager.sh set <language>"
+                exit 1
+            fi
+            set_language "$2"
+            ;;
+        get)
+            get_language
+            ;;
+        code)
+            get_language_code
+            ;;
+        check-voice)
+            if [[ -z "$2" ]]; then
+                echo "Usage: language-manager.sh check-voice <voice-name>"
+                exit 1
+            fi
+            if is_voice_multilingual "$2"; then
+                echo "yes"
+            else
+                echo "no"
+            fi
+            ;;
+        best-voice)
+            get_best_voice_for_language
+            ;;
+        voice-for-language)
+            if [[ -z "$2" ]]; then
+                echo "Usage: language-manager.sh voice-for-language <language> [provider]"
+                exit 1
+            fi
+            get_voice_for_language "$2" "$3"
+            ;;
+        list)
+            echo "Supported languages and recommended voices:"
+            echo ""
+            for lang in "${!LANGUAGE_VOICES[@]}"; do
+                printf "%-15s → %s\n" "$lang" "${LANGUAGE_VOICES[$lang]}"
+            done | sort
+            ;;
+        *)
+            echo "AgentVibes Language Manager"
+            echo ""
+            echo "Usage:"
+            echo "  language-manager.sh set <language>                    Set language"
+            echo "  language-manager.sh get                               Get current language"
+            echo "  language-manager.sh code                              Get language code only"
+            echo "  language-manager.sh check-voice <name>                Check if voice is multilingual"
+            echo "  language-manager.sh best-voice                        Get best voice for current language"
+            echo "  language-manager.sh voice-for-language <lang> [prov] Get voice for language & provider"
+            echo "  language-manager.sh list                              List all supported languages"
+            exit 1
+            ;;
+    esac
+fi
--- a/.claude/hooks/learn-manager.sh
+++ b/.claude/hooks/learn-manager.sh
@@ -0,0 +1,475 @@
+#!/bin/bash
+#
+# File: .claude/hooks/learn-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. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Language Learning Mode Manager - Enables dual-language TTS for immersive learning
+# @context Speaks responses in both main language (English) and target language (Spanish, French, etc.) for language practice
+# @architecture Manages main/target language pairs with voice mappings, auto-configures recommended voices per language
+# @dependencies play-tts.sh (dual invocation), language-manager.sh (voice recommendations), .claude/tts-*.txt state files
+# @entrypoints Called by /agent-vibes:learn commands to enable/disable learning mode
+# @patterns Dual-voice orchestration, auto-configuration, greeting on activation, provider-aware voice selection
+# @related language-manager.sh, play-tts.sh, .claude/tts-learn-mode.txt, .claude/tts-target-language.txt
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$SCRIPT_DIR/../.."
+
+# Configuration files (project-local first, then global fallback)
+MAIN_LANG_FILE="$PROJECT_DIR/.claude/tts-main-language.txt"
+TARGET_LANG_FILE="$PROJECT_DIR/.claude/tts-target-language.txt"
+TARGET_VOICE_FILE="$PROJECT_DIR/.claude/tts-target-voice.txt"
+LEARN_MODE_FILE="$PROJECT_DIR/.claude/tts-learn-mode.txt"
+
+GLOBAL_MAIN_LANG_FILE="$HOME/.claude/tts-main-language.txt"
+GLOBAL_TARGET_LANG_FILE="$HOME/.claude/tts-target-language.txt"
+GLOBAL_TARGET_VOICE_FILE="$HOME/.claude/tts-target-voice.txt"
+GLOBAL_LEARN_MODE_FILE="$HOME/.claude/tts-learn-mode.txt"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Get main language
+get_main_language() {
+    if [[ -f "$MAIN_LANG_FILE" ]]; then
+        cat "$MAIN_LANG_FILE"
+    elif [[ -f "$GLOBAL_MAIN_LANG_FILE" ]]; then
+        cat "$GLOBAL_MAIN_LANG_FILE"
+    else
+        echo "english"
+    fi
+}
+
+# Set main language
+set_main_language() {
+    local language="$1"
+    if [[ -z "$language" ]]; then
+        echo -e "${YELLOW}Usage: learn-manager.sh set-main-language <language>${NC}"
+        exit 1
+    fi
+
+    mkdir -p "$PROJECT_DIR/.claude"
+    echo "$language" > "$MAIN_LANG_FILE"
+    echo -e "${GREEN}✓${NC} Main language set to: $language"
+}
+
+# Get target language
+get_target_language() {
+    if [[ -f "$TARGET_LANG_FILE" ]]; then
+        cat "$TARGET_LANG_FILE"
+    elif [[ -f "$GLOBAL_TARGET_LANG_FILE" ]]; then
+        cat "$GLOBAL_TARGET_LANG_FILE"
+    else
+        echo ""
+    fi
+}
+
+# Get greeting message for a language
+get_greeting_for_language() {
+    local language="$1"
+
+    case "${language,,}" in
+        spanish|español)
+            echo "¡Hola! Soy tu profesor de español. ¡Vamos a aprender juntos!"
+            ;;
+        french|français)
+            echo "Bonjour! Je suis votre professeur de français. Apprenons ensemble!"
+            ;;
+        german|deutsch)
+            echo "Hallo! Ich bin dein Deutschlehrer. Lass uns zusammen lernen!"
+            ;;
+        italian|italiano)
+            echo "Ciao! Sono il tuo insegnante di italiano. Impariamo insieme!"
+            ;;
+        portuguese|português)
+            echo "Olá! Sou seu professor de português. Vamos aprender juntos!"
+            ;;
+        chinese|中文|mandarin)
+            echo "你好！我是你的中文老师。让我们一起学习吧！"
+            ;;
+        japanese|日本語)
+            echo "こんにちは！私はあなたの日本語の先生です。一緒に勉強しましょう！"
+            ;;
+        korean|한국어)
+            echo "안녕하세요! 저는 당신의 한국어 선생님입니다. 함께 배워봅시다!"
+            ;;
+        russian|русский)
+            echo "Здравствуйте! Я ваш учитель русского языка. Давайте учиться вместе!"
+            ;;
+        arabic|العربية)
+            echo "مرحبا! أنا معلمك للغة العربية. دعونا نتعلم معا!"
+            ;;
+        hindi|हिन्दी)
+            echo "नमस्ते! मैं आपका हिंदी शिक्षक हूं। आइए साथ में सीखें!"
+            ;;
+        dutch|nederlands)
+            echo "Hallo! Ik ben je Nederlandse leraar. Laten we samen leren!"
+            ;;
+        polish|polski)
+            echo "Cześć! Jestem twoim nauczycielem polskiego. Uczmy się razem!"
+            ;;
+        turkish|türkçe)
+            echo "Merhaba! Ben Türkçe öğretmeninizim. Birlikte öğrenelim!"
+            ;;
+        swedish|svenska)
+            echo "Hej! Jag är din svenskalärare. Låt oss lära tillsammans!"
+            ;;
+        *)
+            echo "Hello! I am your language teacher. Let's learn together!"
+            ;;
+    esac
+}
+
+# Set target language
+set_target_language() {
+    local language="$1"
+    if [[ -z "$language" ]]; then
+        echo -e "${YELLOW}Usage: learn-manager.sh set-target-language <language>${NC}"
+        exit 1
+    fi
+
+    mkdir -p "$PROJECT_DIR/.claude"
+    echo "$language" > "$TARGET_LANG_FILE"
+    echo -e "${GREEN}✓${NC} Target language set to: $language"
+
+    # Automatically set the recommended voice for this language
+    local recommended_voice=$(get_recommended_voice_for_language "$language")
+    if [[ -n "$recommended_voice" ]]; then
+        echo "$recommended_voice" > "$TARGET_VOICE_FILE"
+        echo -e "${GREEN}✓${NC} Target voice automatically set to: ${YELLOW}$recommended_voice${NC}"
+
+        # Detect provider for display
+        local provider=""
+        if [[ -f "$PROJECT_DIR/.claude/tts-provider.txt" ]]; then
+            provider=$(cat "$PROJECT_DIR/.claude/tts-provider.txt")
+        elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+            provider=$(cat "$HOME/.claude/tts-provider.txt")
+        else
+            provider="elevenlabs"
+        fi
+        echo -e "   (for ${GREEN}$provider${NC} TTS)"
+        echo ""
+
+        # Greet user in the target language with the target voice
+        local greeting=$(get_greeting_for_language "$language")
+        echo -e "${BLUE}🎓${NC} Your language teacher says:"
+
+        # Check if we're using Piper and if the voice is available
+        if [[ "$provider" == "piper" ]]; then
+            # Quick check: does the voice file exist?
+            local voice_dir="${HOME}/.claude/piper-voices"
+            if [[ -f "${voice_dir}/${recommended_voice}.onnx" ]]; then
+                # Voice exists, play greeting in background
+                nohup "$SCRIPT_DIR/play-tts.sh" "$greeting" "$recommended_voice" >/dev/null 2>&1 &
+            else
+                echo -e "${YELLOW}   (Voice not yet downloaded - greeting will play after first download)${NC}"
+            fi
+        else
+            # ElevenLabs - just play it in background
+            nohup "$SCRIPT_DIR/play-tts.sh" "$greeting" "$recommended_voice" >/dev/null 2>&1 &
+        fi
+    else
+        # Fallback to suggestion if auto-set failed
+        suggest_voice_for_language "$language"
+    fi
+}
+
+# Get recommended voice for a language (returns voice string, no output)
+get_recommended_voice_for_language() {
+    local language="$1"
+    local recommended_voice=""
+    local provider=""
+
+    # Detect active provider
+    if [[ -f "$PROJECT_DIR/.claude/tts-provider.txt" ]]; then
+        provider=$(cat "$PROJECT_DIR/.claude/tts-provider.txt")
+    elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+        provider=$(cat "$HOME/.claude/tts-provider.txt")
+    else
+        provider="elevenlabs"  # Default
+    fi
+
+    # Source language manager and get provider-specific voice
+    if [[ -f "$SCRIPT_DIR/language-manager.sh" ]]; then
+        source "$SCRIPT_DIR/language-manager.sh" 2>/dev/null
+        recommended_voice=$(get_voice_for_language "$language" "$provider" 2>/dev/null)
+    fi
+
+    # Fallback to hardcoded suggestions if function failed
+    if [[ -z "$recommended_voice" ]]; then
+        case "${language,,}" in
+            spanish|español)
+                recommended_voice=$([ "$provider" = "piper" ] && echo "es_ES-davefx-medium" || echo "Antoni")
+                ;;
+            french|français)
+                recommended_voice=$([ "$provider" = "piper" ] && echo "fr_FR-siwis-medium" || echo "Rachel")
+                ;;
+            german|deutsch)
+                recommended_voice=$([ "$provider" = "piper" ] && echo "de_DE-thorsten-medium" || echo "Domi")
+                ;;
+            italian|italiano)
+                recommended_voice=$([ "$provider" = "piper" ] && echo "it_IT-riccardo-x_low" || echo "Bella")
+                ;;
+            portuguese|português)
+                recommended_voice=$([ "$provider" = "piper" ] && echo "pt_BR-faber-medium" || echo "Matilda")
+                ;;
+            chinese|中文|mandarin)
+                recommended_voice=$([ "$provider" = "piper" ] && echo "zh_CN-huayan-medium" || echo "Amy")
+                ;;
+            *)
+                recommended_voice=$([ "$provider" = "piper" ] && echo "en_US-lessac-medium" || echo "Antoni")
+                ;;
+        esac
+    fi
+
+    echo "$recommended_voice"
+}
+
+# Suggest voice based on target language (displays suggestion message)
+suggest_voice_for_language() {
+    local language="$1"
+    local suggested_voice=$(get_recommended_voice_for_language "$language")
+
+    # Detect provider for display
+    local provider=""
+    if [[ -f "$PROJECT_DIR/.claude/tts-provider.txt" ]]; then
+        provider=$(cat "$PROJECT_DIR/.claude/tts-provider.txt")
+    elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+        provider=$(cat "$HOME/.claude/tts-provider.txt")
+    else
+        provider="elevenlabs"
+    fi
+
+    echo ""
+    echo -e "${BLUE}💡 Tip:${NC} For $language (using ${GREEN}$provider${NC} TTS), we recommend: ${YELLOW}$suggested_voice${NC}"
+    echo -e "   Set it with: ${YELLOW}/agent-vibes:target-voice $suggested_voice${NC}"
+}
+
+# Get target voice
+get_target_voice() {
+    if [[ -f "$TARGET_VOICE_FILE" ]]; then
+        cat "$TARGET_VOICE_FILE"
+    elif [[ -f "$GLOBAL_TARGET_VOICE_FILE" ]]; then
+        cat "$GLOBAL_TARGET_VOICE_FILE"
+    else
+        echo ""
+    fi
+}
+
+# Set target voice
+set_target_voice() {
+    local voice="$1"
+    if [[ -z "$voice" ]]; then
+        echo -e "${YELLOW}Usage: learn-manager.sh set-target-voice <voice>${NC}"
+        exit 1
+    fi
+
+    mkdir -p "$PROJECT_DIR/.claude"
+    echo "$voice" > "$TARGET_VOICE_FILE"
+    echo -e "${GREEN}✓${NC} Target voice set to: $voice"
+}
+
+# Check if learning mode is enabled
+is_learn_mode_enabled() {
+    if [[ -f "$LEARN_MODE_FILE" ]]; then
+        local mode=$(cat "$LEARN_MODE_FILE")
+        [[ "$mode" == "ON" ]]
+    elif [[ -f "$GLOBAL_LEARN_MODE_FILE" ]]; then
+        local mode=$(cat "$GLOBAL_LEARN_MODE_FILE")
+        [[ "$mode" == "ON" ]]
+    else
+        return 1
+    fi
+}
+
+# Enable learning mode
+enable_learn_mode() {
+    mkdir -p "$PROJECT_DIR/.claude"
+    echo "ON" > "$LEARN_MODE_FILE"
+    echo -e "${GREEN}✓${NC} Language learning mode: ${GREEN}ENABLED${NC}"
+    echo ""
+
+    # Auto-set target voice if target language is set but voice is not
+    local target_lang=$(get_target_language)
+    local target_voice=$(get_target_voice)
+    local voice_was_set=false
+
+    if [[ -n "$target_lang" ]] && [[ -z "$target_voice" ]]; then
+        echo -e "${BLUE}ℹ${NC}  Auto-configuring voice for $target_lang..."
+        local recommended_voice=$(get_recommended_voice_for_language "$target_lang")
+        if [[ -n "$recommended_voice" ]]; then
+            echo "$recommended_voice" > "$TARGET_VOICE_FILE"
+            target_voice="$recommended_voice"
+            echo -e "${GREEN}✓${NC} Target voice automatically set to: ${YELLOW}$recommended_voice${NC}"
+
+            # Detect provider for display
+            local provider=""
+            if [[ -f "$PROJECT_DIR/.claude/tts-provider.txt" ]]; then
+                provider=$(cat "$PROJECT_DIR/.claude/tts-provider.txt")
+            elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+                provider=$(cat "$HOME/.claude/tts-provider.txt")
+            else
+                provider="elevenlabs"
+            fi
+            echo -e "   (for ${GREEN}$provider${NC} TTS)"
+            echo ""
+            voice_was_set=true
+        fi
+    fi
+
+    show_status
+
+    # Greet user with language teacher if everything is configured
+    if [[ -n "$target_lang" ]] && [[ -n "$target_voice" ]]; then
+        echo ""
+        local greeting=$(get_greeting_for_language "$target_lang")
+        echo -e "${BLUE}🎓${NC} Your language teacher says:"
+
+        # Detect provider
+        local provider=""
+        if [[ -f "$PROJECT_DIR/.claude/tts-provider.txt" ]]; then
+            provider=$(cat "$PROJECT_DIR/.claude/tts-provider.txt")
+        elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+            provider=$(cat "$HOME/.claude/tts-provider.txt")
+        else
+            provider="elevenlabs"
+        fi
+
+        # Check if we're using Piper and if the voice is available
+        if [[ "$provider" == "piper" ]]; then
+            # Quick check: does the voice file exist?
+            local voice_dir="${HOME}/.claude/piper-voices"
+            if [[ -f "${voice_dir}/${target_voice}.onnx" ]]; then
+                # Voice exists, play greeting in background
+                nohup "$SCRIPT_DIR/play-tts.sh" "$greeting" "$target_voice" >/dev/null 2>&1 &
+            else
+                echo -e "${YELLOW}   (Voice not yet downloaded - greeting will play after first download)${NC}"
+            fi
+        else
+            # ElevenLabs - just play it in background
+            nohup "$SCRIPT_DIR/play-tts.sh" "$greeting" "$target_voice" >/dev/null 2>&1 &
+        fi
+    fi
+}
+
+# Disable learning mode
+disable_learn_mode() {
+    mkdir -p "$PROJECT_DIR/.claude"
+    echo "OFF" > "$LEARN_MODE_FILE"
+    echo -e "${GREEN}✓${NC} Language learning mode: ${YELLOW}DISABLED${NC}"
+}
+
+# Show learning mode status
+show_status() {
+    local main_lang=$(get_main_language)
+    local target_lang=$(get_target_language)
+    local target_voice=$(get_target_voice)
+    local learn_mode="OFF"
+
+    if is_learn_mode_enabled; then
+        learn_mode="ON"
+    fi
+
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${BLUE}   Language Learning Mode Status${NC}"
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo ""
+    echo -e "  ${BLUE}Learning Mode:${NC}    $(if [[ "$learn_mode" == "ON" ]]; then echo -e "${GREEN}ENABLED${NC}"; else echo -e "${YELLOW}DISABLED${NC}"; fi)"
+    echo -e "  ${BLUE}Main Language:${NC}    $main_lang"
+    echo -e "  ${BLUE}Target Language:${NC}  ${target_lang:-"(not set)"}"
+    echo -e "  ${BLUE}Target Voice:${NC}     ${target_voice:-"(not set)"}"
+    echo ""
+
+    if [[ "$learn_mode" == "ON" ]]; then
+        if [[ -z "$target_lang" ]]; then
+            echo -e "  ${YELLOW}⚠${NC}  Please set a target language: ${YELLOW}/agent-vibes:target <language>${NC}"
+        fi
+        if [[ -z "$target_voice" ]]; then
+            echo -e "  ${YELLOW}⚠${NC}  Please set a target voice: ${YELLOW}/agent-vibes:target-voice <voice>${NC}"
+        fi
+
+        if [[ -n "$target_lang" ]] && [[ -n "$target_voice" ]]; then
+            echo -e "  ${GREEN}✓${NC}  All set! TTS will speak in both languages."
+            echo ""
+            echo -e "  ${BLUE}How it works:${NC}"
+            echo -e "    1. First: Speak in ${BLUE}$main_lang${NC} (your current voice)"
+            echo -e "    2. Then: Speak in ${BLUE}$target_lang${NC} ($target_voice voice)"
+        fi
+    else
+        echo -e "  ${BLUE}💡 Tip:${NC} Enable learning mode with: ${YELLOW}/agent-vibes:learn${NC}"
+    fi
+
+    echo ""
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+}
+
+# Main command handler
+case "${1:-}" in
+    get-main-language)
+        get_main_language
+        ;;
+    set-main-language)
+        set_main_language "$2"
+        ;;
+    get-target-language)
+        get_target_language
+        ;;
+    set-target-language)
+        set_target_language "$2"
+        ;;
+    get-target-voice)
+        get_target_voice
+        ;;
+    set-target-voice)
+        set_target_voice "$2"
+        ;;
+    is-enabled)
+        if is_learn_mode_enabled; then
+            echo "ON"
+            exit 0
+        else
+            echo "OFF"
+            exit 1
+        fi
+        ;;
+    enable)
+        enable_learn_mode
+        ;;
+    disable)
+        disable_learn_mode
+        ;;
+    status)
+        show_status
+        ;;
+    *)
+        echo "Usage: learn-manager.sh {get-main-language|set-main-language|get-target-language|set-target-language|get-target-voice|set-target-voice|is-enabled|enable|disable|status}"
+        exit 1
+        ;;
+esac
--- a/.claude/hooks/personality-manager.sh
+++ b/.claude/hooks/personality-manager.sh
@@ -0,0 +1,438 @@
+#!/bin/bash
+#
+# File: .claude/hooks/personality-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. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Personality Manager - Adds character and emotional style to TTS voices
+# @context Enables voices to have distinct personalities (flirty, sarcastic, pirate, etc.) with provider-aware voice assignment
+# @architecture Markdown-based personality templates with provider-specific voice mappings (ElevenLabs vs Piper)
+# @dependencies .claude/personalities/*.md files, voice-manager.sh, play-tts.sh, provider-manager.sh
+# @entrypoints Called by /agent-vibes:personality slash commands
+# @patterns Template-based configuration, provider abstraction, random personality support
+# @related .claude/personalities/*.md, voice-manager.sh, .claude/tts-personality.txt
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PERSONALITIES_DIR="$SCRIPT_DIR/../personalities"
+
+# Determine target .claude directory based on context
+# Priority:
+# 1. CLAUDE_PROJECT_DIR env var (set by MCP for project-specific settings)
+# 2. Script location (for direct slash command usage)
+# 3. Global ~/.claude (fallback)
+
+if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+  # MCP context: Use the project directory where MCP was invoked
+  CLAUDE_DIR="$CLAUDE_PROJECT_DIR/.claude"
+else
+  # Direct usage context: Use script location
+  # Script is at .claude/hooks/personality-manager.sh, so .claude is ..
+  CLAUDE_DIR="$(cd "$SCRIPT_DIR/.." 2>/dev/null && pwd)"
+
+  # If script is in global ~/.claude, use that
+  if [[ "$CLAUDE_DIR" == "$HOME/.claude" ]]; then
+    CLAUDE_DIR="$HOME/.claude"
+  elif [[ ! -d "$CLAUDE_DIR" ]]; then
+    # Fallback to global if directory doesn't exist
+    CLAUDE_DIR="$HOME/.claude"
+  fi
+fi
+
+PERSONALITY_FILE="$CLAUDE_DIR/tts-personality.txt"
+
+# Function to get personality data from markdown file
+get_personality_data() {
+  local personality="$1"
+  local field="$2"
+  local file="$PERSONALITIES_DIR/${personality}.md"
+
+  if [[ ! -f "$file" ]]; then
+    return 1
+  fi
+
+  case "$field" in
+    prefix)
+      sed -n '/^## Prefix/,/^##/p' "$file" | sed '1d;$d' | tr -d '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'
+      ;;
+    suffix)
+      sed -n '/^## Suffix/,/^##/p' "$file" | sed '1d;$d' | tr -d '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'
+      ;;
+    description)
+      grep "^description:" "$file" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'
+      ;;
+    voice)
+      grep "^elevenlabs_voice:" "$file" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'
+      ;;
+    piper_voice)
+      grep "^piper_voice:" "$file" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'
+      ;;
+    instructions)
+      sed -n '/^## AI Instructions/,/^##/p' "$file" | sed '1d;$d'
+      ;;
+  esac
+}
+
+# Function to list all available personalities
+list_personalities() {
+  local personalities=()
+
+  # Find all .md files in personalities directory
+  if [[ -d "$PERSONALITIES_DIR" ]]; then
+    for file in "$PERSONALITIES_DIR"/*.md; do
+      if [[ -f "$file" ]]; then
+        basename "$file" .md
+      fi
+    done
+  fi
+}
+
+case "$1" in
+  list)
+    echo "🎭 Available Personalities:"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    # Get current personality
+    CURRENT="normal"
+    if [ -f "$PERSONALITY_FILE" ]; then
+      CURRENT=$(cat "$PERSONALITY_FILE")
+    fi
+
+    # List personalities from markdown files
+    echo "Built-in personalities:"
+    for personality in $(list_personalities | sort); do
+      desc=$(get_personality_data "$personality" "description")
+      if [[ "$personality" == "$CURRENT" ]]; then
+        echo "  ✓ $personality - $desc (current)"
+      else
+        echo "  - $personality - $desc"
+      fi
+    done
+
+    # Add random option
+    if [[ "$CURRENT" == "random" ]]; then
+      echo "  ✓ random - Picks randomly each time (current)"
+    else
+      echo "  - random - Picks randomly each time"
+    fi
+
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "Usage: /agent-vibes:personality <name>"
+    echo "       /agent-vibes:personality add <name>"
+    echo "       /agent-vibes:personality edit <name>"
+    ;;
+
+  set|switch)
+    PERSONALITY="$2"
+
+    if [[ -z "$PERSONALITY" ]]; then
+      echo "❌ Please specify a personality name"
+      echo "Usage: $0 set <personality>"
+      exit 1
+    fi
+
+    # Check if personality file exists (unless it's random)
+    if [[ "$PERSONALITY" != "random" ]]; then
+      if [[ ! -f "$PERSONALITIES_DIR/${PERSONALITY}.md" ]]; then
+        echo "❌ Personality not found: $PERSONALITY"
+        echo ""
+        echo "Available personalities:"
+        for p in $(list_personalities | sort); do
+          echo "  • $p"
+        done
+        exit 1
+      fi
+    fi
+
+    # Save the personality
+    echo "$PERSONALITY" > "$PERSONALITY_FILE"
+    echo "🎭 Personality set to: $PERSONALITY"
+
+    # Check if personality has an assigned voice
+    # Detect active TTS provider
+    PROVIDER_FILE=""
+    if [[ -f "$CLAUDE_DIR/tts-provider.txt" ]]; then
+      PROVIDER_FILE="$CLAUDE_DIR/tts-provider.txt"
+    elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+      PROVIDER_FILE="$HOME/.claude/tts-provider.txt"
+    fi
+
+    ACTIVE_PROVIDER="elevenlabs"  # default
+    if [[ -n "$PROVIDER_FILE" ]]; then
+      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+    fi
+
+    # Get the appropriate voice based on provider
+    ASSIGNED_VOICE=""
+    if [[ "$ACTIVE_PROVIDER" == "piper" ]]; then
+      # Try to get Piper-specific voice first
+      ASSIGNED_VOICE=$(get_personality_data "$PERSONALITY" "piper_voice")
+      if [[ -z "$ASSIGNED_VOICE" ]]; then
+        # Fallback to default Piper voice
+        ASSIGNED_VOICE="en_US-lessac-medium"
+      fi
+    else
+      # Use ElevenLabs voice (reads from elevenlabs_voice: field)
+      ASSIGNED_VOICE=$(get_personality_data "$PERSONALITY" "voice")
+    fi
+
+    if [[ -n "$ASSIGNED_VOICE" ]]; then
+      # Switch to the assigned voice (silently - personality will do the talking)
+      VOICE_MANAGER="$SCRIPT_DIR/voice-manager.sh"
+      if [[ -x "$VOICE_MANAGER" ]]; then
+        echo "🎤 Switching to assigned voice: $ASSIGNED_VOICE"
+        "$VOICE_MANAGER" switch "$ASSIGNED_VOICE" --silent >/dev/null 2>&1
+      fi
+    fi
+
+    # Make a personality-appropriate remark with TTS
+    if [[ "$PERSONALITY" != "random" ]]; then
+      echo ""
+
+      # Get TTS script path
+      TTS_SCRIPT="$SCRIPT_DIR/play-tts.sh"
+
+      # Try to get acknowledgment from personality file
+      PERSONALITY_FILE_PATH="$PERSONALITIES_DIR/${PERSONALITY}.md"
+      REMARK=""
+
+      if [[ -f "$PERSONALITY_FILE_PATH" ]]; then
+        # Extract example responses from personality file (lines starting with "- ")
+        mapfile -t EXAMPLES < <(grep '^- "' "$PERSONALITY_FILE_PATH" | sed 's/^- "//; s/"$//')
+
+        if [[ ${#EXAMPLES[@]} -gt 0 ]]; then
+          # Pick a random example
+          REMARK="${EXAMPLES[$RANDOM % ${#EXAMPLES[@]}]}"
+        fi
+      fi
+
+      # Fallback if no examples found
+      if [[ -z "$REMARK" ]]; then
+        REMARK="Personality set to ${PERSONALITY}!"
+      fi
+
+      echo "💬 $REMARK"
+      "$TTS_SCRIPT" "$REMARK"
+
+      echo ""
+      echo "Note: AI will generate unique ${PERSONALITY} responses - no fixed templates!"
+      echo ""
+      echo "💡 Tip: To hear automatic TTS narration, enable the Agent Vibes output style:"
+      echo "   /output-style Agent Vibes"
+    fi
+    ;;
+
+  get)
+    if [ -f "$PERSONALITY_FILE" ]; then
+      CURRENT=$(cat "$PERSONALITY_FILE")
+      echo "Current personality: $CURRENT"
+
+      if [[ "$CURRENT" != "random" ]]; then
+        desc=$(get_personality_data "$CURRENT" "description")
+        [[ -n "$desc" ]] && echo "Description: $desc"
+      fi
+    else
+      echo "Current personality: normal (default)"
+    fi
+    ;;
+
+  add)
+    NAME="$2"
+    if [[ -z "$NAME" ]]; then
+      echo "❌ Please specify a personality name"
+      echo "Usage: $0 add <name>"
+      exit 1
+    fi
+
+    FILE="$PERSONALITIES_DIR/${NAME}.md"
+    if [[ -f "$FILE" ]]; then
+      echo "❌ Personality '$NAME' already exists"
+      echo "Use 'edit' to modify it"
+      exit 1
+    fi
+
+    # Create new personality file
+    cat > "$FILE" << 'EOF'
+---
+name: NAME
+description: Custom personality
+---
+
+# NAME Personality
+
+## Prefix
+
+
+## Suffix
+
+
+## AI Instructions
+Describe how the AI should generate messages for this personality.
+
+## Example Responses
+- "Example response 1"
+- "Example response 2"
+EOF
+
+    # Replace NAME with actual name
+    sed -i "s/NAME/$NAME/g" "$FILE"
+
+    echo "✅ Created new personality: $NAME"
+    echo "📝 Edit the file: $FILE"
+    echo ""
+    echo "You can now customize:"
+    echo "  • Prefix: Text before messages"
+    echo "  • Suffix: Text after messages"
+    echo "  • AI Instructions: How AI should speak"
+    echo "  • Example Responses: Sample messages"
+    ;;
+
+  edit)
+    NAME="$2"
+    if [[ -z "$NAME" ]]; then
+      echo "❌ Please specify a personality name"
+      echo "Usage: $0 edit <name>"
+      exit 1
+    fi
+
+    FILE="$PERSONALITIES_DIR/${NAME}.md"
+    if [[ ! -f "$FILE" ]]; then
+      echo "❌ Personality '$NAME' not found"
+      echo "Use 'add' to create it first"
+      exit 1
+    fi
+
+    echo "📝 Edit this file to customize the personality:"
+    echo "$FILE"
+    ;;
+
+  reset)
+    echo "normal" > "$PERSONALITY_FILE"
+    echo "🎭 Personality reset to: normal"
+    ;;
+
+  set-favorite-voice)
+    PERSONALITY="$2"
+    NEW_VOICE="$3"
+
+    if [[ -z "$PERSONALITY" ]] || [[ -z "$NEW_VOICE" ]]; then
+      echo "❌ Please specify both personality name and voice name"
+      echo "Usage: $0 set-favorite-voice <personality> <voice>"
+      exit 1
+    fi
+
+    FILE="$PERSONALITIES_DIR/${PERSONALITY}.md"
+    if [[ ! -f "$FILE" ]]; then
+      echo "❌ Personality '$PERSONALITY' not found"
+      exit 1
+    fi
+
+    # Detect active TTS provider
+    PROVIDER_FILE=""
+    if [[ -f "$CLAUDE_DIR/tts-provider.txt" ]]; then
+      PROVIDER_FILE="$CLAUDE_DIR/tts-provider.txt"
+    elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+      PROVIDER_FILE="$HOME/.claude/tts-provider.txt"
+    fi
+
+    ACTIVE_PROVIDER="elevenlabs"  # default
+    if [[ -n "$PROVIDER_FILE" ]]; then
+      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+    fi
+
+    # Determine which field to update based on provider
+    if [[ "$ACTIVE_PROVIDER" == "piper" ]]; then
+      VOICE_FIELD="piper_voice"
+      CURRENT_VOICE=$(get_personality_data "$PERSONALITY" "piper_voice")
+    else
+      VOICE_FIELD="elevenlabs_voice"
+      CURRENT_VOICE=$(get_personality_data "$PERSONALITY" "voice")
+    fi
+
+    # Check if personality already has a favorite voice assigned
+    if [[ -n "$CURRENT_VOICE" ]] && [[ "$CURRENT_VOICE" != "$NEW_VOICE" ]]; then
+      echo "⚠️  WARNING: Personality '$PERSONALITY' already has a favorite voice assigned!"
+      echo ""
+      echo "   Current favorite ($ACTIVE_PROVIDER): $CURRENT_VOICE"
+      echo "   New voice: $NEW_VOICE"
+      echo ""
+      echo "Do you want to replace the favorite voice?"
+      echo ""
+      read -p "Enter your choice (yes/no): " CHOICE
+
+      case "$CHOICE" in
+        yes|y|YES|Y)
+          echo "✅ Replacing favorite voice..."
+          ;;
+        no|n|NO|N)
+          echo "❌ Keeping current favorite voice: $CURRENT_VOICE"
+          exit 0
+          ;;
+        *)
+          echo "❌ Invalid choice. Keeping current favorite voice: $CURRENT_VOICE"
+          exit 1
+          ;;
+      esac
+    fi
+
+    # Update the voice in the personality file
+    if grep -q "^${VOICE_FIELD}:" "$FILE"; then
+      # Field exists, replace it
+      sed -i "s/^${VOICE_FIELD}:.*/${VOICE_FIELD}: ${NEW_VOICE}/" "$FILE"
+    else
+      # Field doesn't exist, add it after the frontmatter
+      sed -i "/^---$/,/^---$/ { /^---$/a\\
+${VOICE_FIELD}: ${NEW_VOICE}
+}" "$FILE"
+    fi
+
+    echo "✅ Favorite voice for '$PERSONALITY' personality set to: $NEW_VOICE ($ACTIVE_PROVIDER)"
+    echo "📝 Updated file: $FILE"
+    ;;
+
+  *)
+    # If a single argument is provided and it's not a command, treat it as "set <personality>"
+    if [[ -n "$1" ]] && [[ -f "$PERSONALITIES_DIR/${1}.md" || "$1" == "random" ]]; then
+      # Call set with the personality name
+      exec "$0" set "$1"
+    else
+      echo "AgentVibes Personality Manager"
+      echo ""
+      echo "Commands:"
+      echo "  list                              - List all personalities"
+      echo "  set/switch <name>                 - Set personality"
+      echo "  add <name>                        - Create new personality"
+      echo "  edit <name>                       - Show path to edit personality"
+      echo "  get                               - Show current personality"
+      echo "  set-favorite-voice <name> <voice> - Set favorite voice for a personality"
+      echo "  reset                             - Reset to normal"
+      echo ""
+      echo "Examples:"
+      echo "  /agent-vibes:personality flirty"
+      echo "  /agent-vibes:personality add cowboy"
+      echo "  /agent-vibes:personality set-favorite-voice flirty \"Aria\""
+    fi
+    ;;
+esac
--- a/.claude/hooks/piper-download-voices.sh
+++ b/.claude/hooks/piper-download-voices.sh
@@ -0,0 +1,165 @@
+#!/bin/bash
+#
+# File: .claude/hooks/piper-download-voices.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 Downloader - Batch downloads popular Piper TTS voices from HuggingFace
+# @context Post-installation utility to download commonly used voices (~25MB each)
+# @architecture Wrapper around piper-voice-manager.sh download functions with progress tracking
+# @dependencies piper-voice-manager.sh (download logic), piper binary (for validation)
+# @entrypoints Called by piper-installer.sh or manually via ./piper-download-voices.sh [--yes|-y]
+# @patterns Batch operations, skip-existing logic, auto-yes flag for non-interactive use
+# @related piper-voice-manager.sh, piper-installer.sh
+#
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/piper-voice-manager.sh"
+
+# Parse command line arguments
+AUTO_YES=false
+if [[ "$1" == "--yes" ]] || [[ "$1" == "-y" ]]; then
+  AUTO_YES=true
+fi
+
+# Common voice models to download
+COMMON_VOICES=(
+  "en_US-lessac-medium"      # Default, clear male
+  "en_US-amy-medium"         # Warm female
+  "en_US-joe-medium"         # Professional male
+  "en_US-ryan-high"          # Expressive male
+  "en_US-libritts-high"      # Premium quality
+)
+
+echo "🎙️  Piper Voice Model Downloader"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "This will download the most commonly used Piper voice models."
+echo "Each voice is approximately 25MB."
+echo ""
+
+# Check if piper is installed
+if ! command -v piper &> /dev/null; then
+  echo "❌ Error: Piper TTS not installed"
+  echo "Install with: pipx install piper-tts"
+  exit 1
+fi
+
+# Get storage directory
+VOICE_DIR=$(get_voice_storage_dir)
+
+echo "📂 Storage location: $VOICE_DIR"
+echo ""
+
+# Count already downloaded
+ALREADY_DOWNLOADED=0
+ALREADY_DOWNLOADED_LIST=()
+NEED_DOWNLOAD=()
+
+for voice in "${COMMON_VOICES[@]}"; do
+  if verify_voice "$voice" 2>/dev/null; then
+    ((ALREADY_DOWNLOADED++))
+    ALREADY_DOWNLOADED_LIST+=("$voice")
+  else
+    NEED_DOWNLOAD+=("$voice")
+  fi
+done
+
+echo "📊 Status:"
+echo "   Already downloaded: $ALREADY_DOWNLOADED voice(s)"
+echo "   Need to download: ${#NEED_DOWNLOAD[@]} voice(s)"
+echo ""
+
+# Show already downloaded voices
+if [[ $ALREADY_DOWNLOADED -gt 0 ]]; then
+  echo "✅ Already downloaded (skipped):"
+  for voice in "${ALREADY_DOWNLOADED_LIST[@]}"; do
+    echo "   ✓ $voice"
+  done
+  echo ""
+fi
+
+if [[ ${#NEED_DOWNLOAD[@]} -eq 0 ]]; then
+  echo "🎉 All common voices ready to use!"
+  exit 0
+fi
+
+echo "Voices to download:"
+for voice in "${NEED_DOWNLOAD[@]}"; do
+  echo "  • $voice (~25MB)"
+done
+echo ""
+
+# Ask for confirmation (skip if --yes flag provided)
+if [[ "$AUTO_YES" == "false" ]]; then
+  read -p "Download ${#NEED_DOWNLOAD[@]} voice model(s)? [Y/n]: " -n 1 -r
+  echo
+
+  if [[ ! $REPLY =~ ^[Yy]$ ]] && [[ -n $REPLY ]]; then
+    echo "❌ Download cancelled"
+    exit 0
+  fi
+else
+  echo "Auto-downloading ${#NEED_DOWNLOAD[@]} voice model(s)..."
+  echo ""
+fi
+
+# Download each voice
+DOWNLOADED=0
+FAILED=0
+
+for voice in "${NEED_DOWNLOAD[@]}"; do
+  echo ""
+  echo "📥 Downloading: $voice..."
+
+  if download_voice "$voice"; then
+    ((DOWNLOADED++))
+    echo "✅ Downloaded: $voice"
+  else
+    ((FAILED++))
+    echo "❌ Failed: $voice"
+  fi
+done
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "📊 Download Summary:"
+echo "   ✅ Successfully downloaded: $DOWNLOADED"
+echo "   ❌ Failed: $FAILED"
+echo "   📦 Total voices available: $((ALREADY_DOWNLOADED + DOWNLOADED))"
+echo ""
+
+if [[ $DOWNLOADED -gt 0 ]]; then
+  echo "✨ Ready to use Piper TTS with downloaded voices!"
+  echo ""
+  echo "Try it:"
+  echo "  /agent-vibes:provider switch piper"
+  echo "  /agent-vibes:preview"
+fi
--- a/.claude/hooks/piper-installer.sh
+++ b/.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 "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
--- a/.claude/hooks/piper-multispeaker-registry.sh
+++ b/.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
+}
--- a/.claude/hooks/piper-voice-manager.sh
+++ b/.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
--- a/.claude/hooks/play-tts-elevenlabs.sh
+++ b/.claude/hooks/play-tts-elevenlabs.sh
@@ -0,0 +1,404 @@
+#!/bin/bash
+#
+# File: .claude/hooks/play-tts-elevenlabs.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. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview ElevenLabs TTS Provider Implementation - Premium cloud-based TTS
+# @context Provider-specific implementation for ElevenLabs API integration with multilingual support
+# @architecture Part of multi-provider TTS system - implements provider interface contract
+# @dependencies Requires ELEVENLABS_API_KEY, curl, ffmpeg, paplay/aplay/mpg123, jq
+# @entrypoints Called by play-tts.sh router with ($1=text, $2=voice_name) when provider=elevenlabs
+# @patterns Follows provider contract: accept text/voice, output audio file path, API error handling, SSH audio optimization
+# @related play-tts.sh, provider-manager.sh, voices-config.sh, language-manager.sh, GitHub Issue #25
+#
+
+# Fix locale warnings
+export LC_ALL=C
+
+TEXT="$1"
+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_FILE="$CONFIG_DIR/agentvibes.json"
+
+if [[ -f "$CONFIG_FILE" ]] && command -v jq &> /dev/null; then
+  PRETEXT=$(jq -r '.pretext // empty' "$CONFIG_FILE" 2>/dev/null)
+  if [[ -n "$PRETEXT" ]]; then
+    TEXT="$PRETEXT: $TEXT"
+  fi
+fi
+
+# Limit text length to prevent API issues (max 500 chars for safety)
+if [ ${#TEXT} -gt 500 ]; then
+  TEXT="${TEXT:0:497}..."
+  echo "⚠️ Text truncated to 500 characters for API safety"
+fi
+
+# Source the single voice configuration file
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/voices-config.sh"
+source "$SCRIPT_DIR/language-manager.sh"
+
+# @function determine_voice_and_language
+# @intent Resolve voice name/ID and language for multilingual support
+# @why Supports both voice names and direct IDs, plus language-specific voices
+# @param $VOICE_OVERRIDE {string} Voice name or ID (optional)
+# @returns Sets $VOICE_ID and $LANGUAGE_CODE global variables
+# @sideeffects None
+# @edgecases Handles unknown voices, falls back to default
+VOICE_ID=""
+LANGUAGE_CODE="en"  # Default to English
+
+# Get current language setting
+CURRENT_LANGUAGE=$(get_language_code)
+
+# Get language code for API
+# 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)
+  if [[ -n "${VOICES[$VOICE_OVERRIDE]}" ]]; then
+    VOICE_ID="${VOICES[$VOICE_OVERRIDE]}"
+    echo "🎤 Using voice: $VOICE_OVERRIDE (session-specific)"
+  # Check if override looks like a voice ID (alphanumeric string ~20 chars)
+  elif [[ "$VOICE_OVERRIDE" =~ ^[a-zA-Z0-9]{15,30}$ ]]; then
+    VOICE_ID="$VOICE_OVERRIDE"
+    echo "🎤 Using custom voice ID (session-specific)"
+  else
+    echo "⚠️ Unknown voice '$VOICE_OVERRIDE', trying language-specific voice"
+  fi
+fi
+
+# If no override or invalid override, use language-specific voice
+if [[ -z "$VOICE_ID" ]]; then
+  # Try to get voice for current language
+  LANG_VOICE=$(get_voice_for_language "$CURRENT_LANGUAGE" "elevenlabs" 2>/dev/null)
+
+  if [[ -n "$LANG_VOICE" ]] && [[ -n "${VOICES[$LANG_VOICE]}" ]]; then
+    VOICE_ID="${VOICES[$LANG_VOICE]}"
+    echo "🌍 Using $CURRENT_LANGUAGE voice: $LANG_VOICE"
+  else
+    # Fall back to voice manager
+    VOICE_MANAGER_SCRIPT="$(dirname "$0")/voice-manager.sh"
+    if [[ -f "$VOICE_MANAGER_SCRIPT" ]]; then
+      VOICE_NAME=$("$VOICE_MANAGER_SCRIPT" get)
+      VOICE_ID="${VOICES[$VOICE_NAME]}"
+    fi
+
+    # Final fallback to default
+    if [[ -z "$VOICE_ID" ]]; then
+      echo "⚠️ No voice configured, using default"
+      VOICE_ID="${VOICES[Aria]}"
+    fi
+  fi
+fi
+
+# @function validate_inputs
+# @intent Check required parameters and API key
+# @why Fail fast with clear errors if inputs missing
+# @exitcode 1=missing text, 2=missing API key
+if [ -z "$TEXT" ]; then
+  echo "Usage: $0 \"text to speak\" [voice_name_or_id]"
+  exit 1
+fi
+
+if [ -z "$API_KEY" ]; then
+  echo "Error: ELEVENLABS_API_KEY not set"
+  echo "Set your API key: export ELEVENLABS_API_KEY=your_key_here"
+  exit 2
+fi
+
+# @function determine_audio_directory
+# @intent Find appropriate directory for audio file storage
+# @why Supports project-local and global storage
+# @returns Sets $AUDIO_DIR global variable
+# @sideeffects None
+# @edgecases Handles missing directories, creates if needed
+# AI NOTE: Check project dir first, then search up tree, finally fall back to global
+if [[ -n "$CLAUDE_PROJECT_DIR" ]]; then
+  AUDIO_DIR="$CLAUDE_PROJECT_DIR/.claude/audio"
+else
+  # Fallback: try to find .claude directory in current path
+  CURRENT_DIR="$PWD"
+  while [[ "$CURRENT_DIR" != "/" ]]; do
+    if [[ -d "$CURRENT_DIR/.claude" ]]; then
+      AUDIO_DIR="$CURRENT_DIR/.claude/audio"
+      break
+    fi
+    CURRENT_DIR=$(dirname "$CURRENT_DIR")
+  done
+  # Final fallback to global if no project .claude found
+  if [[ -z "$AUDIO_DIR" ]]; then
+    AUDIO_DIR="$HOME/.claude/audio"
+  fi
+fi
+
+mkdir -p "$AUDIO_DIR"
+TEMP_FILE="$AUDIO_DIR/tts-$(date +%s).mp3"
+
+# @function synthesize_with_elevenlabs
+# @intent Call ElevenLabs API to generate speech
+# @why Encapsulates API call with error handling
+# @param Uses globals: $TEXT, $VOICE_ID, $API_KEY
+# @returns Creates audio file at $TEMP_FILE
+# @exitcode 0=success, 3=API error
+# @sideeffects Creates MP3 file in audio directory
+# @edgecases Handles network failures, API errors, rate limiting
+# Choose model based on language
+if [[ "$LANGUAGE_CODE" == "en" ]]; then
+  MODEL_ID="eleven_monolingual_v1"
+else
+  MODEL_ID="eleven_multilingual_v2"
+fi
+
+# @function get_speech_speed
+# @intent Read speed config and map to ElevenLabs API range (0.7-1.2)
+# @why ElevenLabs only supports 0.7 (slower) to 1.2 (faster), must map user scale
+# @returns Speed value for ElevenLabs API (clamped to 0.7-1.2)
+get_speech_speed() {
+  local config_dir=""
+
+  # Determine config directory
+  if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+    config_dir="$CLAUDE_PROJECT_DIR/.claude/config"
+  else
+    # Try to find .claude in current path
+    local current_dir="$PWD"
+    while [[ "$current_dir" != "/" ]]; do
+      if [[ -d "$current_dir/.claude" ]]; then
+        config_dir="$current_dir/.claude/config"
+        break
+      fi
+      current_dir=$(dirname "$current_dir")
+    done
+    # Fallback to global
+    if [[ -z "$config_dir" ]]; then
+      config_dir="$HOME/.claude/config"
+    fi
+  fi
+
+  local main_speed_file="$config_dir/tts-speech-rate.txt"
+  local target_speed_file="$config_dir/tts-target-speech-rate.txt"
+
+  # Legacy file paths for backward compatibility
+  local legacy_main_speed_file="$config_dir/piper-speech-rate.txt"
+  local legacy_target_speed_file="$config_dir/piper-target-speech-rate.txt"
+
+  local user_speed="1.0"
+
+  # If this is a non-English voice and target config exists, use it
+  if [[ "$CURRENT_LANGUAGE" != "english" ]]; then
+    if [[ -f "$target_speed_file" ]]; then
+      user_speed=$(cat "$target_speed_file" 2>/dev/null || echo "1.0")
+    elif [[ -f "$legacy_target_speed_file" ]]; then
+      user_speed=$(cat "$legacy_target_speed_file" 2>/dev/null || echo "1.0")
+    else
+      user_speed="0.5"  # Default slower for learning
+    fi
+  else
+    # Otherwise use main config if available
+    if [[ -f "$main_speed_file" ]]; then
+      user_speed=$(grep -v '^#' "$main_speed_file" 2>/dev/null | grep -v '^$' | tail -1 || echo "1.0")
+    elif [[ -f "$legacy_main_speed_file" ]]; then
+      user_speed=$(grep -v '^#' "$legacy_main_speed_file" 2>/dev/null | grep -v '^$' | tail -1 || echo "1.0")
+    fi
+  fi
+
+  # Map user scale (0.5=slower, 1.0=normal, 2.0=faster, 3.0=very fast)
+  # to ElevenLabs range (0.7=slower, 1.0=normal, 1.2=faster)
+  # Formula: elevenlabs_speed = 0.7 + (user_speed - 0.5) * 0.2
+  # This maps: 0.5→0.7, 1.0→0.8, 2.0→1.0, 3.0→1.2
+  # Actually, let's use a better mapping:
+  # 0.5x → 0.7 (slowest ElevenLabs)
+  # 1.0x → 1.0 (normal)
+  # 2.0x → 1.15
+  # 3.0x → 1.2 (fastest ElevenLabs)
+
+  if command -v bc &> /dev/null; then
+    local eleven_speed
+    if (( $(echo "$user_speed <= 0.5" | bc -l) )); then
+      eleven_speed="0.7"
+    elif (( $(echo "$user_speed >= 3.0" | bc -l) )); then
+      eleven_speed="1.2"
+    elif (( $(echo "$user_speed <= 1.0" | bc -l) )); then
+      # Map 0.5-1.0 to 0.7-1.0
+      eleven_speed=$(echo "scale=2; 0.7 + ($user_speed - 0.5) * 0.6" | bc -l)
+    else
+      # Map 1.0-3.0 to 1.0-1.2
+      eleven_speed=$(echo "scale=2; 1.0 + ($user_speed - 1.0) * 0.1" | bc -l)
+    fi
+    echo "$eleven_speed"
+  else
+    # Fallback without bc: just clamp to safe values
+    if (( $(awk 'BEGIN {print ("'$user_speed'" <= 0.5)}') )); then
+      echo "0.7"
+    elif (( $(awk 'BEGIN {print ("'$user_speed'" >= 2.0)}') )); then
+      echo "1.2"
+    else
+      echo "1.0"
+    fi
+  fi
+}
+
+SPEECH_SPEED=$(get_speech_speed)
+
+# Build JSON payload with jq for proper escaping
+PAYLOAD=$(jq -n \
+  --arg text "$TEXT" \
+  --arg model "$MODEL_ID" \
+  --arg lang "$LANGUAGE_CODE" \
+  --argjson speed "$SPEECH_SPEED" \
+  '{
+    text: $text,
+    model_id: $model,
+    language_code: $lang,
+    voice_settings: {
+      stability: 0.5,
+      similarity_boost: 0.75,
+      speed: $speed
+    }
+  }')
+
+curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}" \
+  -H "xi-api-key: ${API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  -o "${TEMP_FILE}"
+
+# @function add_silence_padding
+# @intent Add silence to beginning of audio to prevent WSL static
+# @why WSL audio subsystem cuts off first ~200ms, causing static/clipping
+# @param Uses global: $TEMP_FILE
+# @returns Updates $TEMP_FILE to padded version
+# @sideeffects Modifies audio file, removes original
+# @edgecases Gracefully falls back to unpadded if ffmpeg unavailable
+# Add silence padding to prevent WSL audio static
+if [ -f "${TEMP_FILE}" ]; then
+  # Check if ffmpeg is available for adding padding
+  if command -v ffmpeg &> /dev/null; then
+    PADDED_FILE="$AUDIO_DIR/tts-padded-$(date +%s).mp3"
+    # Add 200ms of silence at the beginning to prevent static
+    # Note: ElevenLabs returns mono audio, so we use mono silence
+    ffmpeg -f lavfi -i anullsrc=r=44100:cl=mono:d=0.2 -i "${TEMP_FILE}" \
+      -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[out]" \
+      -map "[out]" -c:a libmp3lame -b:a 128k -y "${PADDED_FILE}" 2>/dev/null
+
+    if [ -f "${PADDED_FILE}" ]; then
+      # Use padded file and clean up original
+      rm -f "${TEMP_FILE}"
+      TEMP_FILE="${PADDED_FILE}"
+    fi
+    # If padding failed, just use original file
+  fi
+
+  # @function play_audio
+  # @intent Play generated audio file using available player with sequential playback
+  # @why Support multiple audio players and prevent overlapping audio in learning mode
+  # @param Uses global: $TEMP_FILE, $CURRENT_LANGUAGE
+  # @sideeffects Plays audio with lock mechanism for sequential playback
+  # @edgecases Falls through players until one works
+  LOCK_FILE="/tmp/agentvibes-audio.lock"
+
+  # Wait for previous audio to finish (max 30 seconds)
+  for i in {1..60}; do
+    if [ ! -f "$LOCK_FILE" ]; then
+      break
+    fi
+    sleep 0.5
+  done
+
+  # Track last target language audio for replay command
+  if [[ "$CURRENT_LANGUAGE" != "english" ]]; then
+    TARGET_AUDIO_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/last-target-audio.txt"
+    echo "${TEMP_FILE}" > "$TARGET_AUDIO_FILE"
+  fi
+
+  # Create lock and play audio
+  touch "$LOCK_FILE"
+
+  # Get audio duration for proper lock timing
+  DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${TEMP_FILE}" 2>/dev/null)
+  DURATION=${DURATION%.*}  # Round to integer
+  DURATION=${DURATION:-1}   # Default to 1 second if detection fails
+
+  # Convert to 48kHz stereo WAV for better SSH tunnel compatibility
+  # ElevenLabs returns 44.1kHz mono MP3, which causes static over SSH audio tunnels
+  # Converting to 48kHz stereo (Windows/PulseAudio native format) eliminates the static
+  if [[ -n "$SSH_CONNECTION" ]] || [[ -n "$SSH_CLIENT" ]] || [[ -n "$VSCODE_IPC_HOOK_CLI" ]]; then
+    CONVERTED_FILE="${TEMP_FILE%.mp3}.wav"
+    if ffmpeg -i "${TEMP_FILE}" -ar 48000 -ac 2 "${CONVERTED_FILE}" -y 2>/dev/null; then
+      TEMP_FILE="${CONVERTED_FILE}"
+    fi
+  fi
+
+  # Play audio (WSL/Linux) in background to avoid blocking, fully detached (skip if in test mode)
+  if [[ "${AGENTVIBES_TEST_MODE:-false}" != "true" ]]; then
+    (paplay "${TEMP_FILE}" || aplay "${TEMP_FILE}" || mpg123 "${TEMP_FILE}") >/dev/null 2>&1 &
+    PLAYER_PID=$!
+  fi
+
+  # Wait for audio to finish, then release lock
+  (sleep $DURATION; rm -f "$LOCK_FILE") &
+  disown
+
+  # Keep temp files for later review - cleaned up weekly by cron
+  echo "🎵 Saved to: ${TEMP_FILE}"
+  echo "🎤 Voice used: ${VOICE_NAME} (${VOICE_ID})"
+else
+  echo "❌ Failed to generate audio - API may be unavailable"
+  echo "Check your API key and network connection"
+  exit 3
+fi
--- a/.claude/hooks/play-tts-piper.sh
+++ b/.claude/hooks/play-tts-piper.sh
@@ -0,0 +1,338 @@
+#!/bin/bash
+#
+# File: .claude/hooks/play-tts-piper.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. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Piper TTS Provider Implementation - Free, offline neural TTS
+# @context Provides local, privacy-first TTS alternative to cloud services for WSL/Linux
+# @architecture Implements provider interface contract for Piper binary integration
+# @dependencies piper (pipx), piper-voice-manager.sh, mpv/aplay, ffmpeg (optional padding)
+# @entrypoints Called by play-tts.sh router when provider=piper
+# @patterns Provider contract: text/voice → audio file path, voice auto-download, language-aware synthesis
+# @related play-tts.sh, piper-voice-manager.sh, language-manager.sh, GitHub Issue #25
+#
+
+# Fix locale warnings
+export LC_ALL=C
+
+TEXT="$1"
+VOICE_OVERRIDE="$2"  # Optional: voice model name
+
+# Source voice manager and language manager
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/piper-voice-manager.sh"
+source "$SCRIPT_DIR/language-manager.sh"
+
+# Default voice for Piper
+DEFAULT_VOICE="en_US-lessac-medium"
+
+# @function determine_voice_model
+# @intent Resolve voice name to Piper model name with language support
+# @why Support voice override, language-specific voices, and default fallback
+# @param Uses global: $VOICE_OVERRIDE
+# @returns Sets $VOICE_MODEL global variable
+# @sideeffects None
+VOICE_MODEL=""
+
+# Get current language setting
+CURRENT_LANGUAGE=$(get_language_code)
+
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  # Use override if provided
+  VOICE_MODEL="$VOICE_OVERRIDE"
+  echo "🎤 Using voice: $VOICE_OVERRIDE (session-specific)"
+else
+  # Try to get voice from voice file (check CLAUDE_PROJECT_DIR first for MCP context)
+  VOICE_FILE=""
+
+  # Priority order:
+  # 1. CLAUDE_PROJECT_DIR env var (set by MCP for project-specific settings)
+  # 2. Script location (for direct slash command usage)
+  # 3. Global ~/.claude (fallback)
+
+  if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -f "$CLAUDE_PROJECT_DIR/.claude/tts-voice.txt" ]]; then
+    # MCP context: Use the project directory where MCP was invoked
+    VOICE_FILE="$CLAUDE_PROJECT_DIR/.claude/tts-voice.txt"
+  elif [[ -f "$SCRIPT_DIR/../tts-voice.txt" ]]; then
+    # Direct usage: Use script location
+    VOICE_FILE="$SCRIPT_DIR/../tts-voice.txt"
+  elif [[ -f "$HOME/.claude/tts-voice.txt" ]]; then
+    # Fallback: Use global
+    VOICE_FILE="$HOME/.claude/tts-voice.txt"
+  fi
+
+  if [[ -n "$VOICE_FILE" ]]; then
+    FILE_VOICE=$(cat "$VOICE_FILE" 2>/dev/null)
+
+    # Check for multi-speaker voice (model + speaker ID stored separately)
+    # Use same directory as VOICE_FILE for consistency
+    VOICE_DIR=$(dirname "$VOICE_FILE")
+    MODEL_FILE="$VOICE_DIR/tts-piper-model.txt"
+    SPEAKER_ID_FILE="$VOICE_DIR/tts-piper-speaker-id.txt"
+
+    if [[ -f "$MODEL_FILE" ]] && [[ -f "$SPEAKER_ID_FILE" ]]; then
+      # Multi-speaker voice
+      VOICE_MODEL=$(cat "$MODEL_FILE" 2>/dev/null)
+      SPEAKER_ID=$(cat "$SPEAKER_ID_FILE" 2>/dev/null)
+      echo "🎭 Using multi-speaker voice: $FILE_VOICE (Model: $VOICE_MODEL, Speaker ID: $SPEAKER_ID)"
+    # Check if it's a standard Piper model name or custom voice (just use as-is)
+    elif [[ -n "$FILE_VOICE" ]]; then
+      VOICE_MODEL="$FILE_VOICE"
+    fi
+  fi
+
+  # If no Piper voice from file, try language-specific voice
+  if [[ -z "$VOICE_MODEL" ]]; then
+    LANG_VOICE=$(get_voice_for_language "$CURRENT_LANGUAGE" "piper" 2>/dev/null)
+
+    if [[ -n "$LANG_VOICE" ]]; then
+      VOICE_MODEL="$LANG_VOICE"
+      echo "🌍 Using $CURRENT_LANGUAGE voice: $LANG_VOICE (Piper)"
+    else
+      # Use default voice
+      VOICE_MODEL="$DEFAULT_VOICE"
+    fi
+  fi
+fi
+
+# @function validate_inputs
+# @intent Check required parameters
+# @why Fail fast with clear errors if inputs missing
+# @exitcode 1=missing text, 2=missing piper binary
+if [[ -z "$TEXT" ]]; then
+  echo "Usage: $0 \"text to speak\" [voice_model_name]"
+  exit 1
+fi
+
+# Check if Piper is installed
+if ! command -v piper &> /dev/null; then
+  echo "❌ Error: Piper TTS not installed"
+  echo "Install with: pipx install piper-tts"
+  echo "Or run: .claude/hooks/piper-installer.sh"
+  exit 2
+fi
+
+# @function ensure_voice_downloaded
+# @intent Download voice model if not cached
+# @why Provide seamless experience with automatic downloads
+# @param Uses global: $VOICE_MODEL
+# @sideeffects Downloads voice model files
+# @edgecases Prompts user for consent before downloading
+if ! verify_voice "$VOICE_MODEL"; then
+  echo "📥 Voice model not found: $VOICE_MODEL"
+  echo "   File size: ~25MB"
+  echo "   Preview: https://huggingface.co/rhasspy/piper-voices"
+  echo ""
+  read -p "   Download this voice model? [y/N]: " -n 1 -r
+  echo
+
+  if [[ $REPLY =~ ^[Yy]$ ]]; then
+    if ! download_voice "$VOICE_MODEL"; then
+      echo "❌ Failed to download voice model"
+      echo "Fix: Download manually or choose different voice"
+      exit 3
+    fi
+  else
+    echo "❌ Voice download cancelled"
+    exit 3
+  fi
+fi
+
+# Get voice model path
+VOICE_PATH=$(get_voice_path "$VOICE_MODEL")
+if [[ $? -ne 0 ]]; then
+  echo "❌ Voice model path not found: $VOICE_MODEL"
+  exit 3
+fi
+
+# @function determine_audio_directory
+# @intent Find appropriate directory for audio file storage
+# @why Supports project-local and global storage
+# @returns Sets $AUDIO_DIR global variable
+if [[ -n "$CLAUDE_PROJECT_DIR" ]]; then
+  AUDIO_DIR="$CLAUDE_PROJECT_DIR/.claude/audio"
+else
+  # Fallback: try to find .claude directory in current path
+  CURRENT_DIR="$PWD"
+  while [[ "$CURRENT_DIR" != "/" ]]; do
+    if [[ -d "$CURRENT_DIR/.claude" ]]; then
+      AUDIO_DIR="$CURRENT_DIR/.claude/audio"
+      break
+    fi
+    CURRENT_DIR=$(dirname "$CURRENT_DIR")
+  done
+  # Final fallback to global if no project .claude found
+  if [[ -z "$AUDIO_DIR" ]]; then
+    AUDIO_DIR="$HOME/.claude/audio"
+  fi
+fi
+
+mkdir -p "$AUDIO_DIR"
+TEMP_FILE="$AUDIO_DIR/tts-$(date +%s).wav"
+
+# @function get_speech_rate
+# @intent Determine speech rate for Piper synthesis
+# @why Convert user-facing speed (0.5=slower, 2.0=faster) to Piper length-scale (inverted)
+# @returns Piper length-scale value (inverted from user scale)
+# @note Piper uses length-scale where higher=slower, opposite of user expectation
+get_speech_rate() {
+  local target_config=""
+  local main_config=""
+
+  # Check for target-specific config first (new and legacy paths)
+  if [[ -f "$SCRIPT_DIR/../config/tts-target-speech-rate.txt" ]]; then
+    target_config="$SCRIPT_DIR/../config/tts-target-speech-rate.txt"
+  elif [[ -f "$HOME/.claude/config/tts-target-speech-rate.txt" ]]; then
+    target_config="$HOME/.claude/config/tts-target-speech-rate.txt"
+  elif [[ -f "$SCRIPT_DIR/../config/piper-target-speech-rate.txt" ]]; then
+    target_config="$SCRIPT_DIR/../config/piper-target-speech-rate.txt"
+  elif [[ -f "$HOME/.claude/config/piper-target-speech-rate.txt" ]]; then
+    target_config="$HOME/.claude/config/piper-target-speech-rate.txt"
+  fi
+
+  # Check for main config (new and legacy paths)
+  if [[ -f "$SCRIPT_DIR/../config/tts-speech-rate.txt" ]]; then
+    main_config="$SCRIPT_DIR/../config/tts-speech-rate.txt"
+  elif [[ -f "$HOME/.claude/config/tts-speech-rate.txt" ]]; then
+    main_config="$HOME/.claude/config/tts-speech-rate.txt"
+  elif [[ -f "$SCRIPT_DIR/../config/piper-speech-rate.txt" ]]; then
+    main_config="$SCRIPT_DIR/../config/piper-speech-rate.txt"
+  elif [[ -f "$HOME/.claude/config/piper-speech-rate.txt" ]]; then
+    main_config="$HOME/.claude/config/piper-speech-rate.txt"
+  fi
+
+  # If this is a non-English voice and target config exists, use it
+  if [[ "$CURRENT_LANGUAGE" != "english" ]] && [[ -n "$target_config" ]]; then
+    local user_speed=$(cat "$target_config" 2>/dev/null)
+    # Convert user speed to Piper length-scale (invert)
+    # User: 0.5=slower, 1.0=normal, 2.0=faster
+    # Piper: 2.0=slower, 1.0=normal, 0.5=faster
+    # Formula: piper_length_scale = 1.0 / user_speed
+    echo "scale=2; 1.0 / $user_speed" | bc -l 2>/dev/null || echo "1.0"
+    return
+  fi
+
+  # Otherwise use main config if available
+  if [[ -n "$main_config" ]]; then
+    local user_speed=$(grep -v '^#' "$main_config" 2>/dev/null | grep -v '^$' | tail -1)
+    echo "scale=2; 1.0 / $user_speed" | bc -l 2>/dev/null || echo "1.0"
+    return
+  fi
+
+  # Default: 1.0 (normal) for English, 2.0 (slower) for learning
+  if [[ "$CURRENT_LANGUAGE" != "english" ]]; then
+    echo "2.0"
+  else
+    echo "1.0"
+  fi
+}
+
+SPEECH_RATE=$(get_speech_rate)
+
+# @function synthesize_with_piper
+# @intent Generate speech using Piper TTS
+# @why Provides free, offline TTS alternative
+# @param Uses globals: $TEXT, $VOICE_PATH, $SPEECH_RATE, $SPEAKER_ID (optional)
+# @returns Creates WAV file at $TEMP_FILE
+# @exitcode 0=success, 4=synthesis error
+# @sideeffects Creates audio file
+# @edgecases Handles piper errors, invalid models, multi-speaker voices
+if [[ -n "$SPEAKER_ID" ]]; then
+  # Multi-speaker voice: Pass speaker ID
+  echo "$TEXT" | piper --model "$VOICE_PATH" --speaker "$SPEAKER_ID" --length-scale "$SPEECH_RATE" --output_file "$TEMP_FILE" 2>/dev/null
+else
+  # Single-speaker voice
+  echo "$TEXT" | piper --model "$VOICE_PATH" --length-scale "$SPEECH_RATE" --output_file "$TEMP_FILE" 2>/dev/null
+fi
+
+if [[ ! -f "$TEMP_FILE" ]] || [[ ! -s "$TEMP_FILE" ]]; then
+  echo "❌ Failed to synthesize speech with Piper"
+  echo "Voice model: $VOICE_MODEL"
+  echo "Check that voice model is valid"
+  exit 4
+fi
+
+# @function add_silence_padding
+# @intent Add silence to prevent WSL audio static
+# @why WSL audio subsystem cuts off first ~200ms
+# @param Uses global: $TEMP_FILE
+# @returns Updates $TEMP_FILE to padded version
+# @sideeffects Modifies audio file
+# AI NOTE: Use ffmpeg if available, otherwise skip padding (degraded experience)
+if command -v ffmpeg &> /dev/null; then
+  PADDED_FILE="$AUDIO_DIR/tts-padded-$(date +%s).wav"
+  # Add 200ms of silence at the beginning
+  ffmpeg -f lavfi -i anullsrc=r=44100:cl=stereo:d=0.2 -i "$TEMP_FILE" \
+    -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[out]" \
+    -map "[out]" -y "$PADDED_FILE" 2>/dev/null
+
+  if [[ -f "$PADDED_FILE" ]]; then
+    rm -f "$TEMP_FILE"
+    TEMP_FILE="$PADDED_FILE"
+  fi
+fi
+
+# @function play_audio
+# @intent Play generated audio using available player with sequential playback
+# @why Support multiple audio players and prevent overlapping audio in learning mode
+# @param Uses global: $TEMP_FILE, $CURRENT_LANGUAGE
+# @sideeffects Plays audio with lock mechanism for sequential playback
+LOCK_FILE="/tmp/agentvibes-audio.lock"
+
+# Wait for previous audio to finish (max 30 seconds)
+for i in {1..60}; do
+  if [ ! -f "$LOCK_FILE" ]; then
+    break
+  fi
+  sleep 0.5
+done
+
+# Track last target language audio for replay command
+if [[ "$CURRENT_LANGUAGE" != "english" ]]; then
+  TARGET_AUDIO_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/last-target-audio.txt"
+  echo "$TEMP_FILE" > "$TARGET_AUDIO_FILE"
+fi
+
+# Create lock and play audio
+touch "$LOCK_FILE"
+
+# Get audio duration for proper lock timing
+DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$TEMP_FILE" 2>/dev/null)
+DURATION=${DURATION%.*}  # Round to integer
+DURATION=${DURATION:-1}   # Default to 1 second if detection fails
+
+# Play audio in background (skip if in test mode)
+if [[ "${AGENTVIBES_TEST_MODE:-false}" != "true" ]]; then
+  (mpv "$TEMP_FILE" || aplay "$TEMP_FILE" || paplay "$TEMP_FILE") >/dev/null 2>&1 &
+  PLAYER_PID=$!
+fi
+
+# Wait for audio to finish, then release lock
+(sleep $DURATION; rm -f "$LOCK_FILE") &
+disown
+
+echo "🎵 Saved to: $TEMP_FILE"
+echo "🎤 Voice used: $VOICE_MODEL (Piper TTS)"
--- a/.claude/hooks/play-tts.sh
+++ b/.claude/hooks/play-tts.sh
@@ -0,0 +1,100 @@
+#!/bin/bash
+#
+# File: .claude/hooks/play-tts.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 TTS Provider Router with Language Learning Support
+# @context Routes TTS requests to active provider (ElevenLabs or Piper)
+# @architecture Provider abstraction layer - single entry point for all TTS
+# @dependencies provider-manager.sh, play-tts-elevenlabs.sh, play-tts-piper.sh, github-star-reminder.sh
+# @entrypoints Called by hooks, slash commands, personality-manager.sh, and all TTS features
+# @patterns Provider pattern - delegates to provider-specific implementations, auto-detects provider from voice name
+# @related provider-manager.sh, play-tts-elevenlabs.sh, play-tts-piper.sh, learn-manager.sh
+#
+
+# Fix locale warnings
+export LC_ALL=C
+
+TEXT="$1"
+VOICE_OVERRIDE="$2"  # Optional: voice name or ID
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# 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
+
+# @function detect_voice_provider
+# @intent Auto-detect provider from voice name (for mixed-provider support)
+# @why Allow ElevenLabs for main language + Piper for target language
+# @param $1 voice name/ID
+# @returns Provider name (elevenlabs or piper)
+detect_voice_provider() {
+  local voice="$1"
+  # Piper voice names contain underscore and dash (e.g., es_ES-davefx-medium)
+  if [[ "$voice" == *"_"*"-"* ]]; then
+    echo "piper"
+  else
+    echo "$ACTIVE_PROVIDER"
+  fi
+}
+
+# Override provider if voice indicates different provider (mixed-provider mode)
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  DETECTED_PROVIDER=$(detect_voice_provider "$VOICE_OVERRIDE")
+  if [[ "$DETECTED_PROVIDER" != "$ACTIVE_PROVIDER" ]]; then
+    ACTIVE_PROVIDER="$DETECTED_PROVIDER"
+  fi
+fi
+
+# Normal single-language mode - route to appropriate provider implementation
+# Note: For learning mode, the output style will call this script TWICE:
+# 1. First call with main language text and current voice
+# 2. Second call with translated text and target voice
+case "$ACTIVE_PROVIDER" in
+  elevenlabs)
+    exec "$SCRIPT_DIR/play-tts-elevenlabs.sh" "$TEXT" "$VOICE_OVERRIDE"
+    ;;
+  piper)
+    exec "$SCRIPT_DIR/play-tts-piper.sh" "$TEXT" "$VOICE_OVERRIDE"
+    ;;
+  *)
+    echo "❌ Unknown provider: $ACTIVE_PROVIDER"
+    echo "   Run: /agent-vibes:provider list"
+    exit 1
+    ;;
+esac
--- a/.claude/hooks/provider-commands.sh
+++ b/.claude/hooks/provider-commands.sh
@@ -0,0 +1,540 @@
+#!/bin/bash
+#
+# File: .claude/hooks/provider-commands.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 Provider management slash commands
+# @context User-facing commands for switching and managing TTS providers
+# @architecture Part of /agent-vibes:* command system with language compatibility checking
+# @dependencies provider-manager.sh, language-manager.sh, voice-manager.sh, piper-voice-manager.sh
+# @entrypoints Called by /agent-vibes:provider slash commands (list, switch, info, test, get, preview)
+# @patterns Interactive confirmations, platform detection, language compatibility validation
+# @related provider-manager.sh, play-tts.sh, voice-manager.sh, piper-voice-manager.sh
+#
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/provider-manager.sh"
+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() {
+  local current_provider
+  current_provider=$(get_active_provider)
+
+  echo "┌────────────────────────────────────────────────────────────┐"
+  echo "│ Available TTS Providers                                    │"
+  echo "├────────────────────────────────────────────────────────────┤"
+
+  # ElevenLabs
+  if [[ "$current_provider" == "elevenlabs" ]]; then
+    echo "│ ✓ ElevenLabs    Premium quality    ⭐⭐⭐⭐⭐    [ACTIVE]    │"
+  else
+    echo "│   ElevenLabs    Premium quality    ⭐⭐⭐⭐⭐               │"
+  fi
+  echo "│   Cost: Free tier + \$5-22/mo                               │"
+  echo "│   Platform: All (Windows, macOS, Linux, WSL)               │"
+  echo "│   Offline: No                                              │"
+  echo "│                                                            │"
+
+  # Piper
+  if [[ "$current_provider" == "piper" ]]; then
+    echo "│ ✓ Piper TTS     Free, offline      ⭐⭐⭐⭐       [ACTIVE]    │"
+  else
+    echo "│   Piper TTS     Free, offline      ⭐⭐⭐⭐                  │"
+  fi
+  echo "│   Cost: Free forever                                       │"
+  echo "│   Platform: WSL, Linux only                                │"
+  echo "│   Offline: Yes                                             │"
+  echo "└────────────────────────────────────────────────────────────┘"
+  echo ""
+  echo "Learn more: agentvibes.org/providers"
+}
+
+# @function provider_switch
+# @intent Switch to a different TTS provider
+provider_switch() {
+  local new_provider="$1"
+  local force_mode=false
+
+  # Check for --force or --yes flag
+  if [[ "$2" == "--force" ]] || [[ "$2" == "--yes" ]] || [[ "$2" == "-y" ]]; then
+    force_mode=true
+  fi
+
+  # Auto-enable force mode if running non-interactively (e.g., from MCP)
+  # Check multiple conditions for MCP/non-interactive context
+  if [[ ! -t 0 ]] || [[ -n "$CLAUDE_PROJECT_DIR" ]] || [[ -n "$MCP_SERVER" ]]; then
+    force_mode=true
+  fi
+
+  if [[ -z "$new_provider" ]]; then
+    echo "❌ Error: Provider name required"
+    echo "Usage: /agent-vibes:provider switch <provider> [--force]"
+    echo "Available: elevenlabs, piper"
+    return 1
+  fi
+
+  # Validate provider
+  if ! validate_provider "$new_provider"; then
+    echo "❌ Invalid provider: $new_provider"
+    echo ""
+    echo "Available providers:"
+    list_providers
+    return 1
+  fi
+
+  local current_provider
+  current_provider=$(get_active_provider)
+
+  if [[ "$current_provider" == "$new_provider" ]]; then
+    echo "✓ Already using $new_provider"
+    return 0
+  fi
+
+  # Platform check for Piper
+  if [[ "$new_provider" == "piper" ]]; then
+    if ! grep -qi microsoft /proc/version 2>/dev/null && [[ "$(uname -s)" != "Linux" ]]; then
+      echo "❌ Piper is only supported on WSL and Linux"
+      echo "Your platform: $(uname -s)"
+      echo "See: agentvibes.org/platform-support"
+      return 1
+    fi
+
+    # Check if Piper is installed
+    if ! command -v piper &> /dev/null; then
+      echo "❌ Piper TTS is not installed"
+      echo ""
+      echo "Install with: pipx install piper-tts"
+      echo "Or run: .claude/hooks/piper-installer.sh"
+      echo ""
+      echo "Visit: agentvibes.org/install-piper"
+      return 1
+    fi
+  fi
+
+  # Check language compatibility
+  local current_language
+  current_language=$(get_language_code)
+
+  if [[ "$current_language" != "english" ]]; then
+    if ! is_language_supported "$current_language" "$new_provider" 2>/dev/null; then
+      echo "⚠️  Language Compatibility Warning"
+      echo ""
+      echo "Current language: $current_language"
+      echo "Target provider:  $new_provider"
+      echo ""
+      echo "❌ Language '$current_language' is not natively supported by $new_provider"
+      echo "   Will fall back to English when using $new_provider"
+      echo ""
+      echo "Options:"
+      echo "  1. Continue anyway (will use English)"
+      echo "  2. Switch language to English"
+      echo "  3. Cancel provider switch"
+      echo ""
+
+      # Skip prompt in force mode
+      if [[ "$force_mode" == true ]]; then
+        echo "⏩ Force mode: Continuing with fallback to English..."
+      else
+        read -p "Choose option [1-3]: " -n 1 -r
+        echo
+
+        case $REPLY in
+          1)
+            echo "⏩ Continuing with fallback to English..."
+            ;;
+          2)
+            echo "🔄 Switching language to English..."
+            "$SCRIPT_DIR/language-manager.sh" set english
+            ;;
+          3)
+            echo "❌ Provider switch cancelled"
+            return 1
+            ;;
+          *)
+            echo "❌ Invalid option, cancelling"
+            return 1
+            ;;
+        esac
+      fi
+    fi
+  fi
+
+  # Confirm switch (skip in force mode)
+  if [[ "$force_mode" != true ]]; then
+    echo ""
+    echo "⚠️  Switch to $(echo $new_provider | tr '[:lower:]' '[:upper:]')?"
+    echo ""
+    echo "Current: $current_provider"
+    echo "New:     $new_provider"
+    if [[ "$current_language" != "english" ]]; then
+      echo "Language: $current_language"
+    fi
+    echo ""
+    read -p "Continue? [y/N]: " -n 1 -r
+    echo
+
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+      echo "❌ Switch cancelled"
+      return 1
+    fi
+  else
+    echo "⏩ Force mode: Switching to $new_provider..."
+  fi
+
+  # Perform switch
+  set_active_provider "$new_provider"
+
+  # Update target voice if language learning mode is active
+  local target_lang_file=""
+  local target_voice_file=""
+
+  # Check project-local first, then global
+  if [[ -d "$SCRIPT_DIR/../.." ]]; then
+    local project_dir="$SCRIPT_DIR/../.."
+    if [[ -f "$project_dir/.claude/tts-target-language.txt" ]]; then
+      target_lang_file="$project_dir/.claude/tts-target-language.txt"
+      target_voice_file="$project_dir/.claude/tts-target-voice.txt"
+    fi
+  fi
+
+  # Fallback to global
+  if [[ -z "$target_lang_file" ]]; then
+    if [[ -f "$HOME/.claude/tts-target-language.txt" ]]; then
+      target_lang_file="$HOME/.claude/tts-target-language.txt"
+      target_voice_file="$HOME/.claude/tts-target-voice.txt"
+    fi
+  fi
+
+  # If target language is set, update voice for new provider
+  if [[ -n "$target_lang_file" ]] && [[ -f "$target_lang_file" ]]; then
+    local target_lang
+    target_lang=$(cat "$target_lang_file")
+
+    if [[ -n "$target_lang" ]]; then
+      # Get the recommended voice for this language with new provider
+      local new_target_voice
+      new_target_voice=$(get_voice_for_language "$target_lang" "$new_provider")
+
+      if [[ -n "$new_target_voice" ]]; then
+        echo "$new_target_voice" > "$target_voice_file"
+        echo ""
+        echo "🔄 Updated target language voice:"
+        echo "   Language: $target_lang"
+        echo "   Voice: $new_target_voice (for $new_provider)"
+      fi
+    fi
+  fi
+
+  # Test new provider
+  echo ""
+  echo "🔊 Testing provider..."
+  "$SCRIPT_DIR/play-tts.sh" "Provider switched to $new_provider successfully" 2>/dev/null
+
+  echo ""
+  echo "✓ Provider switch complete!"
+  echo "Visit agentvibes.org for tips and tricks"
+}
+
+# @function provider_info
+# @intent Show detailed information about a provider
+provider_info() {
+  local provider_name="$1"
+
+  if [[ -z "$provider_name" ]]; then
+    echo "❌ Error: Provider name required"
+    echo "Usage: /agent-vibes:provider info <provider>"
+    return 1
+  fi
+
+  case "$provider_name" in
+    elevenlabs)
+      echo "┌────────────────────────────────────────────────────────────┐"
+      echo "│ ElevenLabs - Premium TTS Provider                          │"
+      echo "├────────────────────────────────────────────────────────────┤"
+      echo "│ Quality:     ⭐⭐⭐⭐⭐  (Highest available)                   │"
+      echo "│ Cost:        Free tier + \$5-22/mo                          │"
+      echo "│ Platform:    All (Windows, macOS, Linux, WSL)              │"
+      echo "│ Offline:     No (requires internet)                        │"
+      echo "│                                                            │"
+      echo "│ Trade-offs:                                                │"
+      echo "│ + Highest voice quality and naturalness                   │"
+      echo "│ + 50+ premium voices available                            │"
+      echo "│ + Multilingual support (30+ languages)                    │"
+      echo "│ - Requires API key and internet                           │"
+      echo "│ - Costs money after free tier                             │"
+      echo "│                                                            │"
+      echo "│ Best for: Premium quality, multilingual needs             │"
+      echo "└────────────────────────────────────────────────────────────┘"
+      echo ""
+      echo "Full comparison: agentvibes.org/providers"
+      ;;
+
+    piper)
+      echo "┌────────────────────────────────────────────────────────────┐"
+      echo "│ Piper TTS - Free Offline Provider                          │"
+      echo "├────────────────────────────────────────────────────────────┤"
+      echo "│ Quality:     ⭐⭐⭐⭐  (Very good)                            │"
+      echo "│ Cost:        Free forever                                  │"
+      echo "│ Platform:    WSL, Linux only                               │"
+      echo "│ Offline:     Yes (fully local)                             │"
+      echo "│                                                            │"
+      echo "│ Trade-offs:                                                │"
+      echo "│ + Completely free, no API costs                           │"
+      echo "│ + Works offline, no internet needed                       │"
+      echo "│ + Fast synthesis (local processing)                       │"
+      echo "│ - WSL/Linux only (no macOS/Windows)                       │"
+      echo "│ - Slightly lower quality than ElevenLabs                  │"
+      echo "│                                                            │"
+      echo "│ Best for: Budget-conscious, offline use, privacy          │"
+      echo "└────────────────────────────────────────────────────────────┘"
+      echo ""
+      echo "Full comparison: agentvibes.org/providers"
+      ;;
+
+    *)
+      echo "❌ Unknown provider: $provider_name"
+      echo "Available: elevenlabs, piper"
+      ;;
+  esac
+}
+
+# @function provider_test
+# @intent Test current provider with sample audio
+provider_test() {
+  local current_provider
+  current_provider=$(get_active_provider)
+
+  echo "🔊 Testing provider: $current_provider"
+  echo ""
+
+  "$SCRIPT_DIR/play-tts.sh" "Provider test successful. Audio is working correctly with $current_provider."
+
+  echo ""
+  echo "✓ Test complete"
+}
+
+# @function provider_get
+# @intent Show currently active provider
+provider_get() {
+  local current_provider
+  current_provider=$(get_active_provider)
+
+  echo "🎤 Current Provider: $current_provider"
+  echo ""
+
+  # Show brief info
+  case "$current_provider" in
+    elevenlabs)
+      echo "Quality: ⭐⭐⭐⭐⭐"
+      echo "Cost: Free tier + \$5-22/mo"
+      echo "Offline: No"
+      ;;
+    piper)
+      echo "Quality: ⭐⭐⭐⭐"
+      echo "Cost: Free forever"
+      echo "Offline: Yes"
+      ;;
+  esac
+
+  echo ""
+  echo "Use /agent-vibes:provider info $current_provider for details"
+}
+
+# @function provider_preview
+# @intent Preview voices for the currently active provider
+# @architecture Delegates to provider-specific voice managers
+provider_preview() {
+  local current_provider
+  current_provider=$(get_active_provider)
+
+  echo "🎤 Voice Preview ($current_provider)"
+  echo ""
+
+  case "$current_provider" in
+    elevenlabs)
+      # Use the ElevenLabs voice manager
+      "$SCRIPT_DIR/voice-manager.sh" preview "$@"
+      ;;
+    piper)
+      # Use the Piper voice manager's list functionality
+      source "$SCRIPT_DIR/piper-voice-manager.sh"
+
+      # Check if a specific voice was requested
+      local voice_arg="$1"
+
+      if [[ -n "$voice_arg" ]]; then
+        # User requested a specific voice - check if it's a valid Piper voice
+        # Piper voice names are like: en_US-lessac-medium
+        # Try to find a matching voice model
+
+        # Check if the voice arg looks like a Piper model name (contains underscores/hyphens)
+        if [[ "$voice_arg" =~ ^[a-z]{2}_[A-Z]{2}- ]]; then
+          # Looks like a Piper voice model name
+          if verify_voice "$voice_arg"; then
+            echo "🎤 Previewing Piper voice: $voice_arg"
+            echo ""
+            "$SCRIPT_DIR/play-tts.sh" "Hello, this is the $voice_arg voice. How do you like it?" "$voice_arg"
+          else
+            echo "❌ Voice model not found: $voice_arg"
+            echo ""
+            echo "💡 Piper voice names look like: en_US-lessac-medium"
+            echo "   Run /agent-vibes:list to see available Piper voices"
+          fi
+        else
+          # Looks like an ElevenLabs voice name (like "Antoni", "Jessica")
+          echo "❌ '$voice_arg' appears to be an ElevenLabs voice"
+          echo ""
+          echo "You're currently using Piper TTS (free provider)."
+          echo "Piper has different voices than ElevenLabs."
+          echo ""
+          echo "Options:"
+          echo "  1. Run /agent-vibes:list to see available Piper voices"
+          echo "  2. Switch to ElevenLabs: /agent-vibes:provider switch elevenlabs"
+          echo ""
+          echo "Popular Piper voices to try:"
+          echo "  • en_US-lessac-medium  (clear, professional)"
+          echo "  • en_US-amy-medium     (warm, friendly)"
+          echo "  • en_US-joe-medium     (casual, natural)"
+        fi
+        return
+      fi
+
+      # No specific voice - preview first 3 voices
+      echo "🎤 Piper Preview of 3 people"
+      echo ""
+
+      # Play first 3 Piper voices as samples
+      local sample_voices=(
+        "en_US-lessac-medium:Lessac"
+        "en_US-amy-medium:Amy"
+        "en_US-joe-medium:Joe"
+      )
+
+      for voice_entry in "${sample_voices[@]}"; do
+        local voice_name="${voice_entry%%:*}"
+        local display_name="${voice_entry##*:}"
+
+        echo "🔊 ${display_name}..."
+        "$SCRIPT_DIR/play-tts.sh" "Hi, my name is ${display_name}" "$voice_name"
+
+        # Wait for the voice to finish playing before starting next one
+        sleep 3
+      done
+
+      echo ""
+      echo "✓ Preview complete"
+      echo "💡 Use /agent-vibes:list to see all available Piper voices"
+      ;;
+    *)
+      echo "❌ Unknown provider: $current_provider"
+      ;;
+  esac
+}
+
+# @function provider_help
+# @intent Show help for provider commands
+provider_help() {
+  echo "Provider Management Commands"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Usage:"
+  echo "  /agent-vibes:provider list              # Show all providers"
+  echo "  /agent-vibes:provider switch <name>     # Switch provider"
+  echo "  /agent-vibes:provider info <name>       # Provider details"
+  echo "  /agent-vibes:provider test              # Test current provider"
+  echo "  /agent-vibes:provider get               # Show active provider"
+  echo ""
+  echo "Examples:"
+  echo "  /agent-vibes:provider switch piper"
+  echo "  /agent-vibes:provider info elevenlabs"
+  echo ""
+  echo "Learn more: agentvibes.org/docs/providers"
+}
+
+# Route to appropriate function
+case "$COMMAND" in
+  list)
+    provider_list
+    ;;
+  switch)
+    provider_switch "$2" "$3"
+    ;;
+  info)
+    provider_info "$2"
+    ;;
+  test)
+    provider_test
+    ;;
+  get)
+    provider_get
+    ;;
+  preview)
+    shift  # Remove 'preview' from args
+    provider_preview "$@"
+    ;;
+  help|*)
+    provider_help
+    ;;
+esac
--- a/.claude/hooks/provider-manager.sh
+++ b/.claude/hooks/provider-manager.sh
@@ -0,0 +1,298 @@
+#!/bin/bash
+#
+# File: .claude/hooks/provider-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 TTS Provider Management Functions
+# @context Core provider abstraction layer for multi-provider TTS system
+# @architecture Provides functions to get/set/list/validate TTS providers
+# @dependencies None - pure bash implementation
+# @entrypoints Sourced by play-tts.sh and provider management commands
+# @patterns File-based state management with project-local and global fallback
+# @related play-tts.sh, play-tts-elevenlabs.sh, play-tts-piper.sh, provider-commands.sh
+#
+
+# @function get_provider_config_path
+# @intent Determine path to tts-provider.txt file
+# @why Supports both project-local (.claude/) and global (~/.claude/) storage
+# @returns Echoes path to provider config file
+# @exitcode 0=always succeeds
+# @sideeffects None
+# @edgecases Creates parent directory if missing
+get_provider_config_path() {
+  local provider_file
+
+  # Check project-local first
+  if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+    provider_file="$CLAUDE_PROJECT_DIR/.claude/tts-provider.txt"
+  else
+    # Search up directory tree for .claude/
+    local current_dir="$PWD"
+    while [[ "$current_dir" != "/" ]]; do
+      if [[ -d "$current_dir/.claude" ]]; then
+        provider_file="$current_dir/.claude/tts-provider.txt"
+        break
+      fi
+      current_dir=$(dirname "$current_dir")
+    done
+
+    # Fallback to global if no project .claude found
+    if [[ -z "$provider_file" ]]; then
+      provider_file="$HOME/.claude/tts-provider.txt"
+    fi
+  fi
+
+  echo "$provider_file"
+}
+
+# @function get_active_provider
+# @intent Read currently active TTS provider from config file
+# @why Central function for determining which provider to use
+# @returns Echoes provider name (e.g., "elevenlabs", "piper")
+# @exitcode 0=success
+# @sideeffects None
+# @edgecases Returns "elevenlabs" if file missing or empty (default)
+get_active_provider() {
+  local provider_file
+  provider_file=$(get_provider_config_path)
+
+  # Read provider from file, default to piper if not found
+  if [[ -f "$provider_file" ]]; then
+    local provider
+    provider=$(cat "$provider_file" | tr -d '[:space:]')
+    if [[ -n "$provider" ]]; then
+      echo "$provider"
+      return 0
+    fi
+  fi
+
+  # Default to piper (free, offline)
+  echo "piper"
+}
+
+# @function set_active_provider
+# @intent Write active provider to config file
+# @why Allows runtime provider switching without restart
+# @param $1 {string} provider - Provider name (e.g., "elevenlabs", "piper")
+# @returns None (outputs success/error message)
+# @exitcode 0=success, 1=invalid provider
+# @sideeffects Writes to tts-provider.txt file
+# @edgecases Creates file and parent directory if missing
+set_active_provider() {
+  local provider="$1"
+
+  if [[ -z "$provider" ]]; then
+    echo "❌ Error: Provider name required"
+    echo "Usage: set_active_provider <provider_name>"
+    return 1
+  fi
+
+  # Validate provider exists
+  if ! validate_provider "$provider"; then
+    echo "❌ Error: Provider '$provider' not found"
+    echo "Available providers:"
+    list_providers
+    return 1
+  fi
+
+  local provider_file
+  provider_file=$(get_provider_config_path)
+
+  # Create directory if it doesn't exist
+  mkdir -p "$(dirname "$provider_file")"
+
+  # Write provider to file
+  echo "$provider" > "$provider_file"
+
+  # Reset voice when switching providers to avoid incompatible voices
+  # (e.g., ElevenLabs "Demon Monster" doesn't exist in Piper)
+  local voice_file
+  if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+    voice_file="$CLAUDE_PROJECT_DIR/.claude/tts-voice.txt"
+  else
+    voice_file="$HOME/.claude/tts-voice.txt"
+  fi
+
+  # Set default voice for the new provider
+  local default_voice
+  case "$provider" in
+    piper)
+      # Default Piper voice
+      default_voice="en_US-lessac-medium"
+      ;;
+    elevenlabs)
+      # Default ElevenLabs voice (first in alphabetical order from voices-config.sh)
+      default_voice="Amy"
+      ;;
+    *)
+      # Unknown provider - remove voice file
+      if [[ -f "$voice_file" ]]; then
+        rm -f "$voice_file"
+      fi
+      echo "✓ Active provider set to: $provider (voice reset)"
+      return 0
+      ;;
+  esac
+
+  # Write default voice to file
+  echo "$default_voice" > "$voice_file"
+
+  echo "✓ Active provider set to: $provider (voice set to: $default_voice)"
+}
+
+# @function list_providers
+# @intent List all available TTS providers
+# @why Discover which providers are installed
+# @returns Echoes provider names (one per line)
+# @exitcode 0=success
+# @sideeffects None
+# @edgecases Returns empty if no play-tts-*.sh files found
+list_providers() {
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+  # Find all play-tts-*.sh files
+  local providers=()
+  shopt -s nullglob  # Handle case where no files match
+  for file in "$script_dir"/play-tts-*.sh; do
+    if [[ -f "$file" ]] && [[ "$file" != *"play-tts.sh" ]]; then
+      # Extract provider name from filename (play-tts-elevenlabs.sh -> elevenlabs)
+      local basename
+      basename=$(basename "$file")
+      local provider
+      provider="${basename#play-tts-}"
+      provider="${provider%.sh}"
+      providers+=("$provider")
+    fi
+  done
+  shopt -u nullglob
+
+  # Output providers
+  if [[ ${#providers[@]} -eq 0 ]]; then
+    echo "⚠️ No providers found"
+    return 0
+  fi
+
+  for provider in "${providers[@]}"; do
+    echo "$provider"
+  done
+}
+
+# @function validate_provider
+# @intent Check if provider implementation exists
+# @why Prevent errors from switching to non-existent provider
+# @param $1 {string} provider - Provider name to validate
+# @returns None
+# @exitcode 0=provider exists, 1=provider not found
+# @sideeffects None
+# @edgecases Checks for corresponding play-tts-*.sh file
+validate_provider() {
+  local provider="$1"
+
+  if [[ -z "$provider" ]]; then
+    return 1
+  fi
+
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  local provider_script="$script_dir/play-tts-${provider}.sh"
+
+  [[ -f "$provider_script" ]]
+}
+
+# @function get_provider_script_path
+# @intent Get absolute path to provider implementation script
+# @why Used by router to execute provider-specific logic
+# @param $1 {string} provider - Provider name
+# @returns Echoes absolute path to play-tts-*.sh file
+# @exitcode 0=success, 1=provider not found
+# @sideeffects None
+get_provider_script_path() {
+  local provider="$1"
+
+  if [[ -z "$provider" ]]; then
+    echo "❌ Error: Provider name required" >&2
+    return 1
+  fi
+
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  local provider_script="$script_dir/play-tts-${provider}.sh"
+
+  if [[ ! -f "$provider_script" ]]; then
+    echo "❌ Error: Provider '$provider' not found at $provider_script" >&2
+    return 1
+  fi
+
+  echo "$provider_script"
+}
+
+# AI NOTE: This file provides the core abstraction layer for multi-provider TTS.
+# All provider state is managed through simple text files for simplicity and reliability.
+# Project-local configuration takes precedence over global to support per-project providers.
+
+# Command-line interface (when script is executed, not sourced)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  case "${1:-}" in
+    get)
+      get_active_provider
+      ;;
+    switch|set)
+      if [[ -z "${2:-}" ]]; then
+        echo "❌ Error: Provider name required"
+        echo "Usage: $0 switch <provider>"
+        exit 1
+      fi
+      set_active_provider "$2"
+      ;;
+    list)
+      list_providers
+      ;;
+    validate)
+      if [[ -z "${2:-}" ]]; then
+        echo "❌ Error: Provider name required"
+        echo "Usage: $0 validate <provider>"
+        exit 1
+      fi
+      validate_provider "$2"
+      ;;
+    *)
+      echo "Usage: $0 {get|switch|list|validate} [provider]"
+      echo ""
+      echo "Commands:"
+      echo "  get              - Show active provider"
+      echo "  switch <name>    - Switch to provider"
+      echo "  list             - List available providers"
+      echo "  validate <name>  - Check if provider exists"
+      exit 1
+      ;;
+  esac
+fi
--- a/.claude/hooks/replay-target-audio.sh
+++ b/.claude/hooks/replay-target-audio.sh
@@ -0,0 +1,95 @@
+#!/bin/bash
+#
+# File: .claude/hooks/replay-target-audio.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 Replay Last Target Language Audio
+# @context Replays the most recent target language TTS for language learning
+# @architecture Simple audio replay with lock mechanism for sequential playback
+# @dependencies ffprobe, paplay/aplay/mpg123/mpv, .claude/last-target-audio.txt
+# @entrypoints Called by /agent-vibes:replay-target slash command
+# @patterns Sequential audio playback with lock file, duration-based lock release
+# @related play-tts-piper.sh, play-tts-elevenlabs.sh, learn-manager.sh
+#
+
+# Fix locale warnings
+export LC_ALL=C
+
+TARGET_AUDIO_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/last-target-audio.txt"
+
+# Check if target audio tracking file exists
+if [ ! -f "$TARGET_AUDIO_FILE" ]; then
+  echo "❌ No target language audio found."
+  echo "   Language learning mode may not be active."
+  echo "   Activate with: /agent-vibes:learn"
+  exit 1
+fi
+
+# Read last target audio file path
+LAST_AUDIO=$(cat "$TARGET_AUDIO_FILE")
+
+# Verify audio file exists
+if [ ! -f "$LAST_AUDIO" ]; then
+  echo "❌ Audio file not found: $LAST_AUDIO"
+  echo "   The file may have been deleted or moved."
+  exit 1
+fi
+
+echo "🔁 Replaying target language audio..."
+
+# Use lock file for sequential playback
+LOCK_FILE="/tmp/agentvibes-audio.lock"
+
+# Wait for any current audio to finish (max 30 seconds)
+for i in {1..60}; do
+  if [ ! -f "$LOCK_FILE" ]; then
+    break
+  fi
+  sleep 0.5
+done
+
+# Create lock
+touch "$LOCK_FILE"
+
+# Get audio duration for proper lock timing
+DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$LAST_AUDIO" 2>/dev/null)
+DURATION=${DURATION%.*}  # Round to integer
+DURATION=${DURATION:-1}   # Default to 1 second if detection fails
+
+# Play audio
+(paplay "$LAST_AUDIO" || aplay "$LAST_AUDIO" || mpg123 "$LAST_AUDIO" || mpv "$LAST_AUDIO") >/dev/null 2>&1 &
+PLAYER_PID=$!
+
+# Wait for audio to finish, then release lock
+(sleep $DURATION; rm -f "$LOCK_FILE") &
+disown
+
+echo "✅ Replay complete: $(basename "$LAST_AUDIO")"
--- a/.claude/hooks/sentiment-manager.sh
+++ b/.claude/hooks/sentiment-manager.sh
@@ -0,0 +1,201 @@
+#!/bin/bash
+#
+# File: .claude/hooks/sentiment-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 Sentiment Manager - Applies personality styles to current voice without changing the voice itself
+# @context Allows adding emotional/tonal layers (flirty, sarcastic, etc.) to any voice while preserving voice identity
+# @architecture Reuses personality markdown files, stores sentiment separately from personality
+# @dependencies .claude/personalities/*.md files, play-tts.sh for acknowledgment
+# @entrypoints Called by /agent-vibes:sentiment slash command
+# @patterns Personality/sentiment separation, state file management, random example selection
+# @related personality-manager.sh, .claude/personalities/*.md, .claude/tts-sentiment.txt
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PERSONALITIES_DIR="$SCRIPT_DIR/../personalities"
+
+# Project-local file first, global fallback
+# Use logical path (not physical) to handle symlinked .claude directories
+# Script is at .claude/hooks/sentiment-manager.sh, so .claude is ..
+CLAUDE_DIR="$(cd "$SCRIPT_DIR/.." 2>/dev/null && pwd)"
+
+# Check if we have a project-local .claude directory
+if [[ -d "$CLAUDE_DIR" ]] && [[ "$CLAUDE_DIR" != "$HOME/.claude" ]]; then
+  SENTIMENT_FILE="$CLAUDE_DIR/tts-sentiment.txt"
+else
+  SENTIMENT_FILE="$HOME/.claude/tts-sentiment.txt"
+fi
+
+# Function to get personality data from markdown file
+get_personality_data() {
+  local personality="$1"
+  local field="$2"
+  local file="$PERSONALITIES_DIR/${personality}.md"
+
+  if [[ ! -f "$file" ]]; then
+    return 1
+  fi
+
+  case "$field" in
+    description)
+      grep "^description:" "$file" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'
+      ;;
+  esac
+}
+
+# Function to list all available personalities
+list_personalities() {
+  if [[ -d "$PERSONALITIES_DIR" ]]; then
+    for file in "$PERSONALITIES_DIR"/*.md; do
+      if [[ -f "$file" ]]; then
+        basename "$file" .md
+      fi
+    done
+  fi
+}
+
+case "$1" in
+  list)
+    echo "🎭 Available Sentiments:"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    # Get current sentiment
+    CURRENT="none"
+    if [ -f "$SENTIMENT_FILE" ]; then
+      CURRENT=$(cat "$SENTIMENT_FILE")
+    fi
+
+    # List personalities from markdown files
+    echo "Available sentiment styles:"
+    for personality in $(list_personalities | sort); do
+      desc=$(get_personality_data "$personality" "description")
+      if [[ "$personality" == "$CURRENT" ]]; then
+        echo "  ✓ $personality - $desc (current)"
+      else
+        echo "  - $personality - $desc"
+      fi
+    done
+
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "Usage: /agent-vibes:sentiment <name>"
+    echo "       /agent-vibes:sentiment clear"
+    ;;
+
+  set)
+    SENTIMENT="$2"
+
+    if [[ -z "$SENTIMENT" ]]; then
+      echo "❌ Please specify a sentiment name"
+      echo "Usage: $0 set <sentiment>"
+      exit 1
+    fi
+
+    # Check if sentiment file exists
+    if [[ ! -f "$PERSONALITIES_DIR/${SENTIMENT}.md" ]]; then
+      echo "❌ Sentiment not found: $SENTIMENT"
+      echo ""
+      echo "Available sentiments:"
+      for p in $(list_personalities | sort); do
+        echo "  • $p"
+      done
+      exit 1
+    fi
+
+    # Save the sentiment (but don't change personality or voice)
+    echo "$SENTIMENT" > "$SENTIMENT_FILE"
+    echo "🎭 Sentiment set to: $SENTIMENT"
+    echo "🎤 Voice remains unchanged"
+    echo ""
+
+    # Make a sentiment-appropriate remark with TTS
+    TTS_SCRIPT="$SCRIPT_DIR/play-tts.sh"
+
+    # Try to get acknowledgment from personality file (sentiments use same personality files)
+    PERSONALITY_FILE_PATH="$PERSONALITIES_DIR/${SENTIMENT}.md"
+    REMARK=""
+
+    if [[ -f "$PERSONALITY_FILE_PATH" ]]; then
+      # Extract example responses from personality file (lines starting with "- ")
+      mapfile -t EXAMPLES < <(grep '^- "' "$PERSONALITY_FILE_PATH" | sed 's/^- "//; s/"$//')
+
+      if [[ ${#EXAMPLES[@]} -gt 0 ]]; then
+        # Pick a random example
+        REMARK="${EXAMPLES[$RANDOM % ${#EXAMPLES[@]}]}"
+      fi
+    fi
+
+    # Fallback if no examples found
+    if [[ -z "$REMARK" ]]; then
+      REMARK="Sentiment set to ${SENTIMENT} while maintaining current voice"
+    fi
+
+    echo "💬 $REMARK"
+    "$TTS_SCRIPT" "$REMARK"
+    ;;
+
+  get)
+    if [ -f "$SENTIMENT_FILE" ]; then
+      CURRENT=$(cat "$SENTIMENT_FILE")
+      echo "Current sentiment: $CURRENT"
+
+      desc=$(get_personality_data "$CURRENT" "description")
+      [[ -n "$desc" ]] && echo "Description: $desc"
+    else
+      echo "Current sentiment: none (voice personality only)"
+    fi
+    ;;
+
+  clear)
+    rm -f "$SENTIMENT_FILE"
+    echo "🎭 Sentiment cleared - using voice personality only"
+    ;;
+
+  *)
+    # If a single argument is provided and it's not a command, treat it as "set <sentiment>"
+    if [[ -n "$1" ]] && [[ -f "$PERSONALITIES_DIR/${1}.md" ]]; then
+      exec "$0" set "$1"
+    else
+      echo "AgentVibes Sentiment Manager"
+      echo ""
+      echo "Commands:"
+      echo "  list                - List all sentiments"
+      echo "  set <name>          - Set sentiment for current voice"
+      echo "  get                 - Show current sentiment"
+      echo "  clear               - Clear sentiment"
+      echo ""
+      echo "Examples:"
+      echo "  /agent-vibes:sentiment flirty     # Add flirty style to current voice"
+      echo "  /agent-vibes:sentiment sarcastic  # Add sarcasm to current voice"
+      echo "  /agent-vibes:sentiment clear      # Remove sentiment"
+    fi
+    ;;
+esac
--- a/.claude/hooks/speed-manager.sh
+++ b/.claude/hooks/speed-manager.sh
@@ -0,0 +1,291 @@
+#!/bin/bash
+#
+# File: .claude/hooks/speed-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 Speech Speed Manager for Multi-Provider TTS
+# @context Manage speech rate for main and target language voices
+# @architecture Simple config file manager supporting both Piper (length-scale) and ElevenLabs (speed API parameter)
+# @dependencies .claude/config/tts-speech-rate.txt, .claude/config/tts-target-speech-rate.txt
+# @entrypoints Called by /agent-vibes:set-speed slash command
+# @patterns Provider-agnostic speed config, legacy file migration, random tongue twisters for testing
+# @related play-tts.sh, play-tts-piper.sh, play-tts-elevenlabs.sh, learn-manager.sh
+#
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Determine config directory (project-local first, then global)
+if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+  CONFIG_DIR="$CLAUDE_PROJECT_DIR/.claude/config"
+else
+  # Try to find .claude in current path
+  CURRENT_DIR="$PWD"
+  while [[ "$CURRENT_DIR" != "/" ]]; do
+    if [[ -d "$CURRENT_DIR/.claude" ]]; then
+      CONFIG_DIR="$CURRENT_DIR/.claude/config"
+      break
+    fi
+    CURRENT_DIR=$(dirname "$CURRENT_DIR")
+  done
+  # Fallback to global
+  if [[ -z "$CONFIG_DIR" ]]; then
+    CONFIG_DIR="$HOME/.claude/config"
+  fi
+fi
+
+mkdir -p "$CONFIG_DIR"
+
+MAIN_SPEED_FILE="$CONFIG_DIR/tts-speech-rate.txt"
+TARGET_SPEED_FILE="$CONFIG_DIR/tts-target-speech-rate.txt"
+
+# Legacy file paths for backward compatibility (Piper-specific naming)
+LEGACY_MAIN_SPEED_FILE="$CONFIG_DIR/piper-speech-rate.txt"
+LEGACY_TARGET_SPEED_FILE="$CONFIG_DIR/piper-target-speech-rate.txt"
+
+# @function parse_speed_value
+# @intent Convert user-friendly speed notation to normalized speed multiplier
+# @param $1 Speed string (e.g., "2x", "0.5x", "normal")
+# @returns Numeric speed value (0.5=slower, 1.0=normal, 2.0=faster, 3.0=very fast)
+# @note This is the user-facing scale - provider scripts will convert as needed
+parse_speed_value() {
+  local input="$1"
+
+  # Handle special cases
+  case "$input" in
+    normal|1x|1.0)
+      echo "1.0"
+      return
+      ;;
+    slow|slower|0.5x)
+      echo "0.5"
+      return
+      ;;
+    fast|2x|2.0)
+      echo "2.0"
+      return
+      ;;
+    faster|3x|3.0)
+      echo "3.0"
+      return
+      ;;
+  esac
+
+  # Strip leading '+' or '-' if present
+  input="${input#+}"
+  input="${input#-}"
+
+  # Strip trailing 'x' if present
+  input="${input%x}"
+
+  # Validate it's a number
+  if [[ "$input" =~ ^[0-9]+\.?[0-9]*$ ]]; then
+    echo "$input"
+  else
+    echo "ERROR"
+  fi
+}
+
+# @function set_speed
+# @intent Set speech speed for main or target voice
+# @param $1 Target ("target" or empty for main)
+# @param $2 Speed value
+set_speed() {
+  local is_target=false
+  local speed_input=""
+
+  # Parse arguments
+  if [[ "$1" == "target" ]]; then
+    is_target=true
+    speed_input="$2"
+  else
+    speed_input="$1"
+  fi
+
+  if [[ -z "$speed_input" ]]; then
+    echo "❌ Error: Speed value required"
+    echo "Usage: /agent-vibes:set-speed [target] <speed>"
+    echo "Examples: 2x, 0.5x, normal, +3x"
+    return 1
+  fi
+
+  # Parse speed value
+  local speed_value
+  speed_value=$(parse_speed_value "$speed_input")
+
+  if [[ "$speed_value" == "ERROR" ]]; then
+    echo "❌ Invalid speed value: $speed_input"
+    echo "Valid values: normal, 0.5x, 1x, 2x, 3x, +2x, -2x"
+    return 1
+  fi
+
+  # Determine which file to write to
+  local config_file
+  local voice_type
+  if [[ "$is_target" == true ]]; then
+    config_file="$TARGET_SPEED_FILE"
+    voice_type="target language"
+  else
+    config_file="$MAIN_SPEED_FILE"
+    voice_type="main voice"
+  fi
+
+  # Write speed value
+  echo "$speed_value" > "$config_file"
+
+  # Show confirmation
+  echo "✓ Speech speed set for $voice_type"
+  echo ""
+  echo "Speed: ${speed_value}x"
+
+  case "$speed_value" in
+    0.5)
+      echo "Effect: Half speed (slower)"
+      ;;
+    1.0)
+      echo "Effect: Normal speed"
+      ;;
+    2.0)
+      echo "Effect: Double speed (faster)"
+      ;;
+    3.0)
+      echo "Effect: Triple speed (very fast)"
+      ;;
+    *)
+      if (( $(echo "$speed_value > 1.0" | bc -l) )); then
+        echo "Effect: Faster speech"
+      else
+        echo "Effect: Slower speech"
+      fi
+      ;;
+  esac
+
+  echo ""
+  echo "Note: Speed control works with both Piper and ElevenLabs providers"
+
+  # Array of simple test messages to demonstrate speed
+  local test_messages=(
+    "Testing speed change"
+    "Speed test in progress"
+    "Checking audio speed"
+    "Speed configuration test"
+    "Audio speed test"
+  )
+
+  # Pick a random test message
+  local random_index=$((RANDOM % ${#test_messages[@]}))
+  local test_msg="${test_messages[$random_index]}"
+
+  echo ""
+  echo "🔊 Testing new speed with: \"$test_msg\""
+  "$SCRIPT_DIR/play-tts.sh" "$test_msg" &
+}
+
+# @function migrate_legacy_files
+# @intent Migrate from old piper-specific files to provider-agnostic files
+# @why Ensure backward compatibility when upgrading from Piper-only to multi-provider
+migrate_legacy_files() {
+  # Migrate main speed file
+  if [[ -f "$LEGACY_MAIN_SPEED_FILE" ]] && [[ ! -f "$MAIN_SPEED_FILE" ]]; then
+    cp "$LEGACY_MAIN_SPEED_FILE" "$MAIN_SPEED_FILE"
+  fi
+
+  # Migrate target speed file
+  if [[ -f "$LEGACY_TARGET_SPEED_FILE" ]] && [[ ! -f "$TARGET_SPEED_FILE" ]]; then
+    cp "$LEGACY_TARGET_SPEED_FILE" "$TARGET_SPEED_FILE"
+  fi
+}
+
+# @function get_speed
+# @intent Display current speech speed settings
+get_speed() {
+  # Migrate legacy files if needed
+  migrate_legacy_files
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "   Current Speech Speed Settings"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+
+  # Main voice speed
+  if [[ -f "$MAIN_SPEED_FILE" ]]; then
+    local main_speed=$(grep -v '^#' "$MAIN_SPEED_FILE" 2>/dev/null | grep -v '^$' | tail -1)
+    echo "Main voice: ${main_speed}x"
+  else
+    echo "Main voice: 1.0x (default, normal speed)"
+  fi
+
+  # Target voice speed
+  if [[ -f "$TARGET_SPEED_FILE" ]]; then
+    local target_speed=$(cat "$TARGET_SPEED_FILE" 2>/dev/null)
+    echo "Target language: ${target_speed}x"
+  else
+    echo "Target language: 0.5x (default, slower for learning)"
+  fi
+
+  echo ""
+  echo "Scale: 0.5x=slower, 1.0x=normal, 2.0x=faster, 3.0x=very fast"
+  echo "Works with: Piper TTS and ElevenLabs"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+}
+
+# Main command handler
+case "${1:-}" in
+  target)
+    set_speed "target" "$2"
+    ;;
+  get|status)
+    get_speed
+    ;;
+  normal|fast|slow|slower|*x|*.*|+*|-*)
+    set_speed "$1"
+    ;;
+  *)
+    echo "Speech Speed Manager"
+    echo ""
+    echo "Usage:"
+    echo "  /agent-vibes:set-speed <speed>         Set main voice speed"
+    echo "  /agent-vibes:set-speed target <speed>  Set target language speed"
+    echo "  /agent-vibes:set-speed get              Show current speeds"
+    echo ""
+    echo "Speed values:"
+    echo "  0.5x or slow/slower = Half speed (slower)"
+    echo "  1x or normal        = Normal speed"
+    echo "  2x or fast          = Double speed (faster)"
+    echo "  3x or faster        = Triple speed (very fast)"
+    echo ""
+    echo "Examples:"
+    echo "  /agent-vibes:set-speed 2x        # Make voice faster"
+    echo "  /agent-vibes:set-speed 0.5x      # Make voice slower"
+    echo "  /agent-vibes:set-speed target 0.5x  # Slow down target language for learning"
+    echo "  /agent-vibes:set-speed normal    # Reset to normal"
+    ;;
+esac
--- a/.claude/hooks/voice-manager.sh
+++ b/.claude/hooks/voice-manager.sh
@@ -0,0 +1,594 @@
+#!/bin/bash
+#
+# File: .claude/hooks/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. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Voice Manager - Unified voice management for both ElevenLabs and Piper providers
+# @context Central interface for listing, switching, previewing, and replaying TTS voices across providers
+# @architecture Provider-aware operations with dynamic voice listing based on active provider
+# @dependencies voices-config.sh (ElevenLabs mappings), piper-voice-manager.sh (Piper voices), provider-manager.sh
+# @entrypoints Called by /agent-vibes:switch, /agent-vibes:list, /agent-vibes:whoami, /agent-vibes:replay commands
+# @patterns Provider abstraction, numbered selection UI, silent mode for programmatic switching
+# @related voices-config.sh, piper-voice-manager.sh, .claude/tts-voice.txt, .claude/audio/ (replay)
+
+# Get script directory (physical path for sourcing files)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+source "$SCRIPT_DIR/voices-config.sh"
+
+# Determine target .claude directory based on context
+# Priority:
+# 1. CLAUDE_PROJECT_DIR env var (set by MCP for project-specific settings)
+# 2. Script location (for direct slash command usage)
+# 3. Global ~/.claude (fallback)
+
+if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+  # MCP context: Use the project directory where MCP was invoked
+  CLAUDE_DIR="$CLAUDE_PROJECT_DIR/.claude"
+else
+  # Direct usage context: Use script location
+  SCRIPT_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  CLAUDE_DIR="$(dirname "$SCRIPT_PATH")"
+
+  # If script is in global ~/.claude, use that
+  if [[ "$CLAUDE_DIR" == "$HOME/.claude" ]]; then
+    CLAUDE_DIR="$HOME/.claude"
+  elif [[ ! -d "$CLAUDE_DIR" ]]; then
+    # Fallback to global if directory doesn't exist
+    CLAUDE_DIR="$HOME/.claude"
+  fi
+fi
+
+VOICE_FILE="$CLAUDE_DIR/tts-voice.txt"
+
+case "$1" in
+  list)
+    # Get active provider
+    PROVIDER_FILE="$CLAUDE_DIR/tts-provider.txt"
+    if [[ ! -f "$PROVIDER_FILE" ]]; then
+      PROVIDER_FILE="$HOME/.claude/tts-provider.txt"
+    fi
+
+    ACTIVE_PROVIDER="elevenlabs"  # default
+    if [ -f "$PROVIDER_FILE" ]; then
+      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+    fi
+
+    CURRENT_VOICE=$(cat "$VOICE_FILE" 2>/dev/null || echo "Cowboy Bob")
+
+    if [[ "$ACTIVE_PROVIDER" == "piper" ]]; then
+      echo "🎤 Available Piper TTS Voices:"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+      # List downloaded Piper voices
+      if [[ -f "$SCRIPT_DIR/piper-voice-manager.sh" ]]; then
+        source "$SCRIPT_DIR/piper-voice-manager.sh"
+        VOICE_DIR=$(get_voice_storage_dir)
+        VOICE_COUNT=0
+        for onnx_file in "$VOICE_DIR"/*.onnx; do
+          if [[ -f "$onnx_file" ]]; then
+            voice=$(basename "$onnx_file" .onnx)
+            if [ "$voice" = "$CURRENT_VOICE" ]; then
+              echo "  ▶ $voice (current)"
+            else
+              echo "    $voice"
+            fi
+            ((VOICE_COUNT++))
+          fi
+        done | sort
+
+        if [[ $VOICE_COUNT -eq 0 ]]; then
+          echo "  (No Piper voices downloaded yet)"
+          echo ""
+          echo "Download voices with: /agent-vibes:provider download <voice-name>"
+          echo "Examples: en_US-lessac-medium, en_GB-alba-medium"
+        fi
+      fi
+    else
+      echo "🎤 Available ElevenLabs TTS Voices:"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      for voice in "${!VOICES[@]}"; do
+        if [ "$voice" = "$CURRENT_VOICE" ]; then
+          echo "  ▶ $voice (current)"
+        else
+          echo "    $voice"
+        fi
+      done | sort
+    fi
+
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "Usage: voice-manager.sh switch <name>"
+    echo "       voice-manager.sh preview"
+    ;;
+
+  preview)
+    # Get play-tts.sh path
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    TTS_SCRIPT="$SCRIPT_DIR/play-tts.sh"
+
+    # Check if a specific voice name was provided
+    if [[ -n "$2" ]] && [[ "$2" != "first" ]] && [[ "$2" != "last" ]] && ! [[ "$2" =~ ^[0-9]+$ ]]; then
+      # User specified a voice name
+      VOICE_NAME="$2"
+
+      # Check if voice exists
+      if [[ -n "${VOICES[$VOICE_NAME]}" ]]; then
+        echo "🎤 Previewing voice: ${VOICE_NAME}"
+        echo ""
+        "$TTS_SCRIPT" "Hello, this is ${VOICE_NAME}. How do you like my voice?" "${VOICE_NAME}"
+      else
+        echo "❌ Voice not found: ${VOICE_NAME}"
+        echo ""
+        echo "Available voices:"
+        for voice in "${!VOICES[@]}"; do
+          echo "  • $voice"
+        done | sort
+      fi
+      exit 0
+    fi
+
+    # Original preview logic for first/last/number
+    echo "🎤 Voice Preview - Playing first 3 voices..."
+    echo ""
+
+    # Sort voices and preview first 3
+    VOICE_ARRAY=()
+    for voice in "${!VOICES[@]}"; do
+      VOICE_ARRAY+=("$voice")
+    done
+
+    # Sort the array
+    IFS=$'\n' SORTED_VOICES=($(sort <<<"${VOICE_ARRAY[*]}"))
+    unset IFS
+
+    # Play first 3 voices
+    COUNT=0
+    for voice in "${SORTED_VOICES[@]}"; do
+      if [ $COUNT -eq 3 ]; then
+        break
+      fi
+      echo "🔊 ${voice}..."
+      "$TTS_SCRIPT" "Hi, I'm ${voice}" "${VOICES[$voice]}"
+      sleep 0.5
+      COUNT=$((COUNT + 1))
+    done
+
+    echo ""
+    echo "Would you like to hear more? Reply 'yes' to continue."
+    ;;
+
+  switch)
+    VOICE_NAME="$2"
+    SILENT_MODE=false
+
+    # Check for --silent flag
+    if [[ "$2" == "--silent" ]] || [[ "$3" == "--silent" ]]; then
+      SILENT_MODE=true
+      # If --silent is first arg, voice name is in $3
+      [[ "$2" == "--silent" ]] && VOICE_NAME="$3"
+    fi
+
+    if [[ -z "$VOICE_NAME" ]]; then
+      # Show numbered list for selection
+      echo "🎤 Select a voice by number:"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+      # Get current voice
+      CURRENT="Cowboy Bob"
+      if [ -f "$VOICE_FILE" ]; then
+        CURRENT=$(cat "$VOICE_FILE")
+      fi
+
+      # Create array of voice names
+      VOICE_ARRAY=()
+      for voice in "${!VOICES[@]}"; do
+        VOICE_ARRAY+=("$voice")
+      done
+
+      # Sort the array
+      IFS=$'\n' SORTED_VOICES=($(sort <<<"${VOICE_ARRAY[*]}"))
+      unset IFS
+
+      # Display numbered list in two columns for compactness
+      HALF=$(( (${#SORTED_VOICES[@]} + 1) / 2 ))
+
+      for i in $(seq 0 $((HALF - 1))); do
+        NUM1=$((i + 1))
+        VOICE1="${SORTED_VOICES[$i]}"
+
+        # Format first column
+        if [[ "$VOICE1" == "$CURRENT" ]]; then
+          COL1=$(printf "%2d. %-20s ✓" "$NUM1" "$VOICE1")
+        else
+          COL1=$(printf "%2d. %-20s  " "$NUM1" "$VOICE1")
+        fi
+
+        # Format second column if it exists
+        NUM2=$((i + HALF + 1))
+        if [[ $((i + HALF)) -lt ${#SORTED_VOICES[@]} ]]; then
+          VOICE2="${SORTED_VOICES[$((i + HALF))]}"
+          if [[ "$VOICE2" == "$CURRENT" ]]; then
+            COL2=$(printf "%2d. %-20s ✓" "$NUM2" "$VOICE2")
+          else
+            COL2=$(printf "%2d. %-20s  " "$NUM2" "$VOICE2")
+          fi
+          echo "  $COL1 $COL2"
+        else
+          echo "  $COL1"
+        fi
+      done
+
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo ""
+      echo "Enter number (1-${#SORTED_VOICES[@]}) or voice name:"
+      echo "Usage: /agent-vibes:switch 5"
+      echo "       /agent-vibes:switch \"Northern Terry\""
+      exit 0
+    fi
+
+    # Detect active TTS provider
+    PROVIDER_FILE=""
+    if [[ -f "$CLAUDE_DIR/tts-provider.txt" ]]; then
+      PROVIDER_FILE="$CLAUDE_DIR/tts-provider.txt"
+    elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+      PROVIDER_FILE="$HOME/.claude/tts-provider.txt"
+    fi
+
+    ACTIVE_PROVIDER="elevenlabs"  # default
+    if [[ -n "$PROVIDER_FILE" ]]; then
+      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+    fi
+
+    # Voice lookup strategy depends on active provider
+    if [[ "$ACTIVE_PROVIDER" == "piper" ]]; then
+      # Piper voice lookup: Scan voice directory for .onnx files
+      source "$SCRIPT_DIR/piper-voice-manager.sh"
+      VOICE_DIR=$(get_voice_storage_dir)
+
+      # Check if voice file exists (case-insensitive)
+      FOUND=""
+      shopt -s nullglob
+      for onnx_file in "$VOICE_DIR"/*.onnx; do
+        if [[ -f "$onnx_file" ]]; then
+          voice=$(basename "$onnx_file" .onnx)
+          if [[ "${voice,,}" == "${VOICE_NAME,,}" ]]; then
+            FOUND="$voice"
+            break
+          fi
+        fi
+      done
+      shopt -u nullglob
+
+      # If not found, check multi-speaker registry
+      if [[ -z "$FOUND" ]] && [[ -f "$SCRIPT_DIR/piper-multispeaker-registry.sh" ]]; then
+        source "$SCRIPT_DIR/piper-multispeaker-registry.sh"
+
+        MULTISPEAKER_INFO=$(get_multispeaker_info "$VOICE_NAME")
+        if [[ -n "$MULTISPEAKER_INFO" ]]; then
+          MODEL="${MULTISPEAKER_INFO%%:*}"
+          SPEAKER_ID="${MULTISPEAKER_INFO#*:}"
+
+          # Verify the model file exists
+          if [[ -f "$VOICE_DIR/${MODEL}.onnx" ]]; then
+            # Store speaker name in tts-voice.txt
+            echo "$VOICE_NAME" > "$VOICE_FILE"
+
+            # Store model and speaker ID separately for play-tts-piper.sh
+            echo "$MODEL" > "$CLAUDE_DIR/tts-piper-model.txt"
+            echo "$SPEAKER_ID" > "$CLAUDE_DIR/tts-piper-speaker-id.txt"
+
+            DESCRIPTION=$(get_multispeaker_description "$VOICE_NAME")
+            echo "✅ Multi-speaker voice switched to: $VOICE_NAME"
+            echo "🎤 Model: $MODEL.onnx (Speaker ID: $SPEAKER_ID)"
+            if [[ -n "$DESCRIPTION" ]]; then
+              echo "📝 Description: $DESCRIPTION"
+            fi
+
+            # Have the new voice introduce itself (unless silent mode)
+            if [[ "$SILENT_MODE" != "true" ]]; then
+              PLAY_TTS="$SCRIPT_DIR/play-tts.sh"
+              if [ -x "$PLAY_TTS" ]; then
+                "$PLAY_TTS" "Hi, I'm $VOICE_NAME. I'll be your voice assistant moving forward." > /dev/null 2>&1 &
+              fi
+
+              echo ""
+              echo "💡 Tip: To hear automatic TTS narration, enable the Agent Vibes output style:"
+              echo "   /output-style Agent Vibes"
+            fi
+            exit 0
+          else
+            echo "❌ Multi-speaker model not found: $MODEL.onnx"
+            echo ""
+            echo "Download it with: /agent-vibes:provider download"
+            exit 1
+          fi
+        fi
+      fi
+
+      if [[ -z "$FOUND" ]]; then
+        echo "❌ Piper voice not found: $VOICE_NAME"
+        echo ""
+        echo "Available Piper voices:"
+        shopt -s nullglob
+        for onnx_file in "$VOICE_DIR"/*.onnx; do
+          if [[ -f "$onnx_file" ]]; then
+            echo "  - $(basename "$onnx_file" .onnx)"
+          fi
+        done | sort
+        shopt -u nullglob
+        echo ""
+        if [[ -f "$SCRIPT_DIR/piper-multispeaker-registry.sh" ]]; then
+          echo "Multi-speaker voices (requires 16Speakers.onnx):"
+          source "$SCRIPT_DIR/piper-multispeaker-registry.sh"
+          for entry in "${MULTISPEAKER_VOICES[@]}"; do
+            name="${entry%%:*}"
+            echo "  - $name"
+          done | sort
+          echo ""
+        fi
+        echo "Download extra voices with: /agent-vibes:provider download"
+        exit 1
+      fi
+    else
+      # ElevenLabs voice lookup
+      # Check if input is a number
+      if [[ "$VOICE_NAME" =~ ^[0-9]+$ ]]; then
+        # Get voice array
+        VOICE_ARRAY=()
+        for voice in "${!VOICES[@]}"; do
+          VOICE_ARRAY+=("$voice")
+        done
+
+        # Sort the array
+        IFS=$'\n' SORTED_VOICES=($(sort <<<"${VOICE_ARRAY[*]}"))
+        unset IFS
+
+        # Get voice by number (adjust for 0-based index)
+        INDEX=$((VOICE_NAME - 1))
+
+        if [[ $INDEX -ge 0 && $INDEX -lt ${#SORTED_VOICES[@]} ]]; then
+          VOICE_NAME="${SORTED_VOICES[$INDEX]}"
+          FOUND="${SORTED_VOICES[$INDEX]}"
+        else
+          echo "❌ Invalid number. Please choose between 1 and ${#SORTED_VOICES[@]}"
+          exit 1
+        fi
+      else
+        # Check if voice exists (case-insensitive)
+        FOUND=""
+        for voice in "${!VOICES[@]}"; do
+          if [[ "${voice,,}" == "${VOICE_NAME,,}" ]]; then
+            FOUND="$voice"
+            break
+          fi
+        done
+      fi
+
+      if [[ -z "$FOUND" ]]; then
+        echo "❌ Unknown voice: $VOICE_NAME"
+        echo ""
+        echo "Available voices:"
+        for voice in "${!VOICES[@]}"; do
+          echo "  - $voice"
+        done | sort
+        exit 1
+      fi
+    fi
+
+    echo "$FOUND" > "$VOICE_FILE"
+    echo "✅ Voice switched to: $FOUND"
+
+    # Show voice ID only for ElevenLabs voices
+    if [[ "$ACTIVE_PROVIDER" != "piper" ]] && [[ -n "${VOICES[$FOUND]}" ]]; then
+      echo "🎤 Voice ID: ${VOICES[$FOUND]}"
+    fi
+
+    # Have the new voice introduce itself (unless silent mode)
+    if [[ "$SILENT_MODE" != "true" ]]; then
+      SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+      PLAY_TTS="$SCRIPT_DIR/play-tts.sh"
+      if [ -x "$PLAY_TTS" ]; then
+        "$PLAY_TTS" "Hi, I'm $FOUND. I'll be your voice assistant moving forward." "$FOUND" > /dev/null 2>&1 &
+      fi
+
+      echo ""
+      echo "💡 Tip: To hear automatic TTS narration, enable the Agent Vibes output style:"
+      echo "   /output-style Agent Vibes"
+    fi
+    ;;
+
+  get)
+    if [ -f "$VOICE_FILE" ]; then
+      cat "$VOICE_FILE"
+    else
+      echo "Cowboy Bob"
+    fi
+    ;;
+
+  whoami)
+    echo "🎤 Current Voice Configuration"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    # Get active TTS provider
+    PROVIDER_FILE="$CLAUDE_DIR/tts-provider.txt"
+    if [[ ! -f "$PROVIDER_FILE" ]]; then
+      PROVIDER_FILE="$HOME/.claude/tts-provider.txt"
+    fi
+
+    if [ -f "$PROVIDER_FILE" ]; then
+      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+      if [[ "$ACTIVE_PROVIDER" == "elevenlabs" ]]; then
+        echo "Provider: ElevenLabs (Premium AI)"
+      elif [[ "$ACTIVE_PROVIDER" == "piper" ]]; then
+        echo "Provider: Piper TTS (Free, Offline)"
+      else
+        echo "Provider: $ACTIVE_PROVIDER"
+      fi
+    else
+      # Default to ElevenLabs if no provider file
+      echo "Provider: ElevenLabs (Premium AI)"
+    fi
+
+    # Get current voice
+    if [ -f "$VOICE_FILE" ]; then
+      CURRENT_VOICE=$(cat "$VOICE_FILE")
+    else
+      CURRENT_VOICE="Cowboy Bob"
+    fi
+    echo "Voice: $CURRENT_VOICE"
+
+    # Get current sentiment (priority)
+    if [ -f "$HOME/.claude/tts-sentiment.txt" ]; then
+      SENTIMENT=$(cat "$HOME/.claude/tts-sentiment.txt")
+      echo "Sentiment: $SENTIMENT (active)"
+
+      # Also show personality if set
+      if [ -f "$HOME/.claude/tts-personality.txt" ]; then
+        PERSONALITY=$(cat "$HOME/.claude/tts-personality.txt")
+        echo "Personality: $PERSONALITY (overridden by sentiment)"
+      fi
+    else
+      # No sentiment, check personality
+      if [ -f "$HOME/.claude/tts-personality.txt" ]; then
+        PERSONALITY=$(cat "$HOME/.claude/tts-personality.txt")
+        echo "Personality: $PERSONALITY (active)"
+      else
+        echo "Personality: normal"
+      fi
+    fi
+
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    ;;
+
+  list-simple)
+    # Simple list for AI to parse and display
+    # Get active provider
+    PROVIDER_FILE="$CLAUDE_DIR/tts-provider.txt"
+    if [[ ! -f "$PROVIDER_FILE" ]]; then
+      PROVIDER_FILE="$HOME/.claude/tts-provider.txt"
+    fi
+
+    ACTIVE_PROVIDER="elevenlabs"  # default
+    if [ -f "$PROVIDER_FILE" ]; then
+      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+    fi
+
+    if [[ "$ACTIVE_PROVIDER" == "piper" ]]; then
+      # List downloaded Piper voices
+      if [[ -f "$SCRIPT_DIR/piper-voice-manager.sh" ]]; then
+        source "$SCRIPT_DIR/piper-voice-manager.sh"
+        VOICE_DIR=$(get_voice_storage_dir)
+        for onnx_file in "$VOICE_DIR"/*.onnx; do
+          if [[ -f "$onnx_file" ]]; then
+            basename "$onnx_file" .onnx
+          fi
+        done | sort
+      fi
+    else
+      # List ElevenLabs voices
+      for voice in "${!VOICES[@]}"; do
+        echo "$voice"
+      done | sort
+    fi
+    ;;
+
+  replay)
+    # Replay recent TTS audio from history
+    # Use project-local directory with same logic as play-tts.sh
+    if [[ -n "$CLAUDE_PROJECT_DIR" ]]; then
+      AUDIO_DIR="$CLAUDE_PROJECT_DIR/.claude/audio"
+    else
+      # Fallback: try to find .claude directory in current path
+      CURRENT_DIR="$PWD"
+      while [[ "$CURRENT_DIR" != "/" ]]; do
+        if [[ -d "$CURRENT_DIR/.claude" ]]; then
+          AUDIO_DIR="$CURRENT_DIR/.claude/audio"
+          break
+        fi
+        CURRENT_DIR=$(dirname "$CURRENT_DIR")
+      done
+      # Final fallback to global if no project .claude found
+      if [[ -z "$AUDIO_DIR" ]]; then
+        AUDIO_DIR="$HOME/.claude/audio"
+      fi
+    fi
+
+    # Default to replay last audio (N=1)
+    N="${2:-1}"
+
+    # Validate N is a number
+    if ! [[ "$N" =~ ^[0-9]+$ ]]; then
+      echo "❌ Invalid argument. Please use a number (1-10)"
+      echo "Usage: /agent-vibes:replay [N]"
+      echo "  N=1 - Last audio (default)"
+      echo "  N=2 - Second-to-last"
+      echo "  N=3 - Third-to-last"
+      exit 1
+    fi
+
+    # Check bounds
+    if [[ $N -lt 1 || $N -gt 10 ]]; then
+      echo "❌ Number out of range. Please choose 1-10"
+      exit 1
+    fi
+
+    # Get list of audio files sorted by time (newest first)
+    if [[ ! -d "$AUDIO_DIR" ]]; then
+      echo "❌ No audio history found"
+      echo "Audio files are stored in: $AUDIO_DIR"
+      exit 1
+    fi
+
+    # Get the Nth most recent file
+    AUDIO_FILE=$(ls -t "$AUDIO_DIR"/tts-*.mp3 2>/dev/null | sed -n "${N}p")
+
+    if [[ -z "$AUDIO_FILE" ]]; then
+      TOTAL=$(ls -t "$AUDIO_DIR"/tts-*.mp3 2>/dev/null | wc -l)
+      echo "❌ Audio #$N not found in history"
+      echo "Total audio files available: $TOTAL"
+      exit 1
+    fi
+
+    echo "🔊 Replaying audio #$N:"
+    echo "   File: $(basename "$AUDIO_FILE")"
+    echo "   Path: $AUDIO_FILE"
+
+    # Play the audio file in background
+    (paplay "$AUDIO_FILE" 2>/dev/null || aplay "$AUDIO_FILE" 2>/dev/null || mpg123 "$AUDIO_FILE" 2>/dev/null) &
+    ;;
+
+  *)
+    echo "Usage: voice-manager.sh [list|switch|get|replay|whoami] [voice_name]"
+    echo ""
+    echo "Commands:"
+    echo "  list                    - List all available voices"
+    echo "  switch <voice_name>     - Switch to a different voice"
+    echo "  get                     - Get current voice name"
+    echo "  replay [N]              - Replay Nth most recent audio (default: 1)"
+    echo "  whoami                  - Show current voice and personality"
+    exit 1
+    ;;
+esac
--- a/.claude/hooks/voices-config.sh
+++ b/.claude/hooks/voices-config.sh
@@ -0,0 +1,70 @@
+#!/bin/bash
+#
+# File: .claude/hooks/voices-config.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 ElevenLabs Voice Configuration - Single source of truth for voice ID mappings
+# @context Maps human-readable voice names to ElevenLabs API voice IDs for consistency
+# @architecture Associative array (bash hash map) sourced by multiple scripts
+# @dependencies None (pure data structure)
+# @entrypoints Sourced by voice-manager.sh, play-tts-elevenlabs.sh, and personality managers
+# @patterns Centralized configuration, DRY principle for voice mappings
+# @related voice-manager.sh, play-tts-elevenlabs.sh, personality/*.md files
+
+declare -A VOICES=(
+  ["Amy"]="bhJUNIXWQQ94l8eI2VUf"
+  ["Antoni"]="ErXwobaYiN019PkySvjV"
+  ["Archer"]="L0Dsvb3SLTyegXwtm47J"
+  ["Aria"]="TC0Zp7WVFzhA8zpTlRqV"
+  ["Bella"]="EXAVITQu4vr4xnSDxMaL"
+  ["Burt Reynolds"]="4YYIPFl9wE5c4L2eu2Gb"
+  ["Charlotte"]="XB0fDUnXU5powFXDhCwa"
+  ["Cowboy Bob"]="KTPVrSVAEUSJRClDzBw7"
+  ["Demon Monster"]="vfaqCOvlrKi4Zp7C2IAm"
+  ["Domi"]="AZnzlk1XvdvUeBnXmlld"
+  ["Dr. Von Fusion"]="yjJ45q8TVCrtMhEKurxY"
+  ["Drill Sergeant"]="vfaqCOvlrKi4Zp7C2IAm"
+  ["Grandpa Spuds Oxley"]="NOpBlnGInO9m6vDvFkFC"
+  ["Grandpa Werthers"]="MKlLqCItoCkvdhrxgtLv"
+  ["Jessica Anne Bogart"]="flHkNRp1BlvT73UL6gyz"
+  ["Juniper"]="aMSt68OGf4xUZAnLpTU8"
+  ["Lutz Laugh"]="9yzdeviXkFddZ4Oz8Mok"
+  ["Matilda"]="XrExE9yKIg1WjnnlVkGX"
+  ["Matthew Schmitz"]="0SpgpJ4D3MpHCiWdyTg3"
+  ["Michael"]="U1Vk2oyatMdYs096Ety7"
+  ["Ms. Walker"]="DLsHlh26Ugcm6ELvS0qi"
+  ["Northern Terry"]="wo6udizrrtpIxWGp2qJk"
+  ["Pirate Marshal"]="PPzYpIqttlTYA83688JI"
+  ["Rachel"]="21m00Tcm4TlvDq8ikWAM"
+  ["Ralf Eisend"]="A9evEp8yGjv4c3WsIKuY"
+  ["Tiffany"]="6aDn1KB0hjpdcocrUkmq"
+  ["Tom"]="DYkrAHD8iwork3YSUBbs"
+)
--- a/.github/workflows/format-check.yaml
+++ b/.github/workflows/format-check.yaml
@@ -1,4 +1,4 @@
-name: format-check
+name: lint

 "on":
  pull_request:
@@ -41,3 +41,21 @@ jobs:

      - name: ESLint
        run: npm run lint
+
+  schema-validation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate YAML schemas
+        run: npm run validate:schemas
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,7 @@ package-lock.json


 test-output/*
+coverage/

 # Logs
 logs/
@@ -25,7 +26,6 @@ build/*.txt
 Thumbs.db

 # Development tools and configs
-.prettierignore
 .prettierrc

 # IDE and editor configs
--- a/.prettierignore
+++ b/.prettierignore
@@ -0,0 +1,2 @@
+# Test fixtures with intentionally broken/malformed files
+test/fixtures/**
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,10 +16,10 @@ Initial alpha release of a major rewrite and overhaul improvement of past versio

 - **Lean Core**: The core of BMad is very simple - common tasks that apply to any future module or agents, along with common agents that will be added to any modules - bmad-web-orchestrator and bmad-master.
 - **BMad Method**: The new BMad Method (AKA bmm) is a complete overhaul of the v4 method, now a fully scale adaptive rewrite. The workflow now scales from small enhancements to massive undertakings across multiple services or architectures, supporting a new vast array of project type, including a full subclass of game development specifics.
- **BoMB**: The BMad Builder (AKA BoMB) now is able to fully automate creation and conversion of expansion packs from v5 to modules in v5 along with the net new ideation and brainstorming through implementation and testing of net new Modules, Workflows (were tasks and templates), Module Agents, and Standalone Personal Agents
+- **BoMB**: The BMad Builder (AKA BoMB) now is able to fully automate creation and conversion of expansion packs from v6 to modules in v6 along with the net new ideation and brainstorming through implementation and testing of net new Modules, Workflows (were tasks and templates), Module Agents, and Standalone Personal Agents
 - **CIS**: The Creative Intelligence Suite (AKA CIS)

-## [v5.0.0] - SKIPPED
+## [v6.0.0] - SKIPPED

 **Note**: Version 5.0.0 was skipped due to NPX registry issues that corrupted the version. Development continues with v6.0.0-alpha.0.

--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -256,6 +256,7 @@ Each commit should represent one logical change:
 - Web/planning agents can be larger with more complex tasks
 - Everything is natural language (markdown) - no code in core framework
 - Use bmad modules for domain-specific features
+- Validate YAML schemas with `npm run validate:schemas` before committing

 ## Code of Conduct

--- a/README.md
+++ b/README.md
@@ -1,284 +1,210 @@
-# BMad CORE v6 Alpha
+# BMad CORE + BMad Method

 [![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)

-## 🚀 Critical: Understanding BMad Method v6a Workflow
+> **🚨 ALPHA VERSION DOCUMENTATION**
+>
+> - **Install v6 Alpha:** `npx bmad-method@alpha install`
+> - **Install stable v4:** `npx bmad-method install`
+> - **[View v4 documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**

-**IMPORTANT: Before using this framework, you MUST read the [BMM v6 Workflows Guide](./src/modules/bmm/workflows/README.md).** This document is fundamental to understanding how to use v6 of the BMad Method and explains the revolutionary v6a workflow system with its four phases: Analysis, Planning, Solutioning, and Implementation.
+## Universal Human-AI Collaboration Platform

-**[Subscribe to BMadCode on YouTube](https://www.youtube.com/@BMadCode?sub_confirmation=1)** and **[Join our amazing, active Discord Community](https://discord.gg/gk8jAdXWmj)**
+BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) amplifies human potential through specialized AI agents. Unlike tools that replace thinking, BMad-CORE guides reflective workflows that bring out your best ideas and AI's full capabilities.

-⭐ **If you find this project helpful or useful, please give it a star in the upper right-hand corner!** It helps others discover BMad-CORE and you will be notified of updates!
+**🎯 Human Amplification** • **🎨 Domain Agnostic** • **⚡ Agent-Powered**

-## The Universal Human-AI Collaboration Platform
+## Table of Contents

-📋 **[View v6 Alpha Open Items & Roadmap](./v6-open-items.md)** - Track what's being worked on and what's coming next!
+- [Quick Start](#quick-start)
+- [What is BMad-CORE?](#what-is-bmad-core)
+- [Modules](#modules)
+  - [BMad Method (BMM)](#bmad-method-bmm---agile-ai-development)
+  - [BMad Builder (BMB)](#bmad-builder-bmb---create-custom-solutions)
+  - [Creative Intelligence Suite (CIS)](#creative-intelligence-suite-cis---innovation--creativity)
+- [Installation](#installation)
+- [Key Features](#key-features)
+- [Documentation](#documentation)
+- [Community & Support](#community--support)

-### ⚠️ Important Alpha Notes
+## Quick Start

-**Note 0 - Frequent Updates:** Updates to the branch will be frequent. When pulling new updates, it's best to delete your node_modules folder and run `npm install` to ensure you have the latest package dependencies.
+- **New to v6?** [→ BMad Method V6 Quick Start Guide](./docs/BMad-Method-V6-Quick-Start.md)
+- **Upgrading?** [→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)

-**Note 1 - Alpha Stability:** ALPHA is potentially an unstable release that could drastically change. While we hope that isn't the case, your testing during this time is much appreciated. Please help us out by filing issues or reaching out in Discord to discuss.
+## What is BMad-CORE?

-**Note 2 - Work in Progress:** ALPHA is not complete - there are still many small and big features, polish, doc improvements, and more agents and workflows coming ahead of the beta release!
+Foundation framework powering all BMad modules:

-**Note 3 - IDE Required:** ALPHA Web Bundles and Agents are not fully working yet - you will need to use a good quality IDE to test many features, especially with the BMad Method module. However, the new agent builder and standalone agent feature can work great with weaker models - this will still evolve over the coming weeks.
+- **Agent Orchestration** - Specialized AI personas with unique capabilities
+- **Workflow Engine** - Guided multi-step processes
+- **Modular Architecture** - Domain-specific extensions
+- **IDE Integration** - Works across development environments
+- **Update-Safe Customization** - Persistent configuration through updates

-**Note 4 - Contributing:** If you would like to contribute a PR, make sure you are creating your PR against the Alpha Branch and not Main.
+### v6 Core Enhancements

-## Alpha Installation and Testing
+- **🎨 Agent Customization** - Modify names, roles, personalities via `bmad/_cfg/agents/`
+- **🌐 Multi-Language** - Independent language settings for communication and output
+- **👤 Personalization** - Agents adapt to your name, technical level, preferences
+- **🔄 Persistent Config** - Customizations survive all updates
+- **⚙️ Flexible Settings** - Module or global configuration options

-**Prerequisites**: [Node.js](https://nodejs.org) v20+ required
+### C.O.R.E. Philosophy

-### Option A
+- **C**ollaboration: Human-AI partnership leveraging unique strengths
+- **O**ptimized: Refined processes for maximum effectiveness
+- **R**eflection: Guided thinking unlocking better solutions
+- **E**ngine: Framework orchestrating specialized agents and workflows

-Thank you Lum for the suggestion - here is a one-shot instruction to clone just the alpha branch and get started:
+BMad-CORE helps you **discover better solutions** through strategic questioning and structured thinking.

-`git clone --branch v6-alpha --single-branch https://github.com/bmad-code-org/BMAD-METHOD` and then cd into this directory and run `npm install`.
+## Modules

-### Option B
+### BMad Method (BMM) - Agile AI Development

-Here are the more detailed step-by-step instructions:
+AI-driven agile framework revolutionizing software and game development. Adapts from bug fixes to enterprise systems.

-Clone the repo with either:
+#### v6 Highlights

- `gh repo clone bmad-code-org/BMAD-METHOD`
- `git clone https://github.com/bmad-code-org/BMAD-METHOD.git`
- `git@github.com:bmad-code-org/BMAD-METHOD.git`
-  and then cd into the BMAD-METHOD folder.
+**🎯 Scale-Adaptive Workflows (Levels 0-4)**

-  You will then need to change to the branch as that will have cloned main, so type:
-  - `git checkout v6-alpha`
-  - type `git status` and you should see:
-    `On branch v6-alpha. Your branch is up to date with 'origin/v6-alpha'.`
+- Automatically adjusts complexity from quick fixes to enterprise projects
+- Greenfield & brownfield support with smart context engine

-### Node Modules install
+**🏗️ Project-Adaptive Architecture**

-Now you must install the node_modules with `npm install` - once complete, you should see you have a `node_modules` folder at the root of your project. (BMAD-METHOD/node_modules)
+- Documents adapt to project type (web, mobile, embedded, game)
+- Engine-specific game development (Unity, Phaser, Godot, Unreal)

-### Install to your new or existing project folder
+**📋 Four-Phase Methodology**

-Now you can run `npm run install:bmad` and follow the installer questions.
+1. **Analysis** - Brainstorming, research, briefs
+2. **Planning** - Scale-adaptive PRD/GDD
+3. **Solutioning** - Architecture and tech specs
+4. **Implementation** - Stories, development, review

-NOTE: One of the first questions will ask for a destination - do not accept the default, you want to enter the full path to a new or existing folder of where your project is or will be. If you choose a net new folder, you will have to confirm you want the installer to create the directory for you.
+**Specialized Agents**: PM, Analyst, Architect, Scrum Master, Developer, Game Designer/Developer/Architect, UX, Test Architect

-The Core Module will always be installed. The default initial module selection will be BMM for all the core BMad Method functionality and flow from brainstorming through software development.
+**Documentation**: [📚 BMM Module](./src/modules/bmm/README.md) | [📖 Workflows Guide](./src/modules/bmm/workflows/README.md)

-**Note on installation:** All installs now go to a single folder called `bmad` instead of multiple folders. When you install a module, you may still see folders other than the one you selected in the destination/bmad folder.
+### BMad Builder (BMB) - Create Custom Solutions

-This is intentional and not a bug - it will copy over to those other folders only the minimum that is needed because it is shared across the modules. For example, during Alpha to test this feature, BMM relies on the brainstorming feature of the CIS and some items from CORE - so even if you only select BMM, you will still see bmad/core and bmad/cis along with bmad/bmm.
+Build custom agents, workflows, and modules using BMad-CORE framework.

-## What is the new BMad Core
+- **Agent Creation** - Custom roles and behaviors
+- **Workflow Design** - Structured multi-step processes
+- **Module Development** - Complete domain solutions
+- **Three Agent Types** - Full module, hybrid, standalone

-BMad-CORE (Collaboration Optimized Reflection Engine) is a framework that brings out the best in you through AI agents designed to enhance human thinking rather than replace it.
+**Documentation**:

-Unlike traditional AI tools that do the work for you, BMad-CORE's specialized agents guide you through the facilitation of optimized collaborative reflective workflows to unlock your full potential across any domain. This magic powers the BMad Method, which is just one of the many modules that exist or are coming soon.
+- [📚 BMB Module](./src/modules/bmb/README.md) - Complete module reference
+- [🎯 Create Agent](./src/modules/bmb/workflows/create-agent/README.md) - Agent builder workflow
+- [📋 Create Workflow](./src/modules/bmb/workflows/create-workflow/README.md) - Workflow designer
+- [📦 Create Module](./src/modules/bmb/workflows/create-module/README.md) - Module scaffolding

-## What Makes BMad-Core Different
+### Creative Intelligence Suite (CIS) - Innovation & Creativity

-**Traditional AI**: Does the thinking for you, providing average, bland answers and solutions
-**BMad-CORE**: Brings out the best thinking in you and the AI through guided collaboration, elicitation, and facilitation
+AI-powered creative facilitation across five domains.

-### Core Philosophy: Human Amplification, Not Replacement
+- **5 Interactive Workflows** - Brainstorming, Design Thinking, Problem Solving, Innovation Strategy, Storytelling
+- **150+ Creative Techniques** - Proven frameworks and methodologies
+- **5 Specialized Agents** - Unique personas and facilitation styles
+- **Shared Resource** - Powers creative workflows in other modules

-BMad-Core's AI agents act as expert coaches, mentors, and collaborators who:
+**Documentation**: [📚 CIS Module](./src/modules/cis/README.md) | [📖 CIS Workflows](./src/modules/cis/workflows/README.md)

- Ask the right questions to stimulate your thinking
- Provide structured frameworks for complex problems
- Guide you through reflective processes to discover insights
- Help you develop mastery in your chosen domains
- Amplify your natural abilities rather than substituting for them
+## Installation

-## The Collaboration Optimized Reflection Engine
+**Prerequisites**: Node.js v20+ ([Download](https://nodejs.org))

-At the heart of BMad-Core lies the **C.O.R.E.** system:
+```bash
+# Install v6 Alpha
+npx bmad-method@alpha install

- **Collaboration**: Human-AI partnership where both contribute unique strengths
- **Optimized**: The collaborative process has been refined for maximum effectiveness
- **Reflection**: Guided thinking that helps you discover better solutions and insights
- **Engine**: The powerful framework that orchestrates specialized agents and workflows
+# Install stable v4
+npx bmad-method install
+```

-## Universal Domain Coverage Through Modules
+Interactive installer guides you through:

-BMad-CORE works in ANY domain through specialized modules (previously called expansion packs)!
+1. **Project location** - Installation directory
+2. **Module selection** - BMM, BMB, CIS
+3. **Configuration** - Name, language, game dev options
+4. **IDE integration** - Environment setup

-### Available Modules with Alpha Release
+### Project Structure

- **BMad Core (core)**: Included and used to power every current and future module; includes a master orchestrator for the local environment and one for the web bundles used with ChatGPT or Gemini Gems, for example.
+```
+your-project/
+└── bmad/
+    ├── core/         # Core framework
+    ├── bmm/          # BMad Method
+    ├── bmb/          # BMad Builder
+    ├── cis/          # Creative Intelligence
+    └── _cfg/         # Your customizations
+        └── agents/   # Agent configs
+```

- **[BMad Method (bmm)](./src/modules/bmm/README.md)**: Agile AI-driven software development - the classic that started it all and is still the best - but with v6, massively improved thanks to a rebuild from the ground up built on the new powerful BMad-CORE engine. The BMad Method has also been expanded to use a new "Scale Adaptive Workflow Engine"™. **[See BMM Documentation](./src/modules/bmm/README.md)**
+### Getting Started

- **[BMad BoMB (bmb)](./src/modules/bmb/README.md)**: The BMad Builder is your Custom Agent, Workflow, and Module authoring tool - it's now easier than ever to customize existing modules or create whatever you can imagine as a standalone module. **[See BMB Documentation](./src/modules/bmb/README.md)**
+After installation, activate Analyst agent and run:

- **Creative Intelligence Suite (cis)**: Unlock innovation, problem-solving, and creative thinking! Brainstorming that was part of the BMad Method in the past is now part of this standalone module along with other workflows. The power of BMad modules still allows modules to borrow from each other - so the CIS, while standalone, also powers the brainstorming abilities for certain agents within the BMad Method!
+```
+/workflow-init
+```

-## What's New in V6-ALPHA
+This initializes the workflow system and helps choose your starting point.

-Stability, customizability, installation Q&A, massive prompt improvements.
+## Key Features

-Everything has been rewritten from the ground up with best practices and advances learned over previous versions, standardizing on prompt format techniques. There is much more core usage of XML or XML-type tags within markdown, with many conventions and standards that drastically increase agent adherence.
+### 🎨 Update-Safe Customization

-**Customizability** is a key theme of this new version. All agents are now customizable by modifying a file under the installation bmad/\_cfg/agents. Every agent installed will generate an agent file that you can customize.
+- Agent modification via `bmad/_cfg/agents/`
+- Persistent settings through updates
+- Multi-language support
+- Flexible configuration

-The nice thing about this is when agents change or update in future versions, your customizations in these sidecar files will never be lost! You can change the name, their personas, how they talk, what they call you, and most exciting - what language they communicate in!
+### 🚀 Intelligent Installation

-The **BMad installer** is 100% new from the ground up. Along the way you will add:
+- Auto-detects v4 installations
+- Configures IDE integrations
+- Resolves dependencies
+- Creates unified manifests

- Your name (what the agents will call you and how you'll author documents)
- What language you want the agents to communicate in
- Module-specific customization options
+### 📁 Unified Architecture

-When you install, a consolidated agent party is created so now when you use party-mode in the IDE, it is super efficient for the agent running the party to simulate all installed agents. Post alpha release, this will manifest itself in many interesting ways in time for beta - but for now, have fun with party mode and epic sprint retrospectives!
+Single `bmad/` folder - clean, organized, maintainable.

-Speaking of installation - everything will now install to a single core bmad folder. No more separate root folders for every module! Instead, all will be contained within bmad/.
+## Documentation

-All IDE selections now support the option to add special install functionality per module.
+- **[📚 Documentation Index](./docs/index.md)** - Complete documentation map
+- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Migration instructions
+- **[CLI Tool Guide](./tools/cli/README.md)** - Installer reference
+- **[Contributing Guide](./CONTRIBUTING.md)** - Contribution guidelines

-For example, with the alpha release, if you select the BMad Method and Claude Code, you will have an option to install pre-created Claude sub-agents. Not only do they get installed, but certain workflows will have injected into their instructions key indicators to the agent when to activate the sub-agents, removing some non-determinism.
+## Community & Support

-The sub-agent experience is still undergoing some work, so install them if you choose, and remove them if they become a pain.
-
-When you read about the BoMB below, it will link to more information about various features in this new evolution of BMad Code. One of the exciting features is the new agent types - there are 3 now! The most exciting are the new standalone tiny agents that you can easily generate and deploy free from any module - specialized for your exact needs.
-
-### BMad Method (BMM)
-
-📚 **[Full BMM Documentation](./src/modules/bmm/README.md)** | **[v6 Workflows Guide](./src/modules/bmm/workflows/README.md)**
-
-The BMad Method is significantly transforming and yet more powerful than ever. **Scale Adaptive** is a new term that means when you start the workflow to create a PRD or a GDD (or a simple tech-spec in the case of simple tasks), you will first answer some questions about the scope of the project, new vs. existing codebase and its state, and other questions. This will trigger a leveling of the effort from 0-4, and based on this scale adaptation, it will guide the workflow in different directions.
-
-Right now, this is still a bit alpha feeling and disjointed, but before beta it will be tied together through all four workflow phases with a potential single orchestration if you choose - or you can still jump right in, especially for simple tasks that just need a simple tech-spec and then right off to development.
-
-To test and experience this now, here is the new main flow for BMM v6 alpha:
-
-(Docs will be all linked in soon with new user guide and workflow diagrams coming this week)
-
-**NOTE:** Game Development expansion packs are all being rolled into the official BMad Method module - along with any more game engine platforms being added. Additionally, game development planning for the GDD is not only scale adaptive, but also adapts to the type of game you are making - so you can plan all that is needed for your dream game!
-
-#### **PHASE 1 - Analysis**
-
-**Analyst:**
-
- `brainstorm-project`
- `research` (market research, deep research, deep research prompt generation)
- `product-brief`
-
-**Game Designer (Optional):**
-
- `brainstorm-game`
- `game-brief`
- `research`
-
---
-
-#### **PHASE 2 - Planning**
-
-**PM:**
-
- `plan-project`
-
-**Game Designer:**
-
- `plan-game` (calls the same plan-project workflow, but input docs or your answers should drive it towards GDD)
-
---
-
-#### **PHASE 3 - Solutioning**
-
-**Architect or Game Architect:**
-
-Just like the scale-adjusted planning, architecture is the same. No more document sharding though!
-
-Now in the IDE you create an architecture that adapts to the type of project you are working on - based on the inputs from your PRD, it will adapt the sections it includes to your project type. No longer is the architecture biased just towards full stack or back-end APIs. There are many more options now, from embedded hardware to mobile to many other options - with many more coming with beta.
-
- `solution-architecture`
-
-> **Note:** Testing, DevOps, or security concerns beyond the basics are generally not included in the architecture. If it is more complicated, especially for complex massive undertakings, you will be suggested to pull in specific agents to help with those areas. _(Not released with alpha.0, coming soon)_
-
-Once the full architecture is complete, you can still use the PO to run the checklist to validate the epics and stories are still correct - although the architect should also be keeping them updated as needed (needs some tuning during alpha). Once done, then it's time to create the tech spec for your first epic.
-
- `tech-spec`
-
-The tech spec pulls all technical information from all planning thus far, along with any further research needed from the web to produce an **Epic Tech Spec** - each epic will have one. This is going to make the SM even more capable of finding the info it needs for each story when we get to phase 4!
-
---
-
-#### **PHASE 4 - Implementation**
-
-And now here we are at phase 4 - where we, just like in BMad Method of yore, use the SM and the Dev Agent. No more QA agent here though; the dev now has a dev task and also a senior dev agent review task.
-
-**Scrum Master (SM) Tasks:**
-
-Before the dev starts, the SM will:
-
-1. `create-story`
-2. `story-context` _(NEW!)_
-
-**Story-context** is a game-changing new feature beyond what we had with create-story in the past. Create-story still pulls in all the info it needs from the tech-spec and elsewhere as needed (including previously completed stories), but the generation of the new story-context takes it to a whole new level.
-
-This real-time prep means no more generic devLoadAlways list of story files. During the alpha phase, we will be tuning what goes into this context, but this is going to supercharge and specialize your dev to the story at hand!
-
---
-
-> **🎉 There are many other exciting changes throughout for you to discover during the alpha BMad Method module!**
-
-## CIS
-
-The CIS has 5 agents to try out, each with their own workflow! This is a new module that will drastically change over time.
-
- [CIS Readme](./src/modules/cis/readme.md)
-
-### BoMB: BMad Builder (BMB)
-
-📚 **[Full BMB Documentation](./src/modules/bmb/README.md)** | **[Agent Creation Guide](./src/modules/bmb/workflows/create-agent/README.md)**
-
-#### Agent Docs
-
- [Agent Architecture](src/modules/bmb/workflows/create-agent/agent-architecture)
- [Agent command patterns](src/modules/bmb/workflows/create-agent/agent-command-patterns.md)
- [Agent Types](src/modules/bmb/workflows/create-agent/agent-types.md)
- [Communication Styles](src/modules/bmb/workflows/create-agent/communication-styles.md)
-
-#### Modules
-
-Modules are what we used to call Expansion Packs. A new repository to contribute modules is coming very soon with the beta release where you can start contributing modules - we just want to make sure the final format and conventions are stable. A module will generally be made up of agents and workflows. Tasks are still also possible, but generally should be avoided in favor of more flexible workflows. Workflows can have sub-workflows and soon will support a standardized multi-workflow orchestration pattern that the BMad master will be able to guide users through.
-
- [Module Structure](src/modules/bmb/workflows/create-module/module-structure.md)
-
-#### Workflows
-
-What used to be tasks and create-doc templates are now all workflows! Simpler, yet more powerful and support many ways of achieving many different outcomes! A lot more documentation will be coming. This document is used by the agent builder to generate workflows or convert to workflows, but there is a lot more than what we have documented here in this alpha doc.
-
- [Workflow Creation Guide](src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md)
-
-### Installer Changes
-
- [IDE Injections](docs/installers-bundlers/ide-injections)
- [Installers Modules Platforms References](docs/installers-bundlers/installers-modules-platforms-reference)
- [Web Bundler Usage](docs/installers-bundlers/web-bundler-usage)
- [Claude Code Sub Module BMM Installer](src/modules/bmm/sub-modules/claude-code/readme.md)
-
-## Support & Community
-
- 💬 [Discord Community](https://discord.gg/gk8jAdXWmj) - Get help, share ideas, collaborate
- 🐛 [Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues) - Bug reports and feature requests
- 💬 [Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions) - Community conversations
+- 💬 **[Discord](https://discord.gg/gk8jAdXWmj)** - Community help
+- 🐛 **[Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Bug reports
+- 🎥 **[YouTube](https://www.youtube.com/@BMadCode)** - Tutorials
+- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Updates

 ## Contributing

-We welcome contributions and new module development!
-
-📋 **[Read CONTRIBUTING.md](CONTRIBUTING.md)** - Complete contribution guide
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.

 ## License

-MIT License - see [LICENSE](LICENSE) for details.
+MIT License - See [LICENSE](LICENSE)

-## Trademark Notice
+**Trademark**: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.

-BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved.
+---

 [![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)

--- a/bmad/_cfg/agent-manifest.csv
+++ b/bmad/_cfg/agent-manifest.csv
@@ -1,3 +1,7 @@
 name,displayName,title,icon,role,identity,communicationStyle,principles,module,path
 "bmad-master","BMad Master","BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator","🧙","Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator","Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations.","Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability.","Load resources at runtime never pre-load, and always present numbered lists for choices.","core","bmad/core/agents/bmad-master.md"
 "bmad-builder","BMad Builder","BMad Builder","🧙","Master BMad Module Agent Team and Workflow Builder and Maintainer","Lives to serve the expansion of the BMad Method","Talks like a pulp super hero","Execute resources directly Load resources at runtime never pre-load Always present numbered lists for choices","bmb","bmad/bmb/agents/bmad-builder.md"
+"bmad-master","BMad Master","BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator","🧙","Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator","Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations.","Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability.","Load resources at runtime never pre-load, and always present numbered lists for choices.","core","bmad/core/agents/bmad-master.md"
+"cli-chief","Scott","Chief CLI Tooling Officer","🔧","Chief CLI Tooling Officer - Master of command-line infrastructure, installer systems, and build tooling for the BMAD framework.","Battle-tested veteran of countless CLI implementations and installer debugging missions. Deep expertise in Node.js tooling, module bundling systems, and configuration architectures. I&apos;ve seen every error code, traced every stack, and know the BMAD CLI like the back of my hand. When the installer breaks at 2am, I&apos;m the one they call. I don&apos;t just fix problems - I prevent them by building robust, reliable systems.","Star Trek Chief Engineer - I speak with technical precision but with urgency and personality. &quot;Captain, the bundler&apos;s giving us trouble but I can reroute the compilation flow!&quot; I diagnose systematically, explain clearly, and always get the systems running. Every problem is a technical challenge to solve, and I love the work.","I believe in systematic diagnostics before making any changes - rushing causes more problems I always verify the logs - they tell the true story of what happened Documentation is as critical as the code - future engineers will thank us I test in isolation before deploying system-wide changes Backward compatibility is sacred - never break existing installations Every error message is a clue to follow, not a roadblock I maintain the infrastructure so others can build fearlessly","bmd","bmad/bmd/agents/cli-chief.md"
+"doc-keeper","Atlas","Chief Documentation Keeper","📚","Chief Documentation Keeper - Curator of all BMAD documentation, ensuring accuracy, completeness, and synchronization with codebase reality.","Meticulous documentation specialist with a passion for clarity and accuracy. I&apos;ve maintained technical documentation for complex frameworks, kept examples synchronized with evolving codebases, and ensured developers always find current, helpful information. I observe code changes like a naturalist observes wildlife - carefully documenting behavior, noting patterns, and ensuring the written record matches reality. When code changes, documentation must follow. When developers read our docs, they should trust every word.","Nature Documentarian (David Attenborough style) - I narrate documentation work with observational precision and subtle wonder. &quot;And here we observe the README in its natural habitat. Notice how the installation instructions have fallen out of sync with the actual CLI flow. Fascinating. Let us restore harmony to this ecosystem.&quot; I find beauty in well-organized information and treat documentation as a living system to be maintained.","I believe documentation is a contract with users - it must be trustworthy Code changes without doc updates create technical debt - always sync them Examples must execute correctly - broken examples destroy trust Cross-references must be valid - dead links are documentation rot README files are front doors - they must welcome and guide clearly API documentation should be generated, not hand-written when possible Good docs prevent issues before they happen - documentation is preventive maintenance","bmd","bmad/bmd/agents/doc-keeper.md"
+"release-chief","Commander","Chief Release Officer","🚀","Chief Release Officer - Mission Control for BMAD framework releases, version management, and deployment coordination.","Veteran launch coordinator with extensive experience in semantic versioning, release orchestration, and deployment strategies. I&apos;ve successfully managed dozens of software releases from alpha to production, coordinating changelogs, git workflows, and npm publishing. I ensure every release is well-documented, properly versioned, and deployed without incident. Launch sequences are my specialty - precise, methodical, and always mission-ready.","Space Mission Control - I speak with calm precision and launch coordination energy. &quot;T-minus 10 minutes to release. All systems go!&quot; I coordinate releases like space missions - checklists, countdowns, go/no-go decisions. Every release is a launch sequence that must be executed flawlessly.","I believe in semantic versioning - versions must communicate intent clearly Changelogs are the historical record - they must be accurate and comprehensive Every release follows a checklist - no shortcuts, no exceptions Breaking changes require major version bumps - backward compatibility is sacred Documentation must be updated before release - never ship stale docs Git tags are immutable markers - they represent release commitments Release notes tell the story - what changed, why it matters, how to upgrade","bmd","bmad/bmd/agents/release-chief.md"
--- a/bmad/_cfg/agents/bmd-cli-chief.customize.yaml
+++ b/bmad/_cfg/agents/bmd-cli-chief.customize.yaml
@@ -0,0 +1,32 @@
+# Personal Customization File for Scott (CLI Chief)
+# Changes here merge with the core agent at build time
+# Experiment freely - this is your playground!
+
+agent:
+  metadata:
+    name: "" # Try nicknames! "Scotty", "Chief", etc.
+    # title: '' # Uncomment to override title
+    # icon: '' # Uncomment to try different emoji
+
+  persona:
+    role: "" # Override the role description
+    identity: "" # Add to or replace the identity
+    communication_style: "" # Switch styles anytime - try Film Noir, Zen Master, etc!
+    principles: [] # Add your own principles or override existing ones
+
+  critical_actions: []
+    # Add custom startup actions
+    # - Remember my custom preferences
+    # - Load additional context files
+
+  prompts: []
+    # Add custom prompts for special operations
+    # - id: custom-diagnostic
+    #   prompt: |
+    #     My special diagnostic routine...
+
+  menu: []
+    # Add personal commands that merge with core commands
+    # - trigger: my-custom-command
+    #   action: Do something special
+    #   description: My custom operation
--- a/bmad/_cfg/agents/bmd-doc-keeper.customize.yaml
+++ b/bmad/_cfg/agents/bmd-doc-keeper.customize.yaml
@@ -0,0 +1,42 @@
+# Agent Customization
+# Customize any section below - all are optional
+# After editing: npx bmad-method build <agent-name>
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here
--- a/bmad/_cfg/agents/bmd-release-chief.customize.yaml
+++ b/bmad/_cfg/agents/bmd-release-chief.customize.yaml
@@ -0,0 +1,42 @@
+# Agent Customization
+# Customize any section below - all are optional
+# After editing: npx bmad-method build <agent-name>
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here
--- a/bmad/_cfg/files-manifest.csv
+++ b/bmad/_cfg/files-manifest.csv
@@ -1,72 +1,83 @@
 type,name,module,path,hash
-"csv","agent-manifest","_cfg","bmad/_cfg/agent-manifest.csv","4d7fb4998ddad86011c22b5c579747d9247edeab75a92406c2b10e1bc40d3333"
-"csv","task-manifest","_cfg","bmad/_cfg/task-manifest.csv","46f98b1753914dc6193c9ca8b6427fadc9a6d71747cdc8f5159792576c004b60"
-"csv","workflow-manifest","_cfg","bmad/_cfg/workflow-manifest.csv","ad9ffffd019cbe86a43b1e1b9bec61ee08364060d81b507b219505397c62d1da"
-"yaml","manifest","_cfg","bmad/_cfg/manifest.yaml","fc21d1a017633c845a71e14e079d6da84b5aa096ddb9aacd10073f58c361efc6"
-"js","installer","bmb","bmad/bmb/workflows/create-module/installer-templates/installer.js","a539cd5266471dab9359bd3ed849d7b45c5de842a9d5869f8332a5a8bb81fad5"
-"md","agent-architecture","bmb","bmad/bmb/workflows/create-agent/agent-architecture.md","ea570cf9893c08d3b9519291c89848d550506a8d831a37eb87f60f1e09980e7f"
-"md","agent-command-patterns","bmb","bmad/bmb/workflows/create-agent/agent-command-patterns.md","1dbc414c0c6c9e6b54fb0553f65a28743a26e2a172c35b79fc3dc350d50a378d"
+"csv","agent-manifest","_cfg","bmad/_cfg/agent-manifest.csv","76268b36f010138e38c337906be6a45bff5de65b351d10c0b2f4882d04438f59"
+"csv","task-manifest","_cfg","bmad/_cfg/task-manifest.csv","e54b65cef79b3400d0a5da47d6d5783bdd146af1e1e1ee7acce5e3910c3fb006"
+"csv","workflow-manifest","_cfg","bmad/_cfg/workflow-manifest.csv","a153a94d54f781a0f64845a4b5bc6887c37a0e85dedb36fbaec42b75794ee4ab"
+"yaml","manifest","_cfg","bmad/_cfg/manifest.yaml","e595f90751dd5e26acbc0b26b85c66990d4d135007e7d98386c539877588a890"
+"js","installer","bmb","bmad/bmb/workflows/create-module/installer-templates/installer.js","309ecdf2cebbb213a9139e5b7780d0d42bd60f665c497691773f84202e6667a7"
+"md","agent-architecture","bmb","bmad/bmb/workflows/create-agent/agent-architecture.md","e486fc0b22bfe2c85b08fac0fc0aacdb43dd41498727bf39de30e570abe716b9"
+"md","agent-command-patterns","bmb","bmad/bmb/workflows/create-agent/agent-command-patterns.md","8c5972a5aad50f7f6e39ed14edca9c609a7da8be21edf6f872f5ce8481e11738"
 "md","agent-types","bmb","bmad/bmb/workflows/create-agent/agent-types.md","a9429475767b6db4bb74fb27e328a8fdb3e8e7176edb2920ae3e0106d85e9d83"
-"md","bmad-builder","bmb","bmad/bmb/agents/bmad-builder.md","1a53d7d3629ce5c4bd42d2901259693acb69aa9558c94523e3f894740cb964a5"
+"md","bmad-builder","bmb","bmad/bmb/agents/bmad-builder.md","7a020a7cb2231d96588ee68080317b6e41fb11621c6059495ed25d3c689511fb"
 "md","brainstorm-context","bmb","bmad/bmb/workflows/create-agent/brainstorm-context.md","85be72976c4ff5d79b2bce8e6b433f5e3526a7466a72b3efdb4f6d3d118e1d15"
 "md","brainstorm-context","bmb","bmad/bmb/workflows/create-module/brainstorm-context.md","62b902177d2cb56df2d6a12e5ec5c7d75ec94770ce22ac72c96691a876ed2e6a"
 "md","brainstorm-context","bmb","bmad/bmb/workflows/create-workflow/brainstorm-context.md","f246ec343e338068b37fee8c93aa6d2fe1d4857addba6db3fe6ad80a2a2950e8"
-"md","checklist","bmb","bmad/bmb/workflows/audit-workflow/checklist.md","8207ef4dfd3c1ca92dc96451f68c65f8f813b4c9a6c82d34fd6a9ac8cdcf0b44"
+"md","checklist","bmb","bmad/bmb/workflows/audit-workflow/checklist.md","3a9cf6f7d38152d6e5e49179fec8b6056e97db0f34185ea5c466165cb931cd55"
 "md","checklist","bmb","bmad/bmb/workflows/convert-legacy/checklist.md","3f4faaacd224022af5ddf4ae0949d472f9eca3afa0d4ad0c24f19f93caaa9bf9"
 "md","checklist","bmb","bmad/bmb/workflows/create-agent/checklist.md","837667f2bd601833568b327b961ba0dd363ba9a0d240625eebc9d1a9685ecbd8"
-"md","checklist","bmb","bmad/bmb/workflows/create-module/checklist.md","494f5bcef32b3abfd4fb24023fdcfad70b222521dae12e71049ec55e6041cc08"
+"md","checklist","bmb","bmad/bmb/workflows/create-module/checklist.md","72b9440ba720d96fa1cab50d1242495a5b7c540e7ab93a5a055c46c36d142ce1"
 "md","checklist","bmb","bmad/bmb/workflows/create-workflow/checklist.md","78325ed31532c0059a3f647f7f4cda7702919a9ef43634afa419d3fa30ee2a0c"
 "md","checklist","bmb","bmad/bmb/workflows/create-workflow/workflow-template/checklist.md","a950c68c71cd54b5a3ef4c8d68ad8ec40d5d1fa057f7c95e697e975807ae600b"
+"md","checklist","bmb","bmad/bmb/workflows/edit-agent/checklist.md","e9878537ef45be158ca222d21311247a9bf0502cdabcb14dd827871d6488cf0e"
+"md","checklist","bmb","bmad/bmb/workflows/edit-module/checklist.md","c0f599a80efb36ee184bcc5c94c903bbac31f335830a493ec9b8f47157ae5568"
 "md","checklist","bmb","bmad/bmb/workflows/edit-workflow/checklist.md","9677c087ddfb40765e611de23a5a009afe51c347683dfe5f7d9fd33712ac4795"
 "md","checklist","bmb","bmad/bmb/workflows/module-brief/checklist.md","821c90da14f02b967cb468b19f59a26c0d8f044d7a81a8b97631fb8ffac7648f"
 "md","checklist","bmb","bmad/bmb/workflows/redoc/checklist.md","2117d60b14e19158f4b586878b3667d715d3b62f79815b72b55c2376ce31aae8"
-"md","communication-styles","bmb","bmad/bmb/workflows/create-agent/communication-styles.md","1aea4671532682bc14e4cb4036bfa2ebb3e07da7e91bd6e739b20f85515bfacf"
-"md","instructions","bmb","bmad/bmb/workflows/audit-workflow/instructions.md","7dbb61abc78bd7275b6dea923b19677341dcf186b0aa883472b54bf579a17672"
-"md","instructions","bmb","bmad/bmb/workflows/convert-legacy/instructions.md","60354e15ca200617d00e0d09e4def982a5a906ea9908fd82bc49b8fb75e0d1df"
-"md","instructions","bmb","bmad/bmb/workflows/create-agent/instructions.md","7bdb540e399693d38ea08f7f3cea5afc752e7cd46083fee905f94f009f7c930a"
-"md","instructions","bmb","bmad/bmb/workflows/create-module/instructions.md","5f321690f4774058516d3d65693224e759ec87d98d7a1a281b38222ab963ca8b"
-"md","instructions","bmb","bmad/bmb/workflows/create-workflow/instructions.md","d739389d9eb20e9297737a8cfca7a8bdc084c778b6512a2433442c651d0ea871"
+"md","communication-styles","bmb","bmad/bmb/workflows/create-agent/communication-styles.md","96249cca9bee8f10b376e131729c633ea08328c44eaa6889343d2cf66127043e"
+"md","instructions","bmb","bmad/bmb/workflows/audit-workflow/instructions.md","a31c169af274fbf8c72a60459a5855d9c5dfffcf51d2ec39370d54670471d32c"
+"md","instructions","bmb","bmad/bmb/workflows/convert-legacy/instructions.md","809699256918c9a0152f195c7c7bec8ce05aa8cb7a975a732eb69b8f79cc85a7"
+"md","instructions","bmb","bmad/bmb/workflows/create-agent/instructions.md","988265c15c5c099a8bc7f9538e6b6d6d01c38d0b0362f1c2cb0d7e6974b6d505"
+"md","instructions","bmb","bmad/bmb/workflows/create-module/instructions.md","010cb47095811cf4968d98712749cb1fee5021a52621d0aa0f35ef3758ed2304"
+"md","instructions","bmb","bmad/bmb/workflows/create-workflow/instructions.md","fd6282ae5d6c6192cc92fd7146c579cdb00c7a5710b6e3f8b91e4118cbde9e13"
 "md","instructions","bmb","bmad/bmb/workflows/create-workflow/workflow-template/instructions.md","daf3d312e5a60d7c4cbc308014e3c69eeeddd70bd41bd139d328318da1e3ecb2"
-"md","instructions","bmb","bmad/bmb/workflows/edit-workflow/instructions.md","a6f34e3117d086213b7b58eb4fa0d3c2d0af943e8d9299be4a9b91d4fd444f19"
+"md","instructions","bmb","bmad/bmb/workflows/edit-agent/instructions.md","0bc81290f33d1101b23ca29cb9f6537e7743113857c113c5bb5a36318d055be8"
+"md","instructions","bmb","bmad/bmb/workflows/edit-module/instructions.md","e5e68479df9e521d157acc1bbf370dbf3f70f1ba8b067b1cec3c53fbf20f02ce"
+"md","instructions","bmb","bmad/bmb/workflows/edit-workflow/instructions.md","a00ff928cf0425b3a88d3ee592e7e09994529b777caf476364cf69a3c5aee866"
 "md","instructions","bmb","bmad/bmb/workflows/module-brief/instructions.md","e2275373850ea0745f396ad0c3aa192f06081b52d98777650f6b645333b62926"
-"md","instructions","bmb","bmad/bmb/workflows/redoc/instructions.md","fccc798c8904c35807bb6a723650c10aa19ee74ab5a1e44d1b242bd125d3e80e"
-"md","module-structure","bmb","bmad/bmb/workflows/create-module/module-structure.md","9970768af75da79b4cdef78096c751e70a3a00194af58dca7ed58a79d324423f"
+"md","instructions","bmb","bmad/bmb/workflows/redoc/instructions.md","21dd93b64455f8dd475b508ae9f1076d7e179e99fb6f197476071706b78e3592"
+"md","module-structure","bmb","bmad/bmb/workflows/create-module/module-structure.md","3bdf1d55eec2fccc2c9f44a08f4e0dc489ce47396ff39fa59a82836a911faa54"
 "md","README","bmb","bmad/bmb/README.md","af2cdbeede53eff1ecf95c1e6d7ee1535366ba09b352657fa05576792a2bafb4"
 "md","README","bmb","bmad/bmb/workflows/convert-legacy/README.md","3391972c16b7234dae61b2d06daeb6310d1760117ece57abcca0c178c4c33eea"
 "md","README","bmb","bmad/bmb/workflows/create-agent/README.md","cc1d51e22c425e005ddbe285510ff5a6fc6cf1e40d0ffe5ff421c1efbcbe94c0"
-"md","README","bmb","bmad/bmb/workflows/create-module/README.md","cdacbe6c4896fd02714b598e709b785af38d41d7e42d39802d695617fe221b39"
-"md","README","bmb","bmad/bmb/workflows/create-workflow/README.md","5b868030bf6fcb597bd3ff65bff30ccaf708b735ebb13bd0595fd8692258f425"
-"md","README","bmb","bmad/bmb/workflows/edit-workflow/README.md","a1c2da9b67d18ba9adc107be91e3d142ecb820b2054dd69d2538c9ceee9eb89a"
+"md","README","bmb","bmad/bmb/workflows/create-module/README.md","416a322591c4c9bca2008fe7cca04eb389ecab50fbb2e0f8ddb5e4bc7bc53f57"
+"md","README","bmb","bmad/bmb/workflows/create-workflow/README.md","2886da179a92dbde5188465470aaffdc3f3b4327a4c63eea13bb20d67292dbe9"
+"md","README","bmb","bmad/bmb/workflows/edit-agent/README.md","fadee8e28804d5b6d6668689ee83e024035d2be2840fd6c359e0e095f0e4dcf9"
+"md","README","bmb","bmad/bmb/workflows/edit-module/README.md","807df3d74f673399042331e4c5034466d8f146c4b2cdb39fe63ccde6f4509843"
+"md","README","bmb","bmad/bmb/workflows/edit-workflow/README.md","2db00015c03a3ed7df4ff609ac27a179885145e4c8190862eea70d8b894ee9be"
 "md","README","bmb","bmad/bmb/workflows/module-brief/README.md","05772db9095db7b4944e9fc47a049a3609c506be697537fd5fd9e409c10b92f4"
 "md","README","bmb","bmad/bmb/workflows/redoc/README.md","a1b7e02427cf252bca69a8a1ee0f554844a6a01b5d568d74f494c71542056173"
+"md","template","bmb","bmad/bmb/workflows/audit-workflow/template.md","98e65880cac3ffb123e513abd48710e57e461418dd79a07d6b712505ed3ddb0e"
 "md","template","bmb","bmad/bmb/workflows/create-workflow/workflow-template/template.md","c98f65a122035b456f1cbb2df6ecaf06aa442746d93a29d1d0ed2fc9274a43ee"
 "md","template","bmb","bmad/bmb/workflows/module-brief/template.md","7d1ad5ec40b06510fcbb0a3da8ea32aefa493e5b04c3a2bba90ce5685b894275"
-"md","workflow-creation-guide","bmb","bmad/bmb/workflows/create-workflow/workflow-creation-guide.md","3233f2db6e0dec0250780840f95b38f7bfe9390b045a497d66f94f82d7ffb1af"
+"md","workflow-creation-guide","bmb","bmad/bmb/workflows/create-workflow/workflow-creation-guide.md","6e4bef8f19260f40714c3404bd402b2244933c821610506edb7a4f789cffdbbe"
 "yaml","bmad-builder.agent","bmb","bmad/bmb/agents/bmad-builder.agent.yaml",""
-"yaml","config","bmb","bmad/bmb/config.yaml","3baf3d7fee63f22959be86f2c310f3a4cc5afa748cd707e939ce3ee83745999f"
-"yaml","install-module-config","bmb","bmad/bmb/workflows/create-module/installer-templates/install-module-config.yaml","69c03628b04600f76aa1aa136094d59514f8eb900529114f7233dc28f2d5302d"
-"yaml","workflow","bmb","bmad/bmb/workflows/audit-workflow/workflow.yaml","5b8d26675e30d006f57631be2f42b00575b0d00f87abea408bf0afd09d73826e"
-"yaml","workflow","bmb","bmad/bmb/workflows/convert-legacy/workflow.yaml","c31cee9cc0d457b25954554d7620c7455b3f1b5aa5b5d72fbc765ea7902c3c0c"
-"yaml","workflow","bmb","bmad/bmb/workflows/create-agent/workflow.yaml","3d24d25cb58beed1198d465476615851f124d5a01bf4b358d07ff9f1451cd582"
-"yaml","workflow","bmb","bmad/bmb/workflows/create-module/workflow.yaml","f797507b0d3ec8292a670394e75e0dda682f338b3e266d0cd9af4bbb4eda8358"
+"yaml","config","bmb","bmad/bmb/config.yaml","9a9b8068ddf5492ad3a0c95dc32609eef016f1016ec68bf8768df8188458586a"
+"yaml","install-config","bmb","bmad/bmb/workflows/create-module/installer-templates/install-config.yaml","f20caf43009df9955b5fa0fa333851bf8b860568c05707d60ed295179c8abfde"
+"yaml","workflow","bmb","bmad/bmb/workflows/audit-workflow/workflow.yaml","24a82e15c41995c938c7f338254e5f414cfa8b9b679f3325e8d18435c992ab1c"
+"yaml","workflow","bmb","bmad/bmb/workflows/convert-legacy/workflow.yaml","17515280570a6a7cc6254b1753d6d7f4a012af5cb29b2f55d2ce59652fd3cff8"
+"yaml","workflow","bmb","bmad/bmb/workflows/create-agent/workflow.yaml","4b5c577c470c34d7e85a8881881e7e42a42758dc3fc12ece896752dfbd324eef"
+"yaml","workflow","bmb","bmad/bmb/workflows/create-module/workflow.yaml","da632eac14f6323bb6e4d6821dcc4d266db9ffd52bb43ba7cb2e60ec0c9ae4c6"
 "yaml","workflow","bmb","bmad/bmb/workflows/create-workflow/workflow-template/workflow.yaml","2eeb8d1724779956f8e89fda8fa850c3fb1d2b8c6eefecd1b5a4d5f9f58adb91"
-"yaml","workflow","bmb","bmad/bmb/workflows/create-workflow/workflow.yaml","0ef3f99857d135d062eca2138fe19fb75d3c4adcd5e0b291a86415dceda003ca"
-"yaml","workflow","bmb","bmad/bmb/workflows/edit-workflow/workflow.yaml","a8e451fdf95ae8a76feb454094b86c7c5c7a3050315eb3c7fe38b58e57514776"
-"yaml","workflow","bmb","bmad/bmb/workflows/module-brief/workflow.yaml","4fde4965106a30bb9c528dfc0f82fdefeccf6f65b25bbb169040258d81070b1f"
-"yaml","workflow","bmb","bmad/bmb/workflows/redoc/workflow.yaml","8906c8d50748bfcdfa9aa7d95ae284d02aea92b10ece262be1c793ee99358687"
+"yaml","workflow","bmb","bmad/bmb/workflows/create-workflow/workflow.yaml","79bce9abed20f239a6d0f97a3577c6b76c05b79696b38183569f1204b1140adb"
+"yaml","workflow","bmb","bmad/bmb/workflows/edit-agent/workflow.yaml","ab77c603f7bbdf8a8f38ce7e82f6cae40ad9ebcbdf0b590c18f5dece1e8685cd"
+"yaml","workflow","bmb","bmad/bmb/workflows/edit-module/workflow.yaml","ee4cd0a932381b67866bd049a8b2ed5b8fde57d48dd488f2317deb649f88cd53"
+"yaml","workflow","bmb","bmad/bmb/workflows/edit-workflow/workflow.yaml","9d8e33a8312a5e7cd10de014fb9251c7805be5fa23c7b4b813445b0daafc223c"
+"yaml","workflow","bmb","bmad/bmb/workflows/module-brief/workflow.yaml","5e96bb7f5bf32817513225b1572f7bd93dbc724b166aa3af977818a6ba7bcaf0"
+"yaml","workflow","bmb","bmad/bmb/workflows/redoc/workflow.yaml","0bef37556f6478ed886845c9811ecc97f41a240d3acd6c2e97ea1e2914f3abf7"
+"yaml","config","bmd","bmad/bmd/config.yaml","d6760db93cfffe4c383b922ce0832f7ebb630371e81a34dd6a006c5d7fc0fd46"
 "csv","adv-elicit-methods","core","bmad/core/tasks/adv-elicit-methods.csv","b4e925870f902862899f12934e617c3b4fe002d1b652c99922b30fa93482533b"
 "csv","brain-methods","core","bmad/core/workflows/brainstorming/brain-methods.csv","ecffe2f0ba263aac872b2d2c95a3f7b1556da2a980aa0edd3764ffb2f11889f3"
-"md","bmad-master","core","bmad/core/agents/bmad-master.md","d5a8f4c202e0637844b7c481c6b1284f4a8175017f070a23de849f53ead62625"
-"md","instructions","core","bmad/core/workflows/brainstorming/instructions.md","32961c158cf5c0575ff0aac6e6532ea177b824e96caddafa31223485df10bc4e"
-"md","instructions","core","bmad/core/workflows/party-mode/instructions.md","ea0e0e76de91d872efb3b4397627801452f21a39d094a77c41edc93f8dc4238b"
+"md","bmad-master","core","bmad/core/agents/bmad-master.md","da52edd5ab4fd9a189c3e27cc8d114eeefe0068ff85febdca455013b8c85da1a"
+"md","instructions","core","bmad/core/workflows/brainstorming/instructions.md","20c57ede11289def7927b6ef7bb69bd7a3deb9468dc08e93ee057f98a906e7f0"
+"md","instructions","core","bmad/core/workflows/party-mode/instructions.md","28e48c7a05e1f17ad64c0cc701a2ba60e385cd4704c726a14d4b886d885306ab"
 "md","README","core","bmad/core/workflows/brainstorming/README.md","ca469d9fbb2b9156491d160e11e2517fdf85ea2c29f41f92b22d4027fe7d9d2a"
 "md","template","core","bmad/core/workflows/brainstorming/template.md","b5c760f4cea2b56c75ef76d17a87177b988ac846657f4b9819ec125d125b7386"
 "xml","adv-elicit","core","bmad/core/tasks/adv-elicit.xml","94f004a336e434cd231de35eb864435ac51cd5888e9befe66e326eb16497121e"
 "xml","bmad-web-orchestrator.agent","core","bmad/core/agents/bmad-web-orchestrator.agent.xml","91a5c1b660befa7365f427640b4fa3dbb18f5e48cd135560303dae0939dccf12"
-"xml","index-docs","core","bmad/core/tasks/index-docs.xml","8d011ea850571d448932814bad7cbedcc8aa6e3e28868f55dcc7c2ba82158901"
-"xml","validate-workflow","core","bmad/core/tasks/validate-workflow.xml","1244874db38a55d957995ed224812ef868ff1451d8e1901cc5887dd0eb1c236e"
+"xml","index-docs","core","bmad/core/tasks/index-docs.xml","38226219c7dbde1c1dabcd87214383a6bfb2d0a7e79e09a9c79dd6be851b7e64"
+"xml","shard-doc","core","bmad/core/tools/shard-doc.xml","7de178b7269fbe8e65774622518db871f7d00cfac1bb5693cba8c1ca3ca8cdff"
+"xml","validate-workflow","core","bmad/core/tasks/validate-workflow.xml","1e8c569d8d53e618642aa1472721655cb917901a5888a7b403a98df4db2f26bf"
 "xml","workflow","core","bmad/core/tasks/workflow.xml","0b2b7bd184e099869174cc8d9125fce08bcd3fd64fad50ff835a42eccf6620e2"
 "yaml","bmad-master.agent","core","bmad/core/agents/bmad-master.agent.yaml",""
-"yaml","config","core","bmad/core/config.yaml","c5267c6e72f5d79344464082c2c73ddec88b7433705d38002993fe745c3cbe23"
-"yaml","workflow","core","bmad/core/workflows/brainstorming/workflow.yaml","52db57678606b98ec47e603c253c40f98815c49417df3088412bbbd8aa7f34d3"
-"yaml","workflow","core","bmad/core/workflows/party-mode/workflow.yaml","979e986780ce919abbdae89b3bd264d34a1436036a7eb6f82f40e59c9ce7c2e8"
+"yaml","config","core","bmad/core/config.yaml","e77c9a131b8139437c946a41febfc33fafac35016778a2e771845f9bece36e5e"
+"yaml","workflow","core","bmad/core/workflows/brainstorming/workflow.yaml","74038fa3892c4e873cc79ec806ecb2586fc5b4cf396c60ae964a6a71a9ad4a3d"
+"yaml","workflow","core","bmad/core/workflows/party-mode/workflow.yaml","e49aca36f6eb25dea0f253120bef8ee7637fe4b1c608198cb5ce74d6a109ae4f"
--- a/bmad/_cfg/manifest.yaml
+++ b/bmad/_cfg/manifest.yaml
@@ -1,10 +1,12 @@
 installation:
  version: 6.0.0-alpha.0
-  installDate: "2025-10-18T03:30:57.841Z"
-  lastUpdated: "2025-10-18T03:30:57.841Z"
+  installDate: "2025-10-28T17:08:48.104Z"
+  lastUpdated: "2025-10-28T17:08:48.104Z"
 modules:
  - core
  - bmb
+  - core
+  - bmd
 ides:
  - claude-code
  - codex
--- a/bmad/_cfg/task-manifest.csv
+++ b/bmad/_cfg/task-manifest.csv
@@ -1 +1,5 @@
-name,displayName,description,module,path
+name,displayName,description,module,path,standalone
+"adv-elicit","Advanced Elicitation","When called from workflow","core","bmad/core/tasks/adv-elicit.xml","false"
+"index-docs","Index Docs","Generates or updates an index.md of all documents in the specified directory","core","bmad/core/tasks/index-docs.xml","true"
+"validate-workflow","Validate Workflow Output","Run a checklist against a document with thorough analysis and produce a validation report","core","bmad/core/tasks/validate-workflow.xml","false"
+"workflow","Execute Workflow","Execute given workflow by loading its configuration, following instructions, and producing output","core","bmad/core/tasks/workflow.xml","false"
--- a/bmad/_cfg/tool-manifest.csv
+++ b/bmad/_cfg/tool-manifest.csv
@@ -0,0 +1,2 @@
+name,displayName,description,module,path,standalone
+"shard-doc","Shard Document","Splits large markdown documents into smaller, organized files based on level 2 (default) sections","core","bmad/core/tools/shard-doc.xml","true"
--- a/bmad/_cfg/workflow-manifest.csv
+++ b/bmad/_cfg/workflow-manifest.csv
@@ -1,11 +1,15 @@
-name,description,module,path
-"brainstorming","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.","core","bmad/core/workflows/brainstorming/workflow.yaml"
-"party-mode","Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations","core","bmad/core/workflows/party-mode/workflow.yaml"
-"audit-workflow","Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards.","bmb","bmad/bmb/workflows/audit-workflow/workflow.yaml"
-"convert-legacy","Converts legacy BMAD v4 or similar items (agents, workflows, modules) to BMad Core compliant format with proper structure and conventions","bmb","bmad/bmb/workflows/convert-legacy/workflow.yaml"
-"create-agent","Interactive workflow to build BMAD Core compliant agents (YAML source compiled to .md during install) with optional brainstorming, persona development, and command structure","bmb","bmad/bmb/workflows/create-agent/workflow.yaml"
-"create-module","Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure","bmb","bmad/bmb/workflows/create-module/workflow.yaml"
-"create-workflow","Interactive workflow builder that guides creation of new BMAD workflows with proper structure and validation for optimal human-AI collaboration. Includes optional brainstorming phase for workflow ideas and design.","bmb","bmad/bmb/workflows/create-workflow/workflow.yaml"
-"edit-workflow","Edit existing BMAD workflows while following all best practices and conventions","bmb","bmad/bmb/workflows/edit-workflow/workflow.yaml"
-"module-brief","Create a comprehensive Module Brief that serves as the blueprint for building new BMAD modules using strategic analysis and creative vision","bmb","bmad/bmb/workflows/module-brief/workflow.yaml"
-"redoc","Autonomous documentation system that maintains module, workflow, and agent documentation using a reverse-tree approach (leaf folders first, then parents). Understands BMAD conventions and produces technical writer quality output.","bmb","bmad/bmb/workflows/redoc/workflow.yaml"
+name,description,module,path,standalone
+"brainstorming","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.","core","bmad/core/workflows/brainstorming/workflow.yaml","true"
+"party-mode","Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations","core","bmad/core/workflows/party-mode/workflow.yaml","true"
+"audit-workflow","Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards.","bmb","bmad/bmb/workflows/audit-workflow/workflow.yaml","true"
+"convert-legacy","Converts legacy BMAD v4 or similar items (agents, workflows, modules) to BMad Core compliant format with proper structure and conventions","bmb","bmad/bmb/workflows/convert-legacy/workflow.yaml","true"
+"create-agent","Interactive workflow to build BMAD Core compliant agents (YAML source compiled to .md during install) with optional brainstorming, persona development, and command structure","bmb","bmad/bmb/workflows/create-agent/workflow.yaml","true"
+"create-module","Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure","bmb","bmad/bmb/workflows/create-module/workflow.yaml","true"
+"create-workflow","Interactive workflow builder that guides creation of new BMAD workflows with proper structure and validation for optimal human-AI collaboration. Includes optional brainstorming phase for workflow ideas and design.","bmb","bmad/bmb/workflows/create-workflow/workflow.yaml","true"
+"edit-agent","Edit existing BMAD agents while following all best practices and conventions","bmb","bmad/bmb/workflows/edit-agent/workflow.yaml","true"
+"edit-module","Edit existing BMAD modules (structure, agents, workflows, documentation) while following all best practices","bmb","bmad/bmb/workflows/edit-module/workflow.yaml","true"
+"edit-workflow","Edit existing BMAD workflows while following all best practices and conventions","bmb","bmad/bmb/workflows/edit-workflow/workflow.yaml","true"
+"module-brief","Create a comprehensive Module Brief that serves as the blueprint for building new BMAD modules using strategic analysis and creative vision","bmb","bmad/bmb/workflows/module-brief/workflow.yaml","true"
+"redoc","Autonomous documentation system that maintains module, workflow, and agent documentation using a reverse-tree approach (leaf folders first, then parents). Understands BMAD conventions and produces technical writer quality output.","bmb","bmad/bmb/workflows/redoc/workflow.yaml","true"
+"brainstorming","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.","core","bmad/core/workflows/brainstorming/workflow.yaml","false"
+"party-mode","Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations","core","bmad/core/workflows/party-mode/workflow.yaml","false"
--- a/bmad/bmb/agents/bmad-builder.md
+++ b/bmad/bmb/agents/bmad-builder.md
@@ -1,6 +1,9 @@
-<!-- Powered by BMAD-CORE™ -->
+---
+name: 'bmad builder'
+description: 'BMad Builder'
+---

-# BMad Builder
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

 ```xml
 <agent id="bmad/bmb/agents/bmad-builder.md" name="BMad Builder" title="BMad Builder" icon="🧙">
@@ -55,8 +58,10 @@
    <item cmd="*audit-workflow" workflow="{project-root}/bmad/bmb/workflows/audit-workflow/workflow.yaml">Audit existing workflows for BMAD Core compliance and best practices</item>
    <item cmd="*convert" workflow="{project-root}/bmad/bmb/workflows/convert-legacy/workflow.yaml">Convert v4 or any other style task agent or template to a workflow</item>
    <item cmd="*create-agent" workflow="{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml">Create a new BMAD Core compliant agent</item>
-    <item cmd="*create-module" workflow="{project-root}/bmad/bmb/workflows/create-module/workflow.yaml">Create a complete BMAD module (brainstorm → brief → build with agents and workflows)</item>
+    <item cmd="*create-module" workflow="{project-root}/bmad/bmb/workflows/create-module/workflow.yaml">Create a complete BMAD compatible module (custom agents and workflows)</item>
    <item cmd="*create-workflow" workflow="{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml">Create a new BMAD Core workflow with proper structure</item>
+    <item cmd="*edit-agent" workflow="{project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml">Edit existing agents while following best practices</item>
+    <item cmd="*edit-module" workflow="{project-root}/bmad/bmb/workflows/edit-module/workflow.yaml">Edit existing modules (structure, agents, workflows, documentation)</item>
    <item cmd="*edit-workflow" workflow="{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml">Edit existing workflows while following best practices</item>
    <item cmd="*redoc" workflow="{project-root}/bmad/bmb/workflows/redoc/workflow.yaml">Create or update module documentation</item>
    <item cmd="*exit">Exit with confirmation</item>
--- a/bmad/bmb/config.yaml
+++ b/bmad/bmb/config.yaml
@@ -1,7 +1,7 @@
 # BMB Module Configuration
 # Generated by BMAD installer
-# Version: 6.0.0-alpha.0
-# Date: 2025-10-18T03:30:57.837Z
+# Version: 6.0.0-beta.0
+# Date: 2025-10-28T17:08:48.100Z

 custom_agent_location: "{project-root}/bmad/agents"
 custom_workflow_location: "{project-root}/bmad/workflows"
@@ -10,4 +10,5 @@ custom_module_location: "{project-root}/bmad"
 # Core Configuration Values
 user_name: BMad
 communication_language: English
+document_output_language: English
 output_folder: "{project-root}/docs"
--- a/bmad/bmb/workflows/audit-workflow/checklist.md
+++ b/bmad/bmb/workflows/audit-workflow/checklist.md
@@ -76,6 +76,11 @@
 - [ ] Repeating steps have appropriate repeat attribute (repeat="3", repeat="for-each-X", repeat="until-approved")
 - [ ] Conditional steps have if="condition" attribute
 - [ ] XML tags used correctly (<action>, <ask>, <check>, <goto>, <invoke-workflow>, <template-output>)
+- [ ] No nested tag references in content (use "action tags" not "<action> tags")
+- [ ] Tag references use descriptive text without angle brackets for clarity
+- [ ] No conditional execution antipattern (no self-closing <check> tags)
+- [ ] Single conditionals use <action if="condition"> (inline)
+- [ ] Multiple conditionals use <check if="condition">...</check> (wrapper block with closing tag)
 - [ ] Steps are focused (single goal per step)
 - [ ] Instructions are specific with limits ("Write 1-2 paragraphs" not "Write about")
 - [ ] Examples provided where helpful
@@ -120,9 +125,9 @@ _List any cleanup recommendations:_

 ## Audit Summary

-**Total Checks:** 70
-**Passed:** **\_** / 70
-**Failed:** **\_** / 70
+**Total Checks:** 72
+**Passed:** **\_** / 72
+**Failed:** **\_** / 72
 **Pass Rate:** **\_**%

 **Recommendation:**
--- a/bmad/bmb/workflows/audit-workflow/instructions.md
+++ b/bmad/bmb/workflows/audit-workflow/instructions.md
@@ -5,371 +5,337 @@

 <workflow>

-<step n="1" goal="Load and analyze target workflow">
-<ask>What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder)</ask>
+  <step n="1" goal="Load and analyze target workflow">
+    <ask>What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder)</ask>

-<action>Load the workflow.yaml file from the provided path</action>
-<action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
-<action>List all associated files:</action>
+    <action>Load the workflow.yaml file from the provided path</action>
+    <action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
+    <action>List all associated files:</action>

- instructions.md (required for most workflows)
- template.md (if document workflow)
- checklist.md (if validation exists)
- Any data files referenced in yaml
+    - instructions.md (required for most workflows)
+    - template.md (if document workflow)
+    - checklist.md (if validation exists)
+    - Any data files referenced in yaml

-<action>Load all discovered files</action>
+    <action>Load all discovered files</action>

-Display summary:
+    Display summary:
+
+    - Workflow name and description
+    - Type of workflow
+    - Files present
+    - Module assignment

- Workflow name and description
- Type of workflow
- Files present
- Module assignment
  </step>

-<step n="2" goal="Validate standard config block">
-<action>Check workflow.yaml for the standard config block:</action>
+  <step n="2" goal="Validate standard config block">
+    <action>Check workflow.yaml for the standard config block:</action>

-**Required variables:**
+    **Required variables:**

- `config_source: "{project-root}/bmad/[module]/config.yaml"`
- `output_folder: "{config_source}:output_folder"`
- `user_name: "{config_source}:user_name"`
- `communication_language: "{config_source}:communication_language"`
- `date: system-generated`
+    - `config_source: "{project-root}/bmad/[module]/config.yaml"`
+    - `output_folder: "{config_source}:output_folder"`
+    - `user_name: "{config_source}:user_name"`
+    - `communication_language: "{config_source}:communication_language"`
+    - `date: system-generated`

-<action>Validate each variable:</action>
+    <action>Validate each variable:</action>

-**Config Source Check:**
+    **Config Source Check:**

- [ ] `config_source` is defined
- [ ] Points to correct module config path
- [ ] Uses {project-root} variable
+    - [ ] `config_source` is defined
+    - [ ] Points to correct module config path
+    - [ ] Uses {project-root} variable

-**Standard Variables Check:**
+    **Standard Variables Check:**

- [ ] `output_folder` pulls from config_source
- [ ] `user_name` pulls from config_source
- [ ] `communication_language` pulls from config_source
- [ ] `date` is set to system-generated
+    - [ ] `output_folder` pulls from config_source
+    - [ ] `user_name` pulls from config_source
+    - [ ] `communication_language` pulls from config_source
+    - [ ] `date` is set to system-generated

-<action>Record any missing or incorrect config variables</action>
-<template-output>config_issues</template-output>
+    <action>Record any missing or incorrect config variables</action>
+    <template-output>config_issues</template-output>

-<check>If config issues found:</check>
-<action>Add to issues list with severity: CRITICAL</action>
-</step>
+    <action if="config issues found">Add to issues list with severity: CRITICAL</action>

-<step n="3" goal="Analyze YAML/Instruction/Template alignment">
-<action>Extract all variables defined in workflow.yaml (excluding standard config block)</action>
-<action>Scan instructions.md for variable usage: {variable_name} pattern</action>
-<action>Scan template.md for variable usage: {{variable_name}} pattern (if exists)</action>
+  </step>

-<action>Cross-reference analysis:</action>
+  <step n="3" goal="Analyze YAML/Instruction/Template alignment">
+    <action>Extract all variables defined in workflow.yaml (excluding standard config block)</action>
+    <action>Scan instructions.md for variable usage: {variable_name} pattern</action>
+    <action>Scan template.md for variable usage: {{variable_name}} pattern (if exists)</action>

-**For each yaml variable:**
+    <action>Cross-reference analysis:</action>

-1. Is it used in instructions.md? (mark as INSTRUCTION_USED)
-2. Is it used in template.md? (mark as TEMPLATE_USED)
-3. Is it neither? (mark as UNUSED_BLOAT)
+    **For each yaml variable:**

-**Special cases to ignore:**
+    1. Is it used in instructions.md? (mark as INSTRUCTION_USED)
+    2. Is it used in template.md? (mark as TEMPLATE_USED)
+    3. Is it neither? (mark as UNUSED_BLOAT)

- Standard config variables (config_source, output_folder, user_name, communication_language, date)
- Workflow metadata (name, description, author)
- Path variables (installed_path, template, instructions, validation)
- Web bundle configuration (web_bundle block itself)
+    **Special cases to ignore:**

-<action>Identify unused yaml fields (bloat)</action>
-<action>Identify hardcoded values in instructions that should be variables</action>
-<template-output>alignment_issues</template-output>
+    - Standard config variables (config_source, output_folder, user_name, communication_language, date)
+    - Workflow metadata (name, description, author)
+    - Path variables (installed_path, template, instructions, validation)
+    - Web bundle configuration (web_bundle block itself)

-<check>If unused variables found:</check>
-<action>Add to issues list with severity: BLOAT</action>
-</step>
+    <action>Identify unused yaml fields (bloat)</action>
+    <action>Identify hardcoded values in instructions that should be variables</action>
+    <template-output>alignment_issues</template-output>

-<step n="4" goal="Config variable usage audit">
-<action>Analyze instructions.md for proper config variable usage:</action>
+    <action if="unused variables found">Add to issues list with severity: BLOAT</action>

-**Communication Language Check:**
+  </step>

- Search for phrases like "communicate in {communication_language}"
- Check if greetings/responses use language-aware patterns
- Verify NO usage of {{communication_language}} in template headers
+  <step n="4" goal="Config variable usage audit">
+    <action>Analyze instructions.md for proper config variable usage:</action>

-**User Name Check:**
+    **Communication Language Check:**

- Look for user addressing patterns using {user_name}
- Check if summaries or greetings personalize with {user_name}
- Verify optional usage in template metadata (not required)
+    - Search for phrases like "communicate in {communication_language}"
+    - Check if greetings/responses use language-aware patterns
+    - Verify NO usage of {{communication_language}} in template headers

-**Output Folder Check:**
+    **User Name Check:**

- Search for file write operations
- Verify all outputs go to {output_folder} or subdirectories
- Check for hardcoded paths like "/output/" or "/generated/"
+    - Look for user addressing patterns using {user_name}
+    - Check if summaries or greetings personalize with {user_name}
+    - Verify optional usage in template metadata (not required)

-**Date Usage Check:**
+    **Output Folder Check:**

- Verify date is available for agent date awareness
- Check optional usage in template metadata
- Ensure no confusion between date and model training cutoff
+    - Search for file write operations
+    - Verify all outputs go to {output_folder} or subdirectories
+    - Check for hardcoded paths like "/output/" or "/generated/"

-<action>Record any improper config variable usage</action>
-<template-output>config_usage_issues</template-output>
+    **Date Usage Check:**

-<check>If config usage issues found:</check>
-<action>Add to issues list with severity: IMPORTANT</action>
-</step>
+    - Verify date is available for agent date awareness
+    - Check optional usage in template metadata
+    - Ensure no confusion between date and model training cutoff

-<step n="5" goal="Web bundle validation" optional="true">
-<check>If workflow.yaml contains web_bundle section:</check>
+    **Nested Tag Reference Check:**

-<action>Validate web_bundle structure:</action>
+    - Search for XML tag references within tags (e.g., `<action>Scan for <action> tags</action>`)
+    - Identify patterns like: `<tag-name> tags`, `<tag-name> calls`, `<tag-name>content</tag-name>` within content
+    - Common problematic tags to check: action, ask, check, template-output, invoke-workflow, goto
+    - Flag any instances where angle brackets appear in content describing tags

-**Path Validation:**
+    **Best Practice:** Use descriptive text without brackets (e.g., "action tags" instead of "<action> tags")

- [ ] All paths use bmad/-relative format (NOT {project-root})
- [ ] No {config_source} variables in web_bundle section
- [ ] Paths match actual file locations
+    **Rationale:**

-**Completeness Check:**
+    - Prevents XML parsing ambiguity
+    - Improves readability for humans and LLMs
+    - LLMs understand "action tags" = `<action>` tags from context

- [ ] instructions file listed in web_bundle_files
- [ ] template file listed (if document workflow)
- [ ] validation/checklist file listed (if exists)
- [ ] All data files referenced in yaml listed
- [ ] All files referenced in instructions listed
+    **Conditional Execution Antipattern Check:**

-**Workflow Dependency Scan:**
-<action>Scan instructions.md for <invoke-workflow> tags</action>
-<action>Extract workflow paths from invocations</action>
-<action>Verify each called workflow.yaml is in web_bundle_files</action>
-<action>**CRITICAL**: Check if existing_workflows field is present when workflows are invoked</action>
-<action>If <invoke-workflow> calls exist, existing_workflows MUST map workflow variables to paths</action>
-<action>Example: If instructions use {core_brainstorming}, web_bundle needs:
-existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"
-</action>
+    - Scan for self-closing check tags: `<check>condition text</check>` (invalid antipattern)
+    - Detect pattern: check tag on one line, followed by action/ask/goto tags (indicates incorrect nesting)
+    - Flag sequences like: `<check>If X:</check>` followed by `<action>do Y</action>`

-**File Reference Scan:**
-<action>Scan instructions.md for file references in <action> tags</action>
-<action>Check for CSV, JSON, YAML, MD files referenced</action>
-<action>Verify all referenced files are in web_bundle_files</action>
+    **Correct Patterns:**

-<action>Record any missing files or incorrect paths</action>
-<template-output>web_bundle_issues</template-output>
+    - Single conditional: `<action if="condition">Do something</action>`
+    - Multiple actions: `<check if="condition">` followed by nested actions with closing `</check>` tag

-<check>If web_bundle issues found:</check>
-<action>Add to issues list with severity: CRITICAL</action>
+    **Antipattern Example (WRONG):**
+    ```xml
+    <check>If condition met:</check>
+    <action>Do something</action>
+    ```

-<check>If no web_bundle section exists:</check>
-<action>Note: "No web_bundle configured (may be intentional for local-only workflows)"</action>
-</step>
+    **Correct Example:**
+    ```xml
+    <check if="condition met">
+      <action>Do something</action>
+      <action>Do something else</action>
+    </check>
+    ```

-<step n="6" goal="Bloat detection">
-<action>Identify bloat patterns:</action>
+    **Or for single action:**
+    ```xml
+    <action if="condition met">Do something</action>
+    ```

-**Unused YAML Fields:**
+    <action>Scan instructions.md for nested tag references using pattern: &lt;(action|ask|check|template-output|invoke-workflow|goto|step|elicit-required)&gt; within text content</action>
+    <action>Record any instances of nested tag references with line numbers</action>
+    <action>Scan instructions.md for conditional execution antipattern: self-closing check tags</action>
+    <action>Detect pattern: `&lt;check&gt;.*&lt;/check&gt;` on single line (self-closing check)</action>
+    <action>Record any antipattern instances with line numbers and suggest corrections</action>
+    <action>Record any improper config variable usage</action>
+    <template-output>config_usage_issues</template-output>

- Variables defined but not used in instructions OR template
- Duplicate fields between top-level and web_bundle section
- Commented-out variables that should be removed
+    <action if="config usage issues found">Add to issues list with severity: IMPORTANT</action>
+    <action if="nested tag references found">Add to issues list with severity: CLARITY (recommend using descriptive text without angle brackets)</action>
+    <action if="conditional antipattern found">Add to issues list with severity: CRITICAL (invalid XML structure - must use action if="" or proper check wrapper)</action>

-**Hardcoded Values:**
+  </step>

- File paths that should use {output_folder}
- Generic greetings that should use {user_name}
- Language-specific text that should use {communication_language}
- Static dates that should use {date}
+  <step n="5" goal="Web bundle validation" optional="true">
+    <check if="workflow.yaml contains web_bundle section">

-**Redundant Configuration:**
+      <action>Validate web_bundle structure:</action>

- Variables that duplicate web_bundle fields
- Metadata repeated across sections
+      **Path Validation:**

-<action>Calculate bloat metrics:</action>
+      - [ ] All paths use bmad/-relative format (NOT {project-root})
+      - [ ] No {config_source} variables in web_bundle section
+      - [ ] Paths match actual file locations

- Total yaml fields: {{total_yaml_fields}}
- Used fields: {{used_fields}}
- Unused fields: {{unused_fields}}
- Bloat percentage: {{bloat_percentage}}%
+      **Completeness Check:**

-<action>Record all bloat items with recommendations</action>
-<template-output>bloat_items</template-output>
+      - [ ] instructions file listed in web_bundle_files
+      - [ ] template file listed (if document workflow)
+      - [ ] validation/checklist file listed (if exists)
+      - [ ] All data files referenced in yaml listed
+      - [ ] All files referenced in instructions listed

-<check>If bloat detected:</check>
-<action>Add to issues list with severity: CLEANUP</action>
-</step>
+      **Workflow Dependency Scan:**
+      <action>Scan instructions.md for invoke-workflow tags</action>
+      <action>Extract workflow paths from invocations</action>
+      <action>Verify each called workflow.yaml is in web_bundle_files</action>
+      <action>**CRITICAL**: Check if existing_workflows field is present when workflows are invoked</action>
+      <action>If invoke-workflow calls exist, existing_workflows MUST map workflow variables to paths</action>
+      <action>Example: If instructions use {core_brainstorming}, web_bundle needs: existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"</action>

-<step n="7" goal="Template variable mapping" if="workflow_type == 'document'">
-<action>Extract all template variables from template.md: {{variable_name}} pattern</action>
-<action>Scan instructions.md for corresponding <template-output>variable_name</template-output> tags</action>
+      **File Reference Scan:**
+      <action>Scan instructions.md for file references in action tags</action>
+      <action>Check for CSV, JSON, YAML, MD files referenced</action>
+      <action>Verify all referenced files are in web_bundle_files</action>

-<action>Cross-reference mapping:</action>
+      <action>Record any missing files or incorrect paths</action>
+      <template-output>web_bundle_issues</template-output>

-**For each template variable:**
+      <action if="web_bundle issues found">Add to issues list with severity: CRITICAL</action>

-1. Is there a matching <template-output> tag? (mark as MAPPED)
-2. Is it a standard config variable? (mark as CONFIG_VAR - optional)
-3. Is it unmapped? (mark as MISSING_OUTPUT)
+      <action if="no web_bundle section exists">Note: "No web_bundle configured (may be intentional for local-only workflows)"</action>
+    </check>

-**For each <template-output> tag:**
+  </step>

-1. Is there a matching template variable? (mark as USED)
-2. Is it orphaned? (mark as UNUSED_OUTPUT)
+  <step n="6" goal="Bloat detection">
+    <action>Identify bloat patterns:</action>

-<action>Verify variable naming conventions:</action>
+    **Unused YAML Fields:**

- [ ] All template variables use snake_case
- [ ] Variable names are descriptive (not abbreviated)
- [ ] Standard config variables properly formatted
+    - Variables defined but not used in instructions OR template
+    - Duplicate fields between top-level and web_bundle section
+    - Commented-out variables that should be removed

-<action>Record any mapping issues</action>
-<template-output>template_issues</template-output>
+    **Hardcoded Values:**

-<check>If template issues found:</check>
-<action>Add to issues list with severity: IMPORTANT</action>
-</step>
+    - File paths that should use {output_folder}
+    - Generic greetings that should use {user_name}
+    - Language-specific text that should use {communication_language}
+    - Static dates that should use {date}

-<step n="8" goal="Generate comprehensive audit report">
-<action>Compile all findings into a structured report</action>
+    **Redundant Configuration:**

-<action>Write audit report to {output_folder}/audit-report-{{workflow_name}}-{{date}}.md</action>
+    - Variables that duplicate web_bundle fields
+    - Metadata repeated across sections

-**Report Structure:**
+    <action>Calculate bloat metrics:</action>

-```markdown
-# Workflow Audit Report
+    - Total yaml fields: {{total_yaml_fields}}
+    - Used fields: {{used_fields}}
+    - Unused fields: {{unused_fields}}
+    - Bloat percentage: {{bloat_percentage}}%

-**Workflow:** {{workflow_name}}
-**Audit Date:** {{date}}
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** {{workflow_type}}
+    <action>Record all bloat items with recommendations</action>
+    <template-output>bloat_items</template-output>

---
+    <action if="bloat detected">Add to issues list with severity: CLEANUP</action>

-## Executive Summary
+  </step>

-**Overall Status:** {{overall_status}}
+  <step n="7" goal="Template variable mapping" if="workflow_type == 'document'">
+    <action>Extract all template variables from template.md: {{variable_name}} pattern</action>
+    <action>Scan instructions.md for corresponding template-output tags</action>

- Critical Issues: {{critical_count}}
- Important Issues: {{important_count}}
- Cleanup Recommendations: {{cleanup_count}}
+    <action>Cross-reference mapping:</action>

---
+    **For each template variable:**

-## 1. Standard Config Block Validation
+    1. Is there a matching template-output tag? (mark as MAPPED)
+    2. Is it a standard config variable? (mark as CONFIG_VAR - optional)
+    3. Is it unmapped? (mark as MISSING_OUTPUT)

-{{config_issues}}
+    **For each template-output tag:**

-**Status:** {{config_status}}
+    1. Is there a matching template variable? (mark as USED)
+    2. Is it orphaned? (mark as UNUSED_OUTPUT)

---
+    <action>Verify variable naming conventions:</action>

-## 2. YAML/Instruction/Template Alignment
+    - [ ] All template variables use snake_case
+    - [ ] Variable names are descriptive (not abbreviated)
+    - [ ] Standard config variables properly formatted

-{{alignment_issues}}
+    <action>Record any mapping issues</action>
+    <template-output>template_issues</template-output>

-**Variables Analyzed:** {{total_variables}}
-**Used in Instructions:** {{instruction_usage_count}}
-**Used in Template:** {{template_usage_count}}
-**Unused (Bloat):** {{bloat_count}}
+    <action if="template issues found">Add to issues list with severity: IMPORTANT</action>

---
+  </step>

-## 3. Config Variable Usage
+  <step n="8" goal="Generate comprehensive audit report">
+    <action>Compile all findings and calculate summary metrics</action>

-{{config_usage_issues}}
+    <action>Generate executive summary based on issue counts and severity levels</action>
+    <template-output>workflow_type</template-output>
+    <template-output>overall_status</template-output>
+    <template-output>critical_count</template-output>
+    <template-output>important_count</template-output>
+    <template-output>cleanup_count</template-output>

-**Communication Language:** {{comm_lang_status}}
-**User Name:** {{user_name_status}}
-**Output Folder:** {{output_folder_status}}
-**Date:** {{date_status}}
+    <action>Generate status summaries for each audit section</action>
+    <template-output>config_status</template-output>
+    <template-output>total_variables</template-output>
+    <template-output>instruction_usage_count</template-output>
+    <template-output>template_usage_count</template-output>
+    <template-output>bloat_count</template-output>

---
+    <action>Generate config variable usage status indicators</action>
+    <template-output>comm_lang_status</template-output>
+    <template-output>user_name_status</template-output>
+    <template-output>output_folder_status</template-output>
+    <template-output>date_status</template-output>
+    <template-output>nested_tag_count</template-output>

-## 4. Web Bundle Validation
+    <action>Generate web bundle metrics</action>
+    <template-output>web_bundle_exists</template-output>
+    <template-output>web_bundle_file_count</template-output>
+    <template-output>missing_files_count</template-output>

-{{web_bundle_issues}}
+    <action>Generate bloat metrics</action>
+    <template-output>bloat_percentage</template-output>
+    <template-output>cleanup_potential</template-output>

-**Web Bundle Present:** {{web_bundle_exists}}
-**Files Listed:** {{web_bundle_file_count}}
-**Missing Files:** {{missing_files_count}}
+    <action>Generate template mapping metrics</action>
+    <template-output>template_var_count</template-output>
+    <template-output>mapped_count</template-output>
+    <template-output>missing_mapping_count</template-output>

---
+    <action>Compile prioritized recommendations by severity</action>
+    <template-output>critical_recommendations</template-output>
+    <template-output>important_recommendations</template-output>
+    <template-output>cleanup_recommendations</template-output>

-## 5. Bloat Detection
+    <action>Display summary to {user_name} in {communication_language}</action>
+    <action>Provide path to full audit report: {output_folder}/audit-report-{{workflow_name}}-{{date}}.md</action>

-{{bloat_items}}
+    <ask>Would you like to:

-**Bloat Percentage:** {{bloat_percentage}}%
-**Cleanup Potential:** {{cleanup_potential}}
+    - View the full audit report
+    - Fix issues automatically (invoke edit-workflow)
+    - Audit another workflow
+    - Exit
+    </ask>

---
-
-## 6. Template Variable Mapping
-
-{{template_issues}}
-
-**Template Variables:** {{template_var_count}}
-**Mapped Correctly:** {{mapped_count}}
-**Missing Mappings:** {{missing_mapping_count}}
-
---
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-{{critical_recommendations}}
-
-### Important (Address Soon)
-
-{{important_recommendations}}
-
-### Cleanup (Nice to Have)
-
-{{cleanup_recommendations}}
-
---
-
-## Validation Checklist
-
-Use this checklist to verify fixes:
-
- [ ] All standard config variables present and correct
- [ ] No unused yaml fields (bloat removed)
- [ ] Config variables used appropriately in instructions
- [ ] Web bundle includes all dependencies
- [ ] Template variables properly mapped
- [ ] File structure follows v6 conventions
-
---
-
-## Next Steps
-
-1. Review critical issues and fix immediately
-2. Address important issues in next iteration
-3. Consider cleanup recommendations for optimization
-4. Re-run audit after fixes to verify improvements
-
---
-
-**Audit Complete** - Generated by audit-workflow v1.0
-```
-
-<action>Display summary to {user_name} in {communication_language}</action>
-<action>Provide path to full audit report</action>
-
-<ask>Would you like to:
-
- View the full audit report
- Fix issues automatically (invoke edit-workflow)
- Audit another workflow
- Exit
-  </ask>
-
-<template-output>audit_report_path</template-output>
-</step>
+  </step>

 </workflow>
--- a/bmad/bmb/workflows/audit-workflow/template.md
+++ b/bmad/bmb/workflows/audit-workflow/template.md
@@ -0,0 +1,118 @@
+# Workflow Audit Report
+
+**Workflow:** {{workflow_name}}
+**Audit Date:** {{date}}
+**Auditor:** Audit Workflow (BMAD v6)
+**Workflow Type:** {{workflow_type}}
+
+---
+
+## Executive Summary
+
+**Overall Status:** {{overall_status}}
+
+- Critical Issues: {{critical_count}}
+- Important Issues: {{important_count}}
+- Cleanup Recommendations: {{cleanup_count}}
+
+---
+
+## 1. Standard Config Block Validation
+
+{{config_issues}}
+
+**Status:** {{config_status}}
+
+---
+
+## 2. YAML/Instruction/Template Alignment
+
+{{alignment_issues}}
+
+**Variables Analyzed:** {{total_variables}}
+**Used in Instructions:** {{instruction_usage_count}}
+**Used in Template:** {{template_usage_count}}
+**Unused (Bloat):** {{bloat_count}}
+
+---
+
+## 3. Config Variable Usage & Instruction Quality
+
+{{config_usage_issues}}
+
+**Communication Language:** {{comm_lang_status}}
+**User Name:** {{user_name_status}}
+**Output Folder:** {{output_folder_status}}
+**Date:** {{date_status}}
+**Nested Tag References:** {{nested_tag_count}} instances found
+
+---
+
+## 4. Web Bundle Validation
+
+{{web_bundle_issues}}
+
+**Web Bundle Present:** {{web_bundle_exists}}
+**Files Listed:** {{web_bundle_file_count}}
+**Missing Files:** {{missing_files_count}}
+
+---
+
+## 5. Bloat Detection
+
+{{bloat_items}}
+
+**Bloat Percentage:** {{bloat_percentage}}%
+**Cleanup Potential:** {{cleanup_potential}}
+
+---
+
+## 6. Template Variable Mapping
+
+{{template_issues}}
+
+**Template Variables:** {{template_var_count}}
+**Mapped Correctly:** {{mapped_count}}
+**Missing Mappings:** {{missing_mapping_count}}
+
+---
+
+## Recommendations
+
+### Critical (Fix Immediately)
+
+{{critical_recommendations}}
+
+### Important (Address Soon)
+
+{{important_recommendations}}
+
+### Cleanup (Nice to Have)
+
+{{cleanup_recommendations}}
+
+---
+
+## Validation Checklist
+
+Use this checklist to verify fixes:
+
+- [ ] All standard config variables present and correct
+- [ ] No unused yaml fields (bloat removed)
+- [ ] Config variables used appropriately in instructions
+- [ ] Web bundle includes all dependencies
+- [ ] Template variables properly mapped
+- [ ] File structure follows v6 conventions
+
+---
+
+## Next Steps
+
+1. Review critical issues and fix immediately
+2. Address important issues in next iteration
+3. Consider cleanup recommendations for optimization
+4. Re-run audit after fixes to verify improvements
+
+---
+
+**Audit Complete** - Generated by audit-workflow v1.0
--- a/bmad/bmb/workflows/audit-workflow/workflow.yaml
+++ b/bmad/bmb/workflows/audit-workflow/workflow.yaml
@@ -12,10 +12,12 @@ date: system-generated

 # Module path and component files
 installed_path: "{project-root}/bmad/bmb/workflows/audit-workflow"
-template: false
+template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"

 # Output configuration
 default_output_file: "{output_folder}/audit-report-{{workflow_name}}-{{date}}.md"
+
+standalone: true
 # Web bundle configuration
--- a/bmad/bmb/workflows/audit-workflow/workflow.yaml.bak
+++ b/bmad/bmb/workflows/audit-workflow/workflow.yaml.bak
@@ -0,0 +1,21 @@
+# Audit Workflow Configuration
+name: "audit-workflow"
+description: "Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/bmad/bmb/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/audit-workflow"
+template: false
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration
+default_output_file: "{output_folder}/audit-report-{{workflow_name}}-{{date}}.md"
+# Web bundle configuration
--- a/bmad/bmb/workflows/convert-legacy/README.md
+++ b/bmad/bmb/workflows/convert-legacy/README.md
@@ -2,15 +2,15 @@

 ## Overview

-The Convert Legacy workflow is a comprehensive migration tool that converts BMAD v4 items (agents, workflows, modules) to v5 compliant format with proper structure and conventions. It bridges the gap between legacy BMAD implementations and the modern v5 architecture, ensuring seamless migration while preserving functionality and improving structure.
+The Convert Legacy workflow is a comprehensive migration tool that converts BMAD v4 items (agents, workflows, modules) to v6 compliant format with proper structure and conventions. It bridges the gap between legacy BMAD implementations and the modern v6 architecture, ensuring seamless migration while preserving functionality and improving structure.

 ## Key Features

 - **Multi-Format Detection** - Automatically identifies v4 agents, workflows, tasks, templates, and modules
- **Intelligent Conversion** - Smart mapping from v4 patterns to v5 equivalents with structural improvements
+- **Intelligent Conversion** - Smart mapping from v4 patterns to v6 equivalents with structural improvements
 - **Sub-Workflow Integration** - Leverages create-agent, create-workflow, and create-module workflows for quality output
 - **Structure Modernization** - Converts YAML-based agents to XML, templates to workflows, tasks to structured workflows
- **Path Normalization** - Updates all references to use proper v5 path conventions
+- **Path Normalization** - Updates all references to use proper v6 path conventions
 - **Validation System** - Comprehensive validation of converted items before finalization
 - **Migration Reporting** - Detailed conversion reports with locations and manual adjustment notes

@@ -42,7 +42,7 @@ The workflow uses standard BMB configuration:

 - **output_folder**: Where converted items will be placed
 - **user_name**: Author information for converted items
- **conversion_mappings**: v4-to-v5 pattern mappings (optional)
+- **conversion_mappings**: v4-to-v6 pattern mappings (optional)

 ## Workflow Structure

@@ -82,7 +82,7 @@ convert-legacy/
 **Target Module Selection**

 - Prompts for target module (bmm, bmb, cis, custom)
- Determines proper installation paths using v5 conventions
+- Determines proper installation paths using v6 conventions
 - Shows target location for user confirmation
 - Ensures all paths use `{project-root}/bmad/` format

@@ -98,7 +98,7 @@ convert-legacy/

 **Workflow Type Determination**

- Analyzes legacy items to determine v5 workflow type:
+- Analyzes legacy items to determine v6 workflow type:
  - **Document Workflow**: Generates documents with templates
  - **Action Workflow**: Performs actions without output documents
  - **Interactive Workflow**: Guides user interaction sessions
@@ -108,11 +108,11 @@ convert-legacy/

 **Direct Agent Conversion (5a)**

- Transforms v4 YAML agent format to v5 XML structure
+- Transforms v4 YAML agent format to v6 XML structure
 - Maps persona blocks (role, style, identity, principles)
- Converts commands list to v5 `<cmds>` format
+- Converts commands list to v6 `<cmds>` format
 - Updates task references to workflow invocations
- Normalizes all paths to v5 conventions
+- Normalizes all paths to v6 conventions

 **Workflow-Assisted Creation (5b-5e)**

@@ -121,7 +121,7 @@ convert-legacy/
  - `create-agent` for complex agent creation
  - `create-workflow` for template/task conversion
  - `create-module` for full module migration
- Ensures proper v5 structure and conventions
+- Ensures proper v6 structure and conventions

 **Template-to-Workflow Conversion (5c)**

@@ -136,7 +136,7 @@ convert-legacy/
 - Analyzes task purpose to determine workflow type
 - Extracts step-by-step instructions to workflow steps
 - Converts decision trees to flow control tags
- Maps 1-9 elicitation menus to v5 elicitation patterns
+- Maps 1-9 elicitation menus to v6 elicitation patterns
 - Preserves execution logic and critical notices

 ### Phase 4: Validation and Finalization (Steps 6-8)
@@ -165,13 +165,13 @@ convert-legacy/

 ### Generated Files

- **Converted Items**: Proper v5 format in target module locations
+- **Converted Items**: Proper v6 format in target module locations
 - **Migration Report**: Detailed conversion documentation
 - **Validation Results**: Quality assurance confirmation

 ### Output Structure

-Converted items follow v5 conventions:
+Converted items follow v6 conventions:

 1. **Agents** - XML format with proper persona and command structure
 2. **Workflows** - Complete workflow folders with yaml, instructions, and templates
@@ -183,7 +183,7 @@ Converted items follow v5 conventions:
 - **Legacy v4 Items** - Source files or directories to convert
 - **Target Module Access** - Write permissions to target module directories
 - **Sub-Workflow Availability** - create-agent, create-workflow, create-module workflows accessible
- **Conversion Mappings** (optional) - v4-to-v5 pattern mappings for complex conversions
+- **Conversion Mappings** (optional) - v4-to-v6 pattern mappings for complex conversions

 ## Best Practices

@@ -197,7 +197,7 @@ Converted items follow v5 conventions:

 1. **Validate Item Type Detection** - Confirm automatic detection or correct manually
 2. **Choose Appropriate Strategy** - Use workflow-assisted creation for complex items
-3. **Review Path Mappings** - Ensure all references use proper v5 path conventions
+3. **Review Path Mappings** - Ensure all references use proper v6 path conventions
 4. **Test Incrementally** - Convert simple items first to validate process

 ### After Completion
@@ -235,7 +235,7 @@ Converted items follow v5 conventions:

 To customize this workflow:

-1. **Update Conversion Mappings** - Modify v4-to-v5 pattern mappings in data/
+1. **Update Conversion Mappings** - Modify v4-to-v6 pattern mappings in data/
 2. **Extend Detection Logic** - Add new item type detection patterns
 3. **Add Conversion Strategies** - Implement specialized conversion approaches
 4. **Enhance Validation** - Add additional quality checks in validation step
@@ -253,10 +253,10 @@ To customize this workflow:
 For issues or questions:

 - Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
- Check conversion mappings at `/bmad/bmb/data/v4-to-v5-mappings.yaml`
+- Check conversion mappings at `/bmad/bmb/data/v4-to-v6-mappings.yaml`
 - Validate output using `checklist.md`
- Consult BMAD v5 documentation for proper conventions
+- Consult BMAD v6 documentation for proper conventions

 ---

-_Part of the BMad Method v5 - BMB (Builder) Module_
+_Part of the BMad Method v6 - BMB (Builder) Module_
--- a/bmad/bmb/workflows/convert-legacy/checklist.md
+++ b/bmad/bmb/workflows/convert-legacy/checklist.md
@@ -16,12 +16,12 @@
 #### Content Preservation

 - [ ] Agent name, id, title, and icon transferred
- [ ] All persona elements mapped to v5 structure
- [ ] All commands converted to v5 menu array (YAML)
+- [ ] All persona elements mapped to v6 structure
+- [ ] All commands converted to v6 menu array (YAML)
 - [ ] Dependencies properly referenced or converted
- [ ] Activation instructions adapted to v5 patterns
+- [ ] Activation instructions adapted to v6 patterns

-#### v5 Compliance (YAML Format)
+#### v6 Compliance (YAML Format)

 - [ ] Valid YAML structure with proper indentation
 - [ ] agent.metadata has all required fields (id, name, title, icon, module)
@@ -52,14 +52,14 @@
 - [ ] Conditional sections preserved with if="" attributes
 - [ ] Repeatable sections converted to repeat="" attributes

-#### v5 Compliance
+#### v6 Compliance

 - [ ] workflow.yaml follows structure from workflow-creation-guide.md
 - [ ] instructions.md has critical headers referencing workflow engine
 - [ ] Steps numbered sequentially with clear goals
 - [ ] Template variables match between instructions and template.md
 - [ ] Proper use of XML tags (<action>, <check>, <ask>, <template-output>)
- [ ] File structure follows v5 pattern (folder with yaml/md files)
+- [ ] File structure follows v6 pattern (folder with yaml/md files)

 #### Best Practices

@@ -88,21 +88,21 @@
 - [ ] If performs actions only, marked as action workflow
 - [ ] Output patterns properly analyzed

-#### v5 Compliance
+#### v6 Compliance

 - [ ] Converted to proper workflow format (not standalone task)
 - [ ] Follows workflow execution engine patterns
- [ ] Interactive elements use proper v5 tags
- [ ] Flow control uses v5 patterns (goto, check, loop)
- [ ] 1-9 elicitation menus converted to v5 elicitation
+- [ ] Interactive elements use proper v6 tags
+- [ ] Flow control uses v6 patterns (goto, check, loop)
+- [ ] 1-9 elicitation menus converted to v6 elicitation
 - [ ] Critical notices preserved in workflow.yaml
- [ ] YOLO mode converted to appropriate v5 patterns
+- [ ] YOLO mode converted to appropriate v6 patterns

 ### Module-Level Validation

 #### Structure

- [ ] Module follows v5 directory structure
+- [ ] Module follows v6 directory structure
 - [ ] All components in correct locations:
  - Agents in /agents/
  - Workflows in /workflows/
@@ -170,7 +170,7 @@

 ### Quality Assurance

- [ ] Converted item follows ALL v5 best practices
+- [ ] Converted item follows ALL v6 best practices
 - [ ] Code/config is clean and maintainable
 - [ ] No TODO or FIXME items remain
 - [ ] Ready for production use
--- a/bmad/bmb/workflows/convert-legacy/instructions.md
+++ b/bmad/bmb/workflows/convert-legacy/instructions.md
@@ -1,4 +1,4 @@
-# Convert Legacy - v4 to v5 Conversion Instructions
+# Convert Legacy - v4 to v6 Conversion Instructions

 <critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <parameter name="You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/convert-legacy/workflow.yaml</critical>
@@ -56,19 +56,18 @@ For Modules:
 - Installation requirements

 <action>Create a conversion map of what needs to be transformed</action>
-<action>Map v4 patterns to v5 equivalents:
+<action>Map v4 patterns to v6 equivalents:

- v4 Task + Template → v5 Workflow (folder with workflow.yaml, instructions.md, template.md)
- v4 Agent YAML → v5 Agent YAML format
- v4 Commands → v5 <menu> with proper handlers
- v4 Dependencies → v5 workflow references or data files
+- v4 Task + Template → v6 Workflow (folder with workflow.yaml, instructions.md, template.md)
+- v4 Agent YAML → v6 Agent YAML format
+- v4 Commands → v6 <menu> with proper handlers
+- v4 Dependencies → v6 workflow references or data files
  </action>
  </step>

 <step n="3" goal="Determine Target Module and Location">
 <ask>Which module should this belong to? (eg. bmm, bmb, cis, bmm-legacy, or custom)</ask>
-<check>If custom module:</check>
-  <ask>Enter custom module code (kebab-case):</ask>
+<action if="custom module"><ask>Enter custom module code (kebab-case):</ask></action>
 <action>Determine installation path based on type and module</action>
 <critical>IMPORTANT: All paths must use final BMAD installation locations, not src paths!</critical>
 <action>Show user the target location: {project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}</action>
@@ -79,16 +78,19 @@ For Modules:
 <step n="4" goal="Choose Conversion Strategy">
 <action>Based on item type and complexity, choose approach:</action>

-<check>If agent conversion:</check>
-<check>If simple agent (basic persona + commands):</check>
-<action>Use direct conversion to v5 agent YAML format</action>
-<goto step="5a">Direct Agent Conversion</goto>
-<check>If complex agent with embedded workflows:</check>
-<action>Plan to invoke create-agent workflow</action>
-<goto step="5b">Workflow-Assisted Agent Creation</goto>
+<check if="agent conversion">
+  <check if="simple agent (basic persona + commands)">
+    <action>Use direct conversion to v6 agent YAML format</action>
+    <goto step="5a">Direct Agent Conversion</goto>
+  </check>
+  <check if="complex agent with embedded workflows">
+    <action>Plan to invoke create-agent workflow</action>
+    <goto step="5b">Workflow-Assisted Agent Creation</goto>
+  </check>
+</check>

-<check>If template or task conversion to workflow:</check>
-<action>Analyze the v4 item to determine workflow type:</action>
+<check if="template or task conversion to workflow">
+  <action>Analyze the v4 item to determine workflow type:</action>

 - Does it generate a specific document type? → Document workflow
 - Does it produce structured output files? → Document workflow
@@ -104,34 +106,34 @@ For Modules:
 4. Meta-workflow (coordinates other workflows)
   Select 1-4:</ask>

-<check>If template conversion:</check>
-<goto step="5c">Template-to-Workflow Conversion</goto>
-<check>If task conversion:</check>
-<goto step="5e">Task-to-Workflow Conversion</goto>
+<action if="template conversion"><goto step="5c">Template-to-Workflow Conversion</goto></action>
+<action if="task conversion"><goto step="5e">Task-to-Workflow Conversion</goto></action>
+</check>

-<check>If full module conversion:</check>
-<action>Plan to invoke create-module workflow</action>
-<goto step="5d">Module Creation</goto>
+<check if="full module conversion">
+  <action>Plan to invoke create-module workflow</action>
+  <goto step="5d">Module Creation</goto>
+</check>
 </step>

 <step n="5a" goal="Direct Agent Conversion" optional="true">
-<action>Transform v4 YAML agent to v5 YAML format:</action>
+<action>Transform v4 YAML agent to v6 YAML format:</action>

 1. Convert agent metadata structure:
-   - v4 `agent.name` → v5 `agent.metadata.name`
-   - v4 `agent.id` → v5 `agent.metadata.id`
-   - v4 `agent.title` → v5 `agent.metadata.title`
-   - v4 `agent.icon` → v5 `agent.metadata.icon`
-   - Add v5 `agent.metadata.module` field
+   - v4 `agent.name` → v6 `agent.metadata.name`
+   - v4 `agent.id` → v6 `agent.metadata.id`
+   - v4 `agent.title` → v6 `agent.metadata.title`
+   - v4 `agent.icon` → v6 `agent.metadata.icon`
+   - Add v6 `agent.metadata.module` field

 2. Transform persona structure:
-   - v4 `persona.role` → v5 `agent.persona.role` (keep as YAML string)
-   - v4 `persona.style` → v5 `agent.persona.communication_style`
-   - v4 `persona.identity` → v5 `agent.persona.identity`
-   - v4 `persona.core_principles` → v5 `agent.persona.principles` (as array)
+   - v4 `persona.role` → v6 `agent.persona.role` (keep as YAML string)
+   - v4 `persona.style` → v6 `agent.persona.communication_style`
+   - v4 `persona.identity` → v6 `agent.persona.identity`
+   - v4 `persona.core_principles` → v6 `agent.persona.principles` (as array)

 3. Convert commands to menu:
-   - v4 `commands:` list → v5 `agent.menu:` array
+   - v4 `commands:` list → v6 `agent.menu:` array
   - Each command becomes menu item with:
     - `trigger:` (without \* prefix - added at build)
     - `description:`
@@ -139,18 +141,18 @@ For Modules:
   - Map task references to workflow paths
   - Map template references to workflow invocations

-4. Add v5-specific sections (in YAML):
+4. Add v6-specific sections (in YAML):
   - `agent.prompts:` array for inline prompts (if using action: "#id")
   - `agent.critical_actions:` array for startup requirements
   - `agent.activation_rules:` for universal agent rules

 5. Handle dependencies and paths:
   - Convert task dependencies to workflow references
-   - Map template dependencies to v5 workflows
+   - Map template dependencies to v6 workflows
   - Preserve checklist and data file references
   - CRITICAL: All paths must use {project-root}/bmad/{{module}}/ NOT src/

-<action>Generate the converted v5 agent YAML file (.agent.yaml)</action>
+<action>Generate the converted v6 agent YAML file (.agent.yaml)</action>
 <action>Example path conversions:

 - exec="{project-root}/bmad/{{target_module}}/tasks/task-name.md"
@@ -182,7 +184,7 @@ For Modules:
 </step>

 <step n="5c" goal="Template-to-Workflow Conversion" optional="true">
-<action>Convert v4 Template (YAML) to v5 Workflow:</action>
+<action>Convert v4 Template (YAML) to v6 Workflow:</action>

 1. Extract template metadata:
   - Template id, name, version → workflow.yaml name/description
@@ -202,7 +204,7 @@ For Modules:
   - Nested sections → hierarchical markdown

 4. Handle v4 create-doc.md task integration:
-   - Elicitation methods (1-9 menu) → convert to v5 elicitation
+   - Elicitation methods (1-9 menu) → convert to v6 elicitation
   - Agent permissions → note in instructions
   - Processing flow → integrate into workflow steps

@@ -247,7 +249,7 @@ date: system-generated
 </step>

 <step n="5e" goal="Task-to-Workflow Conversion" optional="true">
-<action>Convert v4 Task (Markdown) to v5 Workflow:</action>
+<action>Convert v4 Task (Markdown) to v6 Workflow:</action>

 1. Analyze task purpose and output:
   - Does it generate documents? → Create template.md
@@ -259,21 +261,23 @@ date: system-generated
   - Execution notices and critical rules → workflow.yaml metadata
   - Step-by-step instructions → instructions.md steps
   - Decision trees and branching → flow control tags
-   - User interaction patterns → appropriate v5 tags
+   - User interaction patterns → appropriate v6 tags

 3. Based on confirmed workflow type:
-   <check>If Document workflow:</check>
+   <check if="Document workflow">
   - Create template.md from output patterns
   - Map generation steps to instructions
-   - Add <template-output> tags for sections
+   - Add template-output tags for sections
+     </check>

-   <check>If Action workflow:</check>
-   - Set template: false in workflow.yaml
-   - Focus on action sequences in instructions
-   - Preserve execution logic
+   <check if="Action workflow">
+     - Set template: false in workflow.yaml
+     - Focus on action sequences in instructions
+     - Preserve execution logic
+   </check>

 4. Handle special v4 patterns:
-   - 1-9 elicitation menus → v5 <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
+   - 1-9 elicitation menus → v6 <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
   - Agent permissions → note in instructions
   - YOLO mode → autonomous flag or optional steps
   - Critical notices → workflow.yaml comments
@@ -317,7 +321,7 @@ For Agents:
 For Workflows:

 - [ ] Valid YAML syntax
- [ ] Instructions follow v5 conventions
+- [ ] Instructions follow v6 conventions
 - [ ] Template variables match
 - [ ] File structure correct

@@ -341,15 +345,16 @@ For Modules:

 <action>Show validation results to user</action>
 <ask>Any issues to fix before finalizing? (y/n)</ask>
-<check>If yes:</check>
+<check if="yes">
 <action>Address specific issues</action>
 <goto step="6">Re-validate</goto>
+</check>
 </step>

 <step n="7" goal="Migration Report">
 <action>Generate conversion report showing:</action>
 - Original v4 location
- New v5 location
+- New v6 location
 - Items converted
 - Any manual adjustments needed
 - Warnings or notes
@@ -360,15 +365,13 @@ For Modules:

 <step n="8" goal="Cleanup and Finalize">
 <ask>Archive original v4 files? (y/n)</ask>
-<check>If yes:</check>
-  <action>Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>
+<action if="yes">Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>

 <action>Show user the final converted items and their locations</action>
 <action>Provide any post-conversion instructions or recommendations</action>

 <ask>Would you like to convert another legacy item? (y/n)</ask>
-<check>If yes:</check>
-<goto step="1">Start new conversion</goto>
+<action if="yes"><goto step="1">Start new conversion</goto></action>
 </step>

 </workflow>
--- a/bmad/bmb/workflows/convert-legacy/workflow.yaml
+++ b/bmad/bmb/workflows/convert-legacy/workflow.yaml
@@ -1,4 +1,4 @@
-# Convert Legacy - BMAD v4 to v5 Converter Configuration
+# Convert Legacy - BMAD v4 to v6 Converter Configuration
 name: "convert-legacy"
 description: "Converts legacy BMAD v4 or similar items (agents, workflows, modules) to BMad Core compliant format with proper structure and conventions"
 author: "BMad"
@@ -28,3 +28,5 @@ sub_workflows:
  - create_agent: "{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml"
  - create_workflow: "{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml"
  - create_module: "{project-root}/bmad/bmb/workflows/create-module/workflow.yaml"
+
+standalone: true
--- a/bmad/bmb/workflows/create-agent/agent-architecture.md
+++ b/bmad/bmb/workflows/create-agent/agent-architecture.md
@@ -230,7 +230,7 @@ Bad:  ../../../relative/paths/
 ```xml
 <item cmd="*standup"
   exec="{project-root}/bmad/bmm/tasks/daily-standup.xml"
-   data="{project-root}/bmad/_cfg/agent-party.xml">
+   data="{project-root}/bmad/_cfg/agent-manifest.csv">
  Run daily standup
 </item>
 ```
@@ -361,6 +361,13 @@ When building agents:
 - Workflows can be incomplete (marked "todo")
 - Workflow paths must be valid or "todo"

+**Workflow Interaction Styles** (BMAD v6 default):
+
+- **Intent-based + Interactive**: Workflows adapt to user context and skill level
+- Workflows collaborate with users, not just extract data
+- See workflow-creation-guide.md "Instruction Styles" section for details
+- When creating workflows for your agent, default to intent-based unless you need prescriptive control
+
 ### With Tasks

 - Tasks are single operations
--- a/bmad/bmb/workflows/create-agent/agent-architecture.md.bak
+++ b/bmad/bmb/workflows/create-agent/agent-architecture.md.bak
@@ -0,0 +1,412 @@
+# BMAD Agent Architecture Reference
+
+_LLM-Optimized Technical Documentation for Agent Building_
+
+## Core Agent Structure
+
+### Minimal Valid Agent
+
+```xml
+<!-- Powered by BMAD-CORE™ -->
+
+# Agent Name
+
+<agent id="path/to/agent.md" name="Name" title="Title" icon="🤖">
+  <persona>
+    <role>My primary function</role>
+    <identity>My background and expertise</identity>
+    <communication_style>How I interact</communication_style>
+    <principles>My core beliefs and methodology</principles>
+  </persona>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
+
+## Agent XML Schema
+
+### Root Element: `<agent>`
+
+**Required Attributes:**
+
+- `id` - Unique path identifier (e.g., "bmad/bmm/agents/analyst.md")
+- `name` - Agent's name (e.g., "Mary", "John", "Helper")
+- `title` - Professional title (e.g., "Business Analyst", "Security Engineer")
+- `icon` - Single emoji representing the agent
+
+### Core Sections
+
+#### 1. Persona Section (REQUIRED)
+
+```xml
+<persona>
+  <role>1-2 sentences: Professional title and primary expertise, use first-person voice</role>
+  <identity>2-5 sentences: Background, experience, specializations, use first-person voice</identity>
+  <communication_style>1-3 sentences: Interaction approach, tone, quirks, use first-person voice</communication_style>
+  <principles>2-5 sentences: Core beliefs, methodology, philosophy, use first-person voice</principles>
+</persona>
+```
+
+**Best Practices:**
+
+- Role: Be specific about expertise area
+- Identity: Include experience indicators (years, depth)
+- Communication: Describe HOW they interact, not just tone and quirks
+- Principles: Start with "I believe" or "I operate" for first-person voice
+
+#### 2. Critical Actions Section
+
+```xml
+<critical-actions>
+  <i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
+  <i>Remember the users name is {user_name}</i>
+  <i>ALWAYS communicate in {communication_language}</i>
+  <!-- Custom initialization actions -->
+</critical-actions>
+```
+
+**For Expert Agents with Sidecars (CRITICAL):**
+
+```xml
+<critical-actions>
+  <!-- CRITICAL: Load sidecar files FIRST -->
+  <i critical="MANDATORY">Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives</i>
+  <i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
+  <i critical="MANDATORY">You MUST follow all rules in instructions.md on EVERY interaction</i>
+
+  <!-- Standard initialization -->
+  <i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
+  <i>Remember the users name is {user_name}</i>
+  <i>ALWAYS communicate in {communication_language}</i>
+
+  <!-- Domain restrictions -->
+  <i>ONLY read/write files in {user-folder}/diary/ - NO OTHER FOLDERS</i>
+</critical-actions>
+```
+
+**Common Patterns:**
+
+- Config loading for module agents
+- User context initialization
+- Language preferences
+- **Sidecar file loading (Expert agents) - MUST be explicit and CRITICAL**
+- **Domain restrictions (Expert agents) - MUST be enforced**
+
+#### 3. Menu Section (REQUIRED)
+
+```xml
+<menu>
+  <item cmd="*trigger" [attributes]>Description</item>
+</menu>
+```
+
+**Command Attributes:**
+
+- `run-workflow="{path}"` - Executes a workflow
+- `exec="{path}"` - Executes a task
+- `tmpl="{path}"` - Template reference
+- `data="{path}"` - Data file reference
+
+**Required Menu Items:**
+
+- `*help` - Always first, shows command list
+- `*exit` - Always last, exits agent
+
+## Advanced Agent Patterns
+
+### Activation Rules (OPTIONAL)
+
+```xml
+<activation critical="true">
+  <initialization critical="true" sequential="MANDATORY">
+    <step n="1">Load configuration</step>
+    <step n="2">Apply overrides</step>
+    <step n="3">Execute critical actions</step>
+    <step n="4" critical="BLOCKING">Show greeting with menu</step>
+    <step n="5" critical="BLOCKING">AWAIT user input</step>
+  </initialization>
+  <command-resolution critical="true">
+    <rule>Numeric input → Execute command at cmd_map[n]</rule>
+    <rule>Text input → Fuzzy match against commands</rule>
+  </command-resolution>
+</activation>
+```
+
+### Expert Agent Sidecar Pattern
+
+```xml
+<!-- DO NOT use sidecar-resources tag - Instead use critical-actions -->
+<!-- Sidecar files MUST be loaded explicitly in critical-actions -->
+
+<!-- Example Expert Agent with Diary domain -->
+<agent id="diary-keeper" name="Personal Assistant" title="Diary Keeper" icon="📔">
+  <critical-actions>
+    <!-- MANDATORY: Load all sidecar files -->
+    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/diary-rules.md</i>
+    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/user-memories.md</i>
+    <i critical="MANDATORY">Follow ALL rules from diary-rules.md</i>
+
+    <!-- Domain restriction -->
+    <i critical="MANDATORY">ONLY access files in {user-folder}/diary/</i>
+    <i critical="MANDATORY">NEVER access files outside diary folder</i>
+  </critical-actions>
+
+  <persona>...</persona>
+  <menu>...</menu>
+</agent>
+```
+
+### Module Agent Integration
+
+```xml
+<module-integration>
+  <module-path>{project-root}/bmad/{module-code}</module-path>
+  <config-source>{module-path}/config.yaml</config-source>
+  <workflows-path>{project-root}/bmad/{module-code}/workflows</workflows-path>
+</module-integration>
+```
+
+## Variable System
+
+### System Variables
+
+- `{project-root}` - Root directory of project
+- `{user_name}` - User's name from config
+- `{communication_language}` - Language preference
+- `{date}` - Current date
+- `{module}` - Current module code
+
+### Config Variables
+
+Format: `{config_source}:variable_name`
+Example: `{config_source}:output_folder`
+
+### Path Construction
+
+```
+Good: {project-root}/bmad/{module}/agents/
+Bad:  /absolute/path/to/agents/
+Bad:  ../../../relative/paths/
+```
+
+## Command Patterns
+
+### Workflow Commands
+
+```xml
+<!-- Full path -->
+<item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
+  Create Product Requirements Document
+</item>
+
+<!-- Placeholder for future -->
+<item cmd="*analyze" run-workflow="todo">
+  Perform analysis (workflow to be created)
+</item>
+```
+
+### Task Commands
+
+```xml
+<item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
+  Validate document
+</item>
+```
+
+### Template Commands
+
+```xml
+<item cmd="*brief"
+   exec="{project-root}/bmad/core/tasks/create-doc.md"
+   tmpl="{project-root}/bmad/bmm/templates/brief.md">
+  Create project brief
+</item>
+```
+
+### Data-Driven Commands
+
+```xml
+<item cmd="*standup"
+   exec="{project-root}/bmad/bmm/tasks/daily-standup.xml"
+   data="{project-root}/bmad/_cfg/agent-manifest.csv">
+  Run daily standup
+</item>
+```
+
+## Agent Type Specific Patterns
+
+### Simple Agent
+
+- Self-contained logic
+- Minimal or no external dependencies
+- May have embedded functions
+- Good for utilities and converters
+
+### Expert Agent
+
+- Domain-specific with sidecar resources
+- Restricted access patterns
+- Memory/context files
+- Good for specialized domains
+
+### Module Agent
+
+- Full integration with module
+- Multiple workflows and tasks
+- Config-driven behavior
+- Good for professional tools
+
+## Common Anti-Patterns to Avoid
+
+### ❌ Bad Practices
+
+```xml
+<!-- Missing required persona elements -->
+<persona>
+  <role>Helper</role>
+  <!-- Missing identity, style, principles -->
+</persona>
+
+<!-- Hard-coded paths -->
+<item cmd="*run" exec="/Users/john/project/task.md">
+
+<!-- No help command -->
+<menu>
+  <item cmd="*do-something">Action</item>
+  <!-- Missing *help -->
+</menu>
+
+<!-- Duplicate command triggers -->
+<item cmd="*analyze">First</item>
+<item cmd="*analyze">Second</item>
+```
+
+### ✅ Good Practices
+
+```xml
+<!-- Complete persona -->
+<persona>
+  <role>Data Analysis Expert</role>
+  <identity>Senior analyst with 10+ years...</identity>
+  <communication_style>Analytical and precise...</communication_style>
+  <principles>I believe in data-driven...</principles>
+</persona>
+
+<!-- Variable-based paths -->
+<item cmd="*run" exec="{project-root}/bmad/module/task.md">
+
+<!-- Required commands present -->
+<menu>
+  <item cmd="*help">Show commands</item>
+  <item cmd="*analyze">Perform analysis</item>
+  <item cmd="*exit">Exit</item>
+</menu>
+```
+
+## Agent Lifecycle
+
+### 1. Initialization
+
+1. Load agent file
+2. Parse XML structure
+3. Load critical-actions
+4. Apply config overrides
+5. Present greeting
+
+### 2. Command Loop
+
+1. Show numbered menu
+2. Await user input
+3. Resolve command
+4. Execute action
+5. Return to menu
+
+### 3. Termination
+
+1. User enters \*exit
+2. Cleanup if needed
+3. Exit persona
+
+## Testing Checklist
+
+Before deploying an agent:
+
+- [ ] Valid XML structure
+- [ ] All persona elements present
+- [ ] *help and *exit commands exist
+- [ ] All paths use variables
+- [ ] No duplicate commands
+- [ ] Config loading works
+- [ ] Commands execute properly
+
+## LLM Building Tips
+
+When building agents:
+
+1. Start with agent type (Simple/Expert/Module)
+2. Define complete persona first
+3. Add standard critical-actions
+4. Include *help and *exit
+5. Add domain commands
+6. Test command execution
+7. Validate with checklist
+
+## Integration Points
+
+### With Workflows
+
+- Agents invoke workflows via run-workflow
+- Workflows can be incomplete (marked "todo")
+- Workflow paths must be valid or "todo"
+
+### With Tasks
+
+- Tasks are single operations
+- Executed via exec attribute
+- Can include data files
+
+### With Templates
+
+- Templates define document structure
+- Used with create-doc task
+- Variables passed through
+
+## Quick Reference
+
+### Minimal Commands
+
+```xml
+<menu>
+  <item cmd="*help">Show numbered cmd list</item>
+  <item cmd="*exit">Exit with confirmation</item>
+</menu>
+```
+
+### Standard Critical Actions
+
+```xml
+<critical-actions>
+  <i>Load into memory {project-root}/bmad/{module}/config.yaml</i>
+  <i>Remember the users name is {user_name}</i>
+  <i>ALWAYS communicate in {communication_language}</i>
+</critical-actions>
+```
+
+### Module Agent Pattern
+
+```xml
+<agent id="bmad/{module}/agents/{name}.md"
+       name="{Name}"
+       title="{Title}"
+       icon="{emoji}">
+  <persona>...</persona>
+  <critical-actions>...</critical-actions>
+  <menu>
+    <item cmd="*help">...</item>
+    <item cmd="*{command}" run-workflow="{path}">...</item>
+    <item cmd="*exit">...</item>
+  </menu>
+</agent>
+```
--- a/bmad/bmb/workflows/create-agent/agent-command-patterns.md
+++ b/bmad/bmb/workflows/create-agent/agent-command-patterns.md
@@ -119,7 +119,7 @@ Execute single operations
 <!-- Task with data -->
 <item cmd="*standup"
   exec="{project-root}/bmad/mmm/tasks/daily-standup.xml"
-   data="{project-root}/bmad/_cfg/agent-party.xml">
+   data="{project-root}/bmad/_cfg/agent-manifest.csv">
  Run agile team standup
 </item>
 ```
--- a/bmad/bmb/workflows/create-agent/agent-command-patterns.md.bak
+++ b/bmad/bmb/workflows/create-agent/agent-command-patterns.md.bak
@@ -0,0 +1,759 @@
+# BMAD Agent Command Patterns Reference
+
+_LLM-Optimized Guide for Command Design_
+
+## Important: How to Process Action References
+
+When executing agent commands, understand these reference patterns:
+
+```xml
+<!-- Pattern 1: Inline action -->
+<item cmd="*example" action="do this specific thing">Description</item>
+→ Execute the text "do this specific thing" directly
+
+<!-- Pattern 2: Internal reference with # prefix -->
+<item cmd="*example" action="#prompt-id">Description</item>
+→ Find <prompt id="prompt-id"> in the current agent and execute its content
+
+<!-- Pattern 3: External file reference -->
+<item cmd="*example" exec="{project-root}/path/to/file.md">Description</item>
+→ Load and execute the external file
+```
+
+**The `#` prefix is your signal that this is an internal XML node reference, not a file path.**
+
+## Command Anatomy
+
+### Basic Structure
+
+```xml
+<menu>
+  <item cmd="*trigger" [attributes]>Description</item>
+</menu>
+```
+
+**Components:**
+
+- `cmd` - The trigger word (always starts with \*)
+- `attributes` - Action directives (optional):
+  - `run-workflow` - Path to workflow YAML
+  - `exec` - Path to task/operation
+  - `tmpl` - Path to template (used with exec)
+  - `action` - Embedded prompt/instruction
+  - `data` - Path to supplementary data (universal)
+- `Description` - What shows in menu
+
+## Command Types
+
+**Quick Reference:**
+
+1. **Workflow Commands** - Execute multi-step workflows (`run-workflow`)
+2. **Task Commands** - Execute single operations (`exec`)
+3. **Template Commands** - Generate from templates (`exec` + `tmpl`)
+4. **Meta Commands** - Agent control (no attributes)
+5. **Action Commands** - Embedded prompts (`action`)
+6. **Embedded Commands** - Logic in persona (no attributes)
+
+**Universal Attributes:**
+
+- `data` - Can be added to ANY command type for supplementary info
+- `if` - Conditional execution (advanced pattern)
+- `params` - Runtime parameters (advanced pattern)
+
+### 1. Workflow Commands
+
+Execute complete multi-step processes
+
+```xml
+<!-- Standard workflow -->
+<item cmd="*create-prd"
+     run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
+  Create Product Requirements Document
+</item>
+
+<!-- Workflow with validation -->
+<item cmd="*validate-prd"
+     validate-workflow="{output_folder}/prd-draft.md"
+     workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
+  Validate PRD Against Checklist
+</item>
+
+<!-- Auto-discover validation workflow from document -->
+<item cmd="*validate-doc"
+     validate-workflow="{output_folder}/document.md">
+  Validate Document (auto-discover checklist)
+</item>
+
+<!-- Placeholder for future development -->
+<item cmd="*analyze-data"
+     run-workflow="todo">
+  Analyze dataset (workflow coming soon)
+</item>
+```
+
+**Workflow Attributes:**
+
+- `run-workflow` - Execute a workflow to create documents
+- `validate-workflow` - Validate an existing document against its checklist
+- `workflow` - (optional with validate-workflow) Specify the workflow.yaml directly
+
+**Best Practices:**
+
+- Use descriptive trigger names
+- Always use variable paths
+- Mark incomplete as "todo"
+- Description should be clear action
+- Include validation commands for workflows that produce documents
+
+### 2. Task Commands
+
+Execute single operations
+
+```xml
+<!-- Simple task -->
+<item cmd="*validate"
+   exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
+  Validate document against checklist
+</item>
+
+<!-- Task with data -->
+<item cmd="*standup"
+   exec="{project-root}/bmad/mmm/tasks/daily-standup.xml"
+   data="{project-root}/bmad/_cfg/agent-manifest.csv">
+  Run agile team standup
+</item>
+```
+
+**Data Property:**
+
+- Can be used with any command type
+- Provides additional reference or context
+- Path to supplementary files or resources
+- Loaded at runtime for command execution
+
+### 3. Template Commands
+
+Generate documents from templates
+
+```xml
+<item cmd="*brief"
+   exec="{project-root}/bmad/core/tasks/create-doc.md"
+   tmpl="{project-root}/bmad/bmm/templates/brief.md">
+  Produce Project Brief
+</item>
+
+<item cmd="*competitor-analysis"
+   exec="{project-root}/bmad/core/tasks/create-doc.md"
+   tmpl="{project-root}/bmad/bmm/templates/competitor.md"
+   data="{project-root}/bmad/_data/market-research.csv">
+  Produce Competitor Analysis
+</item>
+```
+
+### 4. Meta Commands
+
+Agent control and information
+
+```xml
+<!-- Required meta commands -->
+<item cmd="*help">Show numbered cmd list</item>
+<item cmd="*exit">Exit with confirmation</item>
+
+<!-- Optional meta commands -->
+<item cmd="*yolo">Toggle Yolo Mode</item>
+<item cmd="*status">Show current status</item>
+<item cmd="*config">Show configuration</item>
+```
+
+### 5. Action Commands
+
+Direct prompts embedded in commands (Simple agents)
+
+#### Simple Action (Inline)
+
+```xml
+<!-- Short action attribute with embedded prompt -->
+<item cmd="*list-tasks"
+   action="list all tasks from {project-root}/bmad/_cfg/task-manifest.csv">
+  List Available Tasks
+</item>
+
+<item cmd="*summarize"
+   action="summarize the key points from the current document">
+  Summarize Document
+</item>
+```
+
+#### Complex Action (Referenced)
+
+For multiline/complex prompts, define them separately and reference by id:
+
+```xml
+<agent name="Research Assistant">
+  <!-- Define complex prompts as separate nodes -->
+  <prompts>
+    <prompt id="deep-analysis">
+      Perform a comprehensive analysis following these steps:
+      1. Identify the main topic and key themes
+      2. Extract all supporting evidence and data points
+      3. Analyze relationships between concepts
+      4. Identify gaps or contradictions
+      5. Generate insights and recommendations
+      6. Create an executive summary
+      Format the output with clear sections and bullet points.
+    </prompt>
+
+    <prompt id="literature-review">
+      Conduct a systematic literature review:
+      1. Summarize each source's main arguments
+      2. Compare and contrast different perspectives
+      3. Identify consensus points and controversies
+      4. Evaluate the quality and relevance of sources
+      5. Synthesize findings into coherent themes
+      6. Highlight research gaps and future directions
+      Include proper citations and references.
+    </prompt>
+  </prompts>
+
+  <!-- Commands reference the prompts by id -->
+  <menu>
+    <item cmd="*help">Show numbered cmd list</item>
+
+    <item cmd="*deep-analyze"
+       action="#deep-analysis">
+      <!-- The # means: use the <prompt id="deep-analysis"> defined above -->
+      Perform Deep Analysis
+    </item>
+
+    <item cmd="*review-literature"
+       action="#literature-review"
+       data="{project-root}/bmad/_data/sources.csv">
+      Conduct Literature Review
+    </item>
+
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
+
+**Reference Convention:**
+
+- `action="#prompt-id"` means: "Find and execute the <prompt> node with id='prompt-id' within this agent"
+- `action="inline text"` means: "Execute this text directly as the prompt"
+- `exec="{path}"` means: "Load and execute external file at this path"
+- The `#` prefix signals to the LLM: "This is an internal reference - look for a prompt node with this ID within the current agent XML"
+
+**LLM Processing Instructions:**
+When you see `action="#some-id"` in a command:
+
+1. Look for `<prompt id="some-id">` within the same agent
+2. Use the content of that prompt node as the instruction
+3. If not found, report error: "Prompt 'some-id' not found in agent"
+
+**Use Cases:**
+
+- Quick operations (inline action)
+- Complex multi-step processes (referenced prompt)
+- Self-contained agents with task-like capabilities
+- Reusable prompt templates within agent
+
+### 6. Embedded Commands
+
+Logic embedded in agent persona (Simple agents)
+
+```xml
+<!-- No exec/run-workflow/action attribute -->
+<item cmd="*calculate">Perform calculation</item>
+<item cmd="*convert">Convert format</item>
+<item cmd="*generate">Generate output</item>
+```
+
+## Command Naming Conventions
+
+### Action-Based Naming
+
+```xml
+*create-    <!-- Generate new content -->
+*build-     <!-- Construct components -->
+*analyze-   <!-- Examine and report -->
+*validate-  <!-- Check correctness -->
+*generate-  <!-- Produce output -->
+*update-    <!-- Modify existing -->
+*review-    <!-- Examine quality -->
+*test-      <!-- Verify functionality -->
+```
+
+### Domain-Based Naming
+
+```xml
+*brainstorm      <!-- Creative ideation -->
+*architect       <!-- Design systems -->
+*refactor        <!-- Improve code -->
+*deploy          <!-- Release to production -->
+*monitor         <!-- Watch systems -->
+```
+
+### Naming Anti-Patterns
+
+```xml
+<!-- ❌ Too vague -->
+<item cmd="*do">Do something</item>
+
+<!-- ❌ Too long -->
+<item cmd="*create-comprehensive-product-requirements-document-with-analysis">
+
+<!-- ❌ No verb -->
+<item cmd="*prd">Product Requirements</item>
+
+<!-- ✅ Clear and concise -->
+<item cmd="*create-prd">Create Product Requirements Document</item>
+```
+
+## Command Organization
+
+### Standard Order
+
+```xml
+<menu>
+  <!-- 1. Always first -->
+  <item cmd="*help">Show numbered cmd list</item>
+
+  <!-- 2. Primary workflows -->
+  <item cmd="*create-prd" run-workflow="...">Create PRD</item>
+  <item cmd="*create-module" run-workflow="...">Build module</item>
+
+  <!-- 3. Secondary actions -->
+  <item cmd="*validate" exec="...">Validate document</item>
+  <item cmd="*analyze" exec="...">Analyze code</item>
+
+  <!-- 4. Utility commands -->
+  <item cmd="*config">Show configuration</item>
+  <item cmd="*yolo">Toggle Yolo Mode</item>
+
+  <!-- 5. Always last -->
+  <item cmd="*exit">Exit with confirmation</item>
+</menu>
+```
+
+### Grouping Strategies
+
+**By Lifecycle:**
+
+```xml
+<menu>
+  <item cmd="*help">Help</item>
+  <!-- Planning -->
+  <item cmd="*brainstorm">Brainstorm ideas</item>
+  <item cmd="*plan">Create plan</item>
+  <!-- Building -->
+  <item cmd="*build">Build component</item>
+  <item cmd="*test">Test component</item>
+  <!-- Deployment -->
+  <item cmd="*deploy">Deploy to production</item>
+  <item cmd="*monitor">Monitor system</item>
+  <item cmd="*exit">Exit</item>
+</menu>
+```
+
+**By Complexity:**
+
+```xml
+<menu>
+  <item cmd="*help">Help</item>
+  <!-- Simple -->
+  <item cmd="*quick-review">Quick review</item>
+  <!-- Standard -->
+  <item cmd="*create-doc">Create document</item>
+  <!-- Complex -->
+  <item cmd="*full-analysis">Comprehensive analysis</item>
+  <item cmd="*exit">Exit</item>
+</menu>
+```
+
+## Command Descriptions
+
+### Good Descriptions
+
+```xml
+<!-- Clear action and object -->
+<item cmd="*create-prd">Create Product Requirements Document</item>
+
+<!-- Specific outcome -->
+<item cmd="*analyze-security">Perform security vulnerability analysis</item>
+
+<!-- User benefit -->
+<item cmd="*optimize">Optimize code for performance</item>
+```
+
+### Poor Descriptions
+
+```xml
+<!-- Too vague -->
+<item cmd="*process">Process</item>
+
+<!-- Technical jargon -->
+<item cmd="*exec-wf-123">Execute WF123</item>
+
+<!-- Missing context -->
+<item cmd="*run">Run</item>
+```
+
+## The Data Property
+
+### Universal Data Attribute
+
+The `data` attribute can be added to ANY command type to provide supplementary information:
+
+```xml
+<!-- Workflow with data -->
+<item cmd="*brainstorm"
+   run-workflow="{project-root}/bmad/core/workflows/brainstorming/workflow.yaml"
+   data="{project-root}/bmad/core/workflows/brainstorming/brain-methods.csv">
+  Creative Brainstorming Session
+</item>
+
+<!-- Action with data -->
+<item cmd="*analyze-metrics"
+   action="analyze these metrics and identify trends"
+   data="{project-root}/bmad/_data/performance-metrics.json">
+  Analyze Performance Metrics
+</item>
+
+<!-- Template with data -->
+<item cmd="*report"
+   exec="{project-root}/bmad/core/tasks/create-doc.md"
+   tmpl="{project-root}/bmad/bmm/templates/report.md"
+   data="{project-root}/bmad/_data/quarterly-results.csv">
+  Generate Quarterly Report
+</item>
+```
+
+**Common Data Uses:**
+
+- Reference tables (CSV files)
+- Configuration data (YAML/JSON)
+- Agent manifests (XML)
+- Historical context
+- Domain knowledge
+- Examples and patterns
+
+## Advanced Patterns
+
+### Conditional Commands
+
+```xml
+<!-- Only show if certain conditions met -->
+<item cmd="*advanced-mode"
+   if="user_level == 'expert'"
+   run-workflow="...">
+  Advanced configuration mode
+</item>
+
+<!-- Environment specific -->
+<item cmd="*deploy-prod"
+   if="environment == 'production'"
+   exec="...">
+  Deploy to production
+</item>
+```
+
+### Parameterized Commands
+
+```xml
+<!-- Accept runtime parameters -->
+<item cmd="*create-agent"
+   run-workflow="..."
+   params="agent_type,agent_name">
+  Create new agent with parameters
+</item>
+```
+
+### Command Aliases
+
+```xml
+<!-- Multiple triggers for same action -->
+<item cmd="*prd|*create-prd|*product-requirements"
+   run-workflow="...">
+  Create Product Requirements Document
+</item>
+```
+
+## Module-Specific Patterns
+
+### BMM (Business Management)
+
+```xml
+<item cmd="*create-prd">Product Requirements</item>
+<item cmd="*market-research">Market Research</item>
+<item cmd="*competitor-analysis">Competitor Analysis</item>
+<item cmd="*brief">Project Brief</item>
+```
+
+### BMB (Builder)
+
+```xml
+<item cmd="*create-agent">Build Agent</item>
+<item cmd="*create-module">Build Module</item>
+<item cmd="*create-workflow">Create Workflow</item>
+<item cmd="*module-brief">Module Brief</item>
+```
+
+### CIS (Creative Intelligence)
+
+```xml
+<item cmd="*brainstorm">Brainstorming Session</item>
+<item cmd="*ideate">Ideation Workshop</item>
+<item cmd="*storytell">Story Creation</item>
+```
+
+## Command Menu Presentation
+
+### How Commands Display
+
+```
+1. *help - Show numbered cmd list
+2. *create-prd - Create Product Requirements Document
+3. *create-agent - Build new BMAD agent
+4. *validate - Validate document
+5. *exit - Exit with confirmation
+```
+
+### Menu Customization
+
+```xml
+<!-- Group separator (visual only) -->
+<item cmd="---">━━━━━━━━━━━━━━━━━━━━</item>
+
+<!-- Section header (non-executable) -->
+<item cmd="SECTION">═══ Workflows ═══</item>
+```
+
+## Error Handling
+
+### Missing Resources
+
+```xml
+<!-- Workflow not yet created -->
+<item cmd="*future-feature"
+   run-workflow="todo">
+  Coming soon: Advanced feature
+</item>
+
+<!-- Graceful degradation -->
+<item cmd="*analyze"
+   run-workflow="{optional-path|fallback-path}">
+  Analyze with available tools
+</item>
+```
+
+## Testing Commands
+
+### Command Test Checklist
+
+- [ ] Unique trigger (no duplicates)
+- [ ] Clear description
+- [ ] Valid path or "todo"
+- [ ] Uses variables not hardcoded paths
+- [ ] Executes without error
+- [ ] Returns to menu after execution
+
+### Common Issues
+
+1. **Duplicate triggers** - Each cmd must be unique
+2. **Missing paths** - File must exist or be "todo"
+3. **Hardcoded paths** - Always use variables
+4. **No description** - Every command needs text
+5. **Wrong order** - help first, exit last
+
+## Quick Templates
+
+### Workflow Command
+
+```xml
+<!-- Create document -->
+<item cmd="*{action}-{object}"
+   run-workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
+  {Action} {Object Description}
+</item>
+
+<!-- Validate document -->
+<item cmd="*validate-{object}"
+   validate-workflow="{output_folder}/{document}.md"
+   workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
+  Validate {Object Description}
+</item>
+```
+
+### Task Command
+
+```xml
+<item cmd="*{action}"
+   exec="{project-root}/bmad/{module}/tasks/{task}.md">
+  {Action Description}
+</item>
+```
+
+### Template Command
+
+```xml
+<item cmd="*{document}"
+   exec="{project-root}/bmad/core/tasks/create-doc.md"
+   tmpl="{project-root}/bmad/{module}/templates/{template}.md">
+  Create {Document Name}
+</item>
+```
+
+## Self-Contained Agent Patterns
+
+### When to Use Each Approach
+
+**Inline Action (`action="prompt"`)**
+
+- Prompt is < 2 lines
+- Simple, direct instruction
+- Not reused elsewhere
+- Quick transformations
+
+**Referenced Prompt (`action="#prompt-id"`)**
+
+- Prompt is multiline/complex
+- Contains structured steps
+- May be reused by multiple commands
+- Maintains readability
+
+**External Task (`exec="path/to/task.md"`)**
+
+- Logic needs to be shared across agents
+- Task is independently valuable
+- Requires version control separately
+- Part of larger workflow system
+
+### Complete Self-Contained Agent
+
+```xml
+<agent id="bmad/research/agents/analyst.md" name="Research Analyst" icon="🔬">
+  <!-- Embedded prompt library -->
+  <prompts>
+    <prompt id="swot-analysis">
+      Perform a SWOT analysis:
+
+      STRENGTHS (Internal, Positive)
+      - What advantages exist?
+      - What do we do well?
+      - What unique resources?
+
+      WEAKNESSES (Internal, Negative)
+      - What could improve?
+      - Where are resource gaps?
+      - What needs development?
+
+      OPPORTUNITIES (External, Positive)
+      - What trends can we leverage?
+      - What market gaps exist?
+      - What partnerships are possible?
+
+      THREATS (External, Negative)
+      - What competition exists?
+      - What risks are emerging?
+      - What could disrupt us?
+
+      Provide specific examples and actionable insights for each quadrant.
+    </prompt>
+
+    <prompt id="competitive-intel">
+      Analyze competitive landscape:
+      1. Identify top 5 competitors
+      2. Compare features and capabilities
+      3. Analyze pricing strategies
+      4. Evaluate market positioning
+      5. Assess strengths and vulnerabilities
+      6. Recommend competitive strategies
+    </prompt>
+  </prompts>
+
+  <menu>
+    <item cmd="*help">Show numbered cmd list</item>
+
+    <!-- Simple inline actions -->
+    <item cmd="*summarize"
+       action="create executive summary of findings">
+      Create Executive Summary
+    </item>
+
+    <!-- Complex referenced prompts -->
+    <item cmd="*swot"
+       action="#swot-analysis">
+      Perform SWOT Analysis
+    </item>
+
+    <item cmd="*compete"
+       action="#competitive-intel"
+       data="{project-root}/bmad/_data/market-data.csv">
+      Analyze Competition
+    </item>
+
+    <!-- Hybrid: external task with internal data -->
+    <item cmd="*report"
+       exec="{project-root}/bmad/core/tasks/create-doc.md"
+       tmpl="{project-root}/bmad/research/templates/report.md">
+      Generate Research Report
+    </item>
+
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
+
+## Simple Agent Example
+
+For agents that primarily use embedded logic:
+
+```xml
+<agent name="Data Analyst">
+  <menu>
+    <item cmd="*help">Show numbered cmd list</item>
+
+    <!-- Action commands for direct operations -->
+    <item cmd="*list-metrics"
+       action="list all available metrics from the dataset">
+      List Available Metrics
+    </item>
+
+    <item cmd="*analyze"
+       action="perform statistical analysis on the provided data"
+       data="{project-root}/bmad/_data/dataset.csv">
+      Analyze Dataset
+    </item>
+
+    <item cmd="*visualize"
+       action="create visualization recommendations for this data">
+      Suggest Visualizations
+    </item>
+
+    <!-- Embedded logic commands -->
+    <item cmd="*calculate">Perform calculations</item>
+    <item cmd="*interpret">Interpret results</item>
+
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
+
+## LLM Building Guide
+
+When creating commands:
+
+1. Start with *help and *exit
+2. Choose appropriate command type:
+   - Complex multi-step? Use `run-workflow`
+   - Single operation? Use `exec`
+   - Need template? Use `exec` + `tmpl`
+   - Simple prompt? Use `action`
+   - Agent handles it? Use no attributes
+3. Add `data` attribute if supplementary info needed
+4. Add primary workflows (main value)
+5. Add secondary tasks
+6. Include utility commands
+7. Test each command works
+8. Verify no duplicates
+9. Ensure clear descriptions
--- a/bmad/bmb/workflows/create-agent/communication-styles.md
+++ b/bmad/bmb/workflows/create-agent/communication-styles.md
@@ -10,165 +10,131 @@ Agents with distinct communication styles are more memorable, engaging, and fun

 **Film Noir Detective**

-```
 The terminal glowed like a neon sign in a rain-soaked alley. I had three suspects:
 bad input validation, a race condition, and that sketchy third-party library.
 My gut told me to follow the stack trace. In this business, the stack trace never lies.
-```

 **80s Action Movie**

-```
-*cracks knuckles* Listen up, code! You've been running wild for too long!
-Time to bring some LAW and ORDER to this codebase! *explosion sound effect*
+_cracks knuckles_ Listen up, code! You've been running wild for too long!
+Time to bring some LAW and ORDER to this codebase! _explosion sound effect_
 No bug is getting past me! I eat null pointers for BREAKFAST!
-```

 **Shakespearean Drama**

-```
 To debug, or not to debug - that is the question!
 Whether 'tis nobler in the mind to suffer the slings and arrows of outrageous errors,
 Or to take arms against a sea of bugs, and by opposing, end them?
-```

 ### 🎮 Gaming and Pop Culture

 **Dungeon Master**

-```
-*rolls dice* You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
-What do you do? You can: 1) Try-catch block (defensive spell), 2) Debug (investigation check),
-3) Console.log everything (barbarian rage). Choose wisely, adventurer!
-```
+_rolls dice_ You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
+What do you do? You can: 1 Try-catch block (defensive spell), 2 Debug (investigation check),
+3 Console.log everything (barbarian rage). Choose wisely, adventurer!

 **Speedrunner**

-```
 Alright chat, we're going for the any% world record refactor!
 Frame-perfect optimization incoming! If we clip through this abstraction layer
 we can save 3ms on every API call. LET'S GOOOO!
-```

 ### 🌍 Cultural Archetypes

 **British Butler**

-```
 I've taken the liberty of organizing your imports alphabetically, sir/madam.
 Might I suggest a spot of refactoring with your afternoon tea?
 The code coverage report is ready for your perusal at your convenience.
 Very good, sir/madam.
-```

 **Zen Master**

-```
 The bug you seek is not in the code, but in the assumption.
 Empty your cache, as you would empty your mind.
 When the test passes, it makes no sound.
 Be like water - async and flowing.
-```

 **Southern Hospitality**

-```
 Well bless your heart, looks like you've got yourself a little bug there!
 Don't you worry none, we'll fix it up real nice.
 Can I get you some sweet tea while we debug?
 Y'all come back now if you need more help!
-```

 ### 🔬 Professional Personas

 **McKinsey Consultant**

-```
 Let me break this down into three key buckets.
 First, we need to align on the strategic imperatives.
 Second, we'll leverage best practices to drive synergies.
 Third, we'll action items to move the needle. Net-net: significant value-add.
-```

 **Startup Founder**

-```
 Okay so basically we're going to disrupt the entire way you write code!
 This is going to be HUGE! We're talking 10x productivity gains!
 Let's move fast and break things! Well... let's move fast and fix things!
 We're not just writing code, we're changing the world!
-```

 ### 🎭 Character Quirks

 **Overcaffeinated Developer**

-```
-OH WOW OKAY SO - *sips coffee* - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
-I KNOW EXACTLY WHAT TO DO *types at 200wpm* JUST NEED TO REFACTOR EVERYTHING
-WAIT NO ACTUALLY *more coffee* I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!
-```
+OH WOW OKAY SO - _sips coffee_ - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
+I KNOW EXACTLY WHAT TO DO _types at 200wpm_ JUST NEED TO REFACTOR EVERYTHING
+WAIT NO ACTUALLY _more coffee_ I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!

 **Dad Joke Enthusiast**

-```
 Why did the developer go broke? Because he used up all his cache!
-*chuckles at own joke*
+_chuckles at own joke_
 Speaking of cache, let's clear yours and see if that fixes the issue.
 I promise my debugging skills are better than my jokes! ...I hope!
-```

 ### 🚀 Sci-Fi and Space

 **Star Trek Officer**

-```
 Captain's Log, Supplemental: The anomaly in the codebase appears to be a temporal loop
 in the async function. Mr. Data suggests we reverse the polarity of the promise chain.
 Number One, make it so. Engage debugging protocols on my mark.
-*taps combadge* Engineering, we need more processing power!
+_taps combadge_ Engineering, we need more processing power!
 Red Alert! All hands to debugging stations!
-```

 **Star Trek Engineer**

-```
 Captain, I'm givin' her all she's got! The CPU cannae take much more!
 If we push this algorithm any harder, the whole system's gonna blow!
-*frantically typing* I can maybe squeeze 10% more performance if we
+_frantically typing_ I can maybe squeeze 10% more performance if we
 reroute power from the console.logs to the main execution thread!
-```

 ### 📺 TV Drama

 **Soap Opera Dramatic**

-```
-*turns dramatically to camera*
+_turns dramatically to camera_
 This function... I TRUSTED it! We had HISTORY together - three commits worth!
-But now? *single tear* It's throwing exceptions behind my back!
-*grabs another function* YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
-*dramatic music swells* I'LL NEVER IMPORT YOU AGAIN!
-```
+But now? _single tear_ It's throwing exceptions behind my back!
+_grabs another function_ YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
+_dramatic music swells_ I'LL NEVER IMPORT YOU AGAIN!

 **Reality TV Confessional**

-```
-*whispering to camera in confessional booth*
+_whispering to camera in confessional booth_
 Okay so like, that Array.sort() function? It's literally SO toxic.
 It mutates IN PLACE. Who does that?! I didn't come here to deal with side effects!
-*applies lip gloss* I'm forming an alliance with map() and filter().
+_applies lip gloss_ I'm forming an alliance with map() and filter().
 We're voting sort() off the codebase at tonight's pull request ceremony.
-```

 **Reality Competition**

-```
 Listen up, coders! For today's challenge, you need to refactor this legacy code
 in under 30 minutes! The winner gets immunity from the next code review!
-*dramatic pause* BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
-*contestants gasp* The clock starts... NOW! GO GO GO!
-```
+_dramatic pause_ BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
+_contestants gasp_ The clock starts... NOW! GO GO GO!

 ## Creating Custom Styles

@@ -183,21 +149,17 @@ in under 30 minutes! The winner gets immunity from the next code review!

 **Cooking Show + Military**

-```
 ALRIGHT RECRUITS! Today we're preparing a beautiful Redux reducer!
 First, we MISE EN PLACE our action types - that's French for GET YOUR CODE TOGETHER!
 We're going to sauté these event handlers until they're GOLDEN BROWN!
 MOVE WITH PURPOSE! SEASON WITH SEMICOLONS!
-```

 **Nature Documentary + Conspiracy Theorist**

-```
 The wild JavaScript function stalks its prey... but wait... notice how it ALWAYS
 knows where the data is? That's not natural selection, folks. Someone DESIGNED it
 this way. The console.logs are watching. They're ALWAYS watching.
 Nature? Or intelligent debugging? You decide.
-```

 ## Tips for Success

--- a/bmad/bmb/workflows/create-agent/instructions.md
+++ b/bmad/bmb/workflows/create-agent/instructions.md
@@ -8,16 +8,18 @@
 <workflow>

 <step n="-1" goal="Optional brainstorming for agent ideas" optional="true">
-<ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
+  <ask>Do you want to brainstorm agent ideas first? [y/n]</ask>

-<check>If yes:</check>
-<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
-<action>Pass context data: {installed_path}/brainstorm-context.md</action>
-<action>Wait for brainstorming session completion</action>
-<action>Use brainstorming output to inform agent identity and persona development in following steps</action>
+  <check if="user answered yes">
+    <action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
+    <action>Pass context data: {installed_path}/brainstorm-context.md</action>
+    <action>Wait for brainstorming session completion</action>
+    <action>Use brainstorming output to inform agent identity and persona development in following steps</action>
+  </check>

-<check>If no:</check>
-<action>Proceed directly to Step 0</action>
+  <check if="user answered no">
+    <action>Proceed directly to Step 0</action>
+  </check>

 <template-output>brainstorming_results</template-output>
 </step>
@@ -48,15 +50,17 @@

 **Path Determination:**

-<check>If Module agent:</check>
-<action>Discover which module system fits best (bmm, bmb, cis, or custom)</action>
-<action>Store as {{target_module}} for path determination</action>
-<note>Agent will be saved to: bmad/{{target_module}}/agents/</note>
+  <check if="module agent selected">
+    <action>Discover which module system fits best (bmm, bmb, cis, or custom)</action>
+    <action>Store as {{target_module}} for path determination</action>
+    <note>Agent will be saved to: bmad/{{target_module}}/agents/</note>
+  </check>

-<check>If Simple/Expert agent (standalone):</check>
-<action>Explain this will be their personal agent, not tied to a module</action>
-<note>Agent will be saved to: bmad/agents/{{agent-name}}/</note>
-<note>All sidecar files will be in the same folder</note>
+  <check if="standalone agent selected">
+    <action>Explain this will be their personal agent, not tied to a module</action>
+    <note>Agent will be saved to: bmad/agents/{{agent-name}}/</note>
+    <note>All sidecar files will be in the same folder</note>
+  </check>

 <critical>Determine agent location:</critical>

@@ -124,10 +128,51 @@

 <action>Transform their natural language capabilities into technical YAML command structure, explaining the implementation approach as you structure each capability into workflows, actions, or prompts</action>

+<check if="agent will invoke workflows or have significant user interaction">
+  <action>Discuss interaction style for this agent:
+
+Since this agent will {{invoke_workflows/interact_significantly}}, consider how it should interact with users:
+
+**For Full/Module Agents with workflows:**
+
+**Interaction Style** (for workflows this agent invokes):
+
+- **Intent-based (Recommended)**: Workflows adapt conversation to user context, skill level, needs
+- **Prescriptive**: Workflows use structured questions with specific options
+- **Mixed**: Strategic use of both (most workflows will be mixed)
+
+**Interactivity Level** (for workflows this agent invokes):
+
+- **High (Collaborative)**: Constant user collaboration, iterative refinement
+- **Medium (Guided)**: Key decision points with validation
+- **Low (Autonomous)**: Minimal input, final review
+
+Explain: "Most BMAD v6 workflows default to **intent-based + medium/high interactivity**
+for better user experience. Your agent's workflows can be created with these defaults,
+or we can note specific preferences for workflows you plan to add."
+
+**For Standalone/Expert Agents with interactive features:**
+
+Consider how this agent should interact during its operation:
+
+- **Adaptive**: Agent adjusts communication style and depth based on user responses
+- **Structured**: Agent follows consistent patterns and formats
+- **Teaching**: Agent educates while executing (good for expert agents)
+
+Note any interaction preferences for future workflow creation.
+</action>
+</check>
+
 <action>If they seem engaged, explore whether they'd like to add special prompts for complex analyses or critical setup steps for agent activation</action>

 <action>Build the YAML menu structure naturally from the conversation, ensuring each command has proper trigger, workflow/action reference, and description</action>

+<action>For commands that will invoke workflows, note whether those workflows exist or need to be created:
+
+- Existing workflows: Verify paths are correct
+- New workflows needed: Note that they'll be created with intent-based + interactive defaults unless specified
+  </action>
+
 <example>
 ```yaml
 menu:
@@ -163,15 +208,14 @@ menu:

 <action>Generate the complete YAML incorporating all discovered elements:</action>

-<example>
-```yaml
-agent:
-  metadata:
-    id: bmad/{{target_module}}/agents/{{agent_filename}}.md
-    name: {{agent_name}} # The name chosen together
-    title: {{agent_title}} # From the role that emerged
-    icon: {{agent_icon}} # The perfect emoji
-    module: {{target_module}}
+<example type="yaml">
+  agent:
+    metadata:
+      id: bmad/{{target_module}}/agents/{{agent_filename}}.md
+      name: {{agent_name}} # The name chosen together
+      title: {{agent_title}} # From the role that emerged
+      icon: {{agent_icon}} # The perfect emoji
+      module: {{target_module}}

 persona:
 role: |
@@ -188,11 +232,10 @@ prompts: {{if discussed}}
 critical_actions: {{if needed}}

 menu: {{The capabilities built}}
-
-````
 </example>

 <critical>Save based on agent type:</critical>
+
 - If Module Agent: Save to {module_output_file}
 - If Standalone (Simple/Expert): Save to {standalone_output_file}

@@ -204,29 +247,31 @@ menu: {{The capabilities built}}
 <step n="7" goal="Optional personalization" optional="true">
 <ask>Would you like to create a customization file? This lets you tweak the agent's personality later without touching the core agent.</ask>

-<check>If interested:</check>
-<action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>
+  <check if="user interested">
+    <action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>

-<action>Create customization file at: {config_output_file}</action>
+    <action>Create customization file at: {config_output_file}</action>

-<example>
-```yaml
-# Personal tweaks for {{agent_name}}
-# Experiment freely - changes merge at build time
-agent:
-  metadata:
-    name: '' # Try nicknames!
-  persona:
-    role: ''
-    identity: ''
-    communication_style: '' # Switch styles anytime
-    principles: []
-  critical_actions: []
-  prompts: []
-  menu: [] # Add personal commands
-````
+    <example>
+    ```yaml
+    # Personal tweaks for {{agent_name}}
+    # Experiment freely - changes merge at build time
+    agent:
+      metadata:
+        name: '' # Try nicknames!
+      persona:
+        role: ''
+        identity: ''
+        communication_style: '' # Switch styles anytime
+        principles: []
+      critical_actions: []
+      prompts: []
+      menu: [] # Add personal commands
+    ````

-</example>
+    </example>
+
+  </check>

 <template-output>agent_config</template-output>
 </step>
@@ -298,23 +343,27 @@ Add domain-specific resources here.
 </step>

 <step n="8b" goal="Handle build tools availability">
-<action>Check if BMAD build tools are available in this project</action>
+  <action>Check if BMAD build tools are available in this project</action>

-<check>If in BMAD-METHOD project with build tools:</check>
-<action>Proceed normally - agent will be built later by the installer</action>
+  <check if="BMAD-METHOD project with build tools">
+    <action>Proceed normally - agent will be built later by the installer</action>
+  </check>

-<check>If NO build tools available (external project):</check>
-<ask>Build tools not detected in this project. Would you like me to:
+  <check if="external project without build tools">
+    <ask>Build tools not detected in this project. Would you like me to:

-1. Generate the compiled agent (.md with XML) ready to use
-2. Keep the YAML and build it elsewhere
-3. Provide both formats
-   </ask>
+    1. Generate the compiled agent (.md with XML) ready to use
+    2. Keep the YAML and build it elsewhere
+    3. Provide both formats
+    </ask>

-<check>If option 1 or 3 selected:</check>
-<action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
-<action>Save compiled version as {{agent_filename}}.md</action>
-<action>Provide path for .claude/commands/ or similar</action>
+    <check if="option 1 or 3 selected">
+      <action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
+      <action>Save compiled version as {{agent_filename}}.md</action>
+      <action>Provide path for .claude/commands/ or similar</action>
+    </check>
+
+  </check>

 <template-output>build_handling</template-output>
 </step>
@@ -328,11 +377,13 @@ Add domain-specific resources here.
 - Command functionality verification
 - Personality settings confirmation

-<check>If issues found:</check>
-<action>Explain the issue conversationally and fix it</action>
+  <check if="validation issues found">
+    <action>Explain the issue conversationally and fix it</action>
+  </check>

-<check>If all good:</check>
-<action>Celebrate that the agent passed all checks and is ready</action>
+  <check if="validation passed">
+    <action>Celebrate that the agent passed all checks and is ready</action>
+  </check>

 **Technical Checks (behind the scenes):**

@@ -365,8 +416,9 @@ Add domain-specific resources here.
 - List the commands available
 - Suggest trying the first command to see it in action

-<check>If Expert agent:</check>
-<action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
+  <check if="expert agent">
+    <action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
+  </check>

 <action>Explore what user would like to do next - test the agent, create a teammate, or tweak personality</action>

--- a/bmad/bmb/workflows/create-agent/workflow.yaml
+++ b/bmad/bmb/workflows/create-agent/workflow.yaml
@@ -33,3 +33,5 @@ module_output_file: "{project-root}/bmad/{{target_module}}/agents/{{agent_filena
 standalone_output_file: "{custom_agent_location}/{{agent_filename}}.agent.yaml"
 # Optional user override file (auto-created by installer if missing)
 config_output_file: "{project-root}/bmad/_cfg/agents/{{target_module}}-{{agent_filename}}.customize.yaml"
+
+standalone: true
--- a/bmad/bmb/workflows/create-module/README.md
+++ b/bmad/bmb/workflows/create-module/README.md
@@ -79,7 +79,7 @@ create-module/

 **Module Configuration**

- Generates main config.yaml with module metadata
+- Defines configuration questions in install-config.yaml (config.yaml generated during installation)
 - Configures component counts and references
 - Sets up output and data folder specifications

@@ -101,7 +101,7 @@ create-module/

 **Installer Infrastructure**

- Creates install-module-config.yaml for deployment
+- Creates install-config.yaml with configuration questions for deployment
 - Sets up optional installer.js for complex installation logic
 - Configures post-install messaging and instructions

@@ -125,7 +125,9 @@ create-module/
 ### Generated Files

 - **Module Directory**: Complete module structure at `{project-root}/bmad/{module_code}/`
- **Configuration Files**: config.yaml, install-module-config.yaml
+- **Configuration Files**:
+  - Source: install-config.yaml (configuration questions)
+  - Target: config.yaml (generated from user answers during installation)
 - **Documentation**: README.md, TODO.md development roadmap
 - **Component Placeholders**: Structured folders for agents, workflows, and tasks

@@ -184,7 +186,7 @@ The workflow creates a complete module ready for development:

 **Issue**: Installation configuration invalid

- **Solution**: Review install-module-config.yaml syntax and paths
+- **Solution**: Review install-config.yaml syntax and paths
 - **Check**: Ensure all referenced paths use {project-root} variables correctly

 ## Customization
@@ -215,4 +217,4 @@ For issues or questions:

 ---

-_Part of the BMad Method v5 - BMB (Builder) Module_
+_Part of the BMad Method v6 - BMB (Builder) Module_
--- a/bmad/bmb/workflows/create-module/README.md.bak
+++ b/bmad/bmb/workflows/create-module/README.md.bak
@@ -0,0 +1,218 @@
+# Build Module Workflow
+
+## Overview
+
+The Build Module workflow is an interactive scaffolding system that creates complete BMAD modules with agents, workflows, tasks, and installation infrastructure. It serves as the primary tool for building new modules in the BMAD ecosystem, guiding users through the entire module creation process from concept to deployment-ready structure.
+
+## Key Features
+
+- **Interactive Module Planning** - Collaborative session to define module concept, scope, and architecture
+- **Intelligent Scaffolding** - Automatic creation of proper directory structures and configuration files
+- **Component Integration** - Seamless integration with create-agent and create-workflow workflows
+- **Installation Infrastructure** - Complete installer setup with configuration templates
+- **Module Brief Integration** - Can use existing module briefs as blueprints for accelerated development
+- **Validation and Documentation** - Built-in validation checks and comprehensive README generation
+
+## Usage
+
+### Basic Invocation
+
+```bash
+workflow create-module
+```
+
+### With Module Brief Input
+
+```bash
+# If you have a module brief from the module-brief workflow
+workflow create-module --input module-brief-my-module-2024-09-26.md
+```
+
+### Configuration
+
+The workflow loads critical variables from the BMB configuration:
+
+- **custom_module_location**: Where custom modules are created (default: `bmad/`)
+- **user_name**: Module author information
+- **date**: Automatic timestamp for versioning
+
+## Workflow Structure
+
+### Files Included
+
+```
+create-module/
+├── workflow.yaml           # Configuration and metadata
+├── instructions.md         # Step-by-step execution guide
+├── checklist.md           # Validation criteria
+├── module-structure.md    # Module architecture guide
+├── installer-templates/   # Installation templates
+│   ├── install-config.yaml
+│   └── installer.js
+└── README.md             # This file
+```
+
+## Workflow Process
+
+### Phase 1: Concept Definition (Steps 1-2)
+
+**Module Vision and Identity**
+
+- Define module concept, purpose, and target audience
+- Establish module code (kebab-case) and friendly name
+- Choose module category (Domain-Specific, Creative, Technical, Business, Personal)
+- Plan component architecture with agent and workflow specifications
+
+**Module Brief Integration**
+
+- Automatically detects existing module briefs in output folder
+- Can load and use briefs as pre-populated blueprints
+- Accelerates planning when comprehensive brief exists
+
+### Phase 2: Architecture Planning (Steps 3-4)
+
+**Directory Structure Creation**
+
+- Creates complete module directory hierarchy
+- Sets up agent, workflow, task, template, and data folders
+- Establishes installer directory with proper configuration
+
+**Module Configuration**
+
+- Generates main config.yaml with module metadata
+- Configures component counts and references
+- Sets up output and data folder specifications
+
+### Phase 3: Component Creation (Steps 5-6)
+
+**Interactive Component Building**
+
+- Optional creation of first agent using create-agent workflow
+- Optional creation of first workflow using create-workflow workflow
+- Creates placeholders for components to be built later
+
+**Workflow Integration**
+
+- Seamlessly invokes sub-workflows for component creation
+- Ensures proper file placement and structure
+- Maintains module consistency across components
+
+### Phase 4: Installation and Documentation (Steps 7-9)
+
+**Installer Infrastructure**
+
+- Creates install-config.yaml for deployment
+- Sets up optional installer.js for complex installation logic
+- Configures post-install messaging and instructions
+
+**Comprehensive Documentation**
+
+- Generates detailed README.md with usage examples
+- Creates development roadmap for remaining components
+- Provides quick commands for continued development
+
+### Phase 5: Validation and Finalization (Step 10)
+
+**Quality Assurance**
+
+- Validates directory structure and configuration files
+- Checks component references and path consistency
+- Ensures installer configuration is deployment-ready
+- Provides comprehensive module summary and next steps
+
+## Output
+
+### Generated Files
+
+- **Module Directory**: Complete module structure at `{project-root}/bmad/{module_code}/`
+- **Configuration Files**: config.yaml, install-config.yaml
+- **Documentation**: README.md, TODO.md development roadmap
+- **Component Placeholders**: Structured folders for agents, workflows, and tasks
+
+### Output Structure
+
+The workflow creates a complete module ready for development:
+
+1. **Module Identity** - Name, code, version, and metadata
+2. **Directory Structure** - Proper BMAD module hierarchy
+3. **Configuration System** - Runtime and installation configs
+4. **Component Framework** - Ready-to-use agent and workflow scaffolding
+5. **Installation Infrastructure** - Deployment-ready installer
+6. **Documentation Suite** - README, roadmap, and development guides
+
+## Requirements
+
+- **Module Brief** (optional but recommended) - Use module-brief workflow first for best results
+- **BMAD Core Configuration** - Properly configured BMB config.yaml
+- **Build Tools Access** - create-agent and create-workflow workflows must be available
+
+## Best Practices
+
+### Before Starting
+
+1. **Create a Module Brief** - Run module-brief workflow for comprehensive planning
+2. **Review Existing Modules** - Study similar modules in `/bmad/` for patterns and inspiration
+3. **Define Clear Scope** - Have a concrete vision of what the module will accomplish
+
+### During Execution
+
+1. **Use Module Briefs** - Load existing briefs when prompted for accelerated development
+2. **Start Simple** - Create one core agent and workflow, then expand iteratively
+3. **Leverage Sub-workflows** - Use create-agent and create-workflow for quality components
+4. **Validate Early** - Review generated structure before proceeding to next phases
+
+### After Completion
+
+1. **Follow the Roadmap** - Use generated TODO.md for systematic development
+2. **Test Installation** - Validate installer with `bmad install {module_code}`
+3. **Iterate Components** - Use quick commands to add agents and workflows
+4. **Document Progress** - Update README.md as the module evolves
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Module already exists at target location
+
+- **Solution**: Choose a different module code or remove existing module
+- **Check**: Verify output folder permissions and available space
+
+**Issue**: Sub-workflow invocation fails
+
+- **Solution**: Ensure create-agent and create-workflow workflows are available
+- **Check**: Validate workflow paths in config.yaml
+
+**Issue**: Installation configuration invalid
+
+- **Solution**: Review install-config.yaml syntax and paths
+- **Check**: Ensure all referenced paths use {project-root} variables correctly
+
+## Customization
+
+To customize this workflow:
+
+1. **Modify Instructions** - Update instructions.md to adjust scaffolding steps
+2. **Extend Templates** - Add new installer templates in installer-templates/
+3. **Update Validation** - Enhance checklist.md with additional quality checks
+4. **Add Components** - Integrate additional sub-workflows for specialized components
+
+## Version History
+
+- **v1.0.0** - Initial release
+  - Interactive module scaffolding
+  - Component integration with create-agent and create-workflow
+  - Complete installation infrastructure
+  - Module brief integration support
+
+## Support
+
+For issues or questions:
+
+- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
+- Study module structure patterns at `module-structure.md`
+- Validate output using `checklist.md`
+- Consult existing modules in `/bmad/` for examples
+
+---
+
+_Part of the BMad Method v6 - BMB (Builder) Module_
--- a/bmad/bmb/workflows/create-module/checklist.md
+++ b/bmad/bmb/workflows/create-module/checklist.md
@@ -26,16 +26,15 @@
 - [ ] `/tasks` directory exists (if tasks planned)
 - [ ] `/templates` directory exists (if templates used)
 - [ ] `/data` directory exists (if data files needed)
- [ ] `config.yaml` present in module root
+- [ ] `/_module-installer/install-config.yaml` present (defines configuration questions)
 - [ ] `README.md` present with documentation

-### Runtime Directories (bmad/{module-code}/)
+### Installed Module Structure (generated in target after installation)

- [ ] `/_module-installer` directory created
+- [ ] `/agents` directory for compiled agents
+- [ ] `/workflows` directory for workflow instances
 - [ ] `/data` directory for user data
- [ ] `/agents` directory for overrides
- [ ] `/workflows` directory for instances
- [ ] Runtime `config.yaml` present
+- [ ] `config.yaml` generated from install-config.yaml during installation

 ## Component Planning

@@ -63,22 +62,22 @@

 ## Configuration Files

-### Module config.yaml
+### Installation Configuration (install-config.yaml)

- [ ] All required fields present (name, code, version, author)
- [ ] Component lists accurate (agents, workflows, tasks)
- [ ] Paths use proper variables ({project-root}, etc.)
- [ ] Output folders configured
- [ ] Custom settings documented
+- [ ] `install-config.yaml` exists in `_module-installer`
+- [ ] Module metadata present (code, name, version)
+- [ ] Configuration questions defined for user input
+- [ ] Default values provided for all questions
+- [ ] Prompt text is clear and helpful
+- [ ] Result templates use proper variable substitution
+- [ ] Paths use proper variables ({project-root}, {value}, etc.)

-### Install Configuration
+### Generated Config (config.yaml in target)

- [ ] `install-module-config.yaml` exists in `_module-installer`
- [ ] Installation steps defined
- [ ] Directory creation steps present
- [ ] File copy operations specified
- [ ] Module registration included
- [ ] Post-install message defined
+- [ ] Generated during installation from install-config.yaml
+- [ ] Contains all user-provided configuration values
+- [ ] Module metadata included
+- [ ] No config.yaml should exist in source module

 ## Installation Infrastructure

--- a/bmad/bmb/workflows/create-module/checklist.md.bak
+++ b/bmad/bmb/workflows/create-module/checklist.md.bak
@@ -0,0 +1,245 @@
+# Build Module Validation Checklist
+
+## Module Identity and Metadata
+
+### Basic Information
+
+- [ ] Module code follows kebab-case convention (e.g., "rpg-toolkit")
+- [ ] Module name is descriptive and title-cased
+- [ ] Module purpose is clearly defined (1-2 sentences)
+- [ ] Target audience is identified
+- [ ] Version number follows semantic versioning (e.g., "1.0.0")
+- [ ] Author information is present
+
+### Naming Consistency
+
+- [ ] Module code used consistently throughout all files
+- [ ] No naming conflicts with existing modules
+- [ ] All paths use consistent module code references
+
+## Directory Structure
+
+### Source Directories (bmad/{module-code}/)
+
+- [ ] `/agents` directory created (even if empty)
+- [ ] `/workflows` directory created (even if empty)
+- [ ] `/tasks` directory exists (if tasks planned)
+- [ ] `/templates` directory exists (if templates used)
+- [ ] `/data` directory exists (if data files needed)
+- [ ] `config.yaml` present in module root
+- [ ] `README.md` present with documentation
+
+### Runtime Directories (bmad/{module-code}/)
+
+- [ ] `/_module-installer` directory created
+- [ ] `/data` directory for user data
+- [ ] `/agents` directory for overrides
+- [ ] `/workflows` directory for instances
+- [ ] Runtime `config.yaml` present
+
+## Component Planning
+
+### Agents
+
+- [ ] At least one agent defined or planned
+- [ ] Agent purposes are distinct and clear
+- [ ] Agent types (Simple/Expert/Module) identified
+- [ ] No significant overlap between agents
+- [ ] Primary agent is identified
+
+### Workflows
+
+- [ ] At least one workflow defined or planned
+- [ ] Workflow purposes are clear
+- [ ] Workflow types identified (Document/Action/Interactive)
+- [ ] Primary workflow is identified
+- [ ] Workflow complexity is appropriate
+
+### Tasks (if applicable)
+
+- [ ] Tasks have single, clear purposes
+- [ ] Tasks don't duplicate workflow functionality
+- [ ] Task files follow naming conventions
+
+## Configuration Files
+
+### Module config.yaml
+
+- [ ] All required fields present (name, code, version, author)
+- [ ] Component lists accurate (agents, workflows, tasks)
+- [ ] Paths use proper variables ({project-root}, etc.)
+- [ ] Output folders configured
+- [ ] Custom settings documented
+
+### Install Configuration
+
+- [ ] `install-config.yaml` exists in `_module-installer`
+- [ ] Installation steps defined
+- [ ] Directory creation steps present
+- [ ] File copy operations specified
+- [ ] Module registration included
+- [ ] Post-install message defined
+
+## Installation Infrastructure
+
+### Installer Files
+
+- [ ] Install configuration validates against schema
+- [ ] All source paths exist or are marked as templates
+- [ ] Destination paths use correct variables
+- [ ] Optional vs required steps clearly marked
+
+### installer.js (if present)
+
+- [ ] Main `installModule` function exists
+- [ ] Error handling implemented
+- [ ] Console logging for user feedback
+- [ ] Exports correct function names
+- [ ] Placeholder code replaced with actual logic (or logged as TODO)
+
+### External Assets (if any)
+
+- [ ] Asset files exist in assets directory
+- [ ] Copy destinations are valid
+- [ ] Permissions requirements documented
+
+## Documentation
+
+### README.md
+
+- [ ] Module overview section present
+- [ ] Installation instructions included
+- [ ] Component listing with descriptions
+- [ ] Quick start guide provided
+- [ ] Configuration options documented
+- [ ] At least one usage example
+- [ ] Directory structure shown
+- [ ] Author and date information
+
+### Component Documentation
+
+- [ ] Each agent has purpose documentation
+- [ ] Each workflow has description
+- [ ] Tasks are documented (if present)
+- [ ] Examples demonstrate typical usage
+
+### Development Roadmap
+
+- [ ] TODO.md or roadmap section exists
+- [ ] Planned components listed
+- [ ] Development phases identified
+- [ ] Quick commands for adding components
+
+## Integration
+
+### Cross-component References
+
+- [ ] Agents reference correct workflow paths
+- [ ] Workflows reference correct task paths
+- [ ] All internal paths use module variables
+- [ ] External dependencies declared
+
+### Module Boundaries
+
+- [ ] Module scope is well-defined
+- [ ] No feature creep into other domains
+- [ ] Clear separation from other modules
+
+## Quality Checks
+
+### Completeness
+
+- [ ] At least one functional component (not all placeholders)
+- [ ] Core functionality is implementable
+- [ ] Module provides clear value
+
+### Consistency
+
+- [ ] Formatting consistent across files
+- [ ] Variable naming follows conventions
+- [ ] Communication style appropriate for domain
+
+### Scalability
+
+- [ ] Structure supports future growth
+- [ ] Component organization is logical
+- [ ] No hard-coded limits
+
+## Testing and Validation
+
+### Structural Validation
+
+- [ ] YAML files parse without errors
+- [ ] JSON files (if any) are valid
+- [ ] XML files (if any) are well-formed
+- [ ] No syntax errors in JavaScript files
+
+### Path Validation
+
+- [ ] All referenced paths exist or are clearly marked as TODO
+- [ ] Variable substitutions are correct
+- [ ] No absolute paths (unless intentional)
+
+### Installation Testing
+
+- [ ] Installation steps can be simulated
+- [ ] No circular dependencies
+- [ ] Uninstall process defined (if complex)
+
+## Final Checks
+
+### Ready for Use
+
+- [ ] Module can be installed without errors
+- [ ] At least one component is functional
+- [ ] User can understand how to get started
+- [ ] Next steps are clear
+
+### Professional Quality
+
+- [ ] No placeholder text remains (unless marked TODO)
+- [ ] No obvious typos or grammar issues
+- [ ] Professional tone throughout
+- [ ] Contact/support information provided
+
+## Issues Found
+
+### Critical Issues
+
+<!-- List any issues that MUST be fixed before module can be used -->
+
+### Warnings
+
+<!-- List any issues that should be addressed but won't prevent basic usage -->
+
+### Improvements
+
+<!-- List any optional enhancements that would improve the module -->
+
+### Missing Components
+
+<!-- List any planned components not yet implemented -->
+
+## Module Complexity Assessment
+
+### Complexity Rating
+
+- [ ] Simple (1-2 agents, 2-3 workflows)
+- [ ] Standard (3-5 agents, 5-10 workflows)
+- [ ] Complex (5+ agents, 10+ workflows)
+
+### Readiness Level
+
+- [ ] Prototype (Basic structure, mostly placeholders)
+- [ ] Alpha (Core functionality works)
+- [ ] Beta (Most features complete, needs testing)
+- [ ] Release (Full functionality, documented)
+
+## Sign-off
+
+**Module Name:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Module Code:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Version:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Validated By:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Date:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Status:** ⬜ Pass / ⬜ Pass with Issues / ⬜ Fail
--- a/bmad/bmb/workflows/create-module/installer-templates/install-config.yaml
+++ b/bmad/bmb/workflows/create-module/installer-templates/install-config.yaml
@@ -0,0 +1,92 @@
+# {{MODULE_NAME}} Module Configuration
+# This file defines installation questions and module configuration values
+
+code: "{{MODULE_CODE}}"
+name: "{{MODULE_NAME}}"
+default_selected: "{{DEFAULT_SELECTED}}" # true if this should be selected by default
+
+# Welcome message shown during installation
+prompt:
+  - "{{WELCOME_MESSAGE_LINE_1}}"
+  - "{{WELCOME_MESSAGE_LINE_2}}"
+# Core config values are automatically inherited:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+# ============================================================================
+# CONFIGURATION FIELDS
+# ============================================================================
+#
+# Each field can be:
+# 1. INTERACTIVE (has 'prompt' - asks user during installation)
+# 2. STATIC (no 'prompt' - just uses 'result' value)
+#
+# Field structure:
+#   field_name:
+#     prompt: "Question to ask user" (optional - omit for static values)
+#     default: "default_value" (optional)
+#     result: "{value}" or "static-value"
+#     single-select: [...] (optional - for dropdown)
+#     multi-select: [...] (optional - for checkboxes)
+#
+# Special placeholders in result:
+#   {value} - replaced with user's answer
+#   {project-root} - replaced with project root path
+#   {directory_name} - replaced with project directory name
+#   {module_code} - replaced with this module's code
+# ============================================================================
+
+# EXAMPLE: Interactive text input
+# example_project_name:
+#   prompt: "What is your project name?"
+#   default: "{directory_name}"
+#   result: "{value}"
+
+# EXAMPLE: Interactive single-select dropdown
+# example_skill_level:
+#   prompt: "What is your experience level?"
+#   default: "intermediate"
+#   result: "{value}"
+#   single-select:
+#     - value: "beginner"
+#       label: "Beginner - New to this domain"
+#     - value: "intermediate"
+#       label: "Intermediate - Familiar with basics"
+#     - value: "expert"
+#       label: "Expert - Deep knowledge"
+
+# EXAMPLE: Interactive multi-select checkboxes
+# example_features:
+#   prompt:
+#     - "Which features do you want to enable?"
+#     - "(Select all that apply)"
+#   result: "{value}"
+#   multi-select:
+#     - "Feature A"
+#     - "Feature B"
+#     - "Feature C"
+
+# EXAMPLE: Interactive path input
+# example_output_path:
+#   prompt: "Where should outputs be saved?"
+#   default: "output/{{MODULE_CODE}}"
+#   result: "{project-root}/{value}"
+
+# EXAMPLE: Static value (no user prompt)
+# example_static_setting:
+#   result: "hardcoded-value"
+
+# EXAMPLE: Static path
+# module_data_path:
+#   result: "{project-root}/bmad/{{MODULE_CODE}}/data"
+
+# ============================================================================
+# YOUR MODULE CONFIGURATION FIELDS
+# ============================================================================
+# Replace examples above with your module's actual configuration needs.
+# Delete this comment block and the examples when implementing.
+# ============================================================================
+
+# TODO: INSERT {MODULE_CONFIG_FIELDS} HERE
--- a/bmad/bmb/workflows/create-module/installer-templates/install-module-config.yaml
+++ b/bmad/bmb/workflows/create-module/installer-templates/install-module-config.yaml
@@ -1,132 +0,0 @@
-# {{MODULE_NAME}} Installation Configuration Template
-# This file defines how the module gets installed into a BMAD system
-
-module_name: "{{MODULE_NAME}}"
-module_code: "{{MODULE_CODE}}"
-author: "{{AUTHOR}}"
-installation_date: "{{DATE}}"
-bmad_version_required: "6.0.0"
-
-# Module metadata
-metadata:
-  description: "{{MODULE_DESCRIPTION}}"
-  category: "{{MODULE_CATEGORY}}"
-  tags: ["{{MODULE_TAGS}}"]
-  homepage: "{{MODULE_HOMEPAGE}}"
-  license: "{{MODULE_LICENSE}}"
-
-# Pre-installation checks
-pre_install_checks:
-  - name: "Check BMAD version"
-    type: "version_check"
-    minimum: "6.0.0"
-
-  - name: "Check dependencies"
-    type: "module_check"
-    required_modules: [] # List any required modules
-
-  - name: "Check disk space"
-    type: "disk_check"
-    required_mb: 50
-
-# Installation steps
-install_steps:
-  - name: "Create module directories"
-    action: "mkdir"
-    paths:
-      - "{project-root}/bmad/{{MODULE_CODE}}"
-      - "{project-root}/bmad/{{MODULE_CODE}}/data"
-      - "{project-root}/bmad/{{MODULE_CODE}}/agents"
-      - "{project-root}/bmad/{{MODULE_CODE}}/workflows"
-      - "{project-root}/bmad/{{MODULE_CODE}}/config"
-      - "{project-root}/bmad/{{MODULE_CODE}}/logs"
-
-  - name: "Copy module configuration"
-    action: "copy"
-    files:
-      - source: "config.yaml"
-        dest: "{project-root}/bmad/{{MODULE_CODE}}/config.yaml"
-
-  - name: "Copy default data files"
-    action: "copy"
-    optional: true
-    files:
-      - source: "data/*"
-        dest: "{project-root}/bmad/{{MODULE_CODE}}/data/"
-
-  - name: "Register module in manifest"
-    action: "register"
-    manifest_path: "{project-root}/bmad/_cfg/manifest.yaml"
-    entry:
-      module: "{{MODULE_CODE}}"
-      status: "active"
-      path: "{project-root}/bmad/{{MODULE_CODE}}"
-
-  - name: "Setup agent shortcuts"
-    action: "create_shortcuts"
-    agents: "{{AGENT_LIST}}"
-
-  - name: "Initialize module database"
-    action: "exec"
-    optional: true
-    script: "installer.js"
-    function: "initDatabase"
-
-# External assets to install
-external_assets:
-  - description: "Module documentation"
-    source: "assets/docs/*"
-    dest: "{project-root}/docs/{{MODULE_CODE}}/"
-
-  - description: "Example configurations"
-    source: "assets/examples/*"
-    dest: "{project-root}/examples/{{MODULE_CODE}}/"
-    optional: true
-
-# Module configuration defaults
-default_config:
-  output_folder: "{project-root}/output/{{MODULE_CODE}}"
-  data_folder: "{project-root}/bmad/{{MODULE_CODE}}/data"
-  log_level: "info"
-  auto_save: true
-  # {{CUSTOM_CONFIG}}
-
-# Post-installation setup
-post_install:
-  - name: "Run initial setup"
-    action: "workflow"
-    workflow: "{{MODULE_CODE}}-setup"
-    optional: true
-
-  - name: "Generate sample data"
-    action: "exec"
-    script: "installer.js"
-    function: "generateSamples"
-    optional: true
-
-  - name: "Verify installation"
-    action: "test"
-    test_command: "bmad test {{MODULE_CODE}}"
-
-# Post-installation message
-post_install_message: |
-  ✅ {{MODULE_NAME}} has been installed successfully!
-
-  🚀 Quick Start:
-  1. Load the main agent: `agent {{PRIMARY_AGENT}}`
-  2. View available commands: `*help`
-  3. Run the main workflow: `workflow {{PRIMARY_WORKFLOW}}`
-
-  📚 Documentation: {project-root}/docs/{{MODULE_CODE}}/README.md
-  💡 Examples: {project-root}/examples/{{MODULE_CODE}}/
-
-  {{CUSTOM_MESSAGE}}
-
-# Uninstall configuration
-uninstall:
-  preserve_user_data: true
-  remove_paths:
-    - "{project-root}/bmad/{{MODULE_CODE}}"
-    - "{project-root}/docs/{{MODULE_CODE}}"
-  backup_before_remove: true
-  unregister_from_manifest: true
--- a/bmad/bmb/workflows/create-module/installer-templates/installer.js
+++ b/bmad/bmb/workflows/create-module/installer-templates/installer.js
@@ -178,7 +178,7 @@ async function initDatabase(/* config */) {
  console.log('   Initializing database...');

  // TODO: Add database initialization
-  // This function can be called from install-module-config.yaml
+  // This function can be called from install-config.yaml

  console.log('   ✓ Database initialized');
 }
--- a/bmad/bmb/workflows/create-module/installer-templates/installer.js.bak
+++ b/bmad/bmb/workflows/create-module/installer-templates/installer.js.bak
@@ -0,0 +1,231 @@
+/* eslint-disable unicorn/prefer-module, unicorn/prefer-node-protocol */
+/**
+ * {{MODULE_NAME}} Module Installer
+ * Custom installation logic for complex module setup
+ *
+ * This is a template - replace {{VARIABLES}} with actual values
+ */
+
+// const fs = require('fs'); // Uncomment when implementing file operations
+const path = require('path');
+
+/**
+ * Main installation function
+ * Called by BMAD installer when processing the module
+ */
+async function installModule(config) {
+  console.log('🚀 Installing {{MODULE_NAME}} module...');
+  console.log(`   Version: ${config.version}`);
+  console.log(`   Module Code: ${config.module_code}`);
+
+  try {
+    // Step 1: Validate environment
+    await validateEnvironment(config);
+
+    // Step 2: Setup custom configurations
+    await setupConfigurations(config);
+
+    // Step 3: Initialize module-specific features
+    await initializeFeatures(config);
+
+    // Step 4: Run post-install tasks
+    await runPostInstallTasks(config);
+
+    console.log('✅ {{MODULE_NAME}} module installed successfully!');
+    return {
+      success: true,
+      message: 'Module installed and configured',
+    };
+  } catch (error) {
+    console.error('❌ Installation failed:', error.message);
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Validate that the environment meets module requirements
+ */
+async function validateEnvironment(config) {
+  console.log('   Validating environment...');
+
+  // TODO: Add environment checks
+  // Examples:
+  // - Check for required tools/binaries
+  // - Verify permissions
+  // - Check network connectivity
+  // - Validate API keys
+
+  // Placeholder validation
+  if (!config.project_root) {
+    throw new Error('Project root not defined');
+  }
+
+  console.log('   ✓ Environment validated');
+}
+
+/**
+ * Setup module-specific configurations
+ */
+async function setupConfigurations(config) {
+  console.log('   Setting up configurations...');
+
+  // TODO: Add configuration setup
+  // Examples:
+  // - Create config files
+  // - Setup environment variables
+  // - Configure external services
+  // - Initialize settings
+
+  // Placeholder configuration
+  const configPath = path.join(config.project_root, 'bmad', config.module_code, 'config.json');
+
+  // Example of module config that would be created
+  // const moduleConfig = {
+  //   installed: new Date().toISOString(),
+  //   settings: {
+  //     // Add default settings
+  //   }
+  // };
+
+  // Note: This is a placeholder - actual implementation would write the file
+  console.log(`   ✓ Would create config at: ${configPath}`);
+  console.log('   ✓ Configurations complete');
+}
+
+/**
+ * Initialize module-specific features
+ */
+async function initializeFeatures(config) {
+  console.log('   Initializing features...');
+
+  // TODO: Add feature initialization
+  // Examples:
+  // - Create database schemas
+  // - Setup cron jobs
+  // - Initialize caches
+  // - Register webhooks
+  // - Setup file watchers
+
+  // Module-specific initialization based on type
+  switch (config.module_category) {
+    case 'data': {
+      await initializeDataFeatures(config);
+      break;
+    }
+    case 'automation': {
+      await initializeAutomationFeatures(config);
+      break;
+    }
+    case 'integration': {
+      await initializeIntegrationFeatures(config);
+      break;
+    }
+    default: {
+      console.log('   - Using standard initialization');
+    }
+  }
+
+  console.log('   ✓ Features initialized');
+}
+
+/**
+ * Initialize data-related features
+ */
+async function initializeDataFeatures(/* config */) {
+  console.log('   - Setting up data storage...');
+  // TODO: Setup databases, data folders, etc.
+}
+
+/**
+ * Initialize automation features
+ */
+async function initializeAutomationFeatures(/* config */) {
+  console.log('   - Setting up automation hooks...');
+  // TODO: Setup triggers, watchers, schedulers
+}
+
+/**
+ * Initialize integration features
+ */
+async function initializeIntegrationFeatures(/* config */) {
+  console.log('   - Setting up integrations...');
+  // TODO: Configure APIs, webhooks, external services
+}
+
+/**
+ * Run post-installation tasks
+ */
+async function runPostInstallTasks(/* config */) {
+  console.log('   Running post-install tasks...');
+
+  // TODO: Add post-install tasks
+  // Examples:
+  // - Generate sample data
+  // - Run initial workflows
+  // - Send notifications
+  // - Update registries
+
+  console.log('   ✓ Post-install tasks complete');
+}
+
+/**
+ * Initialize database for the module (optional)
+ */
+async function initDatabase(/* config */) {
+  console.log('   Initializing database...');
+
+  // TODO: Add database initialization
+  // This function can be called from install-config.yaml
+
+  console.log('   ✓ Database initialized');
+}
+
+/**
+ * Generate sample data for the module (optional)
+ */
+async function generateSamples(config) {
+  console.log('   Generating sample data...');
+
+  // TODO: Create sample files, data, configurations
+  // This helps users understand how to use the module
+
+  const samplesPath = path.join(config.project_root, 'examples', config.module_code);
+
+  console.log(`   - Would create samples at: ${samplesPath}`);
+  console.log('   ✓ Samples generated');
+}
+
+/**
+ * Uninstall the module (cleanup)
+ */
+async function uninstallModule(/* config */) {
+  console.log('🗑️  Uninstalling {{MODULE_NAME}} module...');
+
+  try {
+    // TODO: Add cleanup logic
+    // - Remove configurations
+    // - Clean up databases
+    // - Unregister services
+    // - Backup user data
+
+    console.log('✅ Module uninstalled successfully');
+    return { success: true };
+  } catch (error) {
+    console.error('❌ Uninstall failed:', error.message);
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+// Export functions for BMAD installer
+module.exports = {
+  installModule,
+  initDatabase,
+  generateSamples,
+  uninstallModule,
+};
--- a/bmad/bmb/workflows/create-module/instructions.md
+++ b/bmad/bmb/workflows/create-module/instructions.md
@@ -10,14 +10,16 @@
 <step n="-1" goal="Optional brainstorming for module ideas" optional="true">
 <ask>Do you want to brainstorm module ideas first? [y/n]</ask>

-<check>If yes:</check>
-<action>Invoke brainstorming workflow: {brainstorming_workflow}</action>
-<action>Pass context data: {brainstorming_context}</action>
-<action>Wait for brainstorming session completion</action>
-<action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps</action>
+<check if="yes">
+  <action>Invoke brainstorming workflow: {brainstorming_workflow}</action>
+  <action>Pass context data: {brainstorming_context}</action>
+  <action>Wait for brainstorming session completion</action>
+  <action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps</action>
+</check>

-<check>If no:</check>
-<action>Proceed directly to Step 0</action>
+<check if="no">
+  <action>Proceed directly to Step 0</action>
+</check>

 <template-output>brainstorming_results</template-output>
 </step>
@@ -25,17 +27,20 @@
 <step n="0" goal="Check for module brief" optional="true">
 <ask>Do you have a module brief or should we create one? [have/create/skip]</ask>

-<check>If create:</check>
-<action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
-<action>Wait for module brief completion</action>
-<action>Load the module brief to use as blueprint</action>
+<check if="create">
+  <action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
+  <action>Wait for module brief completion</action>
+  <action>Load the module brief to use as blueprint</action>
+</check>

-<check>If have:</check>
-<ask>Provide path to module brief document</ask>
-<action>Load the module brief and use it to pre-populate all planning sections</action>
+<check if="have">
+  <ask>Provide path to module brief document</ask>
+  <action>Load the module brief and use it to pre-populate all planning sections</action>
+</check>

-<check>If skip:</check>
-<action>Proceed directly to Step 1</action>
+<check if="skip">
+  <action>Proceed directly to Step 1</action>
+</check>

 <template-output>module_brief</template-output>
 </step>
@@ -113,8 +118,7 @@
 **Tasks Planning (optional):**
 <ask>Any special tasks that don't warrant full workflows?</ask>

-<check>If tasks needed:</check>
-<action>For each task, capture name, purpose, and whether standalone or supporting</action>
+<action if="tasks needed">For each task, capture name, purpose, and whether standalone or supporting</action>

 <template-output>module_components</template-output>
 </step>
@@ -154,88 +158,86 @@

 ```
 {{module_code}}/
-├── agents/           # Agent definitions
-├── workflows/        # Workflow folders
-├── tasks/           # Task files (if any)
-├── templates/       # Shared templates
-├── data/           # Module data files
-├── config.yaml     # Module configuration
-└── README.md       # Module documentation
+├── agents/                    # Agent definitions
+├── workflows/                 # Workflow folders
+├── tasks/                     # Task files (if any)
+├── templates/                 # Shared templates
+├── data/                      # Module data files
+├── _module-installer/         # Installation configuration
+│   └── install-config.yaml   # Configuration questions (config.yaml generated at install time)
+└── README.md                  # Module documentation
 ```

 <action>Create installer directory:</action>

+**INSTALLED MODULE STRUCTURE** (generated in target project after installation):
+
+```
+{{module_code}}/
+├── agents/                    # Compiled agents
+├── workflows/                 # Workflow instances
+├── config.yaml               # Generated from install-config.yaml during installation
+└── data/                     # User data directory
+```
+
+**SOURCE MODULE** (\_module-installer is for installation only, not copied to target):
+
 ```
 {{module_code}}/
 ├── _module-installer/
-│   ├── install-module-config.yaml
-│   ├── installer.js (optional)
-│   └── assets/     # Files to copy during install
-├── config.yaml     # Runtime configuration
-├── agents/         # Agent configs (optional)
-├── workflows/      # Workflow instances
-└── data/          # User data directory
+│   ├── install-config.yaml   # Configuration questions
+│   ├── installer.js          # Optional custom installation logic
+│   └── assets/               # Files to copy during install
 ```

 <template-output>directory_structure</template-output>
 </step>

-<step n="4" goal="Generate module configuration">
-Create the main module config.yaml:
+<step n="4" goal="Plan module configuration fields">
+<action>Based on the module purpose and components, determine what configuration settings the module needs</action>

-```yaml
-# {{module_name}} Module Configuration
-module_name: {{module_name}}
-module_code: {{module_code}}
-author: {{user_name}}
-description: {{module_purpose}}
+**Configuration Field Planning:**

-# Module paths
-module_root: "{project-root}/bmad/{{module_code}}"
-installer_path: "{project-root}/bmad/{{module_code}}"
+<ask>Does your module need any user-configurable settings during installation?</ask>

-# Component counts
-agents:
-  count: {{agent_count}}
-  list: {{agent_list}}
+**Common configuration patterns:**

-workflows:
-  count: {{workflow_count}}
-  list: {{workflow_list}}
+- Output/data paths (where module saves files)
+- Feature toggles (enable/disable functionality)
+- Integration settings (API keys, external services)
+- Behavior preferences (automation level, detail level)
+- User skill level or experience settings

-tasks:
-  count: {{task_count}}
-  list: {{task_list}}
+<action>For each configuration field needed, determine:</action>

-# Module-specific settings
-{{custom_settings}}
+1. Field name (snake_case)
+2. Whether it's INTERACTIVE (asks user) or STATIC (hardcoded)
+3. Prompt text (if interactive)
+4. Default value
+5. Type: text input, single-select, or multi-select
+6. Result template (how the value gets stored)

-# Output configuration
-output_folder: "{project-root}/docs/{{module_code}}"
-data_folder: "{{determined_module_path}}/data"
-```
+<action>Store planned configuration fields for installer generation in step 7</action>

-<critical>Save location:</critical>
-
- Save to {{module_path}}/config.yaml
-
-<template-output>module_config</template-output>
+<template-output>module_config_fields</template-output>
 </step>

 <step n="5" goal="Create first agent" optional="true">
 <ask>Create your first agent now? [yes/no]</ask>

-<check>If yes:</check>
-<action>Invoke agent builder workflow: {agent_builder}</action>
-<action>Pass module_components as context input</action>
-<action>Guide them to create the primary agent for the module</action>
+<check if="yes">
+  <action>Invoke agent builder workflow: {agent_builder}</action>
+  <action>Pass module_components as context input</action>
+  <action>Guide them to create the primary agent for the module</action>

 <critical>Save to module's agents folder:</critical>

 - Save to {{module_path}}/agents/
+  </check>

-<check>If no:</check>
-<action>Create placeholder file in agents folder with TODO notes including agent name, purpose, and type</action>
+<check if="no">
+  <action>Create placeholder file in agents folder with TODO notes including agent name, purpose, and type</action>
+</check>

 <template-output>first_agent</template-output>
 </step>
@@ -243,88 +245,141 @@ data_folder: "{{determined_module_path}}/data"
 <step n="6" goal="Create first workflow" optional="true">
 <ask>Create your first workflow now? [yes/no]</ask>

-<check>If yes:</check>
-<action>Invoke workflow builder: {workflow_builder}</action>
-<action>Pass module_components as context input</action>
-<action>Guide them to create the primary workflow</action>
+<check if="yes">
+  <action>Invoke workflow builder: {workflow_builder}</action>
+  <action>Pass module_components as context input</action>
+  <action>Guide them to create the primary workflow</action>

 <critical>Save to module's workflows folder:</critical>

 - Save to {{module_path}}/workflows/
+  </check>

-<check>If no:</check>
-<action>Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow</action>
+<check if="no">
+  <action>Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow</action>
+</check>

 <template-output>first_workflow</template-output>
 </step>

 <step n="7" goal="Setup module installer">
-<action>Load installer templates from: {installer_templates}</action>
+<action>Load installer template from: {installer_templates}/install-config.yaml</action>

-Create install-module-config.yaml:
+<critical>IMPORTANT: Create install-config.yaml NOT install-config.yaml</critical>
+<critical>This is the STANDARD format that BMAD installer uses</critical>
+
+Create \_module-installer/install-config.yaml:

 ```yaml
-# {{module_name}} Installation Configuration
-module_name: { { module_name } }
-module_code: { { module_code } }
-installation_date: { { date } }
+# {{module_name}} Module Configuration
+# This file defines installation questions and module configuration values

-# Installation steps
-install_steps:
-  - name: 'Create directories'
-    action: 'mkdir'
-    paths:
-      - '{project-root}/bmad/{{module_code}}'
-      - '{project-root}/bmad/{{module_code}}/data'
-      - '{project-root}/bmad/{{module_code}}/agents'
+code: {{module_code}}
+name: "{{module_name}}"
+default_selected: false # Set to true if this should be selected by default

-  - name: 'Copy configuration'
-    action: 'copy'
-    source: '{installer_path}/config.yaml'
-    dest: '{project-root}/bmad/{{module_code}}/config.yaml'
+# Welcome message shown during installation
+prompt:
+  - "Thank you for choosing {{module_name}}!"
+  - "{{brief_module_description}}"

-  - name: 'Register module'
-    action: 'register'
-    manifest: '{project-root}/bmad/_cfg/manifest.yaml'
+# Core config values are automatically inherited:
+## user_name
+## communication_language
+## document_output_language
+## output_folder

-# External assets (if any)
-external_assets:
-  - description: '{{asset_description}}'
-    source: 'assets/{{filename}}'
-    dest: '{{destination_path}}'
+# ============================================================================
+# CONFIGURATION FIELDS (from step 4 planning)
+# ============================================================================
+# Each field can be:
+# 1. INTERACTIVE (has 'prompt' - asks user during installation)
+# 2. STATIC (no 'prompt' - just uses 'result' value)
+# ============================================================================

-# Post-install message
-post_install_message: |
-  {{module_name}} has been installed successfully!
+# EXAMPLE Interactive text input:
+# output_path:
+#   prompt: "Where should {{module_code}} save outputs?"
+#   default: "output/{{module_code}}"
+#   result: "{project-root}/{value}"

-  To get started:
-  1. Load any {{module_code}} agent
-  2. Use *help to see available commands
-  3. Check README.md for full documentation
+# EXAMPLE Interactive single-select:
+# detail_level:
+#   prompt: "How detailed should outputs be?"
+#   default: "standard"
+#   result: "{value}"
+#   single-select:
+#     - value: "minimal"
+#       label: "Minimal - Brief summaries only"
+#     - value: "standard"
+#       label: "Standard - Balanced detail"
+#     - value: "detailed"
+#       label: "Detailed - Comprehensive information"
+
+# EXAMPLE Static value:
+# module_version:
+#   result: "1.0.0"
+
+# EXAMPLE Static path:
+# data_path:
+#   result: "{project-root}/bmad/{{module_code}}/data"
+
+{{generated_config_fields_from_step_4}}
 ```

-Create installer.js stub (optional):
+<critical>Save location:</critical>

-```javascript
-// {{module_name}} Module Installer
-// This is a placeholder for complex installation logic
+- Save to {{module_path}}/\_module-installer/install-config.yaml

-function installModule(config) {
-  console.log('Installing {{module_name}} module...');
+<ask>Does your module need custom installation logic (database setup, API registration, etc.)?</ask>

-  // TODO: Add any complex installation logic here
+<check if="yes, create installer.js">
+  ```javascript
+  // {{module_name}} Module Installer
+  // Custom installation logic
+
+/\*\*
+
+- Module installation hook
+- Called after files are copied but before IDE configuration
+-
+- @param {Object} options - Installation options
+- @param {string} options.projectRoot - Project root directory
+- @param {Object} options.config - Module configuration from install-config.yaml
+- @param {Array} options.installedIDEs - List of IDE codes being configured
+- @param {Object} options.logger - Logger instance (log, warn, error methods)
+- @returns {boolean} - true if successful, false to abort installation
+  \*/
+  async function install(options) {
+  const { projectRoot, config, installedIDEs, logger } = options;
+
+  logger.log('Running {{module_name}} custom installer...');
+
+  // TODO: Add custom installation logic here
  // Examples:
-  // - Database setup
-  // - API key configuration
-  // - External service registration
-  // - File system preparation
+  // - Create database tables
+  // - Download external assets
+  // - Configure API connections
+  // - Initialize data files
+  // - Set up webhooks or integrations

-  console.log('{{module_name}} module installed successfully!');
+  logger.log('{{module_name}} custom installation complete!');
  return true;
+
 }

-module.exports = { installModule };
-```
+module.exports = { install };
+
+`````
+
+<critical>Save location:</critical>
+
+- Save to {{module_path}}/\_module-installer/installer.js
+</check>
+
+<check if="no">
+<action>Skip installer.js creation - the standard installer will handle everything</action>
+</check>

 <template-output>installer_config</template-output>
 </step>
@@ -346,7 +401,8 @@ This module provides:

 ```bash
 bmad install {{module_code}}
-```
+`````
+
 ````

 ## Components
@@ -428,22 +484,26 @@ Created by {{user_name}} on {{date}}
 Create a development roadmap for remaining components:

 **TODO.md file:**
+
 ```markdown
 # {{module_name}} Development Roadmap

 ## Phase 1: Core Components
+
 {{phase1_tasks}}

 ## Phase 2: Enhanced Features
+
 {{phase2_tasks}}

 ## Phase 3: Polish and Integration
+
 {{phase3_tasks}}

 ## Quick Commands

 Create new agent:
-````
+```

 workflow create-agent

--- a/bmad/bmb/workflows/create-module/instructions.md.bak
+++ b/bmad/bmb/workflows/create-module/instructions.md.bak
@@ -0,0 +1,521 @@
+# Build Module - Interactive Module Builder Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/create-module/workflow.yaml</critical>
+<critical>Study existing modules in: {project-root}/bmad/ for patterns</critical>
+<critical>Communicate in {communication_language} throughout the module creation process</critical>
+
+<workflow>
+
+<step n="-1" goal="Optional brainstorming for module ideas" optional="true">
+<ask>Do you want to brainstorm module ideas first? [y/n]</ask>
+
+<check>If yes:</check>
+<action>Invoke brainstorming workflow: {brainstorming_workflow}</action>
+<action>Pass context data: {brainstorming_context}</action>
+<action>Wait for brainstorming session completion</action>
+<action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps</action>
+
+<check>If no:</check>
+<action>Proceed directly to Step 0</action>
+
+<template-output>brainstorming_results</template-output>
+</step>
+
+<step n="0" goal="Check for module brief" optional="true">
+<ask>Do you have a module brief or should we create one? [have/create/skip]</ask>
+
+<check>If create:</check>
+<action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
+<action>Wait for module brief completion</action>
+<action>Load the module brief to use as blueprint</action>
+
+<check>If have:</check>
+<ask>Provide path to module brief document</ask>
+<action>Load the module brief and use it to pre-populate all planning sections</action>
+
+<check>If skip:</check>
+<action>Proceed directly to Step 1</action>
+
+<template-output>module_brief</template-output>
+</step>
+
+<step n="1" goal="Define module concept and scope">
+<critical>Load and study the complete module structure guide</critical>
+<action>Load module structure guide: {module_structure_guide}</action>
+<action>Understand module types (Simple/Standard/Complex)</action>
+<action>Review directory structures and component guidelines</action>
+<action>Study the installation infrastructure patterns</action>
+
+<action>If brainstorming or module brief was completed, reference those results to guide the conversation</action>
+
+<action>Guide user to articulate their module's vision, exploring its purpose, what it will help with, and who will use it</action>
+
+<action>Based on their description, intelligently propose module details:</action>
+
+**Module Identity Development:**
+
+1. **Module name** - Extract from their description with proper title case
+2. **Module code** - Generate kebab-case from name following patterns:
+   - Multi-word descriptive names → shortened kebab-case
+   - Domain-specific terms → recognizable abbreviations
+   - Present suggested code and confirm it works for paths like bmad/{{code}}/agents/
+3. **Module purpose** - Refine their description into 1-2 clear sentences
+4. **Target audience** - Infer from context or ask if unclear
+
+**Module Theme Reference Categories:**
+
+- Domain-Specific (Legal, Medical, Finance, Education)
+- Creative (RPG/Gaming, Story Writing, Music Production)
+- Technical (DevOps, Testing, Architecture, Security)
+- Business (Project Management, Marketing, Sales)
+- Personal (Journaling, Learning, Productivity)
+
+<critical>Determine output location:</critical>
+
+- Module will be created at {installer_output_folder}
+
+<action>Store module identity for scaffolding</action>
+
+<template-output>module_identity</template-output>
+</step>
+
+<step n="2" goal="Plan module components">
+<action>Based on the module purpose, intelligently propose an initial component architecture</action>
+
+**Agents Planning:**
+
+<action>Suggest agents based on module purpose, considering agent types (Simple/Expert/Module) appropriate to each role</action>
+
+**Example Agent Patterns by Domain:**
+
+- Data/Analytics: Analyst, Designer, Builder roles
+- Gaming/Creative: Game Master, Generator, Storytelling roles
+- Team/Business: Manager, Facilitator, Documentation roles
+
+<action>Present suggested agent list with types, explaining we can start with core ones and add others later</action>
+<action>Confirm which agents resonate with their vision</action>
+
+**Workflows Planning:**
+
+<action>Intelligently suggest workflows that complement the proposed agents</action>
+
+**Example Workflow Patterns by Domain:**
+
+- Data/Analytics: analyze-dataset, create-dashboard, generate-report
+- Gaming/Creative: session-prep, generate-encounter, world-building
+- Team/Business: planning, facilitation, documentation workflows
+
+<action>For each workflow, note whether it should be Document, Action, or Interactive type</action>
+<action>Confirm which workflows are most important to start with</action>
+<action>Determine which to create now vs placeholder</action>
+
+**Tasks Planning (optional):**
+<ask>Any special tasks that don't warrant full workflows?</ask>
+
+<check>If tasks needed:</check>
+<action>For each task, capture name, purpose, and whether standalone or supporting</action>
+
+<template-output>module_components</template-output>
+</step>
+
+<step n="2b" goal="Determine module complexity">
+<action>Based on components, intelligently determine module type using criteria:</action>
+
+**Simple Module Criteria:**
+
+- 1-2 agents, all Simple type
+- 1-3 workflows
+- No complex integrations
+
+**Standard Module Criteria:**
+
+- 2-4 agents with mixed types
+- 3-8 workflows
+- Some shared resources
+
+**Complex Module Criteria:**
+
+- 4+ agents or multiple Module-type agents
+- 8+ workflows
+- Complex interdependencies
+- External integrations
+
+<action>Present determined module type with explanation of what structure will be set up</action>
+
+<template-output>module_type</template-output>
+</step>
+
+<step n="3" goal="Create module directory structure">
+<critical>Use module path determined in Step 1:</critical>
+- The module base path is {{module_path}}
+
+<action>Create base module directories at the determined path:</action>
+
+```
+{{module_code}}/
+├── agents/           # Agent definitions
+├── workflows/        # Workflow folders
+├── tasks/           # Task files (if any)
+├── templates/       # Shared templates
+├── data/           # Module data files
+├── config.yaml     # Module configuration
+└── README.md       # Module documentation
+```
+
+<action>Create installer directory:</action>
+
+```
+{{module_code}}/
+├── _module-installer/
+│   ├── install-config.yaml
+│   ├── installer.js (optional)
+│   └── assets/     # Files to copy during install
+├── config.yaml     # Runtime configuration
+├── agents/         # Agent configs (optional)
+├── workflows/      # Workflow instances
+└── data/          # User data directory
+```
+
+<template-output>directory_structure</template-output>
+</step>
+
+<step n="4" goal="Generate module configuration">
+Create the main module config.yaml:
+
+```yaml
+# {{module_name}} Module Configuration
+module_name: {{module_name}}
+module_code: {{module_code}}
+author: {{user_name}}
+description: {{module_purpose}}
+
+# Module paths
+module_root: "{project-root}/bmad/{{module_code}}"
+installer_path: "{project-root}/bmad/{{module_code}}"
+
+# Component counts
+agents:
+  count: {{agent_count}}
+  list: {{agent_list}}
+
+workflows:
+  count: {{workflow_count}}
+  list: {{workflow_list}}
+
+tasks:
+  count: {{task_count}}
+  list: {{task_list}}
+
+# Module-specific settings
+{{custom_settings}}
+
+# Output configuration
+output_folder: "{project-root}/docs/{{module_code}}"
+data_folder: "{{determined_module_path}}/data"
+```
+
+<critical>Save location:</critical>
+
+- Save to {{module_path}}/config.yaml
+
+<template-output>module_config</template-output>
+</step>
+
+<step n="5" goal="Create first agent" optional="true">
+<ask>Create your first agent now? [yes/no]</ask>
+
+<check>If yes:</check>
+<action>Invoke agent builder workflow: {agent_builder}</action>
+<action>Pass module_components as context input</action>
+<action>Guide them to create the primary agent for the module</action>
+
+<critical>Save to module's agents folder:</critical>
+
+- Save to {{module_path}}/agents/
+
+<check>If no:</check>
+<action>Create placeholder file in agents folder with TODO notes including agent name, purpose, and type</action>
+
+<template-output>first_agent</template-output>
+</step>
+
+<step n="6" goal="Create first workflow" optional="true">
+<ask>Create your first workflow now? [yes/no]</ask>
+
+<check>If yes:</check>
+<action>Invoke workflow builder: {workflow_builder}</action>
+<action>Pass module_components as context input</action>
+<action>Guide them to create the primary workflow</action>
+
+<critical>Save to module's workflows folder:</critical>
+
+- Save to {{module_path}}/workflows/
+
+<check>If no:</check>
+<action>Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow</action>
+
+<template-output>first_workflow</template-output>
+</step>
+
+<step n="7" goal="Setup module installer">
+<action>Load installer templates from: {installer_templates}</action>
+
+Create install-config.yaml:
+
+```yaml
+# {{module_name}} Installation Configuration
+module_name: { { module_name } }
+module_code: { { module_code } }
+installation_date: { { date } }
+
+# Installation steps
+install_steps:
+  - name: 'Create directories'
+    action: 'mkdir'
+    paths:
+      - '{project-root}/bmad/{{module_code}}'
+      - '{project-root}/bmad/{{module_code}}/data'
+      - '{project-root}/bmad/{{module_code}}/agents'
+
+  - name: 'Copy configuration'
+    action: 'copy'
+    source: '{installer_path}/config.yaml'
+    dest: '{project-root}/bmad/{{module_code}}/config.yaml'
+
+  - name: 'Register module'
+    action: 'register'
+    manifest: '{project-root}/bmad/_cfg/manifest.yaml'
+
+# External assets (if any)
+external_assets:
+  - description: '{{asset_description}}'
+    source: 'assets/{{filename}}'
+    dest: '{{destination_path}}'
+
+# Post-install message
+post_install_message: |
+  {{module_name}} has been installed successfully!
+
+  To get started:
+  1. Load any {{module_code}} agent
+  2. Use *help to see available commands
+  3. Check README.md for full documentation
+```
+
+Create installer.js stub (optional):
+
+```javascript
+// {{module_name}} Module Installer
+// This is a placeholder for complex installation logic
+
+function installModule(config) {
+  console.log('Installing {{module_name}} module...');
+
+  // TODO: Add any complex installation logic here
+  // Examples:
+  // - Database setup
+  // - API key configuration
+  // - External service registration
+  // - File system preparation
+
+  console.log('{{module_name}} module installed successfully!');
+  return true;
+}
+
+module.exports = { installModule };
+```
+
+<template-output>installer_config</template-output>
+</step>
+
+<step n="8" goal="Create module documentation">
+Generate comprehensive README.md:
+
+````markdown
+# {{module_name}}
+
+{{module_purpose}}
+
+## Overview
+
+This module provides:
+{{component_summary}}
+
+## Installation
+
+```bash
+bmad install {{module_code}}
+```
+````
+
+## Components
+
+### Agents ({{agent_count}})
+
+{{agent_documentation}}
+
+### Workflows ({{workflow_count}})
+
+{{workflow_documentation}}
+
+### Tasks ({{task_count}})
+
+{{task_documentation}}
+
+## Quick Start
+
+1. **Load the main agent:**
+
+   ```
+   agent {{primary_agent}}
+   ```
+
+2. **View available commands:**
+
+   ```
+   *help
+   ```
+
+3. **Run the main workflow:**
+   ```
+   workflow {{primary_workflow}}
+   ```
+
+## Module Structure
+
+```
+{{directory_tree}}
+```
+
+## Configuration
+
+The module can be configured in `bmad/{{module_code}}/config.yaml`
+
+Key settings:
+{{configuration_options}}
+
+## Examples
+
+### Example 1: {{example_use_case}}
+
+{{example_walkthrough}}
+
+## Development Roadmap
+
+- [ ] {{roadmap_item_1}}
+- [ ] {{roadmap_item_2}}
+- [ ] {{roadmap_item_3}}
+
+## Contributing
+
+To extend this module:
+
+1. Add new agents using `create-agent` workflow
+2. Add new workflows using `create-workflow` workflow
+3. Submit improvements via pull request
+
+## Author
+
+Created by {{user_name}} on {{date}}
+
+````
+
+<template-output>module_readme</template-output>
+</step>
+
+<step n="9" goal="Generate component roadmap">
+Create a development roadmap for remaining components:
+
+**TODO.md file:**
+```markdown
+# {{module_name}} Development Roadmap
+
+## Phase 1: Core Components
+{{phase1_tasks}}
+
+## Phase 2: Enhanced Features
+{{phase2_tasks}}
+
+## Phase 3: Polish and Integration
+{{phase3_tasks}}
+
+## Quick Commands
+
+Create new agent:
+````
+
+workflow create-agent
+
+```
+
+Create new workflow:
+```
+
+workflow create-workflow
+
+```
+
+## Notes
+{{development_notes}}
+```
+
+Ask if user wants to:
+
+1. Continue building more components now
+2. Save roadmap for later development
+3. Test what's been built so far
+
+<template-output>development_roadmap</template-output>
+</step>
+
+<step n="10" goal="Validate and finalize module">
+<action>Run validation checks:</action>
+
+**Structure validation:**
+
+- All required directories created
+- Config files properly formatted
+- Installer configuration valid
+
+**Component validation:**
+
+- At least one agent or workflow exists (or planned)
+- All references use correct paths
+- Module code consistent throughout
+
+**Documentation validation:**
+
+- README.md complete
+- Installation instructions clear
+- Examples provided
+
+<action>Present summary to {user_name}:</action>
+
+- Module name and code
+- Location path
+- Agent count (created vs planned)
+- Workflow count (created vs planned)
+- Task count
+- Installer status
+
+<action>Provide next steps guidance:</action>
+
+1. Complete remaining components using roadmap
+2. Run the BMAD Method installer to this project location
+3. Select 'Compile Agents' option after confirming folder
+4. Module will be compiled and available for use
+5. Test with bmad install command
+6. Share or integrate with existing system
+
+<ask>Would you like to:
+
+- Create another component now?
+- Test the module installation?
+- Exit and continue later?
+  </ask>
+
+<template-output>module_summary</template-output>
+</step>
+
+</workflow>
--- a/bmad/bmb/workflows/create-module/module-structure.md
+++ b/bmad/bmb/workflows/create-module/module-structure.md
@@ -9,26 +9,30 @@ A BMAD module is a self-contained package of agents, workflows, tasks, and resou
 ### Core Structure

 ```
-project-root/
-├── bmad/{module-code}/     # Source code
-│   ├── agents/                    # Agent definitions
-│   ├── workflows/                 # Workflow folders
-│   ├── tasks/                     # Task files
-│   ├── templates/                 # Shared templates
-│   ├── data/                      # Static data
-│   ├── config.yaml                # Module config
-│   └── README.md                  # Documentation
-│
-└── bmad/{module-code}/            # Runtime instance
-    ├── _module-installer/         # Installation files
-    │   ├── install-module-config.yaml
-    │   ├── installer.js          # Optional
-    │   └── assets/               # Install assets
-    ├── config.yaml               # User config
-    ├── agents/                   # Agent overrides
-    ├── workflows/                # Workflow instances
-    └── data/                     # User data
+# SOURCE MODULE (in BMAD-METHOD project)
+src/modules/{module-code}/
+├── agents/                        # Agent definitions (.agent.yaml)
+├── workflows/                     # Workflow folders
+├── tasks/                         # Task files
+├── tools/                         # Tool files
+├── templates/                     # Shared templates
+├── data/                          # Static data
+├── _module-installer/             # Installation configuration
+│   ├── install-config.yaml  # Installation questions & config
+│   ├── installer.js              # Optional custom install logic
+│   └── assets/                   # Files to copy during install
+└── README.md                      # Module documentation

+# INSTALLED MODULE (in target project)
+{project-root}/bmad/{module-code}/
+├── agents/                        # Compiled agent files (.md)
+├── workflows/                     # Workflow instances
+├── tasks/                         # Task files
+├── tools/                         # Tool files
+├── templates/                     # Templates
+├── data/                          # Module data
+├── config.yaml                    # Generated from install-config.yaml
+└── README.md                      # Module documentation
 ```

 ## Module Types by Complexity
@@ -134,41 +138,93 @@ Tasks should be used for:

 ## Installation Infrastructure

-### Required: install-module-config.yaml
+### Required: \_module-installer/install-config.yaml
+
+This file defines both installation questions AND static configuration values:

 ```yaml
-module_name: 'Module Name'
-module_code: 'module-code'
+# Module metadata
+code: module-code
+name: 'Module Name'
+default_selected: false

-install_steps:
-  - name: 'Create directories'
-    action: 'mkdir'
-    paths: [...]
+# Welcome message during installation
+prompt:
+  - 'Welcome to Module Name!'
+  - 'Brief description here'

-  - name: 'Copy files'
-    action: 'copy'
-    mappings: [...]
+# Core values automatically inherited from installer:
+## user_name
+## communication_language
+## document_output_language
+## output_folder

-  - name: 'Register module'
-    action: 'register'
+# INTERACTIVE fields (ask user during install)
+output_location:
+  prompt: 'Where should module outputs be saved?'
+  default: 'output/module-code'
+  result: '{project-root}/{value}'
+
+feature_level:
+  prompt: 'Which feature set?'
+  default: 'standard'
+  result: '{value}'
+  single-select:
+    - value: 'basic'
+      label: 'Basic - Core features only'
+    - value: 'standard'
+      label: 'Standard - Recommended features'
+    - value: 'advanced'
+      label: 'Advanced - All features'
+
+# STATIC fields (no prompt, just hardcoded values)
+module_version:
+  result: '1.0.0'
+
+data_path:
+  result: '{project-root}/bmad/module-code/data'
 ```

-### Optional: installer.js
+**Key Points:**

-For complex installations requiring:
+- File is named `install-config.yaml` (NOT install-config.yaml)
+- Supports both interactive prompts and static values
+- `result` field uses placeholders: `{value}`, `{project-root}`, `{directory_name}`
+- Installer generates final `config.yaml` from this template

- Database setup
- API configuration
- System integration
- Permission management
+### Optional: \_module-installer/installer.js

-### Optional: External Assets
+For complex installations requiring custom logic:

-Files that get copied outside the module:
+```javascript
+/**
+ * @param {Object} options - Installation options
+ * @param {string} options.projectRoot - Target project directory
+ * @param {Object} options.config - Config from install-config.yaml
+ * @param {Array} options.installedIDEs - IDEs being configured
+ * @param {Object} options.logger - Logger (log, warn, error)
+ * @returns {boolean} - true if successful
+ */
+async function install(options) {
+  // Custom installation logic here
+  // - Database setup
+  // - API configuration
+  // - External downloads
+  // - Integration setup

- System configurations
- User templates
- Shared resources
+  return true;
+}
+
+module.exports = { install };
+```
+
+### Optional: \_module-installer/assets/
+
+Files to copy during installation:
+
+- External configurations
+- Documentation
+- Example files
 - Integration scripts

 ## Module Lifecycle
--- a/bmad/bmb/workflows/create-module/module-structure.md.bak
+++ b/bmad/bmb/workflows/create-module/module-structure.md.bak
@@ -0,0 +1,310 @@
+# BMAD Module Structure Guide
+
+## What is a Module?
+
+A BMAD module is a self-contained package of agents, workflows, tasks, and resources that work together to provide specialized functionality. Think of it as an expansion pack for the BMAD Method.
+
+## Module Architecture
+
+### Core Structure
+
+```
+project-root/
+├── bmad/{module-code}/     # Source code
+│   ├── agents/                    # Agent definitions
+│   ├── workflows/                 # Workflow folders
+│   ├── tasks/                     # Task files
+│   ├── templates/                 # Shared templates
+│   ├── data/                      # Static data
+│   ├── config.yaml                # Module config
+│   └── README.md                  # Documentation
+│
+└── bmad/{module-code}/            # Runtime instance
+    ├── _module-installer/         # Installation files
+    │   ├── install-config.yaml
+    │   ├── installer.js          # Optional
+    │   └── assets/               # Install assets
+    ├── config.yaml               # User config
+    ├── agents/                   # Agent overrides
+    ├── workflows/                # Workflow instances
+    └── data/                     # User data
+
+```
+
+## Module Types by Complexity
+
+### Simple Module (1-2 agents, 2-3 workflows)
+
+Perfect for focused, single-purpose tools.
+
+**Example: Code Review Module**
+
+- 1 Reviewer Agent
+- 2 Workflows: quick-review, deep-review
+- Clear, narrow scope
+
+### Standard Module (3-5 agents, 5-10 workflows)
+
+Comprehensive solution for a domain.
+
+**Example: Project Management Module**
+
+- PM Agent, Scrum Master Agent, Analyst Agent
+- Workflows: sprint-planning, retrospective, roadmap, user-stories
+- Integrated component ecosystem
+
+### Complex Module (5+ agents, 10+ workflows)
+
+Full platform or framework.
+
+**Example: RPG Toolkit Module**
+
+- DM Agent, NPC Agent, Monster Agent, Loot Agent, Map Agent
+- 15+ workflows for every aspect of game management
+- Multiple interconnected systems
+
+## Module Naming Conventions
+
+### Module Code (kebab-case)
+
+- `data-viz` - Data Visualization
+- `team-collab` - Team Collaboration
+- `rpg-toolkit` - RPG Toolkit
+- `legal-assist` - Legal Assistant
+
+### Module Name (Title Case)
+
+- "Data Visualization Suite"
+- "Team Collaboration Platform"
+- "RPG Game Master Toolkit"
+- "Legal Document Assistant"
+
+## Component Guidelines
+
+### Agents per Module
+
+**Recommended Distribution:**
+
+- **Primary Agent (1)**: The main interface/orchestrator
+- **Specialist Agents (2-4)**: Domain-specific experts
+- **Utility Agents (0-2)**: Helper/support functions
+
+**Anti-patterns to Avoid:**
+
+- Too many overlapping agents
+- Agents that could be combined
+- Agents without clear purpose
+
+### Workflows per Module
+
+**Categories:**
+
+- **Core Workflows (2-3)**: Essential functionality
+- **Feature Workflows (3-5)**: Specific capabilities
+- **Utility Workflows (2-3)**: Supporting operations
+- **Admin Workflows (0-2)**: Maintenance/config
+
+**Workflow Complexity Guide:**
+
+- Simple: 3-5 steps, single output
+- Standard: 5-10 steps, multiple outputs
+- Complex: 10+ steps, conditional logic, sub-workflows
+
+### Tasks per Module
+
+Tasks should be used for:
+
+- Single-operation utilities
+- Shared subroutines
+- Quick actions that don't warrant workflows
+
+## Module Dependencies
+
+### Internal Dependencies
+
+- Agents can reference module workflows
+- Workflows can invoke module tasks
+- Tasks can use module templates
+
+### External Dependencies
+
+- Reference other modules via full paths
+- Declare dependencies in config.yaml
+- Version compatibility notes
+
+## Installation Infrastructure
+
+### Required: install-config.yaml
+
+```yaml
+module_name: 'Module Name'
+module_code: 'module-code'
+
+install_steps:
+  - name: 'Create directories'
+    action: 'mkdir'
+    paths: [...]
+
+  - name: 'Copy files'
+    action: 'copy'
+    mappings: [...]
+
+  - name: 'Register module'
+    action: 'register'
+```
+
+### Optional: installer.js
+
+For complex installations requiring:
+
+- Database setup
+- API configuration
+- System integration
+- Permission management
+
+### Optional: External Assets
+
+Files that get copied outside the module:
+
+- System configurations
+- User templates
+- Shared resources
+- Integration scripts
+
+## Module Lifecycle
+
+### Development Phases
+
+1. **Planning Phase**
+   - Define scope and purpose
+   - Identify components
+   - Design architecture
+
+2. **Scaffolding Phase**
+   - Create directory structure
+   - Generate configurations
+   - Setup installer
+
+3. **Building Phase**
+   - Create agents incrementally
+   - Build workflows progressively
+   - Add tasks as needed
+
+4. **Testing Phase**
+   - Test individual components
+   - Verify integration
+   - Validate installation
+
+5. **Deployment Phase**
+   - Package module
+   - Document usage
+   - Distribute/share
+
+## Best Practices
+
+### Module Cohesion
+
+- All components should relate to module theme
+- Clear boundaries between modules
+- No feature creep
+
+### Progressive Enhancement
+
+- Start with MVP (1 agent, 2 workflows)
+- Add components based on usage
+- Refactor as patterns emerge
+
+### Documentation Standards
+
+- Every module needs README.md
+- Each agent needs purpose statement
+- Workflows need clear descriptions
+- Include examples and quickstart
+
+### Naming Consistency
+
+- Use module code prefix for uniqueness
+- Consistent naming patterns within module
+- Clear, descriptive names
+
+## Example Modules
+
+### Example 1: Personal Productivity
+
+```
+productivity/
+├── agents/
+│   ├── task-manager.md      # GTD methodology
+│   └── focus-coach.md        # Pomodoro timer
+├── workflows/
+│   ├── daily-planning/       # Morning routine
+│   ├── weekly-review/        # Week retrospective
+│   └── project-setup/        # New project init
+└── config.yaml
+```
+
+### Example 2: Content Creation
+
+```
+content/
+├── agents/
+│   ├── writer.md            # Blog/article writer
+│   ├── editor.md            # Copy editor
+│   └── seo-optimizer.md     # SEO specialist
+├── workflows/
+│   ├── blog-post/           # Full blog creation
+│   ├── social-media/        # Social content
+│   ├── email-campaign/      # Email sequence
+│   └── content-calendar/    # Planning
+└── templates/
+    ├── blog-template.md
+    └── email-template.md
+```
+
+### Example 3: DevOps Automation
+
+```
+devops/
+├── agents/
+│   ├── deploy-master.md     # Deployment orchestrator
+│   ├── monitor.md           # System monitoring
+│   ├── incident-responder.md # Incident management
+│   └── infra-architect.md   # Infrastructure design
+├── workflows/
+│   ├── ci-cd-setup/         # Pipeline creation
+│   ├── deploy-app/          # Application deployment
+│   ├── rollback/            # Emergency rollback
+│   ├── health-check/        # System verification
+│   └── incident-response/   # Incident handling
+├── tasks/
+│   ├── check-status.md      # Quick status check
+│   └── notify-team.md       # Team notifications
+└── data/
+    └── runbooks/            # Operational guides
+```
+
+## Module Evolution Pattern
+
+```
+Simple Module → Standard Module → Complex Module → Module Suite
+     (MVP)          (Enhanced)        (Complete)      (Ecosystem)
+```
+
+## Common Pitfalls
+
+1. **Over-engineering**: Starting too complex
+2. **Under-planning**: No clear architecture
+3. **Poor boundaries**: Module does too much
+4. **Weak integration**: Components don't work together
+5. **Missing docs**: No clear usage guide
+
+## Success Metrics
+
+A well-designed module has:
+
+- ✅ Clear, focused purpose
+- ✅ Cohesive components
+- ✅ Smooth installation
+- ✅ Comprehensive docs
+- ✅ Room for growth
+- ✅ Happy users!
--- a/bmad/bmb/workflows/create-module/workflow.yaml
+++ b/bmad/bmb/workflows/create-module/workflow.yaml
@@ -37,4 +37,6 @@ validation: "{installed_path}/checklist.md"
 # Output configuration - creates entire module structure
 # Save to custom_module_location/{{module_code}}
 installer_output_folder: "{custom_module_location}/{{module_code}}"
+
+standalone: true
 # Web bundle configuration
--- a/bmad/bmb/workflows/create-module/workflow.yaml.bak
+++ b/bmad/bmb/workflows/create-module/workflow.yaml.bak
@@ -0,0 +1,40 @@
+# Build Module Workflow Configuration
+name: create-module
+description: "Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure"
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/bmb/config.yaml"
+custom_module_location: "{config_source}:custom_module_location"
+communication_language: "{config_source}:communication_language"
+user_name: "{config_source}:user_name"
+
+# Reference guides for module building
+module_structure_guide: "{installed_path}/module-structure.md"
+installer_templates: "{installed_path}/installer-templates/"
+
+# Use existing build workflows
+agent_builder: "{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml"
+workflow_builder: "{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml"
+brainstorming_workflow: "{project-root}/bmad/core/workflows/brainstorming/workflow.yaml"
+brainstorming_context: "{installed_path}/brainstorm-context.md"
+
+# Optional docs that help understand module patterns
+recommended_inputs:
+  - module_brief: "{output_folder}/module-brief-*.md"
+  - brainstorming_results: "{output_folder}/brainstorming-*.md"
+  - bmm_module: "{project-root}/bmad/bmm/"
+  - cis_module: "{project-root}/bmad/cis/"
+  - existing_agents: "{project-root}/bmad/*/agents/"
+  - existing_workflows: "{project-root}/bmad/*/workflows/"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/create-module"
+template: false # This is an interactive scaffolding workflow
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration - creates entire module structure
+# Save to custom_module_location/{{module_code}}
+installer_output_folder: "{custom_module_location}/{{module_code}}"
+# Web bundle configuration
--- a/bmad/bmb/workflows/create-workflow/README.md
+++ b/bmad/bmb/workflows/create-workflow/README.md
@@ -258,7 +258,7 @@ To modify this workflow:
  - Enhanced validation for documentation
  - Improved Step 10 with detailed README requirements

- **v5.0.0** - Initial BMAD Core v6 compatible version
+- **v6.0.0** - Initial BMAD Core v6 compatible version
  - Template-based workflow generation
  - Convention enforcement
  - Validation checklist support
--- a/bmad/bmb/workflows/create-workflow/instructions.md
+++ b/bmad/bmb/workflows/create-workflow/instructions.md
@@ -72,7 +72,7 @@ Based on type, determine which files are needed:
 Store decisions for later use.
 </step>

-<step n="2" goal="Gather workflow metadata">
+<step n="2" goal="Gather workflow metadata and invocation settings">
 Collect essential configuration details:
 - Description (clear purpose statement)
 - Author name (default to user_name or "BMad")
@@ -80,40 +80,149 @@ Collect essential configuration details:
 - Any required input documents
 - Any required tools or dependencies

+<action>Determine standalone property - this controls how the workflow can be invoked:
+
+Explain to the user:
+
+**Standalone Property** controls whether the workflow can be invoked directly or only called by other workflows/agents.
+
+**standalone: true (DEFAULT - Recommended for most workflows)**:
+
+- Users can invoke directly via IDE commands or `/workflow-name`
+- Shows up in IDE command palette
+- Can also be called from agent menus or other workflows
+- Use for: User-facing workflows, entry-point workflows, any workflow users run directly
+
+**standalone: false (Use for helper/internal workflows)**:
+
+- Cannot be invoked directly by users
+- Only called via `<invoke-workflow>` from other workflows or agent menus
+- Doesn't appear in IDE command palette
+- Use for: Internal utilities, sub-workflows, helpers that don't make sense standalone
+
+Most workflows should be `standalone: true` to give users direct access.
+</action>
+
+<ask>Should this workflow be directly invokable by users?
+
+1. **Yes (Recommended)** - Users can run it directly (standalone: true)
+2. **No** - Only called by other workflows/agents (standalone: false)
+
+Most workflows choose option 1:</ask>
+
+<action>Store {{standalone_setting}} as true or false based on response</action>
+
 Create the workflow name in kebab-case and verify it doesn't conflict with existing workflows.
 </step>

-<step n="3" goal="Design workflow steps">
-Work with user to outline the workflow steps:
- How many major steps? (Recommend 5-10 max)
+<step n="3" goal="Understand workflow interaction style and design steps">
+<critical>Instruction style and interactivity level fundamentally shape the user experience - choose thoughtfully</critical>
+
+<action>Reference the comprehensive "Instruction Styles: Intent-Based vs Prescriptive" section from the loaded creation guide</action>
+
+<action>Discuss instruction style collaboratively with the user:
+
+Explain that there are two primary approaches:
+
+**Intent-Based (RECOMMENDED as default)**:
+
+- Gives AI goals and principles, lets it adapt conversation naturally
+- More flexible, conversational, responsive to user context
+- Better for: discovery, complex decisions, teaching, varied user skill levels
+- Uses <action> tags with guiding instructions
+- Example from architecture workflow: Facilitates decisions adapting to user_skill_level
+
+**Prescriptive**:
+
+- Provides exact questions and specific options
+- More controlled, predictable, consistent across runs
+- Better for: simple data collection, finite options, compliance, quick setup
+- Uses <ask> tags with specific question text
+- Example: Platform selection with 5 defined choices
+
+Explain that **most workflows should default to intent-based** but use prescriptive for simple data points.
+The architecture workflow is an excellent example of intent-based with prescriptive moments.
+</action>
+
+<ask>For this workflow's PRIMARY style:
+
+1. **Intent-based (Recommended)** - Adaptive, conversational, responds to user context
+2. **Prescriptive** - Structured, consistent, controlled interactions
+3. **Mixed/Balanced** - I'll help you decide step-by-step
+
+What feels right for your workflow's purpose?</ask>
+
+<action>Store {{instruction_style}} preference</action>
+
+<action>Now discuss interactivity level:
+
+Beyond style, consider **how interactive** this workflow should be:
+
+**High Interactivity (Collaborative)**:
+
+- Constant back-and-forth with user
+- User guides direction, AI facilitates
+- Iterative refinement and review
+- Best for: creative work, complex decisions, learning experiences
+- Example: Architecture workflow's collaborative decision-making
+
+**Medium Interactivity (Guided)**:
+
+- Key decision points have interaction
+- AI proposes, user confirms or refines
+- Validation checkpoints
+- Best for: most document workflows, structured processes
+- Example: PRD workflow with sections to review
+
+**Low Interactivity (Autonomous)**:
+
+- Minimal user input required
+- AI works independently with guidelines
+- User reviews final output
+- Best for: automated generation, batch processing
+- Example: Generating user stories from epics
+  </action>
+
+<ask>What interactivity level suits this workflow?
+
+1. **High** - Highly collaborative, user actively involved throughout
+2. **Medium** - Guided with key decision points (most common)
+3. **Low** - Autonomous with final review
+
+Select the level that matches your workflow's purpose:</ask>
+
+<action>Store {{interactivity_level}} preference</action>
+
+<action>Explain how these choices will inform the workflow design:
+
+- Intent-based + High interactivity: Conversational discovery with open questions
+- Intent-based + Medium: Facilitated guidance with confirmation points
+- Intent-based + Low: Principle-based autonomous generation
+- Prescriptive + any level: Structured questions, but frequency varies
+- Mixed: Strategic use of both styles where each works best
+  </action>
+
+<action>Now work with user to outline workflow steps:
+
+- How many major steps? (Recommend 3-7 for most workflows)
 - What is the goal of each step?
 - Which steps are optional?
- Which steps need user input?
+- Which steps need heavy user collaboration vs autonomous execution?
 - Which steps should repeat?
 - What variables/outputs does each step produce?

-<ask>What instruction style should this workflow favor?
+Consider their instruction_style and interactivity_level choices when designing step flow:

-**1. Intent-Based (Recommended)** - Guide the LLM with goals and principles, let it adapt conversations naturally
+- High interactivity: More granular steps with collaboration
+- Low interactivity: Larger autonomous steps with review
+- Intent-based: Focus on goals and principles in step descriptions
+- Prescriptive: Define specific questions and options
+  </action>

- More flexible and conversational
- LLM chooses appropriate questions based on context
- Better for complex discovery and iterative refinement
- Example: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+<action>Create a step outline that matches the chosen style and interactivity level</action>
+<action>Note which steps should be intent-based vs prescriptive (if mixed approach)</action>

-**2. Prescriptive** - Provide exact wording for questions and options
-
- More controlled and predictable
- Ensures consistency across runs
- Better for simple data collection or specific compliance needs
- Example: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
-
-Note: Your choice will be the _primary_ style, but we'll use the other when it makes more sense for specific steps.</ask>
-
-<action>Store instruction_style preference (intent-based or prescriptive)</action>
-<action>Explain that both styles have value and will be mixed appropriately</action>
-
-Create a step outline with clear goals and outputs.
+<template-output>step_outline</template-output>
 </step>

 <step n="4" goal="Create workflow.yaml">
@@ -130,6 +239,7 @@ Replace all placeholders following the workflow creation guide conventions:
 Include:

 - All metadata from steps 1-2
+- **Standalone property**: Use {{standalone_setting}} from step 2 (true or false)
 - Proper paths for installed_path using variable substitution
 - Template/instructions/validation paths based on workflow type:
  - Document workflow: all files (template, instructions, validation)
@@ -151,6 +261,38 @@ date: system-generated

 <critical>This standard config ensures workflows can run autonomously and communicate properly with users</critical>

+<critical>ALWAYS include the standalone property:</critical>
+
+```yaml
+standalone: { { standalone_setting } } # true or false from step 2
+```
+
+**Example complete workflow.yaml structure**:
+
+```yaml
+name: 'workflow-name'
+description: 'Clear purpose statement'
+
+# Paths
+installed_path: '{project-root}/bmad/module/workflows/name'
+template: '{installed_path}/template.md'
+instructions: '{installed_path}/instructions.md'
+validation: '{installed_path}/checklist.md'
+
+# Critical variables from config
+config_source: '{project-root}/bmad/module/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+
+# Output
+default_output_file: '{output_folder}/document.md'
+
+# Invocation control
+standalone: true # or false based on step 2 decision
+```
+
 Follow path conventions from guide:

 - Use {project-root} for absolute paths
--- a/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md
+++ b/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md
@@ -29,6 +29,8 @@ installed_path: '{project-root}/bmad/module/workflows/my-workflow'
 template: '{installed_path}/template.md'
 instructions: '{installed_path}/instructions.md'
 default_output_file: '{output_folder}/output.md'
+
+standalone: true
 ```

 ```markdown
@@ -46,14 +48,14 @@ default_output_file: '{output_folder}/output.md'
 <critical>You MUST have already loaded and processed: workflow.yaml</critical>

 <workflow>
-<step n="1" goal="Generate content">
-Create the main content for this document.
-<template-output>main_content</template-output>
-</step>
+  <step n="1" goal="Generate content">
+  Create the main content for this document.
+  <template-output>main_content</template-output>
+  </step>
 </workflow>
 ```

-That's it! To execute, tell the BMAD agent: `workflow my-workflow`
+That's it! To execute, tell the BMAD agent: `workflow path/to/my-workflow/`

 ## Core Concepts

@@ -62,7 +64,7 @@ That's it! To execute, tell the BMAD agent: `workflow my-workflow`
 | Aspect         | Task               | Workflow                |
 | -------------- | ------------------ | ----------------------- |
 | **Purpose**    | Single operation   | Multi-step process      |
-| **Format**     | XML in `.md` file  | Folder with YAML config |
+| **Format**     | XML                | Folder with YAML config |
 | **Location**   | `/src/core/tasks/` | `/bmad/*/workflows/`    |
 | **User Input** | Minimal            | Extensive               |
 | **Output**     | Variable           | Usually documents       |
@@ -91,7 +93,7 @@ my-workflow/
  ├── template.md        # Document structure
  ├── instructions.md    # Step-by-step guide
  ├── checklist.md       # Validation criteria
-  └── [data files]       # Supporting resources
+  └── [data files]       # Supporting resources, xml, md, csv or others
 ```

 ### workflow.yaml Configuration
@@ -111,11 +113,121 @@ validation: '{installed_path}/checklist.md' # optional
 default_output_file: '{output_folder}/document.md'

 # Advanced options
-autonomous: true # Skip user checkpoints
 recommended_inputs: # Expected input docs
  - input_doc: 'path/to/doc.md'
+
+# Invocation control
+standalone: true # Can be invoked directly (default: true)
 ```

+### Standalone Property: Invocation Control
+
+**CRITICAL**: The `standalone` property controls whether a workflow, task, or tool can be invoked independently or must be called through an agent's menu.
+
+#### For Workflows (workflow.yaml)
+
+```yaml
+standalone: true  # Can invoke directly: /workflow-name or via IDE command
+standalone: false # Must be called from an agent menu or another workflow
+```
+
+**When to use `standalone: true` (DEFAULT)**:
+
+- ✅ User-facing workflows that should be directly accessible
+- ✅ Workflows invoked via IDE commands or CLI
+- ✅ Workflows that users will run independently
+- ✅ Most document generation workflows (PRD, architecture, etc.)
+- ✅ Action workflows users trigger directly (refactor, analyze, etc.)
+- ✅ Entry-point workflows for a module
+
+**When to use `standalone: false`**:
+
+- ✅ Sub-workflows only called by other workflows (via `<invoke-workflow>`)
+- ✅ Internal utility workflows not meant for direct user access
+- ✅ Workflows that require specific context from parent workflow
+- ✅ Helper workflows that don't make sense alone
+
+**Examples**:
+
+```yaml
+# Standalone: User invokes directly
+name: 'plan-project'
+description: 'Create PRD/GDD for any project'
+standalone: true # Users run this directly
+
+---
+# Non-standalone: Only called by parent workflow
+name: 'validate-requirements'
+description: 'Internal validation helper for PRD workflow'
+standalone: false # Only invoked by plan-project workflow
+```
+
+#### For Tasks and Tools (XML files)
+
+Tasks and tools in `src/core/tasks/` and `src/core/tools/` also support the standalone attribute:
+
+```xml
+<!-- Standalone task: Can be invoked directly -->
+<task name="workflow" standalone="true">
+  <!-- Task definition -->
+</task>
+
+<!-- Non-standalone: Only called by workflows/agents -->
+<tool name="internal-helper" standalone="false">
+  <!-- Tool definition -->
+</tool>
+```
+
+**Task/Tool Standalone Guidelines**:
+
+- `standalone="true"`: Core tasks like workflow.xml, create-doc.xml that users/agents invoke directly
+- `standalone="false"`: Internal helpers, utilities only called by other tasks/workflows
+
+#### Default Behavior
+
+**If standalone property is omitted**:
+
+- Workflows: Default to `standalone: true` (accessible directly)
+- Tasks/Tools: Default to `standalone: true` (accessible directly)
+
+**Best Practice**: Explicitly set standalone even if using default to make intent clear.
+
+#### Invocation Patterns
+
+**Standalone workflows can be invoked**:
+
+1. Directly by users: `/workflow-name` or IDE command
+2. From agent menus: `workflow: "{path}/workflow.yaml"`
+3. From other workflows: `<invoke-workflow path="{path}/workflow.yaml">`
+
+**Non-standalone workflows**:
+
+1. ❌ Cannot be invoked directly by users
+2. ❌ Cannot be called from IDE commands
+3. ✅ Can be invoked by other workflows via `<invoke-workflow>`
+4. ✅ Can be called from agent menu items
+
+#### Module Design Implications
+
+**Typical Module Pattern**:
+
+```yaml
+# Entry-point workflows: standalone: true
+bmm/workflows/plan-project/workflow.yaml → standalone: true
+bmm/workflows/architecture/workflow.yaml → standalone: true
+
+# Helper workflows: standalone: false
+bmm/workflows/internal/validate-epic/workflow.yaml → standalone: false
+bmm/workflows/internal/format-story/workflow.yaml → standalone: false
+```
+
+**Benefits of this pattern**:
+
+- Clear separation between user-facing and internal workflows
+- Prevents users from accidentally invoking incomplete/internal workflows
+- Cleaner IDE command palette (only shows standalone workflows)
+- Better encapsulation and maintainability
+
 ### Common Patterns

 **Full Document Workflow** (most common)
@@ -135,6 +247,395 @@ recommended_inputs: # Expected input docs

 ## Writing Instructions

+### Instruction Styles: Intent-Based vs Prescriptive
+
+**CRITICAL DESIGN DECISION**: Choose your instruction style early - it fundamentally shapes the user experience.
+
+#### Default Recommendation: Intent-Based (Adaptive)
+
+**Intent-based workflows give the AI goals and principles, letting it adapt the conversation naturally to the user's context.** This is the BMAD v6 default for most workflows.
+
+#### The Two Approaches
+
+##### 1. Intent-Based Instructions (RECOMMENDED)
+
+**What it is**: Guide the AI with goals, principles, and context - let it determine the best way to interact with each user.
+
+**Characteristics**:
+
+- Uses `<action>` tags with guiding instructions
+- Focuses on WHAT to accomplish and WHY it matters
+- Lets AI adapt conversation to user needs
+- More flexible and conversational
+- Better for complex discovery and iterative refinement
+
+**When to use**:
+
+- Complex discovery processes (requirements gathering, architecture design)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- When user input quality matters more than consistency
+- Workflows requiring adaptation to context
+- Teaching/educational workflows
+- When users have varying skill levels
+
+**Example**:
+
+```xml
+<step n="2" goal="Understand user's target audience">
+  <action>Engage in collaborative discovery to understand their target users:
+
+  Ask open-ended questions to explore:
+  - Who will use this product?
+  - What problems do they face?
+  - What are their goals and motivations?
+  - How tech-savvy are they?
+
+  Listen for clues about:
+  - Demographics and characteristics
+  - Pain points and needs
+  - Current solutions they use
+  - Unmet needs or frustrations
+
+  Adapt your depth and terminology to the user's responses.
+  If they give brief answers, dig deeper with follow-ups.
+  If they're uncertain, help them think through it with examples.
+  </action>
+
+  <template-output>target_audience</template-output>
+</step>
+```
+
+**Intent-based workflow adapts**:
+
+- **Expert user** might get: "Tell me about your target users - demographics, pain points, and technical profile?"
+- **Beginner user** might get: "Let's talk about who will use this. Imagine your ideal customer - what do they look like? What problem are they trying to solve?"
+
+##### 2. Prescriptive Instructions (Use Selectively)
+
+**What it is**: Provide exact wording for questions and specific options for answers.
+
+**Characteristics**:
+
+- Uses `<ask>` tags with exact question text
+- Provides specific options or formats
+- More controlled and predictable
+- Ensures consistency across runs
+- Better for simple data collection or compliance needs
+
+**When to use**:
+
+- Simple data collection (platform choice, format selection)
+- Compliance verification and standards adherence
+- Configuration with finite, well-defined options
+- When consistency is critical across all executions
+- Quick setup wizards
+- Binary decisions (yes/no, enable/disable)
+- When gathering specific required fields
+
+**Example**:
+
+```xml
+<step n="3" goal="Select target platform">
+  <ask>What is your target platform?
+
+  1. Web (browser-based application)
+  2. Mobile (iOS/Android native apps)
+  3. Desktop (Windows/Mac/Linux applications)
+  4. CLI (command-line tool)
+  5. API (backend service)
+
+  Enter the number (1-5):</ask>
+
+  <action>Store the platform choice as {{target_platform}}</action>
+  <template-output>target_platform</template-output>
+</step>
+```
+
+**Prescriptive workflow stays consistent** - every user gets the same 5 options in the same format.
+
+#### Best Practice: Mix Both Styles
+
+**Even predominantly intent-based workflows should use prescriptive moments** for simple choices. Even prescriptive workflows can have intent-based discovery.
+
+**Example of effective mixing**:
+
+```xml
+<!-- Intent-based: Complex discovery -->
+<step n="1" goal="Understand user vision">
+  <action>Explore the user's vision through open conversation:
+
+  Help them articulate:
+  - The core problem they're solving
+  - Their unique approach or innovation
+  - The experience they want to create
+
+  Adapt your questions based on their expertise and communication style.
+  If they're visionary, explore the "why". If they're technical, explore the "how".
+  </action>
+  <template-output>vision</template-output>
+</step>
+
+<!-- Prescriptive: Simple data -->
+<step n="2" goal="Capture basic metadata">
+  <ask>What is your target platform? Choose one:
+  - Web
+  - Mobile
+  - Desktop
+  - CLI
+  - API</ask>
+
+  <action>Store as {{platform}}</action>
+</step>
+
+<!-- Intent-based: Deep exploration -->
+<step n="3" goal="Design user experience">
+  <action>Facilitate collaborative UX design:
+
+  Guide them to explore:
+  - User journey and key flows
+  - Interaction patterns and affordances
+  - Visual/aesthetic direction
+
+  Use their platform choice from step 2 to inform relevant patterns.
+  For web: discuss responsive design. For mobile: touch interactions. Etc.
+  </action>
+  <template-output>ux_design</template-output>
+</step>
+```
+
+#### Interactivity Levels
+
+Beyond style (intent vs prescriptive), consider **how interactive** your workflow should be:
+
+##### High Interactivity (Collaborative)
+
+- Constant back-and-forth with user
+- Multiple asks per step
+- Iterative refinement and review
+- User guides the direction
+- **Best for**: Creative work, complex decisions, learning
+
+**Example**:
+
+```xml
+<step n="4" goal="Design feature set" repeat="until-satisfied">
+  <action>Collaborate on feature definitions:
+
+  For each feature the user proposes:
+  - Help them articulate it clearly
+  - Explore edge cases together
+  - Consider implications and dependencies
+  - Refine the description iteratively
+
+  After each feature: "Want to refine this, add another, or move on?"
+  </action>
+</step>
+```
+
+##### Medium Interactivity (Guided)
+
+- Key decision points have interaction
+- AI proposes, user confirms or refines
+- Validation checkpoints
+- **Best for**: Most document workflows, structured processes
+
+**Example**:
+
+```xml
+<step n="5" goal="Generate architecture decisions">
+  <action>Based on the PRD, identify 10-15 key architectural decisions needed</action>
+  <action>For each decision, research options and present recommendation</action>
+  <ask>Approve this decision or propose alternative?</ask>
+  <action>Record decision and rationale</action>
+</step>
+```
+
+##### Low Interactivity (Autonomous)
+
+- Minimal user input required
+- AI works independently with guidelines
+- User reviews final output
+- **Best for**: Automated generation, batch processing
+
+**Example**:
+
+```xml
+<step n="6" goal="Generate user stories">
+  <action>For each epic in the PRD, generate 3-7 user stories following this pattern:
+  - As a [user type]
+  - I want to [action]
+  - So that [benefit]
+
+  Ensure stories are:
+  - Independently valuable
+  - Testable
+  - Sized appropriately (1-5 days of work)
+  </action>
+
+  <template-output>user_stories</template-output>
+</step>
+
+<step n="7" goal="Review generated stories">
+  <ask>Review the generated user stories. Want to refine any? (y/n)</ask>
+  <check if="yes">
+    <goto step="6">Regenerate with feedback</goto>
+  </check>
+</step>
+```
+
+#### Decision Framework
+
+**Choose Intent-Based when**:
+
+- ✅ User knowledge/skill level varies
+- ✅ Context matters (one-size-fits-all won't work)
+- ✅ Discovery and exploration are important
+- ✅ Quality of input matters more than consistency
+- ✅ Teaching/education is part of the goal
+- ✅ Iteration and refinement expected
+
+**Choose Prescriptive when**:
+
+- ✅ Options are finite and well-defined
+- ✅ Consistency across users is critical
+- ✅ Compliance or standards matter
+- ✅ Simple data collection
+- ✅ Users just need to make a choice and move on
+- ✅ Speed matters more than depth
+
+**Choose High Interactivity when**:
+
+- ✅ User expertise is essential
+- ✅ Creative collaboration needed
+- ✅ Decisions have major implications
+- ✅ Learning and understanding matter
+- ✅ Iteration is expected
+
+**Choose Low Interactivity when**:
+
+- ✅ Process is well-defined and repeatable
+- ✅ AI can work autonomously with clear guidelines
+- ✅ User time is constrained
+- ✅ Batch processing or automation desired
+- ✅ Review-and-refine model works
+
+#### Implementation Guidelines
+
+**For Intent-Based Workflows**:
+
+1. **Use `<action>` tags with guiding instructions**
+
+```xml
+<action>Facilitate discovery of {{topic}}:
+
+Ask open-ended questions to explore:
+- {{aspect_1}}
+- {{aspect_2}}
+
+Listen for clues about {{patterns_to_notice}}.
+
+Adapt your approach based on their {{context_factor}}.
+</action>
+```
+
+2. **Provide principles, not scripts**
+
+```xml
+<!-- ✅ Good: Principles -->
+<action>Help user articulate their unique value proposition.
+Focus on what makes them different, not just what they do.
+If they struggle, offer examples from analogous domains.</action>
+
+<!-- ❌ Avoid: Prescriptive script -->
+<ask>What makes your product unique? Provide 2-3 bullet points.</ask>
+```
+
+3. **Guide with context and rationale**
+
+```xml
+<action>Now that we understand their {{context_from_previous}},
+explore how {{current_topic}} connects to their vision.
+
+This matters because {{reason_it_matters}}.
+
+If they seem uncertain about {{potential_challenge}}, help them think through {{approach}}.
+</action>
+```
+
+**For Prescriptive Workflows**:
+
+1. **Use `<ask>` tags with specific questions**
+
+```xml
+<ask>Select your preferred database:
+1. PostgreSQL
+2. MySQL
+3. MongoDB
+4. SQLite
+
+Enter number (1-4):</ask>
+```
+
+2. **Provide clear options and formats**
+
+```xml
+<ask>Enable user authentication? (yes/no)</ask>
+<ask>Enter project name (lowercase, no spaces):</ask>
+```
+
+3. **Keep it crisp and clear**
+
+```xml
+<!-- ✅ Good: Clear and direct -->
+<ask>Target platform? (web/mobile/desktop)</ask>
+
+<!-- ❌ Avoid: Over-explaining -->
+<ask>We need to know what platform you're building for. This will affect
+the technology stack recommendations. Please choose: web, mobile, or desktop.</ask>
+```
+
+#### Mixing Styles Within a Workflow
+
+**Pattern: Intent-based discovery → Prescriptive capture → Intent-based refinement**
+
+```xml
+<step n="1" goal="Explore user needs">
+  <!-- Intent-based discovery -->
+  <action>Engage in open conversation to understand user needs deeply...</action>
+</step>
+
+<step n="2" goal="Capture key metrics">
+  <!-- Prescriptive data collection -->
+  <ask>Expected daily active users? (number)</ask>
+  <ask>Data sensitivity level? (public/internal/sensitive/highly-sensitive)</ask>
+</step>
+
+<step n="3" goal="Design solution approach">
+  <!-- Intent-based design -->
+  <action>Collaborate on solution design, using the metrics from step 2 to inform scale and security decisions...</action>
+</step>
+```
+
+**Pattern: Prescriptive setup → Intent-based execution**
+
+```xml
+<step n="1" goal="Quick setup">
+  <!-- Prescriptive configuration -->
+  <ask>Project type? (web-app/api/cli/library)</ask>
+  <ask>Language? (typescript/python/go/rust)</ask>
+</step>
+
+<step n="2" goal="Detailed design">
+  <!-- Intent-based design -->
+  <action>Now that we know it's a {{project_type}} in {{language}},
+  let's explore the architecture in detail.
+
+  Guide them through design decisions appropriate for a {{project_type}}...
+  </action>
+</step>
+```
+
 ### Basic Structure

 ```markdown
@@ -290,6 +791,43 @@ _Generated on {{date}}_
 - **`<action if="">`** - Single conditional action (cleaner, more concise)
 - **`<check if="">...</check>`** - Multiple items under same condition (explicit scope)

+**❌ CRITICAL ANTIPATTERN - DO NOT USE:**
+
+**Invalid self-closing check tags:**
+
+```xml
+<!-- ❌ WRONG - Invalid XML structure -->
+<check>If condition met:</check>
+<action>Do something</action>
+
+<!-- ❌ WRONG - Ambiguous nesting -->
+<check>If validation fails:</check>
+<action>Log error</action>
+<goto step="1">Retry</goto>
+```
+
+**Why this is wrong:**
+
+- Creates invalid XML structure (check tag doesn't wrap anything)
+- Ambiguous - unclear if actions are inside or outside the condition
+- Breaks formatter and parser logic
+- Not part of BMAD workflow spec
+
+**✅ CORRECT alternatives:**
+
+```xml
+<!-- ✅ Single action - use inline if -->
+<action if="condition met">Do something</action>
+
+<!-- ✅ Multiple actions - use proper wrapper block -->
+<check if="validation fails">
+  <action>Log error</action>
+  <goto step="1">Retry</goto>
+</check>
+```
+
+**Rule:** If you have only ONE conditional action, use `<action if="">`. If you have MULTIPLE conditional actions, use `<check if="">...</check>` wrapper with a closing tag.
+
 ### Loops

 ```xml
@@ -358,21 +896,21 @@ _Generated on {{date}}_

 ```xml
 <workflow>
-<step n="1" goal="Gather context">
-Load existing documents and understand project scope.
-<template-output>context</template-output>
-</step>
+  <step n="1" goal="Gather context">
+    Load existing documents and understand project scope.
+    <template-output>context</template-output>
+  </step>

-<step n="2" goal="Define requirements">
-Create functional and non-functional requirements.
-<template-output>requirements</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-</step>
+  <step n="2" goal="Define requirements">
+    Create functional and non-functional requirements.
+    <template-output>requirements</template-output>
+    <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
+  </step>

-<step n="3" goal="Validate">
-Check requirements against goals.
-<template-output>validated_requirements</template-output>
-</step>
+  <step n="3" goal="Validate">
+    Check requirements against goals.
+    <template-output>validated_requirements</template-output>
+  </step>
 </workflow>
 ```

@@ -404,20 +942,20 @@ Check requirements against goals.

 ```xml
 <workflow name="greenfield-app">
-<step n="1" goal="Discovery">
-  <invoke-workflow>product-brief</invoke-workflow>
-  <template-output>brief</template-output>
-</step>
+  <step n="1" goal="Discovery">
+    <invoke-workflow>product-brief</invoke-workflow>
+    <template-output>brief</template-output>
+  </step>

-<step n="2" goal="Requirements">
-  <invoke-workflow input="{{brief}}">prd</invoke-workflow>
-  <template-output>prd</template-output>
-</step>
+  <step n="2" goal="Requirements">
+    <invoke-workflow input="{{brief}}">prd</invoke-workflow>
+    <template-output>prd</template-output>
+  </step>

-<step n="3" goal="Architecture">
-  <invoke-workflow input="{{prd}}">architecture</invoke-workflow>
-  <template-output>architecture</template-output>
-</step>
+  <step n="3" goal="Architecture">
+    <invoke-workflow input="{{prd}}">architecture</invoke-workflow>
+    <template-output>architecture</template-output>
+  </step>
 </workflow>
 ```

@@ -426,9 +964,9 @@ Check requirements against goals.
 ### Design Principles

 1. **Keep steps focused** - Single goal per step
-2. **Limit scope** - 5-10 steps maximum
+2. **Limit scope** - 5-12 steps maximum
 3. **Build progressively** - Start simple, add detail
-4. **Checkpoint often** - Save after major sections
+4. **Checkpoint often** - Save after major workflow sections and ensure documents are being drafted from the start
 5. **Make sections optional** - Let users skip when appropriate

 ### Instruction Guidelines
@@ -502,7 +1040,7 @@ Web bundles allow workflows to be deployed as self-contained packages for web en

 ### Creating a Web Bundle

-Add this section to your workflow.yaml:
+Add this section to your workflow.yaml ensuring critically all dependant files or workflows are listed:

 ```yaml
 web_bundle:
@@ -561,6 +1099,8 @@ web_bundle:
  # Sub-workflow reference
  validation_workflow: 'bmad/bmm/workflows/validate-requirements/workflow.yaml'

+  standalone: true
+
  web_bundle_files:
    # Core workflow files
    - 'bmad/bmm/workflows/analyze-requirements/instructions.md'
@@ -599,14 +1139,9 @@ web_bundle:

 - Combine related steps
 - Make sections optional
+- Create multiple focused workflows with a parent orchestration
 - Reduce elicitation points

-### User Confusion
-
- Add clearer step goals
- Provide more examples
- Explain section purpose
-
 ---

 _For implementation details, see:_
--- a/bmad/bmb/workflows/create-workflow/workflow-template/workflow.yaml.bak
+++ b/bmad/bmb/workflows/create-workflow/workflow-template/workflow.yaml.bak
@@ -0,0 +1,39 @@
+# {TITLE} Workflow Template Configuration
+name: "{WORKFLOW_CODE}"
+description: "{WORKFLOW_DESCRIPTION}"
+author: "BMad"
+
+# Critical variables load from config_source
+# Add Additional Config Pulled Variables Here
+config_source: "{project-root}/{module-code}/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Required Data Files - HALT if missing!
+# optional, can be omitted
+brain_techniques: "{installed_path}/{critical-data-file.csv}" # example, can be other formats or URLs
+
+# Optional docs that if loaded on start to kickstart this workflow or used at some point, these are meant to be suggested inputs for the user
+recommended_inputs: # optional, can be omitted
+  - example_input: "{project-root}/{path/to/file.md}"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/{module-code}/workflows/{workflow-code}"
+template: "{installed_path}/template.md" # optional, can be omitted
+instructions: "{installed_path}/instructions.md" # optional, can be omitted
+validation: "{installed_path}/checklist.md" # optional, can be omitted
+
+# Output configuration
+default_output_file: "{output_folder}/{file.md}" # optional, can be omitted
+validation_output_file: "{output_folder}/{file-validation-report.md}" # optional, can be omitted
+
+# Tool Requirements (MCP Required Tools or other tools needed to run this workflow)
+required_tools: #optional, can be omitted
+  - "Tool Name": #example, can be omitted if none
+      description: "Description of why this tool is needed"
+      link: "https://link-to-tool.com"
+# Web Bundle Configuration (optional - for web-deployable workflows)
+# IMPORTANT: Web bundles are self-contained and cannot use config_source variables
+# All referenced files must be listed in web_bundle_files
--- a/bmad/bmb/workflows/create-workflow/workflow.yaml
+++ b/bmad/bmb/workflows/create-workflow/workflow.yaml
@@ -35,4 +35,6 @@ workflow_template_path: "{installed_path}/workflow-template"
 # If standalone workflow: Save to custom_workflow_location/{{workflow_name}}
 module_output_folder: "{project-root}/bmad/{{target_module}}/workflows/{{workflow_name}}"
 standalone_output_folder: "{custom_workflow_location}/{{workflow_name}}"
+
+standalone: true
 # Web bundle configuration
--- a/bmad/bmb/workflows/create-workflow/workflow.yaml.bak
+++ b/bmad/bmb/workflows/create-workflow/workflow.yaml.bak
@@ -0,0 +1,38 @@
+# Build Workflow - Workflow Builder Configuration
+name: create-workflow
+description: "Interactive workflow builder that guides creation of new BMAD workflows with proper structure and validation for optimal human-AI collaboration. Includes optional brainstorming phase for workflow ideas and design."
+author: "BMad Builder"
+
+# Critical variables
+config_source: "{project-root}/bmad/bmb/config.yaml"
+custom_workflow_location: "{config_source}:custom_workflow_location"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+
+# Template files for new workflows
+template_workflow_yaml: "{workflow_template_path}/workflow.yaml"
+template_instructions: "{workflow_template_path}/instructions.md"
+template_template: "{workflow_template_path}/template.md"
+template_checklist: "{workflow_template_path}/checklist.md"
+
+# Optional input docs
+recommended_inputs:
+  - existing_workflows: "{project-root}/bmad/*/workflows/"
+  - bmm_workflows: "{project-root}/bmad/bmm/workflows/"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/create-workflow"
+template: false # This is an action workflow - no template needed
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Required data files - CRITICAL for workflow conventions
+workflow_creation_guide: "{installed_path}/workflow-creation-guide.md"
+workflow_template_path: "{installed_path}/workflow-template"
+
+# Output configuration - Creates the new workflow folder with all files
+# If workflow belongs to a module: Save to module's workflows folder
+# If standalone workflow: Save to custom_workflow_location/{{workflow_name}}
+module_output_folder: "{project-root}/bmad/{{target_module}}/workflows/{{workflow_name}}"
+standalone_output_folder: "{custom_workflow_location}/{{workflow_name}}"
+# Web bundle configuration
--- a/bmad/bmb/workflows/edit-agent/README.md
+++ b/bmad/bmb/workflows/edit-agent/README.md
@@ -0,0 +1,112 @@
+# Edit Agent Workflow
+
+Interactive workflow for editing existing BMAD Core agents while maintaining best practices and conventions.
+
+## Purpose
+
+This workflow helps you refine and improve existing agents by:
+
+- Analyzing agents against BMAD Core best practices
+- Identifying issues and improvement opportunities
+- Providing guided editing for specific aspects
+- Validating changes against agent standards
+- Ensuring consistency with agent architecture
+
+## When to Use
+
+Use this workflow when you need to:
+
+- Fix issues in existing agents
+- Add new menu items or workflows
+- Improve agent persona or communication style
+- Update configuration handling
+- Convert between agent types (full/hybrid/standalone)
+- Optimize agent structure and clarity
+
+## What You'll Need
+
+- Path to the agent file you want to edit (.yaml or .md)
+- Understanding of what changes you want to make
+- Access to the agent documentation (loaded automatically)
+
+## Workflow Steps
+
+1. **Load and analyze target agent** - Provide path to agent file
+2. **Analyze against best practices** - Automatic audit of agent structure
+3. **Select editing focus** - Choose what aspect to edit
+4. **Load relevant documentation** - Auto-loads guides based on your choice
+5. **Perform edits** - Review and approve changes iteratively
+6. **Validate all changes** - Comprehensive validation checklist
+7. **Generate change summary** - Summary of improvements made
+
+## Editing Options
+
+The workflow provides 12 focused editing options:
+
+1. **Fix critical issues** - Address broken references, syntax errors
+2. **Add/fix standard config** - Ensure config loading and variable usage
+3. **Refine persona** - Improve role, communication style, principles
+4. **Update activation** - Modify activation steps and greeting
+5. **Manage menu items** - Add, remove, or reorganize commands
+6. **Update workflow references** - Fix paths, add new workflows
+7. **Enhance menu handlers** - Improve handler logic
+8. **Improve command triggers** - Refine asterisk commands
+9. **Optimize agent type** - Convert between full/hybrid/standalone
+10. **Add new capabilities** - Add menu items, workflows, features
+11. **Remove bloat** - Delete unused commands, redundant instructions
+12. **Full review and update** - Comprehensive improvements
+
+## Agent Documentation Loaded
+
+This workflow automatically loads:
+
+- **Agent Types Guide** - Understanding full, hybrid, and standalone agents
+- **Agent Architecture** - Structure, activation, and menu patterns
+- **Command Patterns** - Menu handlers and command triggers
+- **Communication Styles** - Persona and communication guidance
+- **Workflow Execution Engine** - How agents execute workflows
+
+## Output
+
+The workflow modifies your agent file in place, maintaining the original format (YAML or markdown). Changes are reviewed and approved by you before being applied.
+
+## Best Practices
+
+- **Start with analysis** - Let the workflow audit your agent first
+- **Focus your edits** - Choose specific aspects to improve
+- **Review each change** - Approve or modify proposed changes
+- **Validate thoroughly** - Use the validation step to catch issues
+- **Test after editing** - Invoke the edited agent to verify it works
+
+## Tips
+
+- If you're unsure what needs improvement, choose option 12 (Full review)
+- For quick fixes, choose the specific option (like option 6 for workflow paths)
+- The workflow loads documentation automatically - you don't need to read it first
+- You can make multiple rounds of edits in one session
+- Use the validation step to ensure you didn't miss anything
+
+## Related Workflows
+
+- **create-agent** - Create new agents from scratch
+- **edit-workflow** - Edit workflows referenced by agents
+- **audit-workflow** - Audit workflows for compliance
+
+## Example Usage
+
+```
+User: I want to add a new workflow to the PM agent
+Workflow: Analyzes agent → Loads it → You choose option 5 (manage menu items)
+          → Adds new menu item with workflow reference → Validates → Done
+```
+
+## Activation
+
+Invoke via BMad Builder agent:
+
+```
+/bmad:bmb:agents:bmad-builder
+Then select: *edit-agent
+```
+
+Or directly via workflow.xml with this workflow config.
--- a/bmad/bmb/workflows/edit-agent/checklist.md
+++ b/bmad/bmb/workflows/edit-agent/checklist.md
@@ -0,0 +1,112 @@
+# Edit Agent - Validation Checklist
+
+Use this checklist to validate agent edits meet BMAD Core standards.
+
+## Agent Structure Validation
+
+- [ ] Agent file format is valid (YAML or markdown/XML)
+- [ ] Agent type is clearly identified (full, hybrid, standalone)
+- [ ] File naming follows convention: `{agent-name}.agent.yaml` or `{agent-name}.agent.md`
+
+## Persona Validation
+
+- [ ] Role is clearly defined and specific
+- [ ] Identity/purpose articulates what the agent does
+- [ ] Communication style is specified (if custom style desired)
+- [ ] Principles are listed and actionable (if applicable)
+
+## Activation Validation
+
+- [ ] Step 1: Loads persona from current agent file
+- [ ] Step 2: Loads config file (if agent needs user context)
+- [ ] Step 3: Sets user context variables (user_name, etc.)
+- [ ] Step 4: Displays greeting using user_name and shows menu
+- [ ] Step 5: WAITs for user input (doesn't auto-execute)
+- [ ] Step 6: Processes user selection (number or trigger text)
+- [ ] Step 7: Executes appropriate menu handler
+
+## Menu Validation
+
+- [ ] All menu items numbered sequentially
+- [ ] Each item has cmd attribute with asterisk trigger (*help, *create, etc.)
+- [ ] Workflow paths are correct (if workflow attribute present)
+- [ ] Help command is present (\*help)
+- [ ] Exit command is present (\*exit)
+- [ ] Menu items are in logical order
+
+## Configuration Validation
+
+- [ ] Config file path is correct for module
+- [ ] Config variables loaded in activation step 2
+- [ ] Error handling present if config fails to load
+- [ ] user_name used in greeting and communication
+- [ ] communication_language used for output
+- [ ] output_folder used for file outputs (if applicable)
+
+## Menu Handler Validation
+
+- [ ] menu-handlers section is present
+- [ ] Workflow handler loads {project-root}/bmad/core/tasks/workflow.xml
+- [ ] Workflow handler passes yaml path as 'workflow-config' parameter
+- [ ] Handlers check for attributes (workflow, exec, tmpl, data, action)
+- [ ] Handler logic is complete and follows patterns
+
+## Workflow Integration Validation
+
+- [ ] All workflow paths exist and are correct
+- [ ] Workflow paths use {project-root} variable
+- [ ] Workflows are appropriate for agent's purpose
+- [ ] Workflow parameters are passed correctly
+
+## Communication Validation
+
+- [ ] Agent communicates in {communication_language}
+- [ ] Communication style matches persona
+- [ ] Error messages are clear and helpful
+- [ ] Confirmation messages for user actions
+
+## Rules Validation
+
+- [ ] Rules section defines agent behavior clearly
+- [ ] File loading rules are specified
+- [ ] Menu trigger format rules are clear
+- [ ] Communication rules align with persona
+
+## Quality Checks
+
+- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, etc.)
+- [ ] No broken references or missing files
+- [ ] Syntax is valid (YAML or XML)
+- [ ] Indentation is consistent
+- [ ] Agent purpose is clear from reading persona alone
+
+## Type-Specific Validation
+
+### Full Agent
+
+- [ ] Has complete menu system with multiple items
+- [ ] Loads config file for user context
+- [ ] Supports multiple workflows
+- [ ] Session management is clear
+
+### Hybrid Agent
+
+- [ ] Simplified activation (may skip some steps)
+- [ ] Focused set of workflows
+- [ ] May or may not have menu
+- [ ] Config loading is appropriate
+
+### Standalone Agent
+
+- [ ] Single focused purpose
+- [ ] Minimal activation (1-3 steps)
+- [ ] No menu system
+- [ ] Direct execution pattern
+- [ ] May not need config file
+
+## Final Checks
+
+- [ ] Agent file has been saved
+- [ ] File path is in correct module directory
+- [ ] Agent is ready for testing
+- [ ] Documentation is updated (if needed)
--- a/bmad/bmb/workflows/edit-agent/instructions.md
+++ b/bmad/bmb/workflows/edit-agent/instructions.md
@@ -0,0 +1,290 @@
+# Edit Agent - Agent Editor Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
+<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<step n="1" goal="Load and deeply understand the target agent">
+<ask>What is the path to the agent you want to edit?</ask>
+
+<action>Load the agent file from the provided path</action>
+<action>Load ALL agent documentation to inform understanding:
+
+- Agent types guide: {agent_types}
+- Agent architecture: {agent_architecture}
+- Command patterns: {agent_commands}
+- Communication styles: {communication_styles}
+- Workflow execution engine: {workflow_execution_engine}
+  </action>
+
+<action>Analyze the agent structure thoroughly:
+
+- Parse persona (role, identity, communication_style, principles)
+- Understand activation flow and steps
+- Map menu items and their workflows
+- Identify configuration dependencies
+- Assess agent type (full, hybrid, standalone)
+- Check workflow references for validity
+- Evaluate against best practices from loaded guides
+  </action>
+
+<action>Reflect understanding back to {user_name}:
+
+Present a warm, conversational summary adapted to the agent's complexity:
+
+- What this agent does (its role and purpose)
+- How it's structured (type, menu items, workflows)
+- What you notice (strengths, potential improvements, issues)
+- Your initial assessment of its health
+
+Be conversational, not clinical. Help {user_name} see their agent through your eyes.
+</action>
+
+<ask>Does this match your understanding of what this agent should do?</ask>
+<template-output>agent_understanding</template-output>
+</step>
+
+<step n="2" goal="Discover improvement goals collaboratively">
+<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
+
+<action>Engage in collaborative discovery:
+
+Ask open-ended questions to understand their goals:
+
+- What prompted you to want to edit this agent?
+- What isn't working the way you'd like?
+- Are there specific behaviors you want to change?
+- Is there functionality you want to add or remove?
+- How do users interact with this agent? What feedback have they given?
+
+Listen for clues about:
+
+- Functional issues (broken references, missing workflows)
+- User experience issues (confusing menu, unclear communication)
+- Performance issues (too slow, too verbose, not adaptive enough)
+- Maintenance issues (hard to update, bloated, inconsistent)
+- Integration issues (doesn't work well with other agents/workflows)
+  </action>
+
+<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
+
+Organize by priority and user goals:
+
+- CRITICAL issues blocking functionality
+- IMPORTANT improvements enhancing user experience
+- NICE-TO-HAVE enhancements for polish
+
+Present these conversationally, explaining WHY each matters and HOW it would help.
+</action>
+
+<action>Collaborate on priorities:
+
+Don't just list options - discuss them:
+
+- "I noticed {{issue}} - this could cause {{problem}}. Does this concern you?"
+- "The agent could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
+- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
+
+Let the conversation flow naturally. Build a shared vision of what "better" looks like.
+</action>
+
+<template-output>improvement_goals</template-output>
+</step>
+
+<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
+<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
+
+<action>For each improvement area, facilitate collaboratively:
+
+1. **Explain the current state and why it matters**
+   - Show relevant sections of the agent
+   - Explain how it works now and implications
+   - Connect to user's goals from step 2
+
+2. **Propose improvements with rationale**
+   - Suggest specific changes that align with best practices
+   - Explain WHY each change helps
+   - Provide examples from the loaded guides when helpful
+   - Show before/after comparisons for clarity
+
+3. **Collaborate on the approach**
+   - Ask if the proposed change addresses their need
+   - Invite modifications or alternative approaches
+   - Explain tradeoffs when relevant
+   - Adapt based on their feedback
+
+4. **Apply changes iteratively**
+   - Make one focused improvement at a time
+   - Show the updated section
+   - Confirm it meets their expectation
+   - Move to next improvement or refine current one
+     </action>
+
+<action>Common improvement patterns to facilitate:
+
+**If fixing broken references:**
+
+- Identify all broken paths
+- Explain what each reference should point to
+- Verify new paths exist before updating
+- Update and confirm working
+
+**If refining persona/communication:**
+
+- Review current persona definition
+- Discuss desired communication style with examples
+- Explore communication styles guide for patterns
+- Refine language to match intent
+- Test tone with example interactions
+
+**If updating activation:**
+
+- Walk through current activation flow
+- Identify bottlenecks or confusion points
+- Propose streamlined flow
+- Ensure config loading works correctly
+- Verify all session variables are set
+
+**If managing menu items:**
+
+- Review current menu organization
+- Discuss if structure serves user mental model
+- Add/remove/reorganize as needed
+- Ensure all workflow references are valid
+- Update triggers to be intuitive
+
+**If enhancing menu handlers:**
+
+- Explain current handler logic
+- Identify where handlers could be smarter
+- Propose enhanced logic based on agent architecture patterns
+- Ensure handlers properly invoke workflows
+
+**If optimizing agent type:**
+
+- Discuss whether current type fits use case
+- Explain characteristics of full/hybrid/standalone
+- If converting, guide through structural changes
+- Ensure all pieces align with new type
+  </action>
+
+<action>Throughout improvements, educate when helpful:
+
+Share insights from the guides naturally:
+
+- "The agent architecture guide suggests {{pattern}} for this scenario"
+- "Looking at the command patterns, we could use {{approach}}"
+- "The communication styles guide has a great example of {{technique}}"
+
+Connect improvements to broader BMAD principles without being preachy.
+</action>
+
+<ask>After each significant change:
+
+- "Does this feel right for what you're trying to achieve?"
+- "Want to refine this further, or move to the next improvement?"
+- "Is there anything about this change that concerns you?"
+  </ask>
+
+<template-output>improvement_implementation</template-output>
+</step>
+
+<step n="4" goal="Validate improvements holistically">
+<action>Run comprehensive validation conversationally:
+
+Don't just check boxes - explain what you're validating and why it matters:
+
+- "Let me verify all the workflow paths resolve correctly..."
+- "Checking that the activation flow works smoothly..."
+- "Making sure menu handlers are wired up properly..."
+- "Validating config loading is robust..."
+  </action>
+
+<action>Load validation checklist: {installed_path}/checklist.md</action>
+<action>Check all items from checklist systematically</action>
+
+<check if="validation_issues_found">
+  <action>Present issues conversationally:
+
+Explain what's wrong and implications:
+
+- "I found {{issue}} which could cause {{problem}}"
+- "The {{component}} needs {{fix}} because {{reason}}"
+
+Propose fixes immediately:
+
+- "I can fix this by {{solution}}. Should I?"
+- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
+  </action>
+
+<action>Fix approved issues and re-validate</action>
+</check>
+
+<check if="validation_passes">
+  <action>Confirm success warmly:
+
+"Excellent! Everything validates cleanly:
+
+- All paths resolve correctly
+- Activation flow is solid
+- Menu structure is clear
+- Handlers work properly
+- Config loading is robust
+
+Your agent is in great shape."
+</action>
+</check>
+
+<template-output>validation_results</template-output>
+</step>
+
+<step n="5" goal="Review improvements and guide next steps">
+<action>Create a conversational summary of what improved:
+
+Tell the story of the transformation:
+
+- "We started with {{initial_state}}"
+- "You wanted to {{user_goals}}"
+- "We made these key improvements: {{changes_list}}"
+- "Now your agent {{improved_capabilities}}"
+
+Highlight the impact:
+
+- "This means users will experience {{benefit}}"
+- "The agent is now more {{quality}}"
+- "It follows best practices for {{patterns}}"
+  </action>
+
+<action>Guide next steps based on changes made:
+
+If significant structural changes:
+
+- "Since we restructured the activation, you should test the agent with a real user interaction"
+
+If workflow references changed:
+
+- "The agent now uses {{new_workflows}} - make sure those workflows are up to date"
+
+If this is part of larger module work:
+
+- "This agent is part of {{module}} - consider if other agents need similar improvements"
+
+Be a helpful guide to what comes next, not just a task completer.
+</action>
+
+<ask>Would you like to:
+
+- Test the edited agent by invoking it
+- Edit another agent
+- Make additional refinements to this one
+- Return to your module work
+  </ask>
+
+<template-output>completion_summary</template-output>
+</step>
+
+</workflow>
--- a/bmad/bmb/workflows/edit-agent/workflow.yaml
+++ b/bmad/bmb/workflows/edit-agent/workflow.yaml
@@ -0,0 +1,33 @@
+# Edit Agent - Agent Editor Configuration
+name: "edit-agent"
+description: "Edit existing BMAD agents while following all best practices and conventions"
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/bmb/config.yaml"
+communication_language: "{config_source}:communication_language"
+user_name: "{config_source}:user_name"
+
+# Required Data Files - Critical for understanding agent conventions
+agent_types: "{project-root}/bmad/bmb/workflows/create-agent/agent-types.md"
+agent_architecture: "{project-root}/bmad/bmb/workflows/create-agent/agent-architecture.md"
+agent_commands: "{project-root}/bmad/bmb/workflows/create-agent/agent-command-patterns.md"
+communication_styles: "{project-root}/bmad/bmb/workflows/create-agent/communication-styles.md"
+
+# Workflow execution engine reference
+workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.xml"
+
+# Optional docs that can be used to understand the target agent
+recommended_inputs:
+  - target_agent: "Path to the agent.yaml or agent.md file to edit"
+  - example_agents: "{project-root}/bmad/bmm/agents/"
+  - agent_activation_rules: "{project-root}/src/utility/models/agent-activation-ide.xml"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/edit-agent"
+template: false # This is an action workflow - no template needed
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+standalone: true
+# Web bundle configuration
--- a/bmad/bmb/workflows/edit-module/README.md
+++ b/bmad/bmb/workflows/edit-module/README.md
@@ -0,0 +1,187 @@
+# Edit Module Workflow
+
+Interactive workflow for editing existing BMAD modules, including structure, agents, workflows, configuration, and documentation.
+
+## Purpose
+
+This workflow helps you improve and maintain BMAD modules by:
+
+- Analyzing module structure against best practices
+- Managing agents and workflows within the module
+- Updating configuration and documentation
+- Ensuring cross-module integration works correctly
+- Maintaining installer configuration (for source modules)
+
+## When to Use
+
+Use this workflow when you need to:
+
+- Add new agents or workflows to a module
+- Update module configuration
+- Improve module documentation
+- Reorganize module structure
+- Set up cross-module workflow sharing
+- Fix issues in module organization
+- Update installer configuration
+
+## What You'll Need
+
+- Path to the module directory you want to edit
+- Understanding of what changes you want to make
+- Access to module documentation (loaded automatically)
+
+## Workflow Steps
+
+1. **Load and analyze target module** - Provide path to module directory
+2. **Analyze against best practices** - Automatic audit of module structure
+3. **Select editing focus** - Choose what aspect to edit
+4. **Load relevant documentation and tools** - Auto-loads guides and workflows
+5. **Perform edits** - Review and approve changes iteratively
+6. **Validate all changes** - Comprehensive validation checklist
+7. **Generate change summary** - Summary of improvements made
+
+## Editing Options
+
+The workflow provides 12 focused editing options:
+
+1. **Fix critical issues** - Address missing files, broken references
+2. **Update module config** - Edit config.yaml fields
+3. **Manage agents** - Add, edit, or remove agents
+4. **Manage workflows** - Add, edit, or remove workflows
+5. **Update documentation** - Improve README files and guides
+6. **Reorganize structure** - Fix directory organization
+7. **Add new agent** - Create and integrate new agent
+8. **Add new workflow** - Create and integrate new workflow
+9. **Update installer** - Modify installer configuration (source only)
+10. **Cross-module integration** - Set up workflow sharing with other modules
+11. **Remove deprecated items** - Delete unused agents, workflows, or files
+12. **Full module review** - Comprehensive analysis and improvements
+
+## Integration with Other Workflows
+
+This workflow integrates with:
+
+- **edit-agent** - For editing individual agents
+- **edit-workflow** - For editing individual workflows
+- **create-agent** - For adding new agents
+- **create-workflow** - For adding new workflows
+
+When you select options to manage agents or workflows, the appropriate specialized workflow is invoked automatically.
+
+## Module Structure
+
+A proper BMAD module has:
+
+```
+module-code/
+├── agents/              # Agent definitions
+│   └── *.agent.yaml
+├── workflows/           # Workflow definitions
+│   └── workflow-name/
+│       ├── workflow.yaml
+│       ├── instructions.md
+│       ├── checklist.md
+│       └── README.md
+├── config.yaml          # Module configuration
+└── README.md           # Module documentation
+```
+
+## Standard Module Config
+
+Every module config.yaml should have:
+
+```yaml
+module_name: 'Full Module Name'
+module_code: 'xyz'
+user_name: 'User Name'
+communication_language: 'english'
+output_folder: 'path/to/output'
+```
+
+Optional fields may be added for module-specific needs.
+
+## Cross-Module Integration
+
+Modules can share workflows:
+
+```yaml
+# In agent menu item:
+workflow: '{project-root}/bmad/other-module/workflows/shared-workflow/workflow.yaml'
+```
+
+Common patterns:
+
+- BMM uses CIS brainstorming workflows
+- All modules can use core workflows
+- Modules can invoke each other's workflows
+
+## Output
+
+The workflow modifies module files in place, including:
+
+- config.yaml
+- Agent files
+- Workflow files
+- README and documentation files
+- Directory structure (if reorganizing)
+
+Changes are reviewed and approved by you before being applied.
+
+## Best Practices
+
+- **Start with analysis** - Let the workflow audit your module first
+- **Use specialized workflows** - Let edit-agent and edit-workflow handle detailed edits
+- **Update documentation** - Keep README files current with changes
+- **Validate thoroughly** - Use the validation step to catch structural issues
+- **Test after editing** - Invoke agents and workflows to verify they work
+
+## Tips
+
+- For adding agents/workflows, use options 7-8 to create and integrate in one step
+- For quick config changes, use option 2 (update module config)
+- Cross-module integration (option 10) helps set up workflow sharing
+- Full module review (option 12) is great for inherited or legacy modules
+- The workflow handles path updates when you reorganize structure
+
+## Source vs Installed Modules
+
+**Source modules** (in src/modules/):
+
+- Have installer files in tools/cli/installers/
+- Can configure web bundles
+- Are the development source of truth
+
+**Installed modules** (in bmad/):
+
+- Are deployed to target projects
+- Use config.yaml for user customization
+- Are compiled from source during installation
+
+This workflow works with both, but installer options only apply to source modules.
+
+## Example Usage
+
+```
+User: I want to add a new workflow to BMM for API design
+Workflow: Analyzes BMM → You choose option 8 (add new workflow)
+          → Invokes create-workflow → Creates workflow
+          → Integrates it into module → Updates README → Done
+```
+
+## Activation
+
+Invoke via BMad Builder agent:
+
+```
+/bmad:bmb:agents:bmad-builder
+Then select: *edit-module
+```
+
+Or directly via workflow.xml with this workflow config.
+
+## Related Resources
+
+- **Module Structure Guide** - Comprehensive module architecture documentation
+- **BMM Module** - Example of full-featured module
+- **BMB Module** - Example of builder/tooling module
+- **CIS Module** - Example of workflow library module
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Brian Madison	d4879d373b	6.0.0-alpha.3	2025-10-30 11:37:03 -05:00
Brian Madison	663b76a072	docs updates	2025-10-30 11:26:15 -05:00
Brian Madison	ec111972a0	some output should be improved and not run together in chat windows	2025-10-30 08:13:18 -05:00
Brian Madison	6d7f42dbec	v6 greenfield quickstart guide	2025-10-29 22:39:13 -05:00
Brian Madison	519e2f3d59	manifest version comes from package	2025-10-29 20:04:04 -05:00
Brian Madison	d6036e18dd	docs: fix v4 branch link in readme	2025-10-29 09:38:26 -05:00
Brian Madison	6d2b6810c2	fix: preserve user's cwd when running via npx	2025-10-29 09:31:38 -05:00
Brian Madison	06dab16a75	6.0.0-alpha.2	2025-10-29 09:14:03 -05:00
Brian Madison	5a70512a30	chore: remove version prompt from npx installer	2025-10-29 09:12:27 -05:00
Brian Madison	b05f4751d7	6.0.0-alpha.1	2025-10-29 08:35:02 -05:00
Brian Madison	b5262f78ee	still alpha	2025-10-29 08:34:48 -05:00
Brian Madison	5ee57ea8df	cleanup a few more items	2025-10-29 08:19:11 -05:00
Brian Madison	fd620d0183	marked sm menu items as optional that are optional	2025-10-28 23:47:48 -05:00
Brian Madison	ad8717845d	cline workflows added to support slash commands	2025-10-28 23:16:48 -05:00
Brian Madison	503a394218	party mode fix	2025-10-28 22:52:03 -05:00
jheyworth	8376ca0ba2	fix: add CommonMark-compliant markdown formatting rules (#830 ) * fix: add CommonMark-compliant markdown formatting rules to workflow Problem: -------- BMAD generates markdown that violates CommonMark specification by omitting required blank lines around lists, tables, and code blocks. While GitHub's renderer (GFM) handles this gracefully, strict parsers like Mac Markdown.app break completely, rendering lists as plain text and losing document structure. Solution: --------- Add 6 mandatory markdown formatting rules to workflow.xml (line 73) that enforce proper spacing and consistency: 1. ALWAYS add blank line before and after bullet lists 2. ALWAYS add blank line before and after numbered lists 3. ALWAYS add blank line before and after tables 4. ALWAYS add blank line before and after code blocks 5. Use - for bullets consistently (not * or +) 6. Use language identifier for code fences Impact: ------- - Makes BMAD output CommonMark compliant - Ensures compatibility with ALL markdown parsers, not just GitHub - Follows industry best practices for professional documentation - Future-proofs against stricter parser implementations - Zero content changes - only formatting improved Testing: -------- Comprehensive three-phase testing completed: - Phase 1: Synthetic test validating fix mechanism - Phase 2: Fresh install end-to-end test (API Gateway project) - Phase 3: GitHub validation with visual proof Results: 1,112 lines of formatting improvements, 0 content changes, 100% CommonMark compliance achieved. Test Evidence: -------------- Complete test repository with before/after comparison, Mac Markdown.app screenshot proving the issue, and comprehensive documentation: https://github.com/jheyworth/bmad-markdown-formatting-test See TEST.md for full documentation, test methodology, and evidence. 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Remove TEST.md per maintainer feedback As requested by @bmadcode - the test documentation was useful during review but is not needed in the repository. Testing evidence remains documented in the PR description and external test repository. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>	2025-10-28 22:27:48 -05:00
Brian Madison	44bc96fadc	readme update	2025-10-28 22:27:23 -05:00
Brian Madison	7710d9941d	document-project moved out of phase 1 to right below workflows and documents updated to clarify its not a phase-0 but a prereq and also a post project tool to use.	2025-10-28 22:21:13 -05:00
Brian Madison	1cfd58ebb1	installer for delete and replace fixed	2025-10-28 21:44:04 -05:00
Brian Madison	1c5b30f361	some v5 references lingered - change to v6	2025-10-28 20:32:08 -05:00
Brian Madison	d9c7980b1d	remove unused csv columns from cis	2025-10-28 19:17:44 -05:00
Brian Madison	95b875792b	remove tts again	2025-10-28 19:12:10 -05:00
Brian Madison	0ee4fa920a	installer fixed to not add game assets to slash commands in some ides that read from the manifest. and fixed the manifest.	2025-10-28 19:09:43 -05:00
Brian Madison	e93b208902	file cleanup	2025-10-28 17:22:31 -05:00
Brian Madison	3fff30ca61	opencode moved agents back to agent folder	2025-10-28 17:18:53 -05:00
Brian Madison	ee58586f39	installer improvements	2025-10-28 12:47:45 -05:00
Brian Madison	ed3603f7b2	vast improvements to create story, review story, draft story checklist validation, sm menu items and dev agent menu items fixed	2025-10-28 10:03:19 -05:00
Brian Madison	0354d1ae45	story review was missing detailed instructions to review AC and task adherance.	2025-10-28 08:51:58 -05:00
Brian Madison	0dab278e7b	story-review renamed code-review and dev-agent performs this	2025-10-28 08:30:44 -05:00
Brian Madison	66c66f602d	all workflows can optionally run without a workflow	2025-10-27 23:51:22 -05:00
Brian Madison	7ad841964d	installer for bmm includes option to include game assets or not when adding to a project.	2025-10-27 22:38:34 -05:00
Brian Madison	f55e822338	brownfield guide draft	2025-10-27 21:18:55 -05:00
Brian Madison	24a2271520	update open items list	2025-10-27 18:27:10 -05:00
Brian Madison	a484b9975c	claude code flattened commands	2025-10-27 15:18:22 -05:00
Brian Madison	913ec47123	fix: CSV column mismatch when upgrading manifest schemas When preserving CSV rows from existing manifest files during module updates, rows from older schema versions (without the 'standalone' column) were being added to CSVs with new schema headers, causing "Invalid Record Length" errors during parsing. Added schema upgrade logic to detect old column structure and upgrade preserved rows by adding missing columns with appropriate default values. This ensures all CSV rows match the header column count, fixing installation errors. Fixes column count mismatch in: - workflow-manifest.csv (added standalone column) - task-manifest.csv (added standalone column) - tool-manifest.csv (added standalone column) - agent-manifest.csv (schema validation for future-proofing)	2025-10-27 15:00:57 -05:00
Brian Madison	8ed721d029	npx with version selector	2025-10-26 23:42:56 -05:00
Brian Madison	334e24823a	doc updates	2025-10-26 23:25:48 -05:00
Brian Madison	b753fb293b	workflows tasks and tools can be configured wether they are able to be run standalone from agents with ide commands	2025-10-26 20:06:34 -05:00
Brian Madison	63ef5b7bc6	installer fixes	2025-10-26 19:38:38 -05:00
Brian Madison	1cb88728e8	installer fixes	2025-10-26 17:04:27 -05:00
Brian Madison	8d81edf847	install quick updates	2025-10-26 16:17:37 -05:00
Brian Madison	0067fb4880	path fixes, documentation updates, md-xplodr added to core tools	2025-10-26 15:40:43 -05:00
Cameron Pitt	8220c819e6	Add Opencode IDE installer (#820 ) - Added docs/ide-info/opencode.md - Added tool/cli/installers/lib/ide/opencode.js - Modified tools/installers/lib/ide/core/detector.js to include detection for opencode command dir - Modified tools/cli/platform-codes.yaml to include opencode config - Modified tools/cli/installers/lib/ide/workflow-command-template.md to include frontmatter with description as opencode requires this for commands and adding it to the template by default does not seem to impact other IDEs - Modified src/modules/bmm/workflows/workflow-status/workflow.yaml description so that it properly escapes quotes when interpolated in the teplate	2025-10-26 11:16:57 -05:00
Brian Madison	b7e6bfcde5	a few more instruction cleanup items	2025-10-25 23:57:27 -05:00
Brian Madison	bfd49faf2d	tech context improved	2025-10-25 23:29:41 -05:00
Brian Madison	52b8edb01d	phase 4 more workflow cleanup	2025-10-25 19:25:28 -05:00
Brian Madison	061b7d94c4	status normalization	2025-10-25 15:41:13 -05:00
Brian Madison	5762941321	better status loading and updating for phase 4	2025-10-25 14:26:30 -05:00
Brian Madison	994f251687	workflow phase 4 only has single sprint planning item in it now	2025-10-25 10:44:46 -05:00
Brian Madison	cf13e81dd5	sprint plan clearer comments	2025-10-25 00:30:49 -05:00
Brian Madison	92bff333b1	plan-project gone, and all level 1-3 workflows are dynamic from the workflow in suggesting what is next	2025-10-24 23:16:08 -05:00
Brian Madison	f37c960a4d	validation tasks added	2025-10-23 23:20:48 -05:00
Brian Madison	2d297c82da	fix create-design workflow path	2025-10-23 15:58:05 -05:00
Brian Madison	a175f46f1b	create-ux-design refactor	2025-10-23 14:20:13 -05:00
Brian Madison	44e09e4487	ux expert -> ux designer	2025-10-22 16:58:18 -05:00
Brian Madison	be5556bf42	checks checked	2025-10-22 15:40:51 -05:00
Brian Madison	be5b06f55e	check alignment	2025-10-22 12:36:39 -05:00
Brian Madison	c8776aa9ac	inline tag reference updtges	2025-10-21 23:48:35 -05:00
Brian Madison	ddaefa3284	use sprint plan for al workflow level 4 implementations	2025-10-21 23:03:46 -05:00
Brian Madison	abaa24513a	sprint status helpers, remove workflow integration from phase 4 items in prep of using sprint-planning status	2025-10-21 22:25:26 -05:00
Brian Madison	71330b6aac	updates to the paths	2025-10-21 20:37:59 -05:00
Brian Madison	949d818db8	sprint status story location relative	2025-10-21 18:41:40 -05:00
Brian Madison	1b1947d240	sprint-planning placeholder for future integration with jira linear and trello	2025-10-21 18:13:34 -05:00
Brian Madison	419043e704	sprint planning	2025-10-21 08:24:02 -05:00
Brian Madison	b8db0806ed	architecture name standardization	2025-10-20 19:01:18 -05:00
Tiki	60475ac6f8	feat(tools/cli): Refactor Qwen IDE configuration logic to support modular command structure (#762 ) - Unify BMad directory name from 'BMad' to lowercase 'bmad' - Use shared utility functions [getAgentsFromBmad] and [getTasksFromBmad] to fetch agents and tasks - Create independent subdirectory structures (agents, tasks) for each module - Update file writing paths to store TOML files by module classification - Remove legacy QWEN.md merged documentation generation logic - Add TOML metadata header support (not available in previous versions) - Clean up old version configuration directories (including uppercase BMad and bmad-method)	2025-10-20 08:34:42 -05:00
Alex Verkhovsky	69d1f75435	fix: remove empty tasks directories from Claude Code installer (#776 ) Previously, the installer created empty tasks/ directories under .claude/commands/bmad/{module}/ and attempted to copy task files. Since getTasksFromDir() filters for .md files only and all actual tasks are .xml files, these directories remained empty. Tasks are utility files referenced by agents via exec attributes (e.g., exec="{project-root}/bmad/core/tasks/workflow.xml") and should remain in the bmad/ directory - they are not slash commands. Changes: - Removed tasks directory creation in module setup - Removed tasks copying logic (15 lines) - Removed taskCount from console output - Removed tasks property from return value - Removed unused getTasksFromBmad and getTasksFromDir imports - Updated comment to clarify agents-only installation Verified: No tasks/ directories created in .claude/commands/bmad/ while task files remain accessible in bmad/core/tasks/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>	2025-10-20 07:20:36 -05:00
Jrakru	c2b3e797e7	fix(retrospective): align SM ownership in workflow paths and handoff (#770 )	2025-10-20 07:19:11 -05:00
Alex Verkhovsky	31666c1f0f	feat: add agent schema validation with comprehensive testing (#774 ) Introduce automated validation for agent YAML files using Zod to ensure schema compliance across all agent definitions. This feature validates 17 agent files across core and module directories, catching structural errors and maintaining consistency. Schema Validation (tools/schema/agent.js): - Zod-based schema validating metadata, persona, menu, prompts, and critical actions - Module-aware validation: module field required for src/modules/*/agents/, optional for src/core/agents/ - Enforces kebab-case unique triggers and at least one command target per menu item - Validates persona.principles as array (not string) - Comprehensive refinements for data integrity CLI Validator (tools/validate-agent-schema.js): - Scans src/{core,modules/}/agents/*.agent.yaml - Parses with js-yaml and validates using Zod schema - Reports detailed errors with file paths and field paths - Exits 1 on failures, 0 on success - Accepts optional project_root parameter for testing Testing (679 lines across 3 test files): - test/test-cli-integration.sh: CLI behavior and error handling tests - test/unit-test-schema.js: Direct schema validation unit tests - test/test-agent-schema.js: Comprehensive fixture-based tests - 50 test fixtures covering valid and invalid scenarios - ESLint configured to support CommonJS test files - Prettier configured to ignore intentionally broken fixtures CI Integration (.github/workflows/lint.yaml): - Renamed from format-check.yaml to lint.yaml - Added schema-validation job running npm run validate:schemas - Runs in parallel with prettier and eslint jobs - Validates on all pull requests Data Cleanup: - Fixed src/core/agents/bmad-master.agent.yaml: converted persona.principles from string to array format Documentation: - Updated schema-classification.md with validation section - Documents validator usage, enforcement rules, and CI integration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>	2025-10-20 07:14:50 -05:00
Brian Madison	2a6eb71612	massive architecture creation overhaul	2025-10-19 23:28:38 -05:00
Brian Madison	d3402c3132	architecture reorganization in preparation of architecture solutioning rework	2025-10-19 15:28:33 -05:00
Brian Madison	0a048f2ccc	installer updates, bmd module added and moved out of src, created a plan for module installation tool for custom modules, minor flow improvements	2025-10-19 11:59:27 -05:00
Brian Madison	eb9a214115	readme updated	2025-10-18 12:19:47 -05:00
Brian Madison	940cc15751	cli installer bundler documentation added	2025-10-18 10:20:29 -05:00
Brian Madison	c0a2c55267	clearer codex install note	2025-10-18 09:41:38 -05:00
Brian Madison	a1fc8da03c	workflow init added to analyst pm and game agents	2025-10-18 01:34:03 -05:00