FAF defines. MD instructs. AI codes.
project/
├── package.json ← npm reads this
├── project.faf ← AI reads this
├── README.md ← humans read this
└── src/
Every building requires a foundation. FAF is AI's foundational layer.
You have a
package.json. AI needs you to add aproject.faf. Done.
Git-Native. project.faf versions with your code — every clone, every fork, every checkout gets full AI context. No setup, no drift, no re-explaining.
bunx faf # Bun — zero install, fastest path
npx faf # npm — works everywhere
brew install faf-cli && faf # Homebrew
fafis shorthand forfaf-cli auto— same behavior, fewer keystrokes.
Run faf with no arguments:
Until now we have had 85% as a recommended minimum. It's now 100%! 🏆 All or nothing.
AI gets its best shot at assisting you. Period.
We are able to do this because we can now get you to 100% on virtually any app-type.
FAF Init > Auto > Go = 100%.
faf sync locks MD ↔ FAF with 100% 🏆 — anti-hallucination, pro-code.
(Adding about — the 20th app-type — made the ladder hit a score. How no-score became a score. Fitting, because v6.6 is when that score became the only one we recommend.)
Receipts → CHANGELOG
v6 is a ground-up rewrite. All-in on Bun — same toolchain as Claude Code.
| Claude Code | faf-cli v6 | |
|---|---|---|
| Runtime | Bun | Bun (bunx) |
| Test | Bun | bun test |
| Build | Bun | bun build |
| Language | TypeScript | TypeScript |
| Compile | Bun bytecode | bun build --compile |
408 tests in ~13s. 296KB bundle in 2.4s. Single portable binary, 4 platforms. npx backward-compatible.
26 commands. 408 tests. WJTTC-tested. 93% smaller than v5.
commands → interop → core → wasm
The WASM scoring kernel (faf-scoring-kernel 2.0.0) does the math. Bun does the delivery.
| # | Command | One-liner |
|---|---|---|
| 1 | faf init |
Create .faf from your local project |
| 2 | faf git <url> |
Instant .faf from any GitHub repo — no clone |
| 3 | faf auto |
Zero to 100% in one command |
| 4 | faf go |
Guided interview to gold code |
| 5 | faf score |
Check AI-readiness (0-100%) |
| 6 | faf sync |
.faf ↔ CLAUDE.md (bi-sync, mtime auto-direction) |
| 7 | faf compile |
.faf → .fafb binary — sealed, portable, deterministic |
| 8 | faf decompile |
.fafb → JSON |
| 9 | faf export |
Generate AGENTS.md, .cursorrules, GEMINI.md |
| 10 | faf check |
Validate .faf file |
| 11 | faf edit |
Edit .faf fields inline |
| 12 | faf convert |
Convert .faf to JSON |
| 13 | faf drift |
Check context drift |
| 14 | faf context |
Generate context output |
| 15 | faf recover |
Recover .faf from CLAUDE.md / AGENTS.md |
| 16 | faf migrate |
Migrate .faf to latest version |
| 17 | faf search |
Search slots and formats |
| 18 | faf share |
Share .faf via URL |
| 19 | faf taf |
Generate TAF test receipt |
| 20 | faf demo |
Demo walkthrough |
| 21 | faf ai |
AI-powered enhance & analyze |
| 22 | faf pro |
Pro features & licensing |
| 23 | faf conductor |
Conductor integration |
| 24 | faf formats |
Show supported formats |
| 25 | faf info |
Version and system info |
| 26 | faf clear |
Clear cached data |
Run faf --help for full options.
# ANY GitHub repo — no clone, no install, 2 seconds
bunx faf-cli git https://github.com/facebook/react
# Your own project
bunx faf-cli init # Create .faf
bunx faf-cli auto # Zero to 100% in one command
bunx faf-cli go # Interactive interview to gold code🏆 Trophy 100% — all or nothing. From v6.6.0 onward, faf-cli recommends only Trophy. 100% on the FCL is what makes the layers above (MD instructions, Agents, AI tooling) work — sub-Trophy leaves gaps that AI guesses on. Sub-Trophy tiers are honest interim states on the way to Trophy, not endpoints.
| Tier | Score | Status |
|---|---|---|
| 🏆 Trophy | 100% | AI never has to guess |
| ★ Gold | 99%+ | 1 slot from Trophy |
| ◆ Silver | 95%+ | Close — keep going |
| ◇ Bronze | 85%+ | Interim — keep going |
| ● Green | 70%+ | Interim — keep going |
| ● Yellow | 55%+ | AI flipping coins |
| ○ Red | <55% | AI working blind |
| ♡ White | 0% | No context at all |
bi-sync: .faf ←── 8ms ──→ CLAUDE.md (free forever)
tri-sync: .faf ←── 8ms ──→ CLAUDE.md ↔ MEMORY.md (Pro)
Bun's single-file compiler produces standalone binaries — no runtime needed.
bun run compile # Current platform
bun run compile:all # darwin-arm64, darwin-x64, linux-x64, windows-x64Ship faf as a single binary for CI/CD, Docker, or air-gapped environments.
src/
├── cli.ts ← Entry point, 26 command registrations
├── commands/ ← 26 command files (1 per command)
├── core/ ← Types, slots (33 Mk4), tiers, scorer, schema
├── detect/ ← Framework detection, stack scanner
├── interop/ ← YAML I/O, CLAUDE.md, AGENTS.md, GEMINI.md
├── ui/ ← Colors (#00D4D4), display
└── wasm/ ← faf-scoring-kernel wrapper (Rust → WASM)
Toolchain: Bun (test, build, compile) · TypeScript (strict) · WASM (scoring kernel)
Robust. Reliable. Next-level WJTTC tested. — The Foundation Edition.
bun test # 408 tests, 42 files, ~13s- WJTTC Build Resilience (13) — every regression class locked.
- WJTTC Kernel Stress (19) — WASM kernel boundary tests.
- e2e lifecycle — every command in sequence.
Test reports in reports/.
- GitHub Discussions — Questions, ideas, community
- Email: team@faf.one
If faf-cli has been useful, consider starring the repo — it helps others find it.
MIT — Free and open source
IANA-registered: application/vnd.faf+yaml
format | driven 🏎️⚡️ wolfejam.dev