robotframework-plugins 2026.11.0.dev1__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 (195) 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 +110 -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/authentication.md +58 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +119 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  31. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  32. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +11 -0
  33. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  34. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +104 -0
  35. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  36. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  37. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  38. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +435 -0
  39. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  40. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  41. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  42. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +108 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +509 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  50. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  51. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  52. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  108. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +103 -0
  109. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  110. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +107 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  115. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  116. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +9 -0
  117. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +266 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  128. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  129. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  130. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  143. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  144. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  145. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  146. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  147. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +132 -0
  148. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  149. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  172. robotframework_plugins/_assets.py +120 -0
  173. robotframework_plugins/_catalog.py +123 -0
  174. robotframework_plugins/_snapshot.py +230 -0
  175. robotframework_plugins/adapters/__init__.py +53 -0
  176. robotframework_plugins/adapters/_base.py +400 -0
  177. robotframework_plugins/adapters/claude_code.py +312 -0
  178. robotframework_plugins/adapters/claude_desktop.py +129 -0
  179. robotframework_plugins/adapters/codex.py +276 -0
  180. robotframework_plugins/adapters/copilot.py +87 -0
  181. robotframework_plugins/adapters/cursor.py +295 -0
  182. robotframework_plugins/adapters/goose.py +240 -0
  183. robotframework_plugins/adapters/opencode.py +170 -0
  184. robotframework_plugins/bundle.py +85 -0
  185. robotframework_plugins/cli.py +1311 -0
  186. robotframework_plugins/detect.py +121 -0
  187. robotframework_plugins/manifest.py +338 -0
  188. robotframework_plugins/py.typed +0 -0
  189. robotframework_plugins/skillzip.py +39 -0
  190. robotframework_plugins/transforms.py +725 -0
  191. robotframework_plugins-2026.11.0.dev1.dist-info/METADATA +178 -0
  192. robotframework_plugins-2026.11.0.dev1.dist-info/RECORD +195 -0
  193. robotframework_plugins-2026.11.0.dev1.dist-info/WHEEL +4 -0
  194. robotframework_plugins-2026.11.0.dev1.dist-info/entry_points.txt +2 -0
  195. robotframework_plugins-2026.11.0.dev1.dist-info/licenses/LICENSE +201 -0
