REA-Reconstruction-Companion

Understand existing software. Plan a reconstruction. Build and validate when requested.

An open-source, model-independent Agent Skill that works with REA. Turn reverse-engineering evidence into requirements, architecture, an implementation roadmap and testable results—at the scope you choose.

Get started · Usage examples · REA integration · Documentation · Releases · Support on Ko-fi

Start with the installation prompt below, or use the manual commands. The portable core has no model SDK or paid API requirement. Integration and weekly update checks are separate choices; both are explained before setup.

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.

You can explicitly invoke $rea-reconstruction-companion in Codex or /rea-reconstruction-companion in Claude Code. With integration enabled, a relevant request to REA also instructs the agent to load the companion.

Describe the software and the outcome you want in ordinary language. The companion uses available REA tools or supplied evidence, identifies gaps, and keeps the work at your requested scope. These examples are illustrations, not required prompts: paraphrases, casual wording, minor typos and follow-ups should work in context. Say what you want to understand or build; you do not need to name a mode or reproduce a template. Explicit corrections and exclusions take precedence, and a possible future rebuild does not request implementation now.

If the original has awkward behavior, say which compatibility matters and what you want improved—for example, “Keep exports readable by my existing tools, but make failed saves clear.” The companion separates observed behavior from intended changes, checks affected dependencies, and keeps unresolved or deferred work visible. See the worked quirk decisions.

Understand and plan a future reconstruction. Expect evidence-backed behavior and workflow requirements, known unknowns, and a staged roadmap before implementation:

Use REA and the companion to understand the desktop notes app I have open
so I can plan a similar app later. Focus on creating, editing, searching,
and saving notes. Link requirements to the evidence, separate observations
from inferences, and list unanswered questions and a staged build roadmap.
Stop after the specification and plan.

Build a similar app now. A build request authorizes implementation within the requested scope. Expect incremental code changes and validation against observed requirements, with gaps and differences reported:

Use REA and the companion to investigate the desktop notes app I have open
and build a local web app with similar note creation, editing, search,
and save behavior in this workspace. I need to trust today's notes first:
it must work offline and reopen my saved notes. Start with that working
journey, including save failures, then add search and the remaining
features in testable increments. Animations can wait. Validate against
the evidence and report differences and anything you could not verify.

For a broad request, expect a compact plan around the first useful outcome, its essential dependencies and design-changing unknowns, with evidence-linked checks and deferred work kept visible. Explicit hard requirements remain binding. If finding existing notes matters most, that can lead instead of creating new ones; you do not need to use priority labels or complete a feature inventory. See the worked prioritization example for a plan and its limits.

Investigate one function or feature. Expect a focused contract covering inputs, outputs, side effects, errors, and evidence gaps:

Use REA and the companion to investigate the CSV import feature in the
app I have open. Trace how it handles headers, quoted fields, duplicate
rows, and malformed input. Document inputs, outputs, side effects, error
behavior, and representative acceptance cases, citing the evidence.
Keep this to an investigation; do not implement changes.

The agent must report missing tools or evidence instead of claiming live analysis or complete equivalence. A build request does not authorize deployment, releases, installation changes, paid tools, or additional charges. Those actions require their own authority; the no-additional-charges constraint below still applies.

Continue implementing the app from this project's REA reconstruction specification.

Reimplement the decodeFrame function in this library and make it faster for large inputs. Recover its contract, then compare correctness and performance.

Pick up from this checkpoint. Keep the same scope, retain the passing evidence that still applies, and work on the next unfinished part.

Select the checkpoint or its path and identify any changed target or goal. The agent should read that record and the sources needed for the next step, check evidence applicability, and preserve historical results. Resuming a specification does not authorize building it. See portable checkpoint guidance and the worked resume example.

For a small question, expect a compact evidence-linked answer or contract with limits and a useful next action. A feature build adds implementation and acceptance results; it need not produce a whole-app blueprint. If a consequential target or outcome is unclear, expect one focused clarification. Host activation and instruction following vary: explicit invocation can help select the skill, but examples and installation do not guarantee every host/model will interpret every phrasing correctly.

When a service is inaccessible. “Build local editing now; keep actual sharing pending until I supply authorized service evidence.” Expect an explicitly labeled local substitute or finite replay where useful, with real-service requirements still pending. Client observations do not recover server internals, and a local demo cannot verify remote compatibility. The runnable synthetic example checks local save/reopen, unavailable versus empty, replay mismatch and misleading structured completion claims without contacting a provider.

To see the workflow before trying a target, follow the worked investigation, reconstruction, or resume for your goal. These disclose answers and prior source exposure; they are teaching material, not prerequisites or evidence of a fresh agent trial. The first-use review separates manual intent scenarios from executable checks.

• 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.

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.

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, first install REA for your client. Then choose a command:

# Claude Code, with the optional integration
node install.mjs --client claude-code --integration on

# Codex, with the optional integration
node install.mjs --client codex --integration on

# Companion only; no changes to REA
node install.mjs --client claude-code --integration off

Use --dry-run on any installation command to inspect the paths and changes without writing files. The companionChanges lists identify added, modified, and removed files relative to the companion directory, including local files that a replacement would move into the backup. Use the same command with --check afterward to verify the selected installation mode. A missing REA skill or ambiguous choice stops integrated installation before the companion is installed. Differently cased paths to the same REA file are treated as one candidate; genuinely separate installations still require an explicit selection.

claude_code, as used by REA, is accepted as an alias for claude-code by the installer and updater. Plans, receipts and newly saved update settings use claude-code.

node install.mjs --client generic --integration on --skills-dir "/path/to/skills" --rea-skill "/path/to/reverse-engineer-anything/SKILL.md"

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.

