Goaljaby

골잡이 (goaljaby) — Codex 판

PRD를 Codex /goal 운영 계약으로 변환하는 브릿지 스킬. 사용자 언어로 검토 문서 5종 + PLANS.md ExecPlan을 생성하고, 검토 요약을 대화창에 띄운 뒤 승인을 받으면 복사해서 바로 실행할 수 있는 /goal 명령을 건넨다.

Read these first:

• references/templates.md
• references/compact-strategy.md
• references/task-type-classifier.md
• references/task-type-templates.md
• references/policy-excerpt.md (언어 §1·§2·§3·§5 + 질문 §1·§2a·§2c 번들 발췌)

질문 정책은 shared/questioning-policy.md (특히 §A 렌더링 규칙 + §0~§2)을 상속한다.

이 스킬을 쓰는 이유

PRD가 "무엇을 만들지"라면, /goal은 "어떻게 끝났음을 증명하고 실패에서 어떻게 돌아올지"의 운영 계약이다. 두 단계 사이의 빈 구간(VALIDATION/RECOVERY/PLAN 작성 + 4,000자 컴팩트 + 사용자 언어 검토 + 골 시작)을 매번 손으로 채우는 대신 자동화한다.

첫 실행 설정 (수동 — 훅 아님)

Codex 플러그인은 hooks를 지원하지 않는다. 원판 goaljaby의 setup/setup.sh(첫 실행 안내·업데이트 체크)는 이식하지 않는다. 별도 부트스트랩이 필요하면 사용자가 직접 실행하는 1회 단계로만 안내한다(현재 이 스킬은 외부 부트스트랩이 필요 없다). 이 스킬은 PRD 읽기·검토 문서 쓰기 외에 아무 부수효과도 만들지 않는다.

원판(본진)과의 차이 (왜 Codex 판이 따로 있나)

원판 goaljaby는 호스트 CLI 전용이다. 마지막에 어시스턴트가 응답의 마지막 줄로 /goal을 출력하면 호스트가 그 줄을 다음 턴 입력으로 처리해 골 루프를 자동 시작한다. Codex에는 이 메커니즘이 없다 — 스킬이 슬래시 명령을 마지막 줄로 "자동 발사"할 수 없다.

대신 Codex에는 네이티브 /goal (codex 0.139에서 goals 기능 stable=true)과 /plan 모드, 그리고 PLANS.md/ExecPlan 관례가 있다. 그래서 이 판은:

• 원판의 검토 문서 5종(VALIDATION/RECOVERY/PLAN/PROGRESS + goal-command)을 그대로 output_lang(사용자 언어)으로 생성하고,
• 추가로 PLANS.md ExecPlan 파일(Progress / Validation / Decision-Log 섹션)을 생성해 본진 5종을 그 위에 매핑한다.
• 마지막에 슬래시 명령을 자동 발사하는 대신, 사용자가 복사해서 실행할 /goal 명령 한 줄을 제시한다.
• objective는 ≤ 4,000자로 유지하고, 파일 포인터 패턴을 쓴다 — objective 본문이 ./PLANS.md를 가리킨다.

언어 정책 (shared/language-policy.md · references/policy-excerpt.md 상속)

출력 언어 = 사용자 요청 언어(output_lang). 본문을 읽기 전에 §1 자동 감지로 잠근다: 요청 텍스트의 언어 → 없으면 직전 대화 언어 → 둘 다 없으면(빈 호출) 영어. 한국 제작이라고 한국어를 기본값으로 두지 말 것.

생성되는 6종 문서(5종 + PLANS.md)는 output_lang 본문 + 영어 식별자(파일명·명령·약어·슬롯). 핵심은 언어가 아니라 "사용자가 읽고 검토할 수 있어야 승인에 의미가 있다" 이다 — 그래서 한국어 사용자에겐 한국어로, 영어 사용자에겐 영어로 생성한다. 검토 불가능한 외국어 문서는 승인 게이트를 무의미하게 만든다.

