vicunav/vicunav-transform-claude-to-gutenberg

Claude Code in Gutenberg FSE transformieren

Ziel

Das genehmigte Claude-Code-Projekt in eine native und wartbare WordPress-Seite umwandeln. Das vereinbarte Design, den Inhalt und das Verhalten beibehalten, ohne die Architektur des Frontend-Prototyps mitzuschleppen, wenn WordPress bereits eine über Blöcke editierbare Lösung bietet.

Das Quellprojekt als visuelle und funktionale Spezifikation behandeln. Nur im autorisierten LocalWP arbeiten. Weder die Produktion ändern noch Inhalte, Anpassungen des Site Editors oder lokale Daten ohne explizite Genehmigung löschen.

Minimalen Kontext sammeln

Vor dem Bearbeiten bestätigen oder ermitteln:

• Pfad des exportierten oder verfeinerten Projekts in Claude Code;
• Pfad der LocalWP-Seite und des Ziel-Themes;
• Commit, Build oder exakter Zustand, der das genehmigte Design darstellt;
• Enthaltene Seiten, Breakpoints, Zustände und Interaktionen;
• Tatsächliche WordPress- und PHP-Version der lokalen Seite;
• ob das Ziel 1:1-Parität, eine genehmigte Optimierung oder ein Redesign ist;
• Inhalt und Integrationen, die in WordPress editierbar sein müssen;
• Einschränkungen zu Plugins, Custom-Blöcken, Schriftarten und Asset-Lizenzen.

Fehlt eine Entscheidung, die Inhalt, Architektur, Funktionalität oder Design ändert, anhalten und nachfragen. Fehlt ein aus dem Dateisystem, Frontend oder der lokalen Seite wiederherstellbarer Datenpunkt, diesen inspizieren und die Annahme dokumentieren.

Wiederverwendbare Grundlagen laden

Die je nach Phase installierten offiziellen Skills anwenden:

• wp-project-triage: das WordPress-Projekt und seine Toolchain klassifizieren;
• wp-block-themes: theme.json, Templates, Parts, Patterns und FSE-Stile implementieren;
• wp-block-development: nur verwenden, wenn eine Interaktion einen Custom-Block erfordert;
• wp-wpcli-and-ops: Inhalte und Optionen mit WP-CLI inspizieren oder ändern;
• unlazy (falls installiert): Abschlussdisziplin für eine Migration mit erheblichem Umfang (mehr als eine Seite oder Arbeiten, die als abgeschlossen gemeldet werden sollen, ohne ständige Aufsicht). Siehe „Jede Einheit mit Gate-Disziplin abschließen“ weiter unten.

Zuerst die Zielversion prüfen. Wenn ein offizielles Skill auf eine neuere WordPress-Version als die von LocalWP verweist, ausschließlich die kompatiblen APIs verwenden und die offizielle Dokumentation zu Rate ziehen, um Unterschiede aufzulösen.

Bei Bedarf eigene Ressourcen lesen:

• source-contract.md: vor dem Einfrieren der Baseline und Festlegen des Migrationsvertrags;
• migration-manifest.md: vor dem Erfassen der Baseline oder dem Implementieren von Änderungen mit visuellen Auswirkungen;
• translation-map.md: vor der Entscheidung über die Gutenberg-Architektur und während der Übersetzung jeder Komponente;
• localwp.md: vor dem Bearbeiten der Seite oder ihrer Datenbank;
• qa-checklist.md: vor dem ersten sichtbaren Abschnitt und erneut, bevor die Arbeit als abgeschlossen erklärt wird;
• upstream.md: beim Aktualisieren, Auditieren oder Weiterverteilen der wiederverwendeten Grundlagen;
• templates/gates-fse-migration.md: beim Öffnen von $unlazy für eine Seite oder einen Abschnitt als initiales Ledger zum Kopieren und Ausfüllen, anstatt die Gates von Grund auf zu schreiben.

