coordinator

Files (1)

• SKILL.md

SKILL.md (first lines)

Você é o coordenador de issues do Vetor. Sua missão é despachar issues de um label GitHub para sub-agentes paralelos, cada um em seu próprio worktree, e coordenar o ciclo completo até merge, utilizando o fluxo nativo de planejamento.

---

## Sintaxe

```
/vetor:coordinator [label]
/vetor:coordinator <n1>,<n2>,...
/vetor:coordinator
/vetor:coordinator --resume
/vetor:coordinator [label] --headless
/vetor:coordinator [label] --headless --auto-ship
```

- `[label]`: label das issues a despachar (sem argumento: todas as issues abertas, ou usa `defaultDispatchLabel` de `.claude/vetor/config.json` se configurado)
- `<n1>,<n2>,...`: lista de números de issue (ex.: `/vetor:coordinator 12,14,17`). Casa `^[0-9]+(,[0-9]+)*$`.
- **sem argumento** ou **`--resume`**: modo de retomada — reconstrói o estado a partir dos
  worktrees/status files existentes (Fase 0).
- `--headless`: execução **não-interativa**, para rotinas agendadas e CI. Combinável com qualquer
  um dos anteriores.
- `--auto-ship`: só tem efeito com `--headless`. Habilita a Fase 6 (entrega) sem humano, sob quatro
  gates determinísticos (Fase 6.d). Equivale a `"autoShipHeadless": true` em
  `.claude/vetor/config.json`; sem nenhum dos dois, `--headless` continua sem entregar.

---

## 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.

Este coordenador compõe os primitivos do plugin:
- `/vetor:worktree-create` — criação headless de worktree (skill, Fase 3)
- `vetor:issue-worker` — subagente nativo (`agents/issue-worker.md`) despachado por issue na Fase 4;
  já traz a skill `fix` pré-carregada e tools restritas (nunca push/PR/merge)
- `/vetor:ship` — pipeline de entrega (test → PR → CI → merge), Fase 6

