Developer Handover Pack

Developer Handover Pack

Meeting and Decision Documentation

Connects to the Zoom API to retrieve the cloud recording for a completed meeting session. Converts the audio file to a full text transcript with speaker labels and timestamps. Designed to handle variable audio quality and meeting lengths up to 90 minutes. Output is a clean, structured transcript string passed directly to the Summary and Action Extraction Agent. Estimated build time: 6 hours. Complexity: Moderate.

// Input
zoom_webhook_payload: {
  event: 'recording.completed',
  payload.object.uuid: string,          // Zoom meeting UUID
  payload.object.host_id: string,
  payload.object.topic: string,         // Meeting title
  payload.object.start_time: ISO8601,
  payload.object.duration: integer,     // Minutes
  payload.object.recording_files: [
    { file_type: 'MP4'|'M4A', download_url: string, status: 'completed' }
  ]
}

// Output
transcript_payload: {
  meeting_uuid: string,
  meeting_title: string,
  meeting_start_time: ISO8601,
  meeting_duration_minutes: integer,
  host_id: string,
  transcript_text: string,              // Full timestamped speaker-labelled text
  speaker_segments: [
    { speaker: string, timestamp: string, text: string }
  ],
  transcript_status: 'success'|'partial'|'failed',
  error_reason: string|null
}

Receives the transcript payload from the Transcription Agent and uses a structured prompt to produce a formatted meeting summary covering key discussion points, decisions reached, and action items with proposed owners and due dates. Applies a consistent output schema every time regardless of meeting type or facilitator. Writes the summary to a new Notion database page and creates one ClickUp task per action item. Estimated build time: 9 hours. Complexity: Complex.

// Input
transcript_payload: {
  meeting_uuid: string,
  meeting_title: string,
  meeting_start_time: ISO8601,
  meeting_duration_minutes: integer,
  transcript_text: string,
  speaker_segments: [ { speaker, timestamp, text } ],
  transcript_status: 'success'|'partial'
}

// Output (after LLM extraction)
structured_summary: {
  meeting_title: string,
  meeting_date: ISO8601,
  attendees_inferred: string[],          // Speaker labels from transcript
  key_discussion_points: string[],
  decisions_reached: string[],
  action_items: [
    {
      action_text: string,
      proposed_owner: string,
      proposed_due_date: ISO8601|null,
      clickup_task_id: string            // Populated after ClickUp write
    }
  ],
  notion_page_id: string,               // Populated after Notion write
  notion_page_url: string,
  partial_transcript_flag: boolean
}

// On approval (passed to Distribution Agent)
distribution_payload: {
  meeting_uuid: string,
  meeting_title: string,
  meeting_date: ISO8601,
  notion_page_url: string,
  summary_text: string,                 // Human-readable paragraph form
  action_items: [ { action_text, proposed_owner, proposed_due_date } ],
  approval_status: 'approved'|'edited_and_approved',
  approved_by: string,
  approved_at: ISO8601
}

Receives the approved distribution payload and handles all outbound communication. Retrieves the full attendee list from the Google Calendar event linked to the meeting UUID, composes and sends a formatted follow-up email via Gmail to all attendees, and posts a condensed summary to the designated Slack channel. Operates only after the human review gate returns an 'approved' or 'edited_and_approved' status. Estimated build time: 5 hours. Complexity: Moderate.

// Input
distribution_payload: {
  meeting_uuid: string,
  meeting_title: string,
  meeting_date: ISO8601,
  notion_page_url: string,
  summary_text: string,
  action_items: [ { action_text, proposed_owner, proposed_due_date } ],
  approval_status: 'approved'|'edited_and_approved',
  approved_by: string,
  approved_at: ISO8601
}

// Output
distribution_result: {
  email_sent: boolean,
  email_recipients: string[],           // Resolved from Google Calendar event
  gmail_message_id: string,
  slack_post_ts: string,               // Slack message timestamp (thread ID)
  slack_channel_id: string,
  notion_status_updated_to: 'Sent',
  distribution_completed_at: ISO8601,
  errors: string[]|null
}

// ─────────────────────────────────────────────────────────────────
// TRIGGER: Zoom meeting session ends
// ─────────────────────────────────────────────────────────────────
ZOOM_WEBHOOK_EVENT: recording.completed
  -> meeting_uuid         : string   (Zoom payload.object.uuid)
  -> meeting_title        : string   (Zoom payload.object.topic)
  -> meeting_start_time   : ISO8601  (Zoom payload.object.start_time)
  -> meeting_duration     : integer  (Zoom payload.object.duration, minutes)
  -> host_id              : string   (Zoom payload.object.host_id)
  -> calendar_event_id    : string   (Zoom payload.object.calendar_event_id, if present)
  -> recording_files[]    : array    (file_type, download_url, status)

  // Dedupe check: meeting_uuid written to log table
  // If UUID already exists: discard, return HTTP 200

// ─────────────────────────────────────────────────────────────────
// AGENT 1: Transcription Agent
// ─────────────────────────────────────────────────────────────────
INPUT:
  recording_url           : string   (signed download URL, expiry 24h)
  preferred_file_type     : 'TRANSCRIPT'|'M4A'|'MP4'  (priority order)

