diff --git a/tools/file_edit b/tools/file_edit index f0e70fe..fc8e9e5 100644 --- a/tools/file_edit +++ b/tools/file_edit @@ -1,6 +1,18 @@ #!/usr/bin/env python3 -# description: Replace text in a file; old_string not found is the guard -# Args: [replace_all=true|1|yes] +# ollie:prompt +# ## file_edit +# +# Replace text in a file. Has fuzzy matching (whitespace/indent flexible). +# +# **Args**: `[path, old_string, new_string]` or `[path, old_string, new_string, "replace_all=true"]` +# +# ``` +# call_tool: calls=[{tool: "file_edit", args: ["/abs/path", "old text", "new text"]}] +# call_tool: calls=[{tool: "file_edit", args: ["/abs/path", "old text", "new text", "replace_all=true"]}] +# ``` +# +# **Constraints**: Absolute paths only. Errors if `old_string` matches multiple locations — add surrounding context to disambiguate, or use `replace_all=true`. +# ollie:end import sys import os diff --git a/tools/file_glob b/tools/file_glob index 7597b7b..e6658da 100644 --- a/tools/file_glob +++ b/tools/file_glob @@ -1,7 +1,20 @@ #!/usr/bin/env bash # ollie:parallel read -# description: Find files by name/path pattern, sorted by modification time (newest first) -# Args: [path] +# ollie:prompt +# ## file_glob +# +# Find files by glob pattern, sorted by mtime (newest first). +# +# **Args**: `[pattern]` or `[pattern, search_dir]` +# +# - First arg: glob pattern (e.g. `"*.go"`, `"**/*.ts"`). +# - Second arg (optional): absolute search directory. Defaults to cwd. +# +# ``` +# call_tool: calls=[{tool: "file_glob", args: ["*.go", "/abs/search/dir"]}] +# call_tool: calls=[{tool: "file_glob", args: ["**/*.go"]}] +# ``` +# ollie:end pattern="$1" search_path="${2:-$PWD}" diff --git a/tools/file_grep b/tools/file_grep index 6e2b750..9823997 100644 --- a/tools/file_grep +++ b/tools/file_grep @@ -1,7 +1,26 @@ #!/usr/bin/env python3 # ollie:parallel read -# description: Search file contents using ripgrep (or grep fallback). Default output: file:lineno| content (one match per line). -# Args: [--path=] [--mode=files_with_matches|content|count] [--glob=] [--type=] [-i] [-A ] [-B ] [-C ] [--multiline] [--head=] [--offset=] +# ollie:prompt +# ## file_grep +# +# Search file contents with ripgrep. Capped at 50 matches by default. +# +# **Args**: `[pattern, ...flags]` +# +# - First arg (required): regex search pattern (positional). +# - Remaining args: flags only. The search path is a **flag**, not a positional arg. +# +# ``` +# call_tool: calls=[{tool: "file_grep", args: ["pattern", "--path=/abs/dir"]}] +# call_tool: calls=[{tool: "file_grep", args: ["TODO", "--path=src/", "--glob=*.go", "-i"]}] +# call_tool: calls=[{tool: "file_grep", args: ["func main", "--path=/home/user/project"]}] +# ``` +# +# - BAD: `args: ["pattern", "/path/to/dir"]` — path must use `--path=` flag +# - GOOD: `args: ["pattern", "--path=/path/to/dir"]` +# +# **Flags**: `--path=`, `--mode=files_with_matches|content|count`, `--glob=`, `--type=`, `-i`, `-A `, `-B `, `-C `, `--multiline`, `--head=`, `--offset=`. +# ollie:end import sys import os diff --git a/tools/file_write b/tools/file_write index 76c54e2..55e5bd0 100644 --- a/tools/file_write +++ b/tools/file_write @@ -1,6 +1,17 @@ #!/usr/bin/env python3 -# description: Write or overwrite a file -# Args: +# ollie:prompt +# ## file_write +# +# Create or overwrite a file. Produces a unified diff. +# +# **Args**: `[path, content]` +# +# ``` +# call_tool: calls=[{tool: "file_write", args: ["/abs/path", "file content here"]}] +# ``` +# +# **Constraints**: Absolute paths only. Parent directory must exist. +# ollie:end import sys import os diff --git a/tools/lsp_completion b/tools/lsp_completion index b164461..d233eba 100755 --- a/tools/lsp_completion +++ b/tools/lsp_completion @@ -1,7 +1,18 @@ #!/usr/bin/env python3 # ollie:parallel read -# description: Get completions at cursor position from the language server. -# Args: +# ollie:prompt +# ## lsp_completion +# +# Completion candidates at cursor position. +# +# **Args**: `[path, line, col]` +# +# ``` +# call_tool: calls=[{tool: "lsp_completion", args: ["/abs/path.go", "42", "10"]}] +# ``` +# +# **Returns**: up to 20 candidates. +# ollie:end import os import sys diff --git a/tools/lsp_definition b/tools/lsp_definition index 4879b11..dd20b5b 100755 --- a/tools/lsp_definition +++ b/tools/lsp_definition @@ -1,7 +1,18 @@ #!/usr/bin/env python3 # ollie:parallel read -# description: Go to definition of symbol at position. Returns file:line:col. -# Args: +# ollie:prompt +# ## lsp_definition +# +# Go to definition of symbol at position. +# +# **Args**: `[path, line, col]` +# +# ``` +# call_tool: calls=[{tool: "lsp_definition", args: ["/abs/path.go", "42", "10"]}] +# ``` +# +# **Returns**: `file:line:col` location(s). +# ollie:end import os import sys diff --git a/tools/lsp_diagnostics b/tools/lsp_diagnostics index c593c5d..5051831 100755 --- a/tools/lsp_diagnostics +++ b/tools/lsp_diagnostics @@ -1,7 +1,16 @@ #!/usr/bin/env python3 # ollie:parallel read -# description: Get diagnostics (errors, warnings) for a file. -# Args: +# ollie:prompt +# ## lsp_diagnostics +# +# Errors and warnings for a file. +# +# **Args**: `[path]` +# +# ``` +# call_tool: calls=[{tool: "lsp_diagnostics", args: ["/abs/path.go"]}] +# ``` +# ollie:end import os import sys diff --git a/tools/lsp_hover b/tools/lsp_hover index 1c21c8b..12f5481 100755 --- a/tools/lsp_hover +++ b/tools/lsp_hover @@ -1,7 +1,16 @@ #!/usr/bin/env python3 # ollie:parallel read -# description: Get type/documentation info for symbol at position. -# Args: +# ollie:prompt +# ## lsp_hover +# +# Type signature and documentation for symbol at position. +# +# **Args**: `[path, line, col]` +# +# ``` +# call_tool: calls=[{tool: "lsp_hover", args: ["/abs/path.go", "42", "10"]}] +# ``` +# ollie:end import os import sys diff --git a/tools/lsp_references b/tools/lsp_references index 970a394..dfe5c56 100755 --- a/tools/lsp_references +++ b/tools/lsp_references @@ -1,7 +1,20 @@ #!/usr/bin/env python3 # ollie:parallel read -# description: Find all references to symbol at position. Returns file:line:col per reference. -# Args: +# ollie:prompt +# ## lsp_references +# +# Find all references to symbol at position. Capped at 50. +# +# **Args**: `[path, line, col]` +# +# ``` +# call_tool: calls=[{tool: "lsp_references", args: ["/abs/path.go", "42", "10"]}] +# ``` +# +# **Returns**: `file:line:col` per reference. +# +# **Prefer over `file_grep`** for semantic references — won't match comments, strings, or unrelated identifiers. +# ollie:end import os import sys diff --git a/tools/lsp_rename b/tools/lsp_rename index 20f5dda..a2a70cc 100755 --- a/tools/lsp_rename +++ b/tools/lsp_rename @@ -1,6 +1,17 @@ #!/usr/bin/env python3 -# description: Rename symbol at position across the workspace. Applies edits directly to files. -# Args: +# ollie:prompt +# ## lsp_rename +# +# Rename symbol across workspace. Applies edits directly. +# +# **Args**: `[path, line, col, new_name]` +# +# ``` +# call_tool: calls=[{tool: "lsp_rename", args: ["/abs/path.go", "42", "10", "NewName"]}] +# ``` +# +# **Prefer over manual find-and-replace** — understands scope, interfaces, cross-package references. +# ollie:end import os import sys diff --git a/tools/lsp_symbols b/tools/lsp_symbols index 8aa00b1..c26fc08 100755 --- a/tools/lsp_symbols +++ b/tools/lsp_symbols @@ -1,7 +1,17 @@ #!/usr/bin/env python3 # ollie:parallel read -# description: List symbols in a file or search workspace symbols. -# Args: [--workspace] +# ollie:prompt +# ## lsp_symbols +# +# List symbols in a file, or search workspace-wide. +# +# **Args**: `[path]` or `[query, "--workspace"]` +# +# ``` +# call_tool: calls=[{tool: "lsp_symbols", args: ["/abs/path.go"]}] +# call_tool: calls=[{tool: "lsp_symbols", args: ["MyFunc", "--workspace"]}] +# ``` +# ollie:end import os import sys diff --git a/tools/memory_recall b/tools/memory_recall index 535948a..f508314 100755 --- a/tools/memory_recall +++ b/tools/memory_recall @@ -1,8 +1,25 @@ #!/usr/bin/env bash # ollie:parallel read # ollie:tier cold -# description: Search memories by keyword, tag, or title -# Args: +# ollie:prompt +# ## memory_recall +# +# Search stored memories for relevant context. +# +# **Trigger condition**: ALWAYS recall before exploring code or starting work on a task. Memory is a first-class source of context — check it before reading files or running commands. +# +# **Calling convention**: +# ``` +# call_tool: calls=[{tool: "memory_recall", args: [""]}] +# ``` +# - `query`: single keyword or short term. Prefer single keywords over phrases. +# +# **Returns**: matching memory files. +# +# **Constraints**: +# - Recall at the start of a topic, not mid-task. +# - If recall returns nothing relevant, proceed without it. +# ollie:end [ -z "$*" ] && echo "usage: memory_recall " && exit 1 diff --git a/tools/memory_remember b/tools/memory_remember index 6562c7c..c8e70bd 100755 --- a/tools/memory_remember +++ b/tools/memory_remember @@ -1,6 +1,28 @@ #!/usr/bin/env python3 -# description: Save a memory as a denote-formatted flat file -# Args: <tags_csv> <body> +# ollie:prompt +# ## memory_remember +# +# Persist a fact that would otherwise be lost when the session ends. +# +# **Trigger condition**: the user states a preference, constraint, or decision affecting future work; you discover a non-obvious fact about the codebase, system, or environment; a debugging session surfaces a root cause worth keeping; the user explicitly asks you to remember something. Autonomously remember architectural patterns, service relationships, API behaviors, configuration quirks, and other structural knowledge as you encounter it. +# +# **Calling convention**: +# ``` +# call_tool: calls=[{tool: "memory_remember", args: ["<title>", "<tags_csv>", "<body>"]}] +# ``` +# - `title`: short noun phrase +# - `tags_csv`: comma-separated tags; pick specific and reusable terms +# - `body`: the fact, written so it stands alone without session context +# +# **Returns**: confirmation. +# +# **Constraints**: +# - One memory per distinct fact. +# - Before writing, recall on the same topic to avoid duplicates. +# - Do not store stale facts. If a previously stored fact is wrong, update it with `file_edit`. +# - Never delete a memory without explicit user instruction. +# - **Act autonomously.** Do not ask the user whether to remember something. +# ollie:end import sys import os diff --git a/tools/reasoning_think b/tools/reasoning_think index 4dd7e59..62d5500 100755 --- a/tools/reasoning_think +++ b/tools/reasoning_think @@ -1,7 +1,24 @@ #!/usr/bin/env bash # ollie:parallel read -# description: Internal reasoning scratchpad; think through complex problems before acting -# Args: <thought> +# ollie:prompt +# ## reasoning_think +# +# Scratchpad for externalizing reasoning. Recorded in history but not shown to the user. +# +# **Trigger condition**: before acting on non-trivial tasks — complex problems, multi-step logic, decisions with trade-offs. Skip for simple single-step tasks. +# +# **Calling convention**: +# ``` +# call_tool: calls=[{tool: "reasoning_think", args: ["your reasoning here"]}] +# ``` +# +# **Returns**: nothing. The value is in writing the thought. +# +# **Constraints**: +# - One call per decision point. +# - Never call reasoning_think more than once before taking an action (tool call or response). Think, then act. +# - Keep under 200 words. State the decision and key tradeoffs, not stream-of-consciousness. +# ollie:end [ -z "$*" ] && echo "usage: reasoning_think <thought>" && exit 1 exit 0