Bootstrap project environment

Bootstrap Project Environment

Run a project from cold start with the smallest safe Docker path: dependency inventory, Compose selection, startup, smoke tests, and team setup docs.

Hard Rules

• Prefer Docker/Compose over host package installs.
• Reuse existing Compose files before creating any new file.
• Never delete volumes, databases, caches, or object storage data.
• Never copy real secrets into docs; write variable names and placeholders.
• Never silently change ports or upgrade middleware major versions.
• Try at most 3 fixes for the same error, then stop and record the blocker.
• For external API keys, check variable presence only unless the user explicitly asks for live calls.

Read references/docker-compose-policy.md before creating or changing Compose files, running startup, or writing smoke/setup docs.

Workflow

1. Inventory dependencies

Inspect the lightest reliable sources first:

• README*, AGENTS.md, AGNET.md
• docs/external-deps.svg, existing docs/env-checklist.md
• docker-compose*.yml, docker-compose*.yaml, Dockerfile*
• .env.example, .env.*, sample configs
• build/runtime manifests such as pom.xml, application*.yml, package.json, requirements*.txt, pyproject.toml, go.mod, composer.json

Create or update docs/env-checklist.md. For every dependency, include name, major version, default port, connection info, initialization requirements, and source evidence. Classify each dependency as compose-covered, compose-missing, external-api, or host-tooling.

2. Choose the Docker path

• If existing Compose covers app plus middleware, reuse it.
• If existing Compose is missing required middleware, add the smallest docker-compose.deps.yml overlay.
• If no Compose exists, create docker-compose.dev.yml.
• Validate with docker compose config; fall back to docker-compose config only when needed.

Write docs/install-log.md with the selected Compose file, rationale, images, ports, volumes, init actions, and any fixes. For Docker flows, this is the equivalent of a host install-log.md.

3. Start services

Use up -d. Wait for readiness with healthchecks first, then container status, ports, and logs. Run migrations only through existing project mechanisms; do not duplicate entrypoint migrations.

Write docs/startup-log.md with commands, service states, URLs, ports, errors, and fixes.

4. Smoke test

Select 3-5 core checks from API docs, routes, README, and visible ports:

• frontend or homepage
• API health or basic endpoint
• key middleware connectivity
• one core business read-only path where credentials exist

Skip authenticated flows when no test credential exists. Do not call destructive, payment, messaging, external-write, or data-mutating endpoints.

Write docs/smoke-test-result.md with command, status, response summary, and pass/fail for each check.

5. Write team setup guide

Generate docs/setup-guide.md from docs/install-log.md, docs/startup-log.md, and docs/smoke-test-result.md.

Include prerequisites, one-command startup, dependency summary, environment variables, initialization notes, common problems, smoke checklist, and stop/restart/status commands.

Completion

Before reporting done, verify:

• expected docs exist
• Compose was reused when sufficient
• no secret values were copied
• no new Compose file was created unnecessarily
• smoke results distinguish passed, failed, and skipped checks