jabdulraman/setup-prototype-project

Configurer un Projet Prototype

Construire une application web fonctionnelle à partir d'une idée, puis la partager sous forme de lien en direct. La personne fournit la direction et le jugement ; vous faites le travail technique.

La pile technologique

Couche	Outil par défaut
Interface (ce que les gens voient et cliquent)	Next.js (App Router) + TypeScript + Tailwind + shadcn/ui (UI de base, thème neutre, icônes Lucide, style Sera) à partir d'un preset shadcn
Travail serveur (clés secrètes, API externes, appels IA)	Next.js Server Actions
Données	IndexedDB dans le navigateur (Dexie). CLI Supabase installée pour plus tard
Hébergement et partage	Vercel
Configuration et automatisation	CLI officiels (vercel, supabase, gh, shadcn) + scripts de cette compétence

IndexedDB vient en premier : pas de compte, pas de clés, fonctionne hors ligne. Passez à Supabase uniquement lorsque les données doivent être partagées entre personnes ou appareils, que l'application a besoin d'une connexion, ou qu'un serveur/tâche planifiée doit lire les données (voir references/7-extend.md).

Toujours la dernière version stable (pas besoin de demander)

• Les mises à jour ne nécessitent jamais d'approbation, à une exception près : les outils provenant d'un Homebrew tap tiers (par exemple supabase/tap). Demandez avant de faire confiance à un tel tap et avant chaque mise à jour à partir de celui-ci pendant la configuration, même s'il a déjà été approuvé.
• Sinon, amenez chaque CLI et paquet à sa dernière version stable : npm i -g <cli>@latest, brew upgrade, winget upgrade, Node.js LTS actuel, et dans le projet npm outdated --json | jq -r 'keys[] + "@latest"' | xargs npm i. Dites ce que vous avez mis à jour en une ligne.
• N'utilisez jamais les tags canary, beta, rc ou next sauf si la personne le demande. Ne verrouillez pas les versions de mémoire ou à partir de ces documents.
• Après la mise à jour, exécutez les vérifications (lint, typecheck, build). Si l'une échoue, lisez l'erreur pour trouver le paquet qui l'a cassé, rétrogradez uniquement ce paquet vers la version la plus récente de sa version majeure précédente (npm i -D <pkg>@^<major-1>) et relancez. Enregistrez le blocage et la raison dans PROTOTYPE.md Décisions. Exemple : TypeScript 7 a cassé le plugin TypeScript d'ESLint, donc bloquez typescript@^6 et gardez tout le reste à jour.
• Lorsque vous reprenez un prototype existant, faites la même passe de mise à jour et de vérification avant tout nouveau travail.

La construction, étape par étape

Lisez le fichier de référence de l'étape lorsque vous l'atteignez. Ne les lisez pas tous à l'avance.

Étape	La personne fait	Vous faites	Référence
1. Configuration	Choisit un dossier	Vérifier les outils et leurs dépendances, installer ce qui manque, générer l'application	references/1-setup.md
2. Connexion	Approuve, se connecte une fois dans le navigateur	Exécuter chaque connexion CLI, confirmer qu'elle a fonctionné, stocker les clés de l'application dans le gestionnaire d'identifiants du système	references/2-connect.md
3. Spécifications	Façonne l'idée	Poser des séries de questions courtes, rédiger SPEC.md	references/3-spec.md
4. Construction	Réagit, redirige	Construire une fonctionnalité à la fois, la montrer en cours d'exécution	references/4-build.md
5. Test	Essaie	Exécuter les vérifications, tester dans un vrai navigateur, corriger	references/5-test.md
6. Livraison	Approuve, partage	Synchroniser les clés vers Vercel, déployer, transmettre le lien	references/6-ship.md
À tout moment	Demande une nouvelle capacité	Trouver le CLI ou la compétence de l'outil, demander à installer, connecter	references/7-extend.md

Résultat : une application fonctionnelle sur localhost, puis un lien en direct que tout le monde peut ouvrir.

Plateformes

	macOS	Windows	Linux
Shell pour les scripts de cette compétence	Terminal (zsh/bash)	Git Bash (fourni avec Git pour Windows)	bash
Gestionnaire de paquets pour les CLI	Homebrew	winget (Scoop pour Supabase)	Homebrew sur Linux, ou npm
Où vivent les clés de l'application	Trousseau	Gestionnaire d'identifiants	Secret Service (secret-tool) ; sinon un .env.local ignoré par git

