triflux 9.2.4 → 9.3.0

package/bin/triflux.mjs

@@ -876,6 +876,21 @@ function cmdSetup(options = {}) {
           skillCount++;
         }
       }
+      // references/ 디렉토리 동기화 (존재하면)
+      const refSrc = join(skillsSrc, name, "references");
+      const refDst = join(skillsDst, name, "references");
+      if (existsSync(refSrc)) {
+        mkdirSync(refDst, { recursive: true });
+        for (const refFile of readdirSync(refSrc)) {
+          const rSrc = join(refSrc, refFile);
+          const rDst = join(refDst, refFile);
+          if (statSync(rSrc).isFile()) {
+            if (!existsSync(rDst) || readFileSync(rSrc, "utf8") !== readFileSync(rDst, "utf8")) {
+              copyFileSync(rSrc, rDst);
+            }
+          }
+        }
+      }
     }
     for (const { alias, source } of SKILL_ALIASES) {
       const srcDir = join(skillsSrc, source);

package/package.json

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

package/skills/tfx-auto/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: tfx-auto
-description: 통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반.
+description: >
+  통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반.
+  '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은
+  구현/수정 요청에 사용. CLI 라우팅이 필요한 모든 작업에 적극 활용.
 triggers:
   - tfx-auto
   - implement

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

@@ -1,6 +1,8 @@
 ---
 name: tfx-auto-codex
-description: Codex 리드형 tfx-auto. Claude 네이티브 역할을 Codex로 치환하고 Gemini 사용은 유지합니다.
+description: >
+  Codex 리드형 tfx-auto. Claude 네이티브 역할을 Codex로 치환하고 Gemini 사용은 유지합니다.
+  '코덱스 리드', '코덱스가 주도', 'codex lead' 같은 요청에 사용.
 triggers:
   - tfx-auto-codex
 argument-hint: "\"작업 설명\" | N:agent_type \"작업 설명\""

package/skills/tfx-autopilot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tfx-autopilot
-description: "간단한 작업을 자율적으로 구현해야 할 때 사용한다. 'autopilot', '자동으로', '알아서 해', '그냥 해줘' 같은 요청에 반드시 사용. 명확한 단일 작업을 빠르게 자동 구현+검증할 때 적극 활용."
+description: "단일 파일/모듈 수준의 간단한 작업을 자율 구현할 때 사용한다. 구현+검증까지 5분 이내 완료 가능한 작업, '간단히', '빠르게', '하나만', '자동으로', '알아서 해', '그냥 해줘' 같은 수식어가 있을 때 사용. 복잡한 멀티파일 작업은 tfx-fullcycle을 사용하세요."
 triggers:
   - autopilot
   - 자동

package/skills/tfx-autoresearch/SKILL.md

@@ -3,6 +3,8 @@ name: tfx-autoresearch
 description: >
   자율 웹 리서치 → 실행 가능 계획 도출.
   주제를 받아 웹 검색 → 정보 수집 → 분석 → 구조화된 리서치 보고서 생성.
+  '알아봐', '조사해', '리서치해줘', '검색하고 정리해', 'research and plan' 같은 요청에 반드시 사용.
+  웹 검색 후 실행 가능한 계획까지 도출이 필요할 때 적극 활용.
 triggers:
   - autoresearch
   - 자율 리서치

package/skills/tfx-codex/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: tfx-codex
-description: Codex-Only 오케스트레이터. tfx-auto 워크플로우를 Codex 전용으로 고정합니다.
+description: >
+  Codex-Only 오케스트레이터. tfx-auto 워크플로우를 Codex 전용으로 고정합니다.
+  '코덱스로 해줘', '코덱스한테 시켜', 'codex로', 'Codex 전용' 같은 요청에 반드시 사용.
 triggers:
   - tfx-codex
 argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""

package/skills/tfx-consensus/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: tfx-consensus
-description: 3자 합의 엔진 — 모든 Deep 스킬의 핵심 인프라. Claude/Codex/Gemini 독립 분석 결과를 교차검증하여 편향 없는 합의를 도출한다.
-triggers: []
-argument-hint: "(내부 전용 — Deep 스킬이 자동 호출)"
+description: >
+  3자 합의 엔진 — 모든 Deep 스킬의 핵심 인프라. Claude/Codex/Gemini 독립 분석 결과를 교차검증하여 편향 없는 합의를 도출한다.
+  독립 실행도 가능: '합의로 분석해', '3자 합의', 'consensus' 같은 요청 시 직접 호출 가능.
+triggers: [consensus, 합의]
+argument-hint: "<분석 주제 또는 컨텍스트> (Deep 스킬 내부 자동 호출 또는 직접 사용 가능)"
 ---
 
 # tfx-consensus — Tri-CLI Consensus Engine

package/skills/tfx-fullcycle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tfx-fullcycle
-description: "복잡한 기능을 처음부터 끝까지 자율 개발해야 할 때 사용한다. 'deep autopilot', '풀 오토', '처음부터 끝까지', 'full auto', '전체 파이프라인으로' 같은 요청에 사용. 설계→계획→구현→QA→검증 전체 사이클이 필요한 대규모 기능에 적극 활용."
+description: "여러 파일/모듈에 걸친 복잡한 기능을 처음부터 끝까지 자율 개발할 때 사용한다. 설계→계획→구현→QA→검증 전체 파이프라인이 필요한 작업, '처음부터 끝까지', '전체', '완전히', '풀 오토', 'full auto', '전체 파이프라인으로' 같은 수식어가 있을 때 사용. 단순 단일 작업은 tfx-autopilot이 더 빠릅니다."
 triggers:
   - deep autopilot
   - 풀 오토

package/skills/tfx-gemini/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: tfx-gemini
-description: Gemini-Only 오케스트레이터. tfx-auto 워크플로우를 Gemini 전용으로 고정합니다.
+description: >
+  Gemini-Only 오케스트레이터. tfx-auto 워크플로우를 Gemini 전용으로 고정합니다.
+  '제미나이로 해줘', '제미나이한테 시켜', 'gemini로', 'Gemini 전용' 같은 요청에 반드시 사용.
 triggers:
   - tfx-gemini
 argument-hint: "\"작업 설명\" | N:gemini \"작업 설명\""

package/skills/tfx-hooks/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: tfx-hooks
+description: >
+  Claude Code 훅 우선순위 관리자. AskUserQuestion 기반 인터랙티브 UI로
+  훅 스캔, 우선순위 조정, 오케스트레이터 적용/복원, 개별 훅 토글을 수행합니다.
+  사용자가 훅, hooks, 훅 관리, hook priority, 훅 우선순위, 오케스트레이터,
+  orchestrator, 훅 설정, hook 설정, 훅 순서, hook order를 언급할 때마다
+  반드시 이 스킬을 사용하세요.
+  Use when: hooks, 훅, hook priority, 훅 관리, orchestrator, 오케스트레이터, 훅 설정, 훅 순서
+triggers:
+  - tfx-hooks
+argument-hint: "[scan|apply|restore]"
+---
+
+# tfx-hooks — 훅 우선순위 관리자
+
+> Claude Code 훅의 실행 순서를 관리합니다. triflux 훅이 항상 최우선 실행되도록 보장합니다.
+
+## 핵심 개념
+
+Claude Code는 같은 이벤트에 매칭된 훅을 **병렬 실행**합니다. 순서 보장이 불가능합니다.
+triflux의 **hook-orchestrator**는 이벤트당 하나의 진입점을 두고, 내부에서 **우선순위대로 순차 실행**합니다.
+
+```
+settings.json → hook-orchestrator.mjs (단일 진입점)
+                    ↓ hook-registry.json 읽기
+                    ↓ priority 순 정렬
+                    1. triflux 훅 (priority=0)
+                    2. OMC 훅 (priority=50)
+                    3. 외부 훅 (priority=100)
+```
+
+## 워크플로우
+
+### Step 1: 현재 상태 확인
+
+```bash
+Bash("node hooks/hook-manager.mjs status")
+```
+
+결과 JSON에서 `orchestrated` 필드로 적용 여부를 판단한다.
+
+### Step 2: 메인 메뉴 (AskUserQuestion)
+
+```
+question: "훅 관리 — 어떤 작업을 수행하시겠습니까?"
+header: "Hook Manager"
+options:
+  - label: "현재 상태 보기"
+    description: "settings.json 훅 스캔 + 오케스트레이터 적용 상태"
+  - label: "오케스트레이터 적용"
+    description: "모든 훅을 통합 — triflux 최우선 실행 보장"
+  - label: "변경점 미리보기 (diff)"
+    description: "적용 시 어떻게 바뀌는지 확인"
+  - label: "원래대로 복원"
+    description: "오케스트레이터 제거, 원래 settings.json 훅으로 복원"
+  - label: "개별 훅 관리"
+    description: "특정 훅 활성/비활성, 우선순위 변경"
+```
+
+### Step 3: 선택에 따른 분기
+
+#### "현재 상태 보기"
+
+```bash
+Bash("node hooks/hook-manager.mjs scan")
+```
+
+결과 JSON을 파싱하여 테이블로 표시:
+
+```markdown
+## 현재 훅 상태
+
+| 이벤트 | 훅 수 | 소스 |
+|--------|-------|------|
+| SessionStart | 4 | triflux(3), session-vault(1) |
+| PreToolUse | 3 | triflux(1), omc(2) |
+| ...    | ...   | ... |
+
+오케스트레이터: ❌ 미적용 / ✅ 적용됨 (N개 이벤트)
+```
+
+#### "오케스트레이터 적용"
+
+먼저 diff를 보여준 후 확인:
+
+```bash
+Bash("node hooks/hook-manager.mjs diff")
+```
+
+결과를 표시한 뒤 AskUserQuestion:
+```
+question: "위 변경을 적용하시겠습니까?"
+header: "확인"
+options:
+  - label: "적용"
+    description: "settings.json 백업 후 오케스트레이터 적용"
+  - label: "취소"
+    description: "변경 없이 돌아가기"
+```
+
+"적용" 선택 시:
+```bash
+Bash("node hooks/hook-manager.mjs apply")
+```
+
+적용 결과 표시:
+```
+✅ 오케스트레이터 적용 완료
+   N개 이벤트 → 1개 오케스트레이터로 통합
+   실행 순서: triflux(0) → OMC(50) → external(100)
+   복원: /tfx-hooks → 원래대로 복원
+   또는: triflux hooks restore
+```
+
+#### "변경점 미리보기 (diff)"
+
+```bash
+Bash("node hooks/hook-manager.mjs diff")
+```
+
+결과를 테이블로 표시:
+```markdown
+| 이벤트 | 현재 | 적용 후 | 변경 |
+|--------|------|---------|------|
+| PreToolUse | 2개 개별 | 1개 오케스트레이터 (내부 4개) | 교체 |
+| PostToolUse | 없음 | 1개 오케스트레이터 (내부 1개) | 신규 |
+| ... | ... | ... | ... |
+```
+
+#### "원래대로 복원"
+
+```bash
+Bash("node hooks/hook-manager.mjs restore")
+```
+
+결과에서 status를 확인:
+- `"restored"` → "✅ 원래 훅 설정이 복원되었습니다."
+- `"no_backup"` → "⚠️ 백업이 없습니다. 오케스트레이터를 적용한 적이 없습니다."
+
+#### "개별 훅 관리"
+
+레지스트리에서 전체 훅 목록을 읽어 표시:
+
+```bash
+Bash("node -e \"const r=JSON.parse(require('fs').readFileSync('hooks/hook-registry.json','utf8')); const all=[]; for(const [e,hs] of Object.entries(r.events)) hs.forEach(h=>all.push({event:e,...h})); console.log(JSON.stringify(all))\"")
+```
+
+결과를 테이블로 표시 후 AskUserQuestion:
+```
+question: "어떤 훅을 관리하시겠습니까?"
+header: "훅 선택"
+options:
+  (레지스트리의 각 훅을 옵션으로 나열)
+  - label: "tfx-safety-guard"
+    description: "[PreToolUse:Bash] 위험 명령 차단 — priority:0, 활성"
+  - label: "tfx-agent-route-guard"
+    description: "[PreToolUse:Agent] 에이전트 라우팅 — priority:0, 활성"
+  - label: "omc-headless-guard"
+    description: "[PreToolUse:Bash|Agent] headless 가드 — priority:50, 활성"
+  ...
+```
+
+훅 선택 후 AskUserQuestion:
+```
+question: "{hookId} — 어떤 조작을 하시겠습니까?"
+header: "훅 조작"
+options:
+  - label: "활성/비활성 토글"
+    description: "현재: 활성 → 비활성으로 전환"
+  - label: "우선순위 변경"
+    description: "현재: 0 — 숫자가 낮을수록 먼저 실행"
+  - label: "뒤로"
+    description: "훅 목록으로 돌아가기"
+```
+
+"활성/비활성 토글":
+```bash
+Bash("node hooks/hook-manager.mjs toggle {hookId}")
+```
+
+"우선순위 변경":
+AskUserQuestion으로 새 우선순위 입력:
+```
+question: "새 우선순위를 입력하세요 (0=최우선, 50=중간, 100=후순위)"
+header: "Priority"
+```
+```bash
+Bash("node hooks/hook-manager.mjs set-priority {hookId} {newPriority}")
+```
+
+변경 후 오케스트레이터가 적용된 상태라면 재적용 안내:
+```
+💡 레지스트리가 변경되었습니다. 오케스트레이터는 실시간으로 레지스트리를 읽으므로 재적용 불필요합니다.
+```
+
+## CLI 대응
+
+| 스킬 UI | CLI 명령 |
+|---------|---------|
+| 현재 상태 보기 | `triflux hooks scan` |
+| 오케스트레이터 적용 | `triflux hooks apply` |
+| 변경점 미리보기 | `triflux hooks diff` |
+| 원래대로 복원 | `triflux hooks restore` |
+| 상태 확인 | `triflux hooks status` |
+| 훅 토글 | `triflux hooks toggle <hookId>` |
+| 우선순위 변경 | `triflux hooks set-priority <hookId> <priority>` |
+
+## 에러 처리
+
+| 상황 | 처리 |
+|------|------|
+| hook-registry.json 없음 | "레지스트리가 없습니다. triflux hooks 디렉토리를 확인하세요." |
+| settings.json 파싱 실패 | "settings.json이 손상되었습니다. 수동 확인이 필요합니다." |
+| 백업 없이 복원 시도 | "오케스트레이터를 적용한 적이 없어 복원할 수 없습니다." |
+| hook-manager.mjs 실행 실패 | "hook-manager를 실행할 수 없습니다. node hooks/hook-manager.mjs를 직접 실행해 보세요." |

package/skills/tfx-multi/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: tfx-multi
-description: 멀티-CLI 팀 모드. Claude Native Agent Teams + Codex/Gemini 멀티모델 오케스트레이션.
+description: >
+  멀티-CLI 팀 모드. Claude Native Agent Teams + Codex/Gemini 멀티모델 오케스트레이션.
+  '멀티로', '팀 모드', '다중 CLI', '3개 다 동원', 'multi' 같은 요청에 반드시 사용.
+  Claude+Codex+Gemini 협업이 필요한 모든 상황에 적극 활용.
 triggers:
   - tfx-multi
 argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'

package/skills/tfx-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tfx-plan
-description: "구현 계획이 필요할 때 사용한다. '계획 세워줘', 'plan', '플랜', '어떻게 구현하지', '태스크 분해', '작업 순서' 같은 요청에 반드시 사용. 기능 구현 전 영향 범위 파악과 태스크 분해가 필요할 때 적극 활용."
+description: "구현 계획이 필요할 때 사용한다. '계획 세워줘', 'plan', '플랜', '어떻게 구현하지', '태스크 분해', '작업 순서' 같은 요청에 반드시 사용. 기능 구현 전 영향 범위 파악과 태스크 분해가 필요할 때 적극 활용. 작업 분해, 순서 정리, '어떤 순서로', '먼저 뭐 해야', 'breakdown', 'decompose', 'task list' 같은 요청에도 적극 활용. 단순 계획은 이 스킬, 3자 합의 계획은 tfx-deep-plan을 사용."
 triggers:
   - plan
   - 계획

package/skills/tfx-ralph/SKILL.md

@@ -1,78 +1,23 @@
 ---
 name: tfx-ralph
-description: "작업이 완전히 끝날 때까지 멈추지 않고 반복 실행해야 할 때 사용한다. 'ralph', '끝까지 해', '멈추지 마', 'don't stop', '완료될 때까지', '다 될 때까지 계속' 같은 요청에 반드시 사용. 여러 기준을 모두 충족해야 하는 복잡한 구현 작업에 적극 활용."
+description: >
+  tfx-persist의 별칭(alias). 'ralph', '끝까지 해', '멈추지 마' 같은 요청에 사용.
+  실제 동작은 tfx-persist 스킬이 수행합니다.
+  Use when: ralph, 끝까지, don't stop, 멈추지 마
 triggers:
   - tfx-ralph
-argument-hint: "<완료할 작업 설명>"
+  - ralph
 ---
 
-# tfx-ralph — Alias for tfx-persist
+# tfx-ralph — tfx-persist 별칭
 
-> **래퍼**: tfx-persist의 alias. 동일 기능.
-> `tfx-ralph`는 `tfx-persist`의 alias이다. 동일한 Tri-Verified Persistence Loop을 실행한다.
-> The boulder never stops — but it stops being wrong.
+이 스킬은 `tfx-persist`와 동일합니다. `/tfx-persist` 스킬을 호출하세요.
 
-## 실행 계약
-
-이 스킬은 `tfx-persist`와 **완전히 동일한 실행 흐름**을 공유한다:
-
-1. **동일한 headless multi 경로** — `tfx multi --teammate-mode headless` 기반 3자 검증
-2. **동일한 degradation 체인** — Tier 1 (전체 가용) → Tier 2 (부분 가용) → Tier 3 (Claude only)
-3. **동일한 워크플로우** — Goal Definition → Execution Loop → Final Verification → Deslop Pass
-
-## 전제조건 프로브 및 Tier Degradation
-
-> **진입 즉시 실행** — 10초 내 가시적 출력을 보장한다. 빈 stdout + exit 0 **금지**.
-
-### 환경 프로브
-
-```bash
-psmux --version 2>/dev/null && \
-  curl -sf http://127.0.0.1:27888/status >/dev/null && \
-  codex --version 2>/dev/null && \
-  gemini --version 2>/dev/null
-```
-
-### Tier 판정
-
-| Tier | 조건 | 실행 방식 |
-|------|------|----------|
-| **Tier 1** | psmux + Hub + Codex + Gemini 전부 정상 | 기존 headless multi (변경 없음) |
-| **Tier 2** | 일부 CLI만 가용 (Codex 또는 Gemini 중 하나) | 가용 CLI + Claude Agent 조합 |
-| **Tier 3** | headless 불가 또는 `claude -p` one-shot | Claude Agent only |
-
-```
-IF claude -p (one-shot 모드):
-  → Tier 3 즉시 fallback
-
-IF psmux 없음 OR Hub 미응답:
-  → Tier 3
-
-IF Codex 없음 AND Gemini 없음:
-  → Tier 3
-
-IF Codex 없음 OR Gemini 없음:
-  → Tier 2
-
-ELSE:
-  → Tier 1
-```
-
-### Tier 3 진입 시 필수 출력
-
-```
-⚠ [Tier 3] headless multi 환경 미충족 — single-model 모드로 실행합니다 (consensus 미적용)
-  누락: {missing_components}
-  권장: psmux, Hub, Codex CLI, Gemini CLI 설치 후 재실행
-```
-
-Tier 3에서는 모든 headless dispatch(`tfx multi ...`)를 **Claude Agent**(subagent)로 대체한다.
-Tier 2에서는 누락된 CLI만 Claude Agent로 대체한다.
-
-## 라우팅
+## 동작
 
+Skill 도구로 tfx-persist를 호출한다:
 ```
-/tfx-ralph "{task}" → /tfx-persist "{task}" 로 내부 전달
+Skill: tfx-persist
 ```
 
-전체 워크플로우, 토큰 예산, Anti-Stuck 메커니즘은 [tfx-persist/SKILL.md](../tfx-persist/SKILL.md)를 참조하라.
+사용자의 원래 요청을 그대로 전달한다.

package/skills/tfx-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tfx-review
-description: "코드 리뷰가 필요할 때 사용한다. 'review', '리뷰해줘', '코드 봐줘', '이거 괜찮아?', 'PR 리뷰', '변경사항 확인' 같은 요청에 반드시 사용. git diff, 특정 파일, 또는 최근 변경에 대한 빠른 피드백이 필요할 때 적극 활용."
+description: "코드 리뷰가 필요할 때 사용한다. 'review', '리뷰해줘', '코드 봐줘', '이거 괜찮아?', 'PR 리뷰', '변경사항 확인' 같은 요청에 반드시 사용. git diff, 특정 파일, 또는 최근 변경에 대한 빠른 피드백이 필요할 때 적극 활용. 코드 변경사항 확인, '이거 문제 없어?', 'looks good?', 'LGTM?', '머지해도 될까' 같은 요청에도 적극 활용. 꼼꼼한 심층 리뷰는 tfx-deep-review를 사용."
 triggers:
   - review
   - 리뷰