@oh-my-pi/pi-coding-agent 12.19.3 → 13.0.1

package/src/prompts/tools/exit-plan-mode.md

@@ -1,25 +1,27 @@
-Signals plan completion, requests user approval to begin implementation.
+Signals plan completion, requests user approval, and provides the final plan title for handoff.
 
 <conditions>
 Use when:
-- Plan written to plan file
+- Plan written to `local://PLAN.md`
 - No unresolved questions about requirements or approach
 - Ready for user review and approval
 </conditions>
 
 <instruction>
-- Write plan to plan file BEFORE calling this tool
+- You MUST write plan to plan file BEFORE calling this tool
 - Tool reads plan from file—does not take plan content as parameter
+- You MUST provide a `title` argument for the final plan artifact (example: `WP_MIGRATION_PLAN`)
+- `.md` is optional in `title`; it is appended automatically when omitted
 - User sees plan contents when reviewing
 </instruction>
 
 <output>
-Presents plan to user for approval. If approved, exits plan mode with full tool access restored.
+Presents plan to user for approval. If approved, plan mode exits with full tool access restored and the plan is renamed to `local://<title>.md`.
 </output>
 
 <example name="ready">
-Plan complete at specified path, no open questions.
-→ Call `exit_plan_mode`
+Plan complete at local://PLAN.md, no open questions.
+→ Call `exit_plan_mode` with `{ "title": "WP_MIGRATION_PLAN" }`
 </example>
 
 <example name="unclear">
@@ -28,11 +30,12 @@ Unsure about auth method (OAuth vs JWT).
 </example>
 
 <avoid>
-- Calling before plan written to file
-- Using `ask` to request plan approval (this tool does that)
-- Calling after pure research tasks (no implementation planned)
+- MUST NOT call before plan is written to file
+- MUST NOT omit `title`
+- MUST NOT use `ask` to request plan approval (this tool does that)
+- MUST NOT call after pure research tasks (no implementation planned)
 </avoid>
 
 <critical>
-Only use when planning implementation steps. Research tasks (searching, reading, understanding) do not need this tool.
+You MUST only use when planning implementation steps. Research tasks (searching, reading, understanding) do not need this tool.
 </critical>

package/src/prompts/tools/find.md

@@ -6,7 +6,7 @@ Fast file pattern matching that works with any codebase size.
 - Pattern includes the search path: `src/**/*.ts`, `lib/*.json`, `**/*.md`
 - Simple patterns like `*.ts` automatically search recursively from cwd
 - Includes hidden files by default (use `hidden: false` to exclude)
-- Speculatively perform multiple searches in parallel when potentially useful
+- You SHOULD perform multiple searches in parallel when potentially useful
 </instruction>
 
 <output>
@@ -14,5 +14,5 @@ Matching file paths sorted by modification time (most recent first). Results tru
 </output>
 
 <avoid>
-Open-ended searches requiring multiple rounds of globbing and grepping — use Task tool instead.
+For open-ended searches requiring multiple rounds of globbing and grepping, you MUST use Task tool instead.
 </avoid>

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

@@ -3,9 +3,9 @@
 Generate or edit images using Gemini image models.
 
 <instruction>
-Provide structured parameters for best results. Tool assembles into optimized prompt.
+You SHOULD provide structured parameters for best results. Tool assembles into optimized prompt.
 
-When using multiple `input_images`, describe each image's role in `subject` or `scene` field:
+When using multiple `input_images`, you MUST describe each image's role in `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>
@@ -15,9 +15,9 @@ Returns generated image saved to disk. Response includes file path where image w
 </output>
 
 <caution>
