@draht/coding-agent 2026.6.11 → 2026.7.7

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 (302) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +1 -4
  3. package/dist/bun/register-bedrock.d.ts.map +1 -1
  4. package/dist/bun/register-bedrock.js +1 -1
  5. package/dist/bun/register-bedrock.js.map +1 -1
  6. package/dist/bun/restore-sandbox-env.d.ts +4 -0
  7. package/dist/bun/restore-sandbox-env.d.ts.map +1 -1
  8. package/dist/bun/restore-sandbox-env.js +4 -0
  9. package/dist/bun/restore-sandbox-env.js.map +1 -1
  10. package/dist/cli/args.d.ts.map +1 -1
  11. package/dist/cli/args.js +4 -4
  12. package/dist/cli/args.js.map +1 -1
  13. package/dist/cli/config-selector.d.ts +4 -2
  14. package/dist/cli/config-selector.d.ts.map +1 -1
  15. package/dist/cli/config-selector.js +1 -1
  16. package/dist/cli/config-selector.js.map +1 -1
  17. package/dist/cli/file-processor.d.ts.map +1 -1
  18. package/dist/cli/file-processor.js +13 -25
  19. package/dist/cli/file-processor.js.map +1 -1
  20. package/dist/cli/session-picker.d.ts +2 -1
  21. package/dist/cli/session-picker.d.ts.map +1 -1
  22. package/dist/cli/session-picker.js +5 -4
  23. package/dist/cli/session-picker.js.map +1 -1
  24. package/dist/cli/startup-ui.d.ts +5 -1
  25. package/dist/cli/startup-ui.d.ts.map +1 -1
  26. package/dist/cli/startup-ui.js +94 -22
  27. package/dist/cli/startup-ui.js.map +1 -1
  28. package/dist/config.d.ts +6 -2
  29. package/dist/config.d.ts.map +1 -1
  30. package/dist/config.js +35 -16
  31. package/dist/config.js.map +1 -1
  32. package/dist/core/agent-session.d.ts +10 -4
  33. package/dist/core/agent-session.d.ts.map +1 -1
  34. package/dist/core/agent-session.js +124 -83
  35. package/dist/core/agent-session.js.map +1 -1
  36. package/dist/core/auth-storage.d.ts +11 -12
  37. package/dist/core/auth-storage.d.ts.map +1 -1
  38. package/dist/core/auth-storage.js +25 -26
  39. package/dist/core/auth-storage.js.map +1 -1
  40. package/dist/core/compaction/branch-summarization.d.ts +3 -1
  41. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  42. package/dist/core/compaction/branch-summarization.js +3 -3
  43. package/dist/core/compaction/branch-summarization.js.map +1 -1
  44. package/dist/core/compaction/compaction.d.ts +5 -4
  45. package/dist/core/compaction/compaction.d.ts.map +1 -1
  46. package/dist/core/compaction/compaction.js +23 -20
  47. package/dist/core/compaction/compaction.js.map +1 -1
  48. package/dist/core/export-html/vendor/marked.min.js +75 -3
  49. package/dist/core/extensions/index.d.ts +1 -1
  50. package/dist/core/extensions/index.d.ts.map +1 -1
  51. package/dist/core/extensions/index.js.map +1 -1
  52. package/dist/core/extensions/loader.d.ts +2 -3
  53. package/dist/core/extensions/loader.d.ts.map +1 -1
  54. package/dist/core/extensions/loader.js +77 -14
  55. package/dist/core/extensions/loader.js.map +1 -1
  56. package/dist/core/extensions/runner.d.ts +2 -1
  57. package/dist/core/extensions/runner.d.ts.map +1 -1
  58. package/dist/core/extensions/runner.js +33 -1
  59. package/dist/core/extensions/runner.js.map +1 -1
  60. package/dist/core/extensions/types.d.ts +29 -2
  61. package/dist/core/extensions/types.d.ts.map +1 -1
  62. package/dist/core/extensions/types.js.map +1 -1
  63. package/dist/core/http-dispatcher.d.ts +1 -0
  64. package/dist/core/http-dispatcher.d.ts.map +1 -1
  65. package/dist/core/http-dispatcher.js +45 -2
  66. package/dist/core/http-dispatcher.js.map +1 -1
  67. package/dist/core/index.d.ts +1 -1
  68. package/dist/core/index.d.ts.map +1 -1
  69. package/dist/core/index.js.map +1 -1
  70. package/dist/core/keybindings.d.ts +1 -1
  71. package/dist/core/keybindings.d.ts.map +1 -1
  72. package/dist/core/keybindings.js +3 -6
  73. package/dist/core/keybindings.js.map +1 -1
  74. package/dist/core/model-registry.d.ts +2 -1
  75. package/dist/core/model-registry.d.ts.map +1 -1
  76. package/dist/core/model-registry.js +32 -67
  77. package/dist/core/model-registry.js.map +1 -1
  78. package/dist/core/model-resolver.d.ts +11 -1
  79. package/dist/core/model-resolver.d.ts.map +1 -1
  80. package/dist/core/model-resolver.js +37 -19
  81. package/dist/core/model-resolver.js.map +1 -1
  82. package/dist/core/package-manager.d.ts +5 -2
  83. package/dist/core/package-manager.d.ts.map +1 -1
  84. package/dist/core/package-manager.js +99 -43
  85. package/dist/core/package-manager.js.map +1 -1
  86. package/dist/core/project-trust.d.ts.map +1 -1
  87. package/dist/core/project-trust.js +4 -3
  88. package/dist/core/project-trust.js.map +1 -1
  89. package/dist/core/provider-attribution.d.ts +2 -2
  90. package/dist/core/provider-attribution.d.ts.map +1 -1
  91. package/dist/core/provider-attribution.js.map +1 -1
  92. package/dist/core/provider-display-names.d.ts.map +1 -1
  93. package/dist/core/provider-display-names.js +1 -1
  94. package/dist/core/provider-display-names.js.map +1 -1
  95. package/dist/core/resolve-config-value.d.ts +7 -8
  96. package/dist/core/resolve-config-value.d.ts.map +1 -1
  97. package/dist/core/resolve-config-value.js +24 -26
  98. package/dist/core/resolve-config-value.js.map +1 -1
  99. package/dist/core/resource-loader.d.ts +3 -2
  100. package/dist/core/resource-loader.d.ts.map +1 -1
  101. package/dist/core/resource-loader.js +16 -6
  102. package/dist/core/resource-loader.js.map +1 -1
  103. package/dist/core/sdk.d.ts +9 -9
  104. package/dist/core/sdk.d.ts.map +1 -1
  105. package/dist/core/sdk.js +3 -1
  106. package/dist/core/sdk.js.map +1 -1
  107. package/dist/core/session-manager.d.ts +21 -2
  108. package/dist/core/session-manager.d.ts.map +1 -1
  109. package/dist/core/session-manager.js +121 -77
  110. package/dist/core/session-manager.js.map +1 -1
  111. package/dist/core/settings-manager.d.ts +10 -1
  112. package/dist/core/settings-manager.d.ts.map +1 -1
  113. package/dist/core/settings-manager.js +29 -3
  114. package/dist/core/settings-manager.js.map +1 -1
  115. package/dist/core/system-prompt.d.ts.map +1 -1
  116. package/dist/core/system-prompt.js +7 -7
  117. package/dist/core/system-prompt.js.map +1 -1
  118. package/dist/core/timings.d.ts +4 -2
  119. package/dist/core/timings.d.ts.map +1 -1
  120. package/dist/core/timings.js +24 -14
  121. package/dist/core/timings.js.map +1 -1
  122. package/dist/core/tools/bash.d.ts.map +1 -1
  123. package/dist/core/tools/bash.js +32 -8
  124. package/dist/core/tools/bash.js.map +1 -1
  125. package/dist/core/tools/edit-diff.d.ts +23 -4
  126. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  127. package/dist/core/tools/edit-diff.js +99 -20
  128. package/dist/core/tools/edit-diff.js.map +1 -1
  129. package/dist/core/tools/edit.d.ts.map +1 -1
  130. package/dist/core/tools/edit.js +2 -2
  131. package/dist/core/tools/edit.js.map +1 -1
  132. package/dist/core/tools/find.d.ts.map +1 -1
  133. package/dist/core/tools/find.js +19 -11
  134. package/dist/core/tools/find.js.map +1 -1
  135. package/dist/core/tools/read.d.ts.map +1 -1
  136. package/dist/core/tools/read.js +12 -25
  137. package/dist/core/tools/read.js.map +1 -1
  138. package/dist/core/trust-manager.d.ts +8 -3
  139. package/dist/core/trust-manager.d.ts.map +1 -1
  140. package/dist/core/trust-manager.js +26 -11
  141. package/dist/core/trust-manager.js.map +1 -1
  142. package/dist/index.d.ts +6 -4
  143. package/dist/index.d.ts.map +1 -1
  144. package/dist/index.js +5 -3
  145. package/dist/index.js.map +1 -1
  146. package/dist/main.d.ts +2 -2
  147. package/dist/main.d.ts.map +1 -1
  148. package/dist/main.js +47 -15
  149. package/dist/main.js.map +1 -1
  150. package/dist/migrations.d.ts.map +1 -1
  151. package/dist/migrations.js +1 -123
  152. package/dist/migrations.js.map +1 -1
  153. package/dist/modes/interactive/assets/clankolas.png +0 -0
  154. package/dist/modes/interactive/components/assistant-message.d.ts +3 -1
  155. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  156. package/dist/modes/interactive/components/assistant-message.js +23 -15
  157. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  158. package/dist/modes/interactive/components/config-selector.d.ts +34 -3
  159. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  160. package/dist/modes/interactive/components/config-selector.js +284 -29
  161. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  162. package/dist/modes/interactive/components/custom-entry.d.ts +19 -0
  163. package/dist/modes/interactive/components/custom-entry.d.ts.map +1 -0
  164. package/dist/modes/interactive/components/custom-entry.js +52 -0
  165. package/dist/modes/interactive/components/custom-entry.js.map +1 -0
  166. package/dist/modes/interactive/components/extension-editor.d.ts +3 -1
  167. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  168. package/dist/modes/interactive/components/extension-editor.js +12 -3
  169. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  170. package/dist/modes/interactive/components/footer.d.ts +2 -2
  171. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  172. package/dist/modes/interactive/components/footer.js +4 -0
  173. package/dist/modes/interactive/components/footer.js.map +1 -1
  174. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  175. package/dist/modes/interactive/components/login-dialog.js +0 -1
  176. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  177. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  178. package/dist/modes/interactive/components/model-selector.js +2 -1
  179. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  180. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  181. package/dist/modes/interactive/components/scoped-models-selector.js +4 -1
  182. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  183. package/dist/modes/interactive/components/session-selector.d.ts +0 -1
  184. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  185. package/dist/modes/interactive/components/session-selector.js +14 -8
  186. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  187. package/dist/modes/interactive/components/settings-selector.d.ts +4 -0
  188. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  189. package/dist/modes/interactive/components/settings-selector.js +188 -16
  190. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  191. package/dist/modes/interactive/components/status-indicator.d.ts +28 -0
  192. package/dist/modes/interactive/components/status-indicator.d.ts.map +1 -0
  193. package/dist/modes/interactive/components/status-indicator.js +60 -0
  194. package/dist/modes/interactive/components/status-indicator.js.map +1 -0
  195. package/dist/modes/interactive/components/tree-selector.d.ts +1 -1
  196. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  197. package/dist/modes/interactive/components/tree-selector.js +130 -15
  198. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  199. package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -1
  200. package/dist/modes/interactive/components/trust-selector.js +4 -4
  201. package/dist/modes/interactive/components/trust-selector.js.map +1 -1
  202. package/dist/modes/interactive/components/user-message.d.ts +6 -2
  203. package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
  204. package/dist/modes/interactive/components/user-message.js +19 -6
  205. package/dist/modes/interactive/components/user-message.js.map +1 -1
  206. package/dist/modes/interactive/interactive-mode.d.ts +13 -11
  207. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  208. package/dist/modes/interactive/interactive-mode.js +252 -233
  209. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  210. package/dist/modes/interactive/model-search.d.ts +12 -0
  211. package/dist/modes/interactive/model-search.d.ts.map +1 -0
  212. package/dist/modes/interactive/model-search.js +15 -0
  213. package/dist/modes/interactive/model-search.js.map +1 -0
  214. package/dist/modes/interactive/theme/theme-controller.d.ts +29 -0
  215. package/dist/modes/interactive/theme/theme-controller.d.ts.map +1 -0
  216. package/dist/modes/interactive/theme/theme-controller.js +102 -0
  217. package/dist/modes/interactive/theme/theme-controller.js.map +1 -0
  218. package/dist/modes/interactive/theme/theme-schema.json +2 -1
  219. package/dist/modes/interactive/theme/theme.d.ts +27 -8
  220. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  221. package/dist/modes/interactive/theme/theme.js +64 -42
  222. package/dist/modes/interactive/theme/theme.js.map +1 -1
  223. package/dist/modes/rpc/rpc-client.d.ts +19 -4
  224. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  225. package/dist/modes/rpc/rpc-client.js +14 -0
  226. package/dist/modes/rpc/rpc-client.js.map +1 -1
  227. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  228. package/dist/modes/rpc/rpc-mode.js +17 -1
  229. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  230. package/dist/modes/rpc/rpc-types.d.ts +26 -0
  231. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  232. package/dist/modes/rpc/rpc-types.js.map +1 -1
  233. package/dist/package-manager-cli.d.ts +2 -2
  234. package/dist/package-manager-cli.d.ts.map +1 -1
  235. package/dist/package-manager-cli.js +152 -48
  236. package/dist/package-manager-cli.js.map +1 -1
  237. package/dist/prompts/commands/brainstorm.md +148 -0
  238. package/dist/rpc-entry.d.ts +3 -0
  239. package/dist/rpc-entry.d.ts.map +1 -0
  240. package/dist/rpc-entry.js +10 -0
  241. package/dist/rpc-entry.js.map +1 -0
  242. package/dist/utils/child-process.d.ts +7 -4
  243. package/dist/utils/child-process.d.ts.map +1 -1
  244. package/dist/utils/child-process.js +23 -5
  245. package/dist/utils/child-process.js.map +1 -1
  246. package/dist/utils/image-convert.d.ts +1 -0
  247. package/dist/utils/image-convert.d.ts.map +1 -1
  248. package/dist/utils/image-convert.js +21 -15
  249. package/dist/utils/image-convert.js.map +1 -1
  250. package/dist/utils/image-process.d.ts +18 -0
  251. package/dist/utils/image-process.d.ts.map +1 -0
  252. package/dist/utils/image-process.js +83 -0
  253. package/dist/utils/image-process.js.map +1 -0
  254. package/dist/utils/mime.d.ts.map +1 -1
  255. package/dist/utils/mime.js +41 -0
  256. package/dist/utils/mime.js.map +1 -1
  257. package/dist/utils/shell.d.ts +1 -0
  258. package/dist/utils/shell.d.ts.map +1 -1
  259. package/dist/utils/shell.js +12 -5
  260. package/dist/utils/shell.js.map +1 -1
  261. package/dist/utils/version-check.d.ts.map +1 -1
  262. package/dist/utils/version-check.js +4 -27
  263. package/dist/utils/version-check.js.map +1 -1
  264. package/docs/extensions.md +55 -8
  265. package/docs/keybindings.md +1 -1
  266. package/docs/packages.md +2 -2
  267. package/docs/providers.md +2 -1
  268. package/docs/rpc.md +58 -0
  269. package/docs/sdk.md +50 -0
  270. package/docs/session-format.md +18 -8
  271. package/docs/settings.md +10 -0
  272. package/docs/usage.md +2 -2
  273. package/examples/extensions/README.md +1 -0
  274. package/examples/extensions/custom-compaction.ts +2 -1
  275. package/examples/extensions/custom-provider-anthropic/index.ts +1 -1
  276. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  277. package/examples/extensions/custom-provider-anthropic/package.json +1 -1
  278. package/examples/extensions/custom-provider-gitlab-duo/index.ts +9 -5
  279. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  280. package/examples/extensions/custom-provider-gitlab-duo/test.ts +1 -1
  281. package/examples/extensions/entry-renderer.ts +41 -0
  282. package/examples/extensions/gondolin/package-lock.json +2 -2
  283. package/examples/extensions/gondolin/package.json +1 -1
  284. package/examples/extensions/handoff.ts +2 -2
  285. package/examples/extensions/plan-mode/index.ts +87 -37
  286. package/examples/extensions/preset.ts +10 -4
  287. package/examples/extensions/provider-payload.ts +5 -5
  288. package/examples/extensions/qna.ts +2 -2
  289. package/examples/extensions/question.ts +32 -18
  290. package/examples/extensions/questionnaire.ts +41 -28
  291. package/examples/extensions/sandbox/index.ts +2 -2
  292. package/examples/extensions/sandbox/package-lock.json +2 -2
  293. package/examples/extensions/sandbox/package.json +1 -1
  294. package/examples/extensions/subagent/agents.ts +2 -2
  295. package/examples/extensions/subagent/index.ts +9 -3
  296. package/examples/extensions/summarize.ts +2 -1
  297. package/examples/extensions/with-deps/package-lock.json +2 -2
  298. package/examples/extensions/with-deps/package.json +1 -1
  299. package/examples/sdk/02-custom-model.ts +1 -1
  300. package/examples/sdk/12-full-control.ts +2 -2
  301. package/package.json +14 -15
  302. package/prompts/commands/brainstorm.md +148 -0
