triflux 10.50.2 → 10.51.0

package/CLAUDE.md

@@ -1,20 +1,25 @@
-# triflux — Claude Code 운영 가이드
+# triflux Claude Code 운영 가이드
 
 <core-systems>
-## 핵심 스킬 시스템 (항상 인지)
+## 스킬 시스템
 
 이 프로젝트는 3개의 스킬 시스템을 동시에 사용한다. 어떤 작업이든 해당 시스템의 스킬이 있는지 먼저 확인한다.
 
 | 시스템 | 접두사 | 용도 | 스킬 수 |
 |--------|--------|------|---------|
-| **triflux** | `/tfx-*` | CLI 라우팅·다중 모델 조정·스웜·원격 실행 | ~40개 |
+| **triflux** | `/tfx-*` | CLI 라우팅·다중 모델 조정·원격 실행 | 10개 |
 | **gstack** | `/` (접두사 없음) | QA·출시·조사·설계·검토·점검 지점 | ~35개 |
 | **omc** | `/oh-my-claudecode:*` | autopilot·ralph·team·execute·ultragoal | ~37개 |
 
-스킬을 모르면 자연어 라우팅(`.claude/rules/tfx-routing.md`)으로 자동 매핑된다.
-세션 종료 전 메모리 파일이 3개+ 변경됐으면 `/memory-hygiene` 제안을 검토한다.
+필요한 스킬은 이름으로 호출한다.
 </core-systems>
 
+<code-principles>
+## 코드 작성 원칙
+
+코드는 간결하게 쓰고 의미 있는 이름을 쓴다. 주석은 이유만 짧게 한국어로 쓴다. 테스트는 회귀를 막는 핵심 경로만 최소한으로 둔다. 제거 여부는 해당 파일을 끝까지 직접 읽고 판단한다.
+</code-principles>
+
 <psmux-wt>
 ## psmux/WT 규칙 (Windows 한정)
 
@@ -28,7 +33,7 @@ macOS/Linux는 플랫폼 보호기가 아무 작업도 하지 않게 처리하
 
 위 `<psmux-wt>` 룰셋은 Windows 전용이다. macOS/Linux 환경에서 triflux가 터미널/세션을 다루는 방식.
 
-### terminal-opener.mjs 3단계 대체 경로(`hub/team/terminal-opener.mjs` 의 `openCommand`)
+### 터미널 실행 경로
 
 `openCommand()` 가 순차 평가하는 분기:
 
@@ -37,9 +42,9 @@ macOS/Linux는 플랫폼 보호기가 아무 작업도 하지 않게 처리하
 | 1 | `platform === "win32"` | `wt-manager.createTab` | `hub/team/wt-manager.mjs` |
 | 2 | `isTmuxLikeMux(mux)` (`detectMultiplexer()` → `getMultiplexerType()`/`hasMultiplexer()`/`hasTmux()`) | `tmux new-window -n <title> <command>` | 셸 직접 호출 |
 | 3 | `platform === "darwin"` (대체 경로) | `open -a Terminal` | macOS `open` 명령 |
-| — | Linux(멀티플렉서 없음) | 미지원(`false` 반환) | — |
+| 없음 | Linux(멀티플렉서 없음) | 미지원(`false` 반환) | 없음 |
 
-### 별도 mac 매니저 불필요
+### 터미널 관리 방식
 
 | 후보 | 필요성 | 이유 |
 |------|--------|------|
@@ -47,21 +52,19 @@ macOS/Linux는 플랫폼 보호기가 아무 작업도 하지 않게 처리하
 | tmux 관리자 | **불필요** | `terminal-opener.mjs`가 `tmux new-window`로 직접 호출한다. |
 | psmux 관리자 | **이미 있음** | `hub/team/psmux.mjs`가 Windows에서는 psmux, macOS/Linux에서는 tmux를 사용한다. |
 
-참고 사례: OMC(`oh-my-claudecode`)도 운영체제별 관리자를 만들지 않고 Tmux 관리자·워크트리 관리자·Claude 실행기 세 구성 요소로 정리한다. 이 저장소 결정의 외부 근거가 아니라 비교 참고로만 본다.
-
-### 플랫폼 보호기 위치(참고)
+### 플랫폼 보호기
 
