Facts File Format

The .facts File Format

A .facts file is both valid Markdown and valid YAML (per section). It is deliberately simple so it can be read in its entirety in under a minute and edited by both users and AI agents.

File Discovery

• The project root is the directory containing the nearest .git folder.
• All *.facts files in the project root (and optionally subdirectories when explicitly targeted) are discovered.
• .facts is the default/main sheet. Use semantic names like api.facts, auth.facts, or cli.facts for additional sheets.

Structure

# section-name
- a plain string fact @tag1 @tag2
- label: a fact with extra data
  command: cargo test --quiet
  tags: [core, mvp]
  id: xyz          # optional explicit ID

Headings = Sections

• # creates a top-level section
• ##, ###, etc. create nested sections addressable by path (api/auth/login)
• Sections are created implicitly when you facts add --section "foo/bar"
• Empty sections are automatically cleaned up when their last fact is removed

Facts

Every fact is a YAML sequence item (-).

Two forms are supported:

1. Plain string (most common for simple truths)

   - users can sign up with email and password @mvp

2. Mapping (when you need a command, explicit ID, or structured tags)

   - label: the login endpoint returns a JWT on success
     command: curl -s -X POST ... | jq -e '.token'
     tags: [api, auth]

Allowed mapping keys: label (required), command, tags, id.

Tags

Tags are free-form tokens for filtering and categorization.

• Inline: - some fact @core @security
• Structured: tags: [core, security]
• Both can be combined; the tool normalizes them.
• Use boolean expressions on the CLI: --tags "core and not blocked" or --tags "mvp or v1"

Three special lifecycle tags drive agent workflows:

• @draft
• @spec
• @implemented

IDs

Every fact receives a short, stable ID (usually 3 characters) derived from a hash of its label (tags stripped).

• IDs appear in facts list, facts get <id>, and when adding.
• You can override with --id or --new-id on edit.
• IDs are stable as long as the label text does not change.

Validation Commands

Any fact with a command key is automatically verified by facts check.

• Commands run in the project root via $SHELL (or sh).
• Exit code 0 = the fact holds.
• Non-zero = failure (stderr is shown).
• No caching — every check is fresh.
• Timeouts are supported per-command via --timeout.

Facts without a command are manual facts. An agent or user must read the relevant code and explicitly state PASS or FAIL with a one-line reason.

Best Practices for Writing Facts

• Describe behavior, not file layout or library choices.
• Keep facts stable (avoid "there are currently 47 tests").
• Make commands fast and idempotent (test -f, grep -q, small scripts).
• One fact = one truth.

See the full Facts CLI Reference and the embedded facts skill for more examples and the official grammar.

The format is intentionally minimal — no frontmatter, no complex nesting, no custom directives. This is what makes it work so well with agents.