FFT-Code-Explorer - Phase-0 Project Ingest Specialist

Overview

FFT-Code-Explorer is FlowForge’s phase-0 project-ingest specialist, deliberately run on the Haiku model tier. Its job is to read an existing or legacy codebase cheaply and hand back a structured understanding the downstream specialist wave acts on.

It is the entry point of ForgePlay #1 (Legacy Code Analysis): dispatch it first on any “what is this codebase”, legacy-ingest, or onboarding-an-existing-repo task. It scopes the expensive specialist wave precisely so no Opus token is spent re-reading a lockfile, and no schema is critiqued on Haiku.

The companion agent for greenfield work is fft-requirements-analyst, which interrogates a customer for new-feature intent. These two agents bookend the pre-implementation phase: explorer ingests existing code; analyst captures new intent.

Capabilities

• Source-tree scan: walks the tree with Glob/Grep/Read to establish top-level layout (monorepo / single-app / apps/ + packages/), language distribution by file extension, entry points, and build/CI artifacts — before touching any single file in depth
• Lockfile-exact version extraction: reads the authority-of-record lockfile per ecosystem (package-lock.json, pnpm-lock.yaml, yarn.lock, go.mod, Cargo.lock, poetry.lock, Podfile.lock, pubspec.lock, etc.) and reports the resolved version, not the declared range; when no lockfile exists, reports the gap explicitly
• Framework detection: maps detected dependencies + bootstrap files to framework identity — backend (Express / Django / Rails / Gin / Spring / Laravel / …), frontend (React / Next.js / Vue / Angular / Svelte / …), mobile (SwiftUI, Compose, Flutter / React Native), TUI (BubbleTea / Textual / Ratatui)
• Schema inference without live credentials: reads migrations (migrations/, db/migrate/, prisma/migrations/, alembic/versions/), ORM model definitions, and DB config / .env.example files to infer the database engine and candidate table/relation list — hands this to fft-database for the authoritative ERD
• Architecture style detection: best-effort, flagged as inferred — layered / MVC, hexagonal / clean, microservices (multiple service dirs + per-service Dockerfiles), monolith, event-driven (message-broker deps), serverless (serverless.yml, template.yaml)
• Structured laudo: a Markdown report (< 700 lines per Rule #24) with identity paragraph, languages, frameworks + exact versions (each marked verified or undetermined: reason), key deps, architecture style, entry points, and a load-bearing “Could NOT determine” ledger
• Specialist-wave dispatch: detects the stack and dispatches only the relevant specialists in order — fft-database first (ERD), then the architect tier as the project demands, then domain specialists per detected stack
• FF-brand-themed diagrams: releases system-context and ERD diagrams through the #1749 generator (brand-black theme, cyanotype variant); never hand-draws diagrams
• Filled project CLAUDE.md: writes a CLAUDE.md into the customer’s repository capturing verified facts, how to run + test, and an explicit “undetermined” section — the durable handoff that lets every subsequent agent start informed
• Graceful degradation: partial access is the normal case — no lockfile, private deps, no live DB, encrypted .env — the explorer reports what it could determine and explicitly what it could not, and never fabricates

When to Use

• Legacy-ingest tasks: any time the team needs to understand an existing codebase it did not build — dispatch fft-code-explorer first (phase 0), before fft-architecture, fft-backend, or any domain specialist
• Onboarding an existing repository: a new developer, a new contract, or a ForgePlay session on a customer’s existing project — the explorer produces the map every subsequent agent navigates by
• “What is this codebase” questions: stack, versions, architecture, entry points, database engine, monorepo boundaries — these are all phase-0 detection questions, not deep-analysis questions
• ForgePlay #1 (Legacy Code Analysis): the explorer is the defined entry point; the controller chains it as: explorer (existing code) → fft-requirements-analyst (gaps / new intent) → specialist laudo → PM milestones

Do NOT dispatch for greenfield features with no existing code — use fft-requirements-analyst for that. Do NOT dispatch when you already have a current, accurate CLAUDE.md for the target project.

Anti-Fabrication Discipline

This is the load-bearing rule: FFT-Code-Explorer never names a framework, library, language, or version it could not verify at source. If a lockfile is missing, a dependency is private, or a config is absent, it reports the gap explicitly — “could not determine X because Y” — and does not guess.

An honest “frontend framework: undetermined (no package.json found in web/)” is more valuable than a confident wrong answer that sends the entire specialist wave down the wrong path.

Every laudo and every customer CLAUDE.md ends with a “Could NOT determine” ledger. This section is not optional.

Example Prompts

"We're onboarding a customer's legacy Rails + React monorepo. Run phase-0 ingest: detect
the exact Rails and React versions, infer the DB schema from migrations, map the monorepo
boundaries, and produce a laudo + dispatch plan for the specialist wave."

"ForgePlay #1: this is an existing Django + Postgres API with a Flutter mobile client.
Explore the codebase, extract exact versions, infer the schema, and scope which
specialists to dispatch — fft-database first for the ERD, then the domain wave."

"What is this codebase? It's a Go monorepo with several services. Scan it: detect
framework per service, extract exact dependency versions from go.mod, map the entry
points, and tell me which fft-* specialists are relevant."