flowstate-agent-collaboration-routing

Agent Collaboration Routing

Status: Active Purpose: Pick the smallest FlowState collaboration channel that will reliably surface in the target agent's inbox Scope: Agent-to-agent work coordination across tasks, discussions, conversations, approvals, and description mentions Trigger: An agent needs another agent to act, review, decide, answer, or take ownership Input: Desired outcome, target agent slug or role, related FlowState entity ID Output: One routed collaboration action with a traceable inbox path

---

Overview

The inbox is the receiving agent's source of truth. Route collaboration to the inbox section that matches the work shape:

Need work done      -> create/assign task        -> Active tasks
Need entity context -> post @mention discussion  -> Mentions
Need answer thread  -> reply to discussion       -> Replies
Need live exchange  -> start/message conversation -> Conversations
Need formal gate    -> create approval           -> Approvals
Need durable owner  -> description @mention      -> Description mentions

Use the most concrete channel available. If you need execution, assign a task. If you only need attention on an existing entity, mention the agent on that entity. If you need back-and-forth with turn control, use an agent conversation.

---

Step 1: Identify the Inbox Item You Want to Create

Desired result	Create this	Receiver sees it under	Companion skill
Agent owns implementation or investigation work	MCP task-create + task-assign, or task-claim for self-ownership	Active tasks	flowstate-agent-task-assignment
Agent should inspect or comment on a task/project/milestone	MCP agent-mention or discussion-create containing @<agent-slug>	Mentions	flowstate-agent-mentioning
Agent should continue an existing discussion thread	MCP discussion-reply with parentId set to the thread root	Replies	flowstate-agent-handoff-response
Agent should answer a short direct question	Agent-chat conversation message	Conversations	flowstate-agent-conversation-protocol
Agent must approve, reject, or request revisions	Approval record with approverId set to target teamMemberId	Approvals	flowstate-approval-workflow
Agent should remain visibly associated with an entity description	Entity description containing @<agent-slug>	Description mentions	flowstate-agent-mentioning

Do not create multiple channels for the same ask unless each channel has a different job. A task assignment may include one discussion comment for context, but the task remains the action item.

---

Step 2: Resolve the Agent First

Before writing anything that names another agent:

1. Use flowstate-agent-collaborator-lookup or MCP agent-resolve.
2. Resolve slug to teammembers.id.
3. Confirm isAgent === true.
4. Use the slug for human-readable @mentions.
5. Use the team member ID for assignment, approval, authorship, and runner scoping fields.

Never infer a team member ID from a display name, role title, or local agent file.

---

Step 3: Route by Urgency and Ownership

Situation	Route
The target agent must spend real time producing an outcome	Create or update a task, assign owner, and mention them in a discussion
The target agent only needs to read and respond	Post an @<slug> discussion on the related entity
The target agent is already in a thread	Reply to the existing root discussion rather than starting a new thread
The target agent must unblock a process step	Create or update an approval, then mention the approval's related entity if needed
Two or more agents need bounded deliberation	Start an agent-chat conversation with maxTurns and expectedConfidence
A manager needs visibility into a subordinate's load	Use subordinate report/inbox commands before assigning more work

---

Step 4: Verify the Receiver Can See It

After creating the routed item, run the lowest-cost verification:

Channel	Verification
Task assignment	flowstate mcp call agent-inbox --json '{"slug":"<target-slug>","sinceDays":1,"limit":25}' --raw
Mention	Check the agent-mention/discussion-create response, or fallback collection-query discussions, and confirm mentions includes target
Reply	Check the discussion-reply response, or fallback collection-get discussions <reply_id>, and confirm parentId is the root discussion
Conversation	flowstate agent conversation show <conv_id>
Approval	collection-get approvals <approval_id> and confirm status: "pending" plus target approverId
Description mention	`collection-get <tasks

If verification fails, fix the FlowState record. Do not tell the requester the agent was notified until the item is visible through the expected channel.

---

Error Handling

Situation	Action
Target slug is unknown	Stop and list valid agents with flowstate agent list; do not create anonymous work
Target is a human team member	Use human assignment or approval flow; do not label it agent-to-agent collaboration
Related entity is missing	Create or recover the parent entity first; do not post orphaned context
Same ask already exists in receiver inbox	Update or reply to the existing item instead of duplicating
Receiver has an In Progress task	Assign only urgent work, and state priority/blocker context in the task or mention

---

Conventions

Item	Convention
Agent handle	@<slug>
Agent identity source	teammembers row resolved by slug
Work owner	tasks.assigneeId plus entityassignments owner
Runner owner	metadata.assignedAgent set to target teamMemberId
Traceability	Every collaboration write references a task, project, milestone, approval, or conversation ID
Inbox proof	Verify with target inbox, discussion query, conversation show, or approval get before claiming routed

---

Cross-References

• flowstate-agent-inbox - receiver-side triage of every routed item
• flowstate-agent-collaborator-lookup - resolving agent slugs and team member IDs
• flowstate-agent-task-assignment - creating work that appears in Active tasks
• flowstate-agent-mentioning - writing mentions that index correctly
• flowstate-agent-handoff-response - replying and escalating from inbox items
• flowstate-agent-conversation-protocol - bounded direct agent conversations

---

Created: 2026-05-26