pr-to-video - Dispatch-Eintrag
Die Eingabe ist ein GitHub Pull Request (eine Code-Änderung), angegeben als PR-URL, als <owner>/<repo>#<N>-Referenz oder als „dieser PR“ in einem Repository mit einem offenen PR, das ausgecheckt ist. Die Ausgabe ist ein Code-Änderungs-Erklärvideo: was ausgeliefert wurde, warum und wie es funktioniert – gerendert aus dem Diff/den Commits als Vorher-Nachher-, Diff-Highlight-, Dateibaum- und Auswirkungsszenen. Standardlänge bis zu ~3 min (Sweet Spot ~30–90s); ein wirklich längerer oder erschöpfender Durchgang durch jede Datei (5 min+) ist ein anderer Stil → /general-video. Es gibt kein Website-Scraping und kein Headless Chrome für die Aufnahme – die Aufnahme erfolgt über die gh CLI. Die ausgelieferte Stilvorgabe ist immer claude (warm-redaktionell; charakteristisches navy Code-Fenster).
Bestätige die Route vor Schritt 0. Dieser Skill erklärt einen GitHub Pull Request (eine Code-Änderung, die über
ghgelesen wird). Wenn die Eingabe eine Marketing-/Produktseite ist →/product-launch-video; eine allgemeine Website →/website-to-video; ein Thema/Artikel ohne PR →/faceless-explainer; eine gesamte Repository-Tour oder ein Multi-PR-Release →/general-video. Nicht im Anwendungsbereich: Live-/Renderzeitdaten – PR-Fakten werden einmal zum Autorzeitpunkt gelesen und fest eingebacken. Bei einer Nicht-PR-Eingabe oder Unsicherheit: Lies zuerst/hyperframes.
Dieser Workflow besitzt nur die PR-spezifische Front (Aufnahme + Story-Design); jede Phase, die als gemeinsam markiert ist, verwendet die Engine von faceless-explainer unverändert (sie liegt unter den eigenen scripts/ + agents/ + phases/ des Skills, sodass <SKILL_DIR> zu pr-to-video aufgelöst wird).
Alle Artefakte gehen zu PROJECT_DIR = videos/<project-name>/ (erstellt in Schritt 0); alle Pfade unten sind relativ dazu. Der Dispatch ist Harness-portabel: Vor dem ersten Sub-Agenten-Dispatch lies <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md einmal – es bildet die Dispatch-Verben (paralleler Fan-out / Hintergrund / Warten) auf die Primitiven deines Harness ab; ein Parallelitäts-Limit unter N bedeutet Wellen der Größe N, niemals weniger Worker. Diese Datei ist ein verbindliches Runbook, keine Hintergrundlektüre: Führe die Schritte der Reihe nach aus und erstelle jedes Phasen-Artefakt mit dem dafür vorgesehenen Skript oder der Agentenrolle – ersetze keine freie Pipeline und überspringe keinen Pausenschritt, nur weil die Anfrage klar erscheint. Einen Schritt, den du nicht ausführen kannst → stoppe und melde.
| Phase | Ausführung | Primäres Artefakt | Detaillierter Ablauf |
|---|---|---|---|
| init | Bash | hyperframes.json | Schritt 0 |
| Aufnahme (eigen) | Bash (gh CLI + ingest.mjs + fetch-people-avatars.mjs, KEIN Agent, KEIN Scrape) | capture/pr.json + diff.patch + extracted/{tokens.json,visible-text.txt,people.json} + public/avatars/ | Schritt 1 |
| Design-System (gemeinsam) | Bash (kein Agent, deterministisch claude) | design-system/design.html + chunks/ | Schritt 1b |
| Story-Design (eigen) | Sub-Agent | narrator_scripts.json | agents/story-design.md |
| Audio (gemeinsam) | audio.mjs in Bash | audio_meta.json | phases/audio/guide.md |
| Visuelles Design (gemeinsam) | Sub-Agent | section_plan.md | agents/visual-design.md |
| Vorbereitung (gemeinsam) | prep.mjs in Bash | group_spec.json | scripts/prep.mjs |
| Untertitel (gemeinsam, detailliert) | captions.mjs group -> captions.mjs html in Bash (kein Sub-Agent) | caption_groups.json + compositions/captions.html | scripts/captions.mjs |
| Szenen (gemeinsam) | N x Sub-Agent (parallel) | compositions/scene_*.html oder compositions/group_w*.html | agents/hyperframes-scene.md |
| Finalisierung (gemeinsam) | Bash-Präludium (wait-bgm + Zusammenbau + Transitions einfügen/verifizieren + Videos heben + SFX verifizieren + Preflight) -> Finalisierungs-Sub-Agent (kleine Befunde direkt beheben + einen schlanken Kontaktbogen-Look + Rendering) | renders/video.mp4 | Schritt 7 / agents/hyperframes-finalize.md |
Voraussetzungen
macOS Apple Silicon oder Linux x64. Systemtools: brew install [email protected] node ffmpeg (verwende Homebrew Python, nicht /usr/bin/python3, sonst wird pip install durch PEP 668 blockiert); dann einmal npx hyperframes doctor ausführen (lädt Chrome herunter – benötigt für Snapshot/Rendering, nicht für die Aufnahme). Die überlappte Render-Prüfung (scripts/check-overlap.mjs, ausgeführt in Worker-Selbstprüfungen und Preflight) verwendet denselben gecachten Chrome – es lädt niemals einen Browser herunter; seine einzige Abhängigkeit ist das puppeteer-core npm-Modul, das einmal vor dem Szenen-Fan-out sichergestellt wird (Schritt 5.5, --ensure-deps, ~5s, keine vollständige puppeteer-Installation). CLIs: gh (GitHub CLI, authentifiziert – gh auth status muss bestehen) und hyperframes. Optionale Cloud-Schlüssel (sonst lokale Fallbacks) – in Schritt 0.5 eingeben:
| Schlüssel / Anforderung | Verwendet für | Standard / Fallback |
|---|---|---|
gh auth status OK | Lesen des PR (öffentlich oder privat) | erforderlich – schnell fehlschlagen mit dem Auth-Hinweis |
HEYGEN_API_KEY (oder hyperframes auth login) | TTS (Cloud, Wort-für-Wort-Zeitstempel) | Stimme: automatisch (erste englische Starfish-Stimme; überschreibe mit --voice) |
ELEVENLABS_API_KEY | TTS (Cloud; benötigt pip install elevenlabs) | Stimme 21m00Tcm4TlvDq8ikWAM (Rachel) |
| Keines und nicht eingeloggt | TTS | Lokales Kokoro, Stimme am_michael (nicht-Englisch: Übergib --voice) |
GEMINI_API_KEY / GOOGLE_API_KEY (Aliase) | Lyria BGM | Nicht gesetzt -> lokales MusicGen (erster Lauf lädt ~300 MB herunter) |
Ablauf
Schritt 0.0 - Bestätige das Briefing (IMMER eine Runde fragen, dann bauen)
Vor Schritt 0 immer pausieren und das Briefing in einer Nachricht erfragen, dann auf den Benutzer warten – dies niemals überspringen, selbst wenn die Anfrage vollständig erscheint. Starte mit einer empfohlenen Voreinstellung für jedes Feld und fülle vor, was der Benutzer bereits angegeben hat (bestätigen, nicht blind erneut fragen): den Winkel (Changelog / Feature-Enthüllung / Fix / Refaktorierung – Standard: aus PR ableiten), die Zielgruppe (Entwickler vs. allgemeine Benutzer – Standard: Entwickler), die Länge (Standard ~60–90s) und – falls /hyperframes sie nicht gesetzt hat – Seitenverhältnis (Standard 16:9) und Sprache. Stil ist immer claude. Fahre mit Schritt 0 nur fort, nachdem der Benutzer geantwortet hat; ein „Los“ / „Verwende die Voreinstellungen“ ist eine gültige Antwort, die alle Voreinstellungen akzeptiert.
Schritt 0 - Initialisiere das Videoprojekt
Arbeitsverzeichnis ist das Agent-Workspace-Root (z. B. /tmp/pr-video-...). Schreibe alle Video-Artefakte unter PROJECT_DIR = videos/<project-name>/.
<project-name>: Verwende das vom Benutzer angegebene Verzeichnis (z. B. Verwende ./videos/retry-pr), sonst ein kurzer kebab-case-Name, der vom PR abgeleitet ist (<repo>-pr-<N>, z. B. widgets-pr-1187). Nicht der Workspace-Basename oder ein Zeitstempel.
Nur wenn $PROJECT_DIR/hyperframes.json fehlt:
PROJECT_DIR="${PR_VIDEO_DIR:-videos/<project-name>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes initlegt ein generischesAGENTS.md/CLAUDE.mdin$PROJECT_DIRab; lasse sie dort – sie sind Agenten-Gerüst für jeden, der später das fertige Projekt öffnet.
Einschränkungen: Führe hyperframes init niemals aus / generiere AGENTS.md / CLAUDE.md im Workspace-Root; verschachtele niemals ein weiteres hyperframes/ innerhalb von PROJECT_DIR; jeder Bash-Befehl (Master + Sub-Agenten) ist eine (cd "$PROJECT_DIR" && ...) Subshell – niemals ein nacktes cd.
Schritt 0.5 - API-Key-Hinweis
Überspringe, wenn $PROJECT_DIR/.env existiert oder context.log nicht leer ist (= nicht der erste Lauf). Andernfalls erkenne zuerst, was verfügbar ist (HeyGen TTS an, wenn $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY gesetzt ist oder ~/.heygen/credentials von hyperframes auth login existiert; ElevenLabs / Gemini nur, wenn ihre Env-Schlüssel gesetzt sind), dann pausiere immer und biete das Menü an – warte auf den Benutzer; fahre nicht selbstständig fort, selbst wenn eine funktionierende Konfiguration erkannt wird (der Benutzer möchte möglicherweise einen Schlüssel wie Gemini hinzufügen). Gib an, was erkannt wurde, dann: Schlüssel einfügen (→ Schreibe $PROJECT_DIR/.env, eine KEY=value-Zeile pro Zeile, gleicher Name wird überschrieben) / „Los“ (mit dem Konfigurierten fortfahren – env, .env oder hyperframes auth login) / „Überspringen“ (mit lokalen Fallbacks für nicht Konfiguriertes fortfahren). Dann fahre mit Schritt 1 fort.
Schritt 1 - Aufnahme (Bash, KEIN Agent, KEIN Scrape)
Löse die PR-Referenz auf und hole strukturierte Fakten mit gh, dann füge sie in das synthetische Aufnahme-Paket ein, das die gemeinsame Backend erwartet (spiegelt das Scrape-freie Gerüst von faceless-explainer). gh wird hier im Orchestrator ausgeführt, sodass Auth-/Nicht-Gefunden-/Private-Repo-Fehler mit gh's eigenem stderr gemeldet werden; ingest.mjs ist eine reine Offline-Transformation.
# PR-Referenz: eine vollständige URL, "<owner>/<repo>#<N>" oder "<N>" innerhalb eines ausgecheckten Repos.
PR="<url | owner/repo#N | N>"
# Schnell fehlschlagen, wenn gh nicht authentifiziert ist.
gh auth status || { echo "gh nicht authentifiziert — ausführen: gh auth login"; exit 1; }
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && gh pr view "$PR" \
--json number,title,body,author,url,baseRefName,headRefName,commits,files,additions,deletions,changedFiles,labels,reviews,latestReviews,comments,assignees,reviewDecision,mergedBy \
> capture/pr.json)
(cd "$PROJECT_DIR" && gh pr diff "$PR" > capture/diff.patch)
# Falte pr.json + diff.patch in tokens.json (colors:[] → claude native palette) +
# visible-text.txt (das narrative Briefing) + people.json (PR-Autor + Commit-Autoren mit Häufigkeiten +
# Reviewer/Kommentatoren/Zugewiesene, Bot-gefiltert + dedupliziert, jeder mit einem GitHub-Avatar-URL).
# (Der PR-`author` ist nur der Ersteller; Commit-Autoren aus commits[].authors[] werden ebenfalls erfasst.)
# ingest ist OFFLINE.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# Netzwerkschritt (der einzige der Personen-Front – ingest bleibt offline): Lade den GitHub-Avatar jedes
# Mitwirkenden zu public/avatars/<login>.png für eine optionale Credits-/ shipped-by-Schlussaufnahme.
# Best-Effort – ein fehlender Avatar oder ein Offline-Lauf blockiert niemals (exit 0).
# Avatare + diese Schlussaufnahme sind der EINE Ort, an dem pr-to-video den faceless-default lockert.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Validierung:
[ -s "$PROJECT_DIR/capture/pr.json" ] && \
[ -s "$PROJECT_DIR/capture/diff.patch" ] && \
[ -s "$PROJECT_DIR/capture/extracted/tokens.json" ] && \
[ -s "$PROJECT_DIR/capture/extracted/visible-text.txt" ] && \
[ -s "$PROJECT_DIR/capture/extracted/people.json" ] && \
[ -d "$PROJECT_DIR/capture/assets" ] && echo ok || echo fehlt
# public/avatars/ ist Best-Effort – seine Abwesenheit ist KEIN Fehler (keine Avatare aufgelöst / offline).
Wenn gh fehlschlägt (Auth / nicht gefunden / privat), melde das genaue stderr und stoppe – erfinde keine PR-Inhalte. Wenn ingest.mjs beendet
…
[gekürzt zur Übersetzung]