@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/referral-program/references/affiliate-programs.md

@@ -0,0 +1,163 @@
+# Affiliate Program Design
+
+Detailed guidance for building and managing affiliate programs.
+
+## Contents
+- Commission Structures
+- Cookie Duration
+- Affiliate Recruitment
+- Affiliate Enablement
+- Tools & Platforms (Referral Program Tools, Affiliate Program Tools, Choosing a Tool)
+- Fraud Prevention (Common Referral Fraud, Prevention Measures)
+
+## Commission Structures
+
+**Percentage of sale:**
+- Standard: 10-30% of first sale or first year
+- Works for: E-commerce, SaaS with clear pricing
+- Example: "Earn 25% of every sale you refer"
+
+**Flat fee per action:**
+- Standard: $5-500 depending on value
+- Works for: Lead gen, trials, freemium
+- Example: "$50 for every qualified demo"
+
+**Recurring commission:**
+- Standard: 10-25% of recurring revenue
+- Works for: Subscription products
+- Example: "20% of subscription for 12 months"
+
+**Tiered commission:**
+- Works for: Motivating high performers
+- Example: "20% for 1-10 sales, 25% for 11-25, 30% for 26+"
+
+---
+
+## Cookie Duration
+
+How long after click does affiliate get credit?
+
+| Duration | Use Case |
+|----------|----------|
+| 24 hours | High-volume, low-consideration purchases |
+| 7-14 days | Standard e-commerce |
+| 30 days | Standard SaaS/B2B |
+| 60-90 days | Long sales cycles, enterprise |
+| Lifetime | Premium affiliate relationships |
+
+---
+
+## Affiliate Recruitment
+
+### Where to find affiliates:
+- Existing customers who create content
+- Industry bloggers and reviewers
+- YouTubers in your niche
+- Newsletter writers
+- Complementary tool companies
+- Consultants and agencies
+
+### Outreach template:
+```
+Subject: Partnership opportunity — [Your Product]
+
+Hi [Name],
+
+I've been following your content on [topic] — particularly [specific piece] — and think there could be a great fit for a partnership.
+
+[Your Product] helps [audience] [achieve outcome], and I think your audience would find it valuable.
+
+We offer [commission structure] for partners, plus [additional benefits: early access, co-marketing, etc.].
+
+Would you be open to learning more?
+
+[Your name]
+```
+
+---
+
+## Affiliate Enablement
+
+Provide affiliates with:
+- [ ] Unique tracking links/codes
+- [ ] Product overview and key benefits
+- [ ] Target audience description
+- [ ] Comparison to competitors
+- [ ] Creative assets (logos, banners, images)
+- [ ] Sample copy and talking points
+- [ ] Case studies and testimonials
+- [ ] Demo access or free account
+- [ ] FAQ and objection handling
+- [ ] Payment terms and schedule
+
+---
+
+## Tools & Platforms
+
+### Referral Program Tools
+
+**Full-featured platforms:**
+- ReferralCandy — E-commerce focused
+- Ambassador — Enterprise referral programs
+- Friendbuy — E-commerce and subscription
+- GrowSurf — SaaS and tech companies
+- Mention Me — AI-powered referral marketing
+- Viral Loops — Template-based campaigns
+
+**Built-in options:**
+- Stripe (basic referral tracking)
+- Segment (tracking and analytics)
+
+### Affiliate Program Tools
+
+**Affiliate networks:**
+- ShareASale — Large merchant network
+- Impact — Enterprise partnerships
+- PartnerStack — SaaS focused
+- Tapfiliate — Simple SaaS affiliate tracking
+- FirstPromoter — SaaS affiliate management
+
+**Self-hosted:**
+- Rewardful — Stripe-integrated affiliates
+- Refersion — E-commerce affiliates
+
+### Choosing a Tool
+
+Consider:
+- Integration with your payment system
+- Fraud detection capabilities
+- Payout management
+- Reporting and analytics
+- Customization options
+- Price vs. program scale
+
+---
+
+## Fraud Prevention
+
+### Common Referral Fraud
+- Self-referrals (creating fake accounts)
+- Referral rings (groups referring each other)
+- Coupon sites posting referral codes
+- Fake email addresses
+- VPN/device spoofing
+
+### Prevention Measures
+
+**Technical:**
+- Email verification required
+- Device fingerprinting
+- IP address monitoring
+- Delayed reward payout (after activation)
+- Minimum activity threshold
+
+**Policy:**
+- Clear terms of service
+- Maximum referrals per period
+- Reward clawback for refunds/chargebacks
+- Manual review for suspicious patterns
+
+**Structural:**
+- Require referred user to take meaningful action
+- Cap lifetime rewards
+- Pay rewards in product credit (less attractive to fraudsters)

