feat(ISV-7390): Add AGENTS.md and basic skills (#981)

Added:
1. AGENTS.md
2. skill for running units tests and other quality gates
3. skill for getting information on running integration tests
- setting a recommendation for not running them using agents, but manually
4. agents-md tox env to verify AGENTS.md lines count to be <= 60 (CI enforced)

Tried to provide only the most impactful information including important
file paths, exact commands, etc.

Co-Assisted-By: Claude Opus 4.6
Signed-off-by: Jakub Durkac <jdurkac@redhat.com>

Author: JakubDurkac

.claude/skills

@@ -0,0 +1 @@
+../skills

.github/workflows/build-and-test.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        tox-env: [test, black, yamllint, bandit, mypy, pylint, ansible-lint]
+        tox-env: [test, black, yamllint, bandit, mypy, pylint, ansible-lint, agents-md]
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

AGENTS.md

@@ -0,0 +1,44 @@
+# operator-pipelines
+
+For a concise summary of the project's purpose, read [pipelines overview](docs/users/pipelines_overview.md).
+
+**Toolchain:** Python, Poetry, tox, Ansible, Tekton (OpenShift Pipelines)
+
+## Architecture
+
+- **Tekton pipelines** (`ansible/roles/operator-pipeline/templates/openshift/pipelines/`) define the end-to-end flows. The main pipelines are:
+  - `operator-ci-pipeline.yml` — ISV CI pipeline for partners to test operators on their own infrastructure without submitting to Red Hat.
+  - `operator-hosted-pipeline.yml` — Hosted pipeline that accepts operator submissions, runs linting, static checks and dynamic tests (preflight checks), and communicates with Red Hat internal systems to control certification flow. Used for both ISV and community operators.
+  - `operator-release-pipeline.yml` — Release pipeline that distributes operators to index images (community-operator-index, certified-operator-index, redhat-marketplace-index).
+- **Tekton tasks** (`ansible/roles/operator-pipeline/templates/openshift/tasks/`) are the individual pipeline steps. Tasks typically invoke a Python entrypoint as its container command. See `apply-test-waivers.yml` for a minimal example.
+- **Python core logic** (`operatorcert/` covered by unit tests in structurally matching `tests/` folder) — Entrypoints in `operatorcert/entrypoints` registered in `pyproject.toml` as `[project.scripts]` are directly used by Tekton tasks. The `operatorcert` also includes Pyxis, IIB, GitHub, OPM clients and bundle/catalog models used by entrypoints.
+- **Documentation** (`docs/`, user-facing `docs/user/`)
+
+## Conventions for making changes to the pipelines
+
+- Avoid including credentials within Task scripts.
+  - Avoid the use of `set -x` in shell scripts which _could_ expose credentials
+    to the console.
+- Don't use workspaces for passing secrets. Use `secretKeyRef` and `volumeMount`
+  with secret and key names instead.
+  - Reason: It adds unnecessary complexity to `tkn` commands.
+- Use images from trusted registries/namespaces.
+  - registry.redhat.io
+  - registry.access.redhat.com
+  - quay.io/redhat-isv
+  - quay.io/opdev
+- Use image pull specs with digests instead of tags wherever possible.
+- Tasks must implement their own skipping behavior, if needed.
+  - Reason: If a task is not executed, any dependent tasks will not be
+    executed either.
+- Don't use ClusterTasks or upstream tasks. All tasks are defined in this repo.
+- Document all params, especially pipeline params.
+- Output human readable logs.
+- Use reasonable defaults for params wherever possible.
+
+## PR Conventions
+
+- Run `tox` (all environments) before submitting. For all the details about the tox environments including unit testing, linting, type checking, formatting, etc. use `skills/running-tests-and-quality-gates`. This includes single-file verification commands, like `poetry run black --check path/to/file.py`, `poetry run mypy --strict --ignore-missing-imports path/to/file.py`, etc.
+- Integration tests should NOT be run by an agent as they can take a lot of time to finish and generate extensive logs. Upon asking, agent should inform the developer about the integration tests setup and how to run them manually using `skills/integration-tests/`.
+- Test coverage of code should remain at 100%.
+- All of the quality gates above are enforced in CI.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

skills/SKILLS.md

@@ -0,0 +1,10 @@
+# Skills
+
+Pattern references and workflow guides for operator-pipelines. Each skill lives in `skills/<name>/SKILL.md`.
+
+For Claude Code, `.claude/skills` symlinks here for auto-discovery.
+
+| Skill | Use when… |
+|-------|-----------|
+| [running-tests-and-quality-gates](running-tests-and-quality-gates/SKILL.md) | Use when running or interacting with unit tests, code formatters, linters, type checks, pip audit or other quality gates. |
+| [integration-tests](integration-tests/SKILL.md) | Use when setting up or running integration tests for operator-pipelines. Agents should NOT run these — guide the user through manual setup and execution instead. |

skills/integration-tests/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: integration-tests
+description: Use when setting up or running integration tests for operator-pipelines. Agents should NOT run these — guide the user through manual setup and execution instead.
+---
+
+# Integration Tests
+
+## Overview
+
+Integration tests create a PR in repository https://github.com/redhat-openshift-ecosystem/operator-pipelines-test. This PR creation triggers the hosted pipeline that tests compatibility of an added operator version in various ways. After success, PR is merged automatically and a release pipeline is triggered that adds the operator to an index image. The tests take up to tens of minutes and produce extensive Ansible logs. **Agents should not run them** — instead, help the user prepare and point them to the right resources.
+
+### Prerequisites
+
+1. Be logged in to an OpenShift stage cluster:
+  ```shell
+    oc login --server=https://api.pipelines-stage.0ce8.p1.openshiftapps.com:6443 --token=<token>
+  ```
+2. Have stage Ansible vault password available in `ansible/vault-password`.
+3. Built image is pushed to $PIPELINE_IMAGE_REPO that defaults to `quay.io/redhat-isv/operator-pipelines-test-image`. Either get access to this repo or set up your own repository to store test images.
+
+### Deployment
+
+```bash
+# build and deploy the project to a playground namespace
+make build-and-deploy-playground
+```
+
+### Running Tests
+
+Before running each test:
+```bash
+# export new release version of a test operator based on previous successfully
+# released versions (may look at operator-pipelines-test closed PRs)
+export OPERATOR_VERSION_RELEASE="402-1"
+```
+
+Then, run any of the available test flows. Passing all of them is required by the CI:
+```bash
+make build-and-test-isv               # ISV operator flow
+make build-and-test-community         # Community operator flow
+make build-and-test-isv-fbc-bundle    # ISV FBC bundle flow
+make build-and-test-isv-fbc-catalog   # ISV FBC catalog flow
+```
+
+More information about the specific env variables and commands used to run these tests is available in the project's `Makefile`.
+
+### Debugging
+Recommended tools for basic interaction with running pipelines are `tkn`, `oc` CLI, and OpenShift Console UI.
+
+## Optional setup
+In case the developer wants to create and test a custom situation, refer to `docs/local-dev-environment.md`
+which provides steps to fork the operator repositories, create webhooks and create custom PRs that trigger
+pipelines in the playground namespace.

skills/running-tests-and-quality-gates/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: running-tests-and-quality-gates
+description: Use when running or interacting with unit tests, code formatters, linters, type checks, pip audit or other quality gates.
+---
+
+# Running Tests and Quality Gates
+
+## Quick reference
+
+| Check | Command | Single-file alternative |
+|---|---|---|
+| Unit tests (all) | `tox -e test` | — |
+| Unit tests (single file) | — | `tox -e test -- tests/path/to/test_file.py --no-cov` |
+| Unit tests (single test) | — | `tox -e test -- -k test_name --no-cov` |
+| Unit tests (by path) | — | `tox -e test -- tests/path/to/test_file.py::test_name --no-cov` |
+| Format check | `tox -e black` | `poetry run black --check path/to/file.py` |
+| Auto-format | `tox -e black-format` | `poetry run black path/to/file.py` |
+| Type check (strict) | `tox -e mypy` | `poetry run mypy --strict --ignore-missing-imports path/to/file.py` |
+| Static analysis | `tox -e pylint` | — |
+| Security scan | `tox -e bandit` | — |
+| YAML lint | `tox -e yamllint` | — |
+| Ansible lint | `tox -e ansible-lint` | — |
+| Dockerfile lint | `tox -e hadolint` | — |
+| Dependency audit | `tox -e pip-audit` | — |
+| All checks | `tox` | — |
+
+Use `--no-cov` when running single test files or functions — the 100% coverage gate measures the whole package and will fail on partial runs.
+
+Single-file format/type checks use `poetry run` directly — tox envs other than `test` do not pass `{posargs}` to the underlying tool.
+
+## Fast feedback loop
+
+For tight iteration, run scoped checks after each change:
+
+```bash
+tox -e test -- tests/path/to/test_file.py --no-cov  # single test file
+poetry run black --check path/to/file.py              # format check
+poetry run mypy --strict --ignore-missing-imports path/to/file.py  # type check
+```
+
+Run the full suite (`tox`) before opening a PR.
+
+## Test layout
+
+Tests mirror the source tree under `tests/`:
+
+```
+tests/entrypoints/       # mirrors operatorcert/entrypoints/
+tests/static_tests/      # mirrors operatorcert/static_tests/
+tests/operator_repo/     # mirrors operatorcert/operator_repo/
+tests/catalog/           # mirrors operatorcert/catalog/
+...
+```
+
+Place new test files in the matching subdirectory. Name them `test_<module_name>.py`.
+
+## Constraints
+
+- **100% unit test coverage enforced** (`--cov-fail-under 100`) — new code needs tests
+- **mypy runs in strict mode** — all functions need type annotations, `Any` usage must be explicit

tox.ini

@@ -13,7 +13,8 @@ envlist = test,
           mypy,
           pylint,
           hadolint,
-          ansible-lint
+          ansible-lint,
+          agents-md
 skipsdist = True
 
 [testenv]
@@ -91,6 +92,14 @@ commands = ansible-galaxy collection install -r ansible/playbooks/requirements.y
            --exclude ansible/roles/config_ocp_cluster/files \
            ansible/roles/index_signature_verification/files
 
+[testenv:agents-md]
+commands =
+    {envpython} -c "from pathlib import Path; \
+    p = Path('AGENTS.md'); \
+    assert p.is_file(), 'AGENTS.md missing'; \
+    n = len(p.read_text(encoding='utf-8').splitlines()); \
+    assert n <= 60, f'AGENTS.md has {n} lines (max 60)'"
+
 # Tekton lint is experimental and may not be supported in the future.
 # However, it is useful to have it here for now for manual testing.
 # It is not included in the default testenv and is not triggered by the