Adopt Repo

---
name: adopt-repo
description: "Mirror external repo privately under user's account + overlay firmware: clone, strip template-only files, privacy-sweep, init-project. Use: /adopt-repo <url>, 'pull this repo into our firmware'."
disable-model-invocation: true
---

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