triflux 3.2.0-dev.8 → 3.2.0-dev.9

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

@@ -74,6 +74,4 @@ Claude 타입 반환은 기본적으로 허용하지 않는다.
 
 ## Troubleshooting
 
-1. `/tfx-doctor` — 진단
-2. `/tfx-doctor --fix` — 자동 수정
-3. `/tfx-doctor --reset` — 캐시 초기화
+문제 발생 시 `/tfx-doctor` 실행. (`--fix` 자동 수정, `--reset` 캐시 초기화)

package/skills/tfx-codex/SKILL.md

@@ -62,7 +62,4 @@ argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""
 
 ## Troubleshooting
 
-문제가 발생하면:
-1. `/tfx-doctor` — 진단 실행
-2. `/tfx-doctor --fix` — 자동 수정
-3. `/tfx-doctor --reset` — 캐시 초기화 (HUD 이상 시)
+문제 발생 시 `/tfx-doctor` 실행. (`--fix` 자동 수정, `--reset` 캐시 초기화)

package/skills/tfx-doctor/SKILL.md

@@ -34,6 +34,7 @@ argument-hint: "[--fix|--reset]"
 - 플러그인 등록 상태
 - MCP 인벤토리 캐시
 - CLI 이슈 트래커
+- 잔존 팀(orphan teams) 감지 (`~/.claude/teams/`)
 
 ### 수정 모드 (`/tfx-doctor --fix`)
 

package/skills/tfx-gemini/SKILL.md

@@ -79,7 +79,4 @@ argument-hint: "\"작업 설명\" | N:gemini \"작업 설명\""
 
 ## Troubleshooting
 
-문제가 발생하면:
-1. `/tfx-doctor` — 진단 실행
-2. `/tfx-doctor --fix` — 자동 수정
-3. `/tfx-doctor --reset` — 캐시 초기화 (HUD 이상 시)
+문제 발생 시 `/tfx-doctor` 실행. (`--fix` 자동 수정, `--reset` 캐시 초기화)

package/skills/tfx-setup/SKILL.md

@@ -98,7 +98,4 @@ Bash("triflux doctor")
 
 ## Troubleshooting
 
-설정 후에도 문제가 있으면:
-1. `/tfx-doctor` — 상세 진단 실행
-2. `/tfx-doctor --fix` — 파일 동기화 + 캐시 정리
-3. `/tfx-doctor --reset` — 캐시 전체 초기화 (HUD 이상 시)
+문제 발생 시 `/tfx-doctor` 실행. (`--fix` 자동 수정, `--reset` 캐시 초기화)

package/skills/tfx-team/SKILL.md

@@ -11,17 +11,7 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
 > 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% 절감) |
+> v2.2 현재 — 슬림 래퍼 Agent로 Shift+Down 네비게이션 복원, Opus 토큰 77% 절감.
 
 ## 사용법
 
@@ -35,17 +25,21 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
 
 ## 실행 워크플로우
 
-### Phase 0: 사전 점검 정책 (출력 최소화)
+### Phase 0: 사전 점검 정책 (출력 최소화 + 즉시 spawn)
 
-세션 시작 전 점검은 **리드 포그라운드에서 단계별로 장황하게 출력하지 않는다.**
+> **[필수] Agent spawn 지연 금지 — preflight와 Agent 생성을 병렬로 실행한다.**
+> Lead가 preflight를 순차 완료한 뒤 Agent를 spawn하면 사용자 체감 지연이 발생한다.
+> 수동 모드(`N:agent`)에서는 입력 파싱 직후 TeamCreate + Agent spawn을 먼저 시작하고,
+> preflight는 **동시에 병렬**로 수행한다. preflight 실패 시에만 Agent를 중단한다.
 
 - 원칙:
-  - 사전 점검은 워커 생성과 **비동기 병렬**로 수행한다.
+  - **수동 모드:** Phase 1 파싱 → Phase 3a~3c(TeamCreate + Agent spawn) + Phase 0(preflight) **동시 병렬**
+  - **자동 모드:** Phase 0(preflight) + Phase 2(triage) **동시 병렬** → Phase 3
   - 사용자가 요청하지 않으면 `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"`
