feat(infra): add IaC and infrastructure related profile and skills

[soulcodex]

Profile

• terraform-module

Skills

• create-terraform-module
• create-terraform-tests
• design-aws-terraform-iac
• use-aws-mini-stack-emulator

[soulcodex]

Reviewed Implementation Plan

Implementation Plan for Issue #88 - feat(infra): add IaC and infrastructure related profile and skills

Source

• Issue: feat(infra): add IaC and infrastructure related profile and skills #88 - feat(infra): add IaC and infrastructure related profile and skills
• URL: feat(infra): add IaC and infrastructure related profile and skills #88
• Labels: none
• Author: soulcodex
• Assignees: none
• Milestone: none
• Created: 2026-04-23T22:37:16Z
• Updated: 2026-04-26T17:13:48Z

Problem summary

The library still has no infrastructure-first composition profile and only one broad Terraform skill, skills/backend/terraform-infrastructure/SKILL.md. That leaves a gap between the repo’s application-oriented profiles and the workflow described in Issue #88: starting an IaC-focused project around reusable Terraform modules, module testing, AWS-oriented Terraform design, and local emulation for infrastructure work.

The implementation should stay within the existing profile and skill system. This issue does not need schema changes, new fragment types, or vendor-tooling changes.

Current behavior / context

• Profiles are plain YAML files in profiles/ and are surfaced directly by filename through just list-profiles in justfile and cmd_list() in tooling/lib/cli.sh.
• The repository currently ships 15 profiles. The count is hard-coded in README.md and docs/index.md, and the inventory table is maintained manually in docs/profiles.md.
• schemas/profile.schema.json does not enforce a filename convention, but repository policy in AGENTS.md says profile names should follow {language}-{framework-or-architecture}-{pattern}.yaml. The requested terraform-module filename is therefore a deliberate convention exception unless maintainers choose a normalized alternative before implementation.
• Skills are discovered from skills/**/SKILL.md, indexed by tooling/lib/index.sh into index/skills.json, listed by agentic list skills, rendered into AGENTS.md by build_skills_section() in tooling/lib/compose.sh, and copied into target projects by tooling/lib/deploy-skills.sh.
• The existing Terraform coverage is concentrated in skills/backend/terraform-infrastructure/SKILL.md. It already covers module layout, remote state, workspace strategy, variable/secrets handling, CI plan/apply flow, and multi-region/provider-alias patterns.
• The repo currently has no dedicated skill for:
  • scaffolding a reusable Terraform module as an immediate task
  • selecting a Terraform-native module test strategy
  • shaping AWS account/state/module boundaries before writing Terraform
  • using a local AWS emulator specifically for Terraform-oriented development and validation
• There is no current skills/devops/ IaC coverage besides write-dockerfile, so adding new IaC skills there is structurally consistent with the existing taxonomy.

Relevant code paths

Include concrete files, packages, symbols, endpoints, jobs, migrations, commands, configuration, tests, or workflows.

• Repository authoring rules
  • AGENTS.md defines the profile naming convention, docs-update requirements, and required just lint / just index / just test workflow.
• Existing Terraform/IaC guidance
  • skills/backend/terraform-infrastructure/SKILL.md
  • skills/development/github-actions-workflow/SKILL.md
  • skills/development/add-tests/SKILL.md
• Existing profile examples to mirror for flat profile structure, tech_stack, skills, and output
  • profiles/go-library.yaml
  • profiles/golang-hexagonal-cobra-cli.yaml
  • profiles/go-hexagonal-microservice.yaml
  • profiles/typescript-library.yaml
• Schema and composition pipeline
  • schemas/profile.schema.json
  • schemas/skill.schema.json
  • tooling/lib/compose.sh
  • build_tech_stack_section() in tooling/lib/compose.sh
  • build_skills_section() in tooling/lib/compose.sh
  • build_commands_block() in tooling/lib/compose.sh
• Skill discovery and deployment
  • tooling/lib/index.sh
  • build_skills_index() in tooling/lib/index.sh
  • tooling/lib/deploy-skills.sh
  • deploy_skill() in tooling/lib/deploy-skills.sh
  • generate_skills_readme() in tooling/lib/deploy-skills.sh
• CLI and inventory surfacing
  • justfile
  • tooling/lib/cli.sh
  • cmd_list() in tooling/lib/cli.sh
