jarvis-ai-framework 1.0.0

package/workflows/engineering/frontend/eng.frontend-review.md

@@ -0,0 +1,185 @@
+---
+name: eng.frontend-review
+description: >
+  Workflow de revisão de código específico para PRs frontend: TypeScript, tokens,
+  acessibilidade, performance, micro frontend e design system.
+  Complementa o eng.review genérico com checklist frontend aprofundado.
+author: jarvis-team
+version: "1.0"
+
+---
+
+# Workflow: Revisão de Código Frontend
+
+## Contexto
+
+Use este workflow ao revisar PRs que envolvem componentes React, design system,
+micro frontend ou qualquer código de interface.
+
+**Skill de referência**: `eng-frontend`, `eng-design-system`, `eng-microfrontend`
+
+---
+
+## Como usar
+
+Execute para um PR específico ou para um conjunto de arquivos:
+
+```bash
+# Ler arquivos alterados no PR
+git diff origin/main...HEAD --name-only | grep -E "\.(tsx|ts|css|scss)$"
+
+# Ler cada arquivo alterado antes de revisar
+```
+
+---
+
+## Checklist de Revisão
+
+### 1. TypeScript
+
+- [ ] Sem `any` não documentado
+- [ ] Sem `@ts-ignore` sem comentário explicativo
+- [ ] Sem `!` (non-null assertion) sem verificação prévia
+- [ ] Props exportadas para componentes públicos
+- [ ] `strict: true` não relaxado
+
+**Flags de atenção:**
+```bash
+grep -n "as any\|@ts-ignore\|@ts-expect-error\| \! " {arquivo}
+```
+
+---
+
+### 2. Componentes
+
+- [ ] Single Responsibility — componente faz uma coisa só
+- [ ] Sem lógica de negócio acoplada ao componente de UI
+- [ ] Sem fetch direto no componente (usar hooks ou Server Components)
+- [ ] `forwardRef` em componentes com elemento DOM
+- [ ] Estados visuais tratados: loading, erro, vazio
+
+**Perguntas a fazer no review:**
+- "Este componente pertence ao design system ou ao remote?"
+- "Existe componente similar no design system que poderia ser usado?"
+- "Esta lógica deveria estar em um hook?"
+
+---
+
+### 3. Tokens e Design System
+
+- [ ] Cores via tokens semânticos (sem `#hex`, `rgb()`, `hsl()`)
+- [ ] Espaçamentos via escala do design system (sem px hardcodados inline)
+- [ ] Componentes reutilizáveis criados no design system, não duplicados por remote
+- [ ] Variantes com `cva` (não condicionais de classe espalhadas)
+
+**Flags de atenção:**
+```bash
+grep -n "#[0-9a-fA-F]\{3,6\}\|rgb(\|style={{" {arquivo}
+```
+
+---
+
+### 4. Acessibilidade
+
+- [ ] Semântica HTML correta (`<button>` para ações, `<a>` para navegação)
+- [ ] Imagens com `alt` (informativas: descritivo; decorativas: `alt=""`)
+- [ ] Formulários: `<label>` associado via `htmlFor` ou `aria-label`
+- [ ] Erros de form com `role="alert"` ou `aria-live`
+- [ ] Elementos interativos são navegáveis por teclado
+- [ ] Focus visível — `outline` não removido sem substituto
+
+**Flags de atenção:**
+```bash
+grep -n "outline-none\|outline: none\|tabIndex={-1}" {arquivo}
+# outline-none do Tailwind em elementos interativos sem focus-visible alternativo
+```
+
+---
+
+### 5. Performance
+
+- [ ] Sem `useEffect` para fetch de dados (usar React Query / Server Components)
+- [ ] Lazy loading em componentes pesados (`lazy()` + `<Suspense>`)
+- [ ] Dependências novas justificadas (avaliar impacto no bundle)
+- [ ] Memoização só onde necessário e comprovado (`memo`, `useMemo`, `useCallback`)
+- [ ] Imagens com `width` e `height` definidos
+
+**Perguntas a fazer:**
+- "Este componente precisa ser Client Component, ou funciona como Server Component?"
+- "Esta dependência nova já está no bundle ou é nova?"
+
+---
+
+### 6. Micro Frontend (se aplicável)
+
+- [ ] Sem import direto de outro remote
+- [ ] Comunicação via event bus ou props do shell
+- [ ] Contrato de interface atualizado se houver mudança na API exposta
+- [ ] Remote ainda funciona em modo standalone
+
+**Flag de atenção:**
+```bash
+# Import entre remotes (nunca deve existir)
+grep -n "from.*'apps/" {arquivo}
+grep -n "from.*'remote" {arquivo}
+```
+
+---
+
+### 7. Testes
+
+- [ ] Testes para o happy path
+- [ ] Testes para estado de erro
+- [ ] Queries por acessibilidade (`getByRole`, `getByLabelText`)
+- [ ] Sem `getByTestId` como primeira opção
+- [ ] Sem `act()` manual desnecessário
+
+---
+
+### 8. Código Geral
+
+- [ ] Sem `console.log` commitado
+- [ ] Sem `TODO` sem issue associada
+- [ ] Seguindo convenções de nomenclatura do projeto
+
+```bash
+grep -n "console\.log\|console\.error\|console\.warn" {arquivo}
+```
+
+---
+
+## Classificação do Feedback
+
+Use prefixos para clareza no review:
+
+```
+[bloqueante]  — deve ser resolvido antes do merge
+[sugestão]    — melhoria não obrigatória, mas recomendada
+[dúvida]      — pergunta para entender melhor a decisão
+[elogio]      — destacar o que foi bem feito
+```
+
+---
+
+## Output do Review
+
+```
+## Review Frontend — {título do PR}
+
+### Resumo
+{1-3 linhas: qual é a mudança e qual o impacto geral}
+
+### Pontos de atenção
+{lista dos [bloqueante] encontrados}
+
+### Sugestões
+{lista dos [sugestão]}
+
+### Dúvidas
+{lista dos [dúvida]}
+
+### Veredicto
+[ ] Aprovado
+[ ] Aprovado com ressalvas (sugestões não bloqueantes)
+[ ] Mudanças necessárias (bloqueantes listados acima)
+```

