kkirikkiri

Kkirikkiri Team Builder for Codex

One natural language sentence → interview → environment scan → team composition → execution → report

Takes the user's natural language request, composes an AI agent team suited to the purpose, and executes it. This document is not a reference document but an execution instruction. In the Codex chat environment, actually call tools step by step.

This skill is used only when the user explicitly wants delegation/team/parallel work. For simple answers or solo code edits, do not use this skill.

Read first

references/presets.md — presets + interview questions (required for Step 1 matching)
references/interview-guide.md — §A numbered blocks + Elicitation rules (§2a/§2b/§2c)
references/shared-memory.md — shared memory template + DEAD_ENDS
references/team-prompts.md — master of 7 archetypes + Codex spawn mechanism

Read when needed

references/subagent-synthesis.md — 5 steps of dynamic synthesis + 4 domain fleshes (when synthesizing teammate cards)
references/coordination-protocols.md — adaptive spine + gates (when running an interactive team)
references/pm-frameworks.md — when matching product presets (PRD/OST/Strategy Canvas, etc.)
references/metaphor-guide.md — official terms + Korean parallel notation (when showing to the user)
references/validation-guide.md — methods A/B/C (when reinforcing in round 2)
references/output-guide.md — session summary, team save, agent save (Step 8)

Codex rendering rules — AskUserQuestion replacement (`shared/questioning-policy.md §A`)

The Codex CLI has no multiple-choice card UI like AskUserQuestion. All decision questions are done with the §A pattern of outputting a numbered choice block in chat and reading the user's next free-text answer .

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

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

The recommended option is always 1번. The last choice is always "write it directly as a sentence" (free-text escape).
Do not make "I don't know" a separate choice; instead guide with the sentence "If you don't know, I'll proceed with option 1."
kkirikkiri is an Elicitation type. Do not stop at the first surface answer (§2a). If the user deflects, the next question must be concrete/past-behavior anchor(§2b, e.g., "If you've recently done this yourself, what was the most blocked part then?"). Conversely, if the request is already sufficiently specific or they want a team directly, proceed immediately without over-questioning (§2c).

Workflow overview

Step 1:   의도 파악 + 프리셋 매칭
Step 2:   환경 스캔 (병렬)
Step 3:   인터뷰 (§A 번호 블록, Elicitation §2a/§2b)
Step 3.5: 실행 방식 선택 (§A) — 대화형 팀 vs batch(결정론 병렬)
   ├─ [대화형 팀 경로]                       ├─ [batch 경로]
Step 4:   동적 팀 구성 (archetype + 합성)      Step 4-B: 결정론 파이프라인 설계
Step 5:   팀 구성 제안 + 유저 확인              (확인은 실행 직전 한 줄 안내가 대신)
Step 6:   공유 메모리 + 팀원 스폰 + 실행        Step 6-B: 라운드별 병렬 스폰 실행
Step 7:   검증 루프 (방식 A/B/C, 최대 3R)       Step 7-B: 스테이지 내 adversarial-verify
Step 8:   결과 수집 + 리포트                    Step 8-B: 반환값 리포트

Core operating principles

Memory externalization: Important decisions must be recorded in the .kkirikkiri/ file (interactive team path — for batch, script variables play this role).
Errand-runner pattern: Teammates spawn sidecars (spawn_agent) when needed to work in parallel.
Verification loop: Interactive teams use methods A/B/C, batch uses adversarial-verify (refute) within the stage.
build ≠ review family: The model that creates and the model that reviews are different families by default (local → Codex CLI → agy → local Opus adversarial instance fallback).
Keep the team lead local: Do not hand off the critical path to workers.

Step 1: Identify intent + match preset

references/presets.mdMatch a preset using the keywords in (research / development / analysis / content / product / generic).

Count the number of matches for each preset keyword in the input and select the one with the most matches. If tied, judge by context. If it fails, use generic.
Context caution: "competitor analysis"=research, "code analysis"=analysis, "analysis+PRD"=product. "Planning"/"strategy"=strong product match.

