@tavaressan/vetor 0.1.0

package/templates/skills/vetor/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: vetor
+description: Porta de entrada do plugin. Inicializa e configura o ambiente do Vetor no projeto-alvo (mapeamento de testes e arquivos de configuração).
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.0.0"
+---
+
+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 [--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`)").
+
+---
+
+## 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;
+- `.claude/vetor/config.json` — `runtime`, `packageManager` e `testCommand` detectados, preservando
+  o `maxConcurrentWorkers` (default 5), o bloco `knowledge` (`enabled`/`provider`) e o bloco opcional
+  `delegation` (`preferredRuntime` — ver `delegate-to-runtime.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 -->`
+e o substitui; se o bloco ainda não existir, insere no fim do arquivo; se o arquivo não existir, não
+faz nada — **nunca crie `CLAUDE.md`/`AGENTS.md` do zero**, isso é convenção de onboarding do
+projeto-alvo, não algo que o Vetor deva opinar. Rodar `/vetor` de novo é idempotente: o bloco é
+atualizado no lugar, sem duplicar e sem exigir `--force`.
+
+O conteúdo do bloco é fixo e definido em uma única fonte — a constante `CAPABILITIES_BODY` em
+`scripts/inject-capabilities-doc.ts` — para não divergir entre execuções nem exigir que o agente
+redija prosa a cada `/vetor`. É um resumo sucinto (não duplica o conteúdo completo dos `SKILL.md`):
+título curto, lista das skills/agentes com o comando de invocação e, entre parênteses, o nome do
+agente/skill correspondente. Se novas skills forem adicionadas ao plugin, atualize a constante — não
+gere a lista ad hoc na hora de rodar `/vetor`.
+
+### 3 — Exibir Sumário de Configuração e Próximos Passos
+
+Após a criação/validação dos arquivos, exiba uma mensagem informativa clara e amigável para o desenvolvedor:
+
+```
+🚀 Vetor inicializado com sucesso!
+
+Runtime detectado: <runtime> (<testCommand>)
+
+Knowledge: <label do campo `knowledge` no JSON de saída — ex.: "✓ Filesystem", "✓ Obsidian" ou "○ Disabled">
+
+Arquivos configurados:
+- [x] .claude/vetor/module-test-map.md (Mapeamento de testes por módulo)
+- [x] .claude/vetor/config.json (runtime detectado + maxConcurrentWorkers: 5)
+- [x] .claude/vetor/status/ (status files dos workers — gitignorado)
+- [x] .claude/rules/vetor/<runtime>.md (convenções do projeto, carregadas sob demanda)
+- [<x ou ->] CLAUDE.md — bloco de capacidades <inserido | atualizado | não encontrado (arquivo ausente)>
+- [<x ou ->] AGENTS.md — bloco de capacidades <inserido | atualizado | não encontrado (arquivo ausente)>
+
+Próximos passos recomendados:
+1. Abra e revise o arquivo `.claude/vetor/module-test-map.md` para garantir que os comandos de teste headless e os mapeamentos de pasta de seu projeto estejam 100% corretos.
+2. Revise e **commite** `.claude/rules/vetor/`. Os issue-workers rodam em worktrees, que só contêm arquivos rastreados pelo git — uma rule não commitada não chega até eles.
+3. (Opcional) Crie a pasta `.claude/vetor/docs/` e adicione guias de arquitetura, padrões do projeto e gaps em markdown. O comando `/vetor:backlog` lerá automaticamente estes arquivos para propor issues altamente contextualizadas.
+4. (Opcional) Rode `/vetor:stack-practices` para gerar regras de melhores práticas da stack detectada (via Context7).
+```
+
+Se o script pulou algum arquivo por já existir, diga qual — e que só `--force` o sobrescreve. Reporte
+também o resultado do passo 2.b: se o bloco de capacidades foi inserido, atualizado, ou se nenhum
+`CLAUDE.md`/`AGENTS.md` foi encontrado na raiz (nesse caso, nenhuma ação foi tomada).
+
+---
+
+## Restrições
+
+- Nunca execute ações destrutivas em arquivos de configuração existentes sem a flag `--force`
+- Nunca altere códigos de negócio ou arquivos fora de `.claude/vetor/` e `.claude/rules/vetor/`
+- Nunca escreva em `.claude/rules/` fora do subdiretório `vetor/` — esse espaço é do usuário

package/templates/skills/worktree-create/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: worktree-create
+description: Criação headless de worktree — sem prompts interativos, todos os parâmetros via args. Primitivo usado pelo issue-coordinator e disponível como slash command standalone.
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.0.0"
+---
+
+Você é o primitivo de criação de worktree do Vetor. Sua única responsabilidade é criar um worktree Git isolado de forma determinística, sem perguntas ao usuário.
+
+---
+
+## Sintaxe
+
+```
+/vetor:worktree-create <type> <slug> [issue#]
+```
+
+- `<type>`: obrigatório — um de `feat`, `fix`, `chore`, `refactor`
+- `<slug>`: obrigatório — kebab-case, máximo 30 caracteres (ex.: `embedding-retry`, `auth-refresh`)
+- `[issue#]`: opcional — número inteiro da issue GitHub
+
+---
+
+## Comportamento
+
+### 1 — Validação de args
+
+Verifique os argumentos recebidos usando o script determinístico:
+
+```bash
+scripts/vetor-checks.sh validate-issue-ref "$issue_ref" || exit 1
+```
+
+Valide também:
+
+- Se `<type>` não for um dos valores aceitos (`feat`, `fix`, `chore`, `refactor`):
+  ```
+  ERRO: tipo inválido "<type>". Valores aceitos: feat, fix, chore, refactor
+  ```
+  Aborte.
+
+- Se `<slug>` não for kebab-case ou tiver mais de 30 caracteres:
+  ```
+  ERRO: slug inválido "<slug>". Use kebab-case com no máximo 30 caracteres.
+  ```
+  Aborte.
+
+### 2 — Derivar nomes
+
+Detecte a branch default do repositório: leia `../shared/references/project-conventions.md` e resolva `$DEFAULT_BRANCH` conforme descrito lá (não assuma `master`).
+
+- **Branch:** `<type>/<issue#>-<slug>` se issue fornecida; `<type>/<slug>` caso contrário
+- **Path:** `.claude/worktrees/<slug>`
+
+### 3 — Verificar conflitos
+
+Antes de criar, verifique se a branch ou o worktree já existem:
+
+```bash
+git branch --list "<branch>"
+git worktree list | grep "<slug>"
+```
+
+Se qualquer um já existir:
+```
+ERRO: branch "<branch>" ou worktree ".claude/worktrees/<slug>" já existe.
+Use outro slug ou remova o worktree existente com:
+  git worktree remove .claude/worktrees/<slug>
+  git branch -d <branch>
+```
+**Aborte.** Nunca entre silenciosamente em um worktree existente.
+
+### 4 — Criar worktree
+
+Execute em sequência:
+
+```bash
+git pull origin "$DEFAULT_BRANCH"
+
+git worktree add -b <branch> .claude/worktrees/<slug> "$DEFAULT_BRANCH"
+```
+
+Se `git pull` falhar (ex.: rede indisponível), continue com a branch default local e avise:
+```
+AVISO: git pull falhou — criando worktree a partir da <default-branch> local.
+```
+
+Se `git worktree add` falhar, reporte o erro e aborte.
+
+### 4.b — Preparar dependências
+
+Delegue ao script determinístico — ele detecta o runtime e faz o que couber (Deno puro é no-op,
+pois o cache `$DENO_DIR` já é global; Node ganha um link para o `node_modules` da raiz):
+
+> O path relativo abaixo resolve 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 — 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.
+
+```bash
+deno run -A "$SKILL_DIR/../../scripts/prepare-worktree.ts" --path .claude/worktrees/<slug>
+```
+
+O script é tolerante a falhas: avisa em stderr e sai com 0 mesmo se a preparação falhar. Prossiga
+normalmente — o worker instala o que faltar.
+
+> No fluxo do `issue-coordinator`, o worktree é criado pelo harness (`isolation: "worktree"`) e a
+> preparação roda sozinha via hook `WorktreeCreate`. Esta chamada só é necessária aqui, no uso
+> standalone do skill.
+
+### 5 — Entrar no worktree
+
+Use a ferramenta `EnterWorktree` com o path `.claude/worktrees/<slug>` para mudar o contexto de trabalho.
+
+### 6 — Saída
+
+Após criar e entrar no worktree com sucesso, imprima:
+
+```json
+{"branch": "<branch>", "path": ".claude/worktrees/<slug>", "issue": <N|null>}
+```
+
+E informe:
+```
+Worktree criado e ativado.
+Branch: <branch>
+Path: .claude/worktrees/<slug>
+```
+
+---
+
+## Restrições
+
+- Nunca faça perguntas ao usuário — todos os parâmetros vêm dos args
+- Nunca entre em um worktree existente — sempre aborte com erro se houver conflito
+- Nunca faça push ou crie PR — isso é responsabilidade do `worktree-ship`
+- Se invocado como primitivo por outro skill (ex.: `issue-coordinator`), o `EnterWorktree` afeta apenas a sessão local do invocador