@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/cmo/references/analytics-guide.md

@@ -0,0 +1,152 @@
+---
+name: cmo-analytics-guide
+description: |
+  Analytics tracking and measurement guide for marketing.
+  Absorbed from analytics-tracking skill. Load on demand when setting up
+  tracking, measuring results, or debugging analytics.
+---
+
+# Analytics and Tracking Guide
+
+Set up tracking that informs decisions, not dashboards.
+
+## Core Principles
+
+1. **Track for decisions, not data.** Every event should inform an action.
+2. **Start with the questions.** What do you need to know? Work backwards.
+3. **Name things consistently.** Establish patterns before implementing.
+4. **Quality over quantity.** Clean data beats more data.
+
+## Event Naming Convention
+
+Use `object_action` format, lowercase with underscores:
+
+```
+signup_completed
+button_clicked
+form_submitted
+article_read
+checkout_payment_completed
+```
+
+Be specific: `cta_hero_clicked` not `button_clicked`. Include context in properties, not event names.
+
+## Essential Events by Context
+
+### Marketing Site
+
+| Event | Properties |
+|-------|------------|
+| cta_clicked | button_text, location |
+| form_submitted | form_type |
+| signup_completed | method, source |
+| demo_requested | company_size |
+| resource_downloaded | resource_name, type |
+
+### Product / App
+
+| Event | Properties |
+|-------|------------|
+| onboarding_step_completed | step_number, step_name |
+| feature_used | feature_name |
+| purchase_completed | plan, value |
+| subscription_cancelled | reason |
+
+### E-commerce
+
+| Event | Properties |
+|-------|------------|
+| product_viewed | product_id, name, category, price |
+| product_added_to_cart | product_id, price, quantity |
+| checkout_started | cart_value, items_count |
+| purchase_completed | transaction_id, value, currency |
+
+## Standard Properties
+
+**User:** user_id, user_type (free/trial/paid), account_id, plan_type
+**Campaign:** source, medium, campaign, content, term (UTM params)
+**Session:** session_id, page, referrer
+**Timing:** timestamp, time_on_page, session_duration
+
+## UTM Parameter Strategy
+
+| Parameter | Purpose | Example |
+|-----------|---------|---------|
+| utm_source | Traffic source | google, newsletter, linkedin |
+| utm_medium | Marketing medium | cpc, email, social, organic |
+| utm_campaign | Campaign name | spring_launch, welcome_series |
+| utm_content | Differentiate versions | hero_cta, sidebar_banner |
+| utm_term | Paid search keywords | running+shoes |
+
+Rules: lowercase everything, underscores or hyphens consistently, document all UTMs.
+
+## Funnel Sequences
+
+### Signup Funnel
+1. signup_started → 2. signup_step_completed → 3. signup_completed → 4. onboarding_started
+
+### Purchase Funnel
+1. pricing_viewed → 2. plan_selected → 3. checkout_started → 4. payment_info_entered → 5. purchase_completed
+
+### Content Funnel
+1. page_view → 2. scroll_depth (50%+) → 3. cta_clicked → 4. form_submitted → 5. signup_completed
+
+## Implementation
+
+### PostHog (recommended for agent-native)
+
+```javascript
+posthog.capture('signup_completed', {
+  method: 'email',
+  plan: 'free',
+  source: 'landing_page'
+});
+```
+
+### GA4
+
+```javascript
+gtag('event', 'signup_completed', {
+  method: 'email',
+  plan: 'free'
+});
+```
+
+### Validation Checklist
+
+- Events firing on correct triggers
+- Property values populating correctly
+- No duplicate events
+- Works across browsers and mobile
+- Conversions recorded
+- No PII leaking
+
+## Privacy
+
+- Cookie consent required in EU/UK/CA
+- No PII in analytics properties
+- Configure data retention settings
+- Use consent mode (wait for consent before tracking)
+- IP anonymization enabled
+- Only collect what you need
+
+## Research Mode Signal
+
+Skills that depend on external data must declare their research mode:
+
+**When web research available:**
+```
+  RESEARCH MODE
+  ├── Web search      ✓ connected
+  └── Data quality: LIVE
+```
+
+**When no research tools:**
+```
+  RESEARCH MODE
+  ├── Web search      ✗ not available
+  ├── Data quality: ESTIMATED
+  └── To upgrade: connect Exa MCP or firecrawl
+```
+
+Always show this signal. Never silently fall back to estimated data. Prefix estimates with `~`.

package/skills/cmo/references/ideas-library.md

