Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
272 changes: 272 additions & 0 deletions openspec/specs/bdd-skill/spec.md

Large diffs are not rendered by default.

31 changes: 27 additions & 4 deletions openspec/specs/language-skill/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -363,12 +363,29 @@ The skill SHALL follow the house style rules of the library skills: no whole-wor

### Requirement: Scope boundaries with sibling skills

The skill SHALL NOT teach Python keyword libraries or listeners (rf-python-library), library-specific keywords, locators or waits (the library skills), installation (rf-setup), or driving the robotcode CLI (running, discovery, keyword documentation, result analysis, debugging). Where a task crosses into those topics, the skill SHALL name the sibling skill, or for robotcode CLI work the robotcode plugin's `robotcode` skill. Its code blocks SHALL call only BuiltIn or standard-library keywords and keywords defined in the example resources.
The skill SHALL NOT teach these topics, which belong elsewhere:
- Python keyword libraries or listeners (rf-python-library);
- library-specific keywords, locators or waits (the library skills);
- installation (rf-setup);
- BDD specification design (rf-bdd): mapping features, rules and examples onto suites, documentation and tags; step vocabularies and scenario state; translating Gherkin; reviewing BDD readability;
- driving the robotcode CLI: running, discovery, keyword documentation, result analysis, debugging.

The BDD mechanics stay in this skill: prefix stripping, prefix-free step definitions and embedded arguments. Where a task crosses into a topic listed above, the skill SHALL name the sibling skill, or for robotcode CLI work the robotcode plugin's `robotcode` skill. Its code blocks SHALL call only BuiltIn or standard-library keywords and keywords defined in the example resources.

The gotcha about keyword-call casing SHALL tell the agent to follow the casing the project's Robocop configuration and existing keywords use, and SHALL NOT require Title Case for BDD steps.

#### Scenario: No library keyword catalogue
- **WHEN** the skill's code blocks are checked
- **THEN** they call only BuiltIn or standard-library keywords and keywords defined in the example resources

#### Scenario: BDD specification work is handed to rf-bdd
- **WHEN** the `When to use` block, `references/styles.md` and the BDD part of `references/embedded-arguments.md` are read
- **THEN** each names `rf-bdd` for writing or reviewing BDD specifications, in one line

#### Scenario: Casing follows the project
- **WHEN** the `Gotchas` section is read
- **THEN** no item requires Title Case for `Given`/`When`/`Then` steps, and the casing item says to follow the project's Robocop configuration

### Requirement: rf_conventions follows the skill script execution contract

`scripts/rf_conventions.py` SHALL satisfy the `skill-script-execution` contract: `uv run python scripts/rf_conventions.py` as the documented command with the non-uv fallback; PEP 723 metadata with `robotframework>=7`; exit codes 0 (completed, including a directory with no Robot Framework files), 1 (internal error), 2 (usage), 3 (Robot Framework missing or older than 7) and 4 (path not found or not a directory); JSON-only stdout; `error:`/`warning:`/`hint:` lines on stderr; `--help` ending with at least three runnable examples; `--json-out FILE`. It SHALL NOT modify any file in the scanned project, and SHALL NOT import the project's libraries or execute project code.
Expand Down Expand Up @@ -434,14 +451,20 @@ By default the output SHALL stay under 8 KB for a project of up to 2,000 Robot F

### Requirement: Companion Skills integration

`SKILL.md` SHALL end with a `## Companion Skills` `Need | Skill` table with rows for rf-python-library (only once shipped in the same release), at least rf-browser and rf-requests as library skills, and rf-setup. A sentence after the table SHALL name the robotcode plugin's `robotcode` skill for running, keyword lookup, result analysis and debugging. The Companion Skills tables of rf-setup, rf-python-library, rf-browser, rf-selenium, rf-appium, rf-requests, rf-restinstance and rf-platynui SHALL get one row naming `rf-language`, with identical Need wording from the shared catalogue key `language`.
`SKILL.md` SHALL end with a `## Companion Skills` `Need | Skill` table with rows for:
- rf-python-library (only once shipped in the same release);
- at least rf-browser and rf-requests as library skills;
- rf-setup;
- rf-bdd.

A sentence after the table SHALL name the robotcode plugin's `robotcode` skill for running, keyword lookup, result analysis and debugging. The Companion Skills tables of rf-setup, rf-python-library, rf-bdd, rf-browser, rf-selenium, rf-appium, rf-requests, rf-restinstance and rf-platynui SHALL each get one row naming `rf-language`, with identical Need wording from the shared catalogue key `language`.

#### Scenario: Table rows present
- **WHEN** the rf-language Companion Skills table is parsed
- **THEN** it has rows naming rf-python-library, rf-browser, rf-requests and rf-setup, no row names rf-libdoc, rf-results or rf-robotcode, and every named skill is shipped in the same release
- **THEN** it has rows naming rf-python-library, rf-browser, rf-requests, rf-setup and rf-bdd, no row names rf-libdoc, rf-results or rf-robotcode, and every named skill is shipped in the same release

