@opendirectory.dev/skills 0.1.44 → 0.1.46

package/skills/oss-launch-kit/TECHNICAL_DESIGN.md

@@ -0,0 +1,187 @@
+# oss-launch-kit Technical Design
+
+## Architecture Summary
+`oss-launch-kit` should follow the same advanced-skill pattern used elsewhere in this repo:
+- `README.md` for public overview and usage
+- `SKILL.md` for operational instructions
+- `.env.example` for required environment variables
+- `scripts/` for executable orchestration
+- `references/` for design guides, templates, and frameworks (note: these are for design-time reference, the current scripts use hardcoded templates for maximum performance and stability).
+- `evals/` for validation cases
+
+The implementation should be a two-stage pipeline:
+
+1. repo context -> structured product brief
+2. product brief -> channel-specific launch assets
+
+This mirrors the repo’s stronger launch skills and keeps the generation grounded.
+
+## Stage A: Repo Context -> Product Brief
+### Responsibility
+Convert raw GitHub repo data into a normalized brief that captures only what can be supported by evidence.
+
+### Inputs
+- repo metadata JSON
+- README text
+- optional release metadata
+
+### Output schema
+```json
+{
+  "repo_name": "string",
+  "one_line_summary": "string",
+  "project_type": "string",
+  "launch_readiness": {
+    "score": "low | medium | high",
+    "signals": "object",
+    "fix_plan": "list"
+  },
+  "audience": "string",
+  "problem_solved": "string",
+  "value_proposition": "string",
+  "key_proof_points": "list",
+  "key_features": "list",
+  "links": "object",
+  "confidence": "low | medium | high",
+  "assumptions": "list",
+  "channel_fitness": "object"
+}
+```
+
+### Failure cases
+- README is sparse or missing.
+- Repo description conflicts with README.
+- Audience is implied, not explicit.
+
+### Hallucination controls
+- Treat README and repo metadata as the only factual source.
+- Allow `unknown` or empty values when evidence is missing.
+- Store evidence alongside every major inference.
+
+## Stage B: Product Brief -> Launch Assets
+### Responsibility
+Use the brief to generate channel-specific drafts with channel rules applied.
+
+### Inputs
+- product brief JSON
+- channel rules from `references/channel_rules.md`
+- output template from `references/output_template.md`
+
+### Output
+- final Markdown launch kit
+
+### Failure cases
+- assets become generic
+- channel tone drifts away from platform norms
+- unsupported claims leak into drafts
+
+### Hallucination controls
+- no new facts beyond the brief
+- confidence notes carry through to final output
+- use explicit `[!TIP]` handoffs to specialized skills
+- suppress aggressive channels for unready repos
+
+## Channel Rules
+### Show HN
+- direct and technical
+- no hype language
+- no fake performance claims
+- plain title alternative only if useful
+
+### Product Hunt
+- include tagline and description
+- maker comment should sound human and specific
+- avoid invented social proof
+- do not exceed practical PH length constraints
+
+### Reddit
+- generate niche suggestions based on repo tags and description
+- include a warning to verify subreddit rules before posting
+- prioritize feedback-first communities for early-stage repos
+
+### Twitter/X
+- concise thread
+- each tweet should carry one idea
+- use evidence-based language only
+- no spammy hashtags
+
+## File Structure
+```text
+skills/oss-launch-kit/
+├── README.md
+├── SKILL.md
+├── .env.example
+├── PRD.md
+├── TECHNICAL_DESIGN.md
+├── evals/
+│   └── evals.json
+├── references/
+│   ├── launch_framework.md
+│   ├── channel_rules.md
+│   └── output_template.md
+└── scripts/
+    ├── run.py
+    ├── fetch_repo_context.py
+    ├── build_product_brief.py
+    └── generate_assets.py
+```
+
+## Implementation Phases
+### Phase 1: Skeleton and docs
+- Create folder structure and planning docs.
+- Acceptance: skill folder exists with PRD, technical design, and reference stubs.
+- Risk: too much upfront design before validation.
+
+### Phase 2: GitHub fetcher
+- Implement repo URL parsing and GitHub API fetches.
+- Acceptance: metadata and README resolve for public repos.
+- Risk: API rate limits and README format variance.
+
+### Phase 3: Brief builder
+- Turn repo context into structured brief JSON.
+- Acceptance: evidence-backed fields and explicit confidence notes.
+- Risk: over-inference from weak READMEs.
+
+### Phase 4: Asset generation
+- Produce final channel drafts from the brief.
+- Acceptance: all outputs obey channel rules and remain grounded.
+- Risk: repetitive or generic copy.
+
+### Phase 5: Testing on 3 public repos
+- Test on a dev tool repo, a library/package repo, and a weak README repo.
+- Acceptance: all three produce usable outputs with honest low-confidence handling.
+- Risk: one-size-fits-all messaging.
+
+### Phase 6: README polish and PR prep
+- Align README with final behavior and usage.
+- Acceptance: maintainer can review quickly and see the merge value.
+
+## Testing Strategy
+### Test set
+- one dev-tool repo with strong README
+- one library/package repo with clear positioning
+- one repo with a weak README
+
+### Good output means
+- factual repo summary
+- specific audience and problem framing
+- channel-appropriate tone
+- no fabricated proof points
+- explicit assumptions where evidence is thin
+
+## Risks and Mitigations
+- Weak README: keep output short, honest, and confidence-tagged.
+- Misleading repo description: prefer README over description.
+- Unclear audience: provide one primary hypothesis and note ambiguity.
+- Generic launch copy: require evidence fields before drafting assets.
+- Wrong subreddit suggestions: mark them as suggestions, not endorsements.
+- Hallucinated claims: final validation pass checks every claim against brief evidence.
+
+## PR Plan
+- Branch: `skill/oss-launch-kit`
+- PR title: `feat(skill): add oss-launch-kit`
+- Commit sequence:
+  - `docs(skill): add oss-launch-kit prd and technical design`
+  - `docs(skill): add oss-launch-kit reference docs and scaffold`
+  - `feat(skill): implement repo context fetcher`
+  - `feat(skill): implement brief builder and launch asset generation`

