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.
- robotframework_plugins/__init__.py +14 -0
- robotframework_plugins/_assets/catalog.json +143 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
- robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +110 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +119 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
- robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
- robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
- robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +11 -0
- robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +104 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
- robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
- robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
- robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +435 -0
- robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +108 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +509 -0
- robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
- robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +103 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +107 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
- robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
- robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
- robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
- robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +266 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
- robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
- robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
- robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
- robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
- robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
- robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
- robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
- robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
- robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +132 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
- robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
- robotframework_plugins/_assets.py +120 -0
- robotframework_plugins/_catalog.py +123 -0
- robotframework_plugins/_snapshot.py +230 -0
- robotframework_plugins/adapters/__init__.py +53 -0
- robotframework_plugins/adapters/_base.py +400 -0
- robotframework_plugins/adapters/claude_code.py +312 -0
- robotframework_plugins/adapters/claude_desktop.py +129 -0
- robotframework_plugins/adapters/codex.py +276 -0
- robotframework_plugins/adapters/copilot.py +87 -0
- robotframework_plugins/adapters/cursor.py +295 -0
- robotframework_plugins/adapters/goose.py +240 -0
- robotframework_plugins/adapters/opencode.py +170 -0
- robotframework_plugins/bundle.py +85 -0
- robotframework_plugins/cli.py +1311 -0
- robotframework_plugins/detect.py +121 -0
- robotframework_plugins/manifest.py +338 -0
- robotframework_plugins/py.typed +0 -0
- robotframework_plugins/skillzip.py +39 -0
- robotframework_plugins/transforms.py +725 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/METADATA +178 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/RECORD +195 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/WHEEL +4 -0
- robotframework_plugins-2026.11.0.dev1.dist-info/entry_points.txt +2 -0
- 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
|
+
}
|