triflux 8.12.2 → 9.0.0

package/skills/tfx-consensus/SKILL.md

@@ -7,6 +7,7 @@ argument-hint: "(내부 전용 — Deep 스킬이 자동 호출)"
 
 # tfx-consensus — Tri-CLI Consensus Engine
 
+> **인프라**: 다른 스킬이 내부적으로 사용. 직접 호출할 필요 없음.
 > 모든 Deep 스킬의 공통 기반. 3개 CLI의 독립 결과를 교차검증하여 합의 도출.
 
 ## HARD RULES

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

@@ -10,6 +10,7 @@ argument-hint: "<분석 대상 — 파일, 디렉토리, 또는 주제>"
 
 # tfx-deep-analysis — Tri-CLI Deep Analysis
 
+> **Light 버전**: tfx-analysis. 기본값. 깊이 수정자 없으면 Light 선택.
 > Claude(아키텍처) + Codex(구현/보안) + Gemini(UX/문서화) → Tri-Debate → 합의.
 > 3자 전문 관점의 편향 없는 분석.
 

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

@@ -13,6 +13,7 @@ argument-hint: "<구현할 기능 설명>"
 
 # tfx-deep-plan — Tri-Model Consensus Planning
 
+> **Light 버전**: tfx-plan. 기본값. 깊이 수정자 없으면 Light 선택.
 3개 모델(Opus 4.6 · GPT 5.4 · Gemini)이 독립 설계 후 교차검증하여 합의된 계획을 도출한다.
 
 ---

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

@@ -11,6 +11,7 @@ argument-hint: "[테스트 대상 경로 또는 기능 설명]"
 
 # tfx-deep-qa — Tri-CLI Deep Verification
 
+> **Light 버전**: tfx-qa. 기본값. 깊이 수정자 없으면 Light 선택.
 > 3-CLI 독립 검증 → 교차검증 → 2+ 합의 항목만 보고. false-positive 87% 감소.
 
 ## 핵심 원리

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

@@ -14,6 +14,7 @@ argument-hint: "[--depth quick|standard|deep] <리서치 주제>"
 
 # tfx-deep-research — Multi-Source Deep Research with Tri-CLI Consensus
 
+> **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,7 @@ argument-hint: "[파일 경로 또는 변경 설명]"
 
 # tfx-deep-review — Tri-CLI Deep Code Review
 
+> **Light 버전**: tfx-review. 기본값. 깊이 수정자 없으면 Light 선택.
 > 3-CLI 독립 리뷰 → 교차검증 → 2+ 합의 항목만 보고. Diffray + Calimero 영감.
 
 ## 핵심 원리

package/skills/tfx-doctor/SKILL.md

@@ -87,6 +87,10 @@ Bash("triflux doctor --fix")
 | 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:
 
@@ -146,6 +150,7 @@ options:
 - 스킬 설치 상태
 - 플러그인 등록 상태
 - MCP 인벤토리 캐시
+- Phase 1 웜업 캐시 무결성 (`node scripts/cache-doctor.mjs`)
 - 잔존 팀(orphan teams) 감지
 
 ## 에러 처리

package/skills/tfx-gemini/SKILL.md

@@ -8,6 +8,7 @@ argument-hint: "\"작업 설명\" | N:gemini \"작업 설명\""
 
 # tfx-gemini — Gemini-Only 오케스트레이터
 
+> **래퍼**: tfx-auto의 Gemini 전용 바로가기. TFX_CLI_MODE=gemini.
 > Gemini CLI만 사용하여 모든 외부 CLI 작업을 라우팅합니다.
 > Codex CLI가 없는 환경에서 사용합니다.
 

package/skills/tfx-hub/SKILL.md

@@ -11,6 +11,7 @@ argument-hint: "<start|stop|status|자유형 작업 설명>"
 
 # tfx-hub — MCP 메시지 버스 관리 + 개방형 작업
 
+> **인프라**: 다른 스킬이 내부적으로 사용. 직접 호출할 필요 없음.
 > CLI 에이전트(Codex/Gemini/Claude) 간 실시간 메시지 허브를 관리합니다.
 > **커맨드 매칭 + fallthrough**: start/stop/status에 매칭되면 즉시 실행,
 > 매칭 안 되면 **hub 도메인 컨텍스트를 활용한 범용 작업**으로 처리합니다.

package/skills/tfx-multi/SKILL.md

@@ -8,6 +8,7 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
 
 # tfx-multi v3 — 파이프라인 기반 멀티-CLI 팀 오케스트레이터
 
