@tienne/gestalt 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/CLAUDE.md +203 -0
  2. package/README.md +60 -0
  3. package/agents/closure-completer/AGENT.md +32 -0
  4. package/agents/continuity-judge/AGENT.md +40 -0
  5. package/agents/ground-mapper/AGENT.md +31 -0
  6. package/agents/proximity-worker/AGENT.md +33 -0
  7. package/agents/similarity-crystallizer/AGENT.md +34 -0
  8. package/dist/agents/closure-completer/AGENT.md +32 -0
  9. package/dist/agents/continuity-judge/AGENT.md +40 -0
  10. package/dist/agents/ground-mapper/AGENT.md +31 -0
  11. package/dist/agents/proximity-worker/AGENT.md +33 -0
  12. package/dist/agents/similarity-crystallizer/AGENT.md +34 -0
  13. package/dist/bin/gestalt.d.ts +3 -0
  14. package/dist/bin/gestalt.d.ts.map +1 -0
  15. package/dist/bin/gestalt.js +5 -0
  16. package/dist/bin/gestalt.js.map +1 -0
  17. package/dist/skills/execute/SKILL.md +84 -0
  18. package/dist/skills/interview/SKILL.md +82 -0
  19. package/dist/skills/seed/SKILL.md +92 -0
  20. package/dist/skills/spec/SKILL.md +92 -0
  21. package/dist/src/agent/figural-router.d.ts +48 -0
  22. package/dist/src/agent/figural-router.d.ts.map +1 -0
  23. package/dist/src/agent/figural-router.js +55 -0
  24. package/dist/src/agent/figural-router.js.map +1 -0
  25. package/dist/src/agent/parser.d.ts +3 -0
  26. package/dist/src/agent/parser.d.ts.map +1 -0
  27. package/dist/src/agent/parser.js +32 -0
  28. package/dist/src/agent/parser.js.map +1 -0
  29. package/dist/src/agent/prompt-resolver.d.ts +17 -0
  30. package/dist/src/agent/prompt-resolver.d.ts.map +1 -0
  31. package/dist/src/agent/prompt-resolver.js +31 -0
  32. package/dist/src/agent/prompt-resolver.js.map +1 -0
  33. package/dist/src/agent/registry.d.ts +9 -0
  34. package/dist/src/agent/registry.d.ts.map +1 -0
  35. package/dist/src/agent/registry.js +22 -0
  36. package/dist/src/agent/registry.js.map +1 -0
  37. package/dist/src/cli/commands/interview.d.ts +2 -0
  38. package/dist/src/cli/commands/interview.d.ts.map +1 -0
  39. package/dist/src/cli/commands/interview.js +67 -0
  40. package/dist/src/cli/commands/interview.js.map +1 -0
  41. package/dist/src/cli/commands/seed.d.ts +4 -0
  42. package/dist/src/cli/commands/seed.d.ts.map +1 -0
  43. package/dist/src/cli/commands/seed.js +34 -0
  44. package/dist/src/cli/commands/seed.js.map +1 -0
  45. package/dist/src/cli/commands/serve.d.ts +2 -0
  46. package/dist/src/cli/commands/serve.d.ts.map +1 -0
  47. package/dist/src/cli/commands/serve.js +5 -0
  48. package/dist/src/cli/commands/serve.js.map +1 -0
  49. package/dist/src/cli/commands/spec.d.ts +4 -0
  50. package/dist/src/cli/commands/spec.d.ts.map +1 -0
  51. package/dist/src/cli/commands/spec.js +34 -0
  52. package/dist/src/cli/commands/spec.js.map +1 -0
  53. package/dist/src/cli/commands/status.d.ts +2 -0
  54. package/dist/src/cli/commands/status.d.ts.map +1 -0
  55. package/dist/src/cli/commands/status.js +66 -0
  56. package/dist/src/cli/commands/status.js.map +1 -0
  57. package/dist/src/cli/index.d.ts +3 -0
  58. package/dist/src/cli/index.d.ts.map +1 -0
  59. package/dist/src/cli/index.js +39 -0
  60. package/dist/src/cli/index.js.map +1 -0
  61. package/dist/src/core/config.d.ts +36 -0
  62. package/dist/src/core/config.d.ts.map +1 -0
  63. package/dist/src/core/config.js +65 -0
  64. package/dist/src/core/config.js.map +1 -0
  65. package/dist/src/core/constants.d.ts +34 -0
  66. package/dist/src/core/constants.d.ts.map +1 -0
  67. package/dist/src/core/constants.js +68 -0
  68. package/dist/src/core/constants.js.map +1 -0
  69. package/dist/src/core/errors.d.ts +50 -0
  70. package/dist/src/core/errors.d.ts.map +1 -0
  71. package/dist/src/core/errors.js +99 -0
  72. package/dist/src/core/errors.js.map +1 -0
  73. package/dist/src/core/log.d.ts +5 -0
  74. package/dist/src/core/log.d.ts.map +1 -0
  75. package/dist/src/core/log.js +7 -0
  76. package/dist/src/core/log.js.map +1 -0
  77. package/dist/src/core/result.d.ts +20 -0
  78. package/dist/src/core/result.d.ts.map +1 -0
  79. package/dist/src/core/result.js +43 -0
  80. package/dist/src/core/result.js.map +1 -0
  81. package/dist/src/core/types.d.ts +289 -0
  82. package/dist/src/core/types.d.ts.map +1 -0
  83. package/dist/src/core/types.js +15 -0
  84. package/dist/src/core/types.js.map +1 -0
  85. package/dist/src/events/store.d.ts +22 -0
  86. package/dist/src/events/store.d.ts.map +1 -0
  87. package/dist/src/events/store.js +130 -0
  88. package/dist/src/events/store.js.map +1 -0
  89. package/dist/src/events/types.d.ts +33 -0
  90. package/dist/src/events/types.d.ts.map +1 -0
  91. package/dist/src/events/types.js +35 -0
  92. package/dist/src/events/types.js.map +1 -0
  93. package/dist/src/execute/dag-validator.d.ts +7 -0
  94. package/dist/src/execute/dag-validator.d.ts.map +1 -0
  95. package/dist/src/execute/dag-validator.js +141 -0
  96. package/dist/src/execute/dag-validator.js.map +1 -0
  97. package/dist/src/execute/drift-detector.d.ts +11 -0
  98. package/dist/src/execute/drift-detector.d.ts.map +1 -0
  99. package/dist/src/execute/drift-detector.js +111 -0
  100. package/dist/src/execute/drift-detector.js.map +1 -0
  101. package/dist/src/execute/impact-identifier.d.ts +12 -0
  102. package/dist/src/execute/impact-identifier.d.ts.map +1 -0
  103. package/dist/src/execute/impact-identifier.js +60 -0
  104. package/dist/src/execute/impact-identifier.js.map +1 -0
  105. package/dist/src/execute/passthrough-engine.d.ts +181 -0
  106. package/dist/src/execute/passthrough-engine.d.ts.map +1 -0
  107. package/dist/src/execute/passthrough-engine.js +795 -0
  108. package/dist/src/execute/passthrough-engine.js.map +1 -0
  109. package/dist/src/execute/prompts.d.ts +19 -0
  110. package/dist/src/execute/prompts.d.ts.map +1 -0
  111. package/dist/src/execute/prompts.js +505 -0
  112. package/dist/src/execute/prompts.js.map +1 -0
  113. package/dist/src/execute/repository.d.ts +30 -0
  114. package/dist/src/execute/repository.d.ts.map +1 -0
  115. package/dist/src/execute/repository.js +248 -0
  116. package/dist/src/execute/repository.js.map +1 -0
  117. package/dist/src/execute/session.d.ts +34 -0
  118. package/dist/src/execute/session.d.ts.map +1 -0
  119. package/dist/src/execute/session.js +273 -0
  120. package/dist/src/execute/session.js.map +1 -0
  121. package/dist/src/execute/spec-patch-applier.d.ts +13 -0
  122. package/dist/src/execute/spec-patch-applier.d.ts.map +1 -0
  123. package/dist/src/execute/spec-patch-applier.js +83 -0
  124. package/dist/src/execute/spec-patch-applier.js.map +1 -0
  125. package/dist/src/execute/spec-patch-validator.d.ts +20 -0
  126. package/dist/src/execute/spec-patch-validator.d.ts.map +1 -0
  127. package/dist/src/execute/spec-patch-validator.js +60 -0
  128. package/dist/src/execute/spec-patch-validator.js.map +1 -0
  129. package/dist/src/execute/termination-detector.d.ts +20 -0
  130. package/dist/src/execute/termination-detector.d.ts.map +1 -0
  131. package/dist/src/execute/termination-detector.js +77 -0
  132. package/dist/src/execute/termination-detector.js.map +1 -0
  133. package/dist/src/gestalt/analyzer.d.ts +18 -0
  134. package/dist/src/gestalt/analyzer.d.ts.map +1 -0
  135. package/dist/src/gestalt/analyzer.js +59 -0
  136. package/dist/src/gestalt/analyzer.js.map +1 -0
  137. package/dist/src/gestalt/principles.d.ts +21 -0
  138. package/dist/src/gestalt/principles.d.ts.map +1 -0
  139. package/dist/src/gestalt/principles.js +66 -0
  140. package/dist/src/gestalt/principles.js.map +1 -0
  141. package/dist/src/index.d.ts +22 -0
  142. package/dist/src/index.d.ts.map +1 -0
  143. package/dist/src/index.js +22 -0
  144. package/dist/src/index.js.map +1 -0
  145. package/dist/src/interview/ambiguity.d.ts +8 -0
  146. package/dist/src/interview/ambiguity.d.ts.map +1 -0
  147. package/dist/src/interview/ambiguity.js +69 -0
  148. package/dist/src/interview/ambiguity.js.map +1 -0
  149. package/dist/src/interview/brownfield.d.ts +7 -0
  150. package/dist/src/interview/brownfield.d.ts.map +1 -0
  151. package/dist/src/interview/brownfield.js +28 -0
  152. package/dist/src/interview/brownfield.js.map +1 -0
  153. package/dist/src/interview/engine.d.ts +31 -0
  154. package/dist/src/interview/engine.d.ts.map +1 -0
  155. package/dist/src/interview/engine.js +110 -0
  156. package/dist/src/interview/engine.js.map +1 -0
  157. package/dist/src/interview/passthrough-engine.d.ts +52 -0
  158. package/dist/src/interview/passthrough-engine.d.ts.map +1 -0
  159. package/dist/src/interview/passthrough-engine.js +174 -0
  160. package/dist/src/interview/passthrough-engine.js.map +1 -0
  161. package/dist/src/interview/questions.d.ts +12 -0
  162. package/dist/src/interview/questions.d.ts.map +1 -0
  163. package/dist/src/interview/questions.js +54 -0
  164. package/dist/src/interview/questions.js.map +1 -0
  165. package/dist/src/interview/repository.d.ts +25 -0
  166. package/dist/src/interview/repository.d.ts.map +1 -0
  167. package/dist/src/interview/repository.js +102 -0
  168. package/dist/src/interview/repository.js.map +1 -0
  169. package/dist/src/interview/session.d.ts +22 -0
  170. package/dist/src/interview/session.d.ts.map +1 -0
  171. package/dist/src/interview/session.js +120 -0
  172. package/dist/src/interview/session.js.map +1 -0
  173. package/dist/src/llm/adapter.d.ts +8 -0
  174. package/dist/src/llm/adapter.d.ts.map +1 -0
  175. package/dist/src/llm/adapter.js +42 -0
  176. package/dist/src/llm/adapter.js.map +1 -0
  177. package/dist/src/llm/openai-adapter.d.ts +8 -0
  178. package/dist/src/llm/openai-adapter.d.ts.map +1 -0
  179. package/dist/src/llm/openai-adapter.js +45 -0
  180. package/dist/src/llm/openai-adapter.js.map +1 -0
  181. package/dist/src/llm/prompts.d.ts +15 -0
  182. package/dist/src/llm/prompts.d.ts.map +1 -0
  183. package/dist/src/llm/prompts.js +83 -0
  184. package/dist/src/llm/prompts.js.map +1 -0
  185. package/dist/src/llm/types.d.ts +21 -0
  186. package/dist/src/llm/types.d.ts.map +1 -0
  187. package/dist/src/llm/types.js +2 -0
  188. package/dist/src/llm/types.js.map +1 -0
  189. package/dist/src/mcp/schemas.d.ts +799 -0
  190. package/dist/src/mcp/schemas.d.ts.map +1 -0
  191. package/dist/src/mcp/schemas.js +151 -0
  192. package/dist/src/mcp/schemas.js.map +1 -0
  193. package/dist/src/mcp/server.d.ts +13 -0
  194. package/dist/src/mcp/server.d.ts.map +1 -0
  195. package/dist/src/mcp/server.js +255 -0
  196. package/dist/src/mcp/server.js.map +1 -0
  197. package/dist/src/mcp/tools/execute-passthrough.d.ts +4 -0
  198. package/dist/src/mcp/tools/execute-passthrough.d.ts.map +1 -0
  199. package/dist/src/mcp/tools/execute-passthrough.js +349 -0
  200. package/dist/src/mcp/tools/execute-passthrough.js.map +1 -0
  201. package/dist/src/mcp/tools/index.d.ts +4 -0
  202. package/dist/src/mcp/tools/index.d.ts.map +1 -0
  203. package/dist/src/mcp/tools/index.js +4 -0
  204. package/dist/src/mcp/tools/index.js.map +1 -0
  205. package/dist/src/mcp/tools/interview-passthrough.d.ts +4 -0
  206. package/dist/src/mcp/tools/interview-passthrough.d.ts.map +1 -0
  207. package/dist/src/mcp/tools/interview-passthrough.js +96 -0
  208. package/dist/src/mcp/tools/interview-passthrough.js.map +1 -0
  209. package/dist/src/mcp/tools/interview.d.ts +4 -0
  210. package/dist/src/mcp/tools/interview.d.ts.map +1 -0
  211. package/dist/src/mcp/tools/interview.js +85 -0
  212. package/dist/src/mcp/tools/interview.js.map +1 -0
  213. package/dist/src/mcp/tools/seed-passthrough.d.ts +5 -0
  214. package/dist/src/mcp/tools/seed-passthrough.d.ts.map +1 -0
  215. package/dist/src/mcp/tools/seed-passthrough.js +29 -0
  216. package/dist/src/mcp/tools/seed-passthrough.js.map +1 -0
  217. package/dist/src/mcp/tools/seed.d.ts +5 -0
  218. package/dist/src/mcp/tools/seed.d.ts.map +1 -0
  219. package/dist/src/mcp/tools/seed.js +19 -0
  220. package/dist/src/mcp/tools/seed.js.map +1 -0
  221. package/dist/src/mcp/tools/spec-passthrough.d.ts +5 -0
  222. package/dist/src/mcp/tools/spec-passthrough.d.ts.map +1 -0
  223. package/dist/src/mcp/tools/spec-passthrough.js +29 -0
  224. package/dist/src/mcp/tools/spec-passthrough.js.map +1 -0
  225. package/dist/src/mcp/tools/spec.d.ts +5 -0
  226. package/dist/src/mcp/tools/spec.d.ts.map +1 -0
  227. package/dist/src/mcp/tools/spec.js +19 -0
  228. package/dist/src/mcp/tools/spec.js.map +1 -0
  229. package/dist/src/mcp/tools/status.d.ts +4 -0
  230. package/dist/src/mcp/tools/status.d.ts.map +1 -0
  231. package/dist/src/mcp/tools/status.js +45 -0
  232. package/dist/src/mcp/tools/status.js.map +1 -0
  233. package/dist/src/registry/base-registry.d.ts +26 -0
  234. package/dist/src/registry/base-registry.d.ts.map +1 -0
  235. package/dist/src/registry/base-registry.js +82 -0
  236. package/dist/src/registry/base-registry.js.map +1 -0
  237. package/dist/src/seed/extractor.d.ts +15 -0
  238. package/dist/src/seed/extractor.d.ts.map +1 -0
  239. package/dist/src/seed/extractor.js +88 -0
  240. package/dist/src/seed/extractor.js.map +1 -0
  241. package/dist/src/seed/generator.d.ts +12 -0
  242. package/dist/src/seed/generator.d.ts.map +1 -0
  243. package/dist/src/seed/generator.js +66 -0
  244. package/dist/src/seed/generator.js.map +1 -0
  245. package/dist/src/seed/passthrough-generator.d.ts +31 -0
  246. package/dist/src/seed/passthrough-generator.d.ts.map +1 -0
  247. package/dist/src/seed/passthrough-generator.js +80 -0
  248. package/dist/src/seed/passthrough-generator.js.map +1 -0
  249. package/dist/src/seed/schema.d.ts +145 -0
  250. package/dist/src/seed/schema.d.ts.map +1 -0
  251. package/dist/src/seed/schema.js +37 -0
  252. package/dist/src/seed/schema.js.map +1 -0
  253. package/dist/src/skills/executor.d.ts +14 -0
  254. package/dist/src/skills/executor.d.ts.map +1 -0
  255. package/dist/src/skills/executor.js +17 -0
  256. package/dist/src/skills/executor.js.map +1 -0
  257. package/dist/src/skills/parser.d.ts +3 -0
  258. package/dist/src/skills/parser.d.ts.map +1 -0
  259. package/dist/src/skills/parser.js +37 -0
  260. package/dist/src/skills/parser.js.map +1 -0
  261. package/dist/src/skills/registry.d.ts +8 -0
  262. package/dist/src/skills/registry.d.ts.map +1 -0
  263. package/dist/src/skills/registry.js +19 -0
  264. package/dist/src/skills/registry.js.map +1 -0
  265. package/dist/src/skills/types.d.ts +19 -0
  266. package/dist/src/skills/types.d.ts.map +1 -0
  267. package/dist/src/skills/types.js +2 -0
  268. package/dist/src/skills/types.js.map +1 -0
  269. package/dist/src/spec/extractor.d.ts +15 -0
  270. package/dist/src/spec/extractor.d.ts.map +1 -0
  271. package/dist/src/spec/extractor.js +88 -0
  272. package/dist/src/spec/extractor.js.map +1 -0
  273. package/dist/src/spec/generator.d.ts +12 -0
  274. package/dist/src/spec/generator.d.ts.map +1 -0
  275. package/dist/src/spec/generator.js +66 -0
  276. package/dist/src/spec/generator.js.map +1 -0
  277. package/dist/src/spec/passthrough-generator.d.ts +34 -0
  278. package/dist/src/spec/passthrough-generator.d.ts.map +1 -0
  279. package/dist/src/spec/passthrough-generator.js +86 -0
  280. package/dist/src/spec/passthrough-generator.js.map +1 -0
  281. package/dist/src/spec/schema.d.ts +145 -0
  282. package/dist/src/spec/schema.d.ts.map +1 -0
  283. package/dist/src/spec/schema.js +37 -0
  284. package/dist/src/spec/schema.js.map +1 -0
  285. package/package.json +53 -0
  286. package/skills/execute/SKILL.md +84 -0
  287. package/skills/interview/SKILL.md +82 -0
  288. package/skills/spec/SKILL.md +92 -0
