bmad-plus 0.21.0 → 0.23.0

package/tools/cli/commands/assurance.js

@@ -0,0 +1,162 @@
+/**
+ * Security assurance cases: start one from the Shield template, run the checks that produce
+ * evidence, verify a case against them.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const assurance = require('../lib/assurance');
+
+const ACTIONS = ['init', 'run', 'verify'];
+
+function print(json, payload, lines) {
+  if (json) console.log(JSON.stringify({ schemaVersion: 1, ...payload }, null, 2));
+  else for (const line of lines) console.log(line);
+}
+
+/** `--emit-check` writes a JSON file atomically, never over the case or its ledger. */
+function writeCheck(projectDir, value, kase, ledger, result) {
+  const file = path.resolve(projectDir, value);
+  if (!/\.json$/i.test(file)) throw new Error('--emit-check writes a .json file');
+  const protectedFiles = [path.resolve(projectDir, kase.file), ledger];
+  if (protectedFiles.some((taken) => path.relative(taken, file) === ''))
+    throw new Error('--emit-check must not overwrite the case or its ledger');
+  if (fs.existsSync(file) && !fs.statSync(file).isFile())
+    throw new Error(`--emit-check: ${file} is not a file`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx' });
+  try {
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+  return file;
+}
+
+function initAction(projectDir, caseFile, json) {
+  const { file, id } = assurance.initCase(projectDir, caseFile);
+  print(json, { action: 'init', case: id, file }, [
+    `${file}: case ${id} started from the Shield template.`,
+    'Replace every example claim and check with those of the project, commit it, then run it.',
+  ]);
+}
+
+async function runAction(projectDir, kase, options, json) {
+  const { file, results, head, authenticated } = await assurance.runChecks(projectDir, kase, {
+    dir: options.dir,
+    only: options.check,
+  });
+  const failed = results.filter((result) => result.failures.length);
+  print(
+    json,
+    {
+      action: 'run',
+      case: kase.id,
+      ledger: file,
+      head,
+      authenticated,
+      results: results.map(({ check, failures, record }) => ({
+        check,
+        status: failures.length ? 'failed' : 'passed',
+        failures,
+        sequence: record.sequence,
+        exitCode: record.exitCode,
+        revision: record.revision,
+        dirty: record.dirty,
+        sha256: record.sha256,
+      })),
+    },
+    [
+      `${file}`,
+      ...results.map(
+        ({ check, failures, record }) =>
+          `  ${failures.length ? 'failed' : 'passed'} ${check.padEnd(24)} exit ${record.exitCode ?? '-'} in ${Math.round(record.durationMs / 100) / 10} s${failures.length ? ` — ${failures.join('; ')}` : ''}`
+      ),
+      ...(results.some(({ record }) => record.dirty !== false)
+        ? [
+            '  Ran on uncommitted changes, untracked files or outside git: a case bound to a commit will not accept these runs.',
+          ]
+        : []),
+      `Recorded ${results.length} run(s)${authenticated ? ', authenticated by key' : ''}; ledger head ${head}.`,
+      `Keep the head outside the ledger and verify with bmad-plus assurance verify ${kase.file} --ledger-head ${head}.`,
+    ]
+  );
+  process.exitCode = failed.length ? 1 : 0;
+}
+
+function verifyAction(projectDir, kase, options, json) {
+  const verdict = assurance.verifyCase(projectDir, kase, {
+    dir: options.dir,
+    head: options.ledgerHead ?? null,
+  });
+  let check = null;
+  if (options.emitCheck)
+    check = writeCheck(
+      projectDir,
+      options.emitCheck,
+      kase,
+      assurance.ledgerFile(projectDir, options.dir, kase.id),
+      assurance.checkResult(verdict)
+    );
+  print(
+    json,
+    { action: 'verify', ...verdict, check },
+    [
+      `${kase.id}: ${verdict.status} — ${verdict.claims.filter((c) => c.status === 'supported').length}/${verdict.claims.length} claim(s) supported, ${verdict.ledger.runs} recorded run(s)`,
+      ...verdict.reasons.map((reason) => `  - ${reason}`),
+      ...Object.entries(verdict.checks)
+        .filter(([, judged]) => judged.status !== 'passed')
+        .map(([id, judged]) => `  ${judged.status.padEnd(7)} ${id}: ${judged.reasons.join('; ')}`),
+      ...verdict.claims
+        .filter((claim) => claim.status !== 'supported')
+        .map((claim) => `  unsupported claim ${claim.id}: ${claim.reasons.join('; ')}`),
+      ...(verdict.controls.supported.length
+        ? [`  controls with executed evidence: ${verdict.controls.supported.join(', ')}`]
+        : []),
+      check ? `  check: ${check}` : '',
+    ].filter(Boolean)
+  );
+  process.exitCode = verdict.exitCode;
+}
+
+module.exports = {
+  command: 'assurance <action> <case>',
+  description: 'Security assurance case bound to executed checks: init, run, verify',
+  options: [
+    ['-d, --directory <path>', 'Project directory'],
+    ['--dir <path>', 'Evidence folder inside the project', assurance.DEFAULT_DIR],
+    ['--check <id>', 'run: only this check (repeatable)', (v, all) => [...all, v], []],
+    ['--ledger-head <sha256>', 'verify: fail unless the ledger still holds this record'],
+    ['--emit-check <file>', 'verify: also write the verdict as a JSON check result for CI'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: async (action, caseFile, options = {}) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
+    const json = Boolean(options.json);
+    const settings = { dir: options.dir || assurance.DEFAULT_DIR, check: options.check || [] };
+    try {
+      if (!ACTIONS.includes(action))
+        throw new Error(`unknown action "${action}" (${ACTIONS.join(', ')})`);
+      if (action === 'init') return initAction(projectDir, caseFile, json);
+      const kase = assurance.loadCase(projectDir, caseFile);
+      if (action === 'run') await runAction(projectDir, kase, settings, json);
+      else
+        verifyAction(
+          projectDir,
+          kase,
+          { ...settings, emitCheck: options.emitCheck, ledgerHead: options.ledgerHead },
+          json
+        );
+    } catch (error) {
+      if (json)
+        console.log(
+          JSON.stringify({ schemaVersion: 1, status: 'error', message: error.message }, null, 2)
+        );
+      else console.error(`assurance: ${error.message}`);
+      process.exitCode = 3;
+    }
+  },
+};

package/tools/cli/commands/install.js

@@ -15,7 +15,7 @@ const clack = require('@clack/prompts');
 const pc = require('picocolors');
 const { t, LANGUAGES, getLanguageOptions, getCommLanguageOptions } = require('../i18n');
 const { PACKS, DERIVED } = require('../lib/packs');
-const { copyPackFiles, copyManagedFile } = require('../lib/pack-copy');
+const { copyPackFiles, copyManagedFile, listPackFiles } = require('../lib/pack-copy');
 const {
   acquireProjectLock,
   atomicWrite,
@@ -30,6 +30,7 @@ const { readInstallManifest } = require('../lib/install-manifest');
 const yaml = require('js-yaml');
 const { validateUserName } = require('../lib/validate');
 const { provisionPack } = require('../lib/python-provision');
+const { SWARM_DEFAULTS } = require('../lib/swarm-defaults');
 
 const PYTHON_PACKS = DERIVED.pythonPacks;
 
@@ -287,6 +288,19 @@ module.exports = {
     const releaseLock = acquireProjectLock(projectDir);
     try {
       const { safeTarget } = require('../../build/generate-adapters');
+      // Every pack must enumerate before the first write: a missing or mismatched
+      // external module aborts here, not after Core files exist without a manifest.
+      for (const packId of selectedPacks) {
+        const pack = PACKS[packId];
+        if (!pack || pack.disabled) continue;
+        listPackFiles({
+          bmadSrc,
+          targetAgentsDir: path.join(projectDir, '.agents', 'skills'),
+          targetDataDir: path.join(projectDir, '.agents', 'data'),
+          projectRoot: path.join(bmadSrc, '..', '..'),
+          pack,
+        });
+      }
       const plannedFiles = collectManagedFiles({ projectDir, packs: selectedPacks });
       if (detectedIDEs.length)
         plannedFiles.push(
@@ -558,6 +572,10 @@ module.exports = {
         agentGuide.push(`  ${i.guide_animated.padEnd(28)} →  "/animated build <video>"`);
       }
 
+      if (selectedPacks.includes('design')) {
+        agentGuide.push(`  ${i.guide_design.padEnd(28)} →  "/design read"`);
+      }
+
       if (selectedPacks.includes('shield')) {
         agentGuide.push(
           `  ${(i.guide_shield || '🛡️ GRC Compliance').padEnd(28)} →  "Shield, audit my SaaS for GDPR"`
@@ -609,6 +627,11 @@ module.exports = {
       if (selectedPacks.includes('animated')) {
         examples.push(`  ${i.guide_example_animated || '🎬 Animated: "/animated build hero.mp4"'}`);
       }
+      if (selectedPacks.includes('design')) {
+        examples.push(
+          `  ${i.guide_example_design || '🎨 Design: "/design read" → Atelier interviews you, then builds'}`
+        );
+      }
       if (selectedPacks.includes('osint')) {
         examples.push(`  ${i.guide_example_osint || '🔍 OSINT: "Shadow, investigate John Doe"'}`);
       }
@@ -819,6 +842,10 @@ function generateConfigYaml(
           page_budget: { max_steps: 15, max_minutes: 30 },
           dir: '_bmad-output/uat',
         },
+        // Swarms of sub-agents. budget: how many one run may use before the host asks the
+        // user; wave: how many are launched together; media_credits: paid generation is
+        // never covered by a budget, the host always asks.
+        swarm: { ...SWARM_DEFAULTS },
       },
       { lineWidth: -1, forceQuotes: true, quotingType: '"' }
     )

package/tools/cli/commands/intake.js

@@ -0,0 +1,124 @@
+/** Validate, plan, record and render a pack intake; the host asks, the user answers. */
+'use strict';
+
+const path = require('node:path');
+const intake = require('../lib/intake');
+
+const collect = (value, list) => [...list, value];
+
+function describePlan(result) {
+  const lines = [
+    `${result.intake} (${result.pack}): ${result.ready ? 'ready' : 'not ready'} — ` +
+      `${result.counts.answered} answered, ${result.counts.defaulted} defaulted, ` +
+      `${result.counts.unknown} unknown, ${result.counts.pending} not asked yet.`,
+  ];
+  if (result.missing.length) lines.push(`Must-haves still open: ${result.missing.join(', ')}`);
+  if (result.next.length) {
+    lines.push(`Ask next (at most ${result.maxPerMessage} per message):`);
+    for (const question of result.next) {
+      const hints = [];
+      if (question.mustHave) hints.push('must-have');
+      if (question.choices) hints.push(`choices: ${question.choices.join(', ')}`);
+      if (question.default !== undefined)
+        hints.push(`default: ${JSON.stringify(question.default)}`);
+      lines.push(
+        `  - ${question.id} [${question.kind}] ${question.ask}${hints.length ? ` (${hints.join('; ')})` : ''}`
+      );
+    }
+  }
+  for (const unknown of result.unknowns) {
+    lines.push(`Unknown: ${unknown.id}${unknown.risk ? ` — risk: ${unknown.risk}` : ''}`);
+  }
+  return lines;
+}
+
+module.exports = {
+  command: 'intake <action> [file]',
+  description:
+    'Pack intake: check a file, plan the next questions, record answers, render the brief',
+  options: [
+    ['-d, --directory <path>', 'Project directory (default: current directory)'],
+    ['--intake <file>', 'Intake file, relative to the project'],
+    ['--answers <file>', 'Answers file, relative to the project (created by record)'],
+    [
+      '--set <id=VALUE>',
+      'Record an answer, or id=UNKNOWN to mark it unknown (repeatable)',
+      collect,
+      [],
+    ],
+    ['--default <id>', 'Record the proposed default of a question (repeatable)', collect, []],
+    ['--reset', 'Start the answers file again, empty, for this intake (record)'],
+    ['--out <file>', 'Brief to write (render)'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: (action, file, options = {}) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
+    const needs = (name) => {
+      if (!options[name]) throw new Error(`--${name} is required for intake ${action}`);
+      return options[name];
+    };
+    try {
+      let result;
+      let lines;
+      if (action === 'check') {
+        if (!file) throw new Error('Use intake check FILE.');
+        result = intake.check({ projectDir, file });
+        process.exitCode = result.ok ? 0 : 1;
+        lines = result.ok
+          ? [
+              `${result.file}: valid intake ${result.id} (${result.pack}), ${result.questions} questions, ${result.mustHave} must-have.`,
+            ]
+          : [
+              `${result.file}: not a valid intake`,
+              ...result.problems.map((problem) => `  - ${problem}`),
+            ];
+        result = { status: result.ok ? 'valid' : 'invalid', ...result };
+      } else if (action === 'plan') {
+        result = intake.plan({
+          projectDir,
+          intakeFile: needs('intake'),
+          answersFile: needs('answers'),
+        });
+        process.exitCode = result.ready ? 0 : 2;
+        lines = describePlan(result);
+        result = { status: result.ready ? 'ready' : 'needs-answers', ...result };
+      } else if (action === 'record') {
+        result = intake.record({
+          projectDir,
+          intakeFile: needs('intake'),
+          answersFile: needs('answers'),
+          sets: options.set,
+          defaults: options.default,
+          reset: options.reset === true,
+        });
+        process.exitCode = 0;
+        lines = [
+          result.reset
+            ? `Reset ${result.answersFile}${result.recorded.length ? `, recorded ${result.recorded.join(', ')}` : ''}.`
+            : `Recorded ${result.recorded.join(', ')} in ${result.answersFile}.`,
+          ...describePlan(result),
+        ];
+        result = { status: 'recorded', ...result };
+      } else if (action === 'render') {
+        result = intake.render({
+          projectDir,
+          intakeFile: needs('intake'),
+          answersFile: needs('answers'),
+          out: needs('out'),
+        });
+        process.exitCode = 0;
+        lines = [
+          `Brief written to ${result.out} (${result.bytes} bytes); ${result.ready ? 'the intake is ready' : 'a must-have is still open'}.`,
+        ];
+        result = { status: 'rendered', ...result };
+      } else throw new Error('Use intake check FILE, plan, record or render.');
+      if (options.json) console.log(JSON.stringify({ schemaVersion: 1, ...result }, null, 2));
+      else for (const line of lines) console.log(line);
+    } catch (error) {
+      process.exitCode = 1;
+      if (options.json)
+        console.log(JSON.stringify({ schemaVersion: 1, status: 'error', error: error.message }));
+      else console.error('Intake: ' + error.message);
+    }
+  },
+};

package/tools/cli/commands/review.js

@@ -169,23 +169,30 @@ function rulesAction(projectDir, target, json) {
       action: 'rules',
       path: file,
       sha256: ruleset.sha256,
+      packFiles: ruleset.packFiles,
       projectFile: ruleset.projectFile,
       disabled: ruleset.disabled,
-      rules: listed.map(({ id, title, group, layer, globs, source }) => ({
+      rules: listed.map(({ id, title, group, layer, pack, globs, controls, source }) => ({
         id,
         title,
         group,
         layer,
+        ...(pack ? { pack } : {}),
         globs,
+        controls,
         source,
       })),
+      controls: reviewRules.controlsOf(
+        ruleset,
+        listed.map((rule) => rule.id)
+      ),
     },
     [
-      `rule set ${ruleset.sha256.slice(0, 12)}${ruleset.projectFile ? ` (built-in + ${ruleset.projectFile})` : ' (built-in)'}`,
+      `rule set ${ruleset.sha256.slice(0, 12)} (${['built-in', ...ruleset.packFiles, ...(ruleset.projectFile ? [ruleset.projectFile] : [])].join(' + ')})`,
       ...(file ? [`${file} gets ${listed.length} rule(s):`] : []),
       ...listed.map(
         (rule) =>
-          `  ${rule.id.padEnd(24)} ${rule.group.padEnd(12)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}`
+          `  ${rule.id.padEnd(24)} ${rule.group.padEnd(12)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}${rule.controls.length ? `\n  ${''.padEnd(24)} controls: ${rule.controls.join(' ')}` : ''}`
       ),
       ...ruleset.disabled.map((id) => `  ${id.padEnd(24)} disabled by the project`),
     ]

package/tools/cli/commands/swarm.js

@@ -0,0 +1,119 @@
+/** Run a swarm of sub-agents under a budget: deal, brief, check, file, tally; the host launches. */
+'use strict';
+
+const path = require('node:path');
+const swarm = require('../lib/swarm');
+
+const USAGE =
+  'Use swarm init --definition FILE [--profile FILE | --units FILE] [--context NAME=FILE] [--n N] [--seed N] [--approved], ' +
+  'briefs RUN [--wave N], check RUN, save RUN UNIT --input FILE, tally RUN [--out FILE], inspect RUN, or plan RUN [--out FILE].';
+
+function lines(action, result) {
+  if (result.status === 'needs-approval') return [`${result.run}: needs approval. ${result.next}`];
+  switch (action) {
+    case 'init':
+      return [
+        `${result.run}: ${result.kind} of ${result.n} units, budget ${result.budget}, approval ${result.approval}.`,
+        result.seed === null
+          ? 'Units listed, no seed.'
+          : `Seed ${result.seed} (same seed, same cards).`,
+        `Next: ${result.next}`,
+      ];
+    case 'briefs':
+      return [
+        `${result.run}: ${result.pending} of ${result.units} units need a sub-agent, in waves of ${result.wave}.`,
+        ...result.waves.flatMap((wave) => [
+          `Wave ${wave.index}:`,
+          ...wave.units.map((unit) => `  ${unit.id}  ${unit.brief}`),
+        ]),
+        `Each sub-agent: ${result.instruction}`,
+        `Disclosure: ${result.disclosure}`,
+      ];
+    case 'check':
+      return [
+        `${result.run}: ${result.valid} of ${result.units} valid answers.`,
+        ...result.pending.map(
+          (unit) => `  ${unit.id}  ${unit.state}${unit.reason ? `: ${unit.reason}` : ''}`
+        ),
+      ];
+    case 'save':
+      return [`${result.run}: answer of ${result.unit} filed at ${result.answer}`];
+    case 'tally': {
+      const { valid, total, skipped } = result.tally.units;
+      return [
+        result.files.markdown,
+        `${valid} of ${total} units counted; ${skipped.length} skipped.`,
+        `Disclosure: ${result.tally.disclosure}`,
+      ];
+    }
+    case 'inspect': {
+      const { counts } = result;
+      return [
+        `${result.run.id}: ${result.status} (${result.run.kind}, ${result.budget.decision})`,
+        `units ${counts.units}, briefed ${counts.briefed}, valid ${counts.valid}, invalid ${counts.invalid}, missing ${counts.missing}`,
+        `Disclosure: ${result.disclosure}`,
+      ];
+    }
+    case 'plan':
+      return [
+        `${result.plan}: ${result.tasks} tasks, ${result.maxParallel} in parallel.`,
+        `Next: ${result.next}`,
+      ];
+    default:
+      return [JSON.stringify(result)];
+  }
+}
+
+module.exports = {
+  command: 'swarm <action> [run] [unit]',
+  description:
+    'Deal, brief, check, file and tally a swarm of sub-agents within the configured budget',
+  options: [
+    ['-d, --directory <path>', 'Project directory'],
+    ['--definition <file>', 'Swarm definition (project-relative JSON) for init'],
+    ['--profile <file>', 'Panel profile (project-relative JSON) for init'],
+    ['--units <file>', 'Fanout units (project-relative JSON) for init'],
+    [
+      '--context <name=file>',
+      'Context file included verbatim in the briefs (repeatable)',
+      (value, all) => [...all, value],
+      [],
+    ],
+    ['--n <count>', 'Units to deal for a panel'],
+    ['--seed <number>', 'Dealing seed; drawn once and recorded when absent'],
+    ['--approved', 'Record that the user agreed to exceed the budget'],
+    ['--wave <count>', 'Sub-agents launched together (default: the configured wave)'],
+    ['--input <file>', 'Printed reply to file with save (project-relative)'],
+    ['--out <file>', 'Output file for tally or plan, under .bmad-plus/swarm/'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: (action, runId, unitId, options = {}) => {
+    const directory = path.resolve(options.directory || process.cwd());
+    try {
+      let result;
+      if (action === 'init' && !runId) result = swarm.init(directory, options);
+      else if (action === 'briefs' && runId && !unitId)
+        result = swarm.briefs(directory, runId, options);
+      else if (action === 'check' && runId && !unitId) result = swarm.check(directory, runId);
+      else if (action === 'save' && runId && unitId)
+        result = swarm.save(directory, runId, unitId, options);
+      else if (action === 'tally' && runId && !unitId)
+        result = swarm.tally(directory, runId, options);
+      else if (action === 'inspect' && runId && !unitId) result = swarm.inspect(directory, runId);
+      else if (action === 'plan' && runId && !unitId)
+        result = swarm.plan(directory, runId, options);
+      else throw new Error(USAGE);
+      process.exitCode =
+        result.status === 'needs-approval' ? 2 : result.status === 'incomplete' ? 1 : 0;
+      if (options.json) console.log(JSON.stringify(result, null, 2));
+      else for (const line of lines(action, result)) console.log(line);
+    } catch (error) {
+      process.exitCode = 1;
+      if (options.json)
+        console.log(
+          JSON.stringify({ schemaVersion: 1, status: 'error', error: error.message }, null, 2)
+        );
+      else console.error('Swarm: ' + error.message.replace(/^Swarm: /, ''));
+    }
+  },
+};

package/tools/cli/commands/uninstall.js

@@ -11,6 +11,7 @@ const pc = require('picocolors');
 const { t } = require('../i18n');
 const { PACKS, DERIVED } = require('../lib/packs');
 const { readInstallManifest } = require('../lib/install-manifest');
+const { externalModuleRoot } = require('../lib/pack-copy');
 const { generateUserFiles, USER_CONFIG_MARKER } = require('../../build/generate-adapters');
 const { contentHash } = require('../lib/installed-adapters');
 
@@ -44,6 +45,16 @@ function safeStat(projectDir, target) {
   return stat;
 }
 
+// The skills copied from an npm package are matched against that package. When it is gone
+// or no longer the pinned version, nothing can be compared and they stay.
+function resolvedExternalModule(externalModule, packageRoot) {
+  try {
+    return externalModuleRoot({ externalModule, projectRoot: packageRoot });
+  } catch {
+    return null;
+  }
+}
+
 function removalPlan(projectDir, manifest, manifestPath) {
   const packageRoot = path.join(__dirname, '..', '..', '..');
   const sourceRoot = path.join(packageRoot, 'src', 'bmad-plus');
@@ -91,6 +102,12 @@ function removalPlan(projectDir, manifest, manifestPath) {
         path.join(packageRoot, pack.externalPackage, 'skills'),
         targetPath('.agents', 'skills')
       );
+    if (pack.externalModule) {
+      const moduleRoot = resolvedExternalModule(pack.externalModule, packageRoot);
+      if (moduleRoot)
+        for (const name of pack.externalModule.skills)
+          matchSource(path.join(moduleRoot, 'skills', name), targetPath('.agents', 'skills', name));
+    }
   }
   for (const name of ['module.yaml', 'module-help.csv'])
     matchSource(path.join(sourceRoot, name), targetPath('_bmad', name));