@rse/ase 1.0.7 → 2.0.1

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 (279) hide show
  1. package/dst/ase-agent-definition-api.d.ts +184 -0
  2. package/dst/ase-agent-definition-api.js +6 -0
  3. package/dst/ase-agent-definition-builtin/condenser.js +42 -0
  4. package/dst/ase-agent-definition-builtin/editor.js +45 -0
  5. package/dst/ase-agent-definition-builtin/estimator.js +98 -0
  6. package/dst/ase-agent-definition-builtin/implementer.js +121 -0
  7. package/dst/ase-agent-definition-builtin/integrator.js +56 -0
  8. package/dst/ase-agent-definition-builtin/qualifier.js +61 -0
  9. package/dst/ase-agent-definition-builtin/rebooter.js +41 -0
  10. package/dst/ase-agent-definition-builtin/researcher.js +77 -0
  11. package/dst/ase-agent-definition-core.js +827 -0
  12. package/dst/ase-agent-fleet.js +772 -0
  13. package/dst/ase-agent-process.js +232 -0
  14. package/dst/ase-agent-relay-client.js +509 -0
  15. package/dst/ase-agent-relay-core.js +213 -0
  16. package/dst/ase-agent-relay-server-bind.js +242 -0
  17. package/dst/ase-agent-relay-server-cli.js +50 -0
  18. package/dst/ase-agent-runtime-claim.js +189 -0
  19. package/dst/ase-agent-runtime-engine.js +1100 -0
  20. package/dst/ase-agent-runtime-exec.js +275 -0
  21. package/dst/ase-agent-runtime-phase.js +581 -0
  22. package/dst/ase-agent-runtime-request.js +272 -0
  23. package/dst/ase-agent-runtime-tool.js +207 -0
  24. package/dst/ase-agent-runtime.js +1316 -0
  25. package/dst/ase-agent.js +65 -0
  26. package/dst/ase-artifact.js +6 -5
  27. package/dst/ase-config-core.js +465 -0
  28. package/dst/ase-config-schema.js +357 -0
  29. package/dst/ase-config-scope.js +172 -0
  30. package/dst/ase-config.js +25 -585
  31. package/dst/ase-hook.js +228 -111
  32. package/dst/ase-lib-daemon-cli.js +130 -0
  33. package/dst/ase-lib-hash.js +20 -0
  34. package/dst/{ase-log.js → ase-lib-log.js} +40 -7
  35. package/dst/ase-lib-server-bind.js +115 -0
  36. package/dst/ase-lib-server-cli.js +474 -0
  37. package/dst/{ase-table.js → ase-lib-table.js} +1 -1
  38. package/dst/{ase-version.js → ase-lib-version.js} +8 -1
  39. package/dst/ase-man.js +96 -0
  40. package/dst/ase-mcp.js +166 -13
  41. package/dst/{ase-getopt.js → ase-service-getopt.js} +82 -80
  42. package/dst/{ase-markdown.js → ase-service-markdown.js} +18 -11
  43. package/dst/ase-service-otel.js +1246 -0
  44. package/dst/{ase-skills.js → ase-service-skills.js} +29 -64
  45. package/dst/ase-service-state.js +101 -0
  46. package/dst/ase-service.js +269 -81
  47. package/dst/ase-setup-common.js +141 -0
  48. package/dst/ase-setup-mcp.js +359 -0
  49. package/dst/ase-setup-settings.js +837 -0
  50. package/dst/ase-setup.js +113 -869
  51. package/dst/ase-spec.js +31 -19
  52. package/dst/ase-statusline.js +108 -43
  53. package/dst/ase-task-board-core.js +739 -0
  54. package/dst/ase-task-board-filter.js +127 -0
  55. package/dst/ase-task-board-flow.js +237 -0
  56. package/dst/ase-task-board-graph.js +497 -0
  57. package/dst/ase-task-board-stats.js +263 -0
  58. package/dst/ase-task-board-tui-control.js +775 -0
  59. package/dst/ase-task-board-tui-model.js +1008 -0
  60. package/dst/ase-task-board-tui-popup.js +626 -0
  61. package/dst/ase-task-board-tui-style.js +106 -0
  62. package/dst/ase-task-board-tui-view.js +847 -0
  63. package/dst/ase-task-board-tui.js +189 -0
  64. package/dst/ase-task-board-web-client.css +1 -0
  65. package/dst/ase-task-board-web-client.html +20 -0
  66. package/dst/ase-task-board-web-client.js +81 -0
  67. package/dst/ase-task-board-web-server.js +823 -0
  68. package/dst/ase-task-board.js +134 -0
  69. package/dst/ase-task-format.js +757 -0
  70. package/dst/ase-task-request.js +208 -0
  71. package/dst/ase-task-store-client.js +495 -0
  72. package/dst/ase-task-store-core.js +804 -0
  73. package/dst/ase-task-store-issues.js +237 -0
  74. package/dst/ase-task-store-plugin-api.js +6 -0
  75. package/dst/ase-task-store-plugin-ase.js +484 -0
  76. package/dst/ase-task-store-plugin-delegate.js +137 -0
  77. package/dst/ase-task-store-plugin-gitea.js +666 -0
  78. package/dst/ase-task-store-plugin-github.js +696 -0
  79. package/dst/ase-task-store-plugin-gitlab.js +668 -0
  80. package/dst/ase-task-store-server-bind.js +538 -0
  81. package/dst/ase-task-store-server-cli.js +154 -0
  82. package/dst/ase-task.js +1335 -357
  83. package/dst/{ase-compat.js → ase-util-compat.js} +2 -2
  84. package/dst/{ase-diagram.js → ase-util-diagram.js} +107 -32
  85. package/dst/{ase-meta.js → ase-util-meta.js} +2 -2
  86. package/dst/{ase-metric.js → ase-util-metric.js} +2 -2
  87. package/dst/{ase-mint.js → ase-util-mint.js} +19 -12
  88. package/dst/{ase-worktree.js → ase-util-worktree.js} +30 -19
  89. package/dst/ase-util.js +20 -0
  90. package/dst/ase.js +108 -32
  91. package/dst/man/ase-agent-adhoc.1 +515 -0
  92. package/dst/man/ase-agent-condenser.1 +193 -0
  93. package/dst/man/ase-agent-editor.1 +212 -0
  94. package/dst/man/ase-agent-estimator.1 +214 -0
  95. package/dst/man/ase-agent-fleet.1 +185 -0
  96. package/dst/man/ase-agent-implementer.1 +233 -0
  97. package/dst/man/ase-agent-integrator.1 +213 -0
  98. package/dst/man/ase-agent-qualifier.1 +214 -0
  99. package/dst/man/ase-agent-rebooter.1 +193 -0
  100. package/dst/man/ase-agent-relay.1 +128 -0
  101. package/dst/man/ase-agent-researcher.1 +217 -0
  102. package/dst/man/ase-agent.1 +264 -0
  103. package/dst/man/ase-artifact-list.1 +38 -0
  104. package/dst/man/ase-artifact-name.1 +39 -0
  105. package/dst/man/ase-artifact.1 +56 -0
  106. package/dst/man/ase-config-delete.1 +45 -0
  107. package/dst/man/ase-config-edit.1 +48 -0
  108. package/dst/man/ase-config-get.1 +46 -0
  109. package/dst/man/ase-config-init.1 +60 -0
  110. package/dst/man/ase-config-list.1 +42 -0
  111. package/dst/man/ase-config-set.1 +52 -0
  112. package/dst/man/ase-config.1 +231 -0
  113. package/dst/man/ase-hook-permission-request.1 +36 -0
  114. package/dst/man/ase-hook-pre-tool-use.1 +59 -0
  115. package/dst/man/ase-hook-session-end.1 +47 -0
  116. package/dst/man/ase-hook-session-persona.1 +37 -0
  117. package/dst/man/ase-hook-session-start.1 +81 -0
  118. package/dst/man/ase-hook-stop.1 +34 -0
  119. package/dst/man/ase-hook-user-prompt-submit.1 +34 -0
  120. package/dst/man/ase-hook.1 +51 -0
  121. package/dst/man/ase-man.1 +67 -0
  122. package/dst/man/ase-mcp.1 +61 -0
  123. package/dst/man/ase-service-log.1 +43 -0
  124. package/dst/man/ase-service-send.1 +47 -0
  125. package/dst/man/ase-service-start.1 +54 -0
  126. package/dst/man/ase-service-status.1 +46 -0
  127. package/dst/man/ase-service-stop.1 +37 -0
  128. package/dst/man/ase-service.1 +85 -0
  129. package/dst/man/ase-setup-disable.1 +44 -0
  130. package/dst/man/ase-setup-enable.1 +45 -0
  131. package/dst/man/ase-setup-install.1 +73 -0
  132. package/dst/man/ase-setup-mcp.1 +124 -0
  133. package/dst/man/ase-setup-status.1 +60 -0
  134. package/dst/man/ase-setup-statusline.1 +92 -0
  135. package/dst/man/ase-setup-telemetry.1 +92 -0
  136. package/dst/man/ase-setup-uninstall.1 +59 -0
  137. package/dst/man/ase-setup-update.1 +64 -0
  138. package/dst/man/ase-setup.1 +93 -0
  139. package/dst/man/ase-spec-export.1 +62 -0
  140. package/dst/man/ase-spec-lint.1 +40 -0
  141. package/dst/man/ase-spec-preview.1 +40 -0
  142. package/dst/man/ase-spec.1 +46 -0
  143. package/dst/man/ase-statusline.1 +189 -0
  144. package/dst/man/ase-task-assign.1 +71 -0
  145. package/dst/man/ase-task-board.1 +384 -0
  146. package/dst/man/ase-task-delete.1 +35 -0
  147. package/dst/man/ase-task-edit.1 +46 -0
  148. package/dst/man/ase-task-idscheme.1 +65 -0
  149. package/dst/man/ase-task-lifecycle.1 +57 -0
  150. package/dst/man/ase-task-list.1 +47 -0
  151. package/dst/man/ase-task-load.1 +36 -0
  152. package/dst/man/ase-task-newid.1 +61 -0
  153. package/dst/man/ase-task-purge.1 +37 -0
  154. package/dst/man/ase-task-rename.1 +44 -0
  155. package/dst/man/ase-task-request.1 +61 -0
  156. package/dst/man/ase-task-save.1 +48 -0
  157. package/dst/man/ase-task-status.1 +55 -0
  158. package/dst/man/ase-task-store.1 +194 -0
  159. package/dst/man/ase-task-view.1 +40 -0
  160. package/dst/man/ase-task.1 +160 -0
  161. package/dst/man/ase-util-compat.1 +25 -0
  162. package/dst/man/ase-util-diagram.1 +76 -0
  163. package/dst/man/ase-util-meta.1 +45 -0
  164. package/dst/man/ase-util-metric.1 +54 -0
  165. package/dst/man/ase-util-mint.1 +59 -0
  166. package/dst/man/ase-util-worktree.1 +72 -0
  167. package/dst/man/ase-util.1 +50 -0
  168. package/dst/man/ase.1 +124 -0
  169. package/package.json +81 -21
  170. package/plugin/.claude-plugin/plugin.json +1 -1
  171. package/plugin/.codex-plugin/plugin.json +1 -1
  172. package/plugin/.github/plugin/plugin.json +1 -1
  173. package/plugin/agents/ase-meta-diagram.md +12 -8
  174. package/plugin/agents/ase-repo-review.md +322 -0
  175. package/plugin/hooks/hooks-codex.json +5 -0
  176. package/plugin/hooks/hooks-copilot.json +5 -0
  177. package/plugin/hooks/hooks.json +8 -0
  178. package/plugin/meta/ase-common-approach.md +117 -0
  179. package/plugin/meta/ase-common-changeset.md +256 -0
  180. package/plugin/meta/ase-common-code.md +10 -173
  181. package/plugin/meta/ase-common-grill.md +317 -0
  182. package/plugin/meta/ase-common-resolve.md +305 -0
  183. package/plugin/meta/ase-common-task.md +83 -4
  184. package/plugin/meta/ase-constitution.md +0 -2
  185. package/plugin/meta/ase-format-specbook.md +208 -25
  186. package/plugin/meta/ase-format-specbook.yaml +242 -851
  187. package/plugin/meta/ase-format-task.md +669 -125
  188. package/plugin/meta/ase-persona.md +3 -4
  189. package/plugin/meta/ase-skill.md +9 -0
  190. package/plugin/mods/ase-mods.ts +409 -0
  191. package/plugin/mods/claude-code.d.ts +13417 -0
  192. package/plugin/skills/ase-arch-analyze/SKILL.md +1 -1
  193. package/plugin/skills/ase-arch-analyze/help.md +2 -2
  194. package/plugin/skills/ase-code-analyze/SKILL.md +59 -8
  195. package/plugin/skills/ase-code-analyze/help.md +29 -4
  196. package/plugin/skills/ase-code-edit/SKILL.md +107 -181
  197. package/plugin/skills/ase-code-edit/help.md +118 -31
  198. package/plugin/skills/ase-code-lint/SKILL.md +64 -13
  199. package/plugin/skills/ase-code-lint/help.md +32 -2
  200. package/plugin/skills/ase-docs-proofread/SKILL.md +4 -4
  201. package/plugin/skills/ase-docs-proofread/help.md +1 -1
  202. package/plugin/skills/ase-docs-refine/SKILL.md +4 -4
  203. package/plugin/skills/ase-docs-shorten/SKILL.md +4 -4
  204. package/plugin/skills/ase-help-intent/data.md +2164 -1087
  205. package/plugin/skills/ase-help-intent/help.md +1 -1
  206. package/plugin/skills/ase-help-skill/catalog.md +12 -9
  207. package/plugin/skills/ase-meta-brainstorm/SKILL.md +1 -1
  208. package/plugin/skills/ase-meta-config/SKILL.md +3 -4
  209. package/plugin/skills/ase-meta-config/help.md +31 -10
  210. package/plugin/skills/ase-meta-mint/SKILL.md +5 -5
  211. package/plugin/skills/ase-meta-mint/help.md +10 -5
  212. package/plugin/skills/ase-meta-why/help.md +1 -1
  213. package/plugin/skills/ase-meta-workflow/SKILL.md +7 -7
  214. package/plugin/skills/ase-meta-workflow/help.md +4 -4
  215. package/plugin/skills/ase-meta-workflow/sample.md +3 -3
  216. package/plugin/skills/ase-meta-workflow/workflow.txt +22 -18
  217. package/plugin/skills/{ase-meta-changelog → ase-repo-changelog}/SKILL.md +4 -3
  218. package/plugin/skills/{ase-meta-changelog → ase-repo-changelog}/help.md +5 -5
  219. package/plugin/skills/{ase-meta-commit → ase-repo-commit}/SKILL.md +6 -6
  220. package/plugin/skills/{ase-meta-commit → ase-repo-commit}/help.md +5 -5
  221. package/plugin/skills/{ase-meta-diff → ase-repo-diff}/SKILL.md +6 -6
  222. package/plugin/skills/{ase-meta-diff → ase-repo-diff}/help.md +8 -8
  223. package/plugin/skills/{ase-code-dissect → ase-repo-dissect}/SKILL.md +19 -19
  224. package/plugin/skills/{ase-code-dissect → ase-repo-dissect}/help.md +10 -12
  225. package/plugin/skills/ase-repo-merge/SKILL.md +346 -0
  226. package/plugin/skills/ase-repo-merge/help.md +107 -0
  227. package/plugin/skills/ase-repo-resolve/SKILL.md +158 -0
  228. package/plugin/skills/ase-repo-resolve/help.md +102 -0
  229. package/plugin/skills/ase-repo-review/SKILL.md +406 -0
  230. package/plugin/skills/ase-repo-review/help.md +181 -0
  231. package/plugin/skills/ase-spec-edit/SKILL.md +117 -183
  232. package/plugin/skills/ase-spec-edit/help.md +107 -26
  233. package/plugin/skills/ase-sync-reconcile/help.md +1 -1
  234. package/plugin/skills/ase-task-assign/SKILL.md +111 -0
  235. package/plugin/skills/ase-task-assign/help.md +119 -0
  236. package/plugin/skills/ase-task-condense/SKILL.md +21 -21
  237. package/plugin/skills/ase-task-condense/help.md +12 -10
  238. package/plugin/skills/ase-task-delete/SKILL.md +1 -1
  239. package/plugin/skills/ase-task-dissect/SKILL.md +71 -48
  240. package/plugin/skills/ase-task-dissect/help.md +10 -9
  241. package/plugin/skills/ase-task-edit/SKILL.md +379 -94
  242. package/plugin/skills/ase-task-edit/help.md +95 -22
  243. package/plugin/skills/ase-task-estimate/SKILL.md +492 -0
  244. package/plugin/skills/ase-task-estimate/help.md +158 -0
  245. package/plugin/skills/ase-task-grill/SKILL.md +246 -138
  246. package/plugin/skills/ase-task-grill/help.md +129 -26
  247. package/plugin/skills/ase-task-id/SKILL.md +8 -1
  248. package/plugin/skills/ase-task-id/help.md +6 -3
  249. package/plugin/skills/ase-task-implement/SKILL.md +535 -145
  250. package/plugin/skills/ase-task-implement/help.md +138 -47
  251. package/plugin/skills/ase-task-integrate/SKILL.md +549 -0
  252. package/plugin/skills/ase-task-integrate/help.md +187 -0
  253. package/plugin/skills/ase-task-list/SKILL.md +55 -23
  254. package/plugin/skills/ase-task-list/help.md +45 -21
  255. package/plugin/skills/ase-task-reboot/SKILL.md +84 -43
  256. package/plugin/skills/ase-task-reboot/help.md +28 -8
  257. package/plugin/skills/ase-task-rename/SKILL.md +10 -2
  258. package/plugin/skills/ase-task-research/SKILL.md +386 -0
  259. package/plugin/skills/ase-task-research/help.md +102 -0
  260. package/plugin/skills/ase-task-status/SKILL.md +137 -0
  261. package/plugin/skills/ase-task-status/help.md +80 -0
  262. package/plugin/skills/ase-task-view/SKILL.md +49 -24
  263. package/plugin/skills/ase-task-view/help.md +19 -9
  264. package/plugin/agents/ase-meta-review.md +0 -187
  265. package/plugin/skills/ase-code-craft/SKILL.md +0 -264
  266. package/plugin/skills/ase-code-craft/help.md +0 -122
  267. package/plugin/skills/ase-code-refactor/SKILL.md +0 -232
  268. package/plugin/skills/ase-code-refactor/help.md +0 -109
  269. package/plugin/skills/ase-code-resolve/SKILL.md +0 -289
  270. package/plugin/skills/ase-code-resolve/help.md +0 -116
  271. package/plugin/skills/ase-meta-review/SKILL.md +0 -210
  272. package/plugin/skills/ase-meta-review/help.md +0 -96
  273. package/plugin/skills/ase-task-preflight/SKILL.md +0 -166
  274. package/plugin/skills/ase-task-preflight/help.md +0 -82
  275. /package/dst/{ase-ignore.js → ase-lib-ignore.js} +0 -0
  276. /package/dst/{ase-stdio.js → ase-lib-stdio.js} +0 -0
  277. /package/dst/{ase-kv.js → ase-service-kv.js} +0 -0
  278. /package/dst/{ase-sleep.js → ase-service-sleep.js} +0 -0
  279. /package/dst/{ase-timestamp.js → ase-service-timestamp.js} +0 -0
@@ -177,7 +177,9 @@ Discover HTTP clients, flagging any without a release in the last 12 months:
177
177
  [`--security`|`-s`]
178
178
  [`--severity`|`-S`=(`LOW`|`MEDIUM`|`HIGH`)]
179
179
  [`--prefix`|`-P` *prefix*]
180
- *source-reference*
180
+ [`--staged`]
181
+ [`--unstaged`]
182
+ [*source-reference*]
181
183
 
182
184
  ## DESCRIPTION
183
185
 
@@ -213,19 +215,29 @@ under *distinct* prefixes coexist instead of overwriting each other.
213
215
  Without the option (the default), ids stay unprefixed and the purge
214
216
  covers the *entire* `ase-issue-*` space, including any prefixed results.
215
217
 
218
+ The `--staged` option restricts the analysis to the source files with
219
+ *staged* Git changes, and the `--unstaged` option restricts it to the
220
+ source files with *unstaged* Git changes plus the *untracked* source
221
+ files. Deleted files are skipped, and the files are analyzed in their
222
+ current working copy state. With a *source-reference*, only the changed
223
+ files within it are analyzed; without one, all changed files of the
224
+ repository are analyzed. If no such file exists, nothing is analyzed.
225
+ Both options can be combined to analyze the source files with *any*
226
+ uncommitted Git changes.
227
+
216
228
  The skill investigates the code base silently, reports each detected
217
229
  problem as a `PROBLEM` entry with severity (`LOW`, `MEDIUM`, `HIGH`) and
218
230
  inline file/line references (in the performance lens, each entry
219
231
  additionally carries an *evidence* and a *trade-off* line), and persists
220
232
  results in the `ase` MCP key/value store as `ase-issue-P<n>` entries so
221
- they can later be resolved via `ase-code-resolve P<n>` or directly
233
+ they can later be planned via `ase-task-edit P<n>` or directly
222
234
  fixed via `ase-code-edit P<n>`.
223
235
 
224
236
  ## ARGUMENTS
225
237
 
226
238
  - *source-reference*:
227
239
  A file, directory, function, or other reference to the source code
228
- to analyze.
240
+ to analyze. Optional only under `--staged` or `--unstaged`.
229
241
 
230
242
  ## SCENARIOS
231
243
 
@@ -234,6 +246,7 @@ fixed via `ase-code-edit P<n>`.
234
246
  - You want performance and efficiency opportunities surfaced
235
247
  - You want a security-focused inspection of your code
236
248
  - You want problems persisted as issue ids like `P1` for later resolving
249
+ - You want only your staged or unstaged changes analyzed before committing
237
250
 
238
251
  ## EXAMPLES
239
252
 
@@ -273,250 +286,16 @@ Analyze a directory under its own id namespace, yielding `auth-P1`, `auth-P2`, .
273
286
  ❯ /ase-code-analyze --prefix auth src/auth/
