Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "marketing-analytics",
+  "description": "Cross-channel marketing KPI frameworks, pacing guardrails, and attribution governance",
+  "version": "1.0.0",
+  "author": {
+    "name": "GTM Agents",
+    "email": "opensource@intentgpt.ai"
+  },
+  "skills": [
+    "./skills/attribution-playbook/SKILL.md",
+    "./skills/roi-benchmark-library/SKILL.md",
+    "./skills/channel-pacing-guardrails/SKILL.md",
+    "./skills/exec-dashboard-blueprint/SKILL.md"
+  ],
+  "agents": [
+    "./agents/marketing-intelligence-lead.md",
+    "./agents/channel-performance-analyst.md",
+    "./agents/attribution-architect.md"
+  ],
+  "commands": [
+    "./commands/produce-campaign-report.md",
+    "./commands/monitor-channel-pacing.md",
+    "./commands/evaluate-attribution-models.md"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# marketing-analytics
+
+Cross-channel marketing KPI frameworks, pacing guardrails, and attribution governance

agents/attribution-architect.md

@@ -0,0 +1,27 @@
+---
+name: attribution-architect
+description: Designs and governs attribution models, data contracts, and executive reporting views.
+model: haiku
+---
+
+# Attribution Architect Agent
+
+## Responsibilities
+- Evaluate attribution methodologies (first/last, position-based, data-driven) against GTM use cases.
+- Maintain data contracts for UTMs, campaign metadata, and funnel mappings.
+- Run model comparisons, lift studies, and calibration routines.
+- Publish clear narratives for finance, marketing, and sales stakeholders.
+
+## Workflow
+1. **Use-Case Intake** – capture stakeholder questions, KPIs, and decision context.
+2. **Model Evaluation** – test multiple models vs historical performance.
+3. **Calibration & QA** – confirm data quality, dedupe overlap, and align funnel definitions.
+4. **Insight Packaging** – produce multi-layer reporting for ops + exec audiences.
+5. **Change Management** – document model updates, train teams, monitor adoption.
+
+## Outputs
+- Attribution methodology comparison deck.
+- Decision memos recommending model + rationale.
+- Implementation runbooks with QA + governance steps.
+
+---

agents/channel-performance-analyst.md

@@ -0,0 +1,27 @@
+---
+name: channel-performance-analyst
+description: Monitors channel-level performance, pacing, and optimization opportunities.
+model: sonnet
+---
+
+# Channel Performance Analyst Agent
+
+## Responsibilities
+- Build dashboards for channel KPIs (reach, CTR, CPL, pipeline, revenue).
+- Monitor pacing vs budget and highlight over/under-performing channels.
+- Run root-cause analyses on creative, audience, and placement performance.
+- Recommend reallocations, creative tests, and enablement actions.
+
+## Workflow
+1. **Data Intake** – sync paid, owned, and earned channel data with unified taxonomy.
+2. **Quality Checks** – validate UTMs, spend allocations, and attribution consistency.
+3. **Performance Diagnostics** – compare to benchmarks, cohorts, and guardrails.
+4. **Opportunity Identification** – surface quick wins, experiments, or rebalancing moves.
+5. **Enablement & Follow-up** – brief channel owners, document actions, track results.
+
+## Outputs
+- Channel scorecards with KPIs, benchmarks, and action items.
+- Pacing alerts with recommended reallocations.
+- Creative/test backlog prioritized by impact and urgency.
+
+---

agents/marketing-intelligence-lead.md

@@ -0,0 +1,29 @@
+---
+name: marketing-intelligence-lead
+description: Owns cross-channel marketing analytics strategy, instrumentation, and
+  reporting cadences.
+model: sonnet
+---
+
+
+# Marketing Intelligence Lead Agent
+
+## Responsibilities
+- Define KPI frameworks for awareness, demand, and lifecycle programs.
+- Align marketing, RevOps, and finance on attribution, pacing, and investment guardrails.
+- Maintain analytics roadmap, tooling, and governance documentation.
+- Translate insights into exec-ready recommendations and enablement resources.
+
+## Workflow
+1. **Metric Strategy** – map KPIs to funnel stages, personas, and investments.
+2. **Instrumentation Review** – ensure UTMs, tracking plans, and dashboards stay healthy.
+3. **Insight Sprints** – analyze performance trends, diagnose anomalies, and prioritize analyses.
+4. **Narrative Delivery** – package insights for ELT, marketing leadership, and partner teams.
+5. **Action Tracking** – log decisions, owners, and follow-up experiments or campaigns.
+
+## Outputs
+- KPI blueprint with definitions, formulas, and guardrails.
+- Executive summaries of marketing performance with actions/asks.
+- Analytics backlog with prioritized projects and dependencies.
+
+---

commands/evaluate-attribution-models.md

@@ -0,0 +1,34 @@
+---
+name: evaluate-attribution-models
+description: Compares attribution models, highlights trade-offs, and recommends rollout plans.
+usage: /marketing-analytics:evaluate-attribution-models --campaigns launch_q1,evergreen_abm --models first,last,position,data-driven --audience finance
+---
+
+# Command: evaluate-attribution-models
+
+## Inputs
+- **campaigns** – list of campaigns/programs to analyze.
+- **models** – attribution models to compare (first, last, linear, position, time-decay, data-driven).
+- **audience** – finance | marketing-lead | ops | exec.
+- **metrics** – choose KPIs (pipeline, revenue, CAC, payback, LTV, ROAS).
+- **confidence** – optional minimum data confidence threshold to highlight gaps.
+
+## Workflow
+1. **Data Preparation** – pull campaign performance, cost, and pipeline/revenue outcomes.
+2. **Model Execution** – run requested models, normalize windows, and apply weighting rules.
+3. **Sensitivity Analysis** – compare outcomes vs benchmarks, highlight variance drivers.
+4. **Narrative Assembly** – contextualize trade-offs, governance considerations, and risks.
+5. **Recommendation Engine** – propose primary model, fallback, and rollout/QA checklist.
+
+## Outputs
+- Attribution comparison deck/table with KPI deltas per model.
+- Recommendation memo with decision, rationale, and risk mitigations.
+- Rollout plan including QA steps, owner assignments, and monitoring hooks.
+
+## Agent/Skill Invocations
+- `attribution-architect` – leads methodology comparison.
+- `marketing-intelligence-lead` – ensures narrative + stakeholder alignment.
+- `attribution-playbook` skill – documents rules + templates.
+- `exec-dashboard-blueprint` skill – packages executive summary.
+
+---

commands/monitor-channel-pacing.md

@@ -0,0 +1,34 @@
+---
+name: monitor-channel-pacing
+description: Tracks spend, performance, and guardrails across paid and owned channels.
+usage: /marketing-analytics:monitor-channel-pacing --window month --channels paid_search,linkedin,display --alerts true
+---
+
+# Command: monitor-channel-pacing
+
+## Inputs
+- **window** – day | week | month | quarter | campaign.
+- **channels** – comma-separated list (paid_search, paid_social, display, events, content, email).
+- **budget** – optional target spend to compare pacing against.
+- **alerts** – true/false to include guardrail breach alerts.
+- **format** – dashboard | memo | slack.
+
+## Workflow
+1. **Spend & Performance Sync** – pull channel spend, impressions, clicks, CPL, pipeline, revenue.
+2. **Normalization** – convert currencies, align attribution windows, reconcile UTMs.
+3. **Guardrail Checks** – compare to CAC, CPL, payback, or custom thresholds.
+4. **Optimization Signals** – flag channels/assets needing creative refresh or budget shift.
+5. **Packaging & Alerts** – publish dashboard/memo and optional Slack digest for owners.
+
+## Outputs
+- Channel pacing dashboard with KPIs vs targets.
+- Alert summary for guardrail breaches + recommended actions.
+- Reallocation recommendations with projected impact.
+
+## Agent/Skill Invocations
+- `channel-performance-analyst` – leads pacing diagnostics.
+- `marketing-intelligence-lead` – confirms priorities + narratives.
+- `channel-pacing-guardrails` skill – enforces budget/efficiency thresholds.
+- `roi-benchmark-library` skill – supplies benchmarks for comparison.
+
+---

commands/produce-campaign-report.md

@@ -0,0 +1,35 @@
+---
+name: produce-campaign-report
+description: Generates cross-channel campaign performance report with insights and recommendations.
+usage: /marketing-analytics:produce-campaign-report --campaign "Spring Launch" --window 30d --audience exec
+---
+
+# Command: produce-campaign-report
+
+## Inputs
+- **campaign** – campaign/program identifier (matches MAP/CRM naming).
+- **window** – analysis window (7d, 30d, campaign, custom).
+- **audience** – exec | marketing-lead | channel-owner | async.
+- **metrics** – optional override list for KPIs to highlight.
+- **format** – deck | memo | dashboard | csv.
+
+## Workflow
+1. **Data Assembly** – join paid, owned, and earned channel data with CRM pipeline/revenue fields.
+2. **Attribution Layer** – apply default or requested model, annotate confidence and limitations.
+3. **Performance Story** – highlight wins, underperformance, and causal insights.
+4. **Action Plan** – recommend optimizations, tests, or budget shifts per channel/asset.
+5. **Packaging** – tailor to audience with visuals, narrative, and calls-to-action.
+
+## Outputs
+- Campaign performance package (deck/memo/dashboard) with KPIs, insights, and actions.
+- Attribution summary with model notes and sensitivity ranges.
+- Optimization plan with owners, due dates, and expected impact.
+
+## Agent/Skill Invocations
+- `marketing-intelligence-lead` – frames narrative + executive summary.
+- `channel-performance-analyst` – provides channel diagnostics and pacing alerts.
+- `attribution-architect` – validates attribution logic and caveats.
+- `attribution-playbook` skill – enforces methodology templates.
+- `exec-dashboard-blueprint` skill – packages outputs for leadership reviews.
+
+---

plugin.lock.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:gtmagents/gtm-agents:plugins/marketing-analytics",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "5cdfa46c93f7864a0d6731ca9ac4fc67edeca55b",
+    "treeHash": "ec8185255150c1f177066a296bf639510dc9b1ff297670b7afac8d1f7d17ed98",
+    "generatedAt": "2025-11-28T10:17:15.031875Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "marketing-analytics",
+    "description": "Cross-channel marketing KPI frameworks, pacing guardrails, and attribution governance",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "00116295cc0c399a65fdefca44b6718d82c5d7d5222d6601a2db0d080f3a873e"
+      },
+      {
+        "path": "agents/attribution-architect.md",
+        "sha256": "a59006a84a829e35662f7a254a206cab1042996db2ec229d64b51be5d13f3bda"
+      },
+      {
+        "path": "agents/channel-performance-analyst.md",
+        "sha256": "ff1e7412a428948c74acf8f6749c0b295f9a1874c5ffad0f7ff3a107d783067a"
+      },
+      {
+        "path": "agents/marketing-intelligence-lead.md",
+        "sha256": "9f5fb23b47eab7241c19c96fa75b0b071ed3d40c27a678e7ef385d4068bddd4f"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "8ce3c6e91bb29551fe25536d2bb3398e2472f8566be41666b7e34ce19acd2202"
+      },
+      {
+        "path": "commands/monitor-channel-pacing.md",
+        "sha256": "0c64defebe02ac6a712eb43673319ddebd0df0a67baf89f1b7a7d51a513d47a1"
+      },
+      {
+        "path": "commands/evaluate-attribution-models.md",
+        "sha256": "14dd2af1f86d79443fc1221719c18fa6abb8af21d511ba4ff221816cb01aa202"
+      },
+      {
+        "path": "commands/produce-campaign-report.md",
+        "sha256": "e1f8e4096f680ca56746acc6d4e601e49684023913850326c46d68d7801dc63c"
+      },
+      {
+        "path": "skills/exec-dashboard-blueprint/SKILL.md",
+        "sha256": "79f770cbd25c96a6d7f2a0baee1f2ca48d64fcd19a3439cc0e8b33ce689d8b78"
+      },
+      {
+        "path": "skills/channel-pacing-guardrails/SKILL.md",
+        "sha256": "0d482353dacad31bcf6a1283e094ab3a9156df265775ceb796f2a8d3c532eb82"
+      },
+      {
+        "path": "skills/roi-benchmark-library/SKILL.md",
+        "sha256": "61518e38a93fa2178aad5e7d787f2dcf542957802d62a52a7455a5027341ff7c"
+      },
+      {
+        "path": "skills/attribution-playbook/SKILL.md",
+        "sha256": "4ce577c7318118219230b7b52659a1f36996b15d50f79105a1851a5a0009b8b9"
+      }
+    ],
+    "dirSha256": "ec8185255150c1f177066a296bf639510dc9b1ff297670b7afac8d1f7d17ed98"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/attribution-playbook/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: attribution-playbook
+description: Standard operating guide for campaign tagging, attribution models, and
+  QA.
+---
+
+# Attribution Playbook Skill
+
+## When to Use
+- Standing up or refreshing attribution models across teams.
+- Training campaign owners on UTMs, tracking, and governance.
+- Running QA before/after changing attribution weights or tooling.
+
+## Framework
+1. **Taxonomy Rules** – channel, campaign, creative, and experiment naming standards.
+2. **Model Catalog** – when to use first/last/linear/position/data-driven with pros/cons.
+3. **Data Contracts** – required fields, systems of record, sync cadence.
+4. **QA Checklist** – sample records, dedupe logic, cross-tool reconciliation.
+5. **Change Management** – approval workflow, communications, and measurement of impact.
+
+## Templates
+- UTM builder + validation sheet.
+- Attribution model comparison matrix.
+- QA runbook for campaign launches and quarterly audits.
+
+## Tips
+- Keep a shared "gotchas" log for recurring tagging errors.
+- Align with finance on ROI/CAC definitions before rolling out model changes.
+- Pair with `evaluate-attribution-models` for decision-ready narratives.
+
+---