package/skills/oss-launch-kit/evals/cli-cli.full.md

@@ -0,0 +1,49 @@
+# Launch Orchestrator for cli/cli
+
+
+
+## Executive Summary & Launch Readiness
+
+**Project Maturity**: HIGH
+
+
+
+## Coordinated Launch Timeline
+
+- [ ] Day 1: Show HN
+- [ ] Day 3: Reddit
+- [ ] Day 5: Product Hunt
+
+
+
+This is identified as a **tool** with **High Launch Readiness**.
+- **Show HN**: High fit. Technical communities appreciate technical tools and libraries.
+- **Product Hunt**: Not recommended yet. Pure libraries or early-stage tools often struggle on PH without a UI/Demo.
+
+
+
+## Channel Strategy & Positioning
+### [Show HN] - Fit: HIGH
+**Positioning**: Focus on technical implementation and 'why I built this'.
+**Recommended Title**: `Show HN: cli/cli - GitHub’s official command line tool`
+**Hook**: I built cli/cli because I wanted a clearer way to serve data/infra users who need github’s official command line tool.
+> [!TIP]
+> Use `show-hn-writer` for a full submission draft.
+
+### [Reddit] - Fit: MEDIUM
+**Niche Strategy**: Engage r/devtools, r/opensource, r/commandline with feedback-first posts.
+**Key Hook**: GitHub’s official command line tool
+> [!TIP]
+> Use `reddit-post-engine` to generate subreddit-specific variants.
+
+### [Twitter/X] - Fit: HIGH
+**Thread Strategy**: Start with the problem of GitHub’s official command line tool.
+**Hook**: I built `cli/cli` to solve github’s official command line tool.
+> [!TIP]
+> Use `tweet-thread-from-blog` or `linkedin-post-generator` to expand this hook.
+
+
+
+## Full Confidence Notes & Assumptions
+
+- Confidence: high

package/skills/oss-launch-kit/evals/evals.json