274
287
  ```
275
288
 
276
- </purpose>
277
- <purpose name="ase-code-craft">
278
-
279
- ## NAME
280
-
281
- `ase-code-craft` - Craft Source Code
282
-
283
- ## SYNOPSIS
284
-
285
- `ase-code-craft`
286
- [`--help`|`-h`]
287
- [`--auto`|`-a`]
288
- [`--dry`|`-d`]
289
- [`--direct`|`-D`]
290
- [`--interactive`|`-i`]
291
- [`--quick`|`-Q`]
292
- [`--next`|`-n` *option*[,...]]
293
- [*task-id*:] *feature*
294
-
295
- ## DESCRIPTION
296
-
297
- The `ase-code-craft` skill crafts a *new feature* from scratch by
298
- investigating the existing code base, internalizing crafting tenets
299
- (KISS, YAGNI, DRY, SRP, loose coupling, ...), proposing one or more
300
- *feature approaches* with pros and cons, letting the user pick the
301
- preferred approach, and composing a corresponding *task plan* aligned
302
- with the existing architecture.
303
-
304
- By default the skill does *not* directly modify source files. It
305
- persists the plan via `ase_task_save` and then hands off to
306
- `ase-task-edit`, `ase-task-preflight`, or `ase-task-implement`, as
307
- selected by `--next`. Only under `--direct` it skips the plan
308
- entirely and applies the change set to the affected artifacts itself.
309
-
310
- ## OPTIONS
311
-
312
- - `--auto`|`-a`:
313
- Automatically pick the recommended feature approach without
314
- asking the user via the interactive dialog.
315
-
316
- - `--dry`|`-d`:
317
- Compose the plan *without* the `## VERIFICATION` section. When
318
- `ase-task-implement` later applies such a plan, it strictly skips
319
- the entire verification phase (no build, tests, linter,
320
- type-checker, or program execution) once the source files have
321
- been modified.
322
-
323
- - `--direct`|`-D`:
324
- Craft the feature *immediately* and *in place*: skip the
325
- feature approaches, the interactive dialog, and the entire task
326
- plan ceremony, and directly apply the complete change set to the
327
- affected artifacts, including a corresponding entry in an existing
328
- `CHANGELOG.md` file. In this mode `--auto`, `--dry`, `--quick`, and
329
- `--next` have no effect, as neither approaches are proposed nor a
330
- plan is composed.
331
-
332
- - `--interactive`|`-i`:
333
- Craft *interactively*: implies `--direct` and, once the initial
334
- *feature* has been applied, repeatedly asks for the *next change*
335
- with a free-text dialog and immediately applies it in place, too,
336
- until the user stops the loop by answering `DONE`.
337
-
338
- - `--quick`|`-Q`:
339
- Shorthand alias for `-a -d -n IMPLEMENT,DELETE`: automatically pick
340
- the recommended feature approach, compose the plan *without* the
341
- `## VERIFICATION` section, immediately hand off to `ase-task-implement`,
342
- and finally `ase-task-delete` the now-consumed plan. This gives a
343
- single, fast *one-shot* crafting mode.
344
-
345
- - `--next`|`-n` *option*[,...]:
346
- Automatically choose the next step after composing the plan.
347
- *option* is a single token or a *comma-separated chronological
348
- list* of tokens; an `IMPLEMENT`, `PREFLIGHT`, or `GRILL` head token
349
- is consumed by this skill (bypassing `ase-task-edit`), and any
350
- remaining tokens are *forwarded* (via `--next`) to the downstream
351
- skill. For all other head tokens, the *entire* list is forwarded
352
- to `ase-task-edit`, which consumes its head itself. This lets an
353
- entire pipeline be pre-scripted in one shot. Recognized tokens at
354
- this skill: `none` (default, hand off to `ase-task-edit`
355
- interactively), `DONE` (stop), `EDIT` (hand off to
356
- `ase-task-edit`), `GRILL` (hand off to `ase-task-grill`),
357
- `PREFLIGHT` (hand off to `ase-task-preflight`),
358
- or `IMPLEMENT` (hand off to `ase-task-implement`). Example:
359
- `--next PREFLIGHT,IMPLEMENT,DONE` crafts the plan, preflights it,
360
- implements it, and exits without further dialog.
361
-
362
- ## ARGUMENTS
363
-
364
- - [*task-id*:] *feature*:
365
- Description of the *feature* to craft. Optionally prefixed with
366
- a *task-id* followed by a colon to bind the resulting plan to
367
- a specific task id.
368
-
369
- ## SCENARIOS
370
-
371
- - You want to add a new feature to the code base
372
- - You want feature approaches with pros and cons before any code changes
373
- - You want a task plan composed for building something new
374
- - You want a fast one-shot crafting without any plan ceremony
375
-
376
- ## EXAMPLES
377
-
378
- Craft a new logging feature:
379
-
380
- ```text
381
- ❯ /ase-code-craft add structured JSON logging with log levels
382
- ```
383
-
384
- Craft a feature under a named task and directly hand off to implementation:
385
-
386
- ```text
387
- ❯ /ase-code-craft --next IMPLEMENT auth: add JWT authentication middleware
388
- ```
389
-
390
- Craft interactively, applying one change after the other in place:
391
-
392
- ```text
393
- ❯ /ase-code-craft -i add a --verbose option to the CLI
394
- ```
395
-
396
- </purpose>
397
- <purpose name="ase-code-dissect">
398
-
399
- ## NAME
400
-
401
- `ase-code-dissect` - Dissect a Change Set
402
-
403
- ## SYNOPSIS
404
-
405
- `ase-code-dissect`
406
- [`--help`|`-h`]
407
- [`--max-parts`|`-m` *count*]
408
- [`--staged`|`-s`]
409
- [`--dry`|`-d`]
410
- [`--force`|`-f`]
411
- [*dissect-hint*]
412
-
413
- ## DESCRIPTION
414
-
415
- The `ase-code-dissect` skill treats the current Git change set as an
416
- *epic* and *dissects* it domain-wise and logically into *cohesive
417
- parts*. Each part is a self-contained unit of change with a single
418
- coherent purpose, so it can be reviewed and committed *atomically* and
419
- *independently* of the others.
420
-
421
- The change set is captured from the working copy (`git diff`), with
422
- untracked files folded in *read-only*, or -- under `--staged`/`-s` --
423
- from the Git index (`git diff --cached HEAD`). The dissection follows a
424
- strict ruleset: at least *2* and at most *count* parts are derived,
425
- *every* hunk is assigned to *exactly one* part, mutually dependent hunks
426
- are kept together, all hunks of one file normally stay in the same part,
427
- and nothing beyond the actual change set is invented. The cut follows
428
- the *semantics* of the change, not its technical structure -- a split by
429
- file, directory, or technical layer is usually *not* the intended one.
430
- If the change set carries only a single cohesive purpose, it is reported
431
- as *not dissectable* and nothing is created.
432
-
433
- An optional *dissect-hint* steers *how* the change set is split -- which
434
- changes belong together, along which axis to cut, or how many parts to
435
- aim at. It is especially useful after a `--dry` run showed an unintended
436
- dissection. The hint overrides the default grouping, but never the
437
- ruleset itself.
438
-
439
- The derived parts are first reported as a *dissection table* (part
440
- number, worktree id, scope, and rationale). Then -- unless `--dry` is
441
- given -- each part's patch is written to a temporary file and applied
442
- inside a *fresh Git WorkTree* `.ase/worktree/<project-id>-<feature-slug>`,
443
- whose branch carries the same name and is created from `HEAD`. If a
444
- `CHANGELOG.md` file exists, a matching entry summarizing that part is
445
- added *inside* the worktree.
446
-
447
- Every part stays *uncommitted*, a failing `git apply` is reported for
448
- that part while the remaining parts continue, and the *original working
449
- copy is never mutated*.
450
-
451
- Note that the working-copy patch (without `--staged`) is taken relative
452
- to the Git *index* while the worktrees are created from `HEAD`. So if
453
- changes are *also* staged, the affected part patches may not apply
454
- cleanly and are then reported as failed; stage everything and use
455
- `--staged` in that situation.
456
-
457
- ## OPTIONS
458
-
459
- - `--max-parts`|`-m` *count*:
460
- Upper bound for the number of derived parts (default: `8`). The
461
- lower bound is always `2`, because fewer parts are no dissection.
462
-
463
- - `--staged`|`-s`:
464
- Dissect the *staged* changes (the Git index against `HEAD`) instead
465
- of the working copy changes. Untracked files are then *not* folded
466
- in, because they are by definition not part of the index.
467
-
468
- - `--dry`|`-d`:
469
- *Report only* -- print the dissection table but create *no*
470
- artifacts at all, so the decision stays fully reversible. Note that
471
- this meaning differs from `--dry`/`-d` in `ase-code-craft`, where it
472
- instead omits the `## VERIFICATION` section of the composed plan.
473
-
474
- - `--force`|`-f`:
475
- Remove and re-create already existing worktrees and branches of the
476
- derived names. Without this option, the skill detects colliding
477
- targets *before* writing anything, reports them, and stops with
478
- status *targets exist*.
479
-
480
- ## ARGUMENTS
481
-
482
- - *dissect-hint*:
483
- A free-text hint telling *how* the change set should be split. If
484
- omitted, the parts are derived from the change set alone.
485
-
486
- The worktree names are *not* argument-driven: they are always derived
487
- from the *current* project id and the per-part feature slug.
488
-
489
- ## SCENARIOS
490
-
491
- - You want a large uncommitted change set split into atomic parts
492
- - You want each cohesive part of a diff in its own Git worktree
493
- - You want mixed-up changes untangled before committing them
494
- - You want a preview of how a change set would be divided
495
-
496
- ## EXAMPLES
497
-
498
- Dissect the current working copy changes:
499
-
500
- ```text
501
- ❯ /ase-code-dissect
502
- ```
503
-
504
- Preview the dissection of the staged changes into at most four parts:
505
-
506
- ```text
507
- ❯ /ase-code-dissect --staged --dry --max-parts 4
508
- ```
509
-
510
- Re-dissect the changes, re-creating the previously created worktrees:
289
+ Analyze only the source files with staged Git changes:
511
290
 
512
291
  ```text
513
- ❯ /ase-code-dissect --force
292
+ ❯ /ase-code-analyze --staged
514
293
  ```
515
294
 
516
- Dissect the changes along an explicitly given axis:
295
+ Analyze only the unstaged and untracked source files below a directory:
517
296
 
518
297
  ```text
519
- ❯ /ase-code-dissect keep the plugin and tool changes in separate parts
298
+ ❯ /ase-code-analyze --unstaged src/handlers/
520
299
  ```
521
300
 
522
301
  </purpose>
@@ -531,19 +310,23 @@ Dissect the changes along an explicitly given axis:
531
310
  `ase-code-edit`
532
311
  [`--help`|`-h`]
533
312
  [`--mode`|`-m` `auto`|`craft`|`refactor`|`resolve`]
313
+ [`--approach`|`-a`]
534
314
  [`--grill`|`-g`]
535
315
  [`--grill-rounds`|`-r` *n*]
316
+ [`--grill-until`|`-u` `MUST`|`SHOULD`|`MAY`]
317
+ [`--grill-perspective`|`-p` *perspective*]
318
+ [`--grill-ground`|`-G`]
536
319
  [`--verify`|`-v`]
537
- [`--worktree`|`-w`]
320
+ [`--worktree`|`-w` *name*[`:`*branch*]]
538
321
  [`--loop`|`-l`]
539
322
  [*query*]
540
323
 
541
324
  ## DESCRIPTION
542
325
 
543
326
  The `ase-code-edit` skill edits the code base *directly* from a *query*,
544
- in one shot and without any task plan ceremony. It is a *plan-less*
545
- fusion of `ase-code-craft`, `ase-code-refactor`, `ase-code-resolve`,
546
- `ase-task-grill`, and `ase-task-implement`.
327
+ in one shot and without any task plan ceremony. It is the *plan-less*
328
+ counterpart of `ase-task-edit`, `ase-task-grill`, and
329
+ `ase-task-implement`, covering crafting, refactoring, and resolving.
547
330
 
548
331
  Each single-shot run (or each `--loop` iteration) walks through five
549
332
  states: *querying* (take the *query* argument or ask for a query via an
@@ -551,11 +334,12 @@ interactive `Edit Query` dialog, and
551
334
  split it into its domain-specific WHAT and its implementation-detail HOW
552
335
  parts), *discovering* (read the source artifacts related to the query),
553
336
  *grilling* (optionally stress-test the query with rounds of questions),
554
- *implementing* (apply the change set in place, honoring the tenet set
555
- selected via `--mode`), and *verifying* (optionally verify the
556
- implementation until it passes). The *querying* state and every
557
- *grilling* round close with an `EDIT TODO` box showing the established
558
- `WHAT` and `HOW` information.
337
+ *implementing* (optionally select an approach, then apply the change
338
+ set in place, honoring the tenet set selected via `--mode`), and
339
+ *verifying* (optionally verify the implementation until it passes). The
340
+ *querying* state, every *grilling* round, and the approach selection
341
+ close with an `EDIT TODO` box showing the established `WHAT` and `HOW`
342
+ information.
559
343
 
560
344
  ## OPTIONS
561
345
 
@@ -564,6 +348,15 @@ implementation until it passes). The *querying* state and every
564
348
  (CRAFTING), `refactor` (REFACTORING), or `resolve` (RESOLVING).
565
349
  The default `auto` infers the tenet set from the query itself.
566
350
 
351
+ - `--approach`|`-a`:
352
+ Before applying the change set, propose one or more crafting,
353
+ refactoring, or resolution approaches with pros and cons, recommend
354
+ one of them, and let the user pick the preferred one via an
355
+ interactive dialog (or, under the `black` project boxing or in
356
+ headless mode, automatically pick the recommended one). The chosen
357
+ approach is merged into the HOW part of the query. Without
358
+ `--approach`, no approaches are determined at all.
359
+
567
360
  - `--grill`|`-g`:
568
361
  Grill the query before implementing, similar to `ase-task-grill`:
569
362
  raise 1-10 questions per round which resolve the open points of the
@@ -571,31 +364,73 @@ implementation until it passes). The *querying* state and every
571
364
  (domain-specifics, must be clarified), `INTERFACE` (externally
572
365
  observable behavior or UI/API interfaces, must be clarified),
573
366
  `ARCHITECTURE` (structure, wiring, placement, or dependencies,
574
- should be clarified), or `IMPLEMENTATION` (inner technical details,
575
- can be clarified) -- and a 1-2 word `TOPIC` hint. The questions of a
576
- round are sorted by descending focus area importance (`DOMAIN`,
577
- `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`).
367
+ should be clarified), `IMPLEMENTATION` (inner technical details,
368
+ can be clarified), `REGRESSION` (what must not break, should be
369
+ clarified), or `CONFIRMATION` (what proves the specified behavior,
370
+ should be clarified) -- and a 1-2 word `TOPIC` hint. The questions
371
+ of a round are sorted by descending focus area importance
372
+ (`DOMAIN`, `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`,
373
+ `REGRESSION`, `CONFIRMATION`). Questions of focus area
374
+ `REGRESSION` and `CONFIRMATION` are raised only together with
375
+ `--verify`, as only then a verification honors their decisions.
578
376
  All questions of a round are announced together below a
579
- `GRILLING ROUND K/L` line (the announcement line and round numbering
580
- are omitted when only a single round is performed) as an
581
- `#`/`FOCUS ▶ TOPIC`/`QUESTION` table with one row per
582
- question, each row carrying two to four grounded answer alternatives
583
- (with the alternative reflecting the current understanding marked as
584
- `CURRENT`). They are then asked in *one* batch via a single
377
+ `GRILLING ROUND K/L` line (the round numbering is omitted when only
378
+ a single round is performed) as a `QUESTION`/`ANSWERS` table with
379
+ one row per question, each row carrying two to three grounded answer
380
+ alternatives (with the alternative reflecting the current understanding
381
+ marked with `⚑`). They are then asked in *one* batch via a single
585
382
  interactive dialog titled `GRILLING ROUND K/L` (or plain `GRILLING`
586
383
  for a single round), whose question asks for the combined answer to
587
384
  all (or a subset) of the listed aspect questions and whose only
588
385
  answer options are the fixed `STOP SKILL` (stop the skill) and
589
386
  `SKIP GRILLING` (skip the remaining grilling) ones, plus free-text
590
- input. The answers are
387
+ input. The questions are numbered `1`, `2`, etc. and their answer
388
+ alternatives are lettered `A`, `B`, etc., so the free-text input can
389
+ cherry-pick answers with short responses matching `\d+[a-zA-Z]`
390
+ (like `1A 2c`), freely mixed with keyword text. The answers are
591
391
  merged back into the WHAT and HOW parts of the query. Without
592
392
  `--grill`, no questions are asked at all.
593
393
 
594
394
  - `--grill-rounds`|`-r` *n*:
595
- The number of grill rounds to apply (default: `1`). Each round
596
- starts from scratch from only the current WHAT and HOW parts,
395
+ The *maximum* number of grill rounds to apply (default: `1`). Each
396
+ round starts from scratch from only the current WHAT and HOW parts,
597
397
  forgetting all information of previous rounds, and closes with an
598
- `EDIT TODO` box. Only effective together with `--grill`.
398
+ `EDIT TODO` box. The grilling stops early -- announced by a
399
+ `grilling finished early` status line -- once a round, even the
400
+ first one, finds the open points clear enough according to
401
+ `--grill-until`. Only effective together with `--grill`.
402
+
403
+ - `--grill-until`|`-u` `MUST`|`SHOULD`|`MAY`:
404
+ Grill until at least all open points of the given severity or
405
+ higher are clear (default: `MUST`), where the severity follows from
406
+ the focus area: `MUST` (`DOMAIN`, `INTERFACE`), `SHOULD`
407
+ (`ARCHITECTURE`, `REGRESSION`, `CONFIRMATION`), and `MAY`
408
+ (`IMPLEMENTATION`). Independent of this, every open point is rated
409
+ with an individual impact (`HIGH`, `MEDIUM`, or `LOW`), which
410
+ decides which points are raised as questions and in which order
411
+ within a focus area. Only effective together with `--grill`.
412
+
413
+ - `--grill-perspective`|`-p` *perspective*:
414
+ Grill exclusively from the logical *perspective* -- a keyword or
415
+ short hint like `domain`, `performance`, or `security`. The
416
+ perspective acts as an exclusive lens: only open points relevant from
417
+ this perspective are raised as questions, while every question still
418
+ carries its focus area, severity, and impact. The active perspective
419
+ is shown in the announcement line, like `GRILLING (security)`.
420
+ Without a perspective, the grilling is holistic. Only effective together with `--grill`.
421
+
422
+ - `--grill-ground`|`-G`:
423
+ Ground the grilling in facts instead of the world knowledge of the
424
+ model alone: once before the first round, the artifacts of all kinds
425
+ (`SPEC`, `CODE`, `DOCS`, `INFR`, and `OTHR`) are scanned for
426
+ the project facts relevant to the grilled subject (from the given
427
+ perspective, if any) and the Internet/Web is searched for the
428
+ established practices, standards, patterns, and pitfalls about it.
429
+ These facts serve all rounds, both for raising the questions and for
430
+ preferably deriving their answer alternatives. The grounding is shown
431
+ in the announcement line, like `GRILLING (security, grounded)`. If
432
+ no usable facts are found, a warning is shown and the grilling falls
433
+ back to model knowledge. Only effective together with `--grill`.
599
434
 
600
435
  - `--verify`|`-v`:
601
436
  Verify whether the implementation fulfills the requirements, by
@@ -604,12 +439,21 @@ implementation until it passes). The *querying* state and every
604
439
  until the verification passes. Without `--verify`, strictly no
605
440
  verification is performed at all.
606
441
 
607
- - `--worktree`|`-w`:
608
- Apply the change sets inside a dedicated Git worktree (as
609
- `ase-task-implement --worktree`) instead of the current working
610
- copy. One single worktree, named by a two-word id derived from the
611
- first query, serves the whole skill run: all `--loop` iterations
612
- land in it and it is left uncommitted for review.
442
+ - `--worktree`|`-w` *name*[`:`*branch*]:
443
+ Apply the change sets inside the dedicated Git worktree
444
+ `.ase/worktree/<name>` instead of the current working copy. The
445
+ worktree is *reused* if it already exists -- then switched to
446
+ *branch* if given and it has no uncommitted changes --, otherwise
447
+ it is *created* with the branch *branch* (default: *name*),
448
+ checked out if it exists or created from `HEAD` otherwise. One
449
+ single worktree serves the whole skill run: it is prepared before
450
+ the first discovery, so discovering, grilling, and implementing all
451
+ operate on it, all `--loop` iterations land in it, and it is left
452
+ uncommitted for review. If
453
+ *name* is a bare lower-case word naming no existing worktree and a
454
+ *query* follows (like `-w fix the crash`, a former boolean `-w`
455
+ usage), the skill asks whether *name* is the worktree name or the
456
+ first query word.
613
457
 
614
458
  - `--loop`|`-l`:
615
459
  Loop the whole state cycle: after each iteration, ask for the next
@@ -630,6 +474,7 @@ implementation until it passes). The *querying* state and every
630
474
  - You want an analyzer issue like `P1` fixed directly without a plan
631
475
  - You want a quick change with optional grilling and verification
632
476
  - You want several edits chained in a loop, optionally in a worktree
477
+ - You want the change set to land on a specific Git branch or worktree
633
478
 
634
479
  ## EXAMPLES
635
480
 
@@ -645,10 +490,31 @@ Grill the query with two rounds first, then implement and verify:
645
490
  ❯ /ase-code-edit -g -r 2 -v refactor the config loading into layers
646
491
  ```
647
492
 
493
+ Let the user pick one of several resolution approaches first, then
494
+ implement:
495
+
496
+ ```text
497
+ ❯ /ase-code-edit -a fix race condition in cache invalidation
498
+ ```
499
+
500
+ Grill the query exclusively from the security perspective, grounded in
501
+ the project artifacts and the Internet/Web, then implement:
502
+
503
+ ```text
504
+ ❯ /ase-code-edit -g -p security -G add a file upload endpoint to the API
505
+ ```
506
+
648
507
  Loop over multiple edits inside a dedicated Git worktree:
649
508
 
650
509
  ```text
651
- ❯ /ase-code-edit -l -w
510
+ ❯ /ase-code-edit -l -w config-layers
511
+ ```
512
+
513
+ Edit inside the dedicated Git worktree `.ase/worktree/verbose` on the
514
+ branch `feature-verbose`:
515
+
516
+ ```text
517
+ ❯ /ase-code-edit -w verbose:feature-verbose add a --verbose option to the CLI
652
518
  ```
653
519
 
654
520
  </purpose>
@@ -764,7 +630,9 @@ Get insights into a specific subsystem:
764
630
  [`--severity`|`-S`=(`LOW`|`MEDIUM`|`HIGH`)]
765
631
  [`--include`|`-i`=*aspect*[`,`...]]
766
632
  [`--exclude`|`-e`=*aspect*[`,`...]]
767
- *source-reference*
633
+ [`--staged`]
634
+ [`--unstaged`]
635
+ [*source-reference*]
768
636
 
769
637
  ## DESCRIPTION
770
638
 
@@ -829,10 +697,25 @@ the code, and comments contradicting the code.
829
697
  code quality aspects. Applied *after* `--include`, so
830
698
  `-i A01,A02 -e A02` checks `A01` only.
831
699
 
700
+ - `--staged`:
701
+ Restrict the linting to the source files with *staged* Git changes.
702
+ Deleted files are skipped, and the files are linted in their current
703
+ working copy state. Combined with `--unstaged`, lint the source
704
+ files with *any* uncommitted Git changes.
705
+
706
+ - `--unstaged`:
707
+ Restrict the linting to the source files with *unstaged* Git changes
708
+ plus the *untracked* source files. Deleted files are skipped.
709
+ Combined with `--staged`, lint the source files with *any*
710
+ uncommitted Git changes.
711
+
832
712
  ## ARGUMENTS
833
713
 
834
714
  - *source-reference*:
835
715
  A file, directory, or other reference to the source code to lint.
716
+ Optional only under `--staged` or `--unstaged`: with it, only the
717
+ changed files within it are linted; without it, all changed files
718
+ of the repository are linted.
836
719
 
837
720
  ## SCENARIOS
838
721
 
@@ -841,6 +724,7 @@ the code, and comments contradicting the code.
841
724
  - You want all quality corrections applied automatically
842
725
  - You want only specific quality aspects like formatting or spelling checked
843
726
  - You want missing or excessive code documentation flagged
727
+ - You want only your staged or unstaged changes linted before committing
844
728
 
845
729
  ## EXAMPLES
846
730
 
@@ -880,224 +764,16 @@ Lint a directory for the documentation aspect only:
880
764
  ❯ /ase-code-lint -i A21 src/handlers/
881
765
  ```
882
766
 
883
- </purpose>
884
- <purpose name="ase-code-refactor">
885
-
886
- ## NAME
887
-
888
- `ase-code-refactor` - Refactor Artifacts
889
-
890
- ## SYNOPSIS
891
-
892
- `ase-code-refactor`
893
- [`--help`|`-h`]
894
- [`--auto`|`-a`]
895
- [`--dry`|`-d`]
896
- [`--direct`|`-D`]
897
- [`--quick`|`-Q`]
898
- [`--next`|`-n` *option*[,...]]
899
- [*task-id*:] *request*
900
-
901
- ## DESCRIPTION
902
-
903
- The `ase-code-refactor` skill refactors existing artifacts by
904
- investigating the related code, internalizing refactoring tenets
905
- (Behavior Preservation, Boy Scout Rule, DRY, SRP, loose coupling,
906
- clear interfaces, ...), proposing one or more *refactoring approaches*
907
- with pros and cons, letting the user pick the preferred approach,
908
- and composing a corresponding *task plan*.
909
-
910
- By default the skill does *not* directly modify source files. It
911
- persists the plan via `ase_task_save` and then hands off to
912
- `ase-task-edit`, `ase-task-preflight`, or `ase-task-implement`, as
913
- selected by `--next`. Only under `--direct` it skips the plan
914
- entirely and applies the change set to the affected artifacts itself.
915
-
916
- ## OPTIONS
917
-
918
- - `--auto`|`-a`:
919
- Automatically pick the recommended refactoring approach without
920
- asking the user via the interactive dialog.
921
-
922
- - `--dry`|`-d`:
923
- Compose the plan *without* the `## VERIFICATION` section. When
924
- `ase-task-implement` later applies such a plan, it strictly skips
925
- the entire verification phase (no build, tests, linter,
926
- type-checker, or program execution) once the source files have
927
- been modified.
928
-
929
- - `--direct`|`-D`:
930
- Apply the refactoring *immediately* and *in place*: skip the
931
- refactoring approaches, the interactive dialog, and the entire task
932
- plan ceremony, and directly apply the complete change set to the
933
- affected artifacts, including a corresponding entry in an existing
934
- `CHANGELOG.md` file. In this mode `--auto`, `--dry`, `--quick`, and
935
- `--next` have no effect, as neither approaches are proposed nor a
936
- plan is composed.
937
-
938
- - `--quick`|`-Q`:
939
- Shorthand alias for `-a -d -n IMPLEMENT,DELETE`: automatically pick
940
- the recommended refactoring approach, compose the plan *without* the
941
- `## VERIFICATION` section, immediately hand off to `ase-task-implement`,
942
- and finally `ase-task-delete` the now-consumed plan. This gives a
943
- single, fast *one-shot* refactoring mode.
944
-
945
- - `--next`|`-n` *option*[,...]:
946
- Automatically choose the next step after composing the plan.
947
- *option* is a single token or a *comma-separated chronological
948
- list* of tokens; an `IMPLEMENT`, `PREFLIGHT`, or `GRILL` head token
949
- is consumed by this skill (bypassing `ase-task-edit`), and any
950
- remaining tokens are *forwarded* (via `--next`) to the downstream
951
- skill. For all other head tokens, the *entire* list is forwarded
952
- to `ase-task-edit`, which consumes its head itself. This lets an
953
- entire pipeline be pre-scripted in one shot. Recognized tokens at
954
- this skill: `none` (default, hand off to `ase-task-edit`
955
- interactively), `DONE` (stop), `EDIT` (hand off to
956
- `ase-task-edit`), `GRILL` (hand off to `ase-task-grill`),
957
- `PREFLIGHT` (hand off to `ase-task-preflight`),
958
- or `IMPLEMENT` (hand off to `ase-task-implement`). Example:
959
- `--next PREFLIGHT,IMPLEMENT,DONE` refactors, preflights, implements,
960
- and exits without further dialog.
961
-
962
- ## ARGUMENTS
963
-
964
- - [*task-id*:] *request*:
965
- Description of the refactoring *request*. Optionally prefixed
966
- with a *task-id* followed by a colon to bind the resulting plan
967
- to a specific task id.
968
-
969
- ## SCENARIOS
970
-
971
- - You want existing code restructured without changing its behavior
972
- - You want refactoring approaches with pros and cons before any changes
973
- - You want a task plan composed for a cleanup
974
- - You want a one-shot refactoring applied directly in place
975
-
976
- ## EXAMPLES
977
-
978
- Refactor a module into smaller files:
979
-
980
- ```text
981
- ❯ /ase-code-refactor split src/handlers.ts into per-route modules
982
- ```
983
-
984
- Refactor under a named task and directly hand off to implementation:
985
-
986
- ```text
987
- ❯ /ase-code-refactor --next IMPLEMENT cleanup: extract HTTP client into its own class
988
- ```
989
-
990
- </purpose>
991
- <purpose name="ase-code-resolve">
992
-
993
- ## NAME
994
-
995
- `ase-code-resolve` - Resolve Problem
996
-
997
- ## SYNOPSIS
998
-
999
- `ase-code-resolve`
1000
- [`--help`|`-h`]
1001
- [`--auto`|`-a`]
1002
- [`--dry`|`-d`]
1003
- [`--direct`|`-D`]
1004
- [`--quick`|`-Q`]
1005
- [`--next`|`-n` *option*[,...]]
1006
- [*task-id*:] *problem*
1007
-
1008
- ## DESCRIPTION
1009
-
1010
- The `ase-code-resolve` skill resolves a *bug* or *problem* by
1011
- investigating the related code, internalizing resolution tenets
1012
- (Surgical Changes, No Cleanups, Minimum Flags, Code Adequacy, Origin
1013
- Proximity, ...), proposing one or more *resolution approaches* with
1014
- pros and cons, letting the user pick the preferred approach, and
1015
- composing a corresponding *task plan*.
1016
-
1017
- The *problem* may also be given as a bare issue identifier (e.g. `P1`
1018
- or `T1`) previously produced by `ase-code-analyze` or
1019
- `ase-arch-analyze` and persisted in the `ase` MCP key/value store
1020
- under `ase-issue-<id>`.
1021
-
1022
- By default the skill does *not* directly modify source files. It
1023
- persists the plan via `ase_task_save` and then hands off to
1024
- `ase-task-edit`, `ase-task-preflight`, or `ase-task-implement`, as
1025
- selected by `--next`. Only under `--direct` it skips the plan
1026
- entirely and applies the change set to the affected artifacts itself.
1027
-
1028
- ## OPTIONS
1029
-
1030
- - `--auto`|`-a`:
1031
- Automatically pick the recommended resolution approach without
1032
- asking the user via the interactive dialog.
1033
-
1034
- - `--dry`|`-d`:
1035
- Compose the plan *without* the `## VERIFICATION` section. When
1036
- `ase-task-implement` later applies such a plan, it strictly skips
1037
- the entire verification phase (no build, tests, linter,
1038
- type-checker, or program execution) once the source files have
1039
- been modified.
1040
-
1041
- - `--direct`|`-D`:
1042
- Resolve the problem *immediately* and *in place*: skip the
1043
- resolution approaches, the interactive dialog, and the entire task
1044
- plan ceremony, and directly apply the complete change set to the
1045
- affected artifacts, including a corresponding entry in an existing
1046
- `CHANGELOG.md` file. In this mode `--auto`, `--dry`, `--quick`, and
1047
- `--next` have no effect, as neither approaches are proposed nor a
1048
- plan is composed.
1049
-
1050
- - `--quick`|`-Q`:
1051
- Shorthand alias for `-a -d -n IMPLEMENT,DELETE`: automatically pick
1052
- the recommended resolution approach, compose the plan *without* the
1053
- `## VERIFICATION` section, immediately hand off to `ase-task-implement`,
1054
- and finally `ase-task-delete` the now-consumed plan. This gives a
1055
- single, fast *one-shot* resolution mode.
1056
-
1057
- - `--next`|`-n` *option*[,...]:
1058
- Automatically choose the next step after composing the plan.
1059
- *option* is a single token or a *comma-separated chronological
1060
- list* of tokens; an `IMPLEMENT`, `PREFLIGHT`, or `GRILL` head token
1061
- is consumed by this skill (bypassing `ase-task-edit`), and any
1062
- remaining tokens are *forwarded* (via `--next`) to the downstream
1063
- skill. For all other head tokens, the *entire* list is forwarded
1064
- to `ase-task-edit`, which consumes its head itself. This lets an
1065
- entire pipeline be pre-scripted in one shot. Recognized tokens at
1066
- this skill: `none` (default, hand off to `ase-task-edit`
1067
- interactively), `DONE` (stop), `EDIT` (hand off to
1068
- `ase-task-edit`), `GRILL` (hand off to `ase-task-grill`),
1069
- `PREFLIGHT` (hand off to `ase-task-preflight`),
1070
- or `IMPLEMENT` (hand off to `ase-task-implement`). Example:
1071
- `--next IMPLEMENT,DONE` resolves the problem, implements it, and
1072
- exits without further dialog.
1073
-
1074
- ## ARGUMENTS
1075
-
1076
- - [*task-id*:] *problem*:
1077
- Description of the *problem* to resolve, or a bare issue
1078
- identifier like `P1` or `T1` previously produced by an analyzer
1079
- skill. Optionally prefixed with a *task-id* followed by a colon
1080
- to bind the resulting plan to a specific task id.
1081
-
1082
- ## SCENARIOS
1083
-
1084
- - You want a bug fixed or a problem resolved in the code
1085
- - You want an issue like `P1` reported by an analyzer resolved
1086
- - You want resolution approaches with pros and cons before any changes
1087
- - You want a task plan composed for a bugfix
1088
-
1089
- ## EXAMPLES
1090
-
1091
- Resolve a free-text problem:
767
+ Lint only the source files with staged Git changes:
1092
768
 
