convoke-agents 2.0.0

package/scripts/update/migrations/1.0.x-to-1.3.0.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Migration: 1.0.x → current version
+ * BREAKING CHANGES (delta only):
+ * - Archive empathy-map and wireframe workflows to _deprecated/
+ * - Remove legacy _designos directory
+ * - Update agent manifest (rename empathy-mapper/wireframe-designer entries)
+ *
+ * Note: Agent files, workflows, config, and guides are handled by refreshInstallation().
+ */
+
+module.exports = {
+  name: '1.0.x-to-1.3.0',
+  fromVersion: '1.0.x',
+  breaking: true,
+
+  async preview() {
+    return {
+      actions: [
+        'BREAKING: Move empathy-map workflow to _deprecated/',
+        'BREAKING: Move wireframe workflow to _deprecated/',
+        'Remove legacy _designos directory (pre-Vortex structure)',
+        'Update agent-manifest.csv (rename empathy-mapper/wireframe-designer entries)'
+      ]
+    };
+  },
+
+  /**
+   * Apply delta-only migration logic.
+   * @param {string} projectRoot - Absolute path to project root
+   * @returns {Promise<Array<string>>} List of changes made
+   */
+  async apply(projectRoot) {
+    const changes = [];
+    const targetDir = path.join(projectRoot, '_bmad/bme/_vortex');
+
+    // 1. Archive old empathy-map workflow
+    const archived1 = await moveToDeprecated(targetDir, 'empathy-map');
+    if (archived1) changes.push('Archived empathy-map workflow to _deprecated/');
+
+    // 2. Archive wireframe workflow
+    const archived2 = await moveToDeprecated(targetDir, 'wireframe');
+    if (archived2) changes.push('Archived wireframe workflow to _deprecated/');
+
+    // 3. Remove legacy _designos directories
+    await removeOldDesignosDirectory(projectRoot);
+    changes.push('Cleaned up legacy _designos directory');
+
+    // 4. Update agent manifest (rename old agent IDs)
+    await updateAgentManifest(projectRoot);
+    changes.push('Updated agent manifest');
+
+    return changes;
+  }
+};
+
+/**
+ * Move workflow to _deprecated directory
+ * @param {string} targetDir - Target vortex directory
+ * @param {string} workflowName - Name of workflow to deprecate
+ * @returns {Promise<boolean>} True if moved, false if not found
+ */
+async function moveToDeprecated(targetDir, workflowName) {
+  const workflowsDir = path.join(targetDir, 'workflows');
+  const workflowPath = path.join(workflowsDir, workflowName);
+  const deprecatedPath = path.join(workflowsDir, '_deprecated', workflowName);
+
+  if (fs.existsSync(workflowPath)) {
+    await fs.ensureDir(path.join(workflowsDir, '_deprecated'));
+    await fs.move(workflowPath, deprecatedPath, { overwrite: true });
+    console.log(`    Moved ${workflowName} → _deprecated/`);
+    return true;
+  }
+
+  console.log(`    ${workflowName} not found (may already be deprecated)`);
+  return false;
+}
+
+/**
+ * Update agent manifest CSV - rename old agent IDs
+ * @param {string} projectRoot - Absolute path to project root
+ */
+async function updateAgentManifest(projectRoot) {
+  const manifestPath = path.join(projectRoot, '_bmad/_config/agent-manifest.csv');
+
+  if (!fs.existsSync(manifestPath)) {
+    console.log('    Agent manifest not found, skipping update');
+    return;
+  }
+
+  let manifestContent = await fs.readFile(manifestPath, 'utf8');
+
+  manifestContent = manifestContent.replace(/empathy-mapper/g, 'contextualization-expert');
+  manifestContent = manifestContent.replace(/Empathy Mapping Specialist/g, 'Contextualization Expert');
+  manifestContent = manifestContent.replace(/wireframe-designer/g, 'lean-experiments-specialist');
+  manifestContent = manifestContent.replace(/Wireframe Designer/g, 'Lean Experiments Specialist');
+
+  await fs.writeFile(manifestPath, manifestContent, 'utf8');
+  console.log('    Updated agent manifest');
+}
+
+/**
+ * Remove old _designos directory (pre-Vortex structure)
+ * @param {string} projectRoot - Absolute path to project root
+ */
+async function removeOldDesignosDirectory(projectRoot) {
+  const legacyPaths = [
+    path.join(projectRoot, '_bmad/bme/_designos'),
+    path.join(projectRoot, '_bmad/_designos'),
+  ];
+
+  let removed = false;
+  for (const designosPath of legacyPaths) {
+    if (fs.existsSync(designosPath)) {
+      await fs.remove(designosPath);
+      console.log(`    Removed legacy directory: ${path.relative(projectRoot, designosPath)}`);
+      removed = true;
+    }
+  }
+
+  if (!removed) {
+    console.log('    No legacy _designos directory found (OK)');
+  }
+}

