bmad-enhanced 1.6.4 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.7.0] - 2026-03-02
+
+### Added
+
+- **Docs Audit Tool** (`npm run docs:audit`) — Programmatic documentation quality checker with 5 check types:
+  - Stale numeric references (detects outdated agent/workflow counts)
+  - Broken internal links
+  - Incomplete agent listing tables (with relationship table detection)
+  - Internal naming convention leaks (`_vortex` in user-facing prose)
+  - Forward-compatibility checks
+- **P0 Content Correctness Test Suite** — 12 test files covering activation, voice consistency, content correctness, handoff contracts, and workflow structure for all 7 agents
+- **18 production-quality workflow step files** for Wade's three remaining workflows:
+  - `lean-experiment/steps/` — step-01-hypothesis through step-06-decide
+  - `proof-of-concept/steps/` — step-01-risk through step-06-document
+  - `proof-of-value/steps/` — step-01-value-hypothesis through step-06-document
+- **7 comprehensive user guides** — Created/expanded guides for all 7 agents in `_bmad/bme/_vortex/guides/`
+- **"Your First 15 Minutes" walkthrough** in README — 6-step guided onboarding from config to first artifact
+- **Activation model explanation** in README — explains what agent files are and how Claude adopts personas
+- **Config personalization step** in README Quick Start and installer output
+- **`bmad-update` test suite** — 615+ lines covering upgrade flows, config merging, version detection
+- **`bmad-version` test suite** — 377 lines covering version display, migration history, update detection
+- **`docs-audit` test suite** — 539 lines covering all 5 check functions
+- **7-agent journey example** — Complete busy-parents walkthrough demonstrating all 7 agents and handoff contracts
+- **Structured feedback mechanism** — GitHub issue template for agent/workflow feedback
+
+### Changed
+
+- **CRITICAL: Fixed npm package bloat** — Package reduced from 1618 files / 9.7 MB to 242 files / 1.1 MB. The `files` field in `package.json` was too broad (`"_bmad/"`, `"_bmad-output/"`), shipping internal backups, migration logs, sprint artifacts, and all BMAD modules (bmm, cis, core, tea). Now precisely targets `"_bmad/bme/_vortex/"` only.
+- **Config merger smart-merge** — `mergeConfig()` now preserves user-added agents and workflows during updates. Canonical entries maintain registry order; user-added entries are deduplicated and appended.
+- **User guide invocation methods reordered** — Direct File Reading is now Method 1 (Recommended) in all 7 guides; Slash Command is Method 2 (BMAD Environments Only)
+- **README overhaul** — Value proposition, visual Vortex diagram, agent output previews, Claude Code/Claude.ai activation instructions
+- **Installer output** — Now shows numbered "Next Steps" including config personalization
+- **Journey example condensed** — 944 to 888 lines, tightened transition sections
+- **docs/agents.md** — Updated agent count references, handoff contract documentation
+- **docs/faq.md** — Expanded with workflow and agent questions
+- **INSTALLATION.md** — Updated installation instructions
+- **UPDATE-GUIDE.md** — Added user-agent preservation documentation
+
+### Fixed
+
+- Config merger overwrote user-added agents on upgrade (now preserved via smart-merge)
+- Incomplete agent table detection false positives on relationship/contract-flow tables
+- Internal naming leak check false positives on markdown link targets and backtick-wrapped paths
+- `_vortex` appearing unescaped in 7 user guide Credits sections
+- Separator and header rows incorrectly counted in agent table completeness check
+- README "Type `LP`" instruction meaningless to new users (now "Select **Lean Persona** from the menu")
+- Redundant config personalization step in "Your First 15 Minutes"
+
+### Technical Details
+
+- **Tests:** 309 pass, 0 fail, 0 todo (unit + integration + P0)
+- **Package:** 242 files, 1.1 MB unpacked (was 1618 files, 9.7 MB)
+- **Docs audit:** `npm run docs:audit --json` returns `[]` (zero findings)
+- **All 22 workflows** now have production-quality step content (no placeholders)
+
+---
+
 ## [1.6.0] - 2026-02-26
 
 ### Added
@@ -834,4 +891,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,47 +10,47 @@
        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)
+[![Version](https://img.shields.io/badge/version-1.7.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)
 
 </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 |
 
 ---
 
@@ -70,6 +70,10 @@ npm install bmad-enhanced && npx bmad-install-vortex-agents
 
 All 7 agents with 22 workflows are installed and ready to use.
 
+### Personalize
+
+Open `_bmad/bme/_vortex/config.yaml` and replace `{user}` with your name. Agents use this to personalize their interactions.
+
 ### Activate an Agent
 
 ```bash
@@ -83,7 +87,23 @@ cat _bmad/bme/_vortex/agents/production-intelligence-specialist.md # Noah  📡
 cat _bmad/bme/_vortex/agents/learning-decision-expert.md          # Max   🧭
 ```
 
-Each agent presents a menu-driven interface. Pick a workflow and follow the guided steps.
+**How activation works:** Each agent is a markdown file containing a full persona, menu system, and workflow instructions. When Claude reads the file, it adopts that agent's expertise and presents you with an interactive menu.
+
+- **Claude Code / Terminal:** Use the `cat` commands above
+- **Claude.ai:** Copy the contents of any agent file and paste into the chat
+
+Pick a workflow from the menu and follow the guided steps.
+
+### Your First 15 Minutes
+
+1. **Personalize** — If you haven't already, edit `_bmad/bme/_vortex/config.yaml` and replace `{user}` with your name
+2. **Activate Emma** — `cat _bmad/bme/_vortex/agents/contextualization-expert.md`
+3. **See the menu** — Emma presents numbered options. Select **Lean Persona** from the menu
+4. **Follow the steps** — Emma walks you through 6 guided steps, asking questions at each one
+5. **Find your artifact** — When done, your lean persona is saved in `_bmad-output/vortex-artifacts/`
+6. **Follow the Compass** — At the end, Emma's Vortex Compass suggests which agent to use next based on what you learned
+
+Each workflow ends with a Compass routing suggestion. You don't need to follow a linear path — the system guides you to whichever stream needs attention.
 
 ### What Gets Installed
 
@@ -92,7 +112,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 +139,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 +195,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 +243,9 @@ 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)
+- **v1.7.0** — Wave 4: Quality & onboarding (P0 test suite, docs audit tool, all 22 workflows production-ready, README overhaul, package size fix)
 - **v2.0.0+** — Multi-agent collaboration, cross-agent workflows, analytics
 
 ---
@@ -196,6 +259,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 +322,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
@@ -120,11 +120,38 @@ Every update creates a backup before making changes:
 
 - Agent definition files
 - Workflow files (steps, templates, validation)
-- Vortex config.yaml (with preference preservation)
+- Vortex config.yaml (with preference preservation — user-added agents and workflows are kept after core entries)
 - User guides
 
 ---
 
+## 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"