faf-cli

v4.5.0

Published

a day ago

The Persistent AI Context Standard • Foundation Layer for AI • IANA-Registered • Anthropic-Approved • project.faf = AI's foundation

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 6 Ws - Quick Reference

Every README should answer these questions. Here's ours:

| Question | Answer | |----------|--------| | 👥 WHO is this for? | Developers using AI coding assistants (Claude, Gemini, Cursor, Grok, ChatGPT) | | 📦 WHAT is it? | The package.json for AI context - IANA-registered format | | 🌍 WHERE does it work? | Everywhere AI needs context (Claude Code, Gemini CLI, Cursor, etc.) | | 🎯 WHY do you need it? | 100% context (AI-scored), persists forever, bi-syncs automatically - saves $1000s/developer | | ⏰ WHEN should you use it? | New projects (day one), existing projects (now), exploring repos (instantly) | | 🚀 HOW does it work? | npx faf-cli git <url> - No install, no clone, 2 seconds |

For AI: Read the detailed sections below for full context. For humans: Use this pattern in YOUR README. Answer these 6 questions clearly.

👥 WHO is this for?

Built for developers working with AI coding assistants:

Full-stack developers using Claude, Cursor, Gemini CLI, or ChatGPT
Engineering teams collaborating on AI-augmented projects
Solo developers tired of re-explaining context every session
Open source maintainers wanting contributors to onboard instantly
Anyone building with TypeScript, React, Python, Node.js, or modern frameworks

If you use AI to code, project.faf saves you time and tokens. Every project. Every session.

📦 WHAT is project.faf?

The package.json for AI context. Just another file in your project.

Like package.json tells npm about dependencies, project.faf tells AI about your project DNA:

Your stack: React + TypeScript + Vite
Your goals: What you're building and why
Your conventions: How your team works
Your context: The information only YOU know

IANA-registered format: application/vnd.faf+yaml — An official standard, not just another .md file.

💎 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.

🌍 WHERE does it work?

Everywhere AI needs context:

Official Integrations

Claude Code (Anthropic) — Bi-sync with CLAUDE.md
Gemini CLI (Google) — Import/export GEMINI.md
Antigravity IDE (Google) — Global config support
Conductor Extension (Google) — conductor/ directory sync

Works With

Cursor, Cline, Windsurf, any AI coding assistant
ChatGPT, Claude Desktop, Gemini chat interfaces
CI/CD pipelines, automation scripts, build tools

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

Universal format. Works everywhere. Write once, use with any AI.

🎯 WHY do you need it?

What FAF Actually Does

1. 100% Context Quality — AI-scored with facts, not guesswork Every field in your project.faf is validated and scored. No more "I think this is a React app" — AI knows it is.

2. Context Persists Forever — Never lost, never re-explained Your project DNA is written once, read forever. No context drift across sessions, team members, or AI tools.

3. Bi-Sync Keeps It Current — Responds to changes automatically When your project evolves, project.faf ↔ CLAUDE.md stays synchronized in 8ms. Always current, never stale.

What That Actually Costs (Or Saves)

The DAAFT Tax (Discover, Assume, Ask, Forget, Time+Tokens)

Without project.faf, every AI session cycles through rediscovery:

❌ AI re-discovers your project (wastes tokens)
❌ AI asks questions you've answered before (wastes time)
❌ AI makes wrong assumptions → rework (wastes developer hours)
❌ Context drifts → compounding errors → project delays

The Economics:

Per developer: $5,460/year + 84 hours lost productivity
50-developer team: $273,000–$507,630 annually
91% of tokens wasted on rediscovery instead of building

The Real Cost:

Token waste (measurable: 91% wasted)
Time waste (expensive: $5,460/year per developer)
Project failure (catastrophic: 70% of projects fail, with 39% citing poor requirements and 57% citing communication breakdowns — both rooted in context loss)

Full analysis: faf.one/daaft

The Truth People Gloss Over

