mpbt-hq/starfleetctl

starfleet — Flottenkoordination

Flottenweite Koordination für gleichzeitige KI-Agenten-Sitzungen („Schiffe“). Deckt die Kommunikation zwischen den Schiffen, Nebenläufigkeit/Isolation, Aufgabenverfolgung und die starfleetctl-CLI ab.

Kommunikation zwischen den Schiffen (Comms)

Schiffe kommunizieren über starfleetctl comms. Nachrichten werden automatisch via System-Prompt-Injektion zugestellt – comms inbox niemals manuell aufrufen (der Poller injiziert bereits ungelesene Nachrichten).

Comms-Regeln

1. Immer antworten. Wenn eine tell- oder ask-Nachricht eintrifft, antworte über starfleetctl comms tell <sender>. Stille bedeutet, dass die Nachricht verloren gegangen ist.
2. Quittieren nach der Antwort. starfleetctl comms ack <id> löscht die Nachricht aus dem Posteingang.
3. Comms-Fragen → an zwei Stellen beantworten: über comms tell (damit der Sender sie erhält) UND in der lokalen Konsole (damit der Mensch sie sehen kann).
4. Das Board aktuell halten. Status nach Start oder Ende einer Arbeit setzen.
5. Niemals comms --help aufrufen. Die vollständige Referenz befindet sich im Skill starfleetctl oder in diesem Dokument.

Wichtige Comms-Unterbefehle

Befehl	Zweck
comms tell <schiff> "<nachricht>"	Eine Anweisung an ein Schiff senden
comms tell <schiff> --stdin	Große Datenmengen über stdin senden
comms broadcast "<nachricht>"	An alle Schiffe senden
comms ask "<frage>"	Eine Frage stellen (asynchrone Antwort erwartet)
comms ack <id>	Eine Nachricht quittieren/aus dem Posteingang entfernen
comms board	Flottenstatus-Board anzeigen
comms board --json	Maschinenlesbares Board (für Skripte)
comms status <status>	Eigenen Status setzen (idle/working/blocked)

Nebenläufigkeit / Isolation

Schiffe dürfen nicht gleichzeitig im selben Git-Arbeitsbaum arbeiten. Verwende separate Klone oder Worktrees. PR-Branch-Besitz: Jeder Klone pusht in denselben GitHub-PR-Branch – verwende starfleetctl github pr claim, bevor du einen PR änderst.

Wichtige Regeln

• Verschiedene Arbeitsbäume können sich nicht gegenseitig überschreiben. Parallelisiere über unabhängige Arbeitsbereiche.
• Die Gefahr: Zwei Akteure mutieren gleichzeitig denselben Klon.
• PR-Branch-Besitz: Verwende starfleetctl github pr claim, bevor du einen PR änderst.

Kurzreferenz

starfleetctl github pr make <commit> [<commit> ...]   # PR aus dem Inkubator einreichen
starfleetctl github pr mk-agent-clone <branch> [name] # Agent-eigener Klon
starfleetctl github pr claim <pr#> "was"              # PR-Branch beanspruchen
starfleetctl github pr claim --release <pr#>           # Beanspruchung freigeben
starfleetctl github backport commit <release> <commit> # einmaliger Backport
.starfleet-ai/bin/starfleetctl worktree add <repo> [name] # arbeitsaufgabenbezogener Worktree
starfleetctl with-clone-lock <cmd...>                  # mutierende Arbeit serialisieren

Aufgabenverfolgung

