[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-877":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":24,"topics":25,"createdAt":9,"pushedAt":9,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},877,"reversa","sandeco\u002Freversa","sandeco","Transform legacy systems into executable specifications for AI coding agents",null,"JavaScript",1202,333,42,6,0,15,63,454,45,20.57,"MIT License",false,"main",true,[],"2026-06-12 02:00:20","# Reversa \n\u003Csmall>by sandeco\u003C\u002Fsmall>\n\n**Turn legacy systems into executable specifications for AI agents.**\n\n[![English Docs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDOCS-English-009c3b?style=for-the-badge&logo=material-for-mkdocs&logoColor=white&labelColor=2d2d2d)](https:\u002F\u002Fsandeco.github.io\u002Freversa\u002F)\u003Cbr>\n[![Português Docs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDOCS-Portugu%C3%AAs-ffcc00?style=for-the-badge&logo=material-for-mkdocs&logoColor=black&labelColor=2d2d2d)](https:\u002F\u002Fsandeco.github.io\u002Freversa\u002Fpt\u002F)\u003Cbr>\n[![Español Docs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDOCS-Espa%C3%B1ol-c60b1e?style=for-the-badge&logo=material-for-mkdocs&logoColor=white&labelColor=2d2d2d)](https:\u002F\u002Fsandeco.github.io\u002Freversa\u002Fes\u002F)\n\nReversa 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.\n\n---\n\n## Why Reversa exists\n\nMost 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.\n\nAI 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.\n\n**Reversa is the bridge between the legacy system and AI agents.**\n\nIt 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.\n\nThe 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.\n\n---\n\n## Installation\n\nIn the root of the legacy project:\n\n```bash\nnpx reversa install\n```\n\nThe installer will:\n1. Detect the AI engines present in the environment (Claude Code, Codex, Cursor, etc.)\n2. Ask which agents to install — all selected by default\n3. Collect project name, language, and preferences\n4. Copy agents to `.agents\u002Fskills\u002F` (and `.claude\u002Fskills\u002F` for Claude Code)\n5. Create the engine entry file (`CLAUDE.md`, `AGENTS.md`, etc.)\n6. Create the `.reversa\u002F` structure with state, configuration, and plan\n7. Generate SHA-256 manifest for safe updates\n\n> Reversa **never deletes or modifies** existing files in your project.\n> Agents write only to `.reversa\u002F` and the output folder (`_reversa_sdd\u002F` by default).\n\n**Requirements:** Node.js 18+\n\n---\n\n> [!IMPORTANT]\n> ### 🔒 Guaranteed immutability of the legacy project\n>\n> The installer only creates new files (`CLAUDE.md`, `AGENTS.md`, `.agents\u002Fskills\u002F`, 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\u002F` and `_reversa_sdd\u002F`** — no other file in your project is touched.\n\n> [!CAUTION]\n> ### 💾 Back up your project before starting\n>\n> Although Reversa never modifies your files, AI agents can make mistakes. **We strongly recommend:**\n>\n> 1. **Version the project in Git** — make sure all files are committed before starting the analysis\n> 2. **Have the repository on GitHub** (or GitLab, Bitbucket) — so you have a safe remote copy\n> 3. **Make a local copy of the folder** — a simple `cp -r my-project my-project-backup` protects against any unexpected event\n>\n> If something unexpected happens during analysis, you can restore the original state with `git restore .` or from the backup copy.\n\n> [!WARNING]\n> 🔑 **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.\n\n---\n\n## How to use\n\nAfter installation, open the project in the AI agent and activate Reversa:\n\n```\n\u002Freversa\n```\n\nFor engines without slash command support (like Codex):\n\n```\nreversa\n```\n\nReversa will introduce itself, create a personalized exploration plan, and coordinate the entire analysis. Progress is saved in `.reversa\u002Fstate.json` at each checkpoint — if the session is interrupted, just type `reversa` to resume where you left off.\n\n---\n\n## How it works\n\nReversa uses a 5-phase pipeline orchestrated by the **Reversa** agent:\n\n```\nReconnaissance  Excavation  Interpretation  Generation  Review\n    Scout       Archaeologist  Detective      Writer    Reviewer\n                                Architect\n```\n\nIndependent agents (run at any phase): **Visor**, **Data Master**, **Design System**, **Tracer**\n\n---\n\n## Agents\n\n### Required\n\n| Agent | Role |\n|-------|------|\n| **Reversa** | Central orchestrator. Coordinates all agents, saves checkpoints, guides the user |\n| **Scout** | Maps the surface: folder structure, languages, frameworks, dependencies, entry points |\n| **Archaeologist** | Deep module-by-module analysis: algorithms, control flows, data structures |\n| **Detective** | Extracts implicit business knowledge: rules, retroactive ADRs, state machines, permissions |\n| **Architect** | Synthesizes everything into C4 diagrams, full ERD, integration map, and technical debt |\n| **Writer** | Generates specifications as operational contracts with code traceability |\n\n### Optional (installed by default)\n\n| Agent | Role |\n|-------|------|\n| **Reviewer** | Reviews specs, finds inconsistencies, and validates gaps with the user |\n| **Tracer** | Dynamic analysis: resolves gaps via logs, tracing, and real data (read-only) |\n| **Visor** | Documents the interface from screenshots — without needing the system to be running |\n| **Data Master** | Complete database analysis: DDL, migrations, ORM, ERD, triggers, procedures |\n| **Design System** | Extracts design tokens: colors, typography, spacing, themes, and components |\n| **Chronicler** | Documents code changes during development sessions |\n\n### Translators (input adapters)\n\nUse 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.\n\n| Agent | Role |\n|-------|------|\n| **N8N Translator** | Reads N8N workflows exported as JSON and produces SDD specs ready for Python reimplementation. Activated via `\u002Freversa-n8n` |\n\n---\n\n## What is generated\n\n```\n_reversa_sdd\u002F\n├── inventory.md              # Project inventory\n├── dependencies.md           # Dependencies with versions\n├── code-analysis.md          # Technical analysis per module\n├── data-dictionary.md        # Data dictionary\n├── domain.md                 # Glossary and business rules\n├── state-machines.md         # State machines in Mermaid\n├── permissions.md            # Permission matrix\n├── architecture.md           # Architectural overview\n├── c4-context.md             # C4 Diagram: Context\n├── c4-containers.md          # C4 Diagram: Containers\n├── c4-components.md          # C4 Diagram: Components\n├── erd-complete.md           # Full ERD in Mermaid\n├── confidence-report.md      # Confidence report 🟢🟡🔴\n├── gaps.md                   # Identified gaps\n├── questions.md              # Questions for human validation\n├── dynamic.md                # Dynamic analysis findings (Tracer)\n├── sdd\u002F                      # Specs per component\n│   └── [component].md\n├── openapi\u002F                  # API specs (if applicable)\n├── user-stories\u002F             # User stories (if applicable)\n├── adrs\u002F                     # Retroactive architectural decisions\n├── flowcharts\u002F               # Flowcharts in Mermaid\n├── sequences\u002F                # Sequence diagrams\n├── ui\u002F                       # Interface specs (Visor)\n├── database\u002F                 # Database specs (Data Master)\n├── design-system\u002F            # Design tokens (Design System)\n└── traceability\u002F\n    ├── spec-impact-matrix.md # Which spec impacts which\n    └── code-spec-matrix.md   # Code file to corresponding spec\n```\n\n### Confidence scale\n\nEvery statement in the specs is marked with:\n\n| Mark | Meaning |\n|------|---------|\n| 🟢 CONFIRMED | Extracted directly from code — can be cited with file and line |\n| 🟡 INFERRED | Deduced from patterns — may be wrong |\n| 🔴 GAP | Not determinable from code — requires human validation |\n\n---\n\n## Supported engines\n\n| Engine | File created | Skills path | Activation |\n|--------|-------------|-------------|------------|\n| Claude Code ⭐ | `CLAUDE.md` | `.claude\u002Fskills\u002Freversa-*\u002F` and `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| Codex ⭐ | `AGENTS.md` | `.agents\u002Fskills\u002Freversa-*\u002F` | `reversa` |\n| Cursor ⭐ | `.cursorrules` | `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| Gemini CLI | `GEMINI.md` | `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| Windsurf | `.windsurfrules` | `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| Antigravity | `AGENTS.md` | `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| Kiro | (none) | `.kiro\u002Fskills\u002Freversa-*\u002F` and `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| Opencode | `AGENTS.md` | `.agents\u002Fskills\u002Freversa-*\u002F` | `reversa` |\n| Cline | `.clinerules` | `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| Roo Code | `.roorules` | `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| GitHub Copilot | `.github\u002Fcopilot-instructions.md` | `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n| Aider | `CONVENTIONS.md` | `.agents\u002Fskills\u002Freversa-*\u002F` | `reversa` |\n| Amazon Q Developer | `.amazonq\u002Frules\u002Freversa.md` | `.agents\u002Fskills\u002Freversa-*\u002F` | `\u002Freversa` |\n\n---\n\n## CLI commands\n\n```bash\nnpx reversa install      # Install Reversa in the project\nnpx reversa status       # Show current analysis state\nnpx reversa update       # Update agents to the latest version\nnpx reversa add-agent    # Add an agent to the project\nnpx reversa add-engine   # Add support for a new engine\nnpx reversa uninstall    # Remove Reversa from the project\n```\n\nThe `update` command detects files you modified via SHA-256 and never overwrites customizations.\nThe `uninstall` command removes only files created by Reversa — nothing from the legacy project is touched.\n\n---\n\n## Internal structure\n\n```\n.reversa\u002F\n├── state.json          # Analysis state between sessions\n├── config.toml         # Project configuration\n├── config.user.toml    # Personal preferences (don't commit)\n├── plan.md             # Exploration plan (user-editable)\n├── version             # Installed version\n├── context\u002F\n│   ├── surface.json    # Generated by Scout\n│   └── modules.json    # Generated by Archaeologist\n└── _config\u002F\n    ├── manifest.yaml       # Installation metadata\n    └── files-manifest.json # SHA-256 hashes for safe updates\n\n.agents\u002Fskills\u002F         # Universal skills (all compatible agents)\n.claude\u002Fskills\u002F         # Mirror for Claude Code\n```\n\n---\n\n## Contributing\n\nContributions are welcome. Open an issue to discuss before submitting a PR.\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fsandeco\u002Freversa.git\ncd reversa\nnpm install\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n","Reversa 是一个将遗留系统转换为可执行规范的框架，以便AI编码代理使用。其核心功能是通过安装在遗留项目中，协调一组专门的AI代理来分析现有代码，并生成完整、可追溯的规范。这些规范实际上是操作合同，允许AI代理在不破坏原有逻辑的基础上进化系统。技术上，Reversa基于JavaScript开发，支持多种AI引擎如Claude Code、Codex等，并且保证不会修改或删除项目中的任何现有文件，确保了项目的不变性。适用于需要对缺乏文档的老系统进行现代化改造，或者希望利用AI辅助开发但又受限于无规范说明的场景。",2,"2026-06-11 02:39:58","CREATED_QUERY"]