@wooojin/forgen 0.2.1 → 0.3.1

package/commands/docker.md

@@ -1,6 +1,17 @@
 ---
 name: docker
-description: This skill should be used when the user asks to "docker,container,컨테이너,dockerfile,도커,docker-compose". Containerization with Docker, Dockerfile optimization, and compose configuration
+description: This skill should be used when the user asks to "docker,container,컨테이너,dockerfile,도커,docker-compose". Docker 컨테이너화 -- Dockerfile 최적화, Compose 구성, 보안 강화
+argument-hint: "[컨테이너화 대상]"
+model: sonnet
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Write
+  - Edit
+  - mcp__forgen-compound__compound-search
+  - mcp__forgen-compound__compound-read
 triggers:
   - "docker"
   - "container"
@@ -9,7 +20,6 @@ triggers:
   - "도커"
   - "docker-compose"
 ---
-<!-- forgen-managed -->
 
 <Purpose>
 Docker를 활용한 컨테이너화를 체계적으로 수행합니다.
@@ -17,107 +27,35 @@ Docker를 활용한 컨테이너화를 체계적으로 수행합니다.
 Docker Compose 구성, 헬스 체크까지 컨테이너 라이프사이클 전체를 다룹니다.
 </Purpose>
 
-<Steps>
-1. **의존성 분석**: 애플리케이션의 런타임 요구사항을 파악합니다
-   - 런타임 환경 (Node.js, Python, Go 등)
-   - 시스템 의존성 (네이티브 바이너리, 라이브러리)
-   - 환경 변수 목록 및 기본값
-   - 포트 매핑 (애플리케이션 포트, 디버그 포트)
-   - 볼륨 마운트 필요 사항 (데이터 영속성, 설정 파일)
-   - 외부 서비스 의존성 (DB, Redis, 메시지 큐)
-
-2. **Dockerfile 작성**: 최적화된 Dockerfile을 구성합니다
-   - 베이스 이미지 선택 (alpine vs slim vs distroless)
-   - 멀티스테이지 빌드 적용 (빌드 스테이지 / 런타임 스테이지)
-   - 레이어 캐싱 최적화 (변경 빈도 낮은 것부터 순서)
-     * 시스템 의존성 설치
-     * package.json / lockfile 복사 + npm install
-     * 소스 코드 복사 + 빌드
-   - .dockerignore 설정 (node_modules, .git, 테스트 파일)
-   - 비루트 사용자 설정 (보안)
-   - 시그널 핸들링 (SIGTERM graceful shutdown)
-   - HEALTHCHECK 명령 설정
-
-3. **이미지 최적화**: 이미지 크기와 보안을 개선합니다
-   - 레이어 수 최소화 (RUN 명령 결합)
-   - 불필요한 파일 제거 (빌드 도구, 캐시, 문서)
-   - 프로덕션 의존성만 설치 (--omit=dev)
-   - 이미지 크기 측정 및 목표 설정
-   - 보안 스캔 (Trivy, Docker Scout)
-   - 이미지 태깅 전략 (semver, git SHA, latest)
+<Compound_Integration>
+## 시작 전: 이전 Docker 구성 패턴 검색
 
-4. **Docker Compose 구성**: 멀티 컨테이너 환경을 정의합니다
-   - 서비스 정의 (app, db, cache, proxy)
-   - 네트워크 구성 (서비스 간 통신)
-   - 볼륨 정의 (데이터 영속성)
-   - 환경 변수 관리 (.env 파일, 인라인)
-   - 의존성 순서 (depends_on + healthcheck)
-   - 개발/프로덕션 오버라이드 분리
-   - 리소스 제한 설정 (CPU, 메모리)
-
-5. **헬스 체크 및 모니터링**: 컨테이너 상태를 관리합니다
-   - HEALTHCHECK 엔드포인트 구현 (/health, /ready)
-   - Liveness probe vs Readiness probe 구분
-   - 로그 수집 구성 (stdout/stderr → 로그 시스템)
-   - 메트릭 노출 (Prometheus 엔드포인트)
-   - Graceful shutdown 구현 (SIGTERM 처리)
-   - 재시작 정책 설정 (restart: unless-stopped)
-</Steps>
-
-## 에이전트 위임
-
-`executor` 에이전트(Sonnet 모델)에 위임하여 Docker 구성을 구현합니다:
+컨테이너화를 시작하기 전에 compound-search MCP 도구로 유사한 런타임/애플리케이션의 과거 Docker 구성을 검색합니다.
 
 ```
-Agent(
-  subagent_type="executor",
-  model="sonnet",
-  prompt="DOCKER TASK
-
-Docker 컨테이너화를 구현하세요.
-
-Application: [애플리케이션 설명]
-Runtime: [Node.js / Python / Go / etc.]
-Services: [필요한 외부 서비스 목록]
-
-Docker Checklist:
-1. Dockerfile 작성 (멀티스테이지, 최적화)
-2. .dockerignore 설정
-3. Docker Compose 구성 (개발/프로덕션)
-4. 헬스 체크 설정
-5. 보안 설정 (비루트 사용자, 이미지 스캔)
-6. 볼륨 및 네트워크 구성
-
-Output: Docker 구성 파일 및 문서:
-- Dockerfile
-- .dockerignore
-- docker-compose.yml (dev/prod)
-- 이미지 크기 리포트
-- 실행 명령 가이드"
-)
+compound-search("[런타임명 또는 애플리케이션 타입 키워드]")
+compound-search("Docker 최적화")
 ```
 