• Existing regression coverage that should be extended instead of replaced
  • tooling/lib/test.sh
  • T12 all-skills deployment
  • T15 index generation
  • T16 tech stack section
  • T17 lean skills section
  • T19 full skill embedding
  • T34 generated skills README
  • T46 CLI list profiles
• Docs with hard-coded profile inventory text
  • README.md
  • docs/index.md
  • docs/profiles.md

Proposed implementation

Add exactly one new profile and four new skills, but keep the AWS-specific content deliberately narrow so this issue does not overlap with Issue #90’s service-oriented AWS slice.

1. Resolve the profile filename decision before writing files.

   • Preferred implementation path: use profiles/terraform-module.yaml only if maintainers explicitly accept a naming-convention exception for this issue.
   • If maintainers want to preserve the documented pattern, stop and record the decision before coding instead of silently renaming the deliverable.
   • The rest of this plan refers to terraform-module because that is the issue language.

2. Add one flat Terraform module profile using only existing schema fields and existing fragments.

   • Create profiles/terraform-module.yaml.
   • Keep output.structure: flat.
   • Reuse only existing fragments:
     • base: git-conventions, security, code-review, testing-philosophy, documentation
     • languages: []
     • frameworks: []
     • architecture: []
     • practices: tdd, ci-cd
     • domains: []
   • Do not introduce a Terraform fragment in this issue. The repo’s current schema and composition flow already support a profile that carries Terraform guidance through tech_stack, skills, and output.project_header.

3. Make the profile concrete and runnable for a reusable Terraform module workflow.

   • Recommended tech_stack:
     • language_runtime: "Terraform 1.6+ / HCL"
     • test_framework: "terraform test"
     • additional:
       • HashiCorp AWS provider
       • tflint
       • tfsec or Checkov
       • LocalStack
   • Recommended output commands:
     • omit build_command
     • test_command: "terraform test"
     • lint_command: "terraform fmt -check -recursive && terraform init -backend=false && terraform validate"
   • output.project_header should establish the reusable-module contract:
     • variables and outputs are the public API
     • modules remain environment-agnostic
     • no hardcoded account IDs, ARNs, regions, or state backends unless explicitly parameterized
     • examples and tests should prove module behavior before real-cloud rollout
   • Keep the profile AWS-oriented but not AWS-service-specific. This profile is for Terraform module repos, not Lambda/API/event-service application repos.

4. Add four new IaC skills as separate task-oriented entry points under skills/devops/.

   • skills/devops/create-terraform-module/SKILL.md
     • Scope: scaffold a reusable module, choose file layout, define inputs/outputs, pin Terraform/provider versions, add example usage, and document interface expectations.
     • Keep it focused on authoring a module now, not on broad infra architecture.
   • skills/devops/create-terraform-tests/SKILL.md
     • Scope: choose and implement a Terraform module test strategy.
     • First version should prioritize terraform test plus validation/lint gates.
     • Mention Terratest or language-driven harnesses only as opt-in escalation when the repo already uses them or when terraform test is insufficient.
   • skills/devops/design-aws-terraform-iac/SKILL.md
     • Scope: account/region boundaries, module boundaries, state layout, provider aliasing, IAM blast radius, tagging, OIDC/CI auth, and environment separation before resources are written.
     • Keep this skill on Terraform-and-account design. Do not add Lambda/API Gateway/EventBridge/DynamoDB application patterns here; those belong to Issue #90.
   • skills/devops/use-aws-mini-stack-emulator/SKILL.md
     • Scope: run Terraform or closely related infrastructure validation against a local AWS emulator, defaulting to LocalStack unless the target repo already uses another tool.
     • Cover endpoint overrides, provider configuration, supported-service limits, bootstrap steps, and the threshold for falling back to a real AWS sandbox account.
     • Do not expand this skill into general Docker Compose authoring; Docker-local orchestration belongs to Issue #91.

5. Reuse the existing terraform-infrastructure skill instead of refactoring it.

   • Leave skills/backend/terraform-infrastructure/SKILL.md in place.
   • Add it to the new profile so the profile combines:
     • broad Terraform conventions
     • module creation
     • module testing
     • AWS Terraform design
     • emulator guidance
     • CI workflow guidance
   • The new profile skills: list should include:
     • terraform-infrastructure
     • create-terraform-module
     • create-terraform-tests
     • design-aws-terraform-iac
     • use-aws-mini-stack-emulator
     • github-actions-workflow

