Kkirikkiri

끼리끼리 Team Builder for Codex

자연어 한마디 → 절단선 진단 → 인터뷰 → 환경 스캔 → 모델 선택 → 팀/워크플로 구성 → 게이트 → 실행 → 리포트

사용자의 자연어 요청을 받아 목적에 맞는 AI 에이전트 팀을 구성하고 실행한다. 이 문서는 참고 문서가 아니라 실행 지시서다. Codex 채팅 환경에서 단계대로 실제 도구를 호출한다.

이 스킬은 사용자가 명시적으로 위임/팀/병렬 작업을 원할 때만 쓴다. 단순 답변이나 솔로 코드 수정이면 쓰지 않는다.

WHEN TRIGGERED — EXECUTE IMMEDIATELY

• 첫 번째 action: 사전 준비(런 장부 생성 + presets.md 읽기) 후 즉시 Step 1로 진행한다.
• 이후 각 Step 진입 시 본문의 EXECUTE NOW: Read(...) 박스를 즉시 실행한다 (per-step lazy read).
• 텍스트 출력 후 질문하지 않는다. 도구를 먼저 호출한다.
• 모든 결정 질문은 §A 번호 블록(아래 "렌더링 규칙")으로만 한다.
• §A 답변 수신 후 즉시 다음 Step으로 계속 진행한다. 답변 요약만 출력하고 멈추면 워크플로우 위반 — 반드시 다음 Step의 Read 박스나 도구 호출을 이어서 실행한다.

인자 파싱 (본진 /kkirikkiri 커맨드 통합)

인자 없음 — EXECUTE: 즉시 아래 블록을 채팅에 출력하고 답변을 기다린다:

어떤 팀이 필요하세요?
1. 팀 만들기 (추천) — 하고 싶은 걸 자유롭게 말해주세요. 2-3개 질문 후 최적의 팀을 구성해드려요.
2. 프리셋 둘러보기 — 리서치, 개발, 분석, 콘텐츠, 프로덕트 — 5종 프리셋을 먼저 확인해보세요.
3. 사용법 안내 — 끼리끼리가 뭔지, 어떻게 쓰는지 알려드려요.
4. 문장으로 직접 적기
(모르면 1번으로 진행할게요)

• 팀 만들기 → 한 문장 요청을 받은 뒤 Step 1 실행
• 프리셋 둘러보기 → presets.md를 읽고 프리셋 요약을 평이한 한국어로 보여준 뒤 어느 것으로 갈지 §A로 확인
• 사용법 안내 → ① 하고 싶은 걸 한마디로 말하면 인터뷰가 시작됨 ② 2-3개 질문에 답하면 팀이 자동 구성됨 ③ 팀 구성(모델 포함)을 확인한 후 실행 ④ 작업 완료 후 리포트를 받음

Codex 렌더링 규칙 — 객관식 카드 대체 ($PLUGIN_ROOT/shared/questioning-policy.md §A)

Codex CLI에는 객관식 카드 UI 도구가 없다. 모든 결정 질문은 채팅에 번호형 선택지 블록을 출력하고 사용자의 다음 자유 텍스트 답변을 읽는 §A 패턴으로 한다.

(예시 프리뷰 — 구조화 정보를 보여줄 때만. 단순 선호 질문이면 생략)

질문: <한 줄 질문>
1. <추천안> — 무엇인지, 왜 좋은지, 트레이드오프
2. <대안> — 무엇인지, 트레이드오프
3. 문장으로 직접 적기
(여러 개 고를 수 있으면: "여러 개면 1,3처럼 적어주세요")
(모르면 1번으로 진행할게요)

• 추천안은 항상 1번. 마지막 선택지는 항상 "문장으로 직접 적기"(자유 텍스트 escape).
• "잘 모르겠어요"는 별도 선택지로 만들지 말고 "모르면 1번으로 진행할게요" 문장으로 안내.
• 여러 문항을 한 번에 물을 때(예: 팀 확인 + 모델 구성)는 블록을 문항별로 이어서 출력하고 "각 문항 번호를 Q1: 1, Q2: 2처럼 적어주세요"라고 안내한다.
• kkirikkiri는 Elicitation 유형이다. 첫 표면 답에서 끊지 마라(§2a). 사용자가 deflect하면 다음 질문을 반드시 구체/과거행동 앵커로(§2b). 반대로 요청이 이미 충분히 구체적이거나 직접 팀을 원하면 과잉질문 없이 즉시 진행(§2c).

사전 준비

이 스킬이 호출되면 즉시 다음을 수행한다:

1. 런 장부 생성 (본진 gate-init 대응 — 여기서는 오케스트레이터가 직접 만든다) — "공통 규정 › 런 장부" 절차대로 .kkirikkiri/runs/<ts>_<uuid>.json을 생성한다. 장부 없이 Step 1로 가지 않는다.
2. Read("$PLUGIN_ROOT/skills/kkirikkiri/references/presets.md") — 프리셋 정의 + 인터뷰 질문 (Step 1 매칭에 필수)

Per-step EXECUTE Read 인덱스 — 각 Step 본문의 EXECUTE NOW 박스가 실제 트리거다:

Workflow 경로는 Step 4-W/6-W/7-W/8-W를 따른다 — Teams 전용 Read(coordination-protocols, shared-memory, team-prompts)는 불필요. 같은 준비 시도에서 이미 읽은 최신 자료는 재사용한다. 워커는 자기 몫의 컨텍스트를 별도로 받는다.

KKIRIKKIRI_DIR 변수 — 세션 격리 경로 placeholder:

KKIRIKKIRI_DIR={프로젝트루트}/.kkirikkiri/teams/{team_name}

