jarvis-ai-framework 1.0.0

package/workflows/AGENTS.md

@@ -0,0 +1,240 @@
+# AGENTS.md - Pasta workflows/
+
+Instrucoes especificas para agentes de IA que manipulam a pasta de workflows.
+
+---
+
+## Proposito desta Pasta
+
+A pasta `workflows/` contem os **templates de execucao** dos comandos slash. Cada workflow define o passo a passo que um comando deve seguir.
+
+---
+
+## Estrutura
+
+```
+workflows/
+├── init.md                         # Inicializacao do framework
+├── warm-up.md                      # Preparacao de sessao
+├── warm-up@1.1.md                  # Versao alternativa
+├── help.md                         # Guia de ajuda
+├── all-tools.md                    # Listar ferramentas
+│
+├── docs/                           # Workflows de documentacao
+│   ├── build-product-docs.md
+│   ├── build-business-docs.md
+│   ├── build-tech-docs.md
+│   └── build-index.md
+│
+├── product/                        # Workflows de produto
+│   ├── prod.spec.md               # Entrypoint de specs
+│   ├── prod.spec.prd.md           # Documento de Requisitos de Produto
+│   ├── prod.spec.frd.md           # Documento de Requisitos Funcionais
+│   ├── prod.spec.breakdown.md     # Quebra em versões / épicos / histórias
+│   ├── prod.spec.epic.md          # Epicos
+│   ├── prod.spec.issue.md         # Issues
+│   └── prod.spec.clarify.md       # Clarificacao
+│
+└── engineering/                    # Workflows de engenharia
+    ├── eng.start.md               # Inicio de desenvolvimento
+    ├── eng.plan.md                # Planejamento
+    ├── eng.work.md                # Execucao
+    ├── eng.pre-pr.md              # Validacao pre-PR
+    ├── eng.pr.md                  # Criacao de PR
+    ├── eng.review.md              # Revisao
+    ├── eng.debug.md               # Debug
+    ├── eng.docs.md                # Documentacao
+    ├── eng.create-ard.md          # Criar ARD
+    ├── eng.create-ard-from-code.md
+    ├── eng.create-rfc.md          # Criar RFC
+    ├── eng.build-tech-spec.md     # Tech Spec
+    ├── eng.breakdown-subtasks.md  # Subtarefas
+    ├── light-arch.md              # Design leve
+    ├── frontend/
+    │   ├── eng.frontend-component.md   # Criar/refatorar componente frontend
+    │   ├── eng.frontend-review.md      # Revisão de PR frontend
+    │   └── eng.frontend-perf-audit.md  # Auditoria de performance (Core Web Vitals)
+    └── qa/
+        └── eng-qa-quality-gate-validation.md
+```
+
+---
+
+## Relacao Command → Workflow
+
+Cada command em `commands/` referencia um workflow:
+
+```markdown
+# nome-do-command
+Utilize o arquivo `../../workflows/[dominio]/nome-do-workflow.md` como template.
+```
+
+| Command | Workflow |
+|---------|----------|
+| `/init` | `init.md` |
+| `/warm-up` | `warm-up.md` |
+| `/eng.start` | `engineering/eng.start.md` |
+| `/eng.plan` | `engineering/eng.plan.md` |
+| `/eng.work` | `engineering/eng.work.md` |
+| `/eng.pr` | `engineering/eng.pr.md` |
+| `/eng.frontend-component` | `engineering/frontend/eng.frontend-component.md` |
+| `/eng.frontend-review` | `engineering/frontend/eng.frontend-review.md` |
+| `/eng.frontend-perf-audit` | `engineering/frontend/eng.frontend-perf-audit.md` |
+| `/prod.spec.prd` | `product/prod.spec.prd.md` |
+
+---
+
+## Convencoes de Nomenclatura
+
+| Tipo | Padrao | Exemplos |
+|------|--------|----------|
+| Workflow global | `{nome}.md` | `init.md`, `warm-up.md` |
+| Workflow versionado | `{nome}@{versao}.md` | `warm-up@1.1.md` |
+| Workflow de engenharia | `eng.{acao}.md` | `eng.start.md`, `eng.pr.md` |
+| Workflow de produto | `prod.{acao}.md` | `prod.spec.prd.md` |
+| Workflow de docs | `build-{tipo}-docs.md` | `build-tech-docs.md` |
+
+---
+
+## Estrutura de um Workflow
+
+Todo workflow deve conter:
+
+```markdown
+# {Nome do Workflow}
+
+## Objetivo
+O que este workflow faz.
+
+## Pre-requisitos
+- Validar ENV.md
+- Outros requisitos
+
+## Entrada
+- `$ARGUMENTS` - Descricao
+- Outros inputs
+
+## Fluxo de Execucao
+
+### Fase 1: {Nome}
+1. Passo 1
+2. Passo 2
+
+### Fase 2: {Nome}
+1. Passo 1
+2. Passo 2
+
+## Output
+Artefatos gerados.
+
+## Mensagem de Conclusao
+Feedback ao usuario.
+```
+
+---
+
+## Fases de Desenvolvimento
+
+Workflows de engenharia seguem fases restritas:
+
+| Fase | Workflows | Restricao |
+|------|-----------|-----------|
+| Planejamento | `eng.start`, `eng.plan` | Somente analise, SEM codigo |
+| Implementacao | `eng.work` | Codigo e testes, SEM commits |
+| Entrega | `eng.pr` | Branch, commit e PR |
+
+**IMPORTANTE**: Respeitar estritamente as restricoes de cada fase.
+
+---
+
+## Workflows vs Skills
+
+| Aspecto | Workflows | Skills |
+|---------|-----------|--------|
+| Define | O que fazer | Como fazer |
+| Nivel | Macro (fases) | Micro (passos) |
+| Ativacao | Via comando slash | Via workflow ou manual |
+| Escopo | Fluxo completo | Tarefa especifica |
+
+**Regra**: Workflows podem invocar skills para tarefas especificas.
+
+---
+
+## Regras
+
+### Nunca
+
+- Criar workflow sem command correspondente
+- Pular validacao de ENV.md (exceto `/init`)
+- Misturar fases de desenvolvimento em um workflow
+- Executar codigo em fase de planejamento
+- Fazer commit em fase de implementacao
+- Duplicar workflow existente
+
+### Sempre
+
+- Validar ENV.md no inicio (exceto `/init`)
+- Respeitar restricoes de fase
+- Definir output esperado
+- Incluir mensagem de conclusao
+- Manter consistencia com workflows similares
+- Referenciar templates quando aplicavel
+
+---
+
+## Fluxos Tipicos
+
+### Inicializacao de Projeto
+
+```bash
+/init
+/warm-up
+/prod.spec.prd
+```
+
+### Nova Feature
+
+```bash
+/warm-up
+/prod.spec.frd
+/eng.start "feature-id"
+/eng.plan "feature-id"
+/eng.work "feature-id"
+/eng.pre-pr
+/eng.pr
+```
+
+### Documentacao
+
+```bash
+/warm-up
+/build-product-docs
+/build-tech-docs
+/build-index
+```
+
+---
+
+## Criando Novo Workflow
+
+1. Identificar necessidade (verificar existentes)
+2. Criar command em `commands/`
+3. Criar workflow seguindo estrutura padrao
+4. Definir restricoes de fase (se engenharia)
+5. Vincular a templates (se aplicavel)
+6. Atualizar README.md
+7. Testar fluxo completo
+
+---
+
+## Referencias
+
+- `README.md` - Lista completa de workflows
+- `../commands/` - Commands que invocam workflows
+- `../skills/` - Skills invocados por workflows
+- `../templates/` - Templates usados por workflows
+- `../rules/` - Regras que governam workflows
+
+---
+
+**Ultima atualizacao**: 2026-01-26