• output_lang ∈ {ko, en}: 헤딩까지 1급 지원(결정론적 검증, Step 7 #7). 헤딩 세트는 references/templates.md의 §헤딩 맵 참조.
• 그 외 언어: 본문·헤딩을 번역하되 결정론적 헤딩 검증은 섹션 존재 검사로 폴백하고 그 한계를 Step 8 요약에 한 줄로 알린다(침묵 폴백 금지).
• 식별자(파일명/명령/약어/{SLOT}/PRD·SDD)와 PROTECTED_CLAUSES 앵커, PLANS.md의 ExecPlan 표준 섹션명(Progress/Validation/Decision-Log)은 번역하지 않는다(§2).

입력

• 필수: PRD 디렉토리 경로 (절대 경로 권장, 예: /Users/<username>/my-project/PRD/). 최소 1개 .md 파일, acceptance criteria 포함 권장.
• 선택: 작업 유형(자동 추정 가능), 골 엄격도, 출력 위치

상대 경로(./PRD/)도 동작하지만 세션 cwd가 달라지면 깨질 수 있으므로 절대 경로가 안전하다.

PRD가 없으면 show-me-the-prd 스킬로 위임한다 (Step 0). 인수 파싱:

• 인수 없음 → §A 번호 블록으로 PRD 디렉토리 경로를 묻는다 (아래 Step 0-B). PRD 자체가 없으면 show-me-the-prd 위임 옵션을 1번으로 제시.
• 절대/상대 경로 → 그 경로를 prd_dir로 사용.
• "분석 [경로]" → 기존 산출물 검토 모드 (덮어쓰기 전 확인).
• PRD 디렉토리에 references/ + sources.json(디자인 레퍼런스, show-me-the-prd v0.10+ 산출물)이 있으면 Step 1에서 감지해 Step 5에서 PLAN/VALIDATION에 승계한다. 없으면 아무 변화 없음 — 재수집하지 않는다.

출력

항상 생성되는 6개 파일 (모두 output_lang 본문)

[output_dir]/
├── VALIDATION.md      — 필수 검증 / 마일스톤별 검증 / 완료 기준 매핑 / 완료로 보지 않는 조건
├── RECOVERY.md        — 기본 원칙 / 실패 루프 / 재시도 한계 / scope 잠금 / 방향 재확인 / 되돌리기 규칙
├── PLAN.md            — 목표 / 참조 문서 / 마일스톤(≤5) / 최종 완료 기준
├── PROGRESS.md        — 빈 초기 템플릿 + Step 8에서 상단에 4줄 요약 prepend됨
├── goal-command.md    — `/goal` 실행 본문 (`output_lang`, 4,000자 강제, ./PLANS.md 포인터)
└── PLANS.md           — Codex ExecPlan (Progress / Validation / Decision-Log) — 위 5종을 한 파일에 매핑

검토 요약은 별도 파일로 만들지 않는다. Step 8에서 대화창에 직접 표시하고, 핸드오프 용도로 PROGRESS.md와 PLANS.md의 Progress 섹션 상단에만 4줄 요약을 prepend한다.

보장사항:

• goal-command.md 본문은 항상 4,000자 이하 (문자 수 기준, byte 아님).
• 5종 검토 문서 + PLANS.md는 모두 output_lang 헤딩 + 본문. 감지 언어와 다른 언어의 헤딩이 잔존하면 Step 7 검증에서 실패 → 결과물 폐기 (ko↔en 교차 검증, 그 외 언어는 섹션 존재 검사). 단 PLANS.md의 ExecPlan 표준 섹션명(Progress/Validation/Decision-Log)은 식별자로 보존.
• PROTECTED_CLAUSES 5종은 한국어/영어 OR 정규식으로 검증 (compact-strategy.md 참조).

본진 5종 → PLANS.md ExecPlan 매핑

PLANS.md는 5종을 대체하지 않는다 — Codex /goal이 한 파일만 읽어도 컨텍스트를 잡도록 5종을 한 곳에 모은 운영 진실 원천이다. 상세는 여전히 개별 파일(VALIDATION.md 등)에 위임한다.

워크플로우 (10단계)

언어 잠금 (먼저): 워크플로우 시작 전 shared/language-policy.md §1로 output_lang을 감지·고정한다. 이후 모든 산출물(6종 문서·헤딩·대화 요약·Step 10 핸드오프 안내)은 output_lang을 따른다. 식별자/슬롯/PROTECTED_CLAUSES 앵커/PLANS.md ExecPlan 표준 섹션명은 제외(§2).

Step 0: PRD 사전 확인 + 입력 분기

타입: Bash + §A 번호 블록 (조건부)

PRD 디렉토리 인수와 내용을 확인한다.

0-A) 인수 있음 + 디렉토리 존재 + .md 1개 이상

• Bash로 acceptance criteria 패턴(- [ ], "Acceptance Criteria", "완료 판정", "completion criteria") 확인. 없으면 Step 1에서 경고하지만 진행은 계속한다.
• 기존 산출물(VALIDATION.md / RECOVERY.md / PLAN.md / PROGRESS.md / goal-command.md / PLANS.md 중 하나라도) 존재 시 §A 번호 블록:
  • 1. 덮어쓰기 — 기존 6종을 새로 생성 (추천)
  • 2. 이어가기 — 기존 PROGRESS.md/PLANS.md만 읽고 /goal 재실행을 안내
  • 3. 취소