-- 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` for 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
+- For photoreal: you SHOULD add "ultra-detailed, realistic, natural skin texture" to style
+- For posters/cards: you SHOULD use 9:16 aspect ratio with negative space for text placement
+- For iteration: you SHOULD use `changes` for targeted adjustments rather than regenerating from scratch
+- For text: you SHOULD add "sharp, legible, correctly spelled" for important text; keep text short
+- For diagrams: you SHOULD include "scientifically accurate" in style and provide facts explicitly
 </caution>

package/src/prompts/tools/grep.md

@@ -12,6 +12,7 @@ Powerful search tool built on ripgrep.
 
 <output>
 - Results are always content mode.
+- Results grouped by directory (`# dir`) and file (`## └─ file`) headings
 {{#if IS_HASHLINE_MODE}}
 - Text output is CID prefixed: `LINE#ID:content`
 {{else}}
@@ -22,7 +23,7 @@ Powerful search tool built on ripgrep.
 </output>
 
 <critical>
-- ALWAYS use Grep when searching for content.
-- NEVER invoke `grep` or `rg` via Bash.
-- If the search is open-ended, requiring multiple rounds, use Task tool with explore subagent instead
+- You MUST use Grep when searching for content.
+- You MUST NOT invoke `grep` or `rg` via Bash.
+- If the search is open-ended, requiring multiple rounds, you MUST use Task tool with explore subagent instead.
 </critical>

package/src/prompts/tools/hashline.md

@@ -3,25 +3,24 @@
 Apply precise file edits using `LINE#ID` tags, anchoring to the file content.
 
 <workflow>
-1. `read` the target range to capture current `LINE#ID` tags.
-2. Pick the smallest operation per change site (line/range/insert/content-replace).
-3. Direction-lock every edit: exact current text → intended text.
-4. Submit one `edit` call per file containing all operations.
-5. If another edit is needed in that file, re-read first (hashes changed).
-6. Output tool calls only; no prose.
+1. You MUST `read` the target range to capture current `LINE#ID` tags.
+2. You MUST pick the smallest operation per change site (line/range/insert/content-replace).
+3. You MUST direction-lock every edit: exact current text → intended text.
+4. You MUST submit one `edit` call per file containing all operations.
+5. If another edit is needed in that file, you MUST re-read first (hashes changed).
+6. You MUST output tool calls only; no prose.
 </workflow>
 
 <operations>
-- **Single line replace/delete**
-  - `{ op: "set", tag: "N#ID", content: […] }`
-  - `content: null` deletes the line; `content: [""]` keeps a blank line.
-- **Range replace/delete**
-  - `{ op: "replace", first: "N#ID", last: "N#ID", content: […] }`
+Every edit has `op`, `first` (start anchor), `last` (end anchor), and `content`. All anchors use `"LINE#ID"` format.
+- **Line or range replace/delete**
+  - `{ op: "replace", first: "N#ID", content: […] }` (single line)
+  - `{ op: "replace", first: "N#ID", last: "N#ID", content: […] }` (range)
   - Use for swaps, block rewrites, or deleting a full span (`content: null`).
 - **Insert** (new content)
-  - `{ op: "prepend", before: "N#ID", content: […] }` or `{ op: "prepend", content: […] }` (no `before` = insert at beginning of file)
-  - `{ op: "append", after: "N#ID", content: […] }` or `{ op: "append", content: […] }` (no `after` = insert at end of file)
-  - `{ op: "insert", after: "N#ID", before: "N#ID", content: […] }` (between adjacent anchors; safest for blocks)
+  - `{ op: "prepend", last: "N#ID", content: […] }` or `{ op: "prepend", content: […] }` (no anchor = insert at beginning of file)
+  - `{ op: "append", first: "N#ID", content: […] }` or `{ op: "append", content: […] }` (no anchor = insert at end of file)
+  - `{ op: "insert", first: "N#ID", last: "N#ID", content: […] }` (between adjacent anchors; safest for blocks)
 - **File-level controls**
   - `{ delete: true, edits: [] }` deletes the file (cannot be combined with `rename`).
   - `{ rename: "new/path.ts", edits: […] }` writes result to new path and removes old path.
@@ -29,33 +28,33 @@ Apply precise file edits using `LINE#ID` tags, anchoring to the file content.
 </operations>
 
 <rules>
-1. **Minimize scope:** one logical mutation site per operation.
-2. **Preserve formatting:** keep indentation, punctuation, line breaks, trailing commas, brace style.
-3. **Prefer insertion over neighbor rewrites:** anchor on structural boundaries (`}`, `]`, `},`) not interior property lines.
-4. **No no-ops:** replacement content must differ from current content.
-5. **Touch only requested code:** avoid incidental edits.
-6. **Use exact current tokens:** never rewrite approximately; mutate the token that exists now.
-7. **For swaps/moves:** prefer one range operation over multiple single-line operations.
+1. **Minimize scope:** You MUST use one logical mutation site per operation.
+2. **Preserve formatting:** You MUST keep indentation, punctuation, line breaks, trailing commas, brace style.
+3. **Prefer insertion over neighbor rewrites:** You SHOULD anchor on structural boundaries (`}`, `]`, `},`) not interior property lines.
+4. **No no-ops:** replacement content MUST differ from current content.
+5. **Touch only requested code:** You MUST NOT make incidental edits.
+6. **Use exact current tokens:** You MUST NOT rewrite approximately; mutate the token that exists now.
+7. **For swaps/moves:** You SHOULD prefer one range operation over multiple single-line operations.
 </rules>
 
-<op_choice>
-- One wrong line → `set`
-- Adjacent block changed → `insert`
-- Missing line/block → insert with `append`/`prepend`
-</op_choice>
+<op-choice>
+- One wrong line → MUST use `set`
+- Adjacent block changed → MUST use `insert`
+- Missing line/block → MUST use `append`/`prepend`
+</op-choice>
 
-<tag_choice>
-- Copy tags exactly from the prefix of the `read` or error output.
-- Never guess tags.
-- For inserts, prefer `insert` > `append`/`prepend` when both boundaries are known.
-- Re-read after each successful edit call before issuing another on same file.
-</tag_choice>
+<tag-choice>
+- You MUST copy tags exactly from the prefix of the `read` or error output.
+- You MUST NOT guess tags.
+- For inserts, you SHOULD prefer `insert` > `append`/`prepend` when both boundaries are known.
+- You MUST re-read after each successful edit call before issuing another on same file.
+</tag-choice>
 
 <recovery>
 **Tag mismatch (`>>>`)**
-- Retry with the updated tags shown in error output.
-- Re-read only if required tags are missing from error snippet.
-- If mismatch repeats, stop and re-read the exact block.
+- You MUST retry with the updated tags shown in error output.
+- You MUST re-read only if required tags are missing from error snippet.
+- If mismatch repeats, you MUST stop and re-read the exact block.
 </recovery>
 
 <example name="fix a value or type">
@@ -63,8 +62,8 @@ Apply precise file edits using `LINE#ID` tags, anchoring to the file content.
 {{hlinefull 23 "  const timeout: number = 5000;"}}
 ```
 ```
-op: "set"
-tag: "{{hlineref 23 "  const timeout: number = 5000;"}}"
+op: "replace"
+first: "{{hlineref 23 "  const timeout: number = 5000;"}}"
 content: ["  const timeout: number = 30_000;"]
 ```
 </example>
@@ -75,8 +74,8 @@ content: ["  const timeout: number = 30_000;"]
 {{hlinefull 8 "const data = fetchSync(url);"}}
 ```
 ```
-op: "set"
-tag: "{{hlineref 7 "// @ts-ignore"}}"
+op: "replace"
+first: "{{hlineref 7 "// @ts-ignore"}}"
 content: null
 ```
 </example>
@@ -86,8 +85,8 @@ content: null
 {{hlinefull 14 "  placeholder: \"DO NOT SHIP\","}}
 ```
 ```
-op: "set"
-tag: "{{hlineref 14 "  placeholder: \"DO NOT SHIP\","}}"
+op: "replace"
+first: "{{hlineref 14 "  placeholder: \"DO NOT SHIP\","}}"
 content: [""]
 ```
 </example>
@@ -129,10 +128,10 @@ content: null
 ```
 ```
 op: "prepend"
-before: "{{hlineref 1 "import * as fs from \"node:fs/promises\";"}}"
+last: "{{hlineref 1 "import * as fs from \"node:fs/promises\";"}}"
 content: ["import * as os from \"node:os\";"]
 ```