package/scripts/update/migrations/1.1.x-to-1.3.0.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * Migration: 1.1.x → current version
+ * No-op delta - all file updates handled by refreshInstallation().
+ * No version-specific changes needed for 1.1.x users.
+ */
+
+module.exports = {
+  name: '1.1.x-to-1.3.0',
+  fromVersion: '1.1.x',
+  breaking: false,
+
+  async preview() {
+    return {
+      actions: [
+        'No version-specific changes needed (refresh handles all updates)'
+      ]
+    };
+  },
+
+  /**
+   * @param {string} projectRoot - Absolute path to project root
+   * @returns {Promise<Array<string>>} List of changes made
+   */
+  async apply(_projectRoot) {
+    return ['No version-specific delta needed'];
+  }
+};

package/scripts/update/migrations/1.2.x-to-1.3.0.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * Migration: 1.2.x → current version
+ * No-op delta - all file updates handled by refreshInstallation().
+ * No version-specific changes needed for 1.2.x users.
+ */
+
+module.exports = {
+  name: '1.2.x-to-1.3.0',
+  fromVersion: '1.2.x',
+  breaking: false,
+
+  async preview() {
+    return {
+      actions: [
+        'No version-specific changes needed (refresh handles all updates)'
+      ]
+    };
+  },
+
+  /**
+   * @param {string} projectRoot - Absolute path to project root
+   * @returns {Promise<Array<string>>} List of changes made
+   */
+  async apply(_projectRoot) {
+    return ['No version-specific delta needed'];
+  }
+};

package/scripts/update/migrations/1.3.x-to-1.5.0.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * Migration: 1.3.x → current version (v1.5.0)
+ * No-op delta - all file updates handled by refreshInstallation().
+ * Wave 2 adds Isla, Max, and 6 new workflows via refresh.
+ */
+
+module.exports = {
+  name: '1.3.x-to-1.5.0',
+  fromVersion: '1.3.x',
+  breaking: false,
+
+  async preview() {
+    return {
+      actions: [
+        'No version-specific changes needed (refresh handles all updates)',
+        'Adds: Isla (discovery-empathy-expert) agent',
+        'Adds: Max (learning-decision-expert) agent',
+        'Adds: empathy-map, user-interview, user-discovery workflows (Isla)',
+        'Adds: learning-card, pivot-patch-persevere, vortex-navigation workflows (Max)'
+      ]
+    };
+  },
+
+  async apply(_projectRoot) {
+    return ['No version-specific delta needed'];
+  }
+};

package/scripts/update/migrations/1.4.x-to-1.5.0.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * Migration: 1.4.x → current version (v1.5.0)
+ * No-op delta - all file updates handled by refreshInstallation().
+ * Wave 2 adds Isla, Max, and 6 new workflows via refresh.
+ */
+
+module.exports = {
+  name: '1.4.x-to-1.5.0',
+  fromVersion: '1.4.x',
+  breaking: false,
+
+  async preview() {
+    return {
+      actions: [
+        'No version-specific changes needed (refresh handles all updates)',
+        'Adds: Isla (discovery-empathy-expert) agent',
+        'Adds: Max (learning-decision-expert) agent',
+        'Adds: empathy-map, user-interview, user-discovery workflows (Isla)',
+        'Adds: learning-card, pivot-patch-persevere, vortex-navigation workflows (Max)'
+      ]
+    };
+  },
+
+  async apply(_projectRoot) {
+    return ['No version-specific delta needed'];
+  }
+};

