• Stacks - Infrastructure blueprints with

  terragrunt.stack.hcl

  (GA since v0.78.0)
• Feature Flags - Runtime control via

  feature

  blocks
• Exclude Blocks - Fine-grained execution control (replaces deprecated

  skip

  )
• Errors Blocks - Advanced error handling (replaces deprecated

  retryable_errors

  )
• OpenTofu Engine - Alternative IaC engine support

RECOMMENDED: Use

root.hcl

instead of

terragrunt.hcl

for root files per migration guide.

root.hcl

find_in_parent_folders("root.hcl")

terragrunt.hcl

find_in_parent_folders()

CRITICAL: Before generating ANY configuration, you MUST determine the architecture pattern and understand its constraints.

root.hcl

infrastructure/
├── root.hcl              # Environment-AGNOSTIC (no env.hcl references)
├── dev/
│   ├── env.hcl           # Environment variables (locals block)
│   ├── vpc/terragrunt.hcl
│   └── rds/terragrunt.hcl
└── prod/
    ├── env.hcl           # Environment variables (locals block)
    ├── vpc/terragrunt.hcl
    └── rds/terragrunt.hcl

• ❌ CANNOT use

  read_terragrunt_config(find_in_parent_folders("env.hcl"))

  - env.hcl doesn't exist at root level
• ❌ CANNOT reference

  local.environment

  or

  local.aws_region

  that come from env.hcl
• ✅ CAN use static values or

  get_env()

  for runtime configuration
• ✅ CAN use

  ${path_relative_to_include()}

  for state keys (this works dynamically)

undefined

Parse environment from path (e.g., "prod/vpc" -> "prod")

OR use environment variable

undefined

Re-export for child modules

... other variables

undefined

MANDATORY: Before writing any files, you MUST complete this checklist and OUTPUT it to the user with checkmarks filled in. This is not optional.

undefined

• Creating new Terragrunt projects or configurations
• Setting up multi-environment infrastructure (dev/staging/prod)
• Implementing DRY Terraform configurations
• Managing complex infrastructure with dependencies
• Working with custom Terraform providers or modules

root.hcl

terragrunt.hcl

MANDATORY: Before generating, READ the template file:

Read: assets/templates/root/terragrunt.hcl

assets/templates/root/terragrunt.hcl

references/common-patterns.md

• [BUCKET_NAME]

  ,

  [AWS_REGION]

  ,

  [DYNAMODB_TABLE]

• [TERRAFORM_VERSION]

  ,

  [PROVIDER_NAME]

  ,

  [PROVIDER_VERSION]

• [ENVIRONMENT]

  ,

  [PROJECT_NAME]

1. Environment-agnostic by default - Don't assume env.hcl exists at root level
2. Use static values for provider/backend region - Or use

   get_env()

   for runtime config
3. State key uses

   path_relative_to_include()

   - This automatically includes environment path
4. Provider tags can be static - Environment-specific tags go in child modules

MANDATORY: Before generating, READ the template file:

Read: assets/templates/child/terragrunt.hcl

assets/templates/child/terragrunt.hcl

references/common-patterns.md

• Local:

  "../../modules/vpc"

• Git:

  "git::https://github.com/org/repo.git//path?ref=v1.0.0"

• Registry:

  "tfr:///terraform-aws-modules/vpc/aws?version=5.1.0"

MANDATORY: Before generating, READ the template file:

Read: assets/templates/module/terragrunt.hcl

assets/templates/module/terragrunt.hcl

MANDATORY: Before generating:

1. Determine architecture pattern (see Architecture Patterns section)
2. Read relevant templates for root and child modules
3. Verify env.hcl placement and access patterns

references/common-patterns.md

infrastructure/
├── root.hcl              # Environment-AGNOSTIC root config
├── dev/
│   ├── env.hcl           # Dev environment variables
│   └── vpc/terragrunt.hcl
└── prod/
    ├── env.hcl           # Prod environment variables
    └── vpc/terragrunt.hcl

terragrunt.stack.hcl

MANDATORY: Before generating, READ the template files:

Read: assets/templates/stack/terragrunt.stack.hcl
Read: assets/templates/catalog/terragrunt.hcl

assets/templates/stack/terragrunt.stack.hcl

assets/templates/catalog/terragrunt.hcl

references/common-patterns.md

terragrunt stack generate    # Generate unit configurations
terragrunt stack run plan    # Plan all units
terragrunt stack run apply   # Apply all units
terragrunt stack output      # Get aggregated outputs
terragrunt stack clean       # Clean generated directories

references/common-patterns.md

CRITICAL: Feature flag

default

values MUST be static (boolean, string, number). They CANNOT reference

local.*

values. Use static defaults and override via CLI/env vars.

feature "enable_monitoring" {
  default = false  # Static value - OK
}

feature "enable_monitoring" {
  default = local.env.locals.enable_monitoring  # Dynamic reference - FAILS
}

terragrunt apply --feature enable_monitoring=true

1. Identify the provider name, source, and version
2. Search using WebSearch:

   "[provider] terraform provider [version] documentation"

3. Or use Context7 MCP if available for structured docs
4. Generate with proper

   required_providers

   block
5. Document authentication requirements in comments

CRITICAL: Follow this workflow for EVERY generation task. Skipping steps leads to validation errors.

• What type of configuration? (root, child, standalone, stack)
• Single or multi-environment?
• What dependencies exist between modules?
• What providers/modules will be used?

MANDATORY: Select and document the pattern BEFORE writing any files.

[ ] Pattern identified: ____
[ ] Root.hcl will be: [ ] environment-agnostic  [ ] environment-aware
[ ] env.hcl will be located in: ____
[ ] Child modules will read env.hcl via: ____

MANDATORY: Read the relevant template file(s) BEFORE generating each configuration type.

