jayabdulraman/setup-prototype-project

Configurar Proyecto Prototipo

Construye una aplicación web funcional a partir de una idea, luego compártela como un enlace en vivo. La persona proporciona dirección y criterio; tú haces el trabajo técnico.

El stack

Capa	Herramienta predeterminada
Interfaz (lo que la gente ve y clica)	Next.js (App Router) + TypeScript + Tailwind + shadcn/ui (UI base, tema neutro, iconos Lucide, estilo Sera) desde un preset de shadcn
Trabajo del servidor (claves secretas, APIs externas, llamadas a IA)	Server Actions de Next.js
Datos	IndexedDB en el navegador (Dexie). CLI de Supabase instalada para después
Alojamiento y compartición	Vercel
Configuración y automatización	CLIs oficiales (vercel, supabase, gh, shadcn) + scripts de este skill

IndexedDB es lo primero: sin cuenta, sin claves, funciona sin conexión. Migra a Supabase solo cuando los datos deban compartirse entre personas o dispositivos, la app necesite inicio de sesión, o un servidor/job programado deba leer los datos (consulta references/7-extend.md).

Siempre la última versión estable (sin necesidad de preguntar)

• Las actualizaciones nunca necesitan aprobación, con una excepción: herramientas que provienen de un tap de Homebrew de terceros (ej. supabase/tap). Pregunta antes de confiar en dicho tap y antes de cada actualización desde él durante la configuración, incluso si ya fue aprobado antes.
• De lo contrario, lleva cada CLI y paquete a su última versión estable: npm i -g <cli>@latest, brew upgrade, winget upgrade, Node.js LTS actual, y en el proyecto npm outdated --json | jq -r 'keys[] + "@latest"' | xargs npm i. Di qué actualizaste en una línea.
• Nunca uses etiquetas canary, beta, rc o next a menos que la persona lo pida. No fijes versiones de memoria o de estos docs.
• Después de actualizar, ejecuta las comprobaciones (lint, typecheck, build). Si alguna falla, lee el error para encontrar el paquete que la rompió, degrada solo ese paquete a la versión más reciente de su major anterior (npm i -D <pkg>@^<major-1>), y vuelve a ejecutar. Registra el fijado y por qué en PROTOTYPE.md Decisiones. Ejemplo: TypeScript 7 rompió el plugin de TypeScript de ESLint, así que fija typescript@^6 y mantén todo lo demás actualizado.
• Al reanudar un prototipo existente, haz la misma pasada de actualización y verificación antes del nuevo trabajo.

La construcción, paso a paso

Lee el archivo de referencia del paso cuando llegues a él. No los leas todos de antemano.

Paso	La persona hace	Tú haces	Referencia
1. Configuración	Elige una carpeta	Verifica herramientas y sus dependencias, instala lo que falta, crea el andamio de la app	references/1-setup.md
2. Conectar	Aprueba, inicia sesión una vez en el navegador	Ejecuta cada inicio de sesión de CLI, confirma que funcionó, almacena las claves de la app en el almacén de credenciales del SO	references/2-connect.md
3. Especificación	Da forma a la idea	Haz rondas cortas de preguntas, escribe SPEC.md	references/3-spec.md
4. Construir	Reacciona, redirige	Construye una función a la vez, muéstrala funcionando	references/4-build.md
5. Probar	La prueba	Ejecuta comprobaciones, prueba en un navegador real, corrige	references/5-test.md
6. Publicar	Aprueba, comparte	Sincroniza claves en Vercel, despliega, entrega el enlace	references/6-ship.md
En cualquier momento	Pide una nueva capacidad	Encuentra la CLI o skill de la herramienta, pide permiso para instalar, conéctala	references/7-extend.md

Resultado: una aplicación funcionando en localhost, luego un enlace en vivo que cualquiera puede abrir.

Plataformas

	macOS	Windows	Linux
Shell para los scripts de este skill	Terminal (zsh/bash)	Git Bash (viene con Git para Windows)	bash
Gestor de paquetes para CLIs	Homebrew	winget (Scoop para Supabase)	Homebrew en Linux, o npm
Dónde viven las claves de la app	Llavero	Administrador de credenciales	Secret Service (secret-tool); de lo contrario un .env.local ignorado por git

