Teaching AI agents to read legacy code before they break it

What it does

Reversa is a specification reverse-engineering framework that drops into an existing codebase and coordinates a team of specialized AI agents to map structure, excavate modules, and extract implicit business rules. It synthesizes these findings into traceable operational contracts—specifications designed for AI consumption, not human reading—that tell coding agents what they must preserve when evolving or migrating the system. The framework keeps its distance from your original files, writing all analysis and output to isolated directories.

The interesting bit

The framework casts reverse engineering as a five-phase archaeological expedition, with agents playing roles like Scout, Archaeologist, Detective, and Architect. It also enforces strict immutability on the legacy project, which is either a thoughtful safety measure or a quiet admission that letting autonomous LLMs dig through production code is inherently unnerving.

Key highlights

• Discovery pipeline runs through five phases (Reconnaissance, Excavation, Interpretation, Generation, Review) with resumable checkpoints saved to disk
• Supports greenfield ideation, forward feature evolution, stack migration, and effort pricing through separate agent teams
• Detects which AI engine is present and adapts entry commands accordingly for Claude Code, Codex, Cursor, and others
• Optional agents include a Soul Extractor for executive summaries and a Visor that documents interfaces from screenshots without a running system
• Outputs are operational contracts with code traceability, not documentation meant for humans

Caveats

• The README explicitly warns users to back up their project before starting, noting that “AI agents can make mistakes” despite immutability guarantees
• Reversa is essentially an orchestration layer; all intelligence is delegated to the AI agents already present in your environment, and the framework itself does not ship with its own analysis engine
• Several sections describing the Migration and Pricing teams are truncated in the provided README, so complete capabilities beyond Discovery and Forward agents remain unclear

Verdict

Worth exploring if you need to hand a legacy codebase to an AI agent without watching it collapse in confusion. Skip it if you expect a standalone analysis engine—this is orchestration glue for the AI tools you already have.