@c0x12c/ai-toolkit 1.15.0

package/skills/terraform-module-creator/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: terraform-module-creator
+description: Create or extend reusable Terraform modules with proper structure, interfaces, and documentation. Use when building new infrastructure modules or extending existing ones.
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# Terraform Module Creator
+
+Creates or extends reusable Terraform modules following standard conventions for structure, interfaces, and composition.
+
+## When to Use
+
+- Creating a new reusable infrastructure module
+- Extending an existing module with new resources
+- Refactoring inline resources into a proper module
+- Standardizing an ad-hoc module to follow conventions
+
+## Process
+
+### 1. Determine Module Purpose
+
+Ask the user:
+- **Module name** (e.g., `rds`, `ecs-service`, `s3-bucket`)
+- **Resources managed** (what AWS/cloud resources it wraps)
+- **Consumers** (which services will use this module)
+
+### 2. Create Module Directory
+
+```
+modules/{module-name}/
+  main.tf           # Core resource or locals
+  variables.tf      # All input variables
+  outputs.tf        # All outputs
+  {resource}.tf     # One file per resource type
+  versions.tf       # Provider version constraints
+  README.md         # Auto-generated usage docs
+```
+
+### 3. Define Variables
+
+```hcl
+# variables.tf — explicit interfaces, no hardcoded defaults for critical values
+
+variable "name" {
+  description = "Resource name prefix"
+  type        = string
+
+  validation {
+    condition     = can(regex("^[a-z][a-z0-9-]+$", var.name))
+    error_message = "Name must be lowercase alphanumeric with hyphens."
+  }
+}
+
+variable "vpc_id" {
+  description = "VPC ID where resources are deployed"
+  type        = string
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs for resource placement"
+  type        = list(string)
+}
+
+variable "tags" {
+  description = "Additional tags to apply to all resources"
+  type        = map(string)
+  default     = {}
+}
+
+# Use object types for grouped config
+variable "backup" {
+  description = "Backup configuration"
+  type = object({
+    enabled          = bool
+    retention_days   = number
+    window           = optional(string, "03:00-04:00")
+  })
+  default = {
+    enabled        = true
+    retention_days = 7
+  }
+}
+```
+
+### 4. Resource Per File
+
+```hcl
+# rds.tf — one resource type per file
+resource "aws_db_instance" "this" {
+  identifier     = var.name
+  engine         = var.engine
+  engine_version = var.engine_version
+  instance_class = var.instance_class
+
+  allocated_storage     = var.allocated_storage
+  max_allocated_storage = var.max_allocated_storage
+
+  db_name  = var.db_name
+  username = var.master_username
+  password = var.master_password
+
+  db_subnet_group_name   = aws_db_subnet_group.this.name
+  vpc_security_group_ids = [aws_security_group.rds.id]
+
+  backup_retention_period = var.backup.retention_days
+  backup_window           = var.backup.window
+  deletion_protection     = var.deletion_protection
+
+  tags = merge(var.tags, {
+    Name = var.name
+  })
+}
+
+resource "aws_db_subnet_group" "this" {
+  name       = "${var.name}-subnet-group"
+  subnet_ids = var.subnet_ids
+
+  tags = merge(var.tags, {
+    Name = "${var.name}-subnet-group"
+  })
+}
+```
+
+### 5. Security Group Per Resource
+
+```hcl
+# sg.tf
+resource "aws_security_group" "rds" {
+  name_prefix = "${var.name}-rds-"
+  vpc_id      = var.vpc_id
+  description = "Security group for ${var.name} RDS instance"
+
+  tags = merge(var.tags, {
+    Name = "${var.name}-rds-sg"
+  })
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+resource "aws_security_group_rule" "rds_ingress" {
+  type                     = "ingress"
+  from_port                = 5432
+  to_port                  = 5432
+  protocol                 = "tcp"
+  security_group_id        = aws_security_group.rds.id
+  source_security_group_id = var.app_security_group_id
+  description              = "Allow access from application"
+}
+```
+
+### 6. Define Outputs
+
+```hcl
+# outputs.tf — expose values that consumers need
+output "endpoint" {
+  description = "Database connection endpoint"
+  value       = aws_db_instance.this.endpoint
+}
+
+output "port" {
+  description = "Database port"
+  value       = aws_db_instance.this.port
+}
+
+output "security_group_id" {
+  description = "Security group ID for the database"
+  value       = aws_security_group.rds.id
+}
+
+output "arn" {
+  description = "ARN of the database instance"
+  value       = aws_db_instance.this.arn
+}
+
+# Mark sensitive outputs
+output "connection_string" {
+  description = "Full connection string"
+  value       = "postgresql://${var.master_username}:${var.master_password}@${aws_db_instance.this.endpoint}/${var.db_name}"
+  sensitive   = true
+}
+```
+
+### 7. Version Constraints
+
+```hcl
+# versions.tf
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.0"
+    }
+  }
+}
+```
+
+### 8. Publishing to Registry
+
+New modules should be contributed to the [c0x12c Terraform Registry](https://registry.terraform.io/namespaces/c0x12c):
+
+1. Create a new repo at `https://github.com/c0x12c/terraform-aws-{module-name}` following the Terraform registry naming convention
+2. Push the module code with proper `versions.tf`, `variables.tf`, `outputs.tf`
+3. Tag a release: `git tag v0.1.0 && git push --tags`
+4. The registry auto-publishes from GitHub tags
+5. Consumers then use: `source = "c0x12c/{module-name}/aws"` with `version = "~> 0.1.0"`
+
+### 9. Module Usage Example
+
+```hcl
+# How consumers call this module — use c0x12c registry
+module "database" {
+  source  = "c0x12c/rds/aws"
+  version = "~> 0.6.6"
+
+  name            = "${local.name_prefix}-db"
+  engine          = "postgres"
+  engine_version  = "15.4"
+  instance_class  = "db.t3.micro"
+  allocated_storage = 20
+  db_name         = "myservice"
+  master_username = "admin"
+  master_password = var.db_password
+  vpc_id          = local.vpc_id
+  subnet_ids      = local.private_subnet_ids
+  app_security_group_id = module.ecs_service.security_group_id
+
+  deletion_protection = var.env == "prod"
+
+  backup = {
+    enabled        = true
+    retention_days = var.env == "prod" ? 30 : 7
+  }
+
+  tags = local.common_tags
+}
+```
+
+## Interaction Style
+
+- Asks module purpose and consumers before generating
+- Creates complete module in one pass
+- Includes usage example showing how to call the module
+- Validates naming and interface consistency
+
+## Rules
+
+- NO provider blocks in modules — providers come from the caller
+- NO hardcoded values — everything via variables
+- Explicit interfaces — every input has description, type, and validation where useful
+- One resource per file — named after the resource type
+- Use `this` as the resource name for the primary resource
+- `name_prefix` over `name` for security groups (allows create-before-destroy)
+- Mark sensitive outputs with `sensitive = true`
+- Use `object()` types for grouped configuration
+- Use `optional()` for fields with sensible defaults
+- Version constraints in `versions.tf`, not `main.tf`
+- Tags passed through and merged, never overridden
+- Lifecycle rules for zero-downtime updates where applicable
+
+## Output
+
+Produces a module directory:
+
+```
+modules/{module-name}/
+  main.tf
+  variables.tf
+  outputs.tf
+  versions.tf
+  sg.tf
+  {resource-1}.tf
+  {resource-2}.tf
+```
+
+Plus a usage snippet for consumers to copy.

package/skills/terraform-review/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: terraform-review
+description: PR review checklist for Terraform changes covering structure, state safety, security, naming, modules, variables, providers, and CI/CD. Use when reviewing Terraform PRs or doing pre-merge checks.
+allowed_tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+# Terraform Review
+
+Runs an 8-category review checklist on Terraform changes. Produces an Approved / Needs Changes / Blocked verdict.
+
+## When to Use
+
+- Reviewing a Terraform pull request
+- Pre-merge validation of infrastructure changes
+- Self-review before opening a PR
+- Auditing existing Terraform code
+
+## Process
+
+### 1. Structure
+
+- [ ] Files follow standard layout: `live/`, `modules/`, `envs/`
+- [ ] One resource per file in modules
+- [ ] `terraform.tf` has backend + provider config
+- [ ] `variables.tf`, `outputs.tf`, `locals.tf` are separate files
+- [ ] No `.terraform/` or `*.tfstate*` in the PR
+
+```
+# CORRECT structure
+terraform/
+  live/terraform.tf        # backend + provider
+  live/variables.tf        # inputs
+  live/locals.tf           # computed values
+  live/outputs.tf          # exports
+  modules/{service}/       # one resource per file
+  envs/{env}/              # per-environment config
+
+# WRONG — everything in one file
+terraform/main.tf          # 500 lines of mixed resources
+```
+
+### 2. State Safety
+
+- [ ] No `terraform state` commands in automation
+- [ ] State stored in S3 with DynamoDB locking
+- [ ] `prevent_destroy` on critical resources (RDS, S3 with data)
+- [ ] No resources removed without `terraform state rm` plan documented
+- [ ] `create_before_destroy` on security groups and launch configs
+- [ ] Import blocks used for adopting existing resources (not `terraform import` CLI)
+
+```hcl
+# CORRECT — protect critical resources
+resource "aws_db_instance" "main" {
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+
+# CORRECT — zero-downtime SG updates
+resource "aws_security_group" "app" {
+  name_prefix = "${local.name_prefix}-app-"
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+```
+
+### 3. Security
+
+- [ ] No secrets in `.tf` or `.tfvars` committed to git
+- [ ] Sensitive variables marked `sensitive = true`
+- [ ] S3 buckets block public access
+- [ ] RDS/Redis in private subnets only
+- [ ] Security groups follow least privilege (no `0.0.0.0/0` ingress on non-ALB)
+- [ ] Encryption enabled (S3 SSE, RDS encryption, Redis transit + at-rest)
+- [ ] IAM policies use least privilege, no `*` actions on `*` resources
+
+```hcl
+# WRONG — overly permissive
+resource "aws_security_group_rule" "bad" {
+  cidr_blocks = ["0.0.0.0/0"]
+  from_port   = 0
+  to_port     = 65535
+}
+
+# CORRECT — scoped to specific source
+resource "aws_security_group_rule" "good" {
+  source_security_group_id = var.alb_security_group_id
+  from_port                = 8080
+  to_port                  = 8080
+}
+```
+
+### 4. Naming
+
+- [ ] Resources use `local.name_prefix` (pattern: `{project}-{service}-{env}`)
+- [ ] Consistent naming across all resources in the module
+- [ ] Tags include: Project, Service, Environment, ManagedBy
+- [ ] No hardcoded names or account IDs
+
+```hcl
+# CORRECT
+locals {
+  name_prefix = "${var.project}-${var.service}-${var.env}"
+}
+
+# WRONG
+resource "aws_s3_bucket" "assets" {
+  bucket = "my-bucket-prod"  # hardcoded
+}
+```
+
+### 5. Modules
+
+- [ ] No provider blocks inside modules
+- [ ] Module source uses version pinning (`?ref=vX.Y.Z`)
+- [ ] No circular module dependencies
+- [ ] Module outputs only expose what consumers need
+- [ ] Modules have `versions.tf` with required provider versions
+
+```hcl
+# CORRECT — pinned version
+module "rds" {
+  source = "git::https://github.com/{project}/terraform-modules.git//rds?ref=v1.2.0"
+}
+
+# WRONG — no version pin
+module "rds" {
+  source = "git::https://github.com/{project}/terraform-modules.git//rds"
+}
+```
+
+### 6. Variables
+
+- [ ] All variables have `description` and `type`
+- [ ] Sensitive variables marked `sensitive = true`
+- [ ] Validation blocks on critical inputs (CIDR, names, enums)
+- [ ] No unused variables
+- [ ] Defaults are sensible for dev, overridden per env
+
+```hcl
+# CORRECT
+variable "instance_class" {
+  description = "RDS instance class"
+  type        = string
+  default     = "db.t3.micro"
+
+  validation {
+    condition     = can(regex("^db\\.", var.instance_class))
+    error_message = "Must be a valid RDS instance class."
+  }
+}
+
+# WRONG — no description, no type
+variable "instance_class" {}
+```
+
+### 7. Providers
+
+- [ ] Provider versions pinned with `~>` (pessimistic constraint)
+- [ ] `required_version` for Terraform itself
+- [ ] Provider config only in `live/terraform.tf`, never in modules
+- [ ] Default tags configured at provider level
+
+### 8. CI/CD
+
+- [ ] `terraform fmt -check` runs in CI
+- [ ] `terraform validate` runs in CI
+- [ ] Plan output posted as PR comment
+- [ ] Apply only runs on merge to main
+- [ ] State locking prevents concurrent applies
+- [ ] Secrets injected via CI environment, not committed
+
+## Interaction Style
+
+- Reads all changed `.tf` files in the PR
+- Checks every category — does not skip sections
+- Flags blocking issues (security, state safety) separately from suggestions
+- Shows exact file and line for each finding
+
+## Rules
+
+- Blocking issues: secrets in code, no state locking, `0.0.0.0/0` ingress, missing encryption
+- Needs Changes: missing descriptions, no version pin, naming inconsistency
+- Suggestions: code style, optional validations, documentation
+
+## Output
+
+Produces a structured review:
+
+```
+## Terraform Review: {PR title}
+
+### Verdict: Approved | Needs Changes | Blocked
+
+### Findings
+
+#### Blocked (if any)
+- [ ] **[Security]** Secrets found in terraform.tfvars — file:line
+
+#### Needs Changes (if any)
+- [ ] **[Naming]** Hardcoded bucket name in s3.tf:12
+- [ ] **[Modules]** Missing version pin on RDS module
+
+#### Suggestions (if any)
+- **[Variables]** Consider adding validation on `instance_class`
+
+### Checklist Summary
+| Category  | Status |
+|-----------|--------|
+| Structure | Pass   |
+| State     | Pass   |
+| Security  | Fail   |
+| Naming    | Warn   |
+| Modules   | Warn   |
+| Variables | Pass   |
+| Providers | Pass   |
+| CI/CD     | Pass   |
+```