jayabdulraman/setup-prototype-project

Setup Prototype Project (Prototyp-Projekt einrichten)

Baue eine funktionsfähige Web-App aus einer Idee und teile sie als Live-Link. Die Person gibt Richtung und Entscheidungen vor; du erledigst die technische Arbeit.

Der Stack

Ebene	Standard-Tool
Oberfläche (was Leute sehen und anklicken)	Next.js (App Router) + TypeScript + Tailwind + shadcn/ui (Basis-UI, neutrales Theme, Lucide-Icons, Sera-Stil) aus einem shadcn-Preset
Serverarbeit (geheime Schlüssel, externe APIs, AI-Aufrufe)	Next.js Server Actions
Daten	IndexedDB im Browser (Dexie). Supabase CLI für später installiert
Hosting und Teilen	Vercel
Einrichtung und Automatisierung	Offizielle CLIs (vercel, supabase, gh, shadcn) + Skripte dieser Fähigkeit

IndexedDB kommt zuerst: kein Konto, keine Schlüssel, funktioniert offline. Wechsle erst zu Supabase, wenn Daten zwischen Personen oder Geräten geteilt werden müssen, die App einen Login benötigt oder ein Server/geplanter Job die Daten lesen muss (siehe references/7-extend.md).

Immer die neueste stabile Version (keine Nachfrage nötig)

• Upgrades benötigen nie eine Genehmigung, mit einer Ausnahme: Tools, die von einem Drittanbieter-Homebrew-Tap stammen (z.B. supabase/tap). Frage, bevor du einem solchen Tap vertraust, und vor jedem Upgrade von dort während der Einrichtung, selbst wenn es zuvor genehmigt wurde.
• Andernfalls bringe jede CLI und jedes Paket auf die neueste stabile Version: npm i -g <cli>@latest, brew upgrade, winget upgrade, Node.js aktuelle LTS, und im Projekt npm outdated --json | jq -r 'keys[] + "@latest"' | xargs npm i. Sage in einer Zeile, was du upgegradet hast.
• Verwende niemals Canary-, Beta-, RC- oder next-Tags, außer die Person bittet darum. Pinne keine Versionen aus dem Gedächtnis oder aus diesen Dokumenten.
• Führe nach Upgrades die Prüfungen durch (lint, typecheck, build). Schlägt eine fehl, lies den Fehler, um das Paket zu finden, das ihn verursacht hat, downgrade nur dieses Paket auf die neueste Version des vorherigen Major (npm i -D <pkg>@^<major-1>), und führe erneut aus. Halte den Pin und den Grund in PROTOTYPE.md unter „Entscheidungen“ fest. Beispiel: TypeScript 7 hat das ESLint-TypeScript-Plugin kaputt gemacht, also pinne typescript@^6 und behalte alles andere auf dem neuesten Stand.
• Wenn du einen bestehenden Prototypen fortsetzt, führe vor neuer Arbeit denselben Upgrade-und-Prüf-Durchlauf durch.

Der Bau, Schritt für Schritt

Lies die Referenzdatei des Schritts, wenn du ihn erreichst. Lies sie nicht alle auf einmal.

Schritt	Person macht	Du machst	Referenz
1. Einrichtung	Wählt einen Ordner aus	Überprüfe Tools und deren Abhängigkeiten, installiere Fehlendes, rüste die App	references/1-setup.md
2. Verbinden	Genehmigt, meldet sich einmal im Browser an	Führe jeden CLI-Login aus, bestätige, dass es funktioniert hat, speichere App-Schlüssel im OS-Credential-Store	references/2-connect.md
3. Spezifikation	Formt die Idee	Stelle kurze Fragerunden, schreibe SPEC.md	references/3-spec.md
4. Bauen	Reagiert, lenkt um	Baue eine Funktion nach der anderen, zeige sie laufend	references/4-build.md
5. Testen	Probiert es aus	Führe Prüfungen durch, teste in einem echten Browser, behebe Fehler	references/5-test.md
6. Ausliefern	Genehmigt, teilt	Synchronisiere Schlüssel zu Vercel, deploye, übergebe den Link	references/6-ship.md
Jederzeit	Fragt nach einer neuen Fähigkeit	Finde die CLI oder Fähigkeit des Tools, frage nach Installation, verbinde es	references/7-extend.md

