triflux 3.2.0-dev.3 → 3.2.0-dev.6

package/skills/tfx-auto-codex/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: tfx-auto-codex
+description: Codex 리드형 tfx-auto. Claude 네이티브 역할을 Codex로 치환하고 Gemini 사용은 유지합니다.
+triggers:
+  - tfx-auto-codex
+argument-hint: "\"작업 설명\" | N:agent_type \"작업 설명\""
+---
+
+# tfx-auto-codex — Codex 리드형 tfx-auto
+
+> 목적: 기존 `tfx-auto`의 오케스트레이션 패턴을 유지하면서
+> Claude 네이티브 역할(`explore`, `verifier`, `test-engineer`, `qa-tester`)을
+> Codex로 치환해 Codex/Gemini만으로 실행한다.
+
+## 핵심 원칙
+
+1. **Codex 라우팅 유지**
+   - 구현/분석/리뷰/디버깅/검증은 Codex 우선.
+2. **Gemini 유지**
+   - `designer`, `writer`는 Gemini 경로를 그대로 사용.
+3. **Claude 네이티브 제거**
+   - 실행 시 `TFX_NO_CLAUDE_NATIVE=1`로 강제.
+4. **고난도 설계는 xhigh**
+   - 설계/분해/비판 검토 성격의 작업은 `codex --profile xhigh` 기준으로 운용.
+
+## 사용법
+
+```bash
+/tfx-auto-codex "인증 리팩터링 + UI 개선 + 테스트 보강"
+/tfx-auto-codex 3:codex "src/api, src/auth, src/payment 병렬 리뷰"
+/tfx-auto-codex 2:gemini "온보딩 UI 카피 + 접근성 개선"
+```
+
+## 실행 규칙
+
+`tfx-auto` 워크플로우(입력 파싱 → 트리아지 → 분해 → DAG 실행 → 수집/보고)를 그대로 사용한다.
+
+단, **실행 명령은 아래 환경변수를 반드시 포함**한다:
+
+```bash
+TFX_NO_CLAUDE_NATIVE=1 bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile}
+```
+
+### 역할 치환 (자동)
+
+`TFX_NO_CLAUDE_NATIVE=1`일 때:
+
+- `explore` -> Codex `fast`
+- `verifier` -> Codex `thorough review`
+- `test-engineer` -> Codex `high`
+- `qa-tester` -> Codex `thorough review`
+
+## 트리아지 기준
+
+- `codex`: 코드 구현/수정/분석/리뷰/디버깅/테스트/검증/리서치
+- `gemini`: 문서/UI/디자인/멀티모달
+
+Claude 타입 반환은 기본적으로 허용하지 않는다.
+분류 결과에 `claude`가 포함되면 `codex`로 치환 후 분해를 진행한다.
+단, Codex CLI 미설치 환경에서는 실행 안전성을 위해 `claude-native` fallback이 유지될 수 있다.
+
+## 권장 프로필
+
+- 설계/계획/비판적 검토: `xhigh`
+- 일반 구현/수정: `high`
+- 리뷰: `thorough`
+- 빠른 탐색: `fast`
+
+## 의존성
+
+- `~/.claude/scripts/tfx-route.sh` 최신 동기화 상태
+- Codex CLI 설치
+- Gemini CLI 설치 (UI/문서 경로 사용 시)
+
+## Troubleshooting
+
+1. `/tfx-doctor` — 진단
+2. `/tfx-doctor --fix` — 자동 수정
+3. `/tfx-doctor --reset` — 캐시 초기화

package/skills/tfx-team/SKILL.md

@@ -6,33 +6,51 @@ triggers:
 argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'
 ---
 
-# tfx-team v2.1 — Lead Direct Bash 기반 멀티-CLI 팀 오케스트레이터
-
-> Claude Code Native Teams는 유지하되, Codex/Gemini 실행 경로에서 Claude teammate 래퍼를 제거한다.
-> 리드가 `tfx-route.sh`를 직접 병렬 실행하고, task 상태는 `team_task_list`를 truth source로 검증한다.
-
-| 구분 | v2 (기존) | v2.1 (현재) |
-|--|--|--|
-| 실행 | `Agent(teammate)` → `Bash(tfx-route.sh)` | `Lead` → `Bash(tfx-route.sh)` 직접 |
-| teammate | Claude Opus 인스턴스 × N | Codex/Gemini용 없음 |
-| task claim | teammate가 `TaskUpdate` 호출 | `tfx-route.sh`가 Hub bridge로 claim |
-| 결과 보고 | teammate가 `SendMessage` 호출 | `tfx-route.sh`가 Hub bridge로 `send-message` 호출 |
-| 결과 수집 | SendMessage 자동 수신 중심 | `team_task_list` 폴링 + stdout/결과 로그 |
-| 정리 | `shutdown_request` × N 후 `TeamDelete` | `TeamDelete` 직접 |
-| Opus 토큰 | N × 래퍼 오버헤드 | 래퍼 오버헤드 0 |
+# 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 "인증 리팩터링 + UI 개선 + 보안 리뷰"
+/tfx-team --agents codex,gemini "프론트+백엔드"
+/tfx-team --tmux "작업"         # 레거시 tmux 모드
+/tfx-team status
 /tfx-team stop
 ```
 
 ## 실행 워크플로우
 
+### Phase 0: 사전 점검 정책 (출력 최소화)
+
+세션 시작 전 점검은 **리드 포그라운드에서 단계별로 장황하게 출력하지 않는다.**
+
+- 원칙:
+  - 사전 점검은 워커 생성과 **비동기 병렬**로 수행한다.
+  - 사용자가 요청하지 않으면 `Searched for ...`, 개별 `Bash(...)` 로그를 전면 보고하지 않는다.
+  - 리드에는 요약 한 줄만 노출한다. 예: `preflight: ok (route/hub)`
+  - Hub 점검은 `/status`를 기준으로 한다 (`/health` 단독 판정 금지).
+- 권장 체크 예시:
+  - `curl -sf http://127.0.0.1:27888/status >/dev/null && echo "Hub: OK" || echo "Hub: NOT RUNNING"`
+- 실패 시에만 상세를 노출한다:
+  - `tfx-route.sh` 없음
+  - Hub 비정상/미기동
+  - 필수 CLI 미설치
+
 ### Phase 1: 입력 파싱
 
 ```
@@ -42,13 +60,13 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --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로 분기.
+
+**제어 커맨드 감지:**
+- `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와 동일)
 
