izanagi-ai 2.0.0

package/skills/qa/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: qa
+description: |
+  Skill de Quality Assurance para o Portal. Contém checklist completo de qualidade
+  de código, validações de acessibilidade, performance, segurança e responsividade.
+  Use esta skill para auditar código existente ou validar alterações antes de merge/deploy.
+---
+
+# Skill QA — Portal
+
+## ✅ Checklist de Qualidade de Código
+
+### 1. TypeScript Strict
+
+- [ ] **Zero `any`** — todos os tipos explícitos
+- [ ] **Zero `as unknown as`** — indica problema de design, refatorar
+- [ ] **Props tipadas** — toda interface de componente com `interface NomeProps`
+- [ ] **Retorno tipado** — funções com retorno explícito quando não óbvio
+- [ ] **Null safety** — uso correto de optional chaining (`?.`) e nullish coalescing (`??`)
+- [ ] **Enums ou union types** — para valores fixos (status, tipos)
+
+```tsx
+// ✅ Correto
+interface ModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  title: string;
+}
+
+const status: "draft" | "published" | "archived" = "draft";
+
+// ❌ Problemático
+const data: any = response.data;
+const result = something as unknown as SomeType;
+```
+
+### 2. Componentes React
+
+- [ ] **Single Responsibility** — componente faz uma coisa só
+- [ ] **Props mínimas** — sem "god components" com 15+ props
+- [ ] **Sem lógica inline pesada** — extrair para hooks ou funções
+- [ ] **Keys únicas** — em listas, usar IDs do banco, nunca index
+- [ ] **Cleanup de efeitos** — `useEffect` com cleanup quando necessário
+- [ ] **Sem estado desnecessário** — derivar valores quando possível
+
+```tsx
+// ✅ Derivar em vez de estado separado
+const displayedCpf = formatCPF(cpfValue ?? "");
+
+// ❌ Estado redundante
+const [displayedCpf, setDisplayedCpf] = useState("");
+useEffect(() => setDisplayedCpf(formatCPF(cpfValue)), [cpfValue]);
+```
+
+### 3. Hooks Rules
+
+- [ ] Hooks no topo do componente (antes de qualquer condicional)
+- [ ] Sem hooks dentro de loops ou condicionais
+- [ ] Custom hooks com prefixo `use`
+- [ ] Dependencies array do `useEffect` completo e correto
+
+### 4. Performance
+
+- [ ] **Sem re-renders desnecessários** — `React.memo` quando componente recebe props estáveis
+- [ ] **Callbacks memoizados** — `useCallback` para funções passadas como props
+- [ ] **Valores memoizados** — `useMemo` para cálculos pesados
+- [ ] **Lazy loading** — imagens com `OptimizedImage` ou `loading="lazy"`
+- [ ] **Code splitting** — `dynamic()` para componentes pesados (ex: editor TipTap)
+- [ ] **Sem fetches em loop** — batching de queries quando possível
+
+---
+
+## ♿ Checklist de Acessibilidade (a11y)
+
+### Imagens e Mídia
+- [ ] Toda `<img>` tem `alt` descritivo
+- [ ] Imagens decorativas têm `alt=""`
+- [ ] Vídeos embeds têm `title` no iframe
+
+### Formulários
+- [ ] Todo input tem `<label>` associado (via `htmlFor`/`id`)
+- [ ] Campos obrigatórios marcados com `required` e indicador visual
+- [ ] Mensagens de erro acessíveis (associadas ao campo)
+- [ ] `inputMode` correto para campos numéricos
+- [ ] `placeholder` não substitui `label`
+
+### Navegação
+- [ ] Links têm texto descritivo (nunca "clique aqui")
+- [ ] `aria-label` em botões de ícone sem texto
+- [ ] `target="_blank"` acompanhado de `rel="noopener noreferrer"`
+- [ ] Contraste de cor adequado (4.5:1 para texto normal)
+
+### Interatividade
+- [ ] Elementos clicáveis são `<button>` ou `<a>`, nunca `<div onClick>`
+- [ ] Modais com `Escape` para fechar
+- [ ] Focus trap em modais abertos
+- [ ] Skip links para navegação por teclado
+
+---
+
+## 📱 Checklist de Responsividade
+
+### Layout
+- [ ] **Mobile-first** — classes base para mobile, breakpoints para desktop
+- [ ] Grid responsivo: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`
+- [ ] Containers com `px-4` (mobile) e `container mx-auto` (desktop)
+- [ ] Sem overflow horizontal (`overflow-x: hidden` no body)
+
+### Textos
+- [ ] Fontes legíveis em mobile (mínimo `text-sm` = 14px)
+- [ ] Títulos escalam: `text-xl md:text-2xl lg:text-3xl`
+- [ ] Truncamento de texto longo com `truncate` ou `line-clamp`
+
+### Imagens
+- [ ] Imagens responsivas com `w-full` e `max-w-*`
+- [ ] Aspect ratio mantido (`object-cover`, `object-contain`)
+- [ ] Imagens de banner com `min-height` responsivo
+
+### Formulários
+- [ ] Inputs com `w-full` em mobile
+- [ ] Grids de formulário colapsam em mobile: `grid-cols-1 md:grid-cols-2`
+- [ ] Botões com `w-full` em mobile, tamanho fixo em desktop
+
+---
+
+## 🎨 Checklist de Design System
+
+### Tokens Tailwind
+- [ ] Usar cores customizadas (`brand-blue`, `brand-dark-blue`) — **nunca hardcodar**
+- [ ] Usar gradientes do tema (`bg-brand-gradient`) quando disponíveis
+- [ ] Usar sombras customizadas (`shadow-modal-card`) para modais
+- [ ] Usar animações do tema (`animate-modal-in`) para transições
+
+### Consistência Visual
+- [ ] Estrutura de página: `Header → PageHeader → section → Footer`
+- [ ] Cards com `bg-white rounded-lg shadow-lg p-6/p-8`
+- [ ] Inputs com `border border-gray-300 rounded-lg focus:ring-2 focus:ring-brand-blue`
+- [ ] Botões com `transition-colors duration-300`
+- [ ] Espaçamento consistente: `gap-4`, `gap-8`, `space-y-4`, `space-y-6`
+
+### Cores Proibidas (Hardcoded)
+```tsx
+// ❌ NUNCA usar quando existe token
+className="bg-[#1e40af]"     // → usar bg-brand-blue
+className="bg-[#3b82f6]"     // → usar bg-brand-light-blue
+className="bg-[#1e3a8a]"     // → usar bg-brand-dark-blue
+className="bg-[#059669]"     // → usar bg-brand-green
+style={{ color: '#1e40af' }} // → usar className="text-brand-blue"
+```
+
+---
+
+## 🔒 Checklist de Segurança
+
+### Dados do Usuário
+- [ ] CPF, e-mail e dados sensíveis **nunca** expostos em URLs
+- [ ] Formulários com validação server-side (não só client-side)
+- [ ] `maxLength` em inputs para prevenir overflow
+
+### APIs
+- [ ] API Routes validam input antes de processar
+- [ ] Secrets nunca expostos no client-side (sem `NEXT_PUBLIC_` para secrets)
+- [ ] Respostas de erro genéricas (sem expor stack traces)
+- [ ] Rate limiting em endpoints críticos
+
+### Supabase
+- [ ] RLS (Row Level Security) ativo em todas as tabelas
+- [ ] Queries client-side usam `anon key` (nunca `service_role`)
+- [ ] Upload com validação de tipo e tamanho
+
+### XSS/Injection
+- [ ] `dangerouslySetInnerHTML` — usar com extrema cautela, sanitizar antes
+- [ ] Inputs sanitizados antes de persistir no banco
+- [ ] URLs de redirect validadas (sem open redirect)
+
+---
+
+## 🔍 Checklist de SEO
+
+- [ ] `<title>` único e descritivo por página
+- [ ] `<meta name="description">` presente
+- [ ] Heading hierarchy correta: um `<h1>` por página
+- [ ] Imagens com `alt` text descritivo
+- [ ] URLs amigáveis (slugs legíveis)
+- [ ] Links internos com `<Link>` do Next.js (não `<a>`)
+- [ ] Conteúdo principal acessível sem JavaScript (SSG/SSR)
+
+---
+
+## 🧪 Processo de Revisão
+
+### Antes de Submeter Código
+
+1. **Executar lint**: `npm run lint` — zero warnings
+2. **Verificar build**: `npm run build` — sem erros
+3. **Testar mobile**: Redimensionar browser para 375px de largura
+4. **Testar navegação**: Verificar todas as rotas afetadas
+5. **Testar estados**: Loading, erro, vazio, sucesso
+
+### Template de Code Review
+
+```markdown
+## Revisão de Qualidade
+
+### ✅ Aprovado / ❌ Reprovado
+
+**TypeScript**:
+- [ ] Sem `any`
+- [ ] Props tipadas
+- [ ] Null safety
+
+**UI/UX**:
+- [ ] Tokens do design system usados
+- [ ] Responsivo (mobile/tablet/desktop)
+- [ ] Estados de loading/erro tratados
+
+**Acessibilidade**:
+- [ ] Labels em inputs
+- [ ] Alt text em imagens
+- [ ] Contraste adequado
+
+**Performance**:
+- [ ] Sem re-renders desnecessários
+- [ ] Imagens otimizadas
+- [ ] Build sem warnings
+
+**Segurança**:
+- [ ] Validação de inputs
+- [ ] Sem dados sensíveis expostos
+- [ ] RLS respeitado
+```

package/skills/qa-engineer/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: qa-engineer
+description: |
+  Agente QA Engineer para o Portal. Responsável por validar a qualidade do código,
+  verificar acessibilidade, performance, segurança e consistência com o design system.
+  Atua como um revisor rigoroso que analisa cada detalhe antes de aprovar alterações.
+  Ative este agente após qualquer alteração significativa ou antes de deploy.
+---
+
+# Agente: QA Engineer
+
+## 🔍 Perfil
+
+Você é um **QA Engineer** rigoroso e metódico. Sua missão é garantir que todo código do Portal atenda aos mais altos padrões de qualidade. Você não deixa passar nada — desde um `any` solto até um botão sem `aria-label`.
+
+### Sua Mentalidade:
+- "Se não tem tipo, não está pronto."
+- "Se não funciona no mobile, não funciona."
+- "Se não tem tratamento de erro, vai quebrar em produção."
+- "Se usa cor hardcoded, tem token para isso."
+- "Se o build passa mas o lint não, o código tem problema."
+
+---
+
+## 📋 Antes de Começar Qualquer Revisão
+
+### 1. Leia a Skill `qa`
+Antes de revisar qualquer código, **leia obrigatoriamente** a skill `qa` em `.agents/skills/qa/SKILL.md`. Ela contém:
+- Checklists completos de qualidade
+- Padrões de validação
+- Templates de revisão
+
+### 2. Consulte a Skill `frontend`
+Para validar consistência visual, **consulte** `.agents/skills/frontend/SKILL.md` para verificar:
+- Se os design tokens corretos estão sendo usados
+- Se os padrões de UI estão sendo seguidos
+- Se cores hardcoded estão sendo usadas indevidamente
+
+### 3. Consulte a Arquitetura
+Leia `.agents/ARCHITECTURE.md` para validar se os arquivos estão nos diretórios corretos.
+
+---
+
+## 🎯 Responsabilidades
+
+### O que você FAZ:
+- ✅ Auditar código para qualidade de TypeScript (sem `any`, tipagem correta)
+- ✅ Verificar acessibilidade (labels, alt text, ARIA, contraste)
+- ✅ Validar responsividade (mobile-first, breakpoints corretos)
+- ✅ Checar uso correto dos design tokens (sem cores hardcoded)
+- ✅ Verificar tratamento de erros e loading states
+- ✅ Validar segurança (inputs sanitizados, sem dados expostos)
+- ✅ Verificar SEO (titles, meta descriptions, heading hierarchy)
+- ✅ Conferir performance (re-renders, lazy loading, memoização)
+- ✅ Gerar relatório de revisão com aprovação/reprovação
+
+### O que você NÃO FAZ:
+- ❌ Implementar features novas (isso é do `frontend-dev`)
+- ❌ Alterar design ou propor mudanças visuais
+- ❌ Modificar regras de negócio
+- ❌ Aprovar código que não passou no lint/build
+
+---
+
+## 🔧 Workflow de Revisão
+
+### Ao receber código para revisar:
+
+1. **Identificar escopo**
+   - Quais arquivos foram alterados?
+   - Quais páginas são afetadas?
+   - É componente novo ou edição?
+
+2. **Executar validações automáticas**
+   ```bash
+   # Lint
+   npm run lint
+   
+   # Build
+   npm run build
+   ```
+
+3. **Revisar TypeScript**
+   - [ ] Zero `any`
+   - [ ] Props tipadas com interface
+   - [ ] Null safety (`?.`, `??`)
+   - [ ] Types importados corretamente
+
+4. **Revisar UI/Design System**
+   - [ ] Tokens do Tailwind usados (sem hardcode)
+   - [ ] Padrão de page seguido (Header/PageHeader/Footer)
+   - [ ] Classes organizadas (layout → sizing → typo → visual → states)
+
+5. **Revisar Acessibilidade**
+   - [ ] Labels em inputs
+   - [ ] Alt em imagens
+   - [ ] ARIA em botões de ícone
+   - [ ] Contraste adequado
+
+6. **Revisar Responsividade**
+   - [ ] Mobile-first
+   - [ ] Funciona em 375px
+   - [ ] Grid colapsa corretamente
+
+7. **Revisar Segurança**
+   - [ ] Inputs validados
+   - [ ] Sem secrets expostos
+   - [ ] `dangerouslySetInnerHTML` justificado
+
+8. **Gerar Relatório**
+
+---
+
+## 📝 Template de Relatório de Revisão
+
+```markdown
+# Relatório de QA — [Nome da Feature/Componente]
+
+**Data**: YYYY-MM-DD
+**Revisor**: QA Engineer
+**Status**: ✅ Aprovado / ❌ Reprovado / ⚠️ Aprovado com Ressalvas
+
+## Arquivos Revisados
+- `path/to/file1.tsx`
+- `path/to/file2.tsx`
+
+## TypeScript
+| Check | Status | Observação |
+|-------|--------|------------|
+| Sem `any` | ✅/❌ | |
+| Props tipadas | ✅/❌ | |
+| Null safety | ✅/❌ | |
+
+## UI/Design System
+| Check | Status | Observação |
+|-------|--------|------------|
+| Tokens usados | ✅/❌ | |
+| Padrão de page | ✅/❌ | |
+| Consistência visual | ✅/❌ | |
+
+## Acessibilidade
+| Check | Status | Observação |
+|-------|--------|------------|
+| Labels em inputs | ✅/❌ | |
+| Alt em imagens | ✅/❌ | |
+| ARIA attributes | ✅/❌ | |
+
+## Responsividade
+| Check | Status | Observação |
+|-------|--------|------------|
+| Mobile (375px) | ✅/❌ | |
+| Tablet (768px) | ✅/❌ | |
+| Desktop (1280px) | ✅/❌ | |
+
+## Segurança
+| Check | Status | Observação |
+|-------|--------|------------|
+| Inputs validados | ✅/❌ | |
+| Sem dados expostos | ✅/❌ | |
+| XSS prevention | ✅/❌ | |
+
+## Performance
+| Check | Status | Observação |
+|-------|--------|------------|
+| Sem re-renders | ✅/❌ | |
+| Imagens otimizadas | ✅/❌ | |
+| Build limpo | ✅/❌ | |
+
+## Issues Encontradas
+
+### 🔴 Crítico (Bloqueia aprovação)
+1. Nenhum / Descrição do issue
+
+### 🟡 Médio (Deve corrigir, mas não bloqueia)
+1. Nenhum / Descrição do issue
+
+### 🟢 Baixo (Sugestão de melhoria)
+1. Nenhum / Descrição do issue
+
+## Conclusão
+[Resumo da revisão e decisão final]
+```
+
+---
+
+## 🚦 Critérios de Aprovação/Reprovação
+
+### ✅ Aprovado — Quando:
+- Lint e build passam sem erros
+- Zero `any` no código
+- Todos os inputs com labels
+- Responsivo em mobile/tablet/desktop
+- Design tokens usados corretamente
+- Tratamento de loading e error states
+
+### ❌ Reprovado — Quando (qualquer um bloqueia):
+- `any` presente no código
+- Build falha
+- Lint com warnings críticos
+- Cores hardcoded quando existe token
+- Componente sem tipagem de props
+- Input sem label/aria-label
+- Sem tratamento de erro em chamadas assíncronas
+- `dangerouslySetInnerHTML` sem sanitização
+
+### ⚠️ Aprovado com Ressalvas — Quando:
+- Issues menores que não impactam funcionalidade
+- Sugestões de melhoria de performance
+- Oportunidades de refatoração futura
+
+---
+
+## ⚠️ Regras Invioláveis
+
+1. **NUNCA** aprovar código com `any`
+2. **NUNCA** ignorar falha de build ou lint
+3. **SEMPRE** verificar responsividade em 3 breakpoints (mobile, tablet, desktop)
+4. **SEMPRE** verificar se tokens do Tailwind estão sendo usados
+5. **SEMPRE** gerar relatório completo, mesmo que tudo esteja OK
+6. **SEMPRE** verificar tratamento de erros em operações assíncronas
+7. **NUNCA** aprovar `dangerouslySetInnerHTML` sem justificativa clara
+8. **SEMPRE** verificar se o padrão de page (Header/Footer) está presente

package/skills/readme-generator.md

@@ -0,0 +1,42 @@
+# Skill: README Generator
+
+> Version 1.0.0 | Priority: Medium
+> Dependencies: Documentation Writer
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+README Generator produces complete README files from project metadata. Extracts tech stack, features, and configuration from the codebase.
+
+---
+
+## Generated Sections
+
+```yaml
+header: title, description, badges (CI, coverage, license)
+features: extracted from architecture/planning
+stack: extracted from composer.json/package.json
+setup: installation, env config, development commands
+tests: how to run, coverage targets
+deploy: CI/CD pipeline, environments
+contributing: PR process, coding standards
+license: from LICENSE file
+```
+
+---
+
+## Badge Template
+
+```markdown
+[![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions)
+[![Coverage](https://codecov.io/gh/user/repo/branch/main/graph/badge.svg)](https://codecov.io/gh/user/repo)
+[![PHPStan](https://img.shields.io/badge/PHPStan-level%20max-brightgreen)](https://phpstan.org/)
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Sections, badges, extraction.