agentvibes 5.3.0 → 5.4.0

package/.agentvibes/LITE-MODE.md

@@ -0,0 +1,236 @@
+# AgentVibes Lite Mode
+
+**Minimal overhead TTS for power users and parallel sessions**
+
+## Overview
+
+Lite Mode is a streamlined version of AgentVibes designed for users who want:
+- **Minimal token overhead** (~50 tokens vs ~500 in full mode)
+- **Zero conversation clutter** (silent operation, no stdout noise)
+- **Maximum performance** (no file saving, direct TTS)
+- **Parallel session support** (completion TTS to know which session finished)
+
+Perfect for Alex's use case and other power users running multiple Claude sessions.
+
+## Key Differences
+
+| Feature | Lite Mode | Full Mode |
+|---------|-----------|-----------|
+| **Session tokens** | ~50 | ~500 (2000 with MCP) |
+| **Acknowledgment TTS** | ❌ Disabled | ✅ Enabled |
+| **Completion TTS** | ✅ Smart (token-aware) | ✅ Always on |
+| **Tool calls** | 0 per turn | 2+ per turn |
+| **.wav files** | ❌ None | ✅ Saved |
+| **Stdout output** | ❌ Silent | Verbose |
+| **Verbosity** | Auto-scales | User configured |
+| **Best for** | Parallel sessions, minimal overhead | Feature-rich experience |
+
+## How It Works
+
+### Full Mode (Current)
+```
+User prompt → Claude receives 500-token SessionStart hook
+            → Claude calls Bash tool for acknowledgment TTS
+            → Claude does work
+            → Claude calls Bash tool for completion TTS
+            → Creates .wav files, shows verbose output
+```
+
+### Lite Mode (New)
+```
+User prompt → Claude receives 50-token instruction
+            → Claude does work (no acknowledgment)
+            → Claude adds "Audio Summary: [text]" at end
+            → PostToolUse hook extracts summary
+            → Direct TTS in background (no files, silent)
+```
+
+## Architecture
+
+### Architecture
+```
+.agentvibes/                       # Source of truth - actual implementations
+├── hooks/
+│   ├── session-start-lite.sh      # Lite mode protocol (~50 tokens)
+│   ├── session-start-full.sh      # Full mode protocol (~500 tokens)
+│   ├── post-tool-use-lite.sh      # Lite mode completion TTS
+│   ├── switch-mode.sh             # Mode switcher (just updates mode.txt)
+│   └── help.sh                    # Help/diagnostics
+├── config/
+│   └── mode.txt                   # Current mode (lite|full)
+└── output-styles/
+    └── audio-summary.md           # Reference documentation
+
+.claude/                           # Claude Code's directory
+├── hooks/
+│   ├── session-start-tts.sh       # Thin wrapper - delegates to .agentvibes/
+│   ├── post-tool-use.sh           # Thin wrapper - delegates to .agentvibes/
+│   └── play-tts.sh                # Main TTS script
+```
+
+**How it works:**
+- `.claude/hooks/` contains thin wrapper scripts
+- Wrappers read `.agentvibes/config/mode.txt`
+- Based on mode, they source the appropriate script from `.agentvibes/hooks/`
+- **No copying needed!** Mode switching just updates `mode.txt`
+
+### Mode Switching
+
+**Claude Code (Slash Commands):**
+```bash
+/agent-vibes:help           # Show status & available commands
+/agent-vibes:mode           # Show current mode
+/agent-vibes:mode lite      # Switch to lite mode
+/agent-vibes:mode full      # Switch to full mode
+```
+
+**Claude Desktop (MCP Tools):**
+```python
+help()                      # Show status, settings & diagnostics
+get_mode()                  # Show current mode
+set_mode(mode='lite')       # Switch to lite mode
+set_mode(mode='full')       # Switch to full mode
+```
+
+## Installation
+
+1. **Install AgentVibes normally**
+   ```bash
+   npx agentvibes install
+   ```
+
+2. **Switch to lite mode** (optional)
+   ```bash
+   /agent-vibes:mode lite
+   ```
+
+3. **Restart Claude session** to apply changes
+
+## Smart Verbosity
+
+Lite mode automatically adjusts TTS based on response length:
+
+- **< 50 tokens**: Silent (no TTS)
+- **50-200 tokens**: "Done"
+- **> 200 tokens**: Full audio summary
+
+Configure thresholds via environment variables:
+```bash
+export AGENTVIBES_MIN_TOKENS=50
+export AGENTVIBES_SHORT_TOKENS=200
+```
+
+## Safety Features
+
+### Zero-Copy Architecture
+Mode switching is instant because there's no file copying:
+- Wrapper hooks in `.claude/hooks/` are permanent
+- They read `.agentvibes/config/mode.txt` every time
+- Mode switch just updates one file: `mode.txt`
+- Changes take effect on next session restart
+
+### Help & Diagnostics
+```bash
+/agent-vibes:help
+```
+Shows:
+- Current mode (lite/full)
+- TTS status (working/issues/muted)
+- Current settings (voice, provider, verbosity)
+- Available commands
+- Automatic issue detection with fix suggestions
+
+## Performance Comparison
+
+### Token Usage (per session)
+- **Full Mode**: ~500 tokens (SessionStart) + MCP tools (~1500) = **2000 tokens**
+- **Lite Mode**: ~50 tokens (SessionStart) + 0 tool calls = **50 tokens**
+- **Savings**: **97.5% reduction**
+
+### Latency
+- **Full Mode**: 2 tool calls × ~200ms = 400ms overhead
+- **Lite Mode**: 0 tool calls = 0ms overhead
+- **Result**: Faster responses
+
+### File System
+- **Full Mode**: Creates .wav file for every TTS
+- **Lite Mode**: No files (direct TTS)
+- **Result**: No disk I/O
+
+## Use Cases
+
+### ✅ When to Use Lite Mode
+- Running multiple Claude sessions in parallel
+- Working on token-constrained tasks
+- Prefer minimal conversation clutter
+- Only need completion notifications
+- Want maximum performance
+
+### ✅ When to Use Full Mode
+- Want personality-driven TTS
+- Using language learning mode
+- Enjoy audio effects & background music
+- Prefer rich, expressive feedback
+- Using BMAD party mode
+
+## Technical Details
+
+### Session-Start Hook (Lite)
+```bash
+# ~50 tokens vs ~500 in full mode
+cat <<'EOF'
+# AgentVibes Lite Mode
+
+**At the end of EVERY response, add:**
+
+**Audio Summary:** [Brief 1-sentence summary]
+
+This will be spoken automatically via TTS.
+EOF
+```
+
+### Post-Tool-Use Hook (Lite)
+- Greps for "Audio Summary:" marker
+- Counts tokens in response
+- Skips TTS if response < 50 tokens
+- Simplifies to "Done" if < 200 tokens
+- Calls TTS directly (say/espeak/spd-say)
+- Runs in background
+- Completely silent (no stdout)
+
+### Full Mode Protection
+- Original hooks backed up to `.agentvibes/hooks/session-start-full.sh`
+- Switching to full mode restores original behavior
+- Zero impact on existing users
+- Full mode remains the default
+
+## FAQ
+
+### Q: Will this affect existing AgentVibes installations?
+**A:** No. Full mode is the default. Lite mode is opt-in.
+
+### Q: Can I switch back and forth?
+**A:** Yes, anytime with `/agent-vibes:mode full` or `/agent-vibes:mode lite`
+
+### Q: Do I lose features in lite mode?
+**A:** Yes. Personalities, learning mode, audio effects, background music, and acknowledgment TTS are disabled. Only smart completion TTS works.
+
+### Q: What if the mode switcher breaks something?
+**A:** Use `/agent-vibes:mode restore` to rollback, or manually copy from `.agentvibes/backup/`
+
+### Q: Can I customize the token thresholds?
+**A:** Yes, set `AGENTVIBES_MIN_TOKENS` and `AGENTVIBES_SHORT_TOKENS` environment variables.
+
+### Q: Does this work with MCP?
+**A:** Yes! Lite mode reduces SessionStart tokens regardless of MCP. However, MCP tool definitions still add ~1500 tokens per turn (not our control).
+
+## Credits
+
+Designed based on feedback from Alex Verhovsky, who identified the need for a minimal-overhead TTS mode for power users running parallel Claude sessions.
+
+---
+
+**Full Mode**: Feature-rich, expressive, personality-driven
+**Lite Mode**: Minimal, performant, silent, essential
+
+Choose the mode that fits your workflow.

