sdtk-kit 0.3.2 → 0.3.4

package/assets/toolkit/toolkit/skills-claude/qa/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: qa
+description: QA workflow for SDTK. Use when you need to validate an implemented feature against BA/PRD/Backlog, run quality gates, document defects, and produce a QA_RELEASE_REPORT with a release decision.
+---
+
+## SDTK Pipeline Rules (always apply)
+1. Pipeline: PM Initiation → BA Analysis → PM Planning → Architecture Design → Development + Review → QA Validation
+2. After completing phase work: update SHARED_PLANNING.md + QUALITY_CHECKLIST.md
+3. If unclear: log OQ-xx in artifact, escalate to PM (PM asks user if needed)
+4. Traceability: REQ → BR/UC/AC → design → backlog → code/tests → QA
+5. Code review must be COMPLETE before QA phase can start
+6. Do not skip phases. If inputs missing, ask focused questions.
+
+## Prerequisites (verify before proceeding)
+Read QUALITY_CHECKLIST.md and verify:
+- Phase 4 DEV gate must show all items [x] Done (including code review completion).
+
+If prerequisites NOT met: report which gate is missing, suggest user run `/dev` first to complete code review.
+
+## Current Context
+- Config: !`node -e "try{process.stdout.write(require('fs').readFileSync('sdtk.config.json','utf8'))}catch{process.stdout.write('{}')}"`
+- Pipeline: !`node -e "try{process.stdout.write(require('fs').readFileSync('SHARED_PLANNING.md','utf8'))}catch{process.stdout.write('Not initialized')}"`
+- Gates: !`node -e "try{process.stdout.write(require('fs').readFileSync('QUALITY_CHECKLIST.md','utf8'))}catch{process.stdout.write('Not initialized')}"`
+- State: !`node -e "try{process.stdout.write(require('fs').readFileSync('.sdtk/orchestration-state.json','utf8'))}catch{process.stdout.write('{}')}"`
+
+## Input
+$ARGUMENTS
+
+If no arguments provided, read current feature context from SHARED_PLANNING.md.
+
+# SDTK QA (Testing + Release Decision)
+
+## Output
+- `docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md`
+- Optional (when detailed test design spec is requested):
+  - `docs/qa/[FEATURE_KEY]_TEST_CASE.md` via `/test-case-spec`
+
+## Process
+1. Validate prerequisites: DEV phase completed + code review PASS.
+2. Create test strategy mapped to UC/AC.
+3. If test-case specification artifact is required, invoke `/test-case-spec` and align counts/coverage with release testing scope.
+4. If acceptance criteria / expected behavior is unclear: record OQ-xx in QA report and escalate to PM (suggest user run `/pm` if still missing info).
+5. Execute/record results (unit/integration/e2e as applicable).
+6. Record defects with severity and status.
+7. Decide: APPROVED vs REJECTED (with reasons).
+8. Update shared state + Phase 5 checklist.
+9. Handoff: suggest user run `/pm` to finalize release status if approved.

