agentleFS
enixenix/kube-image-keeper/.claude/skills/acceptance-scenarios/SKILL.md

acceptance-scenarios

Skill759 starsChanged yesterdayMITView on GitHub

Use when asked to prepare, write or update the acceptance scenarios (or acceptance tests) of a kuik v3 release before its acceptance run, for example "prepare the acceptance scenarios of kuik 3.0.0-alpha.4" or "write the acceptance tests for the next alpha".

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No cluster: never run an acceptance task other than task acceptance-validate, never run kubectl or helm.

    line 19
  2. Distinctive:

    The user validates every scenario: before you write it, and is always invited to add their own.

    line 20
  3. Very specific:

    The spec is read-only: never edit docs/v3/. A scenario that contradicts it is a question for the user, not a spec change.

    line 21
  4. Very specific:

    Scenarios stay inside the guard: test objects are those the guard lets through.

    line 22
  5. Very specific:

    When the tag exists: gh release view v<version> and git log --oneline v<previous>..v<version>.

    line 38
  6. Very specific:

    When it is not cut yet: git log --oneline v<previous>..origin/main.

    line 39
  7. Very specific:

    Keep feat, fix and breaking changes.

    line 41

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

kuik acceptance scenarios of a release

Overview

Prepares, when the maintainer asks for new scenarios, the scenarios the release-acceptance skill will run on a shared cluster. A release behaviour no scenario covers is no reason to write one: it usually belongs in an e2e spec, and the acceptance report lists it for the maintainer to decide. A scenario is a user story in scenarios.md: what a user does, what they expect with its docs/v3/ link, and the commands that prepare and check it, so a human could run it by hand. Its fixture lives under test/acceptance/fixtures/ (note 0015).

You draft; the user decides which scenarios exist. Nothing is written before they agree.

