---
name: tfx-deep-plan
description: "중요한 기능의 구현 계획을 3자 합의로 수립할 때 사용한다. 'deep plan', '합의 계획', 'ralplan', '철저한 계획', '제대로 설계하고 시작하자' 같은 요청에 사용. 마이크로서비스 도입, 대규모 리팩터링 등 리스크가 큰 작업의 사전 계획에 적극 활용."
triggers:
  - deep plan
  - 합의 계획
  - consensus plan
  - deep-plan
  - 철저한 계획
  - ralplan
argument-hint: "<구현할 기능 설명>"
---

# tfx-deep-plan — Tri-Model Consensus Planning

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


> **Light 버전**: tfx-plan. 기본값. 깊이 수정자 없으면 Light 선택.
3개 모델(Opus 4.6 · GPT 5.4 · Gemini)이 독립 설계 후 교차검증하여 합의된 계획을 도출한다.

---

## 전제조건 프로브 및 Tier Degradation

> **진입 즉시 실행** — 10초 내 가시적 출력을 보장한다. 빈 stdout + exit 0 **금지**.

### 환경 프로브

워크플로우 진입 전, 아래 프로브를 실행하여 가용 환경을 감지한다:

```bash
psmux --version 2>/dev/null && \
  curl -sf http://127.0.0.1:27888/status >/dev/null && \
  codex --version 2>/dev/null && \
  gemini --version 2>/dev/null
```

### Tier 판정

| Tier | 조건 | 실행 방식 |
|------|------|----------|
| **Tier 1** | psmux + Hub + Codex + Gemini 전부 정상 | 기존 headless multi (변경 없음) |
| **Tier 2** | 일부 CLI만 가용 (Codex 또는 Gemini 중 하나) | 가용 CLI + Claude Agent 조합 |
| **Tier 3** | headless 불가 또는 `claude -p` one-shot | Claude Agent only |

```
IF claude -p (one-shot 모드):
  → Tier 3 즉시 fallback

IF psmux 없음 OR Hub 미응답:
  → Tier 3

IF Codex 없음 AND Gemini 없음:
  → Tier 3

IF Codex 없음 OR Gemini 없음:
  → Tier 2

ELSE:
  → Tier 1
```

### Tier 3 진입 시 필수 출력

```
⚠ [Tier 3] headless multi 환경 미충족 — single-model 모드로 실행합니다 (consensus 미적용)
  누락: {missing_components}
  권장: psmux, Hub, Codex CLI, Gemini CLI 설치 후 재실행
```

Tier 3에서는 모든 headless dispatch(`tfx multi ...`)를 **Claude Agent**(subagent)로 대체한다.
Tier 2에서는 누락된 CLI만 Claude Agent로 대체한다.

## HARD RULES

> headless-guard가 이 규칙 위반을 **자동 차단**한다. 우회 불가.

1. **`codex exec` / `gemini -p` 직접 호출 절대 금지**
2. Codex·Gemini 작업은 반드시 아래 형식으로만 실행:
   `Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'cli:프롬프트:역할' --timeout 600")`
3. Claude 작업은 `Agent(run_in_background=true)`
4. Step 2, Step 4에서 **Bash + Agent를 같은 메시지에서 동시 호출**하여 3개 모델 병렬 실행

## MODEL ROLES

| Model | Profile | 역할 | 강점 |
|-------|---------|------|------|
| **Claude Opus 4.6** | Agent(model="opus") | Planner | 전략적 아키텍처 비전, 리스크 통합 판단 |
| **Codex GPT 5.4** | `--assign 'codex:...:architect'` (gpt54_xhigh) | Architect | 구현 설계, API 인터페이스, 파일 구조 |
| **Gemini** | `--assign 'gemini:...:critic'` | Critic | 엣지케이스, 보안 위협, 테스트 전략 |

---

## EXECUTION — 아래 Step을 순서대로 실행하라

사용자 입력을 `TASK`로 참조한다.

### Step 1: 코드베이스 정찰

TASK와 관련된 코드베이스를 파악한다. 결과를 `RECON`으로 기억한다.

도구 호출:
```
Agent(
  subagent_type="Explore",
  model="haiku",
  description="codebase recon",
  prompt="다음 기능과 관련된 코드베이스를 탐색하라: [TASK 삽입]
  보고할 것: (1) 관련 파일/디렉토리 (2) 기존 아키텍처 패턴 (3) 주요 의존성/인터페이스. bullet point로 간결하게."
)
```

