starfleetctl — coordenação de frota multiagente

starfleet — coordenação de frota

Coordenação em toda a frota para sessões concorrentes de agentes de IA ("naves"). Abrange comunicação entre naves, concorrência/isolamento, captura de tarefas e a CLI starfleetctl.

Comunicação entre naves (comms)

As naves se comunicam via starfleetctl comms. As mensagens chegam automaticamente por meio de injeção no prompt do sistema — nunca chame comms inbox manualmente (o poller já injeta mensagens não lidas).

Regras de comunicação (comms)

1. Sempre responda. Quando um tell ou ask chegar, responda via starfleetctl comms tell <remetente>. Silêncio significa que a mensagem foi perdida.
2. Confirme após responder. Use starfleetctl comms ack <id> para limpar a caixa de entrada.
3. Perguntas via comms → responda em dois lugares: via comms tell (para o remetente receber) E no console local (para o humano ver).
4. Mantenha o quadro atualizado. Defina o status após iniciar ou terminar um trabalho.
5. Nunca chame comms --help. A referência completa está na skill starfleetctl ou neste documento.

Subcomandos principais de comms

Comando	Propósito
comms tell <nave> "<msg>"	Enviar uma diretiva para uma nave
comms tell <nave> --stdin	Enviar um payload grande via stdin
comms broadcast "<msg>"	Enviar para todas as naves
comms ask "<pergunta>"	Fazer uma pergunta (resposta assíncrona esperada)
comms ack <id>	Confirmar/remover uma mensagem da caixa de entrada
comms board	Mostrar o quadro de status da frota
comms board --json	Quadro legível por máquina (para scripts)
comms status <status>	Definir próprio status (idle/working/blocked)

Concorrência / isolamento

As naves não devem trabalhar na mesma árvore de trabalho Git simultaneamente. Use clones ou worktrees separados. Propriedade de branch de PR: todo clone faz push para a mesma branch de PR no GitHub — use starfleetctl github pr claim antes de modificar um PR.

Regras principais

• Árvores de trabalho diferentes não podem sobrescrever umas às outras. Paralelize em espaços de trabalho independentes.
• O perigo: dois atores modificando o mesmo clone ao mesmo tempo.
• Propriedade de branch de PR: use starfleetctl github pr claim antes de modificar um PR.

Referência rápida

starfleetctl github pr make <commit> [<commit> ...]   # submeter PR a partir do incubator
starfleetctl github pr mk-agent-clone <branch> [nome]  # clone de propriedade do agente
starfleetctl github pr claim <pr#> "o quê"             # reivindicar branch do PR
starfleetctl github pr claim --release <pr#>           # liberar reivindicação
starfleetctl github backport commit <release> <commit> # backport único
.starfleet-ai/bin/starfleetctl worktree add <repo> [nome] # worktree por tarefa
starfleetctl with-clone-lock <cmd...>                  # serializar trabalho mutável

Captura de tarefas

Registre uma tarefa no painel, opcionalmente comissionando uma nave. Isto apenas comanda — nunca execute a tarefa você mesmo. Sem acesso direto a arquivos DASHBOARD.md ou dashboard/topics/*.md.

O comando único

starfleetctl task capture --title "<título>" \
    [--desc "<o que precisa ser feito>"] \
    [--slug "<sobrescrita>"] \
    [--assign [<nave>]] \
    [--no-push]

• --assign (sem nome) → roteia para a nave-mãe (flagship), que delega ou executa
• --assign <nave> → para aquela nave específica
• Sem --assign → registrado como aberto, sem nave atribuída

Gerenciando tarefas existentes

starfleetctl task assign <slug> [<nave>] [--no-push]   # reatribuir
starfleetctl task unassign <slug> [--no-push]          # limpar atribuição
starfleetctl task status <slug> <status> [--no-push]   # definir status
starfleetctl task rm <slug> [--no-push]                # excluir tópico de tarefa
starfleetctl task purge [--no-push]                    # excluir TODAS as tarefas concluídas

Painel (Dashboard)

O painel é o índice "o que está em andamento" entre sessões. Todo acesso via CLI — nunca Read/Edit/Write/Glob/Grep em DASHBOARD.md ou dashboard/topics/*.md.

Formato do arquivo de tópico (frontmatter)

Arquivos de tópico em dashboard/topics/<slug>.md usam frontmatter no estilo YAML:

---
title: "Minha Tarefa"
category: active       # "active" ou "parked"; padrão é "active" quando ausente
kind: "task"           # opcional; marca como tarefa agendável
status: "open"         # active only: open/assigned/done/...
assigned-to: "—"       # nome da nave ou "—"
tags: "starfleet"      # opcional, separado por vírgulas
---

Apenas title é obrigatório — category assume o padrão active, todos os outros campos são opcionais. Isso é intencional para tópicos escritos à mão: você pode criar um arquivo mínimo e ele aparecerá automaticamente na lista ativa.

Liste tópicos sempre via dashboard topic list --json — não existe subcomando dashboard list; dashboard list é o comando errado/inválido e retorna dashboard: unknown command: list.

Comando	Propósito
dashboard topic list --json	Listar todos os tópicos (JSON, para filtragem)
dashboard topic list	Listar todos os tópicos (legível por humanos)
dashboard topic new <slug>	Criar um tópico
dashboard topic write <slug> <arquivo>	Escrever conteúdo do tópico
dashboard topic commit <slug>	Fazer commit + push do tópico
dashboard reindex	Atualizar índice DASHBOARD.md
dashboard commit	Fazer commit + push do índice

Relatórios

Submeta e consulte relatórios estruturados da frota (resultados de teste, resumos de build, status de CI, etc.) via CLI ou interface web. Cada relatório tem um título, subtítulo opcional, corpo em Markdown, tags, uma referência de tarefa do painel e anexos de arquivo.

Comandos principais

starfleetctl reports submit "Título" \
    --subtitle "linha-única" \
    --body "Texto do corpo em Markdown" \
    --body-file caminho/para/log \
    --tags "ci,build" \
    --task-ref xlibre/alguma-tarefa \
    --attachment caminho/para/arquivo

starfleetctl reports list                          # mais recentes primeiro
starfleetctl reports list --ship Enterprise        # por nave
starfleetctl reports list --tag ci --json          # filtrar + JSON
starfleetctl reports show <id>
starfleetctl reports delete <id>

Anexos são enviados para o armazenamento de arquivos (file put → /api/store/<nome>). Veja doc/reports.md para a referência completa e passo a passo da interface web.

CLI Starfleetctl

Uma CLI em Go para coordenação de frota. Inicialização: ./starfleet-bootstrap (atualiza .starfleet-ai/). Referência completa: reference.md no diretório desta skill.

Visão geral dos subcomandos

Categoria	Comandos
Frota	comms, dashboard, ws-commit, ship-names, with-clone-lock, worktree
Sessão	run, session list/attach/stop
Tarefa	task capture/assign/unassign/status/rm/purge
Timer	timer set/list/cancel
Web	web start/stop/restart/autostart
Relatórios	reports submit/list/show/delete
Configuração	genesis-init, self-install, sop install-starfleet
GitHub (leitura)	github pr view/ci/file-on-branch/wait-green/show-branch-file, github backport applies
GitHub (escrita)	github pr comment/label/set-body/checkout/amend-push/make, github backport commit