통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반. '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은 구현/수정 요청에 사용. CLI 라우팅이 필요한 모든 작업에 적극 활용.

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

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

MANDATORY RULES

실행: CLI 에이전트는 반드시 Bash("bash ~/.claude/scripts/tfx-route.sh ..."). Claude 네이티브(explore/verifier/test-engineer/qa-tester)만 Agent().

비용: Codex 우선 → Gemini → Claude 최후 수단. claude 선택 전 "Codex로 가능한가?" 재확인.

DAG: SEQUENTIAL/DAG이면 레벨 기반 순차 실행. .omc/context/{sid}/ 생성, context_output 저장, 실패 시 후속 SKIP.

트리아지: Codex exec --full-auto 분류 + Opus 인라인 분해. Agent 스폰 금지.

thorough: -t/--thorough 시 파이프라인 init 필수. 커맨드 숏컷은 항상 quick.

직접 수정 금지: implement/review/analyze 등 커맨드 숏컷 실행 시 절대로 Edit/Write 도구로 직접 코드를 수정하지 마라. 반드시 Bash(tfx-route.sh)를 통해 Codex/Gemini에 위임하라. 작업이 아무리 사소해도 예외 없음.

모드

입력 형식	모드	트리아지
`/implement JWT 추가`	커맨드 숏컷 (quick)	없음 (즉시 실행)
`/tfx-auto "리팩터링 + UI"`	자동 (quick)	Codex 분류 → Opus 분해
`/tfx-auto -t "리팩터링 + UI"`	자동 (thorough)	Codex 분류 → Opus 분해 → Pipeline
`/tfx-auto --thorough "리팩터링"`	자동 (thorough)	`-t` 동일
`/tfx-auto 3:codex "리뷰"`	수동 (quick)	Opus 분해만

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

커맨드 숏컷

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

Codex 직행

커맨드	에이전트	MCP
`implement`	executor	implement
`build`	build-fixer	implement
`research`	document-specialist	analyze
`brainstorm`	analyst	analyze
`design`	architect	analyze
`troubleshoot`	debugger	implement
`cleanup`	executor	implement
`pm`	planner	analyze

2단계: `improve`

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

병렬

커맨드	에이전트들 (병렬, run_in_background=true)	MCP
`analyze`	quality-reviewer + security-reviewer	review
`spec-panel`	architect + analyst + critic	analyze
`business-panel`	analyst + architect	analyze

Gemini 직행

커맨드	에이전트	MCP
`explain`	writer	docs
`document`	writer	docs

Claude 네이티브

커맨드	실행
`test`	`Agent(subagent_type="oh-my-claudecode:test-engineer", model="sonnet")`
`reflect`	`Bash(tfx-route.sh verifier '{PROMPT}' review)` (기본) / `Agent(subagent_type="oh-my-claudecode:verifier", model="sonnet")` (TFX_VERIFIER_OVERRIDE=claude 시)

복합

커맨드	흐름
`estimate`	explore(haiku) → analyst(codex): 영향범위, 복잡도(S/M/L/XL), 리스크
`index-repo`	explore(haiku) × 2 → Write(PROJECT_INDEX.md). mode=quick/update/full

트리아지

자동 모드:

Codex 분류: codex exec --full-auto --skip-git-repo-check → JSON {parts: [{description, agent: "codex|gemini|claude"}]}
Opus 인라인 분해: {graph_type: "INDEPENDENT|SEQUENTIAL|DAG", subtasks: [{id, description, scope, agent, mcp_profile, depends_on, context_output, context_input}]}
실패 시 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

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

조건	실행 경로	엔진
1개 + quick	tfx-auto 직접 실행 (fire-and-forget)	tfx-route.sh
1개 + thorough	tfx-auto 직접 실행 + verify/fix loop	tfx-route.sh
2개+ + quick	headless 직접 실행 (WT 자동 팝업)	headless.mjs
2개+ + thorough	Plan/PRD/Approval 후 → headless + verify/fix	headless.mjs
psmux 미설치 fallback	Native Teams (Agent slim wrapper)	native.mjs

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> 추가

에이전트 매핑

입력	CLI	MCP
codex / executor / build-fixer / spark / debugger / deep-executor	Codex	implement
architect / planner / critic / analyst	Codex (xhigh)	analyze
scientist / document-specialist	Codex	analyze
code-reviewer / security-reviewer / quality-reviewer	Codex (review)	review
gemini / designer / writer	Gemini	docs
explore / test-engineer / qa-tester	Claude native	—
verifier	Codex review (기본) / Claude native (TFX_VERIFIER_OVERRIDE=claude 시)	review / —

MCP 프로필 자동 결정

에이전트	MCP
executor, build-fixer, spark, debugger, deep-executor	implement
architect, planner, critic, analyst, scientist, document-specialist	analyze
code-reviewer, security-reviewer, quality-reviewer	review
designer, writer	docs

결과 파싱

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

exit_code + status	사용할 출력
0 + success	`=== OUTPUT ===` 섹션
124 + timeout	`=== PARTIAL OUTPUT ===`
≠0 + failed	STDERR → Claude fallback

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

에러 레퍼런스

에러	처리
`tfx-route.sh: not found`	tfx-route.sh 생성
`codex/gemini: not found`	npm install -g
timeout / failed (`tfx-route.sh` 결과)	stderr → Claude fallback
N > 10	10 이하로 조정
순환 의존	분해 재시도
컨텍스트 > 32KB	비례 절삭

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/ 모듈 참조.

tfx-auto

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

모드

커맨드 숏컷

Codex 직행

2단계: improve

병렬

Gemini 직행

Claude 네이티브

복합

트리아지

--thorough 모드

단일 태스크 thorough

멀티 태스크 thorough

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

실행

CLI 에이전트 (Codex/Gemini)

Claude 네이티브

에이전트 매핑

MCP 프로필 자동 결정

결과 파싱

실패 처리

보고 형식

필수 조건

에러 레퍼런스

Troubleshooting

상세 레퍼런스

2단계: `improve`