jarvis-ai-framework 1.0.0

package/templates/engineering/ARD-template.md

@@ -0,0 +1,193 @@
+# 🧱 ARD Template — Architecture Requirement Document
+
+**Arquivo:** /docs/engineering/ARD/ARD-xxx-nome-da-arquitetura.md
+
+---
+
+## 🏗️ ARD-[número] — [Título da Arquitetura]
+
+**Status:** Proposta / Em desenvolvimento / Em validação / Finalizada  
+**Data:** [dd/mm/yyyy]  
+**Autor:** [Tech Lead / Arquiteto responsável]  
+**Revisores:** [Chapter Leads, Eng. de Plataforma, etc.]  
+**Relacionado a:** [RFC-xxx], [FRD-xxx], [PRD-xxx]  
+**Versão:** [1.0]
+
+---
+
+### 🔗 Referência ao PRD (obrigatório quando existir)
+
+- **Referência:** PRD-xxx – [Título]
+- **Arquivo/rota:** [link ou caminho do arquivo do PRD]
+
+#### Legenda (tipos de requisito)
+
+- **RF**: Requisito Funcional (comportamento/capacidade do sistema)
+- **NFR**: Requisito Não Funcional (qualidade: performance, disponibilidade, segurança, etc.)
+- **Restrição**: Limitação obrigatória (técnica/negócio/infra/processo) que guia a solução
+- **SLA**: Service Level Agreement (meta/compromisso mensurável de nível de serviço)
+- **Métrica**: Indicador de sucesso/monitoramento (KPI/SLI) usado para medir resultado
+
+#### Requisitos do PRD consumidos diretamente por este ARD
+
+| ID | Tipo (RF/NFR/Restrição/SLA/Métrica) | Origem (FRD/PRD) | Descrição | Como impacta a arquitetura |
+|----|-------------------------------------|------------------|-----------|----------------------------|
+
+### 🎯 Objetivo
+<!-- Descreva o propósito e metas técnicas -->
+
+---
+
+### 🚫 O que não é papel deste ARD
+
+- Redefinir objetivo de produto
+- Mudar regra de negócio
+- Criar feature nova “porque tecnicamente é melhor”
+- Discutir roadmap ou priorização
+
+> Se algo disso aparecer, é sinal de PRD mal definido ou incompleto. Pausar e validar com Produto/usuário antes de seguir.
+
+---
+
+### 🧠 Premissas e Restrições
+
+- Deve operar dentro do cluster GKE atual  
+- Sem dependência de serviços externos  
+- Limite de CPU total de 6vCPU
+
+---
+
+### ⚙️ Desenho da Arquitetura
+
+```mermaid
+graph TD
+A[Prometheus] -->|export metrics| B[Controller]
+B -->|ajusta concorrência| C[RabbitMQ]
+C --> D[Workers]
+B -->|salva estado| E[Redis]
+```
+
+---
+
+### 🧩 Componentes Principais
+
+| Componente | Função | Responsável |
+|-------------|--------|--------------|
+
+---
+
+### 🔄 Fluxos de Dados
+
+| Fluxo | Origem | Destino | Dados | Garantias (ordem/entrega) |
+|------|--------|---------|------|----------------------------|
+
+---
+
+### 🔌 Integrações
+
+| Integração | Tipo | Direção | Autenticação/Autorização | Observações |
+|----------|------|---------|---------------------------|-------------|
+
+---
+
+### 📜 Contratos (APIs, eventos, filas)
+
+#### APIs
+
+| Endpoint | Método | Request | Response | Erros | Autenticação | Observações |
+|----------|--------|---------|----------|-------|--------------|-------------|
+
+#### Eventos
+
+| Evento | Publisher | Consumers | Schema/Versão | Chave de idempotência | Observações |
+|-------|-----------|-----------|---------------|------------------------|-------------|
+
+#### Filas / Tópicos
+
+| Recurso | Tipo | Producer | Consumers | DLQ/Retry | Ordenação | Observações |
+|---------|------|----------|-----------|----------|-----------|-------------|
+
+---
+
+### 🔐 Segurança e Compliance
+
+- Autenticação via Service Account GCP  
+- Secrets gerenciados pelo Secret Manager  
+- Logs e métricas auditáveis no Stackdriver
+
+---
+
+### 📊 Métricas e Observabilidade
+
+- queue_backlog_total  
+- rebalance_iterations  
+- consumer_restarts
+
+---
+
+### ⚖️ Escalabilidade e Resiliência
+
+- Controlador roda em pod único com HPA mínimo 1 / máximo 3  
+- Retry backoff exponencial  
+- Fallback para configuração manual via Redis
+
+---
+
+### 🧠 Decisões Técnicas e Trade-offs
+
+| Decisão | Referência no PRD (RF/NFR/Restrição/SLA/Métrica) | Alternativas consideradas | Trade-offs | Decisão final |
+|--------|-----------------------------------------------|----------------------------|------------|--------------|
+
+---
+
+### ⚔️ Riscos e Mitigações
+
+| Risco | Mitigação |
+|-------|------------|
+
+---
+
+### ✅ Critérios de Sucesso
+
+- Redistribuição dinâmica < 30s  
+- Nenhum downtime detectado  
+- Redução ≥ 25% no tempo médio de fila  
+- Logs e métricas funcionais
+
+---
+
+### 🧩 Roadmap Técnico
+
+| Etapa | Responsável | Status |
+|-------|--------------|--------|
+
+---
+
+### 🏗️ Como vamos construir isso de forma segura, escalável e sustentável?
+
+#### Segurança
+
+| Medida | Como aplicar | Validação |
+|--------|-------------|----------|
+
+#### Escalabilidade
+
+| Medida | Como aplicar | Validação |
+|--------|-------------|----------|
+
+#### Sustentabilidade (manutenção e evolução)
+
+| Medida | Como aplicar | Validação |
+|--------|-------------|----------|
+
+---
+
+### 🧩 Anexos
+
+- [RFC-xxx](../RFC/RFC-xxx.md)  
+- [AVD-xxx](../AVD/AVD-xxx.md)
+
+---
+
+### 🏁 Conclusão
+<!-- Resumo da decisão arquitetural final -->

