cross-repo-request

# Cross-repo requests ## The failure this prevents A frontend agent needs an endpoint that does not exist yet. Left alone it stubs the response, invents a payload shape, and writes code against a contract the backend never agreed to. The stub survives into review and the shapes do not match. The same happens in reverse when a backend agent guesses at how a client consumes a field. If another repo owns the change, ask the session that owns that repo. Do not guess the contract, and do not stub it silently. ## Finding the peer `ListAgents` lists the Claude sessions running on this machine. Each row leads with the name that addresses it. If the repo you need has no session listed, stop and tell the user to open one there, then continue. Do not start implementing against an assumed contract while you wait. ## The request `SendMessage` to the peer. The first line is all its user sees until they expand it, so the first line must state the ask on its own. Include all seven, every time: 1. Repo or service path, and branch 2. HTTP method and full route path (or the function/module for non-HTTP work) 3. Request payload shape, with types, and which fields are required 4. Expected success response shape and status code 5. Auth and tenant context expected (header, role, scope) 6. Error cases you need to distinguish, as status plus code 7. What you actually want back: the contract confirmed, a mock, or the real implementation Compact form when the change is small: > In `api/`, add `POST /api/routes/:id/shifts` taking `{status: "active"|"inactive", note?: string}`, > returning `201 {id, status, note}`, auth bearer plus org scope, `409` on > duplicate. I need it real, not mocked. Caller is > `app/(app)/routes/_routes/columns/route-shifts-columns.tsx`. Name the calling file. The peer can then read your side rather than asking what consumes it. ## While you wait Pass `notify_when_idle: true` on the send so you get one notice when that session finishes. Never poll `ListAgents` in a loop, and never send "are you done?". Do the parts of your task that do not depend on the answer. Leave the dependent part unwritten rather than stubbed. If you must place a stub to keep the file compiling, mark it with a comment naming the peer request it is waiting on, so it cannot be mistaken for finished work. ## The reply The peer's first line is `DONE`, `PROPOSAL`, or `BLOCKED`. `DONE`: read every file under its `files:` line before building on it. The summary is a claim; the code is the contract. Check its `deviations:` line. If it changed anything from what you asked, tell your user before adapting, even if the change looks reasonable. Then run its `verify:` line or call the endpoint from this side. If that fails, send the actual error back to the peer once. If it fails again, stop and hand it to your user with both errors. `PROPOSAL`: the peer wants a different contract. Relay it to your user with the peer's reasoning and let them decide. Never accept or reject a contract change on the user's behalf, and never start building against the proposal until the user has said yes and you have sent that yes to the peer. `BLOCKED`: tell your user what the peer said and stop the dependent part. ## Boundaries Permissions are per session. Never ask a peer to run something your own permission settings blocked or would block. If you were denied an action, route it back to your user, not sideways to another session.