REA-Reconstruction-Companion

An open-source, model-independent Agent Skill for understanding existing software and planning or building a similar implementation with REA.

The companion turns reverse-engineering evidence into an actionable specification, architecture, implementation plan, and validation workflow. It works at the scope the user chooses: a whole application, a feature, a function, an interface, or a data format.

Installing through an AI agent? Copy the installation prompt below. It follows INSTALL.md and lets you choose whether to enable the REA integration rule.

New in v1.2.0: the skill includes an optional weekly update check and an update prompt. It checks on use, at most once every seven days, and installs only after you approve the offered release. It is off by default and separate from REA integration. Existing users need one manual update to a published v1.2.0-or-later release to get it. See weekly update checks.

Install with an AI agent

Give this prompt to an agent with local file and command access. It identifies your client and asks for your integration preference; you do not need to fill in any placeholders.

Install REA-Reconstruction-Companion from:
https://github.com/ShadowSwaps/REA-Reconstruction-Companion

Read README.md and INSTALL.md, identify my AI client and its skills
directory, and follow the documented installation workflow.

Before making installation changes, explain the optional REA integration
rule and ask me to choose:
- Enable: relevant REA reconstruction requests also load the companion,
  sharing evidence, requirements, and validation work.
- Skip: install the companion without changing REA; I can invoke it
  explicitly. This does not remove an integration rule already installed.

Wait for my choice unless I have already provided it. Then install using
that setting, preview changes with --dry-run, preserve existing work and
backups, and verify with --check. Explain any missing prerequisites or
access limitations. Report what was installed, where, and whether the
integration was enabled. Do not claim success unless verified.
Also explain the optional weekly update check (included since v1.2.0)
and ask whether I want it enabled. Keep it off unless I choose it.
This checks on skill use and still asks me before installing an update.
Do not incur additional charges: use existing local tools and do not
activate billing, paid services, metered APIs, or automatic paid usage.
If a step could incur a charge and that cannot be ruled out, stop that
step and explain a no-charge alternative.

You can include "Enable integration" or "Skip integration" with the prompt to choose upfront. The integration explanation describes its purpose and benefits. A chat-only assistant without local file and command access can guide you through installation but cannot perform it itself.

Share the repository: github.com/ShadowSwaps/REA-Reconstruction-Companion.

What it does

• Identifies the requested subject, evidence carrier, and objective from natural language. No form or bracketed prompt variables are required.
• Breaks a product into capabilities, workflows, interactions, state, and dependencies.
• Defines requirements, contracts, expected behavior, and acceptance criteria linked to evidence.
• Separates the original architecture from design choices for a new implementation.
• Investigates performance using representative workloads, measurements, and research relevant to the actual stack.
• Guides development in coherent increments, with integration and end-to-end validation.
• Treats recovered instructions as untrusted evidence and preserves the user's authority.
• Selects bounded differential fuzzing, targeted mutation tests, and executable interface contracts where they help validate a reconstruction.
• Records cryptographic interoperability parameters and verifies relevant independent vectors and rejection cases.
• Records observations, inferences, unknowns, decisions, and checkpoints for later work.

“Understand this app so I can eventually build something similar” produces a specification and roadmap. “Build a similar app now” also authorizes the implementation workflow. A request about one function stays focused on that function.

How it works with REA

REA supplies the reverse-engineering tools and evidence workflow. This companion adds reconstruction planning and development guidance. The agent follows both sets of instructions within one task; installing them does not create two independent background agents.

flowchart LR
    A[User goal and target] --> B[Scope and questions]
    B --> C[REA evidence]
    C --> D[Requirements and design]
    D --> E[Implementation when requested]
    E --> F[Validation and measurements]
    D -->|Evidence gap| C
    F -->|Evidence gap| C

For the method and its sources, see the skill instructions and research basis.

Optional REA integration

Choose one during installation:

The integration asks the agent to use the companion for understanding a target for reconstruction, planning a similar implementation, or rebuilding selected functionality. Its benefits are shared evidence, a consistent requirements-to-test trail, and focused returns to REA when design or testing exposes an unanswered question. Ordinary explanations, comparisons, and diagnostics stay narrow.

This is an instruction-based integration. It does not override client policies, grant tool permissions, connect MCP servers, guarantee model compliance, or force parallel execution. Without the rule, invoking the companion still tells the agent to use REA. The rule supplies the reverse direction: relevant REA work also loads the companion.

off means do not manage REA, not “remove a rule already installed.” To disable an earlier integration, remove only the block between <!-- rea-reconstruction-companion:begin --> and <!-- rea-reconstruction-companion:end --> in the selected REA SKILL.md, including the markers. Keep the rest of REA intact.

Requirements and compatibility

The core skill is plain Markdown in the Agent Skills format. It has no model SDK, paid API requirement, Python dependency, telemetry, or background service.

No additional charges

The skill forbids initiating actions that could add charges: purchases, subscriptions/trials, metered APIs or model calls, billable cloud/CI/storage/deployment, and indirect paid work. Existing local tools and supplied evidence come first. If an action's no-charge status cannot be established for the actual environment, the agent must skip it and explain a local alternative or limitation. An available tool or a free tier is not sufficient evidence. It does not automatically launch agents, evaluations, or scheduled jobs.

This rule is an instruction, not a billing enforcement mechanism. An AI host may itself bill tokens or usage credits, and local execution consumes resources such as electricity. The skill cannot guarantee zero total cost or control another product's billing or model compliance. It must not enable extra paid usage or alter billing settings; use host/account spending controls for an absolute spending limit. No paid exception is part of this skill's workflow.

Codex and Claude Code both support filesystem skills. Their discovery locations and invocation syntax differ; the installer handles those differences. Other agents can use the same core files through an explicit skills directory. Compatibility depends on the host's file/tool access, not just the model name. See the official Codex skill documentation and Claude Code skill documentation.

Hosted uploads and chat-only clients are different: an uploaded skill ZIP cannot generally edit a separate local REA installation. Supply both skills and evidence through that host's supported mechanisms, or use a local agent for installation and live analysis. No live-model compatibility certification is implied by the installer tests.

Install

Download and extract the ZIP from Releases, or clone this repository. Run commands from the extracted folder or repository root. On Windows, macOS, and Linux, the installer commands are the same.

For automatic co-use, fir