@@ -0,0 +1,44 @@
+[
+  {
+    "repo": "cli/cli",
+    "full": "cli-cli.full.md",
+    "description": "Strong CLI tool",
+    "expectations": [
+      "**Project Maturity**: HIGH",
+      "Show HN fitness is HIGH",
+      "Includes Channel Strategy & Positioning section",
+      "Timeline includes Show HN"
+    ]
+  },
+  {
+    "repo": "octocat/Hello-World",
+    "full": "octocat-hello-world.full.md",
+    "description": "Weak project",
+    "expectations": [
+      "**Project Maturity**: LOW",
+      "> [!CAUTION]",
+      "This project is not launch-ready yet",
+      "Show HN and Product Hunt are NOT recommended",
+      "Channel Strategy & Positioning section is absent",
+      "Coordinated Launch Timeline is absent"
+    ]
+  },
+  {
+    "repo": "pydantic/pydantic",
+    "full": "pydantic-pydantic.full.md",
+    "description": "Mature library",
+    "expectations": [
+      "**Project Maturity**: HIGH",
+      "Show HN fitness is HIGH"
+    ]
+  },
+  {
+    "repo": "vercel/next.js",
+    "full": "vercel-next-js.full.md",
+    "description": "Polished framework",
+    "expectations": [
+      "**Project Maturity**: HIGH",
+      "Product Hunt fitness is HIGH"
+    ]
+  }
+]

package/skills/oss-launch-kit/evals/octocat-hello-world.full.md

@@ -0,0 +1,53 @@
+# Launch Orchestrator for octocat/Hello-World
+
+
+
+## Executive Summary & Launch Readiness
+
+**Project Maturity**: LOW
+
+
+> [!WARNING]
+
+> **Launch Readiness is Low.** This project currently looks like a toy or template repo.
+
+> Recommended next steps: improve README, add installation examples, and fix core metadata.
+
+
+
+- Confidence: low
+- Assumptions: Audience inferred from repo metadata only.; No clear installation instructions found in README
+Edit before posting: this repo context is sparse, so tighten the copy after reviewing the README and repo signals.
+
+
+
+## Coordinated Launch Timeline
+
+- [ ] Day 1-3: Documentation Sprint (Fix README, add examples)
+- [ ] Day 4: Ask for feedback on Reddit (r/opensource or relevant niche)
+- [ ] Day 5: Soft launch on Twitter/X to gathered followers
+- [ ] Day 7+: Re-evaluate for Show HN/PH once README is robust
+
+
+
+This is identified as a **project** with **Low Launch Readiness**.
+- **Show HN**: Not recommended yet. Repository context might be too thin for Hacker News.
+- **Product Hunt**: Not recommended yet. Pure libraries or early-stage tools often struggle on PH without a UI/Demo.
+- **Reddit**: OK for feedback only. Avoid a 'launch' post; ask for specific technical reviews instead.
+
+
+
+## Channel Strategy & Positioning
+### [Twitter/X] - Fit: HIGH
+**Thread Strategy**: Start with the problem of My first repository on GitHub!.
+**Hook**: I built `octocat/Hello-World` to solve my first repository on github!.
+> [!TIP]
+> Use `tweet-thread-from-blog` or `linkedin-post-generator` to expand this hook.
+
+
+
+## Full Confidence Notes & Assumptions
+
+- Confidence: low
+- Assumptions: Audience inferred from repo metadata only.; No clear installation instructions found in README
+Edit before posting: this repo context is sparse, so tighten the copy after reviewing the README and repo signals.

package/skills/oss-launch-kit/evals/pydantic-pydantic.full.md