1093
769
  ```text
1094
- ❯ /ase-code-resolve fix race condition in cache invalidation
770
+ ❯ /ase-code-lint --staged
1095
771
  ```
1096
772
 
1097
- Resolve a previously analyzed issue and hand off to implementation:
773
+ Lint only the unstaged and untracked source files and apply all corrections:
1098
774
 
1099
775
  ```text
1100
- ❯ /ase-code-resolve --next IMPLEMENT P1
776
+ ❯ /ase-code-lint --auto --unstaged
1101
777
  ```
1102
778
 
1103
779
  </purpose>
@@ -1660,58 +1336,17 @@ and a tighter shortlist:
1660
1336
  ```
1661
1337
 
1662
1338
  </purpose>
1663
- <purpose name="ase-meta-changelog">
1339
+ <purpose name="ase-meta-chat">
1664
1340
 
1665
1341
  ## NAME
1666
1342
 
1667
- `ase-meta-changelog` - Update ChangeLog Entries
1343
+ `ase-meta-chat` - Query Foreign LLM for Chat
1668
1344
 
1669
1345
  ## SYNOPSIS
1670
1346
 
1671
- `ase-meta-changelog`
1347
+ `ase-meta-chat`
1672
1348
  [`--help`|`-h`]
1673
-
1674
- ## DESCRIPTION
1675
-
1676
- The `ase-meta-changelog` skill helps to *complete*, *consolidate*, and
1677
- *sort* the entries of the most recent section of a `CHANGELOG.md`
1678
- file, based on the underlying *Git* commits and the currently staged
1679
- changes in the Git *index*.
1680
-
1681
- Each entry is formatted as `<change-type> [<artifact-kind>]: <summary>`
1682
- where *change-type* is one of `FEATURE`, `IMPROVEMENT`, `BUGFIX`,
1683
- `UPDATE`, `CLEANUP`, or `REFACTOR`, and *artifact-kind* is one or more
1684
- comma-separated *artifact class* tags out of `spec`, `arch`, `code`,
1685
- `docs`, `infr`, or `othr`. Entries are grouped and sorted by this
1686
- prefix. The date in the section header is also updated to the current
1687
- date.
1688
-
1689
- ## SCENARIOS
1690
-
1691
- - You want the `CHANGELOG.md` brought up to date with recent commits
1692
- - You want changelog entries completed, consolidated, and sorted
1693
- - You want a tidy changelog section before a release
1694
-
1695
- ## EXAMPLES
1696
-
1697
- Update the most recent ChangeLog section:
1698
-
1699
- ```text
1700
- ❯ /ase-meta-changelog
1701
- ```
1702
-
1703
- </purpose>
1704
- <purpose name="ase-meta-chat">
1705
-
1706
- ## NAME
1707
-
1708
- `ase-meta-chat` - Query Foreign LLM for Chat
1709
-
1710
- ## SYNOPSIS
1711
-
1712
- `ase-meta-chat`
1713
- [`--help`|`-h`]
1714
- *llm* *query*
1349
+ *llm* *query*
1715
1350
 
1716
1351
  ## DESCRIPTION
1717
1352
 
@@ -1750,42 +1385,6 @@ Ask Gemini for a brief comparison:
1750
1385
  ❯ /ase-meta-chat gemini Compare gRPC and REST in one paragraph.
1751
1386
  ```
1752
1387
 
1753
- </purpose>
1754
- <purpose name="ase-meta-commit">
1755
-
1756
- ## NAME
1757
-
1758
- `ase-meta-commit` - Git Commit Message
1759
-
1760
- ## SYNOPSIS
1761
-
1762
- `ase-meta-commit`
1763
- [`--help`|`-h`]
1764
-
1765
- ## DESCRIPTION
1766
-
1767
- The `ase-meta-commit` skill helps to *craft* a *concise commit
1768
- message* for the currently staged Git changes. It inspects the
1769
- output of `git diff --cached` and produces a single-line message of
1770
- the form `<type>: <summary>` where *type* is one of `FEATURE`,
1771
- `IMPROVEMENT`, `BUGFIX`, `UPDATE`, `CLEANUP`, or `REFACTOR`, and
1772
- *summary* is a 60-80 character imperative-mood summary without
1773
- trailing period or Markdown formatting.
1774
-
1775
- ## SCENARIOS
1776
-
1777
- - You want a commit message for the currently staged changes
1778
- - You want a typed one-line summary derived from the staged diff
1779
- - You want to commit but cannot phrase what changed
1780
-
1781
- ## EXAMPLES
1782
-
1783
- Craft a commit message for the currently staged changes:
1784
-
1785
- ```text
1786
- ❯ /ase-meta-commit
1787
- ```
1788
-
1789
1388
  </purpose>
1790
1389
  <purpose name="ase-meta-compat">
1791
1390
 
@@ -1889,13 +1488,14 @@ return the first value that is defined; writes are always confined to
1889
1488
  the strongest (target) scope of the chain.
1890
1489
 
1891
1490
  The recognized keys are grouped under `project.*` (`project.id`,
1892
- `project.name`, `project.boxing`, and the
1893
- `project.artifact.`*kind*`.{basedir,files}` globs) and `agent.*`
1894
- (`agent.persona`, `agent.guidance`, `agent.task`, and `agent.skill`).
1491
+ `project.name`, `project.boxing`, `project.task.lifecycle`,
1492
+ `project.task.idscheme`, `project.task.default.{source,changeset,target}`,
1493
+ and the `project.artifact.`*kind*`.{basedir,files}`
1494
+ globs) and `agent.*` (`agent.persona` and `agent.guidance`).
1895
1495
  Some keys are writable on selected scopes only; in particular
1896
- `agent.task` and `agent.skill` are writable on a `session` scope only,
1897
- and the `project.artifact.*` globs are writable on the `user` and
1898
- `project` scopes only.
1496
+ the `project.artifact.*` globs are writable on the `user` and
1497
+ `project` scopes only. The internal session state, like the active
1498
+ task id (see `ase-task-id`), is not part of the configuration.
1899
1499
 
1900
1500
  The three keys steering the behaviour of the agent itself accept fixed
1901
1501
  value sets: `agent.persona` selects the *communication style* and is one
@@ -1908,7 +1508,22 @@ pyramid-structured `journalist`, the brief, factual, and abbreviating
1908
1508
  `project.boxing` selects the artifact transparency and is one of `white`,
1909
1509
  `grey`, or `black`. Setting `agent.persona`, `agent.guidance`, or
1910
1510
  `project.boxing` takes effect immediately, i.e. still within the running
1911
- session.
1511
+ session. Additionally, `project.task.lifecycle` selects the task plan
1512
+ lifecycle and is one of `solo` (the default), `team`, or `enterprise`; it is
1513
+ exported at session start as `<ase-project-task-lifecycle/>`. Finally,
1514
+ `project.task.idscheme` selects the scheme of newly generated task ids and is one
1515
+ of `slug[:<words>]` (the default, the first *words* (default: 2) words of
1516
+ the task title, lower-cased and joined with `-`), `seq[:<template>]` (a
1517
+ continuously increasing sequence number, rendered through a sprintf-style
1518
+ *template* like `FOO-%03d`, `#%d`, or `%d` (the default)), or `any` (an
1519
+ arbitrary unique id chosen by the agent). Additionally,
1520
+ `project.task.default.{source,changeset,target}` select the defaults of
1521
+ the `Source:`, `Changeset:`, and `Target:` task plan keys (`worktree`,
1522
+ `worktree`, and `source` by default), which an absent key reads as, where
1523
+ a `branch:<name>` or `attachment:<name>` value can carry the placeholder
1524
+ `{id}` of the task id (e.g., `branch:cs-{id}` for a branch per task); they
1525
+ are exported at session start as
1526
+ `<ase-project-task-default-{source,changeset,target}/>`.
1912
1527
 
1913
1528
  The following *operations* exist:
1914
1529
 
@@ -1944,8 +1559,7 @@ preset-bootstrapping operation that stays a shell concern next to
1944
1559
  the strongest explicitly requested term. If the option is
1945
1560
  omitted, the chain of the *current session* (`session:`*id*) is used,
1946
1561
  so that reads see the full `user` -> `project` -> `session` cascade
1947
- and writes -- including those to the session-only keys `agent.task`
1948
- and `agent.skill` -- land on the session layer.
1562
+ and writes land on the session layer.
1949
1563
 
1950
1564
  ## ARGUMENTS
1951
1565
 
@@ -1959,7 +1573,7 @@ preset-bootstrapping operation that stays a shell concern next to
1959
1573
  ## SCENARIOS
1960
1574
 
1961
1575
  - You want the ASE configuration inspected or changed
1962
- - You want the persona, guidance, or boxing switched for a session
1576
+ - You want the persona, guidance, boxing, or task lifecycle switched for a session
1963
1577
  - You want a configuration value persisted at user or project scope
1964
1578
  - You want to see which scope supplies each effective value
1965
1579
 
@@ -1995,6 +1609,12 @@ Persist the guidance level for the whole project instead:
1995
1609
  ❯ /ase-meta-config --scope project set agent.guidance minimal
1996
1610
  ```
1997
1611
 
1612
+ Persist the task lifecycle for the whole project:
1613
+
1614
+ ```text
1615
+ ❯ /ase-meta-config --scope project set project.task.lifecycle team
1616
+ ```
1617
+
1998
1618
  Remove a value from the user-level configuration:
1999
1619
 
2000
1620
  ```text
@@ -2083,116 +1703,6 @@ Surface at least fifteen anti-theses:
2083
1703
  ❯ /ase-meta-diaboli --count 15 We should rewrite the service in Rust.
2084
1704
  ```
2085
1705
 
2086
- </purpose>
2087
- <purpose name="ase-meta-diff">
2088
-
2089
- ## NAME
2090
-
2091
- `ase-meta-diff` - Summarize Diff
2092
-
2093
- ## SYNOPSIS
2094
-
2095
- `ase-meta-diff`
2096
- [`--help`|`-h`]
2097
- [`--coherence`|`-c`]
2098
- [`--risk`|`-r`]
2099
- [`--blast`|`-b`]
2100
-
2101
- ## DESCRIPTION
2102
-
2103
- The `ase-meta-diff` skill turns a raw Git diff into a *concise*,
2104
- *human-readable* narrative of what changed and why, *grouped by
2105
- intent* (such as *Feature*, *Improvement*, *Bugfix*, *Update*,
2106
- *Cleanup*, or *Refactor*) rather than by file. It inspects the
2107
- *staged* changes (`git diff --cached HEAD`). The result is a compact
2108
- table, one row per intent group, each naming the affected files
2109
- with their per-file `[+N/-M]` line counts - giving you the essence
2110
- of the changes at a glance.
2111
-
2112
- With `--coherence`, the skill additionally *reconstructs the single
2113
- intended change* the diff is trying to accomplish - phrased as one crisp
2114
- *thesis* sentence - and then walks *every* hunk to *flag those that do
2115
- not serve it*: **scope creep** (an unrelated feature or drive-by refactor
2116
- riding along) and **stray debug** (leftover prints, commented-out code, or
2117
- disabled tests). It emits an overall **COHERENT** / **INCOHERENT** verdict
2118
- plus a table of the flagged hunks with what to do with each - keeping the
2119
- diff to a *single logical and coherent change* before it is committed.
2120
-
2121
- With `--risk`, the skill additionally *scores* the same diff against a
2122
- four-axis **coupling-criticality-coverage-reversibility** rubric and
2123
- emits a *graded risk report* - one table row per axis (each scored *1*-*5*
2124
- with a one-line evidence justification drawn from the actual hunks), an
2125
- overall risk band (**LOW**, **MODERATE**, **HIGH**, or **CRITICAL**),
2126
- and one actionable *mitigation* per high-risk axis. The axes combine
2127
- with *equal weights*, and the rubric is deliberately *not tuned* to any
2128
- specific project: every score is backed by cited evidence so it remains
2129
- *overridable*, and the report is *decision support*, not a merge gate.
2130
-
2131
- With `--blast`, the skill additionally renders a *blast-radius map* - a
2132
- Mermaid `flowchart` of the *touched modules* and their *reverse
2133
- dependencies*, plus a *brief impact summary*. It *extracts the touched
2134
- modules* from the changed files, *scans the repository* for the
2135
- first-party code that *imports* or *references* those modules, builds a
2136
- blast-radius graph (touched modules as origin nodes, dependents fanning
2137
- out along the edges), dispatches the rendering to the `ase-meta-diagram`
2138
- sub-agent, and appends a short bullet list of the per-module impact -
2139
- giving a visual sense of *what a diff endangers* before a deeper review.
2140
-
2141
- ## ARGUMENTS
2142
-
2143
- - `--coherence`, `-c`:
2144
- In addition to the intent-grouped summary, reconstruct the diff's
2145
- *single intended change* as one crisp *thesis* sentence and flag
2146
- *every* hunk that does *not* serve it - *scope creep* or *stray
2147
- debug* - then emit an overall **COHERENT** / **INCOHERENT** verdict
2148
- with a table of the flagged hunks.
2149
-
2150
- - `--risk`, `-r`:
2151
- In addition to the intent-grouped summary, score the diff against
2152
- the *coupling-criticality-coverage-reversibility* rubric and emit a
2153
- *graded risk report* with an overall risk band and per-axis
2154
- *mitigations*. Scores are equal-weighted, evidence-backed, and
2155
- deliberately untuned to the project.
2156
-
2157
- - `--blast`, `-b`:
2158
- In addition to the intent-grouped summary, render a *blast-radius
2159
- map* - a Mermaid `flowchart` of the *touched modules* and their
2160
- *reverse dependencies* - plus a *brief impact summary* of what
2161
- depends on the touched code and how far the blast reaches.
2162
-
2163
- ## SCENARIOS
2164
-
2165
- - You want a readable, intent-grouped summary of the staged changes
2166
- - You want a diff checked for scope creep and stray debug leftovers
2167
- - You want a graded risk report of a change before committing
2168
- - You want a blast-radius map of what depends on the touched code
2169
-
2170
- ## EXAMPLES
2171
-
2172
- Summarize the currently staged changes:
2173
-
2174
- ```text
2175
- ❯ /ase-meta-diff
2176
- ```
2177
-
2178
- Summarize the staged changes and append an intent-coherence report:
2179
-
2180
- ```text
2181
- ❯ /ase-meta-diff --coherence
2182
- ```
2183
-
2184
- Summarize the staged changes and append a graded risk report:
2185
-
2186
- ```text
2187
- ❯ /ase-meta-diff --risk
2188
- ```
2189
-
2190
- Summarize the staged changes and append a blast-radius map:
2191
-
2192
- ```text
2193
- ❯ /ase-meta-diff --blast
2194
- ```
2195
-
2196
1706
  </purpose>
2197
1707
  <purpose name="ase-meta-eli5">
2198
1708
 
@@ -2327,7 +1837,7 @@ Evaluate database options with hinted criteria:
2327
1837
 
2328
1838
  `ase-meta-mint`
2329
1839
  [`--help`|`-h`]
2330
- [`--type`|`-t` `uuid`|`sha1`|`const`|`var`|`class`|`func`|`path`|`name`]
1840
+ [`--type`|`-t` `uuid`|`sha1`|`nanoid`|`const`|`var`|`class`|`func`|`path`|`name`]
2331
1841
  [`--count`|`-c` *count*]
2332
1842
  [*hint*]
2333
1843
 
@@ -2337,7 +1847,7 @@ The `ase-meta-mint` skill *mints* an identifier or a name of a requested
2337
1847
  type out of the free-text *hint* formed by the positional arguments. It
2338
1848
  dispatches on `--type` and emits the generated strings as its result.
2339
1849
 
2340
- The two *hash-derived* types are delegated to the `ase_mint` tool of the
1850
+ The three *hash-derived* types are delegated to the `ase_mint` tool of the
2341
1851
  `ase` MCP server, which derives them reproducibly instead of guessing
2342
1852
  them:
2343
1853
 
@@ -2350,6 +1860,11 @@ them:
2350
1860
  - `sha1`:
2351
1861
  the 40-character hexadecimal *SHA-1* digest of the *hint*.
2352
1862
 
1863
+ - `nanoid`:
1864
+ the 10-character, *NanoId*-style *base62* hash of the *hint* (its
1865
+ *SHA-1* digest, *base62*-encoded and truncated), a short but still
1866
+ reproducible identifier.
1867
+
2353
1868
  The six *linguistic* types are derived by the skill itself: the *hint*
2354
1869
  is distilled into its essential words, which are then assembled
2355
1870
  according to the conventions of the type:
@@ -2383,7 +1898,7 @@ a random *UUID V4* without one.
2383
1898
 
2384
1899
  ## OPTIONS
2385
1900
 
2386
- `--type`|`-t` `uuid`|`sha1`|`const`|`var`|`class`|`func`|`path`|`name`:
1901
+ `--type`|`-t` `uuid`|`sha1`|`nanoid`|`const`|`var`|`class`|`func`|`path`|`name`:
2387
1902
  Select the type of the minted identifier or name (default: `uuid`).
2388
1903
 
2389
1904
  `--count`|`-c` *count*:
@@ -2404,7 +1919,7 @@ a random *UUID V4* without one.
2404
1919
 
2405
1920
  ## SCENARIOS
2406
1921
 
2407
- - You need a stable, reproducible UUID or SHA-1 digest for a concept
1922
+ - You need a stable, reproducible UUID, SHA-1 digest, or short hash for a concept
2408
1923
  - You need a well-formed constant, variable, function, or class identifier
2409
1924
  - You need a path component or slug derived from a description
2410
1925
  - You need a catchy product name for a new component or tool
@@ -2694,100 +2209,6 @@ to the conceptual neighborhood of the topic:
2694
2209
  ❯ /ase-meta-quotes --ground --proximity --count 12 technical debt
2695
2210
  ```
2696
2211
 
2697
- </purpose>
2698
- <purpose name="ase-meta-review">
2699
-
2700
- ## NAME
2701
-
2702
- `ase-meta-review` - Review Staged Changes
2703
-
2704
- ## SYNOPSIS
2705
-
2706
- `ase-meta-review`
2707
- [`--help`|`-h`]
2708
- [`--severity`|`-S`=(`LOW`|`MEDIUM`|`HIGH`)]
2709
-
2710
- ## DESCRIPTION
2711
-
2712
- The `ase-meta-review` skill performs a *holistic*,
2713
- *human-reviewer-style* critique of the *staged* Git changes and emits a
2714
- single *approve* / *reject* **verdict** backed by *prioritized*,
2715
- *severity-tagged*, *line-cited* **findings**. Rather than scanning the
2716
- code mechanically, it first *reconstructs the change's own intent* and
2717
- then judges the diff *as a whole* against that intent - the way an
2718
- experienced reviewer would on a pull request.
2719
-
2720
- The critique spans a fixed set of reviewer *dimensions*: **intent**
2721
- (does the diff do what it set out to, without scope creep or stray
2722
- residue), **correctness** (latent bugs, edge cases, broken
2723
- control/data flow), **design** (fit with the surrounding architecture,
2724
- naming, abstraction level), **clarity** (readability and
2725
- self-documentation for a future reader), **robustness** (error handling,
2726
- resource and concurrency safety), **security** and **performance** (risks
2727
- introduced by the change), **convention** (conformance to the
2728
- project's documented conventions - code style and the plan/spec
2729
- formats described in `AGENTS.md` and the `ase-format-*` meta documents),
2730
- **testing** (inadequate coverage for the change - new or fixed behavior
2731
- left untested, adjacent tests not updated, or existing tests silently
2732
- broken, disabled, or weakened), and **documentation** (user- or
2733
- developer-facing docs - `README`, `CHANGELOG`, help text, or AI
2734
- guidance/meta documents - left stale by the change).
2735
-
2736
- Each finding carries a *severity* - **HIGH**, **MEDIUM**, **LOW**, or
2737
- **ACCEPTED** (a concern that is contractually addressed or accepted as a
2738
- documented priority conflict) - and is *evidence-grounded*: it cites the
2739
- exact `file:line` location it stems from. The overall verdict is
2740
- **REJECT - DEMANDS CHANGES** when any *HIGH* finding remains, and
2741
- **APPROVE** otherwise. The work is performed by a dedicated `ase-meta-review`
2742
- sub-agent so that the silent reading and read-only repository probing
2743
- never leak into the transcript; only the structured verdict and findings
2744
- are rendered.
2745
-
2746
- The skill *complements* rather than duplicates its neighbors:
2747
- `ase-code-lint` flags *mechanical* code-quality issues, `ase-code-analyze`
2748
- inspects *logic and semantics*, `ase-meta-diff` narrates *what changed*
2749
- (with optional coherence, risk, and blast-radius reports), and
2750
- `ase-meta-diaboli` *adversarially challenges a thesis* - whereas
2751
- `ase-meta-review` renders a *reviewer's judgment* on a concrete diff
2752
- before it is committed.
2753
-
2754
- ## OPTIONS
2755
-
2756
- - `--severity`|`-S`=(`LOW`|`MEDIUM`|`HIGH`):
2757
- Set the *severity floor* (default `LOW`): findings below the chosen
2758
- threshold are silently suppressed, ordered `LOW` < `MEDIUM` <
2759
- `HIGH`. The default `LOW` keeps all findings; `ACCEPTED` findings are
2760
- never suppressed. Surviving findings are rendered in *descending
2761
- severity* order `HIGH`, `MEDIUM`, `LOW`, `ACCEPTED`. The floor only
2762
- affects the rendered findings table, not the overall *verdict*, which
2763
- is always derived from all findings before the floor is applied.
2764
-
2765
- ## ARGUMENTS
2766
-
2767
- The `ase-meta-review` skill takes no positional arguments; it always
2768
- reviews the currently *staged* Git changes.
2769
-
2770
- ## SCENARIOS
2771
-
2772
- - You want the staged changes reviewed like a human reviewer would
2773
- - You want an approve or reject verdict before committing
2774
- - You want severity-tagged, line-cited findings on a diff
2775
- - You want a holistic judgment instead of a mechanical lint
2776
-
2777
- ## EXAMPLES
2778
-
2779
- Review the currently staged changes before committing:
2780
-
2781
- ```text
2782
- ❯ /ase-meta-review
2783
- ```
2784
-
2785
- Review the staged changes, reporting only `MEDIUM` and `HIGH` findings:
2786
-
2787
- ```text
2788
- ❯ /ase-meta-review -S MEDIUM
2789
- ```
2790
-
2791
2212
  </purpose>
2792
2213
  <purpose name="ase-meta-search">
2793
2214
 
@@ -3080,8 +2501,8 @@ derivation but never restricts it: arbitrary non-ASE actions and
3080
2501
  unlisted transitions stay allowed.
3081
2502
 
3082
2503
  The generated skill is *independent* of the ASE plugin installation path:
3083
- it loads the ASE meta definitions through the `ase meta` command instead
3084
- of plugin-relative includes.
2504
+ it loads the ASE meta definitions through the `ase util meta` command
2505
+ instead of plugin-relative includes.
3085
2506
 
3086
2507
  The skill is *portable* across the supported agent tools, because
3087
2508
  *Anthropic Claude Code*, *GitHub Copilot*, and *OpenAI Codex* differ in
@@ -3098,7 +2519,7 @@ agent tool:
3098
2519
  ``!`...`` construct before the skill content reaches the model. The
3099
2520
  other agent tools receive it verbatim and would silently leave it
3100
2521
  unexpanded, so they instead get an explicit instruction to run
3101
- `ase meta ...` themselves before anything else.
2522
+ `ase util meta ...` themselves before anything else.
3102
2523
 
3103
2524
  ## OPTIONS
3104
2525
 
@@ -3155,23 +2576,717 @@ Generate a user-wide skill and overwrite a previous generation:
3155
2576
  ```
3156
2577
 
3157
2578
  </purpose>
3158
- <purpose name="ase-spec-activate">
2579
+ <purpose name="ase-repo-changelog">
3159
2580
 
3160
2581
  ## NAME
3161
2582
 
3162
- `ase-spec-activate` - Activate Specification Know-How
2583
+ `ase-repo-changelog` - Update ChangeLog Entries
3163
2584
 
3164
2585
  ## SYNOPSIS
3165
2586
 