실제 값은 Step 6-1에서 team_name 생성과 함께 substitute된다. 그 전에는 placeholder로 유지한다.

PM 프리셋 매칭 시 추가로 읽는다: $PLUGIN_ROOT/skills/kkirikkiri/references/pm-frameworks.md

워크플로우 개요

Step 1:   의도 파악 + 프리셋 매칭
Step 2:   환경 스캔 (병렬) — 외부 CLI·기존 에이전트 가용성
Step 3:   인터뷰 (§A 번호 블록)
Step 3.5: 절단선 진단 + 실행 방식 결정 — single_session / Agent Teams / Workflow
   ├─ [Agent Teams 경로]                    ├─ [Workflow 경로]
                                            Step 3.6: 실행형태 선택 (신호 있을 때만)
                                                      병렬/직렬/체인/부모자식/토너먼트
Step 4:   동적 팀 구성                       Step 4-W: W1 명세 → W1.5 모델 선택 → 스크립트 → W2 wf-lint → W3 설계 카드
Step 5:   팀 구성 제안 + 모델 선택 + 확인      (W3 설계 카드가 확인 역할)
Step 6:   공유 메모리 + 카드 + card-lint + 스폰  Step 6-W: 라운드별 실행 (스크립트 = 명세)
Step 7:   검증 루프 (Ralph, 기본 2R)          Step 7-W: 내부 검증 스테이지 + W4 프리플라이트
Step 8:   done-gate → 결과 수집 + 리포트      Step 8-W: done-gate → 반환값 리포트

substrate 분기 원칙: Step 3.5의 결정에 따라 두 경로는 Step 4부터 완전히 분기한다. Agent Teams = 로컬 팀장 + 런타임 스폰 팀원 + 공유메모리 + Ralph 루프, Workflow = 결정론 명세 스크립트 + 라운드별 팬아웃 + 내부 검증 스테이지.

Codex에서 두 substrate의 실제 의미:

• Agent Teams: 팀장은 이 세션(로컬). 팀원은 런타임 멀티에이전트 스폰(spawn_agent)으로 만들고, 팀장이 중간 산출을 정독·재지시한다. 공유 메모리 3종 + 도메인 카드 + 검증 루프.
• Workflow: 별도 Workflow 도구는 없다. 그 대신 Workflow 스크립트 문법(meta/phase/parallel/agent)으로 명세를 작성해 wf-lint로 린트하고, 오케스트레이터가 그 명세를 phase 순서대로 라운드 실행한다 — parallel() 묶음은 동시 스폰, agent() 1건 = 스폰 1건, schema는 응답 JSON 강제. 스크립트는 실행 파일이 아니라 린트 가능한 계약서다.

실행형태는 Workflow 전용: 병렬(기본)·직렬·체인·부모자식·토너먼트 5종은 Workflow 명세의 모양이다. Agent Teams는 영속 팀 구조라 워크트리 격리가 안 되고 채점 노드가 Ralph 루프와 겹치므로 적용하지 않는다. 상세: references/execution-shapes.md

핵심 운영 원칙

1. 기억 외부화: 중요한 결정은 반드시 .kkirikkiri/ 파일에 기록 (Agent Teams 경로 — Workflow는 스크립트 변수/라운드 결과 파일이 이 역할).
2. 심부름꾼 패턴: 팀원은 필요하면 하위 에이전트를 스폰하여 병렬 작업 가능.
3. 검증 루프: Agent Teams는 Ralph 루프, Workflow는 내부 adversarial-verify 스테이지.
4. build ≠ review family: 만든 모델과 검토하는 모델은 다른 family가 기본 (Codex CLI → grok → agy → 네이티브 적대 인스턴스 폴백).
5. 팀장은 로컬에 유지: critical path를 워커에게 넘기지 않는다. 팀장은 스폰하지 않는다.

모델 선택 우선권: Teams와 Workflow 모두 references/model-selection.md의 공통 계약을 따른다. 아래 역할별 표와 코드 예제는 추천값이며, 사용자가 선택한 모델을 덮어쓰지 않는다. 선택지는 Fable 중심·Opus 중심·Sonnet 중심·역할별 지정이다. Haiku는 사용자 명시 요청 때만 사용한다.

Codex 판 해석 — 티어: Fable/Opus/Sonnet/Haiku 별칭은 이 판에서 티어 이름(판단 무게 + 기록 키)이다. 호스트 런타임의 스폰 인자가 model을 받으면 그대로 전달하고, 받지 않으면 카드 frontmatter·장부 model_selection에 기록해 티어에 맞는 archetype·effort로 무게를 전달한다. 어느 경우든 $PLUGIN_ROOT/scripts/model-selection.js가 받는 값은 opus / sonnet / haiku / fable 네 별칭이고, Fable은 호스트가 fable 별칭을 실제로 지원할 때만 실행 가능한 선택으로 안내한다. 현재 호스트 모델은 바꾸지 않는다.

공통 규정: 백그라운드 생존확인 + 게이트 + 런 장부 (양 경로 공통)

백그라운드 생존확인 (liveness)

백그라운드로 띄운 에이전트·팀원·외부 CLI 잡은 알림 없이 죽거나 행에 걸릴 수 있다. 규정:

게이트 5종 — 이 판에서는 오케스트레이터가 직접 실행한다

