sdtk-kit 1.1.0 → 1.3.0

package/README.md

@@ -6,10 +6,11 @@
 npm install -g sdtk-kit
 ```
 
-After install, all five SDTK CLI tools are available globally:
+After install, all five SDTK CLI tools — plus the unified `sdtk` orchestrator — are available globally:
 
 | CLI           | Toolkit        | Purpose                                          |
 |---------------|----------------|--------------------------------------------------|
+| `sdtk`        | (all five)     | One-command setup: `sdtk init --runtime <r>`     |
 | `sdtk-spec`   | SDTK-SPEC      | Spec-first SDLC: PM → BA → ARCH → DEV → QA     |
 | `sdtk-design` | SDTK-DESIGN    | MVP design: idea → prototype → handoff           |
 | `sdtk-code`   | SDTK-CODE      | Governed coding: handoff → PR with review gates  |
@@ -19,13 +20,41 @@ After install, all five SDTK CLI tools are available globally:
 ## Quick start
 
 ```bash
-# Initialize the spec toolkit in your project
-sdtk-spec init --runtime claude   # or --runtime codex
+# Set up the chosen runtime for the whole suite in one command
+sdtk init --runtime claude   # or --runtime codex
 
 # Generate a 17-file spec scaffold for your first feature
 sdtk-spec generate --feature-key MY_FEATURE
 ```
 
+## Unified init: `sdtk init`
+
+`sdtk init --runtime <claude|codex>` initialises **all five toolkits** in one step
+— mirroring how `npm install -g sdtk-kit` installs every toolkit at once. It runs
+each toolkit's own, already-shipped `init` in order:
+
+```
+sdtk-spec → sdtk-ops → sdtk-code   (with --runtime <r>)
+sdtk-design → sdtk-wiki            (their own non-runtime init)
+```
+
+```bash
+sdtk init --runtime claude
+sdtk init --runtime codex --project-path ./my-app
+sdtk init --runtime claude --keep-going    # continue past a failing toolkit
+```
+
+Options: `--runtime <claude|codex>` (required), `--runtime-scope <scope>`,
+`--project-path <path>`, `--force`, `--skip-runtime-assets`, `--keep-going`
+(default is fail-fast — stop at the first failing toolkit), `--verbose`.
+`--runtime`, `--runtime-scope`, and `--skip-runtime-assets` apply to the runtime
+toolkits (spec/ops/code); `sdtk-design` and `sdtk-wiki` receive only
+`--project-path`, `--force`, and `--verbose`.
+
+`sdtk init` is a thin orchestrator: it re-implements no init logic, writes no files
+itself, and runs no PowerShell of its own — every side effect happens inside the
+delegated per-toolkit init. The per-toolkit CLIs remain fully available standalone.
+
 ## Unified vs standalone install
 
 You have two install options:
@@ -60,9 +89,14 @@ because `npm install -g <pkg>` only links the bin entries of the top-level
 package, never of its dependencies. A pure deps-only meta-package would install
 the sub-toolkits but leave zero CLIs on PATH.
 
-Do not remove the `bin` field or the `bin/` shims — they are the mechanism that
-puts `sdtk-spec`, `sdtk-code`, `sdtk-ops`, `sdtk-design`, and `sdtk-wiki` on PATH
-after a global install.
+The umbrella also ships its own `sdtk` orchestrator bin (`bin/sdtk.js` + `src/`),
+which delegates `sdtk init` to each sub-toolkit's published bin via subprocess
+(`require.resolve` of the kit's `package.json` `bin` map, spawned with the current
+Node). It adds no new dependency and re-implements no init logic.
+
+Do not remove the `bin` field, the `bin/` shims, or `bin/sdtk.js` + `src/` — they
+are the mechanism that puts `sdtk`, `sdtk-spec`, `sdtk-code`, `sdtk-ops`,
+`sdtk-design`, and `sdtk-wiki` on PATH after a global install.
 
 ## Version pinning model
 
@@ -72,15 +106,15 @@ after a global install.
 - **Major version bumps** in any sub-toolkit require a coordinated `sdtk-kit` major-bump and re-publish.
 - If you need exact version control per toolkit, use standalone packages instead.
 
-Current pinned versions (as of sdtk-kit v1.0.0):
+Current dependency ranges (as of sdtk-kit v1.3.0):
 
 | Package          | Version |
 |------------------|---------|
 | sdtk-spec-kit    | ^0.4.7  |
-| sdtk-code-kit    | ^0.1.3  |
+| sdtk-code-kit    | ^0.3.0  |
 | sdtk-ops-kit     | ^0.2.4  |
 | sdtk-design-kit  | ^0.3.0  |
-| sdtk-wiki-kit    | ^0.1.4  |
+| sdtk-wiki-kit    | ^0.2.0  |
 
 ## Updating
 
@@ -114,6 +148,27 @@ npm config get prefix
 
 Ensure `<prefix>/bin` is in `PATH`.
 
+**Only three CLIs are visible after installing sdtk-kit**
+
+If `sdtk-spec`, `sdtk-code`, and `sdtk-ops` are visible but `sdtk-design` or `sdtk-wiki` are missing, the usual cause is a stale global install, an old npm prefix on `PATH`, or a shell command cache rather than the current `sdtk-kit` package.
+
+Reset and verify from a fresh shell:
+
+```bash
+npm uninstall -g sdtk-kit sdtk-spec-kit sdtk-code-kit sdtk-ops-kit sdtk-design-kit sdtk-wiki-kit
+npm cache verify
+npm install -g sdtk-kit@latest
+hash -r
+command -v sdtk-spec sdtk-code sdtk-ops sdtk-design sdtk-wiki
+sdtk-spec --version
+sdtk-code --version
+sdtk-ops --version
+sdtk-design --version
+sdtk-wiki --version
+```
+
+On Windows PowerShell, close and reopen the terminal after reinstalling, then use `where.exe sdtk-spec`, `where.exe sdtk-design`, and the same `--version` commands.
+
 **Windows PATH issues**
 
 On Windows, npm global binaries land in `%APPDATA%\npm`. Make sure this is in your `PATH`. Run `npm config get prefix` to confirm the location.

package/bin/sdtk.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+"use strict";
+
+// `sdtk` — unified entry point for the SDTK suite (BK-268).
+//
+//   sdtk init --runtime <claude|codex>   one-command setup for all five toolkits
+//   sdtk --help                          top-level help
+//   sdtk --version                       sdtk-kit version + resolved per-kit versions
+//   sdtk                                 no args → help
+//
+// `init` delegates to each toolkit's own shipped init (see src/lib/unified-init.js).
+
+const SUB_KITS = [
+  "sdtk-spec-kit",
+  "sdtk-ops-kit",
+  "sdtk-code-kit",
+  "sdtk-design-kit",
+  "sdtk-wiki-kit",
+];
+
+function helpText() {
+  return [
+    "sdtk — unified SDTK suite CLI",
+    "",
+    "Usage:",
+    "  sdtk init --runtime <claude|codex> [options]   Initialise all five toolkits",
+    "  sdtk --help                                    Show this help",
+    "  sdtk --version                                 Show versions",
+    "",
+    "init options:",
+    "  --runtime <claude|codex>   Required. Runtime to install for spec/ops/code.",
+    "  --runtime-scope <scope>    Optional. Forwarded to the runtime toolkits.",
+    "  --project-path <path>      Optional. Target project directory.",
+    "  --force                    Re-initialise existing assets.",
+    "  --skip-runtime-assets      Skip runtime asset install (runtime toolkits).",
+    "  --keep-going               Continue past a failing toolkit (default: fail-fast).",
+    "  --verbose                  Verbose per-toolkit output.",
+    "",
+    "Runs: sdtk-spec → sdtk-ops → sdtk-code (with --runtime) → sdtk-design → sdtk-wiki",
+    "(sdtk-design and sdtk-wiki run their own non-runtime init).",
+    "",
+    "Standalone per-toolkit CLIs remain available: sdtk-spec, sdtk-ops, sdtk-code,",
+    "sdtk-design, sdtk-wiki.",
+    "",
+    "Docs: https://sdtk.dev",
+  ].join("\n");
+}
+
+function versionText() {
+  // eslint-disable-next-line global-require
+  const self = require("../package.json");
+  const lines = [`sdtk-kit ${self.version}`];
+  for (const kit of SUB_KITS) {
+    let version = "not resolved";
+    try {
+      // eslint-disable-next-line global-require
+      version = require(`${kit}/package.json`).version;
+    } catch (err) {
+      version = "not resolved";
+    }
+    lines.push(`  ${kit.padEnd(15)} ${version}`);
+  }
+  return lines.join("\n");
+}
+
+function main(argv) {
+  const command = argv[0];
+
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    console.log(helpText());
+    return 0;
+  }
+
+  if (command === "--version" || command === "-v") {
+    console.log(versionText());
+    return 0;
+  }
+
+  if (command === "init") {
+    // eslint-disable-next-line global-require
+    const { cmdInit } = require("../src/commands/init");
+    return cmdInit(argv.slice(1));
+  }
+
+  console.error(`sdtk: unknown command '${command}'.`);
+  console.error("Run `sdtk --help` for usage.");
+  return 2;
+}
+
+process.exitCode = main(process.argv.slice(2));

package/package.json

@@ -1,60 +1,65 @@
-{
-  "name": "sdtk-kit",
-  "version": "1.1.0",
-  "description": "Install all five SDTK toolkits in one command. Meta-package for sdtk-spec-kit, sdtk-code-kit, sdtk-ops-kit, sdtk-design-kit, and sdtk-wiki-kit.",
-  "type": "commonjs",
-  "bin": {
-    "sdtk-spec": "bin/sdtk-spec.js",
-    "sdtk-code": "bin/sdtk-code.js",
-    "sdtk-ops": "bin/sdtk-ops.js",
-    "sdtk-design": "bin/sdtk-design.js",
-    "sdtk-wiki": "bin/sdtk-wiki.js"
-  },
-  "files": [
-    "bin/",
-    "scripts/",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "pack:smoke": "npm pack --dry-run"
-  },
-  "dependencies": {
-    "sdtk-spec-kit": "^0.4.7",
-    "sdtk-code-kit": "^0.2.0",
-    "sdtk-ops-kit": "^0.2.4",
-    "sdtk-design-kit": "^0.3.0",
-    "sdtk-wiki-kit": "^0.2.0"
-  },
-  "engines": {
-    "node": ">=18.13.0"
-  },
-  "keywords": [
-    "sdtk",
-    "sdtk-kit",
-    "sdtk-spec",
-    "sdtk-code",
-    "sdtk-ops",
-    "sdtk-design",
-    "sdtk-wiki",
-    "cli",
-    "toolkit",
-    "ai-workflow",
-    "solo-founder",
-    "mvp"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/codexsdtk/sdtk-toolkit.git",
-    "directory": "products/sdtk-kit/distribution/sdtk-kit"
-  },
-  "homepage": "https://sdtk.dev",
-  "bugs": {
-    "url": "https://github.com/codexsdtk/sdtk-toolkit/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "sdtk-kit",
+  "version": "1.3.0",
+  "description": "Install all five SDTK toolkits in one command. Meta-package for sdtk-spec-kit, sdtk-code-kit, sdtk-ops-kit, sdtk-design-kit, and sdtk-wiki-kit.",
+  "type": "commonjs",
+  "bin": {
+    "sdtk": "bin/sdtk.js",
+    "sdtk-spec": "bin/sdtk-spec.js",
+    "sdtk-code": "bin/sdtk-code.js",
+    "sdtk-ops": "bin/sdtk-ops.js",
+    "sdtk-design": "bin/sdtk-design.js",
+    "sdtk-wiki": "bin/sdtk-wiki.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node scripts/unified-init.test.js",
+    "install:smoke:local": "node scripts/install-smoke.js --mode local",
+    "install:smoke:published": "node scripts/install-smoke.js --mode published --package sdtk-kit@latest",
+    "pack:smoke": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "sdtk-spec-kit": "^0.4.7",
+    "sdtk-code-kit": "^0.3.0",
+    "sdtk-ops-kit": "^0.2.4",
+    "sdtk-design-kit": "^0.3.0",
+    "sdtk-wiki-kit": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=18.13.0"
+  },
+  "keywords": [
+    "sdtk",
+    "sdtk-kit",
+    "sdtk-spec",
+    "sdtk-code",
+    "sdtk-ops",
+    "sdtk-design",
+    "sdtk-wiki",
+    "cli",
+    "toolkit",
+    "ai-workflow",
+    "solo-founder",
+    "mvp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codexsdtk/sdtk-toolkit.git",
+    "directory": "products/sdtk-kit/distribution/sdtk-kit"
+  },
+  "homepage": "https://sdtk.dev",
+  "bugs": {
+    "url": "https://github.com/codexsdtk/sdtk-toolkit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install-smoke.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const PACKAGE_JSON = path.join(PACKAGE_ROOT, "package.json");
+const TOOLKITS = Object.freeze([
+  { cli: "sdtk-spec", packageName: "sdtk-spec-kit" },
+  { cli: "sdtk-code", packageName: "sdtk-code-kit" },
+  { cli: "sdtk-ops", packageName: "sdtk-ops-kit" },
+  { cli: "sdtk-design", packageName: "sdtk-design-kit" },
+  { cli: "sdtk-wiki", packageName: "sdtk-wiki-kit" },
+]);
+
+function usage() {
+  return [
+    "Usage:",
+    "  node scripts/install-smoke.js --mode local [--package ./sdtk-kit-1.2.0.tgz] [--keep-prefix]",
+    "  node scripts/install-smoke.js --mode published [--package sdtk-kit@latest] [--keep-prefix]",
+    "",
+    "Modes:",
+    "  local      Packs the local sdtk-kit package when --package is omitted, then installs it into a clean prefix.",
+    "  published  Installs a published package spec, defaulting to sdtk-kit@latest, into a clean prefix.",
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const args = { mode: "local", packageSpec: null, keepPrefix: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--mode") {
+      args.mode = argv[++i];
+    } else if (arg === "--package") {
+      args.packageSpec = argv[++i];
+    } else if (arg === "--keep-prefix") {
+      args.keepPrefix = true;
+    } else if (arg === "--help" || arg === "-h") {
+      console.log(usage());
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${arg}\n${usage()}`);
+    }
+  }
+  if (!new Set(["local", "published"]).has(args.mode)) {
+    throw new Error(`Invalid --mode: ${args.mode}\n${usage()}`);
+  }
+  return args;
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || PACKAGE_ROOT,
+    env: options.env || process.env,
+    encoding: "utf8",
+    shell: options.shell || false,
+  });
+  if (result.status !== 0) {
+    throw new Error([
+      `Command failed: ${command} ${args.join(" ")}`,
+      `exit=${result.status}`,
+      result.stdout ? `stdout:\n${result.stdout}` : "stdout: <empty>",
+      result.stderr ? `stderr:\n${result.stderr}` : "stderr: <empty>",
+    ].join("\n"));
+  }
+  return result;
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function assertPackageMetadata(packageJson) {
+  const missingBins = [];
+  const missingDeps = [];
+  for (const toolkit of TOOLKITS) {
+    if (!packageJson.bin || packageJson.bin[toolkit.cli] !== `bin/${toolkit.cli}.js`) {
+      missingBins.push(toolkit.cli);
+    }
+    if (!packageJson.dependencies || !packageJson.dependencies[toolkit.packageName]) {
+      missingDeps.push(toolkit.packageName);
+    }
+  }
+  if (missingBins.length || missingDeps.length) {
+    throw new Error(`sdtk-kit metadata is incomplete: missingBins=${missingBins.join(",") || "none"}; missingDeps=${missingDeps.join(",") || "none"}`);
+  }
+}
+
+function packLocalPackage() {
+  const result = run("npm", ["pack", "--json"], { cwd: PACKAGE_ROOT });
+  const entries = JSON.parse(result.stdout);
+  if (!Array.isArray(entries) || entries.length !== 1 || !entries[0].filename) {
+    throw new Error(`Unexpected npm pack --json output: ${result.stdout}`);
+  }
+  return path.join(PACKAGE_ROOT, entries[0].filename);
+}
+
+function npmBinPath(prefix, cli) {
+  const binDir = path.join(prefix, "node_modules", ".bin");
+  const candidates = process.platform === "win32"
+    ? [path.join(binDir, `${cli}.cmd`), path.join(binDir, `${cli}.ps1`), path.join(binDir, cli)]
+    : [path.join(binDir, cli)];
+  return candidates.find((candidate) => fs.existsSync(candidate));
+}
+
+function installedPackageJson(prefix, packageName) {
+  const candidates = [
+    path.join(prefix, "node_modules", packageName, "package.json"),
+    path.join(prefix, "node_modules", "sdtk-kit", "node_modules", packageName, "package.json"),
+  ];
+  const found = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!found) {
+    throw new Error(`Cannot find installed package.json for ${packageName} under ${prefix}`);
+  }
+  return readJson(found);
+}
+
+function runCliVersion(binPath) {
+  return run(binPath, ["--version"], { shell: process.platform === "win32" });
+}
+
+function smokeInstall(packageSpec, mode, keepPrefix) {
+  const prefix = fs.mkdtempSync(path.join(os.tmpdir(), "sdtk-kit-install-smoke-"));
+  let packedTarball = null;
+  try {
+    const localPackageJson = readJson(PACKAGE_JSON);
+    assertPackageMetadata(localPackageJson);
+
+    let installSpec = packageSpec;
+    if (mode === "local" && !installSpec) {
+      packedTarball = packLocalPackage();
+      installSpec = packedTarball;
+    }
+    if (mode === "published" && !installSpec) {
+      installSpec = "sdtk-kit@latest";
+    }
+    if (!installSpec) {
+      throw new Error("No package spec resolved for install smoke.");
+    }
+
+    console.log(`[sdtk-kit smoke] mode=${mode}`);
+    console.log(`[sdtk-kit smoke] prefix=${prefix}`);
+    console.log(`[sdtk-kit smoke] install=${installSpec}`);
+    run("npm", ["install", "--prefix", prefix, installSpec]);
+
+    const installedMeta = installedPackageJson(prefix, "sdtk-kit");
+    assertPackageMetadata(installedMeta);
+    console.log(`[sdtk-kit smoke] installed sdtk-kit ${installedMeta.version}`);
+
+    for (const toolkit of TOOLKITS) {
+      const binPath = npmBinPath(prefix, toolkit.cli);
+      if (!binPath) {
+        throw new Error(`Missing CLI shim for ${toolkit.cli} in ${path.join(prefix, "node_modules", ".bin")}`);
+      }
+      const expected = installedPackageJson(prefix, toolkit.packageName).version;
+      const result = runCliVersion(binPath);
+      const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+      if (!output.includes(expected)) {
+        throw new Error(`${toolkit.cli} --version did not include installed ${toolkit.packageName} version ${expected}. Output: ${output}`);
+      }
+      console.log(`[sdtk-kit smoke] ${toolkit.cli} -> ${output}`);
+    }
+
+    console.log("[sdtk-kit smoke] PASS all five CLI shims exist and --version checks passed.");
+  } finally {
+    if (packedTarball && fs.existsSync(packedTarball)) {
+      fs.rmSync(packedTarball, { force: true });
+    }
+    if (keepPrefix) {
+      console.log(`[sdtk-kit smoke] kept prefix: ${prefix}`);
+    } else {
+      fs.rmSync(prefix, { recursive: true, force: true });
+    }
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  smokeInstall(args.packageSpec, args.mode, args.keepPrefix);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`[sdtk-kit smoke] FAIL ${error.message}`);
+  process.exit(1);
+}

