DocGuard

🛡️ 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.

-green)

---

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

`bash

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.

📚 [Documentation](https://raccioly.github.io/docguard/): Installation · Existing projects · Spec Kit · CI · Languages and frameworks · Coding agents · Finding codes · Troubleshooting

---

Table of Contents

• What is DocGuard?
• Why DocGuard?
• Quick Start
• Spec Kit Integration
• Usage
• Validators
• Reading a finding
• 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.

🧭 [How it works (10-page brief)](https://raccioly.github.io/docguard/docguard-explained.html) (PDF) · 📖 [Philosophy](PHILOSOPHY.md) · 📋 [CDD Standard](STANDARD.md) · ⚖️ [Comparisons](https://github.com/raccioly/docguard/blob/main/COMPARISONS.md) · 🔬 [Validation](https://github.com/raccioly/docguard/blob/main/VALIDATION.md) · 🗺️ [Roadmap](https://github.com/raccioly/docguard/blob/main/ROADMAP.md)

Architecture

graph TD

CLI["CLI Entry docguard.mjs"] --> Commands["Commands (28)"] Commands --> guard["guard"] Commands --> generate["generate"] Commands --> score["score"] Commands --> diagnose["diagnose"] Commands --> setup["setup wizard"] Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs · ignore explain · memory · upgrade · agents · hooks · badge · ci · watch"]

guard --> Validators["Validators (36)"] generate --> Scanners["Scanners (4) routes · schemas · doc-tools · speckit"] score --> Scoring["Weighted Scoring 8 categories"] diagnose --> Validators diagnose --> AIPrompts["AI-Ready 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. Exact declarations in .docguard-evidence.json can verify selected statements against current local evidence; every other statement remains unverified. 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 current roadmap prioritizes accurate detection, reproducible evidence, document lifecycle management, and contributor-supplied regression cases. Released plans and superseded specifications are removed from active AI context and remain recoverable from Git.

---

⚡ 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 keep every other output off it. Mount the project you want inspected at /workspace; tools inspect it by default, and a projectDir in a tool call must be /workspace or a directory inside it (add --root after the image name to serve another mounted tree).

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 only reads the mounted project.

More ways to integrate

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

  repos:

• repo: https://github.com/raccioly/docguard rev: v0.46.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`; read-only tools to check docs (guard, score, diagnose, …) and to navigate them one bounded section at a time — the full list is in [docs/ai-integration.md](docs/ai-integration.md). 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. The release workflow renders the formula template in packaging/homebrew/ from the published npm tarball and pushes it to the tap.

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 (override with --force), is idempotent, and prints exactly what changed. Prose stays with the agent.

Continuous documentation workflow

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

• CI / pre-commit: docguard hooks --type pre-commit --auto-fix installs a hook that applies mechanical fixes, re-stages the docs, then runs guard; anything left is surfaced as agent prompts.
• Agent-driven: docguard diagnose --auto scaffolds missing docs and applies mechanical fixes, then emits prompts for the content rewrites that remain.
• JSON for automation: guard/diagnose --format json include a mechanicalFixes array and tag each issue mechanical vs agent, so an agent can apply or delegate precisely.

---

☁️ AWS AI-DLC Integration

DocGuard reads AWS AI-DLC workspaces on its own: traceability targets that no longer exist, gaps left in completed stages, deliverables removed afte