wolfe-jam/faf-skills/faf-expert

v: 1
needs: []
reads: ["the project's project.faf, when the question is about it"]
writes: []
network: []
publishes: false
done_when: "the question is answered, with the command, slot or file it concerns"
project: project.faf

project/
├── package.json     ← dependencies (npm reads this)
├── project.faf      ← AI context (any AI reads this)
├── CLAUDE.md        ← human docs (synced from .faf)
└── src/             ← code (guided by the context)

npm install -g faf-cli        # or: brew install wolfe-jam/faf/faf-cli
faf --version

claude mcp add faf -- npx -y claude-faf-mcp@7.0.1

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

faf auto     # 1. detect stack + language, seed context from your README
faf score    # 2. the % + exactly which slots are still empty
faf go       # 3. guided fill — answer only the gaps the AI can't source
faf score    # 4. 100% ✪
faf sync     # 5. push context → CLAUDE.md  (AGENTS.md: faf export --agents)

# The path to Trophy
faf auto                # detect + seed (fills what it can)
faf score               # AI-readiness % + the empty slots
faf go                  # guided fill — close the gaps
faf sync                # emit CLAUDE.md from the .faf
faf export --agents     # emit AGENTS.md from the .faf
 
# Anytime
faf init                # create a fresh project.faf
faf check               # validate structure (IANA-clean)
faf git <url>           # score any GitHub repo → .faf (shallow-clones to a temp dir)
faf formats             # browse the supported stacks
faf migrate             # upgrade an older .faf
faf export --copilot    # emit .github/copilot-instructions.md
faf taf setup           # wire up TAF test receipts (CI)

# The path to 100% ✪
faf_auto     → scan manifests (package.json, Cargo.toml, pyproject.toml…) + fill the .faf
faf_score    → 0–100% AI-readiness + tier + per-slot breakdown
faf_go       → the friendly front door — asks the 6 Ws
faf_sync     → sync .faf → CLAUDE.md (+ optionally AGENTS.md)
 
# Anytime
faf_init     → create a new project.faf (name, goal, language) + starting score
faf_context  → set / show the active project path faf_ calls resolve against
faf_doctor   → diagnose: empty / weak slots + how to fix each
faf_trust    → attest integrity: validity, score + a deterministic parity hash anyone can verify
faf_bench    → prove the .faf earns its place — the context's worth on THIS repo, falsifiably
faf_about    → explain the FAF format — project DNA for AI (IANA-registered)
 
# Project soul (.fafm) — memory across sessions
faf_etch     → remember a decision / gotcha / win to the .fafm
faf_recall   → recall memories from the .fafm, ranked by priority + recency

# project.faf — IANA application/vnd.faf+yaml
faf_version: "3.0"
 
project:                          # required
  name: modern-web-app
  goal: Real-time collaboration platform for distributed teams
  main_language: typescript
 
human_context:                    # the 6 Ws — the underivable half
  who: distributed product teams
  what: real-time collaboration tool
  why: remove the latency tax of async handoffs
  where: AWS (ECS)
  when: production, since 2026
  how: TypeScript · React · Node · PostgreSQL
 
stack:                            # auto-detected
  frontend: react
  backend: express
  database: postgresql
  runtime: node
  hosting: aws-ecs
  build: vite
  testing: vitest                 # informational — not one of the 33 scored slots
  cicd: github-actions

faf auto                    # 1. baseline: detect + seed
faf score                   # 2. see the empty slots
faf go                      # 3. close the gaps (guided)
faf check                   # 4. IANA compliance
faf sync                    # 5. emit CLAUDE.md
faf export --agents         #    and AGENTS.md
git add project.faf CLAUDE.md AGENTS.md && git commit -m "Add AI context (.faf)"

faf check                                   # is the .faf well-formed?
# re-check claude_desktop_config.json (see Quick start), then restart Claude
tail -f ~/Library/Logs/Claude/mcp-server-claude-faf-mcp.log

faf score          # shows the empty slots holding you back
faf go             # guided fill — close them to 100%