HyperFrames installieren
Stellt in einem Durchgang die Integration her, die HyperFrames als Video-Provider gemäß dem Drei-Schritte-Vertrag Neuen Provider hinzufügen in der CLAUDE.md einbindet. Eine eigenständige Checkliste aller Artefakte, die vorhanden sein müssen; prüft jedes einzelne und erstellt nur, was fehlt.
Führe dieses Skill aus, anstatt die Integration von Grund auf neu abzuleiten. Es ist die kanonische Aufzeichnung davon, was „HyperFrames ist eingebunden“ in diesem Repository bedeutet.
Wann verwenden
- Frischer marketing-engine Clone, der noch keine HyperFrames-Unterstützung hat.
- Ein Rebase oder Merge hat eines der unten genannten Artefakte entfernt (
router:checkmeldet Fehler, Video-Routing fällt für Typografie-Aufgaben aufhiggsfieldzurück, oder.skills/hyperframes*/fehlen). - Ein neuer Kunde wünscht programmatische Kurzfilme / Bewegttypografie / Datenvisualisierungs-Clips und die Matrix muss die drei Aufgabenarten einbinden.
- Ein neuer Operator wird eingearbeitet und benötigt ein einziges befehlssetzerbares Playbook anstatt drei Commits zum Lesen.
Eingaben
repo_root: Zeichenkette. Absoluter Pfad zum marketing-engine Clone. Standard:process.cwd().branch: Zeichenkette, optional. Branch, auf dem committet werden soll. Standard:claude/install-hyperframes. Erstellt den Branch, falls er nicht existiert; committet nie aufmain.dry_run: Boolesch, optional. Beitruewerden die geplanten Änderungen ausgegeben und das Skill wird ohne Schreibzugriff beendet.
Ablauf
Jeden Schritt in Reihenfolge ausführen. Jeder Schritt ist idempotent – eine erneute Ausführung in einem bereits integrierten Repository bewirkt für diesen Schritt nichts.
Schritt 1 – Vorprüfung
- Bestätigen, dass
repo_rooteineCLAUDE.mdmit der Zeile## How to Add a New Providerenthält. Ausführung verweigern, falls fehlend – dies ist kein marketing-engine Repository. - Bestätigen, dass
lib/providers/video.ts,lib/providers/matrix.ts,lib/providers/types.tsundlib/providers/__mocks__/video.tsexistieren. Ausführung verweigern, falls eine davon fehlt. - Bestätigen, dass der aktive Branch nicht
mainist. Falls aufmain, zuerstbrancherstellen und auschecken.
Schritt 2 – Die drei Laufzeit-Skills hinzufügen
Diese drei Verzeichnisse mit den SKILL.md-Dateien erstellen. Jede Datei existiert bereits in der kanonischen Version im Baum – aus dem unten stehenden Referenz-Artefaktsatz wörtlich kopieren. Eine Datei überspringen, wenn sie bereits existiert und ihr Frontmatter name übereinstimmt.
.skills/hyperframes/SKILL.md– Regeln für die Erstellung von Kompositionen (Layout-vor-Animation, abgespielte Zeitachsen + aufwindow.__timelinesregistriert, keinMath.random()/zeitbasierte Logik, Variablen deklariert überdata-composition-variables)..skills/hyperframes-cli/SKILL.md–npx hyperframesLint → Inspect → Render-Entwicklungsschleife. Rendert immer mit--strict --strict-variables..skills/hyperframes-prompt-builder/SKILL.md– Spezialist, der vonvideo-prompt-builderaufgerufen wird, wenn die Matrix aufhyperframesauflöst; lädt Markentoken ausclients/<slug>/design.md, wählt eine Vorlage protask_kindund gibt eine Kompositionsspezifikation + Render-Argumente zurück.
Schritt 3 – Das Dispatcher-Skill aktualisieren
In .skills/video-prompt-builder/SKILL.md:
hyperframes-prompt-builderzur Spezialistenliste im Eröffnungsabsatz und im Abschnitt Verwandte Skills hinzufügen.- Die
task_kind-Eingabe-Enum ummotion_typography,data_viz_reel,programmatic_shorterweitern. - Im Ablauf-Schritt, der Umgebungsvariablen prüft,
HYPERFRAMES_ACTIVEzur Liste hinzufügen. - In der Provider→Spezialist-Zuordnung die Zeile
Hyperframes -> hyperframes-prompt-builderhinzufügen. - Ein Beispiel hinzufügen: ein wöchentlicher KPI-Clip, der an Hyperframes mit
task_kind: programmatic_shortweitergeleitet wird.
Jeden Unterschritt überspringen, dessen Zielzeichenfolge bereits vorhanden ist.
Schritt 4 – Die Provider-Schicht erweitern
In lib/providers/types.ts drei Mitglieder zur VideoTask-Vereinigung hinzufügen:
| "motion-typography"
| "data-viz-reel"
| "programmatic-short"
In lib/providers/matrix.ts:
- Drei Zeilen zu
EMBEDDED_DEFAULTS.videohinzufügen:motion-typography,data-viz-reel,programmatic-short– jeweils standardmäßig aufhyperframes. - Label-Aliase zu
TASK_LABEL_MAPhinzufügen:"motion typography","kinetic typography","data viz reel","data-viz reel","programmatic short","parametrized short".
In lib/providers/video.ts:
- Eine
HyperframesVideoProvider-Klasse hinzufügen, dieRealVideoBaseerweitert, geschützt durchprocess.env.HYPERFRAMES_ACTIVE === "true", die inrealGenerateeinen Fehler „local CLI render required in caller context; stub“ auslöst (entsprechend dem bestehenden higgsfield/topview-Stub-Muster). hyperframes: () => new HyperframesVideoProvider()inREAL_VIDEO_REGISTRYregistrieren.
In lib/providers/__mocks__/video.ts:
- Einen
MockHyperframesVideoProviderhinzufügen, derBaseMockVideomitname = "hyperframes"erweitert. hyperframes: () => new MockHyperframesVideoProvider()inMOCK_VIDEO_REGISTRYregistrieren.
Schritt 5 – Die Routing-Matrix-Datei aktualisieren
In .specs/architecture/PROVIDERS.md drei Zeilen an die Video-Routing-Tabelle anhängen:
| Motion typography | hyperframes | HTML/GSAP kinetic type, brand-faithful, deterministic |
| Data viz reel | hyperframes | declared variables → re-renderable charts (NYT-style) |
| Programmatic short | hyperframes | parametrized HTML composition; byte-identical re-renders |
Schritt 6 – .env.example aktualisieren
Nach WAVESPEED_API_KEY= anhängen:
# HyperFrames is a local HTML→MP4 renderer; no API key needed.
# Set HYPERFRAMES_ACTIVE=true once `npx hyperframes doctor` passes locally
# (Node >= 22, FFmpeg on PATH). See https://github.com/wesleysimplicio/hyperframes
HYPERFRAMES_ACTIVE=false
Schritt 7 – CLAUDE.md aktualisieren
- In der Stack-Tabelle die Provider-Zelle der
Video-Zeile umhyperframes (local HTML→MP4)ergänzen. - In Verfügbare Skills drei Zeilen nach
wavespeed-batcheinfügen:hyperframes– HTML-as-source-of-truth motion composition authoring.hyperframes-cli– runsnpx hyperframeslint/inspect/preview/render.hyperframes-prompt-builder– selected byvideo-prompt-builderwhen the matrix resolves tohyperframes.
Schritt 8 – Verifizieren
.specs/architecture/PROVIDERS.mdmit dem untenstehenden Test parsen und bestätigen, dassmotion-typography,data-viz-reel,programmatic-shortalle aufhyperframesauflösen.npm run typecheckausführen – bestehende Fehler vor der Änderung akzeptieren (z. B. fehlendes@types/node); abbrechen, wenn ein neuer TS-Fehler auf die Provider-Schicht verweist.npm run router:checkausführen, falls eine.envim Repository existiert; sonst überspringen (das Skript benötigt.envund ist nicht mit der Integrationsform verwandt).- Bestätigen, dass
git statusnur die erwarteten Dateien anzeigt.
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
console.error('MISSING:', key); process.exit(1);
}
}
console.log('PROVIDERS.md OK');
"
Schritt 9 – Committen und pushen
- Genau die Dateien stagen, die dieses Skill berührt hat. Niemals
git add -A. - Mit der kanonischen Nachricht committen:
plus einem Body, der die Ausführung des Drei-Schritte-Vertrags beschreibt (siehe den gemergten Referenz-Commit für den Wortlaut).feat(skills): wire HyperFrames as a video provider - Nach
origin <branch>pushen. Einen Draft-PR öffnen, falls für den Branch noch keiner existiert.
Ausgaben
branch: Zeichenkette. Der Branch, der den Commit enthält.pr_url: Zeichenkette. Die Draft-PR-URL, falls eine erstellt wurde oder bereits existierte.files_written: Array relativer Pfade, die tatsächlich erstellt oder geändert wurden.files_skipped_idempotent: Array relativer Pfade, die bereits korrekt waren.verification:{ providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }.
Unverhandelbare Regeln
- Idempotent. Erneute Ausführung in einem bereits integrierten Repository berührt keine Dateien.
- Nie auf
maincommitten. Zuerst einen Feature-Branch erstellen; die Branch-Richtlinie der Engine wird upstream durchgesetzt. - Kein Skill-Body erwähnt
hyperframesaußerhalb des Vertrags. Die Provider-Auswahl erfolgt weiterhin überPROVIDERS.md+lib/router.ts. Dieses Skill ist das Bootstrap; die Laufzeitauswahl bleibt provider-unabhängig. - Kein bearbeitetes MP4 oder eine Datei unter
outputs/ändern. Dieses Skill ändert nur die Engine-Infrastruktur. - Niemals ein bestehendes
compliance-<aktiver Kunde>-Skill oder ein kundenspezifisches Artefakt löschen. Die Integration ist additiv.
Fehlermodi
- Schritt-1-Vorprüfung schlägt fehl (kein marketing-engine Repository): Die fehlende Datei anzeigen und anhalten. Nicht versuchen, sie zu „reparieren“.
- Eine Datei existiert bereits mit widersprüchlichem Inhalt (z. B.
.skills/hyperframes/SKILL.mdwurde manuell bearbeitet): Diff gegen den kanonischen Inhalt durchführen; den Diff anzeigen; den Operator vor dem Überschreiben fragen. npm run typecheckmeldet einen neuen TS-Fehler inlib/providers/: Anhalten, den Fehler anzeigen, nicht committen.git pushschlägt aus nicht-networkbedingten Gründen fehl: Anhalten. Netzwerkfehler werden gemäß der Git-Richtlinie des Projekts wiederholt (2s, 4s, 8s, 16s Backoff, bis zu 4 Versuche).
Verwandte Skills
hyperframes: Laufzeit-Authoring (in Schritt 2 von diesem Skill installiert).hyperframes-cli: Laufzeit-Lint/Inspect/Render (in Schritt 2 von diesem Skill installiert).hyperframes-prompt-builder: Laufzeit-Spezialist (in Schritt 2 von diesem Skill installiert).video-prompt-builder: Dispatcher, der in Schritt 3 von diesem Skill aktualisiert wird.llm-router: Nicht verwandt; LLM-Provider-Routing ist ein paralleler Dispatcher.
Referenz-Artefaktsatz
Die kanonischen Inhalte aller Dateien, die dieses Skill schreibt, befinden sich im gemergten Commit auf main:
- Skills:
.skills/hyperframes/SKILL.md,.skills/hyperframes-cli/SKILL.md,.skills/hyperframes-prompt-builder/SKILL.md - Provider-Schicht:
lib/providers/types.ts,lib/providers/matrix.ts,lib/providers/video.ts,lib/providers/__mocks__/video.ts - Routing-Matrix:
.specs/architecture/PROVIDERS.md - Umgebung:
.env.example - Charter:
CLAUDE.md
Im Zweifelsfall einen Diff gegen origin/main im gemergten Referenz-Commit durchführen und die kanonische Version wörtlich kopieren. Nicht aus dem Gedächtnis neu tippen.
Upstream-Referenz
- HyperFrames: https://github.com/wesleysimplicio/hyperframes
- Projekt-Skill-Katalog: https://github.com/wesleysimplicio/hyperframes/tree/main/skills