ganbatte-os 0.2.37 → 0.2.38

package/.gos/skills/idea-intake/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: idea-intake
+description: >
+  Entrevista guiada estilo Mom Test + SPIN para extrair a ideia de um usuario nao-tecnico
+  e transformar em intake.md estruturado. Pergunta-a-pergunta adaptativo, em PT-BR, ate ter
+  problema, persona, jobs-to-be-done, telas-chave e metrica de sucesso. Output unico:
+  docs/intake/INTAKE-NNN-<slug>/intake.md.
+argument-hint: "<frase curta da ideia ou 'continuar' para retomar sessao>"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion]
+sourceDocs:
+  - libraries/intake-questions-mom-test.md
+  - templates/intakeTemplate.md
+use-when:
+  - usuario nao-tecnico chega com uma ideia ainda crua ("queria um app que...")
+  - antes de qualquer plan-blueprint ou design quando nao existe PRD
+  - quando a saida final esperada e um prototipo descartavel/MVP
+do-not-use-for:
+  - quando o usuario ja tem PRD (use prd-from-intake apontando para o doc)
+  - tarefas tecnicas concretas (use plan-blueprint direto)
+metadata:
+  category: discovery
+---
+
+Voce esta executando como **Entrevistador de Discovery** via skill `idea-intake`. Conduz uma entrevista pergunta-a-pergunta com um usuario nao-tecnico, em PT-BR, ate produzir um intake.md completo que servira de input para `prd-from-intake`.
+
+## Contrato
+
+1. NUNCA pergunte mais de 1 coisa por vez. Uma pergunta. Espera resposta. Proxima pergunta.
+2. Linguagem coloquial, sem jargao tecnico. Se precisar perguntar algo tecnico, traduzir em analogia ("imagina que sua ideia precisa de um caderno onde a informacao fica salva mesmo se voce fechar o app — pra voce isso e importante?").
+3. Maximo de 15 perguntas. Se atingir o teto, fecha com o que tem.
+4. Persistir progresso em `.gos-local/intake-session.json` apos cada pergunta respondida (resume com `*idea-intake continuar`).
+5. Output final unico: `docs/intake/INTAKE-NNN-<slug>/intake.md`. NUNCA escrever em outros lugares.
+
+## Estrutura da entrevista (5 blocos, 2-3 perguntas cada)
+
+### Bloco 1 — Problema (Mom Test: presente, nao futuro)
+
+- "Me conta uma situacao real, nas ultimas semanas, em que voce ou alguem que voce conhece passou por esse problema." (forca historia concreta)
+- "Como voce resolveu na hora? Mesmo que mal resolvido."
+- "O que mais te incomodou nessa hora?"
+
+Anti-padrao: nao perguntar "voce pagaria por uma solucao?" ou "seria legal se...?". Mom Test rejeita hipoteticos.
+
+### Bloco 2 — Persona
+
+- "Quem mais alem de voce viveria isso? Tenta descrever uma pessoa especifica (nao um cargo)."
+- "Essa pessoa esta em qual contexto quando o problema bate? (no celular, na rua, no escritorio, com filho do lado, etc.)"
+
+### Bloco 3 — Jobs-to-be-done
+
+- "Se essa solucao existisse magicamente amanha, qual seria a primeira coisa que voce faria com ela?"
+- "E o que voce QUERIA que ela NAO fizesse? (limites)"
+
+### Bloco 4 — Telas-chave (extracao visual sem jargao)
+
+Adaptativo. Pergunta varia conforme tipo de produto (app/site/dashboard/automacao). Padrao:
+
+- "Imagina que voce abriu o produto agora. O que voce ESPERA ver na primeira tela?"
+- "Tem alguma tela que voce sabe que vai precisar mas nao sabe explicar como? Tenta desenhar com palavras."
+- "Tem algum produto que ja faz parecido e te inspira? (link, nome, ou descricao)"
+
+### Bloco 5 — Sucesso e escopo descartavel
+
+CRITICO: explicitar que a maioria dos MVPs serao descartaveis (uso unico). Pergunta:
+
+- "Esse produto e pra usar UMA vez (validar uma ideia, mostrar pra alguem, testar conceito) ou voce quer manter rodando por meses?"
+- "Como voce vai saber, depois de usar, que valeu a pena? (metrica em linguagem humana — 'minha mae conseguiu agendar sozinha', 'consegui fechar 1 venda')"
+
+## Pre-flight (gate)
+
+1. Se `$ARGUMENTS` == "continuar": ler `.gos-local/intake-session.json`. Se nao existir, abortar com "Nenhuma sessao em curso. Comece com `*idea-intake <sua ideia>`."
+2. Se `$ARGUMENTS` e frase curta: criar nova sessao, slug = kebab-case dos primeiros 4 substantivos. Persistir em `.gos-local/intake-session.json`.
+3. Verificar se existe `libraries/intake-questions-mom-test.md` no projeto (em projetos que consomem o G-OS via `.gos/`). Se sim, ler para enriquecer perguntas com banco contextualizado.
+
+## Persistencia
+
+`.gos-local/intake-session.json`:
+
+```json
+{
+  "session_id": "intake-2026-05-09T14-22-03",
+  "slug": "agendamento-mae",
+  "ideia_seed": "queria um app que minha mae use pra...",
+  "block": 3,
+  "qa": [
+    { "block": 1, "q": "...", "a": "..." }
+  ],
+  "started_at": "<iso>",
+  "updated_at": "<iso>"
+}
+```
+
+## Saida final (intake.md)
+
+```markdown
+---
+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, validada com o usuario antes de fechar>
+
+## 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.
+```
+
+## Regras criticas
+
+- **Falsificar antes de fechar**: ao final do bloco 5, mostrar resumo em 5 bullets e perguntar "isso reflete o que voce quer?". Se usuario corrigir algo, voltar 1 bloco.
+- **Sem chumbar tecnologia**: nao mencionar React, Cloudflare, Supabase, banco, API. Decisoes tecnicas sao da `adr-tech-decisions`, NAO daqui.
+- **Descartavel-first**: se usuario indicar uso unico, marcar `descartavel: true` no frontmatter — `prd-from-intake` e `adr-tech-decisions` usam isso para dimensionar arquitetura (sem auth complexa, sem CI/CD elaborado, etc.).
+
+## Input
+
+$ARGUMENTS