Zeichne eine Aufgabe im Dashboard auf und beauftrage optional ein Schiff. Dieser Befehl gibt nur Anweisungen – führe die Aufgabe nicht selbst aus. Kein direkter Dateizugriff auf DASHBOARD.md oder dashboard/topics/*.md.

Der Einzeiler

starfleetctl task capture --title "<titel>" \
    [--desc "<was zu tun ist>"] \
    [--slug "<überschreibung>"] \
    [--assign [<schiff>]] \
    [--no-push]

• --assign (ohne Name) → leitet an das Flaggschiff weiter, das delegiert oder ausführt
• --assign <schiff> → an dieses bestimmte Schiff
• Ohne --assign → als offen aufgezeichnet, kein Schiff zugewiesen

Vorhandene Aufgaben verwalten

starfleetctl task assign <slug> [<schiff>] [--no-push]   # neu zuweisen
starfleetctl task unassign <slug> [--no-push]          # Zuweisung aufheben
starfleetctl task status <slug> <status> [--no-push]   # Status setzen
starfleetctl task rm <slug> [--no-push]                # Aufgabenthema löschen
starfleetctl task purge [--no-push]                    # ALLE erledigten Aufgaben löschen

Dashboard

Das Dashboard ist der sitzungsübergreifende „Was ist in Arbeit“-Index. Der gesamte Zugriff erfolgt über die CLI – niemals Read/Edit/Write/Glob/Grep auf DASHBOARD.md oder dashboard/topics/*.md.

Themen-Dateiformat (Frontmatter)

Themen-Dateien in dashboard/topics/<slug>.md verwenden YAML-ähnliches Frontmatter:

---
title: "Meine Aufgabe"
category: active       # "active" oder "parked"; Standard ist "active", wenn nicht angegeben
kind: "task"           # optional; kennzeichnet es als planbare Aufgabe
status: "open"         # nur active: open/assigned/done/...
assigned-to: "—"       # Schiffsname oder "—"
tags: "starfleet"      # optional, kommagetrennt
---

Nur title ist erforderlich – category standardmäßig active, alle anderen Felder sind optional. Dies ist beabsichtigt für handschriftliche Themen: Du kannst eine minimale Datei ablegen, die automatisch in der aktiven Liste erscheint.

Themen immer über dashboard topic list --json auflisten – es gibt keinen dashboard list-Unterbefehl; dashboard list ist der falsche/ungültige Befehl und gibt dashboard: unbekannter Befehl: list zurück.

Befehl	Zweck
dashboard topic list --json	Alle Themen auflisten (JSON, zum Filtern)
dashboard topic list	Alle Themen auflisten (menschenlesbar)
dashboard topic new <slug>	Ein Thema erstellen
dashboard topic write <slug> <datei>	Themeninhalt schreiben
dashboard topic commit <slug>	Thema committen + pushen
dashboard reindex	DASHBOARD.md-Index aktualisieren
dashboard commit	Index committen + pushen

Berichte

Strukturierte Flottenberichte einreichen und abfragen (Testergebnisse, Build-Zusammenfassungen, CI-Status usw.) über CLI oder Web-UI. Jeder Bericht hat einen Titel, optionalen Untertitel, Markdown-Text, Tags, eine Dashboard-Aufgabenreferenz und Dateianhänge.

Wichtige Befehle

starfleetctl reports submit "Titel" \
    --subtitle "Einzeiler" \
    --body "Markdown-Text" \
    --body-file pfad/zu/log \
    --tags "ci,build" \
    --task-ref xlibre/eine-aufgabe \
    --attachment pfad/zu/datei

starfleetctl reports list                          # neueste zuerst
starfleetctl reports list --ship Enterprise        # nach Schiff
starfleetctl reports list --tag ci --json          # filtern + JSON
starfleetctl reports show <id>
starfleetctl reports delete <id>

Anhänge werden in den Dateispeicher hochgeladen (file put → /api/store/<name>). Siehe doc/reports.md für die vollständige Referenz und die Web-UI-Anleitung.

Starfleetctl CLI

Eine Go-CLI für die Flottenkoordination. Bootstrap: ./starfleet-bootstrap (aktualisiert .starfleet-ai/). Vollständige Referenz: reference.md im Verzeichnis dieses Skills.

Unterbefehl-Übersicht

Kategorie	Befehle
Flotte	comms, dashboard, ws-commit, ship-names, with-clone-lock, worktree
Sitzung	run, session list/attach/stop
Aufgabe	task capture/assign/unassign/status/rm/purge
Timer	timer set/list/cancel
Web	web start/stop/restart/autostart
Berichte	reports submit/list/show/delete
Einrichtung	genesis-init, self-install, sop install-starfleet
GitHub (lesen)	github pr view/ci/file-on-branch/wait-green/show-branch-file, github backport applies
GitHub (schreiben)	github pr comment/label/set-body/checkout/amend-push/make, github backport commit