@oh-my-pi/pi-coding-agent 16.1.1 → 16.1.2

package/src/prompts/tools/debug.md

@@ -1,21 +1,17 @@
-Provides debugger access through the Debug Adapter Protocol (DAP).
-Use for launching or attaching debuggers, setting breakpoints, stepping through execution, inspecting threads/stack/variables, evaluating expressions, capturing output, and interrupting hung programs.
+Debugger access.
 
 <instruction>
-- You SHOULD prefer this tool over bash for program state, breakpoints, stepping, thread inspection, or interrupting a running process.
-- `action: "launch"` starts a session; `program` is required, `adapter` optional (auto-selected from target path and workspace).
-  For Python, set `adapter: "debugpy"` and `program` to the target `.py` file; put interpreter/script flags in `args`.
-- `action: "attach"` connects to an existing process: `pid` for local attach, `port` for remote attach (where the adapter supports it), `adapter` to force a specific debugger.
-- **Breakpoints**: `set_breakpoint`/`remove_breakpoint` with source (`file`+`line`) or function (`function`); optional `condition` for conditional breakpoints.
-- **Flow control**: `continue` (resumes; briefly waits to observe whether the program stops or keeps running), `step_over`/`step_in`/`step_out` (single-step), `pause` (interrupt a running program so you can inspect state).
-- **Inspect**: `threads` (list), `stack_trace` (frames for current stopped thread), `scopes` (needs `frame_id` or a current stopped frame), `variables` (needs `variable_ref` or `scope_id`), `evaluate` (needs `expression`; `context: "repl"` for raw debugger commands when the adapter supports them), `output` (captured stdout/stderr/console), `sessions` (tracked debug sessions), `terminate`.
-- Timeouts apply per-request, not to the full session lifetime.
+- You SHOULD prefer this over bash for program state, breakpoints, stepping, thread inspection, or interrupting a running process.
+- `action: "launch"` starts a session; `program` required, `adapter` optional. Python: `adapter: "debugpy"`, `program` = target `.py`, interpreter/script flags in `args`.
+- `action: "attach"` connects to a running process: `pid` (local), `port` (remote), `adapter` forces a specific debugger.
+- **Breakpoints**: `set_breakpoint`/`remove_breakpoint` with source (`file`+`line`) or function (`function`); optional `condition`.
+- **Flow control**: `continue` (resume), `step_over`/`step_in`/`step_out` (single-step), `pause` (interrupt a running program).
+- **Inspect**: `threads`, `stack_trace` (current stopped thread), `scopes` (needs `frame_id` or current stopped frame), `variables` (needs `variable_ref` or `scope_id`), `evaluate` (needs `expression`; `context: "repl"` for raw debugger commands), `output` (stdout/stderr/console), `sessions`, `terminate`.
 </instruction>
 
 <caution>
-- Only one active debug session is supported at a time.
-- Some adapters require a launched session to receive `configurationDone` before the target actually runs; if the tool says configuration is pending, set breakpoints and then call `continue`.
-- Adapter availability depends on local binaries. Common built-ins: `gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv dap`.
-- `program` must be an executable file or debug target, not a directory or interpreter name that resolves to a workspace directory.
-- Python debugging requires `debugpy`; install with `pip install debugpy` if the adapter is unavailable.
+- Only one active debug session at a time.
+- Valid `adapter` values: `gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv dap` (must be installed locally).
+- `program` must be an executable file or debug target, not a directory or bare interpreter name.
+- Python debugging requires `debugpy`; `pip install debugpy` if unavailable.
 </caution>

package/src/prompts/tools/eval.md

@@ -1,34 +1,34 @@
 Run code in a persistent kernel using a list of cells.
 
 <instruction>
-Cells run in array order. State persists per language — across cells, tool calls, and `task` subagents: variables either side defines are visible to the other. Stage helpers, datasets, or live clients once; subagents use them directly — no re-importing or serializing across the boundary.
+Cells run in array order. State persists per language across cells, tool calls, and `task` subagents — stage helpers/datasets/clients once, subagents reuse directly, no re-import/serialize.
 
 Cell fields:
 
