TL;DR: We studied how Boris Cherny (creator of Claude Code) structures his projects - subagents, slash commands, MCP servers, Bun runtime - and built a 12-test integration suite that validates all of it. Now .faf detects and preserves the complete Claude Code ecosystem. Every publish passes Boris-Flow or it doesn't ship.

📝 Revision Note

Originally published: January 7, 2026
Updated: February 3, 2026

Since launching Boris-Flow in January, we've integrated it into the WJTTC certification workflow and faf-cli documentation. This update adds practical guidance on when to run Boris-Flow and how it validates project structure before WJTTC Tier 8 certification. See the new "When to Run Boris-Flow" section below.

What's new: Workflow recommendations, WJTTC integration, pre-certification best practices.

The Problem

Claude Code has evolved. It's not just CLAUDE.md anymore. Modern Claude Code projects have:

.claude/agents/*.md - Specialized subagents for different tasks
.claude/commands/*.md - Custom slash commands
.claude/settings.json - Permissions and configuration
.mcp.json - MCP server integrations (Slack, BigQuery, Sentry)
Bun runtime detection (bun.lockb)

If your AI context format doesn't understand this structure, you're working with half a blueprint. Context drift is inevitable.

The Inspiration

Boris Cherny created Claude Code. His setup is the reference implementation:

5 subagents for specialized tasks
Custom slash commands for workflows
MCP servers for external services
Bun as the runtime
Everything wired together

We asked: what if .faf could detect all of this automatically? What if we could validate that detection with real tests?

The Insight

Don't guess what a Claude Code project looks like. Model it on the creator's actual setup. Then test against that model.

Boris-Flow: The Test Suite

12 integration tests that must pass before any faf-cli publish:

Boris-Flow integration tests running - all 12 tests passing

View full test output

$ ./tests/boris-flow.test.sh
🏎️BORIS-FLOW INTEGRATION TEST

🏎️ Using local build: /Users/wolfejam/FAF/cli/dist/cli.js

1️⃣ Testing --version...
✅ faf --version (got: 3.4.4)

2️⃣ Creating Claude Code project...
✅ Created Claude Code structure

3️⃣ Testing faf init...
✅ faf init created project.faf

4️⃣ Checking type detection...
✅ Detected CLI type (got: cli-ts)

5️⃣ Checking language detection...
✅ Language detected (got: TypeScript)

6️⃣ Checking Claude Code detection...
✅ claude_code section exists
✅ Claude Code detected: true
✅ Subagents detected (got: 2)

7️⃣ Testing faf auto...
✅ faf auto maintained score (67 → 67)

8️⃣ Filling human context...
✅ human-set commands succeeded

9️⃣ Testing final score...
✅ Final score is 100% (got: 100%)

🔟 Testing non-TTY safety...
✅ faf enhance safe in non-TTY (100 → 100)

🏆 BORIS-FLOW: ALL 12 TESTS PASSED

✅ Demo ready
✅ Safe to publish
   Final score: 100%

If any test fails, the publish stops. No exceptions.

What .faf Now Detects

Run faf init on a Claude Code project and the output includes:

claude_code:
  detected: true
  claude_md: true
  subagents:
    - code-reviewer
    - test-runner
    - docs-writer
  commands:
    - pubpro
    - deploy
  permissions:
    - Bash(npm:*)
    - Read(**)
  mcp_servers:
    - slack
    - bigquery

Complete metadata. Ready for any AI to understand your Claude Code setup instantly.

When to Run Boris-Flow

Boris-Flow isn't just for faf-cli maintainers — it's a validation tool for anyone using .faf files. Here are the key scenarios:

Scenario	Why Run Boris-Flow
Before `faf init`	Validates faf-cli installation works correctly on your machine
After major .faf changes	Re-validates project structure remains valid
Before WJTTC certification	Pre-validates .faf file for Tier 8 (FAF Documentation) tests
Before publishing	Ensures no regressions in faf-cli (maintainers only)
Team onboarding	Proves faf-cli works and demonstrates 100% scoring

Pre-Certification Workflow

WJTTC users can now validate their .faf files before running certification:

cd your-project faf init && faf auto faf score git clone https://github.com/Wolfe-Jam/faf-cli cd faf-cli && ./tests/boris-flow.test.sh cd ../your-project npx wjttc certify --mcp "npx your-server"

Boris-Flow validates the structure that WJTTC Tier 8 tests. Running it first helps ensure you pass Tier 8.

Where it's documented:

WJTTC README - Pre-certification best practices
faf-cli README - Complete Boris-Flow documentation

Live Bi-Sync Demo

We also shipped faf demo sync - a live demonstration of bidirectional sync:

$ faf demo sync

┌─────────────────────────────────────────────┐
│ FAF BI-SYNC DEMO                            │
│ Live demonstration of .faf <-> CLAUDE.md sync│
└─────────────────────────────────────────────┘

Starting demo...
├─ Files detected:
│  📄 project.faf
│  CLAUDE.md

T=39.589s  🌀 CLAUDE.md  -> editing...
T=40.092s  🔗 Change detected: "DEMO rule added"
T=40.602s  ⚡ project.faf synced (9ms)

T=41.603s  🌀 project.faf  -> editing...
T=42.108s  🔗 Change detected: "demo_marker updated"
T=42.610s  ⚡ CLAUDE.md synced (1ms)

T=43.611s  🌀 CLAUDE.md  -> editing...
T=44.111s  🔗 Change detected: "context update"
T=44.612s  ⚡ project.faf synced (1ms)

3 changes  ·  3 syncs  ·  avg 4ms  ·  0 conflicts

Demo complete - no files changed.

✨ Try: faf bi-sync - Set up real bi-sync for your project

Every faf-cli user can now demo bi-sync to their team. Built-in evangelism.

Try the interactive web demo →

Why This Matters

Context drift happens when your AI doesn't know your project structure. With Boris-Flow:

Before	After
AI guesses your setup	AI knows your exact Claude Code structure
Subagents invisible	Subagents listed by name
MCP servers unknown	MCP servers detected
Runtime assumed	Bun/Node detected from lockfile
Permissions unclear	Permissions extracted from settings.json

One format. Complete AI context. Zero drift.

Try It

brew install faf-cli faf init && faf auto

That's it. Your Claude Code structure is now captured in project.faf.

For the brave:

cd your-project npx faf-cli yolo

Downloads faf-cli via npx and runs yolo — init + auto + aggressive extraction in one command. May take a minute on first run.

Get Started

Install faf-cli and run Boris-Flow yourself.

GitHub

View Tests

See the 12 tests that validate every publish.

boris-flow.test.sh

The FAF Tier System

At FAF-Score 100% AI is optimized. No more guessing, peak AI performance is activated 🏆 Gold Code mode enabled

Score	Tier	Meaning
🏆 100%	Gold Code	AI Optimized
🥇 99%+	Gold	Exceptional
🥈 95%+	Silver	Excellent
🥉 85%+	Bronze	Production ready
🟢 70%+	Green	Good foundation
🟡 55%+	Yellow	Needs work
🔴 <55%	Red	Critical gaps

The Numbers

v3.4.4 - Released January 7, 2026
12/12 - Boris-Flow tests pass
609/629 - Full test suite (20 intentionally skipped)
100% - FAF score on faf-cli itself
4ms - Average bi-sync time
21,000+ - npm downloads