package/scripts/update/migrations/1.5.x-to-1.6.0.js

@@ -0,0 +1,95 @@
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const { AGENTS, AGENT_IDS, WAVE3_WORKFLOW_NAMES } = require('../lib/agent-registry');
+
+/**
+ * Migration: 1.5.x → current version (v1.6.0)
+ * Appends Wave 3 agents and workflows to existing config.
+ * refreshInstallation() handles file copying (agents, workflows, guides).
+ *
+ * Wave 3 agents: Mila (Synthesize), Liam (Hypothesize), Noah (Sensitize)
+ * Wave 3 workflows: 9 new workflows (3 per agent)
+ */
+
+// Wave 1/2 agent IDs (pre-1.6.0)
+const WAVE12_AGENT_IDS = new Set([
+  'contextualization-expert',
+  'discovery-empathy-expert',
+  'lean-experiments-specialist',
+  'learning-decision-expert'
+]);
+
+// Wave 3 agent IDs derived from registry; workflow names from WAVE3_WORKFLOW_NAMES set
+const WAVE3_AGENT_IDS = AGENT_IDS.filter(id => !WAVE12_AGENT_IDS.has(id));
+const WAVE3_WORKFLOWS = [...WAVE3_WORKFLOW_NAMES];
+
+module.exports = {
+  name: '1.5.x-to-1.6.0',
+  fromVersion: '1.5.x',
+  breaking: false,
+
+  async preview() {
+    const wave3Agents = AGENTS.filter(a => WAVE3_AGENT_IDS.includes(a.id));
+    const agentDesc = wave3Agents.map(a => `${a.name} (${a.id})`).join(', ');
+    return {
+      actions: [
+        `Append Wave 3 agents to config: ${agentDesc}`,
+        `Append ${WAVE3_WORKFLOWS.length} Wave 3 workflows to config: ${WAVE3_WORKFLOWS.join(', ')}`,
+        'File copying handled by refreshInstallation()'
+      ]
+    };
+  },
+
+  /**
+   * Apply migration: append Wave 3 agents and workflows to config.
+   * Idempotent — skips entries already present.
+   * @param {string} projectRoot - Absolute path to project root
+   * @returns {Promise<Array<string>>} List of changes made
+   */
+  async apply(projectRoot) {
+    const changes = [];
+    const configPath = path.join(projectRoot, '_bmad', 'bme', '_vortex', 'config.yaml');
+
+    if (!await fs.pathExists(configPath)) {
+      changes.push('No config.yaml found — refreshInstallation will create it');
+      return changes;
+    }
+
+    const configContent = await fs.readFile(configPath, 'utf8');
+    const config = yaml.load(configContent) || {};
+
+    // Ensure arrays exist
+    if (!Array.isArray(config.agents)) {
+      config.agents = [];
+    }
+    if (!Array.isArray(config.workflows)) {
+      config.workflows = [];
+    }
+
+    // Append missing Wave 3 agents (idempotent)
+    const newAgents = WAVE3_AGENT_IDS.filter(id => !config.agents.includes(id));
+    if (newAgents.length > 0) {
+      config.agents.push(...newAgents);
+      changes.push(`Appended ${newAgents.length} Wave 3 agent(s): ${newAgents.join(', ')}`);
+    } else {
+      changes.push('Wave 3 agents already present in config');
+    }
+
+    // Append missing Wave 3 workflows (idempotent)
+    const newWorkflows = WAVE3_WORKFLOWS.filter(name => !config.workflows.includes(name));
+    if (newWorkflows.length > 0) {
+      config.workflows.push(...newWorkflows);
+      changes.push(`Appended ${newWorkflows.length} Wave 3 workflow(s): ${newWorkflows.join(', ')}`);
+    } else {
+      changes.push('Wave 3 workflows already present in config');
+    }
+
+    // Write updated config back
+    if (newAgents.length > 0 || newWorkflows.length > 0) {
+      await fs.writeFile(configPath, yaml.dump(config, { indent: 2, lineWidth: -1, noRefs: true }), 'utf8');
+    }
+
+    return changes;
+  }
+};