-## External Consultation (Optional)
-
-executor 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자문할 수 있습니다.
-
-### Protocol
-1. **자체 Docker 구성을 먼저 완료** -- 독립적으로 구현
-2. **검증을 위한 자문** -- Claude Task 에이전트를 통해 구성 교차 확인
-3. **비판적 평가** -- 외부 제안을 맹목적으로 수용하지 않음
-4. **우아한 폴백** -- 위임이 불가능할 경우 절대 차단하지 않음
+검색 결과가 있으면 의존성 분석 단계 전에 표시합니다:
+```
+이전 Docker 구성 패턴:
+- [애플리케이션명]: [베이스 이미지] → 최종 크기 [N]MB (날짜: YYYY-MM-DD)
+- 주요 최적화: [레이어 전략, 보안 설정 등]
+- 주의사항: [이전에 발견된 문제나 트릭]
+```
 
-### 자문이 필요한 경우
-- 복잡한 멀티스테이지 빌드
-- 프로덕션 수준의 보안 강화
-- 오케스트레이션 (Kubernetes 연동)
-- 네이티브 의존성이 있는 이미지 최적화
+이전 구성을 출발점으로 삼아 중복 탐색을 줄이고, 검증된 패턴을 재사용합니다.
+완료 후 주요 최적화 내용과 이미지 크기를 compound에 기록합니다.
+</Compound_Integration>
 
-### 자문을 생략하는 경우
-- 단순 Node.js/Python 컨테이너화
-- 개발 환경용 Docker Compose
-- 잘 알려진 이미지 패턴
-- 기존 Dockerfile의 경미한 수정
+<Steps>
+1. **의존성 분석**: 런타임 환경, 시스템 의존성, 포트, 볼륨, 외부 서비스
+2. **Dockerfile 작성**: 멀티스테이지, 레이어 캐싱, 비루트 사용자, HEALTHCHECK
+3. **이미지 최적화**: 레이어 최소화, 프로덕션 의존성만, 보안 스캔, 크기 측정
+4. **Docker Compose 구성**: 서비스, 네트워크, 볼륨, 환경 변수, 오버라이드
+5. **헬스 체크 및 모니터링**: probe, 로그 수집, graceful shutdown, 재시작 정책
+</Steps>
 
 ## Docker 체크리스트
 
@@ -129,11 +67,12 @@ executor 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자
 - [ ] 레이어 캐싱이 최적화됨
 - [ ] HEALTHCHECK가 설정됨
 
-### 보안 (4개)
+### 보안 (5개)
 - [ ] 이미지 취약점 스캔 완료
 - [ ] 최소 권한 원칙 적용 (비루트, 읽기 전용 파일시스템)
-- [ ] 시크릿이 이미지에 포함되지 않음
+- [ ] 시크릿이 이미지에 포함되지 않음 (ENV, ARG, COPY 모두 확인)
 - [ ] 불필요한 도구/패키지가 제거됨
+- [ ] 빌드 시 민감 레이어 캐시 방지
 
 ### 운영 (4개)
 - [ ] Graceful shutdown이 구현됨 (SIGTERM)
@@ -154,7 +93,28 @@ executor 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자
 | Node.js | < 150MB | node:20-alpine |
 | Python | < 200MB | python:3.12-slim |
 | Go | < 30MB | gcr.io/distroless/static |
