faf-kernel

The FAF kernel — parse, validate, and score .faf files. The engine every FAF shell runs on.

.faf is the Foundational AI-context Format, an open IANA-registered standard (application/vnd.faf+yaml): one small, portable YAML file that says what a project is, how it's built, and why. faf-kernel is the single source of truth consumed by every FAF shell — CLI, MCP server, WASM, edge worker. Score it here, and the CLI, the browser, and the edge all agree by construction — parity is a property of the build, not a test.

IANA media type: application/vnd.faf+yaml

Install

[dependencies]
faf-kernel = "1.1"

Quick start

use faf_kernel::{parse, score};

let faf = parse("faf_version: 2.5.0\nproject:\n  name: my-project\n").unwrap();
assert_eq!(faf.project_name(), "my-project");

let result = score("project:\n  name: x\n").unwrap();
assert!(result.score <= 100); // Mk4 33-slot scoring, 0–100

Scoring (Mk4, always-33)

.faf files score 0–100 against a fixed 33-slot model. Each slot is populated, empty, or slotignored; score = populated ÷ active (33 − slotignored). The kernel knows nothing about app_type, owner, or intent — a 600-engineer monorepo and a one-file script are the same object: a fill pattern over 33 slots. app_type decides which slots are written slotignored at generation time; the kernel only reads the markers. The score is deterministic — the same file always scores the same.

Tiers: Trophy 🏆 is the only emoji; sub-Trophy tiers are clean Unicode (★ ◆ ◇ ● ○ ♡).

AGENTS.md-ready fields (1.1.0)

FafData also carries commands (top-level build/test/lint/dev map), security (secrets/example/never), ai_instructions (warnings/working_style), and conventions — the fields an AGENTS.md generator (e.g. faf-cli's faf export --agents) actually reads from a .faf file. FafFile::commands() reads the top-level commands first, falling back to instant_context.commands for older .faf files that nest them there. Additive — no existing field renamed or removed.

Testing

28 WJTTC tests (Brake / Engine / Aero). As the kernel beneath every shell, this is the code those shells are tested against too — 236 tests pass across the FAF Rust workspace.

cargo test -p faf-kernel

Part of the FAF Rust workspace

One kernel, many shells:

faf-fafb — the FAFb v2 binary format (the compiled brick)
faf-rust-sdk — the high-level SDK facade (kernel + fafb + Axum)
faf-wasm-sdk — the same engine for the browser and edge (WASM)

License

MIT

Get the CLI

faf-cli — the original AI-context CLI. A must-have for every builder.

npx faf-cli auto

Anthropic MCP #2759 · IANA: application/vnd.faf+yaml · faf.one · npm

faf-kernel 1.1.0