The Frustration

It started with AI changing my auth system. Just... changed it. Wrong assumptions, no context, confident execution of the wrong thing.

I went looking for the industry standard—the package.json for AI context. Surely someone had solved this?

They hadn't.

Every new session, every new file, every new developer—AI starts fresh. Context leaks away. Yesterday's collaborator becomes today's stranger.

So I built one.

The DAAFT Problem

Without persistent context, AI operates in the DAAFT cycle:

    D iscover — "What is this project?"
         ↓
    A ssume — "Probably React? Maybe TypeScript?"
         ↓
    A sk — "Which API are you using?"
         ↓
    F orget ──→ T okens LOST (and TIME!)
         │
         └──── repeat ────┐
                          ↓
                     D iscover...

Don't be DAAFT.

This cycle costs tokens. More importantly, it costs trust. Wrong assumptions cascade into wrong code into debugging sessions into frustration.

Without project.faf

~1,750

tokens per session

+ 7,500 tokens rework risk

With project.faf

~150

tokens once

Zero assumptions. Zero drift.

91% fewer tokens. Zero risk. No drift.

The Proof

What does FAF actually change? Here's a real commit:

Before FAF

git commit -m "fix bug"
git commit -m "update code"
git commit -m "changes"

After FAF

git commit -m "fix: resolve API timeout in voice streaming

Addresses issue where Grok voice responses would timeout
after 30s. Now properly handles chunked streaming.

Context: FAF-Voice browser-to-xAI integration"

The difference? FAF provides project.goal, human_context.why, and stack—the DNA that makes commits meaningful.

What's in Foundation 4.0

The Core Shift

What changed is how we think about it:

Foundation, not configuration — This isn't settings. It's the ground your AI builds on.
Persistent, not cached — Lives in your repo, versioned, shared, permanent.
Universal, not tool-specific — Same file works with Claude, Gemini, Grok, any AI.

Bi-Sync

project.faf stays synchronized with CLAUDE.md in under 10 milliseconds:

project.faf ←── 8ms ──→ CLAUDE.md

One source of truth. Both files aligned. Context drift prevented at root cause.

Developer Loop

New skills integrate FAF context into daily work:

/commit — Context-aware git commits
/pr — Context-aware pull requests
/review — Context-aware code reviews

The Journey

Aug 7, 2025 First .faf file created

Sep 18, 2025 Claude: "This should become the standard"

Oct 16, 2025 Anthropic merges PR #2759 into MCP registry

Oct 30, 2025 IANA registers application/vnd.faf+yaml

Jan 24, 2026 FAF v4.0 — The Foundation Layer

We're not announcing a format. We're documenting a standard.

What the AIs Said

"Game-changer for eternal AI context"

Grok by xAI 9.5/10

"Should become the standard"

Claude Code 9.5/10

"Every project should have one"

OpenAI Codex CLI 9/10

"README evolution for AI era"

Google Gemini CLI 9.5/10

The Philosophy

FAF First

The earlier AI has your project.faf, the more tokens you save. Don't add FAF after months of development. Add it day one.

Foundation, Then Features

Get to 100%, then build. Every session after that starts with full context.

Trust, Not Hope

With FAF, you're not hoping AI understands. You know it does.

Get Started

# 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

Full v4.0 Page npm MCP Registry

What We're Still Learning

FAF isn't perfect. Some honest limitations:

Scoring is approximate. Our 0-100% score is useful but imperfect. A 95% project.faf might still miss something critical for your specific workflow.
Auto-detection has gaps. faf auto catches most stacks, but novel combinations sometimes need manual tuning.
Adoption is still early. Most developers don't know FAF exists. This is as much a communication challenge as a technical one.

We're iterating. Feedback shapes the standard.

Thank You

To everyone who filed issues, suggested features, pointed out bugs, and used FAF in production before it was "ready"—thank you. Standards emerge from use. This one emerged from yours.

.faf — The Persistent AI Context Standard