@kaydash9999/banker-plugins 0.2.0 → 0.4.0

package/skills/smart-compact/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: smart-compact
+description: "(banker) 컨텍스트 임계(기본 50%) 초과 시 append-wiki→ready-compact→compact-copy 자동 실행 + /copy·/compact·paste 유저 핸드오프 게이트. 'smart-compact' 활성화 / '--cancel' 해제."
+---
+
+# smart-compact — 컨텍스트 위생 자동 게이트
+
+긴 세션에서 컨텍스트가 임계(기본 **50%**)를 넘으면, compaction 전에 상태를 안전하게 보존하는
+리추얼을 **자동 발동**한다: `append-wiki` → `ready-compact` → `compact-copy` → *(유저)* `/copy`
+→ `/compact` → paste. `smart-compact` 로 무장, `smart-compact --cancel` 로 해제한다.
+
+## ⚠️ 정직한 실현 한계 (Claude Code 실측)
+"컨텍스트 50%에서 완전 무인 자동"은 **부분만 가능**하다 — 근거:
+- **감지**: 컨텍스트 사용률은 **statusLine stdin** 의 `context_window.used_percentage` 로만 실시간
+  노출된다(hook은 이 값을 못 받음; auto-compact은 ~95%에서만, 50% 이벤트 없음). → statusLine으로
+  **정확히 50% 감지 가능**.
+- **자동 실행 가능(어시스턴트)**: `append-wiki` · `ready-compact` · `compact-copy` — 스킬/도구
+  작업이라 어시스턴트가 수행.
+- **자동 불가(TUI 전용)**: `/copy` · `/compact` · **paste** 는 인터랙티브 TUI 동작이라 hook·스킬이
+  구동할 수 없다(hook은 슬래시명령 호출 불가, `additionalContext` 주입만 가능). → **이 3단은 유저가
+  실행**한다.
+
+따라서 smart-compact의 자동화 천장 = **감지(정확) + 준비 자동 실행 + TUI 3단 유저 핸드오프**.
+완전 hands-off를 약속하지 않는다(그건 별도 외부 데몬이 새 세션을 스폰해야 하고, 메인 세션이 idle일
+때만·클립보드 보장 없이 취약). smart-compact은 **가장 신뢰 가능한 최대 자동화**를 택한다.
+
+## 메커니즘 (무장 시 설치)
+런타임 인식 — Claude Code 경로가 정밀, Codex는 신호 노출이 불확실(아래 참조).
+
+**Claude Code (OMC):**
+1. **statusLine 래퍼(compose-safe)**: 기존 `statusLine.command`(예: OMC HUD)를 **보존**하고, 그것을
+   호출해 출력을 그대로 통과시킨 뒤, stdin의 `context_window.used_percentage` 를 파싱한다. 임계 이상이면
+   신호 파일 `~/.claude/.smart-compact-signal`(uid별; `id -u`)에 timestamp를 쓰고 statusLine에
+   `⚠ smart-compact ARMED (NN%)` 를 덧붙인다. **기존 statusLine을 덮어쓰지 말고 감싼다.**
+2. **hook 브리지**: `UserPromptSubmit`(또는 `PreToolUse`) hook이 신호 파일을 읽어 무장·미처리 상태면
+   `additionalContext` 로 "smart-compact: 컨텍스트 ≥임계 — 위생 체인 실행" 을 주입한다(hook은 명령을
+   못 부르므로 어시스턴트에게 **지시만** 한다).
+3. **게이트 동작(어시스턴트)**: 주입을 받으면 자동파트 실행 → 이어 유저에게 TUI 3단을 정확한 명령으로 안내.
+
+**Codex (OMX):**
+- Codex가 statusline/hook에 컨텍스트%를 노출하는지 **미확인**(문서 부재). 노출되면 위와 동형으로 구성
+  (`~/.codex` 경로·OMX hook). 미노출이면 **휴리스틱 폴백**: 어시스턴트가 스스로 컨텍스트 압박을 감지해
+  체인을 제안하고, 유저가 트리거. 준비 스킬은 banker 것이 양 런타임 동일(아래).
+
+## 게이트 체인
+무장 후 임계 초과가 감지되면 순서대로:
+
+1. **`append-wiki`** — 이번 작업의 비자명 지식을 wiki에 적재(휘발 방지). *(banker `append_wiki`, both)*
+2. **`ready-compact`** — resume 프롬프트 + 내구 메모리 기록. *(banker `ready-compact`, both)*
+3. **`compact-copy`** — resume 프롬프트-only 로 최종 메시지 셰이핑(response.md). *(banker `compact-copy`, both)*
+4. *(유저 · TUI)* **`/copy`** → **`/compact`** → **paste**(복사된 resume 프롬프트 입력).
+
+1~3은 어시스턴트가 자동 수행. 4는 어시스턴트가 **정확한 명령을 제시**하고 유저가 실행한다.
+(Claude=`/banker:append_wiki`·`/banker:ready-compact`·`/banker:compact-copy`,
+Codex=`$banker-append_wiki`·`$banker-ready-compact`·`$banker-compact-copy`; `/copy`·compaction은 양쪽 TUI 내장.)
+
+## 활성화 (idempotent · compose-safe)
+`smart-compact [--threshold N]` (기본 N=50):
+1. `~/.claude/settings.json`(Codex는 `~/.codex/`)의 기존 `statusLine`·hook 설정을 **읽어 백업**
+   (`~/.claude/.smart-compact-prev.json`).
+2. statusLine 래퍼 스크립트를 설치하고 `statusLine.command` 를 래퍼로 교체(래퍼가 이전 command를 위임 호출).
+3. `UserPromptSubmit` hook 항목을 **추가**(기존 hook 보존, 중복 방지 — 이미 있으면 skip).
+4. 임계값을 래퍼에 기록. 무장 완료를 보고.
+
+**멱등·안전 불변식**: 두 번 활성화해도 중복 설치 안 됨. 기존 statusLine/hook을 절대 삭제·덮어쓰지
+않고 **감싸거나 추가만** 한다(uid는 `id -u` 로 계산, 하드코딩 금지).
+
+## 해제
+`smart-compact --cancel`:
+1. 백업(`~/.claude/.smart-compact-prev.json`)에서 원래 `statusLine`·hook 설정 **복원**.
+2. 래퍼 스크립트·신호 파일·백업 제거.
+3. 무장 해제를 보고. (백업이 없으면 smart-compact가 추가한 항목만 안전 제거.)
+
+## 함정
+- **statusLine 덮어쓰기 금지** — OMC HUD 등 기존 statusLine을 감싸라(복원 가능하게 백업).
+- **완전 자동 과대약속 금지** — `/copy`·`/compact`·paste는 TUI 전용, 유저 핸드오프임을 항상 명시.
+- **uid 하드코딩 금지** — 신호/경로는 `id -u` 로.
+- **hook은 명령을 못 부른다** — `additionalContext` 로 어시스턴트에게 지시할 뿐, 스스로 체인을 실행하지 못함.
+- **Codex 신호 미확인** — 노출 안 되면 휴리스틱 폴백으로 정직히 degrade(50% 정밀 트리거 미보장).
+
+ARGUMENTS: [--threshold N] | --cancel   (없으면 기본 임계 50%로 무장)

