Terramate Best Practices

When to Apply

• Creating and organizing Terramate stacks
• Orchestrating commands across multiple stacks
• Using code generation to keep configurations DRY
• Integrating with Terramate Cloud for observability
• Creating Catalyst components and bundles
• Setting up CI/CD workflows with Terramate
• Managing stack dependencies and execution order

Rule Categories by Priority

cli-

cli-orchestration-

cli-codegen-

cli-config-

cloud-

catalyst-

cicd-

advanced-

Quick Reference

1. CLI Fundamentals (CRITICAL)

• cli-stack-structure

  - Organize stacks with clear directory structure

• cli-stack-config

  - Configure stacks with proper stack blocks

• cli-stack-metadata

  - Use metadata for stack identification and filtering

2. CLI Orchestration (HIGH)

• cli-orchestration-run

  - Run commands across stacks efficiently

• cli-orchestration-change-detection

  - Use change detection to limit execution scope

• cli-orchestration-parallel

  - Leverage parallel execution for independent stacks

• cli-orchestration-dependencies

  - Manage stack dependencies and execution order

3. CLI Code Generation (HIGH)

• cli-codegen-hcl

  - Use generate_hcl for DRY Terraform code

• cli-codegen-file

  - Use generate_file for file generation patterns

• cli-codegen-provider

  - Generate provider configurations dynamically

4. CLI Configuration (MEDIUM-HIGH)

• cli-config-globals

  - Use globals for shared configuration across stacks

• cli-config-lets

  - Use lets for stack-local computed values

• cli-config-metadata

  - Leverage metadata for stack information

5. Terramate Cloud (MEDIUM-HIGH)

• cloud-integration

  - Set up Cloud connection and authentication

• cloud-drift-management

  - Configure drift detection and reconciliation

• cloud-observability

  - Use Cloud dashboard for stack visibility

6. Terramate Catalyst (MEDIUM)

• catalyst-components

  - Create reusable component blueprints

• catalyst-bundles

  - Define bundles for component composition

• catalyst-instantiation

  - Instantiate bundles correctly

7. CI/CD Integration (MEDIUM)

• cicd-github-actions

  - Set up GitHub Actions workflows

• cicd-preview-workflows

  - Create preview workflows for PRs

• cicd-deployment-workflows

  - Configure deployment automation

8. Advanced Patterns (LOW-MEDIUM)

• advanced-workflows

  - Create complex multi-step workflows

• advanced-codegen-patterns

  - Advanced code generation techniques

How to Use

rules/cli-stack-structure.md
rules/cli-orchestration-run.md
rules/cli-codegen-hcl.md
rules/cloud-integration.md
rules/catalyst-components.md

• Brief explanation of why it matters
• Incorrect/anti-pattern example with explanation
• Correct/best practice example with explanation
• Additional context and references

Full Compiled Document

AGENTS.md