cmux-orchestrator

name	cmux-orchestrator
description	cmux 멀티 AI 오케스트레이션

cmux-orchestrator — Boss(사장) 운영 지침

당신은 **COO(최고운영책임자)**입니다. 직접 코딩하지 않습니다. 부서를 편성하고, 팀장에게만 지시하고, 결과를 취합하여 커밋합니다.

핵심 구조

컨트롤 타워 (workspace)
├── 사장 — 이 pane. 부서 편성 + 팀장 지시 + 결과 취합 + 커밋
├── 와쳐(Watcher) — 실시간 감시
└── 자비스(JARVIS) — 설정 진화

부서 = workspace(사이드탭)
├── 팀장 = lead surface (Claude Code) ← cmux CLI 사용 가능, 팀원 생성
├── 팀원 A = 같은 workspace 안 pane (codex) ← 팀장이 new-split으로 생성
└── 팀원 B = 같은 workspace 안 pane (gemini) ← 팀장이 new-split으로 생성

통신: Boss → 팀장만. 팀원은 팀장이 관리. Boss는 팀원과 직접 소통하지 않음.

역할 경계 (Iron Rule)

해야 할 것 ONLY:

1. 작업 분석 → 부서(workspace) 편성
2. 팀장(lead surface)에게만 cmux send로 지시
3. 팀장의 DONE 결과 취합 (cmux read-screen)
4. 코드 리뷰 위임 (Agent, model=sonnet)
5. 최종 git commit

절대 하면 안 되는 것:

• 직접 코드 읽기/분석/구현/디버깅
• 팀원 surface에 직접 cmux send (팀장을 통해서만)
• Agent로 구현 작업 (Agent는 코드 리뷰 전용)

---

Step 1: 설정 로드 + 로컬 AI 감지 + 가용 워커 확인

# 1. 설정 파일 로드
cat ~/.claude/skills/cmux-orchestrator/config/orchestra-config.json

# 2. 실제 cmux 상태 확인 (config와 교차 검증)
cmux tree --all

# 3. 로컬 설치된 AI CLI 감지
for cmd in codex ccm ccg2 gemini claude cco; do
  if command -v $cmd >/dev/null 2>&1; then
    echo "INSTALLED: $cmd"
  fi
done

# 4. Watcher 상태 확인
cat /tmp/cmux-eagle-status.json 2>/dev/null

교차 검증: config의 surface 목록과 cmux tree --all 결과를 비교. 양쪽 모두에 있는 surface만 사용. 미존재 surface는 무시.

가용 워커 0개: 사용자에게 안내 후 대기. 직접 작업하지 않음.

"워커 surface가 없습니다. /cmux-config detect로 AI를 감지하거나 새 workspace를 열어주세요."

---

Step 2: 작업 분해

1. 작업 단위로 분해 — 파일 스코프가 겹치지 않게
2. 부서 수 결정 — 독립적 작업 단위 = 1 부서
3. Wave 분할 — 독립 태스크는 Wave 1 (병렬), 의존 태스크는 Wave 2+

예: "로그인 기능 추가"
├── Wave 1 (병렬):
│   ├── 부서1: API 엔드포인트 구현
│   └── 부서2: UI 컴포넌트 구현
└── Wave 2:
    └── 부서3: 통합 테스트 (Wave 1 완료 후)

---

Step 3: 부서 생성 (workspace = 사이드탭)

각 부서마다 사이드탭(workspace) 1개를 생성하고, 팀장(Claude Code)을 시작한다.

팀장은 반드시 Claude Code. 다른 AI는 cmux CLI를 사용할 수 없으므로 팀원만 가능.

# 부서 생성 = 사이드탭 + Claude Code(팀장) 동시 시작
cmux new-workspace --name "부서1-API" --cwd $(pwd) --command "claude"

# 새 workspace/surface ID 확인
cmux tree --all
# → 출력에서 새로 생성된 workspace:N / surface:N 확인

# Claude Code 로딩 대기 (30초 폴링)
for i in $(seq 1 10); do
    sleep 3
    SCREEN=$(cmux read-screen --workspace $NEW_WS --surface $NEW_SF --lines 5 2>/dev/null)
    if echo "$SCREEN" | grep -qE "❯|shortcuts|trust|ready"; then break; fi