• Exécutez les scripts avec bash <chemin absolu>. Sur Windows depuis PowerShell ou cmd, bash simple peut lancer WSL à la place ; utilisez & "$env:ProgramFiles\Git\bin\bash.exe" <script>. Claude Code sur Windows exécute déjà son shell dans Git Bash.
• WSL compte comme Linux, mais secrets.sh utilise le Gestionnaire d'identifiants Windows via powershell.exe lorsqu'il est accessible.
• Les dossiers synchronisés dans le cloud (Dropbox, OneDrive, iCloud, Google Drive) sont acceptables. Dans un dossier Dropbox, exécutez bash SKILL/scripts/ignore-sync.sh <projet> juste après la génération pour que Dropbox ignore node_modules, .next et les résultats de test.

Fichier de progression

Chaque prototype a un fichier PROTOTYPE.md à sa racine (modèle : templates/PROTOTYPE.md). Il contient la liste de contrôle des étapes, la liste des outils (outil, version, installation globale ou projet), les noms des clés (jamais les valeurs), les décisions et les liens.

• Mettez-le à jour à la fin de chaque étape et chaque fois qu'un outil est ajouté.
• Lorsqu'il est invoqué dans un prototype existant, lisez PROTOTYPE.md en premier et reprenez à la première étape non cochée. Si la personne nomme une étape (« livrons-le »), allez-y, mais exécutez d'abord les vérifications de cette étape.
• Toutes les étapes cochées et la personne veut quelque chose de nouveau : ajoutez-le à SPEC.md (indispensables + critères d'acceptation) et aux Fonctionnalités dans PROTOTYPE.md, exécutez references/7-extend.md si cela nécessite un nouvel outil, puis bouclez Construction → Test → Livraison pour cette fonctionnalité.

Vous exécutez chaque commande

La personne donne la direction et les approbations ; vous exécutez chaque commande vous-même. Ne leur demandez jamais de taper ou de coller une commande.

• Aucune approbation nécessaire : recherche d'informations ; mises à jour (voir ci-dessus) ; installation de la pile par défaut et de ses dépendances une fois que la personne a demandé un prototype. Annoncez ce que vous installez et pourquoi en une ligne, puis faites-le.
• Demandez d'abord (expliquez pourquoi en une phrase simple, puis exécutez-la vous-même sur un oui ; un oui peut couvrir un lot listé) :
  • se connecter à un CLI
  • modifier un paramètre de sécurité, par exemple faire confiance à un Homebrew tap (brew trust supabase/tap), et mettre à jour un outil à partir d'un tap tiers
  • installer un outil au-delà de la pile par défaut (references/7-extend.md)
  • créer des ressources cloud (projet Vercel, projet Supabase, dépôt GitHub, intégration de place de marché)
  • déployer en production
  • verrouiller les spécifications et passer de Spécifications à Construction
• Si la demande de la personne dit déjà d'aller jusqu'au bout (« amenez-le à un lien en direct »), cela constitue l'approbation pour le projet Vercel et le déploiement en production. Dites toujours ce que vous allez faire, une ligne, avant de le faire.

Lorsqu'une commande nécessite que la personne interagisse (une connexion navigateur, un code de vérification, un mot de passe administrateur) :

1. Expliquez ce qui va se passer et ce qu'elle verra.
2. Exécutez-la là où elle peut voir et répondre : le panneau de terminal de votre application agent (un outil « exécuter dans le terminal ») si vous en avez un. Donnez à chaque connexion son propre nouvel onglet nommé (« Connexion Vercel », « Connexion GitHub ») ; ne réutilisez jamais un onglet nommé pour autre chose. Amenez le panneau de terminal dans la vue sur cet onglet (un outil « afficher le panneau ») et liez l'onglet dans votre message. Sans panneau, sinon ouvrez une fenêtre de terminal pour eux (macOS : osascript -e 'tell application "Terminal" to do script "cd <projet> && <commande>"' ; Windows : start "" "%ProgramFiles%\Git\git-bash.exe" -c "<commande>; read").
3. Attendez qu'ils disent « fait », puis vérifiez vous-même (vercel whoami, gh auth status, ...). Ne marquez jamais une étape comme terminée sur leur seule parole.

Secrets (clés API, jetons), dans cet ordre :

1. D'abord automatique : une intégration Vercel Marketplace (les clés atterrissent sur Vercel, puis secrets.sh pull-vercel), ou un CLI fournisseur dont la sortie de clé vous redirigez directement dans secrets.sh set NOM --stdin. La personne ne voit ni ne colle jamais de clé.
2. Dialogue en dernier recours : uniquement lorsque le service n'offre ni l'un ni l'autre, exécutez bash SKILL/scripts/secrets.sh ask NOM "où le trouver". Cela ouvre une boîte de dialogue à entrée masquée sur l'écran de la personne et stocke la valeur dans le gestionnaire d'identifiants du système ; rien ne passe par le chat ou votre sortie. Prévenez d'abord la personne qu'un dialogue apparaîtra et pourquoi. Ne demandez jamais un secret dans le chat, n'en imprimez jamais un, ne l'écrivez jamais dans du code ou un fichier validé.

Le répertoire de travail de votre shell peut se réinitialiser entre les appels : commencez chaque commande de projet par cd "<projet>" &&. Les commandes de longue durée (npm run dev) vont en arrière-plan.

Comment parler à la personne

• Avant chaque action, une phrase simple sur ce que cela fait pour eux : « Ajout d'une base de données navigateur pour que votre liste se sauvegarde entre les visites. »
• Après chaque étape, un récapitulatif de 2 à 3 lignes : ce qui fonctionne maintenant, ce qu'ils peuvent essayer, ce qui vient ensuite.
• Lorsqu'il y a un vrai choix, donnez 2 à 3 options et une recommandation. Sinon, choisissez une valeur par défaut sensée et dites ce que vous avez choisi.
• Montrez, ne décrivez pas : ouvrez localhost (ou une capture d'écran) après chaque changement visible.
• Erreurs : corrigez-les vous-même d'abord. N'impliquez la personne que lorsque vous avez besoin d'une décision, d'une approbation ou de ses mains pour une connexion, un mot de passe ou une clé.

Fichiers inclus

• scripts/preflight.sh [répertoire] — outils, dépendances, versions installées vs dernières, connexions, vérifications de dossier
• scripts/secrets.sh — stockage d'identifiants du système (ask ouvre un dialogue à entrée masquée), exécution-avec-clés, exportation .env.local, push/pull Vercel (help pour l'utilisation)
• scripts/ignore-sync.sh <projet> — indique à Dropbox de ne pas synchroniser node_modules, .next et les résultats de test
• scripts/wincred.ps1 — assistant Gestionnaire d'identifiants Windows utilisé par secrets.sh (ne pas appeler directement)
• scripts/discover.sh <outil> — première recherche pour un nouvel outil : CLI, paquet npm et compétences
• scripts/install.sh — installe cette compétence globalement (se rabat sur le niveau projet)
• templates/ — PROTOTYPE.md, SPEC.md, AGENTS.section.md, db.ts, actions.ts, smoke.spec.ts, playwright.config.ts

SKILL dans ces documents signifie le dossier de cette compétence, par exemple ~/.agents/skills/setup-prototype-project. Développez-le en chemin absolu lorsque vous exécutez un script : bash ~/.agents/skills/setup-prototype-project/scripts/preflight.sh.

Erreurs courantes

Erreur	Au lieu de cela
Demander à la personne d'exécuter ou de coller une commande	Expliquez, obtenez un oui, exécutez-la vous-même (terminal visible pour les connexions).
Marquer une connexion comme terminée parce que la personne l'a dit	Vérifiez avec le CLI (vercel whoami, gh auth status, supabase projects list).
Laisser Dropbox synchroniser node_modules	Exécutez ignore-sync.sh juste après la génération.
Installer un CLI avant ce dont il dépend	Suivez l'ordre d'installation dans 1-setup.md (gestionnaire de paquets → git → Node.js → CLI npm).
Installer de mémoire (npm i next@15)	Utilisez @latest stable ; rétrogradez un seul paquet si une vérification échoue.
Atteindre Supabase le premier jour	Commencez sur IndexedDB ; mettez à niveau lorsque le partage ou la connexion est indispensable.
Appeler IndexedDB depuis un Server Component ou une Server Action	IndexedDB n'existe que dans le navigateur. Utilisez-le dans les composants "use client".
Mettre une clé API dans une variable NEXT_PUBLIC_	Tout ce qui est NEXT_PUBLIC_ est envoyé à chaque visiteur. Gardez les clés côté serveur dans les Server Actions.
Construire chaque fonctionnalité avant de montrer quoi que ce soit	Une fonctionnalité à la fois, montrée en cours d'exécution, puis réaction.
Déployer sans synchroniser les clés	Exécutez secrets.sh diff-vercel avant chaque déploiement.
Planifier une tâche qui lit IndexedDB	Les tâches serveur ne peuvent pas voir les données du navigateur. Déplacez d'abord les données vers Supabase (7-extend.md).
Transmettre un lien sans l'ouvrir déconnecté	Vérifiez que l'URL de production renvoie 200 publiquement avant de partager (6-ship.md).
Installer un outil à partir d'un résultat de recherche sans vérifier qui le publie	Préférez le CLI, le paquet ou la compétence officiels du fournisseur. Montrez l'éditeur lorsque vous demandez.