106 lines
5.6 KiB
Markdown
106 lines
5.6 KiB
Markdown
# AGENTS: Neovim Config Migration
|
||
|
||
Scope: applies to the entire `~/.config/nvim` directory tree.
|
||
|
||
This repository is being migrated to a modern, minimal Neovim setup driven by Lua and lazy.nvim. Follow these rules when making changes.
|
||
|
||
## Goals
|
||
- Modern Lua-first config; avoid Vimscript unless explicitly requested.
|
||
- Keep it minimal, fast, and maintainable.
|
||
- Base plugin management on `lazy.nvim` with modular plugin specs.
|
||
- Support tab-per-context workflow with Neo-tree per tab, Telescope navigation, LSP, Treesitter, Copilot, and sane UX defaults.
|
||
|
||
## Do Not Reintroduce
|
||
- Custom Vimscript tabline/statusline, foldtext, UI hacks.
|
||
- Legacy autocommands toggling cursorline/column per window.
|
||
- CoC or CoC-specific config.
|
||
- netrw settings (Neo-tree will be used).
|
||
- Providers for ruby/perl/node (disable unless required by a plugin).
|
||
- Auto-reload vimrc-on-write templates.
|
||
- `cursorcolumn` and old folding logic not related to UFO.
|
||
|
||
## Repository Structure (target)
|
||
```
|
||
~/.config/nvim/
|
||
├── init.lua -- entrypoint; bootstraps lazy.nvim and loads Lua modules
|
||
└── lua/
|
||
├── settings.lua -- non-plugin options
|
||
├── keymaps.lua -- non-plugin keymaps
|
||
├── autocmds.lua -- non-plugin autocommands
|
||
├── abbreviations.lua -- insert-mode abbreviations
|
||
├── netrw-config.lua -- netrw configuration
|
||
├── utils.lua -- helpers (only if needed)
|
||
└── plugins/ -- one file per plugin or domain
|
||
├── telescope.lua
|
||
├── treesitter.lua
|
||
├── cmp.lua
|
||
├── lsp.lua
|
||
├── copilot.lua
|
||
├── oil.lua
|
||
├── ufo.lua
|
||
├── gitsigns.lua
|
||
└── none-ls.lua
|
||
```
|
||
|
||
## Coding Conventions
|
||
- Use Lua APIs: `vim.opt`, `vim.api.nvim_create_autocmd`, `vim.keymap.set`.
|
||
- No inline Vimscript or `vim.cmd` blocks unless strictly necessary.
|
||
- Keep plugin configuration self-contained in its plugin spec file.
|
||
- Prefer small, readable modules and minimal configuration over heavy customization.
|
||
- Keymaps: use `vim.keymap.set` with `{ silent = true, noremap = true }` defaults unless otherwise required.
|
||
- Autocommands: group via `vim.api.nvim_create_augroup` and create specific, narrowly scoped autocmds.
|
||
- Avoid global state; return tables from modules and plugin specs.
|
||
|
||
## Plugin Management (lazy.nvim)
|
||
- Each plugin lives in `lua/plugins/<name>.lua` and returns a spec table.
|
||
- Use `opts = {}` for default options and `config = function(_, opts) ... end` for setup.
|
||
- Do not install any plugin not listed without explicit user confirmation (proposal and rationale are welcome).
|
||
- Approved additions: `folke/neoconf.nvim` for project-local configuration.
|
||
|
||
## Required Plugin Categories
|
||
- Core: `nvim-lspconfig`, `nvim-cmp`, `cmp-nvim-lsp`, `cmp-buffer`, `cmp-path`, `LuaSnip`.
|
||
- Navigation: `neo-tree.nvim`, `telescope.nvim` (+ optional `telescope-fzf-native.nvim`).
|
||
- Treesitter: `nvim-treesitter`, `nvim-treesitter-textobjects`, `nvim-ts-autotag`.
|
||
- UX/Editing: `Comment.nvim`, `surround.nvim`, `nvim-autopairs`, `indent-blankline.nvim`, `leap.nvim` or `flash.nvim`, `nvim-ufo`, `undotree` (optional).
|
||
- Git: `gitsigns.nvim`.
|
||
- Markdown: `render-markdown.nvim`.
|
||
- Copilot: `copilot.lua`, `copilot-cmp`.
|
||
- Formatting: `none-ls.nvim`.
|
||
|
||
## Workflow Requirements to Preserve
|
||
- Tab-per-context: each tab has its own Neo-tree root.
|
||
- Provide keymaps for: Neo-tree floating, Neo-tree sidebar toggle, and file preview. Previews should not pollute buffer list.
|
||
- Keep splits inside tabs.
|
||
- Use Telescope and LSP for navigation.
|
||
- Heavy HTML/PHP/JS/Markdown usage (WordPress plugin dev) — prioritize these languages in LSP/Treesitter.
|
||
|
||
## Behaviours to Keep (modernized)
|
||
- Abbreviations: `adn→and`, `waht→what`, `tehn→then`, `functin→function`, `positin→position`.
|
||
- Templates: auto-populate `.sh` from template.
|
||
- Whitespace highlighting (use modern alternatives, e.g., `listchars`, plugins if needed).
|
||
- Persistent folds (prefer `nvim-ufo`).
|
||
- Spell & text: `spelllang=en_gb`, custom `listchars`, `showbreak`.
|
||
|
||
## Migration Notes
|
||
- Do not edit legacy Vimscript files except to extract settings to Lua. Keep them intact until migration completes.
|
||
- Introduce `init.lua` and bootstrap `lazy.nvim` before adding plugins.
|
||
- Disable unnecessary providers early: `vim.g.loaded_ruby_provider = 0`, etc.
|
||
- Keep startup fast; avoid unnecessary autoloading or heavy defaults.
|
||
- When cleaning, archive existing files into a `legacy/` folder within this config instead of deleting. Maintain a brief index if helpful.
|
||
|
||
## Validation
|
||
- Ensure Neovim starts without errors and with minimal startup time.
|
||
- Verify tab workflow, Neo-tree behaviour, Telescope, LSP basics, and completion.
|
||
- Keep plugin count tight; remove anything unused.
|
||
|
||
## Process
|
||
- Before large changes, update the task plan via the CLI `update_plan` tool.
|
||
- Keep the live checklist in `MIGRATION_PLAN.md:1` up to date and in sync with changes.
|
||
- After any config or plugin change, immediately update `MIGRATION_PLAN.md` (check off items, add notes, or adjust next steps).
|
||
- After any change or decision, also update `README.md:1` (decisions log and design docs).
|
||
- At the start of each phase, confirm scope and priorities for that phase.
|
||
- Execute phases via subphases (`N.x`), where each bullet under a phase is its own implement-and-test step (e.g., Phase 3.1, 3.2, 3.3, 3.4).
|
||
- Record decisions and rationale in `README.md:1` as they’re made.
|
||
- Keep PR-sized patches; avoid broad unrelated edits.
|
||
- Document non-obvious choices in commit messages or short comments near the code that needs it.
|