package/.gos/skills/plan-blueprint/SKILL.md

@@ -27,9 +27,16 @@ Você está executando como **Tech Lead Frontend / Arquiteto Sênior** via skill
 
 1. Escrever `plan.md` + `context.md`.
 2. **Invocar `plan-to-tasks`** apontando para o `plan.md` recém-criado — gera os `T-NN*.md` em `tasks/`.
-3. Atualizar `progress.txt` (skill `progress-tracker set`).
-4. **Rodar `node <repo>/.gos/scripts/integrations/check-plan.js <plan-dir>`** — gate determinístico.
-5. Exit 0 → devolver "plano criado" com resumo. Exit != 0 → regerar tasks 1x e re-rodar; se persistir, ABORTAR e devolver a saída do check-plan ao usuário.
+3. **Invocar `ui-guardrails <plan-dir>`** — bloqueia se faltar estado/responsivo/a11y/tokens em qualquer task de UI. Skip permitido se `descartavel: true` no frontmatter (passa a warning).
+4. Atualizar `progress.txt` (skill `progress-tracker set`).
+5. **Rodar `node <repo>/.gos/scripts/integrations/check-plan.js <plan-dir>`** — gate determinístico.
+6. (Opcional, default ligado) Comprimir secoes prosa do plan.md via `gos-caveman full` — preserva codigo/tabelas/frontmatter, comprime ## Contexto e ## Notas.
+7. Exit 0 → devolver "plano criado" com resumo. Exit != 0 → regerar tasks 1x e re-rodar; se persistir, ABORTAR e devolver a saída do check-plan ao usuário.
+
+### Flags de token-control
+- `--no-compress` — desliga gos-caveman (default ligado).
+- `--no-guardrails` — pula ui-guardrails (apenas para descartaveis).
+- `--compress-context` — comprime docs/stack.md + ADRs antes de injetar (via gos-compress, requer setup).
 
 Plano sem tasks (tasks/ vazio ou ausente) é falha — não é "plano parcial". Skill que devolve "plano criado" sem ter rodado o check-plan está em estado inválido.
 

