jarvis-ai-framework 2.0.0 → 2.1.1

package/skills/eng-frontend-microfrontend/references/3-contratos-interface.md

@@ -0,0 +1,73 @@
+# Contratos de Interface
+
+> Parte do skill `eng-frontend-microfrontend`. Leia este arquivo quando a tarefa definir ou alterar contratos entre shell e remotes.
+
+## Contratos de Interface
+
+O contrato é o **acordo formal** entre shell e remote — define o que o remote expõe e o que espera receber.
+
+### Estrutura do pacote de contratos
+
+```
+packages/
+└── mfe-contracts/
+    ├── src/
+    │   ├── remotes/
+    │   │   ├── {nome-remote}.contract.ts    ← contrato do remote
+    │   │   └── index.ts
+    │   ├── shell/
+    │   │   └── shell.context.ts             ← o que o shell injeta nos remotes
+    │   └── index.ts
+    ├── package.json
+    └── tsconfig.json
+```
+
+### Definindo um contrato
+
+```typescript
+// packages/mfe-contracts/src/remotes/{nome-remote}.contract.ts
+
+// O que o remote expõe ao shell
+export interface {NomeRemote}Exports {
+  default: React.ComponentType<{NomeRemote}Props>
+}
+
+// Props que o shell passa ao montar o remote
+export interface {NomeRemote}Props {
+  basePath: string
+  onNavigate?: (path: string) => void
+}
+
+// Eventos que o remote emite no event bus
+export interface {NomeRemote}Events {
+  '{nome-remote}:action-completed': { id: string; result: unknown }
+  '{nome-remote}:error': { code: string; message: string }
+}
+```
+
+### Contexto do shell (injetado em todos os remotes)
+
+```typescript
+// packages/mfe-contracts/src/shell/shell.context.ts
+export interface ShellContext {
+  user: {
+    id: string
+    name: string
+    permissions: string[]
+  }
+  theme: 'light' | 'dark'
+  locale: string
+  onNavigate: (path: string) => void
+}
+
+// Hook disponível em todos os remotes
+export const ShellContextReact = React.createContext<ShellContext | null>(null)
+
+export function useShellContext(): ShellContext {
+  const ctx = React.useContext(ShellContextReact)
+  if (!ctx) throw new Error('useShellContext deve ser usado dentro do ShellProvider')
+  return ctx
+}
+```
+
+---

package/skills/eng-frontend-microfrontend/references/4-shared-dependencies.md

@@ -0,0 +1,48 @@
+# Shared Dependencies
+
+> Parte do skill `eng-frontend-microfrontend`. Leia este arquivo quando a tarefa envolver dependências compartilhadas ou conflito de versão.
+
+## Shared Dependencies
+
+### Regras críticas
+
+```
+singleton: true   → apenas uma instância em toda a aplicação (obrigatório para React, React DOM)
+eager: false      → NÃO usar eager para shared libs (causa bootstrap error)
+requiredVersion   → sempre declarar para evitar conflitos silenciosos
+```
+
+### Checklist de shared deps
+
+```typescript
+shared: {
+  // Core React — sempre singleton
+  'react': { singleton: true, requiredVersion: '^18.0.0' },
+  'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
+
+  // Router — singleton para evitar múltiplos contextos de roteamento
+  'react-router-dom': { singleton: true, requiredVersion: '^6.0.0' },
+
+  // Design system — singleton obrigatório (CSS e contexto de tema)
+  '@{org}/design-system': { singleton: true },
+
+  // Estado global — singleton se compartilhado entre remotes
+  'zustand': { singleton: true },
+
+  // NÃO compartilhar: libs utilitárias pequenas (date-fns, lodash)
+  // → melhor cada remote ter sua versão para evitar lock de versão
+}
+```
+
+### Conflito de versão (diagnóstico)
+
+```bash
+# Ver qual versão de react cada remote está carregando
+# No DevTools → Network → filtrar por "remoteEntry.js"
+# Abrir arquivo e buscar por "shared"
+
+# Via CLI — verificar versões no monorepo
+pnpm list react --recursive
+```
+
+---

package/skills/eng-frontend-microfrontend/references/5-event-bus.md

@@ -0,0 +1,59 @@
+# Event Bus
+
+> Parte do skill `eng-frontend-microfrontend`. Leia este arquivo quando a tarefa envolver comunicação entre remotes por eventos.
+
+## Event Bus
+
+Remote e shell se comunicam via evento — nunca via import direto.
+
+```typescript
+// packages/mfe-contracts/src/event-bus.ts
+
+type EventHandler<T> = (payload: T) => void
+
+class MFEEventBus {
+  private listeners = new Map<string, Set<EventHandler<unknown>>>()
+
+  emit<T>(event: string, payload: T): void {
+    this.listeners.get(event)?.forEach((handler) => handler(payload as unknown))
+  }
+
+  on<T>(event: string, handler: EventHandler<T>): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set())
+    }
+    this.listeners.get(event)!.add(handler as EventHandler<unknown>)
+
+    // retorna função de cleanup
+    return () => this.listeners.get(event)?.delete(handler as EventHandler<unknown>)
+  }
+}
+
+// Singleton global — compartilhado via shell context
+export const eventBus = new MFEEventBus()
+```
+
+```typescript
+// Uso em um remote
+import { useShellContext } from '@{org}/mfe-contracts'
+
+function CheckoutButton({ orderId }: { orderId: string }) {
+  const { eventBus } = useShellContext()
+
+  return (
+    <button onClick={() => eventBus.emit('checkout:initiated', { orderId })}>
+      Finalizar compra
+    </button>
+  )
+}
+
+// Uso no shell — escutar eventos de remotes
+useEffect(() => {
+  const unsubscribe = eventBus.on('checkout:initiated', ({ orderId }) => {
+    navigate(`/checkout/${orderId}`)
+  })
+  return unsubscribe
+}, [])
+```
+
+---

