ma-agents 2.22.1 → 3.0.0

package/lib/bmad-extension/skills/sre-gitops-status/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: sre-gitops-status
+description: Monitor GitOps synchronization state and detect drift using ArgoCD or Flux
+type: skill
+triggers:
+  - "gitops status"
+  - "drift detection"
+---
+
+# workflow-gitops-status.md
+# GitOps Status & Drift Detection Workflow
+
+This workflow monitors and reports the synchronization state between your git repository and the cluster using ArgoCD or Flux.
+
+## Instructions
+1.  **Identify Tool**: Detect if ArgoCD or Flux is in use.
+2.  **Sync Status**:
+    -   **ArgoCD**: `argocd app list`, `argocd app get {app_name}`
+    -   **Flux**: `flux get kustomizations`, `flux get helmreleases`
+3.  **Drift Detection**:
+    -   Identify "OutOfSync" resources.
+    -   Compare live state with desired state in git.
+4.  **Action**:
+    -   Offer to trigger a sync: `argocd app sync {app_name}` or `flux reconcile kustomization {name}`.
+    -   Analyze reasons for permanent drift (e.g., manual cluster changes).

package/lib/bmad-extension/skills/sre-gitops-status/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: sre-gitops-status
+module: ma-skills

package/lib/bmad.js

@@ -77,11 +77,20 @@ function buildBmadArgs(ctx) {
 }
 
 async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = process.cwd(), force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
+    // Detect migration need
+    const detection = detectMigrationNeed(projectRoot);
+
+    if (detection.migrate) {
+        const fromLabel = detection.fromVersion === 'unknown' ? 'unknown version' : detection.fromVersion;
+        console.log(chalk.yellow(`  Upgrading BMAD from ${fromLabel} to ${BMAD_TARGET_VERSION}...`));
+        return await runMigration(modules, tools, projectRoot, force, { userName, commLang, docLang, outputFolder });
+    }
+
     const command = buildBmadArgs({
         projectRoot,
         modules,
         tools,
-        action: 'install',
+        action: detection.action,
         userName,
         commLang,
         docLang,
@@ -101,6 +110,63 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
     }
 }
 
