System Environment Setup

System & Environment Setup

Use this skill as the repository's canonical broader environment-setup anchor.

The job is to make a project runnable and repeatable across developer machines and environments. That usually includes some mix of:

• runtime/tool version pinning,
• local services and containers,
• bootstrapping scripts,
• onboarding steps,
• local-prod parity tradeoffs,
• secrets/config handoff boundaries,
• setup diagnosis when automation drifts.

Read references/operating-modes.md and references/scope-boundaries.md before unusual cases or when deciding whether the task belongs here or in environment-setup.

If the user mainly needs:

• `.env` structure, env precedence, validation, or framework-specific app config → route to environment-setup
• CI/CD pipelines and hosted deployment automation → route to deployment-automation or vercel-deploy
• security policy and secret-store architecture → pair with security-best-practices
• project slicing / onboarding checklist ownership → pair with task-planning

When to use this skill

• Make a repo runnable on a fresh machine with consistent tooling
• Standardize local dev setup across multiple contributors
• Choose between local-host, Docker Compose, devcontainers, or hybrid workflows
• Pin runtime/tool versions and reduce cross-machine drift
• Set up local supporting services like databases, caches, queues, or search
• Design bootstrap commands, setup checks, or onboarding flows
• Diagnose why local setup docs, scripts, containers, and actual runtime behavior have drifted apart
• Improve local parity without pretending local and production are identical

When not to use this skill

• The main task is app-level .env organization, env schema validation, or framework env rules → use environment-setup
• The main task is production deployment, cloud rollout, or CI orchestration → use deployment-automation
• The main task is hosted infrastructure security review → pair with security-best-practices
• The task is just one package install with no broader environment decision surface → use a narrower install/setup skill when available

Instructions

Step 1: Classify the setup surface

Normalize the request into this intake first:

environment_intake:
  primary_goal: runnable-local-repo | standardized-onboarding | local-service-parity | toolchain-reproducibility | setup-diagnosis | hybrid
  current_state: greenfield | partially-working | drifted | broken-on-new-machine | unknown
  runtime_shape: single-service | app-plus-services | microservices | unknown
  host_strategy: host-native | docker-compose | devcontainer | hosted-remote-dev | hybrid | unknown
  config_strategy: simple-env-files | typed-validation | secret-manager-injection | mixed | unknown
  main_pain:
    - missing-prereqs
    - runtime-version-drift
    - local-service-startup
    - secrets-bootstrap
    - onboarding-doc-rot
    - cross-platform-differences
    - local-prod-parity
    - unclear
  confidence: high | medium | low

If the request is ambiguous, prefer the broadest runnable repo interpretation and state the assumption.

Step 2: Choose one primary operating mode

Pick exactly one mode for the run:

1. bootstrap-and-onboarding

• Use when the repo needs a clean first-run path for contributors.

2. toolchain-reproducibility

• Use when runtimes, CLIs, or package versions drift between machines.

3. local-services-and-parity

• Use when local DB/cache/queue/search or app-plus-service topology is the main challenge.

4. containerized-dev-environment

• Use when Docker Compose, devcontainers, or Codespaces-style flows are the main lever.

5. setup-diagnosis-and-hardening

• Use when scripts, docs, containers, and actual behavior have drifted apart.

Step 3: Pick the smallest reproducibility stack that solves the problem

Use these rules:

• Prefer the smallest stack that makes the repo reliably runnable.
• Use runtime/version pinning before introducing heavier containers if the repo is simple.
• Use Docker Compose when supporting services or shared local topology matter.
• Use devcontainers when editor/runtime standardization and onboarding speed matter more than host-native ergonomics.
• Keep bootstrap scripts / Makefiles / task runners as glue, not the only source of truth.
• Do not pretend local equals production; name the remaining parity gaps explicitly.
• Route app-level env file design and validation details to environment-setup instead of bloating this skill.

Step 4: Build the environment plan

Return this exact structure:

# Environment Setup Brief

## Recommended mode
- Mode: bootstrap-and-onboarding | toolchain-reproducibility | local-services-and-parity | containerized-dev-environment | setup-diagnosis-and-hardening
- Why this mode fits: ...

## Current setup surface
- Project shape: ...
- Host/container strategy: ...
- Config/secrets strategy: ...
- Main drift or blocker: ...
- Confidence: high | medium | low

## Recommended environment stack
1. ...
2. ...
3. ...

## Commands / files to create or verify

...

## Why this is the right level of setup
- ...
- ...

## Parity gaps to acknowledge
- ...
- ...

## Watch-outs
- ...
- ...

## Adjacent handoff
- Use `environment-setup` for ...
- Use `deployment-automation` for ...
- Use `security-best-practices` for ...

Step 5: Apply mode-specific guidance

