# sdtk-spec-kit `sdtk-spec-kit` is the canonical shipped technical interface for `SDTK-SPEC`. It exposes the `sdtk-spec` CLI as the primary upstream command surface. Package version in this source snapshot: `0.4.7` Full usage guide: `products/sdtk-spec/governance/SDTK_SPEC_USAGE_GUIDE.md` Wraps the `SDTK-SPEC` 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 `products/sdtk-spec/toolkit/SDTK_TOOLKIT.md` for workflow quality contracts. ## Migration From `sdtk-kit` / `sdtk` If you previously used the older interface, uninstall the deprecated package first, then install the canonical package: ```bash npm uninstall -g sdtk-kit npm install -g sdtk-spec-kit ``` After migrating, replace `sdtk ...` commands with `sdtk-spec ...`. ## Install ```bash npm install -g sdtk-spec-kit # or link locally for development: npm link ``` ## Update Existing Installation Use the public `update` command when `sdtk-spec-kit` is already installed and you want the current published package line plus refreshed managed project or runtime files. ```bash sdtk-spec update --check-only sdtk-spec update --runtime claude --project-path ./my-project ``` Codex user-scope example: ```bash sdtk-spec update --runtime codex --scope user --project-path ./my-project ``` Important truth: - `sdtk-spec update` still uses `npm install -g sdtk-spec-kit@` as the package refresh mechanism - `update --check-only` is non-destructive and prints the planned commands only - `--skip-project-files` suppresses `sdtk-spec init --force` - `--skip-runtime-assets` suppresses runtime refresh - there is no umbrella suite-wide update command ## Quick Start ### Free Tier ```bash # 1. Install npm install -g sdtk-spec-kit # 2. Initialize workspace with runtime adapter sdtk-spec init --runtime claude # 3. Generate feature documentation (17-file scaffold) sdtk-spec generate --feature-key USER_PROFILE --feature-name "User Profile" # 4. Optional: build the free local Atlas compatibility graph sdtk-spec atlas init --project-path . ``` ### Pro / Custom Tier ```bash # 1. Install npm install -g sdtk-spec-kit # 2. Activate your license (activation key was sent to your email) sdtk-spec activate --license SDTK-XXXX-YYYY # 3. Initialize workspace with runtime adapter sdtk-spec init --runtime claude # 4. Generate feature documentation (17-file scaffold) sdtk-spec generate --feature-key USER_PROFILE --feature-name "User Profile" # 5. Use premium features: ingest/audit an existing project sdtk-spec project ingest --project-path . sdtk-spec project audit --project-path . --json ``` 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-spec init` Initialize `SDTK-SPEC` workspace in the current or specified project directory. ```bash sdtk-spec init --runtime [--project-path ] [--force] [--runtime-scope ] [--skip-runtime-assets] # Deprecated: --skip-skills (use --skip-runtime-assets instead) ``` Creates: - `AGENTS.md` -- project-level agent guidance - `governance/ai/session/SDTK_ACTIVE_BOOTSTRAP.md` -- compact session bootstrap truth - `governance/ai/session/SDTK_AGENT_WORKING_RULES.md` -- stable working-style contract - `sdtk-spec.config.json` -- project configuration - `sdtk-spec.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 install into `$CODEX_HOME/skills/` or `~/.codex/skills/` by default, and into `/.codex/skills/` only when you intentionally launch with the explicit local `CODEX_HOME=/.codex` contract, unless `--skip-runtime-assets` is used - `--skip-skills` is deprecated; use `--skip-runtime-assets` instead ### `sdtk-spec auth` (Advanced / Internal) **Note:** For public Pro/Custom users, use `sdtk-spec activate --license` instead. This command is for advanced or internal organization setups. Manage GitHub authentication and verify entitlement. ```bash sdtk-spec auth --token # store PAT (advanced) sdtk-spec auth --verify # check repo access (advanced) sdtk-spec auth --status # show auth state sdtk-spec auth --logout # clear credentials ``` #### Entitlement repo override (Advanced) By default, `sdtk-spec 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-spec auth --verify ``` ```powershell # PowerShell $env:SDTK_ENTITLEMENT_REPO="owner/repo" sdtk-spec auth --verify ``` ### `sdtk-spec activate` (Pro / Custom) Unlock premium features with your activation key. ```bash sdtk-spec activate --license SDTK-XXXX-YYYY sdtk-spec entitlement status ``` Your activation key was sent to your email after purchase. This command: - Exchanges your key for a signed entitlement manifest - Installs required premium packs locally - Unlocks all premium commands immediately ### `sdtk-spec entitlement` Inspect local entitlement state. ```bash sdtk-spec entitlement status sdtk-spec entitlement sync # advanced / internal only ``` Important: - `entitlement status` is local-only and does not hit the network. - `entitlement sync` is an advanced command for organization-based setups or troubleshooting. - For public Pro/Custom users, use `sdtk-spec activate --license` instead. - Premium commands such as `project ingest`, `project audit`, and `project refresh` fail closed when entitlement or pack integrity is missing. ### `sdtk-spec generate` Generate feature documentation from templates. Produces 17 files matching the `SDTK-SPEC` toolkit contract. ```bash sdtk-spec generate --feature-key --feature-name "" [--project-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-spec analyze` Preserve a customer requirement source, bootstrap the standard 17-file scaffold, and create an agent task packet for PM/BA/ARCH/DEV/QA analysis. ```bash sdtk-spec analyze --source --feature-key --feature-name "" [--project-path ] [--force] [--json] ``` `analyze` is source intake and workflow bootstrap. It records source hash traceability and likely mojibake/encoding risk, but it does not fully understand arbitrary requirements by itself. PM/BA/ARCH agents complete source-backed analysis inside the generated artifacts. ### `sdtk-spec atlas` Build and browse a local document graph for your project. Atlas is a free local compatibility feature in `sdtk-spec-kit`. No authentication or entitlement is required. New SDTK-WIKI work uses `sdtk-wiki` and canonical `.sdtk/wiki` storage; `sdtk-spec atlas` remains the R1 compatibility path and continues to write `.sdtk/atlas`. #### Subcommands ```bash sdtk-spec atlas init # Initialize Atlas config and run first build (opens viewer) sdtk-spec atlas build # Rebuild the local document graph from project markdown sdtk-spec atlas open # Open the last successful atlas build in a local browser sdtk-spec atlas watch # Watch for markdown changes and rebuild automatically sdtk-spec atlas status # Show initialization state and last build summary ``` #### First-run flow ```bash cd sdtk-spec atlas init ``` This creates `.sdtk/atlas/config.json`, scans local markdown, builds the document graph and static viewer, and opens the viewer in your browser by default. #### Common flows ```bash # Initialize with a custom project path, skip opening viewer sdtk-spec atlas init --project-path ./my-project --no-open # Rebuild after doc changes sdtk-spec atlas build --project-path ./my-project # Open the viewer manually sdtk-spec atlas open --project-path ./my-project # Watch for changes and rebuild continuously sdtk-spec atlas watch --project-path ./my-project # Check Atlas initialization state and last build summary sdtk-spec atlas status --project-path ./my-project ``` #### Options (init) ```bash sdtk-spec atlas init [--project-path ] [--output-dir ] [--scan-root ] [--force] [--no-build] [--no-open] [--verbose] ``` #### Key facts - Generated artifacts are written to `/.sdtk/atlas/` (project-local, not global). - `.sdtk/atlas` is the SPEC compatibility output path. Native SDTK-WIKI uses `.sdtk/wiki`. - The viewer server binds to `127.0.0.1` by default (loopback only). - Python 3.8+ must be available in `PATH` for `atlas init`, `build`, and `watch`. - Free Atlas scans local markdown files only and does not upload document content to external services. - `sdtk-spec auth` and `sdtk-spec entitlement` are separate capability-management surfaces; they are not required for free Atlas commands. - The old SPEC ask command path is not supported. Native Ask is owned by `sdtk-wiki ask` and capability `wiki.ask`. ### `sdtk-spec project` Run premium project intelligence workflows against an existing consumer repository. ```bash sdtk-spec project ingest # Build deterministic project foundation + staged docs baseline (Pro) sdtk-spec project audit # Read-only readiness / risk / gap audit (Pro) sdtk-spec project refresh # Incrementally refresh managed .sdtk/project/ artifacts (Pro) ``` Examples: ```bash # First premium ingest against a consumer repo sdtk-spec project ingest --project-path ./my-project # Read-only audit using cached foundation when available sdtk-spec project audit --project-path ./my-project --json # Incrementally refresh foundation, evidence packs, and staged docs baseline sdtk-spec project refresh --project-path ./my-project ``` Key facts: - `project ingest`, `project audit`, and `project refresh` are Pro features. - All three commands require a valid Pro entitlement (unlock with `sdtk-spec activate --license`) and a cached premium pack. - All artifacts stay project-local under `/.sdtk/project/`. - `project ingest` writes reusable foundation artifacts such as census, source inventory, profile, module graph, runtime markers, evidence packs, and a staged docs baseline. - `project audit` is read-only. It does not mutate live `/docs/`, write new staged docs, or refresh ingest artifacts in place. - `project refresh` is incremental and requires an existing managed ingest baseline. - None of the project commands modify live `/docs/`; draft outputs remain under `.sdtk/project/`. - Maintainer-root guardrails block using the SDTK maintainer monorepo root as a premium project target. ### `sdtk-spec runtime` Manage runtime skill assets independently of `sdtk-spec init`. ```bash sdtk-spec runtime install --runtime [--scope ] sdtk-spec runtime uninstall --runtime [--scope ] sdtk-spec runtime status --runtime ``` Scope defaults: - `claude`: `project` (installs to `.claude/skills/`); `user` installs to `~/.claude/skills/` - `codex`: defaults to `user` scope (installs to `$CODEX_HOME/skills/` or `~/.codex/skills/`) and supports `project` scope only through the explicit local `CODEX_HOME=/.codex` contract Important uninstall truth: - `sdtk-spec runtime uninstall` removes only SDTK-SPEC-managed skill folders for the selected runtime and scope - it does **not** delete parent runtime roots such as `.claude/`, `.claude/skills/`, `$CODEX_HOME/`, or `$CODEX_HOME/skills/` - `npm uninstall -g sdtk-spec-kit` removes the CLI package only and does not remove runtime assets that were already installed Examples: ```bash # Install Claude skills at project scope (default) sdtk-spec runtime install --runtime claude # Install Claude skills at user scope sdtk-spec runtime install --runtime claude --scope user # Check installed runtime assets sdtk-spec runtime status --runtime claude # Remove runtime assets sdtk-spec runtime uninstall --runtime claude --scope project # Remove the npm package after runtime cleanup npm uninstall -g sdtk-spec-kit ``` ### `sdtk-spec --help` / `sdtk-spec --version` ```bash sdtk-spec --help sdtk-spec --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) - Python 3.8+ in `PATH` (required for `sdtk-spec atlas init`, `build`, and `watch`) ## Troubleshooting **PowerShell not found** - Ensure `powershell.exe` (Windows) or `pwsh` (macOS/Linux) is in your PATH. **Activation key not received** - Check your email (including spam/junk folders) for your activation key from the fulfillment system. - If the email is missing, contact support with your purchase order details. **Activation failed** - Verify your key is in the format `SDTK-XXXX-YYYY`. - Check your network connection. - If the issue persists, contact support with the error message. **Premium commands still locked after activation** - Run `sdtk-spec entitlement status` to verify activation succeeded. - If status shows no entitlement, try running `sdtk-spec activate --license ` again. - Reinstall the package if issues persist: `npm install -g sdtk-spec-kit@latest`. **Payload hash mismatch** - The bundled toolkit payload may be corrupted. Reinstall the package. **Atlas build fails or Python not found** - Install Python 3.8+ from python.org and ensure `python --version` works from the same shell. - Confirm Python is available in `PATH`, then rerun `sdtk-spec atlas build` or `sdtk-spec atlas init`. ## 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.