bmad-plus 0.22.0 → 0.23.1

package/tools/cli/lib/intake.js

@@ -0,0 +1,202 @@
+/** Read, plan, record and render a pack intake inside one project; the contract decides. */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const yaml = require('js-yaml');
+const { safeTarget } = require('../../build/generate-adapters');
+const contract = require('../../build/intake-contract');
+
+const MAX_FILE = 1024 * 1024;
+// Trees the intake never writes into, wherever they sit in the project.
+const RESERVED_DIRS = new Set(['.git', '_bmad', '.bmad-plus', 'node_modules']);
+
+/** A user-supplied path, kept inside the project and free of symlinks. */
+function projectFile(projectDir, file) {
+  if (typeof file !== 'string' || file.trim() === '') throw new Error('a file path is required');
+  const root = path.resolve(projectDir);
+  const relative = path.relative(root, path.resolve(root, file)).split(path.sep).join('/');
+  if (!relative || relative === '..' || relative.startsWith('../'))
+    throw new Error(`${file}: outside the project directory ${root}`);
+  return { relative, absolute: safeTarget(root, relative) };
+}
+
+/** A path the intake may write: outside the reserved trees, and never through a link. */
+function writableFile(projectDir, file) {
+  const target = projectFile(projectDir, file);
+  const reserved = target.relative.split('/').find((part) => RESERVED_DIRS.has(part));
+  if (reserved) throw new Error(`${target.relative}: the intake never writes under ${reserved}/`);
+  return target;
+}
+
+function readBounded(absolute, label) {
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile()) throw new Error(`${label}: not a regular file`);
+  if (stat.size > MAX_FILE) throw new Error(`${label}: larger than ${MAX_FILE} bytes`);
+  return fs.readFileSync(absolute, 'utf8');
+}
+
+function describe(problems) {
+  return problems.map((problem) => `  - ${problem}`).join('\n');
+}
+
+/** Parse and validate an intake file; throws listing every problem. */
+function loadIntake(projectDir, file) {
+  const target = projectFile(projectDir, file);
+  let parsed;
+  try {
+    parsed = yaml.load(readBounded(target.absolute, target.relative), { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    throw new Error(`${target.relative}: ${error.message}`, { cause: error });
+  }
+  const result = contract.validateIntake(parsed);
+  if (!result.ok)
+    throw new Error(`${target.relative} is not a valid intake:\n${describe(result.problems)}`);
+  return { file: target.relative, intake: parsed };
+}
+
+/** The parsed JSON of an existing answers file when it belongs to this intake; else throws. */
+function ownedAnswers(target, intake) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readBounded(target.absolute, target.relative));
+  } catch (error) {
+    throw new Error(
+      `${target.relative}: exists and is not an answers file of intake "${intake.id}" (${error.message}); move it away or pick another path`,
+      { cause: error }
+    );
+  }
+  if (!parsed || typeof parsed !== 'object' || parsed.intake !== intake.id) {
+    throw new Error(
+      `${target.relative}: exists and belongs to ${JSON.stringify(parsed && parsed.intake)}, not to intake "${intake.id}"; move it away or pick another path`
+    );
+  }
+  return parsed;
+}
+
+/** Parse and validate an answers file; an absent file means no answer yet. */
+function loadAnswers(projectDir, file, intake) {
+  const target = writableFile(projectDir, file);
+  if (!fs.existsSync(target.absolute)) {
+    return { file: target.relative, answers: contract.emptyAnswers(intake), exists: false };
+  }
+  const parsed = ownedAnswers(target, intake);
+  const result = contract.validateAnswers(parsed, intake);
+  if (!result.ok)
+    throw new Error(
+      `${target.relative} does not answer this intake:\n${describe(result.problems)}\nRecord again with --reset to start over.`
+    );
+  return { file: target.relative, answers: parsed, exists: true };
+}
+
+function atomicWrite(projectDir, relative, content) {
+  const target = safeTarget(projectDir, relative);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const temporaryFile = `${relative}.${crypto.randomUUID()}.tmp`;
+  const temporary = safeTarget(projectDir, temporaryFile);
+  let fd;
+  try {
+    fd = fs.openSync(temporary, 'wx');
+    fs.writeFileSync(fd, content);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    safeTarget(projectDir, relative);
+    fs.renameSync(temporary, target);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+}
+
+function check({ projectDir, file }) {
+  const target = projectFile(projectDir, file);
+  let parsed;
+  try {
+    parsed = yaml.load(readBounded(target.absolute, target.relative), { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    return { file: target.relative, ok: false, problems: [error.message] };
+  }
+  const result = contract.validateIntake(parsed);
+  const summary = result.ok
+    ? {
+        id: parsed.id,
+        pack: parsed.pack,
+        questions: contract.listQuestions(parsed).length,
+        mustHave: contract.listQuestions(parsed).filter((q) => q.must_have === true).length,
+      }
+    : {};
+  return { file: target.relative, ...result, ...summary };
+}
+
+function plan({ projectDir, intakeFile, answersFile }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  const { answers, file } = loadAnswers(projectDir, answersFile, intake);
+  return { answersFile: file, ...contract.planIntake(intake, answers) };
+}
+
+/**
+ * `sets` is a list of "id=VALUE" texts, `defaults` a list of question ids. With
+ * `reset`, the file starts again empty for this intake (an existing file must
+ * already belong to it), then takes the sets and defaults of the same call.
+ */
+function record({ projectDir, intakeFile, answersFile, sets = [], defaults = [], reset = false }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  let loaded;
+  if (reset) {
+    const target = writableFile(projectDir, answersFile);
+    if (fs.existsSync(target.absolute)) ownedAnswers(target, intake);
+    loaded = { file: target.relative, answers: contract.emptyAnswers(intake) };
+  } else loaded = loadAnswers(projectDir, answersFile, intake);
+  const pairs = {};
+  for (const assignment of sets) {
+    const at = typeof assignment === 'string' ? assignment.indexOf('=') : -1;
+    if (at < 1) throw new Error(`--set expects id=VALUE, got "${assignment}"`);
+    const id = assignment.slice(0, at);
+    if (Object.hasOwn(pairs, id)) throw new Error(`question "${id}" is set twice in one call`);
+    pairs[id] = assignment.slice(at + 1);
+  }
+  if (!reset && Object.keys(pairs).length === 0 && defaults.length === 0)
+    throw new Error('nothing to record: pass --set id=VALUE, --default id or --reset');
+  const answers = contract.recordAnswers(intake, loaded.answers, { sets: pairs, defaults });
+  const result = contract.validateAnswers(answers, intake);
+  if (!result.ok) throw new Error(`recorded answers are invalid:\n${describe(result.problems)}`);
+  atomicWrite(projectDir, loaded.file, JSON.stringify(answers, null, 2) + '\n');
+  return {
+    answersFile: loaded.file,
+    reset,
+    recorded: [...Object.keys(pairs), ...defaults],
+    ...contract.planIntake(intake, answers),
+  };
+}
+
+/** The brief overwrites only a file it wrote before for the same intake. */
+function render({ projectDir, intakeFile, answersFile, out }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  const { answers } = loadAnswers(projectDir, answersFile, intake);
+  const target = writableFile(projectDir, out);
+  if (fs.existsSync(target.absolute)) {
+    const marker = contract.briefMarker(intake);
+    const head = readBounded(target.absolute, target.relative).split(/\r?\n/, 2);
+    if (head[1] !== marker)
+      throw new Error(
+        `${target.relative}: exists and is not a brief of intake "${intake.id}" (its second line is not the ownership marker); move it away or pick another path`
+      );
+  }
+  const brief = contract.renderBrief(intake, answers);
+  atomicWrite(projectDir, target.relative, brief);
+  const planned = contract.planIntake(intake, answers);
+  return { out: target.relative, bytes: Buffer.byteLength(brief), ready: planned.ready };
+}
+
+module.exports = {
+  projectFile,
+  writableFile,
+  loadIntake,
+  loadAnswers,
+  check,
+  plan,
+  record,
+  render,
+};

package/tools/cli/lib/pack-copy.js

@@ -8,11 +8,90 @@ const crypto = require('node:crypto');
 const { safeTarget } = require('../../build/generate-adapters');
 
 const fileHash = (content) => crypto.createHash('sha256').update(content).digest('hex');
+const MAX_MANIFEST = 1024 * 1024;
 
-function listPackFiles({ bmadSrc, targetAgentsDir, targetDataDir, projectRoot, pack }) {
+/** The package name comes from the generated registry data, never from user input. */
+function resolveModule(name, projectRoot) {
+  return require.resolve(name + '/package.json', { paths: [projectRoot] });
+}
+
+/** The node_modules directories Node searches from the BMAD+ package root upwards. */
+function moduleChain(projectRoot) {
+  const chain = [];
+  let current = fs.realpathSync(projectRoot);
+  for (;;) {
+    if (path.basename(current) !== 'node_modules') chain.push(path.join(current, 'node_modules'));
+    const parent = path.dirname(current);
+    if (parent === current) return chain;
+    current = parent;
+  }
+}
+
+/**
+ * The root of an `external_module` package installed next to BMAD+, once its
+ * version is the one the registry pinned. Node resolves through symlinks, so the
+ * resolved package must sit in the node_modules chain itself: a link or a global
+ * module path is refused.
+ */
+function externalModuleRoot({ externalModule, projectRoot, resolve = resolveModule }) {
+  const { package: name, version } = externalModule;
+  let manifestPath;
+  try {
+    manifestPath = resolve(name, projectRoot);
+  } catch (error) {
+    throw new Error(
+      'External module ' + name + ' is not installed next to BMAD+: ' + error.message,
+      { cause: error }
+    );
+  }
+  const expected = moduleChain(projectRoot).map((dir) =>
+    path.join(dir, ...name.split('/'), 'package.json')
+  );
+  if (!expected.includes(manifestPath)) {
+    throw new Error(
+      'External module ' +
+        name +
+        ' resolved to ' +
+        manifestPath +
+        ', outside the node_modules chain of this BMAD+. A symlinked package, a global module path and the isolated layout of pnpm (node_modules/.pnpm) are refused: install bmad-plus with npm so its pinned dependency sits in that chain.'
+    );
+  }
+  const root = path.dirname(manifestPath);
+  safeTarget(root, 'package.json');
+  const stat = fs.lstatSync(manifestPath);
+  if (!stat.isFile() || stat.size > MAX_MANIFEST)
+    throw new Error('External module ' + name + ' has no readable package.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error('External module ' + name + ': ' + error.message, { cause: error });
+  }
+  if (!manifest || manifest.name !== name || manifest.version !== version) {
+    throw new Error(
+      'External module ' +
+        name +
+        ' is ' +
+        String(manifest && manifest.version) +
+        ' but this BMAD+ expects exactly ' +
+        version +
+        '; reinstall bmad-plus so its pinned dependency matches.'
+    );
+  }
+  return root;
+}
+
+function listPackFiles({
+  bmadSrc,
+  targetAgentsDir,
+  targetDataDir,
+  projectRoot,
+  pack,
+  resolveModule: resolve,
+}) {
   const result = { copiedAgents: 0, copiedSkills: 0, copiedFiles: 0, files: [] };
   if (!pack) return result;
-  function walk(source, target) {
+  function walk(source, target, root) {
     // Local Python execution must not turn interpreter caches into owned/shipped
     // framework files. Keep this aligned with the explicit npm files exclusions.
     if (path.basename(source) === '__pycache__' || /\.py[co]$/i.test(source)) return false;
@@ -26,9 +105,9 @@ function listPackFiles({ bmadSrc, targetAgentsDir, targetDataDir, projectRoot, p
     if (stat.isSymbolicLink()) throw new Error('Pack source is a symbolic link: ' + source);
     if (stat.isDirectory()) {
       for (const name of fs.readdirSync(source).sort())
-        walk(path.join(source, name), path.join(target, name));
+        walk(path.join(source, name), path.join(target, name), root);
     } else if (stat.isFile()) {
-      result.files.push({ source, target });
+      result.files.push(root ? { source, target, root } : { source, target });
     } else throw new Error('Pack source is not a regular file: ' + source);
     return true;
   }
@@ -49,6 +128,17 @@ function listPackFiles({ bmadSrc, targetAgentsDir, targetDataDir, projectRoot, p
     walk(path.join(projectRoot, pack.externalPackage, 'skills'), targetAgentsDir)
   )
     result.copiedSkills++;
+  if (pack.externalModule) {
+    const root = externalModuleRoot({ externalModule: pack.externalModule, projectRoot, resolve });
+    for (const name of pack.externalModule.skills) {
+      if (!walk(path.join(root, 'skills', name), path.join(targetAgentsDir, name), root)) {
+        throw new Error(
+          'External module ' + pack.externalModule.package + ' does not ship skill ' + name
+        );
+      }
+      result.copiedSkills++;
+    }
+  }
   if (
     pack.packDir &&
     walk(
@@ -105,4 +195,4 @@ function copyPackFiles(options) {
   return counts;
 }
 
-module.exports = { copyPackFiles, listPackFiles, copyManagedFile, fileHash };
+module.exports = { copyPackFiles, listPackFiles, copyManagedFile, externalModuleRoot, fileHash };

package/tools/cli/lib/packs.js

@@ -18,8 +18,10 @@ const PACKS = {
     ],
     "skills": [
       "bmad-plus-autopilot",
+      "bmad-plus-intake",
       "bmad-plus-parallel",
       "bmad-plus-sync",
+      "bmad-plus-swarm",
       "bmad-plus-uat"
     ],
     "data": [
@@ -55,7 +57,7 @@ const PACKS = {
     "skills": [],
     "packDir": "pack-shield",
     "packSrcDir": "packs",
-    "desc": "GRC compliance (26 frameworks)"
+    "desc": "GRC compliance (27 frameworks)"
   },
   "seo": {
     "name": "SEO",
@@ -103,6 +105,25 @@ const PACKS = {
     "packDir": "pack-animated",
     "packSrcDir": "packs",
     "desc": "Animated website agents"
+  },
+  "design": {
+    "name": "Design",
+    "icon": "d",
+    "agents": [],
+    "skills": [],
+    "externalModule": {
+      "package": "design-skill",
+      "version": "0.2.1",
+      "skills": [
+        "design",
+        "design-review",
+        "redesign"
+      ]
+    },
+    "packDir": "pack-design",
+    "packSrcDir": "packs",
+    "intake": "intake.yaml",
+    "desc": "Design engine: build, review and redesign interfaces"
   }
 };
 
@@ -115,7 +136,8 @@ const PACK_ORDER = [
   "memory",
   "dev-studio",
   "backup",
-  "animated"
+  "animated",
+  "design"
 ];
 
 const EXPECTED_AGENTS = {
@@ -184,6 +206,13 @@ const EXPECTED_AGENTS = {
     "packAgents": [
       "animated-website-agent.md"
     ]
+  },
+  "design": {
+    "agents": [],
+    "packDir": "pack-design",
+    "packAgents": [
+      "design-engine.md"
+    ]
   }
 };
 
@@ -191,7 +220,7 @@ const DERIVED = {
   "product": {
     "code": "bmad-plus",
     "displayName": "BMAD+",
-    "version": "0.22.0",
+    "version": "0.23.1",
     "derivedFrom": "BMAD-METHOD v6.6.0"
   },
   "packOrder": [
@@ -203,11 +232,12 @@ const DERIVED = {
     "memory",
     "dev-studio",
     "backup",
-    "animated"
+    "animated",
+    "design"
   ],
-  "packCount": 9,
-  "installerAgents": 14,
-  "totalAgents": 47,
+  "packCount": 10,
+  "installerAgents": 15,
+  "totalAgents": 48,
   "languages": [
     "en",
     "fr",
@@ -235,7 +265,7 @@ const DERIVED = {
       "workflowCount": 0,
       "frameworkCount": 0,
       "categoryCount": 0,
-      "skillCount": 4,
+      "skillCount": 6,
       "referenceFiles": 0,
       "categoryAgentCounts": [],
       "runtimes": [
@@ -247,8 +277,10 @@ const DERIVED = {
         ".agents/skills/agent-quality/SKILL.md",
         ".agents/skills/agent-orchestrator/SKILL.md",
         ".agents/skills/bmad-plus-autopilot/SKILL.md",
+        ".agents/skills/bmad-plus-intake/SKILL.md",
         ".agents/skills/bmad-plus-parallel/SKILL.md",
         ".agents/skills/bmad-plus-sync/SKILL.md",
+        ".agents/skills/bmad-plus-swarm/SKILL.md",
         ".agents/skills/bmad-plus-uat/SKILL.md",
         ".agents/data/role-triggers.yaml"
       ],
@@ -364,7 +396,7 @@ const DERIVED = {
       "agentCount": 27,
       "subAgentCount": 0,
       "workflowCount": 11,
-      "frameworkCount": 26,
+      "frameworkCount": 27,
       "categoryCount": 6,
       "skillCount": 0,
       "referenceFiles": 79,
@@ -392,9 +424,9 @@ const DERIVED = {
           "description": "Compliance agents for GDPR, ISO 27001, SOC 2, HIPAA, EU AI Act, DORA, NIS2 and more"
         }
       ],
-      "summary": "27 compliance agents + 11 workflows across 26+ frameworks.",
-      "desc": "GRC compliance (26 frameworks)",
-      "description": "GRC compliance (26 frameworks)"
+      "summary": "27 compliance agents + 11 workflows across 27+ frameworks.",
+      "desc": "GRC compliance (27 frameworks)",
+      "description": "GRC compliance (27 frameworks)"
     },
     "seo": {
       "id": "seo",
@@ -481,6 +513,7 @@ const DERIVED = {
           "alias": "זכר, Memory Guardian"
         }
       ],
+      "cohabitationWarning": "Detects and links existing brains (_brain/, ~/.claude/memory/); NEVER overwrites memory files.",
       "summary": "Cross-session memory + project scanner + Karpathy guardrails.",
       "desc": "Persistent cross-session memory",
       "description": "Persistent cross-session memory"
@@ -564,6 +597,7 @@ const DERIVED = {
           "alias": "אהליאב"
         }
       ],
+      "cohabitationWarning": "Dev Studio agents overlap with Core (Atlas/Forge/Sentinel/Nexus); both can coexist.",
       "summary": "6 specialized agents + 38 workflows: Analysis → Planning → Architecture → Implementation → Review.",
       "desc": "SDLC automation (6 agents, specialized workflows)",
       "description": "SDLC automation (6 agents, specialized workflows)"
@@ -637,6 +671,62 @@ const DERIVED = {
       "summary": "Luxury scroll-driven website from video.",
       "desc": "Animated website agents",
       "description": "Animated website agents"
+    },
+    "design": {
+      "id": "design",
+      "order": 9,
+      "name": "Design",
+      "displayName": "Design",
+      "iconEmoji": "🎨",
+      "required": false,
+      "installerAgentCount": 1,
+      "categoryAgentCount": 0,
+      "agentCount": 1,
+      "subAgentCount": 0,
+      "workflowCount": 0,
+      "frameworkCount": 0,
+      "categoryCount": 0,
+      "skillCount": 0,
+      "referenceFiles": 0,
+      "categoryAgentCounts": [],
+      "runtimes": [
+        "node"
+      ],
+      "requiredResources": [
+        ".agents/skills/pack-design/design-engine.md",
+        ".agents/skills/design/SKILL.md",
+        ".agents/skills/design-review/SKILL.md",
+        ".agents/skills/redesign/SKILL.md",
+        ".agents/skills/pack-design/SKILL.md",
+        ".agents/skills/pack-design/intake.yaml"
+      ],
+      "personas": [
+        {
+          "id": "design-engine",
+          "name": "Atelier",
+          "role": "Design Engine",
+          "description": "Senior product designer and design engineer: surfaces, tokens, accessibility, audits, redesigns",
+          "usesSkills": [
+            "design",
+            "design-review",
+            "redesign"
+          ]
+        }
+      ],
+      "externalModule": {
+        "package": "design-skill",
+        "version": "0.2.1",
+        "skills": [
+          "design",
+          "design-review",
+          "redesign"
+        ]
+      },
+      "intake": "intake.yaml",
+      "cohabitationWarning": "Overlaps Sentinel's UX-review role and Dev Studio's Rachel (UX Designer); when this pack is installed its rules govern visual design and accessibility, and the others hand those over.",
+      "summary": "Atelier builds, audits and redesigns interfaces under checkable rules: intake first, semantic tokens, WCAG AA, every state covered, pre-flight before delivery.",
+      "desc": "Design engine: build, review and redesign interfaces",
+      "description": "Design engine: build, review and redesign interfaces"
     }
   },
   "pythonPacks": {

package/tools/cli/lib/review.js

@@ -221,7 +221,8 @@ function contentDigest(projectDir, file) {
  */
 function buildScope(projectDir, options = {}) {
   const head = options.workspace ? null : resolveCommit(projectDir, options.head || 'HEAD');
-  const base = resolveCommit(projectDir, options.base || 'HEAD~1');
+  // A workspace review covers the uncommitted work, so its default base is HEAD.
+  const base = resolveCommit(projectDir, options.base || (options.workspace ? 'HEAD' : 'HEAD~1'));
   const mergeBase = git(projectDir, ['merge-base', base, head || 'HEAD']).trim();
   const range = options.workspace ? [mergeBase] : [mergeBase, head];
   const numstat = parseNumstat(

package/tools/cli/lib/swarm-deal.js

@@ -0,0 +1,116 @@
+/** Deterministic dealing: the same profile, n and seed give the same cards, on any platform. */
+'use strict';
+
+const crypto = require('node:crypto');
+
+const WORD = 2 ** 32;
+
+/** A counter-mode generator over SHA-256: the stream depends on the seed alone. */
+class Dealer {
+  constructor(seed) {
+    this.seed = String(seed);
+    this.block = 0;
+    this.words = [];
+  }
+
+  next() {
+    if (!this.words.length) {
+      const digest = crypto
+        .createHash('sha256')
+        .update(this.seed + ':' + this.block)
+        .digest();
+      this.block += 1;
+      for (let offset = 0; offset < digest.length; offset += 4)
+        this.words.push(digest.readUInt32BE(offset));
+    }
+    return this.words.shift();
+  }
+
+  /** Uniform integer in [0, n): values above the last full cycle are rejected, never folded. */
+  below(n) {
+    const limit = WORD - (WORD % n);
+    let value = this.next();
+    while (value >= limit) value = this.next();
+    return value % n;
+  }
+
+  between(low, high) {
+    if (Number.isInteger(low) && Number.isInteger(high)) return low + this.below(high - low + 1);
+    return Math.round((low + (this.next() / WORD) * (high - low)) * 100) / 100;
+  }
+
+  shuffle(items) {
+    for (let index = items.length - 1; index > 0; index -= 1) {
+      const other = this.below(index + 1);
+      [items[index], items[other]] = [items[other], items[index]];
+    }
+    return items;
+  }
+}
+
+/** Largest-remainder quotas: the counts add up to n exactly and follow the shares. */
+function quotas(shares, n) {
+  const exact = shares.map((share) => share * n);
+  const counts = exact.map((value) => Math.floor(value));
+  let left = n - counts.reduce((sum, count) => sum + count, 0);
+  const order = exact
+    .map((value, index) => ({ index, remainder: value - Math.floor(value) }))
+    .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
+  for (const { index } of order) {
+    if (left === 0) break;
+    counts[index] += 1;
+    left -= 1;
+  }
+  return counts;
+}
+
+function unitId(prefix, position, n) {
+  return prefix + String(position).padStart(Math.max(3, String(n).length), '0');
+}
+
+function dealCards(profile, n, seed, idPrefix) {
+  const dealer = new Dealer(seed);
+  const slots = profile.dimensions.map((dimension) => {
+    const counts = quotas(
+      dimension.values.map((entry) => entry.share),
+      n
+    );
+    const column = [];
+    counts.forEach((count, index) => {
+      for (let k = 0; k < count; k += 1) column.push(index);
+    });
+    return dealer.shuffle(column);
+  });
+  const cards = [];
+  for (let position = 0; position < n; position += 1) {
+    const card = { id: unitId(idPrefix, position + 1, n) };
+    profile.dimensions.forEach((dimension, index) => {
+      const entry = dimension.values[slots[index][position]];
+      card[dimension.name] = entry.value;
+      // A note is a field of the whole dimension, so every card carries it, empty or not.
+      if (dimension.values.some((value) => value.note !== null))
+        card[dimension.name + '_note'] = entry.note ?? '';
+      for (const [name, [low, high]] of Object.entries(entry.ranges))
+        card[name] = dealer.between(low, high);
+    });
+    for (const [name, [low, high]] of Object.entries(profile.ranges))
+      card[name] = dealer.between(low, high);
+    for (const [name, pool] of Object.entries(profile.pools))
+      card[name] = pool[dealer.below(pool.length)];
+    cards.push(card);
+  }
+  return cards;
+}
+
+function listCards(units, idPrefix) {
+  const cards = units.map((unit, index) => ({
+    ...unit,
+    id: unit.id ?? unitId(idPrefix, index + 1, units.length),
+  }));
+  // Answer files are named by id, and some file systems fold case.
+  if (new Set(cards.map((card) => card.id.toLowerCase())).size !== cards.length)
+    throw new Error('Swarm: jury unit ids must be distinct once dealt, whatever their case.');
+  return cards;
+}
+
+module.exports = { Dealer, quotas, unitId, dealCards, listCards };

package/tools/cli/lib/swarm-defaults.js

@@ -0,0 +1,6 @@
+/** The swarm block bmad-plus install writes; an absent block in a project means these values. */
+'use strict';
+
+const SWARM_DEFAULTS = Object.freeze({ budget: 26, wave: 10, media_credits: 'ask' });
+
+module.exports = { SWARM_DEFAULTS };