assets/templates/root/terragrunt.hcl

assets/templates/child/terragrunt.hcl

assets/templates/module/terragrunt.hcl

assets/templates/stack/terragrunt.stack.hcl

assets/templates/catalog/terragrunt.hcl

• references/common-patterns.md

  - Primary source for generation patterns

Validation Strategy: Use a combination of inline checks during generation and batch validation at the end.

1. Generate root.hcl first
   • Inline checks (during generation):
     • No

       read_terragrunt_config(find_in_parent_folders("env.hcl"))

       if environment-agnostic

     • remote_state

       block has

       encrypt = true

     • errors

       block used (not deprecated

       retryable_errors

       )
2. Generate env.hcl files for each environment
   • Inline checks (during generation):

     • locals

       block contains environment, aws_region, and module-specific vars
     • No references to files that don't exist at that directory level
3. Generate child modules (VPC, etc.) - modules with NO dependencies first
   • Inline checks (during generation):

     • include

       block uses

       find_in_parent_folders("root.hcl")

     • read_terragrunt_config(find_in_parent_folders("env.hcl"))

       present

     • terraform.source

       uses valid syntax (tfr:///, git::, or relative path)
4. Generate dependent modules (RDS, EKS, etc.)
   • Inline checks (during generation):

     • dependency

       blocks have

       mock_outputs

     • mock_outputs_allowed_terraform_commands

       includes

       ["validate", "plan", "destroy"]

     • Production modules have

       prevent_destroy = true

       and/or

       exclude

       block
5. Run batch validation after ALL files are generated

   Note: Full CLI validation (

   terragrunt hcl fmt

   ,

   terragrunt dag graph

   ) requires all files to exist, so these are batched at the end.

   bash

   # Batch validation commands (run after all files exist):
   terragrunt hcl fmt --check          # Format validation
   terragrunt dag graph                 # Dependency graph validation

   • Invoke

     devops-skills:terragrunt-validator

     skill for comprehensive validation

1. Analyze errors (path resolution, missing variables, syntax errors)
2. Fix issues in the specific file(s)
3. Re-validate the fixed file(s)
4. Repeat until ALL errors are resolved

1. Invoke validation skill:

   Invoke: devops-skills:terragrunt-validator skill

2. If validation fails:
   • Analyze errors (missing placeholders, invalid syntax, wrong paths)
   • Fix issues
   • Re-validate (repeat until ALL errors are resolved)
3. If validation succeeds: Present configurations with usage instructions

MANDATORY: After successful validation, you MUST present ALL of the following sections. Incomplete presentation is not acceptable. Copy and fill in the templates below.

You MUST include this section. Copy the template below and fill in the actual values:

undefined

1. AWS credentials are configured (

   aws configure

   or environment variables)
2. S3 bucket

   <BUCKET_NAME>

   exists for state storage
3. DynamoDB table

   <TABLE_NAME>

   exists for state locking

You MUST include this section. Copy the template below and fill in the actual values:

undefined

• S3 bucket

  <BUCKET_NAME>

  must exist before first run
• DynamoDB table

  <TABLE_NAME>

  must exist for state locking
• IAM permissions for Terraform state management

../devops-skills:terragrunt-validator/references/best_practices.md

• Use

  include

  blocks to inherit root configuration (DRY)
• Always provide mock outputs for dependencies
• Enable state encryption (

  encrypt = true

  )
• Use

  generate

  blocks for provider configuration
• Specify bounded version constraints (

  ~> 5.0

  , not

  >= 5.0

  ) for local/Git modules
• Never hardcode credentials or secrets
• Configure retry logic for transient errors

Note on Version Constraints with Registry Modules: When using Terraform Registry modules (e.g.,

tfr:///terraform-aws-modules/vpc/aws?version=5.1.0

), they typically define their own

required_providers

. In this case, you may omit generating

required_providers

in

root.hcl

to avoid conflicts. The module's pinned version (

?version=X.X.X

) provides the version constraint. See "Common Issues → Provider Conflict with Registry Modules" for details.

• Hardcoded account IDs, regions, or environment names
• Missing mock outputs for dependencies
• Duplicated configuration across modules
• Unencrypted state storage
• Missing or loose version constraints (except when using registry modules that define their own)
• Root.hcl trying to read env.hcl that doesn't exist at root level

• Terragrunt Docs
• Configuration Reference
• CLI Reference
• Stacks
• Feature Flags
• Engine
• Migration Guides

tfr:///terraform-aws-modules/vpc/aws

required_providers

root.hcl

Error: Duplicate required providers configuration

1. Remove conflicting generate block - If using registry modules that manage their own providers, avoid generating duplicate

   required_providers

   :
   hcl

   # In root.hcl - only generate provider config, not required_providers
   generate "provider" {
     path      = "provider.tf"
     if_exists = "overwrite_terragrunt"
     contents  = <<EOF
   provider "aws" {
     region = "us-east-1"
   }
   EOF
   }

2. Use if_exists = "skip" - Skip generation if file already exists:
   hcl

   generate "versions" {
     path      = "versions.tf"
     if_exists = "skip"  # Don't overwrite module's versions.tf
     contents  = "..."
   }

3. Clear cache - If conflicts persist after fixes:
   bash

   rm -rf .terragrunt-cache
   terragrunt init

1. references/common-patterns.md

   - Understand available patterns

2. ../devops-skills:terragrunt-validator/references/best_practices.md

   - Know the rules
3. Relevant template(s) from

   assets/templates/

   - Structural reference

1. Format check:

   terragrunt hcl fmt --check

2. Input validation:

   terragrunt hcl validate --inputs

3. Full validation: Invoke

   devops-skills:terragrunt-validator

   skill
4. Fix errors → Re-validate → Repeat until clean