facts CLI
A CLI and four skills for fact-driven development: a .facts file of verifiable claims about a project and their lifecycle
- 207 ★ on the repository
- Last commit
Extended access
Why this level
- The `command` field runs shell commands from the `.facts` file on your machine on every check
- The skills let the agent edit the `.facts` file and implement facts in the project code
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/factsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The `command` field runs shell commands from the `.facts` file on your machine on every check
- The skills let the agent edit the `.facts` file and implement facts in the project code
This is third-party code. Review the repository files before installing.
What it does
facts keeps a project specification in a `.facts` file: each line is one claim such as "sessions expire after 24 hours". A claim can carry a lifecycle tag: `@draft` (a rough idea), `@spec` (a precise requirement ready to build) and `@implemented` (done and backed by code). If a fact has a `command` field, it is a shell command, and exit code 0 means the claim holds. `facts check` lints all files and runs the commands, and manual facts stay unverified until you add `--agent` (presets `claude`, `codex`, `opencode` and others). A non-zero exit code suits CI. Other commands: `facts add`, `edit`, `move`, `remove`, `get`, `list`, `lint`, `fmt`, `init`. Four skills ship with the CLI: `facts` for reading and editing the file, `facts-discover` to scan the codebase and classify facts, `facts-refine` to sharpen drafts into precise specs together with you, and `facts-implement` to build specs, verify them and switch the tag to `@implemented`. It is a single Rust binary for Linux, macOS and Windows.
Who it is for. People building a project with a coding agent who want a specification that fits on one screen and verifies with a command.
Good fit when
- A specification has grown into a long document and the agent loses important parts of it
- You want to see how many requirements are built, how many wait for implementation and how many are drafts
- A requirement verifies with a simple command such as `test -f src/main.rs` or `grep`
- CI needs a check that the declared properties of the project still hold
- You want to give an agent a draft, spec, implementation loop with a recorded state per fact
Not a fit when
- You need detailed design documentation with diagrams and rationale: a fact is meant to be one short line
- Requirements cannot be verified by a command and you do not want an agent to verify them: such facts stay unchecked
- Several teams maintain the specification in different formats and no one plans to convert it into a flat list of claims
- You need an actively maintained project: the repository's last commit is from June 3, 2026
Example request
Init facts. Then scan the codebase, add facts about authentication and data storage and mark which ones are already implemented.Limitations
Only facts with a shell command verify automatically. The rest stay marked `?` until you run `facts check --agent` with a configured agent, and with `--strict` unverified facts fail the build. The command in a `command` field runs on your machine, so a third-party `.facts` file should be read before running the check.
The project is small with a single author. The last commit is from June 3, 2026, and the MIT license is stated in the repository. Skills are installed into a project by `facts init` or by a separate skill manager, and `facts uninit` removes everything.
How to disable. The `facts uninit` command removes `.facts` and the installed skills from the project. The binary is removed the way it was installed: `npm uninstall -g @avcodes/facts` or `pipx uninstall facts-cli`.
FAQ
How do I install facts for an agent?
Run `npx skills add av/facts`, then ask the agent to Init facts: it detects the stack and creates `.facts` with the first claims. The binary installs separately: `curl -fsSL https://av.codes/facts.sh | sh`, `npm install -g @avcodes/facts` or `pipx install facts-cli`.
What does a `.facts` file look like?
It is plain markdown and also valid YAML per section: headings group facts, a list line holds a claim, and the `command` and `tags` sub-keys add a check and labels. A fact's ID is a short hash of its text.
What does `facts check` do?
It lints file structure and runs fact commands. Exit code 0 means everything passed and non-zero means something failed. For manual facts add `--agent claude` or another preset, and in CI use `--strict` and `-q`.
How do the tags differ?
`@draft` is a rough idea, `@spec` a precise requirement ready to build, `@implemented` something built and backed by code. The agent moves facts between states through the refine and implement skills.
Can I keep several lists of facts?
Yes: `.facts` is the default and extra sheets get meaningful names such as `api.facts` or `cli.facts`. All `*.facts` files in the root are discovered automatically, and files in subfolders are visible only with an explicit `--file`.
Discussion
No questions or reviews yet.
Related
CLI toolsGitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
A CLI that keeps feature flags and A/B tests as Markdown in your repo and installs five Claude Code skills to run them.
A Rust CLI for TypeScript and JavaScript: dead code, duplicates, cycles, complexity and architecture boundaries from one graph, plus MCP and skills
Three skills and a clippy config: an agent writes, reviews and ports idiomatic Rust, and CI enforces the checkable rules
Two skills for spec-driven development: /spec asks questions and saves a document to specs/, /spec-impl implements an approved spec step by step
Tasks, docs, specs and decisions live as markdown files in your repository, and the agent reads them through the CLI and MCP
Comparison with similar tools
Cards that share the main search query, and how they differ.
README in short
The documentation describes the file format, a command table with short aliases (`ll`, `at`, `rt`) and the fact-driven development methodology. The project describes itself in a `.facts` file: 224 facts, 154 of them verified by commands. Extended guides live in the repository wiki.