@causyne/agent 0.0.0-stage → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (274) hide show
  1. package/LICENSE +102 -0
  2. package/README.md +31 -2
  3. package/SECURITY.md +24 -0
  4. package/bin/causyne.js +13 -0
  5. package/docs/ARCHITECTURE.md +63 -0
  6. package/docs/PROVENANCE.md +29 -0
  7. package/docs/SECURITY_REVIEW.md +89 -0
  8. package/docs/THIRD_PARTY_NOTICES.md +49 -0
  9. package/native-skills/ai-engineering/context-window-management/SKILL.md +43 -0
  10. package/native-skills/ai-engineering/llm-evaluation/SKILL.md +46 -0
  11. package/native-skills/ai-engineering/model-cost-and-latency/SKILL.md +46 -0
  12. package/native-skills/ai-engineering/prompt-construction/SKILL.md +42 -0
  13. package/native-skills/ai-engineering/retrieval-augmented-generation/SKILL.md +42 -0
  14. package/native-skills/ai-engineering/structured-output-and-schemas/SKILL.md +45 -0
  15. package/native-skills/ai-engineering/tool-calling-agents/SKILL.md +43 -0
  16. package/native-skills/android/app-performance-profiling/SKILL.md +42 -0
  17. package/native-skills/android/background-work-scheduling/SKILL.md +47 -0
  18. package/native-skills/android/compose-state-and-recomposition/SKILL.md +43 -0
  19. package/native-skills/android/gradle-build-configuration/SKILL.md +41 -0
  20. package/native-skills/android/lifecycle-and-leaks/SKILL.md +46 -0
  21. package/native-skills/android/play-store-release/SKILL.md +43 -0
  22. package/native-skills/android/room-and-persistence/SKILL.md +40 -0
  23. package/native-skills/backend/authentication-and-sessions/SKILL.md +45 -0
  24. package/native-skills/backend/background-jobs-and-queues/SKILL.md +42 -0
  25. package/native-skills/backend/caching-strategy/SKILL.md +44 -0
  26. package/native-skills/backend/graceful-shutdown/SKILL.md +42 -0
  27. package/native-skills/backend/rate-limiting-and-quotas/SKILL.md +40 -0
  28. package/native-skills/backend/rest-api-design/SKILL.md +40 -0
  29. package/native-skills/backend/webhook-delivery-and-receipt/SKILL.md +43 -0
  30. package/native-skills/cloud/cost-optimisation/SKILL.md +46 -0
  31. package/native-skills/cloud/iam-least-privilege/SKILL.md +43 -0
  32. package/native-skills/cloud/infrastructure-as-code/SKILL.md +43 -0
  33. package/native-skills/cloud/multi-region-and-failover/SKILL.md +43 -0
  34. package/native-skills/cloud/serverless-patterns/SKILL.md +47 -0
  35. package/native-skills/data/data-quality-monitoring/SKILL.md +51 -0
  36. package/native-skills/data/etl-pipeline-reliability/SKILL.md +43 -0
  37. package/native-skills/data/exploratory-analysis/SKILL.md +43 -0
  38. package/native-skills/data/metric-definition/SKILL.md +42 -0
  39. package/native-skills/data/notebook-to-production/SKILL.md +43 -0
  40. package/native-skills/database/backup-and-recovery/SKILL.md +43 -0
  41. package/native-skills/database/connection-pooling/SKILL.md +42 -0
  42. package/native-skills/database/data-integrity-and-constraints/SKILL.md +42 -0
  43. package/native-skills/database/query-optimisation/SKILL.md +38 -0
  44. package/native-skills/database/safe-migrations/SKILL.md +47 -0
  45. package/native-skills/database/schema-design/SKILL.md +38 -0
  46. package/native-skills/database/transactions-and-isolation/SKILL.md +41 -0
  47. package/native-skills/design/colour-system-construction/SKILL.md +38 -0
  48. package/native-skills/design/design-direction-brief/SKILL.md +41 -0
  49. package/native-skills/design/motion-and-transitions/SKILL.md +38 -0
  50. package/native-skills/design/responsive-strategy/SKILL.md +39 -0
  51. package/native-skills/design/spacing-and-rhythm/SKILL.md +38 -0
  52. package/native-skills/design/type-scale-and-hierarchy/SKILL.md +39 -0
  53. package/native-skills/design/visual-qa-loop/SKILL.md +42 -0
  54. package/native-skills/devops/docker-multi-stage-builds/SKILL.md +60 -0
  55. package/native-skills/devops/github-actions-ci/SKILL.md +60 -0
  56. package/native-skills/devops/incident-triage/SKILL.md +38 -0
  57. package/native-skills/devops/kubernetes-deployment-hardening/SKILL.md +64 -0
  58. package/native-skills/devops/observability-baseline/SKILL.md +38 -0
  59. package/native-skills/devops/secret-management/SKILL.md +40 -0
  60. package/native-skills/devops/terraform-state-and-modules/SKILL.md +36 -0
  61. package/native-skills/devops/zero-downtime-deploys/SKILL.md +40 -0
  62. package/native-skills/git/bisect-regression-hunt/SKILL.md +43 -0
  63. package/native-skills/git/branch-strategy/SKILL.md +39 -0
  64. package/native-skills/git/commit-hygiene/SKILL.md +41 -0
  65. package/native-skills/git/history-recovery/SKILL.md +44 -0
  66. package/native-skills/git/large-repository-surgery/SKILL.md +46 -0
  67. package/native-skills/git/merge-conflict-resolution/SKILL.md +42 -0
  68. package/native-skills/media/cinematic-3d-shot/SKILL.md +104 -0
  69. package/native-skills/mobile/app-startup-optimisation/SKILL.md +41 -0
  70. package/native-skills/mobile/cross-platform-tradeoffs/SKILL.md +42 -0
  71. package/native-skills/mobile/deep-linking/SKILL.md +39 -0
  72. package/native-skills/mobile/mobile-storage-security/SKILL.md +45 -0
  73. package/native-skills/mobile/offline-first-sync/SKILL.md +42 -0
  74. package/native-skills/mobile/push-notifications/SKILL.md +38 -0
  75. package/native-skills/performance/algorithmic-complexity/SKILL.md +43 -0
  76. package/native-skills/performance/concurrency-and-parallelism/SKILL.md +42 -0
  77. package/native-skills/performance/load-testing/SKILL.md +42 -0
  78. package/native-skills/performance/memory-and-leak-hunting/SKILL.md +41 -0
  79. package/native-skills/performance/network-and-payload-efficiency/SKILL.md +42 -0
  80. package/native-skills/performance/profiling-methodology/SKILL.md +46 -0
  81. package/native-skills/python/async-correctness/SKILL.md +40 -0
  82. package/native-skills/python/cli-tool-construction/SKILL.md +44 -0
  83. package/native-skills/python/data-processing-pipelines/SKILL.md +38 -0
  84. package/native-skills/python/environment-isolation/SKILL.md +41 -0
  85. package/native-skills/python/packaging-and-distribution/SKILL.md +56 -0
  86. package/native-skills/python/pytest-suite-design/SKILL.md +39 -0
  87. package/native-skills/python/type-hints-and-static-checking/SKILL.md +42 -0
  88. package/native-skills/security/authorization-model/SKILL.md +42 -0
  89. package/native-skills/security/crypto-usage/SKILL.md +48 -0
  90. package/native-skills/security/dependency-supply-chain/SKILL.md +42 -0
  91. package/native-skills/security/input-validation-and-injection/SKILL.md +44 -0
  92. package/native-skills/security/secure-file-uploads/SKILL.md +46 -0
  93. package/native-skills/security/security-headers-and-csp/SKILL.md +44 -0
  94. package/native-skills/security/threat-modelling/SKILL.md +46 -0
  95. package/native-skills/testing/end-to-end-test-stability/SKILL.md +42 -0
  96. package/native-skills/testing/property-based-testing/SKILL.md +46 -0
  97. package/native-skills/testing/regression-test-from-a-bug/SKILL.md +41 -0
  98. package/native-skills/testing/snapshot-and-visual-regression/SKILL.md +42 -0
  99. package/native-skills/testing/test-doubles-and-mocking/SKILL.md +43 -0
  100. package/native-skills/testing/test-strategy-and-pyramid/SKILL.md +39 -0
  101. package/native-skills/testing/writing-good-assertions/SKILL.md +42 -0
  102. package/native-skills/web/accessible-components/SKILL.md +45 -0
  103. package/native-skills/web/api-client-resilience/SKILL.md +39 -0
  104. package/native-skills/web/bundle-size-reduction/SKILL.md +38 -0
  105. package/native-skills/web/core-web-vitals/SKILL.md +40 -0
  106. package/native-skills/web/css-layout-systems/SKILL.md +41 -0
  107. package/native-skills/web/form-validation-ux/SKILL.md +39 -0
  108. package/native-skills/web/react-state-architecture/SKILL.md +41 -0
  109. package/native-skills/web/ssr-hydration-correctness/SKILL.md +45 -0
  110. package/package.json +68 -4
  111. package/src/agentLoop.js +2458 -0
  112. package/src/appChannel.js +109 -0
  113. package/src/approvalGrants.js +66 -0
  114. package/src/auditLog.js +52 -0
  115. package/src/autoUpdate.js +12 -0
  116. package/src/capabilities.js +36 -0
  117. package/src/checkpoints.js +1199 -0
  118. package/src/cliMode.js +638 -0
  119. package/src/commands.js +805 -0
  120. package/src/compiledSkills.js +540 -0
  121. package/src/config.js +130 -0
  122. package/src/contextManager.js +498 -0
  123. package/src/cortex/autoCondenser.js +192 -0
  124. package/src/cortex/provisioner.js +27 -0
  125. package/src/cortex/vectorDb.js +447 -0
  126. package/src/designPalettes.js +99 -0
  127. package/src/devMode.js +6 -0
  128. package/src/embodimentSession.js +180 -0
  129. package/src/entrypoint.js +194 -0
  130. package/src/execSafe.js +21 -0
  131. package/src/gitSnapshot.js +378 -0
  132. package/src/mcp/jsonRpc.js +165 -0
  133. package/src/mcp/mcpClient.js +136 -0
  134. package/src/mcp/mcpRegistry.js +207 -0
  135. package/src/memory.js +62 -0
  136. package/src/memoryManager.js +124 -0
  137. package/src/modelCatalogue.js +132 -0
  138. package/src/modelIds.js +42 -0
  139. package/src/modelRouter.js +145 -0
  140. package/src/outputStore.js +246 -0
  141. package/src/perception.js +124 -0
  142. package/src/planCache.js +437 -0
  143. package/src/procSignal.js +32 -0
  144. package/src/providers/anthropic.js +408 -0
  145. package/src/providers/base.js +328 -0
  146. package/src/providers/dashscope-byok.js +86 -0
  147. package/src/providers/deepseek.js +80 -0
  148. package/src/providers/factory.js +37 -0
  149. package/src/providers/gemini.js +346 -0
  150. package/src/providers/moonshot.js +73 -0
  151. package/src/providers/muse.js +169 -0
  152. package/src/providers/ollama.js +104 -0
  153. package/src/providers/openai-compatible.js +84 -0
  154. package/src/providers/openai.js +20 -0
  155. package/src/providers/qwen-byok.js +76 -0
  156. package/src/providers/xai.js +73 -0
  157. package/src/provisioning/capabilityConsent.js +24 -0
  158. package/src/provisioning/capabilityProvisioner.js +271 -0
  159. package/src/provisioning/capabilityTools.js +29 -0
  160. package/src/reporting.js +373 -0
  161. package/src/sandbox.js +529 -0
  162. package/src/sessionStore.js +279 -0
  163. package/src/skillsManager.js +288 -0
  164. package/src/slopDetector.js +307 -0
  165. package/src/taskBuffer.js +45 -0
  166. package/src/taskShape.js +241 -0
  167. package/src/textDiff.js +150 -0
  168. package/src/tokenTracker.js +560 -0
  169. package/src/tool-scripts/ax_snapshot.applescript +39 -0
  170. package/src/tool-scripts/ax_snapshot.ps1 +10 -0
  171. package/src/tool-scripts/desktop_act.applescript +58 -0
  172. package/src/tool-scripts/resolve_automator.py +119 -0
  173. package/src/toolPacks.js +524 -0
  174. package/src/tools/archive.js +63 -0
  175. package/src/tools/astryxOracle.js +78 -0
  176. package/src/tools/axSnapshot.js +165 -0
  177. package/src/tools/blenderAutomator.js +349 -0
  178. package/src/tools/browserAutomator.js +252 -0
  179. package/src/tools/checkSystemSpecs.js +64 -0
  180. package/src/tools/clipboard.js +36 -0
  181. package/src/tools/codeSearchAst.js +101 -0
  182. package/src/tools/codeSearcher.js +230 -0
  183. package/src/tools/codeTools.js +262 -0
  184. package/src/tools/codebaseSearch.js +75 -0
  185. package/src/tools/createSkill.js +129 -0
  186. package/src/tools/deferredMcpSearch.js +246 -0
  187. package/src/tools/desktopAct.js +208 -0
  188. package/src/tools/desktopOpen.js +34 -0
  189. package/src/tools/dynamicLoader.js +44 -0
  190. package/src/tools/executeProceduralMedia.js +93 -0
  191. package/src/tools/fsDelete.js +51 -0
  192. package/src/tools/fsEdit.js +105 -0
  193. package/src/tools/fsFind.js +128 -0
  194. package/src/tools/fsList.js +77 -0
  195. package/src/tools/fsMove.js +57 -0
  196. package/src/tools/fsRead.js +87 -0
  197. package/src/tools/fsSearch.js +198 -0
  198. package/src/tools/fsWrite.js +41 -0
  199. package/src/tools/gameAiBehaviorTree.js +208 -0
  200. package/src/tools/gameAnimationRig.js +194 -0
  201. package/src/tools/gameAssetFetcher.js +372 -0
  202. package/src/tools/gameAssetHarvester.js +210 -0
  203. package/src/tools/gameAudioSynth.js +267 -0
  204. package/src/tools/gameBuilder.js +886 -0
  205. package/src/tools/gameCanvasAudit.js +101 -0
  206. package/src/tools/gameCinematicSequencer.js +151 -0
  207. package/src/tools/gameDataForge.js +124 -0
  208. package/src/tools/gameDialogueTreeGen.js +166 -0
  209. package/src/tools/gameEconomyBalancer.js +161 -0
  210. package/src/tools/gameEntitySpawner.js +207 -0
  211. package/src/tools/gameLoreForge.js +153 -0
  212. package/src/tools/gameQuestArcBuilder.js +152 -0
  213. package/src/tools/gameSceneBuilder.js +158 -0
  214. package/src/tools/gameShaderForge.js +181 -0
  215. package/src/tools/gameTilemapGenerator.js +164 -0
  216. package/src/tools/gameUiHudBuilder.js +292 -0
  217. package/src/tools/gameVfxEmitterGen.js +108 -0
  218. package/src/tools/gameWebRuntimeInspector.js +91 -0
  219. package/src/tools/generateMediaViaApi.js +358 -0
  220. package/src/tools/gitExec.js +54 -0
  221. package/src/tools/godotAutomator.js +437 -0
  222. package/src/tools/manageLocalAiDependencies.js +220 -0
  223. package/src/tools/memoryWrite.js +99 -0
  224. package/src/tools/multiEdit.js +107 -0
  225. package/src/tools/palmierAutomator.js +104 -0
  226. package/src/tools/pdfReader.js +112 -0
  227. package/src/tools/persistentShell.js +148 -0
  228. package/src/tools/printer.js +316 -0
  229. package/src/tools/procTerm.js +91 -0
  230. package/src/tools/processList.js +52 -0
  231. package/src/tools/readNativeSkill.js +39 -0
  232. package/src/tools/registry.js +277 -0
  233. package/src/tools/resolveAutomator.js +102 -0
  234. package/src/tools/screenshot.js +75 -0
  235. package/src/tools/subagentOrchestrator.js +305 -0
  236. package/src/tools/sysRun.js +125 -0
  237. package/src/tools/todoWrite.js +75 -0
  238. package/src/tools/toolDispatch.js +127 -0
  239. package/src/tools/toolForge.js +124 -0
  240. package/src/tools/updatePlan.js +88 -0
  241. package/src/tools/viewImage.js +82 -0
  242. package/src/tools/visionInspector.js +154 -0
  243. package/src/tools/webFetch.js +74 -0
  244. package/src/tools/webSearch.js +82 -0
  245. package/src/tui/ask.js +164 -0
  246. package/src/tui/banner.js +158 -0
  247. package/src/tui/block.js +152 -0
  248. package/src/tui/chatRenderer.js +953 -0
  249. package/src/tui/completion.js +424 -0
  250. package/src/tui/dialogs.js +606 -0
  251. package/src/tui/diff.js +296 -0
  252. package/src/tui/history.js +135 -0
  253. package/src/tui/home.js +217 -0
  254. package/src/tui/invocation.js +105 -0
  255. package/src/tui/keys.js +443 -0
  256. package/src/tui/lineEditor.js +256 -0
  257. package/src/tui/overlay.js +256 -0
  258. package/src/tui/prompt.js +1258 -0
  259. package/src/tui/selectList.js +335 -0
  260. package/src/tui/stage.js +330 -0
  261. package/src/tui/stageSurface.js +609 -0
  262. package/src/tui/statusLine.js +254 -0
  263. package/src/tui/text.js +345 -0
  264. package/src/tui/theme.js +393 -0
  265. package/src/tui/toolDisplay.js +176 -0
  266. package/src/tui/transcript.js +235 -0
  267. package/src/tui/viewport.js +337 -0
  268. package/src/uncertainty.js +271 -0
  269. package/src/userSkills.js +265 -0
  270. package/src/utils/cli_ui.js +0 -0
  271. package/src/utils/inquirer.js +12 -0
  272. package/src/utils/paths.js +37 -0
  273. package/src/version.js +38 -0
  274. package/src/vfeTracker.js +220 -0
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: test-doubles-and-mocking
3
+ description: Use mocks, stubs, or fakes in tests. Use when a test needs an external dependency, when mocks make tests brittle, or when a suite mocks its own internals.
4
+ ---
5
+
6
+ # Test Doubles
7
+
8
+ ## The kinds, and when each is right
9
+
10
+ - **Stub** — returns canned answers. For queries: "this returns three users."
11
+ - **Fake** — a working lightweight implementation. An in-memory repository. Usually the best of the four.
12
+ - **Mock** — asserts it was called in a particular way. For commands with no observable result: "an email was sent."
13
+ - **Spy** — records calls for later inspection.
14
+
15
+ Prefer a fake. It exercises real behaviour and does not encode the caller's implementation into the test.
16
+
17
+ ## Workflow
18
+
19
+ 1. Mock only at real boundaries.
20
+ - Network, filesystem, clock, randomness, and third-party services. Mocking your own modules couples the test to the current internal structure — the thing you most want to be free to change.
21
+ - **Done when:** every double replaces something outside the unit under test.
22
+
23
+ 2. Never mock what you can control cheaply.
24
+ - A containerised database is faster to set up and catches far more than a mocked repository. Same for a local HTTP server versus a mocked client.
25
+ - **Done when:** slow-and-external is the only justification for each double.
26
+
27
+ 3. Make time and randomness injectable.
28
+ - Pass a clock and a source of randomness rather than calling the global. This removes the need to mock a global, which is the most fragile kind of double.
29
+ - **Done when:** no test needs to patch a global time or random function.
30
+
31
+ 4. Keep the double honest.
32
+ - A stub returning a shape the real dependency never returns produces a green test and a broken system. Where the language allows, type the double against the real interface, and add one contract test against the real dependency.
33
+ - **Done when:** at least one test exercises the real dependency for each mocked boundary.
34
+
35
+ 5. Assert interactions sparingly.
36
+ - Verify a call only when the call IS the outcome. Verifying every internal call turns the test into a transcript of the implementation.
37
+ - **Done when:** interaction assertions exist only for side effects with no observable result.
38
+
39
+ ## Verification
40
+
41
+ - Each double replaces a genuine external boundary.
42
+ - A contract test covers each mocked dependency against the real thing.
43
+ - Refactoring internals does not require changing doubles.
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: test-strategy-and-pyramid
3
+ description: Decide what to test and at what level. Use when a suite is slow and flaky, when coverage is high but bugs still ship, or when starting testing on an untested codebase.
4
+ ---
5
+
6
+ # Test Strategy
7
+
8
+ ## The proportions
9
+
10
+ Many fast unit tests, fewer integration tests, very few end-to-end tests. Inverting this gives a suite that is slow, flaky, and gives its feedback long after the mistake was made. But note the real goal: CONFIDENCE per second of runtime. A pure unit suite that mocks every boundary can pass while the system is entirely broken.
11
+
12
+ ## Workflow
13
+
14
+ 1. Test behaviour at the boundary the user cares about.
15
+ - For a library, that is its public API. For a service, its HTTP surface. For a UI, what a user can see and do. Testing internals locks the implementation and makes refactoring a test rewrite.
16
+ - **Done when:** the tests still pass after an internal refactor.
17
+
18
+ 2. Put each test at the lowest level that gives real confidence.
19
+ - Pure logic: unit. A query, a serialiser, an auth check: integration against a real dependency. A critical user journey: end-to-end, and only a handful of them.
20
+ - **Done when:** every test's level is justified by what it would catch.
21
+
22
+ 3. Use real dependencies where they are cheap.
23
+ - A containerised database in an integration test catches what a mocked repository never will — wrong SQL, a missing index, a constraint violation. Mock only what is slow, external, or non-deterministic.
24
+ - **Done when:** database and serialisation code is tested against the real thing.
25
+
26
+ 4. Treat coverage as a diagnostic, not a target.
27
+ - Coverage finds untested code. It cannot tell whether the tests assert anything meaningful. A coverage target produces tests written to satisfy the target.
28
+ - **Done when:** coverage is reported and used to find gaps, not enforced as a gate on its own.
29
+
30
+ 5. Delete flaky tests or fix them the same day.
31
+ - A tolerated flaky test teaches the team to re-run rather than to read. That habit is what lets a real failure ship.
32
+ - **Done when:** the suite has no known intermittent failures.
33
+
34
+ ## Verification
35
+
36
+ - The unit suite runs in seconds.
37
+ - The full suite runs in minutes.
38
+ - Ten consecutive runs give identical results.
39
+ - An internal refactor requires no test changes.
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: writing-good-assertions
3
+ description: Write or improve test assertions. Use when a failure message does not say what broke, when tests assert on implementation details, or when a test passes with any input.
4
+ ---
5
+
6
+ # Writing Good Assertions
7
+
8
+ ## What a failing test owes you
9
+
10
+ The failure message alone should tell you what broke and why, without opening the test. `expected true to be false` fails that; it costs a debugging session to learn what the test was even checking.
11
+
12
+ ## Workflow
13
+
14
+ 1. Assert on the outcome, not on the steps.
15
+ - Assert what the function returned and what changed in the world. Asserting that an internal helper was called with particular arguments tests the implementation, and breaks on every refactor while catching no bugs.
16
+ - **Done when:** no assertion mentions a private function or an internal call count.
17
+
18
+ 2. Compare whole values, not field by field.
19
+ - One deep equality on the expected object gives a diff. Ten separate field assertions stop at the first and hide the rest.
20
+ - **Done when:** structured results are asserted as a whole.
21
+
22
+ 3. Make the test name the specification.
23
+ - `rejects a token that expired one second ago`, not `test auth 3`. The name plus the failure should be enough to act on.
24
+ - **Done when:** every test name is a sentence about behaviour.
25
+
26
+ 4. Assert the negative space too.
27
+ - What must NOT happen: no email sent, no second write, nothing logged at error level, no other field changed. Most regressions are unintended extra effects, and only a negative assertion catches them.
28
+ - **Done when:** effect-producing code has at least one assertion about what did not happen.
29
+
30
+ 5. Prove the test can fail.
31
+ - Break the implementation deliberately and confirm the test goes red. A test that passes against broken code is worse than no test, because it is believed.
32
+ - **Done when:** each new test has been seen to fail for the right reason.
33
+
34
+ 6. Avoid conditionals in tests.
35
+ - An `if` in a test means it asserts different things in different runs, and it can silently assert nothing. Split it into separate tests or parametrise it.
36
+ - **Done when:** no test branches on runtime values.
37
+
38
+ ## Verification
39
+
40
+ - Every new test has been observed failing against a deliberate break.
41
+ - No assertion references a private implementation detail.
42
+ - Failure output identifies the problem without opening the test file.
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: accessible-components
3
+ description: Build or audit an interactive UI component — modal, dropdown, tabs, menu, form. Use when a component is built from divs, when it cannot be operated by keyboard, or when accessibility is being reviewed.
4
+ ---
5
+
6
+ # Accessible Components
7
+
8
+ ## The first rule
9
+
10
+ Use the native element. `<button>`, `<a href>`, `<details>`, `<dialog>`, `<input type="checkbox">`. Every one of them brings focus handling, keyboard behaviour, and screen-reader semantics that a div plus ARIA has to reimplement, usually incompletely. Reach for ARIA only when no native element exists.
11
+
12
+ ## Workflow
13
+
14
+ 1. Audit by keyboard alone.
15
+ - Unplug the mouse. Tab through the component. Can you reach everything, operate everything, and see where focus is?
16
+ - **Done when:** every interactive element is reachable and operable, and the focus ring is always visible.
17
+
18
+ 2. Fix semantics before appearance.
19
+ - A clickable div needs `role`, `tabindex`, and key handlers for Enter and Space. A button needs none of them. Convert rather than patch.
20
+ - **Done when:** the accessibility tree in DevTools shows the right role for every control.
21
+
22
+ 3. Manage focus at boundaries.
23
+ - Opening a modal moves focus into it and traps it there. Closing returns focus to the trigger. Without the return, keyboard users land at the top of the document.
24
+ - **Done when:** opening and closing leaves focus exactly where a mouse user's attention would be.
25
+
26
+ 4. Name everything.
27
+ - Every control has an accessible name: visible text, `aria-label`, or a `<label for>`. An icon-only button with no name is unusable by a screen reader.
28
+ - **Done when:** no control in the accessibility tree has an empty name.
29
+
30
+ 5. Announce what changes.
31
+ - Content that appears without a page change (validation errors, toasts, results counts) needs a live region, or it is silent.
32
+ - **Done when:** a screen reader announces the change without the user hunting for it.
33
+
34
+ ## Per-component keyboard contracts
35
+
36
+ - **Modal:** Escape closes, focus trapped, `role="dialog"` `aria-modal="true"`, labelled by its title.
37
+ - **Tabs:** arrow keys move between tabs, Tab moves into the panel, `aria-selected` and `aria-controls` wired.
38
+ - **Menu:** arrows move, Escape closes and returns focus, Home and End jump to the ends.
39
+ - **Combobox:** arrows move through options, Enter selects, Escape reverts, `aria-activedescendant` tracks.
40
+
41
+ ## Verification
42
+
43
+ - The whole flow is completable with the keyboard only.
44
+ - `axe` or the browser's accessibility audit reports no violations.
45
+ - Every control has a non-empty accessible name.
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: api-client-resilience
3
+ description: Write client-side code that calls an API. Use when fetch calls have no error handling, no timeout, or no cancellation, or when a component fetches in an effect without cleanup.
4
+ ---
5
+
6
+ # API Client Resilience
7
+
8
+ ## What every network call needs
9
+
10
+ A timeout, a cancellation path, an error branch, and a decision about retrying. A `fetch` with none of them will eventually hang a UI on a flaky network, and that failure is invisible in testing on a fast connection.
11
+
12
+ ## Workflow
13
+
14
+ 1. Give every request a timeout.
15
+ - `fetch` has no default timeout — a request can hang indefinitely. Use `AbortSignal.timeout(ms)`, and combine it with a cancellation signal via `AbortSignal.any()`.
16
+ - **Done when:** no request can outlive a stated deadline.
17
+
18
+ 2. Cancel on unmount and on supersession.
19
+ - A request whose component has unmounted must be aborted, or it resolves into a dead component. A search-as-you-type must abort the previous request, or responses arrive out of order and the UI shows the wrong result.
20
+ - **Done when:** rapid input produces one final result matching the last query.
21
+
22
+ 3. Treat a non-2xx response as an error explicitly.
23
+ - `fetch` does not reject on 404 or 500. Check `response.ok` — code that omits this parses an error page as data.
24
+ - **Done when:** every call checks `response.ok` before parsing.
25
+
26
+ 4. Retry only what is safe.
27
+ - Idempotent requests (GET, PUT, DELETE) may retry with exponential backoff and jitter. A POST may not, unless it carries an idempotency key.
28
+ - Never retry a 4xx: the request was wrong and will be wrong again.
29
+ - **Done when:** the retry policy is stated per method, and 4xx is excluded.
30
+
31
+ 5. Prefer a server-cache library over hand-rolled effects.
32
+ - TanStack Query or SWR already implement deduplication, caching, revalidation, retry and cancellation correctly. Hand-rolling them in `useEffect` reimplements the same four bugs each time.
33
+ - **Done when:** either a cache library is used, or the four behaviours above are each implemented and tested.
34
+
35
+ ## Verification
36
+
37
+ - A request against an unreachable host fails within the timeout rather than hanging.
38
+ - Typing quickly into a search box leaves the result matching the final query.
39
+ - A 500 response surfaces as an error state, not as parsed data.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: bundle-size-reduction
3
+ description: Reduce JavaScript or CSS bundle size. Use when a build warns about chunk size, when a page ships more than a few hundred kilobytes of script, or when load time is dominated by download and parse.
4
+ ---
5
+
6
+ # Bundle Size Reduction
7
+
8
+ ## Workflow
9
+
10
+ 1. Look at the bundle before guessing.
11
+ - `rollup-plugin-visualizer`, `webpack-bundle-analyzer`, or `vite build --mode production` with a visualiser. One dependency is usually most of the weight.
12
+ - **Done when:** you can name the three largest contributors and their sizes.
13
+
14
+ 2. Attack the largest one first.
15
+ - Common offenders and their fixes:
16
+ - A date library — use `Intl.DateTimeFormat` or a modular alternative.
17
+ - A full icon set — import individual icons, never the barrel file.
18
+ - `lodash` — import the single function path, or use the platform equivalent.
19
+ - A charting or editor library — load it dynamically at the point of use.
20
+ - **Done when:** the largest contributor has dropped measurably or is justified in writing.
21
+
22
+ 3. Split by route.
23
+ - Dynamic `import()` at route boundaries. The landing page should not carry the admin dashboard's code.
24
+ - **Done when:** navigating between routes loads separate chunks.
25
+
26
+ 4. Check tree-shaking is actually working.
27
+ - It requires ES modules, `"sideEffects": false` in the dependency's manifest, and no barrel file re-exporting everything. A single CommonJS dependency in the chain can defeat it silently.
28
+ - **Done when:** an unused export from a first-party module is absent from the output.
29
+
30
+ 5. Do not forget CSS and fonts.
31
+ - Unused CSS from a utility framework needs the purge step configured against every template path. Subset fonts to the characters actually used.
32
+ - **Done when:** the CSS bundle contains no selector the app cannot produce.
33
+
34
+ ## Verification
35
+
36
+ - Report the before and after transferred size for the entry chunk.
37
+ - The largest chunk is below the project's stated budget.
38
+ - The app still works: run the test suite and load every route.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: core-web-vitals
3
+ description: Improve page load or interaction performance on the web. Use when a page feels slow, when Lighthouse scores are low, or before shipping a public-facing page.
4
+ ---
5
+
6
+ # Core Web Vitals
7
+
8
+ ## The three metrics, and what actually moves them
9
+
10
+ - **LCP** (largest contentful paint) — how long until the main thing appears. Dominated by server response time and by whether the hero image or font is discoverable early.
11
+ - **INP** (interaction to next paint) — how long the page takes to respond to input. Dominated by long tasks on the main thread.
12
+ - **CLS** (cumulative layout shift) — how much things move. Dominated by images and ads without reserved space, and by fonts swapping.
13
+
14
+ ## Workflow
15
+
16
+ 1. Measure before changing anything.
17
+ - Lab first (Lighthouse, DevTools performance panel), then field data if available. Lab numbers on a fast laptop are optimistic; throttle to a mid-tier device.
18
+ - **Done when:** you have a baseline number for each of the three metrics.
19
+
20
+ 2. Fix LCP at the source.
21
+ - Identify the LCP element in DevTools. It is almost always an image or a heading blocked by a font.
22
+ - Preload it, set `fetchpriority="high"`, serve modern formats, and size it correctly. Never lazy-load the LCP image — that is the single most common self-inflicted LCP regression.
23
+ - **Done when:** the LCP element starts loading in the first network round trip.
24
+
25
+ 3. Fix CLS by reserving space.
26
+ - Every image and video gets explicit `width` and `height` (or `aspect-ratio`). Every font uses `font-display: optional` or `swap` with a metric-matched fallback.
27
+ - **Done when:** CLS is under 0.1 and the page does not visibly jump on reload.
28
+
29
+ 4. Fix INP by breaking up long tasks.
30
+ - Find tasks over 50ms in the performance panel. Split them, defer them, or move them off the main thread.
31
+ - Ship less JavaScript: code-split by route, drop polyfills for browsers you do not support, and audit the bundle for a single dependency dominating it.
32
+ - **Done when:** no task on the interaction path exceeds 50ms.
33
+
34
+ 5. Re-measure.
35
+ - **Done when:** each metric has improved against the recorded baseline, with the numbers stated.
36
+
37
+ ## Verification
38
+
39
+ - Lighthouse on a throttled mid-tier profile shows LCP under 2.5s, INP under 200ms, CLS under 0.1.
40
+ - The before and after numbers are reported side by side.
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: css-layout-systems
3
+ description: Build a page or component layout in CSS. Use when a layout uses absolute positioning or floats, when it breaks at a viewport size, or when a container will not centre.
4
+ ---
5
+
6
+ # CSS Layout Systems
7
+
8
+ ## Choosing between the two
9
+
10
+ - **Flexbox** — one dimension. A row of items, a column of stacked sections, anything where content size should drive the layout.
11
+ - **Grid** — two dimensions, or any layout where the CONTAINER should define the structure regardless of content. Page shells, card grids, forms with aligned labels.
12
+
13
+ Absolute positioning is for overlays only. Floats are for wrapping text around an image and nothing else.
14
+
15
+ ## Workflow
16
+
17
+ 1. Name the layout in one sentence before writing CSS.
18
+ - "A sidebar of fixed width and a main area that fills the rest" is a grid. "A row of buttons pushed to the right" is flex. The sentence picks the tool.
19
+ - **Done when:** the layout is described in words and the tool follows from it.
20
+
21
+ 2. Let the intrinsic sizing work.
22
+ - `minmax()`, `auto-fit`, `clamp()` and `min-content` remove most media queries. A card grid that reflows with `repeat(auto-fit, minmax(16rem, 1fr))` needs no breakpoints at all.
23
+ - **Done when:** the layout adapts across widths with as few explicit breakpoints as possible.
24
+
25
+ 3. Fix overflow at the source.
26
+ - A grid or flex item defaults to `min-width: auto`, which refuses to shrink below its content. That is why a long word or a wide table breaks the page. Set `min-width: 0` on the item.
27
+ - **Done when:** no horizontal scrollbar appears on the page body at any width.
28
+
29
+ 4. Use logical properties.
30
+ - `margin-inline`, `padding-block`, `inset-inline-start`. They work in right-to-left languages without a second stylesheet.
31
+ - **Done when:** the layout is correct with `dir="rtl"` set on the document.
32
+
33
+ 5. Contain what scrolls.
34
+ - Wide content — tables, code blocks, diagrams — scrolls inside its own `overflow-x: auto` container. The page body never scrolls sideways.
35
+ - **Done when:** every wide element scrolls within itself.
36
+
37
+ ## Verification
38
+
39
+ - No horizontal page scroll from 320px to 2560px.
40
+ - `dir="rtl"` produces a mirrored, correct layout.
41
+ - Zooming text to 200% does not clip or overlap content.
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: form-validation-ux
3
+ description: Build or fix a form. Use when validation fires on every keystroke, when errors are not associated with fields, or when a submit can be double-fired.
4
+ ---
5
+
6
+ # Form Validation UX
7
+
8
+ ## Timing is the whole design
9
+
10
+ Validate a field when the user LEAVES it, not while they are typing. Validating on every keystroke tells someone their email is invalid after the first character, which is both true and useless. Once a field has errored, re-validate on change so the error clears as soon as it is fixed.
11
+
12
+ ## Workflow
13
+
14
+ 1. Validate on the server regardless.
15
+ - Client validation is a convenience. Anything that matters is enforced server-side, because the client is under the user's control.
16
+ - **Done when:** every rule exists on the server, whether or not it also exists on the client.
17
+
18
+ 2. Share one schema.
19
+ - Define the rules once (Zod, Valibot, a JSON schema) and use them on both sides. Two hand-written copies drift, and the drift shows up as a form that submits and then fails.
20
+ - **Done when:** changing a rule in one place changes both sides.
21
+
22
+ 3. Wire errors to fields accessibly.
23
+ - `aria-invalid` on the input, `aria-describedby` pointing at the message, and the message in a live region. An error rendered near the field but not associated with it is invisible to a screen reader.
24
+ - **Done when:** a screen reader announces the error when focus enters the field.
25
+
26
+ 4. Make submission safe.
27
+ - Disable the submit while in flight and guard on the server with an idempotency key. A double-click on a slow network creates two orders.
28
+ - **Done when:** double-submitting produces one result.
29
+
30
+ 5. Never lose what was typed.
31
+ - On a failed submit, keep every value and focus the first invalid field. Clearing a form on error is the fastest way to lose a user.
32
+ - **Done when:** a failed submit preserves all input and moves focus to the first problem.
33
+
34
+ ## Verification
35
+
36
+ - Submitting empty shows all errors at once, with focus on the first.
37
+ - Fixing a field clears its error immediately.
38
+ - Double-clicking submit produces one server-side effect.
39
+ - The whole form is completable by keyboard.
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: react-state-architecture
3
+ description: Choose where state lives in a React application. Use when props are threaded through many layers, when a context re-renders the whole tree, or when a global store is being added.
4
+ ---
5
+
6
+ # React State Architecture
7
+
8
+ ## The ordering rule
9
+
10
+ State belongs at the lowest level that can own it. Every level it is lifted above that is a re-render nobody asked for. Reach for the next tier only when the current one provably fails.
11
+
12
+ 1. Local `useState` — owned by one component.
13
+ 2. Lifted to the nearest common parent — shared by siblings.
14
+ 3. URL — anything the user should be able to link to, refresh into, or navigate back to. Filters, tabs, pagination, selected item.
15
+ 4. Server cache (TanStack Query, SWR, RSC) — anything that came from the network. This is not application state; it is a cache with staleness, and treating it as state is the single most common source of duplicate fetching and stale UI.
16
+ 5. Context — genuinely global and rarely changing: theme, locale, the authenticated user.
17
+ 6. A store (Zustand, Redux) — high-frequency global state with complex updates. Rare.
18
+
19
+ ## Workflow
20
+
21
+ 1. Classify each piece of state against the tiers above.
22
+ - The question that resolves most cases: does this come from the server? If yes, it belongs in the server cache, not in `useState` with a `useEffect`.
23
+ - **Done when:** every piece of state is assigned to a tier with a stated reason.
24
+
25
+ 2. Move URL-shaped state to the URL.
26
+ - Search params via the router. This gets back-button and shareability for free, both of which are otherwise bugs users will report.
27
+ - **Done when:** reloading the page restores the same view.
28
+
29
+ 3. Split contexts by update frequency.
30
+ - One context holding both the theme and a live cursor position re-renders every consumer on every mouse move. Separate them.
31
+ - **Done when:** no context holds values with different change rates.
32
+
33
+ 4. Derive instead of storing.
34
+ - A value computable from other state must not be stored. Two sources of truth drift, and the drift is a bug class you cannot test away.
35
+ - **Done when:** no `useEffect` exists whose only job is to sync one state value from another.
36
+
37
+ ## Verification
38
+
39
+ - The React DevTools profiler shows no component re-rendering on an update it does not display.
40
+ - Reloading any view restores it exactly.
41
+ - Searching for `useEffect` finds none that only call `setState` from other state.
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: ssr-hydration-correctness
3
+ description: Debug or prevent a server-rendering hydration mismatch. Use when the console warns about hydration, when content flashes and changes on load, or when a component behaves differently on first render.
4
+ ---
5
+
6
+ # SSR Hydration Correctness
7
+
8
+ ## What a mismatch means
9
+
10
+ The server produced one tree and the client produced a different one from the same props. The framework has to discard its work and re-render, which costs the performance the server render was supposed to buy — and in the worst case leaves the DOM and the component state disagreeing.
11
+
12
+ ## The four causes, in order of frequency
13
+
14
+ 1. **Non-deterministic values.** `Date.now()`, `Math.random()`, `crypto.randomUUID()` produce different output on each side.
15
+ 2. **Browser-only APIs read during render.** `window`, `document`, `localStorage`, `matchMedia`. These are undefined on the server, so the branch differs.
16
+ 3. **Locale or timezone formatting.** The server formats in UTC and the client in the user's zone.
17
+ 4. **Invalid HTML nesting.** A `<div>` inside a `<p>`, or a `<td>` outside a row. The browser repairs the DOM, so the client tree no longer matches what was sent.
18
+
19
+ ## Workflow
20
+
21
+ 1. Read the mismatch message for the specific element.
22
+ - Modern frameworks name the node and show both trees. That usually identifies the cause outright.
23
+ - **Done when:** you can point at the exact element and value that differ.
24
+
25
+ 2. Move non-deterministic work out of render.
26
+ - Compute it on the server and pass it as a prop, or compute it in an effect after mount and accept one frame of the fallback.
27
+ - **Done when:** render is a pure function of props on both sides.
28
+
29
+ 3. Gate browser-only reads behind mount.
30
+ - Read the value in an effect and store it in state, rather than reading it during render. The first render then matches the server by construction.
31
+ - **Done when:** no browser global is read during render.
32
+
33
+ 4. Fix formatting by fixing the inputs.
34
+ - Send an ISO timestamp and an explicit timezone; format identically on both sides. Do not paper over it with a suppression attribute — that hides the mismatch without removing it.
35
+ - **Done when:** the same input formats to the same string on both sides.
36
+
37
+ 5. Validate the HTML.
38
+ - Run the server output through a validator. Nesting errors produce mismatches that look inexplicable at the component level.
39
+ - **Done when:** the server HTML validates.
40
+
41
+ ## Verification
42
+
43
+ - No hydration warning in the console on any route.
44
+ - No visible flash of changed content on load.
45
+ - Disabling JavaScript still shows correct server-rendered content.
package/package.json CHANGED
@@ -1,6 +1,70 @@
1
1
  {
2
2
  "name": "@causyne/agent",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.10.0",
4
+ "description": "Agentic AI for software, tools, and computer workflows",
5
+ "main": "bin/causyne.js",
6
+ "type": "module",
7
+ "bin": {
8
+ "causyne": "bin/causyne.js",
9
+ "causyne-agent": "bin/causyne.js"
10
+ },
11
+ "files": [
12
+ "bin/",
13
+ "src/",
14
+ "native-skills/",
15
+ "README.md",
16
+ "SECURITY.md",
17
+ "LICENSE",
18
+ "docs/ARCHITECTURE.md",
19
+ "docs/PROVENANCE.md",
20
+ "docs/SECURITY_REVIEW.md",
21
+ "docs/THIRD_PARTY_NOTICES.md"
22
+ ],
23
+ "scripts": {
24
+ "start": "node ./bin/causyne.js",
25
+ "test": "node --test --import ./tests/helpers/isolateState.js \"tests/**/*.test.js\"",
26
+ "build": "node scripts/compile_skills.js",
27
+ "check:release": "node scripts/check_release.js",
28
+ "check:public": "npm run check:release && node scripts/check_public_release.js",
29
+ "prepublishOnly": "npm run check:public && npm test && npm run typecheck:strict",
30
+ "typecheck": "tsc -p tsconfig.json",
31
+ "typecheck:strict": "tsc -p tsconfig.strict.json"
32
+ },
33
+ "engines": {
34
+ "node": ">=24.0.0"
35
+ },
36
+ "keywords": [
37
+ "ai",
38
+ "agent",
39
+ "automation",
40
+ "causyne",
41
+ "cli"
42
+ ],
43
+ "license": "BUSL-1.1",
44
+ "repository": {
45
+ "type": "git",
46
+ "url": "git+https://github.com/ikbal-causyne/causyne-agent.git"
47
+ },
48
+ "homepage": "https://causyne.com/",
49
+ "bugs": {
50
+ "url": "https://github.com/ikbal-causyne/causyne-agent/issues"
51
+ },
52
+ "overrides": {
53
+ "form-data": "^4.0.0",
54
+ "axios": "^1.20.0"
55
+ },
56
+ "dependencies": {
57
+ "@babel/parser": "^8.0.4",
58
+ "acorn-walk": "^8.3.5",
59
+ "commander": "^11.1.0",
60
+ "duck-duck-scrape": "^2.2.7",
61
+ "googlethis": "^1.8.0",
62
+ "inquirer": "^9.2.12"
63
+ },
64
+ "devDependencies": {
65
+ "@types/node": "^22.20.2",
66
+ "acorn": "^8.18.0",
67
+ "typescript": "^7.0.2"
68
+ },
69
+ "private": false
70
+ }