bmad-enhanced 1.6.0 → 1.6.2

package/README.md

@@ -1,31 +1,43 @@
-# BMAD-Enhanced
+<div align="center">
+
+<pre>
+ ██████╗ ███╗   ███╗ █████╗ ██████╗
+ ██╔══██╗████╗ ████║██╔══██╗██╔══██╗
+ ██████╔╝██╔████╔██║███████║██║  ██║
+ ██╔══██╗██║╚██╔╝██║██╔══██║██║  ██║
+ ██████╔╝██║ ╚═╝ ██║██║  ██║██████╔╝
+ ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═════╝
+       E N H A N C E D
+</pre>
 
-**Vortex Pattern - Product Discovery through Lean Startup Validation**
+**BMAD Method enhanced by domain-specialized agents**
 
-[![Version](https://img.shields.io/badge/version-1.6.0-blue)](https://github.com/amalik/BMAD-Enhanced)
+[![Version](https://img.shields.io/badge/version-1.6.2-blue)](https://github.com/amalik/BMAD-Enhanced)
 [![Agents](https://img.shields.io/badge/agents-7-brightgreen)](docs/agents.md)
 [![Workflows](https://img.shields.io/badge/workflows-22-success)](docs/agents.md)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-BMAD-Enhanced extends the [BMAD Method](https://github.com/bmadhub/bmad) with the **Vortex Pattern** — seven specialized agents that guide teams through Lean Startup validation before building anything. The [Innovation Vortex](https://unfix.com/innovation-vortex) is a pattern from the [unFIX model](https://unfix.com/) by [Jurgen Appelo](https://jurgenappelo.com/).
+</div>
+
+BMAD-Enhanced extends the [BMAD Method](https://github.com/bmadhub/bmad) with domain-specialized agents. First batch of agents covers the [Innovation Vortex](https://unfix.com/innovation-vortex) pattern from [unFIX model](https://unfix.com/) by [Jurgen Appelo](https://jurgenappelo.com/). Seven specialized agents will guide teams through full product discovery validation before building anything.
 
 ```
                     VORTEX PATTERN — 7 Streams · 7 Agents
 
   ┌──────────┐  HC1  ┌──────────┐  HC2  ┌──────────┐  HC3  ┌──────────┐
   │  Isla 🔍  │─────▶│  Mila 🔬  │─────▶│  Liam 💡  │─────▶│  Wade 🧪  │
-  │ Empathize │      │Synthesize│      │Hypothesiz│      │Externaliz│
-  └──────────┘      └──────────┘      └──────────┘      └──────────┘
-       ▲                  ▲                │                    │
-       │            HC6   │              HC9│                  HC4│
-       │                  │                ▼                    ▼
-  ┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────┐
-  │ Emma 🎯  │◀HC8─│  Max 🧭  │◀HC5─│  Noah 📡  │◀────────┘
-  │Contextual│      │Systematiz│      │ Sensitize│
-  └──────────┘      └──────────┘      └──────────┘
-       │            HC7   │              HC10│
+  │ Empathize│       │Synthesize│       │Hypothesiz│       │Externaliz│
+  └──────────┘       └──────────┘       └──────────┘       └──────────┘
+       ▲                  ▲                                       │
+       │                 HC6                                    HC4
+       │                  │                                       ▼
+  ┌──────────┐  HC8  ┌──────────┐  HC5  ┌──────────┐              │
+  │  Emma 🎯  │◀─────│  Max  🧭  │◀─────│  Noah 📡  │◀────────────┘
+  │Contextual│       │Systematiz│       │ Sensitize│
+  └──────────┘       └──────────┘       └──────────┘
+       │                  │                  │
        └──────────────────┴──────────────────┘
-                      ▼ to Isla 🔍
+              HC7 · HC9 · HC10 ▶ Isla 🔍
 ```
 
 | Agent | Stream | What they do |
@@ -81,10 +93,10 @@ your-project/
 │   ├── agents/           # 7 agent definition files
 │   ├── workflows/        # 22 workflows
 │   ├── contracts/        # 5 artifact contract schemas (HC1-HC5)
-│   ├── guides/           # User guides (Mila, Liam, Noah)
+│   ├── guides/           # User guides (all 7 agents)
 │   └── config.yaml       # Configuration
 └── _bmad-output/
-    └── vortex-artifacts/  # Generated artifacts + user guides (Emma, Isla, Wade, Max)
+    └── vortex-artifacts/  # Generated artifacts
 ```
 
 ---
@@ -120,13 +132,13 @@ Max's **Vortex Navigation** workflow helps identify which stream needs attention
 
 For detailed workflow descriptions and usage examples, see the [Agent Guide](docs/agents.md) and the individual user guides:
 
-- [Emma User Guide](_bmad-output/vortex-artifacts/EMMA-USER-GUIDE.md)
-- [Isla User Guide](_bmad-output/vortex-artifacts/ISLA-USER-GUIDE.md)
+- [Emma User Guide](_bmad/bme/_vortex/guides/EMMA-USER-GUIDE.md)
+- [Isla User Guide](_bmad/bme/_vortex/guides/ISLA-USER-GUIDE.md)
 - [Mila User Guide](_bmad/bme/_vortex/guides/MILA-USER-GUIDE.md)
 - [Liam User Guide](_bmad/bme/_vortex/guides/LIAM-USER-GUIDE.md)
-- [Wade User Guide](_bmad-output/vortex-artifacts/WADE-USER-GUIDE.md)
+- [Wade User Guide](_bmad/bme/_vortex/guides/WADE-USER-GUIDE.md)
 - [Noah User Guide](_bmad/bme/_vortex/guides/NOAH-USER-GUIDE.md)
-- [Max User Guide](_bmad-output/vortex-artifacts/MAX-USER-GUIDE.md)
+- [Max User Guide](_bmad/bme/_vortex/guides/MAX-USER-GUIDE.md)
 
 ---
 
@@ -190,9 +202,51 @@ MIT License — see [LICENSE](LICENSE)
 ## Acknowledgments
 
 - [BMAD Method v6.0.0](https://github.com/bmadhub/bmad) — Foundation for agent architecture
+- [Innovation Vortex](https://unfix.com/innovation-vortex) — Pattern from the [unFIX model](https://unfix.com/) by [Jurgen Appelo](https://jurgenappelo.com/)
 - Claude (Anthropic) — AI reasoning and agent development
-- Murat (tea agent) — Test architecture and validation
-- BMAD Core Team — Framework and infrastructure
+
+### Agents
+
+Every agent below contributed to the design, implementation, testing, or documentation of this release.
+
+**Core**
+- BMad Master 🧙 — Orchestration and agent coordination
+
+**BMM — BMAD Method Module**
+- Mary 📊 Analyst — Requirements analysis and product briefs
+- Winston 🏗️ Architect — Architecture decisions and technical design
+- Amelia 💻 Dev — Implementation and code delivery
+- John 📋 PM — Product management and PRD creation
+- Barry 🚀 Quick Flow — Rapid solo development
+- Quinn 🧪 QA — Quality assurance and test validation
+- Bob 🏃 SM — Sprint management and retrospectives
+- Paige 📚 Tech Writer — Documentation and editorial review
+- Sally 🎨 UX Designer — User experience design
+
+**BME — Vortex Pattern Agents**
+- Emma 🎯 Contextualize — Problem framing and product vision
+- Isla 🔍 Empathize — User research and empathy mapping
+- Mila 🔬 Synthesize — Research convergence and problem definition
+- Liam 💡 Hypothesize — Hypothesis engineering and assumption mapping
+- Wade 🧪 Externalize — Lean experiments and MVP testing
+- Noah 📡 Sensitize — Production intelligence and signal interpretation
+- Max 🧭 Systematize — Learning capture and pivot/persevere decisions
+
+**CIS — Creative & Innovation Strategies**
+- Carson 🧠 Brainstorming Coach — Creative ideation facilitation
+- Dr. Quinn 🔬 Problem Solver — Systematic problem-solving
+- Maya 🎨 Design Thinking Coach — Human-centered design
+- Victor ⚡ Innovation Strategist — Business model innovation
+- Caravaggio 🎨 Presentation Master — Visual communication
+- Sophia 📖 Storyteller — Narrative and storytelling
+
+**BMB — BMAD Builder Module**
+- Bond 🤖 Agent Builder — Agent creation and configuration
+- Morgan 🏗️ Module Builder — Module architecture
+- Wendy 🔄 Workflow Builder — Workflow design and validation
+
+**TEA — Test Engineering & Architecture**
+- Murat 🧪 Test Architect — Test framework, CI pipeline, and quality gates
 
 ---
 

package/_bmad/bme/_vortex/guides/EMMA-USER-GUIDE.md

@@ -0,0 +1,450 @@
+# Emma User Guide - Contextualization Expert 🎯
+
+**Agent:** Emma (contextualization-expert)
+**Version:** 1.2.0
+**Module:** BMAD Enhanced (bme) - Vortex Pattern
+**Last Updated:** 2026-02-17
+
+---
+
+## Quick Start
+
+**Who is Emma?**
+Emma is a Lean Startup expert who helps teams contextualize their product strategy by defining clear problem spaces and validating assumptions. She guides you through strategic framing, problem-product space navigation, and the critical "Contextualize" stream of the Vortex pattern.
+
+**When to use Emma:**
+- Defining product vision and strategy
+- Creating lean user personas (jobs-to-be-done focused)
+- Clarifying which problem space to investigate
+- Challenging assumptions before building
+- Aligning teams around the "why" before the "what"
+- Validating problem-solution fit
+
+**What you'll get:**
+Strategic framing artifacts using Lean Startup methodologies - personas focused on jobs-to-be-done, product vision documents, problem scope definitions, and validation frameworks.
+
+---
+
+## How to Invoke Emma
+
+### Method 1: Slash Command (Preferred)
+
+If you're in a BMAD environment that supports slash commands:
+
+```
+/bmad-agent-bme-contextualization-expert
+```
+
+**When this works:**
+- Native BMAD CLI environment
+- BMAD-enabled IDEs
+- Production BMAD installations
+
+**If you see "Unknown skill":**
+This means slash commands aren't available in your environment. Use Method 2 instead.
+
+---
+
+### Method 2: Direct Agent File Reading (Always Works)
+
+In any environment (including Claude Code), you can invoke Emma by reading her agent file:
+
+1. Navigate to your BMAD project root
+2. Read the file: `_bmad/bme/_vortex/agents/contextualization-expert.md`
+3. Emma will activate and greet you
+
+**Example (Claude Code):**
+```
+Read the file at _bmad/bme/_vortex/agents/contextualization-expert.md
+```
+
+**Example (Terminal):**
+```bash
+cat _bmad/bme/_vortex/agents/contextualization-expert.md
+```
+
+This method has been fully tested and validated.
+
+---
+
+## Emma's Menu Options
+
+Once Emma activates, you'll see menu options for her available workflows:
+
+```
+1. [MH] Redisplay Menu Help
+2. [CH] Chat with Emma about Lean Startup, strategic framing, or problem-product space navigation
+3. [EM] Empathy Map (Legacy): Create user empathy maps (v1.0 workflow - still functional)
+4. [VM] Validate Artifact: Review existing artifacts against Lean Startup principles
+5. [PM] Start Party Mode
+6. [DA] Dismiss Agent
+```
+
+### How to Select an Option
+
+**Three ways to choose:**
+
+1. **Number:** Type `3` to select option 3
+2. **Command Code:** Type `EM` to create an empathy map
+3. **Fuzzy Match:** Type `empathy` or `map` or `create` - Emma will match the command
+
+---
+
+## Emma's Philosophy: Contextualization over Assumptions
+
+### What is Contextualization?
+
+Contextualization means defining clear problem and product spaces before building solutions. It's about:
+
+1. **Who is this truly for?** (Not demographics - jobs-to-be-done and problem contexts)
+2. **What are we really solving?** (Problem space boundaries and scope)
+3. **Why does this matter?** (Strategic vision and alignment)
+4. **What assumptions need validation?** (Every belief is a hypothesis until tested)
+
+### The Contextualize Stream (Vortex Pattern)
+
+Emma guides teams through the "Contextualize" stream:
+- **Problem-solution fit before product-market fit**
+- **Vision before features** - align on the "why" before the "what"
+- **Challenge assumptions ruthlessly** - unvalidated beliefs are risks
+- **Personas over demographics** - focus on jobs-to-be-done, not age/gender
+- **Clarity before action** - strategic framing prevents wasted effort
+
+---
+
+## Current Workflows (v1.2.0)
+
+### [EM] Empathy Map (Legacy - v1.0 Workflow)
+
+**Status:** Functional but deprecated. Maintained for backwards compatibility.
+
+**What it does:**
+Emma guides you through creating comprehensive empathy maps for target users using a structured 6-step process.
+
+**When to use:**
+- You need quick user insights using familiar empathy mapping framework
+- You have user research data to synthesize
+- You're waiting for v1.4.0+ workflows (lean-persona, product-vision, contextualize-scope)
+
+**Process:** 6 steps
+1. Define Target User
+2. Says & Thinks
+3. Does & Feels
+4. Pain Points
+5. Gains
+6. Synthesize
+
+**Output Location:**
+`{project-root}/_bmad-output/vortex-artifacts/empathy-map-{user-name}-{date}.md`
+
+**Time:** 30-60 minutes
+
+**Important:** This workflow uses traditional empathy mapping methodology. For Lean Startup-focused workflows aligned with the Vortex pattern, see "Coming in v1.4.0+" section below.
+
+---
+
+## Coming in v1.4.0+
+
+Emma's new Contextualize stream workflows are planned for v1.4.0:
+
+### [LP] Lean Persona
+Create lean user personas focused on jobs-to-be-done and problem contexts (not demographics).
+
+**Output:** Lean persona document
+**Focus:** Jobs-to-be-done, context, problems (vs. age, gender, fictional details)
+
+### [PV] Product Vision
+Define product vision and scope with strategic clarity.
+
+**Output:** Product vision document
+**Focus:** Strategic vision, alignment, the "why" before the "what"
+
+### [CS] Contextualize Scope
+Decide which problem space to investigate and define boundaries.
+
+**Output:** Problem scope document
+**Focus:** Problem space boundaries, scope definition, assumption identification
+
+**Note:** These workflows are being designed to fully align with Lean Startup methodologies and the Vortex pattern's Contextualize stream.
+
+---
+
+## Understanding the Legacy Empathy Map Workflow
+
+*This section describes the current v1.0 empathy-map workflow. For the full detailed guide, see the v1.0 documentation.*
+
+### Quick Overview
+
+1. **Define Target User** (5 min)
+   - Demographics, job-to-be-done, context, research sources
+
+2. **Says & Thinks** (10 min)
+   - What they SAY (direct quotes)
+   - What they THINK (inferred thoughts)
+
+3. **Does & Feels** (10 min)
+   - What they DO (observable actions)
+   - What they FEEL (emotional states)
+
+4. **Pain Points** (10 min)
+   - 4-6 pain points with impact and evidence
+
+5. **Gains** (10 min)
+   - 4-6 desired outcomes with value and success metrics
+
+6. **Synthesize** (5 min)
+   - Generate final empathy map artifact
+   - Save to output folder
+
+**Best Practices:**
+- Ground every insight in research evidence (quotes, observations, data)
+- Be specific (not "users" but "34-year-old marketing managers")
+- Make pain points concrete (not "bad UX" but "can't find transfer button")
+- Make gains measurable (not "faster" but "check balance in <5 seconds")
+
+---
+
+## Chatting with Emma (CH)
+
+Select **[CH] Chat** to have a free-form conversation with Emma about:
+
+- Lean Startup methodologies
+- Strategic framing and product vision
+- Problem-product space navigation
+- Jobs-to-be-Done framework
+- Assumption validation
+- Contextualization strategies
+- User research best practices
+
+**Example questions:**
+- "How do I validate assumptions before building?"
+- "What's the difference between problem-solution fit and product-market fit?"
+- "How do I define a problem space?"
+- "What makes a good lean persona vs. a traditional persona?"
+
+---
+
+## Validating Artifacts (VM)
+
+Select **[VM] Validate** to review existing artifacts against Lean Startup principles.
+
+**When to use this:**
+- You created an artifact and want expert review
+- You inherited artifacts from another team
+- Your understanding has changed and you need to update
+- You're preparing to present to stakeholders
+
+**What Emma checks:**
+- Are insights backed by research evidence?
+- Are assumptions clearly identified?
+- Are hypotheses testable?
+- Is the target user/problem specific enough?
+- Can this guide decision-making?
+
+---
+
+## Party Mode (PM)
+
+Select **[PM] Party Mode** to bring Emma into a multi-agent collaboration session.
+
+**When to use this:**
+- You need multiple BMAD agents working together
+- Example: Emma (contextualization) + Wade (experiments) + Quinn (quality review)
+
+**How it works:**
+- Emma joins a group discussion with other agents
+- Each agent contributes their expertise
+- Agents collaborate naturally on complex tasks
+
+---
+
+## Troubleshooting
+
+### Error: "Configuration Error: Cannot load config file"
+
+**What it means:**
+Emma can't find or read the config file at `_bmad/bme/_vortex/config.yaml`
+
+**How to fix:**
+
+1. **Check if file exists:**
+   ```bash
+   ls _bmad/bme/_vortex/config.yaml
+   ```
+
+2. **If missing, reinstall:**
+   ```bash
+   npm install bmad-enhanced@latest
+   npx bmad-install-agents
+   ```
+
+3. **Verify YAML syntax:**
+   - No tabs (use spaces)
+   - Proper indentation
+   - Quotes around string values
+
+---
+
+### Error: "Unknown skill: bmad-agent-bme-contextualization-expert"
+
+**What it means:**
+Slash commands aren't available in your environment.
+
+**How to fix:**
+Use Method 2 (Direct Agent File Reading) instead:
+
+1. Read the file: `_bmad/bme/_vortex/agents/contextualization-expert.md`
+2. Emma will activate normally
+3. This method is fully tested and works in all environments
+
+**Note:** This is NOT an error with Emma - it's an environment limitation.
+
+---
+
+## Tips from Emma
+
+### "Challenge assumptions ruthlessly"
+
+Every belief about your product, users, or market is an assumption until validated. Before you build, ask: "What evidence do we have?" If the answer is "we think" or "we believe," you have a hypothesis that needs testing.
+
+### "Personas over demographics"
+
+Age, gender, and income don't drive behavior - jobs-to-be-done and context do. Instead of "millennials," ask "what job are they hiring your product to do?"
+
+### "Vision before features"
+
+Align your team around the "why" before you debate the "what." A clear product vision prevents feature bloat and scope creep.
+
+### "Problem-solution fit comes first"
+
+Before you find product-market fit, validate problem-solution fit. Are you solving a real problem? For the right people? In the right context?
+
+### "Clarity is kindness"
+
+Unclear product strategy wastes everyone's time. Be specific about problem spaces, target users, and success criteria. Clarity accelerates execution.
+
+---
+
+## Migration Guide (v1.0 → v1.2.0)
+
+### What Changed
+
+**v1.0.0 (DesignOS):**
+- Agent: empathy-mapper
+- Module: `_bmad/bme/_designos/`
+- Focus: Empathy mapping, design thinking
+- Output: `_bmad-output/design-artifacts/`
+
+**v1.2.0 (Vortex Pattern):**
+- Agent: contextualization-expert
+- Module: `_bmad/bme/_vortex/`
+- Focus: Lean Startup, strategic framing, contextualization
+- Output: `_bmad-output/vortex-artifacts/`
+
+### How to Update
+
+1. **Update package:**
+   ```bash
+   npm install bmad-enhanced@latest
+   ```
+
+2. **Reinstall agents:**
+   ```bash
+   npx bmad-install-agents
+   ```
+
+3. **Update activation path:**
+   - Old: `_bmad/bme/_designos/agents/empathy-mapper.md`
+   - New: `_bmad/bme/_vortex/agents/contextualization-expert.md`
+
+4. **Update output references:**
+   - Old: `_bmad-output/design-artifacts/`
+   - New: `_bmad-output/vortex-artifacts/`
+
+### Backwards Compatibility
+
+- Legacy empathy-map workflow still functional in v1.2.0
+- Old artifacts remain valid and accessible
+- New Lean Startup workflows coming in v1.4.0+
+
+---
+
+## Roadmap
+
+**v1.2.0 (Current):**
+- ✅ Agent repositioned as Contextualization Expert
+- ✅ Module renamed to _vortex (Vortex Pattern)
+- ✅ Legacy empathy-map workflow maintained
+- ✅ User guide updated
+
+**v1.3.0 (Planned):**
+- Update/migration tooling
+- Automated update scripts
+
+**v1.4.0+ (Planned):**
+- New Contextualize stream workflows:
+  - [LP] Lean Persona
+  - [PV] Product Vision
+  - [CS] Contextualize Scope
+- Full Vortex Pattern implementation
+
+---
+
+## Getting Help
+
+### Need help using Emma?
+
+1. **Chat with Emma (CH):** Ask her questions about Lean Startup and contextualization
+2. **Read this guide:** Most questions are answered here
+3. **Check troubleshooting section:** Common errors and solutions
+
+### Found a bug or issue?
+
+1. **Check if it's an environment limitation:** Some features (like slash commands) may not work in all environments
+2. **Report the issue:** Provide Emma's version (1.2.0), your environment, and steps to reproduce
+
+### Want to learn more?
+
+**Emma's expertise includes:**
+- Lean Startup methodology
+- Jobs-to-be-Done framework
+- Strategic framing and product vision
+- Problem-product space navigation
+- Assumption validation
+- Contextualization strategies
+
+**Ask Emma (CH) about any of these topics!**
+
+---
+
+## Version History
+
+**v1.2.0 (2026-02-17)**
+- Agent repositioned as Contextualization Expert (Lean Startup focus)
+- Module renamed from _designos to _vortex (Vortex Pattern)
+- Output folder moved to vortex-artifacts
+- Updated documentation to reflect strategic framing and contextualization
+- Legacy empathy-map workflow maintained for backwards compatibility
+- Roadmap added for v1.4.0+ Contextualize stream workflows
+
+**v1.0.0 (2026-02-14)**
+- Initial release as Empathy Mapping Specialist
+- 6-step empathy mapping workflow
+- Config-driven personalization
+- Comprehensive error handling
+- Validation workflow (VM)
+- Party mode integration (PM)
+
+---
+
+## Credits
+
+**Agent:** Emma (contextualization-expert)
+**Module:** BMAD Enhanced (bme)
+**Submodule:** Vortex Pattern (_vortex)
+**Framework:** BMAD Agent Architecture Framework v1.1.0
+**Methodology:** Lean Startup, Jobs-to-be-Done
+
+---
+
+**Questions?** Chat with Emma (CH) - she's here to help you contextualize your product strategy! 🎯