FAQ

About the product

Is specd a coding agent?

No. It is the process around one. It grounds a knowledge base, drafts specs, holds the gate, and dispatches an agent to build what was approved. You can also skip its build station entirely and hand the approved spec to whatever agent you already use.

Do I have to use Claude?

Today, yes — the model allowlist is Claude Opus 5, Sonnet 5 and Haiku 4.5, and the subscription mode drives the Claude Code CLI. The embedding side is provider-agnostic: any OpenAI-compatible /v1/embeddings endpoint works, including a local one.

Does my code leave my machine?

In local mode, no. Otherwise specd reads your repository through the provider's API with short-lived, repository-scoped credentials, and sends the retrieved passages to the model you configured. It never stores a copy of your repository.

Can the agent merge?

No. It opens a pull request. Merging is yours, and merging is also the event that closes the loop.

Can I approve a spec from the CLI?

No, and that is deliberate. The CLI fetches, registers and reports; the server refuses authoring and approving for CLI tokens regardless of what the binary asks. Approval is a signed-in human in the app.

What if the knowledge base is wrong?

Then the specs cite something wrong, and you will see it — that is what following a citation is for. Fix the document; the next index run picks it up. This is why the setup pull request is worth a real review.

What if we do not have any documentation?

Grounding writes the first version by reading your repository, and marks what it could not establish. Your first specs will carry more UNVERIFIED claims than your twentieth. That is the system working, not failing.

About running it

Is there a hosted version?

Not yet. specd is pre-1.0 and local-first: you run it on your own machine or your own infrastructure. knowledge/runbooks/deploy.md is an honest inventory of what a first deployment would need rather than a description of one that exists.

What do I actually have to run?

Postgres, and specd. Postgres is the only runtime dependency — index runs are queued rows woken by LISTEN/NOTIFY, so there is no broker to operate.

Does it work without an API key?

Yes, minus the drafting. Indexing, retrieval, the graph, health, the CLI, MCP and the gate all work. Spec generation fails with a clear error rather than inventing content.

Why is retrieval only okay out of the box?

The default embedder is a deterministic local hash — offline, no extra key, and lexical. The full-text arm carries relevance until you point the index at a real embedding model, which can be a local one.

Can two people use the same project?

Yes. Approval is per-person and recorded by name, which is the whole point of having more than one.

What is not built yet

Stated plainly, because the wizard must not lie and neither should the documentation:

• A deployment story. specd runs as a development platform on your machine. Nothing deploys it as a service.
• Jira inbound sync. specd writes to Jira but does not listen — moving an issue in Jira does not move the spec.
• gitlab.com OAuth. Token paste only.
• Stripe billing. Spend is metered and capped, not billed.
• Runner concurrency. One job at a time per runner.
• The retrieval ceiling. With the default embedder, both retrieval arms measure similar signals. Everything around it is tuned; the ceiling needs a key or a local model.

About the project

What licence?

MIT.

Does specd use specd?

Yes. This repository's own knowledge/ is a live instance of the product's knowledge base — ADRs, runbooks, as-built specs, and the research that shaped the engine. Start at knowledge/README.md.

How do I contribute?

CONTRIBUTING.md in the repository. The verify gate is pnpm typecheck && pnpm test, and CI runs exactly those two commands against a real pgvector service.