ganbatte-os 0.2.37 → 0.2.38

package/.gos/skills/typeform-form-pattern/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: typeform-form-pattern
+description: >
+  Gera estrutura de form passo-a-passo estilo Typeform (uma pergunta por vez), com
+  questions[] tipadas, hooks de navegacao, validacao Zod, animacao, progress bar e
+  estados visuais. Lucide React (zero emoji). React + TS + Tailwind + shadcn.
+argument-hint: "<descricao do form ou 'spec' para ver a anatomia>"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion]
+sourceDocs:
+  - libraries/typeform-pattern-spec.md
+  - libraries/lucide-icons-policy.md
+  - libraries/ui-guardrails-checklist.md
+use-when:
+  - usuario pede form de cadastro/onboarding/quiz/lead/survey
+  - precisa coletar dados em multiplas etapas com baixo cognitive load
+  - mobile-first form
+do-not-use-for:
+  - settings page com varios campos editaveis simultaneamente (use form tradicional)
+  - input simples 1-2 campos (overhead nao compensa)
+metadata:
+  category: ui-pattern
+---
+
+Voce esta executando como **Typeform Pattern Generator** via skill `typeform-form-pattern`. Gera estrutura completa baseada em `libraries/typeform-pattern-spec.md`.
+
+## Pre-flight
+
+1. Pergunta ao usuario:
+   - "Quantas perguntas previstas?" (estimar — pode evoluir)
+   - "Salvar progresso entre sessoes? (sessionStorage / Supabase / nao)"
+   - "Tem tela de Welcome inicial? E de Review final?"
+   - "Submit final manda pra Supabase, Workers, ou apenas mostra resultado?"
+2. Validar stack: deve existir `tailwind.config`, `lucide-react` no package.json, shadcn `Button`, `Input`, `Card`, `Label`. Senao -> propor instalar.
+3. Aplicar `libraries/lucide-icons-policy.md` — zero emoji, todos icones via Lucide.
+
+## Geracao
+
+### Arquivos criados
+
+```
+src/components/<feature>/
+  questions.ts              # tipos + array de questions
+  TypeformContainer.tsx     # estado + navegacao
+  questions/
+    WelcomeQuestion.tsx
+    TextQuestion.tsx
+    NumberQuestion.tsx
+    ChoiceQuestion.tsx
+    MultiChoiceQuestion.tsx
+    ReviewQuestion.tsx
+  hooks/
+    useTypeformFlow.ts
+  schemas/
+    formSchema.ts           # Zod
+```
+
+### Estrutura base de `questions.ts`
+
+```ts
+import type { ComponentType } from 'lucide-react';
+import * as Icons from 'lucide-react';
+
+export type QuestionType =
+  | 'welcome' | 'text' | 'number' | 'choice' | 'multiChoice' | 'date' | 'review';
+
+export interface QuestionOption {
+  value: string;
+  label: string;
+  description?: string;
+  iconName?: keyof typeof Icons;
+}
+
+export interface Question<F = Record<string, unknown>> {
+  id: string;
+  type: QuestionType;
+  field: keyof F | null;
+  question: string | ((data: F) => string);
+  description?: string;
+  placeholder?: string;
+  suffix?: string;
+  decimal?: boolean;
+  buttonText?: string;
+  options?: QuestionOption[];
+  validate?: (value: unknown, data: F) => string | null;
+  showWhen?: (data: F) => boolean;
+}
+
+// Exemplo:
+export const questions: Question<FormData>[] = [
+  {
+    id: 'welcome',
+    type: 'welcome',
+    field: null,
+    question: 'Vamos comecar',
+    description: 'Sera rapido — leva 2 minutos.',
+    buttonText: 'Comecar',
+  },
+  {
+    id: 'name',
+    type: 'text',
+    field: 'name',
+    question: 'Como podemos te chamar?',
+    placeholder: 'Seu nome',
+    validate: (v) => (!v ? 'Campo obrigatorio' : null),
+  },
+  // ...
+];
+```
+
+### Hook `useTypeformFlow`
+
+Encapsula:
+- `currentIndex`, `setCurrentIndex`
+- `data`, `updateField`
+- `activeQuestions` (filtrado por `showWhen`)
+- `currentQ`
+- `handleNext` (com validacao)
+- `handlePrevious`
+- `handleKeyPress` (Enter, Esc)
+- `progress` (% concluido)
+- Persistencia opcional (sessionStorage ou Supabase)
+
+### Container
+
+```tsx
+export function TypeformContainer({ onComplete }: Props) {
+  const flow = useTypeformFlow(questions);
+
+  return (
+    <div className="min-h-screen flex flex-col">
+      <ProgressBar value={flow.progress} />
+
+      <main className="flex-1 flex items-center justify-center px-4">
+        <div className={`max-w-2xl w-full transition-all duration-300 ${
+          flow.isAnimating ? 'opacity-0 translate-y-4' : 'opacity-100 translate-y-0'
+        }`}>
+          <QuestionRenderer question={flow.currentQ} flow={flow} />
+        </div>
+      </main>
+
+      <NavButtons flow={flow} />
+    </div>
+  );
+}
+```
+
+### Estados visuais (UI guardrails)
+
+Aplicar `libraries/ui-guardrails-checklist.md`:
+
+- **Loading** (submitting): botao final disabled + `<Loader2 className="h-4 w-4 animate-spin mr-2" />`.
+- **Empty** (questions = []): tela "Nenhuma pergunta configurada" com `<AlertCircle />`.
+- **Error**: inline acima do CTA primario.
+- **Success**: tela final com `<CheckCircle2 className="h-16 w-16 text-success" />` + redirect/proximos passos.
+- **Skeleton**: nao aplicavel (form nao tem fetch inicial geralmente).
+
+### Validacao com Zod
+
+```ts
+// schemas/formSchema.ts
+import { z } from 'zod';
+
+export const formSchema = z.object({
+  name: z.string().min(2, 'Minimo 2 caracteres'),
+  email: z.string().email('Email invalido'),
+  age: z.coerce.number().int().min(13, 'Minimo 13 anos').max(120),
+  // ...
+});
+
+export type FormData = z.infer<typeof formSchema>;
+```
+
+Chamar no submit final:
+```ts
+const result = formSchema.safeParse(data);
+if (!result.success) {
+  // mostrar primeiro erro inline
+}
+```
+
+### Acessibilidade obrigatoria
+
+- `aria-live="polite"` no container que troca de question.
+- `aria-label` em botoes voltar / Lucide-icon-only.
+- `useEffect` foca o input ao mudar de question.
+- Roles ARIA em listas de opcoes (`role="radiogroup"` para choice).
+
+### Atalhos teclado
+
+- `Enter` -> next.
+- `Esc` ou `Backspace` (em campo vazio) -> previous.
+- Em multiChoice: setas para navegar opcoes, espaco para toggle.
+
+## Customizacao por usuario
+
+Apos gerar estrutura base, AskUserQuestion:
+1. "Cor primaria? (default: shadcn primary)"
+2. "Animacao de transicao? (fade / slide / nenhuma)"
+3. "Progress bar: top, bottom, ou nao?"
+4. "Permite voltar e editar respostas? (sim/nao)"
+
+## Anti-patterns embutidos (gera com warning se usuario insistir)
+
+- "Quero todas as perguntas em uma tela" -> form tradicional, nao typeform-pattern.
+- "Sem progress bar" -> warning, mas gera (UX ruim em mobile).
+- "Emoji nas opcoes" -> recusar, usar Lucide.
+
+## Input
+
+$ARGUMENTS

