@bompus/house-rules 0.0.0-stage → 0.11.0

package/skills/hr-read-x-links/scripts/x-post.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env bun
+// Read X/Twitter posts through the public fxtwitter API: full text, expanded
+// links, quoted posts, long-form articles, and downloadable images.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs as parseCli } from "node:util";
+
+const API = "https://api.fxtwitter.com";
+// pbs.twimg.com answers 403 without a browser-like user agent.
+const HEADERS = { "user-agent": "Mozilla/5.0" };
+const HOSTS = /^(?:www\.|mobile\.)?(?:x|twitter|fixupx|fxtwitter|vxtwitter|fixvx)\.com$/;
+
+// The parts of fxtwitter's response this script reads.
+type Facet = { type?: string; original?: string; replacement?: string; indices: [number, number] };
+type ArticleMedia = { media_id?: string; media_info?: { original_img_url?: string } };
+type Block = { type?: string; text?: string; entityRanges?: { key?: number | string }[] };
+type Entity = { type?: string; data?: { mediaItems?: { mediaId?: string }[] } };
+export type Article = {
+  title?: string;
+  content?: { blocks?: Block[]; entityMap?: { key: number | string; value: Entity }[] };
+  cover_media?: ArticleMedia;
+  media_entities?: ArticleMedia[];
+};
+export type Tweet = {
+  id: string;
+  url?: string;
+  text?: string;
+  created_at?: string;
+  raw_text?: { text?: string; facets?: Facet[] };
+  author?: { screen_name?: string; name?: string };
+  replying_to?: string;
+  replying_to_status?: string;
+  media?: {
+    photos?: { url: string }[];
+    videos?: { url: string; thumbnail_url?: string; duration?: number }[];
+  };
+  article?: Article;
+  quote?: Tweet;
+};
+
+/** `{ user, id }` for a post URL on x.com or a known mirror; null otherwise. */
+export function parseStatusUrl(input: string): { user: string; id: string } | null {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+  if (!HOSTS.test(url.hostname)) {
+    return null;
+  }
+  const match = /^\/([^/]+)\/status(?:es)?\/(\d+)/.exec(url.pathname);
+  return match ? { user: match[1]!, id: match[2]! } : null;
+}
+
+/** Post text with t.co links replaced by their targets. */
+export function expandedText(tweet: Tweet): string {
+  const text = tweet.raw_text?.text ?? tweet.text ?? "";
+  const facets = (tweet.raw_text?.facets ?? [])
+    .filter((f) => f.type === "url" && f.original && f.replacement)
+    .sort((a, b) => b.indices[0] - a.indices[0]);
+  let out = text;
+  for (const f of facets) {
+    out = out.slice(0, f.indices[0]) + f.replacement + out.slice(f.indices[1]);
+  }
+  return out;
+}
+
+export type Photo = { url: string; id: string | null };
+
+/**
+ * Article body as Markdown-ish text. An image block becomes `[image N]`, where N
+ * is that image's position in `mediaOf(tweet).photos` (and its downloaded file).
+ */
+export function articleText(article: Article | undefined, photos: Photo[] = []): string {
+  const blocks = article?.content?.blocks ?? [];
+  const entities = new Map(
+    (article?.content?.entityMap ?? []).map((e) => [String(e.key), e.value]),
+  );
+  const lines: string[] = [];
+  let ordered = 0;
+  for (const block of blocks) {
+    const text = (block.text ?? "").trim();
+    if (block.type !== "ordered-list-item") {
+      ordered = 0;
+    }
+    if (block.type === "atomic") {
+      const entity = entities.get(String(block.entityRanges?.[0]?.key));
+      const mediaId = entity?.type === "MEDIA" ? entity.data?.mediaItems?.[0]?.mediaId : null;
+      if (mediaId) {
+        const n = photos.findIndex((p) => p.id === mediaId);
+        lines.push(n >= 0 ? `[image ${n + 1}]` : "[image]");
+      }
+      continue;
+    }
+    if (!text) {
+      continue;
+    }
+    if (block.type === "header-one") {
+      lines.push(`# ${text}`);
+    } else if (block.type === "header-two") {
+      lines.push(`## ${text}`);
+    } else if (block.type === "unordered-list-item") {
+      lines.push(`- ${text}`);
+    } else if (block.type === "ordered-list-item") {
+      lines.push(`${++ordered}. ${text}`);
+    } else if (block.type === "blockquote") {
+      lines.push(`> ${text}`);
+    } else {
+      lines.push(text);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Every image and video a post carries, including article images. */
+export function mediaOf(tweet: Tweet): {
+  photos: Photo[];
+  videos: { url: string; thumbnail?: string; duration?: number }[];
+} {
+  const photos: Photo[] = (tweet.media?.photos ?? []).map((p) => ({ url: p.url, id: null }));
+  const article = tweet.article;
+  for (const m of [article?.cover_media, ...(article?.media_entities ?? [])]) {
+    if (m?.media_info?.original_img_url) {
+      photos.push({ url: m.media_info.original_img_url, id: m.media_id ?? null });
+    }
+  }
+  const videos = (tweet.media?.videos ?? []).map((v) => ({
+    url: v.url,
+    thumbnail: v.thumbnail_url,
+    duration: v.duration,
+  }));
+  return { photos, videos };
+}
+
+async function fetchPost(user: string, id: string): Promise<Tweet> {
+  const res = await fetch(`${API}/${user}/status/${id}`, { headers: HEADERS });
+  const body = (await res.json().catch(() => null)) as { tweet?: Tweet; message?: string } | null;
+  if (!res.ok || !body?.tweet) {
+    throw new Error(`${user}/status/${id}: HTTP ${res.status} ${body?.message ?? ""}`.trim());
+  }
+  return body.tweet;
+}
+
+async function download(url: string, path: string): Promise<string> {
+  const res = await fetch(url, { headers: HEADERS });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status}`);
+  }
+  writeFileSync(path, Buffer.from(await res.arrayBuffer()));
+  return path;
+}
+
+async function render(tweet: Tweet, mediaDir: string | null, label: string): Promise<string> {
+  const out: string[] = [];
+  const a = tweet.author ?? {};
+  out.push(`### ${label}: @${a.screen_name} (${a.name ?? ""}) · ${tweet.created_at}`);
+  out.push(tweet.url ?? "");
+  if (tweet.replying_to) {
+    out.push(
+      `Reply to @${tweet.replying_to} (${tweet.replying_to_status}); earlier thread posts are not included.`,
+    );
+  }
+  out.push("", expandedText(tweet));
+  const { photos, videos } = mediaOf(tweet);
+  if (tweet.article) {
+    out.push("", `#### Article: ${tweet.article.title}`, "", articleText(tweet.article, photos));
+  }
+  for (const [i, { url }] of photos.entries()) {
+    if (!mediaDir) {
+      out.push(`image ${i + 1}: ${url}`);
+      continue;
+    }
+    const ext = /\.(\w+)(?:\?|$)/.exec(url)?.[1] ?? "jpg";
+    const path = join(mediaDir, `${tweet.id}-${i + 1}.${ext}`);
+    out.push(
+      `image ${i + 1}: ${await download(url, path).catch((e: unknown) => `${url} (download failed: ${e instanceof Error ? e.message : String(e)})`)}`,
+    );
+  }
+  for (const [i, v] of videos.entries()) {
+    out.push(
+      `video ${i + 1} (${v.duration ?? "?"}s, not readable as text): ${v.url} thumbnail: ${v.thumbnail}`,
+    );
+  }
+  return out.join("\n");
+}
+
+export function parseArgs(argv: string[]): {
+  mediaDir: string | null;
+  urls: string[];
+  error?: string;
+} {
+  let parsed;
+  try {
+    parsed = parseCli({
+      args: argv,
+      allowPositionals: true,
+      options: { "media-dir": { type: "string" } },
+    });
+  } catch (error) {
+    return {
+      mediaDir: null,
+      urls: [],
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  const mediaDir = parsed.values["media-dir"] ?? null;
+  // A forgotten directory would otherwise take the first URL as its value.
+  if (mediaDir !== null && /^https?:/i.test(mediaDir)) {
+    return { mediaDir: null, urls: [], error: "--media-dir needs a directory value" };
+  }
+  return { mediaDir, urls: parsed.positionals };
+}
+
+async function main(argv: string[]): Promise<number> {
+  const { mediaDir, urls, error } = parseArgs(argv);
+  if (error || urls.length === 0) {
+    if (error) {
+      console.error(error);
+    }
+    console.error("usage: x-post.ts [--media-dir DIR] <x.com status URL>...");
+    return 2;
+  }
+  if (mediaDir) {
+    mkdirSync(mediaDir, { recursive: true });
+  }
+  let failed = 0;
+  for (const input of urls) {
+    const ref = parseStatusUrl(input);
+    if (!ref) {
+      console.log(`## ${input}\nnot an X post URL\n`);
+      failed++;
+      continue;
+    }
+    try {
+      const tweet = await fetchPost(ref.user, ref.id);
+      const parts = [await render(tweet, mediaDir, "Post")];
+      // The embedded quote omits its article and full media; fetch it directly.
+      if (tweet.quote) {
+        const embedded = tweet.quote;
+        let quote = embedded;
+        try {
+          quote = await fetchPost(embedded.author?.screen_name ?? "i", embedded.id);
+        } catch (error) {
+          parts.push(
+            `Quoted post fetch failed (${error instanceof Error ? error.message : String(error)}); showing the embedded copy, which can lack its article and full media.`,
+          );
+        }
+        parts.push(await render(quote, mediaDir, "Quoted post"));
+      }
+      console.log(`## ${input}\n${parts.join("\n\n")}\n`);
+    } catch (error) {
+      console.log(
+        `## ${input}\nfetch failed: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+      failed++;
+    }
+  }
+  return failed ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/skills/hr-split-to-prs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-split-to-prs/NOTICE.md

@@ -0,0 +1,9 @@
+# Source notice
+
+These instructions were written for house-rules. Their workflow purpose is
+informed by Cursor's built-in split-to-prs skill, described in its public catalogue:
+https://cursor.com/docs/skills
+
+No Cursor instruction text is distributed in this bundle. The MIT licence in
+LICENSE applies to the newly written house-rules material; it does not assert
+a licence for Cursor's skill text.

package/skills/hr-split-to-prs/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: hr-split-to-prs
+description: Split a branch, chat or set of changes into small reviewable PRs when the user asks to divide the work.
+---
+
+# Split work into pull requests
+
+Produce slices that can be reviewed and verified against their actual bases.
+A request for a split proposal authorizes analysis. Execute a selected split
+within the user's existing authorization; ask only about unresolved scope.
+Repository guidance owns checks, submission, landing and cleanup.
+
+## Establish what belongs to the task
+
+Identify the default branch and the checkout's committed, staged, unstaged and
+untracked work. Inspect ownership guidance for affected paths. Record other
+owners' changes separately and preserve them throughout the split.
+
+Describe each slice by its resulting behavior, affected paths and acceptance
+check. Divide independent concerns; keep changes together when separating them
+would break either slice or require temporary machinery with no outside user.
+
+For a real dependency, state which change must land first and why. Use a stack
+only when a slice cannot work against the default branch. Compatibility stages
+need an actual outside caller, released interface or stored-data constraint.
+An API replacement with no such dependency can migrate its callers and remove
+the old path together.
+
+Present the proposed PR titles and dependencies before moving work unless the
+user already selected that plan. Name any work left outside the split. A title
+that describes only part of a slice calls for a better title or a different cut.
+
+## Preserve and partition
+
+Before moving changes, establish a recovery point for all owned work. Committed
+work needs a retained commit or ref. Dirty tracked files and untracked files
+need a verified snapshot that preserves their contents. `git stash create`
+can capture tracked changes without altering the tree; it omits untracked files.
+Do not claim a backup is complete until those files are accounted for too.
+
+Choose isolated checkouts when the starting checkout is shared. For each
+selected slice, reconstruct only its owned changes on the intended base.
+Stage explicit paths or hunks and inspect the staged diff before committing.
+Do not discard the starting work or rewrite published history to obtain a clean
+slice. If a path mixes concerns, split its hunks only when each result remains
+correct; otherwise keep the dependent changes together.
+
+Verify each slice against the base it will actually target, including any
+required earlier slice. Run its relevant checks and every repository-required
+gate. A passing combined branch does not prove each separated PR works.
+
+Submit and land only within existing authorization through the repository's
+required path. Follow its rules for stacked targets and branch retirement.
+Preserve recovery material until cleanup is authorized and no owner needs it.
+
+## Account for the result
+
+Report each PR or retained branch, its base and verification result. Reconcile
+remaining working-tree files and commits against the original inventory.
+Identify blockers, other owners' work and any recovery material still retained.
+Use `hr-writing-pr` for PR text when that skill is available.

package/skills/hr-split-to-prs/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "HR: Split to PRs"

package/skills/hr-stock-ui-audit/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: hr-stock-ui-audit
+description: Find template-default styling in frontend code that nobody chose for this product (stock violet accents, purple-to-blue gradients, one stock font, emoji icons, glow and blur effects), triage each hit in context, and report or fix the real ones as the request asks. Use when asked to audit or remove generic or AI-looking styling in existing UI. It does not set a visual direction.
+---
+
+# Stock UI audit
+
+Generated and starter-kit interfaces share a recognizable look: an indigo or
+violet accent, a purple-to-blue hero gradient, Inter everywhere, frosted cards,
+emoji in the nav. None of these is wrong on its own. The problem is a choice
+that came with the template instead of from the product. This skill finds those
+choices with a static scanner, then sorts them by judgment. The scanner
+produces candidates; only triage produces findings.
+
+This skill removes unchosen defaults. It does not invent a brand. If the
+product has no visual direction yet, say so and ask for one rather than
+replacing one default with another.
+
+## Before you scan
+
+1. Read the brief, the design tokens and the theme or component-library config.
+   Note every color, font and component the product asked for. Those stay,
+   even when the scanner flags them.
+2. Settle the mode from the request:
+   - **Review**: report findings only. Edit nothing.
+   - **Cleanup**: fix confirmed findings, and only inside the area the user
+     named (a page, a component folder, the whole app). Report anything you
+     notice outside it instead of fixing it.
+3. Pick the scan scope: the source folders that render UI, not the whole
+   repository.
+
+## Run the scanner
+
+```sh
+bun <this skill's directory>/scripts/scan.mjs [--json] [--fail-on high|medium|low] <paths>...
+```
+
+Node 22 or later works too. It walks directories, skips dependency, build and
+coverage output and minified files, and reads `.html .css .scss .js .ts .jsx
+.tsx .vue .svelte .astro`. It prints the number of files scanned. Exit 0 means
+nothing reached the failing severity (high by default), 1 means something did,
+2 means bad usage or zero files scanned. A 2 is never a clean result. Pass
+`--fail-on medium` when violet accents, a single stock font or emoji icons
+should fail the run. Do not add the scanner as a CI gate unless asked.
+
+| Rule                    | Severity | Catches                                                                                                                                      |
+| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `purple-blue-gradient`  | high     | gradients whose stops are all cool hues with at least one violet, in CSS or Tailwind `from-`/`to-` classes                                   |
+| `violet-accent`         | medium   | any hex, rgb, hsl, oklch or bare HSL token whose computed hue lands in the indigo-to-purple band, plus Tailwind indigo/violet/purple classes |
+| `gradient-text`         | medium   | `background-clip: text` and `bg-clip-text`                                                                                                   |
+| `single-stock-font`     | medium   | one stock sans (Inter, Roboto, Poppins and similar) as the only named face across two or more declarations in the scanned set                |
+| `emoji-icon`            | medium   | emoji inside headings, buttons, links, nav items or `icon`/`label`/`title` fields                                                            |
+| `neon-glow`             | medium   | zero-offset, wide-blur shadows in a saturated color, and Tailwind colored shadows                                                            |
+| `frosted-glass`         | low      | `backdrop-filter: blur()` and `backdrop-blur`                                                                                                |
+| `library-default-token` | low      | untouched default primaries from Bootstrap, Material, MUI, Ant Design, Chakra, shadcn/ui and the Vite starter                                |
+| `tracked-caps`          | low      | uppercase text with wide letter spacing                                                                                                      |
+
+The font rule looks across every file in one run, so scan the whole UI scope
+together; scanning one file at a time hides it.
+
+## Triage every match
+
+Open each flagged line and read enough around it to see what the element is for.
+Give every match exactly one verdict:
+
+- **Unchosen default**: nothing in the brief, tokens or history asks for it,
+  and it reads like a starter template. This is a finding.
+- **Deliberate choice**: the brief, a token file, a brand guide or a commit
+  message shows someone picked it. Keep it and name the evidence.
+- **False positive**: the match is not doing what the rule assumes, such as a
+  violet hue in a syntax-highlighting theme, a blur on a modal backdrop over
+  busy content, or an emoji inside user-generated sample data. Leave it and say
+  why.
+- **Unresolved**: you cannot tell whether someone chose it. It is not a
+  finding and you change nothing. Report what is missing and the question
+  that would settle it.
+
+## Fixing what is real
+
+- Fix the cause, not the line. Five violet hexes usually mean one missing
+  accent token; define the product's palette and type once and point the
+  components at it.
+- Choose replacements that serve the content: contrast that holds, an accent
+  that marks the one action that matters, type that suits the reading load.
+- Never nudge a value just to leave the scanner's range, such as shifting a hue
+  a few degrees or swapping a hex for an equivalent `oklch()`. If the color is
+  wrong, change it; if it is right, keep it and record why.
+- Never change a brand color, a status color (success, warning, error) or a
+  focus indicator to make the scan pass. Those carry meaning; record them as
+  deliberate.
+- Replace emoji icons with the project's existing icon set. Add a new icon
+  dependency only if the user agrees.
+
+## What the scanner cannot see
+
+Check these by reading the rendered page, since no pattern match finds them:
+
+- every section built from the same centered headline, subtitle and two buttons
+- a three-card feature grid with an icon, title and line of text in each card
+- a small badge or pill sitting above the main heading
+- cards marked by a thick colored left border
+- a stat banner of large numbers ("10k+ users", "99.9% uptime")
+- numbered "1, 2, 3" step sections
+- a dark theme forced on with no light option the brief asked for
+- the same large corner radius and soft shadow on every surface
+- spacing and type sizes that ignore the project's scale
+- copy that could describe any product
+
+## Verify
+
+1. Rerun the scanner on the same scope and confirm each remaining match has a
+   recorded verdict.
+2. Look at the rendered UI at the sizes that matter (a narrow phone width and
+   a desktop width at least), in every theme the product ships.
+3. A clean scan says nothing about accessibility, layout or overall quality.
+   Check contrast and focus states on anything you changed.
+
+If you could not render the UI, say the review was static only.
+
+## Report
+
+Write the report in this order:
+
+1. Scope scanned, files scanned, mode, and the scanner's exit code.
+2. Findings fixed (or, in review mode, proposed), each with `file:line`, the
+   rule, and what replaced it.
+3. Matches kept as deliberate, each with its evidence.
+4. Unresolved matches, each with what is missing and the question that
+   settles it.
+5. False positives, each with one line on why.
+6. Issues the scanner cannot see, if you found any.
+7. How you verified: rerun result, sizes and themes viewed, or "static only".

package/skills/hr-stock-ui-audit/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Stock UI audit"
+  short_description: "Audit or clean up unchosen template styling in UI code"