lead-followup

name	lead-followup
description	Runbook for turning a new HubSpot lead into a researched, personalized follow-up email and a proposed call slot for {{projectName}}. Covers company research, the sales playbook (positioning, tone, qualifying questions), HubSpot record updates, Google Calendar availability, and the human approval gate before anything sends.

Inbound leads convert on the follow-up that shows the company was actually read, and that follow-up has to go out while the lead is still warm. A periodic sweep reads HubSpot for leads on {{hubspot_lifecycle_stage}} that haven't been handled yet, researches each company, drafts a personalized follow-up to the sales playbook with one tailored qualifying question, checks Google Calendar for a real opening and proposes that one slot, and writes the research back onto the HubSpot record. Nothing reaches a lead until a human reviews the draft in {{approval_channel}} and sends it.

Fresh session per sweep — state lives on the HubSpot lead record itself (a kortix_followup_drafted property + timestamp marks a lead handled), not in a local ledger file. A single sweep can find several new leads at once; handle each one as an independent unit — a research or drafting failure on one lead is logged and skipped, and never blocks or corrupts the follow-up for any other lead in the same sweep.

- The periodic new-lead sweep fires. - A human asks the agent to follow up on a specific lead or re-check HubSpot for new signups. - The sales playbook (positioning, tone, qualifying questions) changes and needs to be reflected in the next drafts.

Step 0 — Orient: find what's new

Query HubSpot for contacts/leads on {{hubspot_lifecycle_stage}} that don't yet carry the drafted marker:

GET /crm/v3/objects/contacts/search
  filterGroups: [
    { propertyName: "lifecyclestage", operator: "EQ", value: "{{hubspot_lifecycle_stage}}" },
    { propertyName: "kortix_followup_drafted", operator: "NOT_HAS_PROPERTY" }
  ]

Anything already carrying kortix_followup_drafted was handled by a prior run — skip it, even if it hasn't been sent yet. Sending is a human decision, not a signal to re-draft.

Step 1 — Read the lead record

Pull the full context for each match: company name and domain, contact name and title, the form fields they submitted, source/UTM, and any notes already on the record.

Step 2 — Research the company

Read the company's public site and any other public information (what they do, recent news, product, size) to understand why this contact likely signed up. The draft has to reference something specific from this research — not just the company name.

Step 3 — Draft the follow-up to the playbook

Write the follow-up using the positioning, tone, and structure in memory, plus what's landed well on past leads. Include exactly one qualifying question, tailored to what this company does, not a generic checklist question.

Step 4 — Propose a call slot

Check Google Calendar for the next open {{meeting_length_minutes}}-minute slot in the team's normal booking window. Offer that one specific time in the draft — not a range, not a scheduling link. This is a read-only check: never create, move, or accept a calendar event yourself; the invite only exists once a human sends the email and the lead confirms.

Step 5 — Write research notes back to HubSpot

Update the lead record with the company research and the qualifying question you used, so the context is preserved on the record even before the email goes out or if a human edits the draft first.

Step 6 — Hold for approval

Place the drafted follow-up in {{approval_channel}} as a draft only. Do not send it. Set kortix_followup_drafted = true (with a timestamp) on the HubSpot record so the next sweep skips this lead.

- **Never send.** Every follow-up is a draft held in {{approval_channel}} for a human to review, edit, and send. - **Calendar is read-only.** Check availability and propose a slot; never create, move, or accept an event. - **HubSpot writes are scoped** to research notes and the `kortix_followup_drafted` marker. Never change deal stage, pipeline, or lifecycle stage. - **No duplicate drafts.** Always check the `kortix_followup_drafted` marker before researching or writing — a lead handled once is never re-drafted, even across many sweeps. - **Scoped secrets.** HubSpot and Google Calendar credentials are injected by the connector at runtime, scoped to this agent's grant.