Developer Handover Pack

Developer Handover Pack

Capacity Planning Automation

This agent is the data ingestion layer for the entire automation. It triggers on a Monday morning schedule or on receipt of a HubSpot Closed Won webhook and then makes three sequential API calls: one to Asana for task allocations, one to Google Calendar for leave events, and one to HubSpot for late-stage pipeline deals. It assembles a single normalised JSON dataset that downstream agents consume. No calculations or notifications are performed here; the sole responsibility is reliable, deduplicated data retrieval from all three source systems.

// Input
trigger_type: 'schedule' | 'hubspot_webhook'
trigger_timestamp: ISO8601
week_start_date: YYYY-MM-DD  // Monday of the planning week
hubspot_deal_id?: string      // present only on webhook trigger

// Output
capacity_dataset: {
  generated_at: ISO8601,
  week_start_date: YYYY-MM-DD,
  team_members: [
    {
      member_id: string,
      display_name: string,
      asana_user_id: string,
      allocated_hours: number,       // from Asana task assignments
      leave_hours: number,           // from Google Calendar events
      available_hours: number,       // 40 minus leave_hours
      pipeline_demand_hours: number  // from HubSpot deal resource field
    }
  ],
  pipeline_deals: [
    {
      deal_id: string,
      deal_name: string,
      close_date: YYYY-MM-DD,
      resource_hours_estimate: number,
      assigned_member_ids: string[]
    }
  ],
  data_quality_flags: string[]  // e.g. 'member_x: no Asana tasks found'
}

This agent receives the structured dataset from the Data Collection Agent and performs all numerical reasoning. It calculates utilisation percentage for each team member (allocated hours plus pipeline demand hours, divided by available hours), flags anyone over 100% as overloaded and anyone under 60% as underloaded, and records the cause of each flag. It then writes the completed utilisation table to Google Sheets and sets the status flag that determines whether the Reporting and Notification Agent fires a detailed alert or a routine summary.

// Input
capacity_dataset: <object>  // full output from Data Collection Agent

// Output
analysis_result: {
  analysed_at: ISO8601,
  week_start_date: YYYY-MM-DD,
  utilisation_table: [
    {
      member_id: string,
      display_name: string,
      allocated_hours: number,
      available_hours: number,
      pipeline_demand_hours: number,
      total_demand_hours: number,    // allocated + pipeline_demand
      utilisation_pct: number,       // (total_demand / available) * 100
      status: 'overloaded' | 'underloaded' | 'ok',
      flag_reason: string | null
    }
  ],
  overloaded_count: number,
  underloaded_count: number,
  requires_manager_review: boolean, // true if overloaded_count > 0
  sheets_row_written: boolean,
  data_quality_flags: string[]      // passed through from collection agent
}

This agent is the final delivery layer. It reads the analysis result and routes output to two audiences: the operations manager receives a structured Slack message with a full utilisation breakdown, overload flags, and a direct link to the Sheets dashboard; the leadership team receives an updated Notion page summarising overall team utilisation, headcount at risk, and any hiring or contractor flags surfaced by the data. The content and urgency of the Slack message varies based on the requires_manager_review flag from the Capacity Analysis Agent.

// Input
analysis_result: <object>  // full output from Capacity Analysis Agent
sheets_url: string         // deep link to the updated Sheets tab

// Output (Slack)
slack_message: {
  channel: '#capacity-alerts',  // confirm channel name with ops manager
  recipient_user_id: string,     // ops manager Slack user ID
  message_type: 'alert' | 'routine',
  overloaded_members: string[],
  underloaded_members: string[],
  pipeline_pressure_note: string | null,
  sheets_link: string,
  data_quality_warnings: string[]
}

// Output (Notion)
notion_page: {
  page_id: string,          // existing page ID to update, or parent_id to create under
  title: 'Capacity Summary — Week of YYYY-MM-DD',
  sections: [
    'Team Utilisation Table',
    'Overload Flags',
    'Pipeline Pressure',
    'Hiring or Contractor Flags',
    'Data Quality Notes'
  ]
}

// ============================================================
// TRIGGER
// ============================================================
// Source: Weekly schedule (Monday 07:00) OR HubSpot webhook
// Webhook payload (Closed Won trigger):
//   deal_id: string
//   deal_stage: 'closedwon'
//   close_date: YYYY-MM-DD
//   resource_hours_estimate: number

trigger_event -> {
  trigger_type: 'schedule' | 'hubspot_webhook',
  trigger_timestamp: ISO8601,
  week_start_date: YYYY-MM-DD,
  hubspot_deal_id?: string
}

