feat(setup): install/uninstall primary commands; adopt/unadopt aliases by potiuk · Pull Request #913 · apache/magpie

potiuk · 2026-07-19T14:27:56Z

Now that Magpie can be installed from agent marketplaces (#907), "install" is the more familiar term than "adopt." This makes install/uninstall the primary command surface, with adopt/unadopt kept as aliases (nothing breaks for anyone using them).

Changes

/magpie-setup install — first-time install (the default no-arg action); /magpie-setup adopt is a documented alias.
/magpie-setup uninstall — reverses it; /magpie-setup unadopt is a documented alias.
Renamed skills/setup/adopt.md → install.md, skills/setup/unadopt.md → uninstall.md, and docs/setup/unadopt.md → uninstall.md; all path references repointed.
Updated the skill's argument-hint, sub-action list, and command table.

Deliberately kept

The "adopter" / "adopter repo" noun (the ecosystem role) — unchanged.
The "Adopt a Magpie" landing-page slogan.
Deep internal prose still uses "adopt" informally (a valid alias) — the full verb reword is PR B (follow-up).

Scope: command surface + file renames only. Part of the adoption→installation terminology shift discussed on the list.

potiuk · 2026-07-26T18:17:22Z

Looking for reviews :)

milamberspace

Reviewed the full diff (24 files), CI, and the current state of main. This is a clean, backward-compatible terminology refactor — nicely done. Verified that every file on main referencing adopt.md / unadopt.md is repointed here, so the rename leaves no dangling links, and the renames preserve history. CI is all green.

Two things before merge:

Rebase needed — the PR is currently conflicting. main has moved since this branched: #902 (Codex CLI runtime) edited adopt.md and unadopt.md after the branch point, which creates a rename/edit conflict. The good news is #902 added no new references to the old filenames elsewhere, so the rebase is just folding its content edits into the renamed install.md / uninstall.md.
Consistency nit in skills/setup/SKILL.md. The line

Main-checkout-only sub-actions (adopt, upgrade, unadopt) …

still names the old primaries. It's harmless (they're valid aliases), but for consistency with making install/uninstall primary it'd read better as install, upgrade, uninstall.

Process checks (per AGENTS.md): since this touches skills, worth confirming the setup eval suite still passes (a pure rename shouldn't move behavior, but the rule asks for it) and that tools/spec-loop/.last-sync is current before pushing the rebase.

Nothing blocking on the substance — LGTM once rebased and the SKILL.md line is updated.

choo121600

looks good :)

milamberspace

Reviewed the command-surface change and the renames — the dispatch logic looks right: no-arg → install.md, and install / adopt both route to install.md (adopt as a documented alias), same for uninstall / unadopt. Backward compatibility is preserved, and the repointed anchors (#local-self-adoption-methodlocal, #step-5, #step-12) all resolve in the renamed install.md. No broken links within the PR's own tree.

One thing that will bite on rebase, though: docs/rfcs/RFC-AI-0007.md landed on main after this branch's point, and line 184 still links to the old filename:

- [`skills/setup/SKILL.md`](../../skills/setup/SKILL.md),
  [`adopt.md`](../../skills/setup/adopt.md),
  [`upgrade.md`](../../skills/setup/upgrade.md) — the flow this RFC rewires.

Once this PR is rebased onto current main, that becomes a dangling link and the lychee link-check hook fails in CI. .gitignore:9 carries the same stale reference (see skills/setup/adopt.md → "Local self-adoption") — cosmetic, but worth fixing in the same pass. Both just need repointing to install.md. I confirmed the CI failure reproduces by cherry-picking the three commits onto a current-main-based branch.

Minor (probably your "PR B" scope): a couple of command-token spots in skills/setup/SKILL.md still name the alias rather than the primary — line 404 Main-checkout-only sub-actions (adopt, upgrade, unadopt) and line 439 *(unadopt only)*. Non-blocking.

Otherwise this reads well and the install/uninstall surface is a clear improvement. Happy to see it land once the rebase repoints those two references.

choo121600 · 2026-08-26T00:05:41Z

I think we need to rebase :)

potiuk · 2026-08-26T08:50:11Z

@choo121600 - rebased

choo121600

Cool 😀

potiuk · 2026-08-26T08:56:31Z

Rebased again after other merges - needs re-approve @choo121600

potiuk · 2026-08-26T09:03:56Z

#1116 - should fix those

Now that Magpie can be installed from agent marketplaces, 'install' is the more familiar term than 'adopt'. Make it the primary command surface: - /magpie-setup install (default, no-arg) is first-time install; 'adopt' is a documented alias. - /magpie-setup uninstall reverses it; 'unadopt' is a documented alias. - Rename adopt.md -> install.md, unadopt.md -> uninstall.md (skills + docs); repoint all path references. - Keep the 'adopter'/'adopter repo' noun and the 'Adopt a Magpie' slogan. Command surface only (PR A). The wider docs/skills prose reword of the adopt->install verb is a separate follow-up (PR B).

