DEV Community

Cover image for The File That Sits Between package.json and README.md
wolfejam.dev
wolfejam.dev Subscriber

Posted on

The File That Sits Between package.json and README.md

#programming #opensource #ai #tooling

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
Enter fullscreen mode Exit fullscreen mode

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 Screenshot showing project.faf file sitting alphabetically between package.json and README.md in a file browser
  • 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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

8 milliseconds average sync time. You edit one, the others update. Context drift becomes impossible.

faf bi-sync --watch
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)