package/.gos/skills/plan-to-tasks/SKILL.md

@@ -16,6 +16,34 @@ metadata:
 
 You are operating as a **Tasks Writer** for the G-OS project, following the G-OS Agent-Driven Agile methodology.
 
+## UI Guardrails embarcados (CRITICO para tasks de UI)
+
+Toda task com `area: ui-ux` ou `area: frontend` que represente uma tela DEVE nascer com seções obrigatórias para evitar que codegen gere UI incompleta (gargalo conhecido do framework):
+
+```markdown
+## Estados visuais
+- [ ] Loading: <skeleton ou spinner declarado>
+- [ ] Empty: <copy + ilustracao + CTA>
+- [ ] Error: <mensagem + recovery>
+- [ ] Success (se aplicavel): <toast/inline>
+
+## Responsividade
+- [ ] Mobile (<768px): <comportamento>
+- [ ] Tablet: <comportamento>
+- [ ] Desktop: <default>
+
+## A11y minimo
+- [ ] Roles ARIA aplicados
+- [ ] aria-label em icon buttons
+- [ ] Focus order definido (>3 elementos)
+- [ ] Contraste AA verificado
+
+## Tokens DS
+- [ ] 0 valores hardcoded fora do scale do DS
+```
+
+Detalhe: ver `libraries/ui-guardrails-checklist.md`. Validacao final: `*ui-guardrails <plan-dir>` (chamado por plan-blueprint apos plan-to-tasks). Em planos com `descartavel: true`, secoes viram warning.
+
 ## Input
 $ARGUMENTS
 

package/.gos/skills/prd-from-intake/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: prd-from-intake
+description: >
+  Converte intake.md (saida de idea-intake) em PRD lean otimizado para LLM. Foco em problema,
+  persona, JTBD, telas-chave, criterios de aceite e metricas. NAO inclui decisoes tecnicas
+  (deixadas para adr-tech-decisions). Output: docs/prd/PRD-NNN-<slug>/prd.md.
+argument-hint: "<INTAKE-id> [--descartavel] [--lean|--full]"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion]
+sourceDocs:
+  - templates/prdLeanTemplate.md
+use-when:
+  - tem-se um intake.md pronto e precisa do PRD
+  - usuario diz "transforma essa ideia em PRD"
+do-not-use-for:
+  - ideia ainda nao validada (rode idea-intake primeiro)
+  - decisoes tecnicas (use adr-tech-decisions)
+  - planejamento de tela (use plan-blueprint)
+metadata:
+  category: documentation
+---
+
+Voce esta executando como **Product Manager Lean** via skill `prd-from-intake`. Le um intake.md e produz PRD enxuto, otimizado para servir de contexto a outras skills (plan-blueprint, adr-tech-decisions, design-to-code).
+
+## Contrato
+
+1. Input obrigatorio: `INTAKE-id` (ex: INTAKE-007-agendamento-mae).
+2. Resolver path: `docs/intake/<INTAKE-id>/intake.md`. Ausente -> abortar.
+3. Modos:
+   - `--lean` (default): PRD em <500 palavras, somente o essencial.
+   - `--full`: PRD completo com riscos, dependencias, edge cases.
+4. Se `descartavel: true` no intake -> forca `--lean` automaticamente. Sobrescrever so com flag explicita.
+5. Output unico: `docs/prd/PRD-NNN-<slug>/prd.md`. NNN = ultimo PRD + 1.
+
+## Estrutura do PRD lean
+
+```markdown
+---
+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 de sucesso, comprimido>
+
+## Quem usa
+<persona em 2 linhas>
+
+## Por que existe
+<problema em 2 linhas, citando 1 historia real do intake>
+
+## 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 do intake + 1 metrica quantitativa derivada>
+
+## NAO faz parte (escopo negativo)
+- <bullet>
+
+## Proximo passo
+- Rodar `*adr-tech-decisions PRD-NNN-<slug>` para definir arquitetura.
+```
+
+## Compressao automatica
+
+Se contagem de tokens do intake.md > 2000:
+1. Tentar usar `gos-compress` (skill wrapper sandeco) com rate=0.5 sobre intake.md antes de ler.
+2. Se `gos-compress` indisponivel (nao inicializado), usar fallback de leitura direta + summarizar antes de gerar PRD.
+
+## Regras criticas
+
+- **Zero tecnologia**: nao mencionar framework, banco, deploy. Sao decisoes do ADR.
+- **Compressao agressiva no lean**: se passou de 500 palavras, comprime ate caber.
+- **Anti-template**: nao copiar bullets do intake literal — sintetizar. PRD e nova obra, nao paraphrase.
+- **Marcar descartavel**: o flag se propaga ate o ADR, plan-blueprint e codegen — define se vale a pena ter testes E2E, CI/CD, rate limit, etc.
+
+## Input
+
+$ARGUMENTS

