Docs

Setup and operation guide for SDTK-SPEC, with suite context

This landing-page docs surface remains SDTK-SPEC-specific while pointing users to the dedicated SDTK-CODE, SDTK-OPS, and SDTK-WIKI product pages when work moves beyond upstream specification.

Full suite install

Install all four public toolkit CLIs with one npm command

This docs page remains SDTK-SPEC-specific, but the public SDTK family can still be installed together without introducing a separate umbrella npm package.

Install full suite

npm install -g sdtk-spec-kit sdtk-code-kit sdtk-ops-kit sdtk-wiki-kit

Verify all four CLIs

sdtk-spec --version sdtk-code --version sdtk-ops --version sdtk-wiki --version

Inspect package updates

sdtk-spec update --check-only sdtk-code update --check-only sdtk-ops update --check-only sdtk-wiki update --check-only

There is still no umbrella sdtk-kit update. Each package keeps its own bounded update command.

Canonical combined guide: governance/ai/cli/SDTK_SUITE_INSTALL_AND_USAGE_GUIDE.md

Package uninstall and runtime cleanup are separate operations: npm uninstall -g ... removes CLI packages only, while each toolkit's runtime uninstall command removes only the SDTK-managed skill folders for the selected runtime and scope.

Getting Started

Install the shipped SDTK-SPEC CLI, initialize the runtime, and create the 17-file upstream scaffold contract in your project folder.

This landing-page docs surface is product-specific to SDTK-SPEC inside the broader SDTK Suite.
Install Node.js 18.13+ and PowerShell (Windows PowerShell 5.1+ or pwsh).
Install the CLI globally with npm.
Initialize the workspace using sdtk-spec init with runtime codex or claude.
Claude runtime defaults to project scope and also supports user scope.
Codex defaults to user scope and also supports a bounded project-local path only through the explicit local CODEX_HOME=<project>/.codex contract.
Use --skip-runtime-assets to skip runtime asset installation for either runtime.
Generate your first feature docs with required --feature-key and --feature-name flags.
The generated 17-file contract is an upstream scaffold; phase content is enriched afterward through PM, BA, ARCH, DEV, and QA before downstream coding handoff into SDTK-CODE.

Install SDTK-SPEC CLI

npm install -g sdtk-spec-kit

Initialize for Claude runtime

sdtk-spec init --runtime claude --project-path "."

Initialize for Codex runtime

sdtk-spec init --runtime codex --project-path "."

Inspect a managed update

sdtk-spec update --check-only --runtime claude --project-path "."

Skip runtime asset installation (optional)

sdtk-spec init --runtime codex --project-path "." --skip-runtime-assets

Workflow Contracts

The current toolkit baseline includes hardening features beyond the scaffold itself.

Verification-before-completion: no phase may claim done, pass, or handoff-ready without fresh command evidence.
Two-stage DEV review: Stage 1 artifact/spec compliance before Stage 2 code quality.
Order-critical hard gates for ARCH, DEV, and QA sequencing.
Exact-spec quoting in QA validation and reusable test-case design.
A canonical 14-skill inventory in products/sdtk-spec/toolkit/skills/skills.catalog.yaml, including bounded mailbox dispatch.
Reusable PM/BA/ARCH/DEV/QA handoff templates under products/sdtk-spec/toolkit/templates/handoffs/.
Required Assumptions sections in FLOW_ACTION_SPEC and API_DESIGN_DETAIL templates.
Maintainer runtime readiness auditing via products/sdtk-spec/toolkit/scripts/check-runtime-readiness.ps1.

Atlas Workflow

Build and browse a local document graph for an existing project, then use gated Pro commands only when activation and premium packs are available.

Free Atlas scans local markdown files and writes project-local artifacts under <project>/.sdtk/atlas/.
Free Atlas does not upload document content and does not require auth, entitlement, or a Pro license.
Use atlas init for the first run; use atlas build when files change; use atlas open to reopen the last successful viewer.
wiki.ask is the canonical future Pro Ask capability for SDTK-WIKI; the old SPEC Atlas Ask path was retired before public adoption.
project ingest, project audit, and project refresh are Pro project-intelligence commands and operate on staged project-local artifacts instead of mutating live /docs/.

Initialize and open the local Atlas viewer

sdtk-spec atlas init --project-path .

Rebuild after markdown changes

sdtk-spec atlas build --project-path .

Open the last successful graph

sdtk-spec atlas open --project-path .

Build project intelligence from an existing repo (Pro)

sdtk-spec project ingest --project-path .

CLI Commands

Public command contract for sdtk-spec-kit v0.4.7.

sdtk-spec init supports: --runtime, --runtime-scope, --project-path, --force, --skip-runtime-assets, --verbose.
sdtk-spec update supports: --version, --runtime, --scope, --project-path, --check-only, --skip-project-files, --skip-runtime-assets, and --verbose.
sdtk-spec runtime supports: install, uninstall, and status.
sdtk-spec activate supports: --license and --json for the public Pro activation flow and is the primary paid-user onboarding path.
sdtk-spec auth is retained only for advanced troubleshooting or legacy verification flows and is not required for normal Free or Pro setup.
sdtk-spec generate supports: --feature-key, --feature-name, --project-path, --force, --validate-only, --verbose.
--verbose is supported for init and generate only.
Use sdtk-spec --help to view the latest command contract.

