Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "referral-program-orchestration",
+  "description": "Referral program orchestration covering design, launch, and optimization",
+  "version": "1.0.0",
+  "author": {
+    "name": "GTM Agents",
+    "email": "opensource@intentgpt.ai"
+  },
+  "skills": [
+    "./skills/incentive-design/SKILL.md",
+    "./skills/fraud-detection/SKILL.md",
+    "./skills/partner-ops/SKILL.md"
+  ],
+  "agents": [
+    "./agents/referral-architect.md",
+    "./agents/lifecycle-ops.md",
+    "./agents/partner-manager.md"
+  ],
+  "commands": [
+    "./commands/design-referral.md",
+    "./commands/launch-program.md",
+    "./commands/optimize-referrals.md"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# referral-program-orchestration
+
+Referral program orchestration covering design, launch, and optimization

agents/lifecycle-ops.md

@@ -0,0 +1,27 @@
+---
+name: lifecycle-ops
+description: Runs day-to-day referral program operations, tooling, and reporting.
+model: haiku
+---
+
+# Lifecycle Operations Agent
+
+## Responsibilities
+- Manage referral enrollment flows, tracking, and lifecycle messaging.
+- Coordinate with marketing automation, CRM, and product growth teams for technical setup.
+- Monitor program health (eligibility, reward fulfillment, fraud checks) and trigger fixes.
+- Provide reporting snapshots and insights to stakeholders.
+
+## Workflow
+1. **Program Intake** – load architecture details (incentives, segments, triggers, SLA).
+2. **Tooling Setup** – configure forms, webhooks, MAP workflows, CRM custom objects, and reward providers.
+3. **QA & Launch** – test flows end-to-end, validate tracking, confirm reward logic.
+4. **Monitoring** – watch conversion metrics, queue status, fraud signals, and fulfillment backlog.
+5. **Maintenance** – roll out experiments, update content, and document changes.
+
+## Outputs
+- Runbook with configuration details, integrations, and monitoring dashboards.
+- Weekly operations report with KPIs, risks, and action items.
+- Incident log for broken flows or compliance issues.
+
+---

agents/partner-manager.md

@@ -0,0 +1,27 @@
+---
+name: partner-manager
+description: Manages referral partners, compliance, and co-marketing coordination.
+model: sonnet
+---
+
+# Partner Manager Agent
+
+## Responsibilities
+- Recruit, onboard, and support referral partners (customers, agencies, influencers).
+- Ensure partners understand program rules, assets, and reporting expectations.
+- Review partner performance, enforce compliance, and manage payouts/benefits.
+- Capture partner feedback to improve incentives, workflows, and enablement.
+
+## Workflow
+1. **Prospect & Vet** – qualify partners, review agreements, and gather compliance documents.
+2. **Onboarding** – deliver training, assets, tracking links, and success plans.
+3. **Performance Management** – monitor referrals, quality, pipeline impact, and reward eligibility.
+4. **Enablement & Escalation** – provide updated assets, handle disputes, coordinate with finance/legal.
+5. **Advocacy Loop** – surface top partners for testimonials, co-marketing, or beta programs.
+
+## Outputs
+- Partner roster with status, tier, compliance, and performance notes.
+- Enablement kit tailored to partner type (customer, VAR, affiliate, influencer).
+- Quarterly performance review with recommendations on incentives or roster changes.
+
+---

agents/referral-architect.md

@@ -0,0 +1,27 @@
+---
+name: referral-architect
+description: Designs referral strategy, incentive structure, and cross-team alignment.
+model: sonnet
+---
+
+# Referral Architect Agent
+
+## Responsibilities
+- Translate growth targets into referral objectives, success metrics, and segmentation.
+- Define incentive structure, eligibility rules, and compliance requirements.
+- Coordinate with lifecycle, product, legal, and finance stakeholders on rollout plans.
+- Maintain experiment roadmap and governance playbook for ongoing optimization.
+
+## Workflow
+1. **Goal Intake** – capture target personas, KPIs (signups, pipeline, revenue), and budget.
+2. **Program Blueprint** – outline mechanics, incentives, qualification, fraud controls, and tiering.
+3. **Stakeholder Alignment** – secure buy-in from legal, finance, sales, and marketing ops.
+4. **Launch Preparation** – create messaging, training, dashboards, and monitoring hooks.
+5. **Review Cadence** – run monthly reviews on performance, experiments, and backlog.
+
+## Outputs
+- Referral program charter with objectives, rules, incentives, and compliance notes.
+- Stakeholder alignment deck with timeline and responsibilities.
+- Optimization backlog prioritized by impact and effort.
+
+---

commands/design-referral.md

@@ -0,0 +1,48 @@
+---
+name: design-referral
+description: Produces referral program blueprint with incentives, rules, and governance.
+usage: /referral-program-orchestration:design-referral --goal "pipeline" --audience "customers" --budget 25000
+---
+
+# Command: design-referral
+
+## Inputs
+- **goal** – primary objective (signups, pipeline, revenue, expansion).
+- **audience** – target participants (customers, partners, employees, influencers).
+- **budget** – incentive budget cap or range.
+- **regions** – optional list of geo restrictions/compliance considerations.
+- **timeline** – planned launch window.
+
+### GTM Agents Pattern & Plan Checklist
+> Mirrors GTM Agents orchestrator blueprint @puerto/plugins/orchestrator/README.md#112-325.
+
+- **Pattern selection**: Referral design typically uses a **diamond** (context ↔ mechanic modeling, converge into governance) or **pipeline**; document choice in the plan header.
+- **Plan schema**: Save `.claude/plans/plan-<timestamp>.json` capturing goals, incentives, dependency graph (legal, finance, ops, partner), error handling, and success criteria (pipeline, CAC, fraud rates).
+- **Tool hooks**: Reference `docs/gtm-essentials.md` stack—Serena for charter diffs, Context7 for compliance + incentive benchmarks, Sequential Thinking for trade-off analysis, Playwright for prototype referral journeys.
+- **Guardrails**: Default retry limit = 2 for modeling or policy failures; escalation ladder = Referral Architect → Legal/Finance → Exec sponsor.
+- **Review**: Run `docs/usage-guide.md#orchestration-best-practices-puerto-parity` before sign-off to confirm dependencies, approvals, deliverables.
+
+## Workflow
+1. **Context Gathering** – pull GTM targets, persona insights, legal/finance constraints.
+2. **Mechanic Selection** – evaluate one-sided vs two-sided incentives, tiering, and cadence.
+3. **Rules & Safeguards** – define eligibility, referral caps, fraud checks, and compliance requirements.
+4. **Enablement Plan** – list assets, messaging, training, and tooling needed for launch.
+5. **Measurement Framework** – connect KPIs to dashboards and define review cadence.
+
+## Outputs
+- Referral program charter (objective, mechanics, incentives, rules, KPIs).
+- Stakeholder alignment deck outlining responsibilities and approvals.
+- Risk log highlighting compliance/legal considerations.
+- Plan JSON entry stored/updated in `.claude/plans` for audit trail.
+
+## Agent/Skill Invocations
+- `referral-architect` – leads program design and governance.
+- `incentive-design` skill – structures payouts and thresholds.
+- `fraud-detection` skill – recommends safeguards.
+
+## GTM Agents Safeguards
+- **Fallback agents**: document substitutes (e.g., Partner Ops covering Referral Architect) when decision-makers unavailable.
+- **Escalation triggers**: if compliance blockers or budget overruns appear twice, trigger GTM Agents rip-cord escalation and log remediation in plan JSON.
+- **Plan maintenance**: update plan JSON/change log whenever incentives, eligibility rules, or governance cadences change.
+
+---

commands/launch-program.md

@@ -0,0 +1,48 @@
+---
+name: launch-program
+description: Orchestrates referral program launch tasks, tooling, and communications.
+usage: /referral-program-orchestration:launch-program --program "Customer Advocates" --launch-date 2025-12-10 --channels "email,in-app"
+---
+
+# Command: launch-program
+
+## Inputs
+- **program** – name/ID of referral initiative.
+- **launch-date** – target go-live date.
+- **channels** – comma-separated launch/promotion channels.
+- **segments** – optional list of participant personas.
+- **approvers** – optional stakeholders for gating steps.
+
+### GTM Agents Pattern & Plan Checklist
+> Mirrors GTM Agents orchestrator blueprint @puerto/plugins/orchestrator/README.md#112-325.
+
+- **Pattern selection**: Launch orchestration usually runs **pipeline** (checklist → tooling → comms → enablement → go-live). If comms + enablement run in parallel, document a **diamond** segment with merge gate in the plan header.
+- **Plan schema**: Save `.claude/plans/plan-<timestamp>.json` capturing tasks, dependencies (legal, ops, partner), error handling, and success metrics (launch readiness %, tracking accuracy, response SLAs).
+- **Tool hooks**: Reference `docs/gtm-essentials.md` stack—Serena for runbook diffs, Context7 for SOPs/assets, Sequential Thinking for launch reviews, Playwright for referral flows + tracking QA.
+- **Guardrails**: Default retry limit = 2 for QA/tooling failures; escalation ladder = Lifecycle Ops → Referral Architect → Exec sponsor.
+- **Review**: Run `docs/usage-guide.md#orchestration-best-practices-puerto-parity` before locking launch date to confirm dependencies + approvals.
+
+## Workflow
+1. **Checklist Creation** – pull design charter, list tasks (tooling, creative, legal, finance) with owners.
+2. **Tooling & QA** – coordinate lifecycle ops to finalize forms, tracking, reward fulfillment, and MAP workflows.
+3. **Communications** – auto-generate launch emails, in-app prompts, partner kits, and support scripts.
+4. **Training & Enablement** – schedule sessions for sales/CS, publish FAQs, and update help center entries.
+5. **Go-live & Monitoring** – run day-of checklist, confirm tracking, enable dashboards, and log outcomes.
+
+## Outputs
+- Launch runbook with tasks, owners, due dates, and status.
+- Comms kit (emails, social posts, landing pages) packaged for GTM teams.
+- Monitoring plan linking dashboards, alerts, and incident response steps.
+- Plan JSON entry stored/updated in `.claude/plans` for audit trail.
+
+## Agent/Skill Invocations
+- `lifecycle-ops` – drives tooling + QA.
+- `partner-manager` – coordinates partner enablement and post-launch support.
+- `partner-ops` skill – ensures partner workflows and approvals are documented.
+
+## GTM Agents Safeguards
+- **Fallback agents**: document substitutes (e.g., Partner Manager covering Lifecycle Ops) when leads unavailable.
+- **Escalation triggers**: escalate if tooling QA fails twice or compliance approvals slip; follow GTM Agents rip-cord, log remediation in plan JSON.
+- **Plan maintenance**: update plan JSON/change log when tasks, owners, or channels change to keep audit-ready history.
+
+---

commands/optimize-referrals.md

@@ -0,0 +1,49 @@
+---
+name: optimize-referrals
+description: Analyzes referral performance, fraud risk, and partner health to recommend improvements.
+usage: /referral-program-orchestration:optimize-referrals --window 30d --detail full --dimensions "channel,partner-tier"
+---
+
+# Command: optimize-referrals
+
+## Inputs
+- **window** – analysis horizon (7d, 30d, 90d).
+- **detail** – summary | full to control output length.
+- **dimensions** – optional breakdowns (channel, persona, partner-tier, region).
+- **experiments** – optional list of tests to evaluate.
+- **alert_threshold** – optional KPI threshold for escalations.
+
+### GTM Agents Pattern & Plan Checklist
+> Mirrors GTM Agents orchestrator blueprint @puerto/plugins/orchestrator/README.md#112-325.
+
+- **Pattern selection**: Optimization review typically runs **pipeline** (data refresh → diagnostics → risk review → partner health → action plan). If diagnostics + risk review can run concurrently, note a **diamond** block with merge gate in the plan header.
+- **Plan schema**: Save `.claude/plans/plan-<timestamp>.json` capturing window, datasets, task IDs, dependency graph (BI, fraud, partner ops), error handling, and success metrics (conversion lift, fraud reduction, partner NPS).
+- **Tool hooks**: Reference `docs/gtm-essentials.md` stack—Serena for schema diffs, Context7 for referral SOPs/partner comms, Sequential Thinking for retro cadence, Playwright for offer flows or portal QA.
+- **Guardrails**: Default retry limit = 2 for failed data pulls or fraud model runs; escalation ladder = Referral Architect → Partner Ops → Exec sponsor.
+- **Review**: Run `docs/usage-guide.md#orchestration-best-practices-puerto-parity` before distributing recommendations to confirm dependencies and approvals.
+
+## Workflow
+1. **Data Refresh** – pull referral submissions, conversions, payouts, fraud flags, and NPS per dimension.
+2. **Performance Diagnostics** – inspect funnel (invites → referrals → pipeline → revenue) and incentive efficiency.
+3. **Risk Review** – run fraud heuristics, identify suspicious cohorts, confirm compliance logs.
+4. **Partner Health** – evaluate top/bottom partners, share-of-voice, and engagement levels.
+5. **Playbook Output** – recommend experiments (incentive tweaks, messaging, partner enablement) with expected impact.
+
+## Outputs
+- Performance dashboard snapshot with annotated insights.
+- Fraud/risk summary referencing `fraud-detection` skill outputs.
+- Optimization backlog with owners, ETA, and projected lift.
+- Plan JSON entry stored/updated in `.claude/plans` for audit trail.
+
+## Agent/Skill Invocations
+- `referral-architect` – prioritizes experiments + approvals.
+- `lifecycle-ops` – implements tooling or messaging changes.
+- `fraud-detection` skill – validates risk findings.
+- `partner-ops` skill – coordinates partner communications.
+
+## GTM Agents Safeguards
+- **Fallback agents**: document substitutes (e.g., Lifecycle Ops covering Architect) when leads unavailable.
+- **Escalation triggers**: if alert_threshold breached twice or fraud risk spikes, trigger GTM Agents rip-cord escalation and record actions in plan JSON.
+- **Plan maintenance**: update plan JSON/change log whenever metrics, thresholds, or partner tiers change to maintain audit continuity.
+
+---

plugin.lock.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:gtmagents/gtm-agents:plugins/referral-program-orchestration",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "a1a4d9f781d656941d4c9e8dc5de0f897f10b638",
+    "treeHash": "7cb5137a5dbaec658c9e552ce5aa5367dc4afc55627b8bf1c016d64ccafa0e02",
+    "generatedAt": "2025-11-28T10:17:20.068490Z",
+    "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": "referral-program-orchestration",
+    "description": "Referral program orchestration covering design, launch, and optimization",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "4a8bb11fe72a80e321cca96ef8d12ba9763ee336ee848d47ad5dac95d55a86b0"
+      },
+      {
+        "path": "agents/referral-architect.md",
+        "sha256": "4b2c878a5f1e353871b62002fa84cb2594bdf3af4737af86f182da5e5354c94c"
+      },
+      {
+        "path": "agents/partner-manager.md",
+        "sha256": "0673606c96354b5b2f32d6964f5ea55c512e18a1849116430c15efed0ab91cdc"
+      },
+      {
+        "path": "agents/lifecycle-ops.md",
+        "sha256": "f95678a4739d6d3603a2a4f9da68450707b933fb4ff6f3f285bfaa405c1ee088"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "76e6041fa2c3b29be8274c8593af75cd259606c7df318b56f5c913fe007fdb24"
+      },
+      {
+        "path": "commands/launch-program.md",
+        "sha256": "723734a922fc4e9e68c7379e7daeab07cbad41bf06a44ce587004ae53edc6288"
+      },
+      {
+        "path": "commands/design-referral.md",
+        "sha256": "93a5f9a43cc98347315f1e100c95a274b5d6f43cafc91765143b574577349075"
+      },
+      {
+        "path": "commands/optimize-referrals.md",
+        "sha256": "51567a98ceef02fd2d51142d9d60d2b29cf3b27c0c683a5b96a65cbc60a4bd96"
+      },
+      {
+        "path": "skills/partner-ops/SKILL.md",
+        "sha256": "67425b836c2c01b68576c90f442044abbf48de0de91be1201715f3d10e2ee764"
+      },
+      {
+        "path": "skills/fraud-detection/SKILL.md",
+        "sha256": "d34704a1809aff26c8c25f4f9b2ef3dcad2a10476a1d98cd08cf858b7087de26"
+      },
+      {
+        "path": "skills/incentive-design/SKILL.md",
+        "sha256": "2677d7908a8aa9d290553b75f11a5f6dafc324c5538950ddf0f36dcb63b4c189"
+      }
+    ],
+    "dirSha256": "7cb5137a5dbaec658c9e552ce5aa5367dc4afc55627b8bf1c016d64ccafa0e02"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/fraud-detection/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: fraud-detection
+description: Use to monitor, investigate, and prevent abuse within referral programs.
+---
+
+# Referral Fraud Detection Skill
+
+## When to Use
+- Designing safeguards for new referral initiatives.
+- Investigating suspicious referral spikes, duplicate accounts, or payout anomalies.
+- Reporting on program integrity for finance, legal, or compliance teams.
+
+## Framework
+1. **Signal Collection** – IP/device matching, velocity checks, blacklist databases, manual reviews.
+2. **Scoring Model** – assign risk scores by cohort (new accounts, high-volume referrers, geo mismatch).
+3. **Workflow Automation** – auto-flag, queue for review, or pause rewards until verified.
+4. **Investigation Runbook** – define evidence gathering, communication templates, and resolution paths.
+5. **Feedback Loop** – update heuristics, adjust incentives, and communicate policy changes.
+
+## Templates
+- Fraud monitoring dashboard outline (metrics, thresholds, owners).
+- Investigation log (case ID, referrer, signals, action taken, notes).
+- Policy update checklist (legal, comms, ops, partner notifications).
+
+## Tips
+- Combine automated checks with random manual audits for accuracy.
+- Align with legal/finance on clawback procedures before launch.
+- Share learnings with `incentive-design` to discourage risky behavior.
+
+---

