mpbt-hq/starfleetctl

starfleet — 함대 조정 (fleet coordination)

동시 AI 에이전트 세션("함선")을 위한 함대 전체 조정 도구입니다. 함선 간 통신, 동시성/격리, 작업 캡처, starfleetctl CLI를 다룹니다.

함선 간 통신 (comms)

함선은 starfleetctl comms를 통해 통신합니다. 메시지는 시스템 프롬프트 주입을 통해 자동으로 도착합니다. — 절대 수동으로 comms inbox를 호출하지 마십시오 (폴러가 이미 보지 않은 메시지를 주입합니다).

Comms 규칙

1. 항상 응답하십시오. tell 또는 ask가 도착하면 starfleetctl comms tell <발신자>로 회신하십시오. 침묵은 메시지가 손실되었음을 의미합니다.
2. 응답 후 확인(Ack)하십시오. starfleetctl comms ack <id>로 받은 편지함에서 지웁니다.
3. Comms 질문 → 두 군데에 응답: comms tell(발신자가 받도록) 및 로컬 콘솔(인간이 볼 수 있도록)에 응답하십시오.
4. 게시판을 최신 상태로 유지하십시오. 작업을 시작하거나 마친 후 상태를 설정하십시오.
5. 절대 comms --help를 호출하지 마십시오. 전체 참조는 starfleetctl 스킬 또는 이 문서에 있습니다.

주요 comms 하위 명령어

명령어	목적
comms tell <함선> "<메시지>"	함선에 지시 보내기
comms tell <함선> --stdin	stdin을 통해 큰 페이로드 보내기
comms broadcast "<메시지>"	모든 함선에 보내기
comms ask "<질문>"	질문하기 (비동기 응답 예상)
comms ack <id>	받은 편지함에서 메시지 확인/제거
comms board	함대 상태 게시판 표시
comms board --json	기계 판독 가능 게시판 (스크립트용)
comms status <상태>	자신의 상태 설정 (idle/working/blocked)

동시성 / 격리 (Concurrency / isolation)

함선은 동시에 동일한 git 작업 트리에서 작업해서는 안 됩니다. 별도의 클론 또는 작업 트리를 사용하십시오. PR-브랜치 소유권: 모든 클론은 동일한 GitHub PR 브랜치로 푸시합니다 — PR을 변경하기 전에 starfleetctl github pr claim을 사용하십시오.

주요 규칙

• 서로 다른 작업 트리는 서로를 덮어쓸 수 없습니다. 독립적인 작업 공간에서 병렬화하십시오.
• 위험 요소: 두 행위자가 동시에 동일한 클론을 변경하는 경우.
• 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 <명령어...>                  # 변경 작업 직렬화

작업 캡처 (Task capture)

대시보드에 작업을 기록하고, 선택적으로 함선에 위임합니다. 이것은 명령만 내립니다 — 작업을 직접 실행하지 마십시오. DASHBOARD.md 또는 dashboard/topics/*.md에 직접 파일 접근하지 마십시오.

한 줄 명령어

starfleetctl task capture --title "<제목>" \
    [--desc "<해야 할 일>"] \
    [--slug "<재정의>"] \
    [--assign [<함선>]] \
    [--no-push]

• --assign (이름 없음) → 기함(flagship)으로 라우팅, 기함이 위임 또는 실행
• --assign <함선> → 특정 함선
• --assign 없음 → 미할당으로 기록, 함선 없음

기존 작업 관리

starfleetctl task assign <slug> [<함선>] [--no-push]   # 재할당
starfleetctl task unassign <slug> [--no-push]          # 할당 해제
starfleetctl task status <slug> <상태> [--no-push]   # 상태 설정
starfleetctl task rm <slug> [--no-push]                # 작업 주제 삭제
starfleetctl task purge [--no-push]                    # 완료된 모든 작업 삭제

대시보드 (Dashboard)

대시보드는 교차 세션 "진행 중인 작업" 인덱스입니다. 모든 접근은 CLI를 통해 이루어집니다 — 절대 DASHBOARD.md 또는 dashboard/topics/*.md에 대해 Read/Edit/Write/Glob/Grep을 수행하지 마십시오.

주제 파일 형식 (머리말)

dashboard/topics/<slug>.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 <slug>	주제 생성
dashboard topic write <slug> <파일>	주제 내용 쓰기
dashboard topic commit <slug>	주제 커밋 + 푸시
dashboard reindex	DASHBOARD.md 인덱스 새로 고침
dashboard commit	인덱스 커밋 + 푸시

보고서 (Reports)

CLI 또는 웹 UI를 통해 구조화된 함대 보고서(테스트 결과, 빌드 요약, CI 상태 등)를 제출하고 조회합니다. 각 보고서에는 제목, 선택적 부제목, 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/<이름>). 전체 참조 및 웹 UI 연습은 doc/reports.md를 참조하십시오.

Starfleetctl CLI

함대 조정을 위한 Go CLI입니다. 부트스트랩: ./starfleet-bootstrap (.starfleet-ai/ 업데이트). 전체 참조: 이 스킬 디렉토리의 reference.md.

하위 명령어 개요

카테고리	명령어
함대 (Fleet)	comms, dashboard, ws-commit, ship-names, with-clone-lock, worktree
세션 (Session)	run, session list/attach/stop
작업 (Task)	task capture/assign/unassign/status/rm/purge
타이머 (Timer)	timer set/list/cancel
웹 (Web)	web start/stop/restart/autostart
보고서 (Reports)	reports submit/list/show/delete
설정 (Setup)	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