| name | tfx-auto |
| description | 통합 CLI 오케스트레이터이자 실행 스킬 front door. 단일/병렬 구현·수정 작업을 자동 분류해 Codex 우선으로 dispatch 하고, 명시 플래그로 mode/parallel/consensus 등 동작을 오버라이드한다. '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은 구현/수정 요청에 사용. 플래그 상세는 argument-hint, 라우팅 정책은 .claude/rules/tfx-routing.md 참조.
|
| argument-hint | <command|task> [args...] [--cli auto|codex|antigravity|claude] [--mode quick|deep|consensus] [--risk-tier auto|low|medium|high] [--shape consensus|debate|panel] [--cli-set triad|no-antigravity|custom] [--parallel 1|N|swarm] [--retry 0|1|ralph] [--isolation none|worktree] [--remote <host>|none] [--skill <name>] |
tfx-auto — 통합 CLI 오케스트레이터
ARGUMENTS 처리: 이 스킬이 ARGUMENTS: <값>과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
Step 0: 스마트 라우팅 (tfx-auto 진입 시 자동 실행)
preamble에서 routing-weights.json을 읽고, 사용자 입력을 분석하여 dispatch 결정.
SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")
WEIGHTS_FILE="$HOME/.gstack/projects/$SLUG/routing-weights.json"
USER_MODE=""
if [ -f "$WEIGHTS_FILE" ]; then
USER_MODE=$(node -e "
const w=JSON.parse(require('fs').readFileSync('$WEIGHTS_FILE','utf8'));
const m=w.weights?.mode_bias||{};
const top=Object.entries(m).sort((a,b)=>b[1]-a[1])[0];
if(top && top[1]>0.3) console.log(top[0]);
" 2>/dev/null)
fi
echo "USER_PREFERRED_MODE: ${USER_MODE:-none}"
판단 기준 (우선순위 순):
-
명시 플래그 (최우선, 추론 스킵): ARGUMENTS 에 --cli/--mode/--risk-tier/--shape/--cli-set/--parallel/--retry/--isolation/--remote 플래그가 있으면 분류/추론을 건너뛰고 플래그 값대로 즉시 dispatch. 자세한 플래그 동작은 아래 "플래그 오버라이드" 섹션 참조.
--parallel swarm → tfx-swarm 엔진 위임 (PRD 필요)--parallel N → tfx-multi 엔진 위임 (headless)--cli codex|antigravity → TFX_CLI_MODE 설정 + 단일 실행--mode deep → -t/--thorough 동일 동작 (pipeline init)--risk-tier low|medium|high → risk-tier 기준으로 verification 강도와 mode 결정--mode ... 명시 시 --risk-tier 는 무시 (mode 우선)--mode consensus --shape debate|panel → prompt ensemble fold 경로--retry ralph → stderr 경고 후 bounded 3회 degrade (Phase 2 미구현)
-
사용자 명시 키워드 (플래그 없을 때):
- "병렬", "swarm", "PRD 돌려" →
--parallel swarm --mode consensus --isolation worktree
- "꼼꼼히", "제대로", "deep" →
--mode deep
- "끝까지", "멈추지마", "ralph" →
--retry ralph
- "multi", "팀", "협업" →
--parallel N --mode deep
- "codex로", "antigravity로" →
--cli codex 또는 --cli antigravity
-
PRD 인자 분석:
- PRD 경로 2개 이상 →
--parallel swarm --mode consensus --isolation worktree
- PRD 1개 + XL 규모 →
--mode deep --parallel 1
-
선호도 가중치 (tiebreaker):
- USER_PREFERRED_MODE가 있고 가중치 > 0.3이면 제안
- "[tfx] 사용자 선호: {mode}. 이 모드로 실행할까요?" 1줄 표시
- 응답 없으면 기본(auto) 진행
-
기본: 기존 tfx-auto 워크플로우 그대로 실행
정규화된 플래그를 현재 tfx-auto 실행 인자로 적용한다. legacy Skill 이름은 compatibility alias 문서에서만 다룬다.
라우팅 결정 후 1줄 표시:
[tfx] 규모: {S/M/L/XL}, 모드: {mode} ({profile}) — 오버라이드: /tfx-multi, /tfx-swarm 등
MANDATORY RULES
- 실행: CLI 에이전트는 반드시
Bash("bash ~/.claude/scripts/tfx-route.sh ..."). Claude 네이티브(explore/verifier/test-engineer/qa-tester)만 Agent().
- 비용/편향 분리: 실행 워커 비용은 Codex/Antigravity 우선으로 낮추되, consensus/debate/panel에서는 Claude/Opus를 최후수단이 아니라 counter-bias outvoice로 둔다. Claude가 실행을 맡는 경우는 명시적
--cli claude, Claude-native host role, 또는 fallback뿐이다.
2-a. Anti-bias triad: Triflux의 본가 목적은 Codex↔Claude 균형으로 단일 모델 편향을 줄이는 것이다. triad는 Claude/Opus(counter-bias outvoice) + Codex(implementation/reality check) + Antigravity(product/UX auxiliary)를 보존하고, disputed/minority view를 삭제하지 않는다.
2-b. Claude effort: Claude lane은 Claude Code CLI의 --model과 --effort를 사용한다. Triflux의 CLI_EFFORT/profile 값은 low|medium|high|xhigh|max Claude effort로 매핑한다(ultracode는 claude --effort 값이 아니라 하니스 모드이므로 기본 effort로 매핑된다). skill 문서가 모델 ID를 하드코딩하지 않는다.
- 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/Antigravity에 위임하라. 작업이 아무리 사소해도 예외 없음.
모드
| 입력 형식 | 모드 | 트리아지 |
|---|
/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)이 적용된다.
플래그 오버라이드 (명시 제어, Phase 2 v10.9.33+)
ARGUMENTS 에 아래 플래그가 있으면 Step 0 스마트 라우팅의 내부 추론을 건너뛰고 값대로 즉시 dispatch 한다. legacy tfx-codex/antigravity/multi/swarm 등을 이 플래그로 표현할 수 있게 되어, 기존 11개 실행 스킬의 front door 역할을 tfx-auto 가 맡는다.
플래그 표
| 플래그 | 값 | 효과 | 위임 엔진 |
|---|
--cli | auto (기본) | Codex 분류 후 최적 CLI 선택 | 기존 라우팅 |
--cli | codex | Codex 전용 고정. TFX_CLI_MODE=codex | tfx-route.sh |
--cli | antigravity | Antigravity CLI 고정. TFX_CLI_MODE=antigravity | tfx-route.sh |
--cli | claude | Claude native 에이전트만 (CLI 호출 없음) | Agent() |
--mode | quick (기본) | fire-and-forget, plan/verify 오버헤드 없음 | 직접 실행 |
--mode | deep | pipeline init → plan → PRD → verify → fix loop | -t/--thorough 동일 |
--mode | consensus | 3-CLI 합의 family 실행 | tfx-auto consensus root |
--risk-tier | auto (기본) | changed files 기준 자동 분류 후 mode/verify 강도 결정 | risk matrix |
--risk-tier | low | quick mode + verify skip | 기존 default 와 동일 |
--risk-tier | medium | quick mode + verify (lint + test 만) | bounded verify |
--risk-tier | high | deep mode + full verify/fix loop | pipeline + full verify |
--shape | consensus (기본) | findings 합의/충돌 판정 | consensus renderer |
--shape | debate | 옵션 비교 + 점수화 + 최종 추천 | debate renderer |
--shape | panel | 전문가 roster 기반 시뮬레이션 | panel renderer |
--cli-set | triad (기본) | Claude + Codex + Antigravity | consensus participants |
--cli-set | no-antigravity | Claude/Opus outvoice + Codex partial degrade | consensus participants |
--cli-set | custom | 기존 3 CLI 내부 subset/repetition 만 허용 | consensus participants |
--options | `"A | B | C"` |
--criteria | `"latency | complexity | operability"` |
--experts | "claude:...;codex:...;antigravity:..." | panel roster override | panel normalizer |
--analysis-prompt-file | <path> | consensus family 공통 분석 프롬프트 주입 | consensus normalizer |
--parallel | 1 (기본) | 단일 워커 | tfx-route.sh |
--parallel | N | 로컬 headless 병렬 (cwd 공유) | tfx multi |
--parallel | swarm | worktree 격리 + 다기기 | tfx swarm (PRD 필요) |
--no-native-bridge-ui | true | headless worker의 Claude agents UI 노출을 비활성화 | tfx multi |
--retry | 0 | 자동 재시도 없음 | — |
--retry | 1 (기본) | bounded verify → fix loop 3회 | — |
--retry | ralph | Phase 3 — true ralph state machine (unlimited, stuck detector 3회 중단) | retry-state-machine.mjs |
--retry | auto-escalate | Phase 3 — 프로필 기반 체인 승격 | retry-state-machine.mjs |
--isolation | none (기본) | cwd 공유 | — |
--isolation | worktree | shard별 .codex-swarm/wt-*/ 격리 | --parallel swarm 자동 강제 |
--remote | none (기본) | 로컬만 | — |
--remote | <host> | hosts.json 의 host 로 shard 분배 | --parallel swarm 전용 |
--lead | claude (기본) | 분류·메타판단을 Claude 가 담당 | tfx-auto 내장 |
--lead | codex | 분류·메타판단을 Codex 에 위임 (tfx-auto-codex 의미 일부 흡수) | tfx-route.sh |
--no-claude-native | false (기본) | Claude native sub-agent 경로 유지 | — |
--no-claude-native | true | Claude native 경로 disable, CLI 기반 worker 강제 | tfx-route.sh |
--max-iterations | 0 (기본, unlimited) | --retry ralph/auto-escalate 상한 | retry-state-machine.mjs |
--skill | <name> | skills/<name>/SKILL.md 본문을 codex/agy 프롬프트 앞에 주입 (TFX_INJECT_SKILL). 미지정 시 no-op | tfx-route.sh |
--risk-tier 계약
- 기본값은
auto.
--mode 가 명시되면 --risk-tier 는 무시된다. mode 가 최종 우선순위다.--risk-tier 만 명시되면 tier 가 mode 를 자동 결정한다.low → quick mode + verify skip.medium → quick mode + verify (lint + test 만).high → deep mode + full verify/fix loop.auto → 아래 변경 분류 매트릭스로 tier 를 계산한다.- auto 분류 입력은 staged + unstaged 전체 변경 파일 기준이다. untracked 파일도 relative path 집합에 포함해 판정한다.
자동 분류 매트릭스
hub/lib/risk-tier.mjs 의 classifyRiskTier({ changedFiles }) 계약을 기준으로 적용한다. 판정 순서는 high → medium → low → default 이다.
| tier | 규칙 | 판정 기준 |
|---|
high | 아키텍처/배포/운영 핵심 경로 | hub/, scripts/, .claude/rules/, bin/, .github/ prefix 중 하나라도 매칭 |
medium | 빌드/설정/런타임 영향 | 다중 파일 변경, package.json, .yml/.yaml, .toml, config/, hooks/ 매칭 |
low | 문서/텍스트/테스트-only | 단일 파일 + non-config (.md/.txt 만) 또는 .test 파일만 |
| default | 안전 fallback | 어떤 low/high 패턴에도 안 맞으면 medium |
플래그 검증
--mode ... + --risk-tier ... 동시 지정 → mode 우선. risk-tier 는 informational 로그만 남기고 실행 결정에는 사용하지 않음--parallel swarm + PRD 없음 → PRD 자동 생성 또는 사용자에게 경로 질의--parallel 1 + --isolation worktree → warning, isolation=none 으로 강제--remote <host> + --parallel != swarm → warning, remote 무시--shape 미지정 + --mode consensus → shape=consensus--shape 지정 + --mode != consensus → warning 또는 error. shape 는 consensus family 에서만 유효--cli-set custom + 기존 3 CLI 외 participant 지정 → 즉시 error. silent fallback 금지--retry ralph → true ralph state machine (Phase 3, retry-state-machine.mjs)--retry auto-escalate → CLI 승격 체인 (Phase 3)--max-iterations N (N>0) → ralph/auto-escalate 에 상한 부여--skill <name> → TFX_INJECT_SKILL=<name> 로 tfx-route.sh 에 전달. 스킬 파일 부재 시 warning 후 주입 생략 (fail-open, 작업은 계속)
스킬 주입 (--skill <name>)
codex/agy 워커 프롬프트 앞에 등록된 스킬의 방법론을 주입하는 opt-in 프레임워크. 설계 근거는 decision-skill-passing (omc 레퍼런스 + codex/agy 네이티브 스킬 조사):
- 메커니즘:
--skill <name> → tfx-route.sh TFX_INJECT_SKILL=<name>. skills/<name>/SKILL.md 본문을 --- SKILL: <name> (apply this methodology...) --- delimited block 으로 프롬프트 앞에 prepend. codex·agy 레인 공통 (CLI-agnostic, prepend_skill).
- 기본 off: 미지정이면 no-op → 현행 동작 그대로. 회귀 위험 없음.
- 파싱 안전: prepend 는
printf/cat → temp file 만 사용. codex 는 argv -- 뒤, agy 는 stdin printf %s 로 전달되므로 $(codex)·₩/백슬래시(agy) 같은 특수문자를 셸 재확장 없이 리터럴 보존. 스킬 본문을 그대로 넘겨도 깨지지 않음.
- 네이티브 스킬을 안 쓰는 이유: codex
$skill-name//name 슬래시와 agy /name 은 둘 다 인터랙티브 TUI 전용 → headless one-shot 에서 named-skill 강제 호출 불가 (미문서). 그래서 prose 주입을 채택 (레퍼런스 omc 도 role .md 를 raw prepend, 네이티브 회피).
커맨드→스킬 매핑 (tfx-auto convention, opt-in)
tfx-auto 가 커맨드/agent 별로 주입할 스킬을 고를 때 쓰는 권고 테이블. 기본은 매핑 없음 (명시 --skill 만 작동) — 부적절한 스킬이 모든 프롬프트에 새는 것을 막는다. 프로젝트가 명시적으로 활성화할 때만 아래를 적용해 --skill 을 자동 부여한다.
| 커맨드/agent | 권고 스킬 | 비고 |
|---|
| (기본) | 없음 | explicit --skill 우선 |
| 프로젝트 정의 | 프로젝트가 지정 | 활성화 시 tfx-auto 가 해당 --skill set |
매핑된 스킬 파일이 없으면 prepend_skill 이 warning 후 주입을 생략한다 (fail-open). 존재하지 않는 매핑을 "주입됨"으로 가정하지 않는다.
agy anti-overclaim (자동, agy 레인 전용)
agy 레인은 TFX_AGY_ANTI_OVERCLAIM(기본 on) 으로 완료/grounding 규율 블록을 프롬프트 END 에 자동 append (append_agy_anti_overclaim). Gemini 3.x 과신(AA-Omniscience 실측: 정확도 53-56% 대비 환각률 88-91%) 대응:
- fresh 증거 없이 done/fixed/passing 주장 금지.
- 검증 불가 시
No Info / 확인 불가 후 중단 (날조 금지).
- 추론은 주어진 context 로, confident guessing 보다 accurate abstention 우선.
부정 제약은 Gemini 3 공식 가이드대로 END 배치하고 blanket "do not guess" 는 역효과라 피한다. opt-out: TFX_AGY_ANTI_OVERCLAIM=0.
Retry state machine 계약 (legacy autoroute / persist 이관)
--retry ralph 와 --retry auto-escalate 는 모두 hub/team/retry-state-machine.mjs 를 사용한다.
--retry ralph 는 true ralph state machine 으로 동작한다. 기본값 --max-iterations 0 은 unlimited 의미다.- 실행 상태는
.omc/state/ralph-<sessionId>.json 에 append 저장한다. resumeFromStateFile() 로 재개 가능해야 한다.
- 동일
failureReason 이 3회 연속 반복되면 stuckCounter 가 올라가고 STUCK 으로 중단한다.
--retry auto-escalate 는 DEFAULT_ESCALATION_CHAIN 을 기본으로 사용한다. 커스텀 체인이 필요하면 .triflux/config/escalation-chain.json 으로 override 한다.
DEFAULT_ESCALATION_CHAIN
정확한 모델 ID는 .claude/rules/tfx-escalation-chain.md와 CLI 프로필 설정을 따른다.
- codex : 표준 코드/추론 프로필 (profile optional; 미지정 시 config 기본값)
- claude : 최종 수단 프로필
커스텀 체인은 .triflux/config/escalation-chain.json 으로 override 한다.
체인 규칙:
- 각 단계에서
max-iterations 를 모두 소진하면 다음 CLI/모델로 전이한다.
- 체인 끝까지 소진하면
BUDGET_EXCEEDED 와 reason: "escalation-chain-exhausted" 를 기록한다.
- 체인 항목은 optional
profile 필드를 지원한다. 값이 있으면 파싱/전달만 하고, 없으면 기존 CLI/config 기본 동작을 따른다.
Codex lead 계약 (legacy auto-codex 이관)
--cli codex --lead codex --no-claude-native 조합이 tfx-auto-codex 의 canonical 표현이다.
--cli codex 는 CLI 워커를 Codex 로 고정한다.--lead codex 는 분류·메타판단도 Codex 가 담당하게 한다.--no-claude-native 는 Claude native sub-agent 경로를 끄고 CLI 기반 worker 만 허용한다.- 하위 호환 env
TFX_NO_CLAUDE_NATIVE=1 는 계속 읽되, 플래그가 우선한다.
사용 예시
/tfx-auto "리팩터링" --mode deep # = 기존 -t/--thorough
/tfx-auto "구현" --cli codex # = legacy tfx-codex
/tfx-auto "문서만 수정" --risk-tier low # = quick + verify skip
/tfx-auto "설정/빌드 손봄" --risk-tier medium # = quick + lint/test verify
/tfx-auto "hub 라우팅 개편" --risk-tier high # = deep + full verify/fix loop
/tfx-auto "병렬" --parallel N --mode deep # = legacy tfx-multi 기본값
/tfx-auto "PRD 실행" --parallel swarm # = legacy tfx-swarm
/tfx-auto "REST vs GraphQL" --mode consensus --shape debate
/tfx-auto "모놀리스 분해 전략" --mode consensus --shape panel --experts "claude:Fowler|Beck;codex:Newman|Hohpe;antigravity:Porter|Wiegers"
Consensus shape 계약 (Phase 4a — ensemble fold)
--mode consensus 는 orchestration family 를 뜻하고, --shape 는 그 family 내부의 출력/해석 surface 를 뜻한다.
--mode consensus --shape consensus → 기존 tfx-consensus--mode consensus --shape debate → 기존 tfx-debate--mode consensus --shape panel → 기존 tfx-panel
canonical 호출:
tfx-auto \
"<task or topic>" \
--mode consensus \
--shape consensus|debate|panel \
--cli-set triad|no-antigravity|custom \
[--experts "..."] \
[--options "..."] \
[--criteria "..."] \
[--analysis-prompt-file <path>]
shape 의미:
--shape | 의미 | orchestration 차이 |
|---|
consensus | 3-CLI findings 합의/충돌 판정 | 기존 tfx-consensus 의미 |
debate | 옵션 비교 + ranking/recommendation | 옵션/criteria renderer |
panel | 전문가 역할 시뮬레이션 | expert roster + panel renderer |
--cli-set 규약:
| 값 | 의미 | 비고 |
|---|
triad | Claude/Opus outvoice + Codex + Antigravity | 기본값 |
no-antigravity | Claude/Opus outvoice + Codex | Antigravity 미가용 degrade |
custom | 기존 3 CLI 내부 subset/repetition 만 허용 | 신규 provider 추가 금지 |
shape 입력 정규화:
{
"mode": "consensus",
"shape": "consensus|debate|panel",
"topic": "...",
"cli_set": "triad",
"participants": ["claude", "codex", "antigravity"],
"context": "...",
"analysis_prompt": "...",
"shape_input": {}
}
shape 별 shape_input:
{
"consensus": {
"analysis_prompt_file": "optional-path",
"resolution_threshold": 70
},
"debate": {
"options": ["A", "B", "C"],
"criteria": ["latency", "complexity", "operability"]
},
"panel": {
"experts": {
"claude": ["Martin Fowler", "Kent Beck"],
"codex": ["Sam Newman", "Gregor Hohpe"],
"antigravity": ["Michael Porter", "Karl Wiegers"]
}
}
}
공통 orchestration 루프:
- ARGUMENTS + 플래그 파싱
--mode consensus 확인--shape 기본값 보정 (consensus)- shape 별 payload 정규화
- Claude/Opus outvoice + headless Codex/Antigravity 동시 dispatch
- 결과 수집
- 공통
meta_judgment 생성
- shape renderer 로 markdown/json 출력
- artifact 저장
공통 메타/렌더링 계약:
- 공통 유틸:
hub/team/consensus-meta.mjs
- 공통
meta_judgment 스키마:
{
"severity_classification": { "p1": [], "p2": [], "p3": [] },
"consensus_vs_dispute": { "agreements": [], "conflicts": [] },
"recommended_action": "merge|FIX_FIRST|close|defer|split",
"followup_issues": [],
"mode_specific_meta": {}
}
{
"mode": "consensus",
"shape": "consensus|debate|panel",
"topic": "...",
"cli_set": "triad",
"participants": [
{ "name": "claude", "status": "success" },
{ "name": "codex", "status": "success" },
{ "name": "antigravity", "status": "timeout" }
],
"status": "complete|partial|needs_user_input"
}
shape 별 orchestration 정책:
shape=consensus
정책:
- 목적: 각 participant 의 findings 를 합의/충돌 항목으로 압축하고
FIX_FIRST / merge / defer 같은 실행 결정을 빠르게 내린다.
- 수집 단위: 옵션 비교가 아니라 finding/assertion 단위다. 동일 결론이라도 근거가 다르면 separate evidence 로 보존한다.
- 합의 판정: 3자 중 2자 이상이 같은 remediation 또는 risk assessment 를 지지하면 provisional agreement 로 분류하고, Claude/Opus outvoice가 반론을 제공하고 lead가 최종
resolved_items 승격 여부를 결정한다.
- 충돌 승격: P1/P2 급 충돌은 score 와 무관하게
user_decision_needed 또는 FIX_FIRST 로 승격한다. score 가 높아도 안전 이슈를 묻지 않는다.
- degrade:
no-antigravity 또는 partial timeout 시 2자 합의를 허용하되 root meta 의 status=partial 과 누락 participant 이유를 반드시 남긴다.
출력 schema 예시:
{
"mode": "consensus",
"shape": "consensus",
"topic": "Phase 5 alias removal readiness",
"cli_set": "triad",
"participants": [
{ "name": "claude", "status": "success" },
{ "name": "codex", "status": "success" },
{ "name": "antigravity", "status": "success" }
],
"status": "complete",
"shape_output": {
"consensus_score": 82,
"consensus_items": [
"15 legacy alias can be removed after usage reaches zero",
"alias usage gate must be verified before physical deletion"
],
"disputed_items": [
{
"item": "Delete tfx-psmux-rules in same PR as remote aliases",
"positions": {
"claude": "defer",
"codex": "proceed",
"antigravity": "defer"
},
"severity": "p2"
}
],
"resolved_items": [
"Delete consensus/debate/panel aliases after routing docs are updated"
],
"user_decision_needed": [],
"meta_judgment": {
"severity_classification": {
"p1": [],
"p2": [
"Remote alias removal ordering still disputed"
],
"p3": []
},
"consensus_vs_dispute": {
"agreements": [
"Phase 5 requires zero alias usage before deletion"
],
"conflicts": [
"Remote alias deletion bundling"
]
},
"recommended_action": "FIX_FIRST",
"followup_issues": [
"Confirm remote migration docs before deleting remote aliases"
],
"mode_specific_meta": {
"threshold_passed": true,
"needs_resolution_round": false
}
}
}
}
shape=debate
정책:
- 목적: 2개 이상 옵션을 criteria 기반으로 비교하고 최종 추천안 1개를 만든다.
- 수집 단위: option x criterion matrix 다. participant 자유서술을 그대로 합치지 말고 각 옵션의 장단점/score 를 정규화한다.
- 라운드 운영: 1차 독립 평가 후 상위 2개 옵션 간 반론 라운드 1회를 허용한다.
--max-rounds 로 늘리더라도 기본은 2라운드 이하로 제한한다.
- 추천 규칙: 단순 다수결이 아니라 weighted ranking 을 사용하되, P1 risk 가 있는 옵션은 총점이 높아도 최종 추천에서 제외 가능하다.
- criteria 누락: 사용자가 criteria 를 주지 않으면 latency, implementation complexity, operability, migration risk 를 기본 축으로 채운다.
출력 schema 예시:
{
"mode": "consensus",
"shape": "debate",
"topic": "REST vs GraphQL for triflux remote control API",
"cli_set": "triad",
"participants": [
{ "name": "claude", "status": "success" },
{ "name": "codex", "status": "success" },
{ "name": "antigravity", "status": "success" }
],
"status": "complete",
"shape_output": {
"options": [
"REST",
"GraphQL"
],
"criteria": [
"latency",
"complexity",
"operability",
"migration_risk"
],
"scorecard": [
{
"option": "REST",
"total_score": 84,
"criterion_scores": {
"latency": 86,
"complexity": 88,
"operability": 83,
"migration_risk": 79
}
},
{
"option": "GraphQL",
"total_score": 68,
"criterion_scores": {
"latency": 64,
"complexity": 55,
"operability": 70,
"migration_risk": 83
}
}
],
"agreements": [
"REST is simpler to roll out incrementally"
],
"disputes": [
"GraphQL may reduce future overfetching but adds current operational complexity"
],
"recommendation": {
"winner": "REST",
"decision_type": "majority_with_risk_adjustment",
"why": "REST wins on complexity and operability while avoiding a new query layer"
},
"meta_judgment": {
"severity_classification": {
"p1": [],
"p2": [
"GraphQL rollout would widen migration scope"
],
"p3": []
},
"consensus_vs_dispute": {
"agreements": [
"REST is lower risk for the current phase"
],
"conflicts": [
"Long-term schema flexibility payoff"
]
},
"recommended_action": "merge",
"followup_issues": [
"Re-evaluate GraphQL after remote surface stabilizes"
],
"mode_specific_meta": {
"rounds_run": 2,
"winning_margin": 16
}
}
}
}
shape=panel
정책:
- 목적: 전문가 roster 기반으로 관점이 다른 조언을 구조화하고 majority/minority view 를 명시한다.
- roster 규칙:
--experts 미지정 시 기본 roster 를 채우되 각 CLI 가 서로 다른 전문성을 대표하도록 배분한다. 동일 전문가를 중복 배정하지 않는다.
- 발언 구조: participant raw answer 를 그대로 이어붙이지 말고
expert -> thesis -> supporting evidence -> concern -> recommendation 구조로 정리한다.
- 합의 규칙: panel 은 unanimity 보다 "majority view + minority view + open questions" 보존이 중요하다. minority 가 P1/P2 를 제기하면 별도
open_questions 로 승격한다.
- moderator 역할: Claude/Opus outvoice 는 moderator 로서 panel synthesis 를 담당하지만, 자기 의견을 추가 participant 처럼 중복 집계하지 않는다.
출력 schema 예시:
{
"mode": "consensus",
"shape": "panel",
"topic": "How should triflux remove 15 legacy aliases in Phase 5?",
"cli_set": "triad",
"participants": [
{ "name": "claude", "status": "success" },
{ "name": "codex", "status": "success" },
{ "name": "antigravity", "status": "success" }
],
"status": "complete",
"shape_output": {
"panelists": [
{ "cli": "claude", "experts": ["Martin Fowler", "Kent Beck"] },
{ "cli": "codex", "experts": ["Sam Newman", "Gregor Hohpe"] },
{ "cli": "antigravity", "experts": ["Michael Porter", "Karl Wiegers"] }
],
"majority_view": "Delete routing aliases first, then consensus family, then remote aliases after usage and docs converge",
"minority_views": [
{
"position": "Delete remote aliases together with consensus family in one release",
"supporters": ["Sam Newman"],
"severity": "p3"
}
],
"open_questions": [
"Should tfx-psmux-rules be deleted in the same PR as tfx-remote-setup/spawn?"
],
"action_items": [
"Verify alias-usage.log aggregate is zero",
"Update README and routing docs before physical deletion"
],
"meta_judgment": {
"severity_classification": {
"p1": [],
"p2": [
"Docs drift would make remote alias deletion unsafe"
],
"p3": []
},
"consensus_vs_dispute": {
"agreements": [
"Usage-zero gate is mandatory"
],
"conflicts": [
"Exact ordering of remote alias deletion"
]
},
"recommended_action": "split",
"followup_issues": [
"Run a repo-wide reference-zero audit before remote alias deletion"
],
"mode_specific_meta": {
"panel_size": 6,
"moderator": "claude",
"majority_strength": "5/6"
}
}
}
}
Legacy 스킬 매핑
| legacy 스킬 | tfx-auto 등가 플래그 |
|---|
tfx-autopilot | (기본) |
tfx-autoroute | --retry auto-escalate (Phase 3) |
tfx-fullcycle | --mode deep --parallel 1 |
tfx-persist | --retry ralph (Phase 3, unlimited) |
tfx-codex | --cli codex |
tfx-antigravity | --cli antigravity |
tfx-auto-codex | --cli codex --lead codex --no-claude-native (Phase 3) |
tfx-consensus | --mode consensus |
tfx-debate | --mode consensus --shape debate |
tfx-panel | --mode consensus --shape panel |
tfx-multi | --parallel N --mode deep |
tfx-swarm | --parallel swarm --mode consensus --isolation worktree |
tfx-codex-swarm | --parallel swarm --cli codex --isolation worktree |
legacy 스킬은 thin alias 로 유지. 호출 시 stderr 에 [deprecated] {legacy} -> use: tfx-auto --{flag} {value} 1회 출력, stdout 머리부에 [DEPRECATED] 마커를 남기고 .omc/state/alias-usage.log 에 usage 를 append 한다. Phase 5 (v11) 에 물리 삭제.
Phase 5 삭제 게이트:
- 코드 검색에서 alias 파일 자체만 남아야 함
- integration + golden test 100% pass
.omc/state/alias-usage.log 7일 집계 0
파싱 규칙
- 플래그는 ARGUMENTS 어느 위치에든 올 수 있다. 순서 자유.
- 플래그 값은 공백 뒤 다음 토큰 (예:
--cli codex). = 문법 (--cli=codex) 도 허용.
- 알 수 없는 플래그는 무시 후 warning. 작업 설명으로 포함.
- 플래그 제외한 나머지 텍스트를 작업 설명
<task> 로 추출.
설계 근거: .triflux/plans/phase2-tfx-run-design.md (GitHub Issue #112 umbrella Phase 2 산출물).
커맨드 숏컷
커맨드명 매칭 시 트리아지 없이 즉시 실행. 패턴: 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 |
Antigravity 직행
| 커맨드 | 에이전트 | 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|antigravity|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를 수행.
PRE-CONTEXT GATE
legacy tfx-fullcycle 가 맡던 deep/fullcycle 계약은 tfx-auto --mode deep --parallel 1 로 이관되었다. Phase 1 시작 전 아래 intake 를 먼저 수행한다.
- task slug 를 생성한다.
- 최근 관련 컨텍스트와 산출물을 탐색한다.
- 현재 작업용
context-snapshot.md 를 생성한다.
- ambiguity 가 높으면
.tfx/plans/interview-* 산출물을 우선 재사용한다.
권장 저장 경로:
.tfx/fullcycle/{run-id}/context-snapshot.md
STATE & ARTIFACT CONTRACT
deep/fullcycle 경로는 phase 별 산출물과 상태를 남긴다.
- 기본 아티팩트 디렉토리:
.tfx/fullcycle/{run-id}/
- 최소 산출물:
context-snapshot.md, expanded-spec.md, implementation-plan.md, execution-summary.md, qa-findings.md, validation-decision.md, state.json
state.json 최소 필드: current phase, started_at, last_successful_phase, retry_count, failure_reason- 재실행 시 전체를 처음부터 다시 돌리지 않는다.
state.json 을 읽고 마지막 미완료 phase 부터 resume 한다.
- QA / Validation 재시도는 해당 phase 만 다시 실행한다.
deep/fullcycle 추가 규칙:
task slug 와 context-snapshot.md 는 항상 같이 생성한다./deep-interview 또는 기존 .tfx/plans/interview-{timestamp}.md 산출물이 있으면 raw prompt 대신 재사용한다.- 동일한 실패 / 동일한 에러가 3회 반복되면 무한 루프를 중단하고 근본 이슈 보고서를 남긴다.
CLEANUP & CANCEL RULES
- 성공 시
state.json 을 complete 상태로 기록하고 orphan state 가 남지 않도록 정리한다.
- 취소/비정상 종료 시에도 마지막 phase,
failure_reason, 재개 힌트를 남겨 다음 실행에서 resume 가능해야 한다.
- cleanup 은 상태를 무조건 삭제하는 것이 아니라, 성공/취소 여부가 판별되도록 메타데이터를 남긴 뒤 정리한다.
멀티 태스크 라우팅 (트리아지 후)
트리아지 결과에 따라 실행 경로 결정.
v6.0.0부터 CLI 워커는 Lead-Direct Headless 가 기본. Agent 래퍼 불필요.
OS별 primary multiplexer는 macOS/Linux = tmux, Windows = psmux다. macOS에서 psmux 미설치는 fallback 사유가 아니다.
| 조건 | 실행 경로 | 엔진 |
|---|
| 1개 + quick | tfx-auto 직접 실행 (fire-and-forget) | tfx-route.sh |
| 1개 + thorough | tfx-auto 직접 실행 + verify/fix loop | tfx-route.sh |
| 2개+ + quick | headless 직접 실행 (Windows: WT/psmux / macOS·Linux: tmux) | headless.mjs |
| 2개+ + thorough | Plan/PRD/Approval 후 → headless + verify/fix | headless.mjs |
| primary multiplexer 없음 | Native/in-process fallback | native.mjs |
MANDATORY: 2개+ 서브태스크 시 headless 엔진 필수
Agent() 백그라운드나 Bash(tfx-route.sh) 개별 호출로 대체 금지.
반드시 아래 Bash("tfx multi ...") 명령으로 headless 엔진에 위임한다.
headless dispatch는 기본적으로 Claude agents native bridge UI에 노출된다. 필요 시 --no-native-bridge-ui 로 opt-out 한다.
전환 방법:
thorough = args에 -t 또는 --thorough 포함
if subtasks.length >= 2:
if OS primary multiplexer 사용 가능(macOS/Linux tmux, Windows psmux):
→ Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --native-bridge-ui --assign 'cli:prompt:role' ...")
→ if thorough: verify → fix loop
else:
→ fallback: tfx-multi Native/in-process fallback
else:
if thorough:
→ Pipeline init → Plan → PRD → Approval → 직접 실행 → Verify → Fix loop
else:
→ tfx-auto 직접 실행 (아래)
실행
CLI 에이전트 (Codex/Antigravity)
Bash("bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp_profile}", run_in_background=true)
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 / spark | Codex (high; 복잡 구현은 deep-executor/xhigh) | implement |
| debugger / deep-executor | Codex (xhigh) | implement |
| build-fixer | Codex (low) | implement |
| architect / planner / critic / analyst | Codex (xhigh) | analyze |
| scientist / document-specialist | Codex | analyze |
| code-reviewer / security-reviewer / quality-reviewer | Codex (review) | review |
| antigravity / designer / writer | Antigravity | 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 | antigravity: curl -fsSL https://antigravity.google/cli/install.sh | bash
에러 레퍼런스
| 에러 | 처리 |
|---|
tfx-route.sh: not found | tfx-route.sh 생성 |
codex/antigravity: 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/ 모듈 참조.
