Why the system is the way it is lives in people's heads, chat threads, and closed tickets. A new engineer, or an agent asked to change the code, works from the code alone and re-decides what was already decided.
A design decision is made in a review thread or a call, and the code that follows carries the outcome but not the reason. Months later the reason is the thing that matters, and it is in a closed ticket nobody reopens.
Writing the design into the code repository does not fix this. Source churns on every commit, so a document beside it is either stale or re-read on every change, and an index rebuilt on every commit is one nobody trusts.
Agents make the gap visible. Asked what the code does and what it should do at the same time, an assistant working from the source alone answers the first question and guesses at the second.
sdd keeps design intent in a dedicated spec repository, separate from the source on purpose: architecture, decision records, feature designs, and a record for each work item that makes a decision. The corpus is validated in CI, indexed by vectors and by the relationships between specs, and retrieved by the people and agents doing the work.
Run the init command in a source repository. It writes the project and developer configuration, renders the agent skills, and adds a marker-delimited block to the assistant's instructions. A doctor command then proves the chain works: endpoint, auth, MCP registration.
sdd init · sdd doctorA work item that is not spec-ready is bounced rather than guessed at: it needs a type, one testable objective, acceptance criteria as a checklist, and a user statement. The spec advisor retrieves prior decisions from the index and drafts the spec against them before implementation starts.
spec.mdThe spec repository's CI validates the format on every change. A CI job in the source repository checks that the specs still describe real code, and the review skill flags a change that touches a standing spec without amending it, while it is still a comment.
sdd validate --refsThe index ingests the spec repository when its revision moves, storing chunks as vectors and spec edges as a graph, and serves both to skills and developers through an MCP endpoint with authentication. A housekeeping skill, run daily, compares the index, the specs, and the closed issues.
vectors · graph · MCPEvery 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.
sdd is open source, published on npm as @dependably/sdd, and adopted in a repository with one command. The index runs on your own infrastructure from a Docker Compose bundle in the same repository: a vector store, a graph store, the ingest job, and the query API exposed as an MCP server, with local embeddings as an option.