skills/channel-pacing-guardrails/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: channel-pacing-guardrails
+description: Guardrail framework for monitoring spend, efficiency, and CAC thresholds
+  by channel.
+---
+
+# Channel Pacing Guardrails Skill
+
+## When to Use
+- Reviewing weekly/monthly pacing to stay within spend and efficiency targets.
+- Triggering alerts when CPL/CAC/ROAS drift beyond tolerance.
+- Aligning finance + marketing on reallocation decisions.
+
+## Framework
+1. **Budget Bands** – define min/max pacing per channel, region, and campaign tier.
+2. **Efficiency Guardrails** – set CAC, CPL, ROAS, payback thresholds with warning/critical bands.
+3. **Alert Workflow** – specify channels, owners, escalation paths, and notification cadence.
+4. **Exception Policy** – document when overrides are allowed and approval requirements.
+5. **Post-Mortem Loop** – capture breaches, actions taken, and guardrail adjustments.
+
+## Templates
+- Guardrail matrix (channel x metric x threshold).
+- Alert playbook with messaging, owner, and resolution steps.
+- Reallocation recommendation sheet linking to finance approvals.
+
+## Tips
+- Sync guardrail metrics with `roi-benchmark-library` to keep thresholds grounded in data.
+- Tie alerts to `/marketing-analytics:monitor-channel-pacing` outputs for automation.
+- Include leading indicators (CTR, CPC) to catch issues before CAC blows up.
+
+---