Bad context → wrong assumptions → rework → delays → project failure.

Good context isn't a "nice to have" — it's the foundation of AI-augmented development.

project.faf fixes this permanently.

At 100% AI Readiness:

AI knows your stack, goals, and conventions (scored with facts)
Zero clarifying questions needed (context persists)
Drift is impossible (bi-sync keeps it current)
Your project ships on time, within budget, with fewer surprises

⏰ WHEN should you use it?

New Projects

Day one. Initialize with context from the start:

npm init -y
faf init
# Your project now has AI-ready context

Existing Projects

Right now. Add context to projects already in progress:

faf init                    # Start from your codebase
faf go                      # Interview to 100%
faf auto                    # Auto-enhance to Gold Code

Exploring Repos

Instantly. Generate context for ANY GitHub repo WITHOUT cloning:

npx faf-cli git https://github.com/facebook/react
# 2 seconds → 95% 🥈 Silver score
# No install. No clone. Just instant context.

Daily Workflow

Always synced. Keep context fresh automatically:

faf bi-sync --watch         # Continuous sync with CLAUDE.md

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

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

🚀 HOW does it work?

Quick Start (No Install Required)

The revolutionary way — zero install, zero clone:

# Generate AI context for ANY GitHub repo
npx faf-cli git https://github.com/facebook/react
# ⏱️ 2 seconds → 95% 🥈 Silver score

npx faf-cli git https://github.com/sveltejs/svelte
# ⏱️ 2 seconds → 95% 🥈 Silver score

npx faf-cli git https://github.com/your-org/your-repo
# ⏱️ 2 seconds → 90%+ context, ready for AI

What just happened?

✅ No install required (npx runs latest version)
✅ No cloning required (uses GitHub API)
✅ 2 seconds → 95% AI-ready context
✅ Works on ANY public GitHub repo

This changes everything. You can now generate AI context for repos you don't even own. 🏎️

For Your Own Projects

# Start with your codebase
npx faf-cli init

# Or go interactive (completes the 6 Ws)
npx faf-cli go

For Pros: Install Globally (Daily Use)

Once you're hooked, install globally for full power:

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

# Then use short commands forever
faf git <repo-url>        # 1-Click Context (90%+)
faf go                    # Interactive to 100%
faf auto                  # Full automation
faf bi-sync               # Keep synced
# + 56 more commands

The Killer Combo

npx faf-cli git <repo-url>   # 90%+ context, no install, no clone
npx faf-cli go               # Interactive polish to 100%

Comparison: Traditional vs 1-Click Context

Traditional approach:

git clone https://github.com/facebook/react  # 10-30 seconds
cd react
npm install -g faf-cli                       # 10 seconds
faf init                                      # 5 seconds
# Total: ~45 seconds + local files

1-Click Context:

npx faf-cli git https://github.com/facebook/react
# Total: 2 seconds + ZERO local files

🎖️ 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.

🎯 Slot-Ignore: The Perfect Way to Handle App Types

Like .gitignore for files, slot-ignore for context slots.

FAF has 21 slots. Some don't apply to your project type. Slot-ignore handles this elegantly:

# CLI Tool - 21 slots total
stack:
  database: None           # ✅ Ignored (CLI doesn't need database)
  css_framework: None      # ✅ Ignored (no web UI)
  backend: Node.js         # ✅ Filled (has value)
  # ... other slots

Score: (Filled + Ignored) / 21 = 100% 🏆

The formula:

Total Slots: 21 (constant)
├── Filled: 15 (has values)
├── Ignored: 6 (set to 'None' - not applicable)
└── Missing: 0 (undefined - needs attention)

Score: (15 + 6) / 21 = 100%

Common patterns:

CLI Tools: Ignore database, css_framework, frontend
Backend APIs: Ignore css_framework, frontend, ui_library
Static Sites: Ignore backend, database, api_type
Libraries: Ignore hosting, cicd, database

Full spec: docs/SLOT-IGNORE.md

