git:20261003.62834b1 to git:20261005.4fda294

- description: 'Tear down an authorized competitor repo, binary or product into a feature inventory and adoption choices. Use when: comparing an external system; local questions go to Research.'

- Reverse-engineer an external system into two things: a **mechanically-verifiable teardown** (feature inventory + registry + specs, optionally a security audit) and a **steal-map** — what to adopt into our surfaces, what to leave behind. The teardown is the evidence; the steal-map is the decision. Separating them works because a decision row that must cite a registry entry can be re-checked by anyone, while a decision made from impressions cannot be re-checked by its own author. The original failure mode this skill exists to prevent: reading a competitor's README and "deciding" from vibes.

-

- **Triggers:** "reverse-engineer X", "tear down Y", "what should we steal from Z", "evaluate competitor/upstream", "should we fork/adopt/build-native".

-

- ## Prompt

-

- ```text

- Reverse-engineer the beads CLI (github.com/steveyegge/beads, tag v2.1.0)

- in repo mode, then author steal-map.md comparing its dependency-graph

- reconciler against our cli/internal/gates/ package. I own this analysis

- and have authorization for the clone.

- ```

-

- ## It's working if

-

- Observable in the trace, without reading the prose:

-

- - `feature-registry.yaml` and `clone-metadata.json` land under

- `.agents/scratch/reverse-engineer/<product>/` with the resolved

- upstream commit recorded.

- - Every `steal-map.md` row cites a teardown registry entry and our

- matching surface, using the full `have`/`gap`/`steal`/`park`/`reject`

- set.

- - `bash skills/reverse-engineer/scripts/validate-output.sh --output-dir

- "$output_dir" --phase complete` exits 0 before handoff.

- - A one-way-door adoption row is routed to Plan instead of decided

- inside `steal-map.md`.

- ## Phase 1 — Mechanical teardown (the script)

- Produce evidence, not vibes. The script clones (pinned), scans CLI/config/artifact surface, and writes a feature inventory + machine-checkable registry + spec set.

- Binary mode requires `--authorized` (see Invocation Contract + Self-Test). Use the bundled demo fixture if you lack authorization for a real binary.

- ## Phase 2 — The steal-map (the decision)

- Map each capability the teardown found onto **our** surfaces. This is the part that turns research into a decision. Emit `.agents/scratch/reverse-engineer/<product>/steal-map.md` with a table; every row cites the teardown evidence **and** the matching surface in our repo.

- The mechanical script intentionally stops after validating Phase 1. It cannot

- truthfully decide whether our live tree has, lacks, or should adopt a capability.

- The caller authors `steal-map.md` from the generated registry plus a fresh read

- of our repository, then runs the complete-output validator below. A missing or

- malformed map is therefore an incomplete skill result, not a script success

- silently relabelled as a decision.

- | `<feature>` | `<our file / skill / CLI, or "none">` | **have** / **gap** / **steal** / **park** / **reject** |

-

- Verdict rules (hard-won — apply them, do not skip):

- - **steal** — we lack it and it advances our core. Steal the *pattern*, not the storage engine: re-express in our primitives, never vendor their runtime.

- - **park** — real, but it's substrate we deliberately delegate (e.g. orchestration per ADR-0009) or downstream of an unproven bet. Name it, don't build it.

- - **reject** — it 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).

- - **have** — we already do this; confirm it still holds, move on.

- - **gap** — we should have it and don't. These are the steal candidates.

- Discipline that makes the map trustworthy:

- - **Independently checked, not self-report.** Get facts on *how* they implement

- each capability from code, cross-checked by a fresh reader — never from a

- README or one context's summary. Model family is optional metadata, not a

- trust requirement.

- - **Probe the real state, don't argue from stale.** Re-verify our side against the live tree before calling something a gap; every "X is missing" carries the search that proved it.

- - **The steal is the pattern, not the platform.** Their robustness is usually one idea (unification, a gate, a reconcile loop). Steal the idea; leave the scaffolding.

- context, or a migration), do not decide it here. Hand the steal-map to Plan.

- Dueling Idea Genies or Premortem may challenge the choice as advisory

- evidence. Plan alone shapes the selected option in the existing intent source;

- neither strategy grants readiness or continuation authority.

-

- ## Invocation Contract

-

