triflux 3.2.0-dev.11 → 3.2.0-dev.13

package/skills/tfx-multi/SKILL.md

@@ -6,17 +6,18 @@ triggers:
 argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'
 ---
 
-# tfx-multi v2.2 — 슬림 래퍼 + 네비게이션 복원 기반 멀티-CLI 팀 오케스트레이터
+# tfx-multi v3 — 파이프라인 기반 멀티-CLI 팀 오케스트레이터
 
 > Claude Code Native Teams의 Shift+Down 네비게이션을 복원한다.
 > Codex/Gemini 워커마다 최소 프롬프트(~100 토큰)의 슬림 Agent 래퍼를 spawn하여 네비게이션에 등록하고,
 > 실제 작업은 `tfx-route.sh`가 수행한다. task 상태는 `team_task_list`를 truth source로 검증한다.
-> v2.2 현재 — 슬림 래퍼 Agent로 Shift+Down 네비게이션 복원, Opus 토큰 77% 절감.
+> v3 — `--quick`(기본, v2.2 호환) + `--thorough`(전체 파이프라인: plan→prd→exec→verify→fix loop).
 
 ## 사용법
 
 ```
-/tfx-multi "인증 리팩터링 + UI 개선 + 보안 리뷰"
+/tfx-multi "인증 리팩터링 + UI 개선 + 보안 리뷰"           # --quick (기본)
+/tfx-multi --thorough "인증 리팩터링 + UI 개선 + 보안 리뷰"  # 전체 파이프라인
 /tfx-multi --agents codex,gemini "프론트+백엔드"
 /tfx-multi --tmux "작업"         # 레거시 tmux 모드
 /tfx-multi status
@@ -60,7 +61,7 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
   (`bin/triflux.mjs` 절대경로는 triflux 패키지 루트 기준)
 - 그 외 → Phase 2 트리아지
 
-**--tmux 감지:** 입력에 `--tmux`가 포함되면 Phase 3-tmux로 분기.
+**--tmux/--psmux 감지:** 입력에 `--tmux` 또는 `--psmux`가 포함되면 Phase 3-mux로 분기. psmux가 primary (Windows).
 
 ### Phase 2: 트리아지 (tfx-auto와 동일)
 
@@ -96,6 +97,32 @@ Bash("codex exec --full-auto --skip-git-repo-check '다음 작업을 분석하
 
 Codex 분류 건너뜀 → Opus가 직접 N개 서브태스크 분해.
 
+### Phase 2.5–2.6: 파이프라인 Plan/PRD (`--thorough` 전용)
+
+> `--quick`(기본) 모드에서는 이 단계를 건너뛰고 Phase 3으로 직행한다.
+> `--thorough` 모드에서만 실행된다.
+
+```
+[--thorough 모드 감지]
+
+Phase 2.5: Plan (Codex architect)
+  1. Hub pipeline 초기화:
+     Bash("node hub/bridge.mjs pipeline-advance --team ${teamName} --status plan")
+     — 또는 createPipeline(db, teamName) 직접 호출
+  2. Codex architect로 작업 분석 + 접근법 설계:
+     bash ~/.claude/scripts/tfx-route.sh architect "${task}" analyze
+  3. 결과를 파이프라인 artifact에 저장:
+     pipeline.setArtifact('plan_path', planOutputPath)
+  4. pipeline advance: plan → prd
+
+Phase 2.6: PRD (Codex analyst)
+  1. Codex analyst로 수용 기준 확정:
+     bash ~/.claude/scripts/tfx-route.sh analyst "${task}" analyze
+  2. 결과를 파이프라인 artifact에 저장:
+     pipeline.setArtifact('prd_path', prdOutputPath)
+  3. pipeline advance: prd → exec
+```
+
 ### Phase 3: Native Teams 실행 (v2.1 개편)
 
 트리아지 결과를 Claude Code 네이티브 Agent Teams로 실행한다.
@@ -212,6 +239,37 @@ Shift+Down으로 다음 워커 (마지막→리드 wrap), Shift+Tab으로 이전
 (Shift+Up은 Claude Code 미지원 — 대부분 터미널에서 scroll-up으로 먹힘)"
 ```
 