+/**
+ * Run the full migration pipeline: backup → update → merge → cleanup.
+ * Rolls back on failure (NFR29).
+ */
+async function runMigration(modules, tools, projectRoot, force, { userName, commLang, docLang, outputFolder }) {
+    // Step 1: Backup existing customizations
+    console.log(chalk.cyan('  Step 1/4: Backing up existing customizations...'));
+    const backedUpFiles = await backupCustomizations(projectRoot);
+
+    // Step 2: Run bmad-method with --action update
+    console.log(chalk.cyan('  Step 2/4: Updating BMAD-METHOD...'));
+    const command = buildBmadArgs({
+        projectRoot,
+        modules,
+        tools,
+        action: 'update',
+        userName,
+        commLang,
+        docLang,
+        outputFolder,
+    });
+
+    await prePopulateBmadCache(force);
+
+    console.log(chalk.gray(`  Running: ${command}`));
+    try {
+        execSync(command, { stdio: 'inherit', cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+    } catch (error) {
+        // Rollback on failure
+        console.error(chalk.red(`  BMAD update failed: ${error.message}`));
+        if (backedUpFiles.length > 0) {
+            console.log(chalk.yellow('  Rolling back — restoring backed-up customizations...'));
+            await restoreCustomizations(projectRoot);
+        }
+        console.error(chalk.red('  Migration aborted. Your project remains on the previous version.'));
+        console.error(chalk.yellow('  Suggestion: Run "npm update bmad-method" manually, then retry installation.'));
+        return false;
+    }
+
+    // Step 3: Merge user customizations
+    if (backedUpFiles.length > 0) {
+        console.log(chalk.cyan('  Step 3/4: Merging user customizations...'));
+        await mergeUserCustomizations(projectRoot);
+    } else {
+        console.log(chalk.gray('  Step 3/4: No customizations to merge'));
+    }
+
+    // Step 4: Clean up legacy artifacts
+    console.log(chalk.cyan('  Step 4/4: Cleaning up legacy artifacts...'));
+    await cleanupLegacyArtifacts(projectRoot);
+
+    await deployMethodology(projectRoot, force);
+
+    console.log(chalk.green(`  Migration to BMAD ${BMAD_TARGET_VERSION} complete!`));
+    return true;
+}
+
 async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = process.cwd(), force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
     const command = buildBmadArgs({
         projectRoot,
@@ -214,6 +280,20 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
         console.log(chalk.cyan('    + Deployed BMAD extension module: ma-agents-skills'));
     }
 
+    // STAGE:CUSTOMIZE — Deploy built-in agent customizations from lib/bmad-customize/
+    // These add critical_actions to the 8 built-in BMM agents (pm, architect, dev, qa,
+    // sm, tech-writer, ux-designer, bmad-master) so they load project skills at startup.
+    // Runs AFTER --custom-content (extension module) and BEFORE quick-update.
+    const customizeSource = path.join(__dirname, 'bmad-customize');
+    if (fs.existsSync(customizeSource)) {
+        await fs.ensureDir(configTargetDir);
+        const customizeFiles = (await fs.readdir(customizeSource)).filter(f => f.endsWith('.customize.yaml'));
+        for (const file of customizeFiles) {
+            await fs.copy(path.join(customizeSource, file), path.join(configTargetDir, file));
+            console.log(chalk.cyan(`    + Applied built-in customization: ${file}`));
+        }
+    }
+
     // STAGE:WORKFLOWS — Apply workflows (AFTER recompile so they persist)
     if (fs.existsSync(workflowSourceDir)) {
         await fs.ensureDir(workflowTargetDir);
@@ -439,6 +519,458 @@ async function prePopulateBmadCache(force = false) {
     }
 }
 
+// ── Migration constants ─────────────────────────────────────────────────────
+
+const BMAD_TARGET_VERSION = '6.2.1';
+const BMAD_MIGRATION_THRESHOLD = '6.2.0'; // versions below this need migration
+const BACKUP_DIR_NAME = '.backup-pre-migration';
+
+/**
+ * Standard critical_actions injected by ma-agents (used to distinguish
+ * user-added entries from standard ones during merge).
+ */
+const STANDARD_CRITICAL_ACTIONS = [
+    'Read the skills MANIFEST at {project-root}',
+    'For each skill marked always_load: true, read the skill file completely',
+    'If _bmad-output/project-context.md exists, read it completely',
+    'Follow all skill directives and project-context rules during this session',
+];
+
+// ── Migration functions ─────────────────────────────────────────────────────
+
+/**
+ * Compare two semver-style version strings (X.Y.Z only).
+ * Returns -1 if a < b, 0 if a == b, 1 if a > b.
+ *
+ * **Limitation:** Only supports strict X.Y.Z numeric versions.
+ * Pre-release suffixes (e.g. "6.2.1-beta.1") are ignored — the hyphen
+ * and everything after it will be parsed as NaN by Number(), which
+ * falls back to 0 via the `|| 0` guard. Two-segment versions like
+ * "6.2" are handled by treating the missing patch as 0.
+ *
+ * @param {string} a - First version string (X.Y.Z)
+ * @param {string} b - Second version string (X.Y.Z)
+ * @returns {number} -1 | 0 | 1
+ */
+function compareVersions(a, b) {
+    const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+    if (a && !SEMVER_RE.test(a)) {
+        console.log(chalk.yellow(`  Warning: compareVersions received non-standard version "${a}" — only X.Y.Z is fully supported`));
+    }
+    if (b && !SEMVER_RE.test(b)) {
+        console.log(chalk.yellow(`  Warning: compareVersions received non-standard version "${b}" — only X.Y.Z is fully supported`));
+    }
+    const pa = (a || '0.0.0').split('.').map(Number);
+    const pb = (b || '0.0.0').split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const va = pa[i] || 0;
+        const vb = pb[i] || 0;
+        if (va < vb) return -1;
+        if (va > vb) return 1;
+    }
+    return 0;
+}
+
+/**
+ * Detect whether a migration is needed by inspecting `_bmad/core/config.yaml`.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {{ action: 'install'|'update', migrate: boolean, fromVersion?: string }}
+ */
+function detectMigrationNeed(projectRoot) {
+    const bmadPath = path.join(projectRoot, BMAD_DIR);
+    if (!fs.existsSync(bmadPath)) {
+        return { action: 'install', migrate: false };
+    }
+
+    // _bmad/ exists — try to read version from config.yaml
+    const configPath = path.join(bmadPath, 'core', 'config.yaml');
+    let version = null;
+
+    if (fs.existsSync(configPath)) {
+        try {
+            const content = fs.readFileSync(configPath, 'utf-8');
+            // Simple regex extraction — config.yaml is a simple key: value YAML
+            const match = content.match(/^version:\s*['"]?([^\s'"#]+)/m);
+            if (match) {
+                version = match[1];
+            }
+        } catch {
+            // Cannot read — treat as unknown version
+        }
+    }
+
+    // If _bmad/ exists but no version found (e.g. config.yaml is `{}` or missing),
+    // treat as needing migration since it's likely a pre-6.2.0 install
+    if (!version) {
+        console.log(chalk.yellow('  BMAD version not found in config.yaml — assuming pre-6.2.0 install'));
+        return { action: 'update', migrate: true, fromVersion: 'unknown' };
+    }
+
+    if (compareVersions(version, BMAD_MIGRATION_THRESHOLD) < 0) {
+        return { action: 'update', migrate: true, fromVersion: version };
+    }
+
+    return { action: 'update', migrate: false };
+}
+
+/**
+ * Back up existing customize.yaml files before migration.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {Promise<string[]>} List of backed-up file names
+ */
+async function backupCustomizations(projectRoot) {
+    const configDir = path.join(projectRoot, CONFIG_DIR);
+    const backupDir = path.join(configDir, BACKUP_DIR_NAME);
+
+    if (!fs.existsSync(configDir)) {
+        console.log(chalk.gray('  No _bmad/_config/agents/ directory — nothing to back up'));
+        return [];
+    }
+
+    const files = await fs.readdir(configDir);
+    const customizeFiles = files.filter(f => f.endsWith('.customize.yaml'));
+
+    if (customizeFiles.length === 0) {
+        console.log(chalk.gray('  No customize.yaml files found — nothing to back up'));
+        return [];
+    }
+
+    // Remove previous backup before creating a new one
+    if (fs.existsSync(backupDir)) {
+        await fs.remove(backupDir);
+        console.log(chalk.dim('  Removed previous migration backup'));
+    }
+
+    await fs.ensureDir(backupDir);
+    const backedUp = [];
+
+    for (const file of customizeFiles) {
+        await fs.copy(path.join(configDir, file), path.join(backupDir, file));
+        backedUp.push(file);
+        console.log(chalk.cyan(`    + Backed up: ${file}`));
+    }
+
+    console.log(chalk.green(`  Backed up ${backedUp.length} customize.yaml file(s) to ${BACKUP_DIR_NAME}/`));
+    return backedUp;
+}
+
+/**
+ * Restore backed-up customize.yaml files (rollback on failure).
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {Promise<boolean>} true if restore succeeded
+ */
+async function restoreCustomizations(projectRoot) {
+    const configDir = path.join(projectRoot, CONFIG_DIR);
+    const backupDir = path.join(configDir, BACKUP_DIR_NAME);
+
+    if (!fs.existsSync(backupDir)) {
+        console.log(chalk.yellow('  No backup directory found — cannot restore'));
+        return false;
+    }
+
+    try {
+        const files = await fs.readdir(backupDir);
+        const customizeFiles = files.filter(f => f.endsWith('.customize.yaml'));
+
+        for (const file of customizeFiles) {
+            await fs.copy(path.join(backupDir, file), path.join(configDir, file), { overwrite: true });
+            console.log(chalk.cyan(`    + Restored: ${file}`));
+        }
+
+        console.log(chalk.green(`  Restored ${customizeFiles.length} customize.yaml file(s) from backup`));
+        return true;
+    } catch (err) {
+        console.error(chalk.red(`  Failed to restore customizations: ${err.message}`));
+        return false;
+    }
+}
+
+/**
+ * Check whether a critical_action line is one of the standard ma-agents entries.
+ * Uses a substring match against STANDARD_CRITICAL_ACTIONS patterns.
+ */
+function isStandardCriticalAction(line) {
+    const trimmed = (typeof line === 'string' ? line : '').trim().replace(/^["']|["']$/g, '');
+    return STANDARD_CRITICAL_ACTIONS.some(std => trimmed.includes(std));
+}
+
+/**
+ * Parse a simple YAML customize.yaml file into a structured object.
+ * Returns raw text sections for keys like persona, memories, critical_actions.
+ * This is intentionally simple — only parses the top-level keys we care about.
+ *
+ * @param {string} content - YAML file content
+ * @returns {{ memories: string[], criticalActions: string[], personaLines: string[], raw: string }}
+ */
+function parseCustomizeYaml(content) {
+    const result = {
+        memories: [],
+        criticalActions: [],
+        personaLines: [],
+        raw: content,
+    };
+
+    const lines = content.split('\n');
+    let currentSection = null;
+
+    for (const line of lines) {
+        // Detect top-level keys
+        if (/^memories\s*:/.test(line)) {
+            currentSection = 'memories';
+            continue;
+        } else if (/^critical_actions\s*:/.test(line)) {
+            currentSection = 'criticalActions';
+            continue;
+        } else if (/^persona\s*:/.test(line)) {
+            currentSection = 'persona';
+            continue;
+        } else if (/^[a-z_]+\s*:/.test(line) && !line.startsWith(' ') && !line.startsWith('\t')) {
+            // New top-level key — stop current section
+            currentSection = null;
+        }
+
+        if (currentSection === 'memories' && /^\s+[-\d]/.test(line)) {
+            // Extract the value from list item (- "value") or numbered (1: "value")
+            const listMatch = line.match(/^\s+-\s*["']?(.+?)["']?\s*$/);
+            const numMatch = line.match(/^\s+\d+\s*:\s*["']?(.+?)["']?\s*$/);
+            const value = listMatch ? listMatch[1] : (numMatch ? numMatch[1] : null);
+            if (value) result.memories.push(value);
+        } else if (currentSection === 'criticalActions' && /^\s+[-\d]/.test(line)) {
+            const listMatch = line.match(/^\s+-\s*["']?(.+?)["']?\s*$/);
+            const numMatch = line.match(/^\s+\d+\s*:\s*["']?(.+?)["']?\s*$/);
+            const value = listMatch ? listMatch[1] : (numMatch ? numMatch[1] : null);
+            if (value) result.criticalActions.push(value);
+        } else if (currentSection === 'persona' && /^\s+/.test(line)) {
+            result.personaLines.push(line);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Merge user customizations from backed-up files into new customize.yaml files.
+ * Detects user-added memories, extra critical_actions, and persona overrides.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {Promise<{ merged: string[], skipped: string[] }>}
+ */
+async function mergeUserCustomizations(projectRoot) {
+    const configDir = path.join(projectRoot, CONFIG_DIR);
+    const backupDir = path.join(configDir, BACKUP_DIR_NAME);
+    const result = { merged: [], skipped: [] };
+
+    if (!fs.existsSync(backupDir)) {
+        console.log(chalk.gray('  No backup directory — skipping customization merge'));
+        return result;
+    }
+
+    const backupFiles = (await fs.readdir(backupDir)).filter(f => f.endsWith('.customize.yaml'));
+
+    for (const file of backupFiles) {
+        const backupPath = path.join(backupDir, file);
+        const newPath = path.join(configDir, file);
+
+        const backupContent = await fs.readFile(backupPath, 'utf-8');
+        const oldParsed = parseCustomizeYaml(backupContent);
+
+        // Detect user additions
+        const userMemories = oldParsed.memories; // all memories are user content
+        const userCriticalActions = oldParsed.criticalActions.filter(ca => !isStandardCriticalAction(ca));
+
+        // Detect persona overrides — compare with defaults from our shipped customizations
+        const shippedDir = path.join(__dirname, 'bmad-customizations');
+        const shippedPath = path.join(shippedDir, file);
+        let hasPersonaOverride = false;
+
+        if (fs.existsSync(shippedPath)) {
+            const shippedContent = await fs.readFile(shippedPath, 'utf-8');
+            const shippedParsed = parseCustomizeYaml(shippedContent);
+            // If the user's persona section differs from shipped, they customized it
+            if (oldParsed.personaLines.join('\n').trim() !== shippedParsed.personaLines.join('\n').trim()
+                && oldParsed.personaLines.length > 0) {
+                hasPersonaOverride = true;
+            }
+        } else {
+            // No shipped version — any persona content is user-added
+            if (oldParsed.personaLines.length > 0) {
+                hasPersonaOverride = true;
+            }
+        }
+
+        const hasUserContent = userMemories.length > 0 || userCriticalActions.length > 0 || hasPersonaOverride;
+
+        if (!hasUserContent) {
+            result.skipped.push(file);
+            continue;
+        }
+
+        // Merge into new file
+        let newContent;
+        if (fs.existsSync(newPath)) {
+            newContent = await fs.readFile(newPath, 'utf-8');
+        } else {
+            // New file doesn't exist — use backup as base
+            newContent = backupContent;
+        }
+
+        // Append user memories
+        if (userMemories.length > 0) {
+            // Check if memories section already exists
+            if (/^memories\s*:/m.test(newContent)) {
+                // Append to existing memories section
+                const memoriesBlock = userMemories.map(m => `  - "${m}"`).join('\n');
+                newContent = newContent.replace(/^(memories\s*:.*)/m, `$1\n${memoriesBlock}`);
+            } else {
+                // Add new memories section
+                const memoriesBlock = '\nmemories:\n' + userMemories.map(m => `  - "${m}"`).join('\n') + '\n';
+                newContent = newContent.trimEnd() + '\n' + memoriesBlock;
+            }
+            console.log(chalk.cyan(`    + Merged ${userMemories.length} user memories into ${file}`));
+        }
+
+        // Append user critical_actions (non-standard ones)
+        if (userCriticalActions.length > 0) {
+            if (/^critical_actions\s*:/m.test(newContent)) {
+                // Find the last numbered entry and continue from there
+                const caLines = newContent.split('\n');
+                let lastCaIdx = -1;
+                let lastNum = 0;
+                for (let i = 0; i < caLines.length; i++) {
+                    const numMatch = caLines[i].match(/^\s+(\d+)\s*:/);
+                    if (numMatch && parseInt(numMatch[1]) > lastNum) {
+                        lastNum = parseInt(numMatch[1]);
+                        lastCaIdx = i;
+                    }
+                }
+                if (lastCaIdx >= 0) {
+                    const extraLines = userCriticalActions.map((ca, idx) =>
+                        `  ${lastNum + idx + 1}: "${ca}"`
+                    );
+                    caLines.splice(lastCaIdx + 1, 0, ...extraLines);
+                    newContent = caLines.join('\n');
+                }
+            } else {
+                const caBlock = '\ncritical_actions:\n' + userCriticalActions.map((ca, idx) =>
+                    `  ${idx + 1}: "${ca}"`
+                ).join('\n') + '\n';
+                newContent = newContent.trimEnd() + '\n' + caBlock;
+            }
+            console.log(chalk.cyan(`    + Merged ${userCriticalActions.length} user critical_actions into ${file}`));
+        }
+
+        // If persona was overridden by the user, keep the user's persona block
+        if (hasPersonaOverride) {
+            // Replace persona section in new file with user's version
+            const personaBlock = 'persona:\n' + oldParsed.personaLines.join('\n');
+            if (/^persona\s*:/m.test(newContent)) {
+                // Replace existing persona section up to next top-level key
+                newContent = newContent.replace(
+                    /^persona\s*:[\s\S]*?(?=\n[a-z_]+\s*:|$)/m,
+                    personaBlock + '\n'
+                );
+            } else {
+                newContent = newContent.trimEnd() + '\n' + personaBlock + '\n';
+            }
+            console.log(chalk.cyan(`    + Preserved user persona overrides in ${file}`));
+        }
+
+        await fs.writeFile(newPath, newContent, 'utf-8');
+
+        // Validate merged output: re-read and parse to ensure YAML integrity
+        try {
+            const written = await fs.readFile(newPath, 'utf-8');
+            const validated = parseCustomizeYaml(written);
+            if (validated.criticalActions.length === 0 && written.includes('critical_actions:')) {
+                // critical_actions section exists but parsed to nothing — likely corrupt
+                console.log(chalk.yellow(`    ! Merge output validation failed for ${file} — restoring from backup`));
+                await fs.copy(backupPath, newPath, { overwrite: true });
+                result.skipped.push(file);
+                continue;
+            }
+        } catch (parseErr) {
+            console.log(chalk.yellow(`    ! Merge output parse error for ${file}: ${parseErr.message} — restoring from backup`));
+            await fs.copy(backupPath, newPath, { overwrite: true });
+            result.skipped.push(file);
+            continue;
+        }
+
+        result.merged.push(file);
+    }
+
+    if (result.merged.length > 0) {
+        console.log(chalk.green(`  Merged user customizations into ${result.merged.length} file(s)`));
+    }
+    if (result.skipped.length > 0) {
+        console.log(chalk.gray(`  ${result.skipped.length} file(s) had no user customizations to merge`));
+    }
+
+    return result;
+}
+
+/**
+ * Clean up legacy artifacts after successful migration.
+ * Conservative approach: only removes known-replaced files.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {Promise<string[]>} List of cleaned-up paths (relative to projectRoot)
+ */
+async function cleanupLegacyArtifacts(projectRoot) {
+    const cleaned = [];
+
+    // 1. Remove old custom agent XML definitions in _bmad/custom/agents/
+    const customAgentsDir = path.join(projectRoot, BMAD_DIR, 'custom', 'agents');
+    if (fs.existsSync(customAgentsDir)) {
+        const files = await fs.readdir(customAgentsDir);
+        for (const file of files) {
+            if (file.endsWith('.xml')) {
+                await fs.remove(path.join(customAgentsDir, file));
+                const relPath = path.join(BMAD_DIR, 'custom', 'agents', file);
+                cleaned.push(relPath);
+            }
+        }
+    }
+
+    // 2. Remove legacy YAML workflow files (engine artifacts, not extension workflows)
+    // These are in _bmad/bmm/workflows/ — only remove known legacy patterns
+    const legacyWorkflowDir = path.join(projectRoot, BMAD_DIR, 'bmm', 'workflows');
+    if (fs.existsSync(legacyWorkflowDir)) {
+        const entries = await fs.readdir(legacyWorkflowDir);
+        for (const entry of entries) {
+            const entryPath = path.join(legacyWorkflowDir, entry);
+            const stat = await fs.stat(entryPath);
+            // Only remove .yaml files at the root of workflows/ (legacy engine artifacts)
+            // Do NOT remove subdirectories (those contain current workflow content)
+            if (!stat.isDirectory() && entry.endsWith('.yaml')) {
+                await fs.remove(entryPath);
+                const relPath = path.join(BMAD_DIR, 'bmm', 'workflows', entry);
+                cleaned.push(relPath);
+            }
+        }
+    }
+
+    // NOTE: Backup directory (.backup-pre-migration/) is intentionally preserved
+    // after cleanup. It is only removed when a NEW backup is created by
+    // backupCustomizations() during the next migration cycle. This ensures
+    // users can manually recover customizations if needed.
+
+    // Print migration log
+    if (cleaned.length > 0) {
+        console.log(chalk.green(`\n  Migration cleanup summary:`));
+        for (const item of cleaned) {
+            console.log(chalk.gray(`    - Removed: ${item}`));
+        }
+        console.log(chalk.green(`  Cleaned up ${cleaned.length} legacy artifact(s)`));
+    } else {
+        console.log(chalk.gray('  No legacy artifacts to clean up'));
+    }
+
+    return cleaned;
+}
+
 /**
  * Restore _git_preserved → .git and set origin to a local file:// URL.
  *
@@ -478,4 +1010,12 @@ module.exports = {
     applyCustomizations,
     prePopulateBmadCache,
     deployMethodology,
+    // Migration functions (exported for testing)
+    detectMigrationNeed,
+    compareVersions,
+    backupCustomizations,
+    restoreCustomizations,
+    mergeUserCustomizations,
+    cleanupLegacyArtifacts,
+    parseCustomizeYaml,
 };

package/lib/installer.js

@@ -254,17 +254,23 @@ async function updateAgentInstructions(agent, projectRoot) {
   if (!agent.instructionFiles || agent.instructionFiles.length === 0) return;
 
   // JSON merge strategy (e.g., OpenCode)
+  // OpenCode expects instructions to be plain strings, not objects.
+  // We identify our entries by a marker prefix in the string content,
+  // and also clean up legacy object-format entries from older versions.
   if (agent.injectionStrategy?.position === 'json-merge') {
     const targetKey = agent.injectionStrategy.targetKey || 'instructions';
     const filePath = path.join(projectRoot, agent.instructionFiles[0]);
     const agentProjectPath = agent.getProjectPath();
     const relManifestPath = path.relative(projectRoot, path.join(agentProjectPath, 'MANIFEST.yaml')).replace(/\\/g, '/');
-    const instructionText = `# AI Agent Skills - Planning Instruction\n\nYou have access to a library of skills in your skills directory. Before starting any task:\n\n1. Read the skill manifest at ${relManifestPath}\n2. Based on the task description, select which skills are relevant\n3. Read only the selected skill files\n4. Then proceed with the task\n\nAlways load skills marked with always_load: true.\nDo not load skills that are not relevant to the current task.`;
+    const instructionText = `[${MA_AGENTS_SOURCE}] # AI Agent Skills - Planning Instruction\n\nYou have access to a library of skills in your skills directory. Before starting any task:\n\n1. Read the skill manifest at ${relManifestPath}\n2. Based on the task description, select which skills are relevant\n3. Read only the selected skill files\n4. Then proceed with the task\n\nAlways load skills marked with always_load: true.\nDo not load skills that are not relevant to the current task.`;
+
+    const isMaEntry = (entry) =>
+      (typeof entry === 'string' && entry.startsWith(`[${MA_AGENTS_SOURCE}]`)) ||
+      (typeof entry === 'object' && entry != null && entry._source === MA_AGENTS_SOURCE);
 
     if (!fs.existsSync(filePath)) {
       // File absent: create fresh (atomic write)
-      const data = { [targetKey]: [] };
-      data[targetKey].push({ _source: MA_AGENTS_SOURCE, text: instructionText });
+      const data = { [targetKey]: [instructionText] };
       const tmpPath = filePath + '.tmp';
       await fs.outputFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
       await fs.rename(tmpPath, filePath);
@@ -278,11 +284,9 @@ async function updateAgentInstructions(agent, projectRoot) {
       if (!Array.isArray(data[targetKey])) {
         data[targetKey] = [];
       }
-      // Filter out stale ma-agents entries, keep user entries (null-safe)
-      const userEntries = data[targetKey].filter(entry => entry != null && entry._source !== MA_AGENTS_SOURCE);
-      // Append fresh ma-agents entries
-      const freshEntries = [{ _source: MA_AGENTS_SOURCE, text: instructionText }];
-      data[targetKey] = [...userEntries, ...freshEntries];
+      // Filter out stale ma-agents entries (string or legacy object format), keep user entries
+      const userEntries = data[targetKey].filter(entry => entry != null && !isMaEntry(entry));
+      data[targetKey] = [...userEntries, instructionText];
       // Atomic write: temp file then rename
       const tmpPath = filePath + '.tmp';
       await fs.outputFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');

package/opencode.json

@@ -1,8 +1,5 @@
 {
   "instructions": [
-    {
-      "_source": "ma-agents",
-      "text": "# AI Agent Skills - Planning Instruction\n\nYou have access to a library of skills in your skills directory. Before starting any task:\n\n1. Read the skill manifest at .opencode/skills/MANIFEST.yaml\n2. Based on the task description, select which skills are relevant\n3. Read only the selected skill files\n4. Then proceed with the task\n\nAlways load skills marked with always_load: true.\nDo not load skills that are not relevant to the current task."
-    }
+    "[ma-agents] # AI Agent Skills - Planning Instruction\n\nYou have access to a library of skills in your skills directory. Before starting any task:\n\n1. Read the skill manifest at .opencode/skills/MANIFEST.yaml\n2. Based on the task description, select which skills are relevant\n3. Read only the selected skill files\n4. Then proceed with the task\n\nAlways load skills marked with always_load: true.\nDo not load skills that are not relevant to the current task."
   ]
 }