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".
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- decision-noteSkill
- e2e-specSkill
- pull-requestSkill
- release-acceptanceSkill
- release-notesSkill
- test-outlineSkill
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
- Very specific: line 19
No cluster: never run an acceptance task other than task acceptance-validate, never run kubectl or helm.
- Distinctive: line 20
The user validates every scenario: before you write it, and is always invited to add their own.
- Very specific: line 21
The spec is read-only: never edit docs/v3/. A scenario that contradicts it is a question for the user, not a spec change.
- Very specific: line 22
Scenarios stay inside the guard: test objects are those the guard lets through.
- Very specific: line 38
When the tag exists: gh release view v<version> and git log --oneline v<previous>..v<version>.
- Very specific: line 39
When it is not cut yet: git log --oneline v<previous>..origin/main.
- Very specific: line 41
Keep feat, fix and breaking changes.
≈ “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.
Files
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 runkubectlorhelm. The scenarios are checked byrelease-acceptanceon 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-inspectwith--grepand--metrics, orKUBECONFIG=<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-requestskill.
Workflow
1. Inputs
- The new version (for example
3.0.0-alpha.4). Ask if it is missing. - The previous version: the latest
v3.*tag before it (git fetch --tags origin, thengit tag --list 'v3.*' --sort=-v:refname). - Work on a branch off a fresh
origin/main, as thepull-requestskill 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>andgit 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
- 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. - 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 objectskuik-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, andsetupskips without them only the files its skip rules name (11-and13-,14-): any other fixture that uses them fails every run without one, andacceptance-validatecannot see it. A scenario that needs the private repository gets its own numbered fixture, so it keeps its ownsince, and extends the skip rule ofsetup.go(and the Scenarios paragraph of the README) to it: a change named to the user first. Never add it to the11-files, whosesinceis older. - A new kind of test object: extend
guard.go, and the guard section of the README. - An ImageMirror fixture writes to a
.invalidhost. 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 arekuik-test-*Secrets or${PULL_AUTH}, never another Secret.
6. Check
One task per Bash call, and fix what they report in your files:
task acceptance-validate: every fixture decodes, passes the guard and carries itssinceline. No cluster needed.task lint-markdown.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
| Mistake | Fix |
| Writing the scenarios before the user agrees | Draft, ask, iterate; write only the agreed list |
| A scenario per commit | One per behaviour a user can observe; a refactor or a test change has none |
| A scenario only Kind can show | Drop it: the e2e suite covers it |
| A scenario for a fixed behaviour Kind can check | An e2e or envtest spec instead; a scenario only for a use case or what Kind cannot reproduce |
| Duplicating a scenario the release changes | Amend the existing one |
| An expectation without its spec link | Every 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 cover | Extend the skip rule to its own numbered fixture, after asking the user; never grow the 11- files |
| A check that reads a Secret's data | Check its name, type, keys or owner, never its data |
| Running the scenarios to try them | Only task acceptance-validate; the cluster is release-acceptance's job |
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
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.

