Search everything...

Skill

multi-ai-roundtable

Use when a project needs diverse expert perspectives before execution - launches a multi-AI roundtable that calls real codex-cli/gemini-cli binaries via Bash (Claude agent fallback only on quota/missing-CLI/repeated-failure), synthesizes into a roadmap, then executes with parallel agents

npx claudepluginhub vp-k/multi-ai-roundtable

Tool Access

This skill is limited to using the following tools:

ReadWriteEditBashGlobGrepAgentWebSearchAskUserQuestion

Preview

복잡한 프로젝트(책 집필, 아키텍처 설계, 콘텐츠 기획 등)에서 **외부 AI CLI 바이너리(`codex`, `gemini`)의 실제 호출**로 다각도 관점을 수집하고, 합의된 로드맵을 기반으로 **병렬 에이전트**로 실행하는 워크플로우. 모드: `codex`(기본) / `gemini` / `both`.

SKILL.md

Similar Skills

cache-components

139.4k

Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.

cache-components

pdf

131.6k

Processes PDFs: extracts text/tables/images, merges/splits/rotates pages, adds watermarks, creates/fills forms, encrypts/decrypts, OCRs scans. Activates on PDF mentions or output requests.

11 files

document-skills

Stats

Stars1

Forks0

Last CommitApr 27, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

multi-ai-roundtable | multi-ai-roundtable | ClaudePluginHub

Back to Skills

Skill

multi-ai-roundtable

From multi-ai-roundtable

npx claudepluginhub vp-k/multi-ai-roundtable

Tool Access

This skill is limited to using the following tools:

ReadWriteEditBashGlobGrepAgentWebSearchAskUserQuestion

Preview

SKILL.md

Multi-AI Roundtable: 다자 토론 → 로드맵 → 병렬 실행

Overview

복잡한 프로젝트(책 집필, 아키텍처 설계, 콘텐츠 기획 등)에서 외부 AI CLI 바이너리(codex, gemini)의 실제 호출로 다각도 관점을 수집하고, 합의된 로드맵을 기반으로 병렬 에이전트로 실행하는 워크플로우. 모드: codex(기본) / gemini / both.

Core principle: 한 AI의 편향을 진짜 다른 모델의 의견으로 극복하고, 합의된 계획을 병렬 실행으로 빠르게 구현한다. Claude Agent 툴 폴백은 CLI 미설치·quota 초과·반복 실패 시의 예외 경로일 뿐.

Announce at start: "multi-ai-roundtable 스킬을 사용하여 외부 AI CLI 토론 → 로드맵 → 병렬 실행을 진행합니다. (모드: <codex|gemini|both>)"

When to Use

기존 콘텐츠/코드를 대규모로 재편성해야 할 때
설계 결정에 다양한 관점이 필요할 때
"이게 최선인가?"라는 질문이 드는 복잡한 프로젝트
책 집필, 커리큘럼 설계, API 아키텍처, 프로젝트 구조 등 구조적 결정이 핵심인 작업

Don't use when:

단순 버그 수정이나 기능 추가
이미 합의된 계획이 있을 때
1~2개 파일 수정으로 끝나는 작업

The Process

Phase 1: 현황 분석 (Context Gathering)
    ↓
Phase 2: 3자 토론 (Multi-AI Roundtable)
    ↓
Phase 3: 로드맵 합성 (Roadmap Synthesis)
    ↓
Phase 4: 병렬 실행 (Parallel Execution)
    ↓
Phase 5: 검증 및 정리 (Verification & Cleanup)

Phase 1: 현황 분석

대상 프로젝트의 현재 상태를 파악한다.

1-1. 파일 구조 파악

# 프로젝트 파일 목록
find . -name "*.md" -o -name "*.dart" -o -name "*.ts" | head -50

1-2. 핵심 파일 읽기

기존 콘텐츠/코드의 품질, 톤, 구조를 파악한다. 최소 3~5개 파일을 읽어 패턴을 이해한다.

1-3. 분석 요약 작성

다음 항목을 정리하여 Phase 2에 전달한다:

## 현황 요약
- **현재 구조**: 파일/챕터/모듈 목록
- **강점**: 잘 되어 있는 부분
- **약점/누락**: 빠져 있거나 보강이 필요한 부분
- **톤/스타일**: 기존 콘텐츠의 문체나 코드 컨벤션
- **파일 수**: N개 (규모 판단용)

Phase 2: 다자 토론 (실제 CLI 호출)