// ============================================================
// DATA COLLECTION AGENT — step 1: Asana task pull
// ============================================================
GET https://app.asana.com/api/1.0/tasks
  ?assignee=<asana_user_gid>
  &project=<portfolio_project_gid>
  &due_on.after=<week_start_date>
  &due_on.before=<week_end_date>
  &opt_fields=assignee,name,custom_fields,estimated_hours,completed

asana_response -> per_member: {
  asana_user_id: string,
  display_name: string,
  tasks: [{ task_id, task_name, estimated_hours, due_on }],
  allocated_hours: number  // sum of estimated_hours across tasks
}

// DATA COLLECTION AGENT — step 2: Google Calendar leave pull
GET https://www.googleapis.com/calendar/v3/calendars/<member_email>/events
  ?timeMin=<week_start_date>T00:00:00Z
  ?timeMax=<week_end_date>T23:59:59Z
  &singleEvents=true
  &orderBy=startTime

calendar_response -> per_member: {
  member_id: string,
  leave_events: [{ event_id, summary, start, end, is_all_day }],
  leave_hours: number  // computed: all_day * 8 + partial_day duration
}

// DATA COLLECTION AGENT — step 3: HubSpot pipeline pull
POST https://api.hubapi.com/crm/v3/objects/deals/search
body: {
  filterGroups: [{
    filters: [
      { propertyName: 'dealstage', operator: 'IN', values: [<late_stage_ids>] },
      { propertyName: 'closedate', operator: 'LTE', value: <14_days_forward> }
    ]
  }],
  properties: ['dealname','closedate','resource_hours_estimate','hubspot_owner_id']
}

hubspot_response -> {
  pipeline_deals: [
    {
      deal_id: string,
      deal_name: string,
      close_date: YYYY-MM-DD,
      resource_hours_estimate: number,
      hubspot_owner_id: string
    }
  ]
}

// DATA COLLECTION AGENT — assembles capacity_dataset
capacity_dataset -> {
  generated_at, week_start_date,
  team_members: [{ member_id, display_name, asana_user_id,
    allocated_hours, leave_hours, available_hours,
    pipeline_demand_hours }],
  pipeline_deals: [...],
  data_quality_flags: [...]
}

// ============================================================
// HANDOFF: Data Collection Agent -> Capacity Analysis Agent
// ============================================================

// CAPACITY ANALYSIS AGENT — calculations
for each member in capacity_dataset.team_members:
  total_demand_hours = allocated_hours + pipeline_demand_hours
  utilisation_pct = (total_demand_hours / available_hours) * 100
  status = utilisation_pct > 100 ? 'overloaded'
         : utilisation_pct < 60  ? 'underloaded'
         : 'ok'

// CAPACITY ANALYSIS AGENT — Sheets write
POST https://sheets.googleapis.com/v4/spreadsheets/<SHEET_ID>/values
  /<TAB_NAME>!A:M:append
body: {
  values: [[
    week_start_date, member_id, display_name,
    allocated_hours, leave_hours, available_hours,
    pipeline_demand_hours, total_demand_hours,
    utilisation_pct, status, flag_reason,
    data_quality_flags, analysed_at
  ]]
}

analysis_result -> {
  analysed_at, week_start_date,
  utilisation_table: [...],
  overloaded_count, underloaded_count,
  requires_manager_review: boolean,
  sheets_row_written: boolean,
  data_quality_flags: [...]
}

// ============================================================
// HANDOFF: Capacity Analysis Agent -> Reporting and Notification Agent
// ============================================================

// REPORTING AGENT — Slack message
POST https://slack.com/api/chat.postMessage
body: {
  channel: '#capacity-alerts',
  blocks: [
    { type: 'header', text: requires_manager_review ? 'ALERT' : 'Capacity Ready' },
    { type: 'section', fields: [overloaded_members, underloaded_members] },
    { type: 'section', text: pipeline_pressure_note },
    { type: 'actions', elements: [{ type: 'button', text: 'View Sheet', url: sheets_url }] }
  ]
}

// REPORTING AGENT — Notion page update
PATCH https://api.notion.com/v1/pages/<notion_page_id>
body: {
  properties: { title: 'Capacity Summary — Week of <week_start_date>' },
  children: [
    utilisation_table_block,
    overload_flags_block,
    pipeline_pressure_block,
    hiring_flags_block,
    data_quality_notes_block
  ]
}

// ============================================================
// END STATE
// ============================================================
// Ops manager has Slack alert with full utilisation breakdown
// Leadership has updated Notion page
// Google Sheets log row appended for trend tracking
// Human step: ops manager reviews, reallocates tasks in Asana if needed