devspecs-cli

README

DevSpecs CLI

Local-first CLI for AI coding work as addressable task slices.

DevSpecs helps developers and coding agents work from durable intent instead of one-off chat context. It indexes the plans, specs, ADRs, PRDs, task notes, and OpenSpec changes already in a repository, then helps start new work from bounded, repo-grounded task slices with packed source/test context.

• Website: devspecs.com
• Docs: docs.devspecs.com
• Public task transcript: TASK_WORKFLOW_EXAMPLE.md
• Public eval boundary: EVALS.md
• Changelog: CHANGELOG.md
• Releases: GitHub Releases

Why

AI-assisted development creates a lot of useful intent artifacts: plans, checklists, ADRs, PRDs, RFCs, OpenSpec changes, implementation notes, and follow-up summaries. They are valuable, but they often end up scattered across repo folders, editor state, pull requests, and ad-hoc files.

DevSpecs gives those artifacts stable local identity and makes them useful to the next human or agent session.

Its launch workflow is task-first:

• Known work: start ds task or ds task quick to create a bounded agent workspace with packed source/test/doc context and decision gates.
• Unclear work: use ds map, ds recent, and ds find as diagnostic/evidence tools, then convert the result into a bounded task.

DevSpecs is not an autonomous agent, task manager, SaaS workspace, or hosted memory layer. The CLI is the product; generated editor and agent files are thin wrappers over the same local ds task and ds apply commands.

Install

macOS / Linux

brew install devspecs-com/tap/devspecs

or:

curl -fsSL https://raw.githubusercontent.com/devspecs-com/devspecs-cli/main/install.sh | sh

Windows

scoop bucket add devspecs https://github.com/devspecs-com/scoop-bucket
scoop install devspecs

or:

irm https://raw.githubusercontent.com/devspecs-com/devspecs-cli/main/install.ps1 | iex

Go

go install github.com/devspecs-com/devspecs-cli/cmd/ds@latest

After installing or upgrading, restart your shell or IDE terminal if ds is not found. Verify the active binary with:

ds version

Check for updates with:

ds update

ds update is guidance-only: it shows the active binary, likely install source, latest release status, and the update command to run. It does not modify your system. Use ds update --no-check for offline guidance.

If an upgrade succeeds but ds version still shows the old build, restart the current shell or IDE terminal. Editors often keep an old PATH until their embedded terminal is reopened.

Agent quickstart

Start a repo with ds init. In an interactive terminal it can detect common layouts, prepare repo config, and offer Codex, Cursor, Claude, or Windsurf adapter files. The generated files route agents back through ds task and ds apply.

ds init
# then use the generated adapter when available:
/ds-task "goal"

Without an adapter, use the CLI directly:

ds task "goal"
ds apply <task-id>

Start agent sessions with ds tldr. It is the shortest way to remind an LLM to work on one bounded target, checkpoint evidence, and avoid claiming full repo coverage.

ds tldr
ds tldr setup
ds tldr hotfix
ds tldr incident --json

If the work item is already known, start with ds task or ds task quick. Task creation refreshes the local index and packs source, test, docs, and receipt context for the generated slice. Use ds map, ds recent, or ds find first only when the agent is still discovering system boundaries, recent activity, repo intent, current plans, or likely scope.

Intent artifacts and task workspaces

DevSpecs has a two-layer model:

• Canonical intent artifacts are the repo's existing PLAN-* files, ADRs, PRDs, RFCs, decision memos, north-star docs, OpenSpec changes, and runbooks. Humans still own these. DevSpecs should route agents to them, not replace reading them.
• Task workspaces under devspecs/tasks/<task-id>/ are execution slices: bounded plans, prompts, checkpoints, result receipts, and decision gates for one implementation thread.

