agent-guard

The Problem: Context Rot

Every codebase tells two stories: the code itself, and the documentation that explains it. Over time, these stories diverge. A developer adds a new API route but forgets to update the docs. Another renames an environment variable but doesn't touch the README. A third refactors the database schema while the architecture doc still references the old model names.

This is Context Rot — the slow decay of documentation accuracy that plagues every long-lived project.

The symptoms are familiar:

• New team members onboard with outdated information
• AI coding assistants hallucinate based on stale context
• Architecture decisions get lost to tribal knowledge
• "The code is the documentation" becomes the reluctant mantra

agent-guard solves Context Rot with a four-layer defense system that keeps your documentation perpetually synchronized with your code.

How It Works: Four Layers of Defense

┌─────────────────────────────────────────────────────────────────────┐
│                         YOUR CODEBASE                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  LAYER 1: Standing Instructions                               │  │
│  │  ─────────────────────────────────────────────────────────── │  │
│  │  AI agents receive real-time context about your docs.         │  │
│  │  When they modify code, they update documentation inline.     │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              │                                      │
│                              ▼                                      │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  LAYER 2: Generated Inventories                               │  │
│  │  ─────────────────────────────────────────────────────────── │  │
│  │  Deterministic scripts extract truth from code:               │  │
│  │  • API routes → docs/_generated/api-routes.md                 │  │
│  │  • Prisma models → docs/_generated/prisma-models.md           │  │
│  │  • Env vars → docs/_generated/env-vars.md                     │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              │                                      │
│                              ▼                                      │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  LAYER 3: Pre-commit Hook                                     │  │
│  │  ─────────────────────────────────────────────────────────── │  │
│  │  Catches drift before it reaches the repo:                    │  │
│  │  • Detects doc-relevant code changes                          │  │
│  │  • Auto-fixes docs or generates remediation prompts           │  │
│  │  • Configurable: advisory (exit 0) or blocking (exit 1)       │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              │                                      │
│                              ▼                                      │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  LAYER 4: CI/CD Audits                                        │  │
│  │  ─────────────────────────────────────────────────────────── │  │
│  │  Final safety net in your pipeline:                           │  │
│  │  • GitHub Actions catch drift on every push                   │  │
│  │  • Weekly scheduled health checks                             │  │
│  │  • PR comments with specific remediation steps                │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Quick Start

# Install agent-guard as a dev dependency
npm install --save-dev @mossrussell/agent-guard

# Initialize agent-guard in your project
npx agent-guard init

# Run full documentation sync (generators + AI narrative)
npx agent-guard sync

# Set up git hooks
npm run prepare

Auto-Fix Mode

When you commit, the pre-commit hook automatically:

1. Runs inventory generators — regenerates docs/_generated/*.md files and stages them
2. Updates narrative docs — uses your configured engine to update ARCHITECTURE.md and README.md based on your changes
3. Refreshes standing instructions — rebuilds the documentation maintenance section in your AI agent config files (.cursorrules, CLAUDE.md, etc.) from the current config categories
4. Updates session context — writes .agent-guard/session-context.md with a rolling 10-commit summary so AI agents have continuity between sessions
5. Falls back gracefully — if no engine is available, it prints a copy-paste prompt instead

By default the hook is advisory (exit 0). In blocking mode (autoFix.hook.mode: "blocking"), it exits 1 when docs are stale, ensuring documentation stays in sync.

Self-invocation guard

When Claude Code (or another AI agent) is the one committing, the hook detects this via environment variables and skips all AI engines to prevent deadlock. In blocking mode, it exits 1 with a remediation message telling the agent to update docs itself and retry.

Engine Options

| Engine | Speed | Cost | Requirements | |--------|-------|------|--------------| | API Engine (Recommended) | ~12 seconds | ~$0.13/commit | ANTHROPIC_API_KEY in .env | | Claude Code Engine | ~30-60 seconds | Free (uses your session) | Claude Code CLI installed |

API Engine — Calls the Anthropic API directly. Fast, cross-platform, and reliable. Set "engine": "api" in config.

Claude Code Engine — Spawns Claude Code as a subprocess. Free if you have an active Claude Code session, but slower and requires the CLI installed.

When auto-fix succeeds:

✓ Doc-relevant changes detected — docs also updated. Nice!

[main abc1234] feat: add user endpoint
 4 files changed, 52 insertions(+)

When no engine is available (prompt mode):

⚠️  Documentation may need updating
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Changed:
  📡  API Routes (1 file):
     - src/app/api/users/route.ts

┌─────────────────────────────────────────────┐
│  Claude Code Prompt (copy-paste this):       │
└─────────────────────────────────────────────┘

The following files were changed and documentation may need updating...

API Engine Setup

To use the faster API engine:

1. Add your API key to .env:

   ANTHROPIC_API_KEY=sk-ant-...

2. Set engine to "api" in agent-docs.config.json:

   "autoFix": {
     "narrative": {
       "enabled": true,
       "engine": "api"
     }
   }

3. That's it — next commit or npx agent-guard sync will use the API.

Cost estimate: ~$0.13/commit, ~$0.29/sync, ~$12-15/month with active use. Zero new dependencies (uses Node 20+ native fetch).

Commands

| Command | Description | |---------|-------------| | agent-guard init | Interactive setup wizard. Creates config, scripts, hooks, and workflows. | | agent-guard init --yes | Non-interactive setup with defaults. Use --project-name, --prisma, --agent-config flags. | | agent-guard init --force | Update template scripts to latest version. Preserves ARCHITECTURE.md, config settings, and husky hooks. | | agent-guard detect | Auto-detect baselines (file counts, TODOs, etc.) and update config. | | agent-guard gen | Run all inventory generators (gen:api-routes, gen:env, gen:models). | | agent-guard check | Run the pre-commit documentation check manually. | | agent-guard check --check-only | Staleness detection only — no AI calls. | | agent-guard sync | Full documentation pass: runs generators + AI narrative updates. |

All commands support -v, --verbose for detailed output and -c, --config <path> to specify a custom config file.

Configuration

agent-guard is configured via agent-docs.config.json:

{
  "projectName": "My Project",
  "architectureFile": "docs/ARCHITECTURE.md",
  "agentConfigFile": ".cursorrules",
  "additionalAgentConfigs": ["CLAUDE.md"],
  "autoFix": {
    "generators": true,
    "narrative": {
      "enabled": true,
      "engine": "api",
      "model": "claude-sonnet-4-20250514",
      "apiKeyEnv": "ANTHROPIC_API_KEY",
      "maxTokens": 32000,
      "review": false,
      "narrativeTriggers": ["api-routes", "prisma", "env"],
      "additionalNarrativeTargets": ["README.md"]
    },
    "hook": {
      "mode": "blocking",
      "checkOnly": false,
      "skipIfClaudeRunning": true
    }
  },
  "scanPaths": {
    "apiRoutes": "src/app/api/",
    "prismaSchema": "prisma/schema.prisma",
    "envFile": ".env.example"
  }
}

Key configuration fields:

| Field | Description | |-------|-------------| | projectName | Your project name, used in generated docs. | | architectureFile | Path to your main architecture doc (default: docs/ARCHITECTURE.md). | | agentConfigFile | Primary AI agent config file (.cursorrules, CLAUDE.md, etc.). | | additionalAgentConfigs | Extra agent config files to write standing instructions to. | | autoFix.generators | Auto-run inventory generators at commit time (default: true). | | autoFix.narrative.enabled | Enable AI narrative updates (default: true). | | autoFix.narrative.engine | "api" (direct API) or "claude-code" (subprocess). Default: "claude-code". | | autoFix.narrative.model | Anthropic model ID. Default: "claude-sonnet-4-20250514". Only used with API engine. | | autoFix.narrative.apiKeyEnv | Env var name for API key. Default: "ANTHROPIC_API_KEY". Only used with API engine. | | autoFix.narrative.maxTokens | Max response tokens. Default: 32000. Only used with API engine. | | autoFix.narrative.review | Show diff and confirm before staging AI changes (default: false). | | autoFix.narrative.narrativeTriggers | Category IDs that trigger narrative updates. | | autoFix.narrative.additionalNarrativeTargets | Extra files for AI to update beyond architectureFile. | | autoFix.hook.mode | "advisory" (default, never block commits) or "blocking" (exit 1 when docs stale). | | autoFix.hook.checkOnly | Skip AI calls, only detect staleness (default: false). | | autoFix.hook.skipIfClaudeRunning | Skip all AI engines when Claude Code is committing (default: true). Prevents deadlock and surprise costs. | | scanPaths | Paths to scan for API routes, Prisma schema, env file, etc. |

Documentation Structure

docs/
├── ARCHITECTURE.md          # Human-maintained architecture overview
└── _generated/              # Auto-generated inventories (do not edit)
    ├── api-routes.md        # Extracted from src/app/api/**
    ├── prisma-models.md     # Extracted from prisma/schema.prisma
    └── env-vars.md          # Extracted from .env.example

.agent-guard/
├── session-context.md       # Rolling commit summary for AI session continuity
├── log.json                 # Rotating audit log (last 500 entries)
├── .gitkeep
└── .gitignore               # Excludes signal files (.auto-fix-ran, .docs-stale)

Session Context

On every commit with doc-relevant changes, agent-guard generates .agent-guard/session-context.md containing:

• Recent Commits — last 10 commits with categories triggered and docs updated
• Last Hook Run — what the pre-commit hook did (engine used, files auto-fixed, errors)
• Documentation Health — hook mode, engine config, stale markers, monitored categories

AI agents read this at session start for continuity. The standing instructions injected into your agent config files include a "Session Start" section that tells agents to read this file.

How the Layers Work Together

| Layer | Trigger | Action | |-------|---------|--------| | Standing Instructions | AI agent session | Updates docs alongside code changes | | Generated Inventories | npm run gen:all or auto at commit | Regenerates markdown from source files | | Pre-commit Hook | git commit | Auto-runs generators, AI narrative updates, standing instruction refresh, session context; falls back to prompt if unavailable | | Session Context | git commit | Writes .agent-guard/session-context.md with rolling commit summary | | CI/CD Audits | Push / PR / Schedule | Creates issues if drift detected; quality-checks AI-generated docs |

Upgrading

To upgrade agent-guard and get the latest template scripts:

npm install --save-dev @mossrussell/agent-guard@latest
npx agent-guard init --force

The --force flag updates template scripts in scripts/ to the latest versions while preserving:

• docs/ARCHITECTURE.md — your real architecture doc is never overwritten
• agent-docs.config.json — existing settings are deep-merged with new defaults
• .husky/pre-commit — only prepends the doc-check line if missing
• .husky/prepare-commit-msg — same treatment

License

MIT