triflux 8.3.0 → 8.4.0

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

@@ -0,0 +1,113 @@
+---
+name: tfx-deep-plan
+description: "중요한 기능의 구현 계획을 3자 합의로 수립할 때 사용한다. 'deep plan', '합의 계획', 'ralplan', '철저한 계획', '제대로 설계하고 시작하자' 같은 요청에 사용. 마이크로서비스 도입, 대규모 리팩터링 등 리스크가 큰 작업의 사전 계획에 적극 활용."
+triggers:
+  - deep plan
+  - 합의 계획
+  - consensus plan
+  - deep-plan
+  - 철저한 계획
+  - ralplan
+argument-hint: "<구현할 기능 설명>"
+---
+
+# tfx-deep-plan — Consensus Planning via Tri-CLI Debate
+
+> OMC ralplan 오마주. Planner + Architect + Critic 3자 반복 토론으로 합의된 계획.
+
+## 워크플로우
+
+### Round 1: 독립 계획 (Anti-Herding)
+
+```
+Claude Opus (Planner):
+  "소프트웨어 아키텍트로서 {feature}의 구현 계획을 수립하라.
+   태스크 분해, 순서, 의존성, 검증 방법 포함.
+   JSON: { tasks, dependencies, risks, complexity, reasoning }"
+
+Codex (Architect):
+  "시니어 엔지니어로서 {feature}의 기술적 설계를 작성하라.
+   파일 구조, API 인터페이스, 데이터 모델, 에러 처리 포함.
+   JSON: { design, file_changes, interfaces, data_models, risks }"
+
+Gemini (Critic):
+  "QA/보안 전문가로서 {feature} 구현 시 예상되는 문제를 분석하라.
+   엣지 케이스, 보안 위협, 성능 병목, 테스트 전략 포함.
+   JSON: { edge_cases, security_risks, performance_concerns, test_strategy }"
+```
+
+### Round 2: 교차 검토
+
+각 CLI에게 다른 두 CLI의 결과를 제시:
+
+```
+Claude에게:
+  "Architect 설계: {codex_result}
+   Critic 우려: {gemini_result}
+   이를 반영하여 계획을 수정하라. 수용/반박 근거 포함."
+
+Codex에게:
+  "Planner 계획: {claude_result}
+   Critic 우려: {gemini_result}
+   설계를 수정하라."
+
+Gemini에게:
+  "Planner 계획: {claude_result}
+   Architect 설계: {codex_result}
+   우려 사항이 해소되었는지 판단하라. 미해소 항목 지적."
+```
+
+### Round 3: 합의 도출 (필요 시)
+
+```
+Round 2 후 Consensus Score 산출:
+  >= 80 → 합의 확정
+  60-79 → Round 3 진행 (미합의 항목만)
+  < 60 → 사용자에게 주요 불일치 제시 + 방향 결정 요청
+```
+
+### Final: 합의된 계획 출력
+
+```markdown
+## 합의된 구현 계획: {feature}
+**Consensus Score**: {score}% | **Rounds**: {count}
+
+### 아키텍처 결정
+{3자 합의된 설계 방향}
+
+### 태스크 (합의됨)
+1. [ ] {태스크1} → 검증: {방법} — Planner ✓ Architect ✓ Critic ✓
+2. [ ] {태스크2} → 검증: {방법} — Planner ✓ Architect ✓ Critic: "{조건부}"
+...
+
+### 파일 변경 계획
+| 파일 | 작업 | 이유 |
+|------|------|------|
+| {file} | 생성/수정 | {reason} |
+
+### 리스크 및 완화 (합의됨)
+- {리스크}: {완화} — 3/3 합의
+
+### 테스트 전략 (Critic 주도)
+{Gemini가 제안하고 Claude/Codex가 합의한 테스트 전략}
+
+### 미합의 사항
+- {항목}: {각 CLI 입장 요약}
+```
+
+## 토큰 예산
+
+| 라운드 | 토큰 |
+|--------|------|
+| Round 1 (3x 독립) | ~12K |
+| Round 2 (3x 교차) | ~9K |
+| Round 3 (필요시) | ~6K |
+| 합의 종합 | ~3K |
+| **총합** | **~20-30K** |
+
+## 사용 예
+
+```
+/tfx-deep-plan "마이크로서비스 간 이벤트 기반 통신 도입"
+/tfx-deep-plan "기존 REST API를 GraphQL로 점진적 마이그레이션"
+```

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

