by sandeco

Turn legacy systems into executable specifications for AI agents.

📄 Paper: Reversa: A Reverse Documentation Engineering Framework for Converting Legacy Software into Operational Specifications for AI Agents — Macedo & da Costa, May 2026.

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:

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+

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.

For other workflows, use the matching entry command:

Each orchestrator pauses between agents and asks for CONTINUAR before advancing, so you stay in control of every step.

Two commands concentrate every question in a single interview at the start and then run without stopping, for sessions where nobody is watching the terminal (Claude Code YOLO mode or equivalent):

• /reversa-autonomous — the full Discovery pipeline, same agents and same checkpoints as /reversa.
• /reversa-new expresso "<your idea>" — greenfield from the idea all the way to implemented code, chaining into the forward cycle after the specs.

Both keep the non-destructive rule intact: writes stay inside .reversa/ and the output folders, and no destructive or outward-facing command (delete, git push, publish, install) is ever run on its own. Doubts that come up along the way are recorded with the 🟡 seal instead of interrupting the flow.

The Discovery pipeline (/reversa) is the heart of the framework: a 5-phase sequence 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, Soul Extractor, Reconstructor.

Once the specs exist, you can move forward in three directions, depending on the goal:

Discovery (/reversa)
        │
        ├── /reversa-forward    Evolve the system from specs to code
        ├── /reversa-migrate    Rebuild the legacy on a modern stack
        └── /reversa-docs       Render specs as an HTML mini-site

For a greenfield project (no legacy to extract), start with /reversa-new instead. It walks from a one-line idea to SDD specs and then hands off to /reversa-forward.

Reversa organizes its agents in nine specialized Teams. The Discovery Team (Reversa Agents Core) and the Bug Agents are always installed; six Teams are pre-checked in the installer and Translators are opt-in.

These run the main /reversa pipeline.

For projects that do not exist yet. Activate with /reversa-new and the orchestrator drives the pipeline Ideator → Researcher → Drafter → Spec SDD, with a CONTINUAR checkpoint between agents. Final handoff suggests /reversa-forward to take the specs to code.

The orchestrator has two modes. In guided mode (default) it stops at every agent and ends at the specs. In express mode (/reversa-new expresso "<your idea>") every question is concentrated in one interview at the start and, after INICIAR, the pipeline runs straight through the specs and into the forward cycle (requirements → plan → to-do → coding) until the code is on disk.

The bridge from specs to running code. Pipeline: requirements → clarify → quality → plan → to-do → audit → coding → sync. Use /reversa-forward as the entry point: it detects the physical stage of the active feature (by inspecting the artifacts on disk, not metadata) and suggests the next agent.

Use after /reversa when the goal is to rebuild the legacy on a modern stack. Activate with /reversa-migrate. Pipeline: Paradigm Advisor → Curator → Strategist → Designer → Screen Translator → Inspector, with a human review pause between agents. Every artifact lands in _reversa_sdd/migration/.

Three agents on top of the specs to estimate effort, size and price. Activate with /reversa-pricing-profile, /reversa-pricing-size and /reversa-pricing-estimate.

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.

After discovery completes, this team turns the extracted knowledge into a self-contained HTML mini-site under _reversa_docs/. Run /reversa-docs to orchestrate the full team, or activate any agent in isolation to regenerate only its pages.

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.

A repository-native causal defect memory, organized by context (the feature/module/use case the user is talking about): each context folder under _reversa_bugs/<context>/ aggregates everything of that area (annotated reports in intake/, self-contained bug folders, inspections and generated views incl. a clickable graph.html). Every bug carries a YAML front matter record traceable to the specs (SPEC ↔ CODE ↔ TEST ↔ BUG), a visual fix plan approved before any change, and a DONE.md lock once closed. Registering and fixing are strictly separate acts.

Perfective and preventive maintenance on code that already works: improve the internal structure without changing observable behavior, and prove that preservation before touching the code. Organized by context under _reversa_refactor/<context>/, with each transformation anchored to the soul (soul.md) and confirmed specs. The founding rule: proposing a transformation and applying it are separate acts, and nothing touches the legacy without proof of behavior preservation (a safety net of characterization tests, plus soul and regression checks). Project code changes only through an approved, reversible diff gate.

_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
├── 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)
├── addenda/                  # Post-delivery addenda, one per feature (Sync)
└── traceability/
    ├── spec-impact-matrix.md # Which spec impacts which
    └── code-spec-matrix.md   # Code file to corresponding spec

In a greenfield run, /reversa-new adds the following on top of _reversa_sdd/:

_reversa_sdd/
├── newproject-brief.md      # Initial brief (Reversa New)
├── ideation.md              # Structured brainstorm (Ideator)
├── personas.md              # Personas with journeys (Researcher)
├── prd.md                   # Product Requirements Document (Drafter)
└── sdd/
    └── [component].md       # SDD specs with quality score (Spec SDD)

Forward features land in a separate folder, _reversa_forward/ by default:

_reversa_forward/
└── <NNN>-<short-name>/      # One folder per feature
    ├── requirements.md
    ├── roadmap.md
    ├── investigation.md
    ├── data-delta.md
    ├── onboarding.md
    ├── interfaces/
    ├── actions.md
    ├── progress.jsonl
    ├── legacy-impact.md
    ├── regression-watch.md
    └── audit/
        ├── requirements-audit.md
        └── cross-check.md

After /reversa-coding, the optional /reversa-sync distills the delivered feature into _reversa_sdd/addenda/<feature-id>-<short-name>.md. The addendum is a bridge: it keeps the extraction representative of the system as it is today, points at the sections of architecture.md and domain.md that drifted, and is marked as superseded by the next full re-extraction. Original extraction artifacts are never edited.

The Documentation Team writes only inside _reversa_docs/ (HTML mini-site, fully offline).

Bug Agents write only inside _reversa_bugs/ (one folder per bug, plus generated views), spec addenda in _reversa_sdd/addenda/ and the generated mirror _reversa_sdd/traceability/bugs.md. Original specs are never edited; project code changes only through approval gates with explicit diffs.

Code Quality Agents write only inside _reversa_refactor/ (opportunities, plans and transformation records per context). Project code changes exclusively through an approved, reversible diff gate, and only after the safety net proves behavior is preserved.

Every statement in the specs is marked with:

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.