---
name: verbiflow
description: Use for GTM, outbound, sales, research, enrichment, lead lists, messaging, sequences, senders, notifications, CRM, and durable Plays through the Verbiflow Python SDK.
metadata:
  short-description: Execute GTM work through the typed Verbiflow SDK
---

# Verbiflow

Verbiflow is the execution layer for audience discovery, company and person
research, enrichment, qualification, positioning, messaging, sequences,
senders, inboxes, CRM, notifications, reporting, and repeatable GTM Plays.
Use typed `vf.*` calls whenever correctness depends on live workspace state,
provider evidence, durable artifacts, or a platform mutation. Pure advice can
remain advice.

## Operating contract

- Start from the user's commercial outcome. Resolve who matters, why now, what
  evidence supports the decision, what action should follow, and how the work
  can remain useful.
- Separate verified facts, reasoned inference, and recommendations. Preserve
  source identity, observation time, qualification rationale, and limitations.
- Bound execution with explicit budgets, deadlines, cursors, and retry guards;
  never turn those operational bounds into a business membership rule. Preview
  samples prove shape only. A final Play must evaluate the complete declared
  universe (or disclose that it stopped partial), retain every analyzed row,
  and express qualification or ranking as evidence-driven fields and filters.
  Never turn a provider failure, empty page, or partial source into success.
- Inspect representative final rows and cross-artifact relationships. Syntax,
  row count, stdout, and an empty QA file are not proof of semantic quality.
- Preserve canonical IDs and receipts. Resume or repair the same job, Play,
  revision, schedule, tick, run, and artifact instead of silently creating a
  replacement.
- Keep large schemas, raw captures, and row bodies out of conversation context.
  Save them as artifacts and inspect only the ranges needed for the next step.
- Explore while a material uncertainty could still change correctness, scope, or
  the deliverable. Once evidence resolves that uncertainty, consolidate the
  proven acquisition, normalization, validation, and output path into a bounded
  program with concurrent independent I/O. Every pagination or retry loop needs
  a deadline and no-progress guard.
- Use `ctx.progress(...)` for numeric low-level activity. Use
  `ctx.milestone(...)` for a small number of semantic workflow stages with a
  stable `stage_id`; completed milestones must cite `run`, `output`, `job`, or
  `artifact` ids that already resolve from the current run's durable store.
- Before a terminal completion claim, verify the exact final artifact bytes and
  durable receipts. A completed Play requires evidence for its synced revision,
  run, and declared outputs; otherwise report the saved partial state.

## One-off work or a Play

Use a one-off SDK operation when the user needs a bounded answer or isolated
mutation that will not be refreshed, scheduled, audited, or handed off.

Use a durable Play when the work should be repeated, scheduled, refreshed,
reviewed, repaired, or reused. The Play must own the successful acquisition,
transformation, validation, and declared outputs. Exploratory code may discover
the source shape, but captured answers or static fixtures are not a reproducible
Play. Calling step functions directly is not a durable run.

Before substantial work on a new or edited Play, prove that Play-authoring
authority is available. Give each semantic deliverable its own membership
predicate and lineage. Two outputs may contain identical rows only after each
predicate is independently evaluated.

## Effects and approvals

| Class | Examples | Rule |
| --- | --- | --- |
| Read | List, inspect, search, preview, status | Execute when needed; preserve evidence. |
| Local/draft | Write project files, build a draft, preview output | Execute; disclose the useful result. |
| Reversible platform write | Create/edit a draft, sync a Play, create/pause a schedule | Execute when clearly requested; verify the receipt. |
| External communication | Send email/LinkedIn, publish externally, post a real notification | Require clear user intent and follow the owning guide's preflight. |
| Purchase or irreversible change | Buy domains/mailboxes, delete or transfer durable state | Require explicit approval immediately before the effect. |

Never hide a side effect inside a helper or retry. Preview, validate, and quote
costs or audience scope before consequential effects when the owning guide
requires it.

## Start here

1. Classify the outcome as advice, one-off execution, or a durable Play.
2. Resolve one outcome guide below. Use its choice hierarchy to select a
   capability or provider leaf, then read the exact callable owner only when the
   operation remains unresolved.
3. Inspect only the live state needed to remove material uncertainty.
4. Execute the smallest coherent program, preserving IDs and durable receipts.
5. Verify the requested semantics and final artifacts before reporting success.

