App-managed roles can exchange asynchronous messages across providers. In your prompt, describe who may decide what, when a reply is required, and what should reach the lead. The provider handles labels and message commands.
Choose a communication pattern
Section titled “Choose a communication pattern”Direct collaboration:
Let the API and UI roles resolve routine questions about their shared contract directly. Escalate any change to scope, ownership, or architecture to the lead.
Lead-centered collaboration:
Route design and ownership decisions through the lead. Peers may exchange factual information directly.
Review isolation:
Keep reviewers independent while they assess the verified checkpoint. Let them compare findings only after each has submitted its own result.
These constraints usually communicate more than a prescribed list of message commands.
What the provider handles
Section titled “What the provider handles”The provider creates stable labels for launched roles and uses them as addresses. It can:
- send a prompt or correction to one existing role;
- broadcast one instruction to a group of roles;
- interrupt a running turn before sending a correction;
- wait for a role and read its result; and
- collect structured reports from a durable team run.
A successful send confirms that the app accepted or dispatched the message. It does not mean the recipient has finished. The lead must wait for and read any response that gates later work.
Write messages with a response contract
Section titled “Write messages with a response contract”When an answer matters, state what decision you need and what happens next:
Ask the backend role whether the existing endpoint can support pagination without a schema change. Have it reply to the frontend role with the chosen contract before frontend implementation continues.
For a correction:
Interrupt the migration role, tell it to preserve the current schema, and have it propose alternatives before resuming edits.
For a broadcast:
Tell all implementation roles that the public API is frozen. Ask each role to acknowledge any conflict with its current work.
You can use these as follow-ups after orchestration starts. In a standalone initial request, include an orchestration trigger.
Keep decisions with their owners
Section titled “Keep decisions with their owners”Good prompts identify decision boundaries:
- the lead owns scope, architecture, and integration;
- a component owner answers questions about that component;
- a reviewer reports findings but does not silently redesign the implementation; and
- a blocked role escalates instead of guessing across an ownership boundary.
This structure prevents a message graph from becoming a second, conflicting management system.
Reuse sessions for continuity
Section titled “Reuse sessions for continuity”Send follow-ups to an existing role when it should retain its repository knowledge and prior decisions:
Send the verified review findings back to the original implementer and have it address only confirmed issues.
Launch a fresh session when independence matters:
Start a fresh read-only reviewer after integration. Do not seed it with the implementer’s conclusions.
Messages, reports, and shared state
Section titled “Messages, reports, and shared state”Use each channel for a different purpose:
| Channel | Best for |
|---|---|
| Direct message | Questions, answers, corrections, and negotiation |
| Group message | One instruction shared with several existing roles |
| Team report | A role’s terminal outcome, verification, failures, and uncertainty |
| Coordination state | One current machine-readable decision, owner, lock, or checkpoint |
Keep discussion in messages. Publish shared state only when several roles need one authoritative current value.
See Coordination state for versioned shared facts and CLI automation for exact messaging syntax.