package/workflows/README.md

@@ -0,0 +1,160 @@
+# Sistema de Workflows do Jarvis
+
+Este diretório contém os workflows (templates) usados pelos comandos slash do Jarvis, organizados por domínio.
+
+---
+
+## Estrutura de Workflows
+
+```
+workflows/
+├── warm-up.md                    # Preparação de sessão
+├── warm-up@1.1.md                # Variante do warm-up
+├── all-tools.md                  # Listar ferramentas
+│
+├── product/                      # Gestão de Produto & Requisitos
+│   ├── prod.spec.md              # Entrypoint de especificações
+│   ├── prod.spec.prd.md          # Documento de Requisitos de Produto
+│   ├── prod.spec.frd.md          # Documento de Requisitos Funcionais
+│   ├── prod.spec.breakdown.md    # Quebra em versões / épicos / histórias
+│   ├── prod.spec.epic.md         # Épicos
+│   ├── prod.spec.issue.md        # Issues (stories, tasks, bugs)
+│   └── prod.spec.clarify.md      # Esclarecer/validar spec
+│
+└── engineering/                  # Engenharia & Desenvolvimento
+    ├── eng.start.md              # Início de desenvolvimento
+    ├── eng.plan.md               # Planejamento
+    ├── eng.work.md               # Execução do trabalho
+    ├── eng.pre-pr.md             # Validação pré-PR
+    ├── eng.pr.md                 # Criação de PR
+    ├── eng.review.md             # Revisão
+    ├── eng.debug.md              # Debug/incident
+    ├── eng.bug-audit.md          # Auditoria de bugs
+    ├── eng.docs.md               # Documentação (engenharia)
+    ├── eng.create-ard.md         # Criar ARD
+    ├── eng.create-ard-from-code.md
+    ├── eng.create-rfc.md         # Criar RFC
+    ├── eng.build-tech-spec.md    # Criar Tech Spec
+    ├── eng.breakdown-subtasks.md # Quebrar em subtarefas
+    ├── eng.light-arch.md         # Design arquitetural leve
+    ├── eng.rpa.robot.md      # Criar robô RPA do zero ao PR (skill técnica)
+    ├── frontend/
+    │   ├── eng.frontend-component.md     # Criar/refatorar componente (design system vs remote, a11y, testes)
+    │   ├── eng.frontend-review.md        # Revisão de PR frontend (TS, tokens, a11y, MFE)
+    │   └── eng.frontend-perf-audit.md    # Auditoria Core Web Vitals e bundle
+    └── qa/
+        ├── eng-qa-quality-gate-validation.md
+        ├── eng-qa-e2e-test-generation.md
+        ├── eng-qa-exploratory-session.md
+        ├── eng-qa-dev-quality-guide.md
+        ├── eng-qa-quality-report.md
+        ├── eng-qa-refinement-entry.md
+        ├── eng-qa-release-signoff.md
+        └── eng-qa-sprint-planning.md
+```
+
+---
+
+## Workflows Globais
+
+| Workflow | Propósito |
+|----------|-----------|
+| `warm-up.md` | Preparar sessão carregando contexto do projeto |
+| `warm-up@1.1.md` | Variante do warm-up (versão 1.1) |
+| `all-tools.md` | Listar todas as ferramentas disponíveis |
+
+---
+
+## Workflows de Produto
+
+| Workflow | Propósito |
+|----------|-----------|
+| `prod.spec.md` | Entrypoint unificado para especificações |
+| `prod.spec.prd.md` | Criar/editar Documento de Requisitos de Produto |
+| `prod.spec.frd.md` | Criar/editar Documento de Requisitos Funcionais |
+| `prod.spec.breakdown.md` | Quebrar spec grande em versões, épicos e histórias |
+| `prod.spec.epic.md` | Criar/editar épicos |
+| `prod.spec.issue.md` | Criar/editar issues (stories, tasks, bugs) |
+| `prod.spec.clarify.md` | Esclarecer e validar especificações existentes |
+
+---
+
+## Workflows de Engenharia
+
+| Workflow | Propósito |
+|----------|-----------|
+| `eng.start.md` | Inicializar desenvolvimento e criar architecture.md |
+| `eng.plan.md` | Criar plano de execução por fases |
+| `eng.work.md` | Executar implementação de código |
+| `eng.pre-pr.md` | Validação final antes do PR |
+| `eng.pr.md` | Criar branch, commit e Pull Request |
+| `eng.review.md` | Revisão de solução/PR |
+| `eng.debug.md` | Debug e investigação de incidentes |
+| `eng.docs.md` | Atualizar documentação de engenharia |
+| `eng.create-ard.md` | Criar ARD (Architecture Review Document) |
+| `eng.create-ard-from-code.md` | Criar ARD a partir do código |
+| `eng.create-rfc.md` | Criar RFC (Request For Comments) |
+| `eng.build-tech-spec.md` | Criar especificação técnica |
+| `eng.breakdown-subtasks.md` | Quebrar tech spec em subtarefas |
+| `eng.bug-audit.md` | Auditoria e análise de bugs |
+| `eng.light-arch.md` | Design arquitetural leve |
+| `eng.rpa.robot.md` | Criar robô novo ou manter existente — análise, scaffolding, impl, docs, PR |
+| `eng.frontend-component.md` | Criar ou refatorar componente frontend com qualidade (design system vs remote, a11y, testes) |
+| `eng.frontend-review.md` | Revisão de código específica para PRs frontend (TypeScript, tokens, a11y, MFE) |
+| `eng.frontend-perf-audit.md` | Auditoria de performance frontend (Core Web Vitals, bundle, diagnóstico por métrica) |
+| `eng-qa-quality-gate-validation.md` | Validação de quality gate de um ticket |
+| `eng-qa-e2e-test-generation.md` | Geração de testes E2E Cypress para uma feature |
+| `eng-qa-exploratory-session.md` | Conduzir sessão de teste exploratório |
+| `eng-qa-dev-quality-guide.md` | Orientar dev a escrever seus próprios testes Cypress |
+| `eng-qa-quality-report.md` | Relatório de qualidade consolidado por sprint/release |
+| `eng-qa-refinement-entry.md` | Entrada do QA no refinement de tickets |
+| `eng-qa-release-signoff.md` | Sign-off QA pré-deploy (GO/NO-GO) |
+| `eng-qa-sprint-planning.md` | Planejamento de capacidade QA por sprint |
+
+---
+
+## Relação Command → Workflow
+
+Cada command em `commands/` referencia seu workflow correspondente:
+
+```markdown
+# nome-do-command
+Utilize o arquivo `../../workflows/[dominio]/nome-do-workflow.md` como template para este comando.
+```
+
+---
+
+## Fluxos de Trabalho Típicos
+
+### 1. Inicialização de Projeto
+```bash
+/init
+/warm-up
+/prod.spec.prd
+```
+
+### 2. Nova Feature
+```bash
+/warm-up
+/prod.spec.frd
+/prod.spec.clarify
+/prod.spec.breakdown   # se a feature ainda estiver grande
+/eng.start "feature-id"
+/eng.plan "feature-id"
+/eng.work "feature-id"
+/eng.pre-pr
+/eng.pr
+```
+
+---
+
+## Referências
+
+- [Agentes](../agents/README.md)
+- [Rules](../rules/)
+- [Templates](../templates/)
+- ENV.md (`$IDE/ENV.md`)
+
+---
+
+**Última atualização**: 2026-01-25

