av/facts

What is facts?

av/facts is a workflow and specification format for managing a project as a list of atomic claims in a .facts file. Each line is a short, structured statement about what should be true, and it can optionally include a shell command that the machine runs to verify the claim.

The core purpose is to let an agent and your team keep project requirements readable and checkable: you write rough truths, refine them into precise specs, and then implement and verify them. You can run facts check to see which claims pass, fail, or need manual attention.

Key Features

• Atomic “fact” specification format (.facts): Write one claim per line as plain strings, organized with Markdown headings by domain.
• Lifecycle tagging for progress tracking: Use @draft, @spec, and @implemented (plus any custom tags) to show where each claim is in its pipeline.
• Command-backed verification: For facts that include a command, facts check runs the command and considers the claim true when the command exits 0.
• Automated verification and status grouping: facts check lints files, runs every command, and groups results (e.g., green pass, red fail, yellow manual); it exits non-zero if anything fails.
• CI-friendly exit codes and filtering: Filter checks by tag expressions (e.g., --tags "mvp and not blocked") to verify subsets of your spec.
• Agent-managed transitions and implementation against the spec: An agent reads the fact sheet, picks up @spec facts, builds them, runs facts check, and tags passing facts as @implemented while the spec updates itself.

How to Use facts

1. Install the CLI/agent tooling (the project offers multiple install options, including a Rust binary and an npx command as described below).
   • Example: npx skills add av/facts
   • Then ask the agent to run Init facts (e.g., “Init facts”) to detect your stack and create an initial .facts file.
2. Create or edit your .facts file using the documented format:
   • Add headings to organize by domain (e.g., # auth, # data).
   • Add one claim per line.
   • Tag each fact with lifecycle stage labels such as @draft, @spec, or @implemented.
   • For verifiable claims, include a command that exits 0 when the claim holds.
3. Run verification: use facts check to lint and verify all facts (or use --tags to limit checks). Review which ones passed, failed, or require manual work.
4. Iterate with the agent: write rough ideas as @draft, refine them into @spec, then let the agent implement @spec facts and tag them as @implemented after they pass facts check.

Use Cases

• Project spec validation after changes: Keep a living checklist of what must be true and run facts check after edits to quickly see what still holds.
• Turning requirements into executable checks: Convert “must be true” statements (like authentication behavior or data handling rules) into facts with command-based verification.
• Managing work-in-progress with a fact lifecycle: Use @draft → @spec → @implemented to communicate progress and ensure each claim is either implemented and verified or clearly marked for refinement.
• Automated codebase discovery and classification: Use the facts-discover skill to scan the codebase and classify facts by lifecycle stage, including adding missing truths.
• Implementing against a spec: Use the facts-implement flow where the agent reads @spec facts, builds code, verifies it with facts check, and updates tags.

FAQ

Is facts only a documentation format, or does it actually verify claims? It can do both: facts without commands may be verified by the agent against the codebase, while facts with a command are verified by running the command and checking for exit code 0.

What does facts check do? It lints the files, runs every provided command, groups results by status (pass/fail/manual), and exits non-zero if anything fails.

How are facts organized and tracked? Facts live in a .facts file written in Markdown/YAML-compatible structure, with headings for domain organization and tags (including @draft, @spec, @implemented) to track lifecycle status.

Can I check only part of my project? Yes. facts check supports tag filtering via --tags with boolean expressions.

Alternatives

• Test suites (unit/integration tests): Traditional tests can verify behavior, but a .facts checklist emphasizes human-readable atomic claims and a lifecycle/status pipeline, not just automated pass/fail.
• Static documentation + code review: Docs can capture requirements, but they usually aren’t directly executable; facts ties claims to verification via facts check.
• Specification tools that support requirements traceability: Tools that link requirements to implementation may provide traceability, but facts specifically uses a line-by-line claim format with optional command execution and tag-based lifecycle transitions.