-| 파일 | 줄 | 보호기 |
+| 파일 | 함수 | 보호기 |
 |------|------|-------|
-| `hub/team/wt-manager.mjs` | 199 | `if (platform() !== "win32") return createNonWindowsStubManager();` |
-| `hub/team/headless.mjs` | 1725-1726 | `if (process.platform !== "win32") return false;` + `WT_SESSION` 체크 |
-| `tfx-route.sh` | 86, 1662, 1681 | `case "$(uname -s)"` 분기 |
+| `hub/team/wt-manager.mjs` | `createWtManager` | `if (platform() !== "win32") return createNonWindowsStubManager();` |
+| `hub/team/headless.mjs` | `autoAttachTerminal` | `if (process.platform !== "win32") return false;` + `WT_SESSION` 체크 |
+| `scripts/tfx-route.sh` | `resolve_machine_profile_path`, `heartbeat_monitor` | `case "$(uname -s)"` 분기 |
 
-mac에서 위 코드가 호출돼도 일찍 반환하므로 실행되지 않는 코드가 동작하지 않는다. **실행되지 않는 문서만 주입되는 것이 남은 불일치다.**
+Windows 전용 경로는 플랫폼과 `WT_SESSION` 조건을 확인한다.
 
-### macOS 알림(참고)
+### macOS 알림
 
-`hub/team/notify.mjs:221~234`가 `osascript`로 macOS 기본 알림을 보낸다. 별도 의존성은 없다.
+`hub/team/notify.mjs`의 `sendToast`가 `osascript`로 macOS 기본 알림을 보낸다. 별도 의존성은 없다.
 </macos-terminal>
 
 <codex-config>
@@ -74,25 +77,24 @@ mac에서 위 코드가 호출돼도 일찍 반환하므로 실행되지 않는
 | `approval_policy` (`on-request` / `never` / granular) | `--dangerously-bypass-approvals-and-sandbox` |
 | `sandbox_mode` (`read-only` / `workspace-write` / `danger-full-access`) | `-s`, `--sandbox` |
 
-`--full-auto` 는 Codex 0.147 에서 제거됐다. 안전한 방식: `config.toml`에 기본값을 두고 CLI에서는 `--profile`만 선택한다.
+`--full-auto` 는 Codex 0.147 에서 제거되었다. 안전한 방식: `config.toml`에 기본값을 두고 CLI에서는 `--profile`만 선택한다.
 프로필은 `$CODEX_HOME/<이름>.config.toml` 파일이다(인라인 `[profiles.*]` 아님).
 </codex-config>
 
 <account-broker>
 ## AccountBroker (계정 브로커)
 
-conductor·headless·swarm-hypervisor가 하나의 AccountBroker 단일 인스턴스를 공유한다.
+headless 워커는 AccountBroker를 사용한다.
 
 | 항목 | 설명 |
 |------|------|
-| 계정별 회로 차단기 | 장애 격리 — 한 계정 오류가 다른 계정에 전파되지 않음 |
+| 계정별 회로 차단기 | 장애 격리: 한 계정 오류가 다른 계정에 전파되지 않음 |
 | 사용 중 플래그 | 동일 계정 이중 임대 방지 |
 | `/broker/reload` | 장시간 세션 중 accounts.json을 다시 불러온다. 활성 임대 소유권은 다시 불러온 뒤에도 보존한다. |
 | 어댑터의 임대 없음 정책 | headless 어댑터는 브로커가 비활성·비어 있음이면 기본 CLI 인증 경로로 실행하고, 브로커가 활성인데 임대가 없으면 `circuit_open`으로 실패한다. |
-| Conductor의 임대 없음 정책 | 로컬 Conductor 세션은 `broker_no_lease`를 이벤트 로그에 남기고 생성을 계속한다. accountId가 없으므로 해제는 호출하지 않는다. |
 | 공개 스냅숏 정책 | `/broker/snapshot`과 대시보드는 `publicSnapshot()`만 사용한다. `env`, `authFile`, `profile`, `host`, 파일 경로, 가공하지 않은 실패 시각은 공개하지 않는다. |
 | 진단 이벤트 | `securityViolation`, `authSyncError`는 허브가 가린 경고 로그(`broker.security_violation`, `broker.auth_sync_error`)로 처리한다. |