@@ -69,16 +87,16 @@ Bash("codex exec --full-auto --skip-git-repo-check '다음 작업을 분석하
   { \"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" }]
-```
+
+> Codex 분류 실패 시 → Opus(오케스트레이터)가 직접 분류+분해
+
+```
+# Step 2b: 인라인 분해
+분류 결과 → 서브태스크 배열 구성:
+  [{ cli: "codex", subtask: "인증 리팩터링", role: "executor" },
+   { cli: "gemini", subtask: "UI 개선", role: "designer" },
+   { cli: "codex", subtask: "보안 리뷰", role: "reviewer" }]
+```
 
 #### 수동 모드 (`N:agent_type` 또는 `--agents`)
 
@@ -90,12 +108,12 @@ Codex 분류 건너뜀 → Opus가 직접 N개 서브태스크 분해.
 
 #### Step 3a: 팀 생성
 
-```
-teamName = "tfx-" + Date.now().toString(36).slice(-6)
-
-TeamCreate({
-  team_name: teamName,
-  description: "tfx-team: {원본 작업 요약}"
+```
+teamName = "tfx-" + Date.now().toString(36).slice(-6)
+
+TeamCreate({
+  team_name: teamName,
+  description: "tfx-team: {원본 작업 요약}"
 })
 ```
 
@@ -116,17 +134,42 @@ for each assignment in assignments (index i):
   runQueue.push({ taskId, agentName, ...assignment })
 ```
 
-#### Step 3c: 리드가 직접 Bash 병렬 실행 (teammate 스폰 제거)
+#### Step 3c: 슬림 래퍼 Agent 실행 (v2.2 네비게이션 복원)
 
-Codex/Gemini 서브태스크는 teammate를 만들지 않고, 리드가 직접 `Bash(..., run_in_background=true)`를 병렬 호출한다.
+Codex/Gemini 서브태스크마다 최소 프롬프트의 Agent를 spawn하여 네비게이션에 등록한다.
+Agent 내부에서 `Bash(tfx-route.sh)` 1회 실행 후 결과 보고하고 종료한다.
 
 ```
 for each item in runQueue where item.cli in ["codex", "gemini"]:
-  Bash(
-    "TFX_TEAM_NAME={teamName} TFX_TEAM_TASK_ID={item.taskId} TFX_TEAM_AGENT_NAME={item.agentName} TFX_TEAM_LEAD_NAME=team-lead bash ~/.claude/scripts/tfx-route.sh {item.role} \"{item.subtask}\" {mcp_profile}",
-    run_in_background=true
-  )
+  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`: 팀 식별자
@@ -164,8 +207,9 @@ Agent({
 
 ```
 "팀 '{teamName}' 생성 완료.
-Codex/Gemini 작업은 리드가 백그라운드 Bash로 병렬 실행 중이며,
-claude 작업만 teammate로 실행됩니다."
+Codex/Gemini 워커가 슬림 래퍼 Agent로 네비게이션에 등록되었습니다.
+Shift+Down으로 다음 워커, Shift+Tab/Shift+Left로 이전 워커 전환이 가능합니다.
+(Shift+Up은 일부 환경에서 동작하지 않을 수 있음)"
 ```
 
 ### Phase 4: 결과 수집 (truth source = team_task_list)
@@ -192,25 +236,25 @@ Bash("curl -sf http://127.0.0.1:27888/bridge/team/task-list -H \"Content-Type: a
 | 3 | claude-worker-1 | claude | 실패 fallback 재시도 | completed |
 ```
 
-### Phase 5: 정리 (간소화)
+### Phase 5: 정리
 
-teammate 래퍼를 제거했으므로 `shutdown_request` 브로드캐스트를 사용하지 않는다.
-정리 단계는 `TeamDelete()` 직접 호출로 마무리한다.
+슬림 래퍼 Agent는 Bash 완료 후 자동 종료된다.
+claude 타입 Agent와 슬림 래퍼 Agent 모두 완료 확인 후 `TeamDelete()`를 호출한다.
 
-> **중요:** claude 타입 백그라운드 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 세션 안내:
-
-```
+
+```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 전환
@@ -235,6 +279,7 @@ Bash("node {PKG_ROOT}/bin/triflux.mjs team --no-attach --agents {agents.join(','
 - **codex/gemini CLI** — 해당 에이전트 사용 시
 - **tfx setup** — tfx-route.sh 동기화 + AGENT_TEAMS 자동 설정 (사전 실행 권장)
 - **Hub bridge 활성 상태** — 기본 `http://127.0.0.1:27888` (`/bridge/team/*`, `/bridge/result` 사용)
+- **출력 정책** — preflight는 비동기/요약 출력이 기본이며, 실패 시에만 상세 출력
 
 ## 에러 처리
 

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.");
-}