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 dispatch task:<task-id>	Run one frozen target through an explicitly configured orchestration provider and return a receipt. Experimental.
ds compose adr|rfc|prd "<title>"	Create and index a repo-owned durable document draft. Experimental.
ds hub	Share repo or opt-in home-global topics, messages, validated events, pull subscriptions, and cooperative leases. Experimental. See Local Hub.

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.

Experimental Dispatch

ds dispatch is an opt-in bridge from one frozen ds apply --json target to an external orchestration provider. It runs inside the existing ds binary; installing DevSpecs does not install or configure an orchestrator.

Configure the provider in the repository that owns the task:

version: 1
integrations:
  orchestration:
    provider: waspflow
    options:
      executable: waspflow

Then verify readiness and dispatch one exact target:

ds doctor
ds dispatch task:checkout-redesign --task-repo . --cwd . --agent-provider codex

Dispatch waits for a normalized receipt by default. Detached operation keeps the same bounded lifecycle:

ds dispatch task:checkout-redesign --detach
ds dispatch status <dispatch-id>
ds dispatch resume <dispatch-id>
ds dispatch receipt <dispatch-id>

The first driver uses stock Waspflow commands; Waspflow does not require a DevSpecs patch. Provider runtime state remains provider-owned. DevSpecs stores only its frozen request, provider handle, and normalized receipt under $DEVSPECS_HOME/dispatches/. A provider may edit its isolated execution workspace, but it cannot checkpoint, promote, or otherwise mutate DevSpecs task lifecycle state. Configuration alone never launches work.

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. Default ds prune changes only the rebuildable SQLite index; explicit --hub prunes local coordination history. Neither mode 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 prune --hub --before <RFC3339> [--dry-run|--vacuum]	Explicitly remove eligible old local hub publications after a verified backup; optional vacuum reports actual reclaim.
ds doctor [--redact] [--json]	Inspect the active binary, local index compatibility, writer state, and repository identity without changing local state.
ds index backup [--output <file>]	Create a verified schema-agnostic SQLite snapshot.
ds index rebuild [--path <repo>]	Build and validate a complete replacement before publishing it.
ds index restore <backup-file>	Restore an exact snapshot while preserving the index it replaces.
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.

Local diagnostics

Run ds doctor before changing local state when an install, index, or repository operation behaves unexpectedly. It is offline and read-only: it does not create the DevSpecs home, migrate or repair SQLite, or contact the network.

ds doctor
ds doctor --redact
ds doctor --json --redact

Use --redact before sharing a report. A shadowed binary calls for a PATH fix; an older schema can migrate forward under the current CLI; a newer schema calls for updating the CLI rather than rebuilding the index. A held writer is a point-in-time observation, so wait for the active operation and retry. For a large index, inspect ds prune --dry-run before pruning or vacuuming.

Preserve an unreadable index while collecting the report. ds doctor reports evidence and bounded remediation; it does not perform backup or rollback. Repository identity probing is bounded at five seconds. If Git does not answer, doctor retains the other evidence and reports a warning.

Back up and recover the index

The SQLite index is rebuildable, but recovery is backup-first. Supported forward migrations create and verify a rollback snapshot before publishing the new schema. Use the explicit maintenance commands when you need a durable snapshot or a controlled repair:

ds index backup
ds index rebuild --path .
ds index restore <backup-file>

backup can snapshot a database whose schema is newer than the running CLI. rebuild performs a full cold scan into staged storage, validates it, and only then replaces the active index. restore publishes the selected snapshot without migrating it and preserves the displaced index first.

To return to an older CLI, restore a snapshot created by that CLI generation as your final current-CLI index action, then launch the older binary. Running a newer indexed command again may migrate it forward. Backups are stored under ~/.devspecs/backups/index/ and are not automatically removed.

The backup-first guarantee begins with v1.5.0, which includes ds index. DevSpecs v1.4.0's compatibility ds scan --rebuild deleted the active index before rescanning. Update first, or copy ~/.devspecs/devspecs.db while DevSpecs is idle before using that older rebuild path.

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.