FAF Dogfooding Guide

Step 1: Create Your README

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

```bash
npm install -g my-awesome-cli
```

## Usage

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

Step 2: Add Basic Project Structure

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 (TypeScript, Python, Rust, Go)
• Package manager (npm, poetry, cargo, go modules)
• Project type (CLI, library, web-app)

Step 3: Generate project.faf

cd your-project
faf init

What happens:

• Reads your README (extracts WHO, WHAT, WHY, HOW)
• Detects project type from files (CLI, web-app, library, etc.)
• Detects stack from package.json/pyproject.toml/Cargo.toml
• Generates project.faf with honest initial score

Output:

✓ 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!

Step 4: Commit the Foundation

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

Why commit now:

• Records "birth DNA" (starting score)
• Shows AI context is first-class, not afterthought
• Foundation committed before implementation

Step 5: Build Your Project

Now write your actual implementation:

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

Benefits:

• AI assistants (Claude, Copilot, etc.) have context from day 1
• No "add docs later" technical debt
• Clear definition before implementation

Step 6: Auto-Detect New Context

After significant development, let Turbo-Cat discover what you've built:

faf auto

What it does:

• Turbo-Cat scans your codebase (153 format types)
• Detects test frameworks, build tools, config files
• Updates project.faf with discovered context
• Grows score from 42% → 78%

Example discoveries:

✓ 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%

Before release, fill remaining gaps through interactive Q&A:

faf go

Interactive questions:

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

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

? Who is the primary audience?
  › Developers
    End users
    Internal team

Step 8: Keep Context Fresh

Periodically update as your project evolves:

# After adding new features
faf auto

# Before releases
faf go

Your project.faf stays synchronized with your codebase.

TypeScript/Node.js

# Setup
npm init -y
npm install typescript @types/node

# Generate
faf init

# Detects: TypeScript, npm, Node.js

Python

# Setup
poetry init

# Generate
faf init

# Detects: Python, poetry

Rust

# Setup
cargo init

# Generate
faf init

# Detects: Rust, cargo, Native runtime

Go

# Setup
go mod init github.com/user/project

# Generate
faf init

# Detects: Go, go modules