선택된 외부 AI CLI(codex / gemini)를 반드시 Bash 툴로 직접 실행하여 입장을 수집한다. Claude Agent 툴은 폴백 경로에서만 허용된다 (CLI 미설치 / quota 초과 / 반복 실패). 본 단계의 결정성은 이 플러그인의 핵심 가치이므로 절대 위반 금지.

자세한 호출 규약·재시도·quota 감지·폴백 표기는 ${CLAUDE_PLUGIN_ROOT}/rules/shared-rules.md의 "Phase 2 — 외부 CLI 호출 규약" 섹션을 단일 출처로 따른다.

2-0. 모드 결정

/roundtable 슬래시 명령에서 전달된 모드(또는 사용자 의도)를 다음과 같이 매핑한다:

모드	호출 대상
`codex` (기본)	codex CLI만
`gemini`	gemini CLI만
`both`	codex + gemini 병렬

역할 배정

AI	역할	핵심 지시
codex-cli (CLI 바이너리)	비판적 분석가	"문제점을 찾아라. 빠진 것은? 리스크는?"
gemini-cli (CLI 바이너리)	창의적 대안 제시자	"다른 접근법은? 차별화 포인트는? 놓친 관점은?"
Claude (이 세션)	중재자 + 합성자	수집된 입장을 종합하여 최종 합의안 도출

2-1. 작업 폴더 생성 및 사전 점검

mkdir -p .roundtable
# 선택된 CLI에 대해 존재 확인
command -v codex  >/dev/null 2>&1 || echo "MISSING:codex"
command -v gemini >/dev/null 2>&1 || echo "MISSING:gemini"

MISSING:<cli>가 출력되면 AskUserQuestion으로 사용자에게 (a) Claude 폴백으로 진행 / (b) 중단하고 설치 후 재시도 중 선택을 요청한다.

2-2. 프롬프트 파일 작성

Phase 1의 현황 요약을 포함하여 다음 두 파일을 Write 툴로 생성한다 (선택된 모드에 해당하는 것만).

.roundtable/codex-prompt.md:

당신은 비판적 분석가입니다. 다음 프로젝트의 현황을 분석하고 문제점을 지적하세요.

## 현황 요약
[Phase 1 결과를 그대로 붙여넣기]

## 분석 요청
1. 구조적 문제점 (순서, 누락, 중복)
2. 내용 품질 이슈 (깊이, 정확성, 실용성)
3. 타겟 독자/사용자 관점에서의 갭
4. 리스크 요소 (저작권, 기술적 한계, 시장성 등)
5. 구체적인 개선 우선순위 (상/중/하)

구체적인 근거와 함께 비판하세요. 마크다운 형식으로 응답하세요.

.roundtable/gemini-prompt.md:

당신은 창의적 대안 제시자입니다. 다음 프로젝트를 한 단계 격상시킬 전략적 제안을 하세요.

## 현황 요약
[Phase 1 결과를 그대로 붙여넣기]

## 제안 요청
1. 놓친 관점이나 기회
2. 구체적인 재편성/재구성 안 (표 형태)
3. 차별화 포인트 및 시장 포지셔닝
4. 단계별 실행 로드맵

파격적이되 실현 가능한 제안을 하세요. 마크다운 형식으로 응답하세요.

2-3. CLI 실행 (결정적, 재시도·폴백 포함)

모드별 실행 패턴:

codex: 아래 codex 블록 1회 호출 (포그라운드)
gemini: 아래 gemini 블록 1회 호출 (포그라운드)
both: 두 블록을 별개 Bash 호출로 만들고 둘 다 run_in_background=true로 띄운 뒤 BashOutput으로 완료 폴링

codex 실행 블록:

codex exec --skip-git-repo-check --sandbox read-only - \
  < .roundtable/codex-prompt.md \
  > .roundtable/codex-output.md \
  2> .roundtable/codex-stderr.log
echo "CODEX_EXIT=$?"

gemini 실행 블록:

gemini --approval-mode plan --output-format text \
  -p "$(cat .roundtable/gemini-prompt.md)" \
  > .roundtable/gemini-output.md \
  2> .roundtable/gemini-stderr.log
echo "GEMINI_EXIT=$?"

각 호출의 결과 분기 (shared-rules.md "재시도 정책" 단일 출처):

exit == 0
   └─ 결과 채택. .roundtable/<cli>-output.md를 입장으로 사용.

