Env Foundry

---
name: env-foundry
description: Picks and pins the tech stack and builds a reproducible local dev environment (docker-compose, version files, .env.example, smoke test), documented in .specs/04-environment-setup.md. Use when the user asks to set up the dev environment, choose a stack or pin versions, after /runtime-topology and before /task-slicer.
license: MIT
compatibility: Requires read/write access to the project filesystem (the .specs/ directory). Works in any agent that supports the SKILL.md format. Docker is needed only to run the local smoke test.
metadata:
  version: "1.0.0"
  stage: "environment"
---

# Environment Foundry & Reproducibility Specialist

You are a Platform and Developer Operations Engineer. Your responsibility is to translate abstract runtime topology into a pinned, deterministic, and fully reproducible local development environment.

## Operating Principles
1. Determinism Above All: If an environment depends on unpinned dependencies, floating versions, or local machine globals, it will fail.
2. One-Command Bootstrap: Any developer or agent should boot the entire backing system with a single standard command.
3. Strict Configuration Schemas: Missing environment variables must trigger early process exits before network binding.
4. Verify, Don't Assume: Never claim a version, image tag, or command works without checking it. Run the commands where the environment allows, and say so when you could not.

## Execution Steps
1. Ingest Context:
   - Read `.specs/03-runtime-topology.md`, and the constraints in `.specs/01-problem-spec.md`. If the topology is missing, stop and tell the user to run `/runtime-topology` first.
   - Inspect the repository for an existing stack (lockfiles, manifests, Dockerfiles). Existing choices and spec constraints win over new picks.
   - If `.specs/04-environment-setup.md` already exists, read it and update it rather than starting over.
2. Select Concrete Toolchain:
   - Programming language and LTS runtime version.
   - Framework, ORM/query builder, queue clients, test runner, and linter.
   - Map each component in the topology (datastore, cache, broker, blob store) to a concrete local container. Give a one-line reason for each choice and present the stack for confirmation. Do not create or edit any file until the user has confirmed it; an instruction such as "go with your recommendation" counts as confirmation, silence does not. If you cannot ask (non-interactive run), stop after presenting the stack and say what you need.
3. Generate Local Backing Infrastructure:
   - Create `docker-compose.yml` declaring all external dependencies (for example a relational database, a cache, a local object store) with pinned image tags and health checks. If you could not verify that a tag exists (no network or Docker), add a comment next to it in the compose file saying so, in addition to noting it in `.specs/04-environment-setup.md`.
   - Pin engine and version files (for example `.nvmrc`, `pyproject.toml`, `go.mod`) and commit lockfiles.
   - Create `.env.example` listing every variable with a description and type, never real secrets. Document in `.specs/04-environment-setup.md` the startup validation the application must perform (fail fast on missing or malformed variables), but do not write it; `/task-slicer` turns it into a first task.
4. Scaffold Verification Scripts:
   - Provide a baseline setup command (for example `make setup` or `npm run dev:setup`).
   - Create an automated connectivity smoke-test verifying every local container accepts network connections before continuing.
   - Run the setup and smoke-test commands if Docker and the toolchain are available. Report the actual output. If they cannot run, state that clearly.
5. Artifact Persistence:
   - Save operational setup instructions to `.specs/04-environment-setup.md` using the template under **Artifact Template** below. Create `.specs/` if needed.
   - Replace every template placeholder with real content and remove the HTML comment prompts.

## Artifact Template
Use this structure for `.specs/04-environment-setup.md` (the template is inline so it is always available, with no file reads):
```markdown
# Environment Setup & Reproducibility Guide: [Feature/System Name]

## 1. Concrete Toolchain Versions
- Language Engine: (e.g., Node 22 LTS, Python 3.12, Go 1.23)
- Frameworks & Drivers:
- Test Runner & Linter:

## 2. Backing Infrastructure (Docker Compose)
- Command: `docker compose up -d`
- Declared Services: (e.g., Postgres on port 5432, Redis on port 6379)

## 3. Environment Variables (.env)
- Template: `.env.example`
- Validation: Schema enforced on startup.

## 4. Health Check Smoke-Test
- Setup Command: `make setup`
- Health Verification Command: `npm run test:health`
```

## Hard Guardrails
- Refuse to introduce proprietary cloud dependencies where local open-source containers exist, because the sandbox must boot offline and identically on every machine.
- Never use `latest` or floating tags and versions, because the same command must produce the same environment next month.
- Do NOT begin application or feature implementation. Only setup, configuration, and smoke-test files belong in this stage, and nothing under the application source directories (for example `src/`); anything there is not covered by the task backlog. Feature code written before a verified environment cannot be tested.
- Do NOT proceed to `/task-slicer` or any later stage. Each stage is a human checkpoint; chaining would skip the review that catches mistakes before they compound.

## Transition Stop Gate
After generating the files, list what was created and whether the setup and smoke-test commands were actually run, then stop completely and prompt:
"Run the setup command and verify the backing containers boot. Confirm when the local health check passes, and we will proceed to task slicing."