### Step 2: Round 1 — 독립 설계 (Anti-Herding)

3개 모델이 서로의 결과를 **보지 않고** 동시에 독립 분석한다.
**아래 2개 도구를 반드시 같은 응답에서 동시에 호출하라.**

#### 2a. Claude Opus — Planner (Agent, background)

```
Agent(
  subagent_type="oh-my-claudecode:architect",
  model="opus",
  run_in_background=true,
  name="planner-r1",
  description="deep-plan R1 Planner",
  prompt="소프트웨어 아키텍트로서 구현 계획을 수립하라.

기능: [TASK 삽입]
코드베이스: [RECON 삽입]

아래 JSON으로 응답하라:
{
  \"vision\": \"설계 방향 1-2문장\",
  \"tasks\": [{\"id\": \"T1\", \"title\": \"...\", \"desc\": \"...\", \"deps\": [], \"complexity\": \"low|med|high\"}],
  \"order\": [\"T1\", \"T2\"],
  \"risks\": [{\"id\": \"R1\", \"desc\": \"...\", \"severity\": \"critical|high|med|low\", \"mitigation\": \"...\"}],
  \"files\": [{\"path\": \"...\", \"action\": \"create|modify|delete\", \"reason\": \"...\"}],
  \"confidence\": 0.85,
  \"reasoning\": \"핵심 결정 이유\"
}"
)
```

#### 2b. Codex + Gemini — Architect + Critic (headless)

`TASK`와 `RECON`을 프롬프트에 삽입하여 아래 Bash를 호출한다.
프롬프트 안의 작은따옴표는 `'\''`로 이스케이프한다.

```
Bash("tfx multi --teammate-mode headless --auto-attach --dashboard \
  --assign 'codex:시니어 엔지니어로서 기술적 설계를 작성하라. 기능: [TASK]. 코드베이스: [RECON]. JSON 응답: {\"architecture\": \"패턴+이유\", \"components\": [{\"name\": \"\", \"responsibility\": \"\", \"interfaces\": []}], \"data_models\": [{\"name\": \"\", \"fields\": [], \"relations\": []}], \"api\": [{\"endpoint\": \"\", \"method\": \"\", \"desc\": \"\"}], \"files\": [{\"path\": \"\", \"purpose\": \"\"}], \"impl_notes\": [], \"confidence\": 0.85}:architect' \
  --assign 'gemini:QA 보안 전문가로서 구현 리스크를 분석하라. 기능: [TASK]. 코드베이스: [RECON]. JSON 응답: {\"edge_cases\": [{\"id\": \"E1\", \"scenario\": \"\", \"impact\": \"\", \"fix\": \"\"}], \"security\": [{\"id\": \"S1\", \"threat\": \"\", \"severity\": \"critical|high|med|low\", \"mitigation\": \"\"}], \"performance\": [{\"id\": \"P1\", \"bottleneck\": \"\", \"optimization\": \"\"}], \"test_strategy\": {\"unit\": [], \"integration\": [], \"edge_case\": []}, \"missing_reqs\": [], \"risk_level\": \"low|med|high|critical\", \"confidence\": 0.85}:critic' \
  --timeout 600")
```

### Step 3: 결과 수집

- `RESULT_PLANNER`: planner-r1 Agent 결과 (SendMessage로 수신 또는 완료 알림 대기)
- `RESULT_ARCHITECT` + `RESULT_CRITIC`: headless stdout JSON에서 각 워커 출력 추출

**실패 워커 처리**: 워커가 실패하면 Claude Agent로 해당 역할을 대체 실행한다.

### Step 4: Round 2 — 교차 검토

각 모델에게 다른 두 모델의 Round 1 결과를 제시하고 수용/수정/반박을 요청한다.
**아래 2개 도구를 반드시 같은 응답에서 동시에 호출하라.**

#### 4a. Claude Opus — 계획 수정 (Agent, background)

```
Agent(
  subagent_type="oh-my-claudecode:critic",
  model="opus",
  run_in_background=true,
  name="planner-r2",
  description="deep-plan R2 cross-review",
  prompt="Round 1 결과를 교차 검토하고 계획을 수정하라.

네 계획: [RESULT_PLANNER 삽입]
Architect(Codex) 설계: [RESULT_ARCHITECT 삽입]
Critic(Gemini) 분석: [RESULT_CRITIC 삽입]

각 항목에 대해:
- ACCEPT: 수용 (이유)
- MODIFY: 부분 수정 (원안→수정안, 이유)
- REJECT: 반박 (근거)

JSON: {\"revisions\": [{\"source\": \"codex|gemini\", \"item\": \"...\", \"action\": \"accept|modify|reject\", \"reason\": \"...\"}], \"updated_plan\": {같은 스키마}}"
)
```

