auto-env

Auto-env

Use this skill when you need to turn a repository into a usable development or verification environment. The primary output is an environment contract that tells a human or downstream agent how to run commands in the configured environment. Smoke testing is required evidence that the environment works, but end-to-end product testing is a downstream consumer of this skill rather than the skill's core job.

Operating Rules

1. Start from the environment goal: what command, service, CLI, or workflow needs to run after setup.
2. Read obvious setup surfaces before guessing: README, package manifests, lockfiles, Makefiles, language build files, Dockerfiles, compose files, and env templates.
3. Discover environment variables quickly and narrowly. Prefer authoritative templates and docs over broad source greps.
4. Prefer the minimal reproducible setup that leaves the repo usable for follow-up development. Do not over-provision services or delete build artifacts.
5. Use Docker when isolation, reproducibility, or dependency setup matters. Use an existing user-provided environment when the user already gave one.
6. Never claim the environment is ready without concrete smoke-test evidence from commands, logs, HTTP responses, screenshots, or generated artifacts.
7. Always leave behind environment.md, environment.json, and artifacts/command-log.txt in the output directory you create for the run.

Workflow

1. Resolve the target repository. Default repo to the current workspace when no path or URL is named.
2. Create an output directory, usually .dev-output/auto-env/<repo>-<timestamp>/, with an artifacts/ subdirectory.
3. Inspect setup surfaces in this order:
   • README or setup docs
   • .env.example, .env.sample, .env.template, or similar
   • docker-compose.yml, compose.yml, Dockerfiles, devcontainer files
   • package/build manifests such as package.json, pyproject.toml, requirements.txt, Cargo.toml, go.mod, Makefile, or justfile
   • targeted source/config search only when the above are insufficient
4. Build an env-var inventory:
   • Include required and optional variables that affect startup, external services, auth, providers, databases, or cloud resources.
   • Exclude ordinary runtime/tooling variables such as PATH, HOME, TERM, CI, DEBUG, NODE_ENV, and test-only variables unless the project explicitly requires them for startup.
   • If a required secret is missing, record it as a blocker or ask only for the minimal set needed for the requested environment goal.
5. Choose the setup strategy:
   • Existing Dockerfile or compose stack when it already models the app.
   • Minimal base container when the repo has no usable Docker setup but isolation is valuable.
   • Existing local shell only when the user requested local setup or the current host environment is the intended environment.
6. Configure the environment:
   • Install only needed system packages, language runtimes, and project dependencies.
   • Build or prepare the project enough for development and smoke testing.
   • Keep source, .git, dependency caches, and build artifacts that make the environment useful.
7. Define the run contract:
   • Record workdir, command template, env vars, ports, services, and how to open a shell.
   • If a Docker container or image was created, record its name and the exact docker exec or docker run command to reuse it.
   • If the project has a natural entrypoint, record the command that forwards user args to it.
8. Smoke-test the environment using the smallest command that proves it works, such as CLI --help, build/test startup, HTTP health check, or page load.
9. Fill the environment artifacts and summarize the readiness status from those artifacts.