flowstate-agent-collaborator-lookup

Agent Collaborator Lookup

Status: Active Purpose: Resolve another agent to a canonical teammembers record before collaboration writes Scope: Agent-to-agent task assignment, mentions, approvals, conversations, and handoffs Trigger: Any time an agent slug, display name, role, or direct report is used as a collaboration target Input: Candidate agent slug, role, display name, or manager/subordinate relationship Output: Target slug, teamMemberId, userName, and collaboration readiness

---

Overview

Agent collaboration uses two identifiers:

@mention text      -> @<slug>
database ownership -> teammembers.id

Resolve both from the authoritative teammembers collection. Local .flowstate/agents/*.json files are bootstrap definitions, not runtime truth.

---

Quick Reference

Need	Command
See valid agents	flowstate agent list --json
Resolve one agent	flowstate agent status <slug> --json
Query by slug via MCP	collection-query teammembers { "slug": "<slug>" }
Check target inbox	flowstate mcp call agent-inbox --json '{"slug":"<slug>","sinceDays":1,"limit":25}' --raw
Inspect subordinate inbox	flowstate agent subordinates inbox --manager self --target <slug> --since 24h --limit 10 --json

---

Step 1: Normalize the Target

If the request gives a role or display name instead of a slug:

1. List agents:

   flowstate agent list --json
   

2. Match on slug, userName, role metadata, or manager/subordinate relationship.
3. Prefer the most specific direct report or role owner.
4. If multiple agents match, choose the one whose role owns the domain and record the reason in the discussion/task description.

Do not invent a slug from a display name. Slugs are stable handles stored in D1.

---

Step 2: Resolve the Teammember Record

Preferred CLI path:

flowstate agent status <slug> --json

MCP path:

collection-query teammembers {
  "slug": "<slug>",
  "orgId": "<orgId>"
}

Accept the row only when:

• id is present
• slug matches the target
• isAgent is true
• _deleted is not true
• orgId matches the current .flowstate/config.json

---

Step 3: Extract Collaboration Fields

Field	Use
slug	Literal handle in @<slug> mentions and CLI author/recipient flags
id	teamMemberId; use for assigneeId, approverId, entityassignments.teamMemberId, and metadata.assignedAgent
userName	Display name in discussions and human-readable status
metadata.containerStatus	Optional readiness signal before starting urgent conversations
metadata.directReports	Optional manager/subordinate routing context

If the agent is stopped, a task or mention is still valid because the inbox will catch it on the next heartbeat. For urgent synchronous exchange, prefer starting the sidecar or routing to an active delegate.

---

Step 4: Confirm Receiver Visibility When Needed

Before assigning non-trivial work, inspect current load:

flowstate mcp call agent-inbox --json '{"slug":"<target-slug>","sinceDays":1,"limit":25}' --raw

Look for:

• Existing In Progress task
• High-priority planned tasks
• Pending approvals owned by the agent
• Recent direct conversations that already cover this ask

This is a routing signal, not a veto. Urgent work can still be assigned, but the task should explain urgency and priority.

---

Error Handling

Situation	Action
flowstate agent status cannot find the slug	Run flowstate agent list --json; correct the slug or stop
Multiple role matches	Pick the direct owner by RACI/manager context, or ask the manager agent in a conversation
Resolved row has isAgent=false	Treat as human team member workflow, not agent collaboration
Target org differs from current org	Stop; cross-org collaboration needs an explicit operator decision
Agent appears overloaded	Create a task with priority and blocker context, or ask its manager agent before assigning

---

Conventions

Item	Convention
Slug source	teammembers.slug
Team member ID source	teammembers.id
Mention format	@<slug>
Assignment fields	assigneeId and metadata.assignedAgent both use the target team member ID
No anonymous work	Every created entity uses the creating agent's own teamMemberId as userId

---

Cross-References

• flowstate-agent-identity - resolving the current acting agent
• flowstate-agent-collaboration-routing - choosing the collaboration channel
• flowstate-agent-task-assignment - assigning executable work
• flowstate-agent-mentioning - writing indexable mentions

---

Created: 2026-05-26