jarvis-ai-framework 2.0.0 → 2.1.0

package/skills/jarvis-evolution-architect/references/exemplos.md

@@ -0,0 +1,297 @@
+# Exemplos - Jarvis Evolution Architect
+
+## 📌 Exemplo 1: Nova Feature - Spec Reviewer Agent
+
+**Pergunta:**
+> "Estou pensando em criar um novo agent chamado Spec Reviewer. Ele analisaria se as especificações estão completas. O que você acha?"
+
+### Resposta Estruturada
+
+**Minha Leitura:**
+Você quer adicionar uma etapa de validação de specs depois que são criadas, possivelmente como um novo agent independente.
+
+**O Que Eu Acho:**
+Não criaria um novo agent ainda. A pergunta certa é: "Esse reviewer precisa realmente de identidade própria?"
+
+**O Que Eu Mudaria:**
+Começaria como uma **etapa de workflow** no workflow de spec atual. Se depois perceber que o reviewer tem:
+- Comportamento próprio (não apenas validação)
+- Contexto especializado (diferente da spec)
+- Ciclo de vida independente
+
+...aí extraio para um agent.
+
+**O Que Eu Não Faria:**
+- Não criaria um agent novo só porque "reviewar" é uma responsabilidade
+- Não adicionaria complexidade arquitetural sem estar 100% certo
+
+**Como Eu Faria:**
+```
+1. Criar uma skill "eng-spec-review" que valida critérios de completude
+2. Integrar como etapa do workflow "spec-validation" 
+3. Monitorar padrões de uso por 2-3 ciclos
+4. Se ver que vai além de validação → extrair para agent
+```
+
+**Trade-Offs:**
+- ✅ Menor complexidade inicial
+- ✅ Mais fácil iterar
+- ❌ Se precisar depois, refatorar será um pouco mais custoso
+
+**Minha Recomendação:**
+Comece com skill + workflow. Agent pode esperar.
+
+---
+
+## 📌 Exemplo 2: Nova Funcionalidade - Context Optimizer
+
+**Pergunta:**
+> "Sinto que os agentes estão recebendo muita informação desnecessária. Deveria criar um Context Optimizer skill?"
+
+### Resposta Estruturada
+
+**Minha Leitura:**
+Contexto em excesso está prejudicando qualidade das decisões dos agentes. Você quer uma forma de otimizar isso.
+
+**O Que Eu Acho:**
+Problema real. Mas a solução não é uma nova skill, é uma **regra arquitetural sobre CDD** (Context-Driven Development).
+
+**O Que Eu Mudaria:**
+Em vez de skill:
+1. Criar uma **Rule** que define "Minimal Context Principle"
+2. Documentar em `lentes-e-conceitos.md` quando usar contexto e quando não
+3. Adicionar checklist na skill de spec para "contextos mínimos necessários"
+
+**Como Eu Faria:**
+```
+rules/cdd/
+├── minimal-context-principle.md
+└── context-validation-checklist.md
+
+skills/
+├── ...
+└── eng-spec-review/
+    └── checklists/
+        └── context-needs.md
+```
+
+**Trade-Offs:**
+- ✅ Educativo (desenvolvedores entendem a razão)
+- ✅ Sistêmico (afeta todas as skills)
+- ❌ Requer disciplina
+
+**Minha Recomendação:**
+Trata como um problema arquitetural, não uma feature nova.
+
+---
+
+## 📌 Exemplo 3: Tecnologia Nova - MCP Integration
+
+**Pergunta:**
+> "MCP (Model Context Protocol) saiu novo. Devemos integrar ao Jarvis?"
+
+### Resposta Estruturada
+
+**Minha Leitura:**
+MCP é um protocolo novo da Anthropic para contexto estruturado. Você quer saber se relevante pro Jarvis.
+
+**O Que Eu Acho:**
+Potencialmente muito relevante. Mas precisa de pesquisa antes de decidir.
+
+**Pesquisa (você faz isso):**
+- Documentação oficial do MCP
+- Casos de uso em AI frameworks
+- Comparação com abordagem atual do Jarvis
+- Complexidade de integração
+
+**Avaliação de Tendência:**
+```
+Tendência: MCP Protocol
+↓
+Problema que resolve: 
+  - Contexto estruturado entre agentes
+  - Compartilhamento de recursos entre ferramentas
+  - Padrão de interoperabilidade
+↓
+Relevância para Jarvis:
+  - ALTA (contexto é core do Jarvis)
+↓
+Benefício:
+  - Agentes compartilham recursos nativamente
+  - Interop com outras ferramentas
+  - Menos duplicação de informação
+↓
+Complexidade:
+  - Média (já existe, mas precisa integração)
+↓
+Trade-off:
+  - Ganhamos: interop + padrão aberto
+  - Perdemos: abstração a mais, curva aprendizado
+↓
+Decisão: EXPERIMENT
+```
+
+**Minha Recomendação:**
+Criar um projeto piloto integrando MCP com um agent existente. Validar complexidade real antes de decisão arquitetural.
+
+---
+
+## 📌 Exemplo 4: Simplificação - Muitas Skills?
+
+**Pergunta:**
+> "Temos 50+ skills. Está difícil achar qual skill usar. Deveria consolidar?"
+
+### Resposta Estruturada
+
+**Minha Leitura:**
+Discoverability é problema. Muitas skills, sem navegação clara.
+
+**O Que Eu Acho:**
+Consolidar skills **não é a resposta**. Problema é **organização e documentação**, não quantidade.
+
+**O Que Eu Mudaria:**
+1. Criar um **INDEX.md** principal que agrupa skills por contexto
+2. Adicionar tags em metadatas das skills
+3. Criar uma skill `/jarvis-find-skill` que busca
+4. Melhorar `metadata.area` e `metadata.tags`
+
+**O Que Eu Não Faria:**
+- Não consolidaria skills de responsabilidades diferentes
+- Não criaria mega-skills com 10 opções
+
+**Como Eu Faria:**
+```
+skills/
+├── INDEX.md (mapa visual de skills por contexto)
+├── eng-* (10 skills de engenharia)
+├── qa-* (8 skills de QA)
+├── prod-* (6 skills de produto)
+└── ...
+
+INDEX.md:
+## Engineering Skills
+Tarefas comuns:
+- `/eng.start` → planeja feature
+- `/eng.work` → implementa
+- `/eng.test` → testa
+- ...
+```
+
+**Trade-Offs:**
+- ✅ Mantém responsabilidades separadas
+- ✅ Fácil estender com novas skills
+- ❌ Precisa documentação ativa
+
+**Minha Recomendação:**
+Skills estão OK. Melhore discovery com INDEX e tags.
+
+---
+
+## 📌 Exemplo 5: Arquitetura - Agents vs Workflows
+
+**Pergunta:**
+> "Qual a diferença entre um agent e um workflow? Quando usar cada um?"
+
+### Resposta Estruturada
+
+**Minha Leitura:**
+Confusão sobre quando criar um novo agente vs uma sequência de workflow.
+
+**O Que Eu Acho:**
+Diferença fundamental:
+- **Agent**: Identidade, contexto, autonomia
+- **Workflow**: Orquestração, sequência, decisões
+
+**Quando Criar um Agent:**
+```
+❌ Pode ser workflow se:
+  - É apenas uma sequência de etapas
+  - Não tem contexto especializado
+  - Não toma decisões independentes
+
+✅ Cria um agent se:
+  - Tem identidade própria (Role bem-definida)
+  - Contexto especializado (informação específica)
+  - Autonomia (toma decisões sozinho)
+  - Ciclo de vida próprio (pode rodar repetidamente)
+```
+
+**Exemplo - Spec Reviewer:**
+```
+Se é apenas: validar lista de critérios
+→ Workflow (sequência de checks)
+
+Se é: entender intent da spec + sugerir melhorias
+→ Agent (tem opinião, expertise, contexto)
+```
+
+**Minha Recomendação:**
+Default para workflow. Extrai para agent só se notar padrões de autonomia e expertise.
+
+---
+
+## 💬 Padrão de Conversa - Sua Entrada
+
+Quando você invoca a skill:
+
+```
+/jarvis-evolution-architect "Estou achando a arquitetura do Jarvis complexa. O que eu deveria remover?"
+```
+
+### Fluxo esperado:
+
+1. **Eu questiono** 
+   - "Qual aspecto está complexo?"
+   - "Como isso afeta desenvolvedores?"
+   - "Afeta agentes de IA ou código?"
+
+2. **Eu analiso**
+   - Vejo estado atual
+   - Comparo com preferência evolutiva
+   - Avalio trade-offs
+
+3. **Eu recomendo**
+   - Com opinião
+   - Com justificativa
+   - Com próximos passos
+
+---
+
+## 🎯 Entrada Típica vs Resposta Inesperada
+
+### ❌ Não fazer isso:
+```
+"Qual skill devo usar para X?"
+```
+❌ Isso não é pergunta arquitetural. Use `/jarvis-find-skill` em vez disso.
+
+### ✅ Fazer isso:
+```
+"Acho que deveria criar uma nova skill para X. Essa skill faria Y. O que você acha? Deveria ser uma skill ou algo diferente?"
+```
+✅ Questão arquitetural legítima.
+
+### ✅ Fazer isso:
+```
+"Estou indeciso entre duas formas de resolver X. Uma é com um novo agent, outra é estender o workflow existente. Como você abordaria?"
+```
+✅ Questão de design com trade-offs.
+
+---
+
+## 📊 Matriz de Quando Usar Evolution Architect
+
+| Situação | Use Evolution Architect |
+|----------|----------------------|
+| "Devo criar um novo agent?" | ✅ SIM |
+| "Essa feature deveria ser skill ou workflow?" | ✅ SIM |
+| "Acho que essa feature está complexa demais" | ✅ SIM |
+| "Qual skill usa para X?" | ❌ NÃO (use `/jarvis-find-skill`) |
+| "Como implement feature X?" | ❌ NÃO (use skill específica) |
+| "Devemos adotar X tendência?" | ✅ SIM |
+| "Qual a diferença entre SDD e CDD?" | ✅ SIM |
+| "Como faço para debugar skill X?" | ❌ NÃO (use skill específica) |
+
+---
+
+**Última atualização**: 2026-10-04

