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 install
The installer will:
.agents/skills/ (and .claude/skills/ for Claude Code)CLAUDE.md, AGENTS.md, etc.).reversa/ structure with state, configuration, and planReversa 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:
- 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 eventIf 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 |
After discovery completes, this team turns the extracted knowledge into a self-contained HTML mini-site under .reversa/documentation/. Run /reversa-docs to orchestrate the full team, or activate any agent in isolation to regenerate only its pages.
| Agent | Role |
|---|---|
| Reversa Docs | Orchestrates the team, runs the 3-question interview, computes deterministic seed. Activated via /reversa-docs |
| Mapper | Spatial structure: arquitetura.html (Code City 3D, Three.js), modulos.html (force-directed D3), topologia.html (legacy vs modern side-by-side) |
| Analyst | Quantitative data: metricas.html (Highcharts treemap, sankey, histogram, columns), timeline.html (events from .reversa/chronicle.md) |
| Storyteller | Narrative: glossario.html (client-side search), deck.html (6 to 10 navigable slides), features/<spec>.html (one per SDD spec) |
| Publisher | Final integration: index.html with hero + unique generative seal, auto-discovery of auxiliary HTMLs from other agents, link validation, local telemetry |
The team brings 5 shared skills (reversa-arquitetura-3d, reversa-selo-generativo, reversa-highcharts-visualizer, reversa-especialista-d3, reversa-image-prompt-json) which are installed automatically alongside the team. The output is a static mini-site that opens via file:// with no server required.
_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 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.
.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 install
MIT — see LICENSE for details.
FAQs
Transform legacy systems into executable specifications for AI coding agents
We found that reversa demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Socket found 37 malicious PyPI wheels that abuse Python startup hooks to launch a Bun-powered credential stealer tied to Mini Shai-Hulud/Miasma.
Security News
RubyGems and Bundler 4.0.13 introduced an opt-in cooldown feature that delays newly published gems during dependency resolution.
Security News
pnpm 11.5 now recognizes npm staged publish approvals in release metadata, preventing those releases from being mistaken for lower-trust package publishes.