@tienne/gestalt 0.9.0 → 0.9.2

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Gestalt — AI Development Harness
 
 ## Overview
-게슈탈트 심리학 원리를 요구사항 명확화 프로세스에 매핑한 TypeScript 기반 AI 개발 하네스.
+게슈탈트 지각이론을 요구사항 명확화 프로세스에 매핑한 TypeScript 기반 AI 개발 하네스.
 "전체는 부분의 합보다 크다" — 흩어진 요구사항 조각들을 모아 완전한 스펙(Spec)으로 결정화.
 
 ## Architecture
@@ -11,6 +11,7 @@
 - **Resilience Engine**: Stagnation 감지 → Lateral Thinking Personas → Human Escalation
 - **MCP Server**: stdio transport로 Claude Code 등 AI 에이전트와 통합
 - **Skill System**: SKILL.md 기반 확장, chokidar hot-reload 지원. 각 스킬(`/interview`, `/spec`, `/execute`)은 실행 중 Claude Code Task 패널에 진행 상태를 `TaskCreate`/`TaskUpdate`로 실시간 표시 (공통 진행 패널)
+- **Code Knowledge Graph**: 코드베이스 정적 분석 → 의존성 그래프화 → Blast-Radius로 영향 파일 추림. Execute 파이프라인 태스크 실행 시 `suggestedFiles`로 자동 컨텍스트 주입해 불필요한 파일 읽기를 줄임
 - **Event Store**: better-sqlite3 WAL 모드 이벤트 소싱
 
 ## Tech Stack
@@ -25,6 +26,9 @@ pnpm tsx bin/gestalt.ts interview "topic"  # Interactive interview
 pnpm tsx bin/gestalt.ts spec <session-id>  # Generate spec
 pnpm tsx bin/gestalt.ts status             # Check sessions
 pnpm tsx bin/gestalt.ts setup              # Generate gestalt.json config