Ergebnis: eine funktionierende App auf localhost, dann ein Live-Link, den jeder öffnen kann.

Plattformen

	macOS	Windows	Linux
Shell für die Skripte dieser Fähigkeit	Terminal (zsh/bash)	Git Bash (kommt mit Git für Windows)	bash
Paketmanager für CLIs	Homebrew	winget (Scoop für Supabase)	Homebrew auf Linux oder npm
Wo App-Schlüssel leben	Keychain	Credential Manager	Secret Service (secret-tool); andernfalls eine git-ignorierte .env.local

• Führe Skripte mit bash <absoluter Pfad> aus. Unter Windows von PowerShell oder cmd aus kann bash WSL starten; verwende stattdessen & "$env:ProgramFiles\Git\bin\bash.exe" <script>. Claude Code unter Windows führt seine Shell bereits in Git Bash aus.
• WSL zählt als Linux, aber secrets.sh verwendet den Windows Credential Manager über powershell.exe, wenn er erreichbar ist.
• Cloud-synchronisierte Ordner (Dropbox, OneDrive, iCloud, Google Drive) sind in Ordnung. Führe in einem Dropbox-Ordner direkt nach dem Gerüst bash SKILL/scripts/ignore-sync.sh <projekt> aus, damit Dropbox node_modules, .next und Testausgaben überspringt.

Fortschrittsdatei

Jeder Prototyp hat eine PROTOTYPE.md im Stammverzeichnis (Vorlage: templates/PROTOTYPE.md). Sie enthält die Schritt-Checkliste, die Tool-Liste (Tool, Version, global oder Projekt-Installation), Schlüssel-Namen (niemals Werte), Entscheidungen und Links.

• Aktualisiere sie am Ende jedes Schritts und immer, wenn ein Tool hinzugefügt wird.
• Wenn du innerhalb eines bestehenden Prototypen aufgerufen wirst, lies zuerst PROTOTYPE.md und fahre beim ersten ungeprüften Schritt fort. Wenn die Person einen Schritt nennt („lass uns ausliefern“), gehe dorthin, führe aber zuerst die Prüfungen dieses Schritts durch.
• Alle Schritte sind abgehakt und die Person möchte etwas Neues: Füge es zu SPEC.md (Muss-haben + Abnahmeprüfungen) und zu den Funktionen in PROTOTYPE.md hinzu, führe references/7-extend.md aus, wenn ein neues Tool benötigt wird, und durchlaufe dann erneut Bauen → Testen → Ausliefern für diese Funktion.

Du führst jeden Befehl aus

Die Person gibt Richtung und Genehmigungen vor; du führst jeden Befehl selbst aus. Bitte sie nie, einen Befehl einzutippen oder einzufügen.

• Keine Genehmigung nötig: Nachschlagen; Upgrades (siehe oben); Installieren des Standard-Stacks und seiner Abhängigkeiten, sobald die Person um einen Prototypen gebeten hat. Kündige in einer Zeile an, was du installierst und warum, und mache es dann.
• Frage zuerst (erkläre warum in einem einfachen Satz, führe es dann bei „Ja“ selbst aus; ein „Ja“ kann eine aufgelistete Charge abdecken):
  • Anmelden bei einer CLI
  • Ändern einer Sicherheitseinstellung, z.B. Vertrauen in einen Homebrew-Tap (brew trust supabase/tap), und Upgrade eines Tools von einem Drittanbieter-Tap
  • Installieren eines Tools über den Standard-Stack hinaus (references/7-extend.md)
  • Erstellen von Cloud-Ressourcen (Vercel-Projekt, Supabase-Projekt, GitHub-Repository, Marketplace-Integration)
  • Deployment in die Produktion
  • Festlegen der Spezifikation und Wechsel von Spezifikation zu Bauen
