Skip to content

Commit 2efbfd4

Browse files
docs(prompting): document the intent interview and align pages with skill contracts (#2872)
* docs(prompting): correct workflow one-liners against skill contracts general-video leads with its positive identity and companion mode; faceless-explainer keys on invented visuals instead of TTS; talking-head-recut uses the 'graphic overlays' trigger term; motion-graphics gains its input side and overlay output; music-to-video stops implying images are required. * docs(prompting): make vocabulary video grids readable Replace the 4-5 column table hack with a 3-column CSS grid, switch demo clips to autoplay muted loops (no black poster frame, no player chrome over tiny videos), and align cells at 16:9. * docs(prompting): document the opening interview and run-shape questions The guide taught prompt shapes but never prepared readers for the conversation that follows: the intent interview, the two run-shape questions (storyboard, automation vs companion), the just-build-it skip, and BRIEF.md as the resumable artifact. Add that section to the overview, a disambiguation note on the storyboards page, and free up 'companion' as a reserved term in media-and-audio. * docs(guides): make BRIEF.md the pipeline's Step 3 artifact Step 3 (Strategy & Messaging) listed no output while describing exactly what BRIEF.md now captures. Name the artifact in the step table, project tree, step body, gate, and iterating list, and fix SCRIPT.md's step label in the tree (Step 4, not 3). * docs(quickstart): realign the setup surface with the skills catalog The quickstart drifted from docs/guides/skills.mdx, CLAUDE.md, and the prompting overview — it had never been updated when those surfaces were: - `--full-depth` on both install commands, with the reason inline. Without it `skills add` fetches the skills.sh registry blob, which lags `main` by hours, so a reader following the quickstart installs stale skills. - `check` in the `/hyperframes-cli` row, and a validate step in the manual dev loop, which went preview → render with no gate at all. The prompting overview calls `check` "the step people skip and regret" and states both `lint` and `check` must pass before rendering. - `/hyperframes-keyframes` in the core-skills table (8 rows → 9). - `/figma` in the optional-workflow list (10 → 11). * docs(skills): close the catalog drift class and complete the music-to-video input Follow-up on the two review nits from #2872. `/music-to-video`'s SKILL.md names three inputs — an audio file, a video to pull audio from, or a track generated from a mood brief. Every compressed copy of that description carried only the first two, and the third is the one that makes "a complete video needs zero assets" true. Fixed on all eight surfaces that state it, so no surface is now more correct than its siblings: the prompting overview and quickstart setup tables, docs/guides/skills.mdx, the README catalog, root CLAUDE.md + AGENTS.md, both CLI project templates, and the router's own routes/music-to-video.md Input line (whose Interview must-haves already listed all three). The drift was structural, not accidental: the sync set declared in docs/guides/skills.mdx and in CLAUDE.md's "Skill catalog maintenance" named four surfaces and never the two setup tables, so those two were free to rot while the declared four stayed correct. Both declarations now name them, and both say the set applies to a *changed contract* — a reworded description — not only to an added or renamed skill. skills-manifest.json regenerated for the touched route file. * docs(claude): point the routing-surface rule at routes/, not the moved stubs Item 3 of "Skill catalog maintenance" still sent readers to `references/workflow-catalog.md` for a workflow's input/output/trigger contract and `references/route-briefs.md` for its interview entry. Both are now "moved" stubs — the contract and the interview entry live together in `references/routes/<workflow>.md`, one read per candidate route. Same failure class the previous commit fixed at item 1: a maintenance rule outliving the layout it describes. Swept the tree for other pointers at the two stubs; there are none, so this closes it rather than fixing one instance.
1 parent 10b517d commit 2efbfd4

14 files changed

Lines changed: 90 additions & 38 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ npx skills add heygen-com/hyperframes --full-depth # interactive picker (termi
1919
- `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed **graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath, footage untouched. For plain captions/subtitles → `/embedded-captions`.
2020
- `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → code-change explainer, up to ~3 min (changelog / feature reveal / fix / refactor). A PR link, not a product website.
2121
- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`.
22-
- `/music-to-video` — a **music track** (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
22+
- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
2323
- `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
2424
- `/general-video` — fallback for any other video creation (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes flow — design → plan → layout → build → validate, any length.
2525

‎CLAUDE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Keep `--full-depth`: it installs the current `main`. Without it, `skills add` fe
2525
- `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (verbatim rail + embedded climax, or pure-cinematic embed); the footage itself is untouched (no NLE-style editing).
2626
- `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed **graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, PiP) synced to the transcript; the clip plays unchanged underneath, footage untouched. For plain captions/subtitles → `/embedded-captions`.
2727
- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`.
28-
- `/music-to-video` — a **music track** (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
28+
- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
2929
- `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
3030
- `/general-video` — fallback for any other video creation (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes flow — design → plan → layout → build → validate, any length.
3131
- `/remotion-to-hyperframes` — port an existing Remotion (React) composition to HyperFrames HTML. One-way migration, not creation.
@@ -47,9 +47,9 @@ Atomic capabilities the creation workflows compose against — pull one when you
4747

4848
When adding a new skill, or substantially renaming / repurposing an existing one, update all agent-facing discoverability surfaces in lockstep:
4949

50-
1. The skill list above (CLAUDE.md) AND the workflow list in the root `AGENTS.md` (it carries workflows only, no domain-skill section) AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)). Out-of-date entries silently kill discovery.
50+
1. The skill list above (CLAUDE.md) AND the workflow list in the root `AGENTS.md` (it carries workflows only, no domain-skill section) AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup tables that compress the same descriptions — `docs/prompting/overview.mdx` ("One-time setup") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill.
5151
2. The scaffolded project template `packages/cli/src/templates/_shared/CLAUDE.md` + `AGENTS.md` — written into every `hyperframes init` project, so a stale entry there ships to users. The two template files must stay byte-identical.
52-
3. If the skill changes the routing surface for "make a video" requests, also update the routing table + intent layer in `skills/hyperframes/SKILL.md` AND that workflow's entry in `skills/hyperframes/references/workflow-catalog.md` (the input/output/trigger contract the router reads before the workflow is installed) — plus its row in `references/route-briefs.md` when the route asks questions.
52+
3. If the skill changes the routing surface for "make a video" requests, also update the routing table + intent layer in `skills/hyperframes/SKILL.md` AND that workflow's own route file, `skills/hyperframes/references/routes/<workflow>.md`. One file carries both halves: the input/output/trigger contract the router reads before the workflow is installed, and its interview entry (must-haves, conditionals, deferred asks, run-shape). The older `references/workflow-catalog.md` and `references/route-briefs.md` are now "moved" stubs pointing at `routes/` — don't edit them.
5353
4. Mirror the Router / Creation workflows / Domain skills grouping across all surfaces so a skill always lives in the same column.
5454
5. Skill count appears in the README and CLAUDE.md intro lines ("19 AI agent skills…") — update on add/remove. The `docs/guides/skills.mdx` page and the CLI templates deliberately omit a count to avoid drift; keep them count-free.
5555

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ This writes `dist/hyperframes-plugin.zip` with a `hyperframes/` root folder and
8585
| `/embedded-captions` | Adding **captions / subtitles** to an existing talking-head video (footage untouched) — verbatim rail, embedded climax behind the subject, or pure-cinematic embed. |
8686
| `/talking-head-recut` | Packaging an existing talking-head / interview / podcast video with **designed graphic overlays** — lower-thirds, data callouts, kinetic titles, pull-quotes, side panels, PiP. |
8787
| `/motion-graphics` | A short, **unnarrated, design-led motion graphic** (~under 10s) — kinetic type, stat / chart hit, logo sting, lower-third, animated tweet / headline. MP4 or transparent overlay. |
88-
| `/music-to-video` | A **music track** (audio file, or video to pull audio from) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. |
88+
| `/music-to-video` | A **music track** (audio file, video to pull audio from, or one generated from a mood brief) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. |
8989
| `/slideshow` | A **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. |
9090
| `/general-video` | **Anything else** — longer or multi-scene pieces, brand / sizzle reel, title card, static loop, freeform composition. Input- and length-agnostic fallback, and the home of companion mode (co-create with the full toolbox). |
9191
| `/remotion-to-hyperframes` | **Porting an existing Remotion** (React) composition's source to HyperFrames HTML. One-way migration, not creation. |