#### Scenario: Other skills point back
- **WHEN** the Companion Skills tables of the eight skills listed above are parsed
- **WHEN** the Companion Skills tables of the nine skills listed above are parsed
- **THEN** each has a row naming `rf-language` with identical Need wording, and no table names `rf-test-design`, `rf-keyword-design` or a retired skill

### Requirement: Trigger query set
Expand Down
4 changes: 2 additions & 2 deletions openspec/specs/plugin-split/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The catalogue SHALL contain these plugins, and every skill and subagent SHALL be

| Plugin | Skills | Subagents | Hooks |
|---|---|---|---|
| `rf-core` | `rf-language`, `rf-setup`, `rf-python-library` | `rf-test-architect`, `rf-debug-expert`, `rf-migration-guide` | all |
| `rf-core` | `rf-language`, `rf-bdd`, `rf-setup`, `rf-python-library` | `rf-test-architect`, `rf-debug-expert`, `rf-migration-guide` | all |
| `rf-web` | `rf-browser`, `rf-selenium` | none | none |
| `rf-api` | `rf-requests`, `rf-restinstance` | none | none |
| `rf-mobile` | `rf-appium` | none | none |
Expand All @@ -22,7 +22,7 @@ A technology plugin SHALL NOT be added to the catalogue without content and at l

#### Scenario: Every skill has one home
- **WHEN** the skill directories of all plugins are listed
- **THEN** the nine skills appear once each, in the plugins the table names
- **THEN** the ten skills appear once each, in the plugins the table names