• Wenn die Anfrage der Person bereits sagt, dass es bis zum Ende gehen soll („mach es zu einem Live-Link“), gilt das als Genehmigung für das Vercel-Projekt und das Produktions-Deployment. Sage trotzdem, was du gleich tun wirst, in einer Zeile, bevor du es tust.

Wenn ein Befehl die Interaktion der Person erfordert (Browser-Anmeldung, Verifizierungscode, Admin-Passwort):

1. Erkläre, was passieren wird und was sie sehen werden.
2. Führe es dort aus, wo sie es sehen und beantworten können: im Terminal-Panel deiner Agenten-App (ein „run in terminal“-Tool), falls du eines hast. Gib jeder Anmeldung einen eigenen neuen Tab mit ihrem Namen („Vercel-Anmeldung“, „GitHub-Anmeldung“); verwende nie einen Tab wieder, der für etwas anderes benannt ist. Bringe das Terminal-Panel auf diesem Tab in den Vordergrund (ein „show pane“-Tool) und verlinke den Tab in deiner Nachricht. Ohne Panel öffne andernfalls ein Terminal-Fenster für sie (macOS: osascript -e 'tell application "Terminal" to do script "cd <projekt> && <befehl>"'; Windows: start "" "%ProgramFiles%\Git\git-bash.exe" -c "<befehl>; read").
3. Warte, bis sie „fertig“ sagen, dann überprüfe es selbst (vercel whoami, gh auth status, ...). Markiere einen Schritt nie allein aufgrund ihrer Aussage als erledigt.

Geheimnisse (API-Schlüssel, Tokens), in dieser Reihenfolge:

1. Automatisch zuerst: eine Vercel Marketplace-Integration (Schlüssel landen auf Vercel, dann secrets.sh pull-vercel), oder eine Anbieter-CLI, deren Schlüsselausgabe du direkt in secrets.sh set NAME --stdin leitest. Die Person sieht oder fügt niemals einen Schlüssel ein.
2. Dialog zuletzt: nur wenn der Dienst keins von beiden anbietet, führe bash SKILL/scripts/secrets.sh ask NAME "wo zu finden" aus. Es öffnet einen Dialog mit versteckter Eingabe auf dem Bildschirm der Person und speichert den Wert im OS-Credential-Store; nichts geht durch den Chat oder deine Ausgabe. Sage der Person zuerst, dass ein Dialog erscheint und warum. Frage niemals nach einem Geheimnis im Chat, drucke niemals eines aus, schreibe niemals eines in Code oder eine versionierte Datei.

Das Arbeitsverzeichnis deiner Shell kann zwischen Aufrufen zurückgesetzt werden: Beginne jeden Projektbefehl mit cd "<projekt>" &&. Lang laufende Befehle (npm run dev) gehören in den Hintergrund.

Wie du mit der Person sprichst

• Vor jeder Aktion ein einfacher Satz, was es für sie tut: „Füge eine Browser-Datenbank hinzu, damit deine Liste zwischen Besuchen gespeichert wird.“
• Nach jedem Schritt eine Zusammenfassung von 2–3 Zeilen: was jetzt funktioniert, was sie ausprobieren können, was als nächstes kommt.
• Wenn es eine echte Wahl gibt, gib 2–3 Optionen und eine Empfehlung. Wähle andernfalls eine sinnvolle Standardeinstellung und sage, was du gewählt hast.
• Zeige, beschreibe nicht: Öffne localhost (oder einen Screenshot) nach jeder sichtbaren Änderung.
• Fehler: Behebe sie zuerst selbst. Hole die Person nur herein, wenn du eine Entscheidung, eine Genehmigung oder ihre Hände für eine Anmeldung, ein Passwort oder einen Schlüssel brauchst.