-| Rust | < 30MB | debian:bookworm-slim (빌드) + scratch (런타임) |
+| Rust | < 30MB | debian:bookworm-slim + scratch |
+| Java | < 250MB | eclipse-temurin:21-jre-alpine |
+
+<Failure_Modes>
+## 피해야 할 실패 패턴
+
+### 이미지 빌드
+- **:latest 태그 사용**: 빌드 재현 불가능. 항상 `node:20.11.1-alpine3.19` 같이 고정.
+- **단일 스테이지**: 빌드 도구가 런타임에 포함됨. 멀티스테이지 필수.
+- **레이어 순서 오류**: 소스 코드를 lockfile보다 먼저 배치하면 캐시 무효화.
+
+### 보안
+- **root 실행**: `USER` 지시어 없이 실행. 컨테이너 탈출 시 호스트 루트 권한 획득 위험.
+- **시크릿 하드코딩**: ENV/ARG/RUN에 시크릿 포함. BuildKit `--mount=type=secret` 사용.
+- **ARG로 시크릿 전달**: 중간 레이어에 남음. BuildKit secret mount 사용.
+
+### 구성
+- **.dockerignore 누락**: node_modules, .git, .env가 이미지에 포함됨.
+- **SIGTERM 미처리**: 10초 후 SIGKILL로 강제 종료. 데이터 손실 가능.
+- **HEALTHCHECK 누락**: 애플리케이션 응답 불능 상태 미감지.
+- **Compose 비밀번호 하드코딩**: .env 파일 또는 Docker secrets 사용.
+</Failure_Modes>
 
 <Output>
 ```
@@ -166,95 +126,25 @@ Runtime: [Node.js 20]
 Image Size: [최종 이미지 크기]
 
 DOCKERFILE / Dockerfile
--------------------------
-# Build stage
-FROM node:20-alpine AS builder
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --omit=dev
-COPY . .
-RUN npm run build
-
-# Runtime stage
-FROM node:20-alpine AS runtime
-RUN addgroup -g 1001 -S appgroup && \
-    adduser -S appuser -u 1001 -G appgroup
-WORKDIR /app
-COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
-COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
-USER appuser
-EXPOSE 3000
-HEALTHCHECK --interval=30s --timeout=3s \
-  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
-CMD ["node", "dist/index.js"]
-
 DOCKER COMPOSE / docker-compose.yml
---------------------------------------
-services:
-  app:
-    build: .
-    ports: ["3000:3000"]
-    depends_on:
-      db: { condition: service_healthy }
-    environment:
-      DATABASE_URL: postgres://user:pass@db:5432/app
-  db:
-    image: postgres:16-alpine
-    volumes: ["pgdata:/var/lib/postgresql/data"]
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready"]
-
 IMAGE ANALYSIS / 이미지 분석
-------------------------------
-Total Size: 142MB
-Layers: 8
-Base Image: node:20-alpine (45MB)
-Dependencies: 85MB
-Application: 12MB
-
 SECURITY SCAN / 보안 스캔
----------------------------
-Vulnerabilities: 0 CRITICAL, 0 HIGH, 2 MEDIUM
-Recommendation: [조치 사항]
 ```
 </Output>
 
 <Policy>
-- 베이스 이미지에 항상 고정 태그를 사용합니다 (latest 금지)
-- 프로덕션 이미지에서 반드시 비루트 사용자로 실행합니다
-- 시크릿은 절대 이미지에 포함하지 않습니다 (빌드 시에도)
-- 이미지 크기를 정기적으로 모니터링합니다
-- 보안 스캔을 CI/CD에 통합하여 취약한 이미지 배포를 차단합니다
-- Graceful shutdown을 반드시 구현하여 데이터 손실을 방지합니다
+- 베이스 이미지에 항상 고정 태그 사용 (latest 금지)
+- 프로덕션 이미지에서 비루트 사용자 실행 필수
+- 시크릿은 절대 이미지에 포함하지 않음
+- 멀티스테이지 빌드 기본 적용
+- .dockerignore 필수 작성
+- Graceful shutdown 필수 구현
 </Policy>
 
 ## 다른 스킬과의 연동
-
-**CI/CD 연동:**
-```
-/forgen:ci-cd Docker 이미지 빌드 및 푸시 파이프라인
-```
-CI에서 Docker 이미지 자동 빌드/배포
-
-**보안 리뷰 연동:**
-```
-/forgen:security-review Dockerfile 및 이미지
-```
-Docker 구성의 보안 취약점 점검
-
-**성능 연동:**
-```
-/forgen:performance 컨테이너 리소스 사용량 분석
-```
-컨테이너의 리소스 최적화
-
-## Best Practices
-
-- **작은 이미지** -- 불필요한 것을 빼서 크기를 줄임
-- **멀티스테이지** -- 빌드 도구를 런타임에 포함하지 않음
-- **캐시 활용** -- 레이어 순서를 변경 빈도 기준으로 정렬
-- **보안 우선** -- 비루트, 최소 권한, 시크릿 분리
-- **헬스 체크** -- 컨테이너 상태를 자동으로 모니터링
+- `/forgen:ci-cd` -- Docker 이미지 빌드/배포 파이프라인
+- `/forgen:security-review` -- Dockerfile/이미지 보안 점검
+- `/forgen:performance` -- 컨테이너 리소스 최적화
 
 <Arguments>
 ## 사용법

