triflux 3.2.0-dev.2 → 3.2.0-dev.5

package/skills/tfx-team/SKILL.md

@@ -1,290 +1,286 @@
----
-name: tfx-team
-description: 멀티-CLI 팀 모드. Claude Native Agent Teams + Codex/Gemini 멀티모델 오케스트레이션.
-triggers:
-  - tfx-team
-argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'
----
-
-# tfx-team v2 — Claude Native Teams 기반 멀티-CLI 팀 오케스트레이터
-
-> Claude Code의 네이티브 Agent Teams (in-process 모드)를 활용하여
-> tmux 없이 현재 터미널에서 Codex/Gemini/Claude 멀티모델 팀을 구성한다.
-> 각 teammate는 Claude Code 인스턴스이지만 Codex/Gemini CLI **래퍼**로 동작하여 토큰을 최소화한다.
-
-| | tfx-auto | tfx-team v1 (tmux) | **tfx-team v2 (native)** |
-|--|----------|--------------------|-----------------------------|
-| 트리아지 | Codex 분류 → Opus 분해 | 동일 | **동일** |
-| 실행 | tfx-route.sh one-shot | tmux pane interactive | **Native Teams in-process** |
-| 관찰 | stdout 반환 | Ctrl+B 방향키 | **Shift+Down teammate 전환** |
-| 통신 | 없음 | Hub MCP 버스 | **내장 Mailbox + Task List** |
-| 개입 | 불가 | tfx team send | **SendMessage** |
-| tmux 필요 | ✗ | ✓ | **✗** |
-
-## 사용법
-
-```
-/tfx-team "인증 리팩터링 + UI 개선 + 보안 리뷰"
-/tfx-team --agents codex,gemini "프론트+백엔드"
-/tfx-team --tmux "작업"         # 레거시 tmux 모드
-/tfx-team status
-/tfx-team stop
-```
-
-## 실행 워크플로우
-
-### Phase 1: 입력 파싱
-
-```
-입력: "3:codex 리뷰"         → 수동 모드: N=3, agent=codex
-입력: "인증 + UI + 테스트"    → 자동 모드: Codex 분류 → Opus 분해
-입력: "--tmux 인증 + UI"     → tmux 레거시 모드 → Phase 3-tmux로 분기
-입력: "status"               → 제어 커맨드
-입력: "stop"                 → 제어 커맨드
-```
-
-**제어 커맨드 감지:**
-- `status`, `stop`, `kill`, `attach`, `list`, `send` → `Bash("node bin/triflux.mjs team {cmd}")` 직행
-  (`bin/triflux.mjs` 절대경로는 triflux 패키지 루트 기준)
-- 그 외 → Phase 2 트리아지
-
-**--tmux 감지:** 입력에 `--tmux`가 포함되면 Phase 3-tmux로 분기.
-
-### Phase 2: 트리아지 (tfx-auto와 동일)
-
-#### 자동 모드 — Codex 분류 → Opus 분해
-
-```bash
-# Step 2a: Codex 분류 (무료)
-Bash("codex exec --full-auto --skip-git-repo-check '다음 작업을 분석하고 각 부분에 적합한 agent를 분류하라.
-
-  agent 선택:
-  - codex: 코드 구현/수정/분석/리뷰/디버깅/설계 (기본값)
-  - gemini: 문서/UI/디자인/멀티모달
-  - claude: 코드베이스 탐색/테스트 실행/검증 (최후 수단)
-
-  작업: {task}
-
-  JSON만 출력:
-  { \"parts\": [{ \"description\": \"...\", \"agent\": \"codex|gemini|claude\" }] }
-'")
-```
-
-> Codex 분류 실패 시 → Opus(오케스트레이터)가 직접 분류+분해
-
-```
-# Step 2b: 인라인 분해
-분류 결과 → 서브태스크 배열 구성:
-  [{ cli: "codex", subtask: "인증 리팩터링", role: "executor" },
-   { cli: "gemini", subtask: "UI 개선", role: "designer" },
-   { cli: "codex", subtask: "보안 리뷰", role: "reviewer" }]
-```
-
-#### 수동 모드 (`N:agent_type` 또는 `--agents`)
-
-Codex 분류 건너뜀 → Opus가 직접 N개 서브태스크 분해.
-
-### Phase 3: Native Teams 실행
-
-트리아지 결과를 Claude Code 네이티브 Agent Teams로 실행한다.
-
-#### Step 3a: 팀 생성
-
-```
-teamName = "tfx-" + Date.now().toString(36).slice(-6)
-
-TeamCreate({
-  team_name: teamName,
-  description: "tfx-team: {원본 작업 요약}"
-})
-```
-
-#### Step 3b: 공유 작업 등록
-
-각 서브태스크에 대해 TaskCreate를 호출한다:
-
-```
-for each assignment in assignments:
-  TaskCreate({
-    subject: assignment.subtask,
-    description: "CLI: {assignment.cli}, 역할: {assignment.role}\n\n{상세 작업 내용}",
-    metadata: { cli: assignment.cli, role: assignment.role }
-  })
-```
-
-#### Step 3c: Teammate 스폰
-
-**Agent 도구**에 `team_name`과 `name` 파라미터를 전달하여 teammate를 생성한다.
-**모든 teammate를 `run_in_background: true`로 병렬 스폰한다.**
-
-각 CLI 타입별 teammate 프롬프트:
-
-**codex-worker (Codex CLI 래퍼):**
-
-```
-Agent({
-  name: "codex-worker-{n}",
-  team_name: teamName,
-  description: "codex-worker-{n}",
-  run_in_background: true,
-  prompt: "너는 {teamName}의 Codex 워커이다.
-
-[실행 규칙]
-1. TaskList를 호출하여 너에게 배정된 pending 작업을 확인하라
-2. TaskGet으로 작업 상세를 읽고, TaskUpdate(status: in_progress, owner: 너의 이름)로 claim
-3. Bash(\"bash ~/.claude/scripts/tfx-route.sh {role} '{subtask}' auto\")로 실행
-4. 결과를 확인하고:
-   - 성공: TaskUpdate(status: completed) + SendMessage(type: message, recipient: team-lead, summary: '작업 완료')
-   - 실패: TaskUpdate에 에러 기록 + SendMessage로 리드에게 보고
-5. TaskList를 다시 확인하고 추가 pending 작업이 있으면 반복
-
-[규칙]
-- 실제 구현은 Codex CLI가 수행 — 너는 실행+보고 역할만
-- tfx-route.sh 결과를 그대로 보고하라 (요약하지 말 것)"
-})
-```
-
-**gemini-worker (Gemini CLI 래퍼):**
-
-```
-Agent({
-  name: "gemini-worker-{n}",
-  team_name: teamName,
-  description: "gemini-worker-{n}",
-  run_in_background: true,
-  prompt: "너는 {teamName}의 Gemini 워커이다.
-
-[실행 규칙]
-1. TaskList를 호출하여 너에게 배정된 pending 작업을 확인하라
-2. TaskGet으로 작업 상세를 읽고, TaskUpdate(status: in_progress, owner: 너의 이름)로 claim
-3. Bash(\"bash ~/.claude/scripts/tfx-route.sh {role} '{subtask}' auto\")로 실행
-4. 결과를 확인하고:
-   - 성공: TaskUpdate(status: completed) + SendMessage(type: message, recipient: team-lead, summary: '작업 완료')
-   - 실패: TaskUpdate에 에러 기록 + SendMessage로 리드에게 보고
-5. TaskList를 다시 확인하고 추가 pending 작업이 있으면 반복
-
-[규칙]
-- 실제 구현은 Gemini CLI가 수행 — 너는 실행+보고 역할만
-- tfx-route.sh 결과를 그대로 보고하라 (요약하지 말 것)"
-})
-```
-
-**claude-worker (직접 실행):**
-
-```
-Agent({
-  name: "claude-worker-{n}",
-  team_name: teamName,
-  description: "claude-worker-{n}",
-  run_in_background: true,
-  prompt: "너는 {teamName}의 Claude 워커이다.
-
-[실행 규칙]
-1. TaskList를 호출하여 너에게 배정된 pending 작업을 확인하라
-2. TaskGet으로 작업 상세를 읽고, TaskUpdate(status: in_progress, owner: 너의 이름)로 claim
-3. Glob, Grep, Read, Bash 등 도구를 직접 사용하여 작업 수행
-4. 완료 시 TaskUpdate(status: completed) + SendMessage(type: message, recipient: team-lead, summary: '작업 완료')
-5. TaskList를 다시 확인하고 추가 pending 작업이 있으면 반복
-
-에러 시 TaskUpdate + SendMessage로 리드에게 보고."
-})
-```
-
-#### Step 3d: 사용자 안내
-
-```
-"팀 '{teamName}' 생성 완료 ({N}명의 teammate).
-Shift+Down으로 각 teammate의 진행 상황을 확인할 수 있습니다."
-```
-
-### Phase 4: 결과 수집
-
-리드(이 오케스트레이터)가:
-1. teammate들의 SendMessage를 자동 수신 (폴링 불필요 — 자동 배달됨)
-2. 모든 teammate가 결과를 보고하면 TaskList로 전체 상태 확인
-3. 모든 작업이 completed이면 종합 보고서 출력:
-
-```markdown
-## tfx-team 실행 결과
-
-| # | Teammate | CLI | 작업 | 상태 |
-|---|----------|-----|------|------|
-| 1 | codex-worker-1 | codex | 인증 리팩터링 | ✓ completed |
-| 2 | gemini-worker-1 | gemini | UI 개선 | ✓ completed |
-| 3 | codex-worker-2 | codex | 보안 리뷰 | ✓ completed |
-```
-
-### Phase 5: 정리
-
-```
-# 각 teammate에 shutdown 요청
-for each teammate in teammates:
-  SendMessage({
-    type: "shutdown_request",
-    recipient: teammate.name,
-    content: "모든 작업 완료. 종료합니다."
-  })
-
-# 모든 teammate 종료 후 팀 삭제
-TeamDelete()
-```
-
-> **중요:** TeamDelete는 활성 멤버가 있으면 실패한다. 반드시 모든 teammate에 shutdown_request를 보내고 종료를 확인한 후 호출.
-
-### Phase 3-tmux: 레거시 tmux 모드
-
-`--tmux` 플래그가 있으면 기존 v1 방식으로 실행:
-
-```bash
-# PKG_ROOT: triflux 패키지 루트 (Bash로 확인)
-Bash("node {PKG_ROOT}/bin/triflux.mjs team --no-attach --agents {agents.join(',')} \"{task}\"")
-```
-
-이후 Phase 4-5 대신 사용자에게 tmux 세션 안내:
-
-```
-"tmux 세션이 생성되었습니다.
-  tmux attach -t {sessionId}     세션 연결
-  Ctrl+B → 방향키               pane 전환
-  Ctrl+B → D                    세션 분리
-  Ctrl+B → Z                    pane 전체화면"
-```
-
-## 에이전트 매핑
-
-| 분류 결과 | CLI | teammate 역할 | 실행 방법 |
-|----------|-----|--------------|----------|
-| codex | codex | Codex CLI 래퍼 | `tfx-route.sh {role} '{task}' auto` via Bash |
-| gemini | gemini | Gemini CLI 래퍼 | `tfx-route.sh {role} '{task}' auto` via Bash |
-| claude | claude | 직접 실행 | Glob/Grep/Read/Bash 직접 사용 |
-
-> **핵심 아이디어:** Claude teammate = Codex/Gemini 실행 래퍼
-> - Native Teams 인프라 (in-process, Task List, Mailbox) 활용
-> - 실제 작업은 Codex/Gemini가 수행 (비용 최소화)
-> - teammate의 Claude 토큰은 "실행+보고" 래퍼 역할에만 소비
-
-## 전제 조건
-
-- **CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1** — settings.json env에 설정 (`tfx setup`이 자동 설정)
-- **codex/gemini CLI** — 해당 에이전트 사용 시
-- **tfx setup** — tfx-route.sh 동기화 + AGENT_TEAMS 자동 설정 (사전 실행 권장)
-
-## 에러 처리
-
-| 에러 | 처리 |
-|------|------|
-| TeamCreate 실패 / Agent Teams 비활성 | `--tmux` 폴백 (Phase 3-tmux로 전환) |
-| tfx-route.sh 없음 | `tfx setup` 실행 안내 |
-| CLI 미설치 (codex/gemini) | 해당 서브태스크를 claude 워커로 대체 |
-| Codex 분류 실패 | Opus 직접 분류+분해 |
-| teammate 실행 에러 | TaskUpdate(status: failed) + SendMessage로 리드에게 보고 |
-| teammate shutdown 거부 | 재시도 1회, 이후 사용자에게 보고 |
-
-## 관련
-
-| 항목 | 설명 |
-|------|------|
-| `hub/team/native.mjs` | Native Teams 래퍼 (프롬프트 템플릿, 팀 설정 빌더) |
-| `hub/team/cli.mjs` | tmux 팀 CLI (`--tmux` 레거시 모드) |
-| `tfx-auto` | one-shot 실행 오케스트레이터 (병행 유지) |
-| `tfx-hub` | MCP 메시지 버스 관리 (tmux 모드용) |
+---
+name: tfx-team
+description: 멀티-CLI 팀 모드. Claude Native Agent Teams + Codex/Gemini 멀티모델 오케스트레이션.
+triggers:
+  - tfx-team
+argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'
+---
+
+# tfx-team v2.2 — 슬림 래퍼 + 네비게이션 복원 기반 멀티-CLI 팀 오케스트레이터
+
+> Claude Code Native Teams의 Shift+Down 네비게이션을 복원한다.
+> Codex/Gemini 워커마다 최소 프롬프트(~100 토큰)의 슬림 Agent 래퍼를 spawn하여 네비게이션에 등록하고,
+> 실제 작업은 `tfx-route.sh`가 수행한다. task 상태는 `team_task_list`를 truth source로 검증한다.
+
+| 구분 | v2 (기존) | v2.1 | v2.2 (현재) |
+|--|--|--|--|
+| 실행 | `Agent(teammate)` → `Bash(tfx-route.sh)` | `Lead` → `Bash` 직접 | `Agent(슬림)` → `Bash(tfx-route.sh)` |
+| teammate | Claude Opus 인스턴스 × N | 없음 | 슬림 래퍼 × N |
+| Shift+Down | ✓ | ✗ | ✓ (복원) |
+| task claim | teammate `TaskUpdate` | Hub bridge | Hub bridge (변경 없음) |
+| 결과 보고 | teammate `SendMessage` | Hub bridge | 슬림 래퍼 `SendMessage` + Hub bridge |
+| 결과 수집 | SendMessage 중심 | `team_task_list` 폴링 | `team_task_list` 폴링 (변경 없음) |
+| 정리 | `shutdown_request` × N | `TeamDelete` 직접 | `TeamDelete` 직접 |
+| Opus 토큰 | N × ~800 토큰 | 0 | N × ~180 토큰 (77% 절감) |
+
+## 사용법
+
+```
+/tfx-team "인증 리팩터링 + UI 개선 + 보안 리뷰"
+/tfx-team --agents codex,gemini "프론트+백엔드"
+/tfx-team --tmux "작업"         # 레거시 tmux 모드
+/tfx-team status
+/tfx-team stop
+```
+
+## 실행 워크플로우
+
+### Phase 1: 입력 파싱
+
+```
+입력: "3:codex 리뷰"         → 수동 모드: N=3, agent=codex
+입력: "인증 + UI + 테스트"    → 자동 모드: Codex 분류 → Opus 분해
+입력: "--tmux 인증 + UI"     → tmux 레거시 모드 → Phase 3-tmux로 분기
+입력: "status"               → 제어 커맨드
+입력: "stop"                 → 제어 커맨드
+```
+
+**제어 커맨드 감지:**
+- `status`, `stop`, `kill`, `attach`, `list`, `send` → `Bash("node bin/triflux.mjs team {cmd}")` 직행
+  (`bin/triflux.mjs` 절대경로는 triflux 패키지 루트 기준)
+- 그 외 → Phase 2 트리아지
+
+**--tmux 감지:** 입력에 `--tmux`가 포함되면 Phase 3-tmux로 분기.
+
+### Phase 2: 트리아지 (tfx-auto와 동일)
+
+#### 자동 모드 — Codex 분류 → Opus 분해
+
+```bash
+# Step 2a: Codex 분류 (무료)
+Bash("codex exec --full-auto --skip-git-repo-check '다음 작업을 분석하고 각 부분에 적합한 agent를 분류하라.
+
+  agent 선택:
+  - codex: 코드 구현/수정/분석/리뷰/디버깅/설계 (기본값)
+  - gemini: 문서/UI/디자인/멀티모달
+  - claude: 코드베이스 탐색/테스트 실행/검증 (최후 수단)
+
+  작업: {task}
+
+  JSON만 출력:
+  { \"parts\": [{ \"description\": \"...\", \"agent\": \"codex|gemini|claude\" }] }
+'")
+```
+
+> Codex 분류 실패 시 → Opus(오케스트레이터)가 직접 분류+분해
+
+```
+# Step 2b: 인라인 분해
+분류 결과 → 서브태스크 배열 구성:
+  [{ cli: "codex", subtask: "인증 리팩터링", role: "executor" },
+   { cli: "gemini", subtask: "UI 개선", role: "designer" },
+   { cli: "codex", subtask: "보안 리뷰", role: "reviewer" }]
+```
+
+#### 수동 모드 (`N:agent_type` 또는 `--agents`)
+
+Codex 분류 건너뜀 → Opus가 직접 N개 서브태스크 분해.
+
+### Phase 3: Native Teams 실행 (v2.1 개편)
+
+트리아지 결과를 Claude Code 네이티브 Agent Teams로 실행한다.
+
+#### Step 3a: 팀 생성
+
+```
+teamName = "tfx-" + Date.now().toString(36).slice(-6)
+
+TeamCreate({
+  team_name: teamName,
+  description: "tfx-team: {원본 작업 요약}"
+})
+```
+
+#### Step 3b: 공유 작업 등록
+
+각 서브태스크에 대해 `TaskCreate`를 호출하고 `taskId`를 보존한다.
+리드가 실행 시 사용할 `agentName`도 함께 확정한다.
+
+```
+for each assignment in assignments (index i):
+  TaskCreate({
+    subject: assignment.subtask,
+    description: "CLI: {assignment.cli}, 역할: {assignment.role}\n\n{상세 작업 내용}",
+    metadata: { cli: assignment.cli, role: assignment.role }
+  })
+  taskId = created_task.id
+  agentName = "{assignment.cli}-worker-{i+1}"
+  runQueue.push({ taskId, agentName, ...assignment })
+```
+
+#### Step 3c: 슬림 래퍼 Agent 실행 (v2.2 네비게이션 복원)
+
+Codex/Gemini 서브태스크마다 최소 프롬프트의 Agent를 spawn하여 네비게이션에 등록한다.
+Agent 내부에서 `Bash(tfx-route.sh)` 1회 실행 후 결과 보고하고 종료한다.
+
+```
+for each item in runQueue where item.cli in ["codex", "gemini"]:
+  Agent({
+    name: item.agentName,
+    team_name: teamName,
+    run_in_background: true,
+    prompt: buildSlimWrapperPrompt(item.cli, {
+      subtask: item.subtask,
+      role: item.role,
+      teamName: teamName,
+      taskId: item.taskId,
+      agentName: item.agentName,
+      leadName: "team-lead",
+      mcp_profile: mcp_profile
+    })
+  })
+```
+
+슬림 래퍼 프롬프트 (~100 토큰):
+```
+Bash 1회 실행 후 종료.
+
+TFX_TEAM_NAME={teamName} TFX_TEAM_TASK_ID={taskId} TFX_TEAM_AGENT_NAME={agentName} TFX_TEAM_LEAD_NAME=team-lead bash ~/.claude/scripts/tfx-route.sh {role} '{subtask}' {mcp_profile}
+
+완료 → TaskUpdate(status: completed) + SendMessage(to: team-lead).
+실패 → TaskUpdate(status: failed) + SendMessage(to: team-lead).
+```
+
+`buildSlimWrapperPrompt()`는 `hub/team/native.mjs`에 정의.
+
+**핵심 차이 vs v2:** 프롬프트 ~100 토큰 (v2의 ~500), task claim/complete/report는 tfx-route.sh Hub bridge가 수행.
+
+`tfx-route.sh` 팀 통합 동작(이미 구현됨, `TFX_TEAM_*` 기반):
+- `TFX_TEAM_NAME`: 팀 식별자
+- `TFX_TEAM_TASK_ID`: 작업 식별자
+- `TFX_TEAM_AGENT_NAME`: 워커 표기 이름
+- `TFX_TEAM_LEAD_NAME`: 리드 수신자 이름 (기본 `team-lead`)
+
+Bridge 연동:
+- 실행 시작 시 `POST /bridge/team/task-update`로 `claim + in_progress`
+- 실행 종료 시 `POST /bridge/team/task-update`로 `completed|failed`
+- 리드 보고 `POST /bridge/team/send-message`
+- 이벤트 채널 `POST /bridge/result` (`topic=task.result`) 발행
+
+#### Step 3d: claude 타입만 Agent 직접 실행
+
+`cli == claude`인 서브태스크에만 `Agent(subagent_type)`를 사용한다.
+
+```
+Agent({
+  name: "claude-worker-{n}",
+  team_name: teamName,
+  description: "claude-worker-{n}",
+  run_in_background: true,
+  subagent_type: "{role}",
+  prompt: "너는 {teamName}의 Claude 워커이다.
+
+1. TaskGet 후 TaskUpdate(status: in_progress, owner: 너의 이름)로 claim
+2. 도구를 직접 사용해 작업 수행
+3. 성공 시 TaskUpdate(status: completed) + SendMessage(to: team-lead)
+4. 실패 시 TaskUpdate(status: failed) + SendMessage(to: team-lead)"
+})
+```
+
+#### Step 3e: 사용자 안내
+
+```
+"팀 '{teamName}' 생성 완료.
+Codex/Gemini 워커가 슬림 래퍼 Agent로 네비게이션에 등록되었습니다.
+Shift+Down으로 워커 간 전환이 가능합니다."
+```
+
+### Phase 4: 결과 수집 (truth source = team_task_list)
+
+1. 리드가 Step 3c에서 실행한 모든 백그라운드 Bash 프로세스 완료를 대기한다.
+2. `team_task_list`를 최종 truth source로 조회한다.
+
+```bash
+Bash("curl -sf http://127.0.0.1:27888/bridge/team/task-list -H \"Content-Type: application/json\" -d \"{\\\"team_name\\\":\\\"${teamName}\\\"}\"")
+```
+
+3. 상태가 `failed`인 task가 있으면 Claude fallback으로 재시도한다.
+4. 재시도 후 다시 `team_task_list`를 조회해 최종 상태를 확정한다.
+5. `send-message`와 `/bridge/result(task.result)` 이벤트는 진행 관찰 채널로 사용하고, 최종 판정은 반드시 `team_task_list` 기준으로 한다.
+
+종합 보고서 예시:
+```markdown
+## tfx-team 실행 결과
+
+| # | Worker | CLI | 작업 | 상태 |
+|---|--------|-----|------|------|
+| 1 | codex-worker-1 | codex | 인증 리팩터링 | completed |
+| 2 | gemini-worker-1 | gemini | UI 개선 | completed |
+| 3 | claude-worker-1 | claude | 실패 fallback 재시도 | completed |
+```
+
+### Phase 5: 정리
+
+슬림 래퍼 Agent는 Bash 완료 후 자동 종료된다.
+claude 타입 Agent와 슬림 래퍼 Agent 모두 완료 확인 후 `TeamDelete()`를 호출한다.
+
+> **중요:** 슬림 래퍼 Agent가 아직 실행 중이면 `TeamDelete`가 실패할 수 있다. 모든 워커 완료를 확인한 뒤 삭제한다.
+
+### Phase 3-tmux: 레거시 tmux 모드
+
+`--tmux` 플래그가 있으면 기존 v1 방식으로 실행:
+
+```bash
+# PKG_ROOT: triflux 패키지 루트 (Bash로 확인)
+Bash("node {PKG_ROOT}/bin/triflux.mjs team --no-attach --agents {agents.join(',')} \"{task}\"")
+```
+
+이후 Phase 4-5 대신 사용자에게 tmux 세션 안내:
+
+```
+"tmux 세션이 생성되었습니다.
+  tmux attach -t {sessionId}     세션 연결
+  Ctrl+B → 방향키               pane 전환
+  Ctrl+B → D                    세션 분리
+  Ctrl+B → Z                    pane 전체화면"
+```
+
+## 에이전트 매핑
+
+| 분류 결과 | CLI | 역할 | 실행 방법 |
+|----------|-----|------|----------|
+| codex | codex | Lead 직접 라우팅 | `TFX_TEAM_* bash ~/.claude/scripts/tfx-route.sh {role} "{task}" {mcp_profile}` |
+| gemini | gemini | Lead 직접 라우팅 | `TFX_TEAM_* bash ~/.claude/scripts/tfx-route.sh {role} "{task}" {mcp_profile}` |
+| claude | claude | Claude 직접 실행 | `Agent(subagent_type={role})`로 직접 수행 |
+
+> **핵심 아이디어:** Codex/Gemini 작업은 `tfx-route.sh`가 팀 상태 동기화까지 직접 수행한다.
+> 리드는 오케스트레이션에 집중하고, Claude 토큰은 래퍼 오버헤드 없이 필요한 직접 실행(`claude` 타입)에만 사용한다.
+
+## 전제 조건
+
+- **CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1** — settings.json env에 설정 (`tfx setup`이 자동 설정)
+- **codex/gemini CLI** — 해당 에이전트 사용 시
+- **tfx setup** — tfx-route.sh 동기화 + AGENT_TEAMS 자동 설정 (사전 실행 권장)
+- **Hub bridge 활성 상태** — 기본 `http://127.0.0.1:27888` (`/bridge/team/*`, `/bridge/result` 사용)
+
+## 에러 처리
+
+| 에러 | 처리 |
+|------|------|
+| TeamCreate 실패 / Agent Teams 비활성 | `--tmux` 폴백 (Phase 3-tmux로 전환) |
+| tfx-route.sh 없음 | `tfx setup` 실행 안내 |
+| CLI 미설치 (codex/gemini) | 해당 서브태스크를 claude 워커로 대체 |
+| Codex 분류 실패 | Opus 직접 분류+분해 |
+| Bash 실행 실패 (Lead) | task를 `failed`로 마킹 후 Claude fallback 재시도 |
+| `team_task_list` 조회 실패 | `/bridge/result`/stdout로 임시 관찰 후 bridge 복구 뒤 상태 재검증 |
+| claude fallback 실패 | 실패 task 목록/원인 요약 후 사용자 승인 대기 |
+
+## 관련
+
+| 항목 | 설명 |
+|------|------|
+| `scripts/tfx-route.sh` | 팀 통합 라우터 (`TFX_TEAM_*`, task claim/complete, send-message, `/bridge/result`) |
+| `hub/team/native.mjs` | Native Teams 래퍼 (프롬프트 템플릿, 팀 설정 빌더) |
+| `hub/team/cli.mjs` | tmux 팀 CLI (`--tmux` 레거시 모드) |
+| `tfx-auto` | one-shot 실행 오케스트레이터 (병행 유지) |
+| `tfx-hub` | MCP 메시지 버스 관리 (tmux 모드용) |

