novahiz 0.1.0

package/bundled-skills/social/references/listening-sources-template.md

@@ -0,0 +1,123 @@
+# Listening Sources — Template
+
+Copy this file to `.agents/listening-sources.md` in your project (or `.claude/listening-sources.md`) and fill in the brackets. Claude reads it when running the [listening workflow](listening.md).
+
+Delete sections you don't use. Keep this short and current — stale sources are worse than no sources.
+
+---
+
+## What We're Listening For
+
+**Brand / product:** [Your product name]
+**Category:** [e.g., "AI writing assistant", "Postgres GUI"]
+**Goal:** [e.g., "find people switching from Notion", "engage with B2B SaaS founders 50-200 employees"]
+
+## ICP (for scoring)
+
+Used by the [scoring rubric](listening.md#scoring-rubric) to judge ICP fit.
+
+- **Role:** [e.g., "founder, head of marketing, marketing ops lead"]
+- **Company stage:** [e.g., "seed to Series B SaaS, 10-200 employees"]
+- **Industry:** [e.g., "B2B SaaS, infra, devtools"]
+- **Signals they're a fit:** [e.g., "writes about GTM, runs paid ads, recently raised"]
+
+---
+
+## Target Accounts
+
+Engage with **every** post from these accounts when relevant. Keep this list to 20-50 max.
+
+### LinkedIn (browser-driven — use dev-browser to view feed)
+- [Name] — `linkedin.com/in/handle`
+- [Name] — `linkedin.com/in/handle`
+
+### X / Twitter (browser-driven)
+- [@handle]
+- [@handle]
+
+### Reddit
+- u/[username]
+- u/[username]
+
+### Bluesky
+- [handle.bsky.social]
+
+### Blogs / Newsletters (RSS)
+- [Name] — `https://example.com/feed/`
+- [Name] — `https://example.substack.com/feed`
+
+### YouTube channels (RSS)
+- [Name] — channel ID `UCxxxxxxxx`
+
+---
+
+## Keywords (intent signals)
+
+Search across all platforms. Claude runs these through Reddit, HN, Bluesky on the [daily loop](listening.md#the-daily-triage-loop).
+
+### High-intent (someone shopping or switching)
+- `"alternative to [competitor]"`
+- `"looking for a [category] tool"`
+- `"recommend a [category]"`
+- `"switching from [competitor]"`
+- `"frustrated with [competitor]"`
+
+### Problem signals (someone in pain)
+- `"[category] is so [bad/hard/expensive]"`
+- `"why is [category] [problem]"`
+- `"hate [pain point]"`
+
+### Brand mentions
+- `"[your brand]"`
+- `"[your brand misspelling]"`
+- `"[your domain]"`
+
+### Competitor mentions (monitor for switching language)
+- `"[competitor 1]"`
+- `"[competitor 2]"`
+
+---
+
+## Subreddits
+
+Pulled via Reddit JSON API on the daily loop.
+
+- r/SaaS
+- r/Entrepreneur
+- r/[your niche, e.g., "marketing", "devtools"]
+- r/[adjacent community]
+
+---
+
+## Saved Searches (manual / browser-driven)
+
+URLs Claude opens via dev-browser to scan.
+
+### LinkedIn Sales Navigator
+- [Search name] — `https://linkedin.com/sales/search/people?...`
+
+### LinkedIn (regular)
+- Posts hashtag — `https://linkedin.com/feed/hashtag/yourtopic/`
+
+### X advanced search
+- [Search name] — `https://x.com/search?q=...&f=live`
+
+---
+
+## Do Not Engage
+
+Save yourself the regret.
+
+- Accounts known for bad-faith dunking: [@handle], [@handle]
+- Blocked brands / competitors who'll screenshot: [list]
+- Topics to avoid: [politics, [your founder's hot takes], etc.]
+
+---
+
+## Notes for Claude
+
+- When asked for "today's top 10," output in the format defined in [listening.md](listening.md#the-daily-triage-loop)
+- For LinkedIn and X, use dev-browser with the persistent session (user is logged in)
+- For everything else, use the curl recipes in [listening.md](listening.md#sources--light-tooling-curl-recipes)
+- Default lookback: 24h. User can override.
+- Always ask before posting — output drafts, user approves and posts manually

package/bundled-skills/social/references/listening.md

@@ -0,0 +1,283 @@
+# Social Listening & Engagement Triage
+
+How to surface the right posts to engage with each day — instead of randomly scrolling. The goal is a short, scorable list ("here are your top 10 posts to comment on") rather than an open feed.
+
+## Contents
+- When to use this
+- The daily triage loop
+- Scoring rubric
+- Comment quality tiers
+- Sources & light tooling (curl recipes)
+- Per-platform notes
+- Common workflows
+
+---
+
+## When to Use This
+
+Use listening when the goal is **commenting and relationships**, not posting. Typical asks:
+- "Give me the top 10 posts I should comment on today"
+- "Who's complaining about [competitor] right now?"
+- "Find people asking for a tool like mine"
+- "Surface posts from my 20 target accounts in the last 24h"
+- "What's the conversation around [topic] this week?"
+
+If the user wants to **create** content, use the rest of the social skill. Listening feeds creation (it surfaces angles, language, objections), but the output is different.
+
+---
+
+## The Daily Triage Loop
+
+A repeatable 20-minute loop the user (or you, on their behalf) can run each morning.
+
+1. **Pull** — fetch new posts from defined sources (target accounts, keywords, subreddits, hashtags). See [tooling](#sources--light-tooling-curl-recipes).
+2. **Filter** — drop anything older than 24h, low signal, or off-topic.
+3. **Score** — apply the [rubric](#scoring-rubric). Keep top 10.
+4. **Draft** — for each, draft a comment matched to the post's tier.
+5. **Post** — user reviews, edits, posts. Mark which actually went live.
+6. **Log** — track what you commented on and what got replies. This is your engagement loop dataset.
+
+Output format Claude should produce:
+
+```
+TOP 10 POSTS — 2026-06-05
+
+1. [Score 9/10] @author — LinkedIn — 2h ago
+   "We just rolled out X and the team is loving it…"
+   Why: ICP fit (B2B SaaS, 50–200 employees), buying-intent signal
+   Suggested comment: [draft]
+   Link: https://…
+```
+
+---
+
+## Scoring Rubric
+
+Score each post 1–10 across five dimensions, then sum and rank.
+
+| Dimension | What it measures | Weight |
+|-----------|------------------|--------|
+| **ICP fit** | Is the author your target customer / influencer? | 2x |
+| **Intent signal** | Are they expressing a problem, asking, or shopping? | 2x |
+| **Reach potential** | Is the post getting traction (likes/comments rising)? | 1x |
+| **Comment opportunity** | Can you say something genuinely useful, not generic? | 2x |
+| **Recency** | Posted in last 1–4h (early comments win, especially on LinkedIn) | 1x |
+
+**Intent signal examples (high-value):**
+- "Looking for a tool that does X"
+- "Why is [category] so painful?"
+- "We just switched from [competitor] because…"
+- "Anyone use [competitor] — is it worth it?"
+- A complaint about a known competitor
+
+**Drop if any of these are true:**
+- Author isn't ICP and isn't an influencer
+- Post is >24h old and already has 50+ comments (your comment buries)
+- Generic motivational/AI-slop post
+- Self-promotion thread where comments don't get reach
+- You can't add anything beyond "Great post!"
+
+---
+
+## Comment Quality Tiers
+
+Match the comment to the post. Don't waste a tier-1 draft on a tier-3 opportunity.
+
+**Tier 1 — Relationship builder (target accounts, ICP, high intent)**
+- Add a specific insight or counter-example
+- Reference your own experience with specifics (numbers, names, outcomes)
+- Ask a thoughtful follow-up that invites a reply
+- Length: 2–4 sentences, no link
+
+**Tier 2 — Visibility play (high-reach post, adjacent topic)**
+- Add one sharp insight in one sentence
+- Pattern: "Agreed — and the part most miss is [X]"
+- Length: 1–2 sentences
+
+**Tier 3 — Light touch (relationship maintenance)**
+- Specific reaction, not "Love this"
+- Quote a specific line and react to it
+- Length: 1 sentence
+
+**Never:** "Great post!", emoji-only, "+1", LinkedIn-isms like "This is gold 🔥"
+
+---
+
+## Sources & Light Tooling (curl recipes)
+
+These are public JSON endpoints — no auth needed. Run them from bash, pipe to `jq`, and Claude can parse the output to score and draft comments.
+
+**Requires:** `jq` (most recipes) and `xmllint` (RSS only). Install once:
+```bash
+# macOS
+brew install jq
+# xmllint ships with macOS; on Linux: apt install libxml2-utils
+```
+
+### Reddit (free, scriptable)
+
+**New posts in a subreddit:**
+```bash
+curl -s -A "listening/1.0" \
+  "https://www.reddit.com/r/SaaS/new.json?limit=25" \
+  | jq '.data.children[].data | {title, author, url: ("https://reddit.com"+.permalink), score, num_comments, created_utc, selftext: (.selftext | .[0:300])}'
+```
+
+**Search across Reddit by keyword (last day, sorted new):**
+```bash
+curl -s -A "listening/1.0" \
+  "https://www.reddit.com/search.json?q=KEYWORD&sort=new&t=day&limit=25" \
+  | jq '.data.children[].data | {subreddit, title, url: ("https://reddit.com"+.permalink), author, score, created_utc}'
+```
+
+Swap `KEYWORD` for things like `"alternative to notion"`, `"recommend a crm"`, your competitor names, or your own brand for mentions. Use quotes around multi-word phrases.
+
+### Hacker News (Algolia search)
+
+**Recent stories mentioning a keyword (last 24h):**
+```bash
+SINCE=$(($(date +%s) - 86400))
+curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=story&numericFilters=created_at_i>${SINCE}" \
+  | jq '.hits[] | {title, url, author, points, num_comments, created_at, story_id: .objectID, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
+```
+
+**Recent comments mentioning a keyword:**
+```bash
+curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=comment&numericFilters=created_at_i>${SINCE}" \
+  | jq '.hits[] | {author, comment_text, story_title, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
+```
+
+### Bluesky (free, public API)
+
+**Search posts by keyword:**
+```bash
+curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=KEYWORD&limit=25&sort=latest" \
+  | jq '.posts[] | {author: .author.handle, text: .record.text, likes: .likeCount, replies: .replyCount, url: ("https://bsky.app/profile/"+.author.handle+"/post/"+(.uri | split("/") | last))}'
+```
+
+### RSS for blogs, podcasts, YouTube channels
+
+For target accounts that publish to RSS (most blogs, all YouTube channels):
+```bash
+# YouTube channel feed (replace CHANNEL_ID)
+curl -s "https://www.youtube.com/feeds/videos.xml?channel_id=CHANNEL_ID"
+
+# Generic blog feed
+curl -s "https://example.com/feed/" | xmllint --xpath "//item[position()<6]" - 2>/dev/null
+```
+
+### LinkedIn & X — use the browser
+
+LinkedIn and X don't expose useful public APIs, but you can drive a real browser session. **dev-browser** (MCP, already in the global setup) and **Playwright** both maintain persistent state — log in once, the session stays alive, Claude can navigate the authenticated feed.
+
+**dev-browser workflow (preferred — already wired up):**
+1. User logs into LinkedIn / X once in the dev-browser session
+2. Claude navigates to a target URL (feed, profile, saved search, hashtag)
+3. Claude reads the accessibility tree / page text, extracts posts
+4. Claude scores using the [rubric](#scoring-rubric) and drafts comments
+5. User reviews and posts manually (don't auto-post — high-stakes, bot detection risk)
+
+**Useful URLs to feed dev-browser:**
+
+| URL pattern | What it shows |
+|-------------|---------------|
+| `linkedin.com/in/HANDLE/recent-activity/all/` | A target account's recent posts |
+| `linkedin.com/feed/hashtag/TOPIC/` | Hashtag feed |
+| `linkedin.com/feed/` | Your main feed (algorithmic — less useful for triage) |
+| `x.com/HANDLE` | A target account's profile |
+| `x.com/search?q=QUERY&f=live` | Real-time search (use `f=live` for chronological) |
+| `x.com/i/lists/LIST_ID` | A curated list — best for target accounts |
+
+**Tips:**
+- On X, build a private list of target accounts and use the list URL. Far cleaner than the algorithmic feed.
+- LinkedIn's `/recent-activity/all/` URL is the cleanest way to see one person's posts without the algorithm.
+- For both platforms, scroll programmatically (dev-browser supports it) to load more posts before extracting.
+
+**Paid alternatives if you don't want to drive a browser:**
+
+| Platform | Tools |
+|----------|-------|
+| LinkedIn | Sales Navigator (saved searches), Taplio (engagement) |
+| X | TweetDeck/X Pro (saved columns), Typefully, Taplio, Tweet Hunter |
+
+**Still closed (no good path):**
+- Instagram & TikTok — closed APIs, browser automation is detectable and risky. Use native saved searches / hashtag follows.
+
+---
+
+## Per-Platform Notes
+
+### LinkedIn
+- **Browser-driven** (dev-browser with persistent session) — see [LinkedIn & X — use the browser](#linkedin--x--use-the-browser)
+- **First-hour comments matter most** — algorithm weights early engagement heavily. Prioritize posts <2h old from target accounts.
+- Comments with 5+ words get more reach than reactions
+- Replying to other commenters can put you in front of their network
+- Tag the author in your reply only if it adds context
+
+### Twitter/X
+- **Browser-driven** (dev-browser) — build a private list of target accounts and point dev-browser at the list URL
+- Reply within first 30 min for max reach on big accounts
+- Quote-tweet > reply when adding substantial value
+- Threading your reply (multi-tweet) signals effort
+- Don't pile on dunks — relationships > clout
+
+### Reddit
+- Read the subreddit rules before commenting (some ban self-promotion outright)
+- Earn karma in the sub before linking to anything you own
+- Long, specific answers win. AMAs and "help me decide" threads are gold
+- Never lead with your product — answer the question first
+
+### Hacker News
+- Comment quality bar is high; low-effort gets downvoted fast
+- Founders commenting on threads about their product is welcomed if you're transparent
+- Search for past discussions of your category — they're often dormant gold mines
+
+### Bluesky
+- Smaller volume but high engagement-to-follower ratio
+- Tech and indie-hacker communities are active
+- Custom feeds (like Bluesky's "Following" + topic feeds) replace algorithmic search
+
+---
+
+## Common Workflows
+
+### "Give me my top 10 posts to comment on today"
+1. Pull from: target account RSS/saved searches + Reddit (relevant subs) + HN (last 24h)
+2. Score with the [rubric](#scoring-rubric)
+3. Output top 10 with suggested comments
+
+### "Find people complaining about [competitor]"
+1. Reddit search: `"competitor name" -site:competitor.com` sorted by new
+2. HN comment search for competitor name
+3. Bluesky search for competitor handle/name
+4. Score by intent signal (high if switching language: "moving from", "alternatives to", "frustrated with")
+
+### "Surface brand mentions from the last week"
+1. Reddit search for brand name
+2. HN search (stories + comments) for brand name
+3. Bluesky search for brand name + handle
+4. Output as: reply needed (yes/no), tone (positive/negative/neutral), suggested response
+
+### "Find target-account posts I missed"
+1. Maintain a list of target accounts with their RSS / Reddit usernames / Bluesky handles
+2. Fetch each source's recent posts
+3. Filter to last 24h, output sorted by score
+
+---
+
+## Setting Up the Source List
+
+The user should maintain a list of sources somewhere persistent at `.agents/listening-sources.md` (or `.claude/listening-sources.md`). Claude reads it when running the daily loop.
+
+**A ready-to-fill template lives at [listening-sources-template.md](listening-sources-template.md).** Copy it into the project and edit. The source path depends on how the skill was installed:
+
+```bash
+# Plugin / marketplace install (most common):
+cp .agents/skills/social/references/listening-sources-template.md .agents/listening-sources.md
+# .claude/ install:
+cp .claude/skills/social/references/listening-sources-template.md .agents/listening-sources.md
+# Working inside the marketingskills repo:
+cp skills/social/references/listening-sources-template.md .agents/listening-sources.md
+```
+
+The template covers: brand/category, ICP (for scoring), target accounts per platform, intent keywords, subreddits, saved-search URLs, and a do-not-engage list.

package/bundled-skills/social/references/platform-limits.md

@@ -0,0 +1,110 @@
+# Platform Limits Reference
+
+Quick reference for hashtag limits, character counts, and visible text thresholds on each major social platform.
+
+---
+
+## Instagram
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 5 (official limit) |
+| Recommended hashtags | 3 – 5 |
+| Max caption chars | 2,200 |
+| Visible before "more" | ~125 chars |
+
+---
+
+## Facebook
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | No official limit |
+| Recommended hashtags | 1 – 2 |
+| Max post chars | 63,206 |
+| Ideal for engagement | 40 – 80 chars |
+
+---
+
+## TikTok
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 5 (since August 2025) |
+| Recommended hashtags | 3 – 5 |
+| Max caption chars | 4,000 |
+| Visible before "more" | ~150 chars |
+
+---
+
+## LinkedIn
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | No official limit |
+| Recommended hashtags | 3 – 5 |
+| Max post chars | 3,000 |
+| Visible before "more" | ~210 chars |
+
+---
+
+## Twitter/X
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | No official limit |
+| Recommended hashtags | 1 – 2 |
+| Max tweet chars | 280 (standard) / 25,000 (Premium+) |
+| Visible before "more" | Full tweet (280 standard) |
+
+---
+
+## YouTube
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 15 (exceeding this causes YouTube to ignore ALL hashtags) |
+| Recommended hashtags | 3 – 5 |
+| Max title chars | 100 (visible before truncation: ~70) |
+| Max description chars | 5,000 |
+| Visible before "Show more" | ~100 chars |
+
+> The first 3 hashtags in the description automatically appear above the title as clickable links. For Shorts, use 1 – 5 hashtags.
+
+---
+
+## Pinterest
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 20 per pin |
+| Recommended hashtags | 2 – 5 |
+| Max pin title chars | 100 |
+| Max description chars | 500 |
+| Visible before "More" | ~50 chars (desktop) |
+
+> Pinterest has deprioritized hashtags. Focus on keywords as natural sentences within the description for better SEO instead of relying on hashtags.
+
+---
+
+## Threads (Meta)
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 1 per post (topic tag) |
+| Recommended hashtags | 1 |
+| Max post chars | 500 |
+| Max with text attachment | 10,500 (500 + 10,000 expandable) |
+| Visible without expanding | First ~1 – 2 lines |
+
+> Threads limits topic tags to one per post. The platform is not hashtag-driven — the algorithm prioritizes content from followed accounts mixed with recommendations.
+
+---
+
+## Usage Tips
+
+- **Hashtags count against character limits** on all platforms
+- **Front-load your message** before the "more" truncation point
+- On Instagram and TikTok, fewer hashtags now outperform hashtag-stuffing
+- On LinkedIn, hashtags at the end of the post perform better than inline
+- On Facebook, hashtags have minimal impact on reach — use sparingly

package/bundled-skills/social/references/platforms.md

@@ -0,0 +1,170 @@
+# Platform-Specific Strategy Guide
+
+Detailed strategies for each major social platform.
+
+## Contents
+- LinkedIn
+- Twitter/X
+- Instagram
+- TikTok
+- Facebook
+
+## LinkedIn
+
+**Best for:** B2B, thought leadership, professional networking, recruiting
+**Audience:** Professionals, decision-makers, job seekers
+**Posting frequency:** 3-5x per week
+**Best times:** Tuesday-Thursday, 7-8am, 12pm, 5-6pm
+
+**What works:**
+- Personal stories with business lessons
+- Contrarian takes on industry topics
+- Behind-the-scenes of building a company
+- Data and original insights
+- Carousel posts (document format)
+- Polls that spark discussion
+
+**What doesn't:**
+- Overly promotional content
+- Generic motivational quotes
+- Links in the main post (kills reach)
+- Corporate speak without personality
+
+**Format tips:**
+- First line is everything (hook before "see more")
+- Use line breaks for readability
+- 1,200-1,500 characters performs well
+- Put links in comments, not post body
+- Tag people sparingly and genuinely
+
+**Algorithm tips:**
+- First hour engagement matters most
+- Comments > reactions > clicks
+- Dwell time (people reading) signals quality
+- No external links in post body
+- Document posts (carousels) get strong reach
+- Polls drive engagement but don't build authority
+
+---
+
+## Twitter/X
+
+**Best for:** Tech, media, real-time commentary, community building
+**Audience:** Tech-savvy, news-oriented, niche communities
+**Posting frequency:** 3-10x per day (including replies)
+**Best times:** Varies by audience; test and measure
+
+**What works:**
+- Hot takes and opinions
+- Threads that teach something
+- Behind-the-scenes moments
+- Engaging with others' content
+- Memes and humor (if on-brand)
+- Real-time commentary on events
+
+**What doesn't:**
+- Pure self-promotion
+- Threads without a strong hook
+- Ignoring replies and mentions
+- Scheduling everything (no real-time presence)
+
+**Format tips:**
+- Tweets under 100 characters get more engagement
+- Threads: Hook in tweet 1, promise value, deliver
+- Quote tweets with added insight beat plain retweets
+- Use visuals to stop the scroll
+
+**Algorithm tips:**
+- Replies and quote tweets build authority
+- Threads keep people on platform (rewarded)
+- Images and video get more reach
+- Engagement in first 30 min matters
+- Twitter Blue/Premium may boost reach
+
+---
+
+## Instagram
+
+**Best for:** Visual brands, lifestyle, e-commerce, younger demographics
+**Audience:** 18-44, visual-first consumers
+**Posting frequency:** 1-2 feed posts per day, 3-10 Stories per day
+**Best times:** 11am-1pm, 7-9pm
+
+**What works:**
+- High-quality visuals
+- Behind-the-scenes Stories
+- Reels (short-form video)
+- Carousels with value
+- User-generated content
+- Interactive Stories (polls, questions)
+
+**What doesn't:**
+- Low-quality images
+- Too much text in images
+- Ignoring Stories and Reels
+- Only promotional content
+
+**Format tips:**
+- Reels get 2x reach of static posts
+- First frame of Reels must hook
+- Carousels: 10 slides with educational content
+- Use all Story features (polls, links, etc.)
+
+**Algorithm tips:**
+- Reels heavily prioritized over static posts
+- Saves and shares > likes
+- Stories keep you top of feed
+- Consistency matters more than perfection
+- Use all features (polls, questions, etc.)
+
+---
+
+## TikTok
+
+**Best for:** Brand awareness, younger audiences, viral potential
+**Audience:** 16-34, entertainment-focused
+**Posting frequency:** 1-4x per day
+**Best times:** 7-9am, 12-3pm, 7-11pm
+
+**What works:**
+- Native, unpolished content
+- Trending sounds and formats
+- Educational content in entertaining wrapper
+- POV and day-in-the-life content
+- Responding to comments with videos
+- Duets and stitches
+
+**What doesn't:**
+- Overly produced content
+- Ignoring trends
+- Hard selling
+- Repurposed horizontal video
+
+**Format tips:**
+- Hook in first 1-2 seconds
+- Keep it under 30 seconds to start
+- Vertical only (9:16)
+- Use trending sounds
+- Post consistently to train algorithm
+
+---
+
+## Facebook
+
+**Best for:** Communities, local businesses, older demographics, groups
+**Audience:** 25-55+, community-oriented
+**Posting frequency:** 1-2x per day
+**Best times:** 1-4pm weekdays
+
+**What works:**
+- Facebook Groups (community)
+- Native video
+- Live video
+- Local content and events
+- Discussion-prompting questions
+
+**What doesn't:**
+- Links to external sites (reach killer)
+- Pure promotional content
+- Ignoring comments
+- Cross-posting from other platforms without adaptation