Reversa by sandeco addresses the challenge of extracting actionable, executable specifications from legacy codebases for AI coding agents. It serves engineers and developers working with older systems, enabling AI agents to safely evolve these systems by providing a bridge between undocumented code and AI-driven development. The primary benefit is the transformation of trapped knowledge within legacy code into operational contracts that AI agents can reliably use.

How It Works

Reversa employs a sophisticated 5-phase pipeline orchestrated by a central Reversa agent, coordinating specialized AI agents. These agents perform distinct roles: Scout maps the project structure, Archaeologist analyzes code modules, Detective extracts implicit business rules, Architect synthesizes architectural views, and Writer generates traceable specifications. This modular, agent-based approach allows for deep, systematic analysis and ensures that generated specifications are operational contracts with code traceability, rather than just human-readable documentation.

Quick Start & Requirements

Installation is performed via npx reversa install within the root of the legacy project. The primary requirement is Node.js 18+. Reversa detects and leverages existing AI engines (e.g., Claude Code, Codex, Cursor) present in the environment, eliminating the need for Reversa to handle API keys or external authentication.

Highlighted Details

• Guaranteed Immutability: Reversa strictly adheres to a directive where it only creates new files (e.g., .agents/skills/, .reversa/, _reversa_sdd/) and never modifies or deletes existing project files.
• Comprehensive Output: Generates a wide array of specifications including project inventory, dependency lists, code analysis, data dictionaries, business rules, state machines, C4 architecture diagrams, ERDs, and traceability matrices.
• Confidence Scale: Each statement in the generated specifications is tagged with a confidence level: 🟢 CONFIRMED (directly from code), 🟡 INFERRED (deduced), or 🔴 GAP (requires human validation).
• Agent Specialization: Utilizes distinct agents for specific tasks like dynamic analysis (Tracer), UI documentation (Visor), and database analysis (Data Master).

Maintenance & Community

Contributions are welcomed via GitHub issues before Pull Requests. The project is hosted on GitHub at https://github.com/sandeco/reversa.git.

Licensing & Compatibility

Reversa is released under the MIT License, which permits broad use, modification, and distribution, including for commercial purposes and integration into closed-source projects.

Limitations & Caveats

While Reversa guarantees immutability of the project's original files, AI agents are fallible. Users are strongly advised to back up their projects using version control (Git), remote repositories, or local copies before initiating the analysis process, as AI agents can potentially make mistakes. Some extracted information may be inferred and require human validation.