Skip to content

MIGRATION-GUIDE.md

Latest commit

 

History

History
190 lines (140 loc) · 4.6 KB

MIGRATION-GUIDE.md

File metadata and controls

190 lines (140 loc) · 4.6 KB
Raw

Migration Guide: Progress Tracking v1 to v2

This guide helps you upgrade from Progress Tracking Bundle v1 (BMAD v4 only) to v2 (BMAD v4 & v6 compatible).

What's New in v2

  • BMAD v6 Support: Full compatibility with the new BMAD v6 directory structure
  • Auto-Detection: Scripts automatically detect your BMAD version
  • Backward Compatible: Still works with BMAD v4 projects
  • Improved Scripts: Better error handling and informative messages

Quick Migration (Recommended)

For BMAD v4 Projects (No Changes Needed)

If you're staying on BMAD v4, the v2 bundle is fully backward compatible:

  1. Backup your current installation (optional):
cp -r .bmad-core/utils .bmad-core/utils.backup
  1. Install v2 bundle:
# From the new v2 bundle directory
cp -r * /path/to/your/project/
npm install
  1. Test:
npm run progress

Your existing scripts will continue to work exactly as before!

For Projects Upgrading to BMAD v6

If you're upgrading your project from BMAD v4 to v6:

  1. Complete your BMAD v6 upgrade first (follow BMAD's upgrade guide)

  2. Install the v2 progress tracking bundle:

# From the v2 bundle directory
cp -r tools /path/to/your/project/
cp package.json /path/to/your/project/  # Or merge scripts
npm install
  1. Remove old v4 progress files (after confirming v6 works):
rm -rf .bmad-core/utils/update-progress.js
rm -rf .bmad-core/utils/progress-*.js
  1. Test:
npm run progress

Directory Structure Changes

v1 Structure (BMAD v4 only):

.bmad-core/
└── utils/
    ├── update-progress.js
    ├── progress-watcher.js
    ├── trigger-progress-update.js
    └── progress-terminal.js

v2 Structure (BMAD v4 & v6):

# For v4:
.bmad-core/
└── utils/
    └── [same files as v1]

# For v6:
tools/
└── progress-tracking/
    └── [same files, updated for v6]

Script Changes

Package.json Scripts

The v2 scripts automatically try both locations:

v1 scripts:

"progress": "node .bmad-core/utils/update-progress.js"

v2 scripts (work with both versions):

"progress": "node tools/progress-tracking/update-progress.js 2>/dev/null || node .bmad-core/utils/update-progress.js"

Configuration Changes

Config File Location

  • v4: .bmad-core/core-config.yaml
  • v6: bmad-core/core-config.yaml (no leading dot)

The v2 scripts automatically check both locations.

Compatibility Matrix

Progress Bundle BMAD v4 BMAD v5 BMAD v6
v1.0 ✅ ❌ ❌
v2.0 ✅ N/A ✅

Note: BMAD v5 was skipped and replaced by v6.

Troubleshooting

Issue: Scripts not found after upgrade

Solution: Ensure you've copied the correct directories:

  • For v4: Copy .bmad-core/ directory
  • For v6: Copy tools/ directory

Issue: "Cannot find core-config.yaml"

Solution: Check that your config exists at:

  • v4: .bmad-core/core-config.yaml
  • v6: bmad-core/core-config.yaml

Issue: Old scripts still running

Solution: Clear npm cache and reinstall:

npm cache clean --force
npm install

Issue: Conflicting package.json scripts

Solution: Merge the scripts manually, keeping the v2 versions which support both:

{
  "scripts": {
    "progress": "node tools/progress-tracking/update-progress.js 2>/dev/null || node .bmad-core/utils/update-progress.js",
    // ... other v2 scripts
  }
}

Need Help?

  • Check the main README.md for usage instructions
  • Verify your BMAD version with: ls bmad-core 2>/dev/null && echo "v6" || echo "v4"
  • Run scripts with verbose output: npm run progress --verbose

Rollback Instructions

If you need to rollback to v1:

  1. Restore v1 files:
# If you backed up
cp -r .bmad-core/utils.backup/* .bmad-core/utils/
  1. Restore v1 package.json scripts:
{
  "scripts": {
    "progress": "node .bmad-core/utils/update-progress.js",
    "progress:watch": "node .bmad-core/utils/progress-watcher.js",
    "progress:trigger": "node .bmad-core/utils/trigger-progress-update.js",
    "progress:terminal": "node .bmad-core/utils/progress-terminal.js"
  }
}
  1. Remove v6 files (if installed):
rm -rf tools/progress-tracking

Summary

The v2 bundle is designed to be a drop-in replacement for v1 with added v6 support. For most users, simply copying the new files and running npm install is all that's needed. The scripts will automatically detect your BMAD version and use the appropriate paths.