package/scripts/update/migrations/1.6.x-to-1.7.0.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * Migration: 1.6.x → current version (v1.7.0)
+ * No-op delta - all file updates handled by refreshInstallation().
+ * Wave 4: production-quality workflow steps, updated guides, config-merger
+ * smart-merge, docs-audit tool. No schema or structural changes.
+ */
+
+module.exports = {
+  name: '1.6.x-to-1.7.0',
+  fromVersion: '1.6.x',
+  breaking: false,
+
+  async preview() {
+    return {
+      actions: [
+        'No version-specific changes needed (refresh handles all updates)',
+        'Updates: 18 workflow step files (lean-experiment, proof-of-concept, proof-of-value)',
+        'Updates: 7 user guides with reordered invocation methods',
+        'Updates: config-merger with smart-merge for user-added agents/workflows'
+      ]
+    };
+  },
+
+  async apply(_projectRoot) {
+    return ['No version-specific delta needed'];
+  }
+};

package/scripts/update/migrations/1.7.x-to-2.0.0.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * Migration: 1.7.x -> current version (v2.0.0)
+ * No-op delta - all file updates handled by refreshInstallation().
+ * Product rename: BMAD-Enhanced -> Convoke.
+ * CLI commands renamed from bmad-* to convoke-*.
+ * Internal _bmad/ directory structure preserved.
+ */
+
+module.exports = {
+  name: '1.7.x-to-2.0.0',
+  fromVersion: '1.7.x',
+  breaking: true,
+
+  async preview() {
+    return {
+      actions: [
+        'Product renamed from BMAD-Enhanced to Convoke',
+        'npm package: bmad-enhanced -> convoke-agents',
+        'CLI commands renamed: bmad-install-vortex-agents -> convoke-install-vortex, bmad-install-agents -> convoke-install, bmad-update -> convoke-update, bmad-version -> convoke-version, bmad-migrate -> convoke-migrate, bmad-doctor -> convoke-doctor',
+        'Internal _bmad/ directory structure preserved (no data loss)',
+        'No version-specific changes needed (refresh handles all updates)'
+      ]
+    };
+  },
+
+  async apply(_projectRoot) {
+    return ['No version-specific delta needed — refreshInstallation handles file updates'];
+  }
+};

