DigitalRavagers/Experiment

HyperFrames — à lire en premier

Commencez ici pour toute tâche HyperFrames — surtout en l’absence de configuration d’agent de projet (CLAUDE.md / AGENTS.md / .cursorrules). Carte des capacités + routeur vidéo ci-dessous.

Carte des capacités — quelle compétence pour quelle intention

Vous voulez…	Allez vers
Créer une vidéo (à partir d’une URL, d’un brief, d’un sujet, d’une PR GitHub, d’un métrage existant ou d’un seul élément à animer)	le routeur vidéo ci-dessous (§ Aiguillage vidéo)
Créer un diaporama / une présentation / un pitch deck — diapositives discrètes, fragments, branchements, zones interactives	/slideshow
Créer / éditer une composition HTML — le contrat data-*, clips, pistes, sous-compositions, variables	/hyperframes-core
Animer — règles de mouvement atomiques, blueprints de scènes, transitions, adaptateurs runtime (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU)	/hyperframes-animation
Direction créative — design.md, palettes, typographie, narration, planification des beats, audio-réactif	/hyperframes-creative
Prétraitement média — voix off TTS, musique de fond, transcription, suppression d’arrière-plan, sous-titres	/hyperframes-media
Boucle de développement CLI — init, lint, validate, inspect, preview, render, publish, doctor	/hyperframes-cli
Installer des blocs / composants du registre (hyperframes add)	/hyperframes-registry

Le contrat de création de composition (tout élément temporisé nécessite data-start / data-duration / data-track-index ; les éléments temporisés nécessitent class="clip" ; les timelines GSAP sont en pause et enregistrées sur window.__timelines ; logique déterministe uniquement — pas de Date.now() / Math.random() / réseau) n'est pas dupliqué ici — il se trouve dans /hyperframes-core. Lisez-le avant d'écrire du HTML de composition.

Ce que HyperFrames ne peut pas faire — vérifiez d'abord ceci

HyperFrames crée une composition HTML et la rend en MP4 à partir du code. Ce modèle a des limites strictes. Toute demande qui les dépasse n'est pas un choix d'aiguillage — elle est hors de portée, donc déclinez (ou orientez vers le bon outil) au lieu de chercher un workflow. Ces limites découlent de l'architecture, pas d'une demande spécifique :

