Keep the reasons behind the code where they can be found.
Why the system is the way it is lives as tribal knowledge, lost chat threads, closed tickets, the descriptions or comments on a pull request that no one goes back to look at, or a document in Confluence that was out of date the moment it was written. A new engineer, or an AI agent asked to change the code, works from the code alone and makes on-the-fly decisions for what was already decided.
The code carries the decision, but loses context and the reasoning behind it.
Some spec-driven approaches treat the plan as the whole story: get the spec detailed enough before the work starts, and the code will follow from it. When it doesn't, the verdict is usually that the spec wasn't good enough, as if a better one up front would have produced the right outcome. It rarely would have. A user story written before anyone touches the code cannot contain the decision a reviewer forces in a pull request thread, or the edge case that reshapes the approach halfway through.
A quality specification reflects the finished work, not the half-baked idea it set out as.
sdd works inside the workflow you already have, a work item tracker, a pull request, review comments, rather than asking for a separate spec-writing ritual in place of it. What it keeps lives in a repository of its own, apart from the source: architecture, decision records, feature designs, and one record per work item. Keeping the specs apart means you can query and manage them without diluting your context window with your source code, and vice versa.
Set up the repository
Run the init command in a source repository, new or years old. It writes the configuration and renders the agent skills, and a doctor command checks the whole chain afterward, reporting pass, fail, or no signal rather than assuming success from a clean exit. On a codebase with years of undocumented decisions, a backfill skill reconstructs specs from commit and pull request history instead of starting from nothing.
sdd init · sdd doctorDraft the spec, not the final word
A work item in theory has a user story, requirements, and acceptance criteria, but traditionally that is not the case. sdd checks the work item for them and bounces it with a comment naming each gap. From a work item that passes, sdd drafts a spec grounded in related decisions already on record, a starting point for the implementation, not a blueprint it has to match exactly.
sdd-spec-advisorImplement and iterate
The draft becomes the pull request description, and it is rewritten as reviewers push back and the approach changes. What lands in the code is often not what the ticket said going in, and that is expected, not a sign the spec failed.
sdd-implement · sdd-spec-reviewFinalize from what happened
Once the pull request is approved, you can merge your code. sdd then writes the final spec into the separate repository, from the merged changes, the pull request description, and the review comments.
sdd-spec-advisorKeep everything synchronized
A scheduled skill, sdd-housekeeping, checks for drift between your specs, the code, the RAG index, and the work that actually shipped. It flags a stale or inconsistent spec for correction.
sdd-housekeepingVisualize the spec repository.
Every spec is a Markdown file in the spec repository, and the relationships between specs render into a wikilink block that sdd keeps in sync with the frontmatter. Point a graph tool such as Obsidian at the folder, and you are looking at the same structure sdd-housekeeping checks every day.
- The graph is drawn from the same edges retrieval walks, so what looks connected in Obsidian is what an agent reaches one hop out from a search hit.
- Using a tool like Obsidian brings you out of the source code and focuses your development attention on the structure and architecture.
Decisions that outlive the thread they were made in.
Every material change has a spec, or amends one, that says what it was for, what it must satisfy, and what it relates to, and the spec is retrievable at the moment the next change starts.
- A standing spec that governs a changed path gets amended, or the change records why it doesn't; nothing else is mandatory.
- The housekeeping skill identifies a broken reference and a spec left stale against the codebase.
- Specs carry explicit relationships to each other, so retrieval never pits a decision against the one that already replaced it.
- The format has one implementation, in the CLI, so the chunk boundaries the author sees are the ones the index embeds.
- kind work-item
- id SPEC-482
- refs src/billing/invoice.ts#refundOrder
- amends ARCH-billing-invariants
Open source, self-hosted.
sdd is open source, published on npm as @dependably/sdd, and installs into a repository with one command. A developer can run a personal RAG mirror locally, where company policy on local AI tooling allows for that, or an admin can stand up a team instance on shared infrastructure that every developer's agent queries over MCP instead.