GTM Intelligence System

October 2, 2025 · View on GitHub

Multi-agent system with deterministic orchestration for analyzing CRM and web analytics data.

Key Innovation: Agent Manager

This system uses an Agent Manager that ensures deterministic, reproducible workflows. Every analysis follows the same pattern:

  1. User makes request → Agent Manager creates workflow plan
  2. Agent Manager provisions and chains specialized agents
  3. Each agent executes deterministic tasks
  4. Complete audit trail logged for reproducibility

Quick Start

One command to get started:

git clone <your-repo-url>
cd gtm-intelligence
./setup.sh

The setup script will:

  • ✅ Install Python 3.8+ (if not present)
  • ✅ Install Claude Code CLI (if not present)
  • ✅ Install all Python dependencies (pandas, duckdb, etc.)
  • ✅ Create directory structure
  • ✅ Generate sample data for demo
  • ✅ Launch Claude Code ready to use

Using Your Own Data

Replace the sample data files in data/ with your own:

  • data/hubspot_deals.csv - CRM deals and pipeline data
  • data/ga4_events.csv - Google Analytics 4 events
  • data/product_usage.csv - Product telemetry and usage metrics

Then ask Claude:

"Analyze high-intent leads from my Hubspot and GA4 data.
I need a daily digest for the sales team."

The Agent Manager will:

  • Create a workflow plan
  • Provision data-scientist → gtm-strategist → report-builder → provenance-auditor
  • Execute deterministically
  • Log complete audit trail

Agents

Orchestration Layer

  • agent-manager: Master orchestrator, always invoked first, ensures deterministic workflows

Specialist Agents

  • data-scientist: SQL/DuckDB analysis, scoring models, pattern detection, generates reusable Python scripts
  • gtm-strategist: Converts insights to sales actions and battle cards
  • hypothesis-analyst: Designs experiments and generates testable hypotheses
  • provenance-auditor: OSEMN audit trails for full transparency
  • report-builder: Formatted outputs (Slack, HTML, PDF, CSV)

Workflow Types

The Agent Manager recognizes these standard workflows:

1. High-Intent Lead Identification

Trigger: "find high-intent leads", "daily lead scoring" Chain: data-scientist → gtm-strategist → report-builder → provenance-auditor

2. Expansion Opportunity Analysis

Trigger: "expansion opportunities", "upsell analysis" Chain: data-scientist → hypothesis-analyst → gtm-strategist → report-builder → provenance-auditor

3. Experiment Design

Trigger: "design experiment", "A/B test", "test hypothesis" Chain: data-scientist → hypothesis-analyst → report-builder

4. Attribution Analysis

Trigger: "attribution", "channel performance" Chain: data-scientist → hypothesis-analyst → gtm-strategist → report-builder → provenance-auditor

5. Weekly Battle Plan

Trigger: "weekly plan", "battle plan" Chain: data-scientist → gtm-strategist → hypothesis-analyst → report-builder → provenance-auditor

Deterministic Execution

Every workflow:

  • Creates a plan in workflows/plan_*.json
  • Logs execution in workflows/execution_log_*.json
  • Produces timestamped outputs
  • Is fully reproducible

View workflow history:

python scripts/workflow_validator.py

Example Usage

Simple Request

"I need to identify our top expansion opportunities"

Agent Manager will:

  1. Plan: data-scientist (identify patterns) → hypothesis-analyst (suggest tests) → gtm-strategist (create playbooks) → report-builder (format outputs) → provenance-auditor (document)
  2. Execute each step with validation
  3. Provide final deliverables

Complex Request

"Design an experiment to test if personalized video outreach
improves demo-to-close rate for enterprise deals. Include
sample size calculation and implementation plan."

Agent Manager will:

  1. Plan: data-scientist (baseline metrics) → hypothesis-analyst (design experiment) → report-builder (create documentation)
  2. Execute with checkpoints
  3. Deliver experiment design doc

Script Generation Request

"Create a reusable Python script for scoring high-intent leads.
It should accept Hubspot and GA4 CSV files as inputs and generate
a scored lead list. Make it parameterized so the sales team can run it daily."

Agent Manager will:

  1. Invoke data-scientist to create scripts/score_high_intent_leads.py
  2. Generate CLI wrapper with argparse for easy execution
  3. Document usage and parameters
  4. Test the script with sample data

The team can then run:

python scripts/score_high_intent_leads.py \
  --hubspot data/hubspot_deals.csv \
  --ga4 data/ga4_events.csv \
  --output-dir outputs \
  --lookback-days 7

Outputs

Workflow Artifacts

  • workflows/plan_*.json - Execution plans
  • workflows/execution_log_*.json - Complete audit trails

Analysis Outputs

  • outputs/daily_digest_*.txt - Slack-ready top 10 lists
  • outputs/battle_plan_*.html - Weekly prioritized opportunities
  • outputs/executive_summary_*.md - Pipeline insights
  • outputs/provenance_report_*.html - Full audit trails
  • outputs/target_list_*.csv - CRM-importable lists
  • outputs/experiments/hypothesis_*.md - Test designs

Sharing & Contributing

This is an open-source project. To use or contribute:

For Users

git clone https://github.com/<your-username>/gtm-intelligence
cd gtm-intelligence
./setup.sh

For Contributors

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add amazing feature'
  4. Push to branch: git push origin feature/amazing-feature
  5. Open a Pull Request

License

MIT License - see LICENSE file for details

Workflow Monitoring

View workflow stats

python scripts/workflow_validator.py

Inspect specific workflow

cat workflows/execution_log_20241002_143022.json | jq

Check recent workflows

ls -lt workflows/

Development

Test workflow planning (dry run)

"Agent manager: Create a workflow plan for identifying high-intent leads,
but don't execute yet. Show me the plan."

Validate workflow determinism

Run same request twice, compare execution logs:

diff workflows/execution_log_A.json workflows/execution_log_B.json

Should show identical structure, only timestamps differ.

Troubleshooting

Workflow failed mid-execution

Check execution log for failure point:

cat workflows/execution_log_*.json | jq '.steps_executed[] | select(.status=="failed")'

Agent not being invoked

Agent Manager decides which agents to use. To force specific agent:

"Agent manager: Use the hypothesis-analyst agent to design this experiment"

Outputs not generated

Check execution log for validation failures:

cat workflows/execution_log_*.json | jq '.steps_executed[] | select(.validation_passed==false)'

Best Practices

  1. Always let Agent Manager orchestrate - Don't invoke specialist agents directly
  2. Be specific in requests - More detail = better workflow planning
  3. Review workflow plans - Before execution, check the plan makes sense
  4. Monitor execution logs - Track success rates and optimize
  5. Keep data current - Fresh exports = better insights

Documentation

  • README.md (this file) - Complete system documentation
  • EXAMPLES.md - 7 detailed usage examples with expected outputs
  • SCRIPT_GENERATION_GUIDE.md - How to generate reusable Python scripts

System Requirements

  • Python 3.8 or higher
  • Claude Code CLI
  • 2GB disk space for data and outputs