One .faf file → AGENTS.md · CLAUDE.md · GEMINI.md · .cursorrules,
detected from your real stack, scored, and versioned with your code. No drift. No re-explaining.
· across npm, PyPI and crates.io · IANA-registered · Anthropic-merged (#2759)
⭐ Star it on GitHub: bookmarks it for you, helps other devs find it too.
FAF defines. AGENTS.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 auto # Bun — zero install, fastest path
npx faf auto # npm — works everywhere
pnpm dlx faf auto # pnpm — zero install
brew install wolfe-jam/faf/faf-cli && faf auto # Homebrew (auto-taps)
fafwith no arguments shows your project's score.faf autofills what it detects in the repo, and suggests the goal and six W's for you to confirm infaf go.
# Any public GitHub repo — one shallow clone, no install (fills the tech slots)
bunx faf-cli git https://github.com/facebook/react
# Your own project
bunx faf-cli init # Create .faf
bunx faf-cli auto # Fill the tech slots from the repo, then score
bunx faf-cli go # Confirm the goal and six W's, suggested in grayRun faf with no arguments:
faf-cli dogfoods itself — project.faf is source DNA; CLAUDE.md, GEMINI.md and AGENTS.md are authored from it (
faf export, andfaf syncfor CLAUDE.md); AGENTS.md keeps a hand-written section below faf's block.
| Command | What it does |
|---|---|
faf init |
Create project.faf from your local project; suggest the goal and six W's |
faf git <url> |
Instant .faf from any GitHub repo (a shallow clone) |
faf auto |
Detect the stack, fill the slots it detects, score; suggest the goal and six W's |
faf go |
Fill the human slots: each suggestion in gray, Tab to edit, Enter to confirm |
faf score |
Check AI-readiness (0–100%) |
faf export |
Author AGENTS.md, GEMINI.md, .cursorrules and the Copilot instructions |
faf sync |
.faf → CLAUDE.md, one way (faf's block only) |
faf memory |
.fafm soul ops — convert Claude memory, etch, recall, ls, show |
faf diff / log |
Semantic context diff + score timeline across git history |
faf hooks --install |
Pre-commit guard against context regression |
faf taf setup |
Write the CI workflow that prints a Test Receipt for every run: a test job with a read-only token, then a receipt job (JavaScript with Jest, Vitest or Bun; Python; Go; Rust; Java with Maven or Gradle; .NET) |
faf taf receipts |
Your Test Receipts in the terminal, newest first |
faf compile / decompile |
.faf → .fafb v2 sealed brick; decompile shows sections as JSON |
faf check |
Validate a .faf file |
faf show |
Render project.faf to a browsable HTML page |
faf formats |
List supported stacks and formats |
Run faf --help for the full command set and options.
Portable agent memory in the IANA-registered .fafm format. Same INTEROP as claude-fafm-sdk 1.0.
# Claude Code memory dir → soul.fafm
faf memory convert ~/.claude/projects/.../memory -o soul.fafm
faf memory ls # ranked facts
faf memory recall "your query" # deterministic filter + rank
faf memory etch "a durable fact" --id my-fact
faf memory showThe six W's now reach every agent: AGENTS.md points to project.faf, and CLAUDE.md, GEMINI.md, .cursorrules, Copilot and llms.txt carry them, one rule, one line each.
- AGENTS.md points to the facts. A
## Project factssection namesproject.faf, by its real path from AGENTS.md (a legacy.faf, a file one folder up,--output). The only pointer before was an HTML comment, which agents skip. AGENTS.md still doesn't copy the six W's. - The six W's in every context file. GEMINI.md and .cursorrules gain a Context section, as CLAUDE.md and the Copilot instructions have.
llms.txtand Claude Code's MEMORY.md block (Pro) show the same values. - One rule, the score's. A slot the score counts as empty (empty,
slotignored, TBD, N/A) is left out; numbers, dates and lists show as text; each fact is one line. CLAUDE.md no longer showsslotignoredor placeholders. faf taf setupwrites two jobs (faf-taf-git 2.7.0): the tests run with a read-only token, only the receipt job can write, and a red run on the default branch is recorded as aFAILEDreceipt.- Why: the evidence. On tasks whose deciding fact was only in the six W's, Codex and OpenCode found the team's decision 4/22 times with the old AGENTS.md, 12/21 with the pointer, 19/20 with the six W's in the file.
Earlier editions: CHANGELOG.md · Releases
Your own rules for the AI — "use full words in identifiers," "use bun, not npm" — go in project.faf under ai_instructions.warnings. They lead the Guardrails section of every AGENTS.md faf writes, verbatim and non-destructive.
→ How to add custom rules · docs.faf.one
✪ 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 (including Bronze 85) remain on the ladder as honest interim states — they are not deleted; we just no longer aim for 85 as the goal.
| Tier | Score | Status |
|---|---|---|
| ✪ Trophy | 100% | AI never has to guess — target |
| ★ Gold | 99%+ | 1 slot from Trophy |
| ◆ Silver | 95%+ | Close — keep going |
| ◇ Bronze | 85%+ | On the ladder (was the old recommend-min; not the target) |
| ● Green | 70%+ | Interim — keep going |
| ● Yellow | 55%+ | AI flipping coins |
| ○ Red | <55% | AI working blind |
| ♡ White | 0% | No context at all |
Always-33. The score is filled ÷ active across all 33 Mk4 slots. Your app-type decides which slots are active; the rest are slotignored and stay visible. Same file, same engine, same number — see docs/SCORING.md.
One score, three glyphs: ✪ work (CLI · docs · receipts) · 🏆 social (X · blogs) · Trophy Mark PNG (brand). Source of truth: src/core/tiers.ts.
sync: .faf ───→ CLAUDE.md (one way: faf's block only)
tri-sync: .faf ───→ CLAUDE.md + Claude Code's MEMORY.md (Pro: faf's block only; Claude's notes kept)
The full manual lives at docs.faf.one — facts for devs, faf-cli first. One-page overview: faf-cli.vercel.app.
- Getting started — install · run · use
- Cards — one
.fafa→ A2A · Server Card · registry · AI Catalog · ARD - Custom rules — pin instructions your AI must follow
- Every command — one section per command, with real output
For a specific agent: Grok, xAI & Cursor 👀 · Claude Code 👀 · Bun 👀
Pivotal releases — full history in CHANGELOG.md:
- v8.11 — Project Facts — the six W's reach every agent file; AGENTS.md points to project.faf.
- v8.10 — Human Slots — AI suggests the goal and six W's; you confirm each one in
faf go. - v8.9 — Write-Once — a birth certificate that can't be reissued, checked against its birth commit.
- v8.0 — Always33 — one engine, one number: the same score everywhere.
- v7.1 — AGENTS.md —
faf export --agentsauthors a complete, non-destructiveAGENTS.md. - v7.0 — GIT — context goes git-native:
faf diff/log/hooks. - v6.16 — Know Your Stack — every emitted file labels your stack identically.
- v6.15 — Copilot —
faf export --copilotwrites the file GitHub Copilot reads. - v6.14 — Loop —
faf loopdrives any repo to ✪ 100% or the honest human wall. - v6.7 — HTML —
faf showrenders a.fafto a browsable page. (FAF defines. AGENTS.md instructs. AI codes. HTML shows.) - v6.6 — Trophy — 100% or nothing.
- v6.0 — Bun — ground-up rewrite; single portable binary, four platforms.
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 (Commander registrations)
├── commands/ ← one file per faf subcommand
├── core/ ← Types, slots (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.
npm test # extensive WJTTC + e2e suite- WJTTC Build Resilience — regression classes locked.
- WJTTC Kernel Stress — WASM kernel boundary tests.
- e2e lifecycle — commands 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.
If you use faf-cli or the .faf / .fafm / .fafa formats in research or production, please cite the format papers:
Wolfe, J. (2025). Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding. Zenodo. https://doi.org/10.5281/zenodo.18251362
Wolfe, J. (2026). Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory. Zenodo. https://doi.org/10.5281/zenodo.20348942
Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641
@article{wolfe2025faf,
title = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},
author = {Wolfe, James},
year = {2025},
month = {nov},
publisher = {Zenodo},
doi = {10.5281/zenodo.18251362},
url = {https://doi.org/10.5281/zenodo.18251362}
}
@article{wolfe2026fafm,
title = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},
author = {Wolfe, James},
year = {2026},
month = {may},
publisher = {Zenodo},
doi = {10.5281/zenodo.20348942},
url = {https://doi.org/10.5281/zenodo.20348942}
}
@article{wolfe2026fafa,
title = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},
author = {Wolfe, James},
year = {2026},
month = {aug},
publisher = {Zenodo},
doi = {10.5281/zenodo.21951641},
url = {https://doi.org/10.5281/zenodo.21951641}
}MIT — Free and open source
IANA-registered: application/vnd.faf+yaml (Context Layer) · application/vnd.fafm+yaml (Memory Layer) · application/vnd.fafa+yaml (Agent Layer)
format | driven 🏎️⚡️ wolfejam.dev · faf.one/cli
