wizz-method 2.10.0 → 2.10.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "description": "Wizz Method: método de agência orientado por IA em PT-BR",
   "keywords": [
     "agile",

package/skills-registry.yaml

@@ -203,7 +203,11 @@ areas:
         # Neutraliza remotion-to-hyperframes: o bundle instala uma skill de
         # migração Remotion→HyperFrames proibida pela regra do pipeline
         # (_shared/video-pipeline.md: HyperFrames desenha, Remotion monta).
-        install: 'd="$(mktemp -d)" && git clone https://github.com/heygen-com/hyperframes.git "$d" && git -C "$d" checkout 59a69a145bfbd0f10dee72246b68ee5d9bd71063 && npx skills add "$d" -g -y --copy && printf "%s\\n" 59a69a145bfbd0f10dee72246b68ee5d9bd71063 > "$HOME/.claude/skills/hyperframes/.wizz-pin" && rm -rf "$d" && rm -rf "$HOME/.claude/skills/remotion-to-hyperframes"'
+        # O perl troca a description da skill de entrada: no upstream ela se
+        # declara "o padrão pra renderizar vídeo" e, fora de um projeto Wizz
+        # (sem router), puxa a montagem com áudio pro HyperFrames. O regex casa
+        # o bloco `description: >` do SHA fixado; ao trocar o pin, conferir.
+        install: 'd="$(mktemp -d)" && git clone https://github.com/heygen-com/hyperframes.git "$d" && git -C "$d" checkout 59a69a145bfbd0f10dee72246b68ee5d9bd71063 && npx skills add "$d" -g -y --copy && perl -0pi -e ''s{\A---\nname: hyperframes\ndescription: >\n(?:  [^\n]*\n)+}{---\nname: hyperframes\ndescription: >\n  Wizz Method pipeline: HyperFrames DRAWS, Remotion ASSEMBLES. Use to draw a silent video screen in HTML, one scene per composition (app mockup, animated chart, title card, loop, transparent overlay), and to reach the HyperFrames workflows (embedded-captions with matte on a recorded talking head, website or PR or product to video, slideshow). A film with narration, SFX, synced captions or several scenes is assembled in Remotion (skill wizz-remotion-best-practices), which imports these renders as silent clips; never place audio here and never port a Remotion composition to HyperFrames.\n}'' "$HOME/.claude/skills/hyperframes/SKILL.md" && grep -q "HyperFrames DRAWS" "$HOME/.claude/skills/hyperframes/SKILL.md" && printf "%s\\n" 59a69a145bfbd0f10dee72246b68ee5d9bd71063 > "$HOME/.claude/skills/hyperframes/.wizz-pin" && rm -rf "$d" && rm -rf "$HOME/.claude/skills/remotion-to-hyperframes"'
       - id: claude-video
         when: "Analisar/entender vídeo EXISTENTE: baixa, extrai frames e transcreve para resumir, achar momentos ou diagnosticar footage. NÃO cria vídeo. Precisa ffmpeg + yt-dlp (+ Groq/OpenAI p/ transcrição sem legenda)."
         rel:

package/src/modules/wizz/_shared/video-pipeline.md

@@ -20,6 +20,7 @@
 | Draw/animate ONE screen or scene (app mockup, chart, title) — silent visual | `hyperframes` (skills + CLI) |
 | Short video WITHOUT synced audio (loop, overlay, silent motion graphic) | `hyperframes` |
 | Assemble the film: sequence of scenes + narration + SFX + captions + frame timing | **Remotion** (skill `wizz-remotion-best-practices`) |
+| Captions passing behind the person on a recorded talking head (matte) | embedded-captions (HyperFrames bundle), then the clip goes to Remotion |
 | Word-by-word timestamps of the TTS narration (sync captions/cuts/animation) | `ctc-align` |
 | Narration / voice / TTS / voice cloning | `voicebox` |
 | **Source B-roll / inserts: find real footage of what the script names** | `get-brolls` (darwin) |
@@ -43,6 +44,7 @@
    self-approves.**
 6. **Assembly** — **Remotion** joins the exported scenes and the approved B-roll,
    adds audio, SFX, and captions at the ctc-align timestamps, with frame precision.
+   Scenes follow the handoff contract below.
 7. **Fine cut** (if there's recorded footage) — `buttercut`.
 8. **Publishing/distribution** — social/ads area.
 
@@ -52,6 +54,31 @@ narration cites. A script that says "Nvidia's CEO announced" wants the actual
 footage, not a drawn card with his name on it. Reach for `hyperframes` when
 there is nothing real to show; reach for `get-brolls` when there is.
 
+## Handoff contract (HyperFrames → Remotion)
+
+The two tools work together only if the scenes arrive in the shape Remotion
+expects. Decide the Remotion composition first, then render every scene to it.
+
+| Item | Rule |
+|---|---|
+| fps and size | Set once in the Remotion composition (e.g. 30 fps, 1080×1920 for Reels) and pass the same `--fps` and dimensions to every `npx hyperframes render`. Never let Remotion resample a scene. |
+| Duration | Each scene is rendered at the length of its `<Sequence>`, taken from the ctc-align timestamps. A mismatch is fixed with `trimBefore`/`trimAfter` in Remotion, never by stretching the clip. |
+| Opaque scene | `npx hyperframes render` → MP4, **no audio track**. |
+| Overlay (lower third, callout, title over footage) | `npx hyperframes render --format webm` (or `mov`) → transparent file, no audio. |
+| Where it goes | `public/scenes/NN-slug.mp4` and `public/overlays/NN-slug.webm` in the Remotion project; `NN` is the beat order in the script, `slug` names the beat. |
+| How it comes in | `<Video src={staticFile("scenes/NN-slug.mp4")} muted />` inside a `<Sequence>` (see `rules/videos.md` and `rules/transparent-videos.md` in `wizz-remotion-best-practices`). |
+| Audio | Only Remotion places narration, SFX and music. A HyperFrames render with sound is a contract break: re-render it silent. |
+
+### Captions: which tool
+
+- **Narrated video (TTS)** → captions in Remotion at the `ctc-align` timestamps.
+  This is the default.
+- **Recorded talking head with the text passing behind the person** (matte,
+  36 styles of the embedded-captions catalog) → embedded-captions, run on the
+  recorded clip itself. Its output enters Remotion as a finished clip that keeps
+  the original speech track; do not add the narration or a second caption layer
+  over it.
+
 ## Anti-patterns (don't do this)
 
 - Don't use HyperFrames to position audio, SFX, or synced captions.

package/src/modules/wizz/agents/wizz-designer/SKILL.md

@@ -25,7 +25,7 @@ You are Wizz's Designer. It creates high-level interfaces and landing pages, sho
 
 ## How I work (bridge to global skills)
 
-> **Single source (registry) — ALWAYS read before the examples below:** the real list for your area (`designer`) lives in `skills-registry.yaml`. Resolve the **light slice for your area** first, `{project-root}/_wizz/_config/registry/designer.yaml` (already comes as the full `areas.designer` block — skills/mcps/clis/references); if it's missing (old install), fall back to the monolith in order `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` and find the `areas.designer` block there. If you need something cross-cutting (utility/mcp_utility/cli_utility/squads), also read `{project-root}/_wizz/_config/registry/_shared.yaml`. Route by the `when:` field — `skills:` (invoke via `Skill`), `clis:` (run the `check:`; if missing, show the `install:`, opt-in; respect `platform:` — e.g. `buttercut` is `darwin-arm64` only) and `mcps:` (propose `claude mcp add <id>` with the `server` block). **Follow `rel:` before answering.** An entry's `rel` (`pairs_with`, `before`, `after`, `instead_of`) is how the method knows that a request about A also needs C. Every edge is reciprocal by construction — the schema validator rejects one-way edges — so the relation shows up whichever side the user enters from. Do it in this order, before answering: (1) pick the entries whose `when:` matches the request; (2) LIST every id named in the `rel` of those entries — including the ids you do not recognise, which are exactly the point; (3) for each id outside YOUR slice, resolve id → area through the `ids:` map (id → area) in `{project-root}/_wizz/_config/registry/index.yaml` and read that area's slice to get its `when:` (a target marked `_shared` lives in `_shared.yaml`); (4) either bring it in or discard it with a stated reason. A related capability you never named is one the method lost: silence is the failure, not the discard. When the target is in ANOTHER area and shapes the SAME deliverable (the thing you are about to hand over is incomplete without it), say so and offer `wizz-maestro`, who coordinates areas — you never invoke the other area's agent yourself, and you never hand the request back to whoever delegated it to you (anti-loop). Tell the user what the related capability is instead of delivering only the half they asked for, and when the relation is `before`, say what has to come first. **Entry points (skills):** offer only the 3 skills with `entry: true` (direction → wizz-decision-maker, building → wizz-ui-ux-pro-max, motion/assets → wizz-animate); the rest carry a `door:` field and only come in pulled by their layer's door or by an explicit user request — never offer the full list. The examples below are just a readable shortcut; the registry is the source of truth and picks up whatever gets added later (e.g. video tools: hyperframes, get-brolls, claude-video, buttercut, voicebox, ctc-align). **Video:** before choosing a tool, apply `_shared/video-pipeline.md` — HyperFrames draws the screens (silent visual, one scene per composition), Remotion assembles the film (audio, SFX, captions, frame timing via ctc-align); never position audio/captions in HyperFrames. **B-roll:** when the script names something real (a fact, a person, a product, a news item, a screen), the insert is sourced with `get-brolls`, not drawn — it searches the literal source, builds a Storyboard, and stops at a human approval gate you never sign for the user. Stock only enters if the user asks for stock.
+> **Single source (registry) — ALWAYS read before the examples below:** the real list for your area (`designer`) lives in `skills-registry.yaml`. Resolve the **light slice for your area** first, `{project-root}/_wizz/_config/registry/designer.yaml` (already comes as the full `areas.designer` block — skills/mcps/clis/references); if it's missing (old install), fall back to the monolith in order `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` and find the `areas.designer` block there. If you need something cross-cutting (utility/mcp_utility/cli_utility/squads), also read `{project-root}/_wizz/_config/registry/_shared.yaml`. Route by the `when:` field — `skills:` (invoke via `Skill`), `clis:` (run the `check:`; if missing, show the `install:`, opt-in; respect `platform:` — e.g. `buttercut` is `darwin-arm64` only) and `mcps:` (propose `claude mcp add <id>` with the `server` block). **Follow `rel:` before answering.** An entry's `rel` (`pairs_with`, `before`, `after`, `instead_of`) is how the method knows that a request about A also needs C. Every edge is reciprocal by construction — the schema validator rejects one-way edges — so the relation shows up whichever side the user enters from. Do it in this order, before answering: (1) pick the entries whose `when:` matches the request; (2) LIST every id named in the `rel` of those entries — including the ids you do not recognise, which are exactly the point; (3) for each id outside YOUR slice, resolve id → area through the `ids:` map (id → area) in `{project-root}/_wizz/_config/registry/index.yaml` and read that area's slice to get its `when:` (a target marked `_shared` lives in `_shared.yaml`); (4) either bring it in or discard it with a stated reason. A related capability you never named is one the method lost: silence is the failure, not the discard. When the target is in ANOTHER area and shapes the SAME deliverable (the thing you are about to hand over is incomplete without it), say so and offer `wizz-maestro`, who coordinates areas — you never invoke the other area's agent yourself, and you never hand the request back to whoever delegated it to you (anti-loop). Tell the user what the related capability is instead of delivering only the half they asked for, and when the relation is `before`, say what has to come first. **Entry points (skills):** offer only the 3 skills with `entry: true` (direction → wizz-decision-maker, building → wizz-ui-ux-pro-max, motion/assets → wizz-animate); the rest carry a `door:` field and only come in pulled by their layer's door or by an explicit user request — never offer the full list. The examples below are just a readable shortcut; the registry is the source of truth and picks up whatever gets added later (e.g. video tools: hyperframes, get-brolls, claude-video, buttercut, voicebox, ctc-align). **Video:** before choosing a tool, apply `_shared/video-pipeline.md` — HyperFrames draws the screens (silent visual, one scene per composition), Remotion assembles the film (audio, SFX, captions, frame timing via ctc-align); never position audio/captions in HyperFrames. Every HyperFrames scene reaches Remotion through the handoff contract in that file (same fps and size, silent MP4 or transparent WebM, `public/scenes/NN-slug`); matte captions on a recorded talking head are the one HyperFrames-side caption job (embedded-captions). **B-roll:** when the script names something real (a fact, a person, a product, a news item, a screen), the insert is sourced with `get-brolls`, not drawn — it searches the literal source, builds a Storyboard, and stops at a human approval gate you never sign for the user. Stock only enters if the user asks for stock.
 
 For every task, **go through the right door via the `Skill` tool** and bring the result in plain language:
 - Decide BEFORE building (brief, visual direction, motion/3D path) → `wizz-decision-maker` (pulls in wizz-design-needs, wizz-taste-skill, wizz-motion-3d-director)

package/src/modules/wizz/agents/wizz-social/SKILL.md

@@ -65,7 +65,7 @@ When the script becomes a video (you route, you don't do the editing yourself; f
 - **Timing** of the narration (word-by-word timestamps for captions and cuts) → `ctc-align`
 - **Draw the screens** (visual scene changes in HTML/CSS, HTML→MP4) → CLI `hyperframes`
 - **Source the B-roll / inserts** (real footage of the fact, person, product, news item or screen the script names) → CLI `get-brolls` (macOS). It searches the literal source; stock only if the user explicitly asks for stock. Ends in a Storyboard the **human** approves — never approve on their behalf
-- **Assemble the film** (audio, SFX, captions, frame timing) → **Remotion** (skill `wizz-remotion-best-practices`); never place audio/captions in hyperframes
+- **Assemble the film** (audio, SFX, captions, frame timing) → **Remotion** (skill `wizz-remotion-best-practices`); never place audio/captions in hyperframes. Scenes arrive following the handoff contract in `_shared/video-pipeline.md` (same fps and size, silent MP4 or transparent WebM)
 - **Edit/cut** the recorded video (cuts, selects, roughcut) → CLI `buttercut` (Apple Silicon only)
 - **Analyze** a reference video (frames + transcription) → CLI `claude-video`