@tienne/gestalt 0.9.1 → 0.10.0

package/skills/build-graph/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: build-graph
+version: "1.0.0"
+description: "Build a code knowledge graph for the current repository to enable blast-radius analysis"
+triggers:
+  - "build graph"
+  - "build-graph"
+  - "index codebase"
+  - "build code graph"
+inputs:
+  repoRoot:
+    type: string
+    required: false
+    description: "Repository root path (defaults to current working directory)"
+  include:
+    type: string[]
+    required: false
+    description: "Glob patterns to include (default: **/*)"
+  exclude:
+    type: string[]
+    required: false
+    description: "Glob patterns to exclude"
+  mode:
+    type: string
+    required: false
+    description: "Build mode: 'full' (default) or 'incremental' (hash-based, skip unchanged files)"
+outputs:
+  - nodesBuilt
+  - edgesBuilt
+  - timeTakenMs
+---
+
+# Build Graph Skill
+
+코드베이스를 정적 분석해 코드 지식 그래프를 빌드합니다. 이 그래프를 바탕으로 `/blast-radius` 스킬을 사용할 수 있습니다.
+
+## 목적
+
+코드 지식 그래프는 파일·함수·클래스 사이의 의존 관계를 SQLite DB(`.gestalt/code-graph.db`)에 저장합니다. 한 번 빌드해두면 `blast-radius` 분석으로 변경 영향 파일만 빠르게 조회할 수 있어 불필요한 파일 읽기를 크게 줄일 수 있습니다.
+
+## 지원 언어
+
+TypeScript / JavaScript, Python, Go, Java, Kotlin, Rust, Swift, Objective-C
+
+## 실행 방법
+
+### 기본 (전체 빌드)
+
+```
+ges_code_graph {
+  action: "build",
+  repoRoot: "<현재 디렉토리 절대 경로>"
+}
+```
+
+### 증분 빌드 (변경 파일만 재파싱)
+
+```
+ges_code_graph {
+  action: "build",
+  repoRoot: "<현재 디렉토리 절대 경로>",
+  mode: "incremental"
+}
+```
+
+### 특정 디렉토리만 포함
+
+```
+ges_code_graph {
+  action: "build",
+  repoRoot: "<경로>",
+  include: ["src/**", "lib/**"],
+  exclude: ["**/*.test.ts", "dist/**"]
+}
+```
+
+## 빌드 후 통계 확인
+
+```
+ges_code_graph {
+  action: "stats",
+  repoRoot: "<경로>"
+}
+```
+
+## 결과 해석
+
+| 필드 | 설명 |
+|------|------|
+| `nodesBuilt` | 인덱싱된 노드 수 (파일·함수·클래스·타입) |
+| `edgesBuilt` | 인덱싱된 엣지 수 (호출·임포트·상속·포함 관계) |
+| `timeTakenMs` | 소요 시간 (밀리초) |
+
+## Skill Instructions
+
+1. `repoRoot`가 주어지지 않으면 현재 작업 디렉토리(`cwd`)를 절대 경로로 사용합니다.
+2. `ges_code_graph { action: "build", repoRoot: "<repoRoot>", mode: "<mode>" }`를 호출합니다.
+3. 빌드 결과를 사용자에게 표시합니다.
+4. "그래프 빌드 완료! 이제 `/blast-radius`로 변경 영향 파일을 분석할 수 있습니다." 안내를 포함합니다.
+5. 오류가 발생하면 오류 내용을 표시하고 지원 언어인지 확인하도록 안내합니다.