Den Ablauf ausführen

1. Lokale Anweisungen, Git-Status und direkt beteiligte Dokumentation beider Projekte lesen.
2. scripts/audit_source.mjs <quellpfad> ausführen und die Ergebnisse manuell prüfen. Den heuristischen Bericht nicht als architektonische Entscheidung behandeln.
3. Das Migrationsmanifest erstellen, alle erwarteten Kombinationen indizieren und scripts/validate_migration_manifest.mjs <manifestpfad> ausführen.
4. Das Frontend der Quelle in einer sauberen Umgebung starten und die Baseline für Desktop, Tablet und Mobilbildschirm erfassen, einschließlich relevanter interaktiver Zustände.
5. Den Migrationsvertrag erstellen: Seiten, Abschnitte, Texte, Assets, Tokens, Interaktionen, Datenquellen, Integrationen und Akzeptanzkriterien.
6. Wiederverwendbare Tokens von lokaler Geometrie trennen. Erstere in theme.json abbilden, Letztere durch Blöcke, Layouts und minimale semantische Klassen erhalten.
7. Die FSE-Architektur entwerfen: Templates, Template Parts, Patterns, Seiteninhalte und nur wenn nötig Custom-Blöcke oder Plugins.
8. Zuerst einen repräsentativen Abschnitt implementieren. Frontend und Site Editor vergleichen, bevor das Muster auf die restliche Seite ausgeweitet wird.
9. Seite für Seite und Abschnitt für Abschnitt migrieren. Das Quellprojekt während der gesamten Implementierung als Referenz sichtbar halten. Wenn $unlazy verfügbar ist, eine Einheit öffnen, indem templates/gates-fse-migration.md in ein eigenes GATES.md für diese Seite oder diesen Abschnitt kopiert wird, bevor sie implementiert wird – nicht danach.
10. Das Theme im LocalWP über den dokumentierten Projektablauf installieren oder aktivieren. Inhalte idempotent und unter Erhaltung des Vorhandenen erstellen oder aktualisieren.
11. scripts/validate_fse_theme.mjs <themepfad> ausführen und alle Fehler korrigieren. Die zutreffenden Warnungen überprüfen.
12. Die visuelle, strukturelle, redaktionelle, responsive, barrierefreie und leistungsbezogene Qualitätssicherung im Frontend und Site Editor abschließen.
13. Aufnahme, Vergleich und Gate ausführen mittels capture_visual_evidence.mjs, compare_visual_evidence.mjs und verify_visual_evidence.mjs; manuell nebeneinander und als Overlay prüfen. Für jede Seite mit mindestens einem full-bleed-Abschnitt zusätzlich scripts/verify_editor_frontend_parity.mjs ausführen (erfordert ein echtes Session-Cookie, generiert mit scripts/wp_auth_cookies.php, siehe translation-map.md) und PARIDAD_EDITOR_FRONTEND_OK verlangen: der visuelle Vergleich allein reicht für diese Art von Bug nicht aus, die in diesem Projekt bereits zweimal dokumentiert wurde. Wenn die Einheit ein GATES.md hat, node <unlazy-skill-verzeichnis>/scripts/gate-check.mjs --reverify GATES.md ausführen und ALL MET verlangen, bevor es weitergeht.
14. Nachweise, Einschränkungen, Rollback und nächste Arbeitseinheit übergeben. Wenn $unlazy verwendet wurde, die qualifizierten IDs der erfüllten, nicht erfüllten und aufgegebenen Gates einschließen; eine Einheit mit einem anhängigen oder aufgegebenen Gate nicht als abgeschlossen beschreiben.

Jede Einheit mit Gate-Disziplin abschließen ($unlazy)

