oh-my-customcode 0.140.0 → 0.141.0

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-49 agents. 118 skills. 23 rules. One command.
+49 agents. 119 skills. 23 rules. One command.
 
 ```bash
 npm install -g oh-my-customcode && cd your-project && omcustom init
@@ -132,7 +132,7 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (118)
+### Skills (119)
 
 | Category | Count | Includes |
 |----------|-------|----------|
@@ -272,7 +272,7 @@ your-project/
 ├── CLAUDE.md                   # Entry point
 ├── .claude/
 │   ├── agents/                 # 49 agent definitions
-│   ├── skills/                 # 118 skill modules
+│   ├── skills/                 # 119 skill modules
 │   ├── rules/                  # 22 governance rules (R000-R021)
 │   ├── hooks/                  # 15 lifecycle hook scripts
 │   ├── schemas/                # Tool input validation schemas

package/dist/cli/index.js

@@ -2334,7 +2334,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.140.0",
+    version: "0.141.0",
     description: "Batteries-included agent harness for Claude Code",
     type: "module",
     bin: {

package/dist/index.js

@@ -2014,7 +2014,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.140.0",
+  version: "0.141.0",
   description: "Batteries-included agent harness for Claude Code",
   type: "module",
   bin: {

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.140.0",
+  "version": "0.141.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/skills/semble-integration/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: semble-integration
+description: Semble (MinishLab) MCP wrapper — semantic code search via embeddings (98% token reduction vs grep+read, NDCG@10=0.854)
+scope: core
+version: 0.1.0
+user-invocable: true
+effort: low
+---
+
+# Semble Integration Skill
+
+[MinishLab/semble](https://github.com/MinishLab/semble) MCP 서버의 의미 기반 코드 검색 도구를 노출하는 wrapper 스킬.
+코드 인식 청킹 + 정적 임베딩 + BM25 + RRF 조합으로 transformer 수준 정확도를 CPU에서 달성한다.
+
+## 목적
+
+- **~98% 토큰 절감** (grep+Read 대비): 전체 파일 읽기 없이 의미적으로 관련된 코드 청크만 반환
+- **의미 기반 검색**: 자연어 쿼리로 "비슷한 코드 찾기", "에러 핸들링 패턴 검색" 등 구조 검색이 어려운 작업에 특화
+- **NDCG@10 = 0.854**: transformer 모델 수준 정확도를 CPU 인덱싱 (~250ms), 쿼리 (~1.5ms)로 달성
+- **R013 ecomode 보완**: context 사용량 ≥ 60% 시점에 Semble 호출로 추가 파일 읽기 비용 절감
+
+## CRG와의 보완 관계
+
+Semble과 CRG는 서로 다른 검색 축을 담당하며 상호 보완적이다.
+
+| 도구 | 검색 유형 | 강점 | 약점 |
+|------|----------|------|------|
+| `crg-integration` | 구조 (AST) | 호출 그래프, 영향 분석, recall-우선 | 의미 검색 약함 |
+| `semble-integration` | 의미 (임베딩) | 자연어 쿼리, "비슷한 코드 찾기" | 구조 정보 없음 |
+
+**사용 가이드**:
+- "이 함수의 caller는?" → CRG (`query_graph`)
+- "에러 핸들링 코드 패턴" → Semble
+- "변경 영향 범위" → CRG (`get_impact_radius`)
+- "인증 관련 코드 전부 찾기" → Semble (자연어 쿼리)
+
+## 노출 도구
+
+Semble MCP 서버가 제공하는 도구를 통해 다음 기능을 수행한다.
+구체적인 tool 이름은 MCP 서버 설치 후 Claude Code MCP introspection으로 확인한다.
+
+| 기능 | 설명 |
+|------|------|
+| 의미 검색 | 자연어 쿼리로 코드베이스 내 관련 청크 반환 |
+| 인덱싱 | 코드베이스를 code-aware 청킹 + 정적 임베딩으로 인덱싱 (CPU ~250ms) |
+| 결과 ranking | BM25 + RRF + embedding fusion으로 최종 랭킹 결정 |
+
+> 자세한 tool 사양은 `guides/token-efficiency/semble.md` 참조.
+
+## 설치 가이드
+
+> R001 정책: auto-install 스크립트 금지. 아래 명령어는 **사용자가 직접** 실행한다.
+
+### 1단계: 패키지 설치
+
+```bash
+# uv 기반 설치 (권장)
+uv tool install semble
+```
+
+### 2단계: MCP 서버 등록
+
+```bash
+# 방법 A: claude mcp 명령어 (권장)
+claude mcp add semble -- semble mcp
+
+# 방법 B: .mcp.json 수동 편집
+# 프로젝트 루트 또는 ~/.claude/.mcp.json 직접 수정
+```
+
+`.mcp.json` 수동 설정 예시:
+
+```json
+{
+  "mcpServers": {
+    "semble": {
+      "command": "semble",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+auto-install hook 또는 스크립트로 `.mcp.json`을 자동 수정하는 방식은 R001 위반이다.
+
+### 3단계: 인덱싱
+
+```bash
+# 명시적 인덱싱 (선택 — 첫 MCP 호출 시 lazy 인덱싱도 가능)
+semble index
+```
+
+자세한 설치/설정 절차는 `guides/token-efficiency/semble.md` 참조.
+
+## 사용 패턴
+
+### 의미 기반 코드 검색
+
+```
+"인증 미들웨어 관련 코드 찾아줘"
+→ Semble 의미 검색 → 관련 청크 반환 → 전체 파일 읽기 없이 컨텍스트 주입
+```
+
+### 패턴 검색
+
+```
+"에러 핸들링 컨벤션이 어떻게 되어 있어?"
+→ Semble "error handling convention" 쿼리 → 패턴 예시 청크 반환
+```
+
+### dev-review/adversarial-review와 조합
+
+```
+1. Semble로 유사 패턴 사전 조사
+2. /dev-review {focused_files} → 범위를 좁힌 리뷰
+```
+
+### CRG와 결합 사용
+
+```
+1. Semble "authentication related code" → 관련 파일 목록 식별
+2. CRG get_impact_radius(identified_files) → 영향 범위 확인
+3. 두 결과를 조합하여 완전한 컨텍스트 구성
+```
+
+## R013 Ecomode와의 관계
+
+R013 ecomode가 자동 활성화되는 시점 (context 사용량 ≥ 60%)에서 Semble을 적극 활용한다:
+
+| Ecomode 상황 | Semble 활용법 |
+|-------------|--------------|
+| 광범위 grep 대신 | Semble 의미 검색 → 관련 청크만 추출 |
+| 파일 전체 읽기 대신 | Semble으로 관련 섹션만 수신 |
+| 패턴 파악 시 | Semble 쿼리 → 대표 예시만 수집 |
+
+## 다른 자산과의 관계
+
+### 보완 관계 (함께 사용)
+
+| 자산 | 조합 방식 |
+|------|----------|
+| `crg-integration` | Semble (의미) + CRG (구조) 결합으로 완전한 코드 이해 |
+| `dev-review` | Semble로 유사 패턴 사전 조사 → dev-review 입력 최적화 |
+| `adversarial-review` | Semble로 관련 보안 패턴 수집 → adversarial-review 컨텍스트 보강 |
+
+### 대체 후보 (일부 use case)
+
+| 기존 방식 | Semble 대체 가능 여부 |
+|----------|---------------------|
+| `claude-mem:smart-explore` 의 자연어 탐색 | 일부 대체 가능 — 구조 탐색은 CRG 유지 |
+| grep + Read 조합의 패턴 검색 | 대체 권장 (98% 토큰 절감) |
+
+## 트러블슈팅
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| MCP 도구가 보이지 않음 | `.mcp.json` 미설정 또는 `claude mcp add` 미실행 | MCP 등록 확인, Claude Code 재시작 |
+| `command not found: semble` | uv tool install 미실행 또는 PATH 누락 | `uv tool install semble` 재실행, `which semble` 확인 |
+| 인덱싱 오류 | 초기 인덱싱 미완료 | `semble index` 실행 후 재시도 |
+| 검색 결과 없음 | 인덱싱 범위 외 또는 쿼리 불명확 | 인덱싱 재실행, 쿼리 구체화 |
+| 서버 연결 실패 | Semble MCP 서버 미실행 | MCP 서버 로그 확인, Claude Code 재시작 |
+| uv 미설치 | uv 패키지 매니저 없음 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` (사용자 직접 실행) |
+
+## 참고
+
+- 상세 설치/설정: `guides/token-efficiency/semble.md`
+- 관련 이슈: #1173 (scout:integrate Semble)
+- 기술 출처: [MinishLab/semble](https://github.com/MinishLab/semble)
+- 보완 자산: `crg-integration` (구조 기반 검색)

package/templates/CLAUDE.md

@@ -117,7 +117,7 @@ project/
 +-- CLAUDE.md                    # 진입점
 +-- .claude/
 |   +-- agents/                  # 서브에이전트 정의 (49 파일)
-|   +-- skills/                  # 스킬 (118 디렉토리)
+|   +-- skills/                  # 스킬 (119 디렉토리)
 |   +-- rules/                   # 전역 규칙 (R000-R023)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
@@ -246,6 +246,8 @@ Claude Code의 Agent Teams 기능이 활성화되어 있으면 (`CLAUDE_CODE_EXP
 | 서버 | 용도 |
 |------|------|
 | claude-mem | 세션 메모리 영속성 (Chroma 기반) |
+| code-review-graph | Token-efficient AST 기반 context retrieval (8.2× 토큰 절감) — wrapper: `crg-integration` 스킬 (#1171) |
+| semble | Semantic code search via embeddings (98% 토큰 절감, NDCG@10=0.854) — wrapper: `semble-integration` 스킬 (#1173) |
 
 ### 설치 명령어
 
@@ -261,6 +263,15 @@ Claude Code의 Agent Teams 기능이 활성화되어 있으면 (`CLAUDE_CODE_EXP
 # MCP 설정 (claude-mem)
 npm install -g claude-mem
 claude-mem setup
+
+# CRG MCP 설치 (token efficiency)
+pipx install code-review-graph
+# .mcp.json 에 code-review-graph 서버 수동 추가 (R001 auto-install 금지)
+
+# Semble MCP 설치 (semantic code search)
+uv tool install semble
+claude mcp add semble -- semble mcp
+# 또는 .mcp.json 수동 편집 (R001 auto-install 금지)
 ```
 
 <!-- omcustom:git-workflow -->

package/templates/README.md

@@ -48,7 +48,7 @@ templates/
 ├── manifest.json                    # 배포 컴포넌트 카운트 및 메타데이터
 ├── .claude/
 │   ├── agents/                      # 에이전트 정의 파일 (*.md, 49개)
-│   ├── skills/                      # 스킬 모듈 (각 디렉토리에 SKILL.md, 118개)
+│   ├── skills/                      # 스킬 모듈 (각 디렉토리에 SKILL.md, 119개)
 │   ├── rules/                       # 전역 규칙 (R000–R023, 23개)
 │   ├── hooks/
 │   │   ├── hooks.json               # 훅 이벤트 설정 (PreToolUse/PostToolUse 등)
@@ -86,7 +86,7 @@ CI의 `verify-template-sync.sh`가 소스와 templates/ 간 일치를 검증합
 | Manager | 6 |
 | System | 4 |
 
-### Skills (118)
+### Skills (119)
 
 `.claude/skills/*/SKILL.md` — 재사용 가능한 스킬 모듈.
 

package/templates/guides/token-efficiency/semble.md

@@ -0,0 +1,188 @@
+# Semble 통합 가이드
+
+> **출처**: [MinishLab/semble](https://github.com/MinishLab/semble)
+> **관련 이슈**: #1173 (scout:integrate Semble)
+> **wrapper 스킬**: `.claude/skills/semble-integration/SKILL.md`
+
+## Semble 개요
+
+Semble은 [MinishLab](https://github.com/MinishLab)이 개발한 MCP(Model Context Protocol) 서버로, 코드 인식 청킹(Chonkie) + 정적 임베딩(Model2Vec potion-code-16M) + BM25 + RRF 조합으로 의미 기반 코드 검색을 제공한다.
+
+### 핵심 특성
+
+| 항목 | 값 |
+|------|-----|
+| 구현 | Python MCP server |
+| 청킹 엔진 | Chonkie (code-aware chunking) |
+| 임베딩 모델 | Model2Vec potion-code-16M (정적 임베딩) |
+| 검색 방식 | BM25 + RRF + embedding fusion |
+| GitHub | ~1.5k stars (2026-05 기준) |
+| 토큰 절감 | **~98%** (grep+Read 대비) |
+| 정확도 | NDCG@10 = **0.854** (transformer 모델 수준) |
+
+### R013 Ecomode 정합성
+
+Semble의 ~98% 토큰 절감은 R013 ecomode의 목표와 직접 정합한다. ecomode가 context 사용량 ≥ 60%에서 자동 활성화될 때, Semble 호출로 광범위한 grep+Read 비용을 대폭 줄일 수 있다.
+
+## 벤치마크 요약
+
+| 지표 | 값 | 비고 |
+|------|-----|------|
+| CPU 인덱싱 | ~250ms (레포당 평균) | GPU 불필요 |
+| 쿼리 응답 | ~1.5ms | 실시간 응답 수준 |
+| NDCG@10 | 0.854 | transformer 모델 대비 동급 |
+| 토큰 사용량 | ~98% 절감 | grep+Read 전략 대비 |
+
+> **출처**: #1173 이슈 본문 및 MinishLab/semble 공식 벤치마크
+
+### CRG와의 비교
+
+| 항목 | Semble | CRG (code-review-graph) |
+|------|--------|------------------------|
+| 검색 방식 | 의미 기반 (임베딩) | 구조 기반 (AST) |
+| 강점 | 자연어 쿼리, 패턴 유사성 | 호출 그래프, 의존성 분석 |
+| 약점 | 구조 정보 없음 | 의미 검색 약함 |
+| 토큰 절감 | ~98% (grep+Read 대비) | 8.2× |
+| 정확도 | NDCG@10 = 0.854 | precision 0.38 (recall-우선) |
+
+두 도구는 서로 다른 검색 축을 담당하며 결합 시 시너지 효과가 크다.
+
+## 설치
+
+> **R001 정책**: auto-install 스크립트 또는 hook 작성 금지. 아래 명령어는 개발자가 직접 실행한다.
+
+### 패키지 설치
+
+```bash
+# uv 기반 설치 (권장)
+uv tool install semble
+```
+
+uv가 없는 경우 먼저 설치한다 (사용자 직접 실행):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### MCP 서버 등록
+
+```bash
+# 방법 A: claude mcp 명령어 (권장)
+claude mcp add semble -- semble mcp
+
+# 방법 B: .mcp.json 수동 편집
+```
+
+`.mcp.json` 수동 설정 (프로젝트 루트 또는 `~/.claude/.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "semble": {
+      "command": "semble",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**주의**: `.mcp.json`을 자동으로 수정하는 스크립트나 hook은 R001 위반이다. 반드시 수동 편집한다.
+
+설정 후 Claude Code를 재시작하면 MCP 도구가 활성화된다.
+
+### 설치 확인
+
+```bash
+# 바이너리 확인
+which semble
+
+# 버전 확인
+semble --version
+```
+
+## 인덱싱
+
+Semble은 첫 MCP 호출 시 lazy 인덱싱을 수행하지만, 대용량 코드베이스의 경우 명시적 인덱싱을 권장한다:
+
+```bash
+# 프로젝트 루트에서 실행
+semble index
+
+# 특정 경로만 인덱싱
+semble index --path src/
+```
+
+인덱싱은 로컬 캐시에 저장된다. `.gitignore`에 추가를 권장한다.
+
+## 사용 시나리오
+
+### 의미 검색 → Semble
+
+자연어 쿼리로 코드 의미를 파악해야 할 때 Semble을 사용한다:
+
+| 작업 | 도구 | 이유 |
+|------|------|------|
+| "인증 관련 코드 전부 찾기" | Semble | 자연어 의미 검색 |
+| "에러 핸들링 컨벤션 파악" | Semble | 패턴 유사성 검색 |
+| "이 로직과 비슷한 코드 찾기" | Semble | 의미 유사성 |
+| "데이터 직렬화 예시 수집" | Semble | 코드 패턴 검색 |
+
+### 구조 분석 → CRG
+
+코드 구조와 의존성을 파악해야 할 때 CRG를 사용한다:
+
+| 작업 | 도구 | 이유 |
+|------|------|------|
+| "이 함수의 caller는?" | CRG (`query_graph`) | AST 기반 호출 그래프 |
+| "변경 영향 범위 파악" | CRG (`get_impact_radius`) | 의존성 트리 분석 |
+| "PR 리뷰 전 변경 폭 파악" | CRG (`detect_changes`) | 의미적 diff |
+
+### 결합 사용 예시
+
+두 도구를 결합하면 의미 + 구조 양면에서 완전한 코드 이해가 가능하다:
+
+```
+1. Semble "authentication middleware" → 관련 파일 목록 식별
+2. CRG get_impact_radius(identified_files) → 영향 범위 확인
+3. Semble "auth error handling" → 에러 처리 패턴 수집
+4. /dev-review {focused_files} → 좁혀진 범위의 상세 리뷰
+```
+
+## R013 Ecomode 통합
+
+context ≥ 60%에서 광범위한 파일 읽기 대신 Semble을 우선 사용한다:
+
+| 기존 방식 | Semble 대체 |
+|----------|-----------|
+| `Grep(pattern, recursive)` + `Read(file)` | Semble 의미 검색 단일 호출 |
+| `Read(multiple_files[])` 패턴 파악 목적 | Semble 쿼리 → 관련 청크만 수신 |
+| grep으로 키워드 검색 후 파일 읽기 | Semble 자연어 쿼리로 직접 청크 추출 |
+
+## Explore 에이전트 힌트
+
+Explore 에이전트가 Semble MCP를 사용 가능한 환경에서는, 코드베이스 탐색 시 grep+Read 조합보다 Semble 의미 검색을 우선 호출하는 것을 권장한다.
+
+> Explore 에이전트 description 갱신은 별도 이슈로 추적 가능 (본 PR scope 외).
+
+## 트러블슈팅
+
+| 증상 | 원인 | 해결 방법 |
+|------|------|---------|
+| MCP 도구가 Claude Code에 보이지 않음 | `.mcp.json` 미설정 또는 `claude mcp add` 미실행 | MCP 등록 확인 후 Claude Code 재시작 |
+| `command not found: semble` | 패키지 미설치 또는 PATH 누락 | `uv tool install semble`, `which semble` 확인 |
+| uv 명령어 없음 | uv 미설치 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` 실행 |
+| 첫 호출이 느림 | lazy 인덱싱 진행 중 | 정상 동작. `semble index`로 사전 인덱싱 권장 |
+| 검색 결과 없음 | 인덱싱 범위 외 또는 쿼리 불명확 | `semble index` 재실행, 쿼리 구체화 |
+| MCP 연결 실패 | Semble MCP 서버 미실행 | MCP 서버 로그 확인, `semble --version`으로 바이너리 확인 |
+| 인덱싱 실패 | 권한 문제 또는 코드베이스 경로 오류 | 실행 경로 확인, `semble index --path .` 시도 |
+
+## 참고 자료
+
+- **GitHub**: [MinishLab/semble](https://github.com/MinishLab/semble)
+- **wrapper 스킬**: `.claude/skills/semble-integration/SKILL.md`
+- **관련 이슈**: #1173 (scout:integrate Semble)
+- **보완 도구**: `guides/token-efficiency/crg.md` (구조 기반 검색)
+- **관련 규칙**:
+  - [[r001]] (MUST-safety.md): auto-install 금지 정책
+  - [[r013]] (SHOULD-ecomode.md): context budget 관리, ecomode 통합
+  - [[crg-integration]]: 구조 기반 검색 — 의미 검색 보완 대상

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.140.0",
+  "version": "0.141.0",
   "lastUpdated": "2026-05-18T00:00:00.000Z",
   "omcustomMinClaudeCode": "2.1.121",
   "omcustomMinClaudeCodeReason": "Sensitive-path direct Write/Edit on .claude/** under bypassPermissions (R010 deprecation, #1101)",
@@ -20,7 +20,7 @@
       "name": "skills",
       "path": ".claude/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 118
+      "files": 119
     },
     {
       "name": "guides",