-| EventEmitter 이벤트 | `lease`, `release`, `cooldown`, `tierFallback`, `circuitOpen`, `circuitClose`, `noAvailableAccounts` — HUD 연동용 |
+| EventEmitter 이벤트 | `lease`, `release`, `cooldown`, `tierFallback`, `circuitOpen`, `circuitClose`, `noAvailableAccounts`: HUD 연동용 |
 </account-broker>
 
 <remote>
@@ -102,7 +104,6 @@ conductor·headless·swarm-hypervisor가 하나의 AccountBroker 단일 인스
 
 | 스킬 | 대상 | 방식 |
 |------|------|------|
-| tfx-swarm | 로컬 worktree + shard `host:` 원격 분배 | PRD별 worktree, 다중 모델·기기 |
 | tfx-remote | Claude Code 원격 | SSH → Claude Code 세션 → 내부 tfx 라우팅 |
 
 Codex를 SSH 너머로 직접 실행하지 않는다. `config.toml` 충돌과 TTY 문제가 있다.
@@ -137,6 +138,12 @@ Codex를 SSH 너머로 직접 실행하지 않는다. `config.toml` 충돌과 TT
 </headless-retrieval>
 
 <native-bridge>
+## 팀 실행 모드
+
+`tfx multi`는 tmux/psmux와 headless를 지원한다. in-process와 WT 팀 모드는 지원하지 않는다.
+대화형 auto 실행에서 멀티플렉서가 없으면 tmux(macOS/Linux) 또는 psmux(Windows) 설치 오류로 끝난다.
+비TTY에서 멀티플렉서가 없으면 headless로 실행한다. Windows Terminal의 독립 탭 열기는 유지한다.
+
 ## 기본 연결 UI(`claude agents` 노출)
 
 비대화식 워커는 기본적으로 `claude agents` 패널에 행으로 나타난다. 제외하려면 `--no-native-bridge-ui`를 쓴다.
@@ -144,9 +151,7 @@ Codex를 SSH 너머로 직접 실행하지 않는다. `config.toml` 충돌과 TT
 | 모드 | 기본값 | 행이 보이는 위치 |
 |------|---------|--------------------|
 | `tfx-auto` / `tfx multi`(비대화식) | 켬 | 로컬 `claude agents` |
