penwyp/claudepreference/local-project-runtime

Local Project Runtime

Use this skill to turn an unknown repository into a locally manageable project with predictable build, start, test, logs, health, and cleanup commands.

Core Workflow

1. Inspect first:

• Read root docs and manifests: README*, AGENTS.md, package.json, lockfiles, Dockerfile, Compose files, Makefile, task runner configs, CI workflows.
• Identify the package manager, runtime, service entrypoint, frontend directories, backend directories, DB/external dependencies, default ports, and health endpoints.
• Check current worktree state before editing.

1. Reproduce narrowly:

• Run the smallest relevant command for the reported failure.
• Capture the exact failing phase: dependency install, typecheck/compile, frontend bundle, Docker image build, container boot, health probe, migration, or test runner.
• Prefer targeted checks before repo-wide verification.

1. Fix architecture, not symptoms:

• Keep build/start/test contracts in one local runtime surface, normally deploy/local/.
• Avoid one-off shell notes that cannot be rerun.
• Make generated scripts explicit, idempotent, and safe when services are absent.

1. Add or repair a lifecycle manager:

• Required commands: init, deps, build, test, image, start, apply, restart, stop, status, logs, ps, clean, doctor.
• start creates services and waits for health.
• apply rebuilds the image and force-recreates the service.
• restart restarts an existing container; if none exists, it must start instead of doing an empty restart.
• status must show Compose state and HTTP health.
• clean must stop services and remove local runtime data only.

1. Add build acceleration where justified:

• For Node/monorepos, add a local build wrapper that hashes frontend inputs and skips frontend production bundling when unchanged.
• Preserve correctness by hashing lockfiles, frontend source/config/public assets, and shared packages imported by the frontend.
• For Docker, split frontend build into its own layer before backend/application COPY . . so backend-only changes reuse frontend layers.
• Update .dockerignore to exclude local build artifacts and caches.

1. Add port and health decisions:

• Keep host port in deploy/local/.env; generate it from .env.example or defaults.
• For a new lifecycle manager, do not default to port 3000. Allocate a random free host port from [30-300] * 100 while excluding 3000, effectively 3100, 3200, ... 30000.
• If deploy/local/runtime/control.sh already exists and deploy/local/.env or .env.example already contains a host port, keep that port and do not allocate a new one.
• If the configured host port is occupied and the project service is not already running, auto-select another free port from the same [30-300] * 100 pool and update public URL.
• Probe health with a bounded retry loop and print recent service logs on failure.
• Use concrete URLs in handoff.

1. Verify end to end:

• Syntax-check generated scripts.
• Validate Compose config.
• Run first build and a second build to prove cache behavior if caching was added.
• Start or apply the service and verify HTTP health.
• Run relevant tests or report why tests were not run.

Bundled Resources

• For lifecycle script semantics and command contracts, read references/lifecycle-manager.md.
• For frontend compile speed, task caching, Docker layer caching, and invalidation rules, read references/build-cache.md.
• For build/start/test failure triage patterns, read references/diagnostics.md.
• For Node/PNPM/NPM/Yarn projects, run or adapt:

node skills/local-project-runtime/scripts/scaffold-node-runtime.mjs --help

The scaffold script is a starting point, not a substitute for repo inspection. Review generated files before final handoff and adjust commands, ports, health paths, service names, and Dockerfile behavior to match the project.