File mode (@파일명 or when a path is included): Read the corresponding file → automatically decompose roles (skill file → step-by-step roles, agent file → include team members, general document → match preset to the goal). Reduce the interview to 1-2 questions.

Step 2: Environment scan (parallel)

Scan the environment in parallel with the interview:

python3 "$PLUGIN_ROOT/skills/kkirikkiri/scripts/scan_environment.py" --root "$PWD"

Additional checks (items the script cannot catch, do directly):

External AI CLI: codex(code and large-scale analysis, first priority for cross-model review) / agy(design and UI, follows Gemini CLI) / gjc(multi-model code and cross-review)
Development tools: gh, npm, bun, pnpm
Existing agents: .codex/agents/*.md or ~/.codex/agents/*.md — dynamic matching by description/recommended-for (do not match by filename)
MCP: perplexity If there are tools of this kind, assign them to the Researcher

Scan results (internal variables): codex_cli, antigravity_cli(agy), gjc_cli, gh_cli, package_manager, existing_agents, perplexity_mcp.

Dynamic matching of existing agents (priority)

recommended-for: {프리셋 id} match → match unconditionally
agent_match_keywords(presets.md) and description keywords overlap by 2 or more → match
If both above fail → judge by the semantic relevance between the description and the team goal Matched agents are proposed to the team first as "previously configured specialists" and confirmed by the user.

Step 3: Interview (§A numbered blocks)

Immediately upon entry: Read("$PLUGIN_ROOT/skills/kkirikkiri/references/interview-guide.md") + (when PM is matched) references/pm-frameworks.md.

Output the interview questions for each preset from presets.md as §A numbered blocks in the chat (no AskUserQuestion).

Rules:

Q1 (open question) may be omitted if the user has already answered in natural language. Proceed with Q2/Q3 unless there is a §2c signal (already specific/direct request).
Maximum 3 questions. Never more than 4.
§2a No early termination: Do not adopt the first surface/polite/evasive answer as the conclusion. Continue until the real job is confirmed in the person's own words.
§2b Deflection handling: When deflection is detected, the next question must be concrete/past-behavior anchor(do not ask another abstract question). Maximum 3 probes.
§2c Over-questioning guard: If the request is already sufficiently specific or the user explicitly wants a direct team, proceed by confirming only the defaults without additional questions.
Use official names for terminology (Opus, Sonnet, Codex, etc.) as-is, with a Korean explanation alongside. Do not expose internal implementation (spawn_agent, file paths).
If it is the generic preset, identify the goal with Q1 → select the type with Q2 → continue with the interview for that preset.

When a reply is received, immediately proceed to Step 3.5. Outputting only a response summary and stopping is a workflow violation.

Step 3.5: Choose execution mode (substrate branch)

Principle: Do not decide arbitrarily. The user directly chooses via the §A numbered block.

The actual meaning of the two substrates in Codex:

Interactive team: The local lead (this Codex session) directly drives as an adaptive spine, and when needed spawns, closely reads, and re-directs bounded sidecars (spawn_agent). Shared memory + verification loop (methods A/B/C). Strong for design decisions, deep review, critique, and convergence.
batch (deterministic parallel): Per round, spawn multiple independent sidecars in parallel and run them like a deterministic pipeline, with adversarial-verify within each stage for verification. Do not build shared memory/domain card infrastructure; store intermediate results in variables. Strong for large-scale, independent, multi-source cross-verification, auditing, and migration.

Recommended heuristics:

Signal	Recommendation
Convergence, perspective conflict, design decisions, adversarial review, trade-offs / "decide for me", "review/critique it" / presets product, analysis	Interactive team
Independent, large-scale, deterministic / "all, every, N items" / auditing, migration, multi-source cross-verification / presets research, large-scale development	batch
If ambiguous	Interactive team (small-scale safe default). If clearly large-scale, batch

§A block (recommended option as number 1):

이 작업을 어떤 방식으로 진행할까요?
1. 대화형 팀 (실시간 협업) — 팀원들이 의견을 주고받으며 수렴해요. 설계 결정·깊은 검토·비평에 강해요. (추천: <위 휴리스틱>)
2. batch (대량 자동 병렬 처리) — 수십 개 작업을 병렬로 돌리고 교차 검증해요. 대량 리서치·감사·일괄 작업에 강해요.
(모르면 1번으로 진행할게요)

"Interactive team" → Step 4 / "batch" → Step 4-B.

Step 4: Dynamic team composition (interactive team path)

Immediately upon entry: Read("$PLUGIN_ROOT/skills/kkirikkiri/references/subagent-synthesis.md") + references/team-prompts.md.

Synthesize interview answers + environment scan to compose the final team.

Composition process

Preset default compositionStart from (presets.md).
Adjust via interview: Research "deep and comprehensive" → expand (4-5 people) / Development "tests too" → add Tester (Critic) / Analysis multiple perspectives → subdivide Explorer.
Adjust via environment: Codex CLI → code, large-scale analysis production or verification (Critic, cross-model first priority) / agy → Designer / gjc → code implementation, analysis, or Critic / Perplexity MCP → Researcher tool / gh → Builder.

Team member synthesis procedure (subagent-synthesis.md 5 steps)

[4-A] Role decomposition: Role name / domain / verification method (execution, source, usability, rebuttal, data, delivery, coordination) / output form.
[4-B] archetype matching (team-prompts.md 7 types): Builder / Writer / Designer / Researcher / Analyst / Critic / Leader. Do not assign two archetypes to one person (spawn separately). If ambiguous → Researcher default. Recommend 1 Critic + 1 Leader.
[4-C] Collect 4 types of domain flesh: Identity / stack, methods (table 5-8 rows) / failure patterns (4-6) / KPI actual figures (3-5, no abstractions). For collection, prioritize the LLM's own knowledge → if insufficient, one fetch sidecar.

Model tier rules (strictly comply — Codex interpretation)

"Opus tier / Sonnet tier / Haiku tier" is Role's judgment weight classificationCodex runtime does not model: opus receive pins, so that weight is conveyed through the archetype body + domain card. (External CLI is actual model separation.)

Role	Tier	Notes
Lead (Team Lead)	Opus tier	Unconditional. Keep local
Analysis, critique, final synthesis / core, high-difficulty implementation	Opus tier	All roles involving judgment
General worker (collection, query, draft, simple implementation, standard tasks)	Sonnet tier	Worker default — actively use
Mechanical glue (collection, formatting, extraction, progress summary, dummy data)	Haiku tier	Only work with zero judgment
Code, large-scale analysis (production + review)	Codex CLI	Different base model. If unavailable, local Opus tier fallback
Design/UI	Antigravity CLI(agy)	If unavailable, local Sonnet tier fallback
Code implementation, analysis + cross-review	gajae-code(gjc)	If unavailable, Codex/local fallback

Reviewer fallback chain (different family from build): Codex available → Codex / not available and agy available → agy / neither available → local Opus adversarial review instance (separate context + "Find defects (refute)" prompt, no rubber-stamp).

Team Lead R&R (strictly comply)

The Team Lead does not write code / does not search directly / does not write documents directly. Planning, task distribution, result verification, final integrationonly. If the Team Lead works directly, it is an R&R violation.

Fallback when no CLI

If there is no external CLI, guide the user (without technical terms) → if declined, substitute local (Opus/Sonnet tier); if accepted, provide installation guidance and rescan.

Step 4-B: Deterministic pipeline design (batch path)

Shared memory and domain cards are not created — intermediate results are kept in variables.

Design a parallel sidecar pipeline per round:

Stage design: basic sequential rounds (collection → verification → synthesis). Within each round, independent items are parallelized spawn_agent.
adversarial-verify stage required: before synthesis, an independent verification sidecar uses the "Refute this finding (refute). If not confident, refuted=true" prompt for cross-verification. Enforce structured return (JSON schema) to eliminate parsing uncertainty.
Tier guide: fanned-out collection, draft, verification (refute) = Sonnet tier / mechanical formatting, extraction = Haiku tier / synthesis, prioritization, final composition = Opus tier (1–2 times per round). The verification stage is also Sonnet tier (volume proportional to fan-out).

Skeleton:

[수집]  독립 소스마다 spawn_agent("explorer", "[조사 지시] {source} → JSON 스키마")  // 병렬
[검증]  발견마다 spawn_agent("reviewer", "다음 발견을 반박하라(refute)... {finding}")  // 병렬
[종합]  로컬에서 검증 통과 결과만 종합 리포트로

Design complete → Skip Step 5 and immediately go to Step 6-B. One-line guide for the user:

대량 병렬 처리로 구성했어요. 백그라운드로 돌리고 완료되면 정리해서 보여드릴게요.

Step 5: Team composition proposal + user confirmation (interactive team path)

Output the final team composition as a plain-text tree and get confirmation via the §A numbered block.

이렇게 팀을 구성할게요:

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

팀 구성:
├── 팀장 — [역할 설명] (Opus — 가장 똑똑한 모델, 로컬)
├── [역할명 1] — [역할 설명] (Sonnet — 균형형 모델)
├── [역할명 2] — [역할 설명] (Sonnet — 균형형 모델)
└── (선택) [외부 CLI] — [역할 설명] (백그라운드)

작업 방식: 팀장이 계획·배분 → 팀원 병렬 작업 → 팀장이 검증·통합 → 최종 리포트
⏱️ 예상 소요: [기본 3명 10-15분 / 확장 4-5명 15-25분 / 외부 CLI +5-10분]

이대로 진행할까요?
1. 네, 시작해주세요 (추천)
2. 팀원을 조정하고 싶어요
3. 처음부터 다시
(모르면 1번으로 진행할게요)

Notation: official term + Korean explanation together (Opus (가장 똑똑한 모델)). Internal implementation (spawn_agent, file paths) is not exposed. Do not throw out terms without explanation.

Response handling:

"Yes, please start" → immediately Step 6 (create team_name + initialize shared memory + domain cards + spawn).
"I want to adjust" → ask via §A which part to change and re-run Step 4.
"Start over from the beginning" → return to Step 1.

Step 6: Shared memory + teammate spawn + execution (interactive team path)

Upon entry: Read("$PLUGIN_ROOT/skills/kkirikkiri/references/coordination-protocols.md") (adaptive spine + gate). Agent Teams always uses active coordination. Bulk/independent/deterministic already branched to batch in Step 3.5.

6-1. team_name + directory

RAND4=$(openssl rand -hex 2 2>/dev/null || printf '%04x' $((RANDOM % 65536)))
team_name="kkirikkiri-{preset}-$(date +%Y%m%d-%H%M)-${RAND4}"   # 예: kkirikkiri-research-20260620-1430-a3f2
mkdir -p ".kkirikkiri/teams/${team_name}/agents" ".kkirikkiri/teams/${team_name}/archive" ".kkirikkiri/shared/saved-teams"

Inform the user of the session handle (team_name + working directory).

6-2. Initialize shared memory (externalize memory)

Upon entry: Read("$PLUGIN_ROOT/skills/kkirikkiri/references/shared-memory.md").

Write the 3 types of files using the shared-memory.md template (including the DEAD_ENDS section). Only proceed after confirming all three files are complete. Spawning is prohibited while uninitialized (unrecoverable if context is lost).

.kkirikkiri/teams/{team_name}/TEAM_PLAN.md      (팀 목표·구성·태스크 분배)
.kkirikkiri/teams/{team_name}/TEAM_PROGRESS.md  (빈 진행 로그)
.kkirikkiri/teams/{team_name}/TEAM_FINDINGS.md  (빈 발견 + DEAD_ENDS)

6-2.5. Domain card synthesis (archetype + 4 kinds of flesh)

Before spawning teammates, save each teammate's domain card synthesized into .kkirikkiri/teams/{team_name}/agents/{역할명}.md(100–150 lines). Procedures/few-shot in subagent-synthesis.md [3][4]. If even one of the 4 kinds of domain flesh (identity, stack, failure patterns, KPI actual figures) is missing, it falls into generalities.

6-3. Teammate spawn

Spawn each teammate with spawn_agent. In the prompt, include archetype body path + domain card path + first task + shared memory pathonly (do not copy-paste the card/archetype body itself). For mechanism details, see team-prompts.md "Codex spawn mechanism".

spawn_agent({
  agent_type: "explorer",   // Researcher/Analyst→explorer, Builder/Writer/Designer→worker, Critic→reviewer
  prompt: `
당신은 [역할명]입니다. ([archetype] + [도메인])
## 1. 마스터 행동 원칙
Read("$PLUGIN_ROOT/skills/kkirikkiri/references/team-prompts.md") 의 "# [archetype]" 섹션을 읽고 내재화.
## 2. 도메인 카드
Read(".kkirikkiri/teams/{team_name}/agents/{역할명}.md")
## 3. 첫 태스크
[구체적 지시]
## 4. 공유 메모리
- .kkirikkiri/teams/{team_name}/TEAM_PLAN.md / TEAM_PROGRESS.md / TEAM_FINDINGS.md
## 5. 팀 정보
- 팀장: [leader] (로컬) / 다른 팀원: [목록]
`
})

Do not spawn a team lead — the local (this Codex session) is the team lead. Internalize the team lead R&R + active coordination (coordination-protocols.md) and drive it directly.

6-4. External CLI execution (Codex/agy/gjc)

For roles assigned to an external CLI, run in the background via the runner (if any) in $PLUGIN_ROOT/skills/kkirikkiri/scripts/or by invoking the CLI directly. --provideris what was confirmed in the environment scan (codex | antigravity | gjc). If it is a review role, make the prompt **"not 'review this' but 'find flaws in the following deliverable and refute'"**. agy 1.0.x has a non-TTY stdout bug, so if results are empty, fall back to local. Record results in TEAM_FINDINGS.md.

6-5. Active driving (no collect-at-end)

The team lead (local) reads each sidecar final note carefully as it arrives → judges verification/contradiction/gaps → decides the next move (re-instruct / delegate cross-verification / spawn a runtime expert). No fire-and-forget. Trigger the gate (independent opinions + judge) only at forks (irreversible/value conflicts) — for details, see coordination-protocols.md.

Step 6-B: batch execution (batch path)

Run the Step 4-B pipeline round by round.

Each round: parallelize independent items spawn_agent. Collect the results into a variable.
The adversarial-verify round must be run before synthesis (refute + JSON schema).
Synthesize locally using only results that passed verification.
Stage error → fix only that stage and rerun. Do not create TeamCreate, shared memory, or domain cards.
Complete → Step 8-B.

Step 7: Verification loop (interactive team path)

Do not finish in 1 round. Repeat until quality is sufficient (max 3 rounds).

7-1. Quality assessment (after round 1 is complete — always performed)

The team lead (local) reads all 3 shared memory files before integration and assesses:

Goal achievement / completeness / accuracy (sources, evidence, tests) / consistency (contradictions among team members).

7-2. Automatic assessment → decide the approach

목표달성 FAIL → 방식 B (전체 재구성)
일관성 FAIL   → 방식 C (부분 교체)
완성도/정확성 FAIL → 방식 A (팀 유지 + 보강)
라운드 >= 3   → 중단, 최선 결과로 리포트

7-3. User confirmation (§A)

(1라운드 결과 + 부족한 부분 설명) 보강할까요?
1. 네, 보강해주세요 (추천) — 부족한 부분 집중 보완. 시간 더 걸려요.
2. 이 정도면 괜찮아요 — 현재 결과를 최종 리포트로.
3. 처음부터 다시 — 팀 해산 후 새로 구성.
(모르면 1번으로 진행할게요)

"Reinforce" → Read("$PLUGIN_ROOT/skills/kkirikkiri/references/validation-guide.md") then run approach A/B/C.
"It's fine" → Step 8.
"From the start" → Step 1.

7-4. Maximum rounds

Maximum 3 rounds. If still insufficient after 3 rounds, honestly disclose the limitations and report the best result.

Step 8: Collect results + report

8-1. Clean up sidecars + deliver results

If a sidecar is running, terminate it. To the user:

끼리끼리 팀 작업이 완료되었어요!
📋 팀: [구성 요약]  🎯 목표: [목표]  📄 결과: [리포트 경로]  🔄 라운드: [수]
[핵심 요약 2-3줄]

8-2. Session summary + save (optional)

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

Output a session summary (what was effective and why) in natural language + also leave it in TEAM_REPORT.md.
Save team: ask via §A .kkirikkiri/shared/saved-teams/{team_name}.md create.
Save agent: ask via §A to refine and save the team member that worked well as .codex/agents/{역할명}.md(including recommended-for). For save procedure/conflict handling, see output-guide.md.
Work record (.kkirikkiri/teams/{team_name}/) is retained (for later reference). Delete if the user wants.

Step 8-B: batch report

Report the return value in the 8-1 format, but replace "team composition" with "processing scale (number of agents, stages)". If the same task will be repeated, inform that the pipeline can be reused. The session summary is the same as 8-2.

Error handling

Team member unresponsive/underperforming: 1 time → ignore / 2 times → check progress / 3 times → replace only that role.
Sidecar result quality low: Team member/team lead compensates directly or re-instructs another sidecar.
CLI execution failure: Substitute with local (Opus tier) (if it is a review role, a local Opus adversarial instance). Do not expose technical errors to the user as-is — at the level of "we replaced it with an internal AI due to an external tool issue."
Interview interrupted: Terminate immediately, do not create a team. "You can restart anytime."

Never do

Do not create a team without user confirmation (for batch, a one-line notice right before execution serves this role)
Do not arbitrarily decide the substrate without the Step 3.5 user choice
Don't use presets as fixed values — dynamically adjust via interview + environment scan
Don't replace official terms (Opus/Sonnet/Codex/agy/gjc) with metaphors — use them as-is with Korean alongside. Only internal implementation (spawn_agent/file paths) stays hidden
Don't assume AskUserQuestion cards — Codex doesn't have them. Only §A numbered blocks
Don't adopt the first surface/avoidance answer as the real need (§2a). For deflect, use concrete/past-action anchors (§2b)
Don't over-question an already specific request (§2c)
Don't ask 4 or more interview questions
Don't assign the Haiku tier to roles requiring judgment — limited to mechanical glue
Don't make formal review within the same family the default — Codex→agy→local Opus adversarial. When it's a fallback, use a refute prompt
Don't make the team lead write code/search/docs (only the final integration report is the exception)
Don't spawn a team lead — local is the team lead
Don't spawn team members without initializing shared memory
Don't omit the shared memory path from team member prompts
Don't fire-and-forget the sidecar — carefully read intermediate outputs + re-instruct
Don't deliver results to the user without verification
Don't repeat 4 or more rounds — maximum 3 rounds
Don't fill domain cards by copy-pasting the archetype body — archetypes go in team-prompts.md, cards get the 4 domain essentials
Don't omit any of the 4 domain essentials
Don't force two archetypes onto one team member — spawn separately
Don't start with an external fetch when it can be synthesized from the LLM's own knowledge

Always do it

For every §A numbered block: option 1 marked "(recommended)" + "if unsure, go with 1" guidance + "write it directly as a sentence" escape
When proposing team composition, explain roles in everyday terms + official terms with Korean alongside + estimated time required
User confirmation before team execution (for batch, notify right before execution)
In the environment scan, check execution substrate availability + Codex/agy/gjc + existing agents
Include an adversarial-verify (refute) stage in the batch pipeline
If preset matching fails, switch to a generic interview
Immediately after team creation, initialize the 3 shared memory files (including DEAD_ENDS)
Before spawning team members, synthesize domain cards (archetype + 4 essentials, 100–150 lines)
Include both the archetype body path + domain card path in team member prompts
Internalize team lead R&R + active coordination (no collect-at-end)
After round 1 completes, always judge quality (goal/completeness/accuracy/consistency)
Read all 3 shared memory files before the team lead's final integration
When an existing agent is found, confirm with the user whether to reuse it
On file mode (@filename) input, analyze the file → auto-decompose roles
After work completes, confirm with the user whether to save the team