Skip to content

docs(setup): fix pre-Magpie migration steps that became no-ops #877

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
potiuk merged 1 commit into from
Jul 15, 2026
Merged

docs(setup): fix pre-Magpie migration steps that became no-ops #877

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions docs/setup/install-recipes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
- [Method 3 — git branch (defaults to `main`)](#method-3--git-branch-defaults-to-main)
- [After any recipe — let the skill take over](#after-any-recipe--let-the-skill-take-over)
- [Subsequent runs and drift detection](#subsequent-runs-and-drift-detection)
- [Migrating a pre-Magpie (`apache-magpie`) adopter](#migrating-a-pre-magpie-apache-magpie-adopter)
- [Migrating a pre-Magpie (`apache-steward`) adopter](#migrating-a-pre-magpie-apache-steward-adopter)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Expand Down Expand Up @@ -262,26 +262,26 @@ and updates the local lock. See
[`setup/upgrade.md`](../../skills/setup/upgrade.md)
for the full flow.

## Migrating a pre-Magpie (`apache-magpie`) adopter
## Migrating a pre-Magpie (`apache-steward`) adopter

A repo that adopted the framework **before** it was renamed from
`apache-magpie` to **Apache Magpie** is on the old layout: a committed
`.claude/skills/magpie-setup/` skill, an `.apache-magpie/` snapshot,
`.apache-magpie.lock` / `.apache-magpie-overrides/`, un-prefixed
framework symlinks, and `~/.config/apache-magpie/`. The framework
`apache-steward` to **Apache Magpie** is on the old layout: a committed
`.claude/skills/setup-steward/` skill, an `.apache-steward/` snapshot,
`.apache-steward.lock` / `.apache-steward-overrides/`, un-prefixed
framework symlinks, and `~/.config/apache-steward/`. The framework
**no longer ships an automated migration** for this layout — migrate by
hand:

1. Remove the legacy in-repo artefacts: `.apache-magpie*` (snapshot,
1. Remove the legacy in-repo artefacts: `.apache-steward*` (snapshot,
locks, overrides), any un-prefixed framework symlinks under the
skills dir, and the committed `.claude/skills/magpie-setup/` skill.
skills dir, and the committed `.claude/skills/setup-steward/` skill.
2. Re-adopt from scratch with `/magpie-setup` (see
[`setup/adopt.md`](../../skills/setup/adopt.md)) so the current
`.apache-magpie*` layout and `magpie-`-prefixed symlinks are written
fresh. Preserve any `.apache-magpie-overrides/*.md` you want to keep
fresh. Preserve any `.apache-steward-overrides/*.md` you want to keep
by moving them into the new `.apache-magpie-overrides/` first.
3. Move `~/.config/apache-magpie/` (per-user) to
`~/.config/apache-magpie/`, and update any `~/.config/apache-magpie/`
3. Move `~/.config/apache-steward/` (per-user) to
`~/.config/apache-magpie/`, and update any `~/.config/apache-steward/`
entry in your Claude Code sandbox allowlist (project
`.claude/settings.local.json` / `.claude/settings.json` or user-scope
`~/.claude/settings.json`) to `~/.config/apache-magpie/` — otherwise
Expand Down