3166
- `ase-spec-activate`
2587
+ `ase-repo-changelog`
3167
2588
  [`--help`|`-h`]
3168
- [*query*]
3169
2589
 
3170
2590
  ## DESCRIPTION
3171
2591
 
3172
- The `ase-spec-activate` skill activates the know-how about the
3173
- *SpecBook*-based specification (`SPEC`) of the project in the current
3174
- session: it loads the *SpecBook* format contract, reads the *SpecBook*
2592
+ The `ase-repo-changelog` skill helps to *complete*, *consolidate*, and
2593
+ *sort* the entries of the most recent section of a `CHANGELOG.md`
2594
+ file, based on the underlying *Git* commits and the currently staged
2595
+ changes in the Git *index*.
2596
+
2597
+ Each entry is formatted as `<change-type> [<artifact-kind>]: <summary>`
2598
+ where *change-type* is one of `FEATURE`, `IMPROVEMENT`, `BUGFIX`,
2599
+ `UPDATE`, `CLEANUP`, or `REFACTOR`, and *artifact-kind* is one or more
2600
+ comma-separated *artifact class* tags out of `spec`, `arch`, `code`,
2601
+ `docs`, `infr`, or `othr`. Entries are grouped and sorted by this
2602
+ prefix. The date in the section header is also updated to the current
2603
+ date.
2604
+
2605
+ ## SCENARIOS
2606
+
2607
+ - You want the `CHANGELOG.md` brought up to date with recent commits
2608
+ - You want changelog entries completed, consolidated, and sorted
2609
+ - You want a tidy changelog section before a release
2610
+
2611
+ ## EXAMPLES
2612
+
2613
+ Update the most recent ChangeLog section:
2614
+
2615
+ ```text
2616
+ ❯ /ase-repo-changelog
2617
+ ```
2618
+
2619
+ </purpose>
2620
+ <purpose name="ase-repo-commit">
2621
+
2622
+ ## NAME
2623
+
2624
+ `ase-repo-commit` - Git Commit Message
2625
+
2626
+ ## SYNOPSIS
2627
+
2628
+ `ase-repo-commit`
2629
+ [`--help`|`-h`]
2630
+
2631
+ ## DESCRIPTION
2632
+
2633
+ The `ase-repo-commit` skill helps to *craft* a *concise commit
2634
+ message* for the currently staged Git changes. It inspects the
2635
+ output of `git diff --cached` and produces a single-line message of
2636
+ the form `<type>: <summary>` where *type* is one of `FEATURE`,
2637
+ `IMPROVEMENT`, `BUGFIX`, `UPDATE`, `CLEANUP`, or `REFACTOR`, and
2638
+ *summary* is a 60-80 character imperative-mood summary without
2639
+ trailing period or Markdown formatting.
2640
+
2641
+ ## SCENARIOS
2642
+
2643
+ - You want a commit message for the currently staged changes
2644
+ - You want a typed one-line summary derived from the staged diff
2645
+ - You want to commit but cannot phrase what changed
2646
+
2647
+ ## EXAMPLES
2648
+
2649
+ Craft a commit message for the currently staged changes:
2650
+
2651
+ ```text
2652
+ ❯ /ase-repo-commit
2653
+ ```
2654
+
2655
+ </purpose>
2656
+ <purpose name="ase-repo-diff">
2657
+
2658
+ ## NAME
2659
+
2660
+ `ase-repo-diff` - Summarize Diff
2661
+
2662
+ ## SYNOPSIS
2663
+
2664
+ `ase-repo-diff`
2665
+ [`--help`|`-h`]
2666
+ [`--coherence`|`-c`]
2667
+ [`--risk`|`-r`]
2668
+ [`--blast`|`-b`]
2669
+
2670
+ ## DESCRIPTION
2671
+
2672
+ The `ase-repo-diff` skill turns a raw Git diff into a *concise*,
2673
+ *human-readable* narrative of what changed and why, *grouped by
2674
+ intent* (such as *Feature*, *Improvement*, *Bugfix*, *Update*,
2675
+ *Cleanup*, or *Refactor*) rather than by file. It inspects the
2676
+ *staged* changes (`git diff --cached HEAD`). The result is a compact
2677
+ table, one row per intent group, each naming the affected files
2678
+ with their per-file `[+N/-M]` line counts - giving you the essence
2679
+ of the changes at a glance.
2680
+
2681
+ With `--coherence`, the skill additionally *reconstructs the single
2682
+ intended change* the diff is trying to accomplish - phrased as one crisp
2683
+ *thesis* sentence - and then walks *every* hunk to *flag those that do
2684
+ not serve it*: **scope creep** (an unrelated feature or drive-by refactor
2685
+ riding along) and **stray debug** (leftover prints, commented-out code, or
2686
+ disabled tests). It emits an overall **COHERENT** / **INCOHERENT** verdict
2687
+ plus a table of the flagged hunks with what to do with each - keeping the
2688
+ diff to a *single logical and coherent change* before it is committed.
2689
+
2690
+ With `--risk`, the skill additionally *scores* the same diff against a
2691
+ four-axis **coupling-criticality-coverage-reversibility** rubric and
2692
+ emits a *graded risk report* - one table row per axis (each scored *1*-*5*
2693
+ with a one-line evidence justification drawn from the actual hunks), an
2694
+ overall risk band (**LOW**, **MODERATE**, **HIGH**, or **CRITICAL**),
2695
+ and one actionable *mitigation* per high-risk axis. The axes combine
2696
+ with *equal weights*, and the rubric is deliberately *not tuned* to any
2697
+ specific project: every score is backed by cited evidence so it remains
2698
+ *overridable*, and the report is *decision support*, not a merge gate.
2699
+
2700
+ With `--blast`, the skill additionally renders a *blast-radius map* - a
2701
+ Mermaid `flowchart` of the *touched modules* and their *reverse
2702
+ dependencies*, plus a *brief impact summary*. It *extracts the touched
2703
+ modules* from the changed files, *scans the repository* for the
2704
+ first-party code that *imports* or *references* those modules, builds a
2705
+ blast-radius graph (touched modules as origin nodes, dependents fanning
2706
+ out along the edges), dispatches the rendering to the `ase-meta-diagram`
2707
+ sub-agent, and appends a short bullet list of the per-module impact -
2708
+ giving a visual sense of *what a diff endangers* before a deeper review.
2709
+
2710
+ ## ARGUMENTS
2711
+
2712
+ - `--coherence`, `-c`:
2713
+ In addition to the intent-grouped summary, reconstruct the diff's
2714
+ *single intended change* as one crisp *thesis* sentence and flag
2715
+ *every* hunk that does *not* serve it - *scope creep* or *stray
2716
+ debug* - then emit an overall **COHERENT** / **INCOHERENT** verdict
2717
+ with a table of the flagged hunks.
2718
+
2719
+ - `--risk`, `-r`:
2720
+ In addition to the intent-grouped summary, score the diff against
2721
+ the *coupling-criticality-coverage-reversibility* rubric and emit a
2722
+ *graded risk report* with an overall risk band and per-axis
2723
+ *mitigations*. Scores are equal-weighted, evidence-backed, and
2724
+ deliberately untuned to the project.
2725
+
2726
+ - `--blast`, `-b`:
2727
+ In addition to the intent-grouped summary, render a *blast-radius
2728
+ map* - a Mermaid `flowchart` of the *touched modules* and their
2729
+ *reverse dependencies* - plus a *brief impact summary* of what
2730
+ depends on the touched code and how far the blast reaches.
2731
+
2732
+ ## SCENARIOS
2733
+
2734
+ - You want a readable, intent-grouped summary of the staged changes
2735
+ - You want a diff checked for scope creep and stray debug leftovers
2736
+ - You want a graded risk report of a change before committing
2737
+ - You want a blast-radius map of what depends on the touched code
2738
+
2739
+ ## EXAMPLES
2740
+
2741
+ Summarize the currently staged changes:
2742
+
2743
+ ```text
2744
+ ❯ /ase-repo-diff
2745
+ ```
2746
+
2747
+ Summarize the staged changes and append an intent-coherence report:
2748
+
2749
+ ```text
2750
+ ❯ /ase-repo-diff --coherence
2751
+ ```
2752
+
2753
+ Summarize the staged changes and append a graded risk report:
2754
+
2755
+ ```text
2756
+ ❯ /ase-repo-diff --risk
2757
+ ```
2758
+
2759
+ Summarize the staged changes and append a blast-radius map:
2760
+
2761
+ ```text
2762
+ ❯ /ase-repo-diff --blast
2763
+ ```
2764
+
2765
+ </purpose>
2766
+ <purpose name="ase-repo-dissect">
2767
+
2768
+ ## NAME
2769
+
2770
+ `ase-repo-dissect` - Dissect a Change Set
2771
+
2772
+ ## SYNOPSIS
2773
+
2774
+ `ase-repo-dissect`
2775
+ [`--help`|`-h`]
2776
+ [`--max-parts`|`-m` *count*]
2777
+ [`--staged`|`-s`]
2778
+ [`--dry`|`-d`]
2779
+ [`--force`|`-f`]
2780
+ [*dissect-hint*]
2781
+
2782
+ ## DESCRIPTION
2783
+
2784
+ The `ase-repo-dissect` skill treats the current Git change set as an
2785
+ *epic* and *dissects* it domain-wise and logically into *cohesive
2786
+ parts*. Each part is a self-contained unit of change with a single
2787
+ coherent purpose, so it can be reviewed and committed *atomically* and
2788
+ *independently* of the others.
2789
+
2790
+ The change set is captured from the working copy (`git diff`), with
2791
+ untracked files folded in *read-only*, or -- under `--staged`/`-s` --
2792
+ from the Git index (`git diff --cached HEAD`). The dissection follows a
2793
+ strict ruleset: at least *2* and at most *count* parts are derived,
2794
+ *every* hunk is assigned to *exactly one* part, mutually dependent hunks
2795
+ are kept together, all hunks of one file normally stay in the same part,
2796
+ and nothing beyond the actual change set is invented. The cut follows
2797
+ the *semantics* of the change, not its technical structure -- a split by
2798
+ file, directory, or technical layer is usually *not* the intended one.
2799
+ If the change set carries only a single cohesive purpose, it is reported
2800
+ as *not dissectable* and nothing is created.
2801
+
2802
+ An optional *dissect-hint* steers *how* the change set is split -- which
2803
+ changes belong together, along which axis to cut, or how many parts to
2804
+ aim at. It is especially useful after a `--dry` run showed an unintended
2805
+ dissection. The hint overrides the default grouping, but never the
2806
+ ruleset itself.
2807
+
2808
+ The derived parts are first reported as a *dissection table* (part
2809
+ number, worktree id, scope, and rationale). Then -- unless `--dry` is
2810
+ given -- each part's patch is written to a temporary file and applied
2811
+ inside a *fresh Git WorkTree* `.ase/worktree/<project-id>-<feature-slug>`,
2812
+ whose branch carries the same name and is created from `HEAD`. If a
2813
+ `CHANGELOG.md` file exists, a matching entry summarizing that part is
2814
+ added *inside* the worktree.
2815
+
2816
+ Every part stays *uncommitted*, a failing `git apply` is reported for
2817
+ that part while the remaining parts continue, and the *original working
2818
+ copy is never mutated*.
2819
+
2820
+ Note that the working-copy patch (without `--staged`) is taken relative
2821
+ to the Git *index* while the worktrees are created from `HEAD`. So if
2822
+ changes are *also* staged, the affected part patches may not apply
2823
+ cleanly and are then reported as failed; stage everything and use
2824
+ `--staged` in that situation.
2825
+
2826
+ ## OPTIONS
2827
+
2828
+ - `--max-parts`|`-m` *count*:
2829
+ Upper bound for the number of derived parts (default: `8`). The
2830
+ lower bound is always `2`, because fewer parts are no dissection.
2831
+
2832
+ - `--staged`|`-s`:
2833
+ Dissect the *staged* changes (the Git index against `HEAD`) instead
2834
+ of the working copy changes. Untracked files are then *not* folded
2835
+ in, because they are by definition not part of the index.
2836
+
2837
+ - `--dry`|`-d`:
2838
+ *Report only* -- print the dissection table but create *no*
2839
+ artifacts at all, so the decision stays fully reversible.
2840
+
2841
+ - `--force`|`-f`:
2842
+ Remove and re-create already existing worktrees and branches of the
2843
+ derived names. Without this option, the skill detects colliding
2844
+ targets *before* writing anything, reports them, and stops with
2845
+ status *targets exist*.
2846
+
2847
+ ## ARGUMENTS
2848
+
2849
+ - *dissect-hint*:
2850
+ A free-text hint telling *how* the change set should be split. If
2851
+ omitted, the parts are derived from the change set alone.
2852
+
2853
+ The worktree names are *not* argument-driven: they are always derived
2854
+ from the *current* project id and the per-part feature slug.
2855
+
2856
+ ## SCENARIOS
2857
+
2858
+ - You want a large uncommitted change set split into atomic parts
2859
+ - You want each cohesive part of a diff in its own Git worktree
2860
+ - You want mixed-up changes untangled before committing them
2861
+ - You want a preview of how a change set would be divided
2862
+
2863
+ ## EXAMPLES
2864
+
2865
+ Dissect the current working copy changes:
2866
+
2867
+ ```text
2868
+ ❯ /ase-repo-dissect
2869
+ ```
2870
+
2871
+ Preview the dissection of the staged changes into at most four parts:
2872
+
2873
+ ```text
2874
+ ❯ /ase-repo-dissect --staged --dry --max-parts 4
2875
+ ```
2876
+
2877
+ Re-dissect the changes, re-creating the previously created worktrees:
2878
+
2879
+ ```text
2880
+ ❯ /ase-repo-dissect --force
2881
+ ```
2882
+
2883
+ Dissect the changes along an explicitly given axis:
2884
+
2885
+ ```text
2886
+ ❯ /ase-repo-dissect keep the plugin and tool changes in separate parts
2887
+ ```
2888
+
2889
+ </purpose>
2890
+ <purpose name="ase-repo-merge">
2891
+ ## NAME
2892
+
2893
+ `ase-repo-merge` - Merge a Branch
2894
+
2895
+ ## SYNOPSIS
2896
+
2897
+ `ase-repo-merge`
2898
+ [`--help`|`-h`]
2899
+ [`--target`|`-t` *branch*]
2900
+ [`--mode`|`-m` `merge`|`rebase`|`squash`]
2901
+ [`--cleanup`|`-c`]
2902
+ *source-branch*
2903
+
2904
+ ## DESCRIPTION
2905
+
2906
+ The `ase-repo-merge` skill *merges* a Git *source-branch* into a target
2907
+ branch and reports the result as a *merge verdict*: `MERGED`,
2908
+ `CONFLICT`, or `FAILED`.
2909
+
2910
+ Still *uncommitted* changes in the worktree where the source branch is
2911
+ checked out are first *committed* with a derived one-line commit
2912
+ message of the form `<type>: <summary>`. The source branch is then
2913
+ merged inside the worktree where the target branch is checked out,
2914
+ which has to be free of uncommitted changes, in one of three modes: a
2915
+ regular *merge* with a merge commit (`git merge --no-ff`), a *rebase*
2916
+ of the source branch onto the target branch followed by a
2917
+ fast-forward (`git rebase` plus `git merge --ff-only`), or a *squash*
2918
+ of all source commits into one commit (`git merge --squash`).
2919
+ Merge conflicts are *resolved semantically*, honoring the intents of
2920
+ both sides and never losing any change, through the same procedure as
2921
+ `ase-repo-resolve`. If a conflict is unresolvable, because both
2922
+ intents contradict each other or no confident resolution exists, the
2923
+ unresolvable conflicts are reported, the merge is *aborted*, the
2924
+ target branch is left untouched, and the verdict is `CONFLICT`. Finally, the skill *checks*
2925
+ that the source branch is contained in the target branch. It does
2926
+ *not* build or test the merge result, so semantically resolved
2927
+ conflicts still deserve a review.
2928
+
2929
+ On a `CONFLICT` or `FAILED` verdict, the commit of the previously
2930
+ uncommitted source changes is *undone* again, so they are uncommitted
2931
+ as before (but no longer partially staged).
2932
+
2933
+ If the source branch *equals* the target branch, only its uncommitted
2934
+ changes are committed. The skill is also used by `ase agent integrator`
2935
+ to drive the *Integration* phase of the `enterprise` task lifecycle
2936
+ model headless. As the target branch is by default the checked-out
2937
+ branch of the working copy of the project, any uncommitted change
2938
+ there lets the merge of every task with its own branch fail, and hence
2939
+ the task become `DEFERRED`, while for a task with an in-place change
2940
+ set it is committed together with that change set. So, when running
2941
+ the integrator, keep the working copy clean and do your own work in
2942
+ separate worktrees.
2943
+
2944
+ ## OPTIONS
2945
+
2946
+ - `--target`|`-t` *branch*:
2947
+ The target branch of the merge (default: `current`, the checked-out
2948
+ branch of the working copy).
2949
+
2950
+ - `--mode`|`-m` `merge`|`rebase`|`squash`:
2951
+ The merge mode (default: `merge`): `merge` creates a merge commit,
2952
+ `rebase` rebases the source branch (rewriting its commits, in its
2953
+ own worktree if it is checked out) onto the target branch and
2954
+ fast-forwards the target branch, and `squash` combines all changes
2955
+ of the source branch into one new commit on the target branch.
2956
+ Conflicts are resolved per rebased commit under `rebase`.
2957
+
2958
+ - `--cleanup`|`-c`:
2959
+ After a successful merge, remove the worktree of the source branch
2960
+ (if any) and delete the merged source branch.
2961
+
2962
+ ## ARGUMENTS
2963
+
2964
+ - *source-branch*:
2965
+ The Git branch to merge.
2966
+
2967
+ ## SCENARIOS
2968
+
2969
+ - You want a feature branch landed on the checked-out branch
2970
+ - You want the uncommitted result of a worktree committed and merged
2971
+ - You want merge conflicts resolved instead of hand-editing them
2972
+
2973
+ ## EXAMPLES
2974
+
2975
+ Merge the branch `feature-x` into the checked-out branch:
2976
+
2977
+ ```text
2978
+ ❯ /ase-repo-merge feature-x
2979
+ ```
2980
+
2981
+ Merge the branch `feature-x` into `develop` and remove it afterwards:
2982
+
2983
+ ```text
2984
+ ❯ /ase-repo-merge --target develop --cleanup feature-x
2985
+ ```
2986
+
2987
+ Squash the branch `feature-x` into one commit on the checked-out branch:
2988
+
2989
+ ```text
2990
+ ❯ /ase-repo-merge --mode squash feature-x
2991
+ ```
2992
+
2993
+ </purpose>
2994
+ <purpose name="ase-repo-resolve">
2995
+
2996
+ ## NAME
2997
+
2998
+ `ase-repo-resolve` - Resolve Merge Conflicts
2999
+
3000
+ ## SYNOPSIS
3001
+
3002
+ `ase-repo-resolve`
3003
+ [`--help`|`-h`]
3004
+ [`--dir`|`-d` *dir*]
3005
+ [`--safe`|`-s`]
3006
+ [`--interactive`|`-i`]
3007
+ [*path* ...]
3008
+
3009
+ ## DESCRIPTION
3010
+
3011
+ The `ase-repo-resolve` skill *resolves* the Git merge conflicts of a
3012
+ working directory and reports the result as a *resolve verdict*:
3013
+ `RESOLVED`, `PARTIAL`, `NONE`, or `FAILED`.
3014
+
3015
+ It handles every *unmerged* state of the Git index -- left by an
3016
+ in-progress `git merge`, `git rebase`, `git cherry-pick`, `git revert`,
3017
+ or by `git stash apply` -- and additionally files carrying conflict
3018
+ markers *without* an unmerged index entry, e.g., left by `patch
3019
+ --merge`. Reject files (`*.rej`) of `patch` are escalated, but never
3020
+ touched.
3021
+
3022
+ Every conflict hunk is resolved *semantically*: the intents of both
3023
+ sides are determined from the commits, the base version, and the
3024
+ surrounding code, and the hunk is resolved so that *both* intents are
3025
+ honored. Trivial, independent, and compatible changes are combined,
3026
+ while a hunk whose intents *contradict* each other, or for which no
3027
+ confident resolution exists, is *kept as-is* including its conflict
3028
+ markers and *escalated* to the user. Files with only some unresolvable
3029
+ hunks are resolved *partially* and stay unmerged. Non-content conflicts
3030
+ (binary, submodule, modify/delete, rename, delete/delete) are resolved
3031
+ only if their intent is unambiguous.
3032
+
3033
+ The skill is very careful to *never lose* any change: every touched
3034
+ file is first backed up into the `ase-resolve` directory inside the Git
3035
+ directory, and every resolved hunk is checked to still reflect all
3036
+ changes of both sides relative to the base; a hunk failing this check
3037
+ is restored with its conflict markers and escalated. The backups are
3038
+ removed on a `RESOLVED` verdict and kept otherwise.
3039
+
3040
+ Fully resolved unmerged files are staged. On a `RESOLVED` verdict, the
3041
+ in-progress operation is *continued* (e.g., `git merge --continue`),
3042
+ and, if this stops at the next conflicting commit of a rebase,
3043
+ cherry-pick, or revert, those conflicts are resolved, too. The skill
3044
+ does *not* build or test the result, so the resolved conflicts still
3045
+ deserve a review.
3046
+
3047
+ The same resolution procedure is used by `ase-repo-merge` for the
3048
+ conflicts of its merge.
3049
+
3050
+ ## OPTIONS
3051
+
3052
+ - `--dir`|`-d` *dir*:
3053
+ The Git working directory whose conflicts are resolved (default:
3054
+ `.`, the current working directory).
3055
+
3056
+ - `--safe`|`-s`:
3057
+ Never touch non-content conflicts (binary, submodule,
3058
+ modify/delete, rename, delete/delete), but always escalate them.
3059
+
3060
+ - `--interactive`|`-i`:
3061
+ Instead of directly escalating an unresolvable hunk, show it and
3062
+ let the user choose `OURS`, `THEIRS`, `BOTH`, `KEEP` (escalate), or
3063
+ describe a manual resolution. Ignored when running headless.
3064
+
3065
+ ## ARGUMENTS
3066
+
3067
+ - *path* ...:
3068
+ Restrict the resolution to the conflicted files equal to or below
3069
+ the given paths. The in-progress operation is then continued only
3070
+ if no conflicted files remain elsewhere.
3071
+
3072
+ ## SCENARIOS
3073
+
3074
+ - You ran into merge conflicts during a merge, rebase, or cherry-pick
3075
+ - You applied a stash or a patch and got conflict markers
3076
+ - You want conflicts resolved without risking the loss of any change
3077
+
3078
+ ## EXAMPLES
3079
+
3080
+ Resolve all conflicts of the current working directory:
3081
+
3082
+ ```text
3083
+ ❯ /ase-repo-resolve
3084
+ ```
3085
+
3086
+ Resolve the conflicts below `src/`, deciding unresolvable hunks
3087
+ interactively:
3088
+
3089
+ ```text
3090
+ ❯ /ase-repo-resolve --interactive src/
3091
+ ```
3092
+
3093
+ </purpose>
3094
+ <purpose name="ase-repo-review">
3095
+
3096
+ ## NAME
3097
+
3098
+ `ase-repo-review` - Review Changes
3099
+
3100
+ ## SYNOPSIS
3101
+
3102
+ `ase-repo-review`
3103
+ [`--help`|`-h`]
3104
+ [`--severity`|`-S`=(`AUTO`|`LOW`|`MEDIUM`|`HIGH`)]
3105
+ [`--thorough`|`-t`]
3106
+ [`--staged`]
3107
+ [`--unstaged`]
3108
+ [`--branch`|`-b` *branch*]
3109
+ [`--commit`|`-c` *commit*]
3110
+
3111
+ ## DESCRIPTION
3112
+
3113
+ The `ase-repo-review` skill performs a *holistic*,
3114
+ *human-reviewer-style* critique of the *staged* Git changes (or, with
3115
+ `--unstaged`, of the *unstaged* and *untracked* changes, with both
3116
+ `--staged` and `--unstaged`, of *all* uncommitted changes, with
3117
+ `--branch`, of the changes of a *branch* against its *base*, or, with
3118
+ `--commit`, of a *single commit*) and emits a single
3119
+ *approve* / *reject* **verdict** backed by *prioritized*,
3120
+ *severity-tagged*, *line-cited* **findings**. Rather than scanning the
3121
+ code mechanically, it first *reconstructs the change's own intent* and
3122
+ then judges the diff *as a whole* against that intent - the way an
3123
+ experienced reviewer would on a pull request.
3124
+
3125
+ The critique spans a fixed set of reviewer *dimensions*: **intent**
3126
+ (does the diff do what it set out to, without scope creep),
3127
+ **propagation** (the change fully and consistently carried over to call
3128
+ sites, types, schemas, registries, catalogs, and analogous sibling
3129
+ places, with matching contracts and terminology, and without orphans left
3130
+ behind), **coverage** (all special and edge cases handled, like empty
3131
+ values, boundaries, error paths, and all variants), **residue** (debug
3132
+ output, commented-out code, scaffolding, temporary files, build output,
3133
+ or secrets which do not belong into the change), **correctness**
3134
+ (latent bugs, broken control/data flow), **design** (fit with the surrounding architecture,
3135
+ naming, abstraction level), **clarity** (readability and
3136
+ self-documentation for a future reader), **robustness** (error handling,
3137
+ resource and concurrency safety), **security** and **performance** (risks
3138
+ introduced by the change), **convention** (conformance to the
3139
+ project's documented conventions - code style and the plan/spec
3140
+ formats described in `AGENTS.md` and the `ase-format-*` meta documents),
3141
+ **testing** (inadequate coverage for the change - new or fixed behavior
3142
+ left untested, adjacent tests not updated, or existing tests silently
3143
+ broken, disabled, or weakened), and **documentation** (user- or
3144
+ developer-facing docs - `README`, `CHANGELOG`, help text, or AI
3145
+ guidance/meta documents - left stale by the change).
3146
+
3147
+ Each finding carries a *severity* - **HIGH**, **MEDIUM**, **LOW**, or
3148
+ **ACCEPTED** (a concern that is contractually addressed or accepted as a
3149
+ documented priority conflict) - and is *evidence-grounded*: it cites the
3150
+ exact `file:line` location it stems from. The overall verdict is
3151
+ **REJECT - DEMANDS CHANGES** when any *HIGH* finding remains, and
3152
+ **APPROVE** otherwise. The work is performed by a dedicated `ase-repo-review`
3153
+ sub-agent so that the silent reading and read-only repository probing
3154
+ never leak into the transcript; only the structured verdict and findings
3155
+ are rendered.
3156
+
3157
+ The skill *complements* rather than duplicates its neighbors:
3158
+ `ase-code-lint` flags *mechanical* code-quality issues, `ase-code-analyze`
3159
+ inspects *logic and semantics*, `ase-repo-diff` narrates *what changed*
3160
+ (with optional coherence, risk, and blast-radius reports), and
3161
+ `ase-meta-diaboli` *adversarially challenges a thesis* - whereas
3162
+ `ase-repo-review` renders a *reviewer's judgment* on a concrete diff
3163
+ before it is committed or merged.
3164
+
3165
+ ## OPTIONS
3166
+
3167
+ - `--severity`|`-S`=(`AUTO`|`LOW`|`MEDIUM`|`HIGH`):
3168
+ Set the *severity floor* (default `AUTO`): findings below the chosen
3169
+ threshold are suppressed, ordered `LOW` < `MEDIUM` < `HIGH`. The
3170
+ default `AUTO` means `MEDIUM` for a project with `grey` boxing and
3171
+ `LOW` (keep all findings) otherwise; an explicitly given floor always
3172
+ wins over the boxing. `ACCEPTED` findings are never suppressed, and
3173
+ the number of suppressed findings is always reported. Surviving
3174
+ findings are rendered in *descending severity* order `HIGH`,
3175
+ `MEDIUM`, `LOW`, `ACCEPTED`. The floor only affects the rendered
3176
+ findings table, not the overall *verdict*, which is always derived
3177
+ from all findings before the floor is applied.
3178
+
3179
+ - `--thorough`|`-t`:
3180
+ Review *exhaustively* instead of reporting only a *few* high-signal
3181
+ findings: report every well-grounded concern, including minor nits,
3182
+ and additionally *plausible* concerns whose impact cannot be fully
3183
+ proven, marked with "*Plausible:*" and rated at most `MEDIUM`.
3184
+
3185
+ - `--staged`:
3186
+ Review the *staged* changes of the working copy. This is the default
3187
+ if neither `--unstaged`, `--branch`, nor `--commit` is given.
3188
+ Combined with `--unstaged`, review *all* uncommitted changes.
3189
+ Combined with `--branch`, additionally review the staged changes of
3190
+ the worktree where the *branch* is checked out.
3191
+
3192
+ - `--unstaged`:
3193
+ Review the *unstaged* changes and the *untracked* files of the
3194
+ working copy (except *ASE*'s own state below `.ase/`) instead of the
3195
+ *staged* changes. Combined with `--staged`, review *all* uncommitted
3196
+ changes. Combined with `--branch`, additionally review the unstaged
3197
+ changes and untracked files of the worktree where the *branch* is
3198
+ checked out.
3199
+
3200
+ - `--branch`|`-b` *branch*:
3201
+ Review the commits of *branch* (any Git revision) since its fork
3202
+ point from its *base*, instead of the *staged* changes. The base is
3203
+ determined automatically as the local branch with the *nearest* fork
3204
+ point (preferring the checked-out branch on a tie) and is reported
3205
+ before the review. The commit messages are checked for mismatches
3206
+ against the diff.
3207
+
3208
+ - `--commit`|`-c` *commit*:
3209
+ Review the single *commit* (any Git revision) against its first
3210
+ parent, instead of the *staged* changes. Its commit message is
3211
+ checked for mismatches against the diff. This option cannot be
3212
+ combined with `--branch`, `--staged`, or `--unstaged`.
3213
+
3214
+ ## ARGUMENTS
3215
+
3216
+ The `ase-repo-review` skill takes no positional arguments; it reviews the
3217
+ currently *staged* Git changes, with `--unstaged` the unstaged and
3218
+ untracked changes, with both `--staged` and `--unstaged` all uncommitted
3219
+ changes, with `--branch` a branch against its base, or with `--commit` a
3220
+ single commit.
3221
+
3222
+ ## SCENARIOS
3223
+
3224
+ - You want the staged changes reviewed like a human reviewer would
3225
+ - You want an approve or reject verdict before committing
3226
+ - You want severity-tagged, line-cited findings on a diff
3227
+ - You want a holistic judgment instead of a mechanical lint
3228
+ - You want your not yet staged changes reviewed
3229
+ - You want an exhaustive review of all uncommitted changes
3230
+ - You want a feature branch reviewed before merging it
3231
+ - You want a single, already committed change reviewed
3232
+
3233
+ ## EXAMPLES
3234
+
3235
+ Review the currently staged changes before committing:
3236
+
3237
+ ```text
3238
+ ❯ /ase-repo-review
3239
+ ```
3240
+
3241
+ Review the staged changes, reporting only `MEDIUM` and `HIGH` findings:
3242
+
3243
+ ```text
3244
+ ❯ /ase-repo-review -S MEDIUM
3245
+ ```
3246
+
3247
+ Review the unstaged and untracked changes only:
3248
+
3249
+ ```text
3250
+ ❯ /ase-repo-review --unstaged
3251
+ ```
3252
+
3253
+ Review all uncommitted changes exhaustively, reporting all findings:
3254
+
3255
+ ```text
3256
+ ❯ /ase-repo-review --staged --unstaged -t -S LOW
3257
+ ```
3258
+
3259
+ Review the branch `feature` against its base, including the uncommitted
3260
+ changes of its worktree:
3261
+
3262
+ ```text
3263
+ ❯ /ase-repo-review -b feature --staged --unstaged
3264
+ ```
3265
+
3266
+ Review the last commit:
3267
+
3268
+ ```text
3269
+ ❯ /ase-repo-review -c HEAD
3270
+ ```
3271
+
3272
+ </purpose>
3273
+ <purpose name="ase-spec-activate">
3274
+
3275
+ ## NAME
3276
+
3277
+ `ase-spec-activate` - Activate Specification Know-How
3278
+
3279
+ ## SYNOPSIS
3280
+
3281
+ `ase-spec-activate`
3282
+ [`--help`|`-h`]
3283
+ [*query*]
3284
+
3285
+ ## DESCRIPTION
3286
+
3287
+ The `ase-spec-activate` skill activates the know-how about the
3288
+ *SpecBook*-based specification (`SPEC`) of the project in the current
3289
+ session: it loads the *SpecBook* format contract, reads the *SpecBook*
3175
3290
  schema configuration of the project (the schema files configured via
3176
3291
  `project.artifact.spec.schema`, where the entry `std` -- also the default
3177
3292
  -- names the standard schema bundled with *ASE*), and resolves the list
@@ -3240,10 +3355,14 @@ Activate and directly answer a question about the specification:
3240
3355
 
3241
3356
  `ase-spec-edit`
3242
3357
  [`--help`|`-h`]
3358
+ [`--approach`|`-a`]
3243
3359
  [`--grill`|`-g`]
3244
3360
  [`--grill-rounds`|`-r` *n*]
3361
+ [`--grill-until`|`-u` `MUST`|`SHOULD`|`MAY`]
3362
+ [`--grill-perspective`|`-p` *perspective*]
3363
+ [`--grill-ground`|`-G`]
3245
3364
  [`--verify`|`-v`]
3246
- [`--worktree`|`-w`]
3365
+ [`--worktree`|`-w` *name*[`:`*branch*]]
3247
3366
  [`--loop`|`-l`]
3248
3367
  [*query*]
3249
3368
 
@@ -3264,11 +3383,12 @@ WHAT and its implementation-detail HOW parts), *discovering* (resolve
3264
3383
  the `SPEC` artifacts, read the *SpecBook* schema configuration of the
3265
3384
  project, and read the specification artifacts related to the query),
