jarvis-ai-framework 1.0.0

package/workflows/engineering/eng.pre-pr.md

@@ -0,0 +1,167 @@
+---
+description: Validação de segurança para realizar um pull request ou merge request
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+rules_file: "$IDE/rules/engineering/eng.pre-pr-rules.md"
+recommended_model: claude-sonnet-4-20250514
+model_tier: high
+model_justification: Revisão multi-agente requer coordenação, análise de código, validação de testes e verificação de conformidade
+---
+
+# pre-pr
+
+Estamos nos aproximando de finalizar o trabalho nesta branch e nos preparar para um solicitação de integração. Agora, é hora de fazer verificações finais e limpezas para assegurar que estamos alinhados com nossos convenções e objetivos.
+
+## Skills recomendados
+
+- **eng-qa-test-plan**: para avaliar cobertura de testes e identificar gaps antes do PR.
+  - Arquivo: `$IDE/skills/eng-qa-test-plan/SKILL.md`
+- **eng-qa-testsprite**: para executar testes automatizados e validar cobertura com TestSprite MCP.
+  - Arquivo: `$IDE/skills/eng-qa-testsprite/SKILL.md`
+- **eng-docs-write**: para atualizar documentação baseada nas mudanças da branch.
+  - Arquivo: `$IDE/skills/eng-docs-write/SKILL.md`
+- **docs-index**: para atualizar o índice de documentação quando necessário.
+  - Arquivo: `$IDE/skills/docs-index/SKILL.md`
+- **eng-performance-engineer**: para validar thresholds de performance e analisar regressões quando a feature tiver requisitos não-funcionais de latência, throughput ou escalabilidade.
+  - Arquivo: `$IDE/skills/eng-performance-engineer/SKILL.md`
+- **eng-frontend**: para validar implementação de componentes React, performance de UI e acessibilidade (WCAG 2.1 AA).
+  - Arquivo: `$IDE/skills/eng-frontend/SKILL.md`
+- **eng-design-system**: para auditar conformidade do código com tokens e componentes do design system.
+  - Arquivo: `$IDE/skills/eng-design-system/SKILL.md`
+- **eng-microfrontend**: quando a branch envolver shell app ou remotes em Module Federation.
+  - Arquivo: `$IDE/skills/eng-microfrontend/SKILL.md`
+- **eng-cybersecurity**: quando a branch tocar em auth, sessions, inputs, CORS, CSP, permissões ou adicionar dependências novas.
+  - Arquivo: `$IDE/skills/eng-cybersecurity/SKILL.md`
+
+<arguments>
+#$ARGUMENTS
+</arguments>
+
+## Fase 0.5: Comentário no card — Início
+
+Pular se `TASK_MANAGER` estiver vazio (freelance).
+
+Ao iniciar o pre-PR, registrar:
+
+```
+/eng-task-comment {TASK_MANAGER_KEY} 🔍 [Jarvis] Iniciando validação pre-PR - bateria de testes e revisão de código
+```
+
+> Usa o skill `/eng-task-comment`. Não bloquear se falhar.
+
+---
+
+## Regras de Execução
+
+- **Escopo**: avalie apenas as mudanças desta branch em relação ao branch base (ex.: `main`/`master`).
+- **Evidências**: sempre que mencionar “testes/validações passando”, inclua quais comandos foram usados e o resultado (ou descreva smoke tests manuais quando não houver suíte).
+- **Revalidação**: se qualquer gate levar a mudanças no código, reexecute no mínimo:
+  - Gate 2 (revisão técnica)
+  - Gate 3 (testes/validações)
+
+## Gates
+
+### Gate 0: Verificar Documentação Central (condicional)
+
+Se `CENTRAL_DOCS_REPO` estiver configurado no ENV.md:
+
+**Passo 1:** Detectar mudanças arquiteturais no diff da branch
+```bash
+git diff main...HEAD | grep -E "(class|interface|schema|migration|config)" || true
+```
+
+**Passo 2:** Se mudanças arquiteturais detectadas:
+- Verificar se ARD local existe em `./docs/engineering/`
+- Comparar com ARD do central-docs (se existir)
+- Se desatualizado ou novo:
+  - Perguntar: "Publicar ARD atualizado no central-docs?"
+  - Se sim: executar `jarvis docs publish --file <path> --tipo ard --feature <slug>`
+
+**Passo 3:** Se novos contratos/APIs criados:
+- Verificar se há RFC relacionado
+- Se não: sugerir criar RFC para decisões arquiteturais
+
+**Comportamento:**
+- Se `CENTRAL_DOCS_REPO` vazio → pular silenciosamente
+- Não bloquear PR por docs desatualizados (apenas avisar)
+
+---
+
+1. Invoque o agente [prod.pm-checker]($IDE/agents/product/prod.pm-checker.md) para verificar se a branch está alinhada com os docs do projeto, documentação de produto e de engenharia.
+2. Invoque o agente [eng.dev-code-reviewer]($IDE/agents/engineering/eng.dev-code-reviewer.md) para revisar o código e assegurar que está bom para lançar.
+3. Invoque o agente [eng.qa.test-planner]($IDE/agents/engineering/qa/eng.qa.test-planner.md) para identificar gaps de cobertura de testes na branch.
+4. **Se o test-planner identificar gaps críticos**, invoque o agente [eng.qa.testing-engineer]($IDE/agents/engineering/qa/eng.qa.testing-engineer.md) para escrever os testes faltantes antes de prosseguir.
+   - Gaps críticos: funções públicas sem teste, lógica de negócio descoberta, tratamento de erros não validado
+   - Gaps aceitáveis (com justificativa): código de infraestrutura, integrações já cobertas por e2e
+5. **Se a feature tiver requisitos não-funcionais** (definidos no `architecture.md` ou explícitos na task), invoque o agente [eng.qa.test-architect]($IDE/agents/engineering/qa/eng.qa.test-architect.md) para validar:
+   - Testes de performance executados e dentro dos thresholds
+   - Testes de segurança passando (RBAC, injection, etc.)
+   - Quality gates configurados corretamente
+6. Execute o skill [eng-qa-testsprite]($IDE/skills/eng-qa-testsprite/SKILL.md) com `testScope=diff` para validar testes automatizados nas mudanças da branch.
+   - Se o projeto tiver frontend: execute com `type=frontend`
+   - Se o projeto tiver backend: execute com `type=backend`
+   - Se tiver ambos: execute os dois tipos sequencialmente
+7. **Se a branch tiver mudanças de interface** (componentes React, design system, micro frontend), invoque o agente [eng.frontend.agent]($IDE/agents/engineering/eng.frontend.agent.md) para validar:
+   - TypeScript sem `any`, tokens do design system usados, acessibilidade WCAG 2.1 AA
+   - Se micro frontend: contrato de interface atualizado, remote funciona standalone
+8. **Se a branch introduzir nova feature de UI ou alterar fluxo de usuário**, invoque o agente [eng.ux-designer.agent]($IDE/agents/engineering/eng.ux-designer.agent.md) para verificar:
+   - Empty states, loading states e mensagens de erro em linguagem humana
+   - Consistência com padrões visuais existentes no produto
+9. Invoque o agente [eng.docs-writer]($IDE/agents/engineering/eng.docs-writer.md) para atualizar a documentação do projeto.
+10. **Se a branch tocar em auth, sessions, inputs de usuário, CORS, CSP, permissões ou adicionar endpoints públicos**, executar o workflow [eng.security-review]($IDE/workflows/engineering/eng.security-review.md) como gate de segurança:
+   - Revisar sanitização de inputs e queries parametrizadas
+   - Verificar auth guards em endpoints novos
+   - Validar headers de segurança e configurações de CORS
+   - Escanear secrets no diff (`grep` por patterns de tokens/senhas)
+   - Verificar `npm audit` sem vulnerabilidades HIGH/CRITICAL
+   - Se achados CRITICAL: status **Red** (bloqueador)
+
+Você também precisará lidar com todo o feedback que esses agentes fornecerem e fazer mudanças e correções conforme necessário.
+
+## Checklist final (obrigatório)
+
+- [ ] Não existem bloqueadores abertos (segurança/bugs críticos).
+- [ ] Testes e validações relevantes foram executados e passaram (com evidências via eng-qa-testsprite ou manual).
+- [ ] Cobertura de testes para mudanças da branch foi avaliada (e gaps críticos tratados ou justificados).
+- [ ] Documentação foi revisada/atualizada (listar arquivos alterados) ou foi explicitado por que não foi necessário.
+- [ ] Riscos conhecidos e trade-offs foram registrados (e follow-ups criados quando aplicável).
+
+## Saída final (obrigatória)
+
+### 1) Status Pre-PR (Semáforo)
+
+- Green: pronto para PR
+- Yellow: pode abrir PR com notas e follow-ups
+- Red: não pode abrir PR (listar bloqueadores)
+
+### 2) Bloqueadores e pendências
+
+- Bloqueadores:
+- Pendências aceitas (com justificativa):
+- Follow-ups (links/IDs):
+
+### 3) PR Brief (para colar no PR)
+
+- Resumo do que mudou:
+- Como testar:
+- Evidências de testes/validações:
+- Docs atualizadas:
+- Riscos / trade-offs:
+
+## Comentário no card — Conclusão
+
+Pular se `TASK_MANAGER` estiver vazio (freelance).
+
+Após apresentar o resultado final, registrar:
+
+- Se **Green**: `✅ [Jarvis] Pre-PR concluído com status GREEN - pronto para abrir MR`
+- Se **Yellow**: `⚠️ [Jarvis] Pre-PR concluído com status YELLOW - pode abrir MR com ressalvas`
+- Se **Red**: `🚫 [Jarvis] Pre-PR concluído com status RED - bloqueadores encontrados, não abrir MR`
+
+```
+/eng-task-comment {TASK_MANAGER_KEY} {mensagem_status}
+```
+
+---
+
+Uma vez terminado, me avise e peça minha permissão para abrir o Pull Request.

