bmad-overlay 0.1.1

package/install/install-overlay.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import process from "process";
+import { execFileSync } from "child_process";
+
+const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
+const OVERLAY_ROOT = path.resolve(SCRIPT_DIR, "..");
+const VALID_MODES = new Set(["codex", "claude-code", "bmad", "full"]);
+
+main();
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const mode = args.mode || "full";
+  const target = args.target || process.cwd();
+  const mergeBmad = args["merge-bmad"] === true || args["merge-bmad"] === "true";
+
+  if (!VALID_MODES.has(mode)) {
+    fail(`Unknown mode '${mode}'. Valid modes: codex, claude-code, bmad, full`);
+  }
+  if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+    fail(`Target project does not exist: ${target}`);
+  }
+
+  const targetOverlayDir = path.join(target, "overlay");
+  copyDir(OVERLAY_ROOT, targetOverlayDir, new Set([".DS_Store", "node_modules"]));
+
+  ensureDir(path.join(target, "docs"));
+  ensureDir(path.join(target, "docs", "features"));
+  ensureDir(path.join(target, "docs", "studio", "runs"));
+  ensureDir(path.join(target, ".overlay"));
+  ensureDir(path.join(target, "scripts"));
+
+  installDocs(target);
+  installRuntimeWrappers(target);
+  installMetadata(target, mode);
+
+  if (mode === "claude-code" || mode === "full") {
+    installClaudeFiles(target);
+  }
+
+  if (mode === "codex" || mode === "full") {
+    installCodexFiles(target);
+  }
+
+  if (mode === "bmad" || mode === "full") {
+    installBmadFiles(target);
+    if (mergeBmad) {
+      applyBmadMerge(target);
+    }
+  }
+
+  printSummary(target, mode, mergeBmad);
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    i += 1;
+  }
+  return args;
+}
+
+function installDocs(target) {
+  copyIfMissing(
+    path.join(OVERLAY_ROOT, "templates", "docs-index.md"),
+    path.join(target, "docs", "index.md")
+  );
+  copyIfMissing(
+    path.join(OVERLAY_ROOT, "templates", "feature-index.md"),
+    path.join(target, "docs", "features", "_template.index.md")
+  );
+}
+
+function installClaudeFiles(target) {
+  copyIfMissing(
+    path.join(OVERLAY_ROOT, "templates", "CLAUDE.md"),
+    path.join(target, "CLAUDE.md")
+  );
+  ensureDir(path.join(target, ".claude"));
+  writeText(
+    path.join(target, ".claude", "overlay-mode.md"),
+    [
+      "# Claude Code Overlay Mode",
+      "",
+      "This project has the BMAD overlay installed for Claude Code.",
+      "",
+      "Primary runtime entry points:",
+      "- `scripts/overlay-run-claude.sh`",
+      "- `scripts/overlay-execute-claude.sh`",
+      "",
+      "Primary state files:",
+      "- `docs/studio/current-stage.yaml`",
+      "- `docs/studio/run-manifest.md`",
+    ].join("\n")
+  );
+}
+
+function installCodexFiles(target) {
+  ensureDir(path.join(target, ".codex"));
+  writeText(
+    path.join(target, ".codex", "overlay-mode.md"),
+    [
+      "# Codex Overlay Mode",
+      "",
+      "This project has the BMAD overlay installed for Codex.",
+      "",
+      "Primary runtime entry points:",
+      "- `scripts/overlay-run-codex.sh`",
+      "- `scripts/overlay-execute-codex.sh`",
+      "",
+      "Primary state files:",
+      "- `docs/studio/current-stage.yaml`",
+      "- `docs/studio/run-manifest.md`",
+    ].join("\n")
+  );
+}
+
+function installBmadFiles(target) {
+  const appliedDir = path.join(target, "overlay-applied");
+  ensureDir(appliedDir);
+  ensureDir(path.join(appliedDir, "customizations"));
+  copyDir(path.join(OVERLAY_ROOT, "customizations"), path.join(appliedDir, "customizations"));
+  copyFile(
+    path.join(OVERLAY_ROOT, "config", "agent-map.yaml"),
+    path.join(appliedDir, "agent-map.yaml")
+  );
+  writeText(
+    path.join(appliedDir, "README.md"),
+    [
+      "# Overlay Applied",
+      "",
+      "This folder contains BMAD integration artifacts to merge into the target project.",
+      "",
+      "Files:",
+      "- `customizations/` for `_bmad/_config/agents/*.customize.yaml`",
+      "- `agent-map.yaml` for overlay council-to-BMAD role mapping",
+      "",
+      "Next step:",
+      "- merge the customization snippets into `_bmad/_config/agents/`",
+      "- rerun `npx bmad-method install` in the target project",
+    ].join("\n")
+  );
+}
+
+function applyBmadMerge(target) {
+  const mergeScript = path.join(OVERLAY_ROOT, "install", "merge-bmad-customizations.mjs");
+  execFileSync("node", [mergeScript, "--target", target], {
+    cwd: OVERLAY_ROOT,
+    stdio: "inherit",
+  });
+}
+
+function installRuntimeWrappers(target) {
+  const scripts = {
+    "overlay-run-codex.sh": `#!/usr/bin/env bash
+set -euo pipefail
+node overlay/runtime/codex-stage-runner.js run-to-close --studio-dir docs/studio --executor codex-cli --request "\${*:-Create a SaaS project}"`,
+    "overlay-run-claude.sh": `#!/usr/bin/env bash
+set -euo pipefail
+node overlay/runtime/codex-stage-runner.js run-to-close --studio-dir docs/studio --executor claude-code --request "\${*:-Create a SaaS project}"`,
+    "overlay-run-auto.sh": `#!/usr/bin/env bash
+set -euo pipefail
+node overlay/runtime/codex-stage-runner.js run-to-close --studio-dir docs/studio --executor heuristic --request "\${*:-Create a SaaS project}"`,
+    "overlay-execute-codex.sh": `#!/usr/bin/env bash
+set -euo pipefail
+node overlay/runtime/codex-stage-runner.js execute-stage --studio-dir docs/studio --advance --executor codex-cli`,
+    "overlay-execute-claude.sh": `#!/usr/bin/env bash
+set -euo pipefail
+node overlay/runtime/codex-stage-runner.js execute-stage --studio-dir docs/studio --advance --executor claude-code`,
+    "overlay-status.sh": `#!/usr/bin/env bash
+set -euo pipefail
+node overlay/runtime/codex-orchestrator.js status --studio-dir docs/studio`,
+  };
+
+  for (const [name, content] of Object.entries(scripts)) {
+    const scriptPath = path.join(target, "scripts", name);
+    writeText(scriptPath, content);
+    fs.chmodSync(scriptPath, 0o755);
+  }
+}
+
+function installMetadata(target, mode) {
+  const metadata = {
+    installed_at: new Date().toISOString(),
+    mode,
+    overlay_dir: "overlay",
+    runtime_entrypoints: {
+      run_codex: "scripts/overlay-run-codex.sh",
+      run_claude: "scripts/overlay-run-claude.sh",
+      run_auto: "scripts/overlay-run-auto.sh",
+      execute_codex: "scripts/overlay-execute-codex.sh",
+      execute_claude: "scripts/overlay-execute-claude.sh",
+      status: "scripts/overlay-status.sh",
+    },
+    docs_dir: "docs/studio",
+  };
+  writeText(path.join(target, ".overlay", "setup.json"), `${JSON.stringify(metadata, null, 2)}\n`);
+}
+
+function printSummary(target, mode, mergeBmad) {
+  const lines = [
+    `Overlay installed in: ${target}`,
+    `Mode: ${mode}`,
+    "Installed assets:",
+    "- overlay/",
+    "- docs/index.md and docs/features/_template.index.md when missing",
+    "- docs/studio/ runtime directories",
+    "- scripts/overlay-*.sh wrappers",
+    "- .overlay/setup.json",
+  ];
+
+  if (mode === "claude-code" || mode === "full") {
+    lines.push("- CLAUDE.md when missing");
+    lines.push("- .claude/overlay-mode.md");
+  }
+  if (mode === "codex" || mode === "full") {
+    lines.push("- .codex/overlay-mode.md");
+  }
+  if (mode === "bmad" || mode === "full") {
+    lines.push("- overlay-applied/customizations/");
+    lines.push("- overlay-applied/agent-map.yaml");
+    lines.push(mergeBmad
+      ? "- BMAD customizations merged into _bmad/_config/agents/"
+      : "Next BMAD step: merge snippets into _bmad/_config/agents/ and run `npx bmad-method install`.");
+  }
+
+  console.log(lines.join("\n"));
+}
+
+function copyIfMissing(source, target) {
+  if (!fs.existsSync(target)) {
+    copyFile(source, target);
+  }
+}
+
+function copyFile(source, target) {
+  ensureDir(path.dirname(target));
+  fs.copyFileSync(source, target);
+}
+
+function copyDir(source, target, exclude = new Set()) {
+  ensureDir(target);
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    if (exclude.has(entry.name)) continue;
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(sourcePath, targetPath, exclude);
+    } else {
+      copyFile(sourcePath, targetPath);
+    }
+  }
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeText(file, content) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, content, "utf8");
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}