package/templates/engineering/CONTACTS-template.md

@@ -0,0 +1,135 @@
+ Contatos Importantes
+
+> Lista de pessoas-chave do time e quando procurá-las.
+
+ Membros do Time
+
+> Esta seção é atualizada automaticamente quando alguém executa `/init-jarvis`.
+
+| Nome | Cargo | Área | Hub | Email |
+|------|-------|------|-----|-------|
+<!-- MEMBERS_START -->
+<!-- MEMBERS_END -->
+
+ Liderança
+
+| Nome | Cargo | Responsabilidade | Quando Procurar | Contato |
+|------|-------|------------------|-----------------|---------|
+| [Nome] | Tech Lead | Decisões técnicas, arquitetura | Dúvidas de design, bloqueios técnicos | @slack |
+| [Nome] | Product Owner | Requisitos, priorização | Dúvidas sobre features, escopo | @slack |
+| [Nome] | Engineering Manager | Processos, carreira | :s, feedback, processos | @slack |
+| [Nome] | QA Lead | Qualidade, testes | Estratégia de testes, bugs críticos | @slack |
+
+ Especialistas
+
+| Área | Nome | Quando Procurar |
+|------|------|-----------------|
+| Backend | [Nome] | APIs, performance, banco de dados |
+| Frontend | [Nome] | UI/UX, componentes, estado |
+| DevOps | [Nome] | CI/CD, infraestrutura, deploy |
+| Segurança | [Nome] | Vulnerabilidades, autenticação |
+| Data | [Nome] | Analytics, relatórios, BI |
+
+ Canais de Comunicação
+
+ Chat (`$MESSAGE_COMUNICATOR`)
+
+| Canal | Propósito |
+|-------|-----------|
+| `squad-{nome}` | Comunicação geral do squad |
+| `squad-{nome}-dev` | Discussões técnicas |
+| `squad-{nome}-alerts` | Alertas de produção |
+| `engineering` | Engenharia geral |
+| `help-devops` | Suporte de infraestrutura |
+
+ Reuniões Recorrentes
+
+| Reunião | Frequência | Horário | Participantes |
+|---------|------------|---------|---------------|
+| Daily | Diária | : | Todo o squad |
+| Planning | Quinzenal | Segunda : | Todo o squad |
+| Retro | Quinzenal | Sexta : | Todo o squad |
+| Tech Review | Semanal | Quarta : | Engenharia |
+| : com EM | Quinzenal | A definir | Você + EM |
+
+ Escalação
+
+ Problemas Técnicos
+
+```
+. Tentar resolver sozinho (- min)
+      
+. Pedir ajuda no canal tech-{nome-do-squad}
+      
+. Escalar para Tech Lead
+      
+. Escalar para Specialist
+      
+. Escalar para Head of Tech
+
+Recomendação: ler o playbook de tomada de decisões em tecnologia do time (wiki / docs internos)
+```
+
+ Incidentes em Produção
+
+```
+. Alertar no canal squad-{nome}-alerts
+      
+. Acionar pessoa de plantão (PagerDuty)
+      
+. Seguir runbook de incidentes
+      
+. Postmortem após resolução
+```
+
+ Acessos Necessários
+
+ Checklist de Acessos
+
+| Sistema | Responsável | Como Solicitar |
+|---------|-------------|----------------|
+| Controle de versão (`$VERSION_CONTROL`) | Tech Lead | Pedir no chat do time |
+| Task manager (`$TASK_MANAGER`) | EM | Ticket / canal de acessos |
+| Cloud console | DevOps | Ticket / canal de acessos |
+| Observabilidade (`$OBSERVABILITY`) | DevOps | Pedir no canal de infra |
+| Chat (`$MESSAGE_COMUNICATOR`) | EM | Pedir no chat do time |
+| VPN | Infra | Ticket / canal de acessos |
+
+ Credenciais de Desenvolvimento
+
+| Recurso | Como Obter |
+|---------|------------|
+| Banco de dados (dev) | `.env.example` + pedir senha no chat do time |
+| APIs externas (sandbox) | Documentação interna |
+| Tokens de teste | Vault ou Password do time |
+
+ Links Úteis
+
+| Recurso | Link |
+|---------|------|
+| Board do squad | `{TASK_MANAGER_URL_BASE}` |
+| Repositório | URL do `$VERSION_CONTROL` do projeto |
+| Documentação | `$DOCS_FOLDER/` |
+| Runbooks | `docs/runbooks/` |
+| Postmortems | `docs/postmortems/` |
+| Wiki | URL da wiki da organização |
+
+ Dicas de Comunicação
+
+. Seja específico - "Estou com erro X no arquivo Y" > "Não funciona"
+. Mostre o que tentou - Demonstra esforço e ajuda a diagnosticar
+. Use threads - Mantém o canal organizado
+. Marque pessoas - Se precisar de alguém específico, @mencione
+. Documente - Se a resposta pode ajudar outros, documente
+
+ Primeiro Contato
+
+Ao entrar no time, apresente-se no canal `squad-{nome}`:
+
+```
+Olá!  Sou [Nome], novo [Cargo] do squad.
+Venho de [Experiência anterior].
+Meus interesses são [X, Y, Z].
+Podem me encontrar no chat do time ou [outro contato].
+Animado para trabalhar com vocês!
+```