#### Scenario: Empty plugin refused
- **WHEN** a PR adds `plugins/rf-database/` with a `catalog.yaml` but no skill, subagent or hook
Expand Down
5 changes: 5 additions & 0 deletions openspec/specs/plugin-subagents/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Defines what the rf-agentskills subagents (`rf-test-architect`, `rf-migration-gu

Each subagent SHALL contain a routing table. The table maps the kinds of work the subagent delegates to the skill that owns them, or to the robotcode command that answers them, using the skill identifiers of the shipped catalog. Routes:
- test-case and suite design, user keywords, resources, variables and legacy-syntax migration SHALL route to `rf-language`;
- BDD specifications (Given/When/Then suites, step vocabularies, translating Gherkin or acceptance criteria) SHALL route to `rf-bdd`;
- Python keyword libraries and listeners SHALL route to `rf-python-library`;
- keyword name and argument lookup SHALL route to `robotcode doc keywords` / `robotcode doc keyword`;
- reading results SHALL route to `robotcode results`;
Expand All @@ -23,6 +24,10 @@ When a routed library skill is not available, the subagent SHALL name the plugin
- **WHEN** `rf-test-architect` has decided the project layout and must write test suites and shared keywords
- **THEN** its instructions direct it to load `rf-language` for the suites and the resource files, and not to follow an inline syntax guide

#### Scenario: Test architect delegates BDD specifications
- **WHEN** `rf-test-architect` is asked to set up acceptance tests written as Given/When/Then specifications
- **THEN** its routing table sends the suites and step keywords to `rf-bdd`

#### Scenario: Debug expert routes a library-side failure
- **WHEN** `rf-debug-expert` diagnoses "library contains no keywords" or state that resets between tests
- **THEN** its routing table sends that failure class to `rf-python-library`
Expand Down
15 changes: 12 additions & 3 deletions openspec/specs/rf-session-context-hooks/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Defines the two informational hooks that tell the agent which rf-agentskills res

When the user prompt contains a Robot Framework signal, the `UserPromptSubmit` hook SHALL inject one additional-context message. The message SHALL route by kind of work:
- tests, suites, user keywords, resources and variables to `rf-language`;
- Given/When/Then specifications and Gherkin input to `rf-bdd`;
- Python libraries and listeners to `rf-python-library`;
- library usage to the library's own skill, without naming it, and to installing the technology plugin (`rf-web`, `rf-api`, `rf-mobile`, `rf-desktop`) when that skill is not available;
- keyword names and arguments to `robotcode doc keyword`, instead of memory;
Expand All @@ -19,7 +20,7 @@ The message SHALL end with a one-line reminder to write RF 7 syntax (`RETURN`, `

#### Scenario: RF prompt gets the routing message
- **WHEN** the prompt is "add a data-driven login test to tests/login.robot"
- **THEN** the hook emits exactly one `UserPromptSubmit` additional-context message that names `rf-language`, `rf-python-library`, `robotcode doc` and `robotcode results`
- **THEN** the hook emits exactly one `UserPromptSubmit` additional-context message that names `rf-language`, `rf-bdd`, `rf-python-library`, `robotcode doc` and `robotcode results`

#### Scenario: Non-RF prompt gets nothing
- **WHEN** the prompt contains no Robot Framework signal (e.g. "refactor this React component")
Expand All @@ -43,15 +44,19 @@ The injected message SHALL be at most 450 characters, which is about 80 tokens.

The trigger SHALL match case-insensitively:
- existing RF signals: the framework name, the `.robot` and `.resource` extensions, library names, and tooling names such as libdoc, robocop and robotcode;
- the identifiers of the shipped skills and subagents, including `rf-language`, `rf-python-library` and `rf-setup`;
- the identifiers of the shipped skills and subagents, including `rf-language`, `rf-bdd`, `rf-python-library` and `rf-setup`;
- RF section headers pasted into the prompt (`*** Settings ***`, `*** Variables ***`, `*** Test Cases ***`, `*** Tasks ***`, `*** Keywords ***`).

It SHALL NOT match bare "test" or bare "RF".
It SHALL NOT match bare "test", bare "RF", or Gherkin keywords such as "Given" or "Scenario" on their own.

#### Scenario: New skill name triggers
- **WHEN** the prompt is "use rf-python-library to build a listener"
- **THEN** the hook injects the message

#### Scenario: BDD skill name triggers
- **WHEN** the prompt is "use rf-bdd to turn these acceptance criteria into tests"
- **THEN** the hook injects the message

#### Scenario: Pasted RF source triggers
- **WHEN** the prompt contains a line `*** Keywords ***`
- **THEN** the hook injects the message
Expand All @@ -60,6 +65,10 @@ It SHALL NOT match bare "test" or bare "RF".
- **WHEN** the prompt is "run the unit tests and fix the RF amplifier model"
- **THEN** the hook emits nothing

#### Scenario: Plain Gherkin does not trigger
- **WHEN** the prompt is "write Cucumber step definitions in Java for: Given a cart, When I check out"
- **THEN** the hook emits nothing

### Requirement: Context hooks never block

The context-injection and environment-report hooks SHALL always exit 0. On missing, empty or malformed input they SHALL produce no output.
Expand Down
11 changes: 10 additions & 1 deletion openspec/specs/skill-triggering/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ The sibling pairs and signals are:
- rf-browser ↔ rf-selenium: the imported library (`Browser` vs `SeleniumLibrary`), or Playwright vs WebDriver/Selenium Grid.
- rf-requests ↔ rf-restinstance: the imported library (`RequestsLibrary` vs `REST`), or JSON Schema/OpenAPI-driven assertions.
- rf-language ↔ the robotcode plugin's `robotcode` skill: writing Robot Framework syntax vs running, discovering, looking up, analysing or debugging with the robotcode CLI. rf-language names the robotcode skill by its plugin, outside its Companion Skills table.
- rf-language ↔ rf-bdd: Robot Framework syntax, keyword-driven and data-driven tests vs a BDD specification. The BDD signals are Given/When/Then scenarios written as a specification, pasted Gherkin or acceptance criteria, step-vocabulary design, and reviewing the readability of BDD suites. rf-bdd says that it relies on rf-language for syntax, so loading both is expected.
- rf-setup ↔ the library skills: installing and fixing the environment vs writing and fixing test code.

#### Scenario: Web siblings reference each other
Expand All @@ -74,6 +75,10 @@ The sibling pairs and signals are:
- **WHEN** the "When to use" block of rf-language is read
- **THEN** it says that running, discovering, keyword lookup, result reading and debugging with the robotcode CLI are covered by the robotcode plugin's `robotcode` skill

#### Scenario: Language and BDD siblings reference each other
- **WHEN** the "When to use" blocks of rf-language and rf-bdd are read
- **THEN** rf-language names rf-bdd for BDD specifications, and rf-bdd names rf-language for Robot Framework syntax

#### Scenario: Setup is separated from test writing
- **WHEN** the "When to use" block of rf-setup is read
- **THEN** it lists installation and environment error triggers and says that writing tests belongs to the library skills
Expand Down Expand Up @@ -193,12 +198,16 @@ Trigger query files and baseline entries SHALL exist only for shipped skills. Th

### Requirement: Sibling skills share a plugin

Skills that the "Sibling skills state their boundary" requirement pairs as siblings for the same task (rf-browser and rf-selenium; rf-requests and rf-restinstance) SHALL ship in the same plugin, so that a user who has one also has the boundary text of the other.
Skills that the "Sibling skills state their boundary" requirement pairs as siblings for the same task SHALL ship in the same plugin, so that a user who has one also has the boundary text of the other. These pairs are rf-browser and rf-selenium, rf-requests and rf-restinstance, and rf-language and rf-bdd.

#### Scenario: Web siblings together
- **WHEN** the catalogue is listed
- **THEN** `rf-browser` and `rf-selenium` are both in `rf-web`, and `rf-requests` and `rf-restinstance` are both in `rf-api`

#### Scenario: Language siblings together
- **WHEN** the catalogue is listed
- **THEN** `rf-language` and `rf-bdd` are both in `rf-core`

### Requirement: Trigger accuracy holds for partial installs

Trigger baselines SHALL be measured both with all plugins staged and with `rf-core` plus one technology plugin staged. With a partial install, the should-trigger queries of the staged skills SHALL meet the same thresholds as with all plugins. Queries for a technology whose plugin is not staged SHALL count as correct when no rf-* skill of another technology loads.
Expand Down
Loading