package/skills/referral-program/references/program-examples.md

@@ -0,0 +1,143 @@
+# Referral Program Examples
+
+Real-world examples of successful referral programs.
+
+## Contents
+- Dropbox (Classic)
+- Uber/Lyft
+- Morning Brew
+- Notion
+- Incentive Types Comparison
+- Incentive Sizing Framework
+- Viral Coefficient & Metrics (Key Metrics, Calculating Referral Program ROI)
+
+## Dropbox (Classic)
+
+**Program:** Give 500MB storage, get 500MB storage
+
+**Why it worked:**
+- Reward directly tied to product value
+- Low friction (just an email)
+- Both parties benefit equally
+- Gamified with progress tracking
+
+---
+
+## Uber/Lyft
+
+**Program:** Give $10 ride credit, get $10 when they ride
+
+**Why it worked:**
+- Immediate, clear value
+- Double-sided incentive
+- Easy to share (code/link)
+- Triggered at natural moments
+
+---
+
+## Morning Brew
+
+**Program:** Tiered rewards for subscriber referrals
+- 3 referrals: Newsletter stickers
+- 5 referrals: T-shirt
+- 10 referrals: Mug
+- 25 referrals: Hoodie
+
+**Why it worked:**
+- Gamification drives ongoing engagement
+- Physical rewards are shareable (more referrals)
+- Low cost relative to subscriber value
+- Built status/identity
+
+---
+
+## Notion
+
+**Program:** $10 credit per referral (education)
+
+**Why it worked:**
+- Targeted high-sharing audience (students)
+- Product naturally spreads in teams
+- Credit keeps users engaged
+
+---
+
+## Incentive Types Comparison
+
+| Type | Pros | Cons | Best For |
+|------|------|------|----------|
+| Cash/credit | Universally valued | Feels transactional | Marketplaces, fintech |
+| Product credit | Drives usage | Only valuable if they'll use it | SaaS, subscriptions |
+| Free months | Clear value | May attract freebie-seekers | Subscription products |
+| Feature unlock | Low cost to you | Only works for gated features | Freemium products |
+| Swag/gifts | Memorable, shareable | Logistics complexity | Brand-focused companies |
+| Charity donation | Feel-good | Lower personal motivation | Mission-driven brands |
+
+---
+
+## Incentive Sizing Framework
+
+**Calculate your maximum incentive:**
+```
+Max Referral Reward = (Customer LTV × Gross Margin) - Target CAC
+```
+
+**Example:**
+- LTV: $1,200
+- Gross margin: 70%
+- Target CAC: $200
+- Max reward: ($1,200 × 0.70) - $200 = $640
+
+**Typical referral rewards:**
+- B2C: $10-50 or 10-25% of first purchase
+- B2B SaaS: $50-500 or 1-3 months free
+- Enterprise: Higher, often custom
+
+---
+
+## Viral Coefficient & Metrics
+
+### Key Metrics
+
+**Viral coefficient (K-factor):**
+```
+K = Invitations × Conversion Rate
+
+K > 1 = Viral growth (each user brings more than 1 new user)
+K < 1 = Amplified growth (referrals supplement other acquisition)
+```
+
+**Example:**
+- Average customer sends 3 invitations
+- 15% of invitations convert
+- K = 3 × 0.15 = 0.45
+
+**Referral rate:**
+```
+Referral Rate = (Customers who refer) / (Total customers)
+```
+
+Benchmarks:
+- Good: 10-25% of customers refer
+- Great: 25-50%
+- Exceptional: 50%+
+
+**Referrals per referrer:**
+
+Benchmarks:
+- Average: 1-2 referrals per referrer
+- Good: 2-5
+- Exceptional: 5+
+
+### Calculating Referral Program ROI
+
+```
+Referral Program ROI = (Revenue from referred customers - Program costs) / Program costs
+
+Program costs = Rewards paid + Tool costs + Management time
+```
+
+**Track separately:**
+- Cost per referred customer (CAC via referral)
+- LTV of referred customers (often higher than average)
+- Payback period for referral rewards