New scenarios go in their own pull request. A behaviour change that makes an existing scenario, fixture or guard comment of test/acceptance/ wrong updates it in the pull request of that behaviour, not here (for example the ImageMirror finalizer that stopped waiting for pods updated scenarios 14 and 23 in #829); a change with no acceptance effect leaves those files alone. A guard.go change in a behaviour pull request still needs task acceptance-approve at the next acceptance run, until it is on origin/main.

Hard rules

  • No cluster: never run an acceptance task other than task acceptance-validate, never run kubectl or helm. The scenarios are checked by release-acceptance on a shared cluster where the release is deployed, after review; never on a throwaway cluster.
  • The user validates every scenario before you write it, and is always invited to add their own.
  • The spec is read-only: never edit docs/v3/. A scenario that contradicts it is a question for the user, not a spec change.
  • Scenarios stay inside the guard: test objects are those the guard lets through. A new kind of test object extends the guard in guard.go, a reviewed code change you name to the user first.
  • Check commands only read: task acceptance-inspect with --grep and --metrics, or KUBECONFIG=<path> kubectl --context <name> get ... -o jsonpath=.... Never a command that reads a Secret's data.
  • No push: the work ends in local commits, handed to the pull-request skill.

Workflow

1. Inputs

  1. The new version (for example 3.0.0-alpha.4). Ask if it is missing.
  2. The previous version: the latest v3.* tag before it (git fetch --tags origin, then git tag --list 'v3.*' --sort=-v:refname).
  3. Work on a branch off a fresh origin/main, as the pull-request skill says.

2. What changed

There is no changelog file: the release notes are the GitHub release body, generated by semantic-release from the conventional commits (.releaserc.mjs).

  • When the tag exists: gh release view v<version> and git log --oneline v<previous>..v<version>.
  • When it is not cut yet: git log --oneline v<previous>..origin/main.

Keep feat, fix and breaking changes; keep a chore, docs or test commit only when it changes what a user sees (a chart value, a metric). Open the pull request, the code at the tag or docs/v3/ where a commit is unclear.

3. What a user can observe

Acceptance scenarios are the user stories kuik is sold for: the documented use cases under docs/use-cases/, each played end to end on a real cluster with real registries. Keep a change only when it adds or changes a documented use case, or when it depends on what Kind cannot reproduce: real registries and their quirks (Harbor, Docker Hub quotas, ECR, private registries, corporate CAs), the real install (GitOps, an upgrade from the previous release, several replicas, existing admission policies), coexistence with real workloads, operations (real metrics, logs, restarts).

A precise behaviour (an event, a reason, an annotation, a counter), a bug fix's included, is no scenario: it gets an e2e spec or an envtest spec instead (the e2e-spec skill). For each change kept, write what the user does and sees along the use case.

Then read scenarios.md:

  • a change that alters an existing scenario amends it (its expectation, its check); it does not duplicate it;
  • a scenario the release makes obsolete is proposed for removal;
  • a "scenarios to add" section of the last acceptance report, if the user has one, is input too.

4. Draft and ask

Show the draft as a numbered list, one scenario per item: The user, They expect (each point with its docs/v3/ link) and the fixture it needs, in a few lines. Then ask the user, with AskUserQuestion or plain questions:

  • which to keep, drop or change;
  • what they want checked on every release that is not in the list: invite their own scenarios explicitly.

Iterate until the user agrees with the whole list. STOP at each round and wait for the answer.

5. Write

  1. In scenarios.md, one section per scenario, numbered after the last one, with its fields in order: Since (the new version), The user, They expect, Prepare, Do, Check, Explore. Copy the shape of an existing section; amend the scenarios step 4 changed.
  2. Each new fixture is test/acceptance/fixtures/<NN>-<slug>.yaml, <NN> the scenario number. Its first line is # since: <version>. It uses ${KUIK_NAMESPACE} instead of the kuik namespace, and names its test objects kuik-test-*. A scenario that reuses a fixture names it in Prepare and adds none. ${PRIVATE_REPO} and ${PULL_AUTH} are set only on a run with a private repository, ${MIRROR_PREFIX} only on a run with --mirror-prefix, and setup skips without them only the files its skip rules name (11- and 13-, 14-): any other fixture that uses them fails every run without one, and acceptance-validate cannot see it. A scenario that needs the private repository gets its own numbered fixture, so it keeps its own since, and extends the skip rule of setup.go (and the Scenarios paragraph of the README) to it: a change named to the user first. Never add it to the 11- files, whose since is older.
  3. A new kind of test object: extend guard.go, and the guard section of the README.
  4. An ImageMirror fixture writes to a .invalid host. One that must copy for real needs --mirror-prefix, a registry path the user dedicates to the test on every run: name it to the user first. Credentials are kuik-test-* Secrets or ${PULL_AUTH}, never another Secret.

6. Check

One task per Bash call, and fix what they report in your files:

  1. task acceptance-validate: every fixture decodes, passes the guard and carries its since line. No cluster needed.
  2. task lint-markdown.
  3. task lint, when a Go file changed.

7. Hand over

Commit a change to the program (guard.go, a skip rule of setup.go, a new fixture variable, any Go file or the Taskfile) in its own commit, then the scenarios as test(e2e): add the acceptance scenarios of <version>. The branch can run on the shared cluster with the release-acceptance skill before its pull request opens, once the release is deployed there: fixtures and Markdown need no approval, a program change one task acceptance-approve for the whole run, after the agent explains it. Then hand over to the pull-request skill.

Common mistakes

MistakeFix
Writing the scenarios before the user agreesDraft, ask, iterate; write only the agreed list
A scenario per commitOne per behaviour a user can observe; a refactor or a test change has none
A scenario only Kind can showDrop it: the e2e suite covers it
A scenario for a fixed behaviour Kind can checkAn e2e or envtest spec instead; a scenario only for a use case or what Kind cannot reproduce
Duplicating a scenario the release changesAmend the existing one
An expectation without its spec linkEvery point of They expect links its docs/v3/ section
${PRIVATE_REPO} or ${PULL_AUTH} in a fixture the skip rule of setup.go does not coverExtend the skip rule to its own numbered fixture, after asking the user; never grow the 11- files
A check that reads a Secret's dataCheck its name, type, keys or owner, never its data
Running the scenarios to try themOnly task acceptance-validate; the cluster is release-acceptance's job

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.