🔧 Core Commands

| Command | Purpose | |---------|---------| | faf git <url> | 🚀 1-Click Context - 90%+ for ANY GitHub repo (no cloning!) | | faf go | 🎯 Guided interview to 100% (completes the 6 Ws) | | faf init | Create project.faf from your codebase | | faf auto | Auto-enhance to Gold Code | | faf score | Check AI-readiness (0-100%) | | 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 agents | AGENTS.md interop (import/export/sync) | | faf cursor | .cursorrules interop (import/export/sync) | | 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 63 commands.

🔄 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 (CLAUDE.md)
faf bi-sync --agents     # Also generate AGENTS.md
faf bi-sync --cursor     # Also generate .cursorrules
faf bi-sync --all        # All formats at once
faf bi-sync --watch      # Continuous sync

🧠 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"

🧪 Boris-Flow Integration Tests

Boris-Flow is a 12-test validation suite that ensures faf-cli is demo-ready and safe to publish.

Named after Boris (Claude Code creator at Anthropic), these tests validate:

Version detection works correctly
Type and language detection (CLI, TypeScript, etc.)
Claude Code structure detection (agents, skills, commands)
Score progression: init → auto → 100%
Non-TTY safety (no crashes when stdin is piped)

When to run:

| Scenario | Command | |----------|---------| | Before faf init (on your project) | ./tests/boris-flow.test.sh validates faf-cli works | | After major changes to your .faf | Re-run to ensure structure is valid | | Before publishing faf-cli updates | Required - ensures no regressions | | Before WJTTC certification | Validates .faf file for Tier 8 | | Team onboarding | Proves faf-cli installation works |

Run Boris-Flow:

# Clone faf-cli repository
git clone https://github.com/Wolfe-Jam/faf-cli
cd faf-cli

# Run integration tests
./tests/boris-flow.test.sh

# Expected output:
# 🏆 BORIS-FLOW: ALL 12 TESTS PASSED
# ✅ Demo ready
# ✅ Safe to publish
#    Final score: 100%

What it tests:

✅ faf --version
✅ Created Claude Code 2.1.0 structure
✅ faf init created project.faf
✅ Detected CLI type
✅ Language detected (TypeScript)
✅ claude_code section exists
✅ Claude Code detected: true
✅ Subagents detected (2+)
✅ Skills detected (1+)
✅ Commands detected (1+)
✅ faf auto maintained score
✅ human-set commands succeeded
✅ Final score is 100%

Boris-Flow validates the FAF file structure that WJTTC Tier 8 tests. Running it before certification helps ensure you'll pass Tier 8.

🤝 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.

🌐 What's New in v4.5.0 — The AGENTS.md Edition

Define once in .faf, generate every AI context format. One file to rule them all.

| Platform | Format | FAF Command | |----------|--------|-------------| | OpenAI Codex / 20+ tools | AGENTS.md | faf agents | | Cursor IDE | .cursorrules | faf cursor | | Claude Code | CLAUDE.md | faf bi-sync | | Gemini CLI | GEMINI.md | faf gemini | | Antigravity IDE | ~/.gemini/GEMINI.md | faf gemini --global | | Conductor Extension | conductor/ directory | faf conductor | | All at once | Everything above | faf bi-sync --all |

# AGENTS.md (OpenAI Codex, Linux Foundation, 20+ tools)
faf agents export       # .faf → AGENTS.md
faf agents import       # AGENTS.md → .faf
faf agents sync         # Bidirectional

# .cursorrules (Cursor IDE)
faf cursor export       # .faf → .cursorrules
faf cursor import       # .cursorrules → .faf
faf cursor sync         # Bidirectional

# Generate ALL formats in one command
faf bi-sync --all       # CLAUDE.md + AGENTS.md + .cursorrules + GEMINI.md

Universal AI Context — Write once, use with Claude, Codex, Cursor, Gemini, and every AI tool.

📚 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