Skip to content

Commit 7170fd5

Browse files
jrusso1020Jake Moran
andcommitted
feat(skills): add changelog-video skill for repo-native CC + Codex discovery
Packages the weekly changelog-video pipeline (Jake Moran's v1) as a repo-native skill set that Claude Code and Codex CLI auto-discover the moment the repo is opened. No install step; run the skill against a changelog markdown for a week's git range and it produces a lint-clean, seam-gate-green 1080x1080 MP4 (~45-60s, Annie VO, mock-UI visualizations, caption rail) end-to-end. Layout follows the existing .claude-plugin/ / .codex-plugin/ mirror pattern: - .claude/skills/<name>/ - project-local skills for Claude Code - .codex/skills/<name>/ - byte-identical copy for Codex CLI Six skills added to each: changelog-video (the pipeline entry point) plus five doctrine deps it routes through - motion-doctrine, cut-the-curve, captions-overlay, seam-craft, oversized-cursor. Fonts, background pattern video, house BGM, lexicon, align-captions.mjs, and seam-stamp/seam-gate scripts all live inside the skill dirs so the flow needs zero external provisioning beyond HeyGen CLI auth (existing repo dep). Not distributed via the marketplace plugin - .claude/skills/ and .codex/skills/ are separate namespaces from skills/, which stays the external-plugin path. The changelog-video flow is a repo-native weekly-runner, not something we want cluttering external installs. .gitignore change: rewrites the .claude/ block to ignore agent-installed skills and local state (unchanged intent) while re-including the six repo-native skill dirs plus README.md. Removes the redundant blanket .claude/ + .claude/worktrees/ rules further down since the top-level block now covers them. One SKILL.md path rewrite in changelog-video: the TTS invocation was node ~/.claude/skills/media-use/audio/scripts/heygen-tts.mjs (user-home path from Jake's portable-install context); rewritten to node skills/hyperframes-media/scripts/heygen-tts.mjs so the repo-native flow reads the tracked helper without needing npx hyperframes skills. Validated end-to-end by Home on June 23-29 range (posted MP4 in C0ACCNHLG3U thread 1784181166.041319) with two geometry-nudge fixes; the skill's build-spec + review-loop caught the automated gates plus the visual spot-check James asks for. Co-Authored-By: Jake Moran <[email protected]>
1 parent 1b4cf12 commit 7170fd5

51 files changed

Lines changed: 4650 additions & 5 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Project-local Claude Code skills
2+
3+
Skills in this directory are auto-discovered by Claude Code when the
4+
`hyperframes` repo is opened as the working directory. They are NOT part of
5+
the marketplace-distributed plugin (that set lives under `skills/` and is
6+
manifested by `.claude-plugin/`). Two separate namespaces, on purpose:
7+
8+
- `.claude/skills/` — **repo-native**, run only against this repo (weekly
9+
changelog videos, doctrine-heavy authoring flows).
10+
- `skills/` — **marketplace-distributable**, installed into other projects
11+
via `npx hyperframes skills` or `npx skills add heygen-com/hyperframes`.
12+
13+
## Weekly changelog video
14+
15+
The `changelog-video` skill turns a weekly changelog markdown into a
16+
~45–60s branded 1080×1080 MP4 (motion-doctrine layout, Annie VO,
17+
seam-gated cuts, caption rail). It ships pre-configured — fonts,
18+
background pattern, house BGM, lexicon, and the align-captions script all
19+
live inside `changelog-video/`. Its five dependency skills
20+
(`motion-doctrine`, `cut-the-curve`, `captions-overlay`, `seam-craft`,
21+
`oversized-cursor`) sit alongside so the router graph is complete on
22+
clone.
23+
24+
Weekly usage:
25+
26+
1. Regenerate the digest markdown for the target range:
27+
`bun run changelog:weekly --from YYYY-MM-DD --to YYYY-MM-DD` (this
28+
only reads git; the `--write` variant is what the docs cron uses).
29+
2. In Claude Code at the repo root, invoke `/changelog-video` with the
30+
generated markdown. The agent will present its script + visualization
31+
plan for review before rendering.
32+
3. Accept, and the agent produces `weekly-changelog-<range>.mp4` gated by
33+
`hyperframes check` (0 errors) + `seam-gate verify` (0 fail/warn).
34+
35+
TTS uses the tracked `skills/hyperframes-media/scripts/heygen-tts.mjs`
36+
(no extra install needed). HeyGen CLI ≥ 0.3.0 authenticated via
37+
`heygen auth login --oauth` is the one credential.
38+
39+
The parallel set at `.codex/skills/` is a byte-identical copy so Codex
40+
users get the same auto-discover behaviour — keep the two in sync when
41+
editing.
Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
name: captions-overlay
3+
description: Overlay doctrine for the embedded-captions workflow — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Quotes the rail+embed model from embedded-captions and constraint #13 (captions overlay, keep-out band retired) from the product-launch-video scene agent. Applies ON TOP of embedded-captions.
4+
---
5+
6+
# Captions Overlay Doctrine
7+
8+
> **Overlay doctrine — supplements the upstream `embedded-captions` skill. Applies ON TOP of it; do not expect it folded into the upstream skill.**
9+
10+
Two ideas combine here. First, the **caption model** — every spoken phrase is `drop`,
11+
`rail`, or `embed`, and embed is the scarce earned peak, not the default. Second, the
12+
**overlay law** — a caption line is composited ON TOP of the film as an overlay; it is
13+
NOT a reserved zone, so you never shift content up or leave a dead band to "make room"
14+
for it. The two reinforce each other: because captions ride as an overlay (the verbatim
15+
rail in front, the occasional embed behind the subject), the composition keeps its full
16+
frame and centers on the true vertical center.
17+
18+
## The caption model — drop / rail / embed
19+
20+
Every spoken phrase is one of three things (verbatim from `embedded-captions`):
21+
22+
| | What | How it's shown |
23+
|---|---|---|
24+
| **drop** | filler — um/uh, stutters, self-corrections | not shown |
25+
| **rail** | the default — ordinary spoken content (verbatim) | clean lower-third subtitle, **in front**, readable. A punch word can get an inline `emphasis` highlight (accent colour / active-word pop) — it stays on the rail. |
26+
| **embed** | a promoted peak — the headline beat | one big word composited **behind the subject** (matte occlusion), designed entrance + exit |
27+
28+
**The rail carries most of the text; embed is the scarce, earned peak** — ≤1 per beat,
29+
never two adjacent/co-visible, spaced ≥ a beat apart. A short clip → usually one embed;
30+
a long explainer → ~one per section. Embedding every word is the common mistake.
31+
32+
This is the **Standard** mode shape (rail = the verbatim lower-third; embed = the climax
33+
composited behind the subject). **Cinematic** mode drops the rail and makes everything
34+
embed-style — use it only for pure-cinematic asks, never for explainer / voiceover where
35+
the words must read.
36+
37+
### Rail-first, embed-scarce (the load-bearing rules)
38+
39+
Quoted from the `embedded-captions` non-negotiables:
40+
41+
- **Rail-first for talking-head / explainer.** Don't embed the whole transcript — most
42+
text is the rail; embed only peaks. Embedding everything is the default mistake.
43+
- **Embed is scarce + spaced.** ≤1 embed per sentence/beat, never two adjacent or
44+
co-visible, ≥ a beat apart, at most one `apex`. climax = per-beat peak, **not** "the
45+
single payoff of the entire clip."
46+
47+
## The overlay law — captions are NOT a reserved band
48+
49+
In a generated launch composition, when captions are enabled, finalize composites a
50+
**small, minimal word-by-word caption line** as an overlay layer ON TOP of the whole
51+
film (a single text line, bottom-centered, roughly the bottom ~5-8% of canvas height).
52+
It is an overlay, not a reserved zone (verbatim from constraint #13 of the
53+
product-launch-video scene agent):
54+
55+
- **Center the composition on the TRUE vertical center — y = H / 2** (landscape 540,
56+
portrait 960). Do not shift content up to "make room" for captions; a composition
57+
centered at 0.42 × H with a dead lower band is the bug, not the fix.
58+
- Content may extend to the canvas bottom. Full-bleed subjects, rails, and backgrounds
59+
all welcome.
60+
- **One soft courtesy rule:** avoid parking _critical small readable text_ (a URL line,
61+
a legal line, a sub-caption) exactly in the bottom ~80px center span where the caption
62+
line sits — the overlay would fight it. Large imagery / cards / ambient content under
63+
the captions is fine; the caption skin is designed to read over content.
64+
- There is no machine keep-out gate (the old `captions.mjs keepout` check is retired).
65+
Finalize snapshot QA judges caption-over-content legibility visually.
66+
67+
**When captions are disabled:** identical positioning freedom — the overlay simply
68+
doesn't exist.
69+
70+
## Why these two rules are one doctrine
71+
72+
The model says the rail rides **in front** and an embed is a rare word composited
73+
**behind the subject** — both are layers added to footage that ships untouched. The
74+
overlay law says the caption line is a layer composited **on top** of the whole film,
75+
not a band carved out of the layout. So in both the captioning pipeline and the
76+
launch-video pipeline, captions are an overlay you add, not a zone you reserve:
77+
78+
- Keep the full frame; center on true center; let content run to the edges.
79+
- Make the rail (or the small overlay caption line) carry the verbatim words.
80+
- Promote a word to an embed only at a genuine peak — scarce, spaced, never two at once.
81+
- Reserve nothing; judge legibility of captions-over-content visually, not by a keep-out gate.
Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
name: changelog-video
3+
description: Turn a weekly changelog .md into a finished branded changelog video (square 1080, ~45-60s, Annie VO, animated brand background, mock-UI visualizations, lowkey captions). Use when the user provides a changelog/digest markdown and wants the weekly video, or says "changelog video". Self-contained — fonts, background, lexicon, and scripts ship in this skill.
4+
---
5+
6+
# Changelog → Branded Video
7+
8+
Input: a changelog .md (themes + items, like the weekly HyperFrames digest).
9+
Output: a lint-clean, seam-gate-green HyperFrames project in
10+
`projects/active/weekly-changelog-<range>/`. Render only when asked.
11+
12+
**Load first, non-negotiable:** `motion-doctrine` (+ `cut-the-curve`,
13+
`oversized-cursor` if a cursor appears, `seam-craft`) and `captions-overlay`.
14+
This skill supplies the changelog-specific pipeline; the doctrine supplies the
15+
motion law.
16+
17+
## The prime directive: visualize, don't list
18+
19+
Every theme is illustrated by an **animated mock of the actual UI or a
20+
faithful analog** acting out the change in experience — never text bullets.
21+
Route every theme/item through `references/visualization-registry.md` BEFORE
22+
writing the script; the registry decides ui-recreate / ui-analog / terminal /
23+
checklist. Text checklist is the LAST resort, reserved for genuinely
24+
non-visual items (reliability fix lists).
25+
26+
## Pipeline
27+
28+
### 1 · Parse + editorial cut
29+
30+
- Extract: week range, headline stats (releases, commits), themes, items.
31+
- **Budget: 45-60s total.** Title ≤2s, outro ≤3.5s, 4 themes ≈ 9-12s each.
32+
- Per theme keep ONE hero visualization + at most 3 spoken items. Everything
33+
else exists only as the outro's "full digest" pointer. Cutting is the job:
34+
a changelog with 30 items still yields ≤14 spoken beats.
35+
- Order themes by story: marquee feature → product surface → performance →
36+
reliability (the digest usually already reads this way).
37+
38+
### 2 · Visualization routing
39+
40+
For each theme, pick the surface from `references/visualization-registry.md`
41+
and write one line: `theme → surface → the 2-4 sequenced actions the mock
42+
performs, each tied to a script phrase`. If no registry surface fits and no
43+
faithful analog exists, it's a checklist scene — don't invent fake UI for
44+
something we can't represent honestly.
45+
46+
### 3 · Two-layer script (spoken vs display)
47+
48+
Write the script as **token lines** per `references/script-voice.md`:
49+
conversational register, every technical term carrying a `spoken` phonetic
50+
form from `references/lexicon.json` while `display` keeps standard spelling.
51+
Captions show `display`; the VO reads `spoken`. Any term not in the lexicon:
52+
STOP and ask the user how it's pronounced, then add it to the lexicon.
53+
Save as `script-tokens.json` in the project.
54+
55+
### 4 · VO — Annie (HeyGen, pinned)
56+
57+
```bash
58+
# spoken-layer text only; words JSON = ground-truth timestamps of the SPOKEN text
59+
# Repo-native path: the changelog-video skill runs from the hyperframes repo root,
60+
# so it uses the tracked hyperframes-media TTS helper directly (no `npx hyperframes
61+
# skills` install step). If you've copied the skill into another repo, swap in
62+
# your own path to the media-use / hyperframes-media heygen-tts.mjs.
63+
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
64+
-o voiceover.mp3 --words vo-words.json \
65+
--voice 330290724a1b470fb63153f34d4c0183 # Annie — lifelike (do not substitute)
66+
```
67+
68+
Requires `heygen` CLI ≥0.3.0 authenticated (`heygen auth login --oauth`).
69+
Then align spoken timestamps back to display tokens:
70+
71+
```bash
72+
node <SKILL_DIR>/scripts/align-captions.mjs \
73+
--tokens script-tokens.json --words vo-words.json --out captions.json
74+
```
75+
76+
`captions.json` is the caption-rail input (display spelling, spoken timing).
77+
The aligner prints `MISMATCH` warnings — resolve every one before building
78+
(usually a lexicon spelling the TTS renders as multiple words). **The audio
79+
is the clock**: all beat times come from `vo-words.json`; a VO regen re-opens
80+
every seam.
81+
82+
### 5 · Build
83+
84+
Follow `references/build-spec.md` exactly: brand tokens + fonts (bundled in
85+
`<SKILL_DIR>/assets/`), the animated background encode, scene scaffold,
86+
chrome, caption rail, one rationed green moment per scene. Then the doctrine
87+
order: `ledger.json` (all ordinary seams cut-the-curve LEFT) → seam-stamp →
88+
internal beats on VO words → seam-gate verify.
89+
90+
### 6 · Gates (all green before presenting)
91+
92+
1. `npx hyperframes@latest check` — 0 errors (contrast: dim text ≥ .66 alpha).
93+
2. `seam-gate.mjs verify` — 0 fail.
94+
3. Restart the preview server (it caches the bundle), spot-check 3-4 beats
95+
via `__player.seek` on the raw comp page.
96+
4. Do NOT render unless the user asks. After a requested render, verify
97+
frames from the MP4 (`ffmpeg -ss <t> … -frames:v 1`): captions present,
98+
background video not black, no tiny/frozen frames.
99+
100+
## Project layout
101+
102+
```
103+
projects/active/weekly-changelog-<range>/
104+
├── index.html # single-doc master (scenes as slides, stamped seams)
105+
├── ledger.json # vector ledger (seam-stamp input)
106+
├── script-tokens.json # two-layer script (source of truth for VO + captions)
107+
├── vo-spoken.txt # generated: spoken layer, one line
108+
├── voiceover.mp3 + vo-words.json + captions.json
109+
├── bgm.mp3 # copy from <SKILL_DIR>/assets/bgm.mp3 (the house track) unless the user supplies one
110+
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4
111+
```
112+
113+
## Anti-patterns
114+
115+
| Don't | Instead |
116+
|---|---|
117+
| Bullet-point slides for UI changes | Mock the surface acting out the change |
118+
| Fake UI for un-representable items | Honest checklist scene |
119+
| Plain "JSON"/"CLI" in the TTS text | Lexicon spoken forms; display stays standard |
120+
| Phonetic spellings in captions | Captions always render the display layer |
121+
| Guessing an unknown term's pronunciation | Ask, then grow the lexicon |
122+
| Speaking every changelog item | ≤3 per theme; the digest link carries the rest |
123+
| Green accents everywhere | One green moment per scene (#5ef17c) |
12.2 MB
Binary file not shown.
5.07 MB
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

0 commit comments

Comments
 (0)