FAF CLI v6.4.0

🏎️ FAF CLI v6.4.0

F1-Inspired Software Engineering - Making AI development better for everyone! 🏁

🚀 Installation

npm install -g faf-cli@v6.4.0

📋 Changes

• fix(test): strip ISO timestamps properly in determinism assertion (cb66be3)
• fix(test): correct false determinism assertion in sync.test.ts (6396be9)
• ci(release): propagate skip from Install to Performance Tests (70d17af)
• test(e2e): bump subprocess timeout 15s → 30s for Windows CI (9473d8b)
• ci(release): Performance Validation skip-with-warning when npm lacks the version (3085397)
• fix: cross-platform path handling — Windows production bugs (2e96f36)
• docs(readme): GLANCEME pass for v6.4.0 — The Foundation Edition (3c18197)
• ci(release): add Bun setup to all build/test jobs in release.yml (ae31446)
• docs(changelog): full scrub of "Bible-Grade" — WJTTC framing only (317c372)
• docs(changelog): scrub "Bible-Grade" framing from public copy (6ed4ccc)
• docs(changelog): strengthen v6.4.0 lede with positioning copy (e79668d)
• chore(release): v6.4.0 — The Foundation Edition (fbe727e)
• docs(changelog): amend v6.3.3 entry with Bible-Grade sweep + rename (67577ae)
• fix(git) + test: graceful handling of network failures — Phase D (94980e1)
• test(kernel): WJTTC kernel-boundary stress suite — Phase C (20292af)
• test(demo): bulk up command coverage 33% → 149% — Bible-grade phase A4 (090959d)
• test(go): bulk up command coverage 47% → 145% — Bible-grade phase A3 (634b100)
• test(sync): bulk up command coverage 32% → 132% — Bible-grade phase A2 (59e1024)
• test(ai): bulk up command coverage 25% → 116% — Bible-grade phase A1 (785a9a7)
• test: WJTTC Build Resilience suite — lock in 2026-04-28 lessons learned (3f80075)
• ci: drop v6 from trigger branches — v6 is now main (580698a)
• docs: CHANGELOG entry for v6.3.3 — build resilience + hygiene (97f6603)
• chore(deps): bump open 8.4.2 → ^11.0.0 (ESM) (f3978a0)
• revert: drop --sourcemap from build/compile scripts (f7927b2)
• chore: gitignore /faf and /cli.js.map (dcfea42)
• chore(deps): bump @anthropic-ai/sdk 0.74.0 → 0.91.1 (5f29345)
• chore(release): v6.3.3 — fix compile + bytecode + sourcemaps (1b2c20b)
• ci: add packed-tarball smoke test to Node Smoke job (0af0ade)
• fix: read --version from package.json instead of hardcoded constant (86281cf)
• test: add build-invariant tests to meta.test.ts (no hardcoded paths) (878b4b7)
• fix(test): set local git identity in temp repo for CI (093a356)
• ci: add Bun setup to Node Smoke Test job (55567e7)
• chore(deps): npm audit fix — yaml CVE → 0 vulnerabilities (5bcb738)
• ci: install typescript-eslint + make lint non-blocking (c87fc90)
• chore(deps): sync package-lock.json with package.json (76c6f35)
• ci: trigger Championship CI/CD on v6 branch (b8580ab)
• chore(release): v6.3.2 — pin Bun + bump TAF action (e96162e)
• chore(release): v6.3.1 — P0 build fix bundle (279d40f)
• ci: grant contents:write to github-release job (49d38e9)
• ci: add prepublish no-hardcode guard — enforce policy at the gate (d6c945d)
• fix: externalize faf-scoring-kernel + open in bun build — P0 install crash (cc00b71)
• docs: align README H1 tagline + add canonical credo (5b43834)

🎯 Quick Start

# Create .faf file for your project
faf init

# Check your AI context score
faf score

# Zero to 100% in one command
faf auto

📊 v6 — Built with Bun

• ⚡ Same toolchain as Claude Code
• 🧪 218 tests, 37 files
• 📦 290KB bundle
• 🏆 26 commands

🔗 Links

• 📦 NPM Package
• 🌐 Website
• 📝 Blog
• 🐛 Report Issues

---

🏁 Define. Build. Lock. Relax.

v6.3.0 — The Ghostty-Inspired Edition

Added

• Desktop notifications for Trophy unlocks, tier upgrades, and long-running command completion (faf auto, faf go, faf sync).
• OSC 9 escape sequence on TTY (Ghostty / iTerm2 / Wezterm / Kitty); silent no-op elsewhere.
• macOS preference: routes through terminal-notifier if installed (brew install terminal-notifier) for click-to-dismiss persistence when set to "Alerts" in System Settings → Notifications.
• 5-second duration guard on auto / sync so notifications fire only when the user has actually drifted away. Trophy and tier-upgrade always fire (rarity-gated).
• Opt-out: FAF_NO_NOTIFY=1. Force OSC 9 path: FAF_NOTIFY_OSC9=1.