+> **인프라**: 다른 스킬이 내부적으로 사용. 직접 호출할 필요 없음.
 > Claude Code Native Teams의 Shift+Down 네비게이션을 복원한다.
 > Codex/Gemini 워커마다 최소 프롬프트(~100 토큰)의 슬림 Agent 래퍼를 spawn하여 네비게이션에 등록하고,
 > 실제 작업은 `tfx-route.sh`가 수행한다. task 상태는 `team_task_list`를 truth source로 검증한다.

package/skills/tfx-plan/SKILL.md

@@ -11,6 +11,7 @@ argument-hint: "<구현할 기능 설명>"
 
 # tfx-plan — Light Implementation Plan
 
+> **Deep 버전**: tfx-deep-plan. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
 > Claude Opus 단독 빠른 계획. 복잡한 합의 없이 즉시 태스크 분해.
 
 ## 워크플로우

package/skills/tfx-qa/SKILL.md

@@ -11,6 +11,7 @@ argument-hint: "[테스트 명령 또는 파일 경로]"
 
 # tfx-qa — Light Test-Fix Cycle
 
+> **Deep 버전**: tfx-deep-qa. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
 > 테스트 실행 → 실패 분석 → 자동 수정 → 재실행. 최대 3회. OMC ultraqa 영감.
 
 ## 용도

package/skills/tfx-ralph/SKILL.md

@@ -2,16 +2,13 @@
 name: tfx-ralph
 description: "작업이 완전히 끝날 때까지 멈추지 않고 반복 실행해야 할 때 사용한다. 'ralph', '끝까지 해', '멈추지 마', 'don't stop', '완료될 때까지', '다 될 때까지 계속' 같은 요청에 반드시 사용. 여러 기준을 모두 충족해야 하는 복잡한 구현 작업에 적극 활용."
 triggers:
-  - ralph
-  - don't stop
-  - 끝까지
-  - until done
-  - 멈추지 마
+  - tfx-ralph
 argument-hint: "<완료할 작업 설명>"
 ---
 
 # tfx-ralph — Alias for tfx-persist
 
+> **래퍼**: tfx-persist의 alias. 동일 기능.
 > `tfx-ralph`는 `tfx-persist`의 alias이다. 동일한 Tri-Verified Persistence Loop을 실행한다.
 > The boulder never stops — but it stops being wrong.
 

package/skills/tfx-research/SKILL.md

@@ -13,6 +13,7 @@ argument-hint: "<검색 주제>"
 
 # tfx-research — Light Web Research
 
+> **Deep 버전**: tfx-deep-research. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
 > 빠른 단일 소스 검색 + 요약. 토큰 최소화, 즉시 결과.
 
 ## 용도

package/skills/tfx-review/SKILL.md

@@ -11,6 +11,8 @@ argument-hint: "[파일 경로 또는 변경 설명]"
 
 # tfx-review — Light Code Review
 
+> **Deep 버전**: tfx-deep-review. "제대로/꼼꼼히" 수정자로 자동 에스컬레이션.
+> **HARD RULE**: 리뷰 결과를 생성할 때 Claude가 직접 git log/diff를 실행하지 마라. Codex code-reviewer에게 위임하라.
 > Codex 단일 리뷰로 빠른 피드백. 토큰 최소화.
 
 ## 워크플로우

package/skills/tfx-setup/SKILL.md

@@ -2,7 +2,7 @@
 name: tfx-setup
 description: >
   triflux 초기 설정 및 진단. AskUserQuestion 기반 인터랙티브 위저드로
-  파일 동기화, HUD 설정, Codex 프로파일, CLI 진단, MCP 확인을 수행합니다.
+  파일 동기화, HUD 설정, Codex 프로파일, CLI 진단, MCP 확인, 검색 MCP 설정을 수행합니다.
   Use when: setup, 설정, 설치, install, 초기화, 처음, 시작, wizard
 triggers:
   - tfx-setup
@@ -22,7 +22,7 @@ question: "어떤 설정 모드를 실행하시겠습니까?"
 header: "모드"
 options:
   - label: "전체 설정 (Recommended)"
-    description: "5단계 순서 실행: 동기화 → HUD → 프로파일 → CLI → MCP"
+    description: "6단계 순서 실행: 동기화 → HUD → 프로파일 → CLI → MCP → 검색 MCP"
   - label: "단계별 선택"
     description: "필요한 단계만 골라서 실행"
   - label: "현재 상태 확인"
@@ -31,7 +31,7 @@ options:
 
 `doctor` 인자가 있으면 바로 `triflux doctor` 실행.
 