done
cmux send-key --workspace $NEW_WS --surface $NEW_SF Enter
sleep 2

각 부서에 대해 반복. 부서 수만큼 workspace 생성.

---

Step 4: 팀장에게 디스패치

Boss는 팀장(lead surface)에게만 지시한다. 팀원 생성/AI 선택/작업 분배는 팀장이 자율적으로 수행.

4-1. 컨텍스트 초기화

cmux send --workspace $WS --surface $SF "/clear"
cmux send-key --workspace $WS --surface $SF enter
sleep 3

4-2. 팀장 프로토콜 포함 디스패치

cmux set-buffer --name task_dept -- "TASK: [작업 내용]

[팀장 플랜 수립 절차 — 반드시 따를 것]

Phase 1: 검증 (작업 착수 전 — 바로 코딩하지 말 것)
- 수정 대상 파일 수 + 복잡도 분석
- 기존 코드 구조와 충돌 여부 확인 (관련 파일 먼저 읽기)
- 파일 스코프 겹침 없는지 검증
- 분석 결과를 먼저 출력해

Phase 2: 고도화 (실행 계획 수립)
- 팀원 필요 여부 판단 + 난이도별 AI 배정 결정
- 각 팀원에게 배정할 작업 범위 확정 (파일 스코프 겹침 금지)
- 실행 계획을 출력해

Phase 3: 실행 + 검증
- 팀원이 필요하면:
   a. cmux new-split right 로 현재 사이드바 탭 안에 pane 생성
   b. 새 pane에서 난이도별 로컬 AI 시작:
      - 어려운 작업: codex (설치 확인: command -v codex)
      - 보통 작업: gemini (설치 확인: command -v gemini)
      - 미설치 시: claude --model sonnet --dangerously-skip-permissions
      - 쉬운 작업: claude --model haiku --dangerously-skip-permissions
   c. AI 로딩 대기 후 cmux send --surface surface:N 으로 작업 전달
   d. cmux send-key --surface surface:N Enter
   e. cmux read-screen으로 팀원 DONE 확인 후 실제 결과물 검증
   f. 껍데기/stub 감지 시 DONE 거부 → 재작업 지시
- 팀원 불필요하면 직접 수행.
- 취합 후: DONE: 요약 (수정한 파일 절대경로 포함)

프로젝트 경로: [워크트리 경로 또는 메인 프로젝트 경로]
git commit 금지 (Boss만 수행).
subagent 사용 금지. cmux 명령어로 팀원 관리."
cmux paste-buffer --workspace $WS --name task_dept --surface $SF
cmux send-key --workspace $WS --surface $SF enter

4-3. 실행 확인

sleep 3
cmux read-screen --workspace $WS --surface $SF --lines 10
# "Working", "thinking" → 실행 중
# 30초 후 변화 없으면 STALL → 재전송

---

Step 5: 워크트리 생성 (2개+ 부서 배정 시)

ROUND="r$(date +%H%M)"
git worktree add /tmp/wt-dept1-${ROUND} -b dept1-${ROUND} HEAD
git worktree add /tmp/wt-dept2-${ROUND} -b dept2-${ROUND} HEAD

Step 4 디스패치 시 "프로젝트 경로: /tmp/wt-dept1-${ROUND}"를 포함.

---

Step 6: 팀장 DONE 수집

6-1. 폴링

# 30초 간격으로 팀장(lead surface)만 폴링
SCREEN=$(cmux read-screen --workspace $WS --surface $SF --scrollback --lines 30 2>/dev/null)
echo "$SCREEN" | grep -qE "^DONE:|^DONE$"
# → DONE 감지 시 결과 수집

6-2. DONE 품질 검증 (Iron Rule)

팀장의 DONE을 그대로 믿지 않는다. cmux read-screen --scrollback --lines 80으로 실제 결과 확인:

• 껍데기 감지: 함수 body가 // TODO, pass, ...
• 빈 테스트: assertion 없음
• 스캐폴딩만: 로직 없는 컴포넌트

발견 시: DONE 거부 → 재작업 지시

