triflux 10.3.4 → 10.7.0

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

@@ -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]"
+---
+
+# {{SKILL_NAME}} — 훅 우선순위 관리자
+
+> 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-hooks/skill.json

@@ -1,8 +1,6 @@
 {
   "name": "tfx-hooks",
   "description": "Claude Code 훅 우선순위 관리자. AskUserQuestion 기반 인터랙티브 UI로 훅 스캔, 우선순위 조정, 오케스트레이터 적용/복원, 개별 훅 토글을 수행합니다. 사용자가 훅, hooks, 훅 관리, hook priority, 훅 우선순위, 오케스트레이터, orchestrator, 훅 설정, hook 설정, 훅 순서, hook order를 언급할 때마다 반드시 이 스킬을 사용하세요. Use when: hooks, 훅, hook priority, 훅 관리, orchestrator, 오케스트레이터, 훅 설정, 훅 순서",
-  "triggers": [
-    "tfx-hooks"
-  ],
+  "triggers": ["tfx-hooks"],
   "argument_hint": "[scan|apply|restore]"
 }

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

@@ -0,0 +1,212 @@
+---
+name: tfx-hub
+description: >
+  tfx-hub MCP 메시지 버스 관리. CLI 에이전트 간 실시간 통신 허브를 시작/중지/상태확인하고,
+  hub 도메인의 자유형 작업도 처리합니다.
+  Use when: hub, 허브, 메시지 버스, message bus, 브릿지, bridge, MCP 서버 관리, 에이전트 통신
+triggers:
+  - tfx-hub
+argument-hint: "<start|stop|status|자유형 작업 설명>"
+---
+
+# {{SKILL_NAME}} — MCP 메시지 버스 관리 + 개방형 작업
+
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+
+> **인프라**: 다른 스킬이 내부적으로 사용. 직접 호출할 필요 없음.
+> CLI 에이전트(Codex/Gemini/Claude) 간 실시간 메시지 허브를 관리합니다.
+> **커맨드 매칭 + fallthrough**: start/stop/status에 매칭되면 즉시 실행,
+> 매칭 안 되면 **hub 도메인 컨텍스트를 활용한 범용 작업**으로 처리합니다.
+
+## 입력 해석 규칙
+
+```
+/tfx-hub start          → 커맨드 매칭 → 허브 시작
+/tfx-hub stop           → 커맨드 매칭 → 허브 중지
+/tfx-hub status         → 커맨드 매칭 → 상태 확인
+/tfx-hub 테스트해줘      → fallthrough → hub 관련 범용 작업으로 처리
+/tfx-hub 문서 저장해     → fallthrough → hub 관련 범용 작업으로 처리
+/tfx-hub 브릿지 분석해   → fallthrough → hub 관련 범용 작업으로 처리
+```
+
+**fallthrough 규칙**: 인자가 start/stop/status/--port 등 커맨드 키워드에 매칭되지 않으면,
+사용자의 입력을 **hub/브릿지/메시지버스 도메인의 자유형 작업**으로 해석한다.
+
+fallthrough 라우팅:
+```bash
+# tfx-route.sh 경유 (권장)
+Bash("bash ~/.claude/scripts/tfx-route.sh {에이전트} '{hub 컨텍스트 + 작업}' {mcp_profile}")
+
+# codex 직접 호출 시 — 반드시 exec 서브커맨드 포함
+Bash("codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check '{작업}'")
+Bash("codex --profile gpt54_xhigh exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check '{작업}'")
+#          ↑ --profile은 exec 앞에, --skip-git-repo-check은 exec 뒤에
+
+# Claude 네이티브 (탐색/검증)
+Agent(subagent_type="oh-my-claudecode:explore", prompt="{작업}")
+```
+
+## 커맨드
+
+### start — 허브 시작
+
+```bash
+Bash("node hub/server.mjs", run_in_background=true)
+```
+
+- Streamable HTTP MCP 서버를 `http://127.0.0.1:27888/mcp` 에서 시작
+- SQLite WAL DB: `~/.claude/cache/tfx-hub/state.db`
+- PID 파일: `~/.claude/cache/tfx-hub/hub.pid`
+- 환경변수: `TFX_HUB_PORT` (포트), `TFX_HUB_DB` (DB 경로)
+
+### stop — 허브 중지
+
+```bash
+# PID 파일에서 프로세스 ID 읽어서 종료
+Bash("node -e \"
+  const fs = require('fs');
+  const path = require('path');
+  const pidFile = path.join(require('os').homedir(), '.claude/cache/tfx-hub/hub.pid');
+  if (fs.existsSync(pidFile)) {
+    const info = JSON.parse(fs.readFileSync(pidFile, 'utf8'));
+    process.kill(info.pid, 'SIGTERM');
+    console.log('tfx-hub 종료 (PID ' + info.pid + ')');
+  } else {
+    console.log('tfx-hub 미실행');
+  }
+\"")
+```
+
+### status — 상태 확인
+
+```bash
+# HTTP 상태 엔드포인트 조회
+Bash("curl -s http://127.0.0.1:27888/status 2>/dev/null || echo '{\"error\":\"hub 미실행\"}'")
+```
+
+## 각 CLI 등록 방법
+
+허브 시작 후 각 CLI에 MCP 서버로 등록:
+
+```bash
+# Codex (수동 opt-in 예시)
+# triflux는 config.json을 자동 관리하며, standalone Codex 노이즈 방지를 위해
+# 사전 등록은 disabled로 두고 `tfx hub start` 이후에만 enabled로 전환한다.
+codex mcp add tfx-hub --url http://127.0.0.1:27888/mcp
+
+# Gemini (settings.json)
+# mcpServers.tfx-hub.url = "http://127.0.0.1:27888/mcp"
+
+# Claude
+claude mcp add --transport http tfx-hub http://127.0.0.1:27888/mcp
+```
+
+## MCP 도구 (20개)
+
+### Core — 기본 통신
+
+| 도구 | 설명 |
+|------|------|
+| `register` | 에이전트 등록 + lease 발급 |
+| `status` | 허브/에이전트/큐/트레이스 상태 조회 |
+| `publish` | 이벤트/응답 메시지 발행 (topic fanout 지원) |
+| `ask` | 다른 에이전트에게 질문 (request/reply, await_response_ms 폴링 지원) |
+| `handoff` | 작업 인계 (acceptance_criteria 지정 가능) |
+| `poll_messages` | 수신함에서 메시지 폴링 **(Deprecated — Named Pipe 사용)** |
+
+### Assign — 비차단 작업 할당
+
+| 도구 | 설명 |
+|------|------|
+| `assign_async` | AWS CAO 스타일 비차단 job 생성 + 워커 실시간 전달 |
+| `assign_result` | job 진행/완료 결과 보고 |
+| `assign_status` | job 단건 상태 또는 목록 조회 |
+
+### Team — Claude Native Teams 프록시
+
+| 도구 | 설명 |
+|------|------|
+| `team_info` | Teams 메타/멤버/경로 정보 조회 |
+| `team_task_list` | task 목록 조회 (owner/status 필터) |
+| `team_task_update` | task claim/update |
+| `team_send_message` | Teams inbox에 메시지 append |
+
+### Pipeline — 파이프라인 관리
+
+| 도구 | 설명 |
+|------|------|
+| `pipeline_init` | 새 파이프라인 초기화 |
+| `pipeline_state` | 파이프라인 상태 조회 |
+| `pipeline_advance` | 다음 단계로 전이 (전이 규칙 + fix loop 바운딩) |
+| `pipeline_advance_gated` | HITL 승인 게이트 포함 전이 |
+| `pipeline_list` | 활성 파이프라인 목록 조회 |
+
+### HITL — Human-in-the-Loop
+
+| 도구 | 설명 |
+|------|------|
+| `request_human_input` | 사용자 입력 요청 (CAPTCHA/승인/자격증명/선택/텍스트) |
+| `submit_human_input` | 사용자 입력 응답 (accept/decline/cancel) |
+
+## 브릿지 REST 엔드포인트 (4개)
+
+| 엔드포인트 | 설명 |
+|-----------|------|
+| `POST /bridge/register` | 에이전트 등록 (프로세스 수명 기반 lease) |
+| `POST /bridge/result` | 결과 발행 (topic fanout) |
+| `POST /bridge/context` | 선행 컨텍스트 폴링 (auto_ack) |
+| `POST /bridge/deregister` | 에이전트 offline 마킹 |
+
+## 프로젝트 구조
+
+```
+hub/
+├── server.mjs            # MCP 서버 + REST 브릿지 엔드포인트
+├── store.mjs             # SQLite WAL 상태 저장소
+├── router.mjs            # Actor mailbox 라우터 + QoS
+├── tools.mjs             # MCP 도구 20개 정의
+├── hitl.mjs              # Human-in-the-Loop 매니저
+├── bridge.mjs            # tfx-route.sh ↔ hub 브릿지 CLI
+├── schema.sql            # DB 스키마
+├── paths.mjs             # 경로 상수 (PID 파일, DB 경로 등)
+├── pipe.mjs              # Named Pipe 서버 (push 구독 채널)
+├── assign-callbacks.mjs  # assign job 콜백 처리
+├── intent.mjs            # 인텐트 파싱
+├── reflexion.mjs         # reflexion 루프
+├── research.mjs          # 리서치 프록시
+├── token-mode.mjs        # 토큰 모드 관리
+├── pipeline/             # 파이프라인 엔진
+│   ├── index.mjs         # createPipeline() 팩토리
+│   ├── state.mjs         # 파이프라인 상태 CRUD
+│   ├── transitions.mjs   # 전이 규칙
+│   └── gates/            # HITL 게이트 (selfcheck, confidence)
+├── delegator/            # 작업 위임 레이어
+│   ├── index.mjs
+│   ├── service.mjs
+│   ├── contracts.mjs
+│   └── tool-definitions.mjs
+├── team/                 # Claude Native Teams 통합
+│   ├── nativeProxy.mjs   # Teams MCP 프록시
+│   ├── orchestrator.mjs  # 팀 오케스트레이터
+│   ├── session.mjs       # 세션 관리
+│   ├── dashboard.mjs     # TUI 대시보드
+│   ├── tui.mjs           # TUI 렌더러
+│   └── cli/              # tfx team CLI 커맨드
+├── workers/              # CLI 워커 어댑터
+│   ├── factory.mjs
+│   ├── claude-worker.mjs
+│   ├── codex-mcp.mjs
+│   ├── gemini-worker.mjs
+│   └── delegator-mcp.mjs
+├── middleware/           # 요청 미들웨어
+│   └── request-logger.mjs
+├── quality/              # 품질 검사
+│   └── deslop.mjs
+└── public/               # 정적 자산 (대시보드 HTML, 트레이 아이콘)
+```
+
+## 상태
+
+**dev 전용** — 로컬 테스트 목적. 프로덕션 배포 전 안정화 필요.

