Developer Handover Pack

Developer Handover Pack

Client Reporting & Status Updates

Queries the connected Asana workspace at the start of each reporting window and retrieves task-level progress, open blockers, overdue items, and upcoming milestones for each active account project. The agent normalises the raw Asana data into a structured weekly status object that downstream agents can consume directly. It replaces the 40-minute manual Asana trawl and the 25-minute prioritisation step.

// Input
account_id: string          // Internal account identifier
reporting_week: ISO8601     // e.g. 2024-06-03
asana_project_gid: string   // Asana project GID mapped to account

// Output
status_object: {
  account_id: string,
  week_ending: ISO8601,
  tasks_completed: Task[],
  tasks_in_progress: Task[],
  blockers: Task[],
  upcoming_milestones: Milestone[],
  rag_status: 'green' | 'amber' | 'red'
}

Receives the structured status object from the Status Gathering Agent and produces a client-ready update document in the house style. The LLM prompt uses a locked template that enforces tone, section order, and word count. The draft is written to a Google Doc in a designated review folder and a review link is surfaced to the Account Manager via the configured notification channel. The agent replaces the 55-minute manual writing step.

// Input
status_object: StatusObject  // From Status Gathering Agent
template_doc_id: string      // Google Drive ID of master template
client_display_name: string  // Name used in salutation
house_style_prompt: string   // Injected system prompt fragment

// Output
draft_doc_url: string        // Google Docs review URL
draft_doc_id: string         // Google Drive file ID
run_id: string               // Orchestration run reference
review_status: 'pending_review'

Fires only after the Account Manager approves the draft (review_status set to 'approved'). Reads the final Google Doc content, composes and sends an HTML email to the client contact via Gmail, then creates or updates a HubSpot engagement record against the account. The agent replaces the 15-minute send step and the 15-minute manual CRM logging step.

// Input
run_id: string               // Orchestration run reference
draft_doc_id: string         // Approved Google Docs file ID
client_email: string         // Recipient email address
hubspot_company_id: string   // HubSpot company record ID
account_manager_email: string

// Output
gmail_message_id: string     // Sent message ID for audit log
hubspot_engagement_id: string
run_status: 'complete'
sent_at: ISO8601

// ── TRIGGER ─────────────────────────────────────────────────────────────
CRON schedule fires  ->  FullSpec Automation orchestrator wakes
  payload: { account_id, reporting_week, asana_project_gid,
             template_doc_id, client_email, hubspot_company_id,
             account_manager_email, client_display_name }

// ── AGENT 1: Status Gathering Agent ─────────────────────────────────────
FullSpec -> Asana Projects API
  GET /projects/{asana_project_gid}/tasks?opt_fields=name,completed_at,
       due_on,custom_fields,assignee
  -> filter: active tasks + tasks completed in reporting_week
  -> classify: blockers (overdue > 2 days), milestones, in-progress
  -> derive rag_status from blocker count + overdue pct

FullSpec emits status_object:
  { account_id, week_ending, tasks_completed[], tasks_in_progress[],
    blockers[], upcoming_milestones[], rag_status }

// ── AGENT 2: Update Drafting Agent ──────────────────────────────────────
FullSpec -> Google Drive API
  POST /files/{template_doc_id}/copy
  -> new draft_doc_id created in /ClientUpdates/{account_id}/

FullSpec -> Google Docs API
  POST /documents/{draft_doc_id}:batchUpdate
  -> inject: client_display_name, rag_status, completed summary,
             blocker list, upcoming milestones

FullSpec -> LLM (GPT-4o via FullSpec Automation)
  system: house_style_prompt
  user:   status_object JSON + doc placeholder markers
  -> returns: polished prose sections (max 300 words)

FullSpec -> Google Docs API batchUpdate (second pass)
  -> write LLM prose into placeholder sections

FullSpec -> Gmail API (notification only)
  POST /users/me/messages/send
  -> To: account_manager_email
  -> Body: 'Your draft update is ready: {draft_doc_url}'

run_record.review_status = 'pending_review'

// ── HUMAN GATE ──────────────────────────────────────────────────────────
Account Manager opens draft_doc_url
  -> Optional edits made directly in Google Doc
  -> AM sets review_status = 'approved' via FullSpec review UI
     OR clicks approve link in notification email

// ── AGENT 3: Send & Log Agent ────────────────────────────────────────────
FullSpec <- webhook: { run_id, review_status: 'approved' }

FullSpec -> Google Docs API
  GET /documents/{draft_doc_id}  -> extract final plain-text + HTML body

FullSpec -> Gmail API
  POST /users/me/messages/send
  From: account_manager_email (delegated send)
  To:   client_email
  Subject: 'Your weekly update: {client_display_name} w/e {week_ending}'
  Body: HTML-formatted update content
  -> returns: gmail_message_id

FullSpec -> HubSpot Engagements API v3
  POST /crm/v3/objects/emails
  -> associations: companyId = hubspot_company_id
  -> properties: hs_timestamp, hs_email_subject, hs_email_text,
                 hs_email_html, hubspot_owner_id (AM)
  -> returns: hubspot_engagement_id

FullSpec marks run_record:
  { run_status: 'complete', sent_at: ISO8601, gmail_message_id,
    hubspot_engagement_id }

// ── OUTPUT ───────────────────────────────────────────────────────────────
Client receives weekly update email
HubSpot account record reflects sent communication
FullSpec dashboard shows run complete