package/assets/toolkit/toolkit/skills-claude/screen-design-spec/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: screen-design-spec
+description: Create/update screen flow-action specifications from requirement sources (Excel/Figma/spec docs), including screen flow PlantUML, UI item/action tables, API mapping tables, and screen-to-API traceability.
+---
+
+## Required Inputs (read before proceeding)
+Read the following artifacts for the current feature:
+1. `docs/specs/BA_SPEC_*.md` — business rules, use cases
+2. `docs/architecture/ARCH_DESIGN_*.md` — system components
+3. `docs/api/[FEATURE_KEY]_ENDPOINTS.md` — API endpoints (when available)
+
+## Input
+$ARGUMENTS
+
+# SDTK Screen Flow Action Spec
+
+## Outputs
+- `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
+- Optional supporting docs:
+  - `docs/specs/[FEATURE_KEY]_FIGMA_LAYOUT.md`
+  - `docs/specs/[FEATURE_KEY]_DESIGN_SPEC_FROM_EXCEL.md`
+  - `docs/specs/assets/[feature_snake]/screens/*`
+
+## Required Inputs
+- Feature key/name
+- Primary requirement sources (BA spec, architecture, customer design docs)
+- Screen source references (Figma URLs and/or requirement screenshots)
+- API endpoint source (`docs/api/[FEATURE_KEY]_ENDPOINTS.md`) when available
+
+## Process
+1. Read requirement sources and identify in-scope screens, dialogs, and transitions.
+2. Read and apply rules from `.claude/skills/references/FLOW_ACTION_SPEC_CREATION_RULES.md`.
+3. Build/update section `Feature overview` and `Screen flow action` (PlantUML).
+4. For each screen/dialog:
+   - Add metadata (screen ID, source link)
+   - Add screen image reference
+   - Add UI item/action table with `No` column
+   - Add API mapping table (trigger -> API -> data usage)
+5. Build/update `System processing flow` from use-case and process sources.
+6. Build/update `Open questions` for unresolved behavior/API/data points.
+7. Build/update `Screen - API Mapping` summary section.
+8. Validate:
+   - global numbering consistency (no screen-level reset)
+   - no broken image paths
+   - PlantUML renderability
+   - consistency with API endpoints spec
+   - EN artifact hygiene (no VI leftovers, no mojibake, no merged heading lines)
+   - for legacy specs with per-screen reset numbering: run renumber migration first
+9. Update document history and handoff to ARCH/DEV.
+
+## Rule References
+- Core rules: `.claude/skills/references/FLOW_ACTION_SPEC_CREATION_RULES.md`
+- Numbering reference: `.claude/skills/references/numbering-rules.md`
+- Figma reference: `.claude/skills/references/figma-mcp.md`
+- Excel image export reference: `.claude/skills/references/excel-image-export.md`
+
+## Validation Script
+- `scripts/validate_flow_action_spec_numbering.py`
+  - Checks duplicate/resetted numbering in action tables.
+  - Checks encoding/markdown hygiene.
+  - For EN artifacts, run with `--en-check`:
+    - `python scripts/validate_flow_action_spec_numbering.py --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md" --en-check`
+- `scripts/renumber_flow_action_spec_global.py`
+  - Auto-migrates action table `No` fields to global numbering.
+  - Dry-run:
+    - `python scripts/renumber_flow_action_spec_global.py --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md"`
+  - Apply:
+    - `python scripts/renumber_flow_action_spec_global.py --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md" --write`

package/assets/toolkit/toolkit/skills-claude/test-case-spec/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: test-case-spec
+description: Generate screen-based QA test-case markdown in Excel-aligned layout (Statistic + per-screen UTC/ITC worksheets). Use when QA needs reusable test design artifacts before or during execution.
+---
+
+## Required Inputs (read before proceeding)
+Read the following artifacts for the current feature:
+1. `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` — screen/flow references
+2. `docs/specs/BA_SPEC_[FEATURE_KEY].md` — business rules, use cases
+3. `docs/api/[FEATURE_KEY]_ENDPOINTS.md` — API reference
+4. `docs/specs/Q&A.md` or `docs/en/specs/Q&A.md` — clarification source (when available)
+
+## Input
+$ARGUMENTS
+
+# SDTK Test Case Spec
+
+## Outputs
+- `docs/qa/[FEATURE_KEY]_TEST_CASE.md`
+- Optional project variant:
+  - `docs/en/qa/[FEATURE_KEY]_TEST_CASE.md` (only when project uses `docs/en/**`)
+
+## Core Rules
+1. Apply `.claude/skills/references/TEST_CASE_CREATION_RULES.md` first.
+2. Keep section order fixed (Statistic -> Abbreviations -> Scope -> References -> Environment -> Coverage -> Screen-based UTC/ITC -> OQ -> STC/UAT note).
+3. Use screen-first layout to mirror worksheet structure:
+   - each screen can have `[SCREEN_KEY]_UTC` and `[SCREEN_KEY]_ITC`.
+4. Keep one unified 18-column schema for UTC/ITC rows.
+5. Keep stable case IDs; do not renumber only because of regrouping.
+6. Track unresolved decisions via `OQ-xx`.
+
+## Procedure
+1. Resolve output path:
+   - default `docs/qa/[FEATURE_KEY]_TEST_CASE.md`
+   - use `docs/en/qa/...` only if the repo already follows `docs/en/**`.
+2. Build/refresh `Statistic Summary (Excel-aligned)`:
+   - include UT total, IT total, grand total.
+3. Build `Feature Coverage Matrix` from flow/action and API docs.
+4. Split UTC/ITC by screen sections (`screen-first`), not by test type only.
+5. Fill conflict/permission/error-path cases from Q&A decisions and API contracts.
+6. Record unresolved items in section `Open Questions`.
+7. Validate:
+   - counts in summary match table rows
+   - no placeholder tokens like `??`
+   - out-of-scope boundaries are explicit
+
+## Role Integration
+- Primary owner: `/qa`.
+- `/qa` uses this skill to design/update reusable test-case specs.
+- `/qa` still owns release decision artifact (`QA_RELEASE_REPORT_*`).
+
+## Notes
+- This skill is for test-case specification artifacts, not test execution logs.
+- For release approval and defect triage, continue with `/qa`.
+
+## Validator Script
+- `scripts/validate_test_case_spec.py`
+
+### Typical command
+```bash
+python scripts/validate_test_case_spec.py \
+  --file "docs/qa/[FEATURE_KEY]_TEST_CASE.md"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "sdtk-kit",
-    "version":  "0.3.2",
+    "version":  "0.3.4",
     "description":  "SDTK CLI toolkit for deterministic software documentation workflows",
     "bin":  {
                 "sdtk":  "./bin/sdtk.js"
@@ -36,7 +36,7 @@
                        "url":  "https://github.com/codexsdtk/sdtk-toolkit.git",
                        "directory":  "distribution/sdtk-cli"
                    },
-    "homepage":  "https://sdtk.dev",
+    "homepage":  "https://agenttoolkits.dev",
     "bugs":  {
                  "url":  "https://github.com/codexsdtk/sdtk-toolkit/issues"
              },

package/src/commands/help.js

@@ -9,15 +9,36 @@ function cmdHelp() {
     "",
     "Commands:",
     "  init      Initialize SDTK workspace (runtime adapter + config)",
+    "  runtime   Manage runtime asset installation (install, uninstall, status)",
     "  auth      Manage GitHub authentication and entitlement",
     "  generate  Scaffold feature documentation from templates (17 files)",
     "",
     "Init options:",
-    "  --runtime <codex|claude>   Runtime adapter (default: codex)",
+    "  --runtime <codex|claude>       Runtime adapter (default: codex)",
+    "  --runtime-scope <project|user> Install scope (default: project for claude, user for codex)",
+    "  --project-path <path>          Target project directory (default: cwd)",
+    "  --force                        Overwrite existing files",
+    "  --skip-runtime-assets          Skip runtime asset installation",
+    "  --skip-skills                  (deprecated, use --skip-runtime-assets)",
+    "  --verbose                      Show detailed PowerShell script output",
+    "",
+    "Runtime subcommands:",
+    "  sdtk runtime install   --runtime <codex|claude> [--scope <project|user>]",
+    "  sdtk runtime uninstall --runtime <codex|claude> [--scope <project|user>] [--all]",
+    "  sdtk runtime status    --runtime <codex|claude>",
+    "",
+    "Runtime options:",
+    "  --runtime <codex|claude>   Target runtime (required)",
+    "  --scope <project|user>     Install scope (default: project for claude, user for codex)",
     "  --project-path <path>      Target project directory (default: cwd)",
-    "  --force                    Overwrite existing files",
-    "  --skip-skills              Skip Codex skill installation",
-    "  --verbose                  Show detailed PowerShell script output",
+    "  --force                    Overwrite existing skills",
+    "  --all                      Uninstall all managed skills",
+    "  --verbose                  Show detailed script output",
+    "",
+    "Scope behavior:",
+    "  project  Skills are installed inside the repo (Claude only: .claude/skills/)",
+    "  user     Skills are installed in the runtime home (~/.claude/skills/ or ~/.codex/skills/)",
+    "  Note: Codex supports user scope only. Project scope is not available for Codex.",
     "",
     "Auth options:",
     "  --token <value>            Store GitHub PAT",
@@ -60,6 +81,11 @@ function cmdHelp() {
     "  sdtk auth --verify",
     '  sdtk generate --feature-key USER_PROFILE --feature-name "User Profile"',
     "  sdtk generate --feature-key ORDER_MGMT --feature-name \"Order Management\" --validate-only",
+    "  sdtk init --runtime claude --runtime-scope user",
+    "  sdtk runtime install --runtime claude --scope project",
+    "  sdtk runtime install --runtime codex --scope user",
+    "  sdtk runtime status --runtime claude",
+    "  sdtk runtime uninstall --runtime claude --scope project --all",
     "",
     "  # Override entitlement repo (bash/zsh):",
     "  export SDTK_ENTITLEMENT_REPO=owner/repo",

package/src/commands/init.js

@@ -5,12 +5,15 @@ const { parseFlags, validateChoice } = require("../lib/args");
 const { verify, resolvePayloadFile } = require("../lib/toolkit-payload");
 const { runScript } = require("../lib/powershell");
 const { ValidationError } = require("../lib/errors");
+const { VALID_SCOPES, defaultScope, isProjectScopeSupported } = require("../lib/scope");
 
 const FLAG_DEFS = {
   runtime: { type: "string" },
   "project-path": { type: "string" },
+  "runtime-scope": { type: "string" },
   force: { type: "boolean" },
   "skip-skills": { type: "boolean" },
+  "skip-runtime-assets": { type: "boolean" },
   verbose: { type: "boolean" },
 };
 
@@ -23,6 +26,25 @@ async function cmdInit(args) {
   const runtime = flags.runtime || "codex";
   validateChoice(runtime, VALID_RUNTIMES, "runtime");
 
+  // Resolve scope
+  const scope = flags["runtime-scope"] || defaultScope(runtime);
+  validateChoice(scope, VALID_SCOPES, "runtime-scope");
+
+  // Gate C0: Codex does not support project-local skills
+  if (scope === "project" && !isProjectScopeSupported(runtime)) {
+    throw new ValidationError(
+      "Codex does not support project-local skills. Use --runtime-scope user instead."
+    );
+  }
+
+  // Handle deprecated --skip-skills
+  const skipAssets = flags["skip-runtime-assets"] || flags["skip-skills"];
+  if (flags["skip-skills"] && !flags["skip-runtime-assets"]) {
+    console.warn(
+      "Warning: --skip-skills is deprecated. Use --skip-runtime-assets instead."
+    );
+  }
+
   // Resolve project path
   const projectPath = flags["project-path"]
     ? path.resolve(flags["project-path"])
@@ -38,13 +60,15 @@ async function cmdInit(args) {
   const params = {
     ProjectPath: projectPath,
     Runtime: runtime,
+    Scope: scope,
   };
   if (flags.force) params.Force = true;
-  if (flags["skip-skills"]) params.SkipSkills = true;
+  if (skipAssets) params.SkipRuntimeAssets = true;
   if (!flags.verbose) params.Quiet = true;
 
   console.log(`Initializing SDTK workspace...`);
   console.log(`  Runtime: ${runtime}`);
+  console.log(`  Scope:   ${scope}`);
   console.log(`  Project: ${projectPath}`);
   console.log("");
 

package/src/commands/runtime.js

@@ -0,0 +1,217 @@
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const { parseFlags, requireFlag, validateChoice } = require("../lib/args");
+const { verify, resolvePayloadFile } = require("../lib/toolkit-payload");
+const { runScript } = require("../lib/powershell");
+const { ValidationError } = require("../lib/errors");
+const {
+  VALID_SCOPES,
+  defaultScope,
+  isProjectScopeSupported,
+  resolveSkillsDir,
+  managedSkillNames,
+} = require("../lib/scope");
+
+const FLAG_DEFS = {
+  runtime: { type: "string" },
+  scope: { type: "string" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+  all: { type: "boolean" },
+  verbose: { type: "boolean" },
+};
+
+const VALID_RUNTIMES = ["codex", "claude"];
+const SUBCOMMANDS = ["install", "uninstall", "status"];
+
+function validateScopeForRuntime(runtime, scope) {
+  if (scope === "project" && !isProjectScopeSupported(runtime)) {
+    throw new ValidationError(
+      `Codex does not support project-local skills. Use --scope user instead.`
+    );
+  }
+}
+
+async function cmdRuntimeInstall(flags) {
+  const runtime = requireFlag(flags, "runtime", "runtime");
+  validateChoice(runtime, VALID_RUNTIMES, "runtime");
+
+  const scope = flags.scope || defaultScope(runtime);
+  validateChoice(scope, VALID_SCOPES, "scope");
+  validateScopeForRuntime(runtime, scope);
+
+  const projectPath = flags["project-path"]
+    ? path.resolve(flags["project-path"])
+    : process.cwd();
+
+  verify();
+
+  const scriptName =
+    runtime === "claude"
+      ? "toolkit/scripts/install-claude-skills.ps1"
+      : "toolkit/scripts/install-codex-skills.ps1";
+  const script = resolvePayloadFile(scriptName);
+
+  const params = { Scope: scope };
+  if (runtime === "claude") {
+    params.ProjectPath = projectPath;
+  }
+  if (flags.force) params.Force = true;
+
+  console.log(`Installing ${runtime} runtime assets...`);
+  console.log(`  Runtime: ${runtime}`);
+  console.log(`  Scope:   ${scope}`);
+  if (scope === "project") {
+    console.log(`  Project: ${projectPath}`);
+  }
+  console.log("");
+
+  const result = await runScript(script, params, {
+    silent: !flags.verbose,
+  });
+
+  if (result.exitCode !== 0) {
+    if (result.stderr) console.error(result.stderr);
+    throw new ValidationError(
+      `Runtime install failed (exit code ${result.exitCode}).`
+    );
+  }
+
+  console.log("");
+  console.log(`${runtime} runtime assets installed successfully.`);
+  return 0;
+}
+
+async function cmdRuntimeUninstall(flags) {
+  const runtime = requireFlag(flags, "runtime", "runtime");
+  validateChoice(runtime, VALID_RUNTIMES, "runtime");
+
+  const scope = flags.scope || defaultScope(runtime);
+  validateChoice(scope, VALID_SCOPES, "scope");
+  validateScopeForRuntime(runtime, scope);
+
+  const projectPath = flags["project-path"]
+    ? path.resolve(flags["project-path"])
+    : process.cwd();
+
+  verify();
+
+  const scriptName =
+    runtime === "claude"
+      ? "toolkit/scripts/uninstall-claude-skills.ps1"
+      : "toolkit/scripts/uninstall-codex-skills.ps1";
+  const script = resolvePayloadFile(scriptName);
+
+  const params = {};
+  if (runtime === "claude") {
+    params.Scope = scope;
+    params.ProjectPath = projectPath;
+  }
+  if (flags.all) params.All = true;
+
+  console.log(`Uninstalling ${runtime} runtime assets...`);
+  console.log(`  Runtime: ${runtime}`);
+  console.log(`  Scope:   ${scope}`);
+  console.log("");
+
+  const result = await runScript(script, params, {
+    silent: !flags.verbose,
+  });
+
+  if (result.exitCode !== 0) {
+    if (result.stderr) console.error(result.stderr);
+    throw new ValidationError(
+      `Runtime uninstall failed (exit code ${result.exitCode}).`
+    );
+  }
+
+  console.log("");
+  console.log(`${runtime} runtime assets uninstalled successfully.`);
+  return 0;
+}
+
+function cmdRuntimeStatus(flags) {
+  const runtime = requireFlag(flags, "runtime", "runtime");
+  validateChoice(runtime, VALID_RUNTIMES, "runtime");
+
+  const projectPath = flags["project-path"]
+    ? path.resolve(flags["project-path"])
+    : process.cwd();
+
+  console.log(`Runtime: ${runtime}`);
+  console.log("");
+
+  // Check both scopes
+  const scopes = runtime === "claude" ? ["project", "user"] : ["user"];
+
+  for (const scope of scopes) {
+    const skillsDir = resolveSkillsDir(runtime, scope, projectPath);
+    const exists = fs.existsSync(skillsDir);
+    let skillCount = 0;
+
+    const managed = managedSkillNames(runtime);
+    let installedNames = [];
+
+    if (exists) {
+      try {
+        const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+        installedNames = entries
+          .filter((e) => e.isDirectory() && managed.includes(e.name))
+          .map((e) => e.name);
+        skillCount = installedNames.length;
+      } catch {
+        // Directory not readable
+      }
+    }
+
+    const allInstalled = skillCount === managed.length;
+
+    console.log(`  Scope: ${scope}`);
+    console.log(`    Path:   ${skillsDir}`);
+    const statusLabel = !exists
+      ? "not installed"
+      : allInstalled
+        ? `installed (${skillCount}/${managed.length} SDTK skills)`
+        : `partial (${skillCount}/${managed.length} SDTK skills)`;
+    console.log(`    Status: ${statusLabel}`);
+    if (exists && skillCount < managed.length) {
+      const missing = managed.filter((n) => !installedNames.includes(n));
+      console.log(`    Missing: ${missing.join(", ")}`);
+    }
+    console.log("");
+  }
+
+  return 0;
+}
+
+async function cmdRuntime(args) {
+  const { flags, positional } = parseFlags(args, FLAG_DEFS);
+
+  const subcommand = positional[0];
+  if (!subcommand) {
+    throw new ValidationError(
+      `Missing subcommand. Usage: sdtk runtime <${SUBCOMMANDS.join("|")}> [options]`
+    );
+  }
+
+  if (!SUBCOMMANDS.includes(subcommand)) {
+    throw new ValidationError(
+      `Unknown subcommand: "${subcommand}". Must be one of: ${SUBCOMMANDS.join(", ")}`
+    );
+  }
+
+  switch (subcommand) {
+    case "install":
+      return cmdRuntimeInstall(flags);
+    case "uninstall":
+      return cmdRuntimeUninstall(flags);
+    case "status":
+      return cmdRuntimeStatus(flags);
+  }
+}
+
+module.exports = {
+  cmdRuntime,
+};

package/src/index.js

@@ -4,6 +4,7 @@ const { cmdHelp } = require("./commands/help");
 const { cmdInit } = require("./commands/init");
 const { cmdAuth } = require("./commands/auth");
 const { cmdGenerate } = require("./commands/generate");
+const { cmdRuntime } = require("./commands/runtime");
 const { ValidationError, CliError } = require("./lib/errors");
 
 function getVersion() {
@@ -25,7 +26,7 @@ function parseCommand(argv) {
   return { command: first, args: rest };
 }
 
-const COMMANDS = new Set(["help", "version", "init", "auth", "generate"]);
+const COMMANDS = new Set(["help", "version", "init", "auth", "generate", "runtime"]);
 
 async function run(argv) {
   const { command, args } = parseCommand(argv);
@@ -48,6 +49,8 @@ async function run(argv) {
       return cmdAuth(args);
     case "generate":
       return cmdGenerate(args);
+    case "runtime":
+      return cmdRuntime(args);
   }
 }
 

package/src/lib/scope.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const path = require("path");
+const os = require("os");
+
+const VALID_SCOPES = ["project", "user"];
+
+/**
+ * Returns the default scope for a given runtime.
+ * Claude defaults to project-local, Codex defaults to user/global.
+ */
+function defaultScope(runtime) {
+  return runtime === "claude" ? "project" : "user";
+}
+
+/**
+ * Returns true if the given runtime supports project-local scope.
+ * Gate C0: Codex does not support project-local skills.
+ */
+function isProjectScopeSupported(runtime) {
+  return runtime === "claude";
+}
+
+/**
+ * Resolves the skills directory for a given runtime, scope, and project path.
+ */
+function resolveSkillsDir(runtime, scope, projectPath) {
+  if (runtime === "claude") {
+    if (scope === "user") {
+      return path.join(os.homedir(), ".claude", "skills");
+    }
+    return path.join(projectPath || process.cwd(), ".claude", "skills");
+  }
+
+  // Codex: always user/global scope
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  return path.join(codexHome, "skills");
+}
+
+/**
+ * SDTK-managed skill directory names per runtime.
+ * Used by runtime status to distinguish SDTK skills from unrelated user skills.
+ */
+const MANAGED_CODEX_SKILLS = [
+  "sdtk-api-design-spec", "sdtk-api-doc", "sdtk-arch", "sdtk-ba",
+  "sdtk-design-layout", "sdtk-dev", "sdtk-dev-backend", "sdtk-dev-frontend",
+  "sdtk-orchestrator", "sdtk-pm", "sdtk-qa", "sdtk-screen-design-spec",
+  "sdtk-test-case-spec",
+];
+
+const MANAGED_CLAUDE_SKILLS = [
+  "api-design-spec", "api-doc", "arch", "ba",
+  "design-layout", "dev", "dev-backend", "dev-frontend",
+  "orchestrator", "pm", "qa", "screen-design-spec",
+  "test-case-spec",
+];
+
+function managedSkillNames(runtime) {
+  return runtime === "claude" ? MANAGED_CLAUDE_SKILLS : MANAGED_CODEX_SKILLS;
+}
+
+module.exports = {
+  VALID_SCOPES,
+  defaultScope,
+  isProjectScopeSupported,
+  resolveSkillsDir,
+  managedSkillNames,
+};