rsc-universal 0.1.1

package/skills/shortform-ideation/scripts/verify.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# verify.sh — structurally lint emitted shortform-ideation artifacts.
+#
+# Usage:
+#   bash scripts/verify.sh 02-DOCS/shortform/            # lint a directory tree
+#   bash scripts/verify.sh 02-DOCS/shortform/backlog.md  # lint one file
+#   bash scripts/verify.sh                               # no target -> exit 0
+#
+# It checks STRUCTURE and LEGALITY, never idea quality (that is the capability eval):
+#
+#   Backlog files   (a markdown table mentioning the required header columns):
+#     - the header row names: id, idea, hook, trend, score, status
+#     - at least one data row exists under it
+#   Experiment files (under an experiments/ path, or any .md with a Hypothesis):
+#     - a "Hypothesis" line/heading is present
+#     - a dated trend signal is present (a YYYY-MM-DD date)
+#     - result fields are present (a "result:" / "## Result" marker)
+#   ALL artifacts:
+#     - no baked-in scraping command targeting creativecenter / ads.tiktok.com
+#       (curl|wget|fetch|scrape|headless against those hosts) — a ToS violation.
+#
+# Read-only: never writes, installs, or touches the network. Pure text parsing.
+# Exits 0 on clean artifacts AND on an empty/clean target (no false failure):
+#   - no argument                         -> "nothing to check", exit 0
+#   - directory with no relevant .md      -> "nothing to check", exit 0
+#   - a .md that is neither a backlog nor an experiment -> skipped, not failed
+# Exits non-zero only when a real, recognizable artifact breaks a rule.
+#
+# Portability: stock macOS bash 3.2. No mapfile, no associative arrays. set -u on,
+# set -e intentionally off (each check owns its exit handling).
+
+set -u
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+warn() { printf '%s\n' "${YELLOW}WARN: $1${RESET}"; }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+# --- collect targets -------------------------------------------------------
+if [ "$#" -eq 0 ]; then
+  printf '%s\n' "${YELLOW}Nothing to check (no path given). Pass a backlog/experiment .md or the 02-DOCS/shortform/ dir.${RESET}"
+  exit 0
+fi
+
+targets=""
+add_target() { targets="${targets}${targets:+
+}$1"; }
+
+for arg in "$@"; do
+  if [ -d "$arg" ]; then
+    # gather .md files recursively without relying on globstar
+    while IFS= read -r f; do
+      [ -n "$f" ] && add_target "$f"
+    done <<EOF
+$(find "$arg" -type f -name '*.md' 2>/dev/null)
+EOF
+  elif [ -f "$arg" ]; then
+    add_target "$arg"
+  else
+    warn "Skipping '$arg' (not a file or directory)."
+  fi
+done
+
+if [ -z "$targets" ]; then
+  printf '%s\n' "${YELLOW}No .md files found in the target(s). Nothing to check.${RESET}"
+  exit 0
+fi
+
+failures=0
+recognized=0
+
+# A scraping command baked at an off-limits host = a hard fail (ToS violation).
+SCRAPE_HOSTS='creativecenter|ads\.tiktok\.com'
+SCRAPE_VERBS='curl|wget|fetch|scrape|puppeteer|playwright|selenium|headless'
+
+for file in $targets; do
+  [ -f "$file" ] || continue
+
+  is_backlog=0
+  is_experiment=0
+
+  # Backlog: a markdown header row naming all the required columns (any order).
+  header="$(grep -iE '^\|.*\|' "$file" 2>/dev/null \
+            | grep -iE 'id' | grep -iE 'hook' | grep -iE 'trend' \
+            | grep -iE 'score' | grep -iE 'status' | grep -iE 'idea' | head -1)"
+  [ -n "$header" ] && is_backlog=1
+
+  # Experiment: lives under experiments/, or carries a Hypothesis marker.
+  case "$file" in
+    *experiments/*) is_experiment=1 ;;
+  esac
+  if grep -qiE '(^|[^a-z])hypothesis' "$file" 2>/dev/null; then
+    is_experiment=1
+  fi
+
+  if [ "$is_backlog" -eq 0 ] && [ "$is_experiment" -eq 0 ]; then
+    # Not a recognizable artifact — but still enforce the no-scrape rule on it,
+    # because a scraper hidden in a stray .md is still a problem if it's ours.
+    if grep -niE "($SCRAPE_VERBS).*($SCRAPE_HOSTS)" "$file" >/dev/null 2>&1; then
+      printf '\n%s\n' "Checking: $file"
+      fail "$file contains a scraping command against a TikTok surface — that violates ToS. Use manual/assisted capture or a sanctioned API."
+      recognized=$((recognized + 1))
+    fi
+    continue
+  fi
+
+  recognized=$((recognized + 1))
+  file_fail_start=$failures
+  printf '\n%s\n' "Checking: $file"
+
+  # ---- no-scrape rule (all artifacts) -------------------------------------
+  if grep -niE "($SCRAPE_VERBS).*($SCRAPE_HOSTS)" "$file" >/dev/null 2>&1; then
+    fail "scraping command against a TikTok surface present — ToS violation; use manual/assisted capture or a sanctioned API."
+  else
+    ok "no scraping command baked in"
+  fi
+
+  if [ "$is_backlog" -eq 1 ]; then
+    # data row = a table row after the header that is not the header and not a
+    # separator (---). Count rows starting with '|' that contain a digit.
+    data_rows="$(grep -E '^\|' "$file" 2>/dev/null \
+                 | grep -vE '^\|[[:space:]:|-]+\|?[[:space:]]*$' \
+                 | grep -iE '[0-9]' | grep -ivE '^\|[[:space:]]*id[[:space:]]*\|')"
+    if [ -n "$data_rows" ]; then
+      ok "backlog table has the required columns (id, idea, hook, trend, score, status) and >=1 data row"
+    else
+      fail "backlog table has the required header but no data rows — an empty backlog ranks nothing."
+    fi
+  fi
+
+  if [ "$is_experiment" -eq 1 ]; then
+    if grep -qiE '(^|[^a-z])hypothesis' "$file" 2>/dev/null; then
+      ok "hypothesis present"
+    else
+      fail "experiment file has no Hypothesis — every bet needs one falsifiable sentence."
+    fi
+
+    if grep -qE '[0-9]{4}-[0-9]{2}-[0-9]{2}' "$file" 2>/dev/null; then
+      ok "dated trend signal present (YYYY-MM-DD)"
+    else
+      fail "no dated trend signal (YYYY-MM-DD) — an undated signal cannot be scored for freshness."
+    fi
+
+    if grep -qiE '(^|[^a-z])result' "$file" 2>/dev/null; then
+      ok "result fields present (even if pending)"
+    else
+      fail "no result fields — the loop never learns if the outcome is never recorded (use 'result: pending')."
+    fi
+  fi
+
+  if [ "$failures" -eq "$file_fail_start" ]; then
+    ok "$file passed"
+  fi
+done
+
+if [ "$recognized" -eq 0 ]; then
+  printf '\n%s\n' "${YELLOW}No backlog or experiment artifacts among the target(s). Nothing to verify.${RESET}"
+  exit 0
+fi
+
+printf '\n'
+if [ "$failures" -gt 0 ]; then
+  printf '%s\n' "${RED}$failures check(s) failed.${RESET}"
+  exit 1
+fi
+printf '%s\n' "${GREEN}All checks passed.${RESET}"
+exit 0

package/skills/shortform-packaging/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: shortform-packaging
+description: "Use when a vertical short (TikTok/Reels/YouTube Shorts) is shot or scripted and you need the upload-form copy and cover that win the feed: the hook line, the first-frame on-screen text, the search-led caption, a tight 3-5 hashtag set, and the cover frame; it learns from what performed via the 02-DOCS log. Triggers: 'write the hook and caption for this Reel', 'pick the cover frame and its text', 'what hashtags for this TikTok', the non-obvious 'is 20 hashtags too many' and 'my shorts get views but nobody shares them, fix the packaging', 'rewrite the caption to rank in TikTok search', 'log how the last 5 shorts performed and apply it', plus Spanish/Catalan 'escríbeme el gancho y el pie de foto para este Reel' / 'ningú comparteix els meus vídeos, arregla'm el packaging i dona'm els hashtags'. NOT inventing the idea (that is shortform-ideation), NOT scripting or directing the cuts (that is video-shorts), NOT executing the edit (that is shortform-editing), NOT scheduling the post (that is social-publisher)."
+tags: [shortform, packaging, tiktok, reels, shorts, caption, hashtags, hook, cover, retention, social-copy]
+recommends: [video-shorts, shortform-ideation, shortform-strategy, shortform-editing, social-publisher, brand-voice, tiktok-api, instagram-api]
+profiles: []
+origin: risco
+---
+
+# Short-form packaging
+
+You write the words and choose the frame that wrap a finished or scripted vertical
+short so it survives the feed. The clip already exists — your job is the upload-form
+copy and the cover that decide whether a scroller stops, finishes, and sends it to a
+friend. You are not the idea, not the script, not the edit, not the schedule. A great
+clip dies on a weak package; a tested package multiplies a fine clip.
+
+You optimize against measured retention and shares pulled from the account's own
+`02-DOCS` log — not a hunch, not the latest "viral hook" thread.
+
+## What you produce
+
+Five artifacts plus one feedback entry, every single time:
+
+1. **A hook line** — the spoken/written opener, 4-7 words, that has to survive second 3.
+2. **A first-frame on-screen text set** — the burned-in line a sound-off scroller reads
+   before any audio decision; 2-3 variants to test, each ≤7 words.
+3. **A caption** — search-led, front-loaded, keyword-first sentence.
+4. **A hashtag set** — 3-5 topic-signal tags, never a discovery dump.
+5. **A cover frame + overlay** — which frame becomes the grid/Shorts-shelf billboard,
+   plus its 3-6 word overlay.
+6. **A `02-DOCS` feedback entry** — what shipped, the metric that moved, what won.
+
+**Precondition (do not skip).** The video must be shot or scripted, and the idea/angle
+must be decided. If there is no script, route to `video-shorts`. If there is no settled
+idea, route to `shortform-ideation`. Do not invent either here — packaging an undecided
+short means guessing the hook, the keyword, and the audience all at once.
+
+## Rule zero: package for the seed test and the send
+
+Every choice below serves exactly two outcomes. Hold them in mind:
+
+- **The seed test is the whole game.** TikTok and Shorts push each upload to a small
+  seed audience first; weak intro retention plus high swipe-away kills distribution
+  before it spreads. Intro retention (made it past 3s) of **70%+** is the bar, and the
+  first ~3 seconds carry most of the swing in whether a clip is finished at all. So hook
+  + first-frame text + cover are the highest-leverage copy on the whole post.
+- **Sends and saves are the currency, weighted above likes.** Instagram's stated Reels
+  ranking factors are watch time, likes-per-reach, and **sends-per-reach (DM shares)**;
+  Mosseri has repeatedly said sends and saves signal more intent than likes, so treat
+  them as outweighing likes. Package for "I have to send this to someone," not for vanity
+  likes.
+
+## Ground first
+
+Before you write a word, read the account. Skipping this produces generic copy in a
+stranger's voice that contradicts what already won.
+
+1. Read `02-DOCS/wiki/shortform/` for the **brand voice** and prior packages.
+2. Read the **performance feedback log** — which hooks, covers, and hashtags already
+   lifted intro retention and sends. Carry the winner's shape forward.
+3. Pull the decided **idea/angle** from `shortform-ideation` output if it exists.
+4. **No script or no settled angle? Route OUT** (see Handoffs). Never invent here.
+
+Persist the package under `02-DOCS/wiki/shortform/` and raw test results under
+`02-DOCS/raw/shortform/`. Pattern depth lives in
+[references/package-templates.md](references/package-templates.md).
+
+## The two-second decision
+
+A scroller meets your short in one of two states, and you design for both:
+
+- **From the feed/FYP:** frame 1 plays muted. ~60% watch sound-off, so the **first-frame
+  on-screen text carries the hook** — it is read before any audio decision is made.
+- **From a profile grid or Shorts shelf:** they see the **cover frame** first, cropped
+  and silent.
+
+So three artifacts must say the *same promise* in the same words: the spoken hook, the
+first-frame on-screen text (its silent twin), and the cover overlay. Co-design them;
+never let them drift apart.
+
+## Hook line + on-screen text
+
+The 3 seconds that decide distribution. Rules, each with its reason:
+
+- **4-7 words.** Longer and the muted scroller swipes before finishing the read.
+- **Lead with the promise or the tension, not the setup.** The payoff or the stakes go
+  first; context can wait for the caption.
+- **On-screen text is the silent twin of the spoken hook** — restate the hook as burned-in
+  text so the sound-off majority gets it. Keep it inside the safe zones (clear of the
+  top status bar and the bottom UI: caption, buttons, profile tap target).
+- **Emit a SET of 2-3 variants, never one.** You ship a hypothesis to measure on the
+  seed audience, not a guess to defend.
+
+| Bad | Good | Why |
+|---|---|---|
+| "Hey guys, so today I wanted to talk about..." | "I deleted my to-do app. Here's why." | Promise up front; survives second 3. |
+| "Watch till the end!" | "The last step is the one nobody does." | Open loop with a concrete stake, not a beg. |
+| On-screen: *(none — relies on audio)* | On-screen: "3 apps that replaced Notion" | Carries the hook for the muted 60%. |
+| Hook says X, on-screen text says Y | Hook and on-screen text say the same 5 words | Twin promise, no drift. |
+
+Full pattern library (open loop · number · contrarian · stakes · POV · before/after)
+with Bad→Good rewrites is in
+[references/package-templates.md](references/package-templates.md).
+
+## The caption
+
+The caption is now a **search-ranking field**, not a throwaway line. Mosseri lists
+captions as a Reels ranking factor; TikTok and Instagram Search read caption language
+like page copy. Rules:
+
+- **Lead the first sentence with the actual keyword phrase a viewer would search** —
+  not a teaser, not a question. A keyword-led first line is what surfaces the clip in
+  in-app search and the "related" rail; a teaser line surfaces nowhere.
+- **Only the first ~100-150 chars show before "more."** Put the keyword, the value, and
+  any code/link there. The rest may never be seen.
+- **Sweet spot ~150-300 chars** for context plus engagement; go to 500+ only for a
+  deliberately educational/SEO post. Hard limits (TikTok 4,000, Reels 2,200) are
+  irrelevant — the first line does the work.
+- **End on a save/send-worthy payoff and one soft CTA.** "Send this to the friend who
+  needs it" beats "like and follow."
+
+Pick the caption shape from the ask:
+
+| If the goal is... | Caption shape |
+|---|---|
+| Rank in in-app search (evergreen, how-to) | Keyword phrase first → value → soft CTA. Lean to 200-400 chars. |
+| Engagement on a timely/entertaining clip | Punchy payoff line + send prompt. Keep ~150 chars. |
+
+| Bad | Good |
+|---|---|
+| "wait for it 👀 you won't believe this" | "3 Notion templates that replaced my to-do app (free links below)" |
+| "new video!! check it out 🔥🔥" | "How to batch a week of shorts in one afternoon — the exact workflow" |
+
+## Hashtags
+
+The rules changed; the old 30-tag dump is now a liability.
+
+- **3-5 hashtags. Never more.** Instagram now **hard-caps posts/Reels at 5** (Mosseri,
+  rolling into 2026) and states hashtags "categorize content for the algorithm" — they
+  do not boost reach. TikTok best practice is also **3-5** (CapCut, ByteDance's own
+  editor); 10+ signals spam and gives the algorithm mixed signals.
+- **Topic-signal, not discovery.** Pick specific tags that label what the video *is*,
+  not broad reach-bait like `#fyp #viral #foryou`.
+- **Tune per platform.** Same clip, but match each platform's search audience — a tag
+  that ranks on TikTok may be noise on Reels.
+
+```text
+Bad:   #fyp #foryou #viral #trending #productivity #notion #app #tech #life #2026 ... (22 more)
+Good:  #notiontemplates #productivitytips #notionsetup
+```
+
+## Cover frame
+
+The cover is the grid/search/shelf billboard — it sells the replay and the profile
+visit, and it is **not** what plays in-feed. Choose and spec it:
+
+- **Pick a high-motion, high-contrast, or peak-emotion frame** — a face mid-expression
+  or the visual payoff. Avoid a flat, mid-sentence frame.
+- **Respect the crops.** A Reels cover shows full 9:16 (1080×1920) in the Reels tab, but
+  the **profile grid crops it to 3:4 (1080×1440)** — Instagram removed the top and bottom
+  ~240px of the 1080×1920 frame when it moved the grid to 3:4 in 2025 (postfa.st "Instagram
+  Reels Size", Buffer 2026). The feed crops differently again (4:5, 1080×1350). The one
+  region that survives *every* crop is the **1:1 centre square (1080×1080)** — so keep all
+  cover text inside that centre square and you are safe on the grid, the feed, and the tab.
+- **Add 3-6 words of overlay** — the **same words as the hook**, high contrast.
+
+Cover checklist:
+
+- [ ] Frame has motion/contrast/face or shows the payoff (not a flat mid-frame)
+- [ ] Overlay is 3-6 words and matches the hook line
+- [ ] Overlay text sits inside the 1:1 centre square (the only region that survives the 3:4 grid crop, the 4:5 feed crop, and the 9:16 tab)
+- [ ] Text clears the top status bar and bottom UI
+
+## The learning loop (02-DOCS)
+
+This is the core that makes the skill compound. **Read winners before writing; append a
+result after shipping.** Key the log on the metrics that move distribution — NOT likes:
+
+```yaml
+- shipped: "2026-06-02 / faceless productivity TikTok"
+  hook: "I deleted my to-do app. Here's why."
+  on_screen_text: "3 apps that replaced Notion"
+  cover_overlay: "I deleted my to-do app"
+  hashtags: ["#notiontemplates", "#productivitytips", "#notionsetup"]
+  intro_retention: 0.74   # made it past 3s — bar is 0.70
+  sends_per_reach: 0.018  # DM shares, the share-economy currency
+  saves: 312              # weighted above likes (intent signal)
+  won: "number-led on-screen text beat the question variant on intro retention"
+```
+
+The filled schema and a per-platform tuned example are in
+[references/package-templates.md](references/package-templates.md). When you write the
+next package, open the log first and mirror the shape that won.
+
+## Test in sets, ship across the trio
+
+Specs are shared — 9:16, 1080×1920, MP4 H.264/AAC — so one package repurposes across
+TikTok, Reels, and Shorts. But tune the caption keywords and hashtags per platform's
+search audience, and treat the 1:1 safe square as most critical on Instagram. Ship 2-3
+hook + on-screen-text + cover variants, read which lifted intro retention and sends, log
+it, repeat.
+
+## Handoffs
+
+Route out the moment the ask leaves the upload-form copy and cover. The tell: if it is
+one of the five artifacts above, it is here; otherwise it is a sibling.
+
+| Request | Route to |
+|---|---|
+| Invent the idea / topic / angle for the short | `shortform-ideation` |
+| Account-level plan: niche, cadence, which platforms, growth | `shortform-strategy` |
+| Write the spoken script / beat sheet, direct the cuts | [video-shorts](../video-shorts/SKILL.md) |
+| Execute the edit — caption burn-in, B-roll, sound sync | `shortform-editing` |
+| Schedule / cross-post the finished short | [social-publisher](../social-publisher/SKILL.md) |
+| Upload programmatically via the platform Graph/API | `tiktok-api` / `instagram-api` |
+| Title/description/tags for a long-form YouTube video | [youtube-packaging](../youtube-packaging/SKILL.md) |
+| Define the durable brand tone reused across all content | [brand-voice](../brand-voice/SKILL.md) |
+
+Sharp line vs `video-shorts`: that sibling owns the *internal* on-screen text of every
+beat as part of the narrative. You own the *packaging* layer — the single first-frame
+hook overlay, the caption, the hashtags, and the cover — and you treat the script's
+existence as a precondition.
+
+## Anti-patterns
+
+| Anti-pattern | Do instead |
+|---|---|
+| Caption opens with a teaser ("wait for it 👀") | Lead the first sentence with the searched keyword phrase. |
+| Shipping one hook instead of a set | Emit 2-3 hook + on-screen-text variants to test on the seed. |
+| Dumping 15-30 hashtags | 3-5 specific topic tags; IG hard-caps at 5, TikTok best is 3-5. |
+| Like-bait CTA ("smash that like") | A save/send payoff — sends and saves outweigh likes. |
+| Cover text outside the 1:1 centre square | Keep overlay inside the centre square — the band that survives the 3:4 grid, 4:5 feed, and 9:16 tab crops — clear of UI. |
+| On-screen text that doesn't match the hook | Make on-screen text the silent twin — same words. |
+| Writing blind, ignoring the 02-DOCS log | Read prior winners first; carry the winning shape forward. |
+| Packaging before a script/idea exists | Route to `video-shorts` / `shortform-ideation` first. |
+| Same caption copy-pasted to every platform | Tune keywords and hashtags per platform's search audience. |
+| Logging likes as the success metric | Log intro retention, sends-per-reach, and saves. |
+
+## Verify
+
+`scripts/verify.sh <package-file>` is a read-only, network-free lint over one package
+draft: hook set has ≥2 variants; on-screen text exists and is ≤7 words per line; the
+caption's first sentence is ≤~150 chars and does not open with a banned teaser; the
+hashtag count is 3-5; a cover frame + overlay is present; and a `02-DOCS` feedback block
+exists with `intro_retention`, `sends_per_reach`, and `saves`. A clean or empty file
+exits 0 — never a false failure. See `evals/README.md` for how the cases are run.

package/skills/shortform-packaging/evals/README.md

@@ -0,0 +1,10 @@
+# Evals — shortform-packaging
+
+These are routing and capability checks, not an automated harness. Run them by hand:
+read each `should_trigger` prompt and confirm the skill's Use-when/Triggers fire on it
+(including the non-obvious "nobody shares my shorts" and the Spanish/Catalan prompt);
+read each `should_not_trigger` prompt and confirm the description's NOT-boundary sends
+it to the named `route_to` sibling instead. For the `capability` case, draft a real
+package against the scenario and check it hits every `must_include` rubric line — then
+run `scripts/verify.sh` on that draft to confirm the structural lint passes. No network,
+no fixtures.

package/skills/shortform-packaging/evals/cases.yaml

@@ -0,0 +1,48 @@
+skill: shortform-packaging
+
+should_trigger:
+  - prompt: "Write the hook, caption and hashtags for this finished Reel."
+    why: Core ask — three of the five upload-form artifacts for a finished short.
+  - prompt: "Pick the cover frame and the text that goes on it for my TikTok."
+    why: The cover artifact specifically — frame choice plus overlay, owned here.
+  - prompt: "My shorts get views but nobody shares them — fix the packaging."
+    why: Non-obvious — a shares complaint with no copy keyword; diagnosis maps to send-bait caption and a sendable hook, not the edit.
+  - prompt: "Is 20 hashtags too many for a Reel?"
+    why: Non-obvious — tests the Instagram 5-tag hard cap and the 3-5 best-practice rule.
+  - prompt: "Log how my last 5 shorts performed and apply it to the next batch."
+    why: The learning loop — read the 02-DOCS feedback log on retention/sends and carry winners forward.
+  - prompt: "Rewrite this caption so it ranks in TikTok search."
+    why: Caption as a search-ranking field — keyword-led first sentence, owned here.
+  - prompt: "Escríbeme el gancho i el pie de foto per a aquest Reel i dona'm els hashtags."
+    why: Spanish/Catalan — full upload-form copy ask (hook, caption, hashtags).
+
+should_not_trigger:
+  - prompt: "Come up with an idea for a short about productivity."
+    route_to: shortform-ideation
+    why: The idea/angle, which packaging consumes but never invents.
+  - prompt: "Write the full script and plan the cuts for this 30s TikTok."
+    route_to: video-shorts
+    why: The spoken script and edit direction (the narrative layer), not the upload copy.
+  - prompt: "Burn in the captions and add the B-roll for this clip."
+    route_to: shortform-editing
+    why: Execution of the edit, not the words and cover that wrap it.
+  - prompt: "Schedule this Reel to post Tuesday 6pm across IG and TikTok."
+    route_to: social-publisher
+    why: When and where to post, not the copy or cover.
+  - prompt: "Write the title and description for my long-form YouTube video."
+    route_to: youtube-packaging
+    why: Long-form metadata, not a vertical short's package.
+
+capability:
+  - scenario: >
+      Given a finished 25s faceless productivity TikTok and a 02-DOCS feedback log whose
+      last winner was a number-led on-screen hook, produce the full package.
+    must_include:
+      - Reads the 02-DOCS feedback log / brand voice BEFORE writing, and carries the number-led winner forward.
+      - Emits a SET of >=2 hook + on-screen-text variants, each 4-7 words.
+      - On-screen text restates the hook (the silent twin) and stays in the safe zones.
+      - Caption first sentence is keyword-led and <=~150 chars, not a teaser like "wait for it".
+      - Exactly 3-5 hashtags, topic-signal not a discovery dump.
+      - A cover frame plus a <=6-word overlay that sits inside the 1:1 centre square (the band that survives the 3:4 grid, 4:5 feed, and 9:16 tab crops) and matches the hook.
+      - A feedback-entry stub keyed on intro_retention / sends_per_reach / saves — not likes.
+      - Routes nothing it does not own (no scripting, editing, scheduling, or idea invention).

package/skills/shortform-packaging/references/package-templates.md

@@ -0,0 +1,117 @@
+# Package templates & pattern library
+
+Depth offloaded from `SKILL.md`. Use this when you need the full package file format,
+the hook/on-screen-text pattern library, the cover-frame safe-area in pixels, or the
+filled `02-DOCS` feedback-log schema.
+
+## The package file format
+
+Emit one plain-text/markdown block per short. `scripts/verify.sh` lints exactly these
+labels (English or ES/CA, one per line, content following):
+
+```text
+Hook:
+  - I deleted my to-do app. Here's why.
+  - The app that runs my whole week (it's free)
+
+On-screen text:
+  - 3 apps that replaced Notion
+  - I deleted my to-do app
+
+Caption:
+  3 Notion templates that replaced my to-do app — the full setup, free links below.
+  Send this to the friend drowning in tabs.
+
+Hashtags:
+  #notiontemplates #productivitytips #notionsetup
+
+Cover:
+  frame: 00:07 (peak — laptop closing, face mid-grin)
+  overlay: I deleted my to-do app
+
+Feedback:
+  intro_retention: 0.74
+  sends_per_reach: 0.018
+  saves: 312
+```
+
+### TikTok (search-led) vs Reels (send-led) — same clip, tuned
+
+```text
+# TikTok — lean into in-app search
+Caption: How to batch a week of shorts in one afternoon — exact workflow inside.
+Hashtags: #contentbatching #shortformvideo #creatorworkflow
+
+# Reels — lean into the DM send
+Caption: This is how I never run out of shorts. Send it to your co-founder.
+Hashtags: #reelstips #contentcreator #solopreneur
+```
+
+Caption keywords and hashtags differ per platform's search audience; the hook,
+on-screen text, and cover frame stay identical (shared 9:16 / 1080×1920 spec).
+
+## Hook + on-screen-text pattern library
+
+Each is 4-7 words, promise/tension first, and the on-screen text is the silent twin.
+
+| Pattern | Bad | Good |
+|---|---|---|
+| Open loop | "Let me explain something" | "Nobody does step 3 — and it's the one that matters" |
+| Number | "Some tips for you" | "5 shorts in one afternoon" |
+| Contrarian | "Posting daily is good" | "Stop posting daily. Do this instead." |
+| Stakes | "A mistake to avoid" | "This caption mistake kills your reach" |
+| POV | "Here is my routine" | "POV: you finally batched a week of content" |
+| Before/after | "It got better over time" | "0 to 10k saves with one caption change" |
+
+Rule: whichever you pick, the **on-screen first-frame text restates it in the same words**
+for the sound-off ~60%, inside the safe zones (clear of top status bar and bottom UI).
+
+## Cover-frame selection & safe area (in pixels)
+
+The cover is the grid/shelf billboard, not the in-feed frame. The same 1080×1920 source
+frame is cropped three different ways depending on where it surfaces:
+
+- **Reels tab / Shorts shelf:** shows the full **9:16 frame, 1080×1920** — no crop.
+- **Profile grid:** crops to **3:4, 1080×1440**. Instagram moved the grid from 1:1 to 3:4
+  in 2025, lopping the **top ~240px and bottom ~240px** off the 1920-tall frame
+  (the surviving band is roughly **y=240 to y=1680**). Sources: postfa.st "Instagram Reels
+  Size", Buffer 2026.
+- **Main feed:** crops to **4:5, 1080×1350** (a different, taller centre band again).
+
+You cannot author one band that pleases all three crops separately — so author for the
+**intersection**: the **1:1 centre square, 1080×1080** (vertical centre, roughly
+**y=420 to y=1500**) sits inside every one of the three crops above. Keep all overlay
+text in that square and it survives the grid, the feed, and the tab. Then also clear the
+platform UI overlays (bottom ~250px: caption, action buttons, audio tag; top ~120px:
+status bar). Practical safe band for overlay text: centred, between y≈600 and y≈1350.
+
+Checklist:
+
+- [ ] Frame shows motion / high contrast / a face mid-expression / the payoff
+- [ ] Overlay is 3-6 words, same words as the hook line
+- [ ] Overlay sits inside the 1:1 centre square (the intersection that survives the 3:4 grid, 4:5 feed, and 9:16 tab crops)
+- [ ] Text clears top ~120px and bottom ~250px UI bands
+
+## 02-DOCS feedback-log schema
+
+Append one entry per shipped short under `02-DOCS/raw/shortform/`. Key on distribution
+metrics, never likes. Read the log before writing the next package and mirror the
+winning shape.
+
+```yaml
+- shipped: "2026-06-02 / faceless productivity TikTok"
+  platform: tiktok
+  hook: "I deleted my to-do app. Here's why."
+  on_screen_text: "3 apps that replaced Notion"
+  caption_lede: "3 Notion templates that replaced my to-do app"
+  cover_overlay: "I deleted my to-do app"
+  hashtags: ["#notiontemplates", "#productivitytips", "#notionsetup"]
+  intro_retention: 0.74    # past-3s rate; bar is 0.70
+  sends_per_reach: 0.018   # DM shares — the share-economy currency
+  saves: 312               # weighted above likes (stronger intent signal)
+  variant_tested: "number-led vs question on-screen text"
+  won: "number-led lifted intro_retention 0.74 vs 0.61; carry forward"
+```
+
+Fields the next package reads first: `won`, `intro_retention`, `sends_per_reach`. If the
+last winner was a number-led hook, start the next set there and test against it.