local-docker-k3d-alignment - SKILL.md Agent Skill

name: local-docker-k3d-alignment description: When adding or changing preconditions, cleanup steps, or env usage for local Docker Compose or local k3d, keep both in sync where they share resources (e.g. infra/config/local/*.env).

Local Docker vs k3d alignment

When to use

When modifying Makefile targets or scripts that:

Start or stop local Docker Compose services or the local k3d cluster
Read or write infra/config/local/*.env (generated from infra/env/classification/ via scripts/local-env/setup.sh, not from .env.example stubs)
Check for “running” state before running env clean, setup, or reset

Rule

Keep Docker and k3d local behavior aligned where they share resources (e.g. env files). If a target aborts when Docker containers are running, consider aborting when the k3d cluster is running when the same env files are in use. Full teardown / clean targets should also tear down the k3d cluster, not only Docker.

Commands that should consider k3d: (1) Guards: any target that refuses to run while Docker is up and touches shared env (e.g. local_env_clean) should also refuse while k3d is up. (2) Teardown: any "clean" or "full teardown" target (e.g. local_clean) should run local_k3d_down so both Docker and k3d are stopped. (3) Docs: where local env or k3d is described, note shared env and that local_clean tears down both.

Do

infra/config/local/*-sidecar.env vs apps/*/sidecar/.env: local_env_setup generates both with merge-env: infra files use --profile local_docker (Compose env_file); app sidecar/.env files use --profile dev (host npm). They are independent outputs, not copies; do not assume byte parity.
Guard local_env_clean on both Docker Compose containers and the k3d cluster; document that both use infra/config/local/*.env (Postgres: single db.env; Valkey: valkey-source-only.env, valkey.env).
Include k3d in "full teardown" targets: local_clean should run local_k3d_down so Docker, k3d, and test/E2E are all torn down.
When adding a precondition or cleanup step that touches infra/config/local/*.env or “running” state, apply the same logic to both Docker and k3d (or document why they differ).

Don't

Don’t add Docker-only or k3d-only guards for shared env without considering the other (e.g. cleaning env while k3d is up leaves the cluster with stale secrets).

Examples

local_env_clean: Aborts if Boilerplate local containers are running (make local_down) and also if the k3d cluster is running (make local_k3d_down).
local_clean: Full teardown runs local_down, local_down_volumes, local_k3d_down (idempotent if cluster is gone), and test_clean so both Docker and k3d are stopped.
Docs: local_env_setup and local_k3d_up both consume infra/config/local/*.env; mention this where describing local env or k3d setup. Document that make local_clean tears down k3d as well as Docker.