adopt-repo: overlay the firmware onto an existing repo

The generator (bootstrap/new-claude-project.*) spawns empty projects. This skill is the other entry point: a repo that already exists elsewhere (a take-home exercise, a client codebase, a fork target) becomes a harness-equipped copy under the user's account, with upstream history preserved as the root.

Inputs

Ask only for what the invocation left out: upstream URL, target repo name (default: upstream's name), visibility (default: private). Check the target name before creating anything. A failed gh repo view is not proof of availability: distinguish a confirmed not-found result from authentication, permission, or network failure. Verify the local destination is absent or empty; never overlay an unrelated checkout.

Steps

1. Clone upstream to a short path. Not a session scratchpad or other deep temp directory: Windows checkouts lose files past 260 chars when core.longpaths is off, and the loss is silent if clone output is piped. After cloning, compare git ls-files | wc -l against the upstream tree count.
2. Prepare the mirror locally. Record the exact upstream commit and file inventory, retain an upstream remote, and confirm target account, name, and visibility. Inspect upstream history for private material or secrets before any push; preserving history means a clean working tree alone cannot establish safe publication. A real finding blocks publication pending a user decision about history handling.
3. Overlay the firmware. Shallow-clone the template (also to a short path). Read .agents/template-manifest.json in that clone and strip every templateOnly path (the template README.md is one of them) and any .tmp* directories; do not keep a private copy of the list, the manifest is the source of truth. Copy the rest over with these collision rules: the adopted repo's own files always win (README.md, manifests, configs); .gitignore is merged by appending the template's entries under a # Harness comment; report any other collision instead of resolving it silently. If the adopted repo has an .agents/skill-locks.json, copy nothing into the .claude/skills/<name>/ or .agents/skills/<name>/ folder of a skill it locks; a lock file that cannot be read or parsed stops the overlay. Then confirm every requiredFiles path in the manifest exists in the adopted repo.
4. Privacy sweep before committing or publishing. The overlay may travel to reviewers or clients. Grep it for email addresses, personal names, client or project identifiers, and key/secret/token patterns; exclude generic prose hits. Anything real stays out and gets reported.
5. Commit the overlay locally as its own commit (subject notes the template and that template-only files were stripped). Honor the adopted repo's commit convention. Do not publish until collision resolution, privacy checks, configuration, and preservation checks below complete.
6. Run the init-project skill. It fills CLAUDE.md's FILL IN sections from the detected stack, seeds .claude/reference/, applies the skill profile, checks Codex skill registration, and wires the starter remote.
7. Verify and publish within authorization. Check configuration placeholders and compare against the recorded upstream commit. Original files remain byte-identical except the intentional .gitignore union and any explicitly approved collision resolution. Inspect those exceptions separately: retain all upstream ignore rules and record additions. Check the actual added-file inventory rather than assuming counts add across collisions. After all checks pass, create the target repo with the confirmed visibility, set origin, and push the preserved history plus overlay/configuration commits. Verify remote identity and visibility.

Hard rules

• Never force-push; never rewrite the upstream history that forms the base.
• Never modify upstream-pinned dependencies or build config during adoption; adoption adds the harness, nothing else.
• Fork only when the user explicitly wants the public upstream link and accepts that a fork of a public repo cannot be private; otherwise this clone-and-push flow is the default.