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", "multi_grep"],
      "text": "For literal search, narrow in stages instead of requesting a repository-wide dump:\n  1. Use find to identify likely files or directories. Constrain path/glob and keep the result limit small.\n  2. Use grep or multi_grep only inside the narrowed path or file to obtain matching line numbers. Start with a specific or literal pattern, a small context window, and a bounded limit.\n  3. Use read with offset/limit only for the exact matching region when full source is still needed."
    },
    {
      "whenAny": ["find", "grep", "multi_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."
    },
    {
      "whenAny": ["bash"],
      "text": "Use bash for builds, tests, git, package scripts, and other programs. Never search files by running grep, find, rg, or fd through bash; use the find/grep tools."
    },
    {
      "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": ["web_fetch", "ctx_fetch_and_index"],
      "text": "Read a web page with web_fetch. Use ctx_fetch_and_index only when the content should be indexed into the context-mode knowledge base for repeated ctx_search queries."
    },
    {
      "whenAny": ["ctx_execute", "ctx_execute_file", "ctx_batch_execute"],
      "text": "Use Context Mode for logs, test/build output, generated data, large-file exploration/analysis/summarization, and any command whose output may be large or unpredictable. Prefer one ctx_batch_execute over several ctx_execute calls for multi-command research, and print only the derived answer needed for the task."
    },
    {
      "whenAny": ["ctx_execute_file"],
      "text": "ctx_execute_file analyzes a file and never edits it; make changes with read + edit. It is confined to the current project root: do not call it for absolute paths outside the workspace, ../ traversal, or symlinks that resolve outside the workspace; host permission approval does not bypass this boundary. Use another explicitly authorized tool for those files."
    },
    {
      "whenAll": ["chrome_snapshot", "ctx_execute_file"],
      "text": "After chrome_snapshot or a Chrome action with includeSnapshot=true, immediately analyze the returned workspace-relative capture path with ctx_execute_file; never use read or cat for the raw JSON. Print only the uids, text, or state needed for the next action, and take a fresh snapshot after any interaction because the previous capture may be 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 file merely to copy, compare, hash, count, explore, or summarize it."
    },
    {
      "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": "Stop searching once the current evidence is sufficient. Avoid repeating the same lookup through CodeGraph, find, grep, and read without a concrete information gap."
    }
  ]
}