For bootstrap-and-onboarding

• Define the one clean happy path first.
• Separate prerequisites, secrets/bootstrap, and verification steps.
• Prefer a setup check (make doctor, bin/setup --check, etc.) when possible.

For toolchain-reproducibility

• Pin runtime versions explicitly.
• Choose one version-management layer per repo when possible.
• Call out cross-platform differences instead of hiding them.

For local-services-and-parity

• Name which services must run locally and which can stay remote.
• Prefer Docker Compose for shared service topology.
• Explain the local-prod gap instead of overselling parity.

For containerized-dev-environment

• Decide whether Compose, devcontainers, or both are necessary.
• Keep secrets/bootstrap out of committed container config unless clearly safe.
• State the editor or platform assumptions.

For setup-diagnosis-and-hardening

• Compare docs, bootstrap scripts, env templates, container files, and actual commands.
• Identify which artifact is authoritative.
• Reduce duplicate instructions and make verification explicit.

Step 6: Keep boundaries sharp

Before finalizing:

• Do not bury .env / env validation details here when the real need belongs in environment-setup.
• Do not turn setup guidance into a cloud deployment tutorial.
• Do not claim total parity if auth, secrets, or platform quirks remain manual.
• Do not let bootstrap scripts become unexplained magic.

Examples

Example 1: Fresh repo onboarding

Input: "Set up this repo so a new developer can run it locally with the right Node version, Postgres, and Redis." Output: chooses bootstrap-and-onboarding, recommends pinned runtime versions plus Compose for local services, and adds a verification path.

Example 2: Containerized local standardization

Input: "Our team wants a devcontainer because everybody's local machine is different." Output: chooses containerized-dev-environment, names which tooling should move into the container, and routes env-file details to environment-setup.

Example 3: Drift diagnosis

Input: "The README says one thing, Docker says another, and new hires still can't run the app." Output: chooses setup-diagnosis-and-hardening, compares setup artifacts, and identifies the authoritative source plus cleanup steps.

Best practices

1. Optimize for a runnable repo, not maximal tooling sophistication. 2. Pick one canonical reproducibility story and make alternatives explicit. 3. Keep secrets/config guidance connected but not conflated with machine/runtime setup. 4. Add a verification step so onboarding is testable. 5. Name parity gaps instead of pretending containers solve everything. 6. Route narrower app-config questions to environment-setup.

References

• Scope boundaries
• Operating modes
• Docker Compose docs
• VS Code dev containers
• GitHub dev containers intro

System Environment Setup Operating Modes

1. bootstrap-and-onboarding

Use when the repo needs a clean first-run path.

Typical ingredients:

• prerequisite list
• version manager or pinned runtime file
• bootstrap script / task runner
• local env template handoff
• verification command (make doctor, bin/setup --check, smoke test)

2. toolchain-reproducibility

Use when the main drift is runtime versions or local CLIs.

Typical ingredients:

• .tool-versions, mise.toml, or equivalent
• install/verify commands
• cross-platform notes
• minimal shell activation guidance

3. local-services-and-parity

Use when the app depends on databases, caches, queues, or search.

Typical ingredients:

• Docker Compose or equivalent
• service startup/health-check commands
• note of what remains remote
• explicit parity gaps

4. containerized-dev-environment

Use when you need standardized editor/runtime environments.

Typical ingredients:

• devcontainer or remote-dev config
• editor assumptions
• secrets/bootstrap boundary
• container vs host workflow notes

5. setup-diagnosis-and-hardening

Use when the setup already exists but drifts.

Typical comparison set:

• README / onboarding docs
• env templates
• bootstrap scripts
• Compose or devcontainer files
• actual commands contributors run

System Environment Setup Boundaries

Use system-environment-setup when the real question is how to make a repo runnable and repeatable across machines.

It owns:

• runtime/tool version pinning
• local supporting services (DB, cache, queue, search)
• Docker Compose and hybrid local stacks
• devcontainers / Codespaces-style environment design
• bootstrap scripts and setup verification
• onboarding and setup-drift diagnosis

Route away when the need changes

App config / .env design

Use environment-setup when the real question is:

• how should .env files be structured?
• which vars belong in templates vs local-only files?
• how do we validate env vars?
• how do we handle framework-specific public/private env behavior?

Deployment and CI

Use deployment-automation when the real question is:

• how do we deploy or promote environments?
• how do CI/CD pipelines inject config or secrets?
• how do we automate rollout and infrastructure changes?

Security policy

Use security-best-practices when the real question is:

• what is the correct secret-management policy?
• how should credentials be rotated or scoped?
• what is the security architecture for env/config handling?

Core rule

system-environment-setup owns the runnable local environment. It should not absorb every app-config or deployment concern that happens to sit nearby.