install

Files (1)

• SKILL.md

SKILL.md (first lines)

Você é a skill de inicialização e configuração do Vetor. Sua missão é preparar o repositório-alvo para o uso do plugin, criando os diretórios e arquivos de configuração necessários caso não existam.

---

## Sintaxe

```
/vetor:install [--force]
```

- `--force`: opcional — força a sobrescrita do mapeamento de testes (`module-test-map.md`), do arquivo de
  configuração (`config.json`) e das rules geradas (`.claude/rules/vetor/`) mesmo que já existam.

---

## Referências

> Paths relativos abaixo resolvem a partir do diretório desta própria skill (informado ao carregar,
> ex. "Base directory for this skill: ..."), não do `cwd` de execução. Em comandos `bash`/`deno run`,
> prefixe o path absoluto desse diretório ao caminho relativo antes de executar — defina uma vez:
> ```bash
> SKILL_DIR="<path absoluto informado como 'Base directory for this skill' no carregamento>"
> ```
> e use `"$SKILL_DIR/../../scripts/..."` em todo comando abaixo, nunca o path relativo isolado.

- `../shared/references/mcp-availability.md` — se, durante o setup, for
  preciso explicar ou depurar comportamento do próprio Claude Code (hooks, slash commands,
  configuração de MCP, permissões, SDK de agentes), o MCP `claude-code-docs` é **obrigatório quando
  disponível** (ver "Documentação do próprio Claude Code (`claude-code-docs`)").
- `../shared/references/memory-gotchas.md` — regra de escopo do ai-memory (`.ai-memory.toml` com
  `workspace` e `project`) que o passo 2.c oferece scaffoldar.

---

## Comportamento

### 0 — Verificar pré-requisitos

O Vetor executa seus scripts com Deno. Confirme que ele está disponível:

```bash
deno --version
```

Se o comando falhar, **pare** e instrua a instalação — sem Deno, o hook de segurança e a preparação
de dependências dos worktrees não funcionam:
- macOS/Linux: `curl -fsSL https://deno.land/install.sh | sh`
- Windows: `winget install DenoLand.Deno`

### 1 — Garantir estrutura de diretórios

Crie os diretórios do Vetor no projeto-alvo e garanta que os status files dos workers
(escritos em `.claude/vetor/status/` — ver
`../shared/references/agent-status.template.md`) nunca sejam commitados:

```bash
mkdir -p .claude/vetor/status
grep -qxF '.claude/vetor/status/' .gitignore 2>/dev/null || echo '.claude/vetor/status/' >> .gitignore
```

A entrada no `.gitignore` é idempotente — este passo substitui qualquer ajuste de gitignore por
worker.

### 2 — Detectar o projeto (`module-test-map.md` + `config.json` + rules)

Um único script detecta o runtime, gera o mapeamento de testes, persiste a configuração e escreve as
rules de convenção do projeto:

```bash
deno run -A "$SKILL_DIR/../../scripts/detect-project.ts" [--force]
```

Repasse o `--force` recebido nos args. A guarda é **por arquivo**: sem `--force`, cada arquivo que já
existe é preservado (o JSON de saída informa o que foi criado e o que foi pulado).

O script grava:
- `.claude/vetor/module-test-map.md` — comandos de teste por módulo e mapeamento por prefixo de path. Quando a raiz possui runtime detectado, ela é sempre incluída como módulo (`./`). Subdiretórios ignorados pelo `.gitignore` (verificados via `git check-ignore`) nunca viram módulos falsos positivos. Em projetos Node sem script `test` no `package.json`, o comando é composto a partir dos scripts de validação presentes (ex.: `npm run lint && npm run build`) com anotação no mapa de ausência de suíte de testes dedicada; caso nenhum script sirva, grava `AJUSTE:` explícito em vez de um comando inválido;
- `.claude/vetor/config.json` — `runtime`, `packageManager` e `testCommand` detectados (incluindo o comando composto ou `AJUSTE:` em projetos Node sem script de teste), preservando
  o `maxConcurrentWorkers` (default 5), o bloco `knowledge` (`enabled`/`provider`) e o bloco opcional
  `delegation` (`preferredRuntime` — ver `delegate-to-runtime.md`) e o bloco opcional `hooks`
  (`typecheckOnEdit: true` liga o `tsc` a cada edição em projetos Node/TS — ver `wiki/Configuracao.md`),
  se já existirem. O
  `prepare-worktree.ts` lê isso para saber como preparar cada worktree;
- `.claude/rules/vetor/<runtime>.md` — convenções do projeto (comando de teste, formatador, lint,
  estilo de import), com frontmatter `paths` para entrarem em contexto **apenas** quando o agente lê
  um arquivo daquele tipo. Só há rules para projetos Deno e Node; nos demais runtimes o script não
  gera nenhuma.

Cada linha de uma rule corresponde a um fato lido do repositório (`deno.json`, `package.json`,
arquivos de config). O que não foi detectado não vira regra.

Se o runtime sair como `unknown`, avise o usuário de que o `module-test-map.md` precisa de ajuste
manual — as skills de teste dependem dele.

O JSON de saída inclui um campo `knowledge` (`{"status": ..., "label": ...}`) com o estado do
**Knowledge Provider** — ver `../shared/references/knowledge-provider-contract.md`.
Ausência do bloco `knowledge` em `config.json` (ou de `config.json` inteiro) nunca é erro: o default é
`✓ Filesystem`, sempre funcional sem configuração adicional. Só vira `○ Disabled` com
`knowledge.enabled: false` explícito, e `✓ Obsidian` com `knowledge.provider: "obsidian"` explícito.

Ausência do bloco `delegation` também nunca é erro: sem `delegation.preferredRuntime` configurado,
a seleção do runtime de delegação (Gemini/OpenCode/Codex) segue puramente por disponibilidade no
PATH e, se ambígua (2+ candidatos), por anuência explícita — ver algoritmo completo em
`delegate-to-runtime.md` §2.

### 2.b — Inserir/atualizar resumo de capacidades em CLAUDE.md/AGENTS.md

`CLAUDE.md`/`AGENTS.md` são os arquivos que agentes de código carregam automaticamente no início de
uma sessão — diferente de `.claude/rules/vetor/`, que só entra em contexto sob demanda. Um
desenvolvedor (ou agente) que abre esses arquivos deve ficar sabendo, sem já conhecer o Vetor de
antemão, que o plugin está instalado e como invocar suas skills/agentes.

Para cada um de `CLAUDE.md` e `AGENTS.md` que já exista na raiz do projeto-alvo, rode:

```bash
deno run -A "$SKILL_DIR/../../scripts/inject-capabilities-doc.ts" <caminho-do-arquivo>
```

O script acha o bloco delimitado por `<!-- vetor:capabilities:start -->` / `<!-- vetor:capabilities:end -->`

From Tavaressan/Vetor, MIT.

More from Tavaressan/Vetor