@@ -5,7 +5,7 @@
5
5
  */
6
6
 
7
7
  import type { ExtensionAPI } from "@draht/coding-agent";
8
- import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from "@draht/tui";
8
+ import { Editor, type EditorTheme, Key, matchesKey, Text, visibleWidth, wrapTextWithAnsi } from "@draht/tui";
9
9
  import { Type } from "typebox";
10
10
 
11
11
  interface OptionWithDesc {
@@ -39,6 +39,7 @@ export default function question(pi: ExtensionAPI) {
39
39
  label: "Question",
40
40
  description: "Ask the user a question and let them pick from options. Use when you need user input to proceed.",
41
41
  parameters: QuestionParams,
42
+ executionMode: "sequential",
42
43
 
43
44
  async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
44
45
  if (ctx.mode !== "tui") {
@@ -139,10 +140,27 @@ export default function question(pi: ExtensionAPI) {
139
140
  if (cachedLines) return cachedLines;
140
141
 
141
142
  const lines: string[] = [];
142
- const add = (s: string) => lines.push(truncateToWidth(s, width));
143
+ const renderWidth = Math.max(1, width);
143
144
 
144
- add(theme.fg("accent", "─".repeat(width)));
145
- add(theme.fg("text", ` ${params.question}`));
145
+ function addWrapped(text: string) {
146
+ lines.push(...wrapTextWithAnsi(text, renderWidth));
147
+ }
148
+
149
+ function addWrappedWithPrefix(prefix: string, text: string) {
150
+ const prefixWidth = visibleWidth(prefix);
151
+ if (prefixWidth >= renderWidth) {
152
+ addWrapped(prefix + text);
153
+ return;
154
+ }
155
+ const wrapped = wrapTextWithAnsi(text, renderWidth - prefixWidth);
156
+ const continuationPrefix = " ".repeat(prefixWidth);
157
+ for (let i = 0; i < wrapped.length; i++) {
158
+ lines.push(`${i === 0 ? prefix : continuationPrefix}${wrapped[i]}`);
159
+ }
160
+ }
161
+
162
+ lines.push(theme.fg("accent", "─".repeat(renderWidth)));
163
+ addWrappedWithPrefix(" ", theme.fg("text", params.question));
146
164
  lines.push("");
147
165
 
148
166
  for (let i = 0; i < allOptions.length; i++) {
@@ -150,36 +168,32 @@ export default function question(pi: ExtensionAPI) {
150
168
  const selected = i === optionIndex;
151
169
  const isOther = opt.isOther === true;
152
170
  const prefix = selected ? theme.fg("accent", "> ") : " ";
171
+ const label = `${i + 1}. ${opt.label}${isOther && editMode ? " ✎" : ""}`;
172
+ const color = selected || (isOther && editMode) ? "accent" : "text";
153
173
 
154
- if (isOther && editMode) {
155
- add(prefix + theme.fg("accent", `${i + 1}. ${opt.label} ✎`));
156
- } else if (selected) {
157
- add(prefix + theme.fg("accent", `${i + 1}. ${opt.label}`));
158
- } else {
159
- add(` ${theme.fg("text", `${i + 1}. ${opt.label}`)}`);
160
- }
174
+ addWrappedWithPrefix(prefix, theme.fg(color, label));
161
175
 
162
176
  // Show description if present
163
177
  if (opt.description) {
164
- add(` ${theme.fg("muted", opt.description)}`);
178
+ addWrappedWithPrefix(" ", theme.fg("muted", opt.description));
165
179
  }
166
180
  }
167
181
 
168
182
  if (editMode) {
169
183
  lines.push("");
170
- add(theme.fg("muted", " Your answer:"));
171
- for (const line of editor.render(width - 2)) {
172
- add(` ${line}`);
184
+ addWrappedWithPrefix(" ", theme.fg("muted", "Your answer:"));
185
+ for (const line of editor.render(Math.max(1, renderWidth - 2))) {
186
+ lines.push(` ${line}`);
173
187
  }
174
188
  }
175
189
 
176
190
  lines.push("");
177
191
  if (editMode) {
178
- add(theme.fg("dim", " Enter to submit • Esc to go back"));
192
+ addWrappedWithPrefix(" ", theme.fg("dim", "Enter to submit • Esc to go back"));
179
193
  } else {
180
- add(theme.fg("dim", " ↑↓ navigate • Enter to select • Esc to cancel"));
194
+ addWrappedWithPrefix(" ", theme.fg("dim", "↑↓ navigate • Enter to select • Esc to cancel"));
181
195
  }
182
- add(theme.fg("accent", "─".repeat(width)));
196
+ lines.push(theme.fg("accent", "─".repeat(renderWidth)));
183
197
 
184
198
  cachedLines = lines;
185
199
  return lines;
@@ -6,7 +6,7 @@
6
6
  */
7
7
 
8
8
  import type { ExtensionAPI } from "@draht/coding-agent";
9
- import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from "@draht/tui";
9
+ import { Editor, type EditorTheme, Key, matchesKey, Text, visibleWidth, wrapTextWithAnsi } from "@draht/tui";
10
10
  import { Type } from "typebox";
11
11
 
12
12
  // Types
@@ -259,13 +259,28 @@ export default function questionnaire(pi: ExtensionAPI) {
259
259
  if (cachedLines) return cachedLines;
260
260
 
261
261
  const lines: string[] = [];
262
+ const renderWidth = Math.max(1, width);
262
263
  const q = currentQuestion();
263
264
  const opts = currentOptions();
264
265
 
265
- // Helper to add truncated line
266
- const add = (s: string) => lines.push(truncateToWidth(s, width));
266
+ function addWrapped(text: string) {
267
+ lines.push(...wrapTextWithAnsi(text, renderWidth));
268
+ }
269
+
270
+ function addWrappedWithPrefix(prefix: string, text: string) {
271
+ const prefixWidth = visibleWidth(prefix);
272
+ if (prefixWidth >= renderWidth) {
273
+ addWrapped(prefix + text);
274
+ return;
275
+ }
276
+ const wrapped = wrapTextWithAnsi(text, renderWidth - prefixWidth);
277
+ const continuationPrefix = " ".repeat(prefixWidth);
278
+ for (let i = 0; i < wrapped.length; i++) {
279
+ lines.push(`${i === 0 ? prefix : continuationPrefix}${wrapped[i]}`);
280
+ }
281
+ }
267
282
 
268
- add(theme.fg("accent", "─".repeat(width)));
283
+ lines.push(theme.fg("accent", "─".repeat(renderWidth)));
269
284
 
270
285
  // Tab bar (multi-question only)
271
286
  if (isMulti) {
@@ -287,7 +302,7 @@ export default function questionnaire(pi: ExtensionAPI) {
287
302
  ? theme.bg("selectedBg", theme.fg("text", submitText))
288
303
  : theme.fg(canSubmit ? "success" : "dim", submitText);
289
304
  tabs.push(`${submitStyled} →`);
290
- add(` ${tabs.join("")}`);
305
+ addWrappedWithPrefix(" ", tabs.join(""));
291
306
  lines.push("");
292
307
  }
293
308
 
@@ -298,54 +313,52 @@ export default function questionnaire(pi: ExtensionAPI) {
298
313
  const selected = i === optionIndex;
299
314
  const isOther = opt.isOther === true;
300
315
  const prefix = selected ? theme.fg("accent", "> ") : " ";
301
- const color = selected ? "accent" : "text";
302
- // Mark "Type something" differently when in input mode
303
- if (isOther && inputMode) {
304
- add(prefix + theme.fg("accent", `${i + 1}. ${opt.label} ✎`));
305
- } else {
306
- add(prefix + theme.fg(color, `${i + 1}. ${opt.label}`));
307
- }
316
+ const label = `${i + 1}. ${opt.label}${isOther && inputMode ? " ✎" : ""}`;
317
+ const color = selected || (isOther && inputMode) ? "accent" : "text";
318
+
319
+ addWrappedWithPrefix(prefix, theme.fg(color, label));
308
320
  if (opt.description) {
309
- add(` ${theme.fg("muted", opt.description)}`);
321
+ addWrappedWithPrefix(" ", theme.fg("muted", opt.description));
310
322
  }
311
323
  }
312
324
  }
313
325
 
314
326
  // Content
315
327
  if (inputMode && q) {
316
- add(theme.fg("text", ` ${q.prompt}`));
328
+ addWrappedWithPrefix(" ", theme.fg("text", q.prompt));
317
329
  lines.push("");
318
330
  // Show options for reference
319
331
  renderOptions();
320
332
  lines.push("");
321
- add(theme.fg("muted", " Your answer:"));
322
- for (const line of editor.render(width - 2)) {
323
- add(` ${line}`);
333
+ addWrappedWithPrefix(" ", theme.fg("muted", "Your answer:"));
334
+ for (const line of editor.render(Math.max(1, renderWidth - 2))) {
335
+ lines.push(` ${line}`);
324
336
  }
325
337
  lines.push("");
326
- add(theme.fg("dim", " Enter to submit • Esc to cancel"));
338
+ addWrappedWithPrefix(" ", theme.fg("dim", "Enter to submit • Esc to cancel"));
327
339
  } else if (currentTab === questions.length) {
328
- add(theme.fg("accent", theme.bold(" Ready to submit")));
340
+ addWrappedWithPrefix(" ", theme.fg("accent", theme.bold("Ready to submit")));
329
341
  lines.push("");
330
342
  for (const question of questions) {
331
343
  const answer = answers.get(question.id);
332
344
  if (answer) {
333
345
  const prefix = answer.wasCustom ? "(wrote) " : "";
334
- add(`${theme.fg("muted", ` ${question.label}: `)}${theme.fg("text", prefix + answer.label)}`);
346
+ const summary = `${theme.fg("muted", `${question.label}: `)}${theme.fg("text", prefix + answer.label)}`;
347
+ addWrappedWithPrefix(" ", summary);
335
348
  }
336
349
  }
337
350
  lines.push("");
338
351
  if (allAnswered()) {
339
- add(theme.fg("success", " Press Enter to submit"));
352
+ addWrappedWithPrefix(" ", theme.fg("success", "Press Enter to submit"));
340
353
  } else {
341
354
  const missing = questions
342
355
  .filter((q) => !answers.has(q.id))
343
356
  .map((q) => q.label)
344
357
  .join(", ");
345
- add(theme.fg("warning", ` Unanswered: ${missing}`));
358
+ addWrappedWithPrefix(" ", theme.fg("warning", `Unanswered: ${missing}`));
346
359
  }
347
360
  } else if (q) {
348
- add(theme.fg("text", ` ${q.prompt}`));
361
+ addWrappedWithPrefix(" ", theme.fg("text", q.prompt));
349
362
  lines.push("");
350
363
  renderOptions();
351
364
  }
@@ -353,11 +366,11 @@ export default function questionnaire(pi: ExtensionAPI) {
353
366
  lines.push("");
354
367
  if (!inputMode) {
355
368
  const help = isMulti
356
- ? " Tab/←→ navigate • ↑↓ select • Enter confirm • Esc cancel"
357
- : " ↑↓ navigate • Enter select • Esc cancel";
358
- add(theme.fg("dim", help));
369
+ ? "Tab/←→ navigate • ↑↓ select • Enter confirm • Esc cancel"
370
+ : "↑↓ navigate • Enter select • Esc cancel";
371
+ addWrappedWithPrefix(" ", theme.fg("dim", help));
359
372
  }
360
- add(theme.fg("accent", "─".repeat(width)));
373
+ lines.push(theme.fg("accent", "─".repeat(renderWidth)));
361
374
 
362
375
  cachedLines = lines;
363
376
  return lines;
@@ -400,7 +413,7 @@ export default function questionnaire(pi: ExtensionAPI) {
400
413
  let text = theme.fg("toolTitle", theme.bold("questionnaire "));
401
414
  text += theme.fg("muted", `${count} question${count !== 1 ? "s" : ""}`);
402
415
  if (labels) {
403
- text += theme.fg("dim", ` (${truncateToWidth(labels, 40)})`);
416
+ text += theme.fg("dim", ` (${labels})`);
404
417
  }
405
418
  return new Text(text, 0, 0);
406
419
  },
@@ -46,7 +46,7 @@ import { existsSync, readFileSync } from "node:fs";
46
46
  import { join } from "node:path";
47
47
  import { SandboxManager, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
48
48
  import type { ExtensionAPI } from "@draht/coding-agent";
49
- import { type BashOperations, createBashTool, getAgentDir } from "@draht/coding-agent";
49
+ import { type BashOperations, CONFIG_DIR_NAME, createBashTool, getAgentDir } from "@draht/coding-agent";
50
50
 
51
51
  interface SandboxConfig extends SandboxRuntimeConfig {
52
52
  enabled?: boolean;
@@ -77,7 +77,7 @@ const DEFAULT_CONFIG: SandboxConfig = {
77
77
  };
78
78
 
79
79
  function loadConfig(cwd: string): SandboxConfig {
80
- const projectConfigPath = join(cwd, ".pi", "sandbox.json");
80
+ const projectConfigPath = join(cwd, CONFIG_DIR_NAME, "sandbox.json");
81
81
  const globalConfigPath = join(getAgentDir(), "extensions", "sandbox.json");
82
82
 
83
83
  let globalConfig: Partial<SandboxConfig> = {};
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-extension-sandbox",
3
- "version": "1.9.1",
3
+ "version": "1.10.3",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-extension-sandbox",
9
- "version": "1.9.1",
9
+ "version": "1.10.3",
10
10
  "dependencies": {
11
11
  "@anthropic-ai/sandbox-runtime": "^0.0.26"
12
12
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-sandbox",
3
3
  "private": true,
4
- "version": "1.9.1",
4
+ "version": "1.10.3",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
@@ -4,7 +4,7 @@
4
4
 
5
5
  import * as fs from "node:fs";
6
6
  import * as path from "node:path";
7
- import { getAgentDir, parseFrontmatter } from "@draht/coding-agent";
7
+ import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@draht/coding-agent";
8
8
 
9
9
  export type AgentScope = "user" | "project" | "both";
10
10
 
@@ -85,7 +85,7 @@ function isDirectory(p: string): boolean {
85
85
  function findNearestProjectAgentsDir(cwd: string): string | null {
86
86
  let currentDir = cwd;
87
87
  while (true) {
88
- const candidate = path.join(currentDir, ".pi", "agents");
88
+ const candidate = path.join(currentDir, CONFIG_DIR_NAME, "agents");
89
89
  if (isDirectory(candidate)) return candidate;
90
90
 
91
91
  const parentDir = path.dirname(currentDir);
@@ -19,7 +19,13 @@ import * as path from "node:path";
19
19
  import type { AgentToolResult } from "@draht/agent-core";
20
20
  import type { Message } from "@draht/ai";
21
21
  import { StringEnum } from "@draht/ai";
22
- import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@draht/coding-agent";
22
+ import {
23
+ CONFIG_DIR_NAME,
24
+ type ExtensionAPI,
25
+ getAgentDir,
26
+ getMarkdownTheme,
27
+ withFileMutationQueue,
28
+ } from "@draht/coding-agent";
23
29
  import { Container, Markdown, Spacer, Text } from "@draht/tui";
24
30
  import { Type } from "typebox";
25
31
  import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.ts";
@@ -458,8 +464,8 @@ export default function (pi: ExtensionAPI) {
458
464
  description: [
459
465
  "Delegate tasks to specialized subagents with isolated context.",
460
466
  "Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
461
- 'Default agent scope is "user" (from ~/.pi/agent/agents).',
462
- 'To enable project-local agents in .pi/agents, set agentScope: "both" (or "project").',
467
+ `Default agent scope is "user" (from ${path.join(getAgentDir(), "agents")}).`,
468
+ `To enable project-local agents in ${CONFIG_DIR_NAME}/agents, set agentScope: "both" (or "project").`,
463
469
  ].join(" "),
464
470
  parameters: SubagentParams,
465
471
 
@@ -1,4 +1,4 @@
1
- import { complete, getModel } from "@draht/ai";
1
+ import { complete, getModel } from "@draht/ai/compat";
2
2
  import type { ExtensionAPI, ExtensionCommandContext } from "@draht/coding-agent";
3
3
  import { DynamicBorder, getMarkdownTheme } from "@draht/coding-agent";
4
4
  import { Container, Markdown, matchesKey, Text } from "@draht/tui";
@@ -191,6 +191,7 @@ export default function (pi: ExtensionAPI) {
191
191
  {
192
192
  apiKey: auth.apiKey,
193
193
  headers: auth.headers,
194
+ env: auth.env,
194
195
  reasoningEffort: "high",
195
196
  },
196
197
  );
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-extension-with-deps",
3
- "version": "0.79.1",
3
+ "version": "0.80.3",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-extension-with-deps",
9
- "version": "0.79.1",
9
+ "version": "0.80.3",
10
10
  "dependencies": {
11
11
  "ms": "^2.1.3"
12
12
  },
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-with-deps",
3
3
  "private": true,
4
- "version": "0.79.1",
4
+ "version": "0.80.3",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
@@ -4,7 +4,7 @@
4
4
  * Shows how to select a specific model and thinking level.
5
5
  */
6
6
 
7
- import { getModel } from "@draht/ai";
7
+ import { getModel } from "@draht/ai/compat";
8
8
  import { AuthStorage, createAgentSession, ModelRegistry } from "@draht/coding-agent";
9
9
 
10
10
  // Set up auth storage and model registry
@@ -4,7 +4,7 @@
4
4
  * Replace everything - no discovery, explicit configuration.
5
5
  */
6
6
 
7
- import { getModel } from "@draht/ai";
7
+ import { getModel } from "@draht/ai/compat";
8
8
  import {
9
9
  AuthStorage,
10
10
  createAgentSession,
@@ -26,7 +26,7 @@ if (process.env.MY_ANTHROPIC_KEY) {
26
26
  // Model registry with no custom models.json
27
27
  const modelRegistry = ModelRegistry.inMemory(authStorage);
28
28
 
29
- const model = getModel("anthropic", "claude-sonnet-4-20250514");
29
+ const model = getModel("anthropic", "claude-sonnet-4-5");
30
30
  if (!model) throw new Error("Model not found");
31
31
 
32
32
  // In-memory settings with overrides
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@draht/coding-agent",
3
- "version": "2026.6.11",
3
+ "version": "2026.7.7",
4
4
  "description": "Coding agent CLI with read, bash, edit, write tools and session management",
5
5
  "type": "module",
6
6
  "drahtConfig": {
@@ -19,9 +19,8 @@
19
19
  "types": "./dist/index.d.ts",
20
20
  "import": "./dist/index.js"
21
21
  },
22
- "./hooks": {
23
- "types": "./dist/core/hooks/index.d.ts",
24
- "import": "./dist/core/hooks/index.js"
22
+ "./rpc-entry": {
23
+ "import": "./dist/rpc-entry.js"
25
24
  }
26
25
  },
27
26
  "files": [
@@ -37,25 +36,23 @@
37
36
  "scripts": {
38
37
  "clean": "shx rm -rf dist",
39
38
  "dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
40
- "build": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js && bun run copy-assets",
41
- "build:binary": "bun run build && bun build --compile ./dist/cli.js --outfile dist/draht && bun run copy-binary-assets",
42
- "copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/ && shx rm -rf dist/prompts dist/hooks dist/agents && shx cp -r prompts dist/prompts && shx cp -r hooks dist/hooks && shx cp -r agents dist/agents",
43
- "copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp -r prompts dist/ && shx cp -r hooks dist/ && shx cp -r agents dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
39
+ "build": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && bun run copy-assets",
40
+ "build:binary": "bun run build && bun build --compile ./dist/cli.js ./src/utils/image-resize-worker.ts --outfile dist/draht && bun run copy-binary-assets",
41
+ "copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/ && shx rm -rf dist/prompts dist/hooks dist/agents && shx cp -r prompts dist/prompts && shx cp -r hooks dist/hooks && shx cp -r agents dist/agents",
42
+ "copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp -r prompts dist/ && shx cp -r hooks dist/ && shx cp -r agents dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
44
43
  "sync-tools": "node ../../scripts/sync-draht-tools.mjs",
45
44
  "test": "vitest --run",
46
45
  "prepublishOnly": "node ../../scripts/sync-draht-tools.mjs && bun run clean && bun run build"
47
46
  },
48
47
  "dependencies": {
49
48
  "@mariozechner/jiti": "^2.6.2",
50
- "@draht/agent-core": "2026.6.11",
51
- "@draht/ai": "2026.6.11",
52
- "@draht/tools": "2026.6.11",
53
- "@draht/tui": "2026.6.11",
49
+ "@draht/agent-core": "2026.7.7",
50
+ "@draht/ai": "2026.7.7",
51
+ "@draht/tools": "2026.7.7",
52
+ "@draht/tui": "2026.7.7",
54
53
  "@silvia-odwyer/photon-node": "^0.3.4",
55
54
  "@sinclair/typebox": "^0.34.41",
56
- "ajv": "^8.17.1",
57
- "chalk": "^5.5.0",
58
- "cli-highlight": "^2.1.11",
55
+ "chalk": "^5.6.2",
59
56
  "cross-spawn": "7.0.6",
60
57
  "diff": "^8.0.2",
61
58
  "extract-zip": "^2.0.1",
@@ -67,6 +64,7 @@
67
64
  "marked": "^15.0.12",
68
65
  "minimatch": "^10.2.3",
69
66
  "proper-lockfile": "^4.1.2",
67
+ "semver": "^7.8.0",
70
68
  "strip-ansi": "^7.1.0",
71
69
  "typebox": "^1.1.24",
72
70
  "undici": "^7.19.1",
@@ -89,6 +87,7 @@
89
87
  "@types/ms": "^2.1.0",
90
88
  "@types/node": "^24.3.0",
91
89
  "@types/proper-lockfile": "^4.1.4",
90
+ "@types/semver": "^7.7.1",
92
91
  "shx": "^0.4.0",
93
92
  "typescript": "^6.0.0-beta",
94
93
  "vitest": "^3.2.4"
@@ -0,0 +1,148 @@
1
+ ---
2
+ description: "Refine a fuzzy idea into a written design spec before planning or coding"
3
+ ---
4
+
5
+ # /brainstorm
6
+
7
+ The pre-planning gate. Before draht's GSD cycle runs, before code is scaffolded, before `/new-project` or `/init-project`, converge on the idea through dialogue and write it to `.planning/specs/`. This command enforces design-first discipline.
8
+
9
+ ## Usage
10
+ ```
11
+ /brainstorm [idea or topic]
12
+ ```
13
+
14
+ Topic: $ARGUMENTS
15
+
16
+ ## Atomic Reasoning
17
+
18
+ Before asking anything, decompose the idea into atomic reasoning units:
19
+
20
+ 1. **State the logical component** — What problem does this solve? Who is it for? What changes for them when it ships?
21
+ 2. **Validate independence** — What bounded contexts will exist? What is core vs peripheral? What can be built independently?
22
+ 3. **Verify correctness** — What defines v1 success? What constraints exist (time, tech, team)? What is explicitly out of scope?
23
+
24
+ **Synthesize design strategy:**
25
+ - Ground questions in what is already on disk instead of asking what the user already told you
26
+ - Sequence questions foundational → detailed, one at a time
27
+ - Surface 2–3 approaches with trade-offs before committing
28
+ - Record decisions (not proposals) in a spec file
29
+
30
+ ## The Hard Gate
31
+
32
+ > Do NOT invoke any planning command, write any code, scaffold any project, or take any implementation action until you have:
33
+ > 1. Asked clarifying questions one at a time
34
+ > 2. Proposed 2–3 approaches with trade-offs
35
+ > 3. Presented a structured design and the user has approved it
36
+ > 4. Written the design to `.planning/specs/YYYY-MM-DD-<slug>-design.md`
37
+
38
+ If the user pushes to skip ("just build it"), surface the trade-off: "I can scaffold something now, but skipping brainstorming usually means we throw out the first version. Are you sure?" If yes, proceed but make the assumption explicit in the spec.
39
+
40
+ ## The Process
41
+
42
+ ### 1. Explore Context
43
+
44
+ Before asking anything, read what's already on disk:
45
+ - `git log --oneline -30` — what has the user been working on recently?
46
+ - `ls -la` — what's in the project root?
47
+ - `.planning/` if it exists — is there an active project?
48
+ - `README.md`, `package.json`, any `*.md` in root — what does this codebase claim to do?
49
+
50
+ If an existing codebase is in play (extending a real project), run `draht-tools map-codebase` + `draht-tools graph-hotspots` first to ground ideation in the real structure — so brainstormed ideas don't contradict existing architecture.
51
+
52
+ Use this to ground questions in reality instead of asking things the user has already told you.
53
+
54
+ ### 2. Ask Clarifying Questions — ONE at a time
55
+
56
+ Most failed projects come from rushing past ambiguity. Ask **one focused question per message**, not a long list. Wait for the answer, then ask the next.
57
+
58
+ Question categories (sequence from foundational → detailed):
59
+ - **Goal** — who is this for? what changes for them when it ships?
60
+ - **Constraints** — deadline? budget? team size? language/stack preferences?
61
+ - **Scope** — what's in v1? what's explicitly NOT in v1?
62
+ - **Success criteria** — how do we know it works? what's the demoable outcome?
63
+ - **Domain** — what are the key nouns and verbs in this space? any existing glossary?
64
+ - **Risks** — what's the scariest part of this? what would make it fail?
65
+
66
+ If the project is obviously oversized for one cycle (e.g., "I want to build a social network"), flag it explicitly and propose decomposition into a v1 / v2 / out-of-scope split.
67
+
68
+ ### 3. Propose 2–3 Approaches With Trade-offs
69
+
70
+ Once you have enough context, propose multiple approaches:
71
+ - Approach A: the simplest path. What it sacrifices.
72
+ - Approach B: the most flexible. What it costs.
73
+ - (Optional) Approach C: the most ambitious. Why it's tempting and why it might be too much.
74
+
75
+ For each: list trade-offs in plain language (time, complexity, future flexibility, lock-in). Let the user pick — don't pre-pick for them.
76
+
77
+ ### 4. Present the Design in Sections, Each With an Approval Gate
78
+
79
+ Once an approach is chosen, present the design **section by section**, not all at once:
80
+ 1. Goal & non-goals
81
+ 2. User stories / observable truths
82
+ 3. Domain model (bounded contexts, key nouns)
83
+ 4. Architecture sketch (components, data flow)
84
+ 5. v1 scope (what ships) vs v2/out-of-scope (what doesn't)
85
+ 6. Open questions / risks
86
+
87
+ After each section, ask: "Does this match what you want, or should we adjust?" Only move to the next section once the current one is approved.
88
+
89
+ ### 5. Write the Spec to `.planning/specs/`
90
+
91
+ Once all sections are approved:
92
+
93
+ ```
94
+ .planning/specs/YYYY-MM-DD-<topic-slug>-design.md
95
+ ```
96
+
97
+ The file should include:
98
+ - Header with date and approver
99
+ - All approved sections
100
+ - Open questions section (the things you flagged but didn't resolve)
101
+ - Next step: which command picks this up (`/new-project` or `/init-project`)
102
+
103
+ ### 6. Self-Review the Written Spec
104
+
105
+ Before handing off, re-read the spec yourself looking for:
106
+ - Contradictions between sections (the goal says X, the architecture implies not-X)
107
+ - Gaps (a user story with no architectural support)
108
+ - Premature commitments (specific tech choices made before they were needed)
109
+ - Domain language drift (different names for the same thing)
110
+
111
+ Report any findings to the user and update before proceeding.
112
+
113
+ ### 7. Hand Off
114
+
115
+ Direct the user to the next command:
116
+ - Greenfield with no codebase → `/new-project`
117
+ - Existing codebase → `/init-project`
118
+
119
+ The spec file becomes input to those commands.
120
+
121
+ ## Workflow
122
+
123
+ `/brainstorm` runs before any project initialization. Each later step runs in its own session (`/new` between steps):
124
+
125
+ ```
126
+ /brainstorm → /new → /new-project (or /init-project) → /new → /discuss-phase 1 → /new → /plan-phase 1 → ...
127
+ ```
128
+
129
+ ## Anti-Patterns — STOP
130
+
131
+ - **Asking multiple questions in one message** — splits the user's attention, lowers answer quality
132
+ - **Pre-deciding before they've answered** — "I'll just assume you mean X" is a failure mode
133
+ - **Skipping the alternatives** — proposing only one approach hides the trade-space
134
+ - **Writing the spec before approval** — the spec records *decisions*, not *proposals*. Get the decision first.
135
+ - **Brainstorming code** — this command is for the design, not the implementation. Resist the urge to start writing.
136
+
137
+ ## Rationalization Table
138
+
139
+ | Excuse | Reality |
140
+ |--------|---------|
141
+ | "It's a simple project, no need to brainstorm" | Simple projects also have ambiguous scope. The gate is fast for simple ones. |
142
+ | "User said 'just build it'" | They'll be unhappier when the wrong thing gets built. Surface the trade-off. |
143
+ | "I already know what they want" | Verify by stating it back and getting confirmation. |
144
+ | "Let's iterate after a first draft" | A first draft in code is more expensive to throw away than a first draft on paper. |
145
+
146
+ ## Output
147
+
148
+ Brainstorming ends with a written spec file in `.planning/specs/`. That file is the artifact. If no file is written, the command did not complete.