+- 권장 체크 예시 (단일 Bash로 통합):
+  - `curl -sf http://127.0.0.1:27888/status >/dev/null && test -f ~/.claude/scripts/tfx-route.sh && echo "preflight: ok" || echo "preflight: FAIL"`
 - 실패 시에만 상세를 노출한다:
   - `tfx-route.sh` 없음
   - Hub 비정상/미기동
@@ -136,6 +130,11 @@ for each assignment in assignments (index i):
 
 #### Step 3c: 슬림 래퍼 Agent 실행 (v2.2 네비게이션 복원)
 
+> **[필수] Codex/Gemini 서브태스크는 워커 수에 관계없이 반드시 Agent 래퍼를 spawn해야 한다.**
+> 단일 워커(1:gemini 등)여도 Lead가 직접 Bash를 실행하면 안 된다.
+> Agent 래퍼를 생략하면 Shift+Down 네비게이션에 워커가 등록되지 않아 v2.2의 핵심 가치가 사라진다.
+> Lead가 "효율적"이라고 판단해서 Agent를 건너뛰는 것은 금지한다.
+
 Codex/Gemini 서브태스크마다 최소 프롬프트의 Agent를 spawn하여 네비게이션에 등록한다.
 Agent 내부에서 `Bash(tfx-route.sh)` 1회 실행 후 결과 보고하고 종료한다.
 
@@ -157,17 +156,14 @@ for each item in runQueue where item.cli in ["codex", "gemini"]:
   })
 ```
 
-슬림 래퍼 프롬프트 (~100 토큰):
-```
-Bash 1회 실행 후 종료.
+슬림 래퍼 프롬프트는 `hub/team/native.mjs`의 `buildSlimWrapperPrompt()`가 **단일 truth source**.
+핵심 동작: Bash 1회 실행(tfx-route.sh) → TaskUpdate(completed) + SendMessage → 종료.
+status는 "completed"만 사용. 실패 여부는 `metadata.result`로 구분.
 
-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`에 정의.
+> **[금지] Lead 또는 Agent 래퍼가 `gemini -y -p "..."` 또는 `codex exec "..."`를 직접 호출하면 안 된다.**
+> 직접 호출하면 tfx-route.sh의 모델 지정(`-m gemini-3.1-pro-preview`), MCP 필터, 팀 bridge 연동,
+> Windows 호환 경로, 타임아웃, 후처리(토큰 추적/이슈 로깅)가 모두 누락된다.
+> 반드시 `bash ~/.claude/scripts/tfx-route.sh {role} '{subtask}' {mcp_profile}`을 통해 실행해야 한다.
 
 **핵심 차이 vs v2:** 프롬프트 ~100 토큰 (v2의 ~500), task claim/complete/report는 tfx-route.sh Hub bridge가 수행.
 
@@ -198,8 +194,11 @@ Agent({
 
 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)"
+3. 성공 시 TaskUpdate(status: completed, metadata: {result: 'success'}) + SendMessage(to: team-lead)
+4. 실패 시 TaskUpdate(status: completed, metadata: {result: 'failed', error: '에러 요약'}) + SendMessage(to: team-lead)
+
+중요: status는 'completed'만 사용. 'failed'는 API 미지원. 실패 여부는 metadata.result로 구분.
+어떤 경우에도 TaskUpdate + SendMessage 후 반드시 종료하라."
 })
 ```
 