package/templates/engineering/PR-template.md

@@ -0,0 +1,40 @@
+## Descrição
+
+Descreva de forma sucinta o objetivo do MR
+
+## Tarefas Relacionadas
+
+- [ ] [TASK-ID]({TASK_MANAGER_URL_BASE}/browse/TASK-ID)
+
+## Mudanças Propostas
+
+- Mudança 1
+- Mudança 2
+- Mudança n
+
+## Testes Realizados
+
+Descrição dos testes realizados
+
+## Revisores
+
+- @
+- @
+- @
+
+## Observações Específicas
+
+- Capturas de telas;
+- Contexto que ajude a revisar do código
+
+## Checklist de Revisão
+
+- [ ] As mudanças estão alinhadas com os requisitos da tarefa do Jira.
+- [ ] Os testes unitários/funcionais propostos foram executados e passaram.
+- [ ] O código segue as convenções de estilo da empresa.
+- [ ] A documentação foi atualizada, se necessário.
+- [ ] A solução não causa impactos negativos em outras áreas do sistema.
+- [ ] Não há erros ou advertências nas análises de qualidade de código.
+- [ ] A solicitação de merge foi revisada por pelo menos um revisor.
+
+## Linked Issues

package/templates/engineering/RFC-Playbook.md

@@ -0,0 +1,325 @@
+# Versão: 1.0
+
+Escopo: Engineering Core e Squads.
+
+Objetivo: Alinhar a criação de soluções de acordo com a visão de Tencologia. Este playbook é um artefato vivo e pode evoluir conforme a maturidade da engenharia.
+
+## Objetivo
+
+Este playbook define **como RFCs são usados na prática**, quais são os **papéis, responsabilidades, expectativas e regras** para garantir:
+
+* Uso eficiente de energia do time
+* Decisões técnicas claras
+* Menos retrabalho
+* Governança sem burocracia
+* Escalabilidade do processo de engenharia
+
+\
+RFC neste contexto **não é um documento de ideia** e **não é uma etapa isolada**. RFC é o **fio condutor da decisão**, do problema até a aprovação técnica.
+
+
+---
+
+## O que é um RFC (no nosso modelo)
+
+RFC é um **container vivo de decisão técnica**, que:
+
+* Pode ser aberto e evoluir junto com PRD e FRD se for necessário
+* Não decide nada no início
+* Só é fechado após maturidade suficiente de PRD e FRD para permitir uma decisão consciente
+* Registra comentários, trade-offs e a decisão final
+
+
+---
+
+## Visão Geral do Fluxo
+
+```none
+[Ideia ou problema]
+↓
+RFC (Draft — aberto)
+↓
+PRD (visão de produto)
+↓
+FRD (comportamento funcional)
+↓
+RFC (review + convergência + decisão)
+↓
+ARD (arquitetura)
+↓
+Implementação
+↓
+AVD (validação pós-implementação)
+```
+
+---
+
+## Estados do RFC e significado
+
+| Status | Significado | Energia esperada |
+|----|----|----|
+| Draft | Investigação inicial | Muito baixa |
+| In Review | PRD/FRD existem | Baixa |
+| Ready for Decision | Marcar agenda para apresentar o documento final | Média |
+| Accepted | Autorizado a implementar | Alta |
+| Rejected | Decisão de não seguir | Encerrada |
+| Superseded | Substituído | Encerrada |
+
+
+---
+
+## Papéis e Responsabilidades
+
+### 1. Proponente (Dev, TL, PM, etc.)
+
+**Responsabilidades**
+
+* Detectar o problema ou oportunidade
+* Abrir o RFC em status `Draft`
+* Garantir que o PRD já esteja criado
+* Manter o RFC atualizado com links corretos
+
+**O que NÃO é esperado**
+
+* Propor solução técnica cedo
+* Defender arquitetura
+* Forçar aprovação
+
+
+---
+
+### 2. Produto (PM / PO)
+
+**Responsabilidades**
+
+* Validar o problema e a hipótese
+* Garantir clareza do PRD
+* Ajudar a definir escopo e fora de escopo
+* Alinhar indicadores de sucesso
+
+**O que NÃO é esperado**
+
+* Definir stack
+* Influenciar decisões técnicas
+
+
+---
+
+### 3. Engenharia 
+
+**Responsabilidades**
+
+* Avaliar viabilidade técnica
+* Avaliar e contemplar todos os documentos PRD/FRD
+* Explicitar trade-offs e riscos
+* Referenciar corretamente o RFC
+
+**O que NÃO é esperado**
+
+* Decidir sozinho
+* Começar implementação sem RFC Accepted
+
+
+---
+
+### 4. Reviewers (TLs / Engineering Core)
+
+**Responsabilidades**
+
+* Ler o RFC
+* Comentar no RFC na ferramenta selecionada (não em chats ou meets soltos)
+* Avaliar riscos, custos, escalabilidade e operação e alinhamento estratégico
+* Ajudar a amadurecer a decisão
+* Ver o vinculo com os OKRs que estão sendo executados no quarter
+
+**O que NÃO é esperado**
+
+* Redesenhar solução sem base
+* Trazer opiniões sem leitura prévia
+
+
+---
+
+### 5. Decisores (TL / Core / Head / CTO)
+
+**Responsabilidades**
+
+* Avaliar o conjunto (RFC)
+* Tomar decisão explícita
+* Registrar condições, se houver
+* Fechar o RFC
+
+**O que NÃO é esperado**
+
+* Decidir sem artefatos
+* Reabrir discussões após aceite
+
+
+---
+
+## Regras de Ouro (não negociáveis)
+
+* ❌ RFC não pode ser Accepted sem clareza arquitetural suficiente
+* ❌ Implementação não começa sem RFC `Accepted`
+* ❌ Decisões não acontecem em chats privados
+* ✅ RFC pode permanecer aberta enquanto PRD e FRD evoluem
+* ✅ Energia investida cresce conforme maturidade
+
+
+---
+
+## Boas Práticas
+
+* RFC curto e objetivo
+* Comentários registrados no RFC
+* Decisão explícita sempre
+* Trade-offs documentados
+* Pendências com owner e prazo
+* Se você já sabe o “como”, não é RFC.
+* Se você ainda discute alternativas, é RFC.
+* Se durante a elaboração de um ARD surgir uma dúvida estrutural ou alternativa relevante, o ARD deve ser pausado e a discussão movida novamente para a RFC.
+
+
+---
+
+## Anti-Padrões (evitar)
+
+* RFC como brainstorm
+* RFC como checklist burocrático
+* RFC aprovado “no verbal”
+* Arquitetura decidida antes do ARD
+* Implementação iniciada sem aceite
+
+
+---
+
+## Lembretes Culturais
+
+* Se você já sabe **como** implementar, isso não é RFC.
+* Se ainda existem alternativas relevantes, isso **é** RFC.
+* Decisões importantes não acontecem fora deste documento.
+
+
+---
+
+## Quando uma RFC é obrigatória (regra de ouro)
+
+RFC **não é para tudo**. Uma RFC é **obrigatória** se **qualquer** item abaixo for verdadeiro:
+
+### Critérios objetivos (use como checklist)
+
+* Impacta **mais de uma squad**
+* Altera **arquitetura**, **padrões técnicos** ou **infra**
+* Introduz **nova dependência crítica** (serviço, lib, vendor)
+* Afeta **custo recorrente** (cloud, APIs, licenças)
+* Muda **SLA, SLO ou contratos técnicos**
+* Pode gerar **lock-in** ou dívida técnica relevante
+* Envolve **dados sensíveis / compliance**
+* Vai virar **padrão reutilizável**
+
+### Não exige RFC:
+
+* Refactors locais
+* Correções pontuais
+* Features isoladas sem impacto sistêmico
+
+\
+## Passo a Passo para apertura de um RFC
+
+### 🧩 Passo 1 — Criação da RFC
+
+**Quem cria:**
+
+* TL, Staff, Principal, Head ou qualquer dev **que proponha a mudança**
+
+**Onde:**
+
+* Repositório único na Wiki
+* Seguir o template estabelecido `RFC-template.md`
+
+**Formato:**
+
+* Markdown
+* ID sequencial: RFC-001, RFC-002, etc.
+
+**Status inicial:** Draft
+
+
+---
+
+### 🧩 Passo 2 — Divulgação obrigatória
+
+A RFC **não vale se ninguém souber que ela existe**.
+
+**Checklist mínimo:**
+
+* Link compartilhado no Slack (#tech-rfcs)
+* Menção aos revisores obrigatórios
+* Data limite para comentários (ex: D+5)
+
+Exemplo de mensagem padrão no Slack:
+
+> 📄 Nova RFC aberta: RFC-023 — Redistribuição dinâmica de concorrência\nComentários até: 10/11\nRevisores: @plataforma @backend @infra
+
+
+---
+
+### 🧩 Passo 3 — Discussão assíncrona (regra crítica)
+
+**Regras claras:**
+
+* Comentários **no documento**, não no privado
+* Opiniões **com argumento técnico**
+* Discordância é esperada e desejada
+
+**Anti-padrões proibidos:**
+
+* Decidir tudo em call fechada
+* “Já implementamos, depois documentamos”
+* Aprovação sem leitura
+
+
+---
+
+### 🧩 Passo 4 — Decisão formal
+
+Após o prazo:
+
+* O **dono da RFC** consolida os comentários
+* Registra a decisão final no próprio documento
+
+Possíveis decisões:
+
+* ✅ Aprovada
+* ⚠️ Aprovada com ressalvas
+* ❌ Rejeitada
+* 🔄 Retornar para ajustes
+
+⚠️ **Regra importante**\nDecisão **sempre documentada**, mesmo se for “não vamos fazer”.
+
+
+---
+
+### 🧩 Passo 5 — Gate para implementação
+
+Regra simples e poderosa:
+
+> ❌ **Não existe implementação relevante sem RFC aprovada**
+
+Tecnicamente:
+
+* Link da RFC vira **pré-requisito do ARD**
+* PRs grandes devem referenciar a RFC
+
+
+## Conclusão
+
+> RFC existe para **proteger o time de  fazer implementações eficientes**
+
+Seguir este playbook garante:
+
+* Menos desgaste
+* Menos retrabalho
+* Mais clareza
+* Decisões escaláveis
+