6. Keep skill boundaries explicit to avoid overlap with adjacent issues.

   • Issue #88 should stop at Terraform-module and infrastructure-design concerns.
   • Issue #90 owns AWS service presets and service-specific skills such as Lambda/API Gateway, EventBridge/SQS, and DynamoDB workload design.
   • Issue #91 owns general Docker/Compose workflows. The emulator skill may mention LocalStack startup assumptions and limits, but it should not become a Docker Compose cookbook.

7. Update profile-facing docs to describe the new IaC profile accurately.

   • README.md
     • change the profile count from 15 to 16
     • update the short inventory copy so it no longer implies the repo only covers TypeScript, Go, Python, and PHP application profiles
   • docs/index.md
     • change the hard-coded count from 15 to 16
     • mention Terraform / IaC coverage in the short summary
   • docs/profiles.md
     • add a row for terraform-module
     • set the language column to Terraform / HCL
     • describe it as a reusable Terraform module profile with AWS-oriented IaC skills

8. Regenerate indexes, but keep expectations precise.

   • Run just index.
   • index/skills.json must change because new skills are being added.
   • index/fragments.json should remain semantically unchanged because no fragment files are being modified, but the worker should still verify the diff instead of assuming no file rewrite occurred.

Files likely affected

• profiles/terraform-module.yaml
• skills/devops/create-terraform-module/SKILL.md
• skills/devops/create-terraform-tests/SKILL.md
• skills/devops/design-aws-terraform-iac/SKILL.md
• skills/devops/use-aws-mini-stack-emulator/SKILL.md
• index/skills.json
• README.md
• docs/index.md
• docs/profiles.md
• tooling/lib/test.sh

Tests to add or update

• Extend T12 in tooling/lib/test.sh so all-skills deployment asserts at least one new IaC skill directory exists under .agentic/skills/, and preferably the two most distinctive additions:
  • .agentic/skills/create-terraform-module/SKILL.md
  • .agentic/skills/use-aws-mini-stack-emulator/SKILL.md
• Extend T15 so index coverage asserts each new skill name exists in index/skills.json, not only that the total count stays above a minimum:
  • create-terraform-module
  • create-terraform-tests
  • design-aws-terraform-iac
  • use-aws-mini-stack-emulator
• Extend T16 or add a nearby technical-stack assertion so composing terraform-module proves ## Technical Stack includes Terraform 1.6+ / HCL.
• Add a lean compose regression for profiles/terraform-module.yaml.
  • Assert generated AGENTS.md contains:
    • ## Technical Stack
    • Terraform 1.6+ / HCL
    • terraform-infrastructure
    • at least one new skill name such as create-terraform-module
    • the module-contract wording from output.project_header
• Add a --full compose regression for the same profile.
  • Assert AGENTS.md inlines at least one full heading from a new IaC skill, for example ## Create Terraform Module Skill or the exact chosen heading.
• Extend T34 so the generated .agentic/skills/README.md includes at least one of the new IaC skills by name.
• Extend T46 so agentic list profiles includes terraform-module.
• Run just index, just lint, and just test because tooling/lib/test.sh changes.

Risks and unknowns

• terraform-module is a documented naming-convention exception unless maintainers explicitly approve it. That decision should happen before file creation to avoid churn.
• design-aws-terraform-iac can easily drift into service-specific AWS design and duplicate the future #90 work. The implementation must keep it at the account/state/module/provider level.
• use-aws-mini-stack-emulator can easily drift into Docker/Compose setup instructions and duplicate #91. Keep it Terraform/emulator focused.
• create-terraform-tests needs a deliberate first-scope choice between terraform test, Terratest, and emulator-backed tests. The first version should keep terraform test as the default path and describe escalation criteria rather than trying to bless all strategies equally.
• The profile has no Terraform language fragment, so all Terraform-specific behavior depends on tech_stack, project_header, and skills. That is acceptable for this issue, but it means the profile text needs to be more precise than a typical language-backed profile.

Dependencies or blockers

