// Manage .facts files — atomic, validatable truth statements about a project. Install, check, list, add, edit, remove, and lint facts via the CLI. ALWAYS read this skill when the user mentions facts in any capacity.
Answer questions about how 'mi' works, write new tools, or modify the harness. Use for "how do you work", "write a tool", "add a tool", "create a tool", "extend yourself", "edit yourself", "what tools do you have", or any introspection/modification of the running agent.
Scan the codebase and classify every fact by lifecycle stage — tag @draft, @spec, or @implemented based on what the code actually shows. Add missing facts, fix inaccurate ones, remove obsolete ones. Use when asked to discover facts, bootstrap or update a fact sheet, scan the codebase for truths, sync facts to match the code, or audit the fact sheet for accuracy.
Operate on @spec facts — implement them in code, then tag @implemented. Use when asked to implement facts, implement the spec, build from the fact sheet, make facts true, or work through unimplemented requirements.
Operate on @draft facts — collaboratively refine them into precise, actionable @spec facts. Resolve ambiguities, fill gaps, eliminate contradictions, and sharpen labels until every fact is ready to implement. Use when asked to refine facts, clarify the spec, review facts for quality, or "work on facts" with the user.
Write a new SKILL.md to teach yourself a procedure for a recurring task. Use when asked to "write a skill", "create a skill", "add a skill", "remember how to X", "make a procedure for X", or when you notice a task pattern worth recalling in future sessions.
Answer "how does X work", "where is X defined", or "trace through Y" questions about a codebase using parallel subagent searches with cited summaries.
| name | facts |
| description | Manage .facts files — atomic, validatable truth statements about a project. Install, check, list, add, edit, remove, and lint facts via the CLI. ALWAYS read this skill when the user mentions facts in any capacity. |
A CLI for fact-driven development. You use it to specify what must be true about a project, then validate that reality matches.
Project: https://github.com/av/facts
If facts is not installed, install it with one of:
curl -fsSL https://raw.githubusercontent.com/av/facts/main/install.sh | sh
npm install -g @avcodes/facts
pipx install facts-cli
Verify with facts --version. The command is always facts — never npx facts.
A .facts file is a flat list of atomic truth statements about a project. Each fact can optionally have a shell command that verifies it. The fact sheet serves as both specification (what should be true) and documentation (what is true) — the difference is just which direction you're working from.
- the API returns JSON
- label: project builds
command: cargo build
- label: tests pass
command: cargo test
tags: [ci, core]
That's the entire format. Plain strings for simple facts, mappings when you need a command, tags, or explicit ID. Allowed mapping keys: id, label, command, tags — nothing else.
See everything:
facts list
facts list --tags "not implemented"
facts list --has-command
Validate:
facts check
facts check --tags "ci"
check is your primary feedback loop. It lints the files first (aborting on structural errors), then runs every command-fact and reports pass/fail/manual. Run it often. Exit 0 means all command-facts pass; manual facts don't affect the exit code.
Add facts:
facts add "users can sign up" --section features/auth
facts add "signup returns 201" --command "curl -s -o /dev/null -w '%{http_code}' localhost:3000/signup | grep 201" --section features/auth
Edit facts:
facts edit <id> --add-tag "implemented"
facts edit <id> --remove-tag "blocked"
facts edit <id> --label "corrected statement"
facts edit <id> --command "new check command"
Prefer --add-tag / --remove-tag over --tags. The latter replaces all tags silently — use it only when you intend a full replacement.
Remove facts:
facts remove <id>
Scaffold a new project:
facts init
Run facts <command> --help for the full flag reference.
Files: .facts is the default. Additional sheets use semantic names (cli.facts, api.facts). All *.facts files in the project root are discovered automatically.
Sections: Markdown headings (#, ##, etc.) create hierarchical sections addressable by path (e.g. cli/subcommands). Sections are created when you add to them and removed when their last fact is deleted.
Tags: @word tokens for filtering. Inline for plain strings (- some fact @mvp), tags: key for mappings. Stripped from the label before display and ID hashing. Filter with boolean expressions: --tags "mvp and not blocked".
Lifecycle tags: Three well-known tags drive the agent workflow:
@draft — rough idea, needs refinement and atomization@spec — precise and actionable, ready to implement@implemented — true and backed by codeThe lifecycle flows @draft → @spec → @implemented. Each companion skill owns one transition.
IDs: Every fact gets a short ID (3+ chars) derived from its label hash. Stable as long as the label doesn't change. Use --id or --new-id to override.
Validation: Commands run via $SHELL (fallback sh) in the project root. Exit 0 = fact holds. Write commands that are fast and idempotent — they run on every check.
Good validation commands are fast, idempotent, and test one thing. Prefer test -f, grep -q, and short script checks over running full builds.
Start of work — always do this first:
facts list # read the full spec
facts check # see what holds and what doesn't
Use the fact sheet to orient before writing code. It is the source of truth for what the project should look like and what is already validated.
Define the spec (most common user intent): When the user says "work on facts", "add facts", or "define the spec", they want to collaboratively define what should be true — not audit what already is.
facts add "users can sign up" --section features/auth --tags "draft"
facts add "signup returns 201" --command "curl -s ..." --section features/auth --tags "spec"
@draft — they'll be refined into precise specs later@spec — they're ready to implement@draft or @spec facts — they represent intended future workfacts-discover unless the user explicitly asks to sync with realityTrack lifecycle progress:
facts list --tags "draft" # rough ideas to refine
facts list --tags "spec" # ready to implement
facts list --tags "implemented" # done
facts list --tags "not implemented" # all remaining work
facts check # verify
Maintain accuracy during coding work: When you add a feature, add corresponding facts. When you fix a bug, verify related facts still hold. When you remove code, remove obsolete facts.
facts check # find failing facts
facts edit <id> --label "corrected" # fix inaccurate facts
facts remove <id> # remove obsolete facts
facts add "new truth" --section foo # add discovered truths
Each skill owns one lifecycle transition:
@draft, @spec, @implemented). Use to triage or bootstrap.@draft facts and refine them into precise @spec facts with the user. Use when drafts need sharpening.@spec facts and implement them in code, then tag @implemented. Use when specs are ready to build.