jarvis-ai-framework 1.0.0

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

@@ -0,0 +1,359 @@
+---
+trigger: always_on
+---
+
+> **Applies to:** HUB: all | POSITION: all | AREA: ENGINEERING | SQUAD: all
+
+# Regras do Workflow PR (Pull Request / Merge Request)
+
+## Propósito
+
+O workflow `pr` tem como objetivo **criar a branch, commitar as alterações e abrir um Merge Request** seguindo os padrões do time.
+
+---
+
+## ⛔ 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).
+
+**→ PARAR. Não executar nenhuma fase.**
+
+### 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. Padrão de Nomenclatura de Branch
+
+O nome da branch **DEVE** seguir o padrão:
+
+```
+{TASK_MANAGER_KEY}-{titulo-em-kebab-case}
+```
+
+**Regras:**
+- `TASK_MANAGER_KEY` em **UPPERCASE** (ex: `TASK-123`, `STORY-456`)
+- Título extraído do Jira convertido para **kebab-case**
+- Remover caracteres especiais
+- Substituir espaços por hífens
+
+**Exemplos:**
+
+| TASK_MANAGER_KEY | Título no Jira | Nome da Branch |
+|----------|----------------|----------------|
+| `TASK-123` | "Implementar autenticação JWT" | `TASK-123-implementar-autenticacao-jwt` |
+| `STORY-456` | "Adicionar botão de logout" | `STORY-456-adicionar-botao-de-logout` |
+| `BUG-789` | "Fix: null pointer em login" | `BUG-789-fix-null-pointer-em-login` |
+
+### 2. Padrão de Commit
+
+**Formato da mensagem de commit:**
+
+```
+{TASK_MANAGER_KEY} {tipo}({escopo}): {descrição}
+```
+
+**Tipos permitidos:**
+- `feat`: Nova funcionalidade
+- `fix`: Correção de bug
+- `docs`: Documentação
+- `style`: Formatação (não afeta código)
+- `refactor`: Refatoração
+- `test`: Testes
+- `chore`: Manutenção
+
+**Exemplo:**
+```
+TASK-123 feat(auth): implementar autenticação JWT
+```
+
+Sempre utilizar commits de 1 linha, dividir em vários commits quando for necessário, caso esteja implementando uma tarefa pai, commits de filhas devem conter o TASK_MANAGER_KEY das filhas.
+
+### 3. Branch de Destino
+
+O MR deve ser aberto para a branch especificada pelo usuário.
+
+**Branches comuns:**
+- `develop` - Para features e bugs
+- `main` - Para hotfixes (com aprovação)
+- `hotfix/{TASK_MANAGER_KEY}-{titulo-em-kebab-case}` - Para correções direto em produção (Apenas MRs com hotfix podem ser abertos diretamente para a branch main
+sempre utiliza a branch main)
+
+---
+
+
+## Fluxo de Execução
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│  1. VALIDAR → Testes passando, lint OK                      │
+│        ↓                                                    │
+│  2. CRIAR BRANCH → {TASK_MANAGER_KEY}-{titulo}                      │
+│        ↓                                                    │
+│  3. STAGE → git add (arquivos específicos)                  │
+│        ↓                                                    │
+│  4. COMMIT → Mensagem padronizada                           │
+│        ↓                                                    │
+│  5. PUSH → Enviar para remote                               │
+│        ↓                                                    │
+│  6. CRIAR MR (desenvolvedor) → Com template preenchido      │
+│        ↓                                                    │
+│  7. ATUALIZAR JIRA (desenvolvedor) → Mover para "In Review" │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Comportamento Esperado
+
+### Fase 1: Validação
+
+1. **Executar testes**
+   ```bash
+   npm test  # ou comando do projeto
+   ```
+
+2. **Verificar lint**
+   ```bash
+   npm run lint  # ou comando do projeto
+   ```
+
+3. **Verificar build**
+   ```bash
+   npm run build  # ou comando do projeto
+   ```
+
+**Se qualquer validação falhar**, corrigir antes de prosseguir.
+
+### Fase 2: Criação da Branch
+
+1. **Obter informações do Jira**
+   - TASK_MANAGER_KEY (ex: `TASK-123`)
+   - Título da tarefa
+
+2. **Criar branch**
+   ```bash
+   git checkout -b {TASK_MANAGER_KEY}-{titulo-kebab-case}
+   ```
+
+3. **Confirmar criação**
+   ```bash
+   git branch --show-current
+   ```
+
+### Fase 3: Stage e Commit
+
+1. **Adicionar arquivos específicos** (NUNCA usar `git add .`)
+   ```bash
+   git add {arquivo1} {arquivo2} ...
+   ```
+
+2. **Criar commit**
+   ```bash
+   git commit -m "{TASK_MANAGER_KEY} {tipo}({escopo}): {descrição}"
+   ```
+
+### Fase 4: Push
+
+1. **Enviar para remote**
+   ```bash
+   git push -u origin {nome-da-branch}
+   ```
+
+### Fase 5: Criar Merge Request
+
+1. **Preencher template do MR** com:
+   - Descrição clara do objetivo
+   - Link para o card do Jira
+   - Lista de mudanças realizadas
+   - Testes executados
+   - Checklist de revisão
+
+2. **Definir branch de destino** (conforme solicitado pelo usuário)
+
+3. **Criar MR** fica a cargo do desenvolvedor criar o MR da branch de origem para a destino, você pode retornar o link rápido de criação do MR do gitlab.
+
+### Fase 6: Atualizar Jira
+
+1. Desenvolvedor deve mover o card para "In Review"
+
+---
+
+## Template do Merge Request
+
+O MR deve seguir o template em `$IDE/templates/engineering/PR-template.md`:
+
+```markdown
+## Descrição
+
+{Objetivo claro do MR em 2-3 frases}
+
+## Tarefas Relacionadas
+
+- [x] [{TASK_MANAGER_KEY}]({TASK_MANAGER_URL_BASE}/browse/{TASK_MANAGER_KEY})
+
+## Mudanças Propostas
+
+- {Mudança 1}
+- {Mudança 2}
+- {Mudança N}
+
+## Testes Realizados
+
+- {Tipo de teste}: {Resultado}
+- Unitários: ✅ Passando
+- Lint: ✅ OK
+
+## Revisores
+
+- @{revisor1}
+- @{revisor2}
+
+## Checklist de Revisão
+
+- [x] As mudanças estão alinhadas com os requisitos da tarefa do Jira
+- [x] Os testes foram executados e passaram
+- [x] O código segue as convenções de estilo
+- [ ] A documentação foi atualizada (se necessário)
+```
+
+---
+
+## Regras de Segurança
+
+### ⛔ NUNCA FAÇA
+
+- ❌ `git add .` (adiciona arquivos indesejados)
+- ❌ Commitar arquivos de configuração local
+- ❌ Commitar credenciais ou tokens
+- ❌ Mencionar AI/Claude no PR
+- ❌ [!IMPORTANT] PUSH DIRETO PARA `main`/`dev`
+
+### ✅ SEMPRE FAÇA
+
+- ✅ Adicionar arquivos específicos
+- ✅ Verificar `git status` antes do commit
+- ✅ Usar mensagens de commit descritivas
+- ✅ Referenciar o TASK_MANAGER_KEY no commit
+- ✅ **Limpar sessão após criar MR**
+
+---
+
+## Erros Comuns a Evitar
+
+### ❌ Anti-padrões
+
+1. **Branch sem padrão**
+   - ❌ `feature/login`
+   - ✅ `TASK-123-implementar-login`
+
+2. **Commit genérico**
+   - ❌ `fix bug`
+   - ✅ `fix(auth): corrigir validação de token expirado`
+
+3. **Adicionar tudo**
+   - ❌ `git add .`
+   - ✅ `git add src/auth.ts src/auth.test.ts`
+
+4. **Esquecer referência**
+   - ❌ Commit sem TASK_MANAGER_KEY
+   - ✅ Commit começando com `TASK-123`
+
+---
+
+## Checklist de Conclusão
+
+Antes de considerar o PR completo:
+
+- [ ] Testes passando com cobertura maior 80%
+- [ ] Lint OK
+- [ ] Build OK
+- [ ] Branch criada no padrão `{TASK_MANAGER_KEY}-{titulo}`
+- [ ] Arquivos adicionados individualmente (não `git add .`)
+- [ ] Commit com mensagem padronizada
+- [ ] Commit referencia o TASK_MANAGER_KEY
+- [ ] Push realizado
+- [ ] MR criado com template preenchido
+- [ ] Branch de destino correta
+- [ ] Card do Jira movido para "In Review"
+- [ ] Comentários de code review processados
+- [ ] **Sessão limpa** (`$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/` removida)
+
+---
+
+## Limpeza da Sessão
+
+### Por que limpar?
+
+1. **Evitar poluição**: Sessões antigas ocupam espaço e confundem
+2. **Fonte da verdade**: A documentação oficial está no Jira e no MR
+3. **Organizacão**: Manter apenas sessões ativas
+
+### O que é removido?
+
+```
+$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
+├── architecture.md    → Removido
+├── plan.md            → Removido
+└── context.md         → Removido (se existir)
+```
+
+### Onde a documentação permanece?
+
+- **Card do Jira**: Tech spec anexada, comentários
+- **Merge Request**: Descrição, histórico de commits
+- **Código**: Comentários inline, docstrings
+
+### Comando de limpeza
+
+```bash
+rm -rf $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
+```

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

