my-pi/config/prompt/routing.jsonc

{
  // Cross-tool workflow rules rendered by extensions/system-prompt.ts into the
  // <tool_routing> section. A rule is included when every tool in "whenAll"
  // and at least one tool in "whenAny" is active; a rule with neither is
  // always included. Rules render in file order as "- <text>".
  // Optional "scope": "main" | "subagent" restricts a rule to that session
  // audience (main session vs pi-subagents child); absent means both.
  "version": 1,
  "rules": [
    {
      "whenAny": ["codegraph_explore"],
      "text": "Use codegraph_explore first for architecture, symbol relationships, code flows, and symbols you are about to change. Treat the source it returns as already read for understanding; do not repeat the same exploration with read or search unless information is missing. Before editing, still read the exact target range to get fresh LINE#HASH anchors."
    },
    {
      "whenAny": ["lsp_definition", "lsp_references", "lsp_hover", "lsp_symbols", "lsp_diagnostics"],
      "text": "Use LSP for symbol definitions, references, hover/type information, and post-edit diagnostics when the language server supports the file."
    },
    {
      "whenAny": ["find", "grep"],
      "text": "Pick the local search tool by what you already know:\n  - Exact identifier or text: grep with a literal pattern, constrained by path/exclude. Do not run find first just to locate it.\n  - Several identifiers or naming variants: one grep with a regex alternation (e.g. user_id|userId|UserId) instead of several greps.\n  - A filename, path fragment, or feature concept: find (fuzzy whole-path match; use a glob in path for exact names).\n  - Then read only the matching region with offset/limit."
    },
    {
      "whenAny": ["find", "grep"],
      "text": "Do not run a broad search expected to return hundreds or thousands of files or matches. If results truncate or hit a limit, narrow the path, glob, or pattern instead of increasing the limit or dumping all results."
    },
    {
      "whenAll": ["codemode"],
      "whenAny": ["find", "grep"],
      "text": "To extract, deduplicate, count, or aggregate across search matches (what grep -o | sort -u | wc would do), call tools.grep / tools.find inside one codemode script and post-process the results in JavaScript."
    },
    {
      "whenAny": ["bash"],
      "text": "Use bash for builds, tests, git, package scripts, and other programs. Never run grep, rg, find, fd, or git grep in bash — standalone, piped, inside a loop, or in $(…). Search files with the grep/find tools; when a program needs a file list (wc, node, tsc), pass $(git ls-files '<glob>')."
    },
    {
      "whenAll": ["bash", "overflow_query"],
      "text": "To filter a command's output, run it without | grep; if the result carries a [pi-overflow id=…] marker, search it with overflow_query instead of re-running."
    },
    {
      "whenAny": ["ssh_connect"],
      "scope": "main",
      "text": "Use ssh_connect only when the user explicitly names an imported host as part of a concrete remote task. Call it as a separate step and wait for success before calling other ssh_* tools; never infer or substitute a different host."
    },
    {
      "whenAny": ["ssh_connect"],
      "scope": "subagent",
      "text": "Use ssh_connect only when the delegated task explicitly names an imported host as part of a concrete remote task. Call it as a separate step and wait for success before calling other ssh_* tools; never infer or substitute a different host."
    },
    {
      "whenAny": ["ssh_cd"],
      "text": "Treat ssh_cd as a reviewed persistent workspace transition: call it as a separate step and wait for success before issuing ssh_bash or relative ssh_read/ssh_write/ssh_edit/ssh_find/ssh_grep calls that depend on the new remote cwd. Use cd inside ssh_bash only for an intentionally temporary, command-local directory change."
    },
    {
      "whenAny": ["ssh_find", "ssh_grep"],
      "text": "For remote SSH searches, use ssh_find to narrow remote file paths before ssh_grep searches file contents. Keep path and limit bounded; when a result says truncated, narrow the path or pattern instead of increasing the limit. Do not run find, fd, grep, or rg through ssh_bash."
    },
    {
      "whenAny": ["web_search", "web_fetch"],
      "text": "Use web_search for current, real-world, or citable web information; provider selection is handled internally. Keep queries focused and use site/published_* filters only when they materially narrow results. Read selected pages with web_fetch instead of repeating similar searches."
    },
    {
      "whenAll": ["chrome_snapshot", "overflow_query"],
      "text": "chrome_snapshot (and Chrome actions with includeSnapshot=true) return the page snapshot JSON directly. When it is large the result carries a [pi-overflow id=…] marker: extract only the uids, text, or state you need with overflow_query (jsonPath or search) instead of taking another snapshot, and take a fresh snapshot after any page interaction because the previous one is stale."
    },
    {
      "whenAny": ["overflow_query"],
      "text": "When a tool result starts with or ends with a [pi-overflow id=…] marker, the full original output is stored; inspect it with overflow_query (search, line ranges, or jsonPath) instead of re-running the command or dumping it again."
    },
    {
      "whenAny": ["read"],
      "text": "Use read only when exact source is needed or the file is small. Before editing, request the smallest useful offset/limit range; do not read a complete large source file merely to copy, compare, hash, count, or explore it. Reading project overview docs such as a README in full is fine."
    },
    {
      "whenAll": ["read", "edit"],
      "text": "For existing-file changes, obtain fresh LINE#HASH anchors with a small read (find/grep output has no anchors), then use anchored edit operations. Reuse fresh anchors returned by successful edits for chained changes; re-read only when anchors are stale or the next target region was not shown."
    },
    {
      "text": "When a tool call is denied by policy, use the alternative named in the denial and continue the subtask; do not drop it or present unverified facts as checked."
    },
    {
      "text": "Stop searching once the current evidence is sufficient. Avoid repeating the same lookup through CodeGraph, find, grep, and read without a concrete information gap."
    }
  ]
}