synapos 2.5.0

package/.synapos/skills/brave-search/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: brave-search
+displayName: "Brave Search"
+version: "1.0.0"
+type: mcp
+description: "Pesquisa web via Brave Search API — resultados reais sem rastreamento"
+categories: [search, research, web]
+domains: [produto, ia-dados, backend, fullstack]
+---
+
+## O Que Faz
+
+Habilita o agent a realizar buscas reais na web usando a API do Brave Search.
+
+**Com esta skill, o agent pode:**
+- Buscar informações atualizadas sobre qualquer tópico
+- Pesquisar benchmarks e concorrentes para análises de produto
+- Encontrar documentação técnica, artigos e discussões
+- Validar dados de mercado em tempo real
+
+**Sem esta skill:** O agent usa apenas seu conhecimento de treinamento (sem dados atualizados).
+
+---
+
+## Instalação
+
+### 1. Obter API Key
+
+Crie uma conta e gere a API key em: https://brave.com/search/api/
+
+O plano gratuito inclui **2.000 queries/mês**.
+
+### 2. Configurar variável de ambiente
+
+Adicione ao `.env` do projeto:
+```
+BRAVE_API_KEY=sua_chave_aqui
+```
+
+### 3. Configurar MCP no IDE
+
+**Claude Code** — adicione em `.claude/settings.local.json`:
+```json
+{
+  "mcpServers": {
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — adicione em `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "sua_chave_aqui"
+      }
+    }
+  }
+}
+```
+
+### 4. Reiniciar o IDE
+
+Skills MCP requerem restart do IDE após configuração.
+
+---
+
+## Configuração MCP
+
+```yaml
+type: mcp
+mcp_config:
+  command: npx
+  args: ["-y", "@modelcontextprotocol/server-brave-search"]
+  env:
+    BRAVE_API_KEY: ${BRAVE_API_KEY}
+```
+
+---
+
+## Variáveis de Ambiente
+
+| Variável | Obrigatória | Descrição |
+|----------|-------------|-----------|
+| `BRAVE_API_KEY` | ✅ | Chave de API do Brave Search |
+
+---
+
+## Instruções para o Agent
+
+Quando a skill `brave-search` estiver ativa:
+
+```
+SKILL ATIVA: brave-search
+
+Você tem acesso à ferramenta `brave_web_search` para realizar buscas reais na web.
+
+Diretrizes de uso:
+- Use para dados que podem estar desatualizados no seu treinamento (preços, versões, tendências)
+- Prefira queries específicas a queries genéricas: "React 19 breaking changes 2025" em vez de "React mudanças"
+- Cite as fontes dos dados encontrados (URL + data de publicação quando disponível)
+- Para análises de produto, busque: concorrentes diretos, benchmarks de mercado, reviews de usuários
+- Limite: não use para dados que você já sabe com certeza — priorize buscas para validar ou atualizar
+
+Quando retornar resultados:
+- Filtre pela relevância e data de publicação
+- Sintetize as fontes, não as transcreva
+- Indique se os dados encontrados contradizem seu conhecimento prévio
+```
+
+---
+
+## Casos de Uso por Squad
+
+| Squad | Uso típico |
+|-------|-----------|
+| Produto | Benchmarks de concorrentes, pesquisa de mercado, validação de UX patterns |
+| IA/Dados | Papers recentes, documentação de modelos, melhores práticas de MLOps |
+| Backend | Vulnerabilidades de segurança, changelogs de bibliotecas, Stack Overflow |
+| Frontend | Compatibilidade de browsers, atualizações de frameworks |

package/.synapos/skills/fetch-url/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: fetch-url
+displayName: "Fetch URL"
+version: "1.0.0"
+type: mcp
+description: "Leitura de URLs e extração de conteúdo web — páginas, documentações e APIs públicas"
+categories: [web, research, scraping, documentation]
+domains: [produto, backend, ia-dados, fullstack]
+---
+
+## O Que Faz
+
+Habilita o agent a ler e extrair conteúdo de qualquer URL acessível publicamente.
+
+**Com esta skill, o agent pode:**
+- Ler documentação técnica de qualquer URL
+- Extrair conteúdo de páginas web para análise
+- Consumir endpoints de APIs públicas (REST/JSON)
+- Ler changelogs e release notes de bibliotecas
+- Analisar landing pages de concorrentes
+
+**Diferença de `brave-search`:** `fetch-url` lê o conteúdo completo de uma URL específica. `brave-search` busca URLs relevantes via query. Use ambos em conjunto: busca para encontrar, fetch para ler.
+
+**Sem esta skill:** O agent não consegue acessar URLs externas — apenas usa conhecimento do treinamento.
+
+---
+
+## Instalação
+
+### 1. Configurar MCP no IDE
+
+**Claude Code** — adicione em `.claude/settings.local.json`:
+```json
+{
+  "mcpServers": {
+    "fetch": {
+      "command": "uvx",
+      "args": ["mcp-server-fetch"]
+    }
+  }
+}
+```
+
+Alternativa com npx:
+```json
+{
+  "mcpServers": {
+    "fetch": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    }
+  }
+}
+```
+
+**Cursor** — adicione em `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "fetch": {
+      "command": "uvx",
+      "args": ["mcp-server-fetch"]
+    }
+  }
+}
+```
+
+### 2. Pré-requisito para `uvx`
+
+```bash
+pip install uv
+# ou
+brew install uv
+```
+
+### 3. Reiniciar o IDE
+
+---
+
+## Configuração MCP
+
+```yaml
+type: mcp
+mcp_config:
+  command: uvx
+  args: ["mcp-server-fetch"]
+```
+
+---
+
+## Variáveis de Ambiente
+
+Nenhuma variável de ambiente necessária.
+
+---
+
+## Instruções para o Agent
+
+Quando a skill `fetch-url` estiver ativa:
+
+```
+SKILL ATIVA: fetch-url
+
+Você tem acesso à ferramenta `fetch` para ler conteúdo de URLs.
+
+Ferramentas disponíveis:
+- `fetch` — busca o conteúdo de uma URL e retorna como texto/markdown
+
+Diretrizes de uso:
+- Para documentações: busque a URL da doc oficial, não mirrors ou caches
+- Para APIs públicas: verifique se a URL retorna JSON e parse adequadamente
+- Para páginas longas: identifique as seções relevantes em vez de processar tudo
+- Respeite robots.txt — não use para scraping massivo ou automatizado
+- Cite sempre a URL fonte dos dados extraídos
+
+Combinação recomendada com brave-search:
+1. Use brave-search para encontrar as URLs mais relevantes
+2. Use fetch-url para ler o conteúdo completo das páginas encontradas
+
+Limitações:
+- Não acessa páginas que requerem autenticação
+- Não executa JavaScript (use playwright-browser para SPAs)
+- Conteúdo pode estar desatualizado (cache)
+```
+
+---
+
+## Casos de Uso por Squad
+
+| Squad | Uso típico |
+|-------|-----------|
+| Produto | Ler landing pages de concorrentes, extrair features e pricing |
+| IA/Dados | Ler papers, documentação de modelos, changelogs de APIs de IA |
+| Backend | Ler documentação de APIs externas, RFC specs, changelogs de libs |
+| Frontend | Ler documentação de frameworks, MDN, spec de CSS/HTML |

package/.synapos/skills/filesystem/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: filesystem
+displayName: "Filesystem"
+version: "1.0.0"
+type: mcp
+description: "Leitura e escrita avançada de arquivos — acesso direto ao sistema de arquivos do projeto"
+categories: [file, system, project]
+domains: [frontend, backend, fullstack, mobile, devops, ia-dados, produto]
+---
+
+## O Que Faz
+
+Habilita o agent a ler e escrever arquivos do projeto com acesso direto ao sistema de arquivos.
+
+**Com esta skill, o agent pode:**
+- Ler múltiplos arquivos em uma operação
+- Listar diretórios e árvores de arquivos
+- Escrever e editar arquivos diretamente
+- Buscar por padrões de conteúdo em arquivos
+- Criar e gerenciar estruturas de diretórios
+
+**Diferença do uso padrão:** IDEs como Claude Code já têm capacidade de file I/O. Esta skill MCP é útil principalmente em contextos onde o agent está sendo executado em modo mais restrito, ou quando se quer padronizar o acesso a arquivos entre múltiplos IDEs.
+
+**Sem esta skill:** O agent depende das ferramentas de file I/O nativas do IDE (geralmente suficiente).
+
+---
+
+## Instalação
+
+### 1. Configurar MCP no IDE
+
+**Claude Code** — adicione em `.claude/settings.local.json`:
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/caminho/para/seu/projeto"
+      ]
+    }
+  }
+}
+```
+
+Substitua `/caminho/para/seu/projeto` pelo diretório raiz do seu projeto.
+
+**Múltiplos diretórios:**
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/você/projeto-a",
+        "/Users/você/projeto-b"
+      ]
+    }
+  }
+}
+```
+
+**Cursor** — adicione em `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/caminho/para/seu/projeto"
+      ]
+    }
+  }
+}
+```
+
+### 2. Reiniciar o IDE
+
+---
+
+## Configuração MCP
+
+```yaml
+type: mcp
+mcp_config:
+  command: npx
+  args:
+    - "-y"
+    - "@modelcontextprotocol/server-filesystem"
+    - "${PROJECT_ROOT}"
+```
+
+---
+
+## Variáveis de Ambiente
+
+| Variável | Obrigatória | Descrição |
+|----------|-------------|-----------|
+| `PROJECT_ROOT` | ✅ (na config) | Caminho raiz do projeto a ser acessado |
+
+> Nota: O path é configurado diretamente nos args do MCP, não como env var. Use a variável apenas como referência na configuração.
+
+---
+
+## Segurança
+
+⚠️ **Atenção:** Esta skill concede ao agent acesso de leitura/escrita ao diretório configurado.
+
+- Configure apenas o diretório do projeto, nunca `/` ou `~` completo
+- Em produção, use modo somente-leitura quando escrita não for necessária
+- Nunca configure diretórios com credenciais, SSH keys ou dados sensíveis
+
+---
+
+## Instruções para o Agent
+
+Quando a skill `filesystem` estiver ativa:
+
+```
+SKILL ATIVA: filesystem
+
+Você tem acesso expandido ao sistema de arquivos via MCP.
+
+Ferramentas disponíveis:
+- `read_file` — ler conteúdo de arquivo
+- `read_multiple_files` — ler múltiplos arquivos de uma vez
+- `write_file` — escrever arquivo (cria ou sobrescreve)
+- `create_directory` — criar diretório
+- `list_directory` — listar conteúdo de diretório
+- `directory_tree` — árvore completa de diretórios
+- `move_file` — mover ou renomear arquivo
+- `search_files` — buscar arquivos por padrão glob
+- `get_file_info` — metadados do arquivo (tamanho, datas)
+
+Diretrizes de uso:
+- Prefira `read_multiple_files` para análises que exigem comparar múltiplos arquivos
+- Antes de sobrescrever (`write_file`): confirme com o usuário se não é uma edição incremental
+- Use `directory_tree` para entender a estrutura antes de começar a trabalhar
+- Para buscas, use `search_files` com padrões glob específicos
+
+Segurança:
+- Não acesse arquivos fora do diretório configurado
+- Nunca leia ou escreva arquivos .env, .pem, secrets, ou credenciais
+- Operações destrutivas (delete, overwrite): confirme com o usuário
+```
+
+---
+
+## Casos de Uso por Squad
+
+| Squad | Uso típico |
+|-------|-----------|
+| Todos | Análise de estrutura de projeto, leitura em batch de arquivos |
+| IA/Dados | Leitura de datasets, notebooks, arquivos de configuração de modelos |
+| DevOps | Leitura de configs de infraestrutura (Terraform, K8s manifests) |
+| Produto | Leitura de documentos de spec e ADRs para contexto |

package/.synapos/skills/github/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: github
+displayName: "GitHub"
+version: "1.0.0"
+type: mcp
+description: "Integração com GitHub — issues, PRs, repositórios, código e actions via MCP"
+categories: [git, collaboration, project-management, code]
+domains: [frontend, backend, fullstack, mobile, devops]
+---
+
+## O Que Faz
+
+Habilita o agent a interagir diretamente com o GitHub sem sair do contexto de trabalho.
+
+**Com esta skill, o agent pode:**
+- Criar, listar e comentar em issues
+- Criar e revisar Pull Requests
+- Consultar código de repositórios
+- Buscar em repositórios e código (GitHub Search)
+- Verificar status de GitHub Actions
+- Criar e gerenciar branches
+
+**Sem esta skill:** O agent não consegue criar ou acessar recursos no GitHub — apenas sugere comandos git locais.
+
+---
+
+## Instalação
+
+### 1. Criar Personal Access Token (PAT)
+
+1. Acesse: GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
+2. Crie um token com as permissões necessárias:
+   - `Contents` (read & write) — para ler/escrever arquivos
+   - `Issues` (read & write) — para gerenciar issues
+   - `Pull requests` (read & write) — para criar/revisar PRs
+   - `Actions` (read) — para verificar workflows
+
+### 2. Configurar variável de ambiente
+
+```
+GITHUB_PERSONAL_ACCESS_TOKEN=ghp_sua_chave_aqui
+```
+
+### 3. Configurar MCP no IDE
+
+**Claude Code** — adicione em `.claude/settings.local.json`:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — adicione em `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_sua_chave_aqui"
+      }
+    }
+  }
+}
+```
+
+### 4. Reiniciar o IDE
+
+---
+
+## Configuração MCP
+
+```yaml
+type: mcp
+mcp_config:
+  command: npx
+  args: ["-y", "@modelcontextprotocol/server-github"]
+  env:
+    GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PERSONAL_ACCESS_TOKEN}
+```
+
+---
+
+## Variáveis de Ambiente
+
+| Variável | Obrigatória | Descrição |
+|----------|-------------|-----------|
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | ✅ | PAT com permissões de repo, issues e PRs |
+
+---
+
+## Instruções para o Agent
+
+Quando a skill `github` estiver ativa:
+
+```
+SKILL ATIVA: github
+
+Você tem acesso a ferramentas de integração com GitHub.
+
+Ferramentas disponíveis:
+- `create_issue` — criar issue em repositório
+- `list_issues` — listar issues abertas
+- `create_pull_request` — criar PR
+- `get_pull_request` — consultar PR existente
+- `search_repositories` — buscar repositórios
+- `get_file_contents` — ler arquivo de repositório
+- `list_commits` — listar commits de branch
+
+Diretrizes de uso:
+- Ao criar issues: use título descritivo, labels relevantes, e inclua steps de reprodução para bugs
+- Ao criar PRs: inclua description clara (o quê + por quê), checklist de testes, e linked issue
+- Ao buscar código: use queries específicas com linguagem e repo quando possível
+- Nunca force-push em main/master sem confirmação explícita do usuário
+- Para operações destrutivas (fechar, deletar): confirme com o usuário antes de executar
+
+Formato de PR recomendado:
+## O que esse PR faz
+[descrição]
+
+## Por que
+[motivação]
+
+## Como testar
+[steps]
+
+Closes #{número da issue}
+```
+
+---
+
+## Casos de Uso por Squad
+
+| Squad | Uso típico |
+|-------|-----------|
+| Frontend/Backend | Criar issues para bugs encontrados no review, abrir PRs automaticamente |
+| DevOps | Verificar status de Actions, criar issues de infra |
+| Produto | Consultar issues abertas para contexto de features, criar issues de produto |
+| Todos | Buscar referências de código em outros repositórios |

package/.synapos/skills/playwright-browser/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: playwright-browser
+displayName: "Playwright Browser"
+version: "1.0.0"
+type: mcp
+description: "Automação de browser via Playwright — navegação, screenshots, testes E2E e extração de conteúdo"
+categories: [browser, testing, automation, scraping]
+domains: [frontend, fullstack, mobile, produto]
+---
+
+## O Que Faz
+
+Habilita o agent a controlar um browser real (Chromium, Firefox, WebKit) via Playwright.
+
+**Com esta skill, o agent pode:**
+- Tirar screenshots de qualquer URL (útil para análise de concorrentes e UX)
+- Executar e escrever testes E2E interativos
+- Navegar em SPAs e aplicações que requerem JavaScript
+- Preencher formulários e simular interações do usuário
+- Extrair conteúdo de páginas que não têm API
+
+**Sem esta skill:** O agent não consegue interagir com browsers; apenas analisa código estático.
+
+---
+
+## Instalação
+
+### 1. Instalar dependências
+
+```bash
+npm install -g @playwright/mcp
+npx playwright install chromium
+```
+
+### 2. Configurar MCP no IDE
+
+**Claude Code** — adicione em `.claude/settings.local.json`:
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+**Cursor** — adicione em `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+### 3. Reiniciar o IDE
+
+---
+
+## Configuração MCP
+
+```yaml
+type: mcp
+mcp_config:
+  command: npx
+  args: ["@playwright/mcp@latest"]
+```
+
+---
+
+## Variáveis de Ambiente
+
+Nenhuma variável de ambiente necessária para uso básico.
+
+| Variável | Obrigatória | Descrição |
+|----------|-------------|-----------|
+| `PLAYWRIGHT_BROWSERS_PATH` | ❌ | Caminho customizado para binários de browser |
+
+---
+
+## Instruções para o Agent
+
+Quando a skill `playwright-browser` estiver ativa:
+
+```
+SKILL ATIVA: playwright-browser
+
+Você tem acesso a ferramentas de automação de browser via Playwright.
+
+Ferramentas disponíveis:
+- `browser_navigate` — navegar para uma URL
+- `browser_screenshot` — capturar screenshot da página atual
+- `browser_click` — clicar em elemento
+- `browser_type` — digitar texto em campo
+- `browser_wait` — aguardar elemento ou condição
+
+Diretrizes de uso:
+- Para testes E2E: use seletores semânticos (role, label, text) em vez de CSS/XPath
+- Para screenshots de análise: capture em viewport 1280x800 (desktop) e 390x844 (mobile)
+- Para extração de conteúdo: prefira estrutura semântica (headings, listas) ao HTML bruto
+- Sempre feche o browser após finalizar (evite processos órfãos)
+
+Ao escrever testes:
+- Um teste = um comportamento do usuário
+- Prefira `getByRole`, `getByLabel`, `getByText` a seletores de CSS
+- Adicione waitFor explícito para elementos dinâmicos
+- Testes E2E são lentos — use com parcimônia, foque nos fluxos críticos
+```
+
+---
+
+## Casos de Uso por Squad
+
+| Squad | Uso típico |
+|-------|-----------|
+| Frontend | Escrever e executar testes E2E, verificar regressões visuais |
+| Produto | Screenshots de concorrentes, análise de UX flows |
+| Fullstack | Testes de integração FE↔BE com browser real |
+| QA | Automação de smoke tests pós-deploy |