package/install/install-overlay.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "${1:-}" = "" ]; then
+  echo "Usage: $0 /path/to/target-project [mode] [merge-bmad:true|false]"
+  exit 1
+fi
+
+SOURCE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+TARGET_DIR="$1"
+MODE="${2:-full}"
+MERGE_BMAD="${3:-false}"
+
+node "$SOURCE_DIR/install/install-overlay.mjs" --target "$TARGET_DIR" --mode "$MODE" --merge-bmad "$MERGE_BMAD"

package/install/merge-bmad-customizations.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import process from "process";
+
+const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
+const OVERLAY_ROOT = path.resolve(SCRIPT_DIR, "..");
+const SECTION_NAMES = ["critical_actions", "memories", "menu", "prompts"];
+const FILES = ["bmm-pm.customize.yaml", "bmm-dev.customize.yaml", "bmm-qa.customize.yaml"];
+
+main();
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const target = args.target || process.cwd();
+  const targetAgentsDir = path.join(target, "_bmad", "_config", "agents");
+
+  if (!fs.existsSync(targetAgentsDir)) {
+    fail(`BMAD agent customization directory not found: ${targetAgentsDir}`);
+  }
+
+  for (const fileName of FILES) {
+    const sourcePath = path.join(OVERLAY_ROOT, "customizations", fileName);
+    const targetPath = path.join(targetAgentsDir, fileName);
+    if (!fs.existsSync(targetPath)) {
+      fail(`Target BMAD customization file not found: ${targetPath}`);
+    }
+
+    const sourceSections = parseSections(readText(sourcePath));
+    const merged = mergeIntoTarget(readText(targetPath), sourceSections);
+    fs.writeFileSync(targetPath, merged, "utf8");
+  }
+
+  console.log(`Merged overlay customizations into: ${targetAgentsDir}`);
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    i += 1;
+  }
+  return args;
+}
+
+function parseSections(text) {
+  const lines = text.split("\n");
+  const result = {};
+  let current = null;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const sectionMatch = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (sectionMatch && SECTION_NAMES.includes(sectionMatch[1])) {
+      current = sectionMatch[1];
+      result[current] = [];
+      continue;
+    }
+    if (!current) continue;
+    if (/^[A-Za-z_]+:/.test(line)) {
+      current = null;
+      continue;
+    }
+    if (!line.startsWith("  - ")) {
+      continue;
+    }
+
+    const itemLines = [line];
+    while (i + 1 < lines.length) {
+      const next = lines[i + 1];
+      if (/^[A-Za-z_]+:/.test(next) || next.startsWith("  - ")) break;
+      if (next.startsWith("    ") || next.trim() === "") {
+        itemLines.push(next);
+        i += 1;
+        continue;
+      }
+      break;
+    }
+    result[current].push(itemLines.join("\n").trimEnd());
+  }
+
+  return result;
+}
+
+function mergeIntoTarget(targetText, sourceSections) {
+  const lines = targetText.split("\n");
+  const sectionRanges = findSectionRanges(lines);
+
+  for (const sectionName of SECTION_NAMES) {
+    const additions = sourceSections[sectionName] || [];
+    if (additions.length === 0 || !sectionRanges[sectionName]) continue;
+
+    const { start, end } = sectionRanges[sectionName];
+    const blockLines = lines.slice(start, end);
+    const existingItems = parseItemsFromBlock(blockLines);
+    const seen = new Set(existingItems.map(normalizeItem));
+    const uniqueAdditions = additions.filter((item) => !seen.has(normalizeItem(item)));
+    if (uniqueAdditions.length === 0) continue;
+
+    const sectionHeader = lines[start];
+    const replacement = buildMergedSection(sectionHeader, existingItems, uniqueAdditions);
+    lines.splice(start, end - start, ...replacement);
+
+    const delta = replacement.length - (end - start);
+    for (const key of Object.keys(sectionRanges)) {
+      if (sectionRanges[key].start > start) {
+        sectionRanges[key].start += delta;
+        sectionRanges[key].end += delta;
+      } else if (sectionRanges[key].start === start) {
+        sectionRanges[key].end = sectionRanges[key].start + replacement.length;
+      }
+    }
+  }
+
+  return `${lines.join("\n").replace(/\n+$/, "\n")}`;
+}
+
+function findSectionRanges(lines) {
+  const ranges = {};
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = lines[i].match(/^([a-z_]+):\s*(.*)$/);
+    if (!match || !SECTION_NAMES.includes(match[1])) continue;
+    const name = match[1];
+    let end = i + 1;
+    while (end < lines.length && !/^[A-Za-z_]+:/.test(lines[end])) {
+      end += 1;
+    }
+    ranges[name] = { start: i, end };
+  }
+  return ranges;
+}
+
+function parseItemsFromBlock(blockLines) {
+  if (blockLines.length === 0) return [];
+  const items = [];
+  for (let i = 1; i < blockLines.length; i += 1) {
+    const line = blockLines[i];
+    if (!line.startsWith("  - ")) continue;
+    const itemLines = [line];
+    while (i + 1 < blockLines.length) {
+      const next = blockLines[i + 1];
+      if (next.startsWith("  - ") || /^[A-Za-z_]+:/.test(next)) break;
+      itemLines.push(next);
+      i += 1;
+    }
+    items.push(itemLines.join("\n").trimEnd());
+  }
+  return items;
+}
+
+function buildMergedSection(header, existingItems, uniqueAdditions) {
+  const mergedItems = [...existingItems, ...uniqueAdditions];
+  if (mergedItems.length === 0) {
+    return [`${header.replace(/:\s*.*/, ": []")}`];
+  }
+  return [header.replace(/:\s*.*/, ":"), ...mergedItems];
+}
+
+function normalizeItem(item) {
+  return item.replace(/\s+$/gm, "").trim();
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "bmad-overlay",
+  "version": "0.1.1",
+  "description": "Portable BMAD overlay kit for Codex, Claude Code, and BMAD projects",
+  "license": "MIT",
+  "files": [
+    "LICENSE",
+    "CHANGELOG.md",
+    "README.md",
+    "QUICKSTART.md",
+    "PUBLISH.md",
+    "agents/",
+    "config/",
+    "customizations/",
+    "install/",
+    "policies/",
+    "runtime/",
+    "skills/",
+    "templates/",
+    "workflows/"
+  ],
+  "bin": {
+    "bmad-overlay": "install/install-overlay.mjs",
+    "bmad-overlay-merge-bmad": "install/merge-bmad-customizations.mjs"
+  },
+  "scripts": {
+    "pack:check": "node install/check-package.mjs"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/policies/routing-policy.md

@@ -0,0 +1,60 @@
+# Routing Policy
+
+## Objectif
+
+Orienter chaque demande vers le bon niveau de ceremonie.
+
+## Entree
+
+La demande doit respecter le contrat:
+
+- nom
+- objectif
+- domaine
+- stack envisagee
+- contraintes
+- risques
+- definition minimale de succes
+
+## Modes
+
+### `quick`
+
+Choisir `quick` si:
+
+- une seule capacite principale
+- stack connue
+- peu d'integration externe
+- pas de contrainte forte de conformite
+- pas de complexite multi-tenant ou billing avance
+
+Pipeline:
+
+`product-brief -> quick-spec -> quick-flow-solo-dev -> code-review`
+
+### `structured`
+
+Choisir `structured` si au moins un point est vrai:
+
+- auth complexe
+- billing
+- multi-tenant
+- workflows metier multiples
+- integrateurs externes nombreux
+- exigences de fiabilite ou audit
+- equipe multi-contributeurs
+
+Pipeline:
+
+`analyst -> pm/prd -> ux -> architect -> create-epics-and-stories -> dev -> qa`
+
+## Rule of escalation
+
+Si une demande commence en `quick` mais expose ensuite:
+
+- un second domaine produit
+- une dette de cadrage
+- plusieurs inconnues techniques
+- des regressions repetitives
+
+alors elle doit basculer en `structured`.

package/runtime/README.md

@@ -0,0 +1,112 @@
+# Overlay Runtime
+
+This folder contains the first Codex-first runtime controller for the overlay.
+
+Companion runner:
+
+- `codex-stage-runner.js` executes the active stage from generated task files
+- supports `codex-cli`, `claude-code`, and `heuristic` executors
+
+## Current Scope
+
+The runtime controls the file-backed orchestration loop:
+
+- `start-run`
+- `launch-council`
+- `advance-stage`
+- `block-stage`
+- `resume-stage`
+- `close-run`
+- `status`
+
+It manages:
+
+- `current-stage.yaml`
+- `run-manifest.md`
+- run directories under `docs/studio/runs/`
+- council seat output targets
+- council seat and lead task files
+- output templates for seats, synthesis, and handoff
+
+It does not yet launch real LLM workers by itself.
+It is the autonomous control plane for the overlay state machine.
+
+The intended execution bridge is:
+
+- runtime launches a stage
+- runtime writes task files and templates
+- Codex uses `orchestrator-execute-active-stage`
+- runtime advances or blocks based on the produced artifacts
+
+## Command Examples
+
+```bash
+node overlay/runtime/codex-orchestrator.js start-run --request "Create a SaaS website for appointment booking"
+node overlay/runtime/codex-orchestrator.js launch-council
+node overlay/runtime/codex-orchestrator.js status
+node overlay/runtime/codex-orchestrator.js block-stage --reason "Missing synthesis" --missing docs/studio/runs/<run_id>/analysis-synthesis.md
+node overlay/runtime/codex-orchestrator.js resume-stage
+node overlay/runtime/codex-orchestrator.js close-run --reason "QA passed"
+node overlay/runtime/codex-stage-runner.js execute-stage --studio-dir docs/studio-runtime-test --advance
+node overlay/runtime/codex-stage-runner.js run-to-close --studio-dir docs/studio-runtime-test --request "Create a SaaS website"
+```
+
+## Safer Test Mode
+
+To avoid touching the main studio state, use a dedicated studio dir:
+
+```bash
+node overlay/runtime/codex-orchestrator.js start-run --studio-dir docs/studio-runtime-test --request "Create a SaaS website"
+```
+
+## Recommended Test Order
+
+1. `start-run`
+2. `launch-council`
+3. create seat outputs, synthesis, and handoff
+4. `advance-stage`
+5. `status`
+
+## Current Validation Status
+
+Smoke-tested on `docs/studio-runtime-test/` for:
+
+- `start-run`
+- `launch-council`
+- `advance-stage`
+- `block-stage`
+- `resume-stage`
+- `close-run`
+
+Multi-stage runtime proof also completed on `docs/studio-runtime-test-4/`:
+
+- real `analysis` artifact production
+- real `pm` artifact production
+- runtime advancement up to `architecture`
+
+End-to-end runtime proof completed on `docs/studio-runtime-test-5/`:
+
+- `analysis`
+- `pm`
+- `architecture`
+- `delivery`
+- `qa-review`
+- `closed`
+
+Fully autonomous runner proof completed on `docs/studio-runtime-test-6/`:
+
+- one `run-to-close` command
+- full planning pipeline execution
+- clean final `closed` state
+
+Executor fallback proof completed on `docs/studio-runtime-test-9/`:
+
+- `codex-cli` attempted first
+- single failure disables further `codex-cli` attempts for the run
+- heuristic fallback still closes the pipeline
+
+Claude Code fallback proof completed on `docs/studio-runtime-test-10/`:
+
+- `claude-code` attempted first
+- single timeout disables further `claude-code` attempts for the run
+- heuristic fallback still closes the pipeline