Philosophy

"README first, .faf second, code third."

Foundation doesn't mean empty. Foundation means you know WHAT you're building.

The Workflow

Step 1: Define Your Project (README.md)

When: Day 1, before any code

What:

# Create repo
git init

# Write README
cat > README.md << 'EOF'
# faf-generator-wasm

Rust WASM generator for FAF (Foundational AI-context Format).

Generate project.faf files in the browser or at the edge.

## Mission

Build a Rust WASM generator that matches faf-cli v4.2.1 output exactly.
EOF

Why:

Defines WHO, WHAT, WHY
Gives AI context to extract from
Can't generate meaningful .faf from empty repo

Result: Foundation in prose (human-readable)

Step 2: Add Basic Structure

When: After README, before implementation

# Add language-specific structure
Cargo.toml          # For Rust
# OR
package.json        # For JavaScript/TypeScript
# OR
pyproject.toml      # For Python

Why:

Detects project type (cli, web-app, ml-research, etc.)
Detects stack (Rust, TypeScript, Python, etc.)
Detects package manager (cargo, npm, poetry, etc.)

Result: Structure reveals intent

Step 3: Generate project.faf

When: After README + structure, before implementation

Score: 30-50% (honest starting point)

Command:

faf init

What it does:

Reads README.md (extracts 6 Ws)
Reads package files (detects stack)
Generates project.faf (YAML)

Result: AI-readable context file (30-50% score)

Step 4: Generate CLAUDE.mdOptional

When: After project.faf exists

Command:

faf bi-sync

What it does:

Reads project.faf
Generates CLAUDE.md (prose version)
Establishes bi-directional sync

Why optional:

Only needed if working primarily with Claude
project.faf alone works with ALL AIs
CLAUDE.md is human-readable version

Step 5: Commit the Foundation

When: After .faf (and optionally CLAUDE.md) generated

git add README.md Cargo.toml project.faf CLAUDE.md
git commit -m "Add project foundation

- README defines purpose
- Cargo.toml defines structure
- project.faf provides AI context
- CLAUDE.md provides Claude-specific prose

AI-ready before first line of code."

Why:

Foundation is committed before implementation
Shows AI context is first-class, not afterthought
Birth DNA recorded (starting score)

Step 6: Build (Implementation)

When: After foundation committed

# Now write actual code
src/lib.rs
tests/
# etc.

Why:

Definition before implementation
AI has context from day 1 of coding
No "add docs later" technical debt

Step 7: Grow Context (During Development)

When: After significant progress

Score: 30% → 80%

Command:

faf auto

What it does:

Turbo-Cat discovers formats (153 types)
Fills detected stack slots
Grows score from 30% → 80%

Step 8: Refine (Before Release)

When: Before v1.0.0

Score: 85%+ (Bronze) or 100% (Trophy)

Command:

faf go

What it does:

Interactive questions
Fill remaining gaps
Human refinement
Reaches 85%+ 🥉 or 100% 🏆

Timing Summary

Step	File	When	Score
1	README.md	Day 1	-
2	Cargo.toml	Day 1-2	-
3	project.faf	After docs	30-50%
4	CLAUDE.md	Optional	-
5	Git commit	Before code	-
6	src/lib.rs	Implementation	-
7	faf auto	Mid-dev	80%
8	faf go	Pre-release	100%

Common Mistakes

❌ Wrong: Code First, Docs Later

# Write all the code
git add src/
git commit -m "Initial implementation"

# Oh yeah, should add docs
echo "# Project" > README.md
faf init  # Low score, missed context

Problem: AI has no context during development

❌ Wrong: Empty Repo .faf

git init
faf init  # Nothing to extract from!
# Score: 5% (basically empty)

Problem: Can't extract 6 Ws from empty repo

✅ Right: Definition → Documentation → Implementation

# 1. Define
README.md (WHO/WHAT/WHY)

# 2. Document for AI
faf init → project.faf (30-50%)

# 3. Build
src/lib.rs (code)

# 4. Grow
faf auto → 80%

Result: AI context available from day 1

Why This Order Matters

README first:

Forces you to articulate purpose
Human-readable definition
Can't fake it (you must know what you're building)

project.faf second:

AI-readable version of README context
Structured format (YAML)
Machine-parseable

Code third:

Implementation follows definition
AI has context to help from start
No documentation debt

Key Takeaways

Foundation ≠ Empty - You must know what you're building
README defines for humans - Write this first, always
project.faf defines for AI - Auto-extracted from README
CLAUDE.md is optional - Only if working with Claude primarily
Code comes last - Implementation follows definition
Context grows - 30% → 80% → 100% over time
Bi-sync keeps prose in sync - Edit either, both update

FAF Dogfooding Guide

Philosophy

The Workflow

Step 1: Define Your Project (README.md)

Step 2: Add Basic Structure

Step 3: Generate project.faf

Step 4: Generate CLAUDE.mdOptional

Step 5: Commit the Foundation

Step 6: Build (Implementation)

Step 7: Grow Context (During Development)

Step 8: Refine (Before Release)

Timing Summary

Common Mistakes

❌ Wrong: Code First, Docs Later

❌ Wrong: Empty Repo .faf

✅ Right: Definition → Documentation → Implementation

Why This Order Matters

Key Takeaways