/tf-best-practices

name: tf-best-practices
description: >-
  Best-practice authoring guidance AND a read-only policy gate for AWS Terraform generated by a
  migration skill. Load during any phase that writes a terraform/ directory — first as the "what to
  emit" posture rules + security-baseline spec, then after writing as the deterministic policy verdict.
  Read-only: it reports whether the generated Terraform passes; it never edits .tf files, never touches
  .phase-status.json, and never decides phase completion. Complements (does not replace) terraform
  fmt/init/validate.

tf-best-practices — Generated-IaC posture rules + read-only policy gate

A **shared authoring guide and verdict producer**, not a workflow. It answers two questions for a phase that generates AWS Terraform:

1. **Before writing** — "what security posture must the generated `terraform/` follow?" (the posture rules + the `baseline.tf` account-hardening spec) 2. **After writing** — "does the generated `terraform/` pass policy?" (a deterministic, **read-only** verdict + a machine-readable report)

Routing — load the part that matches your context

This skill is entered at two touchpoints in the caller's Generate flow, with the caller's own terraform-authoring work in between. **The caller states which touchpoint it is at when it loads this skill**, and reads the corresponding part:

| Caller context | Load | Why | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **About to author `terraform/`** (before writing) | Part 1 → [`references/security-posture-rules.md`](references/security-posture-rules.md) | The "what to emit" AWS authoring rules (gate-enforced + authoring-only + compliance-conditional). | | **`terraform/` written, ready to validate** (after writing) | Part 2 → [`references/terraform-validation.md`](references/terraform-validation.md) + run the gate script | The `fmt → init → validate → policy` protocol and the read-only verdict. |

Everything this skill states is **source-cloud-agnostic** (pure AWS Terraform). Any GCP/Heroku detection or artifact reading is the caller's job; where a rule needs a caller-known fact (e.g. declared compliance frameworks), the caller passes it as a **caller-context signal** — see `references/security-posture-rules.md` § _Caller-context signals_.

Boundary (read this first)

This unit is a **verdict producer, never a mutator**. Its entire write surface is the JSON verdict it is asked to emit. Specifically it **MUST NOT**:

• edit, format, or rewrite any `.tf` file (the caller owns remediation),
• read or write `.phase-status.json` or any run-state file (interpreter-owned),
• decide whether a phase may complete, or prompt the user (caller policy).

The caller (a migration skill's Generate phase) owns: the fix-and-retry loop that edits the `.tf` it generated, `terraform fmt` auto-apply, the retry/skip/abort prompt, the Phase Completion gate, and every `.phase-status.json` write. See the consuming skill's generate phase for how the verdict feeds those decisions.

> **Consumers:** `gcp-to-aws` (prose Generate) and `heroku-to-aws` (DSL Generate). The > contract is source-agnostic; each caller wires the two touchpoints in its own Generate > idiom — gcp-to-aws as prose steps, heroku-to-aws as a fragment step plus a fail-closed > `_postconditions` assert enforced by the interpreter.

Part 1 — Authoring posture (load before writing `terraform/`)

Emit generated Terraform that satisfies the posture in [`references/security-posture-rules.md`](references/security-posture-rules.md).

These are the "what good AWS Terraform looks like" rules. Following them makes the Part 2 gate pass by construction. This unit does not read the caller's artifacts — it consumes only caller-context signals the caller passes in.

> **Scope.** `security-posture-rules.md` covers, in three tiers: > > - **Gate-enforced** (Part 2 verifies statically): ALB TLS, no-public-database, RDS + > ElastiCache encryption-at-rest, no-public-DB-port ingress, no-public admin/datastore-port > ingress, no-wildcard-IAM. > - **Authoring-only** (not gate-checkable, still required): `deletion_protection`, > master-password-via-Secrets-Manager, S3 hardening, Fargate/EKS/ECR settings, private-subnet > placement, backups, baseline monitoring. > - **Compliance-conditional** (emitted when the caller declares `soc2`/`pci`/`hipaa`/`fedramp`): > VPC flow logs, S3 access logging, secret rotation, customer-managed KMS. > > Still the **caller's** own generation concern (candidates to migrate here later): the > account-hardening `baseline.tf` layer (CloudTrail, GuardDuty, Config, Security Hub).

Part 2 — Policy gate (run after writing `terraform/`)

Run the read-only checker against the generated directory. Resolve the script path relative to the plugin root (`$PLUGIN_ROOT/skills/tf-best-practices/scripts/...`), the same convention the plugin uses for its other scripts:

python3 "$PLUGIN_ROOT/skills/tf-best-practices/scripts/validate-terraform-policy.py" "$TERRAFORM_DIR" --json "$VERDICT_PATH"

• `$TERRAFORM_DIR` — **required, caller-supplied**: the generated `terraform/` directory

(e.g. `$MIGRATION_DIR/terraform`). This skill never defaults or discovers it — the caller always passes the path it wrote Terraform to.

• `--json $VERDICT_PATH` — optional; writes a machine-readable verdict the caller can merge

into its own `validation-report.json`.

The policy check is one stage of a larger validation flow (`fmt