triflux 10.3.4 → 10.7.0

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

@@ -0,0 +1,217 @@
+---
+internal: true
+name: tfx-deep-research
+description: "기술 비교, 아키텍처 조사, 경쟁사 분석 등 깊이 있는 리서치가 필요할 때 사용한다. '심층 조사', '자세히 알아봐', 'deep research', '전면 리서치', '비교 분석 보고서', '종합 리서치' 같은 요청에 반드시 사용. 단순 검색이 아닌 멀티소스 교차검증이 필요한 리서치에 적극 활용."
+triggers:
+  - deep research
+  - 딥 리서치
+  - 심층 리서치
+  - deep-research
+  - thorough research
+  - 깊이 조사
+  - 전면 리서치
+argument-hint: "[--depth quick|standard|deep] <리서치 주제>"
+---
+
+# {{SKILL_NAME}} — 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 영감.
+
+## 용도
+
+- 기술 선택 전 심층 조사
+- 경쟁사/대안 분석
+- 새 도메인 학습을 위한 종합 리서치
+- 아키텍처 결정 근거 수집
+- 학술/산업 동향 파악
+
+## 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를 같은 메시지에서 동시 호출하여 병렬 실행
+
+## MODEL ROLES
+
+| CLI | MCP | 관점 |
+|-----|-----|------|
+| Claude | Exa (neural semantic) | 학술/기술 깊이 (논문, 공식 문서, 벤치마크) |
+| Codex | Brave Search | 실용/구현/산업 사례 중심 |
+| Gemini | Tavily | 비용/운영/DX(개발자 경험) 중심 |
+
+## Depth 모드
+
+| 모드 | 서브쿼리 | 소스/쿼리 | 라운드 | 토큰 | 시간 |
+|------|---------|----------|--------|------|------|
+| quick | 3개 | 2 | 1 | ~20K | 2-3분 |
+| standard | 5개 | 3 | 1-2 | ~40K | 5-8분 |
+| deep | 8-10개 | 5 | 2-3 | ~80K | 10-15분 |
+
+기본값: standard
+
+## EXECUTION STEPS
+
+### Pre-Phase: Depth 선택
+
+`--depth` 플래그가 지정되지 않은 경우, AskUserQuestion으로 depth를 선택받아라:
+
+```
+AskUserQuestion:
+  "리서치 깊이를 선택하세요:"
+  1. quick (3 서브쿼리, ~20K 토큰, 2-3분)
+  2. standard (5 서브쿼리, ~40K 토큰, 5-8분) [기본]
+  3. deep (8-10 서브쿼리, ~80K 토큰, 10-15분)
+```
+
+사용자가 빈 응답을 보내면 기본값 `standard`를 적용하라.
+
+### Step 1: 주제 분석 및 쿼리 분해
+
+Claude Opus로 주제를 분석하고 서브쿼리로 분해하라:
+
+- depth에 따라 서브쿼리 수를 결정한다 (quick=3, standard=5, deep=8-10)
+- 각 서브쿼리에 관점(학술/기술, 실용/산업, 비용/운영)을 매핑한다
+- sub_queries 목록과 perspectives 목록을 내부적으로 보유한다
+
+### Step 2: 3-CLI 독립 병렬 검색 (Anti-Herding)
+
+**아래 2개 도구를 반드시 같은 응답에서 동시에 호출하라.**
+
+Claude Agent를 백그라운드로 실행하라:
+
+```
+Agent(
+  subagent_type="claude",
+  model="opus",
+  run_in_background=true,
+  prompt="다음 서브쿼리를 Exa web_search_exa로 검색하라.
+  서브쿼리 목록: {sub_queries}
+  관점: 학술/기술 깊이 (논문, 공식 문서, 벤치마크)
+  각 쿼리에서 category='research paper' 우선, highlights=true, numResults=5로 검색하라.
+  각 결과의 제목, URL, 핵심 내용을 추출하여 구조화하여 반환하라."
+)
+```
+
+Codex와 Gemini를 headless dispatch로 동시에 실행하라:
+
+```
+Bash("tfx multi --teammate-mode headless --auto-attach --dashboard \
+  --assign 'codex:다음 서브쿼리를 Brave Search로 검색하고 결과를 종합하라. 서브쿼리 목록: {sub_queries}. 관점: 실용/구현/산업 사례 중심. brave_web_search와 brave_news_search를 활용하고, freshness=pw로 최신 결과를 우선하라. 각 쿼리당 상위 5개 결과의 제목, URL, 핵심 내용을 구조화하여 반환하라.:researcher' \
+  --assign 'gemini:다음 서브쿼리를 Tavily로 검색하라. 서브쿼리 목록: {sub_queries}. 관점: 비용/운영/DX(개발자 경험) 중심. tavily_search를 search_depth=advanced, max_results=5, include_raw_content=false로 호출하라. 각 결과를 구조화하여 제목, URL, 핵심 내용을 반환하라.:researcher' \
+  --timeout 600")
+```
+
+### Step 3: 결과 수집 및 교차검증
+
+3개 CLI 결과가 모두 수집되면 다음 기준으로 교차검증하라:
+
+1. 사실 일치: 3개 소스가 동일 사실을 보고하는가
+2. 추천 일치: 동일 기술/접근법을 추천하는가
+3. 수치 일치: 벤치마크, 가격, 성능 수치가 일치하는가
+4. 리스크 일치: 동일 위험을 식별하는가
+
+소스 신뢰도를 다음 가중치로 평가하라:
+- 공식 문서/벤치마크 → weight 1.0
+- 학술 논문 → weight 0.9
+- 신뢰 블로그 (engineering blog) → weight 0.7
+- 일반 블로그/포럼 → weight 0.5
+- 날짜 가중: 6개월 이내 ×1.0, 1년 이내 ×0.8, 2년 이내 ×0.5
+
+### Step 4: 합의 종합 보고서 생성
+
+Claude Opus가 교차검증된 결과를 종합하여 다음 구조로 최종 보고서를 작성하라:
+
+```markdown
+# Deep Research Report: {topic}
+**Date**: {date} | **Depth**: {depth} | **Consensus Score**: {score}%
+**Sources**: {total_sources}개 | **Sub-queries**: {count}개
+
+## Executive Summary
+{3-5줄 핵심 요약}
+
+## 핵심 발견사항 (Consensus Items)
+### 1. {finding_1} — 합의도: {3/3 또는 2/3}
+{상세 내용 + 근거 + 출처}
+
+### 2. {finding_2}
+...
+
+## 비교 분석
+| 항목 | 옵션A | 옵션B | 옵션C |
+|------|-------|-------|-------|
+| 성능 | ... | ... | ... |
+| 비용 | ... | ... | ... |
+| 운영 | ... | ... | ... |
+
+## 미합의 사항 (Disputed Items)
+- {항목}: Claude는 X, Codex는 Y, Gemini는 Z — 이유: ...
+
+## 추천
+{교차검증된 최종 추천 + 조건부 판단 기준}
+
+## 소스 목록
+1. [{title}]({url}) — 신뢰도: {score} — 사용 MCP: {exa|brave|tavily}
+...
+```
+
+### Step 5: Recursive Depth (deep 모드 전용)
+
+deep 모드에서 Phase 3 교차검증 중 중요 하위 주제가 발견되면 재귀적으로 Step 2-4를 반복하라:
+
+- 최대 3개 하위 주제까지 재귀 실행한다
+- 각 재귀 결과를 메인 보고서에 병합한다
+- 재귀 실행도 반드시 Agent + Bash 동시 호출 패턴을 사용한다
+
+## ERROR RECOVERY
+
+- Codex 또는 Gemini 결과가 없으면: 해당 CLI 없이 2개 소스로 교차검증을 진행하고 보고서에 누락 CLI를 명시하라
+- tfx multi 명령이 실패하면: 오류 메시지를 그대로 출력하고 재시도 1회 후 실패를 사용자에게 보고하라
+- Agent 결과가 없으면: Claude Exa 검색 없이 나머지 2개 소스로 진행하라
+
+## TOKEN BUDGET
+
+| 단계 | quick | standard | deep |
+|------|-------|----------|------|
+| Step 1 (분해) | 1K | 2K | 3K |
+| Step 2 (3x검색) | 9K | 18K | 30K |
+| Step 3 (교차검증) | 3K | 5K | 8K |
+| Step 4 (보고서) | 5K | 10K | 15K |
+| Step 5 (재귀) | — | — | 24K |
+| **총합** | **~18K** | **~35K** | **~80K** |
+
+## MCP 활용 전략 (Exa/Brave/Tavily 리버스엔지니어링 기반)
+
+### Exa 최적 활용
+- `type: "auto"` — neural+keyword 하이브리드
+- `category: "research paper"` — 학술 검색 시
+- `highlights: true, text.maxCharacters: 300` — 토큰 효율 핵심
+- `includeDomains` — 신뢰 도메인 필터링
+
+### Brave 최적 활용
+- `brave_news_search` — 최신 동향/뉴스
+- `freshness: "pw"` (past week) — 최신성 보장
+- `result_filter: "web"` — 불필요한 결과 방지
+- 독립 인덱스 → Google/Bing과 다른 결과
+
+### Tavily 최적 활용
+- `tavily_search` — 빠른 범용 검색
+- `include_raw_content: false` — 토큰 절약
+- `max_results: 5` — 적정 결과 수
+- `search_depth: "advanced"` — standard 모드 이상
+
+## 사용 예
+
+```
+/tfx-deep-research "2026 실시간 데이터 파이프라인 아키텍처 비교"
+/tfx-deep-research --depth deep "Claude Code vs Cursor vs Windsurf 멀티에이전트 지원 비교"
+/tfx-deep-research --depth quick "pnpm vs bun vs npm 2026 벤치마크"
+```

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

