tfx-auto — 통합 CLI 오케스트레이터

ARGUMENTS 처리: 이 스킬이 ARGUMENTS: <값>과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.

MANDATORY RULES

1. 실행: CLI 에이전트는 반드시 Bash("bash ~/.claude/scripts/tfx-route.sh ..."). Claude 네이티브(explore/verifier/test-engineer/qa-tester)만 Agent().
2. 비용: Codex 우선 → Gemini → Claude 최후 수단. claude 선택 전 "Codex로 가능한가?" 재확인.
3. DAG: SEQUENTIAL/DAG이면 레벨 기반 순차 실행. .omc/context/{sid}/ 생성, context_output 저장, 실패 시 후속 SKIP.
4. 트리아지: Codex exec --full-auto 분류 + Opus 인라인 분해. Agent 스폰 금지.
5. thorough: -t/--thorough 시 파이프라인 init 필수. 커맨드 숏컷은 항상 quick.
6. 직접 수정 금지: implement/review/analyze 등 커맨드 숏컷 실행 시 절대로 Edit/Write 도구로 직접 코드를 수정하지 마라. 반드시 Bash(tfx-route.sh)를 통해 Codex/Gemini에 위임하라. 작업이 아무리 사소해도 예외 없음.

모드

tfx-auto는 --quick이 기본. 커맨드 숏컷·단일 실행에서 plan/verify 오버헤드가 불필요하기 때문. 멀티 태스크 시 tfx-multi로 전환되면 tfx-multi의 기본값(--thorough)이 적용된다.

커맨드 숏컷

커맨드명 매칭 시 트리아지 없이 즉시 실행. 패턴: Bash("bash ~/.claude/scripts/tfx-route.sh {에이전트} '{PROMPT}' {MCP}").

Codex 직행

2단계: improve

1단계 code-reviewer '{PROMPT}' review → 사용자 승인 → 2단계 executor '리뷰 반영: {요약}' implement

병렬

Gemini 직행

Claude 네이티브

복합

트리아지

자동 모드:

1. Codex 분류: codex exec --full-auto --skip-git-repo-check → JSON {parts: [{description, agent: "codex|gemini|claude"}]}
2. Opus 인라인 분해: {graph_type: "INDEPENDENT|SEQUENTIAL|DAG", subtasks: [{id, description, scope, agent, mcp_profile, depends_on, context_output, context_input}]}
3. 실패 시 Opus가 직접 분류+분해

수동 모드 (N:agent_type): Codex 분류 건너뜀 → Opus가 N개 서브태스크 분해. N > 10 거부.

--thorough 모드

-t 또는 --thorough 플래그 시 파이프라인 기반 실행. 커맨드 숏컷에서는 무시된다.

분기점은 "실행 전략"이지 "계획"이 아님:

TRIAGE
  │
  ├─ [thorough] → PIPELINE INIT(plan) → PLAN → PRD → [APPROVAL]
  │                                                      │
  │                                      ┌───────────────┤
  │                                      │               │
  │                                  [1 task]        [2+ tasks]
  │                                      │               │
  │                                  AUTO 직접 실행   TEAM EXEC (multi Phase 3)
  │                                      │               │
  │                                      └───────┬───────┘
  │                                              │
  │                                          VERIFY → FIX loop → COMPLETE
  │
  └─ [quick] → [1 task] → fire-and-forget
               [2+ tasks] → TEAM EXEC → COLLECT → CLEANUP

단일 태스크 thorough

1. Bash("node hub/bridge.mjs pipeline-init --team ${sid}") — 파이프라인 초기화 (phase: plan)
2. Plan: Codex architect → 결과를 pipeline.writePlanFile() 저장
3. PRD: Codex analyst → acceptance criteria 확정
4. pipeline_advance_gated → [Approval Gate] → 사용자 승인 대기
5. Exec: tfx-auto 직접 실행 (아래 "실행" 섹션)
6. Verify: Codex verifier → 검증
7. 실패 시 Fix loop (최대 3회) → Exec 재실행
8. Complete

멀티 태스크 thorough

Plan/PRD/Approval은 tfx-auto에서 실행, 그 후 tfx-multi Phase 3로 전환. 서브태스크 배열 + thorough: true 신호를 함께 전달하여 multi 측에서 verify/fix를 수행.

멀티 태스크 라우팅 (트리아지 후)

트리아지 결과에 따라 실행 경로 결정. v6.0.0부터 CLI 워커는 Lead-Direct Headless (psmux)가 기본. Agent 래퍼 불필요.

MANDATORY: 2개+ 서브태스크 시 headless 엔진 필수 Agent() 백그라운드나 Bash(tfx-route.sh) 개별 호출로 대체 금지. 반드시 아래 Bash("tfx multi ...") 명령으로 headless 엔진에 위임한다.

전환 방법:

thorough = args에 -t 또는 --thorough 포함

if subtasks.length >= 2:
  if psmux 설치됨:
    → Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'cli:prompt:role' ...")
    → if thorough: verify → fix loop
  else:
    → fallback: tfx-multi Phase 3 Native Teams (Agent slim wrapper)
else:
  if thorough:
    → Pipeline init → Plan → PRD → Approval → 직접 실행 → Verify → Fix loop
  else:
    → tfx-auto 직접 실행 (아래)

실행

CLI 에이전트 (Codex/Gemini)

# Level 0 / INDEPENDENT
Bash("bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile}", run_in_background=true)

# Level 1+ (컨텍스트 의존) — 4번째=timeout(빈값), 5번째=context_file
Bash("bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile} '' .omc/context/{sid}/combined-{tid}.md", run_in_background=true)

Claude 네이티브

Agent(subagent_type="oh-my-claudecode:{agent}", model="{model}", prompt="{prompt}", run_in_background=true)
# 컨텍스트 있으면 prompt에 <prior_context>...</prior_context> 추가

에이전트 매핑

MCP 프로필 자동 결정

결과 파싱

여기서 failed는 tfx-route.sh/CLI 종료 결과를 뜻한다. Claude Code TaskUpdate 상태값이 아니다.

OUTPUT 추출: echo "$result" | sed -n '/^=== OUTPUT ===/,/^=== /{/^=== OUTPUT ===/d;/^=== /d;p}'

실패 처리

1차 → Agent(subagent_type="oh-my-claudecode:executor", model="sonnet") fallback. 2차 연속 실패 → 실패 보고 + 성공 결과만 종합.

보고 형식

## tfx-auto 완료
**모드**: {auto|manual} | **그래프**: {type} | **레벨**: {N}
| # | 서브태스크 | Agent | CLI | MCP | 레벨 | 상태 | 시간 |
### 워커 {n}: {제목}
(출력 요약)
### Token Savings Report
(node ~/.claude/scripts/token-snapshot.mjs report {session-id})

필수 조건

• ~/.claude/scripts/tfx-route.sh (필수)
• codex: npm install -g @openai/codex | gemini: npm install -g @google/gemini-cli

에러 레퍼런스

Claude Code TaskUpdate를 사용할 때는 status: "failed"를 쓰지 않는다. 실패 보고는 status: "completed" + metadata.result: "failed"로 표현한다.

Troubleshooting

/tfx-doctor 진단 | /tfx-doctor --fix 자동 수정 | /tfx-doctor --reset 캐시 초기화

상세 레퍼런스

DAG 알고리즘, 컨텍스트 머지 규칙, 토큰 스냅샷, 보고서 상세는 scripts/tfx-route.sh 내부 주석 및 hub/ 모듈 참조.