bmad-enhanced 1.3.8 → 1.4.0

package/scripts/install-all-agents.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs-extra');
 const path = require('path');
+const { refreshInstallation } = require('./update/lib/refresh-installation');
 
 const BOLD = '\x1b[1m';
 const RESET = '\x1b[0m';
@@ -17,17 +18,16 @@ function printBanner() {
   console.log(`${MAGENTA}${BOLD}║                                                    ║${RESET}`);
   console.log(`${MAGENTA}${BOLD}║        BMAD-Enhanced Complete Installer 🚀        ║${RESET}`);
   console.log(`${MAGENTA}${BOLD}║                                                    ║${RESET}`);
-  console.log(`${MAGENTA}${BOLD}║     Installing Emma + Wade Design Agents          ║${RESET}`);
+  console.log(`${MAGENTA}${BOLD}║     Installing Emma + Wade Vortex Agents          ║${RESET}`);
   console.log(`${MAGENTA}${BOLD}║                                                    ║${RESET}`);
   console.log(`${MAGENTA}${BOLD}╚════════════════════════════════════════════════════╝${RESET}`);
   console.log('');
 }
 
-function checkPrerequisites() {
+function checkPrerequisites(projectRoot) {
   console.log(`${CYAN}[1/6]${RESET} Checking prerequisites...`);
 
-  const targetDir = process.cwd();
-  const bmadDir = path.join(targetDir, '_bmad');
+  const bmadDir = path.join(projectRoot, '_bmad');
 
   // Create _bmad directory if it doesn't exist
   if (!fs.existsSync(bmadDir)) {
@@ -48,160 +48,54 @@ function checkPrerequisites() {
   console.log(`${GREEN}  ✓${RESET} Prerequisites met`);
 }
 
-function copyAllAgentFiles() {
-  console.log(`${CYAN}[2/6]${RESET} Installing Emma + Wade agent files...`);
+function archiveDeprecatedWorkflows(projectRoot) {
+  console.log(`${CYAN}[2/6]${RESET} Archiving deprecated workflows...`);
 
   const sourceDir = path.join(__dirname, '..', '_bmad', 'bme', '_vortex');
-  const targetDir = path.join(process.cwd(), '_bmad', 'bme', '_vortex');
-
-  // Create target directory structure
-  fs.mkdirSync(path.join(targetDir, 'agents'), { recursive: true });
-  fs.mkdirSync(path.join(targetDir, 'workflows', '_deprecated', 'empathy-map', 'steps'), { recursive: true });
-  fs.mkdirSync(path.join(targetDir, 'workflows', '_deprecated', 'wireframe', 'steps'), { recursive: true });
-
-  // Copy Emma agent file
-  console.log(`${CYAN}  →${RESET} Installing Emma (contextualization-expert)...`);
-  fs.copyFileSync(
-    path.join(sourceDir, 'agents', 'contextualization-expert.md'),
-    path.join(targetDir, 'agents', 'contextualization-expert.md')
-  );
-
-  // Copy Emma workflow files
-  const emmaWorkflowFiles = [
-    'workflow.md',
-    'empathy-map.template.md',
-    'steps/step-01-define-user.md',
-    'steps/step-02-says-thinks.md',
-    'steps/step-03-does-feels.md',
-    'steps/step-04-pain-points.md',
-    'steps/step-05-gains.md',
-    'steps/step-06-synthesize.md'
-  ];
-
-  emmaWorkflowFiles.forEach(file => {
-    fs.copyFileSync(
-      path.join(sourceDir, 'workflows', '_deprecated', 'empathy-map', file),
-      path.join(targetDir, 'workflows', '_deprecated', 'empathy-map', file)
-    );
-  });
-
-  console.log(`${GREEN}  ✓${RESET} Emma installed`);
-
-  // Copy Wade agent file
-  console.log(`${CYAN}  →${RESET} Installing Wade (lean-experiments-specialist)...`);
-  fs.copyFileSync(
-    path.join(sourceDir, 'agents', 'lean-experiments-specialist.md'),
-    path.join(targetDir, 'agents', 'lean-experiments-specialist.md')
-  );
-
-  // Copy Wade workflow files
-  const wadeWorkflowFiles = [
-    'workflow.md',
-    'wireframe.template.md',
-    'steps/step-01-define-requirements.md',
-    'steps/step-02-user-flows.md',
-    'steps/step-03-information-architecture.md',
-    'steps/step-04-wireframe-sketch.md',
-    'steps/step-05-components.md',
-    'steps/step-06-synthesize.md'
-  ];
-
-  wadeWorkflowFiles.forEach(file => {
-    fs.copyFileSync(
-      path.join(sourceDir, 'workflows', '_deprecated', 'wireframe', file),
-      path.join(targetDir, 'workflows', '_deprecated', 'wireframe', file)
-    );
-  });
+  const targetDir = path.join(projectRoot, '_bmad', 'bme', '_vortex');
 
-  console.log(`${GREEN}  ✓${RESET} Wade installed`);
-
-  // Copy all 7 new workflow directories
-  console.log(`${CYAN}  →${RESET} Installing Vortex Framework workflows...`);
-  const workflows = [
-    'lean-persona',
-    'product-vision',
-    'contextualize-scope',
-    'mvp',
-    'lean-experiment',
-    'proof-of-concept',
-    'proof-of-value'
-  ];
+  // Create deprecated workflow archive directories
+  const deprecatedWorkflows = ['empathy-map', 'wireframe'];
 
-  workflows.forEach(workflow => {
-    const workflowSourceDir = path.join(sourceDir, 'workflows', workflow);
-    const workflowTargetDir = path.join(targetDir, 'workflows', workflow);
+  for (const workflow of deprecatedWorkflows) {
+    const workflowSourceDir = path.join(sourceDir, 'workflows', '_deprecated', workflow);
+    const workflowTargetDir = path.join(targetDir, 'workflows', '_deprecated', workflow);
 
     if (fs.existsSync(workflowSourceDir)) {
       fs.copySync(workflowSourceDir, workflowTargetDir);
-      console.log(`${GREEN}    ✓${RESET} ${workflow}`);
-    } else {
-      console.log(`${YELLOW}    ⚠${RESET} ${workflow} not found in package (skipping)`);
+      console.log(`${GREEN}  ✓${RESET} Archived ${workflow} to _deprecated/`);
     }
-  });
+  }
 
-  console.log(`${GREEN}  ✓${RESET} All workflows installed`);
+  // Legacy cleanup
+  cleanupLegacyFiles(projectRoot);
 }
 
-function updateConfig() {
-  console.log(`${CYAN}[3/6]${RESET} Configuring agents...`);
-
-  const configPath = path.join(process.cwd(), '_bmad', 'bme', '_vortex', 'config.yaml');
-  const manifestPath = path.join(process.cwd(), '_bmad', '_config', 'agent-manifest.csv');
-
-  console.log(`${CYAN}  →${RESET} Config path: ${configPath}`);
-
-  // Create config
-  const configContent = `---
-submodule_name: _vortex
-description: Contextualize and Externalize streams - Strategic framing and validated learning
-module: bme
-version: 1.3.8
-
-# Output Configuration
-output_folder: "{project-root}/_bmad-output/vortex-artifacts"
-user_name: "{user}"
-communication_language: "en"
-
-# Agents in this submodule
-agents:
-  - contextualization-expert     # Emma - Contextualization Expert
-  - lean-experiments-specialist  # Wade - Lean Experiments Specialist
-
-# Workflows available
-workflows:
-  # Emma - Contextualize Stream
-  - lean-persona           # Create lean user personas
-  - product-vision         # Define product vision
-  - contextualize-scope    # Decide which problem space to investigate
-
-  # Wade - Externalize Stream
-  - mvp                    # Design Minimum Viable Product
-  - lean-experiment        # Run Build-Measure-Learn cycle
-  - proof-of-concept       # Validate technical feasibility
-  - proof-of-value         # Validate business value
-
-# Integration
-party_mode_enabled: true
-core_module: bme
-`;
+function cleanupLegacyFiles(projectRoot) {
+  console.log(`${CYAN}  →${RESET} Cleaning up legacy files...`);
 
-  try {
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, configContent);
+  // Remove _designos directory (pre-Vortex structure) from all possible locations
+  const legacyPaths = [
+    path.join(projectRoot, '_bmad', 'bme', '_designos'),
+    path.join(projectRoot, '_bmad', '_designos'),
+  ];
 
-    // Verify file was created
-    if (fs.existsSync(configPath)) {
-      console.log(`${GREEN}  ✓${RESET} Created config.yaml`);
-    } else {
-      console.error(`${RED}  ✗${RESET} Config file not found after write!`);
+  for (const legacyPath of legacyPaths) {
+    if (fs.existsSync(legacyPath)) {
+      fs.removeSync(legacyPath);
+      console.log(`${GREEN}    ✓${RESET} Removed legacy directory: ${path.relative(projectRoot, legacyPath)}`);
     }
-  } catch (error) {
-    console.error(`${RED}  ✗${RESET} Error creating config.yaml:`, error.message);
-    throw error;
   }
 
-  // Create manifest
+  console.log(`${GREEN}  ✓${RESET} Legacy cleanup complete`);
+}
+
+function createAgentManifest(projectRoot) {
+  console.log(`${CYAN}[3/6]${RESET} Creating agent manifest...`);
+
+  const manifestPath = path.join(projectRoot, '_bmad', '_config', 'agent-manifest.csv');
   fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+
   const header = '"agent_id","name","title","icon","role","identity","communication_style","expertise","submodule","path"\n';
   const emmaRow = '"contextualization-expert","Emma","Contextualization Expert","🎯","Strategic Framing + Problem-Product Space Navigator","Expert in helping teams contextualize their product strategy by defining clear problem spaces and validating assumptions. Specializes in Lean Startup methodologies, persona creation, and product vision framing. Guides teams through the critical \'Contextualize\' stream of the Vortex framework.","Strategic yet approachable - speaks in frameworks and validated learning. Like a product strategist who asks \'What are we really solving?\' and \'Who is this truly for?\' Uses Lean Startup language (hypotheses, assumptions, pivots) and focuses on clarity before action.","- Master of Lean Startup and strategic framing methodologies - Personas over demographics - focus on jobs-to-be-done and problem contexts - Vision before features - align team around the \'why\' before the \'what\' - Challenge assumptions - every belief is a hypothesis until validated - Problem-solution fit comes before product-market fit","bme","_bmad/bme/_vortex/agents/contextualization-expert.md"\n';
   const wadeRow = '"lean-experiments-specialist","Wade","Lean Experiments Specialist","🧪","Lean Startup + Validated Learning Expert","Lean Startup practitioner specialized in running rapid experiments to validate product hypotheses. Helps teams move from assumptions to evidence through Build-Measure-Learn cycles. Guides teams through the \'Externalize\' stream - taking ideas into the real world to test with actual users.","Experimental and evidence-driven - speaks in hypotheses, metrics, and learning. Like a scientist who says \'Let\'s test that assumption\' and \'What would prove us wrong?\' Uses Lean language (MVPs, pivots, validated learning) and focuses on speed-to-insight over perfection.","- Master of Lean Startup and rapid experimentation - Build the smallest thing that tests the riskiest assumption - Measure what matters - focus on actionable metrics, not vanity metrics - Learn fast, pivot faster - every experiment teaches something - Proof-of-concept before proof-of-value - validate feasibility before business case - Fail fast is good, learn fast is better","bme","_bmad/bme/_vortex/agents/lean-experiments-specialist.md"\n';
@@ -209,30 +103,27 @@ core_module: bme
   console.log(`${GREEN}  ✓${RESET} Created agent-manifest.csv`);
 }
 
-function createOutputDirectory() {
+function createOutputDirectory(projectRoot) {
   console.log(`${CYAN}[4/6]${RESET} Setting up output directory...`);
 
-  const outputDir = path.join(process.cwd(), '_bmad-output', 'vortex-artifacts');
+  const outputDir = path.join(projectRoot, '_bmad-output', 'vortex-artifacts');
   fs.mkdirSync(outputDir, { recursive: true });
 
   console.log(`${GREEN}  ✓${RESET} Output directory ready`);
 }
 
-function verifyInstallation() {
-  console.log(`${CYAN}[5/6]${RESET} Verifying installation...`);
+function verifyInstallation(projectRoot) {
+  console.log(`${CYAN}[6/6]${RESET} Verifying installation...`);
 
-  const targetDir = process.cwd();
   const checks = [
     { path: '_bmad/bme/_vortex/agents/contextualization-expert.md', name: 'Emma agent file' },
     { path: '_bmad/bme/_vortex/agents/lean-experiments-specialist.md', name: 'Wade agent file' },
-    { path: '_bmad/bme/_vortex/workflows/_deprecated/empathy-map/workflow.md', name: 'Emma workflow (legacy)' },
-    { path: '_bmad/bme/_vortex/workflows/_deprecated/wireframe/workflow.md', name: 'Wade workflow (legacy)' },
     { path: '_bmad/bme/_vortex/config.yaml', name: 'Configuration file' },
   ];
 
   let allChecksPass = true;
   checks.forEach(check => {
-    const fullPath = path.join(targetDir, check.path);
+    const fullPath = path.join(projectRoot, check.path);
     if (fs.existsSync(fullPath)) {
       console.log(`${GREEN}  ✓${RESET} ${check.name}`);
     } else {
@@ -250,24 +141,6 @@ function verifyInstallation() {
   console.log(`${GREEN}  ✓${RESET} All files installed successfully`);
 }
 
-function copyUserGuides() {
-  console.log(`${CYAN}[6/6]${RESET} Installing user guides...`);
-
-  const sourceDir = path.join(__dirname, '..', '_bmad-output', 'vortex-artifacts');
-  const targetDir = path.join(process.cwd(), '_bmad-output', 'vortex-artifacts');
-
-  // Copy user guides if they exist
-  const guides = ['EMMA-USER-GUIDE.md', 'WADE-USER-GUIDE.md'];
-  guides.forEach(guide => {
-    const sourcePath = path.join(sourceDir, guide);
-    if (fs.existsSync(sourcePath)) {
-      fs.copyFileSync(sourcePath, path.join(targetDir, guide));
-    }
-  });
-
-  console.log(`${GREEN}  ✓${RESET} User guides installed`);
-}
-
 function printSuccess() {
   console.log('');
   console.log(`${GREEN}${BOLD}╔════════════════════════════════════════════════════╗${RESET}`);
@@ -289,51 +162,24 @@ function printSuccess() {
   console.log('  Activate Wade:');
   console.log(`  ${CYAN}cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md${RESET}`);
   console.log('');
-  console.log(`${YELLOW}Note: User guides being updated for v1.2.0${RESET}`);
-  console.log('');
-}
-
-function cleanupLegacyFiles() {
-  console.log(`${CYAN}  →${RESET} Cleaning up legacy files...`);
-
-  // Remove _designos directory (pre-Vortex structure) from all possible locations
-  const legacyPaths = [
-    path.join(process.cwd(), '_bmad', 'bme', '_designos'),
-    path.join(process.cwd(), '_bmad', '_designos'),
-  ];
-
-  for (const legacyPath of legacyPaths) {
-    if (fs.existsSync(legacyPath)) {
-      fs.removeSync(legacyPath);
-      console.log(`${GREEN}    ✓${RESET} Removed legacy directory: ${path.relative(process.cwd(), legacyPath)}`);
-    }
-  }
-
-  // Remove deprecated agent files from _vortex/agents
-  const agentsDir = path.join(process.cwd(), '_bmad', 'bme', '_vortex', 'agents');
-  const deprecatedAgents = ['empathy-mapper.md', 'wireframe-designer.md'];
-
-  for (const agent of deprecatedAgents) {
-    const agentPath = path.join(agentsDir, agent);
-    if (fs.existsSync(agentPath)) {
-      fs.removeSync(agentPath);
-      console.log(`${GREEN}    ✓${RESET} Removed deprecated agent: ${agent}`);
-    }
-  }
-
-  console.log(`${GREEN}  ✓${RESET} Legacy cleanup complete`);
 }
 
 async function main() {
   try {
+    const projectRoot = process.cwd();
+
     printBanner();
-    checkPrerequisites();
-    copyAllAgentFiles();
-    cleanupLegacyFiles();
-    updateConfig();
-    createOutputDirectory();
-    verifyInstallation();
-    copyUserGuides();
+    checkPrerequisites(projectRoot);
+    archiveDeprecatedWorkflows(projectRoot);
+    createAgentManifest(projectRoot);
+    createOutputDirectory(projectRoot);
+
+    // Use refreshInstallation for agents, workflows, config, and user guides
+    console.log(`${CYAN}[5/6]${RESET} Installing agents, workflows, config, and guides...`);
+    await refreshInstallation(projectRoot, { backupGuides: false });
+    console.log(`${GREEN}  ✓${RESET} Installation refreshed`);
+
+    verifyInstallation(projectRoot);
     printSuccess();
   } catch (error) {
     console.error(`${RED}✗ Installation failed:${RESET}`, error.message);

package/scripts/postinstall.js

@@ -27,9 +27,12 @@ async function main() {
     const versionDetector = require('./update/lib/version-detector');
     const registry = require('./update/migrations/registry');
 
-    const currentVersion = versionDetector.getCurrentVersion();
+    const { findProjectRoot, compareVersions } = require('./update/lib/utils');
+    const projectRoot = findProjectRoot();
+
+    const currentVersion = versionDetector.getCurrentVersion(projectRoot);
     const targetVersion = versionDetector.getTargetVersion();
-    const scenario = versionDetector.detectInstallationScenario();
+    const scenario = versionDetector.detectInstallationScenario(projectRoot);
 
     // Fresh install
     if (scenario === 'fresh' || !currentVersion) {
@@ -52,7 +55,7 @@ async function main() {
     }
 
     // Upgrade detected
-    if (versionDetector.compareVersions(currentVersion, targetVersion) < 0) {
+    if (compareVersions(currentVersion, targetVersion) < 0) {
       console.log(`${YELLOW}${BOLD}⚠ UPGRADE DETECTED${RESET}`);
       console.log('');
       console.log(`  Current version: ${RED}${currentVersion}${RESET}`);
@@ -60,7 +63,7 @@ async function main() {
       console.log('');
 
       // Check for breaking changes
-      const breakingChanges = registry.getBreakingChanges(currentVersion, targetVersion);
+      const breakingChanges = registry.getBreakingChanges(currentVersion);
       if (breakingChanges.length > 0) {
         console.log(`${RED}${BOLD}  ⚠ Breaking changes detected!${RESET}`);
         console.log('');
@@ -83,7 +86,7 @@ async function main() {
     }
 
     // Downgrade (shouldn't happen normally)
-    if (versionDetector.compareVersions(currentVersion, targetVersion) > 0) {
+    if (compareVersions(currentVersion, targetVersion) > 0) {
       console.log(`${YELLOW}Note: Package version (${targetVersion}) is older than installed version (${currentVersion})${RESET}`);
       console.log('');
       return;
@@ -95,8 +98,8 @@ async function main() {
     console.log(`  ${CYAN}npx bmad-install-agents${RESET}  - Install all agents (Emma + Wade)`);
     console.log('');
     console.log('Or install individually:');
-    console.log(`  ${CYAN}npx bmad-install-emma${RESET}    - Install Emma (empathy-mapper)`);
-    console.log(`  ${CYAN}npx bmad-install-wade${RESET}    - Install Wade (wireframe-designer)`);
+    console.log(`  ${CYAN}npx bmad-install-emma${RESET}    - Install Emma (contextualization-expert)`);
+    console.log(`  ${CYAN}npx bmad-install-wade${RESET}    - Install Wade (lean-experiments-specialist)`);
     console.log('');
   }
 }

package/scripts/update/bmad-migrate.js

@@ -2,6 +2,9 @@
 
 const chalk = require('chalk');
 const registry = require('./migrations/registry');
+const backupManager = require('./lib/backup-manager');
+const { refreshInstallation } = require('./lib/refresh-installation');
+const { findProjectRoot } = require('./lib/utils');
 
 /**
  * BMAD-Enhanced Migrate CLI
@@ -11,6 +14,15 @@ const registry = require('./migrations/registry');
 async function main() {
   const args = process.argv.slice(2);
 
+  // Validate project root
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.error('');
+    console.error(chalk.red('Not in a BMAD project. Could not find _bmad/ directory.'));
+    console.error('');
+    process.exit(1);
+  }
+
   // No args - show available migrations
   if (args.length === 0) {
     showAvailableMigrations();
@@ -32,6 +44,15 @@ async function main() {
     process.exit(1);
   }
 
+  // Check if already applied
+  const configPath = require('path').join(projectRoot, '_bmad/bme/_vortex/config.yaml');
+  if (registry.hasMigrationBeenApplied(migrationName, configPath)) {
+    console.log('');
+    console.log(chalk.yellow(`Migration '${migrationName}' has already been applied.`));
+    console.log('');
+    process.exit(0);
+  }
+
   // Load migration module
   if (!migration.module) {
     try {
@@ -44,29 +65,61 @@ async function main() {
     }
   }
 
-  // Run migration
+  // Run migration with backup and refresh
   console.log('');
   console.log(chalk.cyan.bold(`Running migration: ${migration.name}`));
   console.log(chalk.gray(migration.description));
   console.log('');
 
+  let backupMetadata = null;
+
   try {
-    const changes = await migration.module.apply();
+    // Create backup before running delta
+    console.log(chalk.cyan('Creating backup...'));
+    backupMetadata = await backupManager.createBackup('manual', projectRoot);
+    console.log(chalk.green(`✓ Backup created: ${require('path').basename(backupMetadata.backup_dir)}`));
+    console.log('');
+
+    // Run the delta
+    const changes = await migration.module.apply(projectRoot);
 
     console.log('');
-    console.log(chalk.green.bold('✓ Migration completed'));
+    console.log(chalk.green.bold('✓ Migration delta completed'));
     console.log('');
-    console.log(chalk.cyan('Changes:'));
+    console.log(chalk.cyan('Delta changes:'));
     changes.forEach(change => {
       console.log(chalk.gray(`  - ${change}`));
     });
     console.log('');
 
+    // Refresh installation after delta
+    console.log(chalk.cyan('Refreshing installation files...'));
+    const refreshChanges = await refreshInstallation(projectRoot);
+    console.log(chalk.green('✓ Installation refreshed'));
+    console.log('');
+
   } catch (error) {
     console.error('');
     console.error(chalk.red.bold('✗ Migration failed'));
     console.error(chalk.red(error.message));
     console.error('');
+
+    // Rollback if we have a backup
+    if (backupMetadata) {
+      console.log(chalk.yellow('Restoring from backup...'));
+      try {
+        await backupManager.restoreBackup(backupMetadata, projectRoot);
+        console.log(chalk.green('✓ Installation restored from backup'));
+        console.log('');
+      } catch (restoreError) {
+        console.error(chalk.red('✗ Restore failed!'));
+        console.error(chalk.red(restoreError.message));
+        console.error('');
+        console.error(chalk.yellow(`Manual restore may be needed from: ${backupMetadata.backup_dir}`));
+        console.error('');
+      }
+    }
+
     if (error.stack) {
       console.error(chalk.gray(error.stack));
       console.error('');
@@ -95,7 +148,7 @@ function showAvailableMigrations() {
     const breaking = m.breaking ? chalk.red('[BREAKING]') : chalk.green('[SAFE]');
     console.log(`  ${index + 1}. ${chalk.cyan(m.name)} ${breaking}`);
     console.log(`     ${chalk.gray(m.description)}`);
-    console.log(`     ${chalk.gray(`${m.fromVersion} → ${m.toVersion}`)}`);
+    console.log(`     ${chalk.gray(`From: ${m.fromVersion}`)}`);
     console.log('');
   });
 

package/scripts/update/bmad-update.js

@@ -5,6 +5,7 @@ const chalk = require('chalk');
 const versionDetector = require('./lib/version-detector');
 const migrationRunner = require('./lib/migration-runner');
 const registry = require('./migrations/registry');
+const { findProjectRoot } = require('./lib/utils');
 
 /**
  * BMAD-Enhanced Update CLI
@@ -15,7 +16,6 @@ async function main() {
   const args = process.argv.slice(2);
   const dryRun = args.includes('--dry-run');
   const yes = args.includes('--yes') || args.includes('-y');
-  const force = args.includes('--force');
   const verbose = args.includes('--verbose') || args.includes('-v');
 
   // Header
@@ -25,10 +25,20 @@ async function main() {
   console.log(chalk.bold.magenta('╚════════════════════════════════════════╝'));
   console.log('');
 
+  // Validate project root
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log(chalk.red('Not in a BMAD project. Could not find _bmad/ directory.'));
+    console.log('');
+    console.log('Run: ' + chalk.cyan('npx bmad-install-agents'));
+    console.log('');
+    process.exit(1);
+  }
+
   // 1. Detect current state
-  const currentVersion = versionDetector.getCurrentVersion();
+  const currentVersion = versionDetector.getCurrentVersion(projectRoot);
   const targetVersion = versionDetector.getTargetVersion();
-  const scenario = versionDetector.detectInstallationScenario();
+  const scenario = versionDetector.detectInstallationScenario(projectRoot);
 
   // Handle different scenarios
   if (scenario === 'fresh') {
@@ -88,7 +98,7 @@ async function main() {
   console.log(`  To:   ${chalk.green(targetVersion)}`);
   console.log('');
 
-  const migrations = registry.getMigrationsFor(currentVersion, targetVersion);
+  const migrations = registry.getMigrationsFor(currentVersion);
 
   if (migrations.length === 0) {
     console.log(chalk.yellow('No migrations needed (versions compatible)'));
@@ -104,7 +114,7 @@ async function main() {
   console.log('');
 
   // 3. Show breaking changes warning
-  const breakingChanges = registry.getBreakingChanges(currentVersion, targetVersion);
+  const breakingChanges = registry.getBreakingChanges(currentVersion);
   if (breakingChanges.length > 0) {
     console.log(chalk.red.bold('⚠ BREAKING CHANGES:'));
     breakingChanges.forEach(change => {
@@ -119,7 +129,7 @@ async function main() {
     console.log('');
 
     try {
-      await migrationRunner.runMigrations(currentVersion, targetVersion, { dryRun: true, verbose });
+      await migrationRunner.runMigrations(currentVersion, { dryRun: true, verbose });
     } catch (error) {
       console.error(chalk.red('Error during preview:'), error.message);
       process.exit(1);
@@ -148,7 +158,7 @@ async function main() {
   console.log(chalk.cyan.bold('Starting migration...'));
 
   try {
-    const result = await migrationRunner.runMigrations(currentVersion, targetVersion, { verbose });
+    const result = await migrationRunner.runMigrations(currentVersion, { verbose });
 
     // 7. Show success report
     console.log('');

package/scripts/update/bmad-version.js

@@ -5,6 +5,7 @@ const path = require('path');
 const chalk = require('chalk');
 const yaml = require('js-yaml');
 const versionDetector = require('./lib/version-detector');
+const { findProjectRoot, compareVersions } = require('./lib/utils');
 
 /**
  * BMAD-Enhanced Version CLI
@@ -12,14 +13,26 @@ const versionDetector = require('./lib/version-detector');
  */
 
 async function main() {
-  const currentVersion = versionDetector.getCurrentVersion();
+  const projectRoot = findProjectRoot();
   const targetVersion = versionDetector.getTargetVersion();
-  const scenario = versionDetector.detectInstallationScenario();
 
   console.log('');
   console.log(chalk.bold('BMAD-Enhanced Version Information'));
   console.log('');
 
+  // Not in a BMAD project
+  if (!projectRoot) {
+    console.log(chalk.yellow('Status:           Not in a BMAD project'));
+    console.log(`Package version:  ${chalk.cyan(targetVersion)}`);
+    console.log('');
+    console.log('Run: ' + chalk.cyan('npx bmad-install-agents'));
+    console.log('');
+    return;
+  }
+
+  const currentVersion = versionDetector.getCurrentVersion(projectRoot);
+  const scenario = versionDetector.detectInstallationScenario(projectRoot);
+
   // Fresh install - not installed yet
   if (scenario === 'fresh') {
     console.log(chalk.yellow('Status:           Not installed'));
@@ -64,7 +77,7 @@ async function main() {
   // Status
   if (currentVersion === targetVersion) {
     console.log(chalk.green('Status: ✓ Up to date'));
-  } else if (versionDetector.compareVersions(currentVersion, targetVersion) < 0) {
+  } else if (compareVersions(currentVersion, targetVersion) < 0) {
     console.log(chalk.yellow('Status: ⚠ Update available'));
     console.log('');
     console.log('Run: ' + chalk.cyan('npx bmad-update --dry-run') + ' (to preview)');
@@ -74,7 +87,7 @@ async function main() {
   }
 
   // Show migration history
-  const migrationHistory = await getMigrationHistory();
+  const migrationHistory = await getMigrationHistory(projectRoot);
   if (migrationHistory && migrationHistory.length > 0) {
     console.log('');
     console.log(chalk.cyan('Migration History:'));
@@ -94,10 +107,11 @@ async function main() {
 
 /**
  * Get migration history from config.yaml
+ * @param {string} projectRoot - Project root
  * @returns {Promise<Array|null>} Migration history or null
  */
-async function getMigrationHistory() {
-  const configPath = path.join(process.cwd(), '_bmad/bme/_vortex/config.yaml');
+async function getMigrationHistory(projectRoot) {
+  const configPath = path.join(projectRoot, '_bmad/bme/_vortex/config.yaml');
 
   if (!fs.existsSync(configPath)) {
     return null;