docs: add AGENTS.md and agent skills for runner workflows

miragecentury · cursoragent · miragecentury · commit a6e34713a062 · 2026-07-19T13:02:55.000+02:00
Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/.agents/skills/runner-add-tool/SKILL.md b/.agents/skills/runner-add-tool/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: runner-add-tool
+description: >-
+  Add or update a CLI/tool in the Deerhide python-github-runner image (Containerfile,
+  manifest.yaml pins, Renovate, OpenAPI npm overrides, README). Use when adding a binary,
+  apt package, OpenAPI npm CLI, changing an install RUN layer, or wiring a new *_VERSION pin.
+---
+
+# Add a tool to the runner image
+
+## When to use
+
+- New CLI or runtime in the image
+- Change how an existing tool is installed
+- OpenAPI npm tool / CVE override in `openapi-tools/`
+- Keywords: Containerfile, manifest.yaml, Renovate, `*_VERSION`, redocly, spectral, portman, newman, oasdiff
+
+## Install method
+
+| Method | When |
+| --- | --- |
+| GitHub release binary (curl + install to `/usr/local/bin`) | Default for pin-able CLIs |
+| apt | OS packages only (skopeo, buildah, jq, trivy repo, deadsnakes) |
+| npm via `openapi-tools/` | OpenAPI JS CLIs sharing one prefix + CVE overrides |
+| pip | Rare (e.g. pre-commit); prefer binary otherwise |
+
+## Checklist
+
+Copy and track:
+
+```
+Task progress:
+- [ ] 1. Choose install method
+- [ ] 2. Pin FOO_VERSION in manifest.yaml + Containerfile ARG
+- [ ] 3. Add RUN install layer (root, before USER runner)
+- [ ] 4. OpenAPI npm only: package + symlink + overrides if needed
+- [ ] 5. Renovate customManagers entry for the new pin
+- [ ] 6. Update README "What's included"
+- [ ] 7. Validate (hadolint / pre-commit / build-scan)
+```
+
+### 1–2. Pin versions
+
+Add the same value in both places:
+
+```yaml
+# manifest.yaml → build.args
+- FOO_VERSION=1.2.3
+```
+
+```dockerfile
+# Containerfile
+ARG FOO_VERSION=1.2.3
+```
+
+### 3. Binary install example
+
+```dockerfile
+ARG FOO_VERSION=1.2.3
+RUN curl -sSL -o /usr/local/bin/foo \
+      "https://github.com/org/foo/releases/download/v${FOO_VERSION}/foo-linux-amd64" \
+    && chmod +x /usr/local/bin/foo
+```
+
+Install as root in the `base` stage. Do not leave the final stage as root.
+
+**Bun:** use `bun-linux-x64-baseline.zip` (no AVX2 on some runner CPUs).
+
+### 4. OpenAPI npm tools
+
+Versions come from build args. CVE overrides only in `openapi-tools/package.json` (no lockfile).
+
+1. Add `FOO_VERSION` to `manifest.yaml` and `ARG` in Containerfile.
+2. Extend the `npm install --prefix /tmp/openapi-tools` line with `"@scope/pkg@${FOO_VERSION}"`.
+3. Add the binary name to the symlink `for bin in ...` loop.
+4. Add `overrides` only when Trivy reports a fixable transitive CVE.
+
+`oasdiff` is a standalone Go binary — do **not** put it in the npm prefix.
+
+### 5. Renovate
+
+Mirror existing managers in `renovate.json`:
+
+```json
+{
+  "customType": "regex",
+  "description": "Update Foo version",
+  "fileMatch": ["^Containerfile$", "^manifest\\.yaml$"],
+  "matchStrings": ["FOO_VERSION=(?<currentValue>\\S+)"],
+  "depNameTemplate": "org/foo",
+  "datasourceTemplate": "github-releases",
+  "extractVersionTemplate": "^v?(?<version>.+)$"
+}
+```
+
+Adjust `extractVersionTemplate` / `datasourceTemplate` to match upstream tags (see Node / Bun managers).
+
+### 6–7. Docs and validate
+
+- Update the matching table in [README.md](../../../README.md).
+- Run `pre-commit run --all-files` (includes hadolint).
+- Prefer a full build-scan via the [`runner-build-release`](../runner-build-release/SKILL.md) skill before merge.
diff --git a/.agents/skills/runner-build-release/SKILL.md b/.agents/skills/runner-build-release/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: runner-build-release
+description: >-
+  Build, scan, and release the Deerhide python-github-runner OCI image. Use when running
+  local builds, debugging CI/PR validation, semantic-release on main, dive/trivy failures,
+  image tags, or .trivyignore updates.
+---
+
+# Build and release the runner image
+
+## When to use
+
+- Local image build / push
+- PR CI failures (commitlint, hadolint, build-and-scan)
+- Release on `main` (semantic-release + GHCR push)
+- dive efficiency or Trivy HIGH/CRITICAL findings
+- Keywords: `builder.sh`, validate.yaml, release.yaml, GHCR, `.trivyignore`, dive
+
+## Prerequisites
+
+```bash
+# Docker required
+./scripts/install_tools.sh
+skopeo login ghcr.io
+```
+
+Local tool versions from `install_tools.sh` MAY differ from pinned image/CI versions.
+
+## Local full pipeline
+
+```bash
+./scripts/builder.sh
+```
+
+Order: hadolint → buildah (OCI, squashed) → dive → trivy → push to registry from `manifest.yaml`.
+
+Config knobs:
+
+| File | Role |
+| --- | --- |
+| `manifest.yaml` | Name, registry, build args, labels |
+| `.hadolint.yaml` | Containerfile lint |
+| `.dive-ci` | Layer efficiency thresholds |
+| `.trivyignore` | Base-image CVEs with `exp:` dates |
+
+## CI map
+
+| Workflow | Trigger | What it does |
+| --- | --- | --- |
+| `ci.yaml` | PR → `main` | commitlint + calls `validate.yaml` |
+| `validate.yaml` | `workflow_call` | hadolint, buildah build, dive, trivy |
+| `release.yaml` | push → `main` | validate → semantic-release → build & push if new version |
+
+## Image tags (after release)
+
+```
+ghcr.io/deerhide/python-github-runner:latest
+ghcr.io/deerhide/python-github-runner:1
+ghcr.io/deerhide/python-github-runner:1.2
+ghcr.io/deerhide/python-github-runner:1.2.3
+```
+
+## Semantic-release / commits
+
+Conventional Commits drive the bump (commitlint enforced):
+
+| Prefix | Bump |
+| --- | --- |
+| `fix:` | patch |
+| `feat:` | minor |
+| `feat!:` / `BREAKING CHANGE:` | major |
+
+Examples:
+
+```bash
+git commit -m "feat: add kubectl to image"
+git commit -m "fix: correct trivy scan exit code"
+git commit -m "chore: update argo to v4.0.7"
+```
+
+On new version, release workflow updates `CHANGELOG.md`, creates the GitHub release, builds, scans, and pushes semver tags.
+
+## Scan policy
+
+Trivy in this repo:
+
+- Library packages only (`--pkg-types library`)
+- Ignores unfixed vulnerabilities
+- Fails on HIGH/CRITICAL that are not ignored
+
+**When a finding appears:**
+
+1. Prefer upgrade (tool pin / `RUNNER_VERSION` / Renovate PR).
+2. For base-image / upstream-only CVEs that cannot be fixed here: add to `.trivyignore` with `exp:YYYY-MM-DD` and a short comment naming the origin.
+3. MUST NOT add ignores without expiry. Re-evaluate when bumping the base runner.
+
+Dive failures: fix layer bloat in Containerfile (cleanup apt lists, remove temp archives) or adjust `.dive-ci` only with justification.
+
+## Quick checklist
+
+```
+Task progress:
+- [ ] Tools installed (`install_tools.sh`)
+- [ ] Registry login (`skopeo login ghcr.io`)
+- [ ] `./scripts/builder.sh` green locally OR CI validate green
+- [ ] Conventional commit message matches intended bump
+- [ ] New .trivyignore entries have exp: dates (if any)
+```
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,59 @@
+# AGENTS.md — Python GitHub Runner
+
+Always-on orientation for AI agents working in this repo. Read before touching files.
+
+## What this repo is
+
+Self-hosted GitHub Actions runner **container image** for Deerhide / Velmios CI:
+
+- Image: `ghcr.io/deerhide/python-github-runner`
+- Base: `ghcr.io/actions/actions-runner` (`RUNNER_VERSION` in `manifest.yaml`)
+- Includes Python 3.12/3.13 (deadsnakes), Poetry, UV, DevOps CLIs (argo, kargo, kubectl, pack, skopeo, buildah, …), OpenAPI CLIs (redocly, spectral, portman, newman, oasdiff), Node/Bun, and a full OCI build/scan pipeline so the image can build itself.
+
+Tool inventory and version tables live in [README.md](README.md). Do not duplicate them here.
+
+## Directory map
+
+| Path | What lives here |
+| --- | --- |
+| [Containerfile](Containerfile) | Multi-stage image definition (`base` → `runtime`) |
+| [manifest.yaml](manifest.yaml) | Build args, OCI labels, registry, Actions cache list |
+| [openapi-tools/package.json](openapi-tools/package.json) | CVE `overrides` for npm OpenAPI CLIs (no lockfile) |
+| [scripts/](scripts/) | `builder.sh`, `install_tools.sh`, `cache_actions.sh`, helpers |
+| [.github/workflows/](.github/workflows/) | `ci.yaml`, `validate.yaml`, `release.yaml`, nightly/update |
+| [renovate.json](renovate.json) | Regex managers for `*_VERSION=` pins |
+| [.pre-commit-config.yaml](.pre-commit-config.yaml) | hadolint, shellcheck, commitlint, hygiene |
+| [.hadolint.yaml](.hadolint.yaml) | Containerfile lint config |
+| [.trivyignore](.trivyignore) | Base-image CVEs with `exp:` dates |
+| [.dive-ci](.dive-ci) | Dive efficiency thresholds |
+| [.releaserc.yaml](.releaserc.yaml) | semantic-release config |
+
+## Key invariants
+
+- Pin tool versions in **both** `manifest.yaml` `build.args` and `Containerfile` `ARG` defaults. Renovate regex managers match both files.
+- Prefer pinned GitHub-release / curl binary installs over apt. Use apt for OS packages only (skopeo, buildah, jq, trivy apt repo, deadsnakes Python, etc.).
+- OpenAPI npm CLIs: versions come from build args; CVE overrides **only** in `openapi-tools/package.json`. No `package-lock.json`.
+- Pre-cache GitHub Actions listed under `manifest.yaml` `cache.actions` via `scripts/cache_actions.sh` at image build time.
+- Trivy scans library packages only and ignores unfixed vulns. Base-image findings go in `.trivyignore` with `exp:` dates — MUST NOT ignore without expiry.
+- Conventional Commits + commitlint; semantic-release bumps and publishes on push to `main`.
+- Install as root in `base`, then switch to `USER runner`. Final stage MUST NOT stay root (hadolint DL3002).
+- Bun: install `bun-linux-x64-baseline` (runner CPUs may lack AVX2).
+
+## Local validation
+
+```bash
+pre-commit install --hook-type pre-commit --hook-type commit-msg
+pre-commit run --all-files
+./scripts/install_tools.sh
+skopeo login ghcr.io
+./scripts/builder.sh   # hadolint → buildah → dive → trivy → push
+```
+
+## Task → skill index
+
+Skills live under [.agents/skills/](.agents/skills/). Read the matching skill when starting a task:
+
+| Task | Skill |
+| --- | --- |
+| Add or change a CLI/tool in the image (binary, apt, OpenAPI npm, Renovate pin) | [`runner-add-tool`](.agents/skills/runner-add-tool/SKILL.md) |
+| Local build, CI/PR validation, release, dive/trivy failures, semantic-release | [`runner-build-release`](.agents/skills/runner-build-release/SKILL.md) |
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -58,6 +58,7 @@
 
 ### Added
 
+* **docs:** add AGENTS.md and agent skills for adding tools and build/release workflows
 * **ci:** add nightly rebuild workflow to force daily semantic-release/image refreshes when no unreleased commits exist
 
 ### Changed
