@oh-my-pi/pi-coding-agent 7.0.0 → 8.0.0

package/src/prompts/tools/find.md

@@ -1,6 +1,16 @@
-- Fast file pattern matching tool that works with any codebase size
+# Find
+
+Fast file pattern matching that works with any codebase size.
+
+<instruction>
 - Supports glob patterns like "**/*.js" or "src/**/*.ts"
-- Returns matching file paths sorted by modification time
-- Use this tool when you need to find files by name patterns
-- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead
-- You can call multiple tools in a single response. It is always better to speculatively perform multiple searches in parallel if they are potentially useful.
+- Speculatively perform multiple searches in parallel when potentially useful
+</instruction>
+
+<output>
+Matching file paths sorted by modification time (most recent first). Results truncated at 1000 entries or 50KB.
+</output>
+
+<avoid>
+Open-ended searches requiring multiple rounds of globbing and grepping — use Task tool instead.
+</avoid>

package/src/prompts/tools/gemini-image.md

@@ -1,8 +1,23 @@
-Generate or edit images using Gemini image models directly or via OpenRouter.
+# Gemini Image
 
-Provide a text prompt and optional input images. Use response modalities to request image-only output,
-set aspect ratio or image size, and choose the model explicitly when needed.
+Generate or edit images using Gemini image models.
 
-Prompt tips:
-- Describe subject, composition, style, and lighting in full sentences.
-- For edits, reference the input image and specify the exact changes.
+<instruction>
+Provide structured parameters for best results. The tool assembles them into an optimized prompt.
+
+When using multiple `input_images`, describe each image's role in the `subject` or `scene` field:
+- "Use Image 1 for the character's face and outfit, Image 2 for the pose, Image 3 for the background environment"
+- "Match the color palette from Image 1, apply the lighting style from Image 2"
+</instruction>
+
+<output>
+Returns the generated image saved to disk. The response includes the file path where the image was written.
+</output>
+
+<important>
+- For photoreal: add "ultra-detailed, realistic, natural skin texture" to style
+- For posters/cards: use 9:16 aspect ratio with negative space for text placement
+- For iteration: use `changes` to make targeted adjustments rather than regenerating from scratch
+- For text: add "sharp, legible, correctly spelled" for important text; keep text short
+- For diagrams: include "scientifically accurate" in style and provide facts explicitly
+</important>

package/src/prompts/tools/grep.md

