Local Runtime Harness

---
name: local-runtime-harness
description: 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 runtime debugging instructions.
---

# Local 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

1. Define local prerequisites.
   - Package manager and runtime versions.
   - Required services.
   - Required environment variables.

2. Create stable runtime scripts.
   - `scripts/dev`
   - `scripts/healthcheck`
   - `scripts/db-reset` when a database exists.
   - `scripts/seed` when seed data exists or is needed.
   - `scripts/logs` when logs are inspectable locally.
   - For databases or queues, add a readiness wait before any push, migrate, reset, or seed operation.

3. Create environment docs.
   - `.env.example` with non-secret example values.
   - `docs/development/environment.md`.
   - `docs/development/local-setup.md`.

4. 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_isready` when available; otherwise use `assets/templates/wait-for-port.sh.tmpl` as the target repo pattern.

5. 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-generator` to create `project-runtime-debugging` when runtime docs and commands are stable enough for a repo-local skill.

## Runtime Rules

- Never commit real secrets.
- Preserve existing `.env.example` values 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/dev` if feasible and stop it cleanly.
- Run `./scripts/healthcheck`.
- Run reset/seed commands for databases when safe.
- Confirm `.env.example` and 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.