triflux 7.1.4 → 7.2.2

package/scripts/tmp-cleanup.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * tmp-cleanup.mjs — triflux 임시 파일 자동 정리
+ * 7일 이상 된 파일을 삭제한다.
+ * SessionStart 훅 또는 독립 실행으로 사용.
+ */
+import { existsSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7일
+
+// tfx-psmux-check.json은 guard가 TTL을 직접 관리하므로 제외
+const SKIP_FILES = new Set(["tfx-psmux-check.json"]);
+
+/**
+ * 7일 이상 된 임시 파일/디렉터리를 정리한다.
+ * @returns {number} 삭제된 항목 수
+ */
+export async function cleanupTmpFiles() {
+  const now = Date.now();
+  let cleaned = 0;
+  const tmp = tmpdir();
+
+  // 1) tmpdir() 직하위의 tfx-* 패턴 항목 정리
+  let topEntries;
+  try { topEntries = readdirSync(tmp); } catch { topEntries = []; }
+
+  for (const entry of topEntries) {
+    if (!entry.startsWith("tfx-")) continue;
+    if (SKIP_FILES.has(entry)) continue;
+
+    const full = join(tmp, entry);
+    try {
+      const stat = statSync(full);
+      if (now - stat.mtimeMs > MAX_AGE_MS) {
+        rmSync(full, { recursive: true, force: true });
+        cleaned++;
+      }
+    } catch { /* 권한 에러 등 무시 */ }
+  }
+
+  // 2) tfx-headless/ 내 오래된 결과 파일 정리 (디렉터리 자체는 유지)
+  const headlessDir = join(tmp, "tfx-headless");
+  if (existsSync(headlessDir)) {
+    let entries;
+    try { entries = readdirSync(headlessDir); } catch { entries = []; }
+
+    for (const entry of entries) {
+      if (SKIP_FILES.has(entry)) continue;
+      const full = join(headlessDir, entry);
+      try {
+        const stat = statSync(full);
+        if (now - stat.mtimeMs > MAX_AGE_MS) {
+          rmSync(full, { recursive: true, force: true });
+          cleaned++;
+        }
+      } catch { /* 권한 에러 등 무시 */ }
+    }
+  }
+
+  return cleaned;
+}
+
+// 독립 실행 시 결과를 stdout으로 출력 (SessionStart 훅 호환)
+if (process.argv[1]) {
+  const { fileURLToPath } = await import("node:url");
+  if (fileURLToPath(import.meta.url) === process.argv[1]) {
+    const cleaned = await cleanupTmpFiles();
+    if (cleaned > 0) {
+      process.stdout.write(JSON.stringify({ message: `tfx-cleanup: ${cleaned} files removed` }));
+    }
+  }
+}

package/skills/tfx-auto/SKILL.md

@@ -1,278 +1,279 @@
----
-name: tfx-auto
-description: 통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반.
-triggers:
-  - tfx-auto
-  - implement
-  - build
-  - research
-  - brainstorm
-  - design
-  - test
-  - analyze
-  - troubleshoot
-  - improve
-  - cleanup
-  - explain
-  - document
-  - pm
-  - reflect
-  - estimate
-  - spec-panel
-  - business-panel
-  - index-repo
-argument-hint: "<command|task> [args...]"
----
-
-# tfx-auto — 통합 CLI 오케스트레이터
-
-> **MANDATORY RULES**
->
-> 1. **실행**: CLI 에이전트는 반드시 `Bash("bash ~/.claude/scripts/tfx-route.sh ...")`. Claude 네이티브(explore/verifier/test-engineer/qa-tester)만 `Agent()`.
-> 2. **비용**: Codex 우선 → Gemini → Claude 최후 수단. `claude` 선택 전 "Codex로 가능한가?" 재확인.
-> 3. **DAG**: SEQUENTIAL/DAG이면 레벨 기반 순차 실행. `.omc/context/{sid}/` 생성, context_output 저장, 실패 시 후속 SKIP.
-> 4. **트리아지**: Codex `--full-auto` 분류 + Opus 인라인 분해. Agent 스폰 금지.
-> 5. **thorough**: `-t`/`--thorough` 시 파이프라인 init 필수. 커맨드 숏컷은 항상 quick.
-
-## 모드
-
-| 입력 형식 | 모드 | 트리아지 |
-|-----------|------|----------|
-| `/implement JWT 추가` | 커맨드 숏컷 (quick) | 없음 (즉시 실행) |
-| `/tfx-auto "리팩터링 + UI"` | 자동 (quick) | Codex 분류 → Opus 분해 |
-| `/tfx-auto -t "리팩터링 + UI"` | 자동 (thorough) | Codex 분류 → Opus 분해 → Pipeline |
-| `/tfx-auto --thorough "리팩터링"` | 자동 (thorough) | `-t` 동일 |
-| `/tfx-auto 3:codex "리뷰"` | 수동 (quick) | Opus 분해만 |
-
-> **tfx-auto는 `--quick`이 기본.** 커맨드 숏컷·단일 실행에서 plan/verify 오버헤드가 불필요하기 때문.
-> 멀티 태스크 시 tfx-multi로 전환되면 tfx-multi의 기본값(`--thorough`)이 적용된다.
-
-## 커맨드 숏컷
-
-커맨드명 매칭 시 트리아지 없이 즉시 실행. 패턴: `Bash("bash ~/.claude/scripts/tfx-route.sh {에이전트} '{PROMPT}' {MCP}")`.
-
-### Codex 직행
-
-| 커맨드 | 에이전트 | MCP |
-|--------|---------|-----|
-| `implement` | executor | implement |
-| `build` | build-fixer | implement |
-| `research` | document-specialist | analyze |
-| `brainstorm` | analyst | analyze |
-| `design` | architect | analyze |
-| `troubleshoot` | debugger | implement |
-| `cleanup` | executor | implement |
-| `pm` | planner | analyze |
-
-### 2단계: `improve`
-
-1단계 `code-reviewer '{PROMPT}' review` → 사용자 승인 → 2단계 `executor '리뷰 반영: {요약}' implement`
-
-### 병렬
-
-| 커맨드 | 에이전트들 (병렬, run_in_background=true) | MCP |
-|--------|------------------------------------------|-----|
-| `analyze` | quality-reviewer + security-reviewer | review |
-| `spec-panel` | architect + analyst + critic | analyze |
-| `business-panel` | analyst + architect | analyze |
-
-### Gemini 직행
-
-| 커맨드 | 에이전트 | MCP |
-|--------|---------|-----|
-| `explain` | writer | docs |
-| `document` | writer | docs |
-
-### Claude 네이티브
-
-| 커맨드 | 실행 |
-|--------|------|
-| `test` | `Agent(subagent_type="oh-my-claudecode:test-engineer", model="sonnet")` |
-| `reflect` | `Agent(subagent_type="oh-my-claudecode:verifier", model="sonnet")` |
-
-### 복합
-
-| 커맨드 | 흐름 |
-|--------|------|
-| `estimate` | explore(haiku) → analyst(codex): 영향범위, 복잡도(S/M/L/XL), 리스크 |
-| `index-repo` | explore(haiku) × 2 → Write(PROJECT_INDEX.md). mode=quick/update/full |
-
-## 트리아지
-
-**자동 모드:**
-1. Codex 분류: `codex exec --full-auto --skip-git-repo-check` → JSON `{parts: [{description, agent: "codex|gemini|claude"}]}`
-2. Opus 인라인 분해: `{graph_type: "INDEPENDENT|SEQUENTIAL|DAG", subtasks: [{id, description, scope, agent, mcp_profile, depends_on, context_output, context_input}]}`
-3. 실패 시 Opus가 직접 분류+분해
-
-**수동 모드 (`N:agent_type`):** Codex 분류 건너뜀 → Opus가 N개 서브태스크 분해. N > 10 거부.
-
-## --thorough 모드
-
-`-t` 또는 `--thorough` 플래그 시 파이프라인 기반 실행. 커맨드 숏컷에서는 무시된다.
-
-```
-분기점은 "실행 전략"이지 "계획"이 아님:
-
-TRIAGE
-  │
-  ├─ [thorough] → PIPELINE INIT(plan) → PLAN → PRD → [APPROVAL]
-  │                                                      │
-  │                                      ┌───────────────┤
-  │                                      │               │
-  │                                  [1 task]        [2+ tasks]
-  │                                      │               │
-  │                                  AUTO 직접 실행   TEAM EXEC (multi Phase 3)
-  │                                      │               │
-  │                                      └───────┬───────┘
-  │                                              │
-  │                                          VERIFY → FIX loop → COMPLETE
-  │
-  └─ [quick] → [1 task] → fire-and-forget
-               [2+ tasks] → TEAM EXEC → COLLECT → CLEANUP
-```
-
-### 단일 태스크 thorough
-
-1. `Bash("node hub/bridge.mjs pipeline-init --team ${sid}")` — 파이프라인 초기화 (phase: plan)
-2. Plan: Codex architect → 결과를 `pipeline.writePlanFile()` 저장
-3. PRD: Codex analyst → acceptance criteria 확정
-4. `pipeline_advance_gated` → [Approval Gate] → 사용자 승인 대기
-5. Exec: tfx-auto 직접 실행 (아래 "실행" 섹션)
-6. Verify: Codex verifier → 검증
-7. 실패 시 Fix loop (최대 3회) → Exec 재실행
-8. Complete
-
-### 멀티 태스크 thorough
-
-Plan/PRD/Approval은 tfx-auto에서 실행, 그 후 tfx-multi Phase 3로 전환.
-서브태스크 배열 + `thorough: true` 신호를 함께 전달하여 multi 측에서 verify/fix를 수행.
-
-## 멀티 태스크 라우팅 (트리아지 후)
-
-> **트리아지 결과에 따라 실행 경로 결정.**
-> v6.0.0부터 CLI 워커는 **Lead-Direct Headless** (psmux)가 기본. Agent 래퍼 불필요.
-
-| 조건 | 실행 경로 | 엔진 |
-|------|----------|------|
-| 1개 + quick | tfx-auto 직접 실행 (fire-and-forget) | tfx-route.sh |
-| 1개 + thorough | tfx-auto 직접 실행 + verify/fix loop | tfx-route.sh |
-| 2개+ + quick | **headless 직접 실행** (WT 자동 팝업) | headless.mjs |
-| 2개+ + thorough | Plan/PRD/Approval 후 → headless + verify/fix | headless.mjs |
-| psmux 미설치 fallback | Native Teams (Agent slim wrapper) | native.mjs |
-
-> **MANDATORY: 2개+ 서브태스크 시 headless 엔진 필수**
-> `Agent()` 백그라운드나 `Bash(tfx-route.sh)` 개별 호출로 대체 금지.
-> 반드시 아래 `Bash("tfx multi ...")` 명령으로 headless 엔진에 위임한다.
-
-**전환 방법:**
-
-```
-thorough = args에 -t 또는 --thorough 포함
-
-if subtasks.length >= 2:
-  if psmux 설치됨:
-    → Bash("tfx multi --teammate-mode headless --auto-attach --assign 'cli:prompt:role' ...")
-    → if thorough: verify → fix loop
-  else:
-    → fallback: tfx-multi Phase 3 Native Teams (Agent slim wrapper)
-else:
-  if thorough:
-    → Pipeline init → Plan → PRD → Approval → 직접 실행 → Verify → Fix loop
-  else:
-    → tfx-auto 직접 실행 (아래)
-```
-
-## 실행
-
-### CLI 에이전트 (Codex/Gemini)
-
-```bash
-# Level 0 / INDEPENDENT
-Bash("bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile}", run_in_background=true)
-
-# Level 1+ (컨텍스트 의존) — 4번째=timeout(빈값), 5번째=context_file
-Bash("bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile} '' .omc/context/{sid}/combined-{tid}.md", run_in_background=true)
-```
-
-### Claude 네이티브
-
-```
-Agent(subagent_type="oh-my-claudecode:{agent}", model="{model}", prompt="{prompt}", run_in_background=true)
-# 컨텍스트 있으면 prompt에 <prior_context>...</prior_context> 추가
-```
-
-### 에이전트 매핑
-
-| 입력 | CLI | MCP |
-|------|-----|-----|
-| codex / executor / debugger / deep-executor | Codex | implement |
-| architect / planner / critic / analyst | Codex (xhigh) | analyze |
-| scientist / document-specialist | Codex | analyze |
-| code-reviewer / security-reviewer / quality-reviewer | Codex (review) | review |
-| gemini / designer / writer | Gemini | docs |
-| claude / explore / verifier / test-engineer / qa-tester | Claude native | — |
-
-### MCP 프로필 자동 결정
-
-| 에이전트 | MCP |
-|----------|-----|
-| executor, build-fixer, debugger, deep-executor | implement |
-| architect, planner, critic, analyst, scientist, document-specialist | analyze |
-| code-reviewer, security-reviewer, quality-reviewer | review |
-| designer, writer | docs |
-
-### 결과 파싱
-
-여기서 `failed`는 `tfx-route.sh`/CLI 종료 결과를 뜻한다. Claude Code `TaskUpdate` 상태값이 아니다.
-
-| exit_code + status | 사용할 출력 |
-|--------------------|-----------|
-| 0 + success | `=== OUTPUT ===` 섹션 |
-| 124 + timeout | `=== PARTIAL OUTPUT ===` |
-| ≠0 + failed | STDERR → Claude fallback |
-
-OUTPUT 추출: `echo "$result" | sed -n '/^=== OUTPUT ===/,/^=== /{/^=== OUTPUT ===/d;/^=== /d;p}'`
-
-### 실패 처리
-
-1차 → `Agent(subagent_type="oh-my-claudecode:executor", model="sonnet")` fallback.
-2차 연속 실패 → 실패 보고 + 성공 결과만 종합.
-
-### 보고 형식
-
-```markdown
-## tfx-auto 완료
-**모드**: {auto|manual} | **그래프**: {type} | **레벨**: {N}
-| # | 서브태스크 | Agent | CLI | MCP | 레벨 | 상태 | 시간 |
-### 워커 {n}: {제목}
-(출력 요약)
-### Token Savings Report
-(node ~/.claude/scripts/token-snapshot.mjs report {session-id})
-```
-
-## 필수 조건
-
-- `~/.claude/scripts/tfx-route.sh` (필수)
-- codex: `npm install -g @openai/codex` | gemini: `npm install -g @google/gemini-cli`
-
-## 에러 레퍼런스
-
-| 에러 | 처리 |
-|------|------|
-| `tfx-route.sh: not found` | tfx-route.sh 생성 |
-| `codex/gemini: not found` | npm install -g |
-| timeout / failed (`tfx-route.sh` 결과) | stderr → Claude fallback |
-| N > 10 | 10 이하로 조정 |
-| 순환 의존 | 분해 재시도 |
-| 컨텍스트 > 32KB | 비례 절삭 |
-
-> Claude Code `TaskUpdate`를 사용할 때는 `status: "failed"`를 쓰지 않는다.
-> 실패 보고는 `status: "completed"` + `metadata.result: "failed"`로 표현한다.
-
-## Troubleshooting
-
-`/tfx-doctor` 진단 | `/tfx-doctor --fix` 자동 수정 | `/tfx-doctor --reset` 캐시 초기화
-
-## 상세 레퍼런스
-
-DAG 알고리즘, 컨텍스트 머지 규칙, 토큰 스냅샷, 보고서 상세는 `scripts/tfx-route.sh` 내부 주석 및 `hub/` 모듈 참조.
+---
+name: tfx-auto
+description: 통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반.
+triggers:
+  - tfx-auto
+  - implement
+  - build
+  - research
+  - brainstorm
+  - design
+  - test
+  - analyze
+  - troubleshoot
+  - improve
+  - cleanup
+  - explain
+  - document
+  - pm
+  - reflect
+  - estimate
+  - spec-panel
+  - business-panel
+  - index-repo
+argument-hint: "<command|task> [args...]"
+---
+
+# tfx-auto — 통합 CLI 오케스트레이터
+
+> **MANDATORY RULES**
+>
+> 1. **실행**: CLI 에이전트는 반드시 `Bash("bash ~/.claude/scripts/tfx-route.sh ...")`. Claude 네이티브(explore/verifier/test-engineer/qa-tester)만 `Agent()`.
+> 2. **비용**: Codex 우선 → Gemini → Claude 최후 수단. `claude` 선택 전 "Codex로 가능한가?" 재확인.
+> 3. **DAG**: SEQUENTIAL/DAG이면 레벨 기반 순차 실행. `.omc/context/{sid}/` 생성, context_output 저장, 실패 시 후속 SKIP.
+> 4. **트리아지**: Codex `--full-auto` 분류 + Opus 인라인 분해. Agent 스폰 금지.
+> 5. **thorough**: `-t`/`--thorough` 시 파이프라인 init 필수. 커맨드 숏컷은 항상 quick.
+
+## 모드
+
+| 입력 형식 | 모드 | 트리아지 |
+|-----------|------|----------|
+| `/implement JWT 추가` | 커맨드 숏컷 (quick) | 없음 (즉시 실행) |
+| `/tfx-auto "리팩터링 + UI"` | 자동 (quick) | Codex 분류 → Opus 분해 |
+| `/tfx-auto -t "리팩터링 + UI"` | 자동 (thorough) | Codex 분류 → Opus 분해 → Pipeline |
+| `/tfx-auto --thorough "리팩터링"` | 자동 (thorough) | `-t` 동일 |
+| `/tfx-auto 3:codex "리뷰"` | 수동 (quick) | Opus 분해만 |
+
+> **tfx-auto는 `--quick`이 기본.** 커맨드 숏컷·단일 실행에서 plan/verify 오버헤드가 불필요하기 때문.
+> 멀티 태스크 시 tfx-multi로 전환되면 tfx-multi의 기본값(`--thorough`)이 적용된다.
+
+## 커맨드 숏컷
+
+커맨드명 매칭 시 트리아지 없이 즉시 실행. 패턴: `Bash("bash ~/.claude/scripts/tfx-route.sh {에이전트} '{PROMPT}' {MCP}")`.
+
+### Codex 직행
+
+| 커맨드 | 에이전트 | MCP |
+|--------|---------|-----|
+| `implement` | executor | implement |
+| `build` | build-fixer | implement |
+| `research` | document-specialist | analyze |
+| `brainstorm` | analyst | analyze |
+| `design` | architect | analyze |
+| `troubleshoot` | debugger | implement |
+| `cleanup` | executor | implement |
+| `pm` | planner | analyze |
+
+### 2단계: `improve`
+
+1단계 `code-reviewer '{PROMPT}' review` → 사용자 승인 → 2단계 `executor '리뷰 반영: {요약}' implement`
+
+### 병렬
+
+| 커맨드 | 에이전트들 (병렬, run_in_background=true) | MCP |
+|--------|------------------------------------------|-----|
+| `analyze` | quality-reviewer + security-reviewer | review |
+| `spec-panel` | architect + analyst + critic | analyze |
+| `business-panel` | analyst + architect | analyze |
+
+### Gemini 직행
+
+| 커맨드 | 에이전트 | MCP |
+|--------|---------|-----|
+| `explain` | writer | docs |
+| `document` | writer | docs |
+
+### Claude 네이티브
+
+| 커맨드 | 실행 |
+|--------|------|
+| `test` | `Agent(subagent_type="oh-my-claudecode:test-engineer", model="sonnet")` |
+| `reflect` | `Bash(tfx-route.sh verifier '{PROMPT}' review)` (기본) / `Agent(subagent_type="oh-my-claudecode:verifier", model="sonnet")` (TFX_VERIFIER_OVERRIDE=claude 시) |
+
+### 복합
+
+| 커맨드 | 흐름 |
+|--------|------|
+| `estimate` | explore(haiku) → analyst(codex): 영향범위, 복잡도(S/M/L/XL), 리스크 |
+| `index-repo` | explore(haiku) × 2 → Write(PROJECT_INDEX.md). mode=quick/update/full |
+
+## 트리아지
+
+**자동 모드:**
+1. Codex 분류: `codex exec --full-auto --skip-git-repo-check` → JSON `{parts: [{description, agent: "codex|gemini|claude"}]}`
+2. Opus 인라인 분해: `{graph_type: "INDEPENDENT|SEQUENTIAL|DAG", subtasks: [{id, description, scope, agent, mcp_profile, depends_on, context_output, context_input}]}`
+3. 실패 시 Opus가 직접 분류+분해
+
+**수동 모드 (`N:agent_type`):** Codex 분류 건너뜀 → Opus가 N개 서브태스크 분해. N > 10 거부.
+
+## --thorough 모드
+
+`-t` 또는 `--thorough` 플래그 시 파이프라인 기반 실행. 커맨드 숏컷에서는 무시된다.
+
+```
+분기점은 "실행 전략"이지 "계획"이 아님:
+
+TRIAGE
+  │
+  ├─ [thorough] → PIPELINE INIT(plan) → PLAN → PRD → [APPROVAL]
+  │                                                      │
+  │                                      ┌───────────────┤
+  │                                      │               │
+  │                                  [1 task]        [2+ tasks]
+  │                                      │               │
+  │                                  AUTO 직접 실행   TEAM EXEC (multi Phase 3)
+  │                                      │               │
+  │                                      └───────┬───────┘
+  │                                              │
+  │                                          VERIFY → FIX loop → COMPLETE
+  │
+  └─ [quick] → [1 task] → fire-and-forget
+               [2+ tasks] → TEAM EXEC → COLLECT → CLEANUP
+```
+
+### 단일 태스크 thorough
+
+1. `Bash("node hub/bridge.mjs pipeline-init --team ${sid}")` — 파이프라인 초기화 (phase: plan)
+2. Plan: Codex architect → 결과를 `pipeline.writePlanFile()` 저장
+3. PRD: Codex analyst → acceptance criteria 확정
+4. `pipeline_advance_gated` → [Approval Gate] → 사용자 승인 대기
+5. Exec: tfx-auto 직접 실행 (아래 "실행" 섹션)
+6. Verify: Codex verifier → 검증
+7. 실패 시 Fix loop (최대 3회) → Exec 재실행
+8. Complete
+
+### 멀티 태스크 thorough
+
+Plan/PRD/Approval은 tfx-auto에서 실행, 그 후 tfx-multi Phase 3로 전환.
+서브태스크 배열 + `thorough: true` 신호를 함께 전달하여 multi 측에서 verify/fix를 수행.
+
+## 멀티 태스크 라우팅 (트리아지 후)
+
+> **트리아지 결과에 따라 실행 경로 결정.**
+> v6.0.0부터 CLI 워커는 **Lead-Direct Headless** (psmux)가 기본. Agent 래퍼 불필요.
+
+| 조건 | 실행 경로 | 엔진 |
+|------|----------|------|
+| 1개 + quick | tfx-auto 직접 실행 (fire-and-forget) | tfx-route.sh |
+| 1개 + thorough | tfx-auto 직접 실행 + verify/fix loop | tfx-route.sh |
+| 2개+ + quick | **headless 직접 실행** (WT 자동 팝업) | headless.mjs |
+| 2개+ + thorough | Plan/PRD/Approval 후 → headless + verify/fix | headless.mjs |
+| psmux 미설치 fallback | Native Teams (Agent slim wrapper) | native.mjs |
+
+> **MANDATORY: 2개+ 서브태스크 시 headless 엔진 필수**
+> `Agent()` 백그라운드나 `Bash(tfx-route.sh)` 개별 호출로 대체 금지.
+> 반드시 아래 `Bash("tfx multi ...")` 명령으로 headless 엔진에 위임한다.
+
+**전환 방법:**
+
+```
+thorough = args에 -t 또는 --thorough 포함
+
+if subtasks.length >= 2:
+  if psmux 설치됨:
+    → Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'cli:prompt:role' ...")
+    → if thorough: verify → fix loop
+  else:
+    → fallback: tfx-multi Phase 3 Native Teams (Agent slim wrapper)
+else:
+  if thorough:
+    → Pipeline init → Plan → PRD → Approval → 직접 실행 → Verify → Fix loop
+  else:
+    → tfx-auto 직접 실행 (아래)
+```
+
+## 실행
+
+### CLI 에이전트 (Codex/Gemini)
+
+```bash
+# Level 0 / INDEPENDENT
+Bash("bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile}", run_in_background=true)
+
+# Level 1+ (컨텍스트 의존) — 4번째=timeout(빈값), 5번째=context_file
+Bash("bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile} '' .omc/context/{sid}/combined-{tid}.md", run_in_background=true)
+```
+
+### Claude 네이티브
+
+```
+Agent(subagent_type="oh-my-claudecode:{agent}", model="{model}", prompt="{prompt}", run_in_background=true)
+# 컨텍스트 있으면 prompt에 <prior_context>...</prior_context> 추가
+```
+
+### 에이전트 매핑
+
+| 입력 | CLI | MCP |
+|------|-----|-----|
+| codex / executor / build-fixer / spark / debugger / deep-executor | Codex | implement |
+| architect / planner / critic / analyst | Codex (xhigh) | analyze |
+| scientist / document-specialist | Codex | analyze |
+| code-reviewer / security-reviewer / quality-reviewer | Codex (review) | review |
+| gemini / designer / writer | Gemini | docs |
+| explore / test-engineer / qa-tester | Claude native | — |
+| verifier | Codex review (기본) / Claude native (TFX_VERIFIER_OVERRIDE=claude 시) | review / — |
+
+### MCP 프로필 자동 결정
+
+| 에이전트 | MCP |
+|----------|-----|
+| executor, build-fixer, spark, debugger, deep-executor | implement |
+| architect, planner, critic, analyst, scientist, document-specialist | analyze |
+| code-reviewer, security-reviewer, quality-reviewer | review |
+| designer, writer | docs |
+
+### 결과 파싱
+
+여기서 `failed`는 `tfx-route.sh`/CLI 종료 결과를 뜻한다. Claude Code `TaskUpdate` 상태값이 아니다.
+
+| exit_code + status | 사용할 출력 |
+|--------------------|-----------|
+| 0 + success | `=== OUTPUT ===` 섹션 |
+| 124 + timeout | `=== PARTIAL OUTPUT ===` |
+| ≠0 + failed | STDERR → Claude fallback |
+
+OUTPUT 추출: `echo "$result" | sed -n '/^=== OUTPUT ===/,/^=== /{/^=== OUTPUT ===/d;/^=== /d;p}'`
+
+### 실패 처리
+
+1차 → `Agent(subagent_type="oh-my-claudecode:executor", model="sonnet")` fallback.
+2차 연속 실패 → 실패 보고 + 성공 결과만 종합.
+
+### 보고 형식
+
+```markdown
+## tfx-auto 완료
+**모드**: {auto|manual} | **그래프**: {type} | **레벨**: {N}
+| # | 서브태스크 | Agent | CLI | MCP | 레벨 | 상태 | 시간 |
+### 워커 {n}: {제목}
+(출력 요약)
+### Token Savings Report
+(node ~/.claude/scripts/token-snapshot.mjs report {session-id})
+```
+
+## 필수 조건
+
+- `~/.claude/scripts/tfx-route.sh` (필수)
+- codex: `npm install -g @openai/codex` | gemini: `npm install -g @google/gemini-cli`
+
+## 에러 레퍼런스
+
+| 에러 | 처리 |
+|------|------|
+| `tfx-route.sh: not found` | tfx-route.sh 생성 |
+| `codex/gemini: not found` | npm install -g |
+| timeout / failed (`tfx-route.sh` 결과) | stderr → Claude fallback |
+| N > 10 | 10 이하로 조정 |
+| 순환 의존 | 분해 재시도 |
+| 컨텍스트 > 32KB | 비례 절삭 |
+
+> Claude Code `TaskUpdate`를 사용할 때는 `status: "failed"`를 쓰지 않는다.
+> 실패 보고는 `status: "completed"` + `metadata.result: "failed"`로 표현한다.
+
+## Troubleshooting
+
+`/tfx-doctor` 진단 | `/tfx-doctor --fix` 자동 수정 | `/tfx-doctor --reset` 캐시 초기화
+
+## 상세 레퍼런스
+
+DAG 알고리즘, 컨텍스트 머지 규칙, 토큰 스냅샷, 보고서 상세는 `scripts/tfx-route.sh` 내부 주석 및 `hub/` 모듈 참조.