…' for the mechanism Per the terminology model: a project *adopts* Magpie (the relationship); the *installation* is the process/mechanism. Restores 'Adopt and maintain ... via the snapshot-based installation mechanism' in the skill description; the install/uninstall command names and adopt/unadopt aliases are unchanged.

…s install - Reword process-y 'adoption/adopt flow' phrases to 'install/installation' where they describe the mechanism (the adopt/install flow, first-time install, during installation, install recipe/instructions, uninstall flow), and prefer '/magpie-setup install' in how-to steps. Relationship/noun uses ('adopter', 'adopter repo', 'a project adopts Magpie', 'adoption model') and the adopt/unadopt aliases are left untouched. - Add an 'Adoption vs. installation' note to docs/setup/README.md: a project ADOPTS Magpie (relationship); INSTALLATION is the process (adopt = alias).

The `skills/setup/adopt.md` → `install.md` rename in this PR missed one reference, in RFC-AI-0007's References section. `lychee` caught it and failed the required `prek` status: [./docs/rfcs/RFC-AI-0007.md]: [ERROR] .../skills/setup/adopt.md (at 184:3) | File not found. A repo-wide sweep for `adopt.md` / `unadopt.md` finds no other stale reference, and `prek run --all-files` now passes clean.

…tall.md The apache#913 rebase repointed two of the three adopt.md links in this file but missed the one inside the settings.local.json wiring bullet this PR adds, which is what the CI link validator (prek, validate skills and tool contracts) has been failing on.

potiuk marked this pull request as ready for review July 20, 2026 14:45

milamberspace reviewed Jul 29, 2026

View reviewed changes

choo121600 previously approved these changes Jul 29, 2026

View reviewed changes

potiuk force-pushed the feat/setup-install-command branch from 9210ebb to 8adc5a0 Compare August 1, 2026 02:33

potiuk dismissed choo121600’s stale review via 8adc5a0 August 17, 2026 10:44

potiuk mentioned this pull request Aug 17, 2026

feat(marketplace): distribute Magpie 0.2.0 via agent marketplaces + auto-upgrade hook #907

Merged

milamberspace reviewed Aug 18, 2026

View reviewed changes

AmirF194 mentioned this pull request Aug 26, 2026

fix(setup): wire the agent-guard hook into settings.local.json, not settings.json #1115

Open

21 tasks

potiuk force-pushed the feat/setup-install-command branch from 8adc5a0 to 55f5594 Compare August 26, 2026 08:50

choo121600 previously approved these changes Aug 26, 2026

View reviewed changes

potiuk dismissed choo121600’s stale review via 07b2080 August 26, 2026 08:56

potiuk force-pushed the feat/setup-install-command branch from 55f5594 to 07b2080 Compare August 26, 2026 08:56

choo121600 approved these changes Aug 26, 2026

View reviewed changes

potiuk added 3 commits August 26, 2026 13:36

potiuk force-pushed the feat/setup-install-command branch from 07b2080 to fb6db1d Compare August 26, 2026 11:36

potiuk merged commit 72dbd74 into apache:main Aug 26, 2026
10 checks passed

Navigation Menu

Uh oh!

feat(setup): install/uninstall primary commands; adopt/unadopt aliases - #913

feat(setup): install/uninstall primary commands; adopt/unadopt aliases#913
potiuk merged 4 commits into
apache:mainfrom
potiuk:feat/setup-install-command

potiuk commented Jul 19, 2026

Uh oh!

potiuk commented Jul 26, 2026

Uh oh!

milamberspace left a comment

Uh oh!

choo121600 left a comment

Uh oh!

milamberspace left a comment

Uh oh!

choo121600 commented Aug 26, 2026

Uh oh!

potiuk commented Aug 26, 2026

Uh oh!

choo121600 left a comment

Uh oh!

potiuk commented Aug 26, 2026 •

edited

Loading

Uh oh!

potiuk commented Aug 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

potiuk commented Jul 19, 2026

Changes

Deliberately kept

Uh oh!

potiuk commented Jul 26, 2026

Uh oh!

milamberspace left a comment

Choose a reason for hiding this comment

Uh oh!

choo121600 left a comment

Choose a reason for hiding this comment

Uh oh!

milamberspace left a comment

Choose a reason for hiding this comment

Uh oh!

choo121600 commented Aug 26, 2026

Uh oh!

potiuk commented Aug 26, 2026

Uh oh!

choo121600 left a comment

Choose a reason for hiding this comment

Uh oh!

potiuk commented Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

potiuk commented Aug 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

potiuk commented Aug 26, 2026 •

edited

Loading