FAF Wizard - Done For You

The pit crew. Point it at any project, get a scored .faf file back. See also: faf-expert — the mechanic's manual for when you want to understand every bolt.

What This Does

Generates a project.faf file for any codebase. You don't need to know the format — the wizard handles detection, generation, scoring, and reporting.

You: "Set up project context for this repo"
Wizard: Detects stack → generates project.faf → scores it → reports gaps

The Problem It Solves

Even famous repos score 0%. React. Kubernetes. Rails. Django. None have AI-context.

What exists	What it answers
README.md	"What does this do?" (for humans)
docs/	"How do I use this?" (for humans)
project.faf	"How should AI help build this?" (for AI)

Documentation tells humans how to use code. AI-context tells AI how to help you write it. They're not the same thing.

Works on ANY Project

Project State	What FAF Wizard Does
Brand new	Optimized AI context from line one
Legacy codebase	AI finally understands the archaeology
Famous OSS	Even React needs this (it doesn't have one)
Side project	Stop re-explaining every session
Client handoff	Portable context for any AI tool

Workflow

Step 1: Detect Stack

Look for manifest files:

• package.json → Node.js/TypeScript
• Cargo.toml → Rust
• pyproject.toml → Python
• go.mod → Go
• pom.xml → Java
• Gemfile → Ruby

No manifest? Still generate — ask user for stack info.

Step 2: Mine Existing Context

Pull signals from what exists:

• README.md (description, purpose)
• docs/ (architecture decisions)
• CLAUDE.md or .cursorrules (existing AI context — migrate it)
• Package manifests (dependencies reveal intent)
• Directory structure (architecture patterns)

Step 3: Generate project.faf

Create focused AI context at project root using Mk4 33-slot structure:

faf_version: "3.0"

project:
  name: my-project
  goal: One-line purpose
  main_language: typescript

human_context:
  who: Solo developer
  what: REST API for task management
  why: Learning project, portfolio piece
  where: Vercel (serverless)
  when: Started March 2026
  how: TypeScript, Express, PostgreSQL

stack:
  frontend: react
  css_framework: tailwind
  backend: express
  api_type: rest
  runtime: node
  database: postgresql
  hosting: vercel
  build: vite
  cicd: github-actions

Keep under 200 lines. Only what changes AI behavior.

Step 4: Score and Report

Generated: project.faf
AI-Readiness: 87% 🥉 Bronze — Production ready

Filled: 9/11 active slots
Ignored: 22 slots (not applicable for this project type)

To reach Silver (95%):
  - Add deployment details (+5%)
  - Document API patterns (+3%)

Tier System (Mk4)

Score	Tier	Emoji
100%	Trophy	🏆
99%+	Gold	🥇
95%+	Silver	🥈
85%+	Bronze	🥉
70%+	Green	🟢
55%+	Yellow	🟡
> 0%	Red	🔴
0%	White	🤍

Target: 🥉 Bronze (85%+). This is where AI collaboration becomes productive.

Migration

When CLAUDE.md or .cursorrules exist:

• Offer to migrate to .faf (portable format)
• .faf works in Cursor, Gemini, WARP, Windsurf — not just Claude
• YAML structure parses better than freeform markdown

Validation

Generated files must:

• Be valid YAML
• Have faf_version and project.name
• Contain NO secrets or credentials
• Stay under 500 lines

Credentials

• IANA Media Type: application/vnd.faf+yaml
• Anthropic MCP: Registry #2759 (merged)
• Website: https://faf.one