‎docs/guides/pipeline.mdx‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Each step produces an artifact that feeds the next:
1515
|---|-------------------------|-----------------------------------------|-------------------------------------------------------------------------|
1616
| 1 | **Capture** | `capture/` | Extract screenshots, design tokens, fonts, assets, animations from a source |
1717
| 2 | **Design** | `DESIGN.md` | Brand reference: colors, typography, component stylings, spacing, iteration guide |
18-
| 3 | **Strategy & Messaging**| — | Align on video type, style, the ONE message, narrative arc, and audience |
18+
| 3 | **Strategy & Messaging**| `BRIEF.md` | Lock video type, style, the ONE message, arc, audience — and the run's shape (automation or companion, storyboard or one-shot) |
1919
| 4 | **Storyboard + Script** | `STORYBOARD.md` + `SCRIPT.md` | Concept-first storyboard and narration script, written together |
2020
| 5 | **VO + Timing** | `narration.wav` + `transcript.json` | TTS audio with word-level timestamps |
2121
| 6 | **Build** | `compositions/*.html` | Animated HTML compositions, one per beat |
@@ -38,7 +38,8 @@ my-video/
3838
│ ├── AGENTS.md # capture summary for AI agents
3939
│ └── CLAUDE.md
4040
├── DESIGN.md # Step 2, brand cheat sheet
41-
├── SCRIPT.md # Step 3, narration backbone
41+
├── BRIEF.md # Step 3, confirmed intent: message, audience, run shape
42+
├── SCRIPT.md # Step 4, narration backbone
4243
├── STORYBOARD.md # Step 4, beat-by-beat creative plan
4344
├── narration.wav # Step 5, TTS audio
4445
├── narration.txt # Step 5, exact spoken text (with pronunciation subs)
@@ -92,13 +93,15 @@ A typical `DESIGN.md` has five sections:
9293

