triflux 8.2.3 → 8.3.1

package/skills/tfx-doctor/SKILL.md

@@ -1,94 +1,161 @@
----
-name: tfx-doctor
-description: >
-  triflux 진단 및 수리 도구. CLI 미발견, HUD 미표시, 캐시 오류,
-  스킬 미설치 등 문제를 진단하고 자동 수정합니다.
-  Use when: not working, broken, error, 안 돼, 이상해, 에러, 캐시, reset
-triggers:
-  - tfx-doctor
-argument-hint: "[--fix|--reset]"
----
-
-# tfx-doctor — triflux 진단 및 수리
-
-> 뭔가 안 될 때, HUD가 이상할 때, CLI가 안 보일 때 실행하세요.
-
-## 사용법
-
-```
-/tfx-doctor            ← 진단만 (읽기 전용)
-/tfx-doctor --fix      ← 진단 + 자동 수정
-/tfx-doctor --reset    ← 캐시 전체 초기화
-```
-
-## 동작
-
-### 기본 모드 (`/tfx-doctor`)
-
-`triflux doctor`를 실행하여 다음을 진단합니다:
-
-- tfx-route.sh 설치 상태
-- HUD 설치 및 설정 상태
-- Codex/Gemini/Claude CLI 경로 (크로스 셸)
-- 스킬 설치 상태
-- 플러그인 등록 상태
-- MCP 인벤토리 캐시
-- CLI 이슈 트래커
-- 잔존 팀(orphan teams) 감지 (`~/.claude/teams/`)
-
-### 수정 모드 (`/tfx-doctor --fix`)
-
-진단 전에 자동 수정을 시도합니다:
-
-1. tfx-route.sh, HUD, 스킬 파일 재동기화
-2. 에러/손상된 캐시 파일 정리
-3. 수정 완료 후 전체 진단 실행 → 결과 보고
-
-### 초기화 모드 (`/tfx-doctor --reset`)
-
-HUD 캐시 및 모든 triflux 관련 캐시를 전체 삭제합니다:
-
-| 삭제 대상 | 설명 |
-|-----------|------|
-| claude-usage-cache.json | Claude 사용량 캐시 |
-| codex-rate-limits-cache.json | Codex 레이트 리밋 캐시 |
-| gemini-quota/session/rpm cache | Gemini 할당량/세션/RPM 캐시 |
-| sv-accumulator.json | 절약량 누적 캐시 |
-| mcp-inventory.json | MCP 서버 인벤토리 |
-| cli-issues.jsonl | CLI 이슈 로그 |
-| triflux-update-check.json | 업데이트 확인 캐시 |
-| .claude-refresh-lock | 리프레시 락 파일 |
-
-초기화 후 다음 세션에서 캐시가 새로 생성됩니다.
-
-## 실행 방법
-
-```bash
-# 진단만
-Bash("triflux doctor")
-
-# 진단 + 자동 수정
-Bash("triflux doctor --fix")
-
-# 캐시 전체 초기화
-Bash("triflux doctor --reset")
-```
-
-결과를 사용자에게 보고합니다.
-
-## 자동 제안 트리거
-
-사용자가 다음과 같이 말하면 이 스킬 실행을 고려하세요:
-
-- "HUD가 안 보여" / "HUD 이상해" / "상태줄이 안 나와"
-- "codex/gemini가 안 돼" / "CLI 안 됨"
-- "캐시 초기화" / "리셋" / "reset"
-- "triflux 안 돼" / "뭔가 안 돼" / "에러"
-
-## 에러 처리
-
-| 상황 | 처리 |
-|------|------|
-| 캐시 디렉토리 없음 | 정상 — 삭제할 파일 없음 보고 |
-| 파일 삭제 권한 없음 | 수동 삭제 안내 |
-| --fix 후에도 이슈 남음 | Codex/Gemini 설치는 수동 필요 안내 |
+---
+name: tfx-doctor
+description: >
+  triflux 진단 및 수리 도구. AskUserQuestion 기반 인터랙티브 선택지로
+  CLI 미발견, HUD 미표시, 캐시 오류, 스킬 미설치 등을 진단하고 자동 수정합니다.
+  Use when: not working, broken, error, 안 돼, 이상해, 에러, 캐시, reset, doctor
+triggers:
+  - tfx-doctor
+argument-hint: "[--fix|--reset]"
+---
+
+# tfx-doctor — 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 | 업데이트 체크 |
+
+존재하는 캐시 파일 목록과 크기를 테이블로 표시 후 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 경로 (크로스 셸)
+- Codex Profiles (필수 프로파일 존재 여부)
+- 스킬 설치 상태
+- 플러그인 등록 상태
+- MCP 인벤토리 캐시
+- 잔존 팀(orphan teams) 감지
+
+## 에러 처리
+
+| 상황 | 처리 |
+|------|------|
+| 캐시 디렉토리 없음 | 정상 — 삭제할 파일 없음 보고 |
+| 파일 삭제 권한 없음 | 수동 삭제 안내 |
+| --fix 후에도 이슈 남음 | Codex/Gemini 설치는 수동 필요 안내 |
+
+## standalone TUI
+
+터미널에서 직접 실행도 가능: `node tui/doctor.mjs` (arrow key 방식)

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 주석"
+/코드에서 찾기 "환경변수 사용하는 파일"
+```

package/skills/tfx-forge/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: tfx-forge
+description: "새 스킬을 만들거나 기존 스킬을 수정할 때 사용한다. 'forge', '스킬 만들기', 'create skill', '새 스킬', '스킬 생성', 'SKILL.md 작성' 같은 요청에 반드시 사용. 반복 작업을 스킬로 자동화하고 싶을 때 적극 활용."
+triggers:
+  - forge
+  - 스킬 만들기
+  - create skill
+  - 스킬 생성
+  - new skill
+argument-hint: "[스킬 이름 또는 설명]"
+---
+
+# tfx-forge — Skill Authoring Meta-Skill
+
+> Superpowers skill authoring 오마주. 스킬을 만드는 스킬.
+> "메타 레벨에서 자동화하라."
+
+## 용도
+
+- 새 tfx 스킬의 SKILL.md를 대화형으로 생성
+- 기존 스킬 형식과 품질 기준을 자동 준수
+- YAML frontmatter + 본문 구조를 일관되게 유지
+- 스킬 작성 시행착오 최소화
+
+## 워크플로우
+
+### Step 1: 요구사항 수집 (대화형)
+
+AskUserQuestion으로 필수 정보를 순서대로 수집한다. 사용자가 초기 입력에 일부 정보를 포함했으면 해당 항목은 건너뛴다.
+
+**먼저 스킬 유형을 선택받는다:**
+
+```
+AskUserQuestion:
+  "스킬 유형을 선택하세요:"
+  1. Light (경량, 단일 CLI, 토큰 절약)
+  2. Deep (딥, 3-CLI 합의, 정확도 우선)
+  3. Core (인프라, 다른 스킬이 내부 호출)
+```
+
+선택된 유형에 따라 이후 수집 항목과 템플릿이 달라진다:
+- **Light**: 단일 CLI 워크플로우, 낮은 토큰 예산
+- **Deep**: 3-CLI 병렬 + tfx-consensus 통합, 높은 토큰 예산
+- **Core**: 외부 호출 인터페이스 정의, 내부 API 문서화 포함
+
+**이후 나머지 정보를 순서대로 수집한다:**
+
+```
+수집 항목 (순서대로):
+
+1. 이름 (name)
+   "스킬 이름은? (예: tfx-myskill)"
+   → 접두사 'tfx-' 자동 부여 (없으면)
+
+2. 한줄 설명 (description)
+   "이 스킬이 무엇을 하는지 한 문장으로?"
+
+3. 트리거 (triggers)
+   "어떤 키워드로 이 스킬을 호출? (쉼표 구분)"
+
+4. 토큰 예산
+   "예상 토큰 예산은? (예: ~10K)"
+
+5. 핵심 워크플로우
+   "주요 단계를 간략히 설명해주세요. (3-5 단계)"
+
+6. 사용 예시
+   "사용 예시 1-3개를 알려주세요."
+```
+
+### Step 2: 기존 스킬 분석
+
+프로젝트 내 기존 SKILL.md를 참조하여 형식과 품질 기준을 확인한다:
+
+```
+Glob("skills/**/SKILL.md")로 기존 스킬 목록 수집
+→ 유사한 타입(Deep/Light)의 스킬 1-2개를 Read하여 형식 참조
+→ YAML frontmatter 구조, 본문 섹션 패턴, 토큰 예산 표 형식 추출
+```
+
+### Step 3: SKILL.md 생성
+
+수집된 정보로 SKILL.md를 자동 생성한다:
+
+```yaml
+# YAML Frontmatter 템플릿
+---
+name: {name}
+description: {description}
+triggers:
+  - {trigger_1}
+  - {trigger_2}
+  - ...
+argument-hint: "{hint}"
+---
+```
+
+```markdown
+# 본문 템플릿
+
+# {name} — {short_title}
+
+> {한줄 설명 또는 오마주}
+
+## 용도
+
+- {use_case_1}
+- {use_case_2}
+- {use_case_3}
+
+## 워크플로우
+
+### Step 1: {step_title}
+{step_description}
+
+### Step 2: {step_title}
+{step_description}
+
+...
+
+## 토큰 예산
+
+| 단계 | 토큰 |
+|------|------|
+| {step} | ~{N}K |
+| **총합** | **~{total}K** |
+
+## 사용 예
+
+```
+/{name} "{example_1}"
+/{name} "{example_2}"
+```
+```
+
+### Step 4: 디렉토리 생성 및 저장
+
+```
+mkdir -p skills/{name}/
+Write → skills/{name}/SKILL.md
+```
+
+### Step 5: 검증
+
+생성된 파일을 읽어 검증한다:
+
+```
+검증 항목:
+  - [ ] YAML frontmatter 파싱 가능
+  - [ ] name, description, triggers 필수 필드 존재
+  - [ ] 본문에 용도, 워크플로우, 토큰 예산, 사용 예 섹션 존재
+  - [ ] 파일 크기 < 800줄
+  - [ ] 기존 스킬과 트리거 충돌 없음
+```
+
+충돌 발견 시 AskUserQuestion으로 트리거 조정 요청.
+
+## 동작 규칙
+
+1. 사용자가 이름만 제공해도 나머지는 대화형으로 수집한다.
+2. 사용자가 상세 설명을 한꺼번에 제공하면 확인만 받고 즉시 생성한다.
+3. Deep 타입 선택 시 tfx-consensus 통합 포인트를 본문에 자동 포함한다.
+4. 생성 후 반드시 사용자에게 결과를 보여주고 수정 요청을 받는다.
+5. 기존 SKILL.md가 있으면 덮어쓰기 전 사용자 확인을 받는다.
+
+## 토큰 예산
+
+| 단계 | 토큰 |
+|------|------|
+| 요구사항 수집 | ~2K |
+| 기존 스킬 분석 | ~3K |
+| SKILL.md 생성 | ~3K |
+| 검증 | ~2K |
+| **총합** | **~10K** |
+
+## 사용 예
+
+```
+/tfx-forge
+/tfx-forge tfx-myskill
+/tfx-forge "CI/CD 파이프라인 자동 생성 스킬"
+/스킬 만들기 "코드 마이그레이션 도우미"
+```