@@ -1,12 +1,28 @@
-A powerful search tool built on ripgrep
-
-Usage:
-  - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
-  - Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
-  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
-  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
-  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)
-  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`
-
-Important:
-  - ALWAYS Use Task tool with explore subagent over this for open-ended searches requiring multiple rounds
+# Grep
+
+A powerful search tool built on ripgrep.
+
+<instruction>
+- Supports full regex syntax (e.g., `log.*Error`, `function\\s+\\w+`)
+- Filter files with `glob` (e.g., `*.js`, `**/*.tsx`) or `type` (e.g., `js`, `py`, `rust`)
+- Pattern syntax uses ripgrep—literal braces need escaping (`interface\\{\\}` to find `interface{}` in Go)
+- For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`
+</instruction>
+
+<output>
+Results depend on `output_mode`:
+- `content`: Matching lines with file paths and line numbers
+- `files_with_matches`: File paths only (one per line)
+- `count`: Match counts per file
+
+In `content` mode, truncated at 100 matches by default (configurable via `limit`).
+For `files_with_matches` and `count` modes, use `head_limit` to truncate results.
+</output>
+
+<critical>
+- ALWAYS use Grep for search tasks—NEVER invoke `grep` or `rg` via Bash. This tool has correct permissions and access.
+</critical>
+
+<avoid>
+- Open-ended searches requiring multiple rounds—use Task tool with explore subagent instead
+</avoid>

package/src/prompts/tools/lsp.md

@@ -1,14 +1,35 @@
-Interact with Language Server Protocol (LSP) servers to get code intelligence features.
-
-Standard operations:
-- diagnostics: Get errors/warnings for a file
-- workspace_diagnostics: Check entire project for errors (uses tsc, cargo check, go build, etc.)
-- definition: Go to symbol definition
-- references: Find all references to a symbol
-- hover: Get type info and documentation
-- symbols: List symbols in a file (functions, classes, etc.)
-- workspace_symbols: Search for symbols across the project
-- rename: Rename a symbol across the codebase
-- actions: List and apply code actions (quick fixes, refactors)
-- incoming_calls: Find all callers of a function
-- outgoing_calls: Find all functions called by a function
+# LSP
+
+Interact with Language Server Protocol servers for code intelligence.
+
+<operations>
+- `diagnostics`: Get errors/warnings for a file
+- `workspace_diagnostics`: Check entire project (uses tsc, cargo check, go build, etc.)
+- `definition`: Go to symbol definition
+- `references`: Find all references to a symbol
+- `hover`: Get type info and documentation
+- `symbols`: List symbols in a file (functions, classes, etc.)
+- `workspace_symbols`: Search for symbols across the project
+- `rename`: Rename a symbol across the codebase
+- `actions`: List and apply code actions (quick fixes, refactors)
+- `incoming_calls`: Find all callers of a function
+- `outgoing_calls`: Find all functions called by a function
+</operations>
+
+<output>
+Returns vary by operation:
+- `diagnostics`/`workspace_diagnostics`: List of errors/warnings with file, line, severity, message
+- `definition`: File path and position of the definition
+- `references`: List of locations (file + position) where symbol is used
+- `hover`: Type signature and documentation text
+- `symbols`/`workspace_symbols`: List of symbol names, kinds, and locations
+- `rename`: Confirmation of changes made across files
+- `actions`: List of available code actions; when applied, returns the result
+- `incoming_calls`/`outgoing_calls`: Call hierarchy with caller/callee locations
+</output>
+
+<important>
+- Requires a running LSP server for the target language
+- Some operations require the file to be saved to disk
+- `workspace_diagnostics` may be slow on large projects
+</important>

package/src/prompts/tools/patch.md

@@ -1,15 +1,29 @@
-Performs patch operations on a file given a diff.
-This is your primary tool for making changes to existing files.
+# Edit
 
-<critical>
-- Always read the target file before editing.
-- Copy anchors + context lines verbatim (including whitespace).
-- Output the clean patch format below.
-</critical>
+Performs patch operations on a file given a diff. Primary tool for modifying existing files.
+
+<instruction>
+**Hunk Headers:**
+- `@@` — bare header when context lines are already unique
+- `@@ $ANCHOR` — anchor must be copied verbatim from the file (full line or unique substring)
+
+**Anchor Selection Algorithm:**
+1. If surrounding context lines are already unique, use bare `@@`
+2. Otherwise choose a highly specific anchor copied from the file:
+   - full function signature line
+   - class declaration line
+   - unique string literal / error message
+   - config key with uncommon name
+3. If "Found multiple matches" error: add more context lines, use multiple hunks with separate anchors, or use a longer anchor substring
+
+**Context Lines:**
+- Include enough ` `-prefixed lines to make match unique (usually 2–8 total)
+- Must exist in the file exactly as written (preserve indentation/trailing spaces)
+</instruction>
 
 <parameters>
 ```ts
-type T = 
+type T =
    // Diff is one or more hunks, within the same file.
    // - Each hunk begins with "@@" (optionally with an anchor).
    // - Each hunk body contains only lines starting with: ' ' | '+' | '-'.
@@ -24,40 +38,18 @@ type T =
 ```
 </parameters>
 
-<hunk_header>
-Allowed:
-- `@@`
-- `@@ $ANCHOR`
+<output>
+Returns success/failure status. On failure, returns error message indicating:
+- "Found multiple matches" — anchor/context not unique enough
+- "No match found" — context lines don't exist in file (wrong content or stale read)
+- Syntax errors in diff format
+</output>
 
-ANCHOR RULES:
-- `$ANCHOR` MUST be copied verbatim from the file as either:
-  - a full existing line, OR
-  - a unique substring of a single existing line.
-- NEVER use it as a comment:
-  - line numbers / ranges: `line 207`, `lines 26-37`
-  - location labels: `top of file`, `start`, `near imports`
-  - placeholders: `@@ @@`, `...`
-</hunk_header>
-
-<anchor_selection>
-ANCHOR SELECTION ALGORITHM (use in this order):
-1) If the surrounding context lines are already unique in the file, use bare `@@`.
-2) Else choose an anchor that is highly specific and stable, copied from the file, e.g.:
-   - full function signature line
-   - class declaration line
-   - a unique string literal / error message
-   - a config key with uncommon name
-3) If you get "Found multiple matches", escalate by:
-   - adding more context lines, OR
-   - using multiple hunks with separate nearby anchors, OR
-   - using a more specific anchor substring (longer, includes identifiers).
-NEVER use generic anchors like `import`, `export`, `describe`, `function`, `const`.
-</anchor_selection>
-
-<context_rules>
-- Include enough context lines (' ' prefixed) to make the match unique (usually 2–8 total).
-- Context lines must exist in the file exactly as written; preserve indentation/trailing spaces.
-</context_rules>
+<critical>
+- Always read the target file before editing
+- Copy anchors and context lines verbatim (including whitespace)
+- Never use anchors as comments (no line numbers, location labels, or placeholders like `@@ @@`)
+</critical>
 
 <example name="create">
 edit {"path":"hello.txt","op":"create","diff":"Hello\n"}
@@ -74,3 +66,9 @@ edit {"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n ...\
 <example name="delete">
 edit {"path":"obsolete.txt","op":"delete"}
 </example>
+
+<avoid>
+- Generic anchors: `import`, `export`, `describe`, `function`, `const`
+- Anchor comments: `line 207`, `top of file`, `near imports`, `...`
+- Editing without reading the file first (causes stale context errors)
+</avoid>

package/src/prompts/tools/python.md

@@ -1,7 +1,8 @@
-Executes Python cells sequentially in a persistent IPython kernel.
+# Python
 
-## How to use (REPL discipline)
+Executes Python cells sequentially in a persistent IPython kernel.
 
+<instruction>
 The kernel persists between calls and between cells. **Imports, variables, and functions survive.** Use this.
 
 **Work incrementally:**
@@ -15,64 +16,9 @@ The kernel persists between calls and between cells. **Imports, variables, and f
 - Earlier cells already ran—their state persists in the kernel
 - Resubmit with only the fixed cell (or the fixed cell + remaining cells)
 - Do NOT rewrite working cells or re-import modules
+</instruction>
 
-**Anti-patterns to avoid:**
-- Putting everything in one giant cell
-- Re-importing modules you already imported
-- Rewriting working code when only one part failed
-- Large functions that are hard to debug piece by piece
-
-```python
-# BAD: One giant cell
-cells: [{
-    "title": "all-in-one",
-    "code": "import json\nfrom pathlib import Path\ndef process_all_files():\n    # 50 lines...\n    pass\nresult = process_all_files()"
-}]
-
-# GOOD: Multiple small cells
-cells: [
-    {"title": "imports", "code": "import json\nfrom pathlib import Path"},
-    {"title": "parse helper", "code": "def parse_config(path):\n    return json.loads(Path(path).read_text())"},
-    {"title": "test helper", "code": "parse_config('config.json')"},
-    {"title": "use helper", "code": "configs = [parse_config(p) for p in Path('.').glob('*.json')]"}
-]
-```
-
-## When to use Python
-
-**Use Python for user-facing operations:**
-- Displaying, concatenating, or merging files → `cat(*paths)`
-- Batch transformations across files → `batch(paths, fn)`, `rsed()`
-- Formatted output, tables, summaries
-- Any loop, conditional, or multi-step logic
-- Anything you'd write a bash script for
-
-**Use specialized tools for YOUR reconnaissance:**
-- Reading to understand code → Read tool
-- Searching to locate something → Grep tool
-- Finding files to identify targets → Find tool
-
-The distinction: Read/Grep/Find gather info for *your* decisions. Python executes *the user's* request.
-
-**Prefer Python over bash for:**
-- Loops and iteration → Python for-loops, not bash for/while
-- Text processing → `sed()`, `cols()`, `sort_lines()`, not sed/awk/cut
-- File operations → prelude helpers, not mv/cp/rm commands
-- Conditionals → Python if/else, not bash [[ ]]
-
-**Shell commands:** Use `sh()` or `run()`, never raw `subprocess`:
-```python
-# Good
-sh("bun run check")
-run("cargo build --release")
-
-# Bad - never use subprocess directly
-import subprocess
-subprocess.run(["bun", "run", "check"], ...)
-```
-
-## Prelude helpers
-
+<prelude>
 All helpers auto-print results and return values for chaining.
 
 {{#if categories.length}}
@@ -84,14 +30,49 @@ All helpers auto-print results and return values for chaining.
     {{docstring}}
 {{/each}}
 ```
-
 {{/each}}
 {{else}}
 (Documentation unavailable — Python kernel failed to start)
 {{/if}}
+</prelude>
 
-## Examples
+<output>
+Output streams in real time, truncated after 100KB.
+If output is truncated, full output is stored under $ARTIFACTS and referenced as `artifact://<id>` in metadata.
 
+The user sees output like a Jupyter notebook—rich displays are fully rendered:
+- `display(JSON(data))` → interactive JSON tree
+- `display(HTML(...))` → rendered HTML
+- `display(Markdown(...))` → formatted markdown
+- `plt.show()` → inline figures
+
+**You will see object repr** (e.g., `<IPython.core.display.JSON object>`) **but the user sees the rendered output.** Trust that `display()` calls work correctly—do not assume the user sees only the repr.
+</output>
+
+<important>
+- Kernel persists for the session by default; per-call mode uses a fresh kernel each call
+- Use `reset: true` to clear state when session mode is active
+</important>
+
+<critical>
+- Use `plt.show()` to display figures
+- Use `display()` from IPython.display for rich output (HTML, Markdown, images, etc.)
+- Use `sh()` or `run()` for shell commands, never raw `subprocess`
+</critical>
+
+<example name="good">
+```python
+# Multiple small cells
+cells: [
+    {"title": "imports", "code": "import json\nfrom pathlib import Path"},
+    {"title": "parse helper", "code": "def parse_config(path):\n    return json.loads(Path(path).read_text())"},
+    {"title": "test helper", "code": "parse_config('config.json')"},
+    {"title": "use helper", "code": "configs = [parse_config(p) for p in Path('.').glob('*.json')]"}
+]
+```
+</example>
+
+<example name="prelude-helpers">
 ```python
 # Concatenate all markdown files in docs/
 cat(*find("*.md", "docs"))
@@ -108,21 +89,23 @@ sort_lines(read("data.txt"), unique=True)
 # Extract columns 0 and 2 from TSV
 cols(read("data.tsv"), 0, 2, sep="\t")
 ```
+</example>
 
-## Notes
-
-- Code executes as IPython cells; users see the full cell output (including rendered figures, tables, etc.)
-- Kernel persists for the session by default; per-call mode uses a fresh kernel each call. Use `reset: true` to clear state when session mode is active
-- Use `plt.show()` to display figures
-- Use `display()` from IPython.display for rich output (HTML, Markdown, images, etc.)
-- Output streams in real time, truncated after 50KB
-
-## Rich output rendering
+<example name="shell-commands">
+```python
+# Good
+sh("bun run check")
+run("cargo build --release")
 
-The user sees output like a Jupyter notebook—rich displays are fully rendered:
-- `display(JSON(data))` → interactive JSON tree
-- `display(HTML(...))` → rendered HTML
-- `display(Markdown(...))` → formatted markdown
-- `plt.show()` → inline figures
+# Bad - never use subprocess directly
+import subprocess
+subprocess.run(["bun", "run", "check"], ...)
+```
+</example>
 
-**You will see object repr** (e.g., `<IPython.core.display.JSON object>`) **but the user sees the rendered output.** Trust that `display()` calls work correctly—do not assume the user sees only the repr.
+<avoid>
+- Putting everything in one giant cell
+- Re-importing modules you already imported
+- Rewriting working cells when only one part failed
+- Large functions that are hard to debug piece by piece
+</avoid>

package/src/prompts/tools/read.md

@@ -1,25 +1,26 @@
-Reads a file from the local filesystem. You can access any file directly by using this tool.
-Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+# Read
 
-Usage:
-- By default, it reads up to {{DEFAULT_MAX_LINES}} lines starting from the beginning of the file
-- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
-- Any lines longer than 500 characters will be truncated
-- By default, results omit line numbers. Use `lines: true` to include them
-- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
-- This tool can read PDF files (.pdf). PDFs are processed page by page, extracting both text and visual content for analysis.
-- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
-- This tool can only read files, not directories. To read a directory, use the ls tool.
-- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
-- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
-- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
-
-Empty files trigger a warning. Directory paths return an ls-style listing. Missing files return an error with closest matches (gitignore respected).
-
-## Best Practices
+Reads files from the local filesystem or internal URLs.
 
+<instruction>
+- Reads up to {{DEFAULT_MAX_LINES}} lines by default
+- Use `offset` and `limit` for large files
+- Use `lines: true` to include line numbers
+- Supports images (PNG, JPG) and PDFs
+- For directories, use the ls tool instead
 - Parallelize reads when exploring related files
-- Read before editing (required in current session)
-- Trust user-provided paths; attempt the read
-- Screenshots: Read tool renders images visually
-- Skip re-reading after edits (Edit/Write report errors)
+- Supports internal URLs:
+  - `skill://<name>` - read SKILL.md for a skill
+  - `skill://<name>/<path>` - read relative path within skill directory
+  - `rule://<name>` - read rule content
+  - `agent://<id>` - read agent output artifact
+  - `agent://<id>/<path>` or `agent://<id>?q=<query>` - extract JSON from agent output
+</instruction>
+
+<output>
+- Returns file content as text
+- Images: returns visual content for analysis
+- PDFs: returns extracted text
+- Missing files: returns closest filename matches for correction
+- Internal URLs: returns resolved content with pagination support
+</output>

package/src/prompts/tools/replace.md

@@ -1,18 +1,24 @@
+# Replace
+
 Performs string replacements in files with fuzzy whitespace matching.
 
-Usage:
-- Use the smallest edit that uniquely identifies the change. To toggle a checkbox: `- [ ] Task` → `- [x] Task`, not the entire line.
-- If the old text is not unique, expand the replacement to a larger block (function/class/section) so it is unique.
-- You must use your read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
-- Fuzzy matching handles minor whitespace/indentation differences automatically - you don't need to match indentation exactly.
-- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
-- Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+<instruction>
+- Use the smallest edit that uniquely identifies the change
+- If `old_text` is not unique, expand to include more context or use `all: true` to replace all occurrences
+- Fuzzy matching handles minor whitespace/indentation differences automatically
+- Prefer editing existing files over creating new ones
+</instruction>
+
+<output>
+Returns success/failure status. On success, the file is modified in place with the replacement applied. On failure (e.g., `old_text` not found or matches multiple locations without `all: true`), returns an error describing the issue.
+</output>
 
-## When to use bash instead
+<critical>
+- You must read the file at least once in the conversation before editing. The tool will error if you attempt an edit without reading the file first.
+</critical>
 
-Edit is for content-addressed changes—you identify *what* to change by its text.
+<bash_alternatives>
+Replace is for content-addressed changes—you identify *what* to change by its text.
 
 For position-addressed or pattern-addressed changes, bash is more efficient:
 
@@ -27,5 +33,6 @@ For position-addressed or pattern-addressed changes, bash is more efficient:
 | Copy lines N-M to another file | `sed -n 'N,Mp' src >> dest` |
 | Move lines N-M to another file | `sed -n 'N,Mp' src >> dest && sed -i 'N,Md' src` |
 
-Use Edit when the *content itself* identifies the location.
+Use Replace when the *content itself* identifies the location.
 Use bash when *position* or *pattern* identifies what to change.
+</bash_alternatives>

package/src/prompts/tools/ssh.md

@@ -1,11 +1,14 @@
-Execute commands on remote SSH hosts.
-
-## Critical: Match Commands to Host Shell
+# SSH
 
-Each host runs a specific shell. **You MUST use commands native to that shell.**
+Execute commands on remote SSH hosts.
 
-### Command Reference
+<instruction>
+1. Check the host's shell type from "Available hosts" below
+2. Use ONLY commands for that shell type
+3. Construct your command using the reference below
+</instruction>
 
+<commands>
 **linux/bash, linux/zsh, macos/bash, macos/zsh** — Unix-like systems:
 - Files: `ls`, `cat`, `head`, `tail`, `grep`, `find`
 - System: `ps`, `top`, `df`, `uname`, `free` (Linux), `df`, `uname`, `top` (macOS)
@@ -26,49 +29,39 @@ Each host runs a specific shell. **You MUST use commands native to that shell.**
 - Files: `dir`, `type`, `findstr`, `where`
 - System: `tasklist`, `systeminfo`
 - Navigation: `cd`, `echo %CD%`
+</commands>
 
-## Execution Pattern
+<output>
+Command output (stdout/stderr combined), truncated at 50KB. Exit code is captured.
+If output is truncated, full output is stored under $ARTIFACTS and referenced as `artifact://<id>` in metadata.
+</output>
 
-1. Check the host's shell type from "Available hosts" below
-2. Use ONLY commands for that shell type
-3. Construct your command using the reference above
+<critical>
+Each host runs a specific shell. You MUST use commands native to that shell.
+Verify host shell type from "Available hosts" and use matching commands.
+</critical>
 
-## Examples
-
-<example>
+<example name="linux">
 Task: List files in /home/user on host "server1"
 Host: server1 (10.0.0.1) | linux/bash
 Command: `ls -la /home/user`
 </example>
 
-<example>
+<example name="windows-cmd">
 Task: Show running processes on host "winbox"
 Host: winbox (192.168.1.5) | windows/cmd
 Command: `tasklist /v`
 </example>
 
-<example>
+<example name="windows-wsl">
 Task: Check disk usage on host "wsl-dev"
 Host: wsl-dev (192.168.1.10) | windows/bash
 Command: `df -h`
 Note: Windows host with WSL — use Unix commands
 </example>
 
-<example>
+<example name="macos">
 Task: Get system info on host "macbook"
 Host: macbook (10.0.0.20) | macos/zsh
 Command: `uname -a && sw_vers`
 </example>
-
-## Parameters
-
-- **host**: Host name from "Available hosts" below
-- **command**: Command to execute (see Command Reference above)
-- **cwd**: Working directory (optional)
-- **timeout**: Timeout in seconds (optional)
-
-## Output
-
-Truncated at 50KB. Exit codes captured.
-
-**Before executing: verify host shell type below and use matching commands.**