---
name: prepare-harness
description: Pré-configura o harness para clone-and-go. Use no primeiro setup (ou quando faltam repos na workspace) — checa pré-requisitos, instala/habilita os plugins do Claude Code, projeta e pré-aprova os MCP servers, e clona cada repo git listado em workspace/repos.md (idempotente: pula os já clonados, dá fast-forward pull nos existentes).
allowed-tools: [read, grep, glob, exec]
triggers:
  user: ["/prepare-harness", "/preparar-harness"]
  model: ["preparar o harness", "primeiro setup do harness", "clonar os repos da workspace", "faltam repos na workspace"]
---
# prepare-harness

> Template agnóstico de org/host. Liste seus repositórios em `workspace/repos.md`
> (qualquer URL git — SSH ou HTTPS) e rode a skill.

## Quando usar
- Logo após clonar este harness (setup inicial / onboarding).
- Quando algum repo esperado não está em `workspace/`.
- Depois de adicionar uma nova entrada em `workspace/repos.md`.

## O que faz
1. Valida pré-requisitos do ambiente.
2. (Opcional) Sincroniza as projeções do harness com `./bin/harness sync`.
3. **Instala/habilita os plugins do Claude Code** declarados em `catalog/plugins/plugins.json`
   via o `claude plugin` CLI (adiciona o marketplace + `claude plugin install <plugin>@<marketplace>`).
   Idempotente: pula os já instalados, desabilita os marcados `enabled:false`. Se o `claude`
   CLI não estiver no PATH, esta etapa é pulada (o `.claude/settings.json` projetado por
   `harness sync` assume a instalação no próximo start).
4. **Projeta a config de MCP** gerando o `./.mcp.json` a partir de `mcp/servers.json` (só os
   servers `enabled`) — é o arquivo que o Claude Code carrega como MCP **project-scope** ao
   abrir este harness. Também grava `enabledMcpjsonServers` no `.claude/settings.json` para
   **pré-aprovar** esses servers e evitar o prompt manual de "trust". Idempotente.
5. Lê o registro `workspace/repos.md`.
6. Para cada URL git (SSH `git@host:org/repo.git` ou HTTPS `https://host/org/repo`), **clona
   em `workspace/<repo>`** se ainda não existir; se já existir, faz `git pull --ff-only`.

Os clones ficam fora do versionamento deste harness (ver `.gitignore`).

## Como executar
Rode o script idempotente a partir da raiz do harness:

```bash
bash catalog/skills/prepare-harness/scripts/prepare-harness.sh
```

Flags úteis:
- `--sync` — roda `./bin/harness sync` antes de clonar.
- `--no-pull` — não atualiza repos já clonados, só clona os que faltam.
- `--no-plugins` — não instala/habilita os plugins do Claude Code.
- `--no-mcp` — não regenera o `./.mcp.json` (config de MCP project-scope).

## Pré-requisitos
- `git` instalado.
- Acesso aos repositórios listados (chave SSH ou credencial HTTPS). Para repos **privados de
  GitHub**, o `gh` (GitHub CLI) autenticado é usado como fallback — se precisar:
  `! gh auth login`.
- `python3` (já usado pelos renderers do harness) — lê o registro e gera as projeções.
- `claude` CLI no PATH (opcional) — só necessário para instalar os plugins; sem ele a etapa
  de plugins é pulada sem falhar.

## Passos (fallback manual, se o script não puder rodar)
1. Liste as URLs git em `workspace/repos.md`.
2. Para cada `<url>`: derive `<repo>` do final da URL (sem `.git`); se `workspace/<repo>/.git`
   não existe, `git clone <url> workspace/<repo>`.

## Notas sobre MCP
- **Definição** dos servers vai no `./.mcp.json` (raiz do repo) — é o único lugar de onde o
  Claude Code lê MCP project-scope, **não** `.claude/.mcp.json`. A **aprovação** vai no
  `.claude/settings.json` (`enabledMcpjsonServers`), também gerada pela skill.
- A sessão lê esses arquivos **no início**. Se você rodar a skill com o Claude Code já aberto
  neste projeto, **reinicie a sessão** (ou rode `/mcp`) para ele detectar.
- Servers HTTP remotos com OAuth (ex.: Linear) pedem **autenticação** na 1ª conexão
  (`/mcp` → authenticate). Servers stdio que dependem de env (ex.: GitHub via
  `GITHUB_PERSONAL_ACCESS_TOKEN`) só funcionam com a variável setada localmente.
- Fonte canônica: `mcp/servers.json` (marque `enabled: true/false`). Credenciais/tokens ficam
  **locais** (env / `*.local.json`), nunca no repo.

## Saída
Resumo: quais plugins foram instalados/habilitados, quais MCP servers ficaram no `./.mcp.json`,
quais repos foram clonados, quais já existiam (e foram atualizados), e quaisquer falhas de
acesso (repo privado sem permissão, auth, plugin com nome inválido, etc.).