raccioly/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:**
>
> Runs against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.
📚 **Documentation**: 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.
| Traditional Development | Canonical-Driven Development |
|:----|:----|
| Code first, docs maybe | Docs first, code conforms |
| Docs rot silently | Drift is tracked and enforced |
| Docs are optional | Docs are required and validated |
| One AI agent, one context | Any agent, shared context via canonical docs |
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 (9-page brief)** (PDF) · 📖 **Philosophy** · 📋 **CDD Standard** · ⚖️ **Comparisons** · 🔬 **Validation** · 🗺️ **Roadmap**
Architecture
> **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)
Python (PyPI)
> **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:
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; 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:
The server is **read-only** — it never writes to the mounted project.
More ways to integrate
- **pre-commit** — changed-only guard on every commit:
- **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. Registry manifest ships in-repo (server.json, Smithery-ready).