exit != 0
   └─ stderr 로그에 quota 패턴 매칭? (regex는 shared-rules.md 참조)
        ├─ Yes → 재시도 금지. 즉시 2-5 Claude 폴백.
        └─ No  → 2~3초 대기 후 1회 재시도.
                  ├─ 재시도 성공 → 결과 채택.
                  └─ 재시도 실패 → 2-5 Claude 폴백.

stderr 검사 명령:

grep -iE 'quota|rate.?limit|429|exceeded|RESOURCE_EXHAUSTED|too many requests|insufficient_quota' \
  .roundtable/codex-stderr.log >/dev/null 2>&1 && echo "QUOTA:codex"

2-4. 출력 정합성 점검

각 .roundtable/<cli>-output.md가 비어있지 않고 최소한의 분석 형태(헤더·항목 등)를 갖췄는지 Read로 확인. 비어있거나 에러 메시지만 있으면 일반 실패로 분류하여 폴백.

2-5. Claude 폴백 (예외 경로)

CLI 미설치(사용자가 폴백 동의), quota 감지, 또는 반복 실패 시에만 발동.

Agent 툴을 사용해 누락된 입장을 보완한다:

description: "<codex|gemini> 폴백 — <비판적 분석가|창의적 대안 제시자> 관점"
prompt: 위 2-2의 해당 프롬프트 본문 + 다음 안내 1줄 추가

"참고: 이는 <codex|gemini> CLI 사용 불가(사유: <quota|미설치|반복실패>)로 인한 Claude 폴백 분석입니다."
두 입장 모두 폴백이면 run_in_background=true로 병렬

폴백으로 생성된 파일 최상단에 다음 헤더를 반드시 추가:

> ⚠️ 폴백: <codex|gemini> CLI 사용 불가 (사유: <quota|미설치|반복실패>) — Claude로 대체 분석

2-6. 토론 라운드

라운드	내용
1라운드	각자 독립 분석 (위 2-3 ~ 2-5로 입장 수집 완료)
2라운드	필요 시 상대 입장에 대한 반론/보완 (각 CLI에 추가 호출. 동일하게 결정적 흐름 적용)
3라운드	최종 합의 시도 (필요 시)

최대 3라운드로 제한 — 그 이상은 수렴하지 않는다. 라운드를 추가할 때마다 .roundtable/<cli>-prompt-rN.md / <cli>-output-rN.md 식으로 파일 분리.

2-7. 합의 판단 기준

상황	처리
두 입장 동의 (또는 단일 모드에서 명확)	즉시 채택
한쪽만 동의	Claude가 근거를 평가하여 결정
양쪽 반대	제3의 절충안 도출 또는 사용자에게 판단 요청

Phase 3: 로드맵 합성

Claude가 중재자로서 토론 결과를 하나의 실행 가능한 로드맵으로 합성한다.

로드맵 문서 작성

${CLAUDE_PLUGIN_ROOT}/templates/roadmap-template.md 템플릿을 참조하여 작성한다.

핵심 구성요소:

결론 — 한 문단 요약
최종 구조 — 합의된 항목 목록 (표 형태)
항목별 상세 — 유지/축소/보강/신설 구분
기존→신규 매핑 — 어떤 것이 어디로 이동하는지
차별화 포인트 — 합의된 강점
토론 과정 요약 — 쟁점별 합의 결과 (표 형태). Phase 2에서 Claude 폴백이 발동된 입장은 해당 칸에 (Claude 폴백 — <사유>) 표기 필수. 사용자가 결과 출처를 명확히 알 수 있어야 함.

사용자 확인

반드시 사용자에게 로드맵을 보여주고 승인을 받는다:

"이 로드맵으로 실행해도 될까요?"
수정 요청이 있으면 반영 후 재확인
승인 없이 Phase 4로 넘어가지 않는다

Phase 4: 병렬 실행

승인된 로드맵을 기반으로 병렬 에이전트를 실행한다.

4-1. 작업 분할 원칙

원칙	설명
독립성	각 에이전트가 서로 다른 파일을 수정한다
자족성	필요한 모든 정보를 프롬프트에 포함한다
일관성	톤, 포맷, 용어 기준을 프롬프트에 명시한다
적정 크기	에이전트 하나당 파일 1~2개가 적정

4-2. 에이전트 프롬프트 필수 포함 사항

[역할 설명]

## 작업 대상
파일 경로: [출력 파일 경로]
제목: [제목]
소속: [Part/Section 정보]

