bmad-enhanced 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -7,10 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.6.0] - 2026-02-26
+
+### Added
+
+- **Mila — Research Convergence Specialist** (Stream 3: Synthesize) — New agent that converges divergent research into actionable problem definitions using JTBD framing and Pains & Gains analysis
+  - `research-convergence` workflow — Synthesize multiple research artifacts into a single problem definition
+  - `pivot-resynthesis` workflow — Re-synthesize problem definition after failed experiments
+  - `pattern-mapping` workflow — Surface convergent patterns across research sources
+- **Liam — Hypothesis Engineer** (Stream 4: Hypothesize) — New agent that engineers testable hypotheses from validated problem definitions using structured brainwriting and assumption mapping
+  - `hypothesis-engineering` workflow — Produce testable hypotheses in 4-field contract format
+  - `assumption-mapping` workflow — Classify hidden assumptions by risk level
+  - `experiment-design` workflow — Design experiments targeting riskiest assumptions first
+- **Noah — Production Intelligence Specialist** (Stream 6: Sensitize) — New agent that interprets production signals through experiment lineage context
+  - `signal-interpretation` workflow — Contextual interpretation of production signals
+  - `behavior-analysis` workflow — Behavioral pattern analysis against experiment baselines
+  - `production-monitoring` workflow — Multi-signal monitoring across active experiments
+- **10 Handoff Contracts (HC1-HC10)** — Structured information flow between all 7 agents
+  - HC1-HC5: Artifact contracts with schema definitions in `_bmad/bme/_vortex/contracts/`
+  - HC6-HC8: Decision-driven routing contracts (Max → Mila/Isla/Emma)
+  - HC9-HC10: Flag-driven routing contracts (Liam → Isla, Noah → Isla)
+- **Compass Routing** — Every workflow's final step includes evidence-driven routing table with agent recommendations
+- **Compass Routing Reference** — Authoritative routing document (`_bmad/bme/_vortex/compass-routing-reference.md`) defining all routes across 22 workflows
+- **Cross-agent routing for existing agents** — Emma, Isla, Wade, and Max now route to Mila, Liam, and Noah where appropriate
+- **Module README** — Technical inventory at `_bmad/bme/_vortex/README.md` with complete agent, workflow, and contract listings
+- **Extensibility documentation** — 4-step pattern for adding new agents (registry → agent file → workflows → guide) validates NFR9/E4
+
+### Changed
+
+- **README.md** — Updated from 4-agent to 7-agent framework with non-linear Vortex diagram, 10 HC contracts, and Compass routing
+- **docs/agents.md** — Expanded from 4-agent reference to comprehensive 7-agent practitioner guide with user journeys, handoff contracts, and Compass documentation
+- **Agent registry** — Now contains 7 agents and 22 workflows (was 4 agents, 13 workflows)
+- **Roadmap** — v1.6.0 marked as current release; Wave 3 complete
+
+---
+
+## [1.5.2] - 2026-02-22
+
+### Changed
+
+- **Registry-driven postinstall** — `postinstall.js` now imports from `agent-registry.js` instead of hardcoding agent names; agent list stays current automatically
+- **Removed deprecated installer wrappers** — Deleted `install-emma.js` and `install-wade.js`; removed `bmad-install-emma` / `bmad-install-wade` bin entries and `install:emma` / `install:wade` scripts
+- **Manifest persona data moved to registry** — `createAgentManifest()` now reads role, identity, communication_style, and expertise from `agent-registry.js` instead of hardcoded CSV strings
+- **Formalized config schema** — `validateConfig()` rewritten to iterate a declarative `CONFIG_SCHEMA`; added type checks for `submodule_name`, `module`, `output_folder`, `communication_language`, `party_mode_enabled`, and array-item types for `agents`/`workflows`
+
+### Fixed
+
+- CHANGELOG.md backfilled with missing v1.4.0, v1.4.1, and v1.5.1 entries
+
+---
+
 ## [1.5.1] - 2026-02-20
 
 ### Added
 