REA skill refreshes can remove this rule. In REA 6.5.0 (skill version 42), rea doctor requires byte-for-byte canonical skill files, so adding our block can produce skill:identity / config_drift with “Installed REA skill identity is stale” even when version and tool count match. This is a known cause, not a reason to ignore all stale or doctor diagnostics: other managed files or settings may also differ. The pinned identity check and skill installer show why rea setup restores canonical files and preserves edited originals in backups, removing the active companion block. An REA update that refreshes the skill can do the same; other upstream versions may differ.

After rea setup, rea update, or another REA skill refresh, recheck the selected integration and, if needed, restore only its block using the matching verified companion package; see verification and scoped recovery. Do not restore an entire old REA backup over newer instructions. If routing disappeared, explicitly invoke the companion or run the manual check. The optional on-use warning cannot run if the companion/helper is never invoked.

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.

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.

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.

Starting with v1.2.0, the updater is bundled inside the skill, including installations for Codex, Claude Code and generic clients. Enable it once after installation if you want release notifications. The host calls a small local helper when the skill is used; it contacts GitHub only when seven days have elapsed. An idle skill runs nothing. Earlier versions do not gain this automatically: manually install a published v1.2.0-or-later package first.

With checks enabled and recorded integration on, the current helper also inspects the recorded REA rule locally before cooldown or network decisions. Missing, changed/malformed, or unreadable/unsafe rules return integration-needs-attention without repair, state changes or networking. Disabled checks and integration off do not inspect REA. This warning is available only in versions containing this change and only when the companion/helper is invoked; it is not a background monitor or a full rea doctor check.

When a newer stable release is found, the agent offers Update now / Remind me next week / Skip this version / Disable checks. No answer means no update. Approval is tied to the offered release and asset; changed assets require a new offer. Local customizations stop automatic replacement. Successful updates retain backups, verify the result and preserve your selected client and REA integration setting.

Checks are off by default, independent of integration, and require existing Node.js 20+. There is no npm dependency, model/API key, paid service, extra model call, background daemon or scheduled AI task. Online operations also require confirmation that the actual network/tool environment cannot add charges. Unknown-cost or unavailable access is skipped; this is not an unconditional zero-resource-cost or billing-enforcement guarantee.

Read the setup, commands, state location and recovery guide. Host instruction-following and local command access are required; the helper cannot force every AI host to invoke it or authenticate a human response. Installation refresh behavior depends on the host. The project owner's release approval process remains unchanged.

• Repeating the same installation is safe and does not duplicate the integration block.
• Differing companion files require --replace; the installer backs up the entire prior companion directory before replacing it.
• REA edits preserve everything outside the marked integration block. The exact earlier pre-release rule can also be migrated; customized unmarked rules require review.
• Backups and a receipt are stored in .rea-reconstruction-companion-installer/ next to the parent skills directory. The installer prints the exact transaction path.
• Failed commits attempt REA and companion recovery independently, so an unreadable or missing REA file does not prevent restoring the prior companion. Backups remain available; a detected concurrent edit is retained and reported rather than overwritten.
• Updating REA may replace its skill instructions. Follow verification and scoped recovery after a refresh. Nothing monitors or rewrites REA in the background.

For manual recovery, use the printed receipt to locate the selected paths. Restore companion-before to the companion's former location if appropriate. Restore rea-before.md only when REA has no later changes you need to retain; otherwise remove or repair just the integration block. If a process was killed and left an install.lock, make sure no installer is running before removing that exact lock file and retrying.

For stopped local validation, see the bounded interrupted-run recovery example: preserve the failed attempt, validate eligible completed evidence, and rerun unfinished checks in a fresh destination.

The full source is included: skill and research references, installer, optional adapter, tests, manifest generator, and release builder. There are no hidden components or npm dependencies.

node scripts/manifest.mjs
node scripts/run-checks.mjs
python scripts/build_release.py

Tests cover installation choices, backups, rollback, package integrity, and the local behavioral evaluation harness, including deliberately incorrect candidates. CI runs on Windows, macOS, and Linux with Node 20, 22, and 24. The included workflows use standard runners, skip private repositories, and add no model API calls or artifact/cache uploads. These checks do not establish reconstruction quality on every target or model.

The test runner first checks directory-link fixture setup in the same temporary parent/runtime. A denied or unknown probe leaves required validation incomplete; it does not explain unrelated assertion failures or prove administrator rights are needed. Original test failures and counts remain visible. See test environment diagnostics for probe-only output, explicit full runs and supported local/CI next steps.

The behavioral evaluation kit supplies portable tasks, raw evidence, independent executable oracles, and a human review rubric. It covers narrow functions, file formats, stateful workflows, original quirks versus approved improvements, ambiguous retries, inaccessible backends, contradictory evidence, hostile embedded instructions, cryptographic boundaries, and cost-sensitive tool choices. Paired selection tasks check that an implementation follows the requested compatibility or improvement goal; human review still verifies its reasoning and authorization. Running its harness tests is separate from evaluating an actual agent; model runs are not started automatically and require an environment established to incur no additional charge. See CONTRIBUTING.md.

If this project is useful to you, you can support my work on Ko-fi. Contributions are optional; the project remains freely available under its open-source licenses.

Bug reports, reproducible examples and focused pull requests are also welcome. Read CONTRIBUTING.md before contributing.

All original code, skill instructions, tests, build scripts, and documentation in this repository are released under the MIT license. You may use, modify, and redistribute them, including commercially, subject to that license. The evaluation kit includes a small, attributed Wycheproof test-data subset under its bundled Apache-2.0 license; it remains fully open-source. Upstream REA and linked research remain separate projects; no REA code or cryptographic implementation is bundled. No particular AI provider or proprietary model is required by this project.