| name | experiment-bootstrap |
| description | Bootstrap new repo experiments with the red conventions for folder layout, runtime config, testing, and compose-based e2e. |
Experiment Bootstrap
Use this skill when starting a new experiment under experiments/, or when
standardizing an existing one onto the repo's experiment conventions.
Workflow
- Create the experiment under
experiments/<name>/.
- Use a thin root with
src/, compose/, README.md, Dockerfile, docker-compose.yml, package.json, tsconfig.json, and a local bun.lock.
- Keep source layout singular:
src/service/ for runtime services and adapters
src/store/ for persistence abstractions
src/util/ for config, errors, and shared types
src/test/ for tests and fixtures
- Keep HTTP routes thin; push behavior into services.
- Use Hono for web routes, Bun for runtime, Biome for lint/format, and
just for commands.
- Make Compose strict: explicit env vars, fail-fast startup, and health checks that wait for readiness.
- Prefer test-only fixtures over test-only state mutation routes. Delivery sinks may be fake; lifecycle transitions should be service-driven.
- Verify the experiment with typecheck, tests, and compose E2E before calling it ready.
Conventions
Read the experiment checklist before scaffolding
or refactoring an experiment.