Overview

👤 Human

Start here. Read Getting Started for a walkthrough, then explore Architecture, Commands, and the Guides.

These docs are written in narrative style with rationale, examples, and context.

🤖 Agent

You’re told to “use Spec Engine.” Go straight to the Agent Reference — it has the exact CLI contracts, exit codes, JSON shapes, and the route → tag → check loop in as few tokens as possible. That page is optimized for agents, not humans.

Spec Engine is a cross-repo requirements engine. It manages durable domain requirements that survive past production, addressed by permanent ID, bound to code, and checkable in CI.

It ships as one npm package — no clone, no build step, no service. With Bun installed:

$ bunx @spec-engine/spec-engine --help    # run without installing
$ bun add -g @spec-engine/spec-engine     # or put the `spec` bin on your PATH

That package carries the CLI, the local coverage webapp (spec serve), and these docs offline (spec docs). See Getting Started to run your first check.

A spec is the standing specification of one domain. Requirements carry permanent IDs (KEY-NNN); code points back at them with a // @spec KEY-NNN tag. From that one convention you get three things:

1. An agent can be routed to exactly the requirements a task touches
2. Integrity can be checked mechanically
3. A requirement’s history survives every refactor because IDs are permanent and changes supersede rather than overwrite

The idea

Everything in Spec Engine follows from eight statements:

1. A requirement represents a single behavior.
2. A requirement is never deleted. When behavior changes, it is superseded or deprecated.
3. The written requirements are the single source of truth for what the software is supposed to do.
4. A requirement can be linked to the code that implements it and to the tests that prove it.
5. Reports are computed from the requirements and their links.
6. You can check whether the requirements, code, and tests agree, and exactly where they don’t.
7. Tickets are not requirements. A ticket is temporary work; requirements outlive it.
8. Requirements are written in a fixed shape (when X happens, the system shall do Y).

Why it exists

Most spec tools are keyed to the change you are about to make: their specs describe one feature and end at “implemented.” Spec Engine is keyed to the domain, which outlives every feature. Its first-class operation is what happens after production: superseding established truth, not generating new work.

When AI agents produce more code in an afternoon than a person can carefully read in a week, Spec Engine answers by making the mission-critical path defend itself: spec check runs on every change and reports whether a load-bearing requirement was broken, orphaned, or left unverified.

Provenance — the external join

A requirement can also carry an optional Issues: field linking it back to the tracker where the why lives, by role (created, supersedes-via, amends-via). spec provenance widens the coverage matrix into a provenance matrix: per requirement, the issue that birthed it, the issues that revised or retired it, and the tests backing it. The engine treats issue IDs as opaque strings and never makes a network call; an optional tracker adapter resolves them to titles and URLs. See SPEC.json Format and Commands.

What ships today, and what is planned

What ships today is the local platform: the CLI, the SQLite index, and the local webapp — free, MIT-licensed, running entirely on your machine. A hosted service and an on-premises version are planned but do not exist yet; nothing on this site describes a product you can buy today.

The working loop

• Author — write a requirement before code. Agent drafts, human approves.
• Route — spec resolve / spec query to load the requirements a task touches.
• Tag — add @spec KEY-NNN in code as you satisfy a requirement.
• Check — spec check --ci as a gate.