## 기존 콘텐츠 (있을 경우)
[기존 내용 전문 — 요약이나 생략 금지]

## 변경 사항
1. [구체적 변경 1]
2. [구체적 변경 2]

## 통일 포맷
[프로젝트 전체에 적용되는 포맷 규칙]

## 톤/스타일 가이드
[기존 콘텐츠의 문체나 코드 스타일 — 예시 포함]

## 교차 참조
[다른 항목과의 연결 관계]

## 출력 요구사항
- 전체 내용을 작성할 것 (요약/생략 금지)

4-3. 실행 배치 전략

배치 1: 독립 작업들 (최대 6~12개 에이전트, run_in_background=true)
    ↓ 완료 대기
배치 2: 배치 1 결과 참조 필요한 작업 (있을 경우)
    ↓ 완료 대기
배치 3: 통합 작업 (부록, 인덱스, 교차 참조 등)

4-4. 진행 상황 추적

에이전트 완료 알림이 올 때마다 표로 상태를 업데이트하고 사용자에게 보고한다:

| 항목 | 작업 내용 | 상태 |
|------|-----------|------|
| Item 1 | ... | ✅ 완료 |
| Item 2 | ... | ⏳ 실행 중 |

Phase 5: 검증 및 정리

5-1. 파일 정리

# 기존 파일을 _old/ 폴더로 이동 (삭제하지 않음!)
mkdir -p _old/
mv [기존파일들] _old/

절대 기존 파일을 삭제하지 않는다. 반드시 _old/로 백업한다.

5-2. 검증 체크리스트

모든 에이전트가 파일을 정상 생성했는가
항목 간 교차 참조가 올바른가 (다음/이전 링크)
용어가 전체적으로 일관되는가
통일 포맷이 모든 항목에 적용되었는가
기존 파일이 _old/에 백업되었는가

5-3. 최종 보고

## 실행 완료 보고

### 파일 구조
[최종 파일 트리]

### 주요 변경 요약
- 신설: [새로 만든 항목]
- 재배치: [순서가 바뀐 항목]
- 보강: [내용이 추가된 항목]
- 수정: [수정된 사항]

### 차별화 포인트
[로드맵에서 합의된 차별화 포인트 재확인]

Customization Points

AI 역할 변경

프로젝트 유형에 따라 역할을 조정할 수 있다:

프로젝트 유형	codex-cli 역할	gemini-cli 역할
책/콘텐츠	구조 비평가	차별화 전략가
API 설계	보안/성능 감사	DX/UX 제안자
코드 아키텍처	기술 부채 분석	확장성 설계자
커리큘럼	교육학 비평	학습 경험 설계

규모 조절

프로젝트 규모	토론 라운드	병렬 에이전트 수
소 (파일 5개 이하)	1라운드	3~5개
중 (파일 10~15개)	2라운드	6~10개
대 (파일 20개 이상)	2~3라운드	배치별 8~12개

codex-cli / gemini-cli 없이 사용 (자동 폴백)

CLI가 설치되지 않았거나 quota가 소진된 경우, Phase 2의 폴백 경로(2-5)가 자동으로 발동한다:

사전 점검에서 MISSING:<cli> 감지 시 사용자에게 폴백/중단 선택 요청
실행 중 quota 패턴 감지 시 재시도 없이 즉시 Claude Agent 툴로 대체
일반 에러 시 1회 재시도 후 실패하면 Claude Agent 툴로 대체
모든 폴백 결과에는 > ⚠️ 폴백: ... 헤더와 토론 요약 표 (Claude 폴백) 표기가 붙음

중요: 폴백은 예외 경로다. CLI가 설치·작동 가능한 환경에서는 절대 폴백을 기본값으로 쓰지 않는다 (사용자가 진짜 다중 모델 관점을 받지 못하게 됨).

Red Flags

Never:

토론 없이 바로 실행하지 않는다 — 편향된 결과가 나온다
에이전트 프롬프트에 기존 콘텐츠를 생략하지 않는다 — 톤/스타일 불일치가 생긴다
기존 파일을 삭제하지 않는다 — 반드시 _old/로 백업한다
3라운드 이상 토론하지 않는다 — 수렴하지 않으면 사용자 판단을 받는다
한 에이전트에 3개 이상 파일을 맡기지 않는다 — 품질이 떨어진다
사용자 승인 없이 Phase 4를 시작하지 않는다
Phase 2에서 CLI가 작동 가능한데 Agent 툴(Claude 역할극)로 우회하지 않는다 — 사용자가 사실상 단일 모델 결과를 받게 된다 (폴백은 미설치/quota/반복실패 시에만)
quota 에러를 만나도 재시도하지 않는다 — 같은 에러가 반복되며 시간만 낭비된다. 즉시 폴백

