mpbt-hq/starfleetctl

starfleet — coordinación de flota

Coordinación en toda la flota para sesiones concurrentes de agentes de IA ("naves"). Cubre comunicación entre naves, concurrencia/aislamiento, captura de tareas y la CLI starfleetctl.

Comunicación entre naves (comms)

Las naves se comunican a través de starfleetctl comms. Los mensajes llegan automáticamente mediante inyección de prompt del sistema — nunca llames a comms inbox manualmente (el poller ya inyecta los mensajes no vistos).

Reglas de comunicaciones

1. Siempre responde. Cuando llega un tell o ask, responde mediante starfleetctl comms tell <remitente>. El silencio significa que el mensaje se perdió.
2. Acuse de recibo después de responder. starfleetctl comms ack <id> para eliminar de la bandeja de entrada.
3. Preguntas de comunicaciones → responde en dos lugares: a través de comms tell (para que el remitente lo reciba) Y en la consola local (para que el humano lo vea).
4. Mantén el tablero actualizado. Establece el estado después de comenzar o terminar el trabajo.
5. Nunca llames a comms --help. La referencia completa está en la habilidad starfleetctl o en este documento.

Subcomandos clave de comunicaciones

Comando	Propósito
comms tell <nave> "<msg>"	Enviar una directiva a una nave
comms tell <nave> --stdin	Enviar un payload grande a través de stdin
comms broadcast "<msg>"	Enviar a todas las naves
comms ask "<pregunta>"	Hacer una pregunta (se espera respuesta asíncrona)
comms ack <id>	Acusar recibo/eliminar un mensaje de la bandeja de entrada
comms board	Mostrar el tablero de estado de la flota
comms board --json	Tablero legible por máquina (para scripts)
comms status <estado>	Establecer el propio estado (idle/working/blocked)

Concurrencia / aislamiento

Las naves no deben trabajar en el mismo árbol de trabajo de git simultáneamente. Utiliza clones separados o worktrees. Propiedad de rama PR: cada clon empuja a la misma rama de PR de GitHub — usa starfleetctl github pr claim antes de mutar un PR.

Reglas clave

• Diferentes árboles de trabajo no pueden sobrescribirse entre sí. Paralelizar en espacios de trabajo independientes.
• El peligro: dos actores mutando el mismo clon a la vez.
• Propiedad de rama PR: Usa starfleetctl github pr claim antes de mutar un PR.

Referencia rápida

starfleetctl github pr make <commit> [<commit> ...]   # enviar PR desde incubator
starfleetctl github pr mk-agent-clone <branch> [name] # clon propiedad del agente
starfleetctl github pr claim <pr#> "qué"              # reclamar rama PR
starfleetctl github pr claim --release <pr#>           # liberar reclamo
starfleetctl github backport commit <release> <commit> # backport único
.starfleet-ai/bin/starfleetctl worktree add <repo> [name] # worktree por tarea
starfleetctl with-clone-lock <cmd...>                  # serializar trabajo de mutación

Captura de tareas

Registrar una tarea en el panel de control, opcionalmente comisionar una nave. Esto solo comanda — nunca ejecutes la tarea tú mismo. Sin acceso directo a archivos a DASHBOARD.md o dashboard/topics/*.md.

El comando único

starfleetctl task capture --title "<título>" \
    [--desc "<lo que hay que hacer>"] \
    [--slug "<sobrescribir>"] \
    [--assign [<nave>]] \
    [--no-push]

• --assign (sin nombre) → se enruta a la nave insignia, que lo delega o ejecuta
• --assign <nave> → esa nave específica
• Sin --assign → registrado como abierto, sin nave

Gestión de tareas existentes

starfleetctl task assign <slug> [<nave>] [--no-push]   # reasignar
starfleetctl task unassign <slug> [--no-push]          # limpiar asignación
starfleetctl task status <slug> <estado> [--no-push]   # establecer estado
starfleetctl task rm <slug> [--no-push]                # eliminar un tema de tarea
starfleetctl task purge [--no-push]                    # eliminar TODAS las tareas hechas

Panel de control

El panel de control es el índice "qué está en vuelo" entre sesiones. Todo el acceso a través de la CLI — nunca Read/Edit/Write/Glob/Grep en DASHBOARD.md o dashboard/topics/*.md.

Formato de archivo de tema (frontmatter)

Los archivos de tema en dashboard/topics/<slug>.md usan frontmatter estilo YAML:

---
title: "Mi Tarea"
category: active       # "active" o "parked"; por defecto "active" cuando falta
kind: "task"           # opcional; lo marca como una tarea programable
status: "open"         # solo activo: open/assigned/done/...
assigned-to: "—"       # nombre de nave o "—"
tags: "starfleet"      # opcional, separado por comas
---

Solo title es obligatorio — category por defecto es active, todos los demás campos son opcionales. Esto es intencional para temas escritos a mano: puedes agregar un archivo mínimo y aparece automáticamente en la lista activa.

Enumera los temas siempre con dashboard topic list --json — no hay ningún subcomando dashboard list; dashboard list es el comando incorrecto/inválido y devuelve dashboard: unknown command: list.

Comando	Propósito
dashboard topic list --json	Listar todos los temas (JSON, para filtrar)
dashboard topic list	Listar todos los temas (legible para humanos)
dashboard topic new <slug>	Crear un tema
dashboard topic write <slug> <archivo>	Escribir contenido del tema
dashboard topic commit <slug>	Commit + push del tema
dashboard reindex	Actualizar el índice DASHBOARD.md
dashboard commit	Commit + push del índice

Informes

Enviar y consultar informes estructurados de la flota (resultados de pruebas, resúmenes de compilación, estado de CI, etc.) a través de la CLI o la interfaz web. Cada informe tiene un título, subtítulo opcional, cuerpo en Markdown, etiquetas, referencia de tarea del panel de control y archivos adjuntos.

Comandos clave

starfleetctl reports submit "Título" \
    --subtitle "una línea" \
    --body "Texto del cuerpo en Markdown" \
    --body-file ruta/a/log \
    --tags "ci,build" \
    --task-ref xlibre/alguna-tarea \
    --attachment ruta/al/archivo

starfleetctl reports list                          # más recientes primero
starfleetctl reports list --ship Enterprise        # por nave
starfleetctl reports list --tag ci --json          # filtrar + JSON
starfleetctl reports show <id>
starfleetctl reports delete <id>

Los archivos adjuntos se suben al almacén de archivos (file put → /api/store/<nombre>). Consulta doc/reports.md para la referencia completa y el tutorial de la interfaz web.

CLI Starfleetctl

Una CLI en Go para la coordinación de la flota. Inicio: ./starfleet-bootstrap (actualiza .starfleet-ai/). Referencia completa: reference.md en el directorio de esta habilidad.

Resumen de subcomandos

Categoría	Comandos
Flota	comms, dashboard, ws-commit, ship-names, with-clone-lock, worktree
Sesión	run, session list/attach/stop
Tarea	task capture/assign/unassign/status/rm/purge
Temporizador	timer set/list/cancel
Web	web start/stop/restart/autostart
Informes	reports submit/list/show/delete
Configuración	genesis-init, self-install, sop install-starfleet
GitHub (lectura)	github pr view/ci/file-on-branch/wait-green/show-branch-file, github backport applies
GitHub (escritura)	github pr comment/label/set-body/checkout/amend-push/make, github backport commit