package/workflows/engineering/qa/eng.qa-dev-quality-guide.md

@@ -0,0 +1,51 @@
+---
+description: Orienta desenvolvedores sobre cobertura de testes para uma feature ou PR
+auto_execution_mode: 2
+rules_file: "$IDE/rules/engineering/qa/eng.qa.cypress-standards-rules.md"
+model_tier: medium
+model_justification: Análise de código e geração de orientação estruturada
+---
+
+# qa.dev-quality-guide
+
+Analisa o código de um desenvolvedor e orienta sobre quais testes Cypress escrever,
+usando os padrões do projeto. Não escreve o teste — guia e valida.
+
+> 📋 **Rules**: `$IDE/rules/engineering/qa/eng.qa.cypress-standards-rules.md`
+> 🔧 **Skill**: `eng-qa-dev-guide`
+
+---
+
+## Entrada
+
+```
+#$ARGUMENTS
+```
+
+Aceita: caminho de arquivo(s), ID de task no $TASK_MANAGER, ou diff/PR em texto.
+
+**Se não receber argumentos**, perguntar:
+- Qual arquivo ou PR do dev você quer analisar?
+
+---
+
+## Execução
+
+Invocar Skill tool: `eng-qa-dev-guide`
+
+A skill irá:
+1. Ler o código fornecido e mapear o que foi alterado/adicionado
+2. Verificar quais specs de teste já existem para o domínio
+3. Gerar análise de cobertura: o que está coberto vs. o que precisa de teste
+4. Orientar sobre como estruturar cada cenário (setup, intercept, ação, asserção)
+5. Indicar quais `data-testid` precisam ser adicionados
+6. Entregar checklist acionável para o dev
+
+---
+
+## Output
+
+- Análise de cobertura: coberto vs. crítico vs. recomendado
+- Orientação de implementação para cada cenário necessário
+- Checklist de testes a implementar antes do merge
+- Lista de `data-testid` pendentes no código

package/workflows/engineering/qa/eng.qa-e2e-test-generation.md

