terraform-agentic-workflows-demo01

Disclaimer: These workflows are intended for delivery via RTS (Resident Technical Services) as part of a Professional Services engagement. This repository should not be handed over without guided enablement — agentic infrastructure development requires mature IaC practices, layered guardrails, and operational readiness. Without these foundations, autonomous code generation against live infrastructure carries significant risk. Adoption and customization should be guided by a Resident Solutions Architect to ensure alignment with your organization's security posture, operational standards, and infrastructure maturity.

Get Started: Engage via the Lighthouse program or reach out to Fiona Black directly. For technical guidance or queries reach out to Simon Lynch or Aaron Evans.

Terraform Agentic Workflows

A framework for agentic Infrastructure as Code development workflows using Spec-Driven Development (SDD) — a structured approach that guides AI agents through building production-ready Terraform code with guardrails at every phase. Built on industry standards like agent skills and subagents, this framework is designed to be generic and can be customized to work with any AI coding harness that supports these primitives. Validated with Claude Code and GitHub Copilot CLI; Cursor is supported experimentally via the plugin. Coming soon Project Bob ...

Guardrails matter. Agentic AI for critical infrastructure requires mature IaC practices and strong operational guardrails to deliver successful outcomes. HCP Terraform is a key component of this approach — providing remote execution, policy enforcement, state management, and approval workflows that keep AI-generated infrastructure safe and auditable.

Note: This repository is a framework for agentic development workflows for Infrastructure as Code. Customization to a customer's specific requirements, security posture, and best practices should be undertaken as a Resident Solutions Architect (RSA) engagement.

Learn more: Visit AI-Powered Infrastructure Engineering at Enterprise Scale — a structured learning path for platform teams adopting autonomous HCP Terraform development, covering agent architecture, layered guardrails, Specification-Driven Development, and three validated workflow patterns.

What is this?

This repository is a development template, not a deployed module. It provides orchestrated AI agent workflows for three core Terraform use cases, each following the same structure:

graph LR
    A["🔍 Clarify"] --> B["📐 Design"] --> C{"🧑‍💻 Human Review"}
    C --> D["🔨 Implement"] --> E["✅ Validate"] --> F["🚀 PR"]

    style A fill:#4a90d9,stroke:#2c5f8a,color:#fff,rx:8
    style B fill:#6c5ce7,stroke:#4a3db0,color:#fff,rx:8
    style C fill:#e17055,stroke:#b34a3a,color:#fff
    style D fill:#00b894,stroke:#008c6e,color:#fff,rx:8
    style E fill:#fdcb6e,stroke:#c9a224,color:#333,rx:8
    style F fill:#00cec9,stroke:#009e9a,color:#fff,rx:8

• Clarify — Gather requirements, resolve ambiguity, research AWS/provider docs
• Design — Produce a design document with architecture, interfaces, security controls
• Human Review — Approve the design before any code is written
• Implement — TDD: write tests first, then build to pass them
• Validate — Run the full quality pipeline (fmt, validate, test, tflint, trivy, docs)
• PR — Create a pull request with the implementation for final review

Why use this? Writing production-grade Terraform by hand is slow and error-prone — security defaults get missed, tests are skipped, documentation drifts. SDD with AI agents enforces quality at every phase, producing consistent, tested, documented infrastructure code in a fraction of the time.

Can't I build my own workflows? Yes — and many teams do. But getting agentic IaC right is harder than it looks. Naive prompting produces code that works in demos but fails in production: no tests, no security defaults, inconsistent structure, and no guardrails to prevent drift. This framework encodes months of iteration into reusable skills, constitutions, and validation pipelines. You get a proven starting point instead of rebuilding the same lessons from scratch — and because it's built on open standards (agent skills, subagents, MCP), you can extend and customize it rather than being locked in.

Are these workflows designed to run in the IDE? These workflows are designed for long-running, background agentic execution — not quick inline completions. We recommend starting in the IDE (VS Code devcontainer) as the fastest path to adoption. As practices mature, these same workflows can be centralized in cloud agent sandboxes such as AWS AgentCore, decoupling execution from individual developer machines, enabling platform-level orchestration, and unlocking dynamic secrets management for coding agent harnesses.

