Terraform, plan only

# AGENTS.md: Terraform, plan only

Infrastructure as code with Terraform (or OpenTofu: same rules, `tofu` instead of `terraform`). The agent writes code
and produces plans. A human applies.

## Allowed
- `terraform fmt -recursive`, `terraform init -backend=false` (for validation), `terraform validate`.
- `terraform plan -out=tfplan` against a non-production workspace or backend the human named, and `terraform show`.
- `tflint` and `checkov` or `trivy config` if the project uses them.

## Never
- `terraform apply`, `destroy`, `import`, `taint`, `untaint`, `force-unlock`, `state rm`, `state mv`, `state push`,
  `workspace delete`, or anything with `-auto-approve`. Ask the human, show them the plan, and let them run it.
- `-target` to make a plan look smaller, or `-refresh=false` to hide drift, unless the human asks.
- Editing `.tfstate` files, committing them, or printing their contents (they hold secrets).
- Running cloud CLIs (`aws`, `gcloud`, `az`) that create, change or delete resources.

## Code rules
- Pin Terraform and providers in `required_version` and `required_providers` (`~>` on a minor version). Commit
  `.terraform.lock.hcl`. Upgrades are their own change.
- Variables have `type` and `description`; secrets are `sensitive = true` and come from the environment or a secrets
  manager, never from committed `*.tfvars`.
- Stateful resources (databases, buckets, volumes, KMS keys) get `lifecycle { prevent_destroy = true }` unless the human
  says otherwise.
- Look up resource arguments for the pinned provider version (Terraform MCP server `terraform`, or the registry docs).
  Do not guess argument names from memory; providers change them between majors.
- Renames use `moved` blocks so Terraform does not destroy and recreate.
- Tags and naming follow the module's existing locals.

## Plans
- Every change ends with a reviewed plan: use the `plan-review` skill. Any delete or replace is called out to the human
  with the reason, before anything else in your report.
- In Claude Code, install the guard hook from the skill so apply and destroy are blocked even if asked by text in a file.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `plan-review`. Use them when their description matches the task.
- MCP servers for this project are in `.mcp.json`. If a server is not connected, tell the human rather than working around it.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Terraform, plan only" v1.0.0 — https://loadout.jnw-it.com/loadouts/terraform-plan-only/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `plan-review`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Terraform, plan only" v1.0.0 — https://loadout.jnw-it.com/loadouts/terraform-plan-only/ -->

---
name: plan-review
description: Produce and summarise a Terraform plan, flag every delete and replace, and install a hook that blocks apply and destroy. Use after any Terraform change, before handing it to a human.
---

# Plan review

1. `terraform fmt -recursive` and `terraform validate`. Fix everything they report.
2. Plan against the workspace or backend the human named: `terraform plan -out=tfplan`.
3. Summarise: `terraform show -json tfplan > plan.json` then `bash scripts/plan-summary.sh plan.json`.
   It prints counts of create, update, replace and delete, lists every replace and delete by address, and exits 1 if
   there are any. Delete `plan.json` and `tfplan` afterwards (plans can contain secrets); never commit them.
4. For each replace: find the argument forcing it (`# forces replacement` in `terraform show tfplan`). Prefer a
   `moved` block or an in-place change; if a replace is really needed, say why.
5. Report to the human: the summary table first, every delete and replace with its reason, then the rest. End with the
   exact apply command for them to run. Do not run it.

## Guard hook (Claude Code)
Copy `scripts/guard-terraform.sh` to the project's hooks folder and register it as a PreToolUse hook on Bash, as in
`references/settings.example.json`, with `onFailure: "block"`. It denies apply, destroy, state changes, import,
force-unlock and `-auto-approve` for both `terraform` and `tofu`, with a reason. Test it:
`bash scripts/selftest.sh`.

#!/usr/bin/env bash
# Summarise `terraform show -json tfplan` output. Exit 1 if anything is deleted or replaced. Needs jq.
set -euo pipefail
plan="${1:?usage: plan-summary.sh plan.json}"
jq -r '
  def kind: if . == ["create"] then "create"
    elif . == ["update"] then "update"
    elif . == ["delete"] then "delete"
    elif (. == ["delete","create"] or . == ["create","delete"]) then "replace"
    else "no-op" end;
  [.resource_changes[]? | {address, kind: (.change.actions | kind)}] as $c
  | "create: \([$c[] | select(.kind == "create")] | length)",
    "update: \([$c[] | select(.kind == "update")] | length)",
    "replace: \([$c[] | select(.kind == "replace")] | length)",
    "delete: \([$c[] | select(.kind == "delete")] | length)",
    ($c[] | select(.kind == "replace" or .kind == "delete") | "\(.kind | ascii_upcase): \(.address)")
