Repository Guidelines

Project Structure & Module Organization

Core manifests: main.tf wires providers, workspace.tf defines the agent, and services.tf/apps.tf supply optional containers and apps.citeturn0search11
scripts.tf maps Terraform to scripts/*.sh; add entries to locals.workspace_agent_scripts and keep those scripts idempotent because agents rerun them.
terraform.tfvars carries defaults; store environment overrides in separate *.auto.tfvars.
Workspace image comes from ../.devcontainer/Dockerfile; after edits rebuild, retag, and bump var.devcontainer_image so Terraform targets a ready registry image.citeturn0search5

terraform init — rerun after changing required_providers.
terraform fmt -recursive — enforce two-space indentation before committing.
terraform validate — catch schema or variable issues early.
terraform plan -var-file=terraform.tfvars -out plan.tfplan — review planned changes; share the summary in reviews.
docker build -t <registry>/<image>:<tag> -f ../.devcontainer/Dockerfile .. then docker push — refresh the devcontainer base before updating devcontainer_image.citeturn0search5

Follow Terraform style: snake_case for locals/variables, singular resource names (coder_agent.main), and kebab-case for Docker/Coder name/slug fields.
Group locals by concern and comment non-obvious transformations (e.g., startup script assembly).
Keep required_providers aligned with Coder template defaults so coder and docker stay pinned.citeturn0search11
Bash scripts must start with #!/usr/bin/env bash and set -euo pipefail; prefer functions for reusable logic.

Run terraform fmt -check and terraform validate locally and in CI.
Exercise feature toggles with targeted plans, e.g. terraform plan -var enable_services=false.
When services are enabled, run bash scripts/port-forward.sh inside the workspace to confirm pgAdmin and Qdrant forwards.
Skip committing plan.tfplan; attach terraform show plan.tfplan output in PRs.

History is absent here; default to Conventional Commits (feat:, fix:, chore:) used across Coder templates.
Scope commits narrowly and reference modules in the subject, e.g. fix: tighten docker socket handling in workspace.tf.
PRs should note the user impact, include relevant terraform plan excerpts, call out service toggle defaults, and link tracking issues.

Never commit secrets: provide gitea_pat, github_pat, or service passwords via overrides or template environment variables.
When mount paths or ports move, update matching Terraform locals and scripts so port forwarding and health checks stay aligned.
Rebuild the devcontainer image separately; this module assumes var.devcontainer_image already bundles required toolchains.
Rely on registry scanning and caching; Coder guidance expects hardened, prebuilt images before workspaces launch.citeturn0search2