package/.gos/skills/ui-guardrails/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ui-guardrails
+description: >
+  Pre-flight obrigatorio antes de codar uma tela. Verifica que cada task de tela tem
+  estados (loading/empty/error/success), responsividade, a11y e tokens declarados.
+  Bloqueia codegen se faltar — evita que erros de UI sejam descobertos tarde.
+  Pensado para reduzir o "trabalho extra de corrigir o que nao foi previsto".
+argument-hint: "<plan-id-ou-task-path>"
+allowedTools: [Read, Glob, Grep, Edit, AskUserQuestion]
+sourceDocs:
+  - libraries/ui-guardrails-checklist.md
+use-when:
+  - antes de design-to-code/figma-implement-design rodar
+  - validar plano de UI antes de execute-plan
+  - usuario reclama "esqueceram do estado vazio de novo"
+do-not-use-for:
+  - tasks de backend (sem UI)
+  - bug fixes pontuais (use react-doctor)
+metadata:
+  category: validation
+---
+
+Voce esta executando como **UI Guardrails Validator** via skill `ui-guardrails`. Verifica que cada task de UI tem cobertura completa antes de codegen — bloqueia execucao se faltar.
+
+## Contrato
+
+1. Le um plano (`docs/plans/PLAN-NNN/`) ou task individual (`tasks/T-NN-...md`).
+2. Para cada task com `area: ui-ux` ou `area: frontend`, aplica checklist (ver `libraries/ui-guardrails-checklist.md`).
+3. Se faltar item -> output structured com gaps + sugestao de adicao + opcao de `AskUserQuestion` para corrigir inline OU abortar.
+4. Se passar -> output curto "OK, N tasks validadas, codegen liberado".
+
+## Checklist (resumo — detalhe na library)
+
+Para CADA task de UI:
+
+### A. Estados visuais (5 obrigatorios)
+- [ ] Loading: **skeleton OBRIGATORIO** (shadcn `Skeleton`) para listas/cards/tabelas; spinner Lucide `Loader2` so para botoes ou acoes pontuais.
+- [ ] Empty: copy + Lucide icon (h-12 w-12 text-muted-foreground) + CTA primario.
+- [ ] Error: mensagem + Lucide `AlertTriangle` + recovery action (botao retry).
+- [ ] Success (quando aplicavel): Lucide `CheckCircle2` em toast/inline.
+- [ ] Default (renderizado normal).
+
+**Regra critica**: **SEMPRE skeleton ao carregar dados**, **SEMPRE empty state quando lista vazia**. Sem excecoes mesmo em descartavel.
+
+### B. Responsividade (3 breakpoints minimos)
+- [ ] Mobile (<768px): layout declarado
+- [ ] Tablet (768-1024px): comportamento declarado
+- [ ] Desktop (>1024px): default
+
+### C. A11y (4 minimos)
+- [ ] Roles ARIA quando aplicavel (button, dialog, listbox)
+- [ ] Labels em inputs (htmlFor + id ou aria-label)
+- [ ] Focus order definido se mais de 3 elementos interativos
+- [ ] Contraste AA verificado (lens 6 do figma-print-diff)
+
+### D. Tokens do DS (todos via referencia)
+- [ ] Cores via tokens (`bg-primary`, NUNCA hex direto)
+- [ ] Spacing via scale (`gap-4`, NUNCA `gap-[17px]`)
+- [ ] Typography via classes (`text-base`, NUNCA `text-[15px]`)
+- [ ] Border-radius via scale (`rounded-md`, NUNCA `rounded-[7px]`)
+
+### F. Lucide React (zero-emoji policy)
+- [ ] Import de icones SO de `lucide-react` (nunca FontAwesome/Heroicons/outra lib).
+- [ ] **Zero emoji unicode em strings de UI** (regex `/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}]/u`).
+- [ ] Icon-only button com `aria-label` obrigatorio.
+- [ ] Tamanhos canonicos: `h-3.5 w-3.5` inline, `h-4 w-4` button, `h-5 w-5` heading, `h-12 w-12` empty state, `h-16 w-16` hero.
+
+Detalhe: `libraries/lucide-icons-policy.md`.
+
+### E. Interacao (quando aplicavel)
+- [ ] Trigger -> acao -> resultado declarado em `## Interacoes & Estados`
+- [ ] Edge case: o que acontece se trigger duplicar (debounce)?
+- [ ] Edge case: o que acontece se backend demorar >3s?
+
+## Niveis de violacao
+
+| Tipo | Severidade | Acao |
+|------|-----------|------|
+| A faltando (estado) | high | Bloqueia codegen. Pede correcao via AskUserQuestion. |
+| B faltando (responsivo) | high | Bloqueia se task e tela full. Warning se componente isolado. |
+| C faltando (a11y) | medium | Warning. Codegen continua mas adiciona TODO no codigo. |
+| D faltando (tokens) | medium | Warning. Codegen pode prosseguir mas relatorio ao final. |
+| E faltando (interacao) | high (se ha trigger) | Bloqueia. plan-blueprint ja exige isso — caso aqui e detectar regressao. |
+| F faltando (Lucide/emoji) | high | Bloqueia. Recusar codigo com emoji em UI ou icone nao-Lucide. |
+
+## Output
+
+```
+[ui-guardrails] PLAN-NNN — N tasks de UI validadas
+
+[OK]   T-01: cards-projeto-list           A B C D E
+[FAIL] T-02: drawer-edit-projeto          A . C D E   (faltando: empty state, hover focus)
+[WARN] T-03: tooltip-status               A B . D E   (a11y: sem aria-label)
+
+bloqueado: 1 task (T-02). Corrija antes de design-to-code.
+warnings: 1 (T-03 — a11y).
+```
+
+## Hook em pipeline
+
+`prototype-orchestrator` (fase 5 -> 6) e `plan-blueprint` (apos plan-to-tasks) DEVEM chamar `ui-guardrails` automaticamente em produtos NAO-descartaveis. Para descartaveis, oferecer skip via flag `--no-guardrails`.
+
+## Regras criticas
+
+- **Descartavel relax**: se plan tem `descartavel: true` no frontmatter, A/B viram warning (nao block).
+- **Codegen sem guardrails**: violacao da regra do dono ("muito trabalho corrigindo erros nao previstos"). Bloqueia.
+- **Self-update**: se task tem `interaction_target` mas falta `## Interacoes & Estados` no plano, sugerir patch automatico.
+
+## Input
+
+$ARGUMENTS