• Ejecuta los scripts con bash <ruta absoluta>. En Windows desde PowerShell o cmd, bash simple puede iniciar WSL; usa & "$env:ProgramFiles\Git\bin\bash.exe" <script>. Claude Code en Windows ya ejecuta su shell en Git Bash.
• WSL cuenta como Linux, pero secrets.sh usa el Administrador de credenciales de Windows a través de powershell.exe cuando es accesible.
• Las carpetas sincronizadas en la nube (Dropbox, OneDrive, iCloud, Google Drive) están bien. En una carpeta de Dropbox, ejecuta bash SKILL/scripts/ignore-sync.sh <project> justo después del andamio para que Dropbox omita node_modules, .next y la salida de pruebas.

Archivo de progreso

Cada prototipo tiene un PROTOTYPE.md en su raíz (plantilla: templates/PROTOTYPE.md). Contiene la lista de verificación de pasos, la lista de herramientas (herramienta, versión, instalación global o de proyecto), los nombres de las claves (nunca los valores), decisiones y enlaces.

• Actualízalo al final de cada paso y cada vez que se añada una herramienta.
• Cuando se te invoque dentro de un prototipo existente, lee primero PROTOTYPE.md y reanuda en el primer paso sin marcar. Si la persona nombra un paso ("publiquemos"), ve allí, pero ejecuta primero las comprobaciones de ese paso.
• Todos los pasos marcados y la persona quiere algo nuevo: agrégalo a SPEC.md (imprescindibles + criterios de aceptación) y a Funciones en PROTOTYPE.md, ejecuta references/7-extend.md si necesita una nueva herramienta, luego repite Construir → Probar → Publicar para esa función.

Tú ejecutas cada comando

La persona da dirección y aprobaciones; tú ejecutas cada comando tú mismo. Nunca le pidas que escriba o pegue un comando.

• Sin necesidad de aprobación: buscar información; actualizaciones (ver arriba); instalar el stack predeterminado y sus dependencias una vez que la persona pidió un prototipo. Anuncia qué estás instalando y por qué en una línea, luego hazlo.
• Pregunta primero (explica por qué en una frase simple, luego ejecútalo tú mismo si dice que sí; un "sí" puede cubrir un lote listado):
  • iniciar sesión en una CLI
  • cambiar un ajuste de seguridad, ej. confiar en un tap de Homebrew (brew trust supabase/tap), y actualizar una herramienta desde un tap de terceros
  • instalar una herramienta más allá del stack predeterminado (references/7-extend.md)
  • crear recursos en la nube (proyecto Vercel, proyecto Supabase, repositorio GitHub, integración de marketplace)
  • desplegar a producción
  • fijar la especificación y pasar de Especificación a Construcción
• Si la solicitud de la persona ya dice que vaya hasta el final ("llévalo a un enlace en vivo"), esa es la aprobación para el proyecto Vercel y el despliegue de producción. Aun así, di lo que estás a punto de hacer, una línea, antes de hacerlo.

Cuando un comando necesita que la persona interactúe (un inicio de sesión en el navegador, un código de verificación, una contraseña de administrador):

1. Explica qué sucederá y qué verán.
2. Ejecútalo donde puedan verlo y responder: el panel de terminal de tu aplicación de agente (una herramienta "ejecutar en terminal") si tienes uno. Dale a cada inicio de sesión su propia pestaña nueva con su nombre ("Inicio de sesión Vercel", "Inicio de sesión GitHub"); nunca reutilices una pestaña nombrada para otra cosa. Trae el panel de terminal a la vista en esa pestaña (una herramienta "mostrar panel") y enlaza la pestaña en tu mensaje. Sin panel, de lo contrario abre una ventana de terminal para ellos (macOS: osascript -e 'tell application "Terminal" to do script "cd <project> && <command>"'; Windows: start "" "%ProgramFiles%\Git\git-bash.exe" -c "<command>; read").
3. Espera a que digan "listo", luego verifícalo tú mismo (vercel whoami, gh auth status, ...). Nunca marques un paso como hecho solo por sus palabras.

Secretos (claves API, tokens), en este orden:

1. Automático primero: una integración de Vercel Marketplace (las claves llegan a Vercel, luego secrets.sh pull-vercel), o una CLI de proveedor cuya salida de clave canalizas directamente a secrets.sh set NAME --stdin. La persona nunca ve ni pega una clave.
2. Diálogo como último recurso: solo cuando el servicio no ofrece ninguna de las anteriores, ejecuta bash SKILL/scripts/secrets.sh ask NAME "dónde encontrarlo". Abre un diálogo de entrada oculta en la pantalla de la persona y almacena el valor en el almacén de credenciales del SO; nada pasa a través del chat o tu salida. Informa primero a la persona de que aparecerá un diálogo y por qué. Nunca pidas un secreto en el chat, nunca lo imprimas, nunca lo escribas en código o en un archivo versionado.

