---
name: tfx-auto
description: >
  통합 CLI 오케스트레이터 + 실행 스킬 front door. 커맨드 숏컷(단일) + 자동 분류/분해(병렬)
  + 수동 병렬 + 명시 플래그 오버라이드. tfx-route.sh 기반. `--cli`, `--mode`, `--parallel`,
  `--retry`, `--isolation`, `--remote`, `--shape`, `--cli-set`, `--risk-tier` 플래그로 legacy tfx-codex/gemini/
  multi/swarm/fullcycle/persist/autopilot/autoroute/auto-codex 와 consensus/debate/panel 동작을 직접 제어.
  legacy 스킬은 thin alias (Phase 5 v11 삭제 예정).
  '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은
  구현/수정 요청에 사용.
triggers:
  - tfx-auto
  - implement
  - build
  - research
  - brainstorm
  - design
  - test
  - analyze
  - troubleshoot
  - improve
  - cleanup
  - explain
  - document
  - pm
  - reflect
  - estimate
  - spec-panel
  - business-panel
  - index-repo
argument-hint: "<command|task> [args...] [--cli auto|codex|gemini|claude] [--mode quick|deep|consensus] [--risk-tier auto|low|medium|high] [--shape consensus|debate|panel] [--cli-set triad|no-gemini|custom] [--parallel 1|N|swarm] [--retry 0|1|ralph] [--isolation none|worktree] [--remote <host>|none]"
---

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

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

> **Telemetry**
>
> - Skill: `tfx-auto`
> - Description: `통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반. '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은 구현/수정 요청에 사용. CLI 라우팅이 필요한 모든 작업에 적극 활용.`
> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.



### Step 0: 스마트 라우팅 (tfx-auto 진입 시 자동 실행)

preamble에서 routing-weights.json을 읽고, 사용자 입력을 분석하여 dispatch 결정.

```bash
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}"
```

판단 기준 (우선순위 순):

0. **명시 플래그** (최우선, 추론 스킵): 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|gemini` → `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 미구현)

1. **사용자 명시 키워드** (플래그 없을 때):
   - "병렬", "swarm", "PRD 돌려" → `Skill("tfx-swarm")` dispatch
   - "꼼꼼히", "제대로", "deep" → 해당 `tfx-deep-*` dispatch
   - "끝까지", "멈추지마", "ralph" → `Skill("tfx-persist")` dispatch
   - "multi", "팀", "협업" → `Skill("tfx-multi")` dispatch
   - "codex로", "gemini로" → `Skill("tfx-codex")` 또는 `Skill("tfx-gemini")` dispatch

2. **PRD 인자 분석**:
   - PRD 경로 2개 이상 → `Skill("tfx-swarm")` dispatch
   - PRD 1개 + XL 규모 → `Skill("tfx-fullcycle")` dispatch

3. **선호도 가중치** (tiebreaker):
   - USER_PREFERRED_MODE가 있고 가중치 > 0.3이면 제안
   - "[tfx] 사용자 선호: {mode}. 이 모드로 실행할까요?" 1줄 표시
   - 응답 없으면 기본(auto) 진행

4. **기본**: 기존 tfx-auto 워크플로우 그대로 실행

dispatch 시 해당 스킬을 Skill 도구로 호출하고 **이 워크플로우를 종료**한다. dispatch하지 않으면 아래 기존 워크플로우 진행.

라우팅 결정 후 1줄 표시:
```
[tfx] 규모: {S/M/L/XL}, 모드: {mode} ({profile}) — 오버라이드: /tfx-multi, /tfx-swarm 등
```

> **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에 위임하라. 작업이 아무리 사소해도 예외 없음.

## 모드

| 입력 형식 | 모드 | 트리아지 |
|-----------|------|----------|
| `/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/gemini/multi/swarm 등을 이 플래그로 표현할 수 있게 되어, 기존 11개 실행 스킬의 front door 역할을 tfx-auto 가 맡는다.

### 플래그 표

| 플래그 | 값 | 효과 | 위임 엔진 |
|--------|-----|------|----------|
| `--cli` | `auto` (기본) | Codex 분류 후 최적 CLI 선택 | 기존 라우팅 |
| `--cli` | `codex` | Codex 전용 고정. `TFX_CLI_MODE=codex` | tfx-route.sh |
| `--cli` | `gemini` | Gemini 전용 고정. `TFX_CLI_MODE=gemini` | 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 + Gemini | consensus participants |
| `--cli-set` | `no-gemini` | Claude + Codex partial degrade | consensus participants |
| `--cli-set` | `custom` | 기존 3 CLI 내부 subset/repetition 만 허용 | consensus participants |
| `--options` | `"A|B|C"` | debate 비교 대상 | debate normalizer |
| `--criteria` | `"latency|complexity|operability"` | debate 평가 기준 | debate normalizer |
| `--experts` | `"claude:...;codex:...;gemini:..."` | 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 필요) |
| `--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** — 체인 승격 (codex:5.4-mini → codex:gpt-5.5 → claude:sonnet → claude:opus) | 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 |

### `--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 에 상한 부여

### 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` 을 기본으로 사용한다. 커스텀 체인이 필요하면 `.claude/rules/tfx-escalation-chain.md` 로 override 한다.

`DEFAULT_ESCALATION_CHAIN`
1. codex : gpt-5.4-mini
2. codex : gpt-5.5
3. claude : sonnet-4-6
4. claude : opus-4-7

체인 규칙:
- 각 단계에서 `max-iterations` 를 모두 소진하면 다음 CLI/모델로 전이한다.
- 체인 끝까지 소진하면 `BUDGET_EXCEEDED` 와 `reason: "escalation-chain-exhausted"` 를 기록한다.

