FAF Expert - Project DNA Specialist

What is .faf?

.faf is the universal format for persistent AI project context - "Project DNA ✨ for ANY AI".

Core Concepts:

•Foundational AI-context Format - YAML-based project context file
•Persistent Context - Survives across sessions, tools, and AI assistants
•Universal - Works with Claude, ChatGPT, Gemini, Cursor, any AI
•Measurable - Championship scoring system (0-100% AI-readiness)
•Official Anthropic MCP Steward - PR #2759 MERGED

When to Use This Skill

Activate this skill when:

•Creating or updating .faf files
•Working with CLAUDE.md files
•Running faf CLI commands (init, auto, score, formats, bi-sync)
•Scoring project AI-readiness
•Setting up MCP server (claude-faf-mcp)
•Configuring tool visibility (v2.8.0+)
•Discussing project context or documentation

Key Files

•.faf - YAML format, machine-readable project context
•CLAUDE.md - Markdown format, human-readable project guide
•Bi-Sync - .faf ↔ CLAUDE.md kept in sync automatically
•project.faf - v1.2.0 standard naming

Common Commands

faf-cli Commands

bash

faf init              # Create .faf from project
faf auto              # Auto-detect stack and create .faf
faf score             # Rate AI-readiness (0-100%)
faf formats           # List 153+ supported formats
faf bi-sync           # Sync .faf ↔ CLAUDE.md
faf status            # Check project AI-readiness
faf validate          # Validate .faf structure
faf doctor            # Diagnose and fix issues
faf migrate           # Migrate to latest format

MCP Tools (claude-faf-mcp v2.8.0+)

v2.8.0 introduces Tool Visibility System:

•21 Core Tools (default) - Essential workflow
•51 Total Tools (opt-in) - All features

Configuration:

json

{
  "mcpServers": {
    "faf": {
      "command": "npx",
      "args": ["-y", "claude-faf-mcp@2.8.0"],
      "env": {
        "FAF_MCP_SHOW_ADVANCED": "false"
      }
    }
  }
}

Core Tools (21):

•Essential Workflow: faf, faf_auto, faf_init, faf_innit, faf_status
•Quality: faf_score, faf_validate, faf_doctor, faf_audit
•Intelligence: faf_formats, faf_stacks, faf_skills
•Sync: faf_sync, faf_bi_sync, faf_update, faf_migrate
•AI: faf_chat, faf_enhance
•Help: faf_index, faf_faq, faf_about

Advanced Tools (30+): Set FAF_MCP_SHOW_ADVANCED: "true" to enable:

•Display variants: faf_display, faf_show, faf_check
•Trust system: faf_trust, faf_trust_confidence, faf_trust_garage
•File operations: faf_read, faf_write, faf_list, faf_exists, etc.
•DNA tracking: faf_dna, faf_log, faf_auth, faf_recover
•Utilities: faf_choose, faf_clear, faf_share, faf_credit

AI-Readiness Scoring

Championship Tiers:

•🏆 95-100% - Championship (Gold)
•🥇 85-94% - Podium (Silver)
•🥈 70-84% - Points (Bronze)
•🥉 55-69% - Midfield
•🟢 40-54% - Backmarker
•🟡 25-39% - Struggling
•🔴 10-24% - Critical
•🤍 0-9% - DNF (Did Not Finish)

Target: 85%+ for production projects

.faf File Structure

yaml

# Basic .faf structure
format: typescript-nextjs
language: typescript
framework: nextjs
version: "14.0.0"

structure:
  - src/
  - components/
  - pages/

dependencies:
  react: "^18.0.0"
  next: "^14.0.0"

testing: jest
deployment: vercel

# v1.2.0+ additions
project_name: "My Project"
ai_readiness_score: 87

Best Practices

•Start with faf auto - Let it detect your stack
•Review and refine - Auto-detection is 85% accurate, tweak as needed
•Run faf score - Target 85%+ for championship context
•Use faf bi-sync - Keep .faf and CLAUDE.md in sync
•Update regularly - As project evolves, update context
•Use core tools first - Advanced tools are opt-in for specific needs

The FAF Family

6 Championship Integrations:

•React (20M/week npm downloads) 🏆
•TypeScript (40M/week) 🏆
•Next.js (5M/week) 🏆
•Vite (9M/week) 🥇
•Svelte (400K/week) 🥇
•n8n (401K/week - TURBO only) 🥇

Installation

faf-cli (npm)

bash

npm install -g faf-cli

faf-cli (Homebrew)

bash

brew install faf-cli

claude-faf-mcp (MCP Server)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

json

{
  "mcpServers": {
    "faf": {
      "command": "npx",
      "args": ["-y", "claude-faf-mcp@latest"]
    }
  }
}

For advanced tools:

json

{
  "mcpServers": {
    "faf": {
      "command": "npx",
      "args": ["-y", "claude-faf-mcp@latest"],
      "env": {
        "FAF_MCP_SHOW_ADVANCED": "true"
      }
    }
  }
}

