jayabdulraman/setup-prototype-project

Configurar Projeto Protótipo

Construa um aplicativo web funcional a partir de uma ideia e compartilhe-o como um link ativo. A pessoa fornece direção e julgamento; você faz o trabalho técnico.

A stack

Camada	Ferramenta padrão
Interface (o que as pessoas veem e clicam)	Next.js (App Router) + TypeScript + Tailwind + shadcn/ui (Base UI, tema neutro, ícones Lucide, estilo Sera) a partir de um preset shadcn
Trabalho do servidor (chaves secretas, APIs externas, chamadas de IA)	Server Actions do Next.js
Dados	IndexedDB no navegador (Dexie). CLI do Supabase instalada para uso posterior
Hospedagem e compartilhamento	Vercel
Configuração e automação	CLIs oficiais (vercel, supabase, gh, shadcn) + scripts desta skill

IndexedDB vem primeiro: sem conta, sem chaves, funciona offline. Mude para Supabase apenas quando os dados precisarem ser compartilhados entre pessoas ou dispositivos, o aplicativo precisar de login ou um servidor/tarefa agendada precisar ler os dados (veja references/7-extend.md).

Sempre a versão estável mais recente (sem necessidade de perguntar)

• Atualizações nunca precisam de aprovação, com uma exceção: ferramentas provenientes de um terceiro Homebrew tap (ex.: supabase/tap). Peça permissão antes de confiar em tal tap e antes de cada atualização dele durante a configuração, mesmo que tenha sido aprovado anteriormente.
• Caso contrário, atualize cada CLI e pacote para sua versão estável mais recente: npm i -g <cli>@latest, brew upgrade, winget upgrade, Node.js último LTS, e no projeto npm outdated --json | jq -r 'keys[] + "@latest"' | xargs npm i. Diga o que foi atualizado em uma linha.
• Nunca use tags canary, beta, rc ou next a menos que a pessoa peça. Não fixe versões de memória ou destes documentos.
• Após atualizar, execute as verificações (lint, typecheck, build). Se uma falhar, leia o erro para encontrar o pacote que a quebrou, faça downgrade apenas desse pacote para a versão mais recente de sua major anterior (npm i -D <pkg>@^<major-1>), e execute novamente. Registre a fixação e o motivo em PROTOTYPE.md Decisões. Exemplo: TypeScript 7 quebrou o plugin TypeScript do ESLint, então fixe typescript@^6 e mantenha todo o resto atualizado.
• Ao retomar um protótipo existente, faça a mesma passagem de atualização e verificação antes de novos trabalhos.

A construção, passo a passo

Leia o arquivo de referência do passo quando chegar nele. Não os leia todos de uma vez.

Passo	Pessoa faz	Você faz	Referência
1. Configuração	Escolhe uma pasta	Verificar ferramentas e suas dependências, instalar o que falta, criar o esqueleto do app	references/1-setup.md
2. Conectar	Aprova, faz login uma vez no navegador	Executar cada login CLI, confirmar que funcionou, armazenar chaves do app no gerenciador de credenciais do SO	references/2-connect.md
3. Especificação	Modela a ideia	Fazer rodadas curtas de perguntas, escrever SPEC.md	references/3-spec.md
4. Construir	Reage, redireciona	Construir uma funcionalidade por vez, mostrar funcionando	references/4-build.md
5. Testar	Testa	Executar verificações, testar em navegador real, corrigir	references/5-test.md
6. Enviar	Aprova, compartilha	Sincronizar chaves para Vercel, implantar, entregar o link	references/6-ship.md
A qualquer momento	Pede uma nova capacidade	Encontrar a CLI ou skill da ferramenta, pedir para instalar, conectar	references/7-extend.md

Resultado: um aplicativo funcionando em localhost, depois um link ativo que qualquer pessoa pode abrir.

Plataformas

	macOS	Windows	Linux
Shell para scripts desta skill	Terminal (zsh/bash)	Git Bash (vem com Git for Windows)	bash
Gerenciador de pacotes para CLIs	Homebrew	winget (Scoop para Supabase)	Homebrew no Linux, ou npm
Onde as chaves do app ficam	Keychain	Credential Manager	Secret Service (secret-tool); caso contrário, um .env.local ignorado pelo git