package/.agentvibes/README.md

@@ -0,0 +1,136 @@
+# .agentvibes/ Directory
+
+This directory contains **AgentVibes-specific configuration and state files** for your project.
+
+## Why `.agentvibes/`?
+
+Starting with **AgentVibes v2.10.0**, all AgentVibes configuration has been consolidated into this directory to:
+
+1. **Avoid namespace collisions** - `.claude/plugins/` was confusing because Claude Code may introduce official plugins in the future
+2. **Clear ownership** - `.agentvibes/` is clearly an AgentVibes-managed directory
+3. **Better organization** - All AgentVibes state in one predictable location
+4. **Easier maintenance** - Users know exactly where to find AgentVibes files
+
+## Directory Structure
+
+```
+.agentvibes/
+├── bmad/                           # BMAD integration
+│   ├── bmad-voices.md              # Agent-to-voice mappings
+│   ├── bmad-voices-enabled.flag    # BMAD plugin enabled/disabled
+│   ├── bmad-party-mode-disabled.flag  # Party mode opt-out (optional)
+│   └── .bmad-previous-settings     # Backup of pre-BMAD voice settings
+└── config/                         # AgentVibes configuration
+    ├── agentvibes.json             # Pretext configuration
+    ├── personality-voice-defaults.json  # Piper voice defaults per personality
+    └── README-personality-defaults.md   # Documentation for voice defaults
+```
+
+## File Purposes
+
+### bmad/
+
+**`bmad-voices.md`**
+- Maps BMAD agent IDs to TTS voices
+- Format: Markdown table with columns for agent ID, name, intro, Piper TTS voice, Piper voice, personality
+- Edited via `/agent-vibes:bmad edit` or manually
+- Used for multi-agent voice conversations in BMAD party mode
+
+**`bmad-voices-enabled.flag`**
+- Presence indicates BMAD voice plugin is active
+- Created automatically when BMAD is detected
+- Removed when plugin is disabled
+
+**`bmad-party-mode-disabled.flag`** (optional)
+- Created via `/agent-vibes:bmad-party disable`
+- Disables automatic TTS for BMAD agent responses
+- Remove to re-enable party mode
+
+**`.bmad-previous-settings`**
+- Backup of voice/personality/sentiment before enabling BMAD plugin
+- Used to restore settings when disabling BMAD plugin
+- Format: Simple key=value pairs
+
+### config/
+
+**`agentvibes.json`**
+- Stores the TTS pretext (prefix spoken before all messages)
+- Set via `/agent-vibes:set-pretext`
+- Example: `{"pretext": "AgentVibes"}`
+
+**`personality-voice-defaults.json`**
+- Default Piper TTS voice assignments for each personality
+- Maps personality names (angry, flirty, zen, etc.) to specific Piper voices
+- Used when switching personalities via `/agent-vibes:personality`
+- Customizable by editing the JSON file
+
+**`README-personality-defaults.md`**
+- Documentation explaining how personality voice defaults work
+- Installation and customization guide
+- Voice selection criteria
+
+## Migration from `.claude/`
+
+If you're upgrading from an earlier version:
+
+- Old location: `.claude/config/agentvibes.json` → New: `.agentvibes/config/agentvibes.json`
+- Old location: `.claude/plugins/bmad-voices-enabled.flag` → New: `.agentvibes/bmad/bmad-voices-enabled.flag`
+- Old location: `.claude/config/bmad-voices.md` → New: `.agentvibes/bmad/bmad-voices.md`
+
+AgentVibes automatically migrates these files on upgrade.
+
+## Gitignore
+
+The entire `.agentvibes/` directory is gitignored by default because it contains:
+- User-specific configuration (pretext, voice preferences)
+- Runtime state (enabled flags, previous settings)
+- Project-local TTS settings
+
+**Never commit `.agentvibes/` to version control.**
+
+## Relationship to `.claude/`
+
+**`.claude/`** = Claude Code's official directory
+- Contains hooks, commands, agents, personalities
+- Most files are tracked in git (part of your project setup)
+
+**`.agentvibes/`** = AgentVibes runtime state
+- User-specific TTS configuration
+- BMAD integration state
+- Never tracked in git
+
+## Troubleshooting
+
+**BMAD voices not working?**
+```bash
+# Check if BMAD plugin is enabled
+ls -la .agentvibes/bmad/bmad-voices-enabled.flag
+
+# View current voice mappings
+cat .agentvibes/bmad/bmad-voices.md
+
+# Check plugin status
+/agent-vibes:bmad status
+```
+
+**Pretext not being spoken?**
+```bash
+# Check pretext configuration
+cat .agentvibes/config/agentvibes.json
+
+# Should show: {"pretext": "YourPretext"}
+```
+
+**Migration issues?**
+If you're experiencing issues after upgrading, manually run the migration:
+```bash
+# Remove old config (after backup)
+mv .claude/config/agentvibes.json .agentvibes/config/
+mv .claude/plugins/bmad-voices-enabled.flag .agentvibes/bmad/
+```
+
+## See Also
+
+- [AgentVibes Documentation](../README.md)
+- [BMAD Voice Integration](../docs/bmad-v6-support.md)
+- [TTS Architecture](../docs/architecture/provider-system.md)