9394
## Step 3: Strategy & Messaging
9495

95-
**Output:** Alignment on video type, duration, style, and — critically — the ONE message and narrative arc
96+
**Output:** `BRIEF.md` in the project root
9697

9798
Before any creative decisions, align with the user on the story this video must tell. Parse the user's prompt first — they probably already gave you the video type and style. Only ask about things they didn't specify. If the prompt is detailed enough, confirm the direction in one message and move to Step 4.
9899

99100
The questions to resolve: what type of video (social ad, product demo, brand reel, etc.), what style and energy, what's the ONE thing this video must communicate, what narrative arc serves that message, and whether narration is wanted.
100101

101-
**Gate:** Video type, duration, format, and the message and narrative arc are locked. Without those, Step 4 can't write a concept-first storyboard.
102+
When the project starts from `/hyperframes`, this step is the [opening interview](/prompting/overview#the-interview-what-the-agent-asks-first) — and it runs before Step 1, since the answers decide whether there's anything to capture at all. Either way, the confirmed answers land in `BRIEF.md`: frontmatter keys for the deterministic fields (`workflow`, `flow`, `storyboard`, `message`, audience, length), prose sections for the intent and any supplied material. A later session resumes from this file instead of re-asking.
103+
104+
**Gate:** `BRIEF.md` exists — video type, duration, format, message, and narrative arc locked. Without those, Step 4 can't write a concept-first storyboard.
102105

103106
## Step 4: Storyboard + Script
104107

@@ -185,6 +188,7 @@ For personalized or catalog outputs, render the same validated composition with
185188

186189
The pipeline is built around named artifacts on disk so you can re-enter anywhere without re-running everything:
187190

191+
- To change what the video is *for* — the message, the audience, the run's shape — edit `BRIEF.md`; it's the file the agent trusts over chat history.
188192
- To rework the creative plan, edit `STORYBOARD.md`: change a beat's mood, swap an asset, retime the entrance, then ask the agent to rebuild just that beat.
189193
- For surgical tweaks, open a composition file directly (e.g. `compositions/beat-3-proof.html`) and adjust animations, colors, or layout. `npx hyperframes preview` shows changes live.
190194
- To rebuild one beat from scratch, prompt the agent: _"Rebuild beat 2 with more energy. Use the product screenshot as full-bleed background."_ It reads `STORYBOARD.md`, `DESIGN.md`, and the transcript, then regenerates just that file.

‎docs/guides/skills.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ One workflow per input shape. The router (`/hyperframes`) picks one of these for
8989
| `/embedded-captions` | Adding **captions / subtitles** to an existing talking-head video (footage untouched) — verbatim rail, embedded climax behind the subject, or pure-cinematic embed. |
9090
| `/talking-head-recut` | Packaging an existing talking-head / interview / podcast video with **designed graphic overlays** — lower-thirds, data callouts, kinetic titles, pull-quotes, side panels, PiP. |
9191
| `/motion-graphics` | A short, **unnarrated, design-led motion graphic** (~under 10s) — kinetic type, stat / chart hit, logo sting, lower-third, animated tweet / headline. MP4 or transparent overlay. |
92-
| `/music-to-video` | A **music track** (audio file, or video to pull audio from) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. |
92+
| `/music-to-video` | A **music track** (audio file, video to pull audio from, or one generated from a mood brief) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. |
9393
| `/slideshow` | A **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. |
9494
| `/general-video` | **Anything else** — longer or multi-scene pieces, brand / sizzle reel, title card, static loop, freeform composition. Input- and length-agnostic fallback, and the home of companion mode (co-create with the full toolbox). |
9595
| `/remotion-to-hyperframes` | **Porting an existing Remotion** (React) composition's source to HyperFrames HTML. One-way migration, not creation. |
@@ -111,7 +111,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
111111

112112
## Source of truth
113113

114-
The one-line "use when" for each skill comes from its own `SKILL.md` frontmatter `description:` field in the [hyperframes repo](https://github.com/heygen-com/hyperframes/tree/main/skills). The same catalog lives in the [README's `## Skills` section](https://github.com/heygen-com/hyperframes#skills) and the repo `CLAUDE.md`; all three surfaces are kept in sync when a skill is added or renamed.
114+
The one-line "use when" for each skill comes from its own `SKILL.md` frontmatter `description:` field in the [hyperframes repo](https://github.com/heygen-com/hyperframes/tree/main/skills). The same catalog lives in the [README's `## Skills` section](https://github.com/heygen-com/hyperframes#skills) and the repo `CLAUDE.md`. Two more surfaces compress the same descriptions and drift the same way, so they belong to the same sync set: the setup tables in the [prompting guide](/prompting/overview#one-time-setup) and the [quickstart](/quickstart). All of them are kept in sync when a skill is added, renamed, or has its contract changed.
115115

116116
## Next steps
117117

‎docs/prompting/media-and-audio.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Media and audio
33
description: "Ask for the voiceover, music, sound, captions, cutouts, and assets a composition needs — with the precise, unambiguous phrasing the media pipeline acts on."
44
---
55

6-
By now your video moves and reads right; this level gives it a voice. HyperFrames owns media *playback*; a companion media pipeline resolves everything else — voice, music, sound effects, images, icons, logos, captions, and background removal. You reach all of it by describing what the composition needs, and the agent resolves each need to a frozen local file. The craft here is precision: vague media asks ("add some music," "no sound") are the ones that come back wrong, because the pipeline does exactly what the words say.
6+
By now your video moves and reads right; this level gives it a voice. HyperFrames owns media *playback*; a sibling media pipeline resolves everything else — voice, music, sound effects, images, icons, logos, captions, and background removal. You reach all of it by describing what the composition needs, and the agent resolves each need to a frozen local file. The craft here is precision: vague media asks ("add some music," "no sound") are the ones that come back wrong, because the pipeline does exactly what the words say.
77

88
## Voiceover (TTS)
99

0 commit comments

Comments
 (0)