bmad-method 6.5.1-next.10 → 6.5.1-next.12

package/README.md

@@ -52,6 +52,15 @@ Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, etc.)
 npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes
 ```
 
+Override any module config option with `--set <module>.<key>=<value>` (repeatable). Run `--list-options [module]` to see locally-known official keys (built-in modules plus any external officials cached on this machine):
+
+```bash
+npx bmad-method install --yes \
+  --modules bmm --tools claude-code \
+  --set bmm.project_knowledge=research \
+  --set bmm.user_skill_level=expert
+```
+
 [See all installation options](https://docs.bmad-method.org/how-to/non-interactive-installation/)
 
 > **Not sure what to do?** Ask `bmad-help` — it tells you exactly what's next and what's optional. You can also ask questions like `bmad-help I just finished the architecture, what do I do next?`

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.5.1-next.10",
+  "version": "6.5.1-next.12",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -39,12 +39,13 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run validate:refs && npm run validate:skills",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run test:channels && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",
+    "test:urls": "node test/test-parse-source-urls.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",
     "validate:skills": "node tools/validate-skills.js --strict"
   },

package/tools/installer/commands/install.js

@@ -18,6 +18,16 @@ module.exports = {
       'Comma-separated list of tool/IDE IDs to configure (e.g., "claude-code,cursor"). Required for fresh non-interactive (--yes) installs. Run with --list-tools to see all valid IDs.',
     ],
     ['--list-tools', 'Print all supported tool/IDE IDs (with target directories) and exit.'],
+    [
+      '--set <spec>',
+      'Set a module config option non-interactively. Spec format: <module>.<key>=<value> (e.g. bmm.project_knowledge=research). Repeatable. Run --list-options to see available keys.',
+      (value, prev) => [...(prev || []), value],
+      [],
+    ],
+    [
+      '--list-options [module]',
+      'List available --set keys for all locally-known official modules, or for a single module by code, then exit.',
+    ],
     ['--action <type>', 'Action type for existing installations: install, update, or quick-update'],
     ['--user-name <name>', 'Name for agents to use (default: system username)'],
     ['--communication-language <lang>', 'Language for agent communication (default: English)'],
@@ -47,12 +57,43 @@ module.exports = {
         process.exit(0);
       }
 
+      if (options.listOptions !== undefined) {
+        const { formatOptionsList } = require('../list-options');
+        const moduleArg = options.listOptions === true ? null : options.listOptions;
+        const { text, ok } = await formatOptionsList(moduleArg);
+        const stream = ok ? process.stdout : process.stderr;
+        // process.exit() forces immediate termination and can truncate the
+        // buffered write when stdout/stderr is piped or captured by CI. Wait
+        // for the write to flush, then set process.exitCode and return so the
+        // event loop drains naturally. Non-zero exit when a single-module
+        // lookup misses so a CI typo like `--list-options bmn` doesn't look
+        // successful in scripts.
+        await new Promise((resolve, reject) => {
+          stream.write(text + '\n', (error) => (error ? reject(error) : resolve()));
+        });
+        process.exitCode = ok ? 0 : 1;
+        return;
+      }
+
       // Set debug flag as environment variable for all components
       if (options.debug) {
         process.env.BMAD_DEBUG_MANIFEST = 'true';
         await prompts.log.info('Debug mode enabled');
       }
 
+      // Validate --set syntax up-front so malformed entries fail fast,
+      // before we touch the network or filesystem. Parsed entries are
+      // re-derived inside ui.js where overrides are seeded.
+      if (options.set && options.set.length > 0) {
+        const { parseSetEntries } = require('../set-overrides');
+        try {
+          parseSetEntries(options.set);
+        } catch (error) {
+          await prompts.log.error(error.message);
+          process.exit(1);
+        }
+      }
+
       const config = await ui.promptInstall(options);
 
       // Handle cancel
@@ -61,8 +102,13 @@ module.exports = {
         process.exit(0);
       }
 
-      // Handle quick update separately
+      // Handle quick update separately. --set is a post-install TOML patch so
+      // it works the same way for quick-update as for a regular install — the
+      // installer runs, then `applySetOverrides` patches the central config
+      // files. Pass the parsed overrides through.
       if (config.actionType === 'quick-update') {
+        const { parseSetEntries } = require('../set-overrides');
+        config.setOverrides = parseSetEntries(options.set || []);
         const result = await installer.quickUpdate(config);
         await prompts.log.success('Quick update complete!');
         await prompts.log.info(`Updated ${result.moduleCount} modules with preserved settings (${result.modules.join(', ')})`);

package/tools/installer/core/config.js

@@ -3,7 +3,19 @@
  * User input comes from either UI answers or headless CLI flags.
  */
 class Config {
-  constructor({ directory, modules, ides, skipPrompts, verbose, actionType, coreConfig, moduleConfigs, quickUpdate, channelOptions }) {
+  constructor({
+    directory,
+    modules,
+    ides,
+    skipPrompts,
+    verbose,
+    actionType,
+    coreConfig,
+    moduleConfigs,
+    quickUpdate,
+    channelOptions,
+    setOverrides,
+  }) {
     this.directory = directory;
     this.modules = Object.freeze([...modules]);
     this.ides = Object.freeze([...ides]);
@@ -15,6 +27,11 @@ class Config {
     this._quickUpdate = quickUpdate;
     // channelOptions carry a Map + Set; don't deep-freeze.
     this.channelOptions = channelOptions || null;
+    // Parsed `--set <module>.<key>=<value>` overrides, applied as a TOML
+    // patch AFTER the install finishes. Shape: { moduleCode: { key: value } }.
+    // Intentionally NOT integrated with the prompt/template/schema flow; see
+    // `tools/installer/set-overrides.js` for the rationale and tradeoffs.
+    this.setOverrides = setOverrides || {};
     Object.freeze(this);
   }
 
@@ -40,6 +57,7 @@ class Config {
       moduleConfigs: userInput.moduleConfigs || null,
       quickUpdate: userInput._quickUpdate || false,
       channelOptions: userInput.channelOptions || null,
+      setOverrides: userInput.setOverrides || {},
     });
   }
 

package/tools/installer/core/installer.js

@@ -310,6 +310,19 @@ class Installer {
           moduleConfigs,
         });
 
+        // Apply post-install --set TOML patches. Runs after writeCentralConfig
+        // (inside generateManifests above) so the patch operates on the
+        // freshly written `_bmad/config.toml` / `_bmad/config.user.toml`.
+        // See `tools/installer/set-overrides.js` for routing rules.
+        if (config.setOverrides && Object.keys(config.setOverrides).length > 0) {
+          const { applySetOverrides } = require('../set-overrides');
+          const applied = await applySetOverrides(config.setOverrides, paths.bmadDir);
+          if (applied.length > 0) {
+            const summary = applied.map((a) => `${a.module}.${a.key} → ${a.file}`).join(', ');
+            await prompts.log.info(`Applied --set overrides: ${summary}`);
+          }
+        }
+
         message('Generating help catalog...');
         await this.mergeModuleHelpCatalogs(paths.bmadDir, manifestGen.agents);
         addResult('Help catalog', 'ok');
@@ -1283,6 +1296,10 @@ class Installer {
       ides: configuredIdes,
       coreConfig: quickModules.collectedConfig.core,
       moduleConfigs: quickModules.collectedConfig,
+      // Forward `--set` overrides so the post-install patch step
+      // (`applySetOverrides`) runs at the end of quick-update too. The
+      // installer.install path applies them after writeCentralConfig.
+      setOverrides: config.setOverrides || {},
       actionType: 'install',
       _quickUpdate: true,
       _preserveModules: skippedModules,

package/tools/installer/list-options.js

@@ -0,0 +1,210 @@
+const path = require('node:path');
+const fs = require('./fs-native');
+const yaml = require('yaml');
+const { getProjectRoot, getModulePath, getExternalModuleCachePath } = require('./project-root');
+
+/**
+ * Read a module.yaml and return its declared `code:` field, or null if missing/unparseable.
+ */
+async function readModuleCode(yamlPath) {
+  try {
+    const parsed = yaml.parse(await fs.readFile(yamlPath, 'utf8'));
+    if (parsed && typeof parsed === 'object' && typeof parsed.code === 'string') {
+      return parsed.code;
+    }
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+/**
+ * Discover module.yaml files for officials we can read locally:
+ *   - core, bmm: bundled in src/ (always present)
+ *   - external officials: only if previously cloned to ~/.bmad/cache/external-modules/
+ *
+ * Each result's `code` is the `code:` field from the module.yaml when present;
+ * that's the value `--set <module>.<key>=<value>` matches against.
+ *
+ * Community/custom modules are not enumerated; users reference their own
+ * module.yaml directly per the design (see issue #1663).
+ *
+ * @returns {Promise<Array<{code: string, yamlPath: string, source: string}>>}
+ */
+async function discoverOfficialModuleYamls() {
+  const found = [];
+  // Dedupe is case-insensitive because module caches occasionally retain a
+  // legacy UPPERCASE-named directory alongside the canonical lowercase one
+  // (same module, different cache key from an older schema). We pick whichever
+  // entry we see first and skip the alternate-case duplicate. NOTE: `--set`
+  // matching itself is case-sensitive (it keys on `moduleName` from the install
+  // flow's selected list, which is always lowercase short codes), so the
+  // surfaced `code` here is what users should type. Don't change to
+  // case-sensitive dedupe without revisiting that contract.
+  const seenCodes = new Set();
+
+  const addFound = async (yamlPath, source, fallbackCode) => {
+    const declaredCode = await readModuleCode(yamlPath);
+    const code = declaredCode || fallbackCode;
+    if (!code) return;
+    const lower = code.toLowerCase();
+    if (seenCodes.has(lower)) return;
+    seenCodes.add(lower);
+    found.push({ code, yamlPath, source });
+  };
+
+  // Built-ins.
+  for (const code of ['core', 'bmm']) {
+    const yamlPath = path.join(getModulePath(code), 'module.yaml');
+    if (await fs.pathExists(yamlPath)) {
+      // Built-ins use their well-known short codes regardless of what the
+      // module.yaml `code:` says, since the install flow keys on these.
+      seenCodes.add(code.toLowerCase());
+      found.push({ code, yamlPath, source: 'built-in' });
+    }
+  }
+
+  // Bundled in src/modules/<code>/module.yaml (rare, but supported by getModulePath).
+  const srcModulesDir = path.join(getProjectRoot(), 'src', 'modules');
+  if (await fs.pathExists(srcModulesDir)) {
+    const entries = await fs.readdir(srcModulesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const yamlPath = path.join(srcModulesDir, entry.name, 'module.yaml');
+      if (await fs.pathExists(yamlPath)) {
+        await addFound(yamlPath, 'bundled', entry.name);
+      }
+    }
+  }
+
+  // External cache (~/.bmad/cache/external-modules/<code>/...).
+  const cacheRoot = getExternalModuleCachePath('').replace(/\/$/, '');
+  if (await fs.pathExists(cacheRoot)) {
+    const rawEntries = await fs.readdir(cacheRoot, { withFileTypes: true });
+    for (const entry of rawEntries) {
+      if (!entry.isDirectory()) continue;
+      const candidates = [
+        path.join(cacheRoot, entry.name, 'module.yaml'),
+        path.join(cacheRoot, entry.name, 'src', 'module.yaml'),
+        path.join(cacheRoot, entry.name, 'skills', 'module.yaml'),
+      ];
+      for (const candidate of candidates) {
+        if (await fs.pathExists(candidate)) {
+          await addFound(candidate, 'cached', entry.name);
+          break;
+        }
+      }
+    }
+  }
+
+  return found;
+}
+
+function formatPromptText(item) {
+  if (Array.isArray(item.prompt)) return item.prompt.join(' ');
+  return String(item.prompt || '').trim();
+}
+
+function inferType(item) {
+  if (item['single-select']) return 'single-select';
+  if (item['multi-select']) return 'multi-select';
+  if (typeof item.default === 'boolean') return 'boolean';
+  if (typeof item.default === 'number') return 'number';
+  return 'string';
+}
+
+function formatModuleOptions(code, parsed, source) {
+  const lines = [];
+  const header = source === 'built-in' ? code : `${code} (${source})`;
+  lines.push(header + ':');
+
+  let count = 0;
+  for (const [key, item] of Object.entries(parsed)) {
+    if (!item || typeof item !== 'object' || !('prompt' in item)) continue;
+    count++;
+    const type = inferType(item);
+    const scope = item.scope === 'user' ? ' [user-scope]' : '';
+    const defaultStr = item.default === undefined || item.default === null ? '(none)' : String(item.default);
+    lines.push(`  ${code}.${key}    (${type}${scope})  default: ${defaultStr}`);
+    const promptText = formatPromptText(item);
+    if (promptText) lines.push(`    ${promptText}`);
+    if (Array.isArray(item['single-select'])) {
+      const values = item['single-select'].map((v) => (typeof v === 'object' ? v.value : v)).filter((v) => v !== undefined);
+      if (values.length > 0) lines.push(`    values: ${values.join(' | ')}`);
+    }
+    lines.push('');
+  }
+
+  if (count === 0) {
+    lines.push('  (no configurable options)', '');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Render `--list-options` output.
+ *
+ * Returns `{ text, ok }` so callers can surface a non-zero exit code on
+ * a typo'd module-code lookup. Discovery dedupes case-insensitively, so
+ * the lookup is also case-insensitive — typing `--list-options BMM` and
+ * `--list-options bmm` both find the bmm built-in.
+ *
+ * @param {string|null} moduleCode - if non-null, restrict to this module
+ * @returns {Promise<{text: string, ok: boolean}>}
+ */
+async function formatOptionsList(moduleCode) {
+  const discovered = await discoverOfficialModuleYamls();
+  const needle = moduleCode ? moduleCode.toLowerCase() : null;
+  const filtered = needle ? discovered.filter((d) => d.code.toLowerCase() === needle) : discovered;
+
+  if (filtered.length === 0) {
+    if (moduleCode) {
+      const text = [
+        `No locally-known module.yaml for '${moduleCode}'.`,
+        '',
+        'Built-in modules (core, bmm) are always available. External officials',
+        'appear here after they have been installed at least once on this machine',
+        '(they are cached under ~/.bmad/cache/external-modules/).',
+        '',
+        'For community or custom modules, read the module.yaml file in that',
+        "module's source repository directly.",
+      ].join('\n');
+      return { text, ok: false };
+    }
+    return { text: 'No modules found.', ok: false };
+  }
+
+  const sections = [];
+  // Track when a module-scoped lookup couldn't actually be rendered (yaml
+  // unparseable or empty after parse). The full `--list-options` output is
+  // tolerant of one bad entry, but `--list-options <module>` against a single
+  // unreadable module should still fail tooling so a CI script catches it.
+  let moduleScopedFailure = false;
+  sections.push('Available --set keys', 'Format: --set <module>.<key>=<value> (repeatable)', '');
+  for (const { code, yamlPath, source } of filtered) {
+    let parsed;
+    try {
+      parsed = yaml.parse(await fs.readFile(yamlPath, 'utf8'));
+    } catch {
+      sections.push(`${code} (${source}): could not parse module.yaml`, '');
+      if (moduleCode) moduleScopedFailure = true;
+      continue;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      sections.push(`${code} (${source}): module.yaml is not a valid object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`, '');
+      if (moduleCode) moduleScopedFailure = true;
+      continue;
+    }
+    sections.push(formatModuleOptions(code, parsed, source));
+  }
+
+  if (!moduleCode) {
+    sections.push(
+      'Community and custom modules are not listed here — read their module.yaml directly. Unknown keys still persist with a warning.',
+    );
+  }
+
+  return { text: sections.join('\n'), ok: !moduleScopedFailure };
+}
+
+module.exports = { formatOptionsList, discoverOfficialModuleYamls };

package/tools/installer/modules/custom-module-manager.js

@@ -128,58 +128,102 @@ class CustomModuleManager {
       };
     }
 
-    // HTTPS/HTTP URL: https://host/owner/repo[/tree/branch/subdir][.git]
-    const httpsMatch = trimmed.match(/^(https?):\/\/([^/]+)\/([^/]+)\/([^/.]+?)(?:\.git)?(\/.*)?$/);
-    if (httpsMatch) {
-      const [, protocol, host, owner, repo, remainder] = httpsMatch;
-      const cloneUrl = `${protocol}://${host}/${owner}/${repo}`;
-      let subdir = null;
-      let urlRef = null; // branch/tag extracted from /tree/<ref>/subdir
-
-      if (remainder) {
-        // Extract subdir from deep path patterns used by various Git hosts
+    // HTTPS/HTTP URL: generic handling for any Git host.
+    // We avoid host-specific parsing — `git clone` will accept whatever URL the
+    // user provides. We only need to (a) separate an optional browser-style
+    // subdir suffix from the clone URL, (b) extract any embedded ref
+    // (branch/tag) from deep-path URLs, and (c) derive a cache key / display
+    // name from the path. The original protocol (http or https) is preserved.
+    if (/^https?:\/\//i.test(trimmed)) {
+      let url;
+      try {
+        url = new URL(trimmed);
+      } catch {
+        url = null;
+      }
+
+      if (url && url.host) {
+        const host = url.host;
+        let repoPath = url.pathname.replace(/^\/+/, '').replace(/\/+$/, '');
+        let subdir = null;
+        let urlRef = null; // branch/tag/commit extracted from deep-path URLs
+
+        // Detect browser-style deep-path patterns that embed a ref
+        // (branch/tag/commit) and optional subdirectory. These appear
+        // across many hosts:
+        //   GitHub  /<repo>/tree|blob/<ref>[/<subdir>]
+        //   GitLab  /<repo>/-/tree|blob/<ref>[/<subdir>]
+        //   Gitea   /<repo>/src/<ref>[/<subdir>]
+        //   Gitea   /<repo>/src/(branch|commit|tag)/<ref>[/<subdir>]
+        // Group 1 = repo path prefix, Group 2 = ref, Group 3 = subdir (optional).
         const deepPathPatterns = [
-          { regex: /^\/(?:-\/)?tree\/([^/]+)\/(.+)$/, refIdx: 1, pathIdx: 2 }, // GitHub, GitLab
-          { regex: /^\/(?:-\/)?blob\/([^/]+)\/(.+)$/, refIdx: 1, pathIdx: 2 },
-          { regex: /^\/src\/([^/]+)\/(.+)$/, refIdx: 1, pathIdx: 2 }, // Gitea/Forgejo
+          /^(.+?)\/(?:-\/)?(?:tree|blob)\/([^/]+)(?:\/(.+))?$/,
+          /^(.+?)\/src\/(?:branch\/|commit\/|tag\/)?([^/]+)(?:\/(.+))?$/,
         ];
-        // Also match `/tree/<ref>` with no subdir
-        const refOnlyPatterns = [/^\/(?:-\/)?tree\/([^/]+?)\/?$/, /^\/(?:-\/)?blob\/([^/]+?)\/?$/, /^\/src\/([^/]+?)\/?$/];
-
-        for (const p of deepPathPatterns) {
-          const match = remainder.match(p.regex);
+        for (const pattern of deepPathPatterns) {
+          const match = repoPath.match(pattern);
           if (match) {
-            urlRef = match[p.refIdx];
-            subdir = match[p.pathIdx].replace(/\/$/, '');
+            repoPath = match[1];
+            if (match[2]) urlRef = match[2];
+            if (match[3]) {
+              const cleaned = match[3].replace(/\/+$/, '');
+              if (cleaned) subdir = cleaned;
+            }
             break;
           }
         }
+
+        // Some hosts use ?path=/subdir on browse links to point at a file or
+        // directory. Honor it when no deep-path marker matched above.
         if (!subdir) {
-          for (const r of refOnlyPatterns) {
-            const match = remainder.match(r);
-            if (match) {
-              urlRef = match[1];
-              break;
-            }
+          const pathParam = url.searchParams.get('path');
+          if (pathParam) {
+            const cleaned = pathParam.replace(/^\/+/, '').replace(/\/+$/, '');
+            if (cleaned) subdir = cleaned;
           }
         }
-      }
 
-      // Precedence: explicit @version suffix > URL /tree/<ref> path segment.
-      const version = versionSuffix || urlRef || null;
+        // Strip a single trailing .git for a stable cacheKey/displayName.
+        const repoPathClean = repoPath.replace(/\.git$/i, '');
+        if (!repoPathClean) {
+          return {
+            type: null,
+            cloneUrl: null,
+            subdir: null,
+            localPath: null,
+            cacheKey: null,
+            displayName: null,
+            isValid: false,
+            error: 'Not a valid Git URL or local path',
+          };
+        }
 
-      return {
-        type: 'url',
-        cloneUrl,
-        subdir,
-        localPath: null,
-        version,
-        rawInput: trimmedRaw,
-        cacheKey: `${host}/${owner}/${repo}`,
-        displayName: `${owner}/${repo}`,
-        isValid: true,
-        error: null,
-      };
+        const cloneUrl = `${url.protocol}//${host}/${repoPathClean}`;
+        const cacheKey = `${host}/${repoPathClean}`;
+
+        // Display name: prefer "<owner>/<repo>" using the last two meaningful
+        // path segments.
+        const segments = repoPathClean.split('/').filter(Boolean);
+        const repoSeg = segments.at(-1);
+        const ownerSeg = segments.at(-2);
+        const displayName = ownerSeg ? `${ownerSeg}/${repoSeg}` : repoSeg;
+
+        // Precedence: explicit @version suffix > URL /tree/<ref> path segment.
+        const version = versionSuffix || urlRef || null;
+
+        return {
+          type: 'url',
+          cloneUrl,
+          subdir,
+          localPath: null,
+          version,
+          rawInput: trimmedRaw,
+          cacheKey,
+          displayName,
+          isValid: true,
+          error: null,
+        };
+      }
     }
 
     return {

package/tools/installer/set-overrides.js

@@ -0,0 +1,330 @@
+// `--set <module>.<key>=<value>` is a post-install patch. The installer runs
+// its normal flow and writes `_bmad/config.toml`, `_bmad/config.user.toml`,
+// and `_bmad/<module>/config.yaml`; afterwards `applySetOverrides` upserts
+// each override into those files.
+//
+// This is intentionally NOT integrated with the prompt/template/schema
+// system. Tradeoffs:
+//   - No `result:` template rendering: `--set bmm.project_knowledge=research`
+//     writes "research" verbatim. Pass `--set bmm.project_knowledge='{project-root}/research'`
+//     if you want the rendered form.
+//   - Carry-forward across installs is best-effort: declared schema keys
+//     persist via the existingValue path on the next interactive run; values
+//     for keys outside any module's schema may need to be re-passed on each
+//     install (or edited directly in `_bmad/config.toml`).
+//   - No "key not in schema" validation: whatever you assert, we write.
+//
+// Names that, when used as object keys, can mutate `Object.prototype` and
+// cascade into every plain-object lookup in the process. The `--set` pipeline
+// assigns into plain `{}` maps keyed by user input, so `--set __proto__.x=1`
+// would otherwise reach `overrides.__proto__[x] = 1` and pollute every plain
+// object. We reject the names at parse time and harden the maps in
+// `parseSetEntries` with `Object.create(null)` for defense-in-depth.
+const PROTOTYPE_POLLUTING_NAMES = new Set(['__proto__', 'prototype', 'constructor']);
+
+const path = require('node:path');
+const fs = require('./fs-native');
+const yaml = require('yaml');
+
+/**
+ * Parse a single `--set <module>.<key>=<value>` entry.
+ * @param {string} entry - raw flag value
+ * @returns {{module: string, key: string, value: string}}
+ * @throws {Error} on malformed input
+ */
+function parseSetEntry(entry) {
+  if (typeof entry !== 'string' || entry.length === 0) {
+    throw new Error('--set: empty entry. Expected <module>.<key>=<value>');
+  }
+  const eq = entry.indexOf('=');
+  if (eq === -1) {
+    throw new Error(`--set "${entry}": missing '='. Expected <module>.<key>=<value>`);
+  }
+  const lhs = entry.slice(0, eq);
+  // Note: only the LHS is trimmed. Values may legitimately contain leading
+  // or trailing whitespace (paths with spaces, quoted strings); module / key
+  // names cannot, so it's safe to be strict on the left.
+  const value = entry.slice(eq + 1);
+  const dot = lhs.indexOf('.');
+  if (dot === -1) {
+    throw new Error(`--set "${entry}": missing '.'. Expected <module>.<key>=<value>`);
+  }
+  const moduleCode = lhs.slice(0, dot).trim();
+  const key = lhs.slice(dot + 1).trim();
+  if (!moduleCode || !key) {
+    throw new Error(`--set "${entry}": empty module or key. Expected <module>.<key>=<value>`);
+  }
+  if (PROTOTYPE_POLLUTING_NAMES.has(moduleCode) || PROTOTYPE_POLLUTING_NAMES.has(key)) {
+    throw new Error(
+      `--set "${entry}": '__proto__', 'prototype', and 'constructor' are reserved and cannot be used as a module or key name.`,
+    );
+  }
+  return { module: moduleCode, key, value };
+}
+
+/**
+ * Parse repeated `--set` entries into a `{ module: { key: value } }` map.
+ * Later entries overwrite earlier ones for the same key. Both the outer
+ * map and the per-module inner maps are `Object.create(null)` so callers
+ * that bypass `parseSetEntry`'s name check still can't pollute prototypes.
+ *
+ * @param {string[]} entries
+ * @returns {Object<string, Object<string, string>>}
+ */
+function parseSetEntries(entries) {
+  const overrides = Object.create(null);
+  if (!Array.isArray(entries)) return overrides;
+  for (const entry of entries) {
+    const { module: moduleCode, key, value } = parseSetEntry(entry);
+    if (!overrides[moduleCode]) overrides[moduleCode] = Object.create(null);
+    overrides[moduleCode][key] = value;
+  }
+  return overrides;
+}
+
+/**
+ * Encode a JS string as a TOML basic string (double-quoted with escapes).
+ * @param {string} value
+ */
+function tomlString(value) {
+  const s = String(value);
+  // Per the TOML spec, basic strings escape `\`, `"`, and control characters.
+  return (
+    '"' +
+    s
+      .replaceAll('\\', '\\\\')
+      .replaceAll('"', String.raw`\"`)
+      .replaceAll('\b', String.raw`\b`)
+      .replaceAll('\f', String.raw`\f`)
+      .replaceAll('\n', String.raw`\n`)
+      .replaceAll('\r', String.raw`\r`)
+      .replaceAll('\t', String.raw`\t`) +
+    '"'
+  );
+}
+
+/**
+ * Section header for a given module code.
+ * - `core`     → `[core]`
+ * - `<other>`  → `[modules.<other>]`
+ *
+ * Mirrors the layout `manifest-generator.writeCentralConfig` produces.
+ */
+function sectionHeader(moduleCode) {
+  return moduleCode === 'core' ? '[core]' : `[modules.${moduleCode}]`;
+}
+
+/**
+ * Insert or update `key = value` inside a TOML section, returning the new
+ * file content. The format produced by the installer is regular and small
+ * enough that a line scanner is more reliable than pulling in a TOML
+ * round-tripper that would normalize the file's existing whitespace and
+ * comment structure.
+ *
+ *   - If `[section]` exists and contains `key`, replace the value on that
+ *     line (preserving any inline comment after the value).
+ *   - If `[section]` exists but `key` doesn't, append `key = value` at the
+ *     end of the section (before the next `[...]` header or EOF, skipping
+ *     trailing blank lines so the section stays tidy).
+ *   - If `[section]` doesn't exist, append a new section block at EOF.
+ *
+ * @param {string} content   existing file content (may be empty)
+ * @param {string} section   exact `[section]` header to target
+ * @param {string} key
+ * @param {string} valueToml already TOML-encoded value (e.g. `"foo"`)
+ * @returns {string} new content
+ */
+function upsertTomlKey(content, section, key, valueToml) {
+  const lines = content.split('\n');
+  // Track whether the file already ended with a newline so we can preserve
+  // that. `split('\n')` on `"a\n"` yields `['a', '']`, which gives us the
+  // marker we need.
+  const hadTrailingNewline = lines.length > 0 && lines.at(-1) === '';
+  if (hadTrailingNewline) lines.pop();
+
+  // Locate the target section.
+  const sectionStart = lines.findIndex((line) => line.trim() === section);
+  if (sectionStart === -1) {
+    // Section doesn't exist — append a new block. Pad with a blank line if
+    // the file is non-empty so sections stay visually separated.
+    if (lines.length > 0 && lines.at(-1).trim() !== '') lines.push('');
+    lines.push(section, `${key} = ${valueToml}`);
+    return lines.join('\n') + (hadTrailingNewline ? '\n' : '');
+  }
+
+  // Find the section's end (next `[...]` header or EOF).
+  let sectionEnd = lines.length;
+  for (let i = sectionStart + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  // Look for the key inside the section. Match `<key> = ...` allowing
+  // optional leading whitespace; preserve the comment tail (`# ...`) if any.
+  const keyPattern = new RegExp(`^(\\s*)${escapeRegExp(key)}\\s*=\\s*(.*)$`);
+  for (let i = sectionStart + 1; i < sectionEnd; i++) {
+    const match = lines[i].match(keyPattern);
+    if (match) {
+      const indent = match[1];
+      // Preserve trailing comment if present. We split on the first `#` that
+      // is preceded by whitespace — TOML strings can't contain unescaped `#`
+      // in basic-string form so this is safe for the values we emit.
+      const tail = match[2];
+      const commentIdx = tail.search(/\s+#/);
+      const commentSuffix = commentIdx === -1 ? '' : tail.slice(commentIdx);
+      lines[i] = `${indent}${key} = ${valueToml}${commentSuffix}`;
+      return lines.join('\n') + (hadTrailingNewline ? '\n' : '');
+    }
+  }
+
+  // Section exists but key doesn't. Insert before the next section header,
+  // skipping trailing blank lines inside the current section so the new
+  // entry sits with its siblings.
+  let insertAt = sectionEnd;
+  while (insertAt > sectionStart + 1 && lines[insertAt - 1].trim() === '') {
+    insertAt--;
+  }
+  lines.splice(insertAt, 0, `${key} = ${valueToml}`);
+  return lines.join('\n') + (hadTrailingNewline ? '\n' : '');
+}
+
+function escapeRegExp(s) {
+  return s.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+/**
+ * Look up `[section] key` in a TOML file. Returns true if the file exists,
+ * the section is present, and `key` is set within it. Used by
+ * `applySetOverrides` to route an override to the file that already owns
+ * the key (so user-scope keys land in `config.user.toml`, team-scope keys
+ * land in `config.toml`).
+ */
+async function tomlHasKey(filePath, section, key) {
+  if (!(await fs.pathExists(filePath))) return false;
+  const content = await fs.readFile(filePath, 'utf8');
+  const lines = content.split('\n');
+  const sectionStart = lines.findIndex((line) => line.trim() === section);
+  if (sectionStart === -1) return false;
+  const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  for (let i = sectionStart + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) return false;
+    if (keyPattern.test(lines[i])) return true;
+  }
+  return false;
+}
+
+/**
+ * Apply parsed `--set` overrides to the central TOML files written by the
+ * installer. Called at the end of an install / quick-update.
+ *
+ * Routing per (module, key):
+ *   1. If `_bmad/config.user.toml` already has `[section] key`, update there
+ *      (user-scope key like `core.user_name`, `bmm.user_skill_level`).
+ *   2. Otherwise update `_bmad/config.toml` (team scope, the default).
+ *
+ * The schema-correct user/team partition lives in `manifest-generator`. We
+ * intentionally don't re-read module schemas here — the only goal is to
+ * match the file the installer just wrote the key to. For brand-new keys
+ * (not in either file yet), team scope is the safe default.
+ *
+ * @param {Object<string, Object<string, string>>} overrides
+ * @param {string} bmadDir absolute path to `_bmad/`
+ * @returns {Promise<Array<{module:string,key:string,scope:'team'|'user',file:string}>>}
+ *          a list of applied entries (for caller logging)
+ */
+async function applySetOverrides(overrides, bmadDir) {
+  const applied = [];
+  if (!overrides || typeof overrides !== 'object') return applied;
+
+  const teamPath = path.join(bmadDir, 'config.toml');
+  const userPath = path.join(bmadDir, 'config.user.toml');
+
+  for (const moduleCode of Object.keys(overrides)) {
+    // Skip overrides for modules not actually installed. The installer writes
+    // `_bmad/<module>/config.yaml` for every installed module (including core),
+    // so its presence is a reliable "is this module here?" signal that works
+    // for both fresh installs and quick-updates without coupling to caller-
+    // supplied module lists.
+    const moduleConfigYaml = path.join(bmadDir, moduleCode, 'config.yaml');
+    if (!(await fs.pathExists(moduleConfigYaml))) {
+      continue;
+    }
+
+    const section = sectionHeader(moduleCode);
+    const moduleOverrides = overrides[moduleCode] || {};
+    for (const key of Object.keys(moduleOverrides)) {
+      const value = moduleOverrides[key];
+      const valueToml = tomlString(value);
+
+      const userOwnsIt = await tomlHasKey(userPath, section, key);
+      const targetPath = userOwnsIt ? userPath : teamPath;
+
+      // The team file always exists post-install; the user file only exists
+      // if the install wrote at least one user-scope key. If we're routing to
+      // it but it doesn't exist yet, create it with a minimal header so it
+      // has the same shape as installer-written user toml.
+      let content = '';
+      if (await fs.pathExists(targetPath)) {
+        content = await fs.readFile(targetPath, 'utf8');
+      } else {
+        content = '# Personal overrides for _bmad/config.toml.\n';
+      }
+
+      const next = upsertTomlKey(content, section, key, valueToml);
+      await fs.writeFile(targetPath, next, 'utf8');
+      applied.push({
+        module: moduleCode,
+        key,
+        scope: userOwnsIt ? 'user' : 'team',
+        file: path.basename(targetPath),
+      });
+    }
+
+    // Also patch the per-module yaml (`_bmad/<module>/config.yaml`). The
+    // installer reads this file as `_existingConfig` on subsequent runs and
+    // surfaces declared values as prompt defaults — under `--yes` those
+    // defaults are accepted, so patching here gives `--set` natural
+    // carry-forward for declared keys without needing schema-strict
+    // partition exemptions in the manifest writer. For undeclared keys the
+    // value lives in the per-module yaml but won't be re-emitted into
+    // config.toml on the next install (the schema-strict partition drops
+    // it); re-pass `--set` if you need it sticky.
+    const moduleYamlPath = path.join(bmadDir, moduleCode, 'config.yaml');
+    if (await fs.pathExists(moduleYamlPath)) {
+      try {
+        const text = await fs.readFile(moduleYamlPath, 'utf8');
+        const parsed = yaml.parse(text);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          // Preserve the installer's banner header (everything up to the
+          // first non-comment line) so `_bmad/<module>/config.yaml` keeps
+          // its provenance comments after we round-trip it.
+          const headerLines = [];
+          for (const line of text.split('\n')) {
+            if (line.startsWith('#') || line.trim() === '') {
+              headerLines.push(line);
+            } else {
+              break;
+            }
+          }
+          for (const key of Object.keys(moduleOverrides)) {
+            parsed[key] = moduleOverrides[key];
+          }
+          const body = yaml.stringify(parsed, { indent: 2, lineWidth: 0, minContentWidth: 0 });
+          const header = headerLines.length > 0 ? headerLines.join('\n') + '\n' : '';
+          await fs.writeFile(moduleYamlPath, header + body, 'utf8');
+        }
+      } catch {
+        // Per-module yaml unparseable — skip silently. The central toml was
+        // already patched above, which is the user-visible state for the
+        // current install. Carry-forward will fail next install but the
+        // current install reflects the override.
+      }
+    }
+  }
+
+  return applied;
+}
+
+module.exports = { parseSetEntry, parseSetEntries, applySetOverrides, upsertTomlKey, tomlString };

package/tools/installer/ui.js

@@ -16,6 +16,7 @@ const {
 } = require('./modules/channel-plan');
 const channelResolver = require('./modules/channel-resolver');
 const prompts = require('./prompts');
+const { parseSetEntries } = require('./set-overrides');
 
 const manifest = new Manifest();
 
@@ -287,7 +288,7 @@ class UI {
         // Get tool selection
         const toolSelection = await this.promptToolSelection(confirmedDirectory, options);
 
-        const moduleConfigs = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
+        const { moduleConfigs, setOverrides } = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
           ...options,
           channelOptions,
         });
@@ -313,6 +314,7 @@ class UI {
           skipIde: toolSelection.skipIde,
           coreConfig: moduleConfigs.core || {},
           moduleConfigs: moduleConfigs,
+          setOverrides,
           skipPrompts: options.yes || false,
           channelOptions,
         };
@@ -364,7 +366,7 @@ class UI {
     await this._interactiveChannelGate({ options, channelOptions, selectedModules });
 
     let toolSelection = await this.promptToolSelection(confirmedDirectory, options);
-    const moduleConfigs = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
+    const { moduleConfigs, setOverrides } = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
       ...options,
       channelOptions,
     });
@@ -390,6 +392,7 @@ class UI {
       skipIde: toolSelection.skipIde,
       coreConfig: moduleConfigs.core || {},
       moduleConfigs: moduleConfigs,
+      setOverrides,
       skipPrompts: options.yes || false,
       channelOptions,
     };
@@ -709,6 +712,33 @@ class UI {
    */
   async collectModuleConfigs(directory, modules, options = {}) {
     const { OfficialModules } = require('./modules/official-modules');
+
+    // Parse --set up front purely to surface user-error before the install
+    // burns time on the network / filesystem. The actual application happens
+    // in installer.install() as a post-write TOML patch — see
+    // `tools/installer/set-overrides.js`. We also warn about overrides
+    // targeting modules the user didn't include, since those will silently
+    // miss the file the patch step looks for.
+    let setOverrides = {};
+    try {
+      setOverrides = parseSetEntries(options.set || []);
+    } catch (error) {
+      // install.js validated already; rethrow as-is for the user.
+      throw error;
+    }
+    // Drop overrides for modules that aren't in the install set so the
+    // post-install patch step doesn't create orphan sections in config.toml
+    // for modules that were never installed.
+    const selectedModuleSet = new Set(['core', ...modules]);
+    for (const moduleCode of Object.keys(setOverrides)) {
+      if (!selectedModuleSet.has(moduleCode)) {
+        await prompts.log.warn(
+          `--set ${moduleCode}.* — module '${moduleCode}' is not in the install set; values will be ignored. Add it to --modules to apply.`,
+        );
+        delete setOverrides[moduleCode];
+      }
+    }
+
     const configCollector = new OfficialModules({ channelOptions: options.channelOptions });
 
     // Seed core config from CLI options if provided
@@ -774,7 +804,7 @@ class UI {
       skipPrompts: options.yes || false,
     });
 
-    return configCollector.collectedConfig;
+    return { moduleConfigs: configCollector.collectedConfig, setOverrides };
   }
 
   /**