udecodeudecode/better-convex/.agents/skills/scenarios/SKILL.md

scenarios

Skill452 starsChanged 23 days agoApache-2.0View on GitHub

Prove kitcn fixture and scenario runtime the right way. Use when validating prepared scenario apps, auth smoke and browser lanes, or deciding whether a scenario key should use `scenario:dev` or `scenario:check`.

We split this skill into the rules it gives an agent

12 rules. 0 are common, 6 are distinctive, and 6 are very specific to this project.

0
Common
Most of the 4 edited versions we read keep these.
6
Distinctive
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

Distinctive:
Use this skill for committed fixture checks and runtime proof of prepared scenarios.
line 12
Very specific:
Use committed fixtures/* only as sources.
line 17
Distinctive:
Stop once the assigned proof path succeeds.
line 19
Very specific:
Never run committed fixtures/* in place.
line 24
Very specific:
Always prepare into tmp/scenarios/<name>/project.
line 25
Distinctive:
Stop spawned dev processes once proof succeeds or fails.
line 28
Very specific:
If a temp app is stale after package or scaffold changes, rerun bun run scenario:prepare -- <name> once.
line 29
Distinctive:
If a scenario has no real browser auth surface, do not invent one.
line 32
Distinctive:
Use this path for:
line 61
Distinctive:
Wait for ready logs.
line 73
Very specific:
Do not fake test:e2e.
line 125
Very specific:
Do not add test:auth here unless the registry grows a dedicated auth proof lane.
line 126

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “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

Scenarios

Use this skill for committed fixture checks and runtime proof of prepared scenarios.

Contract

Pick the proof path from the registered scenario key.
Use committed fixtures/* only as sources. The runnable app lives under tmp/scenarios/*.
Stop once the assigned proof path succeeds. Do not keep poking the app for sport.

Hard Rules

Never run committed fixtures/* in place.
Always prepare into tmp/scenarios/<name>/project.
fixtures:* owns committed snapshot sync/check.
scenario:* owns runnable temp apps.
Stop spawned dev processes once proof succeeds or fails.
If a temp app is stale after package or scaffold changes, rerun bun run scenario:prepare -- <name> once. If it still fails, debug the cause. Do not loop forever.
If a scenario has no real browser auth surface, do not invent one.
For bootstrap-heavy Convex lanes, bun run scenario:check -- <name> is the proof. Do not replace it with ad-hoc scenario:dev.

Canonical Commands

bun run fixtures:sync
bun run fixtures:check
bun run scenario:prepare -- <name>
bun run scenario:dev -- <name>
bun run scenario:check -- <name>
bun run scenario:test -- <name>
bun run test:runtime
bun run test:auth -- <name|url>
bun run test:e2e -- <name|url>

test:auth and test:e2e assume the scenario is already running. scenario:test wraps the proof matrix below. test:runtime runs scenario:test -- all and is the default non-browser runtime gate. test:e2e is a separate auth browser lane and should be run only when auth surfaces changed.

Proof Matrix

Plain runtime proof

Use this path for:

next
vite
create-convex-bare
create-convex-nextjs-shadcn
create-convex-react-vite-shadcn

Run:

bun run scenario:prepare -- <name>
bun run scenario:dev -- <name>
Wait for ready logs.
Stop.

Or:

bun run scenario:test -- <name>

Auth demo proof

Use this path for:

next-auth
start-auth

Run:

bun run scenario:prepare -- <next-auth|start-auth>
bun run scenario:dev -- <next-auth|start-auth>
bun run test:auth -- <next-auth|start-auth>
Stop.

Or:

bun run scenario:test -- <next-auth|start-auth>

Why:

scenario:test -- <next-auth|start-auth> proves runtime + auth smoke only.
Browser auth proof belongs to the explicit test:e2e lane:
1. bun run scenario:prepare -- <next-auth|start-auth>
2. bun run scenario:dev -- <next-auth|start-auth>
3. bun run test:e2e -- <next-auth|start-auth>

Auth backend proof without browser auth

Use this path for:

vite-auth

Run:

bun run scenario:prepare -- vite-auth
bun run scenario:dev -- vite-auth
Stop.

Or:

bun run scenario:test -- vite-auth

Why:

There is no /auth page or equivalent browser auth surface today.
Do not fake test:e2e.
Do not add test:auth here unless the registry grows a dedicated auth proof lane.

Bootstrap-heavy Convex proof

Use this path for:

convex-next-auth-bootstrap
convex-vite-auth-bootstrap
convex-next-all
create-convex-nextjs-shadcn-auth

Run:

bun run scenario:check -- <name>
Stop.

Or:

bun run scenario:test -- <name>

Why:

Fresh kitcn lanes already bootstrap during scenario:prepare through kitcn init -t <next|vite> --yes, then finish the bootstrap-heavy proof with in-place kitcn init --yes after plugin setup.
The raw Convex auth adoption lane still owns convex init plus kitcn add auth --preset convex --yes.
Raw Convex auth adoption is not a next-auth browser demo. Do not invent /auth.

Re-prepare Rule

Re-run scenario:prepare once when:

package or scaffold source changed
the temp app predates that change
the temp app is missing expected local env or generated files

Otherwise, reuse the prepared app.

Examples

`next-auth` or `start-auth`

bun run scenario:prepare -- next-auth
bun run scenario:dev -- next-auth
bun run test:auth -- next-auth

Short path:

bun run scenario:test -- next-auth

Browser lane:

bun run scenario:prepare -- next-auth
bun run scenario:dev -- next-auth
bun run test:e2e -- next-auth

`vite-auth`

bun run scenario:prepare -- vite-auth
bun run scenario:dev -- vite-auth

Short path:

bun run scenario:test -- vite-auth

`convex-next-all`

bun run scenario:check -- convex-next-all

Short path:

bun run scenario:test -- convex-next-all

Download now (ZIP)

Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
Autonoma-AI/autonoma★ 242same name
hass-energy/haeo★ 72same name
jantichy/claude★ 45same name
envisioning/skills★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository54 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- .agents/skills/autoreview/AGENTS.mdAGENTS.md
- .agents/skills/autoreview/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- 4-ultraciteSkill
- agent-browser-issueSkill
- agent-native-reviewerSkill
- architecture-cleanupSkill
- autoclosureSkill
- autogoalSkill
- autoreviewSkill
- autoSkill
- avoid-feature-creepSkill
- better-auth-best-practicesSkill
- changeset-doc-syncSkill
- changeset-resolveSkill
- changesetSkill
- component-colocationSkill
- concave-paritySkill
- concaveSkill
- convex-release-auditSkill
- designSkill
- deslopSkill
- diagnosing-bugsSkill
- find-skillsSkill
- grill-with-visionSkill
- hard-cutSkill
- jotai-xSkill
- kitcnSkill
- linear-backlogSkill
- major-taskSkill
- next-dev-loopSkill
- nextjsSkill
- orchestratorSkill
- package-release-auditSkill
- prototypeSkill
- react-querySkill
- research-wikiSkill
- resolve-pr-feedbackSkill
- resolving-merge-conflictsSkill
- shadcn-paritySkill
- sync-convex-authSkill
- sync-visionSkill
- taskSkill
- tddSkill
- testingSkill
- toastSkill
- to-milestoneSkill
- to-prdSkill
- turborepoSkill
- video-transcriptsSkill
- visionSkill
- walkthroughSkill

Does it work?

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

Reviews can't be read right now.

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.

Check your setup, free

12 rules. 0 are common, 6 are distinctive, and 6 are very specific to this project.

Scenarios

Contract

Hard Rules

Canonical Commands

Proof Matrix

Plain runtime proof

Auth demo proof

Auth backend proof without browser auth

Bootstrap-heavy Convex proof

Re-prepare Rule

Examples

next-auth or start-auth

vite-auth

convex-next-all

Word for word · 0

Edited · 0

Wrote their own version · 4

Does it work?

Your trail

Now do this for your own.

`next-auth` or `start-auth`

`vite-auth`

`convex-next-all`