triflux 8.7.0 → 8.9.1

package/README.ko.md

@@ -17,16 +17,11 @@
   <a href="https://www.npmjs.com/package/triflux"><img src="https://img.shields.io/npm/v/triflux?style=flat-square&color=FFAF00&label=npm" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/triflux"><img src="https://img.shields.io/npm/dm/triflux?style=flat-square&color=F5C242" alt="npm downloads"></a>
   <a href="https://github.com/tellang/triflux/stargazers"><img src="https://img.shields.io/github/stars/tellang/triflux?style=flat-square&color=FFAF00" alt="GitHub stars"></a>
-  <a href="https://github.com/tellang/triflux/actions"><img src="https://img.shields.io/github/actions/workflow/status/tellang/triflux/ci.yml?style=flat-square&label=CI" alt="CI"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-374151?style=flat-square" alt="License: MIT"></a>
 </p>
 
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/demo-dark.gif">
-    <source media="(prefers-color-scheme: light)" srcset="docs/assets/demo-light.gif">
-    <img alt="triflux 데모" src="docs/assets/demo-dark.gif" width="680">
-  </picture>
+  <img alt="triflux 데모" src="docs/assets/demo-multi.gif" width="680">
 </p>
 
 <p align="center">
@@ -40,6 +35,49 @@
 
 ---
 
+## 빠른 시작
+
+### 1. 설치
+
+```bash
+npm install -g triflux
+```
+
+### 2. 설정
+
+```bash
+tfx setup
+```
+
+### 3. 사용법
+
+```bash
+# Light — 단일 모델로 빠르게 실행
+/tfx-research "React 19 Server Actions best practices"
+/tfx-review
+/tfx-plan "add JWT auth middleware"
+
+# Deep — 중요한 작업에 3자 합의 적용
+/tfx-deep-research "microservice architecture comparison 2026"
+/tfx-deep-review
+/tfx-deep-plan "migrate REST to GraphQL"
+
+# Debate — 3개의 독립적인 의견을 확보
+/tfx-debate "Redis vs PostgreSQL LISTEN/NOTIFY for real-time events"
+
+# Persistence — 완료될 때까지 멈추지 않음
+/tfx-ralph "implement full auth flow with tests"
+
+# Team — Multi-CLI 병렬 오케스트레이션
+/tfx-multi "refactor auth + update UI + add tests"
+
+# Remote — 원격 머신에 Claude 세션 생성
+/tfx-remote-setup                              # 인터랙티브 호스트 설정 위저드 (Tailscale + SSH)
+/tfx-remote-spawn "울트라에서 보안 리뷰 해"      # 원격 호스트에서 세션 실행
+```
+
+---
+
 ## v8의 새로운 기능
 
 **triflux v8**은 **Tri-CLI Consensus Intelligence**를 도입합니다. Claude, Codex, Gemini가 각각 독립적으로 분석한 뒤, 구조화된 토론을 거쳐 교차 검증하는 근본적으로 새로운 접근 방식입니다. 모든 Deep 스킬은 Anti-Herding(편향 오염 방지)과 Consensus Gate를 통한 출력 보장을 제공합니다.
@@ -171,7 +209,8 @@ Phase 3: Resolution (합의율 < 70%일 경우)
 | `tfx-codex` | Codex 전용 오케스트레이터 |
 | `tfx-gemini` | Gemini 전용 오케스트레이터 |
 | `tfx-auto-codex` | Codex 주도 오케스트레이터 |
-| `remote-spawn` | psmux를 통한 원격 세션 관리 |
+| `tfx-remote-spawn` | psmux를 통한 원격 세션 관리 |
+| `tfx-remote-setup` | 원격 호스트 설정 위저드 (Tailscale + SSH) |
 
 ---
 

package/README.md

@@ -17,16 +17,11 @@
   <a href="https://www.npmjs.com/package/triflux"><img src="https://img.shields.io/npm/v/triflux?style=flat-square&color=FFAF00&label=npm" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/triflux"><img src="https://img.shields.io/npm/dm/triflux?style=flat-square&color=F5C242" alt="npm downloads"></a>
   <a href="https://github.com/tellang/triflux/stargazers"><img src="https://img.shields.io/github/stars/tellang/triflux?style=flat-square&color=FFAF00" alt="GitHub stars"></a>
