@opendirectory.dev/skills 0.1.38 → 0.1.40

package/skills/product-update-logger/references/content-rules.md

@@ -0,0 +1,154 @@
+# Content Rules Reference
+
+## One-liner
+
+- Max 20 words
+- Cover the 1-2 biggest items
+- Plain language -- no jargon, no product name unless ambiguous
+- No period required
+- Not a tagline -- just a summary of what shipped
+
+**Good:**
+- "Dark mode, faster API, and a fix for the export bug."
+- "CSV export is live and the login bug is gone."
+- "Redesigned onboarding with two new integrations."
+
+**Bad:**
+- "Exciting new features have been released this week." (vague)
+- "We are pleased to announce several improvements to our platform." (corporate)
+- "Dark mode toggle in Settings > Appearance with full cross-view support plus 40% API response time improvement and off-by-one iterator fix." (too long)
+
+## Tweet Thread Rules
+
+**Structure (3-5 tweets):**
+- Tweet 1: Hook. "We shipped [N] things this week." OR lead with the biggest feature.
+- Tweets 2-N: One item per tweet, 1-2 sentences max. Specific, concrete.
+- Last tweet: Optional CTA -- "Changelog: [link]" or "More next week." Keep it light.
+
+**Hard rules:**
+- Each tweet strictly under 280 characters (count spaces and punctuation)
+- No hashtags -- ever
+- No em dashes (use hyphen or rewrite)
+- Active voice: "Dark mode is live" not "Dark mode has been added"
+- No promotional language ("game-changing", "revolutionize", "excited to share")
+- No markdown formatting
+- Thread numbering: 1/4, 2/4 style is optional -- skip if it feels forced
+
+**Good tweet:**
+"Dark mode is live. Toggle it in Settings > Appearance. Works everywhere."
+
+**Bad tweet:**
+"We're thrilled to announce that dark mode -- a highly requested feature -- has been added to the settings panel and is now available across all views! #darkmode #productupdate"
+
+## LinkedIn Post Rules
+
+**Format:**
+- No markdown. No asterisks (**bold** renders as **bold** on LinkedIn). No underscores.
+- No hashtags -- ever
+- Short paragraphs: 1-2 sentences, then blank line
+- Total: 150-400 words
+
+**Voice:**
+- Founder voice: "We shipped", "We fixed", "We added"
+- Not corporate: never "We are excited to announce", "We are pleased to share", "We are thrilled"
+- Direct: state the fact, then the benefit
+- Close with a question or observation, not a CTA ("What are you waiting for?" is a CTA -- avoid)
+
+**Hook (first line):**
+- Under 150 characters (LinkedIn truncates after ~210 chars before "see more")
+- "We shipped [N] updates this week." or lead with the biggest item
+- Formula options:
+  1. "We shipped [N] things this week."
+  2. "[Biggest feature] is live."
+  3. "This week: [feature], [fix], and [improvement]."
+
+**Body:**
+- One paragraph per major item (2-3 sentences max per paragraph)
+- Start with what it does, then why it matters
+- Skip Under the hood items -- users don't care
+- Blank line between paragraphs
+
+**Close:**
+- One line
+- A question that invites response: "What have you been waiting for us to ship next?"
+- Or an observation: "Smaller releases, shipped more often -- that's the goal."
+- Not: "Check out the full changelog at [link]" (that's a CTA)
+
+**Good opening:**
+```
+We shipped 3 updates this week.
+
+Dark mode is live. Toggle it in Settings under Appearance.
+
+API response time is down 40%. The dashboard now loads in under a second.
+
+We also fixed a bug where CSV exports were silently dropping the last row.
+
+What feature have you been waiting for?
+```
+
+## Email Snippet Rules
+
+**Subject line formula:**
+"What shipped this week: [biggest item] + [1 more]"
+
+Examples:
+- "What shipped this week: dark mode + faster API"
+- "What shipped this week: CSV export + 3 bug fixes"
+- "What shipped this week: onboarding redesign"
+
+**Body:**
+- 50-100 words
+- Casual, direct. Open with "Here's what we shipped this week:"
+- Bullet list of top 3-4 items with one-line descriptions
+- No marketing language
+- Appropriate for a product newsletter or drip sequence
+
+**Good:**
+```
+Subject: What shipped this week: dark mode + faster API
+
+Here's what we shipped this week:
+
+- Dark mode: toggle in Settings > Appearance
+- API response time: 40% faster, dashboard loads under 1 second
+- Fixed: CSV exports no longer drop the last row
+
+Full changelog below.
+```
+
+## Banned Words
+
+Never use these in any content piece:
+
+- powerful
+- robust
+- seamless
+- innovative
+- game-changing
+- streamline / streamlined
+- leverage
+- transform / transformative
+- revolutionize / revolutionary
+- excited to announce
+- pleased to announce
+- we are thrilled
+- cutting-edge
+- best-in-class
+- world-class
+- next-level
+- unlock
+- delightful
+
+## Anti-Patterns
+
+| Pattern | Why it's wrong |
+|---|---|
+| "We are excited to announce..." | Corporate speak. Say "We shipped." |
+| Hashtags in LinkedIn | This skill never uses hashtags |
+| **bold** in LinkedIn | Renders as literal asterisks |
+| Em dashes (--) in tweets | Use hyphen or rewrite the sentence |
+| Inventing numbers ("3x faster") | Only include metrics present in the source data |
+| Vague superlatives ("major update") | Be specific about what shipped |
+| Padding with filler items | If there's one real item, write about one item |
+| Thread recap tweet ("That's a wrap!") | Wastes a tweet -- skip it |

package/skills/product-update-logger/references/noise-filter.md

@@ -0,0 +1,86 @@
+# Noise Filter Reference
+
+## Commit Patterns to Skip
+
+These regex patterns match commits that should be excluded from the changelog:
+
+```
+^Merge (pull request|branch)\b          -- merge commits
+^(bump|update) version\b               -- version bumps
+^chore[\s:(]                           -- chore commits (chore: ..., chore(...):)
+^ci[\s:(]                              -- CI/CD commits
+^build[\s:(]                           -- build system commits
+^test[\s:(]                            -- test-only commits
+^docs[\s:(]                            -- documentation-only commits
+^style[\s:(]                           -- formatting/style commits
+^fix typo\b                            -- typo fixes
+^\s*typo\b                             -- typo commits
+^wip\b                                 -- work in progress
+^revert\b                              -- reverts (usually indicate something broken)
+^Initial commit$                       -- first commit
+^init$                                 -- init commits
+single-word subject under 8 chars      -- too vague to be useful
+```
+
+## Examples: Skip
+
+```
+Merge pull request #45 from user/feature-branch     -> skip (merge commit)
+Merge branch 'main' into feature                    -> skip (merge commit)
+bump version to 1.3.2                               -> skip (version bump)
+Update version: 2.0.1                               -> skip (version bump)
+chore: update dependencies                          -> skip (chore)
+chore(deps): bump lodash to 4.17.21                 -> skip (chore)
+ci: fix GitHub Actions workflow                     -> skip (CI)
+build: update webpack config                        -> skip (build)
+test: add unit tests for auth module                -> skip (test-only)
+docs: update README                                 -> skip (docs-only)
+style: fix linting errors                           -> skip (style)
+fix typo in error message                           -> skip (typo)
+wip: experimenting with new approach                -> skip (WIP)
+revert "Add experimental feature"                   -> skip (revert)
+Initial commit                                      -> skip
+Update                                              -> skip (single word, under 8 chars)
+Fix                                                 -> skip (single word, under 8 chars)
+```
+
+## Examples: Keep
+
+Even vague commits that don't match noise patterns should be kept and passed to the AI for judgment:
+
+```
+Update dashboard layout                             -> keep (AI will decide if useful)
+Improve error messages for API validation           -> keep
+Add dark mode toggle in Settings                    -> keep
+Fix timezone bug in scheduler                       -> keep
+Refactor authentication flow                        -> keep (even though technical)
+Increase connection pool size                       -> keep (performance-relevant)
+Add rate limiting to public API endpoints           -> keep (developer-relevant)
+Fix off-by-one error in CSV row iterator            -> keep (specific bug)
+```
+
+## PR Labels to Skip
+
+These GitHub PR labels indicate noise:
+
+```
+documentation
+chore
+dependencies
+ci
+test
+tests
+```
+
+## What the AI Does With Kept Items
+
+The AI (in Step 4 of the skill) has final discretion over:
+- Vague commits like "Update dashboard layout" -- may omit if unclear
+- "Under the hood" items -- only includes if developer-relevant
+- Categorization -- assigns each item to New, Improved, Fixed, or Under the hood
+
+The noise filter's job is to remove obvious non-user-facing commits before they reach the AI. The AI handles the judgment calls.
+
+## The Rule of Thumb
+
+If removing the commit from the list wouldn't confuse a user reading the changelog -- filter it out. If it might represent a real user-visible change (even if described technically) -- keep it and let the AI decide.

package/skills/product-update-logger/scripts/gather.py

@@ -0,0 +1,364 @@
+#!/usr/bin/env python3
+"""
+product-update-logger gather script
+Collects shipped items from git commits, GitHub PRs, and free text.
+No required API keys. GITHUB_TOKEN optional (enables GitHub PR fetching).
+
+Usage:
+    python3 scripts/gather.py --since 7 --output /tmp/pul-raw.json
+    python3 scripts/gather.py --items "Add dark mode|Fix CSV bug" --output /tmp/pul-raw.json
+    GITHUB_TOKEN=your_token python3 scripts/gather.py --repo owner/repo --since 14
+    python3 scripts/gather.py --stdout | jq '.items'
+"""
+
+import argparse
+import json
+import os
+import re
+import ssl
+import subprocess
+import sys
+from datetime import datetime, timedelta, timezone
+
+_ssl_ctx = ssl._create_unverified_context()
+
+TODAY = datetime.now(timezone.utc)
+GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
+
+quiet = False
+
+
+# ---------------------------------------------------------------------------
+# HTTP helpers (reused from map-your-market pattern)
+# ---------------------------------------------------------------------------
+
+def fetch_json(url, headers=None, timeout=20):
+    import urllib.request, urllib.error
+    req = urllib.request.Request(url, headers=headers or {})
+    req.add_header("User-Agent", "product-update-logger/1.0")
+    try:
+        with urllib.request.urlopen(req, context=_ssl_ctx, timeout=timeout) as r:
+            return json.loads(r.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        if not quiet:
+            print(f"  HTTP {e.code}: {url[:80]}", file=sys.stderr)
+        return None
+    except Exception as e:
+        if not quiet:
+            print(f"  Error: {e} -- {url[:80]}", file=sys.stderr)
+        return None
+
+
+def gh_get(path):
+    import urllib.request
+    headers = {"Accept": "application/vnd.github+json"}
+    if GITHUB_TOKEN:
+        headers["Authorization"] = f"Bearer {GITHUB_TOKEN}"
+    return fetch_json(f"https://api.github.com{path}", headers=headers)
+
+
+# ---------------------------------------------------------------------------
+# Noise filter patterns
+# ---------------------------------------------------------------------------
+
+NOISE_PATTERNS = [
+    re.compile(r"^Merge (pull request|branch)\b", re.IGNORECASE),
+    re.compile(r"^(bump|update) version\b", re.IGNORECASE),
+    re.compile(r"^chore[\s:(]", re.IGNORECASE),
+    re.compile(r"^ci[\s:(]", re.IGNORECASE),
+    re.compile(r"^build[\s:(]", re.IGNORECASE),
+    re.compile(r"^fix typo\b", re.IGNORECASE),
+    re.compile(r"^\s*typo\b", re.IGNORECASE),
+    re.compile(r"^wip\b", re.IGNORECASE),
+    re.compile(r"^test[\s:(]", re.IGNORECASE),
+    re.compile(r"^docs[\s:(]", re.IGNORECASE),
+    re.compile(r"^style[\s:(]", re.IGNORECASE),
+    re.compile(r"^revert\b", re.IGNORECASE),
+    re.compile(r"^Initial commit$", re.IGNORECASE),
+    re.compile(r"^init$", re.IGNORECASE),
+]
+
+NOISE_PR_LABELS = {"documentation", "chore", "dependencies", "ci", "test", "tests"}
+
+
+def filter_noise(commits: list) -> list:
+    filtered = []
+    for c in commits:
+        subject = c.get("subject", "").strip()
+        if not subject:
+            continue
+        # Skip single-word subjects under 8 chars
+        if len(subject.split()) == 1 and len(subject) < 8:
+            continue
+        skip = False
+        for pat in NOISE_PATTERNS:
+            if pat.match(subject):
+                skip = True
+                break
+        if not skip:
+            filtered.append(c)
+    return filtered
+
+
+# ---------------------------------------------------------------------------
+# Git commits
+# ---------------------------------------------------------------------------
+
+def get_git_commits(since_days: int, repo_path: str = ".") -> list:
+    try:
+        result = subprocess.run(
+            [
+                "git", "-C", repo_path, "log",
+                f"--since={since_days} days ago",
+                "--pretty=format:%H|%s|%b|%ad",
+                "--date=short",
+            ],
+            capture_output=True, text=True, timeout=30
+        )
+        if result.returncode != 0:
+            return []
+        commits = []
+        for line in result.stdout.strip().split("\n"):
+            if not line.strip():
+                continue
+            parts = line.split("|", 3)
+            commit_hash = parts[0].strip() if len(parts) > 0 else ""
+            subject = parts[1].strip() if len(parts) > 1 else ""
+            body = parts[2].strip() if len(parts) > 2 else ""
+            date = parts[3].strip() if len(parts) > 3 else ""
+            if subject:
+                commits.append({
+                    "subject": subject,
+                    "body": body,
+                    "source": "git_commit",
+                    "hash": commit_hash[:7],
+                    "date": date,
+                })
+        return commits
+    except FileNotFoundError:
+        if not quiet:
+            print("  git not installed -- skipping git commits", file=sys.stderr)
+        return []
+    except Exception as e:
+        if not quiet:
+            print(f"  git error: {e}", file=sys.stderr)
+        return []
+
+
+# ---------------------------------------------------------------------------
+# GitHub PRs
+# ---------------------------------------------------------------------------
+
+def get_github_prs(repo: str, since_date: str) -> list:
+    if not GITHUB_TOKEN:
+        if not quiet:
+            print("  GITHUB_TOKEN not set -- skipping GitHub PRs", file=sys.stderr)
+        return []
+    if not repo:
+        return []
+
+    data = gh_get(f"/repos/{repo}/pulls?state=closed&sort=updated&direction=desc&per_page=50")
+    if not data:
+        return []
+
+    prs = []
+    for pr in data:
+        merged_at = pr.get("merged_at")
+        if not merged_at:
+            continue
+        # Filter by since_date
+        merged_date = merged_at[:10]
+        if merged_date < since_date:
+            continue
+        labels = [lbl["name"].lower() for lbl in (pr.get("labels") or [])]
+        # Skip PRs with noise labels
+        if any(lbl in NOISE_PR_LABELS for lbl in labels):
+            continue
+        prs.append({
+            "subject": pr.get("title", "").strip(),
+            "body": (pr.get("body") or "").strip()[:500],
+            "source": "github_pr",
+            "pr_number": pr.get("number"),
+            "merged_at": merged_at[:10],
+            "labels": labels,
+        })
+    return prs
+
+
+# ---------------------------------------------------------------------------
+# Free text input
+# ---------------------------------------------------------------------------
+
+def parse_free_text(items_str: str) -> list:
+    if not items_str or not items_str.strip():
+        return []
+    items = []
+    for item in re.split(r"[|\n]", items_str):
+        item = item.strip()
+        if item:
+            items.append({"subject": item, "source": "free_text"})
+    return items
+
+
+# ---------------------------------------------------------------------------
+# Deduplication
+# ---------------------------------------------------------------------------
+
+def deduplicate(commits: list, prs: list) -> list:
+    result = list(prs)
+    pr_titles = [pr["subject"].lower() for pr in prs]
+
+    for commit in commits:
+        subject = commit["subject"].lower()
+        is_dup = False
+        for pr_title in pr_titles:
+            # If commit subject is substring of PR title or vice versa -> same item
+            if subject in pr_title or pr_title in subject:
+                is_dup = True
+                break
+        if not is_dup:
+            result.append(commit)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Existing changelog detection
+# ---------------------------------------------------------------------------
+
+def detect_existing_changelog(path: str = "docs/changelog.md") -> dict:
+    if not os.path.exists(path):
+        return {"exists": False, "last_label": "", "format": "date-based"}
+
+    try:
+        with open(path) as f:
+            lines = [f.readline() for _ in range(100)]
+        lines = [l.rstrip() for l in lines if l.strip()]
+    except Exception:
+        return {"exists": True, "last_label": "", "format": "date-based"}
+
+    last_label = ""
+    version_format = "date-based"
+
+    for line in lines:
+        # Look for ## headings (changelog entry labels)
+        m = re.match(r"^## (.+)$", line)
+        if m:
+            last_label = m.group(1).strip()
+            # Detect semver format
+            if re.match(r"^v?\d+\.\d+\.\d+", last_label):
+                version_format = "semver"
+            break
+
+    return {"exists": True, "last_label": last_label, "format": version_format}
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    global quiet
+
+    parser = argparse.ArgumentParser(description="Gather shipped items for product-update-logger")
+    parser.add_argument("--since", default="7",
+                        help="Days back to look, or YYYY-MM-DD date (default: 7)")
+    parser.add_argument("--repo", default="",
+                        help="GitHub repo as owner/repo for PR fetching")
+    parser.add_argument("--items", default="",
+                        help="Pipe-separated free text items")
+    parser.add_argument("--output", default="/tmp/pul-raw.json",
+                        help="Output file path (default: /tmp/pul-raw.json)")
+    parser.add_argument("--stdout", action="store_true",
+                        help="Print JSON to stdout instead of file")
+    parser.add_argument("--quiet", action="store_true",
+                        help="Suppress progress output")
+    args = parser.parse_args()
+
+    quiet = args.quiet
+    use_stdout = args.stdout
+
+    def log(msg):
+        if not quiet:
+            print(msg, file=sys.stderr if use_stdout else sys.stdout)
+
+    # Resolve since_days and since_date
+    since_str = args.since.strip()
+    if re.match(r"^\d{4}-\d{2}-\d{2}$", since_str):
+        since_date = since_str
+        delta = TODAY.date() - datetime.strptime(since_str, "%Y-%m-%d").date()
+        since_days = max(delta.days, 1)
+    else:
+        since_days = int(since_str)
+        since_date = (TODAY - timedelta(days=since_days)).strftime("%Y-%m-%d")
+
+    today_str = TODAY.strftime("%Y-%m-%d")
+
+    log(f"Gathering items since {since_date} ({since_days} days)...")
+
+    # 1. Free text items
+    free_text_items = parse_free_text(args.items)
+    if free_text_items:
+        log(f"  Free text: {len(free_text_items)} items")
+
+    # 2. Git commits
+    git_available = False
+    raw_commits = []
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            capture_output=True, text=True, timeout=5
+        )
+        git_available = result.returncode == 0
+    except Exception:
+        git_available = False
+
+    noise_filtered = 0
+    if git_available:
+        raw_commits = get_git_commits(since_days)
+        before = len(raw_commits)
+        raw_commits = filter_noise(raw_commits)
+        noise_filtered = before - len(raw_commits)
+        log(f"  Git: {len(raw_commits)} commits ({noise_filtered} noise filtered)")
+
+    # 3. GitHub PRs
+    github_available = bool(GITHUB_TOKEN and args.repo)
+    prs = []
+    if github_available:
+        prs = get_github_prs(args.repo, since_date)
+        log(f"  GitHub PRs: {len(prs)} merged PRs")
+
+    # 4. Deduplicate commits + PRs
+    combined = deduplicate(raw_commits, prs)
+
+    # 5. Merge with free text (free text first, then git/PR items)
+    all_items = free_text_items + combined
+    free_text_provided = bool(free_text_items)
+
+    # 6. Detect existing changelog
+    existing_changelog = detect_existing_changelog()
+
+    output = {
+        "date": today_str,
+        "since_date": since_date,
+        "since_days": since_days,
+        "git_available": git_available,
+        "github_available": github_available,
+        "free_text_provided": free_text_provided,
+        "items": all_items,
+        "total_items": len(all_items),
+        "noise_filtered": noise_filtered,
+        "existing_changelog": existing_changelog,
+    }
+
+    if use_stdout:
+        print(json.dumps(output, indent=2))
+    else:
+        with open(args.output, "w") as f:
+            json.dump(output, f, indent=2)
+        log(f"\nOutput: {args.output}")
+        log(f"Total items: {len(all_items)}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/where-your-customer-lives/.env.example

@@ -0,0 +1,4 @@
+GITHUB_TOKEN=      # optional -- github.com/settings/tokens (no scopes needed for public repos)
+                   # Without it: competitor layer GitHub enrichment runs at 60 req/hr
+                   # With it: 5000 req/hr -- use if scanning many competitors
+                   # Core channel discovery (Reddit + DuckDuckGo) works without any token