faf-wizard git:20261021.6fda463A

Immutable. This exact content never changes and is served at /api/v1/blob/0045c5a570ed66ac.

---
name: faf-wizard
description: 'Use when someone wants project context set up for them: "set up Claude for this repo", "onboard AI to this codebase", "make me a project.faf". Detects the stack, reads what already exists (README, docs, an existing CLAUDE.md or .cursorrules), writes project.faf and scores it. Works on new, legacy or inherited code. Turns the CLAUDE.md you already have into the structured facts behind it: GOOD to BETTER, done for you.'
license: MIT
---

# 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 have no AI-context.** React. Kubernetes. Rails. Django — none ship a `.faf`. Detection alone gets React to ~56%; the human half (who / why / where) that grounds an AI is missing. **That's the gap.**

| 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. **Every `.faf` is scored against the same 33 slots**: faf-cli fills the 21 base slots and marks the 12 enterprise slots `slotignored` unless your app type uses them. `app_type` selects which are *active*; the rest are `slotignored` (never counted against you). Detection fills the stack; the human supplies the underivable bits (`project.name`/`goal` + the 6 Ws). `human_context.how` is **how it's built** (sourced from the stack), not AI preferences.

```yaml
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
  backend: express
  api_type: rest
  runtime: node
  database: postgresql
  hosting: vercel
  build: vite
  testing: vitest                 # informational — not one of the 33 scored slots
  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: 13/15 active slots
slotignored: the slots that don't apply to this app_type (never counted)

To reach 100% ✪:
  - Add deployment details
  - Document the testing strategy
  - Fill the last Ws the AI couldn't source
```

**The target is 100% ✪ — Bronze is the floor, not the finish line.** At 100% every *active* slot is filled and the AI starts every session already knowing the project.

## Tier System

| Score | Tier | Symbol | Status |
|-------|------|--------|--------|
| 100% | Trophy | ✪ | AI is optimized to code |
| 99% | Gold | ★ | Exceptional |
| 95% | Silver | ◆ | Top tier |
| 85% | Bronze | ◇ | Production ready |
| 70% | Green | ● | Solid foundation |
| 55% | Yellow | ● | Needs improvement |
| 1% | Red | ○ | Major work needed |
| 0% | White | ♡ | Empty |

**Target: 100% ✪.** Bronze (◇ 85%) is the floor where AI collaboration becomes productive — Trophy is the goal: every *active* slot filled, the AI fully grounded from session one.

## 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 200 lines

## Credentials

- **IANA Media Type:** `application/vnd.faf+yaml`
- Listed in **modelcontextprotocol/servers** (#2759, merged 2025-10-17)
- **Website:** https://faf.one