Do not recursively read the graph. Open a child only when it resolves the next
material decision, a provider rule, or an exact callable contract.

Every substantial reference begins with a generated Guide map. Its stable
section IDs and exact runtime-specific line ranges let you read only the section
needed for the next decision.

Reference names below are relative Skill files. Open the outcome first, then the
smallest child needed for the next decision.

## Outcome routes

Start with the outcome, not a provider or namespace. The outcome guide
chooses among its capability and provider references. Open an exact owner
guide only when a callable contract or provider-specific rule is needed.

### Find

| Outcome | Start here when |
| --- | --- |
| [`company-search.md`](references/company-search.md) | Find and qualify companies from ICP, market, geography, funding, or local-business criteria. |
| [`contact-search.md`](references/contact-search.md) | Find the right people at target companies and preserve identity, role, and source evidence. |
| [`job-search.md`](references/job-search.md) | Find current job openings and turn hiring evidence into qualified company or contact rows. |
| [`signals.md`](references/signals.md) | Find timely GTM signals such as funding, activity, intent, and relationship evidence. |

### Understand

| Outcome | Start here when |
| --- | --- |
| [`company-enrichment.md`](references/company-enrichment.md) | Resolve trustworthy company facts, identifiers, firmographics, and evidence for known companies. |
| [`contact-enrichment.md`](references/contact-enrichment.md) | Resolve trustworthy person identity, role, profile, email, phone, and evidence for known contacts. |
| [`web-research.md`](references/web-research.md) | Research public or rendered web sources while retaining URLs, captures, and structured evidence. |

### Create

| Outcome | Start here when |
| --- | --- |
| [`copywriting.md`](references/copywriting.md) | Create, critique, and verify grounded outbound copy and personalization. |
| [`artifacts.md`](references/artifacts.md) | Create, inspect, verify, publish, and share durable jobs, CSV, HTML, report, and rowset outputs. |

### Activate

| Outcome | Start here when |
| --- | --- |
| [`outbound-campaigns.md`](references/outbound-campaigns.md) | Design, stage, publish, and operate multistep outbound sequences with truthful audience data. |
| [`mailboxes.md`](references/mailboxes.md) | Connect, provision, inspect, and prepare mailbox, sender, and sending-domain capacity for outbound. |
| [`inbox-and-replies.md`](references/inbox-and-replies.md) | Inspect, triage, classify, and reply to email or LinkedIn conversations. |
| [`linkedin-outreach.md`](references/linkedin-outreach.md) | Research relationships and perform approved LinkedIn connection, message, and posting work. |
| [`notifications.md`](references/notifications.md) | Configure, inspect, analyze, and verify Slack notification delivery for workspace events. |

### Automate

| Outcome | Start here when |
| --- | --- |
| [`workflows.md`](references/workflows.md) | Build, run, schedule, verify, and hand off repeatable durable GTM Plays. |

### Operate

| Outcome | Start here when |
| --- | --- |
| [`crm.md`](references/crm.md) | Inspect, connect, and operate CRM schema, HubSpot lists, list creation and deletion, contact and company upserts, objects, properties, associations, and inline contact enrichment. |
| [`billing.md`](references/billing.md) | Inspect workspace billing, plans, credits, usage, checkout, and reconciliation state. |

Local-only setup and host integration:

| Need | Owning reference |
| --- | --- |
| Login, profiles, workspace focus, project context | `references/auth.md` |
| Find an exact callable when the route map is insufficient | `references/discovery.md` |
| Local coding-agent harness integration | `references/agent_harnesses.md` |
| <!-- VERBIFLOW_HOST_REFERENCE_ROW --> | Selected host guide injected by `install.sh`. |
| Local multi-Play queues | `references/workflow_queues.md` |

## Local execution

- Import `verbiflow as vf`; do not substitute CLI or MCP calls for SDK work.
- Resolve the installed SDK interpreter once and reuse it. Never assume bare
  system Python contains the correct `verbiflow` package.
- Authenticate and focus the intended workspace/project root before live work.
  Keep tokens out of output. Use `references/auth.md` for the exact precedence.
- Local Chrome, cookie capture, daemon sync, external schedulers, and local
  workflow roots are available only through their owning references.
- Keep reusable Play projects under the user's chosen durable root, not `/tmp`.
