GTM Orchestrator is the pipeline glue that takes a campaign brief from "new campaign" to "ready for human checkpoint before launch." Every intermediate CSV and state is inspectable on disk and in Sheets throughout.
list_source field determines how leads enter the pipeline.Every stage writes to all four observability channels simultaneously.
Trigger: PreToolUse → Read | Edit | Write | Glob | Grep | Bash
Blocks any shell command that reads or references .env files. Forces all env access through Python launcher scripts that load .env programmatically. Prevents accidental secret exposure in tool output.
Trigger: PreToolUse → Bash
Guards against accidental Gmail sends. Intercepts gws CLI calls that would send email and requires explicit confirmation. Prevents unintended outbound messages from automation.
Trigger: PreToolUse → Agent
Auto-generates .claude/agent-context/snapshot.md before every subagent spawn. Contains git branch, recent commits, working tree changes, and active tasks. Ensures every subagent has workspace awareness.
Trigger: PostToolUse → Edit | Write
Auto-formats files after every edit or write operation. Keeps code style consistent without manual intervention. Runs via Bun for speed.
Trigger: SessionStart
Synchronizes plugin state at session start. Ensures all Claude Code plugins and their skills are available and up-to-date before work begins.
All external services (DiscoLike, Supabase, LeadMagic, Google Drive) accessed via CLI or Python SDK — not MCP. Only AutoContext runs as MCP for codebase intelligence.
SubagentStop hook on campaign-doctor agent auto-logs session completions to leadgrow-hq/automation/logs/agents/. Provides audit trail for autonomous agent runs.
Stages raise CheckpointPending (exit code 5) when human judgment needed. Operator edits the surfaced file (YAML/CSV/JSON), then runs gtm-orchestrator resume. Partial resolution valid — unfilled rows re-surface. 6 checkpoint locations: enrich, segment, copy, QA, inboxes, launch gate.
Before pipeline starts: validates 15 GitHub labels exist in the repo + Supabase namespace is bootstrapped. Blocks the run if missing — prevents mid-pipeline failures from infrastructure gaps.
--dry-run simulates all Bison calls with synthetic IDs and skips gate 9g. Use for testing pipeline wiring end-to-end without touching production systems or requiring human confirmation.
Brief is frozen at campaign init. Since v4.0, copy (_copy.json) is generated at briefing time by the campaign-copywriting skill and included in the frozen brief. Stage 7 (Apply) deterministically renders variables — no LLM calls at runtime for copy.
Every LLM call via tracked_run auto-increments the cost accumulator. gtm-orchestrator status shows per-stage + grand total. Langfuse provides span-level detail but cost_accumulator remains the billing source of truth.
SQLite per campaign is the source of truth. Google Sheets is the human-readable mirror (visibility window). GitHub Issues track per-stage lifecycle via label state machine. Supabase stores cross-campaign enrichment data.
public schema for the operator dashboard. Per-client table isolation via table_prefix. Swallows all exceptions — logs warning, returns None.
leadgrow_knowledge schema for cross-campaign intelligence. Retries failed writes via queue (not swallow-only). Auto-reconnects on stale connections for 60min+ pipeline runs.
Derived from CANONICAL_STAGE_NAMES at runtime. Sub-stages grouped: 02a/02b/02c/02.5 → stage:normalize, 04b/04c → stage:people, 07b → stage:copy. Plus 5 status labels. Pre-flight validates all labels exist before first run.
Every issue carries exactly 3 labels:
stage:qualify — which pipeline stage
status:running — current lifecycle state
campaign:rbs-mca-v1 — which campaign
PATCH-based atomic transitions swap all 3 at once.
When a stage raises CheckpointPending, the adapter posts a comment with: the file to edit, the action to take, and the resume command. Operator gets notified via GitHub, edits the file, resumes.
One parent issue per campaign tracks the full run. Includes client, campaign slug, list source, segments. Checkpoint comments accumulate as the pipeline hits pause points. Closed at launch. Sidecar file (.github_issue) ensures idempotency.
GitHub Projects board turns issues into a sortable, filterable table. Each row = one pipeline stage for one campaign. Columns show status labels as colored badges. Filter by campaign:slug to see one campaign's progress, or by status:checkpoint to see all blocked stages across all campaigns.
All active campaigns with status, lead count, cost, and last activity. Server-rendered with ISR (60s revalidation). Data sourced from Google Sheets CAMPAIGN_SPREADSHEET_MAP env var.
Per-campaign stage table — each of 19 stages shows row count, status (complete/idle), and timing. GitHub Issues panel surfaces open checkpoints that need operator action.
gtm-orchestrator run <campaign_dir>
Starts or resumes from last completed stage. Add --dry-run to simulate Bison calls.
gtm-orchestrator resume <campaign_dir>
Edit the checkpoint file, then resume. Partial resolution OK.
gtm-orchestrator status <campaign_dir>
Per-stage progress + token/cost totals.
gtm-orchestrator score-replies <campaign_dir>
Post-launch: classify replies into 9 categories. SHA-256 dedup.