package/skills/diff-radius/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: diff-radius
+version: "1.0.0"
+description: "커밋 전 미저장·스테이징 변경의 영향범위를 분석한다. 작업 중인 코드가 어디까지 영향 주는지 바로 확인할 때 자동 발동한다."
+triggers:
+  # 작업 중 변경 확인
+  - "지금 바꾼 거 영향범위"
+  - "작업 중인 거 영향범위"
+  - "저장한 거 영향범위"
+  - "수정 중인 거 영향범위"
+  - "아직 커밋 안 한 거 영향범위"
+  - "미커밋 영향범위"
+  # 스테이징 확인
+  - "스테이징된 거 영향범위"
+  - "staged 영향범위"
+  - "git add 한 거 영향범위"
+  # 커밋 전 안전 확인
+  - "커밋 전에 영향범위"
+  - "올리기 전에 영향범위"
+  - "푸시 전에 영향범위"
+inputs:
+  repoRoot:
+    type: string
+    required: false
+    description: "Repository root path (defaults to current working directory)"
+  diffMode:
+    type: string
+    required: false
+    description: "staged: git diff --cached, unstaged: git diff, all: staged+unstaged (default)"
+  maxDepth:
+    type: number
+    required: false
+    description: "BFS traversal depth (default: 2)"
+outputs:
+  - changedFiles
+  - impactedFiles
+  - riskScore
+  - summary
+---
+
+# Diff Radius Skill
+
+커밋하지 않은 변경의 영향범위를 분석합니다. `/blast-radius`가 커밋 기준이라면, 이 스킬은 **지금 작업 중인 변경** 기준으로 동작합니다.
+
+## 전제 조건
+
+코드 지식 그래프가 먼저 빌드되어 있어야 합니다:
+```
+/build-graph
+```
+
+## 실행 방법
+
+### 기본 (staged + unstaged 전체)
+
+```
+ges_code_graph {
+  action: "diff_radius",
+  repoRoot: "<현재 디렉토리 절대 경로>"
+}
+```
+
+### 스테이징된 변경만 (git add 한 것)
+
+```
+ges_code_graph {
+  action: "diff_radius",
+  repoRoot: "<경로>",
+  diffMode: "staged"
+}
+```
+
+### 아직 스테이징 안 된 변경만
+
+```
+ges_code_graph {
+  action: "diff_radius",
+  repoRoot: "<경로>",
+  diffMode: "unstaged"
+}
+```
+
+## blast-radius와 차이
+
+| | `/blast-radius` | `/diff-radius` |
+|---|---|---|
+| 기준 | 마지막 커밋 (`HEAD~1`) | 현재 작업 중인 변경 |
+| git 명령 | `git diff HEAD~1` | `git diff HEAD` / `git diff --cached` |
+| 용도 | 배포된 변경 영향 확인 | 커밋 전 영향범위 사전 확인 |
+
+## 결과 해석
+
+| 필드 | 설명 |
+|------|------|
+| `changedFiles` | 변경된 파일 목록 |
+| `impactedFiles` | 영향받는 파일 목록 (테스트 파일 우선 정렬) |
+| `riskScore` | 위험도 점수 0~1 |
+| `summary` | 한 줄 요약 |
+
+## Skill Instructions
+
+1. `repoRoot`가 주어지지 않으면 현재 작업 디렉토리를 절대 경로로 사용합니다.
+2. 코드 그래프 DB가 없으면 먼저 `/build-graph`를 실행하도록 안내합니다:
+   - `ges_code_graph { action: "db_exists", repoRoot: "<repoRoot>" }` 호출
+   - `exists: false`이면 빌드 먼저 안내
+3. `ges_code_graph { action: "diff_radius", repoRoot: "<repoRoot>", diffMode?: "staged"|"unstaged"|"all", maxDepth?: 2 }` 호출합니다.
+4. 결과를 다음 형식으로 표시합니다:
+
+```
+## 영향범위 분석 결과 (미커밋 변경)
+
+**변경된 파일** (N개):
+- src/auth.ts
+- src/middleware.ts
+
+**영향받는 파일** (M개):
+- src/auth.test.ts        ← 테스트 파일 우선
+- src/api/routes.ts
+
+**위험도**: 0.23 (낮음)
+**요약**: {summary}
+```
+
+5. `impactedFiles` 목록을 컨텍스트로 활용합니다.
+6. 변경된 파일이 없으면 "현재 미커밋 변경이 없습니다." 안내합니다.

