@kontourai/flow-agents 0.1.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 (418) hide show
  1. package/.githooks/pre-push +11 -0
  2. package/.github/workflows/ci.yml +210 -0
  3. package/.github/workflows/docs-pages.yml +52 -0
  4. package/.github/workflows/publish-npm.yml +104 -0
  5. package/AGENTS.md +26 -0
  6. package/CHANGELOG.md +66 -0
  7. package/CODE_OF_CONDUCT.md +25 -0
  8. package/CONTEXT.md +300 -0
  9. package/CONTRIBUTING.md +44 -0
  10. package/LICENSE +201 -0
  11. package/README.md +129 -0
  12. package/SECURITY.md +33 -0
  13. package/agent-cards/dev.json +19 -0
  14. package/agents/dev.json +127 -0
  15. package/agents/tool-code-reviewer.json +61 -0
  16. package/agents/tool-dependencies-updater.json +118 -0
  17. package/agents/tool-explore-config.json +92 -0
  18. package/agents/tool-explore-deps.json +92 -0
  19. package/agents/tool-explore-entry.json +92 -0
  20. package/agents/tool-explore-patterns.json +92 -0
  21. package/agents/tool-explore-structure.json +92 -0
  22. package/agents/tool-explore-tests.json +92 -0
  23. package/agents/tool-planner.json +57 -0
  24. package/agents/tool-playwright.json +145 -0
  25. package/agents/tool-security-reviewer.json +56 -0
  26. package/agents/tool-verifier.json +61 -0
  27. package/agents/tool-worker.json +58 -0
  28. package/build/src/cli/console-learning-projection.js +123 -0
  29. package/build/src/cli/docs-preview.js +39 -0
  30. package/build/src/cli/effective-backlog-settings.js +102 -0
  31. package/build/src/cli/export-bookmarks.js +38 -0
  32. package/build/src/cli/fixture-retirement-audit.js +140 -0
  33. package/build/src/cli/flow-kit.js +138 -0
  34. package/build/src/cli/import-bookmarks.js +50 -0
  35. package/build/src/cli/init.js +239 -0
  36. package/build/src/cli/instinct-cli.js +93 -0
  37. package/build/src/cli/promote-workflow-artifact.js +63 -0
  38. package/build/src/cli/publish-change-helper.js +154 -0
  39. package/build/src/cli/pull-work-provider.js +469 -0
  40. package/build/src/cli/runtime-adapter.js +23 -0
  41. package/build/src/cli/telemetry-doctor.js +221 -0
  42. package/build/src/cli/usage-feedback.js +443 -0
  43. package/build/src/cli/validate-hook-influence.js +152 -0
  44. package/build/src/cli/validate-source-tree.js +31 -0
  45. package/build/src/cli/validate-workflow-artifacts.js +486 -0
  46. package/build/src/cli/veritas-governance.js +262 -0
  47. package/build/src/cli/workflow-artifact-cleanup-audit.js +272 -0
  48. package/build/src/cli/workflow-sidecar.js +816 -0
  49. package/build/src/cli.js +89 -0
  50. package/build/src/flow-kit/validate.js +75 -0
  51. package/build/src/lib/args.js +45 -0
  52. package/build/src/lib/fs.js +62 -0
  53. package/build/src/lib/workflow-learning-projection.js +334 -0
  54. package/build/src/runtime-adapters.js +146 -0
  55. package/build/src/tools/build-universal-bundles.js +397 -0
  56. package/build/src/tools/common.js +56 -0
  57. package/build/src/tools/filter-installed-packs.js +132 -0
  58. package/build/src/tools/generate-context-map.js +198 -0
  59. package/build/src/tools/validate-package.js +64 -0
  60. package/build/src/tools/validate-source-tree.js +622 -0
  61. package/console.telemetry.json +176 -0
  62. package/context/base-rules.md +17 -0
  63. package/context/code-review-standards.md +62 -0
  64. package/context/coding-standards.md +42 -0
  65. package/context/common/orchestrators.md +12 -0
  66. package/context/common/subagents.md +28 -0
  67. package/context/contracts/artifact-contract.md +182 -0
  68. package/context/contracts/builder-kit-workflow-state-contract.md +319 -0
  69. package/context/contracts/delivery-contract.md +69 -0
  70. package/context/contracts/execution-contract.md +53 -0
  71. package/context/contracts/governance-adapter-contract.md +67 -0
  72. package/context/contracts/planning-contract.md +85 -0
  73. package/context/contracts/review-contract.md +104 -0
  74. package/context/contracts/sandbox-policy.md +52 -0
  75. package/context/contracts/verification-contract.md +134 -0
  76. package/context/contracts/work-item-contract.md +215 -0
  77. package/context/deferred/demo-mode.md +33 -0
  78. package/context/deferred/languages/go.md +31 -0
  79. package/context/deferred/languages/python.md +31 -0
  80. package/context/deferred/languages/typescript.md +34 -0
  81. package/context/deferred/parallelization.md +35 -0
  82. package/context/deferred/worktree-isolation.md +24 -0
  83. package/context/development-workflow.md +50 -0
  84. package/context/scripts/context-budget/budget-scan.sh +166 -0
  85. package/context/scripts/detect-tools.sh +3 -0
  86. package/context/scripts/discover-agents.sh +28 -0
  87. package/context/scripts/git-status.sh +49 -0
  88. package/context/scripts/hooks/config-protection.js +79 -0
  89. package/context/scripts/hooks/desktop-notify.sh +39 -0
  90. package/context/scripts/hooks/governance-audit.sh +135 -0
  91. package/context/scripts/hooks/lib/audit-transport.sh +40 -0
  92. package/context/scripts/hooks/lib/hook-flags.js +49 -0
  93. package/context/scripts/hooks/lib/patterns.sh +57 -0
  94. package/context/scripts/hooks/lib/resolve-formatter.js +80 -0
  95. package/context/scripts/hooks/post-edit-accumulator.js +66 -0
  96. package/context/scripts/hooks/pre-commit-quality.js +194 -0
  97. package/context/scripts/hooks/quality-gate.js +93 -0
  98. package/context/scripts/hooks/report-only-guard.js +21 -0
  99. package/context/scripts/hooks/run-hook.js +136 -0
  100. package/context/scripts/hooks/stop-format-typecheck.js +141 -0
  101. package/context/scripts/hooks/stop-goal-fit.js +337 -0
  102. package/context/scripts/hooks/workflow-steering.js +250 -0
  103. package/context/scripts/telemetry/console-presets.sh +14 -0
  104. package/context/scripts/telemetry/install-console-config.sh +214 -0
  105. package/context/scripts/telemetry/lib/config.sh +85 -0
  106. package/context/scripts/telemetry/lib/enrich.sh +115 -0
  107. package/context/scripts/telemetry/lib/redact.sh +22 -0
  108. package/context/scripts/telemetry/lib/session.sh +63 -0
  109. package/context/scripts/telemetry/lib/transport.sh +183 -0
  110. package/context/scripts/telemetry/lib/usage.sh +29 -0
  111. package/context/scripts/telemetry/sync-agents.sh +173 -0
  112. package/context/scripts/telemetry/telemetry.conf +23 -0
  113. package/context/scripts/telemetry/telemetry.sh +387 -0
  114. package/context/scripts/validate-package.sh +89 -0
  115. package/context/settings/backlog-provider-settings.json +54 -0
  116. package/context/templates/core/identity.md +26 -0
  117. package/context/templates/core/user.md +15 -0
  118. package/docs/_config.yml +15 -0
  119. package/docs/_layouts/default.html +87 -0
  120. package/docs/adr/0001-flow-agents-consumes-flow.md +77 -0
  121. package/docs/adr/0002-flow-kits-as-extension-unit.md +13 -0
  122. package/docs/adr/0003-flow-agents-coordinates-kits-and-adapters.md +13 -0
  123. package/docs/adr/0004-gates-expect-surface-claims.md +15 -0
  124. package/docs/adr/0005-kubernetes-inspired-resource-contracts.md +48 -0
  125. package/docs/adr/0006-typescript-first-source-policy.md +98 -0
  126. package/docs/agent-system-guidebook.md +391 -0
  127. package/docs/agent-usage-feedback-loop.md +351 -0
  128. package/docs/assets/favicon.svg +13 -0
  129. package/docs/assets/og-image.png +0 -0
  130. package/docs/assets/site.css +774 -0
  131. package/docs/assets/site.js +139 -0
  132. package/docs/configurable-workflow-routing.md +174 -0
  133. package/docs/context-map.md +145 -0
  134. package/docs/developer-architecture.md +145 -0
  135. package/docs/developer-hook-setup.md +61 -0
  136. package/docs/fixture-ownership.md +44 -0
  137. package/docs/flow-kit-repository-contract.md +180 -0
  138. package/docs/index.md +129 -0
  139. package/docs/kontour-resource-contract.md +358 -0
  140. package/docs/migrations.md +64 -0
  141. package/docs/north-star.md +322 -0
  142. package/docs/operating-layers.md +110 -0
  143. package/docs/repository-structure.md +132 -0
  144. package/docs/sandbox-policy.md +56 -0
  145. package/docs/skills-map.md +203 -0
  146. package/docs/standards-register.md +96 -0
  147. package/docs/veritas-integration.md +165 -0
  148. package/docs/work-item-adapters.md +72 -0
  149. package/docs/workflow-artifact-lifecycle.md +141 -0
  150. package/docs/workflow-eval-strategy.md +295 -0
  151. package/docs/workflow-shared-contracts.md +51 -0
  152. package/docs/workflow-usage-guide.md +443 -0
  153. package/evals/ARCHITECTURE.md +143 -0
  154. package/evals/CONVENTIONS.md +58 -0
  155. package/evals/README.md +128 -0
  156. package/evals/acceptance/run.sh +29 -0
  157. package/evals/acceptance/test_claude_harness.sh +242 -0
  158. package/evals/acceptance/test_codex_harness.sh +108 -0
  159. package/evals/acceptance/test_kiro_harness.sh +128 -0
  160. package/evals/cases/dev/404.html +97 -0
  161. package/evals/cases/dev/code-review.yaml +44 -0
  162. package/evals/cases/dev/dashboard.html +300 -0
  163. package/evals/cases/dev/deliver.yaml +66 -0
  164. package/evals/cases/dev/dependency-update.yaml +16 -0
  165. package/evals/cases/dev/explore.yaml +20 -0
  166. package/evals/cases/dev/index.html +370 -0
  167. package/evals/cases/dev/package-lock.json +28 -0
  168. package/evals/cases/dev/package.json +16 -0
  169. package/evals/cases/dev/plan-work.yaml +20 -0
  170. package/evals/cases/dev/promptfooconfig.yaml +666 -0
  171. package/evals/cases/dev/search-first.yaml +20 -0
  172. package/evals/cases/dev/tdd-workflow.yaml +48 -0
  173. package/evals/cases/dev/verify-work.yaml +44 -0
  174. package/evals/cases/dev/workflow.yaml +34 -0
  175. package/evals/ci/run-baseline.sh +283 -0
  176. package/evals/fixtures/backlog-provider-settings/global-default.json +44 -0
  177. package/evals/fixtures/backlog-provider-settings/project-override.json +53 -0
  178. package/evals/fixtures/builder-kit-workflow-state/baseline-freshness-resolution-hint.json +139 -0
  179. package/evals/fixtures/builder-kit-workflow-state/direct-primitive-stop.json +59 -0
  180. package/evals/fixtures/builder-kit-workflow-state/empty-board-route-shape.json +55 -0
  181. package/evals/fixtures/builder-kit-workflow-state/happy-path.json +71 -0
  182. package/evals/fixtures/builder-kit-workflow-state/mid-work-resume.json +80 -0
  183. package/evals/fixtures/builder-kit-workflow-state/missing-prestep-recovery.json +65 -0
  184. package/evals/fixtures/builder-kit-workflow-state/product-build-chaining.json +60 -0
  185. package/evals/fixtures/builder-kit-workflow-state/stale-continuation-requires-new-probe.json +57 -0
  186. package/evals/fixtures/console-learning-projection/artifacts/console-learning-correction/learning.json +50 -0
  187. package/evals/fixtures/console-learning-projection/artifacts/console-learning-open-route/learning.json +41 -0
  188. package/evals/fixtures/flow-kit-repository/invalid-absolute-path/kit.json +8 -0
  189. package/evals/fixtures/flow-kit-repository/invalid-asset-section/flows/review.flow.json +6 -0
  190. package/evals/fixtures/flow-kit-repository/invalid-asset-section/kit.json +11 -0
  191. package/evals/fixtures/flow-kit-repository/invalid-duplicate-flow/flows/review.flow.json +6 -0
  192. package/evals/fixtures/flow-kit-repository/invalid-duplicate-flow/kit.json +9 -0
  193. package/evals/fixtures/flow-kit-repository/invalid-id/flows/review.flow.json +6 -0
  194. package/evals/fixtures/flow-kit-repository/invalid-id/kit.json +8 -0
  195. package/evals/fixtures/flow-kit-repository/invalid-malformed-json/kit.json +8 -0
  196. package/evals/fixtures/flow-kit-repository/invalid-missing-flow/kit.json +8 -0
  197. package/evals/fixtures/flow-kit-repository/invalid-missing-id/flows/review.flow.json +6 -0
  198. package/evals/fixtures/flow-kit-repository/invalid-missing-id/kit.json +7 -0
  199. package/evals/fixtures/flow-kit-repository/invalid-missing-schema-version/flows/review.flow.json +6 -0
  200. package/evals/fixtures/flow-kit-repository/invalid-missing-schema-version/kit.json +7 -0
  201. package/evals/fixtures/flow-kit-repository/invalid-name/flows/review.flow.json +6 -0
  202. package/evals/fixtures/flow-kit-repository/invalid-name/kit.json +8 -0
  203. package/evals/fixtures/flow-kit-repository/invalid-schema-version/flows/review.flow.json +6 -0
  204. package/evals/fixtures/flow-kit-repository/invalid-schema-version/kit.json +8 -0
  205. package/evals/fixtures/flow-kit-repository/invalid-traversal/kit.json +8 -0
  206. package/evals/fixtures/flow-kit-repository/mixed-runtime-kit/adapters/example.json +3 -0
  207. package/evals/fixtures/flow-kit-repository/mixed-runtime-kit/assets/example.txt +1 -0
  208. package/evals/fixtures/flow-kit-repository/mixed-runtime-kit/docs/README.md +3 -0
  209. package/evals/fixtures/flow-kit-repository/mixed-runtime-kit/flows/runtime.flow.json +26 -0
  210. package/evals/fixtures/flow-kit-repository/mixed-runtime-kit/kit-evals/example.json +3 -0
  211. package/evals/fixtures/flow-kit-repository/mixed-runtime-kit/kit-skills/mixed/SKILL.md +3 -0
  212. package/evals/fixtures/flow-kit-repository/mixed-runtime-kit/kit.json +44 -0
  213. package/evals/fixtures/flow-kit-repository/valid-local-kit/docs/README.md +3 -0
  214. package/evals/fixtures/flow-kit-repository/valid-local-kit/flows/review.flow.json +26 -0
  215. package/evals/fixtures/flow-kit-repository/valid-local-kit/kit.json +20 -0
  216. package/evals/fixtures/hook-influence/cases.json +336 -0
  217. package/evals/fixtures/pull-work-provider/github-issues.json +170 -0
  218. package/evals/fixtures/pull-work-wip-shepherding/global-wip-informs.json +43 -0
  219. package/evals/fixtures/pull-work-wip-shepherding/personal-wip-blocks.json +42 -0
  220. package/evals/fixtures/surface-trust/accepted-claim-trust-report.json +31 -0
  221. package/evals/fixtures/surface-trust/artifact-absent.json +19 -0
  222. package/evals/fixtures/surface-trust/integrity-mismatch-trust-report.json +32 -0
  223. package/evals/fixtures/surface-trust/missing-authority-trust-report.json +27 -0
  224. package/evals/fixtures/surface-trust/provider-absent.json +19 -0
  225. package/evals/fixtures/surface-trust/rejected-claim-trust-report.json +30 -0
  226. package/evals/fixtures/surface-trust/stale-claim-trust-snapshot.json +31 -0
  227. package/evals/fixtures/usage-feedback/sample-full.jsonl +11 -0
  228. package/evals/fixtures/usage-feedback/sample-outcomes.jsonl +1 -0
  229. package/evals/fixtures/veritas-governance-adapter/fake-veritas-pass.sh +18 -0
  230. package/evals/fixtures/veritas-governance-adapter/fake-veritas-secret-fail.sh +10 -0
  231. package/evals/fixtures/veritas-governance-adapter/fake-veritas-unconfigured.sh +4 -0
  232. package/evals/integration/test_bundle_install.sh +541 -0
  233. package/evals/integration/test_console_learning_projection.sh +192 -0
  234. package/evals/integration/test_context_map.sh +65 -0
  235. package/evals/integration/test_effective_backlog_settings.sh +58 -0
  236. package/evals/integration/test_fixture_retirement_audit.sh +58 -0
  237. package/evals/integration/test_flow_agents_statusline.sh +93 -0
  238. package/evals/integration/test_flow_kit_repository.sh +90 -0
  239. package/evals/integration/test_goal_fit_hook.sh +482 -0
  240. package/evals/integration/test_hook_category_behaviors.sh +190 -0
  241. package/evals/integration/test_hook_influence_cases.sh +69 -0
  242. package/evals/integration/test_local_flow_kit_install.sh +145 -0
  243. package/evals/integration/test_publish_change_helper.sh +176 -0
  244. package/evals/integration/test_pull_work_provider.sh +140 -0
  245. package/evals/integration/test_runtime_adapter_activation.sh +106 -0
  246. package/evals/integration/test_telemetry.sh +485 -0
  247. package/evals/integration/test_telemetry_doctor.sh +193 -0
  248. package/evals/integration/test_usage_feedback_dashboard.sh +169 -0
  249. package/evals/integration/test_usage_feedback_global.sh +117 -0
  250. package/evals/integration/test_usage_feedback_import.sh +227 -0
  251. package/evals/integration/test_usage_feedback_outcomes.sh +165 -0
  252. package/evals/integration/test_usage_feedback_report.sh +263 -0
  253. package/evals/integration/test_veritas_governance_adapter.sh +235 -0
  254. package/evals/integration/test_workflow_artifact_cleanup_audit.sh +287 -0
  255. package/evals/integration/test_workflow_artifacts.sh +1247 -0
  256. package/evals/integration/test_workflow_sidecar_writer.sh +2112 -0
  257. package/evals/integration/test_workflow_steering_hook.sh +337 -0
  258. package/evals/lib/assertions/delegated-to.js +40 -0
  259. package/evals/lib/assertions/max-tool-calls.js +15 -0
  260. package/evals/lib/assertions/no-write-tools.js +27 -0
  261. package/evals/lib/assertions/pass-at-k.js +39 -0
  262. package/evals/lib/assertions/telemetry-utils.js +105 -0
  263. package/evals/lib/assertions/tool-called.js +39 -0
  264. package/evals/lib/assertions/verify-after-fix.js +61 -0
  265. package/evals/lib/claude-judge.sh +40 -0
  266. package/evals/lib/claude-provider.sh +74 -0
  267. package/evals/lib/codex-judge.sh +39 -0
  268. package/evals/lib/codex-provider.sh +81 -0
  269. package/evals/lib/eval-dev.sh +5 -0
  270. package/evals/lib/eval-judge.sh +22 -0
  271. package/evals/lib/eval-provider.sh +26 -0
  272. package/evals/lib/eval-report.sh +73 -0
  273. package/evals/lib/kiro-dev.sh +4 -0
  274. package/evals/lib/kiro-judge.sh +17 -0
  275. package/evals/lib/kiro-provider.sh +62 -0
  276. package/evals/lib/node.sh +111 -0
  277. package/evals/promptfooconfig.yaml +70 -0
  278. package/evals/run.sh +309 -0
  279. package/evals/static/test_evidence_refs.sh +141 -0
  280. package/evals/static/test_package.sh +407 -0
  281. package/evals/static/test_repo_hooks.sh +68 -0
  282. package/evals/static/test_universal_bundles.sh +274 -0
  283. package/evals/static/test_workflow_skills.sh +1207 -0
  284. package/install.sh +64 -0
  285. package/integrations/veritas/flow-agents.adapter.json +138 -0
  286. package/integrations/veritas/flow-agents.authority-settings.json +26 -0
  287. package/integrations/veritas/flow-agents.repo-standards.json +82 -0
  288. package/kits/builder/flows/build.flow.json +218 -0
  289. package/kits/builder/flows/shape.flow.json +127 -0
  290. package/kits/builder/kit.json +19 -0
  291. package/kits/catalog.json +11 -0
  292. package/package.json +130 -0
  293. package/packaging/README.md +60 -0
  294. package/packaging/manifest.json +173 -0
  295. package/packaging/packs.json +69 -0
  296. package/powers/dependency-checker/POWER.md +20 -0
  297. package/powers/dependency-checker/mcp.json +20 -0
  298. package/powers/playwright/POWER.md +25 -0
  299. package/powers/playwright/mcp.json +12 -0
  300. package/prompts/code-audit.md +123 -0
  301. package/prompts/kcommit.md +88 -0
  302. package/schemas/backlog-provider-settings.schema.json +138 -0
  303. package/schemas/workflow-acceptance.schema.json +216 -0
  304. package/schemas/workflow-critique.schema.json +113 -0
  305. package/schemas/workflow-evidence.schema.json +357 -0
  306. package/schemas/workflow-handoff.schema.json +52 -0
  307. package/schemas/workflow-learning.schema.json +223 -0
  308. package/schemas/workflow-release.schema.json +172 -0
  309. package/schemas/workflow-state.schema.json +80 -0
  310. package/scripts/README.md +111 -0
  311. package/scripts/build-universal-bundles.js +3 -0
  312. package/scripts/check-content-boundary.cjs +99 -0
  313. package/scripts/context-budget/budget-scan.sh +166 -0
  314. package/scripts/detect-tools.sh +3 -0
  315. package/scripts/discover-agents.sh +28 -0
  316. package/scripts/effective-backlog-settings.js +2 -0
  317. package/scripts/filter-installed-packs.js +2 -0
  318. package/scripts/flow-kit.js +2 -0
  319. package/scripts/generate-context-map.js +2 -0
  320. package/scripts/git-status.sh +49 -0
  321. package/scripts/hooks/claude-hook-adapter.js +174 -0
  322. package/scripts/hooks/claude-telemetry-hook.js +115 -0
  323. package/scripts/hooks/codex-hook-adapter.js +176 -0
  324. package/scripts/hooks/codex-telemetry-hook.js +95 -0
  325. package/scripts/hooks/config-protection.js +79 -0
  326. package/scripts/hooks/desktop-notify.sh +39 -0
  327. package/scripts/hooks/governance-audit.sh +135 -0
  328. package/scripts/hooks/lib/audit-transport.sh +40 -0
  329. package/scripts/hooks/lib/hook-flags.js +49 -0
  330. package/scripts/hooks/lib/patterns.sh +57 -0
  331. package/scripts/hooks/lib/resolve-formatter.js +80 -0
  332. package/scripts/hooks/post-edit-accumulator.js +66 -0
  333. package/scripts/hooks/pre-commit-quality.js +194 -0
  334. package/scripts/hooks/quality-gate.js +93 -0
  335. package/scripts/hooks/report-only-guard.js +21 -0
  336. package/scripts/hooks/run-hook.js +136 -0
  337. package/scripts/hooks/stop-format-typecheck.js +141 -0
  338. package/scripts/hooks/stop-goal-fit.js +337 -0
  339. package/scripts/hooks/workflow-steering.js +250 -0
  340. package/scripts/install-codex-home.sh +106 -0
  341. package/scripts/package.json +3 -0
  342. package/scripts/promote-workflow-artifact.js +2 -0
  343. package/scripts/publish-change-helper.js +2 -0
  344. package/scripts/pull-work-provider.js +2 -0
  345. package/scripts/setup-repo-hooks.sh +8 -0
  346. package/scripts/statusline/flow-agents-statusline.js +157 -0
  347. package/scripts/telemetry/console-presets.sh +14 -0
  348. package/scripts/telemetry/install-console-config.sh +214 -0
  349. package/scripts/telemetry/lib/config.sh +85 -0
  350. package/scripts/telemetry/lib/enrich.sh +115 -0
  351. package/scripts/telemetry/lib/redact.sh +22 -0
  352. package/scripts/telemetry/lib/session.sh +63 -0
  353. package/scripts/telemetry/lib/transport.sh +183 -0
  354. package/scripts/telemetry/lib/usage.sh +29 -0
  355. package/scripts/telemetry/sync-agents.sh +173 -0
  356. package/scripts/telemetry/telemetry.conf +23 -0
  357. package/scripts/telemetry/telemetry.sh +387 -0
  358. package/scripts/usage-feedback.js +2 -0
  359. package/scripts/validate-hook-influence-cases.js +2 -0
  360. package/scripts/validate-package.sh +89 -0
  361. package/scripts/validate-source-tree.js +9 -0
  362. package/skills/agentic-engineering/SKILL.md +62 -0
  363. package/skills/browser-test/SKILL.md +51 -0
  364. package/skills/builder-shape/SKILL.md +76 -0
  365. package/skills/context-budget/SKILL.md +40 -0
  366. package/skills/deliver/SKILL.md +241 -0
  367. package/skills/dependency-update/SKILL.md +68 -0
  368. package/skills/design-probe/SKILL.md +107 -0
  369. package/skills/eval-rebuild/SKILL.md +39 -0
  370. package/skills/evidence-gate/SKILL.md +186 -0
  371. package/skills/execute-plan/SKILL.md +110 -0
  372. package/skills/explore/SKILL.md +137 -0
  373. package/skills/feedback-loop/SKILL.md +87 -0
  374. package/skills/fix-bug/SKILL.md +133 -0
  375. package/skills/frontend-design/SKILL.md +80 -0
  376. package/skills/github-cli/SKILL.md +63 -0
  377. package/skills/idea-to-backlog/SKILL.md +267 -0
  378. package/skills/knowledge-capture/SKILL.md +55 -0
  379. package/skills/learning-review/SKILL.md +115 -0
  380. package/skills/pickup-probe/SKILL.md +114 -0
  381. package/skills/plan-work/SKILL.md +176 -0
  382. package/skills/pull-work/SKILL.md +309 -0
  383. package/skills/release-readiness/SKILL.md +121 -0
  384. package/skills/review-work/SKILL.md +161 -0
  385. package/skills/search-first/SKILL.md +66 -0
  386. package/skills/tdd-workflow/SKILL.md +140 -0
  387. package/skills/verify-work/SKILL.md +109 -0
  388. package/src/cli/console-learning-projection.ts +140 -0
  389. package/src/cli/effective-backlog-settings.ts +99 -0
  390. package/src/cli/fixture-retirement-audit.ts +154 -0
  391. package/src/cli/flow-kit.ts +139 -0
  392. package/src/cli/init.ts +248 -0
  393. package/src/cli/promote-workflow-artifact.ts +64 -0
  394. package/src/cli/publish-change-helper.ts +143 -0
  395. package/src/cli/pull-work-provider.ts +481 -0
  396. package/src/cli/runtime-adapter.ts +24 -0
  397. package/src/cli/telemetry-doctor.ts +243 -0
  398. package/src/cli/usage-feedback.ts +418 -0
  399. package/src/cli/validate-hook-influence.ts +119 -0
  400. package/src/cli/validate-source-tree.ts +30 -0
  401. package/src/cli/validate-workflow-artifacts.ts +411 -0
  402. package/src/cli/veritas-governance.ts +322 -0
  403. package/src/cli/workflow-artifact-cleanup-audit.ts +281 -0
  404. package/src/cli/workflow-sidecar.ts +676 -0
  405. package/src/cli.ts +95 -0
  406. package/src/flow-kit/validate.ts +74 -0
  407. package/src/lib/args.ts +43 -0
  408. package/src/lib/fs.ts +62 -0
  409. package/src/lib/workflow-learning-projection.ts +491 -0
  410. package/src/runtime-adapters.ts +154 -0
  411. package/src/tools/build-universal-bundles.ts +366 -0
  412. package/src/tools/common.ts +61 -0
  413. package/src/tools/filter-installed-packs.ts +129 -0
  414. package/src/tools/generate-context-map.ts +199 -0
  415. package/src/tools/validate-package.ts +57 -0
  416. package/src/tools/validate-source-tree.ts +488 -0
  417. package/tsconfig.json +19 -0
  418. package/veritas.claims.json +6 -0