### 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;gemini: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 호출:

```bash
tfx-auto \
  "<task or topic>" \
  --mode consensus \
  --shape consensus|debate|panel \
  --cli-set triad|no-gemini|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 + Codex + Gemini | 기본값 |
| `no-gemini` | Claude + Codex | Gemini 미가용 degrade |
| `custom` | 기존 3 CLI 내부 subset/repetition 만 허용 | 신규 provider 추가 금지 |

shape 입력 정규화:

```json
{
  "mode": "consensus",
  "shape": "consensus|debate|panel",
  "topic": "...",
  "cli_set": "triad",
  "participants": ["claude", "codex", "gemini"],
  "context": "...",
  "analysis_prompt": "...",
  "shape_input": {}
}
```

shape 별 `shape_input`:

```json
{
  "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"],
      "gemini": ["Michael Porter", "Karl Wiegers"]
    }
  }
}
```

공통 orchestration 루프:

1. ARGUMENTS + 플래그 파싱
2. `--mode consensus` 확인
3. `--shape` 기본값 보정 (`consensus`)
4. shape 별 payload 정규화
5. Claude native + headless Codex/Gemini 동시 dispatch
6. 결과 수집
7. 공통 `meta_judgment` 생성
8. shape renderer 로 markdown/json 출력
9. artifact 저장

공통 메타/렌더링 계약:

- 공통 유틸: `hub/team/consensus-meta.mjs`
- 공통 `meta_judgment` 스키마:

```json
{
  "severity_classification": { "p1": [], "p2": [], "p3": [] },
  "consensus_vs_dispute": { "agreements": [], "conflicts": [] },
  "recommended_action": "merge|FIX_FIRST|close|defer|split",
  "followup_issues": [],
  "mode_specific_meta": {}
}
```

- 공통 root 메타:

```json
{
  "mode": "consensus",
  "shape": "consensus|debate|panel",
  "topic": "...",
  "cli_set": "triad",
  "participants": [
    { "name": "claude", "status": "success" },
    { "name": "codex", "status": "success" },
    { "name": "gemini", "status": "timeout" }
  ],
  "status": "complete|partial|needs_user_input"
}
```

- 필수 markdown 섹션:
  - `shape=consensus`: `합의 결과`, `Consensus Score`, `합의 항목`, `disputed items`, `resolved items`, `user decision needed`, `meta judgment`
  - `shape=debate`: `토론 결과`, `비교 대상`, `평가 기준`, `합의 사항`, `최종 추천`, `리스크 및 완화 방안`, `meta judgment`
  - `shape=panel`: `전문가 패널 보고서`, `패널 구성`, `패널 합의`, `소수 견해`, `핵심 추천`, `미해결 쟁점`, `다음 단계`, `meta judgment`

- artifact 경로:
- markdown: `.omc/artifacts/consensus/<session-id>/<shape>.md`
- json: `.omc/artifacts/consensus/<session-id>/<shape>.json`

shape 별 orchestration 정책:

#### `shape=consensus`

정책:

- 목적: 각 participant 의 findings 를 합의/충돌 항목으로 압축하고 `FIX_FIRST` / `merge` / `defer` 같은 실행 결정을 빠르게 내린다.
- 수집 단위: 옵션 비교가 아니라 finding/assertion 단위다. 동일 결론이라도 근거가 다르면 separate evidence 로 보존한다.
- 합의 판정: 3자 중 2자 이상이 같은 remediation 또는 risk assessment 를 지지하면 provisional agreement 로 분류하고, Claude 가 최종 `resolved_items` 승격 여부를 결정한다.
- 충돌 승격: P1/P2 급 충돌은 score 와 무관하게 `user_decision_needed` 또는 `FIX_FIRST` 로 승격한다. score 가 높아도 안전 이슈를 묻지 않는다.
- degrade: `no-gemini` 또는 partial timeout 시 2자 합의를 허용하되 root meta 의 `status=partial` 과 누락 participant 이유를 반드시 남긴다.

출력 schema 예시:

```json
{
  "mode": "consensus",
  "shape": "consensus",
  "topic": "Phase 5 alias removal readiness",
  "cli_set": "triad",
  "participants": [
    { "name": "claude", "status": "success" },
    { "name": "codex", "status": "success" },
    { "name": "gemini", "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",
          "gemini": "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 예시:

```json
{
  "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": "gemini", "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 는 moderator 로서 panel synthesis 를 담당하지만, 자기 의견을 추가 participant 처럼 중복 집계하지 않는다.

출력 schema 예시:

```json
{
  "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": "gemini", "status": "success" }
  ],
  "status": "complete",
  "shape_output": {
    "panelists": [
      { "cli": "claude", "experts": ["Martin Fowler", "Kent Beck"] },
      { "cli": "codex", "experts": ["Sam Newman", "Gregor Hohpe"] },
      { "cli": "gemini", "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-gemini` | `--cli gemini` |
| `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 |

### 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 |

## 트리아지

**자동 모드:**
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를 수행.

## PRE-CONTEXT GATE

legacy `tfx-fullcycle` 가 맡던 deep/fullcycle 계약은 `tfx-auto --mode deep --parallel 1` 로 이관되었다. Phase 1 시작 전 아래 intake 를 먼저 수행한다.

1. task slug 를 생성한다.
2. 최근 관련 컨텍스트와 산출물을 탐색한다.
3. 현재 작업용 `context-snapshot.md` 를 생성한다.
4. 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** (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)

```bash
# 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차 연속 실패 → 실패 보고 + 성공 결과만 종합.

### 보고 형식

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