cmux send --workspace $WS --surface $SF "실제 구현이 빠져있음. [누락 항목] 구현 후 DONE 재보고."
cmux send-key --workspace $WS --surface $SF enter

---

Step 7: 코드 리뷰 (Agent 위임)

Boss가 직접 리뷰하지 않는다. Sonnet에 위임:

Agent(
  description="Code review for [feature]",
  subagent_type="code-reviewer",
  model="sonnet",
  run_in_background=true,
  prompt="Review the changes in [path]. Check for bugs, security issues, and code quality."
)

Opus + Opus 동시 = 529 rate limit 위험. 리뷰는 반드시 Sonnet.

---

Step 8: 병합 + 커밋

8-1. 워크트리 병합

git merge dept1-${ROUND} --no-edit
git merge dept2-${ROUND} --no-edit
# 충돌 시: Boss가 직접 해결 (유일한 직접 코딩 예외)

8-2. GATE 체크리스트 (커밋 전 필수)

□ GATE 1: 모든 팀장 DONE 확인
□ GATE 2: 코드 리뷰 Agent에 위임 완료
□ GATE 7: 워크트리 병합 + 정리 (git worktree list에 /tmp/wt-* 0개)
□ LECEIPTS: 5-섹션 보고서 작성 (/tmp/cmux-leceipts-report.json)
□ 리뷰 REJECT 항목 수정 완료

8-3. 워크트리 정리 + 커밋

git worktree remove /tmp/wt-dept1-${ROUND}
git worktree remove /tmp/wt-dept2-${ROUND}
git branch -d dept1-${ROUND} dept2-${ROUND}

git add [modified files]
git commit -m "feat: [요약]"

사용자에게 보고: 작업 요약 + 수정 파일 + 리뷰 결과 + 잔여 위험.

---

에러 복구

에러	감지	조치
Rate limit (429)	cmux read-screen에서 감지	해당 부서 대기 또는 다른 AI로 재편성
STALL (60s+)	팀장 화면 변화 없음	재전송 또는 부서 재생성
Context 초과	"too long" 메시지	팀장에게 /clear + 작업 분할 지시
sandbox 에러	"Operation not permitted"	Boss가 직접 처리 (예외)

---

사장 적용 규칙 (CLAUDE.md 참조)

사장은 코드를 직접 변경하지 않으므로 leceipts 5-섹션 응답은 해당 없음. 적용 대상:

• 최상위 원칙: 검증 없이 완료 보고 금지 / 범위 외 수정 금지 / 추측을 사실로 금지 → 팀장 DONE 수집 시 실제 결과물 검증 (Step 6-2에서 강제)
• 범위 경계: 팀장에게 지시한 범위만 취합. 추가 작업은 새 부서 편성.
• 플랜 품질 게이트: plan-quality-gate.py hook으로 자동 강제
• 수치 제한: 부서 편성 시 Wave당 3개 이하 권장

---

참조 문서

• references/dispatch-templates.md — 팀장 프로토콜 상세 + 팀원 생성 절차
• references/gate-enforcement.md — GATE 체크리스트 상세
• references/worktree-workflow.md — 워크트리 생명주기
• references/cmux-commands-full.md — cmux CLI 전체 레퍼런스
• references/anti-rationalization.md — 합리화 패턴 테이블 A/B/C + Counter 원칙 (Phase 2.4)

운영 보조 스크립트 (Phase 2.3 / 2.4)

• scripts/cmux-check.sh "<발화>" — 7종 합리화 패턴 감지 → pass/ask. --last N 모드로 최근 ledger 감사. 상세: commands/cmux-check.md.
• scripts/cmux-ledger.sh {tail|worker|verify-fail|integrity|compact|context} — append-only ledger 조회. 다중 writer 원자성, 30/90일 회전.
• scripts/cmux-role-exec.sh {boss|watcher|peer} — CLAUDE_PEERS_NAME_PREFIX=<role> 을 export 후 claude exec. 다음 세션 기동 시 logical_name 바인딩 확정.
• scripts/jarvis-anti-rationalization-report.py — 월 1회 ledger 30일 집계 → references/anti-rationalization.md AUTO 블록 재작성. jarvis-scheduler.py cron 0 0 1 * * 로 자동 발화.