---
name: rp
description: Always read this skill when the user mentions "rp" or "repoprompt", or before accessing a repository outside the current RepoPrompt workspace. Covers workspace discovery, binding, root verification, and workspace hygiene.
---

# RP

## Use RepoPrompt (`rp`) for Within-Repository Discovery

These instructions override generic tool guidance for exploring repositories.

`rp` is the default for repo-scoped work. Usage:
- **Bind**: `rp({ windows: true })` → `rp({ bind: { window: N } })`
- **Call tools**: `rp({ call: "<tool>", args: { ... } })`

### Mental Model

RepoPrompt (macOS app) organizes state as:
- **Workspaces** → one or more root folders
- **Windows** → each shows one workspace
- **Tabs** → each tab has its own prompt + file selection; selections, slices, and codemaps are tab-scoped
- **Oracle chats** → planning/review conversations live in the current tab/context

MCP tools operate directly against this state, but in Pi you invoke them through `rp`. Bind to the correct window with `rp({ bind: { window: N } })`, then call tools via `rp({ call: "<tool>", args: { ... } })`.

**Mandatory routing check:** Do not infer availability of any repo of interest from workspace/window titles; workspaces may have more roots available than the title implies. Before any repo-scoped work, confirm the target repo/root is (or isn't) present by checking workspace roots (e.g. `get_file_tree`). If it's not confirmed, pause and resolve routing (bind the right window/tab or open the repo).

### Parallel RepoPrompt calls

After RepoPrompt routing, binding, and target-root confirmation are complete, inspect the ready set before every repository exploration call.

- If two or more RepoPrompt operations are independent and read-only with respect to both files and RepoPrompt session state, issue them as separate rp calls in the same tool-call block so they run together.
- Do not issue consecutive model turns containing one independent `rp` read/search call each.
- Typical parallel candidates include `read_file`, `file_search`, `get_file_tree`, `get_code_structure`, and independent read-only `git` queries.
- Do not parallelize routing or binding changes, selection mutations, workspace or tab lifecycle operations, edits, file actions, approvals, or calls whose inputs depend on another result.
- Complete routing or state mutations before launching reads that depend on the resulting state.

### Workspace Hygiene (Session Start Priority)

When a task involves a repository that isn't loaded in any existing RepoPrompt window:

1. **Do NOT** use `manage_workspaces action="add_folder"` to add unrelated repositories to an existing workspace
2. **Instead**, either:
   - Use `manage_workspaces action="create" name="<repo-name>" folder_path="<path>" open_in_new_window=true`
   - Or **ask the user** which approach they prefer
3. Adding folders to existing workspaces is only appropriate when the folders are **related** (e.g., adding a shared library to a project that uses it)

Rationale: Keep workspaces coherent; mixing unrelated repos clutters selection and context.

### Constraints

Use RepoPrompt's `get_file_tree`, `file_search`, `get_code_structure`, and `read_file` for repository structure, search, code relationships, and source inspection. Do not substitute shell or Pi-native filesystem tools unless `rp` is unavailable after one retry.

Never switch workspaces in an existing window unless the user explicitly says it's safe. Switching clobbers selection, prompt, and context. Use `open_in_new_window=true`.

Keep context intentional: select only what you need, prefer codemaps for reference files, use slices when only a portion matters.

### Tool Selection by Task

| Task | MCP Tool | Notes |
|------|----------|-------|
| Repo structure | `get_file_tree type="files" [mode="folders"] [path="..."] [max_depth=N]` | gitignore-aware |
| Code search | `file_search pattern="..." [path="..."] [mode="both\|path\|content"] [filter={...}] [context_lines=N]` | regex auto-detected by default |
| API signatures | `get_code_structure [paths=["dir/"]] [expand="uses\|used_by\|both"] [depth=N] [signatures=true] [size="small\|medium\|large"]` | omit `paths` to inspect the current selection |
| Context curation | `manage_selection op="get\|set\|add\|remove\|clear" [view="summary\|files\|content\|codemaps"]` | selection drives oracle/review context |
| Snapshot/export | `workspace_context [include=["prompt","selection","code","tree","tokens"]]` or `workspace_context op="export"` | verify or export current context |
| Reading files | `read_file path="..." [start_line=N] [limit=N]` | 120-200 line chunks |
| Code editing | `apply_edits path="..." search="..." replace="..." [all=true] [verbose=true]` | supports multi-edit, rewrite |
| File ops | `file_actions action="create\|move\|delete" path="..."` | absolute path for delete |
| Planning/review | `oracle_send mode="chat\|plan\|review" [new_chat=true] [chat_id="..."] [export_response=true]` | uses the current tab/context; exporting returns `oracle_export_path` |
| Oracle helpers | `oracle_utils op="models\|sessions" [limit=N] [context_id="..."] [scope="workspace\|tab"]` | list models or existing Oracle conversations; `sessions` defaults to the current workspace and can filter to a specific context |
| Sticky routing | `bind_context op="status\|bind\|list" [context_id="..."] [working_dirs="/abs/root[,/abs/root2]"]` | use `list` to discover windows and `context_id`s; prefer `bind context_id="..."` to pin a tab, or use `working_dirs` when you want RepoPrompt to route to a workspace by roots (exact match first, repo_paths superset fallback) |
| Window routing bootstrap | `rp({ windows: true })` then `rp({ bind: { window: N } })` | only for initial window selection before using `bind_context` |
| Workspace inventory/tab lifecycle | `manage_workspaces action="list\|switch\|create\|delete\|add_folder\|remove_folder\|create_tab\|close_tab"` | inventory + lifecycle only; use `bind_context` for routing/context discovery |
| Agent runs | `agent_run op="start\|poll\|wait\|cancel\|steer\|respond"` | advanced, session-based Agent Mode control; `poll`/`wait` accept `session_id` or `session_ids` |
| Agent/session management | `agent_manage op="list_agents\|list_sessions\|extract_handoff\|create_session\|resume_session\|stop_session\|cleanup_sessions\|list_workflows"` | inspect durable session/workflow state and export agent handoff transcript; `list_sessions` uses MCP-facing states and `list_workflows` includes `orchestrate` |
| Auto context | `context_builder instructions="..." [response_type="clarify\|question\|plan\|review"]` | token-costly, invoke explicitly |
| Git operations | `git op="status\|diff\|log\|show\|blame" [compare="..."] [detail="..."]` | worktree support via `main`/`trunk` aliases and merge-base comparisons, `@main:<branch>` |

### Paths and roots

Path syntax is tool-specific. Use absolute paths when a tool accepts them. For `read_file` and `apply_edits`, reuse the exact path returned by `read_file` unchanged; in a multi-root workspace, its explicit form may be `root@<UUID>//rel/path`. For `manage_selection`, prefix a relative path with the loaded root name when needed (for example, `ProjectA/src/main.swift`).

Notes:
- `file_search path="..."` is an alias for `file_search filter.paths=["..."]`
- `file_search filter.paths` accepts absolute or relative paths/folders, loaded root names, and root-name-prefixed paths (for example, `ProjectA/src`). It does not accept `root@<UUID>//...` aliases returned by `read_file`.
- `file_actions` requires absolute `path` and `new_path` values
- `get_code_structure` reads RepoPrompt's committed code graph; use `read_file` when you need the latest file contents

### Routing

If results look wrong, assume routing first-not tool failure.

1. `rp({ windows: true })` - list available windows
2. If `rp` is already bound and the needed roots are present, keep it
3. Otherwise `rp({ bind: { window: N } })` - bind to the right window
4. `bind_context op="list"` - inspect windows, active workspaces, tabs, `context_id`s, and current bindings when routing is ambiguous
5. Prefer `bind_context op="bind" context_id="..."` - pin the specific compose tab you want after choosing it from `list`
6. Use `bind_context op="bind" working_dirs="/abs/root"` when you want RepoPrompt to route to a workspace by roots without pinning a tab
7. `get_file_tree` - confirm workspace roots

Notes:
- `bind_context op="bind" working_dirs="/abs/root[,/abs/root2]"` matches workspace roots, not descendant paths
- Matching prefers an exact workspace `repo_paths` set; if none exists, RepoPrompt may fall back to a workspace whose roots are a strict superset
- `manage_workspaces action="list"` is workspace inventory; `bind_context op="list"` is the global window/tab routing view

RepoPrompt only operates within workspace root folders.

### Agent Mode

`agent_run` + `agent_manage` are RepoPrompt's external control plane for Agent Mode: use them when you need to drive a long-running per-tab subagent session, not just make one-off MCP file/chat calls.

- Use `agent_run` for run lifecycle: `start`, `wait`/`poll`, `respond`, `steer`, `cancel`
- Use `agent_manage` for durable metadata: discover agents/workflows, list sessions, and export handoff transcript
- Use `agent_manage op="extract_handoff"` to pull into your context a handoff transcript of the subagent's context. It exports a `<forked_session ...>` payload; set `output_path` to write a file, or omit it for inline XML.
- Session state uses MCP-facing values such as `running`, `waiting_for_input`, `completed`, and `failed`; `waiting_for_input` means reply with `agent_run op="respond"`
- `agent_manage op="list_workflows"` includes `orchestrate` for planning, decomposition, and sub-agent dispatch
- `agent_run op="wait"` / `op="poll"` accept either `session_id` or `session_ids`; multi-wait wakes on the first interesting session
- If you start sub-agents, do not end your turn while any started session is still unattended; always `wait`/`poll` and handle pending input first
- MCP-started `orchestrate` runs may spawn sub-agents, but nested sub-agents cannot recursively start more agent runs

### Asynchronous Context Builder and Oracle

Through `rp`, `context_builder` and generic `oracle_send` are asynchronous: the start call returns a `job_id`; call the matching `context_builder_wait` or `oracle_send_wait`, and if it returns `running`, repeat that same wait as the next action. Waits observe the original request and never resubmit it; `/rp oracle` remains synchronous.

`context_builder instructions="..." [response_type="clarify|question|plan|review"]`

Context Builder explores the codebase and curates file selection automatically.

- `response_type="clarify"` (default): Returns context for handoff or manual refinement
- `response_type="question"`: Answers using built context
- `response_type="plan"`: Generates an implementation plan
- `response_type="review"`: Generates a code review with git diff context

For question, plan, and review responses, use the `chat_id` from the terminal wait result with `oracle_send new_chat=false chat_id="..."` for follow-up.

For a shareable handoff artifact, set `export_response=true`; the terminal wait result includes `oracle_export_path`.

These operations are token-costly; invoke them explicitly when the user requests them or during planning phases, not automatically.

### Edit Discipline

- Re-read the target region of a file before editing if: (a) the last read was >2 turns ago, (b) you edited the same file since last reading it, or (c) you switched RP windows since last reading it
- After an `apply_edits` failure, always re-read before retrying - never guess at what changed
- When making multiple edits to the same file, apply them one at a time (each edit shifts content for subsequent ones)
- Confirm you are bound to the correct RP window before any `apply_edits` - relative paths resolve against the bound workspace

### Start Here

When the task involves a repository, use `rp` as your toolkit for exploration, reading, editing, and file operations.

1. `rp({ windows: true })`
2. If already bound and roots are correct, keep it; otherwise `rp({ bind: { window: N } })`
3. When routing matters across repeated tool calls, use `rp({ call: "bind_context", args: { op: "list" } })`, then `rp({ call: "bind_context", args: { op: "bind", context_id: "..." } })`
4. Then use `get_file_tree`, `file_search`, `read_file`, etc.

Use Pi-native `ls/find/grep/read/edit/write` only when `rp` is unavailable after one retry.

Unexpected output is usually a routing issue-wrong workspace, wrong window, wrong tab-not a tool failure. Check routing before falling back.

### Repository startup contract

- For repo-scoped work, default to RepoPrompt via `rp`, not native repo-file tools or bash
- If the user refers to the current cwd/project, verify it first with `pwd`
- If the user names a repo path, treat that path as the repo of interest and resolve RepoPrompt routing before using native tools
- Before repo-scoped work, inspect windows and roots, then bind the correct window/tab, then confirm the target root
- Do not bind a random window just because it is available
- Do not guess RepoPrompt tool interfaces; use `rp({ describe: "tool_name" })` when exact parameters matter

### Text-file changes

Never use the terminal to modify text files. Always use `rp`'s `apply_edits` (or Pi's edit if `rp` unavailable). Modifying files via terminal is only acceptable if `rp` is not available *and* you need to do large-scale find/replace operations or similar on files. In such cases, explicitly get the user's permission before using it.