starter-supabase — ponto de entrada do dispatch
Confirme a rota antes do Passo 0. Este skill cria um projeto inicial configurado com Supabase (autenticação, banco de dados e armazenamento prontos para uso). Uma aplicação sem Supabase →
/general-webapp; uma aplicação com backend customizado →/custom-backend; apenas front-end →/static-site. Fora do escopo: projetos legados ou que não utilizam Supabase.
Um projeto inicial full-stack, infraestrutura-primeiro: decida a estratégia de autenticação e banco de dados antes de escrever código de aplicação, depois construa o front-end em torno da infraestrutura. Todos os artefatos vão para PROJECT_DIR = projetos/<nome-do-projeto>/ (criado no Passo 0); todos os caminhos abaixo são relativos a ele.
| Fase | Execução | Artefato primário | Fluxo detalhado |
|---|---|---|---|
| init | Bash | supabase-config.json | Passo 0 |
| plan | subagente — decidir autenticação? + classificar + estratégia DB | schema.sql (rascunho: tabelas, políticas de segurança) | agents/orquestrador.md (Parte 1) |
| config | Bash — configurar variáveis de ambiente e inicializar Supabase | .env.local + supabase/ | passos/config/guia.md |
| design | subagente — APIs e funções serverless ao redor do schema | api/ + functions/ | agents/orquestrador.md (Parte 2) |
| build | subagente — composição reutilizável de componentes | components/index.html (ou JSX) | agents/constructor.md |
| deploy | Bash — supabase link + deploy de funções | deploy/url.txt | Passo 5 |
| verificar | Bash — lint / inspect -> subagente de reparo em falha | (correções no local) | agents/finalizar.md |
◇ config só executa quando o plano declara provedores de autenticação. Categorias puras de código (ex.: auth-email, auth-magic-link) têm providers: [] e pulam direto do plano para o design.
Categorias — divididas pela decisão de autenticação
plan's primeira decisão é: precisa de autenticação social? Esse fork divide as categorias em dois grupos; então a categoria específica é escolhida — para autenticação social, pelo tipo de provedor. Cada categoria é um categorias/<id>/modulo.md (suas regras de planejamento + construção); o vocabulário compartilhado de banco de dados vive em referencias/banco-de-dados-vocabulario.md (→ regras/blocos de supabase-schema + blocos de registro).
Categorias de formulário — sem autenticação social; o usuário fornece os dados:
| Categoria | Intenção | Depende de |
|---|---|---|
auth-email | autenticação por email/senha | blocos auth-* + regras de validação |
auth-magic | link mágico sem senha | magic-link / regras/{envio-email, verificacao} |
auth-anon | autenticação anônima | auth-anon bloco |
db-only | apenas banco de dados (sem auth) | schema bloco |
storage-only | apenas armazenamento de arquivos (sem auth) | storage bloco |
Categorias orientadas por autenticação social — configurar provedores primeiro, depois construir APIs:
| Provedor | Categoria | Configuração |
|---|---|---|
auth-google | OAuth 2.0 (credenciais no console Google) | |
| GitHub | auth-github | OAuth 2.0 (credenciais no GitHub) |
| Apple | auth-apple | OAuth 2.0 (credenciais no Apple Developer) |
| Vários | auth-multi | Múltiplos provedores + email (configuração única) |
Ordem de construção: um de cada vez, cobertura primeiro (rascunho está bom). auth-email portado do protótipo; os demais seguem.
Pré-requisitos
macOS Apple Silicon ou Linux x64. Ferramentas do sistema: brew install node git. npx supabase init uma vez. Docker (para o Supabase local).
Chaves opcionais (fallbacks locais se não definidas) — necessárias apenas em categorias que usam autenticação social:
| Chave | Usada para | Fallback |
|---|---|---|
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET | autenticação GitHub | skip / modo de demonstração |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | autenticação Google | skip / modo de demonstração |
Fluxo
Passo 0 — Inicializar
cwd é a raiz do workspace do agente; escreva todos os artefatos sob PROJECT_DIR = projetos/<nome-do-projeto>/. <nome-do-projeto>: use o diretório que o usuário deu, senão um nome curto em kebab-case a partir da intenção (<assunto>-supabase). Não o nome base do workspace ou um timestamp.
Apenas quando $PROJECT_DIR/supabase.json estiver ausente:
PROJECT_DIR="${SUPABASE_DIR:-projetos/<nome-do-projeto>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx create-next-app "$PROJECT_DIR" --typescript --tailwind --app
init verifica as versões instaladas do Supabase CLI contra as mais recentes no GitHub e atualiza as globais se estiverem desatualizadas.
Restrições: nunca supabase init na raiz do workspace; nunca aninhe outro supabase/ dentro de PROJECT_DIR; todo comando Bash (mestre + subagentes) é um subshell (cd "$PROJECT_DIR" && ...) — nunca cd simples.
Passo 1 — Planejar (subagente: Orquestrador Parte 1)
Despache um subagente. prompt = completo agents/orquestrador.md + ## Contexto do dispatch (SKILL_DIR / PROJECT_DIR / a solicitação do usuário / Schema: <SKILL_DIR>/referencias/shot-plan-ir.md). Ele deve:
- Decidir: precisa de autenticação social? (o primeiro fork)
- Não → escolha uma categoria de formulário (auth-email / auth-magic / auth-anon / db-only / storage-only); conteúdo fornecido pelo usuário;
providers: []. - Sim → emita um plano de provedores em
providers[](Google / GitHub / Apple / múltiplos). A categoria orientada por autenticação social específica (auth-google / auth-github / auth-apple / auth-multi) é confirmada pelo tipo de provedor retornado no Passo 2, e finalizada no Passo 3.
- Não → escolha uma categoria de formulário (auth-email / auth-magic / auth-anon / db-only / storage-only); conteúdo fornecido pelo usuário;
- Escreva um rascunho de
schema.sql(esqueleto + escolha de tabelas +providers+ um parágrafo de resumo do projeto). Schema:referencias/shot-plan-ir.md.
Validação: [ -s "$PROJECT_DIR/supabase-config.json" ] && echo ok || echo ausente.
Passo 2 — Configurar ◇ (Bash: supabase, condicional)
Se shot-plan.json.providers não estiver vazio, configure provedores (registrar URLs de callback, obter secrets, criar arquivo .env.local com variáveis). Veja passos/config/guia.md (envolve supabase config). Se providers estiver vazio, pule para o Passo 3.
# ilustrativo — veja passos/config/guia.md
(cd "$PROJECT_DIR" && node <SKILL_DIR>/passos/config/configurar.mjs --plan ./supabase-config.json --out ./.env.local)
Degrade com elegância: se um provedor estiver indisponível, a categoria cai para sem autenticação (anote no context.log).
Passo 3 — Design (subagente: Orquestrador Parte 2)
Despache um subagente (prompt = agents/orquestrador.md Parte 2 + contexto de dispatch incluindo o .env.local resolvido se o Passo 2 executou + catalogo-map.md). Ele desenha as APIs ao redor dos provedores disponíveis: escolhe os blocos de função + as regras de supabase-functions, as rotas, os middlewares e (para auth-multi) as providers_config + paleta de credenciais. Finaliza shot-plan.json (content.functions + content.customize + conteúdo por categoria).
Passo 4 — Construir (subagente: Construtor, reuso-primeiro)
Despache um subagente. prompt = completo agents/constructor.md + contexto de dispatch (shot-plan.json, catalogo-map.md, o modulo.md da categoria, referencias/banco-de-dados-vocabulario.md, referencias/constructor-contrato.md). Reuso-primeiro: npx create-next-app + adicione pacotes @supabase/supabase-js, personalize no local; escreva manualmente apenas lacunas + a camada de autenticação. Saída components/index.html (ou JSX) honrando o contrato do Supabase (rotas protegidas, sessão gerenciada via createPagesBrowserClient).
Passo 5 — Deploy (Bash)
(cd "$PROJECT_DIR" && npx supabase link --project-ref <ref> && npx supabase deploy --project-ref <ref>)
Passo 6 — Verificar (Bash → subagente de reparo em falha)
(cd "$PROJECT_DIR" && npx supabase db lint && npx supabase functions lint)
exit 0 → pronto. Em erros de lint, despache o subagente de reparo (agents/finalizar.md: QA de snapshot + uma correção no local + re-deploy). Nunca mude uma duração fixa no reparo.
Relatório + pré-visualização opcional
Relate a saída final (URL do deploy em deploy/url.txt) + duração. Não abra uma pré-visualização durante a execução. Ofereça apenas sob solicitação, iniciada após o deploy para que sirva o arquivo final:
(cd "$PROJECT_DIR" && npm run dev) # servidor de desenvolvimento
Bandeiras (flags) vivem no skill supabase-cli (referencias/preview-deploy.md).
Tabela de retomada
| Estado | Continuar de |
|---|---|
sem supabase-config.json | Passo 1 (planejar) |
supabase-config.json tem providers, sem .env.local | Passo 2 (configurar) |
supabase-config.json final, sem components/ | Passo 3/4 (design+construir) |
components/ existe, sem deploy/url.txt | Passo 5 (deploy) + Passo 6 |
deploy/url.txt existe | Relatório + parar |
Notas de design (mantenedores — execução não lê isso)
- Infraestrutura-primeiro fundamentação: a configuração é carregada antes e informa o design das APIs (fluxo RWA: analisar → configurar → revisar → construir). As categorias orientadas por autenticação social (
auth-google/auth-github/auth-apple) eauth-multiusam ambas a pesquisa de provedores do Supabase, que é a linhagem RWA documentada do Supabase. - Reuso-primeiro: o análogo dentro do ecossistema de templates gerados por LLM é "compor blocos de catálogo + regras
supabase-schema". O gerenciamento de sessão pausada do Supabase ≙useCurrentFramedo Remotion. - Contrato do módulo de categoria: um
categorias/<id>/modulo.md(planejamento + construção), compartilhandoreferencias/banco-de-dados-vocabulario.md(+ avaliação opcional). Adicionar uma categoria = soltar a pasta + registrar sua linha de classificação emagents/orquestrador.md+ sua linha emcatalogo-map.md; o pipeline de fases fica intocado. - Estrutura de diretórios:
projetos/<nome-do-projeto>/ supabase-config.json context.log schema.sql # o schema (saída do Orquestrador) .env.local # variáveis de ambiente (saída da configuração) components/index.html # saída do Construtor api/ functions/ deploy/url.txt - Registro: no roteador
supabase— adicione a intenção "projeto inicial configurado com Supabase" + descrição do Workflow; recorte os gatilhos desupabase-setupde gerais; adicione arestas reversas de NÃO-USAR. Vejasupabase-projeto-inicial-genre.md§5-7.