bmad-enhanced 1.5.2 → 1.6.0

package/README.md

@@ -1,47 +1,48 @@
 # BMAD-Enhanced
 
-**Vortex Framework - Product Discovery through Lean Startup Validation**
+**Vortex Pattern - Product Discovery through Lean Startup Validation**
 
-> Four specialized agents: Emma, Wade, Isla, and Max
+[![Version](https://img.shields.io/badge/version-1.6.0-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)
 
-[![Status](https://img.shields.io/badge/status-v1.5.2--stable-success)]()
-[![Version](https://img.shields.io/badge/version-1.5.2-blue)]()
-[![Agents](https://img.shields.io/badge/agents-4-brightgreen)]()
-[![Workflows](https://img.shields.io/badge/workflows-13_implemented-success)]()
-[![License](https://img.shields.io/badge/license-MIT-blue)]()
-
----
-
-## 🎯 What is BMAD-Enhanced?
-
-BMAD-Enhanced extends the [BMAD Method](https://github.com/bmadhub/bmad) with the **Vortex framework** - a Lean Startup validation approach with four specialized agents across four Vortex streams:
+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/).
 
 ```
-VORTEX FRAMEWORK
-
-Contextualize        Empathize           Externalize         Systematize
-┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
-│   Emma 🎯   │    │   Isla 🔍   │    │   Wade 🧪   │    │   Max  🧭   │
-│             │    │             │    │             │    │             │
-│  Strategic  │───>│  Discovery  │───>│    Lean     │───>│  Learning   │
-│   Framing   │    │  & Empathy  │    │ Experiments │    │ & Decisions │
-│             │    │             │    │             │    │             │
-│ • Personas  │    │ • Empathy   │    │ • MVPs      │    │ • Learning  │
-│ • Vision    │    │ • Interview │    │ • Tests     │    │ • Pivot/    │
-│ • Scope     │    │ • Discovery │    │ • Proof     │    │   Persevere │
-└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+                    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│
+       └──────────────────┴──────────────────┘
+                      ▼ to Isla 🔍
 ```
 
-**Contextualize (Emma):** Frame the right problem before building
-**Empathize (Isla):** Understand users through research and empathy mapping
-**Externalize (Wade):** Test assumptions with real users through experiments
-**Systematize (Max):** Capture learnings and navigate between Vortex streams
+| Agent | Stream | What they do |
+|-------|--------|-------------|
+| **Emma** 🎯 | Contextualize | Frame the right problem — lean personas, product vision, scope decisions |
+| **Isla** 🔍 | Empathize | Understand users — empathy maps, interviews, discovery research |
+| **Mila** 🔬 | Synthesize | Converge research into problem definitions — JTBD, pains & gains analysis |
+| **Liam** 💡 | Hypothesize | Engineer testable hypotheses — assumption mapping, experiment design |
+| **Wade** 🧪 | Externalize | Test assumptions — MVPs, experiments, proof-of-concept/value |
+| **Noah** 📡 | Sensitize | Interpret production signals — behavior analysis, monitoring |
+| **Max** 🧭 | Systematize | Capture learnings — learning cards, pivot/persevere decisions, stream navigation |
 
----
+Every workflow ends with a **Vortex Compass** — evidence-driven routing that creates non-linear loops across all streams. Ten handoff contracts (HC1-HC10) ensure structured information flows between agents.
 
-## ⚡ Quick Start
+---
 
-**📖 See [INSTALLATION.md](INSTALLATION.md) for complete installation guide**
+## Quick Start
 
 ### Prerequisites
 
@@ -49,1146 +50,156 @@ Contextualize        Empathize           Externalize         Systematize
 - Git
 - Claude Code or Claude.ai
 
-**Optional:** [BMAD Method](https://github.com/bmadhub/bmad) - BMAD-Enhanced works standalone or as an extension to BMAD Method.
-
-### One-Command Installation
+### Install
 
 ```bash
 npm install bmad-enhanced && npx bmad-install-vortex-agents
 ```
 
-That's it! All 4 Vortex agents (Emma, Isla, Wade, Max) with 13 workflows are installed.
+All 7 agents with 22 workflows are installed and ready to use.
 
-### Installation
-
-**Option 1: Install from npm (Recommended)**
+### Activate an Agent
 
 ```bash
-# Install into your project
-npm install bmad-enhanced
-
-# Install all Vortex agents with all 13 workflows
-npx bmad-install-vortex-agents
+# Read an agent file to activate it
+cat _bmad/bme/_vortex/agents/contextualization-expert.md          # Emma  🎯
+cat _bmad/bme/_vortex/agents/discovery-empathy-expert.md          # Isla  🔍
+cat _bmad/bme/_vortex/agents/research-convergence-specialist.md   # Mila  🔬
+cat _bmad/bme/_vortex/agents/hypothesis-engineer.md               # Liam  💡
+cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md       # Wade  🧪
+cat _bmad/bme/_vortex/agents/production-intelligence-specialist.md # Noah  📡
+cat _bmad/bme/_vortex/agents/learning-decision-expert.md          # Max   🧭
 ```
 
-**Option 2: Clone from source**
+Each agent presents a menu-driven interface. Pick a workflow and follow the guided steps.
 
-```bash
-# Clone repository
-git clone https://github.com/yourusername/BMAD-Enhanced.git
-cd BMAD-Enhanced
-
-# Install dependencies
-npm install
+### What Gets Installed
 
-# Agents are already installed and operational
-cat _bmad/bme/_vortex/agents/contextualization-expert.md
 ```
-
-**What gets installed:**
-- Agent definition files (`_bmad/bme/_vortex/agents/`)
-- **13 complete workflows** (104 files):
-  - Emma: lean-persona, product-vision, contextualize-scope
-  - Isla: empathy-map, user-interview, user-discovery
-  - Wade: mvp, lean-experiment, proof-of-concept, proof-of-value
-  - Max: learning-card, pivot-patch-persevere, vortex-navigation
-- Configuration file (`_bmad/bme/_vortex/config.yaml`)
-- Output directory (`_bmad-output/vortex-artifacts/`)
-- User guides (Emma, Isla, Wade & Max)
-
-### Getting Started with the Agents
-
-```bash
-# Activate any agent by reading their definition file
-cat _bmad/bme/_vortex/agents/contextualization-expert.md    # Emma
-cat _bmad/bme/_vortex/agents/discovery-empathy-expert.md    # Isla
-cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md  # Wade
-cat _bmad/bme/_vortex/agents/learning-decision-expert.md     # Max
+your-project/
+├── _bmad/bme/_vortex/
+│   ├── agents/           # 7 agent definition files
+│   ├── workflows/        # 22 workflows
+│   ├── contracts/        # 5 artifact contract schemas (HC1-HC5)
+│   ├── guides/           # User guides (Mila, Liam, Noah)
+│   └── config.yaml       # Configuration
+└── _bmad-output/
+    └── vortex-artifacts/  # Generated artifacts + user guides (Emma, Isla, Wade, Max)
 ```
 
-### Emma - Contextualize Stream (3 workflows)
-
-Emma will guide you through strategic contextualization with 3 workflows:
-
-- **[LP] Lean Persona** - Create jobs-to-be-done focused user personas
-  - 6-step guided workflow
-  - Hypothesis-driven with validation planning
-  - Output: Lean persona document with riskiest assumptions identified
-
-- **[PV] Product Vision** - Define strategic product vision
-  - Vision statement, future state (3-5 years), guiding principles
-  - Strategic assumptions and validation plan
-  - Output: Complete product vision document
-
-- **[CS] Contextualize Scope** - Decide which problem space to investigate
-  - Systematic opportunity evaluation with scoring matrix
-  - Clear scope boundaries (what's in, what's out)
-  - Output: Scope decision document with rationale
-
-### Isla - Empathize Stream (3 workflows)
-
-Isla will guide you through user discovery and empathy with 3 workflows:
-
-- **[EM] Empathy Map** - Build deep user understanding through empathy mapping
-  - 5-step guided workflow
-  - Maps what users think, feel, say, do, and experience
-  - Output: Empathy map artifact with pain/gain analysis
-
-- **[UI] User Interview** - Design and conduct effective user interviews
-  - 6-step guided workflow
-  - Interview script design with findings capture
-  - Output: Interview findings with patterns and insights
-
-- **[UD] User Discovery** - Plan and execute discovery research
-  - 6-step guided workflow
-  - Research planning, execution, and synthesis
-  - Output: Discovery research report with key findings
-
-### Wade - Externalize Stream (4 workflows)
-
-Wade will guide you through validated learning with 4 workflows:
-
-- **[MVP] Minimum Viable Product** - Design MVPs to test riskiest assumptions
-  - Not feature-light products - smallest thing to test assumptions
-  - Build-Measure-Learn cycle planning
-  - Output: MVP specification document
-
-- **[LE] Lean Experiment** - Execute Build-Measure-Learn cycles
-  - Hypothesis-driven experimentation framework
-  - Metrics definition and pivot-or-persevere decisions
-  - Output: Experiment results and learning documentation
-
-- **[POC] Proof-of-Concept** - Validate technical feasibility
-  - Test "Can we build it?" before "Should we build it?"
-  - Technical risk assessment and PoC scoping
-  - Output: Feasibility evaluation document
-
-- **[POV] Proof-of-Value** - Validate business value
-  - Test "Should we build it?" (business case)
-  - Willingness to pay and market demand experiments
-  - Output: Business case and build/pivot/kill decision
-
-### Max - Systematize Stream (3 workflows)
-
-Max will guide you through learning capture and strategic navigation with 3 workflows:
-
-- **[LC] Learning Card** - Capture what was tested, learned, and decided
-  - 6-step guided workflow
-  - Structured learning documentation from experiments
-  - Output: Learning card artifact with evidence and decisions
-
-- **[PPP] Pivot, Patch, or Persevere** - Make evidence-based decisions after experiments
-  - 6-step guided workflow
-  - Decision framework with evidence evaluation
-  - Output: Decision document with rationale and next steps
-
-- **[VN] Vortex Navigation** - Decide which Vortex stream to focus on next
-  - 6-step guided workflow
-  - Assess progress across all streams, identify gaps
-  - Output: Navigation recommendation with action plan
-
 ---
 
-## 🔄 Updating BMAD-Enhanced
-
-### Check Version
-
-```bash
-npx bmad-version
-```
-
-**Output shows:**
-- Current installed version
-- Latest package version
-- Update availability status
-- Migration history
-
-### Update to Latest Version
-
-```bash
-# Update the package
-npm install bmad-enhanced@latest
-
-# Preview changes (dry run)
-npx bmad-update --dry-run
-
-# Apply the update
-npx bmad-update
-```
-
-**Your data is automatically backed up before any changes.**
-
-### Update Commands
-
-- `npx bmad-update` - Apply updates and migrations
-- `npx bmad-update --dry-run` - Preview changes without applying
-- `npx bmad-update --yes` - Skip confirmation prompt
-- `npx bmad-version` - Show current version and status
-- `npx bmad-doctor` - Diagnose installation issues
-
-### Data Safety
-
-**Automatic backups before every update:**
-- Location: `_bmad-output/.backups/backup-{version}-{timestamp}/`
-- Automatic rollback if migration fails
-- Keeps last 5 backups
-
-**Never touched:**
-- All user data in `_bmad-output/`
-- User preferences (name, language)
-- Custom configurations
-
-### Migration Paths
-
-**From v1.3.x or v1.4.x to v1.5.0:**
-- No breaking changes
-- Adds Isla (Discovery & Empathy Expert) and Max (Learning & Decision Expert)
-- 6 new workflows installed, empathy-map resurrected for Isla
-
-**From v1.1.x, v1.2.x, or v1.3.x to v1.4.0:**
-- No breaking changes
-- Internal architecture refactor (no user-facing changes)
-- Agent files and workflows refreshed
-
-**From v1.0.x to v1.4.0:**
-- Breaking: empathy-map → lean-persona
-- Old workflows preserved in `_deprecated/`
-- 7 new workflows installed
-
-### Troubleshooting
+## Updating
 
 ```bash
-# Run diagnostics
-npx bmad-doctor
+npx bmad-version              # Check current version
+npx bmad-update --dry-run     # Preview changes
+npx bmad-update               # Apply update (auto-backup)
+npx bmad-doctor               # Diagnose issues
 ```
 
-The doctor checks project root, config validity, agent files, workflows, output directory permissions, migration lock status, and version consistency — with actionable fix suggestions for each issue.
+Your data in `_bmad-output/` is never touched. Automatic backups are created before every update.
 
-If update fails:
-
-```bash
-# Check migration logs
-ls _bmad-output/.logs/
-
-# Restore from backup
-cp -r _bmad-output/.backups/backup-{version}-{timestamp}/* _bmad/bme/_vortex/
-
-# Reinstall (preserves user data)
-npx bmad-install-vortex-agents
-```
-
-**📖 See [UPDATE-GUIDE.md](UPDATE-GUIDE.md) for comprehensive update documentation**
+See [UPDATE-GUIDE.md](UPDATE-GUIDE.md) for migration paths and troubleshooting.
 
 ---
 
-## 🏗️ Architecture
-
-### BMAD Agent Architecture Framework v1.1.0
-
-All agents built using a standard pattern:
+## Using the Agents
 
-**Core Components:**
-- **XML-based agent structure** - Agent definition in markdown code blocks
-- **Config-driven personalization** - user_name, communication_language, output_folder
-- **Step-file workflow pattern** - Just-in-time sequential workflow loading
-- **Menu-driven interaction** - Numeric, text, and fuzzy command matching
-- **Error handling** - Robust validation with clear error messages
-- **Artifact generation** - Template-based professional output
+Each agent can be used independently or as part of the full Vortex flow:
 
-**Pattern Proven:** Emma + Wade (reference implementations) validated with 100% P0 test pass rate (18/18 tests each)
-
----
+1. **Emma (Contextualize)** — Start here when defining a new product or problem space
+2. **Isla (Empathize)** — Start here when you need to understand users better
+3. **Mila (Synthesize)** — Start here when you have research to converge into a problem definition
+4. **Liam (Hypothesize)** — Start here when you have a problem definition and need testable hypotheses
+5. **Wade (Externalize)** — Start here when you have hypotheses ready to test
+6. **Noah (Sensitize)** — Start here when experiments have graduated to production
+7. **Max (Systematize)** — Start here when you have results and need to decide next steps
 
-## 🚀 Agents
+Max's **Vortex Navigation** workflow helps identify which stream needs attention based on evidence gaps — you don't have to follow a linear path. Every workflow ends with a **Vortex Compass** that routes you to the right next agent based on what you learned.
 
-### Emma (contextualization-expert) - ✅ COMPLETE
+For detailed workflow descriptions and usage examples, see the [Agent Guide](docs/agents.md) and the individual user guides:
 
-**Status:** v1.5.0 - All 3 workflows implemented and ready to use
-**Title:** Contextualization Expert 🎯
-**Stream:** Contextualize
-**Domain:** Strategic framing, problem-product space navigation
-
-**Workflows Available Now:**
-- **lean-persona** - Create jobs-to-be-done focused personas (6 steps)
-- **product-vision** - Define clear product vision and strategic direction (6 steps)
-- **contextualize-scope** - Decide which problem space to investigate (6 steps)
-
-**Key Positioning:**
-- Helps teams frame the right problem before building solutions
-- Focus on Lean Startup methodologies and validated assumptions
-- Guides teams through strategic clarity before tactical execution
-- Hypothesis-driven with built-in validation planning
-
-**Differentiation:**
-- **Emma vs Maya:** Emma contextualizes (problem space), Maya creates (solution space)
-- Emma answers "What should we solve?" before Maya answers "How should we solve it?"
-
-**Output:** Lean personas, product visions, and scope decisions in `_bmad-output/vortex-artifacts/`
+- [Emma User Guide](_bmad-output/vortex-artifacts/EMMA-USER-GUIDE.md)
+- [Isla User Guide](_bmad-output/vortex-artifacts/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)
+- [Noah User Guide](_bmad/bme/_vortex/guides/NOAH-USER-GUIDE.md)
+- [Max User Guide](_bmad-output/vortex-artifacts/MAX-USER-GUIDE.md)
 
 ---
 
-### Isla (discovery-empathy-expert) - ✅ COMPLETE
-
-**Status:** v1.5.0 - All 3 workflows implemented and ready to use
-**Title:** Discovery & Empathy Expert 🔍
-**Stream:** Empathize
-**Domain:** User research, empathy mapping, discovery
+## How It Fits with BMAD Core
 
-**Workflows Available Now:**
-- **empathy-map** - Build deep user understanding through empathy mapping (5 steps)
-- **user-interview** - Design interview scripts and capture findings (6 steps)
-- **user-discovery** - Plan and execute discovery research (6 steps)
+BMAD-Enhanced handles **pre-implementation validation**. BMAD Core handles **implementation**.
 
-**Key Positioning:**
-- Helps teams deeply understand users before designing solutions
-- Focus on evidence-based user insights over assumptions
-- Guides teams through structured discovery and empathy practices
-- Bridges the gap between strategic framing and experimentation
-
-**Differentiation:**
-- **Isla vs Emma:** Isla empathizes (understand users), Emma contextualizes (frame the problem)
-- Isla answers "Who are our users and what do they need?" to inform Emma's strategic framing
-
-**Output:** Empathy maps, interview findings, discovery reports in `_bmad-output/vortex-artifacts/`
-
----
-
-### Wade (lean-experiments-specialist) - ✅ COMPLETE
-
-**Status:** v1.5.0 - All 4 workflows implemented and ready to use
-**Title:** Lean Experiments Specialist 🧪
-**Stream:** Externalize
-**Domain:** Lean Startup experimentation, validated learning
-
-**Workflows Available Now:**
-- **mvp** - Design Minimum Viable Product to test riskiest assumptions (6 steps)
-- **lean-experiment** - Run Build-Measure-Learn cycles (6 steps)
-- **proof-of-concept** - Validate technical feasibility (6 steps)
-- **proof-of-value** - Validate business value (6 steps)
-
-**Key Positioning:**
-- Helps teams test assumptions with real users through rapid experiments
-- Focus on validated learning over perfection
-- Guides teams from hypotheses to evidence
-- Build-Measure-Learn cycles with pivot-or-persevere decisions
-
-**Differentiation:**
-- **Wade vs Sally:** Wade externalizes (test with users), Sally internalizes (test with code)
-- Wade answers "Should we build this?" before Sally answers "How do we build this well?"
-
-**Output:** MVP specs, experiment results, PoC/PoV evaluations in `_bmad-output/vortex-artifacts/`
-
----
-
-### Max (learning-decision-expert) - ✅ COMPLETE
-
-**Status:** v1.5.0 - All 3 workflows implemented and ready to use
-**Title:** Learning & Decision Expert 🧭
-**Stream:** Systematize
-**Domain:** Learning capture, decision frameworks, Vortex navigation
-
-**Workflows Available Now:**
-- **learning-card** - Capture what was tested, learned, and decided (6 steps)
-- **pivot-patch-persevere** - Evidence-based decision framework after experiments (6 steps)
-- **vortex-navigation** - Decide which Vortex stream to focus on next (6 steps)
-
-**Key Positioning:**
-- Helps teams systematize learnings and make evidence-based decisions
-- Focus on capturing validated learning as organizational knowledge
-- Guides teams through pivot/patch/persevere decisions
-- Navigates between Vortex streams based on evidence and gaps
-
-**Differentiation:**
-- **Max vs Wade:** Max systematizes (what did we learn?), Wade externalizes (test with users)
-- Max answers "What should we do next?" based on accumulated evidence
-
-**Output:** Learning cards, decision documents, navigation recommendations in `_bmad-output/vortex-artifacts/`
-
----
-
-## 📊 Project Status
-
-**Current Version:** v1.5.0 - Wave 2: Four Vortex Agents ✅
-
-**Progress:**
-- ✅ Emma - 3 Contextualize workflows IMPLEMENTED
-- ✅ Isla - 3 Empathize workflows IMPLEMENTED (NEW in v1.5.0)
-- ✅ Wade - 4 Externalize workflows IMPLEMENTED
-- ✅ Max - 3 Systematize workflows IMPLEMENTED (NEW in v1.5.0)
-- ✅ 104 workflow files created (13 workflows × 8 files each)
-- ✅ Update/migration system with backup and rollback
-- ✅ Standalone installation support (no BMAD Method required)
-- ✅ `npx bmad-doctor` diagnostic CLI
-- ✅ CI pipeline with lint, test matrix, coverage, security, publish-on-tag
-
-**What's New in v1.5.0:**
-- **Isla (Discovery & Empathy Expert)** - Empathize stream with empathy-map, user-interview, user-discovery workflows
-- **Max (Learning & Decision Expert)** - Systematize stream with learning-card, pivot-patch-persevere, vortex-navigation workflows
-- **`npx bmad-install-vortex-agents`** - New primary installer for all 4 Vortex agents
-- **Empathy-map resurrected** - Moved from deprecated back to active, now owned by Isla
-- **Legacy installer deprecation** - `install-emma`/`install-wade` now show deprecation warnings
-
-**Roadmap:**
 ```
-v1.1.0             v1.3.x ✅        v1.4.x ✅        v1.5.0 ✅          v2.0.0
-├────────────────┬────────────────┬────────────────┬────────────────┬──────────┤
-│ Foundation ✅   │ Tooling ✅      │ Quality ✅      │ Wave 2 ✅       │ Advanced │
-│ • Emma + Wade  │ • Update tools │ • Refactor     │ • Isla + Max   │ • Wave 3 │
-│ • 7 workflows  │ • Migration    │ • 183 tests    │ • 13 workflows │ • Multi  │
-│ • Framework    │ • Automation   │ • CI/CD + lint │ • 4 streams    │ • Stats  │
-└────────────────┴────────────────┴────────────────┴────────────────┴──────────┘
-   Feb 2026         Feb 2026         Feb 2026         Feb 2026         Q3 2026
+BMAD-Enhanced (Vortex)                          BMAD Core
+┌──────────────────────────────────────┐       ┌──────────────────────┐
+│ Isla → Mila → Liam → Wade → Noah    │ ───>  │ PM → Architect → Dev │
+│   ↑                          ↓       │       │ "Let's build it"     │
+│   └──── Max ◀── Noah    Max ↻        │       └──────────────────────┘
+│ Emma provides context at any point   │
+│ "Should we build this?"             │
+└──────────────────────────────────────┘
 ```
 
-**See:** [CHANGELOG.md](CHANGELOG.md) for complete version history
+BMAD-Enhanced works standalone or as an extension — no BMAD Method installation required.
 
 ---
 
-## 📚 Documentation
-
-### User Guides
-
-- **[Emma User Guide](_bmad-output/vortex-artifacts/EMMA-USER-GUIDE.md)** - Complete guide to strategic contextualization with Emma
-- **[Isla User Guide](_bmad-output/vortex-artifacts/ISLA-USER-GUIDE.md)** - Complete guide to discovery and empathy with Isla
-- **[Wade User Guide](_bmad-output/vortex-artifacts/WADE-USER-GUIDE.md)** - Complete guide to lean experiments with Wade
-- **[Max User Guide](_bmad-output/vortex-artifacts/MAX-USER-GUIDE.md)** - Complete guide to learning and decisions with Max
-
-### Technical Documentation
-
-- **[BMAD Agent Architecture Framework](_bmad-output/GENERIC-AGENT-INTEGRATION-FRAMEWORK.md)** - Standard agent pattern (v1.1.0)
-- **[Emma Reference Implementation](_bmad-output/EMMA-REFERENCE-IMPLEMENTATION-COMPLETE.md)** - How Emma was built
+## Documentation
 
-### Test Results
-
-- **[Emma Test Results](_bmad-output/test-artifacts/emma-tests/emma-p0-test-results.md)** - P0 test validation (18/18 passed)
-- **[Emma Stakeholder Review](_bmad-output/test-artifacts/emma-tests/STAKEHOLDER-SIGNOFF-REVIEW.md)** - Approval documentation
-- **[Wade Test Results](_bmad-output/test-artifacts/wade-tests/wade-p0-test-execution.md)** - P0 test validation (18/18 passed)
-- **Isla Test Results** - Pending (Wave 2 agent, workflow validation in progress)
-- **Max Test Results** - Pending (Wave 2 agent, workflow validation in progress)
-
-### Planning Artifacts
-
-- **[Project Status Update](_bmad-output/PROJECT-STATUS-UPDATE.md)** - Current progress and timeline
-- **[Phase 0 Implementation Guide](_bmad-output/planning-artifacts/phase-0-implementation-guide.md)** - Complete implementation plan
-- **[Original Multi-Framework Vision](_bmad-output/planning-artifacts/ORIGINAL-VISION-README.md)** - Earlier exploration (archived)
-
-**Browse all documentation:** [_bmad-output/README.md](_bmad-output/README.md)
+| Document | Description |
+|----------|-------------|
+| [Agent Guide](docs/agents.md) | Detailed agent descriptions, workflows, and positioning |
+| [Testing](docs/testing.md) | Automated test suite, CI pipeline, and agent test results |
+| [Development Guide](docs/development.md) | Architecture, building agents, and contributing |
+| [FAQ](docs/faq.md) | Common questions about the framework |
+| [CHANGELOG](CHANGELOG.md) | Complete version history |
+| [UPDATE-GUIDE](UPDATE-GUIDE.md) | Migration paths and update troubleshooting |
 
 ---
 
-## 💡 Key Features
-
-### 🎯 Lean Startup Validation Framework
-
-The Vortex framework brings structured validation to product development:
-- **Contextualize Stream (Emma):** Frame the right problem before building
-- **Empathize Stream (Isla):** Understand users through research and empathy
-- **Externalize Stream (Wade):** Test assumptions with real users
-- **Systematize Stream (Max):** Capture learnings and navigate between streams
-- **Integrated Approach:** Strategic clarity → User empathy → Validated learning → Systematic decisions
-- **Vortex Compass:** Every workflow ends with evidence-driven navigation — "If you learned X → go to Y" — creating non-linear loops across all streams
-
-### 🔄 Clear Agent Differentiation
-
-**Emma vs Maya:**
-- Emma: Contextualizes (What problem should we solve?)
-- Maya: Creates (How should we solve it?)
-
-**Wade vs Sally:**
-- Wade: Externalizes (Should we build this? - test with users)
-- Sally: Internalizes (Are we building it well? - test with code)
-
-### 🚀 Strategic Positioning
-
-BMAD-Enhanced now focuses on the critical pre-implementation phase:
-1. **Emma:** Frame strategy and define problem space
-2. **Isla:** Understand users through research and empathy
-3. **Wade:** Validate assumptions through experiments
-4. **Max:** Capture learnings and decide what to do next
-5. **Hand off to BMAD Core:** Let PM/Dev/QA agents implement
-
-### 🔄 Reusable Patterns
-
-Emma validates patterns used by all agents:
-- XML-based agent structure
-- Config-driven personalization
-- Step-file workflow architecture
-- Menu-driven interaction (3 command types)
-- Professional artifact generation
-
-**Impact:** Each subsequent agent developed 33% faster than Emma (8 hours vs. 12 hours)
+## Roadmap
 
-### 📖 User-Friendly
-
-Clear, comprehensive documentation:
-- User guides with examples and troubleshooting
-- Multiple invocation methods (slash command + direct file reading)
-- Step-by-step workflow guidance
-- Best practices and FAQs
-
----
-
-## 🛠️ Development
-
-### Building a New Agent
-
-1. **Clone Emma's structure:**
-   ```bash
-   cp _bmad/bme/_vortex/agents/contextualization-expert.md \
-      _bmad/bme/_vortex/agents/your-agent.md
-   ```
-
-2. **Customize the agent:**
-   - Update persona (role, identity, communication style, principles)
-   - Define menu options (workflows, chat, validate)
-   - Create workflow step files
-   - Add templates for output artifacts
-
-3. **Register in manifest:**
-   ```csv
-   "your-agent","YourName","Your Title","🎯","role","identity",...
-   ```
-
-4. **Test thoroughly:**
-   - Clone Emma test plan (39 scenarios)
-   - Execute P0 tests (18 critical scenarios)
-   - Target: 100% pass rate
-
-**See:** [BMAD Agent Architecture Framework](_bmad-output/GENERIC-AGENT-INTEGRATION-FRAMEWORK.md)
+- **v1.1.0–v1.5.x** — Waves 1-2: Foundation (Emma, Isla, Wade, Max — 4 agents, 13 workflows, update system, CI/CD)
+- **v1.6.0** — Wave 3: Complete 7-stream Vortex (added Mila, Liam, Noah — 22 workflows, 10 handoff contracts, Compass routing)
+- **v2.0.0+** — Multi-agent collaboration, cross-agent workflows, analytics
 
 ---
 
-## 🧪 Testing
-
-### Automated Test Suite
-
-Zero-dependency test runner (`node:test`)
-
-| Suite | Tests | Coverage |
-|-------|-------|----------|
-| utils | 12 | compareVersions, getPackageVersion, findProjectRoot |
-| registry | 19 | getMigrationsFor, getBreakingChanges, hasMigrationBeenApplied |
-| version-detector | 23 | getCurrentVersion, detectInstallationScenario |
-| config-merger | 17 | mergeConfig, validateConfig, addMigrationHistory |
-| backup-manager | 11 | createBackup, restoreBackup, cleanupOldBackups |
-| migration-runner | 10 | executeMigration, previewMigrations, MigrationError |
-| migration-runner-orchestration | 9 | runMigrations full cycle, dry-run, skip, lock conflict, error handling |
-| validator | 23 | validateInstallation, config, agents, workflows, manifest, user data, deprecated |
-| migrations-to-1.5.0 | 6 | 1.3.x and 1.4.x migration metadata, preview, apply |
-| fresh-install (integration) | 9 | refreshInstallation end-to-end (all 4 agents) |
-| upgrade (integration) | 22 | v1.0.x→1.5.0, v1.3.x→1.5.0, v1.4.x→1.5.0 upgrade paths |
-| cli-entry-points (integration) | 8 | index.js, bmad-version, bmad-update, bmad-doctor |
-| installer-e2e (integration) | 7 | install-vortex-agents CLI end-to-end, idempotency |
-| bmad-doctor (integration) | 7 | negative paths: no project, missing config, invalid YAML, missing agents, stale/corrupt lock, version mismatch |
-
-**CI Pipeline (6 jobs):**
-
-| Job | What it does |
-|-----|-------------|
-| `lint` | ESLint with architecture rules (no `process.cwd()`) |
-| `test` | Node 18/20/22 matrix, unit + integration |
-| `coverage` | c8 with threshold enforcement (60% lines, 50% branches) |
-| `security` | `npm audit --omit=dev` |
-| `package-check` | `npm pack --dry-run` + `node index.js` |
-| `publish` | Automated npm publish on `v*` tags |
-
-```bash
-npm test                 # Unit tests
-npm run test:integration # Integration tests
-npm run test:all         # All tests
-npm run test:coverage    # Tests with coverage thresholds
-npm run lint             # ESLint
-```
-
-### Emma Test Results
+## Contributing
 
-**P0 Test Suite:** 18/18 PASSED (100%)
+We welcome contributions in these areas:
 
-| Domain | Scenarios | Passed | Status |
-|--------|-----------|--------|--------|
-| Agent Activation | 7 | 7 | ✅ PASS |
-| Command Processing | 3 | 3 | ✅ PASS |
-| Workflow Execution | 6 | 6 | ✅ PASS |
-| Registration | 3 | 2 | ⚠️ PARTIAL* |
+- **Agents** — New domain-specialized agents, workflow improvements
+- **Testing** — Edge cases, performance testing
+- **Documentation** — Tutorials, translations, video walkthroughs
+- **Integration** — IDE plugins, third-party tools
 
-*One environment limitation (slash command), validated workaround exists
-
-**Quality Gates:** 6/6 PASSED
-- ✅ Test Coverage: 100%
-- ✅ Pass Rate: 100%
-- ✅ Critical Path: End-to-end validated
-- ✅ Risk Mitigation: High risks addressed
-- ✅ Usability: Smooth user experience
-- ✅ Documentation: Complete
-
-**See:** [Emma Test Results](_bmad-output/test-artifacts/emma-tests/emma-p0-test-results.md)
-
-### Wade Test Results
-
-**P0 Test Suite:** 18/18 PASSED (100%)
-
-| Domain | Scenarios | Passed | Status |
-|--------|-----------|--------|--------|
-| Activation & Registration | 6 | 6 | ✅ PASS |
-| Command Processing | 3 | 3 | ✅ PASS |
-| Workflow Execution | 6 | 6 | ✅ PASS |
-| Error Handling | 3 | 3 | ✅ PASS |
-
-**Live Test Suite:** 5/5 PASSED (100%)
-- ✅ Agent Activation
-- ✅ Full Workflow Execution
-- ✅ Validation Workflow
-- ✅ Chat Mode
-- ✅ Party Mode Integration
-
-**Quality Gates:** 6/6 PASSED
-- ✅ Test Coverage: 100%
-- ✅ Pass Rate: 100%
-- ✅ Critical Path: End-to-end validated
-- ✅ Risk Mitigation: High risks addressed
-- ✅ Usability: Smooth user experience
-- ✅ Documentation: Complete
-
-**See:** [Wade Test Results](_bmad-output/test-artifacts/wade-tests/wade-p0-test-execution.md)
-
-### Isla Test Results
-
-**Status:** Pending formal P0 test execution
-
-Isla follows the same agent architecture as Emma and Wade. Infrastructure validation is covered by the automated test suite:
-- ✅ Installation verified (fresh-install integration tests)
-- ✅ Upgrade paths verified (v1.3.x and v1.4.x upgrade tests)
-- ✅ CLI entry points verified (agent listed in `bmad-enhanced` output)
-- ✅ All 3 workflow directories present with templates, steps, and validation
-- Formal P0 test suite (agent activation, command processing, workflow execution) planned for v1.5.1
-
-### Max Test Results
-
-**Status:** Pending formal P0 test execution
-
-Max follows the same agent architecture as Emma and Wade. Infrastructure validation is covered by the automated test suite:
-- ✅ Installation verified (fresh-install integration tests)
-- ✅ Upgrade paths verified (v1.3.x and v1.4.x upgrade tests)
-- ✅ CLI entry points verified (agent listed in `bmad-enhanced` output)
-- ✅ All 3 workflow directories present with templates, steps, and validation
-- Formal P0 test suite (agent activation, command processing, workflow execution) planned for v1.5.1
+See the [Development Guide](docs/development.md) for architecture details and agent development patterns.
 
 ---
 
-## 📈 Roadmap
-
-### Completed
+## License
 
-- ✅ **v1.1.0** - Vortex Framework repositioning (Emma + Wade)
-- ✅ **v1.2.0** - All 7 workflows implemented (56 files)
-- ✅ **v1.3.x** - Update/migration system with backup and rollback
-- ✅ **v1.4.0** - Architecture refactor (single source of truth, project root detection, safer migrations)
-- ✅ **v1.4.1** - Industrial-grade tooling (183 tests, CI/CD, ESLint, bmad-doctor, publish-on-tag)
-- ✅ **v1.5.0** - Wave 2: Isla + Max agents, 13 workflows, 4 Vortex streams
+MIT License — see [LICENSE](LICENSE)
 
-### Future (v1.6.0 / v2.0.0+)
+## Acknowledgments
 
-- 📋 Wave 3: Synthesize, Hypothesize, Sensitize streams (3 more agents)
-- 📋 Data-driven agent/workflow registry (replace hardcoded arrays)
-
-- 📋 Multi-agent collaboration patterns
-- 📋 Cross-agent workflow integration
-- 📋 Analytics and reporting
-- 📋 Community agent contributions
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! Areas where we need help:
-
-**Agent Development:**
-- New domain-specialized agents
-- Workflow improvements
-- Template enhancements
-
-**Testing:**
-- P1/P2 test execution
-- Edge case testing
-- Performance testing
-
-**Documentation:**
-- User guides
-- Tutorials
-- Video walkthroughs
-- Translation (internationalization)
-
-**Integration:**
-- BMAD CLI integration
-- IDE plugins
-- Third-party tool integrations
-
-**See:** CONTRIBUTING.md (coming soon)
-
----
-
-## 💼 Business Value
-
-### For Product Managers & Strategists (Emma)
-
-**Before:**
-- Unclear problem definition
-- Assumptions presented as facts
-- No validation plan for strategy
-- Weeks of strategic discussion
-
-**After (v1.5.0):**
-- Clear problem space framing: 1-2 hours
-- Explicit assumption mapping
-- Built-in validation planning
-- Strategic alignment in days
-
-**Value:** Faster strategic clarity, reduced risk of building the wrong thing
-
-### For UX Researchers & Design Teams (Isla)
-
-**Before:**
-- Ad-hoc user research with no structure
-- Empathy maps based on assumptions, not evidence
-- Interviews without clear research goals
-- User insights scattered across documents
-
-**After (v1.5.0):**
-- Structured discovery research: 2-4 hours per activity
-- Evidence-based empathy maps grounded in real user data
-- Interview guides with clear goals and synthesis
-- Centralized user insights in standardized artifacts
-
-**Value:** Deeper user understanding, research-backed design decisions, reduced rework from wrong assumptions
-
-### For Innovation Teams (Wade)
-
-**Before:**
-- Long development cycles before user feedback
-- High investment in unvalidated ideas
-- No structured experiment process
-- 6-12 months to market validation
-
-**After (v1.5.0):**
-- Rapid experiment design: 2-3 hours
-- Minimal investment in learning
-- Structured Build-Measure-Learn cycles
-- 2-4 weeks to validated learning
-
-**Value:** 70-80% faster validation, 90% lower validation cost, data-driven decisions
-
-### For Leadership & Decision Makers (Max)
-
-**Before:**
-- Experiment results lost or poorly documented
-- Pivot/persevere decisions based on gut feeling
-- No systematic way to capture validated learnings
-- Teams unsure which problem area to focus on next
-
-**After (v1.5.0):**
-- Structured learning cards capturing evidence and decisions
-- Evidence-based pivot/patch/persevere framework
-- Accumulated organizational knowledge from experiments
-- Vortex navigation recommendations based on gap analysis
-
-**Value:** Institutional learning, faster strategic pivots, evidence-driven portfolio decisions
-
-### For Startups & Product Teams
-
-**The Complete Vortex Flow:**
-- Emma: Strategic framing and problem-solution fit
-- Isla: User empathy and evidence-based understanding
-- Wade: Validated learning and product-market fit
-- Max: Systematic decisions and strategic navigation
-- BMAD Core: Implementation and delivery
-
-**Impact:**
-- Validate before building (avoid waste)
-- Understand users before designing (reduce rework)
-- Learn fast, pivot faster (reduce risk)
-- Data-driven decisions (evidence over opinions)
-
----
-
-## 📊 Success Metrics
-
-### Emma (Operational Metrics)
-
-**Adoption (Target):**
-- 50+ teams using Emma for strategic contextualization
-- 80%+ complete the full 6-step workflow
-- NPS ≥8
-
-**Quality (Target):**
-- 90%+ lean personas grounded in research evidence
-- 95%+ artifacts include all required sections (assumptions, validation plan)
-
-**Performance (Measured):**
-- Complete workflow: 30-60 minutes
-- Artifact generation: <5 seconds
-
-### Isla (Operational Metrics)
-
-**Adoption (Target):**
-- 50+ teams using Isla for user discovery and empathy
-- 80%+ complete the full workflow for each activity
-- NPS ≥8
-
-**Quality (Target):**
-- 90%+ empathy maps grounded in real user data (not assumptions)
-- 95%+ interview guides include clear research goals and synthesis
-- 85%+ discovery reports include actionable insights with evidence
-
-**Performance (Measured):**
-- Complete empathy map: 30-45 minutes
-- Complete interview workflow: 45-90 minutes
-- Complete discovery research: 60-120 minutes
-
-### Wade (Operational Metrics)
-
-**Adoption (Target):**
-- 50+ teams using Wade for lean experiments
-- 80%+ complete the full 6-step workflow
-- NPS ≥8
-
-**Quality (Target):**
-- 90%+ experiments include clear hypothesis and success metrics
-- 95%+ artifacts include pivot-or-persevere decision criteria
-- 85%+ pass validated learning checklist
-
-**Performance (Measured):**
-- Complete workflow: 45-90 minutes
-- Artifact generation: <5 seconds
-
-### Max (Operational Metrics)
-
-**Adoption (Target):**
-- 50+ teams using Max for learning capture and decisions
-- 80%+ complete the full workflow for each activity
-- NPS ≥8
-
-**Quality (Target):**
-- 90%+ learning cards link back to specific experiment evidence
-- 95%+ pivot/patch/persevere decisions include quantitative thresholds
-- 85%+ vortex navigation recommendations cite evidence gaps
-
-**Performance (Measured):**
-- Complete learning card: 20-30 minutes
-- Complete pivot/patch/persevere: 30-60 minutes
-- Complete vortex navigation: 30-45 minutes
-
-### Project-Wide (Target Post-Launch)
-
-**Adoption:**
-- 100+ teams using BMAD-Enhanced agents
-- 4/4 Vortex agents in production ✅ (Wave 2)
-- Community agents contributed
-
-**Quality:**
-- 100% P0 test pass rate for all agents
-- All quality gates passed before release
-- 180+ automated tests across unit and integration suites
-
----
-
-## 🔍 Sample Output
-
-### Emma Lean Persona Artifact
-
-Emma generates comprehensive lean personas with:
-
-**Executive Summary:**
-- Jobs-to-be-done identification
-- Top riskiest assumptions
-- Validation plan priorities
-
-**Detailed Sections:**
-- Target user profile (demographics, context, goals)
-- Jobs-to-be-done (functional, emotional, social)
-- Pain points (prioritized: HIGH/MEDIUM/LOW)
-- Current alternatives and workarounds
-- Riskiest assumptions (ranked by impact and uncertainty)
-
-**Validation Planning:**
-- Which assumptions to test first
-- Suggested experiment types
-- Success/failure criteria
-
-**Assumption Prioritization Matrix:**
-| Assumption | Risk Level | Experiment Type | Priority |
-|------------|-----------|-----------------|----------|
-| Users want X | HIGH | Interview | P0 |
-
-**See:** [Emma User Guide](_bmad-output/vortex-artifacts/EMMA-USER-GUIDE.md) for examples
-
-### Wade MVP Specification Artifact
-
-Wade generates comprehensive MVP specs with:
-
-**Executive Summary:**
-- Riskiest assumption to test
-- MVP type and scope
-- Build-Measure-Learn cycle plan
-
-**Detailed Sections:**
-- Hypothesis statement (testable, falsifiable)
-- MVP scope (minimum needed to test assumption)
-- Success metrics (quantitative thresholds)
-- Measurement plan (how to collect data)
-- Timeline and resource requirements
-
-**Experiment Design:**
-- Target audience and sample size
-- Data collection methods
-- Analysis approach
-- Pivot-or-persevere decision criteria
-
-**Decision Framework:**
-- Evidence thresholds for persevere
-- Evidence thresholds for pivot
-- Kill criteria
-
-**See:** [Wade User Guide](_bmad-output/vortex-artifacts/WADE-USER-GUIDE.md) for examples
-
-### Isla Empathy Map Artifact
-
-Isla generates evidence-based empathy maps with:
-
-**User Profile:**
-- Target user segment and context
-- Research methods used (interviews, observation, surveys)
-
-**Empathy Quadrants:**
-- Says: Direct quotes and statements from users
-- Thinks: Inferred thoughts, beliefs, and mental models
-- Does: Observable behaviors and actions
-- Feels: Emotional states and reactions
-
-**Pain & Gain Analysis:**
-- Pain points (prioritized: HIGH/MEDIUM/LOW)
-- Gains and desired outcomes
-- Gaps between current state and desired state
-
-**Synthesis:**
-- Key insights from the empathy mapping exercise
-- Assumptions validated or invalidated
-- Recommended next steps (further research, experiments, design)
-
-**See:** [Isla User Guide](_bmad-output/vortex-artifacts/ISLA-USER-GUIDE.md) for examples
-
-### Max Learning Card Artifact
-
-Max generates structured learning cards with:
-
-**Experiment Context:**
-- Hypothesis tested and experiment type
-- Link to original experiment (Wade artifacts)
-- Timeline and scope
-
-**Results & Analysis:**
-- Raw results and data collected
-- Statistical significance and confidence level
-- What worked, what didn't, and surprises
-
-**Validated Learning:**
-- What was learned (stated as validated or invalidated hypothesis)
-- Evidence strength (strong/moderate/weak)
-- Implications for product strategy
-
-**Decision & Next Steps:**
-- Pivot, patch, or persevere recommendation
-- Specific actions and owners
-- Impact on other Vortex streams
-
-**See:** [Max User Guide](_bmad-output/vortex-artifacts/MAX-USER-GUIDE.md) for examples
-
----
-
-## 🎓 Learning Resources
-
-### For Users
-
-**Emma (Strategic Contextualization):**
-- **[Emma User Guide](_bmad-output/vortex-artifacts/EMMA-USER-GUIDE.md)** - Complete guide with examples
-- Emma's chat mode (CH command) - Ask Emma questions about lean personas, product vision, and scope
-
-**Isla (Discovery & Empathy):**
-- **[Isla User Guide](_bmad-output/vortex-artifacts/ISLA-USER-GUIDE.md)** - Complete guide with examples
-- Isla's chat mode (CH command) - Ask Isla questions about empathy maps, interviews, and user discovery
-
-**Wade (Lean Experiments):**
-- **[Wade User Guide](_bmad-output/vortex-artifacts/WADE-USER-GUIDE.md)** - Complete guide with examples
-- Wade's chat mode (CH command) - Ask Wade questions about MVPs, experiments, and validated learning
-
-**Max (Learning & Decisions):**
-- **[Max User Guide](_bmad-output/vortex-artifacts/MAX-USER-GUIDE.md)** - Complete guide with examples
-- Max's chat mode (CH command) - Ask Max questions about learning cards, decisions, and Vortex navigation
-
-### For Developers
-
-- **[BMAD Agent Architecture Framework](_bmad-output/GENERIC-AGENT-INTEGRATION-FRAMEWORK.md)** - How to build agents
-- **[Emma Reference Implementation](_bmad-output/EMMA-REFERENCE-IMPLEMENTATION-COMPLETE.md)** - Detailed walkthrough
-- **[Test Design Document](_bmad-output/test-artifacts/test-design/emma-agent-verification-test-design.md)** - How to test agents
-
-### For Stakeholders
-
-- **[Project Status Update](_bmad-output/PROJECT-STATUS-UPDATE.md)** - Current progress
-- **[CHANGELOG.md](CHANGELOG.md)** - Complete version history
-- **[Emma Test Results](_bmad-output/test-artifacts/emma-tests/emma-p0-test-results.md)** - Emma quality validation
-- **[Wade Test Results](_bmad-output/test-artifacts/wade-tests/wade-p0-test-execution.md)** - Wade quality validation
-- Isla and Max P0 test results - Planned for v1.5.1
-
----
-
-## 🏛️ Architecture Principles
-
-### 1. Domain Specialization Over Generic Tools
-
-Each agent brings deep expertise in a specific domain (strategic framing, lean experimentation) rather than generic capabilities.
-
-### 2. Standard Interface, Diverse Expertise
-
-All agents use BMAD Agent Architecture Framework for consistency, but each has unique workflows and knowledge.
-
-### 3. Research-Driven Design
-
-Workflows based on proven frameworks (Jobs-to-be-Done, Lean Startup, Build-Measure-Learn).
-
-### 4. Test-First Development
-
-100% P0 test coverage required before operational approval. Emma set the standard.
-
-### 5. Documentation as First-Class Citizen
-
-Comprehensive user guides required for each agent. Users should be able to self-serve.
-
-### 6. Error Handling from Day One
-
-Clear, actionable error messages. Users should never be confused about what went wrong or how to fix it.
-
----
-
-## 📜 License
-
-MIT License - see [LICENSE](LICENSE)
-
----
-
-## 🙏 Acknowledgments
-
-Built on:
-- **[BMAD Method v6.0.0](https://github.com/bmadhub/bmad)** - Foundation for agent architecture
-- **Claude (Anthropic)** - AI reasoning and agent development
-- **Open Source Community** - Testing, feedback, contributions
-
-**Special Thanks:**
-- Murat (tea agent) - Test architecture and validation
-- BMAD Core Team - Framework and infrastructure
-
----
-
-## 📞 Contact
-
-**Project Lead:** Amalik Amriou
-**Repository:** [github.com/yourusername/BMAD-Enhanced](https://github.com/yourusername/BMAD-Enhanced)
-**Documentation:** `_bmad-output/`
-**Issues:** [GitHub Issues](https://github.com/yourusername/BMAD-Enhanced/issues)
-
----
-
-## ❓ FAQ
-
-### Is this the same as the multi-framework orchestration project?
-
-**No.** This project pivoted from multi-framework orchestration (Quint + DesignOS + BMAD + AgentOS) to focused domain-specialized agents within BMAD.
-
-**Original vision (archived):** [ORIGINAL-VISION-README.md](_bmad-output/planning-artifacts/ORIGINAL-VISION-README.md)
-
-**Current approach:** Vortex Framework with 4 specialized agents (Emma, Isla, Wade, Max) using BMAD Agent Architecture Framework.
-
-### What happened to empathy mapping and wireframing?
-
-**They were repositioned in v1.1.0.** Emma and Wade now focus on Lean Startup validation rather than traditional design deliverables.
-
-**Old positioning (v1.0.x):**
-- Emma: Empathy Mapping Specialist
-- Wade: Wireframe Design Specialist
-
-**New positioning (v1.1.0+):**
-- Emma: Contextualization Expert (strategic framing, lean personas, product vision)
-- Wade: Lean Experiments Specialist (MVPs, experiments, proof-of-concept/value)
-
-**Why?** To create clear differentiation from BMAD core agents (Maya for design, Sally for quality) and focus on the critical pre-implementation validation phase.
-
-### Can I use agents independently?
-
-**Yes!** Each agent works standalone:
-- Use Emma alone for strategic framing and problem space definition
-- Use Isla alone for user research and empathy mapping
-- Use Wade alone for experiment design and validation
-- Use Max alone for learning capture and decision-making
-- Use all four together for the complete Vortex flow: Contextualize → Empathize → Externalize → Systematize
-
-### Are the workflows ready?
-
-**Yes! All 13 workflows are fully implemented and ready to use:**
-
-**Emma (Contextualize):** lean-persona, product-vision, contextualize-scope
-**Isla (Empathize):** empathy-map, user-interview, user-discovery
-**Wade (Externalize):** mvp, lean-experiment, proof-of-concept, proof-of-value
-**Max (Systematize):** learning-card, pivot-patch-persevere, vortex-navigation
-
-Each workflow includes templates, step files, and comprehensive guidance.
-
-### How is this different from BMAD core agents?
-
-**Pre-implementation validation vs. implementation.**
-
-**BMAD-Enhanced (Vortex):** Pre-implementation - validate before building
-- Emma: Strategic framing (what problem should we solve?)
-- Isla: User empathy (who are our users and what do they need?)
-- Wade: Validated learning (should we build this?)
-- Max: Systematic decisions (what did we learn? what's next?)
-
-**BMAD Core:** Implementation - build and deliver
-- Maya: Solution design (how should we solve it?)
-- Dev/Arch: Implementation
-- Sally/QA: Quality validation (are we building it well?)
-
-**Flow:** Emma → Isla → Wade → Max → BMAD Core agents for implementation
-
-### What's the recommended order for the agents?
-
-**Follow the Vortex flow, but jump in wherever you are:**
-
-1. **Emma (Contextualize)** - Start here if you're defining a new product or problem space
-2. **Isla (Empathize)** - Start here if you know the problem but need to understand users better
-3. **Wade (Externalize)** - Start here if you have hypotheses ready to test with users
-4. **Max (Systematize)** - Start here if you have experiment results and need to decide next steps
-
-You don't have to be linear — Max's Vortex Navigation workflow helps you identify which stream needs attention based on your current evidence gaps.
-
-### What's coming in Wave 3?
-
-Wave 3 (v1.6.0) will add the remaining 3 Vortex streams:
-- **Synthesize** - Pattern recognition and insight synthesis across research
-- **Hypothesize** - Structured hypothesis generation from insights
-- **Sensitize** - Stakeholder alignment and organizational buy-in
-
-This will complete the full 7-stream Vortex Framework.
+- [BMAD Method v6.0.0](https://github.com/bmadhub/bmad) — Foundation for agent architecture
+- Claude (Anthropic) — AI reasoning and agent development
+- Murat (tea agent) — Test architecture and validation
+- BMAD Core Team — Framework and infrastructure
 
 ---
 
 <div align="center">
 
-**BMAD-Enhanced - Vortex Framework**
-
-*Contextualize, Empathize, Externalize, and Systematize for Lean Startup Validation*
-
-[Get Started](#quick-start) • [Documentation](#documentation) • [Roadmap](#roadmap)
-
-**Current Status:** ✅ v1.5.0 Stable - 4 Vortex Agents, 13 Workflows
+**Vortex Pattern** — *Validate before you build*
 
-Made with ❤️ by the BMAD-Enhanced community
+[Get Started](#quick-start) | [Agents](docs/agents.md) | [Docs](#documentation) | [Roadmap](#roadmap)
 
 </div>