@@ -0,0 +1,197 @@
+---
+name: cmo-ideas-library
+description: |
+  139 proven marketing ideas organized by category, stage, and budget.
+  Absorbed from the marketing-ideas skill. Load on demand when the user
+  needs inspiration or strategic direction.
+---
+
+# Marketing Ideas Library
+
+139 proven marketing approaches. Use this when the user needs ideas, is stuck, or wants to explore new channels.
+
+## By Category
+
+### Content and SEO (1-10)
+1. Easy keyword ranking — target low-competition terms competitors overlook
+2. SEO audit — technical audit, document fixes publicly
+3. Glossary marketing — "what is X" pages for every industry term
+4. Programmatic SEO — template-driven pages at scale (location, comparison, integration)
+5. Content repurposing — one piece becomes thread, video, podcast, infographic
+6. Proprietary data content — original research from your product data
+7. Internal linking — topical clusters distributing authority
+8. Content refreshing — update existing content with fresh data
+9. Knowledge base SEO — optimize help docs for problem-solution queries
+10. Parasite SEO — publish on Medium, LinkedIn, Substack for faster ranking
+
+### Competitor and Comparison (11-13)
+11. Competitor comparison pages — "[You] vs [Competitor]" for high-intent searches
+12. Marketing jiu-jitsu — turn competitor weaknesses into your campaigns
+13. Competitive ad research — study competitor ads via SpyFu, Meta Ad Library
+
+### Free Tools and Engineering (14-22)
+14. Side projects as marketing — small useful tools that funnel to your product
+15. Engineering as marketing — calculators, analyzers, generators
+16. Importers — "Import from [Competitor]" reduces switching friction
+17. Quiz marketing — interactive quizzes that qualify leads
+18. Calculator marketing — ROI calculators, pricing estimators, savings tools
+19. Chrome extensions — browser tools as a distribution channel
+20. Microsites — focused sites for specific campaigns or audiences
+21. Scanners — free audit tools (website, security, performance)
+22. Public APIs — enable an ecosystem of developers
+
+### Paid Advertising (23-34)
+23. Podcast advertising — host-read ads on relevant shows
+24. Pre-targeting ads — awareness before direct response
+25-26. Facebook and Instagram ads — detailed targeting, retargeting
+27. Twitter/X ads — reach professionals discussing your industry
+28. LinkedIn ads — target by job title, company size, industry
+29. Reddit ads — authentic messaging to passionate communities
+30. Quora ads — target users asking questions your product answers
+31. Google ads — capture high-intent search queries
+32. YouTube ads — pre-roll and discovery with detailed targeting
+33. Cross-platform retargeting — consistent messaging across platforms
+34. Click-to-messenger ads — conversations over landing pages
+
+### Social and Community (35-44)
+35. Community marketing — Slack, Discord, Facebook groups
+36. Quora marketing — answer questions with genuine expertise
+37. Reddit keyword research — mine real language from subreddits
+38. Reddit marketing — participate authentically, value first
+39. LinkedIn audience — personal brand building for B2B
+40. Instagram audience — visual storytelling, behind-the-scenes
+41. X/Twitter audience — threads and insights grow followings
+42. Short-form video — TikTok, Reels, Shorts
+43. Engagement pods — coordinate with peers for boost
+44. Comment marketing — thoughtful comments build visibility
+
+### Email Marketing (45-53)
+45. Mistake emails — authentic "oops" emails drive engagement
+46. Reactivation emails — win back churned or inactive users
+47. Founder welcome email — personal connection from the founder
+48. Dynamic email capture — exit intent, scroll triggers
+49. Monthly newsletters — consistent brand touchpoint
+50. Inbox placement — deliverability, authentication, list hygiene
+51. Onboarding emails — guide new users to activation
+52. Win-back emails — re-engage churned users
+53. Trial reactivation — recover expired trials
+
+### Partnerships (54-64)
+54. Affiliate discovery via backlinks — find affiliates from competitor links
+55. Influencer whitelisting — run ads through influencer accounts
+56. Reseller programs — white-label distribution partners
+57. Expert networks — certified implementors
+58. Newsletter swaps — exchange mentions with complementary newsletters
+59. Article quotes — HARO, expert quotes for journalists
+60. Pixel sharing — share remarketing audiences with partners
+61. Shared Slack channels — direct partner and customer communication
+62. Affiliate program — structured commission programs
+63. Integration marketing — joint campaigns with integration partners
+64. Community sponsorship — sponsor newsletters, communities, publications
+
+### Events and Speaking (65-72)
+65. Live webinars — educational lead generation
+66. Virtual summits — multi-speaker events
+67. Roadshows — meet customers directly
+68-69. Local meetups — host or sponsor
+70. Conference speaking — reach engaged audiences
+71. Host your own conference — become the industry center
+72. Conference sponsorship — brand visibility
+
+### PR and Media (73-76)
+73. Media acquisitions — acquire newsletters, podcasts
+74. Press coverage — pitch newsworthy stories
+75. Fundraising PR — leverage funding for press
+76. Documentaries — explore your industry or customers
+
+### Launches and Promotions (77-86)
+77. Black Friday promotions — urgency and acquisition spikes
+78. Product Hunt launch — structured launch for early adopters
+79. Early-access referrals — rewards for referral during launch
+80. New Year promotions — fresh budgets, goal-setting energy
+81. Early access pricing — discounted launch tiers
+82. Product Hunt alternatives — BetaList, Launching Next, AlternativeTo
+83-85. Giveaways — Twitter, strategic, grand prize
+86. Lifetime deals — one-time payment for users and cash
+
+### Product-Led Growth (87-96)
+87. Powered-by badges — free impressions on customer sites
+88. Free migrations — reduce switching friction
+89. Contract buyouts — pay to exit competitor contracts
+90. One-click registration — OAuth, minimal signup friction
+91. In-app upsells — strategic upgrade prompts
+92. Newsletter referrals — built-in referral programs
+93. Viral loops — product mechanics encouraging sharing
+94. Offboarding flows — optimize cancellation to retain or learn
+95. Concierge setup — white-glove onboarding for high-value accounts
+96. Onboarding optimization — continuous improvement of new user experience
+
+### Content Formats (97-109)
+97. Playlists — Spotify playlists for your audience
+98. Template marketing — free templates users immediately use
+99. Graphic novel marketing — visual narratives for complex stories
+100. Promo videos — showcase product
+101. Industry interviews — customers, experts, thought leaders
+102. Social screenshots — shareable screenshot templates
+103. Online courses — authority building + lead gen
+104. Book marketing — author a book establishing expertise
+105. Annual reports — industry data and trends
+106. End-of-year wraps — personalized summaries users share
+107. Podcasts — reach commuters and passive listeners
+108. Changelogs — public product momentum
+109. Public demos — live product demonstrations
+
+### Unconventional (110-122)
+110. Awards — create industry awards, be the tastemaker
+111. Challenges — viral challenges that spread organically
+112. Reality TV content — follow real customers
+113. Controversy — strategic positioning against norms
+114. Moneyball marketing — data-driven undervalued channels
+115. Curation — curate valuable resources
+116. Grants — offer grants to customers or community
+117. Product competitions — competitions using your product
+118. Cameo marketing — personalized celebrity messages
+119. OOH advertising — billboards, transit ads
+120. Marketing stunts — bold attention-grabbing moments
+121. Guerrilla marketing — unconventional, low-cost, unexpected
+122. Humor marketing — stand out and create memorability
+
+### Platforms and Marketplaces (123-130)
+123. Open source — build developer goodwill
+124. App store optimization — discoverability in app stores
+125. App marketplaces — Shopify, Salesforce, etc.
+126. YouTube reviews — get YouTubers to review your product
+127. YouTube channel — tutorials and thought leadership
+128. Source platforms — G2, Capterra, GetApp
+129. Review sites — manage presence on review platforms
+130. Live audio — Twitter Spaces, LinkedIn Audio
+
+### Other (131-139)
+131-132. International — expansion and price localization
+133. Investor marketing — portfolio introductions
+134. Certifications — validate expertise with programs
+135. Support as marketing — exceptional support creates stories
+136. Developer relations — build dev community relationships
+137. Two-sided referrals — reward both referrer and referred
+138. Podcast tours — guest on multiple relevant podcasts
+139. Customer language — use exact words your customers use
+
+## By Stage
+
+**Pre-launch:** Waitlist referrals (79), early access pricing (81), Product Hunt prep (78)
+**Early stage:** Content and SEO (1-10), community (35), founder emails (47)
+**Growth:** Paid acquisition (23-34), partnerships (54-64), events (65-72)
+**Scale:** Brand campaigns, international (131-132), media acquisitions (73)
+
+## By Budget
+
+**Free:** Content, SEO, community, social media, comment marketing
+**Low:** Targeted ads, sponsorships, free tools
+**Medium:** Events, partnerships, PR
+**High:** Acquisitions, conferences, brand campaigns
+
+## By Timeline
+
+**Quick wins:** Ads, email, social posts (days)
+**Medium-term:** Content, SEO, community (weeks-months)
+**Long-term:** Brand, thought leadership, platform effects (months-years)

