sdtk-kit 0.3.9 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SDTK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,177 +1,135 @@
-# sdtk-kit
-
-SDTK CLI -- deterministic documentation toolkit for software teams.
-
-Wraps the SDTK PowerShell toolkit for portable, reproducible feature documentation scaffolding.
-
-Canonical install/runtime source in the source repo: `governance/ai/cli/SDTK_RUNTIME_AND_FEATURE_STATUS.md`
-
-Generated skills include verification gates and two-stage review hard gates. The current source baseline also ships a canonical skill catalog, handoff templates, public example packs, and a runtime readiness audit. See `toolkit/SDTK_TOOLKIT.md` for workflow quality contracts.
-
-## Install
-
-```bash
-npm install -g sdtk-kit
-# or link locally for development:
-npm link
-```
-
-## Quick Start
-
-```bash
-# 1. Initialize workspace with runtime adapter
-sdtk init --runtime claude
-
-# 2. Store GitHub token for entitlement
-sdtk auth --token ghp_xxxxxxxxxxxx
-sdtk auth --verify
-
-# 3. Generate feature documentation (17-file scaffold)
-sdtk generate --feature-key USER_PROFILE --feature-name "User Profile"
-# Codex runtime remains available:
-# sdtk init --runtime codex
-
-```
-
-The CLI generates the scaffold contract only. Full content enrichment still runs phase-by-phase through PM, BA, ARCH, DEV, and QA using the installed runtime guidance plus the toolkit docs.
-
-## Commands
-
-### `sdtk init`
-
-Initialize SDTK workspace in the current or specified project directory.
-
-```bash
-sdtk init --runtime <codex|claude> [--project-path <path>] [--force] [--runtime-scope <project|user>] [--skip-runtime-assets]
-
-# Deprecated: --skip-skills (use --skip-runtime-assets instead)
-```
-
-Creates:
-- `AGENTS.md` -- project-level agent guidance
-- `sdtk.config.json` -- project configuration
-- `sdtk.config.profiles.example.json` -- stack profile examples
-- `CODEX.md` or `CLAUDE.md` -- runtime adapter
-- for `--runtime claude`, skill files are installed into `.claude/skills/` (project scope, default) or `~/.claude/skills/` (user scope) unless `--skip-runtime-assets` is used
-- for `--runtime codex`, skill files are installed into `$CODEX_HOME/skills/` or `~/.codex/skills/` (user scope only) unless `--skip-runtime-assets` is used
-- `--skip-skills` is deprecated; use `--skip-runtime-assets` instead
-
-### `sdtk auth`
-
-Manage GitHub authentication and verify entitlement.
-
-```bash
-sdtk auth --token <value>   # store PAT
-sdtk auth --verify           # check repo access
-sdtk auth --status           # show auth state
-sdtk auth --logout           # clear credentials
-```
-
-#### Entitlement repo override
-
-By default, `sdtk auth --verify` checks access against the built-in private repo. You can override this with the `SDTK_ENTITLEMENT_REPO` environment variable:
-
-```bash
-# bash / zsh
-export SDTK_ENTITLEMENT_REPO=owner/repo
-sdtk auth --verify
-```
-
-```powershell
-# PowerShell
-$env:SDTK_ENTITLEMENT_REPO="owner/repo"
-sdtk auth --verify
-```
-
-### `sdtk generate`
-
-Generate feature documentation from templates. Produces 17 files matching the SDTK toolkit contract.
-
-```bash
-sdtk generate --feature-key <UPPER_SNAKE_CASE> --feature-name "<text>" [--project-path <path>] [--force] [--validate-only]
-```
-
-Output files include: project initiation, BA spec, flow-action spec, PRD, backlog, architecture design, database spec, API specs (OpenAPI + endpoints + design detail + flow list), UI design layout, implementation plan, test cases, and QA release report.
-
-### `sdtk runtime`
-
-Manage runtime skill assets independently of `sdtk init`.
-
-```bash
-sdtk runtime install --runtime <codex|claude> [--scope <project|user>]
-sdtk runtime uninstall --runtime <codex|claude> [--scope <project|user>]
-sdtk runtime status --runtime <codex|claude>
-```
-
-Scope defaults:
-- `claude`: `project` (installs to `.claude/skills/`); `user` installs to `~/.claude/skills/`
-- `codex`: `user` only (installs to `$CODEX_HOME/skills/` or `~/.codex/skills/`); project scope is not supported (Gate C0)
-
-Examples:
-
-```bash
-# Install Claude skills at project scope (default)
-sdtk runtime install --runtime claude
-
-# Install Claude skills at user scope
-sdtk runtime install --runtime claude --scope user
-
-# Check installed runtime assets
-sdtk runtime status --runtime claude
-
-# Remove runtime assets
-sdtk runtime uninstall --runtime claude --scope project
-```
-
-### `sdtk --help` / `sdtk --version`
-
-```bash
-sdtk --help
-sdtk --version
-```
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Validation or user error (bad args, missing auth) |
-| 2 | Dependency error (PowerShell not found) |
-| 3 | Integrity error (payload hash mismatch) |
-| 4 | Unexpected internal error |
-
-## Requirements
-
-- Node.js >= 18.13.0
-- PowerShell (Windows PowerShell 5.1+ or PowerShell Core)
-
-## Troubleshooting
-
-**PowerShell not found**
-- Ensure `powershell.exe` (Windows) or `pwsh` (macOS/Linux) is in your PATH.
-
-**Invalid or expired token**
-- Run `sdtk auth --token <new-token>` with a valid GitHub PAT.
-
-**No repository access**
-- Verify your token has access to the private distribution repo with `sdtk auth --verify`.
-- If your organization uses a custom entitlement repo, set `SDTK_ENTITLEMENT_REPO=owner/repo` before running `--verify`.
-
-**Payload hash mismatch**
-- The bundled toolkit payload may be corrupted. Reinstall the package.
-
-## Development
-
-```bash
-# Sync toolkit payload from repo root
-npm run build:payload
-
-# Verify payload integrity
-npm run verify:payload
-
-# Smoke test npm pack
-npm run pack:smoke
-```
-
-Run `tests/skill_triggering/` to validate skill routing behavior.
-
+# sdtk-kit
+
+> Install all five SDTK toolkits in one command.
+
+```bash
+npm install -g sdtk-kit
+```
+
+After install, all five SDTK CLI tools are available globally:
+
+| CLI           | Toolkit        | Purpose                                          |
+|---------------|----------------|--------------------------------------------------|
+| `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  |
+| `sdtk-ops`    | SDTK-OPS       | Operations: deploy → smoke → sign-off            |
+| `sdtk-wiki`   | SDTK-WIKI      | Local second brain: your project memory          |
+
+## Quick start
+
+```bash
+# Initialize the spec toolkit in your project
+sdtk-spec init --runtime claude   # or --runtime codex
+
+# Generate a 17-file spec scaffold for your first feature
+sdtk-spec generate --feature-key MY_FEATURE
+```
+
+## Unified vs standalone install
+
+You have two install options:
+
+**Option 1 — Install everything at once (recommended for new projects)**
+
+```bash
+npm install -g sdtk-kit
+```
+
+npm installs all five sub-toolkits as dependencies. All CLI binaries land on PATH in one step.
+
+**Option 2 — Install individual toolkits**
+
+```bash
+npm install -g sdtk-spec-kit    # spec / planning
+npm install -g sdtk-design-kit  # design
+npm install -g sdtk-code-kit    # coding
+npm install -g sdtk-ops-kit     # operations
+npm install -g sdtk-wiki-kit    # local second brain
+```
+
+Use Option 2 if you only need one or two toolkits, or if you want granular version control per toolkit.
+
+Both options are permanently supported. `sdtk-kit` does not replace the standalone packages.
+
+## How the unified CLI works (maintainer note)
+
+`sdtk-kit` declares the five sub-toolkits as dependencies AND ships thin bin
+shims (`bin/sdtk-*.js`) that re-export each sub-package's CLI. This is required
+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.
+
+## Version pinning model
+
+`sdtk-kit` uses caret-range dependencies (`^X.Y.Z`) on each sub-toolkit. This means:
+
+- **Patch and minor updates** of sub-toolkits are picked up automatically when you run `npm update -g sdtk-kit`.
+- **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):
+
+| Package          | Version |
+|------------------|---------|
+| sdtk-spec-kit    | ^0.4.7  |
+| sdtk-code-kit    | ^0.1.3  |
+| sdtk-ops-kit     | ^0.2.4  |
+| sdtk-design-kit  | ^0.3.0  |
+| sdtk-wiki-kit    | ^0.1.4  |
+
+## Updating
+
+```bash
+npm update -g sdtk-kit
+```
+
+This updates all sub-toolkits within their caret ranges.
+
+## Uninstalling
+
+To remove sdtk-kit and its sub-toolkits:
+
+```bash
+npm uninstall -g sdtk-kit
+```
+
+Note: `npm uninstall` removes the package and its transitive dependencies. If you had any sub-toolkits installed standalone _before_ installing sdtk-kit, npm may or may not remove them depending on your npm version. Run `npm uninstall -g sdtk-spec-kit sdtk-code-kit sdtk-ops-kit sdtk-design-kit sdtk-wiki-kit` to be sure.
+
+## Troubleshooting
+
+**Command not found after install**
+
+Re-open your terminal. npm global installs require a new shell session on some systems.
+
+Check your global prefix:
+
+```bash
+npm config get prefix
+```
+
+Ensure `<prefix>/bin` is in `PATH`.
+
+**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.
+
+**Binary collision**
+
+If you have standalone sub-toolkits installed at different versions than what `sdtk-kit` pins, `npm install -g sdtk-kit` will upgrade them to the pinned versions. To keep a standalone version pinned, install it standalone after sdtk-kit:
+
+```bash
+npm install -g sdtk-kit
+npm install -g sdtk-spec-kit@0.4.6  # pin to an older version
+```
+
+## Links
+
+- Docs: [https://sdtk.dev](https://sdtk.dev)
+- Source: [https://github.com/codexsdtk/sdtk-toolkit](https://github.com/codexsdtk/sdtk-toolkit)
+- Issues: [https://github.com/codexsdtk/sdtk-toolkit/issues](https://github.com/codexsdtk/sdtk-toolkit/issues)
+- License: MIT

package/bin/sdtk-code.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-code CLI from the sdtk-code-kit dependency.
+// See bin/sdtk-spec.js for the rationale behind these shims.
+require("sdtk-code-kit/bin/sdtk-code.js");

package/bin/sdtk-design.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-design CLI from the sdtk-design-kit dependency.
+// See bin/sdtk-spec.js for the rationale behind these shims.
+require("sdtk-design-kit/bin/sdtk-design.js");

package/bin/sdtk-ops.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-ops CLI from the sdtk-ops-kit dependency.
+// See bin/sdtk-spec.js for the rationale behind these shims.
+require("sdtk-ops-kit/bin/sdtk-ops.js");

package/bin/sdtk-spec.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-spec CLI from the sdtk-spec-kit dependency.
+//
+// Why this exists: `npm install -g <pkg>` only links the bin entries of the
+// top-level package, NOT of its dependencies. A pure meta-package (deps only,
+// no bin) therefore installs the sub-packages but leaves no CLI on PATH.
+//
+// Each sub-toolkit CLI reads process.argv directly, so requiring its bin
+// entry here runs it with the real arguments unchanged.
+require("sdtk-spec-kit/bin/sdtk.js");

package/bin/sdtk-wiki.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+
+// Bin shim — re-exports the sdtk-wiki CLI from the sdtk-wiki-kit dependency.
+// See bin/sdtk-spec.js for the rationale behind these shims.
+require("sdtk-wiki-kit/bin/sdtk-wiki.js");

package/package.json

@@ -1,46 +1,60 @@
-{
-    "name": "sdtk-kit",
-    "version": "0.3.9",
-    "description": "SDTK CLI toolkit for deterministic software documentation workflows",
-    "bin": {
-        "sdtk": "./bin/sdtk.js"
-    },
-    "main": "src/index.js",
-    "type": "commonjs",
-    "files": [
-        "bin/",
-        "src/",
-        "assets/"
-    ],
-    "scripts": {
-        "test": "node -e \"console.log('No tests configured yet')\"",
-        "build:payload": "powershell -ExecutionPolicy Bypass -File scripts/sync-toolkit-assets.ps1 && powershell -ExecutionPolicy Bypass -File scripts/build-toolkit-manifest.ps1",
-        "verify:payload": "node -e \"require('./src/lib/toolkit-payload').verify()\"",
-        "pack:smoke": "npm pack --dry-run",
-        "pack:release": "npm pack",
-        "prepublishOnly": "node -e \"require('./src/lib/toolkit-payload').verify()\""
-    },
-    "engines": {
-        "node": ">=18.13.0"
-    },
-    "keywords": [
-        "sdtk",
-        "cli",
-        "documentation",
-        "toolkit",
-        "dockkit"
-    ],
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/codexsdtk/sdtk-toolkit.git",
-        "directory": "distribution/sdtk-cli"
-    },
-    "homepage": "https://agenttoolkits.dev",
-    "bugs": {
-        "url": "https://github.com/codexsdtk/sdtk-toolkit/issues"
-    },
-    "publishConfig": {
-        "access": "public"
-    }
-}
+{
+  "name": "sdtk-kit",
+  "version": "1.0.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": {
+    "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.1.3",
+    "sdtk-ops-kit": "^0.2.4",
+    "sdtk-design-kit": "^0.3.0",
+    "sdtk-wiki-kit": "^0.1.4"
+  },
+  "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/postinstall.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+"use strict";
+
+// Skip banner in CI environments and headless installs.
+// This avoids noisy output in automated pipelines that install sdtk-kit
+// as a transitive dependency.
+const isCI =
+  process.env.CI === "true" ||
+  process.env.NODE_ENV === "test" ||
+  process.env.npm_config_loglevel === "silent" ||
+  process.env.npm_config_loglevel === "error";
+
+if (isCI) {
+  process.exit(0);
+}
+
+const lines = [
+  "",
+  "  ╔══════════════════════════════════════════════════════╗",
+  "  ║            SDTK — All Five Toolkits Installed        ║",
+  "  ╚══════════════════════════════════════════════════════╝",
+  "",
+  "  You now have all five SDTK CLI tools available:",
+  "",
+  "    sdtk-spec    — Spec-first SDLC: PM → BA → ARCH → DEV → QA",
+  "    sdtk-design  — MVP design: idea → prototype → handoff",
+  "    sdtk-code    — Governed coding: handoff → PR with review gates",
+  "    sdtk-ops     — Operations: deploy → smoke → sign-off",
+  "    sdtk-wiki    — Local second brain: your project memory",
+  "",
+  "  Start with the SPEC toolkit:",
+  "",
+  "    sdtk-spec init --runtime claude   (or --runtime codex)",
+  "    sdtk-spec generate --feature-key <YOUR_FEATURE>",
+  "",
+  "  Docs: https://sdtk.dev",
+  "",
+];
+
+process.stdout.write(lines.join("\n") + "\n");