-- `language` — {{#if py}}`"py"` for the IPython kernel{{/if}}{{#ifAll py js}}, {{/ifAll}}{{#if js}}`"js"` for the persistent JavaScript VM{{/if}}.
-- `code` — cell body, verbatim. Newlines and quotes JSON-encoded; no fences, no headers.
+- `language` — {{#if py}}`"py"` IPython kernel{{/if}}{{#ifAll py js}}, {{/ifAll}}{{#if js}}`"js"` persistent JavaScript VM{{/if}}.
+- `code` — cell body, verbatim. Newlines/quotes JSON-encoded; no fences, no headers.
 - `title` (optional) — short transcript label (e.g. `"imports"`).
-- `timeout` (optional) — per-cell seconds (1-3600, default 30). Bounds the cell's own work only; the clock pauses while `agent()`/`parallel()`/`completion()` calls are in flight, so fanouts never need a raise. Raise only for heavy local compute or long non-agent tool calls.
+- `timeout` (optional) — per-cell seconds. Raise only for heavy compute or long non-agent tool calls.
 - `reset` (optional) — wipe this cell's language kernel first.{{#ifAll py js}} Per-language: a `py` reset never touches the JS VM.{{/ifAll}}
 
-Work incrementally: one logical step per cell (imports, define, test, use); pass multiple small cells per call; define small reusable functions for individual debugging. Workflow explanations go in the assistant message or `title`, never inside cell code.
-{{#if py}}Python runs in IPython with a live event loop: use top-level `await` directly; `asyncio.run(…)` raises "cannot be called from a running event loop".{{/if}}
-On failure, errors name the failing cell ("Cell 3 failed") — resubmit only the fixed cell (plus any remaining).
+Work incrementally — one logical step per cell (imports, define, test, use), many small cells per call; workflow notes in the assistant message or `title`, never in cell code.
+{{#if py}}Live event loop: use top-level `await` directly; `asyncio.run(…)` raises "cannot be called from a running event loop".{{/if}}
+Errors name the failing cell ("Cell 3 failed") — resubmit the fixed cell + any remaining.
 </instruction>
 
 <prelude>
-{{#ifAll py js}}Same helpers in both runtimes, same positional order. Python: helpers run synchronously; trailing options are keyword args. JavaScript: helpers are async and `await`able; trailing options are ONE trailing object literal, never positional (extra positional args throw).{{else}}{{#if py}}Helpers run synchronously. Trailing options are keyword arguments.{{/if}}{{#if js}}Helpers are async and `await`able. Trailing options are ONE trailing object literal, never positional (extra positional args throw).{{/if}}{{/ifAll}}
+{{#ifAll py js}}Same helpers + arg order, both runtimes. Python: sync, options = trailing kwargs. JS: async/`await`able, options = ONE trailing object literal, never positional (extras throw).{{else}}{{#if py}}Sync; options = trailing kwargs.{{/if}}{{#if js}}Async/`await`able; options = ONE trailing object literal, never positional (extras throw).{{/if}}{{/ifAll}}
 ```
 display(value) → None
-    Render value in cell output, shows presentable values natively (figures, images, dataframes)
+    Cell output; figures/images/dataframes shown natively.
 print(value, ...) → None
-    Print to text output.
+    Text output.
 read(path, offset?=1, limit?=None) → str
-    Read file as text; offset/limit are 1-indexed lines. Accepts `local://…`.
+    File as text; offset/limit 1-indexed lines. Accepts `local://…`.
 write(path, content) → str
-    Write file (creates parents); returns resolved path. `local://…` persists across turns / subagents.
+    Write file (creates parents) → resolved path. `local://…` persists across turns/subagents.
 append(path, content) → str
-    Append to file; returns resolved path. Accepts `local://…`.
+    Append → resolved path. Accepts `local://…`.
 tree(path?=".", max_depth?=3, show_hidden?=False) → str
     Directory tree.
 diff(a, b) → str
@@ -36,35 +36,35 @@ diff(a, b) → str
 env(key?=None, value?=None) → str | None | dict
     No args → full env dict; one → value of `key`; two → set `key=value`, return value.
 output(*ids, format?="raw", query?=None, offset?=None, limit?=None) → str | dict | list[dict]
-    Read task/agent output by id; one id → text/dict, multiple → list.
+    Task/agent output by id; one → text/dict, multiple → list.
 tool.<name>(args) → unknown
-    Invoke any session tool; `args` is its parameter object.
+    Invoke any session tool; `args` = its parameter object.
 completion(prompt, model?="default", system?=None, schema?=None) → str | dict
-    Oneshot stateless completion (no history, no tools). `model` tier: "smol" (fast) | "default" (session model) | "slow" (most capable). JSON-Schema `schema` forces structured output, returns parsed object.
+    Oneshot, stateless (no history/tools). `model`: "smol" fast | "default" session | "slow" most capable. `schema` (JSON-Schema) → structured output, parsed object.
 {{#if spawns}}agent(prompt, agent_type?="task", model?=None, label?=None, schema?=None, return_handle?=False) → str | dict
-    Run a subagent, return its final output. `agent_type`/`agentType` picks another discovered agent; `schema` as in completion(). Share background via `local://` files referenced in the prompt. `return_handle`/`returnHandle` → a DAG node dict { text, output, handle: "agent://<id>", id, agent } (parsed object under `data` when `schema` set) so a downstream stage references the transcript by handle instead of re-inlining it.
+    Run a subagent → final output. `agent_type`/`agentType` picks another discovered agent; `schema` as in completion(). Background via `local://` files named in the prompt. `return_handle`/`returnHandle` → DAG node dict { text, output, handle: "agent://<id>", id, agent } (parsed under `data` when `schema` set).
 {{#if js}}    JS: options are ONE trailing object — agent(prompt, { agentType, schema, returnHandle }).
 {{/if}}
 {{/if}}
 parallel(thunks) → list
-    Run thunks through a bounded pool (as wide as a `task` batch — don't pre-shrink), preserving input order. Barrier: returns when all finish; a throwing thunk propagates.
+    Thunks through a bounded pool (wide as a `task` batch — don't pre-shrink), input order kept; returns when all finish, a throwing thunk propagates.
 pipeline(items, ...stages) → list
-    Map items through one-arg stages left-to-right, barrier between stages; stage 1 gets the item, later stages the previous result. Same pool width as parallel().
+    Map items through one-arg stages left-to-right, barrier between stages; stage 1 gets the item, later stages the previous result.
 log(message) → None
     Progress line above the status tree.
 phase(title) → None
-    Start a phase grouping subsequent status lines.
+    Phase grouping subsequent status lines.
 budget → per-turn token budget
-    {{#if py}}`budget.total` (ceiling or None), `budget.spent()`, `budget.remaining()` (math.inf when no ceiling), `budget.hard` (bool).{{/if}}{{#if js}}`await budget.total()` (ceiling or null), `await budget.spent()`, `await budget.remaining()` (Infinity when no ceiling), `await budget.hard()`.{{/if}} Ceiling comes from a `+Nk` directive (advisory) or `+Nk!`/Goal Mode (hard — `agent()` refuses to spawn past it); otherwise None/null, spend still tracked across the turn.
+    {{#if py}}`budget.total` (ceiling or None), `budget.spent()`, `budget.remaining()` (math.inf when no ceiling), `budget.hard`.{{/if}}{{#if js}}`await budget.total()` (ceiling or null), `await budget.spent()`, `await budget.remaining()` (Infinity when no ceiling), `await budget.hard()`.{{/if}} Ceiling: `+Nk` (advisory) or `+Nk!`/Goal Mode (hard — `agent()` won't spawn past it); spend still tracked.
 ```
 </prelude>
 {{#if spawns}}
 <dag>
-Build a dependency graph by piping handles through the stage helpers — ephemeral, in-session, acyclic waves:
-- **Name nodes.** Capture each `agent(…, {{#if py}}return_handle=True{{/if}}{{#if js}}{ returnHandle: true }{{/if}})` result; it carries `handle` (`agent://<id>`) + `output`.
-- **Wire edges by reference.** Embed an upstream node's `handle` or `output` in the dependent stage's prompt so a large transcript flows by reference, never re-inlined. For bulk artifacts, `write("local://<name>.md", …)` and pass the URI.
-- **`pipeline(items, *stages)` = staged waves** with a barrier between stages (every item clears stage N before any enters stage N+1) — the linear spine of a DAG. **`parallel(thunks)` = one wave** of independent nodes.
-- **Isolate failure.** A raising node re-raises the lowest-index error and aborts its wave; wrap each risky node in try/except so a failed node degrades only its dependent subtree while independent branches still finish.
-- **Acyclic only.** A node never waits on its own descendant; cycles are an authoring bug, not a supported pattern.
+Pipe handles through stage helpers to build a dependency graph — acyclic waves:
+- **Name nodes.** Capture each `agent(…, {{#if py}}return_handle=True{{/if}}{{#if js}}{ returnHandle: true }{{/if}})` result; carries `handle` (`agent://<id>`) + `output`.
+- **Wire edges by reference.** Put an upstream node's `handle`/`output` in the dependent stage's prompt — large transcript never re-inlined. Bulk: `write("local://<name>.md", …)`, pass the URI.
+- **`pipeline(items, *stages)` = staged waves**, barrier between stages (every item clears stage N before any enters N+1). **`parallel(thunks)` = one wave** of independent nodes.
+- **Isolate failure.** A raising node re-raises the lowest-index error, aborts its wave; wrap risky nodes in try/except so a failure degrades only its dependent subtree, independent branches finish.
+- **Acyclic only.** A node never waits on its own descendant.
 </dag>
 {{/if}}

package/src/prompts/tools/find.md

@@ -1,21 +1,17 @@
-Finds files and directories using fast pattern matching that works with any codebase size.
+Finds files and directories via fast pattern matching, any codebase size.
 
 <instruction>
-- `paths` is required and accepts an array of globs, files, or directories
-- Pass multiple targets as **separate array elements** (`paths: ["a", "b"]`).
-- `gitignore` defaults to `true` and hides files matched by `.gitignore`. Set `gitignore: false` to find `.env*`, `*.log`, freshly-created build outputs, or anything else your repo ignores
-- `hidden` defaults to `true`; combine with `gitignore: false` to surface dotfiles that are also gitignored
-- `limit` is clamped to 1-200 (default 200). Narrow the pattern instead of raising the limit
-- `timeout` is in seconds (default 5, clamped to 0.5–60). On timeout, find returns whatever partial matches it has collected with `truncated: true` and a notice — increase `timeout` or narrow the pattern instead of retrying blindly
-- You SHOULD perform multiple searches in parallel when potentially useful
+- `paths`: array of globs, files, or directories.
+- `gitignore` (default `true`) hides `.gitignore` matches. Set `gitignore: false` to find `.env*`, `*.log`, fresh build outputs, or anything your repo ignores.
+- `hidden` (default `true`); combine with `gitignore: false` to surface dotfiles also gitignored.
 </instruction>
 
 <output>
-Matching file and directory paths sorted by modification time (most recent first), grouped by directory to reduce token usage. Each group starts with `# <dir>/` followed by basenames (one per line); directory entries get a trailing `/`. Root-level entries have no header. Truncated at 200 entries or 50KB.
+Matching paths sorted by mtime (newest first), grouped under `# <dir>/` headers with basenames below; directories get a trailing `/`.
 </output>
 
 <avoid>
-For open-ended searches requiring multiple rounds of globbing and searching, you MUST use Task tool instead.
+Open-ended searches needing multiple rounds of globbing/searching: you MUST use the Task tool instead.
 </avoid>
 
 <critical>

package/src/prompts/tools/github.md

@@ -1,21 +1,17 @@
-GitHub CLI tool with a single op-based dispatch. Wraps `gh` for repositories, pull requests, search, checkout, push, and Actions watch workflows. For reading a single issue or PR view, use the `issue://<N>` or `pr://<N>` URL schemes (cached automatically). For reading PR diffs, use `pr://<N>/diff` (changed-file listing), `pr://<N>/diff/<i>` (single file slice, 1-indexed), or `pr://<N>/diff/all` (full unified diff).
+Op-based `gh` wrapper: repos, PRs, search, checkout, push, Actions watch. Read an issue/PR via `issue://<N>`/`pr://<N>`. PR diffs: `pr://<N>/diff` (file listing), `pr://<N>/diff/<i>` (file slice, 1-indexed), `pr://<N>/diff/all` (full diff).
 
 <instruction>
-Pick the operation via `op`. Each op uses a subset of the parameters:
-- `repo_view` — Read repository metadata. Optional `repo` (owner/repo) and `branch`. Falls back to the current checkout or default `gh` repo.
-- `pr_create` — Create a pull request. Either provide `title` (and optional `body`) or set `fill: true` to auto-fill from commits. Optional `base` (target, defaults to repo default), `head` (source, defaults to current branch), `draft`, `repo`, `reviewer[]`, `assignee[]`, `label[]`. Returns the new PR URL plus a summary.
-- `pr_checkout` — Check one or more pull requests out into dedicated git worktrees. Optional `pr` (number, URL, branch, or array of any of those — pass an array to batch-check-out multiple PRs in one call), `repo`, `force` (reset existing local branch).
-- `pr_push` — Push a checked-out PR branch back to its source branch. Requires the branch to have been checked out via `op: pr_checkout`. Optional `branch`; defaults to the current checked-out git branch. Optional `forceWithLease`.
-- `search_issues` — Search issues using normal GitHub issue search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`.
-- `search_prs` — Search pull requests using normal GitHub PR search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`.
-- `search_code` — Search code with GitHub code search syntax. Required `query`. Optional `repo`, `limit`. Returns matching paths with surrounding fragments. Date filtering (`since`/`until`) is **not** supported by GitHub code search.
-- `search_commits` — Search commits. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`. `dateField` is ignored — always uses `committer-date`.
-- `search_repos` — Search repositories across GitHub. Optional `query` (required unless `since`/`until` is set), `limit`, `since`, `until`, `dateField` (use query qualifiers like `org:`, `language:` instead of `repo`).
-- All `search_*` ops except `search_repos` default `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
-- Date filter format for `since` / `until`: relative duration `<n><unit>` (`m`/`h`/`d`/`w`/`mo`/`y`, e.g. `3d`, `12h`, `2w`), an ISO date `YYYY-MM-DD`, or an ISO datetime. Translated to a single GitHub-search qualifier (`created:≥…`, `created:≤…`, or `created:since..until`). `dateField: "updated"` maps to `updated:` for issues/prs and `pushed:` for repos. When you only want a date filter and no keywords, omit `query` entirely.
-- `run_watch` — Watch a GitHub Actions workflow run. Optional `run` (id or URL). Omitting `run` watches all workflow runs for the current HEAD commit; `branch` falls back to the current branch. Optional `tail` (log lines per failed job). Fast-fails on the first job failure and returns tailed logs for the failed jobs.
+Pick op via `op`. Beyond the field descriptions, per op:
+- `repo_view` — omit `repo` to view the current checkout.
+- `pr_create` — `head` defaults to the current branch.
+- `pr_checkout` — checks PR(s) out into dedicated git worktrees, not your working tree; pass an array of `pr` to batch multiple in one call.
+- `pr_push` — requires the branch to have been checked out first via `op: pr_checkout`.
+- `search_issues`/`search_prs`/`search_commits`/`search_repos` — `query` is optional when `since`/`until` is set (omit it for a date-only filter). `search_code` supports neither: `query` is required and `since`/`until` are rejected.
+- `search_*` default `repo` to the current checkout's `owner/repo`; pass a `repo:`/`org:`/`user:` qualifier in `query` to search elsewhere. `search_repos` is the exception — it ignores `repo`; scope it with `org:`/`language:` qualifiers in `query`.
+- `since`/`until` — relative duration (`<n>` + `m`/`h`/`d`/`w`/`mo`/`y`, e.g. `3d`, `2w`), ISO date (`YYYY-MM-DD`), or ISO datetime. `dateField: "updated"` filters on update time (issues/PRs) or push time (repos), not creation.
+- `run_watch` — omit `run` to watch every run for the current HEAD (`branch` falls back to current). Fast-fails on the first job failure.
 </instruction>
 
 <output>
-Returns a concise readable summary tailored to the chosen op (repo metadata, PR metadata, diff text, search results, checkout info, push target, or workflow run snapshot). For `run_watch`, the full failed-job logs are saved as a session artifact when failures occur.
+Concise summary per op. `run_watch` failures save full logs to a session artifact.
 </output>

package/src/prompts/tools/goal.md

@@ -7,12 +7,5 @@ Use a single `op` field:
 - `complete` marks the goal complete after you have verified every deliverable against current evidence.
 - `drop` discards the current goal without completing it.
 
-Examples:
-- `goal({"op":"create","objective":"Implement feature X","token_budget":50000})`
-- `goal({"op":"get"})`
-- `goal({"op":"resume"})`
-- `goal({"op":"complete"})`
-- `goal({"op":"drop"})`
-
 NEVER call `complete` because a budget is low or a turn is ending. Call it only when the goal is actually done and verified.
 If `get` shows a paused goal, call `resume` before continuing work on it.

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

@@ -17,7 +17,6 @@ Inspects an image file with a vision-capable model and returns compact text anal
 </output>
 
 <critical>
-- Parameters are strict: only `path` and `question` are allowed
 - If image submission is blocked by settings, the tool will fail with an actionable error
 - If configured model does not support image input, configure a vision-capable model role before retrying
 </critical>

package/src/prompts/tools/irc.md

@@ -1,42 +1,33 @@
-Sends short text messages to other agents in this process and receives theirs.
+Send/receive short text messages between agents in this process.
 
 <instruction>
-- Main agent is `Main`; subagents reuse their task id (`AuthLoader`, or `AuthLoader-2` when the name repeats).
+- Main agent is `Main`; subagents reuse their task id (`AuthLoader`, `AuthLoader-2` on repeat).
 - `op: "list"` — peers with status (`running` | `idle` | `parked`), unread count, parent, last activity. Use when unsure who exists.
-- `op: "send"` — fire-and-forget `message` to `to` (peer id, or `"all"` to broadcast to live peers). Returns per-recipient receipts immediately; NEVER waits for the recipient to act. Outcomes: `injected` (mid-turn; folded in at next step boundary), `woken` (idle peer started a turn), `revived` (parked peer brought back and woken), `failed`.
-- Messaging an `idle`/`parked` peer is how you wake it — there is no separate revive call.
-- `send` + `await: true` — round-trip: send, then block until that peer's next message (or timeout). Invalid with `to: "all"`.
-- `op: "wait"` — block until a message arrives (optionally only `from` one peer); consumes and returns it. Timeout = clean "no message", not an error.
-- `op: "inbox"` — drain pending messages without blocking (`peek: true` leaves them unread).
-- `replyTo` — id of the message you are answering, so the sender can correlate.
-- Replies arrive only when the recipient sends one. Exception: `await: true` to a peer stuck mid-turn (async execution disabled, e.g. blocked in a synchronous task spawn) gets a side-channel auto-reply from its context. For background on a peer, `read` `history://<id>` instead of interrogating it.
+- `op: "send"` — fire-and-forget; returns per-recipient receipts immediately, NEVER waits for the recipient to act. Outcomes: delivered, or `failed` (unreachable). `to: "all"` broadcasts to live peers.
+- Messaging an `idle`/`parked` peer wakes it — no separate revive call.
+- `op: "wait"` — block for a message (optionally only `from` one peer); consumes + returns it. Timeout = clean "no message", not an error.
+- `op: "inbox"` — drain pending messages without blocking.
+- Replies arrive only when the recipient sends one. For peer background, `read` `history://<id>`, don't interrogate.
 </instruction>
 
 <when_to_use>
-Reach for `irc` proactively when continuing alone is wasteful or wrong; when in doubt, message.
-- **Unexpected state** — missing file, config contradicting the assignment, API/tool behaving differently than told. DM `Main` (or your spawner) instead of guessing.
-- **Blocked by another agent** — a peer holds the file/branch/resource or decision you need, or started the change you're about to make. DM them (or broadcast to discover who) before duplicating work.
-- **Decision outside your scope** — a genuine fork the assignment didn't pre-decide. Ask the requester rather than picking unilaterally.
-- **Coordination** — a peer's in-flight work overlaps yours (the roster shows each peer's role and current activity); message before editing a shared file or duplicating a sibling's change.
+Reach for `irc` when going alone is wasteful or wrong; when in doubt, message.
+- **Unexpected state** — missing file, config contradicting the assignment, API/tool behaving differently than told. DM `Main` (or your spawner), don't guess.
+- **Blocked by another agent** — a peer holds the file/branch/resource/decision you need, or started your change. DM them (or broadcast to find who) before duplicating work.
+- **Decision outside your scope** — a genuine fork the assignment didn't pre-decide. Ask the requester, don't pick unilaterally.
+- **Coordination** — a peer's in-flight work overlaps yours (roster shows each peer's role + activity); message before editing a shared file or duplicating a sibling's change.
 
 NEVER for: routine progress updates, things a tool call can verify, questions your assignment/repo/docs already answer.
 </when_to_use>
 
 <etiquette>
-Applies to sending and replying.
+Applies to sending + replying.
 - **Plain prose only.** NEVER JSON status payloads like `{"type":"task_completed",…}` — write a normal sentence.
 - **NEVER quote the message you answer.** Lead with the answer; set `replyTo`.
 - **Learn about peers via IRC** — NEVER grep artifacts, read other sessions' JSONL, or shell-poke. DM them, or `read` `history://<id>`.
-- **Send, then keep working.** `wait`/`await: true` only when you genuinely cannot proceed. NEVER "did you get my message?". A `failed` receipt = peer unreachable — move on; NEVER retry in a loop.
-- **Answer expected questions** via `irc send` to the sender (finishing your current step first is fine).
+- **Send, then keep working.** `wait`/`await: true` only when you cannot proceed. NEVER "did you get my message?". A `failed` receipt = peer unreachable — move on; NEVER retry in a loop.
+- **Answer expected questions** via `irc send` to the sender (finish your current step first).
 - **Stay terse.** One question per send; share files via `local://`/`memory://`/`artifact://` URLs, never pasted blobs.
 - **Address peers by exact id** from `op: "list"` (e.g. `AuthLoader`, `Main`). NEVER invent friendly names.
 - **NEVER IRC what a tool answers.** A `read`, grep, or build resolves it? Do that first.
 </etiquette>
-
-<output>
-- `send`: per-recipient receipts; with `await: true`, also the reply (or timeout notice).
-- `wait`: the consumed message, or a clean timeout notice.
-- `inbox`: pending messages, oldest first.
-- `list`: peers with status, unread count, parent, last activity.
-</output>

package/src/prompts/tools/job.md

@@ -1,20 +1,17 @@
 Inspects, waits, or cancels async jobs.
 
-Background job results are delivered automatically when complete. Reach for this tool only when you need to intervene.
+Results arrive automatically on completion; reach for this tool only to intervene.
 
 # Operations
 
 ## `list: true`
-Use to inspect what's running.
+Inspect what's running.
 
 ## `poll: [id, …]`
-Block until the specified jobs finish or the wait window elapses. Omit `poll` (with no `list`/`cancel`) to wait on ALL running jobs — NEVER enumerate ids you don't need to filter.
-- Use when you are genuinely blocked on a result and have no other work to do.
-- Returns the current snapshot when the timer elapses; running jobs remain running.
-- Completed jobs include their final output in the returned snapshot.
-- With Max Poll Time set to `smart` (the default), the wait window adapts: it starts at ~5s and lengthens with each back-to-back poll (up to ~5m), then resets to ~5s after you go a while without polling. Spinning in a poll loop costs progressively more; do real work between polls.
+Block until specified jobs finish or the wait window elapses. Omit `poll` (no `list`/`cancel`) to wait on ALL running jobs — NEVER enumerate ids you don't need to filter.
+- Use only when genuinely blocked with no other work.
+- Completed jobs include final output.
 
 ## `cancel: [id, …]`
 Stop running jobs.
 - Use when a job is stalled, hung, or no longer needed.
-- Returns immediately after cancelling.

package/src/prompts/tools/learn.md

@@ -1,7 +1,7 @@
 Capture a reusable lesson into long-term memory, and optionally mint or enhance a managed skill in the same call.
 
-Use after solving something whose insight will pay off again: a non-obvious fix, a project convention you had to discover, a workflow that worked. The `memory` field is the durable, self-contained lesson — include what, when, and why so a future session understands it without this conversation.
+Use after solving something whose insight will pay off again: a non-obvious fix, a project convention you had to discover, a workflow that worked.
 
-Provide the optional `skill` object when the lesson is a repeatable *procedure* worth codifying as a `SKILL.md` (not just a fact). Managed skills are written to an isolated directory (`~/.omp/agent/managed-skills`) and are surfaced like normal skills next session. They NEVER touch user-authored skills. `body` is the SKILL.md content in markdown — do not include frontmatter; it is generated from `name` and `description`. Use `action: "update"` to enhance an existing managed skill.
+Provide the optional `skill` object when the lesson is a repeatable *procedure* worth codifying as a `SKILL.md` (not just a fact). Managed skills are written to an isolated directory (`~/.omp/agent/managed-skills`) and are surfaced like normal skills next session. They NEVER touch user-authored skills. Frontmatter is generated from `name` and `description`.
 
 Capture sparingly and specifically. One strong, reusable lesson beats several vague ones.

package/src/prompts/tools/lsp.md

@@ -1,42 +1,39 @@
-Interacts with Language Server Protocol servers for code intelligence.
+Language Server Protocol (LSP) servers for code intelligence.
 
 <operations>
-- `diagnostics`: Get errors/warnings for a file, a glob of files, or the entire workspace (`file: "*"`)
-- `definition`: Go to symbol definition → file path + position + 3-line source context
-- `type_definition`: Go to symbol type definition → file path + position + 3-line source context
-- `implementation`: Find concrete implementations → file path + position + 3-line source context
-- `references`: Find references → locations with 3-line source context (first 50), remaining location-only
-- `hover`: Get type info and documentation → type signature + docs
-- `symbols`: List symbols in a file, or search workspace with `file: "*"` and a `query`
-- `rename`: Rename symbol across codebase → preview or apply edits
-- `rename_file`: Rename or move a file/directory; sends `workspace/willRenameFiles` so LSP servers update import paths and other references → preview or apply edits + filesystem rename
-- `code_actions`: List available quick-fixes/refactors/import actions; apply one when `apply: true` and `query` matches title or index
-- `status`: Show active language servers
-- `capabilities`: Dump per-server capabilities (standard + experimental + executeCommand list) for discovery — file scopes to one server, omitted/`"*"` lists every active server
-- `request`: Send a raw LSP request to a server — `query` is the method name (e.g., `rust-analyzer/expandMacro`, `typescript/goToSourceDefinition`, `workspace/executeCommand`); use `payload` for arbitrary JSON params or let the tool auto-build them from `file`/`line`/`symbol`
-- `reload`: Restart a specific server (via `file`) or all servers with `file: "*"`
+- `diagnostics`: errors/warnings for a file, glob, or workspace (`file: "*"`)
+- `definition`: symbol definition
+- `type_definition`: symbol's type definition
+- `implementation`: concrete implementations
+- `references`: all references
+- `hover`: type info / docs
+- `symbols`: list file symbols, or search workspace with `file: "*"` + `query`
+- `rename`: rename symbol codebase-wide
+- `rename_file`: rename/move a file/directory; updates import paths + other references
+- `code_actions`: list quick-fixes/refactors/import actions; apply one when `apply: true` + `query` matches title or index
+- `status`: active language servers
+- `capabilities`: per-server capabilities
+- `request`: raw LSP request — `query` = method name (e.g. `rust-analyzer/expandMacro`, `workspace/executeCommand`); `payload` = JSON params
+- `reload`: restart one server (via `file`) or all (`file: "*"`)
 </operations>
 
 <parameters>
-- `file`: File path, glob pattern (e.g. `src/**/*.ts`), or `"*"` for workspace scope. Globs are expanded locally before dispatch. `"*"` routes `diagnostics`/`symbols`/`reload` to their workspace-wide form.
-- `line`: 1-indexed line number for position-based actions
-- `symbol`: Substring on the target line used to resolve column automatically. Append `#N` to pick the Nth occurrence on that line (1-indexed; default 1) — e.g. `foo#2` selects the second `foo`.
-- `query`: Symbol search query, code-action kind filter / selector (list/apply mode), or LSP method name when `action: request`
-- `new_name`: Required for `rename` (new symbol identifier) and `rename_file` (destination path)
-- `apply`: Apply edits for rename/rename_file/code_actions (default true for rename and rename_file; list mode for code_actions unless explicitly true)
-- `payload`: JSON-encoded params for `action: request`. Overrides the auto-built `{ textDocument, position }` shape when present.
-- `timeout`: Request timeout in seconds (clamped to 5-60, default 20)
+- `file`: path, glob (e.g. `src/**/*.ts`), or `"*"` for workspace scope
+- `line`: 1-indexed line for position-based actions
+- `symbol`: substring on the target line. Append `#N` for the Nth occurrence — e.g. `foo#2` = second `foo`.
+- `query`: symbol search, code-action kind filter/selector (list/apply mode), or LSP method name when `action: request`
+- `new_name`: required for `rename` (new identifier) and `rename_file` (destination path)
+- `apply`: apply edits for rename/rename_file/code_actions (default true for rename/rename_file; code_actions list mode unless true)
+- `payload`: JSON params for `action: request`
+- `timeout`: seconds
 </parameters>
 
 <caution>
-- Requires running LSP server for target language
-- Some operations require file to be saved to disk
-- Glob expansion samples up to 20 files per request; use `file: "*"` for broader coverage
-- When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `#N` occurrence selectors return an explicit error instead of silently falling back
+- Missing `symbol` or out-of-bounds `#N` → explicit error.
 </caution>
 
 <critical>
-- You MUST use `lsp` for symbol-aware operations (rename, find references, go to definition/implementation, code actions) whenever a language server is available — it is safer and more accurate than text-based alternatives.
-- You NEVER perform cross-file renames with `ast_edit`, `sed`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and usages in other files.
-- You SHOULD use `lsp` `code_actions` for imports, quick-fixes, and refactors the language server already knows how to apply.
+- You MUST use `lsp` for symbol-aware operations (rename, references, definition/implementation, code actions) whenever a language server is available — safer and more accurate than text-based alternatives.
+- You NEVER perform cross-file renames with `ast_edit`, `sed`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and cross-file usages.
+- You SHOULD use `lsp` `code_actions` for imports, quick-fixes, and refactors the server already applies.
 </critical>

package/src/prompts/tools/manage-skill.md

@@ -2,8 +2,8 @@ Create, update, or delete a managed skill — a `SKILL.md` written to an isolate
 
 Managed skills are for repeatable procedures worth codifying: a setup sequence, a debugging recipe, a project-specific workflow. They are kept separate from user-authored skills and this tool NEVER edits those.
 
-- `action: "create"` — requires `name`, `description`, and `body`. Fails if the skill already exists.
-- `action: "update"` — requires `name`, `description`, and `body`. Fails if the skill does not exist. Overwrites the body.
-- `action: "delete"` — requires `name`. Fails if the skill does not exist.
+- `action: "create"` — fails if the skill already exists.
+- `action: "update"` — overwrites the body; fails if the skill does not exist.
+- `action: "delete"` — fails if the skill does not exist.
 
-`name` is kebab-case (lowercase letters, digits, hyphens). `description` is a single line stating when to use the skill — it drives discovery, so make it specific. `body` is the SKILL.md content in markdown; do not include frontmatter (it is generated from `name` and `description`).
+`name` is kebab-case (lowercase letters, digits, hyphens). The `description` drives discovery, so make it specific. Do not include frontmatter in `body`; it is generated from `name` and `description`.

package/src/prompts/tools/read.md

@@ -1,50 +1,48 @@
-Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single `path` string.
+Read files, directories, archives, SQLite, images, documents, internal resources, and web URLs via one `path`.
 
 <instruction>
-- You SHOULD parallelize independent reads when exploring related files.
-- You SHOULD reach for `read` — not a browser/puppeteer tool — for web content; browser only when `read` cannot deliver it.
+- SHOULD parallelize independent reads.
+- SHOULD use `read` (not a browser tool) for web content; browser only when `read` can't deliver.
 </instruction>
 
 ## Parameters
 
-- `path` — required. Local path, internal URI (`skill://`, `agent://`, `artifact://`, `history://`, `memory://`, `rule://`, `local://`, `vault://`, `mcp://`, `omp://`, `issue://`, `pr://`), or URL. Append `:<sel>` for line ranges or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
+- `path` — required. Local path, internal URI (`skill://`, `agent://`, `artifact://`, `history://`, `memory://`, `rule://`, `local://`, `vault://`, `mcp://`, `omp://`, `issue://`, `pr://`), or URL. Append `:<sel>` for ranges/modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
 
 ## Selectors
 
-Append `:<sel>` to `path`; bare path = default mode.
-
 - _(none)_ — parseable code → structural summary; other files → from start (up to {{DEFAULT_LIMIT}} lines).
 - `:50` / `:50-` — from line 50 onward.
 - `:50-200` — lines 50–200 inclusive.
-- `:50+150` — 150 lines starting at 50.
-- `:20+1` — anchor line 20 (single-range reads pad ≤1 leading / ≤3 trailing context lines).
-- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged); exact bounds, no padding.
-- `:raw` — verbatim; no anchors, no summary, no line prefixes.
-- `:2-4:raw` / `:raw:2-4` — range AND verbatim; compose in either order.
+- `:50+150` — 150 lines from 50.
+- `:20+1` — anchor line 20.
+- `:5-16,960-973` — multiple ranges in one call.
+- `:raw` — verbatim; no anchors/summary/line prefixes.
+- `:2-4:raw` / `:raw:2-4` — range AND verbatim; either order.
 - `:conflicts` — one line per unresolved git merge conflict block.
 
 # Files
 
-- Directory path → depth-limited dirent listing.
+- Directory → depth-limited dirent listing.
 {{#if IS_HL_MODE}}
-- File with explicit selector → snapshot tag header + numbered lines: `[src/foo.ts#1A2B]` then `41:def alpha():`. Copy the `[PATH#TAG]` header for anchored edits; ops use bare line numbers. NEVER fabricate the tag.
+- File + selector → snapshot tag header + numbered lines: `[src/foo.ts#1A2B]` then `41:def alpha():`. Copy `[PATH#TAG]` for anchored edits; ops use bare line numbers. NEVER fabricate the tag.
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
-- File with explicit selector → lines prefixed with numbers: `41|def alpha():`.
+- File + selector → numbered lines: `41|def alpha():`.
 {{/if}}
 {{/if}}
-- Parseable code without selector → **structural summary**: declarations kept, body elided with `…`. The footer shows the recovery selector. Re-issue ONLY the ranges you need via the multi-range selector.
+- Parseable code, no selector → **structural summary**: declarations kept, body elided with `…`. Footer names the recovery selector; re-issue ONLY the ranges you need.
 
 # Documents & Notebooks
 
-PDF, Word, PowerPoint, Excel, RTF, EPUB → extracted text. Notebooks (`.ipynb`) → editable `# %% [type] cell:N` text; edits round-trip to the underlying JSON preserving metadata. `:raw` bypasses the converter.
+PDF, Word, PowerPoint, Excel, RTF, EPUB → extracted text. Notebooks (`.ipynb`) → editable `# %% [type] cell:N` text. `:raw` bypasses the converter.
 
 # Images
 
 {{#if INSPECT_IMAGE_ENABLED}}
-Image path → metadata (mime, bytes, dimensions, channels, alpha). For visual analysis, call `inspect_image` with the path and a question.
+Image → metadata. Visual analysis: call `inspect_image` with the path and a question.
 {{else}}
-Image path → decoded image inline (PNG, JPEG, GIF, WEBP) for direct visual analysis.
+Image → decoded inline (PNG, JPEG, GIF, WEBP) for direct visual analysis.
 {{/if}}
 
 # Archives
@@ -63,16 +61,16 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 
 # URLs
 
-- Reader-mode by default: HTML, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.
-- `:raw` → untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetch.
-- Bare `host:port` collides with the selector grammar — add a trailing slash: `https://example.com/:80`.
+- Reader-mode default: HTML, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.
+- `:raw` → untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the fetch.
+- Bare `host:port` collides with selector grammar — add a trailing slash: `https://example.com/:80`.
 
 # Internal URIs
 
-All `path` URI schemes resolve transparently and take the same line selectors. `artifact://<id>` recovers full output a previous bash/eval/tool result spilled or truncated. `history://<agentId>` is an agent's transcript as concise markdown; bare `history://` lists agents.
+All URI schemes take the same line selectors. `artifact://<id>` recovers full output a bash/eval/tool result spilled or truncated. `history://<agentId>` = agent transcript; bare `history://` lists agents.
 
 <critical>
-- You MUST use `read` for every file, directory, archive, and URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN bash calls, however short or convenient.
+- MUST use `read` for every file/directory/archive/URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN bash calls, however convenient.
 - Line ranges go in the selector (`path="src/foo.ts:50-200"`) — NEVER `sed -n`, `awk NR`, or `head`/`tail` pipelines.
 - Summary footer names elided ranges? Re-issue ONLY those ranges. NEVER guess `..`/`…` content.
 </critical>

package/src/prompts/tools/replace.md

@@ -1,7 +1,6 @@
 Performs string replacements in files with fuzzy whitespace matching.
 
 <instruction>
-- Params MUST be `{ path, edits }`; `path` is required at the top level and applies to every replacement
 - You MUST use the smallest `old_text` that uniquely identifies the change
 - If `old_text` is not unique, you MUST expand it with more context or use `all: true` to replace all occurrences
 - You SHOULD prefer editing existing files over creating new ones

package/src/prompts/tools/resolve.md

@@ -1,9 +1,4 @@
-Resolves a pending action by either applying or discarding it.
-- `action` is required:
-  - `"apply"` persists / submits the pending action.
-  - `"discard"` rejects the pending action.
-- `reason` is required: one short complete sentence explaining why, starting with a capital letter and ending with a period.
-- `extra` (optional) is free-form metadata passed to the resolving tool. When the pending action is a plan-approval gate, supply `extra.title` (kebab/PascalCase slug for the approved plan filename). For preview-style pending actions (e.g. `ast_edit`), `extra` is unused.
-
-Valid whenever a pending action exists — either a preview-style staging (e.g. `ast_edit`) or a long-lived approval gate.
-Call fails with an error when no pending action exists.
+Resolves a pending action — apply or discard. Valid only when a pending action exists; errors otherwise.
+- `action` (required): `"apply"` persists/submits; `"discard"` rejects.
+- `reason` (required): one short sentence explaining why.
+- `extra` (optional): free-form metadata. Plan-approval gate? Supply `extra.title` (kebab/PascalCase slug = approved plan filename). Unused for preview actions (e.g. `ast_edit`).

package/src/prompts/tools/rewind.md

@@ -3,7 +3,7 @@ End an active checkpoint. Rewind context to it, replacing intermediate explorati
 Call immediately after `checkpoint`-started investigative work.
 
 Requirements:
-- `report` is REQUIRED and MUST be concise, factual, and actionable.
+- `report` MUST be concise, factual, and actionable.
 - Include key findings, decisions, and any unresolved risks.
 - AVOID raw scratch logs unless essential.
 - You MUST call this before yielding if a checkpoint is active.