@mrciphersmith/keryx 0.3.1 → 0.3.3

package/src/gdskills/bundled/stacks/docker-k8s-terraform/governance/scout.json

@@ -0,0 +1,16 @@
+[
+  {
+    "query": "Use when reviewing a Dockerfile, Docker Compose file, Kubernetes/Helm manifest, or Terraform change for security and config-authoring risks -- root containers, unpinned base images, secrets baked into image layers, missing Kubernetes securityContext/NetworkPolicy, and Terraform state/secrets handling. Read-only, no edits.",
+    "decision": "create",
+    "topMatch": "docker-k8s-terraform/docker-k8s-terraform-build-fix",
+    "recordedAt": "2026-09-25T15:30:30.700Z",
+    "skillName": "docker-k8s-terraform-review"
+  },
+  {
+    "query": "Use when a Docker build fails, a Kubernetes/Helm manifest is rejected by validation or the API server, or a Terraform validate/plan fails -- resolves the actual root cause (a bad COPY path, an ownership/permission mismatch after switching to a non-root USER, a schema-invalid manifest, a Terraform state/address mismatch) with the smallest fix, never a suppression.",
+    "decision": "create",
+    "topMatch": "ci-github-gitlab/ci-pipeline-build-fix",
+    "recordedAt": "2026-09-25T15:30:36.249Z",
+    "skillName": "docker-k8s-terraform-build-fix"
+  }
+]

package/src/gdskills/bundled/stacks/docker-k8s-terraform/pack.json

