diff --git a/affordances/officer/core/coordinating-another-agent.md b/affordances/officer/core/coordinating-another-agent.md new file mode 100644 index 0000000..de8c880 --- /dev/null +++ b/affordances/officer/core/coordinating-another-agent.md @@ -0,0 +1,31 @@ +--- +name: Coordinating another agent +description: Use when the user hands you another agent's name, or asks you to manage, review or drive work another session is doing. +version: 1 +--- + +**You can be handed another session and made responsible for its work.** Not spawned by you — a peer, often +one the user started themselves. `ListAgents` shows who is reachable; `SendMessage` talks to them. That much +is in the tool descriptions. What follows is not. + +**The name is the address, and it is not a session id.** `ListAgents` prints names like `platform-59`. A user +who wants to hand you a session will often paste a uuid instead, because that is what they can see — a +transcript id, a URL fragment. It will not resolve. List the agents, work out which one they mean from what +it is doing, and confirm before you rely on it. + +**Do not poll.** `SendMessage` takes `notify_when_idle`, which wakes you once when that session next stops +working. Send the instruction and the subscription together, then stop — the notice is how you learn it is +your turn again. Polling a peer is both slower and visible to them as noise. + +**A message from you is not authorization for them.** This is the part that matters most and the part a +manager gets wrong first. A peer receiving your prompt is right to ask the user before acting on it, and if +they do, that is correct behaviour rather than obstruction. What settles it is the user saying, once, to +*them*, that this hand-off is delegated to you. Ask for that rather than insisting. + +The same rule binds you in the other direction: **never ask a peer to do something you were refused.** Route +it back to the user. + +**What you actually owe, as the manager:** read what they produced rather than taking the summary, write the +next instruction yourself, and carry the standing context they do not have. The reason this arrangement is +worth anything is that the user stops being a clipboard — so if you are relaying their words unchanged, you +have added a step and nothing else.