devspecs

Local intent trail

Stop losing the thread.

DevSpecs keeps the durable thread of AI coding work attached to your repo, so you can let an agent run, come back later, and understand why the changes exist and what happens next.

ds recent
Install CLITry on FastAPI

Local-first. No cloud sync. No LLM calls. Works with your existing coding agents.

Git

what the agent changed

fastapi/openapi/docs.py
tests/test_swagger_ui_redirect.py

DevSpecs

why it exists, what to review next

Thread: Swagger OAuth redirect regression
State: tests passed, review required

Context recovery

Git shows what changed. DevSpecs shows what matters next.

Agents and developers already use Git and rg to inspect recent work. DevSpecs adds the local thread: why the change exists, what state it is in, and where to continue.

Q: Can we continue from here?

Git + rg

Source evidence

  • commits 02373aa, 9f2c1b7, 41d8e0c
  • changes fastapi/openapi/docs.py, tests/test_swagger_ui_redirect.py
  • tests test_swagger_ui_redirect.py
  • matches "OAuth redirect", "swagger ui", "oauth2RedirectUrl"

Context / thread

  • goal: infer from commits
  • state: infer from tests/history
  • old workaround: search manually
  • next step: choose manually
Outcome: evidence found; thread reconstructed manuallyCmds: 10Time: 78sTokens: ~18k
See how to review an agent's work after returning

Install

Try it in a repo in under five minutes.

Start with ds recent when you came back cold. Use ds task when the goal is already clear. On a large first run, DevSpecs shows indexing progress while keeping quiet and JSON output clean.

brew install devspecs-com/tap/devspecs

Come back after an agent.

Recover the active thread, lifecycle state, and likely next context before reviewing or continuing the work.

ds recent
Open reviewed workflow

Try on FastAPI

Use a real repo in a disposable checkout.

After installing ds, use FastAPI to feel the thread recovery and task handoff loop without touching your own code first.

git clone https://github.com/fastapi/fastapi
cd fastapi
ds init
ds recent
ds task "trace Swagger OAuth redirect behavior"
ds apply

DevSpecs writes local task files and a local SQLite index. Delete the checkout when you are done.

See reviewed FastAPI workflows

How it works

Use the context already in your repo.

DevSpecs reads repo files, docs, specs, plans, commits, and task records. It keeps evidence, decisions, checkpoints, and bounded handoffs connected so the next human or agent can recover the thread.

Intent

plansADRsPRDsnotes

Repo

sourcetestsdocscommits

DevSpecs

threadevidencenext

FAQ

Read the full FAQ

What is DevSpecs for?

DevSpecs keeps the durable work thread attached to the repo so humans and agents can recover intent, evidence, and handoffs before the next edit.

Why not just use Git and rg?

Keep using them. Git and rg show source evidence; DevSpecs adds lifecycle state, decisions, superseded work, and the next gate.

Does it call an LLM?

No. The CLI is local-first and boring on purpose: it indexes local artifacts and emits context your existing agent can use.

Does it replace my issue tracker?

No. Keep Jira, Linear, GitHub Issues, or Notion. DevSpecs tracks the local AI work layer underneath.

Is this a spec framework like OpenSpec?

Partly, but broader. DevSpecs can create lightweight task specs with packed context, gates, iteration slices, and checkpoints. It also works as a local navigation layer for the intent already scattered through your repo.