@wooojin/forgen 0.2.0 → 0.3.0

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

package/commands/learn.md

@@ -0,0 +1,231 @@
+---
+name: learn
+description: This skill should be used when the user asks to "learn, 학습 관리, compound 정리, 솔루션 정리". Compound 지식의 관리 인터페이스 — 검색, 통계, 가지치기, 내보내기/가져오기.
+argument-hint: "[search {query}|stats|prune|export|import {path}]"
+model: inherit
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+triggers:
+  - "learn"
+  - "학습 관리"
+  - "compound 정리"
+  - "솔루션 정리"
+  - "compound 관리"
+  - "솔루션 관리"
+  - "지식 관리"
+---
+
+<Purpose>
+compound에 축적된 솔루션을 관리합니다.
+시간이 지남에 따라 솔루션은 낡거나 중복되거나 모순됩니다.
+learn은 이를 정기적으로 정리하여 compound의 신호 대 잡음 비율을 유지합니다.
+
+서브커맨드: search, stats, prune, export, import
+서브커맨드 생략 시: stats 실행
+</Purpose>
+
+<Compound_Integration>
+## Compound 데이터 직접 조작
+
+learn은 compound의 관리 도구입니다.
+모든 서브커맨드에서 compound MCP 도구를 직접 사용합니다:
+- `compound-stats` -- 전체 현황 조회
+- `compound-list` -- 솔루션 목록 조회
+- `compound-read` -- 개별 솔루션 상세 조회
+- `compound-search` -- 키워드 검색
+
+retire/merge 전에 반드시 사용자 확인을 받습니다.
+mature 상태 솔루션은 어떤 경우에도 자동 정리 대상이 아닙니다.
+</Compound_Integration>
+
+<Steps>
+## search {query}
+
+compound-search MCP로 검색하고 결과를 정리합니다.
+
+```
+compound-search("{query}")
+```
+
+```
+SEARCH RESULTS / 검색 결과
+===========================
+Query: "{query}"
+Found: {N}개
+
+  # | Title                    | Type          | Status     | Last Used
+----+--------------------------|---------------|------------|----------
+  1 | {제목}                   | {type}        | {status}   | {date}
+  2 | {제목}                   | {type}        | {status}   | {date}
+```
+
+결과 없으면: "검색 결과 없음. 관련 키워드 제안: {1-3개}"
+
+---
+
+## stats
+
+```
+compound-stats
+compound-list
+```
+
+```
+COMPOUND KNOWLEDGE / 복리 지식 현황
+════════════════════════════════════
+Total: {N} solutions
+
+By Status:
+  mature (3+ hits):     {N} ({N}%) {bar}
+  verified (2 hits):    {N} ({N}%) {bar}
+  candidate (1 hit):    {N} ({N}%) {bar}
+  experiment (0 hits):  {N} ({N}%) {bar}
+
+By Type:
+  pattern: {N} | troubleshoot: {N} | decision: {N} | anti-pattern: {N}
+
+By Scope:
+  me: {N} | project: {N} | universal: {N}
+
+Activity (last 7 days):
+  Injected: {N}/{total} ({N}%)
+  New: +{N} | Promoted: +{N} | Retired: -{N}
+  Top: "{title}" ({N} hits)
+```
+
+바 차트는 비율에 따라 `#` 문자로 시각화 (최대 20자).
+
+---
+
+## prune
+
+**prune은 항상 stats를 먼저 실행합니다.**
+
+### 감지 기준
+1. STALE: 30일+ 미사용
+2. DUPLICATE: 유사도 80%+ (제목+내용 키워드 비교)
+3. CONTRADICTORY: 같은 주제에 서로 반대 결론
+4. LOW-QUALITY: experiment 상태 60일+ 미승격
+
+### 제외 규칙
+- mature 상태는 절대 prune 대상이 아님
+- verified 상태는 STALE일 때만 후보
+
+```
+PRUNE CANDIDATES / 정리 후보
+════════════════════════════
+
+STALE (30d+ unused):
+  1. "{title}" ({N}일 미사용)                    [retire / keep]
+  2. "{title}" ({N}일 미사용)                    [retire / keep]
+
+DUPLICATE (similarity {N}%+):
+  3. "{title-a}" ~ "{title-b}" ({N}%)            [merge / keep both]
+
+CONTRADICTORY:
+  4. "{title-a}" vs "{title-b}"                  [resolve / keep both]
+
+LOW-QUALITY (experiment {N}d+):
+  5. "{title}" (experiment {N}일 경과)           [retire / promote / keep]
+
+선택하세요 (번호 + 행동, 예: "1 retire, 3 merge, 4 resolve"):
+```
+
+사용자 선택을 받은 후에만 실행합니다.
+
+---
+
+## export
+
+```bash
+# tar.gz (기본)
+tar -czf compound-export-$(date +%Y%m%d).tar.gz ~/.forgen/me/solutions/
+
+# markdown (--md 인수)
+# 각 솔루션을 하나의 markdown으로 결합
+```
+
+```
+EXPORT COMPLETE / 내보내기 완료
+================================
+Format: {tar.gz / markdown}
+File:   {파일 경로}
+Size:   {크기}
+Count:  {솔루션 수}
+```
+
+---
+
+## import {path}
+
+```bash
+tar -xzf {path} -C /tmp/compound-import/
+```
+
+중복 검사 후 처리:
+- 동일 -> skip
+- 유사 -> 사용자에게 merge/skip/replace 선택
+- 신규 -> 추가
+
+```
+IMPORT RESULTS / 가져오기 결과
+===============================
+Source: {path}
+Total:  {N}개
+  Added:    {N}개
+  Skipped:  {N}개 (중복)
+  Merged:   {N}개
+```
+</Steps>
+
+<Failure_Modes>
+**확인 없이 retire**: 각 후보의 선택을 반드시 사용자에게 받는다. 자동 삭제 없음.
+**mature 솔루션 삭제 제안**: mature는 prune 대상에서 제외. 3회 이상 활용된 지식은 가치가 검증됨.
+**stats 없이 prune**: stats 먼저, 그 다음 prune 후보. 전체 맥락 없이 개별 삭제 불가.
+**import 무조건 덮어쓰기**: 기존 솔루션과 충돌 시 반드시 중복 검사 먼저.
+**빈 compound에서 prune 시도**: 솔루션이 없으면 "/compound로 세션 패턴을 축적하세요" 안내.
+</Failure_Modes>
+
+<Output>
+## stats 출력
+
+```
+COMPOUND KNOWLEDGE / 복리 지식 현황
+════════════════════════════════════
+Total: {N} solutions
+...
+```
+
+## prune 출력
+
+```
+PRUNE CANDIDATES / 정리 후보
+════════════════════════════
+[stale] "{title}" -- {N}일 미사용 -> retire/keep?
+[duplicate] "{a}" ~ "{b}" -> merge/keep?
+[low-quality] "{title}" -- experiment {N}일 -> retire/promote/keep?
+```
+</Output>
+
+<Policy>
+- retire/merge는 반드시 사용자 확인 후 실행.
+- mature 상태 솔루션은 prune 대상이 아님. 예외 없음.
+- prune은 항상 stats 출력 이후에 후보 제시.
+- export는 현재 디렉토리에 날짜 포함 파일명.
+- import는 중복 검사 먼저, 충돌 시 사용자 선택.
+- 서브커맨드 없으면 stats 기본 실행.
+</Policy>
+
+<Arguments>
+- `search {query}`: 솔루션 검색
+- `stats`: 전체 현황 통계 (기본값)
+- `prune`: stale/중복/모순/저품질 감지 및 정리
+- `export`: tar.gz 내보내기
+- `export --md`: markdown 내보내기
+- `import {path}`: 외부 compound 가져오기 (중복 검사 후 머지)
+</Arguments>
+
+$ARGUMENTS

