by sandeco
Turn legacy systems into executable specifications for AI agents.
Reversa is a specification reverse-engineering framework. Install it inside a legacy project and it coordinates a team of specialized AI agents to analyze the existing code and generate complete, traceable specifications ready for use by any coding agent.
Most production systems carry years of accumulated knowledge: implicit business rules, undocumented architectural decisions, critical logic buried in code nobody wants to touch. That knowledge exists, but it's trapped.
AI agents are transformative for creating and evolving software, but they depend on specifications to operate safely. For new systems, you write the spec and the agent executes. For legacy systems — or those built with pure vibe coding — there is no spec: the agent has no way of knowing what it cannot break.
Reversa is the bridge between the legacy system and AI agents.
It analyzes the existing code, extracts accumulated knowledge (business rules, flows, module contracts, retroactive architectural decisions) and transforms everything into executable, traceable specifications ready for any coding agent.
The result is not documentation for humans to read. These are operational contracts that allow an agent to evolve the system with fidelity to what already exists.
In the root of the legacy project:
npx reversa installThe installer will:
- Detect the AI engines present in the environment (Claude Code, Codex, Cursor, etc.)
- Ask which agents to install — all selected by default
- Collect project name, language, and preferences
- Copy agents to
.agents/skills/(and.claude/skills/for Claude Code) - Create the engine entry file (
CLAUDE.md,AGENTS.md, etc.) - Create the
.reversa/structure with state, configuration, and plan - Generate SHA-256 manifest for safe updates
Reversa never deletes or modifies existing files in your project. Agents write only to
.reversa/and the output folder (_reversa_sdd/by default).
Requirements: Node.js 18+
Important
The installer only creates new files (CLAUDE.md, AGENTS.md, .agents/skills/, etc.) and never modifies or deletes any existing file in your project. During analysis, agents operate under a strict and inviolable directive: all writes are restricted to .reversa/ and _reversa_sdd/ — no other file in your project is touched.
Caution
Although Reversa never modifies your files, AI agents can make mistakes. We strongly recommend:
- Version the project in Git — make sure all files are committed before starting the analysis
- Have the repository on GitHub (or GitLab, Bitbucket) — so you have a safe remote copy
- Make a local copy of the folder — a simple
cp -r my-project my-project-backupprotects against any unexpected event
If something unexpected happens during analysis, you can restore the original state with git restore . or from the backup copy.
Warning
🔑 Reversa does not request, store, or transmit API keys from any LLM service. All intelligence is delegated to the AI agent already present in your environment (Claude Code, Codex, Cursor, etc.) — no external authentication dependencies.
After installation, open the project in the AI agent and activate Reversa:
/reversa
For engines without slash command support (like Codex):
reversa
Reversa will introduce itself, create a personalized exploration plan, and coordinate the entire analysis. Progress is saved in .reversa/state.json at each checkpoint — if the session is interrupted, just type reversa to resume where you left off.
Reversa uses a 5-phase pipeline orchestrated by the Reversa agent:
Reconnaissance Excavation Interpretation Generation Review
Scout Archaeologist Detective Writer Reviewer
Architect
Independent agents (run at any phase): Visor, Data Master, Design System, Tracer
| Agent | Role |
|---|---|
| Reversa | Central orchestrator. Coordinates all agents, saves checkpoints, guides the user |
| Scout | Maps the surface: folder structure, languages, frameworks, dependencies, entry points |
| Archaeologist | Deep module-by-module analysis: algorithms, control flows, data structures |
| Detective | Extracts implicit business knowledge: rules, retroactive ADRs, state machines, permissions |
| Architect | Synthesizes everything into C4 diagrams, full ERD, integration map, and technical debt |
| Writer | Generates specifications as operational contracts with code traceability |
| Agent | Role |
|---|---|
| Reviewer | Reviews specs, finds inconsistencies, and validates gaps with the user |
| Tracer | Dynamic analysis: resolves gaps via logs, tracing, and real data (read-only) |
| Visor | Documents the interface from screenshots — without needing the system to be running |
| Data Master | Complete database analysis: DDL, migrations, ORM, ERD, triggers, procedures |
| Design System | Extracts design tokens: colors, typography, spacing, themes, and components |
| Chronicler | Documents code changes during development sessions |
Use when the legacy "code" is not source code but a structured artifact like a visual workflow. Generates the SDD spec and prepares the state for the main pipeline to take over.
| Agent | Role |
|---|---|
| N8N Translator | Reads N8N workflows exported as JSON and produces SDD specs ready for Python reimplementation. Activated via /reversa-n8n |
_reversa_sdd/
├── inventory.md # Project inventory
├── dependencies.md # Dependencies with versions
├── code-analysis.md # Technical analysis per module
├── data-dictionary.md # Data dictionary
├── domain.md # Glossary and business rules
├── state-machines.md # State machines in Mermaid
├── permissions.md # Permission matrix
├── architecture.md # Architectural overview
├── c4-context.md # C4 Diagram: Context
├── c4-containers.md # C4 Diagram: Containers
├── c4-components.md # C4 Diagram: Components
├── erd-complete.md # Full ERD in Mermaid
├── confidence-report.md # Confidence report 🟢🟡🔴
├── gaps.md # Identified gaps
├── questions.md # Questions for human validation
├── dynamic.md # Dynamic analysis findings (Tracer)
├── sdd/ # Specs per component
│ └── [component].md
├── openapi/ # API specs (if applicable)
├── user-stories/ # User stories (if applicable)
├── adrs/ # Retroactive architectural decisions
├── flowcharts/ # Flowcharts in Mermaid
├── sequences/ # Sequence diagrams
├── ui/ # Interface specs (Visor)
├── database/ # Database specs (Data Master)
├── design-system/ # Design tokens (Design System)
└── traceability/
├── spec-impact-matrix.md # Which spec impacts which
└── code-spec-matrix.md # Code file to corresponding spec
Every statement in the specs is marked with:
| Mark | Meaning |
|---|---|
| 🟢 CONFIRMED | Extracted directly from code — can be cited with file and line |
| 🟡 INFERRED | Deduced from patterns — may be wrong |
| 🔴 GAP | Not determinable from code — requires human validation |
| Engine | File created | Skills path | Activation |
|---|---|---|---|
| Claude Code ⭐ | CLAUDE.md |
.claude/skills/reversa-*/ and .agents/skills/reversa-*/ |
/reversa |
| Codex ⭐ | AGENTS.md |
.agents/skills/reversa-*/ |
reversa |
| Cursor ⭐ | .cursorrules |
.agents/skills/reversa-*/ |
/reversa |
| Gemini CLI | GEMINI.md |
.agents/skills/reversa-*/ |
/reversa |
| Windsurf | .windsurfrules |
.agents/skills/reversa-*/ |
/reversa |
| Antigravity | AGENTS.md |
.agents/skills/reversa-*/ |
/reversa |
| Kiro | (none) | .kiro/skills/reversa-*/ and .agents/skills/reversa-*/ |
/reversa |
| Opencode | AGENTS.md |
.agents/skills/reversa-*/ |
reversa |
| Cline | .clinerules |
.agents/skills/reversa-*/ |
/reversa |
| Roo Code | .roorules |
.agents/skills/reversa-*/ |
/reversa |
| GitHub Copilot | .github/copilot-instructions.md |
.agents/skills/reversa-*/ |
/reversa |
| Aider | CONVENTIONS.md |
.agents/skills/reversa-*/ |
reversa |
| Amazon Q Developer | .amazonq/rules/reversa.md |
.agents/skills/reversa-*/ |
/reversa |
npx reversa install # Install Reversa in the project
npx reversa status # Show current analysis state
npx reversa update # Update agents to the latest version
npx reversa add-agent # Add an agent to the project
npx reversa add-engine # Add support for a new engine
npx reversa uninstall # Remove Reversa from the projectThe update command detects files you modified via SHA-256 and never overwrites customizations.
The uninstall command removes only files created by Reversa — nothing from the legacy project is touched.
.reversa/
├── state.json # Analysis state between sessions
├── config.toml # Project configuration
├── config.user.toml # Personal preferences (don't commit)
├── plan.md # Exploration plan (user-editable)
├── version # Installed version
├── context/
│ ├── surface.json # Generated by Scout
│ └── modules.json # Generated by Archaeologist
└── _config/
├── manifest.yaml # Installation metadata
└── files-manifest.json # SHA-256 hashes for safe updates
.agents/skills/ # Universal skills (all compatible agents)
.claude/skills/ # Mirror for Claude Code
Contributions are welcome. Open an issue to discuss before submitting a PR.
git clone https://github.com/sandeco/reversa.git
cd reversa
npm installMIT — see LICENSE for details.