• Execute scripts com bash <caminho absoluto>. No Windows a partir do PowerShell ou cmd, bash pode iniciar o WSL; use & "$env:ProgramFiles\Git\bin\bash.exe" <script>. Claude Code no Windows já executa seu shell no Git Bash.
• WSL conta como Linux, mas secrets.sh usa o Windows Credential Manager através de powershell.exe quando está acessível.
• Pastas sincronizadas na nuvem (Dropbox, OneDrive, iCloud, Google Drive) são adequadas. Em uma pasta do Dropbox, execute bash SKILL/scripts/ignore-sync.sh <projeto> logo após criar o esqueleto, para que o Dropbox ignore node_modules, .next e saída de teste.

Arquivo de progresso

Cada protótipo tem um PROTOTYPE.md em sua raiz (modelo: templates/PROTOTYPE.md). Ele contém a checklist de passos, a lista de ferramentas (ferramenta, versão, instalação global ou no projeto), nomes de chaves (nunca valores), decisões e links.

• Atualize-o ao final de cada passo e sempre que uma ferramenta for adicionada.
• Quando invocado dentro de um protótipo existente, leia PROTOTYPE.md primeiro e retome a partir do primeiro passo não marcado. Se a pessoa nomear um passo ("vamos enviar"), vá para lá, mas execute as verificações desse passo primeiro.
• Todos os passos marcados e a pessoa quer algo novo: adicione a SPEC.md (obrigatórios + critérios de aceitação) e em Funcionalidades no PROTOTYPE.md, execute references/7-extend.md se precisar de uma nova ferramenta, depois loop Construir → Testar → Enviar para essa funcionalidade.

Você executa todo comando

A pessoa dá direção e aprovações; você executa todo comando pessoalmente. Nunca peça para ela digitar ou colar um comando.

• Sem necessidade de aprovação: pesquisas; atualizações (veja acima); instalar a stack padrão e suas dependências uma vez que a pessoa pediu um protótipo. Anuncie o que está instalando e por que em uma linha, depois faça.
• Pergunte primeiro (explique o porquê em uma frase simples, depois execute você mesmo se for sim; um sim pode cobrir um lote listado):
  • fazer login em uma CLI
  • alterar uma configuração de segurança, ex.: confiar em um Homebrew tap (brew trust supabase/tap), e atualizar uma ferramenta de um tap de terceiros
  • instalar uma ferramental além da stack padrão (references/7-extend.md)
  • criar recursos em nuvem (projeto Vercel, projeto Supabase, repositório GitHub, integração de marketplace)
  • implantar em produção
  • travar a especificação e passar de Especificação para Construção
• Se o pedido da pessoa já diz para ir até o fim ("leve a um link ativo"), isso é a aprovação para o projeto Vercel e implantação em produção. Ainda assim, diga o que você está prestes a fazer, uma linha, antes de fazer.

Quando um comando precisar que a pessoa interaja (login no navegador, código de verificação, senha de administrador):

1. Explique o que acontecerá e o que ela verá.
2. Execute onde ela possa ver e responder: o painel de terminal do seu app agente (uma ferramenta "executar no terminal") se você tiver um. Dê a cada login sua própria aba nomeada para ele ("Login Vercel", "Login GitHub"); nunca reutilize uma aba nomeada para outra coisa. Traga o painel do terminal para vista nessa aba (uma ferramenta "mostrar painel") e linke a aba em sua mensagem. Sem um painel, abra uma janela de terminal para a pessoa (macOS: osascript -e 'tell application "Terminal" to do script "cd <projeto> && <comando>"'; Windows: start "" "%ProgramFiles%\Git\git-bash.exe" -c "<comando>; read").
3. Aguarde ela dizer "pronto", então verifique você mesmo (vercel whoami, gh auth status, ...). Nunca marque um passo como concluído apenas pela palavra dela.

Segredos (chaves de API, tokens), nesta ordem:

1. Automático primeiro: uma integração do Vercel Marketplace (as chaves vão para o Vercel, depois secrets.sh pull-vercel), ou uma CLI de provedor cuja saída de chave você pipe diretamente para secrets.sh set NOME --stdin. A pessoa nunca vê ou cola uma chave.
2. Diálogo por último: apenas quando o serviço não oferecer nenhum dos anteriores, execute bash SKILL/scripts/secrets.sh ask NOME "onde encontrar". Ele abre um diálogo de entrada oculta na tela da pessoa e armazena o valor no gerenciador de credenciais do SO; nada passa pelo chat ou sua saída. Avise a pessoa primeiro que um diálogo aparecerá e por quê. Nunca peça um segredo no chat, nunca imprima um, nunca escreva um em código ou arquivo versionado.