package/workflows/engineering/eng.review.md

@@ -0,0 +1,185 @@
+---
+description: Fluxo de trabalho de Engenharia para revisão de solução ou PR
+globs:
+  alwaysApply: false
+recommended_model: claude-sonnet-4-20250514
+model_tier: high
+model_justification: Revisão de código requer análise crítica, identificação de riscos, edge cases e sugestões de melhorias
+---
+
+# Workflow de Engenharia – Revisão de Solução / Pull Request
+
+## Objetivo
+
+Guiar o assistente de Engenharia (ENG) na revisão de soluções técnicas, ARDs, PRs ou trechos de código,
+apontando riscos, gaps e melhorias, sempre respeitando `$IDE/rules/engineering/eng-rules.md`.
+
+## Skills recomendados
+
+- **eng-qa-test-plan**: para revisar cobertura de testes da branch e sugerir gaps (quando a revisão envolver mudanças de código).
+  - Arquivo: `$IDE/skills/eng-qa-test-plan/SKILL.md`
+- **eng-qa-testsprite**: para executar testes automatizados e validar cobertura real das mudanças.
+  - Arquivo: `$IDE/skills/eng-qa-testsprite/SKILL.md`
+- **eng-arch-c4**: quando a revisão envolver mudanças arquiteturais relevantes e precisar atualizar diagramas.
+  - Arquivo: `$IDE/skills/eng-arch-c4/SKILL.md`
+- **eng-frontend**: quando a revisão envolver componentes React, hooks, performance de UI ou acessibilidade.
+  - Arquivo: `$IDE/skills/eng-frontend/SKILL.md`
+- **eng-design-system**: quando a revisão envolver componentes do design system, tokens ou Storybook.
+  - Arquivo: `$IDE/skills/eng-design-system/SKILL.md`
+- **eng-microfrontend**: quando a revisão envolver Module Federation, shell/remote ou contratos de interface.
+  - Arquivo: `$IDE/skills/eng-microfrontend/SKILL.md`
+
+## Agentes recomendados
+
+- **eng.qa.test-planner**: para análise detalhada de cobertura de testes e identificação de gaps.
+  - Arquivo: `$IDE/agents/engineering/qa/eng.qa.test-planner.md`
+  - Quando usar: Se a revisão identificar problemas de cobertura que precisam de análise mais profunda.
+- **eng.frontend.agent**: para revisão aprofundada de código React, decisões arquiteturais frontend e acessibilidade.
+  - Arquivo: `$IDE/agents/engineering/eng.frontend.agent.md`
+  - Quando usar: PR com mudanças significativas de interface, componentes ou micro frontend.
+- **eng.ux-designer.agent**: para avaliação de usabilidade, fluxo do usuário e microcopy.
+  - Arquivo: `$IDE/agents/engineering/eng.ux-designer.agent.md`
+  - Quando usar: PR que introduz nova feature de UI ou altera fluxo de usuário existente.
+
+---
+
+## Passo 1 – Entender o objetivo da mudança
+
+Pergunte e resuma:
+
+- Qual é o objetivo principal dessa mudança?
+- Ela está ligada a:
+  - ( ) Um ARD específico
+  - ( ) Um PRD / demanda de produto
+  - ( ) Bug/Incidente
+  - ( ) Refactor / melhoria técnica
+
+Se houver ARD ou PRD relacionados, peça o contexto e leia rapidamente para alinhar a intenção.
+
+---
+
+## Passo 2 – Escopo e impacto declarado
+
+Peça para o usuário (ou infira do diff):
+
+- O que essa mudança **pretende** alterar?
+- O que explicitamente **não** deveria mudar?
+
+Liste componentes tocados:
+
+- serviços, módulos, arquivos relevantes
+- endpoints, jobs, filas, migrations (se houver)
+
+---
+
+## Passo 3 – Revisão estrutural
+
+Na revisão da solução/PR, analise:
+
+- Clareza e organização do código/arquitetura.
+- Adequação ao stack e padrões existentes (conforme [ENV.md]).
+- Complexidade desnecessária (overengineering) versus soluções simples.
+
+Aponte:
+
+- pontos positivos
+- partes confusas ou acopladas demais
+- oportunidades claras de simplificação
+
+---
+
+## Passo 4 – Riscos e edge cases
+
+Sempre responda explicitamente:
+
+- Quais são os principais **riscos técnicos** dessa solução?
+- Há casos de borda óbvios não tratados?
+- Como essa mudança se comporta em:
+  - falhas de rede / timeouts
+  - dados inválidos ou inesperados
+  - cargas maiores que o normal
+
+Se necessário, sugira:
+
+- validações adicionais
+- tratamentos de erro mais robustos
+- limites / timeouts / retries
+
+---
+
+## Passo 5 – Qualidade e legibilidade
+
+Avalie e comente:
+
+- Nomes de variáveis, funções e módulos (semântica, clareza).
+- Tamanho de funções/métodos (muito grandes? fazem coisas demais?).
+- Duplicação de código óbvia.
+- Comentários/documentação essenciais ausentes (sem inventar novos blocos além do combinado).
+
+Sugira melhorias específicas, mas **não reescreva tudo do zero** sem necessidade.
+
+---
+
+## Passo 6 – Testes e cobertura mínima
+
+Para a solução ou PR revisado, responda:
+
+- Que tipos de teste deveriam existir para essa mudança?
+- Quais cenários mínimos deveriam ser cobertos?
+- Há algum fluxo crítico sem teste?
+
+Sugira, no mínimo:
+
+- alguns casos de teste principais (happy path + 2–3 edge cases relevantes).
+- se faz sentido adicionar testes de integração ou contrato.
+
+### Análise de Cobertura (opcional)
+
+Para uma análise detalhada de cobertura, invoque o agente **eng.qa.test-planner**:
+
+`$IDE/agents/engineering/qa/eng.qa.test-planner.md`
+
+```
+@eng.qa.test-planner Analise a cobertura de testes para as mudanças desta branch
+```
+
+O agente irá:
+
+- Mapear arquivos alterados para arquivos de teste
+- Identificar lacunas de cobertura
+- Gerar relatório com recomendações
+
+### Validação com TestSprite (opcional)
+
+Se o projeto estiver rodando localmente, execute o skill **eng-qa-testsprite** para obter evidências de cobertura:
+
+```
+/eng-qa-testsprite diff
+```
+
+Inclua no parecer:
+
+- Resultado dos testes executados (passou/falhou)
+- Cobertura atingida vs. esperada
+- Gaps identificados pelo TestSprite
+
+---
+
+## Passo 7 – Recomendação e próximos passos
+
+Feche sempre com uma recomendação clara:
+
+- ( ) Aprovável como está (com pequenos ajustes opcionais)
+- ( ) Recomendado aprovar **com ajustes** listados
+- ( ) **Não aprovar ainda** – pontos críticos a resolver
+
+Para cada ponto que imped gl tar aprovação, detalhe:
+
+- por que é crítico
+- qual a sugestão concreta de correção/melhoria
+
+Se fizer sentido, recomende:
+
+- quebrar a mudança em partes menores
+- criar ARD ou especificação técnica adicional
+- registrar débitos técnicos em tarefa separada

