bmad-enhanced 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -0,0 +1,624 @@
+# Changelog
+
+All notable changes to BMAD-Enhanced will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.3.2] - 2026-02-18
+
+### Fixed
+
+**🚨 CRITICAL Package Bug:**
+- Fixed `.npmignore` excluding Vortex framework 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
+- User guides in both `vortex-artifacts/` and `design-artifacts/` now included
+- **This was blocking all installations and migrations in v1.3.0 and v1.3.1** ❌
+
+**Package now includes:**
+- 113 files (was 27 in v1.3.0/v1.3.1)
+- 116.1 kB (was 55.0 kB in v1.3.0/v1.3.1)
+- All necessary agent and workflow files
+
+**⚠️ Action Required:**
+- If you installed v1.3.0 or v1.3.1: `npm install bmad-enhanced@1.3.2`
+- Fresh installations now work: `npx bmad-install-agents`
+- Migrations now work: `npx bmad-update`
+
+---
+
+## [1.3.1] - 2026-02-18
+
+### Fixed
+
+**🐛 Migration Bug:**
+- Fixed issue where deprecated agent files (`empathy-mapper.md`, `wireframe-designer.md`) were not being removed during migration
+- All three migrations (1.0.x, 1.1.x, 1.2.x → 1.3.0) now properly remove deprecated agents before copying new ones
+- Users upgrading from v1.0.x or v1.1.x will now see only the correct agent files
+- Migration preview output now explicitly shows which deprecated files will be removed
+
+**⚠️ Note:** v1.3.1 still had the critical `.npmignore` bug from v1.3.0. Use v1.3.2 instead.
+
+---
+
+## [1.3.0] - 2026-02-17
+
+### Major Release: Automatic Update/Migration System
+
+This release introduces a comprehensive update/migration system that makes it safe and easy to upgrade BMAD-Enhanced from previous versions.
+
+### Added
+
+**🔄 Automatic Update System:**
+- **bmad-update** - Main update CLI with dry-run support
+  - Preview changes before applying: `npx bmad-update --dry-run`
+  - Interactive confirmation (or `--yes` to skip)
+  - Automatic backup before every migration
+  - Automatic rollback on failure
+  - Detailed progress indicators
+
+- **bmad-version** - Version information CLI
+  - Shows current vs. latest version
+  - Displays migration history
+  - Update availability status
+  - Example: `npx bmad-version`
+
+- **bmad-migrate** - Manual migration control (advanced users)
+  - Run specific migrations
+  - List available migrations
+  - Example: `npx bmad-migrate 1.1.x-to-1.2.0`
+
+**📦 Migration Framework:**
+- Version detector with fallback strategies
+- Backup manager with automatic cleanup (keeps last 5)
+- Config merger preserving user preferences
+- Migration registry with version matching
+- Installation validator with comprehensive checks
+- Migration runner with orchestration and error handling
+
+**🛡️ Data Safety:**
+- Automatic backups before every migration
+- Backup location: `_bmad-output/.backups/backup-{version}-{timestamp}/`
+- Automatic rollback if migration fails
+- Migration history tracking in config.yaml
+- Migration logs in `_bmad-output/.logs/`
+- Lock file prevents concurrent migrations
+
+**📋 Migrations Implemented:**
+- `1.2.x-to-1.3.0` - Minor update (adds migration system)
+  - Updates version, removes deprecated agents, refreshes agent files, verifies structure
+- `1.1.x-to-1.3.0` - Minor update (no breaking changes)
+  - Updates version, removes deprecated agents, refreshes agent files, verifies structure
+- `1.0.x-to-1.3.0` - Breaking change migration
+  - Moves empathy-map → _deprecated/
+  - Installs all 7 new workflows
+  - Updates config and agent manifest
+  - Removes deprecated agent files
+  - Preserves all user data
+
+**📚 Documentation:**
+- **UPDATE-GUIDE.md** - Comprehensive update documentation
+  - Quick update instructions
+  - Migration paths (v1.1.x and v1.0.x)
+  - Data safety guarantees
+  - Troubleshooting guide
+  - FAQs
+- **README.md** - Added update section
+  - Version checking
+  - Update commands
+  - Migration paths
+  - Troubleshooting
+- **CHANGELOG.md** - This entry!
+
+### Changed
+
+**🎨 Enhanced Postinstall Experience:**
+- Now detects upgrades automatically
+- Shows breaking changes warnings
+- Prompts to run `npx bmad-update`
+- Displays current → new version
+- Does NOT auto-migrate (requires user consent)
+
+**⚙️ Package.json:**
+- Added `js-yaml` dependency for config parsing
+- Added 3 new bin commands:
+  - `bmad-update`
+  - `bmad-version`
+  - `bmad-migrate`
+
+**📁 File Structure:**
+- New `scripts/update/` directory:
+  - `lib/` - Shared migration logic (6 modules)
+  - `migrations/` - Individual migration files + registry
+  - `bmad-update.js`, `bmad-version.js`, `bmad-migrate.js` - CLI commands
+
+### Migration Features
+
+**Preserved During Updates:**
+- All user data in `_bmad-output/` (except documentation guides)
+- User preferences (user_name, communication_language)
+- Custom config settings (output_folder, party_mode_enabled)
+- BMAD Method files (never touched)
+- Deprecated workflows (remain functional in `_deprecated/`)
+
+**Updated During Migrations:**
+- Agent definition files
+- Workflow files
+- Config.yaml (with preference preservation)
+- User guides (documentation)
+- Agent manifest
+
+**Version Tracking:**
+- New `migration_history` field in config.yaml
+- Tracks: timestamp, from_version, to_version, migrations_applied
+- Prevents re-running migrations
+- Useful for debugging and support
+
+### User Experience
+
+**Before Update:**
+```bash
+npm install bmad-enhanced@1.3.0
+# Postinstall shows:
+# ⚠ UPGRADE DETECTED
+# Current version: 1.1.0
+# New version: 1.3.0
+# Run: npx bmad-update --dry-run (to preview)
+```
+
+**Preview Changes:**
+```bash
+npx bmad-update --dry-run
+# Shows detailed preview of changes without applying
+```
+
+**Apply Update:**
+```bash
+npx bmad-update
+# [1/5] Creating backup...
+# [2/5] Running migrations...
+# [3/5] Updating configuration...
+# [4/5] Validating installation...
+# [5/5] Cleanup...
+# ✓ Migration completed successfully!
+```
+
+### Technical Implementation
+
+**Core Components:**
+- **version-detector.js** - Detects versions, determines migration path
+- **backup-manager.js** - Creates backups, handles rollback
+- **config-merger.js** - Smart YAML merging preserving user settings
+- **migration-runner.js** - Orchestrates migrations, handles errors
+- **validator.js** - Validates installation integrity
+- **registry.js** - Tracks available migrations
+
+**Migration Flow:**
+1. Detect current/target versions
+2. Get applicable migrations
+3. Create backup
+4. Execute migrations sequentially
+5. Update config and migration history
+6. Validate installation
+7. Cleanup old backups
+8. Create migration log
+
+**Error Handling:**
+- Automatic rollback on any failure
+- Detailed error logs
+- Migration lock prevents concurrent runs
+- Validation checks after migration
+
+### Backwards Compatibility
+
+- v1.1.x users: Smooth upgrade, no breaking changes
+- v1.0.x users: Breaking changes handled automatically
+- Fresh installs: Unaffected, install normally
+- Manual migration: Fallback instructions provided
+- All migrations preserve user data
+
+### Future-Proof
+
+- Extensible migration registry
+- Easy to add new migrations (just add to registry.js)
+- Supports chained migrations (e.g., 1.0 → 1.1 → 1.2 → 1.3)
+- Version range matching (1.0.x, 1.1.x patterns)
+
+### Notes
+
+- This is a MAJOR infrastructure release
+- Sets foundation for future seamless updates
+- Users on v1.0.x or v1.1.x can safely upgrade
+- Update system tested with comprehensive migration scenarios
+- v1.4.0+ updates will use this system for smooth upgrades
+
+---
+
+## [1.2.0] - 2026-02-17
+
+### Major Release: Complete Vortex Framework Implementation
+
+This release completes the Vortex Framework by implementing all 7 new Lean Startup workflows, updating documentation, and cleaning up deprecated workflows.
+
+### Added
+
+**🎯 Emma's Contextualize Stream Workflows (3 workflows):**
+- **lean-persona** - Create lean user personas focused on jobs-to-be-done (not demographics)
+  - 6-step workflow from job definition through validation planning
+  - Hypothesis-driven approach with riskiest assumptions identified
+  - Integrates with Wade's lean-experiment workflow
+
+- **product-vision** - Define strategic product vision and alignment
+  - 6-step workflow from problem definition through synthesis
+  - Vision statement formula, future state (3-5 years), guiding principles
+  - Strategic assumptions identification and validation planning
+
+- **contextualize-scope** - Decide which problem space to investigate
+  - 6-step workflow using systematic opportunity evaluation
+  - Scoring matrix with weighted criteria
+  - Clear scope boundaries (what's in, what's out)
+
+**🧪 Wade's Externalize Stream Workflows (4 workflows):**
+- **mvp** - Design Minimum Viable Product specifications
+  - Focus on testing riskiest assumptions, not building feature-light products
+  - Build-Measure-Learn cycle planning
+  - Success criteria and MVP scope definition
+
+- **lean-experiment** - Execute Build-Measure-Learn cycles
+  - Hypothesis-driven experimentation framework
+  - Metrics definition and experiment design
+  - Pivot or persevere decision framework
+
+- **proof-of-concept** - Validate technical feasibility
+  - Test that you CAN build it before validating you SHOULD
+  - Technical risk assessment and PoC scoping
+  - Feasibility evaluation and findings documentation
+
+- **proof-of-value** - Validate business value and market demand
+  - Test that you SHOULD build it (business case)
+  - Willingness to pay experiments
+  - Business case calculation and build/pivot/kill decisions
+
+**📚 Documentation Updates:**
+- **Emma User Guide v1.2.0** - Updated to reflect Contextualization Expert role
+  - Focuses on Lean Startup methodologies and strategic framing
+  - Documents legacy empathy-map workflow (still functional)
+  - Documents all 3 new Contextualize stream workflows
+  - Location: `_bmad-output/vortex-artifacts/EMMA-USER-GUIDE.md`
+
+- **Wade User Guide v1.2.0** - Updated to reflect Lean Experiments Specialist role
+  - Focuses on Build-Measure-Learn cycles and validated learning
+  - Documents legacy wireframe workflow (still functional)
+  - Documents all 4 new Externalize stream workflows
+  - Location: `_bmad-output/vortex-artifacts/WADE-USER-GUIDE.md`
+
+### Changed
+- User guides moved from `design-artifacts/` to `vortex-artifacts/`
+- Deprecated workflows archived to `_bmad/bme/_vortex/workflows/_deprecated/`
+  - `empathy-map/` moved to `_deprecated/empathy-map/` (still functional)
+  - `wireframe/` moved to `_deprecated/wireframe/` (still functional)
+- Installer scripts updated to reference deprecated workflow locations
+- Config.yaml version bumped to 1.2.0
+- All installer scripts now install user guides from vortex-artifacts location
+
+### Documentation
+- Emma positioned as Lean Startup expert (not design thinking)
+- Wade positioned as experimentation specialist (not wireframe designer)
+- Comprehensive migration guides added to both user guides
+- Roadmap section added documenting v1.3.0 and v1.4.0+ plans
+
+### Backwards Compatibility
+- Legacy workflows (empathy-map, wireframe) remain functional
+- Old artifacts from v1.0.x-v1.1.x continue to work
+- Migration path documented for users on previous versions
+
+### Technical Details
+- **Total files created:** 56 workflow files (7 workflows × 8 files each)
+- **Workflow architecture:** Step-file based with just-in-time loading
+- **Output templates:** Markdown-based artifact templates for each workflow
+- **Integration:** Workflows reference each other (e.g., lean-persona → mvp → lean-experiment)
+
+### Notes
+- All 7 Vortex workflows now fully implemented and ready to use
+- Legacy workflows (empathy-map, wireframe) remain in `_deprecated/` for backwards compatibility
+- Update/migration tooling planned for v1.3.0
+- This is a MAJOR feature release, not just documentation cleanup
+
+---
+
+## [1.1.3] - 2026-02-17
+
+### Fixed
+- Removed outdated user guide references from installer output
+  - Replaced with "User guides being updated for v1.2.0" message in all 3 installers
+
+---
+
+## [1.1.2] - 2026-02-17
+
+### Fixed
+- **CRITICAL: Installer scripts now reference correct agent file names**
+  - Updated `install-all-agents.js` to copy `contextualization-expert.md` and `lean-experiments-specialist.md`
+  - Updated `install-emma.js` to copy `contextualization-expert.md`
+  - Updated `install-wade.js` to copy `lean-experiments-specialist.md`
+  - Fixed config.yaml generation in all installers to use new agent names
+  - Fixed agent-manifest.csv generation to reference correct file paths
+  - Fixed Quick Start instructions in installer output
+
+**Impact:** v1.1.1 had broken installer scripts that would fail when users ran `npx bmad-install-agents`. This patch fixes the installation process.
+
+### Known Issues
+- User guides still reference v1.0.0 content and will be updated in v1.2.0
+
+---
+
+## [1.1.1] - 2026-02-17
+
+### Fixed
+- **Agent file naming consistency:** Renamed agent files to match BMM module naming convention
+  - `empathy-mapper.md` → `contextualization-expert.md`
+  - `wireframe-designer.md` → `lean-experiments-specialist.md`
+- Updated all workflow references to use new agent file names
+- Updated config.yaml agent list with new names
+- Fixed migration guide in v1.1.0 to reference correct agent file names
+
+---
+
+## [1.1.0] - 2026-02-16
+
+### MAJOR REPOSITIONING: From Design Agents to Vortex Framework
+
+This release represents a fundamental repositioning of BMAD-Enhanced from design-focused agents (empathy mapping, wireframing) to a Lean Startup validation framework.
+
+### Changed
+- **BREAKING:** Renamed module from `_designos` to `_vortex`
+- **BREAKING:** Emma repositioned from "Empathy Mapping Specialist" to "Contextualization Expert" (icon: 🎯)
+  - Focus: Strategic framing, lean personas, product vision, problem space navigation
+  - Role: Guides teams through the "Contextualize" stream
+  - New workflows: lean-persona, product-vision, contextualize-scope (empathy-map deprecated)
+- **BREAKING:** Wade repositioned from "Wireframe Design Specialist" to "Lean Experiments Specialist" (icon: 🧪)
+  - Focus: Build-Measure-Learn cycles, MVPs, validated learning
+  - Role: Guides teams through the "Externalize" stream
+  - 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 agent-manifest.csv with new agent identities and expertise
+
+### Added
+- Vortex framework 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
+- Version field in config.yaml for better version tracking
+
+### Migration Guide
+
+**For existing users upgrading from 1.0.x:**
+
+1. **Module path changed:**
+   - Old: `_bmad/bme/_designos/`
+   - New: `_bmad/bme/_vortex/`
+
+2. **Output folder changed:**
+   - Old: `_bmad-output/design-artifacts/`
+   - New: `_bmad-output/vortex-artifacts/`
+
+3. **Agent activation paths updated:**
+   - Emma: `cat _bmad/bme/_vortex/agents/contextualization-expert.md`
+   - Wade: `cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md`
+
+4. **Workflows replaced:**
+   - Emma's empathy-map workflow → lean-persona workflow (coming in v1.2.0)
+   - Wade's wireframe workflow → lean-experiment workflow (coming in v1.2.0)
+
+5. **Clean reinstall recommended:**
+   ```bash
+   # Backup any custom configs
+   # Remove old installation
+   rm -rf _bmad/bme/_designos
+   rm -rf _bmad-output/design-artifacts
+
+   # Install v1.1.0
+   npm install bmad-enhanced@1.1.0
+   npx bmad-install-agents
+   ```
+
+### Positioning Rationale
+
+**Why this change?**
+
+The repositioning aligns Emma and Wade with Lean Startup and validated learning principles:
+
+- **Emma (Contextualize):** Helps teams frame the right problem before building solutions
+  - Differentiation: Emma contextualizes (problem space), Maya creates (solution space)
+- **Wade (Externalize):** Helps teams validate assumptions through rapid experimentation
+  - Differentiation: Wade externalizes (test with users), Sally internalizes (test with code)
+
+This creates a clear value proposition: Use Emma + Wade for Lean Startup validation, then hand off to BMAD core agents for implementation.
+
+### Technical Details
+- Module version: 1.1.0
+- Config structure: Updated with submodule metadata
+- Backward compatibility: NONE (breaking changes require migration)
+- Package size: ~55KB (unchanged)
+
+### Notes
+- v1.0.x workflows (empathy-map, wireframe) are deprecated
+- New workflows (lean-persona, mvp, etc.) will be fully implemented in v1.2.0
+- User guides will be updated in v1.2.0 to reflect new positioning
+
+---
+
+## [1.0.4-alpha] - 2026-02-16
+
+### Fixed
+- **Documentation:** All installation commands now correctly use `npm install bmad-enhanced@alpha` instead of `npm install bmad-enhanced`
+- Updated installation instructions across all documentation files:
+  - README.md
+  - INSTALLATION.md
+  - BMAD-METHOD-COMPATIBILITY.md
+  - PUBLISHING-GUIDE.md
+  - scripts/README.md
+  - index.js
+
+### Changed
+- Updated CLI output in index.js to show npx commands instead of npm run commands
+- Updated version references from 1.0.3-alpha to 1.0.4-alpha
+
+### Notes
+- v1.0.3-alpha was unpublished due to incorrect installation documentation
+- This release contains the same functionality as 1.0.3-alpha with corrected docs
+
+---
+
+## [1.0.3-alpha] - 2026-02-15 (Unpublished)
+
+### Added
+- **npx bin commands** for user-friendly installation
+  - `npx bmad-install-agents` - Install all agents (Emma + Wade)
+  - `npx bmad-install-emma` - Install Emma only
+  - `npx bmad-install-wade` - Install Wade only
+- bin section in package.json with executable scripts
+- Updated postinstall message to show npx commands
+
+### Changed
+- **BREAKING:** Installation command changed from `npm run install:agents` to `npx bmad-install-agents`
+- Updated all documentation to use npx commands:
+  - README.md
+  - INSTALLATION.md
+  - BMAD-METHOD-COMPATIBILITY.md
+  - PUBLISHING-GUIDE.md
+  - All other documentation files
+
+### Fixed
+- Installation now works correctly in user projects (previous `npm run` commands didn't work)
+- Users can now install agents without package.json modifications
+
+### Technical Details
+- Added bin executables that npm automatically links to node_modules/.bin/
+- Maintained backward compatibility with npm scripts for development
+
+---
+
+## [1.0.2-alpha] - 2026-02-15
+
+### Added
+- User guides now included in npm package (19KB Emma guide + 43KB Wade guide)
+
+### Fixed
+- **Bug:** User guides were excluded from npm package due to .npmignore pattern ordering
+- Reordered .npmignore patterns so specific inclusions take precedence over general exclusions
+
+### Changed
+- Package size increased from 40KB to 55.6KB (due to user guides inclusion)
+
+---
+
+## [1.0.1-alpha] - 2026-02-15
+
+### Fixed
+- **Critical Bug:** Wade workflow installation failed due to filename mismatch
+  - Installer tried to copy `step-05-components-interactions.md`
+  - Actual filename was `step-05-components.md`
+- Fixed in:
+  - scripts/install-all-agents.js (line 114)
+  - scripts/install-wade.js (line 72)
+
+---
+
+## [1.0.0-alpha] - 2026-02-15
+
+### Added
+- Initial release of BMAD-Enhanced
+- **Emma (empathy-mapper)** - Empathy Mapping Specialist
+  - 6-step empathy map workflow
+  - Empathy map template
+  - Validation workflow
+  - Complete user guide (19KB)
+- **Wade (wireframe-designer)** - Wireframe Design Expert
+  - 6-step wireframe workflow
+  - Wireframe template
+  - Complete user guide (43KB)
+- Complete installation system
+  - BMAD Method prerequisite checking
+  - Automatic agent file copying
+  - Configuration file generation
+  - User-friendly installation messages
+- Comprehensive documentation
+  - README.md with project overview
+  - INSTALLATION.md with detailed installation guide
+  - BMAD-METHOD-COMPATIBILITY.md explaining integration
+  - User guides for both agents
+- Test coverage
+  - Emma: 18 P0 tests + 5 live tests (100% pass rate)
+  - Wade: 18 P0 tests + 5 live tests (100% pass rate)
+
+### Technical Details
+- Package size: 40KB (initial)
+- 33 files in package
+- Dependencies: chalk (4.1.2), fs-extra (11.3.3)
+- Node.js requirement: >=14.0.0
+- License: MIT
+
+---
+
+## Version History
+
+| Version | Date | Type | Description |
+|---------|------|------|-------------|
+| 1.0.3-alpha | 2026-02-15 | Feature | npx bin commands |
+| 1.0.2-alpha | 2026-02-15 | Bug Fix | User guides included |
+| 1.0.1-alpha | 2026-02-15 | Bug Fix | Wade filename fix |
+| 1.0.0-alpha | 2026-02-15 | Initial | First release |
+
+---
+
+## Upgrade Guide
+
+### From 1.0.2-alpha to 1.0.3-alpha
+
+**Installation command changed:**
+
+**Old:**
+```bash
+npm install bmad-enhanced@alpha
+npm run install:agents  # This doesn't work
+```
+
+**New:**
+```bash
+npm install bmad-enhanced@alpha
+npx bmad-install-agents  # This works!
+```
+
+**Note:** The old `npm run install:agents` command never actually worked in user projects. The new npx command is the correct installation method.
+
+### From 1.0.1-alpha to 1.0.2-alpha
+
+No changes to installation flow. User guides are now automatically included.
+
+### From 1.0.0-alpha to 1.0.1-alpha
+
+No changes to installation flow. Reinstallation will fix the Wade workflow bug.
+
+---
+
+## Links
+
+- **npm Package:** https://www.npmjs.com/package/bmad-enhanced
+- **GitHub Repository:** https://github.com/amalik/BMAD-Enhanced
+- **BMAD Method:** https://github.com/bmadhub/bmad
+- **Issues:** https://github.com/amalik/BMAD-Enhanced/issues
+
+---
+
+**For detailed technical documentation, see:**
+- [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/`