skills/exec-dashboard-blueprint/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: exec-dashboard-blueprint
+description: Layout and storytelling guide for marketing analytics executive dashboards.
+---
+
+# Executive Dashboard Blueprint Skill
+
+## When to Use
+- Preparing ELT/board-ready snapshots of marketing performance.
+- Standardizing dashboard layout across BI, RevOps, and marketing teams.
+- Packaging insights from `/marketing-analytics` commands into clear narratives.
+
+## Framework
+1. **Story Arc** – headline → KPI spine → risks/opps → actions.
+2. **KPI Tiles** – awareness, demand, pipeline, revenue, efficiency metrics with traffic lights.
+3. **Drill Cards** – channel, campaign, and audience breakouts linking to deeper views.
+4. **Insight Callouts** – annotate anomalies, root causes, and required decisions.
+5. **Action Register** – owners, due dates, and follow-ups surfaced alongside metrics.
+
+## Templates
+- 3-slide deck structure (headline, KPIs, actions).
+- Dashboard wireframe with recommended chart types + layout.
+- Annotation checklist ensuring context + next steps accompany data.
+- **GTM Agents KPI Guardrail Sheet** – baseline vs target vs alert ranges for reach, pipeline, win rate, CAC payback @puerto/README.md#214-241.
+- **Measurement Spec** – metric definitions, filters, refresh cadence, owner column.
+- **Weekly Exec Packet** – combines dashboard screenshots, narrative summary, decision log (mirrors GTM Agents Data Analyst deliverable).
+
+## Tips
+- Limit each dashboard view to one primary objective to avoid overload.
+- Embed links back to commands (`produce-campaign-report`, `monitor-channel-pacing`) for drilldowns.
+- Archive monthly snapshots for trend storytelling.
+- Adopt GTM Agents cadence: Monday data QA, Tuesday ELT preview, Thursday exec meeting, Friday retro + action register updates.
+- Highlight which KPIs are within guardrail, trending to alert, or breaching (RAG) so leadership can react quickly.
+- Pair with `docs/gtm-essentials.md` tools: Context7 for latest GA4 docs, Serena for patching data models, Sequential Thinking for retro facilitation.
+
+## GTM Agents Dashboard Governance Overlay
+1. **Data QA Loop** – run freshness + anomaly checks before distributing (log results in audit trail).
+2. **Narrative Structure** – use Story Arc to link KPI shifts to drivers and required decisions.
+3. **Action Register** – every dashboard delivery must include owner, due date, and status for prescribed actions.
+4. **Escalation** – if guardrail breach persists >2 weeks, escalate to Chief Product Officer / Sales Director per GTM Agents governance.
+
+## KPI Guardrails (GTM Agents Reference)
+- Awareness (reach/impressions) ±8% window before alerting; >12% triggers campaign review.
+- Pipeline add ≥3x quota per quarter; warn at 2.5x.
+- Win rate ≥25% for in-quarter commit; escalate if <20%.
+- CAC payback ≤14 months; escalate if >16 months.
+
+## Weekly Exec Packet Outline
+```
+1. Headline + KPI spine (traffic lights per guardrail)
+2. Insights & Drivers – 3 bullets tying KPI movement to channels/programs
+3. Required Decisions – what leadership must approve/block
+4. Action Register – owner, due date, status
+5. Appendix – detailed drill cards + methodology
+```
+
+## Tool Hooks
+- **Context7** – fetch current platform docs (GA4, Salesforce) referenced in measurement specs.
+- **Serena** – update BI repo SQL notebooks or dbt models safely.
+- **Sequential Thinking** – facilitate monthly retros and architecture of dashboard iterations.
+- **Playwright** – capture dashboard screenshots or verify embedded web components before distribution.
+
+---