@@ -0,0 +1,158 @@
+---
+name: tfx-deep-qa
+description: "보안, 성능, 접근성까지 포함한 철저한 검증이 필요할 때 사용한다. 'deep qa', '심층 검증', '철저히 테스트', '보안까지 확인', '전방위 검증' 같은 요청에 사용. 프로덕션 배포 전 다각도 품질 검증에 적극 활용."
+triggers:
+  - deep qa
+  - 심층 검증
+  - thorough test
+  - deep-qa
+argument-hint: "[테스트 대상 경로 또는 기능 설명]"
+---
+
+# tfx-deep-qa — Tri-CLI Deep Verification
+
+> 3-CLI 독립 검증 → 교차검증 → 2+ 합의 항목만 보고. false-positive 87% 감소.
+
+## 핵심 원리
+
+**Anti-Herding**: 3개 CLI가 서로의 결과를 보지 않고 독립 검증.
+**Consensus Only**: 2개 이상 CLI가 동일 이슈를 지적한 항목만 최종 보고.
+
+## 용도
+
+- 릴리스 전 전면 검증
+- 보안/성능/접근성을 동시에 다각도 점검
+- 단일 CLI 검증으로는 놓치는 교차 영역 결함 탐지
+- false-positive 최소화가 필요한 QA 게이트
+
+## 워크플로우
+
+### Step 1: 검증 대상 수집
+
+```
+대상 결정:
+  1. 사용자 지정 파일/경로 → 해당 범위
+  2. git diff (staged + unstaged) → 변경된 파일
+  3. 지정 없음 → 프로젝트 전체 테스트
+
+수집 항목:
+  - 변경 파일 목록 + diff
+  - 관련 테스트 파일
+  - 영향 받는 모듈/의존성
+```
+
+### Step 2: 3-CLI 독립 검증 (동시, 상호 비공개)
+
+```
+Claude Opus (기능 + 엣지케이스, background):
+  "QA 엔지니어로서 다음 코드의 기능 정확성을 검증하라.
+   - 테스트 실행 후 결과 보고
+   - 누락된 엣지 케이스 식별 (null, 빈 입력, 경계값, 동시성)
+   - 누락된 테스트 케이스 제안
+   JSON: { test_result: {pass, fail, skip},
+           findings: [{id, file, line, category, severity, description, test_scenario}],
+           edge_case_tests: [...],
+           overall_verdict: 'pass'|'fail' }"
+
+Codex (보안 + 성능, background):
+  codex exec review --profile thorough \
+    --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
+  "보안/성능 전문가로서 검증하라.
+   - OWASP Top 10 체크
+   - O(n²) 이상 복잡도 탐지
+   - 메모리 누수 패턴
+   - 입력 검증 누락
+   JSON: { findings: [{id, file, line, category, severity, description, fix}],
+           overall_verdict: 'pass'|'fail' }"
+
+Gemini (UX + 접근성, background):
+  gemini -y -p \
+  "UX/접근성 전문가로서 검증하라.
+   - API 응답 형식 일관성
+   - 에러 메시지 사용자 친화성
+   - WCAG 2.1 AA 준수 (UI 관련 시)
+   - 문서와 실제 동작 일치 여부
+   JSON: { findings: [{id, file, line, category, severity, description, suggestion}],
+           overall_verdict: 'pass'|'fail' }"
+```
+
+### Step 3: Consensus Scoring
+
+```
+모든 findings를 수집하여 유사도 비교:
+  - 동일 파일+라인±5 + 유사 카테고리 → 동일 이슈로 간주
+  - 3/3 합의 → CONFIRMED (severity 유지)
+  - 2/3 합의 → LIKELY (severity 유지, 반대 의견 첨부)
+  - 1/3만 지적 → UNVERIFIED (참고용, 별도 섹션)
+
+consensus_score = consensus_items / total_unique_items × 100
+```
+
+### Step 4: 실패 수정 (합의된 항목만)
+
+```
+합의된 Critical/High 항목에 대해:
+  codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
+  "다음 합의된 이슈를 수정하라:
+   {consensus_findings}
+   수정 후 테스트를 재실행하여 확인하라."
+```
+
+### Step 5: 종합 보고서
+
+```markdown
+## Deep QA Report: {target}
+**Consensus Score**: {score}% | **Verifiers**: Claude/Codex/Gemini
+**Verdict**: PASS / CONDITIONAL PASS / FAIL
+
+### Critical (3/3 합의)
+- [C1] `{file}:{line}` — {description}
+  - Claude: {detail} | Codex: {detail} | Gemini: {detail}
+  - **Fix**: {applied_fix}
+
+### High (2/3 합의)
+- [H1] `{file}:{line}` — {description}
+  - 합의: {agreers} | 반대: {dissenter}: "{reason}"
+
+### Verified Medium
+- ...
+
+### 엣지 케이스 테스트 제안
+| 시나리오 | 입력 | 기대 결과 | 제안자 |
+|---------|------|----------|--------|
+| {scenario} | {input} | {expected} | Claude |
+
+### Unverified (1/3만 지적, 참고용)
+- [U1] `{file}:{line}` — {description} (by {single_cli})
+
+### 수정 요약
+- 수정된 파일: {list}
+- 테스트 재실행 결과: {pass}/{total}
+
+### 검증 통계
+| CLI | 영역 | 발견 수 | 합의 기여율 |
+|-----|------|---------|------------|
+| Claude | 기능/엣지케이스 | {n} | {%} |
+| Codex | 보안/성능 | {n} | {%} |
+| Gemini | UX/접근성 | {n} | {%} |
+```
+
+## 토큰 예산
+
+| 단계 | 토큰 |
+|------|------|
+| Step 1 (수집) | ~1K |
+| Step 2 (3x 독립 검증) | ~15K |
+| Step 3 (Consensus) | ~3K |
+| Step 4 (수정) | ~3K |
+| Step 5 (보고) | ~3K |
+| **총합** | **~25K** |
+
+## 사용 예
+
+```
+/tfx-deep-qa
+/tfx-deep-qa "src/auth/ 디렉토리 전체"
+/tfx-deep-qa "최근 커밋 변경사항 심층 검증"
+/tfx-deep-qa "결제 모듈 배포 전 최종 검증"
+```

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

