core/packages/workflow-chat/README.md

Workflow Chat Integration

Creates scoped chat conversations when workflow stages require team collaboration.

Setup

1. Install the workflow-chat and chat-core packages.
2. In your workflow stage with audience: team, set stage_config:

{
  "on_advance": {
    "package_id": "workflow-chat",
    "entry_point": "on_advance"
  }
}

3. When the workflow advances to that stage, ensure stage_data includes:

{
  "title": "Bug Triage Discussion",
  "team_members": [
    {"id": "user-1", "display_name": "Alice"},
    {"id": "user-2", "display_name": "Bob"}
  ],
  "creator_id": "user-1",
  "creator_display_name": "Alice"
}

The hook will:

• Create a group conversation titled "Bug Triage Discussion [abcd1234]" (suffixed with instance ID)
• Add all team members as participants
• Send a system message linking to the workflow instance
• Enrich stage_data with the conversation_id

Idempotency

If stage_data already contains a conversation_id, the hook returns None (no-op).