wolfe-jam/faf-cli/faf-expert

FAF Expert — Persistent Project Context Specialist

What is .faf?

The .faf file is Persistent Project Context for AI — a single source of truth that survives across sessions, tools, and AI assistants.

• IANA-registered media type: application/vnd.faf+yaml (registered Oct 30, 2025)
• Anthropic-listed: modelcontextprotocol/servers PR #2759 — claude-faf-mcp shipped as "Persistent Project Context Server" (merged Oct 17, 2025)
• Git-native: project.faf versions with your code; every clone gets full AI context
• The CLI behind the FCL — the Foundational Context Layer for AI

The credo: FAF defines. AGENTS.md instructs. AI codes.

When to activate this skill

• Creating, editing, or scoring .faf files
• Syncing .faf → CLAUDE.md, or exporting it to AGENTS.md, .cursorrules, GEMINI.md
• Diagnosing sub-Trophy scores and reaching 🏆 100%
• Explaining the FCL, tier system, or app-type ladder
• Connecting .faf work to the broader receipts: IANA, Anthropic PR #2759, MCP Registry

Install the CLI

bunx faf                       # Bun — zero install, fastest
npx faf                        # npm — works everywhere
npm install -g faf-cli         # global install
brew install faf-cli           # Homebrew

faf is the verb across every surface: bunx faf, npx faf, /faf (Claude Code plugin), faf (global). Bare faf shows your project's score; faf auto detects and fills.

The workflow

faf init → faf auto → faf go → 🏆 Trophy 100%

Run faf --help for the full 26-command set.

Scoring — Trophy 100% all-or-nothing

From v6.6.0 onward, faf-cli recommends only 🏆 Trophy.

Why all-or-nothing? Architectural, not aspirational:

Layer 4   AI tooling          ← AI optimised by complete FCL
Layer 3   Agents              ← can act because FCL is complete
Layer 2   MD instructions     ← can be re-authored correctly
Layer 1   .faf (FCL)          ← 🏆 Trophy = complete = foundation

100% on Layer 1 makes Layers 2–4 work. Sub-100% degrades every layer above — instructions miss context, agents guess, AI optimisation can't happen.

🏆 is the only emoji. Sub-Trophy tiers use geometric Unicode (★ ◆ ◇ ● ○ ♡). The retired medal ladder (🥇🥈🥉🟢🟡🔴🤍) is history.

The app-types

The app-type answers one question: what does this repo ship? It sets which of the 33 slots count; the rest are slotignored. App-types are types of projects, not types of file (a CLAUDE.md or a SKILL.md sits inside a project of some type).

The full table, with each type's slots, is in docs/SCORING.md. Write the type's own name (cli, not cli-tool); a name faf doesn't know is treated as library.

About (not an app_type): declare about.represents: owner/repo. Inherits about.source_score. Do not set app_type: about.

The CLI auto-detects via # found: rationale next to type::

project:
  type: cli  # found: package.json bin

Read the rationale; refute by inspection. Glass Hood doctrine — the CLI shows its work.

.faf file structure (current schema)

faf_version: 3.0
app_type: cli
 
project:
  name: my-project
  goal: One-line elevator pitch
  main_language: TypeScript
 
stack:
  framework: React
  backend: Node.js
  db: PostgreSQL
  api: REST
  css: Tailwind
  state: Zustand
  pkg_manager: bun
  hosting: Vercel
  build: vite
  cicd: GitHub Actions
  runtime: Node 20+
  connection: prisma
 
human_context:
  who: target users
  what: one-line description
  why: the problem this solves
  where: where it ships
  when: production since YYYY-MM
  how: install/usage command

v6.6.0 uses Mk4 canonical slot names in user-facing docs: db (was database), framework (was frontend), css (was css_framework), state (was state_management), api (was api_type), pkg_manager (was package_manager). 36k+ existing .faf files continue scoring correctly via read-time aliasing.

The sync flow — one way

.faf is the canonical Foundational Context Layer (FCL). CLAUDE.md / AGENTS.md / .cursorrules / GEMINI.md are downstream prose renders that READ .faf to save AI time. They never write back automatically.

.faf  ──── 8ms ───→  CLAUDE.md     (faf sync)
                     AGENTS.md     (faf export)
                     .cursorrules
                     GEMINI.md

faf sync --direction pull (CLAUDE.md → .faf backfill of name, goal and language) is Trophy-gated — blocked below 100% to prevent overwriting canonical slots with prose drift.

Receipts ladder

• IANA-registered: application/vnd.faf+yaml at iana.org/assignments/media-types/application/vnd.faf+yaml — registered 2025-10-30
• Anthropic-listed: PR #2759 merged Oct 17, 2025 — claude-faf-mcp added as "Persistent Project Context Server"
• MCP Registry: FAF Ecosystem #2759 (Five Fingers: claude / faf / grok / gemini / WJTTC)
• One dev, <12 months — IANA-registered, Anthropic-listed, xAI ZEPH commission, 100+ FAF-disciplined repos, the format used to build itself

Where to go next

FAF defines. AGENTS.md instructs. AI codes. v6.6.0 — The Trophy Edition. How no-score became a score.