3266
3385
  *grilling* (optionally stress-test the query with rounds of questions),
3267
- *implementing* (apply the change set in place, honoring the GENERIC and
3268
- SPECIFYING tenets and the `SPEC` format contract), and *verifying*
3269
- (optionally validate the specification until it passes). The *querying*
3270
- state and every *grilling* round close with an `EDIT TODO` box showing
3271
- the established `WHAT` and `HOW` information.
3386
+ *implementing* (optionally select an approach, then apply the change set
3387
+ in place, honoring the GENERIC and SPECIFYING tenets and the `SPEC`
3388
+ format contract), and *verifying* (optionally validate the specification
3389
+ until it passes). The *querying* state, every *grilling* round, and the
3390
+ approach selection close with an `EDIT TODO` box showing the established
3391
+ `WHAT` and `HOW` information.
3272
3392
 
3273
3393
  The change set stays strictly restricted to the `SPEC` artifacts -- the
3274
3394
  artifact kinds `CODE`, `DOCS`, `TASK`, `INFR`, and `OTHR` are never
@@ -3278,6 +3398,15 @@ timestamp refreshed.
3278
3398
 
3279
3399
  ## OPTIONS
3280
3400
 
3401
+ - `--approach`|`-a`:
3402
+ Before applying the change set, propose one or more specification
3403
+ approaches with pros and cons, recommend one of them, and let the
3404
+ user pick the preferred one via an interactive dialog (or, under the
3405
+ `black` project boxing or in headless mode, automatically pick the
3406
+ recommended one). The chosen approach is merged into the HOW part of
3407
+ the query. Without `--approach`, no approaches are determined at
3408
+ all.
3409
+
3281
3410
  - `--grill`|`-g`:
3282
3411
  Grill the query before implementing, similar to `ase-task-grill`:
3283
3412
  raise 1-10 questions per round which resolve the open points of the
@@ -3285,11 +3414,16 @@ timestamp refreshed.
3285
3414
  (domain-specifics, must be clarified), `INTERFACE` (externally
3286
3415
  observable behavior or UI/API interfaces, must be clarified),
3287
3416
  `ARCHITECTURE` (structure, wiring, placement, or dependencies,
3288
- should be clarified), or `IMPLEMENTATION` (inner technical details,
3289
- can be clarified) -- and a 1-3 word `TOPIC` hint. The questions of a
3290
- round are sorted by descending focus area importance (`DOMAIN`,
3291
- `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`) and are announced
3292
- together below a `GRILLING ROUND K/L` line (the round numbering is
3417
+ should be clarified), `IMPLEMENTATION` (inner technical details,
3418
+ can be clarified), `REGRESSION` (what must not break, should be
3419
+ clarified), or `CONFIRMATION` (what proves the specified behavior,
3420
+ should be clarified) -- and a 1-3 word `TOPIC` hint. The questions
3421
+ of a round are sorted by descending focus area importance
3422
+ (`DOMAIN`, `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`,
3423
+ `REGRESSION`, `CONFIRMATION`). Questions of focus area
3424
+ `REGRESSION` and `CONFIRMATION` are raised only together with
3425
+ `--verify`, as only then a verification honors their decisions.
3426
+ All questions of a round are announced together below a `GRILLING ROUND K/L` line (the round numbering is
3293
3427
  omitted when only a single round is performed) as a
3294
3428
  `QUESTION`/`ANSWERS` table with one row per question, each row
3295
3429
  carrying two to three grounded answer alternatives (with the
@@ -3298,15 +3432,54 @@ timestamp refreshed.
3298
3432
  whose question asks for the combined answer to all (or a subset) of
3299
3433
  the listed questions and whose only answer options are the fixed
3300
3434
  `SKIP GRILLING` (skip the remaining grilling) and `STOP SKILL` (stop
3301
- the skill) ones, plus free-text input. The answers are merged back
3302
- into the WHAT and HOW parts of the query. Without `--grill`, no
3303
- questions are asked at all.
3435
+ the skill) ones, plus free-text input. The questions are numbered
3436
+ `1`, `2`, etc. and their answer alternatives are lettered `A`, `B`,
3437
+ etc., so the free-text input can cherry-pick answers with short
3438
+ responses matching `\d+[a-zA-Z]` (like `1A 2c`), freely mixed with
3439
+ keyword text. The answers are merged back into the WHAT and HOW
3440
+ parts of the query. Without `--grill`, no questions are asked at
3441
+ all.
3304
3442
 
3305
3443
  - `--grill-rounds`|`-r` *n*:
3306
- The number of grill rounds to apply (default: `1`). Each round
3307
- starts from scratch from only the current WHAT and HOW parts,
3444
+ The *maximum* number of grill rounds to apply (default: `1`). Each
3445
+ round starts from scratch from only the current WHAT and HOW parts,
3308
3446
  forgetting all information of previous rounds, and closes with an
3309
- `EDIT TODO` box. Only effective together with `--grill`.
3447
+ `EDIT TODO` box. The grilling stops early -- announced by a
3448
+ `grilling finished early` status line -- once a round, even the
3449
+ first one, finds the open points clear enough according to
3450
+ `--grill-until`. Only effective together with `--grill`.
3451
+
3452
+ - `--grill-until`|`-u` `MUST`|`SHOULD`|`MAY`:
3453
+ Grill until at least all open points of the given severity or
3454
+ higher are clear (default: `MUST`), where the severity follows from
3455
+ the focus area: `MUST` (`DOMAIN`, `INTERFACE`), `SHOULD`
3456
+ (`ARCHITECTURE`, `REGRESSION`, `CONFIRMATION`), and `MAY`
3457
+ (`IMPLEMENTATION`). Independent of this, every open point is rated
3458
+ with an individual impact (`HIGH`, `MEDIUM`, or `LOW`), which
3459
+ decides which points are raised as questions and in which order
3460
+ within a focus area. Only effective together with `--grill`.
3461
+
3462
+ - `--grill-perspective`|`-p` *perspective*:
3463
+ Grill exclusively from the logical *perspective* -- a keyword or
3464
+ short hint like `domain`, `performance`, or `security`. The
3465
+ perspective acts as an exclusive lens: only open points relevant from
3466
+ this perspective are raised as questions, while every question still
3467
+ carries its focus area, severity, and impact. The active perspective
3468
+ is shown in the announcement line, like `GRILLING (security)`.
3469
+ Without a perspective, the grilling is holistic. Only effective together with `--grill`.
3470
+
3471
+ - `--grill-ground`|`-G`:
3472
+ Ground the grilling in facts instead of the world knowledge of the
3473
+ model alone: once before the first round, the artifacts of all kinds
3474
+ (`SPEC`, `CODE`, `DOCS`, `INFR`, and `OTHR`) are scanned for
3475
+ the project facts relevant to the grilled subject (from the given
3476
+ perspective, if any) and the Internet/Web is searched for the
3477
+ established practices, standards, patterns, and pitfalls about it.
3478
+ These facts serve all rounds, both for raising the questions and for
3479
+ preferably deriving their answer alternatives. The grounding is shown
3480
+ in the announcement line, like `GRILLING (security, grounded)`. If
3481
+ no usable facts are found, a warning is shown and the grilling falls
3482
+ back to model knowledge. Only effective together with `--grill`.
3310
3483
 
3311
3484
  - `--verify`|`-v`:
3312
3485
  Verify the edited specification by validating it via *SpecBook*
@@ -3315,14 +3488,22 @@ timestamp refreshed.
3315
3488
  the last round are listed as `REMAINING DIAGNOSTICS`. Without
3316
3489
  `--verify`, strictly no validation is performed at all.
3317
3490
 
3318
- - `--worktree`|`-w`:
3319
- Apply the change sets inside a dedicated Git worktree (as
3320
- `ase-task-implement --worktree`) instead of the current working
3321
- copy. One single worktree, named by a two-word id derived from the
3322
- first query, serves the whole skill run: all `--loop` iterations
3323
- land in it and it is left uncommitted for review. Under `--verify`,
3324
- the validation then runs as the `ase spec lint` command inside the
3325
- worktree.
3491
+ - `--worktree`|`-w` *name*[`:`*branch*]:
3492
+ Apply the change sets inside the dedicated Git worktree
3493
+ `.ase/worktree/<name>` instead of the current working copy. The
3494
+ worktree is *reused* if it already exists -- then switched to
3495
+ *branch* if given and it has no uncommitted changes --, otherwise
3496
+ it is *created* with the branch *branch* (default: *name*),
3497
+ checked out if it exists or created from `HEAD` otherwise. One
3498
+ single worktree serves the whole skill run: it is prepared before
3499
+ the first discovery, so discovering, grilling, and implementing all
3500
+ operate on it, all `--loop` iterations land in it, and it is left
3501
+ uncommitted for review. Under
3502
+ `--verify`, the validation then runs as the `ase spec lint` command
3503
+ inside the worktree. If *name* is a bare lower-case word naming no
3504
+ existing worktree and a *query* follows (like `-w fix the crash`, a
3505
+ former boolean `-w` usage), the skill asks whether *name* is the
3506
+ worktree name or the first query word.
3326
3507
 
3327
3508
  - `--loop`|`-l`:
3328
3509
  Loop the whole state cycle: after each iteration, ask for the next
@@ -3343,6 +3524,7 @@ timestamp refreshed.
3343
3524
  - You want `SPEC` changes without the task plan ceremony
3344
3525
  - You want the query stress-tested by grilling before the spec is edited
3345
3526
  - You want specification edits validated by SpecBook linting
3527
+ - You want the change set to land on a specific Git branch or worktree
3346
3528
 
3347
3529
  ## EXAMPLES
3348
3530
 
@@ -3358,10 +3540,24 @@ Grill the query with two rounds first, then edit and validate:
3358
3540
  ❯ /ase-spec-edit -g -r 2 -v split the Event entity into Event and EventSeries
3359
3541
  ```
3360
3542
 
3543
+ Let the user pick one of several specification approaches first, then
3544
+ edit:
3545
+
3546
+ ```text
3547
+ ❯ /ase-spec-edit -a model the access permissions of the personas
3548
+ ```
3549
+
3550
+ Grill the query exclusively from the domain perspective, grounded in
3551
+ the project artifacts and the Internet/Web, then edit:
3552
+
3553
+ ```text
3554
+ ❯ /ase-spec-edit -g -p domain -G add recurring events to the Event model
3555
+ ```
3556
+
3361
3557
  Loop over multiple specification edits inside a dedicated Git worktree:
3362
3558
 
3363
3559
  ```text
3364
- ❯ /ase-spec-edit -l -w
3560
+ ❯ /ase-spec-edit -l -w event-series
3365
3561
  ```
3366
3562
 
3367
3563
  </purpose>
@@ -3666,6 +3862,123 @@ specification as a unified diff, without applying it:
3666
3862
  ❯ /ase-sync-reconcile -d -t CODE -s SPEC
3667
3863
  ```
3668
3864
 
3865
+ </purpose>
3866
+ <purpose name="ase-task-assign">
3867
+
3868
+ ## NAME
3869
+
3870
+ `ase-task-assign` - Assign a Task Plan
3871
+
3872
+ ## SYNOPSIS
3873
+
3874
+ `ase-task-assign`
3875
+ [`--help`|`-h`]
3876
+ [*id*`:`] *assignee*
3877
+
3878
+ ## DESCRIPTION
3879
+
3880
+ The `ase-task-assign` skill assigns a *task plan* to an *assignee*, i.e.
3881
+ sets its `Assignee:` frontmatter key, via the `ase_task_assign` MCP tool,
3882
+ leaving its `Modified:` key alone, as that key tracks changes of the plan
3883
+ body only. Additionally, it *accounts* the *AI usage* of the session onto
3884
+ the task:
3885
+
3886
+ - Assigning the task to *oneself* (`me` or the current user id) opens
3887
+ the *usage window* of the task, or attaches the session to an already
3888
+ open one (e.g. of a previous session). From then on, all turns of the
3889
+ session are accounted: the AI request time, the cache read, cache
3890
+ write, input, and output tokens, and the costs, as reported by the
3891
+ agent tool via *OpenTelemetry* to the ASE service, plus, in addition,
3892
+ the human time (the whole real time of the window, as the engineer
3893
+ costs money even while waiting for the AI) and its costs at the
3894
+ hourly rate of the assignee in `telemetry.prices.hr` (default: 110 USD).
3895
+
3896
+ - Assigning the task to *anybody else*, or to *nobody* with `none`
3897
+ (removing the `Assignee:` key), *gives it back*: it closes the usage
3898
+ window and, after a grace period of 10 seconds for late telemetry,
3899
+ adds the accumulated usage to the usage attachment of the task
3900
+ (`Type: application/yaml; kind="usage"`), whose YAML data carries the
3901
+ amounts `time: { ai, hr, real }` (minutes), `token: { cread, cwrite,
3902
+ input, output }` (counts), and `cost: { ai, hr }` (USD). Each
3903
+ booking *adds* to the existing amounts, atomically, so concurrent
3904
+ changes of the task (e.g. by the agents of `ase agent`) are never lost.
3905
+
3906
+ A usage window also closes and books when its last session *ends*, and
3907
+ when the `Assignee:` of the task is changed *elsewhere* (e.g. on the task
3908
+ board) while the task is the current task of the session. Conversely,
3909
+ changing the `Assignee:` of a task to oneself *elsewhere* (e.g. on the
3910
+ task board) opens its usage window, too, and attaches every session of
3911
+ the project whose current task it is (also a session switching to it,
3912
+ or starting with it, later on), with the window starting *paused*, i.e.,
3913
+ accounting from the next AI request of its sessions on. An *unassigned*
3914
+ task is even accounted *implicitly*, without any assignment: while it is
3915
+ the current task of a session, the session is attached to its usage
3916
+ window in the same way, until the session switches to another task, the
3917
+ task gets assigned to anybody else, or the session ends (configurable via
3918
+ `telemetry.implicit`, default: `true`, never for task `default`), so
3919
+ explicitly assigning a task to oneself is needed only for claiming it,
3920
+ e.g. against the agents of `ase agent`. Long windows
3921
+ additionally book every `telemetry.service.interval` minutes (default: 10).
3922
+ Without any AI request for `telemetry.service.idle` minutes (default: 30),
3923
+ a usage window *pauses*, and the next AI request (of any kind, not just
3924
+ ASE skills) silently *resumes* it, so forgetting a task assigned to
3925
+ oneself does not account an idle session endlessly. A usage window without
3926
+ any AI request for 7 days is closed and booked.
3927
+
3928
+ The accounting is *opt-in*: it requires the configuration key
3929
+ `telemetry.enabled` to be `true` (via `ase config set telemetry.enabled
3930
+ true`) and the telemetry export of the agent tool to be activated once
3931
+ via `ase setup telemetry activate --tool` *tool*, otherwise only the
3932
+ assignee is set and a `NOTICE` is reported. If *id*`:` is omitted, the *current* task id
3933
+ (inherited from the session context) is used, otherwise, on a successful
3934
+ assignment to *oneself*, the current task id of the session is switched
3935
+ to *id*.
3936
+
3937
+ ## ARGUMENTS
3938
+
3939
+ - *id*`:`:
3940
+ The unique identifier of the task plan, with a trailing colon.
3941
+ If omitted, the current task id is used.
3942
+
3943
+ - *assignee*:
3944
+ The assignee: `me` for oneself, `none` for nobody, or any other
3945
+ name of a human or agent. If the configuration key `project.users`
3946
+ lists the known users, a name which is neither one of them nor the
3947
+ name of an agent present at the agent relay is still assigned, but
3948
+ reported with a `NOTICE`.
3949
+
3950
+ ## SCENARIOS
3951
+
3952
+ - You start working on a task and want its AI usage tracked
3953
+ - You hand a task over to a colleague or an agent, booking your usage
3954
+ - You want to know the AI time, tokens, and costs spent on a task
3955
+
3956
+ ## EXAMPLES
3957
+
3958
+ Take the current task plan and track the AI usage of the session:
3959
+
3960
+ ```text
3961
+ ❯ /ase-task-assign me
3962
+ ```
3963
+
3964
+ Take a specific task plan:
3965
+
3966
+ ```text
3967
+ ❯ /ase-task-assign hello: me
3968
+ ```
3969
+
3970
+ Give the task plan back to a colleague, booking the AI usage:
3971
+
3972
+ ```text
3973
+ ❯ /ase-task-assign alice
3974
+ ```
3975
+
3976
+ Unassign the task plan, booking the AI usage:
3977
+
3978
+ ```text
3979
+ ❯ /ase-task-assign hello: none
3980
+ ```
3981
+
3669
3982
  </purpose>
3670
3983
  <purpose name="ase-task-condense">
3671
3984
 
@@ -3686,13 +3999,15 @@ The `ase-task-condense` skill *compresses* the wording of an existing
3686
3999
  task plan to make it require as little reading as possible, while
3687
4000
  keeping *all semantics fully preserved and unchanged*. It loads the
3688
4001
  current (or given) plan, applies a self-contained, telegrapher-like