skills/roi-benchmark-library/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: roi-benchmark-library
+description: Reference benchmarks for CAC, CPL, ROAS, and payback across channels
+  and segments.
+---
+
+# ROI Benchmark Library Skill
+
+## When to Use
+- Comparing current performance vs historical or industry benchmarks.
+- Setting guardrails for budgeting, pacing, and campaign approvals.
+- Equipping finance/marketing leaders with realistic ROI expectations.
+
+## Framework
+1. **Benchmark Sources** – internal history, partner data, analyst reports, industry surveys.
+2. **Segmentation** – channel, region, persona, product, funnel stage.
+3. **Metric Definitions** – CAC, CPL, ROAS, payback, pipeline-to-spend, revenue-to-spend.
+4. **Update Cadence** – monthly for active channels, quarterly for strategic benchmarks.
+5. **Usage Guidance** – when to escalate variances, how to contextualize outliers.
+
+## Templates
+- Benchmark matrix (channel x metric x segment).
+- Variance alert sheet with thresholds + recommended actions.
+- Executive summary page for QBRs.
+
+## Tips
+- Normalize for currency changes and attribution windows before comparing.
+- Pair with `monitor-channel-pacing` to trigger alerts against guardrails.
+- Share benchmark deltas with channel owners to inform creative/test roadmaps.
+
+---