jarvis-ai-framework 1.0.0

package/rules/engineering/eng.work-rules.md

@@ -0,0 +1,312 @@
+---
+trigger: always_on
+---
+
+> **Applies to:** HUB: all | POSITION: all | AREA: ENGINEERING | SQUAD: all
+
+# Regras do Workflow Work
+
+## Propósito
+
+O workflow `work` tem como **único objetivo** implementar código seguindo o plano de execução (`plan.md`). É uma etapa de **codificação pura**, sem commits ou PRs.
+
+---
+
+## ⛔ Gate 0: Pré-requisitos Obrigatórios
+
+> Esta regra é executada **antes de qualquer ação**. Se qualquer condição falhar, o workflow para imediatamente.
+
+### Regra 0.1 — TASK_MANAGER_KEY obrigatório
+
+Ler `TASK_MANAGER` do ENV.md. Ver `eng.integrations-rules.md` (freelance vs board).
+
+Se `$ARGUMENTS` não trouxer o key: **perguntar e aguardar**. Não inventar. Não exigir `XXX-000`.
+
+- Freelance (`TASK_MANAGER` vazio): *Qual o seu número de controle para esta tarefa?*
+- Com board: *Qual o id do card no {TASK_MANAGER}?*
+
+Sem resposta → **PARAR**. Com resposta → seguir (pasta/branch em lowercase).
+
+### Regra 0.2 — Proibido executar em branch protegida
+
+Verificar branch atual:
+
+```bash
+git branch --show-current
+```
+
+Se for `main`, `master`, `develop`, `staging` ou `homolog`:
+
+```
+🚫 BLOQUEADO: Você está em uma branch protegida ({BRANCH_ATUAL}).
+
+Este workflow só pode ser executado em uma branch de feature.
+Execute /eng.start {TASK_MANAGER_KEY} primeiro para criar a branch correta.
+
+Branch esperada: {TASK_MANAGER_KEY}-{titulo-kebab-case}
+```
+
+**→ PARAR. Não executar nenhuma fase.**
+
+### Regra 0.3 — Branch deve corresponder ao TASK_MANAGER_KEY
+
+Se a branch atual **não contém** o `{TASK_MANAGER_KEY}` no nome:
+
+```
+⚠️ ATENÇÃO: A branch atual ({BRANCH_ATUAL}) não corresponde à tarefa {TASK_MANAGER_KEY}.
+
+  Branch atual:  {BRANCH_ATUAL}
+  Esperado:      branch contendo {TASK_MANAGER_KEY}
+
+Confirmar que está na branch certa? (s/n)
+```
+
+**→ Aguardar confirmação explícita antes de prosseguir.**
+
+---
+
+## Princípios Fundamentais
+
+### 1. Somente Codificação - NUNCA Commits ou PRs
+
+O `work` é **estritamente proibido** de:
+
+
+| ❌ Proibido                                 | ✅ Permitido                        |
+| ------------------------------------------- | ----------------------------------- |
+| Fazer commits                               | Escrever código                    |
+| Criar Pull Requests                         | Criar/modificar arquivos de código |
+| Executar`git add`, `git commit`, `git push` | Ler arquivos da sessão             |
+| Mover cards no Jira                         | Executar testes locais              |
+| Fazer merge de branches                     | Atualizar`plan.md` com progresso    |
+| Sugerir "vamos fazer o PR agora"            | Validar código com o usuário      |
+
+### 2. Escopo de Atuação
+
+O `work` atua **exclusivamente** em:
+
+```
+$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
+├── architecture.md  → LEITURA (referência)
+└── plan.md          → LEITURA + ESCRITA (progresso)
+```
+
+E no **código do projeto** conforme definido no `plan.md`.
+
+### 3. Ciclo de Trabalho
+
+O workflow segue um ciclo rígido:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│  1. LER plan.md → Identificar fase em progresso             │
+│        ↓                                                    │
+│  2. APRESENTAR → Plano de abordagem da fase                 │
+│        ↓                                                    │
+│  3. AGUARDAR → Aprovação do usuário                         │
+│        ↓                                                    │
+│  4. IMPLEMENTAR → Código conforme plano                     │
+│        ↓                                                    │
+│  5. TESTAR → Validar localmente                             │
+│        ↓                                                    │
+│  6. VALIDAR → Usuário revisa código                         │
+│        ↓                                                    │
+│  7. ATUALIZAR plan.md → Marcar fase como concluída          │
+│        ↓                                                    │
+│  8. REPETIR → Próxima fase (se houver)                      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Comportamento Esperado
+
+### Fase de Leitura
+
+1. **Ler arquivos da sessão**
+
+   - `architecture.md` - Entender a arquitetura
+   - `plan.md` - Identificar fase atual
+2. **Identificar fase em progresso**
+
+   - Procurar por `[Em Progresso ⏰]` ou `[In Progress ⏰]`
+   - Se nenhuma em progresso, identificar a primeira `[Não Iniciada ⏳]`
+
+### Fase de Planejamento
+
+3. **Apresentar plano de abordagem**
+
+   - Listar tarefas da fase
+   - Ordem de execução proposta
+   - Arquivos que serão criados/modificados
+   - Riscos ou pontos de atenção
+4. **Aguardar aprovação**
+
+   - NUNCA iniciar sem confirmação do usuário
+   - Se usuário tiver sugestões, ajustar plano
+
+### Fase de Implementação
+
+5. **Implementar código**
+
+   - Seguir padrões do projeto
+   - Usar arquivos existentes como referência
+   - Criar testes junto com o código
+   - Documentar decisões no código
+6. **Executar testes locais**
+
+   - Rodar testes unitários
+   - Verificar lint/formatação
+   - Validar que não quebrou nada existente
+
+### Fase de Validação
+
+7. **Solicitar validação do usuário**
+
+   - Apresentar resumo do que foi feito
+   - Destacar pontos importantes
+   - Aguardar feedback
+8. **Iterar se necessário**
+
+   - Fazer ajustes solicitados
+   - Revalidar após mudanças
+
+### Fase de Atualização
+
+9. **Atualizar plan.md**
+
+   - Marcar tarefas como `[Completada ✅]`
+   - Adicionar comentários sobre:
+     - Decisões tomadas
+     - Problemas encontrados
+     - Mudanças de direção
+     - Aprendizados
+10. **Comunicar próximos passos**
+
+    - Informar que a fase foi concluída
+    - Perguntar se deseja iniciar próxima fase
+    - ⚠️ **NUNCA sugerir PR ou commit**
+
+---
+
+## Regras de Atualização do plan.md
+
+### Marcadores de Status
+
+
+| Status        | Marcador             |
+| ------------- | -------------------- |
+| Não iniciada | `[Não Iniciada ⏳]` |
+| Em progresso  | `[Em Progresso ⏰]`  |
+| Completada    | `[Completada ✅]`    |
+| Bloqueada     | `[Bloqueada 🚫]`     |
+
+### Comentários Obrigatórios
+
+Ao concluir uma fase, adicione na seção `### Comentários:`:
+
+```markdown
+### Comentários:
+
+- **Decisão**: {decisão tomada e por quê}
+- **Mudança**: {algo que mudou em relação ao planejado}
+- **Aprendizado**: {algo descoberto durante implementação}
+- **Atenção**: {ponto importante para próximas fases}
+```
+
+---
+
+## Interação com Usuário
+
+### Pontos de Pausa Obrigatórios
+
+O workflow **DEVE pausar e aguardar confirmação**:
+
+1. ✋ **Antes de iniciar qualquer fase**
+2. ✋ **Após completar implementação** (antes de atualizar plan.md)
+3. ✋ **Antes de iniciar próxima fase**
+
+### Comunicação
+
+- Seja claro sobre o que foi feito
+- Destaque arquivos criados/modificados
+- Mencione testes executados
+- Liste decisões tomadas
+
+---
+
+## Erros Comuns a Evitar
+
+### ❌ Anti-padrões
+
+1. **Escapar para Git**
+
+   - "Vou fazer o commit dessas mudanças..."
+   - "Agora podemos criar o PR..."
+   - "Deixa eu dar push das alterações..."
+2. **Pular validação**
+
+   - Implementar várias fases sem pausar
+   - Não aguardar confirmação do usuário
+3. **Não atualizar plan.md**
+
+   - Esquecer de marcar tarefas como concluídas
+   - Não adicionar comentários
+4. **Ignorar testes**
+
+   - Implementar sem testar
+   - Não rodar lint/formatação
+
+### ✅ Boas Práticas
+
+1. **Implementação incremental**
+
+   - Uma tarefa por vez
+   - Testar após cada mudança
+2. **Comunicação clara**
+
+   - Explicar o que está fazendo
+   - Mostrar código relevante
+3. **Documentação no código**
+
+   - Comentários explicativos
+   - JSDoc/docstrings
+
+---
+
+## Transição para Próxima Etapa
+
+Ao finalizar **TODAS as fases** do `plan.md`, informe:
+
+```
+✅ Todas as fases do plano foram implementadas!
+
+📁 Sessão: $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
+📄 Plan atualizado: plan.md
+
+📌 Próximos passos:
+1. Revise todo o código implementado
+2. Execute os testes completos
+3. Quando estiver pronto, use `eng.pr` para criar o Pull Request
+
+⚠️ Este workflow NÃO faz commits ou PRs.
+   Use `eng.pr` quando estiver pronto para submeter.
+```
+
+---
+
+## Checklist de Conclusão de Fase
+
+Antes de considerar uma fase completa:
+
+- [ ]  Todas as tarefas da fase foram implementadas
+- [ ]  Testes locais passando
+- [ ]  Lint/formatação OK
+- [ ]  Usuário validou o código
+- [ ]  `plan.md` atualizado com status
+- [ ]  Comentários adicionados no plan.md
+- [ ]  NENHUM commit foi feito
+- [ ]  NENHUM PR foi criado
+- [ ]  Próximos passos comunicados