El directorio de trabajo de tu shell puede reiniciarse entre llamadas: comienza cada comando del proyecto con cd "<project>" &&. Los comandos de larga duración (npm run dev) van en segundo plano.

Cómo hablar con la persona

• Antes de cada acción, una frase simple sobre lo que hace por ellos: "Agregando una base de datos en el navegador para que tu lista se guarde entre visitas."
• Después de cada paso, un resumen de 2–3 líneas: qué funciona ahora, qué pueden probar, qué viene después.
• Cuando haya una elección real, da 2–3 opciones y una recomendación. De lo contrario, elige un valor predeterminado sensato y di lo que elegiste.
• Muestra, no describas: abre localhost (o una captura de pantalla) después de cada cambio visible.
• Errores: corrígelos tú mismo primero. Solo involucra a la persona cuando necesites una decisión, aprobación, o sus manos para un inicio de sesión, contraseña o clave.

Archivos incluidos

• scripts/preflight.sh [dir] — herramientas, dependencias, versiones instaladas vs últimas, inicios de sesión, comprobaciones de carpeta
• scripts/secrets.sh — almacenamiento de credenciales del SO (ask abre un diálogo de entrada oculta), ejecución con claves, exportación a .env.local, push/pull a Vercel (help para uso)
• scripts/ignore-sync.sh <project> — le dice a Dropbox que no sincronice node_modules, .next y la salida de pruebas
• scripts/wincred.ps1 — ayudante del Administrador de credenciales de Windows usado por secrets.sh (no lo llames directamente)
• scripts/discover.sh <tool> — búsqueda inicial para la CLI, paquete npm y skills de una nueva herramienta
• scripts/install.sh — instala este skill globalmente (con fallback a nivel de proyecto)
• templates/ — PROTOTYPE.md, SPEC.md, AGENTS.section.md, db.ts, actions.ts, smoke.spec.ts, playwright.config.ts

SKILL en estos docs significa la carpeta de este skill, ej. ~/.agents/skills/setup-prototype-project. Expándelo a la ruta absoluta cuando ejecutes un script: bash ~/.agents/skills/setup-prototype-project/scripts/preflight.sh.

Errores comunes

Error	En su lugar
Pedir a la persona que ejecute o pegue un comando	Explica, obtén un sí, ejecútalo tú mismo (terminal visible para inicios de sesión).
Marcar un inicio de sesión como hecho porque la persona lo dijo	Verifica con la CLI (vercel whoami, gh auth status, supabase projects list).
Dejar que Dropbox sincronice node_modules	Ejecuta ignore-sync.sh justo después del andamio.
Instalar una CLI antes de sus dependencias	Sigue el orden de instalación en 1-setup.md (gestor de paquetes → git → Node.js → CLIs npm).
Instalar de memoria (npm i next@15)	Usa @latest estable; degrada solo un paquete si una comprobación falla.
Usar Supabase desde el primer día	Empieza con IndexedDB; actualiza cuando compartir o el inicio de sesión sea imprescindible.
Llamar a IndexedDB desde un Server Component o Server Action	IndexedDB solo existe en el navegador. Úsalo en componentes "use client".
Poner una clave API en una variable NEXT_PUBLIC_	Cualquier NEXT_PUBLIC_ se envía a todos los visitantes. Mantén las claves del lado del servidor en Server Actions.
Construir cada función antes de mostrar nada	Una función a la vez, mostrada funcionando, luego reacciona.
Desplegar sin sincronizar claves	Ejecuta secrets.sh diff-vercel antes de cada despliegue.
Programar un job que lea IndexedDB	Los jobs del servidor no pueden ver datos del navegador. Migra los datos a Supabase primero (7-extend.md).
Entregar un enlace sin abrirlo con sesión cerrada	Verifica que la URL de producción devuelva 200 públicamente antes de compartir (6-ship.md).
Instalar una herramienta de un resultado de búsqueda sin verificar quién la publica	Prefiere la CLI, paquete o skill oficial del proveedor. Muestra el editor al preguntar.