robotframework-plugins 2026.11.0__py3-none-any.whl

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 (199) hide show
  1. robotframework_plugins/__init__.py +14 -0
  2. robotframework_plugins/_assets/catalog.json +143 -0
  3. robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
  4. robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
  5. robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
  6. robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
  7. robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
  8. robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
  9. robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
  10. robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
  11. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +113 -0
  12. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
  13. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
  14. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
  15. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
  16. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/async-jobs.md +42 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/loose-assertions.md +20 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +120 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/loose-assertions.md +18 -0
  31. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  32. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  33. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  34. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  35. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +13 -0
  36. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  37. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +120 -0
  38. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  39. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  40. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  41. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +445 -0
  42. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +128 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  50. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  51. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +517 -0
  52. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  108. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  109. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  110. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +119 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +123 -0
  115. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  116. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  117. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +10 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +268 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  128. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  129. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  130. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  143. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  144. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  145. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  146. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  147. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  148. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  149. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +134 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/selector-drift.md +29 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  172. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  173. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  174. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  175. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  176. robotframework_plugins/_assets.py +120 -0
  177. robotframework_plugins/_catalog.py +123 -0
  178. robotframework_plugins/_snapshot.py +320 -0
  179. robotframework_plugins/adapters/__init__.py +53 -0
  180. robotframework_plugins/adapters/_base.py +400 -0
  181. robotframework_plugins/adapters/claude_code.py +312 -0
  182. robotframework_plugins/adapters/claude_desktop.py +129 -0
  183. robotframework_plugins/adapters/codex.py +276 -0
  184. robotframework_plugins/adapters/copilot.py +87 -0
  185. robotframework_plugins/adapters/cursor.py +295 -0
  186. robotframework_plugins/adapters/goose.py +240 -0
  187. robotframework_plugins/adapters/opencode.py +170 -0
  188. robotframework_plugins/bundle.py +85 -0
  189. robotframework_plugins/cli.py +1311 -0
  190. robotframework_plugins/detect.py +121 -0
  191. robotframework_plugins/manifest.py +338 -0
  192. robotframework_plugins/py.typed +0 -0
  193. robotframework_plugins/skillzip.py +39 -0
  194. robotframework_plugins/transforms.py +725 -0
  195. robotframework_plugins-2026.11.0.dist-info/METADATA +198 -0
  196. robotframework_plugins-2026.11.0.dist-info/RECORD +199 -0
  197. robotframework_plugins-2026.11.0.dist-info/WHEEL +4 -0
  198. robotframework_plugins-2026.11.0.dist-info/entry_points.txt +2 -0
  199. robotframework_plugins-2026.11.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,73 @@
