@tavaressan/vetor 0.1.0

package/templates/skills/shared/references/mcp-availability.md

@@ -0,0 +1,104 @@
+# Verificação de Disponibilidade de MCP (Vetor)
+
+Todas as skills que têm um caminho "Com MCP" / "Sem MCP (Fallback)" devem verificar disponibilidade
+da mesma forma — esta referência centraliza o mecanismo para evitar que cada skill reinvente (ou
+pule) a checagem.
+
+## O mecanismo correto
+
+Ferramentas de servidores MCP aparecem no seu namespace de ferramentas com o prefixo
+`mcp__<server>__<tool>` (ex.: `mcp__sentry__list_issues`) — diretas na
+lista de ferramentas disponíveis, ou listadas por nome entre as ferramentas diferidas (que você
+carrega via `ToolSearch` antes de chamar).
+
+**Verificar disponibilidade é simplesmente olhar se algum nome com esse prefixo existe** — não é
+necessário rodar comando, nem tentar a chamada MCP "para ver se funciona":
+
+1. Procure na sua lista de ferramentas (diretas + diferidas, listadas em `<system-reminder>` no
+   início da conversa e sempre que atualizadas) por qualquer nome começando com `mcp__<server>__`,
+   onde `<server>` é o servidor relevante para a tarefa (sentry/observabilidade,
+   banco de dados).
+2. **Se existir:** o MCP está disponível. Se a ferramenta estiver na lista de diferidas, carregue-a
+   primeiro com `ToolSearch({query: "select:<tool_name>"})` antes de chamá-la.
+3. **Se não existir nenhum nome com esse prefixo:** o MCP não está configurado nesta sessão — vá
+   direto para o fallback documentado na skill (CLI `gh`, query SQL manual, etc.). Não gaste uma
+   chamada tentando invocar uma ferramenta MCP inexistente só para descobrir que falha.
+
+## Por que não "tentar e capturar erro"
+
+Tentar chamar uma ferramenta MCP e cair para o fallback só se ela falhar desperdiça uma chamada de
+ferramenta (e o turno associado) sempre que o MCP não está configurado — que é exatamente o caso mais
+comum hoje. Como a lista de ferramentas já informa antecipadamente o que está disponível, a checagem
+correta é estática (olhar a lista), não uma tentativa em runtime.
+
+## Servidores relevantes neste plugin
+
+| Observabilidade (Sentry/Datadog) | `mcp__sentry__` / `mcp__datadog__` | `backlog-ideator` §2.a (opcional) |
+| Banco de dados | `mcp__<db>__` (nome depende do MCP configurado) | `guardian` (auditoria de schema/queries) |
+| Docker | `mcp__docker__` | `guardian` (auditoria de saúde de containers) |
+| Browser (chrome-devtools) | `mcp__chrome-devtools__` | `fix-loop-agent` (reproduzir bug de UI antes do fix), `worktree-ship` (checagem e2e leve antes do PR) |
+| Pesquisa web (Exa) | `mcp__exa__` | `backlog-ideator` (pesquisar padrões/arquitetura antes de propor issue), `fix-loop-agent` (pesquisar mensagem de erro/documentação de uma lib externa), `issue-worker` (checar docs de API externa durante a implementação) |
+| Documentação de ferramentas/libs (Context7) | `mcp__context7__` | **Obrigatório quando disponível** (ver issue vetor#163) — qualquer skill que precise pesquisar comportamento de uma ferramenta/lib/framework/API externa (`issue-worker`, `fix-loop-agent`, `guardian`, `backlog-ideator`) |
+| Documentação do próprio Claude Code (`claude-code-docs`) | `mcp__claude-code-docs__` | **Obrigatório quando disponível** (ver issue vetor#164) — qualquer skill que precise responder sobre o funcionamento do próprio Claude Code (hooks, slash commands, MCP, permissões, SDK) (`vetor` (setup), `retro`) |
+
+### Documentação de ferramentas/libs (Context7)
+
+Use antes de afirmar comportamento de uma ferramenta, biblioteca, framework, SDK ou API externa —
+não confie só no conhecimento pré-treinado do agente, que pode estar desatualizado.
+
+- **Com MCP (obrigatório):** `mcp__context7__resolve-library-id` para achar o library ID, depois
+  `mcp__context7__query-docs` com uma pergunta específica e escopada a um único conceito.
+- **Sem MCP (fallback):** siga sem o MCP, sinalizando a limitação no resultado entregue ao usuário —
+  não bloqueia a skill.
+
+### Documentação do próprio Claude Code (`claude-code-docs`)
+
+Use antes de afirmar comportamento do próprio Claude Code (hooks, slash commands, configuração de
+MCP, permissões, SDK de agentes, comportamento do harness) — evita responder de memória sobre um
+produto que muda rápido.
+
+- **Com MCP (obrigatório):** consulte via `mcp__claude-code-docs__*` antes de afirmar comportamento
+  do produto. Registro: `claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp`
+  (endpoint oficial confirmado via Context7 contra `code.claude.com/docs/en/mcp-quickstart` —
+  **não** usar `https://claude.com` nem `https://code.claude.com/docs/en/`, que são páginas HTML e
+  não conectam como MCP).
+- **Sem MCP (fallback):** siga sem o MCP, sinalizando a limitação no resultado — não bloqueia a
+  skill. Nota: há sobreposição parcial com o agente `claude-code-guide` já existente no Vetor/Claude
+  Code para dúvidas sobre o próprio produto; ao implementar, avaliar se o MCP substitui ou
+  complementa esse agente.
+
+### Pesquisa web (Exa)
+
+Use quando a tarefa precisa de busca na web ou fetch de uma página específica — pesquisar
+documentação externa, mensagens de erro pouco usuais, padrões de arquitetura, ou conteúdo de uma
+URL já conhecida. Não é um substituto do Context7 (ver issue vetor#163 — Context7 é o caminho
+preferido para documentação de ferramentas/bibliotecas quando disponível); use Exa para busca web
+geral e fetch de páginas que o Context7 não cobre.
+
+- **Com MCP:** use `mcp__exa__web_search_exa` para busca geral e `mcp__exa__web_fetch_exa` para
+  buscar o conteúdo de uma URL específica. Se o servidor tiver sido registrado com
+  `web_search_advanced_exa` habilitado (query param `tools=` na URL do MCP), prefira essa variante
+  para buscas que precisem de filtros mais refinados.
+- **Sem MCP (fallback):** prossiga sem pesquisa web — baseie a resposta no conhecimento do agente e
+  nos arquivos do projeto, sinalizando a limitação quando a falta de pesquisa externa for relevante
+  para a conclusão.
+
+**Autenticação:** o Exa MCP usa OAuth (sem API key) — a primeira conexão abre o navegador para login
+na conta Exa. Não é necessário configurar segredo nenhum no ambiente do Vetor.
+
+### Browser (chrome-devtools)
+
+Use só quando a tarefa envolve UI/frontend (bug reportado como visual, PR que altera componentes de
+interface). Não invoque para módulos puramente backend/CLI.
+
+- **Com MCP:** navegue até a página relevante (`mcp__chrome-devtools__navigate_page`), reproduza o
+  cenário (`click`/`fill`/`fill_form`) e capture evidência (`take_screenshot`,
+  `list_console_messages`, `list_network_requests`) antes de propor o fix. No `worktree-ship`, use o
+  mesmo fluxo como checagem e2e leve (navegar pelo fluxo alterado e conferir ausência de erros de
+  console) antes de abrir o PR — nunca como substituto dos testes automatizados do módulo.
+- **Sem MCP (fallback):** prossiga sem reprodução visual — baseie o diagnóstico/fix na descrição do
+  bug, logs de erro e testes existentes, como já era feito antes deste mecanismo.
+
+Cada skill que referencia este documento deve nomear o servidor esperado (ex.: "Observabilidade" na seção
+acima) antes de aplicar o mecanismo — este documento define *como* checar, não *quais* servidores
+uma skill específica precisa.

package/templates/skills/shared/references/module-test-map.template.md

@@ -0,0 +1,72 @@
+# Module Test Map — TEMPLATE
+
+> **Este é um template.** Copie-o para o seu projeto e preencha com os comandos do
+> SEU repositório:
+>
+> ```bash
+> mkdir -p .claude/vetor
+> cp "$CLAUDE_PLUGIN_ROOT/skills/shared/references/module-test-map.template.md" \
+>    .claude/vetor/module-test-map.md
+> # edite .claude/vetor/module-test-map.md
+> ```
+>
+> As skills `worktree-ship`, `fix-loop-agent` e `guardian` procuram a cópia preenchida
+> em `.claude/vetor/module-test-map.md`. Se ela não existir, tentam auto-detectar os
+> comandos a partir de `.github/workflows/*.yml`; só então recorrem a este template.
+
+Referência canônica dos comandos de teste headless por módulo. O ideal é derivá-la do
+seu pipeline de CI (ex.: `.github/workflows/ci.yml`).
+
+---
+
+## Comandos por módulo
+
+Substitua as linhas abaixo pelos módulos e comandos do seu projeto. Cada comando deve
+ser **headless** (sem interação) e retornar exit code 0 em caso de sucesso.
+
+| Módulo            | Comando headless                                  | Notas |
+|-------------------|---------------------------------------------------|-------|
+| `<seu-modulo-1>`  | `<comando de format + lint + test>`               | `<observações>` |
+| `<seu-modulo-2>`  | `<comando de build + test>`                        | `<observações>` |
+| `<modulo-integ>`  | `<comando de testes de integração>`                | Requer serviço externo (DB etc.); pular em sandbox e reportar "skipped (requires <dep>)" |
+| `<modulo-sem-testes>` | `sem suíte de testes` | Não executar; reportar como "skipped (no test suite)" |
+
+<!--
+Exemplo ilustrativo (remova após preencher):
+
+| `api`           | `cd api && deno task test`                              | Deno; deps vêm do cache global |
+| `core`          | `cd core && deno test -A`                               | Deno sem task `test` definida |
+| `backend`       | `cd backend && npm ci && npm run lint && npm test`      | Node: lint + unit |
+| `backend-integ` | `cd backend && npm run test:integration`                | Requer DB vivo; pular em sandbox |
+-->
+
+## Detecção de módulo por arquivos alterados
+
+Para determinar qual módulo testar, inspecione `git diff <default-branch> --name-only`
+e mapeie os prefixos de path aos módulos:
+
+| Prefixo do path     | Módulo            |
+|---------------------|-------------------|
+| `<seu-modulo-1>/`   | `<seu-modulo-1>`  |
+| `<seu-modulo-2>/`   | `<seu-modulo-2>`  |
+
+Se arquivos de múltiplos módulos foram alterados, execute todos os módulos afetados em
+sequência.
+
+## Regras de execução
+
+### Regra sandbox
+- **Docker:** uma tentativa por sessão; se bloqueado pelo usuário ou pelo sistema, troca
+  permanentemente para comandos headless desta tabela.
+- **Docker isolado:** usar `docker compose -p <slug>` para evitar conflito de portas entre
+  worktrees paralelos.
+- **Testes que exigem serviço externo (DB, broker, etc.):** só executar em ambiente com a
+  dependência disponível (docker ou CI); em headless, pular e reportar como
+  "skipped (requires <dep>)" no sumário.
+- **Módulo sem suíte:** quando o comando for `sem suíte de testes`, não execute comando algum;
+  reporte "skipped (no test suite)". Isso não é falha de teste.
+
+### Exclusões obrigatórias
+Todo `find` ou `grep` executado pelos skills deve excluir:
+- `.claude/worktrees/*` — evita contaminação por worktrees aninhados
+- `node_modules/`, `target/`, `.next/`, `__pycache__/`, `.venv/`, `build/`, `dist/`

package/templates/skills/shared/references/planning-conventions.md

@@ -0,0 +1,97 @@
+# Convenções de Planejamento e Economia de Tokens (Vetor)
+
+Este documento estabelece o padrão de design para o ciclo de vida de planejamento das skills do Vetor, visando a **experiência do usuário (Human-in-the-Loop)** e a **redução drástica do consumo de tokens**.
+
+---
+
+## 1. Princípios de Economia de Tokens e Contexto
+
+Para evitar sessões com mais de 150k de contexto e o spawn excessivo de subagentes caros:
+
+### 1.1 Limites de Contexto e Leitura Bruta
+* **Regra de 100 linhas**: Nunca despeje mais de 100 linhas de logs, documentações ou dumps brutos de arquivos no contexto do agente primário se houver um runtime de delegação disponível (Gemini/OpenCode/Codex — ver `delegate-to-runtime.md`).
+* **Delegação Obrigatória** (sintaxe de invocação e algoritmo de seleção de runtime em `delegate-to-runtime.md` §1-2; `$DELEGATE` = comando do runtime selecionado):
+  - **Logs de Erro/CI**: Utilize `gh run view <run-id> --log-failed | $DELEGATE "..."` para obter resumos de até 15 linhas antes do diagnóstico.
+  - **Documentações longas**: Use `cat <docs> | $DELEGATE "..."` para gerar sumários arquiteturais compactos de alta densidade antes de analisar o backlog.
+  - **Dumps de Migrations/Estruturas**: Use `ls -R | $DELEGATE "..."` para pré-auditar antes de o agente ler os arquivos.
+* **Finalização Restrita**: Oriente os subagentes a finalizarem a execução assim que atingirem seu objetivo restrito, em vez de manter contexto acumulando além do necessário.
+
+### 1.2 Regras de Orquestração de Subagentes
+* **Haicuzation por Padrão**: Todo subagente worker deve ser configurado por padrão com `haiku` para tarefas classificadas como `fix`, `chore` ou `test` menores.
+* **Sonnet sob Demanda**: Limite o uso de `sonnet` apenas para features complexas (`feat`), refatorações estruturais (`refactor`) ou quando um subagente `haiku` esgotar suas iterações e o coordenador optar pelo redespacho seletivo.
+
+---
+
+## 2. Aprovação do plano antes de despachar subagentes
+
+Todas as skills que realizam mutações estruturais (criar issues, rodar auto-fixes no repo, despachar
+subagentes) devem apresentar o plano de ações e obter aprovação explícita do usuário antes de agir.
+O mecanismo de aprovação depende do ecossistema — ver §2.2.
+
+### 2.1 Conteúdo mínimo do plano
+
+Independente do mecanismo de aprovação, o plano apresentado deve conter:
+
+```markdown
+# Plano de Execução Vetor — [Nome da Skill]
+
+[Breve sumário executivo da operação]
+
+## Ações Propostas
+
+[Lista detalhada de mutações a serem feitas, ex.: issues a criar, commits a aplicar, subagentes a iniciar]
+
+### Tabela de Configuração e Recursos
+Exemplo para Coordinator:
+| Subagente/Grupo | Módulo/Issue | Modelo Sugerido | Ação |
+|-----------------|--------------|-----------------|------|
+| worker-slug-a   | #42          | haiku           | Criar|
+
+*Você pode pedir para forçar o uso de um modelo diferente antes de aprovar.*
+```
+
+### 2.2 Mecanismo de aprovação por ecossistema
+
+#### Para skills de implementação de código (`fix-loop-agent`, `issue-worker`, e similares)
+
+* **No Claude Code**: use o plan mode nativo — apresente o plano acima e conclua com `ExitPlanMode`
+  para pedir aprovação do usuário. Este é o caminho de primeira classe no Claude Code para código,
+  não um fallback.
+* **No Antigravity/Gemini**: salve o plano no artefato `implementation_plan.md` definindo
+  `request_feedback: true` nos metadados. O agente interromperá a chamada até o clique em "Proceed".
+
+#### Para skills de orquestração/ideação (`backlog-ideator`, `issue-coordinator`, `guardian`)
+
+Estas skills realizam mutações estruturais (criar issues, orquestrar subagentes) mas **não implementam
+código de produto**. Para elas:
+
+* **No Claude Code**: exiba o plano no chat e aguarde uma resposta textual afirmativa do usuário
+  (ex.: "sim", "prosseguir"). **Não use `ExitPlanMode`** — a ferramenta a desaconselha explicitamente
+  para tarefas fora do escopo de escrita de código.
+* **No Antigravity/Gemini**: salve o plano no artefato `implementation_plan.md` definindo
+  `request_feedback: true` nos metadados. O agente interromperá a chamada até o clique em "Proceed".
+
+#### Fallback para ecossistemas sem mecanismo nativo
+
+Em ecossistemas sem nenhum dos dois mecanismos acima, exiba o plano no chat e aguarde uma resposta
+textual afirmativa do usuário (ex.: "sim", "prosseguir") antes de prosseguir com a execução.
+
+---
+
+## 3. Equilíbrio de Princípios: YAGNI, KISS e DRY
+
+Regras não-óbvias de escrita de código, consumidas por referência pelos prompts do `issue-worker`
+e do `fix-loop-agent` (não replique estes parágrafos nas skills):
+
+* **Regra das 3 perguntas**: só pergunte quando houver ambiguidade crítica de arquitetura/escopo,
+  e nunca mais de 3 perguntas objetivas num único turno. Se o prompt/requisitos já bastam,
+  prossiga sem perguntar (YAGNI — não pergunte sobre cenários futuros).
+* **TDD antes do fix**: red antes de green — escreva primeiro um teste de reprodução que falhe,
+  cobrindo só o bug em questão, antes de tocar no código de produto. Disciplina completa (bom teste,
+  seams, anti-padrões, mocking) em `tdd-conventions.md` — não replique o texto aqui.
+* **KISS/YAGNI no código**: a menor alteração que faz o teste passar; sem refatoração oportunista
+  em arquivos adjacentes nem abstrações "para o futuro".
+* **Reuso antes de reinventar**: rotinas complexas (detecção de testes, checagens de git) já podem
+  estar em `scripts/` (ex.: `detect-project.ts`, `vetor-checks.sh`) ou nas referências — verifique
+  antes de escrever lógica inline.
+

package/templates/skills/shared/references/project-conventions.md

@@ -0,0 +1,63 @@
+# Convenções de projeto (branch default + comandos de teste)
+
+Referência compartilhada para as duas resoluções que `fix-loop-agent`, `worktree-ship` e
+`worktree-create` precisam fazer no início de sua execução. Consumida pelos três — nenhuma outra
+skill precisa disso.
+
+---
+
+## Branch default
+
+Nunca assuma `master`. Resolva em runtime via mecanismo compartilhado:
+
+```bash
+DEFAULT_BRANCH=$(bash "$CLAUDE_PLUGIN_ROOT/scripts/vetor-checks.sh" default-branch)
+```
+
+Use `$DEFAULT_BRANCH` em todos os comandos subsequentes (`git diff`, `git pull`, `git push`,
+`gh pr create --base`, etc.).
+
+---
+
+## Comandos de teste por módulo (`module-test-map`)
+
+**Mecanismo canônico de resolução (issue #160): sempre resolva via ROOT do repositório, nunca via
+`cwd`.** Quando `fix-loop-agent`/`worktree-ship` rodam dentro de um worktree linkado, o worktree é
+um checkout limpo — arquivos ignorados pelo `.gitignore` do projeto-alvo (ex.: uma entrada `.claude/`,
+comum em setups que tratam config de assistente como local) nunca são materializados nele. Se
+`.claude/vetor/module-test-map.md`/`config.json` só existirem no repositório principal, procurá-los
+a partir do `cwd` do worktree falha silenciosamente — o agente ou inventa um comando de teste, ou
+reporta erroneamente que não há suíte.
+
+Resolva o root primeiro, sempre:
+
+```bash
+REPO_ROOT=$(bash "$CLAUDE_PLUGIN_ROOT/scripts/vetor-checks.sh" repo-root)
+```
+
+Esse subcomando usa `git rev-parse --git-common-dir`, que aponta para o `.git` compartilhado do
+checkout principal mesmo quando executado de dentro de um worktree linkado — funciona tanto no root
+quanto em qualquer worktree.
+
+Em seguida, resolva nesta ordem, sempre a partir de `$REPO_ROOT` (nunca do `cwd`):
+
+1. Verifique se `$REPO_ROOT/.claude/vetor/module-test-map.md` existe.
+2. Se não existir, alerte o desenvolvedor que o ambiente não está inicializado e recomende rodar a skill `/vetor` para configurá-lo corretamente. Como fallback de execução automática, execute o script de auto-detecção:
+   ```bash
+   deno run -A "$CLAUDE_PLUGIN_ROOT/scripts/detect-project.ts"
+   ```
+   Imprima no console do desenvolvedor:
+   `echo "[Vetor:AutoSetup] ATENÇÃO: Configuração não encontrada. Recomenda-se rodar o comando /vetor para inicializar. Gerado mapeamento temporário em .claude/vetor/module-test-map.md"`
+3. Se a auto-detecção falhar, instrua o usuário a rodar o comando `/vetor` para preparar o ambiente.
+
+O mesmo vale para `.claude/vetor/config.json` (que contém `testCommand`, `runtime`,
+`packageManager`, etc.) — sempre leia via `$REPO_ROOT/.claude/vetor/config.json`, nunca via um path
+relativo ao `cwd`.
+
+Mapeie arquivos alterados (`git diff "$DEFAULT_BRANCH" --name-only`) aos módulos usando a tabela de
+detecção do `module-test-map.md` resolvido.
+
+**Nota (reforço redundante, opcional):** o `issue-coordinator`, ao detectar que `.claude/` está no
+`.gitignore` do projeto-alvo (`git check-ignore -q .claude`), pode injetar os comandos de teste já
+resolvidos diretamente no prompt de cada worker despachado, como reforço adicional — mas a fonte de
+verdade permanece a resolução via `repo-root` acima, não essa injeção.

package/templates/skills/shared/references/tdd-conventions.md

@@ -0,0 +1,81 @@
+# Disciplina de TDD (Vetor)
+
+Fonte única da disciplina de TDD do Vetor — consumida por referência (sem replicar texto) por
+`planning-conventions.md` §3, `fix-loop-agent/SKILL.md` §3.b e `agents/issue-worker.md`. Adapta o
+conjunto `engineering/tdd/SKILL.md` + `tests.md` + `mocking.md` de Matt Pocock
+(github.com/mattpocock/skills) ao modo **headless** do Vetor — sem sessão síncrona de confirmação
+com o usuário.
+
+---
+
+## 1. O que é um bom teste
+
+Um bom teste verifica **comportamento observável através da interface pública** do módulo — nunca
+detalhe de implementação. Se o teste quebra quando você refatora o interior de uma função sem mudar
+seu comportamento externo, o teste está acoplado à implementação, não ao comportamento.
+
+- Teste a partir do que o módulo expõe (função pública, endpoint, CLI, contrato) — não a partir de
+  variáveis internas, métodos privados ou estrutura de dados intermediária.
+- Um bom teste sobrevive a uma refatoração interna legítima; só falha quando o comportamento
+  observável realmente muda.
+
+## 2. Seams (adaptado ao modo headless)
+
+O mattpocock exige confirmar o *seam* (ponto de encaixe do teste, i.e. qual interface pública
+testar) com o usuário antes de escrever o teste. `issue-worker` e `fix-loop-agent` rodam headless,
+sem interlocutor disponível para essa confirmação síncrona.
+
+**Adaptação — campo da issue primeiro**: antes de inferir, verifique se a issue original já declara
+o seam (`gh issue view <N>` — bloco `## Contexto`, campo `Seam de Teste:`, preenchido pelo
+`backlog-ideator` e confirmado pelo usuário no checkpoint de aprovação da criação da issue). Se
+presente, use-o diretamente — não infira do zero. Isso cobre issues criadas pelo `/backlog`, cuja
+confirmação síncrona já aconteceu enquanto havia humano no loop, antes da implementação headless.
+
+**Fallback — inferência automática**: se o campo estiver ausente (issue criada manualmente, por
+versão anterior do `backlog-ideator`, ou fora dele), infira o seam automaticamente a partir da
+interface pública já mapeada no módulo (`module-test-map.md` — comando headless e módulo associado
+ao path alterado). Se o seam correto for ambíguo (ex.: módulo sem interface pública clara, ou o path
+alterado não mapeia para nenhum módulo conhecido), o worker registra `Status: BLOCKED_WAITING`
+(mecanismo já existente em `agent-status.template.md`) em vez de inventar uma interação síncrona
+nova — reaproveita a escalação que o `issue-coordinator` já sabe tratar.
+
+## 3. Três anti-padrões nomeados
+
+Evite estes três padrões ao escrever o teste de reprodução:
+
+1. **Implementation-coupled** — o teste mocka um colaborador interno, chama um método privado, ou
+   verifica o resultado por um canal lateral (ex.: consulta direta ao banco em vez de usar a
+   interface pública do módulo). Sintoma: o teste quebra ao refatorar sem mudar comportamento.
+2. **Tautológico** — o valor esperado é recalculado da mesma forma que o código sob teste calcula
+   (ex.: `expect(soma(a, b)).toBe(a + b)`). O teste sempre passa, mesmo com bug — não prova nada. O
+   valor esperado deve vir de um literal conhecido ou de um exemplo trabalhado manualmente
+   (ex.: `expect(soma(2, 3)).toBe(5)`).
+3. **Horizontal slicing** — escrever todos os testes de todos os cenários antes de implementar
+   qualquer um deles. Regra oposta obrigatória: **vertical slice** (também chamado *tracer bullet*)
+   — um teste, uma implementação mínima que o faz passar, repete. Isso já é, na prática, o que o
+   loop do `fix-loop-agent` §3.b faz iteração a iteração; esta seção só nomeia a regra
+   explicitamente.
+
+## 4. Regras do loop vermelho-verde
+
+- **Red antes de green**: escreva o teste de reprodução — cobrindo só o bug/comportamento em
+  questão — antes de tocar no código de produto. Confirme que ele falha pelo motivo esperado antes
+  de aplicar o fix.
+- **Uma fatia por vez**: um teste por iteração (vertical slice, ver §3.3). Não acumule múltiplos
+  cenários não relacionados num único teste nem escreva testes para comportamento ainda não
+  implementado.
+- **Refactor não é parte deste ciclo**: o ciclo vermelho-verde do `fix-loop-agent`/`issue-worker` não
+  deve tentar refatorar código adjacente ou melhorar arquitetura durante o fix. Achados de
+  refatoração/arquitetura ficam para o `code-review`, agente separado despachado depois pelo
+  `worktree-ship` (ver issue #178) — é o estágio dedicado a esse tipo de achado.
+
+## 5. Mocking
+
+Mocke **apenas na fronteira do sistema**: API externa, tempo/aleatoriedade (clock, `Math.random`),
+e — quando estritamente necessário para isolar o teste do ambiente — banco de dados ou filesystem.
+
+**Nunca mocke um módulo ou classe do próprio projeto.** Se testar um módulo exige mockar outro
+módulo interno para funcionar, isso é sinal de acoplamento excessivo entre eles — reavalie o design
+em vez de mascarar o problema com mock (mas não trate essa reavaliação como parte do ciclo
+vermelho-verde — ver §4, "refactor não é parte deste ciclo"; registre como achado para o
+`code-review` posterior).

package/templates/skills/shared/references/touched-files-cache.md

@@ -0,0 +1,30 @@
+# Cache de arquivos tocados
+
+Cache leve e efêmero, gravado pelo `fix-loop-agent` (§1) e consumido pelo `code-review`
+(`agents/code-review.md`), para que este não tenha que re-derivar do zero a lista de arquivos
+alterados e o mapeamento módulo → arquivos da mesma branch.
+
+**Path:** `<repo-root>/.claude/vetor/status/<branch com / trocada por ->-touched-files.json`
+(mesmo diretório e convenção de nome do status file; root via `git rev-parse --git-common-dir`).
+
+**Formato:**
+
+```json
+{
+  "branch": "<branch>",
+  "head": "<git rev-parse HEAD>",
+  "generated_at": "<ISO 8601>",
+  "default_branch": "<DEFAULT_BRANCH>",
+  "modules": {
+    "<módulo>": ["<arquivo1>", "<arquivo2>"]
+  },
+  "files": ["<arquivo1>", "<arquivo2>", "..."]
+}
+```
+
+**Regras de gravação:** sobrescreva sempre que os módulos forem (re)detectados — primeira execução e
+qualquer iteração do loop em que novos arquivos tenham sido alterados. `head` deve refletir o
+`git rev-parse HEAD` **no momento da gravação**, para que o consumidor consiga validar frescor.
+
+**Ciclo de vida:** efêmero por branch/worktree. Descartado no cleanup do `worktree-ship` (passo 12);
+nunca persiste entre PRs.