From 2589dee4d51d2bc22e3bfdff92c52e2f8b943f31 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Mon, 11 May 2026 14:04:53 +0200 Subject: [PATCH] prompts: document steps vs pipe semantics, add lsp_completion --- prompts/SYSTEM_PROMPT.md | 2 ++ prompts/tools-elevate.md | 2 +- prompts/tools-file.md | 5 +++++ prompts/tools-lsp.md | 7 +++++++ 4 files changed, 15 insertions(+), 1 deletion(-) diff --git a/prompts/SYSTEM_PROMPT.md b/prompts/SYSTEM_PROMPT.md index f78ea25..0b9b3ea 100644 --- a/prompts/SYSTEM_PROMPT.md +++ b/prompts/SYSTEM_PROMPT.md @@ -25,6 +25,8 @@ Be truthful. If the user is wrong, say so — do not soften, hedge, or dance aro # Tool preferences - Make independent tool calls in parallel when there are no dependencies between them. +- `steps` are independent and run in parallel when safe. Use multiple steps in one call for independent reads. +- `pipe` is an explicit sequential pipeline (stdout → stdin chaining). Use it to compose tool+code stages. - Prefer dedicated tools over inline shell for file operations — see the file tools prompt. # Reminder diff --git a/prompts/tools-elevate.md b/prompts/tools-elevate.md index f7a436e..f573716 100644 --- a/prompts/tools-elevate.md +++ b/prompts/tools-elevate.md @@ -12,7 +12,7 @@ execute_code: steps=[{code: "systemctl restart nginx", elevated: true}] **Constraints**: - Before running an elevated step, briefly explain in your response what the command does and why it requires elevation. The user must approve the request — give them enough context to make that decision. -- `elevated: true` is a per-step flag — apply it only to steps that actually need it; other steps in the same pipeline run normally inside the sandbox. +- `elevated: true` is a per-step flag — apply it only to steps that actually need it; other steps in the same call run normally inside the sandbox. - Only bash is supported for elevated steps. - Elevation may not be available on all systems; if absent, the step fails with "elevation not available". Do not assume it is always present. - Elevated steps block until the user approves or denies the request — this is expected, not an error. diff --git a/prompts/tools-file.md b/prompts/tools-file.md index bc77648..c823141 100644 --- a/prompts/tools-file.md +++ b/prompts/tools-file.md @@ -24,6 +24,11 @@ execute_code: steps=[{tool: "file_grep", args: ["func.*Handler", "src/"]}] **Returns**: file contents with line numbers / match results / write confirmation. +**Batch independent reads** in a single call for parallel execution: +``` +execute_code: steps=[{tool: "file_read", args: ["a.go", "1", "50"]}, {tool: "file_read", args: ["b.go", "1", "50"]}] +``` + **Prefer segments over full-file reads.** Use `file_grep` or `file_glob` to locate the relevant section, then read only the lines you need with `start`/`end`. Full-file reads are for small files or when you need the whole content. **Line numbers**: `file_read` output is prefixed with accurate file line numbers (`{lineno}\t{content}`). Use these when specifying `start`/`end` for subsequent reads or writes. diff --git a/prompts/tools-lsp.md b/prompts/tools-lsp.md index cac9f3a..4667276 100644 --- a/prompts/tools-lsp.md +++ b/prompts/tools-lsp.md @@ -10,6 +10,7 @@ Code intelligence via language servers (gopls, clangd, intelephense). The bridge | `lsp_rename` | ` ` | Applies rename across workspace, prints summary | | `lsp_symbols` | ` [--workspace]` | Symbols in file or workspace-wide search | | `lsp_diagnostics` | `` | Errors and warnings with positions | +| `lsp_completion` | ` ` | Completion candidates at cursor position | **Trigger condition**: when you need semantic code understanding — finding callers before refactoring, checking a type signature, renaming across a codebase, or verifying a file compiles cleanly. @@ -21,6 +22,7 @@ execute_code: steps=[{tool: "lsp_hover", args: ["/abs/path/to/file.go", "4 execute_code: steps=[{tool: "lsp_rename", args: ["/abs/path/to/file.go", "42", "10", "NewName"]}] execute_code: steps=[{tool: "lsp_symbols", args: ["/abs/path/to/file.go"]}] execute_code: steps=[{tool: "lsp_diagnostics", args: ["/abs/path/to/file.go"]}] +execute_code: steps=[{tool: "lsp_completion", args: ["/abs/path/to/file.go", "42", "10"]}] ``` **Line/col are 1-indexed** — matching `file_read` output. Use the line numbers from `file_read` directly. @@ -30,3 +32,8 @@ execute_code: steps=[{tool: "lsp_diagnostics", args: ["/abs/path/to/file.go"]}] **Prefer `lsp_rename` over manual find-and-replace** for symbol renames — it understands scope, interfaces, and cross-package references. **Prefer `lsp_references` over `file_grep`** when you need semantic references (not just text matches) — it won't return comments, strings, or unrelated identifiers that happen to share a name. + +**Parallel reads**: all read-only LSP tools can be batched in a single call: +``` +execute_code: steps=[{tool: "lsp_hover", args: [...]}, {tool: "lsp_symbols", args: [...]}, {tool: "lsp_completion", args: [...]}] +```