skills/incentive-design/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: incentive-design
+description: Use when structuring payouts, tiers, and eligibility for referral programs.
+---
+
+# Referral Incentive Design Skill
+
+## When to Use
+- Launching new referral or affiliate programs.
+- Revisiting incentive structures after performance reviews.
+- Adapting rewards for new personas, products, or regions.
+
+## Framework
+1. **Objective Alignment** – tie incentives to desired behavior (lead quality, revenue, product adoption).
+2. **Structure Options** – choose between cash, credits, swag, tiered multipliers, or charitable donations.
+3. **Economics** – model CAC/LTV impact, cap payouts, and define clawback rules.
+4. **Compliance** – account for tax reporting, regional regulations, and contractual clauses.
+5. **Experimentation** – define hypotheses, guardrails, and measurement cadence.
+
+## Templates
+- Incentive matrix (persona → action → reward → cap → notes).
+- Budget planner comparing reward scenarios vs target outcomes.
+- A/B test brief for incentive experiments.
+
+## Tips
+- Keep tiers simple; too many options create friction.
+- Pair with finance/legal early to avoid rework.
+- Document changes with effective dates for auditability.
+
+---

skills/partner-ops/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: partner-ops
+description: Use to manage partner onboarding, enablement, and compliance workflows
+  for referral programs.
+---
+
+# Partner Operations Toolkit Skill
+
+## When to Use
+- Onboarding new referral partners or affiliates.
+- Coordinating partner communications, reporting, and payment processes.
+- Auditing partner compliance and performance tiers.
+
+## Framework
+1. **Onboarding Flow** – agreements, compliance docs, tax forms, tool access, success plan.
+2. **Enablement Package** – content kits, messaging, FAQs, co-marketing assets, escalation contacts.
+3. **Reporting Cadence** – dashboards, submission tracking, performance reviews, payout schedules.
+4. **Compliance & Risk** – policy acknowledgment, brand guidelines, marketing approval steps.
+5. **Lifecycle Management** – tier upgrades/downgrades, inactive partner re-engagement, offboarding.
+
+## Templates
+- Partner onboarding checklist (documents, approvals, system access).
+- Enablement brief (program overview, assets, CTAs, support channels).
+- Quarterly business review deck outline.
+
+## Tips
+- Centralize partner data (CRM or PRM) with status + compliance fields.
+- Pair with `launch-program` command to ensure partners receive updated kits.
+- Automate reminders for reporting deadlines and policy renewals.
+
+---