migrate-from-legacy

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.

Step 6: Verify project state survived

After the script reports "Migration complete", run these checks:

test -f .claude/diamonds/active.yml && echo "diamonds preserved"
test -d .claude/canvas && echo "canvas preserved"
test -f .claude/memory/corrections.md && echo "corrections preserved"
test -f .claude/harness/decision-log.md && echo "decision-log preserved"
test ! -d .claude/skills && echo "legacy framework deleted"
test ! -d .claude/engine && echo "legacy engine deleted"

Then invoke /mycelium:diamond-assess to read the canvas and diamonds — this exercises the plugin reading project state through the new path resolution. If /mycelium:diamond-assess returns a coherent assessment, the migration is verified working.

If any project-state check fails, that's a bug in the migration script — surface it loudly to the user and recommend git reset --hard HEAD to revert.

Step 7: Settings.json hooks block (manual cleanup)

The migration script warns if .claude/settings.json contains a "hooks" block — that block likely points at the deleted .claude/hooks/ tree. In plugin form, hooks are wired via ${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json automatically; the settings-level hooks block is dead weight at best, double-firing or broken at worst.

Tell the user:

"Final manual step: open .claude/settings.json and remove the \"hooks\" block (if present). Plugin form provides hooks automatically. Also worth removing: any \"customCommands\" block referencing the legacy /foo skill names — they're now /mycelium:foo."

This step is manual because settings.json may contain user-customized content alongside the legacy hooks block, and I shouldn't auto-edit it.

Step 8: Final commit

Suggest the commit message:

git add -A
git commit -m "chore: migrate from legacy Mycelium to plugin form"

Then tell the user:

"Migration complete. Going forward:

• Upgrade Mycelium with /plugin update mycelium@haabe-mycelium
• Skill invocations use the mycelium: prefix; /myc<Tab> expands it
• Project state lives in .claude/, framework reference in plugin cache
• Cross-agent contributors see AGENTS.md (if present) for orientation"

Idempotency

This skill is safe to re-invoke. Step 1's detection routes already-migrated projects to early-exit. Step 5's script also detects already-migrated state and exits cleanly without further changes.

What this skill does NOT do

• Does NOT install the plugin for the user (Anthropic plugin install is a Claude Code surface, not callable from a skill).
• Does NOT modify .claude/settings.json (manual step in Step 7 — settings may contain user-owned content).
• Does NOT touch project root files (CLAUDE.md, README.md, etc.).
• Does NOT migrate non-Mycelium content under .claude/ — if the user has put their own files there, they survive.
• Does NOT roll back automatically on failure — the user can git reset --hard HEAD.

Theory grounding

• Brownfield-additive principle (Bentes 2026-05-08): user-owned files are not touched; only framework-reference content in .claude/ is removed.
• Idempotency (operations.md): re-running this skill is a no-op on already-migrated projects.
• Reversibility (escape-hatch.md): every migration commits to a known-good prior state via git, so users can git reset --hard HEAD if anything looks off.
• Liao contrastive XAI: Step 4 explicitly shows what will and will NOT change, contrasting framework reference (deleted) with project state (preserved) and root files (untouched).

Source

The migration surface was identified during 2026-05-09 plugin-form readiness review: existing legacy users (npx-degit installs) need a documented, scripted path forward, not just docs. Without this skill + the upgrade.sh --migrate-to-plugin flag, plugin form would be a fork-in-the-road for new users only — legacy users would either stay on legacy indefinitely or hand-migrate (error-prone). See docs/migration.md for the full prose explanation.