+pnpm tsx bin/gestalt.ts init               # One-step onboarding: gestalt.json + code graph + post-commit hook
+pnpm tsx bin/gestalt.ts init --skip-graph  # Skip code graph build
+pnpm tsx bin/gestalt.ts init --skip-hook   # Skip post-commit hook installation
 ```
 
 ## Configuration
@@ -57,6 +61,7 @@ interface GestaltConfig {
   llm: { apiKey: string; model: string };
   interview: { ambiguityThreshold: number; maxRounds: number };
   execute: { driftThreshold: number; successThreshold: number; goalAlignmentThreshold: number };
+  notifications: boolean;
   dbPath: string;
   skillsDir: string;
   agentsDir: string;
@@ -75,6 +80,7 @@ interface GestaltConfig {
 | `GESTALT_DRIFT_THRESHOLD` | `execute.driftThreshold` | `0.3` |
 | `GESTALT_EVOLVE_SUCCESS_THRESHOLD` | `execute.successThreshold` | `0.85` |
 | `GESTALT_EVOLVE_GOAL_ALIGNMENT_THRESHOLD` | `execute.goalAlignmentThreshold` | `0.80` |
+| `GESTALT_NOTIFICATIONS` | `notifications` | `false` |
 | `GESTALT_DB_PATH` | `dbPath` | `"~/.gestalt/events.db"` |
 | `GESTALT_SKILLS_DIR` | `skillsDir` | `"skills"` |
 | `GESTALT_AGENTS_DIR` | `agentsDir` | `"agents"` |
@@ -87,6 +93,7 @@ interface GestaltConfig {
 - `ges_generate_spec`: sessionId? (optional), text? (optional), force?, spec? (passthrough)
 - `ges_execute`: action=[start|plan_step|plan_complete|execute_start|execute_task|evaluate|status|evolve_fix|evolve|evolve_patch|evolve_re_execute|evolve_lateral|evolve_lateral_result|role_match|role_consensus]
 - `ges_create_agent`: action=[start|submit] — 인터뷰 기반 커스텀 Role Agent 생성
+- `ges_code_graph`: action=[build|blast_radius|query|stats|db_exists] — 코드 지식 그래프 관리
 - `ges_status`: sessionId?
 
 ## MCP Passthrough Mode
@@ -365,6 +372,7 @@ ges_execute({ action: "role_consensus", sessionId: "<id>", consensus: {...} })
 - `src/spec/` — SpecGenerator, SpecExtractor
 - `src/execute/` — ExecuteEngine, DAG Validator, ExecuteSessionManager
 - `src/resilience/` — Stagnation Detector, Lateral Thinking Personas, Human Escalation
+- `src/code-graph/` — CodeGraphEngine, CodeGraphStore, BlastRadius, 언어 플러그인 8개
 - `src/skills/` — SkillRegistry, parser
 - `src/agent/` — AgentRegistry, FiguralRouter, multi-provider LLM, RoleAgentRegistry, PassthroughAgentGenerator
 - `src/registry/` — BaseRegistry 추상 클래스
@@ -374,6 +382,75 @@ ges_execute({ action: "role_consensus", sessionId: "<id>", consensus: {...} })
 - `src/cli/` — commander 기반 CLI (interview, spec, status, setup)
 - `schemas/` — JSON Schema (gestalt.schema.json)
 - `role-agents/` — 내장 Role Agent 정의 (architect, frontend-developer 등 8개)
+- `skills/` — 외부 스킬 정의 (`build-graph`, `blast-radius`)
+
+## Code Knowledge Graph
+
+코드베이스를 정적 분석해 의존성 그래프를 빌드하고, 변경 영향 파일을 빠르게 추려 AI 컨텍스트를 절약한다.
+
+### ges_code_graph MCP 툴
+
+```
+// 그래프 빌드 (최초 또는 full rebuild)
+ges_code_graph({ action: "build", repoRoot: "<절대경로>" })
+→ { nodesBuilt, edgesBuilt, timeTakenMs, installedHook }
+
+// Blast-Radius 분석 (커밋 기준 영향범위)
+ges_code_graph({ action: "blast_radius", repoRoot: "<경로>", base?: "HEAD~1", changedFiles?: [...], maxDepth?: 2 })
+→ { changedFiles, impactedFiles, riskScore, summary }
+
+// Diff-Radius 분석 (미커밋 변경 기준 영향범위)
+ges_code_graph({ action: "diff_radius", repoRoot: "<경로>", diffMode?: "staged"|"unstaged"|"all", maxDepth?: 2 })
+→ { changedFiles, impactedFiles, riskScore, summary }
+
+// 키워드 기반 관련 파일 검색
+ges_code_graph({ action: "query", repoRoot: "<경로>", pattern: "callers_of"|"callees_of"|"tests_for"|"imports_of", target: "<노드명>" })
+→ { nodes, edges }
+
+// 그래프 통계
+ges_code_graph({ action: "stats", repoRoot: "<경로>" })
+→ { totalFiles, totalNodes, totalEdges, lastBuiltAt, dbSizeBytes }
+
+// DB 존재 여부 확인
+ges_code_graph({ action: "db_exists", repoRoot: "<경로>" })
+→ { exists: boolean }
+```
+
+저장소: `.gestalt/code-graph.db` (WAL SQLite, EventStore DB와 별도)
+
+### 자동 컨텍스트 주입 (Execute 파이프라인 통합)
+
+`ges_execute { action: "start", spec: {...}, codeGraphRepoRoot: "/path" }` 호출 시 활성화.
+
+태스크 실행 시 `buildNextTaskContext()`가 자동으로:
+1. 태스크 title + description에서 키워드를 추출 (`extractKeywords()`)
+2. `codeGraphEngine.searchByKeywords()`로 관련 파일 최대 10개 검색
+3. `execute_task` 응답의 `suggestedFiles` 필드로 반환
+
+Claude Code가 `suggestedFiles`를 받으면 해당 파일을 먼저 Read한 뒤 태스크를 수행한다 (`EXECUTE_EXECUTION_SYSTEM_PROMPT` 지시).
+
+code-graph.db가 없거나 검색 실패 시 `suggestedFiles`는 undefined — 기존 동작 그대로 유지 (graceful fallback).
+
+### 스킬
+
+| 스킬 | 파일 | 설명 |
+|------|------|------|
+| `/build-graph` | `skills/build-graph/SKILL.md` | 코드 그래프 빌드 및 증분 갱신 |
+| `/blast-radius` | `skills/blast-radius/SKILL.md` (v1.1.0) | 영향범위 분석 (커밋 기준), 23개 트리거 |
+| `/diff-radius` | `skills/diff-radius/SKILL.md` (v1.0.0) | 영향범위 분석 (미커밋 기준), staged/unstaged/all 지원 |
+
+blast-radius 스킬은 "영향범위", "어디까지 영향받아", "사이드 이펙트", "리팩토링" 등 자연스러운 한국어 표현으로 자동 발동한다. CLAUDE.md나 훅과 달리 호출 시에만 토큰이 발생한다.
+
+### 언어 플러그인 (8개)
+
+TypeScript/JavaScript, Python, Go, Java, Kotlin, Rust, Swift, Objective-C
+
+각 플러그인: `{ language, extensions[], parse(filePath) → {nodes, edges} }`
+TypeScript 플러그인은 TypeScript Compiler API 사용 (Tree-sitter 불필요).
+
+### 주의사항
+- `glob` 패키지 미사용 → `readdirSync({ recursive: true })`로 파일 수집, `Dirent.parentPath` 활용
+- `noUncheckedIndexedAccess` 환경 → 배열 인덱스·regex 캡처그룹에 `!` 단언 필수
 
 ## Conventions
 - MCP 서버에서 `console.log` 사용 금지 → stderr(`log()` 유틸)

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -46,6 +46,7 @@
     "gray-matter": "^4.0.3",
     "ink": "^6.8.0",
     "jimp": "^1.6.0",
+    "node-notifier": "^10.0.1",
     "node-pty": "^1.1.0",
     "openai": "^6.27.0",
     "react": "^19.2.4",
@@ -54,6 +55,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.13.10",
+    "@types/node-notifier": "^8.0.5",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
     "vitest": "^3.0.9"

package/dist/schemas/gestalt.schema.json

@@ -87,6 +87,11 @@
       "description": "Directory containing agent definitions (env: GESTALT_AGENTS_DIR)",
       "default": "agents"
     },
+    "notifications": {
+      "type": "boolean",
+      "description": "Enable OS desktop notifications for pipeline events (env: GESTALT_NOTIFICATIONS)",
+      "default": false
+    },
     "logLevel": {
       "type": "string",
       "enum": ["debug", "info", "warn", "error"],

package/dist/skills/blast-radius/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: blast-radius
+version: "1.1.0"
+description: "코드 변경 전 영향 범위를 파악해 읽어야 할 파일만 컨텍스트에 제공한다. 변경 범위가 불확실하거나 사이드 이펙트가 걱정될 때 자동 발동한다."
+triggers:
+  # 영향범위 확인 의도
+  - "영향범위"
+  - "영향범위 확인"
+  - "영향범위 얼마나 돼"
+  - "어디까지 영향받아"
+  - "어디 영향받아"
+  - "뭐가 깨질 수 있어"
+  - "어떤 파일 같이 봐야 해"
+  - "관련 파일 뭐 있어"
+  - "어디 의존하고 있어"
+  - "어디서 쓰이고 있어"
+  # 변경 전 안전 확인 의도
+  - "건드리기 전에"
+  - "수정 전에 확인"
+  - "수정 범위"
+  - "사이드 이펙트"
+  # 범위가 큰 변경 작업
+  - "시그니처 바꿔"
+  - "인터페이스 변경"
+  - "타입 바꿔"
+  - "리팩토링"
+  # 기존 영어 표현 유지
+  - "blast radius"
+  - "blast-radius"
+  - "impact analysis"
+inputs:
+  repoRoot:
+    type: string
+    required: false
+    description: "Repository root path (defaults to current working directory)"
+  changedFiles:
+    type: string[]
+    required: false
+    description: "Changed file paths (auto-detected from git diff HEAD~1 if omitted)"
+  base:
+    type: string
+    required: false
+    description: "Git base ref for diff detection (default: HEAD~1)"
+  maxDepth:
+    type: number
+    required: false
+    description: "BFS traversal depth (default: 2)"
+outputs:
+  - changedFiles
+  - impactedFiles
+  - riskScore
+  - summary
+---
+
+# Blast Radius Skill
+
+최근 코드 변경의 영향 범위를 분석해 **읽어야 할 파일만** 컨텍스트에 제공합니다. 불필요한 파일 읽기를 줄여 LLM 토큰 사용을 최소화합니다.
+
+## 전제 조건
+
+코드 지식 그래프가 먼저 빌드되어 있어야 합니다:
+```
+/build-graph
+```
+
+## 실행 방법
+
+### 기본 (마지막 커밋 변경 파일 자동 감지)
+
+```
+ges_code_graph {
+  action: "blast_radius",
+  repoRoot: "<현재 디렉토리 절대 경로>"
+}
+```
+
+### 변경 파일 직접 지정
+
+```
+ges_code_graph {
+  action: "blast_radius",
+  repoRoot: "<경로>",
+  changedFiles: ["src/auth.ts", "src/middleware.ts"]
+}
+```
+
+### Git base ref 지정
+
+```
+ges_code_graph {
+  action: "blast_radius",
+  repoRoot: "<경로>",
+  base: "main"
+}
+```
+
+## 결과 해석
+
+| 필드 | 설명 |
+|------|------|
+| `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: "blast_radius", repoRoot: "<repoRoot>", changedFiles?: [...], base?: "...", maxDepth?: 2 }` 호출합니다.
+4. 결과를 다음 형식으로 표시합니다:
+
+```
+## 영향범위 분석 결과
+
+**변경된 파일** (N개):
+- src/auth.ts
+- src/middleware.ts
+
+**영향받는 파일** (M개):
+- src/auth.test.ts        ← 테스트 파일 우선
+- src/api/routes.ts
+- src/api/middleware.ts
+
+**위험도**: 0.23 (낮음)
+**요약**: {summary}
+```
+
+5. `impactedFiles` 목록을 컨텍스트로 활용합니다:
+   - "아래 파일들이 영향을 받을 수 있습니다. 관련 작업 전 이 파일들을 먼저 읽어보겠습니다:" 형식으로 안내
+   - 파일이 많으면 (10개 이상) 가장 중요한 파일(테스트 파일, 핵심 모듈)을 우선 읽도록 제안
+6. 빌드된 그래프가 오래된 경우 `/build-graph --incremental` 실행을 권장합니다.

package/dist/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/dist/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/dist/skills/execute/SKILL.md

@@ -183,6 +183,67 @@ API 키 없이 MCP 서버 실행 시 자동 활성화. LLM 작업을 caller가
 
 ---
 
+### 병렬 그룹 실행 (parallelGroups 활용)
+
+`plan_complete` 응답에 `parallelGroups: string[][]`가 포함되어 있으면 병렬 실행을 사용한다. 각 내부 배열은 동시에 실행할 수 있는 태스크 ID 묶음이다.
+
+**병렬 그룹 실행 흐름:**
+
+1. `parallelGroups[groupIndex]`의 taskId 목록을 확인한다.
+2. **단일 메시지에서** 각 taskId마다 Agent 툴을 하나씩, 동시에 호출한다 (여러 Agent 툴 호출을 같은 메시지에 담는다).
+3. 각 Agent는 독립적으로 해당 태스크를 수행하고, 완료되면 `execute_task`를 호출해 결과를 제출한다.
+4. 그룹 내 일부 Agent가 실패해도 나머지는 계속 실행한다. 실패한 태스크는 `status: "failed"`로 제출한다.
+5. 그룹 내 모든 Agent가 완료되면 다음 그룹으로 넘어간다.
+6. 모든 그룹이 완료된 후 실패한 태스크가 있으면 기존 evolve 파이프라인으로 재처리한다.
+
+**Agent 툴 호출 예시 (parallelGroups[0] = ["task-0", "task-1", "task-2"] 인 경우):**
+
+단일 메시지에서 세 Agent를 동시에 실행한다.
+
+```
+// 같은 메시지에서 동시 호출 — Agent 1
+Agent(task: "task-0 실행: {task-0 title}\n컨텍스트: {taskContext}\n완료 후 execute_task로 결과 제출")
+
+// 같은 메시지에서 동시 호출 — Agent 2
+Agent(task: "task-1 실행: {task-1 title}\n컨텍스트: {taskContext}\n완료 후 execute_task로 결과 제출")
+
+// 같은 메시지에서 동시 호출 — Agent 3
+Agent(task: "task-2 실행: {task-2 title}\n컨텍스트: {taskContext}\n완료 후 execute_task로 결과 제출")
+```
+
+**각 Agent의 execute_task 제출:**
+
+```json
+{
+  "action": "execute_task",
+  "sessionId": "...",
+  "taskResult": {
+    "taskId": "task-0",
+    "status": "completed",
+    "output": "태스크 수행 결과 요약",
+    "artifacts": ["path/to/file.ts"]
+  }
+}
+```
+
+실패 시:
+```json
+{
+  "action": "execute_task",
+  "sessionId": "...",
+  "taskResult": {
+    "taskId": "task-1",
+    "status": "failed",
+    "output": "실패 원인 설명",
+    "artifacts": []
+  }
+}
+```
+
+**parallelGroups가 없는 경우:** 기존 순차 실행 방식을 사용한다.
+
+---
+
 ### `execute_task` — 태스크 실행 결과 제출
 
 role_match/role_consensus로 얻은 `roleGuidance`를 참조해 태스크를 수행한 후 결과 제출.
@@ -381,26 +442,47 @@ Planning 패널 태스크를 완료하고, 새 Execution 패널 태스크를 생
 
 ```
 subject: "Gestalt Execute: {spec.goal 앞 40자}"
