SKILL PROCESS

Terraform PR Workflow

PR workflow Skill for Terraform/Terragrunt repos: branch naming, PR hygiene, read-only CI gates, and versioning expectations for interface changes.

Overview

PR workflow Skill for Terraform/Terragrunt repos: branch naming, PR hygiene, read-only CI gates, and versioning expectations for interface changes.

This skill ships inside the Terraform Workflows plugin and can be installed through the Claude Code marketplace or directly in Codex from its skill path.

Parent Surface

Parent docs: Terraform Workflows

Related wrapper commands from the parent plugin:

/terraform:check-pr

When to Use This Skill

Use this Skill when preparing or reviewing a PR in Terraform/Terragrunt repos, especially shared module libraries and their consumers.

Goal: catch workflow/process issues early (before apply-time surprises).

Severity Tags

  • [BLOCKING] – cannot merge as-is (missing plan rationale, unsafe workflow, breaking change not called out).
  • [SHOULD_FIX] – strongly recommended before merge (docs drift, missing versioning note).
  • [NIT] – minor polish.

Checks This Skill Enforces

PR description must include either:

Strongly preferred sections (when applicable):

If the PR changes module interface (examples):

Then require:

If changes are breaking (renames/removals, behavior changes, tighter validations):

  • Branch name uses a standard prefix (feat/, fix/, chore/, docs/, refactor/).
  • PR title matches intent (don’t hide breaking changes behind “chore” wording).
  • One PR = one coherent change; if it’s a stack of unrelated edits, recommend splitting.
  • Plan evidence (preferred):
  • module-level validation summary, or
  • terragrunt plan output summary for the relevant stacks, or
  • A clear explanation of why plans weren’t run (missing creds, non-executable change, doc-only PR, etc.) plus what validation was done instead (fmt/validate/lint).
  • What changed
  • Plan / Validation
  • Risk / Rollout
  • Breaking changes (if any)
  • Versioning (module repos)
  • CI should run fmt, validate, tflint, and optionally plan.
  • CI should not run apply.
  • If the repo currently has apply in CI, flag as [BLOCKING] and recommend moving applies to a gated/manual workflow.
  • Verify by scanning .github/workflows/*.yml for apply usage (terraform apply, terragrunt apply, run-all apply).
  • variables.tf inputs added/renamed/removed
  • outputs.tf outputs added/renamed/removed
  • required provider/terraform versions changed
  • Explicit callout in PR description (“Interface change”) with migration notes.
  • A versioning plan aligned with the repo’s conventions (tags/releases/VERSIONING.md when present).
  • “Moving ref” avoidance: consumers should pin to a tag/SHA rather than a branch when the repo supports releases.
  • PR must include a Breaking changes section with:
  • what changed,
  • why,
  • how to migrate,
  • what version/tag will contain the change.
  • If the repo maintains a changelog, require an entry.
  • If it doesn’t, require release notes in the PR body.

Output Format

Return:

  • Verdict: MERGE-READY / NOT READY
  • Findings: bullets with [BLOCKING] / [SHOULD_FIX] / [NIT]
  • Suggested edits: concrete fixes to branch name / PR title / PR body sections

Resources

Declared allowed tools:

BashReadEditGlobGrep

Installation

Switch between Claude Code and Codex, then copy the install command for the runtime you use.

claude plugin marketplace add DiversioTeam/agent-skills-marketplace
claude plugin install terraform@diversiotech

Invocation:

/terraform:check-pr