bmad-enhanced 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.5.1] - 2026-02-20
+
+### Added
+
+- **Vortex Compass** — Evidence-driven cross-stream navigation in every workflow's final step
+  - Conditional "If you learned X → go to Y" tables replace fixed "Next suggested workflow" links
+  - Each compass points to workflows across different agents, creating true vortex loops
+  - All 12 workflow endpoints now interconnect (vortex-navigation excluded — it IS the navigator)
+  - Always includes Max's Vortex Navigation as escape hatch for full gap analysis
+
+---
+
 ## [1.5.0] - 2026-02-20
 
 ### Added

package/README.md

@@ -4,8 +4,8 @@
 
 > Four specialized agents: Emma, Wade, Isla, and Max
 
-[![Status](https://img.shields.io/badge/status-v1.5.0--stable-success)]()
-[![Version](https://img.shields.io/badge/version-1.5.0-blue)]()
+[![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)]()
@@ -434,7 +434,7 @@ v1.1.0             v1.3.x ✅        v1.4.x ✅        v1.5.0 ✅          v2.0.
 ├────────────────┬────────────────┬────────────────┬────────────────┬──────────┤
 │ Foundation ✅   │ Tooling ✅      │ Quality ✅      │ Wave 2 ✅       │ Advanced │
 │ • Emma + Wade  │ • Update tools │ • Refactor     │ • Isla + Max   │ • Wave 3 │
-│ • 7 workflows  │ • Migration    │ • 120 tests    │ • 13 workflows │ • Multi  │
+│ • 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
@@ -486,6 +486,7 @@ The Vortex framework brings structured validation to product development:
 - **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
 
@@ -565,16 +566,20 @@ Zero-dependency test runner (`node:test`)
 
 | Suite | Tests | Coverage |
 |-------|-------|----------|
-| utils | ~15 | compareVersions, getPackageVersion, findProjectRoot |
-| registry | ~15 | getMigrationsFor, getBreakingChanges, hasMigrationBeenApplied |
-| version-detector | ~20 | getCurrentVersion, detectInstallationScenario |
-| config-merger | ~15 | mergeConfig, validateConfig, addMigrationHistory |
-| backup-manager | 10 | createBackup, restoreBackup, cleanupOldBackups |
+| 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-1.x-to-1.5.0 | 6 | 1.3.x and 1.4.x migration metadata, preview, apply |
-| fresh-install (integration) | ~10 | refreshInstallation end-to-end (all 4 agents) |
-| upgrade (integration) | ~20 | v1.0.x→1.5.0, v1.3.x→1.5.0, v1.4.x→1.5.0 upgrade paths |
-| cli-entry-points (integration) | 10 | index.js, bmad-version, bmad-update, bmad-doctor |
+| 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):**
 
@@ -678,7 +683,7 @@ Max follows the same agent architecture as Emma and Wade. Infrastructure validat
 - ✅ **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 (120 tests, CI/CD, ESLint, bmad-doctor, publish-on-tag)
+- ✅ **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
 
 ### Future (v1.6.0 / v2.0.0+)
@@ -882,7 +887,7 @@ We welcome contributions! Areas where we need help:
 **Quality:**
 - 100% P0 test pass rate for all agents
 - All quality gates passed before release
-- 120+ automated tests across unit and integration suites
+- 180+ automated tests across unit and integration suites
 
 ---
 

package/_bmad/bme/_vortex/config.yaml

@@ -2,7 +2,7 @@
 submodule_name: _vortex
 description: Vortex Framework - Contextualize, Empathize, Externalize, and Systematize streams
 module: bme
-version: 1.5.0
+version: 1.5.2
 
 # Output Configuration
 output_folder: "{project-root}/_bmad-output/vortex-artifacts"

package/_bmad/bme/_vortex/workflows/contextualize-scope/steps/step-06-synthesize.md

@@ -20,11 +20,14 @@ Provide final decision summary:
 
 ## Workflow Complete
 
-Next suggested workflows:
-- **lean-persona** to understand your target user
-- **Wade's mvp** to design your minimum viable product
-- **Wade's lean-experiment** to validate assumptions
+## Vortex Compass
 
----
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Scope is defined, users unknown | lean-persona | Emma 🎯 | Understand who exists in this problem space |
+| Scope chosen, need user validation | user-interview | Isla 🔍 | Confirm real users care about this scope |
+| Ready to test assumptions | mvp | Wade 🧪 | Design the smallest test for your scope decision |
 
-**Created with:** BMAD-Enhanced v1.2.0
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/empathy-map/steps/step-06-synthesize.md

@@ -91,14 +91,14 @@ Once you confirm, I'll create:
 
 ---
 
-## What's Next?
+## Vortex Compass
 
-After creating this empathy map, you might:
+Based on what you just completed, here are your evidence-driven options:
 
-1. **Validate with users** - Show the empathy map to actual users and ask if it resonates
-2. **Share with team** - Get stakeholder alignment on user needs
-3. **Create wireframes** - Use insights to inform design decisions (invoke Wade!)
-4. **Prioritize features** - Focus on gains that address the biggest pain points
-5. **Define success metrics** - Use gain metrics to track if solutions work
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Pain points need validation | lean-experiment | Wade 🧪 | Test if pain points drive real behavior |
+| New user segment discovered | lean-persona | Emma 🎯 | Re-contextualize for the new segment |
+| Deeper understanding needed | user-interview | Isla 🔍 | Follow up with targeted interviews |
 
-Great work! This empathy map will be a valuable tool for user-centered decision making. 🎨
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-06.md

@@ -6,3 +6,17 @@ workflow: lean-experiment
 # Step 6
 
 [Content for step 6]
+
+---
+
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Experiment complete | learning-card | Max 🧭 | Capture validated learning before it fades |
+| Results challenge assumptions | contextualize-scope | Emma 🎯 | Re-evaluate your problem space framing |
+| User behavior surprising | empathy-map | Isla 🔍 | Understand why users behaved unexpectedly |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/lean-persona/steps/step-06-synthesize.md

@@ -113,4 +113,14 @@ After synthesis, your lean persona artifact will include:
 - Validation experiments ready to run
 - Revision history to track what you learn
 
-Next suggested workflow: **Wade's lean-experiment** to run your validation experiments.
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Riskiest assumptions identified | lean-experiment | Wade 🧪 | Test your riskiest assumption with real users |
+| User needs unclear | user-interview | Isla 🔍 | Validate persona assumptions with actual users |
+| Multiple user segments | empathy-map | Isla 🔍 | Build deeper understanding of each segment |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/learning-card/steps/step-06-synthesize.md

@@ -105,4 +105,14 @@ After synthesis, your learning card artifact will include:
 - Links to related learnings and discoverability tags
 - Revision history for future updates as you learn more
 
-Next suggested workflow: **Max's pivot-patch-persevere** if this learning triggers a strategic decision, or **Wade's lean-experiment** to run follow-up experiments.
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Learning triggers strategic decision | pivot-patch-persevere | Max 🧭 | Decide: pivot, patch, or persevere |
+| Need more data | lean-experiment | Wade 🧪 | Run follow-up experiments |
+| Assumptions invalidated | contextualize-scope | Emma 🎯 | Re-frame the problem based on evidence |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/mvp/steps/step-06-synthesize.md

@@ -10,4 +10,16 @@ Create your final MVP specification.
 
 ## Workflow Complete
 
-Next: Use lean-experiment workflow to run your Build-Measure-Learn cycle.
+---
+
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| MVP designed, ready to run | lean-experiment | Wade 🧪 | Execute the Build-Measure-Learn cycle |
+| Unsure about user needs | user-interview | Isla 🔍 | Validate user need before building |
+| MVP results available | learning-card | Max 🧭 | Capture what you learned from the MVP |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/steps/step-06-action-plan.md

@@ -172,4 +172,14 @@ After creating the action plan, your PPP decision artifact will include:
 - Concrete action plan with owners, timelines, and success metrics
 - Risk mitigation strategies
 
-Next suggested workflow: **Wade's lean-experiment** to design and run the next experiment, or **Max's learning-card** to capture results when the next experiment completes.
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Pivoting — new direction | contextualize-scope | Emma 🎯 | Re-contextualize for the pivot |
+| Patching — adjust approach | lean-experiment | Wade 🧪 | Test the adjusted approach |
+| Persevering — need deeper insight | user-discovery | Isla 🔍 | Strengthen your understanding of users |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/product-vision/steps/step-06-synthesize.md

@@ -153,3 +153,15 @@ After synthesis, your product vision document will include:
 - Team alignment status
 
 This becomes your strategic foundation for all product decisions.
+
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Vision is clear, users are not | lean-persona | Emma 🎯 | Define who you're building for |
+| Strategic assumptions need testing | lean-experiment | Wade 🧪 | Validate your biggest strategic bet |
+| User needs are assumed, not researched | user-discovery | Isla 🔍 | Ground your vision in real user evidence |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/proof-of-concept/steps/step-06.md

@@ -6,3 +6,17 @@ workflow: proof-of-concept
 # Step 6
 
 [PoC step 6 content]
+
+---
+
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Technically feasible | proof-of-value | Wade 🧪 | Now validate the business case |
+| Feasibility uncertain | lean-experiment | Wade 🧪 | Run a focused technical experiment |
+| Results available | learning-card | Max 🧭 | Document technical learnings |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/proof-of-value/steps/step-06.md

@@ -6,3 +6,17 @@ workflow: proof-of-value
 # Step 6
 
 [PoV step 6 content]
+
+---
+
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Business value validated | learning-card | Max 🧭 | Capture the evidence for stakeholders |
+| Value unclear, need user data | user-interview | Isla 🔍 | Understand willingness to pay |
+| Pivot needed | pivot-patch-persevere | Max 🧭 | Make a structured pivot decision |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-06-synthesize.md

@@ -143,12 +143,14 @@ Once you confirm, I'll create:
 
 ---
 
-## What's Next?
+## Vortex Compass
 
-After completing this discovery report, you might:
+Based on what you just completed, here are your evidence-driven options:
 
-1. **Create empathy maps** for key user segments discovered (use the empathy-map workflow)
-2. **Design experiments** to test opportunity area hypotheses (invoke Wade for lean experiments)
-3. **Update personas** based on new understanding
-4. **Present to stakeholders** to align on priorities
-5. **Plan the next research cycle** to address gaps identified in this round
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Problem space needs reframing | contextualize-scope | Emma 🎯 | Re-scope based on discovery findings |
+| Ready to test hypotheses | lean-experiment | Wade 🧪 | Design experiments from discovery insights |
+| Need deeper empathy for key users | empathy-map | Isla 🔍 | Map the users you discovered in depth |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/user-interview/steps/step-06-synthesize.md

@@ -153,6 +153,16 @@ Your artifact will include:
 - Recommendations and next actions
 - Research quality assessment
 
-**Next suggested workflows:**
-- **Emma's lean-persona** to build personas from your interview insights
-- **Wade's lean-experiment** to test your riskiest insights with experiments
+---
+
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Insights suggest different problem | contextualize-scope | Emma 🎯 | Re-scope based on what users actually said |
+| Riskiest insights identified | lean-experiment | Wade 🧪 | Test your riskiest insight with an experiment |
+| Want to synthesize across users | empathy-map | Isla 🔍 | Map patterns across all interview subjects |
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-enhanced",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Vortex Framework - Contextualize, Empathize, Externalize, and Systematize streams for Lean Startup validation",
   "main": "index.js",
   "files": [

package/scripts/install-vortex-agents.js

@@ -174,7 +174,6 @@ function printSuccess() {
 async function main() {
   try {
     // Use findProjectRoot for existing projects, fall back to cwd for fresh installs
-    // eslint-disable-next-line no-restricted-syntax -- fresh install has no _bmad/ dir to detect
     const projectRoot = findProjectRoot() || process.cwd();
 
     printBanner();

package/scripts/update/lib/config-merger.js

@@ -32,8 +32,16 @@ async function mergeConfig(currentConfigPath, newVersion, updates = {}) {
   // Extract user preferences
   const userPrefs = extractUserPreferences(current);
 
-  // Start with current config
-  const merged = { ...current };
+  // Seed with required structural defaults for fresh installs
+  const defaults = {
+    submodule_name: '_vortex',
+    description: 'Vortex Framework - Contextualize, Empathize, Externalize, and Systematize streams',
+    module: 'bme',
+    output_folder: '{project-root}/_bmad-output/vortex-artifacts'
+  };
+
+  // Start with defaults, overlay current config (preserves existing values)
+  const merged = { ...defaults, ...current };
 
   // Update version (system field)
   merged.version = newVersion;

package/scripts/update/lib/validator.js

@@ -103,7 +103,9 @@ async function validateAgentFiles(projectRoot) {
     const agentsDir = path.join(projectRoot, '_bmad/bme/_vortex/agents');
     const requiredAgents = [
       'contextualization-expert.md',
-      'lean-experiments-specialist.md'
+      'lean-experiments-specialist.md',
+      'discovery-empathy-expert.md',
+      'learning-decision-expert.md'
     ];
 
     if (!fs.existsSync(agentsDir)) {