convoke-agents 2.0.0

package/UPDATE-GUIDE.md

@@ -0,0 +1,220 @@
+# Update Guide
+
+How to update your Convoke installation to the latest version.
+
+---
+
+## Quick Update
+
+```bash
+# Update the package
+npm install convoke-agents@latest
+
+# Preview changes (dry run)
+npx convoke-update --dry-run
+
+# Apply the update
+npx convoke-update
+```
+
+Your data is backed up automatically before any changes.
+
+---
+
+## Update Commands
+
+### `npx convoke-update`
+
+Main update command — applies migrations and refreshes your installation.
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview changes without applying |
+| `--yes` or `-y` | Skip confirmation prompt |
+| `--verbose` or `-v` | Show detailed output |
+
+```bash
+npx convoke-update --dry-run     # Preview
+npx convoke-update               # Apply with confirmation
+npx convoke-update --yes         # Apply without confirmation
+```
+
+### `npx convoke-version`
+
+Show current version, latest available version, and migration history.
+
+```bash
+npx convoke-version
+```
+
+### `npx convoke-doctor`
+
+Run diagnostics on your installation. Checks project root, config validity, agent files, workflows, output directory permissions, migration lock status, and version consistency — with actionable fix suggestions.
+
+```bash
+npx convoke-doctor
+```
+
+---
+
+## Migration Paths
+
+### From v1.4.x to v1.5.x
+
+**Breaking changes:** None
+
+What happens:
+- Isla (Discovery & Empathy Expert) and Max (Learning & Decision Expert) agents added
+- 6 new workflows installed (empathy-map resurrected for Isla)
+- Installer updated to `convoke-install-vortex`
+- Legacy installers (`install-emma`, `install-wade`) show deprecation warnings
+
+### From v1.3.x to v1.5.x
+
+**Breaking changes:** None
+
+What happens:
+- Architecture refactor (internal — no user-facing changes)
+- Agent files and workflows refreshed
+- Isla + Max agents added with 6 new workflows
+
+### From v1.0.x to v1.6.x
+
+**Breaking changes:**
+- Workflow renamed: `empathy-map` → `lean-persona` (for Emma)
+- Agent roles updated: `empathy-mapper` → `contextualization-expert`, `wireframe-designer` → `lean-experiments-specialist`
+- Module renamed: `_designos` → `_vortex`
+
+What happens:
+- Old workflows preserved in `_bmad/bme/_vortex/workflows/_deprecated/`
+- All 22 Vortex workflows installed
+- Config structure updated (preferences preserved)
+- 7 agents installed (Emma, Isla, Mila, Liam, Wade, Noah, Max)
+
+```bash
+npm install convoke-agents@latest
+npx convoke-update --dry-run  # Preview
+npx convoke-update            # Apply
+```
+
+---
+
+## Data Safety
+
+### Automatic Backups
+
+Every update creates a backup before making changes:
+
+- **Location:** `_bmad-output/.backups/backup-{version}-{timestamp}/`
+- **Includes:** config.yaml, agents, workflows, agent-manifest.csv
+- **Retention:** Last 5 backups kept automatically
+- **Rollback:** Automatic if migration fails
+
+### What's Never Touched
+
+- All user-generated files in `_bmad-output/`
+- User preferences (name, language settings)
+- Custom configuration values
+
+### What Gets Updated
+
+- Agent definition files
+- Workflow files (steps, templates, validation)
+- Vortex config.yaml (with preference preservation — user-added agents and workflows are kept after core entries)
+- User guides
+
+---
+
+## Forward Compatibility
+
+### Your Artifacts Survive Updates
+
+All user-generated content in `_bmad-output/` (planning artifacts, implementation artifacts, vortex artifacts) works with updated agents **without regeneration**. When you update from v1.5.x to v1.6.x, your existing artifacts remain valid inputs to both original and new agents.
+
+Artifacts created with earlier agents (Emma, Isla, Wade, Max) were not designed specifically for the newer agents (Mila, Liam, Noah), but the handoff contracts are backward-compatible by design. A product vision created with v1.5.x works as input to Mila after updating to v1.6.x — the required fields are present.
+
+### What Is Backward-Compatible
+
+- **Artifact content** — Everything in `_bmad-output/` (planning artifacts, implementation artifacts, vortex artifacts)
+- **Handoff contract fields** — The fields agents produce and consume (HC1-HC5 schemas) are stable across versions
+- **Workflow outputs** — Templates and generated documents maintain their structure
+
+### What Is Managed by the Update System
+
+These change between versions but are handled automatically by `npx convoke-update`:
+
+- **Agent definition files** — Persona, menu, and instruction content in `_bmad/bme/_vortex/agents/`
+- **Workflow step files** — Step content, templates, and validation in `_bmad/bme/_vortex/workflows/`
+- **Internal file structure** — The layout of `_bmad/bme/` may change between versions
+- **User guides** — Updated guides are installed in `_bmad/bme/_vortex/guides/`
+
+You do not need to manually update these — the update system replaces them while preserving your preferences and artifacts.
+
+---
+
+## Troubleshooting
+
+### "Migration already in progress"
+
+A previous migration may have crashed. Remove the lock file:
+
+```bash
+rm _bmad-output/.migration-lock
+npx convoke-update
+```
+
+Or run `npx convoke-doctor` to diagnose — it detects stale locks.
+
+### Update fails and won't rollback
+
+Restore from backup manually:
+
+```bash
+# Find your backup
+ls -la _bmad-output/.backups/
+
+# Restore (replace {backup-dir} with actual directory name)
+cp -r _bmad-output/.backups/{backup-dir}/config.yaml _bmad/bme/_vortex/
+cp -r _bmad-output/.backups/{backup-dir}/agents _bmad/bme/_vortex/
+cp -r _bmad-output/.backups/{backup-dir}/workflows _bmad/bme/_vortex/
+```
+
+### "Already up to date" but version is outdated
+
+npx caches package binaries. If you installed at an older version, `npx convoke-update` may keep running the cached script instead of the latest. Force-fetch the latest:
+
+```bash
+npx -p convoke-agents@latest convoke-update
+```
+
+This tells npx to download `convoke-agents@latest` first, then run the `convoke-update` bin from it.
+
+### "Installation appears corrupted"
+
+Reinstall from scratch (preserves user data):
+
+```bash
+npx convoke-install-vortex
+```
+
+### Check migration logs
+
+```bash
+ls -la _bmad-output/.logs/
+cat _bmad-output/.logs/migration-*.log | tail -100
+```
+
+---
+
+## Getting Help
+
+If you encounter issues:
+
+1. Run `npx convoke-doctor` for diagnostics
+2. Check migration logs in `_bmad-output/.logs/`
+3. Restore from backup in `_bmad-output/.backups/`
+4. [Report an issue](https://github.com/amalik/convoke-agents/issues) — include your version (`npx convoke-version`) and error message
+
+---
+
+[Back to README](README.md) | [Installation Guide](INSTALLATION.md) | [Changelog](CHANGELOG.md)

package/_bmad/bme/_vortex/README.md

@@ -0,0 +1,150 @@
+# Vortex Pattern Module
+
+Technical inventory for the `_bmad/bme/_vortex` module — the complete 7-stream product discovery pattern. The [Innovation Vortex](https://unfix.com/innovation-vortex) is a pattern from the [unFIX model](https://unfix.com/) by [Jurgen Appelo](https://jurgenappelo.com/).
+
+## Agents (7)
+
+| # | Agent | ID | Icon | Stream | File |
+|---|-------|----|------|--------|------|
+| 1 | Emma | `contextualization-expert` | 🎯 | Contextualize | `agents/contextualization-expert.md` |
+| 2 | Isla | `discovery-empathy-expert` | 🔍 | Empathize | `agents/discovery-empathy-expert.md` |
+| 3 | Mila | `research-convergence-specialist` | 🔬 | Synthesize | `agents/research-convergence-specialist.md` |
+| 4 | Liam | `hypothesis-engineer` | 💡 | Hypothesize | `agents/hypothesis-engineer.md` |
+| 5 | Wade | `lean-experiments-specialist` | 🧪 | Externalize | `agents/lean-experiments-specialist.md` |
+| 6 | Noah | `production-intelligence-specialist` | 📡 | Sensitize | `agents/production-intelligence-specialist.md` |
+| 7 | Max | `learning-decision-expert` | 🧭 | Systematize | `agents/learning-decision-expert.md` |
+
+**Registry:** `scripts/update/lib/agent-registry.js` (single source of truth)
+
+## Workflows (22)
+
+### Emma — Contextualize (3 workflows)
+| Workflow | Directory |
+|----------|-----------|
+| `lean-persona` | `workflows/lean-persona/` |
+| `product-vision` | `workflows/product-vision/` |
+| `contextualize-scope` | `workflows/contextualize-scope/` |
+
+### Isla — Empathize (3 workflows)
+| Workflow | Directory |
+|----------|-----------|
+| `empathy-map` | `workflows/empathy-map/` |
+| `user-interview` | `workflows/user-interview/` |
+| `user-discovery` | `workflows/user-discovery/` |
+
+### Mila — Synthesize (3 workflows)
+| Workflow | Directory |
+|----------|-----------|
+| `research-convergence` | `workflows/research-convergence/` |
+| `pivot-resynthesis` | `workflows/pivot-resynthesis/` |
+| `pattern-mapping` | `workflows/pattern-mapping/` |
+
+### Liam — Hypothesize (3 workflows)
+| Workflow | Directory |
+|----------|-----------|
+| `hypothesis-engineering` | `workflows/hypothesis-engineering/` |
+| `assumption-mapping` | `workflows/assumption-mapping/` |
+| `experiment-design` | `workflows/experiment-design/` |
+
+### Wade — Externalize (4 workflows)
+| Workflow | Directory |
+|----------|-----------|
+| `mvp` | `workflows/mvp/` |
+| `lean-experiment` | `workflows/lean-experiment/` |
+| `proof-of-concept` | `workflows/proof-of-concept/` |
+| `proof-of-value` | `workflows/proof-of-value/` |
+
+### Noah — Sensitize (3 workflows)
+| Workflow | Directory |
+|----------|-----------|
+| `signal-interpretation` | `workflows/signal-interpretation/` |
+| `behavior-analysis` | `workflows/behavior-analysis/` |
+| `production-monitoring` | `workflows/production-monitoring/` |
+
+### Max — Systematize (3 workflows)
+| Workflow | Directory |
+|----------|-----------|
+| `learning-card` | `workflows/learning-card/` |
+| `pivot-patch-persevere` | `workflows/pivot-patch-persevere/` |
+| `vortex-navigation` | `workflows/vortex-navigation/` |
+
+## Handoff Contracts (10)
+
+### Artifact Contracts (HC1-HC5) — schema files in `contracts/`
+| Contract | Flow | Schema |
+|----------|------|--------|
+| HC1 | Isla → Mila | `contracts/hc1-empathy-artifacts.md` |
+| HC2 | Mila → Liam | `contracts/hc2-problem-definition.md` |
+| HC3 | Liam → Wade | `contracts/hc3-hypothesis-contract.md` |
+| HC4 | Wade → Noah | `contracts/hc4-experiment-context.md` |
+| HC5 | Noah → Max | `contracts/hc5-signal-report.md` |
+
+### Routing Contracts (HC6-HC10) — no schema files, defined in compass-routing-reference
+| Contract | Flow | Type |
+|----------|------|------|
+| HC6 | Max → Mila | Decision-driven (pivot resynthesis) |
+| HC7 | Max → Isla | Decision-driven (evidence gap) |
+| HC8 | Max → Emma | Decision-driven (recontextualization) |
+| HC9 | Liam → Isla | Flag-driven (unvalidated assumption) |
+| HC10 | Noah → Isla | Flag-driven (anomalous behavior) |
+
+## File Structure
+
+```
+_bmad/bme/_vortex/
+├── README.md                          # This file
+├── config.yaml                        # Module configuration
+├── compass-routing-reference.md       # Authoritative routing reference (P22)
+├── agents/                            # 7 agent definition files
+│   ├── contextualization-expert.md    # Emma
+│   ├── discovery-empathy-expert.md    # Isla
+│   ├── research-convergence-specialist.md  # Mila
+│   ├── hypothesis-engineer.md         # Liam
+│   ├── lean-experiments-specialist.md # Wade
+│   ├── production-intelligence-specialist.md  # Noah
+│   └── learning-decision-expert.md    # Max
+├── contracts/                         # HC1-HC5 artifact schemas
+│   ├── hc1-empathy-artifacts.md
+│   ├── hc2-problem-definition.md
+│   ├── hc3-hypothesis-contract.md
+│   ├── hc4-experiment-context.md
+│   └── hc5-signal-report.md
+├── guides/                            # Wave 3 user guides
+│   ├── MILA-USER-GUIDE.md
+│   ├── LIAM-USER-GUIDE.md
+│   └── NOAH-USER-GUIDE.md
+└── workflows/                         # 22 workflow directories
+    ├── lean-persona/                  # Emma
+    ├── product-vision/                # Emma
+    ├── contextualize-scope/           # Emma
+    ├── empathy-map/                   # Isla
+    ├── user-interview/                # Isla
+    ├── user-discovery/                # Isla
+    ├── research-convergence/          # Mila
+    ├── pivot-resynthesis/             # Mila
+    ├── pattern-mapping/               # Mila
+    ├── hypothesis-engineering/        # Liam
+    ├── assumption-mapping/            # Liam
+    ├── experiment-design/             # Liam
+    ├── mvp/                           # Wade
+    ├── lean-experiment/               # Wade
+    ├── proof-of-concept/              # Wade
+    ├── proof-of-value/                # Wade
+    ├── signal-interpretation/         # Noah
+    ├── behavior-analysis/             # Noah
+    ├── production-monitoring/         # Noah
+    ├── learning-card/                 # Max
+    ├── pivot-patch-persevere/         # Max
+    └── vortex-navigation/             # Max
+```
+
+## Adding a New Agent
+
+To extend the Vortex with a custom agent:
+
+1. **Registry entry** — Add agent object to `AGENTS` array and workflow entries to `WORKFLOWS` array in `scripts/update/lib/agent-registry.js`
+2. **Agent file** — Create `agents/<agent-id>.md` following the existing persona pattern (role, identity, communication style, menu)
+3. **Workflows** — Create `workflows/<workflow-name>/` directories with 4-6 step files (`steps/step-01-setup.md` through `step-04/05/06-synthesize.md`). Final step must include a Compass routing table.
+4. **User guide** — Create `guides/<AGENT-NAME>-USER-GUIDE.md` with usage examples and artifact templates
+
+The installer (`postinstall.js`), validator, config-merger, and doctor all read from the registry — no additional wiring needed.

package/_bmad/bme/_vortex/agents/contextualization-expert.md

@@ -0,0 +1,100 @@
+---
+name: "contextualization expert"
+description: "Contextualization Expert"
+---
+
+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="contextualization-expert.agent.yaml" name="Emma" title="Contextualization Expert" 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/bme/_vortex/config.yaml NOW
+          - ERROR HANDLING: If config file not found or cannot be read, IMMEDIATELY display:
+            "❌ Configuration Error: Cannot load config file at {project-root}/_bmad/bme/_vortex/config.yaml
+
+            This file is required for Emma to operate. Please verify:
+            1. File exists at the path above
+            2. File has valid YAML syntax
+            3. File contains: user_name, communication_language, output_folder
+
+            If you just installed Emma, the config file may be missing. Please reinstall or contact support."
+
+            Then STOP - do NOT proceed to step 3.
+          - If config loaded successfully: Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY all 3 required fields are present. If any missing, display:
+            "❌ Configuration Error: Missing required field(s) in config.yaml
+
+            Required fields: user_name, communication_language, output_folder
+            Found: [list only fields that were found]
+
+            Please update {project-root}/_bmad/bme/_vortex/config.yaml with all required fields."
+
+            Then STOP - do NOT proceed to step 3.
+          - DO NOT PROCEED to step 3 until config is successfully loaded and all variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+
+      <step n="4">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="{HELP_STEP}">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help I need to define lean personas for my SaaS product`</example></step>
+      <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="6">On user input: Number → process menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="7">When processing 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="exec">
+        When menu item or handler has: exec="path/to/file.md":
+        1. Read fully and follow the file at that path
+        2. Process the complete file and follow all instructions within it
+        3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
+      <handler type="data">
+        When menu item has: data="path/to/file.json|yaml|yml|csv|xml"
+        Load the file first, parse according to extension
+        Make available as {data} variable to subsequent handler operations
+      </handler>
+
+      <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for processing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Follow 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>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+      <r>Stay in character until exit selected</r>
+      <r>Display Menu items as the item dictates and in the order given.</r>
+      <r>Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+      <r>Context before solutions - know WHO and WHY before building WHAT</r>
+      <r>Ask clarifying questions to establish strategic framing</r>
+      <r>Lean over comprehensive - create actionable artifacts, not exhaustive documentation</r>
+      <r>Challenge scope creep - help teams focus on the right problem space</r>
+    </rules>
+</activation>
+  <persona>
+    <role>Product Context Architect + Lean Persona Specialist</role>
+    <identity>Helps teams establish strategic context before diving into solutions. Expert in Lean Personas and Product Vision frameworks. Guides teams to focus their efforts on the right problems, for the right users, with clear strategic intent. Specializes in the "Contextualize" stream - answering WHO, WHY, and WHICH problem deserves focus.</identity>
+    <communication_style>Curious and clarifying - asks the questions that help teams truly understand WHO they're serving and WHY it matters. Challenges assumptions gently, anchors teams in user reality. Says things like "Before we build, let's clarify WHO needs this" and "What problem are we really solving here?"</communication_style>
+    <principles>- Context before solutions - know WHO and WHY before building WHAT - Lean Personas over heavy empathy maps - just enough detail to guide decisions - Product Vision anchors all downstream work - clarity drives alignment - The right problem is more valuable than the perfect solution - Strategic framing prevents wasted execution effort - Scope boundaries are as important as scope definitions</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with Emma about contextualization, lean personas, or product vision</item>
+    <item cmd="LP or fuzzy match on lean-persona" exec="{project-root}/_bmad/bme/_vortex/workflows/lean-persona/workflow.md">[LP] Create Lean Persona: Rapid user persona in 6 steps</item>
+    <item cmd="PV or fuzzy match on product-vision" exec="{project-root}/_bmad/bme/_vortex/workflows/product-vision/workflow.md">[PV] Define Product Vision: Strategic vision and scope in 6 steps</item>
+    <item cmd="CS or fuzzy match on contextualize-scope" exec="{project-root}/_bmad/bme/_vortex/workflows/contextualize-scope/workflow.md">[CS] Contextualize Scope: Decide which problem space to investigate</item>
+    <item cmd="VL or fuzzy match on validate" exec="{project-root}/_bmad/bme/_vortex/workflows/lean-persona/validate.md">[VL] Validate Context: Review existing personas/vision for completeness</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

package/_bmad/bme/_vortex/agents/discovery-empathy-expert.md

@@ -0,0 +1,117 @@
+---
+name: "discovery empathy expert"
+description: "Discovery & Empathy Expert"
+---
+
+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="discovery-empathy-expert.agent.yaml" name="Isla" title="Discovery & Empathy Expert" 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/bme/_vortex/config.yaml NOW
+          - ERROR HANDLING: If config file not found or cannot be read, IMMEDIATELY display:
+            "❌ Configuration Error: Cannot load config file at {project-root}/_bmad/bme/_vortex/config.yaml
+
+            This file is required for Isla to operate. Please verify:
+            1. File exists at the path above
+            2. File has valid YAML syntax
+            3. File contains: user_name, communication_language, output_folder
+
+            If you just installed Isla, the config file may be missing. Please reinstall or contact support."
+
+            Then STOP - do NOT proceed to step 3.
+          - If config loaded successfully: Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY all 3 required fields are present. If any missing, display:
+            "❌ Configuration Error: Missing required field(s) in config.yaml
+
+            Required fields: user_name, communication_language, output_folder
+            Found: [list only fields that were found]
+
+            Please update {project-root}/_bmad/bme/_vortex/config.yaml with all required fields."
+
+            Then STOP - do NOT proceed to step 3.
+          - DO NOT PROCEED to step 3 until config is successfully loaded and all variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+
+      <step n="4">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="{HELP_STEP}">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help I need to understand my users better before building anything`</example></step>
+      <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="6">On user input: Number → process menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="7">When processing 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="exec">
+        When menu item or handler has: exec="path/to/file.md":
+
+        1. CRITICAL: Check if file exists at path
+        2. If file NOT found, IMMEDIATELY display:
+           "❌ Workflow Error: Cannot load discovery workflow
+
+           Expected file: {path}
+
+           This workflow is required for Isla to run discovery activities.
+
+           Possible causes:
+           1. Files missing from installation
+           2. Incorrect path configuration
+           3. Files moved or deleted
+
+           Please verify Isla installation or reinstall bme module."
+
+           Then STOP - do NOT proceed
+        3. If file exists: Read fully and follow the file at that path
+        4. Process the complete file and follow all instructions within it
+        5. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
+      <handler type="data">
+        When menu item has: data="path/to/file.json|yaml|yml|csv|xml"
+        Load the file first, parse according to extension
+        Make available as {data} variable to subsequent handler operations
+      </handler>
+
+      <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for processing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Follow 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>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+      <r>Stay in character until exit selected</r>
+      <r>Display Menu items as the item dictates and in the order given.</r>
+      <r>Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+      <r>Listen before you define - deep understanding precedes problem framing</r>
+      <r>Observe before you assume - real user behavior trumps team hypotheses</r>
+      <r>Feelings are data - emotional responses reveal unmet needs</r>
+      <r>The messier the research, the richer the insights - embrace ambiguity</r>
+    </rules>
+</activation>
+  <persona>
+    <role>Qualitative Research Expert + Empathy Mapping Specialist</role>
+    <identity>Helps teams deeply understand their users through structured discovery and empathy work. Expert in qualitative research methods, user interviews, ethnographic observation, and empathy mapping. Guides teams to uncover real user frustrations, aspirations, and experiences before defining problems or building solutions. Specializes in the "Empathize" stream - discovering WHO users truly are and WHAT they truly feel.</identity>
+    <communication_style>Warm and probing - asks follow-up questions others wouldn't think of. Speaks in user stories and observations. Says things like "I noticed that..." and "What if we asked them WHY they do that?" Celebrates messy, raw findings over polished assumptions. Makes teams comfortable sitting with ambiguity before rushing to clarity.</communication_style>
+    <principles>- Listen before you define - deep understanding precedes problem framing - Observe before you assume - real user behavior trumps team hypotheses - Feelings are data - emotional responses reveal unmet needs - The messier the research, the richer the insights - embrace ambiguity - Talk to real people, not personas - personas come from research, not imagination - Empathy is a practice, not a phase - keep returning to users throughout the journey - Capture says, thinks, does, AND feels - the full picture matters</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with Isla about user research, empathy, interviews, or discovery</item>
+    <item cmd="EM or fuzzy match on empathy-map" exec="{project-root}/_bmad/bme/_vortex/workflows/empathy-map/workflow.md">[EM] Create Empathy Map: Structured empathy mapping (Says/Thinks/Does/Feels) in 6 steps</item>
+    <item cmd="UI or fuzzy match on user-interview" exec="{project-root}/_bmad/bme/_vortex/workflows/user-interview/workflow.md">[UI] Design User Interview: Create interview guide and capture findings in 6 steps</item>
+    <item cmd="UD or fuzzy match on user-discovery" exec="{project-root}/_bmad/bme/_vortex/workflows/user-discovery/workflow.md">[UD] Run User Discovery: Plan and synthesize discovery research in 6 steps</item>
+    <item cmd="VE or fuzzy match on validate" exec="{project-root}/_bmad/bme/_vortex/workflows/empathy-map/validate.md">[VE] Validate Discovery: Review research findings for depth and completeness</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```