Reversa

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.

Why Reversa exists

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.

Installation

In the root of the legacy project:

npx reversa install

The installer will:

1. Detect the AI engines present in the environment (Claude Code, Codex, Cursor, etc.)
2. Ask which agents to install — all selected by default
3. Collect project name, language, and preferences
4. Copy agents to .agents/skills/ (and .claude/skills/ for Claude Code)
5. Create the engine entry file (CLAUDE.md, AGENTS.md, etc.)
6. Create the .reversa/ structure with state, configuration, and plan
7. 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]

🔒 Guaranteed immutability of the legacy project

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]

💾 Back up your project before starting

Although Reversa never modifies your files, AI agents can make mistakes. We strongly recommend:

1. Version the project in Git — make sure all files are committed before starting the analysis
2. Have the repository on GitHub (or GitLab, Bitbucket) — so you have a safe remote copy
3. Make a local copy of the folder — a simple cp -r my-project my-project-backup protects 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.

How to use

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.

How it works

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

Agents

Required

| 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 |

Optional (installed by default)

| 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 |

What is generated

_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

Confidence scale

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 |

Supported engines

| 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 | .kiro/steering/reversa.md | .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 |

CLI commands

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 project

The 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.

Internal structure

.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

Contributing

Contributions are welcome. Open an issue to discuss before submitting a PR.

git clone https://github.com/sandeco/reversa.git
cd reversa
npm install

License

MIT — see LICENSE for details.