Problem solved

AI coding agents often leave changes in a repository with no explanation of why they were made, what state they are in, or what the next action should be. Git shows what changed, but reconstructing intent and reviewing next steps manually is expensive. DevSpecs solves this by maintaining a local thread of evidence, decisions, checkpoints, and lifecycle state attached to the repo, so humans and agents can recover context before editing.

Use cases

• Recover the active AI coding thread after returning to a repository using `ds recent`
• Create lightweight task specs with packed context, gates, and iteration slices using `ds task`
• Review an AI agent's changes by comparing source evidence with the recorded intent and next actions
• Hand off bounded work between AI agents and human developers with clear checkpoints and decisions
• Index existing repo plans, ADRs, PRDs, and notes into a local SQLite index for quick context retrieval
• Run disposable experiments on real repositories like FastAPI to learn the workflow without touching your own code

Audience

• Developers
• ML Engineers
• Data Scientists

Pros

• Local-first with no cloud sync or LLM calls, preserving privacy and avoiding extra costs
• Works alongside Git and rg rather than replacing them
• Lightweight CLI with simple subcommands (`recent`, `task`, `apply`)
• Stores durable intent, evidence, decisions, and checkpoints in local files and SQLite
• MIT licensed and free to use

Cons

• Does not replace issue trackers; only tracks the local AI work layer
• CLI-only interface may be less accessible to non-technical users
• Requires team adoption and manual initialization in each repository
• No built-in LLM generation or automation; relies on external coding agents
• Limited to local repository context; no built-in cloud collaboration or sharing