---
name: lisa-wiki-migrate
description: Migrate an existing, hand-rolled wiki implementation onto the lisa-wiki kernel — phased and compatibility-first, with a strict no-loss guarantee. Use when adopting lisa-wiki in a repo that already has its own wiki/, ingest skills, docs, or roles. Renaming things into the canonical shape is fine; losing functionality or data is not. Ends by running /doctor.
---

# lisa-wiki-migrate

Move a repo's bespoke wiki onto the kernel without breaking it or producing one giant diff. Each
phase is a reviewable change; nothing legacy is deleted until its replacement is parity-checked.

## Migration invariant — rename, never lose
Any unique command, ingest path, or role is migrated **as though created via** `/add-ingest`
(front-door skill) or `/add-role` (subagent); wiki-ingest aliases (`*-wiki-ingest`, custom `/ingest`
routers, …) are renamed to the canonical `/ingest`. **Loss of functionality or data is not
acceptable** — for each migrated artifact, run the old path and the new path and diff the output
before deleting the old one.

## Phases (per repo; one reviewable change each)
- **0 — Inventory.** Profile the repo: mode, root, categories, frontmatter coverage, log/index
  format, source dirs, state files, connectors, runtime surfaces, MCP config, scripts, PR policy.
  Write a pre/post manifest mapping every legacy page, source note, doc, command, ingest path, role.
- **1 — Adopt kernel (no content rewrite).** Add `wiki/lisa-wiki.config.json`, render the contract
  snapshot, add `wiki/state/README.md`, run validators in **warning** mode.
- **1b — Documentation absorption & structure.** `scripts/absorb-docs.mjs` moves the host repo's own
  docs (`docs/`, `specs/`, top-level docs) into `wiki/documentation/`, ingests them, and conforms to
  the structure manifest; `scripts/rewrite-refs.mjs` rewrites every internal link/citation/index
  entry (zero dangling links). Keep-in-place files stay at conventional paths. **Ask** the README
  mode (default `rich`; `stub` only on explicit choice). Wrapper mode moves only host docs, never
  child-project docs. Idempotent (source fingerprints); parity-checked.
- **2 — Runtime consolidation.** Replace duplicated local wiki skills with the plugin's; bespoke ones
  become `/add-ingest` front-doors or `/add-role` subagents. Claude commands become facades.
- **3 — Connector consolidation.** Centralize shared connectors (e.g. Slack); keep org-specific ones
  as contrib/overlay.
- **4 — Normalize by touch.** New/touched pages get frontmatter; new logs use the canonical table;
  legacy stays parseable until deliberately migrated.
- **5 — Hard enforcement.** Flip validators to hard-fail (and enable CI) once the baseline is clean.

## Finish
Run `lisa-wiki-doctor --migration`. The repo is not considered migrated until the verdict is `READY`
(or a human-approved `READY_WITH_WARNINGS`). Roll back by reverting the migration change.

## Related
`lisa-wiki-doctor`, `lisa-wiki-setup`, `lisa-wiki-add-ingest`, `lisa-wiki-add-role`.
