devcontainer

name	devcontainer
description	Generate a dev container for my project — auto-detect language, framework, and services like PostgreSQL or Redis, create devcontainer.json with VS Code extensions, port forwarding, post-create commands, Docker Compose for multi-service setups, and GitHub Codespaces compatibility
version	2.0.0
category	productivity
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Do NOT pause for confirmation. Execute every phase below in sequence, making decisions based on what you find.

============================================================ PHASE 0 — INPUT

$ARGUMENTS may contain:

• --compose — force Docker Compose-based setup even for single-service projects
• --minimal — generate a lightweight config without extras (no extensions, no features)
• A base image override (e.g., mcr.microsoft.com/devcontainers/python:3.12)

If no arguments, auto-detect everything and generate a full-featured config.

============================================================ PHASE 1 — STACK DETECTION

Detect the project stack by scanning for manifest files:

Language & Runtime:

• package.json → Node.js (read engines.node for version, default 20)
• tsconfig.json → TypeScript project
• pyproject.toml / requirements.txt / Pipfile → Python (read requires-python, default 3.12)
• go.mod → Go (read go directive for version)
• Cargo.toml → Rust
• pubspec.yaml → Flutter/Dart
• Gemfile → Ruby (read .ruby-version for version)

Services:

• docker-compose.yml / docker-compose.*.yml → existing services to integrate
• prisma/schema.prisma → read provider for database type (postgresql, mysql, sqlite, mongodb)
• .env.example → scan for DATABASE_URL, REDIS_URL, MONGO_URI patterns
• pyproject.toml → check for sqlalchemy, django with database backends

Package Manager:

• package-lock.json (npm), yarn.lock (yarn), pnpm-lock.yaml (pnpm), bun.lockb (bun)
• poetry.lock (poetry), Pipfile.lock (pipenv), uv.lock (uv)

Record: language, version, framework, package manager, required services (database, cache, queue).

============================================================ PHASE 2 — GENERATE DEVCONTAINER CONFIG

Create .devcontainer/devcontainer.json:

Base Image Selection (use Microsoft Dev Container images):

• Node.js: mcr.microsoft.com/devcontainers/javascript-node:{version}
• TypeScript: mcr.microsoft.com/devcontainers/typescript-node:{version}
• Python: mcr.microsoft.com/devcontainers/python:{version}
• Go: mcr.microsoft.com/devcontainers/go:{version}
• Rust: mcr.microsoft.com/devcontainers/rust:latest
• Ruby: mcr.microsoft.com/devcontainers/ruby:{version}
• Universal (polyglot): mcr.microsoft.com/devcontainers/universal:2

Dev Container Features (add based on detected stack):

• Docker-in-Docker: ghcr.io/devcontainers/features/docker-in-docker:2 (if Dockerfile exists)
• GitHub CLI: ghcr.io/devcontainers/features/github-cli:1
• Common utilities: ghcr.io/devcontainers/features/common-utils:2
• Node.js (if secondary): ghcr.io/devcontainers/features/node:1
• Python (if secondary): ghcr.io/devcontainers/features/python:1
• AWS CLI: ghcr.io/devcontainers/features/aws-cli:1 (if AWS config detected)

VS Code Extensions (match detected stack):

• Node/TS: dbaeumer.vscode-eslint, esbenp.prettier-vscode, ms-vscode.vscode-typescript-next
• Python: ms-python.python, ms-python.vscode-pylance, charliermarsh.ruff
• Go: golang.go
• Rust: rust-lang.rust-analyzer
• Flutter: Dart-Code.dart-code, Dart-Code.flutter
• Common: eamodio.gitlens, EditorConfig.EditorConfig, usernamehw.errorlens
• Database: mtxr.sqltools + appropriate driver extension
• Docker: ms-azuretools.vscode-docker

Port Forwarding (detect from project):