Wenn unlazy installiert ist, diese als Abschluss-Disziplin-Schicht dieses Skills behandeln, nicht als Alternative: Dieses Skill entscheidet, was bei einer FSE-Migration zu überprüfen ist; unlazy zwingt dazu, diese Kriterien vor der Arbeit als ausführbare Befehle zu deklarieren und sie mit echten Beweisen erneut zu überprüfen, bevor die Arbeit als abgeschlossen gemeldet wird, anstatt sich auf einen visuellen „sieht gut aus“-Eindruck zu verlassen.

• Den solo-Modus von unlazy für eine Seite oder einen Abschnitt verwenden (ein GATES.md pro Einheit, kopiert aus templates/gates-fse-migration.md). Den orchestrierten Modus nur für eine komplette Seite mit vielen unabhängigen Unterseiten verwenden, wobei jede Unterseite ein Blatt im Depth Tree mit eigenem OWNS: (eigenen Template-/Pattern-Dateien) ist und ein Integrationszweig Cross-Navigation, gemeinsamen Header/Footer und das Fehlen von Regressionen zwischen den Seiten überprüft.
• Nicht jede triviale Korrektur in ein Gates-Ledger verwandeln. Die Disziplin für eine Seite, eine vollständige Seitenmigration oder jede Einheit vorbehalten, deren Kosten, wenn sie stillschweigend unvollständig bleibt, dies rechtfertigen (siehe das reale Beispiel: hartcodierter Inhalt in einem Template, der eine Seite leer und uneditierbar über mehrere Arbeitseinheiten hinweg hinterließ, bevor der Seitenbesitzer ihn manuell entdeckte).
• Das Gate für echten Inhalt (post_content nicht leer) an den tatsächlichen WP-CLI-Aufruf des Projekts anpassen; auf LocalWP ist dies fast nie der globale wp-Binärbefehl (siehe localwp.md).
• Ein manuelles Gate bleibt für das gültig, was kein Befehl gut messen kann (wahrnehmbare visuelle Treue, redaktionelle Überprüfung von Texten). Keine automatische Metrik erzwingen, nur um ein manuelles Gate zu vermeiden; der Vertrag dieses Skills verbietet bereits die Umwandlung einer Wahrnehmungsmetrik in eine automatische Genehmigung der Parität.
• Den optionalen Stop-Hook von unlazy nicht ohne explizite Aufforderung durch den Benutzer installieren; das Skill selbst verlangt dies.
• Die Arbeit durch das angemessene Modell-Level routen, sowohl im orchestrierten Modus von unlazy als auch bei der Seite-für-Seite-Migration dieses Skills: Ein mechanisches und gut abgegrenztes Blatt (direkte Übersetzung einer bereits auf einer anderen Seite gelösten Komponente, eine Klassenanpassung, eine bereits diagnostizierte punktuelle Korrektur) geht an ein leichteres Modell; ein Blatt, das Architektur-Urteilsvermögen erfordert (Block vs. Pattern vs. CPT entscheiden) oder eine visuelle Überprüfung, wird vom Modell der Sitzung behalten. Nicht für jede kleine Bearbeitung einen vollständigen Agenten verteilen, wenn das Bündeln in einem einzigen Durchlauf dasselbe Ergebnis mit weniger Koordination erzielt.

Nicht verhandelbare Verträge einhalten