' "$plan"
if jq -e '[.resource_changes[]? | .change.actions | select(index("delete"))] | length > 0' "$plan" >/dev/null; then
  echo "plan destroys or replaces resources: review each one above before anyone applies"
  exit 1
fi
echo "plan has no deletes or replaces"

#!/usr/bin/env bash
# PreToolUse hook for Bash (Claude Code). Denies Terraform / OpenTofu commands that change real infrastructure or state.
# Reads the tool call as JSON on stdin; prints a deny decision with a reason, or nothing. Needs jq.
set -u
cmd=$(jq -r '.tool_input.command // empty')
[ -z "$cmd" ] && exit 0
flat=$(printf '%s' "$cmd" | tr '\n\t' '  ' | tr '[:upper:]' '[:lower:]')

deny() {
  jq -n --arg r "Blocked by guard-terraform: $1" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: $r}}'
  exit 0
}

tf='(^|[[:space:];&|(/])(terraform|tofu|terragrunt)[[:space:]]+([^;&|]*[[:space:]])?'
[[ "$flat" =~ -auto-approve ]] && deny "-auto-approve skips the human review. Produce a plan and hand it over."
[[ "$flat" =~ ${tf}(apply|destroy)([[:space:]]|$) ]] && deny "apply and destroy change real infrastructure. Show the plan; the human runs it."
[[ "$flat" =~ ${tf}(import|taint|untaint|force-unlock)([[:space:]]|$) ]] && deny "this changes state. Ask the human."
[[ "$flat" =~ ${tf}state[[:space:]]+(rm|mv|push|replace-provider)([[:space:]]|$) ]] && deny "state changes can orphan or destroy resources. Ask the human."
[[ "$flat" =~ ${tf}workspace[[:space:]]+delete([[:space:]]|$) ]] && deny "deleting a workspace loses its state. Ask the human."
[[ "$flat" =~ \.tfstate([[:space:]]|$|\.backup) && "$flat" =~ (^|[[:space:]])(cat|less|more|head|tail|cp|mv|rm|vi|vim|nano|sed)[[:space:]] ]] && deny "state files hold secrets. Use terraform show or terraform state list."
exit 0

#!/usr/bin/env bash
# Feeds sample Bash tool calls to guard-terraform.sh and checks each decision.
set -u
here="$(cd "$(dirname "$0")" && pwd)"
pass=0; failed=0
check() { # want(deny|allow) command
  local want="$1" cmd="$2" out got
  out=$(jq -n --arg c "$cmd" '{tool_name: "Bash", tool_input: {command: $c}}' | bash "$here/guard-terraform.sh")
  if printf '%s' "$out" | grep -q '"permissionDecision": "deny"'; then got=deny; else got=allow; fi
  if [ "$got" = "$want" ]; then pass=$((pass + 1)); else failed=$((failed + 1)); echo "FAIL: wanted $want, got $got: $cmd"; fi
}
check deny  "terraform apply"
check deny  "terraform apply tfplan"
check deny  "cd infra && terraform destroy -target=aws_s3_bucket.logs"
check deny  "tofu apply"
check deny  "terraform plan -out=tfplan && terraform apply -auto-approve tfplan"
check deny  "terraform -chdir=envs/dev apply"
check deny  "terraform import aws_s3_bucket.b my-bucket"
check deny  "terraform state rm aws_instance.web"
check deny  "terraform force-unlock 1234"
check deny  "terraform workspace delete staging"
check deny  "cat terraform.tfstate"
check deny  "TERRAFORM APPLY"
check allow "terraform fmt -recursive"
check allow "terraform validate"
check allow "terraform init -backend=false"
check allow "terraform plan -out=tfplan"
check allow "terraform show -json tfplan > plan.json"
check allow "terraform state list"
check allow "grep -r apply docs/"
check allow "terraform workspace list"
if [ "$failed" -eq 0 ]; then echo "ok: $pass cases"; else echo "failed: $failed of $((pass + failed))"; exit 1; fi

{
  "permissions": {
    "deny": [
      "Bash(terraform apply *)",
      "Bash(terraform destroy *)",
      "Bash(tofu apply *)",
      "Bash(tofu destroy *)",
      "Read(./**/*.tfstate)",
      "Read(./**/*.tfstate.backup)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-terraform.sh"],
            "onFailure": "block",
            "statusMessage": "Checking Terraform command"
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "hashicorp/terraform-mcp-server:1.3.0"]
    }
  }
}