triflux 9.5.1 → 9.6.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "9.5.1",
+  "version": "9.6.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "author": {
     "name": "tellang"

package/bin/triflux.mjs

@@ -1766,6 +1766,115 @@ async function cmdDoctor(options = {}) {
     ok("잔존 팀 없음");
   }
 
+  // ── Docs 동기화 상태 ──
+  section("Docs Sync");
+  {
+    const docsDirs = ["docs/design", "docs/research"];
+    const missingDocs = [];
+    for (const dir of docsDirs) {
+      const src = join(PKG_ROOT, dir);
+      const dest = join(CLAUDE_DIR, dir);
+      if (existsSync(src)) {
+        const srcFiles = readdirSync(src).filter(f => f.endsWith(".md"));
+        if (!existsSync(dest)) {
+          missingDocs.push({ dir, missing: srcFiles.length, detail: "디렉토리 없음" });
+        } else {
+          const destFiles = readdirSync(dest).filter(f => f.endsWith(".md"));
+          const missing = srcFiles.filter(f => !destFiles.includes(f));
+          if (missing.length > 0) missingDocs.push({ dir, missing: missing.length, detail: missing.join(", ") });
+        }
+      }
+    }
+    if (missingDocs.length === 0) {
+      addDoctorCheck(report, { name: "docs-sync", status: "ok" });
+      ok("레퍼런스 문서 동기화 정상");
+    } else {
+      addDoctorCheck(report, { name: "docs-sync", status: "issues", missingDocs, fix: "tfx setup" });
+      warn(`${missingDocs.reduce((s, d) => s + d.missing, 0)}개 레퍼런스 미동기화`);
+      for (const d of missingDocs) info(`${d.dir}: ${d.detail}`);
+      if (fix) {
+        for (const dir of docsDirs) {
+          const src = join(PKG_ROOT, dir);
+          const dest = join(CLAUDE_DIR, dir);
+          if (existsSync(src)) {
+            mkdirSync(dest, { recursive: true });
+            for (const f of readdirSync(src).filter(f => f.endsWith(".md"))) {
+              copyFileSync(join(src, f), join(dest, f));
+            }
+          }
+        }
+        ok("레퍼런스 동기화 완료");
+      } else {
+        issues += missingDocs.length;
+      }
+    }
+  }
+
+  // ── Gemini MCP 안전성 ──
+  section("Gemini MCP Safety");
+  {
+    const geminiSettings = join(homedir(), ".gemini", "settings.json");
+    if (existsSync(geminiSettings)) {
+      try {
+        const gs = JSON.parse(readFileSync(geminiSettings, "utf8"));
+        const mcpServers = gs.mcpServers || {};
+        const dangerousServers = Object.keys(mcpServers).filter(name => {
+          const s = mcpServers[name];
+          return s.command && !s.url && name !== "tfx-hub";
+        });
+        if (dangerousServers.length === 0) {
+          addDoctorCheck(report, { name: "gemini-mcp-safety", status: "ok" });
+          ok("stdio MCP 없음 (spawn EPERM 안전)");
+        } else {
+          addDoctorCheck(report, { name: "gemini-mcp-safety", status: "warning", servers: dangerousServers, fix: "~/.gemini/settings.json에서 stdio MCP 제거" });
+          warn(`${dangerousServers.length}개 stdio MCP 감지 — Gemini stall 위험`);
+          for (const s of dangerousServers) info(`  ${s}`);
+          issues++;
+        }
+      } catch {
+        addDoctorCheck(report, { name: "gemini-mcp-safety", status: "ok" });
+        ok("설정 파일 파싱 불가 — 건너뜀");
+      }
+    } else {
+      addDoctorCheck(report, { name: "gemini-mcp-safety", status: "ok" });
+      ok("Gemini 설정 없음 (정상)");
+    }
+  }
+
+  // ── Route Script 정합성 ──
+  section("Route Script Sync");
+  {
+    const srcRoute = join(PKG_ROOT, "scripts", "tfx-route.sh");
+    const destRoute = join(CLAUDE_DIR, "scripts", "tfx-route.sh");
+    if (existsSync(srcRoute) && existsSync(destRoute)) {
+      const srcHash = readFileSync(srcRoute, "utf8").length;
+      const destHash = readFileSync(destRoute, "utf8").length;
+      const srcContent = readFileSync(srcRoute, "utf8");
+      const destContent = readFileSync(destRoute, "utf8");
+      if (srcContent === destContent) {
+        addDoctorCheck(report, { name: "route-sync", status: "ok" });
+        ok("프로젝트 소스와 설치본 일치");
+      } else {
+        addDoctorCheck(report, { name: "route-sync", status: "issues", fix: "tfx setup" });
+        warn("tfx-route.sh 프로젝트 소스와 설치본 불일치");
+        info(`소스: ${srcRoute} (${srcHash}B) / 설치: ${destRoute} (${destHash}B)`);
+        if (fix) {
+          copyFileSync(srcRoute, destRoute);
+          ok("tfx-route.sh 동기화 완료");
+        } else {
+          issues++;
+        }
+      }
+    } else if (existsSync(srcRoute) && !existsSync(destRoute)) {
+      addDoctorCheck(report, { name: "route-sync", status: "missing", fix: "tfx setup" });
+      fail("설치본 없음");
+      issues++;
+    } else {
+      addDoctorCheck(report, { name: "route-sync", status: "ok" });
+      ok("소스 없음 (npm 패키지 모드)");
+    }
+  }
+
   // 결과
   console.log(`\n  ${LINE}`);
   if (issues === 0) {

package/hub/team/headless.mjs

@@ -243,10 +243,12 @@ function dispatchBatch(sessionName, assignments, opts = {}) {
  * @returns {Promise<Array<{d, completion, output}>>}
  */
 async function awaitAll(sessionName, dispatches, timeoutSec, safeProgress, progressIntervalSec) {
+  const ac = new AbortController();
+
   // 병렬 대기 (Promise.all — 모든 pane 동시 폴링, 총 시간 = max(개별 시간))
   return Promise.all(dispatches.map(async (d) => {
     // onPoll → onProgress 변환 (throttle by progressIntervalSec)
-    const pollOpts = {};
+    const pollOpts = { signal: ac.signal };
     if (safeProgress && progressIntervalSec > 0) {
       let lastProgressAt = 0;
       const intervalMs = progressIntervalSec * 1000;
@@ -268,6 +270,11 @@ async function awaitAll(sessionName, dispatches, timeoutSec, safeProgress, progr
     if (d.logPath) pollOpts.logPath = d.logPath;
     const completion = await waitForCompletion(sessionName, d.paneId || d.paneName, d.token, timeoutSec, pollOpts);
 
+    // 세션 사망 감지 시 나머지 워커 폴링 즉시 중단
+    if (completion.sessionDead && !ac.signal.aborted) {
+      ac.abort();
+    }
+
     const output = completion.matched
       ? readResult(d.resultFile, d.paneId)
       : "";

package/hub/team/psmux.mjs

@@ -570,7 +570,7 @@ function killOrphanPipeHelpers(sessionName) {
   const safeSession = sanitizePathPart(sessionName);
   try {
     const output = childProcess.execSync(
-      `powershell -NoProfile -WindowStyle Hidden -Command "$ErrorActionPreference='SilentlyContinue'; Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'pipe-pane-capture' -and $_.CommandLine -match '${safeSession}' } | Select-Object -ExpandProperty ProcessId"`,
+      `powershell -NoProfile -WindowStyle Hidden -Command "$ErrorActionPreference='SilentlyContinue'; Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'pipe-pane-capture' -and $_.CommandLine -match 'tfx-headless[/\\\\]${safeSession}' } | Select-Object -ExpandProperty ProcessId"`,
       { encoding: "utf8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
     );
     const pids = output.split(/\r?\n/).map((l) => Number.parseInt(l.trim(), 10)).filter((p) => Number.isFinite(p) && p > 0);
@@ -605,7 +605,7 @@ function killOrphanMcpProcesses(sessionName) {
   try {
     // 세션 결과 디렉토리 패턴으로 MCP 서버 프로세스 식별
     const output = childProcess.execSync(
-      `powershell -NoProfile -WindowStyle Hidden -Command "$ErrorActionPreference='SilentlyContinue'; Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'node.exe' -and $_.CommandLine -match '${safeSession}' } | Select-Object -ExpandProperty ProcessId"`,
+      `powershell -NoProfile -WindowStyle Hidden -Command "$ErrorActionPreference='SilentlyContinue'; Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'node.exe' -and $_.CommandLine -match 'tfx-headless[/\\\\]${safeSession}' } | Select-Object -ExpandProperty ProcessId"`,
       { encoding: "utf8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
     );
     const pids = output.split(/\r?\n/).map((l) => Number.parseInt(l.trim(), 10)).filter((p) => Number.isFinite(p) && p > 0 && p !== hubPid);
@@ -632,6 +632,9 @@ export function killPsmuxSession(sessionName) {
   }
   disableAllPipeCaptures(sessionName, paneIds);
 
+  // pipe-pane reader가 EOF를 처리하고 정상 종료할 시간 확보
+  sleepMs(500);
+
   // 2. pane 프로세스 트리 강제 종료 (MCP 서버 포함)
   const pids = collectPanePids(sessionName);
   for (const pid of pids) {
@@ -856,7 +859,8 @@ export function dispatchCommand(sessionName, paneNameOrTarget, commandText) {
  * @param {number} timeoutSec
  * @param {object} [opts]
  * @param {(snapshot: {content: string, paneId: string, paneName: string, elapsed: number}) => void} [opts.onPoll] — 각 폴링 주기마다 호출
- * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null }}
+ * @param {AbortSignal} [opts.signal] — 외부에서 폴링 중단 요청 시 사용
+ * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null, aborted?: boolean }}
  */
 export async function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSec = 300, opts = {}) {
   ensurePsmuxInstalled();
@@ -892,7 +896,14 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
   const deadline = startTime + Math.max(0, Math.trunc(timeoutSec * 1000));
   const regex = toPatternRegExp(pattern);
 
+  if (opts?.signal?.aborted) {
+    return { matched: false, paneId: pane.paneId, paneName, logPath, match: null, aborted: true };
+  }
+
   while (Date.now() <= deadline) {
+    if (opts?.signal?.aborted) {
+      return { matched: false, paneId: pane.paneId, paneName, logPath, match: null, aborted: true };
+    }
     // E4 크래시 복구: capture 실패 시 세션 생존 체크
     try {
       if (opts.logPath) {
@@ -940,6 +951,9 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
       break;
     }
     await sleepMsAsync(POLL_INTERVAL_MS);
+    if (opts?.signal?.aborted) {
+      return { matched: false, paneId: pane.paneId, paneName, logPath, match: null, aborted: true };
+    }
   }
 
   return {
@@ -1112,7 +1126,13 @@ export function killWorker(sessionName, workerName) {
       // send-keys 실패 무시
     }
 
-    sleepMs(1000);
+    try {
+      psmuxExec(["send-keys", "-t", paneId, "exit", "Enter"]);
+    } catch {
+      // send-keys 실패 무시
+    }
+
+    sleepMs(2000);
 
     try {
       psmuxExec(["kill-pane", "-t", paneId]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "9.5.1",
+  "version": "9.6.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/headless-guard.mjs

@@ -193,7 +193,7 @@ async function main() {
     }
 
     // codex/gemini 직접 CLI 호출 → deny
-    if (/\bcodex\s+exec\b/.test(cmd) || /\bgemini\s+(-p|--prompt)\b/.test(cmd)) {
+    if (/\bcodex\b.*\bexec\b/.test(cmd) || /\bgemini\s+(-p|--prompt)\b/.test(cmd)) {
       deny(
         "[headless-guard] codex/gemini 직접 호출은 spawn-session에서 차단됩니다. " +
         `승인된 경로: ${HEADLESS_FALLBACK_COMMAND}. ` +

package/scripts/setup.mjs

@@ -569,6 +569,19 @@ if (existsSync(skillsSrc)) {
   }
 }
 
+// ── docs 동기화 ──
+const docsDirs = ['docs/design', 'docs/research'];
+for (const dir of docsDirs) {
+  const src = join(PLUGIN_ROOT, dir);
+  const dest = join(CLAUDE_DIR, dir);
+  if (existsSync(src)) {
+    mkdirSync(dest, { recursive: true });
+    for (const f of readdirSync(src).filter(f => f.endsWith('.md'))) {
+      copyFileSync(join(src, f), join(dest, f));
+    }
+  }
+}
+
 // ── settings.json 통합 R/W ──
 // 3개 섹션(statusLine, agentTeams, hooks)을 1회 read → 일괄 수정 → 1회 write
 

package/scripts/tfx-route.sh

@@ -76,9 +76,13 @@ if [[ "${1:-}" == "--job-status" ]]; then
     fi
   elif [[ -f "$job_dir/pid" ]]; then
     pid=$(cat "$job_dir/pid")
+    if [[ "$pid" == "starting" ]]; then
+      echo "starting"
+      exit 0
+    fi
     if kill -0 "$pid" 2>/dev/null; then
       # 진행 상황 힌트
-      local_bytes=$(wc -c < "$job_dir/stdout.log" 2>/dev/null || echo 0)
+      local_bytes=$(wc -c < "$job_dir/result.log" 2>/dev/null | tr -d ' ' || echo 0)
       elapsed=$(( $(date +%s) - $(cat "$job_dir/start_time" 2>/dev/null || date +%s) ))
       echo "running elapsed=${elapsed}s output=${local_bytes}B"
     else
@@ -98,7 +102,12 @@ if [[ "${1:-}" == "--job-result" ]]; then
   [[ -d "$job_dir" ]] || { echo "error: job not found"; exit 1; }
   [[ -f "$job_dir/done" ]] || { echo "error: job still running"; exit 1; }
 
-  cat "$job_dir/result.log" 2>/dev/null
+  result_bytes=$(wc -c < "$job_dir/result.log" 2>/dev/null | tr -d ' ' || echo 0)
+  if [[ "$result_bytes" -eq 0 ]] && [[ -s "$job_dir/stderr.log" ]]; then
+    cat "$job_dir/stderr.log" 2>/dev/null
+  else
+    cat "$job_dir/result.log" 2>/dev/null
+  fi
   exit_code=$(cat "$job_dir/exit_code" 2>/dev/null || echo 1)
   exit "$exit_code"
 fi
@@ -1362,6 +1371,8 @@ gemini_with_retry() {
       attempt=$(( attempt + 1 ))
       if (( attempt < max_retries )); then
         echo "[tfx-route] Gemini 429 감지. ${delay}초 후 재시도 ($attempt/$max_retries)..." >&2
+        kill "$pid" 2>/dev/null
+        wait "$pid" 2>/dev/null
         sleep "$delay"
         delay=$(( delay * 2 ))
         : > "$STDOUT_LOG"
@@ -1476,7 +1487,7 @@ run_codex_exec() {
     fi
 
     if [[ -s "$STDOUT_LOG" ]]; then
-      echo "[tfx-route] 경고: codex stdout 비어있음, stderr에서 응답 복구 ($(wc -c < "$STDOUT_LOG") bytes)" >&2
+      echo "[tfx-route] 경고: codex stdout 비어있음, stderr에서 응답 복구 ($(wc -c < "$STDOUT_LOG" | tr -d ' ') bytes)" >&2
     else
       echo "[tfx-route] 경고: codex stdout 비어있음, stderr 복구도 실패" >&2
     fi
@@ -1875,11 +1886,12 @@ if [[ "$TFX_ASYNC_MODE" -eq 1 ]]; then
   date +%s > "$JOB_DIR/start_time"
 
   # 백그라운드 서브쉘: main 실행 → 결과 저장
+  echo "starting" > "$JOB_DIR/pid"
   (
     set +e  # main 내부 에러가 exit_code 기록 전에 서브쉘을 죽이는 것 방지
     exec > "$JOB_DIR/result.log" 2>"$JOB_DIR/stderr.log"
-    main
-    echo $? > "$JOB_DIR/exit_code"
+    main; _ec=$?
+    echo "$_ec" > "$JOB_DIR/exit_code"
     touch "$JOB_DIR/done"
   ) &
   bg_pid=$!

package/skills/tfx-analysis/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: "<분석 대상 — 파일, 디렉토리, 또는 주제>"
 
 # tfx-analysis — Light Code Analysis
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Deep 버전**: tfx-deep-analysis. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
 > Codex 단일 분석으로 빠른 인사이트. SuperClaude sc:analyze 영감.
 

package/skills/tfx-auto/SKILL.md

@@ -29,6 +29,10 @@ argument-hint: "<command|task> [args...]"
 
 # tfx-auto — 통합 CLI 오케스트레이터
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **MANDATORY RULES**
 >
 > 1. **실행**: CLI 에이전트는 반드시 `Bash("bash ~/.claude/scripts/tfx-route.sh ...")`. Claude 네이티브(explore/verifier/test-engineer/qa-tester)만 `Agent()`.

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

@@ -10,6 +10,10 @@ argument-hint: "\"작업 설명\" | N:agent_type \"작업 설명\""
 
 # tfx-auto-codex — Codex 리드형 tfx-auto
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **래퍼**: tfx-auto의 Codex 전용 바로가기. TFX_NO_CLAUDE_NATIVE=1.
 > 목적: 기존 `tfx-auto`의 오케스트레이션 패턴을 유지하면서
 > Claude 네이티브 역할(`explore`, `verifier`, `test-engineer`, `qa-tester`)을

package/skills/tfx-autopilot/SKILL.md

@@ -10,6 +10,10 @@ argument-hint: "<구현할 작업 설명>"
 
 # tfx-autopilot — Light Autonomous Execution
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > Codex 직접 구현 → Claude 검증. 최소 토큰으로 빠른 자율 실행.
 
 ## 용도

package/skills/tfx-autoresearch/SKILL.md

@@ -19,6 +19,10 @@ source: GAP 분석 P2 #8
 
 # tfx-autoresearch — 자율 웹 리서치
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > 주제를 받아 자동으로 웹을 검색하고, 결과를 분석하여 구조화된 리서치 보고서를 생성합니다.
 > "조사는 AI가, 판단은 사람이."
 

package/skills/tfx-autoroute/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "<작업 설명>"
 
 # tfx-autoroute — Auto-Routing Autonomous Executor
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > oh-my-openagent Sisyphus agent 오마주. 바위는 멈추지 않는다 — 그리고 올바른 산을 고른다.
 > "실패하면 더 강한 모델로. 성공할 때까지."
 

package/skills/tfx-codex/SKILL.md

@@ -10,6 +10,10 @@ argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""
 
 # tfx-codex — Codex-Only 오케스트레이터
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **래퍼**: tfx-auto의 Codex 전용 바로가기. TFX_CLI_MODE=codex.
 > **HARD RULE**: Claude는 이 스킬에서 Edit/Write를 사용하면 안 된다. 모든 코드 수정은 Codex CLI를 통해 수행한다.
 > Codex CLI만 사용하여 모든 외부 CLI 작업을 라우팅합니다.

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

@@ -5,6 +5,10 @@ description: OMX 스킬을 활용하는 Codex 다중 세션 스폰 오케스트
 
 # tfx-codex-swarm — Codex 다중 세션 스폰 오케스트레이터
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > PRD/태스크 파일 N개를 각각 독립 worktree + psmux 세션으로 Codex full-auto 실행.
 > AskUserQuestion 기반 인터랙티브 설정. 미지정 시 하네스가 자동 판단.
 
@@ -300,9 +304,9 @@ cp {PRD_PATH} .codex-swarm/wt-issue-{N}/{PRD_PATH}
 > bash 문법을 `send-keys`로 직접 전달하면 경로 오류 + 인자 파싱 실패가 발생한다.
 > **반드시 `.sh` 런처 파일을 생성하고, PowerShell 구문으로 bash.exe 전체 경로를 호출해야 한다.**
 
-**실행 방식 2가지 (택 1):**
+**실행 방식 3가지 (택 1):**
 
-**A) .sh 런처 + send-keys (권장)**
+**A) .sh 런처 + send-keys**
 ```bash
 psmux new-session -s "codex-swarm-{id}" -d
 
@@ -339,6 +343,33 @@ Get-Content 'C:\path\.codex-swarm\prompts\prompt-{id}.md' -Raw | codex
 # Get-Content 'prompt.md' -Raw | codex -c 'model="gpt-5.3-codex"' -c 'model_reasoning_effort="high"'
 ```
 
+**C) tfx-route.sh 경유 (권장)**
+```bash
+psmux new-session -s "codex-swarm-{id}" -d
+
+BASH_WIN='C:\\Program Files\\Git\\bin\\bash.exe'
+LAUNCH_DIR='C:\\path\\to\\.codex-swarm'
+psmux send-keys -t "codex-swarm-{id}" \
+  "& '$BASH_WIN' '$LAUNCH_DIR\\launch-{id}.sh'" Enter
+```
+
+launch-{id}.sh:
+```bash
+#!/bin/bash
+cd /c/path/.codex-swarm/wt-issue-{N} || exit 1
+
+# tfx-route.sh가 MCP 프로필, 타임아웃, 에이전트 역할을 자동 관리
+# 프롬프트는 인자로 전달 (stdin 불필요 → TTY 문제 없음)
+~/.claude/scripts/tfx-route.sh executor \
+  "$(cat /c/path/.codex-swarm/prompts/prompt-{id}.md)" \
+  "{profile}" 900
+```
+
+장점:
+- TTY 문제 없음 — stdin 파이프 미사용
+- MCP 프로필 자동 관리 (tfx-route.sh가 처리)
+- 타임아웃 통합 (마지막 인자 = 초 단위)
+
 > **금지 패턴** (절대 사용하지 말 것):
 > ```bash
 > # WRONG — bash 문법을 PowerShell 세션에 직접 전달

package/skills/tfx-consensus/SKILL.md

@@ -9,6 +9,10 @@ argument-hint: "<분석 주제 또는 컨텍스트> (Deep 스킬 내부 자동
 
 # tfx-consensus — Tri-CLI Consensus Engine
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **인프라**: 다른 스킬이 내부적으로 사용. 직접 호출할 필요 없음.
 > 모든 Deep 스킬의 공통 기반. 3개 CLI의 독립 결과를 교차검증하여 합의 도출.
 

package/skills/tfx-debate/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "<토론 주제 또는 질문>"
 
 # tfx-debate — Tri-CLI Structured Debate
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > 3개 CLI가 독립 분석 → 교차검증 → 합의 도출. Anti-herding으로 편향 없는 결론.
 
 ## 용도

package/skills/tfx-deep-analysis/SKILL.md

@@ -10,6 +10,10 @@ argument-hint: "<분석 대상 — 파일, 디렉토리, 또는 주제>"
 
 # tfx-deep-analysis — Tri-CLI Deep Analysis
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Light 버전**: tfx-analysis. 기본값. 깊이 수정자 없으면 Light 선택.
 > Claude(아키텍처) + Codex(구현/보안) + Gemini(UX/문서화) → Tri-Debate → 합의.
 > 3자 전문 관점의 편향 없는 분석.

package/skills/tfx-deep-interview/SKILL.md

@@ -14,6 +14,10 @@ argument-hint: "<topic>"
 
 # tfx-deep-interview — 소크라테스식 깊이 탐색
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > 구현 전에 질문을 통해 요구사항의 깊이를 탐색합니다.
 > "좋은 답은 좋은 질문에서 나온다."
 

package/skills/tfx-deep-plan/SKILL.md

@@ -13,6 +13,10 @@ argument-hint: "<구현할 기능 설명>"
 
 # tfx-deep-plan — Tri-Model Consensus Planning
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Light 버전**: tfx-plan. 기본값. 깊이 수정자 없으면 Light 선택.
 3개 모델(Opus 4.6 · GPT 5.4 · Gemini)이 독립 설계 후 교차검증하여 합의된 계획을 도출한다.
 

package/skills/tfx-deep-qa/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: "[테스트 대상 경로 또는 기능 설명]"
 
 # tfx-deep-qa — Tri-CLI Deep Verification
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Light 버전**: tfx-qa. 기본값. 깊이 수정자 없으면 Light 선택.
 > 3-CLI 독립 검증 → 교차검증 → 2+ 합의 항목만 보고. false-positive 87% 감소.
 

package/skills/tfx-deep-research/SKILL.md

@@ -14,6 +14,10 @@ argument-hint: "[--depth quick|standard|deep] <리서치 주제>"
 
 # tfx-deep-research — Multi-Source Deep Research with Tri-CLI Consensus
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Light 버전**: tfx-research. 기본값. 깊이 수정자 없으면 Light 선택.
 > 쿼리 분해 → 3-CLI 독립 병렬 검색 → 교차검증 → 합의 기반 종합 보고서.
 > STORM(Stanford) perspective-guided + GPT-Researcher recursive tree + Tavily deep research pipeline 영감.

package/skills/tfx-deep-review/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "[파일 경로 또는 변경 설명]"
 
 # tfx-deep-review — Tri-CLI Deep Code Review
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Light 버전**: tfx-review. 기본값. 깊이 수정자 없으면 Light 선택.
 > 3-CLI 독립 리뷰 → 교차검증 → 2+ 합의 항목만 보고. Diffray + Calimero 영감.
 

package/skills/tfx-doctor/SKILL.md

@@ -152,6 +152,9 @@ options:
 - MCP 인벤토리 캐시
 - Phase 1 웜업 캐시 무결성 (`node scripts/cache-doctor.mjs`)
 - 잔존 팀(orphan teams) 감지
+- **Docs 동기화** — `docs/design/`, `docs/research/` → `~/.claude/docs/` 레퍼런스 문서 동기화 상태
+- **Gemini MCP 안전성** — `~/.gemini/settings.json`의 stdio MCP 감지 (spawn EPERM 방지)
+- **Route Script 정합성** — 프로젝트 소스 `scripts/tfx-route.sh`와 `~/.claude/scripts/tfx-route.sh` 일치 여부
 
 ## 에러 처리
 

package/skills/tfx-find/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "<검색 패턴 또는 질문>"
 
 # tfx-find — Fast Codebase Explorer
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > OMC explore agent 오마주. Haiku의 속도 + Glob/Grep/Read의 정밀도.
 > "찾는 건 빠르게, 읽는 건 정확하게."
 

package/skills/tfx-forge/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "[스킬 이름 또는 설명]"
 
 # tfx-forge — Skill Authoring Meta-Skill
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > Superpowers skill authoring 오마주. 스킬을 만드는 스킬.
 > "메타 레벨에서 자동화하라."
 

package/skills/tfx-fullcycle/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: "<구현할 기능 전체 설명>"
 
 # tfx-fullcycle — Full Development Pipeline with Tri-CLI Consensus
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > 5-Phase 파이프라인: Expansion → Planning → Execution → QA → Validation.
 > OMC autopilot + Superpowers TDD + MetaGPT SOP 영감. 처음부터 끝까지 자율 실행.
 

package/skills/tfx-gemini/SKILL.md

@@ -10,6 +10,10 @@ argument-hint: "\"작업 설명\" | N:gemini \"작업 설명\""
 
 # tfx-gemini — Gemini-Only 오케스트레이터
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **래퍼**: tfx-auto의 Gemini 전용 바로가기. TFX_CLI_MODE=gemini.
 > Gemini CLI만 사용하여 모든 외부 CLI 작업을 라우팅합니다.
 > Codex CLI가 없는 환경에서 사용합니다.

package/skills/tfx-hub/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: "<start|stop|status|자유형 작업 설명>"
 
 # tfx-hub — MCP 메시지 버스 관리 + 개방형 작업
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **인프라**: 다른 스킬이 내부적으로 사용. 직접 호출할 필요 없음.
 > CLI 에이전트(Codex/Gemini/Claude) 간 실시간 메시지 허브를 관리합니다.
 > **커맨드 매칭 + fallthrough**: start/stop/status에 매칭되면 즉시 실행,

package/skills/tfx-index/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: "[--update] [경로]"
 
 # tfx-index — Project Indexing (94% Token Reduction)
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > SuperClaude index-repo 오마주. 1회 2K 토큰으로 인덱스 생성, 이후 세션마다 55K 토큰 절감.
 
 > **Gemini 위임**: 스캔 + 인덱스 생성 작업은 Gemini CLI에 위임한다. Claude는 모드 선택(Step 0)과 파일 쓰기만 담당. Claude 토큰 소비 ~500 tokens으로 줄어든다.

package/skills/tfx-interview/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "<구현할 주제 또는 요구사항>"
 
 # tfx-interview — Quantified Socratic Requirements Exploration
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > OMC deep-interview + ouroboros 오마주. 모호성을 숫자로 측정하고 20% 미만까지 질문한다.
 > "측정할 수 없으면 개선할 수 없다."
 >

package/skills/tfx-multi/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
 
 # tfx-multi v3 — 파이프라인 기반 멀티-CLI 팀 오케스트레이터
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **인프라**: 다른 스킬이 내부적으로 사용. 직접 호출할 필요 없음.
 > Claude Code Native Teams의 Shift+Down 네비게이션을 복원한다.
 > Codex/Gemini 워커마다 최소 프롬프트(~100 토큰)의 슬림 Agent 래퍼를 spawn하여 네비게이션에 등록하고,

package/skills/tfx-panel/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "<토론 주제>"
 
 # tfx-panel — Virtual Expert Panel Simulation
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > SuperClaude spec-panel + business-panel 오마주. 실제 전문가 5-10명의 관점을 시뮬레이션하여 다각적 분석.
 > "한 사람의 시야는 좁다. 패널의 시야는 넓다."
 

package/skills/tfx-persist/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "<완료할 작업 설명>"
 
 # tfx-persist — Tri-Verified Persistence Loop
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > OMC ralph 오마주. 핵심 차별점: 검증자가 단일 agent가 아니라 **3-CLI consensus**.
 > The boulder never stops — but it stops being wrong.
 

package/skills/tfx-plan/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: "<구현할 기능 설명>"
 
 # tfx-plan — Light Implementation Plan
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Deep 버전**: tfx-deep-plan. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
 > Gemini 위임 빠른 계획 — Claude는 컨텍스트 수집·출력 포맷만, 핵심 계획 수립은 Gemini에 위임.
 

package/skills/tfx-prune/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "[파일 경로 또는 git diff 범위]"
 
 # tfx-prune — Tri-Verified AI Slop Remover
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > OMC ai-slop-cleaner 오마주. 핵심 차별점: 단일 판단이 아닌 **3자 독립 감지 + 합의** 기반 제거.
 > "AI가 만든 슬롭은 AI 3명이 합의해야 슬롭이다."
 

package/skills/tfx-qa/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: "[테스트 명령 또는 파일 경로]"
 
 # tfx-qa — Light Test-Fix Cycle
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Deep 버전**: tfx-deep-qa. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
 > 테스트 실행 → 실패 분석 → 자동 수정 → 재실행. 최대 3회. OMC ultraqa 영감.
 

package/skills/tfx-ralph/SKILL.md

@@ -11,6 +11,10 @@ triggers:
 
 # tfx-ralph — tfx-persist 별칭
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 이 스킬은 `tfx-persist`와 동일합니다. `/tfx-persist` 스킬을 호출하세요.
 
 ## 동작

package/skills/tfx-remote-setup/SKILL.md

@@ -12,6 +12,10 @@ argument-hint: "[--add|--edit|--probe-all|--diagnose]"
 
 # tfx-remote-setup — 원격 호스트 설정 위저드
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > 원격 세션(tfx-remote-spawn)을 쓰기 전에 호스트를 설정합니다.
 > Tailscale 네트워크 자동 감지 → SSH 연결 → Claude 프로브 → hosts.json 등록을 한번에.
 

package/skills/tfx-remote-spawn/SKILL.md

@@ -15,6 +15,10 @@ argument-hint: "[호스트] [프롬프트] 또는 자연어"
 
 # tfx-remote-spawn — 원격/로컬 Claude 세션 관리
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > psmux 세션 기반으로 Claude를 원격/로컬에서 실행하고 관리합니다.
 > AskUserQuestion 기반 인터랙티브 메뉴로 다중 호출 없이 한번에 처리.
 

package/skills/tfx-research/SKILL.md

@@ -13,6 +13,10 @@ argument-hint: "<검색 주제>"
 
 # tfx-research — Light Web Research
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Deep 버전**: tfx-deep-research. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
 > 빠른 단일 소스 검색 + 요약. **검색 자체를 Gemini에 위임**해 Claude 토큰 최소화. Gemini CLI의 네이티브 Google Search로 검색+요약을 한 번에 처리.
 

package/skills/tfx-review/SKILL.md

@@ -11,6 +11,10 @@ argument-hint: "[파일 경로 또는 변경 설명]"
 
 # tfx-review — Light Code Review
 
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
 > **Deep 버전**: tfx-deep-review. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
 > **HARD RULE**: 리뷰 결과를 생성할 때 Claude가 직접 git log/diff를 실행하지 마라. Codex code-reviewer에게 위임하라.
 > Codex 단일 리뷰로 빠른 피드백. 토큰 최소화.