Quick Start

Prerequisites: Docker Desktop, VS Code, GitHub fine-grained PAT, HCP Terraform Team API token, and either a Claude Code subscription or GitHub Copilot license.

# 1. Create a new repo from this template on GitHub, then clone it
git clone https://github.com/YOUR_ORG/your-new-repo.git
code your-new-repo

# 2. When VS Code prompts, click "Reopen in Container"
#    Choose claude-code or copilot-cli variant depending on your AI assistant

# 3. Validate your environment
bash .foundations/scripts/bash/validate-env.sh

All other tools (Terraform, TFLint, terraform-docs, Trivy, Go, GitHub CLI, and more) are pre-installed in the devcontainer.

See the Getting Started Guide for complete setup instructions including token configuration and branch protection.

Install as a plugin

The workflows can also be installed as a plugin into any repository, instead of using this repo as a template. Parallel manifests serve each AI assistant from the same content: Claude Code reads .claude-plugin/plugin.json, GitHub Copilot CLI reads .github/plugin/plugin.json, and Cursor reads .cursor-plugin/plugin.json (each pointing at the shared skills plus the matching agent dialect).

Claude Code (skills become namespaced, e.g. /tf-workflows:tf-module-plan):

/plugin marketplace add hashi-demo-lab/terraform-agentic-workflows
/plugin install tf-workflows@tf-workflows

GitHub Copilot CLI (the same marketplace manifest works — Copilot reads .claude-plugin/marketplace.json too):

copilot plugin marketplace add hashi-demo-lab/terraform-agentic-workflows
copilot plugin install tf-workflows@tf-workflows

(copilot plugin install hashi-demo-lab/terraform-agentic-workflows also works, but the Copilot CLI has deprecated direct repo installs in favor of marketplace installs.)

Cursor (2.5+): import this repo's URL as a Team Marketplace (Settings → Customize → Plugins), register it under plugins in the project's .cursor/settings.json, or just open a repo containing .claude/ — Cursor natively discovers skills from .claude/skills/ and subagents from .claude/agents/ (behind its third-party extensibility setting, on by default), so the workflows load with no plugin at all. The packaging is validated against Cursor's actual plugin loader (the engine bundled in @cursor/sdk, shared with cursor-agent): all 32 skills and 21 agents load through .cursor-plugin/plugin.json, and the plugin auto-bundles the repo-root .mcp.json like the other two CLIs. Frontmatter dialect: skills: preloading and color: are silently ignored everywhere (agent bodies reference skills by name, which still works via skill discovery); model:/tools: are honored for agents discovered from an open repo's .claude/agents/, but stripped for plugin-delivered agents (they run with model: inherit and all tools). Without the plugin, copy .mcp.json to .cursor/mcp.json for the Terraform MCP tools. Live end-to-end runs on Cursor haven't been exercised — treat as experimental until smoke-tested in an authenticated Cursor session.

MCP servers — both CLIs auto-bundle the repo's .mcp.json with the plugin (it sits at the plugin root; neither CLI offers a manifest opt-out):

• Copilot CLI: bundled servers keep their names (terraform, aws-documentation-mcp-server), so the plugin agents' terraform/* tool references work out of the box — the consuming machine just needs the server runtimes (docker + TFE_TOKEN for terraform, uvx for AWS docs).
• Claude Code: plugin-bundled MCP tools are renamed to mcp__plugin_tf-workflows_<server>__*, which does NOT match the agents' mcp__terraform__* tool allowlists. Copy this repo's .mcp.json into the consuming repo (project scope) so the agents' allowlisted tools exist, and set CLAUDE_CODE_SKIP_PLUGIN_MCP_SERVERS=1 to suppress the plugin-scoped duplicates (otherwise each server runs twice).

Hooks — each manifest declares a hook config in its harness's dialect, carrying the repo-level guards into plugin installs: the deny-config-files.sh PreToolUse guard (all three) and the tf-guard.sh fix/verify pipeline (Claude Code and Copilot, matching the repo wiring — Cursor gets the deny guard only). Commands reference scripts inside the installed plugin via ${CLAUDE_PLUGIN_ROOT}, which all three loaders substitute.