Always:

Phase 1에서 기존 콘텐츠를 충분히 읽는다
Phase 2에서 선택된 모드(codex / gemini / both)에 맞는 실제 CLI 바이너리를 Bash 툴로 호출한다
CLI 호출 전 command -v로 존재를 확인한다
폴백이 발동되면 결과 파일과 로드맵 토론 요약에 폴백 사유를 명시한다
토론 결과에서 합의/비합의 사항을 명확히 구분한다
로드맵을 사용자에게 확인받은 후 실행한다
에이전트 프롬프트에 톤/스타일/포맷 가이드를 포함한다
실행 진행 상황을 실시간으로 사용자에게 보고한다

Example: 아카펠라 책 12챕터 재편성

Phase 1: 기존 10챕터 초안 + 외래어 기준표 분석 Phase 2: codex-cli(구조 비판) + gemini-cli(차별화 전략) → 2라운드 토론 Phase 3: 12챕터 + 부록 로드맵 합성, 사용자 확인 Phase 4: 13개 에이전트 병렬 실행 (Ch1~Ch12 + 부록) Phase 5: 기존 파일 _old/ 이동, 외래어 기준표 업데이트, 최종 보고

결과: 10챕터 → 12챕터 재편성, 신설 2챕터, 전 챕터 보강, 부록 추가 — 약 30분 소요

Similar Skills

cache-components

139.4k

cache-components

pdf

131.6k

Processes PDFs: extracts text/tables/images, merges/splits/rotates pages, adds watermarks, creates/fills forms, encrypts/decrypts, OCRs scans. Activates on PDF mentions or output requests.

11 files

document-skills

Stats

Stars1

Forks0

Last CommitApr 27, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

Multi-AI Roundtable: 다자 토론 → 로드맵 → 병렬 실행

Overview

Announce at start: "multi-ai-roundtable 스킬을 사용하여 외부 AI CLI 토론 → 로드맵 → 병렬 실행을 진행합니다. (모드: <codex|gemini|both>)"

When to Use

기존 콘텐츠/코드를 대규모로 재편성해야 할 때
설계 결정에 다양한 관점이 필요할 때
"이게 최선인가?"라는 질문이 드는 복잡한 프로젝트
책 집필, 커리큘럼 설계, API 아키텍처, 프로젝트 구조 등 구조적 결정이 핵심인 작업

Don't use when:

단순 버그 수정이나 기능 추가
이미 합의된 계획이 있을 때
1~2개 파일 수정으로 끝나는 작업

The Process

Phase 1: 현황 분석 (Context Gathering)
    ↓
Phase 2: 3자 토론 (Multi-AI Roundtable)
    ↓
Phase 3: 로드맵 합성 (Roadmap Synthesis)
    ↓
Phase 4: 병렬 실행 (Parallel Execution)
    ↓
Phase 5: 검증 및 정리 (Verification & Cleanup)

Phase 1: 현황 분석

대상 프로젝트의 현재 상태를 파악한다.

1-1. 파일 구조 파악

# 프로젝트 파일 목록
find . -name "*.md" -o -name "*.dart" -o -name "*.ts" | head -50

1-2. 핵심 파일 읽기

기존 콘텐츠/코드의 품질, 톤, 구조를 파악한다. 최소 3~5개 파일을 읽어 패턴을 이해한다.

1-3. 분석 요약 작성

다음 항목을 정리하여 Phase 2에 전달한다:

## 현황 요약
- **현재 구조**: 파일/챕터/모듈 목록
- **강점**: 잘 되어 있는 부분
- **약점/누락**: 빠져 있거나 보강이 필요한 부분
- **톤/스타일**: 기존 콘텐츠의 문체나 코드 컨벤션
- **파일 수**: N개 (규모 판단용)

Phase 2: 다자 토론 (실제 CLI 호출)

자세한 호출 규약·재시도·quota 감지·폴백 표기는 ${CLAUDE_PLUGIN_ROOT}/rules/shared-rules.md의 "Phase 2 — 외부 CLI 호출 규약" 섹션을 단일 출처로 따른다.

2-0. 모드 결정

