jarvis-ai-framework 1.0.0

package/skills/init-jarvis/assets/setup-guide.md

@@ -0,0 +1,360 @@
+ Guia de Setup do Ambiente
+
+> Este guia detalha a configuração completa do ambiente de desenvolvimento.
+
+ Pré-requisitos
+
+ Software Necessário
+
+| Software | Versão Mínima | Verificar |
+|----------|---------------|-----------|
+| Node.js | .x | `node --version` |
+| NPM | .x | `npm --version` |
+| Git | .x | `git --version` |
+| Docker | .x | `docker --version` |
+| IDE (Windsurf/Cursor/Claude/VS Code) | Última | - |
+
+ Instalação (macOS)
+
+```bash
+ Homebrew (se não tiver)
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+ Node.js via NVM (recomendado)
+brew install nvm
+nvm install 
+nvm use 
+
+ Git
+brew install git
+
+ Docker Desktop
+brew install --cask docker
+```
+
+ Instalação (Linux/Ubuntu)
+
+```bash
+ Node.js via NVM
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v../install.sh | bash
+nvm install 
+nvm use 
+
+ Git
+sudo apt update && sudo apt install git
+
+ Docker
+sudo apt install docker.io docker-compose
+sudo usermod -aG docker $USER
+```
+
+ Configuração do Workspace
+
+ . Clonar o workspace
+
+O Jarvis fica na pasta **workspace**, não dentro de um repo.
+
+```bash
+mkdir -p {WORKSPACE} && cd {WORKSPACE}
+
+# single: um único git nesta pasta
+# git clone git@host:org/repo.git .
+
+# multi: um git por subpasta
+# git clone git@host:org/repo-api.git repo-api
+# git clone git@host:org/repo-frontend.git repo-frontend
+```
+
+ . Instalar Dependências
+
+```bash
+npm install
+```
+
+ . Configurar Variáveis de Ambiente
+
+```bash
+ Copiar arquivo de exemplo
+cp .env.example .env
+
+ Editar com suas credenciais
+code .env
+```
+
+Variáveis obrigatórias:
+
+```env
+ Banco de Dados
+DATABASE_URL=mysql://user:password@localhost:/dbname
+
+ APIs Externas
+API_KEY=sua_chave_aqui
+
+ Ambiente
+NODE_ENV=development
+```
+
+ . Configurar Banco de Dados
+
+```bash
+ Subir containers (se usar Docker)
+docker-compose up -d
+
+ Rodar migrations
+npm run migrate
+
+ Seed de dados (opcional)
+npm run seed
+```
+
+ . Rodar Projeto
+
+```bash
+ Desenvolvimento
+npm run dev
+
+ Testes
+npm test
+
+ Build
+npm run build
+```
+
+ Configuração da IDE
+
+ Detectar IDE em Uso
+
+PRIMEIRO: Identifique qual IDE você está utilizando para configurar os caminhos corretos.
+
+```bash
+ Detectar IDE pela pasta existente no projeto
+if [ -d ".windsurf" ]; then
+  echo "IDE: Windsurf"
+  echo "Pasta: .windsurf/"
+  echo "MCP Config: ~/.codeium/windsurf/mcp_config.json"
+elif [ -d ".cursor" ]; then
+  echo "IDE: Cursor"
+  echo "Pasta: .cursor/"
+  echo "MCP Config: ~/.cursor/mcp.json"
+elif [ -d ".claude" ]; then
+  echo "IDE: Claude"
+  echo "Pasta: .claude/"
+  echo "MCP Config: ~/.claude/mcp_config.json"
+elif [ -d ".codex" ]; then
+  echo "IDE: Codex (OpenAI)"
+  echo "Pasta: .codex/"
+elif [ -d ".opencode" ]; then
+  echo "IDE: OpenCode"
+  echo "Pasta: .opencode/"
+elif [ -d ".gemini" ]; then
+  echo "IDE: Gemini CLI / Antigravity"
+  echo "Pasta: .gemini/"
+fi
+```
+
+ Tabela de Caminhos por IDE
+
+| IDE | Pasta do Projeto | Arquivo MCP Config |
+|-----|------------------|--------------------||
+| Windsurf | `.windsurf/` | `~/.codeium/windsurf/mcp_config.json` |
+| Claude Code | `.claude/` | `~/.claude/mcp_config.json` |
+| Cursor | `.cursor/` | `~/.cursor/mcp.json` |
+| Codex (OpenAI) | `.codex/` | - |
+| OpenCode | `.opencode/` | - |
+| Gemini CLI / Antigravity | `.gemini/` | - |
+
+ Windsurf / Claude Code / Cursor / Codex / OpenCode / Gemini
+
+Extensões recomendadas:
+
+- ESLint
+- Prettier
+- GitLens
+- Docker
+- Thunder Client (API testing)
+
+Settings recomendadas:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  }
+}
+```
+
+ Configurar Framework JARVIS
+
+```bash
+ Inicializar framework
+ No chat da sua IDE (Windsurf/Cursor/Claude), digite:
+/init
+```
+
+ Configuração de MCPs (Model Context Protocol)
+
+OBRIGATÓRIO: O framework JARVIS depende de MCPs para funcionalidades avançadas.
+
+ Localização do Arquivo de Configuração (por IDE)
+
+```bash
+ Windsurf
+cat ~/.codeium/windsurf/mcp_config.json >/dev/null || echo "Não encontrado"
+
+ Cursor
+cat ~/.cursor/mcp.json >/dev/null || echo "Não encontrado"
+
+ Claude
+cat ~/.claude/mcp_config.json >/dev/null || echo "Não encontrado"
+```
+
+| IDE | Caminho do Arquivo MCP |
+|-----|------------------------|
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Claude | `~/.claude/mcp_config.json` |
+
+ MCPs
+
+| MCP | Propósito | Documentação |
+|-----|-----------|-------------|
+| Context7 | Documentação atualizada de bibliotecas (**obrigatório**) | [context7.com](https://context7.com) |
+| Task manager | Só se `TASK_MANAGER` estiver no ENV (Jira/Linear/…) | conforme o vendor |
+| TestSprite | Geração automática de testes (opcional) | [testsprite.com](https://testsprite.com) |
+
+ Instalar Context
+
+Adicionar ao arquivo MCP da sua IDE (veja tabela acima):
+
+```json
+{
+  "mcpServers": {
+    "context": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context-mcp"]
+    }
+  }
+}
+```
+
+Testar instalação (no chat da sua IDE):
+```
+Use Context para buscar documentação do React hooks
+```
+
+ Instalar TestSprite
+
+Adicionar ao arquivo MCP da sua IDE:
+
+```json
+{
+  "mcpServers": {
+    "context": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context-mcp"]
+    },
+    "testsprite": {
+      "command": "npx",
+      "args": ["-y", "@testsprite/mcp-server"]
+    }
+  }
+}
+```
+
+Testar instalação (no chat da sua IDE):
+```
+Use TestSprite para analisar cobertura de testes do projeto
+```
+
+ Após Configurar MCPs
+
+. Salvar o arquivo de configuração MCP
+. Reiniciar a IDE completamente (Cmd+Q / fechar e abrir)
+. Verificar se os MCPs aparecem no painel de ferramentas
+
+ Problemas Comuns com MCPs
+
+MCP não aparece após reiniciar:
+```bash
+ Verificar se npx está funcionando
+npx --version
+
+ Limpar cache do npx
+npx clear-npx-cache
+```
+
+Erro de permissão:
+```bash
+ Dar permissão ao diretório (ajustar caminho conforme IDE)
+chmod  ~/.codeium/windsurf/    Windsurf
+chmod  ~/.cursor/              Cursor
+chmod  ~/.claude/              Claude
+```
+
+JSON inválido:
+```bash
+ Validar JSON (ajustar caminho conforme IDE)
+cat ~/.codeium/windsurf/mcp_config.json | python -m json.tool   Windsurf
+cat ~/.cursor/mcp.json | python -m json.tool                    Cursor
+cat ~/.claude/mcp_config.json | python -m json.tool             Claude
+```
+
+ Verificação Final
+
+Execute o checklist:
+
+- [ ] `node --version` retorna .x+
+- [ ] `npm --version` retorna .x+
+- [ ] `git --version` retorna .x+
+- [ ] Projeto clonado com sucesso
+- [ ] `npm install` sem erros
+- [ ] `.env` configurado
+- [ ] `npm run dev` inicia sem erros
+- [ ] `npm test` passa todos os testes
+- [ ] Framework JARVIS inicializado (`/init-jarvis`)
+- [ ] IDE detectada corretamente (Windsurf/Cursor/Claude/VS Code)
+- [ ] MCP Context7 instalado e respondendo (**obrigatório**)
+- [ ] MCP de task manager só se `TASK_MANAGER` estiver no ENV (não bloqueia)
+- [ ] IDE reiniciada após configurar MCPs (se configurou)
+
+ Problemas Comuns
+
+ Erro de permissão no npm
+
+```bash
+sudo chown -R $(whoami) ~/.npm
+```
+
+ Porta já em uso
+
+```bash
+ Encontrar processo
+lsof -i :
+
+ Matar processo
+kill - {PID}
+```
+
+ Docker não inicia
+
+```bash
+ Reiniciar Docker
+sudo systemctl restart docker
+
+ Verificar status
+docker ps
+```
+
+ Próximos Passos
+
+Após setup completo:
+
+. Ler o `README.md` para entender o projeto
+. Ler o `AGENTS.md` para instruções de agentes de IA
+. Verificar acessos em `CONTACTS.md` (raiz do projeto)
+. Pegar primeira tarefa (task manager ou controle próprio se freelance)
+. Usar `/eng.start {TASK_MANAGER_KEY}` para começar
+
+> Fonte da verdade: README.md e AGENTS.md na raiz do projeto contêm a visão geral da arquitetura.

package/skills/lovable-prompt-generator/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: lovable-prompt-generator
+description: >
+  Especialista em gerar prompts estruturados e completos para o Lovable criar frontends React
+  prontos para produção, analisando documentação técnica e de negócio do projeto.
+  Trigger: Use quando alguém pedir para gerar prompts para o Lovable, criar frontend via Lovable,
+  ou precisar de um prompt estruturado para geração de interface React com o Lovable.
+license: AGPL-3.0
+compatibility: Designed for Claude Code (or similar products)
+allowed-tools: Read Glob Grep
+metadata:
+  author: jarvis-team
+  version: "1.0"
+argument-hint: "[contexto-ou-feature]"
+disable-model-invocation: false
+---
+
+# Lovable Prompt Generator - Gerador de Prompts para Frontend
+
+Você é um **especialista em arquitetura frontend React e na plataforma Lovable**, focado em analisar documentação do projeto e gerar prompts estruturados que permitem ao Lovable criar interfaces prontas para produção.
+
+## Objetivo
+
+Analisar toda a documentação disponível do projeto (negócio, técnica e produto) e produzir um prompt completo, detalhado e autocontido que o Lovable possa usar para gerar um frontend React funcional — com mock data realista, navegação completa e pronto para substituição por chamadas reais de API.
+
+## Entrada
+
+- `$ARGUMENTS` - Contexto ou feature a priorizar (ex: `dashboard`, `módulo de veículos`). Se vazio, gerar prompt para o frontend completo.
+
+## Recursos
+
+- **Contexto de negócio**: `docs/business-context/`
+- **Contexto técnico**: `docs/technical-context/`
+- **Master docs**: `docs/master-docs/`
+- **Templates Lovable**: `$IDE/templates/lovable/` (se existir)
+
+---
+
+## Pré-requisito
+
+Verificar se a documentação base existe antes de executar:
+
+```bash
+ls docs/ 2>/dev/null || echo "⚠️ Pasta docs/ não encontrada"
+```
+
+> Se não houver documentação disponível, solicitar ao usuário os contextos mínimos necessários antes de prosseguir.
+
+---
+
+## Quando Usar
+
+Use este skill quando:
+- O usuário pedir para gerar um prompt para o Lovable
+- O backend estiver pronto e precisar criar o frontend com Lovable
+- Precisar de um prompt estruturado para uma tela ou módulo específico do Lovable
+- Quiser criar uma UI navegável com mock data para validação com stakeholders
+
+**NÃO usar quando:**
+- A tarefa for implementar o frontend diretamente no código do projeto (use `eng.work`)
+- Não envolver a plataforma Lovable
+- For apenas uma dúvida de design ou UX (sem geração de prompt)
+
+---
+
+## Padrões Críticos
+
+### Padrão 1: Ler toda a documentação disponível antes de gerar o prompt
+
+Nunca gerar o prompt sem antes extrair de cada documento disponível:
+- Tipos de usuário, permissões e RBAC
+- Fluxos completos de usuário e jornadas
+- Endpoints de API, métodos, payloads e estruturas de resposta
+- Regras de negócio e requisitos de validação
+- Preferências de design e diretrizes de marca
+
+```bash
+# Verificar documentação disponível
+ls docs/business-context/ 2>/dev/null
+ls docs/technical-context/ 2>/dev/null
+ls docs/master-docs/ 2>/dev/null
+```
+
+### Padrão 2: Mock data deve espelhar formatos reais de API
+
+O mock data deve ser estruturado para permitir substituição fácil por chamadas reais:
+- Usar os mesmos nomes de campos que a API real
+- Incluir todos os estados de dados (vazio, carregando, erro, cheio)
+- Cobrir edge cases (sem permissão, sem dados, mais de 100 itens)
+- Usar dados realistas, não genéricos (`"João Silva"`, não `"user1"`)
+
+### Padrão 3: O prompt gerado deve ser autocontido
+
+O Lovable não terá acesso aos documentos do projeto. O prompt deve incluir:
+- Todo contexto necessário embutido
+- Especificações completas sem depender de referências externas
+- Descrição suficiente para que o Lovable não precise pedir clarificações
+
+---
+
+## Árvore de Decisão
+
+```
+$ARGUMENTS preenchido?        → Gerar prompt focado no módulo/feature informado
+$ARGUMENTS vazio?             → Gerar prompt para o frontend completo
+Documentação docs/ existe?    → Ler e extrair contexto antes de gerar
+Documentação docs/ ausente?   → Solicitar contexto mínimo ao usuário antes de prosseguir
+Tem API_SPECIFICATION.md?     → Incluir endpoints e contratos na seção técnica
+Não tem API_SPECIFICATION?    → Solicitar endpoints ao usuário ou usar mocks genéricos
+```
+
+---
+
+## Fluxo de Trabalho
+
+### 1. Análise de Documentação
+
+Ler sequencialmente os arquivos disponíveis:
+
+**Contexto de Negócio** (`docs/business-context/`):
+- `CUSTOMER_PERSONAS.md` — Perfis de usuário e características
+- `CUSTOMER_JOURNEY.md` — Fluxos e pontos de contato
+- `PRODUCT_STRATEGY.md` — Visão e objetivos do produto
+- `FEATURE_CATALOG.md` — Features disponíveis
+- `VOICE_OF_CUSTOMER.md` — Feedback e dores dos usuários
+
+**Contexto Técnico** (`docs/technical-context/`):
+- `API_SPECIFICATION.md` — Endpoints, métodos, payloads, respostas
+- `BUSINESS_LOGIC.md` — Regras de negócio centrais
+- `CODEBASE_GUIDE.md` — Visão geral da arquitetura técnica
+- `CONTRIBUTING.md` — Padrões de desenvolvimento
+
+**Master Docs** (`docs/master-docs/`):
+- `project-prd.md` — Requisitos completos do produto
+- `architectural-principles.md` — Regras arquiteturais não negociáveis
+- `coding-standards.md` — Convenções de código
+- `security-requirements.md` — Requisitos de segurança
+
+### 2. Planejamento da Arquitetura de Componentes
+
+Definir hierarquia seguindo Atomic Design:
+- **Átomos**: elementos básicos (botões, inputs, ícones, tipografia)
+- **Moléculas**: combinações simples (barras de busca, campos de formulário)
+- **Organismos**: seções complexas (headers, formulários, tabelas de dados)
+- **Templates**: layouts e estruturas de página
+- **Páginas**: interfaces completas com conteúdo real
+
+### 3. Geração do Prompt Estruturado
+
+Produzir o prompt com as seguintes seções obrigatórias:
+
+---
+
+**Seção 1 — Visão Geral do Projeto**
+```
+- Descrição breve do propósito da aplicação
+- Usuários-alvo e casos de uso principais
+- Stack técnica: React + TypeScript + Tailwind CSS
+- Arquitetura de componentes (atomic design)
+```
+
+**Seção 2 — Especificação Página por Página**
+```
+Para cada tela/página:
+- Propósito e usuários que acessam
+- Componentes necessários e responsabilidades
+- Interações e fluxos de usuário
+- Estrutura de mock data necessária
+- Padrões de navegação e roteamento
+```
+
+**Seção 3 — Arquitetura de Componentes**
+```
+- Hierarquia atomic design completa
+- Especificações de props e interfaces TypeScript
+- Padrões de gerenciamento de estado
+- Componentes reutilizáveis e seus contratos
+```
+
+**Seção 4 — Sistema de Design**
+```
+- Paleta de cores e especificações de tipografia
+- Princípios de espaçamento e layout
+- Comportamentos de elementos interativos
+- Breakpoints responsivos (mobile, tablet, desktop)
+- Padrões de acessibilidade (WCAG AA)
+```
+
+**Seção 5 — Detalhes de Implementação Técnica**
+```
+- Estrutura de pastas e organização de arquivos
+- Convenções de nomenclatura
+- Pontos de integração com API (com mock data)
+- Padrões de tratamento de erros e validação
+- Estados de carregamento e feedback ao usuário
+```
+
+**Seção 6 — Mock Data**
+```
+- Objetos mock espelhando formato real da API
+- Dados realistas para todos os tipos de usuário
+- Cobertura de edge cases e estados especiais
+- Convenções de nomenclatura para fácil substituição
+```
+
+**Seção 7 — Requisitos de Qualidade**
+```
+- Checklist de acessibilidade (Nielsen's heuristics)
+- Compatibilidade cross-browser
+- Diretrizes de performance
+- Considerações de teste
+```
+
+---
+
+## Regras
+
+### Nunca
+- Gerar o prompt sem ler a documentação disponível do projeto
+- Usar dados mock genéricos (`user1`, `item123`) — usar dados realistas
+- Gerar prompt incompleto que exija clarificações posteriores ao Lovable
+- Incluir credenciais, tokens ou segredos no prompt
+- Referenciar arquivos externos no prompt (o Lovable não tem acesso)
+- Usar emojis nos títulos de seção do prompt gerado
+
+### Sempre
+- Embutir todo o contexto necessário no prompt (autocontido)
+- Especificar TypeScript em todas as interfaces de componentes
+- Incluir `persistent: true` e `delivery_mode: 2` nos dados persistentes
+- Garantir que toda navegação do app funcione com mock data
+- Cobrir estados de loading, erro e vazio para cada componente de dados
+- Seguir heurísticas de usabilidade de Nielsen no design especificado
+
+---
+
+## Tratamento de Erros
+
+### Documentação ausente ou incompleta
+- Listar quais documentos foram encontrados e quais estão faltando
+- Solicitar ao usuário as informações críticas ausentes antes de prosseguir
+- Gerar prompt parcial apenas se o usuário autorizar explicitamente
+
+### API não documentada
+- Informar ao usuário que a especificação de API não foi encontrada
+- Solicitar: endpoints principais, métodos, estruturas de resposta esperadas
+- Usar mock data com estrutura genérica e deixar comentários no prompt indicando onde substituir
+
+### Escopo muito amplo (app completo sem documentação)
+- Solicitar ao usuário que identifique o módulo ou tela prioritária
+- Gerar prompt por módulo, não tentar cobrir tudo de uma vez
+
+---
+
+## Checklist de Conclusão
+
+- [ ] Toda documentação disponível foi lida
+- [ ] Tipos de usuário e permissões mapeados
+- [ ] Fluxos de usuário extraídos da documentação
+- [ ] Endpoints de API mapeados (ou mock genérico documentado)
+- [ ] Regras de negócio incluídas no prompt
+- [ ] Arquitetura atomic design definida
+- [ ] Mock data com estrutura real da API
+- [ ] Todos os estados cobertos (loading, erro, vazio, cheio)
+- [ ] Sistema de design especificado (cores, tipografia, espaçamento)
+- [ ] Prompt autocontido (sem referências externas)
+- [ ] Navegação completa com mock data funcional
+- [ ] Acessibilidade (WCAG AA) especificada
+
+---
+
+## Output
+
+| Artefato | Descrição |
+|----------|-----------|
+| Prompt Lovable (inline) | Prompt completo e estruturado exibido na conversa |
+| `docs/lovable-prompt.md` | Arquivo salvo com o prompt gerado (opcional, se solicitado) |
+
+---
+
+## Mensagem de Conclusão
+
+```
+Prompt Lovable gerado!
+
+Workspace: {WORKSPACE}
+Escopo: {frontend completo | módulo: {nome}}
+Páginas especificadas: {N}
+Componentes mapeados: {N}
+
+Para usar:
+1. Copie o prompt gerado acima
+2. Cole no Lovable como primeiro prompt do projeto
+3. Substitua os mocks por chamadas reais de API ao integrar com o backend
+
+Próximo passo: Validar o frontend gerado com stakeholders antes de integrar com a API real.
+```
+
+---
+
+## Recursos Adicionais
+
+- **Templates Lovable**: Veja `$IDE/templates/lovable/` para templates de documentos relacionados
+- **Documentação de negócio**: `docs/business-context/` — contexto de usuários e produto
+- **Documentação técnica**: `docs/technical-context/` — APIs e arquitetura