DOCS · FOR TEAMS

For engineering leaders

What changes for a team that adopts specd, who owns what, how to roll it out, and what to measure.

On this page

specd is a process change with a tool attached, not the other way around. The tool is a weekend; the process change is the thing to plan.

What actually changes

Before	After
A ticket goes to an engineer, who assembles context by hand.	A ticket becomes a drafted spec grounded in the team's own documentation.
Review happens on a diff, after the work is done.	Review happens on a page, before the work starts. The diff review still happens, and is shorter.
Context lives in people's heads and in Slack.	Context lives in `knowledge/`, in the repository, updated in the same pull request as the code.
"The AI wrote it" is the answer to who decided this.	A named person approved a specific version, with a timestamp.

Spec approver: The person who reads and stamps. Usually a tech lead or a senior engineer on the area. Name one per project. An unowned approval queue is a stalled queue, and a stalled queue is how a team learns to route around the gate.
Knowledge owner: The person who cares whether knowledge/ is true. Not a full-time job — mostly it is answering UNVERIFIED markers and keeping README.md a real map. But it is somebody's job or it is nobody's.
Everyone else: Reads the spec if it touches their area, reviews the pull request as normal, and updates the docs in the same change. That last habit is the one that makes the whole thing compound.

Week 0 — one repository, one approver
Pick a repository somebody actively owns, not the scariest one and not a toy. Ground it, and spend real time reviewing the setup pull request: everything downstream cites it.
Week 1 — five specs, no build station
Draft and approve specs for work you were going to do anyway, and implement by hand. You are testing whether the specs are worth reading, without also testing the agent.
Week 2 — turn on the build station for the easy half
Well-bounded tasks first. Watch the first-pass acceptance rate and the size of the review comments.
Week 3 — decide what specd is a lane for
Write down which changes go through it and which do not. A typo fix does not need a spec, and pretending otherwise is how a good process gets a bad reputation.
Ongoing — watch the UNVERIFIED count
It should fall as the knowledge base fills in. If it is flat, the markers are being ignored rather than answered, and the docs are drifting.

Signal	Healthy	Telling you something is wrong
Ticket → approved spec, median	Days, trending down	Weeks — your docs cannot answer the questions yet
First-pass PR acceptance	Rising	Flat — specs are being stamped, not read
Citations per spec	Rising with coverage	Near zero — retrieval is not finding your documentation
`UNVERIFIED` per spec	Falling	Rising — the knowledge base is drifting from the code
Time from approval to merged PR	Stable	Growing — tasks are sized larger than one pull request

Where does our code go?: Nowhere specd holds. It records which repository, reads it when it needs to, and keeps a derived index. In local mode nothing leaves the machine at all.
What can the agent do to our repository?: Push a branch and open a pull request. It never pushes to a default branch, never merges, and has no shell. The GitHub App asks for three permissions and its tokens expire within the hour.
Who approved this change?: A named human, against a specific spec version, with a timestamp — enforced by a database constraint, append-only, and unavailable to any agent or API token.
What happens if we stop using it?: The knowledge base is markdown in your repository and stays there. You lose an index, and an index rebuilds.
Whose model is it?: Yours. An API key you supply, or the Claude subscription already signed in on your own hardware — specd never holds a subscription credential.

The enforcement details behind each of these are in Security and invariants.