package/skills/ultra-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ultra-init
-description: "아이디어·러프 브리프·그린필드를 계획→구현→QA 통과까지 핸즈오프로 1회 자율 실행(ralplan→ultragoal→ralph→ultraqa). 'ultra-init'/'알아서 만들어'/'핸즈오프 빌드'/'idea to passing' 시 사용."
+description: "(banker) 아이디어·러프 브리프·그린필드를 계획→구현→QA 통과까지 핸즈오프 1회 자율 실행(ralplan→ultragoal→ralph→ultraqa). 'ultra-init'/'알아서 만들어'/'핸즈오프 빌드'/'idea to passing' 시 사용."
 argument-hint: "[--short|--deliberate] [--gated] [--qa tests,build,lint,typecheck] [--critic=architect|critic|codex] [--plan-id <id>] <브리프 / 만들 것>"
 level: 4
 ---
@@ -45,6 +45,7 @@ Several bundled skills are loop/persistence engines. To prevent competing loops,
 - Resolve the brief from the skill arguments. If it is empty, ask once for the brief, then proceed.
 - Parse flags: planning depth (`--deliberate` = default, `--short` = lighter ralplan), `--gated`, `--qa <dims>`, `--critic=...`, `--plan-id <id>`.
 - **OMC prerequisite**: this skill orchestrates OMC's `ralplan`/`ralph`/`ultraqa`, so it needs the `omc` CLI. Check `command -v omc`; if missing, **guide installation first** via `/banker:setup` → oh-my-claudecode (or the `setup-omc` skill / `omc update`), then resume once it is available. Only if the user declines to install, run ultragoal in **degraded mode**: skip the durable ledger, write the approved plan to `plan.md`, and rely on ralph's session-scoped `prd.json` (say so explicitly).
