From a81a69486ce5e6f1934e941a5e7c5d7393576c5e Mon Sep 17 00:00:00 2001 From: Many Kasiriha Date: Tue, 17 Nov 2026 15:05:54 +0100 Subject: [PATCH] chore(openspec): archive repo-cleanup and ai-contributor-docs Task 7.1 of both changes is done: CI on main, a local run of the AGENTS.md checks, and contributor PRs #13-#16 on the new layout. The findings are in each tasks.md; the one open policy question (PRs opened before AI_POLICY.md) is answered in ai-contributor-docs design.md. Archiving merges the deltas into openspec/specs: ten modified requirements from repo-cleanup and the new contributor-guidance spec. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FHEmzL3ErAhGQykKWDx2wP --- .../.openspec.yaml | 0 .../2026-11-17-ai-contributor-docs}/design.md | 1 + .../proposal.md | 0 .../specs/contributor-guidance/spec.md | 0 .../2026-11-17-ai-contributor-docs}/tasks.md | 10 ++- .../2026-11-17-repo-cleanup}/.openspec.yaml | 0 .../2026-11-17-repo-cleanup}/design.md | 0 .../2026-11-17-repo-cleanup}/proposal.md | 0 .../specs/language-skill/spec.md | 0 .../specs/library-skill-structure/spec.md | 0 .../specs/platynui-skill/spec.md | 0 .../specs/python-library-skill/spec.md | 0 .../specs/setup-skill/spec.md | 0 .../specs/skill-catalog/spec.md | 0 .../specs/skill-eval-harness/spec.md | 0 .../specs/skill-metadata-conformance/spec.md | 0 .../2026-11-17-repo-cleanup}/tasks.md | 9 ++- openspec/specs/contributor-guidance/spec.md | 81 +++++++++++++++++++ openspec/specs/language-skill/spec.md | 11 ++- .../specs/library-skill-structure/spec.md | 2 +- openspec/specs/platynui-skill/spec.md | 6 +- openspec/specs/python-library-skill/spec.md | 11 ++- openspec/specs/setup-skill/spec.md | 6 +- openspec/specs/skill-catalog/spec.md | 6 +- openspec/specs/skill-eval-harness/spec.md | 8 +- .../specs/skill-metadata-conformance/spec.md | 4 +- 26 files changed, 121 insertions(+), 34 deletions(-) rename openspec/changes/{ai-contributor-docs => archive/2026-11-17-ai-contributor-docs}/.openspec.yaml (100%) rename openspec/changes/{ai-contributor-docs => archive/2026-11-17-ai-contributor-docs}/design.md (97%) rename openspec/changes/{ai-contributor-docs => archive/2026-11-17-ai-contributor-docs}/proposal.md (100%) rename openspec/changes/{ai-contributor-docs => archive/2026-11-17-ai-contributor-docs}/specs/contributor-guidance/spec.md (100%) rename openspec/changes/{ai-contributor-docs => archive/2026-11-17-ai-contributor-docs}/tasks.md (83%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/.openspec.yaml (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/design.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/proposal.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/specs/language-skill/spec.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/specs/library-skill-structure/spec.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/specs/platynui-skill/spec.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/specs/python-library-skill/spec.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/specs/setup-skill/spec.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/specs/skill-catalog/spec.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/specs/skill-eval-harness/spec.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/specs/skill-metadata-conformance/spec.md (100%) rename openspec/changes/{repo-cleanup => archive/2026-11-17-repo-cleanup}/tasks.md (91%) create mode 100644 openspec/specs/contributor-guidance/spec.md diff --git a/openspec/changes/ai-contributor-docs/.openspec.yaml b/openspec/changes/archive/2026-11-17-ai-contributor-docs/.openspec.yaml similarity index 100% rename from openspec/changes/ai-contributor-docs/.openspec.yaml rename to openspec/changes/archive/2026-11-17-ai-contributor-docs/.openspec.yaml diff --git a/openspec/changes/ai-contributor-docs/design.md b/openspec/changes/archive/2026-11-17-ai-contributor-docs/design.md similarity index 97% rename from openspec/changes/ai-contributor-docs/design.md rename to openspec/changes/archive/2026-11-17-ai-contributor-docs/design.md index 2540315..d6a0b05 100644 --- a/openspec/changes/ai-contributor-docs/design.md +++ b/openspec/changes/archive/2026-11-17-ai-contributor-docs/design.md @@ -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. diff --git a/openspec/changes/ai-contributor-docs/proposal.md b/openspec/changes/archive/2026-11-17-ai-contributor-docs/proposal.md similarity index 100% rename from openspec/changes/ai-contributor-docs/proposal.md rename to openspec/changes/archive/2026-11-17-ai-contributor-docs/proposal.md diff --git a/openspec/changes/ai-contributor-docs/specs/contributor-guidance/spec.md b/openspec/changes/archive/2026-11-17-ai-contributor-docs/specs/contributor-guidance/spec.md similarity index 100% rename from openspec/changes/ai-contributor-docs/specs/contributor-guidance/spec.md rename to openspec/changes/archive/2026-11-17-ai-contributor-docs/specs/contributor-guidance/spec.md diff --git a/openspec/changes/ai-contributor-docs/tasks.md b/openspec/changes/archive/2026-11-17-ai-contributor-docs/tasks.md similarity index 83% rename from openspec/changes/ai-contributor-docs/tasks.md rename to openspec/changes/archive/2026-11-17-ai-contributor-docs/tasks.md index 570485c..a494d38 100644 --- a/openspec/changes/ai-contributor-docs/tasks.md +++ b/openspec/changes/archive/2026-11-17-ai-contributor-docs/tasks.md @@ -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. diff --git a/openspec/changes/repo-cleanup/.openspec.yaml b/openspec/changes/archive/2026-11-17-repo-cleanup/.openspec.yaml similarity index 100% rename from openspec/changes/repo-cleanup/.openspec.yaml rename to openspec/changes/archive/2026-11-17-repo-cleanup/.openspec.yaml diff --git a/openspec/changes/repo-cleanup/design.md b/openspec/changes/archive/2026-11-17-repo-cleanup/design.md similarity index 100% rename from openspec/changes/repo-cleanup/design.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/design.md diff --git a/openspec/changes/repo-cleanup/proposal.md b/openspec/changes/archive/2026-11-17-repo-cleanup/proposal.md similarity index 100% rename from openspec/changes/repo-cleanup/proposal.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/proposal.md diff --git a/openspec/changes/repo-cleanup/specs/language-skill/spec.md b/openspec/changes/archive/2026-11-17-repo-cleanup/specs/language-skill/spec.md similarity index 100% rename from openspec/changes/repo-cleanup/specs/language-skill/spec.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/specs/language-skill/spec.md diff --git a/openspec/changes/repo-cleanup/specs/library-skill-structure/spec.md b/openspec/changes/archive/2026-11-17-repo-cleanup/specs/library-skill-structure/spec.md similarity index 100% rename from openspec/changes/repo-cleanup/specs/library-skill-structure/spec.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/specs/library-skill-structure/spec.md diff --git a/openspec/changes/repo-cleanup/specs/platynui-skill/spec.md b/openspec/changes/archive/2026-11-17-repo-cleanup/specs/platynui-skill/spec.md similarity index 100% rename from openspec/changes/repo-cleanup/specs/platynui-skill/spec.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/specs/platynui-skill/spec.md diff --git a/openspec/changes/repo-cleanup/specs/python-library-skill/spec.md b/openspec/changes/archive/2026-11-17-repo-cleanup/specs/python-library-skill/spec.md similarity index 100% rename from openspec/changes/repo-cleanup/specs/python-library-skill/spec.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/specs/python-library-skill/spec.md diff --git a/openspec/changes/repo-cleanup/specs/setup-skill/spec.md b/openspec/changes/archive/2026-11-17-repo-cleanup/specs/setup-skill/spec.md similarity index 100% rename from openspec/changes/repo-cleanup/specs/setup-skill/spec.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/specs/setup-skill/spec.md diff --git a/openspec/changes/repo-cleanup/specs/skill-catalog/spec.md b/openspec/changes/archive/2026-11-17-repo-cleanup/specs/skill-catalog/spec.md similarity index 100% rename from openspec/changes/repo-cleanup/specs/skill-catalog/spec.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/specs/skill-catalog/spec.md diff --git a/openspec/changes/repo-cleanup/specs/skill-eval-harness/spec.md b/openspec/changes/archive/2026-11-17-repo-cleanup/specs/skill-eval-harness/spec.md similarity index 100% rename from openspec/changes/repo-cleanup/specs/skill-eval-harness/spec.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/specs/skill-eval-harness/spec.md diff --git a/openspec/changes/repo-cleanup/specs/skill-metadata-conformance/spec.md b/openspec/changes/archive/2026-11-17-repo-cleanup/specs/skill-metadata-conformance/spec.md similarity index 100% rename from openspec/changes/repo-cleanup/specs/skill-metadata-conformance/spec.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/specs/skill-metadata-conformance/spec.md diff --git a/openspec/changes/repo-cleanup/tasks.md b/openspec/changes/archive/2026-11-17-repo-cleanup/tasks.md similarity index 91% rename from openspec/changes/repo-cleanup/tasks.md rename to openspec/changes/archive/2026-11-17-repo-cleanup/tasks.md index 806f747..28178a5 100644 --- a/openspec/changes/repo-cleanup/tasks.md +++ b/openspec/changes/archive/2026-11-17-repo-cleanup/tasks.md @@ -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 `/.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. diff --git a/openspec/specs/contributor-guidance/spec.md b/openspec/specs/contributor-guidance/spec.md new file mode 100644 index 0000000..eb1f4f6 --- /dev/null +++ b/openspec/specs/contributor-guidance/spec.md @@ -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: ` 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//` 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 diff --git a/openspec/specs/language-skill/spec.md b/openspec/specs/language-skill/spec.md index 6bee693..859afc4 100644 --- a/openspec/specs/language-skill/spec.md +++ b/openspec/specs/language-skill/spec.md @@ -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; @@ -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 @@ -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 diff --git a/openspec/specs/library-skill-structure/spec.md b/openspec/specs/library-skill-structure/spec.md index bb60aa6..5f91afa 100644 --- a/openspec/specs/library-skill-structure/spec.md +++ b/openspec/specs/library-skill-structure/spec.md @@ -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); diff --git a/openspec/specs/platynui-skill/spec.md b/openspec/specs/platynui-skill/spec.md index 51b41a5..3bf6e4b 100644 --- a/openspec/specs/platynui-skill/spec.md +++ b/openspec/specs/platynui-skill/spec.md @@ -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 diff --git a/openspec/specs/python-library-skill/spec.md b/openspec/specs/python-library-skill/spec.md index 2b7bfc5..802069c 100644 --- a/openspec/specs/python-library-skill/spec.md +++ b/openspec/specs/python-library-skill/spec.md @@ -5,14 +5,13 @@ Provide a Robot Framework agent skill that teaches AI agents to create, review a ## Requirements - ### Requirement: Python library skill exists and follows the house structure -The repository SHALL provide a skill at `skills/rf-python-library/` with a `SKILL.md` whose frontmatter has `name: rf-python-library`, a `description`, a `compatibility` field that names Python ≥ 3.10 and `robotframework>=7`, a `references/` directory, a `scripts/` directory and an `assets/examples/` directory. `SKILL.md` SHALL be at most 300 lines and SHALL contain, in this order, the sections: a quick reference with version gate, a default library template, decision tables, placement and import, agent workflow, Gotchas, when to read the references, and Companion Skills. +The repository SHALL provide a skill at `plugins/rf-core/skills/rf-python-library/` with a `SKILL.md` whose frontmatter has `name: rf-python-library`, a `description`, a `compatibility` field that names Python ≥ 3.10 and `robotframework>=7`, a `references/` directory, a `scripts/` directory and an `assets/examples/` directory. `SKILL.md` SHALL be at most 300 lines and SHALL contain, in this order, the sections: a quick reference with version gate, a default library template, decision tables, placement and import, agent workflow, Gotchas, when to read the references, and Companion Skills. #### Scenario: Directory, frontmatter and size - **WHEN** the repository is inspected -- **THEN** `skills/rf-python-library/SKILL.md` exists with `name: rf-python-library`, a non-empty `description` and a `compatibility` value that mentions Python and `robotframework>=7` +- **THEN** `plugins/rf-core/skills/rf-python-library/SKILL.md` exists with `name: rf-python-library`, a non-empty `description` and a `compatibility` value that mentions Python and `robotframework>=7` - **AND** the file has at most 300 lines and all required sections in the stated order #### Scenario: Spec validator passes @@ -245,11 +244,11 @@ The skill description SHALL start with a third-person capability statement that ### Requirement: Distributed without drift -The skill SHALL be copied by `scripts/sync-skills.sh` to `plugins/rf-agentskills/skills/rf-python-library/`, included in the installer assets, named in the `UserPromptSubmit` hook's skill list, and listed in the README skill table. `scripts/check-drift.sh` SHALL pass after sync, and the script SHALL be a regular file (no symlink) in every channel. +The skill SHALL ship in the `rf-core` plugin, be copied unchanged into `bundles/rf-agentskills/` by the catalogue build, be included in the installer assets, be named in the `UserPromptSubmit` hook's skill list, and be listed in the `rf-core` README. `scripts/build-catalog.py --check` and `scripts/check-drift.sh` SHALL pass, and the script SHALL be a regular file (no symlink) in every channel. #### Scenario: All channels in sync -- **WHEN** `scripts/sync-skills.sh` runs and then `scripts/check-drift.sh` -- **THEN** the drift check passes and each channel contains `rf-python-library/scripts/check_library.py` as a regular file +- **WHEN** `scripts/build-catalog.py --check` and then `scripts/check-drift.sh` run +- **THEN** both pass, and the plugin and the bundle each contain `rf-python-library/scripts/check_library.py` as a regular file #### Scenario: Hook mentions the skill - **WHEN** the context-injection hook runs on the prompt "my robot framework library says it contains no keywords" diff --git a/openspec/specs/setup-skill/spec.md b/openspec/specs/setup-skill/spec.md index e9a566c..875df01 100644 --- a/openspec/specs/setup-skill/spec.md +++ b/openspec/specs/setup-skill/spec.md @@ -8,16 +8,16 @@ Provide a Robot Framework agent skill that guides AI agents to install Robot Fra ### Requirement: Setup skill exists and follows the house structure -The repository SHALL provide a skill at `skills/rf-setup/` with a `SKILL.md` whose frontmatter has `name: rf-setup` (matching its directory) and a non-empty `description`, a `references/` directory and an `assets/examples/` directory. +The repository SHALL provide a skill at `plugins/rf-core/skills/rf-setup/` with a `SKILL.md` whose frontmatter has `name: rf-setup` (matching its directory) and a non-empty `description`, a `references/` directory and an `assets/examples/` directory. #### Scenario: Skill directory and frontmatter - **WHEN** the repository is inspected -- **THEN** `skills/rf-setup/SKILL.md` exists with frontmatter `name: rf-setup` and a description that mentions installing Robot Framework and uv, venv/pip and poetry +- **THEN** `plugins/rf-core/skills/rf-setup/SKILL.md` exists with frontmatter `name: rf-setup` and a description that mentions installing Robot Framework and uv, venv/pip and poetry - **AND** `references/` and `assets/examples/` exist and each contain at least one file #### Scenario: Marketplace validation passes - **WHEN** the marketplace/SKILL.md validation test suite runs -- **THEN** the new skill passes the same frontmatter and structure checks applied to every other skill +- **THEN** the skill passes the same frontmatter and structure checks applied to every other skill ### Requirement: Tool choice follows the project, uv by default diff --git a/openspec/specs/skill-catalog/spec.md b/openspec/specs/skill-catalog/spec.md index eaeb243..006dafe 100644 --- a/openspec/specs/skill-catalog/spec.md +++ b/openspec/specs/skill-catalog/spec.md @@ -76,14 +76,14 @@ The content bundle SHALL NOT ship an MCP server or an MCP server configuration i ### Requirement: Generator skills are not shipped in any remaining channel -The content bundle SHALL NOT contain the skills `rf-keyword-builder`, `rf-testcase-builder` or `rf-resource-architect`, nor the scripts `keyword_builder.py`, `testcase_builder.py` or `resource_architect.py`, in any channel: the root `skills/` tree, the Claude Code plugin (also the source of every marketplace install), the installer's bundled assets, or the release tarballs built from them. +The content SHALL NOT contain the skills `rf-keyword-builder`, `rf-testcase-builder` or `rf-resource-architect`, nor the scripts `keyword_builder.py`, `testcase_builder.py` or `resource_architect.py`, in any channel: the plugins under `plugins/` (the source of every marketplace install), the `bundles/rf-agentskills` copy, the installer's bundled assets, or the release tarballs built from them. #### Scenario: No generator skill directories in any channel -- **WHEN** the root `skills/`, `plugins/rf-agentskills/skills/` and a freshly built installer `_assets/` tree are listed +- **WHEN** `plugins/*/skills/`, `bundles/rf-agentskills/skills/` and a freshly built installer `_assets/` tree are listed - **THEN** none contains a skill whose `name:` or directory is `rf-keyword-builder`, `keyword-builder`, `rf-testcase-builder`, `testcase-builder`, `rf-resource-architect` or `resource-architect` #### Scenario: No generator scripts shipped -- **WHEN** the plugin `scripts/` directory, the root skill `scripts/` directories and the installer `_assets/scripts/` are listed +- **WHEN** the plugin and bundle `scripts/` directories, the skill `scripts/` directories and the installer `_assets/` tree are listed - **THEN** none contains `keyword_builder.py`, `testcase_builder.py` or `resource_architect.py` ### Requirement: Upgrades remove the robotcode-overlap skills and subagent diff --git a/openspec/specs/skill-eval-harness/spec.md b/openspec/specs/skill-eval-harness/spec.md index 9c1a54d..0dbef8b 100644 --- a/openspec/specs/skill-eval-harness/spec.md +++ b/openspec/specs/skill-eval-harness/spec.md @@ -7,16 +7,16 @@ Define how the `rf-skill-eval` harness measures whether the rf-agentskills skill ### Requirement: Paired treatment and baseline arms -The harness SHALL support two arms for every task. `treatment` provisions the rf-agentskills plugin as shipped (skills, hooks, subagents, plugin MCP servers). `baseline` provisions none of these. Apart from that, both arms SHALL use the same fixture, prompt, model, allowed tools, turn and time limits, and non-plugin MCP servers. The baseline arm SHALL NOT be able to discover any rf-agentskills skill, whether user-level, project-level (`.claude/skills/`) or plugin-provided. +The harness SHALL support two arms for every task. `treatment` provisions the plugin content as shipped: the skills, hooks and subagents of the repository's content plugins, merged the way the `rf-agentskills` bundle ships them. `baseline` provisions none of these. Apart from that, both arms SHALL use the same fixture, prompt, model, allowed tools, turn and time limits, and MCP servers (the per-task servers, such as `rf-mcp`). The baseline arm SHALL NOT be able to discover any of the repository's skills, whether user-level, project-level (`.claude/skills/`) or plugin-provided. #### Scenario: Baseline run has no skills available - **WHEN** a task runs in the `baseline` arm -- **THEN** the session's isolated config dir and workspace contain no rf-agentskills skill, hook, subagent or plugin MCP server -- **AND** the transcript contains no successful load of an rf-agentskills skill +- **THEN** the session's isolated config dir and workspace contain no skill, hook or subagent from the repository's plugins +- **AND** the transcript contains no successful load of one of the repository's skills #### Scenario: Arms differ only by the plugin - **WHEN** the same task runs in `treatment` and `baseline` -- **THEN** both runs use identical prompt, model, `max_turns`, `timeout_seconds`, allowed tools, fixture contents and non-plugin MCP configuration +- **THEN** both runs use identical prompt, model, `max_turns`, `timeout_seconds`, allowed tools, fixture contents and MCP configuration - **AND** the run records store the arm name #### Scenario: Selecting arms on the command line diff --git a/openspec/specs/skill-metadata-conformance/spec.md b/openspec/specs/skill-metadata-conformance/spec.md index 2f968aa..2635699 100644 --- a/openspec/specs/skill-metadata-conformance/spec.md +++ b/openspec/specs/skill-metadata-conformance/spec.md @@ -71,14 +71,14 @@ The repository SHALL provide a skill validator that can run offline with no thir ### Requirement: Repository references use the canonical identifiers -Subagent definitions, hook-injected context, eval task `skill:` fields, CI and release packaging, and user documentation SHALL refer to skills only by their `rf-` identifier or their `skills/rf-/` path. The legacy long directory names (`robotframework-*-skill`, `robotframework-results`, `robotframework-libdoc-*`) and the legacy short plugin names MUST NOT be used as skill identifiers. +Subagent definitions, hook-injected context, eval task `skill:` fields, CI and release packaging, and user documentation SHALL refer to skills only by their `rf-` identifier or their `plugins//skills/rf-/` path. The legacy long directory names (`robotframework-*-skill`, `robotframework-results`, `robotframework-libdoc-*`) and the legacy short plugin names MUST NOT be used as skill identifiers. #### Scenario: No legacy identifier remains - **WHEN** the repository's skills, plugin agents and scripts, hooks, eval tasks, workflows, tests and README are searched for legacy skill identifiers - **THEN** no match is found, apart from the changelogs and the installer's legacy-name list used for migration #### Scenario: Release packages use the new directory names -- **WHEN** the release workflow builds the standalone, Codex and Copilot skill tarballs +- **WHEN** the release workflow builds a plugin's standalone skills tarball and its Claude Desktop skill archives - **THEN** every packaged skill directory is named `rf-` and its name matches its `SKILL.md` ### Requirement: Installer upgrades migrate away from old skill directories