Spec Guard

Spec-first. Behavior-tested. Agent-safe.

Spec Guard is a methodology, workflow runner, and MCP server for agent-driven software development. The model is simple: humans write specs, agents write all code. Six mechanical gates enforce the boundary between human intent and agent execution.

Specs guide implementation, but tests validate running behavior and durable contracts — not prose.

The human's interface is a conversation. Describe what you want, answer a few questions, approve the spec. The agent handles gates, contracts, tests, and code. There are no files to fill out, no commands to learn, no dashboard to check — just a description of what you need and a chat window to deliver it in.

Three layers, one system

Each layer enforces the same 6 gates. Pick the one that fits your agent's capabilities — or use all three.

The 6 Gates

DISCOVER → [Gate 1] → CLASSIFY & CONTRACT → [Gate 2] → IMPLEMENTATION PLANNING → [Gate 3] → TEST FIRST → [Gate 4] → IMPLEMENT → [Gate 5] → REVIEW → [Gate 6]

Quick start

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

# Initialize project
npx spec-guard init

# Author a spec (guided wizard)
npx spec-guard draft my-feature

# Orchestrated workflow (recommended)
npx spec-guard run my-feature

# Just validate
npx spec-guard check my-feature

# See all specs
npx spec-guard status

# Browse all .md artifacts locally (no GitHub push needed)
npx spec-guard serve

See the CLI Reference for all commands and flags.

Local markdown viewer

spec-guard serve starts a local HTTP server that renders all .md files in your repo as styled HTML. Navigate spec artifacts, contracts, and reviews in the browser with live reload — no GitHub push required.

npx spec-guard serve            # opens http://localhost:7777
npx spec-guard serve --port 8080

The root page is your README.md (or .spec-guard/README.md as fallback). A sidebar lists every .md file in the repo. Edits to any .md file reload the browser automatically.

Wiring an agent to Spec Guard

Agents don't inherently know the Spec Guard workflow. Without it, they'll implement normally — no gates, no classification, no halt conditions. There are three ways to give an agent the operating contract:

MCP server (preferred) — Connect the MCP server and the agent receives structured guidance at each step via tool calls. No upfront loading required. spec_guard_workflow_next_step always tells the agent what to do next. Works with any MCP-compatible agent (Claude Code, Cursor, Copilot, etc.).

Project file context — spec-guard init puts AGENTS.md in the project root. Agents that automatically ingest project-level instruction files (Claude Code's CLAUDE.md pattern, Cursor rules, etc.) will pick it up without any manual step. Point the agent at the project and it reads the contract on its own.

Manual paste — For agents without MCP support or automatic file ingestion, paste the contents of AGENTS.md at the start of a session. The agent then operates under the full Spec Guard contract for that session.

WORKFLOW.md has the full phase-by-phase process flow. AGENTS.md is the compact operating contract an agent needs to execute it.

MCP Server

Exposes all Spec Guard operations as structured tools for MCP-compatible agents.

{
  "mcpServers": {
    "spec-guard": {
      "command": "node",
      "args": ["/path/to/spec-guard/mcp/server.js"]
    }
  }
}

Available tools

spec_guard_workflow_next_step is the key tool for agents: call it after each action and it returns a structured next_action + instruction so the agent always knows what step comes next without reading docs.

See the MCP Setup guide for configuration and the MCP Tool Reference for full tool inputs, outputs, and examples.

What init creates

.spec-guard/
  specs/
  contracts/
  blockers/
  scope-discoveries/
  reviews/
  deviations/
  discoveries/
  runs/
AGENTS.md
WORKFLOW.md
.github/
  workflows/
    spec-guard.yml

What agents must never do

• Implement before Gates 1, 2, 3, and 4 pass — the spec must be valid, contracts must be present, required implementation planning must be confirmed, and a failing test must exist before any implementation begins

• Skip work classification

• Create documentation by default

• Test whether documentation files (specs, contracts, reviews, READMEs, help files, changelogs) exist or contain expected content, unless the document is explicitly the deliverable of an operational/document deliverable classification

• Invent UI — do not implement UI work until both a mockup/design direction and a component library reference are in the spec, or the human has explicitly confirmed each is not needed

• Assume a component library — if none is referenced, ask the human before proceeding

• Test private/undocumented internals instead of contract surfaces

• Silently absorb out-of-scope work

• Add unrequested features, optional enhancements, or opportunistic refactors

• Upgrade dependencies or change architecture unless the spec requires it

• Redesign UI beyond provided direction

• Implement nearby TODOs unless the spec requires them

• Propose unsolicited feature roadmaps after completing a task

• Treat "what's next?" as permission to invent features

• Perform discovery unless the human explicitly asks

• Implement discovery findings without separate authorization

• Skip Gate 4 (failure-first) without recording a concrete reason

• Close Gate 6 without running spec-guard analyze

Examples

End-to-end walkthroughs showing Spec Guard in use with natural-language requests.

Documentation

Development

npm test                        # 231 tests across check, run, MCP, CLI, discover, analyze, suggest, initiative, and implementation planning
npm run check:example           # gate 1 smoke check
npm run run:example             # gate 1+2 non-interactive check

License

MIT.

Spec Guard

This project uses Spec Guard

Spec Guard Artifacts