oss-launch-posts

name

oss-launch-posts

description

Generate platform-tailored launch posts for an open-source project. Analyzes the current repo (git log, README, key source files), web-searches for relevant communities (subreddits, HN, Lobsters, Discord servers, etc.), drafts a title + body per platform matching that community's tone, runs each body through the humanizer skill, and writes a single LAUNCH_POSTS.md at the repo root. Use whenever the user wants to announce a new repo, share their project, draft a Show HN, write subreddit launch posts, or otherwise promote OSS work — even when they only mention one platform, since this produces a multi-platform set in one shot. Triggers on phrases like "launch posts", "Show HN draft", "announce my project", "subreddit posts", "promote my OSS", "how do I share this on Reddit/HN", "where should I post this", or "make me launch posts".

OSS Launch Posts

Generate platform-tailored launch posts for the open-source project in the current working directory. Output a single LAUNCH_POSTS.md at the repo root containing title + body for each target community, ready to copy-paste.

The output is always a markdown file. Never auto-post to any platform — posting is share-visible and the user must review first.

Workflow

Six phases. Stop for user confirmation only at the community-list step.

1. Analyze the repo

You're in the project root. Build a digest covering:

• What it does — one sentence, no jargon. Read the README's first paragraph and verify it matches the actual code.
• How it does it — top-level architecture in 2-4 bullets. Skim the entrypoint plus key files. Don't go deep.
• Distinguishing features — what makes this different from existing tools in the same space? (If you can't name one, the post will be weak — call this out to the user.)
• Target audience — who actually uses this? (CLI users, web devs, gamedevs, ML researchers, etc.)
• Project type tags — pick from: cli, terminal, macos-app, browser-extension, web-framework, library, ai-tooling, game, mobile-app, devtool, data-tool, etc. Multiple tags fine.
• Public URL — derive from git remote get-url origin, normalize to https://. Confirm the repo is public; if it's private, stop and tell the user.
• License — read the LICENSE file.
• Stage — fresh launch, post-1.0, mature?
• Recent shipping — git log --oneline -20 to spot anything launch-worthy that just landed.

This digest informs every later step. Skipping or skimping here yields generic posts that will be ignored or downvoted.

2. Discover communities

Start with the always-relevant set (include these for every project):

• Hacker News (Show HN)
• Lobsters
• r/opensource
• Twitter/X — short hook tweet
• Bluesky — same tweet, retargeted at the dev-on-Bluesky audience (some overlap with Mastodon crowd)
• Dev.to — longer-form post that becomes the canonical launch write-up. The short posts on HN/Reddit/social can all link back to it for technical depth, so it pulls weight even if Dev.to isn't where the user normally writes.

Add by project type:

Type	Communities
cli, terminal	r/commandline, r/programming, plus shell-specific (r/zsh, r/bash, r/fish) and platform-specific (r/iterm2 if macOS-only, r/linux if Linux-friendly)
macos-app	r/macapps, r/MacOS
ai-tooling	r/ClaudeAI, r/LocalLLaMA, r/MachineLearning (only if research-grade), Anthropic Discord (#claude-code if relevant)
web-framework	r/webdev, language-specific (r/javascript or r/typescript), r/programming
browser-extension	r/chrome, r/firefox, r/browsers
library	language-specific subreddit (r/Python, r/golang, r/rust, r/elixir, …), r/programming
game	r/gamedev, r/IndieDev, r/IndieGaming
devtool	r/programming, r/devops if infra-flavored, r/SideProject
data-tool	r/dataengineering, r/datascience, r/Python (often)

Then web-search to find any niche fit not in the table. Useful queries:

• "<project keyword>" subreddit
• "<project keyword>" community forum OR discord
• "Show HN" "<adjacent keyword>" — confirms prior art exists in this space and shows you what worked

If a Discord exists for the closest related tool/framework, add it (e.g., Anthropic Discord for Claude Code plugins, Tailwind Discord for Tailwind plugins).

Also consider (don't auto-include — only add if signal warrants):

• LinkedIn — only if the project is professional/B2B. Skip for hobbyist or developer-tool work.
• Mastodon (fosstodon.org / hachyderm.io) — increasingly relevant for OSS launches; add if the user mentions a public Mastodon presence.

Present the candidate list to the user with one line of rationale per community. Wait for confirmation or edits before drafting bodies — they know their audience better than you do, and this is where their judgment matters most.

3. Draft posts (one per platform)

Each platform has its own conventions. Match them — recycled bodies get downvoted or ignored, and worse, get the user flagged as a spammer.

Title craft (applies to every platform)

The title is the only thing 95% of viewers see. A weak title tanks an otherwise good post. Apply these patterns; they consistently outperform "Built a plugin that does X" / "Released vX.Y.Z" titles.

Patterns that earn the click:

• Lead with stakes or pain. "I had 6 Claude Code tabs open and couldn't tell which one was waiting" beats "A zsh plugin for Claude Code". The reader feels the problem before they read past the first comma.
• Concrete numbers when truthful. "Took two evenings", "6 tabs", "saves me ~20 context switches a day". Vague claims ("supercharge your workflow") read as marketing; specific numbers read as honesty.
• Visible result, not internals. "My iTerm2 tabs now turn amber when Claude is waiting" beats "zsh plugin that hooks into Claude Code lifecycle events". The reader can picture the outcome.
• Curiosity gap, not clickbait. "Why my iTerm2 tabs change color based on what Claude Code is doing" creates a question the reader wants resolved. "You won't believe this iTerm2 hack" is clickbait — readers downvote it.
• First-person on Reddit and Dev.to. First-person signals a real builder behind the post. "I built X because Y" beats "Plugin to do X".
• Negative framing works on tool-pain titles. "Stop guessing which Claude Code tab needs you" / "Tired of X? Here's Y". Use sparingly — once or twice across the launch, not in every title.

Anti-patterns to avoid:

• Generic verbs: "Built a plugin that...", "A new zsh plugin for...", "Introducing X". These are the AI-default and read as a press release.
• Hype adjectives in titles: amazing, awesome, revolutionary, must-have, supercharged, ultimate, the best. They flatten claims and trigger marketing-detector reflexes.
• Title-cased every word ("Plugin That Drives ITerm2 Tab Color From Claude Code State"). Use sentence case unless the platform uses title case (rare).
• Restating the project name: "claude-tab-watcher: a plugin that watches claude tabs" — the colon-and-tagline pattern works on Lobsters but feels redundant elsewhere.
• Vague "thoughts on", "lessons from", "deep dive into" — promises content the body usually doesn't deliver.

Platform-specific tone for titles:

• HN / Lobsters — earn the click through concreteness, not editorializing. The audience is hostile to marketing language. "Show HN: Color iTerm2 tabs amber when Claude Code is waiting on you" works because the visible result is specific. Don't use stakes-led titles here unless they're factual ("Show HN: I lost two hours hunting for which Claude tab needed me, so I built this").
• Reddit — stakes-led, first-person, problem-shaped titles win. "Stop guessing which iTerm2 tab Claude is waiting on" / "I had 6 Claude Code tabs open and built this to keep them straight" / "Made my iTerm2 tab flash amber when Claude needs input — never miss a prompt".
• Twitter/X / Bluesky — the hook tweet is the title. Lead with stakes or a result: "I had 6 Claude Code tabs open and couldn't tell which one was waiting on me. Built this." Pulls the reader into the body.
• Discord — no title, but the first sentence is the title. Same patterns apply.
• Dev.to / Medium / blog — clear value prop or how-to framing. "How I made my iTerm2 tabs tell me which Claude Code session is waiting" / "Coloring my terminal tabs based on what an AI assistant is doing".

For each title, run a quick A/B in your head: which would you click on if it scrolled past — your draft, or the generic "Built a plugin for X" version? If they're a wash, your draft isn't sharp enough.

Hacker News (Show HN)

• Title: Show HN: <one-line description>. Include the project name only if it's also the description ("Show HN: Postgres for browsers"). Hard limit 80 chars; aim for ~60.
• Body: 2-4 short paragraphs.
  • Para 1: what it does, plus link if not in URL field.
  • Para 2: why you built it / what problem it solves.
  • Para 3 (optional): something technically interesting. A non-obvious design decision, a constraint that shaped it.
  • Para 4 (optional): what feedback you'd find useful.
• Forbidden: emoji, "Hi HN!", "I'm excited to announce", any marketing language, hype adjectives. Modesty wins on HN.
• The repo URL goes in the URL field. Only put it in the body if the body needs it for context.

Lobsters

• Title: descriptive, not promotional. ~60 chars.
• Tags: pick 1-3 from the project type (e.g., unix, release, programming, practices).
• Body: one short paragraph. Context for why this is on Lobsters specifically — usually some technically interesting angle.
• Tick "authored by submitter" (assume the user is the author).

Reddit (per subreddit)

Each subreddit has its own tone. Read the rules and recent top posts before drafting.

• Common pattern: first-person, problem→solution narrative. "I kept losing track of which terminal tab Claude was running in, so I built a zsh plugin that…"
• Length: 100-300 words. Long enough for context, short enough for mobile readers.
• Link: include the GitHub URL inline.
• Tone tuning by subreddit:
  • Tool-specific (r/iterm2, r/zsh, r/neovim) — focus on user benefit. Less architecture talk.
  • r/programming — more technical depth. Mention notable design decisions or trade-offs.
  • r/opensource — emphasize the OSS angle (license, contribution welcome, why open).
  • r/SideProject — narrative + numbers if you have any (download counts, stars, etc.).
  • Niche communities — read 5+ recent posts and match the register.
• Forbidden: "Hey guys!", "What do you think?" filler, "Hope this is allowed!" Just state the thing and leave room for questions.
• Flair: if the subreddit has flair, suggest a fitting one in the output.

Twitter/X and Bluesky

• 280-char hook tweet, with optional 2-3 tweet thread for technical detail.
• Lead with the user-visible benefit, not implementation. "Color iTerm2 tabs amber when Claude Code is waiting on you" beats "I wrote a zsh plugin that uses OSC 6 escapes…"
• Link in the first or last tweet, not the middle.
• If a demo GIF/image would carry the post, note it as media-suggestion: <description> — you can't generate the image, but flag what would help. A demo GIF is the single biggest conversion factor for terminal/UI tools.

Discord (relevant server)

• Casual. 2-3 sentences. "Hey folks — built [thing] that does [user benefit], [link]. Happy to answer questions."
• No title field; the message is the post.
• Match the channel: more polish in #showcase / #projects, more casual in #general.

Dev.to / Medium / personal blog (longer-form)

• Title: clear, not clickbait.
• Body: ~600-1200 words with subheadings.
• Structure: hook → problem → what you built → how it works → install → what's next.
• This is where technical depth lives. Cross-link from the HN/Reddit posts as a "longer write-up here" pointer.

4. Humanize each body

After drafting each platform's body, invoke the humanizer skill on it via the Skill tool to remove AI tells (em-dash overuse, rule-of-three, inflated symbolism, "delve", "robust", "leverage", etc.).

• Pass each body separately so the humanizer has clean context per platform.
• Don't humanize titles. They're too short for humanizer to improve, and the platform-specific conventions (Show HN: prefix, character limits) shouldn't be touched.
• If the humanizer skill is not installed, do a manual pass: scan for the AI-tell patterns above and rewrite. Note in the output file that the manual pass was used so the user knows to re-read more carefully.

5. Write LAUNCH_POSTS.md

Single file at the repo root (or wherever the user is working — match pwd). Use this exact template, in this order: HN, Lobsters, Reddit (one section per subreddit), social, Discord, long-form. Order matters because users typically post HN/Lobsters first, then subreddits over a few days.

# Launch posts for <project name>

> Generated <YYYY-MM-DD>. Review before posting — tone, claims, links.
> Posting all of these on the same day looks like a spam blast; space
> them out over a week and engage with replies on each one.

## Posting checklist

- [ ] Repo is public and the README has install instructions above the fold
- [ ] A `v0.1.0+` tag and GitHub Release exist
- [ ] Demo image/GIF is in the README (biggest single conversion lift)
- [ ] Logged into each platform with a `>0`-karma account — HN/Reddit
      shadowban brand-new accounts

---

## Hacker News (Show HN)

**URL field:** <repo URL>

**Title (80 char max):**

``` Body:

<humanized body>

---

Lobsters

URL: Tags: ,

Title:

<title>

Body:

<humanized body>

---

r/

Suggested flair: <flair, or "none">

Title:

<title>

Body:

<humanized body>

---

Twitter/X

Tweet 1 (hook, ≤280 char):

<tweet 1>

Tweet 2 (link + spec):

<tweet 2>

Tweet 3 (optional, technical):

<tweet 3>

---

Bluesky

Post 1 (hook, ≤300 char):

<post 1>

Post 2 (link):

<post 2>

---

Dev.to (long-form)

Tags: , , ,

Title:

<title>

Body:

<humanized long-form body, ~600-1200 words>

---

Notes

• Communities considered but skipped: <list, one-line reason each>
• Suggested media: <e.g., "5s GIF: tab flipping amber when Claude prompts">
• Suggested posting order: <e.g., "HN Tue 8am ET, Lobsters same day, subreddits Wed-Fri">
• Humanizer pass: <"applied via humanizer skill" or "manual fallback — re-read carefully">

### 6. Hand off

Tell the user the file is written. Suggest:

- Open it, skim, adjust anything that feels off in their voice
- Post one platform at a time and engage with replies — early engagement determines whether posts gain traction
- The humanizer pass tries to remove AI fingerprints, but voice is personal. A 30-second user-edit to make each post sound like *them specifically* beats anything automated.

## Principles

- **Authenticity > reach.** AI-generated posts get sniffed out and downvoted aggressively, especially on HN and Lobsters. The humanizer pass is necessary but not sufficient.
- **Different audience, different post.** A r/programming reader cares about design trade-offs; a r/iterm2 reader cares about whether it solves their problem today. Don't recycle bodies across platforms.
- **Modesty wins.** State the thing, share what's interesting, invite feedback. Don't sell. This is especially true on HN and Lobsters but applies broadly.
- **Confirm the community list, not the bodies.** The user knows their audience better than you do — the community list is where their judgment matters most. After they approve, draft the bodies in one pass and let them edit the final markdown.
- **Never auto-post.** Output is always a file for human review. Posting is share-visible and effectively irreversible.

## Out of scope

- Auto-posting to any platform.
- Generating images, GIFs, or screenshots (suggest what would help, but the user produces the media).
- Account management, scheduling, or analytics.
- Multi-week marketing campaigns. Each post stands alone; the user owns sequencing.