From 7a98fa5b5c7232a2a553d4f93a029047c9913456 Mon Sep 17 00:00:00 2001 From: ray Date: Mon, 5 Jan 2026 20:31:36 +0000 Subject: [PATCH] consolidate and update agent instruction files --- .github/copilot-instructions.md | 192 +++----------------------------- AGENTS.md | 37 ++++++ REGRESSION_FIX_2025-12-07.md | 2 +- 3 files changed, 56 insertions(+), 175 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6e815c0..d17e9fd 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,183 +1,27 @@ # Neovim Config - AI Agent Instructions -## Project Overview -Modern Lua-first Neovim configuration using lazy.nvim, currently in active migration from legacy Vimscript. Target: minimal, fast, tab-per-context workflow with Neo-tree, Telescope, LSP, and Copilot. +**All agent instructions are in `AGENTS.md` at the repository root.** -**Critical**: Read `AGENTS.md` first—it defines all coding rules, migration strategy, and what NOT to reintroduce. +This file exists to satisfy GitHub Copilot's convention of looking for instructions in `.github/copilot-instructions.md`. -## Architecture & Files +## Quick Reference -``` -~/.config/nvim/ -├── init.lua # Entry point: loads settings/keymaps/autocmds, bootstraps lazy.nvim -├── lua/ -│ ├── settings.lua # Non-plugin vim options (exrc, secure, spelllang, listchars) -│ ├── keymaps.lua # Non-plugin keymaps -│ ├── autocmds.lua # Non-plugin autocommands -│ ├── abbreviations.lua # Insert-mode abbreviations (typo corrections) -│ ├── netrw-config.lua # Netrw configuration -│ └── plugins/ # One file per plugin/domain (lazy.nvim specs) -│ ├── lsp.lua # LSP via vim.lsp.config + vim.lsp.enable (Neovim 0.11+) -│ ├── cmp.lua # Completion: nvim-cmp + LuaSnip -│ └── mason*.lua # LSP server installation -├── AGENTS.md # PRIMARY: All rules, migration plan, do-not-reintroduce list -├── MIGRATION_PLAN.md # Phase-by-phase checklist (source of truth for progress) -├── LOG.md # Decision log and design rationale -└── legacy/ # Archived Vimscript (do not edit; reference only) -``` +- **Primary instructions**: See `/home/ray/.config/nvim/AGENTS.md` +- **Migration plan**: See `MIGRATION_PLAN.md` +- **Decision log**: See `LOG.md` +- **Keymap reference**: See `README.md` -## Critical Patterns +## Key Rules (Summary) -### 1. LSP Configuration (Phase 3 Complete) -**Modern API (Neovim 0.11+)**: Uses `vim.lsp.config()` + `vim.lsp.enable()`, NOT `require('lspconfig')[server].setup()`. +1. **Read `AGENTS.md` first** - it contains all coding rules, architecture decisions, and what NOT to reintroduce +2. **Update docs after changes**: + - Config changes → update `MIGRATION_PLAN.md` + - Decisions → update `LOG.md` + - Keymap changes → update `README.md` +3. **Modern Lua-first**: Use `vim.opt`, `vim.keymap.set`, `vim.api` - avoid Vimscript +4. **LSP (Neovim 0.11+)**: Use `vim.lsp.config()` + `vim.lsp.enable()`, NOT lspconfig `.setup()` +5. **Project config**: Native `exrc` + `secure`, no neoconf plugin +6. **No new plugins** without explicit user approval -**CRITICAL (2025-12-07)**: Neovim 0.11+ does NOT support `on_new_config` callback. Use `LspAttach` autocmd instead. +For complete details, workflow requirements, architecture decisions, and troubleshooting, see `AGENTS.md`. -```lua --- lua/plugins/lsp.lua pattern: --- Define config -vim.lsp.config(server_name, { - capabilities = capabilities, - -- NO on_attach here, NO on_new_config here -}) - --- Enable server -vim.lsp.enable({ "lua_ls", "intelephense", ... }) - --- Load project settings via LspAttach autocmd -vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) - local client = vim.lsp.get_client_by_id(args.data.client_id) - -- Load .nvim.lua from client.root_dir - -- Merge into client.settings - -- Send workspace/didChangeConfiguration notification - end, -}) -``` - -**Key decisions**: -- No neoconf (incompatible with Neovim 0.11+, issue #116) -- Native `exrc` + `secure` for project config (see settings.lua) -- Project settings loaded via `LspAttach` autocmd (NOT `on_new_config` which is deprecated) -- `workspace/didChangeConfiguration` sent after merging settings into `client.settings` - -### 2. Project-Local Configuration -**Format**: `.nvim.lua` at project root, returns: -```lua -return { - lsp = { - intelephense = { - settings = { - intelephense = { - environment = { - includePaths = { "/absolute/path/to/external/lib" } - } - } - } - } - } -} -``` - -**Security**: `vim.opt.secure = true` prompts user before loading (one-time per file hash). Trusted files stored in `~/.local/state/nvim/trust`. - -### 3. Plugin Management -- **lazy.nvim**: All plugins in `lua/plugins/` as individual files returning spec tables -- **Mason**: Installs LSP servers only; custom lspconfig setup retained -- **Plugin specs**: Use `opts = {}` for defaults, `config = function(_, opts)` for setup -- **Approval policy**: Do not install unlisted plugins without explicit user confirmation - -### 4. Tab-Per-Context Workflow (Future Phase 4) -- Each tab maintains own Neo-tree root -- Splits stay within tabs -- Neo-tree: sidebar toggle + floating view + preview (no buffer pollution) -- Heavy PHP/HTML/JS/Markdown usage (WordPress plugin dev) - -## Conventions - -### Code Style -- **Lua APIs only**: `vim.opt`, `vim.keymap.set`, `vim.api.nvim_create_autocmd` -- **No Vimscript**: Avoid `vim.cmd` blocks unless strictly necessary -- **Keymaps**: `{ silent = true, noremap = true }` by default -- **Autocommands**: Group via `vim.api.nvim_create_augroup`, narrow scope - -### File Organization -- One plugin = one file in `lua/plugins/` -- Keep plugin config self-contained in its spec -- Settings/keymaps/autocmds: only non-plugin logic in respective files -- No global state; return tables from modules - -### Migration Process -1. Check `MIGRATION_PLAN.md` for current phase and priorities -2. **Before large changes**: Update plan via CLI `update_plan` tool (if available) -3. **After any change**: Immediately update `MIGRATION_PLAN.md` (check off items, add notes) -4. **After decisions**: Update `LOG.md` decisions log -5. **After adding/removing/editing any keymaps**: Immediately update `README.md` with the change (add new entries, remove deleted mappings, or update descriptions) -6. Execute phases via subphases (N.x); one bullet = one implement-and-test step -7. Archive legacy files to `legacy/` instead of deleting - -## Do NOT Reintroduce (from AGENTS.md) -- Custom Vimscript tabline/statusline/foldtext -- Legacy autocommands (cursorline/column per window) -- CoC or CoC-specific config -- netrw settings (Neo-tree replaces it) -- Providers for ruby/perl/node (disabled unless required) -- Auto-reload vimrc-on-write templates -- `cursorcolumn` and old folding logic (UFO will handle folding) -- neoconf plugin (incompatible with Neovim 0.11+) - -## Developer Workflows - -### Testing Changes -```bash -# Quick syntax check -nvim --headless -c 'lua print("Config loads")' -c 'quitall' - -# Check LSP status in test workspace -cd ~/.config/nvim/WORKSPACE_TEST -nvim site/external.php # Then :LspInfo - -# Validate goto-definition for external libs -# In external.php, cursor on Util::greetExternal, press gd -``` - -### Validation Workspaces -- `WORKSPACE_TEST/`: PHP project with `.nvim.lua` and `.git` -- `EXTERNAL_TEST/`: External library referenced via includePaths -- Test that `gd` resolves symbols in EXTERNAL_TEST from WORKSPACE_TEST - -### Current Migration Status (as of 2025-12-07) -- ✅ Phase 1-2: Archive legacy, bootstrap lazy.nvim -- ✅ Phase 3: Core editing & LSP complete - - Settings, completion, LSP servers, Mason installed - - Native exrc + vim.lsp.config migration done - - Project-local `.nvim.lua` working -- ⏸️ Phase 4+: Navigation (Neo-tree, Telescope), Treesitter, UX plugins pending - -## Integration Points - -### External Dependencies -- **Neovim 0.11+**: Required for `vim.lsp.config` API -- **LSP Servers** (via Mason): lua_ls, ts_ls, html, cssls, jsonls, bashls, marksman, intelephense -- **PHP**: intelephense with `single_file_support = false`, uses `environment.includePaths` for external libs - -### Cross-Component Communication -- LSP settings flow: `.nvim.lua` → `on_new_config` → `new_config.settings` → `workspace/didChangeConfiguration` -- Completion: cmp-nvim-lsp provides capabilities → lspconfig → LSP servers - -## Common Issues - -### lua_ls Won't Start -Mason-installed lua_ls may fail with missing `libbfd-2.38-system.so`. Install via system package manager instead. - -### LSP Root Detection -If parent repo picked as root, create empty `.git` or `.nvimroot` marker in intended workspace root. - -### Duplicate gd Results (Fixed) -Was caused by settings loading at wrong time; fixed by using `on_new_config` with actual `root_dir`. - -## When Stuck -1. Check `MIGRATION_PLAN.md` for known issues and current phase -2. Review `AGENTS.md` for rules about what to avoid -3. Read `LOG.md` decisions log for context on past choices -4. Validate with test workspaces before modifying production config diff --git a/AGENTS.md b/AGENTS.md index 7b8fa1d..08ba23f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -158,6 +158,43 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu - **Features**: Incremental selection (CR/BS), textobjects (functions, classes, parameters), autotag - **Custom queries**: `after/queries/css/highlights.scm`, `after/queries/html/highlights.scm` +### Session Management +- **Auto-load**: On `VimEnter`, loads `Session.vim` if it exists (unless files specified on command line) +- **Auto-save**: On `VimLeavePre`, saves to `Session.vim` if it already exists +- **Manual control**: Create with `:mksession` to enable; delete to disable +- **Per-directory**: Sessions are opt-in and workspace-specific + +## Developer Workflows + +### Testing Changes +```bash +# Quick syntax check +nvim --headless -c 'lua print("Config loads")' -c 'quitall' + +# Check LSP status in test workspace +cd ~/.config/nvim/WORKSPACE_TEST +nvim site/external.php # Then :LspInfo + +# Validate goto-definition for external libs +# In external.php, cursor on Util::greetExternal, press gd +``` + +### Validation Workspaces +- `WORKSPACE_TEST/`: PHP project with `.nvim.lua` and `.git` +- `EXTERNAL_TEST/`: External library referenced via includePaths +- Test that `gd` resolves symbols in EXTERNAL_TEST from WORKSPACE_TEST + +## Common Issues + +### lua_ls Won't Start +Mason-installed lua_ls may fail with missing `libbfd-2.38-system.so`. Install via system package manager instead. + +### LSP Root Detection +If parent repo picked as root, create empty `.git` or `.nvimroot` marker in intended workspace root. + +### Duplicate gd Results (Fixed) +Was caused by settings loading at wrong time; fixed by using `LspAttach` autocmd with actual `root_dir`. + ## 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. diff --git a/REGRESSION_FIX_2025-12-07.md b/REGRESSION_FIX_2025-12-07.md index cb5e90c..7bf7e46 100644 --- a/REGRESSION_FIX_2025-12-07.md +++ b/REGRESSION_FIX_2025-12-07.md @@ -110,7 +110,7 @@ vim.api.nvim_create_autocmd('LspAttach', { ## Documentation Updated - `LOG.md`: Added decision log entry for 2025-12-07 -- `.github/copilot-instructions.md`: Documents LspAttach pattern +- `.github/copilot-instructions.md`: Now a simple pointer to AGENTS.md - `AGENTS.md`: Already notes "Native exrc + vim.lsp.config migration done" ## Prevention