@@ -0,0 +1,152 @@
+# Launch Kit
+
+## Repo Summary
+pydantic/pydantic
+
+## Audience
+end users
+
+## Description
+Data validation using Python type hints
+
+# Show HN Draft
+
+## Title
+Show HN: pydantic/pydantic - Data validation using Python type hints
+
+## Short Intro
+Low-confidence repo context. Title-only draft recommended.
+
+## Core Explanation
+Not enough README signal to write a reliable body.
+
+## Feedback Ask
+Please review the repo framing and README quality before posting.
+
+## Notes
+- Confidence: high
+
+# Product Hunt Draft
+
+## Tagline
+pydantic/pydantic: open-source project for end users
+
+## Description
+Built for end users. Keeps the pitch grounded in repo facts.
+
+## Maker Comment
+Draft only. Edit before posting.
+
+## Notes
+- Confidence: high
+
+# Reddit Drafts
+
+## Variant 1
+Subreddit: r/SideProject (general maker context)
+
+I built pydantic/pydantic for end users because data validation using python type hints.
+
+This is a fit for general maker context; I’m sharing it here to get feedback, not to spam the subreddit.
+
+It focuses on the repo metadata and README.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+If this fits the community, I’d appreciate feedback on the launch angle and any missing context.
+
+## Variant 2
+Subreddit: r/opensource (open-source launch context)
+
+I built pydantic/pydantic for end users because data validation using python type hints and I think the interesting part is the launch workflow, not the code itself.
+
+I’m posting in open-source launch context because it’s an OSS launch question first and a product post second.
+
+The repo signals I leaned on were README text and metadata.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+Curious whether this framing would land with open-source launch context.
+
+## Variant 3
+Subreddit: r/programming (developer audience)
+
+I built pydantic/pydantic for end users because data validation using python type hints, and the challenge was keeping the launch copy specific without turning it into jargon.
+
+For developer audience, I’d mainly want feedback on whether the problem/solution framing is actually useful to builders.
+
+The repo cues I used were Data validation using Python type hints and README details.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+Would this problem/solution framing feel useful to builders in developer audience?
+
+## Variant 4
+Subreddit: r/devtools (developer tools audience)
+
+I built pydantic/pydantic for end users because data validation using python type hints and I wanted a cleaner way to turn repo facts into launch copy.
+
+This angle fits developer tools audience; I’m sharing it for feedback on the workflow, not as a promo blast.
+
+The main angle here is Data validation using Python type hints, with README details as supporting context.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+Would this problem/solution framing feel useful to builders in developer tools audience?
+
+## Variant 5
+Subreddit: r/commandline (command-line users)
+
+I built pydantic/pydantic for end users because data validation using python type hints.
+
+This is a fit for command-line users; I’m sharing it here to get feedback, not to spam the subreddit.
+
+It focuses on the repo metadata and README.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+If this fits the community, I’d appreciate feedback on the launch angle and any missing context.
+
+## Notes
+- Confidence: high
+
+# Twitter/X Thread
+
+## Tweet 1
+The launch story for pydantic/pydantic should start with data validation using python type hints, not the implementation details.
+
+## Tweet 2
+The hard part isn’t the code; it’s explaining why data validation using python type hints matters to the right audience.
+
+## Tweet 3
+This kit turns the repo’s own signals into a tighter launch story without inventing traction.
+
+## Tweet 4
+It reads the README + GitHub metadata, then drafts Show HN, Product Hunt, Reddit, and X posts that stay close to the repo. The supporting detail I’d foreground is readme and metadata.
+
+## Tweet 5
+Feedback welcome on the repo angle: add the repo link before posting
+
+## Notes
+- Confidence: high
+
+# First-Week Launch Plan
+
+## Day 0
+Prep the launch copy, verify links, and trim anything that sounds generic for pydantic/pydantic before posting.
+
+## Launch day
+Post the Show HN draft, Product Hunt draft, 5 Reddit variants, and the X thread. Keep replies factual and point people to the repo.
+
+## Day 1-2
+Respond to feedback, update the README if commenters point out missing context, and tighten the launch framing around data validation using python type hints for end users.
+
+## Day 3-7
+Publish a short follow-up post or changelog note, answer questions in communities where you posted, and reuse useful feedback to improve docs, examples, or onboarding.
+
+## Notes
+- Confidence: high
+
+# Assumptions / Low-Confidence Notes
+
+- Confidence: high

package/skills/oss-launch-kit/evals/vercel-next-js.full.md

