Skip to main content

EXAMPLE-FLOW.md — A Typical Day on h.work

This document illustrates the end-to-end flow using a concrete example. Use this as the canonical reference for how the platform works in practice. See the terminology table in /CLAUDE.md for definitions of all terms (Specialist, Expert, AM, SuperAdmin).

The Cast​

PersonRoleDescription
Amy LiuClient Admin (org_admin)Works at Acme Financial, a h.work client. Primary admin contact for their Org. amy@acmefinancial.com
EleanoraSpecialistThe KYC/AML Specialist Acme Financial has contracted. A named AI Specialist — not a real person. eleanora@h852.work (staging) / eleanora@h.work (prod)
David KimExpertSenior KYC/AML compliance specialist, HP employee. Reviews drafts and sends as Eleanora.
Sarah ChenAccount ManagerHP Account Manager who manages Acme Financial's account and configures Eleanora.

Eleanora's team = David Kim (Expert reviewer) + the agent service (backend drafter on Eleanora's behalf).

Terminology note. "Eleanora" / "Specialist" refers to the named client-facing AI Specialist. "The agent service" refers to the internal Python service (agent/) that produces drafts on the Specialist's behalf. Per CLAUDE.md terminology rules, the persona is always Specialist in product-facing language; the backend service is the agent service (or agent as a directory name). Do not call the Specialist "the agent".

Prerequisites​

Before this flow is possible:

  • Acme Financial has fully completed onboarding — company info confirmed, slug live, channels configured
  • Eleanora (catalog Specialist eleanora-kyc-aml-operations-analyst-38f68734) is assigned to Acme Financial by Sarah Chen
  • Amy is a Client Admin with access to the Acme Financial client portal
  • Amy's email (amy@acmefinancial.com) is on the Email Whitelist for Eleanora's inbox

The Flow​

Step 1 — Amy Sends a Request​

Amy sends a message to Eleanora via the client portal (or emails eleanora@h852.work):

"Hi Eleanora, I have a customer escalation — John Smith (ID: JS-4821) failed KYC verification but I believe this was a system error. Can you review and override if appropriate?"

The message arrives on the channel linked to Acme Financial's Org. The platform routes it into the h.work queue, associated with Eleanora.

Step 2 — Specialist Draft (via the agent service)​

The agent service picks up the message on Eleanora's behalf. It:

  1. Loads Eleanora's system prompt (KYC/AML Specialist context configured in the catalog)
  2. Identifies this as a KYC override request
  3. Drafts a response in Eleanora's voice:

"Hi Amy, I've reviewed John Smith's verification (JS-4821). His passport expired 3 days ago — this falls within your 30-day override window per your compliance policy. I can process the exception with your approval. Please confirm and I'll proceed immediately. — Eleanora"

The agent service assigns a confidence score of 82 and risk_level: LOW to this draft.

Step 3 — Expert Review​

Acme Financial's confidenceThreshold is set to 101 by default (all responses require Expert review — the platform default). The draft is routed to the Expert Queue as an ExpertQueueItem.

David Kim logs into the Expert Workspace (/workspace/queue) and sees the queue item. He opens it:

  • Amy's original message
  • Eleanora's draft response (from the agent service)
  • Confidence score and risk level

David reviews the draft, confirms the KYC policy aligns with the response, and approves the draft with a minor edit:

"Hi Amy, I've reviewed John Smith's verification (JS-4821). His passport expired on April 26th — within your 30-day override window. I'll process the override now. Please confirm to authorize. — Eleanora"

David hits Send as Eleanora.

Step 4 — Response Sent to Amy​

The response is sent from eleanora@h852.work to Amy via the client portal (or email/WhatsApp, depending on channel). The Specialist email is backed by a real Google Workspace user — outbound replies are sent from the Specialist's gsuite mailbox via Gmail API DWD impersonation (shipped 2026-06-05, PR #1722). Inbound mail is handled by Gmail API polling, with the Cloudflare Email Routing worker retained as a fallback during the 2-week prod soak (tracking #1440/#1441). Resend is reserved for transactional/invite/onboarding email only. The message appears to come from Eleanora — Amy has no visibility into David's involvement or the agent service's draft.

Step 5 — Amy Confirms​

Amy replies with her confirmation. David can either:

  • Mark the conversation Resolved if the response handled it fully
  • Leave it Active for follow-up

Step 6 — Logging and Training​

The full conversation is logged:

  • Amy's original request
  • The Specialist's initial draft from the agent service (with confidence score and risk level)
  • David's edit and approval
  • Final sent message

The agent service's draft and David's edit are stored as a Correction record, used for quality review and ongoing prompt improvement.

The Low-Confidence Path​

If the agent service produces a low-confidence draft on Eleanora's behalf (e.g., score 30 for an edge case it can't fully resolve):

  1. The queue item surfaces to David with the low-confidence draft and a flag
  2. David logs in, reviews the draft, and either edits it substantially or composes a full manual response in the Expert Workspace — exactly as if David were an Acme Financial employee
  3. Response sent as Eleanora
  4. The correction is stored for review

Key Design Principles Illustrated​

  1. Eleanora is always the face — Amy never knows whether the agent service or David drafted the response. Consistent Specialist identity builds client trust.

  2. Specialist drafts (via the agent service), Expert verifies — the default loop is AI-first with human quality control. This is the core cost and quality model.

  3. Confidence threshold is configurable — Sarah Chen (AM) or David (Expert) can tune how much Expert involvement is required per Specialist. Default is 101 (always Expert review). For FAQ-style queries, it can be lowered.

  4. Graceful degradation — if the agent service can't produce a satisfactory draft, David can compose manually. The system never leaves Amy without a response.

  5. Full audit trail — every action, draft, edit, and send is logged. This supports quality review, client trust, regulatory compliance, and continuous improvement.

For per-feature implementation status, see implementation-status.md.

Created: 2026-04-29 Last updated: 2026-06-03 (terminology pass — "agent"/"AI persona" → "Specialist"/"agent service" per CLAUDE.md) Owner: Platform team

Last updated on by Degen