Table of Contents generated with DocToc

Removing Magpie from an adopter repo (unadopt)

If your project has decided to stop using Magpie, or the adoption was experimental and is now over, this page walks through the removal. It reverses everything an install recipe in install-recipes.md and the subsequent /magpie-setup interactive flow put into your repo.

You may not actually want this. To change install method or version, use /magpie-setup upgrade — it keeps your overrides and re-uses the existing wiring. To temporarily detach a single skill for debugging, edit the relevant file under .apache-magpie-overrides/ instead.

Quick removal

If you’ve already decided and want to act fast — from the main checkout of the adopter repo:

/magpie-setup unadopt    # surfaces a plan, asks for confirmation, then removes

Read on for prerequisites, what the confirmation prompt looks like, how to verify, and how to clean up what unadopt deliberately leaves behind.

Invocation

/magpie-setup unadopt              # default: preserves .apache-magpie-overrides/
/magpie-setup unadopt --purge-overrides
/magpie-setup unadopt dry-run      # print the plan; no writes, no confirmation

The flow refuses to run inside apache/magpie itself (the framework is not its own adopter).

What you’ll be asked to confirm

Before any write, the flow surfaces a single plan and asks for one explicit confirmation. The default selection is abort, not proceed. Each item appears only when present in your repo. The plan looks like:

The following will be REMOVED:

  Gitignored (no commit needed):
    .apache-magpie/                          (snapshot)
    .apache-magpie.local.lock
    .agents/skills/magpie-<skill-1>          → .apache-magpie/skills/<skill-1>/   (canonical)
    .claude/skills/magpie-<skill-1>          → ../../.agents/skills/magpie-<skill-1>   (relay)
    .github/skills/magpie-<skill-1>          → ../../.agents/skills/magpie-<skill-1>   (relay)
    .git/hooks/post-checkout                  (if it contains the Magpie recipe)

  Committed (will show in `git status`):
    .apache-magpie.lock                      (your project's pin)
    .gitignore                                (the Magpie entries)
    README.md                                 (the adoption section, if present)
    AGENTS.md                                 (the Magpie framework section, if present)
    CONTRIBUTING.md                           (the adoption section, if present)
    .agents/skills/magpie-setup/             (this skill itself — self-destructive; canonical copy)
    .claude/skills/magpie-setup              (relay symlink)
    .github/skills/magpie-setup              (relay symlink)

The following will be PRESERVED:

    .apache-magpie-overrides/                (pass `--purge-overrides` to remove)

The framework wires every skills dir the same way per the agent-target registry: .agents/skills/ holds the canonical magpie-* links into the snapshot; .claude/skills/ and .github/skills/ (and any holdout) hold relays into .agents/skills/. unadopt removes the magpie-* entries from every one of them. The skills directories themselves are adopter-owned and are not removed.

If --purge-overrides is passed, .apache-magpie-overrides/ moves into the removed section with its files listed explicitly. If any uncommitted edits exist under it, the flow warns and asks for a second confirmation.

Removal is destructive on disk and on the git index.

Verifying the removal

After the flow finishes, confirm the result:

git status                       # staged deletions / modifications
git diff --cached                # review patches before committing
ls .apache-magpie 2>/dev/null   # should print nothing — directory gone

You should see staged deletions for .apache-magpie.lock, your setup/ skill directory, and modifications to .gitignore plus any of README.md / AGENTS.md / CONTRIBUTING.md that had adoption sections. Pay extra attention to the .gitignore and doc patches — those are the lines most likely to need a human re-read before committing. On disk, .apache-magpie/ and .apache-magpie.local.lock should no longer exist.

If anything is missing or unexpected — or if removal failed partway through — the canonical per-step plan, including failure modes, lives in .claude/skills/magpie-setup/unadopt.md. That’s the procedure the agent steps through when you invoke /magpie-setup unadopt.

What remains after unadopt — and how to remove it

unadopt only deletes content the adopt flow itself installed. Anything you authored, or anything that overlapped with the framework’s footprint but predates the adoption, is preserved on purpose.

.apache-magpie-overrides/

Your hand-written customisations: any per-skill overrides you filled in (e.g. pr-management-triage.md) and, if you used the fallback location instead of the recommended per-user one, a project-local user.md carrying identity and tool-picks (governance membership, local clone paths, etc.). Preserved because the content is yours, not the framework’s. Remove with:

git rm -r .apache-magpie-overrides/

Or use /magpie-setup unadopt --purge-overrides to do this in one step.

If unadopt flagged a symlink under your skills directory that resolved outside the framework snapshot — i.e. you wired up something extra at the same name post- adoption — it was left in place. Inspect and remove if no longer useful:

ls -l .claude/skills/    # find the flagged symlink(s)
rm .claude/skills/<name>

post-checkout hook with extra logic

If your .git/hooks/post-checkout contained anything beyond the Magpie verify --auto-fix-symlinks recipe, unadopt left the entire hook in place and told you which line to delete. Edit it by hand:

$EDITOR .git/hooks/post-checkout

Overlapping .gitignore entries

unadopt removes only the exact lines from the adopt template. If you had unrelated rules referencing .apache-magpie/ (e.g. a custom path under the snapshot dir), they remain. Audit and clean manually:

grep apache-magpie .gitignore

Outside-the-repo state

unadopt only touches your adopter repo. None of the following are removed — retire each one only if you are also retiring Magpie from this machine entirely:

  • ~/.config/apache-magpie/user.md — the recommended per-user identity / tool-picks config. One file, shared across every adopter repo on this machine. If you still use Magpie in any other repo, leave it. Otherwise:

    rm -i ~/.config/apache-magpie/user.md
rmdir ~/.config/apache-magpie 2>/dev/null    # only removes the dir if empty (errors silenced)

  • ~/.claude/ user-scope config, hooks, and settings — not framework-owned. Includes anything setup-shared-config-sync pushed to your private sync repo, which has its own lifecycle.

  • Framework checkout — your local clone of apache/magpie from setup-isolated-setup-install. Remove with rm -rf <path-to-clone> if no longer needed.

  • Per-user state from skills that wrote outside this repo — consult each skill’s docs.

Re-adopting later

Because unadoption deletes the setup skill itself, future /magpie-setup invocations resolve to nothing. To re-adopt, re-run an install recipe in install-recipes.md — the same path a first-time adopter takes.

See also

Suggest a change