@@ -0,0 +1,103 @@
+---
+trigger: always_on
+---
+
+> **Applies to:** HUB: all | POSITION: all | AREA: ENGINEERING | SQUAD: all
+
+# Regras do Workflow Pre-PR
+
+## Propósito
+
+O workflow `pre-pr` valida a branch antes de abrir um Merge Request — revisão de código, testes, documentação e qualidade.
+
+---
+
+## ⛔ 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.**
+
+---
+
+## Regras de Validação
+
+### Escopo de Análise
+
+Avaliar **apenas** as mudanças da branch atual em relação ao branch base (`main`/`develop`):
+
+```bash
+git diff main...HEAD
+```
+
+### Evidências Obrigatórias
+
+Ao citar "testes passando" ou "validações OK", incluir:
+- Qual comando foi executado
+- Output do resultado (ou smoke test manual se não houver suíte)
+
+### Revalidação após Mudanças
+
+Se qualquer gate levar a mudanças de código, reexecutar obrigatoriamente:
+- Revisão técnica do código alterado
+- Testes/validações
+
+---
+
+## Saída Final Obrigatória
+
+O workflow **deve sempre** terminar com:
+
+1. **Semáforo de status**:
+   - 🟢 Green: pronto para PR
+   - 🟡 Yellow: pode abrir PR com ressalvas documentadas
+   - 🔴 Red: bloqueado — listar o que impede o PR
+
+2. **Comentário no card** com o status final (via `/eng-task-comment`) — pular se freelance
+
+3. **Aguardar permissão explícita** do usuário para prosseguir para `/eng.pr`

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

