New Project Guide
Run faf. Answer what it asks. Context grows.
Context before code. README optional — faf go asks the 6 Ws.
Ways to 100%
Three paths. Same honest score. Pick your friction level.
faf git <url> ~2s · no clonefaf auto Turbo-Cat fills stack✪ Often 100% already — else faf gofaf init Extract from filesfaf auto 30% → 80%faf go 6 Ws if needed → 100% ✪faf readme or /6ws · optionalfaf init Commit foundationfaf auto → go Grow · polishGreat README is good discipline — not a gate. faf go fills missing 6 Ws when you're
stuck at 80–90%.
What FAF needs
Sourced context
Repo files, stack detection, or your answers — not a blank repo. FAF scores honestly; it doesn't invent.
project.faf
Structured YAML — machines read it, every AI reads it. The single source of truth.
README optional
Human prose helps, but faf readme, /6ws, or faf go can author what you need without writer's block.
README generation tools
Don't have a README yet? Two easy options:
Web tool: The 6 Ws
Fill out a simple form answering who/what/why/where/when/how. Copy the generated README.
faf.one/6ws →CLI tool
Interactive command-line tool that asks the 6 Ws and generates a README for you.
faf readmeAsks questions, writes README.md instantly
The core loop
init → auto → go. Same loop every time.
Initial Extraction
faf init OR faf git
Decision: choose your path
Have a GitHub repo URL?
npx faf-cli git https://github.com/facebook/react2 seconds → 30–50% score. No clone needed.
OR
Working locally?
faf initExtracts from local files (README, package.json, etc.)
Auto-Enhance
faf auto
faf auto- Turbo-Cat discovers 153+ format types
- Auto-fills detected stack slots
- Grows score from 30% → 80%
- Zero questions asked — fully automated
The Last 10–20%
faf go
faf go- Usually fills 1–2 missing 6 Ws (who/what/why/where/when/how)
- Stack detection is robust — blocker is human context
- 80–90% → 100% ✪ Trophy
- Skip if
faf autoalready got you to 100%
Score progression
| Step | Command | Score | What happens |
|---|---|---|---|
| 1 | faf init or faf git | 30–50% | Initial extraction from README + package files |
| 2 | faf auto | 80% | Turbo-Cat auto-discovers formats and fills slots |
| 3 | faf go | 100% ✪ | Interactive polish to championship grade |
AI-specific context files
Prose for each AI. project.faf sits under all of them — ever-present.
AGENTS.md
Universal agents format
faf bi-syncCLAUDE.md
For Anthropic Claude
faf bi-syncGEMINI.md
For Google Gemini
faf gemini.cursorrules
For Cursor IDE
faf bi-syncproject.faf
Source of truth — machines and every AI read it. AI-specific files are authored from it.
Always authoredCommon mistakes
Skipping the core loop
faf init
# Stop here, start coding
# Score: 30% (incomplete)Problem: Missing 70% of potential context. faf auto and faf go are free wins.
Using faf init on GitHub repos
git clone https://github.com/facebook/react
cd react
faf init # Slow! Wrong tool!Problem: Use faf git instead — no clone needed, 2 seconds.
Full core loop
faf init # or: faf git <url>
faf auto
faf go
# Result: 100% ✪Result: Championship-grade AI context in 3 commands.
Quick reference
What blocks 100%?
Stack detection is robust — faf auto handles most of it. Well-documented repos
via faf git can hit 100% without faf go.
When stuck at 80–90%: Almost always 1–2 missing 6 Ws (who/what/why). You
don't need a great README — faf go asks targeted questions and you're at 100%.
The decision tree
- Have a GitHub URL? →
faf git(might be 100% already) - Working locally? →
faf initthenfaf auto - Want to polish? →
faf go(if not already 100%)
One-liner
faf init → faf auto → faf go = 100% ✪