Read your entire project spec in 30 seconds. Verify it in one command.

facts is the facts cli — a lightweight Rust CLI and toolkit for fact-driven development — a precise, atomic, and machine-verifiable approach to specifications designed specifically for AI coding agents (Claude Code, Cursor, Aider, and others).

Instead of long, fluffy documents that agents struggle to follow, you maintain a .facts file: a flat, readable list of atomic truth statements about your project. Each fact can carry an optional shell command that the machine verifies automatically.

Traditional specs and "project context" files are often vague, contradictory, or out of date. AI agents then produce code that doesn't match the intended behavior.

Fact-driven development fixes this by making every claim:

• Atomic — one clear truth per line
• Verifiable — either by a fast command or explicit agent review
• Lifecycle-tracked — @draft → @spec → @implemented

Run facts check at any time to know exactly what holds, what is work-in-progress, and what still needs refinement.

# Install (choose one)
curl -fsSL https://av.codes/facts.sh | sh
npm install -g @avcodes/facts
pipx install facts-cli

# In your project
facts init
facts check
facts ll --tags "not implemented"

The init command detects your stack (Cargo, Node, etc.), creates a starter .facts file, installs the four agent skills, and adds the workflow section to your CLAUDE.md or AGENTS.md.

• facts or facts ll — skim the entire spec (markdown-like view)
• facts check — run all validation commands + report status
• facts add "..." --section api/auth — extend the spec
• at <id> spec / rt <id> draft — fast lifecycle tagging (aliases for edit)

See the full Facts CLI Reference for every flag and the powerful boolean filters (--tags "mvp and not blocked", --search, --depth).

This wiki expands on the concepts:

• Fact-Driven Development — the methodology in depth
• Fluffy Specs — the problem facts was built to solve
• .facts File Format — complete syntax reference
• Facts Check — how verification works, including CI
• Facts Lifecycle — how agents autonomously move facts through the pipeline
• Facts with AI Agents — integration patterns with Claude, Cursor, and other agents
• Facts CLI Reference — every subcommand and power feature
• Installing Facts — all installation methods

This very project (av/facts) is specified and verified with its own .facts file containing hundreds of facts. Run facts check after cloning to see it in action.

Start using fact-driven development today — your agents (and future self) will thank you.

Maintained by the facts project. Contributions and feedback welcome on GitHub.