Reversa: a spec generator that reads your legacy codebase before any agent touches it

The problem framing: agents cannot work safely without a spec

Reversa describes itself in one line as turning legacy systems into executable specifications for AI agents, and the accompanying paper gives the reasoning. The README's argument is that production systems carry years of accumulated knowledge in the form of implicit business rules, undocumented architectural decisions and critical logic buried in code nobody wants to touch. That knowledge exists but is trapped.

The consequence for coding agents is direct. For a new system you write the specification and the agent executes it. For a legacy system, or one built quickly without design, there is no specification, which means the agent has no way of knowing what it cannot break. That is the gap Reversa targets.

What it produces is deliberately not documentation for humans to read. The README calls the output operational contracts, and the distinction is the point. A human-oriented document explains what the code does. An operational contract states constraints an agent must respect when editing: which invariants hold, which calls must not change, which behaviors other systems depend on.

The associated paper is titled Reversa: A Reverse Documentation Engineering Framework for Converting Legacy Software into Operational Specifications for AI Agents, by Macedo and da Costa, dated May 2026 and available on arXiv as 2605.18684. Documentation is published in English, Portuguese and Spanish, which is a reasonable signal about where the author is writing from, and the repository contains an `evolucao/` directory and a `BRAINSTORMING/` directory alongside the code.

Installing: one npx command and a strict write boundary

Installation runs from the root of the legacy project:

npx reversa install

The installer follows a documented sequence. It detects the AI engines present in the environment, Claude Code, Codex, Cursor and others. It asks which agents to install, with all selected by default. It collects the project name, language and preferences. It copies agents into `.agents/skills/`, and into `.claude/skills/` as well for Claude Code. It creates the engine entry file, meaning `CLAUDE.md`, `AGENTS.md` or the equivalent. It creates the `.reversa/` structure with state, configuration and plan. And it generates a SHA-256 manifest, which is what makes future updates able to tell your files from the tool's own.

The guarantee is stated twice, once in a note and once in a callout, and it is the property to check before you run anything. Reversa never deletes or modifies existing files in your project. During analysis, agents operate under a directive restricting all writes to `.reversa/` and `_reversa_sdd/`, with no other file touched.

The README is still careful about what that means in practice, and the caution is worth reading. AI agents can make mistakes, so it recommends three precautions: version the project in Git with everything committed before starting, have the repository on a remote such as GitHub, GitLab or Bitbucket, and keep a local copy. Recovery is then `git restore .` or the backup.

One more detail that removes a category of worry. The README states that Reversa does not request, store or transmit API keys from any LLM service. All intelligence is delegated to the coding agent already present in your environment, so there is no vendor account, no key management and no data path to a service you did not choose.

Eleven commands for discovery, evolution and estimation

After installation you activate Reversa from inside your agent. For engines with slash command support it is:

/reversa

For engines without slash command support, such as Codex, you type `reversa` instead. Reversa introduces itself, builds a personalized exploration plan, and coordinates the analysis. Progress is written to `.reversa/state.json` at each checkpoint, so an interrupted session resumes by typing the command again.

The rest of the command table maps intent to entry point, and the range tells you this is more than a documentation generator.

Analyzing an existing legacy and producing specs is `/reversa`. Running the same analysis end to end without intermediate stops is `/reversa-autonomous`. Starting a brand new project from a one-line idea is `/reversa-new`, and adding `expresso` takes it all the way to code. Evolving the system one feature at a time from spec to code is `/reversa-forward`. Adding a short amendment to the feature you just delivered is `/reversa-add`. Converging a delivered feature back into the extraction is `/reversa-sync`. Rebuilding the legacy on a modern stack is `/reversa-migrate`.

Rendering the extracted knowledge as an HTML mini-site is `/reversa-docs`. Tracking and fixing defects with causal traceability is `/reversa-debugger` and `/reversa-debugger-fix`. And effort and pricing estimation on top of the specifications comes in three forms: `/reversa-pricing-profile`, `/reversa-pricing-size` and `/reversa-pricing-estimate`.

The loop worth understanding is `add` followed by `sync`. You deliver a feature, record the amendment, then fold that feature back into the extraction so the specification reflects what you actually built rather than what you planned. Without that step a specification degrades into a wish list.

Two orchestrators are built for unattended runs. `/reversa-autonomous` runs the full discovery pipeline with the same agents and checkpoints. `/reversa-new expresso "<your idea>"` goes from a greenfield idea to implemented code, then chains into the forward cycle. Both concentrate every question into a single interview at the start, keep writes inside `.reversa/` and the output folders, and never run a destructive or outward-facing command such as delete, push, publish or install on their own. Uncertainties are recorded with a marker instead of interrupting the run.

