What DevSpecs does, where it fits, and what to run first.

DevSpecs helps humans and agents keep AI coding work bounded. It keeps the durable work thread with the repo: relevant context, stop conditions, decisions, checkpoints, and the next handoff.

AI coding creates a new layer of work: prompts, attempts, decisions, failed paths, and unfinished next slices. DevSpecs preserves the useful parts of that layer locally instead of leaving them scattered across chat history.

They describe intended work. They usually do not capture the agent execution loop: what context was packed, what the agent tried, what failed, what was learned, and whether A01 should become A01-1 before moving to A02.

No. DevSpecs is a local CLI. It prepares bounded context and prompts for the agents you already use.

No. `ds task` creates the workspace and boundary. `ds apply` prints the next prompt. Your editor, terminal, or agent does the work.

Yes, as thin repo-local adapter files from `ds init`. Generic skill files expose `$ds-task` and `$ds-apply`; Cursor, Claude, and Windsurf-style files expose `/ds-task` and `/ds-apply`. They route back to the local CLI.

No. Code and documents stay local. CLI telemetry excludes paths, repo names, remotes, raw queries, document text, and source code.

Hand your agent `ds tldr` first. It explains the main workflows and the commands to use. If you already know the goal, run `ds task "your bounded goal"`. Use `ds recent`, `ds map`, or `ds find` when you need evidence before choosing the goal.

DevSpecs builds a local SQLite index so `ds map`, `ds recent`, and `ds find` can use your code, tests, docs, plans, and git history. Indexing progress stays out of `--json` and `--quiet` output.

Search finds strings. DevSpecs creates a durable task slice, packs related context, and records the decision gate.

Partly, but DevSpecs is broader. It can create lightweight task specs with packed source, tests, intent, decision gates, iteration slices, and checkpoints. It also works as a local codebase navigation layer by indexing existing plans, ADRs, PRDs, RFCs, docs, source, tests, git history, and task state without requiring a new spec process first.

DevSpecs is tool-neutral. Task files live in your repo, and the local index can be rebuilt.

`ds find` and `ds task` group likely source, tests, docs, receipts, and exclusions so the agent starts from a smaller working set.

You can. DevSpecs helps when broad inspection turns into scope drift. It gives the agent a smaller start and a stop condition.

They will improve agent memory and repo understanding, but teams still need local, tool-neutral records of what was attempted, accepted, rejected, and queued next. DevSpecs is that boring control layer: files, decisions, and evidence you can inspect without depending on one model or editor.

Commit task artifacts when they explain durable work. Keep local databases, private notes, and scratch output out of public repos.

Existing plans, PRDs, RFCs, ADRs, specs, docs, and agent notes can already be scanned, mapped, found, and exported in place. Planned adoption wrappers are only for making older intent files explicitly addressable and versionable without mutating originals by default.

No. `ds adopt` is planned. You do not need it to use existing artifacts today: the shipped trust layer is `ds scan`, `ds map`, `ds recent`, `ds find`, and exact artifact export with `ds context` when needed.

FastAPI is recognizable, source/test heavy, and a good fit for showing a bounded task slice with packed implementation and regression-test context.

Yes, by Git. Teams can version durable task and intent files while each developer keeps a local SQLite index. The CLI also includes experimental `ds workspace ...` commands for explicit umbrella-repo coordination.