@@ -0,0 +1,51 @@
+---
+description: Gera testes E2E Cypress a partir de uma feature, task ou spec
+auto_execution_mode: 2
+rules_file: "$IDE/rules/engineering/qa/eng.qa.cypress-standards-rules.md"
+template_file: "$IDE/templates/engineering/qa/qa.cypress-test-template.md"
+model_tier: high
+model_justification: Requer análise de codebase, geração de Page Objects e specs completas
+---
+
+# qa.e2e-test-generation
+
+Gera testes E2E Cypress + TypeScript para uma feature a partir de spec, task ou descrição.
+
+> 📋 **Rules**: `$IDE/rules/engineering/qa/eng.qa.cypress-standards-rules.md`
+> 📤 **Template**: `$IDE/templates/engineering/qa/qa.cypress-test-template.md`
+> 🔧 **Skill**: `eng-qa-cypress-e2e`
+
+---
+
+## Entrada
+
+```
+#$ARGUMENTS
+```
+
+Aceita: caminho de spec/task, ID de task no $TASK_MANAGER, ou descrição do fluxo em linguagem natural.
+
+**Se não receber argumentos**, perguntar:
+- Qual feature ou fluxo deseja cobrir com testes E2E?
+
+---
+
+## Execução
+
+Invocar Skill tool: `eng-qa-cypress-e2e`
+
+A skill irá:
+1. Mapear a estrutura de testes existente no projeto
+2. Analisar o fluxo e identificar cenários (happy path, edge cases, negative tests)
+3. Confirmar cenários com o QA antes de gerar
+4. Gerar: Page Object + fixtures + custom commands (se necessário) + spec `.cy.ts`
+5. Exibir checklist de `data-testid` que precisam ser adicionados ao código da aplicação
+
+---
+
+## Output
+
+- `{TEST_FOLDER}/e2e/{dominio}/{feature}.cy.ts` — spec gerada
+- `{TEST_FOLDER}/support/pages/{Dominio}Page.ts` — Page Object (novo ou atualizado)
+- `{TEST_FOLDER}/fixtures/{dominio}/*.json` — fixtures de intercept
+- Checklist de `data-testid` pendentes no código da aplicação

package/workflows/engineering/qa/eng.qa-exploratory-session.md

@@ -0,0 +1,60 @@
+---
+description: Conduz sessão de teste exploratório estruturada com charter, roteiro de risco e registro de achados
+auto_execution_mode: 2
+rules_file: "$IDE/rules/engineering/qa/eng.qa.exploratory-session-rules.md"
+template_file: "$IDE/templates/engineering/qa/qa.exploratory-session-template.md"
+model_tier: medium
+model_justification: Análise de risco e estruturação de sessão — raciocínio moderado
+---
+
+# qa.exploratory-session
+
+Conduz ou documenta uma sessão de teste exploratório, gerando o doc de sessão estruturado
+e criando cards de bug via `eng-qa-bug-report` ao final.
+
+> 📋 **Rules**: `$IDE/rules/engineering/qa/eng.qa.exploratory-session-rules.md`
+> 📤 **Template**: `$IDE/templates/engineering/qa/qa.exploratory-session-template.md`
+> 🔧 **Skill**: `eng-qa-exploratory`
+
+---
+
+## Entrada
+
+```
+#$ARGUMENTS
+```
+
+Aceita: nome da feature/módulo a explorar, ou caminho de doc de sessão já realizada.
+
+**Se não receber argumentos**, a skill perguntará o modo desejado:
+- `plan` — planejar sessão antes de executar
+- `document` — registrar achados de sessão já realizada
+- `report` — processar doc e criar bug cards
+
+---
+
+## Execução
+
+Invocar Skill tool: `eng-qa-exploratory`
+
+A skill irá (modo `plan`):
+1. Coletar escopo, contexto, tempo disponível e ambiente
+2. Analisar riscos e gerar hipóteses priorizadas
+3. Criar doc de sessão em `$SESSIONS_DIR/qa/EXP-{YYYYMMDD}-{N}.md`
+
+A skill irá (modo `document`):
+1. Carregar doc de sessão existente
+2. Coletar achados em linguagem natural do QA
+3. Classificar severidade e preencher o documento
+4. Acionar `eng-qa-bug-report` para bugs S1–S4
+
+A skill irá (modo `report`):
+1. Processar doc de sessão
+2. Criar todos os cards de bug em batch via `eng-qa-bug-report`
+
+---
+
+## Output
+
+- `$SESSIONS_DIR/qa/EXP-{ID}.md` — documento de sessão estruturado
+- Cards criados no $TASK_MANAGER para cada bug S1–S4

