---
name: wolf-setup
description: Instala e configura três ferramentas complementares para reduzir consumo de token e aumentar disciplina de engenharia em agentes de codificação de IA (Claude Code, Cursor, Antigravity, Codex CLI, etc.) — Superpowers, Serena e Caveman.
---

# Wolf Setup — Superpowers + Serena + Caveman

## Visão geral

Três ferramentas em camadas diferentes do mesmo ciclo de trabalho com IA:

| Ferramenta | Camada | O que resolve |
|---|---|---|
| Superpowers | Processo | Planejamento e disciplina antes de codar |
| Serena | Entrada | Economia de token na leitura de código (navegação semântica via LSP) |
| Caveman | Saída | Economia de token na resposta da IA |

**Ressalva honesta:** números de marketing costumam ser otimistas. Ganho real medido de forma independente é mais modesto que o anunciado — ainda vale a pena, só não espere o número da propaganda.

**Ressalva sobre ativação automática:** nenhuma das três garante ativação sozinha em toda sessão nova, mesmo instalada e commitada. O hook da Fase 2.5 reduz o risco, não elimina — por isso a Fase 6 é obrigatória, não opcional.

## Quando usar / quando não vale a pena

Projeto de porte médio/grande, uso frequente de IA pra codar. Não vale a pena em script pequeno ou projeto recém-criado — o overhead de carregar as ferramentas supera o ganho.

---

# INSTALAÇÃO

Siga as fases na ordem. Ao final de cada uma, reporte o que foi feito antes de iniciar a próxima.

### Fase 0 — Diagnóstico
Identifique e reporte: ambiente atual (Claude Code, Cursor, VS Code, Antigravity, Codex, outro), sistema operacional, se alguma das 3 já está instalada.

### Fase 1 — Superpowers
Claude Code:
```
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
```
Outro ambiente: consulte `github.com/obra/superpowers` — não presuma que o comando do Claude Code funciona igual em outro lugar.

Confirme verificando `/superpowers:brainstorm`, `/superpowers:write-plan`, `/superpowers:execute-plan`. Reporte antes de seguir.

### Fase 2 — Serena

Verifique se `uv` está instalado; instale se necessário.

**Primeiro, pergunte: você trabalha com um projeto só nesta máquina, ou com múltiplos projetos/repositórios?** A resposta muda qual configuração usar — não são intercambiáveis, e escolher errado reproduz o mesmo bug que a checagem manual existe pra evitar.

**Se múltiplos projetos (caso mais comum, e o recomendado por padrão): configuração por repositório.**

Cada projeto tem seu próprio `.cursor/mcp.json` (ou equivalente do ambiente), com `--project` apontando explicitamente pra aquela pasta:
```json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena",
                "start-mcp-server", "--context", "claude-code",
                "--project", "/caminho/absoluto/deste/projeto"]
    }
  }
}
```
Repita essa configuração em cada projeto onde for usar a Serena. Dá mais trabalho de configurar uma vez por projeto, mas elimina por completo a ambiguidade de onde o processo MCP foi iniciado — não depende do editor ter subido o processo no lugar certo.

⚠️ **O caminho é absoluto e específico da sua máquina — não commite esse arquivo sem revisar** (ver Fase 5). Se outro colaborador clonar o repo, o caminho não vai bater com a máquina dele.

**Se projeto único nesta máquina: `--project-from-cwd` global pode funcionar, com ressalva.**
```
claude mcp add --scope user serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project-from-cwd
```
`--project-from-cwd` detecta o projeto subindo diretórios a partir de onde o **processo MCP** foi iniciado — não necessariamente de onde o editor está com foco agora. Isso só é confiável se o editor sempre subir o MCP com o cwd na pasta certa, o que **nem sempre acontece** — foi exatamente essa falha que causou o problema original: o processo subiu com cwd na home, o flag caminhou até `~/.serena/project.yml`, e ativou o projeto errado sem avisar.

⚠️ **Nunca use esse modo global abrindo o editor a partir da pasta home (`~/`), a menos que a home tenha seu próprio `.serena/project.yml` de propósito** — senão a Serena ativa o que encontrar lá, silenciosamente, sem erro nem timeout necessariamente. É o cenário mais perigoso porque não trava — só mente.

⚠️ **Plugin oficial do Claude Code não inclui `--project-from-cwd` por padrão.** Se instalado via `/plugin install`, adicione manualmente (ver troubleshooting).

**Nos dois casos:**

⚠️ **Depois de qualquer mudança na configuração do MCP, recarregue o servidor (ou reinicie o editor) antes de confiar em qualquer resultado.** Mudar o arquivo de config não move um processo já em execução — ele continua preso no projeto anterior até o reload. Se havia processo antigo rodando com configuração diferente, encerre-o explicitamente; não assuma que ele morre sozinho.

