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

| Layer | What it is | Who uses it | |---|---|---| | WORKFLOW.md + AGENTS.md | Process flow document + compact agent instructions | Agents that load project files as context, or humans reviewing the process | | spec-guard run | Interactive CLI that walks a spec through all 6 gates | Agents executing CLI commands | | MCP server | Structured tool calls for all Spec Guard operations | MCP-compatible agents (Claude Code, Cursor, etc.) |

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]

| Gate | Check | How it's confirmed | |---|---|---| | 1 | Spec valid (required headings, content, classification) | spec-guard check — must exit 0 | | 2 | Contracts present (API/UI inputs exist and are referenced) | spec-guard check --warnings | | 3 | Implementation planning confirmed (required stack/layer decisions are recorded) | Agent suggests a context-appropriate stack/layer, human accepts or overrides it, then agent calls spec_guard_confirm_gate | | 4 | Failure-first confirmed (test runs and fails for expected reason) | Agent runs tests, records failure, calls spec_guard_confirm_gate with evidence | | 5 | Tests pass (no scope silently absorbed) | Agent runs tests until passing, calls spec_guard_confirm_gate | | 6 | Review complete + cross-artifact analysis clean | spec-guard review then spec-guard analyze |

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

| Tool | What it does | |---|---| | spec_guard_analyze | Cross-artifact consistency check (spec ↔ contract ↔ review) | | spec_guard_check | Validate a spec; returns diagnostics | | spec_guard_classify | Get classification + test guidance | | spec_guard_confirm_gate | Record gate 3/4/5/6 confirmation, with evidence required for Gate 4 | | spec_guard_create_artifact | Create any artifact from a template | | spec_guard_draft_spec | Turn interview answers into a valid spec (passes Gate 1) | | spec_guard_gate_status | Status of all 6 gates for a spec | | spec_guard_initiative_questions | Get question list for decomposing a broad app into feature slices | | spec_guard_interview_questions | Get structured question list for AI-assisted spec authoring | | spec_guard_save_initiative | Save initiative decomposition artifact; returns slice names for drafting | | spec_guard_status | Overview of all specs | | spec_guard_suggest | Check + return each diagnostic with a concrete fix instruction | | spec_guard_test_guidance | Get test type and Gate 2 checklist for a classification | | spec_guard_validate_directory | Check all specs in a directory | | spec_guard_workflow_next_step | Given gates passed → what to do next |

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.

| Example | What it covers | |---|---| | Todo App | Building a new app with initiative decomposition, then adding a single feature with the standard spec flow |

Documentation

| Doc | What it covers | |---|---| | CLI Reference | All commands, flags, exit codes, diagnostic format | | Glossary | Term definitions | | MCP Setup | MCP server configuration for Claude Code, Cursor, and Windsurf | | MCP Tool Reference | All MCP tools — inputs, outputs, and examples | | Philosophy | Design philosophy, innovations, and problems Spec Guard solves | | Quality Gates | Gate-by-gate breakdown and pass conditions | | Quickstart | Minimum workflow, live validation, CI setup | | Validation Rules | Every rule ID with severity and description | | Work Classification | How to choose the right classification |

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