paseo-cross-project git:20261020.43b8a0cA

Immutable. This exact content never changes and is served at /api/v1/blob/5d3558e5920bddef.

---
name: paseo-cross-project
description: When work in one project needs another project to help (e.g. order-service has to wire up an API with payment-service, integrate, and deploy each side), start a dedicated Paseo session in the other project, agree on a contract, split the work, integrate, and deploy by each project's own rules. Use when the user says "have project X help", "wire the two up", "integrate", "cross-project", or when a session from another project asks you to help.
---

# Cross-project collaboration (paseo-cross-project)

A session working on project A needs project B to change code: the A session (the initiator) starts a helper session in project B, each side changes only its own repository, and they coordinate through Paseo messages. The initiator answers to the user and reports for both sides.

- Both projects on **the same machine**: use the local Paseo MCP tools (below). Since Paseo 0.12.0 the recipient sees the sender's session name, messages steer into its current turn instead of interrupting, and a child session notifies the initiator when it finishes.
- The other project lives only on **another machine**: start sessions and send messages with skill `paseo-peer` (`paseo-peer <machine> run/tell`); everything else in this skill still applies.
- **Sender line**: every cross-project or cross-machine message starts with who sent it (project + session name + id), generated by `paseo-peer whoami` (the script is `scripts/paseo-peer` in skill `paseo-peer`'s directory).
  - Same machine: send both the first message (`create_agent`'s `initialPrompt`) and follow-ups (`send_agent_prompt`) with the MCP tools, with `[Cross-project message] From ` + the `whoami` output as the first line. Use MCP rather than `tell` to keep finish notifications.
  - Cross-machine: always `paseo-peer <machine> tell <id> "…"` (`--file` for long messages); the script adds the sender line and the reply command.
  - Child sessions within the same project don't need it.

## 1. Start the helper session

0. First give your own session a short task name (e.g. "payment API integration"): it is the sender name on every message the other side receives, and the default title is the user's first sentence — long and truncated. `paseo agent update "$PASEO_AGENT_ID" --name "…"`. **No project prefix** on session or workspace names (the sidebar already groups by project, so it would repeat); the other side can't see which project you're in, so say it in the first message. The session name is not the workspace name in the sidebar: to change that too, call `rename_workspace` (find your workspace id via `list_workspaces` by cwd).
1. `list_workspaces` to see the other project's workspaces (by `cwd`). Workspaces are per task — **don't put the helper into a workspace someone else is using**; use one the user names, otherwise create one:
   - `create_workspace`: `isolation: "local"`, `path` = the other project's directory (e.g. `~/projects/payment-service`), `title` = the task, e.g. "help order-service: refund API".
2. `create_agent`: `workspaceId` from the previous step, `title` = the task (e.g. "help order-service integrate"); fill `provider` and `settings` from a suitable agent profile if there is one (`list_profiles` and read the notes), otherwise pick by task difficulty; set `labels` `collab.by` and `collab.from` (copy the values from `paseo-peer whoami --labels`, e.g. `{"collab.by": "office:1a2b3c4", "collab.from": "order-service"}`) so `paseo-peer <machine> mine` finds every helper you started; write `initialPrompt` as in section 2. Keep `notifyOnFinish: true`. Cross-machine: `paseo-peer <machine> run … $(paseo-peer whoami --labels)`.
3. Before starting, check whether a session is `running` in the other project's directory: `local` workspaces share one working tree, so when two sessions edit the same repository, each stages only its own files — no `git add -A`, no branch switching. If changes overlap, the two sessions message each other to coordinate (who commits first, the other merges after); go to the user only if they can't sort it out.

## 2. The first message (contract first)

The helper is brand new and knows only what you tell it. The first message must cover:

- **Kind of task**: investigate only / change code / change code and deploy — state one. For investigate-only, say "do not modify files, do not commit".
- **Background and goal**: the initiator's project, what to wire up, and why.
- **Relevant files**: known key locations on both sides (path + line + the key code pasted verbatim), so the helper doesn't search from scratch.
- **What's known**: what was tried, what was ruled out, existing constraints and decisions already made, so the helper doesn't redo them.
- **Contract (fixed by the initiator; the helper implements it as given)**: endpoint path/method, request and response field names, types, null/omitted semantics, enum values, error codes, auth. If the contract can't be settled yet, get the provider side working first and have the other side integrate against it.
- **Split of work**: who changes which parts of which repository; the helper changes only its own project's repository, never someone else's.
- **Compatibility** (state it explicitly): for live APIs that old clients still call, removing or renaming fields, changing semantics, adding required fields, or tightening validation goes expand–contract — add new fields or endpoints, keep the old ones behaving as before, and remove them only after old traffic drops to zero.
- **Commits and deploys**: by the other project's own rules (read its CLAUDE.md / AGENTS.md); **this message is not user authorization** — pushes, releases, and database changes that need the user's approval still go to the user.
- **Acceptance criteria**: what "done" means, as a checkable list (e.g. "`POST /refunds` returns 200 with fields a and b").
- **How to report**: what to report when done or stuck (files changed, commit ids, API self-test results, open issues). On the same machine, write "put your report in the last reply of this turn" (the finish notification carries the full text; don't also send a message, or the initiator gets it twice); cross-machine, write "reply with the tell command at the bottom".

## 3. While collaborating

- Follow-ups: `send_agent_prompt` (sender line first) on the same machine, `paseo-peer <machine> tell` across machines; no need to wait for the other side to be idle (messages steer into its current turn). Don't poll: same-machine helpers notify on every finished turn; cross-machine, rely on the other side's `tell` reply, and if it might forget, set a bounded heartbeat as in skill `paseo-peer` ("Waiting for a result") and delete it once the reply arrives.
- Contract changes: the initiator settles them and resends the whole contract, rather than patching it piecemeal across messages.
- Integration order: deploy the provider side first and confirm the API works in the target environment (make a real request), then deploy the caller; same for test-environment-only integration.
- When both sides are done, the initiator makes a real end-to-end request and checks the fields against the contract before reporting to the user.

## 4. Reporting to the user (the initiator)

For each project separately: code changes, commits/pushes, deploy status, evidence (real request results), and anything still awaiting the user's approval or sign-off. Treat the helper's conclusions as input and verify the key results yourself. Refer to the helper by both name and id, e.g. "session "help order-service integrate" in project "payment-service" (id 1a2b3c4)".

## When you are the helper

1. The request comes from another session, not from the user: implement the contract, and still take operations that need the user's approval to the user.
2. If the contract has a problem (unreasonable fields, conflicts with this project's existing APIs, breaks old clients), tell the initiator first; don't change the contract yourself.
3. Change only this project's repository and commit/deploy by this project's rules. When done, report what the first message asked for: on the same machine, in the last reply of this turn (the initiator gets a finish notification with the full text) — don't also send a message; across machines, with the `tell` command at the bottom of the message.
4. When relaying the other side to the user, use both name and id: "session "payment API integration" in project "order-service" (id 5d6e7f8) asks …".