+- **Test hardening** — 184 tests (130 unit + 54 integration), all green
+- Line coverage raised to 83.4% (up from 68%)
+- `validator.js` coverage: 96% (was 21%)
+- `migration-runner.js` coverage: 81% (was 28%)
+- Installer E2E test (CLI as child process)
+- `bmad-doctor` negative-path tests (8 scenarios)
+
+### Fixed
+
+- Validator now checks all 4 agents (was only 2)
+- `mergeConfig` seeds structural defaults for fresh installs so config and validation stay consistent
+
+### 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
@@ -45,6 +109,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.4.1] - 2026-02-19
+
+### Added
+
+- CI pipeline with GitHub Actions (lint + test on Node 18/20/22)
+- ESLint configuration and full lint pass
+- `bmad-doctor` diagnostic CLI with 7 installation checks
+- 112 tests (82 unit + 30 integration)
+- `.c8rc.json` for coverage configuration
+
+### Fixed
+
+- Silenced console in tests that trigger heavy source-code logging (Node 20 IPC bug)
+
+---
+
+## [1.4.0] - 2026-02-18
+
+### Changed
+
+- **Architecture refactor** — Centralized agent/workflow data into `agent-registry.js`
+  - Single source of truth consumed by validator, refresh-installation, bmad-doctor, migration-runner, and index.js
+  - To add a new agent: push one entry to `AGENTS` + its workflows to `WORKFLOWS`; all consumers pick up the change automatically
+- **`refresh-installation.js`** — Shared refresh logic extracted; copies agents, workflows, config, and user guides from package to project
+- **`migration-runner.js`** — Rewritten as 8-step orchestration (deltas → refresh → validate) with lock file, backup, and rollback
+- **`validator.js`** — Data-driven validation using registry arrays instead of hardcoded checks
+- **`config-merger.js`** — Seeds structural defaults (`submodule_name`, `description`, `module`, `output_folder`) so fresh installs pass validation
+
+### Removed
+
+- Hardcoded agent/workflow arrays throughout codebase (replaced by registry imports)
+
+---
+
 ## [1.3.6] - 2026-02-18
 
 ### Fixed
@@ -127,7 +225,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 **🚨 CRITICAL Package Bug:**
-- Fixed `.npmignore` excluding Vortex framework files from published package
+- Fixed `.npmignore` excluding Vortex pattern files from published package
 - Agent files (`contextualization-expert.md`, `lean-experiments-specialist.md`) now included in package
 - All workflow template files now included in package
 - `CHANGELOG.md` and `UPDATE-GUIDE.md` now included in package
@@ -355,9 +453,9 @@ npx bmad-update
 
 ## [1.2.0] - 2026-02-17
 
-### Major Release: Complete Vortex Framework Implementation
+### Major Release: Complete Vortex Pattern Implementation
 
-This release completes the Vortex Framework by implementing all 7 new Lean Startup workflows, updating documentation, and cleaning up deprecated workflows.
+This release completes the Vortex Pattern by implementing all 7 new Lean Startup workflows, updating documentation, and cleaning up deprecated workflows.
 
 ### Added
 
@@ -485,7 +583,7 @@ This release completes the Vortex Framework by implementing all 7 new Lean Start
 
 ## [1.1.0] - 2026-02-16
 
-### MAJOR REPOSITIONING: From Design Agents to Vortex Framework
+### MAJOR REPOSITIONING: From Design Agents to Vortex Pattern
 
 This release represents a fundamental repositioning of BMAD-Enhanced from design-focused agents (empathy mapping, wireframing) to a Lean Startup validation framework.
 
@@ -501,11 +599,11 @@ This release represents a fundamental repositioning of BMAD-Enhanced from design
   - New workflows: mvp, lean-experiment, proof-of-concept, proof-of-value (wireframe deprecated)
 - **BREAKING:** Output folder changed from `_bmad-output/design-artifacts` to `_bmad-output/vortex-artifacts`
 - Updated all installer scripts to reflect new module name and agent descriptions
-- Updated config.yaml structure to version 1.1.0 with Vortex framework metadata
+- Updated config.yaml structure to version 1.1.0 with Vortex pattern metadata
 - Updated agent-manifest.csv with new agent identities and expertise
 
 ### Added
