wolfe-jam/faf-skills/faf-wizard

v: 1
needs:
  - "faf-cli on Node 22+ for the score (not installed: run `npx faf-cli score`)"
reads: [README.md, docs/, "CLAUDE.md or .cursorrules", package manifests, the directory structure]
writes: ["project.faf at the project root"]
network: ["registry.npmjs.org (read, only when npx fetches faf-cli)"]
publishes: false
done_when: "project.faf exists at the project root and has a score"
project: project.faf

<!-- faf:end -->

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.

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

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.

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

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