Standard Workflow

Dogfooding guide for any project type

TypeScript Python Rust Go

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

You can't generate meaningful AI context from an empty repository. Start with what you're building, then add context, then code.

Quick start

Prerequisites

npm install -g faf-cli

The 8-step workflow

Step 1: Create your README

When: Day 1, before any code Time: 5–10 minutes

Write a README that answers:

WHAT — What does this project do?
WHY — Why does it exist? What problem does it solve?
WHO — Who is building it? Who is it for?
HOW — How do you install/use it?

# Example README.md

# My Awesome CLI

A command-line tool for managing project tasks efficiently.

## Why

Tired of juggling multiple task managers? This CLI brings everything into your terminal.

## Installation

npm install -g my-awesome-cli

## Usage

my-cli add "Write documentation"
my-cli list

Result: Human-readable project definition

Step 2: Add basic project structure

When: After README

Create your language-specific configuration:

# For TypeScript/JavaScript:
npm init -y

# For Python:
poetry init  # or create pyproject.toml

# For Rust:
cargo init

# For Go:
go mod init github.com/user/project

This gives faf-cli the context it needs to detect language, package manager, and project type.

Step 3: Generate project.faf

Command: faf init Expected score: 30–50%

cd your-project
faf init

What happens:

Reads your README (extracts WHO, WHAT, WHY, HOW)
Detects project type from files
Detects stack from package files
Generates project.faf with honest initial score

✓ Generated project.faf (42% - 9/21 slots filled)

Missing context:
  - Database (if applicable)
  - CI/CD pipeline
  - Hosting platform

Run `faf go` to improve your score!

Result: project.faf created with 30–50% score (honest baseline)

Step 4: Commit the foundation

When: Before writing implementation code

git add README.md package.json project.faf
git commit -m "Add project foundation

- README defines purpose and usage
- package.json defines dependencies
- project.faf provides AI context (42%)

AI-ready before first line of code."

Records birth DNA, shows AI context is first-class, foundation committed before implementation.

Step 5: Build your project

When: After foundation committed

src/
  index.ts
  cli.ts
  commands/
tests/
  cli.test.ts

AI assistants have context from day 1. No "add docs later" technical debt.

Step 6: Auto-detect new context

Command: faf auto Expected score: 70–85%

faf auto

Turbo-Cat scans your codebase (153 format types), detects frameworks and config, grows score 42% → 78%.

✓ Found: vitest.config.ts → Testing: Vitest
✓ Found: .github/workflows → CI/CD: GitHub Actions
✓ Found: vercel.json → Hosting: Vercel

Updated project.faf (78% - 16/21 slots filled)

Step 7: Refine to 100%

Command: faf go Target: 85%+ (◇ Bronze) or 100% (✪ Trophy)

faf go

? What database does this project use?
  › PostgreSQL
    MongoDB
    None

? Where is this deployed?
  › Vercel
    AWS
    Self-hosted

Result: 85%+ ◇ Bronze (production-ready) or 100% ✪ Trophy (perfect)

Step 8: Keep context fresh

Frequency: Before major releases

# After adding new features
faf auto

# Before releases
faf go

Your project.faf stays synchronized with your codebase.

Score progression

Stage	Score	Tier	Meaning
After `faf init`	30–50%	● Yellow	Honest baseline
After `faf auto`	70–85%	◇ Bronze	Production-ready
After `faf go`	85–100%	★ Gold / ✪ Trophy	Excellent / Perfect

Common mistakes

✗ Code first, docs later

# Write 1000 lines of code...
git commit -m "Initial implementation"

# Then try to add docs
echo "# Project" > README.md
faf init  # Score: 15%

Problem: Low score, missed context during development

✗ Empty repo init

mkdir new-project && cd new-project
git init
faf init  # Score: 0% - Nothing to extract!

Problem: Can't extract WHO/WHAT/WHY from empty repo

✗ Never update

faf init  # 6 months ago...
# Add Vite, Vitest, Vercel, tests...
# Never run faf auto
# project.faf still shows 42% (outdated!)

Problem: Stale context doesn't reflect current project

✓ Correct workflow

# 1. README (WHO/WHAT/WHY)
# 2. Structure — npm init -y
# 3. Generate .faf (42%) — faf init
# 4. Commit foundation
# 5. Build (weeks of work...)
# 6. Update context (78%) — faf auto
# 7. Refine before v1.0 (100%) — faf go

Result: Perfect context from day 1, grows with your project

Language-specific examples

TypeScript / Node.js

npm init -y
npm install typescript @types/node
faf init
# Detects: TypeScript, npm, Node.js

Python

poetry init
faf init
# Detects: Python, poetry

Rust

cargo init
faf init
# Detects: Rust, cargo, Native runtime

Go

go mod init github.com/user/project
faf init
# Detects: Go, go modules

FAQ

When exactly should I run `faf init`?

After you have a README and basic structure (package.json, Cargo.toml, etc.), but before writing implementation code. This gives you 30–50% initial context.

Can I edit project.faf manually?

Yes. It's just YAML. But faf go provides a nicer interactive UI.

Do I need CLAUDE.md?

No. project.faf works with all AIs. CLAUDE.md is optional for Claude-specific prose.

How often should I run `faf auto`?

After significant changes — new frameworks, deployment setup, testing added. Usually once mid-development and before releases.

Key takeaways

README first — Define what you're building (WHO/WHAT/WHY)
project.faf second — Generate AI context with faf init
Code third — Build with AI context from day 1
Let it grow — Use faf auto to detect new context
Refine before release — Use faf go to reach 85%+
Honest scores — 30% → 70% → 100% is normal progression
Keep it fresh — Update as your project evolves

Quick reference

Command	When	Purpose
`faf init`	After README + structure	Generate initial project.faf (30–50%)
`faf auto`	Mid-development	Auto-detect new context (→ 70–85%)
`faf go`	Before release	Interactive refinement (→ 100%)
`faf score`	Anytime	Check current score
`faf bi-sync`	Optional	Generate CLAUDE.md

Install: npm install -g faf-cli

Docs: faf.one