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
Original file line number Diff line number Diff line change
Expand Up @@ -85,4 +85,5 @@ It gets two rules, one for `proposal` and one for `tasks`, as listed in the prop
- [The guide drifts on things the test can't see, such as the layout or the OpenSpec steps] → It's kept short, and `repo-cleanup` removes the material that changes most often. A stale line costs a failed CI run, not a wrong release.
- [The RobotCode-first rule blocks a contribution where `robotcode` is close but not good enough] → The rule allows a custom script that names the upstream issue it bridges, and maintainers decide.
- [Disclosure can't be enforced] → The template asks for it every time, and the policy lets maintainers close low-context PRs. As at RobotCode, the aim is honest contributors, not detection.
- [PRs opened before the policy] → The policy applies to every open PR. Review comments say that the author couldn't have known it, ask for what it requires, and leave content decisions to the content.
- [`@AGENTS.md` import syntax changes in Claude Code] → The test pins the one-line form; a change shows up as a failing test, not a silent gap.
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,13 @@

## 7. Initial check

- [ ] 7.1 After merge, check the new policy and agent guide in use: one full CI run on `main`, one local run of the checks in `AGENTS.md` or CONTRIBUTING, and the next contributor PR. Write down anything that broke or got harder. If a decision in `design.md` turns out wrong or risky, propose the change to the maintainer and update `design.md`. Verify that the findings are recorded in this change.
- [x] 7.1 After merge, check the new policy and agent guide in use: one full CI run on `main`, one local run of the checks in `AGENTS.md` or CONTRIBUTING, and the next contributor PR. Write down anything that broke or got harder. If a decision in `design.md` turns out wrong or risky, propose the change to the maintainer and update `design.md`. Verify that the findings are recorded in this change.

Findings so far (2026-11-17):
Findings (2026-11-17):
- Local run of the `AGENTS.md` Checks list, command by command, on `46067e0`: every command exists and runs as written; `tests/test_contributor_guidance.py` passes. The only failure was the rf-core venv test, a test bug recorded in repo-cleanup 7.1 and fixed in the follow-up PR.
- Harder than it should be: the Checks list gives no setup step. The commands need Robot Framework, the libraries and pytest installed. CONTRIBUTING has `uv sync`, but `AGENTS.md` doesn't point to it, so an agent that reads only `AGENTS.md` has to guess. Fixed in the follow-up PR, with the maintainer's agreement: a setup line before the list (`uv sync --all-packages`, `uv run rfbrowser init chromium`).
- Still open: the next contributor PR, to see whether the "AI assistance" section and the RobotCode item get filled in. Tick this task once one has come in.
- CI on `main`: the merges of #33 (`46067e0`), #34 and the contributor PRs #13–#16 (last `d5a1e91`) passed.
- Contributor PRs: the policy was applied in the review of all eight open PRs (#11–#18), and gave a clear basis for each verdict, above all "RobotCode first" (#12, #18) and "does one thing" (#12, #15, #18). #13–#16 merged with small maintainer fixes; #11, #12, #17 and #18 got comments inviting a rework.
- Not observable yet: whether new PRs fill in the "AI assistance" section and the RobotCode item. All eight PRs were opened before the template had them, so none could. The review comments ask for the section; watch it on the next newly opened PR.
- New question the policy didn't answer: how it applies to PRs opened before it existed. Maintainer decision: it applies to all open PRs, and the comments say plainly that the author couldn't have known it. Recorded in `design.md` (Risks).
- No decision in `design.md` turned out wrong.
Original file line number Diff line number Diff line change
Expand Up @@ -86,10 +86,13 @@

## 7. Initial check

- [ ] 7.1 After merge, check the removals and moves in use: one full CI run on `main`, one local run of the checks in `AGENTS.md` or CONTRIBUTING, and the next contributor PR. Write down anything that broke or got harder. If a decision in `design.md` turns out wrong or risky, propose the change to the maintainer and update `design.md`. Verify that the findings are recorded in this change.
- [x] 7.1 After merge, check the removals and moves in use: one full CI run on `main`, one local run of the checks in `AGENTS.md` or CONTRIBUTING, and the next contributor PR. Write down anything that broke or got harder. If a decision in `design.md` turns out wrong or risky, propose the change to the maintainer and update `design.md`. Verify that the findings are recorded in this change.

Findings so far (2026-11-17):
Findings (2026-11-17):
- CI on `main`: the merge of #32 (`b17d0de`) passed. The run before it (`8ae76f5`, #31) failed one Windows test, `test_opencode_plugin_appends_validation_errors`. It ran for about 1m48s against the hook's 60 s timeout and has failed once in the last 40 runs, so it reads as a slow runner rather than this change.
- Local run of every check in `AGENTS.md` on `46067e0`: all pass. The one failure was `test_check_rf_environment_uses_project_venv`, the local-only failure noted in 6.1. The cause is in the test: it symlinked `<tmp>/.venv/bin/python` to the running interpreter, and a venv's python reached through a symlink outside its venv loses that venv's packages. So the test failed for anyone who runs pytest in a uv or other venv, and passed only on CI's system Python. Fixed in the follow-up PR with a shell shim that runs the same interpreter. It passes in both kinds of environment.
- None of the removals or moves got in the way: no check looked for a deleted file, and the `docs/archive/` index answered where the old documents went.
- Still open: the next contributor PR. Tick this task once one has gone through CI on the new layout.
- Contributor PRs: #13, #14, #15 and #16 (fork PRs from before the cleanup) went through on the new layout. A maintainer merged `main` into each branch (no force-push needed, since the PRs allow maintainer edits), made small fixes and regenerated with `build-catalog.py` and `build-agent-variants.py`. None of them touched a removed or moved file, and all checks passed. The merges `f31c1da`, `21c8301`, `51ec999` and `d5a1e91` passed CI on `main`.
- Got harder: fork workflows wait for maintainer approval until the contributor has a merged PR, so a first contribution shows no CI until a maintainer starts it. That is GitHub's default, not this change, and it is worth knowing when reviewing.
- Not yet exercised: D6 (`release.yml` owns `latest`), since no release has run since #32. Check that `latest` moves with the next release.
- No decision in `design.md` turned out wrong.
81 changes: 81 additions & 0 deletions openspec/specs/contributor-guidance/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# contributor-guidance Specification

## Purpose
What people and coding agents need to contribute here: the AI contribution policy (`AI_POLICY.md`), the agent guide (`AGENTS.md`) checked against CI, the RobotCode-first rule, the AI and RobotCode items in the templates, and the OpenSpec project context.

## Requirements

### Requirement: AI contribution policy

The repository SHALL contain `AI_POLICY.md`, linked from `README.md`, `CONTRIBUTING.md` and `AGENTS.md`. It SHALL state that:
- AI tools and coding agents are welcome, and the human who submits a contribution is responsible for it: they understand it, have reviewed all generated output, have run the documented checks, and handle review feedback themselves;
- a pull request, issue or comment made with substantial AI help says so where reviewers see it, with an optional `AI-Assisted-By: <tool>` commit trailer; grammar fixes, formatting and ordinary editor completions need no disclosure;
- by submitting, the contributor confirms the right to submit the content under the Apache-2.0 licence, and that generated content with unclear origin or copied third-party material is disclosed or left out;
- skills, hooks, subagents and scripts are read and run by other people's agents, so changes to them are security-relevant and go through the security gate;
- every keyword a skill teaches resolves against the library it names, as `scripts/check-skill-keywords.py` checks;
- generated files (`bundles/`, `docs/catalog.md`, `.claude-plugin/marketplace.json`, `plugins/*/variants/`, eval baselines) are never edited by hand, and a change to them names the command that regenerated them;
- paid live eval runs and re-baselines are dispatched by maintainers;
- eval tasks and fixtures read like real user requests and real projects, and don't hint at the grading;
- low-context, fully automated or unverified submissions may be closed, and maintainers decide how the policy applies.

#### Scenario: Disclosure asked for
- **WHEN** a contributor opens a PR whose code an agent wrote
- **THEN** the PR template asks for the disclosure, and `AI_POLICY.md` says what it confirms

#### Scenario: Generated file edited by hand
- **WHEN** a contributor asks an agent that follows `AGENTS.md` to change a skill that the bundle copies
- **THEN** the guide tells it to edit `plugins/<name>/` and run `python scripts/build-catalog.py`, not to edit `bundles/`

### Requirement: RobotCode is the base of the Robot Framework AI toolstack

`AI_POLICY.md` and `AGENTS.md` SHALL state the RobotCode-first rule:
- the `robotcode` CLI (https://robotcode.io/guides/cli/) is the core of the Robot Framework AI toolstack;
- AI solutions in this repository use it for running tests, discovery, static analysis, result analysis, running keywords step by step in the REPL, keyword and library documentation, and debugging, in preference to new custom implementations of those capabilities;
- a capability RobotCode lacks is reported or contributed upstream to RobotCode, the central place for such improvements, rather than worked around here;
- custom scripts (hook glue, skill helpers, eval grading, project conventions) are welcome when they call `robotcode` for these capabilities instead of re-implementing them.

`AGENTS.md` SHALL contain a capability map that names, for each capability, the `robotcode` command and the guide page that documents it: `robot`/`run`, `discover`, `analyze code`, `results`, `repl`, `robot-debug`, `doc`, `--wrapper`, and `config`/`profiles`.

#### Scenario: Agent needs keyword documentation
- **WHEN** an agent working on a skill needs the arguments of a library keyword
- **THEN** `AGENTS.md` points it to `robotcode doc keyword`, not to a custom libdoc script

#### Scenario: Missing capability
- **WHEN** a contributor finds that `robotcode` can't do something a skill needs
- **THEN** the policy tells them to open an issue or PR at RobotCode, and a custom script for it states in a comment which upstream issue it covers

### Requirement: Agent guide matches CI

The repository SHALL contain `AGENTS.md` with the layout, the local checks, the generated files with their regenerate commands, the files never to commit, and the OpenSpec workflow. `CLAUDE.md` SHALL consist of an import of `AGENTS.md`, so both agents read one text. A repository test SHALL fail when:
- `AGENTS.md`, `AI_POLICY.md` or `CLAUDE.md` is missing;
- a `scripts/…` path named in `AGENTS.md` doesn't exist;
- a check command listed in the "Checks" section of `AGENTS.md` doesn't appear in `.github/workflows/ci.yml`;
- `CLAUDE.md` doesn't import `AGENTS.md`.

`AGENTS.md`, `AI_POLICY.md` and `CLAUDE.md` SHALL pass the docs voice check.

#### Scenario: Script renamed
- **WHEN** a PR renames `scripts/check-drift.sh` and doesn't update `AGENTS.md`
- **THEN** the repository test fails and names the missing path

#### Scenario: Check dropped from CI
- **WHEN** a PR removes `python scripts/check-docs-voice.py` from `ci.yml` but `AGENTS.md` still lists it
- **THEN** the repository test fails and names the command

### Requirement: PR template asks about AI use and RobotCode

`.github/pull_request_template.md` SHALL have an "AI assistance" section that asks for the disclosure or "none", and a checklist item stating that Robot Framework capabilities go through `robotcode` and that gaps are reported upstream. The issue template SHALL ask reporters to disclose AI-generated reports. A repository test SHALL check that both are present.

#### Scenario: Template item removed
- **WHEN** a PR deletes the RobotCode item from the PR template
- **THEN** the repository test fails

### Requirement: OpenSpec proposals get project context

`openspec/config.yaml` SHALL set `context` with the project summary (marketplace plugins, the installer, the eval harness, security scanning), the layout, the RobotCode-first rule and the docs voice. It SHALL also set `rules`:
- a proposal that touches a Robot Framework capability names the `robotcode` command it uses, or says why none fits;
- every task has a verify clause.

#### Scenario: Proposal drafted by an agent
- **WHEN** an agent runs `openspec instructions proposal` for a new change
- **THEN** the returned context contains the RobotCode-first rule and the proposal rule
11 changes: 5 additions & 6 deletions openspec/specs/language-skill/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,9 @@ Provide the `rf-language` agent skill. It teaches agents to write, refactor and

## Requirements


### Requirement: Skill exists with conformant frontmatter and layout

The repository SHALL provide the skill at `skills/rf-language/` with:
The repository SHALL provide the skill at `plugins/rf-core/skills/rf-language/` with:
- a `SKILL.md` whose frontmatter `name` is `rf-language` (equal to the directory name), with `description`, `license`, `compatibility` and `metadata` (`author`, `version`) in the form required for every shipped skill;
- a `references/` directory;
- an `assets/examples/` directory;
Expand All @@ -17,7 +16,7 @@ The repository SHALL provide the skill at `skills/rf-language/` with:
The `compatibility` text SHALL be at most 500 characters and SHALL state that Python and `robotframework>=7` in the project environment are needed for the bundled script, that the guidance is version-gated, and that `robotcode[all]>=2.8` is required in the project environment (it also provides Robocop). The skill SHALL contain only regular files (no symlinks).

#### Scenario: Directory and frontmatter
- **WHEN** `skills/rf-language/SKILL.md` is parsed
- **WHEN** `plugins/rf-core/skills/rf-language/SKILL.md` is parsed
- **THEN** `name` is `rf-language`, `license`, `compatibility` (≤ 500 characters) and `metadata` (`author`, `version`) are present, `scripts/rf_conventions.py` exists, and the skill validator used for all skills reports no violation

### Requirement: Description states capability, triggers and boundaries
Expand Down Expand Up @@ -494,11 +493,11 @@ The run and dry-run checks take optional `args` and `expected_tests` (minimum pa

### Requirement: Skill is distributed to every channel without drift

The skill SHALL be propagated by the sync tooling to the Claude Code plugin (`plugins/rf-agentskills/skills/rf-language/`, with its own `scripts/rf_conventions.py`) and included in the installer assets through the plugin mirror. The drift check and the skill validator SHALL pass. In addition, the context-injection hook's skill list SHALL name `rf-language`; the subagents `rf-test-architect`, `rf-debug-expert` and `rf-migration-guide` SHALL direct the agent to `rf-language` (and, for migration, to its `references/migration.md` and the `rf_conventions` report); the README skill table and project structure SHALL list the skill; the content CHANGELOG SHALL announce it.
The skill SHALL ship in the `rf-core` plugin, be copied unchanged into `bundles/rf-agentskills/` by the catalogue build (with its own `scripts/rf_conventions.py`), and be included in the installer assets. `scripts/build-catalog.py --check`, the drift check and the skill validator SHALL pass. In addition, the context-injection hook's skill list SHALL name `rf-language`; the subagents `rf-test-architect`, `rf-debug-expert` and `rf-migration-guide` SHALL direct the agent to `rf-language` (and, for migration, to its `references/migration.md` and the `rf_conventions` report); the `rf-core` README SHALL list the skill.

#### Scenario: Channels populated
- **WHEN** `scripts/sync-skills.sh` runs
- **THEN** the plugin copy exists with `name: rf-language` and `scripts/check-drift.sh` exits 0
- **WHEN** `scripts/build-catalog.py --check` runs
- **THEN** the bundle copy exists with `name: rf-language` and `scripts/check-drift.sh` exits 0

#### Scenario: Installer ships the skill
- **WHEN** the installer is built and installs for Claude Code into a temporary project
Expand Down
2 changes: 1 addition & 1 deletion openspec/specs/library-skill-structure/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Define the structure, content rules, size budget, reference and example rules, a

### Requirement: Library skills follow the standard SKILL.md skeleton

Each library skill's `SKILL.md` (`skills/rf-{browser,selenium,appium,requests,restinstance}/SKILL.md`) SHALL contain these level-2 sections in this order:
Each library skill's `SKILL.md` (`plugins/rf-web/skills/rf-{browser,selenium}/SKILL.md`, `plugins/rf-mobile/skills/rf-appium/SKILL.md` and `plugins/rf-api/skills/rf-{requests,restinstance}/SKILL.md`) SHALL contain these level-2 sections in this order:
1. a short orientation (at most ~5 lines, stating what the library is for and when to prefer a sibling skill);
2. `When to use` (the trigger-terms and sibling-boundary block defined by the `skill-triggering` capability), which is the first level-2 section;
3. `Installation` (the short block defined by the `library-skill-install-guidance` capability);
Expand Down
6 changes: 3 additions & 3 deletions openspec/specs/platynui-skill/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,16 @@ Provide a Robot Framework PlatynUI library skill, structured like the existing B

### Requirement: PlatynUI library skill exists and follows the house structure

The repository SHALL provide a Robot Framework PlatynUI library skill at `skills/rf-platynui/`, structured like the existing Browser/Selenium/Appium skills: a `SKILL.md` with valid frontmatter (`name: rf-platynui` matching its directory, and a `description`), a `references/` directory of deep-dive documents, and an `assets/examples/` directory of `.robot` examples.
The repository SHALL provide a Robot Framework PlatynUI library skill at `plugins/rf-desktop/skills/rf-platynui/`, structured like the other library skills: a `SKILL.md` with valid frontmatter (`name: rf-platynui` matching its directory, and a `description`), a `references/` directory of deep-dive documents, and an `assets/examples/` directory of `.robot` examples.

#### Scenario: Skill directory and frontmatter
- **WHEN** the repository is inspected
- **THEN** `skills/rf-platynui/SKILL.md` exists with frontmatter `name: rf-platynui` and a non-empty `description`
- **THEN** `plugins/rf-desktop/skills/rf-platynui/SKILL.md` exists with frontmatter `name: rf-platynui` and a non-empty `description`
- **AND** `references/` and `assets/examples/` subdirectories exist with at least one file each

#### Scenario: Marketplace validation passes
- **WHEN** the marketplace/SKILL.md validation test suite runs
- **THEN** the new skill passes the same frontmatter/structure checks applied to every other skill
- **THEN** the skill passes the same frontmatter/structure checks applied to every other skill

### Requirement: Skill targets new_core PlatynUI.BareMetal only

Expand Down
Loading
Loading