The five-phase discovery pipeline and how state is kept

The Discovery pipeline behind `/reversa` is described in the README as a five-phase sequence orchestrated by the Reversa agent, shown in an ASCII diagram that begins Reconnaissance, Excavation, Interpretation. The README stops at that point, so the later phase names are not stated there.

The three names that are given suggest the method. Reconnaissance is the survey pass, establishing what the system is and where the important logic lives. Excavation is the dig, pulling out behavior from specific files. Interpretation is the step where extracted behavior becomes claims about intent, which is where business rules and architectural decisions get separated from incidental implementation detail.

Pausing behavior is documented clearly. Each orchestrator pauses between agents and asks for confirmation before advancing, so a person stays in control of every step in the default mode. The autonomous commands exist for sessions where nobody is watching the terminal.

State lives in `.reversa/state.json` and is saved at each checkpoint. That file is what makes a long multi-agent run resumable, and it is also the thing to inspect if a run produces something you do not trust: you can see how far it got and what it decided at each step.

The `_reversa_sdd/` output folder is separate from `.reversa/` state, which is a reasonable split. Working state and generated specifications have different lifetimes, and you would want to version one and regenerate the other.

What is actually shipped: an installer, agent skills and templates

The package manifest describes a small npm package with a large payload. The package is `reversa` at version 1.3.3, marked as an ES module, with a single binary at `bin/reversa.js` and a MIT license.

The `files` array is the interesting part, because it defines the install surface: `agents/`, `bin/`, `lib/`, `templates/`, `README.md` and `LICENSE`. So the published artifact is the installer plus the agent definitions plus the templates those agents fill in. The repository tree adds `docs/` with a `mkdocs.yml` for the three-language documentation site, a `scripts/` directory, the `BRAINSTORMING/` and `evolucao/` directories, and `.github/`.

Dependencies are limited to four: `chalk` for terminal color, `inquirer` for the installer's questions, `ora` for the spinner, and `semver` for version comparisons. That is the whole runtime. There is no parser dependency, no AST library and no model client, which confirms the README's claim that analysis is delegated to the agent you already have rather than performed by the tool.

There is a `verify` script worth noting, because it tells you what the maintainer worries about:

python3 scripts/verify-invocation.py && node scripts/test-installer-transport.mjs

A Python script and a Node script, run together. A Python dependency inside a Node package's verification path suggests the agent invocation templates are checked against a reference implementation in Python, which is a reasonable way to keep a large set of markdown templates honest.

On requirements there is a discrepancy to be aware of. The README says Node.js 18+, while the manifest's `engines` field says 18.20.2 or newer. The manifest is what npm enforces and what CI will catch, so treat 18.20.2 as the actual floor and install a current LTS release.

Where this approach breaks down

The premise is sound for code whose behavior you understand but never wrote down. Three situations fall outside it.

First, code where nobody knows the behavior. Reversa extracts rules that exist in the code, and an undocumented system can contain behavior that is wrong, accidental or long obsolete. Specifications derived from it will faithfully describe a system that should not exist in that form. The pipeline cannot distinguish a load-bearing invariant from a bug nobody has hit yet.

Second, systems whose real specification lives outside the repository. Deployment config, database migrations, external API contracts, runbook knowledge and tribal memory about why a workaround exists are all part of the system's behavior, and none of it is in the source tree an agent can read.

Third, scale. A five-phase multi-agent pipeline over a large repository is a long run with many checkpoints, and each phase can surface questions only a person who knows the system can answer. On a monolith, expect the pipeline to produce a large document that is mostly correct and locally wrong in ways that matter.

There is also a question the README does not address: verification. It says the output is traceable, which implies you can check a claim against the code, but it does not say whether the pipeline validates its own extractions or whether traceability is left to you. For a tool whose value is that an agent will edit code based on the output, that distinction matters more than the ergonomics.

Given all of that, the sensible evaluation is a single well-understood module rather than a whole repository. Pick something whose behavior you could explain to a new hire, run the discovery pipeline on it, and compare the specification against what you know. That tells you more than any amount of reading about the framework.

Editorial conclusion

Reversa is aimed at one specific problem, and it solves it in a way that respects your working tree: an existing codebase with real behavior encoded in it, and coding agents about to be let loose in that codebase with no written specification. The immutability rule is the feature to judge it by. Agents write only into `.reversa/` and `_reversa_sdd/`, the installer never modifies an existing file, and the README is explicit that you should still commit everything and keep a copy first, because AI agents make mistakes. Judge it on the specifications it produces for one well-understood module rather than on a whole-repository run, since a five-phase pipeline across a large system will surface questions only you can answer. The last push was on 2026-09-08 and the package is at version 1.3.3 under MIT.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. sandeco/reversa on GitHub