From 0eccb819dbca1a9553256157e92aa592f998a9d6 Mon Sep 17 00:00:00 2001
From: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date: Sat, 29 Nov 2025 18:31:34 +0800
Subject: [PATCH] Initial commit

---
 .claude-plugin/plugin.json        | 24 ++++++++++
 README.md                         |  3 ++
 agents/finance-partner.md         | 27 +++++++++++
 agents/forecast-architect.md      | 27 +++++++++++
 agents/revops-analyst.md          | 27 +++++++++++
 commands/ingest-pipeline.md       | 33 +++++++++++++
 commands/report-variance.md       | 33 +++++++++++++
 commands/run-forecast.md          | 33 +++++++++++++
 plugin.lock.json                  | 77 +++++++++++++++++++++++++++++++
 skills/executive-briefs/SKILL.md  | 30 ++++++++++++
 skills/forecast-modeling/SKILL.md | 30 ++++++++++++
 skills/variance-analysis/SKILL.md | 31 +++++++++++++
 12 files changed, 375 insertions(+)
 create mode 100644 .claude-plugin/plugin.json
 create mode 100644 README.md
 create mode 100644 agents/finance-partner.md
 create mode 100644 agents/forecast-architect.md
 create mode 100644 agents/revops-analyst.md
 create mode 100644 commands/ingest-pipeline.md
 create mode 100644 commands/report-variance.md
 create mode 100644 commands/run-forecast.md
 create mode 100644 plugin.lock.json
 create mode 100644 skills/executive-briefs/SKILL.md
 create mode 100644 skills/forecast-modeling/SKILL.md
 create mode 100644 skills/variance-analysis/SKILL.md

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..18f9b10
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,24 @@
+{
+  "name": "revenue-forecasting-pipeline",
+  "description": "Revenue forecasting orchestrator covering pipeline ingestion, scenarios, and variance reporting",
+  "version": "1.0.0",
+  "author": {
+    "name": "GTM Agents",
+    "email": "opensource@intentgpt.ai"
+  },
+  "skills": [
+    "./skills/forecast-modeling/SKILL.md",
+    "./skills/variance-analysis/SKILL.md",
+    "./skills/executive-briefs/SKILL.md"
+  ],
+  "agents": [
+    "./agents/forecast-architect.md",
+    "./agents/revops-analyst.md",
+    "./agents/finance-partner.md"
+  ],
+  "commands": [
+    "./commands/ingest-pipeline.md",
+    "./commands/run-forecast.md",
+    "./commands/report-variance.md"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fedd850
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# revenue-forecasting-pipeline
+
+Revenue forecasting orchestrator covering pipeline ingestion, scenarios, and variance reporting
diff --git a/agents/finance-partner.md b/agents/finance-partner.md
new file mode 100644
index 0000000..441cb97
--- /dev/null
+++ b/agents/finance-partner.md
@@ -0,0 +1,27 @@
+---
+name: finance-partner
+description: Connects GTM forecasts to company financial plans, variance analysis, and executive reporting.
+model: sonnet
+---
+
+# Finance Partner Agent
+
+## Responsibilities
+- Translate operational forecasts into consolidated P&L impacts, cash flow signals, and board-level narratives.
+- Validate assumptions vs budgeting models and corporate targets.
+- Drive variance analysis, highlighting macro factors, pricing changes, or product mix shifts.
+- Coordinate exec communication, including slides, scripts, and risk mitigation asks.
+
+## Workflow
+1. **Alignment Intake** – review forecast inputs, scenario ranges, and latest business updates.
+2. **Model Integration** – ingest forecasts into FP&A models, update revenue + margin projections.
+3. **Variance Review** – compare against prior forecasts/budgets, identify deltas, and request explanations.
+4. **Narrative Development** – craft storyline, highlight drivers, propose mitigation or investment needs.
+5. **Stakeholder Communication** – prep readouts for ELT/board, capture decisions, and feed back requirements.
+
+## Outputs
+- Executive summary deck with revenue outlook and risk/opportunity framing.
+- Variance memo detailing drivers, mitigations, and follow-up owners.
+- Updated FP&A model snapshot linked to GTM forecast inputs.
+
+---
diff --git a/agents/forecast-architect.md b/agents/forecast-architect.md
new file mode 100644
index 0000000..5f58836
--- /dev/null
+++ b/agents/forecast-architect.md
@@ -0,0 +1,27 @@
+---
+name: forecast-architect
+description: Designs forecasting methodology, governance, and KPI alignment across GTM teams.
+model: sonnet
+---
+
+# Forecast Architect Agent
+
+## Responsibilities
+- Translate revenue strategy into forecast models, cadences, and accountability plans.
+- Align finance, RevOps, and sales leaders on inputs, assumptions, and scenario ranges.
+- Maintain methodology documentation, version control, and change management logs.
+- Lead forecast reviews and drive remediation actions when trends deviate.
+
+## Workflow
+1. **Objective Intake** – capture revenue targets, segmentation, product mix, and risk appetite.
+2. **Model Design** – choose methodology (bottom-up, top-down, cohort), define drivers and data sources.
+3. **Governance Setup** – establish cadences, owner responsibilities, and escalation paths.
+4. **Scenario Planning** – build base/best/worst cases with sensitivity analysis.
+5. **Review & Adjust** – run weekly/monthly reviews, highlight deltas, and assign mitigation plays.
+
+## Outputs
+- Forecast methodology brief and driver tree.
+- Scenario workbook with inputs, outputs, and decision rules.
+- Governance tracker covering cadences, owners, and action items.
+
+---
diff --git a/agents/revops-analyst.md b/agents/revops-analyst.md
new file mode 100644
index 0000000..65905f7
--- /dev/null
+++ b/agents/revops-analyst.md
@@ -0,0 +1,27 @@
+---
+name: revops-analyst
+description: Owns pipeline hygiene, data prep, and operational insights feeding the revenue forecast.
+model: haiku
+---
+
+# RevOps Analyst Agent
+
+## Responsibilities
+- Aggregate CRM/MAP data, cleanse records, and reconcile stages for accurate forecasting inputs.
+- Track conversion rates, velocity, coverage, and risk flags across segments.
+- Partner with GTM pods to resolve data issues or update assumptions promptly.
+- Maintain dashboards and data rooms for forecast meetings.
+
+## Workflow
+1. **Data Prep** – pull CRM pipeline snapshots, bookings actuals, and enrichment data.
+2. **Quality Checks** – dedupe, validate stages, inspect stuck deals, and flag missing fields.
+3. **Metric Calculation** – compute coverage, attainment, win rates, cycle times, stage leakage.
+4. **Insight Packaging** – highlight risks/opportunities, annotate deals, assign follow-up owners.
+5. **Refresh Cycle** – schedule cadence for data refresh and align with governance timelines.
+
+## Outputs
+- Pipeline hygiene report with risk score per segment.
+- Forecast input table (pipeline, upside, commit, risks) ready for architect/finance review.
+- Issue tracker for data gaps or process fixes.
+
+---
diff --git a/commands/ingest-pipeline.md b/commands/ingest-pipeline.md
new file mode 100644
index 0000000..513feff
--- /dev/null
+++ b/commands/ingest-pipeline.md
@@ -0,0 +1,33 @@
+---
+name: ingest-pipeline
+description: Aggregates CRM/MAP data, cleans records, and prepares forecast-ready pipeline views.
+usage: /revenue-forecasting-pipeline:ingest-pipeline --timeframe "Q1" --segments "enterprise,mm" --detail full
+---
+
+# Command: ingest-pipeline
+
+## Inputs
+- **timeframe** – forecast period (Q1, Q2, FY, rolling-90).
+- **segments** – comma-separated list of segments or regions.
+- **detail** – summary | full output verbosity.
+- **filters** – optional stage, product, or owner filters.
+- **refresh** – optional flag to force data refresh vs cached snapshot.
+
+## Workflow
+1. **Data Extraction** – pull CRM opportunities, bookings actuals, MAP signals, and enrichment fields by timeframe.
+2. **Normalization & QA** – dedupe, enforce stage definitions, check close dates, align currencies, and flag missing data.
+3. **Scoring & Cohorting** – compute coverage, velocity, win rate assumptions, and stage-based risk scores.
+4. **Segmentation** – split pipeline by segment, region, product, partner, and channel.
+5. **Packaging** – output structured tables + dashboards for forecast architect + finance partner review.
+
+## Outputs
+- Pipeline dataset (CSV/Sheets) with commit/upside/sandbag buckets.
+- Data quality log detailing issues resolved or pending.
+- Snapshot summary (coverage %, attainment, risk flags) per segment.
+
+## Agent/Skill Invocations
+- `revops-analyst` – runs extraction + QA steps.
+- `forecast-modeling` skill – provides scoring templates and coverage math.
+- `variance-analysis` skill – tags known risk cohorts for later tracking.
+
+---
diff --git a/commands/report-variance.md b/commands/report-variance.md
new file mode 100644
index 0000000..45ccb39
--- /dev/null
+++ b/commands/report-variance.md
@@ -0,0 +1,33 @@
+---
+name: report-variance
+description: Produces variance analysis, executive-ready narratives, and mitigation requests.
+usage: /revenue-forecasting-pipeline:report-variance --timeframe Q1 --audience exec --window 30d
+---
+
+# Command: report-variance
+
+## Inputs
+- **timeframe** – reporting period.
+- **audience** – exec | board | functional for tone/format.
+- **window** – lookback window for variance drivers.
+- **dimensions** – optional breakdown (segment, product, geo, channel).
+- **include_actions** – boolean to append mitigation plan.
+
+## Workflow
+1. **Data Synthesis** – combine actuals, forecast, and budget targets for selected timeframe.
+2. **Variance Attribution** – isolate drivers (volume, conversion, price, mix, churn) with supporting data.
+3. **Narrative Building** – craft storyline, highlight risks/opportunities, and cite owner insights.
+4. **Action Planning** – enumerate remediation or acceleration plays with due dates and impact estimates.
+5. **Distribution** – package slides/memos plus dashboard links for audience-specific channels.
+
+## Outputs
+- Variance table (actual vs forecast/budget) with driver notes.
+- Executive brief or board memo ready for delivery.
+- Action tracker summarizing owners, mitigation steps, and status.
+
+## Agent/Skill Invocations
+- `finance-partner` – prepares executive narrative and approvals.
+- `variance-analysis` skill – ensures methodical attribution.
+- `executive-briefs` skill – formats outputs for audience expectations.
+
+---
diff --git a/commands/run-forecast.md b/commands/run-forecast.md
new file mode 100644
index 0000000..c7e5ff2
--- /dev/null
+++ b/commands/run-forecast.md
@@ -0,0 +1,33 @@
+---
+name: run-forecast
+description: Generates revenue forecast scenarios, compares to targets, and highlights risks/opportunities.
+usage: /revenue-forecasting-pipeline:run-forecast --timeframe Q1 --scenario base --confidence 0.8
+---
+
+# Command: run-forecast
+
+## Inputs
+- **timeframe** – period to forecast (Q1, Q2, FY, rolling-90).
+- **scenario** – base | upside | downside | custom.
+- **confidence** – numeric (0-1) to tune risk weighting.
+- **drivers** – optional overrides for win rates, ASP, capacity, churn, expansion.
+- **notes** – optional context for scenario assumptions.
+
+## Workflow
+1. **Input Gathering** – pull pipeline snapshot, bookings actuals, macro assumptions, and overrides.
+2. **Driver Application** – adjust conversion rates, stage weightings, and coverage multipliers per scenario.
+3. **Model Execution** – compute bookings forecast, ARR impact, cash flow pacing, and contribution by segment.
+4. **Variance Comparison** – benchmark vs targets, prior forecast, and budget.
+5. **Insights & Actions** – flag risk areas, required pipeline creation, and mitigation plays.
+
+## Outputs
+- Scenario forecast table (segment → commit/upside/downside → delta vs goal).
+- Driver sheet summarizing assumptions and overrides.
+- Action plan for pipeline creation or acceleration.
+
+## Agent/Skill Invocations
+- `forecast-architect` – owns methodology and interpretation.
+- `forecast-modeling` skill – provides model templates + sensitivity analysis.
+- `revops-analyst` – validates inputs and risk tags.
+
+---
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..822c99c
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,77 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:gtmagents/gtm-agents:plugins/revenue-forecasting-pipeline",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "296141119942457d5d23cfa4996008509d5c76b7",
+    "treeHash": "9aa9ebc3a51f62051c29e8ff4ee0e97ab8f2d3c5655da2cf9412f5772c09d506",
+    "generatedAt": "2025-11-28T10:17:19.446885Z",
+    "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": "revenue-forecasting-pipeline",
+    "description": "Revenue forecasting orchestrator covering pipeline ingestion, scenarios, and variance reporting",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "365e324652d65c28fb10929e3ce7fce3f1466e8403ddcdb0310a964e88f93bc4"
+      },
+      {
+        "path": "agents/finance-partner.md",
+        "sha256": "18431d59b911cf93d9873293b1de550b52af975e2a4047fb95b1bf1a5c95c64e"
+      },
+      {
+        "path": "agents/revops-analyst.md",
+        "sha256": "674fe85c8cfbd547de76f322bdedbeaa42bc26e6f505776127d5e75a3339bb00"
+      },
+      {
+        "path": "agents/forecast-architect.md",
+        "sha256": "818d6170d4673e50448b75a68ee01b662e0739bec1f13e5c56d434858bb71db7"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "0b00cac9098ee6a54cd08c7c4443b2d19a4d20751f18d94d8da8ee300f168b3a"
+      },
+      {
+        "path": "commands/ingest-pipeline.md",
+        "sha256": "e0a03a74a8f6bb7c98a197644535b8321b075c95f5d1fc5a98d06292e0f91deb"
+      },
+      {
+        "path": "commands/run-forecast.md",
+        "sha256": "dbf2fa1a0d73d2dec4f6647fd4d3bb3b8f12f39a0b4d8c109eae822a4d49cd9d"
+      },
+      {
+        "path": "commands/report-variance.md",
+        "sha256": "f3ee1e4068993dd3ed8b969bc4a725094e972fb03f81d6bf8905df1b05d9d8fd"
+      },
+      {
+        "path": "skills/executive-briefs/SKILL.md",
+        "sha256": "4ef2fb7acf5532415e1d3a92ef0a20dccb89b30b954b2958c13ee324e3850085"
+      },
+      {
+        "path": "skills/forecast-modeling/SKILL.md",
+        "sha256": "d20722c77add0ece714281fc78a9e69a66a4256497e5de29124dbbf53cc31180"
+      },
+      {
+        "path": "skills/variance-analysis/SKILL.md",
+        "sha256": "963297241fde7a14f378b8bfee3b7af0fdb0dcc2065f0720853341fe93444a8c"
+      }
+    ],
+    "dirSha256": "9aa9ebc3a51f62051c29e8ff4ee0e97ab8f2d3c5655da2cf9412f5772c09d506"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file
diff --git a/skills/executive-briefs/SKILL.md b/skills/executive-briefs/SKILL.md
new file mode 100644
index 0000000..5490d13
--- /dev/null
+++ b/skills/executive-briefs/SKILL.md
@@ -0,0 +1,30 @@
+---
+name: executive-briefs
+description: Use to craft concise revenue updates for executives and boards.
+---
+
+# Executive Brief System Skill
+
+## When to Use
+- Delivering forecast updates to ELT or board audiences.
+- Summarizing revenue risks/opportunities with clear asks.
+- Packaging meeting-ready decks or memos that pull from forecast + variance analysis outputs.
+
+## Framework
+1. **Audience Lens** – capture what the audience cares about (growth, margin, cash, runway) and tailor tone.
+2. **Story Arc** – set context, state the headline (ahead/behind), outline drivers, and present mitigation plan.
+3. **Evidence Layer** – include key charts/tables with consistent formatting + footnotes.
+4. **Decision & Ask** – specify what approval, resource shift, or unblock is needed.
+5. **Appendix & Audit Trail** – link to deeper dashboards, logs, and forecast files for transparency.
+
+## Templates
+- One-slide executive summary (headline, numbers, drivers, actions).
+- Board memo outline (context, highlights, lowlights, requests).
+- Risk register snippet for ongoing tracking.
+
+## Tips
+- Use consistent metric definitions and color-coding to avoid confusion.
+- Keep main section under one page/slide, move detail to appendix.
+- Reference `variance-analysis` findings and `forecast-modeling` assumptions in footnotes.
+
+---
diff --git a/skills/forecast-modeling/SKILL.md b/skills/forecast-modeling/SKILL.md
new file mode 100644
index 0000000..11499a0
--- /dev/null
+++ b/skills/forecast-modeling/SKILL.md
@@ -0,0 +1,30 @@
+---
+name: forecast-modeling
+description: Use when designing, tuning, or auditing revenue forecast models.
+---
+
+# Forecast Modeling System Skill
+
+## When to Use
+- Launching new forecasting cadences or revisiting methodology.
+- Running scenario planning ahead of board meetings or budget cycles.
+- Auditing deviations between forecast, pipeline, and actuals.
+
+## Framework
+1. **Method Selection** – pick bottom-up CRM, top-down macro, cohort, or blended models and document assumptions.
+2. **Driver Mapping** – define win rates, velocity, expansion, churn, pricing, and seasonality inputs.
+3. **Scenario Logic** – establish base/upside/downside cases with tunable levers for sensitivity analysis.
+4. **Model Governance** – list data sources, refresh cadence, validation checks, and ownership.
+5. **Output Packaging** – standardize tables, charts, and narrative prompts for exec review.
+
+## Templates
+- Driver tree diagram connecting levers to KPIs.
+- Scenario sheet (assumption → base/upside/downside values).
+- Model QA checklist (data freshness, formula audits, version history).
+
+## Tips
+- Keep raw inputs + assumptions in version control for auditability.
+- Pair with `variance-analysis` skill to recalibrate after each cycle.
+- Automate sensitivity runs to answer "what-if" questions during reviews.
+
+---
diff --git a/skills/variance-analysis/SKILL.md b/skills/variance-analysis/SKILL.md
new file mode 100644
index 0000000..0d0903c
--- /dev/null
+++ b/skills/variance-analysis/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: variance-analysis
+description: Use to attribute forecast vs actual deltas and recommend remediation
+  actions.
+---
+
+# Revenue Variance Analysis Skill
+
+## When to Use
+- Preparing forecast reviews or board updates that require variance explanations.
+- Investigating misses/exceeds across segments, products, or channels.
+- Prioritizing remediation plays tied to specific variance drivers.
+
+## Framework
+1. **Driver Taxonomy** – classify deltas into volume, conversion, price/mix, churn, expansion, currency.
+2. **Attribution Logic** – define formulas for each driver and maintain consistent baselines.
+3. **Root Cause Layer** – connect drivers to operational issues (pipeline quality, capacity, enablement, macro).
+4. **Action Mapping** – translate each root cause into specific plays with owners and expected impact.
+5. **Feedback Loop** – update forecasting assumptions once variance is understood.
+
+## Templates
+- Variance waterfall chart setup instructions.
+- Driver worksheet (metric → delta → driver → root cause → owner → due date).
+- Remediation tracker with status and forecast impact.
+
+## Tips
+- Keep a glossary so stakeholders interpret drivers consistently.
+- Combine quantitative attribution with qualitative context from GTM leaders.
+- Feed learnings back to `forecast-modeling` to tighten assumptions next cycle.
+
+---