reversa-legacy-spec

What this skill does

```markdown
---
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.

```bash
npx reversa install
```

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

```bash
# Install Reversa into the current project
npx reversa install

# Show current analysis state and progress
npx reversa status

# Update agents to the latest version (respects your customizations via SHA-256)
npx reversa update

# Add a single agent to an existing installation
npx reversa add-agent

# Add support for an additional AI engine
npx reversa add-engine

# Remove all Reversa-created files (legacy project untouched)
npx reversa uninstall
```

---

## Activating the Analysis

After installation, open your project in the AI agent and run:

```
/reversa
```

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

```
reversa
```

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

```
Phase 1: Reconnaissance  →  Scout
Phase 2: Excavation      →  Archaeologist
Phase 3: Interpretation  →  Detective + Architect
Phase 4: Generation      →  Writer
Phase 5: Review          →  Reviewer
```

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/`:

```
_reversa_sdd/
├── inventory.md              # Full 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 (Mermaid diagrams)
├── permissions.md            # Permission/role matrix
├── architecture.md           # Architectural overview
├── c4-context.md             # C4 Context diagram
├── c4-containers.md          # C4 Containers diagram
├── c4-components.md          # C4 Components diagram
├── erd-complete.md           # Full ERD in Mermaid
├── confidence-report.md      # 🟢🟡🔴 confidence per statement
├── gaps.md                   # Identified knowledge 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
├── 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 → corresponding spec
```

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

```
.reversa/
├── state.json              # Analysis progress between sessions
├── config.toml             # Project configuration
├── config.user.toml        # Personal preferences (add to .gitignore)
├── plan.md                 # Exploration plan (user-editable)
├── version                 # Installed Reversa version
├── context/
│   ├── surface.json        # Scout output
│   └── modules.json        # Archaeologist output
└── _config/
    ├── manifest.yaml           # Installation metadata
    └── files-manifest.json     # SHA-256 hashes for safe updates

.agents/skills/             # Agent skills (all compatible engines)
.claude/skills/             # Mirror for Claude Code specifically
```

---

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

```bash
# 1. Navigate to your legacy project root
cd /path/to/legacy-project

# 2. Commit everything first (safety)
git add -A && git commit -m "chore: snapshot before reversa analysis"

# 3. Install Reversa
npx reversa install

# 4. Open project in your AI agent (Claude Code, Cursor, etc.)
# 5. Activate Reversa
/reversa
```

### Resuming an interrupted session

```bash
# Check what phase you're on
npx reversa status

# Then in your AI agent, just re-activate
/reversa
# Reversa reads .reversa/state.json and continues from the last checkpoint
```