commit bb54e4824f80f486f7330c951372d76a385ee0f4 Author: Zhongwei Li Date: Sat Nov 29 18:31:27 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9f90411 --- /dev/null +++ b/.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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..7c66435 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# referral-program-orchestration + +Referral program orchestration covering design, launch, and optimization diff --git a/agents/lifecycle-ops.md b/agents/lifecycle-ops.md new file mode 100644 index 0000000..d00b04a --- /dev/null +++ b/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. + +--- diff --git a/agents/partner-manager.md b/agents/partner-manager.md new file mode 100644 index 0000000..691cdcc --- /dev/null +++ b/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. + +--- diff --git a/agents/referral-architect.md b/agents/referral-architect.md new file mode 100644 index 0000000..da2208f --- /dev/null +++ b/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. + +--- diff --git a/commands/design-referral.md b/commands/design-referral.md new file mode 100644 index 0000000..b6e9a82 --- /dev/null +++ b/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-.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. + +--- diff --git a/commands/launch-program.md b/commands/launch-program.md new file mode 100644 index 0000000..1ff5d6b --- /dev/null +++ b/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-.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. + +--- diff --git a/commands/optimize-referrals.md b/commands/optimize-referrals.md new file mode 100644 index 0000000..0d14d5c --- /dev/null +++ b/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-.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. + +--- diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..40ace29 --- /dev/null +++ b/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": [] + } +} \ No newline at end of file diff --git a/skills/fraud-detection/SKILL.md b/skills/fraud-detection/SKILL.md new file mode 100644 index 0000000..82c8498 --- /dev/null +++ b/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. + +--- diff --git a/skills/incentive-design/SKILL.md b/skills/incentive-design/SKILL.md new file mode 100644 index 0000000..ca974a9 --- /dev/null +++ b/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. + +--- diff --git a/skills/partner-ops/SKILL.md b/skills/partner-ops/SKILL.md new file mode 100644 index 0000000..dab74ae --- /dev/null +++ b/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. + +---