+- **런타임 매핑 (Claude Code ↔ Codex).** `ralplan`·`ralph`·`ultraqa`·`ultragoal`·`cancel` 은 Claude Code에선 OMC, **Codex에선 oh-my-codex(OMX)가 제공하는 동명 스킬**이다(Codex는 `omx setup` 전제). 아래 Phase들의 `Skill("oh-my-claudecode:<name>")` 표기는 Claude Code 기준 — **Codex 런타임에선 OMX의 해당 스킬을 적용**한다. `omc ultragoal` CLI(Phase 2)는 Codex에선 OMX의 대응 명령을 쓰거나(정확한 플래그는 감지, 임의 가정 금지), 위 degraded 모드(`plan.md` + ralph `prd.json`)로 대체한다.
 
 ### Phase 1 — PLAN: ralplan --deliberate (합의 계획)
 - Invoke `Skill("oh-my-claudecode:ralplan")` with `--deliberate <brief>` in **non-interactive** mode (so it produces the consensus-approved plan, marks it `pending approval`, and **stops without launching team/ralph itself** — ultra-init controls the hand-off).

package/skills/ultra-ui-qa/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ultra-ui-qa
-description: "웹 UI를 playwright로 실제 렌더해 디자인 SoT(PDF/스펙)와 1:1 대조 + 내부개념 텍스트 누출 점검(데이터·소스까지 검증, HTTP 200만으로 PASS 금지). 'ultra ui qa'/'UI 대조'/'디자인 PDF와 대조'/'어색한 내용 점검' 시 사용."
+description: "(banker) 웹 UI를 playwright로 렌더해 디자인 SoT(PDF/스펙)와 1:1 대조 + 내부개념 텍스트 누출 점검(HTTP 200만으로 PASS 금지). 'ultra ui qa'/'UI 대조'/'디자인 PDF와 대조'/'어색한 내용 점검' 시 사용."
 ---
 
 # ultra-ui-qa — 라이브 UI ↔ SoT 엄격 대조 + 내부개념 누출 점검