3689
- "remove-fluff" ruleset to the *free-text* parts only (the `**WHAT**` /
3690
- `**WHY**` prose and each bullet's specification text), and writes the
3691
- shorter plan back via `ase_task_save`.
3692
-
3693
- The plan *structure* is never altered: all headings, section markers,
3694
- `- **<aspect>**:` bullet labels, code spans, technical terms, file
3695
- paths, numbers, and severities are kept exactly. Only genuinely
4002
+ "remove-fluff" ruleset to the *free-text* parts only (the text of each
4003
+ `DOM`, `IFC`, `ARC`, `IMP`, `REG`, and `CON` bullet point), and writes
4004
+ the shorter plan back via `ase_task_save`.
4005
+
4006
+ The plan *structure* is never altered: the frontmatter, all headings,
4007
+ the `SPECIFICATION (WHAT)`, `DESIGN (HOW)`, and `VERIFICATION (WHEN)`
4008
+ sections, the `- [ ] DOM:`-style bullet prefixes with their checkbox
4009
+ states, all attachments, code spans, technical terms, file paths,
4010
+ numbers, and severities are kept exactly. Only genuinely
3696
4011
  redundant bullets may be merged, and a shortening that would change
3697
4012
  meaning is always rejected in favor of the longer wording. The condense
3698
4013
  ruleset *overrides* the active session persona, so the plan is compressed
@@ -3703,8 +4018,8 @@ further reduction is possible, the plan is left untouched (including its
3703
4018
  `Modified:` frontmatter timestamp) and reported as *already condensed*.
3704
4019
 
3705
4020
  After condensing, the user is asked whether to stop or hand off to
3706
- `ase-task-edit`, `ase-task-implement`, or `ase-task-preflight`, unless
3707
- `--next` pre-selects this choice.
4021
+ `ase-task-edit` or `ase-task-implement` (optionally with `--draft`),
4022
+ unless `--next` pre-selects this choice.
3708
4023
 
3709
4024
  ## OPTIONS
3710
4025
 
@@ -3717,7 +4032,7 @@ After condensing, the user is asked whether to stop or hand off to
3717
4032
  Recognized tokens at this skill: `none` (default, interactive
3718
4033
  answer required), `DONE` (stop), `EDIT` (hand off to
3719
4034
  `ase-task-edit`), `IMPLEMENT` (hand off to `ase-task-implement`),
3720
- or `PREFLIGHT` (hand off to `ase-task-preflight`). Example:
4035
+ or `DRAFT` (hand off to `ase-task-implement --draft`). Example:
3721
4036
  `--next EDIT,DONE` condenses, hands off to editing, and the editing
3722
4037
  loop will exit immediately.
3723
4038
 
@@ -3820,8 +4135,9 @@ it can be implemented, reviewed, and committed entirely on its own.
3820
4135
 
3821
4136
  The dissection follows a strict ruleset: at least *2* and at most
3822
4137
  *count* parts are derived, *every* bullet point of the epic's
3823
- `## CHANGES` and `## VERIFICATION` sections is assigned to *exactly
3824
- one* part, mutually dependent bullet points are kept together, and
4138
+ `## SPECIFICATION (WHAT)`, `## DESIGN (HOW)`, and
4139
+ `## VERIFICATION (WHEN)` sections is assigned to *exactly one* part,
4140
+ mutually dependent bullet points are kept together, and
3825
4141
  nothing beyond the epic's own content is invented. A bullet point which
3826
4142
  itself covers *multiple* domains is *split* into fragments, which are
3827
4143
  then assigned individually -- together they still reproduce the original
@@ -3840,9 +4156,11 @@ never the ruleset itself.
3840
4156
  The derived parts are first reported as a *dissection table* (part
3841
4157
  number, sub-task id, scope, and rationale). Then -- unless `--dry` is
3842
4158
  given -- each part is materialized as its own *complete* sub-task plan
3843
- (with its own `## CONTEXT`, `## CHANGES`, and `## VERIFICATION`
3844
- sections) and persisted under the task id `<task-id>-<feature-slug>`.
3845
- The epic plan itself always stays *untouched*.
4159
+ (with its own `## SPECIFICATION (WHAT)`, `## DESIGN (HOW)`, and
4160
+ `## VERIFICATION (WHEN)` sections, grouped under the epic via its
4161
+ `Group:` frontmatter key) and persisted under the task id
4162
+ `<task-id>-<feature-slug>`. The epic plan itself always stays
4163
+ *untouched*.
3846
4164
 
3847
4165
  ## OPTIONS
3848
4166
 
@@ -3852,9 +4170,7 @@ The epic plan itself always stays *untouched*.
3852
4170
 
3853
4171
  - `--dry`|`-d`:
3854
4172
  *Report only* -- print the dissection table but create *no*
3855
- artifacts at all, so the decision stays fully reversible. Note that
3856
- this meaning differs from `--dry`/`-d` in `ase-code-craft`, where it
3857
- instead omits the `## VERIFICATION` section of the composed plan.
4173
+ artifacts at all, so the decision stays fully reversible.
3858
4174
 
3859
4175
  - `--force`|`-f`:
3860
4176
  Overwrite already existing sub-task plans. Without this option, the
@@ -3914,101 +4230,329 @@ Dissect a specific task plan with a hint:
3914
4230
  ```
3915
4231
 
3916
4232
  </purpose>
3917
- <purpose name="ase-task-edit">
4233
+ <purpose name="ase-task-edit">
4234
+
4235
+ ## NAME
4236
+
4237
+ `ase-task-edit` - Iteratively Edit a Task Plan
4238
+
4239
+ ## SYNOPSIS
4240
+
4241
+ `ase-task-edit`
4242
+ [`--help`|`-h`]
4243
+ [`--plan`|`-p` *option*]
4244
+ [`--mode`|`-m` `auto`|`craft`|`refactor`|`resolve`|`specify`]
4245
+ [`--approach`|`-a`]
4246
+ [`--unverified`|`-u`]
4247
+ [`--next`|`-n` *option*[,...]]
4248
+ [*id* | *id*: *instruction* | *instruction* | *issue-id*]
4249
+
4250
+ ## DESCRIPTION
4251
+
4252
+ The `ase-task-edit` skill establishes and refines a *task plan* purely
4253
+ through a *chat-driven loop*. The user steers each round via an
4254
+ interactive dialog that offers continued refinement, finalization, or
4255
+ hand-off to implementation or draft. It covers the planning of all
4256
+ kinds of change: crafting a new feature, refactoring the code base,
4257
+ resolving a problem, and specifying.
4258
+
4259
+ A newly generated plan is grounded in the relevant specification
4260
+ (`SPEC`), source code (`CODE`), and infrastructure (`INFR`) files of the
4261
+ project: it names the actual files and symbols to change, the actual
4262
+ build, lint, and test procedures, and a `CHANGELOG.md` entry if such a
4263
+ file exists.
4264
+
4265
+ Before a new plan is generated, the skill determines its *kind of
4266
+ change* (stored in the `Kind:` key of the plan) and internalizes the
4267
+ corresponding tenets (for example KISS, YAGNI, and DRY for crafting,
4268
+ or Surgical Changes and Origin Proximity for resolving). For a
4269
+ resolution, it first reports the `PROBLEM CONTEXT` and `PROBLEM
4270
+ DETAILS`. Under `--approach`, it then proposes one or more *approaches*
4271
+ with pros and cons, recommends one of them, and lets the user pick the
4272
+ preferred one via an interactive dialog, and the new plan is then
4273
+ composed along the chosen approach.
4274
+
4275
+ If the current task is `default` and a new plan is generated from an
4276
+ *instruction*, a new task id is allocated from the instruction
4277
+ according to the task id scheme of the project, so the plan does not
4278
+ end up under `default`.
4279
+
4280
+ Attachments in the plan's backmatter are never removed by a refinement.
4281
+ A refinement which changes an attachment refreshes the attachment's
4282
+ `Modified:` key; a refinement which changes the plan body refreshes the
4283
+ `Modified:` key of the frontmatter (which tracks body changes only, so
4284
+ a refinement of frontmatter keys alone leaves it untouched); both use
4285
+ the same value. An implementation draft (an attachment block of type
4286
+ `text/x-diff; charset=utf-8; kind="draft"`, produced by
4287
+ `ase-task-implement --draft`) whose `Modified:` key is absent or older
4288
+ than the frontmatter's is *stale*: it is reported with a warning after
4289
+ each rendering of the plan, together with a hint that
4290
+ `ase-task-implement --draft` has to be run again to re-create the
4291
+ draft for the changed plan, as `ase-task-integrate --draft` refuses a
4292
+ stale draft.
4293
+
4294
+ ## OPTIONS
4295
+
4296
+ - `--plan`|`-p` *option*:
4297
+ Automatically answer the user dialog for the plan refinement
4298
+ with *option*, which can be either `none` (default, interactive
4299
+ answer required), `OVERWRITE` (overwrite an existing plan
4300
+ with *instruction*), `REFINE` (refine the existing plan with
4301
+ *instruction*), or `PRESERVE` (preserve the existing plan by
4302
+ ignoring *instruction* and stopping skill processing).
4303
+
4304
+ - `--mode`|`-m` `auto`|`craft`|`refactor`|`resolve`|`specify`:
4305
+ Select the kind of change of the plan: `craft` (`CRAFTING`),
4306
+ `refactor` (`REFACTORING`), `resolve` (`RESOLVING`), or `specify`
4307
+ (`SPECIFYING`). It selects the tenets internalized when the plan is
4308
+ generated or refined and sets the `Kind:` key of the plan, also on
4309
+ a refinement. The default `auto` infers the kind of a new plan from
4310
+ the *instruction*, uses `RESOLVING` for an *issue-id* (also on a
4311
+ refinement), and otherwise leaves the `Kind:` key of an existing
4312
+ plan as it is and honors its tenets.
4313
+
4314
+ - `--approach`|`-a`:
4315
+ Before a new plan is composed, propose one or more crafting,
4316
+ refactoring, resolution, or specification approaches with pros and
4317
+ cons, recommend one of them, and let the user pick the preferred one
4318
+ via an interactive dialog (or, under the `black` project boxing or
4319
+ in headless mode, automatically pick the recommended one). The new
4320
+ plan is then composed along the chosen approach. Without
4321
+ `--approach`, no approaches are determined at all.
4322
+
4323
+ - `--unverified`|`-u`:
4324
+ Generate any *new* plan *without* the `## VERIFICATION (WHEN)` section.
4325
+ Applies only to freshly generated plans, not to existing plans
4326
+ loaded from disk. When `ase-task-implement` later applies such
4327
+ a plan, it strictly skips the entire verification phase (no
4328
+ build, tests, linter, type-checker, or program execution) once
4329
+ the source files have been modified.
4330
+
4331
+ - `--next`|`-n` *option*[,...]:
4332
+ Automatically answer the user dialog for the next step (at the end
4333
+ of this skill). *option* is a single token or a *comma-separated
4334
+ chronological list* of tokens; each iteration of the planning
4335
+ loop consumes the *first* token of the list, and on hand-off
4336
+ (`IMPLEMENT` / `DRAFT`) any remaining tokens are *forwarded*
4337
+ (via `--next`) to the downstream skill so an entire pipeline can
4338
+ be pre-scripted in one shot. Recognized tokens at this skill:
4339
+ `none` (default, interactive answer required), `DONE` (no next
4340
+ step), `GRILL` (hand-over to `ase-task-grill`), `DRAFT`
4341
+ (hand-over to `ase-task-implement --draft`), or `IMPLEMENT` (hand-over to
4342
+ `ase-task-implement`). Example: `--next GRILL,DONE` hands the plan
4343
+ off to grilling and forwards `DONE` so grilling exits without asking.
4344
+
4345
+ ## ARGUMENTS
4346
+
4347
+ - *id* | *id*: *instruction* | *instruction* | *issue-id*:
4348
+ Edit the task with the unique identifier *id* (default: the current
4349
+ task). Optionally, *instruction* either gives instructions for
4350
+ creating a new task or gives instructions for refining an existing
4351
+ task. Instead, a bare *issue-id* (like `P1`, `T1`, or
4352
+ `<prefix>-P1`), previously reported by `ase-code-analyze` or
4353
+ `ase-arch-analyze`, uses the description of this issue as the
4354
+ *instruction* (also as *id*: *issue-id*), and the issue is removed
4355
+ once the plan is saved. If no such issue exists, *issue-id* is
4356
+ treated as a task *id* resp. as an *instruction*.
4357
+
4358
+ ## SCENARIOS
4359
+
4360
+ - You want a task planned through chat-driven refinement
4361
+ - You want a plan created or refined round by round
4362
+ - You want approaches with pros and cons before a plan is composed
4363
+ - You want a plan to craft a feature, refactor code, or resolve a problem
4364
+ - You want an analyzer issue like `P1` turned into a plan
4365
+ - You want plan refinement with hand-off to draft or implementation
4366
+
4367
+ ## EXAMPLES
4368
+
4369
+ Edit the current task:
4370
+
4371
+ ```text
4372
+ ❯ /ase-task-edit
4373
+ ```
4374
+
4375
+ Create a new task under id `hello`:
4376
+
4377
+ ```text
4378
+ ❯ /ase-task-delete hello
4379
+ ❯ /ase-task-edit hello: new "ase hello" CLI command which prints
4380
+ a nice "Hello World!" to the terminal in color blue.
4381
+ ```
4382
+
4383
+ Further refine the task under id `hello`:
4384
+
4385
+ ```text
4386
+ ❯ /ase-task-edit hello: change the color to red.
4387
+ ```
4388
+
4389
+ Plan the resolution of the analyzer issue `P1` along an interactively
4390
+ chosen approach, and directly hand off to implementation:
4391
+
4392
+ ```text
4393
+ ❯ /ase-task-edit --approach --next IMPLEMENT P1
4394
+ ```
4395
+
4396
+ Plan a refactoring under the id `cleanup`:
4397
+
4398
+ ```text
4399
+ ❯ /ase-task-edit -m refactor cleanup: extract HTTP client into its own class
4400
+ ```
4401
+
4402
+ </purpose>
4403
+ <purpose name="ase-task-estimate">
3918
4404
 
3919
4405
  ## NAME
3920
4406
 
3921
- `ase-task-edit` - Iteratively Edit a Task Plan
4407
+ `ase-task-estimate` - Estimate the Effort of a Task Plan
3922
4408
 
3923
4409
  ## SYNOPSIS
3924
4410
 
3925
- `ase-task-edit`
4411
+ `ase-task-estimate`
3926
4412
  [`--help`|`-h`]
3927
- [`--plan`|`-p` *option*]
3928
- [`--dry`|`-d`]
3929
- [`--next`|`-n` *option*[,...]]
3930
- [*id* | *id*: *instruction* | *instruction*]
4413
+ [`--force`|`-f`]
4414
+ [`--dry-run`|`-d`]
4415
+ [`--all`|`-a`]
4416
+ [*id* ...]
3931
4417
 
3932
- ## DESCRIPTION
4418
+ `ase-task-estimate`
4419
+ `--calibrate`|`-c`
4420
+ [`--save`|`-s`]
3933
4421
 
3934
- The `ase-task-edit` skill establishes and refines a *task plan* purely
3935
- through a *chat-driven loop*. The user steers each round via an
3936
- interactive dialog that offers continued refinement, finalization, or
3937
- hand-off to implementation or preflight.
4422
+ ## DESCRIPTION
3938
4423
 
3939
- When a refinement changes the plan text while an `IMPLEMENTATION
3940
- DRAFT` section (produced by `ase-task-preflight`) exists, that section
3941
- became *stale* and is *removed* -- together with the `preflighted`
3942
- value of the `Properties:` frontmatter key -- and a hint is emitted
3943
- that `ase-task-preflight` has to be run again to re-create the draft
3944
- for the changed plan.
4424
+ The `ase-task-estimate` skill *estimates* the effort of task plans and
4425
+ stores it in their `Effort:` frontmatter key. The effort is the expected
4426
+ *human time* of the *entire* lifecycle of a task (including its
4427
+ planning), matching the human time `time.hr` booked on the usage
4428
+ attachment of the task (see `ase-task-assign`), expressed as one of the
4429
+ T-shirt sizes `XS`, `S`, `M`, `L`, or `XL`. The sizes are bands on a
4430
+ *logarithmic* scale with the upper bounds `15`, `60`, `240`, and `960`
4431
+ human minutes for `XS` to `L` (configuration `project.task.effort.scale`),
4432
+ while `XL` is open-ended. A task without an `Effort:` key is *not
4433
+ estimated*.
4434
+
4435
+ The estimation of a plan combines:
4436
+
4437
+ - an *attention score*: the weighted number of the distinct
4438
+ requirements, behaviors, or changes stated by its checklist items
4439
+ (`DOM` 5.0, `IFC` 4.0, `ARC` 3.0, `IMP` 1.0, `REG` 0.5, `CON` 1.0),
4440
+ converted via `project.task.effort.factor` (default: `1`) human
4441
+ minutes per point,
4442
+
4443
+ - a *volume score*: the code impact of its `ARC` and `IMP` items,
4444
+ predicted read-only from the plan and the code base (never measured
4445
+ from an already existing change set), converted via
4446
+ `project.task.effort.file` (default: `1`) human review minutes per
4447
+ touched file and `project.task.effort.line` (default: `0.025`)
4448
+ human minutes per predicted changed line, which also cover the edge
4449
+ cases and polishing no plan describes, where a newly written line
4450
+ weighs three times a changed one,
4451
+
4452
+ - a *risk surcharge*: 20% more per applying risk out of `dependency`,
4453
+ `ambiguity`, `untested`, `concurrency`, `security`, and
4454
+ `persistence`, but at most 40% in total, where risks applying to
4455
+ virtually every task of the project do not count,
4456
+
4457
+ - an *iteration multiplier*: `project.task.effort.iteration`
4458
+ (default: `2.5`) times the minutes for a task whose main
4459
+ deliverable is an interactive or visual user interface, as such
4460
+ work needs many rounds of post-adjustment,
4461
+
4462
+ - a *plausibility check*: a comparable realization already existing
4463
+ in the code base, whose deviating size lowers the reported
4464
+ *confidence*, and
4465
+
4466
+ - *analogues*: finished tasks with an effort and a usage attachment,
4467
+ whose disagreement lowers the reported *confidence*.
4468
+
4469
+ Cancelled (`[-]`) and deferred (`[>]`) items never count. The skill
4470
+ reports the size, the confidence, and the main drivers of each
4471
+ estimation, and for `XL` additionally warns and suggests splitting the
4472
+ task via `ase-task-dissect` -- an `XL` effort never blocks the
4473
+ lifecycle.
4474
+
4475
+ The effort is *bound* to the plan content it was given for: once the
4476
+ plan content changes, the effort becomes *invalid* and is dropped, while
4477
+ mere checkbox state changes and whitespace-only edits keep it. Hence,
4478
+ an estimation never needs to be cleaned up by hand. Writing the effort
4479
+ neither changes the `Modified:` key nor the lifecycle status of a task.
4480
+ Empty plans and explicit epic tasks (whose effort is the sum of their
4481
+ member tasks) are skipped, and so are tasks already carrying a valid
4482
+ effort, unless `--force` is given.
4483
+
4484
+ With `--calibrate`, the skill instead re-estimates the successfully
4485
+ finished tasks with the *current* rates and compares the results with
4486
+ their *actual* human time (only tasks with at least `5` human minutes
4487
+ count, as agent-driven tasks book little human time), so a repeated
4488
+ calibration converges, and reports the estimated vs. actual band matrix,
4489
+ the hit rate, the bias, the best-fitting rates (factor, file, and line
4490
+ minutes), and alternatively fitting scale bounds.
4491
+
4492
+ The `ase agent estimator` command estimates the tasks automatically in
4493
+ the background, and with `--mode request` on request, in any unfinished
4494
+ status, via `ase task request <id> estimate <prompt>` or key `R` of the
4495
+ task boards.
3945
4496
 
3946
4497
  ## OPTIONS
3947
4498
 
3948
- - `--plan`|`-p` *option*:
3949
- Automatically answer the user dialog for the plan refinement
3950
- with *option*, which can be either `none` (default, interactive
3951
- answer required), `OVERWRITE` (overwrite an existing plan
3952
- with *instruction*), `REFINE` (refine the existing plan with
3953
- *instruction*), or `PRESERVE` (preserve the existing plan by
3954
- ignoring *instruction* and stopping skill processing).
4499
+ - `--force`|`-f`:
4500
+ Re-estimate tasks which already carry a valid effort.
3955
4501
 
3956
- - `--dry`|`-d`:
3957
- Generate any *new* plan *without* the `## VERIFICATION` section.
3958
- Applies only to freshly generated plans, not to existing plans
3959
- loaded from disk. When `ase-task-implement` later applies such
3960
- a plan, it strictly skips the entire verification phase (no
3961
- build, tests, linter, type-checker, or program execution) once
3962
- the source files have been modified.
4502
+ - `--dry-run`|`-d`:
4503
+ Estimate and report only, but do not store the effort.
3963
4504
 
3964
- - `--next`|`-n` *option*[,...]:
3965
- Automatically answer the user dialog for the next step (at the end
3966
- of this skill). *option* is a single token or a *comma-separated
3967
- chronological list* of tokens; each iteration of the planning
3968
- loop consumes the *first* token of the list, and on hand-off
3969
- (`IMPLEMENT` / `PREFLIGHT`) any remaining tokens are *forwarded*
3970
- (via `--next`) to the downstream skill so an entire pipeline can
3971
- be pre-scripted in one shot. Recognized tokens at this skill:
3972
- `none` (default, interactive answer required), `DONE` (no next
3973
- step), `GRILL` (hand-over to `ase-task-grill`), `PREFLIGHT`
3974
- (hand-over to `ase-task-preflight`), or `IMPLEMENT` (hand-over to
3975
- `ase-task-implement`). Example: `--next GRILL,DONE` hands the plan
3976
- off to grilling and forwards `DONE` so grilling exits without asking.
4505
+ - `--all`|`-a`:
4506
+ Estimate all unfinished tasks without a valid effort (with `--force`,
4507
+ all unfinished tasks), instead of the current or given ones.
4508
+
4509
+ - `--calibrate`|`-c`:
4510
+ Report the calibration of the estimation against the finished tasks
4511
+ instead of estimating any task.
4512
+
4513
+ - `--save`|`-s`:
4514
+ Together with `--calibrate`, store the fitted rates as
4515
+ `project.task.effort.factor`, `project.task.effort.file`, and
4516
+ `project.task.effort.line` on the `project` scope. The fitted scale
4517
+ bounds always stay a suggestion only.
3977
4518
 
3978
4519
  ## ARGUMENTS
3979
4520
 
3980
- - *id* | *id*: *instruction* | *instruction*:
3981
- Edit the task with the unique identifier *id* (default: `default`).
3982
- Optionally, *instruction* either gives instructions for creating a
3983
- new task or gives instructions for refining an existing task.
4521
+ - *id* ...:
4522
+ The unique identifiers of the tasks to estimate. If omitted (and
4523
+ without `--all`), the *current* task is estimated.
3984
4524
 
3985
4525
  ## SCENARIOS
3986
4526
 
3987
- - You want a task planned through chat-driven refinement
3988
- - You want a plan created or refined round by round
3989
- - You want a plan iterated on before implementing it
3990
- - You want plan refinement with hand-off to preflight or implementation
4527
+ - You want to know how much human time a planned task will need
4528
+ - You want to size all open tasks for planning a sprint or release
4529
+ - You want to check whether a task is too large and should be split
4530
+ - You want to tune the estimation to the actual pace of your team
3991
4531
 
3992
4532
  ## EXAMPLES
3993
4533
 
3994
- Edit the current task:
4534
+ Estimate the current task plan:
3995
4535
 
3996
4536
  ```text
3997
- ❯ /ase-task-edit
4537
+ ❯ /ase-task-estimate
3998
4538
  ```
3999
4539
 
4000
- Create a new task under id `hello`:
4540
+ Estimate all unestimated tasks, without storing the results:
4001
4541
 
4002
4542
  ```text
4003
- ❯ /ase-task-delete hello
4004
- ❯ /ase-task-edit hello: new "ase hello" CLI command which prints
4005
- a nice "Hello World!" to the terminal in color blue.
4543
+ ❯ /ase-task-estimate --all --dry-run
4006
4544
  ```
4007
4545
 
4008
- Further refine the task under id `hello`:
4546
+ Re-estimate two specific tasks:
4009
4547
 
4010
4548
  ```text
4011
- ❯ /ase-task-edit hello: change the color to red.
4549
+ ❯ /ase-task-estimate --force export-json import-csv
4550
+ ```
4551
+
4552
+ Calibrate the estimation and store the fitted rates:
4553
+
4554
+ ```text
4555
+ ❯ /ase-task-estimate --calibrate --save
4012
4556
  ```
4013
4557
 
4014
4558
  </purpose>
@@ -4023,6 +4567,11 @@ Further refine the task under id `hello`:
4023
4567
  `ase-task-grill`
4024
4568
  [`--help`|`-h`]
4025
4569
  [`--rounds`|`-r` *n*]
4570
+ [`--until`|`-u` `MUST`|`SHOULD`|`MAY`]
4571
+ [`--perspective`|`-p` *perspective*]
4572
+ [`--ground`|`-G`]
4573
+ [`--focus`|`-f` *section*[,...]]
4574
+ [`--force`|`-F`]
4026
4575
  [`--next`|`-n` *option*[,...]]
4027
4576
  [*id*]
4028
4577
 
@@ -4037,37 +4586,114 @@ The skill identifies the essential aspects of the plan and raises up to
4037
4586
  carries a `FOCUS-AREA` -- `DOMAIN` (domain-specifics, must be
4038
4587
  clarified), `INTERFACE` (externally observable behavior or UI/API
4039
4588
  interfaces, must be clarified), `ARCHITECTURE` (structure, wiring,
4040
- placement, or dependencies, should be clarified), or `IMPLEMENTATION`
4041
- (inner technical details, can be clarified) -- and a 1-2 word `ASPECT`
4042
- hint. The questions are sorted primarily by descending focus area
4043
- importance (`DOMAIN`, `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`)
4044
- and secondarily by the decision tree of their dependencies, so each
4589
+ placement, or dependencies, should be clarified), `IMPLEMENTATION`
4590
+ (inner technical details, can be clarified), `REGRESSION` (what must
4591
+ not break, should be clarified), or `CONFIRMATION` (what proves the
4592
+ specified behavior, should be clarified) -- and a 1-3 word `TOPIC`
4593
+ hint. The focus areas are selected by the plan sections under focus
4594
+ (`--focus`): `SPECIFICATION` selects `DOMAIN` and `INTERFACE`, `DESIGN`
4595
+ selects `ARCHITECTURE` and `IMPLEMENTATION`, and `VERIFICATION` selects
4596
+ `REGRESSION` and `CONFIRMATION`. The questions are sorted
4597
+ by descending focus area importance, then by descending individual
4598
+ impact, and finally by the decision tree of their dependencies, so each
4045
4599
  decision is asked after the decisions it depends on. It honors checks
4046
4600
  for *fuzzy language*, *conflicting terminology*, *conflicting code*,
4047
4601
  *non-concrete scenarios*, *unspecified architecture patterns*, and
4048
4602
  *unspecified dependencies*.
4049
4603
 
4050
- In contrast to the batch grilling of `ase-code-edit --grill`, the
4051
- questions are asked *sequentially*, one at a time: each question is
4052
- announced as an `ASPECT n/N ▶ FOCUS ▷ ASPECT, QUESTION` line and then
4053
- raised via an interactive dialog presenting two to four *grounded*
4054
- answer alternatives labeled `A1`-`A4` (the current plan, marked with
4055
- `⚑`, plus alternatives derived from the code base and world knowledge),
4056
- the fixed `SKIP GRILLING` option (skip the remaining questions and
4057
- rounds, keeping the answers gathered so far), and free-text input.
4058
- Cancelling the dialog stops the skill and leaves the plan untouched.
4059
- Once all aspects are resolved, the plan is updated and persisted, its
4060
- `Properties:` frontmatter key gains the value `grilled`, and the user is
4061
- offered a hand-off to editing, implementation, or preflight.
4604
+ As with `ase-code-edit --grill`, all questions of a round are announced
4605
+ together below a `GRILLING ROUND K/L` line (plain `GRILLING` for a
4606
+ single round) as a `QUESTION`/`ANSWERS` table with one row per
4607
+ question, each row carrying two to three *grounded* answer alternatives
4608
+ (the one reflecting the current plan marked with `⚑`). They are then
4609
+ asked in *one* batch via a single interactive dialog, whose only answer
4610
+ option is the fixed `SKIP GRILLING` (skip the remaining grilling, but
4611
+ still update the plan with the answers of the previous rounds), plus
4612
+ free-text input. The questions are numbered `1`, `2`, etc. and their
4613
+ answer alternatives are lettered `A`, `B`, etc., so the free-text input
4614
+ can cherry-pick answers with short responses matching `\d+[a-zA-Z]`
4615
+ (like `1A 2c`), freely mixed with keyword text. A question not
4616
+ addressed by the reply accepts its `⚑` answer, if one exists.
4617
+ Cancelling the dialog stops the skill without updating the plan with
4618
+ the current round. After every round, the plan is updated and
4619
+ persisted, its `Tags:` frontmatter key records each grilled section as
4620
+ its own tag `grilled:`*section* (lower-case, kept alongside the tags of
4621
+ previously grilled sections, e.g. `grilled:specification,
4622
+ grilled:design`), and a `PLAN CHANGES` box shows the bullet-points
4623
+ changed by the round. Finally, the user is offered a complete
4624
+ re-grilling (with the same grilling options), or a hand-off to editing,
4625
+ implementation, or draft.
4626
+
4627
+ The *open* questions are recorded in the checkboxes of the plan's
4628
+ bullet-points: a bullet-point whose question stayed *unanswered*
4629
+ (because the grilling was skipped, or the reply did not address a
4630
+ question the plan offers no answer for) is marked `[?]`, an unanswered
4631
+ question the plan does not cover yet is added as a new `[?]`
4632
+ bullet-point, and an *answered* question resets its bullet-points to
4633
+ `[ ]`. When a section is grilled *again* (its `grilled:`*section* tag
4634
+ is already present), only its `[?]` bullet-points are re-asked, and a
4635
+ section without any `[?]` bullet-point is skipped entirely, unless
4636
+ `--force` is given. Bullet-points
4637
+ in state `[-]` (cancelled) or `[>]` (deferred) are never questioned.
4062
4638
 
