aradotso/trending-skills/reversa-legacy-spec

---
name: reversa-legacy-spec
description: Use Reversa to reverse-engineer legacy codebases into executable AI-agent specifications
triggers:
  -"analyze my legacy codebase"
  -"generate specs from existing code"
  -"reverse engineer this project for AI agents"
  -"install reversa in my project"
  -"extract business rules from old code"
  -"create specifications from legacy system"
  -"help me document this codebase with AI agents"
  -"turn my legacy code into agent-ready specs"
---
 
# Reversa Legacy Spec Engineering
 
> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.
 
Reversa reverse-engineers legacy codebases into executable, traceable specifications ready for AI coding agents. It coordinates a pipeline of specialized agents (Scout, Archaeologist, Detective, Architect, Writer, Reviewer, and more) to extract business rules, architectural decisions, data flows, and implicit knowledge buried in existing code — then outputs structured operational contracts in `_reversa_sdd/`.
 
---
 
## Installation
 
Run inside the root of any legacy project. Node.js 18+ required.
 

 
The installer will:
1. Detect AI engines present (Claude Code, Cursor, Codex, Windsurf, etc.)
2. Prompt which agents to install (all selected by default)
3. Collect project name, language, and preferences
4. Copy agent skills to `.agents/skills/` (and `.claude/skills/` for Claude Code)
5. Create the engine entry file (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.)
6. Create `.reversa/` state/config structure
7. Generate SHA-256 manifest for safe future updates
 
> Reversa **never modifies or deletes** any existing file in your project. All writes go to `.reversa/` and `_reversa_sdd/`.
 
---
 
## CLI Commands
 

 
---
 
## Activating the Analysis
 
After installation, open your project in the AI agent and run:
 

 
For engines without slash command support (Codex, Aider, Opencode):
 

 
Reversa introduces itself, generates a personalized exploration plan, and saves progress to `.reversa/state.json` at every checkpoint. If the session is interrupted, just type `/reversa` again to resume exactly where you left off.
 
---
 
## The 5-Phase Pipeline
 

 
Independent agents that can run at any phase: **Visor**, **Data Master**, **Design System**, **Tracer**
 
### Agent Roles
 
| Agent | What it does |
|-------|-------------|
| **Scout** | Maps folder structure, languages, frameworks, dependencies, entry points |
| **Archaeologist** | Deep module analysis: algorithms, control flows, data structures |
| **Detective** | Extracts implicit business rules, retroactive ADRs, state machines, permissions |
| **Architect** | Synthesizes C4 diagrams, full ERD, integration map, technical debt register |
| **Writer** | Generates specs as operational contracts with code traceability links |
| **Reviewer** | Finds inconsistencies and validates gaps with the user |
| **Tracer** | Resolves gaps via logs, tracing, real data (read-only) |
| **Visor** | Documents UI from screenshots — no running system needed |
| **Data Master** | Full DB analysis: DDL, migrations, ORM, ERD, triggers, procedures |
| **Design System** | Extracts design tokens: colors, typography, spacing, themes |
| **Chronicler** | Documents code changes during active development sessions |
 
---
 
## Output Structure
 
All generated specifications land in `_reversa_sdd/`:
 

 
### Confidence Scale
 
Every statement in generated specs is tagged:
 
| Mark | Meaning |
|------|---------|
| 🟢 CONFIRMED | Extracted directly from code — cited with file + line |
| 🟡 INFERRED | Deduced from patterns — may need validation |
| 🔴 GAP | Not determinable from code — requires human input |
 
---
 
## Internal State Structure
 

 
---
 
## Supported AI Engines
 
| Engine | Entry file created | Activation command |
|--------|-------------------|-------------------|
| Claude Code | `CLAUDE.md` | `/reversa` |
| Codex | `AGENTS.md` | `reversa` |
| Cursor | `.cursorrules` | `/reversa` |
| Gemini CLI | `GEMINI.md` | `/reversa` |
| Windsurf | `.windsurfrules` | `/reversa` |
| Kiro | `.kiro/steering/reversa.md` | `/reversa` |
| Cline | `.clinerules` | `/reversa` |
| Roo Code | `.roorules` | `/reversa` |
| GitHub Copilot | `.github/copilot-instructions.md` | `/reversa` |
| Aider | `CONVENTIONS.md` | `reversa` |
| Amazon Q Developer | `.amazonq/rules/reversa.md` | `/reversa` |
 
---
 
## Common Workflows
 
### Full analysis of a legacy project
 

 
### Resuming an interrupted session
 

 
### Running only the database agent
 

 
Then tell the agent: *"Run only Data Master on the database layer"*
 
### Updating agents after a new Reversa release
 

 
### Adding a new engine to an existing installation
 

 
---
 
## Configuration
 
### `.reversa/config.toml` (project-level, commit this)
 

 
### `.reversa/config.user.toml` (personal preferences, do NOT commit)
 

 
### `.reversa/plan.md`
 
Editable markdown file where you can guide the exploration order, flag modules to skip, or add context the agents should know before starting. Edit this before activating Reversa for best results.
 
---
 
## Troubleshooting
 
### Agent stops mid-analysis
 

 
State is persisted in `.reversa/state.json`. The orchestrator will pick up from the last checkpoint automatically.
 
### Output folder is wrong or missing
 
Check `.reversa/config.toml` — ensure `output_dir` matches where you expect output. Default is `_reversa_sdd`.
 
### Reversa modified my existing files
 
It shouldn't — this is a bug. Restore with:
 

 
Then open an issue at https://github.com/sandeco/reversa with your OS, Node version, and engine.
 
### Update overwrote my customized agent skill
 

 
### Installation fails — Node version
 

 
### Adding Reversa to a project already using Claude Code slash commands
 
The installer creates `CLAUDE.md` only if it doesn't exist. If you already have one, the installer appends the Reversa activation block. Check `CLAUDE.md` after install to confirm the `/reversa` entry is present.
 
---
 
## Best Practices
 
- **Always commit before running** — `git add -A && git commit -m "pre-reversa snapshot"`
- **Edit `.reversa/plan.md`** before activation to give agents context about known sensitive modules or areas to prioritize
- **Use `confidence-report.md`** as your review starting point — focus human validation time on 🔴 GAP items first
- **Don't commit `config.user.toml`** — add it to `.gitignore`
- **Run Tracer** when static analysis leaves too many 🔴 GAPs — it resolves ambiguity through dynamic observation
- **Specs in `_reversa_sdd/` are inputs to other agents** — commit them and reference them when asking a coding agent to modify the legacy system
 
---
 
## Contributing
 

 
Open an issue before submitting a PR to discuss the change.
 
**License:** MIT