Creating a scene

Creating a scene

Add a new folder to this repository. The Yanjú CLI does not ship scene files; it reads index.yaml and fetches that folder.

The harness never imports scenario Python and never assumes FastAPI or Nginx. Any stack that Compose can run is fine.

1. Name the folder

Folder name equals scenario.yaml name and the index.yaml id.

2. Required files

• scenario.yaml
• docker-compose.yaml
• every path listed in workspace.copy
• eval/ pytest that reads YANJU_BASE_URL (skip the module if that env var is unset)

3. Optional files

• chaos/ plus chaos.command in the manifest
• docker-compose.k6.yaml and load/
• extra images used only as build context (not copied)

Do not list eval/, chaos/, load/, docker-compose.k6.yaml, or images/ in workspace.copy.

4. scenario.yaml fields

• name, title, summary
• brief.problem, brief.outcome
• images
• workspace.copy
• compose.file, compose.project
• health.service
• ports
• verify.base_url (and optional verify.timeout_sec)
• optional chaos.command

Also add a folder README.md with the title, summary, problem, expected outcome, and:

yanju init <id>
yanju play

Do not list README.md in workspace.copy. Init still generates the candidate README.

5. Briefs stay spoiler-free

brief.problem, brief.outcome, index.yaml summary, and the folder README state the symptom and the desired HTTP outcome only. Do not name the root cause.

Avoid tokens such as: N+1, JOIN, prefetch, connection leak, finally, OOM, 137, TTL, lock, stampede, poison, NACK, DLQ, public key, private key, volume.

6. Eval grades HTTP only

Hidden tests talk to YANJU_BASE_URL. They never read candidate source, Docker inspect, or SQL. Any valid fix that restores the HTTP behavior (and latency under load, if you assert it) passes.

7. Unique project and port

Give the scene its own compose.project and host port so leftover stacks do not collide with other scenes.

8. Catalog

Append a row to index.yaml and a one-line bullet to this repo’s README.md.

9. Checklist

• Folder name matches name and id
• Copy paths exist and exclude hidden prefixes
• Brief, summary, and folder README have no spoilers
• Folder README.md exists and is not in workspace.copy
• Unique compose project and host port
• CLI layout tests updated if the suite asserts catalog ids