# sdtk-code-kit

`SDTK-CODE` is the coding-process product in the `SDTK-SPEC -> SDTK-CODE -> SDTK-OPS` family.

## Document Role
This README is the npm package landing page for `sdtk-code-kit`.

Use it to confirm:
- package name and install command
- canonical command surface
- runtime scope truth
- upstream dependency boundary

For the full end-user guide, use:
- `products/sdtk-code/governance/SDTKCODE_TOOLKIT_USAGE_GUIDE.md`

## Public Package Truth

- package: `sdtk-code-kit`
- version in this source snapshot: `0.4.3`
- command: `sdtk-code`
- latest published version lookup: `npm view sdtk-code-kit version`
- primary workflow-first surface:
  - `start`
  - `plan`
  - `build`
  - `verify`
  - `ship`
  - `status`
  - `doctor`
  - `resume`
- support commands:
  - `init`
  - `update`
  - `runtime install`
  - `runtime status`
  - `runtime uninstall`
  - `help`
  - `--version`

Not part of the v1 public surface:
- `generate`

## Install

```powershell
npm install -g sdtk-code-kit
sdtk-code --version
sdtk-code --help
```

If you need the exact latest published version number, run:

```powershell
npm view sdtk-code-kit version
```

## Update Existing Installation

Use the public `update` command when `sdtk-code-kit` is already installed and you want the newest published package line.

```powershell
sdtk-code update --check-only
sdtk-code update --runtime claude --project-path ./my-project
```

Codex user-scope variant:

```powershell
sdtk-code update --runtime codex --scope user --project-path ./my-project
```

Project-local Codex refresh is also supported, but only when you intentionally launch the runtime with the explicit local `CODEX_HOME=<project>/.codex` contract. Native `.codex/skills` auto-discovery is still not claimed.

Then verify:

```powershell
sdtk-code --version
sdtk-code runtime status --runtime claude --project-path ./my-project
```

Important truth:
- `sdtk-code update` still uses `npm install -g sdtk-code-kit@<target>` as the package refresh mechanism
- `update --check-only` is non-destructive and prints the planned commands only
- `init --force` refreshes managed project files
- `runtime install --force` refreshes managed runtime assets
- existing workflow docs are not automatically regenerated

## First Quick Start

Initialize the workspace first:

```powershell
sdtk-code init --runtime codex --project-path ./my-project
```

After upstream `SDTK-SPEC` inputs already exist, start the workflow:
- preferred: `docs/dev/CODE_HANDOFF_[FEATURE_KEY].json`
- bounded fallback when the formal handoff file is missing:
  - `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
  - `sdtk-spec.config.json`

```powershell
sdtk-code start --feature-key ORDER_MGMT --lane feature --project-path ./my-project
```

Use Claude instead when you want the simplest project-scope runtime path:

```powershell
sdtk-code init --runtime claude --project-path ./my-project
```

## Runtime Truth

| Runtime | Project scope | User scope | Current truth |
|---|:---:|:---:|---|
| Claude | Yes | Yes | installs `code-*` skills |
| Codex | Yes | Yes | installs `sdtk-code-*` skills; default is user scope and project-local installs require the explicit local `CODEX_HOME=<project>/.codex` contract |

## Remove Runtime Assets vs Remove the Package

Use:

```powershell
sdtk-code runtime uninstall --runtime claude --scope project --project-path ./my-project
sdtk-code runtime uninstall --runtime codex --all
```

when you want to remove only SDTK-CODE-managed runtime skill folders.

Important truth:
- `runtime uninstall` removes only SDTK-CODE-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/`

Use:

```powershell
npm uninstall -g sdtk-code-kit
```

when you want to remove the global npm package and CLI shim only.

That npm command does **not** remove runtime assets that were already copied into Claude or Codex skill folders.

## Upstream Dependency

`SDTK-CODE` is publicly installable, but real workflow execution still expects upstream `SDTK-SPEC` artifacts.

Task-breakdown truth:
- upstream `SDTK-SPEC` `/dev` still owns implementation-readiness planning and formal handoff scope
- `FEATURE_IMPL_PLAN_[FEATURE_KEY].md` remains the upstream readiness plan
- `sdtk-code plan` refines downstream execution slices only after intake succeeds

Preferred intake artifact:
- `docs/dev/CODE_HANDOFF_[FEATURE_KEY].json`

