nvim/MIGRATION_PLAN.md

Neovim Migration Checklist

Source of truth for the step-by-step rebuild. Keep this concise and up to date. See details in neovim-migration-guide.md.

Phase 0 — Ground Rules

• Create AGENTS.md with rules

Phase 1 — Clean & Archive Legacy Config

Phase 1.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 1.2 — Inventory legacy files

• Inventory existing Vimscript, plugin files, and directories

Phase 1.3 — Create archive location

• Create legacy/ archive folder within this config

Phase 1.4 — Move legacy files into archive

• Move legacy init files and plugin directories into legacy/ (do not delete)

Phase 1.5 — Document archived contents

• Optionally add legacy/README.md noting what was archived

Phase 1.6 — Preserve selected directories

• Keep undodir, spell, view, UltiSnips, templates as-is for now (review later)

Phase 2 — Bootstrap

Phase 2.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 2.2 — Scaffold Lua config skeleton

• Scaffold Lua config skeleton (init.lua, lua/settings.lua, lua/keymaps.lua, lua/autocmds.lua, lua/utils.lua, lua/plugins/)

Phase 2.3 — Bootstrap lazy.nvim

• Bootstrap lazy.nvim plugin manager

Phase 2.4 — Disable unused providers

• Disable unused providers (ruby, perl, node)

Phase 2.5 — Ensure lazy boots without specs

• Ensure lazy boots without specs (add empty lua/plugins/init.lua)

Phase 3 — Core Editing & LSP

Phase 3.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 3.2 — Non-plugin settings to Lua

• Port non-plugin settings to Lua (options, listchars, showbreak, spelllang=en_gb)

Phase 3.3 — Core completion stack

• Add core completion stack: nvim-cmp, cmp-nvim-lsp, cmp-buffer, cmp-path, LuaSnip

Phase 3.4 — LSP minimal defaults

• Add nvim-lspconfig with minimal defaults (no over-configuration)

Phase 4 — Navigation

Phase 4.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 4.2 — Neo-tree setup

• Add neo-tree.nvim with per-tab roots, sidebar toggle, floating view, and preview keymap (no buffer pollution)

Phase 4.3 — Telescope setup

• Add telescope.nvim (+ optional telescope-fzf-native.nvim) and basic pickers

Phase 5 — Treesitter

Phase 5.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 5.2 — Base Treesitter

• Add nvim-treesitter with incremental selection, highlighting

Phase 5.3 — Treesitter textobjects

• Add nvim-treesitter-textobjects

Phase 5.4 — Treesitter autotag

• Add nvim-ts-autotag

Phase 6 — UX / Editing

Phase 6.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 6.2 — Comment.nvim

• Add numToStr/Comment.nvim

Phase 6.3 — Surround

• Add kylechui/nvim-surround

Phase 6.4 — Autopairs

• Add windwp/nvim-autopairs

Phase 6.5 — Indent guides

• Add lukas-reineke/indent-blankline.nvim

Phase 6.6 — Motion (leap/flash)

• Add ggandor/leap.nvim or folke/flash.nvim

Phase 6.7 — Folding (UFO)

• Add kevinhwang91/nvim-ufo for folding

Phase 6.8 — Optional: Undotree

• (Optional) Add mbbill/undotree

Phase 7 — Git, Markdown, Copilot, Formatting

Phase 7.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 7.2 — Git

• Add lewis6991/gitsigns.nvim

Phase 7.3 — Markdown

• Add render-markdown.nvim

Phase 7.4 — Copilot

• Add zbirenbaum/copilot.lua + copilot-cmp

Phase 7.5 — Formatting

• Add nvimtools/none-ls.nvim with minimal formatters/linters

Phase 8 — Migrate Kept Behaviours

Phase 8.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 8.2 — Abbreviations

• Abbreviations: adn→and, waht→what, tehn→then, functin→function, positin→position

Phase 8.3 — Templates

• Templates: auto-populate new .sh from template

Phase 8.4 — Whitespace highlighting

• Whitespace highlighting (modern approach)

Phase 8.5 — Persistent folds

• Persistent folds (via UFO)

Phase 9 — Cleanup & Validation

Phase 9.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 9.2 — Retire legacy files

• Retire legacy Vimscript files (keep for reference until verified)

Phase 9.3 — Startup performance

• Validate startup performance (no errors, fast launch)

Phase 9.4 — Tab workflow validation

• Validate tab-per-context workflow with Neo-tree

Phase 9.5 — Navigation validation

• Validate Telescope navigation + LSP jumps

Phase 9.6 — Language tooling validation

• Validate HTML/PHP/JS/Markdown tooling

---

Notes:

• Keep plugin specs minimal; configure in their own lua/plugins/*.lua files.
• Avoid adding plugins not listed in the guide unless explicitly requested.
• Prefer simple defaults; only add settings that clearly improve workflow.