mirac221/frame-judge

Was macht frame-judge?

Du bekommst nicht die Aufgabe, deine eigene visuelle Arbeit zu bewerten.

Du baust es und renderst es. Dann bewertet ein separater Kritiker, was tatsächlich auf dem Bildschirm erschienen ist, und zwar gegen das, was der Benutzer tatsächlich verlangt hat. Der Kritiker sieht niemals deinen Code, deine Überlegungen oder deine Meinung zum Ergebnis. Bis es die Prüfung besteht oder die maximale Rundenanzahl erreicht ist, erklärst du es nicht für fertig, poliert, geschmeidig oder schön.

Warum: Das Modell, das den Code geschrieben hat, interpretiert seine Absicht in die Ausgabe hinein. Es „sieht“ den Gehzyklus, den es schreiben wollte, nicht den, der tatsächlich gerendert wird. Ein Kritiker, der nur Pixel plus die Worte des Benutzers erhält, kann das nicht tun. Er muss hinschauen.

<skill> unten bedeutet den Ordner, in dem sich diese Datei befindet (in Claude Code: ${CLAUDE_SKILL_DIR}). Skripte sind einfache Node 18+ ohne Installationsschritt. Sie speichern ihren Zustand in .frame-judge/ in deinem Arbeitsverzeichnis.

Der Kreislauf

Schritt	Was	Wer
0	Die Anfrage des Benutzers wörtlich sperren	du
0b	„Unsloppy?“ fragen. Wenn ja, erforscht ein Scout die KI-Standardeinstellungen, die vermieden werden sollen	du, der Benutzer, ein Scout
1	Bauen	du
2	Rendern und erfassen: Screenshots, Frame-Tafeln, Bewegungsspuren	Skripte
3	Mechanische Selbstkontrolle: Es rendert, nichts ist leer, keine Laufzeitfehler	du
4	Ein codefreies Überprüfungspaket schnüren	Skript
5	Fragen, auf welchem Modell der Kritiker läuft, sofern die Plattform es erlaubt (einmalig)	du, dann der Benutzer
6	Kritiker überprüft das Paket	frischer Subagent
7	Gate validiert die Überprüfung und entscheidet	Skript
8	Jeden Muss-beheben-Befund beantworten, dann zurück zu Schritt 2	du
9	Das Urteil des Kritikers melden, nicht deine Meinung	du

Standardbegrenzung: 3 Kritikerrunden.

0. Die Aufgabenstellung sichern

node <skill>/scripts/judge.mjs init --brief-file request.txt --kind frontend,motion

Verwende --brief "..." für Inline-Text oder --brief-file - zum Lesen von der Standardeingabe.

• Wörtlich. Speichere die Nachricht des Benutzers genau so, wie sie geschrieben wurde: Tippfehler, Groß-/Kleinschreibung, alles. Paraphrasiere, fasse zusammen oder „klärstelle“ sie niemals. Der Kritiker beurteilt anhand ihrer Worte, nicht anhand deiner Interpretation.
• Spätere Klarstellungen des Benutzers werden mit judge.mjs brief --add "<ihre genauen Worte>" hinzugefügt. Deine eigenen Annahmen kommen niemals hinein.
• Referenzbilder, die der Benutzer dir gegeben hat: Füge --ref mock.png hinzu (wiederholbar), damit der Kritiker sie damit vergleichen kann.
• --kind wählt die Bewertungskriterien: frontend für Seiten und UI, motion für jede Animation, video für Clips und Schnitte. Lasse es weg, um automatisch aus den Aufnahmen zu erkennen.
• --critic-model, wenn der Benutzer bereits eines genannt hat.

Dies erstellt .frame-judge/ (es ignoriert sich selbst in .git) mit brief.md und ledger.json. Das Ledger überlebt Kontextkomprimierung. Wenn du den Überblick verlierst, führe judge.mjs status aus.

0b. Nach dem Unslop-Modus fragen (vor dem Bauen)

Frage den Benutzer einmal in diesen Worten:

Möchtest du es unsloppy? (experimentell: kann die Qualität verringern und wird mehr Tokens verbrauchen)

In Claude Code frage mit AskUserQuestion, in derselben Eingabeaufforderung wie die Frage nach dem Kritiker-Modell aus Schritt 5. Andernorts frage im Chat. Überspringe es, wenn der Benutzer es bereits gesagt hat.

• Nein: Mach weiter. Unslop ist standardmäßig deaktiviert.
• Ja:
  1. Führe judge.mjs set unslop on aus, dann judge.mjs scout. Es gibt eine Nachricht für einen Slop-Scout aus: einen frischen Subagenten mit Websuche, der herausfindet, wie KI diese Art von Anfrage typischerweise falsch macht.
  2. Sende dem Scout diese Nachricht und nichts anderes. Dieselben Regeln wie für den Kritiker: frischer Agent, kein Fork, nichts hinzugefügt. Verwende das Modell des Kritikers, wenn eines gesetzt ist.
  3. Speichere seine Antwort, dann führe judge.mjs avoid --file <reply> aus. Dies lehnt Listen ohne echte Quellen ab.
• Keine Websuche verfügbar: Teile dem Benutzer mit, dass unslop hier nicht ausgeführt werden kann, und fahre ohne fort.

Die Vermeidungsliste landet in .frame-judge/avoid.md und wird in jedes Überprüfungspaket aufgenommen, sodass der Kritiker die Arbeit auch dagegen prüft.

„Experimentell“, weil das Abweichen von den Standardeinstellungen einen Build in seltsame Richtungen treiben kann und der Scout einen zusätzlichen Agentenlauf mit Websuchen kostet.

1. Bauen

Wenn unslop eingeschaltet ist, lies zuerst .frame-judge/avoid.md.

• Entwerfe um jedes Muster herum. Kehre es nicht einfach um: Das Ziel ist Arbeit, die zur Aufgabenstellung passt, nicht Arbeit, die lediglich anders ist.
• Alles, was der Benutzer explizit verlangt hat, hat Vorrang vor der Liste.

Lies vor dem Bauen den Abschnitt von references/craft.md für dein Medium, einmal pro Sitzung. Er behandelt, was Kritiker am häufigsten beanstanden: Abstände, Typografie, KI-Vorlagenmerkmale, Easing, Gehzyklen, Videotiming.

Für alles, was animiert ist, mache Zeit zu einer expliziten Eingabe: einer Zeitleiste, die du durchsuchen kannst, oder einem window.frameJudgeSeek(ms)-Hook. Das macht die Erfassung frame-genau und verwandelt HTML kostenlos in Video.

2. Rendern und erfassen

Seiten und UI (benötigt Playwright; Einrichtung in references/capture.md):

node <skill>/scripts/capture-page.mjs http://localhost:5173 --out .frame-judge/cap/page

Standardmäßig Desktop 1440×900, Tablet 768×1024 und Mobil 390×844, Bildschirm für Bildschirm erfasst. Optionen:

• --actions states.json für Hover-, Menü- und Fehlerzustände
• --color-scheme dark
• --reduced-motion
• Lokale Dateien funktionieren ebenso wie URLs

Animation auf einer Seite. Dies ist frame-genau (falsche Uhr plus Web Animations Seeking) und kodiert zu MP4:

node <skill>/scripts/capture-page.mjs scene.html --out .frame-judge/cap/anim --animate 3000 --fps 30 --selector "#hero"

Jedes Video, einschließlich dieses MP4:

node <skill>/scripts/video-frames.mjs .frame-judge/cap/anim/animation.mp4 --out .frame-judge/cap/anim-views --as motion

Was du erhältst:

• Viewport-Ausschnitte anstelle eines einzigen riesigen Ganzseitenbildes, das zu Matsch herunterskaliert würde.
• Zustandsaufnahmen aus deiner Aktionsdatei.
• Eine mit Zeitstempeln versehene Kontaktseite.
• Filmstreifen: standardmäßig mit 12 fps beprobte Frames, plus Vollratenstreifen um jeden plötzlichen Sprung oder Stillstand, den das Skript erkennt (--motion-fps source gibt jeden Frame überall). Die Beprobung bedeutet, dass ein Ein-Frame-Fehler zwischen die Kacheln fallen kann, weshalb die Ereigniserkennung existiert.
• Bewegungsspuren: Was stillstehen soll, bleibt scharf, und was gleitet, verschmiert.
• Objektive Zahlen: Dauer, fps, schwarze oder eingefrorene Segmente, horizontaler Überlauf, defekte Bilder.

Erfasse, was der Benutzer erleben wird: jeden Viewport, den sie verwenden würden, die relevanten Zustände, die gesamte Animation. Der Kritiker kann nichts beanstanden, was du ihm nicht gezeigt hast. Die hässlichen Teile wegzulassen, ist genau das Schummeln, das dieses Skill verhindern soll.

3. Mechanische Selbstkontrolle

Bevor du eine Kritikerrunde aufwendest, überprüfe und behebe die binären Dinge:

• es rendert
• keine leeren oder schwarzen Frames
• nichts in builder_only in jedem capture.json (Konsolenfehler, fehlgeschlagene Anfragen)
• die richtige Dauer und Größe
• horizontal_overflow_px und broken_images sind null

Das ist die gesamte Liste. Du bekommst nicht das Recht zu entscheiden, dass es gut aussieht, und den Kritiker zu überspringen.

4. Paket schnüren

node <skill>/scripts/judge.mjs bundle .frame-judge/cap/page .frame-judge/cap/anim-views

Dies schreibt .frame-judge/round-N/bundle/. Es enthält nur visuelle Dateien (png, jpg, webp, gif, plus Video, wenn du --include-video übergibst) und diese Textdateien:

• brief.md, mit entfernten Codeblöcken
• die Bewertungskriterien
• CRITIC.md, die Anweisungen für den Kritiker
• manifest.json, mit zitierbaren Artefakt-IDs
• prior.json, ab Runde 2: offene Befunde ohne deine „behobenen“ Behauptungen, damit der Kritiker selbst prüft

Das Skript öffnet keine neue Runde, während Muss-beheben-Befunde unbeantwortet sind oder die Rundenhöchstgrenze überschritten ist. Es gibt die genaue Nachricht aus, die an den Kritiker gesendet werden soll.

Bildbudget: Strebe 20 Bilder oder weniger pro Runde an. Claude verschärft die Bildbegrenzungen pro Anfrage ab 20 Bildern. Jedes Bild kostet etwa ⌈w/28⌉×⌈h/28⌉ Tokens; eine 1440×900-Aufnahme kostet etwa 1,7k. Kontaktseiten und Filmstreifen packen 12 bis 16 Frames in ein Bild, also verlasse dich auf sie. --slices 3 kürzt lange Seiten.

5. Das Modell des Kritikers wählen (nur wo die Plattform es unterstützt)

Frage nur, wenn deine Plattform es dir erlaubt, das Modell eines Subagenten zu wählen, und nur einmal, vor Runde 1. Überspringe es, wenn der Benutzer bereits eines genannt hat. Speichere die Antwort mit judge.mjs set critic-model <alias> und verwende es jede Runde erneut.

Plattform	Fragen?	Wie
Claude Code, Claude Apps	Ja	AskUserQuestion, in derselben Eingabeaufforderung wie die Unslop-Frage: Sonnet (ausgewogen, empfohlen), Opus (schärfstes Auge, meiste Quote), Haiku (billigste, übersieht subtile Probleme), Gleich wie ich
Codex App, Codex CLI	Ja	Im Chat fragen, dann die Wahl beim Erzeugen des Kritikers übergeben
Antigravity	Nein	Es gibt keine Pro-Spawn-Modellwahl. Der Kritiker läuft mit der Einstellung seiner Agentendatei; teile dem Benutzer das mit.
Alles andere	Nein	Es sei denn, es unterstützt eindeutig Pro-Subagenten-Modelle. Verwende den Standard und teile dem Benutzer mit, welches Modell die Arbeit überprüft hat.