Bounded fallback when the formal handoff file is missing:
- `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
- `sdtk-spec.config.json`
- relevant architecture, API, database, and flow/screen specs for the current slice when applicable

Blocking truth:
- invalid or upstream-blocked formal handoff must stop `sdtk-code start`
- no silent fallback is allowed when the formal handoff file already exists but is invalid

## Downstream OPS Bridge

Completed closeout from a formal-handoff-backed workflow writes the canonical downstream bridge:
- `docs/dev/OPS_HANDOFF_[FEATURE_KEY].json`

Important boundary:
- this bridge is produced by `SDTK-CODE` for downstream `SDTK-OPS`
- compatibility fallback workflows do not invent a fake `OPS_HANDOFF` without the current `CODE_HANDOFF_[FEATURE_KEY].json`

## Workflow Recovery

First-wave bounded recovery commands for `SDTK-CODE`:
- `sdtk-code status`
- `sdtk-code doctor`
- `sdtk-code resume`

Behavior truth in this wave:
- `status` is minimal and actionable: current phase, next phase, blocking state, resume guidance
- `doctor` is diagnostic only (no auto-repair)
- `resume` is fail-closed when operator-only inputs are still required
- auto-dispatch is intentionally narrow to machine-safe build transitions only
- lifecycle truth remains inside `docs/dev/CODE_WORKFLOW_[FEATURE_KEY].md` (no second persistence store)
## Verify Output Truth

`sdtk-code verify` records summarized evidence in `docs/dev/CODE_WORKFLOW_[FEATURE_KEY].md` and also emits:
- `docs/dev/REVIEW_PACKET_[FEATURE_KEY].md`

Important boundary:
- the review packet is an evidence package for downstream QA/controller review
- it does not replace QA release authority and it is not a final approval artifact

## Sleep Mode (free readiness gate + Pro unattended execution)

Free (dry-run, nothing is executed):
- `sdtk-code sleep plan --feature-key <KEY>` assembles a bounded plan from the CODE_HANDOFF. Declare the file scope the run may touch with `--allowed <glob>` / `--blocked <glob>` (repeatable) or `--scope-file <path>` (a JSON `{ "allowed_file_scopes": [...], "blocked_file_scopes": [...] }`).
- `sdtk-code sleep report --feature-key <KEY>` grades the plan `READY_TO_SLEEP` or `NOT_READY` with the blocker/warning list.

Pro (entitlement-gated, capability `code.sleep.execute`):
- `sdtk-code sleep authorize --feature-key <KEY>` is the attended consent step. It requires an active Pro entitlement, a `READY_TO_SLEEP` plan/report, a bounded declared scope, and an exact typed confirmation on an interactive TTY. It writes `.sdtk/trust/sleep-authorization.json`, cryptographically bound (sha256) to the exact sleep-plan bytes and pinned scope, with budget caps and a TTL (defaults: 3 iterations / $3.00 / 8h; per-authorization raisable up to 10 / $10.00 / 24h).
- `sdtk-code sleep execute --feature-key <KEY>` runs the bounded session headlessly against a valid, unexpired authorization — the actual "work while you are away" capability. It reuses the same stop conditions, budgets, and doc-class patch guards as the attended `agent-team sleep-execute` preview. Editing the plan, broadening the scope, or letting the authorization expire invalidates it and the run fails closed.

Boundaries: v1 authorizes doc-class patches only (`docs/**.md`, `governance/**.md`, `README.md`, `AGENTS.md`). The **CLI** exposes no unattended path without an active Pro entitlement and the installed `sleep-execute-pro` pack. The engine function itself ships in the public kit, so a caller who can already run arbitrary Node on the machine can invoke it directly — but any such call is still bounded by the same envelope every path enforces: doc-class patch guard, hard ceilings (10 iterations / $10.00 / 24h TTL), per-iteration readiness re-check, pinned scope, and worktree isolation with no auto-merge. Entitlement is a licensing/honesty boundary, not a defense against local code execution. Model/API cost is user-provided via your own provider key, not SDTK-hosted.

## References

- Canonical end-user guide:
  - `products/sdtk-code/governance/SDTKCODE_TOOLKIT_USAGE_GUIDE.md`
- Install and smoke appendix:
  - `products/sdtk-code/governance/installation-runbook.md`
- Product boundary and architecture:
  - `products/sdtk-code/toolkit/SDTKCODE_TOOLKIT.md`