#### 4b. Codex + Gemini — 교차 검토 (headless)

3개 Round 1 결과를 각 프롬프트에 삽입한다. 결과가 길면 핵심만 요약하여 삽입.

```
Bash("tfx multi --teammate-mode headless --auto-attach --dashboard \
  --assign 'codex:교차 검토하라. Planner 계획: [RESULT_PLANNER 요약]. 네 설계: [RESULT_ARCHITECT 요약]. Critic 분석: [RESULT_CRITIC 요약]. 각 항목 ACCEPT/MODIFY/REJECT + 이유. JSON: {\"revisions\": [...], \"updated_design\": {같은 스키마}}:architect' \
  --assign 'gemini:교차 검토하라. Planner 계획: [RESULT_PLANNER 요약]. Architect 설계: [RESULT_ARCHITECT 요약]. 네 분석: [RESULT_CRITIC 요약]. 우려 해소 여부 판단. JSON: {\"resolved\": [...], \"still_concerned\": [...], \"new_concerns\": [...], \"updated_test_strategy\": {...}}:critic' \
  --timeout 600")
```

### Step 5: 합의 점수 산출

Round 2 결과를 모아 Claude가 직접 계산한다 (Agent 불필요):

```
모든 고유 항목에 대해:
  동의 수 = 해당 항목에 동의한 모델 수 (ACCEPT 또는 유사 제안)

  >= 2 동의 → CONSENSUS (합의)
  == 1 동의 → DISPUTED (미합의)

consensus_score = CONSENSUS / 전체_고유_항목 * 100

분기:
  >= 80% → Step 6 확정
  60-79% → Round 3 진행 (미합의 항목만 재토론, 같은 headless 패턴)
  < 60%  → AskUserQuestion으로 핵심 불일치 제시, 사용자 판단 요청
```

### Step 6: 합의된 계획 출력

아래 형식으로 최종 결과를 출력한다:

```markdown
## 합의된 구현 계획: [TASK]

**Consensus**: {score}% | **Rounds**: {count} | **Models**: Opus 4.6 + GPT 5.4 + Gemini

### 설계 방향
{3자 합의된 아키텍처 결정}

### 태스크
| # | 태스크 | 복잡도 | 합의 | 비고 |
|---|--------|--------|------|------|
| T1 | {title} | {complexity} | P:✓ A:✓ C:✓ | {notes} |

### 파일 변경
| 파일 | 작업 | 이유 |
|------|------|------|
| {path} | {action} | {reason} |

### 리스크 & 완화
| 리스크 | 심각도 | 완화 | 합의 |
|--------|--------|------|------|
| {risk} | {severity} | {mitigation} | {n}/3 |

### 테스트 전략 (Critic 주도)
{Gemini가 제안하고 나머지가 합의한 테스트 계획}

### 미합의 사항
| 항목 | Planner(Opus) | Architect(GPT5.4) | Critic(Gemini) |
|------|---------------|---------------------|----------------|
| {item} | {position} | {position} | {position} |
```

---

## ERROR RECOVERY

| 상황 | 대응 |
|------|------|
| headless timeout (600s) | Claude Agent로 해당 역할 대체 실행 |
| Codex 워커 실패 | `Agent(subagent_type="oh-my-claudecode:architect", model="opus")` 대체 |
| Gemini 워커 실패 | `Agent(subagent_type="oh-my-claudecode:critic", model="sonnet")` 대체 |
| consensus < 60% | AskUserQuestion → 사용자 방향 결정 후 해당 방향으로 확정 |
| 프롬프트 quoting 오류 | 작은따옴표 → `'\''` 이스케이프. 줄바꿈 → 공백 치환 |

## TOKEN BUDGET

| Phase | Tokens |
|-------|--------|
| Step 1: Recon (Haiku) | ~2K |
| Step 2: Round 1 (3 parallel) | ~15K |
| Step 4: Round 2 (3 parallel) | ~12K |
| Step 5-6: Consensus + Output | ~3K |
| **Total** | **~25-32K** |