@@ -0,0 +1,152 @@
+# Launch Kit
+
+## Repo Summary
+vercel/next.js
+
+## Audience
+authors and maintainers
+
+## Description
+The React Framework
+
+# Show HN Draft
+
+## Title
+Show HN: vercel/next.js - The React Framework
+
+## Short Intro
+Low-confidence repo context. Title-only draft recommended.
+
+## Core Explanation
+Not enough README signal to write a reliable body.
+
+## Feedback Ask
+Please review the repo framing and README quality before posting.
+
+## Notes
+- Confidence: high
+
+# Product Hunt Draft
+
+## Tagline
+vercel/next.js: framework for authors and maintainers
+
+## Description
+Built for authors and maintainers. Keeps the pitch grounded in repo facts.
+
+## Maker Comment
+Draft only. Edit before posting.
+
+## Notes
+- Confidence: high
+
+# Reddit Drafts
+
+## Variant 1
+Subreddit: r/SideProject (general maker context)
+
+I built vercel/next.js for authors and maintainers because the react framework.
+
+This is a fit for general maker context; I’m sharing it here to get feedback, not to spam the subreddit.
+
+It focuses on the repo metadata and README.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+If this fits the community, I’d appreciate feedback on the launch angle and any missing context.
+
+## Variant 2
+Subreddit: r/opensource (open-source launch context)
+
+I built vercel/next.js for authors and maintainers because the react framework and I think the interesting part is the launch workflow, not the code itself.
+
+I’m posting in open-source launch context because it’s an OSS launch question first and a product post second.
+
+The repo signals I leaned on were README text and metadata.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+Curious whether this framing would land with open-source launch context.
+
+## Variant 3
+Subreddit: r/programming (developer audience)
+
+I built vercel/next.js for authors and maintainers because the react framework, and the challenge was keeping the launch copy specific without turning it into jargon.
+
+For developer audience, I’d mainly want feedback on whether the problem/solution framing is actually useful to builders.
+
+The repo cues I used were The React Framework and README details.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+Would this problem/solution framing feel useful to builders in developer audience?
+
+## Variant 4
+Subreddit: r/devtools (developer tools audience)
+
+I built vercel/next.js for authors and maintainers because the react framework and I wanted a cleaner way to turn repo facts into launch copy.
+
+This angle fits developer tools audience; I’m sharing it for feedback on the workflow, not as a promo blast.
+
+The main angle here is The React Framework, with README details as supporting context.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+Would this problem/solution framing feel useful to builders in developer tools audience?
+
+## Variant 5
+Subreddit: r/commandline (command-line users)
+
+I built vercel/next.js for authors and maintainers because the react framework.
+
+This is a fit for command-line users; I’m sharing it here to get feedback, not to spam the subreddit.
+
+It focuses on the repo metadata and README.
+
+I built this myself and will only post where the subreddit rules allow self-promo.
+
+If this fits the community, I’d appreciate feedback on the launch angle and any missing context.
+
+## Notes
+- Confidence: high
+
+# Twitter/X Thread
+
+## Tweet 1
+The launch story for vercel/next.js should start with the react framework, not the implementation details.
+
+## Tweet 2
+The hard part isn’t the code; it’s explaining why the react framework matters to the right audience.
+
+## Tweet 3
+This kit turns the repo’s own signals into a tighter launch story without inventing traction.
+
+## Tweet 4
+It reads the README + GitHub metadata, then drafts Show HN, Product Hunt, Reddit, and X posts that stay close to the repo. The supporting detail I’d foreground is readme and metadata.
+
+## Tweet 5
+Feedback welcome on the repo angle: add the repo link before posting
+
+## Notes
+- Confidence: high
+
+# First-Week Launch Plan
+
+## Day 0
+Prep the launch copy, verify links, and trim anything that sounds generic for vercel/next.js before posting.
+
+## Launch day
+Post the Show HN draft, Product Hunt draft, 5 Reddit variants, and the X thread. Keep replies factual and point people to the repo.
+
+## Day 1-2
+Respond to feedback, update the README if commenters point out missing context, and tighten the launch framing around the react framework for authors and maintainers.
+
+## Day 3-7
+Publish a short follow-up post or changelog note, answer questions in communities where you posted, and reuse useful feedback to improve docs, examples, or onboarding.
+
+## Notes
+- Confidence: high
+
+# Assumptions / Low-Confidence Notes
+
+- Confidence: high

package/skills/oss-launch-kit/references/channel_rules.md

@@ -0,0 +1,9 @@
+# Channel Rules
+
+This file will hold the operational constraints for each launch channel.
+
+Planned channels:
+- Show HN
+- Product Hunt
+- Reddit
+- Twitter/X

package/skills/oss-launch-kit/references/launch_framework.md

@@ -0,0 +1,10 @@
+# Launch Framework
+
+This file will hold the canonical launch brief structure for `oss-launch-kit`.
+
+Planned sections:
+- repo summary
+- audience and problem framing
+- evidence inventory
+- launch angle
+- channel notes

package/skills/oss-launch-kit/references/output_template.md

@@ -0,0 +1,3 @@
+# Output Template
+
+This file will define the final Markdown layout for the generated launch kit.