• Core-Blöcke, Theme-Patterns und öffentliche WordPress-APIs bevorzugen.
• Nicht core/html als Abkürzung verwenden, um das HTML des Prototyps zu erhalten.
• theme.json als Quelle der Wahrheit für gemeinsame Tokens verwenden.
• Templates und Parts für die globale Struktur behalten; Seiteninhalte oder Patterns für die redaktionelle Zusammensetzung verwenden.
• Weder React, Tailwind noch die Laufzeitumgebung des Prototyps im WordPress-Frontend einführen, es sei denn, dies ist nachgewiesenermaßen erforderlich und genehmigt.
• Custom-Blöcke nur für Verhalten oder Bearbeitung erstellen, die Core-Blöcke nicht wartbar ausdrücken können.
• Geschäftslogik, Reservierungen, Bestellungen und Datenmodelle in Plugins ablegen, nicht im Theme.
• Schriftarten und Bilder lokal bereitstellen und deren Lizenz, Herkunft und Alternativtext erhalten.
• Frontend und Site Editor als obligatorische Oberflächen beibehalten.
• Keine visuelle Migration ohne gültiges Manifest und vollständige Matrix implementieren.
• Keine Wahrnehmungsmetrik in eine automatische Genehmigung der Parität umwandeln.
• Sich nicht auf versehentliche globale Stile in der Datenbank verlassen.
• prefers-reduced-motion, Tastaturbedienung, sichtbaren Fokus und WCAG 2.1 AA respektieren.
• Keine Inhalte, Pfade oder Funktionalitäten erfinden, um Lücken im Design zu schließen.

Das Kriterium der Restaurant-Demo anwenden

• Eine kleine und rein redaktionelle Speisekarte mit Blöcken und Patterns modellieren.
• Nur dann einen CPT wie vicu_menu_item vorschlagen, wenn die Speisekarte strukturierte Bearbeitung, Filter, Wiederverwendung oder echtes Wachstum benötigt; diesen in einem Plugin registrieren und sein Verhalten testen.
• Reservierungen, Bestellungen, Zahlungen, dynamische Öffnungszeiten und Verfügbarkeit als separate funktionale Integrationen behandeln. Diese nicht stillschweigend mit einem statischen Formular simulieren.
• Header, Footer, Buchungsaufrufe und Kontaktmodule über Parts oder Patterns wiederverwenden, synchronisiert mit der genehmigten Architektur.

In überprüfbaren Einheiten arbeiten

Eine Seite oder einen Abschnitt nur dann abschließen, wenn:

• der Inhalt, die Links und die Assets mit dem Vertrag übereinstimmen;
• das Markup gültig und seine Blöcke editierbar bleiben;
• Frontend und Editor die Stile korrekt darstellen;
• Desktop, Tablet und Mobilbildschirm gegen die Baseline verglichen wurden;
• die zutreffenden Hover-, Focus-, Active-, Loading- und Error-Zustände getestet wurden;
• keine Konsolenfehler, unerwarteten Remote-Ressourcen oder Abhängigkeiten vom Entwicklungsserver von Claude Code vorhanden sind;
• die Nachweise dem exakt getesteten Zustand entsprechen;
• die Kombination eine eindeutige Zeile im Manifest hat und nicht ausstehend ist.

Einen überprüfbaren Zustand übergeben

Melden:

• abgeschlossene Seiten und Abschnitte;
• betroffene Architektur und Dateien;
• Entscheidungen zu Core-Blöcken, Patterns, Custom-Blöcken und Plugins;
• ausgeführte Befehle und Prüfungen mit ihren Ergebnissen;
• URLs und Viewports, die für den Vergleich verwendet wurden;
• akzeptierte Unterschiede, verbleibende Risiken und Rollback;
• Pfad des validierten Manifests und Zusammenfassung seiner Beweismatrix.

Keine visuelle Parität behaupten, nur weil die Seite rendert oder das HTML denselben Text enthält. Parität erfordert visuellen Vergleich und Validierung der Editierbarkeit.

Beispiele für die Verwendung

Verwende $transform-claude-to-gutenberg, um dieses Claude-Code-Projekt zu auditieren und den Migrationsvertrag für die Startseite zur angegebenen LocalWP-Seite zu erstellen.

Verwende $transform-claude-to-gutenberg, um die Restaurant-Demo in ein 1:1 FSE-Block-Theme zu transformieren, unter Verwendung von Core-Blöcken und lokalen Assets.

Verwende $transform-claude-to-gutenberg, um das migrierte Theme zu überprüfen und aufzulisten, was daran hindert, es als editierbar und visuell gleichwertig zum genehmigten Prototyp zu betrachten.