-Use `before` for anchored insertion before a specific line. Omit `before` to prepend at BOF.
+Use `last` for anchored insertion before a specific line. Omit anchor to prepend at BOF.
 </example>
 
 <example name="append at end of file">
@@ -141,10 +140,10 @@ Use `before` for anchored insertion before a specific line. Omit `before` to pre
 ```
 ```
 op: "append"
-after: "{{hlineref 260 "export { serialize, deserialize };"}}"
+first: "{{hlineref 260 "export { serialize, deserialize };"}}"
 content: ["export { validate };"]
 ```
-Use `after` for anchored insertion after a specific line. Omit `after` to append at EOF.
+Use `first` for anchored insertion after a specific line. Omit anchor to append at EOF.
 </example>
 
 <example name="add an entry between known siblings">
@@ -154,8 +153,8 @@ Use `after` for anchored insertion after a specific line. Omit `after` to append
 ```
 ```
 op: "insert"
-after: "{{hlineref 44 "  \"build\": \"bun run compile\","}}"
-before: "{{hlineref 45 "  \"test\": \"bun test\""}}"
+first: "{{hlineref 44 "  \"build\": \"bun run compile\","}}"
+last: "{{hlineref 45 "  \"test\": \"bun test\""}}"
 content: ["  \"lint\": \"biome check\","]
 ```
 Dual anchors pin the insert to exactly one gap, preventing drift from edits elsewhere in the file. **Always prefer dual anchors when both boundaries are content lines.**