• → Step 1 진입.

0-B) 인수 없음 OR 디렉토리 없음 OR .md 0개

§A 번호 블록 (질문: "PRD가 아직 없네요. 어떻게 시작할까요?"):

• 1. show-me-the-prd로 지금 만든다 (추천) — show-me-the-prd 스킬로 위임. PRD 폴더 생성 후 그 경로로 0-A 재진입
• 2. 수동 작성한 PRD 폴더 경로를 알려준다 — 경로 받아 0-A 재진입
• 3. PRD 없이 한 줄 목표만 입력하고 진행 — 임시 PRD.md 생성 (한 문장 goal + 자동 추출 1~2 acceptance), light 엄격도 + 마일스톤 1개 강제
• 4. 취소

§A 원칙: PRD에서 추론 가능한 건 묻지 않는다(§1). 경로가 인수로 이미 들어왔으면 0-B를 건너뛴다(§2c — 직접 답이 이미 있음).

Step 1: PRD 분석

타입: prompt + Bash

PRD 본문을 읽고 추출:

• acceptance criteria (없으면 사용자에게 경고)
• non-goals
• open questions
• 가정 원장 감지: PRD에 가정 원장이나 잔여 가정 목록이 있으면 원문 위치와 항목별 내용·근거·영향·확인 상태를 보존한다. 미확정 가정을 확정된 요구사항으로 바꾸지 않는다. 원장이 없으면 새 원장이나 추가 인터뷰를 강제하지 않는다.
• 작업 유형 추정 (한/영 키워드 동시 매칭 — references/task-type-classifier.md 참조)
• 디자인 레퍼런스 감지: PRD 디렉토리에 references/ 폴더 + sources.json이 있으면(show-me-the-prd v0.10+ 산출물) sources.json의 스타일 키워드(query.style)와 keep 이미지 목록을 기억한다. 없으면 이 항목은 이후 단계에서 전부 무시 — 재수집하지 않는다.

Step 2: 운영 컨텍스트 확정 (자동)

타입: 자동 (인터뷰 없음)

이 판은 Codex CLI(0.139+, goals 기능 stable) 전용이다. CLI 분기 인터뷰는 없고 target_cli = codex로 자동 고정한다. 결과적으로:

• goal-command.md는 4,000자 강제 (objective character 한도).
• objective는 ./PLANS.md를 가리키는 파일 포인터 패턴을 쓴다.
• RECOVERY.md는 codex /goal 기준으로 작성한다. codex /goal에서 사람 결정 대기는 "자체 수정을 멈추고 PROGRESS.md/Decision-Log에 보고 후 사용자 결정을 기다린다"로 표현한다 (Step 5 CLI 슬롯 치환 참조).
• Step 10에서 어시스턴트는 슬래시 명령을 자동 발사하지 않는다 — 사용자가 복사해 실행할 /goal 명령 한 줄을 제시한다. (대안: codex /plan 모드도 안내.)

Step 3: 작업 유형 + 검증 방식 + 엄격도

타입: §A 번호 블록 (1~2회로 압축)

• 작업 유형 6종: 기능 구현 / 버그 수정 / UI 구현 / 문서 집필 / 마이그레이션 / eval 개선
  • 자동 추정값을 **1번(추천)**에 둔다. 추정 신뢰도가 약하면 6개를 평평하게 나열(task-type-classifier.md).
• 자동 검증 방식 (여러 개면 1,3처럼): 단위 테스트 / 빌드 / 수동 재현 / 스크린샷 / 섹션 자가 검토 / eval 스코어 / 통합 / 패리티
• 엄격도: 1. 표준(추천) / 2. 엄격 / 3. 가벼움

§A 원칙: PRD에서 작업 유형이 명백하면(예: 추정 점수 압도적) 굳이 묻지 말고 기본값으로 확인만 한다(§1·§2c).

Step 4: 마일스톤 추출 + 사용자 확정

타입: prompt + §A 번호 블록

PRD acceptance criteria를 그룹화하여 마일스톤 초안 생성. ≤5개 강제. 5개 초과 시 우선순위 상위 5개만 1차로 가져가고 나머지는 메모로 분리.

사용자에게 마일스톤 목록을 §A "예시 프리뷰"(번호 트리)로 먼저 보여주고 확정:

예시 프리뷰
  1. {M1_NAME} — 완료: {M1_COMPLETION}
  2. {M2_NAME} — 완료: {M2_COMPLETION}
  ...