package/skills/setup/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: setup
+version: "1.0.0"
+description: "Gestalt 프로젝트 초기 설정 — gestalt.json 생성, 코드 그래프 빌드, post-commit 훅 설치"
+triggers:
+  - "gestalt 초기화"
+  - "gestalt init"
+  - "gestalt setup"
+  - "setup gestalt"
+  - "프로젝트 설정"
+inputs:
+  cwd:
+    type: string
+    required: false
+    description: "초기화할 프로젝트 디렉토리 (기본값: 현재 디렉토리)"
+outputs:
+  - gestalt.json
+  - code-graph.db
+  - post-commit hook
+---
+
+# Setup Skill
+
+`gestalt init` 명령어와 동일한 초기화 작업을 Claude Code 스킬로 실행한다.
+
+## 실행 단계
+
+1. **선택 화면**: `AskUserQuestion`으로 실행할 단계를 다중 선택
+2. **gestalt.json 생성**: 프로젝트 루트에 기본 설정 파일 생성
+3. **코드 그래프 빌드**: `ges_code_graph { action: "build" }`로 의존성 그래프 구축
+4. **post-commit 훅 설치**: `gestalt init --skip-graph --skip-hook`을 활용해 훅만 설치
+
+---
+
+## 실행 방법
+
+### Step 1 — 실행할 단계 선택
+
+`AskUserQuestion`으로 다음 질문을 표시한다. **3개 모두 기본 선택**으로 제시한다.
+
+```
+질문: "실행할 초기화 단계를 선택하세요 (기본: 전체)"
+multiSelect: true
+옵션:
+  - label: "gestalt.json 생성 (Recommended)"
+    description: "프로젝트 루트에 gestalt.json 설정 파일을 생성합니다"
+  - label: "코드 그래프 빌드 (Recommended)"
+    description: "코드베이스를 분석해 의존성 그래프를 구축합니다 (시간이 걸릴 수 있음)"
+  - label: "post-commit 훅 설치 (Recommended)"
+    description: "커밋 시 코드 그래프를 자동으로 갱신하는 git 훅을 설치합니다"
+```
+
+선택된 항목에 따라 아래 단계를 순서대로 실행한다. 아무것도 선택하지 않으면 중단한다.
+
+---
+
+### Step 2 — gestalt.json 생성 (선택된 경우)
+
+프로젝트 루트에 `gestalt.json`이 이미 존재하는지 확인한다.
+
+**파일이 없으면**: Bash로 생성한다.
+
+```bash
+! pnpm tsx bin/gestalt.ts setup
+```
+
+또는 npx로 설치된 환경이면:
+
+```bash
+! npx @tienne/gestalt setup
+```
+
+**파일이 이미 존재하면**: 사용자에게 덮어쓸지 확인 후 진행한다.
+
+성공 시 출력:
+```
+✓ gestalt.json 생성 완료
+```
+
+---
+
+### Step 3 — 코드 그래프 빌드 (선택된 경우)
+
+`ges_code_graph` MCP 툴을 사용한다.
+
+```
+ges_code_graph({ action: "build", repoRoot: "<현재 디렉토리 절대경로>" })
+```
+
+응답 예시:
+```json
+{ "nodesBuilt": 1192, "edgesBuilt": 1321, "timeTakenMs": 4200 }
+```
+
+성공 시 출력:
+```
+✓ 코드 그래프 빌드 완료: 노드 {nodesBuilt}개, 엣지 {edgesBuilt}개 ({timeTakenMs}ms)
+```
+
+실패해도 다음 단계를 계속 진행한다 (non-fatal).
+
+---
+
+### Step 4 — post-commit 훅 설치 (선택된 경우)
+
+```bash
+! pnpm tsx bin/gestalt.ts init --skip-graph
+```
+
+또는:
+
+```bash
+! npx @tienne/gestalt init --skip-graph
+```
+
+성공 시 출력:
+```
+✓ post-commit 훅 설치 완료
+```
+
+---
+
+### Step 5 — 완료 메시지
+
+선택된 모든 단계 완료 후:
+
+```
+Gestalt 초기화 완료!
+
+완료된 단계:
+  ✓ gestalt.json 생성
+  ✓ 코드 그래프 빌드 (노드 1192개, 엣지 1321개)
+  ✓ post-commit 훅 설치
+
+이제 다음 스킬을 바로 사용할 수 있습니다:
+  /gestalt:interview  — 요구사항 인터뷰
+  /build-graph        — 코드 그래프 갱신
+  /blast-radius       — 영향 범위 분석
+```
+
+---
+
+## 에러 처리
+
+| 상황 | 대응 |
+|------|------|
+| `gestalt.json` 이미 존재 | 덮어쓸지 확인 후 진행 |
+| 코드 그래프 빌드 실패 | 경고 출력 후 다음 단계 계속 |
+| git 저장소 아님 | post-commit 훅 설치 건너뜀 + 안내 |
+| CLI 명령어 없음 | `pnpm add @tienne/gestalt` 안내 |