package/commands/retro.md

@@ -0,0 +1,215 @@
+---
+name: retro
+description: This skill should be used when the user asks to "retro, 회고, retrospective, 돌아보기". Git 메트릭 + compound 건강도 + 학습 추세를 교차 분석하는 회고 리포트.
+argument-hint: "[7d|14d|30d] [compare]"
+model: inherit
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+triggers:
+  - "retro"
+  - "회고"
+  - "retrospective"
+  - "돌아보기"
+  - "주간 회고"
+  - "월간 회고"
+  - "주간회고"
+  - "월간회고"
+---
+
+<Purpose>
+git log + compound 통계 + 교정 기록을 교차 분석하여 최근 기간의 개발 패턴을 파악합니다.
+"잘 하고 있는가"가 아니라 "어디서 반복 마찰이 생기는가"를 발견하는 것이 목적입니다.
+데이터 없이 추측하지 않습니다. 모든 분석은 실제 수집된 데이터에 근거합니다.
+</Purpose>
+
+<Compound_Integration>
+## Compound 데이터 활용
+
+retro는 compound stats를 핵심 데이터 소스로 사용합니다.
+
+분석 신호:
+- 활용률 낮음 -> 축적은 되지만 재사용 안 됨 (검색 키워드 품질 문제)
+- stale 많음 -> 정리 필요 (`/learn prune` 추천)
+- experiment 비율 높음 -> 검증 없이 축적만 됨
+- mature 비율 높음 -> 건강한 지식 베이스
+</Compound_Integration>
+
+<Steps>
+## Phase 1: 데이터 수집
+
+기간 기본값: 7d
+`$ARGUMENTS`에서 파싱 (7d, 14d, 30d, compare).
+
+### 1-1: Git 활동 데이터
+
+```bash
+# 커밋 이력
+git log --since="{period}" --oneline --stat --format="%h|%an|%ai|%s"
+
+# 기여자별 커밋
+git shortlog --since="{period}" -sn
+
+# 핫스팟 (파일별 변경 빈도)
+git log --since="{period}" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -10
+
+# 변경 줄 수
+git log --since="{period}" --stat --format="" | tail -1
+```
+
+### 1-2: Compound 데이터
+
+```
+compound-stats
+compound-list
+```
+
+### 1-3: 교정 기록
+
+```bash
+ls -la ~/.forgen/me/evidence/ 2>/dev/null || echo "교정 데이터 없음"
+find ~/.forgen/me/evidence/ -name "*.json" -mtime -{period_days} 2>/dev/null | wc -l
+```
+
+## Phase 2: 코드 활동 분석
+
+- 커밋 수 (일 평균 포함)
+- +추가 / -삭제 비율
+- 핫스팟 Top 5 (3회+ 수정 -> 불안정 영역)
+
+## Phase 3: 세션 패턴 분석
+
+```
+세션 분리: 45분+ 간격 = 새 세션
+```
+
+- 세션 수, 평균 길이
+- 시간대 분포 (정보 제공용, 판단은 사용자에게)
+
+## Phase 4: Compound 건강도 분석
+
+```
+총 솔루션, 상태별/유형별 비율, 활용률, stale 후보
+```
+
+건강도 판정:
+- HEALTHY: mature 20%+, stale < 5, 활용률 30%+
+- ATTENTION: experiment 40%+, 또는 stale 5-10
+- NEEDS CARE: stale 10+, 또는 활용률 10% 미만
+
+## Phase 5: 학습 추세 분석
+
+- 교정 감소 -> 학습 중 (좋은 신호)
+- 교정 증가 -> 드리프트 발생
+- 동일 축 반복 -> `/calibrate` 권장
+- 데이터 없음 -> "교정 데이터 없음" 표시
+
+## Phase 6: 추천 생성 (반드시 3개)
+
+데이터 근거 규칙:
+- 핫스팟 존재 -> `/code-review {파일}`
+- stale 5개+ -> `/learn prune`
+- 동일 교정 3회+ -> `/calibrate`
+- experiment 40%+ -> compound 품질 개선
+- 활용률 10% 미만 -> compound 검색 개선
+- 커밋 급감 -> 블로커 확인
+</Steps>
+
+<Compare_Mode>
+## Compare 모드
+
+`/retro compare` 또는 `/retro 14d compare`
+
+```bash
+# 현재 기간
+git log --since="{period}" --oneline --stat
+# 이전 기간
+git log --since="{period*2}" --until="{period}" --oneline --stat
+```
+
+```
+COMPARE / 기간 비교
+════════════════════
+                 Previous {N}d    This {N}d    Delta
+Commits:              {N}            {N}       {+/-N}%
+LOC:                +{N}           +{N}        {+/-N}%
+Files:                {N}            {N}       {+/-N}%
+Hotspot:         {file}({N})    {file}({N})    {NEW/SAME/GONE}
+Sessions:             {N}            {N}       {+/-N}%
+Compound hits:        {N}            {N}       {+/-N}%
+Corrections:          {N}            {N}       {+/-N}% {arrow}
+```
+
+Delta 해석:
+- 커밋 증가 + 교정 감소 -> 생산성 + 학습 (최고)
+- 커밋 감소 + 핫스팟 동일 -> 같은 파일에서 막힘 (구조적 문제)
+- Compound hits 증가 -> 복리 효과 발현
+</Compare_Mode>
+
+<Failure_Modes>
+**데이터 없이 추측**: git log + compound stats 수집 후 분석. 느낌 기반 회고 금지.
+**긍정만 보고**: 핫스팟, stale, 개선점 반드시 포함. 칭찬 보고서는 가치 없음.
+**추천 없는 보고서**: 반드시 3개 next action. "계속 잘 하세요"는 추천이 아님.
+**기간 무시**: `--since` 파라미터 정확 적용.
+**세션 패턴 판단**: 데이터만 보여주고 판단은 사용자에게.
+</Failure_Modes>
+
+<Output>
+```
+RETRO / 회고
+════════════
+기간: {start} ~ {end}
+
+CODE ACTIVITY
+─────────────
+커밋: {N}개 (일 평균 {N}개) | +{N} / -{N} | 파일: {N}개
+세션: {N}개 (평균 {N}분)
+
+핫스팟:
+  1. {file} ({N}회 수정) <- 구조 리뷰 권장
+  2. {file} ({N}회 수정)
+  3. {file} ({N}회 수정)
+  4. {file} ({N}회 수정)
+  5. {file} ({N}회 수정)
+
+COMPOUND HEALTH [{HEALTHY/ATTENTION/NEEDS CARE}]
+───────────────
+총: {N}개 | mature: {N} | verified: {N} | candidate: {N} | experiment: {N}
+활용률: {N}% (지난주 대비 {+/-N}%)
+Stale 후보: {N}개
+신규: +{N}개 | 승격: +{N}개 | 은퇴: -{N}개
+
+LEARNING TREND
+──────────────
+교정: {N} -> {N} ({down/up/flat} {arrow})
+드리프트: {N}회
+
+RECOMMENDATIONS
+───────────────
+1. {action} -- {data-backed reason}
+2. {action} -- {data-backed reason}
+3. {action} -- {data-backed reason}
+```
+</Output>
+
+<Policy>
+- 데이터 수집 없이 회고 시작하지 않음.
+- 기간 없으면 7d 기본.
+- 추천은 수집된 데이터에만 근거. 추측 금지.
+- 추천 반드시 3개.
+- compare 모드: 두 기간 delta 시각화.
+- 핫스팟 Top 5.
+- compound 건강도 3단계 판정.
+</Policy>
+
+<Arguments>
+- `7d`: 최근 7일 회고 (기본값)
+- `14d`: 최근 14일 회고
+- `30d`: 최근 30일 회고
+- `compare`: 현재 기간 vs 이전 동일 기간 비교
+- `14d compare`: 14일 회고 + 기간 비교
+</Arguments>
+
+$ARGUMENTS