package/skills/cmo/rules/brand-file-map.md

@@ -0,0 +1,198 @@
+# Brand File → Dependent Skills (Reverse Index)
+
+When a `brand/*.md` file changes, some downstream skills become stale and should re-run. This map answers: **"I just updated `<file>` — what's now out of date?"**
+
+/cmo reads this on every "update brand" request and proactively flags regen candidates.
+
+---
+
+## `brand/voice-profile.md` — HIGH impact
+
+Changing voice invalidates tone on every copy and distribution asset ever produced.
+
+**Skills that must re-run (if the asset is still in use):**
+
+| Skill | What regenerates |
+|---|---|
+| `direct-response-copy` | Landing pages, sales copy, cold emails, headlines. |
+| `seo-content` | All published articles (at minimum edit passes). |
+| `lead-magnet` | Lead magnet prose, landing page, follow-up sequence. |
+| `newsletter` | Template + recent issues. |
+| `email-sequences` | Welcome, nurture, launch, win-back flows. |
+| `content-atomizer` | Any `marketing/social/` output. |
+| `social-campaign` | Phase 2 voice calibration re-runs. |
+| `typefully` / `postiz` drafts | Re-review scheduled posts. |
+| `creative` | Ad copy variants. |
+| `marketing-demo` narration / `slideshow-script` / `video-content` scripts | Voice-calibrated scripts. |
+| `startup-launcher` | Platform copy + tagline variants. |
+
+**Routing rule:** when voice changes, surface a rewrite plan before auto-running anything. The user picks which assets are worth the rewrite.
+
+---
+
+## `brand/audience.md` — HIGH impact
+
+Targeting changes mean every copy decision needs re-calibration.
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `direct-response-copy` | "For whom" framing shifts. |
+| `seo-content` | Search intent + watering-hole calibration. |
+| `lead-magnet` | Asset type (ebook vs calculator) depends on audience. |
+| `email-sequences` | Segment splits and pacing. |
+| `newsletter` | Topic calendar pivot. |
+| `content-atomizer` | Platform priority shifts (watering holes). |
+| `positioning-angles` | Re-run — positioning is always relative to audience. |
+| `social-campaign` | Platform mix re-planned. |
+| `pricing-strategy` | Willingness-to-pay changes. |
+| `free-tool-strategy` | Tool utility hinges on audience pain. |
+| `conversion-flow-cro` | Flow friction depends on audience sophistication. |
+
+---
+
+## `brand/positioning.md` — HIGH impact
+
+Positioning drives landing pages, launch copy, and competitive framing.
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `direct-response-copy` | Landing page hero, value prop, differentiation. |
+| `page-cro` | "Why us" rewrite. |
+| `launch-strategy` | Angle selection. |
+| `startup-launcher` | All 56 platform taglines + descriptions. |
+| `competitor-alternatives` | "vs." framing. |
+| `seo-machine` | Drives `/alternatives/<competitor>` + `/compare/<a>-vs-<b>` page angles in Path B. |
+| `off-page-seo` | Anti-positioning + differentiators inform the outreach value-add angle when pitching listicles + guest posts. |
+| `newsletter` | Editorial angle. |
+| `slideshow-script` | Narrative frameworks (AIDA/PAS/BAB) depend on angle. |
+| `creative` | Ad variant themes. |
+| `brand-kit-playground` | Voice preview text. |
+
+---
+
+## `brand/competitors.md` — MEDIUM impact
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `competitor-alternatives` | Full regen — this IS the input. |
+| `competitive-intel` | Refresh baseline. |
+| `landscape-scan` | Re-ground market snapshot. |
+| `positioning-angles` | Gaps shift. |
+| `direct-response-copy` | Objection handling updates. |
+| `seo-content` | Comparison content + "alternatives to" keywords. |
+| `seo-machine` | Re-targets alternatives/compare page batches in the next phase. |
+| `off-page-seo` | Recipe F runs on competitors.md to seed `.seo/backlink-targets.json`. Refresh prompts a re-prospect via `mktg-backlink-prospector`. |
+| `mktg compete scan` | Watchlist sync. |
+
+---
+
+## `brand/landscape.md` — HIGH impact (Claims Blacklist)
+
+Landscape drives the **Claims Blacklist** — any claim not grounded in current landscape data is off-limits.
+
+**Skills affected (ALL content-producing):**
+
+| Skill | Why |
+|---|---|
+| `direct-response-copy` | Claims Blacklist enforcement on every headline. |
+| `seo-content` | Market claims gated. |
+| `newsletter` | Editorial claims gated. |
+| `lead-magnet` | Proof claims gated. |
+| `content-atomizer` | Platform posts inherit Blacklist. |
+| `social-campaign` | Phase 0 reads Blacklist. |
+| `launch-strategy` | Market-size/category claims gated. |
+| `startup-launcher` | Platform copy Blacklist-checked. |
+| `competitor-alternatives` | Comparison claims Blacklist-checked. |
+| `ai-seo` | Citation-worthy claims must be Blacklist-safe. |
+
+**Freshness critical:** landscape is usable for 14 days. Stale landscape = stale Blacklist = risk of unfounded claims shipping.
+
+---
+
+## `brand/keyword-plan.md` — MEDIUM impact
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `seo-content` | Primary/secondary/long-tail targeting. |
+| `ai-seo` | Entity optimization vocabulary. |
+| `competitor-alternatives` | Comparison keyword selection. |
+| `seo-audit` | URL structure + schema recommendations. |
+| `seo-machine` | Seeds every phase — striking-distance keywords, pattern grouping (alternatives/compare/use-case/playbooks), per-page targets. |
+| `free-tool-strategy` | Tool naming + SEO anchor. |
+
+---
+
+## `brand/creative-kit.md` — MEDIUM impact (visual only)
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `creative` | Visual briefs use the kit. |
+| `image-gen` | Style anchors. |
+| `visual-style` | Source file — regenerate if deliberate. |
+| `brand-kit-playground` | Preview reflects the kit. |
+| `paper-marketing` | Design system for designer agents. |
+| `slideshow-script` | Visual styling of generated slides. |
+| `video-content` | Color palette, typography for Remotion compositions. |
+| `app-store-screenshots` | Visual identity on app store pages. |
+| `frontend-slides` | Slide visual theme. |
+
+---
+
+## `brand/stack.md` — LOW impact (integration alerts)
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `email-sequences` | ESP choice (Resend, Mailchimp, etc.) |
+| `send-email` | API wiring points. |
+| `typefully` | Social set IDs, connected accounts. |
+| `postiz` | Connected integrations baseline. |
+| `newsletter` | Platform selection (ConvertKit, Beehiiv, Substack). |
+| `agent-email-inbox` / `resend-inbound` | Domain + webhook config. |
+
+---
+
+## `brand/assets.md` — Append-only (no regen trigger)
+
+Logs created assets (content, images, videos, scheduled posts). `/cmo` reads this to avoid duplicating work — if an asset exists, don't silently overwrite.
+
+---
+
+## `brand/learnings.md` — Append-only (informs routing)
+
+Logs what worked, what didn't, what's been tried. `/cmo` reads this to:
+- Avoid re-running a failed experiment.
+- Compound insights across sessions.
+- Pick the next move based on past outcomes.
+
+Never regenerates any skill — but every post-skill reflection should append an entry via `mktg brand append-learning --input '{...}'`.
+
+---
+
+## Cascade severity summary
+
+| File | Severity | When it changes, /cmo should… |
+|---|---|---|
+| `voice-profile.md` | 🔴 HIGH | Offer a rewrite plan for every downstream copy/distribution asset. |
+| `audience.md` | 🔴 HIGH | Offer re-calibration for copy, distribution, pricing. |
+| `positioning.md` | 🔴 HIGH | Re-run landing page + launch copy. |
+| `landscape.md` | 🔴 HIGH | Warn: Claims Blacklist changed — every piece of content needs re-check. |
+| `competitors.md` | 🟡 MEDIUM | Refresh comparison/alternatives pages, competitive intel. If `docs/seo-machine.md` exists, prompt next phase of `seo-machine` to re-target. |
+| `keyword-plan.md` | 🟡 MEDIUM | Flag SEO content + AI SEO for refresh. If `docs/seo-machine.md` exists, propose a Resume run to roll new terms into pending phases. |
+| `creative-kit.md` | 🟡 MEDIUM | Visual skills inherit automatically; flag published visual assets. |
+| `stack.md` | 🟢 LOW | Integration alerts only. |
+| `assets.md` | — | No regen; avoids duplication. |
+| `learnings.md` | — | No regen; informs future routing. |
+
+**Rule of thumb:** when a HIGH file changes, /cmo surfaces a rewrite plan **before** accepting any downstream request. Don't produce new copy on top of stale inputs.