spec-guard

spec-guard

Hold your code to what your Markdown says about it.

Specs, ADRs, READMEs, agent instructions: the claims they make about your codebase become assertions that run in CI, in milliseconds, with no runtime dependencies.

The retired payment gateway is gone from the service layer.

If someone reintroduces LegacyPaymentGateway, CI fails and points at the line of the ADR that promised it was gone.

The words the spec-* tools share are defined in concepts, and the tutorial runs spec-guard beside its siblings through one round of work on a small repository.

---

Why this exists

Architecture Decision Records, RFCs and technical briefs are full of hard claims about a repository:

• *"LegacyPaymentGateway no longer exists anywhere in the service layer."*
• *"There is exactly one UserSessionManager."*
• *"No secret is ever read from process.env outside src/config."*

Every one of those claims is true on the day it is written and unverified from the day after. Prose does not fail a build. Six months later the document is still confidently asserting something the code stopped doing in March.

That has always been an annoyance. It became a defect multiplier the moment coding agents started reading these documents as ground truth. An agent that reads *"module X does not exist yet"* will happily build a second X. A reviewer who trusts *"this symbol occurs zero times"* skips the grep. Stale documentation is now executable in the worst sense: it executes inside someone's head, or inside a model's context window, and produces work that has to be thrown away.

spec-guard makes the claims executable in the good sense. It reads directives written as ordinary HTML comments - invisible in every Markdown renderer - and checks them against the real tree with ripgrep. A stale claim becomes a failing build with a line number, not a landmine.

Quickstart

npm install --save-dev @spec-family/spec-guard

npx --no-install @spec-family/spec-guard "docs/**/*.md"

npx is given the package's full name, here and in every command below: Names says why the command's name alone is not written.

Add a directive to any Markdown file, here docs/adr/0007-sessions.md, directly under the sentence it makes executable:

## Decision

Session state has exactly one owner.

Run it:

npx --no-install @spec-family/spec-guard "docs/**/*.md" --verbose

spec-guard 1 spec · 1 assertion · javascript

✔ docs/adr/0007-sessions.md:5 @assert-count "UserSessionManager" (1 match) in src

1 passed · 11ms ✔ every spec assertion holds

And when it drifts:

spec-guard 1 spec · 1 assertion · javascript

✖ docs/adr/0007-sessions.md:5 @assert-count "UserSessionManager" must appear exactly 1 time in src expected exactly 1 match, found 3 src/auth/UserSessionManager.ts:12:14 export class UserSessionManager { src/legacy/sessions.ts:3:10 import { UserSessionManager } from '../auth'; src/workers/refresh.ts:8:30 const manager = new auth.UserSessionManager(store);

0 passed · 1 failed · 12ms

Exit code 1. The ADR is now a test. A Windows console other than Windows Terminal or VS Code's writes +, x, ! and o for the marks (ASCII and the marks).

Names

The package is @spec-family/spec-guard, and the command it installs is spec-guard. The name without the scope is not this project: on npm, spec-guard belonged to nobody on 2026-10-07, and whoever registers it decides what it runs.

npx fetches and runs the package of whatever name it is given when the project has none installed - a fresh clone, a worktree before npm ci, a CI job without the install step - and without a terminal it does not ask first. So give npx the full name:

• npx --no-install @spec-family/spec-guard in a project that installed it: it runs that install, the version the lockfile pins, and where there is none it stops with an error that names this package.
• npx @spec-family/spec-guard, without --no-install, where nothing is installed: it fetches this package and runs it.

Never npx spec-guard, and not npx --no-install spec-guard either: --no-install stops a download, and npm still runs a copy of the bare name's package that an earlier fetch left in its cache. The family's adopting guide has what was measured, under npm 10, 11 and 12.

The command alone, spec-guard, is what a package.json script holds - npm fetches nothing for a script - and what a global install puts on the path:

npm install -g @spec-family/spec-guard   # then: spec-guard "docs/**/*.md"

Directives

Every directive is an HTML comment, written directly under the sentence it makes executable. It is read only where a renderer shows Markdown: in code and in front matter it is text, so documentation that shows the syntax, like this README, never executes it. There are eight kinds, and each makes one claim about the tree:

The import rules read the dependency rather than the text, in JavaScript and TypeScript, Python, Go, Rust and C#, and say what they could not resolve rather than counting it clean. A match inside a comment does not count unless a rule asks for it, a rule that inspects no file fails, and a baseline adopts a rule the code already breaks without hiding what is added (attributes). A draft, a proposal or a superseded ADR is read and reported, and its directives are not executed (document status).

Commands

spec-guard [patterns...] [options]     # execute the directives

spec-guard --watch [patterns...] # execute them again whenever the tree changes spec-guard query [options] # the rules in force for files or directories spec-guard mcp [options] # serve the rules over MCP on stdio spec-guard prove [patterns...] # show each rule a violation of itself, in memory spec-guard cites [paths...] # check each spec a code comment cites exists and is in force spec-guard claims [options] # hold each claim a specification labels to the evidence its label asks for spec-guard impact # the files that depend on each path, and the rules in play there

• `query` and `mcp` answer which rules govern a path before anyone writes to it, from the specs alone, and serve that answer to an agent over the Model Context Protocol. The server is listed in the official MCP Registry as io.github.spec-family/spec-guard.
• `prove` shows each rule a violation of itself, in memory, and fails a rule that still passes.
• `cites` holds each decision a code comment cites to a document that exists and is in force.
• `claims` holds each claim a specification labels to the evidence its label asks for.
• `impact` lists the files that depend on a path, however far away, and the rules in play there.
• `--watch` re-executes only the rules a change can affect.

Exit code 0 is every assertion held, 1 is an assertion that failed, and 2 is a run that could not be trusted: bad usage, a malformed configuration, no spec matched. CLI has every option and every exit code.

Configuration

The options that are a project's policy can live in package.json, under "specGuard", so CI, a pre-commit hook and the MCP server an agent starts all hold the same rules the same way:

{

"specGuard": { "specs": ["docs/**/*.md", "README.md"], "strict": true } }

A root with no package.json keeps the same options, at the top level, in .spec-guard.json. The command line wins over either, and every report says what it took from the file. Configuration has every key.

CI integration

# .github/workflows/specs.yml

name: Specs on: push: branches: [main] pull_request:

jobs: spec-guard: runs-on: ubuntu-latest permissions: contents: read steps:

• uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false
• uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: '22'
• run: npm ci
• run: npx --no-install @spec-family/spec-guard "docs/**/*.md" "README.md" --verbose

That job needs nothing else installed: without ripgrep the built-in scanner runs, and gives the same answer. CI integration has why the actions and spec-guard are pinned, installing ripgrep, a pre-commit hook, and --format sarif, github and gitlab, which place each finding on its line of a pull request or a merge request.

Reference

The full reference is in docs/reference/, a topic to a page, which the package ships beside this README:

• The rules. Directives, how one is written and read, and the text rules; import rules, layers and cycles; structure; attributes, with exclude, comments, allow-empty and baseline; regular expressions, the one dialect both engines read; what gets searched; and document status, drafts and superseded ADRs.
• The commands. CLI, with every option and exit code; configuration; watch mode; query and the MCP server; prove; cites; claims; and impact.
• Around them. CI integration, with the formats that annotate a pull request; the programmatic API; how it works, wit