DOCS · START HERE
What is specd?
specd is a delivery platform that turns a ticket into a written, cited, human-approved specification — and only then lets an AI agent write code.
On this page
AI coding agents are fast and confident, and they will happily build the wrong thing. specd puts one document between the request and the code: a spec that a named person on your team read and approved.
The problem, in one paragraph
A coding agent given a two-sentence ticket has to invent everything the ticket left out — your architecture, your naming, which service owns what, what "done" means. It invents plausibly, which is the dangerous part: the pull request looks right. The gap between "looks right" and "is right" is discovered in review, in QA, or in production, and by then the cost of the misunderstanding has multiplied.
The usual fixes make it worse. Longer prompts do not survive the next session. A wiki nobody updates is a wiki the agent cites while it is wrong. And a human reviewing 600 lines of generated code is reviewing the output of a decision they never got to see.
What specd does instead
specd moves the review earlier — to the point where a change is still a paragraph and not a diff. It does that with four moving parts.
It reads your repositories and writes a knowledge base
Manifests, CI workflows, compose files,
.env.example, schemas, the workspace layout. What it finds becomes plain markdown underknowledge/in your repository, delivered as a pull request you review. What it could not establish is markedUNVERIFIEDrather than guessed at.It drafts every ticket into a spec, with citations
Requirements you can test, a design section where every claim links to the passage in your own docs that supports it, and a task list sized so each task is one pull request.
A named human approves it
This is the gate, and it is the product. Nothing downstream runs on an unapproved spec — not the agent, not the CLI, not a script that asks nicely. The approval is recorded against that exact version, permanently.
The agent builds only what was approved, and the result files itself back
One commit per task, on the spec's own branch, opened as a pull request you merge. Merging files the as-built spec into
knowledge/specs/— so the next spec retrieves it, and the fifth spec is better grounded than the first.
The line
Every project gets the same six stations, in the same order. This is not a workflow builder — there is nothing to assemble, and nothing to mis-wire.
Connect → Ground → Spec → [HUMAN] → Build → Learn
01 02 03 04 05 06
└──→ feeds 02Stations cannot be added, skipped or removed. Only station 01 takes configuration — which repository, which model, which tracker. The gate at 04 is structural: no agent may approve its own input, and the server refuses to serve an unapproved spec no matter who asks. Read them one by one in The six stations.
What makes the specs worth trusting
A spec is only useful if a reviewer can check it faster than they could write it. Two properties do that work.
- Every design claim is cited or flagged
- A claim either points at a passage in your knowledge base, or it says
UNVERIFIED. There is no third option where the agent asserts something and nobody can tell where it came from. - Citations are checked, with four possible answers
supported,unsupported(checked and wrong),unknown(the corpus could not answer) andstale(the passage is real, but the code it describes has changed since). "I found no evidence" and "no evidence exists" are different answers, and only one of them is safe to write into a spec.
The machinery behind that is described in Specs and citations and The retrieval engine.
What specd is not
- Not an autonomous agent. It cannot merge, cannot push to a default branch, and cannot approve anything. Every change arrives as a pull request with your name on the approval that authorised it.
- Not a place your code lives. Git stays the source of truth.
knowledge/is plain markdown in your repository; specd holds a derived index it can rebuild. Delete the project and you lose nothing you would miss. - Not a model. You bring one — an API key, or the Claude subscription already signed in on your machine. specd never holds a subscription credential.
- Not a ticket tracker. Jira stays Jira. specd links to the ticket and mirrors status back.
Who it is for
| If you are… | specd gives you… |
|---|---|
| An engineer using a coding agent | An agent that has already read your architecture, cites the doc behind each decision, and flags what it could not ground instead of guessing. |
| A tech lead or reviewer | A one-page spec to review instead of a 600-line diff — and the ability to catch a wrong assumption before it becomes code. |
| An engineering manager or director | A named, timestamped approval on every AI-authored change, and a knowledge base that improves as a by-product of shipping. See For engineering leaders. |
| Someone in a regulated or audited environment | An append-only approval record tied to a specific spec version, enforced by a database constraint rather than by policy. |