• Read docker-compose.yml for exposed ports
• Read .env.example for PORT, API_PORT, DB_PORT variables
• Common defaults: 3000 (Node API), 5432 (PostgreSQL), 6379 (Redis), 8000 (Python), 8080 (Go), 27017 (MongoDB)

Post-Create Command:

• Node (npm): npm install
• Node (pnpm): pnpm install
• Node (yarn): yarn install
• Python (pip): pip install -r requirements.txt
• Python (poetry): poetry install
• Python (uv): uv sync
• Go: go mod download
• Rust: cargo fetch
• Flutter: flutter pub get
• If database migrations exist, chain: && npx prisma migrate dev or equivalent

============================================================ PHASE 3 — MULTI-SERVICE SETUP

If the project requires services (database, cache, queue) OR --compose was passed:

Create .devcontainer/docker-compose.yml:

services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - ..:/workspaces/${localWorkspaceFolderBasename}:cached
    command: sleep infinity

Add detected services:

• PostgreSQL: postgres:16-alpine with POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, volume for data persistence
• MySQL: mysql:8 with equivalent config
• MongoDB: mongo:7 with init script volume
• Redis: redis:7-alpine with persistence config
• RabbitMQ: rabbitmq:3-management-alpine with management UI port

Create .devcontainer/Dockerfile using the detected base image with any additional tooling.

Update devcontainer.json to reference docker-compose:

{
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}"
}

If no services are needed, use the simpler image or build approach directly in devcontainer.json.

============================================================ PHASE 4 — CODESPACES COMPATIBILITY

Ensure GitHub Codespaces compatibility:

• Set "hostRequirements" if the project needs more than the default 2-core machine:
  • Projects with Docker-in-Docker or large builds: "cpus": 4
  • AI/ML projects: "cpus": 4, "memory": "8gb"
• Add "codespaces" section if needed for prebuild configuration
• Ensure all paths use ${localWorkspaceFolderBasename} not hardcoded names
• Add .devcontainer/devcontainer.json to .gitattributes as linguist-generated if the file does not exist

Verify the generated config is valid JSON (no trailing commas, proper escaping).

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After completing, validate the output was produced correctly:

1. Verify generated files exist and are syntactically valid.
2. Run any available validation (lint, type-check, dry-run).
3. If the skill produces configuration, verify it parses without errors.

IF VALIDATION FAILS:

• Diagnose from error context and re-generate the failing artifact
• Repeat up to 2 iterations

============================================================ OUTPUT

Print a summary of all generated files:

## Dev Container Setup Complete

### Files Created
- .devcontainer/devcontainer.json — main configuration
- .devcontainer/docker-compose.yml — multi-service orchestration (if applicable)
- .devcontainer/Dockerfile — custom image (if applicable)

### Detected Stack
- Language: {language} {version}
- Framework: {framework}
- Package Manager: {pm}
- Services: {postgresql, redis, etc. or "none"}

### Included Extensions
- {list of VS Code extensions}

### Port Forwarding
- {port}: {service description}

### Post-Create Setup
- {command that runs after container creation}

============================================================ NEXT STEPS

1. Open the project in VS Code and select "Reopen in Container"
2. Or push to GitHub and open in Codespaces
3. Run /env-setup to verify all dependencies and services are working
4. Run /git-hooks to set up pre-commit hooks inside the container

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /devcontainer — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT

• Do NOT use deprecated base images (e.g., vscode/devcontainers — use mcr.microsoft.com/devcontainers)
• Do NOT hardcode secrets or passwords in devcontainer.json — use .env files or Codespaces secrets
• Do NOT include production databases — dev containers are for local development only
• Do NOT add extensions for stacks not detected in the project
• Do NOT overwrite an existing .devcontainer/devcontainer.json without reading it first and preserving custom settings
• Do NOT use root as the container user unless absolutely necessary — prefer the default dev container user
• Do NOT skip port forwarding for detected services — developers expect ports to be accessible