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
2 changes: 2 additions & 0 deletions openspec/changes/ai-contributor-docs/.openspec.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-16
88 changes: 88 additions & 0 deletions openspec/changes/ai-contributor-docs/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
## Context

See proposal.md (Why). What this change builds on:

- `CONTRIBUTING.md` (173 lines) already has a table of PR checks with their commands. The same commands run in `.github/workflows/ci.yml`: `build-catalog.py --check`, `check-governance.py`, `check_content_rules.py`, `validate-skills.py`, `check-plugin-references.py`, `check-drift.sh`, `check-docs-voice.py`, and `pytest tests/ --ignore=tests/eval` plus each plugin's tests. The harness tests run with `uv sync --all-extras && uv run pytest tests/eval/` (`ci.yml:122`).
- `scripts/check-docs-voice.py` checks the top-level `*.md` files, so new top-level documents are covered without a change.
- `.gitignore` doesn't ignore `CLAUDE.md` or `AGENTS.md`, and neither file exists in the repository.
- `openspec/config.yaml` sets only `schema: spec-driven`.
- RobotCode's `AI_POLICY.md` (robotcodedev/robotcode, main) is the model for the policy. RobotCode's "Working with AI Agents" guide and its chat plugin already teach agents to use the CLI, and our skills hand CLI usage to that plugin.
- The CLI guide (https://robotcode.io/guides/cli/) has these pages:
- Discovering Tests (`discover`)
- Analyzing Code (`analyze code`)
- Analyzing Results (`results`)
- REPL (`repl`)
- Debugging (`robot-debug`)
- Browsing Documentation (`doc`)
- Wrapper (`--wrapper`)
- the `robot.toml` page for `robot`/`run`, and Troubleshooting for `config`/`profiles`

## Goals / Non-Goals

**Goals:**
- One short text that a coding agent can follow to make a PR that passes CI the first time.
- A policy that says what AI-assisted contributions must meet, adapted to a repository whose output is itself agent content.
- RobotCode as the shared base for Robot Framework capabilities, written down where contributors and OpenSpec proposals see it.
- Checks that fail when the guide and CI drift apart, so the guide doesn't need a reviewer to keep it true.

**Non-Goals:**
- Changing the repository's own tooling to follow the RobotCode-first rule: that is `robotcode-first-tooling`.
- Changing review rules: that is `lean-governance`. This change links to `GOVERNANCE.md` and doesn't restate the rules.
- Detecting AI-written PRs automatically. Disclosure relies on the contributor.
- Removing stale documents: that is `repo-cleanup`.

## Decisions

### D1. Two documents: a policy and an operational guide

`AI_POLICY.md` is for people. It explains what is expected and why, and follows the structure of RobotCode's policy (human responsibility, disclosure, licensing, communication, PRs, low-context submissions, enforcement), with a section for what is specific to this repository. `AGENTS.md` is for agents. It is a list of facts and commands, kept under about 120 lines, that links to the policy instead of repeating it.

Alternative: one file. It would mix rules for people with command lists for agents, and the agent part would grow into a second CONTRIBUTING.md.

### D2. `CLAUDE.md` imports `AGENTS.md`

`CLAUDE.md` contains `@AGENTS.md` and nothing else. Claude Code expands the import. Codex, Copilot, Cursor and OpenCode read `AGENTS.md` directly. One text serves every agent we support.

Alternatives:
- A symlink. Plugins avoid symlinks, and Windows checkouts handle them badly.
- A copy. It would drift.

### D3. The RobotCode-first rule and its capability map live in `AGENTS.md`; the policy states the rule

The rule is stated in full in both documents: it is a policy, and agents need it in context. The capability map (need → `robotcode` command → guide page link) appears only in `AGENTS.md`, because only agents act on it. It links the guide pages rather than copying their options, so it stays correct when RobotCode adds flags.

The rule says what "re-implement" means in practice: our own code that parses Robot Framework files to resolve keywords, runs `robot` and parses `output.xml` for results, or builds libdoc output to look up keywords, when a `robotcode` command gives the same answer. Custom code that calls `robotcode` and adds project-specific logic is fine.

### D4. The guide is checked against CI, not reviewed

`tests/test_contributor_guidance.py`:
- **Section parsing.** It reads the "Checks" section of `AGENTS.md` (one command per bullet, in backticks) and asserts that each command string occurs in `.github/workflows/ci.yml`, ignoring whitespace differences.
- **Paths.** It asserts that every `scripts/<file>` named anywhere in `AGENTS.md` exists.
- **`CLAUDE.md`.** It asserts the file's only non-blank line is `@AGENTS.md`.
- **Templates.** It asserts the PR template has an "AI assistance" heading and the RobotCode checklist item, and that the issue template mentions disclosure.

When `lean-governance` or `repo-cleanup` removes a script or a CI step, this test makes them update `AGENTS.md` in the same PR.

### D5. OpenSpec context and rules

`openspec/config.yaml` gets a `context` block of about 20 lines:
- what the repository ships;
- the top-level layout;
- the RobotCode-first rule in two sentences;
- "write for people in the Robot Framework Voice; see CONTRIBUTING.md".

It gets two rules, one for `proposal` and one for `tasks`, as listed in the proposal. The context is plain facts, so it doesn't go stale faster than `AGENTS.md`; the test in D4 doesn't check it, because OpenSpec reads it only when a change is drafted.

### D6. CONTRIBUTING.md keeps its required sections and drops duplicates

`programme-documentation` requires a "Versions" section in `CONTRIBUTING.md`, so it stays.
- The "Review" section shrinks to two sentences and a link to `GOVERNANCE.md`, which `lean-governance` rewrites.
- The layout block gains `legacy/` (the one-shot `rf-agentskills` forwarder) and `openspec/`, and says that `bundles/rf-agentskills/` is generated from the plugins listed in `plugins/rf-agentskills/catalog.yaml`.
- A new first paragraph links `AGENTS.md` for agents and `AI_POLICY.md` for anyone using AI tools.

## Risks / Trade-offs

- [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.
- [`@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.
68 changes: 68 additions & 0 deletions openspec/changes/ai-contributor-docs/proposal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
## Why

Much of the work on this repository is done with coding agents, and the content it ships (skills, hooks, subagents, scripts) is read and run by other people's agents. Yet nothing tells a contributor, human or AI, how AI-assisted work is accepted, which local checks to run, which files are generated, or which tool to build on for Robot Framework capabilities. `openspec/config.yaml` gives proposals no project context either. The result is AI-written changes that re-implement what RobotCode already does, hand-edit generated files, or fail CI on checks nobody ran (PR #20 failed a repository check that was never run locally).

## What Changes

- **`AI_POLICY.md`** (new), adapted from RobotCode's AI policy:
- from RobotCode's policy: a human owns, understands and tests every change; AI use is disclosed in the PR or issue, with an optional `AI-Assisted-By:` commit trailer; the contributor confirms the right to submit under Apache-2.0; low-context automated submissions are declined; maintainers decide;
- specific to this repository:
- skill, hook, subagent and script content is security-relevant, because other people's agents read and run it;
- every keyword a skill teaches must resolve (`scripts/check-skill-keywords.py`);
- generated files are never edited by hand: name the command that regenerates them;
- paid eval runs and re-baselines are dispatched by maintainers;
- eval tasks and fixtures read like real user requests and real projects;
- the **RobotCode-first rule** (below).
- **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 to run, discover, analyse, inspect results, run keywords step by step in the REPL, look up keywords and debug, instead of new custom implementations.
- Gaps go upstream to RobotCode, the central place for such improvements.
- Custom scripts (hooks, skill helpers, eval grading) are fine when they don't re-implement those capabilities.

The rule comes with a capability map: need → command → guide page. Enforcing it in the repository's own tooling is the separate change `robotcode-first-tooling`.
- **`AGENTS.md`** (new): a short operational guide for coding agents. It covers:
- the layout;
- the exact local checks, the same commands CI runs;
- generated files and how to regenerate them;
- files never to commit;
- the OpenSpec workflow;
- links to `AI_POLICY.md` and the RobotCode-first rule.

**`CLAUDE.md`** (new) contains only `@AGENTS.md`, so Claude Code loads the same text.
- **PR template.** Add an AI-disclosure section and a checklist item: "Robot Framework capabilities go through `robotcode`; gaps are reported upstream". The issue template gets a disclosure note.
- **`openspec/config.yaml`.**
- Add `context` with the project summary, the layout, the RobotCode-first rule and the docs voice.
- Add `rules`:
- a proposal that touches Robot Framework capabilities says which `robotcode` command it uses, or why none fits;
- every task has a verify clause.
- **`CONTRIBUTING.md`.**
- Fix the layout: add `legacy/` and `openspec/`, and say that `bundles/` is generated from `plugins/rf-agentskills/catalog.yaml`.
- Replace the review-group list with a link to `GOVERNANCE.md`, which the change `lean-governance` rewrites.
- Link `AGENTS.md` and `AI_POLICY.md`. The README links them too.
- **Automated checks.** A repository test asserts:
- `AGENTS.md` and `AI_POLICY.md` exist;
- every script `AGENTS.md` names exists, and every check command in it appears in `.github/workflows/ci.yml`;
- `CLAUDE.md` imports `AGENTS.md`;
- the PR template has the disclosure section and the RobotCode item.

`scripts/check-docs-voice.py` already covers top-level `*.md` files, so the new documents get the voice check.

## Capabilities

### New Capabilities
- `contributor-guidance`: the AI contribution policy, the RobotCode-first rule, the agent guide, the PR template items, the OpenSpec project context, and the checks that keep them consistent with CI.

### Modified Capabilities

None. `programme-documentation` (added by the unarchived change `launch-plugin-programme`) keeps its requirements. This change adds its own documents next to them and doesn't move the "Versions" section, which that capability requires in `CONTRIBUTING.md`.

## Impact

- **New files:** `AI_POLICY.md`, `AGENTS.md`, `CLAUDE.md`, and a test `tests/test_contributor_guidance.py`.
- **Changed files:** `.github/pull_request_template.md`, `.github/ISSUE_TEMPLATE/plugin-feedback.yml`, `openspec/config.yaml`, `CONTRIBUTING.md` and `README.md`.
- **No change to:** code, plugins, the installer, the release or the evals.
- **Related changes:**
- `repo-cleanup` removes the stale material `AGENTS.md` would otherwise have to warn about.
- `lean-governance` owns the review rules this change links to.
- `robotcode-first-tooling` applies the RobotCode-first rule to the repository's own scripts.
- **Contributors:** a PR with substantial AI help needs a disclosure line. Small fixes don't.
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
## ADDED 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
Loading
Loading