• No schema or composition blocker is visible in the current repository. schemas/profile.schema.json already supports a flat profile with base/practice fragments, tech_stack, skills, and output.
• Required research before writing skill content:
  • official Terraform guidance for reusable modules and terraform test
  • current AWS provider patterns relevant to module/state/account design
  • current LocalStack or equivalent emulator limits relevant to Terraform workflows
• Required product decision before implementation:
  • whether terraform-module.yaml is accepted as an issue-driven naming exception

Execution checklist

• Confirm whether profiles/terraform-module.yaml is an approved naming exception; if not, stop and record the required rename decision before coding.
• Review skills/backend/terraform-infrastructure/SKILL.md and define non-overlapping scope for the four new IaC skills.
• Research official Terraform module, terraform test, AWS provider, and LocalStack guidance before drafting content.
• Create profiles/terraform-module.yaml with valid schema structure, Terraform/AWS tech_stack, the six-skill list, and module-specific output commands/header text.
• Add skills/devops/create-terraform-module/SKILL.md.
• Add skills/devops/create-terraform-tests/SKILL.md.
• Add skills/devops/design-aws-terraform-iac/SKILL.md.
• Add skills/devops/use-aws-mini-stack-emulator/SKILL.md.
• Update README.md, docs/index.md, and docs/profiles.md for the new profile and revised profile count.
• Run just index and keep the updated index/skills.json; verify that index/fragments.json did not change unexpectedly.
• Update tooling/lib/test.sh for deploy, index, tech-stack, compose, generated-skills-readme, and CLI profile-list coverage tied to the new profile and skills.
• Run just lint.
• Run just test.

Suggested worker prompt

Provide a copy/paste prompt for a worker agent to implement this issue safely.

Implement Issue #88 in /Users/soulcodex/Code/Personal/agentic as a Terraform-module and infrastructure-design slice, not as a general AWS services slice.

Scope:

• Add one new profile at profiles/terraform-module.yaml, but first confirm that this filename is an accepted exception to the repo’s documented naming convention. If it is not accepted, stop and document the required rename decision instead of silently changing scope.
• Add four new skills:
  • skills/devops/create-terraform-module/SKILL.md
  • skills/devops/create-terraform-tests/SKILL.md
  • skills/devops/design-aws-terraform-iac/SKILL.md
  • skills/devops/use-aws-mini-stack-emulator/SKILL.md
• Reuse the existing skills/backend/terraform-infrastructure/SKILL.md skill by including it in the new profile; do not move or rename it.
• Update README.md, docs/index.md, and docs/profiles.md so the new profile is listed and the hard-coded profile count changes from 15 to 16.
• Run just index and keep the resulting index/skills.json update. Verify index/fragments.json does not change unexpectedly.
• Update tooling/lib/test.sh so coverage proves:
  • the four new skills appear in index/skills.json
  • terraform-module composes correctly in lean mode
  • terraform-module composes correctly in --full mode
  • at least one new IaC skill deploys under .agentic/skills/
  • generated .agentic/skills/README.md includes at least one new IaC skill
  • agentic list profiles includes terraform-module

Implementation constraints:

• Use only the existing profile schema and existing fragments: base fragments plus tdd and ci-cd.
• Do not add a new Terraform fragment unless you find a concrete blocker.
• Use tech_stack and output.project_header to carry Terraform/AWS-specific guidance because there is no existing Terraform language fragment.
• Recommended profile commands:
  • omit build_command
  • test_command: "terraform test"
  • lint_command: "terraform fmt -check -recursive && terraform init -backend=false && terraform validate"
• Keep the skill boundaries explicit:
  • create-terraform-module for module scaffolding and public interface shape
  • create-terraform-tests for Terraform-native module test strategy
  • design-aws-terraform-iac for account/state/module/provider design decisions only
  • use-aws-mini-stack-emulator for emulator usage and limits in Terraform-oriented workflows only
• Do not duplicate future Issue #90 scope. Leave Lambda/API Gateway, EventBridge/SQS, and DynamoDB workload guidance to the AWS issue.
• Do not duplicate Issue #91 scope. The emulator skill may mention LocalStack assumptions and limits, but it must not become a Docker Compose setup guide.
• Before writing the new skills, verify current official guidance for reusable Terraform modules, terraform test, AWS provider design patterns, and the emulator tool you mention by default.

Validation:

• Run just index
• Run just lint
• Run just test