@@ -0,0 +1,179 @@
+---
+internal: true
+name: tfx-deep-review
+description: "철저한 코드 리뷰가 필요할 때 사용한다. '꼼꼼히 리뷰', 'deep review', '심층 리뷰', '보안까지 리뷰', '다각도 리뷰', '중요한 변경이라 제대로 봐줘' 같은 요청에 사용. 보안/성능/가독성 3관점 독립 검증이 필요한 중요 코드 변경에 적극 활용."
+triggers:
+  - deep review
+  - 심층 리뷰
+  - multi review
+  - deep-review
+  - 철저한 리뷰
+argument-hint: "[파일 경로 또는 변경 설명]"
+---
+
+# {{SKILL_NAME}} — Tri-CLI Deep Code Review
+
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
+> **Light 버전**: tfx-review. 기본값. 깊이 수정자 없으면 Light 선택.
+> 3-CLI 독립 리뷰 → 교차검증 → 2+ 합의 항목만 보고. Diffray + Calimero 영감.
+
+## 핵심 원리
+
+**Anti-Herding**: Round 1에서 3개 CLI가 서로의 결과를 보지 않고 독립 리뷰.
+**Consensus Only**: 2개 이상 CLI가 동일 이슈를 지적한 항목만 최종 보고 → false-positive 87% 감소.
+
+## 전제조건 프로브 및 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로 대체한다.
+
+## 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를 같은 메시지에서 동시 호출하여 병렬 실행
+
+## MODEL ROLES
+
+| CLI | 역할 | 관점 |
+|-----|------|------|
+| Claude Opus | 로직+아키텍처 | 로직 결함, 아키텍처 위반, 설계 패턴 |
+| Codex | 보안+성능 | OWASP Top 10, O(n²) 패턴, 누락된 에러 핸들링 |
+| Gemini | 가독성+DX | 네이밍 컨벤션, 가독성, 주석 필요성, 타입 안전성 |
+
+## EXECUTION STEPS
+
+### Step 1: 리뷰 대상 수집
+
+`git diff` (staged + unstaged) 또는 사용자 지정 파일을 수집한다.
+
+### Step 2: 3-CLI 독립 리뷰 — 아래 2개 도구를 반드시 같은 응답에서 동시에 호출하라.
+
+**Claude Agent (로직+아키텍처):**
+```
+Agent(
+  subagent_type="oh-my-claudecode:code-reviewer",
+  model="opus",
+  run_in_background=true,
+  name="review-logic",
+  description="로직 결함 및 아키텍처 위반 독립 리뷰",
+  prompt="코드 리뷰어로서 로직/아키텍처 관점에서 이 코드를 분석하라. 로직 결함, 아키텍처 위반, 설계 패턴 문제를 찾아라. JSON으로 응답하라: { findings: [{ id, file, line, severity, category, description, suggestion }] }"
+)
+```
+
+**Codex + Gemini headless dispatch (보안+성능+가독성):**
+```
+Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'codex:보안/성능 전문가로서 이 코드를 분석하라. OWASP Top 10 취약점을 확인하라. O(n²) 이상의 성능 병목을 찾아라. 누락된 에러 핸들링을 지적하라. JSON으로 응답하라: { findings: [{ id, file, line, severity, category, description, suggestion }] }:reviewer' --assign 'gemini:코드 품질 전문가로서 이 코드를 분석하라. 가독성과 네이밍 컨벤션을 평가하라. 주석이 필요한 복잡한 로직을 식별하라. 타입 안전성 문제를 찾아라. 개발자 경험(DX)을 저해하는 패턴을 지적하라. JSON으로 응답하라: { findings: [{ id, file, line, severity, category, description, suggestion }] }:reviewer' --timeout 600")
+```
+
+### Step 3: Consensus Scoring
+
+모든 findings를 수집하여 유사도를 비교한다:
+- 동일 파일+라인±5 + 유사 카테고리 → 동일 이슈로 간주
+- 3/3 합의 → severity 유지
+- 2/3 합의 → severity 유지, 반대 의견 첨부
+- 1/3만 지적 → UNVERIFIED 표시 (참고용, 별도 섹션)
+
+`consensus_score = consensus_items / total_unique_items × 100`
+
+### Step 4: 종합 보고서 작성
+
+아래 형식으로 보고서를 출력한다:
+
+```markdown
+## Deep Code Review: {target}
+**Consensus Score**: {score}% | **Reviewers**: Claude/Codex/Gemini
+
+### Critical (3/3 합의)
+- [C1] `{file}:{line}` — {description}
+  - Claude: {detail} | Codex: {detail} | Gemini: {detail}
+  - **Fix**: {suggestion}
+
+### High (2/3 합의)
+- [H1] `{file}:{line}` — {description}
+  - 합의: {agreers} | 반대: {dissenter}: "{reason}"
+
+### Verified Medium
+- ...
+
+### Unverified (1/3만 지적, 참고용)
+- [U1] `{file}:{line}` — {description} (by {single_cli})
+
+### 통계
+| CLI | 발견 수 | 합의 기여율 |
+|-----|---------|------------|
+| Claude | {n} | {%} |
+| Codex | {n} | {%} |
+| Gemini | {n} | {%} |
+```
+
+## ERROR RECOVERY
+
+| 오류 | 조치 |
+|------|------|
+| headless dispatch 타임아웃 | `--timeout` 값을 900으로 올려 재시도 |
+| Agent 결과 미수신 | Step 2를 Agent만 단독 재실행 |
+| consensus 0% | 대상 범위가 너무 넓음 — 파일 단위로 분할 후 재실행 |
+| tfx multi 명령 실패 | `tfx status`로 teammate 연결 상태 확인 |
+
+## 토큰 예산
+
+| 단계 | 토큰 |
+|------|------|
+| Step 1 (수집) | ~1K |
+| Step 2 (3x 독립 리뷰) | ~15K |
+| Step 3 (Consensus) | ~3K |
+| Step 4 (보고) | ~3K |
+| **총합** | **~22K** |