4063
4639
  ## OPTIONS
4064
4640
 
4065
4641
  - `--rounds`|`-r` *n*:
4066
- The number of grill rounds to apply (default: `1`). Each round
4067
- starts from scratch from only the current plan, as updated by all
4068
- previous rounds, and re-derives its questions from it, forgetting
4069
- all questions and answers of previous rounds. With more than one
4070
- round, each round is announced as `GRILLING ROUND K/L`.
4642
+ The *maximum* number of grill rounds to apply (default: `1`). Each
4643
+ round starts from scratch from only the current plan, as updated and
4644
+ saved by all previous rounds, and re-derives its questions from it,
4645
+ forgetting all questions and answers of previous rounds. With more than one
4646
+ round, each round is announced as `GRILLING ROUND K/L`. The grilling
4647
+ stops early -- announced by a `grilling finished early` status line
4648
+ -- once a round, even the first one, finds the open points clear
4649
+ enough according to `--until`.
4650
+
4651
+ - `--until`|`-u` `MUST`|`SHOULD`|`MAY`:
4652
+ Grill until at least all open points of the given severity or
4653
+ higher are clear (default: `MUST`), where the severity follows from
4654
+ the focus area: `MUST` (`DOMAIN`, `INTERFACE`), `SHOULD`
4655
+ (`ARCHITECTURE`, `REGRESSION`, `CONFIRMATION`), and `MAY`
4656
+ (`IMPLEMENTATION`). Independent of this, every open point is rated
4657
+ with an individual impact (`HIGH`, `MEDIUM`, or `LOW`), which
4658
+ decides which points are raised as questions and in which order
4659
+ within a focus area.
4660
+
4661
+ - `--perspective`|`-p` *perspective*:
4662
+ Grill exclusively from the logical *perspective* -- a keyword or
4663
+ short hint like `domain`, `performance`, or `security`. The
4664
+ perspective acts as an exclusive lens: only open points relevant from
4665
+ this perspective are raised as questions, while every question still
4666
+ carries its focus area, severity, and impact. The active perspective
4667
+ is shown in the announcement line, like `GRILLING (security)`.
4668
+ Without a perspective, the grilling is holistic.
4669
+
4670
+ - `--ground`|`-G`:
4671
+ Ground the grilling in facts instead of the world knowledge of the
4672
+ model alone: once before the first round, the artifacts of all kinds
4673
+ (`SPEC`, `CODE`, `DOCS`, `INFR`, and `OTHR`) are scanned for
4674
+ the project facts relevant to the grilled subject (from the given
4675
+ perspective, if any) and the Internet/Web is searched for the
4676
+ established practices, standards, patterns, and pitfalls about it.
4677
+ These facts serve all rounds, both for raising the questions and for
4678
+ preferably deriving their answer alternatives. The grounding is shown
4679
+ in the announcement line, like `GRILLING (security, grounded)`. If
4680
+ no usable facts are found, a warning is shown and the grilling falls
4681
+ back to model knowledge.
4682
+
4683
+ - `--focus`|`-f` *section*[,...]:
4684
+ Grill only the given plan *section*(s), in the given order. Each
4685
+ *section* is one of `SPECIFICATION` (abbreviated `SPEC`), `DESIGN`
4686
+ (abbreviated `DES`), or `VERIFICATION` (abbreviated `VER`), matched
4687
+ case-insensitively, or the sentinel `all` (default), which expands
4688
+ to `SPECIFICATION,DESIGN,VERIFICATION`. The questions are derived
4689
+ from the themes of the focused sections only, while the entire plan
4690
+ stays the context, and the answers may still update any section.
4691
+ An unknown, empty, or duplicate *section* token aborts the skill.
4692
+
4693
+ - `--force`|`-F`:
4694
+ Re-grill already grilled sections completely, i.e., ignore their
4695
+ `grilled:`*section* tags instead of skipping them resp. re-asking
4696
+ only their `[?]` bullet-points.
4071
4697
 
4072
4698
  - `--next`|`-n` *option*[,...]:
4073
4699
  Automatically answer the user dialog for the next step (at the end
@@ -4077,9 +4703,10 @@ offered a hand-off to editing, implementation, or preflight.
4077
4703
  to the downstream skill on hand-off so an entire pipeline can be
4078
4704
  pre-scripted in one shot. Recognized tokens at this skill: `none`
4079
4705
  (default, interactive answer required), `DONE` (no next step),
4080
- `EDIT` (hand-over to `ase-task-edit`), `IMPLEMENT` (hand-over to
4081
- `ase-task-implement`), or `PREFLIGHT` (hand-over to
4082
- `ase-task-preflight`).
4706
+ `GRILL` (re-grilling via `ase-task-grill --force` with the same
4707
+ grilling options), `EDIT` (hand-over to `ase-task-edit`),
4708
+ `IMPLEMENT` (hand-over to `ase-task-implement`), or `DRAFT`
4709
+ (hand-over to `ase-task-implement --draft`).
4083
4710
 
4084
4711
  ## ARGUMENTS
4085
4712
 
@@ -4115,6 +4742,26 @@ Grill the current task plan in two rounds:
4115
4742
  ❯ /ase-task-grill --rounds 2
4116
4743
  ```
4117
4744
 
4745
+ Grill the current task plan exclusively from the performance
4746
+ perspective, grounded in the project artifacts and the Internet/Web:
4747
+
4748
+ ```text
4749
+ ❯ /ase-task-grill --perspective performance --ground
4750
+ ```
4751
+
4752
+ Grill only the `DESIGN` and then the `SPECIFICATION` section of the
4753
+ current task plan:
4754
+
4755
+ ```text
4756
+ ❯ /ase-task-grill --focus DES,SPEC
4757
+ ```
4758
+
4759
+ Re-grill the already grilled current task plan completely:
4760
+
4761
+ ```text
4762
+ ❯ /ase-task-grill --force
4763
+ ```
4764
+
4118
4765
  Grill the current task plan and then hand off to editing:
4119
4766
 
4120
4767
  ```text
@@ -4144,8 +4791,11 @@ task id via the `ase_task_id` MCP tool.
4144
4791
  ## ARGUMENTS
4145
4792
 
4146
4793
  - *id*:
4147
- The new task id to activate. If omitted, the currently active
4148
- task id is reported.
4794
+ The new task id to activate (characters `A-Z`, `a-z`, `0-9`, `#`,
4795
+ `_`, and `-`). If omitted, the currently active task id is
4796
+ reported. An id not conforming to the task id scheme of the
4797
+ project (`project.task.idscheme`: `slug[:<words>]`, `seq[:<template>]`,
4798
+ or `any`) is accepted, but noticed.
4149
4799
 
4150
4800
  ## SCENARIOS
4151
4801
 
@@ -4179,50 +4829,103 @@ Switch to a specific task:
4179
4829
  `ase-task-implement`
4180
4830
  [`--help`|`-h`]
4181
4831
  [`--next`|`-n` *option*[,...]]
4182
- [`--worktree`|`-w`]
4832
+ [`--worktree`|`-w` *name*]
4833
+ [`--source`|`-s` *source*]
4834
+ [`--changeset`|`-c` *changeset*]
4835
+ [`--draft`|`-d`]
4836
+ [`--stateless`|`-S`]
4183
4837
  [*id*]
4184
4838
 
4185
4839
  ## DESCRIPTION
4186
4840
 
4187
4841
  The `ase-task-implement` skill performs the *final implementation* of
4188
- a task plan by modifying the corresponding *artifacts* with a complete
4189
- *change set*. The plan is loaded and any optional `IMPLEMENTATION DRAFT`
4190
- section produced by `ase-task-preflight` is taken over *1:1* as the
4191
- change set -- the draft is assumed to be user-reviewed, so no fresh
4192
- implementation is created and only parts which actually fail are
4193
- adjusted, guided by the plain plan content. Afterwards the plan's
4194
- `Properties:` frontmatter key gains the value `implemented` (plus
4195
- `verified`, if the verification phase actually ran and succeeded), and
4196
- its `Status:` key becomes `COMPLETED` if the change set was applied
4197
- completely and successfully.
4842
+ a task plan by creating a complete *change set* from the plan's
4843
+ *source* (the code basis) into the plan's *changeset* (the location of
4844
+ the change set). Delivering the change set from there into the plan's
4845
+ *target* is the separate concern of `ase-task-integrate`. Afterwards
4846
+ the checkboxes of the realized `DOM`/`IFC`/`ARC`/`IMP` bullet-points
4847
+ and of the performed and succeeded `REG`/`CON` bullet-points are ticked
4848
+ to `[x]` (or `[/]` if only partially realized or succeeded), refreshing
4849
+ the plan's `Modified:` key. Bullet-points in state `[-]` (cancelled) or
4850
+ `[>]` (deferred) are *skipped*: they are neither realized nor checked,
4851
+ do not count against completeness, and keep their checkbox untouched.
4852
+
4853
+ The *source* is selected by the plan's `Source:` frontmatter key
4854
+ (if absent, the configured default `project.task.default.source`),
4855
+ overridable via `--source`:
4856
+
4857
+ - `worktree` (default): the *origin* working copy (the one the skill
4858
+ was started in) with its checked-out branch.
4859
+ - `branch:`*name*: the existing branch *name*. For a `worktree`
4860
+ changeset without `--worktree`, the origin working copy is
4861
+ *switched* to it in place first, but only if it has *no*
4862
+ uncommitted changes, otherwise the skill stops and touches nothing.
4863
+
4864
+ A context worktree created by `--worktree` carries its *own* branch
4865
+ *name*, which starts at the source (so the source branch itself is never
4866
+ checked out there and stays available as the integration target), while
4867
+ a reused one keeps its own base, so earlier work in it is continued.
4868
+
4869
+ The *changeset* is selected by the plan's `Changeset:` frontmatter
4870
+ key (if absent, the configured default `project.task.default.changeset`),
4871
+ overridable via `--changeset`:
4872
+
4873
+ - `worktree` (default): the change set stays *uncommitted* in the
4874
+ context worktree.
4875
+ - `branch:`*name*: the change set is *committed* onto the branch
4876
+ *name* -- created from the source if missing -- inside the worktree
4877
+ in which this branch is checked out, or inside a newly created
4878
+ worktree `.ase/worktree/<name>`.
4879
+ - `attachment:`*name*: the change set is made and verified in a
4880
+ *temporary* worktree, detached at the source commit, and stored as
4881
+ the attachment block of type `text/x-diff; charset=utf-8;
4882
+ kind="<name>"` (with its base commit in the `Desc:` key) of the
4883
+ plan only, leaving all artifacts untouched. An already existing
4884
+ attachment of this kind is re-applied first, so re-runs build the
4885
+ change set *cumulatively*. A *stale* one -- older than the plan --
4886
+ stops the skill with an error, and an already *delivered* one --
4887
+ marked `merged` in its `Desc:` key by `ase-task-integrate
4888
+ --no-cleanup` -- is not re-applied, but replaced by a fresh change
4889
+ set. The `--draft` shorthand selects
4890
+ `attachment:draft`, the *implementation draft* of the plan, which
4891
+ can be reviewed via `ase-task-view --full` and delivered via
4892
+ `ase-task-integrate --draft`. An undelivered draft is *ignored* by
4893
+ any other changeset (with a warning), as only `attachment:draft`
4894
+ builds upon it.
4895
+
4896
+ For derived changesets (`branch:` and `attachment:`), *uncommitted*
4897
+ changes of a `worktree` source are *not* carried over, as they start
4898
+ at its `HEAD`.
4899
+
4900
+ The skill does *not* maintain the *change set snapshot* of the plan
4901
+ (the attachment block of type `text/x-diff; charset=utf-8;
4902
+ kind="changeset"`), which only the `implementer` agent of `ase agent`
4903
+ attaches after its implementation, but passes an existing one through
4904
+ unchanged.
4905
+
4906
+ Unless `--stateless` is given, the plan's `Status:` key follows the
4907
+ task lifecycle model: for `solo` it stays untouched (as the task is
4908
+ closed by `ase-task-integrate`), and for `team` and `enterprise` it
4909
+ becomes `IMPLEMENTING` before and `IMPLEMENTED` (if the change set was
4910
+ applied completely and successfully) or `STALLED` (otherwise) after
4911
+ the implementation.
4198
4912
 
4199
4913
  The *kind of change* stated by the plan's `Kind:` frontmatter key
4200
- (`CRAFTING`, `REFACTORING`, or `RESOLVING`) selects which
4914
+ (`SPECIFYING`, `CRAFTING`, `REFACTORING`, or `RESOLVING`) selects which
4201
4915
  *operation-specific tenet set* of the **ASE Tenets** is internalized
4202
4916
  before any artifact is touched, in addition to the always applying
4203
4917
  **GENERIC TENETS**. If a plan carries no such key, the kind is
4204
4918
  *inferred* from the plan content, defaulting to `CRAFTING`.
4205
4919
 
4206
- If the task plan deliberately *omits* the `## VERIFICATION` section
4207
- (as produced by `ase-code-craft`, `ase-code-refactor`,
4208
- `ase-code-resolve`, or `ase-task-edit` when invoked with `--dry`),
4920
+ If the task plan deliberately *omits* the `## VERIFICATION (WHEN)` section
4921
+ (as produced by `ase-task-edit` when invoked with `--unverified`),
4209
4922
  the entire verification phase is strictly skipped: no build, tests,
4210
4923
  linter, type-checker, or program execution is performed once the
4211
4924
  source files have been modified.
4212
4925
 
4213
- With `--worktree`|`-w`, the change set is *not* applied to the current
4214
- working copy: a *fresh Git WorkTree* `.ase/worktree/<id>` and its
4215
- equally named branch are created from `HEAD` *before* any artifact is
4216
- touched, and the entire implementation -- including all verification
4217
- runs -- then happens *inside* that worktree, which is left
4218
- *uncommitted*. The worktree is *not* named by an option value: it
4219
- always carries the unique *task id*, so worktree and branch stay tied
4220
- to the very task plan implemented in them. As the worktree branches off
4221
- `HEAD`, *uncommitted* changes of the current working copy are *not*
4222
- carried over into it.
4223
-
4224
- After implementation, the user is asked whether to preserve or
4225
- delete the task plan, unless `--next` pre-selects this choice.
4926
+ After implementation, the user is asked whether to stop, hand off to
4927
+ `ase-task-edit`, hand off to `ase-task-integrate`, or delete the task
4928
+ plan, unless `--next` pre-selects this choice.
4226
4929
 
4227
4930
  ## OPTIONS
4228
4931
 
@@ -4230,19 +4933,41 @@ delete the task plan, unless `--next` pre-selects this choice.
4230
4933
  Automatically answer the user dialog for the next step. *option*
4231
4934
  is a single token or a *comma-separated chronological list* of
4232
4935
  tokens; the *first* token is consumed by this skill, and any
4233
- remaining tokens are intentionally *discarded*, because the
4234
- downstream `ase-task-delete` skill accepts no `--next` option.
4235
- Recognized tokens at this skill: `none` (default, interactive
4236
- answer required), `DONE` (preserve task plan and stop), or
4237
- `DELETE` (hand off to `ase-task-delete`).
4238
-
4239
- - `--worktree`|`-w`:
4240
- Apply the change set inside a dedicated *Git WorkTree* instead of
4241
- the current working copy. The worktree directory `.ase/worktree/<id>`
4242
- and its equally named branch are derived from the *task id* and
4243
- created from `HEAD`. If either the directory or the branch already
4244
- exists, the skill stops and touches nothing. By default, the change
4245
- set is applied to the current working copy.
4936
+ remaining tokens are *forwarded* (via `--next`) to the downstream
4937
+ skill. Recognized tokens at this skill: `none` (default,
4938
+ interactive answer required), `DONE` (preserve task plan and stop),
4939
+ `EDIT` (hand off to `ase-task-edit`), `INTEGRATE` (hand off to
4940
+ `ase-task-integrate`, forwarding `--worktree`, `--changeset`, and
4941
+ `--stateless`), or `DELETE` (hand off to `ase-task-delete`).
4942
+
4943
+ - `--worktree`|`-w` *name*:
4944
+ Operate in the *context worktree* `.ase/worktree/<name>` instead
4945
+ of the current working copy: it is *reused* if it already exists,
4946
+ otherwise it is *created* with its own branch *name* (checked out if
4947
+ it exists, created at the source commit otherwise, so the source
4948
+ branch itself is never checked out there). The `worktree` value of the
4949
+ changeset refers to it, while the `worktree` value of the source
4950
+ (and of the target of a subsequent integration) keeps referring to
4951
+ the origin working copy, so an integration delivers the change set
4952
+ from the context worktree back into the origin branch. The option
4953
+ is permitted for a `worktree` changeset only, as a `branch:` or
4954
+ `attachment:` changeset would leave the context worktree unused.
4955
+
4956
+ - `--source`|`-s` *source*:
4957
+ Override the plan's `Source:` key (`worktree` or `branch:`*name*)
4958
+ for this run, without changing the plan.
4959
+
4960
+ - `--changeset`|`-c` *changeset*:
4961
+ Override the plan's `Changeset:` key (`worktree`, `branch:`*name*,
4962
+ or `attachment:`*name*) for this run, without changing the plan.
4963
+
4964
+ - `--draft`|`-d`:
4965
+ Shorthand for `--changeset attachment:draft`: create the
4966
+ *implementation draft* of the plan only, leaving all artifacts
4967
+ untouched (a dry-run). Mutually exclusive with `--changeset`.
4968
+
4969
+ - `--stateless`|`-S`:
4970
+ Leave the plan's `Status:` key untouched.
4246
4971
 
4247
4972
  ## ARGUMENTS
4248
4973
 
@@ -4254,12 +4979,14 @@ delete the task plan, unless `--next` pre-selects this choice.
4254
4979
 
4255
4980
  - You want a task plan turned into actual changes
4256
4981
  - You want the planned change set applied and verified
4257
- - You want a reviewed implementation draft applied 1:1
4982
+ - You want the change set committed onto a dedicated branch
4983
+ - You want the change set attached to the plan for review only
4984
+ - You want a dry-run of the implementation as a reviewable draft
4258
4985
  - You want the implementation isolated in a Git worktree
4259
4986
 
4260
4987
  ## EXAMPLES
4261
4988
 
4262
- Implement the current task plan:
4989
+ Implement the current task plan in the current working copy:
4263
4990
 
4264
4991
  ```text
4265
4992
  ❯ /ase-task-implement
@@ -4271,181 +4998,323 @@ Implement a specific task and delete the plan when done:
4271
4998
  ❯ /ase-task-implement --next DELETE hello
4272
4999
  ```
4273
5000
 
4274
- Implement the task `hello` inside the isolated Git WorkTree
4275
- `.ase/worktree/hello`:
5001
+ Draft the implementation of the task `hello` and apply the draft when
5002
+ done:
5003
+
5004
+ ```text
5005
+ ❯ /ase-task-implement --draft --next INTEGRATE hello
5006
+ ```
5007
+
5008
+ Implement the task `hello` inside the isolated Git worktree
5009
+ `.ase/worktree/hello` and integrate it afterwards:
4276
5010
 
4277
5011
  ```text
4278
- ❯ /ase-task-implement --worktree hello
5012
+ ❯ /ase-task-implement --worktree hello --next INTEGRATE,DONE hello
5013
+ ```
5014
+
5015
+ Implement the task `hello` by committing its change set onto the
5016
+ branch `feature-hello`:
5017
+
5018
+ ```text
5019
+ ❯ /ase-task-implement --changeset branch:feature-hello hello
4279
5020
  ```
4280
5021
 
4281
5022
  </purpose>
4282
- <purpose name="ase-task-list">
5023
+ <purpose name="ase-task-integrate">
4283
5024
 
4284
5025
  ## NAME
4285
5026
 
4286
- `ase-task-list` - List Task Plans
5027
+ `ase-task-integrate` - Integrate a Task Change Set
4287
5028
 
4288
5029
  ## SYNOPSIS
4289
5030
 
4290
- `ase-task-list`
5031
+ `ase-task-integrate`
4291
5032
  [`--help`|`-h`]
4292
- [`--verbose`|`-v`]
4293
- [`--include`|`-i`=*state*[`,`...]]
4294
- [`--exclude`|`-e`=*state*[`,`...]]
5033
+ [`--next`|`-n` *option*[,...]]
5034
+ [`--worktree`|`-w` *name*]
5035
+ [`--changeset`|`-c` *changeset*]
5036
+ [`--draft`|`-d`]
5037
+ [`--target`|`-t` *target*]
5038
+ [`--mode`|`-m` `merge`|`rebase`|`squash`]
5039
+ [`--no-cleanup`|`-K`]
5040
+ [`--stateless`|`-S`]
5041
+ [*id*]
4295
5042
 
4296
5043
  ## DESCRIPTION
4297
5044
 
4298
- The `ase-task-list` skill lists all available *task ids* in the
4299
- current project by calling the `ase_task_list` MCP tool. In the
4300
- default mode, only the task ids are rendered as a single-column
4301
- Markdown table. In verbose mode, the lifecycle status and the
4302
- last-modified timestamp of each task plan are rendered as additional
4303
- columns.
4304
-
4305
- The listing is restricted to an *effective state set*, derived from the
4306
- `Status:` frontmatter key of each task plan (which defaults to `DRAFTED`
4307
- for a plan carrying no such key): with `--include` only, exactly the
4308
- listed states are shown; with `--exclude` only, all states except the
4309
- listed ones; with both, the included ones minus the excluded ones. An
4310
- unknown state, or a combination which cancels out to an empty set,
4311
- aborts the skill with an error. By default,
4312
- `--exclude COMPLETED,CANCELLED` is in effect, so finished and
4313
- abandoned task plans stay out of the way. The eight states are:
4314
-
4315
- ```text
4316
- DRAFTED APPROVED STARTED COMPLETED
4317
- REJECTED DEFERRED BLOCKED CANCELLED
4318
- ```
5045
+ The `ase-task-integrate` skill delivers the *change set* of a task
5046
+ plan, as created by `ase-task-implement`, from the plan's *changeset*
5047
+ (the location of the change set) into the plan's *target* (the place
5048
+ of integration). The integration itself is performed by the skill
5049
+ `ase-repo-merge`, which commits still uncommitted changes of the
5050
+ change set, merges them into the target branch (through a regular
5051
+ merge, a rebase with fast-forward, or a squash merge, as selected via
5052
+ `--mode`), resolves merge conflicts semantically, and reports the
5053
+ verdict `MERGED`, `CONFLICT`, or `FAILED`.
5054
+
5055
+ The *changeset* is selected by the plan's `Changeset:` frontmatter
5056
+ key (if absent, the configured default `project.task.default.changeset`),
5057
+ overridable via `--changeset`:
5058
+
5059
+ - `worktree` (default): the uncommitted changes and the checked-out
5060
+ branch of the context worktree. If it equals the target branch
5061
+ (only possible without `--worktree`), the integration just commits
5062
+ the uncommitted changes in place.
5063
+ - `branch:`*name*: the existing branch *name*.
5064
+ - `attachment:`*name*: the attachment block of type `text/x-diff;
5065
+ charset=utf-8; kind="<name>"` of the plan, which is applied on a
5066
+ *temporary* branch at the commit it is based on, so drift of the
5067
+ target is resolved by the merge. A *stale* attachment -- one whose
5068
+ `Modified:` key is absent or older than the `Modified:` key of the
5069
+ plan frontmatter -- stops the skill with an error, and so does an
5070
+ already *delivered* one -- one whose `Desc:` key carries the
5071
+ `merged` marker of an earlier `--no-cleanup` integration.
5072
+ - `attachment:draft`: the *implementation draft* of the plan, as
5073
+ created by `ase-task-implement --draft`, selectable via the
5074
+ `--draft` shorthand.
5075
+
5076
+ The skill does *not* maintain the *change set snapshot* of the plan
5077
+ (the attachment block of type `text/x-diff; charset=utf-8;
5078
+ kind="changeset"`), which only the `integrator` agent of `ase agent`
5079
+ updates after a successful integration, but passes an existing one
5080
+ through unchanged.
5081
+
5082
+ The *target* is selected by the plan's `Target:` frontmatter key
5083
+ (if absent, the configured default `project.task.default.target`),
5084
+ overridable via `--target`:
5085
+
5086
+ - `worktree`: the checked-out branch of the *origin* working copy,
5087
+ i.e. the one the skill was started in (also with `--worktree`).
5088
+ - `branch:`*name*: the existing branch *name*, which has to be
5089
+ checked out in some worktree and to have no uncommitted changes.
5090
+ - `source` (default): whatever the plan's `Source:` key refers to.
5091
+
5092
+ The skill stops with an error -- touching nothing -- if the change set
5093
+ and the target are the same branch (except for the `worktree` changeset
5094
+ of the origin working copy, which just commits in place, see above), or
5095
+ if the change set carries neither commits beyond the target nor
5096
+ uncommitted changes. Likewise, a merge which leaves the content of the
5097
+ target unchanged, as the change set already landed earlier (e.g. on a
5098
+ repeated integration), counts as *no* integration: its empty merge
5099
+ commit is dropped again and the skill stops with an error. So it never
5100
+ reports a success without having delivered anything.
5101
+
5102
+ Unless `--stateless` is given, the plan's `Status:` key follows the
5103
+ task lifecycle model: for `solo` the plan has to be `OPEN` (otherwise
5104
+ the integration is refused) and it becomes `CLOSED` on a successful
5105
+ integration and stays `OPEN` otherwise, for `enterprise` it becomes
5106
+ `INTEGRATING` before and `INTEGRATED` (on success), `QUALIFIED` (on
5107
+ nothing delivered), or `DEFERRED` (otherwise) after the integration,
5108
+ and for `team`, which defines no integration states, it stays
5109
+ untouched.
5110
+
5111
+ After a successful integration, the user is asked whether to preserve
5112
+ or delete the task plan, unless `--next` pre-selects this choice.
4319
5113
 
4320
5114
  ## OPTIONS
4321
5115
 