@@ -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,435 @@
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`, Robocop check and format run in parallel); 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:** runs `robocop format --no-cache --check --diff`.
110
+ Purely informational — surfaces the proposed reformat as `additionalContext`
111
+ (exit 0). Formatting differences **never** cause exit 2.
112
+ - **Opt-in per-file dry run:** with `RF_AGENTSKILLS_FILE_DRYRUN=1`, a written
113
+ `.robot` suite (not `.resource`, not `__init__.robot`) is also run through
114
+ `robot --dryrun --output NONE --report NONE --log NONE` from the project
115
+ directory (20 s timeout). `[ ERROR ]` lines and failures such as "No keyword
116
+ with name" are reported as advisory context, capped like the deprecation
117
+ warnings. It is off by default: a dry run imports libraries (import-time side
118
+ effects, seconds for Browser/Selenium), and a keyword the agent writes next
119
+ looks missing until it exists.
120
+
121
+ Advisory output (deprecations, formatting, dry run) is emitted only when no
122
+ exit-2 error diagnostic is written. Robocop is always called with
123
+ `--no-cache`, so no `.robocop_cache/` directory is left in your project.
124
+
125
+ #### Environment variables
126
+
127
+ | Variable | Values | Effect |
128
+ |---|---|---|
129
+ | `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. |
130
+ | `RF_AGENTSKILLS_FILE_DRYRUN` | unset (default), `1`/`true`/`yes`/`on` | Enables the per-file dry run above. |
131
+ | `RF_AGENTSKILLS_PROJECT_VALIDATION` | unset (default), `1`/`true`/`yes`/`on` | Enables the project-wide Stop tier below. |
132
+
133
+ #### Opting out per rule
134
+
135
+ Teams that keep a legacy construct on purpose ignore the rule in their Robocop
136
+ config; the hook reads the project's config automatically:
137
+
138
+ ```toml
139
+ # pyproject.toml
140
+ [tool.robocop.lint]
141
+ ignore = ["DEPR08"]
142
+ ```
143
+
144
+ **Selecting several rule groups on the command line:** repeat the option —
145
+ `robocop check --select "DEPR*" --select "ERR*"`. A comma list
146
+ (`--select 'DEPR*,ERR*'`) matches **no** rule in Robocop 8.2 and 9.1: Robocop
147
+ prints a warning, reports "No issues found" and exits 0.
148
+
149
+ This replaced an earlier `robot.api.get_model` check that was effectively a
150
+ no-op: `get_model` is a lenient tokenizer that returns "OK" for unterminated
151
+ `FOR` loops, undefined keywords, missing imports — even for a file of random
152
+ prose. It never raised, so it never caught anything. (It also read the
153
+ edited path from a `TOOL_INPUT` env var; the documented contract delivers it
154
+ as `tool_input.file_path` on stdin, so the new script reads stdin first and
155
+ treats `TOOL_INPUT` only as a legacy fallback.)
156
+
157
+ ### Errors the agent never saw — re-checked at Stop (`report_pending_errors.mjs`)
158
+
159
+ VS Code 1.142's Local agent harness sends the next model request without
160
+ waiting for `PostToolUse` hooks, so a validation error shows up only as the
161
+ banner "A hook prevented chat from continuing" and the model never sees it.
162
+ (An OpenTelemetry capture showed the next request leaving 41 ms after
163
+ `validate_robot.mjs` started; the hook takes about 0.7 s.) VS Code does wait
164
+ for `Stop` hooks, so:
165
+
166
+ - `validate_robot.mjs` records each file with blocking errors or unresolved
167
+ names in `<tmpdir>/rf-agentskills-pending-<session_id>.json`, and removes it
168
+ when a later validation of the file is clean.
169
+ - At `Stop`, `report_pending_errors.mjs` re-validates the recorded files (by
170
+ running `validate_robot.mjs` on each with `RF_AGENTSKILLS_STOP_RECHECK=1`,
171
+ which makes unresolved names blocking and skips the advisory tiers). So a
172
+ keyword the agent called but never defined blocks here, while one it defined
173
+ in a later edit of another file clears. If any file still fails, it blocks with the
174
+ same contract as `validate_robot.mjs`: stderr + exit 2 (Claude Code, Codex,
175
+ VS Code), plus `{"decision": "block", "reason": ...}` on stdout (Copilot). The
176
+ agent then gets one more turn to fix them.
177
+ - Deleted files are dropped. Each content version of a file is reported at most
178
+ once, so a file the agent can't fix doesn't block every later turn. Like every
179
+ Stop hook here, it is a no-op when `stop_hook_active` is set.
180
+
181
+ In agents whose `PostToolUse` feedback reaches the model, the agent normally
182
+ fixes the file right after the edit, which clears the record, and this hook
183
+ stays silent. Without a `session_id` nothing is recorded.
184
+
185
+ ### Tier 3 — whole project, end of task, opt-in (`validate_robot_project.mjs`)
186
+
187
+ Fires from `Stop`, **only when `RF_AGENTSKILLS_PROJECT_VALIDATION` is set**
188
+ to a truthy value (`1`/`true`/`yes`/`on`). Runs one cross-file check that
189
+ only makes sense once the whole project is on disk:
190
+ `robotcode --format json analyze code --collect-unused` from the project root.
191
+ It reads `robot.toml`, and reports every error-severity diagnostic (unresolved
192
+ keywords and variables, broken imports, argument errors) and every unused
193
+ keyword and variable (`KeywordNotUsed`, `VariableNotUsed`), at most 20 of each.
194
+ The JSON is parsed; robotcode's bitmask exit code is not used.
195
+
196
+ It is **off by default** for two reasons: (1) the analysis *loads the
197
+ project's libraries* to read their keywords, which runs their import-time
198
+ code; and (2) it scales with project size. Running them per-save would also false-alarm
199
+ constantly — a keyword you just wrote looks "unused" until something calls
200
+ it; a call into a not-yet-written resource looks "undefined". Deferring to
201
+ `Stop` (end of turn) avoids that. When findings exist the hook exits 2 so the
202
+ agent gets one more turn to fix before the turn ends.
203
+
204
+ ### The exit-2 exception
205
+
206
+ The validation scripts (`validate_robot.mjs`, `report_pending_errors.mjs`,
207
+ `validate_robot_project.mjs`) are the **deliberate exception** to authoring
208
+ guideline #2 below ("hook scripts must always exit 0"). The Claude Code
209
+ `PostToolUse`/`Stop` contract feeds a hook's stderr back to the agent only on
210
+ **exit 2** (exit 1 / other is shown to the user, not the model). Returning a
211
+ real error to the model is the entire point of validation — the
212
+ edit→validate→feed-back→self-correct loop. So they exit 2 *specifically and
213
+ only* on a confirmed Robot Framework error, and exit 0 in every other case
214
+ (tool missing, tool timeout or unparsable output, non-Robot file, no
215
+ findings, formatting-only difference, deprecation findings of any class).
216
+
217
+ ## How `rf_error_hints.mjs` decides
218
+
219
+ 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:
220
+
221
+ | Error message | Hint |
222
+ |---|---|
223
+ | `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>` |
224
+ | `Multiple keywords with name '…' found` | qualify the call or use `Set Library Search Order` (rf-language) |
225
+ | `Invalid argument syntax '…'` | typed arguments `${count: int}` need RF 7.3+ (rf-language) |
226
+ | `Resolving variable '…' failed` | scope, import order, `$var` in expressions (rf-language) |
227
+ | `Importing library '…' failed` | install into the project environment (rf-setup) |
228
+
229
+ It never blocks. It always exits 0, and unrelated or malformed input produces no output.
230
+
231
+ ## Python interpreter resolution
232
+
233
+ `validate_robot.mjs`, `validate_robot_project.mjs`, and
234
+ `check_rf_environment.mjs` run Robot Framework tooling (`robotcode`,
235
+ `robocop`, `robot --dryrun`, `import robot` for the version probe). They share
236
+ `scripts/_python_env.mjs`, which takes the first environment that has the
237
+ needed tool, in this order (for robotcode, the `robotcode` executable in that
238
+ environment's `bin/` or `Scripts\` — robotcode has no `python -m` entry point):
239
+
240
+ 1. the active virtual environment (`$VIRTUAL_ENV`);
241
+ 2. the project's `.venv` under the event's `cwd`
242
+ (`.venv/bin/python`, on Windows `.venv\Scripts\python.exe`);
243
+ 3. the installer-recorded interpreter in `scripts/python_runtime.json`
244
+ (written from `sys.executable`; needed for pipx / uv tool installs);
245
+ 4. `python3`, then `python` on `PATH`.
246
+
247
+ The project environment wins so that robotcode and Robocop see the project's
248
+ libraries and Robot Framework version (version-gated rules such as the `VAR` hint follow it). If
249
+ the project environment has no Robocop, the search falls through to the
250
+ installer's interpreter, whose RF version may differ — a few version-gated
251
+ hints can then be off. The hooks never start `uv run` or another package
252
+ manager: that can create environments, sync dependencies or reach the network.
253
+ If no candidate has the required tool, the hooks exit silently — they're
254
+ non-blocking by design.
255
+
256
+ ## Why two of these are conditional
257
+
258
+ The first version of this plugin used `type: "prompt"` for
259
+ `UserPromptSubmit` and `Stop` — Claude Code's way of statically
260
+ prepending a system note to the conversation. The text was:
261
+
262
+ > If this request involves Robot Framework test automation, load the
263
+ > relevant skill's SKILL.md before responding...
264
+
265
+ That seems harmless, but in headless evals against haiku-4-5 it caused
266
+ non-RF prompts to no-op: the model read the static injection as a gate
267
+ ("is this RF?" → "no" → "task done") rather than as guidance. The eval
268
+ task `narrow-non-rf-control-01` (a plain JSON-authoring prompt) caught
269
+ this regression in CI run `25057802426` — see
270
+ `docs/plugin/hooks-fix-proposal.md` for the full diagnosis.
271
+
272
+ Switching both hooks to `type: "command"` lets a small script inspect
273
+ the prompt / session and only inject context when there's a genuine
274
+ Robot Framework signal. Non-RF sessions are unaffected.
275
+
276
+ ## How `maybe_inject_rf_context.mjs` decides
277
+
278
+ - Reads the Claude Code `UserPromptSubmit` event JSON on stdin.
279
+ - Extracts `.prompt` (the user's text). If empty / missing, exits 0
280
+ silently.
281
+ - Tests the prompt against a case-insensitive regex covering:
282
+ - direct mentions: `robot framework`, `robot-framework`
283
+ - file extensions: `.robot`, `.resource`
284
+ - Robot Framework libraries: `SeleniumLibrary`, `BrowserLibrary`,
285
+ `AppiumLibrary`, `RequestsLibrary`, `RESTinstance`, `PlatynUI`, plus
286
+ space-separated forms (`Browser Library`, etc.)
287
+ - skill ids: `rf-language`, `rf-python-library`, `rf-setup` (rf-core);
288
+ `rf-browser`, `rf-selenium` (rf-web); `rf-requests`, `rf-restinstance` (rf-api);
289
+ `rf-appium` (rf-mobile); `rf-platynui` (rf-desktop)
290
+ - rf-core subagent ids: `rf-test-architect`, `rf-debug-expert`,
291
+ `rf-migration-guide`
292
+ - RF section headers pasted into the prompt: `*** Settings ***`,
293
+ `*** Variables ***`, `*** Test Cases ***`, `*** Tasks ***`,
294
+ `*** Keywords ***`, `*** Comments ***`
295
+ - tooling: `libdoc`, `robotidy`, `robocop`, `rfbrowser`, `robotcode`,
296
+ `robot-debug`, `robot.toml`; Python library API terms (`@keyword`,
297
+ `robot.api.deco`, `ROBOT_LIBRARY_*`, "robot listener")
298
+ - On match: emits one `{"hookSpecificOutput": {"hookEventName":
299
+ "UserPromptSubmit", "additionalContext": "..."}}` with a routing text of
300
+ at most 450 characters (about 80 tokens): tests, suites, keywords,
301
+ resources and variables → `rf-language`; Python libraries and listeners →
302
+ `rf-python-library`; installs → `rf-setup`; library usage → the
303
+ library's own skill, unnamed, and, when it is missing, a suggestion to
304
+ install its plugin (`rf-web`, `rf-api`, `rf-mobile`, `rf-desktop`);
305
+ keyword names and arguments → `robotcode doc keyword`, not memory; run
306
+ results → `robotcode results`, not `output.xml`; and a closing reminder to write RF 7 syntax (`RETURN`, `VAR`,
307
+ `IF`, `Test Tags`). Skill descriptions and subagents are already listed
308
+ by Claude Code, so the text only says which one to use when.
309
+ - On miss: stdout stays empty.
310
+
311
+ Deliberately **not** matched: bare `RF` (too ambiguous), bare `test`
312
+ (too generic), bare `library` / `keyword` / `listener`. The parametrised
313
+ cases in `tests/test_hook_scripts.py` lock in the positive trigger list,
314
+ the negative miss list, the budget and that every `rf-*` name in the text
315
+ is a shipped skill or subagent.
316
+
317
+ ## What `check_rf_environment.mjs` reports
318
+
319
+ At `SessionStart` it reports the Robot Framework version and interpreter
320
+ (same resolution as above, from the event's `cwd`), the robotcode version —
321
+ without robotcode (or below 2.8) the error check on edit is disabled, and it
322
+ names the robotcode plugin as the recommended companion — whether Robocop is
323
+ available (deprecation and formatting advice), and which library packages are
324
+ importable. For missing packages it shows project-environment commands
325
+ (`uv add …`, `uv add --dev "robotcode[all]"`) and points to the rf-setup skill; it never
326
+ recommends `pip install` or a library's post-install step. A missing, empty or malformed
327
+ event produces no output; it always exits 0.
328
+
329
+ ## How `maybe_remind_robot_tests.mjs` decides
330
+
331
+ - Reads the Claude Code `Stop` event JSON on stdin.
332
+ - Extracts `.transcript_path` (path to the session JSONL). If missing
333
+ or unreadable, exits 0.
334
+ - Scans the transcript in 64 KB chunks for `"file_path": "…something.robot"`
335
+ or `"…something.resource"` (with bounded regex — `notes.robotic.md`
336
+ does not count). Streaming chunking keeps memory bounded on
337
+ long sessions.
338
+ - On hit: emits `additionalContext` reminding the user to run
339
+ the affected tests (`uv run robotcode robot -bl "<longname>"`), read the
340
+ results with `uv run robotcode results summary --failed`, and open
341
+ `results/report.html`.
342
+ - On miss: stdout stays empty.
343
+
344
+ ## Verifying the hooks fire
345
+
346
+ Two patterns work, depending on what you can inspect:
347
+
348
+ ### Inspect side effects (most reliable)
349
+
350
+ `stream-json` from `claude -p` includes
351
+ `hook_started/progress/response` events for `SessionStart` but **not**
352
+ for the other event types. To verify `PostToolUse` /
353
+ `UserPromptSubmit` / `Stop` fired, instrument the script itself:
354
+
355
+ ```javascript
356
+ // Prepend to any hook script for ad-hoc tracing:
357
+ import { appendFileSync } from "node:fs";
358
+ appendFileSync(`${process.cwd()}/.hook-trace.log`,
359
+ `[${new Date().toISOString()}] hook fired\n`);
360
+ ```
361
+
362
+ Then check `.hook-trace.log` after the session. The `rf-skill-eval`
363
+ harness exposes the workspace as `process.cwd()` for the hook
364
+ subprocess, so this works under CI as well as in interactive use.
365
+
366
+ ### Run the unit tests
367
+
368
+ `tests/test_hook_scripts.py` invokes each `.mjs` script via `node` as a
369
+ subprocess with synthetic stdin payloads and asserts on the
370
+ (stdout, exit-code) pair. No live Claude session needed:
371
+
372
+ ```bash
373
+ uv run pytest plugins/rf-agentskills/tests/test_hook_scripts.py -v
374
+ ```
375
+
376
+ Parametrised cases covering positive triggers, negative misses,
377
+ malformed input, and pathological transcripts.
378
+
379
+ ## Running the eval suite
380
+
381
+ The `rf-skill-eval` harness includes two paired tasks for the
382
+ conditional injection:
383
+
384
+ - `eval/tasks/narrow/narrow-rf-injection-positive-01.yaml` — RF
385
+ prompt, expects the agent to leverage a robotcode lookup.
386
+ - `eval/tasks/narrow/narrow-non-rf-control-01.yaml` — non-RF prompt,
387
+ expects the agent to write a plain JSON file with no rf tooling.
388
+
389
+ Both should pass green after this hooks fix. Run with:
390
+
391
+ ```bash
392
+ uv run rf-skill-eval run \
393
+ --task eval/tasks/narrow/narrow-rf-injection-positive-01.yaml \
394
+ --output eval/runs/local-probe \
395
+ --profile treatment
396
+ ```
397
+
398
+ ## Authoring guidelines for new hooks in this plugin
399
+
400
+ 1. **Default to conditional injection.** Static `type: "prompt"`
401
+ hooks bias the model on every turn — fine for project-specific
402
+ plugins where the user opted in, lethal for general-purpose
403
+ plugins like this one.
404
+ 2. **Hook scripts must always exit 0** — *unless* they are intentional
405
+ validation hooks. A stray non-zero exit is interpreted as a hook
406
+ error and surfaced to the user, so wrap risky work in
407
+ `try { … } catch { process.exit(0) }`. The sole deliberate exception
408
+ is the validation tier (`validate_robot.mjs`,
409
+ `validate_robot_project.mjs`), which exits **2** on a confirmed Robot
410
+ Framework error to feed the diagnostic back to the agent — and still
411
+ exits 0 in every non-error path (see "the exit-2 exception" above).
412
+ 3. **Stop/SubagentStop hooks MUST short-circuit on `stop_hook_active`.**
413
+ Add `if (event?.stop_hook_active) process.exit(0)` immediately after
414
+ parsing the event. Claude Code sets this flag when a Stop fires as a
415
+ continuation of a previous Stop-hook block; without the guard a hook
416
+ that emits any model-facing output re-fires every time and traps the
417
+ session until `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` (default 9) overrides.
418
+ **Note the trap in guideline #2:** for Stop hooks, *exit 0 is not
419
+ sufficient to be non-blocking* — model-facing output (`additionalContext`
420
+ **or** exit 2) re-invokes the model. `maybe_remind_robot_tests.mjs` once
421
+ looped exactly this way (exit 0 + `additionalContext`, no guard); it now
422
+ short-circuits on `stop_hook_active` and additionally reminds at most once
423
+ per `session_id`.
424
+ 4. **Stay Node-only when possible.** Shelling out to other runtimes
425
+ (Python, bash) reintroduces the install-time dependency surface
426
+ the Node migration eliminated. If a hook genuinely needs Python
427
+ (Robot Framework parsing), resolve the interpreter with
428
+ `scripts/_python_env.mjs` (project env, then `python_runtime.json`),
429
+ not bare `python` on PATH, and give every spawned process a timeout
430
+ (`spawnOptions(...)`).
431
+ 5. **Keep the regex tight.** Adding a trigger that looks ergonomic
432
+ ("test", "library") is a fast way to revive the
433
+ `narrow-non-rf-control-01` regression. The unit-test parameter
434
+ list is the canonical specification of what does and doesn't
435
+ trigger; update it deliberately.
@@ -0,0 +1,70 @@
1
+ {
2
+ "hooks": {
3
+ "PostToolUse": [
4
+ {
5
+ "matcher": "Write|Edit",
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/validate_robot.mjs\"",
10
+ "timeout": 60
11
+ }
12
+ ]
13
+ },
14
+ {
15
+ "matcher": "Bash",
16
+ "hooks": [
17
+ {
18
+ "type": "command",
19
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/rf_error_hints.mjs\"",
20
+ "timeout": 10
21
+ }
22
+ ]
23
+ }
24
+ ],
25
+ "UserPromptSubmit": [
26
+ {
27
+ "matcher": "",
28
+ "hooks": [
29
+ {
30
+ "type": "command",
31
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/maybe_inject_rf_context.mjs\"",
32
+ "timeout": 15
33
+ }
34
+ ]
35
+ }
36
+ ],
37
+ "SessionStart": [
38
+ {
39
+ "matcher": "",
40
+ "hooks": [
41
+ {
42
+ "type": "command",
43
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/check_rf_environment.mjs\"",
44
+ "timeout": 15
45
+ }
46
+ ]
47
+ }
48
+ ],
49
+ "Stop": [
50
+ {
51
+ "matcher": "",
52
+ "hooks": [
53
+ {
54
+ "type": "command",
55
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/report_pending_errors.mjs\"",
56
+ "timeout": 60
57
+ },
58
+ {
59
+ "type": "command",
60
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/maybe_remind_robot_tests.mjs\""
61
+ },
62
+ {
63
+ "type": "command",
64
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/validate_robot_project.mjs\""
65
+ }
66
+ ]
67
+ }
68
+ ]
69
+ }
70
+ }