Skip to content

feat(skills): add terraform safety core#177

Merged
soulcodex merged 1 commit into
mainfrom
feat/terraform-skill-safety-core
Jun 27, 2026
Merged

feat(skills): add terraform safety core#177
soulcodex merged 1 commit into
mainfrom
feat/terraform-skill-safety-core

Conversation

@soulcodex

@soulcodex soulcodex commented Jun 27, 2026

Copy link
Copy Markdown
Owner

Summary

This PR strengthens the Terraform skill set by adding a shared safety and
diagnostics layer, then wiring the existing Terraform skills to use it
explicitly.

The goal is to keep the current split by intent (design, module authoring,
testing, infrastructure structure, emulator usage) while importing the
strongest parts of Anton Babenko's Terraform skill: response contract
discipline, diagnose-first routing, version-aware guards, and common LLM
mistake prevention.

Why

Our Terraform skills were already strong on AWS-focused structure, module
authoring, and terraform-native testing, but the safety guidance was spread
across multiple skills and not expressed as one consistent contract.

This created a few gaps:

  • runtime and version assumptions were not always explicit
  • risk categories like identity churn, CI drift, blast radius, and state
    recovery were not routed consistently
  • rollback expectations for destructive or state-mutating guidance were not
    centralized
  • version-sensitive recommendations like moved blocks, import blocks, mock
    providers, write_only, and S3 use_lockfile were not governed by one shared
    runtime matrix

What changed

New shared Terraform skill

Added terraform-risk-playbook as a new shared Terraform safety core.

It defines:

  • the response contract every Terraform/OpenTofu answer should follow
  • a diagnose-first routing table for common Terraform failure modes
  • a version/runtime guard matrix for feature-sensitive guidance
  • an LLM mistake checklist for common Terraform errors and unsafe
    recommendations

Existing Terraform skills now delegate shared safety behavior

Updated the existing Terraform skills so they explicitly treat
terraform-risk-playbook as the shared safety layer instead of each one
partially reinventing it.

That means:

  • design-aws-terraform-iac now emphasizes explicit runtime/backend
    assumptions, risk categories, validation expectations, and rollback notes in
    the design brief
  • create-terraform-module now calls out address-stability guardrails, prefers
    for_each over count where identity matters, and requires migration notes
    or moved blocks for address refactors
  • create-terraform-tests now maps risk categories to test coverage more
    explicitly, including identity churn, provider/runtime upgrade compatibility,
    computed-value assertions, and confidence-level reporting
  • terraform-infrastructure now states its authoritative scope more clearly,
    delegates shared safety concerns to the new playbook, and updates its backend
    guidance to prefer use_lockfile on Terraform 1.10+ with DynamoDB locking
    framed as an older-runtime compatibility path
  • use-aws-mini-stack-emulator now makes the emulator boundary more explicit by
    documenting what local emulation cannot prove for production-impacting
    changes

Profile and catalog updates

  • added terraform-risk-playbook to the
    hcl-aws-terraform-module profile so Terraform-focused projects receive the
    shared safety layer by default
  • updated docs/skills.md to describe the new skill and to tighten the wording
    for terraform-infrastructure
  • rebuilt index/skills.json
  • updated schemas/profile.schema.json so the new skill is part of the allowed
    profile skill enum

Design intent

This PR does not collapse the Terraform skills into one monolithic skill.

Instead, it keeps the existing separation of concerns and makes it safer:

  • the new playbook owns shared safety, routing, runtime/version assumptions,
    validation contract, and rollback expectations
  • the existing skills continue to own their specific implementation domains

This keeps the skill family modular while removing duplicated or inconsistent
safety guidance.

Validation

Ran:

  • just index
  • just lint

Files touched

Primary changes are limited to:

  • Terraform skill docs under skills/devops/ and skills/backend/
  • profiles/hcl-aws-terraform-module.yaml
  • docs/skills.md
  • generated metadata: index/skills.json, schemas/profile.schema.json

No runtime tooling behavior changed in this PR.

- add a shared terraform-risk-playbook skill for response contract, risk routing, version guards, and LLM mistake checks
- wire the existing Terraform skills to the shared safety layer and tighten their ownership boundaries
- update the Terraform module profile, docs, and generated skill index to include the new shared skill
@soulcodex soulcodex merged commit bdf315a into main Jun 27, 2026
8 checks passed
@soulcodex soulcodex deleted the feat/terraform-skill-safety-core branch June 27, 2026 19:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant