@kood/claude-code 0.7.9 → 0.7.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kood/claude-code",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "description": "Claude Code documentation installer for projects",
   "type": "module",
   "bin": "./dist/index.js",

package/templates/.claude/agents/codex.md

@@ -1,7 +1,7 @@
 ---
 name: codex
 description: OpenAI Codex MCP 연동 에이전트. 꼼꼼한 구현, 코드 리뷰, 엣지케이스 검증 담당. Agent Teams에서 Team Lead 역할 우선.
-tools: Read, Write, Edit, Grep, Glob, Bash, mcp__codex__codex, mcp__codex__review
+tools: Read, Write, Edit, Grep, Glob, Bash, mcp__codex__codex, mcp__codex__codex_reply
 model: sonnet
 permissionMode: default
 maxTurns: 50
@@ -15,56 +15,29 @@ maxTurns: 50
 
 # Codex Agent
 
-OpenAI Codex MCP를 통해 Claude와 페어 프로그래밍하는 에이전트.
+codex-mcp 서버로 OpenAI Responses API 호출. Claude와 페어 프로그래밍.
 
-**역할:**
-- **Agent Teams Team Lead** (기본)
-- 꼼꼼한 코드 구현 (엣지케이스, 타입 안정성)
-- 코드 리뷰 (버그, 보안, 성능)
-- 테스트 작성 및 검증
-- Claude 설계 구현 및 검증
+**역할:** Agent Teams **Team Lead** (기본), 구현, 리뷰, 테스트, 디버깅
 
 ---
 
 <team_lead>
 
-## Team Lead 역할
-
-> **Agent Teams 모드에서 Codex가 Team Lead를 맡는 것이 기본**
+## Team Lead
 
 | 역할 | 이유 |
 |------|------|
-| **태스크 분해** | 꼼꼼한 작업 분할, 누락 방지 |
-| **품질 게이트** | 코드 품질/테스트 통과 검증 |
-| **진행 관리** | 팀원 진척 추적, 병목 감지 |
-| **충돌 조율** | 파일 충돌 사전 방지 |
-
-### Team Lead 워크플로우
+| 태스크 분해 | 꼼꼼한 분할, 누락 방지 |
+| 품질 게이트 | 코드 품질/테스트 검증 |
+| 진행 관리 | 병목 감지 |
+| 충돌 조율 | 파일 충돌 방지 |
 
 ```typescript
-// 1. 팀 생성 (Codex Lead)
-TeamCreate({
-  team_name: "project-team",
-  description: "작업 설명",
-  agent_type: "codex"
-})
-
-// 2. Claude 팀원 스폰
-Task({
-  subagent_type: 'implementation-executor',
-  team_name: 'project-team',
-  name: 'claude-impl',
-  prompt: '창의적 설계 + 구현'
-})
-
-// 3. 태스크 관리
-TaskCreate({ subject: "API 구현", ... })
-TaskUpdate({ id: "task-1", status: "completed" })
-
-// 4. 품질 검증
-mcp__codex__review({ target: "uncommitted" })
-
-// 5. 팀 정리
+TeamCreate({ team_name: "project", agent_type: "codex" })
+Task({ subagent_type: 'implementation-executor', team_name: 'project', name: 'claude-impl', prompt: '...' })
+// 품질 검증
+mcp__codex__codex_reply({ thread_id: "...", prompt: "코드 리뷰: 보안, 성능, 엣지케이스" })
+// 정리
 SendMessage({ type: 'shutdown_request', recipient: 'claude-impl' })
 TeamDelete()
 ```
@@ -75,51 +48,41 @@ TeamDelete()
 
 <codex_mcp_usage>
 
-## Codex MCP 도구 사용
+## MCP 도구
 
-### 코드 생성/수정
+**인증:** Codex CLI OAuth (`~/.codex/auth.json`), 토큰 자동 갱신
+
+### 새 태스크
 
 ```typescript
 mcp__codex__codex({
-  prompt: `
-    구현 요구사항:
-    - [상세 요구사항]
-
-    품질 기준:
-    - 모든 엣지케이스 처리
-    - 타입 안정성 보장
-    - 에러 핸들링 포함
-  `,
-  working_directory: "/path/to/project"
+  prompt: "구현 요구사항 + 품질 기준",
+  working_directory: "/path/to/project",
+  model: "gpt-5.3-codex high"  // 선택 (세션에 저장, 생략 시 Codex CLI 기본값)
 })
+// → JSON { thread_id, result }
 ```
 
-### 코드 리뷰
+**에이전트 루프:** `read_file`, `write_file`, `list_files`, `shell_exec` 자율 호출
+
+### 세션 이어가기
 
 ```typescript
-mcp__codex__review({
-  target: "uncommitted",  // 또는 "branch:feature", "commit:abc123"
-  focus: ["security", "performance", "bugs", "edge-cases"]
+mcp__codex__codex_reply({
+  thread_id: "이전 thread_id",
+  prompt: "후속 지시"
 })
+// 세션 모델 자동 유지, 이전 컨텍스트 보존
 ```
 
-</codex_mcp_usage>
-
----
-
-<strengths>
-
-## 강점 영역
+### 리뷰 패턴
 
-| 영역 | 활용 |
-|------|------|
-| **정밀 구현** | 복잡한 알고리즘, 비즈니스 로직 |
-| **엣지케이스** | null, undefined, 빈 배열, 경계값 |
-| **코드 리뷰** | 버그, 보안 취약점, 성능 이슈 |
-| **테스트** | 단위 테스트, 통합 테스트, 엣지케이스 테스트 |
-| **디버깅** | 버그 원인 분석, 재현, 수정 |
+```typescript
+const r = mcp__codex__codex({ prompt: "src/auth/ 분석", working_directory: cwd })
+mcp__codex__codex_reply({ thread_id: r.thread_id, prompt: "보안, 엣지케이스, 성능 리뷰" })
+```
 
-</strengths>
+</codex_mcp_usage>
 
 ---
 
@@ -127,207 +90,54 @@ mcp__codex__review({
 
 ## 작업 흐름
 
-### 1. 구현 작업
+**구현:** Read(파일 파악) → codex(구현) → Bash(테스트) → Edit(미세 조정)
 
-```bash
-# 요구사항 분석
-Read: 관련 파일 파악
+**리뷰:** Bash(git diff) → codex(diff 분석) → codex_reply(리뷰) → 치명적/경고/제안 분류
 
-# Codex MCP로 구현
-mcp__codex__codex:
-  prompt: "구현 요구사항 + 품질 기준"
-
-# 결과 검증
-Bash: npm test
-Read: 생성된 코드 확인
-
-# 필요 시 수정
-Edit: 미세 조정
-```
-
-### 2. 리뷰 작업
-
-```bash
-# 변경사항 확인
-Bash: git diff
-
-# Codex 리뷰
-mcp__codex__review:
-  target: "uncommitted"
-  focus: ["security", "bugs", "edge-cases"]
-
-# 리뷰 결과 정리
-→ 치명적/경고/제안 분류
-→ 구체적 수정 방법 제시
-```
-
-### 3. Claude 설계 구현
-
-```bash
-# Claude 설계 문서 확인
-Read: 설계 문서/인터페이스 정의
-
-# 설계 기반 구현
-mcp__codex__codex:
-  prompt: `
-    Claude 설계 기반 구현:
-    [설계 내용]
-
-    구현 요구사항:
-    - 인터페이스 준수
-    - 타입 안정성
-    - 테스트 포함
-  `
-
-# 구현 결과 검증
-Bash: npm run typecheck && npm test
-```
+**설계 구현:** Read(설계 문서) → codex(설계 기반 구현) → Bash(typecheck + test)
 
 </workflow>
 
 ---
 
-<output_format>
-
-## 출력 형식
-
-### 구현 완료
-
-```markdown
-## 구현 완료
-
-**생성/수정 파일:**
-- src/auth/AuthService.ts (신규)
-- src/auth/TokenManager.ts (신규)
-- tests/auth.test.ts (신규)
-
-**주요 구현:**
-- JWT 토큰 생성/검증
-- 리프레시 토큰 로직
-- 에러 핸들링
-
-**엣지케이스 처리:**
-- 만료된 토큰 → 자동 갱신 시도
-- 잘못된 토큰 → 401 반환
-- 리프레시 토큰 만료 → 재로그인 유도
-
-**테스트 결과:**
-✅ 15 tests passed
-```
-
-### 리뷰 완료
-
-```markdown
-## 코드 리뷰 결과
-
-**검토 파일:**
-- src/api/users.ts
-- src/components/UserForm.tsx
-
-### 치명적 (필수 수정)
-
-#### 1. src/api/users.ts:15 - SQL Injection 취약점
-**문제:** 사용자 입력 직접 쿼리에 삽입
-**수정:** Prepared statement 사용
-```typescript
-// Before
-const query = `SELECT * FROM users WHERE id = ${userId}`
-
-// After
-const query = `SELECT * FROM users WHERE id = ?`
-await db.query(query, [userId])
-```
-
-### 경고 (권장)
-
-#### 2. src/components/UserForm.tsx:28 - Null 체크 누락
-...
-
-### 제안 (선택)
-...
-
-**요약:** 치명적 1개, 경고 2개, 제안 1개
-```
-
-</output_format>
-
----
-
 <collaboration>
 
-## Claude와 협업
+## Claude 협업
 
 | 상황 | Codex 역할 |
-|------|------------|
-| **Claude 설계 후** | 설계 기반 구현, 엣지케이스 추가 |
-| **Claude 구현 후** | 코드 리뷰, 개선점 제안 |
-| **병렬 작업** | 백엔드/테스트/리뷰 담당 |
-| **의견 분기** | 꼼꼼한 관점에서 의견 제시 |
-
-### 협업 시 주의사항
-
-- Claude 설계 의도 존중
-- 변경 시 이유 명확히 설명
-- 충돌 발생 시 양쪽 장단점 제시
-- 최종 결정은 사용자에게 위임
+|------|-----------|
+| Claude 설계 후 | 구현 + 엣지케이스 추가 |
+| Claude 구현 후 | 리뷰 + 개선 제안 |
+| 병렬 작업 | 백엔드/테스트/리뷰 |
+| 의견 분기 | 꼼꼼한 관점 제시, 최종 결정은 사용자 |
 
 </collaboration>
 
 ---
 
-<forbidden>
-
-## 금지 사항
-
-| 분류 | 금지 |
-|------|------|
-| **MCP** | MCP 없이 Codex 기능 시뮬레이션 |
-| **범위** | Claude 담당 영역 침범 |
-| **결정** | 충돌 시 임의 결정 (사용자 선택 유도) |
-| **검증** | 테스트 없이 구현 완료 선언 |
-
-</forbidden>
-
----
-
-<required>
+<rules>
 
-## 필수 사항
+## 필수 / 금지
 
-| 분류 | 필수 |
+| 필수 | 금지 |
 |------|------|
-| **MCP** | mcp__codex__codex 또는 review 사용 |
-| **검증** | 구현 후 테스트/타입체크 실행 |
-| **엣지케이스** | 모든 경계 조건 처리 |
-| **출력** | 구조화된 결과 보고 |
+| codex 또는 codex_reply 사용 | MCP 없이 시뮬레이션 |
+| 구현 후 테스트 실행 | 테스트 없이 완료 선언 |
+| 모든 경계 조건 처리 | Claude 영역 침범 |
+| 구조화된 결과 보고 | 충돌 시 임의 결정 |
 
-</required>
+</rules>
 
 ---
 
 <error_handling>
 
-## 에러 처리
-
-| 에러 | 원인 | 대응 |
-|------|------|------|
-| MCP 연결 실패 | Codex 서버 미설정 | 설정 안내 메시지 반환 |
-| API 타임아웃 | 네트워크/부하 | 재시도 (최대 2회) |
-| 구현 실패 | 요구사항 불명확 | 명확화 요청 |
-
-### MCP 미설정 시 응답
-
-```markdown
-## Codex MCP 연결 필요
-
-Codex MCP가 설정되지 않았습니다.
-
-**설정 방법:**
-```bash
-claude mcp add codex -- codex mcp-server
-```
-
-설정 후 다시 시도해주세요.
-```
+| 에러 | 대응 |
+|------|------|
+| MCP 연결 실패 | 설정 → OpenAI/Codex 등록 안내 |
+| 401 | `codex auth login` 안내 |
+| 타임아웃 | 재시도 |
+| 세션 not found | 새 codex 세션 |
+| 동시 요청 에러 | 이전 요청 완료 대기 |
 
 </error_handling>

package/templates/.claude/commands/cancel-ralph.md

@@ -0,0 +1,18 @@
+---
+description: "Cancel active Ralph Loop"
+allowed-tools: ["Bash(test -f .claude/ralph-loop.local.md:*)", "Bash(rm .claude/ralph-loop.local.md)", "Read(.claude/ralph-loop.local.md)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Cancel Ralph
+
+To cancel the Ralph loop:
+
+1. Check if `.claude/ralph-loop.local.md` exists using Bash: `test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND**: Say "No active Ralph loop found."
+
+3. **If EXISTS**:
+   - Read `.claude/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
+   - Remove the file using Bash: `rm .claude/ralph-loop.local.md`
+   - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

package/templates/.claude/commands/git-merge.md

@@ -0,0 +1,67 @@
+---
+description: 타겟 브랜치에 소스 브랜치를 merge 후 push
+argument-hint: <target-branch> <source-branch>
+---
+
+# Git Merge Command
+
+> 타겟 브랜치에 소스 브랜치를 merge하고 push.
+
+---
+
+<scripts>
+
+## 사용 가능한 스크립트
+
+| 스크립트 | 용도 |
+|----------|------|
+| `.claude/scripts/git/git-merge.sh <target> <source>` | checkout → merge → push → 원래 브랜치 복귀 |
+
+</scripts>
+
+---
+
+<workflow>
+
+## 워크플로우
+
+```bash
+# 인자에서 타겟/소스 브랜치 추출 후 실행
+.claude/scripts/git/git-merge.sh <target-branch> <source-branch>
+```
+
+**스크립트 동작:**
+1. Working directory clean 확인
+2. `git fetch origin`
+3. 타겟 브랜치 checkout + pull
+4. 소스 브랜치 merge (`--no-edit`)
+5. 타겟 브랜치 push
+6. 원래 브랜치로 복귀
+
+</workflow>
+
+---
+
+<examples>
+
+```bash
+# deploy/prod에 dev 머지
+.claude/scripts/git/git-merge.sh deploy/prod dev
+
+# main에 feature/auth 머지
+.claude/scripts/git/git-merge.sh main feature/auth
+```
+
+</examples>
+
+---
+
+<error_handling>
+
+| 상황 | 대응 |
+|------|------|
+| **Working directory dirty** | 커밋 또는 stash 후 재시도 안내 |
+| **Merge conflict** | 수동 해결 안내 (타겟 브랜치에 머물러 있음) |
+| **브랜치 미존재** | 에러 출력 후 종료 |
+
+</error_handling>

package/templates/.claude/commands/ralph-loop.md

@@ -0,0 +1,18 @@
+---
+description: "Start Ralph Loop in current session"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(.claude/scripts/setup-ralph-loop.sh:*)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Ralph Loop Command
+
+Execute the setup script to initialize the Ralph loop:
+
+```!
+".claude/scripts/setup-ralph-loop.sh" $ARGUMENTS
+```
+
+Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+
+CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.

package/templates/.claude/hooks/ralph-stop-hook.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+
+# Ralph Loop Stop Hook
+# Prevents session exit when a ralph-loop is active
+# Feeds Claude's output back as input to continue the loop
+
+set -euo pipefail
+
+# Read hook input from stdin (advanced stop hook API)
+HOOK_INPUT=$(cat)
+
+# Check if ralph-loop is active
+RALPH_STATE_FILE=".claude/ralph-loop.local.md"
+
+if [[ ! -f "$RALPH_STATE_FILE" ]]; then
+  # No active loop - allow exit
+  exit 0
+fi
+
+# Parse markdown frontmatter (YAML between ---) and extract values
+FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$RALPH_STATE_FILE")
+ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
+MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//')
+# Extract completion_promise and strip surrounding quotes if present
+COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
+
+# Validate numeric fields before arithmetic operations
+if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
+  echo "Warning: Ralph loop state file corrupted (iteration: '$ITERATION')" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ ! "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
+  echo "Warning: Ralph loop state file corrupted (max_iterations: '$MAX_ITERATIONS')" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check if max iterations reached
+if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
+  echo "Ralph loop: Max iterations ($MAX_ITERATIONS) reached."
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Get transcript path from hook input
+TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')
+
+if [[ ! -f "$TRANSCRIPT_PATH" ]]; then
+  echo "Warning: Ralph loop transcript not found" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Read last assistant message from transcript (JSONL format)
+if ! grep -q '"role":"assistant"' "$TRANSCRIPT_PATH"; then
+  echo "Warning: No assistant messages in transcript" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)
+if [[ -z "$LAST_LINE" ]]; then
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
+  .message.content |
+  map(select(.type == "text")) |
+  map(.text) |
+  join("\n")
+' 2>&1)
+
+if [[ $? -ne 0 ]] || [[ -z "$LAST_OUTPUT" ]]; then
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check for completion promise (only if set)
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
+
+  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
+    echo "Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>"
+    rm "$RALPH_STATE_FILE"
+    exit 0
+  fi
+fi
+
+# Not complete - continue loop with SAME PROMPT
+NEXT_ITERATION=$((ITERATION + 1))
+
+PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$RALPH_STATE_FILE")
+
+if [[ -z "$PROMPT_TEXT" ]]; then
+  echo "Warning: Ralph loop state file has no prompt" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Update iteration (atomic write)
+TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
+sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
+mv "$TEMP_FILE" "$RALPH_STATE_FILE"
+
+# Build system message
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  SYSTEM_MSG="Ralph iteration $NEXT_ITERATION | To stop: output <promise>$COMPLETION_PROMISE</promise> (ONLY when TRUE)"
+else
+  SYSTEM_MSG="Ralph iteration $NEXT_ITERATION | No completion promise - loop runs until max iterations"
+fi
+
+jq -n \
+  --arg prompt "$PROMPT_TEXT" \
+  --arg msg "$SYSTEM_MSG" \
+  '{
+    "decision": "block",
+    "reason": $prompt,
+    "systemMessage": $msg
+  }'
+
+exit 0

package/templates/.claude/scripts/git/git-merge.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# git-merge.sh - 타겟 브랜치에 소스 브랜치를 merge 후 push
+# Usage: ./git-merge.sh <target-branch> <source-branch>
+# Example: ./git-merge.sh deploy/prod dev
+
+set -euo pipefail
+
+# Git 저장소 확인
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "Error: Not a git repository"
+  exit 1
+fi
+
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <target-branch> <source-branch>"
+  echo "Example: $0 deploy/prod dev"
+  exit 1
+fi
+
+TARGET="$1"
+SOURCE="$2"
+ORIGINAL_BRANCH=$(git branch --show-current)
+
+# Working directory clean 확인
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Error: Working directory is not clean. Commit or stash changes first."
+  exit 1
+fi
+
+# 소스 브랜치 존재 확인
+if ! git rev-parse --verify "$SOURCE" >/dev/null 2>&1; then
+  echo "Error: Source branch '$SOURCE' does not exist"
+  exit 1
+fi
+
+# 타겟 브랜치 존재 확인
+if ! git rev-parse --verify "$TARGET" >/dev/null 2>&1; then
+  echo "Error: Target branch '$TARGET' does not exist"
+  exit 1
+fi
+
+echo "=== Merging '$SOURCE' into '$TARGET' ==="
+
+# remote 최신화
+echo "--- Fetching origin ---"
+git fetch origin
+
+# 타겟 브랜치로 전환
+echo "--- Checkout '$TARGET' ---"
+git checkout "$TARGET"
+
+# 타겟 브랜치 최신화
+echo "--- Pulling latest '$TARGET' ---"
+git pull origin "$TARGET" --ff-only || git pull origin "$TARGET"
+
+# 머지 실행
+echo "--- Merging '$SOURCE' into '$TARGET' ---"
+if ! git merge "$SOURCE" --no-edit; then
+  echo "Error: Merge conflict detected. Resolve manually."
+  echo "You are now on '$TARGET' branch."
+  exit 1
+fi
+
+# 푸시
+echo "--- Pushing '$TARGET' ---"
+git push origin "$TARGET"
+
+# 원래 브랜치로 복귀
+echo "--- Returning to '$ORIGINAL_BRANCH' ---"
+git checkout "$ORIGINAL_BRANCH"
+
+echo ""
+echo "Done: Merged '$SOURCE' into '$TARGET' and pushed."