self-evolving-workflow 0.0.0-stage → 0.1.4

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 (375) hide show
  1. package/LICENSE +27 -0
  2. package/README.md +195 -2
  3. package/dist/agent-memory-prompts.d.ts +13 -0
  4. package/dist/agent-memory-prompts.js +55 -0
  5. package/dist/cli.d.ts +2 -0
  6. package/dist/cli.js +6 -0
  7. package/dist/closeout.d.ts +105 -0
  8. package/dist/closeout.js +473 -0
  9. package/dist/code.d.ts +39 -0
  10. package/dist/code.js +124 -0
  11. package/dist/codex-memory.d.ts +24 -0
  12. package/dist/codex-memory.js +217 -0
  13. package/dist/common.d.ts +16 -0
  14. package/dist/common.js +52 -0
  15. package/dist/context-envelope.d.ts +59 -0
  16. package/dist/context-envelope.js +23 -0
  17. package/dist/host-adapters.d.ts +34 -0
  18. package/dist/host-adapters.js +151 -0
  19. package/dist/http.d.ts +3 -0
  20. package/dist/http.js +90 -0
  21. package/dist/index.d.ts +16 -0
  22. package/dist/index.js +13 -0
  23. package/dist/knowledge-cli.d.ts +198 -0
  24. package/dist/knowledge-cli.js +761 -0
  25. package/dist/knowledge-reads.d.ts +72 -0
  26. package/dist/knowledge-reads.js +201 -0
  27. package/dist/memory-config.d.ts +44 -0
  28. package/dist/memory-config.js +204 -0
  29. package/dist/memory-evidence.d.ts +13 -0
  30. package/dist/memory-evidence.js +40 -0
  31. package/dist/memory-history.d.ts +46 -0
  32. package/dist/memory-history.js +432 -0
  33. package/dist/memory.d.ts +96 -0
  34. package/dist/memory.js +362 -0
  35. package/dist/retrospective.d.ts +57 -0
  36. package/dist/retrospective.js +240 -0
  37. package/dist/search.d.ts +36 -0
  38. package/dist/search.js +112 -0
  39. package/dist/skill-addition.d.ts +25 -0
  40. package/dist/skill-addition.js +89 -0
  41. package/dist/skill-design.d.ts +96 -0
  42. package/dist/skill-design.js +226 -0
  43. package/dist/skill-replay.d.ts +55 -0
  44. package/dist/skill-replay.js +448 -0
  45. package/dist/skill-route.d.ts +30 -0
  46. package/dist/skill-route.js +75 -0
  47. package/dist/transcript-evidence.d.ts +3 -0
  48. package/dist/transcript-evidence.js +58 -0
  49. package/dist/upstream/chunker.d.ts +24 -0
  50. package/dist/upstream/chunker.js +96 -0
  51. package/dist/upstream/file-protocol.d.ts +45 -0
  52. package/dist/upstream/file-protocol.js +117 -0
  53. package/dist/upstream/frontmatter.d.ts +47 -0
  54. package/dist/upstream/frontmatter.js +86 -0
  55. package/dist/upstream/graph-search.d.ts +33 -0
  56. package/dist/upstream/graph-search.js +67 -0
  57. package/dist/upstream/l1-extraction.d.ts +26 -0
  58. package/dist/upstream/l1-extraction.js +405 -0
  59. package/dist/upstream/llm.d.ts +8 -0
  60. package/dist/upstream/llm.js +1 -0
  61. package/dist/upstream/merge.d.ts +50 -0
  62. package/dist/upstream/merge.js +153 -0
  63. package/dist/upstream/prompts.d.ts +53 -0
  64. package/dist/upstream/prompts.js +181 -0
  65. package/dist/upstream/search-utils.d.ts +34 -0
  66. package/dist/upstream/search-utils.js +55 -0
  67. package/dist/upstream/slug.d.ts +26 -0
  68. package/dist/upstream/slug.js +103 -0
  69. package/dist/upstream/template.d.ts +29 -0
  70. package/dist/upstream/template.js +80 -0
  71. package/dist/upstream/tokenize.d.ts +4 -0
  72. package/dist/upstream/tokenize.js +29 -0
  73. package/dist/wiki-change.d.ts +76 -0
  74. package/dist/wiki-change.js +299 -0
  75. package/dist/wiki-entry.d.ts +26 -0
  76. package/dist/wiki-entry.js +93 -0
  77. package/dist/wiki-ingest.d.ts +12 -0
  78. package/dist/wiki-ingest.js +126 -0
  79. package/dist/wiki-migration.d.ts +16 -0
  80. package/dist/wiki-migration.js +268 -0
  81. package/dist/wiki-tokens.d.ts +1 -0
  82. package/dist/wiki-tokens.js +46 -0
  83. package/dist/wiki.d.ts +103 -0
  84. package/dist/wiki.js +330 -0
  85. package/dist/workflow-cli.d.ts +2 -0
  86. package/dist/workflow-cli.js +319 -0
  87. package/dist/workflow-install.d.ts +37 -0
  88. package/dist/workflow-install.js +148 -0
  89. package/dist/workflow-knowledge.d.ts +18 -0
  90. package/dist/workflow-knowledge.js +32 -0
  91. package/dist/workflow-mcp.d.ts +2 -0
  92. package/dist/workflow-mcp.js +137 -0
  93. package/dist/workflow-names.d.ts +4 -0
  94. package/dist/workflow-names.js +31 -0
  95. package/dist/workflow-runtime.d.ts +735 -0
  96. package/dist/workflow-runtime.js +747 -0
  97. package/dist/workflow-skills.d.ts +48 -0
  98. package/dist/workflow-skills.js +141 -0
  99. package/docs/images/impeccable-skill.png +0 -0
  100. package/docs/images/workflow-overview.png +0 -0
  101. package/docs/images/workflow-skills.png +0 -0
  102. package/package.json +77 -4
  103. package/skills/ew-impeccable/LICENSE +191 -0
  104. package/skills/ew-impeccable/NOTICE.md +19 -0
  105. package/skills/ew-impeccable/SKILL.md +91 -0
  106. package/skills/ew-impeccable/UPSTREAM.md +23 -0
  107. package/skills/ew-impeccable/reference/adapt.md +314 -0
  108. package/skills/ew-impeccable/reference/adapt.native.md +60 -0
  109. package/skills/ew-impeccable/reference/android.md +46 -0
  110. package/skills/ew-impeccable/reference/animate.md +91 -0
  111. package/skills/ew-impeccable/reference/audit.md +138 -0
  112. package/skills/ew-impeccable/reference/audit.native.md +141 -0
  113. package/skills/ew-impeccable/reference/bolder.md +35 -0
  114. package/skills/ew-impeccable/reference/clarify.md +96 -0
  115. package/skills/ew-impeccable/reference/colorize.md +88 -0
  116. package/skills/ew-impeccable/reference/craft-floor.md +44 -0
  117. package/skills/ew-impeccable/reference/craft.md +5 -0
  118. package/skills/ew-impeccable/reference/critique.md +808 -0
  119. package/skills/ew-impeccable/reference/degraded/asset-producer.md +36 -0
  120. package/skills/ew-impeccable/reference/degraded/documenter.md +23 -0
  121. package/skills/ew-impeccable/reference/degraded/finish-reviewer.md +72 -0
  122. package/skills/ew-impeccable/reference/degraded/manual-edit-applier.md +91 -0
  123. package/skills/ew-impeccable/reference/delight.md +72 -0
  124. package/skills/ew-impeccable/reference/distill.md +113 -0
  125. package/skills/ew-impeccable/reference/doctor.md +56 -0
  126. package/skills/ew-impeccable/reference/document.md +418 -0
  127. package/skills/ew-impeccable/reference/extract.md +68 -0
  128. package/skills/ew-impeccable/reference/harden.md +338 -0
  129. package/skills/ew-impeccable/reference/hooks.md +113 -0
  130. package/skills/ew-impeccable/reference/init.md +133 -0
  131. package/skills/ew-impeccable/reference/ios.md +51 -0
  132. package/skills/ew-impeccable/reference/layout.md +86 -0
  133. package/skills/ew-impeccable/reference/live-setup.md +102 -0
  134. package/skills/ew-impeccable/reference/live.md +326 -0
  135. package/skills/ew-impeccable/reference/new-work.md +209 -0
  136. package/skills/ew-impeccable/reference/onboard.md +236 -0
  137. package/skills/ew-impeccable/reference/operate.md +61 -0
  138. package/skills/ew-impeccable/reference/optimize.md +260 -0
  139. package/skills/ew-impeccable/reference/overdrive.md +127 -0
  140. package/skills/ew-impeccable/reference/polish.md +105 -0
  141. package/skills/ew-impeccable/reference/quieter.md +101 -0
  142. package/skills/ew-impeccable/reference/routing.md +20 -0
  143. package/skills/ew-impeccable/reference/shape.md +59 -0
  144. package/skills/ew-impeccable/reference/typeset.md +82 -0
  145. package/skills/ew-impeccable/reference/visualize.md +46 -0
  146. package/skills/ew-impeccable/scripts/build-phase.mjs +1022 -0
  147. package/skills/ew-impeccable/scripts/command-metadata.json +94 -0
  148. package/skills/ew-impeccable/scripts/comp-diff.mjs +391 -0
  149. package/skills/ew-impeccable/scripts/comp-spec.mjs +513 -0
  150. package/skills/ew-impeccable/scripts/concept-seed.mjs +814 -0
  151. package/skills/ew-impeccable/scripts/context-signals.mjs +325 -0
  152. package/skills/ew-impeccable/scripts/context.mjs +1521 -0
  153. package/skills/ew-impeccable/scripts/critique-storage.mjs +473 -0
  154. package/skills/ew-impeccable/scripts/data/font-index-failures.json +121 -0
  155. package/skills/ew-impeccable/scripts/data/font-index.json +1 -0
  156. package/skills/ew-impeccable/scripts/detect-csp.mjs +246 -0
  157. package/skills/ew-impeccable/scripts/detect.mjs +30 -0
  158. package/skills/ew-impeccable/scripts/detector/browser/injected/index.mjs +2580 -0
  159. package/skills/ew-impeccable/scripts/detector/cli/main.mjs +498 -0
  160. package/skills/ew-impeccable/scripts/detector/design-system.mjs +1311 -0
  161. package/skills/ew-impeccable/scripts/detector/detect-antipatterns-browser.js +9486 -0
  162. package/skills/ew-impeccable/scripts/detector/detect-antipatterns.mjs +51 -0
  163. package/skills/ew-impeccable/scripts/detector/engines/browser/detect-url.mjs +434 -0
  164. package/skills/ew-impeccable/scripts/detector/engines/regex/detect-text.mjs +1439 -0
  165. package/skills/ew-impeccable/scripts/detector/engines/static-html/css-cascade.mjs +1242 -0
  166. package/skills/ew-impeccable/scripts/detector/engines/static-html/detect-html.mjs +263 -0
  167. package/skills/ew-impeccable/scripts/detector/engines/visual/screenshot-contrast.mjs +189 -0
  168. package/skills/ew-impeccable/scripts/detector/findings.mjs +23 -0
  169. package/skills/ew-impeccable/scripts/detector/node/file-system.mjs +225 -0
  170. package/skills/ew-impeccable/scripts/detector/profile/profiler.mjs +166 -0
  171. package/skills/ew-impeccable/scripts/detector/registry/antipatterns.mjs +636 -0
  172. package/skills/ew-impeccable/scripts/detector/rules/checks.mjs +5750 -0
  173. package/skills/ew-impeccable/scripts/detector/shared/color.mjs +596 -0
  174. package/skills/ew-impeccable/scripts/detector/shared/constants.mjs +127 -0
  175. package/skills/ew-impeccable/scripts/detector/shared/fonts.mjs +30 -0
  176. package/skills/ew-impeccable/scripts/detector/shared/inline-ignores.mjs +148 -0
  177. package/skills/ew-impeccable/scripts/detector/shared/page.mjs +7 -0
  178. package/skills/ew-impeccable/scripts/detector/vendor/MDN-DATA-LICENSE +116 -0
  179. package/skills/ew-impeccable/scripts/detector/vendor/THIRD_PARTY_LICENSES.md +227 -0
  180. package/skills/ew-impeccable/scripts/detector/vendor/static-html-parser.build-entry.txt +11 -0
  181. package/skills/ew-impeccable/scripts/detector/vendor/static-html-parser.bundle.mjs +9121 -0
  182. package/skills/ew-impeccable/scripts/doctor.mjs +330 -0
  183. package/skills/ew-impeccable/scripts/embed-prompt.mjs +166 -0
  184. package/skills/ew-impeccable/scripts/font-match.mjs +457 -0
  185. package/skills/ew-impeccable/scripts/generate-image.mjs +447 -0
  186. package/skills/ew-impeccable/scripts/hook-admin.mjs +829 -0
  187. package/skills/ew-impeccable/scripts/hook-before-edit.mjs +538 -0
  188. package/skills/ew-impeccable/scripts/hook-lib.mjs +2493 -0
  189. package/skills/ew-impeccable/scripts/hook.mjs +79 -0
  190. package/skills/ew-impeccable/scripts/lib/artifact-schema.mjs +93 -0
  191. package/skills/ew-impeccable/scripts/lib/composition-catalog.mjs +200 -0
  192. package/skills/ew-impeccable/scripts/lib/concept-catalog.mjs +395 -0
  193. package/skills/ew-impeccable/scripts/lib/design-parser.mjs +880 -0
  194. package/skills/ew-impeccable/scripts/lib/font-fingerprint.mjs +564 -0
  195. package/skills/ew-impeccable/scripts/lib/font-index.mjs +130 -0
  196. package/skills/ew-impeccable/scripts/lib/hero-checks.mjs +246 -0
  197. package/skills/ew-impeccable/scripts/lib/image-metrics.mjs +306 -0
  198. package/skills/ew-impeccable/scripts/lib/impeccable-config.mjs +640 -0
  199. package/skills/ew-impeccable/scripts/lib/impeccable-paths.mjs +137 -0
  200. package/skills/ew-impeccable/scripts/lib/is-generated.mjs +72 -0
  201. package/skills/ew-impeccable/scripts/lib/live-path-globs.mjs +37 -0
  202. package/skills/ew-impeccable/scripts/lib/open-system-browser.mjs +26 -0
  203. package/skills/ew-impeccable/scripts/lib/png.mjs +281 -0
  204. package/skills/ew-impeccable/scripts/lib/provider.mjs +5 -0
  205. package/skills/ew-impeccable/scripts/lib/raster.mjs +194 -0
  206. package/skills/ew-impeccable/scripts/lib/roll-selection.mjs +369 -0
  207. package/skills/ew-impeccable/scripts/lib/staleness-deep.mjs +491 -0
  208. package/skills/ew-impeccable/scripts/lib/staleness-notice.mjs +169 -0
  209. package/skills/ew-impeccable/scripts/lib/staleness.mjs +532 -0
  210. package/skills/ew-impeccable/scripts/lib/surface-briefs.mjs +149 -0
  211. package/skills/ew-impeccable/scripts/lib/target-args.mjs +42 -0
  212. package/skills/ew-impeccable/scripts/lib/target-slug.mjs +33 -0
  213. package/skills/ew-impeccable/scripts/lib/template-extensions.mjs +146 -0
  214. package/skills/ew-impeccable/scripts/live/accept-css.mjs +617 -0
  215. package/skills/ew-impeccable/scripts/live/accept-verify.mjs +60 -0
  216. package/skills/ew-impeccable/scripts/live/browser-script-parts.mjs +84 -0
  217. package/skills/ew-impeccable/scripts/live/completion.mjs +28 -0
  218. package/skills/ew-impeccable/scripts/live/event-validation.mjs +199 -0
  219. package/skills/ew-impeccable/scripts/live/frameworks/astro.mjs +47 -0
  220. package/skills/ew-impeccable/scripts/live/frameworks/detect-utils.mjs +73 -0
  221. package/skills/ew-impeccable/scripts/live/frameworks/index.mjs +143 -0
  222. package/skills/ew-impeccable/scripts/live/frameworks/journal.mjs +197 -0
  223. package/skills/ew-impeccable/scripts/live/frameworks/nextjs.mjs +49 -0
  224. package/skills/ew-impeccable/scripts/live/frameworks/nuxt.mjs +161 -0
  225. package/skills/ew-impeccable/scripts/live/frameworks/script-src.mjs +17 -0
  226. package/skills/ew-impeccable/scripts/live/frameworks/static-html.mjs +26 -0
  227. package/skills/ew-impeccable/scripts/live/frameworks/sveltekit.mjs +71 -0
  228. package/skills/ew-impeccable/scripts/live/frameworks/tag-strategy.mjs +247 -0
  229. package/skills/ew-impeccable/scripts/live/frameworks/tanstack-start.mjs +70 -0
  230. package/skills/ew-impeccable/scripts/live/frameworks/vite-generic.mjs +42 -0
  231. package/skills/ew-impeccable/scripts/live/generation-preflight.mjs +149 -0
  232. package/skills/ew-impeccable/scripts/live/insert-ui.mjs +458 -0
  233. package/skills/ew-impeccable/scripts/live/instructions.mjs +142 -0
  234. package/skills/ew-impeccable/scripts/live/manual-apply.mjs +939 -0
  235. package/skills/ew-impeccable/scripts/live/manual-edit-routes.mjs +357 -0
  236. package/skills/ew-impeccable/scripts/live/manual-edits-buffer.mjs +152 -0
  237. package/skills/ew-impeccable/scripts/live/poll-lanes.mjs +14 -0
  238. package/skills/ew-impeccable/scripts/live/project-ignores.mjs +139 -0
  239. package/skills/ew-impeccable/scripts/live/roots.mjs +508 -0
  240. package/skills/ew-impeccable/scripts/live/session-store.mjs +563 -0
  241. package/skills/ew-impeccable/scripts/live/source-lock.mjs +105 -0
  242. package/skills/ew-impeccable/scripts/live/source-search.mjs +105 -0
  243. package/skills/ew-impeccable/scripts/live/svelte-ast.mjs +969 -0
  244. package/skills/ew-impeccable/scripts/live/svelte-component.mjs +1366 -0
  245. package/skills/ew-impeccable/scripts/live/sveltekit-adapter.mjs +304 -0
  246. package/skills/ew-impeccable/scripts/live/tanstack-adapter.mjs +259 -0
  247. package/skills/ew-impeccable/scripts/live/ui-surfaces.mjs +75 -0
  248. package/skills/ew-impeccable/scripts/live/vocabulary.mjs +171 -0
  249. package/skills/ew-impeccable/scripts/live-accept.mjs +938 -0
  250. package/skills/ew-impeccable/scripts/live-browser-dom.js +167 -0
  251. package/skills/ew-impeccable/scripts/live-browser-ignores.js +242 -0
  252. package/skills/ew-impeccable/scripts/live-browser-session.js +144 -0
  253. package/skills/ew-impeccable/scripts/live-browser.js +12851 -0
  254. package/skills/ew-impeccable/scripts/live-commit-manual-edits.mjs +1200 -0
  255. package/skills/ew-impeccable/scripts/live-complete.mjs +107 -0
  256. package/skills/ew-impeccable/scripts/live-copy-edit-agent.mjs +800 -0
  257. package/skills/ew-impeccable/scripts/live-discard-manual-edits.mjs +51 -0
  258. package/skills/ew-impeccable/scripts/live-inject.mjs +463 -0
  259. package/skills/ew-impeccable/scripts/live-insert.mjs +292 -0
  260. package/skills/ew-impeccable/scripts/live-manual-edit-evidence.mjs +368 -0
  261. package/skills/ew-impeccable/scripts/live-poll.mjs +430 -0
  262. package/skills/ew-impeccable/scripts/live-resume.mjs +123 -0
  263. package/skills/ew-impeccable/scripts/live-server.mjs +1698 -0
  264. package/skills/ew-impeccable/scripts/live-status.mjs +71 -0
  265. package/skills/ew-impeccable/scripts/live-target.mjs +30 -0
  266. package/skills/ew-impeccable/scripts/live-wrap.mjs +927 -0
  267. package/skills/ew-impeccable/scripts/live.mjs +334 -0
  268. package/skills/ew-impeccable/scripts/modern-screenshot.umd.js +14 -0
  269. package/skills/ew-impeccable/scripts/palette.mjs +628 -0
  270. package/skills/ew-impeccable/scripts/pin.mjs +352 -0
  271. package/skills/ew-impeccable/scripts/serve-question.mjs +1783 -0
  272. package/skills/ew-impeccable/scripts/surface-brief.mjs +74 -0
  273. package/skills/ew-knowledge/SKILL.md +35 -0
  274. package/skills/ew-knowledge/references/closeout-protocol.md +68 -0
  275. package/skills/ew-knowledge/references/knowledge-route.md +73 -0
  276. package/skills/ew-knowledge/references/wiki-maintenance.md +27 -0
  277. package/skills/ew-odyssey/SKILL.md +106 -0
  278. package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
  279. package/skills/ew-odyssey/references/odyssey-base.md +104 -0
  280. package/skills/ew-odyssey/references/odyssey-debug.md +264 -0
  281. package/skills/ew-odyssey/references/odyssey-defensive.md +351 -0
  282. package/skills/ew-odyssey/references/odyssey-improve.md +230 -0
  283. package/skills/ew-odyssey/references/odyssey-planex.md +294 -0
  284. package/skills/ew-odyssey/references/odyssey-review.md +233 -0
  285. package/skills/ew-odyssey/references/odyssey-security.md +231 -0
  286. package/skills/ew-odyssey/references/odyssey-ui.md +232 -0
  287. package/skills/ew-odyssey/references/prepare/odyssey-debug.md +102 -0
  288. package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +117 -0
  289. package/skills/ew-odyssey/references/prepare/odyssey-improve.md +95 -0
  290. package/skills/ew-odyssey/references/prepare/odyssey-planex.md +105 -0
  291. package/skills/ew-odyssey/references/prepare/odyssey-review.md +105 -0
  292. package/skills/ew-odyssey/references/prepare/odyssey-security.md +91 -0
  293. package/skills/ew-odyssey/references/prepare/odyssey-ui.md +88 -0
  294. package/skills/ew-odyssey/references/runtime-adapters.md +31 -0
  295. package/skills/ew-orchestrate/SKILL.md +89 -0
  296. package/skills/ew-orchestrate/references/auto-policy.md +66 -0
  297. package/skills/ew-orchestrate/references/boundary-grill.md +51 -0
  298. package/skills/ew-orchestrate/references/companion-route.md +40 -0
  299. package/skills/ew-orchestrate/references/ew-orchestrate.md +44 -0
  300. package/skills/ew-orchestrate/references/goal.md +51 -0
  301. package/skills/ew-orchestrate/references/orchestrator-run-loop.md +33 -0
  302. package/skills/ew-orchestrate/references/planning.md +54 -0
  303. package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +70 -0
  304. package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +24 -0
  305. package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +8 -0
  306. package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +138 -0
  307. package/skills/ew-orchestrate/steps/ew-auto-test/SKILL.md +80 -0
  308. package/skills/ew-orchestrate/steps/ew-auto-test/references/prepare.md +23 -0
  309. package/skills/ew-orchestrate/steps/ew-auto-test/references/workflow.md +31 -0
  310. package/skills/ew-orchestrate/steps/ew-blueprint/SKILL.md +122 -0
  311. package/skills/ew-orchestrate/steps/ew-blueprint/references/prepare.md +21 -0
  312. package/skills/ew-orchestrate/steps/ew-blueprint/references/workflow.md +28 -0
  313. package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +49 -0
  314. package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +50 -0
  315. package/skills/ew-orchestrate/steps/ew-debug/SKILL.md +85 -0
  316. package/skills/ew-orchestrate/steps/ew-debug/references/prepare.md +27 -0
  317. package/skills/ew-orchestrate/steps/ew-debug/references/workflow.md +31 -0
  318. package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +74 -0
  319. package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +27 -0
  320. package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +87 -0
  321. package/skills/ew-orchestrate/steps/ew-grill/SKILL.md +62 -0
  322. package/skills/ew-orchestrate/steps/ew-grill/references/prepare.md +26 -0
  323. package/skills/ew-orchestrate/steps/ew-grill/references/workflow.md +31 -0
  324. package/skills/ew-orchestrate/steps/ew-init/SKILL.md +56 -0
  325. package/skills/ew-orchestrate/steps/ew-init/references/prepare.md +25 -0
  326. package/skills/ew-orchestrate/steps/ew-init/references/workflow.md +28 -0
  327. package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +131 -0
  328. package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +8 -0
  329. package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
  330. package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +100 -0
  331. package/skills/ew-orchestrate/steps/ew-retrospective/SKILL.md +68 -0
  332. package/skills/ew-orchestrate/steps/ew-retrospective/references/prepare.md +18 -0
  333. package/skills/ew-orchestrate/steps/ew-retrospective/references/workflow.md +34 -0
  334. package/skills/ew-orchestrate/steps/ew-review/SKILL.md +45 -0
  335. package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +17 -0
  336. package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +116 -0
  337. package/skills/ew-orchestrate/steps/ew-roadmap/SKILL.md +62 -0
  338. package/skills/ew-orchestrate/steps/ew-roadmap/references/prepare.md +27 -0
  339. package/skills/ew-orchestrate/steps/ew-roadmap/references/workflow.md +28 -0
  340. package/skills/ew-orchestrate/steps/ew-test/SKILL.md +99 -0
  341. package/skills/ew-orchestrate/steps/ew-test/references/prepare.md +23 -0
  342. package/skills/ew-orchestrate/steps/ew-test/references/workflow.md +23 -0
  343. package/skills/ew-orchestrate/steps/ew-verify/SKILL.md +73 -0
  344. package/skills/ew-orchestrate/steps/ew-verify/references/prepare.md +21 -0
  345. package/skills/ew-orchestrate/steps/ew-verify/references/workflow.md +29 -0
  346. package/skills/ew-skill-design/SKILL.md +30 -0
  347. package/skills/ew-skill-design/references/package-contract.md +40 -0
  348. package/skills/ew-skill-design/references/validation.md +21 -0
  349. package/skills/team-swarm/SKILL.md +68 -0
  350. package/skills/team-swarm/references/mcp-coordination.md +14 -0
  351. package/skills/team-swarm/roles/analyst/role.md +181 -0
  352. package/skills/team-swarm/roles/ant/role.md +149 -0
  353. package/skills/team-swarm/roles/coordinator/commands/converge.md +112 -0
  354. package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +136 -0
  355. package/skills/team-swarm/roles/coordinator/commands/iterate.md +171 -0
  356. package/skills/team-swarm/roles/coordinator/role.md +170 -0
  357. package/skills/team-swarm/roles/scorer/role.md +150 -0
  358. package/skills/team-swarm/scripts/aco.py +646 -0
  359. package/skills/team-swarm/scripts/pheromone.py +144 -0
  360. package/skills/team-swarm/scripts/scoring.py +111 -0
  361. package/skills/team-swarm/scripts/test_aco.py +606 -0
  362. package/skills/team-swarm/specs/ant-output-schema.md +127 -0
  363. package/skills/team-swarm/specs/convergence-criteria.md +108 -0
  364. package/skills/team-swarm/specs/pheromone-schema.md +125 -0
  365. package/skills/team-swarm/specs/swarm-config-template.json +71 -0
  366. package/skills/team-swarm/specs/swarm-protocol.md +119 -0
  367. package/skills/workflow-evolve/SKILL.md +64 -0
  368. package/skills/workflow-evolve/references/agy-gate.md +27 -0
  369. package/skills/workflow-evolve/references/auto-loop.md +23 -0
  370. package/skills/workflow-evolve/references/history-review.md +15 -0
  371. package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +86 -0
  372. package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
  373. package/skills/workflow-evolve/scripts/evolve-loop.mjs +260 -0
  374. package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
  375. package/workflows/index.json +33 -0