/roundtable 슬래시 명령에서 전달된 모드(또는 사용자 의도)를 다음과 같이 매핑한다:

모드	호출 대상
`codex` (기본)	codex CLI만
`gemini`	gemini CLI만
`both`	codex + gemini 병렬

역할 배정

AI	역할	핵심 지시
codex-cli (CLI 바이너리)	비판적 분석가	"문제점을 찾아라. 빠진 것은? 리스크는?"
gemini-cli (CLI 바이너리)	창의적 대안 제시자	"다른 접근법은? 차별화 포인트는? 놓친 관점은?"
Claude (이 세션)	중재자 + 합성자	수집된 입장을 종합하여 최종 합의안 도출

2-1. 작업 폴더 생성 및 사전 점검

mkdir -p .roundtable
# 선택된 CLI에 대해 존재 확인
command -v codex  >/dev/null 2>&1 || echo "MISSING:codex"
command -v gemini >/dev/null 2>&1 || echo "MISSING:gemini"

MISSING:<cli>가 출력되면 AskUserQuestion으로 사용자에게 (a) Claude 폴백으로 진행 / (b) 중단하고 설치 후 재시도 중 선택을 요청한다.

2-2. 프롬프트 파일 작성

Phase 1의 현황 요약을 포함하여 다음 두 파일을 Write 툴로 생성한다 (선택된 모드에 해당하는 것만).

.roundtable/codex-prompt.md:

당신은 비판적 분석가입니다. 다음 프로젝트의 현황을 분석하고 문제점을 지적하세요.

## 현황 요약
[Phase 1 결과를 그대로 붙여넣기]

## 분석 요청
1. 구조적 문제점 (순서, 누락, 중복)
2. 내용 품질 이슈 (깊이, 정확성, 실용성)
3. 타겟 독자/사용자 관점에서의 갭
4. 리스크 요소 (저작권, 기술적 한계, 시장성 등)
5. 구체적인 개선 우선순위 (상/중/하)

구체적인 근거와 함께 비판하세요. 마크다운 형식으로 응답하세요.

.roundtable/gemini-prompt.md:

당신은 창의적 대안 제시자입니다. 다음 프로젝트를 한 단계 격상시킬 전략적 제안을 하세요.

## 현황 요약
[Phase 1 결과를 그대로 붙여넣기]

## 제안 요청
1. 놓친 관점이나 기회
2. 구체적인 재편성/재구성 안 (표 형태)
3. 차별화 포인트 및 시장 포지셔닝
4. 단계별 실행 로드맵

파격적이되 실현 가능한 제안을 하세요. 마크다운 형식으로 응답하세요.

2-3. CLI 실행 (결정적, 재시도·폴백 포함)

모드별 실행 패턴:

codex: 아래 codex 블록 1회 호출 (포그라운드)
gemini: 아래 gemini 블록 1회 호출 (포그라운드)
both: 두 블록을 별개 Bash 호출로 만들고 둘 다 run_in_background=true로 띄운 뒤 BashOutput으로 완료 폴링

codex 실행 블록:

codex exec --skip-git-repo-check --sandbox read-only - \
  < .roundtable/codex-prompt.md \
  > .roundtable/codex-output.md \
  2> .roundtable/codex-stderr.log
echo "CODEX_EXIT=$?"

gemini 실행 블록:

gemini --approval-mode plan --output-format text \
  -p "$(cat .roundtable/gemini-prompt.md)" \
  > .roundtable/gemini-output.md \
  2> .roundtable/gemini-stderr.log
echo "GEMINI_EXIT=$?"

각 호출의 결과 분기 (shared-rules.md "재시도 정책" 단일 출처):

exit == 0
   └─ 결과 채택. .roundtable/<cli>-output.md를 입장으로 사용.

exit != 0
   └─ stderr 로그에 quota 패턴 매칭? (regex는 shared-rules.md 참조)
        ├─ Yes → 재시도 금지. 즉시 2-5 Claude 폴백.
        └─ No  → 2~3초 대기 후 1회 재시도.
                  ├─ 재시도 성공 → 결과 채택.
                  └─ 재시도 실패 → 2-5 Claude 폴백.

stderr 검사 명령:

grep -iE 'quota|rate.?limit|429|exceeded|RESOURCE_EXHAUSTED|too many requests|insufficient_quota' \
  .roundtable/codex-stderr.log >/dev/null 2>&1 && echo "QUOTA:codex"

2-4. 출력 정합성 점검

