sdtk-kit 1.3.0 → 1.3.1

package/README.md

@@ -34,22 +34,34 @@ sdtk-spec generate --feature-key MY_FEATURE
 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)
+sdtk-spec → sdtk-ops → sdtk-code → sdtk-design   (with --runtime <r>)
+sdtk-wiki                                         (its own non-runtime init)
 ```
 
 ```bash
 sdtk init --runtime claude
 sdtk init --runtime codex --project-path ./my-app
+sdtk init --runtime claude --global        # install skills to the user/global home
 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`.
+Options: `--runtime <claude|codex>` (required), `--runtime-scope <project|user>`,
+`--global` (shorthand for `--runtime-scope user`), `--project-path <path>`,
+`--force`, `--skip-runtime-assets`, `--keep-going` (default is fail-fast — stop
+at the first failing toolkit), `--verbose`.
+
+`--runtime`, `--runtime-scope`, and `--global` apply to the runtime-aware
+toolkits (spec/ops/code **and** sdtk-design), so each places its skills under the
+matching runtime home: `.claude/skills` for claude, `.codex/skills` for codex
+(and `~/.claude/skills` / `~/.codex/skills` for `--global`). `--skip-runtime-assets`
+applies only to spec/ops/code (which own the PowerShell runtime-asset payload).
+`sdtk-wiki` installs no skills and receives only `--project-path`, `--force`,
+and `--verbose`.
+
+> Note: claude defaults to **project** scope (`.claude/skills`); codex defaults
+> to **user/global** scope (`~/.codex/skills`), since Codex discovers skills via
+> `CODEX_HOME`. Pass `--runtime-scope project` with codex to get a project-local
+> `.codex/skills` (then launch Codex with `CODEX_HOME=<project>/.codex`).
 
 `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
@@ -106,14 +118,14 @@ are the mechanism that puts `sdtk`, `sdtk-spec`, `sdtk-code`, `sdtk-ops`,
 - **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 dependency ranges (as of sdtk-kit v1.3.0):
+Current dependency ranges (as of sdtk-kit v1.3.1):
 
 | Package          | Version |
 |------------------|---------|
 | 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-design-kit  | ^0.3.2  |
 | sdtk-wiki-kit    | ^0.2.0  |
 
 ## Updating

package/bin/sdtk.js

