Local-first CLI

Keep AI coding agents from losing the thread.

DevSpecs is a local-first CLI that turns repo context into small agent-ready tasks: packed source/tests, bounded prompts, explicit checkpoints, and recoverable next steps.

ds tldr
ds task "fix OAuth redirect"

Try one task locally See demo Star on GitHub

Try in under 5 minutes. Start agents with `ds tldr`. Free. Local SQLite. No code upload.

FastAPI task flow

ds task -> apply -> checkpoint -> apply

packed source + testscheckpointed slices

Replay from captured FastAPI CLI samples. Each slice, prompt, and checkpoint stays in local files.

ds task "fix Swagger OAuth redirect"

Plain English

DevSpecs helps AI coding agents stop losing the thread.

It creates small local task slices from your repo, packs the relevant source, tests, and docs, gives the agent the next bounded prompt, and records what happened after each attempt.

You keep your existing repo and issue tracker. DevSpecs adds a local SQLite index and task loop inside the workflow you already use.

Run ds tldr

ds tldr

Give the agent a short, workflow-specific starting point before it touches the repo.

Create one task

ds task "fix OAuth redirect"

DevSpecs packs relevant source, tests, docs, and stop conditions into a local task slice.

Apply + checkpoint

ds apply next
ds task checkpoint A01 --decision improve

The agent gets one bounded prompt. You record what happened and whether to promote, improve, or rework.

Who it is for

Engineers using Claude, Codex, Cursor, Windsurf, or other coding agents on real repositories where context and handoff matter.

What it is not

DevSpecs does not replace Jira, Linear, GitHub Issues, or Notion. It adds a local task/context loop inside your repo.

Install

Install locally, then start with the workflow.

Use your package manager when it fits. `ds tldr` is the fastest starting point when you want DevSpecs to recover the local thread and suggest the next command.

brew install devspecs-com/tap/devspecs

Give the agent the rules first.

Shows LLM-oriented workflows for hotfixes, epics, incidents, handoffs, and repo onboarding.

ds tldr

Read workflow docs

Local evidence graph

Drop it into the repo you already have.

DevSpecs does not ask you to move planning into a new platform. It reads local intent artifacts, source, tests, docs, and git activity, then uses that evidence to ground repo maps, evidence packs, and recent-work recovery.

This is the trust layer under the task loop. Use it to understand likely task areas, inspect evidence, and recover recent direction before asking for the next bounded change.

Intent

Code

History

Local index

Intent

plansADRsPRDsRFCsrunbooks

Code

sourcetestsdocsconfigs

History

git activityrecent workcheckpoints

Local index

SQLite on your machine

Rebuildable cache. Source files stay authoritative.

Orient

ds map

System boundaries

Inspect

ds find

Evidence packs

Continue

ds recent

Local direction

AI work layer

Epics, stories, and tasks do not cover the agent loop.

Issue trackers describe intended work. Agents create attempts, misses, learnings, and iteration slices between ticket updates.

Tasks pack their own context

`ds task` writes source files, tests, intent, and stop conditions into a local task slice before the agent starts.

Decision gates stay explicit

Use `promote`, `improve`, `rework`, `rollback`, or `block` instead of vague done/not-done handoffs.

Iterations stay attached

`improve` or `rework` can turn A01 into A01-1/A01-2, so the next attempt stays grounded in what the last one learned.

Agents can query the graph

Agents can call `ds map`, `ds find`, and `ds context` to inspect local repo evidence before changing code.

Works from agent tools

`ds init` can write thin adapter files so Codex, Cursor, Claude, and Windsurf route back through the same CLI primitives.

Boring on purpose

No required MCP server, no LLM calls, no cloud sync. DevSpecs is a local control layer for AI-native workflows.

Jobs

Use DevSpecs at the points where AI coding work usually drifts.

See commands

> ds task "fix OAuth redirect"
Created task: oauth-redirect
Next: ds apply next
Packed: source + tests + docs

Bound an agent task

The agent needs a smaller target, relevant source/tests, and a clear stop line.

ds task "fix OAuth redirect"

Docs

> ds find "OAuth redirect"
Source: fastapi/openapi/docs.py
Tests: tests/test_swagger_ui_redirect.py
Why: docs route + OAuth redirect

Inspect the evidence

The human wants to know why these files, tests, plans, and exclusions are in the working set.

ds find "OAuth redirect"

Docs

> ds map
Subsystem: API docs routing
Boundary: fastapi/openapi/**
Try: ds task "modify API docs routing"

Map a new repo

The human or agent is entering unfamiliar code and needs repo evidence before editing.

ds map

Docs

> ds task checkpoint A01 --decision promote
Stage: validated
Next target: A02
Evidence: tests passed

Keep the receipt

The next session needs to know what changed, what ran, what failed, and what comes next.

ds task checkpoint A01 --decision promote

Docs

Demo

Real task flow, inspectable output.

The FastAPI demo shows DevSpecs packing source and tests into a task, emitting the next bounded prompt, checkpointing the result, and carrying verified leads into the next slice.

Instead of asking the agent to rediscover FastAPI docs routing every session, DevSpecs gives it the relevant source/test working set and a stop condition.

Task flowpacked source + testsdecision checkpoint

Create one grounded task, emit the next bounded prompt, checkpoint F01, then carry verified leads into F02.

Trust layerpacked source + testsdecision checkpoint

Use map and find when the target is unclear, then turn the evidence into a bounded task loop.

Captured FastAPI CLI samples power these demos. See the task workflow transcript for normalized CLI output.

Show demo command

cd fastapi

ds task "fix Swagger OAuth redirect" --id fastapi-oauth-redirect

ds apply next

ds task checkpoint fastapi-oauth-redirect --target F01 --decision promote --next-target F02

Slash commands beta

Same CLI, thinner entry points for agent tools.

Slash commands do not replace DevSpecs. They give Codex, Cursor, Claude, and Windsurf a shorter path back to `ds task`, `ds apply`, and the same local files.

ds init --yes --tool codex,cursor,claude,windsurf

Beta wrapper

Create the bounded task

Turns a goal into local task slices with packed source/test context and a one-target prompt.

/ds-task "fix OAuth redirect"
$ds-task "fix OAuth redirect"

Beta wrapper

Apply the next slice

Asks DevSpecs for the current next slice and emits an agent prompt that respects the decision gate.

/ds-apply <task-id>
$ds-apply <task-id>

Up next

Keep the CLI useful before adding heavier surfaces.

View roadmap

Short-term

Agent adapters

Improve `ds init` adapters, local slash commands, and tool-specific recipes over the same CLI primitives.

Mid-term

Workspace support

Make multi-repo views and workspace config easier to search, address, and hand to agents without forcing one repo layout.

Long-term

Measured context quality

Publish reproducible evidence for better source, test, and intent context as claims become stable.

Try it

Try one bounded task in your repo.

Install DevSpecs, run `ds tldr`, then create one task slice before handing work to an agent.

Install CLI Read task flow