⚠️ **No Cursor, servidor MCP configurado por projeto nasce desligado no painel — precisa ser ativado manualmente.** Depois de criar ou editar o `.cursor/mcp.json`, vá em Settings → Tools & MCP e confirme que o toggle da linha `serena` está ligado (verde), não só que o arquivo existe. **Esta é a causa mais comum de "configurei certo e não conecta"** — o servidor fica parado em `disconnected` sem nenhum erro real, porque o host nem tenta abrir o processo enquanto a fonte estiver desabilitada. Confira isso **antes** de suspeitar de bug de sandbox, path, ou qualquer outra coisa — é o primeiro lugar a olhar, não o último.

Rode a indexação inicial do projeto atual. Reporte antes de seguir.

### Fase 2.5 — Hook de lembrete (SessionStart)

Configure lembrete de ativação. Claude Code, em `.claude/settings.json`:
```json
{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "echo 'Lembrete desta sessão: (1) confirme Superpowers ativo. (2) ative Caveman em modo full como primeira ação, se ainda não estiver. (3) para código deste repo, priorize Serena — ver Regras de Uso antes de confiar em qualquer resultado dela.'"
      }]
    }]
  }
}
```
Cursor: regra `alwaysApply: true` em `.cursor/rules/`, mesmo lembrete.

**Limitação conhecida:** não existe forma de forçar mecanicamente a chamada de uma ferramenta MCP antes da primeira mensagem do usuário. O hook aumenta a chance de ativação, não garante 100%. A Fase 6 continua obrigatória.

### Fase 3 — Caveman
```
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash
```
Outro ambiente: verifique suporte em `github.com/JuliusBrussee/caveman` antes de instalar.

Ative no padrão:
```
/caveman full
```
Reporte antes de seguir.

### Fase 4 — Verificação de instalação
Liste as 3 ferramentas com status (instalada/funcionando, instalada/não testada, não instalada). Confirme indexação da Serena concluída, Caveman ativo em full, hook de SessionStart criado. Nenhuma alteração de código nesta fase.

### Fase 5 — Commit e push (opcional, com confirmação)
Pergunte se deseja commitar a configuração. Se sim:
1. Separe CONFIGURAÇÃO (vai pro commit: registro de MCP, hook de SessionStart, nível do Caveman se salvo em arquivo) de CACHE/ÍNDICE (não vai: índice da Serena, pesado e regenerável — vai pro `.gitignore`)

⚠️ **Se a Serena foi configurada por projeto (`.cursor/mcp.json` com `--project` fixo, ver Fase 2): o caminho é absoluto e específico desta máquina.** Antes de commitar, avalie se isso deveria ir pro `.gitignore` em vez de commitado — se outro colaborador clonar o repo, o caminho não vai bater com a máquina dele. Pergunte ao usuário explicitamente antes de decidir.
2. Crie/atualize `.gitignore` conforme necessário
3. Mostre `git status` antes de commitar — nunca sem essa confirmação visual
4. Commit: `"chore: configura Superpowers, Serena e Caveman no projeto"`
5. Push é decisão separada — nunca automático, mesmo com commit aprovado

### Fase 6 — Verificação final (plano vs. executado)
Compare o plano (Fases 0-5) com o que foi de fato feito. Para cada fase: concluída, parcial, ou não executada — com evidência concreta (comando, arquivo, output), nunca só afirmação.

Pergunte explicitamente: "Você está usando as três de verdade nesta sessão, ou só estão instaladas sem estarem ativas agora?" — não presuma pela instalação anterior.

Gere resumo final em tabela (Fase | Status | Evidência).

---

# REGRAS DE USO

Cobre quando cada ferramenta entra em ação durante o trabalho real — não só instalação.

## Superpowers — ordem de ativação

Todo pedido que envolve escrever ou alterar código passa pelo fluxo (brainstorm → plano → execução) antes de codar. Pedido puramente conceitual ("explica isso", "o que esse arquivo faz") não precisa do fluxo completo.

## Serena — quando usar, e verificação de projeto ativo

**Usa em:** achar/editar função, rename, mapear referência — tarefa de código real neste repositório.

**Não usa em:** pergunta conceitual, DNS, variável de ambiente, copy, documentação. Nesses casos, obrigar Serena **soma** custo (round-trip de MCP + resultado no contexto), não corta — o catálogo de tools dela já entra no input assim que o MCP conecta, então chamar sem necessidade é prejuízo líquido, não economia.

**Nunca obrigatória em todo turno**, inclusive "ok"/"entendi" — isso é o pior caso: tool call inútil, contexto cresce à toa.

**⚠️ Projeto ativo — depende de como a Fase 2 foi configurada:**

A Serena ativa um projeto por processo MCP, não por pasta aberta no editor. Se a configuração não isolar cada projeto de forma explícita, ela pode continuar presa num projeto anterior — ou pior, ativar um projeto totalmente diferente do que você imagina, sem erro nem aviso.

