mpbt-hq/starfleetctl

starfleet — 艦隊連携

AIエージェントセッション（「艦」）を同時に運用するための艦隊全体の連携機能です。艦間通信、並行実行／分離、タスクキャプチャ、およびstarfleetctl CLIをカバーします。

艦間通信（comms）

艦は starfleetctl comms を介して通信します。メッセージはシステムプロンプトインジェクションによって自動的に届きます — comms inbox を手動で呼び出さないでください（ポーラーが未読メッセージをすでに注入しています）。

Commsルール

1. 必ず応答する。 tell または ask が届いたら、starfleetctl comms tell <送信元> で返信します。沈黙はメッセージが失われたことを意味します。
2. 応答後にAckする。 starfleetctl comms ack <id> で受信箱からメッセージを消去します。
3. Commsの質問 → 2か所で回答する： comms tell で（送信元に届くように）、かつローカルコンソールでも（人間が見られるように）回答します。
4. 掲示板を最新に保つ。 作業を開始または終了したらステータスを設定します。
5. comms --help を呼び出さない。 完全なリファレンスは starfleetctl スキルまたはこのドキュメントにあります。

主要なcommsサブコマンド

コマンド	目的
comms tell <艦> "<メッセージ>"	艦に指示を送信
comms tell <艦> --stdin	標準入力から大きなペイロードを送信
comms broadcast "<メッセージ>"	全艦に送信
comms ask "<質問>"	質問を送信（非同期で応答を期待）
comms ack <id>	受信箱のメッセージを確認・削除
comms board	艦隊ステータスボードを表示
comms board --json	機械可読なボード（スクリプト用）
comms status <ステータス>	自身のステータスを設定（idle/working/blocked）

並行実行／分離

艦は同じGitワーキングツリーで同時に作業してはいけません。別々のクローンまたはワークツリーを使用してください。PRブランチの所有権：すべてのクローンは 同じGitHub PRブランチ にプッシュします — PRを変更する前に starfleetctl github pr claim を使用してください。

主要なルール

• 異なるワーキングツリーは互いに上書きできません。 独立したワークスペースで並行処理を行ってください。
• 危険性： 2つのアクターが同時に 同じ クローンを変更すること。
• PRブランチの所有権： PRを変更する前に starfleetctl github pr claim を使用します。

クイックリファレンス

starfleetctl github pr make <コミット> [<コミット> ...]   # インキュベーターからPRを提出
starfleetctl github pr mk-agent-clone <ブランチ> [名前] # エージェント所有のクローン
starfleetctl github pr claim <PR番号> "内容"              # PRブランチを主張
starfleetctl github pr claim --release <PR番号>           # 主張を解放
starfleetctl github backport commit <リリース> <コミット> # 単発バックポート
.starfleet-ai/bin/starfleetctl worktree add <リポジトリ> [名前] # タスクごとのワークツリー
starfleetctl with-clone-lock <コマンド...>                  # 変更作業を直列化

タスクキャプチャ

ダッシュボードにタスクを記録し、必要に応じて艦に委任します。これは指示するだけ — 自分でタスクを実行してはいけません。 DASHBOARD.md や dashboard/topics/*.md へのファイル直接アクセスは禁止です。

ワンライナー

starfleetctl task capture --title "<タイトル>" \
    [--desc "<必要な作業>"] \
    [--slug "<上書き>"] \
    [--assign [<艦>]] \
    [--no-push]

• --assign（名前なし）→ 旗艦にルーティングされ、旗艦が委任または実行する
• --assign <艦> → 特定の艦に割り当て
• --assign なし → オープンとして記録され、艦は割り当てられない

既存のタスクを管理

starfleetctl task assign <スラッグ> [<艦>] [--no-push]   # 再割り当て
starfleetctl task unassign <スラッグ> [--no-push]          # 割り当てを解除
starfleetctl task status <スラッグ> <ステータス> [--no-push]   # ステータスを設定
starfleetctl task rm <スラッグ> [--no-push]                # タスクトピックを削除
starfleetctl task purge [--no-push]                    # 完了したタスクをすべて削除

ダッシュボード

ダッシュボードはセッション間の「現在進行中」のインデックスです。すべてCLI経由でアクセス — DASHBOARD.md または dashboard/topics/*.md に対して 決して Read/Edit/Write/Glob/Grep を行わないでください。

トピックファイル形式（フロントマター）

dashboard/topics/<スラッグ>.md のトピックファイルはYAML風のフロントマターを使用します：

---
title: "マイタスク"
category: active       # "active" または "parked"；省略時は "active"
kind: "task"           # オプション；スケジュール可能なタスクとしてマーク
status: "open"         # activeのみ：open/assigned/done/...
assigned-to: "—"       # 艦名または "—"
tags: "starfleet"      # オプション、カンマ区切り
---

title のみ必須 — category はデフォルトで active、その他のフィールドはすべてオプションです。これは手書きのトピックを意図しています：最小限のファイルを配置するだけで、自動的にアクティブリストに表示されます。

トピックは常に dashboard topic list --json で一覧表示 — dashboard list サブコマンドは 存在しません；dashboard list は誤った/無効なコマンドであり、dashboard: unknown command: list を返します。

コマンド	目的
dashboard topic list --json	全トピックを一覧表示（JSON、フィルタリング用）
dashboard topic list	全トピックを一覧表示（人間可読）
dashboard topic new <スラッグ>	トピックを作成
dashboard topic write <スラッグ> <ファイル>	トピック内容を書き込み
dashboard topic commit <スラッグ>	トピックをコミット＋プッシュ
dashboard reindex	DASHBOARD.md インデックスを更新
dashboard commit	インデックスをコミット＋プッシュ

レポート

構造化された艦隊レポート（テスト結果、ビルドサマリー、CIステータスなど）をCLIまたはWeb UIを介して提出および照会します。各レポートには、タイトル、オプションのサブタイトル、Markdown本文、タグ、ダッシュボードタスク参照、およびファイル添付が含まれます。

主要コマンド

starfleetctl reports submit "タイトル" \
    --subtitle "ワンライナー" \
    --body "Markdown本文テキスト" \
    --body-file path/to/log \
    --tags "ci,build" \
    --task-ref xlibre/some-task \
    --attachment path/to/file

starfleetctl reports list                          # 新しい順
starfleetctl reports list --ship Enterprise        # 艦でフィルタ
starfleetctl reports list --tag ci --json          # フィルタ＋JSON
starfleetctl reports show <ID>
starfleetctl reports delete <ID>

添付ファイルはファイルストアにアップロードされます（file put → /api/store/<名前>）。完全なリファレンスとWeb UIのチュートリアルについては doc/reports.md を参照してください。

Starfleetctl CLI

艦隊連携のためのGo製CLI。ブートストラップ：./starfleet-bootstrap（.starfleet-ai/ を更新）。完全なリファレンス：このスキルのディレクトリにある reference.md。

サブコマンド概要

カテゴリ	コマンド
艦隊	comms, dashboard, ws-commit, ship-names, with-clone-lock, worktree
セッション	run, session list/attach/stop
タスク	task capture/assign/unassign/status/rm/purge
タイマー	timer set/list/cancel
Web	web start/stop/restart/autostart
レポート	reports submit/list/show/delete
セットアップ	genesis-init, self-install, sop install-starfleet
GitHub（読み取り）	github pr view/ci/file-on-branch/wait-green/show-branch-file, github backport applies
GitHub（書き込み）	github pr comment/label/set-body/checkout/amend-push/make, github backport commit