Documentation

New here? Three steps.

Everything, by category

Read straight down the left rail if you are new — the order is the order a newcomer should meet these ideas. Every page has a reading time and says who it is written for.

Start here

What specd is, why it exists, and how to get it running in five minutes.

• 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. Everyone · 6 min
• Why spec-driven delivery The case for approving a specification instead of reviewing a diff — what it costs, what it buys, and where it does not pay off. Leadership · 8 min
• Quickstart Clone, run one command, and have specd running locally against a real Postgres in about five minutes. Engineering · 7 min
• Your first spec, end to end A guided walk through all six stations using the seeded fixture repository — what you click, what specd does, and what to look at while it does it. Everyone · 10 min
• Glossary Every term specd uses, defined once, in the order you will meet them. Everyone · 5 min

Core concepts

The five ideas everything else in specd follows from.

• The six stations Connect, Ground, Spec, the human gate, Build, Learn — what each one does, and why the line cannot be reconfigured. Everyone · 9 min
• The knowledge base What knowledge/ is, why it lives in your repository rather than in specd, and what keeps it from going stale. Everyone · 8 min
• Specs and citations What a spec contains, what a citation promises, and the four verdicts that make the promise checkable. Everyone · 9 min
• The human gate The approval step at station 04: what it records, where it is enforced, and why no agent — including specd's own — can open it. Everyone · 6 min
• The learning loop Why the loop closes on merge, what an as-built spec is, and how the twentieth spec ends up better grounded than the first. Everyone · 6 min

Guides

Task-shaped walkthroughs for the things you will actually do.

• Connect a repository The three ways in — a local path, a GitHub App installation, or a GitLab token — and what each one lets specd do. Engineering · 7 min
• Ground your repository What the onboarding scan reads, what it writes, and how to review the setup pull request properly — the highest-leverage review in the whole product. Everyone · 8 min
• Reviewing and approving a spec A reviewer's checklist: what to read first, which three failure modes to watch for, and what your approval actually commits you to. Everyone · 7 min
• Build and ship What the build station does with an approved spec, the three guarantees it enforces, and how to read the result. Engineering · 7 min
• Bring your own model Three ways to give specd a model — your Claude subscription, an API key, or neither — and what each one costs you in capability. Engineering · 7 min
• Agent integrations Serve the knowledge base to Claude Code, Cursor or Windsurf over MCP, and install the plugin that makes the working agreements bind. Engineering · 8 min

Integrations

GitHub, GitLab, Jira and your own machines.

• GitHub specd connects as a GitHub App with three permissions and hour-long tokens — how to register it, what it listens to, and how to test webhooks locally. Engineering · 7 min
• GitLab gitlab.com and self-managed, connected with an api-scoped access token — same write path, same fail-closed webhook rule. Engineering · 5 min
• Jira Import issues, backlink comments and mirror status — one-way, and unable to fail a specd action. Everyone · 6 min
• Self-hosted runners Pair a machine to run spec, onboard and build jobs with its own Claude Code and its own git credentials. Engineering · 8 min

Reference

The CLI, the MCP surface, configuration, and how the engine works.

• CLI reference Every specd command, the exit codes worth scripting against, the environment overrides, and the interactive shell. Engineering · 8 min
• MCP tools The seven tools and three resources specd mcp serve exposes, and what makes the surface read-only by construction. Engineering · 6 min
• Configuration Every environment variable specd reads, what it defaults to, and which ones fail closed. Engineering · 7 min
• Architecture What runs where, why Postgres is the only runtime dependency, and how an index run stays atomic. Engineering · 9 min
• The retrieval engine Three bounded stages — rank fusion, a graph hop, then real source code — and the honesty rules that stop it overstating what it found. Engineering · 8 min
• Security and invariants The nine properties specd enforces in code rather than by convention, and where each one is enforced. Engineering · 7 min
• Evals Quality is graded against independent oracles rather than asserted — what is measured, on what corpus, and what the numbers do not prove. Engineering · 5 min

For teams

Adoption, cost, and the answers to the questions people actually ask.

• For engineering leaders What changes for a team that adopts specd, who owns what, how to roll it out, and what to measure. Leadership · 9 min
• Costs and metering What a run costs, how spend is capped, and why money is stored as integer cents. Leadership · 5 min
• FAQ The questions people ask in the first hour, answered without hedging. Everyone · 7 min
• Troubleshooting Symptom, cause, fix — for the failures that actually happen. Engineering · 5 min