bmad-enhanced 1.6.4 → 1.6.5

package/CHANGELOG.md

@@ -834,4 +834,4 @@ No changes to installation flow. Reinstallation will fix the Wade workflow bug.
 - [README.md](README.md) - Project overview
 - [INSTALLATION.md](INSTALLATION.md) - Installation guide
 - [BMAD-METHOD-COMPATIBILITY.md](BMAD-METHOD-COMPATIBILITY.md) - Integration details
-- User guides in `_bmad-output/design-artifacts/`
+- User guides in `_bmad/bme/_vortex/guides/`

package/INSTALLATION.md

@@ -20,7 +20,7 @@ BMAD-Enhanced works **standalone** or as an extension to [BMAD Method](https://g
 npm install bmad-enhanced && npx bmad-install-vortex-agents
 ```
 
-All 4 Vortex agents (Emma, Isla, Wade, Max) with 13 workflows are installed and ready to use.
+All 7 Vortex agents (Emma, Isla, Mila, Liam, Wade, Noah, Max) with 22 workflows are installed and ready to use.
 
 ---
 
@@ -62,8 +62,11 @@ your-project/
 │   │       ├── agents/
 │   │       │   ├── contextualization-expert.md      # Emma
 │   │       │   ├── discovery-empathy-expert.md       # Isla
-│   │       │   ├── lean-experiments-specialist.md    # Wade
-│   │       │   └── learning-decision-expert.md       # Max
+│   │       │   ├── research-convergence-specialist.md # Mila
+│   │       │   ├── hypothesis-engineer.md             # Liam
+│   │       │   ├── lean-experiments-specialist.md     # Wade
+│   │       │   ├── production-intelligence-specialist.md # Noah
+│   │       │   └── learning-decision-expert.md        # Max
 │   │       ├── workflows/
 │   │       │   ├── lean-persona/                     # Emma workflows
 │   │       │   ├── product-vision/
@@ -71,10 +74,19 @@ your-project/
 │   │       │   ├── empathy-map/                      # Isla workflows
 │   │       │   ├── user-interview/
 │   │       │   ├── user-discovery/
+│   │       │   ├── research-convergence/             # Mila workflows
+│   │       │   ├── pivot-resynthesis/
+│   │       │   ├── pattern-mapping/
+│   │       │   ├── hypothesis-engineering/           # Liam workflows
+│   │       │   ├── assumption-mapping/
+│   │       │   ├── experiment-design/
 │   │       │   ├── mvp/                              # Wade workflows
 │   │       │   ├── lean-experiment/
 │   │       │   ├── proof-of-concept/
 │   │       │   ├── proof-of-value/
+│   │       │   ├── signal-interpretation/            # Noah workflows
+│   │       │   ├── behavior-analysis/
+│   │       │   ├── production-monitoring/
 │   │       │   ├── learning-card/                    # Max workflows
 │   │       │   ├── pivot-patch-persevere/
 │   │       │   └── vortex-navigation/
@@ -85,17 +97,20 @@ your-project/
     └── vortex-artifacts/
         ├── EMMA-USER-GUIDE.md
         ├── ISLA-USER-GUIDE.md
+        ├── MILA-USER-GUIDE.md
+        ├── LIAM-USER-GUIDE.md
         ├── WADE-USER-GUIDE.md
+        ├── NOAH-USER-GUIDE.md
         ├── MAX-USER-GUIDE.md
         └── (your generated artifacts)
 ```
 
 ### Summary
 
-- **4 agent definitions** in `_bmad/bme/_vortex/agents/`
-- **13 workflows** (104 files) — each with steps, templates, and validation
+- **7 agent definitions** in `_bmad/bme/_vortex/agents/`
+- **22 workflows** (169 files) — each with steps, templates, and validation
 - **Configuration** in `_bmad/bme/_vortex/config.yaml`
-- **4 user guides** in `_bmad-output/vortex-artifacts/`
+- **7 user guides** in `_bmad/bme/_vortex/guides/`
 
 ---
 

package/README.md

@@ -10,7 +10,7 @@
        E N H A N C E D
 </pre>
 
-**BMAD Method enhanced by domain-specialized agents**
+**Validate your product ideas before writing a single line of code**
 
 [![Version](https://img.shields.io/badge/version-1.6.4-blue)](https://github.com/amalik/BMAD-Enhanced)
 [![Agents](https://img.shields.io/badge/agents-7-brightgreen)](docs/agents.md)
@@ -19,38 +19,38 @@
 
 </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.
+Most teams skip validation and build on assumptions. BMAD-Enhanced guides you through seven discovery streams — from understanding your users to testing your riskiest assumptions — so you can make evidence-based decisions before committing to code. Each stream builds on the previous one's findings, and when gaps appear, the system routes you back to fill them.
 
 ```
-                    VORTEX PATTERN — 7 Streams · 7 Agents
-
-  ┌──────────┐  HC1  ┌──────────┐  HC2  ┌──────────┐  HC3  ┌──────────┐
-  │  Isla 🔍  │─────▶│  Mila 🔬  │─────▶│  Liam 💡  │─────▶│  Wade 🧪  │
-  │ Empathize│       │Synthesize│       │Hypothesiz│       │Externaliz│
-  └──────────┘       └──────────┘       └──────────┘       └──────────┘
-       ▲                  ▲                                       │
-       │                 HC6                                    HC4
-       │                  │                                       ▼
-  ┌──────────┐  HC8  ┌──────────┐  HC5  ┌──────────┐              │
-  │  Emma 🎯  │◀─────│  Max  🧭  │◀─────│  Noah 📡  │◀────────────┘
-  │Contextual│       │Systematiz│       │ Sensitize│
-  └──────────┘       └──────────┘       └──────────┘
-       │                  │                  │
-       └──────────────────┴──────────────────┘
-              HC7 · HC9 · HC10 ▶ Isla 🔍
+                         7 Streams · 7 Agents
+
+  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+  │   Isla 🔍    │──▶│   Mila 🔬    │──▶│   Liam 💡    │──▶│   Wade 🧪    │
+  │  Empathize  │   │ Synthesize  │   │ Hypothesize │   │ Externalize │
+  └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘
+         ▲                                                       │
+         │                                                       │
+         │                                                       ▼
+  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
+  │   Emma 🎯    │◀──│   Max  🧭    │◀──│   Noah 📡    │◀──────────┘
+  │Contextualize│   │ Systematize │   │  Sensitize  │
+  └─────────────┘   └─────────────┘   └─────────────┘
+         │                 │                 │
+         └─────────────────┴─────────────────┘
+          ▶ Start at Emma · back to any stream
 ```
 
+Each agent above runs one of these streams. You don't follow a fixed path — the system guides you to whichever stream needs attention based on what you've learned so far.
+
 | Agent | Stream | What they do |
 |-------|--------|-------------|
-| **Emma** 🎯 | Contextualize | Frame the right problem — lean personas, product vision, scope decisions |
+| **Emma** 🎯 | Contextualize | Frame the right problem — personas, product vision, scope |
 | **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.
+| **Mila** 🔬 | Synthesize | Converge research into clear problem definitions |
+| **Liam** 💡 | Hypothesize | Turn problems into testable hypotheses and experiments |
+| **Wade** 🧪 | Externalize | Test assumptions with MVPs, experiments, and prototypes |
+| **Noah** 📡 | Sensitize | Interpret production signals and user behavior |
+| **Max** 🧭 | Systematize | Capture learnings and decide: pivot, patch, or persevere |
 
 ---
 
@@ -92,7 +92,7 @@ your-project/
 ├── _bmad/bme/_vortex/
 │   ├── agents/           # 7 agent definition files
 │   ├── workflows/        # 22 workflows
-│   ├── contracts/        # 5 artifact contract schemas (HC1-HC5)
+│   ├── contracts/        # Artifact contract schemas
 │   ├── guides/           # User guides (all 7 agents)
 │   └── config.yaml       # Configuration
 └── _bmad-output/
@@ -119,6 +119,48 @@ Your data in `_bmad-output/` is never touched. Automatic backups are created bef
 
 See [UPDATE-GUIDE.md](UPDATE-GUIDE.md) for migration paths and troubleshooting.
 
+## What Agents Produce
+
+Here's a sample of real output from a busy parents meal planning project — each excerpt is from the [full 7-agent journey example](_bmad-output/journey-examples/busy-parents-7-agent-journey.md).
+
+### Emma 🎯 Contextualize
+
+Emma frames the right problem. Here's the Job-to-be-Done she produced:
+
+> **Job-to-be-Done:** Eliminate the daily 5:30 PM dinner decision so I can feed my family well without the mental load of planning, shopping, and deciding under time pressure.
+>
+> **Riskiest Assumptions:**
+> 1. Decision fatigue — not cooking skill or ingredient access — is the primary barrier to weeknight dinner success
+> 2. Parents would trust and act on an externally-provided dinner suggestion rather than needing to choose themselves
+> 3. "Good enough" nutrition is an acceptable standard — parents aren't seeking perfection, they're seeking relief from guilt
+
+### Liam 💡 Hypothesize
+
+Liam turns problems into testable ideas. Here's one of three hypotheses he produced:
+
+> **Hypothesis 1: The Pre-Commute Decision Eliminator**
+>
+> We believe that busy parents will act on a single dinner suggestion delivered at 4:00 PM within 3 minutes because the decision burden — not cooking — is their primary barrier, and an earlier intervention catches them before the anxiety spiral begins.
+>
+> **Riskiest Assumption:** Parents will trust and act on an automated suggestion without second-guessing. Research shows they want "someone to tell me what to make" — but "someone" may need to be a trusted person, not an algorithm.
+
+### Max 🧭 Systematize
+
+Max captures what you learned and decides what to do next:
+
+> **Recommendation: PATCH** (iterate on timing, don't pivot direction)
+>
+> The core hypothesis is validated. The product direction (decision elimination via single suggestion) is correct. The timing mechanism needs refinement — shift from fixed 4:00 PM delivery to adaptive delivery based on each user's observed engagement pattern.
+>
+> **Three Actions:**
+> 1. **Implement adaptive timing** — shift the push notification to match each user's observed engagement window. Engineering effort: 1-2 sprints.
+> 2. **Route to Isla for timing investigation** — qualitative research on why users engage at 3:15 PM. Is it anxiety relief, logistical planning, or habit?
+> 3. **Test willingness to pay immediately** — the mechanism works, but we have no commercial validation. Run a landing page test with pricing before further product investment.
+
+Want to see the complete walkthrough of all 7 agents applied to the example above?
+
+**📖 [See the full 7-agent journey example →](_bmad-output/journey-examples/busy-parents-7-agent-journey.md)**
+
 ---
 
 ## Using the Agents
@@ -133,7 +175,7 @@ Each agent can be used independently or as part of the full Vortex flow:
 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
 
-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.
+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. Ten handoff contracts (HC1-HC10) ensure structured information flows between agents, so each agent gets exactly the data it needs from the previous one.
 
 For detailed workflow descriptions and usage examples, see the [Agent Guide](docs/agents.md) and the individual user guides:
 
@@ -181,8 +223,8 @@ BMAD-Enhanced works standalone or as an extension — no BMAD Method installatio
 
 ## Roadmap
 
-- **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)
+- **v1.1.0–v1.5.x** — Waves 1-2: Foundation (Emma, Isla, Wade, Max — agent definitions, workflows, update system, CI/CD)
+- **v1.6.x** — Wave 3: Complete 7-stream Vortex (added Mila, Liam, Noah — 7 agents, 22 workflows, handoff contracts, Compass routing)
 - **v2.0.0+** — Multi-agent collaboration, cross-agent workflows, analytics
 
 ---
@@ -196,6 +238,8 @@ We welcome contributions in these areas:
 - **Documentation** — Tutorials, translations, video walkthroughs
 - **Integration** — IDE plugins, third-party tools
 
+**Have feedback?** Found a quality issue, want a missing capability, or have a general comment about an agent? Open an issue and select the **Agent/Workflow Feedback** template — takes under 30 seconds.
+
 See the [Development Guide](docs/development.md) for architecture details and agent development patterns.
 
 ---
@@ -257,7 +301,7 @@ Every agent below contributed to the design, implementation, testing, or documen
 
 <div align="center">
 
-**Vortex Pattern** — *Validate before you build*
+**Innovation Vortex Pattern** — *Discover what has to be discovered, deliver what has to be delivered*
 
 [Get Started](#quick-start) | [Agents](docs/agents.md) | [Docs](#documentation) | [Roadmap](#roadmap)
 

package/UPDATE-GUIDE.md

@@ -78,7 +78,7 @@ What happens:
 - Agent files and workflows refreshed
 - Isla + Max agents added with 6 new workflows
 
-### From v1.0.x to v1.5.x
+### From v1.0.x to v1.6.x
 
 **Breaking changes:**
 - Workflow renamed: `empathy-map` → `lean-persona` (for Emma)
@@ -87,9 +87,9 @@ What happens:
 
 What happens:
 - Old workflows preserved in `_bmad/bme/_vortex/workflows/_deprecated/`
-- All 13 Vortex workflows installed
+- All 22 Vortex workflows installed
 - Config structure updated (preferences preserved)
-- 4 agents installed (Emma, Isla, Wade, Max)
+- 7 agents installed (Emma, Isla, Mila, Liam, Wade, Noah, Max)
 
 ```bash
 npm install bmad-enhanced@latest
@@ -125,6 +125,33 @@ Every update creates a backup before making changes:
 
 ---
 
+## 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 bmad-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"