package/skills/review-sites/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: review-sites
+description: "Claim and optimize brand profiles on review sites (G2, Capterra, Product Hunt, Sourceforge, etc.) that AI search engines use as trust signals."
+allowed-tools: []
+---
+
+# /review-sites — Review Site Optimization for AI Search
+
+AI search engines check review sites to determine if a product is real, credible, and widely used. G2, Capterra, Product Hunt, and similar platforms are among the highest-trust sources for AI engines building consensus about your brand. Being unlisted on these sites means AI engines can't verify you exist.
+
+This skill handles claiming profiles, optimizing them for AI citation, and building review velocity.
+
+For brand memory protocol, see /cmo [rules/brand-memory.md](../cmo/rules/brand-manager.md).
+
+## On Activation
+
+1. Read `brand/` directory: load `positioning.md`, `competitors.md`, `audience.md` if present.
+2. If `brand/marketing/seo/platform-presence.md` exists, load it — check current review site status.
+3. Show what loaded:
+   ```
+   Brand context loaded:
+   ├── Positioning         ✓/✗
+   ├── Competitors         ✓/✗
+   ├── Audience            ✓/✗
+   ├── Platform Presence   ✓/✗
+   ```
+4. Determine mode:
+   - **Full Setup** — Claim + optimize + review solicitation (default)
+   - **Claim Only** — Just claim profiles, no optimization or outreach
+   - **Review Sprint** — Profile exists, just need more reviews
+
+---
+
+## Phase 1: Claim Profiles
+
+### Priority Review Sites
+
+| Site | AI Citation Value | Claim Effort | Who Uses It |
+|------|------------------|-------------|-------------|
+| **G2** | Very High | 30 min | B2B buyers, all AI engines |
+| **Capterra** | High | 20 min | SMB software buyers |
+| **Product Hunt** | High | 30 min | Early adopters, tech audience |
+| **Sourceforge** | Medium | 15 min | Developer/technical audience |
+| **Trustpilot** | Medium | 15 min | Consumer-facing products |
+| **Software Advice** | Medium | 20 min | Enterprise software buyers |
+| **GetApp** | Medium | 15 min | Business app buyers |
+| **AlternativeTo** | Medium | 10 min | People searching for alternatives |
+| **SaaSworthy** | Low-Medium | 10 min | SaaS comparison shoppers |
+| **There's An AI For That** | High (for AI products) | 10 min | AI tool discovery |
+
+### Claiming Process (Per Site)
+
+For each site:
+
+1. **Search** for existing listing: `site:g2.com "{brand name}"` or search directly on the platform
+2. **If listing exists** — Claim it (verify ownership via email domain, LinkedIn, or phone)
+3. **If no listing** — Create one from scratch
+4. **Required info to prepare before starting:**
+   - Product name (exact spelling)
+   - One-sentence description (what it does, for who)
+   - 3-5 key features with brief descriptions
+   - Pricing model (free tier? starting price?)
+   - Product category/tags
+   - Logo (high-res PNG/SVG)
+   - 2-3 screenshots or product images
+   - Website URL
+   - Support/contact email
+   - Social media links
+   - Founded year
+   - Company size range
+   - Headquarters location
+
+### Profile Claiming Tracker
+
+Write to `brand/marketing/review-sites/profiles.md`:
+
+```yaml
+---
+brand: "{brand}"
+last_updated: "{YYYY-MM-DD}"
+profiles:
+  g2:
+    status: claimed
+    url: "https://g2.com/products/{brand}"
+    claimed_date: "{date}"
+    reviews: 0
+    rating: null
+  capterra:
+    status: claimed
+    url: "https://capterra.com/p/{brand}"
+    claimed_date: "{date}"
+    reviews: 0
+    rating: null
+  product_hunt:
+    status: not_listed
+    url: null
+    planned_launch: "{date or null}"
+```
+
+---
+
+## Phase 2: Optimize Profiles
+
+### Profile Optimization Checklist
+
+For each claimed profile, optimize these fields for AI citation:
+
+**Product Description:**
+- Lead with what the product IS and WHO it's for (one sentence)
+- Include the primary category keyword naturally
+- Mention the target audience explicitly
+- Example: "AIwithJai is an AI agent consulting service that helps small businesses automate workflows with custom AI employees, starting at $999."
+
+**Feature Descriptions:**
+- Each feature should answer: "What does this do?" and "Why does it matter?"
+- Use the language buyers search for (from `subreddit-pain-extraction` or keyword research)
+- Include specific numbers where possible
+
+**Category Selection:**
+- Pick the most specific category available (not the broadest)
+- If multiple categories are allowed, select all relevant ones
+- Categories determine which comparison pages you appear on
+
+**Pricing Information:**
+- Always include pricing. AI engines flag "contact for pricing" as a negative signal.
+- Be specific: "$999 one-time setup" beats "affordable pricing"
+- If you have a free tier, highlight it prominently
+
+**Screenshots:**
+- First screenshot should show the main value proposition visually
+- Include alt text / captions with keywords
+- 3-5 screenshots minimum
+
+**Tags/Keywords:**
+- Add all relevant tags the platform supports
+- Include competitor-adjacent tags (people searching for competitors find you)
+- Use the exact phrases buyers use (from pain point research)
+
+### Competitor Benchmarking
+
+For each review site, check what top competitors have:
+
+| Competitor | G2 Rating | # Reviews | Profile Strength | What they do well |
+|-----------|-----------|-----------|-----------------|-------------------|
+| {Comp 1} | 4.8 | 47 | Strong | Detailed feature breakdowns, video testimonials |
+| {Comp 2} | 4.5 | 23 | Moderate | Strong pricing transparency, case studies |
+
+Use this to set targets: "We need 20+ reviews to match competitor baseline."
+
+---
+
+## Phase 3: Review Solicitation
+
+### Review Sources (Priority Order)
+
+1. **Existing customers** — Highest quality, most credible. Email them directly.
+2. **Beta users / early adopters** — They have opinions. Channel them into reviews.
+3. **Free tier users** — Volume, even if shorter reviews. Helps with review count.
+4. **Partners / integrations** — Their perspective adds credibility.
+
+### Review Solicitation Email
+
+Use `send-email` skill to send individualized emails:
+
+```
+Subject: Quick favor — would you review us on G2?
+
+Hi {Name},
+
+You've been using {product} for {timeframe}, and I'd love to hear about
+your experience.
+
+If you have 5 minutes, would you leave an honest review on G2?
+It helps other {audience} find us — and we read every single one.
+
+{Direct link to G2 review page}
+
+No pressure at all. If you've got feedback that doesn't fit in a review,
+just reply to this email — I read everything.
+
+Thanks,
+{Name}
+{Title}, {Brand}
+```
+
+### Review Solicitation Rules
+
+1. **Ask for honest reviews, not positive reviews.** G2 and Capterra penalize incentivized reviews. A 4-star honest review is worth 10x a fake 5-star review.
+2. **Space out requests.** 2-3 review requests per week maximum. A burst of 20 reviews in 2 days triggers spam filters.
+3. **Make it easy.** Send a direct link to the review page. No login walls if possible.
+4. **Never offer incentives for positive reviews.** You can offer a small thank-you (coffee gift card) for any review regardless of rating, but tie it to the act of reviewing, not the star count.
+5. **Respond to every review.** Thank people for positive ones. Address concerns in negative ones professionally.
+6. **Target 10 reviews minimum** per platform. Below 10, the rating isn't statistically meaningful. Above 20, it starts influencing AI citation.
+
+### Review Response Templates
+
+**Positive review:**
+```
+Thanks for the kind words, {Name}! Glad {specific feature they mentioned}
+is working well for you. We're always improving — feel free to reach out
+if you need anything.
+```
+
+**Negative/constructive review:**
+```
+{Name}, thanks for the honest feedback. {Acknowledge their specific concern}.
+We're actively working on {related improvement}. Would you be open to a
+quick call so we can learn more? {contact email}
+```
+
+---
+
+## Phase 4: Ongoing Management
+
+### Monthly Review Health Check
+
+Add to the weekly cron or run manually monthly:
+
+1. **Review count** — Track growth. Target: 5+ new reviews per month.
+2. **Average rating** — Track trend. Below 4.0 needs attention.
+3. **Response rate** — Every review gets a response within 48 hours.
+4. **Competitor watch** — Are competitors gaining reviews faster?
+5. **New platform opportunities** — Any new review sites gaining traction?
+
+### Review Site SEO for AI Citation
+
+Review site profiles rank in search engines independently. Optimize for this:
+
+1. **Keep product descriptions updated** — Reflect current features and pricing
+2. **Add new screenshots quarterly** — Fresh media signals activity
+3. **Respond to reviews promptly** — Shows the brand is active and engaged
+4. **Link back to your site** — Most profiles allow a website link
+5. **Cross-link from your blog** — "Read our reviews on G2" posts drive traffic and authority
+
+---
+
+## Worked Example
+
+**User request:** "Set up review site profiles for aiwithjai"
+
+**Phase 1:** Search G2, Capterra, Product Hunt. None have aiwithjai listed. Create profiles on all three plus AlternativeTo and There's An AI For That.
+
+**Phase 2:** Optimize each profile with: "AIwithJai builds custom AI employees for small businesses — automating content, outreach, and operations starting at $999." Add 4 screenshots, 6 feature descriptions, pricing ($999 setup + monthly), category: "AI Agent Platforms".
+
+**Phase 3:** Email 12 existing customers asking for G2 reviews. Space 3 per week over 4 weeks. After 6 weeks: 8 reviews, 4.6 average rating.
+
+**Phase 4:** Monthly check — 8 reviews on G2, 3 on Capterra. AI visibility audit shows G2 profile starting to appear in AI search results for "AI agent consulting service."
+
+---
+
+## Chain Offers
+
+After completing, present:
+
+- `/ai-consensus-builder` — Feed review site presence into the overall consensus strategy
+- `/ai-visibility-audit` — Check if review profiles are getting cited by AI engines
+- `/send-email` — Send review solicitation emails to customers
+- "Schedule monthly review check" — Track review growth and respond to new reviews
+
+---
+
+## Anti-Patterns
+
+| Anti-pattern | Instead | Why |
+|-------------|---------|-----|
+| Buying fake reviews | Solicit honest reviews from real customers | G2 and Capterra have sophisticated fake review detection. Getting caught removes all reviews and bans the profile. |
+| Only creating G2 | Claim 5+ review sites | Different AI engines pull from different review sites. G2 is biggest but not universal. |
+| Creating profiles and forgetting | Monthly review health check | A profile with 0 reviews is worse than no profile — it signals "nobody uses this." |
+| Responding defensively to negative reviews | Acknowledge, address, take offline | Defensive responses are public and permanent. Professional responses build trust. |
+| Asking all customers on the same day | Space requests over weeks | A review burst triggers spam filters. Steady trickle looks organic. |
+| Copy-pasting the same review solicitation email | Personalize with usage details | "You've been using us for 3 months" proves it's not a mass email. |
+
+## YAGNI Principles
+
+- Don't build review widgets for your website — link to the profile directly
+- Don't try to be on every review site — focus on the top 5-6 that AI engines cite
+- Don't automate review responses — each response needs to address the specific feedback
+- Don't track individual reviewer identities — focus on aggregate rating and count
+- Don't create a review generation funnel — email outreach is sufficient for most brands