/migrate-from-legacy

name: migrate-from-legacy
description: Migrate a Mycelium project from legacy install (npx-degit, framework files in .claude/) to plugin install (framework lives in plugin cache, .claude/ holds project state only). Detects current install form, walks the user through plugin installation, runs the migration script, and verifies project state survived. Idempotent — safe to invoke on already-migrated projects.
metadata:
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."

Migrate from legacy to plugin form

When this skill runs, walk the user through moving from legacy install to plugin install. The migration is **non-destructive** to project state: canvas, diamonds, memory, decision log, evals, and active metrics are preserved. Only framework reference content (skills, hooks, engine, scripts, schemas, etc.) is removed from `.claude/` — that content now ships in the plugin cache.

Step 1: Detect current install form

Check the project's `.claude/` directory:

test -d "${CLAUDE_PROJECT_DIR:-.}/.claude/skills" && echo "legacy framework files present" || echo "no legacy framework files"
test -d "${CLAUDE_PROJECT_DIR:-.}/.claude/canvas" && echo "project state present" || echo "no project state"

Three states:

• **Legacy install** (skills/ + canvas/ both present): proceed to Step 2.
• **Already migrated** (canvas/ present, skills/ absent): tell the user "This project is already on plugin form. No migration needed." and exit.
• **Empty** (neither present): tell the user "No Mycelium install detected. Run `/mycelium:start` to bootstrap a fresh plugin install." and exit.

Step 2: Verify the plugin is installed

Ask the user to confirm the plugin is installed before deleting legacy framework files. If they don't have the plugin yet, deleting framework files would leave them with no Mycelium at all.

Tell them to run inside Claude Code:

/plugin marketplace add haabe/mycelium
/plugin install mycelium@haabe-mycelium

Then ask: "Is the plugin installed now?" Wait for confirmation before continuing. Acceptable answers: "yes", "installed", "done", or running `/mycelium:ping` to verify the plugin loaded (returns a deterministic marker if so).

If the user says no or seems uncertain, exit and tell them to come back after installing.

Step 3: Verify a clean working tree

The migration is reversible via git, so the project must be a git repo with a clean working tree before proceeding. Run:

cd "$CLAUDE_PROJECT_DIR"
git rev-parse --is-inside-work-tree  # must succeed
git diff-index --quiet HEAD --        # must succeed (no uncommitted changes)

If either check fails, tell the user:

> "Migration is reversible via git, so I need a clean working tree first. Either commit or stash your current changes: > > `git add -A && git commit -m 'Pre-migration snapshot'` > > Then re-run `/mycelium:migrate-from-legacy`."

Then exit.

Step 4: Show the user what will happen

Before running the migration, render this to the user:

> **Migration plan** — legacy → plugin form > > **Will DELETE** (framework reference content, now lives in plugin cache): > - `.claude/skills/`, `.claude/engine/`, `.claude/hooks/` > - `.claude/scripts/`, `.claude/schemas/`, `.claude/domains/` > - `.claude/orchestration/`, `.claude/templates/`, `.claude/tests/` > - `.claude/agents/` (if present) > - `.claude/jit-tooling/*` (except `active-metrics.yml`) > - `.claude/harness/*` (except `decision-log.md`, `warnings-log.md`) > > **Will PRESERVE** (project state): > - `.claude/canvas/` (your populated canvases) > - `.claude/diamonds/active.yml` (diamond state) > - `.claude/memory/` (corrections, patterns, journals) > - `.claude/evals/` (eval scenarios + dogfood reports) > - `.claude/state/` (runtime state, if present) > - `.claude/harness/decision-log.md`, `warnings-log.md` > - `.claude/jit-tooling/active-metrics.yml` > - `.claude/settings.local.json` (your local overrides) > > **Project root files** (CLAUDE.md, README.md, AGENTS.md, LICENSE, CONTRIBUTORS.md, etc.) are NOT touched. > > **Skill invocations change**: `/interview` becomes `/mycelium:interview`. Tab-completion (`/myc<Tab>`) expands the prefix; natural-language invocation ("run mycelium interview") also routes correctly. No alias mechanism in Anthropic's plugin spec. > > **Reversible**: `git reset --hard HEAD` before committing returns to pre-migration state. > > Continue?

Wait for explicit "yes." Anything else aborts.

Step 5: Run the migration script

The legacy `.claude/scripts/upgrade.sh` shipped with the user's project (from their last legacy refresh) supports a `--migrate-to-plugin` flag. Invoke it:

cd "$CLAUDE_PROJECT_DIR"
bash .claude/scripts/upgrade.sh --migrate-to-plugin

If the user's `upgrade.sh` is older than v0.20.10 (predates the migration flag), it will fail with "Unknown flag: --migrate-to-plugin". In that case, tell them to first refresh their legacy install with the standard upgrade:

bash .claude/scripts/upgrade.sh

This pulls the latest legacy framework content (including the migration-aware `upgrade.sh`). Then re-invoke `/mycelium:migrate-from-legacy`.

The script is interactive when run from a terminal — it asks for confirmation before deleting. When invoked from this skill in Claude Code's Bash tool, the script's `[ -t 0 ]` check fails (no TTY); it proceeds without prompting unless `MYCELIUM_MIGRATE_AUTO=cancel` is set. The user has already confirmed in Step 4, so non-interactive proceed is correct here.

If the script exits with a non-zero status, surface the error to the user and stop. Do not attempt manual cleanup — the script's atomic-deletion approach is the safer path; partial cleanup leaves the project in an unknown state.