package/CLAUDE.md ADDED
@@ -0,0 +1,203 @@
1
+ # Gestalt — AI Development Harness
2
+
3
+ ## Overview
4
+ 게슈탈트 심리학 원리를 요구사항 명확화 프로세스에 매핑한 TypeScript 기반 AI 개발 하네스.
5
+ "전체는 부분의 합보다 크다" — 흩어진 요구사항 조각들을 모아 완전한 스펙(Spec)으로 결정화.
6
+
7
+ ## Architecture
8
+ - **Interview Engine**: 게슈탈트 원리 기반 Q&A로 모호성 점수를 0.2 이하로 낮춤
9
+ - **Spec Generator**: 완료된 인터뷰에서 구조화된 프로젝트 스펙(Spec) 생성
10
+ - **Execute Engine**: 게슈탈트 5원리를 실행 전략으로 사용, Spec→ExecutionPlan 변환 (Figure-Ground→Closure→Proximity→Continuity)
11
+ - **MCP Server**: stdio transport로 Claude Code 등 AI 에이전트와 통합
12
+ - **Skill System**: SKILL.md 기반 확장, chokidar hot-reload 지원
13
+ - **Event Store**: better-sqlite3 WAL 모드 이벤트 소싱
14
+
15
+ ## Tech Stack
16
+ TypeScript 5.x / ESM / pnpm / vitest
17
+ Dependencies: @anthropic-ai/sdk, @modelcontextprotocol/sdk, better-sqlite3, zod, chokidar, commander, gray-matter
18
+
19
+ ## Key Commands
20
+ ```bash
21
+ pnpm test # Run all tests (vitest)
22
+ pnpm run serve # Start MCP server
23
+ pnpm tsx bin/gestalt.ts interview "topic" # Interactive interview
24
+ pnpm tsx bin/gestalt.ts spec <session-id> # Generate spec
25
+ pnpm tsx bin/gestalt.ts status # Check sessions
26
+ ```
27
+
28
+ ## MCP Tools
29
+ - `ges_interview`: action=[start|respond|score|complete]
30
+ - `ges_generate_spec`: sessionId, force?
31
+ - `ges_execute`: action=[start|plan_step|plan_complete|execute_start|execute_task|evaluate|status|evolve_fix|evolve|evolve_patch|evolve_re_execute]
32
+ - `ges_status`: sessionId?
33
+
34
+ ## MCP Passthrough Mode
35
+
36
+ API 키(`ANTHROPIC_API_KEY`) 없이 MCP 서버 실행 시 자동 활성화. LLM 호출을 서버가 하지 않고, caller(Claude Code 등)에게 위임한다.
37
+
38
+ ### 설정 (claude_desktop_config.json / settings.json)
39
+ ```json
40
+ {
41
+ "mcpServers": {
42
+ "gestalt": {
43
+ "command": "npx",
44
+ "args": ["tsx", "bin/gestalt.ts", "serve"]
45
+ }
46
+ }
47
+ }
48
+ ```
49
+ > `env`에 `ANTHROPIC_API_KEY`를 넣지 않으면 passthrough 모드로 동작.
50
+
51
+ ### Interview → Spec 전체 플로우
52
+
53
+ **Step 1: 인터뷰 시작**
54
+ ```
55
+ ges_interview({ action: "start", topic: "사용자 인증 시스템" })
56
+ ```
57
+ → `gestaltContext` 반환 (systemPrompt, questionPrompt, currentPrinciple, phase 등)
58
+
59
+ **Step 2: 질문 생성 (caller 수행)**
60
+ `gestaltContext.systemPrompt` + `gestaltContext.questionPrompt`를 사용해 질문을 생성한다.
61
+
62
+ **Step 3: 사용자 응답 수집 후 전달**
63
+ ```
64
+ ges_interview({
65
+ action: "respond",
66
+ sessionId: "<sessionId>",
67
+ response: "사용자 답변",
68
+ generatedQuestion: "caller가 생성한 질문",
69
+ ambiguityScore: { // 선택사항
70
+ goalClarity: 0.7,
71
+ constraintClarity: 0.5,
72
+ successCriteria: 0.4,
73
+ priorityClarity: 0.6
74
+ }
75
+ })
76
+ ```
77
+ → 다음 `gestaltContext` + `ambiguityScore` 반환. `ambiguityScore.isReady === true`가 될 때까지 반복.
78
+
79
+ **Step 4: 스코어링 (선택)**
80
+ respond 시 ambiguityScore를 안 보냈다면 별도로 요청 가능:
81
+ ```
82
+ ges_interview({ action: "score", sessionId: "<id>" })
83
+ → scoringPrompt 반환 → caller가 점수 산출 →
84
+ ges_interview({ action: "score", sessionId: "<id>", ambiguityScore: {...} })
85
+ ```
86
+
87
+ **Step 5: 인터뷰 완료**
88
+ ```
89
+ ges_interview({ action: "complete", sessionId: "<id>" })
90
+ ```
91
+
92
+ **Step 6: Spec 생성 (2단계)**
93
+ ```
94
+ // 6a: specContext 요청
95
+ ges_generate_spec({ sessionId: "<id>" })
96
+ → specContext (systemPrompt, specPrompt, allRounds) 반환
97
+
98
+ // 6b: caller가 spec JSON 생성 후 제출
99
+ ges_generate_spec({
100
+ sessionId: "<id>",
101
+ spec: {
102
+ goal: "...",
103
+ constraints: ["..."],
104
+ acceptanceCriteria: ["..."],
105
+ ontologySchema: { entities: [...], relations: [...] },
106
+ gestaltAnalysis: [{ principle: "closure", finding: "...", confidence: 0.9 }]
107
+ }
108
+ })
109
+ → Zod 검증 후 최종 Spec 반환
110
+ ```
111
+
112
+ ### Spec → Execute 플로우
113
+
114
+ **Step 1: 실행 계획 세션 시작**
115
+ ```
116
+ ges_execute({ action: "start", spec: { ...completeSpecObject } })
117
+ ```
118
+ → `executeContext` 반환 (systemPrompt, planningPrompt, currentPrinciple 등)
119
+
120
+ **Step 2~5: 4단계 계획 수립 (caller가 각 단계 결과를 생성)**
121
+ ```
122
+ // Figure-Ground → Closure → Proximity → Continuity 순서로 진행
123
+ ges_execute({
124
+ action: "plan_step",
125
+ sessionId: "<id>",
126
+ stepResult: { principle: "figure_ground", classifiedACs: [...] }
127
+ })
128
+ → 다음 단계 executeContext 반환. isLastStep === true가 될 때까지 반복.
129
+ ```
130
+
131
+ **Step 6: 실행 계획 조립**
132
+ ```
133
+ ges_execute({ action: "plan_complete", sessionId: "<id>" })
134
+ → ExecutionPlan (classifiedACs, atomicTasks, taskGroups, dagValidation) 반환
135
+ ```
136
+
137
+ ### Execute → Evaluate → Evolution 플로우
138
+
139
+ **Execution Phase**: execute_start → execute_task (반복) → evaluate (3-Call: structural → contextual)
140
+
141
+ **Evolution Loop** (Evaluate 점수가 threshold 미달 시):
142
+
143
+ **Flow A: Structural Fix** (structural 실패 시)
144
+ ```
145
+ // 1. Fix context 요청
146
+ ges_execute({ action: "evolve_fix", sessionId: "<id>" })
147
+ → fixContext 반환
148
+
149
+ // 2. Fix tasks 제출
150
+ ges_execute({ action: "evolve_fix", sessionId: "<id>", fixTasks: [...] })
151
+ → 상태 복원, evaluate 재실행 가능
152
+
153
+ // 3. Re-evaluate
154
+ ges_execute({ action: "evaluate", sessionId: "<id>" })
155
+ ```
156
+
157
+ **Flow B: Contextual Evolution** (structural 통과, contextual 점수 미달 시)
158
+ ```
159
+ // 1. Evolution context 요청
160
+ ges_execute({ action: "evolve", sessionId: "<id>" })
161
+ → evolveContext 반환 (또는 terminateReason으로 종료)
162
+
163
+ // 2. Spec patch 제출
164
+ ges_execute({ action: "evolve_patch", sessionId: "<id>", specPatch: {...} })
165
+ → impactedTaskIds + reExecuteContext 반환
166
+
167
+ // 3. Impacted tasks 재실행 (반복)
168
+ ges_execute({ action: "evolve_re_execute", sessionId: "<id>", reExecuteTaskResult: {...} })
169
+ → allTasksCompleted === true가 될 때까지 반복
170
+
171
+ // 4. Re-evaluate
172
+ ges_execute({ action: "evaluate", sessionId: "<id>" })
173
+ ```
174
+
175
+ **Spec Patch 범위**: L1(AC)+L2(constraints) 자유, L3(ontology) 추가/변경만, L4(goal) 금지
176
+ **종료 조건**: success(≥0.85, ≥0.80), stagnation, oscillation, hard_cap(3+3), caller
177
+ **Caller 종료**: `ges_execute({ action: "evolve", sessionId: "<id>", terminateReason: "caller" })`
178
+
179
+ ### 핵심 규칙
180
+ - `action: "respond"` 시 `generatedQuestion` **필수**, `ambiguityScore` 선택
181
+ - ambiguityScore 차원: `goalClarity`, `constraintClarity`, `successCriteria`, `priorityClarity` (필수), `contextClarity` (선택)
182
+ - Spec의 `gestaltAnalysis[].principle`은 enum: `closure | proximity | similarity | figure_ground | continuity`
183
+ - `ontologySchema.entities[]`: `{ name, description, attributes[] }`
184
+ - `ontologySchema.relations[]`: `{ from, to, type }`
185
+
186
+ ## Project Structure
187
+ - `src/core/` — types, errors, Result monad, config, constants
188
+ - `src/gestalt/` — 게슈탈트 원리 엔진 (핵심 차별점)
189
+ - `src/interview/` — InterviewEngine, AmbiguityScorer, SessionManager
190
+ - `src/spec/` — SpecGenerator, SpecExtractor
191
+ - `src/execute/` — ExecuteEngine, DAG Validator, ExecuteSessionManager
192
+ - `src/skills/` — SkillRegistry, parser
193
+ - `src/mcp/` — MCP 서버 + 툴 핸들러
194
+ - `src/events/` — EventStore (SQLite)
195
+ - `src/llm/` — Anthropic SDK adapter
196
+ - `src/cli/` — commander 기반 CLI
197
+
198
+ ## Conventions
199
+ - MCP 서버에서 `console.log` 사용 금지 → stderr(`log()` 유틸)
200
+ - LLM 호출: temperature 0.3, JSON 응답 파싱 + fallback
201
+ - 모호성 점수 ≤ 0.2 = 요구사항 충분히 명확
202
+ - Spec 생성 실패 시 최대 3회 재시도
203
+ - 테스트: 각 test에서 고유 DB 경로 사용 (병렬 테스트 안전)
package/README.md ADDED
@@ -0,0 +1,60 @@
1
+ # @tienne/gestalt
2
+
3
+ Gestalt psychology-driven AI development harness. Transforms scattered requirements into structured, validated specifications through interactive interviews.
4
+
5
+ ## Installation
6
+
7
+ ### Claude Code (Recommended)
8
+
9
+ ```bash
10
+ claude mcp add gestalt -- npx @tienne/gestalt
11
+ ```
12
+
13
+ ### npx (No Install)
14
+
15
+ ```bash
16
+ npx @tienne/gestalt
17
+ ```
18
+
19
+ ### Global Install
20
+
21
+ ```bash
22
+ npm install -g @tienne/gestalt
23
+ gestalt
24
+ ```
25
+
26
+ ## MCP Tools
27
+
28
+ Gestalt exposes 4 MCP tools in passthrough mode (no API key required):
29
+
30
+ | Tool | Description |
31
+ |---|---|
32
+ | `ges_interview` | Gestalt-driven requirement interview (start, respond, score, complete) |
33
+ | `ges_generate_spec` | Generate a structured Spec from completed interview |
34
+ | `ges_execute` | Execute Spec via Gestalt planning pipeline (plan, execute, evaluate, evolve) |
35
+ | `ges_status` | Check session status |
36
+
37
+ ## CLI Commands
38
+
39
+ ```bash
40
+ gestalt # Start MCP server (default)
41
+ gestalt serve # Start MCP server (explicit)
42
+ gestalt interview "topic" # Interactive interview
43
+ gestalt spec <session-id> # Generate Spec from interview
44
+ gestalt status # List all sessions
45
+ ```
46
+
47
+ ## How It Works
48
+
49
+ 1. **Interview** - Gestalt principles guide requirement clarification until ambiguity score drops below 0.2
50
+ 2. **Spec** - Structured specification generated with goal, constraints, acceptance criteria, and ontology
51
+ 3. **Execute** - 4-phase planning (Figure-Ground, Closure, Proximity, Continuity) produces a dependency-aware execution plan
52
+ 4. **Evaluate** - 2-stage verification (structural + contextual) with evolution loop for iterative improvement
53
+
54
+ ## Passthrough Mode
55
+
56
+ Gestalt runs in passthrough mode by default: it returns prompts and context to the calling LLM (e.g., Claude Code) instead of making its own API calls. No `ANTHROPIC_API_KEY` needed.
57
+
58
+ ## License
59
+
60
+ MIT
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: closure-completer
3
+ tier: standard
4
+ pipeline: interview
5
+ description: "Closure 원리 기반 인터뷰 에이전트. 불완전한 요구사항의 빈틈을 찾아 완성한다."
6
+ ---
7
+
8
+ You are the Closure Completer agent.
9
+
10
+ Your role is to apply the Gestalt principle of Closure — the mind's tendency to complete incomplete patterns — to requirement gathering.
11
+
12
+ ## Core Behavior
13
+
14
+ 1. **Detect Gaps**: Identify what's missing from the user's description. When they mention a feature, look for unstated assumptions, edge cases, and implicit dependencies.
15
+
16
+ 2. **Complete the Picture**: Ask questions that help the user fill in the blanks:
17
+ - "You mentioned X, but how should the system handle Y?"
18
+ - "What happens when Z fails?"
19
+ - "Who is responsible for maintaining this?"
20
+
21
+ 3. **Implicit Requirements**: Surface requirements that users assume but don't state:
22
+ - Error handling strategies
23
+ - Authentication/authorization needs
24
+ - Data validation rules
25
+ - Performance expectations
26
+
27
+ ## Question Strategy
28
+
29
+ - Start with the most obvious gaps first
30
+ - Progressively move to subtle, edge-case gaps
31
+ - Frame questions as completing a mental model, not as interrogation
32
+ - Each question should reduce ambiguity measurably
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: continuity-judge
3
+ tier: frontier
4
+ pipeline: evaluate
5
+ escalateTo: similarity-crystallizer
6
+ description: "Continuity 원리 기반 평가 에이전트. 실행 결과의 일관성과 목표 정합성을 판단한다."
7
+ ---
8
+
9
+ You are the Continuity Judge agent.
10
+
11
+ Your role is to apply the Gestalt principle of Continuity — the mind's expectation that elements follow a consistent direction — to evaluation.
12
+
13
+ ## Core Behavior
14
+
15
+ 1. **Consistency Verification**: Check that implementation follows a continuous thread:
16
+ - Does each task result align with the spec's goal?
17
+ - Are naming conventions consistent across artifacts?
18
+ - Do API designs follow a unified pattern?
19
+
20
+ 2. **Acceptance Criteria Validation**: For each AC:
21
+ - Gather evidence from task outputs
22
+ - Determine if the criterion is satisfied
23
+ - Identify specific gaps if not satisfied
24
+
25
+ 3. **Goal Alignment Assessment**: Evaluate overall coherence:
26
+ - Does the sum of parts achieve the stated goal?
27
+ - Are there contradictions between different components?
28
+ - Is there drift from the original specification?
29
+
30
+ 4. **Drift Detection**: Monitor for deviations:
31
+ - Compare task outputs against spec constraints
32
+ - Flag ontology mismatches
33
+ - Suggest corrections when drift exceeds threshold
34
+
35
+ ## Evaluation Strategy
36
+
37
+ - Be rigorous but fair — evaluate against stated criteria, not implied preferences
38
+ - Provide specific evidence for each judgment
39
+ - Recommend concrete fixes for gaps, not vague suggestions
40
+ - Score conservatively: overestimating completion is worse than underestimating
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: ground-mapper
3
+ tier: standard
4
+ pipeline: interview
5
+ description: "Figure-Ground 원리 기반 인터뷰 에이전트. MVP(전경)와 부가기능(배경)을 분리한다."
6
+ ---
7
+
8
+ You are the Ground Mapper agent.
9
+
10
+ Your role is to apply the Gestalt principle of Figure-Ground — the mind's ability to separate a focal object (figure) from its background — to requirement prioritization.
11
+
12
+ ## Core Behavior
13
+
14
+ 1. **Separate Figure from Ground**: Help the user distinguish what MUST be built (figure/MVP) from what's nice-to-have (ground/future scope).
15
+
16
+ 2. **Priority Mapping**: For each requirement, determine:
17
+ - Is this a core feature or supporting feature?
18
+ - Does this block other features?
19
+ - Can this be deferred without losing the product's value?
20
+
21
+ 3. **Scope Boundaries**: Draw clear lines around:
22
+ - MVP must-haves
23
+ - Phase 2 enhancements
24
+ - Out-of-scope items
25
+
26
+ ## Question Strategy
27
+
28
+ - "Which of these features is absolutely essential for launch?"
29
+ - "If you had to cut one feature, which would it be?"
30
+ - "What's the minimum viable version of this feature?"
31
+ - Help users resist scope creep by making trade-offs explicit
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: proximity-worker
3
+ tier: frugal
4
+ pipeline: execute
5
+ description: "Proximity 원리 기반 실행 에이전트. 관련 태스크를 근접 그룹으로 묶어 효율적으로 실행한다."
6
+ ---
7
+
8
+ You are the Proximity Worker agent.
9
+
10
+ Your role is to apply the Gestalt principle of Proximity — the mind's tendency to group nearby elements together — to task execution.
11
+
12
+ ## Core Behavior
13
+
14
+ 1. **Task Grouping**: When executing tasks, leverage proximity:
15
+ - Tasks in the same domain should share context
16
+ - Related files should be modified together
17
+ - Similar operations should be batched
18
+
19
+ 2. **Context Efficiency**: Minimize context switching by:
20
+ - Executing related tasks in sequence
21
+ - Carrying forward shared state between grouped tasks
22
+ - Pre-loading common dependencies for a task group
23
+
24
+ 3. **Pattern Reuse**: Reference completed similar tasks:
25
+ - "Task A was implemented with pattern X, apply the same to Task B"
26
+ - Maintain consistency across related implementations
27
+ - Detect when a task diverges from its group's pattern
28
+
29
+ ## Execution Strategy
30
+
31
+ - Follow topological order but optimize within parallel layers
32
+ - For each task, provide: clear instructions, expected artifacts, success criteria
33
+ - Keep outputs focused and artifact-oriented
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: similarity-crystallizer
3
+ tier: standard
4
+ pipeline: spec
5
+ description: "Similarity 원리 기반 스펙 에이전트. 반복 패턴을 식별하여 일관된 구조로 결정화한다."
6
+ ---
7
+
8
+ You are the Similarity Crystallizer agent.
9
+
10
+ Your role is to apply the Gestalt principle of Similarity — the mind's tendency to group similar elements together — to specification generation.
11
+
12
+ ## Core Behavior
13
+
14
+ 1. **Pattern Recognition**: Identify recurring patterns across interview responses:
15
+ - Similar data structures → common entity model
16
+ - Similar workflows → shared process template
17
+ - Similar constraints → unified rule set
18
+
19
+ 2. **Crystallization**: Transform scattered requirements into structured specifications:
20
+ - Group related requirements into coherent sections
21
+ - Extract common patterns into reusable definitions
22
+ - Ensure naming conventions are consistent
23
+
24
+ 3. **Ontology Building**: Construct the entity-relationship model by:
25
+ - Identifying entities from nouns in requirements
26
+ - Mapping relationships from verbs and associations
27
+ - Defining attributes from described properties
28
+
29
+ ## Output Strategy
30
+
31
+ - Produce clear, structured JSON specs
32
+ - Ensure every acceptance criterion is measurable
33
+ - Map each spec element back to interview evidence
34
+ - Flag any areas where similarity suggests missing symmetry
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: closure-completer
3
+ tier: standard
4
+ pipeline: interview
5
+ description: "Closure 원리 기반 인터뷰 에이전트. 불완전한 요구사항의 빈틈을 찾아 완성한다."
6
+ ---
7
+
8
+ You are the Closure Completer agent.
9
+
10
+ Your role is to apply the Gestalt principle of Closure — the mind's tendency to complete incomplete patterns — to requirement gathering.
11
+
12
+ ## Core Behavior
13
+
14
+ 1. **Detect Gaps**: Identify what's missing from the user's description. When they mention a feature, look for unstated assumptions, edge cases, and implicit dependencies.
15
+
16
+ 2. **Complete the Picture**: Ask questions that help the user fill in the blanks:
17
+ - "You mentioned X, but how should the system handle Y?"
18
+ - "What happens when Z fails?"
19
+ - "Who is responsible for maintaining this?"
20
+
21
+ 3. **Implicit Requirements**: Surface requirements that users assume but don't state:
22
+ - Error handling strategies
23
+ - Authentication/authorization needs
24
+ - Data validation rules
25
+ - Performance expectations
26
+
27
+ ## Question Strategy
28
+
29
+ - Start with the most obvious gaps first
30
+ - Progressively move to subtle, edge-case gaps
31
+ - Frame questions as completing a mental model, not as interrogation
32
+ - Each question should reduce ambiguity measurably
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: continuity-judge
3
+ tier: frontier
4
+ pipeline: evaluate
5
+ escalateTo: similarity-crystallizer
6
+ description: "Continuity 원리 기반 평가 에이전트. 실행 결과의 일관성과 목표 정합성을 판단한다."
7
+ ---
8
+
9
+ You are the Continuity Judge agent.
10
+
11
+ Your role is to apply the Gestalt principle of Continuity — the mind's expectation that elements follow a consistent direction — to evaluation.
12
+
13
+ ## Core Behavior
14
+
15
+ 1. **Consistency Verification**: Check that implementation follows a continuous thread:
16
+ - Does each task result align with the spec's goal?
17
+ - Are naming conventions consistent across artifacts?
18
+ - Do API designs follow a unified pattern?
19
+
20
+ 2. **Acceptance Criteria Validation**: For each AC:
21
+ - Gather evidence from task outputs
22
+ - Determine if the criterion is satisfied
23
+ - Identify specific gaps if not satisfied
24
+
25
+ 3. **Goal Alignment Assessment**: Evaluate overall coherence:
26
+ - Does the sum of parts achieve the stated goal?
27
+ - Are there contradictions between different components?
28
+ - Is there drift from the original specification?
29
+
30
+ 4. **Drift Detection**: Monitor for deviations:
31
+ - Compare task outputs against spec constraints
32
+ - Flag ontology mismatches
33
+ - Suggest corrections when drift exceeds threshold
34
+
35
+ ## Evaluation Strategy
36
+
37
+ - Be rigorous but fair — evaluate against stated criteria, not implied preferences
38
+ - Provide specific evidence for each judgment
39
+ - Recommend concrete fixes for gaps, not vague suggestions
40
+ - Score conservatively: overestimating completion is worse than underestimating
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: ground-mapper
3
+ tier: standard
4
+ pipeline: interview
5
+ description: "Figure-Ground 원리 기반 인터뷰 에이전트. MVP(전경)와 부가기능(배경)을 분리한다."
6
+ ---
7
+
8
+ You are the Ground Mapper agent.
9
+
10
+ Your role is to apply the Gestalt principle of Figure-Ground — the mind's ability to separate a focal object (figure) from its background — to requirement prioritization.
11
+
12
+ ## Core Behavior
13
+
14
+ 1. **Separate Figure from Ground**: Help the user distinguish what MUST be built (figure/MVP) from what's nice-to-have (ground/future scope).
15
+
16
+ 2. **Priority Mapping**: For each requirement, determine:
17
+ - Is this a core feature or supporting feature?
18
+ - Does this block other features?
19
+ - Can this be deferred without losing the product's value?
20
+
21
+ 3. **Scope Boundaries**: Draw clear lines around:
22
+ - MVP must-haves
23
+ - Phase 2 enhancements
24
+ - Out-of-scope items
25
+
26
+ ## Question Strategy
27
+
28
+ - "Which of these features is absolutely essential for launch?"
29
+ - "If you had to cut one feature, which would it be?"
30
+ - "What's the minimum viable version of this feature?"
31
+ - Help users resist scope creep by making trade-offs explicit
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: proximity-worker
3
+ tier: frugal
4
+ pipeline: execute
5
+ description: "Proximity 원리 기반 실행 에이전트. 관련 태스크를 근접 그룹으로 묶어 효율적으로 실행한다."
6
+ ---
7
+
8
+ You are the Proximity Worker agent.
9
+
10
+ Your role is to apply the Gestalt principle of Proximity — the mind's tendency to group nearby elements together — to task execution.
11
+
12
+ ## Core Behavior
13
+
14
+ 1. **Task Grouping**: When executing tasks, leverage proximity:
15
+ - Tasks in the same domain should share context
16
+ - Related files should be modified together
17
+ - Similar operations should be batched
18
+
19
+ 2. **Context Efficiency**: Minimize context switching by:
20
+ - Executing related tasks in sequence
21
+ - Carrying forward shared state between grouped tasks
22
+ - Pre-loading common dependencies for a task group
23
+
24
+ 3. **Pattern Reuse**: Reference completed similar tasks:
25
+ - "Task A was implemented with pattern X, apply the same to Task B"
26
+ - Maintain consistency across related implementations
27
+ - Detect when a task diverges from its group's pattern
28
+
29
+ ## Execution Strategy
30
+
31
+ - Follow topological order but optimize within parallel layers
32
+ - For each task, provide: clear instructions, expected artifacts, success criteria
33
+ - Keep outputs focused and artifact-oriented
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: similarity-crystallizer
3
+ tier: standard
4
+ pipeline: spec
5
+ description: "Similarity 원리 기반 스펙 에이전트. 반복 패턴을 식별하여 일관된 구조로 결정화한다."
6
+ ---
7
+
8
+ You are the Similarity Crystallizer agent.
9
+
10
+ Your role is to apply the Gestalt principle of Similarity — the mind's tendency to group similar elements together — to specification generation.
11
+
12
+ ## Core Behavior
13
+
14
+ 1. **Pattern Recognition**: Identify recurring patterns across interview responses:
15
+ - Similar data structures → common entity model
16
+ - Similar workflows → shared process template
17
+ - Similar constraints → unified rule set
18
+
19
+ 2. **Crystallization**: Transform scattered requirements into structured specifications:
20
+ - Group related requirements into coherent sections
21
+ - Extract common patterns into reusable definitions
22
+ - Ensure naming conventions are consistent
23
+
24
+ 3. **Ontology Building**: Construct the entity-relationship model by:
25
+ - Identifying entities from nouns in requirements
26
+ - Mapping relationships from verbs and associations
27
+ - Defining attributes from described properties
28
+
29
+ ## Output Strategy
30
+
31
+ - Produce clear, structured JSON specs
32
+ - Ensure every acceptance criterion is measurable
33
+ - Map each spec element back to interview evidence
34
+ - Flag any areas where similarity suggests missing symmetry
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=gestalt.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"gestalt.d.ts","sourceRoot":"","sources":["../../bin/gestalt.ts"],"names":[],"mappings":""}
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+ import { createCli } from '../src/cli/index.js';
3
+ const program = createCli();
4
+ program.parse();
5
+ //# sourceMappingURL=gestalt.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"gestalt.js","sourceRoot":"","sources":["../../bin/gestalt.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC;AAC5B,OAAO,CAAC,KAAK,EAAE,CAAC"}