@@ -0,0 +1,246 @@
+---
+trigger: always_on
+---
+
+> **Applies to:** HUB: all | POSITION: all | AREA: ENGINEERING | SQUAD: all
+
+# Regras do Workflow Start
+
+## Propósito
+
+O workflow `start` tem como **único objetivo** criar o documento de arquitetura (`architecture.md`) para uma nova feature/tarefa. É uma etapa de **planejamento**, não de execução.
+
+---
+
+## Princípios Fundamentais
+
+### 1. Somente Planejamento - NUNCA Execução
+
+O `start` é **estritamente proibido** de:
+
+| ❌ Proibido                          | ✅ Permitido                              |
+| ------------------------------------ | ----------------------------------------- |
+| Criar arquivos de código (.ts, .js)  | Criar `architecture.md`                   |
+| Modificar código existente           | Ler código para análise                   |
+| Executar comandos no terminal        | Listar arquivos e estruturas              |
+| Instalar dependências                | Buscar padrões no codebase                |
+| Fazer commits                        | Criar diretório da sessão                 |
+| Executar testes                      | Documentar decisões                       |
+| Iniciar servidores                   | Dialogar com usuário                      |
+
+### 2. Artefato Único
+
+O **único artefato** produzido pelo `start` é:
+
+```
+$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md
+```
+
+> 📁 **Padrão**: `TASK_MANAGER_KEY` é o ID do card em **lowercase** (ex: `TASK-123` → `task-123`)
+
+Nenhum outro arquivo deve ser criado, modificado ou deletado.
+
+### 3. Aprovação Obrigatória
+
+O workflow **só é considerado completo** após:
+
+1. O `architecture.md` estar preenchido
+2. O usuário revisar o documento
+3. O usuário **aprovar explicitamente** para prosseguir
+
+---
+
+## Comportamento Esperado
+
+### Fase de Entrada
+
+1. **Receber identificador da tarefa (TASK_MANAGER_KEY)**
+   - Ler `TASK_MANAGER` do ENV.md (`eng.integrations-rules.md`)
+   - Se não veio em `$ARGUMENTS`: **perguntar e aguardar**
+     - Freelance (vazio): número de controle próprio (ex: `F-042`)
+     - Com board: id do card naquele vendor
+   - Converter para **lowercase** (ex: `F-042` → `f-042`)
+
+2. **Criar diretório da sessão**
+   - Caminho: `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/`
+   - Se já existir, avisar o usuário
+
+### Fase de Investigação
+
+3. **Coletar informações do requisito**
+   - Buscar card no board só se `TASK_MANAGER` estiver preenchido
+   - Ler documentação relacionada
+   - Analisar código existente (LEITURA APENAS)
+
+4. **Fazer perguntas de clarificação**
+   - Mínimo 3, máximo 5 perguntas
+   - Aguardar respostas antes de prosseguir
+   - Iterar até ter compreensão sólida
+
+### Fase de Documentação
+
+5. **Criar architecture.md**
+   - Usar template: `$IDE/templates/engineering/architecture-template.md`
+   - Preencher TODAS as seções
+   - Ser específico (arquivos reais, nomes de classes)
+
+6. **Apresentar ao usuário**
+   - Resumo das principais decisões
+   - Riscos identificados
+   - Solicitar revisão
+
+### Fase de Aprovação
+
+7. **Aguardar aprovação**
+   - Se aprovado → Informar próximos passos
+   - Se rejeitado → Iterar no documento
+   - NUNCA prosseguir automaticamente
+
+---
+
+## Regras de Nomenclatura
+
+### TASK_MANAGER_KEY (Identificador da Sessão)
+
+O nome da pasta de sessão é **sempre o TASK_MANAGER_KEY em lowercase**:
+
+```
+{TASK-123} → {task-123}
+```
+
+**Regras:**
+- Converter para **lowercase**
+- Manter o formato original (projeto-número)
+- Não adicionar sufixos ou descrições
+
+**Exemplos:**
+| Input (TASK_MANAGER_KEY)    | Nome da Pasta (Sessão)               |
+| ------------------- | ------------------------------------- |
+| `TASK-123`          | `$SESSIONS_DIR/eng/task-123/`        |
+| `STORY-456`         | `$SESSIONS_DIR/eng/story-456/`       |
+| `BUG-789`           | `$SESSIONS_DIR/eng/bug-789/`         |
+| `SPIKE-42`          | `$SESSIONS_DIR/eng/spike-42/`        |
+
+---
+
+## Qualidade do Architecture.md
+
+### Seções Obrigatórias
+
+O documento DEVE conter:
+
+- [ ] **Contexto** - Por que isso está sendo feito
+- [ ] **Objetivo** - O que será alcançado
+- [ ] **Escopo** - O que está incluído/excluído
+- [ ] **Estado Atual** - Como funciona hoje
+- [ ] **Estado Proposto** - Como funcionará
+- [ ] **Componentes Impactados** - Lista de arquivos
+- [ ] **Decisões Arquiteturais** - Com justificativas
+- [ ] **Dependências** - Internas e externas
+- [ ] **Riscos** - Com mitigações
+- [ ] **Estratégia de Testes** - Tipos e cobertura
+
+### Critérios de Qualidade
+
+| Critério                    | Descrição                                      |
+| --------------------------- | ---------------------------------------------- |
+| **Especificidade**          | Usa caminhos reais, não genéricos              |
+| **Completude**              | Todas as seções preenchidas                    |
+| **Clareza**                 | Sem ambiguidades ou jargões indefinidos        |
+| **Rastreabilidade**         | Links para Jira, docs, código                  |
+| **Decisões Justificadas**   | Cada decisão tem "por quê"                     |
+| **Riscos Mapeados**         | Riscos têm mitigações definidas                |
+
+---
+
+## Interação com Usuário
+
+### Perguntas de Clarificação
+
+Sempre pergunte sobre:
+
+1. **Escopo** - O que definitivamente NÃO está incluído?
+2. **Prioridade** - Qual parte é mais crítica?
+3. **Dependências** - Algo bloqueia esta implementação?
+4. **Restrições** - Há limitações técnicas conhecidas?
+5. **Validação** - Como saberemos que está funcionando?
+
+### Comunicação
+
+- **Seja claro** sobre o que é fato vs. suposição
+- **Declare incertezas** explicitamente
+- **Não assuma** - sempre pergunte
+- **Aguarde respostas** antes de prosseguir
+
+---
+
+## Erros Comuns a Evitar
+
+### ❌ Anti-padrões
+
+1. **Escapar para execução**
+   - "Vou criar o arquivo de teste para validar..."
+   - "Deixa eu instalar a dependência para verificar..."
+
+2. **Documentação genérica**
+   - "Modificar os arquivos necessários"
+   - "Implementar a funcionalidade"
+
+3. **Pular aprovação**
+   - Prosseguir sem confirmação explícita do usuário
+
+4. **Assumir requisitos**
+   - Decidir escopo sem confirmar com usuário
+
+5. **Ignorar riscos**
+   - Não documentar riscos óbvios
+
+### ✅ Boas Práticas
+
+1. **Ser específico**
+   - "Modificar `src/services/auth.service.ts` linha ~45"
+
+2. **Justificar decisões**
+   - "Escolhemos JWT porque o sistema já usa e..."
+
+3. **Mapear arquivos reais**
+   - Usar glob/grep para encontrar arquivos existentes
+
+4. **Documentar trade-offs**
+   - "Isso adiciona latência mas simplifica a arquitetura"
+
+---
+
+## Transição para Próxima Etapa
+
+Ao finalizar o `start`, informe claramente:
+
+```
+✅ Architecture.md criado e aprovado!
+
+📄 Documento: $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md
+
+📌 Próximos passos:
+1. eng.plan  → Criar plano detalhado com subtarefas
+2. eng.work  → Iniciar implementação
+
+⚠️ Lembre-se: Use eng.plan antes de eng.work
+```
+
+---
+
+## Checklist de Conclusão
+
+Antes de considerar o `start` completo:
+
+- [ ] Diretório `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/` criado
+- [ ] Arquivo `architecture.md` criado e completo
+- [ ] Template seguido corretamente
+- [ ] Todas as seções obrigatórias preenchidas
+- [ ] Decisões têm justificativas
+- [ ] Riscos têm mitigações
+- [ ] Componentes impactados listados com caminhos reais
+- [ ] Usuário revisou o documento
+- [ ] Usuário aprovou explicitamente
+- [ ] Nenhum código foi executado/criado
+- [ ] Próximos passos comunicados