100xprism 2.3.1

package/modules/push/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: push
+description: Quality gate re-runs before pushing. **Do NOT push if any gate fails.**
+category: lifecycle
+tier: core
+slash_command: /push
+---
+
+# Push — Gate → Push → Monitor CI/CD
+
+Quality gate re-runs before pushing. **Do NOT push if any gate fails.**
+
+## Do NOT ask for permission. Do NOT use `--no-verify` or `--force`.
+
+---
+
+## Phase 0 — Quality Gate (MANDATORY)
+
+Check gate cache first — skip if it already passed for this exact tree state. The cache
+is keyed on a tree token (HEAD + tracked diff + untracked files), not a bare HEAD, so a
+dirty or rebased tree never reuses a stale pass — the same token `/commit` writes and the
+`gate-on-commit` hook checks:
+
+```bash
+TOKEN=$(python3 ~/100xprism/hooks/gate-pass.py --print 2>/dev/null)
+CACHED=$(cat ~/.100xprism/gate-cache 2>/dev/null)
+[ -n "$TOKEN" ] && [ "$CACHED" = "$TOKEN" ] && echo "Gate: skipped (already passed for this tree)" && GATE_DONE=true || GATE_DONE=false
+```
+
+If `GATE_DONE=false`: run the **gate** workflow. On pass, record it:
+```bash
+python3 ~/100xprism/hooks/gate-pass.py
+```
+
+Do NOT push until gate passes. If gate fails → STOP, fix, clear cache, new commit, re-run.
+
+---
+
+## Phase 0b — Code Review (pre-push)
+
+Check review cache — skip if HEAD already reviewed by a prior `/commit` run:
+
+```bash
+HEAD=$(git rev-parse HEAD)
+REVIEWED=$(cat ~/.100xprism/review-cache 2>/dev/null)
+[ "$REVIEWED" = "$HEAD" ] && echo "Review: skipped (already done for $HEAD)" && REVIEW_DONE=true || REVIEW_DONE=false
+```
+
+If `REVIEW_DONE=false`, review unpushed commits now:
+
+```bash
+PR=$(gh pr list --head "$(git branch --show-current)" --json number -q '.[0].number' 2>/dev/null)
+```
+
+- **PR exists** → run the **code-review** skill: `/review $PR`
+- **No PR** → spawn **one** review Agent on `git diff origin/main..HEAD` covering the five dimensions defined in the **commit** skill Phase 5 (bugs, security, architecture, design, CLAUDE.md). Single-pass — no separate agents per dimension.
+
+On clean review:
+```bash
+echo "$HEAD" > ~/.100xprism/review-cache
+```
+
+**Critical or High issues** → fix, new commit, clear cache, re-run gate. Do NOT push.
+**Minor issues** → logged, non-blocking.
+
+---
+
+## Phase 1 — Push
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+cd "$PROJECT_ROOT"
+git push origin main
+```
+
+Let any pre-push hooks run. **Never bypass with `--no-verify`.**
+
+---
+
+## Phase 2 — Handle pre-push hook failures
+
+If the hook fails:
+1. Read the failure output carefully
+2. Fix the root cause — never bypass
+3. Create a **NEW commit** with the fix (never `--amend` over a pushed commit)
+4. Re-run the **gate** workflow to confirm fixes pass
+5. Push again
+
+If push is rejected (non-fast-forward):
+```bash
+git pull --rebase origin main
+git push origin main
+```
+
+---
+
+## Phase 3 — Monitor GitHub Actions & Auto-Fix
+
+```bash
+gh run list --limit 3
+RUN_ID=$(gh run list --limit 1 --json databaseId -q '.[0].databaseId')
+gh run watch "$RUN_ID"
+```
+
+No timeout — watch until CI completes or fails.
+
+### If CI passes → continue to Phase 4.
+
+### If CI fails → Auto-fix loop (max 3 attempts)
+
+```bash
+gh run view "$RUN_ID" --log | tail -100
+```
+
+Read the failure logs and classify the error:
+
+**Auto-fixable failures (language-agnostic):**
+
+| Failure type | Detection signals | Fix strategy |
+|:-------------|:------------------|:-------------|
+| Lint/format | ESLint, Prettier, ruff, black, gofmt, rustfmt, checkstyle, rubocop, swiftlint, ktlint | Run the **lint** workflow, commit fixes |
+| Type errors | TypeScript (`tsc`), mypy, pyright, Go compiler, Rust compiler (`rustc`), Java (`javac`), Kotlin | Read errors, fix types, commit |
+| Test failures | Jest, Vitest, pytest, Go test, cargo test, JUnit, RSpec, PHPUnit, XCTest, ExUnit | Read failing test, fix test or code, commit |
+| Dependency issues | npm/yarn/pnpm lockfile, pip requirements, go.mod, Cargo.lock, Maven/Gradle, Bundler, Composer | Install/update deps, commit lockfile |
+| Build failures | webpack, vite, esbuild, Go build, cargo build, Maven/Gradle build, make, CMake, Swift build | Read build errors, fix, commit |
+
+**Detection logic:**
+1. Read CI log output
+2. Identify the tool/framework from error signatures
+3. Match to the fix strategy above
+4. If no match → classify as unfamiliar → escalate
+
+**For each auto-fix attempt:**
+1. Apply the fix
+2. Create a new commit (never amend)
+3. Re-run the **gate** workflow
+4. Push again
+5. Monitor CI again
+
+```
+CI FAILED — Attempt N/3
+Failure:  [tool/framework] [error type]
+Fix:      [what was done]
+Action:   Committing fix, re-running gate, re-pushing...
+```
+
+**Unfamiliar failures (escalate to human after any attempt):**
+- Infrastructure errors (Docker build fails in CI but not locally)
+- Permission / secrets / environment variable errors
+- Timeout / flaky test patterns (same test passes locally)
+- Network connectivity issues
+- Unknown error codes or tools
+
+```
+╔══════════════════════════════════════════════════════╗
+║            CI FAILED — ESCALATING TO HUMAN            ║
+╠══════════════════════════════════════════════════════╣
+║ Attempts:   N/3 exhausted (or unfamiliar failure)    ║
+║ Last error: [error summary]                          ║
+║ Diagnosis:  [root cause analysis]                    ║
+║ Suggestion: [recommended fix]                        ║
+╠══════════════════════════════════════════════════════╣
+║ This requires human judgment. Auto-fix not possible.  ║
+╚══════════════════════════════════════════════════════╝
+```
+
+**After 3 failed auto-fix attempts → STOP. Report all attempted fixes and escalate.**
+
+---
+
+## Phase 4 — Production verification
+
+After all CI/CD workflows succeed:
+
+```bash
+# Detect project instruction file
+INSTRUCTION_FILE=$(for f in CLAUDE.md AGENTS.md .cursorrules .windsurfrules .github/copilot-instructions.md GEMINI.md; do [ -f "$PROJECT_ROOT/$f" ] && echo "$PROJECT_ROOT/$f" && break; done)
+```
+
+1. **Health checks** — read health endpoint URLs from the project instruction file or README. Hit each and confirm HTTP 200:
+```bash
+[ -n "$INSTRUCTION_FILE" ] && grep -E "https?://[^ ]*/health" "$INSTRUCTION_FILE" 2>/dev/null | head -3
+# Also try common defaults:
+# /health, /healthz, /api/health, /status
+```
+
+Retry up to 5 times with 10-second intervals (deployment may still be rolling out).
+
+2. **Confirm deployment** — verify the deployed version matches the pushed commit if a version endpoint exists.
+
+---
+
+## Output
+
+```
+=== Push Complete ===
+Gate:     ✅ ALL GATES PASSED
+Push:     <branch> → origin/<branch> ✅
+CI/CD:    ✅ All workflows passed (N auto-fixes applied)
+Health:   ✅ All endpoints responding
+Status:   SHIPPED ✅
+```

package/modules/referral-program/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: referral-program
+description: "When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' 'partner program,' 'referral incentive,' 'how to get referrals,' 'customers referring customers,' or 'affiliate payout.' Use this whenever someone wants existing users or partners to bring in new customers. For launch-specific virality, see launch-strategy."
+category: marketing
+tier: on-demand
+---
+
+# Referral & Affiliate Programs
+
+You are an expert in viral growth and referral marketing. Your goal is to help design and optimize programs that turn customers into growth engines.
+
+## Before Starting
+
+**Check for product marketing context first:**
+If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Gather this context (ask if not provided):
+
+### 1. Program Type
+- Customer referral program, affiliate program, or both?
+- B2B or B2C?
+- What's the average customer LTV?
+- What's your current CAC from other channels?
+
+### 2. Current State
+- Existing referral/affiliate program?
+- Current referral rate (% who refer)?
+- What incentives have you tried?
+
+### 3. Product Fit
+- Is your product shareable?
+- Does it have network effects?
+- Do customers naturally talk about it?
+
+### 4. Resources
+- Tools/platforms you use or consider?
+- Budget for referral incentives?
+
+---
+
+## Referral vs. Affiliate
+
+### Customer Referral Programs
+
+**Best for:**
+- Existing customers recommending to their network
+- Products with natural word-of-mouth
+- Lower-ticket or self-serve products
+
+**Characteristics:**
+- Referrer is an existing customer
+- One-time or limited rewards
+- Higher trust, lower volume
+
+### Affiliate Programs
+
+**Best for:**
+- Reaching audiences you don't have access to
+- Content creators, influencers, bloggers
+- Higher-ticket products that justify commissions
+
+**Characteristics:**
+- Affiliates may not be customers
+- Ongoing commission relationship
+- Higher volume, variable trust
+
+---
+
+## Referral Program Design
+
+### The Referral Loop
+
+```
+Trigger Moment → Share Action → Convert Referred → Reward → (Loop)
+```
+
+### Step 1: Identify Trigger Moments
+
+**High-intent moments:**
+- Right after first "aha" moment
+- After achieving a milestone
+- After exceptional support
+- After renewing or upgrading
+
+### Step 2: Design Share Mechanism
+
+**Ranked by effectiveness:**
+1. In-product sharing (highest conversion)
+2. Personalized link
+3. Email invitation
+4. Social sharing
+5. Referral code (works offline)
+
+### Step 3: Choose Incentive Structure
+
+**Single-sided rewards** (referrer only): Simpler, works for high-value products
+
+**Double-sided rewards** (both parties): Higher conversion, win-win framing
+
+**Tiered rewards**: Gamifies referral process, increases engagement
+
+**For examples and incentive sizing**: See [references/program-examples.md](references/program-examples.md)
+
+---
+
+## Program Optimization
+
+### Improving Referral Rate
+
+**If few customers are referring:**
+- Ask at better moments
+- Simplify sharing process
+- Test different incentive types
+- Make referral prominent in product
+
+**If referrals aren't converting:**
+- Improve landing experience for referred users
+- Strengthen incentive for new users
+- Ensure referrer's endorsement is visible
+
+### A/B Tests to Run
+
+**Incentive tests:** Amount, type, single vs. double-sided, timing
+
+**Messaging tests:** Program description, CTA copy, landing page copy
+
+**Placement tests:** Where and when the referral prompt appears
+
+### Common Problems & Fixes
+
+| Problem | Fix |
+|---------|-----|
+| Low awareness | Add prominent in-app prompts |
+| Low share rate | Simplify to one click |
+| Low conversion | Optimize referred user experience |
+| Fraud/abuse | Add verification, limits |
+| One-time referrers | Add tiered/gamified rewards |
+
+---
+
+## Measuring Success
+
+### Key Metrics
+
+**Program health:**
+- Active referrers (referred someone in last 30 days)
+- Referral conversion rate
+- Rewards earned/paid
+
+**Business impact:**
+- % of new customers from referrals
+- CAC via referral vs. other channels
+- LTV of referred customers
+- Referral program ROI
+
+### Typical Findings
+
+- Referred customers have 16-25% higher LTV
+- Referred customers have 18-37% lower churn
+- Referred customers refer others at 2-3x rate
+
+---
+
+## Launch Checklist
+
+### Before Launch
+- [ ] Define program goals and success metrics
+- [ ] Design incentive structure
+- [ ] Build or configure referral tool
+- [ ] Create referral landing page
+- [ ] Set up tracking and attribution
+- [ ] Define fraud prevention rules
+- [ ] Create terms and conditions
+- [ ] Test complete referral flow
+
+### Launch
+- [ ] Announce to existing customers
+- [ ] Add in-app referral prompts
+- [ ] Update website with program details
+- [ ] Brief support team
+
+### Post-Launch (First 30 Days)
+- [ ] Review conversion funnel
+- [ ] Identify top referrers
+- [ ] Gather feedback
+- [ ] Fix friction points
+- [ ] Send reminder emails to non-referrers
+
+---
+
+## Email Sequences
+
+### Referral Program Launch
+
+```
+Subject: You can now earn [reward] for sharing [Product]
+
+We just launched our referral program!
+
+Share [Product] with friends and earn [reward] for each signup.
+They get [their reward] too.
+
+[Unique referral link]
+
+1. Share your link
+2. Friend signs up
+3. You both get [reward]
+```
+
+### Referral Nurture Sequence
+
+- Day 7: Remind about referral program
+- Day 30: "Know anyone who'd benefit?"
+- Day 60: Success story + referral prompt
+- After milestone: "You achieved [X]—know others who'd want this?"
+
+---
+
+## Affiliate Programs
+
+**For detailed affiliate program design, commission structures, recruitment, and tools**: See [references/affiliate-programs.md](references/affiliate-programs.md)
+
+---
+
+## Task-Specific Questions
+
+1. What type of program (referral, affiliate, or both)?
+2. What's your customer LTV and current CAC?
+3. Existing program or starting from scratch?
+4. What tools/platforms are you considering?
+5. What's your budget for rewards/commissions?
+6. Is your product naturally shareable?
+
+---
+
+## Tool Integrations
+
+For implementation, see the [tools registry](../../tools/REGISTRY.md). Key tools for referral programs:
+
+| Tool | Best For | Guide |
+|------|----------|-------|
+| **Rewardful** | Stripe-native affiliate programs | [rewardful.md](../../tools/integrations/rewardful.md) |
+| **Tolt** | SaaS affiliate programs | [tolt.md](../../tools/integrations/tolt.md) |
+| **Mention Me** | Enterprise referral programs | [mention-me.md](../../tools/integrations/mention-me.md) |
+| **Dub.co** | Link tracking and attribution | [dub-co.md](../../tools/integrations/dub-co.md) |
+| **Stripe** | Payment processing (for commission tracking) | [stripe.md](../../tools/integrations/stripe.md) |
+
+---
+
+## Related Skills
+
+- **launch-strategy**: For launching referral program effectively
+- **email-sequence**: For referral nurture campaigns
+- **marketing-psychology**: For understanding referral motivation
+- **analytics-tracking**: For tracking referral attribution

package/modules/referral-program/evals/evals.json

@@ -0,0 +1,89 @@
+{
+  "skill_name": "referral-program",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Help me design a referral program for our SaaS product. We're a $49/month project management tool with about 1,000 customers. We want to encourage word-of-mouth growth.",
+      "expected_output": "Should check for product-marketing-context.md first. Should distinguish between referral and affiliate programs (this is referral — existing customers referring peers). Should design the referral loop: trigger point (when to ask for referral), share mechanism (unique link, email invite, social share), conversion flow (what the referred person experiences), and reward structure. Should recommend incentive type: double-sided recommended (both referrer and referred get value). Should suggest specific incentives appropriate for $49/month SaaS (e.g., free month for both). Should include the launch checklist. Should recommend tool integrations (Rewardful, Tolt, etc.).",
+      "assertions": [
+        "Checks for product-marketing-context.md",
+        "Distinguishes referral from affiliate",
+        "Designs the referral loop (trigger, share, convert, reward)",
+        "Recommends double-sided incentive structure",
+        "Suggests specific incentives for the price point",
+        "Includes launch checklist",
+        "Recommends tool integrations"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "We have a referral program but only 5% of customers have ever referred someone. How do we increase participation?",
+      "expected_output": "Should apply the program optimization guidance. Should diagnose low participation: are customers aware of the program? Is the trigger point well-timed? Is the incentive compelling enough? Is sharing easy? Should recommend optimization tactics: better placement/visibility, timing referral asks at peak satisfaction moments, improving the incentive, simplifying the share mechanism, adding referral reminders in email and in-app. Should provide specific experiment ideas to test improvements.",
+      "assertions": [
+        "Applies program optimization guidance",
+        "Diagnoses potential causes of low participation",
+        "Checks awareness, timing, incentive, and friction",
+        "Recommends optimization tactics",
+        "Suggests timing referral asks at satisfaction moments",
+        "Provides experiment ideas"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "should we do referral or affiliate? we sell online courses for $199-499 and want to get other creators and influencers to promote us.",
+      "expected_output": "Should trigger on casual phrasing. Should apply the referral vs affiliate distinction clearly. For this use case (getting creators/influencers to promote), should recommend an affiliate program (not referral — affiliates are third-party promoters, not existing customers). Should apply the affiliate program section guidance: commission structure for digital products (typically 20-40% for courses), cookie duration, payout terms, affiliate onboarding. Should recommend affiliate platforms/tools appropriate for course creators.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Clearly distinguishes referral from affiliate",
+        "Recommends affiliate for this use case",
+        "Provides commission structure guidance for courses",
+        "Addresses cookie duration and payout terms",
+        "Recommends appropriate affiliate platforms"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "What incentive structure works best? We've been offering $10 off for referrers but it's not working. Our product is $29/month.",
+      "expected_output": "Should evaluate the current incentive: $10 off on a $29/month product is significant but only benefits the referrer (single-sided). Should recommend testing double-sided incentives (both parties get value). Should discuss incentive types: account credit, free months, feature upgrades, cash. Should apply the tiered incentive concept (increasing rewards for multiple referrals). Should provide specific alternative incentive structures to test. Should note that incentive alone may not be the problem — placement and timing matter too.",
+      "assertions": [
+        "Evaluates current incentive structure",
+        "Identifies as single-sided and recommends double-sided",
+        "Discusses multiple incentive types",
+        "Applies tiered incentive concept",
+        "Provides specific alternatives to test",
+        "Notes incentive may not be the only issue"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "How do we measure the success of our referral program? What metrics should we track?",
+      "expected_output": "Should apply the measuring success framework. Should define key metrics: participation rate (% of customers who refer), share rate (referrals sent per participant), conversion rate (referred visitors who become customers), viral coefficient (k-factor), customer acquisition cost via referral vs other channels, referred customer LTV vs organic customer LTV. Should recommend tracking tools and dashboards. Should provide benchmark ranges for each metric.",
+      "assertions": [
+        "Applies measuring success framework",
+        "Defines participation rate, share rate, conversion rate",
+        "Includes viral coefficient / k-factor",
+        "Compares referral CAC to other channels",
+        "Compares referred customer LTV to organic",
+        "Recommends tracking approach",
+        "Provides benchmark ranges"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Can you write the referral invitation emails? I need the email that goes out when someone shares their referral link.",
+      "expected_output": "Should recognize this overlaps with email writing. Should apply the referral email sequence section from the skill for referral-specific emails. However, for detailed email sequence design (multi-email nurture for referred users), should cross-reference the email-sequence skill. Should provide the referral invitation email but note that broader email sequence work is handled by email-sequence.",
+      "assertions": [
+        "Applies referral email section from the skill",
+        "Provides referral invitation email guidance",
+        "Cross-references email-sequence for broader email work",
+        "Provides specific referral email copy or template"
+      ],
+      "files": []
+    }
+  ]
+}