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` 커맨드 통합) | 입력 | 동작 | |---|---| | `[자연어 요청]` | 의도 파악 → 인터뷰 → 팀 생성 → 실행 (Step 1부터) | | `@파일명` 포함 | 파일 모드 (Step 1 "파일 모드 처리") | | (인자 없음) | 아래 인터랙티브 메뉴를 §A 번호 블록으로 출력 | **인자 없음 — 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 패턴으로 한다. ```text (예시 프리뷰 — 구조화 정보를 보여줄 때만. 단순 선호 질문이면 생략) 질문: <한 줄 질문> 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` 박스가 실제 트리거다:** | Step 진입 | Read 대상 | |----------|-----------| | Step 3 진입 (추가 인터뷰 필요 시) | `interview-guide.md` + `metaphor-guide.md` | | Step 4 진입 (Agent Teams 경로) | `subagent-synthesis.md` + `team-prompts.md` | | Step 4-W 진입 (Workflow 경로) | `execution-shapes.md` (실행형태 5종 + 토너먼트) | | Step 5 / W1.5 (모델 선택) | `model-selection.md` | | Step 6 진입 (Agent Teams 경로) | `coordination-protocols.md` (적응형 척추) | | Step 6-2 진입 | `shared-memory.md` | | Step 6-2.6 / W2 / 7-2 (게이트 차단 시) | `gates.md` | | Step 6-4 (옵트인 준비기 사용 시) | `prepare-team-pilot.md` | | Step 7-6 진입 | `validation-guide.md` | | Step 8-2 직후 | `output-guide.md` | > 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 잡은 **알림 없이 죽거나 행에 걸릴 수 있다**. 규정: | 항목 | 값 | |---|---| | 점검 방법 | 산출물/잡 디렉토리 파일의 **mtime + 크기만** 확인 (내용 읽기 금지 — 컨텍스트 오염 방지) | | 점검 시점 | spawn +10분, 이후 작업 전환점마다 | | 사망 판정 | mtime 정지 ≥10분 AND 완료 알림 없음 | | 조치 | ① 재가동 1회("추가 조사 금지, 지금까지 것만 정리 반환") ② 실패 시 메인스레드 폴백 ③ 장부 `liveness_events`에 기록 | ### 게이트 5종 — 이 판에서는 오케스트레이터가 직접 실행한다 본진은 wf-lint·card-lint·done-gate·스폰 경계·장부 생성을 **플러그인 훅**이 자동 실행한다. Codex 플러그인은 선언형 훅을 지원하지 않으므로, 같은 게이트를 **아래 Step에서 스스로 실행하는 체크리스트 단계**로 수행한다. 스크립트는 본진과 동일하다(`$PLUGIN_ROOT/scripts/`). exit≠0이면 진행을 멈추고 위반 사유를 고친 뒤 다시 돈다. 상세 규칙·해소 방법: `Read("$PLUGIN_ROOT/skills/kkirikkiri/references/gates.md")`. | 게이트 | 본진 훅 | 이 판의 실행 지점 | 실행 | |---|---|---|---| | gate-init | UserPromptSubmit | **사전 준비 1.** | 장부 파일을 직접 생성 (아래 스키마) | | gate-wf | PreToolUse(Workflow) | **W2** (발사 전) | `node "$PLUGIN_ROOT/scripts/wf-lint.js" <spec.js> --models-json '<model_selection>'` | | gate-spawn | PreToolUse(Agent) | **6-4 스폰 직전, 팀원마다** | 스폰 프롬프트 본문에 ① 허용 도구 또는 read-only ② `write_scope:` 또는 read-only ③ `stop: maxTurns N, done_when "…"` 3종이 있는지 자가 점검 + 다른 팀원의 write_scope와 교집합 없는지(C5@spawn) + `node "$PLUGIN_ROOT/scripts/model-selection.js"`로 모델 대조. 통과 시 장부 `declarations[]`에 기록, 실패 시 `boundary_violations[]`에 기록하고 프롬프트를 고친 뒤 재시도 | | gate-card | PostToolUse(Write) | **6-2.6** (카드 저장 직후) | `node "$PLUGIN_ROOT/scripts/card-lint.js" --dir "{KKIRIKKIRI_DIR}/agents"` | | gate-done | Stop | **7-2 / 7-W 4 / 8 진입 직전** | `node "$PLUGIN_ROOT/scripts/done-gate.js" --repo <work.repo> --report <work.report> --contract <work.contract>` | - 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.에서 실행:** ```bash 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) ``` ```json {"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 참조) | 프리셋 | 키워드 | |--------|--------| | research | 조사, 리서치, 찾아줘, 알아봐줘, 검색, 분석해줘, 비교해줘 | | development | 만들어줘, 구현해줘, 개발해줘, 코딩해줘, 기능 추가, 리팩토링 | | analysis | 분석해줘, 파악해줘, 구조 분석, 코드 분석, 리뷰해줘, 검토해줘 | | content | 문서, README, 작성해줘, 써줘, 블로그, 가이드, 튜토리얼 | | product | PRD, 전략, 기획, OKR, 로드맵, 가설, 검증, 디스커버리, 페르소나, GTM, 런칭, 경쟁분석, 시장분석, 비즈니스모델, 가격, 포지셔닝, North Star, 사용자스토리, 스프린트 | ### 입력 모드 | 모드 | 입력 예시 | 처리 | |------|----------|------| | **자연어** (기본) | "리서치 팀 만들어줘" | 키워드 매칭 → 프리셋 → 인터뷰 | | **파일 지정** | "@insane-research 팀으로 실행해줘" | 파일 분석 → 역할 자동 분해 | #### 파일 모드 처리 사용자 입력에 `@파일명` 또는 파일 경로가 포함되면: 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 — 지금까지 발견한 것들