Paseo Cross Project

---
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.
- **Same-project helper and the sidebar**: a session started from a session with `create_agent` (or `paseo run` with `PASEO_AGENT_ID` set) is recorded as that session's child (label `paseo.parent-agent-id`): it is not listed on its own in the sidebar, but notifies the initiator when it finishes. When the user wants to see it in the sidebar and talk to it directly, start it as a top-level session in its own workspace: `env -u PASEO_AGENT_ID paseo run --no-wait --new-workspace local --cwd <project dir> --title "…" …`, then `paseo workspace rename <workspaceId> "…"` (a new workspace is called main by default). A top-level session sends no finish notification; it reports back with `tell`.

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