-  <a href="https://github.com/tellang/triflux/actions"><img src="https://img.shields.io/github/actions/workflow/status/tellang/triflux/ci.yml?style=flat-square&label=CI" alt="CI"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-374151?style=flat-square" alt="License: MIT"></a>
 </p>
 
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/demo-dark.gif">
-    <source media="(prefers-color-scheme: light)" srcset="docs/assets/demo-light.gif">
-    <img alt="triflux demo" src="docs/assets/demo-dark.gif" width="680">
-  </picture>
+  <img alt="triflux demo" src="docs/assets/demo-multi.gif" width="680">
 </p>
 
 <p align="center">
@@ -40,6 +35,49 @@
 
 ---
 
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g triflux
+```
+
+### 2. Setup
+
+```bash
+tfx setup
+```
+
+### 3. Use
+
+```bash
+# Light — single model, fast execution
+/tfx-research "React 19 Server Actions best practices"
+/tfx-review
+/tfx-plan "add JWT auth middleware"
+
+# Deep — 3-party consensus for critical work
+/tfx-deep-research "microservice architecture comparison 2026"
+/tfx-deep-review
+/tfx-deep-plan "migrate REST to GraphQL"
+
+# Debate — get 3 independent opinions
+/tfx-debate "Redis vs PostgreSQL LISTEN/NOTIFY for real-time events"
+
+# Persistence — don't stop until done
+/tfx-ralph "implement full auth flow with tests"
+
+# Team — Multi-CLI parallel orchestration
+/tfx-multi "refactor auth + update UI + add tests"
+
+# Remote — spawn Claude sessions on other machines
+/tfx-remote-setup                                # interactive host wizard (Tailscale + SSH)
+/tfx-remote-spawn "run security review on ultra4" # spawn on remote host
+```
+
+---
+
 ## What's New in v8
 
 **triflux v8** introduces **Tri-CLI Consensus Intelligence** — a fundamentally new approach where Claude, Codex, and Gemini independently analyze, then cross-validate through structured debate. Every Deep skill guarantees anti-herding (no bias contamination) and consensus-gated output.
@@ -171,7 +209,8 @@ Phase 3: Resolution (if consensus < 70%)
 | `tfx-codex` | Codex-only orchestrator |
 | `tfx-gemini` | Gemini-only orchestrator |
 | `tfx-auto-codex` | Codex-lead orchestrator |
-| `remote-spawn` | Remote session management via psmux |
+| `tfx-remote-spawn` | Remote session management via psmux |
+| `tfx-remote-setup` | Remote host setup wizard (Tailscale + SSH) |
 
 ---
 

package/package.json

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

package/scripts/hub-ensure.mjs

@@ -66,13 +66,25 @@ function startHubDetached(port) {
   if (!existsSync(serverPath)) return false;
 
   try {
-    const child = spawn(process.execPath, [serverPath], {
-      env: { ...process.env, TFX_HUB_PORT: String(port) },
-      detached: true,
-      stdio: "ignore",
-      windowsHide: true,
-    });
-    child.unref();
+    const env = { ...process.env, TFX_HUB_PORT: String(port) };
+    if (process.platform === "win32") {
+      // Windows: cmd.exe /c start /b → 완전 독립 프로세스 트리 생성
+      // hook timeout 시 프로세스 트리 킬에서 살아남음
+      const child = spawn("cmd.exe", ["/c", "start", "/b", "", process.execPath, serverPath], {
+        env,
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      child.unref();
+    } else {
+      const child = spawn(process.execPath, [serverPath], {
+        env,
+        detached: true,
+        stdio: "ignore",
+      });
+      child.unref();
+    }
     return true;
   } catch {
     return false;
@@ -94,9 +106,16 @@ const { host, port } = resolveHubTarget();
 if (!(await isHubHealthy(host, port))) {
   const started = startHubDetached(port);
   if (started) {
-    const ready = await waitForHubReady(host, port);
-    if (!ready) {
-      console.error("[tfx-hub-ensure] Hub 시작했으나 ready 대기 초과 — MCP 연결 실패 가능");
+    const ready = await waitForHubReady(host, port, 3000);
+    if (ready) {
+      process.stdout.write("hub: ok");
+    } else {
+      // fire-and-forget: hub이 아직 기동 중일 수 있음 — 에러가 아닌 경고
+      process.stdout.write("hub: starting");
     }
+  } else {
+    process.stderr.write("[hub-ensure] hub 시작 실패");
   }
+} else {
+  process.stdout.write("hub: ok");
 }

package/skills/tfx-consensus/SKILL.md

@@ -1,114 +1,138 @@
----
-name: tfx-consensus
-description: 3자 합의 엔진 — 모든 Deep 스킬의 핵심 인프라. Claude/Codex/Gemini 독립 분석 결과를 교차검증하여 편향 없는 합의를 도출한다.
-triggers: []
-argument-hint: "(내부 전용 — Deep 스킬이 자동 호출)"
----
-
-# tfx-consensus — Tri-CLI Consensus Engine
-
-> 모든 Deep 스킬의 공통 기반. 3개 CLI의 독립 결과를 교차검증하여 합의 도출.
-
-## Core Protocol
-
-이 스킬은 직접 호출하지 않는다. `tfx-deep-*` 스킬이 내부적으로 사용한다.
-
-## Consensus Algorithm
-
-### Phase 1: Independent Analysis (Anti-Herding)
-
-3개 CLI가 **동시에, 상호 결과를 보지 않고** 독립 분석한다. 이것이 핵심이다 — 한 CLI의 결과가 다른 CLI에 영향을 주면 편향이 발생한다.
-
-```
-실행 방식 (MANDATORY — headless dispatch):
-  ├─ Claude (Opus/Sonnet): Agent(subagent_type, run_in_background=true)
-  └─ CLI 워커 (Codex+Gemini): Bash("tfx multi --teammate-mode headless --auto-attach --dashboard \
-        --assign 'codex:{prompt}:analyst' \
-        --assign 'gemini:{prompt}:analyst' \
-        --timeout 600")
-
-각 CLI에게 동일한 프롬프트를 전달하되, 출력 형식을 JSON으로 강제:
-  {
-    "findings": [
-      { "id": "F1", "category": "...", "severity": "critical|high|medium|low", "description": "...", "evidence": "..." }
-    ],
-    "summary": "...",
-    "confidence": 0.0-1.0
-  }
-```
-
-### Phase 2: Cross-Validation
-
-Claude가 3개 결과를 통합하여 교차검증한다:
-
-```
-입력: result_claude, result_codex, result_gemini
-
-for each finding in ALL results:
-  agreement_count = count(CLIs that found this or similar finding)
-
-  if agreement_count >= 2:
-    mark as "CONSENSUS" (합의됨)
-  elif agreement_count == 1:
-    mark as "DISPUTED" (미합의 — 추가 검증 필요)
-
-consensus_score = len(CONSENSUS) / len(ALL_UNIQUE) * 100
-```
-
-### Phase 3: Resolution (consensus_score < 70일 때)
-
-```
-미합의 항목에 대해 2차 라운드:
-  1. 각 CLI에게 다른 두 CLI의 반대 논거를 제시
-  2. "수용(accept) 또는 반박(rebut)으로 응답하라"
-  3. 수용이 2개 이상이면 CONSENSUS로 승격
-  4. 여전히 미합의이면 사용자에게 판단 요청 (AskUserQuestion)
-```
-
-### Learned Weights (시간 기반 신뢰도)
-
-```
-각 CLI의 historical accuracy를 .omc/state/consensus-weights.json에 저장:
-{
-  "claude": { "accuracy": 0.85, "total": 100, "correct": 85 },
-  "codex":  { "accuracy": 0.82, "total": 100, "correct": 82 },
-  "gemini": { "accuracy": 0.78, "total": 100, "correct": 78 }
-}
-
-가중 투표 시 accuracy를 weight로 사용:
-  weighted_score = (claude_vote * 0.85 + codex_vote * 0.82 + gemini_vote * 0.78) / (0.85 + 0.82 + 0.78)
-```
-
-## Output Format
-
-```json
-{
-  "consensus_score": 85,
-  "consensus_items": [...],
-  "disputed_items": [...],
-  "resolved_items": [...],
-  "user_decision_needed": [...],
-  "cli_weights": { "claude": 0.85, "codex": 0.82, "gemini": 0.78 }
-}
-```
-
-## Integration Point
-
-Deep 스킬에서 사용하는 방법:
-
-```
-1. 프롬프트 준비 (주제 + 분석 관점 + 출력 형식)
-2. 3개 CLI 병렬 실행 (headless dispatch + Agent background)
-3. 결과 수집
-4. 위 Consensus Algorithm 적용
-5. consensus_score >= 70 → 확정
-6. consensus_score < 70 → Resolution Phase 진입
-7. 최종 결과를 호출 스킬에 반환
-```
-
-## Token Budget
-
-- Phase 1 (3x 독립분석): ~15K (각 5K)
-- Phase 2 (교차검증): ~3K
-- Phase 3 (Resolution, 필요 시): ~8K
-- **총합**: 18-26K tokens
+---
+name: tfx-consensus
+description: 3자 합의 엔진 — 모든 Deep 스킬의 핵심 인프라. Claude/Codex/Gemini 독립 분석 결과를 교차검증하여 편향 없는 합의를 도출한다.
+triggers: []
+argument-hint: "(내부 전용 — Deep 스킬이 자동 호출)"
+---
+
+# tfx-consensus — Tri-CLI Consensus Engine
+
+> 모든 Deep 스킬의 공통 기반. 3개 CLI의 독립 결과를 교차검증하여 합의 도출.
+
+## HARD RULES
+
+> headless-guard가 이 규칙 위반을 **자동 차단**한다. 우회 불가.
+
+1. **`codex exec` / `gemini -p` 직접 호출 절대 금지**
+2. Codex·Gemini → `Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'cli:프롬프트:역할' --timeout 600")` **만** 사용
+3. Claude → `Agent(run_in_background=true)`
+4. Bash + Agent를 같은 메시지에서 동시 호출하여 병렬 실행
+
+이 스킬은 직접 호출하지 않는다. `tfx-deep-*` 스킬이 내부적으로 사용한다.
+
+## MODEL ROLES
+
+| Model | Profile | 역할 | 강점 |
+|-------|---------|------|------|
+| Claude Opus | architect | 합의 통합 및 교차검증 조율 | 논리 분석, 불일치 해소 |
+| Codex | analyst | 구현/보안 관점 독립 분석 | 코드 품질, 취약점 탐지 |
+| Gemini | analyst | UX/문서화 관점 독립 분석 | DX, 접근성, 가독성 |
+
+## EXECUTION STEPS
+
+### Step 1: 독립 분석 dispatch (Anti-Herding)
+
+3개 CLI가 **동시에, 상호 결과를 보지 않고** 독립 분석한다. 한 CLI의 결과가 다른 CLI에 영향을 주면 편향이 발생한다.
+
+**아래 2개 도구를 반드시 같은 응답에서 동시에 호출하라.**
+
+**도구 1 — Claude (Opus/Sonnet) 독립 분석:**
+```
+Agent(
+  subagent_type="oh-my-claudecode:architect",
+  model="opus",
+  run_in_background=true,
+  name="consensus-claude",
+  description="독립 분석 — Claude 관점",
+  prompt="{analysis_prompt} 출력 형식을 JSON으로 강제: { findings: [{ id: 'F1', category: '...', severity: 'critical|high|medium|low', description: '...', evidence: '...' }], summary: '...', confidence: 0.0-1.0 }"
+)
+```
+
+**도구 2 — Codex+Gemini 독립 분석 headless dispatch:**
+```
+Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'codex:{analysis_prompt} 출력 형식을 JSON으로 강제: { findings: [{ id: string, category: string, severity: critical|high|medium|low, description: string, evidence: string }], summary: string, confidence: 0.0-1.0 }:analyst' --assign 'gemini:{analysis_prompt} 출력 형식을 JSON으로 강제: { findings: [{ id: string, category: string, severity: critical|high|medium|low, description: string, evidence: string }], summary: string, confidence: 0.0-1.0 }:analyst' --timeout 600")
+```
+
+### Step 2: 교차검증 (Cross-Validation)
+
+3개 결과(`result_claude`, `result_codex`, `result_gemini`)를 수집한 후 Claude가 통합 교차검증을 수행한다.
+
+합의 분류 알고리즘:
+- 각 finding에 대해 동의한 CLI 수를 집계
+- `agreement_count >= 2` → **CONSENSUS** (합의됨)
+- `agreement_count == 1` → **DISPUTED** (미합의 — 추가 검증 필요)
+- `consensus_score = len(CONSENSUS) / len(ALL_UNIQUE) * 100`
+
+`consensus_score >= 70`이면 Step 4로 직행. 미만이면 Step 3 진행.
+
+### Step 3: Resolution (consensus_score < 70일 때만)
+
+미합의 항목에 대해 2차 라운드를 진행한다.
+
+**아래 2개 도구를 반드시 같은 응답에서 동시에 호출하라.**
+
+**도구 1 — Claude 재검토:**
+```
+Agent(
+  subagent_type="oh-my-claudecode:architect",
+  model="opus",
+  run_in_background=true,
+  name="consensus-resolve-claude",
+  description="미합의 항목 2차 검토",
+  prompt="미합의 항목 목록: {disputed_items}. 다른 두 CLI의 반대 논거: Codex — {codex_rebuttal}, Gemini — {gemini_rebuttal}. 각 항목에 대해 수용(accept) 또는 반박(rebut)으로 응답하라. 수용 시 근거 필수."
+)
+```
+
+**도구 2 — Codex+Gemini 재검토:**
+```
+Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'codex:미합의 항목 목록: {disputed_items}. 다른 두 CLI의 반대 논거: Claude — {claude_rebuttal}, Gemini — {gemini_rebuttal}. 각 항목에 대해 수용(accept) 또는 반박(rebut)으로 응답하라. 수용 시 근거 필수.:analyst' --assign 'gemini:미합의 항목 목록: {disputed_items}. 다른 두 CLI의 반대 논거: Claude — {claude_rebuttal}, Codex — {codex_rebuttal}. 각 항목에 대해 수용(accept) 또는 반박(rebut)으로 응답하라. 수용 시 근거 필수.:analyst' --timeout 600")
+```
+
+Resolution 결과 처리:
+- 수용 2개 이상 → CONSENSUS로 승격
+- 여전히 미합의 → 사용자에게 판단 요청 (AskUserQuestion)
+
+### Step 4: 최종 합의 결과 반환
+
+Learned Weights를 `.omc/state/consensus-weights.json`에서 읽어 가중 투표에 적용한다:
+
+```json
+{
+  "claude": { "accuracy": 0.85, "total": 100, "correct": 85 },
+  "codex":  { "accuracy": 0.82, "total": 100, "correct": 82 },
+  "gemini": { "accuracy": 0.78, "total": 100, "correct": 78 }
+}
+```
+
+가중 투표:
+`weighted_score = (claude_vote * 0.85 + codex_vote * 0.82 + gemini_vote * 0.78) / (0.85 + 0.82 + 0.78)`
+
+최종 결과를 호출 스킬에 반환한다:
+
+```json
+{
+  "consensus_score": 85,
+  "consensus_items": [...],
+  "disputed_items": [...],
+  "resolved_items": [...],
+  "user_decision_needed": [...],
+  "cli_weights": { "claude": 0.85, "codex": 0.82, "gemini": 0.78 }
+}
+```
+
+## ERROR RECOVERY
+
+| 상황 | 대응 |
+|------|------|
+| headless timeout (600s) | Claude Agent로 해당 역할 대체 실행 |
+| Codex 워커 실패 | Agent(oh-my-claudecode:architect, model="opus") 대체 |
+| Gemini 워커 실패 | Agent(oh-my-claudecode:critic, model="sonnet") 대체 |
+
+## 토큰 예산
+
+| Phase | 토큰 |
+|-------|------|
+| Phase 1 (3x 독립분석) | ~15K (각 5K) |
+| Phase 2 (교차검증) | ~3K |
+| Phase 3 (Resolution, 필요 시) | ~8K |
+| **총합** | **18-26K** |