faf-cli

The package.json for AI Context

project/
├── package.json     ← npm reads this
├── project.faf      ← AI reads this
└── src/

Every building requires a foundation. project.faf is AI's foundation.

You have a package.json. Add a project.faf. Done.

At 100% AI Readiness, AI stops guessing and starts knowing. Live bi-sync between project.faf ↔ CLAUDE.md means zero context-drift — your project DNA stays aligned with AI, forever.

---

The Problem: AI Guesses. You Pay.

Without project.faf, every session:

• AI re-discovers your project (costs tokens)
• AI asks questions you've answered before (costs time)
• AI makes wrong assumptions (costs rework)
• Context drifts session to session (costs trust)

project.faf fixes this permanently.

---

The Solution: Add project.faf

🏆 Congrats, your project is optimized for AI.

Over to you. Build something that resonates.

At 100% AI Readiness:

• AI knows your stack, goals, and conventions
• Zero clarifying questions needed
• Context persists across sessions
• Drift is impossible — the foundation doesn't move

---

💎 The Math

Without project.faf	With project.faf
~1,750 tokens/session verifying context	~150 tokens once
Risk: wrong guess = 7,500+ tokens rework	Zero risk
Context drift accumulates	Drift impossible
Hope	Trust

91% fewer tokens. Zero risk. No drift.

---

⚡ Quick Start

FAF first. The earlier AI knows your project, the more tokens you save.

# Install
npm install -g faf-cli    # or: brew install faf-cli

# Initialize (do this FIRST on any project)
cd your-project
faf auto                  # Creates project.faf at 100%

# Verify
faf status --oneline      # 🏆 project.faf 100% | bi-sync ✓ | foundation optimized

# Now plan. Now build.

Add to package.json (see FAF status every dev session):

{
  "scripts": {
    "predev": "faf status --oneline"
  }
}

---

What's New in v3.4.7 — Google Gemini Edition

Full interoperability with the Google Gemini ecosystem. One .faf file now works everywhere.

Platform	Format	FAF Command
Gemini CLI	GEMINI.md	faf gemini
Antigravity IDE	~/.gemini/GEMINI.md	faf gemini --global
Conductor Extension	conductor/ directory	faf conductor
Claude Code	CLAUDE.md	faf bi-sync

# Import from Google formats
faf gemini import       # GEMINI.md → .faf
faf conductor import    # conductor/ → .faf

# Export to Google formats
faf gemini export       # .faf → GEMINI.md
faf conductor export    # .faf → conductor/

# Global Antigravity config
faf gemini --global     # ~/.gemini/GEMINI.md

Universal AI Context — Write once, use with Claude, Gemini CLI, Antigravity IDE, and Conductor.

---

🔄 Bi-Sync: project.faf ↔ CLAUDE.md

Your project.faf stays synchronized with CLAUDE.md in milliseconds.

project.faf  ←──── 8ms ────→  CLAUDE.md
     │                            │
     └── Single source of truth ──┘

faf bi-sync              # Sync once
faf bi-sync --watch      # Continuous sync

---

Tier System: From Blind to Optimized

Tier	Score	Status
🏆 Trophy	100%	AI Optimized — Gold Code
🥇 Gold	99%+	Near-perfect context
🥈 Silver	95%+	Excellent
🥉 Bronze	85%+	Production ready
🟢 Green	70%+	Solid foundation
🟡 Yellow	55%+	AI flipping coins
🔴 Red	<55%	AI working blind
🤍 White	0%	No context at all

At 55%, AI is guessing half the time. At 100%, AI is optimized.

---

Core Commands

Command	Purpose
faf init	Create project.faf from your codebase
faf score	Check AI-readiness (0-100%)
faf auto	Auto-enhance to Gold Code
faf bi-sync	Sync .faf ↔ CLAUDE.md (8ms)
faf readme	Extract 6 Ws from README (+25-35% boost)
faf human	Interactive human context entry
faf human-set	Non-interactive field setting
faf formats	Show 153 detected formats
faf conductor	Google Conductor interop (import/export/sync)
faf gemini	Gemini CLI / Antigravity interop
faf demo sync	Live bi-sync demonstration

Run faf --help for all 46 commands.

---

Human Context (The 6 Ws)

Boost your score by 25-35% with human context — the information only YOU know.

# Auto-extract from README
faf readme --apply

# Manual entry
faf human-set who "Frontend team at Acme Corp"
faf human-set what "Customer dashboard with real-time analytics"
faf human-set why "10x faster than previous solution"

---

CLI vs MCP

Tool	Use Case
faf-cli (this)	Terminal, scripts, CI/CD, automation
claude-faf-mcp	Claude Desktop via MCP protocol

Same project.faf. Same scoring. Same result. Different execution layer.

---

📦 Ecosystem

• MCPaaS — MCP as a Service (The Endpoint for Context)
• claude-faf-mcp — MCP server (52 tools)
• faf-wasm — WASM SDK (<5ms scoring)
• Chrome Extension — Browser integration
• faf.one — Official website

---

📚 Documentation

• CHANGELOG — Version history
• Website — Complete guide

---

📄 License

MIT License — Free and open source

---

.faf is the format. project.faf is the file. 100% 🏆 AI Readiness is the result.

"package.json gives me a list of dependencies, project.faf shows me how to use them" — Claude