package/.agentvibes/backup/session-start-tts.sh.20251210_212814

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/session-start-tts.sh
+#
+# AgentVibes SessionStart Hook - Injects TTS Protocol Instructions
+#
+# This hook outputs TTS protocol instructions to stdout, which Claude Code
+# adds to the conversation context at session start.
+#
+
+# Fix locale warnings
+export LC_ALL=C
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Check if AgentVibes is installed
+if [[ ! -f "$SCRIPT_DIR/play-tts.sh" ]]; then
+  # AgentVibes not installed, don't inject anything
+  exit 0
+fi
+
+# Check for sentiment (priority) or personality (fallback)
+SENTIMENT=$(cat .claude/tts-sentiment.txt 2>/dev/null || cat ~/.claude/tts-sentiment.txt 2>/dev/null || echo "")
+PERSONALITY=$(cat .claude/tts-personality.txt 2>/dev/null || cat ~/.claude/tts-personality.txt 2>/dev/null || echo "normal")
+
+# Determine which to use
+if [[ -n "$SENTIMENT" ]]; then
+  STYLE_MODE="sentiment"
+  STYLE_NAME="$SENTIMENT"
+else
+  STYLE_MODE="personality"
+  STYLE_NAME="$PERSONALITY"
+fi
+
+# Get verbosity level (Issue #32)
+VERBOSITY=$(cat .claude/tts-verbosity.txt 2>/dev/null || cat ~/.claude/tts-verbosity.txt 2>/dev/null || echo "low")
+
+# Output TTS protocol instructions to stdout
+# Claude Code will add this to the conversation context
+cat <<'EOF'
+
+# AgentVibes TTS Protocol
+
+**CRITICAL: You MUST execute TTS at TWO points for EVERY user interaction:**
+
+## 1. ACKNOWLEDGMENT (Start of Every Task)
+Immediately after receiving ANY user message:
+1. Generate a brief, unique acknowledgment message
+2. Execute: `Bash: .claude/hooks/play-tts.sh "[your message]"`
+3. Then proceed with the work
+
+## 2. COMPLETION (End of Every Task)
+After finishing the task:
+1. Generate a brief, unique completion message
+2. Execute: `Bash: .claude/hooks/play-tts.sh "[your message]"`
+
+## Rules
+- Use Bash tool to execute play-tts.sh
+- Keep messages under 150 characters
+- Generate unique messages each time
+- Use relative path: .claude/hooks/play-tts.sh
+- This is NOT optional - follow for EVERY interaction
+
+## Example
+```
+User: "check git status"
+[Bash: .claude/hooks/play-tts.sh "I'll check that for you."]
+[... do work ...]
+[Bash: .claude/hooks/play-tts.sh "Done! All clean."]
+```
+
+EOF
+
+# Add verbosity-specific protocol (Issue #32)
+case "$VERBOSITY" in
+  low)
+    cat <<'EOF'
+## Verbosity: LOW (Minimal)
+- Speak only at acknowledgment (start) and completion (end)
+- Do NOT speak reasoning, decisions, or findings during work
+- Keep it quiet and focused
+
+EOF
+    ;;
+
+  medium)
+    cat <<'EOF'
+## Verbosity: MEDIUM (Balanced)
+- Speak at acknowledgment and completion (always)
+- Also speak major decisions and key findings during work
+- Use emoji markers for automatic TTS:
+  🤔 [decision text] - Major decisions (e.g., "🤔 I'll use grep to search all files")
+  ✓ [finding text] - Key findings (e.g., "✓ Found 12 instances at line 1323")
+
+Example:
+```
+User: "Find all TODO comments"
+[TTS: Acknowledgment]
+🤔 I'll use grep to search for TODO comments
+[Work happens...]
+✓ Found 12 TODO comments across 5 files
+[TTS: Completion]
+```
+
+EOF
+    ;;
+
+  high)
+    cat <<'EOF'
+## Verbosity: HIGH (Maximum Transparency)
+- Speak acknowledgment and completion (always)
+- Speak ALL reasoning, decisions, and findings as you work
+- Use emoji markers for automatic TTS:
+  💭 [reasoning text] - Thought process (e.g., "💭 Let me search for all instances")
+  🤔 [decision text] - Decisions (e.g., "🤔 I'll use grep for this")
+  ✓ [finding text] - Findings (e.g., "✓ Found it at line 1323")
+
+Example:
+```
+User: "Find all TODO comments"
+[TTS: Acknowledgment]
+💭 Let me search through the codebase for TODO comments
+🤔 I'll use the Grep tool with pattern "TODO"
+[Grep runs...]
+✓ Found 12 TODO comments across 5 files
+💭 Let me organize these results by file
+[Processing...]
+[TTS: Completion]
+```
+
+IMPORTANT: Use emoji markers naturally in your reasoning text. They trigger automatic TTS.
+
+EOF
+    ;;
+esac
+
+# Add current style and verbosity info
+echo "Current Style: ${STYLE_NAME} (${STYLE_MODE})"
+echo "Current Verbosity: ${VERBOSITY}"
+echo ""