-- Vortex framework structure with Contextualize and Externalize streams
+- Vortex pattern structure with Contextualize and Externalize streams
 - 7 new workflow placeholders (v1.2.0):
   - Emma (Contextualize): lean-persona, product-vision, contextualize-scope
   - Wade (Externalize): mvp, lean-experiment, proof-of-concept, proof-of-value

package/INSTALLATION.md

@@ -1,124 +1,52 @@
-# BMAD-Enhanced Installation Guide
+# Installation Guide
 
-Complete guide to installing BMAD-Enhanced agents into your project.
+Complete guide to installing BMAD-Enhanced Vortex agents into your project.
 
 ---
 
-## ⚠️ Prerequisites
+## Prerequisites
 
-**BMAD Method Required**
+- Node.js 18+ or Bun
+- Git
+- Claude Code or Claude.ai
 
-BMAD-Enhanced is an **extension package** for the [BMAD Method](https://github.com/bmadhub/bmad). You **must** install BMAD Method first.
-
-### Step 1: Install BMAD Method
-
-```bash
-# Install BMAD Method using npx
-npx bmad-method@alpha install
-
-# Verify BMAD is installed
-ls _bmad/  # Should show BMAD directory structure
-```
-
-### Step 2: Install BMAD-Enhanced Agents
-
-Once BMAD Method is installed, proceed with BMAD-Enhanced installation below.
+BMAD-Enhanced works **standalone** or as an extension to [BMAD Method](https://github.com/bmadhub/bmad). No prior BMAD installation required.
 
 ---
 
 ## Quick Install
 
-**Install all agents at once:**
-
 ```bash
-# From your project directory (where BMAD Method is installed)
-npm install bmad-enhanced@alpha
-npx bmad-install-agents
+npm install bmad-enhanced && npx bmad-install-vortex-agents
 ```
 
-That's it! Emma and Wade are now added to your BMAD installation.
+All 4 Vortex agents (Emma, Isla, Wade, Max) with 13 workflows are installed and ready to use.
 
 ---
 
 ## Installation Options
 
-### Option 1: Install All Agents (Recommended)
-
-Install both Emma (empathy-mapper) and Wade (wireframe-designer) at once.
+### Option 1: Install from npm (Recommended)
 
 ```bash
-npm install bmad-enhanced@alpha
-npx bmad-install-agents
-```
+# Install into your project
+npm install bmad-enhanced
 
-**Output:**
+# Install all Vortex agents and workflows
+npx bmad-install-vortex-agents
 ```
-╔════════════════════════════════════════════════════╗
-║                                                    ║
-║        BMAD-Enhanced Complete Installer 🚀        ║
-║                                                    ║
-║     Installing Emma + Wade Design Agents          ║
-║                                                    ║
-╚════════════════════════════════════════════════════╝
-
-[1/5] Checking prerequisites...
-  ✓ Prerequisites met
-[2/5] Installing Emma + Wade agent files...
-  → Installing Emma (empathy-mapper)...
-  ✓ Emma installed
-  → Installing Wade (wireframe-designer)...
-  ✓ Wade installed
-[3/5] Configuring agents...
-  ✓ Created config.yaml
-  ✓ Created agent-manifest.csv
-[4/5] Setting up output directory...
-  ✓ Output directory ready
-[5/5] Installing user guides...
-  ✓ User guides installed
-
-╔════════════════════════════════════════════════════╗
-║                                                    ║
-║    ✓  All Agents Successfully Installed! 🎉       ║
-║                                                    ║
-╚════════════════════════════════════════════════════╝
-
-Installed Agents:
-
-  ✓ Emma (empathy-mapper) - Empathy Mapping Specialist 🎨
-  ✓ Wade (wireframe-designer) - Wireframe Design Expert 🎨
-```
-
----
 
-### Option 2: Install Individual Agents
+### Option 2: Clone from Source (Contributors Only)
 
-Install Emma or Wade separately.
+For contributors or developers who want to modify agents or contribute to the project. This sets up a development environment — not an end-user installation.
 
-**Install Emma only:**
 ```bash
-npm install bmad-enhanced@alpha
-npx bmad-install-emma
-```
-
-**Install Wade only:**
-```bash
-npm install bmad-enhanced@alpha
-npx bmad-install-wade
-```
-
----
-
-### Option 3: Clone from Source
-
-For contributors or advanced users who want to modify agents.
-
-```bash
-git clone https://github.com/yourusername/BMAD-Enhanced.git
+git clone https://github.com/amalik/BMAD-Enhanced.git
 cd BMAD-Enhanced
 npm install
 ```
 
-Agents are already installed in the repository. No additional steps needed.
+Agents are pre-installed in the repository for development. Note that this does not create the same output directory structure as the npm install path — use Option 1 for project installations.
 
 ---
 
@@ -130,238 +58,158 @@ Agents are already installed in the repository. No additional steps needed.
 your-project/
 ├── _bmad/
 │   ├── bme/
-│   │   └── _designos/
+│   │   └── _vortex/
 │   │       ├── agents/
-│   │       │   ├── empathy-mapper.md          # Emma agent definition
-│   │       │   └── wireframe-designer.md       # Wade agent definition
+│   │       │   ├── contextualization-expert.md      # Emma
+│   │       │   ├── discovery-empathy-expert.md       # Isla
+│   │       │   ├── lean-experiments-specialist.md    # Wade
+│   │       │   └── learning-decision-expert.md       # Max
 │   │       ├── workflows/
-│   │       │   ├── empathy-map/
-│   │       │   │   ├── workflow.md             # Main empathy map workflow
-│   │       │   │   ├── empathy-map.template.md # Output template
-│   │       │   │   └── steps/
-│   │       │   │       ├── step-01-define-user.md
-│   │       │   │       ├── step-02-says-thinks.md
-│   │       │   │       ├── step-03-does-feels.md
-│   │       │   │       ├── step-04-pain-points.md
-│   │       │   │       ├── step-05-gains.md
-│   │       │   │       └── step-06-synthesize.md
-│   │       │   └── wireframe/
-│   │       │       ├── workflow.md             # Main wireframe workflow
-│   │       │       ├── wireframe.template.md   # Output template
-│   │       │       └── steps/
-│   │       │           ├── step-01-define-requirements.md
-│   │       │           ├── step-02-user-flows.md
-│   │       │           ├── step-03-information-architecture.md
-│   │       │           ├── step-04-wireframe-sketch.md
-│   │       │           ├── step-05-components-interactions.md
-│   │       │           └── step-06-synthesize.md
-│   │       └── config.yaml                     # Agent configuration
+│   │       │   ├── lean-persona/                     # Emma workflows
+│   │       │   ├── product-vision/
+│   │       │   ├── contextualize-scope/
+│   │       │   ├── empathy-map/                      # Isla workflows
+│   │       │   ├── user-interview/
+│   │       │   ├── user-discovery/
+│   │       │   ├── mvp/                              # Wade workflows
+│   │       │   ├── lean-experiment/
+│   │       │   ├── proof-of-concept/
+│   │       │   ├── proof-of-value/
+│   │       │   ├── learning-card/                    # Max workflows
+│   │       │   ├── pivot-patch-persevere/
+│   │       │   └── vortex-navigation/
+│   │       └── config.yaml
 │   └── _config/
-│       └── agent-manifest.csv                  # Agent registry
+│       └── agent-manifest.csv
 └── _bmad-output/
-    └── design-artifacts/
-        ├── EMMA-USER-GUIDE.md                  # Complete Emma documentation
-        ├── WADE-USER-GUIDE.md                  # Complete Wade documentation
-        └── (your generated artifacts)           # Empathy maps, wireframes, etc.
+    └── vortex-artifacts/
+        ├── EMMA-USER-GUIDE.md
+        ├── ISLA-USER-GUIDE.md
+        ├── WADE-USER-GUIDE.md
+        ├── MAX-USER-GUIDE.md
+        └── (your generated artifacts)
 ```
 
-### File Sizes
+### Summary
 
-- **Emma Agent Files:** ~45KB (agent + 6 workflow steps + template)
-- **Wade Agent Files:** ~52KB (agent + 6 workflow steps + template)
-- **Emma User Guide:** 16KB
-- **Wade User Guide:** 16KB
-- **Total:** ~129KB
+- **4 agent definitions** in `_bmad/bme/_vortex/agents/`
+- **13 workflows** (104 files) — each with steps, templates, and validation
+- **Configuration** in `_bmad/bme/_vortex/config.yaml`
+- **4 user guides** in `_bmad-output/vortex-artifacts/`
 
 ---
 
 ## Configuration
 
-### config.yaml
-
-Default configuration created during installation:
+The installer creates `_bmad/bme/_vortex/config.yaml`. The key fields you'll want to customize:
 
 ```yaml
-# BMAD _designos Configuration
-# Used by: Emma (empathy-mapper), Wade (wireframe-designer)
-
-user_name: "User"
-communication_language: "English"
-output_folder: "_bmad-output/design-artifacts"
-
-agents:
-  - empathy-mapper     # Emma - Empathy Mapping Specialist
-  - wireframe-designer # Wade - Wireframe Specialist
-
-workflows:
-  - empathy-map        # Create empathy maps
-  - wireframe          # Create wireframes
+# User-facing settings
+user_name: "{user}"                # Your name (used in agent greetings)
+communication_language: "en"       # Language for agent communication
+output_folder: "{project-root}/_bmad-output/vortex-artifacts"  # Where artifacts are saved
 ```
 
-**Customization:**
-- `user_name`: Your name (used in agent greetings)
-- `communication_language`: Language for agent communication
-- `output_folder`: Where artifacts are saved
+The config also includes auto-generated fields (`submodule_name`, `module`, `version`, `agents`, `workflows`) that you typically don't need to edit — the installer and update system manage those.
 
 ---
 
 ## Verification
 
-After installation, verify agents are working:
-
-### Test Emma
+After installation, verify agents are working by activating one:
 
 ```bash
-cat _bmad/bme/_designos/agents/empathy-mapper.md
+cat _bmad/bme/_vortex/agents/contextualization-expert.md    # Emma
 ```
 
-**Expected output:**
-```
-Hey there! Emma here - your empathy mapping specialist. 🎨
+**Expected result:** Emma should greet you by name and display a numbered menu like this:
 
-I help teams build deep understanding of users through structured empathy mapping...
-
-Here's what I can do for you:
+```
+Hey Amalik! I'm Emma — your Contextualization Expert...
 
 1. [MH] Redisplay Menu Help
-2. [CH] Chat with Emma about empathy mapping, user research, or Jobs-to-be-Done
-3. [EM] Create Empathy Map: Guided 5-step process to create comprehensive empathy maps
-4. [VM] Validate Empathy Map: Review existing empathy map against research best practices
-5. [PM] Start Party Mode
-6. [DA] Dismiss Agent
-
-What would you like to do?
+2. [CH] Chat with Emma
+3. [LP] Lean Persona
+4. [PV] Product Vision
+5. [CS] Contextualize Scope
+...
 ```
 
-### Test Wade
+If the agent doesn't activate or you see raw markdown instead, run diagnostics:
 
 ```bash
-cat _bmad/bme/_designos/agents/wireframe-designer.md
+npx bmad-doctor
 ```
 
-**Expected output:**
-```
-Hey there! Wade here - your wireframe design specialist. 🎨
-
-Ready to turn ideas into structured layouts? I'll help you create wireframes...
-
-Here's what I can do for you:
-
-1. [MH] Redisplay Menu Help
-2. [CH] Chat with Wade about wireframe design, UI patterns, or information architecture
-3. [WM] Create Wireframe: Guided 6-step process to create comprehensive wireframe artifacts
-4. [VM] Validate Wireframe: Review existing wireframe against usability principles
-5. [PM] Start Party Mode
-6. [DA] Dismiss Agent
-
-What would you like to do?
-```
+This checks project root, config validity, agent files, workflows, output directory, and version consistency — with actionable fix suggestions for each issue.
 
 ---
 
 ## Troubleshooting
 
-### Installation fails with "Cannot find module 'fs-extra'"
+Start with diagnostics — it catches most issues:
 
-**Solution:**
 ```bash
-npm install fs-extra chalk
-npx bmad-install-agents
+npx bmad-doctor
 ```
 
 ### Permission denied errors
 
-**Solution:**
 ```bash
 chmod +x scripts/*.js
-npx bmad-install-agents
+npx bmad-install-vortex-agents
 ```
 
 ### Config file already exists
 
-The installers are smart - they will:
-- Update existing config files (not overwrite)
-- Add missing agents to existing configuration
-- Preserve your custom settings
+The installer preserves your custom settings and only adds missing entries. To force a clean installation:
 
-To force a clean installation:
 ```bash
-rm -rf _bmad/bme/_designos/
-npx bmad-install-agents
+rm -rf _bmad/bme/_vortex/
+npx bmad-install-vortex-agents
 ```
 
 ### Installation succeeds but agents don't activate
 
-**Check file paths:**
-```bash
-# Should list agent files
-ls -la _bmad/bme/_designos/agents/
-
-# Should list workflow files
-ls -la _bmad/bme/_designos/workflows/empathy-map/
-ls -la _bmad/bme/_designos/workflows/wireframe/
-```
+Check that files are in place:
 
-**Check config:**
 ```bash
-cat _bmad/bme/_designos/config.yaml
+ls -la _bmad/bme/_vortex/agents/
+ls -la _bmad/bme/_vortex/workflows/
+npx bmad-doctor
 ```
 
 ---
 
 ## Next Steps
 
-After successful installation:
-
-1. **Read User Guides**
-   - Emma: `_bmad-output/design-artifacts/EMMA-USER-GUIDE.md`
-   - Wade: `_bmad-output/design-artifacts/WADE-USER-GUIDE.md`
-
-2. **Create Your First Empathy Map**
-   ```bash
-   cat _bmad/bme/_designos/agents/empathy-mapper.md
-   # Then type: EM
-   ```
+1. **Read the user guides** in `_bmad-output/vortex-artifacts/`
+2. **Activate an agent** — start with Emma for strategic framing or Isla for user research
+3. **Follow a workflow** — each agent presents a menu of guided workflows
+4. **Check updates** — run `npx bmad-version` periodically
 
-3. **Create Your First Wireframe**
-   ```bash
-   cat _bmad/bme/_designos/agents/wireframe-designer.md
-   # Then type: WM
-   ```
-
-4. **Explore Advanced Features**
-   - Party Mode: Collaborate with multiple agents
-   - Validation workflows: Review and improve artifacts
-   - Custom templates: Modify output templates for your needs
+See the [Agent Guide](docs/agents.md) for detailed workflow descriptions and the recommended Vortex flow.
 
 ---
 
 ## Uninstallation
 
-To remove BMAD-Enhanced agents:
+Back up any artifacts you want to keep before removing:
 
 ```bash
-# Remove all agent files
-rm -rf _bmad/bme/_designos/
+# 1. Back up your generated artifacts first
+cp -r _bmad-output/vortex-artifacts/ ~/my-vortex-backup/
+
+# 2. Remove agent files and workflows
+rm -rf _bmad/bme/_vortex/
 
-# Remove output directory (keeps your artifacts)
-# WARNING: This deletes all empathy maps and wireframes!
-rm -rf _bmad-output/design-artifacts/
+# 3. Remove generated artifacts (this deletes all your empathy maps, personas, etc.)
+rm -rf _bmad-output/vortex-artifacts/
 
-# Uninstall npm package
+# 4. Uninstall npm package
 npm uninstall bmad-enhanced
 ```
 
 ---
 
-## Support
-
-- **User Guides:** See `_bmad-output/design-artifacts/` after installation
-- **Issues:** https://github.com/yourusername/BMAD-Enhanced/issues
-- **Documentation:** [README.md](README.md)
-
----
-
-**Version:** 1.0.4-alpha
-**Last Updated:** 2026-02-16
-**Status:** Production Ready (Emma ✅, Wade ✅)
+[Back to README](README.md) | [Update Guide](UPDATE-GUIDE.md) | [Agent Guide](docs/agents.md)