January 2025
The Format That Became a Standard
In late 2024, we had a simple observation: AI assistants forget—even inadvertently change stuff (wrong assumptions)!
Every new session, every new file, every new developer—AI starts fresh. Context leaks away. Yesterday's collaborator becomes today's stranger.
We thought: what if project context could persist? Not in AI memory (which resets), but in the project itself.
That idea became .faf—the Foundational AI-context Format.
project/ ├── package.json ← npm reads this ├── project.faf ← AI reads this └── src/
A project.faf file sits alongside your package.json. It contains your project's DNA: the stack, the goals, the conventions, the context that AI needs to understand your project specifically.
Every building requires a foundation. project.faf is AI's foundation. When AI loads your project.faf, it doesn't guess. It knows.
Without persistent context, AI operates in the DAAFT cycle:
Don't be DAAFT.
~1,750
tokens per session
~150
tokens once
91% fewer tokens. Zero risk. No drift.
It was borne out of pure frustration—one day AI even changed the Auth system! I started looking for the Industry format... the package.json for AI context, if you will—to my utter astonishment there wasn't one? AI needed a format for Context, so I built one.
.faf was born. F1-inspired software engineering became faf.one.
We designed the format, then the engine. Developers started using it. Feedback came in. Edge cases emerged. We refined the structure, added scoring, built tooling, launched the CLI on npm. The rest is history.
.faf created (Day 0)faf-cli launches on npm (Day 62)application/vnd.faf+yaml (Day 84).faf — The Persistent AI Context Standard
Scales from 4 slots (minimal) to 21+ slots (full) — some enterprise repos hit 30+
project: name: "acme-dashboard" goal: "Real-time metrics dashboard for engineering teams" main_language: typescript stack: frontend: react backend: node database: postgres hosting: vercel auth: clerk api: rest ci_cd: github_actions monitoring: datadog human_context: who: "Engineering team at Acme Corp" what: "Internal tool replacing spreadsheet workflows" why: "Manual reporting takes 10 hours/week" where: "US-based, remote team" when: "Q1 2026 launch target" how: "Agile sprints, trunk-based development" discovery: frameworks_detected: ["react", "typescript", "vite"] package_manager: npm test_framework: vitest
Above: 21-slot example. Your project might need fewer — faf auto detects what's relevant.
This isn't settings. It's the ground your AI builds on.
Lives in your repo, versioned, shared, permanent.
Works with Claude, Gemini, Grok, ChatGPT, any AI.
One .faf, every AI's context file. The faf sync command keeps them aligned.
One source of truth. All files aligned. Context drift prevented at root cause.
/commit — Context-aware git commits/pr — Context-aware pull requests/review — Context-aware code reviews🏆 project.faf 100% | bi-sync ✓ | foundation optimizedproject.faf is complete for your stackThe foundation is solid. Add great things above it.
The earlier AI has your project.faf, the more tokens you save. Add it day one.
Get to 100%, then build. Every session after that starts with full context.
With FAF, you're not hoping AI understands. You know it does.
Setting honest expectations:
You must run faf init to create the file. Once it exists, Claude reads it first—but someone has to add it.
It's project context, not API documentation. Tools like context7 handle library docs—.faf complements them with your project's DNA.
It's free open-source software (MIT). Quality depends on your project structure. 100% is recommended—that's AI confirming it has full context. Fun fact: a human can only score 99%.
Any project with AI-coding.
# Install npm install -g faf-cli # or: brew install faf-cli # Initialize (do this FIRST on any project) cd your-project faf auto # Verify faf status --oneline # 🏆 project.faf 100% | bi-sync ✓ | foundation optimized # Now plan. Now build.