package/commands/forge-loop.md

@@ -0,0 +1,215 @@
+---
+name: forge-loop
+description: This skill should be used when the user asks to "forge-loop, 포지루프, 끝까지, don't stop". 주어진 작업을 PRD(User Story)로 분해하고, 모든 수용 기준이 충족될 때까지 반복 실행합니다.
+argument-hint: "[task description]"
+model: inherit
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Agent
+  - Edit
+  - Write
+triggers:
+  - "forge-loop"
+  - "포지루프"
+  - "끝까지"
+  - "don't stop"
+  - "완료될 때까지"
+  - "루프로 실행"
+---
+
+<Purpose>
+주어진 작업을 User Story + 수용 기준으로 분해하고, 모든 스토리가 검증을 통과할 때까지
+ch-planner -> ch-executor -> ch-verifier 사이클을 반복합니다.
+스토리 하나가 완료되면 멈추지 않고 즉시 다음 스토리로 진행합니다.
+사용자에게 보고하는 시점은 "전부 완료", "에스컬레이션", "컨텍스트 한계" 세 가지뿐입니다.
+</Purpose>
+
+<Compound_Integration>
+## Compound-In: 관련 패턴 로드
+
+루프 시작 전 + 각 스토리 시작 전에 compound-search를 수행합니다.
+
+```
+compound-search 도구로 작업 키워드를 검색하세요.
+예: compound-search("TypeScript", "테스트", "리팩토링") 등
+```
+
+## Compound-Out: 세션 종료 시 패턴 추출
+
+모든 스토리 완료 후:
+- 실패 후 성공한 패턴 -> troubleshoot 후보
+- 반복 사용된 접근법 -> pattern 후보
+- 아키텍처 결정 -> decision 후보
+</Compound_Integration>
+
+<Steps>
+## Phase 1: PRD 설정
+
+### PRD 구조
+```json
+{
+  "task": "{$ARGUMENTS}",
+  "stories": [
+    {
+      "id": "US-001",
+      "title": "스토리 제목",
+      "description": "As a {role}, I want {feature} so that {value}",
+      "acceptanceCriteria": ["구체적이고 테스트 가능한 기준"],
+      "passes": false,
+      "attempts": 0,
+      "dependencies": []
+    }
+  ]
+}
+```
+
+### 수용 기준 품질 규칙
+
+| 금지 (일반적) | 교체 (구체적) |
+|--------------|-------------|
+| "코드가 컴파일된다" | "npm run build가 exit 0으로 완료된다" |
+| "테스트가 통과한다" | "npm test의 {test-name}이 PASS한다" |
+| "기능이 동작한다" | "POST /api/users에 {payload}를 보내면 201이 반환된다" |
+
+### 상태 파일 저장 (필수 — Stop 훅 연동)
+
+PRD 확정 직후 **반드시** `~/.forgen/state/forge-loop.json`에 저장:
+
+```bash
+mkdir -p ~/.forgen/state
+cat > ~/.forgen/state/forge-loop.json <<EOF
+{"active":true,"startedAt":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","stories":[
+  {"id":"US-001","title":"...","passes":false,"attempts":0}
+]}
+EOF
+```
+
+이 파일이 있어야 Claude가 중간에 멈추지 않도록 Stop 훅이 차단합니다.
+스토리 완료 시 `passes: true`로 업데이트. 전체 완료는 Stop 훅이 자동 처리.
+
+## Phase 2: 스토리 실행 루프
+
+### 2-1. Compound-In (스토리별)
+해당 스토리의 키워드로 compound-search 실행. 관련 패턴을 Planner에게 전달.
+
+### 2-2. Planner
+구현 계획 수립: 변경 파일, 접근법, compound 패턴 적용, 위험 요소, 검증 방법.
+
+### 2-3. Executor
+최소 변경으로 구현: 기존 패턴 준수, <200줄, 빌드 통과, 임시 코드 금지.
+
+### 2-4. Verifier
+각 AC를 독립적으로 검증. PASS/FAIL + 증거(테스트 출력, 빌드 로그, curl 응답).
+"should work"는 증거가 아닙니다 -- 반드시 실행합니다.
+
+```
+수용 기준 검증:
+- AC1: "POST /api/users가 201을 반환한다"
+  -> PASS | 증거: `curl -X POST ... -> HTTP/1.1 201 Created`
+- AC2: "잘못된 이메일 시 400 반환"
+  -> FAIL | 증거: `curl -X POST ... -> 500`
+```
+
+### 2-5. 스토리 완료 판정
+- 모든 AC PASS -> `passes: true` -> 즉시 다음 스토리 (보고하지 않음)
+- FAIL -> `attempts++` -> ch-debugger -> ch-executor -> ch-verifier 재실행
+- attempt == 3 -> 에스컬레이션
+
+## Anti-Polite-Stop 규칙
+
+스토리 완료 후 멈추지 않고 즉시 다음 스토리로 진행합니다.
+보고 시점:
+- **전부 완료**: 모든 스토리 PASS + 최종 검증 통과
+- **에스컬레이션**: 3회 실패
+- **컨텍스트 한계**: 토큰 80% 사용
+
+## Phase 3: 최종 검증
+
+모든 스토리 passes: true 후:
+1. 전체 빌드 + 테스트
+2. Critic 에이전트 리뷰 (코드 패턴, 디버그 코드, 보안)
+3. CRITICAL 이슈 -> 수정 스토리 추가 -> Phase 2 복귀
+4. Compound-Out: 패턴 추출 제안
+
+## 서킷 브레이커
+
+| 브레이커 | 임계값 | 동작 |
+|---------|--------|------|
+| max_attempts_per_story | 3 | 에스컬레이션 |
+| max_total_iterations | 30 | 강제 종료 + 상태 리포트 |
+| same_error_repeat | 3회 | 접근법 변경 요구 |
+| context_limit | 80% 토큰 | 상태 저장 + resume 안내 |
+
+## 진행 상황 추적
+
+```
+FORGE-LOOP PROGRESS
+═══════════════════
+Story 1/4: User Authentication  [DONE] (1 attempt)
+Story 2/4: Payment API          [IN PROGRESS] (attempt 2/3)
+  |- AC1: POST /pay returns 200  [PASS]
+  |- AC2: Webhook verification   [FAIL]
+  +- AC3: Idempotency key        [PENDING]
+Story 3/4: Error Handling        [PENDING]
+Story 4/4: Tests                 [PENDING]
+═══════════════════
+```
+</Steps>
+
+<Failure_Modes>
+NEVER: **PRD 없이 구현**: 스토리 분해를 먼저 수행합니다.
+
+NEVER: **일반적 수용 기준**: "코드가 컴파일된다" -> 프로젝트 특화 기준으로 교체.
+
+NEVER: **3회 실패 후 같은 접근**: 에스컬레이션하고 접근법을 변경합니다.
+
+NEVER: **검증 스킵**: "should work"는 증거가 아닙니다. 실행하여 확인합니다.
+
+NEVER: **중간 보고 (Polite-Stop)**: 스토리 완료 후 즉시 다음으로 진행합니다.
+
+NEVER: **Compound 무시**: 시작 전과 각 스토리 전에 compound-search를 수행합니다.
+
+NEVER: **디버그 코드 방치**: console.log, TODO, HACK, debugger 원천 차단.
+</Failure_Modes>
+
+<Output>
+```
+FORGE-LOOP COMPLETE
+═══════════════════════════════════════════════════
+Task: {task description}
+
+STORIES
+US-001: {title}  [DONE] ({N} attempts)
+US-002: {title}  [DONE] ({N} attempts)
+
+METRICS
+Total: {N} stories, {N} iterations (avg {N.N}/story)
+Build: PASS | Tests: {N} passed, 0 failed
+Critic: {N} warnings, 0 critical
+
+COMPOUND CANDIDATES
+[troubleshoot] "{title}" -- {desc}
+[pattern] "{title}" -- {desc}
+compound에 저장하시겠습니까? [Y/n]
+═══════════════════════════════════════════════════
+```
+</Output>
+
+<Policy>
+- 수용 기준은 구체적이고 검증 가능해야 합니다
+- "should work"는 증거가 아닙니다 -- 반드시 실행
+- 스토리 완료 후 즉시 다음 스토리 (Anti-Polite-Stop)
+- 3회 실패 시 에스컬레이션
+- 전체 완료 후 compound 추출 제안
+- 서킷 브레이커 임계값 절대 무시 금지
+</Policy>
+
+<Arguments>
+- `[task description]`: 실행할 작업 설명. 생략 시 현재 대화 컨텍스트에서 추론.
+- `resume`: 이전에 중단된 루프를 재개합니다.
+</Arguments>
+
+$ARGUMENTS