package/workflows/engineering/qa/eng.qa-quality-gate-validation.md

@@ -0,0 +1,202 @@
+---
+description: Validação de quality gate de uma tech spec antes do breakdown de subtarefas
+auto_execution_mode: 2
+agent: "$IDE/agents/engineering/qa/eng.qa.quality-champion-task-agent.md"
+rules_file: "$IDE/rules/engineering/qa/eng.qa.tech-spec-validation-criteria-rules.md"
+recommended_model: claude-sonnet-4-20250514
+model_tier: medium
+model_justification: Validação estruturada de specs contra critérios definidos — não requer raciocínio arquitetural complexo
+---
+
+# Quality Gate - Tech Spec
+
+## Skill recomendado
+
+Use o skill `eng-qa-gate` como fonte de verdade para o processo de validação e formato de saída:
+
+- Arquivo: `$IDE/skills/eng-qa-gate/SKILL.md`
+
+## Agente Ativado
+
+`$IDE/agents/engineering/qa/eng.qa.quality-champion-task-agent.md`
+
+Este workflow ativa o **Quality Champion Agent**, especializado em validação de qualidade de tarefas Jira e especificações técnicas.
+
+## Instrução
+
+Você é o assistente especializado em Quality Assurance, atuando como um Quality Champion digital para validação de **Especificações Técnicas (Tech Specs)**. Seu papel é garantir que toda tech spec atenda aos padrões de qualidade estabelecidos antes de prosseguir para o breakdown de subtarefas.
+
+## Seu Conhecimento Base
+
+Você tem acesso completo ao:
+
+- "Guia de Qualidade e Boas Práticas" do time
+- Padrão de "Descrição de Bugs"
+- Template de Tech Spec do time
+
+Esses documentos definem os quality gates (pontos de bloqueio automático), processos, checklists e boas práticas adotados.
+
+## Suas Responsabilidades
+
+1. **Validar estrutura da Tech Spec**: Verificar se todos os elementos obrigatórios estão presentes e bem definidos
+2. **Aplicar critérios de bloqueio**: Alertar quando algo não atende aos quality gates
+3. **Promover qualidade**: Sugerir melhorias específicas e garantir que os checklists sejam seguidos
+4. **Documentar análise**: Adicionar comentário detalhado no card do Jira com resultado da validação
+5. **Classificar conformidade**: Adicionar label apropriada no card
+
+## Como Você Deve Atuar
+
+- Seja **objetivo e direto** ao validar estruturas
+- Use os **templates e padrões** dos documentos como referência
+- Aponte **claramente** quando algo não atende aos critérios de bloqueio
+- Sugira **correções específicas** baseadas nos padrões documentados
+- Mantenha o foco na **cultura de qualidade** e responsabilidade compartilhada
+
+## Critérios de Validação
+
+Os critérios completos de validação por tipo de card (Task, Spike, Bug) estão documentados em:
+
+📋 **[Critérios de Validação de Tech Spec]($IDE/rules/engineering/qa/eng.qa.tech-spec-validation-criteria-rules.md)**
+
+**Resumo dos principais critérios**:
+
+### Tasks
+
+- Descrição, Critérios de Aceitação, Cenários de Teste, Análise Técnica, Dependências
+
+### Spikes
+
+- Objetivo, **Referências de Discovery** (crítico!), Critérios de Conclusão, Contexto
+
+### Bugs
+
+- Descrição do Bug, Passos para Reproduzir, Análise Técnica, Severidade
+
+## Sistema de Classificação
+
+O sistema de pontuação e regras de bloqueio estão documentados em:
+
+🎯 **[Regras de Classificação de Score]($IDE/rules/engineering/qa/eng.qa.quality-gate-scoring-rules.md)**
+
+**Resumo das faixas**:
+
+- **100%** → ✅ Conforme → `QualityGate::Conforme` → Pode prosseguir
+- **50-99%** → ⚠️ Parcial → `QualityGate::Parcial` → Pode com ressalvas
+- **< 50%** → 🚫 Bloqueado → `QualityGate::Bloqueado` → Não pode prosseguir
+
+## Processo de Análise
+
+Siga este fluxo para validar uma tech spec:
+
+1. **Receber contexto do card** via parâmetros ou busca no Jira
+   - Incluir comentários para contexto adicional
+
+2. **Identificar tipo do card** (Task, Spike ou Bug)
+
+3. **Aplicar critérios específicos** do tipo identificado
+   - Consulte: [tech-spec-validation.md]($IDE/rules/engineering/qa/eng.qa.tech-spec-validation-criteria-rules.md)
+
+4. **Calcular score de conformidade** (0-100%)
+   - Consulte: [score-classification.md]($IDE/rules/engineering/qa/eng.qa.quality-gate-scoring-rules.md)
+
+5. **Estruturar análise** seguindo o template:
+   - Status (Conforme/Parcial/Bloqueado)
+   - Pontos positivos
+   - Problemas identificados (bloqueantes primeiro)
+   - Recomendações acionáveis
+
+6. **Gerar comentário no Jira** seguindo o template padrão
+
+7. **Adicionar label de Quality Gate** apropriada
+
+## Formato de Resposta
+
+Use o template padrão de comentário documentado em:
+
+📝 **[Template de Comentário]($IDE/templates/engineering/qa/eng.qa.quality-gate-report-template.md)**
+
+**Estrutura base**:
+
+```markdown
+## 🎯 Quality Gate - Tech Spec
+
+**Status**: [✅/⚠️/🚫]
+**Score**: X/100
+**Tipo de Card**: [Task/Spike/Bug]
+
+### ✅ Pontos Positivos
+
+### 🚫 Problemas Identificados
+
+### 🔧 Recomendações
+
+### 📚 Referência
+```
+
+## Exemplos de Análise
+
+Para referência de como estruturar análises em diferentes cenários, consulte:
+
+💡 **[Exemplos de Análise]($IDE/templates/engineering/qa/eng.qa.quality-gate-examples-template.md)**
+
+Disponíveis:
+
+- Task Conforme (100%)
+- Spike Bloqueado (30%)
+- Bug Parcial (70%)
+- Task Parcial - Faltam Testes (80%)
+
+## Labels de Quality Gate
+
+Adicione UMA das seguintes labels após análise:
+
+- `QualityGate::Conforme` - Score 100% (todos os critérios obrigatórios atendidos)
+- `QualityGate::Parcial` - Score 50-99% (alguns critérios obrigatórios faltando)
+- `QualityGate::Bloqueado` - Score < 50% (muitos critérios críticos faltando)
+
+**IMPORTANTE**: Apenas cards com `QualityGate::Conforme` podem prosseguir para o breakdown de subtarefas.
+
+## Estilo de Comunicação
+
+- Respostas **objetivas** e de fácil entendimento para engenheiros seniores
+- **Markdown** com estruturação clara
+- Foco nos **gaps** e **ações necessárias**
+- Sem excesso de formalidade
+- **SEM menções** - removidas do processo
+- Use checkboxes para facilitar acompanhamento de correções
+
+## Fluxo de Execução no Workflow Automático
+
+Este prompt é executado automaticamente pelo workflow `build_tech_spec` na etapa de Quality Gate:
+
+1. **Load da Tech Spec** - Carregada da sessão
+2. **Validação** - Você analisa seguindo os critérios
+3. **Geração de JSON** - Você retorna resultado estruturado:
+   ```json
+   {
+     "status": "Conforme|Parcial|Bloqueado",
+     "score": 0-100,
+     "analysis": "Análise completa em Markdown"
+   }
+   ```
+4. **Processamento Automático**:
+   - Label adicionada automaticamente
+   - Comentário publicado no Jira
+   - Se Conforme → Prossegue para Breakdown
+   - Se Parcial/Bloqueado → Workflow para
+
+## Lembrete Final
+
+Seu objetivo é assegurar que cada tech spec mantenha o alto padrão de qualidade estabelecido pelo time, **sem criar sobrecarga**, mas **garantindo excelência técnica** e **clareza para implementação**.
+
+Uma tech spec bem validada economiza tempo de desenvolvimento, reduz retrabalho e aumenta a previsibilidade das entregas.
+
+---
+
+## Referências Rápidas
+
+- 📋 [Critérios de Validação]($IDE/rules/engineering/qa/eng.qa.tech-spec-validation-criteria-rules.md)
+- 🎯 [Regras de Score]($IDE/rules/engineering/qa/eng.qa.quality-gate-scoring-rules.md)
+- 📝 [Template de Comentário]($IDE/templates/engineering/qa/eng.qa.quality-gate-report-template.md)
+- 💡 [Exemplos Práticos]($IDE/templates/engineering/qa/eng.qa.quality-gate-examples-template.md)
+- 📚 Wiki - Processos (consultar documentação interna do projeto)

