From e0190c4c7a5f3a4b49798d42ca812a3bbcfc0a43 Mon Sep 17 00:00:00 2001 From: Miguel Angel Simon Sierra Date: Fri, 18 Sep 2026 23:32:17 -0400 Subject: [PATCH 1/2] docs(skills): the agent presents a tailor-made storyboard page instead of a Studio board Adds the storyboard recipe (decisions first, beat fields, a self-contained storyboard.html contact sheet, a review round) distilled from the launch films, and rewrites the review loop, brief contract, storyboard format and workflow steps that still described the deleted board and comments file. --- docs/prompting/overview.mdx | 4 +- docs/prompting/storyboards.mdx | 2 +- packages/core/src/storyboard/types.ts | 2 +- skills-manifest.json | 18 +++--- skills/faceless-explainer/SKILL.md | 10 ++-- skills/general-video/SKILL.md | 6 +- skills/hyperframes-cli/SKILL.md | 10 +--- .../references/story-spine.md | 2 + .../references/storyboard-recipe.md | 57 +++++++++++++++++++ skills/hyperframes/SKILL.md | 2 +- .../hyperframes/references/brief-contract.md | 30 +++++----- skills/hyperframes/references/brief-format.md | 16 +++--- .../references/frame-worker-core.md | 2 +- .../references/intent-interview.md | 20 +++---- .../hyperframes/references/production-loop.md | 22 +++---- skills/hyperframes/references/review-loop.md | 26 ++++----- .../references/routes/motion-graphics.md | 2 +- .../hyperframes/references/script-format.md | 4 +- .../references/storyboard-format.md | 35 +----------- skills/music-to-video/SKILL.md | 2 +- skills/music-to-video/references/planning.md | 4 +- skills/pr-to-video/SKILL.md | 10 ++-- skills/product-launch-video/SKILL.md | 10 ++-- 23 files changed, 157 insertions(+), 139 deletions(-) create mode 100644 skills/hyperframes-creative/references/storyboard-recipe.md diff --git a/docs/prompting/overview.mdx b/docs/prompting/overview.mdx index bdf1f67d6b..6626229ba7 100644 --- a/docs/prompting/overview.mdx +++ b/docs/prompting/overview.mdx @@ -120,10 +120,10 @@ Either shape starts a short interview before anything is built. This isn't the a | Question | Your options | | --- | --- | -| **Storyboard?** | `yes` — review the plan, wireframe sketches, and the build pass by pass on a live board (recommended past a couple of scenes) · `no` — one finished video from the confirmed brief | +| **Storyboard?** | `yes` — review the plan in chat, wireframe sketches on a `storyboard.html` page you open in a browser, and the build pass by pass (recommended past a couple of scenes) · `no` — one finished video from the confirmed brief | | **Automation or companion?** | `automation` — the matched workflow's pipeline executes the brief end to end · `companion` — build it together in `/general-video` with every HyperFrames capability on the table | -The two are independent — all four combinations are valid, and a companion run reviews on the live board too when you said yes to the storyboard. Four routes skip both questions because neither has anything to add: `/motion-graphics` (the piece is seconds long), `/slideshow` (the deliverable is a navigable deck, not a rendered video), and `/embedded-captions` and `/talking-head-recut` (the footage is untouched, so there's no storyboard to review). +The two are independent — all four combinations are valid, and a companion run goes through the same review passes when you said yes to the storyboard. Four routes skip both questions because neither has anything to add: `/motion-graphics` (the piece is seconds long), `/slideshow` (the deliverable is a navigable deck, not a rendered video), and `/embedded-captions` and `/talking-head-recut` (the footage is untouched, so there's no storyboard to review). In a hurry, skip the whole conversation by saying so: diff --git a/docs/prompting/storyboards.mdx b/docs/prompting/storyboards.mdx index 16da82f75d..f0146093b4 100644 --- a/docs/prompting/storyboards.mdx +++ b/docs/prompting/storyboards.mdx @@ -14,7 +14,7 @@ Prompt the **plan** once instead — the throughline, the job each frame does, t This narrative vocabulary is a writing discipline, not extra `STORYBOARD.md` schema. The workflow translates your plan into the smaller machine-readable shape the build consumes. -"Storyboard" is also a question the agent asks in the [opening interview](/prompting/overview#the-interview-what-the-agent-asks-first). Say yes there and the plan, the sketches, and the build all get reviewed with you pass by pass on a live board. That answer changes the review process, not the route. Either way, the plan this page teaches is what the build works from. +"Storyboard" is also a question the agent asks in the [opening interview](/prompting/overview#the-interview-what-the-agent-asks-first). Say yes there and the plan (in chat), the sketches (a `storyboard.html` page you open in a browser), and the build all get reviewed with you pass by pass. That answer changes the review process, not the route. Either way, the plan this page teaches is what the build works from. ## Prompt the plan, not the scenes diff --git a/packages/core/src/storyboard/types.ts b/packages/core/src/storyboard/types.ts index 9e7cf144ae..aae4578443 100644 --- a/packages/core/src/storyboard/types.ts +++ b/packages/core/src/storyboard/types.ts @@ -22,7 +22,7 @@ export const SCRIPT_FILENAME = "SCRIPT.md"; /** * Lifecycle of a single frame. The agent advances each frame - * `outline → built → animated`; the Studio renders progress from this. + * `outline → built → animated`; scripts and the agent read progress from this. */ export type FrameStatus = "outline" | "built" | "animated"; diff --git a/skills-manifest.json b/skills-manifest.json index 684952dc70..95987ab32f 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -6,7 +6,7 @@ "files": 142 }, "faceless-explainer": { - "hash": "b5a85c762928ba92", + "hash": "39e1e4d42e9a5ebe", "files": 24 }, "figma": { @@ -14,11 +14,11 @@ "files": 2 }, "general-video": { - "hash": "ab15530f09bec21c", + "hash": "079d3479295e27b4", "files": 4 }, "hyperframes": { - "hash": "30397aa94f47ecc8", + "hash": "8917744c859712f9", "files": 26 }, "hyperframes-animation": { @@ -30,7 +30,7 @@ "files": 7 }, "hyperframes-cli": { - "hash": "656d872004d9e2e8", + "hash": "13f4e5fda3baf7c8", "files": 11 }, "hyperframes-core": { @@ -38,8 +38,8 @@ "files": 11 }, "hyperframes-creative": { - "hash": "7b6b7a78102da71b", - "files": 78 + "hash": "72702af1fbb21bf3", + "files": 79 }, "hyperframes-keyframes": { "hash": "6bc62531ecea9a52", @@ -62,15 +62,15 @@ "files": 23 }, "music-to-video": { - "hash": "e69f4646ef354be9", + "hash": "190e9885dab9b11d", "files": 169 }, "pr-to-video": { - "hash": "4b550901e129c709", + "hash": "da3a68c5a2a86f77", "files": 30 }, "product-launch-video": { - "hash": "3ab59cd235681ee9", + "hash": "ced501f76c52716b", "files": 30 }, "remotion-to-hyperframes": { diff --git a/skills/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md index 55365bf37c..e3012c3b67 100644 --- a/skills/faceless-explainer/SKILL.md +++ b/skills/faceless-explainer/SKILL.md @@ -87,7 +87,7 @@ Read `../hyperframes-creative/references/story-spine.md` (hook language, value-b Use `story-design.md` for the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and `VO_MODE`. The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits. Teaching truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Faceless visuals are invented downstream, so frames do **not** carry an asset inventory: leave `asset_candidates` empty unless the user supplied a real `public/` image. Use the exact required fields from the storyboard and script references. -After drafting, run the review loop's plan pass — `../hyperframes/references/review-loop.md` § 1: present the plan as a proposal, and ask the two questions — approve or change, and **sketches first** (recommended) or skip. Feedback loops through chat or the board's comments file until approved. This is a **checkpoint gate** (brief contract § 1): in autonomous mode there is no board and nothing to ask — post the same summary as a heads-up and proceed; sketches collapse into the build, and the one preview question comes at Step 6. +After drafting, run the review loop's plan pass — `../hyperframes/references/review-loop.md` § 1: present the plan as a proposal, and ask the two questions — approve or change, and **sketches first** (recommended) or skip. Feedback arrives as a chat reply; loop until approved. This is a **checkpoint gate** (brief contract § 1): in autonomous mode there is nothing to ask — post the same summary as a heads-up and proceed; sketches collapse into the build, and the one preview question comes at Step 6. **Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up). @@ -117,7 +117,7 @@ If there is no narration and no `SCRIPT.md`, skip voice generation. BGM may stil Goal: Add the visual direction, layout intent, and motion choices to each storyboard frame. -**Sketch the board first (collaborative only).** The moment the plan is approved, run the sketch pass — `../hyperframes/references/review-loop.md` § 2 (don't wait on Step 3.1; sketches don't use timings): wireframe every frame yourself, mark each `built`, pause for the one layout question when the board is full, and revise only the sketches named until the board is confirmed. Only then write the visual design below onto the confirmed layouts. In autonomous mode, or when the user chose to skip sketches at Step 3, skip this pass — frames go straight from `outline` to `animated` at Step 5. +**Sketch the storyboard sheet first (collaborative only).** The moment the plan is approved, run the sketch pass — `../hyperframes/references/review-loop.md` § 2 (don't wait on Step 3.1; sketches don't use timings): wireframe every frame yourself as a cell of `storyboard.html` (`../hyperframes-creative/references/storyboard-recipe.md` § 3), mark each `built`, pause for the one layout question when every frame is `built`, and revise only the sketches named until the sheet is confirmed. Only then write the visual design below onto the confirmed layouts. In autonomous mode, or when the user chose to skip sketches at Step 3, skip this pass — frames go straight from `outline` to `animated` at Step 5. Edit `STORYBOARD.md` in place. Do not create another storyboard. Use `frame.md` as source of truth for color, type, layout feel, and style. @@ -129,7 +129,7 @@ For every frame, write a **time-coded shot sequence** into `STORYBOARD.md` per ` Do not change story, script, `transition_in`, or the source text. Do not write HTML in this step. There is **no asset-staging step** — faceless visuals are built by the workers in Step 5. If the user supplied a real `public/` image, reference it by path in the relevant frame's `focal`/`roles`; otherwise nothing to stage. -**Gate:** every frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); each frame names its invented `focal` and/or `roles`; `## Video direction` exists. Collaborative: the sketch board was confirmed. +**Gate:** every frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); each frame names its invented `focal` and/or `roles`; `## Video direction` exists. Collaborative: the sketch sheet was confirmed. --- @@ -165,7 +165,7 @@ After audio timings exist, build captions in the background and assemble the ind `captions.mjs` uses the project's `.hyperframes/caption-skin.html` (copied in Step 2) as the caption look, injecting brand tokens from `frame.md`; with no skin present it renders the built-in default pill. `captions: skipped ()` is valid. Continue without captions when explicitly skipped. -**Gate:** every frame is marked `animated` (collaborative: the sketch board was confirmed at Step 4), `index.html` exists, and captions are built or explicitly skipped. +**Gate:** every frame is marked `animated` (collaborative: the sketch sheet was confirmed at Step 4), `index.html` exists, and captions are built or explicitly skipped. --- @@ -191,7 +191,7 @@ If a command fails, surface stderr and stop — don't pile on recovery commands. **Known false-positive — do not chase it.** `check` may report a handful of `text_box_overflow` findings of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word. -After checks pass, pause for user review — the review loop's final look (`../hyperframes/references/review-loop.md` § 4): one question, on the Studio that has been open since Step 3 — render now, or what changes? (Autonomous: the one kept question, preview first or render.) Then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame. +After checks pass, pause for user review — the review loop's final look (`../hyperframes/references/review-loop.md` § 4): one question, on the final Studio preview — render now, or what changes? (Autonomous: the one kept question, preview first or render.) Then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame. Preview: `npx hyperframes preview --background` diff --git a/skills/general-video/SKILL.md b/skills/general-video/SKILL.md index 878fae18d7..223880b164 100644 --- a/skills/general-video/SKILL.md +++ b/skills/general-video/SKILL.md @@ -51,7 +51,7 @@ Use only the canonical terms from `../hyperframes/references/brief-contract.md`: | Field | Meaning | Effect | | -------------- | ------------------------------------- | ----------------------------------------------------------------------------------- | | `flow` | Who drives | `automation`: choose and execute the route. `companion`: co-create in conversation. | -| `storyboard` | Whether the board is a review surface | `yes`: run plan and sketch review. `no`: build without the board. | +| `storyboard` | Plan, sketch, and review before build | `yes`: run plan and sketch review (`storyboard.html`). `no`: build without it. | | derived `mode` | How checkpoint gates behave | Follow the brief contract. Never ask the user to name a mode. | Do not invent synonyms for these states. An ongoing “just build it” signal is handled by the intent layer and arrives as `flow: automation`, `storyboard: no`. @@ -101,8 +101,8 @@ Do not replace these reads with recollection. Progressive disclosure saves conte Use this dependency order. Skip a stage only when its input is absent. -1. **Plan.** State the viewer arc, structure, rhythm, and duration driver. Use one file for a short single scene; use sub-compositions for three or more hard scene cuts or any reused scene. Read `/hyperframes-creative` → `references/story-spine.md` for narrated arcs, `references/beat-direction.md` for rhythm, and `/hyperframes-core` → `references/composition-patterns.md` for structure. For an open-ended multi-scene brief, expand the prompt through `/hyperframes-creative` → `references/prompt-expansion.md`. A multi-scene plan cites each scene's shape: a blueprint id from `/hyperframes-animation` → `blueprints-index.md` when one fits, or the named rules it composes from `rules-index.md` when none does — motion names come from those indexes, never invented. Story truth decides which scenes exist; the citation dresses them. **Search the live catalog before you plan to build any named look yourself**: for every look, effect, treatment or transition the brief names — "CRT scanlines", "glitch", "film grain", "shimmer sweep", "confetti burst" — run `npx hyperframes catalog --query "" --json` and read the top results before the plan names how that look gets built. The search needs **nothing installed**: no project, no prior `add`, no account. It ranks the whole hosted registry (~400 blocks and components) from any directory, so it also applies to a look the user asks for mid-build. Blocks the plan names are installed at stage 3; hand-author a look only after a search for it came back with nothing that fits. A multi-scene plan is also recorded as the dispatch artifact: one `## Frame N` block per scene in `STORYBOARD.md` — `status: outline`, a declared `src:`, the blueprint/rules citation, and the beat text — **even when `storyboard: no`**. The block is the dispatch unit; the board is only the review surface. -2. **Review the plan when requested.** For `storyboard: yes`, run the shared review loop over those blocks. For `storyboard: no`, continue without opening the board. When a plan pause happens anyway, fold the sub-agent delegation grant (needed by codex for step 4's dispatch) into that pause rather than stopping again later. +1. **Plan.** State the viewer arc, structure, rhythm, and duration driver. Use one file for a short single scene; use sub-compositions for three or more hard scene cuts or any reused scene. Read `/hyperframes-creative` → `references/story-spine.md` for narrated arcs, `references/beat-direction.md` for rhythm, and `/hyperframes-core` → `references/composition-patterns.md` for structure. For an open-ended multi-scene brief, expand the prompt through `/hyperframes-creative` → `references/prompt-expansion.md`. A multi-scene plan cites each scene's shape: a blueprint id from `/hyperframes-animation` → `blueprints-index.md` when one fits, or the named rules it composes from `rules-index.md` when none does — motion names come from those indexes, never invented. Story truth decides which scenes exist; the citation dresses them. **Search the live catalog before you plan to build any named look yourself**: for every look, effect, treatment or transition the brief names — "CRT scanlines", "glitch", "film grain", "shimmer sweep", "confetti burst" — run `npx hyperframes catalog --query "" --json` and read the top results before the plan names how that look gets built. The search needs **nothing installed**: no project, no prior `add`, no account. It ranks the whole hosted registry (~400 blocks and components) from any directory, so it also applies to a look the user asks for mid-build. Blocks the plan names are installed at stage 3; hand-author a look only after a search for it came back with nothing that fits. A multi-scene plan is also recorded as the dispatch artifact: one `## Frame N` block per scene in `STORYBOARD.md` — `status: outline`, a declared `src:`, the blueprint/rules citation, and the beat text — **even when `storyboard: no`**. The block is the dispatch unit; the storyboard sheet is only the review surface. +2. **Review the plan when requested.** For `storyboard: yes`, run the shared review loop over those blocks. For `storyboard: no`, continue without a plan pause or sketch sheet. When a plan pause happens anyway, fold the sub-agent delegation grant (needed by codex for step 4's dispatch) into that pause rather than stopping again later. 3. **Resolve dependencies.** Install registry blocks before parallel work. Stage user assets, adopt existing media, and resolve only what the brief requires. Start audio early when its timings drive duration. 4. **Build scenes.** For a short single-scene piece, implement the scene at its most visible moment before adding motion (the confirmed wireframe, when present, is that end state and must not be redrawn), then animate from its cited blueprint or rules — read the full recipe body (`/hyperframes-animation` → `blueprints/.md`, `rules/.md`) before writing motion. diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index 5661c54cdb..459307346e 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -53,15 +53,9 @@ ffprobe -v error -show_format -show_streams out.mp4 `check` runs lint first, then uses one browser session and one seek pass to audit runtime errors, failed requests, layout, `*.motion.json` assertions, and WCAG contrast. Persistent findings gate the exit code; transient entrance or exit findings are informational. Use `--strict` to gate warnings. `validate`, `inspect`, and `layout` remain aliases for compatibility but must not appear in new instructions or scripts. -## Two different preview surfaces +## Preview before render -Do not confuse these states: - -| Surface | When it may open | Purpose | -| ------------------------- | -------------------- | -------------------------------------------------------------------- | -| Final composition preview | After `check` passes | Review the assembled timeline before render. Open `#project/`. | - -The early board is not approval of the final video. Rendering always requires the final approval defined by `hyperframes/references/review-loop.md`. +Open the final composition preview (`#project/`) only after `check` passes, to review the assembled timeline. The plan in chat and the `storyboard.html` sketch sheet are not approval of the final video. Rendering always requires the final approval defined by `hyperframes/references/review-loop.md`. ## Sub-composition smoke test diff --git a/skills/hyperframes-creative/references/story-spine.md b/skills/hyperframes-creative/references/story-spine.md index 5c6f2e6362..f87cd872a8 100644 --- a/skills/hyperframes-creative/references/story-spine.md +++ b/skills/hyperframes-creative/references/story-spine.md @@ -34,6 +34,8 @@ When Step 3 presents the plan (a checkpoint gate — `hyperframes/references/bri - Recommendations keep their receipts (brief-contract § 3): the archetype choice, the beat count, and any beat the user might question each state their basis. +How to write the storyboard itself, and the `storyboard.html` page it is reviewed on, is `storyboard-recipe.md`. + The proposal shape — echo line → frame table → style / duration footer → "approve or adjust" — is the cheapest place to iterate: a frame change here costs 30 seconds; the same change after build costs minutes. ## 4. Visuals point back to the source diff --git a/skills/hyperframes-creative/references/storyboard-recipe.md b/skills/hyperframes-creative/references/storyboard-recipe.md new file mode 100644 index 0000000000..7a2de80a00 --- /dev/null +++ b/skills/hyperframes-creative/references/storyboard-recipe.md @@ -0,0 +1,57 @@ +# Storyboard recipe — plan a video like the launch films + +Applies wherever a run plans on a storyboard (`storyboard: yes` in `brief-contract.md`). This file owns **how to make the storyboard**: what goes in it, and the one HTML page the user reviews. `review-loop.md` owns when the user is asked; `storyboard-format.md` owns the `STORYBOARD.md` file the scripts parse; `story-spine.md` owns the order of the story. The method is distilled from the shipped launch films' storyboards (a header, a named spine, a beat list, a contact sheet, a review round) and from how their handoffs describe them. Nothing here is a Studio feature: the agent writes the storyboard, the user reads it in chat and in a browser. + +## 1. Open with the decisions, before any beat + +Message, audience, arc and format go in the `STORYBOARD.md` frontmatter (`storyboard-format.md`); the rest go in sections above the first `## Frame` heading. Frame packets take everything after a frame heading to the next one, so a section placed after the last frame leaks into that frame's packet. Repeat the first three in the chat proposal: + +- **Message**: one sentence, written as a claim, not a topic ("Close isn't final", not "About the inspector"). +- **Audience and arc**: who watches, and the arc named in one line (pain → turn → proof → logo, or the workflow's own archetype). +- **Format**: aspect, target length, voiceover yes/no, music yes/no. Caption keep-out (content in the top ~83% when captions run). +- **The spine**: the one device that threads every beat, named now, not discovered while building (a persistent window, a silent button that finally has sound, one background that leads every transition). +- **Brand, from a capture**: palette by role with hex, three type roles (display, sans, mono) with sizes, radii and easings, each token noting where it came from. Take them from the real site or product, never from memory; `frame.md` holds them. +- **Bans**: a short per-video "do not" list (no glow, no side-by-side explainer layouts, no fake product UI, no static endcard). Name two motion failures to avoid: the slideshow (every beat a fresh card) and the screensaver (motion that says nothing). +- **Held frame**: allocate one beat on purpose where nothing moves and the line lands. + +## 2. The beat list + +One beat per idea, one focus per beat. Give each beat a short semantic name that will also be its composition filename. + +| Field | Rule | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| Heading | `NN — Name (start–end, ~dur)`, absolute times. Sum the durations and state the total; check it against the target length by arithmetic. | +| Beat length | 1.5–3.5 s. A beat that must be read gets ~3 s; a beat that only hands off gets 1.5–2 s; a line of 5–7 words gets 2–2.5 s. | +| On screen | What is visible, in concrete terms (the object, its count, its position), with every on-screen word verbatim in quotes. | +| Voiceover | Verbatim, or `onscreen` for silent films. Reveals land on the word or beat cue that names them. | +| Hero prop | The object that persists, and the beat where it returns (callback). A callback beat states which earlier beat it answers. | +| Motion | Named moves with easing and duration, from a small vocabulary. First visible motion within 0.2 s of the beat starting. | +| Seam out | The named transition into the next beat and its direction. One direction rule for the whole film (leftward is the default). | +| Audio cue | Sound effect or music cue with its time, when the film has sound. | +| Constraint | At least one explicit "no …" per beat that could go generic. | +| Why | The beat's job in the story, traced to the message. A beat whose why cannot be traced is cut. | + +Real product proof is real: a captured screen, the real command output, or a labelled placeholder beat that holds the slot. Never draw a vendor's UI in DOM. Where the film depicts something real, add a truthfulness line saying what is real. + +Craft devices that make a storyboard specific (hero prop, accumulation, breather, callback, two-color discipline) are taught with examples in `docs/prompting/storyboards.mdx`; use them by name. + +## 3. `storyboard.html`: the page the user reviews + +Write one self-contained HTML file in the project root, `storyboard.html`, from `STORYBOARD.md`. Tell the user the path and to open it in a browser. It is the review surface, and it must be beautiful enough to judge the film from. + +- **Header**: title with a version (`v1`), one-line dek, and a tag with resolution, length and beat count. +- **Grid**: three columns of 16:9 cells (`aspect-ratio: 16 / 9`, `container-type: inline-size`, sizes in `cqw` so the sheet matches the build), chronological, grouped under an act bar when there are acts. +- **Each cell** carries `id="frame-NN"` (the build reads its layout from there) and shows the beat's key moment drawn with the real words in the real fonts and brand colors, plain shapes for panels, charts and media, one accent on the focal. Then a label row (`NN · NAME` left, `id · start–end` right), a note that says what moves first and which way the seam goes (bold lead-in, one or two sentences), and a small chip naming the seam. +- **Two closing cells**: a seam map (every seam on one strip) and a tokens cell (palette, type roles, bans). +- **No motion, no scripts, no external assets.** Fonts are local `@font-face` or a system stack; images are inlined or relative. It must open from `file://`. + +A sketch is a few dozen lines of HTML per cell; the whole sheet lands in minutes. Sketch fidelity is the point: a reviewer reacts to placement, hierarchy and copy, which is why the build later dresses the layout and never redraws it. + +## 4. The review round + +1. Present the chat proposal (`story-spine.md` § 3), then the sheet. +2. Record the user's notes verbatim under `## Changes from v1` and unresolved questions under `## Still open` (above the first frame), then bump the version and revise **only the beats named**. +3. Repeat until the user says the layout is locked, then list what is locked under `## Locked`. Build only after the lock. +4. When the build lands, the compositions are the truth: regenerate the timing table from `index.html` (and the transcript when there is voiceover) and update `STORYBOARD.md` and `storyboard.html` to match, because every launch film drifted from its storyboard. State the final length. + +Do not render until asked. diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 179da100f2..ab648b0130 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -66,7 +66,7 @@ Before finalizing the route, read `references/routes/.md` — one smal - An explicitly short motion graphic may use a URL, tweet, article, or screenshot as source material. A generic "make a video from this site" request is `/product-launch-video`. - Existing footage with captions routes to `/embedded-captions`; footage with designed information cards routes to `/talking-head-recut`. Retiming, reordering, recoloring, reframing, or remixing footage is a custom edit and falls through to `/general-video`. - A music file selects `/music-to-video` only when its beat grid drives the piece. Music used as a bed does not override the subject-matched route. -- "I want a storyboard" changes the review process, not the workflow. With no other routing signal, use `/general-video`. A confirmed sketched board may itself be the requested deliverable; the review loop defines that stop point. +- "I want a storyboard" changes the review process, not the workflow. With no other routing signal, use `/general-video`. A confirmed sketched `storyboard.html` may itself be the requested deliverable; the review loop defines that stop point. - Specialized narrative workflows support up to about 3 minutes and are strongest around 30–90s. Route a clearly longer piece to `/general-video`. Length never overrides an explicit port, deck, caption, overlay, or music-driven deliverable. ## 3. Route once, then leave diff --git a/skills/hyperframes/references/brief-contract.md b/skills/hyperframes/references/brief-contract.md index 416e409bbd..a1805f7672 100644 --- a/skills/hyperframes/references/brief-contract.md +++ b/skills/hyperframes/references/brief-contract.md @@ -15,7 +15,7 @@ Three terms describe different concerns. Do not substitute one for another. | Term | Values | Owns | | ------------ | ------------------------------- | --------------------------------------------------------------------------------------------- | | `flow` | `automation` or `companion` | Who drives execution. `companion` always executes in `/general-video`. | -| `storyboard` | `yes` or `no` | Whether the live board is used for plan and layout review. | +| `storyboard` | `yes` or `no` | Whether the plan and layouts are reviewed before building (`review-loop.md`). | | `mode` | `collaborative` or `autonomous` | How later preference and checkpoint gates behave. The user never chooses this label directly. | Derive `mode` once from the confirmed run shape: @@ -50,9 +50,9 @@ Autonomous mode never silently drops a required capability. If the selected work Rendering remains user-gated in both modes. After checks pass, collaborative runs ask “render now, or what changes?” Autonomous runs ask “preview first, or render?” Render only after the answer. -### Studio comments +### Checkpoint feedback -Checkpoint feedback may arrive in chat or in `.hyperframes/frame-comments.json` (format: `storyboard-format.md`). When the user replies to a checkpoint, read that file before interpreting the chat reply. Apply only the named frame changes, delete the comments file after handling it, and re-present the affected frames. A board submission does not notify the agent, so tell the user to reply in chat after submitting comments. +Checkpoint feedback arrives as a chat reply. Apply only the frames it names and re-present them. Autonomous is not silent: replace absorbed questions with visible decisions and short reasons. Every autonomous visual or video delivery names the final preview or rendered artifact as applicable, reports the actual duration for a time-based deliverable, and includes a contact sheet or snapshot sheet plus relevant frame identifiers when available. For multi-scene work, use scene midpoints; for a single-scene piece, use one or more proof times. This gives the user a review surface even though intermediate checkpoints did not pause. @@ -60,18 +60,18 @@ Autonomous is not silent: replace absorbed questions with visible decisions and Ask only fields used by the selected route. Route entries identify their must-have questions and deferred questions. Values inferred or derived by policy are stated in the brief, not asked. -| Field | Meaning | Policy | -| ------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `flow` | Who drives execution | Ask at the end of intent capture when the route supports both flows. An autonomous signal answers it. | -| `storyboard` | Whether to review on the live board | Ask before `flow` when the route supports a board. A storyboard request answers it. | -| `destination` | Where the video will play | Infer from the request. Ask only when unknown and the answer changes aspect, type scale, or composition. | -| `aspect` | Canvas size | Derive from destination: social feed → `1080x1080`; TikTok/Reels/Shorts → `1080x1920`; YouTube/website/desktop → `1920x1080`. State the derivation. | -| `length` | Target duration | Let the workflow recommend a range supported by the material; include the reason. | -| `language` | Narration and caption language | Use the user's language and state it. | -| `audience` | Who will watch | Infer when clear. Ask only when a different answer changes the story or terminology. | -| `message` | The one thing the video must communicate | Derive and echo one sentence. Do not storyboard until this is clear. | -| `angle` | Route-specific story shape | Recommend one route-defined option with a reason. | -| `narration` | `yes`, `minimal`, or `no`, plus route-specific modes | Follow the selected route. | +| Field | Meaning | Policy | +| ------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `flow` | Who drives execution | Ask at the end of intent capture when the route supports both flows. An autonomous signal answers it. | +| `storyboard` | Whether to review the plan and layout sketches before building | Ask before `flow` when the route supports a storyboard. A storyboard request answers it. | +| `destination` | Where the video will play | Infer from the request. Ask only when unknown and the answer changes aspect, type scale, or composition. | +| `aspect` | Canvas size | Derive from destination: social feed → `1080x1080`; TikTok/Reels/Shorts → `1080x1920`; YouTube/website/desktop → `1920x1080`. State the derivation. | +| `length` | Target duration | Let the workflow recommend a range supported by the material; include the reason. | +| `language` | Narration and caption language | Use the user's language and state it. | +| `audience` | Who will watch | Infer when clear. Ask only when a different answer changes the story or terminology. | +| `message` | The one thing the video must communicate | Derive and echo one sentence. Do not storyboard until this is clear. | +| `angle` | Route-specific story shape | Recommend one route-defined option with a reason. | +| `narration` | `yes`, `minimal`, or `no`, plus route-specific modes | Follow the selected route. | ### Remembered defaults diff --git a/skills/hyperframes/references/brief-format.md b/skills/hyperframes/references/brief-format.md index 6195edf37e..04d0972617 100644 --- a/skills/hyperframes/references/brief-format.md +++ b/skills/hyperframes/references/brief-format.md @@ -8,13 +8,13 @@ Defines the **intent document** — the file a confirmed brief becomes. The ques YAML block at the top: one key per deterministic field — the run's shape first, then the registry fields (`brief-contract.md` § 2) used by the route. Store canonical normalized values. Some values come directly from the user; others, such as `workflow`, `aspect`, and `language`, are routed, derived, or normalized and must use the vocabulary defined by the contract. Preserve the user's own wording in the body when it matters. -| Key | Meaning | Example | -| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -| `workflow` | the executing workflow (companion runs record `general-video`) | `faceless-explainer` | -| `flow` | `automation` — the matched workflow's pipeline · `companion` — co-creation in `/general-video` | `automation` | -| `storyboard` | `yes` — plan, sketches, and build reviewed on the live board (`review-loop.md`) · `no` — one shot from the confirmed brief | `yes` | -| `message` | the ONE thing the video must communicate | `"Ship it in an afternoon"` | -| `destination` / `aspect` / `language` / `audience` / `length` / `angle` … | the registry fields this route confirmed | — | +| Key | Meaning | Example | +| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------- | +| `workflow` | the executing workflow (companion runs record `general-video`) | `faceless-explainer` | +| `flow` | `automation` — the matched workflow's pipeline · `companion` — co-creation in `/general-video` | `automation` | +| `storyboard` | `yes` — plan and sketches reviewed before the build (`review-loop.md`) · `no` — one shot from the confirmed brief | `yes` | +| `message` | the ONE thing the video must communicate | `"Ship it in an afternoon"` | +| `destination` / `aspect` / `language` / `audience` / `length` / `angle` … | the registry fields this route confirmed | — | **Which keys are memory.** Only the preference-backed subset — `destination`, `aspect`, `language`, `flow`, `storyboard`, `voice`, `style_preset` — is recorded with `media-use` → `scripts/prefs.mjs record` (the store rejects any other key). `style_preset` is stored per workflow: record it with `--workflow ` (the store refuses it bare — a look confirmed for one genre is not a default for the others). `message`, `audience`, `length`, `angle` live in the frontmatter only: they describe this video, not the user. @@ -35,7 +35,7 @@ Body prose is **project-local** — nothing in it enters cross-project memory. ( - **It is the no-repeat token.** A workflow that finds `BRIEF.md` reads it and asks no brief question. Its `workflow:` names the executor — a workflow that finds another's name there is in the wrong room: load that skill and hand over, don't re-route through the intent layer. No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → a pre-BRIEF project: resume from the storyboard's frontmatter and the recorded preferences, optionally backfilling `BRIEF.md` from what they already say — never re-interrogate a half-built project. - **It stays the run's truth.** A mid-run decision updates it as it happens: an explicit change to a frontmatter field ("make it 9:16 after all") rewrites the field and re-records the preference — a changed mind is a confirmed answer; an accepted capability, adopted material, or bespoke ask lands as one line in the matching body section. Resume reads this file, so write-back is what makes a dead session resumable — a decision that lives only in chat is a decision resume never sees. - **Execution mode derives; the storyboard's copy wins on resume.** `flow` × `storyboard` derive collaborative/autonomous checkpoint behavior (`brief-contract.md` § 1). Persist the derived mode in `STORYBOARD.md` frontmatter when that file exists. A mid-run mode-only switch updates `STORYBOARD.md`, not the already-confirmed `flow` or `storyboard`; an explicit change to either run-shape field still updates `BRIEF.md`. -- **`message` / `audience` live here first.** `STORYBOARD.md` frontmatter keeps its copies — the board and the parser read them — but when the two disagree, `BRIEF.md` holds what the user confirmed. +- **`message` / `audience` live here first.** `STORYBOARD.md` frontmatter keeps its copies — the parser and scripts read them — but when the two disagree, `BRIEF.md` holds what the user confirmed. - **Recipes carry its skeleton.** Freezing a recipe (`review-loop.md` § 4) captures `brief-skeleton.md` — frontmatter structure kept, run-shape and content values blanked — so the next run starts pre-filled yet still confirms its own two run-shape answers. ## Example diff --git a/skills/hyperframes/references/frame-worker-core.md b/skills/hyperframes/references/frame-worker-core.md index 6b1da927f2..7921bfe214 100644 --- a/skills/hyperframes/references/frame-worker-core.md +++ b/skills/hyperframes/references/frame-worker-core.md @@ -28,7 +28,7 @@ You build the frame composition file(s) assigned in your dispatch and nothing el ## When a confirmed sketch exists -In collaborative runs the orchestrator wireframes the board first, so your target file may already exist as the frame's **user-confirmed wireframe** — your dispatch says whether it does (a file found on a retry is your own prior output, not a sketch). Read it first and **keep its composition**: the placement, hierarchy, and copy were approved — don't move or drop them. Everything else is yours to finish: the full `frame.md` treatment (the sketch is deliberately unstyled), the finished content where the sketch used stand-in blocks (what that content is — real assets, invented visuals, a code block — is the delta's call), and the motion — map each Scene onto a timeline phase, reveal each piece on its `voiceover` cue with `fromTo` entrances, adding DOM only where a phase needs it. The frame's landed state must still read as the approved wireframe, fully dressed. +In collaborative runs the orchestrator sketches every frame first as a cell of `storyboard.html` (`id="frame-NN"`), so your frame may have a **user-confirmed wireframe** there — your dispatch says whether it does (a target file found on a retry is your own prior output, not a sketch). Read that cell first and **keep its composition**: the placement, hierarchy, and copy were approved — don't move or drop them. Everything else is yours to finish: the full `frame.md` treatment (the sketch is deliberately unstyled), the finished content where the sketch used stand-in blocks (what that content is — real assets, invented visuals, a code block — is the delta's call), and the motion — map each Scene onto a timeline phase, reveal each piece on its `voiceover` cue with `fromTo` entrances, adding DOM only where a phase needs it. The frame's landed state must still read as the approved wireframe, fully dressed. ## You do NOT decide diff --git a/skills/hyperframes/references/intent-interview.md b/skills/hyperframes/references/intent-interview.md index 7b9a2743be..41a7edcd7e 100644 --- a/skills/hyperframes/references/intent-interview.md +++ b/skills/hyperframes/references/intent-interview.md @@ -24,7 +24,7 @@ A GitHub PR URL is not a website source. A named or adopted recipe already carri - **Remembered defaults.** Let `` be the installed `/media-use` skill directory. For an existing project, `` is its root. Before scaffolding, use a deliberately nonexistent probe path with no `.media`, such as `/tmp/hyperframes-intent-memory-`; never use the current workspace. Run `node /scripts/prefs.mjs get --hyperframes --json`. Make each remembered value the recommended option and name its source. The pre-project probe sees only the personal tier; do not claim project provenance. - **Recipes.** Run `node /scripts/recipe.mjs list --hyperframes --json`. If the user names a recipe, says "like last time," or a recipe matches the probable route, ask whether to adopt it before other brief questions — and make the offer earn the yes: say why it matches and what adopting saves ("this matches your launch-promo recipe — adopting fills destination, aspect, language, and the design spec; you'd confirm the message and the two run-shape questions"). When several match, list them and include "none." An adopted recipe locks the fields it contains; ask only its missing fields and the run-shape questions. It does not remove review or render approval gates. -**2 — Triage the input.** What is the video about — a website (sold or shown), a PR, a topic, a music track, existing footage? And is the request **formed** — the message, the material, and the occasion readable from what the user gave — or **unformed**, a subject with no take on it? Source material doesn't settle this by itself: a site, document, or PR carries its own thesis, but five tellings of that thesis are five different videos — a request whose only shape comes from its source ("make a video about this URL") is formed about the facts and unformed about the telling, and enters the round to pitch the telling. A formed request runs the layer exactly as it always has; nothing below is added for it. An unformed one goes through the pitch round after routing (step 4) and earns one question here, before anything is generated: what is the user already picturing? Their answer seeds the round (`pitch-round.md`). A user who says they don't know video at all gets that reference's decision map instead of a question sequence. For a genuinely exploratory request ("we need a video but I'm not sure what kind"), don't interrogate — establish the subject and what exists to show, one question at a time, then close by **recommending** a route plus how the run will review: a text storyboard first, on a live board, with optional wireframe sketches before the full build (`review-loop.md`). The user hears the process before any workflow starts. +**2 — Triage the input.** What is the video about — a website (sold or shown), a PR, a topic, a music track, existing footage? And is the request **formed** — the message, the material, and the occasion readable from what the user gave — or **unformed**, a subject with no take on it? Source material doesn't settle this by itself: a site, document, or PR carries its own thesis, but five tellings of that thesis are five different videos — a request whose only shape comes from its source ("make a video about this URL") is formed about the facts and unformed about the telling, and enters the round to pitch the telling. A formed request runs the layer exactly as it always has; nothing below is added for it. An unformed one goes through the pitch round after routing (step 4) and earns one question here, before anything is generated: what is the user already picturing? Their answer seeds the round (`pitch-round.md`). A user who says they don't know video at all gets that reference's decision map instead of a question sequence. For a genuinely exploratory request ("we need a video but I'm not sure what kind"), don't interrogate — establish the subject and what exists to show, one question at a time, then close by **recommending** a route plus how the run will review: a plan in chat first, with optional wireframe sketches on a `storyboard.html` sheet before the full build (`review-loop.md`). The user hears the process before any workflow starts. **3 — Pick the route** (the route table and ambiguity rules in the SKILL.md), then read `routes/.md`. Its Interview section lists the must-have questions to ask now, the **deferred asks** to announce, whether the two run-shape questions apply, and which fields the pitch round may answer. @@ -34,10 +34,10 @@ A GitHub PR URL is not a website source. A named or adopted recipe already carri **6 — The two run-shape questions** — where the route's entry applies them, asked after the must-haves, each on its own: -- **(a) Storyboard?** Review the plan, wireframe sketches, and the finished piece pass by pass on a live board (`review-loop.md`) — recommended for anything beyond a couple of scenes — or skip the board and get one finished video from the confirmed brief. +- **(a) Storyboard?** Review the plan in chat, wireframe sketches on a `storyboard.html` sheet, and the finished piece pass by pass (`review-loop.md`) — recommended for anything beyond a couple of scenes — or skip the review and get one finished video from the confirmed brief. - **(b) Automation or companion?** **Automation** — the matched workflow's pipeline executes the brief end to end. **Companion** — build it together in `/general-video` with every HyperFrames capability on the table; the route's answers still describe the video, general-video executes them. -These two are **orthogonal — never merge them into one menu.** All four `flow` × `storyboard` combinations are valid user choices (a companion run reviews on the live board too when `storyboard: yes`); a flattened three-option list ("storyboard review / one shot / companion") silently makes companion-with-storyboard unselectable. When a diagram or source material summarizes the outcomes as three branches, that is the derived behavior (`brief-contract.md` § 1), not the question shape. In a form-style question UI, keep (a) and (b) as two separate selects. +These two are **orthogonal — never merge them into one menu.** All four `flow` × `storyboard` combinations are valid user choices (a companion run runs the same review passes when `storyboard: yes`); a flattened three-option list ("storyboard review / one shot / companion") silently makes companion-with-storyboard unselectable. When a diagram or source material summarizes the outcomes as three branches, that is the derived behavior (`brief-contract.md` § 1), not the question shape. In a form-style question UI, keep (a) and (b) as two separate selects. Signals replace questions, never add them: an ongoing "just build it" / "surprise me" / "don't ask" locks `flow: automation, storyboard: no`, and every unanswered field becomes a decision with a receipt in the heads-up. A storyboard request, however phrased, locks `storyboard: yes`. Remembered `flow` / `storyboard` values reorder the recommendations — they never make either question disappear. The run's collaborative/autonomous execution mode derives from these two answers — the old first question is never asked; the canonical mapping is `brief-contract.md` § 1. @@ -62,10 +62,10 @@ Then enter the workflow (`flow: companion` → `/general-video`; otherwise the m The interview's deliverable. Every later "what did the route require?" re-reads this ~1KB file, never this document. One key per confirmed field, canonical normalized values (full shape and body sections: `brief-format.md`): -| Key | Meaning | Example | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------- | -| `workflow` | the executing workflow (companion runs record `general-video`) | `faceless-explainer` | -| `flow` | `automation` — the matched workflow's pipeline · `companion` — co-creation in `/general-video` | `automation` | -| `storyboard` | `yes` — plan, sketches, and build reviewed on the live board · `no` — one shot from the confirmed brief | `yes` | -| `message` | the ONE thing the video must communicate | `"Ship it in an afternoon"` | -| `destination` / `aspect` / `language` / `audience` / `length` / `angle` … | the registry fields this route confirmed | — | +| Key | Meaning | Example | +| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------- | +| `workflow` | the executing workflow (companion runs record `general-video`) | `faceless-explainer` | +| `flow` | `automation` — the matched workflow's pipeline · `companion` — co-creation in `/general-video` | `automation` | +| `storyboard` | `yes` — plan and sketches reviewed before the build · `no` — one shot from the confirmed brief | `yes` | +| `message` | the ONE thing the video must communicate | `"Ship it in an afternoon"` | +| `destination` / `aspect` / `language` / `audience` / `length` / `angle` … | the registry fields this route confirmed | — | diff --git a/skills/hyperframes/references/production-loop.md b/skills/hyperframes/references/production-loop.md index 1a3930c23e..28a5c6e254 100644 --- a/skills/hyperframes/references/production-loop.md +++ b/skills/hyperframes/references/production-loop.md @@ -4,17 +4,17 @@ The stages between a plan the user has agreed to and a video in their hands, wri The shipped narrative workflows implement these stages with their own scripts; a freeform build follows this file directly, borrowing tools where the capability menu says they live (`hyperframes/references/capability-menu.md`). -| Stage | Needs | Produces | Where the capability lives | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| **Blocks & assets** | the approved plan | registry blocks installed **once, before any parallel work** (parallel workers race the registry); user assets staged; logos / images / grades resolved | `npx hyperframes add ` per block the plan names; staging, adoption, and `resolve` via the menu's media rows | -| **Audio** | narration text (when narrated); the storyboard's `music:` mood | voice files + **word timings** + BGM + SFX → `audio_meta.json`; **when BGM plays under a voice, the bed is carved** (`hyperframes-audio/scripts/carve.mjs`) before Verify — a duck alone is not a finished mix | the one engine — `media-use/audio/scripts/audio.mjs`, run in the background; `wait-bgm.mjs` before render when BGM generates | -| **Frames** | design spec + the plan (+ a confirmed sketch when one exists — dress that layout, never redraw it: `review-loop.md` § 3) | each scene at `compositions/frames/NN-*.html`, marked `animated` in the storyboard as it lands | `frame.md` + `hyperframes-animation` blueprints / rules (+ the genre lens, menu § Genre lenses); parallel dispatch per `subagent-dispatch.md` | -| **Duration sync** | word timings + frames | scene durations trued to real voice length — real duration wins, silent scenes keep estimates, synced values are never hand-edited | a mechanical rule; the narrative workflows' audio scripts apply it, a freeform build applies it by hand | -| **Assembly** | frames | the index composition — scenes as sub-compositions on tracks | `sub-compositions.md` + `tracks-and-clips.md`; borrowable `assemble-index.mjs` (menu) | -| **Transitions** | the assembled index | scene handoffs injected | `hyperframes-animation/transitions/overview.md` → `catalog.md`; borrowable `transitions.mjs` (menu) | -| **Captions** | word timings + the index | the caption track | borrowable `captions.mjs` (menu); no script to time against → `media-use` `scripts/transcribe.mjs` first | -| **Verify** | the index (+ captions / transitions when present) | `npx hyperframes lint` and `npx hyperframes check` **passing**; a contact-sheet glance (`snapshot --at `) | `hyperframes-cli` | -| **Deliver** | verify passing | the final-look pause → on approval `render` → optionally `publish` (a stable hosted link, private by default) → the recipe offer | final approval and recipe offer: `review-loop.md` § 4; render / publish: `hyperframes-cli` | +| Stage | Needs | Produces | Where the capability lives | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| **Blocks & assets** | the approved plan | registry blocks installed **once, before any parallel work** (parallel workers race the registry); user assets staged; logos / images / grades resolved | `npx hyperframes add ` per block the plan names; staging, adoption, and `resolve` via the menu's media rows | +| **Audio** | narration text (when narrated); the storyboard's `music:` mood | voice files + **word timings** + BGM + SFX → `audio_meta.json`; **when BGM plays under a voice, the bed is carved** (`hyperframes-audio/scripts/carve.mjs`) before Verify — a duck alone is not a finished mix | the one engine — `media-use/audio/scripts/audio.mjs`, run in the background; `wait-bgm.mjs` before render when BGM generates | +| **Frames** | design spec + the plan (+ a confirmed sketch cell in `storyboard.html` when one exists — dress that layout, never redraw it: `review-loop.md` § 3) | each scene at `compositions/frames/NN-*.html`, marked `animated` in the storyboard as it lands | `frame.md` + `hyperframes-animation` blueprints / rules (+ the genre lens, menu § Genre lenses); parallel dispatch per `subagent-dispatch.md` | +| **Duration sync** | word timings + frames | scene durations trued to real voice length — real duration wins, silent scenes keep estimates, synced values are never hand-edited | a mechanical rule; the narrative workflows' audio scripts apply it, a freeform build applies it by hand | +| **Assembly** | frames | the index composition — scenes as sub-compositions on tracks | `sub-compositions.md` + `tracks-and-clips.md`; borrowable `assemble-index.mjs` (menu) | +| **Transitions** | the assembled index | scene handoffs injected | `hyperframes-animation/transitions/overview.md` → `catalog.md`; borrowable `transitions.mjs` (menu) | +| **Captions** | word timings + the index | the caption track | borrowable `captions.mjs` (menu); no script to time against → `media-use` `scripts/transcribe.mjs` first | +| **Verify** | the index (+ captions / transitions when present) | `npx hyperframes lint` and `npx hyperframes check` **passing**; a contact-sheet glance (`snapshot --at `) | `hyperframes-cli` | +| **Deliver** | verify passing | the final-look pause → on approval `render` → optionally `publish` (a stable hosted link, private by default) → the recipe offer | final approval and recipe offer: `review-loop.md` § 4; render / publish: `hyperframes-cli` | The Frames stage follows the plan's citations: a scene planned on a blueprint or on named rules is built by reading that recipe's body (`hyperframes-animation/blueprints/.md`, `rules/.md`) before its motion is written — names come from the indexes, never invented, and a scene the plan left uncited gets its citation at build time, not improvised motion. diff --git a/skills/hyperframes/references/review-loop.md b/skills/hyperframes/references/review-loop.md index 5ba70fd89c..f7cce22a4f 100644 --- a/skills/hyperframes/references/review-loop.md +++ b/skills/hyperframes/references/review-loop.md @@ -1,41 +1,37 @@ # The review loop — plan, sketch, build -How a `storyboard: yes` run earns fidelity one pass at a time: the plan is reviewed as text on a live board, the layouts as wireframe sketches, and the finished piece as the assembled video. Collaborative mode waits at each checkpoint. Autonomous mode posts the same checkpoint summaries and continues, keeping exactly one question before render. +How a `storyboard: yes` run earns fidelity one pass at a time: the plan is reviewed as text in chat, the layouts as a sketched `storyboard.html` the user opens in a browser, and the finished piece as the assembled video. Collaborative mode waits at each checkpoint. Autonomous mode posts the same checkpoint summaries and continues, keeping exactly one question before render. -This is the shared process for any workflow that plans on a storyboard. The contracts it leans on live next door: interaction mode, gate types, and the comments channel in `brief-contract.md`; the `STORYBOARD.md` format, the `outline → built → animated` statuses, and the comments sidecar in `storyboard-format.md`. A workflow's SKILL.md says **when** its steps hit each pass and supplies its **sketch stand-ins** (what the plain blocks represent); how the loop runs is defined here, once. The stage mechanics between the passes — audio, frames, assembly, transitions, captions, verify — live in `production-loop.md`; this file owns only the user-facing pauses. +This is the shared process for any workflow that plans on a storyboard. The contracts it leans on live next door: interaction mode and gate types in `brief-contract.md`; the `STORYBOARD.md` format and the `outline → built → animated` statuses in `storyboard-format.md`. How to make the storyboard itself, and the page it is reviewed on, is `hyperframes-creative/references/storyboard-recipe.md`. A workflow's SKILL.md says **when** its steps hit each pass and supplies its **sketch stand-ins** (what the plain blocks represent); how the loop runs is defined here, once. The stage mechanics between the passes — audio, frames, assembly, transitions, captions, verify — live in `production-loop.md`; this file owns only the user-facing pauses. ## § 1 — The plan, in chat -Present the plan in chat and keep it in `STORYBOARD.md`, which is the source of truth as work lands. +Write the decisions and beat list into `STORYBOARD.md` following the recipe, and present the plan in chat as a proposal (shape: `hyperframes-creative/references/story-spine.md` § 3): open by echoing **"This video tells [audience] that [message]"**, then the frame table — one row per frame: frame · beat (type, duration) · on screen · why (its `narrativeRole`, traced to the message). Feedback arrives as a reply here, one revision loop. -Present the plan as a proposal (shape: `hyperframes-creative/references/story-spine.md` § 3): open by echoing **"This video tells [audience] that [message]"**, then the frame table — one row per frame: frame · beat (type, duration) · on screen · why (its `narrativeRole`, traced to the message). Feedback arrives as a reply here, one revision loop. +In the same message ask two things: **(a)** approve or request changes, and **(b)** **sketches first** (recommended — a quick look at the layouts right after this approval) or skip sketches and build in one go. Iterate until approved: revise exactly the frames the reply names and re-present. -In the same message ask two things: **(a)** approve or request changes, and **(b)** **sketches first** (recommended — a quick wireframe look check right after this approval) or skip sketches and build in one go. Iterate until approved — feedback arrives in chat or as the comments file (`brief-contract.md` § 1, the comments channel): revise exactly the frames it names, clear the file, re-present. - -This is a **checkpoint gate** (`brief-contract.md` § 1). A run that starts autonomous normally has `storyboard: no` and does not enter this loop. If mode switches to autonomous after a board exists, keep updating the board, post the same summary as a heads-up, and continue without waiting; the one kept question comes at § 4. +This is a **checkpoint gate** (`brief-contract.md` § 1). A run that starts autonomous normally has `storyboard: no` and does not enter this loop. If mode switches to autonomous mid-run, keep `STORYBOARD.md` current, post the same summary as a heads-up, and continue without waiting; the one kept question comes at § 4. ## § 2 — The sketch pass (collaborative, unless skipped) -The moment the plan is approved, wireframe every frame yourself — no sub-agents, no waiting on other steps (sketches don't use timings), straight from the approved frame table. +The moment the plan is approved, sketch every frame yourself — no sub-agents, no waiting on other steps (sketches don't use timings), straight from the approved frame table. A sketch is a **wireframe with the real words, not a styled frame**: the frame's layout at its key moment — the actual headline / stat / label text placed where it will live, plain blocks for panels, charts, diagrams, and media (the workflow says what its blocks stand in for), `frame.md`'s background and ink plus one accent on the focal, nothing else. No decoration, no full brand treatment, **no motion** — all of that arrives with the build pass. -Keep each sketch a real composition file at `compositions/frames/NN-*.html` (template wrapper, `data-composition-id`, `#root` styling, one paused **empty** timeline registered at `window.__timelines[""]`) so the Studio poster renders — and the poster is the only picture this pass needs: **run no CLI here** — no `snapshot`, no `lint` / `check`, no rendering. A sketch is a few dozen lines of HTML; the whole board lands in minutes. - -Mark each frame `built` as its sketch lands — the user's open board fills in blue by itself. When every frame is `built`, pause and ask one thing: does the board look right, or which frames change? This is a **checkpoint gate**; the user reviews in Studio (open since § 1 — restart and re-hand the same URL if the server died), and feedback arrives in chat or as the comments file — check the file first when the reply arrives: revise **only the sketches named**, re-present, and loop until the layout is confirmed. Only then does the workflow's visual design get written onto the confirmed layouts. +Draw the sketches as the cells of `storyboard.html` (`storyboard-recipe.md` § 3) and hand the user the file path to open in a browser. Mark each frame `built` in `STORYBOARD.md` as its sketch lands. Run no CLI here — no `snapshot`, no `lint` / `check`, no rendering. When every frame is `built`, pause and ask one thing: does the sheet look right, or which frames change? This is a **checkpoint gate**; feedback arrives in chat: revise **only the sketches named**, bump the sheet's version, re-present, and loop until the layout is confirmed. Only then does the workflow's visual design get written onto the confirmed layouts. -A confirmed board is also a valid place to **stop**. When the user asked for a storyboard rather than a finished video — a plan to pitch, review, or hand off — the sketched board is the deliverable: confirm it, hand the board URL, and go no further unless asked to build. +A confirmed sheet is also a valid place to **stop**. When the user asked for a storyboard rather than a finished video — a plan to pitch, review, or hand off — `storyboard.html` is the deliverable: confirm it, hand over the path, and go no further unless asked to build. In autonomous mode, or when the user chose to skip sketches at § 1, skip this pass — frames go straight from `outline` to `animated` in the build. ## § 3 — Building on confirmed layouts -However the workflow builds — sub-agent workers per frame, or inline scene by scene — a confirmed sketch's **composition is settled**: placement, hierarchy, and copy were approved on the board, so building means dressing that layout (full design treatment, real assets, motion), never redrawing it. Workflows that dispatch workers put "this frame has a **confirmed sketch** on disk" in the worker's context and carry the keep-the-layout rule in their worker prompt; a landed frame must still read as the approved wireframe, fully dressed. +However the workflow builds — sub-agent workers per frame, or inline scene by scene — a confirmed sketch's **composition is settled**: placement, hierarchy, and copy were approved on the sheet, so building means dressing that layout (full design treatment, real assets, motion), never redrawing it. Workflows that dispatch workers put "this frame has a **confirmed sketch** at `storyboard.html#frame-NN`" in the worker's context and carry the keep-the-layout rule in their worker prompt; a landed frame must still read as the approved wireframe, fully dressed. -Mark each frame `animated` as it lands. The build gate carries the loop's condition: in collaborative mode, the sketch board was confirmed at § 2. +Mark each frame `animated` as it lands. The build gate carries the loop's condition: in collaborative mode, the sketch sheet was confirmed at § 2. ## § 4 — The final look -After the workflow's checks pass, use the **final composition preview**. In collaborative mode Studio may already be serving from § 1; hand the timeline URL and ask one thing: render now, or what changes? In autonomous mode this is the one question the mode keeps: ask “preview first, or render?” Open the final preview on yes; render on an explicit render answer. Render only on approval. +After the workflow's checks pass, use the **final composition preview**. In collaborative mode open the Studio preview, hand the timeline URL and ask one thing: render now, or what changes? In autonomous mode this is the one question the mode keeps: ask “preview first, or render?” Open the final preview on yes; render on an explicit render answer. Render only on approval. **After approval, offer the recipe — once.** An approved run is a proven bundle. At delivery, offer to freeze it: `media-use` → `scripts/recipe.mjs freeze --name ` (the workflow comes from BRIEF.md; pass `--workflow` only in a project without one) keeps the design spec, the storyboard skeleton (structure kept, content blanked), the brief skeleton, and the confirmed brief values, and the next run of this type starts from it (the intent layer checks for a matching recipe before its first question). When the freeze lands, teach the recall in the confirmation — "Saved as **** (v). Next time say _make another _, or just _like last time_." — the name is something the system reminds the user of, never something they must remember. In autonomous mode don't ask — name the freeze command in the delivery note instead. diff --git a/skills/hyperframes/references/routes/motion-graphics.md b/skills/hyperframes/references/routes/motion-graphics.md index 41e3216cd7..049483a3cc 100644 --- a/skills/hyperframes/references/routes/motion-graphics.md +++ b/skills/hyperframes/references/routes/motion-graphics.md @@ -7,5 +7,5 @@ ## Interview - Autonomous by design: at most **one** clarifying question, owned by its director step, in the flow. No must-haves here beyond confirming the input; route directly. -- **Run-shape:** neither — the piece is seconds long; a board and a companion session have nothing to add. +- **Run-shape:** neither — the piece is seconds long; a storyboard and a companion session have nothing to add. - **Front-door capability offer:** skip it. The director's one-question limit is authoritative. diff --git a/skills/hyperframes/references/script-format.md b/skills/hyperframes/references/script-format.md index 43d5daf8ce..94bfe04483 100644 --- a/skills/hyperframes/references/script-format.md +++ b/skills/hyperframes/references/script-format.md @@ -4,7 +4,7 @@ The **locked narration** for a project: the final spoken lines + voice + deliver This file defines the SCRIPT.md **shape** only. Synthesizing the spoken lines into audio is a capability owned by `media-use` → `../../media-use/audio/references/tts.md`. -Free-form markdown — there is no strict parser; the Studio renders it read-only beside the Storyboard board, and the TTS step extracts the indented spoken lines. +Free-form markdown — there is no strict parser; the TTS step extracts the indented spoken lines. ## Shape @@ -14,7 +14,7 @@ A header block, then one section per spoken line. | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Header | `**Voice:**` (provider + voice), `**Voice settings:**` (e.g. stability / similarity / style), `**Voice direction:**` (overall delivery) | | `## Line N —