WASM Workflow

The right way to add AI context

Rust WASM faf-wasm-gen Browser / edge

"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

git init

# Write README (heredoc or editor)
# faf-wasm-gen
# Rust WASM generator for FAF
# Generate project.faf in the browser or at the edge

Defines WHO, WHAT, WHY. Gives AI context to extract from.

Result: Foundation in prose (human-readable)

Step 2: Add basic structure

When: After README, before implementation

Cargo.toml          # For Rust
# OR
package.json        # For JavaScript/TypeScript
# OR
pyproject.toml      # For Python

Detects project type, stack, and package manager.

Result: Structure reveals intent

Step 3: Generate project.faf

When: After README + structure Score: 30–50%

faf init

Reads README.md, reads package files, generates project.faf (YAML).

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

Step 4: Generate CLAUDE.md Optional

When: After project.faf exists

faf bi-sync

Only needed if working primarily with Claude. project.faf alone works with all AIs.

Step 5: Commit the foundation

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

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."

Step 6: Build (implementation)

When: After foundation committed

src/lib.rs
tests/
# etc.

Definition before implementation. AI has context from day 1 of coding.

Step 7: Grow context (during development)

When: After significant progress Score: 30% → 80%

faf auto

Turbo-Cat discovers formats (153 types), fills detected stack slots.

Step 8: Refine (before release)

When: Before v1.0.0 Target: 85%+ (◇ Bronze) or 100% (✪ Trophy)

faf go

Interactive questions, fill remaining gaps, human refinement.

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

✗ Code first, docs later

git add src/
git commit -m "Initial implementation"
echo "# Project" > README.md
faf init  # Low score, missed context

Problem: AI has no context during development

✗ Empty repo .faf

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

Problem: Can't extract 6 Ws from empty repo

✓ Definition → documentation → implementation

README.md (WHO/WHAT/WHY)
faf init → project.faf (30-50%)
src/lib.rs (code)
faf auto → 80%

Result: AI context available from day 1

Why this order matters

README first

Forces you to articulate purpose. Human-readable definition you can't fake.

project.faf second

AI-readable version of README context. Structured YAML, machine-parseable.

Code third

Implementation follows definition. AI has context to help from the start.

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

Status: Workflow documented

Tested on: faf-wasm-gen (Feb 7, 2026)

"AI needed a format, it got one — .faf"