rp

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

From w-winter/dot314, MIT.

More from w-winter/dot314