-description: "0/{totalTasks} 완료 | 현재: 시작 대기 중 | 실패: 0개 | 그룹 0/{parallelGroupCount}"
-activeForm: "태스크 실행 중"
+description: "0/{totalTasks} 완료 | 실패: 0개 | 그룹 0/{parallelGroupCount}"
+activeForm: "실행 중: {taskContext.currentTask.title}"
 ```
 
 `plan_complete` 응답의 `planSummary.totalTasks`와 `planSummary.parallelGroupCount`를 활용한다.
+`taskContext.currentTask.title`은 `execute_start` 응답에서 바로 꺼내 쓴다.
+
+### 병렬 그룹 실행 시작 시 (Agent 툴 동시 호출 직전)
+
+각 병렬 그룹 실행을 시작하기 전에 `TaskUpdate`로 병렬 실행 상태를 표시한다.
+
+```
+activeForm: "병렬 실행 중: 그룹 {groupIndex}/{totalGroups} — {agentCount}개 Agent 실행 중"
+```
+
+- `groupIndex`: 현재 병렬 그룹 번호 (1부터 시작)
+- `totalGroups`: 전체 병렬 그룹 수 (`parallelGroups.length`)
+- `agentCount`: 현재 그룹의 태스크 수 (`parallelGroups[groupIndex].length`)
 
 ### 각 태스크 완료 후 (`execute_task` 응답 수신 시마다)
 
-`TaskUpdate`로 진행 상황을 업데이트한다.
+`TaskUpdate`로 진행 상황과 현재 실행 태스크명을 업데이트한다.
+
+순차 실행 중:
+```
+description: "{completedCount}/{totalTasks} 완료 | 실패: {failedCount}개 | 그룹 {groupIndex}/{totalGroups}"
+activeForm: "실행 중: {taskContext.currentTask.title}"
+```
 
+병렬 그룹 실행 중 (각 Agent의 execute_task 완료 시):
 ```