Show command reference

sdtk-spec --help

Activate Pro with a license key

sdtk-spec activate --license SDTK-XXXX-YYYY

Check installed runtime assets

sdtk-spec runtime status --runtime claude

Generate docs (write files)

sdtk-spec generate --feature-key ORDER_TRACKING --feature-name "Order Tracking" --project-path "."

Validate only (no file writes)

sdtk-spec generate --feature-key ORDER_MGMT --feature-name "Order Management" --project-path "." --validate-only

Examples

Current example packs mirror the shipped scaffold contract and the governed phase-by-phase workflow.

examples/enterprise-crud-ui-api-db covers the standard UI + API + DB delivery path.
examples/api-only-service covers API-first delivery without UI artifacts.
examples/admin-console-flow-action focuses on flow-action and screen/layout outputs.
examples/bugfix-hotfix-flow documents what can be shortened and what must remain mandatory during bugfix delivery.
The supported controller path remains the repo-local orchestrator contract until a runtime-specific direct syntax is freshly validated.
Manual role sequence stays valid across runtimes: /pm -> /ba -> /arch -> /dev -> /qa.
Downstream implementation execution happens in SDTK-CODE after the upstream handoff is approved.

Create a complete feature scaffold

sdtk-spec generate --feature-key ORDER_TRACKING --feature-name "Order Tracking" --project-path "."

Run with verbose script output

sdtk-spec generate --feature-key ORDER_TRACKING --feature-name "Order Tracking" --project-path "." --verbose

Troubleshooting

Common setup errors and the fastest fix path.

Unknown command or flag: run sdtk-spec --help and compare option names.
Missing required flag: generate requires both --feature-key and --feature-name.
Invalid feature key: must match ^[A-Z][A-Z0-9_]*$ (example: ORDER_TRACKING).
Activation fails: rerun sdtk-spec activate --license <KEY> and verify the purchased key is still valid for this machine.
PowerShell dependency error: ensure powershell.exe or pwsh is available in PATH.
Codex skills unavailable: rerun sdtk-spec init --runtime codex and verify $CODEX_HOME/skills/ or ~/.codex/skills/.
Claude skills missing: rerun sdtk-spec init --runtime claude --force and verify .claude/skills/ exists.
Use sdtk-spec runtime uninstall when you want to remove only SDTK-SPEC-managed skills; use npm uninstall -g sdtk-spec-kit when you want to remove the npm package itself.
Generated files still contain placeholders: continue with the PM/BA/ARCH/DEV/QA enrichment workflow.
Maintainers can run products/sdtk-spec/toolkit/scripts/check-runtime-readiness.ps1 from the source repo before deeper runtime debugging.

Advanced auth troubleshooting only

sdtk-spec auth --status
sdtk-spec auth --logout

Verify Claude skills installation

ls .claude/skills/

Inspect Codex skills folder (Windows)

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }; echo $codexHome; dir (Join-Path $codexHome "skills")

Re-run init with detailed output (Claude)

sdtk-spec init --runtime claude --project-path "." --force --verbose

Remove SDTK-SPEC runtime assets only

sdtk-spec runtime uninstall --runtime claude --scope project

Remove the SDTK-SPEC npm package only

npm uninstall -g sdtk-spec-kit

Maintainer readiness audit

powershell -ExecutionPolicy Bypass -File ".\products\sdtk-spec\toolkit\scripts\check-runtime-readiness.ps1" -Runtime claude

Release Notes

Current public baseline after Superpowers adoption and core hardening.

Version: 0.4.7 (npm package: sdtk-spec-kit)
CLI contract: init, update, runtime, auth, generate, plus --help and --version.
Generate command enforces the 17-file scaffold contract when not using --validate-only.
Superpowers adoption shipped verification gates, two-stage review, model-selection guidance, DOT flowcharts, and Codex parity docs.
Core hardening shipped the skill catalog, critical constraints, handoff templates, exact-spec quoting, public example packs, and runtime readiness auditing.
Codex runtime defaults to user scope and supports a bounded project-local path only through the explicit local CODEX_HOME=<project>/.codex contract.
Claude runtime installs bundled skills at project scope by default, with optional user scope and --skip-runtime-assets override.
The broader suite framing is now SDTK-SPEC -> SDTK-CODE -> SDTK-OPS plus SDTK-WIKI for local second-brain knowledge workflows, while this docs page remains SDTK-SPEC-specific.
Landing and docs copy now describe phase-by-phase enrichment honestly instead of overclaiming one-shot final-document generation.

Companion product pages

Use the right page when the work moves downstream

This docs page remains about SDTK-SPEC. Use the dedicated SDTK-CODE, SDTK-OPS, and SDTK-WIKI pages once the active concern becomes implementation execution, operations validation, or local second-brain knowledge work.

Current docs page