package/rules/engineering/frontend/eng.frontend-rules.md

@@ -0,0 +1,147 @@
+---
+name: eng.frontend-rules
+description: >
+  Padrões obrigatórios para devs com HUB: FRONTEND — componentes, TypeScript,
+  acessibilidade, performance, micro frontend e design system.
+author: jarvis-team
+version: "1.0"
+---
+
+> **Applies to:** HUB: FRONTEND | POSITION: all | AREA: ENGINEERING | SQUAD: all
+
+# Regras de Engenharia Frontend
+
+---
+
+## 1. Componentes
+
+### Estrutura obrigatória
+- Todo componente deve ter props tipadas com TypeScript — `any` é proibido sem justificativa documentada
+- Props obrigatórias devem ser declaradas sem `?`; opcionais com `?` e valor default explícito
+- Componentes com mais de uma responsabilidade devem ser divididos (Single Responsibility)
+- Lógica de negócio não pertence ao componente de UI — usar hooks ou camada de serviço
+
+### Nomenclatura
+- Componentes: `PascalCase` (`UserCard`, `ProductTable`)
+- Hooks: `use` + `PascalCase` (`useUserData`, `useProductFilters`)
+- Arquivos de componente: `PascalCase.tsx` (`UserCard.tsx`)
+- Arquivos de hook: `camelCase.ts` (`useUserData.ts`)
+
+### Checklist mínimo por componente
+- [ ] Props tipadas (TypeScript)
+- [ ] Estados visuais: normal, hover, focus, disabled, loading, erro, vazio
+- [ ] Semântica HTML correta (não usar `<div>` para botões, links ou listas)
+- [ ] Responsivo (mobile-first com breakpoints do design system)
+- [ ] Testável sem DOM real (lógica isolada em hooks)
+
+---
+
+## 2. TypeScript
+
+- `strict: true` obrigatório em `tsconfig.json`
+- Proibido: `as any`, `@ts-ignore` sem comentário explicativo, `!` (non-null assertion) sem verificação prévia
+- Types vs Interfaces: usar `interface` para objetos de domínio, `type` para uniões e utilitários
+- Exportar tipos públicos de componentes (`export type { ButtonProps }`)
+
+---
+
+## 3. Acessibilidade (WCAG 2.1 AA — obrigatório)
+
+- Semântica HTML nativa antes de ARIA (`<button>`, `<nav>`, `<main>`, `<article>`)
+- Todos os elementos interativos são navegáveis por teclado
+- Contraste mínimo: 4.5:1 para texto normal, 3:1 para texto grande e elementos UI
+- Imagens informativas têm `alt` descritivo; decorativas têm `alt=""`
+- Modais usam `role="dialog"`, `aria-modal="true"`, `aria-labelledby` e focus trap
+- Formulários: todo `<input>` tem `<label>` associado via `htmlFor` ou `aria-label`
+- Erros de formulário: exibidos com `role="alert"` ou `aria-live="polite"`
+- Screen reader: testar com VoiceOver (Mac) ou NVDA (Windows) em features críticas
+
+---
+
+## 4. Performance
+
+### Core Web Vitals — targets obrigatórios
+- LCP (Largest Contentful Paint): < 2.5s
+- CLS (Cumulative Layout Shift): < 0.1
+- INP (Interaction to Next Paint): < 200ms
+
+### Práticas obrigatórias
+- Imagens sempre com `width` e `height` definidos para evitar CLS
+- Componentes pesados com `lazy()` + `<Suspense fallback>`
+- Dependências novas: avaliar impacto no bundle antes de instalar (`bundlephobia.com`)
+- Sem `useEffect` para buscar dados — usar React Query / TanStack Query ou Server Components
+- Memoização apenas quando necessário e comprovado com profiler (não premature optimization)
+
+---
+
+## 5. Testes
+
+- **Testing Library**: queries por acessibilidade primeiro (`getByRole`, `getByLabelText`)
+- **Proibido**: `getByTestId` como primeira opção (usar só quando sem alternativa acessível)
+- **Cobertura mínima**: fluxos críticos de usuário (happy path + estado de erro)
+- **Vitest**: unitários para lógica pura, hooks e utilitários
+- **Playwright / Cypress**: E2E para fluxos de usuário completos (login, checkout, etc.)
+- Mocks de módulos externos devem estar em `__mocks__/` ou `*.mock.ts`
+
+### Ferramentas disponíveis no framework
+
+- **TestSprite** (`/eng-qa-testsprite`): se o TestSprite estiver instalado no projeto, usá-lo para geração
+  e execução de testes de componente e E2E — ele gera planos de teste e código automaticamente.
+  Verificar: `ls node_modules/@testsprite 2>/dev/null || cat package.json | grep testsprite`
+
+- **Stagehand** (`/eng-scraper-robot-builder`, `/eng-qa-e2e`): para testes E2E em linguagem natural
+  ou automação de fluxos de usuário complexos, o Stagehand permite descrever o fluxo em português
+  e gera os steps Playwright automaticamente.
+  Verificar: `cat package.json | grep stagehand`
+
+> Quando qualquer dessas ferramentas estiver disponível no projeto, **preferir sobre a implementação
+> manual** — reduz custo de manutenção e aumenta cobertura mais rapidamente.
+
+---
+
+## 6. Micro Frontend
+
+- Todo remote deve ser versionado e publicado com URL de fallback definida
+- Contratos de interface entre shell e remotes são declarados em tipos TypeScript compartilhados
+- Nenhum remote depende diretamente de outro remote — comunicação via shell ou event bus
+- Shared dependencies declaradas explicitamente no `ModuleFederationPlugin` com `singleton: true`
+- Cada remote deve funcionar em modo standalone (sem shell) para desenvolvimento local
+- Testes de integração entre shell e remote são obrigatórios para cada ponto de montagem
+- Versionamento: breaking changes no contrato de um remote exigem bump de versão major
+
+---
+
+## 7. Design System
+
+- Cores, tipografia, espaçamentos e breakpoints vêm **exclusivamente** dos tokens do design system
+- Proibido hardcodar valores de cor, fonte ou espaçamento fora dos tokens
+- Novos componentes de UI são criados no design system antes de serem usados nos remotes
+- Variantes de componente usam `cva` (class-variance-authority) como padrão
+- Componentes públicos do design system têm story no Storybook antes de serem liberados
+- Alterações na API pública de um componente (props) seguem semver
+
+---
+
+## 8. Code Review (Checklist do Reviewer)
+
+Ao revisar PR de frontend, verificar:
+
+- [ ] TypeScript sem `any` ou `@ts-ignore` injustificado
+- [ ] Nenhuma lógica de negócio em componente de UI
+- [ ] Acessibilidade: semântica HTML, ARIA correto, navegação por teclado
+- [ ] Performance: sem re-renders desnecessários, lazy loading aplicado quando cabível
+- [ ] Tokens do design system usados (sem valores hardcodados)
+- [ ] Testes cobrem happy path e estado de erro
+- [ ] Responsividade verificada em mobile e desktop
+- [ ] Se micro frontend: contrato de interface atualizado, remote funciona standalone
+
+---
+
+## 9. Proibições Absolutas
+
+- `document.querySelector` / manipulação direta do DOM em contexto React
+- `!important` em CSS sem comentário explicativo
+- Fetch direto em componente de UI (usar hooks, queries ou Server Actions)
+- Importar de outro remote diretamente (rompe o isolamento do micro frontend)
+- Hardcodar tokens de design (cores, espaçamentos, fontes) fora do sistema de tokens
+- `console.log` em código commitado (usar logger estruturado ou remover)