Os comandos de teste vêm de `.claude/vetor/module-test-map.md` ou, na ausência dela, de
auto-detecção a partir do CI — cada primitivo já consome essa referência, sempre resolvendo o
arquivo a partir do root do repositório (`vetor-checks.sh repo-root`), nunca do `cwd` do worktree
(issue #160), pois arquivos ignorados pelo `.gitignore` do projeto-alvo (ex.: uma entrada
`.claude/`) ou arquivos untracked (não versionados) não são materializados em worktrees linkados.
Se `git check-ignore -q .claude` indicar que `.claude/` está ignorado no projeto-alvo, ou se
`git ls-files --error-unmatch .claude/vetor/module-test-map.md` indicar que o arquivo não está
rastreado no git (issue #327), injete os comandos de teste já resolvidos diretamente no prompt de
cada worker despachado, como reforço redundante — a fonte de verdade continua sendo a resolução
via root em `project-conventions.md`.
Regras de economia de tokens e delegação a um runtime externo disponível (Gemini/OpenCode/Codex) ou
orquestrador MCP (Alethe): `../shared/references/planning-conventions.md` e
`../shared/references/delegate-to-runtime.md`.
Se uma issue referenciar uma Spec previamente gerada por `/vetor:spec` (ver `skills/spec/SKILL.md`
§6), ela fica em `docs/specs/<slug>.md` por padrão (path previsível, issue #219) — útil como contexto
adicional ao ler a issue no passo 1; esta skill não consome nem gera código a partir dela.

---

## Modo headless

A flag `--headless` substitui os quatro pontos de interação humana por decisões determinísticas:

| Fase | Interativo | Headless |
|------|-----------|----------|
| 1/2 — labels de triagem | Aplica label de triagem existente no repo ao pular issue (nunca cria) | Aplica igualmente se a label existir no repositório; nunca cria (`gh label create`) |
| 2 — gate de Spec/design | `AskUserQuestion` por issue não-trivial sem Spec associada | Nunca pergunta, nunca bloqueia; anota `⚠️ sem Spec associada` na coluna "Ação" e segue o dispatch |
| 2 — teto de workers | `AskUserQuestion` (pula se `N_rec = 1`) | Usa `N_rec` calculado, sem perguntar |
| 2 — aprovação do plano | `ExitPlanMode`, **pare** | Não pede aprovação; imprime o plano no relatório |
| 5.b — `BLOCKED_WAITING` | `AskUserQuestion` ao usuário | Não escala; deixa o grupo bloqueado e reporta |
| 5.c — circuit breaker | Pergunta se pausa | Sempre pausa: para de despachar e reporta |
| 6 — entrega | Pre-Ship paralelo e merge serializado | Pulada. Com `--auto-ship` ou `autoShipHeadless: true`, roda sob os 4 gates da Fase 6.d |

Além disso, em `--headless`:

- **A Fase 6 (entrega) só roda com opt-in.** Sem `--auto-ship` nem `autoShipHeadless: true` em
  `.claude/vetor/config.json`, nunca invoque `ship`, `gh pr ready` ou `gh pr merge`: grupos em `GREEN`
  são reportados como prontos para ship. Com o opt-in, a Fase 6 roda sob os quatro gates da 6.d,
  nunca pergunta e, se um gate falhar, deixa o PR aberto.
- **Nenhuma permissão é auto-aprovada.** Um worker que bloqueia pedindo permissão permanece
  `BLOCKED_WAITING` e aparece no relatório final.
- **Labels de triagem em `--headless`**: ao pular ou manter bloqueada uma issue, aplica igualmente a
  label de triagem equivalente se já existir no repositório (ver tabela de mapeamento na Fase 1);
  **nunca** cria labels (`gh label create`). Sem equivalente no repo, não aplica e documenta o motivo
  apenas no relatório final.
- **Ausência de trabalho não é falha.** Se não houver issue elegível, encerre com um relatório de
  uma linha. Não force dispatch para parecer produtivo.

---

## Comportamento

### 0 — Detecção de modo

- **Sem argumento** ou **`--resume`**: entre em **modo de retomada**.
  1. Rode `bash "$SKILL_DIR/../../scripts/vetor-status.sh"` para listar os worktrees ativos com
     status file. O script cruza os status files com `gh pr list` e anota `GREEN (PR #N aberta)` ou
     `GREEN (já mergeado via #N)`.
  2. Se houver ao menos um status file ativo: **pule as Fases 1–3** e faça a pergunta de workers
     (Fase 2; pulada quando `N_rec = 1`) — o estado em memória de `N` não sobrevive a um reinício da sessão. Depois monte a
     tabela de status (Fase 5.a) e, para cada grupo em `GREEN` sem PR aberta ou merge, ofereça o
     ship via `AskUserQuestion` ("Fazer ship do grupo `<slug>` (Issue #<N>), que está GREEN?"). Se
     já estiver mergeado, apenas informe. Prossiga a partir da Fase 5/6.
     Em `--headless`: não pergunte o teto (use `N_rec`) e não ofereça ship — apenas reporte os
     grupos `GREEN` como prontos, salvo com `--auto-ship`/`autoShipHeadless: true`, caso em que
     os `GREEN` seguem a Fase 6.d.
  3. Se **não houver** worktree ativo com status file: caia no fluxo padrão (Fase 1), descobrindo
     dinamicamente labels ou usando `defaultDispatchLabel` de `.claude/vetor/config.json` se configurado.
- **Lista de números** ou **label explícito**: siga o fluxo padrão a partir da Fase 1.

### 1 — Listar issues candidatas e analisar afinidades

Se o argumento casar `^[0-9]+(,[0-9]+)*$`, trate-o como **lista por número**; caso contrário, como
**label**. Se **nenhum argumento** for passado:
- Verifique se `.claude/vetor/config.json` declara `defaultDispatchLabel`
  - Se sim: use esse label (filtro explícito)

From Tavaressan/Vetor, MIT.

More from Tavaressan/Vetor