@@ -0,0 +1,212 @@
+---
+name: tfx-deep-research
+description: "기술 비교, 아키텍처 조사, 경쟁사 분석 등 깊이 있는 리서치가 필요할 때 사용한다. '심층 조사', '자세히 알아봐', 'deep research', '전면 리서치', '비교 분석 보고서', '종합 리서치' 같은 요청에 반드시 사용. 단순 검색이 아닌 멀티소스 교차검증이 필요한 리서치에 적극 활용."
+triggers:
+  - deep research
+  - 딥 리서치
+  - 심층 리서치
+  - deep-research
+  - thorough research
+  - 깊이 조사
+  - 전면 리서치
+argument-hint: "[--depth quick|standard|deep] <리서치 주제>"
+---
+
+# tfx-deep-research — Multi-Source Deep Research with Tri-CLI Consensus
+
+> 쿼리 분해 → 3-CLI 독립 병렬 검색 → 교차검증 → 합의 기반 종합 보고서.
+> STORM(Stanford) perspective-guided + GPT-Researcher recursive tree + Tavily deep research pipeline 영감.
+
+## 용도
+
+- 기술 선택 전 심층 조사
+- 경쟁사/대안 분석
+- 새 도메인 학습을 위한 종합 리서치
+- 아키텍처 결정 근거 수집
+- 학술/산업 동향 파악
+
+## 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
+
+## 워크플로우
+
+### Pre-Phase: Depth 선택 (--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`를 적용한다.
+
+### Phase 0: 주제 분석 및 쿼리 분해
+
+Claude Opus가 주제를 분석하고 서브쿼리로 분해한다:
+
+```
+입력: "2026년 실시간 데이터 파이프라인 아키텍처 비교"
+
+분해 결과:
+{
+  "main_topic": "실시간 데이터 파이프라인 아키텍처 2026",
+  "sub_queries": [
+    "Apache Kafka vs Apache Pulsar vs Redpanda 2026 comparison benchmark",
+    "real-time data pipeline architecture patterns 2026 stream processing",
+    "Apache Flink vs Spark Structured Streaming vs RisingWave 2026",
+    "real-time data pipeline cloud managed services AWS Kinesis GCP Dataflow Azure Event Hub",
+    "real-time CDC change data capture Debezium alternatives 2026"
+  ],
+  "perspectives": [
+    "성능/처리량 관점",
+    "운영 복잡도/DevOps 관점",
+    "비용/스케일링 관점"
+  ]
+}
+```
+
+### Phase 1: 3-CLI 독립 병렬 검색 (Anti-Herding)
+
+**3개 CLI가 동시에, 서로의 결과를 보지 않고 검색한다.**
+
+각 CLI에 서로 다른 MCP + 관점을 할당:
+
+```
+Claude (Agent, background):
+  - MCP: Exa (neural semantic search)
+  - 관점: 학술/기술 깊이 (논문, 공식 문서, 벤치마크)
+  - 각 서브쿼리를 Exa web_search_exa로 검색
+  - category: "research paper" 우선
+  - highlights 추출, numResults: 5/쿼리
+
+Codex (Bash, background):
+  codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
+  "다음 서브쿼리를 Brave Search로 검색하고 결과를 종합하라:
+   {sub_queries}
+   관점: 실용/구현/산업 사례 중심
+   각 쿼리당 상위 5개 결과의 제목, URL, 핵심 내용을 추출하라."
+
+Gemini (Bash, background):
+  gemini -y -p \
+  "다음 서브쿼리를 Tavily로 검색하라:
+   {sub_queries}
+   관점: 비용/운영/DX(개발자 경험) 중심
+   각 결과를 구조화하여 정리하라."
+```
+
+### Phase 2: 결과 수집 및 교차검증
+
+3개 CLI 결과를 수집한 후 tfx-consensus 프로토콜 적용:
+
+```
+교차검증 항목:
+  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
+```
+
+### Phase 3: 합의 종합 보고서 생성
+
+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}
+...
+```
+
+### Phase 4: Recursive Depth (deep 모드 전용)
+
+deep 모드에서는 Phase 2에서 발견된 중요 하위 주제에 대해 재귀적으로 Phase 1-3을 반복:
+
+```
+if depth == "deep" AND Phase 2에서 중요 하위 주제 발견:
+  for each important_subtopic (max 3):
+    recurse Phase 1-3 with sub_queries = [subtopic-specific queries]
+  merge recursive results into main report
+```
+
+## 토큰 예산
+
+| 단계 | quick | standard | deep |
+|------|-------|----------|------|
+| Phase 0 (분해) | 1K | 2K | 3K |
+| Phase 1 (3x검색) | 9K | 18K | 30K |
+| Phase 2 (교차검증) | 3K | 5K | 8K |
+| Phase 3 (보고서) | 5K | 10K | 15K |
+| Phase 4 (재귀) | — | — | 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

@@ -0,0 +1,91 @@
+---
+name: tfx-deep-review
+description: "철저한 코드 리뷰가 필요할 때 사용한다. '꼼꼼히 리뷰', 'deep review', '심층 리뷰', '보안까지 리뷰', '다각도 리뷰', '중요한 변경이라 제대로 봐줘' 같은 요청에 사용. 보안/성능/가독성 3관점 독립 검증이 필요한 중요 코드 변경에 적극 활용."
+triggers:
+  - deep review
+  - 심층 리뷰
+  - multi review
+  - deep-review
+  - 철저한 리뷰
+argument-hint: "[파일 경로 또는 변경 설명]"
+---
+
+# tfx-deep-review — Tri-CLI Deep Code Review
+
+> 3-CLI 독립 리뷰 → 교차검증 → 2+ 합의 항목만 보고. Diffray + Calimero 영감.
+
+## 핵심 원리
+
+**Anti-Herding**: Round 1에서 3개 CLI가 서로의 결과를 보지 않고 독립 리뷰.
+**Consensus Only**: 2개 이상 CLI가 동일 이슈를 지적한 항목만 최종 보고 → false-positive 87% 감소.
+
+## 워크플로우
+
+### Step 1: 리뷰 대상 수집
+```
+git diff (staged + unstaged) 또는 지정 파일 수집
+```
+
+### Step 2: 3-CLI 독립 리뷰 (동시, 상호 비공개)
+
+```
+Claude Opus (Agent, background):
+  관점: 로직 결함, 아키텍처 위반, 설계 패턴
+  "코드 리뷰어로서 로직/아키텍처 관점에서 분석하라.
+   JSON: { findings: [{ id, file, line, severity, category, description, suggestion }] }"
+
+Codex (Bash, background):
+  관점: 보안 취약점, 성능 병목, 에러 핸들링
+  codex exec review --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
+  "보안/성능 전문가로서 분석하라. OWASP Top 10, O(n²) 패턴, 누락된 에러 핸들링.
+   JSON: { findings: [...] }"
+
+Gemini (Bash, background):
+  관점: 가독성, 문서화, 네이밍, DX
+  gemini -y -p \
+  "코드 품질 전문가로서 분석하라. 가독성, 네이밍 컨벤션, 주석 필요성, 타입 안전성.
+   JSON: { findings: [...] }"
+```
+
+### 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} | {%} |
+```
+
+## 토큰: ~25K

