crag

Your AI agents are reading stale rules right now.

You have .cursorrules from three months ago. CLAUDE.md doesn't know about the API routes you added last week. copilot-instructions.md still says "use npm" but you switched to pnpm. Your CI enforces rules that none of your AI configs mention.

We checked 13 of the most important open-source projects. 9 of them — Django, Angular, Vue, Svelte, Tokio, Remix, Tauri, Cal.com, Airflow — have zero AI agent configuration. No CLAUDE.md. No .cursorrules. No AGENTS.md. Nothing. Your AI agent is working off stale training data with zero project-specific guidance.

The 4 that do have configs? Supabase has 3 separate AI config surfaces that don't share rules. Prisma's own AGENTS.md warns: "Your training data contains a lot of outdated information."

These are projects with hundreds of contributors. Yours is worse.

crag fixes this. One command.

npx @whitehatd/crag

Analyzes your project. Generates governance. Compiles to all 12 AI tool formats. 500 ms. Zero dependencies.

What happens when you run it

crag analyze reads your project — CI workflows, package manifests, configs, directory structure, code patterns — and writes a governance.md that captures what a senior engineer would write after spending a week with your codebase:

## Gates (run in order, stop on failure)
### Lint
- npm run lint
### Test
- npm run test
### Build
- npm run build
- npm run typecheck

## Architecture
- Type: monolith
- Entry: bin/app.js

## Key Directories
- `src/` — source
- `test/` — tests (unit + integration)
- `prisma/` — database

## Testing
- Framework: vitest
- Naming: *.test.ts

## Code Style
- Indent: 2 spaces
- Formatter: prettier
- Linter: eslint

## Anti-Patterns
Do not:
- Use `any` in TypeScript — use `unknown`
- Use `getServerSideProps` with App Router — use Server Components

Then crag compile --target all takes that single file and generates configs for every AI tool your team uses — in each tool's native format, with the right frontmatter, activation patterns, and structure:

One file in, twelve files out. Change a rule, recompile, done.

Then it watches your back

$ crag audit

  crag audit — governance drift report

  Compiled configs
  ✗ .cursor/rules/governance.mdc     stale — governance.md is newer
  ✗ AGENTS.md                        stale — governance.md is newer
  ✓ .github/workflows/gates.yml      in sync
  ✓ .husky/pre-commit                in sync

  Gate reality
  ✗ npx tsc --noEmit                 tsc not in devDependencies
  ✗ npm run lint                     "lint" script not in package.json

  2 stale · 2 drift
  Fix: crag compile --target all — or — crag audit --fix

Install the pre-commit hook and it auto-recompiles on every commit:

crag hook install              # auto-recompile when governance changes
crag hook install --drift-gate # also block commits if drift detected

50 repos. Zero crashes. 40% had drift.

We cloned 50 of the highest-profile open-source projects and ran the full crag pipeline on each one. 20 languages. 7 CI systems. Monorepos to single-crate Rust libraries.

1,809 gates inferred across 50 repos. 96.4% verified accurate (187/194 gates matched against codebase reality in deep audit). Full results: benchmarks/phase1-benchmark.md

Get started

# One command — analyze + compile in one shot
npx @whitehatd/crag

# Or step by step:
npx @whitehatd/crag analyze                   # generate governance.md
npx @whitehatd/crag compile --target all       # compile to 12 targets
npx @whitehatd/crag audit                      # check for drift
npx @whitehatd/crag hook install               # enforce on every commit

Requirements: Node.js 18+ and git. Zero runtime dependencies.

How it works

Analyze. Reads your repo: 25+ language detectors, 11 CI system extractors, 8 framework convention engines. Writes governance.md with gates, architecture, testing profile, code style, anti-patterns, and framework conventions. Under a second, zero config.

Compile. Converts governance.md to each tool's native format. MDC frontmatter for Cursor. YAML trigger: for Windsurf. Numbered steps for AGENTS.md. Path-scoped files for monorepos. Custom content survives recompilation.

Audit. Three detection axes: (1) compiled configs older than governance.md, (2) governance references tools that don't exist, (3) AI tool directories present but no compiled config. Reports drift, suggests fixes.

Hook. Pre-commit hook auto-recompiles when governance.md changes. Optional drift gate blocks commits if configs are stale.

Deterministic: same input produces byte-identical output. No LLM. No network. No API keys.

Proof

Further reading

• docs/commands.md — every subcommand, every flag, every exit code
• docs/compile-targets.md — the 12 compile targets and their formats
• docs/governance-format.md — the governance.md v2 format
• docs/languages.md — the 25+ stack detectors
• docs/ci-systems.md — the 11 CI extractors
• docs/workspaces.md — monorepo and workspace support

Contributing

Issues and PRs at github.com/WhitehatD/crag.

If crag analyze misses a language, CI system, or gate pattern on a public repo, file an issue with the repo URL and crag analyze --dry-run output. That's the most valuable bug report.

MIT — Alexandru Cioc (WhitehatD)