@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/social-content/references/post-templates.md

@@ -0,0 +1,177 @@
+# Post Format Templates
+
+Ready-to-use templates for different platforms and content types.
+
+## Contents
+- LinkedIn Post Templates (The Story Post, The Contrarian Take, The List Post, The How-To)
+- Twitter/X Thread Templates (The Tutorial Thread, The Story Thread, The Breakdown Thread)
+- Instagram Templates (The Carousel Hook, The Reel Script)
+- Hook Formulas (Curiosity Hooks, Story Hooks, Value Hooks, Contrarian Hooks, Social Proof Hooks)
+
+## LinkedIn Post Templates
+
+### The Story Post
+```
+[Hook: Unexpected outcome or lesson]
+
+[Set the scene: When/where this happened]
+
+[The challenge you faced]
+
+[What you tried / what happened]
+
+[The turning point]
+
+[The result]
+
+[The lesson for readers]
+
+[Question to prompt engagement]
+```
+
+### The Contrarian Take
+```
+[Unpopular opinion stated boldly]
+
+Here's why:
+
+[Reason 1]
+[Reason 2]
+[Reason 3]
+
+[What you recommend instead]
+
+[Invite discussion: "Am I wrong?"]
+```
+
+### The List Post
+```
+[X things I learned about [topic] after [credibility builder]:
+
+1. [Point] — [Brief explanation]
+
+2. [Point] — [Brief explanation]
+
+3. [Point] — [Brief explanation]
+
+[Wrap-up insight]
+
+Which resonates most with you?
+```
+
+### The How-To
+```
+How to [achieve outcome] in [timeframe]:
+
+Step 1: [Action]
+↳ [Why this matters]
+
+Step 2: [Action]
+↳ [Key detail]
+
+Step 3: [Action]
+↳ [Common mistake to avoid]
+
+[Result you can expect]
+
+[CTA or question]
+```
+
+---
+
+## Twitter/X Thread Templates
+
+### The Tutorial Thread
+```
+Tweet 1: [Hook + promise of value]
+
+"Here's exactly how to [outcome] (step-by-step):"
+
+Tweet 2-7: [One step per tweet with details]
+
+Final tweet: [Summary + CTA]
+
+"If this was helpful, follow me for more on [topic]"
+```
+
+### The Story Thread
+```
+Tweet 1: [Intriguing hook]
+
+"[Time] ago, [unexpected thing happened]. Here's the full story:"
+
+Tweet 2-6: [Story beats, building tension]
+
+Tweet 7: [Resolution and lesson]
+
+Final tweet: [Takeaway + engagement ask]
+```
+
+### The Breakdown Thread
+```
+Tweet 1: [Company/person] just [did thing].
+
+Here's why it's genius (and what you can learn):
+
+Tweet 2-6: [Analysis points]
+
+Tweet 7: [Your key takeaway]
+
+"[Related insight + follow CTA]"
+```
+
+---
+
+## Instagram Templates
+
+### The Carousel Hook
+```
+[Slide 1: Bold statement or question]
+[Slides 2-9: One point per slide, visual + text]
+[Slide 10: Summary + CTA]
+
+Caption: [Expand on the topic, add context, include CTA]
+```
+
+### The Reel Script
+```
+Hook (0-2 sec): [Pattern interrupt or bold claim]
+Setup (2-5 sec): [Context for the tip]
+Value (5-25 sec): [The actual advice/content]
+CTA (25-30 sec): [Follow, comment, share, link]
+```
+
+---
+
+## Hook Formulas
+
+The first line determines whether anyone reads the rest.
+
+### Curiosity Hooks
+- "I was wrong about [common belief]."
+- "The real reason [outcome] happens isn't what you think."
+- "[Impressive result] — and it only took [surprisingly short time]."
+- "Nobody talks about [insider knowledge]."
+
+### Story Hooks
+- "Last week, [unexpected thing] happened."
+- "I almost [big mistake/failure]."
+- "3 years ago, I [past state]. Today, [current state]."
+- "[Person] told me something I'll never forget."
+
+### Value Hooks
+- "How to [desirable outcome] (without [common pain]):"
+- "[Number] [things] that [outcome]:"
+- "The simplest way to [outcome]:"
+- "Stop [common mistake]. Do this instead:"
+
+### Contrarian Hooks
+- "Unpopular opinion: [bold statement]"
+- "[Common advice] is wrong. Here's why:"
+- "I stopped [common practice] and [positive result]."
+- "Everyone says [X]. The truth is [Y]."
+
+### Social Proof Hooks
+- "We [achieved result] in [timeframe]. Here's the full story:"
+- "[Number] people asked me about [topic]. Here's my answer:"
+- "[Authority figure] taught me [lesson]."