• Le rendu est déterministe et autonome. Chaque valeur, ressource et texte est intégré à la création ; le rendu n'effectue aucun appel réseau ni aucune récupération de données en direct / au moment du rendu (règle de base : pas de Date.now() / Math.random() / réseau). « Rafraîchir les chiffres en direct au rendu » est hors de portée — récupérez les données une fois à la création et intégrez-les, ou déclinez.
• La vidéo existante est superposée, jamais éditée. HyperFrames compose des images par-dessus un clip source — /embedded-captions ajoute une couche de sous-titres, /graphic-overlays ajoute des cartes graphiques conçues (tiers inférieurs, appels de données, titres) — et le clip est lu inchangé en dessous, mais aucun des deux ne post-traite le flux vidéo encodé. Modifier le métrage lui-même (son timing, sa couleur, son cadrage, son ordre ou son audio) est une édition de type NLE, hors de portée.
• L'import Remotion est unidirectionnel. /remotion-to-hyperframes traduit la source du framework Remotion en HyperFrames. Il n'existe pas de sens inverse (HyperFrames → Remotion, ou → tout autre framework — hors de portée), et une source React / animation web non-Remotion n'a pas de source Remotion à traduire — recréez-la via /general-video.
• Il ne peut pas produire des entrées qu'il n'a pas. Pas d'enregistrement d'écran / de session, pas de capture caméra, pas de génération de tête parlante IA / avatar synchronisé labialement. Si le métrage ou la ressource n'existe pas encore, HyperFrames ne peut pas le créer — demandez à l'utilisateur de le fournir (ou d'utiliser le bon outil de capture) d'abord.

Tout le reste — une vidéo à partir d'une URL, d'un brief, d'un sujet, d'une PR, d'un métrage à annoter ou d'un seul élément à animer — est dans le champ ; aiguillez ci-dessous.

---

Aiguillage vidéo

Cette section ne connaît QUE les workflows de haut niveau. Elle ne charge pas les phases internes des workflows, les compétences de domaine (hyperframes-* — voir la carte des capacités ci-dessus) ou les références techniques.

Table de décision

Le type d’ENTRÉE (intention) est l’axe principal ; la longueur de SORTIE n’est qu’un plafond, pas une barrière. Pour une entrée correspondante, les workflows spécialisés gèrent tout ce qui va jusqu’à ~3 min — quel workflow vous entrez est décidé par l’intention (le type d’entrée, et pour le texte le sujet), pas par la longueur. La longueur n’a d’importance qu’à l’extrémité supérieure : un contenu vraiment plus long (un tutoriel de 3 à 5 min, une plongée de 5 min+) est un registre différent et aiguille vers /general-video. Dans la bande ≤~3 min, un troisième axe divise les deux workflows alimentés par du texte — le sujet : un produit en cours de commercialisation vs un sujet en cours d’explication (voir la règle de désambiguïsation à l’étape 3 ci-dessous).

Longueur / Entrée	Lancement produit (URL / brief / script)	Site web général / URL	PR GitHub / changement de code	Sujet / article / notes (pas de produit, pas d’URL)	Vidéo existante (tête parlante) †
≤ ~3 min	/product-launch-video	/website-to-video	/pr-to-video	/faceless-explainer	/embedded-captions · /graphic-overlays †
Tutoriel 3-5 min	/general-video	/general-video	/general-video	/general-video	/embedded-captions · /graphic-overlays †
Plongée 5 min+	/general-video	/general-video	/general-video	/general-video	/embedded-captions · /graphic-overlays †
Statique / boucle	/general-video	/general-video	/general-video	/general-video	/general-video

Couverture actuelle : la bande ≤ ~3 min dispose de workflows dédiés pour les entrées lancement-produit / site-web-général / GitHub-PR / sujet (une URL se divise par type puis par intention — voir l’étape 3), et la colonne vidéo existante est couverte quelle que soit la longueur — par /embedded-captions (sous-titres / légendes) ou /graphic-overlays (calques graphiques conçus), divisés par intention (voir l’étape 2). Toute autre cellule est /general-video — le flux général de création de composition HTML (indépendant de l’entrée et de la longueur) : tout ce qui est plus long que ~3 min (les lignes 3-5 min / 5 min+) et tout format statique / boucle. Le routeur n’aboutit jamais à une impasse sur une vidéo créable ; la seule vraie réponse « général / aucun » est une demande en dehors de HyperFrames lui-même (par exemple, l’édition de type NLE d’un fichier vidéo fini — ré-timing, recoloration, recadrage, réorganisation, audio).

† Le métrage existant se divise par intention, pas par longueur. Sous-titres / légendes → /embedded-captions ; calques graphiques conçus / habillage — tiers inférieurs, appels de données, cartes titrées, citations en exergue — → /graphic-overlays. Les deux superposent le clip, qui est lu inchangé en dessous ; aucun n’édite le métrage lui-même.

Court-circuit de genre (précède le tableau). Un motion graphic court (~moins de 10 s), non narré, mené par le design — typographie cinétique, un hit de statistique / graphique, un logo sting, un tiers inférieur / calque, ou un tweet / titre / surbrillance de page capturée animé — aiguille vers /motion-graphics indépendamment de l’entrée. C’est un GENRE DE SORTIE, pas un type d’entrée, donc il prime sur le tableau des types d’entrée ci-dessus lorsque la demande est clairement axée sur le mouvement sans narration (voir l’étape 2). Un traitement plus long ou narré aiguille par type d’entrée, ou /general-video.

Migrer une composition existante (cas spécial)

Le tableau ci-dessus concerne la création d’une vidéo à partir d’une entrée. Un workflow se trouve en dehors : si l’utilisateur demande explicitement de porter / convertir / migrer une composition Remotion (React) existante en HyperFrames → /remotion-to-hyperframes. Il s’agit de traduction de source, pas de création à partir d’une entrée, donc il n’a pas de cellule ENTRÉE × LONGUEUR. Aiguillez ici UNIQUEMENT sur un langage de migration explicite (« porte mon projet Remotion », « convertis cette comp Remotion », « réécris ceci en HyperFrames ») — une mention passagère de Remotion n’est pas un déclencheur ; par défaut, utilisez le tableau de création ou /hyperframes-core.

Procédure d’aiguillage

1. Déterminez le type d’ENTRÉE + la longueur cible. L’aiguillage doit savoir ce que la vidéo concerne — son sujet et son entrée. Si le sujet lui-même n’est pas spécifié (par exemple « fais une vidéo sur notre truc » sans URL, nom de produit, sujet ou ressource à partir de laquelle travailler), ou si le type d’entrée est inconnu, demandez avant d’entrer dans un workflow — clarifiez d’abord ; n’invoquez pas une compétence de workflow puis ne demandez pas, car s’engager dans un workflow est en soi la décision d’aiguillage. Posez au maximum 2 questions de clarification :
   • « Quelle est votre entrée — un produit (URL ou brief), un site web général / une URL, une PR GitHub / un changement de code, un sujet ou article à expliquer, ou une vidéo existante tête parlante à sous-titrer ? »
   • « Longueur cible — environ 3 minutes ou moins, ou plus long (un tutoriel de 3 à 5 min / une plongée de 5 min+) ? »
   • Valeurs par défaut de spécification — énoncez, ne demandez pas (celles-ci n’affectent PAS le routage, donc ne bloquez jamais l’aiguillage sur elles) : rapport hauteur/largeur 16:9 (le moteur prend également en charge le 9:16 vertical — ne changez que si l’utilisateur nomme une destination verticale comme TikTok / Reels / Shorts) ; langue de narration / sous-titres = celle de l’utilisateur. Confirmez uniquement si l’utilisateur s’y oppose ; le workflow choisi reconfirme ses propres spécificités à son étape 0.
2. Choisissez d’abord par type d’ENTRÉE (intention) ; la longueur n’est qu’un plafond, pas une barrière.
   • Motion graphic court mené par le design (court-circuit de genre, précède le tableau des entrées) — le mouvement lui-même est le message : typographie cinétique, un compteur de statistique / nombre, un hit de graphique, un logo sting, un tiers inférieur / calque, ou un tweet / titre / surbrillance de page capturée animé ; généralement moins de ~10 s, pas de narration / voix off → /motion-graphics. C’est un GENRE DE SORTIE, pas un type d’entrée — lorsque la demande est clairement un morceau de motion design rapide, non narré et mené par le design, aiguillez ici indépendamment de l’entrée. Un traitement plus long ou narré du même matériau n’est PAS cela (aiguillez par type d’entrée, ou /general-video).
   • Vidéo tête parlante existante (l’utilisateur a un clip et veut quelque chose ajouté par-dessus) → divisez par intention, quelle que soit la longueur (le type d’entrée l’emporte sur la longueur) : sous-titres / légendes (les mots parlés comme texte lisible) → /embedded-captions ; calques graphiques conçus — tiers inférieurs, appels de données, cartes d’information titrées, citations en exergue, une édition avec habillage graphique → /graphic-overlays. (Éditer le métrage lui-même — ré-timing, recolorer, recadrer, réorganiser, audio — est de type NLE et hors de portée ; voir § Ce que HyperFrames ne peut pas faire.)
   • PR GitHub / changement de code (un lien github.com/<owner>/<repo>/pull/<N>, une référence owner/repo#N, ou « cette PR ») → /pr-to-video (jusqu’à ~3 min).
   • Sinon (URL de produit / brief / texte de sujet) : l’intention choisit le workflow via l’étape 3, et il gère tout ce qui va jusqu’à ~3 min — un court promo de 15 à 30 s et un explainer d’environ 100 s aiguillent tous deux par intention, pas par longueur. Aiguillez vers /general-video (le fallback indépendant de la longueur — voir l’étape 4) uniquement lorsque la cible est clairement plus longue que ~3 min (un tutoriel de 3 à 5 min, une plongée de 5 min+). Ne forcez jamais un contenu vraiment long dans un workflow ≤~3 min — l’intention décide dans la bande, /general-video couvre le reste.
3. Désambiguïsez les entrées URL / texte ≤~3 min (la division par intention). Deux divisions :
   • Type d’URL + intention — une URL ne gagne plus automatiquement pour PLV ; son type puis son intention décident : un lien PR GitHub (.../pull/<N>, owner/repo#N, « cette PR ») → /pr-to-video ; sinon une URL de site web se divise par intention — commercialisation / lancement / promotion d’un produit ou SaaS spécifique → /product-launch-video ; un site général → vidéo (visite de site, showcase de portfolio / blog / page d’atterrissage, un clip social à partir des visuels du site lui-même, ou simplement « transforme ce site en vidéo ») → /website-to-video. Les deux explorent avec un navigateur headless ; les URL de PR sont lues via gh. Lorsqu’il n’est vraiment pas clair qu’une URL de site est un lancement de produit ou une vidéo de site général, posez une question.
   • Produit vs sujet (texte, pas d’URL) — la question décisive est ce que la vidéo concerne, pas le format d’entrée :
     • Un produit / entreprise / SaaS / application / site web spécifique en cours de commercialisation, lancement ou promotion → /product-launch-video.
     • Un concept / sujet / article / comment-quelque-chose-fonctionne en cours d’explication, sans produit et sans URL → /faceless-explainer.
     • Départages : une formulation « Promouvoir / lancer / vendre / notre produit » → PLV. « Expliquer / enseigner / comment X fonctionne / qu’est-ce que X » sans produit → faceless. Le style livré pour faceless est toujours pin-and-paper.
     • Un site nommé sans URL collée est toujours PLV. Un script qui mentionne un produit ou son site web (« notre site est acme.io », « promouvoir ») aiguille vers PLV même sans lien cliquable — PLV peut chercher le site sur le web et l’explorer pour les actifs de marque (sauf si l’utilisateur s’y oppose, → mode préréglé sans capture). Ne pas coller l’URL n’en fait pas un travail faceless / sans capture. Le choix textuel-littéral-vs-reformulation pour un script fourni est interne à PLV et ne change jamais l’aiguillage.
     • Indices contradictoires → demandez, ne devinez pas. Si la source fournie est le propre matériel marketing d’un produit (sa page d’atterrissage, un script promo de lancement, un billet de blog avec un CTA d’achat), c’est PLV. Si c’est un article pédagogique, un tutoriel ou une description de concept — /faceless-explainer. Un simple nom de produit (« Swingvy », « Clerk », « Acme Corp ») sans indication marketing explicite → /faceless-explainer avec le nom de la marque comme sujet vidéo (pas de capture de site à moins que l’utilisateur ne fournisse une URL ou un brief ; aucun lien/nom de site fourni signifie aucun navigateur : lisez le doc de /faceless-explainer — entrée « produit/nom de marque uniquement » en haut de sa configuration initiale).
4. Ce qui échappe au ≤~3 min → /general-video. Trois cas :
   • Longueur cible supérieure à ~3 min (tutoriel 3-5 min, plongée 5 min+).
   • Format statique / boucle / image seul (pas de timeline, pas de narration, pas de scènes à chronométrer — par exemple une image, un graphique, une diapositive, qui RESTE sur l’écran de manière statique ou en boucle).
   • Aucune des divisions ci-dessus ne s’applique (par exemple, l’entrée ne correspond à aucun type colonne — pas un produit, pas un site, pas une PR, pas un sujet, pas une vidéo existante).

/general-video est le workflow de création de composition général. Il a sa propre procédure de configuration (étape 0) qui demande le public cible, la tonalité, les couleurs, la police et les actifs de marque — celles-ci sont propres à son invocation et ne sont pas spécifiées ici.

---

Phase 0 — configuration de l’appel

Conçu pour l’exécution de l’agent — appelé une fois par tâche, renvoie un objet de configuration JSON.

SequenceDiagram de l’appel

L’agent doit lire l’intégralité de ce fichier, puis se comporter comme suit :

1. Déterminer le workflow via la table de décision ci-dessus (le tableau ENTRÉE × LONGUEUR et les 4 étapes de la § Procédure d’aiguillage). Affichez le fichier de compétence du workflow choisi. Si ce fichier demande à son tour une sous-compétence, aiguillez-le à l’intérieur de ce workflow — ne remontez pas ici ni ne défaussez sur l’utilisateur ; la délégation au sein du workflow est gérée par la compétence de ce workflow. Si le fichier choisi a sa propre Phase 0, exécutez-la ; sinon, passez à la création.
2. Si le type d’entrée ou la longueur cible est inconnu → demandez (posez les questions spécifiées ci-dessus ; au maximum 2). Ne demandez PAS sur le rapport hauteur/largeur, la langue, la marque, la police ou la palette — l’étape 1 l’a déjà défini comme des valeurs par défaut de spécification à énoncer. Le workflow choisi peut avoir ses propres questions de Phase 0 ; exécutez-les ensuite.
3. S’il s’avère que la demande vidéo est mieux servie par un outil différent (par exemple, le montage vidéo de type NLE, l’enregistrement d’écran d’un navigateur) → dites « Cette tâche est en dehors du champ de HyperFrames. Vous voulez un outil capable d’enregistrement d’écran / de montage vidéo traditionnel / de modélisation 3D — voulez-vous que je vous recommande une alternative ? » puis arrêtez-vous (termez).
4. Si un workflow est clair et que son fichier Skill a une Phase 0 → ouvrez ce fichier, exécutez sa Phase 0, et créez (ne continuez pas ici).
5. Si le projet a hyperframes.json (c’est-à-dire que le CLI a été initialisé) → vérifiez que tout préréglage de hyperframes.json correspond aux entrées de la Phase 0 — interprétez ces préréglages comme les réponses données. Si le préréglage couvre tous les champs, passez directement à l’étape 1 du workflow ; ne demandez RIEN. Si un aspect est manquant, demandez uniquement celui-ci ; n’écrasez pas les réglages existants.
6. Démarrer la conversation → Votre première réponse à une demande vidéo doit être cette configuration. Ne créez pas d’abord et ne demandez pas après — la configuration est la première chose.

Règle de longueur de la sortie de compétence. Fournissez un sous-total du fichier de compétence choisi AVANT d’appeler la Phase 0 de cette compétence. N’imprimez pas les fichiers Skill en entier pour l’utilisateur — seuls les résultats de la décision d’aiguillage (remplis de la bonne information) sont transmis. L’agent peut lire les fichiers de compétence pour structurer la réponse ; la réponse de l’utilisateur ne verra que le résumé, pas les détails de la compétence.

---

Résumé des compétences de sous-workflow

Pour référence rapide de l’agent ; ces sommaires ne contiennent pas assez de détails pour exécuter le workflow — ils sont destinés à la planification de l’aiguillage uniquement. Ouvrez la compétence réelle pour l’exécution.

• /product-launch-video — crée un plan de 6 sections (accroche · avant/après · problème/solution · commentaires/statuts · CTA · logo/titre/outro) à partir d’une URL ou d’un brief de produit. Capturations de navigateur + couches texte/animation. Style : lent/narré, utilisation d’une maquette sur fond fixe unie. Divers modes (script fourni textuel, script fourni réécrit en format libre, script généré à partir du site du produit, script généré à partir d’un brief, saisie simplement du nom du produit — import via recherche internet).
• /faceless-explainer — crée un plan basé sur un sujet donné en sections séquentielles, chacune étant une série de cartes d’information (comme des diapositives). Entrée : URL ou texte. Style : pin-and-paper.
• /website-to-video — capture site web → séquence vidéo ; entrez une URL unique, capturez-la en navigateur ≈ 2×, éditez au niveau des sections. Style : isolation de capture + texte en surimpression.
• /pr-to-video — gh pr view <N> --json <champs> → script + captures des diffs/messages de commit → vidéo récapitulative de PR (raccourci).
• /embedded-captions — minuterie de transcription (détection de mots parlés) + couche de sous-titres rendue par-dessus la vidéo de l’utilisateur.
• /graphic-overlays — habillage graphique de haut de gamme pour la vidéo de l’utilisateur (tiers inférieur, appel de données, cartes titrées, citations — rendu par-dessus, vidéo inchangée en dessous).
• /motion-graphics — composition HTML pilotée par le mouvement, ≤~10 s, pas de narration ; défilements, compteurs de nombres, typographie cinétique, logos sting.
• /general-video — tout le reste ; config générale de composition + rendu. Sa Phase 0 demande le public cible, la tonalité, les couleurs, la police, et si les actifs de marque sont disponibles.
• /remotion-to-hyperframes — source Remotion (React → <Composition> → <AbsoluteFill> → <Sequence> + <spring>/<interpolate> + useCurrentFrame/useVideoConfig) → traduction HyperFrames (HTML inline + GSAP, même partition temporelle). Fournissez toujours la source Remotion complète ; sort une seule page HTML de composition.