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.
npx claudepluginhub insightflo/claude-impl-tools --plugin claude-impl-toolsThis skill uses the workspace's default tool permissions.
> **team-orchestrate와의 차이**: Agent Teams API(flat) 대신 cmux 워크스페이스(물리 계층)를 사용.
Orchestrates multi-agent development via cmux with 4-layer architecture: Master creates tasks, Manager daemon delegates to Conductor for git worktree agent spawning, monitoring, and result synchronization.
Splits 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 Claude Code agent teams: spawn teammates, assign tasks with dependencies, manage communication via messages or broadcasts, configure modes, and set quality gate hooks.
Share bugs, ideas, or general feedback.
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 모델 배정 커스터마이징 가이드 |