From 3a4612467687648397c017f80375f3d3e0adc513 Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Wed, 30 Sep 2026 12:33:01 +0100 Subject: [PATCH] docs: Update guidelines and effective discourse for MCP tools --- EFFECTIVE_DISCOURSE.md | 20 +++++++++++++++++++- README.md | 2 +- instructions.md | 11 +++++++++-- 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/EFFECTIVE_DISCOURSE.md b/EFFECTIVE_DISCOURSE.md index af70ae9..b3b54af 100644 --- a/EFFECTIVE_DISCOURSE.md +++ b/EFFECTIVE_DISCOURSE.md @@ -43,7 +43,25 @@ Keep your workflow entirely within your editor rather than copy-pasting code blo * **Do say:** "Push this refactor to my active Neovim buffer as ghost text so I can review it in-line." * **Tool Triggered:** `nvim_set_preview` (via `win-nvim` or `linux-nvim`) -## 8. Graph, Memory & Decay Management +## 8. Structural AST Editing +When asking the LLM to modify complex files, prevent indentation bugs and regex failures by guiding it to use tree-sitter. +* **Don't say:** "Search for `fn process()` and replace it with this string." +* **Do say:** "Use the AST node replacer to swap out the `process` function in `server.rs`." +* **Tool Triggered:** `replace_ast_node` + +## 9. Interactive Terminal Execution +When asking the LLM to run commands that have prompts, long output, or ANSI colors. +* **Don't say:** "Run `cargo run` and tell me what the output is." (Hides output, hangs on prompts). +* **Do say:** "Send the `cargo run` command to my Neovim terminal split so I can interact with it." +* **Tool Triggered:** `nvim_send_to_terminal` + +## 10. Bird's-Eye Repository Exploration +When the LLM is first analyzing a repository, don't let it run `ls -R` and guess. +* **Don't say:** "List the files in the directory and guess where the database code is." +* **Do say:** "Read the directory architecture to get a summary of what each file is responsible for." +* **Tool Triggered:** `read_directory_architecture` + +## 11. Graph, Memory & Decay Management Actively instruct the LLM to maintain its own memory constraints and organize data. The daemon automatically consolidates old sticky notes and snippets to prevent unbounded context growth. * **Do say:** "Log this architectural decision in the knowledge graph." * **Do say:** "Add a sticky note with the test database credentials for this session." diff --git a/README.md b/README.md index a8389b4..3467467 100644 --- a/README.md +++ b/README.md @@ -161,7 +161,7 @@ ead_file_skeleton)**: Uses ree-sitter to parse large code files (Rust, Python, - **Clipboard Watch Mode ( oggle_clipboard_watch_mode)**: Background daemon thread that auto-ingests your Ctrl+C clipboard activity directly into Knowledge Graph StickyNotes while you debug. - **Ghost Text Previews ( vim_set_preview)**: Pushes proposed LLM code diffs directly into Neovim buffers as ephemeral virtual text. -- [Prompting Guide & Effective Discourse](./PROMPTING_GUIDE.md): Learn how to phrase prompts to get the most out of the agent and memory server. +- [Prompting Guide & Effective Discourse](./EFFECTIVE_DISCOURSE.md): Learn how to phrase prompts to get the most out of the agent and memory server. ## T2R & Token Efficiency Enhancements (V2) - **AST Node Replacer ( diff --git a/instructions.md b/instructions.md index c219d94..5c52cf7 100644 --- a/instructions.md +++ b/instructions.md @@ -115,8 +115,15 @@ To maintain absolute traceability, we link memory items directly to the exact gi The project contains two MCP binaries (win-nvim and linux-nvim) that bridge JSON-RPC over stdio directly to the active Neovim instance. - **Interactive UI (UDP):** The active editor connects to the backend via UDP (port 3002). The UI script (`gemini-ui.lua`) supports non-destructive **Ghost Text Diff Reviews** and native `vim.ui` prompts without spawning subprocesses. You can trigger these interactively using the backend server. - **Tools:** These binaries expose basic tools (`nvim_get_cursor`, `nvim_get_active_buffer`, `nvim_list_buffers`, etc.). +- **Interactive Execution QoL:** Use `nvim_send_to_terminal` to run background terminal commands (like tests or builds) in a visible Neovim split so the user can interact with prompts and see ANSI colors. - **God Mode**: They also expose `nvim_execute_lua`. This is the ultimate fallback tool. If you need to access *any* Neovim API that does not have a dedicated Rust tool (e.g., getting LSP diagnostics, evaluating a visual selection block based on modes, setting registers), you MUST write a short Lua script and pass it to `nvim_execute_lua`. Do not attempt to recompile the Rust server to add new basic tools; use the Lua escape hatch dynamically. -## 16. Tool Schema Discovery (Lazy Loading) -Antigravity automatically caches all MCP tool schemas to your disk to save tokens. Do **NOT** grep or search the Rust source code to find tool schemas or arguments. To understand a tool`s arguments, directly read `~/.gemini/antigravity-cli/mcp//.json`. Do NOT guess arguments. ALWAYS read the schema if you are unfamiliar with a tool to prevent invalid argument errors. +## 16. Structural Code & Architecture Exploration +To reduce token costs and eliminate exact-match string failures: +- **`read_directory_architecture`**: When exploring a new repository, use this to get a bird's-eye view of a directory structure with summaries of file responsibilities, instead of blindly reading files. +- **`replace_ast_node`**: Instead of string-matching `replace_file_content` (which fails on whitespace), use this to precisely replace functions or structs based on AST boundaries. +- **`semantic_code_search`**: Use conceptual vector search instead of raw regex (`grep`) when you need to locate abstract logic (e.g., "Where is authentication handled?"). + +## 17. Tool Schema Discovery (Lazy Loading) +Antigravity automatically caches all MCP tool schemas to your disk to save tokens. Do **NOT** grep or search the Rust source code to find tool schemas or arguments. To understand a tool's arguments, directly read `~/.gemini/antigravity-cli/mcp//.json`. Do NOT guess arguments. ALWAYS read the schema if you are unfamiliar with a tool to prevent invalid argument errors.