Command reference
Every command takes --root <dir> (the shell function sets it to your current
directory) and most take --auto for non-interactive runs. Every AI command opens
with a model · root preamble and ends with a Next: hint;
sdd help (or -h) lists them all.
The pipeline
| Command | What it does |
|---|---|
| sdd [dir] sdd setup |
Bootstrap a project. Three evidence-based passes — operational (detect stack +
commands, run the safe ones for a real baseline), purpose (draft
PRODUCT.md, interrogate you to correct it — a greenfield repo gets
interviewed), process (how you ship) — plus an interactive
domain-expert picker, behind one review gate. Writes CLAUDE.md,
PRODUCT.md, .sdd/config.json (recording the model + expert roster);
re-runs never clobber your edits. |
| sdd · sdd interactive | Once set up, a bare sdd opens the live navigator on a
terminal — arrow through features, ↵ runs a feature's next stage inline,
p/b/r/n/s/m/l
for the rest. Piped/CI (or sdd hub / --no-interactive) prints the
static summary; -i/sdd interactive forces the navigator. |
| sdd help · sdd --version | The full command list (-h; an unknown command prints it too, rather than
failing silently); --version / sdd version prints the installed
version, also shown in help and the navigator. |
| sdd spec "<desc>" | Draft specs/<slug>/spec.md. The expert panel (product, UX, security +
your domain roster) raises considerations; you answer the combined questions one at a
time and the spec is refined with your answers. |
| sdd plan <slug> | Decompose the spec into plan.md — an ordered list of small,
independently-testable tasks, built for trunk-based CI/CD (feature-flag what isn't ready
to expose). Same interrogation flow. |
| sdd build <slug> | Implement a task (--task N, default 1; --all for the remaining
tasks) and run the implement → test → fix loop, bounded. The header shows
task N of M. Branches to sdd/<slug> first when you're on a
trunk (--no-branch to opt out). Edits auto-apply; the agent cannot run shell
commands — the CLI verifies. Never commits, and a task that changes nothing is a
⚠ warning, not a false ✓. The header prints the detected stack
(or greenfield — task 1 should scaffold) so you always know what it's building. |
| sdd review [<slug>] | Review the diff against the spec + plan with the multi-lens panel, adversarially
verified. Writes review.md; --comment posts to the current
branch's PR (--pr N to target one). --base <ref> to diff
against a ref. |
| sdd feature "<desc>" | The whole pipeline in one shot: spec → plan → build (all tasks) → review, branching first. For when you've calibrated trust. |
| sdd status | Every feature's position in the pipeline — which artifacts exist, and any review findings. |
The board & the runner
| Command | What it does |
|---|---|
| sdd link | Connect this repo's GitHub board: detects the origin remote, records it in
.sdd/config.json, and provisions the gate labels. No remote?
It offers to create one under your gh-authed account
(gh repo create) and wire origin — rather than erroring.
--project also creates an aggregating GitHub Project. |
| sdd board [--project] | Provision the gate labels (sdd:spec … sdd:done,
sdd:awaiting-you) on the configured repo. With --project, also
create/reuse a GitHub Project as an aggregating view. When nothing's connected yet it falls
through to the sdd link create-a-repo flow. With a product registry, provisions
every owned part's repo + one org-level Project. |
| sdd new "<title>" | Open a ticket already in the pipeline (labelled sdd:spec).
--body "…" for detail. |
| sdd approve <n> | Approve a ticket at a review gate → advance to the next stage
(spec-review → plan, plan-review → build,
build-review → review). |
| sdd bounce <n> | Send a review-gate ticket back to its stage for another pass.
--note "why" posts your feedback as a comment the next pass reads. |
| sdd draft <n> | Pull a ticket into the interactive TUI — draft → interrogate → refine, with experts — then push the result back onto the ticket and advance its gate. The synchronous alternative to the comment-thread dialogue. |
| sdd run | The headless runner: poll the board, dispatch actionable tickets under a concurrency cap.
--once for a single cycle, --max-agents N (default 3).
Inert until runnerActive: true in .sdd/config.json. Unattended
use wants ANTHROPIC_API_KEY; --allow-subscription overrides for
personal, hands-on runs. |
Multi-repo products
| Command | What it does |
|---|---|
| sdd product init | Scan the current folder's child git repos and scaffold the product registry
(.sdd/project.json) + a shared PRODUCT.md.
--name "<product>", --reference "a,b" to mark
context-only parts. With a registry present, spec/plan ground
across the parts and the runner's build fans out a PR per repo. |
Flags & environment
| Flag / variable | Effect |
|---|---|
| --verbose · --vv | Narrate what's happening. Setup shows each pass live — detecting the stack, running `pnpm test` for a baseline… ✓ in 3.2s, drafting PRODUCT.md. This is the answer to "why is sdd slow": it runs your real test/build commands for a baseline. |
| -i / --interactive · --no-interactive | Force the live navigator on / off for a bare sdd (default: navigator on a terminal, static summary when piped). |
| --auto · --root <dir> · --all | Non-interactive run · act on a specific project dir (the shell function sets it) · build all remaining tasks. |
| SDD_MODEL | Route the AI stages to a model: sonnet, haiku, or a full model id. Setup records the chosen model into .sdd/config.json, so later commands pick it up without the prefix; every AI command shows it in its preamble. Default: your Claude Code model. |
| ANTHROPIC_API_KEY | API-key auth for the unattended runner (a subscription is for interactive use, per Anthropic's terms). |
| GH_TOKEN | Standard gh auth override for board/PR operations. |
Files it reads & writes
PRODUCT.md # north star — created by setup, corrected by you
CLAUDE.md # `sdd-framework` block: stack, commands, process
.sdd/config.json # expert roster, model, board connection, runner flag
.sdd/project.json # multi-repo only: the parts registry
specs/<feature>/spec.md # the what
specs/<feature>/plan.md # the how — ordered task list
specs/<feature>/review.md # the panel's verified findingsAll committed, all human-editable. Setup and product-init never overwrite an existing file without your explicit approval.