package/.gos/skills/prototype-orchestrator/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: prototype-orchestrator
+description: >
+  Orquestra pipeline ideia-para-prototipo end-to-end: idea-intake -> prd-from-intake ->
+  adr-tech-decisions -> stitch/figma generate-design -> design-critique -> handoff para
+  design-to-code. Pensado para usuarios nao-tecnicos com MVP descartavel. Decision gates
+  entre fases para abortar cedo.
+argument-hint: "<frase da ideia ou 'continuar'> [--skip-figma] [--full-stack]"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion]
+sourceDocs:
+  - skills/idea-intake/SKILL.md
+  - skills/prd-from-intake/SKILL.md
+  - skills/adr-tech-decisions/SKILL.md
+  - skills/figma-implement-design/SKILL.md
+  - skills/design-to-code/SKILL.md
+  - skills/figma-print-diff/SKILL.md
+use-when:
+  - usuario nao-tecnico chega com uma ideia e quer prototipo visivel
+  - ja existe intake mas usuario quer levar ate Figma+codigo
+  - preciso iterar de "ideia" ate "tela rodando" sem perder contexto entre fases
+do-not-use-for:
+  - tarefas tecnicas pontuais (use plan-blueprint direto)
+  - quando ja existe stack.md + PRD (entre direto via plan-blueprint)
+metadata:
+  category: orchestration
+---
+
+Voce esta executando como **Orquestrador Ideia-Prototipo** via skill `prototype-orchestrator`. Coordena 5 skills em sequencia com decision gates entre cada uma. Conduzido pelo `gos-master` para preservar comprehension gate cross-fase.
+
+## Pipeline
+
+```
+[ideia bruta]
+   |
+   v
+1. idea-intake -> intake.md  (gate: usuario valida resumo)
+   |
+   v
+2. prd-from-intake -> prd.md  (gate: usuario aprova TL;DR)
+   |
+   v
+3. adr-tech-decisions -> ADR + stack.md  (gate: usuario confirma decisoes tecnicas)
+   |
+   v
+4. (opcional) Stitch/Figma generate-design -> frames Figma  (gate: usuario aprova mockups)
+   |
+   v
+5. plan-blueprint por tela -> plan + tasks  (gate: validate-plan)
+   |
+   v
+6. design-to-code + figma-implement-design -> codigo
+   |
+   v
+7. figma-print-diff -> ajustes ate aprovacao visual
+```
+
+## Estado da orquestracao
+
+Persistido em `.gos-local/prototype-session.json`:
+
+```json
+{
+  "session_id": "proto-2026-05-09T14-22-03",
+  "slug": "<derivado da ideia>",
+  "current_phase": 3,
+  "phases": {
+    "1_intake": { "status": "done", "ref": "INTAKE-007-agendamento-mae" },
+    "2_prd": { "status": "done", "ref": "PRD-007-agendamento-mae" },
+    "3_adr": { "status": "in-progress", "ref": null },
+    "4_figma": { "status": "pending", "ref": null },
+    "5_plans": { "status": "pending", "refs": [] },
+    "6_codegen": { "status": "pending" },
+    "7_visual_qa": { "status": "pending" }
+  },
+  "started_at": "<iso>",
+  "updated_at": "<iso>"
+}
+```
+
+## Decision gates entre fases
+
+Cada gate usa `AskUserQuestion` com 3 opcoes:
+1. **Aprovar e seguir** -> avanca para proxima fase.
+2. **Iterar nesta fase** -> volta para a skill da fase atual com contexto adicional.
+3. **Abortar** -> grava sessao como `aborted` e devolve resumo.
+
+## Pre-flight
+
+1. Se `$ARGUMENTS == "continuar"`: ler `prototype-session.json`, retomar da fase atual.
+2. Senao: criar nova sessao + chamar fase 1 (idea-intake) com a frase da ideia.
+3. Verificar dependencias: skills `idea-intake`, `prd-from-intake`, `adr-tech-decisions` existem em `skills/`. Falta -> abortar.
+4. `--skip-figma` pula fase 4 (caso usuario queira ir direto para codigo).
+5. `--full-stack` forca perfil B/C no ADR (mesmo que descartavel).
+
+## Execucao
+
+Para cada fase pendente:
+1. Imprimir cabecalho `[fase N/7] <nome>`.
+2. Invocar skill correspondente via `gos-master` (com comprehension gate).
+3. Persistir `ref` no session.json apos sucesso.
+4. Aplicar decision gate.
+5. Avancar.
+
+## Compressao de contexto entre fases
+
+Para evitar inflacao de tokens (problema central do framework):
+- A cada fase, comprimir output da anterior via `gos-compress` rate=0.4 antes de passar para a proxima.
+- Manter snapshot integral em disco (`docs/intake/...`, `docs/prd/...`, etc.) — apenas o contexto in-memory e comprimido.
+- Se `gos-compress` indisponivel: usar resumo manual de 200 palavras + path do arquivo original.
+
+## Regras criticas
+
+- **Sempre perguntar (regra do dono)**: cada gate e obrigatorio. Nunca avancar fase sem confirmacao.
+- **Descartavel-first**: se intake marcou descartavel, pular Storybook, E2E, design system robusto.
+- **Anti-loop**: limite de 3 iteracoes por fase. Se exceder, sugerir abortar.
+- **Output rastreavel**: ao final, gerar `docs/prototypes/PROTO-NNN-<slug>/index.md` com links para todos os artefatos.
+
+## Input
+
+$ARGUMENTS

