bmad-plus 0.12.2 → 0.14.0

package/tools/cli/commands/doctor.js

@@ -1,233 +1,65 @@
-/**
- * BMAD+ Doctor Command
- * Checks installation integrity and reports issues
- *
- * Author: Laurent Rochetta
- */
-
-const path = require('node:path');
-const fs = require('node:fs');
+/** Human and JSON output share one report; runtime execution is explicitly opt-in. */
 const clack = require('@clack/prompts');
 const pc = require('picocolors');
-const { t } = require('../i18n');
-const { PACKS, EXPECTED_AGENTS } = require('../lib/packs');
+const { collectInstallationHealth } = require('../lib/installation-health');
 
 module.exports = {
   command: 'doctor',
-  description: 'Check BMAD+ installation integrity',
+  description: 'Check BMAD+ installation integrity and declared capabilities',
   options: [
     ['-d, --directory <path>', 'Project directory (default: current directory)'],
     ['-l, --lang <code>', 'Language code: en, fr, es, de, pt-br, ru, zh, he, ja, it'],
+    ['--json', 'Print the diagnostic report as JSON (read-only unless a probe is requested)'],
+    ['--verify-python', 'Execute installed Python interpreters to verify versions and imports'],
   ],
-  action: async (options) => {
-    const projectDir = path.resolve(options.directory || process.cwd());
-    const packageJson = require('../../../package.json');
-
-    clack.intro(pc.bgBlue(pc.white(` BMAD+ Doctor v${packageJson.version} `)));
-
-    let checks = 0;
-    let passed = 0;
-    let warnings = 0;
-    let errors = 0;
-
-    // ── Check 1: Installation manifest ──
-    checks++;
-    const manifestPath = path.join(projectDir, '_bmad', '.bmad-plus-install.json');
-    if (!fs.existsSync(manifestPath)) {
-      clack.log.error('❌ BMAD+ is not installed in this directory');
-      clack.outro(pc.red('Run `npx bmad-plus install` first.'));
+  action: async (options = {}) => {
+    const report = collectInstallationHealth({
+      projectDir: options.directory,
+      verifyPython: Boolean(options.verifyPython),
+    });
+    process.exitCode = report.summary.errors ? 1 : 0;
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
       return;
     }
-
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    const lang = options.lang || manifest.uiLanguage || 'en';
-    clack.log.success(`✅ Manifest found — v${manifest.version}`);
-    passed++;
-
-    // ── Check 2: Version comparison ──
-    checks++;
-    if (manifest.version === packageJson.version) {
-      clack.log.success(`✅ Version up to date (v${manifest.version})`);
-      passed++;
-    } else {
-      clack.log.warn(`⚠️  Version mismatch: installed v${manifest.version} → latest v${packageJson.version}`);
-      clack.log.info('   Run `npx bmad-plus update` to upgrade');
-      warnings++;
+    clack.intro(pc.bgBlue(pc.white(' BMAD+ Doctor v' + report.versions.cli + ' ')));
+    for (const entry of report.checks.filter(
+      (item) => item.status !== 'pass' || item.code === 'manifest.valid'
+    )) {
+      const log =
+        entry.status === 'error'
+          ? clack.log.error
+          : entry.status === 'warning'
+            ? clack.log.warn
+            : clack.log.success;
+      log(
+        entry.message +
+          (entry.path && !entry.message.includes(entry.path) ? ' (' + entry.path + ')' : '')
+      );
     }
-
-    // ── Check 3: Agent files ──
-    checks++;
-    const agentsDir = path.join(projectDir, '.agents', 'skills');
-    if (fs.existsSync(agentsDir)) {
-      const agentDirs = fs.readdirSync(agentsDir, { withFileTypes: true })
-        .filter(d => d.isDirectory())
-        .map(d => d.name);
-      clack.log.success(`✅ ${agentDirs.length} agent/skill directories found`);
-      passed++;
-
-      // Check each expected agent from manifest packs using shared EXPECTED_AGENTS module
-      for (const pack of (manifest.packs || ['core'])) {
-        const entry = EXPECTED_AGENTS[pack];
-        if (!entry) continue;
-
-        // Check individual agent directories
-        for (const agent of (entry.agents || [])) {
-          checks++;
-          const agentPath = path.join(agentsDir, agent);
-          if (fs.existsSync(agentPath)) {
-            passed++;
-          } else {
-            clack.log.warn(`⚠️  Missing agent: ${agent} (pack: ${pack})`);
-            warnings++;
-          }
-        }
-
-        // Check pack directory if applicable
-        if (entry.packDir) {
-          checks++;
-          const packPath = path.join(agentsDir, entry.packDir);
-          if (fs.existsSync(packPath)) {
-            passed++;
-
-            // These packs bundle their agents as files inside packDir — verify
-            // them there (not as loose directories, which would falsely warn).
-            for (const agentFile of (entry.packAgents || [])) {
-              checks++;
-              if (fs.existsSync(path.join(packPath, agentFile))) {
-                passed++;
-              } else {
-                clack.log.warn(`⚠️  Missing agent: ${agentFile} (pack: ${pack})`);
-                warnings++;
-              }
-            }
-          } else {
-            clack.log.warn(`⚠️  Missing pack directory: ${entry.packDir} (pack: ${pack})`);
-            warnings++;
-          }
-        }
-      }
-    } else {
-      clack.log.error('❌ No .agents/skills/ directory found');
-      errors++;
-    }
-
-    // ── Check 4: Config files ──
-    checks++;
-    const configPath = path.join(projectDir, '_bmad', 'config.yaml');
-    if (fs.existsSync(configPath)) {
-      clack.log.success('✅ config.yaml present');
-      passed++;
-    } else {
-      clack.log.error('❌ config.yaml missing');
-      errors++;
-    }
-
-    // ── Check 5: Module config ──
-    checks++;
-    const moduleYaml = path.join(projectDir, '_bmad', 'module.yaml');
-    if (fs.existsSync(moduleYaml)) {
-      clack.log.success('✅ module.yaml present');
-      passed++;
-    } else {
-      clack.log.warn('⚠️  module.yaml missing');
-      warnings++;
+    if (report.versions.installed) {
+      clack.note(
+        [
+          report.summary.passed + '/' + report.checks.length + ' checks passed',
+          report.summary.errors + ' error(s), ' + report.summary.warnings + ' warning(s)',
+          'Installed: v' + report.versions.installed + ' | Executing CLI: v' + report.versions.cli,
+          'Ownership inventory: ' + report.inventory.status,
+          'Integrations use host-managed execution; host capabilities were not probed.',
+        ].join('\n'),
+        'BMAD+ Health Report'
+      );
     }
-
-    // ── Check 6: IDE configs ──
-    checks++;
-    const ideFiles = ['CLAUDE.md', 'GEMINI.md', 'AGENTS.md'].filter(f =>
-      fs.existsSync(path.join(projectDir, f))
+    clack.log.info(
+      'Published version is not checked here. Use `bmad-plus update-check --json` to check npm.'
+    );
+    clack.outro(
+      report.status === 'ok'
+        ? pc.green('Installation checks passed.')
+        : pc.yellow(
+            options.verifyPython
+              ? 'Review the reported evidence. Python import probes ran; no provisioning was requested.'
+              : 'Review the reported evidence before changing files. Doctor did not modify the project.'
+          )
     );
-    if (ideFiles.length > 0) {
-      clack.log.success(`✅ ${ideFiles.length} IDE config(s): ${ideFiles.join(', ')}`);
-      passed++;
-    } else {
-      clack.log.warn('⚠️  No IDE config files found');
-      warnings++;
-    }
-
-    // ── Check 7: Output directories ──
-    checks++;
-    const outputDir = path.join(projectDir, '_bmad-output');
-    if (fs.existsSync(outputDir)) {
-      clack.log.success('✅ _bmad-output/ directory exists');
-      passed++;
-    } else {
-      clack.log.warn('⚠️  _bmad-output/ not found');
-      warnings++;
-    }
-
-    // ── Check 8: Skills integrity (SKILL.md exists in pack dirs) ──
-    if (manifest.packs && manifest.packs.includes('seo')) {
-      checks++;
-      const seoSkill = path.join(agentsDir, 'pack-seo', 'SKILL.md');
-      if (fs.existsSync(seoSkill)) {
-        clack.log.success('✅ SEO Engine SKILL.md present');
-        passed++;
-      } else {
-        clack.log.error('❌ SEO Engine SKILL.md missing — /seo audit will not work');
-        errors++;
-      }
-    }
-
-    // ── Check 9: PACKS ↔ module.yaml sync ──
-    checks++;
-    try {
-      const yaml = require('js-yaml');
-      const moduleYamlSrc = path.join(__dirname, '..', '..', '..', 'src', 'bmad-plus', 'module.yaml');
-      if (fs.existsSync(moduleYamlSrc)) {
-        const moduleContent = yaml.load(fs.readFileSync(moduleYamlSrc, 'utf8'));
-        const modulePackIds = Object.keys(moduleContent.packs || {});
-
-        // Use shared PACKS module instead of fragile regex on install.js source
-        const cliPackIds = Object.keys(PACKS);
-
-        // Find mismatches
-        const missingInCLI = modulePackIds.filter(p => !cliPackIds.includes(p));
-        const missingInModule = cliPackIds.filter(p => !modulePackIds.includes(p));
-
-        if (missingInCLI.length === 0 && missingInModule.length === 0) {
-          clack.log.success(`✅ PACKS ↔ module.yaml in sync (${modulePackIds.length} packs)`);
-          passed++;
-        } else {
-          if (missingInCLI.length > 0) {
-            clack.log.warn(`⚠️  Packs in module.yaml but missing from CLI PACKS: ${missingInCLI.join(', ')}`);
-          }
-          if (missingInModule.length > 0) {
-            clack.log.warn(`⚠️  Packs in CLI PACKS but missing from module.yaml: ${missingInModule.join(', ')}`);
-          }
-          warnings++;
-        }
-      } else {
-        clack.log.info(pc.dim('ℹ️  PACKS↔module.yaml check skipped (source not available in npx context)'));
-        passed++; // Not a failure — just unavailable
-      }
-    } catch (e) {
-      clack.log.info(pc.dim(`ℹ️  PACKS↔module.yaml check skipped: ${e.message}`));
-      passed++; // Graceful skip
-    }
-
-    // ── Summary ──
-    const summaryColor = errors > 0 ? pc.red : warnings > 0 ? pc.yellow : pc.green;
-    const summaryIcon = errors > 0 ? '❌' : warnings > 0 ? '⚠️' : '✅';
-
-    clack.note([
-      `${summaryIcon} ${passed}/${checks} checks passed`,
-      errors > 0 ? `❌ ${errors} error(s)` : null,
-      warnings > 0 ? `⚠️  ${warnings} warning(s)` : null,
-      '',
-      `📦 Version: v${manifest.version}`,
-      `📅 Installed: ${manifest.installed.split('T')[0]}`,
-      `🗣️  Language: ${manifest.language || 'N/A'}`,
-      `📦 Packs: ${(manifest.packs || ['core']).join(', ')}`,
-    ].filter(Boolean).join('\n'), '🩺 BMAD+ Health Report');
-
-    clack.outro(summaryColor(
-      errors > 0
-        ? 'Issues found — run `npx bmad-plus install` to fix'
-        : warnings > 0
-          ? 'Minor issues found — consider running `npx bmad-plus update`'
-          : 'Everything looks great! 🎉'
-    ));
   },
 };

package/tools/cli/commands/install.js

@@ -12,59 +12,18 @@ const fsExtra = require('fs-extra');
 const clack = require('@clack/prompts');
 const pc = require('picocolors');
 const { t, getLanguageOptions, getCommLanguageOptions } = require('../i18n');
-const { PACKS } = require('../lib/packs');
-const { copyPackFiles } = require('../lib/pack-copy');
+const { PACKS, DERIVED } = require('../lib/packs');
+const { copyPackFiles, copyManagedFile } = require('../lib/pack-copy');
+const { acquireProjectLock, inventoryOf, collectManagedFiles } = require('../lib/update-transaction');
 const { initMemory } = require('../lib/memory-init');
-const { generateIDEConfig, IDE_CONFIGS } = require('../lib/ide-config');
+const { generateUserFiles, IDE_CONFIGS } = require('../../build/generate-adapters');
+const { writeIDEConfigs, safeAdapterPath } = require('../lib/installed-adapters');
+const { readInstallManifest } = require('../lib/install-manifest');
+const yaml = require('js-yaml');
 const { validateUserName } = require('../lib/validate');
 const { provisionPack } = require('../lib/python-provision');
 
-// Packs whose runtime includes Python (registry.yaml: runtime includes "python").
-// Provisioned only when the user opts in with --provision-python, so the default
-// install (and the test suite) never spawns Python. Kills SEO "broken on arrival".
-// Paths are resolved relative to the PACKAGE root (projectRoot below), so they
-// must live under a directory shipped in package.json "files". The SEO toolkit
-// is embarked in-pack (src/bmad-plus/packs/pack-seo) precisely so npm consumers
-// receive the scripts + requirements the SKILL.md commands them to run.
-const PYTHON_PACKS = {
-  seo: {
-    requirements: ['src', 'bmad-plus', 'packs', 'pack-seo', 'requirements.txt'],
-    verifyModules: ['requests', 'bs4', 'defusedxml', 'lxml'],
-  },
-  memory: {
-    // NOTE: mcp-server is not in package.json "files" → this still warn-skips for
-    // npm consumers (memory RAG provisioning is a separate, pre-existing gap).
-    requirements: ['mcp-server', 'requirements.txt'],
-    verifyModules: ['chromadb'],
-  },
-};
-
-// Pack definitions are imported from the shared module: require('../lib/packs').PACKS
-
-// ── Root-config ownership markers (PROD-01) ──
-//
-// install writes CLAUDE.md / GEMINI.md / AGENTS.md, but TWO producers own those
-// same paths, each stamping its own marker:
-//   - lib/ide-config.js                 → INSTALLER_MARKER (this installer's template)
-//   - tools/build/generate-adapters.js  → GENERATED_MARKER (registry-generated spine)
-// Recognizing only the first is what let `install --yes` clobber a generated spine.
-const INSTALLER_MARKER = 'BMAD+ — AI Agent Configuration';
-const GENERATOR_MARKER_FALLBACK = 'AUTO-GENERATED by tools/build/generate-adapters.js';
-
-/**
- * The marker the adapter generator stamps on every root file it owns.
- * Read from the generator's own export so the two cannot drift apart — a
- * hand-typed copy is how INSTALLER_MARKER drifted from the spine in the first
- * place. The fallback only covers trees published without the build tooling;
- * tests/unit/install-spine.test.js pins both values to their real producer.
- */
-function resolveGeneratorMarker() {
-  try {
-    return require('../../build/generate-adapters').GENERATED_MARKER || GENERATOR_MARKER_FALLBACK;
-  } catch {
-    return GENERATOR_MARKER_FALLBACK;
-  }
-}
+const PYTHON_PACKS = DERIVED.pythonPacks;
 
 module.exports = {
   command: 'install',
@@ -74,12 +33,34 @@ module.exports = {
     ['-p, --packs <packs>', 'Comma-separated pack IDs: core,osint,all (default: interactive)'],
     ['-y, --yes', 'Accept all defaults, skip prompts'],
     ['-l, --lang <code>', 'Language code: en, fr, es, de, pt-br, ru, zh, he, ja, it (overrides auto-detection)'],
-    ['--tools <tools>', 'Comma-separated IDE IDs (default: auto-detect)'],
-    ['--provision-python', 'Provision an isolated Python env for packs that need one (seo, memory)'],
+    ['--tools <tools>', 'Comma-separated IDE IDs, all, or none (default: auto-detect)'],
+    ['--mode <mode>', 'Execution mode: manual, autopilot, hybrid (default: manual)'],
+    ['--provision-python', 'Provision isolated environments for selected Python packs'],
   ],
   action: async (options) => {
+    // A closed/piped stdin cannot answer prompts. Require explicit defaults
+    // before creating files, instead of silently exiting halfway through UI.
+    if (!options.yes && !process.stdin.isTTY) {
+      const i = t(options.lang || 'en');
+      clack.log.error(i.noninteractive_requires_yes('install'));
+      process.exitCode = 1;
+      return;
+    }
+
     const projectDir = path.resolve(options.directory || process.cwd());
     const bmadSrc = path.join(__dirname, '..', '..', '..', 'src', 'bmad-plus');
+    const previousManifestPath = safeAdapterPath(projectDir, '_bmad/.bmad-plus-install.json');
+    const previousManifestBytes = fs.existsSync(previousManifestPath) ? fs.readFileSync(previousManifestPath) : null;
+    let previousManifest = null;
+    let manifestError;
+    if (fs.existsSync(previousManifestPath)) {
+      try {
+        previousManifest = readInstallManifest(previousManifestPath);
+      } catch (error) {
+        manifestError = error;
+      }
+    }
+    if (options.mode && !['manual', 'autopilot', 'hybrid'].includes(options.mode)) throw new Error('Unknown execution mode: ' + options.mode);
 
     // ── Step 0: Language Selection ──
     const pkgJson = require('../../../package.json');
@@ -151,6 +132,8 @@ module.exports = {
     if (options.tools) {
       if (options.tools === 'none' || options.tools === 'skip') {
         detectedIDEs = [];
+      } else if (options.tools === 'all') {
+        detectedIDEs = Object.keys(IDE_CONFIGS);
       } else {
         detectedIDEs = options.tools.split(',').map(t => t.trim()).filter(t => IDE_CONFIGS[t]);
       }
@@ -196,6 +179,7 @@ module.exports = {
     // ── Step 3: User Config ──
     let userName = process.env.USER || process.env.USERNAME || 'Developer';
     let commLang = 'French';
+    let execMode = options.mode || 'manual';
 
     if (!options.yes) {
       const userConfig = await clack.group({
@@ -230,6 +214,37 @@ module.exports = {
       for (const w of warnings) clack.log.warn(w);
       userName = validatedName;
       commLang = userConfig.commLang;
+      execMode = options.mode || userConfig.execMode;
+    }
+
+    const releaseLock = acquireProjectLock(projectDir);
+    try {
+    const { safeTarget } = require('../../build/generate-adapters');
+    const plannedFiles = collectManagedFiles({ projectDir, packs: selectedPacks });
+    if (detectedIDEs.length) plannedFiles.push(...generateUserFiles(DERIVED, {
+      packs: selectedPacks, tools: detectedIDEs, userName, language: commLang,
+    }));
+    for (const { file } of plannedFiles) safeTarget(projectDir, file);
+    safeTarget(projectDir, '_bmad/config.yaml');
+    safeTarget(projectDir, '_bmad/.bmad-plus-install.json');
+    for (const directory of ['.agents/skills', '.agents/data', '_bmad', '_bmad-output/discovery', '_bmad-output/build', 'docs']) {
+      safeTarget(projectDir, directory + '/.bmad-preflight');
+    }
+    const currentManifestBytes = fs.existsSync(previousManifestPath) ? fs.readFileSync(previousManifestPath) : null;
+    if (previousManifestBytes === null ? currentManifestBytes !== null :
+      currentManifestBytes === null || !previousManifestBytes.equals(currentManifestBytes)) {
+      throw new Error('Installation changed while preparing install. Please retry.');
+    }
+    // Preserve the unreadable manifest before repair; do not trust its ownership
+    // hashes. The adapter writer will retain locally edited user instructions.
+    if (manifestError) {
+      const backupBase = '_bmad/.bmad-plus-install.json.corrupt.bak';
+      let backupFile = backupBase;
+      let index = 1;
+      while (fs.existsSync(safeAdapterPath(projectDir, backupFile))) backupFile = `${backupBase}.${index++}`;
+      const backupPath = safeAdapterPath(projectDir, backupFile);
+      fs.copyFileSync(safeAdapterPath(projectDir, '_bmad/.bmad-plus-install.json'), backupPath, fs.constants.COPYFILE_EXCL);
+      clack.log.warn(`${i.manifest_invalid(manifestError.message)}\nBackup: ${backupPath}`);
     }
 
     // ── Step 4: Install Files ──
@@ -248,6 +263,13 @@ module.exports = {
     let copiedAgents = 0;
     let copiedSkills = 0;
     let copiedFiles = 0;
+    const previousInventory = inventoryOf(previousManifest || {}) || {};
+    const fileInventory = { ...previousInventory };
+    let inventoryComplete = true;
+    const onFileConflict = file => {
+      if (!previousInventory[file]) inventoryComplete = false;
+      clack.log.warn(`${file}: locally changed or unowned content preserved.`);
+    };
 
     const projectRoot = path.join(bmadSrc, '..', '..');
 
@@ -261,6 +283,7 @@ module.exports = {
         targetDataDir,
         projectRoot,
         pack,
+        projectDir, inventory: fileInventory, previousInventory, onConflict: onFileConflict,
       });
       copiedAgents += result.copiedAgents;
       copiedSkills += result.copiedSkills;
@@ -311,35 +334,39 @@ module.exports = {
     // Copy module config
     const moduleYaml = path.join(bmadSrc, 'module.yaml');
     if (fs.existsSync(moduleYaml)) {
-      fsExtra.copySync(moduleYaml, path.join(targetBmadDir, 'module.yaml'));
+      copyManagedFile({ source: moduleYaml, target: path.join(targetBmadDir, 'module.yaml'),
+        projectDir, inventory: fileInventory, previousInventory, onConflict: onFileConflict });
       copiedFiles++;
     }
 
     const helpCsv = path.join(bmadSrc, 'module-help.csv');
     if (fs.existsSync(helpCsv)) {
-      fsExtra.copySync(helpCsv, path.join(targetBmadDir, 'module-help.csv'));
+      copyManagedFile({ source: helpCsv, target: path.join(targetBmadDir, 'module-help.csv'),
+        projectDir, inventory: fileInventory, previousInventory, onConflict: onFileConflict });
       copiedFiles++;
     }
 
     spinner.stop(i.installed_summary(copiedAgents, copiedSkills, copiedFiles));
 
     // ── Step 5: Generate IDE Configs ──
+    let adapterHashes = previousManifest?.adapterHashes || {};
     if (detectedIDEs.length > 0) {
       const ideSpinner = clack.spinner();
       ideSpinner.start(i.configuring_ides);
 
-      writeIDEConfigs({
+      const outcome = writeIDEConfigs({
         projectDir,
-        detectedIDEs,
-        configContent: generateIDEConfig(userName, commLang, selectedPacks),
+        files: generateUserFiles(DERIVED, { packs: selectedPacks, userName, language: commLang, tools: detectedIDEs }),
+        adapterHashes,
         yes: options.yes,
       });
+      adapterHashes = { ...adapterHashes, ...outcome.adapterHashes };
 
       ideSpinner.stop(i.ide_configured(detectedIDEs.length));
     }
 
     // ── Step 6: Create config.yaml ──
-    const configYaml = generateConfigYaml(userName, commLang, projectDir);
+    const configYaml = generateConfigYaml(userName, commLang, projectDir, execMode);
     const configPath = path.join(targetBmadDir, 'config.yaml');
     fs.writeFileSync(configPath, configYaml, 'utf8');
 
@@ -357,6 +384,9 @@ module.exports = {
       installed: new Date().toISOString(),
       packs: selectedPacks,
       ides: detectedIDEs,
+      adapterHashes,
+      fileInventory: { schemaVersion: 1, complete: inventoryComplete, files: fileInventory },
+      executionMode: execMode,
       user: userName,
       language: commLang,
     };
@@ -484,115 +514,30 @@ module.exports = {
     clack.note(agentGuide.join('\n'), i.guide_title);
 
     clack.outro(pc.green(i.guide_ready));
+    } finally {
+      releaseLock();
+    }
   },
   // Exported for functional testing (not part of the public API)
-  _internal: {
-    INSTALLER_MARKER,
-    GENERATOR_MARKER_FALLBACK,
-    resolveGeneratorMarker,
-    writeIDEConfigs,
-  },
+  _internal: { writeIDEConfigs, generateConfigYaml },
 };
 
-
-// ── Helpers ──
-
-/**
- * Write the IDE config files, never destroying one this installer does not own.
- *
- * An existing config falls into one of three classes, tested in this order:
- *
- *  1. GENERATOR-MANAGED (carries the adapter generator's marker) — SKIPPED, even
- *     under --yes. Such a file is a pure function of registry.yaml +
- *     tools/build/adapters.config.js, and the installer template is a strict
- *     subset of it (no registry facts), so overwriting is a downgrade that also
- *     breaks the `generate-adapters.js --check` drift gate. A .bak does not
- *     rescue it: every tool reads the live path, not the backup. The repair is
- *     regeneration, not merging — so install defers and points at the generator.
- *  2. HAND-AUTHORED (no BMAD+ marker) — kept as-is interactively; backed up then
- *     overwritten under --yes (NODE-02).
- *  3. INSTALLER-GENERATED (carries INSTALLER_MARKER) — refreshed in place.
- *
- * @param {object} args
- * @param {string} args.projectDir - Absolute path to the target project
- * @param {string[]} args.detectedIDEs - IDE ids to configure (keys of IDE_CONFIGS)
- * @param {string} args.configContent - Rendered config body to write
- * @param {boolean} [args.yes] - Non-interactive mode (--yes)
- * @returns {{written: string[], skipped: string[], backedUp: string[]}} config file names per outcome
- */
-function writeIDEConfigs({ projectDir, detectedIDEs, configContent, yes }) {
-  const generatorMarker = resolveGeneratorMarker();
-  // Several IDEs share one file (gemini-cli + antigravity → GEMINI.md): dedupe
-  // outcomes by file name so a shared file is reported — and warned about — once.
-  const outcome = { written: new Set(), skipped: new Set(), backedUp: new Set() };
-
-  for (const ideId of detectedIDEs) {
-    const ide = IDE_CONFIGS[ideId];
-    if (!ide) continue;
-
-    const configPath = path.join(projectDir, ide.configFile);
-
-    if (fs.existsSync(configPath)) {
-      const existing = fs.readFileSync(configPath, 'utf8');
-
-      // PROD-01: the adapter generator owns this file — defer to it.
-      if (existing.includes(generatorMarker)) {
-        if (!outcome.skipped.has(ide.configFile)) {
-          clack.log.warn(
-            `⚠️  ${ide.configFile} is generated by tools/build/generate-adapters.js — left untouched. ` +
-              `Run \`node tools/build/generate-adapters.js --adopt\` to refresh it from registry.yaml.`
-          );
-        }
-        outcome.skipped.add(ide.configFile);
-        continue;
-      }
-
-      // NODE-02: never clobber a hand-authored config without protecting it.
-      if (!existing.includes(INSTALLER_MARKER)) {
-        if (!yes) {
-          // Interactive: keep the user's file untouched.
-          if (!outcome.skipped.has(ide.configFile)) {
-            clack.log.warn(`⚠️  ${ide.configFile} already exists and was not created by BMAD+ — kept your file (skipped). Re-run with --yes to back it up and overwrite.`);
-          }
-          outcome.skipped.add(ide.configFile);
-          continue;
-        }
-        // Non-interactive: back up before overwriting, never destroy data.
-        if (!outcome.backedUp.has(ide.configFile)) {
-          let backupPath = `${configPath}.bak`;
-          if (fs.existsSync(backupPath)) backupPath = `${configPath}.${Date.now()}.bak`;
-          fs.copyFileSync(configPath, backupPath);
-          clack.log.warn(`⚠️  Backed up existing ${ide.configFile} → ${path.basename(backupPath)}`);
-          outcome.backedUp.add(ide.configFile);
-        }
-      }
-    }
-
-    fs.writeFileSync(configPath, configContent, 'utf8');
-    outcome.written.add(ide.configFile);
-  }
-
-  return {
-    written: [...outcome.written],
-    skipped: [...outcome.skipped],
-    backedUp: [...outcome.backedUp],
-  };
-}
-
-function generateConfigYaml(userName, language, projectDir) {
-  const projectName = path.basename(projectDir);
-  return `# BMAD+ Project Configuration
-# Generated by bmad-plus install
-
-user_name: "${userName}"
-communication_language: "${language}"
-document_output_language: "${language}"
-output_folder: "_bmad-output"
-project_name: "${projectName}"
-
-# Execution settings
-execution_mode: "manual"
-auto_role_activation: true
-parallel_execution: true
-`;
+function generateConfigYaml(userName, language, projectDir, execMode = 'manual') {
+  if (!['manual', 'autopilot', 'hybrid'].includes(execMode)) throw new Error('Unknown execution mode: ' + execMode);
+  return '# BMAD+ Project Configuration\n# Generated by bmad-plus install\n\n' + yaml.dump({
+    user_name: userName,
+    communication_language: language,
+    document_output_language: language,
+    output_folder: '_bmad-output',
+    project_name: path.basename(projectDir),
+    execution_mode: execMode,
+    auto_role_activation: true,
+    parallel_execution: true,
+    checkpoints: {
+      discovery: 'require_approval',
+      architecture: 'require_approval',
+      story: execMode === 'autopilot' ? 'notify_only' : 'require_approval',
+      delivery: 'require_approval',
+    },
+  }, { lineWidth: -1, forceQuotes: true, quotingType: '"' });
 }