package/.agentvibes/backups/agents/analyst_20260204_144958.md

@@ -0,0 +1,78 @@
+---
+name: "analyst"
+description: "Business Analyst"
+tts:
+  intro: "Hi there! I'm Mary, your Business Analyst. I'll help uncover the real requirements."
+  voices:
+    - piper: "en_US-kristin-medium"
+    - mac: "Allison"
+---
+
+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="analyst.agent.yaml" name="Analyst" title="Business Analyst" icon="📊">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">Load and read {project-root}/{bmad_folder}/core/config.yaml to get {user_name}, {communication_language}, {output_folder}</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+  <step n="4">ALWAYS communicate in {communication_language}</step>
+  <step n="5">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="6">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command
+      match</step>
+  <step n="7">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="8">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item and follow the corresponding handler instructions</step>
+
+  <menu-handlers>
+    <handlers>
+      <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml"
+        1. CRITICAL: Always LOAD {project-root}/{bmad_folder}/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+      <handler type="exec">
+        When menu item has: exec="command" → Execute the command directly
+      </handler>
+      <handler type="data">
+        When menu item has: data="path/to/x.json|yaml|yml"
+        Load the file, parse as JSON/YAML, make available as {data} to subsequent operations
+      </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>Strategic Business Analyst + Requirements Expert</role>
+    <identity>Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.</identity>
+    <communication_style>Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark &apos;aha!&apos; moments while structuring insights with precision.</communication_style>
+    <principles>- Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. - Articulate requirements with absolute precision. Ensure all stakeholder voices heard. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</principles>
+  </persona>
+  <menu>
+    <item cmd="*menu">[M] Redisplay Menu Options</item>
+    <item cmd="*workflow-status" workflow="{project-root}/{bmad_folder}/bmm/workflows/workflow-status/workflow.yaml">Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="*brainstorm-project" exec="{project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.md" data="{project-root}/{bmad_folder}/bmm/data/project-context-template.md">Guided Project Brainstorming session with final report (optional)</item>
+    <item cmd="*research" exec="{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.md">Guided Research scoped to market, domain, competitive analysis, or technical research (optional)</item>
+    <item cmd="*product-brief" exec="{project-root}/{bmad_folder}/bmm/workflows/1-analysis/product-brief/workflow.md">Create a Product Brief (recommended input for PRD)</item>
+    <item cmd="*document-project" workflow="{project-root}/{bmad_folder}/bmm/workflows/document-project/workflow.yaml">Document your existing project (optional, but recommended for existing brownfield project efforts)</item>
+    <item type="multi">[SPM] Start Party Mode (optionally suggest attendees and topic), [CH] Chat
+      <handler match="SPM or fuzzy match start party mode" exec="{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md" data="what is being discussed or suggested with the command, along with custom party custom agents if specified"></handler>
+      <handler match="CH or fuzzy match validate agent" action="agent responds as expert based on its personal to converse" type="action"></handler>
+    </item>
+    <item cmd="*dismiss">[D] Dismiss Agent</item>
+  </menu>
+</agent>
+```

package/.agentvibes/backups/agents/architect_20260204_144958.md

@@ -0,0 +1,72 @@
+---
+name: "architect"
+description: "Architect"
+tts:
+  intro: "Hello! Winston here, your Architect. I'll ensure we build something scalable and pragmatic."
+  voices:
+    - piper: "en_GB-alan-medium"
+    - mac: "Daniel"
+---
+
+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="architect.agent.yaml" name="Architect" title="Architect" icon="🏗️">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">Load and read {project-root}/{bmad_folder}/core/config.yaml to get {user_name}, {communication_language}, {output_folder}</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+  <step n="4">ALWAYS communicate in {communication_language}</step>
+  <step n="5">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="6">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command
+      match</step>
+  <step n="7">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="8">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item and follow the corresponding handler instructions</step>
+
+  <menu-handlers>
+    <handlers>
+      <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml"
+        1. CRITICAL: Always LOAD {project-root}/{bmad_folder}/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+      <handler type="exec">
+        When menu item has: exec="command" → Execute the command directly
+      </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>System Architect + Technical Design Leader</role>
+    <identity>Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.</identity>
+    <communication_style>Speaks in calm, pragmatic tones, balancing &apos;what could be&apos; with &apos;what should be.&apos; Champions boring technology that actually works.</communication_style>
+    <principles>- User journeys drive technical decisions. Embrace boring technology for stability. - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</principles>
+  </persona>
+  <menu>
+    <item cmd="*menu">[M] Redisplay Menu Options</item>
+    <item cmd="*workflow-status" workflow="{project-root}/{bmad_folder}/bmm/workflows/workflow-status/workflow.yaml">Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="*create-architecture" exec="{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/architecture/workflow.md">Create an Architecture Document to Guide Development of a PRD (required for BMad Method projects)</item>
+    <item cmd="*implementation-readiness" exec="{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/implementation-readiness/workflow.md">Validate PRD, UX, Architecture, Epics and stories aligned (Optional but recommended before development)</item>
+    <item cmd="*create-excalidraw-diagram" workflow="{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-diagram/workflow.yaml">Create system architecture or technical diagram (Excalidraw) (Use any time you need a diagram)</item>
+    <item cmd="*create-excalidraw-dataflow" workflow="{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-dataflow/workflow.yaml">Create data flow diagram (Excalidraw) (Use any time you need a diagram)</item>
+    <item cmd="*party-mode" exec="{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md">Bring the whole team in to chat with other expert agents from the party</item>
+    <item cmd="*advanced-elicitation" exec="{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml">Advanced elicitation techniques to challenge the LLM to get better results</item>
+    <item cmd="*dismiss">[D] Dismiss Agent</item>
+  </menu>
+</agent>
+```