package/scripts/team-keyword.mjs

@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-// scripts/team-keyword.mjs — "team" 매직 키워드 → /tfx-team 라우팅
-// UserPromptSubmit 훅에서 실행. stdin으로 프롬프트 수신.
-import { readFileSync } from "node:fs";
-
-// stdin에서 프롬프트 읽기
-let prompt = "";
-try {
-  prompt = readFileSync(0, "utf8");
-} catch {
-  process.exit(0);
-}
-
-// 코드 블록 제거 (오탐 방지)
-const cleaned = prompt
-  .replace(/```[\s\S]*?```/g, "")
-  .replace(/`[^`]+`/g, "")
-  .replace(/https?:\/\/\S+/g, "");
-
-// "team" 키워드 감지 (소유격/관사 뒤는 제외)
-const hasTeam =
-  /(?<!\b(?:my|the|our|a|his|her|their|its|omc|oh-my-claudecode)\s)\bteam\b/i.test(cleaned) ||
-  /\btfx[\s-]?team\b/i.test(cleaned);
-
-if (hasTeam) {
-  console.log("[MAGIC KEYWORD: tfx-team]");
-  console.log("");
-  console.log("You MUST invoke the skill using the Skill tool:");
-  console.log("");
-  console.log("Skill: tfx-team");
-  console.log("");
-  console.log(`User request:\n${prompt.trim()}`);
-  console.log("");
-  console.log("IMPORTANT: Invoke the skill IMMEDIATELY. Do not proceed without loading the skill instructions.");
-}