package/skills/tfx-doctor/SKILL.md

@@ -27,6 +27,8 @@ options:
     description: "읽기 전용 전체 검사 — 아무것도 수정하지 않음"
   - label: "수정 (Fix)"
     description: "파일 동기화 + 캐시 정리 후 진단 실행"
+  - label: "보안 감사 (Audit)"
+    description: "settings.json, CLAUDE.md, MCP, 훅 설정의 보안/성능 정적 분석"
   - label: "캐시 관리 (Cache)"
     description: "캐시 파일별 상태 조회, 선택적 삭제"
   - label: "전체 초기화 (Reset)"
@@ -66,6 +68,25 @@ options:
     description: "수정 없이 결과만 확인"
 ```
 
+#### 보안 감사 모드
+
+```bash
+Bash("triflux doctor --audit")
+```
+
+4개 카테고리를 정적 분석:
+
+| 카테고리 | 검사 항목 |
+|----------|-----------|
+| settings | 권한 모드, env 시크릿 패턴, 훅 timeout |
+| claude-md | 시크릿 노출, CLAUDE.md 크기 (>3000토큰 경고) |
+| mcp | 서버 수 (>10), stdio 수, 위험 명령 패턴 |
+| hooks | blocking 훅 수, 외부 훅, 위험 명령 패턴 |
+
+심각도: critical (즉시 수정), warn (검토 필요), info (참고)
+
+JSON 출력: `Bash("triflux doctor --audit --json")`
+
 #### 수정 모드
 
 ```bash

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