-| `tfx swarm` 로컬 조각 | 켬 | 로컬 `claude agents`(`Triflux swarm <shard-name>`) |
-| `tfx swarm` 원격 조각 | **건너뛰고 경고** | 해당 없음 — `registerSwarmShard()`가 host!=local일 때 `{ ok: true, skipped: true }`를 반환하고 `"remote launcher must register on that host"`만 경고한다. 원격 데몬 실제 등록은 후속 PRD다. |
-| 대화식(tmux/wt) | 끔 | 해당 없음 |
+| 대화식(tmux/psmux) | 끔 | 해당 없음 |
 
 감시자가 종료되면 즉시 데몬의 `sendKillBySessionId`를 실행해 오래된 행을 남기지 않는다. PRD: `.triflux/plans/native-bridge-ui-default-expansion.md`(PR #323으로 병합).
 </native-bridge>
@@ -176,19 +181,22 @@ Codex를 SSH 너머로 직접 실행하지 않는다. `config.toml` 충돌과 TT
 
 | 파일 | 내용 |
 |------|------|
-| `.claude/rules/tfx-routing.md` | 자연어 → 스킬 라우팅, CLI 라우팅 Layer 1~3, 충돌 해소 |
-| `.claude/rules/tfx-execution-skill-map.md` | tfx-auto / multi / swarm 실행 엔진 매핑, 격리 기준, 안티패턴 |
-| `.claude/rules/tfx-autoplan-principles.md` | gstack autoplan의 여섯 가지 결정 원칙·단계 우선순위·충돌 해소 규칙 추출본 |
+| `.claude/rules/tfx-execution-skill-map.md` | tfx-auto / multi 실행 경로와 코드 변경 병렬 작업의 worktree 격리 기준 |
 | `.claude/rules/tfx-update-logic.md` | triflux / OMC / gstack / Codex / Antigravity 업데이트 로직 |
 | `.claude/rules/tfx-stack-coexistence.md` | gstack / superpowers / triflux 공존 원칙, 레이어 분리, 의존 방향, 충돌 해소 |
 | `.claude/rules/tfx-mirror-policy.md` | packages/ 3계층 미러 정책(핵심 단순 복사 / 원격 가져오기 변환 / triflux 바이트 동일), 테스트 제외 규칙, 불일치 차단 |
+| `.claude/rules/tfx-cto-hub-boundary.md` | CTO 조회 표면과 Hub 소유권 경계 |
+| `.claude/rules/tfx-doc-governance.md` | 실행 규칙, ADR, 설계, 계획 문서의 배치 |
+| `.claude/rules/tfx-escalation-chain.md` | 자동 재시도와 CLI 전환 체인 |
+| `.claude/rules/tfx-machine-profile.md` | 기기 프로필 우선순위와 실행 정책 |
+| `.claude/rules/tfx-psmux.md` | Windows psmux와 WT 실행 규칙 |
+| `.claude/rules/tfx-routing.md` | 역할별 CLI 라우팅과 직접 호출 제한 |
+| `.claude/rules/tfx-skill-authoring.md` | 스킬 frontmatter, 프로필 표기, 검증 규약 |
 
 Claude Code는 `.claude/rules/*.md`를 자동으로 불러온다. Codex CLI는 `@import`를 지원하지 않으므로 필요하면 `AGENTS.md`를 독립적으로 유지한다.
 
 ## GBrain
 
-설정 정본은 `~/Projects/CLAUDE.md` 한 곳이다. 여기 있던 사본은 `engine=pglite` /
-`2026-04-25`로 오래되어 전역·Projects 블록과 서로 모순됐다(2026-07-26 제거).
-실제 엔진은 postgres(Supabase), gbrain 0.42.51.0이다.
+설정 정본은 `~/Projects/CLAUDE.md`다.
 
 - 이 저장소 정책: 읽기·쓰기(github.com/tellang/triflux)

package/README.ko.md

@@ -24,8 +24,8 @@
 
 triflux는 코딩 작업을 Claude, Codex, Antigravity 사이에서 나눠 맡기는 Claude Code 플러그인이자
 npm CLI다. `/tfx-auto`에 할 일을 한 번 적으면 triflux가 CLI 레인(기본은 Codex)을 고르고, 임의
-셸 명령 대신 관리된 경로로 실행한다. 필요하면 로컬 병렬 워커, worktree로 격리한 스웜,
-Claude↔Codex 라이브 세션, 원격 호스트로 작업을 나눈다. 설치, 진단, 로컬 Hub, 팀 실행은 `tfx`
+셸 명령 대신 관리된 경로로 실행한다. 필요하면 로컬 병렬 워커, Claude↔Codex 라이브 세션, 원격 호스트로 작업을 나눈다.
+코드 변경을 병렬로 진행할 때는 작업별 worktree와 세션을 분리한다. 설치, 진단, 로컬 Hub, 팀 실행은 `tfx`
 셸 CLI가 맡는다.
 
 ## 설치
@@ -35,6 +35,19 @@ npm install -g triflux   # postinstall이 setup 스크립트를 실행한다
 tfx doctor               # CLI, tmux, Hub, MCP, 프로필, 스킬 점검
 ```
 
+npm 12 이상은 기본적으로 설치 스크립트를 막는다. setup과 네이티브 의존성의 스크립트를 허용해 설치한다.
+
+```bash
+npm i -g triflux --allow-scripts=triflux,better-sqlite3
+```
+
+기본 setup은 `triflux` 마켓플레이스를 등록하고 mods 설치 안내만 출력한다. 사용량 band와
+서브에이전트 effort 강제 기능은 따로 설치한다(Claude Code 2.1.287 이상).
+
+```bash
+tfx setup --mods
+```
+
 이 저장소의 마켓플레이스에서 Claude Code 플러그인으로 설치할 수도 있다.
 
 ```bash
@@ -52,8 +65,6 @@ claude plugin install triflux@triflux
 /tfx-auto "마이그레이션 끝내고 검증까지" --mode deep --retry ralph --max-iterations 10
 ```
 
-실행하지 않고 라우팅 판정만 보려면 셸에서 `tfx auto "<작업>" --json`을 실행한다.
-
 ## 스킬
 
 직접 쓰는 스킬:
@@ -62,7 +73,7 @@ claude plugin install triflux@triflux
 | --- | --- |
 | `/tfx-auto` | 구현, 수정, 리뷰, 병렬 작업의 진입점. 동작은 아래 플래그로 정한다. |
 | `/tfx-live` | Claude↔Codex 라이브 세션. `start`/`ask`/`stop`, `peer` 중계, `orchestrate`, `list-sessions`. |
-| `/tfx-remote` | SSH 너머 원격 Claude Code 세션. `setup`, `spawn`, `list`, `attach`, `send`, `resume`, `probe`, `kill`. |
+| `/tfx-remote` | SSH 원격 Claude Code 세션 시작, 조회, 재부착, 메시지 전송, 준비 상태 확인, 모니터링, 종료. |
 | `/tfx-setup` | 대화형 설정. 파일 동기화, HUD, Codex 프로필, MCP, 훅 우선순위. |
 | `/tfx-doctor` | 진단과 복구. Hub 시작·중지·상태 확인도 여기서 한다. |
 | `/tfx-ship` | triflux 릴리즈 절차(메인테이너용). |
@@ -88,13 +99,10 @@ Codex 프로필은 `~/.codex/<프로필>.config.toml`에서 직접 관리한다.
 | `--shape` | `consensus`, `debate`, `panel` | `--mode consensus`의 결과 형태 |
 | `--cli` | `auto`, `codex`, `antigravity`, `claude` | CLI 레인 고정 |
 | `--cli-set` | `triad`, `no-antigravity`, `custom` | 합의 참여자 구성 |
-| `--parallel` | `1`, `N`, `swarm` | `N` = 로컬 워커(`tfx multi`), `swarm` = worktree별 PRD 샤드(`tfx swarm`) |
-| `--isolation` | `none`, `worktree` | 샤드별 worktree 격리(`swarm`이면 강제) |
-| `--remote` | `<host>` | 스웜 샤드를 `hosts.json`의 호스트로 보냄 |
+| `--parallel` | `1`, `N` | `N` = 로컬 워커(`tfx multi`) |
 | `--retry` | `0`, `1`(기본), `ralph`, `auto-escalate` | `ralph` = 막힘 감지가 있는 재시도 상태 기계, `auto-escalate` = 모델 체인을 한 단계씩 올림 |
 | `--max-iterations` | `N` | `ralph`/`auto-escalate` 상한(`0`은 무제한) |
 | `--rounds` | `N`(기본 4) | `--mode live` 왕복 횟수 |
-| `--risk-tier` | `auto`, `low`, `medium`, `high` | 변경 범위로 검증 강도를 정함. `--mode`가 있으면 무시 |
 | `--skill` | `<name>` | `skills/<name>/SKILL.md`를 Codex/Antigravity 프롬프트 앞에 붙임 |
 | `--no-native-bridge-ui` | | headless 워커를 `claude agents` 패널에 띄우지 않음 |
 
@@ -124,15 +132,14 @@ Codex는 이름 붙은 프로필로 실행한다. 모델 ID는 `~/.codex/<프로
 | 명령 | 용도 |
 | --- | --- |
 | `tfx setup` / `tfx doctor` | 파일·HUD·MCP·프로필 동기화 / 진단과 복구(`--fix`, `--json`) |
-| `tfx auto` | `tfx-auto` 라우팅 판정 미리 보기 |
 | `tfx multi` | tmux + Hub 기반 로컬 멀티 CLI 팀 |
-| `tfx swarm` | PRD 기반 worktree 격리 실행: `plan`, `preflight`, `run`, `list` |
-| `tfx synapse` | 스웜 세션 레지스트리와 lease |
+| `tfx synapse` | 세션 레지스트리와 lease |
 | `tfx hub` | 로컬 Hub: `start`, `stop`, `status`, `ensure` |
 | `tfx mcp` | 관리형 MCP 레지스트리: `list`, `sync`, `add`, `remove` |
 | `tfx handoff` | 현재 맥락을 다른 세션이나 호스트로 넘길 프롬프트로 묶음 |
 | `tfx cto` | 저장소 단위 권위 콘솔: `collect`, `status`, `hygiene`(dry-run) |
-| `tfx review` / `tfx codex-team` | Codex git diff 리뷰 / Codex 주도 팀 모드 |
+| `tfx codex-team` | Codex 주도 팀 모드 |
+| `bash ~/.claude/scripts/tfx-route.sh code-reviewer "<지시>"` | 정책에 따라 `codex exec review`로 리뷰 전달 |
 | `tfx stealth-fetch <url>` | cloakbrowser로 URL 하나를 가져옴(JSON을 stdout으로) |
 | `tfx notion-read`, `tfx why`, `tfx schema`, `tfx list`, `tfx monitor`, `tfx update`, `tfx version` | Notion → Markdown, 커밋 intent 트레일러, CLI 스키마, 설치된 스킬, TUI 모니터, 업데이트, 버전 |
 | `tfx-live` | 라이브 세션 브리지(`/tfx-live` 스킬과 같은 명령) |
@@ -154,7 +161,7 @@ Claude Code Bash 도구의 600초 제한에 걸리지 않는다. 이후 `--job-s
 
 **Hub.** 팀, 원격 세션, MCP 도구, 상태 표시를 잇는 로컬 메시지 버스다. 기본으로
 `127.0.0.1:27888`에 붙고(`TFX_HUB_PORT`로 변경), `TFX_HUB_TOKEN`이 있으면 bearer 토큰을 요구한다.
-`tfx-auto`, `tfx multi`, 로컬 스웜 샤드의 headless 워커는 `claude agents` 패널에 행으로 보인다.
+`tfx-auto`, `tfx multi`의 headless 워커는 `claude agents` 패널에 행으로 보인다.
 끄려면 `--no-native-bridge-ui`를 준다.
 
 **재시도와 승격.** `--retry ralph`는 끝나거나 막힐 때(같은 실패 3회 연속)까지 반복한다.
@@ -169,12 +176,13 @@ Claude Code Bash 도구의 600초 제한에 걸리지 않는다. 이후 `--job-s
 
 **CTO lake.** `tfx cto collect`로 `.triflux/lake/`의 저장소 스냅샷을 갱신하고,
 `tfx cto status`로 생성 시각과 경과 시간을 확인한다. `tfx cto hygiene --dry-run`는 dry-run 결과를
-보고한다. 트레이와 쓰이지 않는 CTO 운영 명령은 제거했다
+보고한다. 트레이와 쓰이지 않는 CTO 운영 명령은 제거하였다
 ([ADR-0024](docs/adr/0024-cto-explicit-queries-only.md)). 자동 수집은 기본으로 꺼져 있고 `TFX_CTO_AUTO_COLLECT=1` 로 켠다([ADR-0018](docs/adr/0018-cto-auto-behaviors-opt-in.md)).
 
-**원격 호스트.** `/tfx-remote`와 `--remote <host>`는 `~/.config/triflux/hosts.json`
-(Windows는 `%APPDATA%\triflux\hosts.json`)에서 호스트를 읽는다. `/tfx-remote setup`으로 호스트를
-추가한 뒤 `/tfx-remote spawn <host> "보안 리뷰 실행"`처럼 쓴다.
+**원격 호스트.** `/tfx-remote`는 `~/.config/triflux/hosts.json`
+(Windows는 `%APPDATA%\triflux\hosts.json`)에서 호스트를 읽는다. 세션 시작은
+`remote-spawn.mjs`의 `--host <host> --prompt "<요청>"` 옵션을 사용한다.
+[실행 옵션](skills/tfx-remote/SKILL.md)을 따른다.
 
 ## 구조
 
@@ -184,12 +192,11 @@ graph TD
     User --> CLI[tfx CLI]
     Skills --> Route[tfx-route.sh]
     Skills --> Live[tfx-live]
-    CLI --> Team["tfx multi · tfx swarm"]
+    CLI --> Team["tfx multi"]
     Route --> Codex[Codex CLI]
     Route --> Agy[Antigravity agy]
     Route --> Claude[Claude Code]
     Team --> Route
-    Team --> WT[(git worktrees)]
     Live -->|UDS 또는 tmux| Sessions[Claude / Codex TUI 세션]
     Route --> Hub["Hub 127.0.0.1:27888"]
     Team --> Hub

package/README.md

@@ -25,8 +25,9 @@
 triflux is a Claude Code plugin and npm CLI that routes coding work across Claude, Codex,
 and Antigravity. You describe the task once with `/tfx-auto`; triflux picks the CLI lane
 (Codex by default), runs it through managed routes instead of ad-hoc shell commands, and
-can fan the work out to parallel workers, worktree-isolated swarms, live Claude↔Codex
-sessions, or remote hosts. The `tfx` shell CLI covers setup, diagnostics, the local Hub,
+can fan the work out to parallel workers, live Claude↔Codex sessions, or remote
+hosts. Parallel code changes use separate worktrees and one session per worktree.
+The `tfx` shell CLI covers setup, diagnostics, the local Hub,
 and team orchestration.
 
 ## Install
@@ -36,6 +37,19 @@ npm install -g triflux   # postinstall runs the setup script
 tfx doctor               # check CLIs, tmux, Hub, MCP, profiles, skills
 ```
 
+npm 12 and newer block install scripts by default. Allow the setup and native dependency scripts:
+
+```bash
+npm i -g triflux --allow-scripts=triflux,better-sqlite3
+```
+
+Setup registers the `triflux` marketplace and prints a mods installation hint. To install
+usage bands and subagent effort enforcement (Claude Code 2.1.287 or newer):
+
+```bash
+tfx setup --mods
+```
+
 Or install the Claude Code plugin from this repository's marketplace:
 
 ```bash
@@ -53,8 +67,6 @@ claude plugin install triflux@triflux
 /tfx-auto "finish the migration and verify it" --mode deep --retry ralph --max-iterations 10
 ```
 
-Run `tfx auto "<task>" --json` in a shell to preview the routing decision without executing it.
-
 ## Skills
 
 Skills you invoke directly:
@@ -63,7 +75,7 @@ Skills you invoke directly:
 | --- | --- |
 | `/tfx-auto` | Front door for implementing, fixing, reviewing, and parallel work. Behavior is set by flags (below). |
 | `/tfx-live` | Live Claude↔Codex sessions: `start`/`ask`/`stop`, `peer` relay, `orchestrate`, `list-sessions`. |
-| `/tfx-remote` | Remote Claude Code sessions over SSH: `setup`, `spawn`, `list`, `attach`, `send`, `resume`, `probe`, `kill`. |
+| `/tfx-remote` | SSH 원격 Claude Code 세션 시작, 조회, 재부착, 메시지 전송, 준비 상태 확인, 모니터링, 종료. |
 | `/tfx-setup` | Interactive setup: file sync, HUD, Codex profiles, MCP, hook priority. |
 | `/tfx-doctor` | Diagnose and repair; also starts, stops, and checks the Hub. |
 | `/tfx-ship` | triflux release flow (maintainers). |
@@ -89,13 +101,10 @@ and execution. Manage Codex profiles directly in `~/.codex/<profile>.config.toml
 | `--shape` | `consensus`, `debate`, `panel` | Output shape for `--mode consensus` |
 | `--cli` | `auto`, `codex`, `antigravity`, `claude` | Force a CLI lane |
 | `--cli-set` | `triad`, `no-antigravity`, `custom` | Consensus participants |
-| `--parallel` | `1`, `N`, `swarm` | `N` = local workers (`tfx multi`); `swarm` = PRD shards in worktrees (`tfx swarm`) |
-| `--isolation` | `none`, `worktree` | Worktree isolation per shard (forced on with `swarm`) |
-| `--remote` | `<host>` | Send swarm shards to a host from `hosts.json` |
+| `--parallel` | `1`, `N` | `N` = local workers (`tfx multi`) |
 | `--retry` | `0`, `1` (default), `ralph`, `auto-escalate` | `ralph` = retry state machine with stuck detection; `auto-escalate` = move up the model chain |
 | `--max-iterations` | `N` | Cap for `ralph` / `auto-escalate` (`0` = unlimited) |
 | `--rounds` | `N` (default 4) | Round trips for `--mode live` |
-| `--risk-tier` | `auto`, `low`, `medium`, `high` | Pick verification strength from the change; ignored when `--mode` is set |
 | `--skill` | `<name>` | Prepend `skills/<name>/SKILL.md` to the Codex/Antigravity prompt |
 | `--no-native-bridge-ui` | | Hide headless workers from the `claude agents` panel |
 
@@ -125,15 +134,14 @@ escalation chain: [`.claude/rules/tfx-escalation-chain.md`](.claude/rules/tfx-es
 | Command | Use |
 | --- | --- |
 | `tfx setup` / `tfx doctor` | Sync files, HUD, MCP, profiles / diagnose and repair (`--fix`, `--json`) |
-| `tfx auto` | Preview the `tfx-auto` routing decision |
 | `tfx multi` | Local multi-CLI team in tmux + Hub |
-| `tfx swarm` | PRD-based, worktree-isolated work: `plan`, `preflight`, `run`, `list` |
-| `tfx synapse` | Swarm session registry and leases |
+| `tfx synapse` | Session registry and leases |
 | `tfx hub` | Local Hub: `start`, `stop`, `status`, `ensure` |
 | `tfx mcp` | Managed MCP registry: `list`, `sync`, `add`, `remove` |
 | `tfx handoff` | Serialize the current context for another session or host |
 | `tfx cto` | Repo-local authority console: `collect`, `status`, `hygiene` (dry-run) |
-| `tfx review` / `tfx codex-team` | Codex git-diff review / Codex-led team mode |
+| `tfx codex-team` | Codex-led team mode |
+| `bash ~/.claude/scripts/tfx-route.sh code-reviewer "<instruction>"` | Send review to Codex (`codex exec review` via policy) |
 | `tfx stealth-fetch <url>` | Fetch one URL through cloakbrowser (JSON on stdout) |
 | `tfx notion-read`, `tfx why`, `tfx schema`, `tfx list`, `tfx monitor`, `tfx update`, `tfx version` | Notion → Markdown, commit intent trailers, CLI schemas, installed skills, TUI monitor, update, version |
 | `tfx-live` | Live session bridge (same as the `/tfx-live` skill) |
@@ -156,7 +164,7 @@ gets past Claude Code's 600-second Bash limit. Follow up with `--job-status`, `-
 
 **Hub.** A local message bus for teams, remote sessions, MCP tools, and status surfaces. It binds
 to `127.0.0.1:27888` by default (`TFX_HUB_PORT` overrides) and accepts a bearer token from
-`TFX_HUB_TOKEN`. Headless workers from `tfx-auto`, `tfx multi`, and local swarm shards appear in
+`TFX_HUB_TOKEN`. Headless workers from `tfx-auto` and `tfx multi` appear in
 the `claude agents` panel unless you pass `--no-native-bridge-ui`.
 
 **Retry and escalation.** `--retry ralph` loops until done or stuck (three identical failures).
@@ -173,9 +181,9 @@ falling back. Details: [`.claude/rules/tfx-machine-profile.md`](.claude/rules/tf
 dry-run findings. The tray and unused CTO operating commands were removed
 ([ADR-0024](docs/adr/0024-cto-explicit-queries-only.md)). Automatic collection stays off unless `TFX_CTO_AUTO_COLLECT=1` is set ([ADR-0018](docs/adr/0018-cto-auto-behaviors-opt-in.md)).
 
-**Remote hosts.** `/tfx-remote` and `--remote <host>` read hosts from `~/.config/triflux/hosts.json`
-(Windows: `%APPDATA%\triflux\hosts.json`). Run `/tfx-remote setup` to add one, then
-`/tfx-remote spawn <host> "run a security review"`.
+**원격 호스트.** `/tfx-remote`는 `~/.config/triflux/hosts.json`에서 호스트를 읽는다
+(Windows: `%APPDATA%\triflux\hosts.json`). 세션 시작은 `remote-spawn.mjs`의
+`--host <host> --prompt "<요청>"` 옵션을 사용한다. [실행 옵션](skills/tfx-remote/SKILL.md)을 따른다.
 
 ## Architecture
 
@@ -185,12 +193,11 @@ graph TD
     User --> CLI[tfx CLI]
     Skills --> Route[tfx-route.sh]
     Skills --> Live[tfx-live]
-    CLI --> Team["tfx multi · tfx swarm"]
+    CLI --> Team["tfx multi"]
     Route --> Codex[Codex CLI]
     Route --> Agy[Antigravity agy]
     Route --> Claude[Claude Code]
     Team --> Route
-    Team --> WT[(git worktrees)]
     Live -->|UDS or tmux| Sessions[Claude / Codex TUI sessions]
     Route --> Hub["Hub 127.0.0.1:27888"]
     Team --> Hub