local-runtime-harness
Make a project reproducible and inspectable locally for coding agents. Use when a repo needs dev server scripts, .env.example, Docker Compose, seed/reset commands, health checks, local logs, or runtim
SKILL.mdskills/local-runtime-harness/SKILL.md
GitHubLocal Runtime Harness
Purpose
Give agents runtime reality: a way to boot the app, reproduce bugs, inspect behavior, reset state, and verify fixes locally.
Inspect First
- existing dev scripts and package manager
- env vars, secret usage,
.env*files, and.gitignore - database, queues, caches, external services, Docker files
- app URLs, ports, API health routes, log output
- seed data and migrations
Procedure
Define local prerequisites.
- Package manager and runtime versions.
- Required services.
- Required environment variables.
Create stable runtime scripts.
scripts/devscripts/healthcheckscripts/db-resetwhen a database exists.scripts/seedwhen seed data exists or is needed.scripts/logswhen logs are inspectable locally.- For databases or queues, add a readiness wait before any push, migrate, reset, or seed operation.
Create environment docs.
.env.examplewith non-secret example values.docs/development/environment.md.docs/development/local-setup.md.
Add local services when justified.
- Use Docker Compose for local databases or queues if project-native setup does not already exist.
- Keep external hosted services optional in local dev when possible.
- Use a stack-native readiness check such as
pg_isreadywhen available; otherwise useassets/templates/wait-for-port.sh.tmplas the target repo pattern.
Add diagnostics.
- Healthcheck command should verify the main app or API is reachable.
- Logs command should expose local logs without requiring external observability platforms.
- Use
project-local-skill-generatorto createproject-runtime-debuggingwhen runtime docs and commands are stable enough for a repo-local skill.
Runtime Rules
- Never commit real secrets.
- Preserve existing
.env.examplevalues and add missing keys. - Prefer deterministic reset and seed commands over manual setup notes.
- Document ports and URLs explicitly.
- Database reset order is: start service, wait until ready, apply schema or migrations, seed when configured, run healthcheck.
Validation
- Run
./scripts/devif feasible and stop it cleanly. - Run
./scripts/healthcheck. - Run reset/seed commands for databases when safe.
- Confirm
.env.exampleand environment docs match.
Completion Criteria
- A new agent can boot the repo locally or has a precise blocker.
- Local state can be reset safely.
- Runtime inspection is documented with commands, ports, and expected output.