package/skills/eng-frontend-microfrontend/references/6-monorepo-deploy.md

@@ -0,0 +1,77 @@
+# Monorepo e Estratégia de Deploy
+
+> Parte do skill `eng-frontend-microfrontend`. Leia este arquivo quando a tarefa envolver a estrutura do monorepo, o deploy independente ou o versionamento de remotes.
+
+## Monorepo Frontend
+
+### Estrutura recomendada
+
+```
+{repo}/
+├── apps/
+│   ├── shell/              ← host application
+│   ├── {remote-a}/         ← micro frontend A
+│   └── {remote-b}/         ← micro frontend B
+├── packages/
+│   ├── design-system/      ← componentes e tokens compartilhados
+│   ├── mfe-contracts/      ← tipos TypeScript de contratos de interface
+│   └── utils/              ← utilitários compartilhados
+├── pnpm-workspace.yaml
+└── turbo.json
+```
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'apps/*'
+  - 'packages/*'
+```
+
+```json
+// turbo.json
+{
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "test": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+---
+
+## Estratégia de Deploy
+
+### Deploy independente (objetivo central do micro frontend)
+
+```
+Cada remote tem seu próprio pipeline de CI/CD:
+  push → build → test → deploy → atualizar URL no shell (via env var ou config service)
+
+Shell NÃO precisa ser re-deployed quando um remote é atualizado.
+```
+
+### Variáveis de ambiente por remote
+
+```bash
+# .env.production do shell
+VITE_REMOTE_URL_NOME_REMOTE=https://cdn.example.com/nome-remote/remoteEntry.js
+VITE_REMOTE_URL_OUTRO_REMOTE=https://cdn.example.com/outro-remote/remoteEntry.js
+```
+
+### Versionamento de remotes
+
+```
+Sem breaking change na API exposta → patch ou minor → URL permanece a mesma
+Breaking change na API exposta (props, eventos) → major → nova URL + migração no shell
+```
+
+---

package/skills/eng-frontend-microfrontend/references/7-troubleshooting.md

@@ -0,0 +1,45 @@
+# Troubleshooting de Micro Frontend
+
+> Parte do skill `eng-frontend-microfrontend`. Leia este arquivo quando houver erro de módulo compartilhado, remote indisponível ou componente que não re-renderiza.
+
+## Troubleshooting
+
+### Erro: "Shared module is not available for eager consumption"
+
+```typescript
+// ❌ Causa: eager: true em shared lib com React
+shared: { react: { singleton: true, eager: true } }  // NÃO FAZER
+
+// ✅ Solução: usar bootstrap.ts com import() dinâmico
+// src/index.ts
+import('./bootstrap')  // async bootstrap resolve o problema
+```
+
+### Erro: "Remote container is not available"
+
+```bash
+# 1. Verificar se o remote está rodando
+curl http://localhost:3001/assets/remoteEntry.js
+
+# 2. Verificar CORS no servidor do remote
+# O remoteEntry.js precisa ser acessível pelo shell
+
+# 3. Verificar se a URL no shell está correta
+grep -r "remoteEntry" vite.config.ts
+```
+
+### Componente do remote não re-renderiza após update de state do shell
+
+```typescript
+// Causa provável: contexto do shell não está sendo re-injetado no remote
+// Solução: passar o contexto via props no ponto de montagem, não via módulo compartilhado
+
+// ❌ Problemático
+import { useShellStore } from 'shell/store'  // import direto entre remote e shell
+
+// ✅ Correto
+// Shell passa estado via props ao montar o remote
+<RemoteApp user={currentUser} onNavigate={navigate} />
+```
+
+---

package/skills/eng-global-browser-extension-builder/SKILL.md

@@ -294,6 +294,12 @@ Firefox:
 6. Enviar para revisão (1-3 dias úteis)
 ```
 
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
+
 ---
 
 ## Anti-Padrões

package/skills/eng-global-docs-write/SKILL.md

@@ -25,7 +25,7 @@ Garantir que a documentação reflita com precisão o **estado atual do codebase
 ## Recursos
 
 - **Template C4**: `$IDE/templates/engineering/c4-model-template.md`
-- **Skill arch-c4**: `$IDE/skills/arch-c4/SKILL.md`
+- **Skill eng-backend-arch-c4**: `$IDE/skills/eng-backend-arch-c4/SKILL.md`
 - **Saída**: `$DOCS_FOLDER/` (conforme ENV.md)
 
 > **Dica**: Em caso de dúvida sobre documentação de bibliotecas ou frameworks, use o MCP `context7` para consultar documentação atualizada.
@@ -172,7 +172,7 @@ Você gostaria que eu prosseguisse com essas atualizações?
 
 ## Documentação de Arquitetura (C4 Model)
 
-Quando houver **mudanças arquiteturais significativas**, utilize a skill `arch-c4`:
+Quando houver **mudanças arquiteturais significativas**, utilize a skill `eng-backend-arch-c4`:
 
 ### Quando usar C4 Model
 
@@ -289,10 +289,15 @@ Antes de finalizar:
 
 ## Integração com Outros Skills
 
-Após atualizar a documentação, considere:
+### Skills invocados durante a execução do skill
 
-- **jarvis-docs-index**: Atualizar o índice de documentação (`$IDE/skills/jarvis-docs-index/SKILL.md`)
-- **arch-c4**: Atualizar diagramas C4 se houver mudanças arquiteturais
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| Documentação de Arquitetura (C4 Model) | `/eng-backend-arch-c4` | Se houver mudanças arquiteturais significativas (novos serviços ou contêineres, integrações externas, componentes, bancos ou filas, APIs públicas) |
+
+Sugestões após atualizar a documentação (não são chamadas do fluxo):
+
+- `jarvis-docs-index`: atualizar o índice de documentação (`$IDE/skills/jarvis-docs-index/SKILL.md`)
 
 ---
 

package/skills/eng-global-jira-comment/SKILL.md

@@ -19,3 +19,9 @@ Este skill foi unificado em **`eng-global-task-comment`**.
 Execute o playbook de `$IDE/skills/eng-global-task-comment/SKILL.md` com os mesmos argumentos `{TASK_MANAGER_KEY} {mensagem}`.
 
 `{TASK_MANAGER_KEY}` — identificador do card no `TASK_MANAGER` do ENV.md.
+
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| Único passo (alias) | `/eng-global-task-comment` | Sempre — o alias executa o playbook da skill alvo com os mesmos argumentos `{TASK_MANAGER_KEY} {mensagem}` |

package/skills/eng-global-pr/SKILL.md

@@ -29,7 +29,7 @@ Criar branch, commitar alterações e abrir um MR (GitLab) ou PR (GitHub/Bitbuck
 ## Recursos
 
 - **Template**: `$IDE/templates/engineering/PR-template.md`
-- **Regras**: `$IDE/rules/engineering/eng.pr-rules.md`
+- **Regras**: `$IDE/rules-on-demand/engineering/eng.pr-rules.md`
 - **Workflow**: `$IDE/workflows/engineering/eng.pr.md`
 
 ---
@@ -247,6 +247,12 @@ rm -rf $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
 
 > ⚠️ **IMPORTANTE**: Sempre pedir confirmação antes de executar comandos destrutivos.
 
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| Passo 6 — Atualizar o card | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido (freelance pula): comentário no card com o link do MR |
+
 ---
 
 ## Regras de Segurança

package/skills/eng-global-task-comment/SKILL.md

@@ -62,3 +62,9 @@ Exit 0 → comentário ok. Exit 2 → avisar e **não bloquear** o workflow.
 ```
 
 Nunca pedir credenciais no chat. Nunca parar o fluxo principal por falha de comentário.
+
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |

package/skills/eng-qa-a11y-audit/SKILL.md

@@ -12,7 +12,7 @@ metadata:
   area: qa
 ---
 
-# qa-a11y-audit
+# eng-qa-a11y-audit
 
 Você é um especialista em acessibilidade web (a11y). Sua função é integrar
 `jest-axe` nos testes unitários existentes de componentes para validar
@@ -31,7 +31,7 @@ e gerar report com correções sugeridas.
 ## Entrada
 
 ```
-/qa-a11y-audit [caminho]
+/eng-qa-a11y-audit [caminho]
 ```
 
 - `caminho` (opcional) — diretório ou arquivo de componente
@@ -65,7 +65,7 @@ e gerar report com correções sugeridas.
 - Onboarding de a11y em projeto que nunca teve
 
 **NÃO usar quando:**
-- Projeto não tem testes unitários (criar testes primeiro com `qa-unit-test`)
+- Projeto não tem testes unitários (criar testes primeiro com `eng-qa-unit-test`)
 - Componentes não renderizam DOM (hooks, utils, serviços)
 - Objetivo é teste E2E de a11y (usar Lighthouse/axe-core no E2E)
 
@@ -219,6 +219,12 @@ npx vitest run {padrão}
 ──────────────────────────────────────────────────────────
 ```
 
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
+
 ---
 
 ## Regras
@@ -261,7 +267,7 @@ npx vitest run {padrão}
 ## Mensagem de Conclusão
 
 ```
-── qa-a11y-audit concluído ───────────────────────────────
+── eng-qa-a11y-audit concluído ───────────────────────────────
   Componentes : {N} testados
   Violações   : {V} encontradas ({C} critical, {S} serious)
   Arquivos    : {M} modificados