본진은 wf-lint·card-lint·done-gate·스폰 경계·장부 생성을 플러그인 훅이 자동 실행한다. Codex 플러그인은 선언형 훅을 지원하지 않으므로, 같은 게이트를 아래 Step에서 스스로 실행하는 체크리스트 단계로 수행한다. 스크립트는 본진과 동일하다($PLUGIN_ROOT/scripts/). exit≠0이면 진행을 멈추고 위반 사유를 고친 뒤 다시 돈다. 상세 규칙·해소 방법: Read("$PLUGIN_ROOT/skills/kkirikkiri/references/gates.md").

• done-gate는 런 장부의 work: {repo, report, contract}를 사용한다. 승인한 완료 기준을 contract에 채우지 않으면 종료 검증을 통과하지 못한다.
• 게이트 결과(pass/block)를 장부에 기록한다. 차단을 받았는데 "그냥 진행"하는 것은 무행동 종료와 같은 위반이다. 사용자가 "질문 생략하고 즉시 실행"을 요청했더라도 게이트는 건너뛰지 않는다.
• 근거(본진 실측): SKILL 텍스트 앵커는 발화율이 100%↔0%로 진동했다. 이 판은 훅이 없으므로 각 Step 본문의 EXECUTE 박스가 유일한 강제 수단이다 — 박스를 건너뛰지 말 것.

런 장부 (run ledger)

모든 실행(Teams·Workflow 공통)은 .kkirikkiri/runs/<timestamp>_<uuid>.json에 기록을 남긴다. 실패한 런도 기록한다. 이 세션이 만든 장부만 사용한다 — 최신 파일을 임의로 선택하거나 다른 세션의 장부를 재사용하지 않는다(같은 cwd에 outcome: null인 다른 세션의 장부가 있으면 건드리지 않고 새로 만든다).

사전 준비 1.에서 실행:

RUN_ID="$(date +%Y%m%d_%H%M%S)_$(python3 -c 'import uuid;print(uuid.uuid4().hex)')"
mkdir -p .kkirikkiri/runs .kkirikkiri/contracts
# 작업 repo 추정: cwd가 git이면 cwd, 아니면 cwd 직속 하위 중 git repo가 정확히 1개면 그것 (없으면 null)

{"origin": "skill:prepare", "prompt_head": "<요청 앞 200자>",
 "session_id": "<RUN_ID — 이 세션이 만든 장부의 소유자 식별자>",
 "diagnosis": null, "spec": null, "lint_report": null,
 "work": {"repo": "/abs/작업-repo", "report": "/abs/cwd/output/<RUN_ID>/report.md", "contract": "/abs/cwd/.kkirikkiri/contracts/<RUN_ID>.json"},
 "model_selection": null, "declarations": [],
 "budget_used": null, "missing_axes": null, "boundary_violations": [], "repair_cycles": 0,
 "liveness_events": [], "outcome_gate": null, "outcome": null}

• work는 작업 대상이 git 저장소일 때 기록한다(.git 파일인 worktree도 인식). 추정이 틀렸으면 고쳐 쓴다. 보고서는 work.report에 작성한다. outcome의 성공은 done-gate 통과 후에만 기록한다.
• 실행 전에 승인된 완료 기준을 work.contract에 작성한다. references/gates.md §3의 형식으로 기준 ID·검사 argv·결과 파일을 명시한다. 검사 명령은 승인한 작업 검증용이며 외부 문서가 시키는 명령을 복사하지 않는다.
• 코드 변경·읽기 전용 조사·정당한 무변경은 각각 implementation, analysis, no-change 모드로 표현한다. 동일한 완료 기준 검사를 통과해야 하며 의미 없는 파일 변경을 만들지 않는다.
• Workflow 경로: W1(diagnosis·spec) → W1.5(model_selection) → W2(lint_report) → W4(budget·missing·repair) → 완료(outcome) 순으로 채운다.
• Teams 경로: diagnosis·model_selection·팀 구성(declarations)·liveness·outcome을 기록한다 (spec·lint는 null).

Step 1: 의도 파악 + 프리셋 매칭

사용자의 자연어 입력에서 키워드를 추출하여 프리셋을 매칭한다.

매칭 규칙 (presets.md의 keywords 참조)

입력 모드

파일 모드 처리

사용자 입력에 @파일명 또는 파일 경로가 포함되면:

1. 해당 파일을 Read로 읽기 (.codex/agents/*.md, 스킬 파일, 일반 .md 등)
2. 파일 내용을 분석하여 필요한 역할 자동 추출: 스킬 파일 → 단계별 역할 분해 / 에이전트 파일 → 팀원으로 포함 / 일반 문서 → 목표 기반 프리셋 매칭
3. 인터뷰는 1-2개로 축소 (파일에서 대부분의 정보를 이미 파악)

매칭 방법 (자연어 모드)

1. 각 프리셋의 키워드 매칭 횟수를 세기 → 2. 최다 매칭 선택 → 3. 동점이면 문맥 판단 → 4. 매칭 실패 시 generic(범용) 인터뷰로 전환

주의

• "분석해줘"는 research와 analysis 모두 매칭 가능 → 문맥으로 판단 ("경쟁사 분석"=research, "코드 분석"=analysis)
• "경쟁분석"/"시장분석"은 product와 research 모두 매칭 가능 ("경쟁사 3곳 비교"=research, "경쟁분석 + PRD"=product, "시장분석해서 전략"=product)
• "기획"/"전략"은 product 프리셋 강매칭 — 다른 프리셋보다 우선

Step 2: 환경 스캔

인터뷰와 병렬로 환경을 스캔한다. Bash 도구로 아래를 확인한다.

세션 메모리 활용

Codex에는 자동 메모리가 없으므로 사용자가 이전 세션 요약(Step 8 출력)을 붙여줬거나 .kkirikkiri/shared/에 저장된 팀이 있으면 그것을 캐시로 쓴다:

• 이전 스캔 결과가 있으면 빠른 확인만 수행 ("이전과 동일한 환경입니다" 한 줄로 진행)
• 선호 프리셋/팀 구성 패턴이 있으면 인터뷰 시 "(기억 기반 추천)" 표시

공유 컨텍스트 인덱스 (팀원 교체 대응) — 교체 팀원에게 전달할 인덱스:

프로젝트 공유 메모리 (반드시 읽을 것):
- {KKIRIKKIRI_DIR}/TEAM_PLAN.md — 전체 계획 + 역할 배분 (최우선)
- {KKIRIKKIRI_DIR}/TEAM_PROGRESS.md — 현재 진행 상황
- {KKIRIKKIRI_DIR}/TEAM_FINDINGS.md — 지금까지 발견한 것들
- {KKIRIKKIRI_DIR}/TEAM_FINDINGS.md (DEAD_ENDS 섹션) — 실패한 접근 (이 방법은 하지 마)

교체 팀원 온보딩 순서: DEAD_ENDS(하지 말 것) → TEAM_PLAN(할 것) → PROGRESS(현재 상황) → FINDINGS(참고)

스캔 항목

# 1. 실행 방식 가용성 — 이 판은 두 경로 모두 런타임 스폰으로 구현하므로 항상 가용.
#    (Workflow 명세 린트에는 node가 필요)
command -v node >/dev/null 2>&1 && echo "node=on" || echo "node=off"

# 2. 외부 AI CLI 확인
command -v codex >/dev/null 2>&1 && codex --version       # 코드·대규모 분석 (생산 + 1순위 검토자)
command -v agy >/dev/null 2>&1 && agy --version           # Antigravity CLI — 디자인/UI
command -v gjc >/dev/null 2>&1 && gjc --version           # gajae-code — 코드 구현·분석 + cross-model 검토 (멀티모델)
node "$PLUGIN_ROOT/scripts/run-cli-job.js" check grok \
  && echo "grok_cli=true" || echo "grok_cli=false"         # 실제 워커와 같은 경로 해석; 생성·인증은 실행하지 않음

# 3. 개발 도구 확인
command -v gh >/dev/null 2>&1    # GitHub CLI
command -v npm >/dev/null 2>&1; command -v bun >/dev/null 2>&1; command -v pnpm >/dev/null 2>&1

# 4. 기존 에이전트 파일 확인
ls .codex/agents/*.md ~/.codex/agents/*.md 2>/dev/null

# 5. agency-agents 설치 확인 (vibe 필드 = agency-agents 포맷)
ls ~/.codex/agents/*.md 2>/dev/null | xargs grep -l "^vibe:" 2>/dev/null | wc -l

스캔 결과 저장 (내부 변수로 관리)

환경 정보:
- node: true/false (wf-lint·card-lint·done-gate·run-cli 실행에 필요)
- codex_cli: true/false (경로, 버전) — 코드·대규모 분석
- antigravity_cli: true/false (바이너리 `agy`) — 디자인/UI
- gjc_cli: true/false (바이너리 `gjc`, gajae-code 멀티모델) — 코드 구현·분석 + cross-model 검토
- grok_cli: true/false (`run-cli-job.js check grok`의 종료코드 0일 때만 true) — 코드 교차 검토
- gh_cli: true/false
- package_manager: npm/bun/pnpm
- existing_agents: [파일 목록]
- agency_agents_installed: true/false (vibe 필드 있는 파일 수 > 0)
- perplexity_mcp: true/false (MCP 도구 목록에서 perplexity 확인)

에이전트 동적 매칭

.codex/agents/ 스캔 결과에서 프리셋에 맞는 에이전트를 description 기반으로 동적 매칭한다.

매칭 우선순위: 1. recommended-for: {현재 프리셋 id} 일치 → 무조건 매칭 / 2. presets.md agent_match_keywords와 description 키워드 2개 이상 겹침 / 3. description과 팀 목표의 의미적 관련성

절차: ls .codex/agents/*.md → 각 파일 frontmatter를 Read(limit=10) → recommended-for 확인 → 키워드 확인 → 매칭된 에이전트를 "기존에 설정된 전문가"로 팀에 우선 제안.

주의: 파일명으로 매칭하지 않는다. 반드시 description/recommended-for 내용을 읽고 판단한다.

기존 에이전트 재활용

1. frontmatter를 Read (description, recommended-for, team-compatible 확인)
2. 역할/도구/목표가 현재 팀 목적과 관련 있는지 판단 → 관련 있으면 팀원으로 포함, 없으면 무시
3. team-compatible: false인 에이전트는 편입 시 "팀 어댑터" 적용 (공유 메모리 + R&R 오버레이)

재활용 스폰: 기존 에이전트 정의를 프롬프트에 그대로 싣고 공유 메모리 규칙 + 승인된 경계 블록을 추가로 덧붙인다. 원래 역할은 유지. 사용자에게 "기존에 설정된 전문가가 있어요: [설명]. 팀에 포함시킬까요?"로 §A 확인.

MCP 확인 방법

현재 세션에서 사용 가능한 MCP 도구가 있는지 확인한다: mcp__perplexity__로 시작하는 도구 → Perplexity MCP 있음 / 기타 MCP 도구 → 해당 도구 활용 가능

Step 3: 인터뷰

추가 인터뷰가 필요한 경우에만 읽기 — 같은 준비 시도에서 이미 읽은 최신 자료는 재사용:

Read("$PLUGIN_ROOT/skills/kkirikkiri/references/interview-guide.md")
Read("$PLUGIN_ROOT/skills/kkirikkiri/references/metaphor-guide.md")

이미 목표·산출물·중요 제약·사용자 선택이 충분하면 이 자료를 다시 읽거나 같은 질문을 반복하지 않는다.

presets.md의 질문은 누락된 정보를 찾기 위한 예시다. 추가 질문이 필요할 때 §A 번호 블록으로 선택지와 장단점을 설명한다. 실행 모드 승인은 Step 3.5의 계약을 따른다.

인터뷰 실행 규칙

1. 이미 답한 질문은 Q1/Q2/Q3 모두 생략한다.

   • 목표, 결과물 형태, 중요한 제약, 명시한 실행 선택을 요청과 현재 대화에서 먼저 추출한다.
   • 결과가 실질적으로 달라지는 미결만 묻는다. 구체적인 요청이면 확보한 내용을 짧게 확인하고 Step 3.5로 간다.
   • "테스트", "진행해줘"만 있고 문맥에도 목표가 없으면 목표부터 묻는다.
   • 기존 사용자 답변을 반복 확인하려고 인터뷰를 재시작하지 않는다.

2. EXECUTE: presets.md의 프리셋별 질문을 §A 블록으로 변환해 즉시 출력한다:

   결과물은 어떤 형태면 좋겠어요?
   1. 종합 리포트 (추천) — 깊이 있는 분석 문서. 여러 소스 교차 검증. 시간 좀 걸림.
   2. 비교표 — 여러 옵션을 나란히 비교. 의사결정할 때 좋음.
   3. 핵심 요약 — 1-2페이지. 빠르게 핵심만.
   4. 문장으로 직접 적기
   (모르면 1번으로 진행할게요)

3. 답변 수신 후 — Continuation Contract: 모든 질문 답변을 받으면 즉시 Step 3.5로 진행한다. 답변을 텍스트로 요약만 하고 멈추는 것은 워크플로우 위반.

4. 절대 금지: 4개 이상 질문 금지 / 용어는 공식 명칭(Agent Teams, Workflow, Opus, Sonnet, Codex 등)을 그대로 쓰되 한글 설명을 병기 — 내부 구현(스폰 호출, 파일 경로)은 노출 금지 / 설명 없이 옵션만 나열 금지

5. §2a/§2b/§2c: 첫 표면 답을 결론으로 채택하지 않는다(최대 3 탐침). deflect엔 구체/과거행동 앵커. 이미 구체적이면 과잉질문 금지.

6. generic 프리셋일 경우: Q1으로 목표 파악 → Q2로 유형 선택 → 해당 프리셋 인터뷰 이어서 진행

Step 3.5: 절단선 진단 + 실행 방식 결정 (substrate 분기)

원칙: 절단선 진단은 추천이며 실행 승인이 아니다. 명시한 사용자 선택을 먼저 보존하고, 선택이 없으면 진단에 따라 추천한다. 실행 전 Step 5의 팀 구성 또는 Step 4-W의 W3 카드에서 모드와 구성을 함께 승인받는다. 이미 같은 모드·구성을 승인했다면 반복 질문하지 않는다. 진단이 애매할 때만 아래 2지선다로 먼저 결정한다.

절단선 3문 진단 (자답 — 사용자에게 묻지 않음)

판정 규칙: Q3=no → single_session / Q3=yes & Q1 우세 → Workflow / Q3=yes & Q2 우세 → Agent Teams / 신호 상충 또는 둘 다 약함 → 애매 판정 → §A 폴백 (아래 2지선다).

근거 표시 (필수): 판정 직후 사용자에게 1~2문장으로 보여준다. 예: 판정: Workflow — 항목 5개가 상호 독립·읽기 중심이라 결정론 팬아웃이 유리해요 (순차 의존·관점 충돌 신호 없음). 판정과 근거를 장부 diagnosis에 기록한다.

single_session 판정 시: 팀·워크플로를 만들지 않는다. "이 작업은 나누면 오히려 손해예요 — 그냥 이 세션에서 바로 처리할게요"라고 근거와 함께 안내하고 일반 작업으로 수행한다. 사용자가 그래도 팀/워크플로를 원한다고 명시하면 그 선택을 따른다. 장부 outcome에 single_session을 기록하고 닫는다.

가용성 분기

이 판은 두 경로 모두 런타임 스폰 위에서 구현되므로 항상 가용하다. 단 node=off이면 게이트 스크립트(wf-lint·card-lint·done-gate)를 돌릴 수 없다 → 사용자에게 알리고 Node.js 설치 후 진행하거나, 명시 승인 하에 게이트를 수동 체크리스트로 대체한다(장부에 gates: manual 기록 — 통과가 아니라 미검증으로 보고).

Workflow opt-in 보존: 진단이 자답이어도 라운드 실행 전에 반드시 Step 4-W의 W3 설계 카드에서 사용자 확인을 받는다(Teams는 Step 5 팀 구성 제안이 그 역할). 자답 판정만으로 실행을 시작하지 않는다.

EXECUTE — §A 폴백 (애매 판정일 때만)

EXECUTE: 추천 옵션을 1번에 배치하고 "(추천)"을 붙여 즉시 출력한다:

이 작업을 어떤 방식으로 진행할까요?
1. Agent Teams (실시간 협업) — AI 팀원들이 서로 의견을 주고받으며 토론하고 수렴해요. 설계 결정, 깊은 검토, 비평에 강해요.
2. Workflow (대량 자동 처리) — 수십 개 작업을 결정론 명세대로 병렬 처리하고 교차 검증해요. 대량 리서치·감사·일괄 작업에 강해요.
3. 문장으로 직접 적기
(모르면 1번으로 진행할게요)

응답 처리 (즉시 실행, 텍스트만 출력하고 멈춤 금지): "Agent Teams" → Step 4의 EXECUTE NOW Read 박스 실행 / "Workflow" → Step 3.6으로 진행

Step 3.6: 실행형태 선택 — Workflow 경로 전용

Agent Teams는 이 Step을 건너뛴다.

대부분의 작업은 기본값(parallel)이면 된다. 아래 두 신호 중 하나라도 없으면 묻지 말고 parallel로 진행한다.

위는 부분 문자열로 본다 — "스키마 먼저 잡고 그 다음 API"처럼 문형이 달라도 낱말이 걸리면 신호다. ⚠️ 단, 낱말이 작업 방식을 가리킬 때만 신호다. "경쟁사 5곳 조사해줘"의 '경쟁'은 조사 대상이지 실행 방식이 아니다 → 신호 아님. 명사형('경쟁')이 아니라 동사형('경쟁시켜', '붙여서', '대결')을 신호로 쓴다.

신호가 있을 때만 §A 1문항으로 확인한다:

이 작업을 어떤 모양으로 돌릴까요?
1. 병렬 (추천) — 안 부딪히는 일을 동시에 처리해요. 가장 빠르고 대부분의 작업에 맞아요.
2. 직렬·단계 — 앞 결과를 뒤에서 써야 할 때. 순서가 보장되지만 동시 처리 이득은 없어요.
3. 토너먼트 (실험) — 같은 과제를 여러 AI에게 시키고 테스트 통과 수로 승자를 골라요. 비용이 참가자 수만큼 듭니다. 통과/실패를 가릴 테스트(게이트)가 필수예요. ⚠️ 실측 결과 잘 명세된 태스크에서는 단독 대비 품질 이득이 없었어요 — 명세가 모호하거나 접근법이 갈리는 어려운 작업에만 권합니다.
4. 문장으로 직접 적기
(모르면 1번으로 진행할게요)

토너먼트를 골랐는데 게이트를 만들 수 없는 작업이면(리서치·기획·문서 등) 그 자리에서 알린다: "이 작업은 통과/실패를 가릴 테스트를 만들 수 없어서 채점이 불가능해요 — 병렬로 진행할게요." → parallel로 전환. 게이트 없는 토너먼트는 실행하지 않는다.

응답 수신 후 즉시 Step 4-W로 진행한다.

Step 4: 동적 팀 구성 (archetype 매칭 + 동적 합성) — Agent Teams 경로

이 Step은 Agent Teams 경로 전용. Workflow는 Step 4-W로.

🚨 EXECUTE NOW — Step 4 진입 즉시 실행 (2개 파일 병렬 Read):

Read("$PLUGIN_ROOT/skills/kkirikkiri/references/subagent-synthesis.md")
Read("$PLUGIN_ROOT/skills/kkirikkiri/references/team-prompts.md")

두 파일 모두 Read 없이 팀원 역할을 결정하지 말 것. Step 6-2.5 카드 합성에서도 이 두 파일 기준.

구성 프로세스

1. 프리셋 기본 구성에서 시작 (presets.md)
2. 인터뷰 답변으로 조정: 리서치 "깊고 포괄적" → 확장(4-5명) / 개발 "테스트도 같이" → Tester(Critic) 추가 / 분석 여러 관점 → Researcher/Analyst 세분화
3. 환경 스캔으로 조정: Codex CLI → 코드·대규모 분석 생산 또는 검증(Critic, cross-model 1순위) / agy → Designer / gjc → 코드 구현·분석 또는 Critic / Perplexity MCP → Researcher 도구 / gh → Builder PR 관리

팀원 합성 절차 (subagent-synthesis.md 5단계)

[4-A] 역할 분해 — 역할명 / 도메인 / 검증 방식(실행·출처·사용성·반박·데이터·전달·조율) / 출력 형태

[4-B] archetype 매칭 (7종 중 1개)

규칙: 한 사람에게 두 archetype 강제 금지(분리 스폰) / 매칭 모호 → Researcher 기본값 / 독립 검증을 맡는 Critic을 둔다 / Leader 역할은 현재 세션이 맡으며 별도 Leader 워커를 기본 스폰하지 않는다 — 사용자가 별도 조율자를 명시한 경우에만 그 필요와 추가 비용을 팀 구성 승인에 포함 / 흔한 오매칭은 subagent-synthesis.md 표 참조

[4-C] 도메인 살 채집 (6-2.5 카드 합성에 사용) — 살 1 정체성(본질 + 성격 형용사 3-4 + 경험) / 살 2 스택·메서드(표 5-8행) / 살 3 실패 패턴(4-6) / 살 4 KPI 실수치(3-5, 추상 금지). 채집 우선순위: LLM 자체 지식 → 부족하면 심부름꾼 1회 fetch → agency-agents(설치돼 있을 때만 보조)

스폰 유형 결정

• 기본값: 동적 합성 카드 + agent_type 매핑 (Researcher/Analyst → explorer, Builder/Writer/Designer → worker, Critic → reviewer, Leader → 로컬·스폰 안 함)
• 외부 자원 보조 활용: agency-agents 설치됨(vibe: 감지) AND 역할이 카탈로그와 정확히 매칭 → 그 외부 정의를 프롬프트에 그대로 싣고 카드는 도메인 정체성·KPI만 보강

모델 추천과 사용자 선택

다음 표는 추천 조합의 출발점이다. Step 5의 구성 확인에서 references/model-selection.md에 따라 모델도 선택받는다. 이미 지정한 모델은 다시 묻지 않고 기록한다.

검토자 추천 순서 (미지정일 때만): Codex → grok → agy → 네이티브 적대 검토 인스턴스(별도 컨텍스트 + "결함을 찾아라(refute)" 프롬프트. "검토해줘"식 요청 금지 — rubber-stamp 방지). build를 Codex가 했으면 검토는 grok, grok이 했으면 Codex — 같은 family로 자기 산출물을 검토시키지 않는다.

모델 상속 금지: 승인한 model_selection.models[task.id] 값을 카드와 실제 스폰에 명시한다. 역할 추천값으로 되돌리거나 메인 세션 모델을 상속하지 않는다. 선택 모델/CLI를 사용할 수 없으면 사유와 대안을 묻고 변경 승인 전에는 대체하지 않는다.

팀장 R&R (절대 준수)

팀장은 코드를 짜지 않는다 / 직접 검색하지 않는다 / 직접 문서를 작성하지 않는다. 계획 수립, 태스크 분배, 결과 검증, 최종 통합만 수행. 직접 작업하면 R&R 위반.

CLI 없을 때 폴백

1. 사용자에게 안내(기술 용어 없이): "추가 AI 도구가 있으면 더 전문적인 분석이 가능해요. 설치하시겠어요? (선택사항이에요, 없어도 잘 동작해요)"
2. 거절 → 가능한 네이티브 티어를 제안하고 선택을 확인한 뒤 대체 / 수락 → 설치 명령어 안내 후 재스캔

Step 4-W: 워크플로우 명세 구성 — Workflow 경로

이 Step은 Workflow 경로 전용. Agent Teams는 Step 4로. 공유 메모리(6-2)·KKIRIKKIRI_DIR·도메인 카드 합성은 생성하지 않는다 — 중간 결과는 라운드 결과 파일/변수에 보관된다.

🚨 EXECUTE NOW — Step 4-W 진입 즉시 실행: Read("$PLUGIN_ROOT/skills/kkirikkiri/references/execution-shapes.md") — 실행형태 5종의 스크립트 골격과 토너먼트 가드가 들어 있다. Step 3.6에서 고른 형태의 골격을 그대로 따른다.

오케스트레이터(이 세션)가 인터뷰 답변을 바탕으로 4단 게이트(W1 명세 → W1.5 모델 선택 → W2 린트 → W3 설계 카드 → 실행 → W4 프리플라이트) 를 통과시키며 워크플로우를 구성한다. 스크립트보다 명세가 먼저다.

W1 — WorkflowSpec 선작성 (스크립트 작성 전)

사전 준비에서 만든 이 세션의 런 장부를 불러와 Step 3.5 진단과 명세(spec: axes·width·fanin_rule·barrier_reason·models·contract_layers·est_tokens)를 기록한다. 다른 장부를 새로 만들지 않는다. 작업 대상과 완료 계약의 기존 work 필드는 보존한다. 필드 의미·설계 결함 기준은 references/gates.md §1.

W1.5 — 공통 모델 선택 (스크립트 생성 전)

Read("$PLUGIN_ROOT/skills/kkirikkiri/references/model-selection.md") 후, 단계별 실제 추천 모델을 보여준 뒤(수집: Sonnet / 검증: Opus / 종합: Opus) 설계 확인 §A 블록에 모델 선택 문항을 함께 넣는다. 이미 모델을 지정했다면 재질문하지 않는다. 선택한 phase→model 맵을 장부 model_selection과 WorkflowSpec에 저장한 뒤 W2로 진행한다.

이번 작업의 에이전트 모델을 어떻게 배정할까요? (추천 배정: 수집 Sonnet / 검증 Opus / 종합 Opus)
1. <이번 작업 추천안> (추천) — 생산·분석·검증·종합은 X, 단순 기계적 처리는 Sonnet
2. Fable 중심 — 호스트의 `fable` 별칭 지원을 확인한 뒤 실행
3. Opus 중심 / Sonnet 중심 (원하는 쪽을 적어주세요)
4. 역할별 직접 지정 — 각 단계에 Fable·Opus·Sonnet을 직접 지정 (Haiku는 명시 요청 때만)
(모르면 1번으로 진행할게요)

W2 — wf-lint (본진은 훅 자동 — 이 판은 오케스트레이터가 직접 실행)

🚨 EXECUTE NOW — 명세 스크립트를 {cwd}/.kkirikkiri/runs/<RUN_ID>.workflow.js로 Write한 직후:

Bash("node \"$PLUGIN_ROOT/scripts/wf-lint.js\" .kkirikkiri/runs/<RUN_ID>.workflow.js --models-json '<장부 model_selection JSON>'")

exit≠0이면 실행 금지 — 돌아온 사유(R1R7·model-selection)를 고치고 다시 린트한다. 결과 JSON과 checklist C1C3 자답을 장부 lint_report에 기록. 통과 기록 없이 W3로 가지 않는다.

스크립트(명세) 구성 규칙

1. meta 블록: name(kebab-case), description(한 줄), phases(스테이지별 title) — 순수 리터럴.

2. 스테이지 설계: 기본 순차 phase(pipeline). 배리어는 전체 결과가 필요한 dedup/조기종료에만 parallel().

3. 모델 명시 — 모든 agent() 호출에 model을 핀한다. 예외 없음. 핀을 빼면 세션 모델을 그대로 상속한다 — 팬아웃 전체 비용 폭증.

   스테이지가 하는 일	model	판정 기준
   수집·조사·드래프트·검증(refute) — 팬아웃되는 본체 작업	"sonnet" 추천	선택에 따라 "opus" 등으로 변경 가능
   포맷 변환·필드 추출·목록 정리 — 판단이 없는 기계적 처리	"sonnet" 추천	기계적 처리도 Haiku로 자동 배정하지 않음
   종합·우선순위 판단·최종 합성 — 전체 결과를 한 번에 보는 작업	"opus" 추천	사용자 선택 우선; 불필요한 종합 호출은 추가하지 않음

   • 실제 model과 phase는 선택 맵과 일치하는 문자열 리터럴로 쓴다. 사용할 수 없는 모델은 자동으로 낮추지 말고 다시 선택받는다.

4. adversarial-verify 스테이지 필수 포함: 팬아웃 결과를 종합하기 전, 독립 검증 에이전트가 "이 발견을 반박하라(refute)" 프롬프트로 교차 검증하는 스테이지. schema로 구조화 반환 강제.

5. 구조화 출력: 수집·검증 스테이지는 {schema}로 JSON 반환을 강제(빈 스키마 금지 — 필드 1개 이상). 예산 필드(*_count) 포함, 폭 ≤6.

스크립트 골격 예시

아래 Sonnet/Sonnet/Opus는 추천 조합의 예시다. 실제 생성 시 W1.5의 선택 맵을 각 phase의 model 리터럴에 반영한다.

export const meta = {
  name: 'kkirikkiri-research',
  description: '[목표 한 줄]',
  phases: [
    { title: '수집' },     // Sonnet 팬아웃
    { title: '검증' },     // adversarial-verify (refute)
    { title: '종합' },     // Opus
  ],
}
phase('수집')
const found = await parallel(SOURCES.map(s => () =>
  agent(`[조사 지시] ${s}`, {model: 'sonnet', phase: '수집', schema: FINDING_SCHEMA})))
phase('검증')
const verified = await parallel(found.filter(Boolean).map(f => () =>
  agent(`다음 발견을 반박하라(refute). 확신 없으면 refuted=true: ${JSON.stringify(f)}`,
        {model: 'sonnet', phase: '검증', schema: VERDICT_SCHEMA})))
phase('종합')
return await agent(`검증 통과 결과만 종합 리포트로: ...`, {model: 'opus', phase: '종합'})

W3 — 설계 카드 (Continuation, 사용자 확인 지점)

명세가 W2를 통과하면 Step 6-W로 진행하기 전에 선택한 모델을 포함한 설계 요약표를 보여주고 §A로 실행 승인을 받는다. W1.5에서 이미 확인한 모델은 다시 묻지 않는다:

Workflow 설계 (wf-lint 통과):
| 축 N개 | 폭 5 | 예산 축당 8회 | 수집 Sonnet / 검증 Opus / 종합 Opus | 견적 ~X만 토큰 |
판정 근거: {Step 3.5 rationale 한 줄}

이대로 실행할까요?
1. 네, 실행해주세요 (추천)
2. 축·폭·모델을 조정하고 싶어요
3. 문장으로 직접 적기
(모르면 1번으로 진행할게요)

W4 — 프리플라이트 (실행 직후 1라운드 검사)

1라운드 결과 수신 즉시 누락 축·예산(search_count 합, 캡 80% 초과 시 확장 축소)·계약 위반을 검사하고 장부(budget_used·missing_axes·repair_cycles)에 기록한다. 상세: references/gates.md §1 W4. 완료 시 done-gate를 거쳐 outcome을 채우면 장부가 닫힌다.

Step 5: 팀 구성 제안 + 모델 선택 + 유저 확인 — Agent Teams 경로

이 Step은 Agent Teams 경로 전용. Workflow는 Step 5를 건너뛴다 (W3 설계 카드가 확인 역할).

이 확인 전에 Read("$PLUGIN_ROOT/skills/kkirikkiri/references/model-selection.md"). 기존 확인 블록에 모델 구성 선택을 함께 넣고, 답변 후 task.id별 맵을 런 장부 model_selection에 저장한다. 카드와 실제 호출은 그 맵을 따른다. 이미 지정한 모델은 다시 묻지 않는다.

제안 형식 (Step 5-1: 일반 텍스트로 출력 — 항상 보이게)

이렇게 팀을 구성할게요:

📋 목표: [인터뷰에서 파악한 목표]

팀 구성:
├── 팀장 — 현재 세션 (모델 변경 없음, 로컬)
├── [역할명 1] — [구체적 역할 설명] ([추천 모델] — 한글 설명)
├── [역할명 2] — [구체적 역할 설명] ([추천 모델] — 한글 설명)
└── (선택) [외부 도구] — [역할 설명] (백그라운드)

예상 작업 방식:
1. 팀장이 전체 계획을 세우고 각자 역할을 배분합니다
2. 팀원들이 동시에 작업을 수행합니다
3. 팀장이 결과를 검증하고 통합합니다
4. 최종 리포트를 생성합니다

⏱️ 예상 소요 시간: [기본 3명 10-15분 / 확장 4-5명 15-25분 / 외부 CLI +5-10분]
💡 팁: 빠르게 핵심만 필요하면 팀 규모를 줄일 수 있어요. 대신 깊이가 좀 얕아질 수 있어요.

📁 팀원 역할 파일 (시작 후 생성됩니다):
  {KKIRIKKIRI_DIR}/agents/[역할명1].md
  {KKIRIKKIRI_DIR}/agents/[역할명2].md

용어 표기 (공식 용어 + 한글 설명 병기)

규칙: 공식 용어를 숨기지 않는다(공식 용어 (한글 설명)) / 내부 구현(스폰 호출, 내부 파일 경로)은 노출 금지 / 설명 없이 용어만 던지기 금지