@tienne/gestalt 0.8.0 → 0.9.1

package/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

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

@@ -1,6 +1,6 @@
 ---
 name: execute
-version: "1.1.0"
+version: "1.2.0"
 description: "Gestalt-driven execution planner that transforms a Spec into a validated ExecutionPlan"
 triggers:
   - "execute"
@@ -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`를 참조해 태스크를 수행한 후 결과 제출.
@@ -350,3 +411,89 @@ role_match/role_consensus로 얻은 `roleGuidance`를 참조해 태스크를 수
 | `hard_cap` | structural 3회 + contextual 3회 실패 |
 | `caller` | `{ action: "evolve", terminateReason: "caller" }` |
 | `human_escalation` | 4개 lateral persona 소진 |
+
+---
+
+## 공통 진행 패널
+
+Execute 파이프라인 실행 중 Claude Code Task 패널에 실시간 상태를 표시한다. 패널 업데이트는 best-effort — 실패가 태스크 실행 흐름을 중단시켜서는 안 된다.
+
+### Planning 단계 시작 시 (`start` 응답 수신 후)
+
+`TaskCreate`로 실행 패널을 생성하고, 반환된 taskId를 세션 동안 보관한다.
+
+```
+subject: "Gestalt Execute: {spec.goal 앞 40자}"
+description: "Planning 중 | 단계 1/4 | figure_ground"
+activeForm: "실행 계획 수립 중"
+```
+
+### Planning 각 단계 후 (`plan_step` 응답 수신 시마다)
+
+`TaskUpdate`로 현재 Planning 단계를 업데이트한다.
+
+```
+description: "Planning 중 | 단계 {stepsCompleted}/4 | {currentPrinciple}"
+```
+
+### Execution 시작 후 (`execute_start` 응답 수신 후)
+
+Planning 패널 태스크를 완료하고, 새 Execution 패널 태스크를 생성한다.
+
+```
+subject: "Gestalt Execute: {spec.goal 앞 40자}"
+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`로 진행 상황과 현재 실행 태스크명을 업데이트한다.
+
+순차 실행 중:
+```
+description: "{completedCount}/{totalTasks} 완료 | 실패: {failedCount}개 | 그룹 {groupIndex}/{totalGroups}"
+activeForm: "실행 중: {taskContext.currentTask.title}"
+```
+
+병렬 그룹 실행 중 (각 Agent의 execute_task 완료 시):
+```
+description: "{completedCount}/{totalTasks} 완료 | 실패: {failedCount}개 | 그룹 {groupIndex}/{totalGroups}"
+activeForm: "병렬 실행 중: 그룹 {groupIndex}/{totalGroups} — {agentCount}개 Agent 실행 중"
+```
+
+- `completedCount`: 지금까지 제출한 taskResult 수 (`response.completedTasks`)
+- `failedCount`: status가 `failed`인 taskResult 수
+- `groupIndex/totalGroups`: 현재 처리 중인 병렬 그룹 번호 / 전체 그룹 수
+- `agentCount`: 해당 그룹에서 아직 실행 중인 Agent 수
+
+`allTasksCompleted === true` 이면 `TaskUpdate({ status: "completed", activeForm: undefined, description: "전체 완료 ({totalTasks}개)" })`로 변경한다.
+
+### 평가/진화 단계
+
+- `evaluate` 시작: description에 "평가 중 — structural 검사" 추가
+- structural 통과: "평가 중 — contextual 검사" 로 업데이트
+- 평가 완료(success): `TaskUpdate({ status: "completed", description: "완료 | score: {overallScore} | alignment: {goalAlignment}" })`
+- Evolve 진입: description에 "개선 중 (generation {N})" 추가
+
+### 오류/에스컬레이션 시
+
+```
+status: "completed"
+description: "종료: {terminationReason} | 최고 점수: {bestScore}"
+```

package/skills/interview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: interview
-version: "1.0.0"
+version: "1.1.0"
 description: "Gestalt-driven interview to clarify project requirements"
 triggers:
   - "interview"
@@ -80,3 +80,39 @@ API 키 없이 MCP 서버 실행 시 자동 활성화. LLM 작업을 caller가
 | `questionPrompt` | string | 다음 질문 생성용 프롬프트 |
 | `scoringPrompt` | string? | 모호성 점수 산출용 프롬프트 (respond 후에만 포함) |
 | `roundNumber` | number | 현재 라운드 번호 |
+
+---
+
+## 공통 진행 패널
+
+인터뷰 진행 중 Claude Code Task 패널에 실시간 상태를 표시한다. 패널 업데이트는 best-effort — 업데이트 실패가 인터뷰 흐름을 중단시켜서는 안 된다.
+
+### 시작 시 (`start` 응답 수신 직후)
+
+`TaskCreate`를 호출해 진행 패널을 생성하고, 반환된 taskId를 세션 동안 보관한다.
+
+```
+subject: "Gestalt 인터뷰: {topic}"
+description: "라운드 1/{maxRounds} | 모호성: 측정 전"
+activeForm: "라운드 1 — {currentPrinciple}"
+```
+
+### 각 라운드 후 (`respond` 응답 수신 시마다)
+
+`TaskUpdate`로 description과 activeForm을 최신 상태로 갱신한다. 모호성 점수는 추이 형식으로 표시한다.
+
+```
+description: "라운드 {roundNumber}/{maxRounds} | 모호성: {score1} → {score2} → {latestScore}"
+activeForm: "라운드 {roundNumber} — {currentPrinciple}"
+```
+
+ambiguityScore.isReady === true 이면 description에 "✓ 준비 완료" 표시를 추가한다.
+
+### 완료 시 (`complete` 응답 수신 후)
+
+`TaskUpdate`로 status를 completed로 변경한다.
+
+```
+status: "completed"
+description: "총 {totalRounds}라운드 완료 | 최종 모호성: {finalAmbiguityScore}"
+```

package/skills/spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec
-version: "1.0.0"
+version: "1.1.0"
 description: "Generate a Spec specification from a completed interview"
 triggers:
   - "generate spec"
@@ -90,3 +90,41 @@ ges_generate_spec({
 - `gestaltAnalysis[].confidence`: 0.0 ~ 1.0
 - `ontologySchema.entities[]`: `{ name: string(min 1), description: string, attributes: string[] }`
 - `ontologySchema.relations[]`: `{ from: string(min 1), to: string(min 1), type: string(min 1) }`
+
+---
+
+## 공통 진행 패널
+
+Spec 생성 중 Claude Code Task 패널에 상태를 표시한다. best-effort — 패널 실패가 Spec 생성을 막아서는 안 된다.
+
+### 시작 시 (1단계 `ges_generate_spec` 호출 전)
+
+`TaskCreate`로 패널을 생성한다.
+
+```
+subject: "Spec 생성 중"
+description: "인터뷰 세션 {sessionId} 기반 Spec 구성 중..."
+activeForm: "1/2 — 컨텍스트 요청 중"
+```
+
+1단계 응답(`status: "prompt"`) 수신 후 `TaskUpdate`로 갱신한다.
+
+```
+activeForm: "2/2 — Spec 검증 중"
+```
+
+### 완료 시 (2단계 `ges_generate_spec` 응답 수신 후)
+
+`TaskUpdate`로 status를 completed로 변경한다.
+
+```
+status: "completed"
+description: "Spec 생성 완료 | specId: {spec.metadata.specId}"
+```
+
+실패 시(error 반환):
+
+```
+status: "completed"
+description: "Spec 생성 실패: {error}"
+```