PROCESSING:
  1. Fetch VTT/TRANSCRIPT file if available
  2. If absent: fetch M4A audio -> send to transcription service in 20-min chunks
  3. Merge chunks with 30-second overlap deduplication
  4. Parse speaker labels and timestamps into speaker_segments[]

OUTPUT -> transcript_payload:
  meeting_uuid            : string
  meeting_title           : string
  meeting_start_time      : ISO8601
  meeting_duration_minutes: integer
  host_id                 : string
  transcript_text         : string   (full merged text)
  speaker_segments[]      : [ { speaker, timestamp, text } ]
  transcript_status       : 'success'|'partial'|'failed'
  error_reason            : string|null

  // On 'failed': write error to log table, alert Slack ops channel, STOP
  // On 'partial': continue with partial_transcript_flag = true

// ─────────────────────────────────────────────────────────────────
// HANDOFF 1: transcript_payload -> Summary and Action Extraction Agent
// ─────────────────────────────────────────────────────────────────

// ─────────────────────────────────────────────────────────────────
// AGENT 2: Summary and Action Extraction Agent
// ─────────────────────────────────────────────────────────────────
INPUT:
  transcript_text         : string
  speaker_segments[]      : [ { speaker, timestamp, text } ]
  transcript_status       : 'success'|'partial'
  meeting_title           : string
  meeting_start_time      : ISO8601

PROCESSING:
  1. Send transcript_text to LLM with structured JSON output prompt
  2. Validate LLM response against structured_summary JSON schema
  3. If validation fails: retry with simplified prompt, log warning
  4. Write Notion page to NOTION_DB_MEETING_SUMMARIES (status: 'Draft')
     -> notion_page_id, notion_page_url returned
  5. For each action_items[n]:
     a. Resolve proposed_owner -> ClickUp member ID via name mapping table
     b. POST task to CLICKUP_LIST_ID_ACTIONS
     c. Store clickup_task_id on action_items[n]
  6. Update Notion page with ClickUp task URLs
  7. If partial_transcript_flag: prepend warning banner to Notion page body

OUTPUT -> structured_summary (stored, awaiting approval):
  meeting_title           : string
  meeting_date            : ISO8601
  attendees_inferred[]    : string[]
  key_discussion_points[] : string[]
  decisions_reached[]     : string[]
  action_items[]          : [ { action_text, proposed_owner,
                               proposed_due_date, clickup_task_id } ]
  notion_page_id          : string
  notion_page_url         : string
  partial_transcript_flag : boolean

// ─────────────────────────────────────────────────────────────────
// REVIEW GATE: Human approval step (Ops Manager)
// ─────────────────────────────────────────────────────────────────
  Ops Manager receives draft notification (Slack DM or email)
  Reviews Notion page draft
  Action: Approve | Edit then Approve
  approval_status         : 'approved'|'edited_and_approved'
  approved_by             : string
  approved_at             : ISO8601
  Notion page status updated to 'Approved'

// ─────────────────────────────────────────────────────────────────
// HANDOFF 2: distribution_payload -> Distribution Agent
// ─────────────────────────────────────────────────────────────────

// ─────────────────────────────────────────────────────────────────
// AGENT 3: Distribution Agent
// ─────────────────────────────────────────────────────────────────
INPUT:
  meeting_uuid            : string
  meeting_title           : string
  meeting_date            : ISO8601
  notion_page_url         : string
  summary_text            : string
  action_items[]          : [ { action_text, proposed_owner, proposed_due_date } ]
  calendar_event_id       : string   (from log table, set at trigger)

PROCESSING:
  1. Fetch Google Calendar event by calendar_event_id
     -> attendee_emails[] : string[] (from event.attendees[].email)
  2. If calendar_event_id absent: match by start_time +/- 10 min + host email
  3. Render Gmail HTML template with meeting_title, meeting_date,
     summary_text, action_items_list (HTML ol), notion_page_url
  4. Send email via Gmail API to attendee_emails[]
     -> gmail_message_id returned
  5. Compose Slack Block Kit message:
     header_block: meeting_title
     section_block: summary_text (condensed, max 3 sentences)
     bullet_list: action_items[] with proposed_owner
     button: 'View Full Notes' -> notion_page_url
  6. POST to SLACK_CHANNEL_MEETING_SUMMARIES
     -> slack_post_ts, slack_channel_id returned
  7. Update Notion page status to 'Sent'

OUTPUT -> distribution_result:
  email_sent              : boolean
  email_recipients[]      : string[]
  gmail_message_id        : string
  slack_post_ts           : string
  slack_channel_id        : string
  notion_status_updated_to: 'Sent'
  distribution_completed_at: ISO8601
  errors[]                : string[]|null

  // On email failure: retry once after 60s
  // On second failure: log error, set Notion status 'Email Failed',
  //                    alert Slack ops channel
// ─────────────────────────────────────────────────────────────────
// END: All records written to Supabase log table for monitoring
// ─────────────────────────────────────────────────────────────────