-### Step 2: 전체 설정 (5단계)
+### Step 2: 전체 설정 (6단계)
 
 각 단계를 순서대로 실행하며 결과를 보고한다.
 
@@ -119,10 +119,181 @@ Bash("triflux setup")
 `triflux doctor --json`을 Bash로 실행하여 CLI 존재 여부 확인.
 결과를 테이블로 표시.
 
-#### 단계 5: MCP 서버 확인
+#### 단계 5: MCP 서버 설정 위저드
 
-`~/.claude/cache/mcp-inventory.json` 존재 여부 + 서버 수 확인.
-없으면 재생성 여부를 AskUserQuestion으로 확인.
+> MCP 서버를 선택적으로 활성화한다. API 키 없는 서버는 건너뛸 수 있다.
+> 선택 결과는 `~/.claude/cache/mcp-enabled.json` 매니페스트에 저장된다.
+> 이후 gateway-start, gateway-config, mcp-filter 모두 이 매니페스트를 참조한다.
+
+##### 5-1: 기존 매니페스트 확인
+
+Read 도구로 `~/.claude/cache/mcp-enabled.json` 읽기 시도.
+- 존재하면 → 현재 설정 표시 후 AskUserQuestion:
+  ```
+  question: "MCP 서버 설정을 변경하시겠습니까?"
+  header: "MCP"
+  options:
+    - label: "현재 설정 유지"
+      description: "활성: {현재 enabled 목록}"
+    - label: "다시 설정"
+      description: "서버를 다시 선택"
+  ```
+  "현재 설정 유지" 선택 시 → Step 5 완료, 다음 단계로.
+
+##### 5-2: Core 서버 안내
+
+Core 서버(context7, serena)는 API 키 불필요, 자동 활성화됨을 표시:
+```
+✅ context7 — 라이브러리 문서 조회 (API 키 불필요)
+✅ serena   — 시맨틱 코드 분석 (API 키 불필요)
+```
+
+##### 5-3: 검색 MCP 선택
+
+AskUserQuestion(multiSelect):
+```
+question: "어떤 검색 MCP를 활성화하시겠습니까? (API 키 필요)"
+header: "검색 MCP"
+multiSelect: true
+options:
+  - label: "brave-search"
+    description: "Brave 웹/뉴스 검색 (BRAVE_API_KEY 필요)"
+  - label: "exa"
+    description: "코드/리포/학술 검색 (EXA_API_KEY 필요)"
+  - label: "tavily"
+    description: "리서치/팩트체크 검색 (TAVILY_API_KEY 필요)"
+  - label: "없음"
+    description: "검색 MCP 사용 안 함 (context7만 사용)"
+```
+
+선택된 서버마다 환경변수 존재 여부를 `process.env`로 확인:
+- 환경변수 있음 → ✅ 표시
+- 환경변수 없음 → ⚠️ 경고 + 안내:
+  ```
+  ⚠️ exa: EXA_API_KEY가 설정되지 않았습니다.
+     → 환경변수를 설정한 뒤 세션을 재시작하면 활성화됩니다.
+     → 매니페스트에는 활성으로 기록합니다 (키 추가 후 바로 사용 가능).
+  ```
+
+##### 5-4: 통합 MCP 선택
+
+AskUserQuestion(multiSelect):
+```
+question: "어떤 통합 MCP를 활성화하시겠습니까?"
+header: "통합 MCP"
+multiSelect: true
+options:
+  - label: "jira"
+    description: "Jira 이슈/스프린트 관리 (JIRA_API_TOKEN + EMAIL + URL 필요)"
+  - label: "notion"
+    description: "Notion 페이지 관리 (NOTION_TOKEN 필요)"
+  - label: "없음"
+    description: "통합 MCP 사용 안 함"
+```
+
+notion 선택 시 notion-guest도 함께 활성화.
+환경변수 체크는 5-3과 동일 패턴.
+
+##### 5-5: 매니페스트 저장
+
+선택된 서버 목록을 수집하여 Bash 도구로 저장:
+```bash
+node -e "
+  import { writeManifest } from './scripts/lib/mcp-manifest.mjs';
+  writeManifest(['brave-search', 'exa']);  // 예시: 선택된 서버
+  console.log('Manifest saved');
+"
+```
+
+또는 Write 도구로 직접 `~/.claude/cache/mcp-enabled.json` 작성:
+```json
+{
+  "version": 1,
+  "updatedAt": "2026-03-31T...",
+  "enabled": ["context7", "serena", "brave-search", "exa"]
+}
+```
+
+##### 5-6: 결과 표시
+
+```
+## MCP 서버 설정 완료
+
+| 서버 | 상태 | 비고 |
+|------|------|------|
+| context7 | ✅ 활성 | Core (항상 활성) |
+| serena | ✅ 활성 | Core (항상 활성) |
+| brave-search | ✅ 활성 | BRAVE_API_KEY ✅ |
+| exa | ⚠️ 활성 | EXA_API_KEY 미설정 — 키 추가 후 사용 가능 |
+| tavily | ⏭️ 건너뜀 | 사용자 선택 |
+| jira | ⏭️ 건너뜀 | 사용자 선택 |
+| notion | ⏭️ 건너뜀 | 사용자 선택 |
+
+💡 나중에 변경: `/tfx-setup` → 단계별 선택 → MCP 설정
+```
+
+#### 단계 6: 검색 MCP 설정
+
+프로젝트 `.mcp.json`을 Read 도구로 읽어 기존 검색 MCP 서버 확인.
+환경변수 파일(`~/projects/.env`, 프로젝트 `.env`)에서 API 키 자동 감지.
+
+감지된 키 상태를 옵션 description에 반영하여 표시 → AskUserQuestion:
+```
+question: "어떤 검색 MCP 서버를 설정하시겠습니까?"
+header: "검색 MCP"
+multiSelect: true
+options:
+  - label: "Exa Web Search"
+    description: "시맨틱 검색 + 크롤링 (EXA_API_KEY: ✅감지됨/❌미감지)"
+  - label: "Brave Search"
+    description: "웹/뉴스/이미지 검색 (BRAVE_API_KEY: ✅감지됨/❌미감지)"
+  - label: "Tavily Search"
+    description: "AI 최적화 검색 (TAVILY_API_KEY: ✅감지됨/❌미감지)"
+  - label: "건너뛰기"
+    description: "검색 MCP 설정 안 함"
+```
+
+"건너뛰기" 선택 시 이 단계 종료.
+
+각 선택된 서버에 대해:
+1. API 키가 감지됨 → "감지된 키를 사용합니다" 확인 메시지
+2. API 키 미감지 → AskUserQuestion으로 키 입력 요청:
+   ```
+   question: "{서버명} API 키를 입력하세요 (발급: {URL})"
+   header: "API Key"
+   ```
+   빈 입력이면 해당 서버 건너뛰기.
+3. `.mcp.json`에 서버 추가 (Edit 도구). 파일 없으면 Write 도구로 생성.
+
+MCP 서버 설정 레지스트리:
+```json
+{
+  "exa": {
+    "command": "npx",
+    "args": ["-y", "exa-mcp-server"],
+    "env": { "EXA_API_KEY": "{key}" },
+    "keyUrl": "https://exa.ai/dashboard"
+  },
+  "brave-search": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+    "env": { "BRAVE_API_KEY": "{key}" },
+    "keyUrl": "https://brave.com/search/api/"
+  },
+  "tavily": {
+    "command": "npx",
+    "args": ["-y", "tavily-mcp@latest"],
+    "env": { "TAVILY_API_KEY": "{key}" },
+    "keyUrl": "https://app.tavily.com/home"
+  }
+}
+```
+
+키 감지 경로 (순서대로 탐색, 첫 번째 매치 사용):
+1. 셸 환경변수 (`$EXA_API_KEY` 등)
+2. `~/projects/.env`
+3. 프로젝트 루트 `.env`
+4. `~/.claude/settings.json` → `env` 섹션
 
 ### Step 3: 단계별 선택
 
@@ -142,6 +313,8 @@ options:
     description: "triflux-profiles.json 생성/확인"
   - label: "CLI + MCP 진단"
     description: "CLI 존재 + MCP 인벤토리 확인"
+  - label: "검색 MCP"
+    description: "Exa/Brave/Tavily 검색 서버 설정"
 ```
 
 선택된 단계만 순서대로 실행.
@@ -159,11 +332,13 @@ options:
 | Codex CLI | ✅ |
 | Gemini CLI | ⚠ 미설치 (선택) |
 | MCP 인벤토리 | ✅ N개 서버 |
+| 검색 MCP | ✅ Exa, Tavily / ⏭ Brave (키 없음) |
 
 ### 다음 단계
 - Codex 미설치 시: `npm install -g @openai/codex`
 - Gemini 미설치 시: `npm install -g @google/gemini-cli`
-- 세션 재시작하면 HUD가 표시됩니다
+- 검색 MCP 추가/변경: `/tfx-setup` → 단계별 선택 → 검색 MCP
+- 세션 재시작하면 HUD + 검색 MCP가 활성화됩니다
 ```
 
 ## 에러 처리