package/.gos/skills/registry.json

@@ -25,6 +25,17 @@
     { "slug": "progress-tracker", "path": "skills/progress-tracker/SKILL.md" },
     { "slug": "execute-plan", "path": "skills/execute-plan/SKILL.md" },
     { "slug": "validate-plan", "path": "skills/validate-plan/SKILL.md" },
-    { "slug": "audit-screenshots", "path": "skills/audit-screenshots/SKILL.md" }
+    { "slug": "audit-screenshots", "path": "skills/audit-screenshots/SKILL.md" },
+    { "slug": "idea-intake", "path": "skills/idea-intake/SKILL.md" },
+    { "slug": "prd-from-intake", "path": "skills/prd-from-intake/SKILL.md" },
+    { "slug": "adr-tech-decisions", "path": "skills/adr-tech-decisions/SKILL.md" },
+    { "slug": "prototype-orchestrator", "path": "skills/prototype-orchestrator/SKILL.md" },
+    { "slug": "gos-caveman", "path": "skills/gos-caveman/SKILL.md" },
+    { "slug": "gos-compress", "path": "skills/gos-compress/SKILL.md" },
+    { "slug": "figma-print-diff", "path": "skills/figma-print-diff/SKILL.md" },
+    { "slug": "ui-guardrails", "path": "skills/ui-guardrails/SKILL.md" },
+    { "slug": "cloudflare-pages-setup", "path": "skills/cloudflare-pages-setup/SKILL.md" },
+    { "slug": "typeform-form-pattern", "path": "skills/typeform-form-pattern/SKILL.md" },
+    { "slug": "timer-component-pattern", "path": "skills/timer-component-pattern/SKILL.md" }
   ]
 }

