Installer HyperFrames
Reproduit, en une passe, l'intégration qui ajoute HyperFrames en tant que fournisseur vidéo en suivant le contrat en trois étapes Ajout d'un nouveau fournisseur dans CLAUDE.md. Liste de contrôle autonome de chaque artefact qui doit exister ; vérifie chacun et crée uniquement ce qui manque.
Exécutez ce skill au lieu de redériver l'intégration à partir de zéro. C'est l'enregistrement canonique de ce que signifie « HyperFrames est câblé » dans ce dépôt.
Quand invoquer
- Clone frais de marketing-engine qui n'a pas encore de support HyperFrames.
- Un rebase ou une fusion a supprimé l'un des artefacts ci-dessous (
router:checkse plaint, le routage vidéo retombe surhiggsfieldpour les tâches de typographie, ou.skills/hyperframes*/sont manquants). - Un nouveau client souhaite des courts métrages programmatiques / typographie animée / bobines de visualisation de données et la matrice a besoin des trois types de tâches câblés.
- Onboarding d'un nouvel opérateur qui a besoin d'un playbook exécutable par commande unique au lieu de trois commits à lire.
Entrées
repo_root: chaîne. Chemin absolu vers le clone de marketing-engine. Par défautprocess.cwd().branch: chaîne, optionnelle. Branche sur laquelle effectuer le commit. Par défautclaude/install-hyperframes. Crée la branche si elle n'existe pas ; ne fait jamais de commit surmain.dry_run: booléen, optionnel. Quand vrai, affiche les modifications prévues et se termine sans écrire.
Processus
Exécutez chaque étape dans l'ordre. Chaque étape est idempotente — réexécutée sur un dépôt déjà intégré, elle ne fait rien pour cette étape.
Étape 1 — Pré-vol
- Confirmer que
repo_rootcontientCLAUDE.mdavec la ligne## How to Add a New Provider. Refuser de s'exécuter si absent — ce n'est pas un dépôt marketing-engine. - Confirmer que
lib/providers/video.ts,lib/providers/matrix.ts,lib/providers/types.tsetlib/providers/__mocks__/video.tsexistent. Refuser de s'exécuter si l'un d'eux manque. - Confirmer que la branche active n'est pas
main. Si surmain, créer et basculer surbranchd'abord.
Étape 2 — Ajouter les trois skills d'exécution
Créer ces trois répertoires avec les fichiers SKILL.md. Chaque fichier existe déjà dans la version canonique de l'arbre — copier depuis la section Ensemble d'artefacts de référence ci-dessous textuellement. Ignorer un fichier s'il existe déjà et que son name de frontmatter correspond.
.skills/hyperframes/SKILL.md— règles de création de composition (mise en page avant animation, timelines mises en pause et enregistrées surwindow.__timelines, pas deMath.random()/logique temporelle, variables déclarées viadata-composition-variables)..skills/hyperframes-cli/SKILL.md— boucle de développementnpx hyperframeslint → inspect → render. Toujours rendu avec--strict --strict-variables..skills/hyperframes-prompt-builder/SKILL.md— spécialiste invoqué parvideo-prompt-builderlorsque la matrice résout enhyperframes; charge les jetons de marque depuisclients/<slug>/design.md, choisit un modèle partask_kind, retourne une spécification de composition + arguments de rendu.
Étape 3 — Mettre à jour le skill de répartition
Dans .skills/video-prompt-builder/SKILL.md :
- Ajouter
hyperframes-prompt-builderà la liste des spécialistes dans le paragraphe d'ouverture et la section Skills connexes. - Étendre l'énumération d'entrée
task_kindavecmotion_typography,data_viz_reel,programmatic_short. - Dans l'étape Processus qui vérifie les variables d'environnement, ajouter
HYPERFRAMES_ACTIVEà la liste. - Dans le mappage fournisseur→spécialiste, ajouter la ligne
Hyperframes -> hyperframes-prompt-builder. - Ajouter un exemple : une bobine KPI hebdomadaire routée vers HyperFrames avec
task_kind: programmatic_short.
Ignorer toute sous-étape dont la chaîne cible est déjà présente.
Étape 4 — Étendre la couche fournisseur
Dans lib/providers/types.ts, ajouter trois membres à l'union VideoTask :
| "motion-typography"
| "data-viz-reel"
| "programmatic-short"
Dans lib/providers/matrix.ts :
- Ajouter trois lignes à
EMBEDDED_DEFAULTS.video:motion-typography,data-viz-reel,programmatic-short— chacune par défauthyperframes. - Ajouter des alias d'étiquette à
TASK_LABEL_MAP:"motion typography","kinetic typography","data viz reel","data-viz reel","programmatic short","parametrized short".
Dans lib/providers/video.ts :
- Ajouter une classe
HyperframesVideoProviderétendantRealVideoBase, conditionnée parprocess.env.HYPERFRAMES_ACTIVE === "true", qui lève une erreur "local CLI render required in caller context; stub" depuisrealGenerate(correspondant au pattern stub existant de higgsfield/topview). - Enregistrer
hyperframes: () => new HyperframesVideoProvider()dansREAL_VIDEO_REGISTRY.
Dans lib/providers/__mocks__/video.ts :
- Ajouter un
MockHyperframesVideoProviderétendantBaseMockVideoavecname = "hyperframes". - Enregistrer
hyperframes: () => new MockHyperframesVideoProvider()dansMOCK_VIDEO_REGISTRY.
Étape 5 — Mettre à jour le fichier de matrice de routage
Dans .specs/architecture/PROVIDERS.md, ajouter trois lignes à la table Routage vidéo :
| 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 |
Étape 6 — Mettre à jour .env.example
Ajouter, après WAVESPEED_API_KEY= :
# HyperFrames est un rendu HTML→MP4 local ; aucune clé API nécessaire.
# Définir HYPERFRAMES_ACTIVE=true une fois que `npx hyperframes doctor` passe localement
# (Node >= 22, FFmpeg dans PATH). Voir https://github.com/wesleysimplicio/hyperframes
HYPERFRAMES_ACTIVE=false
Étape 7 — Mettre à jour CLAUDE.md
- Dans le tableau Stack, changer la cellule des fournisseurs de la ligne
Videopour inclurehyperframes (local HTML→MP4). - Dans Skills disponibles, insérer trois lignes après
wavespeed-batch:hyperframes— création de composition animée avec HTML comme source de vérité.hyperframes-cli— exécutenpx hyperframeslint/inspect/preview/render.hyperframes-prompt-builder— sélectionné parvideo-prompt-builderlorsque la matrice résout enhyperframes.
Étape 8 — Vérifier
- Analyser
.specs/architecture/PROVIDERS.mdvia le test ci-dessous et affirmer quemotion-typography,data-viz-reel,programmatic-shortrésolvent tous enhyperframes. - Exécuter
npm run typecheck— accepter toute défaillance préexistante non liée aux modifications (par exemple,@types/nodemanquant) ; échouer si une nouvelle erreur TypeScript référence la couche fournisseur. - Exécuter
npm run router:checksi un.envexiste dans le dépôt ; sinon ignorer (le script nécessite.envet n'est pas lié à la forme de l'intégration). - Confirmer que
git statusmontre uniquement les fichiers attendus.
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('MANQUANT:', key); process.exit(1);
}
}
console.log('PROVIDERS.md OK');
"
Étape 9 — Commiter et pousser
- Indexer exactement les fichiers que ce skill a touchés. Ne jamais utiliser
git add -A. - Commiter avec le message canonique :
plus un corps décrivant l'exécution du contrat en trois étapes (voir le commit de référence fusionné pour le libellé).feat(skills): connecter HyperFrames en tant que fournisseur vidéo - Pousser vers
origin <branch>. Ouvrir une pull request en brouillon si aucune n'existe pour la branche.
Sorties
branch: chaîne. La branche qui contient le commit.pr_url: chaîne. L'URL de la pull request en brouillon, si elle a été créée ou existait déjà.files_written: tableau de chemins relatifs réellement créés ou modifiés.files_skipped_idempotent: tableau de chemins relatifs qui étaient déjà corrects.verification:{ providers_md_pass: booléen, typecheck_pass: booléen, router_check: "pass" | "skipped" | "fail" }.
Règles non négociables
- Idempotent. Réexécuté sur un dépôt déjà intégré, ne touche aucun fichier.
- Ne jamais commiter sur
main. Créer d'abord une branche de fonctionnalité ; la politique de branche du moteur est appliquée en amont. - Aucun corps de skill ne mentionne
hyperframesen dehors du contrat. La sélection du fournisseur passe toujours parPROVIDERS.md+lib/router.ts. Ce skill est l'amorçage ; la sélection à l'exécution reste agnostique au fournisseur. - Ne pas modifier un MP4 rendu ni aucun fichier sous
outputs/. Ce skill modifie uniquement la plomberie du moteur. - Ne jamais supprimer un skill
compliance-<client actif>existant ni aucun artefact spécifique au client. L'intégration est additive.
Modes d'échec
- Échec de l'étape 1 de pré-vol (pas un dépôt marketing-engine) : afficher le fichier manquant et s'arrêter. Ne pas essayer de le "réparer".
- Un fichier existe déjà avec un contenu conflictuel (par exemple,
.skills/hyperframes/SKILL.mda été modifié manuellement) : faire un diff par rapport au contenu canonique ; afficher le diff ; demander à l'opérateur avant d'écraser. npm run typechecksignale une nouvelle erreur TypeScript danslib/providers/: s'arrêter, afficher l'erreur, ne pas commiter.git pushéchoue pour des raisons non réseau : s'arrêter. Les échecs réseau sont réessayés selon la politique git du projet (2s, 4s, 8s, 16s de backoff, jusqu'à 4 tentatives).
Skills connexes
hyperframes: création à l'exécution (installé par ce skill à l'étape 2).hyperframes-cli: lint/inspect/render à l'exécution (installé par ce skill à l'étape 2).hyperframes-prompt-builder: spécialiste à l'exécution (installé par ce skill à l'étape 2).video-prompt-builder: répartiteur mis à jour par ce skill à l'étape 3.llm-router: non lié ; le routage des fournisseurs LLM est un répartiteur parallèle.
Ensemble d'artefacts de référence
Les contenus canoniques de chaque fichier que ce skill écrit se trouvent dans le commit fusionné sur main :
- Skills :
.skills/hyperframes/SKILL.md,.skills/hyperframes-cli/SKILL.md,.skills/hyperframes-prompt-builder/SKILL.md - Couche fournisseur :
lib/providers/types.ts,lib/providers/matrix.ts,lib/providers/video.ts,lib/providers/__mocks__/video.ts - Matrice de routage :
.specs/architecture/PROVIDERS.md - Env :
.env.example - Charte :
CLAUDE.md
En cas de doute, effectuer un diff par rapport à origin/main au commit de référence fusionné et copier la version canonique textuellement. Ne pas retaper de mémoire.
Référence amont
- HyperFrames : https://github.com/wesleysimplicio/hyperframes
- Catalogue de skills du projet : https://github.com/wesleysimplicio/hyperframes/tree/main/skills