triflux 9.8.7 → 10.0.0-alpha.2

package/bin/triflux.mjs

@@ -16,10 +16,12 @@ import { ensureGeminiProfiles } from "../scripts/lib/gemini-profiles.mjs";
 import { probePsmuxSupport, formatPsmuxInstallGuidance, formatPsmuxUpdateGuidance } from "../scripts/lib/psmux-info.mjs";
 import {
   addRegistryServer,
+  createDefaultRegistry,
   inspectRegistry,
   inspectRegistryStatus,
   removeRegistryServer,
   removeServerFromTargets,
+  saveRegistry,
   syncRegistryTargets,
 } from "../scripts/lib/mcp-guard-engine.mjs";
 import {
@@ -1181,13 +1183,10 @@ function buildMcpStatusRows(statusInfo) {
 }
 
 function ensureValidRegistryState() {
-  const registryState = inspectRegistry();
+  let registryState = inspectRegistry();
   if (!registryState.exists) {
-    throw createCliError(`MCP registry missing: ${registryState.path}`, {
-      exitCode: EXIT_CONFIG_ERROR,
-      reason: "configError",
-      fix: "config/mcp-registry.json을 복원하거나 `tfx mcp add <name> --url <url>`로 다시 생성하세요.",
-    });
+    saveRegistry(createDefaultRegistry());
+    registryState = inspectRegistry();
   }
   if (!registryState.valid) {
     throw createCliError(`MCP registry invalid: ${registryState.errors.join("; ")}`, {
@@ -1388,9 +1387,13 @@ async function cmdDoctor(options = {}) {
         warn(`MCP registry 자동 동기화 실패: ${error.message}`);
       }
     } else if (registryStateForFix.exists) {
-      warn("MCP registry invalid — auto sync 건너뜀");
+      saveRegistry(createDefaultRegistry());
+      report.actions.push({ type: "mcp-registry-reset", status: "ok" });
+      ok("MCP registry 손상 → 기본값으로 재생성됨");
     } else {
-      info("MCP registry 없음 — auto sync 건너뜀");
+      saveRegistry(createDefaultRegistry());
+      report.actions.push({ type: "mcp-registry-create", status: "ok" });
+      ok("MCP registry 없음 → 기본값으로 자동 생성됨");
     }
     console.log(`\n  ${LINE}`);
     info("수정 완료 — 아래 진단 결과를 확인하세요");
@@ -2210,28 +2213,27 @@ async function cmdDoctor(options = {}) {
   // ── MCP 중앙 레지스트리 ──
   section("MCP Registry");
   {
-    const registryState = inspectRegistry();
+    let registryState = inspectRegistry();
     if (!registryState.exists) {
+      saveRegistry(createDefaultRegistry());
+      registryState = inspectRegistry();
       addDoctorCheck(report, {
         name: "mcp-registry",
-        status: "missing",
+        status: "fixed",
         path: registryState.path,
-        fix: "config/mcp-registry.json을 복원하거나 `tfx mcp add <name> --url <url>`를 실행하세요.",
+        action: "기본값으로 자동 생성됨",
       });
-      warn("mcp-registry.json 없음");
-      info(`path: ${registryState.path}`);
-      issues++;
+      ok("mcp-registry.json 없음 → 기본값으로 자동 생성됨");
     } else if (!registryState.valid) {
+      saveRegistry(createDefaultRegistry());
+      registryState = inspectRegistry();
       addDoctorCheck(report, {
         name: "mcp-registry",
-        status: "invalid",
+        status: "fixed",
         path: registryState.path,
-        errors: registryState.errors,
-        fix: "config/mcp-registry.json 구조를 수정하세요.",
+        action: "손상 감지 → 기본값으로 재생성됨",
       });
-      fail("mcp-registry.json invalid");
-      for (const entry of registryState.errors) info(entry);
-      issues++;
+      warn("mcp-registry.json 손상 → 기본값으로 재생성됨");
     } else {
       const statusInfo = inspectRegistryStatus(registryState.registry);
       const invalidConfigs = statusInfo.configs.filter((config) => config.parseError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "9.8.7",
+  "version": "10.0.0-alpha.2",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -13,73 +13,24 @@
     "tfx-doctor-tui": "bin/tfx-doctor-tui.mjs",
     "tfx-setup-tui": "bin/tfx-setup-tui.mjs"
   },
+  "engines": { "node": ">=18.0.0" },
+  "dependencies": {
+    "@triflux/core": "^10.0.0-alpha.1",
+    "@triflux/remote": "^10.0.0-alpha.1"
+  },
   "files": [
     "bin",
-    "tui",
-    "hub",
     "skills",
-    "!skills/tfx-workspace",
-    "!**/failure-reports",
-    "scripts",
-    "hooks",
-    "hud",
-    ".claude-plugin",
     "README.md",
-    "README.ko.md",
     "LICENSE"
   ],
-  "workspaces": [
-    "packages/core",
-    "packages/remote",
-    "packages/triflux"
-  ],
-  "scripts": {
-    "pack": "node scripts/pack.mjs all",
-    "pack:core": "node scripts/pack.mjs core",
-    "pack:remote": "node scripts/pack.mjs remote",
-    "setup": "node scripts/setup.mjs",
-    "preinstall": "node scripts/preinstall.mjs",
-    "postinstall": "node scripts/setup.mjs",
-    "lint": "biome check .",
-    "lint:fix": "biome check --fix .",
-    "health": "npm test && npm run lint",
-    "test": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=1 \"tests/**/*.test.mjs\" \"scripts/__tests__/**/*.test.mjs\"",
-    "test:unit": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=1 tests/unit/**/*.test.mjs",
-    "test:integration": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=1 tests/integration/**/*.test.mjs",
-    "test:route-smoke": "node scripts/test-lock.mjs --test scripts/test-tfx-route-no-claude-native.mjs",
-    "test:contract": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=1 tests/contract/**/*.test.mjs",
-    "gen:skill-docs": "node scripts/gen-skill-docs.mjs"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tellang/triflux.git"
-  },
-  "homepage": "https://github.com/tellang/triflux#readme",
+  "keywords": ["claude-code", "plugin", "codex", "gemini", "cli-routing", "orchestration", "multi-model", "triflux", "tfx"],
   "author": "tellang",
   "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "better-sqlite3": "^12.6.2",
-    "pino": "^10.3.1",
-    "pino-pretty": "^13.1.3",
-    "systray2": "^2.1.4",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.0.0"
-  },
-  "keywords": [
-    "claude-code",
-    "plugin",
-    "codex",
-    "gemini",
-    "cli-routing",
-    "orchestration",
-    "multi-model",
-    "triflux",
-    "tfx"
-  ]
+  "homepage": "https://github.com/tellang/triflux#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tellang/triflux.git",
+    "directory": "packages/triflux"
+  }
 }

package/skills/tfx-auto/SKILL.md

@@ -32,6 +32,14 @@ argument-hint: "<command|task> [args...]"
 > **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
 > 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
 
+> **Telemetry**
+>
+> - Skill: `tfx-auto`
+> - Description: `통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반. '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은 구현/수정 요청에 사용. CLI 라우팅이 필요한 모든 작업에 적극 활용.`
+> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
+> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.
+
+
 
 > **MANDATORY RULES**
 >

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

@@ -0,0 +1,286 @@
+---
+name: tfx-auto
+description: >
+  통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반.
+  '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은
+  구현/수정 요청에 사용. CLI 라우팅이 필요한 모든 작업에 적극 활용.
+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...]"
+---
+
+# {{SKILL_NAME}} — 통합 CLI 오케스트레이터
+
+{{> base}}
+
+
+> **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 `exec --full-auto` 분류 + Opus 인라인 분해. Agent 스폰 금지.
+> 5. **thorough**: `-t`/`--thorough` 시 파이프라인 init 필수. 커맨드 숏컷은 항상 quick.
+> 6. **직접 수정 금지**: implement/review/analyze 등 커맨드 숏컷 실행 시 절대로 Edit/Write 도구로 직접 코드를 수정하지 마라. 반드시 Bash(tfx-route.sh)를 통해 Codex/Gemini에 위임하라. 작업이 아무리 사소해도 예외 없음.
+
+## 모드
+
+| 입력 형식 | 모드 | 트리아지 |
+|-----------|------|----------|
+| `/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/` 모듈 참조.

package/skills/tfx-codex/SKILL.md

@@ -13,6 +13,14 @@ argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""
 > **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
 > 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
 
+> **Telemetry**
+>
+> - Skill: `tfx-codex`
+> - Description: `Codex-Only 오케스트레이터. tfx-auto 워크플로우를 Codex 전용으로 고정합니다. '코덱스로 해줘', '코덱스한테 시켜', 'codex로', 'Codex 전용' 같은 요청에 반드시 사용.`
+> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
+> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.
+
+
 
 > **래퍼**: tfx-auto의 Codex 전용 바로가기. TFX_CLI_MODE=codex.
 > **HARD RULE**: Claude는 이 스킬에서 Edit/Write를 사용하면 안 된다. 모든 코드 수정은 Codex CLI를 통해 수행한다.

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

@@ -0,0 +1,72 @@
+---
+name: tfx-codex
+description: >
+  Codex-Only 오케스트레이터. tfx-auto 워크플로우를 Codex 전용으로 고정합니다.
+  '코덱스로 해줘', '코덱스한테 시켜', 'codex로', 'Codex 전용' 같은 요청에 반드시 사용.
+triggers:
+  - tfx-codex
+argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""
+---
+
+# {{SKILL_NAME}} — Codex-Only 오케스트레이터
+
+{{> base}}
+
+
+> **래퍼**: tfx-auto의 Codex 전용 바로가기. TFX_CLI_MODE=codex.
+> **HARD RULE**: Claude는 이 스킬에서 Edit/Write를 사용하면 안 된다. 모든 코드 수정은 Codex CLI를 통해 수행한다.
+> Codex CLI만 사용하여 모든 외부 CLI 작업을 라우팅합니다.
+> Gemini CLI가 없는 환경에서 사용합니다.
+
+## 사용법
+
+```
+/tfx-codex "작업 설명"
+/tfx-codex N:codex "작업 설명"
+```
+
+## 동작 원리
+
+`tfx-auto`와 동일한 워크플로우를 사용하되, `TFX_CLI_MODE=codex` 환경변수를 설정하여
+모든 Gemini 에이전트(designer, writer)를 Codex로 리매핑합니다.
+
+### 에이전트 라우팅
+
+| 에이전트 | 원래 CLI | tfx-codex에서 |
+|----------|---------|-------------|
+| executor, build-fixer, debugger | Codex | Codex (변경 없음) |
+| architect, planner, critic, analyst | Codex | Codex (변경 없음) |
+| code-reviewer, security-reviewer | Codex | Codex (변경 없음) |
+| scientist, document-specialist | Codex | Codex (변경 없음) |
+| **designer** | ~~Gemini~~ | **Codex** (effort: codex53_high) — UI 코드 생성 |
+| **writer** | ~~Gemini~~ | **Codex Spark** (effort: spark53_low) — 경량 문서 |
+| explore | Claude Haiku | Claude Haiku (변경 없음) |
+| verifier, test-engineer | Claude Sonnet | Codex (변경 없음) |
+
+## 실행 규칙
+
+**tfx-auto SKILL.md의 커맨드 숏컷 → 트리아지 → 멀티 태스크 라우팅 → 실행 → 결과 파싱 → 보고 섹션을 그대로 따릅니다.**
+
+유일한 차이점:
+
+1. **실행 섹션(CLI 에이전트) 수행 시** `TFX_CLI_MODE=codex`를 환경변수로 전달:
+   ```bash
+   TFX_CLI_MODE=codex bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile}
+   ```
+
+2. **트리아지 섹션에서** gemini 분류 결과를 codex로 강제 변환:
+   - Codex 분류가 `gemini`를 반환하면 → `codex`로 교체
+   - Opus 분해에서 designer/writer → Codex 에이전트 + implement/analyze MCP 프로필
+
+3. **MCP 프로필 조정**:
+   - designer: `implement` (코드 기반 UI 작업)
+   - writer: `analyze` (문서 기반 리서치+작성)
+
+## 필수 조건
+
+- [Codex CLI](https://github.com/openai/codex): `npm install -g @openai/codex`
+- Gemini CLI 불필요
+
+## Troubleshooting
+
+문제 발생 시 `/tfx-doctor` 실행. (`--fix` 자동 수정, `--reset` 캐시 초기화)

package/skills/tfx-find/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: tfx-find
-description: "코드베이스에서 파일, 함수, 클래스, 문자열을 빠르게 찾을 때 사용한다. '코드 검색', 'find in code', '어디에 있어?', '이 함수 어디서 쓰여?', '파일 찾아줘', '코드베이스 탐색' 같은 요청에 반드시 사용. 파일 위치, 심볼 사용처, 패턴 검색이 필요한 모든 상황에 적극 활용."
+description: >
+  코드베이스에서 파일, 함수, 클래스, 문자열을 빠르게 찾을 때 사용한다.
+  '코드 검색', 'find in code', '어디에 있어?', '이 함수 어디서 쓰여?',
+  '파일 찾아줘', '코드베이스 탐색' 같은 요청에 반드시 사용.
+  파일 위치, 심볼 사용처, 패턴 검색이 필요한 모든 상황에 적극 활용.
 triggers:
   - 코드 검색
   - codebase search
@@ -15,6 +19,13 @@ argument-hint: "<검색 패턴 또는 질문>"
 > **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
 > 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
 
+> **Telemetry**
+>
+> - Skill: `tfx-find`
+> - Description: `코드베이스에서 파일, 함수, 클래스, 문자열을 빠르게 찾을 때 사용한다. '코드 검색', 'find in code', '어디에 있어?', '이 함수 어디서 쓰여?', '파일 찾아줘', '코드베이스 탐색' 같은 요청에 반드시 사용. 파일 위치, 심볼 사용처, 패턴 검색이 필요한 모든 상황에 적극 활용.`
+> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
+> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.
+
 
 > OMC explore agent 오마주. Haiku의 속도 + Glob/Grep/Read의 정밀도.
 > "찾는 건 빠르게, 읽는 건 정확하게."