Command Reference

Run ds <command> --help for exact current flags.

Start Here

Command	Use
ds init	Initialize local state, repo config, and optional agent adapter files.
ds task <query>	Create a bounded task workspace with packed context.
ds apply	Print the next one-slice agent prompt. It does not run an agent.
ds task checkpoint <task-id|target>	Record files, tests, misses, learnings, and decision gate.
ds thread [task:<task-id>|change:<change-id>]	Inspect named parallel lanes, waits, and joins. Experimental.
ds compose adr|rfc|prd "<title>"	Create and index a repo-owned durable document draft. Experimental.

Trust Layer

Use these when the target is unclear or you want evidence before creating or continuing a task.

Command	Use
ds map [area]	Show architecture/system boundaries from local repo evidence and suggest follow-up commands.
ds recent [topic]	Show recently active local work, boundary hints, and follow-up context commands.
ds find <query>	Build packed context for a query.
ds find <query> --plain	Show flat ranked results instead of the default context pack.
ds context <id>	Export one exact indexed artifact as agent-ready context.
ds show <id>	Show artifact details.

Task Lifecycle

Command	Use
ds task show <target>	Show exact context for one task target.
ds task status <task-id>	Show series, slice, and iteration state.
ds task slice add <task-id> "<title>" --after A01 --reason improve	Create a follow-up such as A01-1 under an existing slice after improve or rework.
ds task refresh <task-id>	Refresh task artifacts in the index without rewriting task docs.
ds task audit <target>	Compare observed work against target scope.
ds task "<query>" --quick	Create a compact one-off workspace for smaller slices.

After all slices in a full task are terminal, ds apply exposes one series closeout target such as A00. Complete it with ds task checkpoint and a --durable-record none|recorded|deferred disposition. Compact --quick tasks and task manifests created before v1.4 skip this review.

Named Execution Threads

Named threads are experimental scheduling lanes over existing task slices. They do not launch agents or create another task type. A normal task remains repo-owned and needs no workspace setup:

ds thread set task:checkout-redesign agent-a A01
ds thread set task:checkout-redesign human-a A02
ds thread set task:checkout-redesign both-a A03 --after agent-a --after human-a
ds thread task:checkout-redesign
ds apply task:checkout-redesign --thread agent-a

When several lanes are runnable, ds apply never picks the first one. Inspect ds thread and pass --thread <key>. Labels identify lanes; they are not assignments or running processes.

Only tasks explicitly linked to one workspace change join its cross-repo thread graph. Use the same root commands with change:<id> and --workspace; there is no separate ds workspace thread. After the shared graph completes, run ds apply <linked-task> --repo <child-repo> for each repo that still needs its one-time durability closeout.

Durable Documents

ds compose writes ordinary Markdown outside devspecs/tasks/ and captures it into the local index:

Command	Use
ds compose adr "<title>"	Record a settled, consequential technical choice.
ds compose rfc "<title>"	Propose a consequential direction that still needs review.
ds compose prd "<title>"	Define a product problem, users, outcomes, and requirements.

ADR format defaults to the recognized repository convention, with Nygard as the no-precedent fallback. --format supports nygard, madr, y-statement, outcome-first, and iso-42010; MADR supports --variant full|minimal. Ambiguous repository conventions fail instead of guessing.

The Markdown file is authoritative. ds prune only changes the rebuildable SQLite index and never removes repository files. If --output selects an unconventional directory, add that directory to .devspecs/config.yaml for deterministic discovery after an index rebuild.

Setup And Maintenance

Command	Use
ds scan	Index configured intent, source, test, docs, and git evidence paths. Most workflows can let task/find/map refresh automatically.
ds prune [--dry-run] [--vacuum]	Remove stale index rows and redundant revisions; optionally compact SQLite. Repository files are never deleted.
ds config show	Inspect effective repo discovery config.
ds update	Check latest release and print update guidance.
ds tldr	Show LLM-oriented quickstarts by workflow type.

Workspace Coordination

Workspace coordination is experimental and explicit. Use it when one umbrella directory coordinates work across several child repos.

Command	Use
ds workspace init .	Create an umbrella workspace manifest and change directory.
ds workspace change create "<title>"	Create a workspace-level change record.
ds workspace slice create <change-id>	Create a repo-local task slice linked to a workspace change.
ds workspace trace <change-id|task-id>	Trace known workspace changes and linked repo-local slices.

ds ws is a shortcut for ds workspace.

Cross-repo named lanes use ds thread change:<change-id> --workspace <root> and ds apply change:<change-id> --thread <key> --workspace <root>. Workspace commands create and link the owning artifacts; thread and apply remain the single scheduling surface.

Compose remains repo-local rather than adding ds workspace compose. From an umbrella root, pass --repo <child-repo> so the owning repository receives the document. Use the umbrella repository only when it is itself the canonical, versioned owner of a cross-repo document.

For task lifecycle work, prefer ds apply, ds task checkpoint, ds task refresh, and ds task "<query>" --quick.

Most read commands support --json for scripts and editor adapters. Non-quiet cold indexing progress is written to stderr. Use --quiet or --json for result-only automation, and --verbose when you need lower-level phase details.