package/docs/_layouts/default.html ADDED
@@ -0,0 +1,87 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
6
+ <meta name="color-scheme" content="light dark">
7
+ <meta name="theme-color" content="#0a0e13" media="(prefers-color-scheme: dark)">
8
+ <meta name="theme-color" content="#f5f4ef" media="(prefers-color-scheme: light)">
9
+ <meta name="description" content="{{ page.description | default: site.description }}">
10
+ <meta property="og:type" content="website">
11
+ <meta property="og:site_name" content="Kontour Flow Agents">
12
+ <meta property="og:title" content="{{ page.title | default: site.title }}">
13
+ <meta property="og:description" content="{{ page.description | default: site.description }}">
14
+ <meta property="og:image" content="https://kontourai.github.io/flow-agents/assets/og-image.png">
15
+ <meta name="twitter:card" content="summary_large_image">
16
+ <meta name="twitter:title" content="{{ page.title | default: site.title }}">
17
+ <meta name="twitter:image" content="https://kontourai.github.io/flow-agents/assets/og-image.png">
18
+ <title>{{ page.title | default: site.title }}</title>
19
+ <link rel="preconnect" href="https://fonts.googleapis.com">
20
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
21
+ <link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;9..144,600&family=Hanken+Grotesk:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
22
+ <link rel="stylesheet" href="{{ '/assets/site.css' | relative_url }}">
23
+ <link rel="icon" href="{{ '/assets/favicon.svg' | relative_url }}" type="image/svg+xml">
24
+ </head>
25
+ <body>
26
+ <script>
27
+ (function () {
28
+ var stored = localStorage.getItem("flow-agents-docs-theme");
29
+ var preferred = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
30
+ document.documentElement.dataset.theme = stored || preferred;
31
+ })();
32
+ </script>
33
+ <div class="site-shell">
34
+ <aside class="site-rail" id="site-rail" aria-label="Documentation">
35
+ <a class="brand" href="{{ '/' | relative_url }}">
36
+ <span class="brand-mark" aria-hidden="true"></span>
37
+ <span>
38
+ <span class="brand-name">Kontour <strong>Flow Agents</strong></span>
39
+ <span class="brand-kicker">agent workflows · v0.1.0</span>
40
+ </span>
41
+ </a>
42
+ <nav class="doc-nav">
43
+ <a href="{{ '/' | relative_url }}">Overview</a>
44
+ <a href="{{ '/workflow-usage-guide.html' | relative_url }}">Workflow Guide</a>
45
+ <a href="{{ '/agent-system-guidebook.html' | relative_url }}">System Guidebook</a>
46
+ <a href="{{ '/skills-map.html' | relative_url }}">Workflow Map</a>
47
+ <a href="{{ '/north-star.html' | relative_url }}">North Star</a>
48
+ <a href="{{ '/sandbox-policy.html' | relative_url }}">Execution Safety</a>
49
+ <a href="{{ '/veritas-integration.html' | relative_url }}">Governance Evidence</a>
50
+ <a href="{{ '/workflow-eval-strategy.html' | relative_url }}">Eval Strategy</a>
51
+ <a href="{{ '/context-map.html' | relative_url }}">Developer Reference</a>
52
+ <a class="doc-nav-external" href="https://kontourai.github.io/flow/" rel="noopener">Kontour Flow ↗</a>
53
+ <a class="doc-nav-external" href="https://github.com/kontourai/flow-agents" rel="noopener">GitHub ↗</a>
54
+ </nav>
55
+ <button class="theme-toggle" type="button" data-theme-toggle aria-label="Toggle color theme">
56
+ <span class="theme-toggle__track" aria-hidden="true">
57
+ <span class="theme-toggle__thumb"></span>
58
+ </span>
59
+ <span data-theme-label>Theme</span>
60
+ </button>
61
+ </aside>
62
+ <div class="nav-backdrop" data-nav-backdrop hidden></div>
63
+ <main class="doc-main">
64
+ <div class="doc-topbar">
65
+ <button class="nav-toggle" type="button" data-nav-toggle aria-expanded="false" aria-controls="site-rail" aria-label="Toggle navigation">
66
+ <span></span><span></span><span></span>
67
+ </button>
68
+ <a class="mobile-brand" href="{{ '/' | relative_url }}">Kontour <strong>Flow Agents</strong></a>
69
+ <button class="theme-toggle theme-toggle--compact" type="button" data-theme-toggle aria-label="Toggle color theme">
70
+ <span class="theme-toggle__track" aria-hidden="true">
71
+ <span class="theme-toggle__thumb"></span>
72
+ </span>
73
+ <span data-theme-label>Theme</span>
74
+ </button>
75
+ </div>
76
+ <article class="doc-content">
77
+ {{ content }}
78
+ </article>
79
+ <footer class="site-footer">
80
+ <p><strong>Kontour AI</strong> shows the work behind AI. Flow Agents is the agent-facing layer, built on <a href="https://kontourai.github.io/flow/">Kontour Flow</a>.</p>
81
+ </footer>
82
+ </main>
83
+ </div>
84
+ <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
85
+ <script src="{{ '/assets/site.js' | relative_url }}" defer></script>
86
+ </body>
87
+ </html>
package/docs/adr/0001-flow-agents-consumes-flow.md ADDED
@@ -0,0 +1,77 @@
1
+ ---
2
+ title: ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement
3
+ ---
4
+
5
+ # ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement
6
+
7
+ Date: 2026-05-24
8
+
9
+ ## Status
10
+
11
+ Accepted
12
+
13
+ ## Context
14
+
15
+ Flow Agents has been accumulating workflow sidecars, hooks, gate checks, evidence records, runtime exports, skills, provider settings, and Console ideas. That made the product useful, but it also blurred product boundaries with Kontour Surface and Kontour Veritas.
16
+
17
+ Surface already owns portable product transparency: claims, evidence, policies, freshness, gaps, and trust snapshots. Veritas already owns repo and AI-agent governance: repo standards, requirements, evidence checks, change guidance, and merge readiness.
18
+
19
+ Generic workflow enforcement is broader than Flow Agents and narrower than Veritas. It needs a focused owner.
20
+
21
+ ## Decision
22
+
23
+ Flow Agents will consume Kontour Flow for generic workflow enforcement instead of owning the generic enforcement kernel.
24
+
25
+ Flow owns:
26
+
27
+ - Flow Definitions
28
+ - Flow Runs
29
+ - steps
30
+ - gates
31
+ - transitions
32
+ - gate evidence
33
+ - exceptions
34
+ - continuation
35
+ - Flow Reports
36
+
37
+ Flow Agents owns:
38
+
39
+ - work modes
40
+ - skills
41
+ - provider settings
42
+ - runtime adapters
43
+ - native harness hooks
44
+ - useful Flow-backed workflow packs
45
+ - Console views for agent users
46
+ - local-first setup and runtime exports
47
+
48
+ Veritas remains an optional development governance evidence provider for Flow-backed Build workflows.
49
+
50
+ ## Consequences
51
+
52
+ Positive:
53
+
54
+ - Flow Agents stays focused on agent-facing interoperability and seamless workflow enforcement.
55
+ - Flow can serve non-agent or future agent consumers without inheriting Flow Agents-specific runtime concerns.
56
+ - Veritas stays focused on repo/change governance rather than generic process state.
57
+ - Surface remains the shared transparency foundation underneath both Flow and Veritas.
58
+
59
+ Trade-offs:
60
+
61
+ - Flow Agents has to map existing sidecars into Flow concepts over time.
62
+ - There is one more Kontour product boundary to explain.
63
+ - Until Flow has a package, Flow Agents keeps its existing sidecar writer and hooks as the local implementation surface.
64
+
65
+ ## Alternatives Considered
66
+
67
+ ### Keep Workflow Enforcement In Flow Agents
68
+
69
+ Rejected because it would make Flow Agents responsible for both the agent-facing distribution and the generic process enforcement kernel.
70
+
71
+ ### Put Workflow Enforcement In Veritas
72
+
73
+ Rejected because Veritas should remain centered on repo standards and merge readiness.
74
+
75
+ ### Use Surface Directly
76
+
77
+ Rejected because Surface represents trust state but does not define process steps, gates, transitions, or continuation semantics.
package/docs/adr/0002-flow-kits-as-extension-unit.md ADDED
@@ -0,0 +1,13 @@
1
+ ---
2
+ title: ADR 0002: Flow Kits As The Extension Unit
3
+ ---
4
+
5
+ # ADR 0002: Flow Kits As The Extension Unit
6
+
7
+ Flow Agents will use **Flow Kit** as the product and implementation term for installable workflow bundles, replacing the older "pack" vocabulary. A Flow Kit may contain Flow Definitions, skills, adapters, provider contracts, docs, and evals; the Kit Catalog lists available kits and installable assets, but the workflow semantics live in kit-owned Flow Definition files. This avoids overloading packaging metadata with process semantics and gives custom workflow authoring a clearer product language.
8
+
9
+ **Status**: Accepted
10
+
11
+ **Considered Options**: Keeping "pack" was familiar from the current `packaging/packs.json`, but it was too generic and carried plugin-marketplace baggage. Keeping "pack" internally while using "kit" publicly was rejected because the repository is unpublished and a split vocabulary would make the migration harder to understand.
12
+
13
+ **Consequences**: Flow Agents will use `kits/catalog.json` as the Kit Catalog. The first real kit will live under `kits/builder/` with its own `kit.json` and Flow Definitions under `kits/builder/flows/`. The Builder Kit must be installable through the same compliance path as future external Flow Kit repositories.
package/docs/adr/0003-flow-agents-coordinates-kits-and-adapters.md ADDED
@@ -0,0 +1,13 @@
1
+ ---
2
+ title: ADR 0003: Flow Agents Coordinates Kits And Adapters
3
+ ---
4
+
5
+ # ADR 0003: Flow Agents Coordinates Kits And Adapters
6
+
7
+ Flow Agents will not own the builder, or knowledge workflows as core behavior. Those out-of-the-box behaviors will be extracted into normal Flow Kits that use the same manifest, Flow Definition, skill, doc, provider, and eval contracts as third-party kits. Flow Agents owns kit validation, installation, runtime adapter selection, provider wiring, status/control commands, and runtime-specific export; Runtime Adapters own target-specific integration for local agent runtimes and API/framework agents.
8
+
9
+ **Status**: Accepted
10
+
11
+ **Considered Options**: Keeping built-in workflows inside Flow Agents core would make the kit model less real and force custom users into a second-class extension path. Treating every adapter as built into Flow Agents would make local agent runtimes, LangGraph, Strands, CrewAI, VoltAgent, and future API frameworks all pay for each other's dependencies and release cadence. Separate adapter packages can come after the internal interface is proven, but the architecture should assume adapters are independently selectable.
12
+
13
+ **Consequences**: The Builder Kit is the first proof point and should be self-validated before Knowledge receives the same depth. Knowledge can remain a future kit target until the builder workflow proves the kit, adapter, and install contracts.
package/docs/adr/0004-gates-expect-surface-claims.md ADDED
@@ -0,0 +1,15 @@
1
+ ---
2
+ title: ADR 0004: Gates Expect Surface Claims
3
+ ---
4
+
5
+ # ADR 0004: Gates Expect Surface Claims
6
+
7
+ Flow-backed kits will model rich gate evidence as claim expectations rather than provider-specific requirements. A gate expectation can require `kind: "surface.claim"`, a Surface claim type such as `repo.policy_compliance`, accepted trust statuses such as `verified`, and whether the expectation blocks the transition; project or runtime config maps claim types to trusted Surface producers and authority traces. This lets the Builder Kit use repo governance, command checks, CI, human decisions, or future producers without naming a specific provider in the Flow Definition.
8
+
9
+ **Status**: Accepted
10
+
11
+ **Considered Options**: Provider-aware gate rules were rejected because they would make Flow Definitions know too much about individual tools. Plain evidence strings such as `tests` or `veritas` were rejected because they cannot represent claim type, accepted status, producer authority, transparency gaps, or project-level enforcement overrides cleanly.
12
+
13
+ **Consequences**: Trusted producer mappings belong upstream in Flow project configuration, not Flow Agents runtime configuration. Flow Agents can help author, install, and adapt that configuration for agent runtimes, but CI, framework agents, local CLIs, and humans should all evaluate gates against the same Flow-owned authority model.
14
+
15
+ **Initial Shape**: Gate expectations should use `expects` entries with `id`, `kind: "surface.claim"`, `required`, `claim.type`, optional `claim.subject`, `claim.accepted_statuses`, `description`, and optional `explore_hint`. The Builder Kit should use intuitive subject strings such as `flow-run`, `flow-step`, `work-item`, `change`, `pull-request`, `release`, `decision`, and `artifact`, while the schema remains open to other subject values.
package/docs/adr/0005-kubernetes-inspired-resource-contracts.md ADDED
@@ -0,0 +1,48 @@
1
+ ---
2
+ title: ADR 0005: Kubernetes-Inspired Kontour Resource Contracts
3
+ ---
4
+
5
+ # ADR 0005: Kubernetes-Inspired Kontour Resource Contracts
6
+
7
+ Date: 2026-05-27
8
+
9
+ ## Status
10
+
11
+ Accepted
12
+
13
+ ## Context
14
+
15
+ Kontour products need durable records that humans, agents, runtime adapters, provider integrations, CLI tools, CI systems, evals, and future control planes can all inspect without relying on hidden chat context. Kubernetes, Tekton, and Argo have converged on versioned resource shapes with metadata, desired state, observed status, and status conditions; that shape is familiar, toolable, and a good fit for workflow state. OpenTelemetry GenAI conventions are also emerging for agent observability, so Kontour products should not invent isolated telemetry concepts where compatible conventions already exist.
16
+
17
+ ## Decision
18
+
19
+ New durable, agent-facing, provider-facing, CLI-facing, cross-product, or user-authored Kontour contracts will use a Kubernetes-inspired Kontour Resource Contract shape by default: versioned resource identity, metadata, desired intent, observed status, and condition-style status summaries. Flow Agents is the first adopter, and current pre-public contracts in Flow, Surface, and Veritas should be audited for migration rather than grandfathered automatically.
20
+
21
+ Kontour Resource Contracts do not create a Kubernetes dependency; local files and provider-backed records remain first-class, and a Kubernetes operator is only a possible future adapter over the same contracts. Product namespaces should distinguish owners, such as `flow.kontourai.io/v1alpha1`, `flowagents.kontourai.io/v1alpha1`, `builder.flowagents.kontourai.io/v1alpha1`, `surface.kontourai.io/v1alpha1`, and `veritas.kontourai.io/v1alpha1`.
22
+
23
+ Products may keep product-native internal types when they are materially clearer, but exported durable artifacts should converge on Kontour Resource Contracts or document an explicit mapping and exception.
24
+
25
+ ## Consequences
26
+
27
+ Positive:
28
+
29
+ - Agents can reason about durable product state without bespoke parsing for every artifact.
30
+ - Runtime adapters, provider adapters, CLI tools, CI systems, evals, and the future Console can share one contract style.
31
+ - Active Workflow Runs can publish Selected Scope metadata for future overlap checks.
32
+ - Future Kubernetes operator support remains possible without making Kubernetes the default runtime.
33
+
34
+ Trade-offs:
35
+
36
+ - Kontour products must avoid turning every concept into a resource.
37
+ - Status must stay disciplined: intent belongs in the desired-state portion of a contract, observed facts belong in status, and evidence records remain separately inspectable.
38
+ - Existing pre-public sidecars and exported artifacts need migration plans or documented exceptions instead of accidental grandfathering.
39
+
40
+ ## Alternatives Considered
41
+
42
+ ### Ad Hoc JSON Sidecars
43
+
44
+ Rejected as the long-term direction because ad hoc sidecars are easy to create but hard for adapters, evals, providers, and users to understand consistently.
45
+
46
+ ### Depend Directly On Kubernetes CRDs
47
+
48
+ Rejected because Flow Agents must remain local-first and runtime-neutral. Kubernetes may become an adapter target, not the substrate required to use Flow Agents.
package/docs/adr/0006-typescript-first-source-policy.md ADDED
@@ -0,0 +1,98 @@
1
+ ---
2
+ title: ADR 0006: TypeScript-First Source Policy
3
+ ---
4
+
5
+ # ADR 0006: TypeScript-First Source Policy
6
+
7
+ Date: 2026-05-31
8
+
9
+ ## Status
10
+
11
+ Accepted
12
+
13
+ ## Context
14
+
15
+ Kontour repositories increasingly share source, contracts, adapters, workflow tooling, and evidence paths. Flow Agents currently includes JavaScript hook/runtime helpers and Python tooling; Flow and Veritas have JavaScript or MJS runtime surfaces; Surface is already TypeScript-first; and `kontourai.io` is an Astro site with TypeScript-enabled tooling plus JavaScript and MJS site/config files.
16
+
17
+ Without a cross-repo policy, new work can accidentally deepen language fragmentation or turn every existing JavaScript, MJS, or Python file into an implicit permanent exception. The policy needs to set direction without bundling source migration, CI rewrites, or sibling repository edits into this ADR.
18
+
19
+ The refreshed local inventory below was collected on 2026-05-31 from sibling checkouts under `~/code/kontourai/`. It is a branch-local snapshot, not a claim about all remote branches.
20
+
21
+ Inventory command:
22
+
23
+ ```bash
24
+ rg --files -g '!node_modules' -g '!dist' -g '!_site' -g '!coverage' -g '!evals/results' |
25
+ rg '\.(ts|tsx|js|jsx|mjs|cjs|py|d\.ts)$'
26
+ ```
27
+
28
+ | Repo | Local branch/status caveat | Snapshot summary | Validation/typecheck surface observed | Follow-up |
29
+ | --- | --- | --- | --- | --- |
30
+ | `flow` | `flow-definition-transition-guard-impl...origin/flow-definition-transition-guard-impl`; untracked local runtime artifacts | 0 TS/TSX, 2 JS, 1 MJS, 0 Python. Small JS/MJS runtime and schema-check surface. | `check:schemas` and `test`; no TypeScript typecheck yet. | Track migration in [Flow #20](https://github.com/kontourai/flow/issues/20). |
31
+ | `flow-agents` | `main...origin/main` | 0 TS/TSX, 34 JS, 34 Python. Mixed hooks, eval helpers, runtime scripts, docs asset JS, and Python tooling. | Static/eval scripts exist outside `package.json`; no TypeScript typecheck yet. | Track TypeScript migration planning in [Flow Agents #65](https://github.com/kontourai/flow-agents/issues/65) and Python removal policy/migration in [Flow Agents #67](https://github.com/kontourai/flow-agents/issues/67). |
32
+ | `surface` | `main...origin/main` | 52 TS files, 0 JS, 2 MJS, 0 Python. Product and test source are TypeScript-first; MJS is limited to build/bin scripts. | `typecheck`, `build`, `test`, and `verify` scripts are present. | No new migration issue needed; refreshed inventory supports Surface as already TypeScript-first. |
33
+ | `veritas` | `main...origin/main [ahead 4, behind 4]` | 0 TS/TSX, 1 `.d.ts`, 80 MJS, 0 Python. MJS product/runtime surface with a typed plugin interface declaration. | `verify`, `test`, coverage, vocabulary, redaction, and Veritas readiness scripts; no TypeScript typecheck yet. | Track staged migration in [Veritas #21](https://github.com/kontourai/veritas/issues/21). |
34
+ | `kontourai.io` | `codex/survey-extraction-readiness-audit...origin/codex/survey-extraction-readiness-audit`; untracked local runtime artifacts | 0 TS/TSX, 1 `.d.ts`, 1 JS, 4 MJS, 0 Python. Astro/TypeScript-enabled site with environment typing, JS worker asset, MJS config/scripts/tests. | `build`, `validate`, and rendered-site test scripts are present; Astro build provides the TypeScript-enabled site validation path. | No new issue currently needed; remaining JS/MJS files fit accepted site/config/test/asset exceptions unless future product source expands in JS. |
35
+
36
+ The existing follow-up issues were checked with GitHub CLI on 2026-05-31 and were open:
37
+
38
+ - [Flow #20: Migrate Flow source toward TypeScript](https://github.com/kontourai/flow/issues/20)
39
+ - [Flow Agents #65: Plan Flow Agents TypeScript migration for runtime and hook code](https://github.com/kontourai/flow-agents/issues/65)
40
+ - [Flow Agents #67: Remove Python from Flow Agents source, tooling, and docs](https://github.com/kontourai/flow-agents/issues/67)
41
+ - [Veritas #21: Plan staged TypeScript migration for Veritas source](https://github.com/kontourai/veritas/issues/21)
42
+
43
+ ## Decision
44
+
45
+ Kontour product and runtime source should be TypeScript-first across Flow, Flow Agents, Surface, Veritas, and `kontourai.io`.
46
+
47
+ New durable product code, runtime adapters, package APIs, CLI behavior, workflow orchestration, hooks, provider bridges, and shared contracts should be authored in TypeScript by default when they live in repositories that are TypeScript-enabled or are being migrated toward TypeScript. Existing JavaScript, MJS, and Python source is not grandfathered as permanent direction; repositories with nontrivial runtime source outside TypeScript should track staged migration through repo-specific issues.
48
+
49
+ This ADR does not require immediate source migration, package manifest changes, `tsconfig` changes, build script changes, or CI workflow edits. It defines the policy direction and the boundary for accepted exceptions.
50
+
51
+ ### CI And Validation Expectations
52
+
53
+ TypeScript-enabled repositories should expose a typecheck or build validation that proves the authored TypeScript surface compiles. CI should run that validation before code is treated as releasable.
54
+
55
+ Repositories that are not yet TypeScript-enabled should first link a migration plan or issue before requiring a TypeScript typecheck in CI. During migration, existing test, schema, static, or verify commands remain valid evidence, but new TypeScript source should include an appropriate typecheck/build path before it becomes the normal implementation surface.
56
+
57
+ For `kontourai.io`, Astro build and site validation are the current TypeScript-enabled validation path. A separate migration issue is not needed for the current snapshot because the remaining JS/MJS files are config, script, test, or generated/site asset surfaces rather than a broad non-TypeScript product source layer.
58
+
59
+ ### Allowed JavaScript And MJS Exceptions
60
+
61
+ JavaScript, MJS, CJS, or plain JS assets are acceptable when they are deliberately limited to one of these categories:
62
+
63
+ - package and tool configuration where the tool expects JavaScript or MJS, such as Astro, Playwright, build-page scripts, or package bin launchers
64
+ - generated docs or site assets, including browser-delivered files where TypeScript compilation would add no useful ownership boundary
65
+ - shell-adjacent launchers or thin entrypoints where portability, startup behavior, shebang support, or package-manager conventions materially matter
66
+ - fixtures, examples, and tests where local repository convention already uses JS/MJS and the files are not the primary product implementation surface
67
+ - historical archived, vendored, or generated artifacts that are not edited as active source
68
+
69
+ Exceptions should stay narrow. A file matching an exception category can remain JS/MJS, but expanding product/runtime behavior in JS/MJS should be treated as a deliberate exception or routed into the repository's TypeScript migration plan.
70
+
71
+ ## Consequences
72
+
73
+ Positive:
74
+
75
+ - New cross-repo implementation work has a clear default language.
76
+ - Surface remains the reference TypeScript-first repository instead of being blocked by other repositories' migrations.
77
+ - Flow, Flow Agents, and Veritas can migrate deliberately through linked issues rather than ad hoc rewrites.
78
+ - CI expectations are explicit without forcing build-system changes into this policy slice.
79
+
80
+ Trade-offs:
81
+
82
+ - The policy depends on branch-local inventory snapshots and must be refreshed when migration work materially changes a repository.
83
+ - Existing JavaScript, MJS, and Python files still require staged migration decisions; this ADR does not remove them.
84
+ - Exception categories need discipline so config/tooling allowances do not become a broad runtime-source escape hatch.
85
+
86
+ ## Alternatives Considered
87
+
88
+ ### Allow Each Repository To Choose Independently
89
+
90
+ Rejected because shared contracts, adapters, and workflow tooling already cross repository boundaries. Independent language policy would preserve avoidable friction for maintainers and agents.
91
+
92
+ ### Require Immediate TypeScript Migration Everywhere
93
+
94
+ Rejected because Flow, Flow Agents, and Veritas need staged migration plans, validation paths, and reviewable changes. This ADR sets direction and links follow-up issues without bundling broad source rewrites into a docs policy change.
95
+
96
+ ### Ban All JavaScript And MJS
97
+
98
+ Rejected because package configuration, tool scripts, site assets, thin launchers, fixtures, and generated or historical artifacts often have practical reasons to remain JS/MJS. The policy narrows those exceptions instead of pretending they do not exist.