Reversa is a specification reverse-engineering framework that transforms legacy systems into executable specifications for AI coding agents. Created by developer 'sandeco' and released under MIT license, the project has gained 318 stars on GitHub since its April 2026 launch.
Legacy Systems Hide Critical Knowledge AI Agents Need
Legacy codebases contain years of accumulated business rules, architectural decisions, and critical logic—but this knowledge remains inaccessible to AI agents. While AI tools excel at building new systems from specifications, they lack understanding of what cannot be broken in existing systems. Reversa addresses this by extracting and formalizing tacit knowledge into operational contracts that AI agents can understand.
Five-Phase Pipeline Extracts System Intelligence
The framework employs specialized AI agents coordinated by a central Reversa controller:
- Reconnaissance (Scout): Maps folder structure, programming languages, frameworks, and dependencies
- Excavation (Archaeologist): Analyzes algorithms, control flows, and data structures module-by-module
- Interpretation (Detective): Extracts business rules, architectural decisions, and state machines
- Generation (Architect & Writer): Synthesizes C4 diagrams, ERDs, and specifications with code traceability
- Review (Reviewer): Validates specifications and identifies inconsistencies
Optional specialized agents handle databases, UI design systems, dynamic tracing, and interface documentation.
Generates Comprehensive Documentation With Confidence Ratings
Reversa outputs a complete documentation suite in the _reversa_sdd/ directory including:
- Architectural diagrams using C4 model and entity-relationship diagrams
- Component specifications with direct code references
- Business domain documentation and state machines
- Confidence ratings (🟢 Confirmed, 🟡 Inferred, 🔴 Gap) for each specification
- Traceability matrices linking code to specifications
The framework works with Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Cline, GitHub Copilot, Amazon Q Developer, and other AI coding tools. Each engine receives specifications through platform-specific configuration files.
Safety Features Protect Existing Code
Reversa never modifies or deletes existing project files. All agent writes are restricted to .reversa/ and output directories. SHA-256 manifests ensure safe updates without overwriting customizations, and stateful checkpoints enable session resumption.
Developers install Reversa using npx reversa install and activate it via /reversa commands within their AI agent environment. The framework requires Node.js 18+ and is written primarily in JavaScript.
Key Takeaways
- Reversa transforms legacy code into formal specifications that AI agents can understand, with 318 GitHub stars since April 2026
- The framework uses a five-phase pipeline with specialized AI agents to extract business rules, architectural decisions, and system constraints
- All documentation includes confidence ratings and code traceability, ensuring AI agents know what can and cannot be changed
- Safety features prevent any modification of existing code—all outputs go to dedicated directories
- Compatible with major AI coding tools including Claude Code, Cursor, GitHub Copilot, and Amazon Q Developer