From 003b3cb2bf4da868e0bfbc9c717fdf48e741ac65 Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Thu, 8 Oct 2026 23:29:44 +0100 Subject: [PATCH] docs: strictly enforce agnostic Neovim rules and ban invisible shell edits --- agent-rules/nvim_editing.md | 49 +++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/agent-rules/nvim_editing.md b/agent-rules/nvim_editing.md index a00f1ad..ebaaa1a 100644 --- a/agent-rules/nvim_editing.md +++ b/agent-rules/nvim_editing.md @@ -3,32 +3,33 @@ name: nvim_editing description: Route code edits to Neovim buffers instead of disk/console when Neovim is running. trigger: always_on --- -# Neovim Code Editing +# Neovim Code Editing (Agnostic & Universal) -## Never Spawn Headless Instances (CRITICAL) -**NEVER** run `nvim ` via bash/terminal commands (`run_command`) to "open" or "show" a file to the user. Because agent terminal commands run in the background, this spawns an invisible ghost process. +These rules apply universally to ALL Neovim environments (Windows, WSL, or any remote server). Do not treat them as OS-specific. -If the user asks to "open", "show", or "see" a file in Neovim, you MUST use the `win-nvim` (Neovim) MCP Server to communicate with their *active* UI (e.g., using `nvim_execute_lua` with `vim.cmd('edit ')`). +## 1. No Invisible Shell Edits (CRITICAL) +**NEVER** use `sed`, `awk`, `python -c`, or `echo` to modify file contents from the terminal. +File edits must use EXACTLY one of two paths: +- **Active UI (Neovim MCP responsive):** Route edits through specialized MCP tools to provide live visual feedback. +- **No UI (Neovim MCP unresponsive):** Fall back to the built-in `replace_file_content` tool to generate clean chat diffs. -When making code edits or displaying search results/outputs: -1. Verify if the `win-nvim` (Neovim) MCP server is responsive. -2. If Neovim is running, apply code changes directly into the relevant Neovim buffers using nvim_execute_lua (e.g., using vim.api.nvim_buf_set_lines or vim.cmd). -3. DO NOT output large diffs or file contents to the chat console. Prefer live buffer manipulation over replace_file_content if the file is open in Neovim. -4. **Fallback Constraint (CRITICAL):** If Neovim is NOT running, you MUST use the `replace_file_content` tool to edit files. This ensures the user is presented with a visual diff block in the chat. **NEVER** use `sed`, `awk`, or `echo` to blindly modify file contents from the terminal. +## 2. Strict Tool Adherence (No Raw Lua RCE) +You must strictly use the specialized, sandboxed Neovim MCP tools: +- `nvim_buffer`: For reading, writing, saving, and creating scratch buffers. +- `nvim_window`: For creating splits and focusing panes. +- `nvim_visual`: For highlighting diffs, adding ghost text, and showing previews. +**DO NOT** use `nvim_execute_lua` to mutate editor state. It is restricted to **READ-ONLY** queries. -## Visual Cues & Auto-Save Policy (MANDATORY) -When manipulating buffers via Lua, you MUST provide visual feedback: -1. **Notifications:** Always trigger a notification explaining what you did using `require("notify")("Antigravity edited [File]: [Summary]", "info", { title = "Antigravity" })` (since `rcarriga/nvim-notify` and `noice.nvim` are installed). -2. **Buffer Focus:** Always switch the active Neovim window to the buffer you just edited (e.g., `vim.cmd('b ' .. bufnr)`). -3. **Cursor Jump:** Move the cursor to the line you edited (`vim.api.nvim_win_set_cursor(0, {line, 0})`). -4. **Auto-Save by Default:** You MUST save the buffer (`vim.cmd('write')`) after making edits so that external tools (tests, compilers, linters, git) can see the changes immediately and unattended tasks are not stalled. -5. **Interactive Review Mode (Exception):** The ONLY time you should disable auto-save (leaving the buffer modified and unsaved) is when you are actively halting execution to seek manual user confirmation for a highly sensitive change. This allows the user to visually review the `gitsigns` diff in the gutter before manually saving (`:w`). +## 3. Headless Quarantine +Headless mode (`nvim --headless`) is strictly banned for interactive edits. +**NEVER** run `nvim ` via terminal commands to edit or "open" a file for the user (it spawns a zombie ghost process). +Headless instances are allowed ONLY for non-interactive background batch processing (e.g., project-wide formatting or linting). -## Interactive Review & Automatic Wakeup (MANDATORY) -When you modify a buffer and disable auto-save to allow the user to visually review the changes, you MUST NOT just wait idly for them to chat back. -You MUST spawn a background task to listen for their :w save event: -1. Use the un_command tool to execute: - curl -s "http://127.0.0.1:3000/events/wait?topic=nvim:save:$((Get-Item $File).FullName.Replace('\', '/'))&session_id=$SessionId" -2. Set WaitMsBeforeAsync to a low value (e.g., 500ms) so it goes to the background immediately. -3. Stop calling tools and end your turn. -When the user saves the file, the curl command will complete and the system will automatically wake you up to proceed. +## 4. UI Presentation & Chat Console Minimization +Never output large plans, context blocks, or architectural discussions to the chat console if Neovim is running. You MUST use the `nvim_buffer` and `nvim_window` tools to open a vertical split (e.g., `Antigravity_Plan.md` scratch buffer) and present the markdown natively. Reserve the chat console strictly for brief confirmations. + +## 5. Visual Cues & Auto-Save +When manipulating buffers via MCP: +1. **Focus & Jump:** Always switch the active Neovim window to the edited buffer and jump the cursor to the changed line. +2. **Auto-Save:** Auto-save the buffer by default so linters/compilers see it immediately. +3. **Interactive Review:** If pausing for human review (leaving unsaved), you MUST spawn a background `curl` task listening to `http://127.0.0.1:3000/events/wait?topic=nvim:save...` to wake you up when the user saves (`:w`).