HashiCorp Agent Skills

The tfpolicy-test skill is an expert agent designed to help you write and debug .policytest.hcl files. It assists in designing resource and module mocks, using expect_failure correctly, mocking cross-resource lookups for core::getresources(), and reasoning about the tfpolicy test runner behavior.

Use this skill when:

• You have an existing policy and want to write or improve tests for it.
• You are debugging a failing or unexpectedly passing test.
• You are writing .policytest.hcl files, policytest { targets = [...] } blocks, resource {} / module {} mocks, or using expect_failure / skip.
• You are testing operation-aware policies and need to mock attrs and/or prior_attrs for create/update/delete scenarios.
• You need to mock cross-resource lookups (e.g., aws_s3_bucket_versioning for core::getresources patterns).
• You are investigating runner caveats (e.g., operations scope behavior, expect_failure limitations on data blocks).

Do NOT use this skill when:

• You are writing the policy itself (use tfpolicy-author instead).
• You are converting a Sentinel test to a .policytest.hcl test (start with tfpolicy-author, then return here for refinements).

The tfpolicy-author skill is an expert agent designed for authoring Terraform Policies (.policy.hcl). It can translate natural-language requirements into policy blocks or convert existing Sentinel (.sentinel) source code into Terraform Policy equivalents.

Use this skill when you need to:

• Generate resource_policy, module_policy, or provider_policy blocks from descriptions (e.g., "block public RDS").
• Convert Sentinel policies to Terraform Policy.
• Migrate a Sentinel policy library to tfpolicy.
• Learn about tfpolicy language features like filter, locals, enforce, input, operations, prior_attrs, and core::* functions.
• Structure policies that use core::getresources() or core::getdatasource() for cross-resource checks.
• Compare Sentinel and tfpolicy capabilities.

Do NOT use this skill for:

• Writing or debugging .policytest.hcl test files. For that, use the tfpolicy-test skill.

Because core::try(attrs.field, default) only triggers the fallback when a key is absent (not when it is null), you must apply specific rules before adding a null test case to a mock:

1. Two-step pattern (raw = core::try(attrs.field, null) then val = raw != null ? raw : []): The null is explicitly normalized. Add a pass case (no expect_failure) to verify this normalization.
2. Explicit non-compliance check (condition = val != null && val != ""): null is intentionally non-compliant. Add a fail case (expect_failure = true).
3. Single-step only (val = core::try(attrs.field, [])) without a null guard: null is not normalized and will crash downstream expressions (e.g., for val in null). Do NOT add a null case. Fix the policy to use the two-step pattern instead.

Rule of thumb: Never add a null test case if the policy treats null the same as the safe default (e.g., false or []).

A critical behavior in TFPolicy is that the logical AND operator (&&) does NOT short-circuit in locals blocks, enforce {} blocks, or for...if predicates. Both sides of the && expression are always evaluated. If the left side is local.var != null and the right side is core::length(local.var), the policy will crash if local.var is null because the right side is still executed.

Correct Patterns:

• In locals or enforce blocks: Use the ternary operator (? :) to guard function calls. Ternary operators do short-circuit.
• In for...if predicates: Use a ternary operator inside the predicate and ensure the second access is also wrapped in core::try() to prevent attribute-access errors.

# ❌ WRONG — condition = also does NOT short-circuit; crashes when local.X is null
enforce {
  condition = local.X != null && core::contains(["a", "b"], local.X)  # ❌ crashes!
}

# ✅ CORRECT — use ternary inside the locals block, then reference in condition
locals {
  is_allowed = local.X != null ? core::contains(["a", "b"], local.X) : false
}
enforce {
  condition = local.is_allowed
}

# ❌ WRONG — for...if predicate also does NOT short-circuit
violating = [
  for r in local.rules : r
  if core::try(r.field, null) != null && core::contains(["a", "b"], r.field)  # ❌ crashes!
]

# ✅ CORRECT — use ternary in for...if predicate
violating = [
  for r in local.rules : r
  if (core::try(r.field, null) != null ? core::contains(["a", "b"], core::try(r.field, "")) : false)
]