package/skills/social-content/references/reverse-engineering.md

@@ -0,0 +1,195 @@
+# Reverse Engineering Viral Content
+
+Instead of guessing what works, systematically analyze top-performing content in your niche and extract proven patterns.
+
+## Contents
+- The 6-Step Framework (Niche ID, Scrape, Analyze, Playbook, Layer Voice, Convert)
+- The Formula
+- Reverse Engineering Checklist
+
+## The 6-Step Framework
+
+### 1. NICHE ID — Find Top Creators
+
+Identify 10-20 creators in your space who consistently get high engagement:
+
+**Selection criteria:**
+- Posting consistently (3+ times/week)
+- High engagement rate relative to follower count
+- Audience overlap with your target market
+- Mix of established and rising creators
+
+**Where to find them:**
+- LinkedIn: Search by industry keywords, check "People also viewed"
+- Twitter/X: Check who your target audience follows and engages with
+- Use tools like SparkToro, Followerwonk, or manual research
+- Look at who gets featured in industry newsletters
+
+### 2. SCRAPE — Collect Posts at Scale
+
+Gather 500-1000+ posts from your identified creators for analysis:
+
+**Tools:**
+- **Apify** — LinkedIn scraper, Twitter scraper actors
+- **Phantom Buster** — Multi-platform automation
+- **Export tools** — Platform-specific export features
+- **Manual collection** — For smaller datasets, copy/paste into spreadsheet
+
+**Data to collect:**
+- Post text/content
+- Engagement metrics (likes, comments, shares, saves)
+- Post format (text-only, carousel, video, image)
+- Posting time/day
+- Hook/first line
+- CTA used
+- Topic/theme
+
+### 3. ANALYZE — Extract What Actually Works
+
+Sort and analyze the data to find patterns:
+
+**Quantitative analysis:**
+- Rank posts by engagement rate
+- Identify top 10% performers
+- Look for format patterns (do carousels outperform?)
+- Check timing patterns (best days/times)
+- Compare topic performance
+
+**Qualitative analysis:**
+- What hooks do top posts use?
+- How long are high-performing posts?
+- What emotional triggers appear?
+- What formats repeat?
+- What topics consistently perform?
+
+**Questions to answer:**
+- What's the average length of top posts?
+- Which hook types appear most in top 10%?
+- What CTAs drive most comments?
+- What topics get saved/shared most?
+
+### 4. PLAYBOOK — Codify Patterns
+
+Document repeatable patterns you can use:
+
+**Hook patterns to codify:**
+```
+Pattern: "I [unexpected action] and [surprising result]"
+Example: "I stopped posting daily and my engagement doubled"
+Why it works: Curiosity gap + contrarian
+
+Pattern: "[Specific number] [things] that [outcome]:"
+Example: "7 pricing mistakes that cost me $50K:"
+Why it works: Specificity + loss aversion
+
+Pattern: "[Controversial take]"
+Example: "Cold outreach is dead."
+Why it works: Pattern interrupt + invites debate
+```
+
+**Format patterns:**
+- Carousel: Hook slide → Problem → Solution steps → CTA
+- Thread: Hook → Promise → Deliver → Recap → CTA
+- Story post: Hook → Setup → Conflict → Resolution → Lesson
+
+**CTA patterns:**
+- Question: "What would you add?"
+- Agreement: "Agree or disagree?"
+- Share: "Tag someone who needs this"
+- Save: "Save this for later"
+
+### 5. LAYER VOICE — Apply Direct Response Principles
+
+Take proven patterns and make them yours with these voice principles:
+
+**"Smart friend who figured something out"**
+- Write like you're texting advice to a friend
+- Share discoveries, not lectures
+- Use "I found that..." not "You should..."
+- Be helpful, not preachy
+
+**Specific > Vague**
+```
+❌ "I made good revenue"
+✅ "I made $47,329"
+
+❌ "It took a while"
+✅ "It took 47 days"
+
+❌ "A lot of people"
+✅ "2,847 people"
+```
+
+**Short. Breathe. Land.**
+- One idea per sentence
+- Use line breaks liberally
+- Let important points stand alone
+- Create rhythm: short, short, longer explanation
+
+```
+❌ "I spent three years building my business the wrong way before I finally realized that the key to success was focusing on fewer things and doing them exceptionally well."
+
+✅ "I built wrong for 3 years.
+
+Then I figured it out.
+
+Focus on less.
+Do it exceptionally well.
+
+Everything changed."
+```
+
+**Write from emotion**
+- Start with how you felt, not what you did
+- Use emotional words: frustrated, excited, terrified, obsessed
+- Show vulnerability when authentic
+- Connect the feeling to the lesson
+
+```
+❌ "Here's what I learned about pricing"
+
+✅ "I was terrified to raise my prices.
+
+My hands were shaking when I sent the email.
+
+Here's what happened..."
+```
+
+### 6. CONVERT — Turn Attention into Action
+
+Bridge from engagement to business results:
+
+**Soft conversions:**
+- Newsletter signups in bio/comments
+- Free resource offers in follow-up comments
+- DM triggers ("Comment X and I'll send you...")
+- Profile visits → optimized profile with clear CTA
+
+**Direct conversions:**
+- Link in comments (not post body on LinkedIn)
+- Contextual product mentions within valuable content
+- Case study posts that naturally showcase your work
+- "If you want help with this, DM me" (sparingly)
+
+---
+
+## The Formula
+
+```
+1. Find what's already working (don't guess)
+2. Extract the patterns (hooks, formats, CTAs)
+3. Layer your authentic voice on top
+4. Test and iterate based on your own data
+```
+
+## Reverse Engineering Checklist
+
+- [ ] Identified 10-20 top creators in niche
+- [ ] Collected 500+ posts for analysis
+- [ ] Ranked by engagement rate
+- [ ] Documented top 10 hook patterns
+- [ ] Documented top 5 format patterns
+- [ ] Documented top 5 CTA patterns
+- [ ] Created voice guidelines (specificity, brevity, emotion)
+- [ ] Built template library from patterns
+- [ ] Set up tracking for your own content performance