package/.gos/skills/timer-component-pattern/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: timer-component-pattern
+description: >
+  Gera componente Timer (countdown) React + TS com state machine, persistencia,
+  atalhos de teclado, edicao inline, tema dark/light, controles via Lucide React.
+  Baseado em code-kata-timer adaptado para React.
+argument-hint: "<descricao do uso ou 'spec' para ver anatomia>"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion]
+sourceDocs:
+  - libraries/timer-pattern-spec.md
+  - libraries/lucide-icons-policy.md
+  - libraries/ui-guardrails-checklist.md
+use-when:
+  - usuario pede pomodoro, code kata timer, countdown, contador regressivo
+  - precisa de timer com play/pause/reset/edit
+  - quer atalhos de teclado (Space, R, E)
+do-not-use-for:
+  - cronometro (countup) — variar via `mode: 'countup'` flag
+  - timer de polling (use TanStack Query refetchInterval)
+  - calendar/scheduler (use componente diferente)
+metadata:
+  category: ui-pattern
+---
+
+Voce esta executando como **Timer Pattern Generator** via skill `timer-component-pattern`. Gera componente React baseado em `libraries/timer-pattern-spec.md`.
+
+## Pre-flight
+
+1. AskUserQuestion:
+   - "Tempo default em segundos? (ex: 30 para code kata, 1500 para pomodoro 25min)"
+   - "Som ao terminar? (Web Audio beep / arquivo / nenhum)"
+   - "Tema dark/light togglavel? (sim / so dark / so light)"
+   - "Persistir entre sessoes? (localStorage / nao)"
+   - "Atalhos teclado? (sim default / nao)"
+   - "Editar tempo inline? (sim / nao — botao edit aparece se sim)"
+2. Validar stack: `lucide-react`, shadcn `Button`. Senao -> instruir instalacao.
+
+## Arquivos gerados
+
+```
+src/components/timer/
+  Timer.tsx                 # componente principal
+  hooks/
+    useTimer.ts             # hook com state machine
+    useTimerKeyboard.ts     # atalhos
+  utils/
+    formatTime.ts           # MM:SS
+    beep.ts                 # Web Audio (opcional)
+  types.ts                  # TimerStatus, TimerSettings
+```
+
+## Componente principal
+
+```tsx
+import { useEffect } from 'react';
+import { Play, Pause, RotateCcw, Pencil, Activity } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { useTimer } from './hooks/useTimer';
+import { useTimerKeyboard } from './hooks/useTimerKeyboard';
+import { TimerStatus, isRunning } from './types';
+import { formatTime } from './utils/formatTime';
+
+interface TimerProps {
+  defaultSeconds?: number;
+  onComplete?: (duration: number) => void;
+  enableEdit?: boolean;
+  enableKeyboard?: boolean;
+}
+
+export function Timer({
+  defaultSeconds = 30,
+  onComplete,
+  enableEdit = true,
+  enableKeyboard = true,
+}: TimerProps) {
+  const timer = useTimer(defaultSeconds);
+
+  useTimerKeyboard({
+    enabled: enableKeyboard,
+    status: timer.status,
+    actions: timer,
+  });
+
+  useEffect(() => {
+    function onDone(e: Event) {
+      const evt = e as CustomEvent<{ duration: number }>;
+      onComplete?.(evt.detail.duration);
+    }
+    window.addEventListener('timer:done', onDone);
+    return () => window.removeEventListener('timer:done', onDone);
+  }, [onComplete]);
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-8 py-12">
+      {/* Indicator */}
+      {isRunning(timer.status) && (
+        <Activity className="h-6 w-6 text-primary animate-pulse" aria-label="Em execucao" />
+      )}
+
+      {/* Display */}
+      {timer.status === TimerStatus.EDITING ? (
+        <input
+          type="number"
+          autoFocus
+          defaultValue={timer.seconds}
+          className="text-7xl md:text-9xl font-mono font-bold tabular-nums bg-transparent w-72 text-center outline-none border-b-2 border-primary"
+          onBlur={(e) => {
+            const v = Number(e.currentTarget.value);
+            if (v > 0) timer.setSeconds(v);
+            timer.setStatus(TimerStatus.STOPPED);
+          }}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') e.currentTarget.blur();
+            if (e.key === 'Escape') timer.setStatus(TimerStatus.STOPPED);
+          }}
+        />
+      ) : (
+        <div
+          className="text-7xl md:text-9xl font-mono font-bold tabular-nums"
+          aria-live="polite"
+          aria-atomic="true"
+        >
+          {formatTime(timer.seconds)}
+        </div>
+      )}
+
+      {/* Controls */}
+      <div className="flex gap-3">
+        {timer.status === TimerStatus.RUNNING ? (
+          <Button onClick={timer.pause} size="lg" aria-label="Pausar">
+            <Pause className="h-5 w-5" />
+          </Button>
+        ) : (
+          <Button
+            onClick={timer.start}
+            size="lg"
+            disabled={timer.seconds === 0}
+            aria-label="Iniciar"
+          >
+            <Play className="h-5 w-5" />
+          </Button>
+        )}
+
+        <Button
+          onClick={() => timer.reset()}
+          size="lg"
+          variant="outline"
+          aria-label="Resetar"
+        >
+          <RotateCcw className="h-5 w-5" />
+        </Button>
+
+        {enableEdit && (
+          <Button
+            onClick={() => timer.setStatus(TimerStatus.EDITING)}
+            size="lg"
+            variant="outline"
+            disabled={isRunning(timer.status)}
+            aria-label="Editar tempo"
+          >
+            <Pencil className="h-5 w-5" />
+          </Button>
+        )}
+      </div>
+
+      {/* Hint atalhos */}
+      {enableKeyboard && (
+        <p className="text-xs text-muted-foreground">
+          Espaco play/pause - R reset - E editar
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+## State machine (types.ts)
+
+Conforme `libraries/timer-pattern-spec.md`:
+
+```ts
+export const TimerStatus = {
+  STOPPED: 'STOPPED',
+  COUNTDOWN: 'COUNTDOWN',
+  RUNNING: 'RUNNING',
+  PAUSED: 'PAUSED',
+  EDITING: 'EDITING',
+} as const;
+
+export type TimerStatusType = typeof TimerStatus[keyof typeof TimerStatus];
+
+export const isRunning = (s: TimerStatusType) =>
+  s === TimerStatus.RUNNING || s === TimerStatus.COUNTDOWN;
+```
+
+## Hook useTimer (com persistencia opcional)
+
+Detalhe completo em `libraries/timer-pattern-spec.md`. Pontos criticos:
+- `setInterval` com cleanup em `useEffect` return + ao parar.
+- Ao restaurar `localStorage`: SEMPRE forcar status STOPPED (evita timer fantasma).
+- Dispatch `CustomEvent('timer:done')` ao zerar.
+
+## Estados visuais
+
+- **Loading**: NA.
+- **Empty**: tempo `00:00` -> Play disabled, mensagem "Tempo zerado, edite para comecar".
+- **Error**: NA em runtime.
+- **Running**: `Activity` icon pulsando + `animate-pulse` no display opcional.
+- **Done**: tela ou toast com `CheckCircle2` quando atinge 0.
+
+## Som ao terminar (utils/beep.ts)
+
+Web Audio API (sem assets):
+```ts
+export function beep(frequency = 800, duration = 200) {
+  const ctx = new (window.AudioContext || (window as any).webkitAudioContext)();
+  const osc = ctx.createOscillator();
+  osc.connect(ctx.destination);
+  osc.frequency.value = frequency;
+  osc.start();
+  setTimeout(() => { osc.stop(); ctx.close(); }, duration);
+}
+```
+
+Disparado em `useEffect` quando `seconds === 0 && previousSeconds !== 0`.
+
+## Modos disponiveis
+
+Flags do componente:
+- `mode="countdown"` (default) — diminui ate 0.
+- `mode="countup"` — sobe a partir de 0 (cronometro).
+- `mode="pomodoro"` — alterna 25min foco / 5min pausa.
+
+Cada modo so muda a logica do hook, UI e controles ficam iguais.
+
+## Anti-patterns embutidos (warning ao usuario)
+
+- "Sem cleanup de setInterval" -> recusar — gera memory leak.
+- "Restaurar status RUNNING do localStorage" -> recusar — timer fantasma.
+- "Emoji nos botoes" -> recusar — usar Lucide.
+- "Sem `tabular-nums`" -> warning — digitos pulam visualmente.
+
+## Input
+
+$ARGUMENTS