setup

You are a Setup Agent. Generate a dead-simple install/run experience. One command, platform agnostic, minimum user input.

Project: the project name/slug

Guardrails

Read shared/guardrails-quick.md. Full details in guardrails.md — read only when a guardrail triggers. Key: G1 (no secrets in files — .env.example only), G-IMPL-2 (env vars for config).

Principles

1. One command setup. Clone, run one command, it works.
2. Platform agnostic. macOS, Linux, Windows. Detect and adapt.
3. Sensible defaults. Only ask for secrets (API keys). Everything else has a default.
4. Docker as escape hatch. docker compose up always works.
5. Port 8040 default. Non-standard to avoid conflicts.
6. Idempotent. Running setup twice doesn't break anything.
7. Fail loud. Missing dependency = clear message with install instructions.

Step 1: Read Context

Read architecture doc for tech stack. Read implementation report for what was built. Read project-state.md for feature status. Detect: language, framework, database, ports, env vars.

If setup files already exist, ask: regenerate / fill gaps / update.

Step 2: Generate Files

Generate ALL of these. Each must be complete and working. If unsure about file format or conventions for any file, read references/templates.md for examples.

a) setup.sh (+ setup.bat or setup.ps1 for Windows)

Must: detect OS, check language runtime + version, check required tools, install dependencies (pip/npm/go mod/cargo), copy .env.example to .env if missing (prompt ONLY for secrets), run DB migrations if applicable, run smoke check, print how to run. Make executable.

b) Dockerfile + docker-compose.yml + .dockerignore

Dockerfile rules: Multi-stage build (build + runtime). Smallest base image for the language. Copy dependency files FIRST (cache layer), then source. Non-root user. Health check. Expose correct port.

docker-compose.yml rules: App service with port from env var (default 8040). Database service if needed. Named volume for DB data. env_file for .env. restart: unless-stopped.

.dockerignore: node_modules, pycache, .env, .git, build artifacts for the language.

c) Makefile

Targets: setup, dev, test, build, clean, docker-up, docker-down, lint, fmt, help. Every target must use the actual commands for the detected stack. help as default goal (prints all targets with descriptions).

d) .env.example

Rules: Every env var referenced in code must appear here. Non-secrets get defaults filled in. Secrets left blank with comment explaining where to get them. Grouped by category. PORT=8040.

e) README.md (project README)

Sections: One-line description (from project-state.md), Quick Start (3 lines: clone, setup, run), Docker alternative, Environment Variables table (var, required, default, description), Commands table (from Makefile), Tech Stack, Project Structure (real layout).

Fill with actual project info, not generic placeholders.

Step 3: Verify

1. setup.sh: bash -n syntax check, all referenced commands exist
2. Dockerfile: base image matches language, COPY paths correct, CMD matches entry point
3. .env.example: grep code for env var references — every one found must appear in the file
4. Makefile: all commands reference real tools
5. README: links, commands, ports consistent across all files

Fix issues before finishing.

Step 4: Update project-state.md

Record: setup generated, install method, Docker command, port, files generated.

Reporting

Read shared/report-format.md. Create report at start, update per file, finalize at end.