package/scripts/update/migrations/registry.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const { compareVersions } = require('../lib/utils');
+
+/**
+ * Migration Registry for Convoke
+ *
+ * APPEND-ONLY: Add new migrations at the bottom. Never edit old entries.
+ * No toVersion needed - target is always the current package version at runtime.
+ */
+
+const MIGRATIONS = [
+  {
+    name: '1.0.x-to-1.3.0',
+    fromVersion: '1.0.x',
+    breaking: true,
+    description: 'Archive deprecated empathy-map/wireframe workflows, rename agents in manifest',
+    module: null
+  },
+  {
+    name: '1.1.x-to-1.3.0',
+    fromVersion: '1.1.x',
+    breaking: false,
+    description: 'No-op delta (refresh handles all file updates)',
+    module: null
+  },
+  {
+    name: '1.2.x-to-1.3.0',
+    fromVersion: '1.2.x',
+    breaking: false,
+    description: 'No-op delta (refresh handles all file updates)',
+    module: null
+  },
+  {
+    name: '1.3.x-to-1.5.0',
+    fromVersion: '1.3.x',
+    breaking: false,
+    description: 'No-op delta (refresh handles Wave 2 agents and workflows)',
+    module: null
+  },
+  {
+    name: '1.4.x-to-1.5.0',
+    fromVersion: '1.4.x',
+    breaking: false,
+    description: 'No-op delta (refresh handles Wave 2 agents and workflows)',
+    module: null
+  },
+  {
+    name: '1.5.x-to-1.6.0',
+    fromVersion: '1.5.x',
+    breaking: false,
+    description: 'Add Wave 3 agents (Mila, Liam, Noah) and 9 workflows to config',
+    module: null
+  },
+  {
+    name: '1.6.x-to-1.7.0',
+    fromVersion: '1.6.x',
+    breaking: false,
+    description: 'Quality & onboarding (production workflow steps, updated guides, smart-merge)',
+    module: null
+  },
+  {
+    name: '1.7.x-to-2.0.0',
+    fromVersion: '1.7.x',
+    breaking: true,
+    description: 'Product rename: BMAD-Enhanced -> Convoke. CLI commands renamed from bmad-* to convoke-*. _bmad/ directory preserved.',
+    module: null
+  }
+  // Future migrations: append here. Only add delta logic for version-specific changes.
+];
+
+/**
+ * Get migrations applicable for upgrading from a given version.
+ * Target version is always the current package version (read at runtime).
+ *
+ * @param {string} fromVersion - Current installed version (e.g., "1.0.5")
+ * @returns {Array} List of applicable migrations with loaded modules
+ */
+function getMigrationsFor(fromVersion) {
+  const applicable = [];
+
+  for (const migration of MIGRATIONS) {
+    if (matchesVersionRange(fromVersion, migration.fromVersion)) {
+      // Lazy load the migration module
+      if (!migration.module) {
+        try {
+          migration.module = require(`./${migration.name}`);
+        } catch (error) {
+          console.error(`Failed to load migration ${migration.name}:`, error.message);
+          continue;
+        }
+      }
+
+      applicable.push(migration);
+    }
+  }
+
+  // Sort by version order (oldest fromVersion first)
+  applicable.sort((a, b) => {
+    const aV = a.fromVersion.replace('.x', '.0');
+    const bV = b.fromVersion.replace('.x', '.0');
+    return compareVersions(aV, bV);
+  });
+
+  return applicable;
+}
+
+/**
+ * Check if migration has already been applied
+ * @param {string} migrationName - Name of migration
+ * @param {string} configPath - Path to config.yaml
+ * @returns {boolean} True if already applied
+ */
+function hasMigrationBeenApplied(migrationName, configPath) {
+  if (!fs.existsSync(configPath)) {
+    return false;
+  }
+
+  try {
+    const configContent = fs.readFileSync(configPath, 'utf8');
+    const config = yaml.load(configContent);
+
+    if (!config.migration_history || !Array.isArray(config.migration_history)) {
+      return false;
+    }
+
+    return config.migration_history.some(entry =>
+      entry.migrations_applied && entry.migrations_applied.includes(migrationName)
+    );
+  } catch (error) {
+    console.warn('Could not check migration history:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Get breaking changes for upgrading from a given version.
+ * @param {string} fromVersion - Current installed version
+ * @returns {Array<string>} List of breaking change descriptions
+ */
+function getBreakingChanges(fromVersion) {
+  const migrations = getMigrationsFor(fromVersion);
+  const breakingChanges = [];
+
+  for (const migration of migrations) {
+    if (migration.breaking) {
+      breakingChanges.push(migration.description);
+    }
+  }
+
+  return breakingChanges;
+}
+
+/**
+ * Match version against version range pattern
+ * @param {string} version - Version to check (e.g., "1.0.5")
+ * @param {string} pattern - Pattern to match (e.g., "1.0.x")
+ * @returns {boolean} True if matches
+ */
+function matchesVersionRange(version, pattern) {
+  if (pattern === version) {
+    return true;
+  }
+
+  // Handle wildcard patterns (e.g., "1.0.x")
+  if (pattern.endsWith('.x')) {
+    const patternParts = pattern.split('.');
+    const versionParts = version.split('.');
+
+    return patternParts[0] === versionParts[0] &&
+           patternParts[1] === versionParts[1];
+  }
+
+  return false;
+}
+
+/**
+ * Get all registered migrations
+ * @returns {Array} All migrations (shallow copy)
+ */
+function getAllMigrations() {
+  return [...MIGRATIONS];
+}
+
+module.exports = {
+  MIGRATIONS,
+  getMigrationsFor,
+  hasMigrationBeenApplied,
+  getBreakingChanges,
+  matchesVersionRange,
+  getAllMigrations
+};