When a repo already has an owner decision doc, link or reference it from the task workspace instead of duplicating the canonical gate. A good pattern is: PLAN-* says what/why; devspecs/tasks/* says what the next agent should do now and records what actually happened.

Bounded Task Slices

Use ds task when you are about to ask an agent to make a repo change and want the first slice to be grounded before the agent grabs the whole roadmap.

For multi-slice features, epics, migrations, or architecture work, use full ds task:

ds task "Serve Swagger UI OAuth2 redirect from a custom docs redirect URL" \
  --profile code-change \
  --slice "Trace Swagger UI OAuth2 redirect flow and tests" \
  --slice "Wire custom docs redirect URL through FastAPI docs helpers" \
  --slice "Add regression coverage and docs examples"

ds task show A01
ds task prompt A01
ds apply <task-id>
ds task checkpoint <task-id> --target A01 --stage validated --decision promote
ds task finish A01 --decision promote
ds task next <task-id>

What this gives you:

• an A00 task index;
• A01, A02, ... slice plan/result artifacts;
• packed source, test, docs, and receipt context;
• a one-slice agent prompt;
• explicit decision gates: promote, improve, rework, rollback, block;
• a completion contract for what changed, evidence, remaining work, and the next iteration;
• lifecycle state from start, checkpoint, finish, decide, and refresh.

For a small one-off change, bugfix, or doc spike, use the lighter entrypoint:

ds task quick "Fix discount rounding in invoice totals"

Use full ds task when you want durable slices and handoff receipts. Use ds task quick when the cost of a full task workspace would exceed the change.

See TASK_WORKFLOW_EXAMPLE.md for a public-safe transcript generated from current CLI output.

Diagnostics: recover existing intent

When a repo already has plans, PRDs, RFCs, ADRs, specs, runbooks, eval cards, recent commits, or agent notes, the fastest path is still ds task if the work is actionable. Task creation refreshes the index and packs source, test, docs, and owner-artifact context for the slice.

ds init
ds task "Serve Swagger UI OAuth2 redirect from a custom docs redirect URL"
ds task show A01
ds task prompt A01

Use map/recent/find/context as the trust layer around the task when the target is unclear, when you need to recover owner intent, or when stale history might confuse the agent.

ds map
ds recent
ds find "oauth redirect"
ds context <id>

ds map, ds recent, ds find, and ds context refresh the local index as needed. ds map summarizes architecture/system boundaries with evidence and follow-up commands. ds recent summarizes recently active local git topics. ds find groups source, tests, docs, receipts, and exclusions into an agent-readable context pack by default. Use ds find --plain when you want the older flat ranked result list. Use ds scan when you want an explicit manual refresh or rebuild.

ds find is a routing layer, not a replacement for owner decision docs. When it surfaces a current decision memo, north-star doc, or Status: next plan, read that artifact while creating or continuing the bounded task. Diagnostics are optional for known work; they are there to build trust when scope is unclear.

ds adopt is planned, not shipped. Current brownfield workflows scan and query existing artifacts in place without mutating old files.

What DevSpecs Indexes

DevSpecs currently indexes:

• OpenSpec changes;
• ADR directories such as docs/adr, docs/adrs, adr, and adrs;
• markdown plans/specs/PRDs/design docs under common paths such as plans, docs/plans, docs/specs, .cursor/plans, docs/design, and docs/technical;
• common agent and planning layouts, including Cursor, Spec Kit, BMAD output, Claude, and Codex samples used by tests;
• checklists, acceptance criteria, success criteria, and OKR-style criteria;
• task workspaces created by ds task.

Source files remain authoritative. DevSpecs stores derived index state locally.

Core Commands

Command	Use
ds init	Create local index state, repo config, and optional agent adapter files.
ds tldr [workflow]	Show LLM-oriented workflow quickstarts for setup, hotfixes, epics, incidents, brownfield recovery, handoff, and deep dives.
ds task <query>	Create a bounded task workspace with slice artifacts.
ds task quick <query>	Create a one-off task workspace with compact output.
ds task show <target>	Show exact context for one task target.
ds task prompt <target>	Emit an agent prompt bounded to one target.
ds apply <next|task-id|target>	Emit the next bounded one-slice agent prompt without mutating task state.
ds task checkpoint <target>	Record files, tests, misses, noise, learnings, decision evidence, and next iteration.
ds task finish <target>	Finish a target with a decision gate.
ds task refresh <task-id>	Recapture edited task artifacts into the local index without rewriting task docs.
ds map	Show architecture/system boundaries with evidence and useful follow-up commands.
ds recent	Show recently active local git topics and useful follow-up context commands.
ds find <query>	Build agent-readable packed context.
ds find --plain <query>	Show the older flat ranked result list.
ds update	Show update guidance and latest-version status for the active binary.
ds context <id>	Export one artifact as paste-ready agent context.
ds scan	Manually refresh or rebuild configured intent-artifact paths.
ds config show	Inspect effective repo discovery config.

Most read commands support --json. Run ds <command> --help for the current flag surface.

Storage And Privacy

Location	Role	Commit?
~/.devspecs/devspecs.db	Local SQLite index and cache.	No.
.devspecs/config.yaml	Repo discovery configuration.	Usually yes.
devspecs/tasks/<task-id>/	Default generated task workspace.	Yes, when durable.
.devspecs/tasks/<task-id>/	Legacy or explicitly local task workspace.	No, unless you chose it deliberately.

Commit task artifacts when they explain durable work, should be reviewed with a change, or are useful to the next person or agent. If a task is scratch-only, ignore devspecs/tasks/<task-id>/ yourself or use an alternate workspace path. Lifecycle commands auto-detect legacy .devspecs/tasks/<task-id>/ workspaces when the visible default path does not contain that task.

Telemetry is minimal and anonymous. It is used for install, init, scan, and query flow health, and excludes repository names, file paths, git remotes, artifact titles, document text, source code, and raw search queries.

Disable it with:

DEVSPECS_TELEMETRY=0

or:

DS_TELEMETRY=0

Use DEVSPECS_TELEMETRY=debug to print the would-send event to stderr.

Install Troubleshooting

If ds is not found after install or upgrade:

1. Restart the current shell or IDE terminal.
2. Run ds version to confirm which binary is active.
3. Run ds update to see the likely install source and update command.

If the command still is not found, make sure the install directory from Homebrew, Scoop, Go, or the install script is on your PATH.

Public Eval Boundary

The public repo contains deterministic product tests and small synthetic fixtures. It is the product claim surface, not a dump of exploratory research material or unreduced evaluation runs. Public claims should stay tied to reproducible public fixtures and documented behavior.

See EVALS.md for the current boundary.

Development

git clone https://github.com/devspecs-com/devspecs-cli.git
cd devspecs-cli
go test ./... -count=1
go run ./cmd/ds --help

Useful checks:

gofmt -l .
go vet ./...
staticcheck ./...

To enable the repo pre-commit hook:

make hooks

The hook runs go vet, staticcheck, gofmt -l, and by default go test -count=1 ./....

Releasing

Releases use GoReleaser via GitHub Actions.

git tag v1.1.0
git push origin v1.1.0

License

MIT License