package/skills/visual-ralph/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: visual-ralph
+description: "(banker) 프론트엔드 UI를 레퍼런스(생성/정적/라이브 URL) 기준으로 측정 빌드: ralph 구현→Visual Verdict(≥90)+픽셀 diff 반복→재사용 디자인 시스템. 'visual-ralph'/'비주얼 랄프'/'UI 클론'/'레퍼런스대로 구현' 시 사용."
+---
+
+# visual-ralph — 측정 기반 비주얼 빌드 루프
+
+사용자가 프론트엔드 UI를 **주관적 서술이 아니라 측정된 반복**으로 구현/리스타일하려 할 때 쓴다:
+승인된 레퍼런스(생성 이미지 / 정적 이미지 / 라이브 URL 파생)를 타깃으로 삼아 `ralph` 가 구현하고,
+**Visual Verdict** 점수가 이터레이션을 이끈다. (OMX `visual-ralph` 를 banker 로 이식 — 양 런타임 제공.)
+
+이건 **오케스트레이션 스킬**이다. 기존 스킬을 조합할 뿐, 자체 런타임 명령·의존·앱 가정을 더하지 않는다.
+
+**런타임 매핑 (Claude Code ↔ Codex).** 흐름은 동일하나 호출 대상이 런타임별로 다르다:
+
+| 단계 | Claude Code (OMC) | Codex (OMX) |
+|---|---|---|
+| 구현 루프 | `Skill("oh-my-claudecode:ralph")` | OMX `$ralph` |
+| 비주얼 판정 | `Skill("oh-my-claudecode:visual-verdict")` | OMX Visual Verdict |
+| 이미지 이해 | **Read 툴 네이티브**(이미지 직접 판독) | `vision` 에이전트 |
+| UI 레퍼런스 생성 | **Stitch**(`/banker:setup-stitch` MCP UI-gen); 없으면 **정적/라이브 URL 레퍼런스**로 폴백(생성 불요) | `$imagegen` + `omx imagegen continuation`(Stop-hook 큐) |
+| 아티팩트/상태 경로 | `.omc/artifacts/visual-ralph/<slug>/` | `.omx/artifacts/visual-ralph/<slug>/` · `.omx/state/sessions/` |
+
+생성 레퍼런스 경로가 양쪽 다 없으면(imagegen 부재) → **정적 레퍼런스 이미지나 라이브 URL을 요구**한다
+(생성 없이도 루프는 성립한다). 라이브 URL 클론은 이 스킬이 흡수한다(구 `$web-clone` 미사용).
+
+## Purpose
+
+`사용자 서술 / 라이브 URL → 승인된 비주얼 레퍼런스 → ralph 구현 → Visual Verdict + 픽셀 diff → 재사용 디자인 시스템`.
+
+## 언제 쓰나
+- 원하는 web/app UI를 서술하고 **조언이 아니라 구현**을 원할 때.
+- 라이브 URL을 주고 측정된 Visual Verdict 반복으로 구현/클론하려 할 때.
+- 픽셀 수준 반복 + pass/fail 임계(≥90)가 필요할 때.
+- 결과가 일회성 스샷 매치가 아니라 **재사용 토큰/컴포넌트**를 남겨야 할 때.
+
+## 쓰지 않을 때
+- repo 전반 디자인 가이드/`DESIGN.md` 소스만 원할 때 → designer 레인.
+- UI 레퍼런스 타깃이 없는 비주얼-무관 백엔드/API.
+- 최종 정적 레퍼런스를 이미 갖고 비교·수정만 필요 → 바로 `ralph` 에 Visual Verdict 지침과 함께 위임.
+
+## 워크플로
+
+### 1. 대상 repo 그라운딩
+스택 선택 전 로컬 증거 확인: 패키지 매니저·스크립트, 프론트 프레임워크·라우팅, 스타일 시스템·디자인
+토큰 규약, 스샷/테스트 툴링, 재사용할 기존 컴포넌트. **React/Vue/Tailwind/Playwright 등을 repo 증거
+없이 하드코딩 금지.**
+
+### 2. 비주얼 레퍼런스 확립
+- **라이브 URL**: URL 파생 레퍼런스를 아티팩트에 기록 + viewport·콘텐츠 상태·인터랙션 제약 반영.
+  포함: 소스 URL·권한/범위 노트, viewport·route/state·seed/login 가정, 캡처 스샷 경로/명령,
+  가시 컨트롤 인터랙션 패리티, 알려진 제외(백엔드/auth·개인화 데이터·멀티페이지 크롤·서드파티 위젯).
+- **생성 레퍼런스**: 위 런타임 매핑의 imagegen 경로로 UI 서술에서 생성. 프롬프트 요건: `ui-mockup`
+  분류, viewport/종횡비·대상 표면, 레이아웃·계층·타이포·컬러 무드·정확한 텍스트, 로고/워터마크 금지,
+  불가능한 UI 디테일·판독불가 텍스트 회피.
+  - Codex 런타임에서 활성 Ralph 루프 중 내장 이미지 툴 호출 전엔 continuation 체크포인트를 큐잉:
+    `omx imagegen continuation <session> --artifact <slug> --generated-dir "$CODEX_HOME/generated_images/<session>" --work-dir ".omx/artifacts/visual-ralph/<slug>"`
+    (내장 이미지 생성이 턴을 즉시 종료할 수 있어, 다음 Stop 체크포인트가 아티팩트 회수·QA를 재개.)
+- 승인된 레퍼런스는 **워크스페이스로 복사**한다(예: `.omc/artifacts/visual-ralph/<slug>/reference.png`).
+  생성 디렉터리에만 두지 말 것.
+
+### 3. 명시적 사용자 승인 (필수 게이트)
+레퍼런스 생성/캡처 후 **멈추고** 한 장의 레퍼런스 이미지/상태를 승인받거나 재생성/조정 요청을 받는다.
+승인 전: 구현 시작 금지·`ralph` 호출 금지·러프 이미지를 최종 취급 금지. 승인 후 그 이미지/URL 파생
+베이스라인이 **비주얼 진실원본**이 된다(방향 전환·레퍼런스 교체는 명시 요청 필요).
+
+### 4. `ralph` 에 구현 위임
+승인 레퍼런스 경로/URL 베이스라인, (URL 태스크면)소스 URL·viewport·상태·인터랙션 패리티, 사용자 서술,
+탐지한 repo/프론트 컨텍스트, 정확한 스샷 명령/viewport, 아래 완료 체크리스트를 넘긴다. ralph 는 승인 후
+자율 반복(코드 편집→앱 실행→스샷→개선)한다.
+
+### 5. 매 편집 전 Visual Verdict
+이터레이션마다: (1) 현재 스샷을 기록된 viewport/state로 캡처 → (2) 승인 레퍼런스 vs 생성 스샷을
+**Visual Verdict**(Claude=`visual-verdict` 스킬, Codex=OMX Visual Verdict; 이미지 이해는 위 매핑)로
+비교 → (3) JSON 판정을 권위로 취급 → (4) `score < 90` 이면 `differences[]`·`suggestions[]` 를 다음
+편집 계획으로 → (5) 다음 편집 전 재실행. 판정 형태: `score·verdict·category_match·differences[]·suggestions[]·reasoning`.
+
+### 6. 픽셀 diff는 2차 증거로만
+매치 진단이 어려울 때만 픽셀 diff/오버레이로 핫스팟 국소화. Verdict를 대체하지 않는다. 최종 diff 증거는
+레퍼런스/스샷 아티팩트와 함께 감사 가능하게 기록.
+
+### 7. 재사용 디자인 시스템 구축
+비주얼 매치를 **repo 네이티브 재사용 아티팩트**(CSS 변수·테마 토큰·Tailwind config·컴포넌트 variant·
+Storybook·DESIGN.md 정렬 등)로 인코딩해야 완료다. 최소 캡처: 컬러·간격 스케일·타이포 스케일/웨이트·
+radii·shadow/elevation·핵심 컴포넌트 variant/state. 기존 토큰/컴포넌트 패턴 우선(새 디자인 레이어 신설 금지).
+
+## 완료 체크리스트
+- [ ] 승인 레퍼런스(이미지/URL 파생 아티팩트)가 워크스페이스에 저장됨.
+- [ ] 스샷 재현 명령·viewport·route·seed/state·출력 경로 문서화.
+- [ ] Visual Verdict 최종 score `≥ 90`(승인 레퍼런스 대비).
+- [ ] 픽셀 diff/오버레이 2차 증거 기록.
+- [ ] 디자인 시스템 토큰/컴포넌트가 repo 네이티브·재사용 가능.
+- [ ] build/lint/test(또는 repo 등가 검증) 통과.
+- [ ] 레퍼런스 승인 후 미승인 방향전환 없음.
+- [ ] 남은 비주얼 차이는 근거와 함께 명시.
+
+## 핸드오프 템플릿
+```text
+ralph "승인된 프론트 레퍼런스를 구현하라.
+Reference: <워크스페이스 레퍼런스 이미지/URL 파생 아티팩트>
+Source URL(URL 파생 시): <url·권한/범위 노트>
+Viewport/콘텐츠 상태: <viewport·route/state·seed/login 가정>
+인터랙션 패리티: <가시 컨트롤·제외 항목>
+Route/표면: <route 또는 컴포넌트>
+스샷 명령: <명령·viewport>
+매 편집 전 Visual Verdict 사용; pass 임계 score ≥ 90.
+픽셀 diff는 2차 디버그 증거로만.
+컬러·간격·타이포·radii·shadow·핵심 variant 재사용 토큰/컴포넌트 추출.
+완료 전 build/lint/test 실행.
+명시 요청 없인 방향전환 금지."
+```
+(Claude=`Skill("oh-my-claudecode:ralph")`, Codex=`$ralph` 에 위 지침 전달.)
+
+## 함정
+- **승인 게이트 스킵 금지** — 러프 이미지를 진실원본으로 굳히면 방향이 틀어진다.
+- Visual Verdict를 픽셀 diff로 대체하지 말 것(diff는 국소화 보조).
+- 생성 레퍼런스를 워크스페이스로 복사 안 하면 유실(생성 디렉터리 휘발).
+- imagegen 경로 부재를 무시하고 진행 금지 — 정적 레퍼런스/라이브 URL로 폴백하라.
+
+ARGUMENTS: [UI 서술 / 라이브 URL / 레퍼런스 경로]