질문: 이 마일스톤으로 진행할까요?
1. 그대로 진행 (추천)
2. 문장으로 직접 수정 요청

Step 5: 6개 파일 슬롯 채움

타입: rag + generate

references/templates.md의 템플릿(VALIDATION/RECOVERY/PLAN/PROGRESS/goal-command + PLANS.md ExecPlan)을 PRD 내용에 맞춰 슬롯 치환하고, 모든 헤딩·본문을 output_lang으로 렌더링한다(템플릿은 한국어로 표기돼 있으니 §헤딩 맵으로 옮긴다. PLANS.md ExecPlan 표준 섹션명은 영어 그대로 유지). 작업 유형에 따라 강조 항목이 달라진다 — 매핑 표는 references/task-type-templates.md 참조.

치환 시 빈 슬롯({...})이 잔존하지 않도록 확인. 빈 슬롯이 남으면 해당 줄 자체 제거.

CLI 슬롯은 codex 전용 고정 문구로 치환한다:

• {RETRY_LIMIT_ACTIONS} / {RETRY_PAUSE_PHRASE} → "자체 수정을 멈추고 PROGRESS.md(및 PLANS.md의 Decision-Log)에 실패 내역을 기록한 뒤 사용자의 결정을 기다린다." (codex /goal은 일시정지 대신 보고-후-대기로 운영한다.)

가정 원장 승계 (Step 1에서 감지된 경우에만):

• PLAN.md 참조 문서 목록에 원장 위치를 남기고, 기존 항목 식별자가 있으면 그대로 사용한다.
• 결과에 영향을 주는 미확정 가정은 VALIDATION.md의 해당 완료 기준에 확인 방법을 연결한다. 지금 확인할 수 없으면 미검증으로 남기며 통과로 처리하지 않는다.
• 실행을 막는 가정과 아직 확인하지 못한 항목은 PROGRESS.md의 리스크·다음 단계(및 PLANS.md ## Decision-Log)에 남긴다. 이미 확인된 항목을 다시 미결로 만들지 않는다.
• goal-command.md에는 원장 전체를 복사하지 않는다. 기존 PLAN/VALIDATION/PLANS 문서 참조를 통해 전달하여 4,000자 예산을 유지한다.

디자인 레퍼런스 승계 (Step 1에서 감지된 경우 + UI 관련 작업 유형일 때만):

• PLAN.md 참조 문서 목록에 PRD/references/ (디자인 레퍼런스 — 스타일: {query.style}) 한 줄 추가. PLANS.md ## 참조 문서에도 같은 줄을 반영한다.
• VALIDATION.md 시각 검증(또는 수동 확인 절차)에 "UI 산출물이 PRD/references/의 레퍼런스 스타일 방향({스타일 키워드})과 부합하는가 — 구현 전 이미지를 열어 방향 확인" 항목 1개 추가.
• 저작권 가드 1줄 승계: "레퍼런스 이미지는 방향 참고 전용 — 산출물에 복사/재게시 금지."
• goal-command.md 본문에는 넣지 않는다(4,000자 예산 보호) — 골 세션은 PLAN/VALIDATION/PLANS를 읽으므로 그쪽에서 전달된다.

멀티에이전트 게이트 승계 (kkirikkiri 설치 시에만): ls -d ~/.codex/plugins/cache/*/kkirikkiri*/ 2>/dev/null (또는 $PLUGIN_ROOT/../kkirikkiri-codex)로 kkirikkiri 플러그인이 설치돼 있는지 1회 확인한다. 있으면 RECOVERY.md의 기본 원칙에 다음 1항목을 추가한다 — 골 세션이 스스로 서브에이전트 팀을 만들 때도 같은 규율을 받게 하는 결선이다:

• "골 작업 중 런타임 서브에이전트 팬아웃·팀 실행을 사용할 때는 kkirikkiri 게이트(coordination-protocols.md)를 따른다: 팀원 정의에는 경계 블록(tools·write_scope·stop·effort) 명시, 검증 역할은 read-only, 갈림길(비가역·가치충돌)에서만 독립 의견 + 심판 게이트 발동. 설치된 kkirikkiri에 wf-lint.js가 있으면 워크플로 스크립트는 발사 전 node <kkirikkiri>/scripts/wf-lint.js <script> 통과 필수."
• PLANS.md ## Decision-Log 상단 운영 규칙 요약에도 "팀 실행은 RECOVERY.md의 kkirikkiri 게이트를 따른다" 한 줄을 반영한다. kkirikkiri가 없으면 이 항목을 조용히 건너뛴다 — 경고·설치 권유 없이 무동작 (graceful fallback, 미설치 환경을 깨지 않는다).