pi-reversa

Pi Coding Agent package for Reversa, the reverse-engineering framework that turns legacy systems into executable specifications for AI agents.

It bundles Reversa 1.3.5 as a native Pi engine:

• all 77 Reversa agents as Pi skills (/skill:reversa, /skill:reversa-scout, …);
• a /reversa-* command alias for every agent (/reversa, /reversa-scout, /reversa-migrate, …);
• /reversa-init, a Pi-native port of npx reversa install;
• /reversa-status, the project progress summary;
• the Reversa legacy-edit policy injected into the system prompt;
• a hard guard that blocks write/edit calls violating .reversa/reversa-config.json.

Install

pi install npm:pi-reversa

Update with pi update npm:pi-reversa (or pi update --extensions). Do not run npx reversa install/update in Pi projects; the package replaces them.

Usage

1. Open Pi in the legacy project.
2. Run /reversa-init and answer the prompts (project name, your name, languages, output folder, git strategy, answer mode). Existing files are never overwritten; running it again only creates missing files and registers pi next to engines already in .reversa/state.json.
3. Run /reversa to start the discovery. Any agent can be called directly with /reversa-<agent> [args].
4. Run /reversa-status to see the current phase and pending steps.

The first /reversa run also works without /reversa-init: the orchestrator creates the state itself.

Legacy-edit policy

Whenever .reversa/ exists in the working directory:

• The Reversa non-destructive policy is added to the system prompt as a <reversa> section.
• Pi's built-in write and edit tools are blocked outside the Reversa folders (.reversa/, the output folder, _reversa_docs/, the forward folder, _reversa_bugs/, _reversa_refactor/) unless .reversa/reversa-config.json allows it. The decision logic and messages match Reversa's Claude Code PreToolUse hook.
• .reversa/reversa-config.json itself can only be changed by you.

To allow edits to legacy code, edit the config yourself:

{ "version": 1, "allowLegacyEdits": true, "allowedPaths": ["src/**"] }

An empty allowedPaths with allowLegacyEdits: true allows every path. The guard covers Pi's built-in write/edit tools only; bash and third-party edit tools are governed by the system-prompt policy alone.

Development

git clone --recurse-submodules <repo> && cd pi-reversa
npm install
npm test           # generates packaged/ from the reversa/ submodule, then runs the tests
npm run typecheck
pi install ./      # local install

packaged/ is generated by npm run prepare-skills (also run on prepack) and is not committed.

License

MIT. Reversa is © its authors under the MIT license; see packaged/LICENSE-reversa.