package/workflows/all-tools.md

@@ -0,0 +1,11 @@
+---
+description: Resumo de todos os workflows e ferramentas
+auto_execution_mode: 1
+recommended_model: gpt-4o-mini
+model_tier: low
+model_justification: Listagem simples de ferramentas, não requer raciocínio complexo
+---
+
+# all-tools
+
+Liste todas as ferramentas disponíveis detalhadas em seu prompt da plataforma. Exiba-as em marcadores. Mostre-as em formato de assinatura de função TypeScript e inclua o propósito da ferramenta como sufixo.

package/workflows/engineering/data/data.contract.md

@@ -0,0 +1,202 @@
+---
+description: Guia para criar contrato de dados entre o time de Data e uma squad requisitante
+auto_execution_mode: 2
+agent: "$IDE/agents/engineering/data/eng.data-engineer.agent.md"
+rules_file: "$IDE/rules/engineering/data/data-rules.md"
+template_file: "$IDE/templates/engineering/data-contract-template.md"
+recommended_model: claude-sonnet-4-20250514
+model_tier: medium
+model_justification: Criação de contrato é estruturada — preencher template com informações fornecidas, sem necessidade de raciocínio arquitetural complexo
+---
+
+# data.contract
+
+Guia para formalizar um contrato de dados entre o time de Data e uma squad requisitante,
+seguindo as convenções definidas em `$IDE/rules/engineering/data/data-rules.md`.
+
+> 📋 **Rules**: `$IDE/rules/engineering/data/data-rules.md`
+> 📤 **Template**: `$IDE/templates/engineering/data-contract-template.md`
+> 🤖 **Agente**: `$IDE/agents/engineering/data/eng.data-engineer.agent.md`
+
+> ℹ️ **Quando usar**: sempre que um dado em camada `gold` for exposto para consumo recorrente por outra squad.
+> Para consultas ad-hoc, não é necessário contrato — entregar via canal de solicitação de dados.
+
+---
+
+## Agentes recomendados
+
+- **eng.data-engineer** *(primário — obrigatório)*: conduz todo o workflow; responsável por formalizar o contrato, definir schema, SLA e restrições de acesso.
+  - Arquivo: `$IDE/agents/engineering/data/eng.data-engineer.agent.md`
+  - Quando usar: sempre — é o agente principal deste workflow.
+
+- **prod.pm-checker** *(opcional)*: valida se o caso de uso descrito pela squad requisitante está bem especificado e alinhado com o produto antes de formalizar o contrato.
+  - Arquivo: `$IDE/agents/product/prod.pm-checker.md`
+  - Quando usar: quando o caso de uso vier de uma solicitação de produto (squad de analytics/BI, analytics de negócio) ou houver ambiguidade sobre o que a squad realmente precisa.
+
+- **eng.docs-writer** *(opcional)*: apoia na redação de definições de negócio e glossário do contrato quando os dados tiverem semântica complexa.
+  - Arquivo: `$IDE/agents/engineering/eng.docs-writer.md`
+  - Quando usar: contratos de domínios com muitos termos de negócio (financeiro, operacional, BI).
+
+---
+
+## Entrada
+
+<contract_info>
+#$ARGUMENTS
+</contract_info>
+
+**Se não receber argumentos**, perguntar ao usuário (uma pergunta por vez):
+
+1. Qual a squad requisitante?
+2. Qual o caso de uso? (o que a squad precisa e por quê)
+3. Qual a tabela ou recurso de dados? (ex: `gold.fato_pedidos`)
+4. O pipeline que alimenta essa tabela já existe e está documentado?
+5. Há campos sensíveis envolvidos? (CPF, dados pessoais, localização)
+
+---
+
+## Fase 1 — Verificação de pré-requisitos
+
+### 1.1 — Confirmar solicitação formal
+
+O processo deve ter sido iniciado via canal de solicitação de dados (Slack `#data-requests` ou equivalente definido nas rules).
+
+Se não houver solicitação formal registrada:
+> ⚠️ Orientar a squad a abrir thread no canal com: caso de uso, frequência e SLA esperado — antes de prosseguir.
+
+### 1.2 — Confirmar existência do pipeline e da tabela gold
+
+Verificar se:
+- A tabela `gold.<nome>` existe e está populada
+- O pipeline que a alimenta está documentado (`data.new-pipeline.md`)
+- A Expectation Suite está ativa e passando
+
+Se o pipeline ainda não existe: executar `data.new-pipeline.md` antes de criar o contrato.
+
+---
+
+## Fase 2 — Preenchimento do contrato
+
+Preencher `$IDE/templates/engineering/data-contract-template.md` com as informações coletadas.
+
+### 2.1 — Campos obrigatórios
+
+| Campo | Observação |
+|-------|-----------|
+| Nome do contrato | Padrão: `{squad_requisitante}_{tabela}` (ex: `core_fato_pedidos`) |
+| Tabela / recurso | Sempre em camada `gold` |
+| Squad dona dos dados | Squad de Data (conforme `$SQUAD` do time responsável) |
+| Squad requisitante | Conforme solicitação |
+| Caso de uso | Descrição objetiva — o que a squad vai fazer com o dado |
+| Status | `Ativo` ao criar |
+| Válido até | Definir prazo ou `Indeterminado` |
+
+### 2.2 — Schema
+
+Listar **todos** os campos que serão expostos para a squad requisitante.
+
+Para cada campo, identificar:
+- Tipo de dado
+- Nulável?
+- Sensível? (CPF, dados pessoais, localização — consultar seção nas rules)
+
+> Se houver campos sensíveis: confirmar que o tratamento (mascaramento) está aplicado antes de expor.
+
+### 2.3 — SLA de atualização
+
+Definir com base no pipeline que alimenta a tabela:
+
+| Campo | Definição |
+|-------|----------|
+| Frequência | Frequência de execução do pipeline |
+| SLA de disponibilidade | Quando os dados do dia D estarão disponíveis |
+| Janela de reprocessamento | Período coberto em caso de reprocessamento (ex: últimos 7 dias) |
+
+> SLA é definido por pipeline — não há SLA global. Consultar doc do pipeline.
+
+### 2.4 — Acesso
+
+Definir como a squad vai consumir os dados:
+
+| Método | Quando usar |
+|--------|------------|
+| Query direta (Athena ou equivalente) | Análises ad-hoc, engenharia |
+| Dashboard (Metabase ou equivalente) | Visualização de negócio |
+| Acesso IAM | Quando a squad precisar de acesso programático |
+
+> Acesso é solicitado via canal de dados + card no board do time de Data.
+
+---
+
+## Fase 3 — Qualidade garantida
+
+Documentar na seção **Qualidade Garantida** do contrato os checks ativos na Expectation Suite:
+
+- Volume mínimo
+- Nulos e unicidade de chave primária
+- Checks de negócio específicos para esta tabela
+
+> A squad consumidora deve ser informada sobre o que está garantido — e o que **não** está.
+
+---
+
+## Fase 4 — Publicação e comunicação
+
+### 4.1 — Salvar contrato
+
+Salvar o contrato preenchido em:
+```
+{REPO_DATA}/contracts/{nome_contrato}.md
+```
+
+> `{REPO_DATA}` = repositório de scripts de pipeline definido nas rules.
+
+### 4.2 — Comunicar à squad requisitante
+
+Notificar no canal de solicitação de dados (thread original) com:
+- Link para o contrato
+- Como acessar os dados (método, IAM role ou equivalente)
+- SLA combinado
+- Contato do owner para dúvidas
+
+### 4.3 — Abrir card no board do time de Data
+
+Criar card no board `DE` (ou equivalente) com:
+- Squad requisitante
+- Tabela/recurso
+- Status: `Ativo`
+- Link para o contrato
+
+---
+
+## Fase 5 — Ciclo de vida do contrato
+
+### Alteração de schema
+
+Qualquer mudança de schema (adição, remoção ou tipo de campo) deve:
+
+1. Ser comunicada no canal de dados com **antecedência** (prazo definido nas rules)
+2. Gerar nova versão do contrato (versionamento semântico: `MAJOR.MINOR`)
+3. Manter versão antiga disponível pelo período de coexistência definido nas rules
+
+### Deprecação
+
+Quando o contrato não for mais necessário:
+1. Atualizar `Status` para `Deprecado` no documento
+2. Comunicar à squad requisitante com prazo de encerramento
+3. Atualizar (ou remover) o card no board do time de Data
+
+---
+
+## Checklist final
+
+```
+[ ] Solicitação formal registrada no canal de dados
+[ ] Pipeline alimentador existe e está documentado
+[ ] Tabela gold populada e com Expectation Suite ativa
+[ ] Contrato preenchido (schema, SLA, acesso, campos sensíveis)
+[ ] Campos sensíveis com tratamento aplicado (ou ausência confirmada)
+[ ] Contrato salvo no repositório de pipelines
+[ ] Squad requisitante notificada com acesso e SLA
+[ ] Card aberto no board do time de Data
+```