Reverse Engineer

Reverse-engineer an external system into two things: a teardown (feature inventory, a registry of where to read, CLI and contract specs, optionally a security audit) and a steal-map (the decision: what to adopt into our surfaces and what to leave behind). A decision row that must cite evidence can be re-checked by anyone; a decision made from impressions cannot be re-checked by its own author. Deciding from a competitor's README is the failure this skill exists to prevent.

⚠️ Constraints — Hard Guardrails (MANDATORY)

• Only operate on code/binaries you own or have explicit written authorization to analyze — this matters because unauthorized teardown is the legal/IP line.
• Do not provide steps to bypass protections/ToS or to extract proprietary source/system prompts.
• Do not output reconstructed proprietary source or embedded prompts (index only; redact in reports) — to prevent reproducing protected IP.
• Redact secrets/tokens/keys if encountered. The output validator runs this skill's scripts/security/scan_secrets.sh over the whole output dir in every phase; a hit fails it until you redact.
• Always separate docs say vs code proves vs hosted/control-plane.

Evidence rules

• Tag every capability by its source. code: their source or binary shows it; cite the file:line (for a binary, the teardown output line) you opened and record what the code actually does, which is often narrower than the claim. docs: a README, doc page or announcement says it; unverified. hosted: a service or control plane you cannot inspect.
• The registry is an index, not evidence. It lists where to read. In repo mode its groups start impl: unclassified (binary mode writes client groups anchored to binary-symbols.txt, still not code evidence); client or mixed needs anchors, and control-plane means hosted. A registry entry alone never makes a row code.
• No code access, no steal. With only docs, a README or a landing page, every row about their implementation is docs and unverified. It can be gap, park or reject, never steal.
• Prove our side on the live tree. A have row cites our file. Every "missing" row carries the search that proved it (command and scope). Check what our current stack already offers before calling anything missing.
• Re-open before a steal. Re-open each cited file before marking steal; a summary from memory is not evidence.
• The steal is the pattern, not the platform. Their robustness is usually one idea (unification, a gate, a reconcile loop). Re-express it in our primitives; never vendor their runtime or storage engine.

Phase 1 — teardown

<skill-dir> is the directory that contains this SKILL.md. Claude Code shows it as "Base directory for this skill"; Codex lists this skill's SKILL.md path; in an AgentOps source checkout it is skills/reverse-engineer. Replace <skill-dir> with that absolute path before running a command. The working directory stays the user's repository. If the host did not show where this skill is installed, use the directory of the SKILL.md you read. If you cannot determine it, do not guess a path or run a same-named script from the current repository; say the bundled script is unavailable and build the inventory and steal-map by hand as in docs-only mode below.

With an authorized clone or binary, the script clones (pinned), scans the CLI/config/artifact surface and validates the teardown:

python3 "<skill-dir>/scripts/reverse_engineer.py" <product> --mode=repo \
  --upstream-repo="https://github.com/org/repo.git" --upstream-ref=v1.0.0 \
  --output-dir=".agents/scratch/reverse-engineer/<product>/"

A passing teardown is not a populated one. The inventory and registry index the target's docs pages (--docs-sitemap-url, else its docs/**/*.md); with no docs they are empty. spec-architecture.md and spec-code-map.md are templates you fill. The code anchors are in contracts/repo-contract.json and spec-cli-surface.md.

The clone lands in .tmp/<product>/ under the current directory unless --local-clone-dir names another place; keep it out of your commits. Binary mode requires --authorized; without written authorization, do not run binary mode; use docs-only mode below. Flags, the full output list, fixtures and tests are in the invocation reference.

Without code access (only a README, docs site or landing page), skip the script: build the inventory and steal-map by hand with each row tagged docs or hosted, and say that no teardown validator ran. When the code is readable but the script cannot run on it, read the code directly and cite file:line for each code row; the validator gap still gets reported.

Phase 2 — steal-map

Map each capability onto our surfaces in .agents/scratch/reverse-engineer/<product>/steal-map.md. The script stops after validating Phase 1; it cannot truthfully decide whether our live tree has, lacks, or should adopt a capability. The caller authors the map from the teardown, the code it points to, and a fresh read of our repository. A missing or malformed map is an incomplete skill result, not a script success relabelled as a decision.

Each row gets exactly one verdict:

• have — our live tree already does it; cite the file and confirm it still holds.
• steal — we lack it, code evidence shows how they do it, and it advances our core. Take the pattern, re-expressed in our primitives.
• gap — we lack it and would want it if it holds up, but steal is not earned: their mechanism is docs or hosted only, or its value to our core is unshown. Name the evidence that would decide it.
• park — real, but deliberately not ours to build now: substrate we delegate (for AgentOps, ADR-0009 keeps scheduling, supervision and queues external) or downstream of a bet we have not made. Name it, don't build it.
• reject — conflicts with our doctrine (e.g. a completion edge with no check behind it, where we require checks and CI, plus one fresh judgment for a costly mistake).

When two seem to fit, reject beats park, and park beats steal or gap; between steal and gap, the evidence rules decide.

Validation and handoff

After authoring steal-map.md, validate the complete output with $output_dir, $security_audit, $sbom, and $upstream_ref_set (each numeric flag 0|1):

bash "<skill-dir>/scripts/validate-output.sh" \
  --output-dir "$output_dir" --phase complete \
  --security-audit "$security_audit" --sbom "$sbom" \
  --upstream-ref-set "$upstream_ref_set"

It fails any table row without a source tag or one of the five verdicts, any steal without code evidence, and any none without a backticked search; with an upstream ref it requires the resolved commit in clone-metadata.json. With --security-audit 1, first fill every _TBD under security/; each finding in findings.md needs Evidence: and Fix: lines. It must exit 0 before handoff, or the report says it did not run (docs-only mode).

If adopting a steal is a one-way door (an architecture fork, a new bounded context, a storage or data migration), do not decide it here: hand the validated steal-map to Plan, which shapes the selected option in the existing intent source. Idea Genie duel mode or Premortem may challenge it as advisory evidence; neither grants readiness or continuation authority. Ordinary have, park and reject rows are evidence-backed terminal decisions.

For general exploration rather than one external system, use Research. The scenarios in reverse-engineer.feature document the behavior; the invocation reference lists the tests that check it.