/migrate-legacy-engine — move the old brain into Cortex, then retire it safely

The earlier AI OS was an engine: a Node/MCP-server system that scattered generated context, a durable memory store, agents, and prompts across .ai-os/ and .github/. Cortex replaced it with plain files (AGENTS.md + shims + docs/decisions.md). This ritual moves any hand-verified knowledge out of the old engine into the new brain, then removes the old files.

The one rule: harvest before you delete

Engine memory is the only thing that isn't re-derivable from the code. Never rm an engine artifact until its knowledge is in AGENTS.md or docs/decisions.md. Re-generatable scaffolding (agents, prompts, dependency graphs, stack/architecture auto-dumps) can be dropped freely.

Step 0 — Confirm scope & require a clean git tree

• Work ONLY inside the target repo (default: cwd). Never touch the personal vault.
• If the cwd is not inside a git work tree (git rev-parse --show-toplevel fails), there is no target yet. Do not scan the directory you happen to be in: "no engine found" there answers a question nobody asked. Ask which repo is meant, and offer the git repos one level down as choices (ls -d */.git).
• Check git status is clean (or stash). The migration is recoverable via git + the backup archive, but a clean tree makes the diff reviewable.
• If there's no new brain yet (AGENTS.md absent), run /setup-repo first — this ritual enriches the brain, it doesn't create it.

Step 1 — Detect the old engine

The engine's two directories are read by a command, which writes nothing: node "${CLAUDE_PLUGIN_ROOT}/index/cortex-next.mjs" . --json. Its state.legacyEngine lists which of .ai-os (the MCP server) and .github/ai-os (config.json, manifest.json, context/, memory/, recommendations.md, tools.json) are there. Take that answer as it is and do not look for those two again.

The command looks for nothing else, so an empty list is not "no engine". Each of these is still a scan by hand, and one of them present means the engine was installed:

• An entry in .mcp.json / .vscode/mcp.json whose command or args point into .ai-os/. The path marks the engine's entry; the name does not. Cortex's own server was registered as ai-os until recently: an entry that runs …/mcp/server.js and carries CORTEX_ROOT (or AI_OS_ROOT, the older name for it) is a current Cortex registration under either name. It is not the engine. List it as "Cortex registration, kept" and leave it alone.
• .github/agents/*.agent.md, .github/copilot/**, .github/instructions/*.instructions.md, .github/skills/**, .github/COPILOT_CONTEXT.md, .github/workflows/ai-os-*.yml
• .vscode/*.chatprompt.md, .vscode/toolsets.json
• An engine-style .github/copilot-instructions.md (references MCP tools like get_session_context)

List exactly what exists before touching anything.

Two more places hold the old setup and are not in the checked-out tree. Both checks are read-only.

Other branches. A branch that is not checked out can still carry the engine, and a memory.jsonl on a forgotten branch is exactly what this ritual exists to save. Scan every local and remote-tracking ref:

git for-each-ref --format='%(refname:short)' refs/heads refs/remotes | while read -r ref; do
  git ls-tree -r --name-only "$ref" 2>/dev/null |
    grep -E '(^|/)(\.ai-os/|\.github/(ai-os|agents|copilot|instructions)/|\.github/COPILOT_CONTEXT\.md$|\.github/workflows/ai-os-)|\.chatprompt\.md$|(^|/)toolsets\.json$|(^|/)memory\.jsonl$' |
    sed "s|^|$ref: |"
done

Report the hits per branch. Harvest from a branch with git show <ref>:<path>, without checking it out. Removing files from another branch is that branch's own change: name it to the user and leave it to them.

MCP registrations outside the repo. A server can be registered at user scope, where no file in the repo shows it. Run claude mcp list, then claude mcp get <name> for each server that could be either kind: it prints the scope, the command and the environment. Sort each into one of two:

• The engine's: its command points into a .ai-os/ directory. It goes with the engine.
• A Cortex registration: its command ends in mcp/server.js outside any .ai-os/, and it carries CORTEX_ROOT, or AI_OS_ROOT on one made under the older name. It is not the engine, whatever it is called, ai-os included. List it with its root. It is only this migration's business when that root is inside something Step 5 deletes, or inside a repo that is no longer there: then it will stop starting.

Step 2 — Harvest (high-signal → into the brain)

Read these, pull only durable, verified facts, and fold them in:

Rules while harvesting:

• Dedupe. If AGENTS.md already says it, skip it.
• Verify against the code. Memory can be stale. If a fact names a file/flag, confirm it still exists before promoting it. Drop or correct anything wrong.
• Keep it factual and concise — one line per fact, evidence-based.
• Route to the right brief. If a fact is specific to a critical area that has (or should have) a scoped AGENTS.md leaf, put it in that leaf — not root. (e.g. RAG/embedding facts → src/lib/AGENTS.md, webhook/raw-body facts → the webhooks leaf.) Offer to run /write-area-brief for areas the harvested memory clusters around. Global facts go in root; area facts go in the leaf.
• Do NOT copy engine mechanics (MCP tool names, get_session_context, session protocols) — those die with the engine.

Step 3 — Record the migration

Append a dated entry to docs/decisions.md: what was migrated, how many memory facts were folded in, and what was removed. This is the audit trail.

Step 4 — Back up everything you're about to delete

Before any rm, archive the full old-engine footprint so nothing is ever truly lost:

tar -czf ai-os-engine-backup-$(date +%Y%m%d).tar.gz \
  .ai-os .github/ai-os .github/agents .github/copilot .github/instructions \
  .github/skills .github/COPILOT_CONTEXT.md .github/workflows/ai-os-*.yml \
  .github/copilot-instructions.md.bak* .vscode/*.chatprompt.md .vscode/toolsets.json \
  .mcp.json .vscode/mcp.json 2>/dev/null || true

Keep the tarball outside the repo (or add it to .gitignore). Git history is the second safety net.

Step 5 — Remove the old engine

Delete only what you backed up and harvested:

• rm -rf .ai-os .github/ai-os .github/agents .github/copilot .github/instructions .github/skills
• rm -f .github/COPILOT_CONTEXT.md .github/workflows/ai-os-*.yml
• rm -f .vscode/*.chatprompt.md .vscode/toolsets.json (leave the user's own settings.json)
• .mcp.json / .vscode/mcp.json: remove just the entry that points into .ai-os/. If it was the only entry, delete the file. An entry that runs Cortex's mcp/server.js stays, under the name ai-os too: Step 1 listed it as a Cortex registration.
• .github/copilot-instructions.md: replace engine content with a shim → AGENTS.md (or leave the Cortex shim if /setup-repo already wrote one). Move old *.bak into the tarball.
• A registration listed in Step 1 that is the engine's, or whose root you are deleting: repoint it or remove it, with the user's yes. claude mcp get <name> prints the exact remove command for its scope.
• Clean stragglers: .gitignore lines that only referenced .ai-os/.github/ai-os; the eslint.config.mjs .ai-os/** ignore.

Step 6 — Verify

• No engine artifacts remain: Step 1 again, the command and the scan → legacyEngine is [] and the scan finds nothing.
• The branch scan is run again. Hits on other branches are listed as still there, never as cleaned.
• Every registration from Step 1 points at a root that exists, or is gone.
• AGENTS.md now contains the harvested facts; docs/decisions.md has the migration entry.
• The backup tarball exists.
• npm run lint (or the repo's lint) still passes.
• Show the user the diff and the list of removed paths. Done.

Rules

• Harvest-before-delete is non-negotiable.
• Idempotent: safe to re-run; if nothing matches Step 1, report "no engine found" and stop.
• One repo at a time. Never promote company code/data into the personal vault.