package/scripts/postinstall.js

@@ -28,9 +28,12 @@ const lines = [
   "    sdtk-ops     — Operations: deploy → smoke → sign-off",
   "    sdtk-wiki    — Local second brain: your project memory",
   "",
-  "  Start with the SPEC toolkit:",
+  "  Set up the whole suite in one command:",
+  "",
+  "    sdtk init --runtime claude   (or --runtime codex)",
+  "",
+  "  Then generate your first feature spec:",
   "",
-  "    sdtk-spec init --runtime claude   (or --runtime codex)",
   "    sdtk-spec generate --feature-key <YOUR_FEATURE>",
   "",
   "  Docs: https://sdtk.dev",

package/scripts/unified-init.test.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+"use strict";
+
+// Offline unit tests for the unified-init orchestrator (BK-268).
+// No real PowerShell, no network, no child processes — every effectful dep
+// (spawn / resolveBin / powershellCheck / log) is injected as a spy/stub.
+
+const assert = require("assert");
+const {
+  runUnifiedInit,
+  buildInitArgs,
+  TOOLKITS,
+  ToolkitResolveError,
+} = require("../src/lib/unified-init");
+
+const RUNTIME_KITS = ["sdtk-spec", "sdtk-ops", "sdtk-code"];
+const NON_RUNTIME_KITS = ["sdtk-design", "sdtk-wiki"];
+
+// Build an injected deps object with a recording spawn spy.
+// `failures` maps toolkit name → exit code to return (default 0).
+// `unresolvable` is a Set of kit package names that resolveBin should reject.
+function makeDeps({ failures = {}, unresolvable = new Set(), psOk = true } = {}) {
+  const spawnCalls = [];
+  const resolveCalls = [];
+  const logs = [];
+  return {
+    spawnCalls,
+    resolveCalls,
+    logs,
+    deps: {
+      spawn(binPath, argv, toolkit) {
+        spawnCalls.push({ binPath, argv, toolkit: toolkit.name });
+        const code = failures[toolkit.name] || 0;
+        return { status: code, stderr: code ? `stub stderr for ${toolkit.name}` : "" };
+      },
+      resolveBin(kitPkg, binName) {
+        resolveCalls.push(kitPkg);
+        if (unresolvable.has(kitPkg)) {
+          throw new ToolkitResolveError(kitPkg);
+        }
+        return `/stub/node_modules/${kitPkg}/bin/${binName}.js`;
+      },
+      powershellCheck() {
+        return { ok: psOk, exe: "pwsh" };
+      },
+      log(line) {
+        logs.push(line);
+      },
+    },
+  };
+}
+
+// Pull the argv recorded for one toolkit's spawn.
+function argvFor(spawnCalls, name) {
+  const call = spawnCalls.find((c) => c.toolkit === name);
+  return call ? call.argv : null;
+}
+
+const tests = [];
+function test(name, fn) {
+  tests.push({ name, fn });
+}
+
+// ── T1 — runtime claude forwards correctly to runtime kits ──────────────────
+test("T1 runtime=claude spawns spec/ops/code with init --runtime claude", () => {
+  const h = makeDeps();
+  const { exitCode } = runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(exitCode, 0);
+  for (const kit of RUNTIME_KITS) {
+    const argv = argvFor(h.spawnCalls, kit);
+    assert.deepStrictEqual(argv, ["init", "--runtime", "claude"], `${kit} argv`);
+  }
+});
+
+// ── T2 — runtime codex ──────────────────────────────────────────────────────
+test("T2 runtime=codex forwards --runtime codex", () => {
+  const h = makeDeps();
+  const { exitCode } = runUnifiedInit({ runtime: "codex" }, h.deps);
+  assert.strictEqual(exitCode, 0);
+  for (const kit of RUNTIME_KITS) {
+    assert.deepStrictEqual(argvFor(h.spawnCalls, kit), ["init", "--runtime", "codex"]);
+  }
+});
+
+// ── T3 — flag forwarding (runtime subset vs full) ───────────────────────────
+test("T3 forwards shared flags to runtime kits; only subset to design/wiki", () => {
+  const h = makeDeps();
+  const opts = {
+    runtime: "claude",
+    runtimeScope: "user",
+    projectPath: "/tmp/proj",
+    force: true,
+    skipRuntimeAssets: true,
+    verbose: true,
+  };
+  runUnifiedInit(opts, h.deps);
+
+  for (const kit of RUNTIME_KITS) {
+    const argv = argvFor(h.spawnCalls, kit);
+    assert.deepStrictEqual(
+      argv,
+      [
+        "init",
+        "--runtime",
+        "claude",
+        "--runtime-scope",
+        "user",
+        "--project-path",
+        "/tmp/proj",
+        "--force",
+        "--skip-runtime-assets",
+        "--verbose",
+      ],
+      `${kit} full forward`
+    );
+  }
+  for (const kit of NON_RUNTIME_KITS) {
+    const argv = argvFor(h.spawnCalls, kit);
+    assert.deepStrictEqual(
+      argv,
+      ["init", "--project-path", "/tmp/proj", "--force", "--verbose"],
+      `${kit} subset`
+    );
+    assert.ok(!argv.includes("--runtime"), `${kit} must not get --runtime`);
+    assert.ok(!argv.includes("--runtime-scope"), `${kit} must not get --runtime-scope`);
+    assert.ok(!argv.includes("--skip-runtime-assets"), `${kit} must not get --skip-runtime-assets`);
+  }
+});
+
+// ── T4 — missing/invalid runtime → exit 2, zero spawns ──────────────────────
+test("T4 missing runtime → exit 2, no spawns", () => {
+  const h = makeDeps();
+  const { exitCode } = runUnifiedInit({}, h.deps);
+  assert.strictEqual(exitCode, 2);
+  assert.strictEqual(h.spawnCalls.length, 0);
+});
+test("T4b invalid runtime → exit 2, no spawns", () => {
+  const h = makeDeps();
+  const { exitCode } = runUnifiedInit({ runtime: "bogus" }, h.deps);
+  assert.strictEqual(exitCode, 2);
+  assert.strictEqual(h.spawnCalls.length, 0);
+});
+
+// ── T5 — PowerShell missing → exit 3, zero spawns ───────────────────────────
+test("T5 powershell missing → exit 3, no spawns", () => {
+  const h = makeDeps({ psOk: false });
+  const { exitCode } = runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(exitCode, 3);
+  assert.strictEqual(h.spawnCalls.length, 0);
+});
+
+// ── T6 — order spec → ops → code → design → wiki ────────────────────────────
+test("T6 runs all five in registry order", () => {
+  const h = makeDeps();
+  runUnifiedInit({ runtime: "claude" }, h.deps);
+  const order = h.spawnCalls.map((c) => c.toolkit);
+  assert.deepStrictEqual(order, [
+    "sdtk-spec",
+    "sdtk-ops",
+    "sdtk-code",
+    "sdtk-design",
+    "sdtk-wiki",
+  ]);
+});
+
+// ── T7 — fail-fast default ──────────────────────────────────────────────────
+test("T7 fail-fast: middle failure stops subsequent toolkits, exit = child code", () => {
+  const h = makeDeps({ failures: { "sdtk-code": 7 } });
+  const { exitCode } = runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(exitCode, 7);
+  const order = h.spawnCalls.map((c) => c.toolkit);
+  assert.deepStrictEqual(order, ["sdtk-spec", "sdtk-ops", "sdtk-code"]);
+  assert.ok(!order.includes("sdtk-design"), "design must not be spawned after fail");
+  assert.ok(!order.includes("sdtk-wiki"), "wiki must not be spawned after fail");
+});
+
+// ── T8 — --keep-going ───────────────────────────────────────────────────────
+test("T8 keep-going: failure does not stop the rest; aggregate exit non-zero", () => {
+  const h = makeDeps({ failures: { "sdtk-code": 5 } });
+  const { exitCode, results } = runUnifiedInit({ runtime: "claude", keepGoing: true }, h.deps);
+  assert.strictEqual(exitCode, 5);
+  assert.strictEqual(h.spawnCalls.length, 5);
+  const failed = results.find((r) => r.name === "sdtk-code");
+  assert.strictEqual(failed.status, "FAILED");
+  const wiki = results.find((r) => r.name === "sdtk-wiki");
+  assert.strictEqual(wiki.status, "OK");
+});
+
+// ── T9 — unresolvable kit → exit 4 naming the kit ───────────────────────────
+test("T9 unresolvable kit → exit 4, names the kit, fail-fast no spawn", () => {
+  const h = makeDeps({ unresolvable: new Set(["sdtk-spec-kit"]) });
+  const { exitCode, results } = runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(exitCode, 4);
+  assert.strictEqual(h.spawnCalls.length, 0, "no spawns once first kit unresolvable (fail-fast)");
+  assert.ok(results[0].statusLabel.includes("sdtk-spec-kit"), "kit named in status");
+});
+test("T9b unresolvable kit with --keep-going continues, exit 4", () => {
+  const h = makeDeps({ unresolvable: new Set(["sdtk-ops-kit"]) });
+  const { exitCode } = runUnifiedInit({ runtime: "claude", keepGoing: true }, h.deps);
+  assert.strictEqual(exitCode, 4);
+  // spec + code + design + wiki spawn; ops is skipped (unresolvable)
+  const order = h.spawnCalls.map((c) => c.toolkit);
+  assert.deepStrictEqual(order, ["sdtk-spec", "sdtk-code", "sdtk-design", "sdtk-wiki"]);
+});
+
+// ── T10 — orchestrator only touches injected deps (no real fs/network/spawn) ─
+test("T10 orchestrator uses only injected deps (no real host access)", () => {
+  const h = makeDeps();
+  // Spy spawn/resolveBin do no real I/O. A successful run that records exactly
+  // the expected spy invocations proves the orchestrator never bypassed the seam.
+  runUnifiedInit({ runtime: "claude" }, h.deps);
+  assert.strictEqual(h.spawnCalls.length, 5, "all process work went through injected spawn");
+  assert.deepStrictEqual(h.resolveCalls, [
+    "sdtk-spec-kit",
+    "sdtk-ops-kit",
+    "sdtk-code-kit",
+    "sdtk-design-kit",
+    "sdtk-wiki-kit",
+  ]);
+  // buildInitArgs is pure: same input → same output, no side effects.
+  const a = buildInitArgs(TOOLKITS[0], { runtime: "claude" });
+  const b = buildInitArgs(TOOLKITS[0], { runtime: "claude" });
+  assert.deepStrictEqual(a, b);
+});
+
+// ── runner ──────────────────────────────────────────────────────────────────
+let passed = 0;
+let failed = 0;
+for (const t of tests) {
+  try {
+    t.fn();
+    passed += 1;
+    console.log(`  ok  ${t.name}`);
+  } catch (err) {
+    failed += 1;
+    console.error(`FAIL  ${t.name}`);
+    console.error(`      ${err.message}`);
+  }
+}
+console.log("");
+console.log(`unified-init tests: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/src/commands/init.js

@@ -0,0 +1,95 @@
+"use strict";
+
+// `sdtk init` command (umbrella). Parses flags, wires real effectful deps, and
+// delegates to the pure orchestrator in src/lib/unified-init.js.
+
+const { spawnSync } = require("child_process");
+const {
+  runUnifiedInit,
+  resolveToolkitBin,
+  checkPowerShellAvailable,
+} = require("../lib/unified-init");
+
+// Minimal local flag parser (the umbrella has no shared args lib, and we must not
+// import a child kit's internal lib). Supports `--flag value`, `--flag=value`,
+// and boolean `--flag`.
+const FLAG_DEFS = Object.freeze({
+  runtime: "string",
+  "runtime-scope": "string",
+  "project-path": "string",
+  force: "boolean",
+  "skip-runtime-assets": "boolean",
+  "keep-going": "boolean",
+  verbose: "boolean",
+});
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+    let key = arg.slice(2);
+    let value;
+    const eq = key.indexOf("=");
+    if (eq !== -1) {
+      value = key.slice(eq + 1);
+      key = key.slice(0, eq);
+    }
+    const type = FLAG_DEFS[key];
+    if (!type) {
+      throw new Error(`Unknown flag: --${key}`);
+    }
+    if (type === "boolean") {
+      flags[key] = true;
+    } else {
+      if (value === undefined) {
+        value = args[i + 1];
+        i += 1;
+      }
+      if (value === undefined) {
+        throw new Error(`Flag --${key} requires a value.`);
+      }
+      flags[key] = value;
+    }
+  }
+  return flags;
+}
+
+function cmdInit(args) {
+  let flags;
+  try {
+    flags = parseFlags(args);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return 2;
+  }
+
+  const opts = {
+    runtime: flags.runtime,
+    runtimeScope: flags["runtime-scope"],
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+    skipRuntimeAssets: Boolean(flags["skip-runtime-assets"]),
+    keepGoing: Boolean(flags["keep-going"]),
+    verbose: Boolean(flags.verbose),
+  };
+
+  const deps = {
+    spawn(binPath, argv) {
+      return spawnSync(process.execPath, [binPath, ...argv], { stdio: "inherit" });
+    },
+    resolveBin: resolveToolkitBin,
+    powershellCheck: () => checkPowerShellAvailable(spawnSync),
+    log: (line) => console.log(line),
+  };
+
+  const { exitCode } = runUnifiedInit(opts, deps);
+  return exitCode;
+}
+
+module.exports = {
+  cmdInit,
+  parseFlags,
+};

package/src/lib/unified-init.js

@@ -0,0 +1,274 @@
+"use strict";
+
+// Unified-init orchestrator (pure logic).
+//
+// BK-268: `sdtk init --runtime <claude|codex>` delegates to each toolkit's own,
+// already-shipped `init`. This module re-implements NO init logic, performs NO
+// filesystem writes, NO network calls, and runs NO PowerShell of its own — every
+// side effect happens inside the delegated per-kit init it spawns.
+//
+// All effectful operations (process spawn, bin resolution, PowerShell pre-flight,
+// logging) are passed in through an injected `deps` seam so the orchestrator runs
+// fully offline under test.
+
+const path = require("path");
+
+const VALID_RUNTIMES = Object.freeze(["claude", "codex"]);
+
+// Ordered target registry. `binName` is the bin key in each kit's package.json
+// (resolved through its `bin` map at runtime, so a kit renaming its bin file
+// across a minor version does not break us — see R1 in the implementation plan).
+// `acceptsRuntime: false` toolkits run their own non-runtime init and receive
+// only the flags they accept (--project-path / --force / --verbose).
+const TOOLKITS = Object.freeze([
+  { name: "sdtk-spec", kitPkg: "sdtk-spec-kit", binName: "sdtk-spec", acceptsRuntime: true },
+  { name: "sdtk-ops", kitPkg: "sdtk-ops-kit", binName: "sdtk-ops", acceptsRuntime: true },
+  { name: "sdtk-code", kitPkg: "sdtk-code-kit", binName: "sdtk-code", acceptsRuntime: true },
+  { name: "sdtk-design", kitPkg: "sdtk-design-kit", binName: "sdtk-design", acceptsRuntime: false },
+  { name: "sdtk-wiki", kitPkg: "sdtk-wiki-kit", binName: "sdtk-wiki", acceptsRuntime: false },
+]);
+
+// Mirrors sdtk-{spec,ops,code} scope.js: claude defaults to project, codex to user.
+// Used only for the honest scope label in the summary; the orchestrator forwards
+// --runtime-scope only when the user supplies it, so each kit applies this same
+// default independently.
+function defaultScope(runtime) {
+  return runtime === "claude" ? "project" : "user";
+}
+
+class ToolkitResolveError extends Error {
+  constructor(kitPkg) {
+    super(`Toolkit '${kitPkg}' could not be resolved. Is it installed as a dependency of sdtk-kit?`);
+    this.name = "ToolkitResolveError";
+    this.kitPkg = kitPkg;
+    this.exitCode = 4;
+  }
+}
+
+// Resolve a toolkit's executable bin via its package.json `bin` map (drift-safe).
+// Default `deps.resolveBin`. Throws ToolkitResolveError when the kit or its bin
+// entry cannot be found.
+function resolveToolkitBin(kitPkg, binName) {
+  let pkgJsonPath;
+  try {
+    pkgJsonPath = require.resolve(`${kitPkg}/package.json`);
+  } catch (err) {
+    throw new ToolkitResolveError(kitPkg);
+  }
+  // eslint-disable-next-line global-require
+  const pkg = require(pkgJsonPath);
+  const binField = pkg.bin;
+  let rel;
+  if (typeof binField === "string") {
+    rel = binField;
+  } else if (binField && typeof binField === "object") {
+    rel = binField[binName] || Object.values(binField)[0];
+  }
+  if (!rel) {
+    throw new ToolkitResolveError(kitPkg);
+  }
+  return path.resolve(path.dirname(pkgJsonPath), rel);
+}
+
+// Default `deps.powershellCheck`. Single pre-flight availability probe mirroring
+// sdtk-code/src/lib/powershell.js resolution (win32 → powershell.exe, else pwsh).
+// Runs a no-op command; returns { ok, exe } and never throws.
+function checkPowerShellAvailable(spawnSync) {
+  const exe = process.platform === "win32" ? "powershell.exe" : "pwsh";
+  try {
+    const res = spawnSync(
+      exe,
+      ["-NoProfile", "-NonInteractive", "-Command", "$null"],
+      { stdio: "ignore" }
+    );
+    if (res && res.error && res.error.code === "ENOENT") {
+      return { ok: false, exe };
+    }
+    return { ok: true, exe };
+  } catch (err) {
+    return { ok: false, exe };
+  }
+}
+
+// Build the forwarded `init` flag args for one toolkit (no leading "init").
+// Runtime kits get --runtime (+ runtime-scope / skip-runtime-assets); non-runtime
+// kits receive only the accepted subset.
+function buildInitArgs(toolkit, opts) {
+  const args = [];
+  if (toolkit.acceptsRuntime) {
+    args.push("--runtime", opts.runtime);
+    if (opts.runtimeScope) {
+      args.push("--runtime-scope", opts.runtimeScope);
+    }
+  }
+  if (opts.projectPath) {
+    args.push("--project-path", opts.projectPath);
+  }
+  if (opts.force) {
+    args.push("--force");
+  }
+  if (toolkit.acceptsRuntime && opts.skipRuntimeAssets) {
+    args.push("--skip-runtime-assets");
+  }
+  if (opts.verbose) {
+    args.push("--verbose");
+  }
+  return args;
+}
+
+function normalizeExitCode(res) {
+  if (res && typeof res.status === "number") {
+    return res.status;
+  }
+  if (res && typeof res.exitCode === "number") {
+    return res.exitCode;
+  }
+  // Spawn failure (e.g. error without numeric status) → non-zero.
+  return 1;
+}
+
+// Render the final per-toolkit summary table (spec §5). Pure.
+function renderSummary(results, opts, scopeLabel) {
+  const rows = results.map((r) => {
+    const runtimeCol = r.acceptsRuntime ? opts.runtime : "-";
+    const scopeCol = r.acceptsRuntime ? scopeLabel : "-";
+    return { toolkit: r.name, runtime: runtimeCol, scope: scopeCol, status: r.statusLabel || r.status };
+  });
+  const headers = { toolkit: "toolkit", runtime: "runtime", scope: "scope", status: "status" };
+  const width = (key) =>
+    Math.max(headers[key].length, ...rows.map((row) => String(row[key]).length));
+  const w = {
+    toolkit: width("toolkit"),
+    runtime: width("runtime"),
+    scope: width("scope"),
+    status: width("status"),
+  };
+  const pad = (val, key) => String(val).padEnd(w[key]);
+  const line = (row) =>
+    `  ${pad(row.toolkit, "toolkit")}  ${pad(row.runtime, "runtime")}  ${pad(row.scope, "scope")}  ${pad(
+      row.status,
+      "status"
+    )}`.replace(/\s+$/, "");
+  const out = ["Summary", line(headers)];
+  for (const row of rows) {
+    out.push(line(row));
+  }
+  return out.join("\n");
+}
+
+// Core orchestrator. `deps` = { spawn, resolveBin, powershellCheck, log }.
+//   spawn(binPath, argv, toolkit) → { status|exitCode, stderr? }
+//   resolveBin(kitPkg, binName)   → absolute bin path (throws ToolkitResolveError)
+//   powershellCheck()             → { ok, exe }
+//   log(line)                     → progress/summary sink
+// Returns { exitCode, results }. Never writes files / opens sockets itself.
+function runUnifiedInit(opts, deps) {
+  const spawn = deps.spawn;
+  const resolveBin = deps.resolveBin || resolveToolkitBin;
+  const powershellCheck = deps.powershellCheck;
+  const log = deps.log || (() => {});
+
+  // 1. Required, validated --runtime (no spawns on failure). Exit 2.
+  if (!opts.runtime || !VALID_RUNTIMES.includes(opts.runtime)) {
+    log(`Error: --runtime is required and must be one of: ${VALID_RUNTIMES.join(", ")}.`);
+    return { exitCode: 2, results: [] };
+  }
+
+  // 2. Single PowerShell pre-flight, fail-closed (no spawns on failure). Exit 3.
+  const ps = powershellCheck();
+  if (!ps || !ps.ok) {
+    const exe = (ps && ps.exe) || "pwsh";
+    log(
+      `Error: PowerShell not found (tried: ${exe}). All runtime toolkit inits require ` +
+        "PowerShell. Install PowerShell and ensure it is on PATH, then retry."
+    );
+    return { exitCode: 3, results: [] };
+  }
+
+  const scopeLabel = opts.runtimeScope || defaultScope(opts.runtime);
+  log(`SDTK unified init — runtime: ${opts.runtime}, scope: ${scopeLabel}`);
+
+  const results = [];
+  let firstFailure = 0;
+  const total = TOOLKITS.length;
+
+  for (let i = 0; i < total; i += 1) {
+    const toolkit = TOOLKITS[i];
+    const idx = `[${i + 1}/${total}]`;
+    const suffix = toolkit.acceptsRuntime ? "" : "   (not runtime-aware)";
+
+    let binPath;
+    try {
+      binPath = resolveBin(toolkit.kitPkg, toolkit.binName);
+    } catch (err) {
+      const code = typeof err.exitCode === "number" ? err.exitCode : 4;
+      results.push({
+        name: toolkit.name,
+        acceptsRuntime: toolkit.acceptsRuntime,
+        status: "FAILED",
+        statusLabel: `FAILED (kit '${toolkit.kitPkg}' not found)`,
+        exitCode: code,
+      });
+      log(`  ${idx} ${toolkit.name} … FAILED — kit '${toolkit.kitPkg}' not resolvable`);
+      if (!firstFailure) {
+        firstFailure = code;
+      }
+      if (!opts.keepGoing) {
+        break;
+      }
+      continue;
+    }
+
+    const argv = ["init", ...buildInitArgs(toolkit, opts)];
+    const res = spawn(binPath, argv, toolkit);
+    const code = normalizeExitCode(res);
+
+    if (code === 0) {
+      results.push({
+        name: toolkit.name,
+        acceptsRuntime: toolkit.acceptsRuntime,
+        status: "OK",
+        exitCode: 0,
+      });
+      log(`  ${idx} ${toolkit.name} … OK${suffix}`);
+    } else {
+      results.push({
+        name: toolkit.name,
+        acceptsRuntime: toolkit.acceptsRuntime,
+        status: "FAILED",
+        statusLabel: `FAILED (exit ${code})`,
+        exitCode: code,
+      });
+      log(`  ${idx} ${toolkit.name} … FAILED (exit ${code})`);
+      if (res && res.stderr) {
+        log(String(res.stderr).trimEnd());
+      }
+      if (!firstFailure) {
+        firstFailure = code;
+      }
+      if (!opts.keepGoing) {
+        break;
+      }
+    }
+  }
+
+  log("");
+  log(renderSummary(results, opts, scopeLabel));
+  const exitCode = firstFailure || 0;
+  if (exitCode === 0) {
+    log(`All toolkits initialised for the ${opts.runtime} runtime.`);
+  }
+  return { exitCode, results };
+}
+
+module.exports = {
+  VALID_RUNTIMES,
+  TOOLKITS,
+  ToolkitResolveError,
+  defaultScope,
+  resolveToolkitBin,
+  checkPowerShellAvailable,
+  buildInitArgs,
+  renderSummary,
+  runUnifiedInit,
+};