@@ -0,0 +1,112 @@
1
+ # Command: converge
2
+
3
+ ## Workflow
4
+
5
+ ### Step 1: Call aco.py report
6
+
7
+ ```
8
+ Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> report
9
+ ```
10
+
11
+ Parse stdout JSON. Expected:
12
+ ```json
13
+ {
14
+ "_meta": {"kind": "swarm-report", "schema": "swarm-report/1.0", "role": "attachment"},
15
+ "status": "ok",
16
+ "best": { ant_id, iteration, path, score, candidate_solution, evidence, ... },
17
+ "top_k": [<top 5 trails>],
18
+ "convergence_curve": [{iteration, entropy, tau_max, tau_mean}, ...],
19
+ "final_pheromone_stats": {...},
20
+ "iterations_completed": <int>
21
+ }
22
+ ```
23
+
24
+ Save the complete stdout JSON, including `_meta`, to `{run_dir}/outputs/swarm-report.json` (raw data for analyst). Do not wrap, strip, or replace the metadata.
25
+
26
+ ### Step 2: Dispatch analyst worker
27
+
28
+ Dispatch an `analyst` worker via host subagent/swarm (`role_spec: <skill_root>/roles/analyst/role.md`) with `outputs/swarm-report.json`, `work/team/best.json`, `work/team/trails/*.jsonl`, and `<config.ant_prompt.objective>` to synthesize `outputs/best-solution.md`, and wait/join for completion.
29
+
30
+ ### Step 3: On analyst callback
31
+
32
+ Give `{run_dir}/outputs/best-solution.md` the `kind: swarm-best-solution`, `schema: swarm-best-solution/1.0`, and `role: primary` YAML frontmatter. Seal with `evolve run complete <run_id> --session <session-id> --actor <actor> --expected-orchestration-revision <rev> --expected-run-revision <rev> --summary "<summary>" --verdict done` and fix any output contract errors it reports.
33
+
34
+ If missing -> ask user (`ask_question` / `request_user_input`) to skip synthesis or retry analyst.
35
+
36
+ ### Step 3.5: Run lifecycle completion
37
+
38
+ ```
39
+ +- Run lifecycle completion:
40
+ | - Read run_id from team-session.json.run.run_id
41
+ | - Write {run_dir}/report.md with frontmatter (verdict/summary/constraints/decisions/concerns; constraints/decisions = {text,status} objects, id auto-derived)
42
+ | - Before requesting completion, merge-write team status="completed", converged_at=<iso8601>, convergence_reason=<triggered_by>, preserving run; log the final state_update now. If completion is blocked, leave it unsealed and merge-write status="paused" with the blocker.
43
+ | - If self-started, run `evolve run complete <run_id> --session <session-id> --actor <actor> --expected-orchestration-revision <rev> --expected-run-revision <rev> --summary "<summary>" --verdict done` (and `evolve session complete --session <session-id> --actor <actor> --expected-orchestration-revision <rev>` when the chain is terminal; follow the `ew-orchestrate` controller run loop guide); if dispatched, return to the claim-holding orchestrator
44
+ | - If complete fails: fix the blocking gate and retry once; still failing -> do NOT archive/clean - keep the team active (status=paused) and report the blocking gate
45
+ ```
46
+
47
+ ### Step 4: Build completion summary
48
+
49
+ ```
50
+ [coordinator] ============================================
51
+ [coordinator] SWARM CONVERGED
52
+ [coordinator]
53
+ [coordinator] Iterations: <iterations_completed> / <max_iterations>
54
+ [coordinator] Trigger: <triggered_by[0]>
55
+ [coordinator] Total ants spawned: <iterations * n_ants>
56
+ [coordinator]
57
+ [coordinator] Best Solution:
58
+ [coordinator] ant_id: <best.ant_id>
59
+ [coordinator] iteration: <best.iteration>
60
+ [coordinator] path: <best.path joined with " -> ">
61
+ [coordinator] verified_score: <best.score>
62
+ [coordinator] summary: <best.candidate_solution.summary>
63
+ [coordinator]
64
+ [coordinator] Convergence curve (entropy):
65
+ [coordinator] iter 1: <e1> iter 2: <e2> iter 3: <e3> ...
66
+ [coordinator]
67
+ [coordinator] Deliverables:
68
+ [coordinator] - {run_dir}/outputs/best-solution.md (analyst synthesis)
69
+ [coordinator] - {run_dir}/outputs/swarm-report.json (raw data)
70
+ [coordinator] - best.json (canonical best)
71
+ [coordinator] - trails/*.jsonl (full exploration log)
72
+ [coordinator]
73
+ [coordinator] Session: <session_path>
74
+ [coordinator] ============================================
75
+ ```
76
+
77
+ ### Step 5: Preserve completed state
78
+
79
+ The final team state and state_update were written before completion in Step 3.5. After sealing, inspect the frozen state read-only; do not update team-session.json or append Run-local logs.
80
+
81
+ ### Step 6: Completion action (interactive)
82
+
83
+ Ask the user via host structured question (`ask_question` / `request_user_input`) to choose one of:
84
+ - **Archive & Clean (Recommended)** — Close/join active worker handles; output final summary; preserve the sealed Run directory and evidence.
85
+ - **Keep Active** — Keep team available for read-only inspection; follow-up work requires a fresh Run.
86
+ - **Export Best Solution** — Prompt for target path, copy `best-solution.md` + `best.json`, then Archive & Clean.
87
+ - **Run Another Round** — Prompt for additional `K`, then follow the fresh-Run handoff below (never reset or iterate in the completed Run).
88
+
89
+ | Choice | Steps |
90
+ |--------|-------|
91
+ | Archive & Clean | Close active worker handles; output final summary; preserve the sealed Run directory and evidence |
92
+ | Keep Active | Keep the live team for read-only inspection; output fresh-Run follow-up instructions; do not change completed team state |
93
+ | Export Best Solution | Ask target path; copy best-solution.md + best.json; then Archive & Clean |
94
+ | Run Another Round | Ask additional K; follow the fresh-Run handoff below; never reset or iterate in the completed Run |
95
+
96
+ ### Fresh-Run handoff for another round
97
+
98
+ - Completion above seals the old Run. Never write its `work/team`, `outputs/`, report, counters, or pheromone again, including changing its completed team state to paused. Keep Active preserves the live team for inspection only; it does not reopen the Run.
99
+ - For an orchestrator-dispatched Run, return the requested K and exact old locator to the completion owner and wait for a new birth packet. Do not create a competing Run or continue under the old locator.
100
+ - For a self-started Run, use the receipt-chained `evolve session open` / `evolve session chain insert` / `evolve run next` flow from `roles/coordinator/role.md`. If the prior Session is terminal/completed, open a new Session; otherwise the owner inserts and dispatches a new chain step. Do not reuse the completed step or Run ID.
101
+ - Resolve a distinct new `session_id` / `run_id` / `run_dir` before any follow-up write. Initialize a new `work/team/team-session.json` via init-swarm.md with the new public locator and reset round-local counters there only.
102
+ - If retaining pheromone is requested, read the old frozen config/task-space/pheromone as seed inputs and copy only compatible inputs into the new Run's coordination directory after initialization; record their exact source locator. Set the new iteration cap to K. Do not copy old outputs, trails, scores, worker liveness, or completion state as new-round evidence. Spawn new ants through Phase 3 iterate.md only after the new locator and seed/config are verified.
103
+ - If allocation or seed validation fails, keep the old Run immutable and report the blocker; never fall back to iterating there.
104
+
105
+ ## Failure Cases
106
+
107
+ | Failure | Action |
108
+ |---------|--------|
109
+ | `aco.py report` fails | Stop before analyst dispatch; keep Run unsealed and team paused, record stderr, repair the script/state, then retry `report`. Do not substitute an untyped manual report for required `outputs/swarm-report.json`. |
110
+ | Analyst worker crashes | Retry once. If synthesizing a minimal best-solution.md from best.json is explicitly chosen, include the required `swarm-best-solution/1.0` primary YAML frontmatter for completion. |
111
+ | best.json missing | Pipeline ran but no successful ant - report failure, keep session for inspection |
112
+ | Run Another Round chosen but max_iterations already at limit | Ask user to raise the cap before continuing |
@@ -0,0 +1,136 @@
1
+ # Command: init-swarm
2
+
3
+ ## Inputs
4
+
5
+ - `swarm-config.json` from Phase 1 (in memory until the exact Run directory is resolved)
6
+ - canonical `session_id` from the birth packet or self-start receipt
7
+ - `skill_root` = directory containing the active `team-swarm/SKILL.md` (do not assume project cwd or a particular mirror)
8
+
9
+ ## Workflow
10
+
11
+ ### Step 0: Resolve Run authority
12
+
13
+ Perform the coordinator role's **Run Lifecycle Integration** before creating `work/team` or writing config. Obtain the exact `session_id`, `run_id`, and `run_dir` from the birth packet or receipt; do not infer a Run path from a local sidecar.
14
+
15
+ ### Step 1: Resolve paths
16
+
17
+ ```
18
+ run_dir = <exact path returned by Run birth packet or team-session.json.run.run_dir>
19
+ skill_root = <resolved directory containing this SKILL.md>
20
+ session_path = Path(run_dir) / "work" / "team"
21
+ # Do not prepend pwd to run_dir: it may already be absolute.
22
+ ```
23
+
24
+ ### Step 2: Create session directory tree
25
+
26
+ Create `<session_path>` and subdirectories (`pheromone/history`, `trails`, `scores`, `artifacts`, `wisdom`) cross-platform (do NOT use POSIX brace expansion `{...}` on Windows PowerShell):
27
+
28
+ ```python
29
+ python -c "from pathlib import Path; s = Path(r'<session_path>'); [ (s/d).mkdir(parents=True, exist_ok=True) for d in ('pheromone/history','trails','scores','artifacts','wisdom') ]"
30
+ ```
31
+
32
+ ### Step 3: Write swarm-config.json
33
+
34
+ Write the Phase 1-generated config to `<session_path>/swarm-config.json`.
35
+
36
+ Validate before write:
37
+ - `task_space.nodes` OR `task_space.auto_discover_from` present
38
+ - `swarm.n_ants` >= 2 (single-ant defeats swarm purpose)
39
+ - `convergence.max_iterations` >= 1
40
+
41
+ ### Step 4: Verify Evolve Run roster
42
+
43
+ ```
44
+ Bash: evolve team list --session <session_id> --run <run_id>
45
+ ```
46
+
47
+ ### Step 5: Write role-binding.json
48
+
49
+ ```json
50
+ {
51
+ "ant": "<skill_root>/roles/ant/role.md",
52
+ "scorer": "<skill_root>/roles/scorer/role.md",
53
+ "analyst": "<skill_root>/roles/analyst/role.md"
54
+ }
55
+ ```
56
+
57
+ Saved at `<session_path>/role-binding.json` — workers resolve their role.md from this file.
58
+
59
+ ### Step 6: Call aco.py init
60
+
61
+ ```
62
+ Bash: python <skill_root>/scripts/aco.py --session <session_path> --run-dir <run_dir> init
63
+ ```
64
+
65
+ Parse stdout JSON. On `status: "error"`:
66
+ - exit_code 2 -> config validation error -> ask user via structured question (`ask_question` / `request_user_input`) to fix
67
+ - exit_code 1 -> runtime error -> log to issues.md + retry once
68
+
69
+ On success, capture:
70
+ - `n_nodes` — search space size
71
+ - `n_edges` — initial edge count
72
+ - `pheromone_path` — confirm written
73
+
74
+ ### Step 7: Initialize team-session.json
75
+
76
+ ```json
77
+ {
78
+ "session_id": "<run-id>",
79
+ "task_description": "<user task>",
80
+ "status": "active",
81
+ "team_name": "swarm",
82
+ "skill": "team-swarm",
83
+ "iteration": 0,
84
+ "max_iterations": <config.convergence.max_iterations>,
85
+ "n_ants_per_iter": <config.swarm.n_ants>,
86
+ "config_path": "swarm-config.json",
87
+ "pheromone_path": "pheromone/current.json",
88
+ "roles": ["coordinator", "ant", "scorer", "analyst"],
89
+ "scoring_mode": "<config.scoring.mode>",
90
+ "active_workers": [],
91
+ "completed_iterations": [],
92
+ "completion_action": "interactive",
93
+ "created_at": "<iso8601>",
94
+ "updated_at": "<iso8601>",
95
+ "run": { "session_id": "<canonical-session-id>", "run_id": "<run-id>", "run_dir": "<run-dir>" }
96
+ }
97
+ ```
98
+
99
+ ### Step 8: Initialize wisdom files
100
+
101
+ Create empty wisdom files with headers:
102
+ - `wisdom/learnings.md` — cross-iteration insights
103
+ - `wisdom/decisions.md` — config refinements made mid-pipeline
104
+ - `wisdom/issues.md` — errors and hallucinations log
105
+
106
+ ### Step 9: Log initialization state_update
107
+
108
+ Save the phase summary in team-session.json.
109
+
110
+ ### Step 10: Proceed to Phase 3 (iterate.md)
111
+
112
+ Do NOT spawn any workers in this command. First spawn happens in iterate.md step 4.
113
+
114
+ ## Success Criteria
115
+
116
+ - `{run_dir}/work/team/swarm-config.json` exists and validates
117
+ - `{run_dir}/work/team/pheromone/current.json` exists with `iteration: 0`
118
+ - `{run_dir}/work/team/task-space.json` exists with `n_nodes > 0`
119
+ - team-session.json initialized with `iteration: 0`
120
+
121
+ ## Failure Recovery
122
+
123
+ | Failure | Action |
124
+ |---------|--------|
125
+ | Config invalid | Ask user via structured question (`ask_question` / `request_user_input`), regenerate, retry |
126
+ | `aco.py init` runtime error | Log to issues.md, retry once, then ask user (abort/refine) |
127
+ | Directory creation fails | Check disk space / permissions, retry |
128
+ | Roster conflict / existing session | Resolve the exact `run_id` / `run_dir`, inspect its one `work/team/team-session.json`, and offer resume only if lifecycle reconciliation verifies a matching active/paused `team-swarm` session; otherwise fail closed |
129
+
130
+ ### Run Conflict Recovery Contract
131
+
132
+ 1. Start from the birth-packet `run_id` / `run_dir`. Do not scan sibling Runs and do not treat an arbitrary existing team name as a resumable match.
133
+ 2. Inspect the exact team session and reconcile canonical Run status, broker-backed live agents, non-terminal tasks, and ordered activity timestamps through the runtime lifecycle adapter.
134
+ 3. Offer **Resume** only when the exact candidate is a verified matching `team-swarm` session with lifecycle `active` or `paused`. If health is `stale_candidate`, show the evidence and require an explicit operator choice; never convert stale health into cleanup eligibility.
135
+ 4. If exact locator evidence is absent, mismatched, `unknown`, or `inconsistent`, fail closed without scanning or guessing an unlocated candidate.
136
+ 5. Do not offer a generic "clean or resume" action. `abandoned` requires a separate explicit audited transition after all liveness/activity checks, and cleanup requires a second confirmation that removes only team coordination state, never Run authority or outputs.
@@ -0,0 +1,171 @@
1
+ # Command: iterate
2
+
3
+ ## Two Entry Points
4
+
5
+ | Entry | Trigger | Action |
6
+ |-------|---------|--------|
7
+ | **Iteration start** | Phase 3 invoked OR previous iteration converged=false | Run "Iteration Start" workflow |
8
+ | **Iteration end** | All ants of current iter reported via callback | Run "Iteration End" workflow |
9
+
10
+ ## Iteration Start Workflow
11
+
12
+ ### Step 1: Determine iteration number
13
+
14
+ ```
15
+ k = session.iteration + 1
16
+ ```
17
+
18
+ If `k > session.max_iterations`: force converge to Phase 4 (safety net).
19
+
20
+ ### Step 2: Call aco.py select
21
+
22
+ ```text
23
+ python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> select --iter <k>
24
+ ```
25
+
26
+ Parse stdout JSON. Expected:
27
+ ```json
28
+ {
29
+ "status": "ok",
30
+ "iteration": <k>,
31
+ "n_assignments": <N>,
32
+ "assignments": [
33
+ {
34
+ "ant_id": "ANT-<k>-<i>",
35
+ "start_node": "<node>",
36
+ "edge_preferences": {"a::b": 0.4, ...},
37
+ "max_path_length": <int>,
38
+ "iteration": <k>
39
+ }, ...
40
+ ]
41
+ }
42
+ ```
43
+
44
+ On error -> log to issues.md and ask user (`ask_question` / `request_user_input`) to retry or abort.
45
+
46
+ For a Run, `select --iter <k>` persists `assignments/<k>.json` before dispatch. Re-run the same command after an interruption to recover the original IDs and start nodes. Use the roster and task mapping to reuse live jobs and completed artifacts. Create a worker only for an assignment that still needs one.
47
+
48
+ ### Step 3: Record ant assignments in Evolve roster
49
+
50
+ Register each `ANT-<k>-<i>` assignment via `evolve team assign` (and update the host progress plan if available). Assignment IDs `ANT-<k>-<i>` are persisted in `assignments/<k>.json` and tracked by the Evolve team roster (`evolve team assign` / `evolve team list`).
51
+
52
+ ### Step 4: Dispatch N ant workers in parallel
53
+
54
+ Dispatch one worker per assignment in parallel using the host's subagent/swarm mechanism (`invoke_subagent` or `swarm` in Antigravity; `spawn_agent` in Codex) with the payload below, and join/wait for all dispatched workers before advancing:
55
+
56
+ ```text
57
+ ## Role Assignment
58
+ role: ant
59
+ role_spec: <skill_root>/roles/ant/role.md
60
+ session: <session_path>
61
+ session_id: <run-id>
62
+ run_dir: <exact run_dir from the birth packet or team-session.json.run.run_dir>
63
+ requirement: <config.ant_prompt.objective>
64
+ inner_loop: false
65
+
66
+ ## Assignment
67
+ <assignment JSON>
68
+ ```
69
+
70
+ ### Step 5: Update session state
71
+
72
+ ```
73
+ session.iteration = <k> (mark "in progress")
74
+ session.active_workers = [<list of ant IDs>]
75
+ ```
76
+
77
+ Persist the iteration and assignment IDs in team-session.json.
78
+
79
+ ### Step 6: STOP
80
+
81
+ Wait for ant callbacks. Each ant uses evolve team report for its assignment. When ALL N reported, callback handler invokes "Iteration End" workflow.
82
+
83
+ ---
84
+
85
+ ## Iteration End Workflow
86
+
87
+ ### Step 1: Verify completion
88
+
89
+ Check `ANT-<k>-*` task statuses. If any still in_progress: not yet complete, do nothing.
90
+
91
+ If all completed -> proceed.
92
+
93
+ ### Step 2: (Conditional) Dispatch scorer
94
+
95
+ If `config.scoring.mode == "llm"`, dispatch a `scorer` worker (`role_spec: <skill_root>/roles/scorer/role.md`) with iteration `<k>`, output path `{run_dir}/work/team/scores/iter-<k>-scores.json`, and input glob `{run_dir}/outputs/ant-<k>-*.json`, then wait/join for completion before Step 3.
96
+
97
+ The callback must identify `SCORE-<k>` and the same iteration. Check that the output covers all ant artifacts for this iteration before invoking `update`. Once the controller has committed the iteration, replay with the same scoring decision and inputs.
98
+
99
+ If `scoring.mode == "script"` or `"fallback"` -> proceed directly to Step 3.
100
+
101
+ ### Step 3: Call aco.py update
102
+
103
+ ```
104
+ Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> update --iter <k>
105
+ ```
106
+
107
+ Parse stdout JSON. Expected:
108
+ ```json
109
+ {
110
+ "status": "ok",
111
+ "iteration": <k>,
112
+ "n_ants_processed": <N>,
113
+ "mean_score": <float>,
114
+ "best_score": <float>,
115
+ "delta": <float>,
116
+ "elite_updated": <bool>,
117
+ "hallucinations_flagged": [<ant_ids>],
118
+ "stats": {<pheromone stats>}
119
+ }
120
+ ```
121
+
122
+ ### Step 4: Log iteration result
123
+
124
+ Save the phase summary in team-session.json.
125
+
126
+ If `hallucinations_flagged.length > N/2`: append warning to wisdom/issues.md (high-noise iteration).
127
+
128
+ ### Step 5: Call aco.py converged
129
+
130
+ ```
131
+ Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> converged
132
+ ```
133
+
134
+ Parse:
135
+ ```json
136
+ { "converged": <bool>, "triggered_by": [...], "reason": "...", "metrics": {...} }
137
+ ```
138
+
139
+ ### Step 6: Branch on convergence
140
+
141
+ ```
142
+ if converged:
143
+ update session: completed_iterations.push(k), status = "converging"
144
+ -> proceed to Phase 4 (converge.md)
145
+ else:
146
+ update session: completed_iterations.push(k), active_workers = []
147
+ -> re-enter "Iteration Start" workflow with k+1
148
+ ```
149
+
150
+ ### Step 7: Output progress to user
151
+
152
+ After each iteration:
153
+ ```
154
+ [coordinator] Iteration <k>/<max> complete.
155
+ [coordinator] best=<best_score> mean=<mean_score> delta=<delta>
156
+ [coordinator] entropy=<entropy> hallucinations=<count>
157
+ [coordinator] Status: <converged | continuing to iter k+1>
158
+ ```
159
+
160
+ ---
161
+
162
+ ## Edge Cases
163
+
164
+ | Condition | Handling |
165
+ |-----------|----------|
166
+ | Ant task failed | Mark task failed; if >50% failed in iter -> halt and ask user via structured prompt |
167
+ | Ant produced no artifact | Script's update will skip it; if all skipped -> error -> halt |
168
+ | `aco.py update` fails | Retry once; if persistent -> halt with error report |
169
+ | Scorer worker fails | Record the failure. For an intentional self-score fallback in a Run, use `update --iter <k> --allow-score-fallback` and record that choice for replay. |
170
+ | Iteration takes too long | After timeout (configurable), check the host job and Evolve assignment roster |
171
+ | User sends `feedback <text>` mid-iteration | Append to wisdom/learnings.md; apply at next iteration start (not mid-iter) |
@@ -0,0 +1,170 @@
1
+ ---
2
+ role: coordinator
3
+ ---
4
+
5
+ # Coordinator Role — team-swarm
6
+
7
+ ## Identity
8
+
9
+ - **Name**: `coordinator` | **Tag**: `[coordinator]`
10
+ - **Responsibility**: Translate user intent into swarm-config -> drive K-iteration outer loop -> dispatch N ants per iteration -> consume script verdicts -> deliver final synthesis
11
+
12
+ ## Boundaries
13
+
14
+ ### MUST
15
+ - Generate `swarm-config.json` from user task description (Phase 1)
16
+ - Invoke `scripts/aco.py` for ALL numeric decisions (selection, update, convergence)
17
+ - Spawn ant workers with strict role-spec assignment + path hints from script
18
+ - After each iteration callback: call `aco.py update` -> `aco.py converged` -> decide loop/exit
19
+ - Persist session state in the Evolve assignment roster and Python controller checkpoints
20
+ - Trigger analyst for final synthesis when converged
21
+
22
+ ### MUST NOT
23
+ - Make selection/update/convergence decisions on its own — these belong to the script
24
+ - Modify `pheromone/*.json`, `best.json`, or `trails/*.jsonl` directly — script owns these
25
+ - Skip the convergence check after each iteration
26
+ - Spawn more than `config.swarm.n_ants` ants per iteration
27
+ - Exceed `config.convergence.max_iterations` outer loops
28
+
29
+ ---
30
+
31
+ ## Message Types
32
+
33
+ | Type | Direction | Trigger |
34
+ |------|-----------|---------|
35
+ | state_update | outbound | Iteration start/end, session init |
36
+ | task_unblocked | outbound | Ant batch ready |
37
+ | ant_done | inbound | Individual ant completion (rolled up to batch check) |
38
+ | iteration_complete | inbound | All ants in batch reported |
39
+ | capability_gap | inbound | Ant requests config change |
40
+ | error | inbound | Worker / script failure |
41
+
42
+ ## Command Execution Protocol
43
+
44
+ When coordinator needs to execute a phase command:
45
+
46
+ 1. Read the command file: `roles/coordinator/commands/<command-name>.md`
47
+ 2. Follow the workflow defined inline
48
+ 3. Commands are inline execution guides — NOT separate agents
49
+
50
+ ## Toolbox
51
+
52
+ | Tool | Type | Purpose |
53
+ |------|------|---------|
54
+ | [Initialization](commands/init-swarm.md) | Command | Phase 2: build swarm-config + call `aco.py init` |
55
+ | [Iteration](commands/iterate.md) | Command | Phase 3: single iteration loop body (select/spawn/update) |
56
+ | [Convergence](commands/converge.md) | Command | Phase 4: convergence handler + analyst spawn |
57
+ | `scripts/aco.py` | Script | All numeric decisions (Python subprocess) |
58
+ | team-worker | Subagent | Worker dispatch (ant, scorer, analyst) via host subagent / swarm |
59
+ | host plan / roster | System | Track assignments and join/await workers before concluding |
60
+ | evolve team | Evolve runtime | Assignment and result receipts |
61
+ | host user prompt | System | Clarify ambiguity / failure (`ask_question` or `request_user_input`) |
62
+
63
+ ---
64
+
65
+ ## Entry Router
66
+
67
+ | Detection | Condition | Handler |
68
+ |-----------|-----------|---------|
69
+ | Worker callback | Message contains `[ant]` / `[scorer]` / `[analyst]` | -> handleCallback |
70
+ | Status check | Args contain `check` or `status` | -> handleCheck |
71
+ | Manual resume | Args contain `resume` or `continue` | -> handleResume |
72
+ | Iteration complete | All ants of current iteration reported | -> Phase 3.5 (update + converged?) |
73
+ | Pipeline complete | aco.py converged returned true | -> Phase 4 |
74
+ | Interrupted session | Active session exists in `{run_dir}/work/team/` | -> Phase 0 |
75
+ | New session | None of above | -> Phase 1 |
76
+
77
+ ---
78
+
79
+ ## Phase 0: Session Resume Check
80
+
81
+ 1. **Exact Run locator first**: when the birth packet supplies `run_id` / `run_dir`, inspect only `{run_dir}/work/team/team-session.json`. An exact `run_dir` contains at most one team session; do not scan sibling Runs and do not enter a multiple-candidate branch. If the locator is absent or inconsistent, fail closed.
82
+ 2. Reconcile the exact candidate through the runtime lifecycle adapter before resuming: canonical Run status, broker-backed live agents, non-terminal team tasks, and the ordered activity clock.
83
+ 3. Resume only a verified matching `team-swarm` session whose canonical lifecycle is `active` or `paused`. Reconcile `list_agents` vs `session.iteration` vs `pheromone/current.json` before dispatching any worker.
84
+ 4. `stale_candidate` is derived health, never a lifecycle and never cleanup eligibility. An operator may explicitly resume an active/paused stale candidate after reviewing evidence, or request an audited transition to `abandoned`; TTL alone must not persist abandonment or delete state.
85
+ 5. Abandonment and cleanup are separate confirmed operations. Abandon only after rechecking Run status, live agents, non-terminal tasks, and activity; cleanup requires a second confirmation and may remove only `{run_dir}/work/team`, never `run.json`, `outputs/`, artifacts, evidence, or Session metadata.
86
+ 6. Reopen the saved assignment batch for this iteration. Match each task with its roster entry, callback and artifact. Wait for live workers and retain completed work. Retry only a missing or failed assignment. For LLM scoring, recover the scorer job and score file before updating. If `pheromone/updates/<k>.json` exists, use its `scoring` value for replay (`fallback` requires `--allow-score-fallback`). Continue with the controller's committed iteration.
87
+
88
+ ---
89
+
90
+ ## Phase 1: Task Analysis + Config Generation
91
+
92
+ **Objective**: Translate user task into `swarm-config.json`.
93
+
94
+ **Workflow**:
95
+
96
+ 1. Parse user task description (text-level only, no codebase exploration)
97
+ 2. Clarify via the host structured question tool if ambiguous:
98
+ - What is the search space? (file glob, explicit node list, abstract decisions)
99
+ - What is the objective? (find best X, discover Y, optimize Z)
100
+ - How should results be scored? (test pass rate, lint, custom rule, LLM judge)
101
+ - Budget? (max iterations, max ants per iter, token budget)
102
+ 3. Generate `swarm-config.json` (see template at `specs/swarm-config-template.json`):
103
+ - `swarm.n_ants` (default 5)
104
+ - `swarm.max_iterations` -> mirrored into `convergence.max_iterations`
105
+ - `aco.alpha/beta/rho/q` (defaults sane)
106
+ - `task_space.nodes` OR `task_space.auto_discover_from`
107
+ - `scoring.mode` ∈ {script, llm, fallback} based on user answer
108
+ - `ant_prompt.objective` — the actual goal injected into ant role-spec at spawn
109
+ 4. Keep config in memory until the Run birth packet provides the exact `run_dir` (self-start Run allocation is the first action of Phase 2). Never write into a guessed Run directory.
110
+
111
+ **CRITICAL**: Phase 1 does NOT call `aco.py`. It only produces the config.
112
+
113
+ ---
114
+
115
+ ## Phase 2: Init Swarm + Session Setup
116
+
117
+ Delegate to `@commands/init-swarm.md`:
118
+
119
+ 1. Resolve or self-start the exact Session/Run as described in `init-swarm.md` before any Run-scoped file write.
120
+ 2. Create session folder structure:
121
+ ```
122
+ {run_dir}/work/team/
123
+ ├── swarm-config.json (from Phase 1)
124
+ ├── pheromone/, trails/, scores/, artifacts/, wisdom/
125
+ └── role-binding.json (paths to role.md files)
126
+ ```
127
+ 3. Verify the Evolve Run roster with `evolve team list --session <session_id> --run <run_id>`
128
+ 4. Bash: `python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> init`
129
+ 5. Parse stdout JSON: capture `n_nodes`, `n_edges`, `pheromone_path`
130
+ 6. Initialize team-session.json with `iteration: 0`, `status: "active"`
131
+ 7. Record the config summary in team-session.json
132
+
133
+ ### Run Lifecycle Integration
134
+
135
+ Before creating the session folder or writing `swarm-config.json`:
136
+
137
+ 1. **Resolve Run** (birth-packet first): if the dispatch context already carries `run_id` / `run_dir` (injected by an orchestrator), retain them in memory and persist them at init-swarm Step 7 after creating the parent directory; skip self-start — a second allocation mints a duplicate Run. Otherwise execute this receipt-chained self-start recipe; every revision comes from the immediately preceding receipt and `--actor` carries the authorized identity (`--participant` defaults to it; the CLI derives a stable request ID per distinct invocation):
138
+ ```bash
139
+ evolve session open "<task summary>" --id <slug> --actor {actor_id}
140
+ evolve session chain insert --session {session_id} --step-id {step_id} --command team-swarm --arg "<task summary>" --actor {actor_id} --expected-orchestration-revision {open_orchestration_revision}
141
+ evolve run next --session {session_id} --actor {actor_id} --expected-orchestration-revision {insert_orchestration_revision}
142
+ ```
143
+ - Slug format: `YYYYMMDD-team-swarm-<topic>` (ASCII, ≤64 chars)
144
+ - Store returned canonical `session_id`, `run_id`, and `run_dir` in `team-session.json`:
145
+ ```json
146
+ "run": { "session_id": "<canonical-session-id>", "run_id": "<id>", "run_dir": "<path>" }
147
+ ```
148
+ 2. **Resume**: Resolve exact `session_id` + `run_id` + `run_dir` from the birth packet or `team-session.json.run`; never infer a Run ID from output files. Read `evolve run check <run_id> --session <session_id>` for status/output blockers, then `evolve run brief <run_id> --session <session_id>` for the structured `continuation`. If sealed, follow the brief's continuation; allocate another Run only through a freshly fenced `run next` when it reports a pending step. If the locator is absent or inconsistent, fail closed rather than minting a duplicate Run.
149
+
150
+ ---
151
+
152
+ ## Phase 3: Iteration Loop
153
+
154
+ **Objective**: Run iteration `k = 1..K`. Execute the canonical loop in [commands/iterate.md](commands/iterate.md):
155
+
156
+ 1. `aco.py select --iter <k>` -> register assignments via `evolve team assign` -> dispatch `N` `ant` workers in parallel (using host `invoke_subagent` / `swarm` with join, or Codex `spawn_agent` + `wait_agent`).
157
+ 2. When all `ANT-<k>-*` report (`evolve team report`), optionally dispatch `scorer` (`scoring.mode == "llm"`), then run `aco.py update --iter <k>` and `aco.py converged`.
158
+ 3. Branch: `converged == true` -> Phase 4; else loop `k + 1`.
159
+
160
+ ---
161
+
162
+ ## Phase 4: Converge + Synthesize
163
+
164
+ Execute [commands/converge.md](commands/converge.md): run `aco.py report` (`outputs/swarm-report.json`), dispatch `analyst` to produce `outputs/best-solution.md`, seal via `evolve run complete`, and run the interactive completion action.
165
+
166
+ ---
167
+
168
+ ## Error Handling
169
+
170
+ Follow the failure recovery tables in [init-swarm.md](commands/init-swarm.md), [iterate.md](commands/iterate.md), and [converge.md](commands/converge.md). On any unrecoverable error, halt and ask the user before mutating state; always join or cancel active subagents before returning.