2-5. Claude 폴백 (예외 경로)

CLI 미설치(사용자가 폴백 동의), quota 감지, 또는 반복 실패 시에만 발동.

Agent 툴을 사용해 누락된 입장을 보완한다:

description: "<codex|gemini> 폴백 — <비판적 분석가|창의적 대안 제시자> 관점"
prompt: 위 2-2의 해당 프롬프트 본문 + 다음 안내 1줄 추가

"참고: 이는 <codex|gemini> CLI 사용 불가(사유: <quota|미설치|반복실패>)로 인한 Claude 폴백 분석입니다."
두 입장 모두 폴백이면 run_in_background=true로 병렬

폴백으로 생성된 파일 최상단에 다음 헤더를 반드시 추가:

> ⚠️ 폴백: <codex|gemini> CLI 사용 불가 (사유: <quota|미설치|반복실패>) — Claude로 대체 분석

2-6. 토론 라운드

라운드	내용
1라운드	각자 독립 분석 (위 2-3 ~ 2-5로 입장 수집 완료)
2라운드	필요 시 상대 입장에 대한 반론/보완 (각 CLI에 추가 호출. 동일하게 결정적 흐름 적용)
3라운드	최종 합의 시도 (필요 시)

최대 3라운드로 제한 — 그 이상은 수렴하지 않는다. 라운드를 추가할 때마다 .roundtable/<cli>-prompt-rN.md / <cli>-output-rN.md 식으로 파일 분리.

2-7. 합의 판단 기준

상황	처리
두 입장 동의 (또는 단일 모드에서 명확)	즉시 채택
한쪽만 동의	Claude가 근거를 평가하여 결정
양쪽 반대	제3의 절충안 도출 또는 사용자에게 판단 요청

Phase 3: 로드맵 합성

Claude가 중재자로서 토론 결과를 하나의 실행 가능한 로드맵으로 합성한다.

로드맵 문서 작성

${CLAUDE_PLUGIN_ROOT}/templates/roadmap-template.md 템플릿을 참조하여 작성한다.

핵심 구성요소:

결론 — 한 문단 요약
최종 구조 — 합의된 항목 목록 (표 형태)
항목별 상세 — 유지/축소/보강/신설 구분
기존→신규 매핑 — 어떤 것이 어디로 이동하는지
차별화 포인트 — 합의된 강점
토론 과정 요약 — 쟁점별 합의 결과 (표 형태). Phase 2에서 Claude 폴백이 발동된 입장은 해당 칸에 (Claude 폴백 — <사유>) 표기 필수. 사용자가 결과 출처를 명확히 알 수 있어야 함.

사용자 확인

반드시 사용자에게 로드맵을 보여주고 승인을 받는다:

"이 로드맵으로 실행해도 될까요?"
수정 요청이 있으면 반영 후 재확인
승인 없이 Phase 4로 넘어가지 않는다

Phase 4: 병렬 실행

승인된 로드맵을 기반으로 병렬 에이전트를 실행한다.

4-1. 작업 분할 원칙

원칙	설명
독립성	각 에이전트가 서로 다른 파일을 수정한다
자족성	필요한 모든 정보를 프롬프트에 포함한다
일관성	톤, 포맷, 용어 기준을 프롬프트에 명시한다
적정 크기	에이전트 하나당 파일 1~2개가 적정

4-2. 에이전트 프롬프트 필수 포함 사항

[역할 설명]

## 작업 대상
파일 경로: [출력 파일 경로]
제목: [제목]
소속: [Part/Section 정보]

## 기존 콘텐츠 (있을 경우)
[기존 내용 전문 — 요약이나 생략 금지]

## 변경 사항
1. [구체적 변경 1]
2. [구체적 변경 2]

## 통일 포맷
[프로젝트 전체에 적용되는 포맷 규칙]

## 톤/스타일 가이드
[기존 콘텐츠의 문체나 코드 스타일 — 예시 포함]

## 교차 참조
[다른 항목과의 연결 관계]

## 출력 요구사항
- 전체 내용을 작성할 것 (요약/생략 금지)

4-3. 실행 배치 전략

배치 1: 독립 작업들 (최대 6~12개 에이전트, run_in_background=true)
    ↓ 완료 대기
배치 2: 배치 1 결과 참조 필요한 작업 (있을 경우)
    ↓ 완료 대기
배치 3: 통합 작업 (부록, 인덱스, 교차 참조 등)

4-4. 진행 상황 추적

