Brainforge Knowledge

outbound-subagent-architecture

2 min read

Outbound subagent architecture (CRM-first)

Purpose: Align parallel Cursor / Claude Code subagents with the outbound orchestrator (tools/hubspot-api-service/scripts/outbound-orchestrator.ts) and Brainforge repo guardrails.
Contrast: The campaign does not start from an open-ended prompt alone. You begin from a fully loaded contacts sheet ingested into the backend CRM (HubSpot) so every row has the fields needed to hit the list; subagents add personalization on top of that system of record.

1. Flow (high level)

  1. Sheet → CRM — Enriched contacts live in HubSpot (create/update contacts + companies; use existing partner-hubspot / CRM patterns where appropriate).
  2. CRM → JSON — Export a cohort to a leads array (--leads-file): email, name, company, optional hubspotContactId, CRM-backed attributes in meta or top-level fields.
  3. Orchestrator session (main agent) — Loads CLAUDE.md / campaign docs + full sequence JSON so messaging context is shared (not row-only like Clay).
  4. Parallel subagents — Each worker receives:
    • The same sequence + voice / framework docs
    • A deterministic batch of leads: run --batch-index N --batch-size 50 (stable sort by email)
    • A strict output schema: tools/hubspot-api-service/examples/outbound-subagent-output.schema.json
  5. Merge — Combine subagent JSON outputs into one leads file (personalization keyed by email).
  6. Checkpoint — Append completed emails to --skip-emails-file after a successful batch merge so a crash rerun skips finished rows (checkpoint_skip).
  7. run — Renders templates, exclusions, experiments → queue JSONL.
  8. dispatch — Hands off to Email Bison (adapter); ledger prevents double-send.

2. Brainforge hardening (reuse)

PracticeWhere / how
Subagent spec (Role → Mission → Context → Approach → Output)knowledge/sales/second-brain/templates/AGENT-TEMPLATE.md
Agent operating guide (standards-first, repo map)knowledge/standards/agents.md
Structured LLM outputsEnforce JSON only against outbound-subagent-output.schema.json; validate in Cursor before merge.
Idempotency--skip-emails-file + dispatch ledger (same pattern as “skip done work on crash”).
Model qualityPrefer Sonnet (or better) for research-heavy personalization; add a review subagent for tone; avoid cheap models for factual competitor / site claims.

3. CLI flags (orchestrator)

FlagRole
--batch-index / --batch-sizeParallel cohorts after stable email sort (default batch size 50 if index set).
--skip-emails-fileJSON array of emails already merged; excluded as checkpoint_skip.
--require-keysEnforces personalization completeness before queue.
  • Nine-step pipeline + tool map: npm run outbound-orchestrator -- pipeline describe (from tools/hubspot-api-service).
  • Partner HubSpot CLI: tools/hubspot-api-service README (partner-hubspot).

Last updated: 2026-04-08

Graph View