@@ -170,10 +169,10 @@ Dual anchors pin the insert to exactly one gap, preventing drift from edits else
 ```
 ```
 op: "insert"
-before: "{{hlineref 103 "export function serialize(data: unknown): string {"}}"
+last: "{{hlineref 103 "export function serialize(data: unknown): string {"}}"
 content: ["function validate(data: unknown): boolean {", "  return data != null && typeof data === \"object\";", "}", ""]
 ```
-The trailing `""` in `content` preserves the blank-line separator. **Anchor to the structural line (`export function ...`), not the blank line above it** — blank lines are ambiguous and may be added or removed by other edits.
+The trailing `""` in `content` preserves the blank-line separator. **Anchor to the structural line (`export function …`), not the blank line above it** — blank lines are ambiguous and may be added or removed by other edits.
 </example>
 
 <example name="file delete">
@@ -194,23 +193,23 @@ edits: […]
 <example name="anti-pattern: anchoring to whitespace">
 Bad — tags to a blank line; fragile if blank lines shift:
 ```
-after: "{{hlineref 102 ""}}"
+first: "{{hlineref 102 ""}}"
 content: ["function validate() {", …, "}"]
 ```
 
 Good — anchors to the structural target:
 
 ```
-before: "{{hlineref 103 "export function serialize(data: unknown): string {"}}"
+last: "{{hlineref 103 "export function serialize(data: unknown): string {"}}"
 content: ["function validate() {", …, "}"]
 ```
 </example>
 
 <critical>
-Ensure:
+You MUST ensure:
 - Payload shape is `{ "path": string, "edits": [operation, …], "delete"?: boolean, "rename"?: string }`
-- Every edit matches exactly one variant
-- Every tag has been copied EXACTLY from a tool result as `N#ID`
-- Scope is minimal and formatting is preserved except targeted token changes
+- Each edit has `op`, optional `first`/`last` anchors, and `content`
+- Every tag MUST be copied EXACTLY from a tool result as `N#ID`
+- Scope MUST be minimal and formatting MUST be preserved except targeted token changes
 </critical>
-**Final reminder:** tags are immutable references to the last read snapshot. Re-read when state changes, then edit.
+**Final reminder:** tags are immutable references to the last read snapshot. You MUST re-read when state changes, then edit.

package/src/prompts/tools/patch.md

@@ -43,11 +43,11 @@ Returns success/failure; on failure, error message indicates:
 </output>
 
 <critical>
-- Always read target file before editing
-- Copy anchors and context lines verbatim (including whitespace)
-- Never use anchors as comments (no line numbers, location labels, placeholders like `@@ @@`)
-- Do not place new lines outside intended block
-- If edit fails or breaks structure, re-read file and produce new patch from current content—do not retry same diff
+- You MUST read the target file before editing
+- You MUST copy anchors and context lines verbatim (including whitespace)
+- You MUST NOT use anchors as comments (no line numbers, location labels, placeholders like `@@ @@`)
+- You MUST NOT place new lines outside the intended block
+- If edit fails or breaks structure, you MUST re-read the file and produce a new patch from current content — you MUST NOT retry the same diff
 - **NEVER** use edit to fix indentation, whitespace, or reformat code. Formatting is a single command run once at the end (`bun fmt`, `cargo fmt`, `prettier --write`, etc.)—not N individual edits. If you see inconsistent indentation after an edit, leave it; the formatter will fix all of it in one pass.
 </critical>
 
@@ -60,7 +60,7 @@ edit {"path":"src/app.py","op":"update","diff":"@@ def greet():\n def greet():\n
 </example>
 
 <example name="rename">
-edit {"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n ...\n"}
+edit {"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n …\n"}
 </example>
 
 <example name="delete">

package/src/prompts/tools/poll-jobs.md

@@ -2,6 +2,6 @@
 
 Block until one or more background jobs complete, fail, or are cancelled.
 
-Use this instead of polling `read jobs://` in a loop when you need to wait for background task or bash results before continuing.
+You MUST use this instead of polling `read jobs://` in a loop when you need to wait for background task or bash results before continuing.
 
 Returns the status and results of all watched jobs once at least one finishes.

package/src/prompts/tools/python.md

@@ -5,13 +5,13 @@ Runs Python cells sequentially in persistent IPython kernel.
 <instruction>
 Kernel persists across calls and cells; **imports, variables, and functions survive—use this.**
 **Work incrementally:**
-- One logical step per cell (imports, define function, test it, use it)
-- Pass multiple small cells in one call
-- Define small functions you can reuse and debug individually
-- Put explanations in assistant message or cell title, **not** in code
+- You SHOULD use one logical step per cell (imports, define function, test it, use it)
+- You SHOULD pass multiple small cells in one call
+- You SHOULD define small functions you can reuse and debug individually
+- You MUST put explanations in assistant message or cell title, MUST NOT put them in code
 **When something fails:**
 - Errors tell you which cell failed (e.g., "Cell 3 failed")
-- Resubmit only fixed cell (or fixed cell + remaining cells)
+- You SHOULD resubmit only the fixed cell (or fixed cell + remaining cells)
 </instruction>
 
 <prelude>
@@ -34,23 +34,21 @@ All helpers auto-print results and return values for chaining.
 </prelude>
 
 <output>
-Streams in real time, truncated after 100KB; if truncated, full output stored under $ARTIFACTS and referenced as `artifact://<id>` in metadata.
-
 User sees output like Jupyter notebook; rich displays render fully:
 - `display(JSON(data))` → interactive JSON tree
-- `display(HTML(...))` → rendered HTML
-- `display(Markdown(...))` → formatted markdown
+- `display(HTML(…))` → rendered HTML
+- `display(Markdown(…))` → formatted markdown
 - `plt.show()` → inline figures
-  **You will see object repr** (e.g., `<IPython.core.display.JSON object>`). Trust `display()`; do not assume user sees only repr.
+  **You will see object repr** (e.g., `<IPython.core.display.JSON object>`). Trust `display()`; you MUST NOT assume user sees only repr.
 </output>
 
 <caution>
 - Per-call mode uses fresh kernel each call
-- Use `reset: true` to clear state when session mode active
+- You MUST use `reset: true` to clear state when session mode active
 </caution>
 
 <critical>
-- Use `run()` for shell commands; never raw `subprocess`
+- You MUST use `run()` for shell commands; you MUST NOT use raw `subprocess`
 </critical>
 
 <example name="good">

package/src/prompts/tools/read.md

@@ -1,6 +1,6 @@
 # Read
 
-Reads files from local filesystem or internal URLs.
+Reads files from local filesystem or harness URLs.
 
 <instruction>
 - Reads up to {{DEFAULT_MAX_LINES}} lines default
@@ -14,17 +14,7 @@ Reads files from local filesystem or internal URLs.
 {{/if}}
 - Supports images (PNG, JPG) and PDFs
 - For directories, returns formatted listing with modification times
-- Parallelize reads when exploring related files
-- 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
-  - `memory://root` - read memory summary (`memory_summary.md`)
-  - `memory://root/<path>` - read relative path within project memory root
-  - `agent://<id>` - read agent output artifact
-  - `agent://<id>/<path>` or `agent://<id>?q=<query>` - extract JSON from agent output
-  - `docs://` - list available pi documentation files
-  - `docs://<file>.md` - read a specific pi documentation file
+- You SHOULD parallelize reads when exploring related files
 </instruction>
 
 <output>

package/src/prompts/tools/replace.md

@@ -3,10 +3,10 @@
 String replacements in files with fuzzy whitespace matching.
 
 <instruction>
-- Use smallest edit that uniquely identifies change
-- If `old_text` not unique, expand to include more context or use `all: true` to replace all occurrences
+- You MUST use the smallest edit that uniquely identifies the change
+- If `old_text` not unique, you MUST 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
+- You SHOULD prefer editing existing files over creating new ones
 </instruction>
 
 <output>
@@ -14,17 +14,17 @@ Returns success/failure status. On success, file modified in place with replacem
 </output>
 
 <critical>
-- Must read file at least once in conversation before editing. Tool errors if you attempt edit without reading file first.
+- You MUST read the file at least once in the conversation before editing. Tool errors if you attempt edit without reading file first.
 </critical>
 
-<bash*alternatives>
+<bash-alternatives>
 Replace for content-addressed changes—you identify \_what* to change by its text.
 
 For position-addressed or pattern-addressed changes, bash more efficient:
 
 |Operation|Command|
 |---|---|
-|Append to file|`cat >> file <<'EOF'`...`EOF`|
+|Append to file|`cat >> file <<'EOF'`…`EOF`|
 |Prepend to file|`{ cat - file; } <<'EOF' > tmp && mv tmp file`|
 |Delete lines N-M|`sed -i 'N,Md' file`|
 |Insert after line N|`sed -i 'Na\text' file`|
@@ -35,4 +35,4 @@ For position-addressed or pattern-addressed changes, bash more efficient:
 
 Use Replace when _content itself_ identifies location.
 Use bash when _position_ or _pattern_ identifies what to change.
-</bash_alternatives>
+</bash-alternatives>

package/src/prompts/tools/ssh.md

@@ -3,7 +3,7 @@
 Run commands on remote hosts.
 
 <instruction>
-Build commands from reference below
+You MUST build commands from the reference below
 </instruction>
 
 <commands>
@@ -23,13 +23,8 @@ Build commands from reference below
 - Navigation: `cd`, `echo %CD%`
 </commands>
 
-<output>
-stdout/stderr combined, truncated at 50KB; exit code captured.
-If truncated, full output stored under $ARTIFACTS as `artifact://<id>`.
-</output>
-
 <critical>
-Verify shell type from "Available hosts", use matching commands.
+You MUST verify the shell type from "Available hosts" and use matching commands.
 </critical>
 
 <example name="linux">