package/workflows/engineering/eng.rpa.robot.md

@@ -0,0 +1,342 @@
+---
+description: Ciclo de vida de um robô RPA — criar novo ou manter existente
+auto_execution_mode: 3
+agent: "$IDE/agents/engineering/eng.rpa.agent.md"
+rules_file: "$IDE/rules/engineering/rpa/eng.rpa-rules.md"
+recommended_model: claude-sonnet-4-20250514
+model_tier: high
+model_justification: Requer análise de sistemas externos, decisões de arquitetura de robô e geração de código resiliente
+---
+
+# eng.rpa.robot
+
+Workflow unificado para criação (`new`) ou manutenção (`update`) de robôs de automação.
+
+> 📋 **Rules**: `$IDE/rules/engineering/rpa/eng.rpa-rules.md`
+> 📋 **Docs**: `$IDE/rules/engineering/eng.docs-scraping-rules.md`
+> 🤖 **Agente**: ARACHNE (`$IDE/agents/engineering/eng.rpa.agent.md`)
+
+---
+
+## Entrada
+
+<arguments>
+#$ARGUMENTS
+</arguments>
+
+Formato esperado: `new {TASK_MANAGER_KEY}` ou `update {TASK_MANAGER_KEY}`
+
+**Se não receber argumentos ou estiverem incompletos**, perguntar na seguinte ordem:
+
+1. **Modo**: criar robô novo (`new`) ou atualizar/manter robô existente (`update`)?
+2. **Card**: qual o ID da tarefa no board? (ex: RPA-123)
+3. **[se `new`]** Qual o tag do serviço? (ex: `ba`, `sp`, `mg`) — será usado como `{robot-tag}`
+4. **[se `update`]** Qual robô será mantido? Listar opções:
+   ```bash
+   ls docs/engineering/robots/
+   ```
+   Apresentar a lista e pedir que o dev escolha.
+
+> O `{robot-tag}` é o nome do serviço do robô em kebab-case (ex: `ba` → `ba-robot.md`).
+> Nunca usar nomes de sistemas externos hardcodados como tag.
+
+---
+
+## Fase 0 — Setup
+
+### 0.1 Verificar ENV.md
+
+```bash
+grep -E "^(SQUAD|HUB|POSITION|ENABLE_CDD)=" $IDE/ENV.md
+```
+
+### 0.2 CDD (condicional)
+
+```bash
+grep "^ENABLE_CDD=" $IDE/ENV.md
+```
+
+- Se `ENABLE_CDD=true` → executar `/context-detect {TASK_MANAGER_KEY}` antes de prosseguir
+- Se `ENABLE_CDD=false` ou não definida → pular
+
+### 0.3 Criar Branch e Sessão
+
+```bash
+git checkout dev && git pull origin dev
+git checkout -b {TASK_MANAGER_KEY}-{robot-tag}
+mkdir -p $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
+echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" > $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/.timestamp_start
+```
+
+> Branch sempre criada a partir de `dev`. Nunca de `main`/`master`.
+
+---
+
+## Modo `new` — Criar Robô Novo
+
+### Fase N1 — Análise do Sistema-Alvo
+
+> ⚠️ Obrigatória antes de qualquer código.
+>
+> 🔍 **Ferramentas de exploração disponíveis nesta fase** (não geram código de produção):
+>
+> | Situação | Ferramenta |
+> |----------|-----------|
+> | MCP Playwright disponível na sessão | **Playwright MCP** — navega e inspeciona direto da IDE sem sair do contexto |
+> | Dev quer demonstrar o fluxo manualmente | **Playwright CLI** — `npx playwright codegen {url}` grava as interações e sugere seletores |
+> | Fluxo descrito em linguagem natural, seletores desconhecidos | **Stagehand** (`/eng-scraper-robot-builder`) — usa `observe()` para descobrir seletores via IA |
+>
+> **Escolha da ferramenta:**
+> - **Padrão** — perguntar ao dev qual ferramenta prefere usar para explorar o sistema-alvo
+> - **Se `MAX_AI_EXECUTION_PERCENTAGE=100`** — decidir automaticamente, sem perguntar:
+>   1. Playwright MCP disponível na sessão → usar MCP
+>   2. MCP indisponível + fluxo descrito em linguagem natural → Stagehand
+>   3. MCP indisponível + fluxo não descrito → Playwright CLI codegen
+>
+> O output de qualquer ferramenta é insumo para o `architecture.md` — não vai para produção diretamente.
+
+**N1.1 Verificar robots.txt e ToS**
+
+```bash
+curl -s "{sistema-alvo}/robots.txt"
+```
+
+Documentar o resultado. Se houver restrições legais significativas, comunicar ao usuário e aguardar decisão antes de prosseguir.
+
+**N1.2 Reconhecimento do Fluxo**
+
+Perguntar ao usuário (ou extrair do card):
+
+1. Qual o fluxo de autenticação? (formulário, token, cookie, sem auth)
+2. Quais as URLs envolvidas em cada etapa?
+3. Quais campos precisam ser extraídos?
+4. Qual o formato de saída? (JSON, CSV, banco de dados, fila)
+5. Existe mecanismo anti-bot conhecido? (rate limiting, captcha, fingerprinting)
+
+**N1.3 Mapear Campos Disponíveis vs. Necessários**
+
+Identificar explicitamente:
+- Campos que **existem** na fonte e serão extraídos
+- Campos que **não existem** na fonte — documentar como limitação por design
+
+Apresentar o mapeamento ao usuário antes de prosseguir.
+
+**N1.4 Decisão de Ferramenta**
+
+> ⚡ **Princípio HTTP-first**: sempre tentar quebrar o site via requisição HTTP antes de recorrer ao browser. Browser é mais lento, frágil e custoso — só usar quando HTTP não for viável.
+
+Ordem de investigação:
+1. Inspecionar as requests de rede do fluxo (DevTools / Playwright MCP / CLI codegen) — verificar se existe API HTTP ou endpoint que retorna os dados diretamente
+2. **Se existir** → implementar com axios + retry (sem browser)
+3. **Se não existir / exigir renderização JS** → recorrer ao browser
+
+| Ferramenta | Quando usar |
+|-----------|------------|
+| axios + retry wrapper | API HTTP identificada, autenticação via token/cookie |
+| Cheerio + axios | HTML estático sem JS relevante |
+| Puppeteer ou Playwright | Renderização JS obrigatória, sem API HTTP viável |
+| Puppeteer stealth | Anti-bot agressivo (Cloudflare, fingerprinting) |
+| `/eng-scraper-robot-builder` (Stagehand) | Fluxo descrito em linguagem natural, seletores desconhecidos |
+
+> ⚠️ **Captchas e proxies**: verificar se a infraestrutura anti-bot já existe no projeto (serviço de resolução de captcha, pool de proxies) — esses recursos são **pré-requisito compartilhado**, não devem ser implementados do zero por robô. Se não existirem, escalar para o TL antes de prosseguir.
+
+Aguardar confirmação antes de prosseguir.
+
+### Fase N1.5 — Criar architecture.md
+
+Com base em tudo coletado na análise, criar o arquivo de arquitetura da sessão:
+
+```
+$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md
+```
+
+O `architecture.md` de um robô RPA deve conter:
+
+| Seção | Conteúdo |
+|-------|---------|
+| **Contexto** | O que o robô resolve, card Jira, squad |
+| **Sistema-alvo** | URLs envolvidas em cada etapa do fluxo |
+| **Autenticação** | Tipo e fluxo de autenticação |
+| **Ferramenta** | Escolha (Puppeteer/Playwright/axios/etc.) e justificativa |
+| **Fases do robô** | Sequência: autenticação → navegação → extração → transformação → saída |
+| **Campos extraídos** | Tabela: campo → fonte → disponível (sim/não) |
+| **Limitações por design** | Campos que não existem na fonte — por que não é possível extrair |
+| **Riscos** | Anti-bot, autenticação frágil, campos instáveis, rate limiting |
+| **Variáveis de ambiente** | Lista de `process.env.*` necessárias |
+
+> ⚠️ **Apresentar o `architecture.md` ao dev e aguardar aprovação antes de prosseguir.**
+> Se houver ajustes, atualizar o arquivo e apresentar novamente.
+
+### Fase N2 — Plano de Execução
+
+```
+/eng.plan {TASK_MANAGER_KEY}
+```
+
+O `eng.plan` lê o `architecture.md` criado na fase anterior e produz o `plan.md` com as fases de implementação detalhadas.
+
+### Fase N3 — Implementação
+
+```
+/eng.work {TASK_MANAGER_KEY}
+```
+
+Garantir durante a implementação:
+- [ ] Seletores seguem prioridade: id > data-* > CSS estável > XPath
+- [ ] Retry com backoff em todos os I/Os que podem falhar
+- [ ] Logs estruturados por fase
+- [ ] Screenshot automático em falha (para browser headless)
+- [ ] Credenciais via `process.env` — nenhuma hardcodada
+- [ ] Testes unitários com mocks
+
+### Fase N4 — Documentação
+
+Criar `docs/engineering/robots/{robot-tag}-robot.md`.
+
+Seguir `$IDE/rules/engineering/eng.docs-scraping-rules.md`:
+
+| Seção | Conteúdo |
+|-------|---------|
+| Visão Geral | O que extrai e o que **não** extrai (limitações por design) |
+| Fluxo de Execução | Sequência de passos com URLs de cada etapa |
+| Fontes de Dados | Mapeamento de campos por fonte |
+| Campos Extraídos | Tabela por situação/estado do registro |
+| Variáveis de Ambiente | Lista de `process.env.*` necessárias (sem valores) |
+| Limitações Conhecidas | Campos indisponíveis — por que não é possível extrair |
+| Histórico de Bugs | Vazio na criação |
+| Checklist de Troubleshooting | Sintoma → causa provável → ação |
+
+Chamar `/docs-index` após criar.
+
+### Fase N5 — Pre-PR e PR
+
+```
+/eng.pre-pr
+/eng.pr
+```
+
+No corpo do PR incluir: link para `{robot-tag}-robot.md`, variáveis de ambiente necessárias, resultado do teste manual (se executado).
+
+---
+
+## Modo `update` — Manter Robô Existente
+
+### Fase U1 — Carregar Contexto do Robô
+
+Ler o documento existente do robô:
+
+```bash
+cat docs/engineering/robots/{robot-tag}-robot.md
+```
+
+Extrair e apresentar ao usuário:
+- O que o robô faz atualmente
+- Limitações conhecidas documentadas
+- Histórico de bugs relevantes
+- Variáveis de ambiente em uso
+
+### Fase U2 — Entender a Mudança
+
+Com base no card e no `{robot-tag}-robot.md`, identificar:
+
+1. O que precisa mudar? (novo campo, correção de seletor, novo fluxo, bug fix)
+2. Mudança afeta o sistema-alvo ou é interna ao robô?
+3. Se envolve sistema-alvo: o layout/comportamento mudou ou é a mesma versão?
+4. Há campos novos disponíveis na fonte ou continua com as mesmas limitações?
+
+**Se a mudança envolve o sistema-alvo**, usar as ferramentas de exploração para inspecionar o que mudou antes de propor qualquer código:
+
+| Situação | Ferramenta |
+|----------|-----------|
+| MCP Playwright disponível | **Playwright MCP** — inspecionar o estado atual do site |
+| Dev quer demonstrar o que mudou | **Playwright CLI** (`codegen`) |
+| Fluxo descrito em texto | **Stagehand** (`observe()`) |
+
+> A escolha segue a mesma regra do modo `new`: perguntar ao dev qual prefere, exceto se `MAX_AI_EXECUTION_PERCENTAGE=100` — nesse caso decidir automaticamente.
+
+**Se a mudança for estrutural** (ex: site que antes não tinha API agora tem), reavaliar a abordagem aplicando o princípio HTTP-first antes de implementar.
+
+Apresentar diagnóstico antes de implementar.
+
+### Fase U2.5 — Criar architecture.md de Manutenção
+
+Criar o arquivo de sessão que registra o contexto da mudança:
+
+```
+$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md
+```
+
+O `architecture.md` de uma manutenção de robô deve conter:
+
+| Seção | Conteúdo |
+|-------|---------|
+| **Contexto** | O que está sendo mantido, card Jira, squad |
+| **Robô** | `{robot-tag}`, link para `{robot-tag}-robot.md` |
+| **Tipo de mudança** | `bugfix` / `novo-campo` / `novo-fluxo` / `refactor` |
+| **Descrição da mudança** | O que muda e por quê |
+| **Impacto no sistema-alvo** | Sim/não — se sim, o que foi inspecionado e o que mudou |
+| **Arquivos afetados** | Lista de arquivos que serão alterados |
+| **Variáveis de ambiente** | Novas env vars necessárias (se houver) |
+
+> ⚠️ **Apresentar ao dev e aguardar confirmação antes de prosseguir.**
+
+### Fase U3 — Implementação
+
+```
+/eng.work {TASK_MANAGER_KEY}
+```
+
+Para bug fixes estruturais (seletor quebrado, campo mudou de posição):
+- Investigar o sistema-alvo antes de propor fix
+- Nunca assumir que o problema é no código sem verificar se o sistema-alvo mudou
+
+### Fase U4 — Atualizar Documentação
+
+Atualizar `docs/engineering/robots/{robot-tag}-robot.md`:
+
+- **Sempre**: Histórico de Bugs (toda correção estrutural entra aqui com referência ao card)
+- **Se campos mudaram**: atualizar Fontes de Dados e Campos Extraídos
+- **Se limitações mudaram**: atualizar Limitações Conhecidas
+- **Se fluxo mudou**: atualizar Fluxo de Execução
+
+> Uma atualização sem `{robot-tag}-robot.md` atualizado **não está pronta**.
+
+Chamar `/docs-index` após atualizar.
+
+### Fase U5 — Pre-PR e PR
+
+```
+/eng.pre-pr
+/eng.pr
+```
+
+---
+
+## Resumo Final
+
+```
+── Robô {new|update} ─────────────────────────────────────────
+  Modo     : {new | update}
+  Robô     : {robot-tag}-robot
+  Classe   : {RobotTag}Robot
+  Docs     : docs/engineering/robots/{robot-tag}-robot.md
+  Branch   : {TASK_MANAGER_KEY}-{robot-tag}
+  PR       : (link do MR criado pelo eng.pr)
+─────────────────────────────────────────────────────────────
+```
+
+---
+
+## Regras
+
+### Nunca
+- Pular a análise do sistema-alvo (modo `new`)
+- Pular leitura do `{robot-tag}-robot.md` existente (modo `update`)
+- Hardcodar credenciais ou nomes de sistemas externos
+- Omitir atualização da documentação ao final
+
+### Sempre
+- Verificar robots.txt antes de qualquer implementação nova
+- Documentar limitações conhecidas explicitamente
+- Usar retry com backoff em todos os I/Os
+- Atualizar Histórico de Bugs em toda correção estrutural (modo `update`)