package/skills/jarvis-evolution-architect/references/guia-de-uso.md

@@ -0,0 +1,355 @@
+# Guia - Jarvis Evolution Architect
+
+## 🚀 Como Usar
+
+### Instalação
+
+O skill vem com o framework. Sincronize a pasta da IDE (`$IDE/skills/`):
+
+```bash
+jarvis init --ide claude --force   # ou a sua IDE (cursor, windsurf, ...)
+```
+
+### Invocação
+
+No chat da sua IDE (Claude, Cursor, Windsurf, etc):
+
+```
+/jarvis-evolution-architect "Sua pergunta ou situação arquitetural aqui"
+```
+
+### Exemplos de Invocação
+
+```
+/jarvis-evolution-architect "Deveria criar um novo agent para isso?"
+
+/jarvis-evolution-architect "Acho que essa feature está muito complexa. Como simplificaria?"
+
+/jarvis-evolution-architect "Pesquise como outros frameworks resolvem contexto"
+
+/jarvis-evolution-architect "Qual a diferença entre criar skill vs rule?"
+```
+
+---
+
+## 📋 O Que a Skill Faz
+
+### Analisa
+- ✅ Decisões arquiteturais
+- ✅ Propostas de novos agentes/skills/workflows
+- ✅ Complexidade arquitetural
+- ✅ Tendências em AI-native development
+
+### Questiona
+- ✅ Antes de concordar com proposta
+- ✅ Intenção real do problema
+- ✅ Se existe solução existente
+- ✅ Trade-offs envolvidos
+
+### Pesquisa
+- ✅ Tendências atuais
+- ✅ Práticas recentes
+- ✅ Comportamento de ferramentas
+- ✅ Comparação com outros frameworks
+
+### Recomenda
+- ✅ Com opinião técnica forte
+- ✅ Com justificativa
+- ✅ Com próximos passos
+- ✅ Sendo direto sobre discordâncias
+
+---
+
+## 🎯 Lentes de Análise
+
+A skill usa **4 lentes** para avaliar decisões:
+
+### 1️⃣ SDD (Spec-Driven Development)
+Questiona a intenção, requisitos, comportamento esperado:
+
+```
+"Qual é realmente o problema que você está tentando resolver?"
+"Quais são os critérios de aceitação?"
+"Como vai saber que está pronto?"
+```
+
+### 2️⃣ CDD (Context-Driven Development)
+Avalia como informação flui entre artefatos:
+
+```
+"Que contexto o novo agent precisa?"
+"Quando ele precisa dessa informação?"
+"Existe duplicação?"
+```
+
+### 3️⃣ Agentic Software Engineering
+Pensa em como agentes de IA entendem e usam:
+
+```
+"Isso ajuda o agente a entender melhor?"
+"Tomar melhores decisões?"
+"Ser mais autônomo com segurança?"
+```
+
+### 4️⃣ Developer Experience
+Considera facilidade de uso:
+
+```
+"É fácil de entender?"
+"É fácil de manter?"
+"É fácil de debugar?"
+```
+
+---
+
+## 📊 Estrutura Típica de Resposta
+
+Quando você faz uma pergunta, a skill responde assim:
+
+### 1. Minha Leitura
+*"O que eu entendi do seu problema"*
+
+```
+Você quer adicionar uma etapa de validação de specs depois 
+que são criadas, possivelmente como um novo agent.
+```
+
+### 2. O Que Eu Acho
+*"Minha avaliação técnica direta"*
+
+```
+Não criaria um novo agent ainda. A pergunta certa é: 
+"Esse reviewer precisa realmente de identidade própria?"
+```
+
+### 3. O Que Eu Mudaria
+*"Melhorias à proposta"*
+
+```
+Começaria como uma etapa de workflow, não agent.
+```
+
+### 4. O Que Eu Não Faria
+*"O que considero problemático"*
+
+```
+Não criaria agent só porque "reviewar" é responsabilidade.
+```
+
+### 5. Como Eu Faria
+*"Proposta arquitetural alternativa"*
+
+```
+1. Criar skill "eng-spec-review"
+2. Integrar como workflow
+3. Monitorar padrões
+4. Extrait para agent depois se necessário
+```
+
+### 6. Trade-Offs
+*"O que ganhamos e perdemos"*
+
+```
+✅ Menor complexidade inicial
+❌ Refatoração pode ser custosa depois
+```
+
+### 7. Minha Recomendação
+*"Decisão clara e opinativa"*
+
+```
+Comece com skill + workflow. Agent pode esperar.
+```
+
+---
+
+## 🔄 Preferência Evolutiva
+
+A skill sempre questiona: **"Por que criar novo?"**
+
+A ordem de preferência é:
+
+```
+1. REUSE - Usar artefato existente como está
+   ✅ Se resolve 100% do problema
+
+2. EXTEND - Estender artefato existente
+   ✅ Se reuse não resolve
+   
+3. REFACTOR - Reorganizar artefato existente
+   ✅ Se extend adiciona muita complexidade
+   
+4. CREATE - Criar novo artefato
+   ⚠️ Última opção, sempre justifique
+```
+
+---
+
+## 🏗️ Classificação de Artefatos
+
+A skill ajuda a classificar o que você está pensando criar:
+
+| Tipo | Use quando... |
+|------|---------------|
+| **Agent** | Identidade própria + contexto especializado + autonomia |
+| **Skill** | Playbook executável, reutilizável, acionável |
+| **Workflow** | Sequência de etapas coordenadas |
+| **Rule** | Diretriz, constraint, gate, convenção |
+| **Template** | Modelo de documento reutilizável |
+| **Specification** | Requisitos estruturados com rastreabilidade |
+| **Context** | Informação usada por múltiplos artefatos |
+
+**Regra importante**: Não escolha pelo nome. Analise a responsabilidade.
+
+---
+
+## 🛡️ Proteção do Jarvis
+
+A skill **questiona** essas situações:
+
+- 🚫 Overengineering
+- 🚫 Abstrações desnecessárias
+- 🚫 Duplicação
+- 🚫 Excesso de configuração
+- 🚫 Excesso de contexto
+- 🚫 Excesso de agentes
+- 🚫 Workflows desnecessariamente complexos
+- 🚫 Regras conflitantes
+- 🚫 Fragmentação excessiva
+
+---
+
+## 📚 Quando Usar Evolution Architect
+
+### ✅ USE:
+
+```
+"Deveria criar um novo agent para X?"
+"Essa feature deveria ser skill ou workflow?"
+"Acho essa solução muito complexa, como simplificaria?"
+"Qual é realmente o problema aqui?"
+"Devemos adotar essa tendência?"
+"Qual a diferença entre SDD e CDD na prática?"
+"Pesquise como o MCP funciona e se relevante pro Jarvis"
+```
+
+### ❌ NÃO USE:
+
+```
+"Qual skill devo usar para X?" (use /jarvis-find-skill)
+"Como implemento feature X?" (use skill específica)
+"Como debugo essa skill?" (use documentação ou skill específica)
+"Como faço um pull request?" (use fluxo de engenharia)
+```
+
+---
+
+## 🔍 Pesquisa - Quando a Skill Pesquisa
+
+A skill pode **pesquisar a web** quando necessário:
+
+### Pesquisa quando:
+```
+✅ Tendências em AI-native development
+✅ Novas capacidades de ferramentas (Claude Code, Cursor)
+✅ Comparação com outros frameworks
+✅ Documentação oficial de tecnologia
+✅ Práticas recentes
+```
+
+### Não pesquisa quando:
+```
+❌ Conhecimento consolidado (arquitetura, princípios)
+❌ Práticas bem-estabelecidas (SOLID, TDD, etc)
+❌ Jarvis Framework (conhecimento interno)
+```
+
+---
+
+## 💬 Passo a Passo - Típica Conversa
+
+### Você entra com:
+```
+/jarvis-evolution-architect "Vou criar um novo agent 
+chamado PR Reviewer que valida qualidade de PRs. 
+O que você acha?"
+```
+
+### Skill responde:
+
+1. **Questiona**
+   - "Qual é realmente o critério de qualidade?"
+   - "O agent toma decisões ou apenas reporta?"
+   - "Isso não deveria ser parte do workflow existente?"
+
+2. **Analisa** (internamente)
+   - Verifica se existe fluxo de PR existente
+   - Avalia se é agente ou etapa de workflow
+   - Pensa em contexto necessário
+
+3. **Recomenda**
+   - Opinião: não criaria agente novo
+   - Alternativa: estender skill existente
+   - Próximos passos: começar com rule + skill
+
+---
+
+## 🚀 Dica: Faça Boas Perguntas
+
+A qualidade da resposta depende da qualidade da pergunta.
+
+### ❌ Pergunta fraca:
+```
+"Como criar um novo agent?"
+```
+
+### ✅ Pergunta forte:
+```
+"Vou criar um agent que valida PRs quanto a qualidade. 
+Esse agent analisaria código, complexity, coverage, 
+style. O que você acha? Deveria ser agent ou algo diferente?"
+```
+
+---
+
+## 🎓 Conceitos Chave
+
+### SDD (Spec-Driven Development)
+- Começa com intenção clara
+- Define requisitos antes de solução
+- Rastreia relação spec → implementação
+
+### CDD (Context-Driven Development)
+- Contexto certo no lugar certo
+- No momento certo
+- Mínimo ruído, sem duplicação
+
+### Agentic Software Engineering
+- Decisões que beneficiam agentes
+- Contexto que facilita entendimento
+- Autonomia com segurança
+
+---
+
+## 📞 Suporte
+
+Se a skill não responder bem:
+
+1. **Reformule sua pergunta** - Seja mais específico
+2. **Forneça contexto** - Explique o problema
+3. **Cite restrições** - Quais são limitações?
+4. **Dê exemplos** - Mostre o que você pensa em criar
+
+---
+
+## 🔗 Referências Internas
+
+- **SKILL.md** - Definição técnica da skill
+- **lentes-e-conceitos.md** - Documentação detalhada das lentes
+- **exemplos.md** - Exemplos de conversas reais
+
+---
+
+**Última atualização**: 2026-10-04  
+**Versão**: 1.0  
+**Framework**: Jarvis 2.0+