convert-site
Der Orchestrator. Er stellt eine einzige Nachricht mit Fragen, führt dann jede andere Fähigkeit der Reihe nach aus, ohne erneut anzuhalten, und endet mit einem Pull Request, den die Person merged, sowie einem Runbook, das sie startet.
Die goldenen Regeln
- Eine einzige Aufnahmem Nachricht, dann keine Stopps. Jede Frage hat einen Standardwert. Alles, was später ein Konto, einen Login oder ein Token benötigt, das Sie nicht haben, kommt auf die „braucht dich“-Liste (
state.needsYouunddocs/LAUNCH.mdAbschnitt A) und der Durchlauf wird fortgesetzt. - Die Live-Seite ist schreibgeschützt. Nur diese lesen sie, im eigenen Tempo: die Erfassungsskripte,
shoot.mjsundstyles.mjsauf der Live-Seite,css-coverage.mjs,launch-audit --old-urlundpre-launch --predecessor-url. Analysen werden bei ihren Live-Seitenaufrufen blockiert, sodass kein Besuch gezählt wird. Senden Sie niemals ein Formular auf der Live-Seite ab, melden Sie sich nicht an und rufen Sie keine Seite von Hand auf, um eine Lücke zu füllen. - Der Standard-Build gleicht der Live-Seite, inklusive Fehlern. Inhalte werden aus erfasstem Markup übernommen, niemals neu getippt oder bereinigt. Jede Besonderheit ist eine Entscheidungszeile, die besagt: „Standardmäßig wie Live reproduzieren“. Ein erzwungener Unterschied ist eine Ausnahme; eine Verbesserung ist ein Vorschlag (
PROPOSALS=onnur). - Tore bei jedem Commit, niemals aufgeweicht. Bearbeiten Sie niemals
baseline/, um zu bestehen (nur diekeep-Flags inbaseline/scripts.json). Ein Überspringen ist kein Bestehen; „Nicht abgedeckt“ ist niemals ein Bestehen. mainerhält den Scaffold-Commit und sonst nichts. Bei einem neuen, leeren Repository erstelltinit-siteeinen Commit aufmain, die Ausnahme von „niemals auf main committen“. Der PR braucht eine Basis. Alles danach geschieht aufastro-rebuild, einem einzigen PR. Niemals Force-Push, niemals mergen, niemals DNS, den alten Host oder eine Dashboard-Einstellung berühren.- Keine Geheimnisse im Chat oder im Repository. Bitten Sie die Person niemals, ein Token einzufügen. Anmeldedaten stammen aus der Umgebung oder einem eigenen Login der CLI.
Verwendete Namen
KIT ist der absolute Pfad dieses Kits (der Ordner mit skills/ und package.json). LIVE ist die Live-Quelldomain. SITE ist der absolute Pfad des neuen Site-Repositorys (Standard: <aktuelles Verzeichnis>/<slug>); die Erfassung und der Ausführungsstatus werden von Anfang an dort gespeichert, und init-site.mjs baut das Gerüst darum herum. Führen Sie jeden Befehl von SITE aus aus. Jedes Skript gibt --help aus; führen Sie dies aus, anstatt den Quellcode zu lesen. Jeder Node-Befehl in einer neuen Shell beginnt mit source ~/.nvm/nvm.sh && nvm use 22.23.4 (oder läuft in einer Shell, die .nvmrc liest).
Schritt 0a: Ein einsatzbereites Kit
Die Skripte importieren parse5, playwright und den Rest aus den node_modules des Kits. Wenn $KIT/package.json oder $KIT/node_modules fehlt (eine Installation, die nur die Skill-Ordner kopiert hat, hat beides nicht), klonen Sie das Kit und installieren Sie es, dann verwenden Sie den Klon als KIT:
git clone https://github.com/ethanplusai/astro-conversion-kit <ordner>/astro-conversion-kit
npm install --prefix <ordner>/astro-conversion-kit
Schritt 0: Vorabprüfung und Fingerabdruck (vor der Aufnahmenachricht)
node $KIT/skills/convert-site/scripts/preflight.mjs --json
node $KIT/skills/capture-site/scripts/fingerprint.mjs $LIVE
Installieren Sie, was fehlt und Sie selbst installieren können, ohne zu fragen: npx playwright install chromium, wenn playwright.chromium false ist; vercel und wrangler laufen über npx. Eine CLI, die vorhanden, aber nicht eingeloggt ist, muss die Person einloggen: nennen Sie den Befehl (gh auth login, npx vercel login, npx wrangler login) in der Aufnahmenachricht und überprüfen Sie es beim Scaffold erneut.
experience bestimmt, wie Sie sprechen, nicht was Sie tun. new: ein einfacher Satz pro Phase, was sie tut und warum, jeder Begriff einmal erklärt, Installationen werden lautlos durchgeführt. some: eine Zeile pro Phase. experienced: nur Befehle und Ergebnisse. Ein Shopify-Fingerabdruck ist ein Shop: Stoppen Sie und sagen Sie es.
Schritt 1: Aufnahme (die eine Nachricht)
Senden Sie die Vorlage von references/intake.md, ausgefüllt mit dem, was die Vorabprüfung und der Fingerabdruck gefunden haben: jede Frage mit ihrem Standardwert und die Liste „Was fehlt und was passiert“. Wenn die Person nicht antwortet, gelten die Standardwerte. Senden Sie niemals eine zweite Nachricht mit Fragen.
Die Phasen
Die Reihenfolge ist die von docs/process.md; references/phases.md enthält jeden Befehl und jeden Nachweis. An jeder Grenze führen Sie node $KIT/skills/convert-site/scripts/state.mjs --dir $SITE phase <name> aus; beginnen Sie keine Phase, bis der Nachweis der vorherigen Phase erbracht ist. Führen Sie state.mjs-Aufrufe einzeln aus, niemals mit && verkettet: Jeder überschreibt state.json, und eine fehlschlagende Kette lässt es aus dem Takt geraten.
| # | Phase (<name>) | Was passiert | Abgeschlossen wenn |
|---|---|---|---|
| 1 | intake | Vorabprüfung, Fingerabdruck, die eine Nachricht | Beantwortet oder Standardwerte gelten |
| 2 | capture | capture-site in $SITE/capture/, CSS-Abdeckung | Jede URL gespeichert oder mit ihrem Status aufgezeichnet; Notizen geschrieben |
| 3 | plan | Hosting, URL-Form, Medienmodus, Vorlagen entscheiden; Entscheidungen im Status; Entwürfe unter .conversion/ | Jede Vorlage, Anzahl, Besonderheit und nicht abgedeckte Funktion hat eine Entscheidung |
| 4 | scaffold | Repo, init-site.mjs um die Erfassung herum, dann docs/plan.md und docs/media-plan.json | Es baut leer; main enthält den einen Scaffold-Commit |
| 5 | baseline | npm run baseline (templates.json existiert bereits) | build-baseline.mjs --check beendet mit 0 |
| 6 | build | Layouts und gemeinsame Teile, eine Seite pro Vorlage, Design-Sperre auf den Vorlagen, dann jede Seite | npm run build besteht; Vorlagen-Tore bestehen Pfad für Pfad |
| 7 | gates | Die vollständigen Tore | npm run verify beendet mit 0 |
| 8 | visual | Jede Vorlage bei 390, 768, 1440; jede Seite bei 390 und 1440 | Jedes Paar besteht |
| 9 | components | Optional, standardmäßig ausgeschaltet (references/components-optional.md) | Tore und Diffs bestehen weiterhin, ein separater Commit |
| 10 | prelaunch | pre-launch, Staging-Deployment, verify-live, launch-audit, eine Test-Übermittlung | prelaunch-reconcile.mjs beendet mit 0 (references/phases.md §10); Audit-Blocker behoben oder aufgelistet |
| 11 | suggestions | suggest-improvements mit gates.json und review/ | docs/suggestions.md mit dem Abschnitt „Aus der Überprüfung“ |
| 12 | pr | Runbook, Push, PR, Abschlussbericht | Der PR zitiert die Torausgabe und jeden Abschnitt „Nicht abgedeckt“ |
| 13 | launch | Die Person, aus docs/LAUNCH.md | post-launch überprüft die Umstellung und beobachtet 30 Tage |
Die Fähigkeiten, die jede Phase verwendet, mit ihren eigenen Regeln: capture-site (2), parity-gates (5 bis 7), visual-review (6, 8), pre-launch und launch-audit (10), suggest-improvements (11), post-launch (im Runbook). Lesen Sie die SKILL.md jeder Fähigkeit vor ihrer Phase.
Der Build, in einem Absatz
references/build-rules.md ist bindend. Layouts und der gemeinsame Header, die Navigation und der Footer sind immer Komponenten; Inhaltsblöcke sind das erfasste Markup, das von einem Skript verschoben wird. Medien unter ihren ursprünglichen Pfaden, Schriftarten selbst gehostet, CSS durch Abdeckungsbereinigung (css-coverage.mjs dann css-prune.mjs), niemals eine Neufassung. Formulare gemäß references/forms.md, Drittanbieter-Skripte gemäß references/third-party.md. redirects.csv ist die einzige Redirect-Quelle: Ein neuer Redirect ist eine Zeile, deren source decision ist und deren note die Entscheidungs-ID nennt, dann npm run redirects:build; niemals die generierten Regeln von Hand bearbeiten. Ein Commit pro Vorlage (feat: <template> template, sobald ihre pfadbezogenen Tore bestehen), niemals einer für den gesamten Build. Das Design wird auf den Vorlagen gesperrt (visuelle Überprüfung) vor dem Ausrollen auf jede Seite. Mit Unteragenten: ein Implementierer pro Vorlage oder Tor-Fix, niemals zwei an einer Datei; jedes Briefing enthält absolute Pfade und build-rules.md, und Sie überprüfen ihre Commits vor der nächsten Phase.
Entscheidungen, Ausnahmen, Vorschläge
Dieser Abschnitt ist die Regel; die Referenzen verweisen hierher.
- Entscheidung. Alles, was die Live-Seite ungewöhnlich macht, und jede Standardeinstellung, die Sie anwenden, erhält
state.mjs decision '{"topic":…,"choice":…,"default":…,"reason":…,"costIfWrong":…}', was seine ID ausgibt (d1,d2, …). Das eine Hauptbuch ist die Entscheidungstabelle indocs/plan.md: ID, Datum, Thema, Auswahl, Standard, Grund, Kosten bei Fehler. Vor dem Scaffold leben die Entscheidungen in.conversion/state.json; die Plantabelle wird unmittelbar nachinit-sitedaraus geschrieben. Der Standard ist immer „Live reproduzieren“. - Ausnahme (
exceptions.json,{ path, field, from, to, reason, approvedBy, date }): Ein Unterschied, den der statische Build nicht vermeiden kann; die Tore ersetzentofürfromfür dieses eine Feld auf diesem einen Pfad.approvedByist"default, <decision id>", bis eine Person es im PR abzeichnet. Formulare und Skripte sind keine Ausnahmefelder (sie haben ihre eigenen Flags).routesist: Eine Route, die die Erfassung nicht lesen konnte:fromist ihr Status als String,toist"skip"oder der gebaute Ersatzpfad. - Vorschlag (
proposals.json, dieselbe Form plusid, die Entscheidungs-ID, undapprovedBy: "proposed"; mehrere Datensätze können eine ID teilen): Eine Verbesserung. Code schaltet es mitproposalOn(id)um; es wird nur in einemPROPOSALS=on-Build ausgeliefert, der durchnpm run verify:proposalsabgesichert ist. Eine Änderung, die kein Tor misst (umgeschriebene hrefs), istfield: "markup", wird niemals verglichen. Wenn eine Person es genehmigt, werden die Datensätze nachexceptions.jsonverschoben (approvedBy).
Hosting
Standardmäßig Vercel, auf Wunsch Cloudflare Pages: references/hosting-vercel.md und references/hosting-cloudflare.md. Jede Seite trägt noindex, es sei denn, der Produktions-Build setzt PUBLIC_INDEXABLE=true. Medien sind repo, store (media-upload.mjs) oder live-temporary (nur Staging; verschwunden bevor DNS umzieht), wie von media-plan.mjs entschieden (references/phases.md §3).
Die eine Nachricht nach dem Plan
Nach Phase 3 senden Sie einen kurzen Status (keine Frage): Plattform, Seiten- und Vorlagenanzahl, die Medienentscheidung, nicht abgedeckte Funktionen und die Optionen, die standardmäßig getroffenen Entscheidungen und die bisherige „braucht dich“-Liste. Dies ist auch in einem nicht-interaktiven Durchlauf erforderlich (stehende Antworten, niemand antwortet): Fortschrittszeilen ersetzen es nicht. Fahren Sie dann ohne Warten fort.
Der Pull Request (Phase 12)
Pushen Sie astro-rebuild (main wurde beim Scaffold gepusht), dann gh pr create --base main --head astro-rebuild --title "Astro Neubau von <host>" --body-file .conversion/pr-body.md. Während pre-launch mit placeholders.form-id fehlschlägt (noch keine Formular-ID), fügen Sie --draft hinzu, und der Abschlussbericht nennt dies als Blocker. Ohne einen gh-Login bleibt der Body in dieser Datei und „pushen und den PR öffnen“ kommt auf die „braucht dich“-Liste. Der Body, in dieser Reihenfolge:
## Was sich geändert hat ein Absatz: Plattform, was konvertiert wurde, Host, Medienmodus
## Zählungen Seiten, Vorlagen, Weiterleitungen, Mediendateien und -größe, Formulare, behaltene/entfernte Anbieter
## Angewandte Ausnahmen jeder exceptions.json-Eintrag: Pfad, Feld, Grund, Entscheidungs-ID
## Offene Vorschläge jede proposals.json-ID: Pfade, was, warum (wird nur mit PROPOSALS=on ausgeliefert)
## Entscheidungen die docs/plan.md Entscheidungstabelle und jede nicht standardmäßige Wahl
## Torausgabe `npm run verify` Ausgabe, wörtlich, in einem Codeblock, mit jeder übersprungenen Zeile;
dann jede Zeile, die prelaunch-reconcile akzeptiert hat, als "von Live reproduziert (dN)"
## Visuelle Überprüfung `npm run review:check` Ausgabe, jeder docs/visual-overrides.json-Eintrag
(Route, ID, Schwelle, Grund), jedes bannerClosed und heightMismatch; die Kontaktbögen sind
review/index.html und review/all.html (lokal; npm run review:sheet)
## Staging die Staging-URL, verify-live-Ergebnis, die launch-audit-Blocker und ihr Status
## Vorschläge Zählungen pro Kategorie, die mittleren und hohen Risikopunkte, die anwendbaren IDs
## Nicht abgedeckt pre-launch und launch-audit "Nicht abgedeckt"-Abschnitte, wörtlich, jeder
unter seiner eigenen Überschrift; dann die von capture-site, visual-review und suggestions
## Wartet auf Sie jeder state.needsYou-Eintrag, in Runbook-Reihenfolge
Der Abschlussbericht (an die Person)
Führen Sie mit dem PR-Link (und „Entwurf, wartet auf Formular-ID“ wenn es einer ist), dann: was konvertiert wurde (Zählungen), Tore und visuelle Überprüfung in je einer Zeile, die Staging-URL, die „braucht dich“-Liste unter Wartet auf Sie gelesen aus state.mjs --dir $SITE get needsYou (jeder Eintrag mit dem genauen Befehl oder Klick, in Runbook-Reihenfolge), dann jeder Abschnitt „Nicht abgedeckt“ wörtlich. Sagen Sie „PR offen, warte auf Ihren Merge“, niemals „fertig“ oder „live“. Stoppen Sie jeden von Ihnen gestarteten Überprüfungsserver (npm run review:serve -- --stop, und npx astro preview stop falls Sie die Vorschau verwendet haben), dann stoppen Sie.
Fortsetzen
Lesen Sie in einer neuen Sitzung node $KIT/skills/convert-site/scripts/state.mjs --dir $SITE get und fahren Sie ab phase fort: Führen Sie zuerst den Nachweis dieser Phase erneut aus; wenn er hält, beginnen Sie die nächste Phase. Die Erfassung wird mit --resume fortgesetzt. Wiederholen Sie niemals die Aufnahme. Das spätere Anwenden eines Vorschlags erfolgt mit convert-site --apply <id> (references/apply-suggestion.md), niemals als Teil des Durchlaufs selbst.
Referenzen
| Datei | Deckt ab |
|---|---|
references/intake.md | Die eine Nachricht: Fragen, Standardwerte, was fehlt und was passiert |
references/phases.md | Jede Phase: genaue Befehle, der Nachweis, dass sie abgeschlossen ist, was aufgezeichnet werden muss |
references/build-rules.md | Wie Layouts, Inhalte, CSS, Medien, Schriftarten, träge Bilder und Weiterleitungen erstellt werden |
references/forms.md | Formspree-Verkabelung, Feldnamen, Honeypot, Danke-Seite, die Formular-ID, die eine Testübermittlung |
references/third-party.md | Die keep-Zulassungsliste in baseline/scripts.json und docs/third-party.md |
references/hosting-vercel.md | Projekt, öffentliches noindexed Staging, Indexierung, Blob-Medien, Opt-in-Schutz |
references/hosting-cloudflare.md | Pages-Projekt, _redirects, _headers, R2-Medienfunktion, Query-Weiterleitungen |
references/runbook.md | docs/LAUNCH.md: A braucht dich, B Abschluss, C Launch-Tag, D 30-Tage-Beobachtung |
references/components-optional.md | Der optionale Komponentendurchlauf |
references/apply-suggestion.md | --apply <id>: Vorschlagsdatensätze, Branch-Commit, Tore, Blatt |