Review Terraform linting and testing rules for best practices alignment

[markcallen]

Overview

Review the existing Terraform linting and testing rules in Ballast to ensure they align with current best practices for managing a Terraform project.

Current State

Ballast ships the following Terraform rules:

• .claude/rules/terraform/terraform-linting.md — linting with tfenv, terraform fmt, terraform validate, tflint, and tfsec/trivy
• .claude/rules/terraform/terraform-testing.md — validation pipeline with syntax, lint, and security checks
• .claude/rules/terraform/terraform-logging.md — plan/apply output safety and auditability
• .claude/rules/terraform/terraform-git-hooks.md — pre-commit hooks with Terraform-specific checks

Review Areas

Linting

• Verify tfenv + .terraform-version is still the recommended version pinning approach vs alternatives (e.g. asdf, mise)
• Confirm tflint configuration guidance is up to date with current plugin model
• Evaluate whether tfsec or trivy config is preferred for security scanning (tfsec is merging into trivy)
• Check if terraform fmt -check -recursive is the right CI gate or if tofu fmt support should be noted
• Review recommended repo layout (main.tf, variables.tf, outputs.tf, providers.tf, versions.tf) against current community conventions
• Ensure golangci-lint or similar is not mistakenly referenced in Terraform context

Testing

• Assess whether terraform validate + tflint + tfsec is a sufficient baseline or if Terratest/terraform test (native, added in Terraform 1.6) should be recommended
• Add guidance on native terraform test framework as an alternative to Terratest for module authors
• Verify that terraform init -backend=false is the correct smoke-test initialization approach for CI
• Review coverage expectations — should there be a recommended minimum validation path per module?

CI/CD Integration

• Ensure CI examples include a concurrency block aligned with the Ballast CI/CD rules
• Add note on plan/apply workflow separation (validate in PR, apply on merge)
• Consider adding guidance on Atlantis or Terraform Cloud/OpenTofu Cloud as orchestration options

OpenTofu Compatibility

• Evaluate whether rules should mention OpenTofu as a drop-in alternative
• Note any syntax or tooling differences that affect the recommended commands

Acceptance Criteria

• Rules reflect current Terraform (1.6+) and tooling ecosystem best practices
• Security scanning guidance clarifies tfsec-to-trivy migration path
• Testing section documents native terraform test alongside Terratest
• CI examples include proper concurrency blocks
• OpenTofu compatibility is acknowledged where relevant

References

• Terraform native testing
• tfsec → trivy migration
• tflint plugin architecture