@@ -0,0 +1,172 @@
+---
+name: tfx-doctor
+description: >
+  triflux 진단 및 수리 도구. AskUserQuestion 기반 인터랙티브 선택지로
+  CLI 미발견, HUD 미표시, 캐시 오류, 스킬 미설치 등을 진단하고 자동 수정합니다.
+  Use when: not working, broken, error, 안 돼, 이상해, 에러, 캐시, reset, doctor
+triggers:
+  - tfx-doctor
+argument-hint: "[--fix|--reset]"
+---
+
+# {{SKILL_NAME}} — triflux 진단 및 수리
+
+> 뭔가 안 될 때, HUD가 이상할 때, CLI가 안 보일 때 실행하세요.
+
+## 워크플로우
+
+### Step 1: 모드 선택 (AskUserQuestion)
+
+인자 없이 호출된 경우 모드를 선택한다:
+
+```
+question: "어떤 진단 모드를 실행하시겠습니까?"
+header: "모드"
+options:
+  - label: "진단 (Diagnose)"
+    description: "읽기 전용 전체 검사 — 아무것도 수정하지 않음"
+  - label: "수정 (Fix)"
+    description: "파일 동기화 + 캐시 정리 후 진단 실행"
+  - label: "캐시 관리 (Cache)"
+    description: "캐시 파일별 상태 조회, 선택적 삭제"
+  - label: "전체 초기화 (Reset)"
+    description: "모든 캐시 삭제 + 재생성 (위험)"
+```
+
+`--fix`, `--reset` 인자가 있으면 바로 해당 모드로 실행.
+
+### Step 2: 모드별 실행
+
+#### 진단 모드
+
+```bash
+Bash("triflux doctor --json")
+```
+
+JSON 결과를 파싱하여 마크다운 테이블로 표시:
+
+```
+| 항목 | 상태 | 비고 |
+|------|------|------|
+| tfx-route.sh | ✅ | v2.0 |
+| HUD | ✅ | 설치됨 |
+| Codex CLI | ✅ | found |
+| Gemini CLI | ⚠ | 미설치 (선택) |
+| ...  | ... | ... |
+```
+
+이슈가 발견되면 AskUserQuestion:
+```
+question: "N개 이슈가 발견되었습니다. 자동 수정을 시도하시겠습니까?"
+header: "수정"
+options:
+  - label: "자동 수정 실행 (Recommended)"
+    description: "triflux doctor --fix 실행"
+  - label: "건너뛰기"
+    description: "수정 없이 결과만 확인"
+```
+
+#### 수정 모드
+
+```bash
+Bash("triflux doctor --fix")
+```
+
+결과를 보고한다.
+
+#### 캐시 관리
+
+`~/.claude/cache/` 디렉토리의 캐시 파일들을 Read/Glob으로 조회:
+
+| 캐시 파일 | 설명 |
+|-----------|------|
+| claude-usage-cache.json | Claude 사용량 |
+| codex-rate-limits-cache.json | Codex 레이트 리밋 |
+| gemini-quota-cache.json | Gemini 쿼터 |
+| sv-accumulator.json | 절약량 누적 |
+| mcp-inventory.json | MCP 서버 인벤토리 |
+| cli-issues.jsonl | CLI 이슈 로그 |
+| triflux-update-check.json | 업데이트 체크 |
+| .omc/cache/codex-skills.json | Codex 스킬 인덱스 |
+| .omc/state/tier-environment.json | Tier 환경 스냅샷 |
+| .omc/cache/project-meta.json | 프로젝트 메타 |
+| .omc/state/search-engines.json | 검색 엔진 상태 |
+
+존재하는 캐시 파일 목록과 크기를 테이블로 표시 후 AskUserQuestion:
+
+```
+question: "어떻게 삭제하시겠습니까?"
+header: "삭제"
+options:
+  - label: "전체 삭제"
+    description: "모든 캐시 파일 삭제"
+  - label: "에러 캐시만 삭제"
+    description: "파싱 에러가 있는 파일만 삭제"
+  - label: "선택 삭제"
+    description: "파일 하나씩 선택하여 삭제"
+  - label: "취소"
+    description: "삭제하지 않음"
+```
+
+"선택 삭제" 시 각 파일에 대해 AskUserQuestion으로 삭제 여부 확인.
+
+#### 전체 초기화
+
+위험 확인:
+```
+question: "전체 캐시를 초기화하시겠습니까? 다음 세션에서 재생성됩니다."
+header: "확인"
+options:
+  - label: "초기화 실행"
+    description: "모든 캐시 삭제 + MCP/사용량 캐시 재생성"
+  - label: "취소"
+    description: "아무것도 하지 않음"
+```
+
+확인 시:
+```bash
+Bash("triflux doctor --reset")
+```
+
+### Step 3: 후속 조치
+
+실행 완료 후 AskUserQuestion:
+```
+question: "다른 작업을 하시겠습니까?"
+header: "계속"
+options:
+  - label: "다른 모드 실행"
+    description: "진단/수정/캐시/초기화 메뉴로 돌아감"
+  - label: "종료"
+    description: "doctor 종료"
+```
+
+## 진단 항목
+
+- tfx-route.sh 설치 상태
+- HUD 설치 및 설정 상태
+- Codex/Gemini/Claude CLI 경로 (크로스 셸)
+- **psmux 버전 / capability preflight**
+  - `new-session`, `attach-session`, `kill-session`, `capture-pane`, `detach-client`
+  - 권장 버전 이상인지 여부
+- Codex Profiles (필수 프로파일 존재 여부)
+- 스킬 설치 상태
+- 플러그인 등록 상태
+- 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` 일치 여부
+
+## 에러 처리
+
+| 상황 | 처리 |
+|------|------|
+| 캐시 디렉토리 없음 | 정상 — 삭제할 파일 없음 보고 |
+| 파일 삭제 권한 없음 | 수동 삭제 안내 |
+| --fix 후에도 이슈 남음 | Codex/Gemini 설치는 수동 필요 안내 |
+
+## standalone TUI
+
+터미널에서 직접 실행도 가능: `node tui/doctor.mjs` (arrow key 방식)

package/skills/tfx-doctor/skill.json

@@ -1,8 +1,6 @@
 {
   "name": "tfx-doctor",
   "description": "triflux 진단 및 수리 도구. AskUserQuestion 기반 인터랙티브 선택지로 CLI 미발견, HUD 미표시, 캐시 오류, 스킬 미설치 등을 진단하고 자동 수정합니다. Use when: not working, broken, error, 안 돼, 이상해, 에러, 캐시, reset, doctor",
-  "triggers": [
-    "tfx-doctor"
-  ],
+  "triggers": ["tfx-doctor"],
   "argument_hint": "[--fix|--reset]"
 }

package/skills/tfx-find/SKILL.md

@@ -28,6 +28,7 @@ argument-hint: "<검색 패턴 또는 질문>"
 > - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.
 
 
+
 > OMC explore agent 오마주. Haiku의 속도 + Glob/Grep/Read의 정밀도.
 > "찾는 건 빠르게, 읽는 건 정확하게."