@@ -208,8 +207,8 @@ Agent({
 ```
 "팀 '{teamName}' 생성 완료.
 Codex/Gemini 워커가 슬림 래퍼 Agent로 네비게이션에 등록되었습니다.
-Shift+Down으로 다음 워커, Shift+Tab/Shift+Left로 이전 워커 전환이 가능합니다.
-(Shift+Up은 일부 환경에서 동작하지 않을 수 있음)"
+Shift+Down으로 다음 워커 (마지막→리드 wrap), Shift+Tab으로 이전 워커 전환이 가능합니다.
+(Shift+Up은 Claude Code 미지원 — 대부분 터미널에서 scroll-up으로 먹힘)"
 ```
 
 ### Phase 4: 결과 수집 (truth source = team_task_list)
@@ -221,9 +220,10 @@ Shift+Down으로 다음 워커, Shift+Tab/Shift+Left로 이전 워커 전환이
 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으로 재시도한다.
+3. `completed` 상태이지만 `metadata.result == "failed"`인 task가 있으면 Claude fallback으로 재시도한다.
 4. 재시도 후 다시 `team_task_list`를 조회해 최종 상태를 확정한다.
 5. `send-message`와 `/bridge/result(task.result)` 이벤트는 진행 관찰 채널로 사용하고, 최종 판정은 반드시 `team_task_list` 기준으로 한다.
+6. Hub bridge의 `task-update`에서는 `status: "failed"`를 그대로 사용한다 (Hub API는 자체 상태 관리). Claude Code `TaskUpdate`만 `"completed"` + `metadata.result`로 구분한다.
 
 종합 보고서 예시:
 ```markdown
@@ -236,42 +236,29 @@ 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: 정리 (반드시 실행)
 
-슬림 래퍼 Agent는 Bash 완료 후 자동 종료된다.
-claude 타입 Agent와 슬림 래퍼 Agent 모두 완료 확인 후 `TeamDelete()`를 호출한다.
+> **[필수] Phase 5는 성공/실패에 관계없이 반드시 실행해야 한다.**
+> 워커 실패, Bash 에러, fallback 실패 등 어떤 상황에서도 TeamDelete를 건너뛰면 안 된다.
+> TeamDelete를 하지 않으면 `~/.claude/teams/{teamName}/`이 잔존하여 OMC hook이 "team executing"을
+> 반복 감지하는 무한 루프에 빠진다.
 
-> **중요:** 슬림 래퍼 Agent가 아직 실행 중이면 `TeamDelete`가 실패할 수 있다. 모든 워커 완료를 확인한 뒤 삭제한다.
+정리 순서:
+1. 모든 백그라운드 Agent 완료를 **최대 30초** 대기한다.
+2. 30초 후에도 미완료 Agent가 있으면 대기를 중단하고 정리를 진행한다.
+3. `TeamDelete()`를 호출한다.
+4. TeamDelete가 실패하면 (활성 멤버 잔존) 수동 정리를 안내한다:
+   ```
+   rm -rf ~/.claude/teams/{teamName}/ ~/.claude/tasks/{teamName}/
+   ```
+5. 종합 보고서를 출력한다.
 
 ### 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 전체화면"
-```
+--tmux 플래그 시 기존 v1 방식으로 실행: Bash("node {PKG_ROOT}/bin/triflux.mjs team --no-attach --agents {agents} \\\"{task}\\\"")
+이후 사용자에게 tmux 세션 연결 안내.
 
 ## 에이전트 매핑
-
-| 분류 결과 | 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` 타입)에만 사용한다.
+> 에이전트 매핑: codex/gemini → tfx-route.sh, claude → Agent(subagent_type) 직접 실행. 상세는 Phase 3c/3d 참조.
 
 ## 전제 조건
 
@@ -289,10 +276,14 @@ Bash("node {PKG_ROOT}/bin/triflux.mjs team --no-attach --agents {agents.join(','
 | tfx-route.sh 없음 | `tfx setup` 실행 안내 |
 | CLI 미설치 (codex/gemini) | 해당 서브태스크를 claude 워커로 대체 |
 | Codex 분류 실패 | Opus 직접 분류+분해 |
-| Bash 실행 실패 (Lead) | task를 `failed`로 마킹 후 Claude fallback 재시도 |
+| Bash 실행 실패 (Lead) | task를 `completed` + `metadata.result: "failed"`로 마킹 후 Claude fallback 재시도 |
 | `team_task_list` 조회 실패 | `/bridge/result`/stdout로 임시 관찰 후 bridge 복구 뒤 상태 재검증 |
 | claude fallback 실패 | 실패 task 목록/원인 요약 후 사용자 승인 대기 |
 
+> **[중요] TaskUpdate 상태값 제약:** Claude Code API는 `pending`, `in_progress`, `completed`, `deleted`만 지원한다.
+> `failed` 상태는 존재하지 않으므로 절대 사용하지 마라. 실패는 `status: "completed"` + `metadata: {result: "failed"}`로 표현한다.
+> Hub bridge API(`/bridge/team/task-update`)는 자체 상태 관리이므로 `"failed"` 사용 가능.
+
 ## 관련
 
 | 항목 | 설명 |