From claude-impl-tools
Orchestrates hierarchical multi-AI teams in cmux workspaces deploying Claude, Gemini, Codex as independent processes for parallel execution on architecture, design, backend/frontend, QA tasks from TASKS.md.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claude-impl-tools:cmux-orchestrateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **team-orchestrate와의 차이**: Agent Teams API(flat) 대신 cmux 워크스페이스(물리 계층)를 사용.
team-orchestrate와의 차이: Agent Teams API(flat) 대신 cmux 워크스페이스(물리 계층)를 사용. L1 리드가 자신의 L2 워커를 직접 스폰 → 진짜 3-Level 독립 프로세스.
현재 Claude 세션 (Level 0: team-lead)
│ 모니터링: cmux sidebar + .claude/collab/reports/
│
├─ cmux workspace "arch-lead" (Level 1)
│ process: claude or codex
│ 스폰: backend-builder 워크스페이스를 직접 생성
│ └─ cmux workspace "backend-builder" (Level 2)
│
├─ cmux workspace "design-lead" (Level 1)
│ process: gemini or claude
│ 스폰: frontend-builder 워크스페이스를 직접 생성
│ └─ cmux workspace "frontend-builder" (Level 2)
│
└─ cmux workspace "qa-lead" (Level 1)
process: claude
핵심 원칙: 각 에이전트는 독립 프로세스 → 컨텍스트 격리 + 진짜 병렬
# 1. cmux 사용 가능
cmux ping || { echo "cmux 필요"; exit 1; }
# 2. TASKS.md 존재
[ -f TASKS.md ] || { echo "/tasks-init로 먼저 생성"; exit 1; }
# 3. 소켓 접근 모드 확인 (에이전트가 사이드바를 쓰려면 allowAll 필요)
export CMUX_SOCKET_MODE=allowAll # 또는 cmux 내부에서 실행 중이면 자동
| 역할 | 기본 AI | 이유 |
|---|---|---|
| team-lead | claude | 전략, 조율, 판단 |
| arch-lead | claude | 아키텍처 결정, 코드 리뷰 |
| backend-builder | codex | 코드 생성 최적화 |
| design-lead | gemini | 창의성, 비주얼 판단 |
| frontend-builder | gemini | UI/UX 구현 |
| qa-lead | claude | 분석적 검증 |
| reviewer | claude | 코드 리뷰, 품질 판단 |
커스터마이징: references/ai-routing.md 참조
# 도메인 추출
grep "domain:" TASKS.md | sort -u
# 예시 출력: backend, frontend, qa
분석 결과로 팀 토폴로지 결정:
backend 도메인 → arch-lead + backend-builderfrontend 도메인 → design-lead + frontend-builderqa 태그 → qa-leadmkdir -p .claude/collab/{reports,requests,decisions,contexts,inbox}
# inbox: team-lead 수신함
# contexts: 각 에이전트용 브리핑 파일 (team-lead가 작성)
각 L1 리드용 브리핑 파일을 .claude/collab/contexts/ 에 작성.
내용: 역할, 담당 도메인 태스크 목록, 통신 규약, 워커 스폰 방법.
상세 프롬프트 템플릿: references/agent-prompts.md
# arch-lead (claude)
ARCH_WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $ARCH_WS "cd $(pwd)
"
cmux send --workspace $ARCH_WS \
"claude --dangerously-skip-permissions -p \"\$(cat .claude/collab/contexts/arch-lead.md)\"
"
cmux set-status "arch-lead" "starting" --icon hammer --color "#ff9500"
# design-lead (gemini)
DESIGN_WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $DESIGN_WS "cd $(pwd)
"
cmux send --workspace $DESIGN_WS \
"gemini --yolo \"\$(cat .claude/collab/contexts/design-lead.md)\"
"
cmux set-status "design-lead" "starting" --icon brush --color "#5856d6"
# qa-lead (claude) — L1 리드들 스폰 후에 시작
QA_WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $QA_WS "cd $(pwd)
"
cmux send --workspace $QA_WS \
"claude --dangerously-skip-permissions -p \"\$(cat .claude/collab/contexts/qa-lead.md)\"
"
cmux set-status "qa-lead" "waiting" --icon checklist --color "#8e8e93"
team-lead는 블로킹 없이 아래를 반복 확인:
# 1. 사이드바 상태 확인
cmux sidebar-state
# 2. 리포트 파일 확인 (리드들이 완료 시 기록)
ls .claude/collab/reports/
# 3. team-lead 수신함 확인 (에이전트가 알림 전달 시)
ls .claude/collab/inbox/
긴급 이슈 → 리드가 cmux notify로 즉시 알림.
리드 간 충돌/의존성 발생 시:
# team-lead가 해당 리드 워크스페이스에 지시 전달
cmux send --workspace $ARCH_WS \
"API 스펙 변경 사항을 .claude/collab/requests/REQ-001.md 에 기록하고 design-lead에 공유
"
결정 사항 → .claude/collab/decisions/DEC-NNN.md 에 기록.
# 작업량 증가 → 워커 추가 스폰
EXTRA_WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $ARCH_WS \
"WS=\$(cmux new-workspace 2>&1 | awk '{print \$2}') && cmux send --workspace \$WS \"cd $(pwd) && codex exec '\$(cat .claude/collab/contexts/backend-builder-2.md)'\"
"
# 완료된 워커 종료
cmux send --workspace $DONE_WS "exit
"
cmux close-workspace --workspace $DONE_WS
cmux clear-status "backend-builder"
# 각 리드에 종료 신호
for WS in $ARCH_WS $DESIGN_WS $QA_WS; do
cmux send --workspace $WS "exit
"
done
# 워크스페이스 정리
cmux close-workspace --workspace $ARCH_WS
cmux close-workspace --workspace $DESIGN_WS
cmux close-workspace --workspace $QA_WS
# 사이드바 클리어
cmux clear-status
cmux log --level success -- "Team disbanded. All tasks complete."
# 시작
cmux set-status "{role}" "active" --icon hammer --color "#ff9500"
cmux set-progress 0.0 --label "{role}: starting"
# 진행 중
cmux set-progress 0.4 --label "{role}: T1.2 in progress"
# Phase 완료
cmux set-status "{role}" "phase-1 done" --icon checkmark --color "#34c759"
cmux log --level success -- "{role}: Phase 1 complete (3/3 tasks)"
# 블로킹 이슈
cmux set-status "{role}" "BLOCKED" --icon warning --color "#ff3b30"
cmux notify --title "{role} BLOCKED" --body "크로스 도메인 의존성 발생. team-lead 확인 필요"
# Phase 완료 시 리포트 작성
cat > .claude/collab/reports/$(date +%Y%m%d)-{role}-phase-N.md << 'EOF'
## {role} Phase N Report
- Completed: T1.1, T1.2, T1.3
- Decisions: ADR-001 작성
- Issues: 없음
- Next: Phase 2 대기
EOF
# arch-lead가 backend-builder 스폰
WORKER_CTX=".claude/collab/contexts/backend-builder.md"
cat > $WORKER_CTX << 'EOF'
[워커 컨텍스트 - 담당 태스크, 테스트 명령, 보고 방법]
EOF
WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $WS "cd $(pwd) && codex exec \"\$(cat $WORKER_CTX)\"
"
cmux set-status "backend-builder" "spawned" --icon gear --color "#007aff"
워커 프롬프트 템플릿: references/agent-prompts.md
| team-orchestrate | cmux-orchestrate | |
|---|---|---|
| 에이전트 실행 | Agent Teams API (in-process) | 독립 프로세스 (cmux workspace) |
| 계층 구조 | 논리적 (SendMessage 프로토콜) | 물리적 (프로세스 계층) |
| 지원 AI | Claude만 | Claude + Gemini + Codex |
| 컨텍스트 | 공유 (같은 프로세스) | 격리 (독립 세션) |
| 상태 모니터링 | TaskList 폴링 | cmux sidebar 실시간 |
| 장애 격리 | 한 에이전트 문제 → 전체 영향 | 독립 프로세스 → 격리됨 |
| 요구사항 | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS | cmux (CMUX_SOCKET_MODE=allowAll) |
| 상황 | 동작 |
|---|---|
| cmux 없음 | /team-orchestrate (Agent Teams API 기반) 사용 권장 |
| codex CLI 없음 | Claude 워크스페이스가 대체 |
| gemini CLI 없음 | Claude 워크스페이스가 대체 |
| 워크스페이스 생성 실패 | 로그 기록 후 해당 역할 건너뜀 |
| Agent 타임아웃 (5분) | Claude가 직접 해당 역할 수행 |
| 파일 | 내용 |
|---|---|
references/agent-prompts.md | 각 역할별 컨텍스트 파일 템플릿 |
references/ai-routing.md | AI 모델 배정 커스터마이징 가이드 |
npx claudepluginhub insightflo/claude-impl-tools --plugin claude-impl-toolsSplits cmux panels for parallel Codex (code), Gemini (design), and Claude (planning) task execution via log streaming and agent teams. Use /cmux-ai-run for multi-AI workflows in cmux.
Orchestrates multi-agent development via cmux using 4-layer architecture (Master→Manager→Conductor→Agent). Manages tasks, spawns agents in git worktrees, monitors progress, collects results, and synchronizes via CLI and slash commands.
Orchestrates Claude Code agent teams: spawn teammates, assign tasks with dependencies, manage communication via messages or broadcasts, configure modes, and set quality gate hooks.