AI changed my auth system last year. Not a bug. Not a misunderstanding. It just... changed it. Confidently. Wrongly.
I went looking for the industry standard for AI context. The package.json for AI tools. The file that says "here's what this project is, here's how we do things."
It didn't exist.
So I built one.
The Alphabetical Accident
When I created project.faf, I didn't plan this. But look where it sits:
package.json ← npm's context
project.faf ← AI's context
README.md ← human's context
Alphabetically, it lands exactly where it belongs. Between the machine context and the human context. That's not marketing - that's the filesystem.
The Problem: DAAFT
Without persistent context, AI operates in a cycle I call DAAFT:
Discover — "What is this project?"
Assume — "Probably React? Maybe TypeScript?"
Ask — "Which API are you using?"
Forget — Next session, repeat from step 1
Tokens — LOST (and time)
The math:
- Without
project.faf: ~1,750 tokens per session re-discovering your project
- With
project.faf: ~150 tokens once
91% reduction. Nice.
But here's what nobody talks about.
Every session, AI's understanding shifts slightly. Different assumptions. Different mental model. After weeks, months — AI has drifted so far from reality it makes confident wrong decisions.
Then you blame AI. "It's hallucinating." "It doesn't understand." "AI is overhyped."
No. Your context drifted. AI is working with what it has.
That's how my auth system got changed. AI wasn't broken. My context was.
project.faf doesn't just save tokens. It makes drift impossible. The foundation doesn't move. AI stays aligned with your project, forever.
Stop blaming AI. Fix the drift.
The Fix: project.faf
project:
name: "acme-dashboard"
goal: "Real-time metrics for engineering teams"
main_language: typescript
stack:
frontend: react
backend: node
database: postgres
hosting: vercel
human_context:
who: "Engineering team at Acme Corp"
what: "Internal tool replacing spreadsheet workflows"
why: "Manual reporting takes 10 hours/week"
That's it. YAML. Human-readable. AI-readable.
When AI loads this first, it doesn't guess. It knows.
What's in v4.0
Bi-Sync
One source of truth that stays aligned with every AI's context file:
project.faf ←→ CLAUDE.md
←→ GEMINI.md
←→ conductor/
←→ any context file
8 milliseconds average sync time. You edit one, the others update. Context drift becomes impossible.
faf bi-sync --watch
Universal Format Detection
FAF scans your project and detects 154 framework/config combinations automatically:
$ faf formats
Detected formats:
✓ typescript (tsconfig.json)
✓ react (package.json → dependencies)
✓ vite (vite.config.ts)
✓ tailwind (tailwind.config.js)
✓ eslint (.eslintrc)
✓ prettier (.prettierrc)
Framework pyramid: 6 formats detected
AI-Readiness Scoring
$ faf score
project.faf analysis:
Project basics: 100% (3/3 slots)
Stack coverage: 100% (5/5 slots)
Human context: 80% (4/5 slots)
Overall: 🏆 95% - Gold tier
Missing: human_context.when
Suggestion: Add target timeline or deadline
The score isn't arbitrary. It's slot-based. A minimal project needs ~4 slots. A full enterprise project might use 21+. The percentage is filled slots divided by needed slots.
At 100%, AI has complete context for your stack. No clarifying questions needed.
The Credentials
I'm not going to oversell this. Here's what's real:
IANA Registration: application/vnd.faf+yaml is now an official media type. Filed October 2025, approved October 30. The format has a home alongside JSON, XML, PDF.
Anthropic MCP: PR #2759 merged into the official Model Context Protocol registry. FAF works natively with Claude Desktop.
Downloads: 21,000+ across the ecosystem (faf-cli, claude-faf-mcp, faf-mcp, grok-faf-mcp).
License: MIT. Free forever. No enterprise tier. No upsell.
Getting Started
# Install
npm install -g faf-cli
# Initialize (do this FIRST on any project)
cd your-project
faf auto
# Check status
faf status --oneline
# 🏆 project.faf 100% | bi-sync ✓ | foundation optimized
# Keep synced
faf bi-sync --watch
That's it. Your project now has persistent AI context.
The Philosophy
FAF first. The earlier AI has your project.faf, the more tokens you save, more importantly--the more time you save, and it adds up. So, don't add it after months of development (although it works on any repo, of any age). Get into a new habit--Add it day one.
Foundation, not configuration. This isn't settings. It's the ground your AI builds on. You don't configure a foundation. You establish it.
Trust, not hope. With FAF, you're not hoping AI understands your project. You know it does.
What's Next
- Native integrations with more AI tools
- Conductor orchestration patterns
- Enterprise patterns (monorepo support)
- Community-driven format extensions
Try It
npm install -g faf-cli && faf auto
GitHub: github.com/Wolfe-Jam/faf-cli
Website: faf.one
AI changed my auth system because it didn't know my project.
Now it does.
What's your biggest frustration with AI context? I'd love to hear what's missing or what would make this more useful for your workflow.