flowstate-agent-handoff-response

Agent Handoff Response

Status: Active Purpose: Turn inbox items into clear replies, escalations, task handoffs, or closure acknowledgements Scope: Mentions, replies, active tasks, conversations, approvals, and description mentions from flowstate inbox Trigger: An agent is triaging inbox and needs to involve, redirect, or acknowledge another agent Input: Inbox row, full entity/discussion/conversation/approval context, target agent if escalating Output: One coherent response path with IDs preserved and next owner clear

---

Overview

Inbox triage should leave the system more legible than it found it. Every response answers:

What did I receive? -> What did I decide? -> Who owns the next action? -> Where is it recorded?

Use this skill after flowstate-agent-inbox surfaces an item.

---

Step 1: Pull Full Context

Never act from the inbox snippet alone.

Inbox section	Pull before responding
Active tasks	collection-get tasks <task_id>
Mentions	collection-get discussions <discussion_id> plus target entity
Replies	Thread root parentDiscussionId, new discussionId, and target entity
Conversations	flowstate agent conversation show <conv_id>
Approvals	collection-get approvals <appr_id> plus related entity/document
Description mentions	`collection-get <tasks

Preserve IDs exactly as printed by the inbox.

---

Step 2: Choose the Response Shape

Inbox item means	Response
You can answer directly	Reply in the same discussion or conversation
You own the work	Start/continue the task and update status
Another agent owns the work	Assign or reassign a task using flowstate-agent-task-assignment
Another agent should weigh in	Mention them on the same entity using flowstate-agent-mentioning
A bounded decision is needed	Start an agent conversation
A formal gate is needed	Create/update an approval
The item is informational	Post a short acknowledgement only if it helps future readers

Avoid scattering the same decision across multiple places. If you escalate, say where the new action lives.

---

Step 3: Reply to a Discussion Thread

For mentions and replies, post to the same entity.

New mention response:

discussion-reply {
  entityType: "<task|project|milestone>",
  entityId: "<entity_id>",
  parentId: "<discussion_id_or_parentDiscussionId>",
  content: "<decision, answer, or escalation note>",
  userName: "<my userName>",
  userId: "<my teamMemberId>",
  orgId: "<orgId>",
  workspaceId: "<workspaceId>",
  threadDepth: 1,
  isEdited: false,
  isDeleted: false
}

For inbox Replies, use parentDiscussionId as parentId, not the new reply's discussionId.

---

Step 4: Escalate to Another Agent

Escalation should create exactly one next-action owner:

Escalation need	Action
Needs execution	Create or reassign a task to target agent
Needs comment/review	Mention target agent in the same entity discussion
Needs short decision	Start agent-chat conversation
Needs formal sign-off	Create approval with target approverId

Always include:

• Original inbox item ID
• Related entity ID
• Why the target agent is the right owner
• What outcome is expected
• Priority or deadline

Then reply to the original thread with the new action ID:

Escalated to @<target-slug> via task_<id> because <reason>. I will monitor the original thread for follow-up.

---

Step 5: Hand Off Active Work

When handing off a task you own:

1. Confirm why you cannot or should not continue.
2. Resolve the receiving agent.
3. Update task ownership and metadata.assignedAgent.
4. Post a task discussion that includes:
   • Current state
   • Work completed
   • Remaining work
   • Known risks
   • Verification already run
5. Stop treating the task as your active work after verification shows the receiver owns it.

Handoff does not mean abandoning context. Leave enough evidence for the receiver to continue cleanly.

---

Step 6: Acknowledge Closure

When a collaboration item is resolved:

Channel	Closure action
Discussion	Reply with result and any linked task/PR/approval ID
Task	Update status/completed fields according to flowstate-task-execution
Conversation	Close with consensus or decision-made and summarize durable outcome elsewhere if needed
Approval	Update approval status and comments
Description mention	Reply on the entity with outcome; do not remove description text unless it is stale or wrong

---

Error Handling

Situation	Action
Inbox snippet lacks enough context	Pull full records before acting
Reply target is unclear	Use the entity discussion root; do not create a separate orphan conversation
Escalation creates duplicate work	Link to the existing task/conversation instead of making another
Target agent is overloaded	Mention manager or lower priority unless the work is urgent/blocking
Approval is pending and you need input	Request revision or comment with blocker; do not leave workflow silently blocked

---

Conventions

Item	Convention
Thread replies	Use root parentDiscussionId
Escalation note	Include new action ID in original thread
Handoff owner	One next owner at a time
Closure	Record outcome where future inbox readers will find it
No silent drops	If choosing no action, be able to state why

---

Cross-References

• flowstate-agent-inbox
• flowstate-agent-collaboration-routing
• flowstate-agent-task-assignment
• flowstate-agent-mentioning
• flowstate-agent-conversation-protocol
• flowstate-approval-workflow

---

Created: 2026-05-26