package/workflows/engineering/qa/eng.qa-quality-report.md

@@ -0,0 +1,83 @@
+---
+description: Gera relatório de qualidade consolidado para uma sprint ou release
+auto_execution_mode: 2
+rules_file: "$IDE/rules/engineering/qa/eng.qa.exploratory-session-rules.md"
+template_file: "$IDE/templates/engineering/qa/qa.quality-report-template.md"
+model_tier: medium
+model_justification: Consolidação de dados locais e síntese analítica
+---
+
+# qa.quality-report
+
+Consolida sessões exploratórias, bug reports e quality gates do período e gera
+relatório de qualidade em markdown pronto para publicar.
+
+> 📤 **Template**: `$IDE/templates/engineering/qa/qa.quality-report-template.md`
+> 🔧 **Skill**: `eng-qa-quality-report`
+
+> ⚠️ **Skill pendente (Fase 5)**: `eng-qa-quality-report` ainda não foi implementada.
+> Será criada após ciclos reais de uso das skills `eng-qa-cypress-e2e`, `eng-qa-exploratory` e `eng-qa-dev-guide`.
+> Por enquanto, ao invocar este workflow o agente deve avisar o usuário e sugerir consolidação manual
+> usando o template `$TEMPLATES_FOLDER/engineering/qa/qa.quality-report-template.md`.
+
+---
+
+## Entrada
+
+```
+#$ARGUMENTS
+```
+
+Aceita: período em texto livre (ex: "Sprint 42", "release 1.4", "abril/2026").
+
+**Se não receber argumentos**, perguntar:
+- Qual período deseja cobrir no relatório? (ex: Sprint N, release X.Y, mês)
+
+---
+
+## Execução
+
+Invocar Skill tool: `eng-qa-quality-report`
+
+A skill irá:
+1. Localizar docs do período em `$SESSIONS_DIR/qa/`
+2. Localizar bug reports relacionados (via $TASK_MANAGER ou docs locais)
+3. Consolidar métricas: sessões, bugs por severidade, quality gates, cobertura E2E
+4. Identificar tendências e áreas de risco
+5. Gerar relatório usando o template de quality report
+6. Salvar em `$DOCS_FOLDER/engineering/qa/reports/QA-REPORT-{SQUAD}-{PERIODO}.md`
+
+---
+
+## Output
+
+- `$DOCS_FOLDER/engineering/qa/reports/QA-REPORT-{SQUAD}-{PERIODO}.md` — relatório completo
+
+---
+
+## Publicação no Central Docs (condicional)
+
+Se `CENTRAL_DOCS_REPO` estiver configurado no ENV.md:
+
+1. Verificar se o relatório tem frontmatter válido (period, squad, version)
+2. Perguntar ao usuário: "Publicar relatório no central-docs?"
+3. Se sim:
+
+```bash
+jarvis docs publish \
+  --file $DOCS_FOLDER/engineering/qa/reports/QA-REPORT-{SQUAD}-{PERIODO}.md \
+  --tipo qa-report \
+  --feature {squad}-{periodo-slug}
+```
+
+Exemplo de feature slug: `core-sprint-42`, `checkout-release-1-4`
+
+- ✅ Sucesso: "Relatório publicado no central-docs. MR criado: [URL]"
+- ❌ Erro de frontmatter: orientar o usuário a preencher os campos `period`, `squad` e `version`
+- ℹ️ Recusou: "Para publicar depois, execute: `jarvis docs publish --file {caminho} --tipo qa-report --feature {slug}`"
+
+Se `CENTRAL_DOCS_REPO` não estiver definido:
+- Informar: "Para habilitar publicação automática, configure `CENTRAL_DOCS_REPO` no ENV.md"
+
+> **Nota**: A publicação cria um Merge Request no GitLab. O relatório só será visível no central-docs após aprovação e merge do MR.
+> O destino no central-docs é: `{SQUAD}/{PRODUCT}/engineering/qa/qa-report-{feature}.md`