V6 FAF New Era - The Standard for AI Context

faf-cli v6.0.10 — MCP Detection + Format 3.0

The biggest v6 release yet. MCP server detection, Python/Rust support, and format version 3.0.

MCP Server Detection

10 MCP frameworks architected. Your MCP server gets the right type, backend, and framework sub-type automatically:

#	Framework	Language	Projects
1	@modelcontextprotocol/sdk	TypeScript	claude-faf-mcp, grok-faf-mcp, faf-mcp
2	fastmcp	Python	gemini-faf-mcp (70% of MCP servers)
3	mcp (Python SDK)	Python	Official Anthropic SDK
4	rmcp	Rust	rust-faf-mcp
5-7	mcp-go, MCP .NET, FastMCP (TS)	Go, C#, TS	Signals ready

Real-World Results

Server	Before	After
claude-faf-mcp	44% cli	59% mcp
grok-faf-mcp	44% cli	59% mcp
gemini-faf-mcp	33% library	41% mcp

Also in This Release

• Format version 3.0 — all generated .faf files use faf_version: "3.0"
• Next.js over React — meta-frameworks supersede their base
• Python dep detection — FastAPI, Django, Flask, SQLAlchemy from pyproject.toml
• Cargo.toml dep detection — rmcp and Rust deps
• Project name from manifests — pyproject.toml and Cargo.toml, not folder name
• Sync never overwrites CLAUDE.md — stamps meta tag, preserves content
• Pre-commit lint hook — errors never reach CI

Numbers

• 375/375 tests — 27 new MCP WJTTC tests
• 95 KB package — 6 files
• 41 test files — 0 failures
• IANA registered — application/vnd.faf+yaml

Install

bunx faf-cli auto          # Bun
npx faf-cli auto           # npm
brew upgrade faf-cli       # Homebrew

---

FAF defines. AI consumes. 🏎️

v6.2.0 — The One Sentence Edition

The One Sentence Edition

One sentence in. Review. Sign off. 🏆

What's New

faf go — completely reimagined interview:

• ★ Opener: "In one sentence, what is this project designed to do?"
• AI thinking step: interprets your answer into meaningful who/what/why/where/when/how (requires ANTHROPIC_API_KEY)
• Keyword extraction for who without API key (detects devs/engineers/teams/users)
• 6Ws sign-off loop: infers where/when/how from stack, human confirms or corrects by slot name
• 6Ws (human_context) always run first, stack slots after

faf git — smarter from the start:

• --keep flag: keeps cloned repo in cwd for faf auto / faf go follow-up
• README enrichment: extracts goal, detects build tool, sets slotignored for MCP servers
• Birth DNA: 41% → 60% from README scan alone

Tests

402/402 passing

FAF defines. MD instructs. AI codes.

v6.1.0 — The Go Rusty Python Edition

The Go Rusty Python Edition

Native type detection for Go, Rust, and Python projects.

Added