O diretório de trabalho do seu shell pode ser redefinido entre chamadas: inicie todo comando do projeto com cd "<projeto>" &&. Comandos de longa duração (npm run dev) vão para segundo plano.

Como falar com a pessoa

• Antes de cada ação, uma frase simples sobre o que faz para ela: "Adicionando um banco de dados no navegador para que sua lista seja salva entre visitas."
• Após cada passo, um resumo de 2 a 3 linhas: o que agora funciona, o que ela pode testar, o que vem a seguir.
• Quando houver uma escolha real, dê 2 a 3 opções e uma recomendação. Caso contrário, escolha um padrão sensato e diga o que escolheu.
• Mostre, não descreva: abra localhost (ou uma captura de tela) após cada mudança visível.
• Erros: corrija você mesmo primeiro. Só envolva a pessoa quando precisar de uma decisão, aprovação ou das mãos dela para login, senha ou chave.

Arquivos incluídos

• scripts/preflight.sh [dir] — ferramentas, dependências, versões instaladas vs. mais recentes, logins, verificações de pasta
• scripts/secrets.sh — armazenamento de credenciais do SO (ask abre um diálogo de entrada oculta), executar-com-chaves, exportar .env.local, push/pull Vercel (help para uso)
• scripts/ignore-sync.sh <projeto> — diz ao Dropbox para não sincronizar node_modules, .next e saída de teste
• scripts/wincred.ps1 — auxiliar do Windows Credential Manager usado por secrets.sh (não chamar diretamente)
• scripts/discover.sh <ferramenta> — primeira pesquisa para uma nova ferramenta: CLI, pacote npm e skills
• scripts/install.sh — instala esta skill globalmente (cai para nível de projeto)
• templates/ — PROTOTYPE.md, SPEC.md, AGENTS.section.md, db.ts, actions.ts, smoke.spec.ts, playwright.config.ts

SKILL nestes documentos significa a pasta desta skill, ex.: ~/.agents/skills/setup-prototype-project. Expanda para o caminho absoluto ao executar um script: bash ~/.agents/skills/setup-prototype-project/scripts/preflight.sh.

Erros comuns

Erro	Em vez disso
Pedir para a pessoa executar ou colar um comando	Explique, obtenha um sim, execute você mesmo (terminal visível para logins).
Marcar um login como concluído porque a pessoa disse	Verifique com a CLI (vercel whoami, gh auth status, supabase projects list).
Deixar o Dropbox sincronizar node_modules	Execute ignore-sync.sh logo após criar o esqueleto.
Instalar uma CLI antes do que ela depende	Siga a ordem de instalação em 1-setup.md (gerenciador de pacotes → git → Node.js → npm CLIs).
Instalar de memória (npm i next@15)	Use @latest estável; faça downgrade de apenas um pacote se uma verificação falhar.
Usar Supabase no primeiro dia	Comece com IndexedDB; atualize quando compartilhamento ou login for obrigatório.
Chamar IndexedDB de um Server Component ou Server Action	IndexedDB existe apenas no navegador. Use-o em componentes "use client".
Colocar uma chave de API em uma variável NEXT_PUBLIC_	Qualquer NEXT_PUBLIC_ é enviado a todo visitante. Mantenha chaves no lado do servidor em Server Actions.
Construir toda funcionalidade antes de mostrar algo	Uma funcionalidade por vez, mostrada funcionando, depois reaja.
Implantar sem sincronizar chaves	Execute secrets.sh diff-vercel antes de cada implantação.
Agendar uma tarefa que lê IndexedDB	Tarefas de servidor não podem ver dados do navegador. Migre os dados para Supabase primeiro (7-extend.md).
Entregar um link sem abri-lo desconectado	Verifique se a URL de produção retorna 200 publicamente antes de compartilhar (6-ship.md).
Instalar uma ferramenta de um resultado de pesquisa sem verificar quem a publica	Prefira a CLI, pacote ou skill oficial do fornecedor. Mostre o publicador ao perguntar.