에이전트 완료 알림이 올 때마다 표로 상태를 업데이트하고 사용자에게 보고한다:

| 항목 | 작업 내용 | 상태 |
|------|-----------|------|
| Item 1 | ... | ✅ 완료 |
| Item 2 | ... | ⏳ 실행 중 |

Phase 5: 검증 및 정리

5-1. 파일 정리

# 기존 파일을 _old/ 폴더로 이동 (삭제하지 않음!)
mkdir -p _old/
mv [기존파일들] _old/

절대 기존 파일을 삭제하지 않는다. 반드시 _old/로 백업한다.

5-2. 검증 체크리스트

모든 에이전트가 파일을 정상 생성했는가
항목 간 교차 참조가 올바른가 (다음/이전 링크)
용어가 전체적으로 일관되는가
통일 포맷이 모든 항목에 적용되었는가
기존 파일이 _old/에 백업되었는가

5-3. 최종 보고

## 실행 완료 보고

### 파일 구조
[최종 파일 트리]

### 주요 변경 요약
- 신설: [새로 만든 항목]
- 재배치: [순서가 바뀐 항목]
- 보강: [내용이 추가된 항목]
- 수정: [수정된 사항]

### 차별화 포인트
[로드맵에서 합의된 차별화 포인트 재확인]

Customization Points

AI 역할 변경

프로젝트 유형에 따라 역할을 조정할 수 있다:

프로젝트 유형	codex-cli 역할	gemini-cli 역할
책/콘텐츠	구조 비평가	차별화 전략가
API 설계	보안/성능 감사	DX/UX 제안자
코드 아키텍처	기술 부채 분석	확장성 설계자
커리큘럼	교육학 비평	학습 경험 설계

규모 조절

프로젝트 규모	토론 라운드	병렬 에이전트 수
소 (파일 5개 이하)	1라운드	3~5개
중 (파일 10~15개)	2라운드	6~10개
대 (파일 20개 이상)	2~3라운드	배치별 8~12개

codex-cli / gemini-cli 없이 사용 (자동 폴백)

CLI가 설치되지 않았거나 quota가 소진된 경우, Phase 2의 폴백 경로(2-5)가 자동으로 발동한다:

사전 점검에서 MISSING:<cli> 감지 시 사용자에게 폴백/중단 선택 요청
실행 중 quota 패턴 감지 시 재시도 없이 즉시 Claude Agent 툴로 대체
일반 에러 시 1회 재시도 후 실패하면 Claude Agent 툴로 대체
모든 폴백 결과에는 > ⚠️ 폴백: ... 헤더와 토론 요약 표 (Claude 폴백) 표기가 붙음

Red Flags

Never:

토론 없이 바로 실행하지 않는다 — 편향된 결과가 나온다
에이전트 프롬프트에 기존 콘텐츠를 생략하지 않는다 — 톤/스타일 불일치가 생긴다
기존 파일을 삭제하지 않는다 — 반드시 _old/로 백업한다
3라운드 이상 토론하지 않는다 — 수렴하지 않으면 사용자 판단을 받는다
한 에이전트에 3개 이상 파일을 맡기지 않는다 — 품질이 떨어진다
사용자 승인 없이 Phase 4를 시작하지 않는다
Phase 2에서 CLI가 작동 가능한데 Agent 툴(Claude 역할극)로 우회하지 않는다 — 사용자가 사실상 단일 모델 결과를 받게 된다 (폴백은 미설치/quota/반복실패 시에만)
quota 에러를 만나도 재시도하지 않는다 — 같은 에러가 반복되며 시간만 낭비된다. 즉시 폴백

Always:

Phase 1에서 기존 콘텐츠를 충분히 읽는다
Phase 2에서 선택된 모드(codex / gemini / both)에 맞는 실제 CLI 바이너리를 Bash 툴로 호출한다
CLI 호출 전 command -v로 존재를 확인한다
폴백이 발동되면 결과 파일과 로드맵 토론 요약에 폴백 사유를 명시한다
토론 결과에서 합의/비합의 사항을 명확히 구분한다
로드맵을 사용자에게 확인받은 후 실행한다
에이전트 프롬프트에 톤/스타일/포맷 가이드를 포함한다
실행 진행 상황을 실시간으로 사용자에게 보고한다

Example: 아카펠라 책 12챕터 재편성

결과: 10챕터 → 12챕터 재편성, 신설 2챕터, 전 챕터 보강, 부록 추가 — 약 30분 소요