package/skills/tfx-hub/skill.json

@@ -1,8 +1,6 @@
 {
   "name": "tfx-hub",
   "description": "tfx-hub MCP 메시지 버스 관리. CLI 에이전트 간 실시간 통신 허브를 시작/중지/상태확인하고, hub 도메인의 자유형 작업도 처리합니다. Use when: hub, 허브, 메시지 버스, message bus, 브릿지, bridge, MCP 서버 관리, 에이전트 통신",
-  "triggers": [
-    "tfx-hub"
-  ],
+  "triggers": ["tfx-hub"],
   "argument_hint": "<start|stop|status|자유형 작업 설명>"
 }

package/skills/tfx-index/SKILL.md

@@ -26,6 +26,7 @@ argument-hint: "[--update] [경로]"
 > - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.
 
 
+
 > SuperClaude index-repo 오마주. 1회 2K 토큰으로 인덱스 생성, 이후 세션마다 55K 토큰 절감.
 
 > **Gemini 위임**: 스캔 + 인덱스 생성 작업은 Gemini CLI에 위임한다. Claude는 모드 선택(Step 0)과 파일 쓰기만 담당. Claude 토큰 소비 ~500 tokens으로 줄어든다.

package/skills/tfx-index/skill.json

@@ -1,11 +1,6 @@
 {
   "name": "tfx-index",
   "description": "프로젝트 구조를 빠르게 파악하거나 토큰을 절약할 때 사용한다. '인덱싱', '프로젝트 구조', '인덱스 만들어', '코드베이스 맵', '프로젝트 개요' 같은 요청에 사용. 새 프로젝트 온보딩, 세션 시작 시 컨텍스트 효율화에 적극 활용.",
-  "triggers": [
-    "인덱싱",
-    "프로젝트 인덱스",
-    "인덱스",
-    "tfx-index"
-  ],
+  "triggers": ["인덱싱", "프로젝트 인덱스", "인덱스", "tfx-index"],
   "argument_hint": "[--update] [경로]"
 }