+### Phase 3.5–3.7: Verify/Fix Loop (`--thorough` 전용)
+
+> `--quick`(기본) 모드에서는 이 단계를 건너뛰고 Phase 4로 직행한다.
+> `--thorough` 모드에서만 실행된다.
+
+```
+Phase 3.5: Verify (Codex review)
+  1. pipeline advance: exec → verify
+  2. Codex verifier로 결과 검증:
+     bash ~/.claude/scripts/tfx-route.sh verifier "결과 검증: ${task}" review
+     — verifier는 Codex --profile thorough review로 실행됨
+  3. 검증 결과를 파이프라인 artifact에 저장:
+     pipeline.setArtifact('verify_report', verifyOutputPath)
+  4. 통과 → pipeline advance: verify → complete → Phase 5 (cleanup)
+  5. 실패 → Phase 3.6
+
+Phase 3.6: Fix (Codex executor, max 3회)
+  1. pipeline advance: verify → fix
+     — fix_attempt 자동 증가, fix_max(3) 초과 시 전이 거부
+  2. fix_attempt > fix_max → Phase 3.7 (ralph loop) 또는 failed 보고 → Phase 5
+  3. Codex executor로 실패 항목 수정:
+     bash ~/.claude/scripts/tfx-route.sh executor "실패 항목 수정: ${failedItems}" implement
+  4. pipeline advance: fix → exec (재실행)
+  5. → Phase 3 (exec) → Phase 3.5 (verify) 재실행
+
+Phase 3.7: Ralph Loop (fix 3회 초과 시)
+  1. ralph_iteration 증가 (pipeline.restart())
+  2. ralph_iteration > ralph_max(10) → 최종 failed → Phase 5
+  3. fix_attempt 리셋, 전체 파이프라인 재시작 (Phase 2.5 plan부터)
+```
+
 ### Phase 4: 결과 수집 (truth source = team_task_list)
 
 1. 리드가 Step 3c에서 실행한 모든 백그라운드 Bash 프로세스 완료를 대기한다.
@@ -254,9 +312,12 @@ Bash("node hub/bridge.mjs team-task-list --team ${teamName}")
    ```
 5. 종합 보고서를 출력한다.
 
-### Phase 3-tmux: 레거시 tmux 모드
---tmux 플래그 시 기존 v1 방식으로 실행: Bash("node {PKG_ROOT}/bin/triflux.mjs multi --no-attach --agents {agents} \\\"{task}\\\"")
-이후 사용자에게 tmux 세션 연결 안내.
+### Phase 3-mux: 레거시 psmux/tmux 모드
+`--tmux` 또는 `--psmux` 플래그 시 pane 기반 실행. `detectMultiplexer()`가 psmux → tmux → wsl-tmux → git-bash-tmux 순으로 자동 감지.
+Windows에서는 **psmux가 1순위** (ADR-001).
+
+Bash("node {PKG_ROOT}/bin/triflux.mjs multi --no-attach --agents {agents} \\\"{task}\\\"")
+이후 사용자에게 세션 연결 안내.
 
 ## 에이전트 매핑
 > 에이전트 매핑: codex/gemini → tfx-route.sh, claude → Agent(subagent_type) 직접 실행. 상세는 Phase 3c/3d 참조.
@@ -266,14 +327,15 @@ Bash("node hub/bridge.mjs team-task-list --team ${teamName}")
 - **CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1** — settings.json env에 설정 (`tfx setup`이 자동 설정)
 - **codex/gemini CLI** — 해당 에이전트 사용 시
 - **tfx setup** — tfx-route.sh 동기화 + AGENT_TEAMS 자동 설정 (사전 실행 권장)
-- **Hub 활성 상태** — Named Pipe(`\\.\pipe\triflux-{pid}`) 우선, HTTP `127.0.0.1:27888` fallback. `bridge.mjs`가 자동 선택.
+- **Hub 활성 상태** — Named Pipe(`\\.\pipe\triflux-{pid}`) 우선, HTTP `127.0.0.1:27888` fallback. `bridge.mjs`가 자동 선택. Hub 미실행 시 nativeProxy fallback.
+- **멀티플렉서** — psmux(Windows 1순위) / tmux / wsl-tmux / git-bash-tmux 자동 감지 (`--tmux`/`--psmux` 모드)
 - **출력 정책** — preflight는 비동기/요약 출력이 기본이며, 실패 시에만 상세 출력
 
 ## 에러 처리
 
 | 에러 | 처리 |
 |------|------|
-| TeamCreate 실패 / Agent Teams 비활성 | `--tmux` 폴백 (Phase 3-tmux로 전환) |
+| TeamCreate 실패 / Agent Teams 비활성 | `--psmux/--tmux` 폴백 (Phase 3-mux로 전환) |
 | tfx-route.sh 없음 | `tfx setup` 실행 안내 |
 | CLI 미설치 (codex/gemini) | 해당 서브태스크를 claude 워커로 대체 |
 | Codex 분류 실패 | Opus 직접 분류+분해 |
@@ -292,5 +354,6 @@ Bash("node hub/bridge.mjs team-task-list --team ${teamName}")
 | `scripts/tfx-route.sh` | 팀 통합 라우터 (`TFX_TEAM_*`, task claim/complete, send-message, Named Pipe/HTTP bridge) |
 | `hub/team/native.mjs` | Native Teams 래퍼 (프롬프트 템플릿, 팀 설정 빌더) |
 | `hub/team/cli.mjs` | tmux 팀 CLI (`--tmux` 레거시 모드) |
+| `hub/pipeline/` | 파이프라인 상태 기계 (transitions, state, index) — `--thorough` 모드 |
 | `tfx-auto` | one-shot 실행 오케스트레이터 (병행 유지) |
 | `tfx-hub` | MCP 메시지 버스 관리 (tmux 모드용) |