4322
- - `--verbose`|`-v`:
4323
- Render an additional `Status` column with the lifecycle state and an
4324
- additional `Last Modified` column with the `YYYY-MM-DD HH:MM`
4325
- timestamp of each task plan.
5116
+ - `--next`|`-n` *option*[,...]:
5117
+ Automatically answer the user dialog for the next step. Recognized
5118
+ tokens at this skill: `none` (default, interactive answer
5119
+ required), `DONE` (preserve task plan and stop), or `DELETE` (hand
5120
+ off to `ase-task-delete`).
5121
+
5122
+ - `--worktree`|`-w` *name*:
5123
+ Operate on the *context worktree* `.ase/worktree/<name>` instead
5124
+ of the current working copy, as for `ase-task-implement`. The
5125
+ worktree has to exist already: an integration never creates it, so
5126
+ a mistyped *name* stops the skill with an error. The option is
5127
+ permitted for a `worktree` changeset only, as a `branch:` or
5128
+ `attachment:` changeset would leave the context worktree unused.
5129
+
5130
+ - `--changeset`|`-c` *changeset*:
5131
+ Override the plan's `Changeset:` key (`worktree`, `branch:`*name*,
5132
+ or `attachment:`*name*) for this run, without changing the plan.
5133
+
5134
+ - `--draft`|`-d`:
5135
+ Shorthand for `--changeset attachment:draft`: deliver the
5136
+ *implementation draft* of the plan. Mutually exclusive with
5137
+ `--changeset`.
5138
+
5139
+ - `--target`|`-t` *target*:
5140
+ Override the plan's `Target:` key (`worktree`, `branch:`*name*, or
5141
+ `source`) for this run, without changing the plan.
5142
+
5143
+ - `--mode`|`-m` `merge`|`rebase`|`squash`:
5144
+ The merge mode, passed through to `ase-repo-merge` (default:
5145
+ `merge`): `merge` creates a merge commit, `rebase` rebases the
5146
+ change set branch (rewriting its commits) onto the target branch
5147
+ and fast-forwards the target branch, and `squash` combines all
5148
+ changes of the change set into one new commit on the target branch.
5149
+
5150
+ - `--no-cleanup`|`-K`:
5151
+ After a successful integration, keep the delivered change set
5152
+ instead of removing it: the branch and its worktree, or the
5153
+ attachment block, which is then marked as delivered by appending
5154
+ `, merged <commit>` to its `Desc:` key, so it is never delivered
5155
+ again. Without this option, a delivered branch is removed only if
5156
+ Git considers it merged (always for `--mode squash`) and its
5157
+ worktree has no uncommitted changes. A temporary branch of an
5158
+ attachment is always removed.
5159
+
5160
+ - `--stateless`|`-S`:
5161
+ Leave the plan's `Status:` key untouched.
4326
5162
 
4327
- - `--include`|`-i`=*state*[`,`...]:
4328
- Restrict the listed task plans to the given comma-separated list of
4329
- lifecycle states (e.g. `STARTED,BLOCKED`). Without this option, all
4330
- eight states are listed. The `none` sentinel selects no state at all.
5163
+ ## ARGUMENTS
4331
5164
 
4332
- - `--exclude`|`-e`=*state*[`,`...]:
4333
- Remove the given comma-separated list of lifecycle states from the
4334
- listed task plans. Applied *after* `--include`, so
4335
- `-i DRAFTED,STARTED -e STARTED` lists `DRAFTED` only. Defaults to
4336
- `COMPLETED,CANCELLED`; pass `--exclude none` to suppress the
4337
- default and list task plans in every state.
5165
+ - *id*:
5166
+ The unique identifier of the task whose change set should be
5167
+ integrated. If omitted, the *current* task id is used.
4338
5168
 
4339
5169
  ## SCENARIOS
4340
5170
 
4341
- - You want an overview of all task plans
4342
- - You want task ids listed with status and timestamps
4343
- - You want the unfinished or in-progress tasks found
5171
+ - You want the implemented change set committed to the code base
5172
+ - You want a change set branch merged into its target branch
5173
+ - You want a change set attachment delivered into the code base
5174
+ - You want a reviewed implementation draft applied to the code base
5175
+ - You want the task closed once its change set has landed
4344
5176
 
4345
5177
  ## EXAMPLES
4346
5178
 
4347
- List all unfinished task ids:
5179
+ Integrate (commit) the change set of the current task plan:
4348
5180
 
4349
5181
  ```text
4350
- ❯ /ase-task-list
5182
+ ❯ /ase-task-integrate
4351
5183
  ```
4352
5184
 
4353
- List all task ids together with their status and last-modified timestamps:
5185
+ Apply the implementation draft of the task `hello` and remove the
5186
+ draft attachment afterwards:
4354
5187
 
4355
5188
  ```text
4356
- ❯ /ase-task-list --verbose
5189
+ ❯ /ase-task-integrate --draft hello
4357
5190
  ```
4358
5191
 
4359
- List the task ids of every task plan, including the finished ones:
5192
+ Merge the change set branch of the task `hello` into `main` and
5193
+ keep the branch afterwards:
4360
5194
 
4361
5195
  ```text
4362
- ❯ /ase-task-list --exclude none
5196
+ ❯ /ase-task-integrate --changeset branch:feature-hello --target branch:main --no-cleanup hello
4363
5197
  ```
4364
5198
 
4365
- List only the task ids of the task plans currently under work:
5199
+ Squash the change set branch of the task `hello` into one commit on
5200
+ its target:
4366
5201
 
4367
5202
  ```text
4368
- ❯ /ase-task-list --include STARTED,BLOCKED
5203
+ ❯ /ase-task-integrate --changeset branch:feature-hello --mode squash hello
4369
5204
  ```
4370
5205
 
4371
5206
  </purpose>
4372
- <purpose name="ase-task-preflight">
5207
+ <purpose name="ase-task-list">
4373
5208
 
4374
5209
  ## NAME
4375
5210
 
4376
- `ase-task-preflight` - Preflight a Task Plan
5211
+ `ase-task-list` - List Task Plans
4377
5212
 
4378
5213
  ## SYNOPSIS
4379
5214
 
4380
- `ase-task-preflight`
5215
+ `ase-task-list`
4381
5216
  [`--help`|`-h`]
4382
- [`--next`|`-n` *option*[,...]]
4383
- [*id*]
5217
+ [`--verbose`|`-v`]
5218
+ [`--include`|`-i`=*state*[`,`...]]
5219
+ [`--exclude`|`-e`=*state*[`,`...]]
4384
5220
 
4385
5221
  ## DESCRIPTION
4386
5222
 
4387
- The `ase-task-preflight` skill performs a *preflight* (dry-run,
4388
- test-drive) of the *implementation* of a task plan by creating a
4389
- draft for a corresponding, complete *artifact change set* in
4390
- *unified diff* format. The draft is appended to the task plan as
4391
- an `IMPLEMENTATION DRAFT` section (replacing any previous draft) and
4392
- the plan's `Properties:` frontmatter key gains the value `preflighted`.
4393
- No source files are modified. The draft is produced under the *same
4394
- tenets* and with the *same rigor* as a final implementation, because
4395
- `ase-task-implement` later takes it over *1:1* after user review --
4396
- only the actual artifact modification and the verification phase
4397
- are deferred.
5223
+ The `ase-task-list` skill lists all available *task ids* in the
5224
+ current project by calling the `ase_task_list` MCP tool. In the
5225
+ default mode, only the task ids are rendered as a single-column
5226
+ Markdown table. In verbose mode, the lifecycle status, the effort size
5227
+ (see `ase-task-estimate`), and the last-modified timestamp of each task
5228
+ plan are rendered as additional columns.
4398
5229
 
4399
- The *kind of change* stated by the plan's `Kind:` frontmatter key
4400
- (`CRAFTING`, `REFACTORING`, or `RESOLVING`) selects which
4401
- *operation-specific tenet set* of the **ASE Tenets** is internalized
4402
- before the draft is produced, in addition to the always applying
4403
- **GENERIC TENETS**. If a plan carries no such key, the kind is
4404
- *inferred* from the plan content, defaulting to `CRAFTING`.
5230
+ The listing is restricted to an *effective state set*, derived from the
5231
+ `Status:` frontmatter key of each task plan (which defaults to the
5232
+ initial state of the task lifecycle model for a plan carrying no such
5233
+ key): with `--include` only, exactly the listed states are shown; with
5234
+ `--exclude` only, all states except the listed ones; with both, the
5235
+ included ones minus the excluded ones. An unknown state, or a
5236
+ combination which cancels out to an empty set, aborts the skill with an
5237
+ error. The `finished` sentinel stands for the finished states of the
5238
+ task lifecycle model. By default, `--exclude finished` is in effect, so
5239
+ finished and abandoned task plans stay out of the way. A task plan whose
5240
+ `Status:` is not a state of the task lifecycle model at all is never
5241
+ filtered out: it is kept in the listing and reported with a warning.
4405
5242
 
4406
- After the preflight, the user is asked whether to stop, hand
4407
- off to `ase-task-edit`, or hand off to `ase-task-implement`,
4408
- unless `--next` pre-selects this choice.
5243
+ The states depend on the task lifecycle model configured for the
5244
+ project via `project.task.lifecycle`. The `solo` model (default) has
5245
+ the 4 states (initial: `OPEN`, finished: `CLOSED` and `CANCELLED`):
5246
+
5247
+ ```text
5248
+ OPEN SHELVED CLOSED CANCELLED
5249
+ ```
5250
+
5251
+ The `team` model has the 6 states (initial: `PLANNING`, finished:
5252
+ `IMPLEMENTED` and `CANCELLED`):
5253
+
5254
+ ```text
5255
+ PLANNING SHELVED IMPLEMENTING STALLED IMPLEMENTED CANCELLED
5256
+ ```
5257
+
5258
+ The `enterprise` model has the 14 states (initial: `DRAFTED`, finished:
5259
+ `INTEGRATED` and `CANCELLED`):
5260
+
5261
+ ```text
5262
+ DRAFTED SHELVED PLANNING PLANNED STALLED
5263
+ IMPLEMENTING IMPLEMENTED DECLINED QUALIFYING QUALIFIED
5264
+ DEFERRED INTEGRATING INTEGRATED CANCELLED
5265
+ ```
4409
5266
 
4410
5267
  ## OPTIONS
4411
5268
 
4412
- - `--next`|`-n` *option*[,...]:
4413
- Automatically answer the user dialog for the next step. *option*
4414
- is a single token or a *comma-separated chronological list* of
4415
- tokens; the *first* token is consumed by this skill, and any
4416
- remaining tokens are *forwarded* (via `--next`) to the downstream
4417
- skill so an entire pipeline can be pre-scripted in one shot.
4418
- Recognized tokens at this skill: `none` (default, interactive
4419
- answer required), `DONE` (stop), `EDIT` (hand off to
4420
- `ase-task-edit`), or `IMPLEMENT` (hand off to
4421
- `ase-task-implement`). Example: `--next IMPLEMENT,DONE` runs the
4422
- preflight, hands off to implementation, then exits without asking.
5269
+ - `--verbose`|`-v`:
5270
+ Render an additional `Status` column with the lifecycle state, an
5271
+ additional `Effort` column with the T-shirt size (`-` if not
5272
+ estimated), and an additional `Last Modified` column with the
5273
+ `YYYY-MM-DD HH:MM` timestamp of each task plan.
4423
5274
 
4424
- ## ARGUMENTS
5275
+ - `--include`|`-i`=*state*[`,`...]:
5276
+ Restrict the listed task plans to the given comma-separated list of
5277
+ lifecycle states (e.g. `IMPLEMENTING,STALLED`). Without this option,
5278
+ all states are listed. The `none` sentinel selects no state at all,
5279
+ the `finished` sentinel selects the finished states.
4425
5280
 
4426
- - *id*:
4427
- The unique identifier of the task whose plan should be
4428
- preflighted. If omitted, the *current* task id is used.
5281
+ - `--exclude`|`-e`=*state*[`,`...]:
5282
+ Remove the given comma-separated list of lifecycle states from the
5283
+ listed task plans. Applied *after* `--include`, so
5284
+ `-i PLANNING,IMPLEMENTING -e IMPLEMENTING` lists `PLANNING` only.
5285
+ Defaults to `finished`; pass `--exclude none` to suppress the
5286
+ default and list task plans in every state.
4429
5287
 
4430
5288
  ## SCENARIOS
4431
5289
 
4432
- - You want a dry-run of a plan's implementation
4433
- - You want the change set previewed as a unified diff before applying
4434
- - You want an implementation draft to review before committing to it
4435
- - You want a plan test-driven without touching any source files
5290
+ - You want an overview of all task plans
5291
+ - You want task ids listed with status and timestamps
5292
+ - You want the unfinished or in-progress tasks found
4436
5293
 
4437
5294
  ## EXAMPLES
4438
5295
 
4439
- Preflight the current task plan:
5296
+ List all unfinished task ids:
5297
+
5298
+ ```text
5299
+ ❯ /ase-task-list
5300
+ ```
5301
+
5302
+ List all task ids together with their status and last-modified timestamps:
5303
+
5304
+ ```text
5305
+ ❯ /ase-task-list --verbose
5306
+ ```
5307
+
5308
+ List the task ids of every task plan, including the finished ones:
4440
5309
 
4441
5310
  ```text
4442
- ❯ /ase-task-preflight
5311
+ ❯ /ase-task-list --exclude none
4443
5312
  ```
4444
5313
 
4445
- Preflight a specific task and hand off to implementation when done:
5314
+ List only the task ids of the task plans currently under work:
4446
5315
 
4447
5316
  ```text
4448
- ❯ /ase-task-preflight --next IMPLEMENT hello
5317
+ ❯ /ase-task-list --include IMPLEMENTING,STALLED
4449
5318
  ```
4450
5319
 
4451
5320
  </purpose>
@@ -4465,13 +5334,32 @@ Preflight a specific task and hand off to implementation when done:
4465
5334
  ## DESCRIPTION
4466
5335
 
4467
5336
  The `ase-task-reboot` skill re-creates an existing task plan *from
4468
- scratch* by extracting the original `**WHAT**` and `**WHY**` sections
4469
- (if present) from the current plan, using them as the new instruction,
4470
- preserving the original creation timestamp, and writing fresh plan
4471
- content via `ase_task_save`.
5337
+ scratch* by extracting the `DOM` and `IFC` bullet points of the
5338
+ `SPECIFICATION (WHAT)` section (if present) from the current plan,
5339
+ using them as the new instruction, re-deriving the `DESIGN (HOW)` and
5340
+ `VERIFICATION (WHEN)` sections grounded in the relevant specification
5341
+ (`SPEC`), source code (`CODE`), and infrastructure (`INFR`) files of the
5342
+ project (naming the actual files and symbols to change, the actual build,
5343
+ lint, and test procedures, and a `CHANGELOG.md` entry if such a file
5344
+ exists), preserving the original creation
5345
+ timestamp, the remaining frontmatter keys, and all attachments, and
5346
+ writing fresh plan content via `ase_task_save`. As the rebooted plan
5347
+ starts its lifecycle anew, its `Status:` key is reset to the default
5348
+ state of the task lifecycle model, all `grilled:` tags are dropped
5349
+ from its `Tags:` key, and its `Source:`, `Changeset:`, and `Target:`
5350
+ keys are dropped, so they read as their configured defaults
5351
+ `project.task.default.{source,changeset,target}`.
5352
+
5353
+ A plan which does *not* follow the task format (or carries no `DOM` or
5354
+ `IFC` bullet point) is rebooted from its entire body instead: all of
5355
+ its existing content is *filed* into the `SPECIFICATION (WHAT)`,
5356
+ `DESIGN (HOW)`, and `VERIFICATION (WHEN)` sections by classifying
5357
+ each statement as a `DOM`, `IFC`, `ARC`, `IMP`, `REG`, or `CON` bullet
5358
+ point, with no statement dropped and missing bullet points derived from
5359
+ the existing content.
4472
5360
 
4473
5361
  After the reboot, the user is asked whether to stop or hand off to
4474
- `ase-task-edit`, `ase-task-implement`, or `ase-task-preflight`,
5362
+ `ase-task-edit` or `ase-task-implement` (optionally with `--draft`),
4475
5363
  unless `--next` pre-selects this choice.
4476
5364
 
4477
5365
  ## OPTIONS
@@ -4485,7 +5373,7 @@ unless `--next` pre-selects this choice.
4485
5373
  Recognized tokens at this skill: `none` (default, interactive
4486
5374
  answer required), `DONE` (stop), `EDIT` (hand off to
4487
5375
  `ase-task-edit`), `IMPLEMENT` (hand off to `ase-task-implement`),
4488
- or `PREFLIGHT` (hand off to `ase-task-preflight`). Example:
5376
+ or `DRAFT` (hand off to `ase-task-implement --draft`). Example:
4489
5377
  `--next EDIT,DONE` reboots, hands off to editing, and the editing
4490
5378
  loop will exit immediately.
4491
5379
 
@@ -4498,8 +5386,9 @@ unless `--next` pre-selects this choice.
4498
5386
  ## SCENARIOS
4499
5387
 
4500
5388
  - You want a task plan re-created from scratch
4501
- - You want a fresh plan from the original WHAT and WHY
5389
+ - You want a fresh plan from the original specification
4502
5390
  - You want planning restarted after a plan degraded
5391
+ - You want a free-form or legacy plan filed into the task format
4503
5392
 
4504
5393
  ## EXAMPLES
4505
5394
 
@@ -4563,6 +5452,184 @@ Rename a specific task:
4563
5452
  ❯ /ase-task-rename old-id new-id
4564
5453
  ```
4565
5454
 
5455
+ </purpose>
5456
+ <purpose name="ase-task-research">
5457
+
5458
+ ## NAME
5459
+
5460
+ `ase-task-research` - Research a Topic for a Task Plan
5461
+
5462
+ ## SYNOPSIS
5463
+
5464
+ `ase-task-research`
5465
+ [`--help`|`-h`]
5466
+ [`--services`|`-s` `all`|`perplexity`|`brave`|`exa`|`websearch`[,...]]
5467
+ [`--refine`|`-r`]
5468
+ [`--dry-run`|`-d`]
5469
+ [*id* | *id*`:` [*topic*] | *topic*]
5470
+
5471
+ ## DESCRIPTION
5472
+
5473
+ The `ase-task-research` skill *researches* a topic in depth for a task
5474
+ plan. It combines a *Web research* -- several focused queries, sent in
5475
+ parallel to the Internet/Web search services of `ase-meta-search` --
5476
+ with a *grounding* in the *source artifacts* of the project (its
5477
+ specification, source code, documentation, and infrastructure).
5478
+
5479
+ The result is a *research report* with the parts *Findings* (the Web
5480
+ facts, each with its source URL), *Project Grounding* (the relevant
5481
+ project facts, each with its project file), *Assessment* (how the
5482
+ findings apply to the project, including its gaps and conflicts), and
5483
+ *Recommendations* (the concrete consequences for the plan), bounded to
5484
+ about 300 lines and at most 10 findings.
5485
+
5486
+ The report is *appended* to the single `research` attachment of the
5487
+ task (of type `text/markdown; charset=utf-8; kind="research"`), so the
5488
+ reports of earlier researches are kept. With `--refine`, the
5489
+ recommendations are additionally applied to the plan itself, preserving
5490
+ its structure. Without a *topic*, the task plan itself (its title and
5491
+ domain items) is researched.
5492
+
5493
+ The search queries carry only a self-contained summary of the topic and
5494
+ never any project internals like file paths or identifiers, as they are
5495
+ sent to foreign search services. The shown report follows the
5496
+ configured `project.boxing`, while the attachment always carries the
5497
+ full report.
5498
+
5499
+ The `ase agent researcher` command researches the tasks automatically
5500
+ and always refines the plan by the recommendations: in its mode
5501
+ `phase`, it researches and grounds the plans of the `DRAFTED` tasks
5502
+ explicitly assigned to it, while in its mode `request`, it researches
5503
+ the topics of the requests in any unfinished status, via `ase task
5504
+ request <id> research [<topic>]` or key `R` of the task boards.
5505
+
5506
+ ## OPTIONS
5507
+
5508
+ - `--services`|`-s` `all`|`perplexity`|`brave`|`exa`|`websearch`[,...]:
5509
+ The comma-separated search services to query (default: `all`).
5510
+
5511
+ - `--refine`|`-r`:
5512
+ Additionally refine the task plan by the recommendations of the
5513
+ research report.
5514
+
5515
+ - `--dry-run`|`-d`:
5516
+ Research and show the report only, but do not change the task.
5517
+
5518
+ ## ARGUMENTS
5519
+
5520
+ - *id*:
5521
+ The unique identifier of the task to research for. If omitted, the
5522
+ *current* task is used. A single word without a trailing `:` is
5523
+ always taken as a task identifier.
5524
+
5525
+ - *topic*:
5526
+ The topic to research. If omitted, the task plan itself is
5527
+ researched.
5528
+
5529
+ ## SCENARIOS
5530
+
5531
+ - You want to know the established practices and pitfalls of a topic before planning a task
5532
+ - You want to check a task plan against the state of the art
5533
+ - You want to keep the research findings of a task together with its plan
5534
+
5535
+ ## EXAMPLES
5536
+
5537
+ Research the current task plan itself:
5538
+
5539
+ ```text
5540
+ ❯ /ase-task-research
5541
+ ```
5542
+
5543
+ Research a topic for a specific task and refine its plan:
5544
+
5545
+ ```text
5546
+ ❯ /ase-task-research --refine export-json: streaming JSON serialization of large data sets
5547
+ ```
5548
+
5549
+ Research a topic with Perplexity only, without changing the task:
5550
+
5551
+ ```text
5552
+ ❯ /ase-task-research --services perplexity --dry-run rate limiting of REST APIs
5553
+ ```
5554
+
5555
+ </purpose>
5556
+ <purpose name="ase-task-status">
5557
+
5558
+ ## NAME
5559
+
5560
+ `ase-task-status` - Configure Task Status
5561
+
5562
+ ## SYNOPSIS
5563
+
5564
+ `ase-task-status`
5565
+ [`--help`|`-h`]
5566
+ [*id*`:`] [*status*]
5567
+
5568
+ ## DESCRIPTION
5569
+
5570
+ The `ase-task-status` skill gets or sets the *lifecycle status* of a
5571
+ *task plan*, i.e. its `Status:` frontmatter key, via the
5572
+ `ase_task_status` MCP tool. Without a *status* argument, it reports the
5573
+ current status of the plan (defaulting to the initial state of the task
5574
+ lifecycle model if the plan carries no `Status:` key). With a *status*
5575
+ argument, it sets the status of the plan, leaving its `Modified:` key
5576
+ alone, as that key tracks changes of the plan body only.
5577
+
5578
+ The *status* is matched case-insensitively against the states of the
5579
+ task lifecycle model configured for the project via
5580
+ `project.task.lifecycle` (`solo`, `team`, or `enterprise`) and rejected
5581
+ if it is no such state. A status not reachable from the current one via
5582
+ one or more transitions of the state machine of the model is *rejected*,
5583
+ too.
5584
+
5585
+ If *id*`:` is omitted, the *current* task id (inherited from the session
5586
+ context) is used. A single bare token which is no state of the model is
5587
+ also taken as the task id. The current task id of the session is never
5588
+ switched.
5589
+
5590
+ ## ARGUMENTS
5591
+
5592
+ - *id*`:`:
5593
+ The unique identifier of the task plan, with a trailing colon.
5594
+ If omitted, the current task id is used.
5595
+
5596
+ - *status*:
5597
+ The lifecycle status to set, one of the states of the configured
5598
+ task lifecycle model (case-insensitive). If omitted, the current
5599
+ status is reported.
5600
+
5601
+ ## SCENARIOS
5602
+
5603
+ - You want to know the lifecycle status of the current or a given task plan
5604
+ - You want a task plan closed, shelved, cancelled, or re-opened
5605
+ - You want a task plan moved into a certain lifecycle state by hand
5606
+
5607
+ ## EXAMPLES
5608
+
5609
+ Show the status of the current task plan:
5610
+
5611
+ ```text
5612
+ ❯ /ase-task-status
5613
+ ```
5614
+
5615
+ Show the status of a specific task plan:
5616
+
5617
+ ```text
5618
+ ❯ /ase-task-status hello:
5619
+ ```
5620
+
5621
+ Close the current task plan (`solo` lifecycle model):
5622
+
5623
+ ```text
5624
+ ❯ /ase-task-status closed
5625
+ ```
5626
+
5627
+ Shelve a specific task plan:
5628
+
5629
+ ```text
5630
+ ❯ /ase-task-status hello: SHELVED
5631
+ ```
5632
+
4566
5633
  </purpose>
4567
5634
  <purpose name="ase-task-view">
4568
5635
 
@@ -4584,18 +5651,28 @@ The plan is loaded via the `ase_task_load` MCP tool and shown framed
4584
5651
  between a `( TASK )` header and footer rule. If *id* is omitted, the
4585
5652
  *current* task id (inherited from the session context) is used.
4586
5653
 
4587
- By default, when the plan is longer than 90 lines and contains an
4588
- `IMPLEMENTATION DRAFT` section (produced by `ase-task-preflight`), the
4589
- content of that section is collapsed to `[...]` to keep the view
4590
- compact. The `--full`|`-f` option suppresses this collapsing and renders
4591
- the plan in full, without any truncation or summarization.
5654
+ By default, the payload of every attachment in the backmatter (like an
5655
+ implementation draft of `ase-task-implement --draft` or the processing
5656
+ log of an `ase agent`) is elided to an `[elided: <n> lines]` marker to
5657
+ keep the view compact. The `--full`|`-f` option loads the payloads, too,
5658
+ and renders the plan in full, without any truncation or summarization.
5659
+
5660
+ An implementation draft attachment whose `Modified:` key is absent or
5661
+ older than the `Modified:` key of the plan frontmatter is *stale*, as
5662
+ the plan changed after the draft was created. Such a draft is reported
5663
+ with a warning after the rendering, together with a hint that
5664
+ `ase-task-implement --draft` has to be run again, as
5665
+ `ase-task-integrate --draft` refuses a stale draft.
5666
+
5667
+ The frontmatter keys `Source:`, `Changeset:`, and `Target:` are
5668
+ rendered as well, stating where the change set of the plan is
5669
+ created from, stored in, and delivered to.
4592
5670
 
4593
5671
  ## OPTIONS
4594
5672
 
4595
5673
  - `--full`|`-f`:
4596
- Render the plan in full, without collapsing the
4597
- `IMPLEMENTATION DRAFT` section. By default, that section is
4598
- replaced with `[...]` for plans longer than 90 lines.
5674
+ Render the plan in full, including the payloads of its attachments.
5675
+ By default, each payload is elided to an `[elided: <n> lines]` marker.
4599
5676
 
4600
5677
  ## ARGUMENTS
4601
5678
 
@@ -4623,7 +5700,7 @@ View a specific task plan:
4623
5700
  ❯ /ase-task-view hello
4624
5701
  ```
4625
5702
 
4626
- View a plan in full, including its `IMPLEMENTATION DRAFT` section:
5703
+ View a plan in full, including its implementation draft attachment:
4627
5704
 
4628
5705
  ```text
4629
5706
  ❯ /ase-task-view --full hello