Wenn du fragst, sei direkt bezüglich des Kompromisses. Ein schwächerer Kritiker ist billiger, halluziniert aber mehr Mängel und übersieht subtile. Das Gate fängt falsche Beweise; es kann keinen schlechten Geschmack auffangen.

Genaue Syntax pro Plattform: references/platforms.md.

6. Den Kritiker ausführen

Verwende einen frischen Kritiker für jede Runde, damit er keine Erinnerung außerhalb von prior.json hat und kein Interesse an seinen früheren Aufrufen hat. Sende ihm die Nachricht, die bundle ausgegeben hat, und nichts anderes:

Du bist der Rahmenkritiker. Dein Paket ist <absoluter Pfad>. Lies <absoluter Pfad>/CRITIC.md und befolge es genau. Öffne nichts außerhalb dieses Ordners. Antworte nur mit dem Überprüfungs-JSON.

• Füge nichts hinzu. Keine Zusammenfassung dessen, was du gebaut hast, kein „konzentriere dich auf die Kopfzeile“, kein „ich habe die Beine repariert“. Deine Meinung ist die eine Eingabe, die der Kritiker niemals bekommen darf. Wenn der Benutzer möchte, dass etwas überprüft wird, steht es bereits in der Aufgabenstellung, in seinen Worten.
• Keine Forks. Führe den Kritiker niemals als Fork oder irgendetwas anderes aus, das Kontext erbt. Es würde deine gesamte Konversation sehen, einschließlich Code.
• Bevorzuge den installierten Agenten. Verwende frame-critic, falls vorhanden, da es auf das Lesen von Dateien beschränkt ist. Sein Name ist frame-judge:frame-critic, wenn das Skill als Claude Code Plugin kam, und frame_critic in Codex. Verwende andernfalls einen Allzweck-Subagenten mit derselben Nachricht.
• Claude Code: Führe die Sandbox aus, wenn möglich. Wenn das claude CLI im PATH ist, führe node <skill>/scripts/critic-sandbox.mjs aus, anstatt einen Subagenten zu spawnen. Es führt den Kritiker als separaten kopflosen Prozess auf einer privaten Kopie des Pakets aus. Dieser Prozess hat nur das Lese-Werkzeug, plus einen Hook, der jedes Lesen außerhalb der Kopie blockiert, und das Skript steuert die Überprüfung selbst (überspringe Schritt 7). Dies ist der einzige Pfad, bei dem Code-Blindheit erzwungen und nicht nur angefordert wird.
• Überall sonst: Verwende den In-Session-Subagenten, und Code-Blindheit beruht auf den Anweisungen des Kritikers. Auf Claude Code fängt das Transkript-Audit in Schritt 7 immer noch einen Kritiker, der heimlich gespickt hat. In Codex, Antigravity und Cursor überprüft es niemand, also sage das in deinem Bericht.

Speichere die Antwort unberührt in .frame-judge/round-N/review.json.

7. Gate

node <skill>/scripts/judge.mjs gate --review .frame-judge/round-N/review.json --reviewer subagent --transcript auto

Auf Claude Code findet --transcript auto das Transkript des Kritiker-Subagenten, sodass das Gate die Bilder zählt, die es wirklich geöffnet hat (nicht die, die es behauptet) und die Überprüfung für ungültig erklärt, wenn es irgendetwas außerhalb des Pakets berührt hat. Andernorts lasse das Flag weg; die Abdeckung wird dann selbst gemeldet, und der Bericht sagt das. (critic-sandbox.mjs übergibt sein eigenes Transkript automatisch.)

Das Gate entscheidet, nicht die Laune des Kritikers und nicht du. Es:

• Lehnt Befunde ab, die Artefakt-IDs zitieren, die nicht existieren oder die der Kritiker nie geöffnet hat, Befunde ohne Beweise, Zitate aus der Aufgabenstellung, die nicht in der Aufgabenstellung stehen, und schlechte Schweregrad- oder Konfidenzwerte.
• Überprüft die Abdeckung: Ein Bestehen zählt nur, wenn der Kritiker jedes Bild geöffnet hat, überprüft anhand seines Transkripts, wo eines existiert, andernfalls anhand seiner eigenen geöffnet-Liste.
• Überprüft die Isolation: Mit einem Transkript macht jedes Lesen außerhalb des Pakets die Überprüfung ungültig (RERUN_CRITIC).
• Sortiert den Rest:
  • muss-beheben: Blocker oder schwerwiegend, Konfidenz 0,6 oder höher
  • überprüfen: Blocker oder schwerwiegend unter 0,6. Näher erfassen; nicht blind beheben.
  • polieren: geringfügig
  • ignoriert: Kleinigkeiten
• Überprüft, dass CRITIC.md und die Bewertungskriterien nicht bearbeitet wurden, damit niemand den Richter milder gestimmt hat.
• Aktualisiert das Ledger und gibt eine Entscheidung aus:

Entscheidung	Bedeutung	Du
PASS	Kein Muss-beheben mehr übrig, nichts aus der Aufgabenstellung fehlt	Bericht (Schritt 9)
SELF_PASS	Gleiches, aber aus einem Selbstprüfungs-Fallback	Bericht, und sage, dass es nicht unabhängig war
REVISE	Muss-beheben-Elemente vorhanden	Schritt 8, dann eine neue Runde
RETHINK	Kritiker sagt, der Ansatz ist von Grund auf falsch	Sage es dem Benutzer, bevor du neu baust
STOP_MAX_ROUNDS	Höchstgrenze erreicht, immer noch fehlschlagend	Berichte, was offen ist, frage, ob fortgesetzt werden soll
STOP_PLATEAU	Diese Runde hat nichts gelöst	Höre auf, mich im Kreis zu drehen. Berichte, frage
RERUN_CRITIC	Überprüfung unbrauchbar (kein JSON, meist erfundene Beweise), ein Bestehen von einem Kritiker, der Bilder übersprungen hat, oder ein Kritiker, der außerhalb seines Pakets gelesen hat	Führe einen frischen Kritiker auf demselben Paket aus
STOP_CRITIC_UNRELIABLE	Zweite unbrauchbare Überprüfung	Schlage ein stärkeres Kritiker-Modell oder einen Fallback vor

8. Überarbeiten

Arbeite die Muss-beheben-Elemente der Reihe nach nach ID ab, zuerst Blocker. Beantworte jedes vor der nächsten Runde:

node <skill>/scripts/judge.mjs respond R1-F2 fixed "contact foot planted for 4 frames"
node <skill>/scripts/judge.mjs respond R1-F4 disputed "gutters are equal on both sides" --evidence crop.png
node <skill>/scripts/judge.mjs respond R1-F6 wont-fix "user asked for this gradient" --quote "purple to blue gradient"

• disputed benötigt visuelle Beweise, wie einen Ausschnitt oder zusätzliche Frames. Es kommt in das nächste Paket und der nächste Kritiker entscheidet darüber. „Das CSS sagt 16px“ ist kein Beweis; Pixel sind es.
• wont-fix benötigt ein wörtliches Zitat aus der Aufgabenstellung, das die Behebung verletzen würde.
• Behebe Ursachen, nicht Aufnahmen. Ändere niemals die Aufnahme, um einem Befund auszuweichen: kein Zuschneiden des defekten Fußbereichs, kein Weglassen des mobilen Viewports, kein Kürzen des Clips.
• Überprüfungselemente und Kritiker-Anfragen: Erfasse diese Stelle genauer (eine Aktion mit clip, ein dichteres --motion-Fenster), damit der nächste Kritiker sie bestätigen oder widerlegen kann.
• Verschlechtere nicht, was der Kritiker unter keep aufgeführt hat.
• …

[längere Auslassung – Rest des Dokuments folgt analog übersetzt]