• Claude Code: .claude-plugin/hooks.json, referenced from the manifest hooks field; claude plugin validate --strict resolves the path.
• Copilot CLI: .github/plugin/hooks.json. Verified against the CLI's native config loader (1.0.71): configLoaderDiscoverPluginHookConfigs resolves the manifest hooks path (defaults would be plugin-root hooks.json / hooks/hooks.json) and configLoaderExpandPluginHookConfig expands ${CLAUDE_PLUGIN_ROOT}. A live agent run was not exercised (account-restricted).
• Cursor: .cursor-plugin/hooks.json (Claude shape — the loader's Claude-compat converter handles it, hard-coding failClosed: false). The plugin loader discovers it, but cursor-agent CLI 2026.07.16 does not execute plugin-delivered hooks: identical hooks fire from a workspace .cursor/hooks.json yet never from --plugin-dir plugins in any layout (manifest path, native dialect, or hooks/hooks.json convention). For hook coverage in Cursor today, copy this repo's .cursor/hooks.json into the consuming repo; the plugin entry is forward-looking.

The verify/fix hooks need the consuming repo's toolchain (below) on PATH; each check no-ops when its tool is absent, and targets are discovered from the consuming repo's git tree, so the hooks are safe in repos that don't use Terraform in every directory.

What the plugin does NOT carry — the consuming repository must provide:

• .foundations/: constitutions, design templates, and helper scripts are referenced repo-relatively by the workflows — copy .foundations/ into the consuming repo (tailor the constitutions to your organization).
• Toolchain: terraform, tflint, trivy, pre-commit config, and gh as per the devcontainer.

For local development of the plugin itself: claude --plugin-dir . from the repo root, and claude plugin validate . before pushing.

Core Workflows

Start any workflow by typing the slash command in your AI assistant's chat (Claude Code terminal or Copilot Chat). The same slash commands work in both tools:

Day 2 Operations

The consumer module uplift pipeline automates dependency management for consumer configurations:

1. Dependabot detects new module versions in the private registry
2. GitHub Actions classifies the version bump, runs terraform plan, and assesses risk
3. Low-risk changes (patch, adds-only) are auto-merged
4. Breaking changes trigger @claude — an AI agent that fetches the old/new module interfaces, fixes consumer code, and pushes the fix for re-validation

See Day 2 Operations for full details.

MCP Servers

Pre-configured Model Context Protocol servers extend AI agent capabilities:

Configured in .mcp.json and available automatically in the devcontainer.

What's Included

• Devcontainer — One per assistant: claude-code (Claude Code CLI) and copilot-cli (GitHub Copilot), each with a Docker variant and a rootless-Podman variant (*-podman), plus bob-podman (IBM Bob Shell, rootless Podman only). All ship Terraform 1.14, TFLint, terraform-docs, Trivy, Go 1.24, GitHub CLI, Vault Radar, Infracost, Checkov, golangci-lint, and pre-commit
• Pre-commit hooks — fmt, validate, docs, tflint, trivy, secret detection, Vault Radar (requires optional VAULT_RADAR_LICENSE)
• TFLint — AWS (0.46.0), Azure (0.31.1), and Terraform plugins with all 20 rules configured
• Constitutions — Non-negotiable rules for module, provider, consumer, and policy code generation
• Design templates — Canonical starting points for each workflow's design phase
• CI/CD pipelines — Validation, apply, release, and consumer uplift workflows
• E2E eval framework — evals/e2e/ runs full plan→implement cycles headlessly in throwaway repos, scores them with deterministic checks plus an independent judge agent, and renders an offline HTML report (wall time, cost, quality)
• Plugin manifests — install the workflows into any repo via Claude Code, Copilot CLI, or Cursor (.claude-plugin/, .github/plugin/, .cursor-plugin/)

Documentation

Validated Models

This solution has been validated with the following models (listed in order of observed performance):

Model choice is up to customer preference — all three produce production-quality output. Evals generally show best results in the order above.

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.

License

This project is licensed under the Apache License 2.0.