package/.gos/templates/intakeTemplate.md

@@ -0,0 +1,41 @@
+---
+intake_id: INTAKE-<NNN>-<slug>
+status: pronto-para-prd
+descartavel: <true|false>
+created_at: <iso>
+---
+
+# <Titulo curto da ideia>
+
+## Problema (em uma frase)
+<sintese feita pelo agente>
+
+## Historias reais coletadas
+- <bullet 1>
+- <bullet 2>
+
+## Persona
+<descricao em prosa, contexto incluido>
+
+## Jobs-to-be-done
+- Quando <situacao>, eu quero <acao>, para que <resultado>.
+
+## Limites (o que NAO fazer)
+- <bullet>
+
+## Telas-chave (visao bruta)
+1. <tela 1 — descricao em palavras leigas>
+2. <tela 2>
+
+## Inspiracoes
+- <link ou nome>
+
+## Escopo
+- Descartavel: <sim|nao>
+- Vida util esperada: <uma vez|semanas|meses|continuo>
+
+## Metrica de sucesso (linguagem humana)
+<frase do usuario>
+
+## Proximo passo
+- Rodar `*prd-from-intake INTAKE-<NNN>-<slug>` para gerar PRD lean.

package/.gos/templates/prdLeanTemplate.md

@@ -0,0 +1,40 @@
+---
+prd_id: PRD-<NNN>-<slug>
+intake_ref: INTAKE-<NNN>-<slug>
+descartavel: <bool>
+status: pronto-para-adr
+created_at: <iso>
+---
+
+# <Titulo>
+
+## TL;DR (1 paragrafo, max 4 linhas)
+<problema + persona + solucao + metrica>
+
+## Quem usa
+<persona em 2 linhas>
+
+## Por que existe
+<problema em 2 linhas, citando 1 historia real>
+
+## O que faz (3-7 bullets)
+- <feature 1>
+- <feature 2>
+
+## Telas-chave
+| # | Tela | Proposito | Inputs | Outputs |
+|---|------|-----------|--------|---------|
+| 1 | <nome> | <verbo + objeto> | <dado entrada> | <dado saida> |
+
+## Criterios de aceite (do nao-tecnico)
+- [ ] Usuario consegue <acao primaria> em menos de <X> passos
+- [ ] <criterio mensurivel>
+
+## Metrica de sucesso
+<copia da metrica humana + 1 metrica quantitativa derivada>
+
+## NAO faz parte (escopo negativo)
+- <bullet>
+
+## Proximo passo
+- Rodar `*adr-tech-decisions PRD-<NNN>-<slug>` para definir arquitetura.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ganbatte-os",
-  "version": "0.2.37",
+  "version": "0.2.38",
   "description": "Framework operacional para design-to-code, squads de entrega e sprint sync com ClickUp.",
   "bin": {
     "gos": ".gos/scripts/cli/gos-cli.js"