@@ -28,16 +28,25 @@ function helpText() {
     "  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.",
+    "  --runtime <claude|codex>   Required. Runtime for the runtime-aware kits",
+    "                             (spec/ops/code and design place skills under",
+    "                             .claude/skills or .codex/skills accordingly).",
+    "  --runtime-scope <project|user>  Optional. project = repo-local skills dir;",
+    "                             user = global home. Default: claude→project,",
+    "                             codex→user (Codex discovers skills via CODEX_HOME).",
+    "  --global                   Shorthand for --runtime-scope user (~/.claude or",
+    "                             ~/.codex). Applies to both runtimes.",
     "  --project-path <path>      Optional. Target project directory.",
     "  --force                    Re-initialise existing assets.",
-    "  --skip-runtime-assets      Skip runtime asset install (runtime toolkits).",
+    "  --skip-runtime-assets      Skip PowerShell runtime asset install (spec/ops/code).",
     "  --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).",
+    "Runs: sdtk-spec → sdtk-ops → sdtk-code → sdtk-design (all with --runtime)",
+    "      → sdtk-wiki (its own non-runtime init; installs no skills).",
+    "",
+    "Note: for a project-local .codex with codex, pass --runtime-scope project and",
+    "launch Codex with CODEX_HOME=<project>/.codex (no native .codex auto-discovery).",
     "",
     "Standalone per-toolkit CLIs remain available: sdtk-spec, sdtk-ops, sdtk-code,",
     "sdtk-design, sdtk-wiki.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-kit",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "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": {
@@ -29,7 +29,7 @@
     "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-design-kit": "^0.3.2",
     "sdtk-wiki-kit": "^0.2.0"
   },
   "engines": {

package/scripts/unified-init.test.js

@@ -12,9 +12,14 @@ const {
   TOOLKITS,
   ToolkitResolveError,
 } = require("../src/lib/unified-init");
+const { parseFlags, buildOpts } = require("../src/commands/init");
 
-const RUNTIME_KITS = ["sdtk-spec", "sdtk-ops", "sdtk-code"];
-const NON_RUNTIME_KITS = ["sdtk-design", "sdtk-wiki"];
+// spec/ops/code own the PowerShell runtime-asset payload (install.ps1) and so
+// also accept --skip-runtime-assets. sdtk-design is runtime-aware (places the
+// design-prototype skill under .claude/.codex) but does NOT take that flag.
+const ASSET_KITS = ["sdtk-spec", "sdtk-ops", "sdtk-code"];
+const RUNTIME_KITS = ["sdtk-spec", "sdtk-ops", "sdtk-code", "sdtk-design"];
+const NON_RUNTIME_KITS = ["sdtk-wiki"];
 
 // Build an injected deps object with a recording spawn spy.
 // `failures` maps toolkit name → exit code to return (default 0).
@@ -95,7 +100,7 @@ test("T3 forwards shared flags to runtime kits; only subset to design/wiki", ()
   };
   runUnifiedInit(opts, h.deps);
 
-  for (const kit of RUNTIME_KITS) {
+  for (const kit of ASSET_KITS) {
     const argv = argvFor(h.spawnCalls, kit);
     assert.deepStrictEqual(
       argv,
@@ -114,6 +119,27 @@ test("T3 forwards shared flags to runtime kits; only subset to design/wiki", ()
       `${kit} full forward`
     );
   }
+  // design is runtime-aware (gets --runtime/--runtime-scope) but owns no
+  // PowerShell payload, so it must NOT receive --skip-runtime-assets.
+  {
+    const argv = argvFor(h.spawnCalls, "sdtk-design");
+    assert.deepStrictEqual(
+      argv,
+      [
+        "init",
+        "--runtime",
+        "claude",
+        "--runtime-scope",
+        "user",
+        "--project-path",
+        "/tmp/proj",
+        "--force",
+        "--verbose",
+      ],
+      "sdtk-design runtime-aware forward (no --skip-runtime-assets)"
+    );
+    assert.ok(!argv.includes("--skip-runtime-assets"), "design must not get --skip-runtime-assets");
+  }
   for (const kit of NON_RUNTIME_KITS) {
     const argv = argvFor(h.spawnCalls, kit);
     assert.deepStrictEqual(
@@ -223,6 +249,30 @@ test("T10 orchestrator uses only injected deps (no real host access)", () => {
   assert.deepStrictEqual(a, b);
 });
 
+// ── T11 — --global shorthand maps to runtime-scope user ─────────────────────
+test("T11 --global parses and maps to runtimeScope=user", () => {
+  const flags = parseFlags(["--runtime", "claude", "--global"]);
+  assert.strictEqual(flags.global, true);
+  const opts = buildOpts(flags);
+  assert.strictEqual(opts.runtimeScope, "user");
+});
+test("T11b explicit --runtime-scope wins over --global", () => {
+  const opts = buildOpts(parseFlags(["--runtime", "codex", "--global", "--runtime-scope", "project"]));
+  assert.strictEqual(opts.runtimeScope, "project");
+});
+test("T11c no scope flag leaves runtimeScope undefined (kits apply their default)", () => {
+  const opts = buildOpts(parseFlags(["--runtime", "codex"]));
+  assert.strictEqual(opts.runtimeScope, undefined);
+});
+test("T11d --global forwards --runtime-scope user to design (runtime-aware)", () => {
+  const h = makeDeps();
+  runUnifiedInit(buildOpts(parseFlags(["--runtime", "claude", "--global"])), h.deps);
+  assert.deepStrictEqual(
+    argvFor(h.spawnCalls, "sdtk-design"),
+    ["init", "--runtime", "claude", "--runtime-scope", "user"]
+  );
+});
+
 // ── runner ──────────────────────────────────────────────────────────────────
 let passed = 0;
 let failed = 0;

package/src/commands/init.js

@@ -16,6 +16,7 @@ const {
 const FLAG_DEFS = Object.freeze({
   runtime: "string",
   "runtime-scope": "string",
+  global: "boolean",
   "project-path": "string",
   force: "boolean",
   "skip-runtime-assets": "boolean",
@@ -57,6 +58,23 @@ function parseFlags(args) {
   return flags;
 }
 
+// Pure flags → orchestrator opts mapping (exported for unit testing).
+// --global is a shorthand for --runtime-scope user (installs skills under the
+// user/global runtime home: ~/.claude/skills or ~/.codex/skills). An explicit
+// --runtime-scope wins if both are supplied.
+function buildOpts(flags) {
+  const runtimeScope = flags["runtime-scope"] || (flags.global ? "user" : undefined);
+  return {
+    runtime: flags.runtime,
+    runtimeScope,
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+    skipRuntimeAssets: Boolean(flags["skip-runtime-assets"]),
+    keepGoing: Boolean(flags["keep-going"]),
+    verbose: Boolean(flags.verbose),
+  };
+}
+
 function cmdInit(args) {
   let flags;
   try {
@@ -66,15 +84,7 @@ function cmdInit(args) {
     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 opts = buildOpts(flags);
 
   const deps = {
     spawn(binPath, argv) {
@@ -92,4 +102,5 @@ function cmdInit(args) {
 module.exports = {
   cmdInit,
   parseFlags,
+  buildOpts,
 };

package/src/lib/unified-init.js

@@ -18,14 +18,20 @@ 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).
+//
+// `acceptsRuntime` toolkits receive --runtime (+ --runtime-scope) so they place
+// their skills under the correct runtime home (.claude vs .codex). Of those,
+// only `installsRuntimeAssets` toolkits (spec/ops/code, which run install.ps1)
+// also accept --skip-runtime-assets. sdtk-design is runtime-aware (it installs
+// the design-prototype skill into the matching skills dir) but does not own the
+// PowerShell runtime-asset payload. sdtk-wiki is not runtime-aware (it installs
+// no skills) and receives only --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 },
+  { name: "sdtk-spec", kitPkg: "sdtk-spec-kit", binName: "sdtk-spec", acceptsRuntime: true, installsRuntimeAssets: true },
+  { name: "sdtk-ops", kitPkg: "sdtk-ops-kit", binName: "sdtk-ops", acceptsRuntime: true, installsRuntimeAssets: true },
+  { name: "sdtk-code", kitPkg: "sdtk-code-kit", binName: "sdtk-code", acceptsRuntime: true, installsRuntimeAssets: true },
+  { name: "sdtk-design", kitPkg: "sdtk-design-kit", binName: "sdtk-design", acceptsRuntime: true, installsRuntimeAssets: false },
+  { name: "sdtk-wiki", kitPkg: "sdtk-wiki-kit", binName: "sdtk-wiki", acceptsRuntime: false, installsRuntimeAssets: false },
 ]);
 
 // Mirrors sdtk-{spec,ops,code} scope.js: claude defaults to project, codex to user.
@@ -107,7 +113,7 @@ function buildInitArgs(toolkit, opts) {
   if (opts.force) {
     args.push("--force");
   }
-  if (toolkit.acceptsRuntime && opts.skipRuntimeAssets) {
+  if (toolkit.installsRuntimeAssets && opts.skipRuntimeAssets) {
     args.push("--skip-runtime-assets");
   }
   if (opts.verbose) {