**Se configurado por repositório** (`.cursor/mcp.json` com `--project` fixo por pasta, ver Fase 2 — recomendado para quem trabalha com múltiplos projetos): o processo já nasce isolado naquele projeto. Ainda assim, confirme depois de qualquer reload que o `project_name` retornado bate com o projeto esperado — configuração correta no arquivo não garante que o processo em execução já reflete isso (ver aviso de reload abaixo).

**Se configurado globalmente com `--project-from-cwd`:** menos confiável, porque depende de onde o editor iniciou o processo MCP — nem sempre é a pasta que está com foco agora. Trate todo resultado da Serena neste modo com a verificação abaixo, sempre, não como exceção.

**Depois de qualquer mudança na configuração do MCP, é preciso recarregar** (no Cursor: Settings → MCP → recarregar o servidor, ou Reload Window) **e encerrar processos antigos explicitamente** — mudar o arquivo não move um processo já em execução, e ele não morre sozinho. Processo zumbi com configuração antiga é a causa mais comum de "corrigi e continua errado".

**Verificação manual (obrigatória no modo global; recomendada como checagem pontual mesmo no modo por repositório):**
1. Compare a pasta de trabalho atual com a última pasta confirmada nesta conversa
2. Se for a primeira chamada da sessão, se a pasta mudou, ou se houve reload recente de configuração: confirme o projeto ativo antes de prosseguir — peça o `project_name` retornado por alguma tool da Serena e confira se bate com o projeto esperado, não presuma pelo que está escrito no arquivo de config
3. Se já verificado e nada mudou: pode confiar sem repetir
4. Nunca reporte resultado da Serena como confiável sem essa verificação ter passado — se não verificou, diga isso explicitamente

## Caveman — nível por contexto

- **full** — padrão pro trabalho solo do dia a dia. Mantém precisão técnica, corta só a conversa desnecessária
- **lite** — ao compartilhar tela/saída com alguém menos técnico, ou navegando código pouco familiar onde nuance importa mais que velocidade
- **ultra** — só em fluxo profundo, domínio que você já conhece de cor. Avaliação independente mostra perda de qualidade em explicação que exige nuance — evite fora desse cenário
- Sai do modo comprimido sozinho em aviso de segurança, confirmação de ação irreversível, ou ao detectar confusão (mesma pergunta repetida) — não precisa desligar manualmente nesses casos

Basta pedir pra ativar, sem especificar nível — o padrão já é `full`.

## Ordem de precedência, quando mais de uma se aplica

```
Pedido de código chega
  → Superpowers decide SE precisa de plano (brainstorm/plano/execução)
  → Durante a execução, Serena entra pra navegar/editar código 
    (critério acima — nunca sem verificar projeto ativo)
  → Caveman filtra a saída final, sempre, independente do que rolou antes
```

---

# TROUBLESHOOTING

- **Serena (ou qualquer MCP por projeto no Cursor) fica em `disconnected` sem erro nenhum, mesmo com a configuração aparentemente correta:** verifique PRIMEIRO se o servidor está desligado no painel — Settings → Tools & MCP → toggle da linha do servidor. Servidor MCP configurado por projeto nasce desligado no Cursor; o arquivo de config existir não é o mesmo que estar ativado. Essa é a causa mais comum e mais barata de descartar, confira antes de qualquer outra hipótese
- **Serena não conecta, mesmo com o toggle ligado:** confirme `uv` instalado e no PATH
- **Serena parece estar no projeto errado:** ver seção "Verificação de projeto ativo" acima — é comportamento conhecido, não bug isolado
- **Corrigi a configuração e continua errado:** processo antigo (zumbi) ainda rodando com a configuração anterior. Encerre o processo explicitamente e recarregue — trocar o arquivo não mexe em processo já em execução
- ⚠️ **Sobre logs mencionando "sandbox" ou "supported=false":** isso pode aparecer no log geral do host mesmo sem relação com o servidor que você está depurando — não é confirmação de bloqueio. Antes de investigar sandbox, confirme o toggle (primeiro item desta lista) e procure a linha específica `connecting stdio for [nome-do-servidor]` no log — se essa linha nunca aparece, o host nem tentou conectar, e a causa é ativação, não sandbox
- **Caveman não reconhecido fora do Claude Code:** sem suporte universal documentado — verifique a documentação oficial antes de insistir
- **Comando de instalação do Superpowers falha fora do Claude Code:** não existe comando único — sempre confira a documentação oficial antes de adaptar
- **Índice da Serena parou após pull de colaborador:** normal, o índice não vai pro Git — reindexe
- **Ferramenta "instalada" mas não usada na sessão:** esperado sem invocação manual ou hook ativo — confira se o SessionStart (Fase 2.5) foi de fato configurado

## Créditos
- Superpowers: github.com/obra/superpowers (Jesse Vincent, MIT)
- Serena: github.com/oraios/serena (Oraios AI, MIT)
- Caveman: github.com/JuliusBrussee/caveman (MIT)