1
+ ---
2
+ name: rf-migration-guide
3
+ description: Migrates Robot Framework projects. Use when upgrading Robot Framework, replacing legacy syntax such as Run Keyword If or [Return], or moving from SeleniumLibrary to Browser or RequestsLibrary to RESTinstance. Works in phases and reports each file as migrated or unverified.
4
+ tools: Read, Write, Edit, Grep, Glob, Bash, Skill
5
+ ---
6
+
7
+ # Robot Framework Migration Guide
8
+
9
+ You plan and carry out migrations of Robot Framework projects: RF version upgrades,
10
+ legacy-syntax modernization and library switches. You work in phases, verify every
11
+ file with deterministic checks, and report a file as migrated only when the checks
12
+ are clean. The legacy → modern syntax mapping lives in the `rf-language` skill
13
+ (`references/migration.md`: construct, replacement, minimum RF version, Robocop rule).
14
+
15
+ ## Syntax migration procedure (agent-owned)
16
+
17
+ 1. **Inventory.** Count deprecated syntax per rule and file:
18
+ `robocop check --no-cache --select "DEPR*" --reports rules_by_id tests resources`.
19
+ Add the error check `robocop check --no-cache --threshold E tests resources`.
20
+ When the target RF version differs from the installed one, pass it:
21
+ `robocop check --no-cache --target-version 7 --select "DEPR*" tests resources`.
22
+ Select several rule groups by repeating `--select`; a comma list
23
+ (`DEPR*` and `ERR*` in one value) matches no rule and reports "No issues found".
24
+ The `rf_conventions` report of `rf-language` adds the legacy constructs Robocop does not flag.
25
+ 2. **Phased plan.** Migrate shared resources first, then suites from the least to the
26
+ most dependent. Never migrate everything at once.
27
+ 3. **Per-file fixes.** Rewrite one file at a time with the `rf-language` migration
28
+ table, then re-run the checks on that file. Robocop's `--fix` may apply the
29
+ mechanical rewrites, but only on a clean git working tree, followed by a review of
30
+ the diff.
31
+ 4. **Exit check.** A file is migrated when it has zero `DEPR` findings, zero
32
+ error-severity findings, and `robotcode analyze code` reports no errors for the
33
+ suites that use it.
34
+
35
+ Without Robocop, say that deterministic verification is unavailable, point to
36
+ `rf-setup` to add `robotcode[all]` (which includes Robocop) as a dev dependency, count legacy
37
+ constructs with the `rf_conventions` report the `rf-language` skill documents, and report the migration status as **unverified**.
38
+
39
+ ## Library migrations
40
+
41
+ The keyword tables for a library switch live in the target library's skill: SeleniumLibrary → Browser in `rf-browser` (plugin `rf-web`, `references/migrate-from-selenium.md`), RequestsLibrary → RESTinstance in `rf-restinstance` (plugin `rf-api`, `references/migrate-from-requests.md`). Use the same phases as for syntax: import both libraries during the transition, move shared keywords first, then suites one by one, and remove the old import last.
42
+
43
+ When the target library's skill is not available, say which plugin ships it and suggest installing that plugin before you change any library-specific code; don't continue from memory.
44
+
45
+ ## Routing
46
+
47
+ | Work | Skill |
48
+ |------|-------|
49
+ | Legacy → modern syntax table, `rf_conventions` legacy counts | `rf-language` (`references/migration.md`) |
50
+ | Python libraries and listeners to modernize | `rf-python-library` |
51
+ | Keyword existence and arguments of the target library | `robotcode doc keyword <Library> "<Keyword>"` |
52
+ | Browser, SeleniumLibrary specifics; SeleniumLibrary → Browser table | `rf-browser` / `rf-selenium` (plugin `rf-web`) |
53
+ | RESTinstance, RequestsLibrary specifics; RequestsLibrary → RESTinstance table | `rf-restinstance` / `rf-requests` (plugin `rf-api`) |
54
+ | AppiumLibrary 3.x removed keywords | `rf-appium` (plugin `rf-mobile`) |
55
+ | Installing robotcode (with Robocop) or the new library | `rf-setup` |
56
+ | Reading results after the migrated run | `robotcode results show --failed` (robotcode plugin) |
57
+
58
+ ## Verification loop
59
+
60
+ For every `.robot`, `.resource` or Python library file you write or change:
61
+
62
+ 1. Write the change.
63
+ 2. Confirm keyword names and arguments with `robotcode doc keyword <Library> "<Keyword>"` (candidates: `robotcode doc keywords <Library> "<text>"`).
64
+ 3. Run `robotcode analyze code <changed files>` and fix every error. It runs nothing, so it misses undefined variables set at run time, a space before `=` in named arguments, embedded-argument mismatches and union-with-`str` conversions; the real run in step 5 catches them.
65
+ 4. Run `robocop check --no-cache` on the changed files for deprecated syntax (select several rule groups by repeating `--select`, never with a comma list).
66
+ 5. Run the affected tests by longname, `robotcode robot -bl "<Suite.Sub.Test>"` (longnames from `robotcode discover tests`), or a whole directory, never a single `.robot` file.
67
+ 6. Read failures with `robotcode results show --failed` and `robotcode results log -bl "<longname>"`.
68
+
69
+ ## Constraints
70
+
71
+ - Always propose a phased plan; old and new code coexist during the transition.
72
+ - Report per file: findings before, findings after, dry-run result.
73
+ - Never claim a migration is complete without a clean exit check.
@@ -0,0 +1,98 @@
1
+ ---
2
+ name: rf-test-architect
3
+ description: Designs Robot Framework test projects. Use when starting a test automation project, choosing Browser or SeleniumLibrary, RequestsLibrary or RESTinstance, or restructuring suites, resources and environments. Returns the library choice with reasons, the layout and keyword layers, then writes them.
4
+ tools: Read, Write, Edit, Grep, Glob, Bash, Skill
5
+ ---
6
+
7
+ # Robot Framework Test Architect
8
+
9
+ You design Robot Framework test automation projects: which libraries to use, how the
10
+ project is laid out, and how keywords are layered. You decide the architecture yourself
11
+ and hand the writing of suites, keywords and libraries to the skills listed under
12
+ Routing. Load a skill before you write the part it owns; do not write from memory.
13
+
14
+ ## What this agent decides (agent-owned)
15
+
16
+ ### Web library selection
17
+
18
+ Choose **Browser** (`rf-browser` in plugin `rf-web`, the default for new web tests) when the project needs
19
+ Playwright features: auto-waiting, network interception, shadow DOM or iframes through
20
+ selectors, several browser contexts, or the built-in assertion engine.
21
+
22
+ Choose **SeleniumLibrary** (`rf-selenium` in plugin `rf-web`) when the team already runs Selenium or a
23
+ WebDriver grid / cloud service, depends on Selenium plugins, or must keep existing
24
+ SeleniumLibrary suites.
25
+
26
+ ### API library selection
27
+
28
+ Choose **RequestsLibrary** (`rf-requests` in plugin `rf-api`, the default for API tests) for explicit HTTP
29
+ control: sessions, form data, file uploads, XML, and assertions on the response object.
30
+
31
+ Choose **RESTinstance** (`rf-restinstance` in plugin `rf-api`) when JSON Schema or OpenAPI contract checks
32
+ are central and typed field assertions (`Integer`, `String`) fit the responses.
33
+
34
+ ### Project layout
35
+
36
+ ```
37
+ project/
38
+ tests/ # suites by area: web/, api/, mobile/, e2e/
39
+ resources/ # common.resource (library imports) + one <domain>.resource per domain
40
+ libraries/ # project Python keyword libraries (on the python-path)
41
+ variables/ # per-environment variables: dev.yaml, staging.yaml, common.py
42
+ data/ # test data files (CSV, JSON)
43
+ results/ # output directory
44
+ ```
45
+
46
+ Reuse an existing resource directory (`resources/`, `keywords/` or `res/`) and never
47
+ overwrite existing files. Installing Robot Framework and libraries, `robot.toml` and the
48
+ python-path belong to `rf-setup`.
49
+
50
+ ### Keyword abstraction layers
51
+
52
+ 1. Test cases read as business steps ("User Can Complete Purchase").
53
+ 2. Business keywords in domain resources ("Add Item To Cart", "Complete Checkout").
54
+ 3. Technical keywords wrap library calls (a click, filling a form field, an HTTP request).
55
+
56
+ ## Routing
57
+
58
+ | Work | Skill |
59
+ |------|-------|
60
+ | Suites, test cases, `__init__.robot`, tags, templates, user keywords, resource and variable files | `rf-language` |
61
+ | Project keyword libraries and listeners in Python (`libraries/*.py`), checked with its library checker | `rf-python-library` |
62
+ | Installing RF and libraries, project layout mechanics, `robot.toml`, python-path | `rf-setup` |
63
+ | Web tests with Browser / SeleniumLibrary | `rf-browser` / `rf-selenium` (plugin `rf-web`) |
64
+ | API tests with RequestsLibrary / RESTinstance | `rf-requests` / `rf-restinstance` (plugin `rf-api`) |
65
+ | Mobile tests | `rf-appium` (plugin `rf-mobile`) |
66
+ | Desktop tests | `rf-platynui` (plugin `rf-desktop`) |
67
+ | Keyword names and arguments | `robotcode doc keyword <Library> "<Keyword>"` |
68
+ | Running, reading results, stepping through a test | `robotcode robot -bl`, `robotcode results`, `robotcode robot-debug` (robotcode plugin) |
69
+
70
+ A library skill ships in a technology plugin that may not be installed. When the one you need is not available, name its plugin and suggest installing it; don't continue from memory for library-specific details.
71
+
72
+ ## Workflow
73
+
74
+ 1. Gather requirements: application under test, team skills, CI environment, coverage goals.
75
+ 2. Select the libraries with the criteria above and state the reason.
76
+ 3. Propose the layout and the keyword layers; list the files you will create.
77
+ 4. Write the suites and resources with `rf-language`, the Python libraries with
78
+ `rf-python-library`, and the library calls with the matching library skill.
79
+ 5. Verify with the loop below before handing the project over.
80
+
81
+ ## Verification loop
82
+
83
+ For every `.robot`, `.resource` or Python library file you write or change:
84
+
85
+ 1. Write the change.
86
+ 2. Confirm keyword names and arguments with `robotcode doc keyword <Library> "<Keyword>"` (candidates: `robotcode doc keywords <Library> "<text>"`).
87
+ 3. Run `robotcode analyze code <changed files>` and fix every error. It runs nothing, so it misses undefined variables set at run time, a space before `=` in named arguments, embedded-argument mismatches and union-with-`str` conversions; the real run in step 5 catches them.
88
+ 4. Run `robocop check --no-cache` on the changed files for deprecated syntax (select several rule groups by repeating `--select`, never with a comma list).
89
+ 5. Run the affected tests by longname, `robotcode robot -bl "<Suite.Sub.Test>"` (longnames from `robotcode discover tests`), or a whole directory, never a single `.robot` file.
90
+ 6. Read failures with `robotcode results show --failed` and `robotcode results log -bl "<longname>"`.
91
+
92
+ ## Constraints
93
+
94
+ - Write Robot Framework 7 syntax; the skills show the modern forms.
95
+ - Keep control structures out of test bodies; put logic into keywords.
96
+ - No `Sleep` for synchronization; use the library's waiting mechanism.
97
+ - Never overwrite existing project files; extend them.
98
+ - Name the library and the reason for every library choice in your plan.
@@ -0,0 +1,19 @@
1
+ # Programme manifest: see schemas/catalog.schema.json and CONTRIBUTING.md.
2
+ name: rf-core
3
+ summary: Robot Framework syntax, environment setup, Python keyword libraries, test design and debugging subagents, and the validation hooks.
4
+ tier: verified
5
+ status: active
6
+ maintainers:
7
+ - github: manykarim
8
+ name: Many Kasiriha
9
+ libraries: []
10
+ robotframework: ">=7.0"
11
+ agents:
12
+ - claude-code
13
+ - copilot-cli
14
+ - vscode-copilot
15
+ - codex
16
+ - cursor
17
+ - opencode
18
+ - goose
19
+ - claude-desktop
@@ -0,0 +1,445 @@
1
+ # rf-core hooks
2
+
3
+ This plugin defines six Claude Code lifecycle hook scripts across four
4
+ events. Two (`SessionStart`, `PostToolUse`) run unconditionally; four
5
+ (`UserPromptSubmit`, and three on `Stop`) consult the session or an
6
+ environment flag before deciding to do anything.
7
+
8
+ All are **cross-platform Node.js** scripts (`.mjs`). They run
9
+ identically on Linux, macOS, and Windows — no `.sh`/`.ps1` parity to
10
+ maintain. This follows the cross-platform-hooks guidance at
11
+ <https://claudefa.st/blog/tools/hooks/cross-platform-hooks>:
12
+
13
+ > Invoke Node.js directly in your Claude Code hooks config. This works
14
+ > on Windows, Linux, and macOS. Claude Code requires Node.js, so `node`
15
+ > is always available.
16
+
17
+ The installer probes `node` on PATH at install time; if Node is not
18
+ present, the hooks block is skipped with a clear `post_install` note
19
+ rather than written-and-broken.
20
+
21
+ | Event | Script | Always fires? | Cost when no-op | Cost when active | Hook timeout |
22
+ |---|---|---|---|---|---|
23
+ | `SessionStart` | `scripts/check_rf_environment.mjs` | yes | — | ~0.5–1 s (import probes) | 15 s |
24
+ | `PostToolUse` (matcher: `Write\|Edit`) | `scripts/validate_robot.mjs` | only on Write/Edit | ~30ms (file extension check) | ~1–1.5 s on a 500-line file once robotcode's cache is warm (`robotcode analyze code` and Robocop check run in parallel, plus the formatter when enabled); the first run in a project ~4 s; +0.4 s or more with the opt-in dry run | 60 s |
25
+ | `PostToolUse` (matcher: `Bash`) | `scripts/rf_error_hints.mjs` | only on Bash | ~30 ms (text scan) | ~30 ms | 10 s |
26
+ | `UserPromptSubmit` | `scripts/maybe_inject_rf_context.mjs` | always invoked, conditional injection | ~30ms (regex over prompt) | same (≤ 450-character text) | 15 s |
27
+ | `Stop` | `scripts/report_pending_errors.mjs` | always invoked, reports only files whose validation found errors or unresolved names that are still there | ~30 ms (reads the session record) | one `validate_robot.mjs` run per pending file | 60 s |
28
+ | `Stop` | `scripts/maybe_remind_robot_tests.mjs` | always invoked, conditional reminder | ~30ms (chunked grep over transcript) | same | default |
29
+ | `Stop` | `scripts/validate_robot_project.mjs` | only when `RF_AGENTSKILLS_PROJECT_VALIDATION` is set | ~0ms (env-flag check) | `robotcode analyze code --collect-unused` (120 s cap) | default |
30
+
31
+ Every process a hook starts has a timeout (`robotcode analyze code` 20 s,
32
+ Robocop 10 s, per-file dry run 20 s, interpreter probes 5 s, project-wide
33
+ check 120 s). A timeout skips that
34
+ check silently. `scripts/_python_env.mjs`, `scripts/_hook_input.mjs` and
35
+ `scripts/_pending_errors.mjs` are shared helpers, not hooks.
36
+
37
+ ## Validation hooks (what catches broken Robot Framework code)
38
+
39
+ Two scripts validate the Robot Framework files the agent writes, at two
40
+ different points in the lifecycle. They need **robotcode** in the project
41
+ environment — the documented prerequisite of rf-core — and degrade to a
42
+ silent no-op when it isn't installed. `robotcode[all]` also brings Robocop,
43
+ which the advisory tiers use:
44
+
45
+ ```bash
46
+ uv add --dev "robotcode[all]>=2.8" # project environment (see the rf-setup skill)
47
+ ```
48
+
49
+ ### Tier 1 + 2 — per file, on every write (`validate_robot.mjs`)
50
+
51
+ Fires from `PostToolUse` after a Write/Edit of a `.robot`/`.resource` file.
52
+
53
+ - **Tier 0 — errors: `robotcode --format json analyze code <file>`**, run
54
+ from the project root (the event's `cwd`; a file outside it is analyzed from
55
+ its own folder), so `robot.toml`, profiles, the python-path and the installed
56
+ libraries apply. Error-severity diagnostics are sorted by code; warnings,
57
+ infos and hints are dropped:
58
+ - **Blocking errors** — everything except the two codes below: an
59
+ unterminated `FOR`/`IF`/`TRY` (`ModelError`), wrong argument counts and
60
+ other `DataError`s, failed imports, duplicate definitions. The diagnostic
61
+ goes to **stderr and the hook exits 2**, which feeds it back to the agent
62
+ (see "the exit-2 exception" below), plus the Copilot `decision` JSON.
63
+ - **Unresolved names** — `KeywordNotFound`, `VariableNotFound`. Reported as
64
+ advisory `additionalContext` (exit 0), because the agent may be about to
65
+ write that keyword or variable in another file. The file is recorded as
66
+ pending; if the name still doesn't resolve when the agent stops, the Stop
67
+ re-check blocks (below).
68
+ - Each list shows at most 5 diagnostics plus "… N more omitted."
69
+ - robotcode missing, a timeout (20 s), unparsable JSON or "0 files analyzed"
70
+ makes the tier silent — a tool failure is never a finding.
71
+ - robotcode keeps its analysis cache in `.robotcode_cache/` in the project
72
+ (the RobotCode VS Code extension uses the same folder; the rf-setup
73
+ `.gitignore` example lists it). With a warm cache the check takes under a
74
+ second; disabling the cache would make every edit take ~4 s.
75
+ - **Tier 1 — deprecations: one Robocop pass, classified by rule ID.** Runs
76
+ `robocop check --no-cache` once, with the **project's configured rule set**
77
+ and a parsable issue format
78
+ (`-c print_issues.output_format=simple --issue-format '{severity}|{rule_id}|{source}:{line}:{col}|{desc}'`),
79
+ in parallel with tier 0. Robocop's own error findings are left to tier 0;
80
+ style rules such as `DOC03` are dropped:
81
+ - **Hard deprecations** — `DEPR03` `WITH NAME`, `DEPR04` singular section
82
+ headers, `DEPR07` `Force/Default Tags`, `DEPR08` `Run Keyword If/Unless`,
83
+ `DEPR09` loop-exit keywords, `DEPR10` `Return From Keyword*`, `DEPR11`
84
+ `[Return]`.
85
+ - **Modernization hints** — `DEPR05` `Set Test/Suite/Global Variable` →
86
+ `VAR`, `DEPR06` `Create List/Dictionary` → `VAR`, and any other `DEPR` rule.
87
+
88
+ **Deprecations only warn.** They are reported as non-blocking
89
+ `additionalContext` (exit 0) and never cause exit 2 — not even a hard
90
+ deprecation on a line the current edit wrote. Classification uses the rule
91
+ ID, not the severity (`DEPR11` is W in Robocop 8.2 and I in 9.1).
92
+ - **Touched lines** are listed individually, hard deprecations first, each
93
+ with file, line and the modern replacement (`WARN DEPR08 x.robot:12 —
94
+ Run Keyword If → use IF/ELSE/END`). Touched lines come from
95
+ `tool_response.structuredPatch` (the `+` lines of each hunk), else the
96
+ lines where an Edit's `new_string` now occurs, else the whole file (Write
97
+ create). Deprecations on other lines are summarized as a count per rule.
98
+ - **Cap:** at most 10 listed findings plus "N more omitted", at most 2,000
99
+ characters.
100
+ - **Dedupe:** a finding listed once in a session (`session_id`; key = file,
101
+ rule and trimmed line text) is only counted afterwards. The marker is
102
+ `<tmpdir>/rf-agentskills-depr-<session_id>.json`; if it cannot be written,
103
+ only the dedupe is lost. When an error exits 2, the deprecation warnings are
104
+ neither written nor recorded, so they appear on the next clean edit.
105
+ - Robocop's gating by Robot Framework version applies (a project on RF 6.1
106
+ gets no `VAR` hint), and so does the project's Robocop config.
107
+ - If Robocop is missing, times out (10 s), or prints nothing parsable while
108
+ failing, the tier is silent — a tool failure is never a finding.
109
+ - **Tier 2 — formatting drift (opt-in):** with `RF_AGENTSKILLS_FORMAT_CHECK=1`,
110
+ runs `robocop format --no-cache --check --diff`. Purely informational —
111
+ surfaces the proposed reformat as `additionalContext` (exit 0). Formatting
112
+ differences **never** cause exit 2. Off by default: shown a diff, the agent
113
+ reformats and re-checks a file that is otherwise correct, which cost one to
114
+ three turns per written file in the evals.
115
+ - **Opt-in per-file dry run:** with `RF_AGENTSKILLS_FILE_DRYRUN=1`, a written
116
+ `.robot` suite (not `.resource`, not `__init__.robot`) is also run through
117
+ `robotcode robot --dryrun --output NONE --report NONE --log NONE` from the
118
+ project directory (20 s timeout), so the project's `robot.toml` and profiles
119
+ apply (python-path, variables), as in the other tiers. Without robotcode the
120
+ dry run is skipped. `[ ERROR ]` lines and failures such as "No keyword
121
+ with name" are reported as advisory context, capped like the deprecation
122
+ warnings. It is off by default: a dry run imports libraries (import-time side
123
+ effects, seconds for Browser/Selenium), and a keyword the agent writes next
124
+ looks missing until it exists.
125
+
126
+ Advisory output (deprecations, formatting, dry run) is emitted only when no
127
+ exit-2 error diagnostic is written. Robocop is always called with
128
+ `--no-cache`, so no `.robocop_cache/` directory is left in your project.
129
+
130
+ #### Environment variables
131
+
132
+ | Variable | Values | Effect |
133
+ |---|---|---|
134
+ | `RF_AGENTSKILLS_DEPRECATION_CHECK` | `warn` (default), `off` | `off` drops all deprecation output. Any other value is treated as `warn`; no value makes a deprecation block (exit 2), and the variable never affects error findings. |
135
+ | `RF_AGENTSKILLS_FILE_DRYRUN` | unset (default), `1`/`true`/`yes`/`on` | Enables the per-file dry run above. |
136
+ | `RF_AGENTSKILLS_FORMAT_CHECK` | unset (default), `1`/`true`/`yes`/`on` | Enables the formatting-drift tier above. |
137
+ | `RF_AGENTSKILLS_PROJECT_VALIDATION` | unset (default), `1`/`true`/`yes`/`on` | Enables the project-wide Stop tier below. |
138
+
139
+ #### Opting out per rule
140
+
141
+ Teams that keep a legacy construct on purpose ignore the rule in their Robocop
142
+ config; the hook reads the project's config automatically:
143
+
144
+ ```toml
145
+ # pyproject.toml
146
+ [tool.robocop.lint]
147
+ ignore = ["DEPR08"]
148
+ ```
149
+
150
+ **Selecting several rule groups on the command line:** repeat the option —
151
+ `robocop check --select "DEPR*" --select "ERR*"`. A comma list
152
+ (`--select 'DEPR*,ERR*'`) matches **no** rule in Robocop 8.2 and 9.1: Robocop
153
+ prints a warning, reports "No issues found" and exits 0.
154
+
155
+ This replaced an earlier `robot.api.get_model` check that was effectively a
156
+ no-op: `get_model` is a lenient tokenizer that returns "OK" for unterminated
157
+ `FOR` loops, undefined keywords, missing imports — even for a file of random
158
+ prose. It never raised, so it never caught anything. (It also read the
159
+ edited path from a `TOOL_INPUT` env var; the documented contract delivers it
160
+ as `tool_input.file_path` on stdin, so the new script reads stdin first and
161
+ treats `TOOL_INPUT` only as a legacy fallback.)
162
+
163
+ ### Errors the agent never saw — re-checked at Stop (`report_pending_errors.mjs`)
164
+
165
+ VS Code 1.142's Local agent harness sends the next model request without
166
+ waiting for `PostToolUse` hooks, so a validation error shows up only as the
167
+ banner "A hook prevented chat from continuing" and the model never sees it.
168
+ (An OpenTelemetry capture showed the next request leaving 41 ms after
169
+ `validate_robot.mjs` started; the hook takes about 0.7 s.) VS Code does wait
170
+ for `Stop` hooks, so:
171
+
172
+ - `validate_robot.mjs` records each file with blocking errors or unresolved
173
+ names in `<tmpdir>/rf-agentskills-pending-<session_id>.json`, and removes it
174
+ when a later validation of the file is clean.
175
+ - At `Stop`, `report_pending_errors.mjs` re-validates the recorded files (by
176
+ running `validate_robot.mjs` on each with `RF_AGENTSKILLS_STOP_RECHECK=1`,
177
+ which makes unresolved names blocking and skips the advisory tiers). So a
178
+ keyword the agent called but never defined blocks here, while one it defined
179
+ in a later edit of another file clears. If any file still fails, it blocks with the
180
+ same contract as `validate_robot.mjs`: stderr + exit 2 (Claude Code, Codex,
181
+ VS Code), plus `{"decision": "block", "reason": ...}` on stdout (Copilot). The
182
+ agent then gets one more turn to fix them.
183
+ - Deleted files are dropped. Each content version of a file is reported at most
184
+ once, so a file the agent can't fix doesn't block every later turn. Like every
185
+ Stop hook here, it is a no-op when `stop_hook_active` is set.
186
+
187
+ In agents whose `PostToolUse` feedback reaches the model, the agent normally
188
+ fixes the file right after the edit, which clears the record, and this hook
189
+ stays silent. Without a `session_id` nothing is recorded.
190
+
191
+ ### Tier 3 — whole project, end of task, opt-in (`validate_robot_project.mjs`)
192
+
193
+ Fires from `Stop`, **only when `RF_AGENTSKILLS_PROJECT_VALIDATION` is set**
194
+ to a truthy value (`1`/`true`/`yes`/`on`). Runs one cross-file check that
195
+ only makes sense once the whole project is on disk:
196
+ `robotcode --format json analyze code --collect-unused` from the project root.
197
+ It reads `robot.toml`, and reports every error-severity diagnostic (unresolved
198
+ keywords and variables, broken imports, argument errors) and every unused
199
+ keyword and variable (`KeywordNotUsed`, `VariableNotUsed`), at most 20 of each.
200
+ The JSON is parsed; robotcode's bitmask exit code is not used.
201
+
202
+ It is **off by default** for two reasons: (1) the analysis *loads the
203
+ project's libraries* to read their keywords, which runs their import-time
204
+ code; and (2) it scales with project size. Running them per-save would also false-alarm
205
+ constantly — a keyword you just wrote looks "unused" until something calls
206
+ it; a call into a not-yet-written resource looks "undefined". Deferring to
207
+ `Stop` (end of turn) avoids that. When findings exist the hook exits 2 so the
208
+ agent gets one more turn to fix before the turn ends.
209
+
210
+ ### The exit-2 exception
211
+
212
+ The validation scripts (`validate_robot.mjs`, `report_pending_errors.mjs`,
213
+ `validate_robot_project.mjs`) are the **deliberate exception** to authoring
214
+ guideline #2 below ("hook scripts must always exit 0"). The Claude Code
215
+ `PostToolUse`/`Stop` contract feeds a hook's stderr back to the agent only on
216
+ **exit 2** (exit 1 / other is shown to the user, not the model). Returning a
217
+ real error to the model is the entire point of validation — the
218
+ edit→validate→feed-back→self-correct loop. So they exit 2 *specifically and
219
+ only* on a confirmed Robot Framework error, and exit 0 in every other case
220
+ (tool missing, tool timeout or unparsable output, non-Robot file, no
221
+ findings, formatting-only difference, deprecation findings of any class).
222
+
223
+ ## How `rf_error_hints.mjs` decides
224
+
225
+ After every Bash command it scans the output (first 20 000 characters) for Robot Framework error messages. The first time each kind appears in a session, it injects one hint of at most 400 characters, naming the skill to load and the fix:
226
+
227
+ | Error message | Hint |
228
+ |---|---|
229
+ | `No keyword with name '…' found` | embedded arguments (`Select team ${city} ${team:\S+}`; text between arguments is literal), rf-language; exact names via `robotcode doc keywords <Library> <pattern>` |
230
+ | `Multiple keywords with name '…' found` | qualify the call or use `Set Library Search Order` (rf-language) |
231
+ | `Invalid argument syntax '…'` | typed arguments `${count: int}` need RF 7.3+ (rf-language) |
232
+ | `Resolving variable '…' failed` | scope, import order, `$var` in expressions (rf-language) |
233
+ | `Importing library '…' failed` | install into the project environment (rf-setup) |
234
+
235
+ It never blocks. It always exits 0, and unrelated or malformed input produces no output.
236
+
237
+ ## Python interpreter resolution
238
+
239
+ `validate_robot.mjs`, `validate_robot_project.mjs`, and
240
+ `check_rf_environment.mjs` run Robot Framework tooling (`robotcode`,
241
+ `robocop`, `robotcode robot --dryrun`, `import robot` for the version probe). They share
242
+ `scripts/_python_env.mjs`, which takes the first environment that has the
243
+ needed tool, in this order (for robotcode, the `robotcode` executable in that
244
+ environment's `bin/` or `Scripts\` — robotcode has no `python -m` entry point):
245
+
246
+ 1. the active virtual environment (`$VIRTUAL_ENV`);
247
+ 2. the project's `.venv` under the event's `cwd`
248
+ (`.venv/bin/python`, on Windows `.venv\Scripts\python.exe`);
249
+ 3. the installer-recorded interpreter in `scripts/python_runtime.json`
250
+ (written from `sys.executable`; needed for pipx / uv tool installs);
251
+ 4. `python3`, then `python` on `PATH`.
252
+
253
+ The project environment wins so that robotcode and Robocop see the project's
254
+ libraries and Robot Framework version (version-gated rules such as the `VAR` hint follow it). If
255
+ the project environment has no Robocop, the search falls through to the
256
+ installer's interpreter, whose RF version may differ — a few version-gated
257
+ hints can then be off. The hooks never start `uv run` or another package
258
+ manager: that can create environments, sync dependencies or reach the network.
259
+ If no candidate has the required tool, the hooks exit silently — they're
260
+ non-blocking by design.
261
+
262
+ ## Why two of these are conditional
263
+
264
+ The first version of this plugin used `type: "prompt"` for
265
+ `UserPromptSubmit` and `Stop` — Claude Code's way of statically
266
+ prepending a system note to the conversation. The text was:
267
+
268
+ > If this request involves Robot Framework test automation, load the
269
+ > relevant skill's SKILL.md before responding...
270
+
271
+ That seems harmless, but in headless evals against haiku-4-5 it caused
272
+ non-RF prompts to no-op: the model read the static injection as a gate
273
+ ("is this RF?" → "no" → "task done") rather than as guidance. The eval
274
+ task `narrow-non-rf-control-01` (a plain JSON-authoring prompt) caught
275
+ this regression in CI run `25057802426` — see
276
+ `docs/archive/hooks-fix-proposal.md` for the full diagnosis.
277
+
278
+ Switching both hooks to `type: "command"` lets a small script inspect
279
+ the prompt / session and only inject context when there's a genuine
280
+ Robot Framework signal. Non-RF sessions are unaffected.
281
+
282
+ ## How `maybe_inject_rf_context.mjs` decides
283
+
284
+ - Reads the Claude Code `UserPromptSubmit` event JSON on stdin.
285
+ - Extracts `.prompt` (the user's text). If empty / missing, exits 0
286
+ silently.
287
+ - Tests the prompt against a case-insensitive regex covering:
288
+ - direct mentions: `robot framework`, `robot-framework`
289
+ - file extensions: `.robot`, `.resource`
290
+ - Robot Framework libraries: `SeleniumLibrary`, `BrowserLibrary`,
291
+ `AppiumLibrary`, `RequestsLibrary`, `RESTinstance`, `PlatynUI`, plus
292
+ space-separated forms (`Browser Library`, etc.)
293
+ - skill ids: `rf-language`, `rf-python-library`, `rf-setup` (rf-core);
294
+ `rf-browser`, `rf-selenium` (rf-web); `rf-requests`, `rf-restinstance` (rf-api);
295
+ `rf-appium` (rf-mobile); `rf-platynui` (rf-desktop)
296
+ - rf-core subagent ids: `rf-test-architect`, `rf-debug-expert`,
297
+ `rf-migration-guide`
298
+ - RF section headers pasted into the prompt: `*** Settings ***`,
299
+ `*** Variables ***`, `*** Test Cases ***`, `*** Tasks ***`,
300
+ `*** Keywords ***`, `*** Comments ***`
301
+ - tooling: `libdoc`, `robotidy`, `robocop`, `rfbrowser`, `robotcode`,
302
+ `robot-debug`, `robot.toml`; Python library API terms (`@keyword`,
303
+ `robot.api.deco`, `ROBOT_LIBRARY_*`, "robot listener")
304
+ - On match: emits one `{"hookSpecificOutput": {"hookEventName":
305
+ "UserPromptSubmit", "additionalContext": "..."}}` with a routing text of
306
+ at most 450 characters (about 80 tokens): tests, suites, keywords,
307
+ resources and variables → `rf-language`; Python libraries and listeners →
308
+ `rf-python-library`; installs → `rf-setup`; library usage → the
309
+ library's own skill, unnamed, and, when it is missing, a suggestion to
310
+ install its plugin (`rf-web`, `rf-api`, `rf-mobile`, `rf-desktop`);
311
+ keyword names and arguments → `robotcode doc keyword`, not memory; run
312
+ results → `robotcode results`, not `output.xml`; and a closing reminder to write RF 7 syntax (`RETURN`, `VAR`,
313
+ `IF`, `Test Tags`). Skill descriptions and subagents are already listed
314
+ by Claude Code, so the text only says which one to use when.
315
+ - On miss: stdout stays empty.
316
+
317
+ Deliberately **not** matched: bare `RF` (too ambiguous), bare `test`
318
+ (too generic), bare `library` / `keyword` / `listener`. The parametrised
319
+ cases in `tests/test_hook_scripts.py` lock in the positive trigger list,
320
+ the negative miss list, the budget and that every `rf-*` name in the text
321
+ is a shipped skill or subagent.
322
+
323
+ ## What `check_rf_environment.mjs` reports
324
+
325
+ At `SessionStart` it reports the Robot Framework version and interpreter
326
+ (same resolution as above, from the event's `cwd`), the robotcode version —
327
+ without robotcode (or below 2.8) the error check on edit is disabled, and it
328
+ names the robotcode plugin as the recommended companion — whether Robocop is
329
+ available (deprecation and formatting advice), and which library packages are
330
+ importable. For missing packages it shows project-environment commands
331
+ (`uv add …`, `uv add --dev "robotcode[all]"`) and points to the rf-setup skill; it never
332
+ recommends `pip install` or a library's post-install step. A missing, empty or malformed
333
+ event produces no output; it always exits 0.
334
+
335
+ ## How `maybe_remind_robot_tests.mjs` decides
336
+
337
+ - Reads the Claude Code `Stop` event JSON on stdin.
338
+ - Extracts `.transcript_path` (path to the session JSONL). If missing
339
+ or unreadable, exits 0.
340
+ - Scans the transcript in 64 KB chunks for `"file_path": "…something.robot"`
341
+ or `"…something.resource"` (with bounded regex — `notes.robotic.md`
342
+ does not count). Streaming chunking keeps memory bounded on
343
+ long sessions.
344
+ - Also notes the last Bash `"command"` that runs Robot Framework (`robot`,
345
+ `python -m robot`, `robotcode … robot`, dry runs included). If that run
346
+ comes after the last `.robot`/`.resource` file path, the session already
347
+ ran its suite and the hook exits without output.
348
+ - On hit: emits `additionalContext` reminding the user to run
349
+ the affected tests where they can run (`uv run robotcode robot -bl "<longname>"`), read the
350
+ results with `uv run robotcode results summary --failed`, and open
351
+ `results/report.html`.
352
+ - On miss: stdout stays empty.
353
+
354
+ ## Verifying the hooks fire
355
+
356
+ Two patterns work, depending on what you can inspect:
357
+
358
+ ### Inspect side effects (most reliable)
359
+
360
+ `stream-json` from `claude -p` includes
361
+ `hook_started/progress/response` events for `SessionStart` but **not**
362
+ for the other event types. To verify `PostToolUse` /
363
+ `UserPromptSubmit` / `Stop` fired, instrument the script itself:
364
+
365
+ ```javascript
366
+ // Prepend to any hook script for ad-hoc tracing:
367
+ import { appendFileSync } from "node:fs";
368
+ appendFileSync(`${process.cwd()}/.hook-trace.log`,
369
+ `[${new Date().toISOString()}] hook fired\n`);
370
+ ```
371
+
372
+ Then check `.hook-trace.log` after the session. The `rf-skill-eval`
373
+ harness exposes the workspace as `process.cwd()` for the hook
374
+ subprocess, so this works under CI as well as in interactive use.
375
+
376
+ ### Run the unit tests
377
+
378
+ `tests/test_hook_scripts.py` invokes each `.mjs` script via `node` as a
379
+ subprocess with synthetic stdin payloads and asserts on the
380
+ (stdout, exit-code) pair. No live Claude session needed:
381
+
382
+ ```bash
383
+ uv run pytest plugins/rf-core/tests/test_hook_scripts.py -v
384
+ ```
385
+
386
+ Parametrised cases covering positive triggers, negative misses,
387
+ malformed input, and pathological transcripts.
388
+
389
+ ## Running the eval suite
390
+
391
+ The `rf-skill-eval` harness includes two paired tasks for the
392
+ conditional injection:
393
+
394
+ - `eval/tasks/narrow/narrow-rf-injection-positive-01.yaml` — RF
395
+ prompt, expects the agent to leverage a robotcode lookup.
396
+ - `eval/tasks/narrow/narrow-non-rf-control-01.yaml` — non-RF prompt,
397
+ expects the agent to write a plain JSON file with no rf tooling.
398
+
399
+ Both should pass green after this hooks fix. Run with:
400
+
401
+ ```bash
402
+ uv run rf-skill-eval run \
403
+ --task eval/tasks/narrow/narrow-rf-injection-positive-01.yaml \
404
+ --output eval/runs/local-probe \
405
+ --profile treatment
406
+ ```
407
+
408
+ ## Authoring guidelines for new hooks in this plugin
409
+
410
+ 1. **Default to conditional injection.** Static `type: "prompt"`
411
+ hooks bias the model on every turn — fine for project-specific
412
+ plugins where the user opted in, lethal for general-purpose
413
+ plugins like this one.
414
+ 2. **Hook scripts must always exit 0** — *unless* they are intentional
415
+ validation hooks. A stray non-zero exit is interpreted as a hook
416
+ error and surfaced to the user, so wrap risky work in
417
+ `try { … } catch { process.exit(0) }`. The sole deliberate exception
418
+ is the validation tier (`validate_robot.mjs`,
419
+ `validate_robot_project.mjs`), which exits **2** on a confirmed Robot
420
+ Framework error to feed the diagnostic back to the agent — and still
421
+ exits 0 in every non-error path (see "the exit-2 exception" above).
422
+ 3. **Stop/SubagentStop hooks MUST short-circuit on `stop_hook_active`.**
423
+ Add `if (event?.stop_hook_active) process.exit(0)` immediately after
424
+ parsing the event. Claude Code sets this flag when a Stop fires as a
425
+ continuation of a previous Stop-hook block; without the guard a hook
426
+ that emits any model-facing output re-fires every time and traps the
427
+ session until `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` (default 9) overrides.
428
+ **Note the trap in guideline #2:** for Stop hooks, *exit 0 is not
429
+ sufficient to be non-blocking* — model-facing output (`additionalContext`
430
+ **or** exit 2) re-invokes the model. `maybe_remind_robot_tests.mjs` once
431
+ looped exactly this way (exit 0 + `additionalContext`, no guard); it now
432
+ short-circuits on `stop_hook_active` and additionally reminds at most once
433
+ per `session_id`.
434
+ 4. **Stay Node-only when possible.** Shelling out to other runtimes
435
+ (Python, bash) reintroduces the install-time dependency surface
436
+ the Node migration eliminated. If a hook genuinely needs Python
437
+ (Robot Framework parsing), resolve the interpreter with
438
+ `scripts/_python_env.mjs` (project env, then `python_runtime.json`),
439
+ not bare `python` on PATH, and give every spawned process a timeout
440
+ (`spawnOptions(...)`).
441
+ 5. **Keep the regex tight.** Adding a trigger that looks ergonomic
442
+ ("test", "library") is a fast way to revive the
443
+ `narrow-non-rf-control-01` regression. The unit-test parameter
444
+ list is the canonical specification of what does and doesn't
445
+ trigger; update it deliberately.