🛡️ DocGuard

English · Português (BR) · Español

The enforcement layer for Spec-Driven Development. Validate. Score. Enforce. Ship documentation that AI agents can actually use.

✨ See what DocGuard catches in 30 seconds — no install, no setup:

Terminal

Copy

npx docguard-cli demo

Runs against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.

Table of Contents

• What is DocGuard?
• Why DocGuard?
• Quick Start
• Spec Kit Integration
• Usage
• Validators
• Templates
• AI Agent Support
• Slash Commands
• Examples
• Testing
• Enterprise Adoption
• CI/CD Integration
• What's New
• File Structure
• Configuration
• Research Credits

What is DocGuard?

DocGuard enforces Canonical-Driven Development (CDD) — a methodology where documentation is the source of truth, not an afterthought. AI writes the docs, DocGuard validates them.

DocGuard is an official GitHub Spec Kit community extension. It validates the artifacts that Spec Kit creates, ensuring your specs stay high-quality throughout the development lifecycle.

📖 Philosophy · 📋 CDD Standard · ⚖️ Comparisons · 🔬 Validation · 🗺️ Roadmap

Architecture

graph TD
    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (20)"]
    Commands --> guard["guard"]
    Commands --> generate["generate"]
    Commands --> score["score"]
    Commands --> diagnose["diagnose"]
    Commands --> setup["setup wizard"]
    Commands --> other["diff · init · fix · trace · impact · sync<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]

    guard --> Validators["Validators (27)"]
    generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
    score --> Scoring["Weighted Scoring<br/>8 categories"]
    diagnose --> Validators
    diagnose --> AIPrompts["AI-Ready<br/>Fix Prompts"]

    Validators --> Output["Output"]
    Scanners --> Output
    Scoring --> Output
    Output --> Terminal["Terminal"]
    Output --> JSON["JSON"]
    Output --> Badge["Badge"]

    style CLI fill:#2d5016,color:#fff
    style Validators fill:#1a3a5c,color:#fff
    style Scanners fill:#1a3a5c,color:#fff
    style Output fill:#5c3a1a,color:#fff

Distribution: Node.js core (npm) · Python wrapper (PyPI) · GitHub Action (action.yml) · Spec Kit Extension (ZIP)

Why DocGuard?

DocGuard checks declared documentation facts against repository evidence and gives agents structured repair tasks. Deterministic checks cover supported facts, references, and generated sections. Human-authored requirements and architectural decisions retain their authority when implementation diverges.

A guard result describes the checks performed. The CDD grade measures structural maturity. Factual accuracy stays explicitly unverified until the relevant claims have supporting evidence. Coverage and unresolved claims remain visible, so teams can choose an appropriate enforcement policy.

Research motivates evaluation of this approach. A 2026 study found that repository context files did not generally improve task success and increased inference cost in its evaluated settings. It also found agents generally followed the instructions. These results support testing concise, relevant context and measuring actual task outcomes; they do not establish DocGuard's effectiveness. Evaluating AGENTS.md, revised June 2026.

The development plan prioritizes accurate detection, reproducible evidence, and contributor-supplied regression cases. See the trust roadmap for implementation status, proposed experiments, and acceptance criteria.

⚡ Quick Start

Package naming: this repo is raccioly/docguard; the published package is docguard-cli on both npm and PyPI; the installed command is docguard. Same project — the -cli suffix is just the registry name. The package runs no install scripts, so npm i -g docguard-cli --ignore-scripts is equivalent.

Node.js (npm)

# No install needed — run directly
npx docguard-cli diagnose

# Or install globally
npm i -g docguard-cli
docguard diagnose

Python (PyPI)

pip install docguard-cli
docguard diagnose

Note: The Python package is a thin wrapper that delegates to npx. Node.js 18+ is required on the system.

Docker (MCP server)

The MCP server ships as a container image on GHCR — no Node.js install required. Public image, so no authentication is needed to pull it:

# Run the MCP server against the current directory
docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:latest

The entrypoint is the stdio MCP transport: stdout is the JSON-RPC channel, so don't pipe anything else into it. Mount the project you want inspected at /workspace and pass {"projectDir": "/workspace"} in tool calls (or rely on the default working directory).

Pin a version rather than tracking latest in CI:

docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:0.34.9

The server is read-only — it never writes to the mounted project.

More ways to integrate

• pre-commit — changed-only guard on every commit:
  yaml

  Copy

  repos:
    - repo: https://github.com/raccioly/docguard
      rev: v0.29.0
      hooks: [{ id: docguard-guard }]   # docguard-guard-full for pre-push
  

• MCP (Claude, Cursor, any MCP client) — claude mcp add docguard -- npx -y docguard-cli mcp; 5 read-only tools (guard, score, explain, verify-claims, diagnose). Registry manifest ships in-repo (server.json, Smithery-ready).
• GitLab CI — component staged at templates/ci/gitlab-component.yml (guard/score/ci job with a SARIF artifact).
• Homebrew — brew install raccioly/tap/docguard (formula in packaging/homebrew/).

Core Workflow

# 1. Initialize docs for your project
npx docguard-cli init

# 2. Or reverse-engineer docs from existing code
npx docguard-cli generate

# 3. AI diagnoses issues and generates fix prompts
npx docguard-cli diagnose

# 4. Validate — use as CI gate
npx docguard-cli guard

# 5. Check maturity score
npx docguard-cli score

The AI Loop

diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
   ↑                                                       ↓
   └───────────────── issues found? ←──────────────────────┘

diagnose is the primary command. It runs all validators, maps every failure to an AI-actionable fix prompt, and outputs a remediation plan. Your AI agent runs it, fixes the docs, and runs guard to verify.

Mechanical vs. agent fixes

DocGuard splits drift into two kinds and is explicit about which is which:

docguard fix --write only touches docs marked <!-- docguard:generated true --> (override with --force), is idempotent, and prints exactly what changed. It never rewrites prose — that stays with the agent.

Continuous documentation workflow

guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)