v2.8.0 Tool Visibility System

Problem Solved: Reduced cognitive load from 51 tools to 21 core tools.

How It Works:

•Default: Shows 21 essential tools
•Opt-in: Enable all 51 tools via environment variable
•Smart Filtering: Tools categorized by purpose
•Backward Compatible: Existing setups continue working

Categories:

•workflow - Essential commands
•quality - Scoring and validation
•intelligence - Format/stack detection
•sync - Context synchronization
•ai - AI enhancement features
•help - Documentation
•trust - Trust validation
•file - File operations
•utility - Misc tools

Configuration Priority:

•Environment variable (FAF_MCP_SHOW_ADVANCED)
•Config file (~/.fafrc)
•Default (core only)

Philosophy

The Noodle Philosophy 🍜

•YAML noodles for AI (machine-readable)
•Converts to markdown/TXT for humans (human-readable)
•Interconnected context, not flat data

Format-First

•The format is the foundation
•Without .faf, there is no universal context
•Format-driven architecture

Official Stewardship

•Anthropic-approved MCP server (PR #2759 MERGED)
•Account Managers for all things .FAF in Anthropic ecosystem
•Governance responsibility for format specification

Brand Values

•NO BS ZONE - Only real stats, verified claims
•Championship Standards - <50ms performance, 1,000+ tests
•Free Forever - MIT license, open source
•Trust is Everything - Built on credibility
•Professional, Boring, Trusted - F1-grade engineering

Stats (Real, Verified - November 2025)

•11,000+ total downloads (CLI + MCP combined)
•5,000+ MCP downloads (weekly: 800+)
•6,000+ CLI downloads
•79 tests passing (57 MCP + 22 visibility)
•153+ formats validated (TURBO-CAT engine)
•<10ms tool filtering (5x better than 50ms target)
•Zero regressions in v2.8.0 release
•WJTTC Gold Certified - F1-inspired testing standards
•Anthropic-approved MCP server (Official steward)

Version History

•v3.1.1 - faf-cli latest
•v2.8.0 - MCP Tool Visibility System (CURRENT)
•v2.7.3 - Previous MCP stable
•v1.2.0 - project.faf standard naming

Resources

•Website: https://faf.one
•CLI npm: https://npmjs.com/package/faf-cli
•MCP npm: https://npmjs.com/package/claude-faf-mcp
•GitHub: https://github.com/Wolfe-Jam/faf-cli
•Homebrew: brew install faf-cli
•Chrome Extension: Chrome Web Store (Google approved)

Testing Standards

WJTTC (WolfeJam Technical & Testing Center)

•F1-Inspired testing methodology
•3 Tiers: Brake Systems, Engine Systems, Aerodynamics
•Philosophy: "We break things so others never have to know they were broken"
•All tests reported and documented
•Gold certification for production releases

Troubleshooting

MCP Server Not Loading

bash

# Check logs
tail -f ~/Library/Logs/Claude/mcp-server-claude-faf-mcp.log

# Verify config
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Test locally
node /path/to/claude-faf-mcp/dist/src/index.js

Tool Count Verification

bash

# Should show 21 core tools (default)
# Or 51 tools (advanced mode)
# Check console output when MCP loads

CLI Not Found

bash

# Install globally
npm install -g faf-cli

# Or via Homebrew
brew install faf-cli

# Verify installation
faf --version

Advanced Usage

Custom Config File

Create ~/.fafrc:

json

{
  "showAdvanced": true
}

Or key=value format:

code

FAF_SHOW_ADVANCED=true

Local Development

bash

# Use local build
{
  "mcpServers": {
    "faf": {
      "command": "node",
      "args": ["/path/to/claude-faf-mcp/dist/src/index.js"],
      "env": {
        "FAF_MCP_SHOW_ADVANCED": "false"
      }
    }
  }
}

Skill Control

To disable this skill temporarily:

bash

# Rename directory to disable
mv ~/.claude/skills/faf-expert ~/.claude/skills/faf-expert.disabled

To re-enable:

bash

# Rename back to enable
mv ~/.claude/skills/faf-expert.disabled ~/.claude/skills/faf-expert

Or just delete the directory to remove completely.

How to Get This Skill

Option 1: Manual Installation

•Copy this SKILL.md file
•Create directory: ~/.claude/skills/faf-expert/
•Save as: ~/.claude/skills/faf-expert/SKILL.md
•Restart Claude Code

Option 2: Git Clone (if published)

bash

# Coming soon - published skills repository
git clone [skills-repo] ~/.claude/skills/faf-expert

Option 3: From FAF CLI (future)

bash

# Planned feature
faf skill install faf-expert

Made with 🧡 by wolfejam.dev Official Anthropic MCP Steward Championship Edition v2.8.0 🏎️✨ IANA-Registered Format: application/vnd.faf+yaml