package/skills/tfx-find/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: tfx-find
+description: "코드베이스에서 파일, 함수, 클래스, 문자열을 빠르게 찾을 때 사용한다. '코드 검색', 'find in code', '어디에 있어?', '이 함수 어디서 쓰여?', '파일 찾아줘', '코드베이스 탐색' 같은 요청에 반드시 사용. 파일 위치, 심볼 사용처, 패턴 검색이 필요한 모든 상황에 적극 활용."
+triggers:
+  - 코드 검색
+  - codebase search
+  - find in code
+  - 코드에서 찾기
+  - 코드베이스 검색
+argument-hint: "<검색 패턴 또는 질문>"
+---
+
+# tfx-find — Fast Codebase Explorer
+
+> OMC explore agent 오마주. Haiku의 속도 + Glob/Grep/Read의 정밀도.
+> "찾는 건 빠르게, 읽는 건 정확하게."
+
+## 용도
+
+- 파일 위치를 모를 때 빠르게 찾기
+- 특정 함수/클래스/변수가 어디서 사용되는지 추적
+- 문자열 패턴으로 코드 검색
+- 프로젝트 구조 빠르게 파악
+- 설정 파일, 진입점, 테스트 파일 탐색
+
+## 워크플로우
+
+### Step 1: 검색 의도 파싱
+
+사용자 입력에서 검색 유형을 판별한다:
+
+```
+검색 유형:
+  file_pattern  — "*.test.ts 파일 찾아" → Glob
+  symbol        — "createBridge 함수 어디?" → Grep (정규식)
+  string        — "TODO 주석 찾아" → Grep (리터럴)
+  structure     — "프로젝트 구조 보여줘" → Glob + tree
+  usage         — "Router 클래스 사용처" → Grep (import/require + 참조)
+  definition    — "handleAuth 정의 찾아" → Grep (function/class/const 패턴)
+```
+
+### Step 2: 검색 실행
+
+검색 유형에 따라 최적 도구 조합을 선택한다:
+
+```
+file_pattern:
+  Glob("**/{pattern}") → 매칭 파일 목록
+
+symbol:
+  Grep(pattern="{symbol}", type="{lang}") → 파일 목록
+  → 상위 5개 파일 Read (정의부 중심, 각 ±10줄)
+
+string:
+  Grep(pattern="{string}", output_mode="content", context=2) → 매칭 라인 + 컨텍스트
+
+structure:
+  Glob("**/*.{ts,js,mjs,py,go}") → 파일 트리 구성
+  → 디렉토리별 파일 수 + 역할 요약
+
+usage:
+  Grep(pattern="import.*{symbol}|require.*{symbol}", output_mode="content") → import 위치
+  Grep(pattern="{symbol}", output_mode="content") → 실제 사용 위치
+  → 중복 제거 후 사용처 목록
+
+definition:
+  Grep(pattern="(function|class|const|let|var|export)\\s+{symbol}", output_mode="content")
+  → 정의 위치 + 파일 경로
+```
+
+### Step 3: 결과 정리
+
+검색 결과를 구조화하여 보고한다:
+
+```markdown
+## 검색 결과: {query}
+
+### 매칭 파일 ({count}개)
+| # | 파일 | 라인 | 컨텍스트 |
+|---|------|------|---------|
+| 1 | src/hub/bridge.mjs | 42 | export function createBridge(...) |
+| 2 | src/hub/router.mjs | 15 | import { createBridge } from './bridge' |
+
+### 코드 스니펫
+{핵심 코드 (필요 시)}
+
+### 관련 파일
+- src/hub/bridge.test.mjs (테스트)
+- src/hub/index.mjs (re-export)
+```
+
+## 검색 최적화 규칙
+
+1. **Glob 먼저, Grep 나중**: 파일 위치를 알면 Glob, 내용 검색은 Grep.
+2. **type 필터 사용**: `type: "js"` 등으로 불필요 파일 제외.
+3. **head_limit 사용**: 결과가 많을 때 상위 N개만 반환.
+4. **병렬 검색**: 독립적인 검색은 동시에 실행.
+5. **점진적 확장**: 좁은 범위 → 넓은 범위. `src/` → `**/*`.
+
+## 동작 규칙
+
+1. 결과가 0개이면 패턴을 완화하여 재검색한다 (대소문자 무시, 부분 매칭).
+2. 결과가 50개 초과이면 가장 관련성 높은 10개만 보여주고 필터 제안.
+3. 파일 내용은 필요한 부분만 Read한다 (전체 파일 읽기 금지).
+4. 검색 패턴에 정규식 특수문자가 있으면 자동 이스케이프.
+
+## 토큰 예산
+
+| 단계 | 토큰 |
+|------|------|
+| 의도 파싱 | ~200 |
+| 검색 실행 | ~1.5K |
+| 결과 정리 | ~1K |
+| **총합** | **~3K** |
+
+## 사용 예
+
+```
+/tfx-find "createBridge 함수 정의와 사용처"
+/코드 검색 "*.test.mjs 파일 목록"
+/find in code "TODO|FIXME|HACK 주석"
+/코드에서 찾기 "환경변수 사용하는 파일"
+```