- Required: `product_name`. Common flags: `--mode=repo|binary|both`, `--upstream-repo`, `--upstream-ref` (requires the selected checkout to be at that exact commit and records its resolved SHA in `clone-metadata.json`), `--local-clone-dir` (selects that exact tree, including a non-Git tree; it never falls back to the caller's checkout), `--output-dir` (default `.agents/scratch/reverse-engineer/<product>/`), `--security-audit`, `--materialize-archives` (authorized-only opt-in; embedded-archive extraction is off/index-only by default), `--authorized` (mandatory for binary mode — refuses without it). Full list: `python3 skills/reverse-engineer/scripts/reverse_engineer.py --help`.

-

- ## Output Specification

-

- Phase-1 teardown under `output_dir/`: `feature-inventory.md`, `feature-registry.yaml`, `feature-catalog.md`, `spec-architecture.md`, `spec-code-map.md`, `spec-clone-vs-use.md`, `spec-clone-mvp.md`, plus `spec-cli-surface.md` only when a CLI is detected. `clone-metadata.json` is written whenever an upstream repo/ref is selected and binds the exact analyzed commit, including an already-present checkout. Security mode adds `output_dir/security/`: `threat-model.md`, `attack-surface.md`, `dataflow.md`, `crypto-review.md`, `authn-authz.md`, `findings.md`, `reproducibility.md`, `validate-security-audit.sh`. Phase-2 adds the caller-authored `steal-map.md`.

-

- - **Artifact directory:** the exact `--output-dir`, defaulting to

- `$REPO/.agents/scratch/reverse-engineer/<product>/`.

- - **Filename convention:** the fixed phase-1 and phase-2 names above; security

- files live only in the `security/` child directory.

- - **Serialization/schema format:** registry is YAML, clone metadata is one JSON

- object, and inventories/specs/steal-map are nonempty Markdown files.

- - **Validator command:** Phase 1 runs this automatically with

- `--phase teardown`. After authoring `steal-map.md`, validate the complete

- skill output with `$output_dir`, `$security_audit`, `$sbom`, and

- `$upstream_ref_set` (each numeric flag `0|1`):

-

- ```bash

- bash skills/reverse-engineer/scripts/validate-output.sh \

- --output-dir "$output_dir" --phase complete \

- --security-audit "$security_audit" --sbom "$sbom" \

- --upstream-ref-set "$upstream_ref_set"

- ```

- - **Downstream handoff:** give the validated `steal-map.md` to Plan for

- one-way-door candidates; ordinary `have`, `park`, and

- `reject` decisions remain evidence-backed terminal rows.

-

- ### Earlier default compatibility

-

- Existing teardowns under `.agents/research/<product>/` remain in place and

- usable. The script accepts that directory when it is passed explicitly with

- `--output-dir`; that flag is caller authorization to write the teardown at the

- exact selected path. It does not relocate or duplicate existing artifacts. An

- invocation that omits the flag writes only to the current scratch default and

- never creates output under the earlier root.

- Consumers must retain the exact selected `output_dir` with their evidence

- references instead of rediscovering outputs by globbing one root. This owning

- skill contract is the compatibility authority; no separate migration receipt

- is required.

-

- ## Reproducibility + fixtures

- `--upstream-ref` binds the selected checkout to one full commit: a new clone is

- checked out detached at the fetched ref, while an existing checkout must already

- match or the run refuses before analysis. `clone-metadata.json` records that

- resolved commit. Regression test: `bash skills/reverse-engineer/scripts/repo_fixture_test.sh`. To update a fixture when contracts legitimately change, re-run with the new pinned ref, copy the contract files into `fixtures/<product>/`, and commit.

- ## Self-Test (acceptance)

- bash skills/reverse-engineer/scripts/self_test.sh

- Must show: feature inventory and registry generated; the exact Phase-1 validator

- passes; the complete validator rejects a missing and malformed steal-map and

- accepts a valid caller-authored fixture; existing-checkout ref mismatch and

- output symlinks fail closed; in security mode `validate-security-audit.sh`

- exits 0 only after the scaffold is completed and the secret scan passes.

-

- ## Examples

-

- ### Reverse-engineer an OSS CLI (repo mode) → steal-map

-

- Run Phase 1 for `cc-sdd` with `--mode=repo --upstream-repo="https://github.com/gotalab/cc-sdd.git" --upstream-ref=v1.0.0`. It clones the pinned source, scans the surface, writes inventory/registry/specs, and validates the teardown. Then inspect our live surfaces, author each `have`/`gap`/`steal`/`park`/`reject` row in `steal-map.md`, and run the complete-output validator. Supply selected steals to Plan.

-

- ### Binary analysis with security audit

- Run the skill for `ao` with `--authorized --mode=binary --binary-path="$(command -v ao)" --security-audit`. It performs authorized static analysis plus the security suite under `output_dir/security/`; the secret-scan check must pass.

- ## Troubleshooting

- | Refuses binary analysis | Missing `--authorized` | Add `--authorized` (explicit written authorization required). |

- | No `clone-metadata.json` | `--upstream-repo` not passed | Pass `--upstream-repo` (and optionally `--upstream-ref`). |

- | Fixture diff fails | Upstream changed / stale golden | Re-run pinned, refresh `fixtures/`, commit. |

- | Existing teardown is under `.agents/research/` | It used the earlier default | Pass that exact directory with `--output-dir`; new runs otherwise use the scratch default. |

- | `spec-cli-surface.md` missing | No Node/Python/Go CLI detected | Surface is documented in `spec-code-map.md` instead. |

- ## Quality Rubric

-

- - [ ] Every steal-map row cites teardown evidence **and** our matching surface (or "none").

- - [ ] Verdicts use the full set — `have`/`gap`/`steal`/`park`/`reject` — not everything marked "steal".

- - [ ] Facts on *how* they implement come from code and a fresh independent check — not a README.

- - [ ] One-way-door adoptions are supplied to Plan, not decided here.

- - [ ] Secret-scan gate passed over all outputs; no proprietary source/prompts reproduced.

-