@@ -0,0 +1,46 @@
+{
+  "id": "docker-k8s-terraform",
+  "family": "tool",
+  "modules": ["docker-k8s-terraform-rules", "docker-k8s-terraform-skills"],
+  "detectionMarkers": ["docker", "docker-compose", "terraform"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 338, Wave 4 batch 6"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": [],
+    "test": [],
+    "review": ["docker-k8s-terraform-review"],
+    "build-fix": ["docker-k8s-terraform-build-fix"],
+    "migrate": []
+  },
+  "notes": {
+    "implement": "No implement skill authored in this batch. W1-stack-catalog.md's target-stack table gives the reason as \"config authoring lives in the deploy quality skill\" -- that does not hold up: `src/gdskills/bundled/skills/quality/deploy/SKILL.md` is scoped to running a deployment pipeline/release (\"Use when deploying a release to any environment\"), not authoring Dockerfiles/K8s manifests/Terraform configs. No existing catalog skill actually covers authoring these files. This is a genuine, honestly-deferred gap, not a covered case -- left for a future batch, and W1-stack-catalog.md's table entry needs its own correction (tracked in that doc's flow 338 review-round notes).",
+    "test": "No separate test skill in this batch. This is a scope deferral, not an absence of a real concept: Terraform has `terraform test` (`.tftest.hcl` run blocks) and Helm has `helm test` (chart-defined test hooks) plus the community `helm-unittest` plugin (template unit tests with no cluster required) -- both are genuine, analogous to what go-testing/python-testing cover for their stacks. `docker-k8s-terraform-build-fix`'s reproduce-and-classify step covers running an EXISTING validator (hadolint, kubeconform/kubeval, `terraform validate`/`plan`) to diagnose a failure, which is a different job from writing/extending `.tftest.hcl` or helm-unittest test suites. Left for a future batch.",
+    "migrate": "No migrate skill in this batch. This is a scope deferral, not an absence of real migration concepts: Kubernetes API version deprecations (e.g. a manifest still on `apps/v1beta1` needing `apps/v1`), a Terraform provider major-version upgrade with its own breaking-change/state-migration steps, and a Helm chart's own major-version upgrade path are all genuine, recurring migration shapes for this family -- none was concrete/scoped enough to write a focused skill and eval suite around in this batch. Left for a future batch, not claimed as nonexistent."
+  },
+  "agentProfile": {
+    "displayName": "Docker / Kubernetes / Terraform",
+    "auditFocus": [
+      "a container image actually running as root -- no USER instruction AND no evidence the base image already defaults to a non-root user (see rules/patterns.mdc), or an explicit USER root reintroduced after a non-root user was already set -- or a Kubernetes securityContext missing runAsNonRoot/allowPrivilegeEscalation: false",
+      "a base image pinned only by a mutable tag (`FROM node:20`) instead of an immutable digest (`FROM node:20@sha256:...`)",
+      "a secret (API key, password, token) baked into an image layer via ARG/ENV/COPY instead of a build-time secret mount or runtime injection",
+      "a Kubernetes Pod/Deployment with no resource requests/limits, no readOnlyRootFilesystem, or capabilities not dropped to the minimum the container needs",
+      "a namespace or workload with no default-deny NetworkPolicy, or one scoped too broadly to serve as a real boundary",
+      "a Terraform resource or module with a hardcoded credential/connection string in `.tf`/`.tfvars`, a `sensitive = true` value treated as if that alone encrypted it, or state configured with a local/unencrypted backend"
+    ],
+    "buildCommands": [
+      "hadolint <Dockerfile> (when hadolint is available)",
+      "docker build . (or docker compose build for a compose project)",
+      "kubeconform -strict -summary <manifest-or-dir> (or kubeval, whichever the project already uses)",
+      "terraform validate && terraform plan (only plan, never apply, from this skill)"
+    ],
+    "fixGuardrails": [
+      "Never remove a USER/securityContext non-root setting, drop a NetworkPolicy, or relax a capability drop just to make a build/deploy pass.",
+      "Never bake a secret into an image layer (ARG/ENV/COPY of a credential) to route around a missing runtime secret — use a build-time secret mount or say the runtime wiring is still needed.",
+      "Never commit or read a `.tfstate` file as the source of truth for a fix, and never suggest disabling remote state locking to unblock a run.",
+      "Never widen a Terraform `sensitive = true` removal or a K8s NetworkPolicy loosening to silence a validator finding without saying so in the report."
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/docker-k8s-terraform/rules/coding-style.mdc

@@ -0,0 +1,74 @@
+---
+extends: common
+paths: ["**/Dockerfile", "**/Dockerfile.*", "**/*.Dockerfile", "**/*.dockerfile", "**/Containerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose.yml", "**/compose.yaml", "k8s/**/*.yaml", "k8s/**/*.yml", "manifests/**/*.yaml", "manifests/**/*.yml", "deploy/**/*.yaml", "deploy/**/*.yml", "overlays/**/*.yaml", "**/kustomization.yaml", "**/kustomization.yml", "helm/**/*.yaml", "helm/**/templates/*.yaml", "charts/**/*.yaml", "charts/**/templates/*.yaml", "charts/*/values.yaml", "**/*.tf", "**/*.tfvars"]
+metadata:
+  origin: authored
+---
+
+# Docker / Kubernetes / Terraform coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to the file shapes
+this pack owns: Dockerfiles, Docker Compose files, Kubernetes/Helm YAML, and
+Terraform. Applies only to those file types — not to application source code
+under any of these directories.
+
+## Dockerfile
+
+- Order instructions from least to most frequently changing (base image,
+  system packages, dependency manifests, dependency install, then source
+  copy) so Docker's build cache is invalidated only by the layer that
+  actually changed, not by every layer after a source edit.
+- Use multi-stage builds (`FROM ... AS builder`, then a slim final stage
+  that copies only the built artifact) for any compiled or bundled
+  language — the build toolchain never belongs in the shipped image.
+- Prefer a minimal, actively maintained base image (`-slim`/`-alpine`, or a
+  distroless/hardened image) over a full OS image unless the project
+  genuinely needs the extra tooling at runtime.
+- One logical concern per `RUN` line where it aids readability, but chain
+  related package-manager commands (`apt-get update && apt-get install
+  -y ... && rm -rf /var/lib/apt/lists/*`) into a single `RUN` so the
+  package cache does not persist as a separate layer.
+- Ship a `.dockerignore` alongside the Dockerfile that excludes `.git/`,
+  `node_modules/`/`vendor/` (rebuilt inside the image), and any local
+  env/secret file — an unfiltered build context both bloats the image and
+  risks copying something that should never leave the host.
+
+## Docker Compose
+
+- Pin every service's `image:` the same way a Dockerfile's `FROM` is
+  pinned (a tag, or a digest for anything security-sensitive) — never
+  `image: latest` in a committed compose file.
+- Keep secrets and per-environment values in `.env`/`environment:` sourced
+  from the shell or a secrets file that is itself gitignored, not
+  hardcoded into `docker-compose.yml`.
+- Name every custom network and volume explicitly rather than relying on
+  Compose's default naming, so multi-project setups do not collide.
+
+## Kubernetes and Helm
+
+- One resource kind's concerns per manifest file where the project's
+  layout allows it (a Deployment, its Service, its ConfigMap as separate
+  files or a clearly delimited multi-document YAML) rather than one
+  sprawling file mixing unrelated workloads.
+- Set explicit `resources.requests`/`resources.limits` on every container
+  — an unbounded container can starve its node's other workloads, and the
+  scheduler cannot place it sensibly without a request.
+- Use a Helm `values.yaml` (or Kustomize overlay) for anything that varies
+  per environment — a hardcoded namespace, hostname, or replica count
+  inside a template defeats the point of templating.
+- Label and select consistently (`app.kubernetes.io/name`,
+  `app.kubernetes.io/instance`) so Services, NetworkPolicies, and
+  `kubectl` tooling can all select the same workload by the same labels.
+
+## Terraform
+
+- Organize a module around `main.tf`/`variables.tf`/`outputs.tf` (plus
+  `versions.tf` pinning the provider and Terraform version) rather than
+  one large file mixing resource definitions with variable declarations.
+- Name resources and variables for what they are (`aws_db_instance.orders`,
+  not `aws_db_instance.db1`), and give every variable a `description` and,
+  where one exists, a `type` constraint — an untyped variable defers a
+  typo to `apply` time instead of `plan`/`validate` time.
+- Prefer a module for any resource group reused across environments
+  (`modules/network`, `modules/service`) over copy-pasted `.tf` blocks per
+  environment directory.

package/src/gdskills/bundled/stacks/docker-k8s-terraform/rules/patterns.mdc

@@ -0,0 +1,81 @@
+---
+extends: common
+paths: ["**/Dockerfile", "**/Dockerfile.*", "**/*.Dockerfile", "**/*.dockerfile", "**/Containerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose.yml", "**/compose.yaml", "k8s/**/*.yaml", "k8s/**/*.yml", "manifests/**/*.yaml", "manifests/**/*.yml", "deploy/**/*.yaml", "deploy/**/*.yml", "overlays/**/*.yaml", "**/kustomization.yaml", "**/kustomization.yml", "helm/**/*.yaml", "helm/**/templates/*.yaml", "charts/**/*.yaml", "charts/**/templates/*.yaml", "charts/*/values.yaml", "**/*.tf", "**/*.tfvars"]
+metadata:
+  origin: authored
+---
+
+# Docker / Kubernetes / Terraform patterns
+
+Structural patterns for building, orchestrating, and provisioning
+containerized workloads with this pack's three file types. Complements
+`rules/coding-style.mdc` (formatting/organization) with the shape decisions
+that are harder to fix after the fact.
+
+## Multi-stage build as the default shape
+
+A build stage that needs a compiler, a package manager's dev dependencies,
+or test tooling should never be the stage that ships. Structure:
+
+```dockerfile
+FROM node:22-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build && npm run test
+
+FROM node:22-slim AS runtime
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+CMD ["node", "dist/index.js"]
+```
+
+The `runtime` stage never sees the source tree's dev dependencies, test
+files, or build toolchain — only what `COPY --from=build` explicitly
+carries over.
+
+## Config and code stay separate
+
+A Kubernetes `ConfigMap`/`Secret` or a Terraform variable exists so the same
+image/module deploys to more than one environment without a rebuild or a
+hand edit. A hardcoded hostname, replica count, or connection string inside
+a Deployment template or a `.tf` resource block is a sign the value belongs
+in a `values.yaml`, a `ConfigMap`, or a `variable` block instead.
+
+## Least-privilege as the default, not an add-on
+
+- A container's Dockerfile ends with a non-root `USER` instruction (or the
+  base image's own non-root default is kept, not overridden back to root)
+  — see `rules/security.mdc` for the full non-root/capability rationale.
+- A Kubernetes workload requests only the RBAC verbs/resources it actually
+  calls — a ServiceAccount bound to a namespace-wide `edit`/`cluster-admin`
+  role because the specific permission set was not worked out is a pattern
+  to flag, not a shortcut to accept.
+- A Terraform IAM/role resource is scoped to the specific actions and
+  resource ARNs the workload needs, not a wildcard `"*"` action or
+  resource granted because narrowing it took more iteration.
+
+## Idempotent, declarative infrastructure
+
+- A Terraform module should be safely re-appliable: no `null_resource` or
+  `local-exec` provisioner standing in for a resource Terraform's provider
+  already models directly, and no resource whose creation depends on
+  something outside Terraform's own state (a manually-created bucket
+  referenced by name instead of imported or created by the module).
+- A Kubernetes manifest describes the desired end state (replica count,
+  image tag, resource limits) rather than an imperative sequence of
+  `kubectl` commands baked into a CI script — prefer `kubectl apply -f`
+  (or a GitOps controller) over a hand-run sequence of `create`/`patch`
+  commands that drift from the checked-in manifest.
+
+## Module and environment layout
+
+Prefer one Terraform module per reusable resource group (`modules/vpc`,
+`modules/eks-cluster`) instantiated per environment (`environments/staging`,
+`environments/production`) with environment-specific variables, over a
+single flat set of `.tf` files gated by `count`/`var.environment ==
+"production"` conditionals scattered through the resources themselves — the
+conditional form makes it easy for one environment's change to silently
+affect another's plan.

package/src/gdskills/bundled/stacks/docker-k8s-terraform/rules/security.mdc

@@ -0,0 +1,146 @@
+---
+extends: common
+paths: ["**/Dockerfile", "**/Dockerfile.*", "**/*.Dockerfile", "**/*.dockerfile", "**/Containerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose.yml", "**/compose.yaml", "k8s/**/*.yaml", "k8s/**/*.yml", "manifests/**/*.yaml", "manifests/**/*.yml", "deploy/**/*.yaml", "deploy/**/*.yml", "overlays/**/*.yaml", "**/kustomization.yaml", "**/kustomization.yml", "helm/**/*.yaml", "helm/**/templates/*.yaml", "charts/**/*.yaml", "charts/**/templates/*.yaml", "charts/*/values.yaml", "**/*.tf", "**/*.tfvars"]
+metadata:
+  origin: authored
+---
+
+# Docker / Kubernetes / Terraform security
+
+Narrows `core-common-rules`' stack-agnostic security rules to the risks
+specific to building images, running them on Kubernetes, and provisioning
+infrastructure with Terraform. This skill's scope is the source files
+(Dockerfile, compose, manifests, `.tf`) — a built image's own vulnerability
+scan is `security-audit`'s job, not this rule's.
+
+## Non-root by default
+
+- Every Dockerfile either ends with a `USER` instruction naming a non-root
+  user (one created with `RUN useradd`, or the base image's own built-in
+  unprivileged user re-selected explicitly, e.g. `USER nginx`), or keeps a
+  base image's own non-root default un-overridden. A missing `USER`
+  instruction is not by itself proof of root — some base images (e.g.
+  `nginxinc/nginx-unprivileged`) already default to a non-root user with
+  no `USER` line needed — but it is not proof of non-root either; confirm
+  what the base image's own default actually is (its Dockerfile/docs, or
+  `docker run --rm <image> whoami`) rather than assuming either way from
+  the absence of a `USER` line alone.
+- The matching Kubernetes `securityContext` sets `runAsNonRoot: true`,
+  `allowPrivilegeEscalation: false`, and drops all capabilities
+  (`capabilities.drop: ["ALL"]`), adding back only the specific ones the
+  container actually needs (e.g. `NET_BIND_SERVICE` to bind a low port).
+  A `privileged: true` container is a last resort that needs its own
+  justification in the change, never a default reached for to make a
+  permission error disappear.
+- Set `readOnlyRootFilesystem: true` where the workload allows it, mounting
+  a scoped `emptyDir`/`tmpfs` for the specific paths that need to be
+  writable at runtime (`/tmp`, a cache directory) rather than leaving the
+  whole filesystem writable because one path needs to be.
+
+## Pin base images by digest, not tag alone
+
+A mutable tag (`FROM node:22`, `FROM node:22-slim`) can point at a
+different image tomorrow than it does today — the base image is not
+actually pinned until the digest is. For anything security-sensitive
+(a production image, a CI build step that must be reproducible), pin with
+the immutable digest:
+
+```dockerfile
+FROM node:22-slim@sha256:<digest>
+```
+
+A tag alone is acceptable for local/throwaway development; flag a
+digest-less `FROM` in a Dockerfile that is clearly meant to ship.
+
+## Never bake a secret into an image layer
+
+`ARG`/`ENV` values, and anything `COPY`'d into an image, persist in that
+layer even if a later layer deletes or overwrites the file — a secret
+baked in during an early `RUN`/`COPY` is still recoverable from the image's
+layer history. Use BuildKit's build-time secret mount instead, which never
+writes the secret into a layer:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+RUN --mount=type=secret,id=npm_token \
+    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
+```
+
+Runtime secrets (a database password, an API key a running container
+needs) belong in a Kubernetes `Secret` (or the platform's secret store),
+mounted as a file or environment variable at run time — never baked into
+the image `ENV` at build time.
+
+## Kubernetes network boundaries
+
+A namespace with no `NetworkPolicy` allows every pod to reach every other
+pod by default — that is Kubernetes' actual default, not a hardened one.
+Start from a default-deny policy and open only the specific paths a
+workload needs:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: default-deny
+spec:
+  podSelector: {}
+  policyTypes: ["Ingress", "Egress"]
+```
+
+then a second, narrower `NetworkPolicy` per workload allowing only the
+`podSelector`/`namespaceSelector` traffic it actually needs. Flag a
+namespace shipping workload manifests with no accompanying `NetworkPolicy`
+at all, and flag a per-workload `NetworkPolicy` broad enough to defeat the
+point of having one -- a `spec.ingress` entry that is a single EMPTY rule
+object (`ingress: [{}]`, no `from`/`ports` inside it) matches every source
+on every port, i.e. allow-all, not the deny-all the pattern above depends
+on (NetworkPolicy is fail-closed: `policyTypes: ["Ingress"]` with `ingress`
+omitted or `ingress: []` means NO ingress rule matches, which is deny-all
+-- do not confuse an EMPTY `ingress:` array with an array containing one
+EMPTY rule object; they are opposite policies), or a `podSelector: {}` on a
+policy meant to be workload-scoped (matches every pod in the namespace,
+not just the intended workload).
+
+## Terraform state and secrets
+
+- Configure a remote backend with encryption at rest and state locking
+  (e.g. an S3 backend with `encrypt = true` and `use_lockfile = true` for
+  native S3-object-based locking — the current recommended approach,
+  superseding a separate DynamoDB lock table for new configurations,
+  though an existing DynamoDB-locked backend is not itself a problem to
+  flag on its own; or an HCP Terraform/Terraform Cloud workspace, which
+  encrypts state and locks automatically) — a local `terraform.tfstate` is
+  both unencrypted on disk and a single point of loss/corruption with no
+  locking against concurrent runs.
+- Renaming or moving a resource/module block in configuration changes its
+  address, which makes an unrelated `terraform plan` show a destroy-then-
+  recreate for a resource nothing actually changed about (state still has
+  it under the old address) — fix with a `moved` block (`moved { from =
+  <old_address> to = <new_address> }`, declarative, stays in the
+  configuration for the next person who reads it) or the equivalent
+  `terraform state mv <old_address> <new_address>` (imperative, a one-off
+  CLI operation) — never by applying the destroy/recreate plan as-is for a
+  resource holding real data.
+- A `force_destroy = true` on a resource that can hold data (an S3 bucket,
+  in particular) lets `terraform destroy`/a replacement delete a
+  non-empty bucket without the safety error Terraform would otherwise
+  raise — flag it on any resource whose data matters, especially paired
+  with a `moved`/`state mv` scenario where the goal is to KEEP the
+  existing data, not clear the way for a fresh create.
+- Never commit a `.tfstate`/`.tfstate.backup` file to version control —
+  state routinely contains resource attributes in plaintext (a generated
+  password, a connection string) even when the variable that produced them
+  was declared `sensitive`.
+- Mark any variable or output that carries a credential, connection
+  string, or key `sensitive = true` so Terraform redacts it from CLI plan
+  output and logs — but treat `sensitive = true` as a **display**
+  protection, not an encryption one: the value is still written to state
+  in plain form, and `terraform output <name>` still prints a sensitive
+  output's value by name. Encryption-at-rest for that value comes from the
+  backend configuration above, not from the `sensitive` flag.
+- Never hardcode a credential directly in a `.tf`/`.tfvars` file — source
+  it from a secrets manager data source (Vault, AWS Secrets Manager/SSM
+  Parameter Store) or an injected environment variable, the same rule
+  `core-common-rules` already states for application source code, applied
+  here to infrastructure code.

package/src/gdskills/bundled/stacks/docker-k8s-terraform/rules/testing.mdc

@@ -0,0 +1,61 @@
+---
+extends: common
+paths: ["**/Dockerfile", "**/Dockerfile.*", "**/*.Dockerfile", "**/*.dockerfile", "**/Containerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose.yml", "**/compose.yaml", "k8s/**/*.yaml", "k8s/**/*.yml", "manifests/**/*.yaml", "manifests/**/*.yml", "deploy/**/*.yaml", "deploy/**/*.yml", "overlays/**/*.yaml", "**/kustomization.yaml", "**/kustomization.yml", "helm/**/*.yaml", "helm/**/templates/*.yaml", "charts/**/*.yaml", "charts/**/templates/*.yaml", "charts/*/values.yaml", "**/*.tf", "**/*.tfvars"]
+metadata:
+  origin: authored
+---
+
+# Docker / Kubernetes / Terraform validation
+
+This pack ships no separate `test` skill yet (see `pack.json`'s
+`notes.test` — genuine test-writing concepts exist for this family,
+`terraform test`/`.tftest.hcl` and `helm test`/helm-unittest chief among
+them; the deferral is a scope decision for this batch, not a claim that no
+such concept exists). What this rule covers instead is VALIDATION: a
+static, tool-driven check that an existing file is well-formed and
+schema-correct, exercised from `docker-k8s-terraform-build-fix`'s own
+reproduce-and-classify step. This rule states what "validated" means for
+each file type so that step — and any manual check — has a concrete bar.
+
+## Dockerfile and Compose
+
+- `hadolint <Dockerfile>` when the project has hadolint configured (a
+  `.hadolint.yaml` present, or the tool available on PATH) — catches
+  missing pins, `apt-get` without `--no-install-recommends`, and other
+  Dockerfile-specific lint findings before a build is even attempted.
+- `docker build .` (or `docker compose build` for a multi-service project)
+  must exit 0 with no `--no-cache` needed to reproduce a passing state —
+  a build that only succeeds from a stale cache is not actually validated.
+- For a compose project, `docker compose config` validates the merged
+  Compose file parses and every referenced `.env` variable resolves,
+  before attempting `up`.
+
+## Kubernetes and Helm
+
+- `kubeconform -strict -summary <manifest-or-dir>` (or `kubeval`, whichever
+  the project already has configured) validates every manifest against the
+  Kubernetes API schema for the cluster's target version — a manifest that
+  parses as YAML can still fail this (unknown field, wrong type) and
+  should not be treated as validated on YAML-parse success alone.
+- `helm template <chart> | kubeconform -strict` for a Helm chart — template
+  rendering can itself fail (a missing `values.yaml` key with no default)
+  independently of the rendered manifests' own schema validity, so both
+  failure modes need to be distinguished when reporting a finding.
+- `kubectl apply --dry-run=server -f <manifest>` (or `--dry-run=client` when
+  no live cluster is reachable) catches a resource the API server would
+  reject that schema validation alone does not (an immutable field on an
+  existing resource, a missing CRD).
+
+## Terraform
+
+- `terraform fmt -check` and `terraform validate` are the syntax/internal-
+  consistency floor — both must pass before a `terraform plan` is
+  attempted, since `validate` catches type errors and missing required
+  arguments that `plan` would otherwise fail on less legibly.
+- `terraform plan` (never `apply` from this pack's skills) shows the actual
+  proposed change; a plan showing an unexpected destroy/replace on a
+  resource the change was not meant to touch is a validation failure in
+  its own right, not just a formality to skip past.
+- A policy check (`conftest`/OPA, or the project's own policy tool) when
+  one is configured — treat its findings the same as a schema-validator
+  finding, not as optional advice to skip under time pressure.

package/src/gdskills/bundled/stacks/docker-k8s-terraform/skills/docker-k8s-terraform-build-fix/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: docker-k8s-terraform-build-fix
+description: "Use when a Docker build fails, a Kubernetes/Helm manifest is rejected by validation or the API server, or a Terraform validate/plan fails -- resolves the actual root cause (a bad COPY path, an ownership/permission mismatch after switching to a non-root USER, a schema-invalid manifest, a Terraform state/address mismatch) with the smallest fix, never a suppression. Not for an application-code build failure unrelated to these config files (a Go/TypeScript/Python compile or test error) -- that is the language's own build-fix skill's territory, even when this pack's Dockerfile happens to build that language's code."
+triggers:
+  - "docker build is failing"
+  - "fix this Kubernetes manifest validation error"
+  - "terraform plan wants to destroy and recreate this resource"
+  - "terraform validate is failing"
+  - "this Dockerfile permission denied error"
+  - "kubectl apply is rejecting this manifest"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Docker / Kubernetes / Terraform build fix
+
+Resolve a `docker build` failure, a Kubernetes/Helm manifest rejected by
+schema validation or the API server, or a `terraform validate`/`plan`
+failure — with the smallest change that fixes the actual root cause.
+`rules/coding-style.mdc` and `rules/security.mdc` govern what a "correct"
+fix looks like; this skill never reaches for a suppression or a shortcut
+that undoes a prior security fix (reverting to root, disabling a lint rule,
+forcing an unreviewed apply) instead of fixing what actually broke.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+```bash
+docker build .                      # or: docker compose build
+kubeconform -strict -summary <manifest>   # or: kubectl apply --dry-run=server -f <manifest>
+terraform validate && terraform plan
+```
+
+Read the exact error text and classify it:
+
+- **Docker build error** (a `COPY`/`ADD` path that does not exist in the
+  build context, a missing `.dockerignore` exclusion breaking a needed
+  file, a package-manager install failure, a permission-denied write after
+  switching to a non-root `USER`).
+- **Kubernetes/Helm validation error** (an unknown field, a wrong type, a
+  Helm template rendering failure from a missing `values.yaml` key, or a
+  live API-server rejection such as an immutable field on an existing
+  resource).
+- **Terraform error** (a type mismatch or missing required argument
+  `validate` catches, a provider/version constraint conflict, or a `plan`
+  showing an unexpected destroy/replace after a resource rename or
+  refactor).
+
+### Step 2: Fix by category
+
+**Docker build error:** for a missing `COPY`/`ADD` source, check the build
+context and `.dockerignore` before assuming the file is genuinely absent —
+a `.dockerignore` entry that is too broad is a common real cause. For a
+permission-denied write after a `USER` switch to a non-root user, fix
+ownership at copy time (`COPY --chown=<user>:<group> ...`) or with an
+explicit `RUN chown`/`mkdir -p` step **before** the `USER` instruction
+switches away from root — never fix it by reverting to `USER root` or by
+running `chmod 777` on the directory; both undo the non-root hardening
+this pack's security rule requires instead of fixing the actual ownership
+mismatch.
+
+**Kubernetes/Helm validation error:** for a schema error, fix the field
+name/type the validator names — do not delete the offending field to make
+the validator stop complaining if the field is actually required for the
+workload to function correctly. For a live API-server rejection on an
+immutable field (e.g. a Deployment's selector), the fix is usually to
+recreate the resource under change management (a new name, or a deliberate
+delete+recreate the team has agreed to), not to strip the field or force
+an update that the API server is correctly refusing.
+
+**Terraform error:** for a type/argument error, fix the resource/variable
+declaration `validate` names. For an unexpected destroy+recreate after a
+rename or a module refactor, relink the existing real resource to its new
+configuration address — either a `moved` block (`moved { from =
+<old_address> to = <new_address> }`, declarative, stays in the
+configuration) or the equivalent `terraform state mv <old_address>
+<new_address>` (imperative, a one-off CLI operation) — never accept the
+destroy+recreate plan with `-auto-approve` (or any unreviewed apply) for a
+stateful resource just to make the plan "go through"; that actually
+destroys and rebuilds the real infrastructure the rename was never meant
+to touch.
+
+### Step 3: Verify
+
+```bash
+docker build .                      # or: docker compose build
+kubeconform -strict -summary <manifest>
+terraform validate && terraform plan
+```
+
+Re-run the specific command whose failure this fix addresses, plus any
+project-configured validator (`hadolint`, `helm template | kubeconform`).
+All must exit 0 — and for the Terraform case, `terraform plan` must show
+no destroy/replace on the resource the fix was meant to preserve — before
+reporting done.
+
+### Step 4: Report
+
+```
+Fixed: Dockerfile permission-denied write to /app after switching to
+  USER app
+  - Root cause: files were COPY'd while still root, so `app` had no
+    write access to /app
+  - Fix: added --chown=app:app to the COPY instruction (no chmod, no
+    reverting to root)
+  - docker build . passes
+```
+
+State the root cause in one sentence, not just "fixed the error."
+
+## Rules
+
+- Find and fix the smallest change that addresses the actual root cause —
+  never widen a fix beyond what the failure requires.
+- NEVER fix a permission-denied error by running `chmod 777` or reverting
+  to `USER root` — fix ownership at the actual `COPY`/`RUN` step instead.
+- NEVER accept an unexpected Terraform destroy/replace with
+  `-auto-approve` (or any unreviewed apply) — use a `moved` block or
+  `terraform state mv` (or another state-preserving fix) when the
+  resource itself was not meant to change.
+- NEVER delete a required Kubernetes manifest field just to make a
+  validator stop complaining.
+- NEVER delete or skip a failing validation step to reach a green build.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just `chmod 777` the directory, it's only a build image" | Undoes the non-root hardening this pack's security rule requires and grants write access to everyone, not just the user that actually needs it; fix ownership at the COPY/RUN step instead |
+| "The rename makes Terraform want to destroy and recreate it, but the resource is basically the same, so `-auto-approve` should be fine" | Terraform's plan is not wrong about what it will do — accepting an unreviewed destroy+recreate on a stateful resource can genuinely lose data; a `moved` block or `terraform state mv` fixes the address without touching real infrastructure |
+| "This field keeps failing validation, I'll just remove it" | If the field is actually required for the workload (a probe, a resource limit), removing it trades a caught validation error for a runtime failure later; fix the field's value instead |
+| "I'll switch back to `USER root` just to unblock this build, we can fix permissions properly later" | Reintroduces a root container to solve an ownership problem that a scoped `--chown`/`chown` step solves without giving up the non-root hardening |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- The specific failing command (`docker build`, `kubeconform`/`kubectl
+  apply --dry-run`, `terraform validate`/`plan`) now exits 0.
+- For a Terraform fix: `terraform plan` shows no destroy/replace on the
+  resource the fix was meant to preserve.
+- The change is the smallest one that addresses the stated root cause —
+  no unrelated files touched, and no security hardening (non-root user,
+  digest pin, `NetworkPolicy`) reverted to reach a green build.
+- The report states the root cause in one sentence, not just "build now
+  passes."