The Day We Added BORIS-FLOW

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?

Boris-Flow: The Test Suite

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

$ ./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.

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:

One format. Complete AI context. Zero drift.

Try It

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

The FAF Tier System

GOAL 🏆 100% then bi-sync for eternal Context-Mirroring

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
• 20,000+ - npm downloads