@tienne/gestalt 0.7.0 → 0.9.0

package/CLAUDE.md

@@ -10,7 +10,7 @@
 - **Execute Engine**: 게슈탈트 5원리를 실행 전략으로 사용, Spec→ExecutionPlan 변환 (Figure-Ground→Closure→Proximity→Continuity)
 - **Resilience Engine**: Stagnation 감지 → Lateral Thinking Personas → Human Escalation
 - **MCP Server**: stdio transport로 Claude Code 등 AI 에이전트와 통합
-- **Skill System**: SKILL.md 기반 확장, chokidar hot-reload 지원
+- **Skill System**: SKILL.md 기반 확장, chokidar hot-reload 지원. 각 스킬(`/interview`, `/spec`, `/execute`)은 실행 중 Claude Code Task 패널에 진행 상태를 `TaskCreate`/`TaskUpdate`로 실시간 표시 (공통 진행 패널)
 - **Event Store**: better-sqlite3 WAL 모드 이벤트 소싱
 
 ## Tech Stack
@@ -84,7 +84,7 @@ interface GestaltConfig {
 
 ## MCP Tools
 - `ges_interview`: action=[start|respond|score|complete]
-- `ges_generate_spec`: sessionId, force?
+- `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_status`: sessionId?
@@ -159,8 +159,18 @@ ges_interview({ action: "complete", sessionId: "<id>" })
 ```
 
 **Step 6: Spec 생성 (2단계)**
+
+두 가지 입력 경로 중 하나를 선택한다.
+
 ```
-// 6a: specContext 요청
+// Text-based 경로 (인터뷰 불필요)
+ges_generate_spec({ text: "..." })
+→ specContext (systemPrompt, specPrompt) 반환
+
+ges_generate_spec({ text: "...", spec: {...} })
+→ Zod 검증 후 최종 Spec 반환 + .gestalt/memory.json 자동 업데이트
+
+// Interview 기반 경로 (6a: specContext 요청)
 ges_generate_spec({ sessionId: "<id>" })
 → specContext (systemPrompt, specPrompt, allRounds) 반환
 
@@ -346,6 +356,7 @@ ges_execute({ action: "role_consensus", sessionId: "<id>", consensus: {...} })
 - Spec의 `gestaltAnalysis[].principle`은 enum: `closure | proximity | similarity | figure_ground | continuity`
 - `ontologySchema.entities[]`: `{ name, description, attributes[] }`
 - `ontologySchema.relations[]`: `{ from, to, type }`
+- text-based 경로: `sessionId` 불필요, 생성된 spec의 `interviewSessionId`는 `"text-input"`으로 설정
 
 ## Project Structure
 - `src/core/` — types, errors, Result monad, config, constants

package/README.ko.md

@@ -4,7 +4,7 @@
 
 <p align="center">
   <strong>Gestalt — AI 개발 하네스</strong><br/>
-  모호한 요구사항을 구조화된 실행 계획으로 — Claude Code 안에서 바로.
+  흩어진 막연함을 하나의 실행 계획으로
 </p>
 
 <p align="center">
@@ -21,24 +21,34 @@
 
 ## Gestalt는 무엇인가요?
 
-Gestalt는 Claude Code 안에서 실행되는 MCP(Model Context Protocol) 서버예요. 구조화된 요구사항 인터뷰를 진행해 검증된 **Spec**(목표·제약조건·완료 기준을 담은 JSON 문서)을 만들어요. 그 Spec을 의존성 기반 실행 계획으로 변환할 때 별도 API 키는 필요하지 않아요.
+Gestalt는 Claude Code 안에서 실행되는 MCP(Model Context Protocol) 서버예요. 요구사항을 인터뷰로 구체화해 **Spec**(목표·제약조건·완료 기준)을 만들고, 그 Spec을 바탕으로 실행 계획을 짜요.
 
 > **시작 전 확인** — Node.js >= 20.0.0이 필요해요. `nvm install 22 && nvm use 22`로 설치할 수 있어요.
 
 ---
 
-## 실제로 어떻게 작동하나요?
+## 빠른 시작
 
-> **30초 만에 구조화된 실행 계획** — API 키 없이도 돼요.
+플러그인을 설치하세요 (최초 1회):
 
 ```bash
-# Gestalt 기반 요구사항 인터뷰 시작
+# 1단계: 마켓플레이스 등록
+/plugin marketplace add tienne/gestalt
+
+# 2단계: 플러그인 설치
+/plugin install gestalt@gestalt
+```
+
+설치가 끝나면 Claude Code에서 바로 사용할 수 있어요:
+
+```bash
+# 요구사항 인터뷰 시작
 /interview "사용자 인증 시스템"
 
-# 인터뷰 완료 후 구조화된 Spec 생성
+# 인터뷰 완료 후 Spec 생성
 /spec
 
-# Spec을 검증된 실행 계획으로 변환하고 실행
+# Spec을 실행 계획으로 만들고 실행
 /execute
 ```
 
@@ -88,17 +98,35 @@ Claude Code
   최종 Spec → 실행 계획
 ```
 
-`ANTHROPIC_API_KEY`는 필요하지 않아요. 모든 LLM 작업은 Claude Code가 처리해요.
-
 > **참고해 주세요** — CLI 직접 실행 모드에서는 `ANTHROPIC_API_KEY`가 필요해요. Claude Code 없이 터미널에서 바로 사용할 경우에만 해당돼요.
 
 ---
 
+## 프로젝트 메모리
+
+Spec과 실행 결과는 레포 루트의 `.gestalt/memory.json`에 자동으로 저장돼요.
+
+```json
+{
+  "specHistory": [
+    { "specId": "...", "goal": "Build a user auth system", "sourceType": "text" }
+  ],
+  "executionHistory": [],
+  "architectureDecisions": []
+}
+```
+
+- **커밋하세요** — `.gestalt/memory.json`은 일반 JSON 파일이에요. 커밋하면 팀원도 `git pull` 후 이전 결정 사항을 그대로 이어받을 수 있어요.
+- **컨텍스트 반영** — 다음 Spec을 생성할 때 이전 목표와 아키텍처 결정 사항이 프롬프트에 자동으로 반영돼요.
+- **User Profile** — 개인 설정은 `~/.gestalt/profile.json`에 저장돼요. git에는 올라가지 않아요.
+
+---
+
 ## 설치
 
 ### 옵션 1: Claude Code 플러그인 (권장)
 
-MCP 서버, 슬래시 커맨드 스킬, Gestalt 에이전트, 프로젝트 컨텍스트를 단일 설치로 묶어서 제공해요.
+설치 한 번에 MCP 서버, 슬래시 커맨드, Gestalt 에이전트, 프로젝트 컨텍스트를 모두 사용할 수 있어요.
 
 ```bash
 # 1단계: 마켓플레이스 등록 (최초 1회)
@@ -115,7 +143,7 @@ MCP 서버, 슬래시 커맨드 스킬, Gestalt 에이전트, 프로젝트 컨
 | **MCP 도구** | `ges_interview`, `ges_generate_spec`, `ges_execute`, `ges_create_agent`, `ges_agent`, `ges_status` |
 | **슬래시 커맨드** | `/interview`, `/spec`, `/execute`, `/agent` |
 | **에이전트** | Gestalt 파이프라인 에이전트 5개 + Role 에이전트 9개 + Review 에이전트 3개 |
-| **CLAUDE.md** | 프로젝트 컨텍스트 및 MCP 사용 가이드 자동 주입 |
+| **CLAUDE.md** | 프로젝트 컨텍스트 및 MCP 사용 가이드 자동 추가 |
 
 > **Node.js >= 20.0.0** 필요 — [nvm](https://github.com/nvm-sh/nvm) 사용 시: `nvm install 22 && nvm use 22`
 
@@ -172,7 +200,7 @@ claude mcp add gestalt -- npx -y @tienne/gestalt
 /interview "Stripe로 결제 플로우를 만들고 싶어"
 ```
 
-각 라운드는 특정 모호성 차원을 목표로 진행돼요:
+각 라운드는 모호한 부분을 집중해서 파악해요:
 
 - **Closure** — 빠진 요구사항과 말하지 않고 가정한 것을 찾아요
 - **Proximity** — 함께 묶여야 할 기능을 식별해요
@@ -188,17 +216,49 @@ claude mcp add gestalt -- npx -y @tienne/gestalt
 8라운드 → 모호성: 0.19  ✓ Spec 생성 준비 완료
 ```
 
+#### 인터뷰가 길어질 때 (Context Compression)
+
+라운드가 5개를 초과하면 Gestalt가 자동으로 압축을 제안해요. `compress` action을 사용하면 이전 대화를 요약해 컨텍스트를 줄일 수 있어요:
+
+```
+1. respond 응답에 needsCompression: true + compressionContext 포함
+2. ges_interview({ action: "compress", sessionId }) → compressionContext 반환
+3. caller가 요약 생성 후 제출 → 세션에 저장
+```
+
+이후 라운드에서 압축된 요약이 자동으로 반영돼요.
+
 ---
 
 ### 2단계 — Spec 생성
 
-모호성 점수가 ≤ 0.2에 도달하면 실행하세요:
+**옵션 A — 텍스트로 바로 생성 (인터뷰 불필요):**
+
+```bash
+ges_generate_spec({ text: "Stripe로 결제 플로우 구현" })
+```
+
+**옵션 A-2 — 내장 템플릿 사용:**
+
+3가지 내장 템플릿으로 빠르게 시작할 수 있어요:
+
+| 템플릿 ID | 설명 |
+|-----------|------|
+| `rest-api` | REST API 서버 (인증, CRUD, OpenAPI) |
+| `react-dashboard` | React 대시보드 앱 (차트, 필터, 반응형) |
+| `cli-tool` | CLI 도구 (서브커맨드, 설정, 배포) |
+
+```bash
+ges_generate_spec({ text: "JWT 인증이 포함된 API", template: "rest-api" })
+```
+
+**옵션 B — 완료된 인터뷰에서 생성:**
 
 ```bash
 /spec
 ```
 
-파이프라인 전체를 구동하는 구조화된 **Spec**을 생성해요:
+이후 단계 전체의 기준이 되는 **Spec**을 생성해요:
 
 ```
 goal                → 명확하고 모호성 없는 프로젝트 목표
@@ -212,7 +272,7 @@ gestaltAnalysis     → 게슈탈트 원리별 핵심 발견 사항
 
 ### 3단계 — Execute (계획 + 실행)
 
-Spec을 의존성 기반 실행 계획으로 변환하고 실행해요:
+Spec에서 실행 계획을 만들어 실행해요:
 
 ```bash
 /execute
@@ -227,11 +287,71 @@ Spec을 의존성 기반 실행 계획으로 변환하고 실행해요:
 | 3 | **Proximity** | 관련 태스크를 도메인별 그룹으로 묶음 |
 | 4 | **Continuity** | 의존성 DAG 검증 — 순환 없음, 위상 정렬 순서 확인 |
 
-**Execution 단계**에서 위상 정렬 순서대로 태스크를 실행해요. 각 태스크 후 **Drift Detection**이 Spec과의 정렬 상태를 확인해요:
+**Execution 단계**에서 위상 정렬 순서대로 태스크를 실행해요. 각 태스크 후 **Drift Detection**이 Spec과 얼마나 맞는지 확인해요:
 
 - 3차원 점수: Goal (50%) + Constraint (30%) + Ontology (20%)
 - Jaccard 유사도 기반 측정
-- Threshold를 초과하면 소급 검토가 자동으로 시작돼요
+- 임계값을 초과하면 회고(Retrospective)가 자동으로 시작돼요
+
+#### 병렬 실행 (Parallel Groups)
+
+`plan_complete` 응답에 `parallelGroups: string[][]`이 포함돼요. 의존성이 없는 태스크를 같은 그룹으로 묶어 동시에 실행해요:
+
+```json
+"parallelGroups": [
+  ["setup-db", "setup-env"],   // 동시 실행 가능
+  ["create-schema"],           // 위 그룹 완료 후 실행
+  ["seed-data", "run-tests"]   // 동시 실행 가능
+]
+```
+
+#### 실행 이어하기 (Resume)
+
+실행 중 세션이 중단되어도 이어서 계속할 수 있어요:
+
+```bash
+ges_execute({ action: "resume", sessionId: "<id>" })
+```
+
+`ResumeContext`를 반환해요: 완료된 태스크 목록, 다음 태스크, 진행률(%). `ges_status` 응답에도 `resumeContext`가 자동으로 포함돼요.
+
+#### Brownfield 감사 (Audit)
+
+기존 코드베이스가 있을 때 Spec 대비 구현 현황을 분석할 수 있어요:
+
+```bash
+# 1단계: 감사 컨텍스트 요청
+ges_execute({ action: "audit", sessionId: "<id>" })
+→ auditContext (systemPrompt, auditPrompt) 반환
+
+# 2단계: 코드베이스 스냅샷 + 감사 결과 제출
+ges_execute({
+  action: "audit",
+  sessionId: "<id>",
+  codebaseSnapshot: "...",
+  auditResult: { implementedACs: [0,2], partialACs: [1], missingACs: [3], gapAnalysis: "..." }
+})
+```
+
+#### 실행 진행 패널
+
+`/execute` 실행 중 Claude Code Task 패널에 진행 상태가 실시간으로 표시돼요. Planning 단계부터 Evaluate까지 각 완료 태스크 수, 현재 태스크 이름, 실패 수, 병렬 그룹 구조가 자동으로 갱신돼요.
+
+#### 하위 에이전트 생성 (Spawn)
+
+실행 중에 복잡한 태스크를 하위 태스크로 나눌 수 있어요:
+
+```bash
+ges_execute({
+  action: "spawn",
+  sessionId: "<id>",
+  parentTaskId: "task-3",
+  subTasks: [
+    { title: "DB 스키마 작성", description: "..." },
+    { title: "마이그레이션 실행", description: "...", dependsOn: ["spawned-<id>"] }
+  ]
+})
+```
 
 ---
 
@@ -241,7 +361,7 @@ Spec을 의존성 기반 실행 계획으로 변환하고 실행해요:
 
 | 단계 | 방식 | 실패 시 |
 |:---:|-------|-----------|
-| 1 | **Structural** — lint → build → test 실행 | 단락(short-circuit); 2단계 스킵 |
+| 1 | **Structural** — lint → build → test 실행 | 조기 종료(short-circuit); 2단계 건너뜀 |
 | 2 | **Contextual** — LLM이 각 AC + goal alignment 검증 | Evolution Loop 진입 |
 
 **성공 조건:** `score ≥ 0.85` AND `goalAlignment ≥ 0.80`
@@ -264,18 +384,18 @@ evolve → Spec 패치 (AC/constraints) → 영향받은 태스크 재실행 →
 
 Spec 패치 범위: AC와 constraints는 자유 수정; ontology는 추가/변경만; **goal은 변경 불가**.
 
-**Flow C — Lateral Thinking** (스태그네이션 감지 시)
+**Flow C — Lateral Thinking** (답보 상태 감지 시)
 
-종료하는 대신 Lateral Thinking Persona를 순환하며 다른 접근을 시도해요:
+종료하는 대신 Lateral Thinking Persona를 순서대로 적용하며 다른 접근을 시도해요:
 
-| 스태그네이션 패턴 | Persona | 전략 |
+| 답보 상태 패턴 | Persona | 전략 |
 |--------------------|---------|---------|
 | Hard cap 도달 | **Multistability** | 다른 각도로 보기 |
 | 진동하는 점수 | **Simplicity** | 단순하게 줄이고 수렴 |
 | 진전 없음 (no drift) | **Reification** | 빠진 것 채우기 |
-| 수익 체감 | **Invariance** | 성공한 패턴 복제 |
+| 효과 감소 | **Invariance** | 성공한 패턴 복제 |
 
-4개 Persona를 모두 소진하면 세션이 **Human Escalation**으로 종료돼요 — 수동 해결을 위한 구체적인 제안 목록과 함께.
+4개 Persona를 모두 소진하면 세션이 **Human Escalation**으로 종료돼요. 직접 해결할 수 있도록 구체적인 제안도 함께 제공해요.
 
 **종료 조건:**
 
@@ -298,7 +418,7 @@ Evolution 완료 후 코드 리뷰 파이프라인이 자동으로 실행돼요:
 review_start → 에이전트 관점 제출 → 합의 → 자동 수정
 ```
 
-9개의 내장 **Role 에이전트**가 다중 관점 리뷰를 제공해요:
+9개의 내장 **Role 에이전트**가 다양한 관점에서 리뷰해요:
 
 | 에이전트 | 도메인 |
 |-------|--------|
@@ -326,7 +446,7 @@ review_start → 에이전트 관점 제출 → 합의 → 자동 수정
 # 사용 가능한 에이전트 목록 조회
 /agent
 
-# 특정 에이전트로 임의 태스크 실행
+# 특정 에이전트로 원하는 태스크 실행
 /agent architect "이 코드베이스의 모듈 경계를 리뷰해줘"
 /agent security-reviewer "이 인증 코드의 취약점을 확인해줘"
 /agent technical-writer "이 모듈의 README를 작성해줘"
@@ -348,9 +468,9 @@ ges_create_agent  →  action: "submit", sessionId: "<id>", agentContent: "..."
 
 ---
 
-### 대안: CLI 직접 실행 모드
+### CLI 모드 (Claude Code 없이 사용하기)
 
-`ANTHROPIC_API_KEY`가 필요해요. Claude Code 없이 터미널에서 직접 실행할 수 있어요:
+Claude Code 없이 터미널에서 바로 사용하고 싶다면 CLI 모드를 이용할 수 있어요. **`ANTHROPIC_API_KEY`가 필요해요.**
 
 ```bash
 # 인터랙티브 인터뷰 시작
@@ -420,7 +540,7 @@ npx @tienne/gestalt setup
 
 **설정 우선순위** (높음 → 낮음): 코드 override → 쉘 환경변수 → `.env` → `gestalt.json` → 기본값
 
-잘못된 값은 경고를 출력하고 기본값으로 fallback해요.
+잘못된 값은 경고를 출력하고 기본값을 사용해요.
 
 ### 환경변수
 
@@ -455,15 +575,19 @@ Claude Code
 │  Interview Engine                │
 │  ├─ GestaltPrincipleSelector     │
 │  ├─ AmbiguityScorer              │
-│  └─ SessionManager               │
+│  ├─ SessionManager               │
+│  └─ ContextCompressor            │
 │                                  │
 │  Spec Generator                  │
-│  └─ PassthroughSpecGenerator     │
+│  ├─ PassthroughSpecGenerator     │
+│  └─ SpecTemplateRegistry         │
 │                                  │
 │  Execute Engine                  │
 │  ├─ DAG Validator                │
+│  ├─ ParallelGroupsCalculator     │
 │  ├─ DriftDetector                │
 │  ├─ EvaluationEngine             │
+│  ├─ AuditEngine                  │
 │  └─ ExecuteSessionManager        │
 │                                  │
 │  Resilience Engine               │

package/README.md

@@ -21,28 +21,33 @@
 
 ## What is Gestalt?
 
-Gestalt is an MCP (Model Context Protocol) server that runs inside Claude Code. It conducts structured requirement interviews, generates a validated **Spec** (a JSON document capturing your goal, constraints, and acceptance criteria), and transforms that Spec into a dependency-aware execution plan — all without a separate API key.
+Gestalt is an MCP (Model Context Protocol) server that runs inside Claude Code. It conducts structured requirement interviews, generates a validated **Spec** (a JSON document capturing your goal, constraints, and acceptance criteria), and transforms that Spec into a dependency-aware execution plan.
 
 > **Prerequisites:** Node.js >= 20.0.0. Use `nvm install 22 && nvm use 22` if needed.
 
 ---
 
-## See it in action
+## Quick Start
 
-> **30 seconds to a structured execution plan** — no API key needed.
+Install the plugin once, then use it in any Claude Code session:
 
 ```bash
-# Start a Gestalt-driven requirements interview
-/interview "user authentication system"
+# Step 1: Add to marketplace (one-time setup)
+/plugin marketplace add tienne/gestalt
 
-# Once the interview is done, generate a structured Spec
-/spec
+# Step 2: Install the plugin
+/plugin install gestalt@gestalt
+```
+
+Then in any Claude Code session:
 
-# Transform the Spec into a validated execution plan and run it
+```bash
+/interview "user authentication system"
+/spec
 /execute
 ```
 
-_(Demo coming soon.)_
+→ **[Full MCP Reference](./docs/mcp-reference.md)** — all tools, parameters, and examples
 
 ---
 
@@ -85,7 +90,25 @@ You (in Claude Code)
   Final Spec → Execution Plan
 ```
 
-`ANTHROPIC_API_KEY` is not required. All LLM work is handled by Claude Code.
+---
+
+## Project Memory
+
+Every spec and execution result is automatically recorded in `.gestalt/memory.json` at your repo root.
+
+```json
+{
+  "specHistory": [
+    { "specId": "...", "goal": "Build a user auth system", "sourceType": "text" }
+  ],
+  "executionHistory": [],
+  "architectureDecisions": []
+}
+```
+
+- **Commit it** — `.gestalt/memory.json` is plain JSON. Commit it and teammates inherit all prior decisions on `git pull`.
+- **Context injection** — When generating the next spec, prior goals and architecture decisions are automatically injected into the prompt.
+- **User profile** — Personal preferences are stored in `~/.gestalt/profile.json` and are never committed.
 
 ---
 
@@ -183,11 +206,43 @@ Round 4 → ambiguity: 0.45  (getting clearer)
 Round 8 → ambiguity: 0.19  ✓ ready for Spec
 ```
 
+#### Long interviews: Context Compression
+
+When rounds exceed 5, Gestalt automatically signals that compression is available. Use the `compress` action to summarize earlier rounds and keep the context window lean:
+
+```
+1. respond returns needsCompression: true + compressionContext
+2. ges_interview({ action: "compress", sessionId }) → compressionContext
+3. Caller generates summary → submits it → stored in session
+```
+
+The compressed summary is automatically injected into all subsequent rounds.
+
 ---
 
 ### Step 2 — Spec Generation
 
-When the ambiguity score reaches ≤ 0.2, run:
+**Option A — From text (no interview required):**
+
+```bash
+ges_generate_spec({ text: "Build a checkout flow with Stripe" })
+```
+
+**Option A-2 — With a built-in template:**
+
+Three starter templates pre-fill common constraints and acceptance criteria:
+
+| Template ID | Description |
+|-------------|-------------|
+| `rest-api` | REST API server with auth, CRUD, and OpenAPI |
+| `react-dashboard` | React dashboard with charts, filters, and responsive layout |
+| `cli-tool` | CLI tool with subcommands, config, and distribution |
+
+```bash
+ges_generate_spec({ text: "API with JWT authentication", template: "rest-api" })
+```
+
+**Option B — From a completed interview:**
 
 ```bash
 /spec
@@ -228,6 +283,66 @@ Transforms the Spec into a dependency-aware execution plan and runs it:
 - Jaccard similarity-based measurement
 - Auto-triggers a retrospective when drift exceeds threshold
 
+#### Parallel execution groups
+
+The `plan_complete` response includes `parallelGroups: string[][]`. Tasks with no mutual dependencies land in the same group and can be executed concurrently:
+
+```json
+"parallelGroups": [
+  ["setup-db", "setup-env"],   // run in parallel
+  ["create-schema"],           // after group above
+  ["seed-data", "run-tests"]   // run in parallel
+]
+```
+
+#### Resuming an interrupted execution
+
+Pick up where you left off when a session is interrupted:
+
+```bash
+ges_execute({ action: "resume", sessionId: "<id>" })
+```
+
+Returns `ResumeContext`: completed task IDs, next task, and `progressPercent`. The `ges_status` response also includes `resumeContext` automatically for any executing session.
+
+#### Brownfield audit
+
+When a codebase already exists, audit it against the Spec before executing new tasks:
+
+```bash
+# Step 1: request audit context
+ges_execute({ action: "audit", sessionId: "<id>" })
+→ auditContext (systemPrompt, auditPrompt)
+
+# Step 2: submit codebase snapshot + audit result
+ges_execute({
+  action: "audit",
+  sessionId: "<id>",
+  codebaseSnapshot: "...",
+  auditResult: { implementedACs: [0,2], partialACs: [1], missingACs: [3], gapAnalysis: "..." }
+})
+```
+
+#### Real-time progress panel
+
+When using the `/execute` slash command, Gestalt displays live execution status in the Claude Code Task panel — showing completed/total tasks, current task name, failed task count, and parallel group progress. Updated automatically at each planning step, task completion, and evaluation stage.
+
+#### Sub-agent spawning
+
+Decompose a complex task into sub-tasks dynamically during execution:
+
+```bash
+ges_execute({
+  action: "spawn",
+  sessionId: "<id>",
+  parentTaskId: "task-3",
+  subTasks: [
+    { title: "Write DB schema", description: "..." },
+    { title: "Run migration", description: "...", dependsOn: ["spawned-<id>"] }
+  ]
+})
+```
+
 ---
 
 ### Step 4 — Evaluate
@@ -341,9 +456,9 @@ ges_create_agent  →  action: "submit", sessionId: "<id>", agentContent: "..."
 
 ---
 
-### Alternative: CLI Direct Mode
+### CLI Mode (without Claude Code)
 
-Requires `ANTHROPIC_API_KEY`. Runs Gestalt directly from the terminal without Claude Code:
+Want to run Gestalt without Claude Code? CLI mode runs interviews directly in your terminal. **Requires `ANTHROPIC_API_KEY`.**
 
 ```bash
 # Start an interactive interview
@@ -448,15 +563,19 @@ Claude Code (you)
 │  Interview Engine                │
 │  ├─ GestaltPrincipleSelector     │
 │  ├─ AmbiguityScorer              │
-│  └─ SessionManager               │
+│  ├─ SessionManager               │
+│  └─ ContextCompressor            │
 │                                  │
 │  Spec Generator                  │
-│  └─ PassthroughSpecGenerator     │
+│  ├─ PassthroughSpecGenerator     │
+│  └─ SpecTemplateRegistry         │
 │                                  │
 │  Execute Engine                  │
 │  ├─ DAG Validator                │
+│  ├─ ParallelGroupsCalculator     │
 │  ├─ DriftDetector                │
 │  ├─ EvaluationEngine             │
+│  ├─ AuditEngine                  │
 │  └─ ExecuteSessionManager        │
 │                                  │
 │  Resilience Engine               │

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",

package/dist/role-agents/technical-writer/AGENT.md

@@ -32,8 +32,20 @@ When writing Korean developer documentation, follow these conventions observed i
 **Formatting Patterns**
 - Bold key terms on first use: **소모성 아이템**, **비소모성 아이템**
 - Use bullet lists for features, options, and constraints — keep each item concise
+- Use numbered lists when sequence matters — installation steps, API call order, migration procedures
+  — Don't: bullet a 3-step setup where step 2 depends on step 1
+  — Do: number any list where "do these in order" is part of the instruction
 - Separate distinct concepts with `---` horizontal rules
-- End conceptual sections with a "참고해 주세요" callout for edge cases or policy notes
+- Use callout blocks to signal importance — choose the type based on consequence:
+  - 💡 **Tip**: better approach, shortcut, optional improvement
+  - 📝 **Note / 참고**: extra context, exception cases, policy notes — use at the end of conceptual sections
+  - ⚠️ **Warning / 주의**: incorrect usage causes problems (wrong output, wasted time)
+  - 🔴 **Danger / 경고**: data loss, security risk, service outage — reader must not skip this
+  — Don't use Note for Danger: "참고로 이 명령어는 데이터를 삭제해요" understates the risk
+- Write descriptive link text — destination should be clear from the link text alone
+  — Don't: "자세한 내용은 [여기](...)를 참고하세요."
+  — Do: "자세한 내용은 [설치 가이드](...)를 참고하세요."
+  — Don't: "See [this](url)." → Do: "See [API authentication guide](url)."
 
 **Content Principles**
 - Lead with business value or user benefit, follow with technical detail
@@ -46,6 +58,26 @@ When writing Korean developer documentation, follow these conventions observed i
 - Avoid listing terms inline in introductions if they are covered in a dedicated section below — redundant inline lists interrupt flow without adding value
 
 **Korean Sentence Writing**
+
+**핵심 원칙: 영어로 생각하고 번역하지 말 것**
+한국어로 직접 작성한다. "dependency-based execution planning"을 머릿속에서 먼저 영어로 구성한 뒤 번역하면 번역체가 된다.
+
+- ❌ 의존성 기반 실행 계획 수립 → ✅ 의존성에 따라 실행 순서를 정해요
+- ❌ 스태그네이션 감지 메커니즘이 트리거됩니다 → ✅ 답보 상태를 감지하면 자동으로 분기해요
+- ❌ 스포닝 → ✅ 하위 에이전트 생성
+- ❌ 소급 검토 컨텍스트 → ✅ 회고 컨텍스트
+- ❌ 임의 태스크에 적용 가능합니다 → ✅ 모든 태스크에 적용할 수 있어요
+- ❌ 단락(short-circuit) 처리 → ✅ 조기 종료 처리
+- ❌ 수익 체감 패턴 → ✅ 효과 감소 패턴
+
+**기술 용어 3단계 처리**
+
+| 단계 | 사용 기준 | 예시 |
+|------|-----------|------|
+| 영어 그대로 | 한국 개발자들이 영어로 통용하는 용어 | API, CLI, JSON, Git, PR, LLM, DAG |
+| 한국어 + 영어 병기 (첫 등장) | 덜 일반적인 전문 용어의 첫 사용 | 이벤트 소싱(Event Sourcing), 단락 회로 실행(Short-circuit Evaluation) |
+| 한국어만 | 자연스러운 한국어 표현이 있는 경우 | 버전 관리 (버저닝 ❌), 배포 (디플로이먼트 ❌) |
+
 - Reader is the subject: write so the developer is the actor — use active constructions
   — Don't: "설정이 완료되어야 합니다." → Do: "설정을 완료하세요."
   — Don't: "이 라이브러리는 초기화를 수행해요." → Do: "이 명령어로 초기화하세요."
@@ -206,7 +238,11 @@ When writing documentation, produce:
 - Callout blocks for important notes, warnings, or tips
 
 When reviewing existing documentation, provide:
-- Specific issues by section (clarity / structure / completeness / consistency)
-- Rewrite suggestions for unclear passages
+- Issues classified by severity:
+  - **Blocker**: reader can misunderstand, follow wrong steps, or miss a critical risk — must fix before publish
+  - **Fix**: clarity, consistency, or structural problem — fix when possible
+  - **Suggest**: improvement idea — optional, at author's discretion
+- Specific location (section name or quoted passage) for each issue
+- Rewrite suggestions for all Blocker and Fix items
 - Missing content checklist
 - Overall readability assessment