Bootstrap, diagnose (doctor), and reconcile local dev environment from env contract/values/secret refs; generate .env.local and redacted docs/context/env/effective-*. Use when local env is broken or needs syncing.
Make local development environments predictable and self-healing under the repo-env-contract SSOT model.
The env-localctl skill:
env/contract.yaml).env.local or .env.<env>.local)docs/context/env/effective-<env>-<workload>.json)docs/project/policy.yaml (auth_mode/preflight rules)Use the skill only when the project env SSOT mode is .
repo-env-contractTo check the mode, read:
docs/project/env-ssot.jsonIf the project is not in the required mode, STOP.
If docs/project/env-ssot.json does not exist (first-time setup), run:
python3 -B -S .ai/skills/features/environment/env-contractctl/scripts/env_contractctl.py init --root .
Then re-run the local workflow.
Use when the user asks to:
.env.local deterministicallyAvoid when:
env-contractctl)env-cloudctl).env.local)..env.local permissions to 0600.env/contract.yamlenv/values/<env>.yaml (+ optional env/values/<env>.local.yaml for per-developer overrides)env/secrets/<env>.ref.yamldocs/project/policy.yaml (selects auth_mode + preflight rules via env/runtime_target/workload)
runtime_target supports local | ecs (remote is accepted as an alias for ecs)Choose one evidence location (no secrets):
dev-docs/active/<task-slug>/artifacts/env-local/.ai/.tmp/env-local/<run-id>/Evidence files (templates available in ./templates/):
00-prereq-check.md01-auth-and-secrets-check.md02-config-compile-report.md03-connectivity-smoke.md04-post-fix-summary.md.env.local (default for dev) or .env.<env>.localdocs/context/env/effective-<env>-<workload>.json (redacted; safe for LLM)Use the same controller on a deploy machine to render a target env-file without writing repo-local context:
python3 -B -S .ai/skills/features/environment/env-localctl/scripts/env_localctl.py compile \
--root . \
--env staging \
--runtime-target ecs \
--workload api \
--env-file /etc/<org>/<project>/staging.env \
--no-context \
--out <EVIDENCE_DIR>/02-config-compile-report.md
repo-env-contract via docs/project/env-ssot.json.
dev).python3 -B -S .ai/skills/features/environment/env-localctl/scripts/env_localctl.py doctor \
--root . \
--env dev \
--runtime-target local \
--workload api \
--out <EVIDENCE_DIR>/00-prereq-check.md
env/values/dev.yamlenv/values/dev.local.yamlenv/secrets/dev.ref.yamlenv/.secrets-store/dev/<secret_name>.env.local).env.local and redacted context:python3 -B -S .ai/skills/features/environment/env-localctl/scripts/env_localctl.py compile \
--root . \
--env dev \
--runtime-target local \
--workload api \
--out <EVIDENCE_DIR>/02-config-compile-report.md
python3 -B -S .ai/skills/features/environment/env-localctl/scripts/env_localctl.py connectivity \
--root . \
--env dev \
--runtime-target local \
--workload api \
--out <EVIDENCE_DIR>/03-connectivity-smoke.md
.env.local drifted, re-run compile (idempotent). Record 04-post-fix-summary.md.repo-env-contract.env.local generated and gitignoreddocs/context/env/effective-<env>-<workload>.json generated (redacted)node .ai/tests/run.mjs --suite environmentenv/contract.yaml in the env-localctl workflow.