package/skills/social-worker/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: social-worker
+description: Humanize and format social media content from NLM research for X, LinkedIn, Instagram. Follows guardrail framework.
+depends-on:
+  - hook-generator
+license: Internal use only
+---
+
+# GUARDRAILS FRAMEWORK
+
+This skill follows the mandatory guardrail protocol. See: .claude/skills/guardrail-framework/SKILL.md
+
+## Pre-Execution Protocol
+1. Read ENTIRE skill before executing ANY step
+2. Copy-paste exact prompts — never paraphrase
+3. Update pipeline-registry.json before each action
+4. If uncertain, ask human before proceeding
+5. **Funnel grounding** (if `funnel_id` provided): Read `funnels/{funnel_id}-*.md` from the brand's `funnels/` directory. Every post MUST include `funnel_id`, `buyer_stage`, `cta`, `icp_segment`. Use the funnel's CTA — not a generic one.
+6. **Awareness Gate** — determine target audience awareness level before any copy work (see below).
+
+## ✅ ALLOWED
+- Run humanizer skill on NLM social drafts
+- Format for X (single, thread, article)
+- Format for LinkedIn (post, article, carousel)
+- Format for Instagram (caption, hashtags)
+- Extract visual prompts from NLM outputs
+- Present drafts to human for review
+- Update registry
+
+## ❌ FORBIDDEN
+- Generate original social content
+- Post without human approval
+- Skip humanization step
+- Make platform decisions without human
+- Skip checkpoint gates
+
+---
+
+## Pipeline Registry Update (START)
+
+Update `businesses/{business}/content/pipeline-registry.json`:
+```json
+{
+  "runId": "from-orchestrator",
+  "currentSkill": "social-worker",
+  "currentStep": 1,
+  "stepName": "find_social_drafts",
+  "status": "in_progress"
+}
+```
+
+---
+
+## Step 1: Find NLM Social Drafts
+
+Location: `businesses/{business}/evergreen.mdcompetitor-intel/{date}-{topic-slug}/`
+
+Files to find:
+- `x-posts.md` - X post drafts
+- `linkedin-article.md` - LinkedIn article draft
+- `linkedin-infographic.md` - Infographic prompts
+- `slide-deck-short.md` - Slide content for visual worker
+
+---
+
+## Step 2: Humanize X Content
+
+Run: `Skill: humanizer`
+
+Input: NLM x-posts.md
+Output: Cleaned X posts in `businesses/{business}/content/social/x-posts-humanized.md`
+
+**Platform requirements**:
+- Single post: 280 chars max
+- Thread: 15-25 posts, each under 280 chars
+- Article: Full article with hook
+
+---
+
+## CHECKPOINT: X Content Review
+
+> "X content humanized. Ready as [single/thread/article]. Waiting for your go-ahead."
+
+[WAIT for go-ahead before proceeding to LinkedIn]
+
+---
+
+## Step 3: Humanize LinkedIn Content
+
+Run: `Skill: humanizer` (or use X content if approved)
+
+Input: NLM linkedin-article.md
+Output: Cleaned LinkedIn content in `businesses/{business}/content/social/linkedin-article-humanized.md`
+
+**Platform requirements**:
+- Post: 3000 chars max, first 200 chars critical
+- Article: Full article with 3-5 section headers
+- Carousel: 10 slides, hook in first
+
+---
+
+## CHECKPOINT: LinkedIn Content Review
+
+> "LinkedIn content humanized. Ready as [post/article/carousel]. Waiting for your go-ahead."
+
+[WAIT for go-ahead before proceeding to Instagram]
+
+---
+
+## Step 4: Format Instagram Content
+
+From NLM outputs or LinkedIn content, create:
+- Caption: Hook (first 125 chars) + body + hashtags
+
+**Hook-generator integration:** Spawn a hook-generator subagent for Instagram caption opening hooks:
+```
+Load the hook-generator skill and execute the full Phase 1-6 pipeline with this context.
+Context:
+- WHO: <audience from brand>
+- WHAT/WHY: <post's core value or insight>
+- Knife: <pain this content addresses>
+- Platform: instagram
+- Brand: <brand name>
+- Target Score: 85
+Return ONLY this JSON array: [{"hook":"...","score":<0-100>,"pattern":"...","formula":"..."}]
+```
+Use top-scored hook as first 125 chars. If subagent fails, write hook manually per NLM output.
+- Hashtags: 3-5 relevant, niche-specific
+
+Save to: `businesses/{business}/content/social/instagram-caption.md`
+
+---
+
+## Step 5: Extract Visual Prompts
+
+From NLM outputs, extract prompts for:
+- X images (if needed)
+- LinkedIn infographic
+- Instagram visuals
+
+Save to: `businesses/{business}/content/social/visual-prompts.md`
+
+---
+
+## Pipeline Registry Update (COMPLETE)
+
+```json
+{
+  "status": "completed",
+  "completedAt": "2026-04-05T12:45:00Z",
+  "outputFiles": [
+    "04-ready/social/x-posts-humanized.md",
+    "04-ready/social/linkedin-article-humanized.md",
+    "04-ready/social/instagram-caption.md",
+    "04-ready/social/visual-prompts.md"
+  ]
+}
+```
+
+---
+
+## STEP N: Copywriting Tournament (RECOMMENDED for post hooks)
+
+Generate 3-5 variants of the key post hooks, then run them through 5 parallel judge personas to find the winner:
+
+1. Generate 3-5 variants (different angles, formulas, or approaches)
+2. Save each to: `content/tournaments/{slug}/variant-1.md` through `variant-N.md`
+3. Spawn 5 PARALLEL `build` subagents (one per judge persona):
+   - `~/.claude/skills/quality-gate/judge-personas/skeptic.md`
+   - `~/.claude/skills/quality-gate/judge-personas/scanner.md`
+   - `~/.claude/skills/quality-gate/judge-personas/buyer.md`
+   - `~/.claude/skills/quality-gate/judge-personas/expert.md`
+   - `~/.claude/skills/quality-gate/judge-personas/outsider.md`
+   - Each gets: tournament_dir, variant_count, mode=`social`, original_prompt
+4. Collect all 5 JSON results, aggregate: sum weighted_avg per variant across judges
+5. Pick winner, apply recommended_edits, save as draft
+6. Winner enters standard quality-gate below
+
+**When to use:** For the opening line of social content
+
+---
+
+## FINAL STEP: Quality Gate (MANDATORY — DO NOT SKIP)
+
+Before presenting ANY draft to Jairo, run the quality gate:
+
+1. Save your complete draft to a file (e.g., `content/drafts/{slug}.md` or a temp file)
+2. Spawn a `build` subagent using the Task tool with the quality-gate prompt from `Skill: quality-gate`
+3. Pass these inputs to the subagent:
+   - **draft_path**: absolute path to the saved draft
+   - **mode**: `social`
+   - **original_prompt**: the writing prompt that started this task
+   - **attempt**: current attempt number (start at 1)
+4. Parse the JSON result from the subagent
+5. If FAIL and attempt < 3:
+   - Rewrite the draft addressing the specific `rewrite_instructions` from the quality gate
+   - Save the new draft (overwrite or new file)
+   - Spawn another subagent with attempt + 1
+6. If FAIL and attempt = 3:
+   - Present to Jairo with all score reports attached
+   - Say: "Couldn't pass quality gate after 3 attempts. Here's what's wrong and what I tried to fix."
+7. If PASS:
+   - Present to Jairo as normal (do NOT show scores — they're internal)
+8. NEVER present a draft that hasn't passed quality gate (except after 3 failed attempts)