• Go module dependency parsing — detects MCP servers, Cobra CLIs, and services from `go.mod`
• `github.com/modelcontextprotocol/go-sdk` detected as MCP Go (covers github/github-mcp-server pattern)
• `github.com/mark3labs/mcp-go` detection now works (was silently missing for Go projects)
• Rust binary detection via `[[bin]]` in `Cargo.toml` (covers ripgrep-style projects)
• Rust CLI detection via `clap`, `argh`, `lexopt`, `structopt` + `src/main.rs`
• Python CLI detection via `console_scripts` / `[project.scripts]` in `pyproject.toml`
• Python library detection via `setup.py` marker
• Go CLI detection via Cobra dependency or `cmd/` + `main.go` pattern
• Default project type fallback changed from `library` → `service`
• WJTTC TIER 4 NATIVE — 12 new tests (#28–#39), 402/402 passing

FAF defines. MD instructs. AI codes.

v5.2.0 — FAFb WASM + Mk4 Renames + Tri-sync Topics

What's New

FAFb Compile/Decompile

• faf compile and faf decompile now live in the CLI
• Powered by faf-scoring-kernel (WASM) — no external binary needed
• .faf → .fafb binary compilation, .fafb → .faf decompilation

Mk4 Slot Renames (6)

• frontend→framework, css_framework→css, state_management→state
• api_type→api, database→db, package_manager→pkg_manager
• Full backward compatibility — 36k+ existing .faf files score identically
• WASM kernel bridge translates Mk4→old names for Rust kernel compat

Tri-sync Topic Files

• Claude Code native memory format with proper frontmatter
• 6 topic types: project, stack, context, preferences, key_files, state
• faf ram export and faf bi-sync --ram write topic files

Tests

• 1184/1184 passing (up from 1143)
• 52 test suites
• 21 new WJTTC Mk4 rename tests across 7 tiers
• 20 new topic writer tests
• FAFb verified with both old and Mk4 name sets

v5.1.0 — The FAFb Edition

The FAFb Edition

faf compile turns your .faf into a .fafb binary — CRC32 sealed, deterministic, portable. Same compiler that runs in the browser (322KB WASM) now runs from the CLI. YAML is source code. FAFb is the compiled output.

What's New

• faf compile — .faf → .fafb binary via WASM kernel (no external binary needed)
• faf decompile — .fafb → JSON inspection
• Mk4 Slot Renames — 6 canonical names aligned with Mk4 engine (full backward compat)
• Tri-sync Topic Files — Claude Code native memory format (6 topic types)
• README restructured — 684 → 164 lines, content moved to docs/

Numbers

• 1,184/1,184 tests passing (52 suites)
• v5.1.0 — from 5.0.6
• 855KB package size

Install

bunx faf-cli compile              # Bun
npx faf-cli compile               # npm
brew upgrade faf-cli && faf compile  # Homebrew

Links

• Blog: The Compiler is the Spec
• npm
• CHANGELOG

v5.0.6 — Bun Compiled Binaries

faf-cli v5.0.6 — Standalone Binaries

Zero runtime dependencies. One download, it works.

What's New

• bun build --compile produces standalone faf-cli binaries
• Same pattern as Claude Code — single executable, no Node/Bun required
• All Top 6 commands verified: init, git, auto, go, bi-sync, score
• 1,143/1,143 tests passing

Binaries

Platform	File	Size
macOS (Apple Silicon)	faf-darwin-arm64	60MB
macOS (Intel)	faf-darwin-x64	66MB
Linux (x64)	faf-linux-x64	102MB
Windows (x64)	faf-windows-x64.exe	113MB

Usage

# Download for your platform, then:
chmod +x faf-darwin-arm64   # macOS/Linux only
./faf-darwin-arm64 auto     # Run any faf command

Still Available

• npm install -g faf-cli (npm)
• brew install wolfe-jam/faf/faf-cli (Homebrew)
• bunx faf-cli auto (zero install)

Built with Bun 1.3.5. MIT License.

v5.0.1 - The RAM Edition

v5.0.1

Changed

• README rewritten for v5.0.0 RAM Edition — added 3Ws/6Ws teaching, tri-sync section, sync comparison table, blog link
• Core commands table updated with tri-sync, ram, pro
• 6Ws sections reordered to canonical order (WHO, WHAT, WHY, WHERE, WHEN, HOW)
• Added grok-faf-mcp and gemini-faf-mcp to Ecosystem and CLI vs MCP table
• Three AI platforms, one format

Blog post: https://faf.one/blog/ram-edition

v4.3.0 - GH API Truth + Slot-Ignore Fixes

• New function: extractFromLanguages() in faf-git-generator.ts

• Slot-Ignore System Fixed - Scoring now works correctly

  • Corrected formula: (filled + ignored) / 21 * 100
  • Fixed: Slots are 'slotignored' only when truly non-applicable to project type
  • Previously: Everything undetected was marked 'slotignored' (inflated scores)
  • Now: Accurate scoring that reflects what's actually filled vs ignored
  • New utility: src/utils/slot-counter.ts

• Clean Output Format - No synthetic scores, just honest status

  • Shows "No .faf file" instead of synthetic baseline score
  • Clear transformation: None → AI-ready with complete context
  • Defensible, provable, honest

📈 Results

Universal language support (achieved):

• React (JavaScript): 100% 🏆 Trophy
• Vue (JavaScript): 100% 🏆 Trophy
• Next.js (Full-stack): 100% 🏆 Trophy
• whisper.cpp (C++): 100% 🏆 Trophy
• Works across ALL languages and ecosystems

📚 Documentation

• README - Added project.faf screenshot showing file in context
  • Visual explainer: "just another file helping you code"
  • Positioned near top for immediate understanding
  • Shows project.faf alongside package.json and README.md

🎯 Positioning

FAF GIT is the killer feature:

• Primary workflow: npx faf-cli git <url> (no install needed)
• Pro workflow: npm install -g faf-cli then faf git <url>
• Works on ANY public GitHub repo
• 2 seconds to AI-ready context
• No cloning, no setup, just instant results

[4.2.2] - 2026-02-08 — Context Quality Edition 🎯

🎯 Slot-Ignore System (Documentation)

The perfect way to handle app-types - Now properly documented.

✨ What's New

• Slot-ignore mechanism - Comprehensive documentation added
  • Full specification in docs/SLOT-IGNORE.md
  • Quick reference in docs/SLOT-IGNORE-QUICK-REF.md
  • Like .gitignore for files, slot-ignore for context slots
  • Formula: (Filled + Ignored) / 21 = 100%

✨ Improvements

• 6 Ws extraction - Transformed human context extraction
  • WHO: Checks package.json author first (TIER 1 authoritative)
  • WHAT: package.json description now TIER 1 (was TIER 2)
  • WHY: Targets Mission sections, uses keywords as fallback
  • WHERE: npm packages → "npm registry + GitHub" (authoritative)