Mitgelieferte Dateien

• scripts/preflight.sh [verz] — Tools, Abhängigkeiten, installierte vs. neueste Versionen, Logins, Ordnerprüfungen
• scripts/secrets.sh — OS-Credential-Speicherung (ask öffnet einen Dialog mit versteckter Eingabe), run-with-keys, .env.local-Export, Vercel-Push/Pull (help für Verwendung)
• scripts/ignore-sync.sh <projekt> — Sagt Dropbox, node_modules, .next und Testausgaben nicht zu synchronisieren
• scripts/wincred.ps1 — Helfer für Windows Credential Manager, verwendet von secrets.sh (nicht direkt aufrufen)
• scripts/discover.sh <tool> — Erste Suche nach der CLI, dem npm-Paket und den Fähigkeiten eines neuen Tools
• scripts/install.sh — Installiert diese Fähigkeit global (fällt auf Projektebene zurück)
• templates/ — PROTOTYPE.md, SPEC.md, AGENTS.section.md, db.ts, actions.ts, smoke.spec.ts, playwright.config.ts

SKILL bedeutet in diesen Dokumenten den Ordner dieser Fähigkeit, z.B. ~/.agents/skills/setup-prototype-project. Erweitere es zum absoluten Pfad, wenn du ein Skript ausführst: bash ~/.agents/skills/setup-prototype-project/scripts/preflight.sh.

Häufige Fehler

Fehler	Stattdessen
Die Person bitten, einen Befehl auszuführen oder einzufügen	Erkläre, hole ein Ja ein, führe es selbst aus (sichtbares Terminal für Anmeldungen).
Einen Login als erledigt markieren, weil die Person es gesagt hat	Überprüfe mit der CLI (vercel whoami, gh auth status, supabase projects list).
Zulassen, dass Dropbox node_modules synchronisiert	Führe ignore-sync.sh direkt nach dem Gerüst aus.
Eine CLI installieren, bevor ihre Abhängigkeiten vorhanden sind	Befolge die Installationsreihenfolge in 1-setup.md (Paketmanager → Git → Node.js → npm CLIs).
Aus dem Gedächtnis installieren (npm i next@15)	Verwende @latest stabil; downgrade nur ein Paket, wenn eine Prüfung fehlschlägt.
Am ersten Tag nach Supabase greifen	Beginne mit IndexedDB; upgrade erst, wenn Teilen oder Login ein Muss ist.
IndexedDB von einer Server-Komponente oder Server Action aufrufen	IndexedDB existiert nur im Browser. Verwende es in "use client" Komponenten.
Einen API-Schlüssel in eine NEXT_PUBLIC_ Variable setzen	Alles NEXT_PUBLIC_ wird an jeden Besucher ausgeliefert. Halte Schlüssel serverseitig in Server Actions.
Jede Funktion bauen, bevor etwas gezeigt wird	Eine Funktion nach der anderen, gezeigt laufend, dann reagieren.
Deployen, ohne Schlüssel zu synchronisieren	Führe vor jedem Deployment secrets.sh diff-vercel aus.
Einen Job planen, der IndexedDB liest	Server-Jobs können keine Browserdaten sehen. Verschiebe die Daten zuerst nach Supabase (7-extend.md).
Einen Link übergeben, ohne ihn abgemeldet zu öffnen	Überprüfe vor dem Teilen, dass die Produktions-URL öffentlich 200 zurückgibt (6-ship.md).
Ein Tool aus einem Suchergebnis installieren, ohne zu prüfen, wer es veröffentlicht	Bevorzuge die offizielle CLI, das Paket oder die Fähigkeit des Anbieters. Zeige den Herausgeber beim Fragen.