sdtk-kit

SDTK CLI -- deterministic documentation toolkit for software teams.

Wraps the SDTK PowerShell toolkit for portable, reproducible feature documentation scaffolding.

Install

npm install -g sdtk-kit
# or link locally for development:
npm link

Quick Start

# 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 files)
sdtk generate --feature-key USER_PROFILE --feature-name "User Profile"
# Codex runtime remains available:
# sdtk init --runtime codex

Commands

sdtk init

Initialize SDTK workspace in the current or specified project directory.

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.

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 / zsh
export SDTK_ENTITLEMENT_REPO=owner/repo
sdtk auth --verify

# 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.

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.

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:

# 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

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

# 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