The FAF Format

Two files, one source of truth

• .faf — the source. Human-readable YAML. faf init creates it, faf auto and a human complete it. The standard.
• .fafb — the compiled form. A small, sealed binary the .faf compiles to. The brick.

YAML is the source code; .fafb is the object file. You never edit the binary — you recompile from the .faf.

Example

A minimal .faf:

faf_version: 2.5.0
project:
  name: my-app
  goal: Ship a fast CLI
  main_language: Rust
human_context:
  who: Rust developers
  what: A command-line tool
  why: Speed without ceremony
stack:
  build: cargo
tech_stack:
  - Rust
key_files:
  - src/main.rs
commands:
  build: cargo build --release

.fafb — context, compiled

.fafb is the compiled binary form of a .faf. It's modeled on IFF — the chunked format Commodore created for the Amiga in the '80s (Microsoft's RIFF and the ELF executable format use the same idea): a magic number, a set of named chunks, and a table that indexes them.

What the binary buys you:

• Content-addressable — identical content compiles to identical bytes. The same project context yields the same hash on every machine, so a .fafb can be deduped, cached, and verified by hash. Context gets an identity.
• O(1) lookup — the section table sits at the end of the file; a reader maps any chunk by name without scanning content.
• Priority truncation — each chunk carries a truncation priority, so a reader deterministically drops lower-priority chunks to fit any token budget; identity chunks are kept longest.
• Sealed — a CRC32 of the source .faf is sealed into the header.

Closed canonical

The single design rule: the writer is closed, the reader is graceful.

• Writer (closed) — a compiler emits exactly the canonical chunk set, in canonical order, and nothing else. Non-canonical keys fold into the context chunk — preserved in full, never given a section of their own. The format has a fixed shape, the way a JPEG does.
• Reader (graceful) — an unknown section name is skipped, not rejected. A future minor version can add a chunk without breaking deployed readers.

Closing the writer is what makes the output content-addressable: the same .faf always compiles to identical .fafb bytes.

The canonical set is 13 chunks — 11 DNA (core identity) + 2 Context — mirroring the .faf structure:

• Identity — faf_version · project · app_type · about
• Stack — stack · tech_stack · key_files · commands
• Human & structure — human_context · monorepo · architecture
• Context — scores · context (the fold target)

The wire (v2)

A 32-byte little-endian header (magic FAFB, version, feature flags, source CRC32, and offsets), then section data in canonical order, a string table, and a 16-byte-per-entry section table at the end for O(1) access. Readers ignore unknown flag bits and skip unknown section names.

Full specification → BINARY-FORMAT.md

Stability — wire v2 is frozen

The byte layout is immutable, enforced by a byte-exact golden-master test. New capabilities ship only as forward-compatible additions — we do not break v2. Because the .faf source is always authoritative, you recompile, never migrate. Nothing gets trapped in an old binary.

Security & interop

.faf extends YAML — every .faf is a valid YAML document, so any standard YAML parser can read one; specialized parsers add validation and scoring. UTF-8, with no platform-specific path conventions in the core — portable by construction.

Treat .faf content as untrusted input. Implementations should:

• validate the YAML structure before parsing,
• sanitize file paths (no directory traversal),
• keep score and confidence values in range (0–100, 0–1.0),
• never execute code found in a .faf.

Privacy: a .faf may carry dependencies, architecture, and workflow detail — don't put secrets in a publicly shared one.

Registration

.faf is registered with IANA as the media type application/vnd.faf+yaml (registered 2025-10-30). The IANA record is the authoritative registration; the security and interop notes above mirror its considerations. Optional parameter: version (e.g. version=1.0).

Get it

Implemented in Rust — one kernel, many shells — so the same engine runs in the CLI, the browser, and at the edge, with nothing to drift:

The fastest way in — one command writes (or refreshes) your .faf:

npx faf-cli auto

Links

• Specification — BINARY-FORMAT.md
• IANA — application/vnd.faf+yaml
• GitHub — Wolfe-Jam/faf-rust