-description: "{completedCount}/{totalTasks} 완료 | 현재: {nextTask.title or '완료'} | 실패: {failedCount}개 | 그룹 {groupIndex}/{totalGroups}"
+description: "{completedCount}/{totalTasks} 완료 | 실패: {failedCount}개 | 그룹 {groupIndex}/{totalGroups}"
+activeForm: "병렬 실행 중: 그룹 {groupIndex}/{totalGroups} — {agentCount}개 Agent 실행 중"
 ```
 
-- `completedCount`: 지금까지 제출한 taskResult 수
-- `nextTask`: 응답의 `nextTaskId`로 다음 태스크 이름 추론
+- `completedCount`: 지금까지 제출한 taskResult 수 (`response.completedTasks`)
 - `failedCount`: status가 `failed`인 taskResult 수
-- `groupIndex/totalGroups`: `plan_complete` 응답의 `parallelGroups` 기준
+- `groupIndex/totalGroups`: 현재 처리 중인 병렬 그룹 번호 / 전체 그룹 수
+- `agentCount`: 해당 그룹에서 아직 실행 중인 Agent 수
 
-`allTasksCompleted === true` 이면 description에 "전체 완료" 표시 후 `TaskUpdate`로 status를 completed로 변경한다.
+`allTasksCompleted === true` 이면 `TaskUpdate({ status: "completed", activeForm: undefined, description: "전체 완료 ({totalTasks}개)" })`로 변경한다.
 
 ### 평가/진화 단계
 

package/dist/skills/interview/SKILL.md

@@ -93,16 +93,17 @@ API 키 없이 MCP 서버 실행 시 자동 활성화. LLM 작업을 caller가
 
 ```
 subject: "Gestalt 인터뷰: {topic}"
-description: "라운드 1/{maxRounds} | 원리: {currentPrinciple} | 모호성: 측정 전"
-activeForm: "인터뷰 진행 중"
+description: "라운드 1/{maxRounds} | 모호성: 측정 전"
+activeForm: "라운드 1 — {currentPrinciple}"
 ```
 
 ### 각 라운드 후 (`respond` 응답 수신 시마다)
 
-`TaskUpdate`로 description을 최신 상태로 갱신한다. 모호성 점수는 추이 형식으로 표시한다.
+`TaskUpdate`로 description과 activeForm을 최신 상태로 갱신한다. 모호성 점수는 추이 형식으로 표시한다.
 
 ```
-description: "라운드 {roundNumber}/{maxRounds} | 원리: {currentPrinciple} | 모호성: {score1} → {score2} → {latestScore}"
+description: "라운드 {roundNumber}/{maxRounds} | 모호성: {score1} → {score2} → {latestScore}"
+activeForm: "라운드 {roundNumber} — {currentPrinciple}"
 ```
 
 ambiguityScore.isReady === true 이면 description에 "✓ 준비 완료" 표시를 추가한다.