@c0x12c/ai-toolkit 1.15.0

package/rules/infrastructure/STRUCTURE.md

@@ -0,0 +1,234 @@
+---
+paths:
+  - "**/*.tf"
+  - "**/*.hcl"
+  - "**/*.tfvars"
+---
+# Project Organization and Layering
+
+> Full guide: use `/spartan:tf-scaffold` command
+
+## Two Template Variants
+
+### Multi-Root (v1)
+
+Separate root modules per environment. Best for multi-account setups.
+
+Reference: [template-infra-terraform-multiple-root](https://github.com/spartan-stratos/template-infra-terraform-multiple-root)
+
+```
+infra-terraform/
+├── bootstrap/              # Foundational (S3 bucket, OIDC, Route53, SSM)
+├── config/                 # Shared config modules (aws, general, github)
+└── live/
+    ├── shared/             # Reusable module compositions
+    │   ├── ecr/
+    │   ├── rds/
+    │   └── redis/
+    ├── dev/                # Dev root module
+    │   ├── terraform.tf
+    │   ├── provider.tf
+    │   ├── variables.tf
+    │   ├── locals.tf
+    │   └── main.tf
+    └── prod/               # Prod root module
+        └── ...
+```
+
+### Single-Root (v2)
+
+One root module with per-environment variable files. Supports both ECS and EKS. Best for simpler setups.
+
+Reference: [template-infra-terraform-single-root](https://github.com/spartan-stratos/template-infra-terraform-single-root)
+
+```
+infra-terraform/
+├── bootstrap/
+├── config/
+│   ├── aws/
+│   ├── general/
+│   ├── github/
+│   └── eks/                # or ecs/
+└── live/
+    ├── terraform.tf
+    ├── provider.tf
+    ├── variables.tf
+    ├── locals.tf
+    ├── config.tf           # Config module references
+    ├── data.tf             # Remote state references
+    └── envs/
+        ├── dev/
+        │   ├── state.config
+        │   ├── terraform.tfvars
+        │   └── secrets.tfvars
+        └── prod/
+            └── ...
+```
+
+---
+
+## 3-Tier Architecture
+
+All platform infrastructure follows a strict 3-tier dependency chain:
+
+1. **bootstrap/** -- Foundational resources. Manual admin setup, local or S3 backend.
+   - S3 state bucket, OIDC roles, Route53 zones, SSM parameters
+
+2. **config/** -- Centralized config modules (aws, general, github, eks/ecs, slack, datadog). Imported by both bootstrap and live layers. DRY constants.
+
+3. **live/** -- Active infrastructure. Contains shared modules (multi-root) or flat orchestration (single-root). Reads bootstrap outputs via `terraform_remote_state`.
+
+---
+
+## Service-Level Terraform
+
+Service infrastructure lives in the **service repo**, not the infra-terraform repo.
+
+```
+{service}-repo/
+└── terraform/
+    ├── live/
+    │   ├── terraform.tf
+    │   ├── provider.tf
+    │   ├── variables.tf
+    │   ├── locals.tf
+    │   ├── data.tf         # Remote state from infra-terraform
+    │   └── main.tf         # Module call to modules/{service}
+    ├── modules/
+    │   └── {service}/
+    │       ├── variables.tf
+    │       ├── outputs.tf
+    │       ├── locals.tf
+    │       ├── ecr.tf
+    │       ├── rds.tf
+    │       ├── redis.tf
+    │       ├── s3.tf
+    │       ├── eks.tf
+    │       └── sqs.tf
+    └── envs/
+        ├── dev/
+        │   ├── state.config
+        │   ├── terraform.tfvars
+        │   └── secrets.tfvars
+        └── prod/
+            └── ...
+```
+
+---
+
+## File Conventions
+
+Every directory follows these file conventions. Do not combine purposes into one file.
+
+| File | Purpose |
+|------|---------|
+| `terraform.tf` | Backend config, `required_providers`, `required_version` |
+| `variables.tf` | Input variable declarations |
+| `locals.tf` | ALL `locals {}` blocks -- never scattered across files |
+| `outputs.tf` | Module/layer outputs |
+| `config.tf` | Config module references |
+| `provider.tf` | Provider configurations (live layer only) |
+| `data.tf` | Data sources and remote state references |
+
+---
+
+## Anti-Patterns
+
+### WRONG -- Flat structure with all resources in root
+
+```hcl
+# Everything dumped in one directory, no layering
+main.tf          # 500+ lines: VPC, RDS, Redis, EKS, ECR, S3, IAM...
+variables.tf     # 200+ variables for everything
+```
+
+### CORRECT -- Layered separation
+
+```hcl
+# bootstrap/ handles foundational resources
+# config/ centralizes constants
+# live/ orchestrates via module calls
+# Each module has one resource type per file
+```
+
+### WRONG -- Mixing bootstrap and live in one state
+
+```hcl
+# S3 state bucket and application RDS in the same terraform state
+resource "aws_s3_bucket" "tf_state" { ... }  # Bootstrap resource
+resource "aws_db_instance" "app" { ... }      # Live resource
+```
+
+### CORRECT -- Separate state files per tier
+
+```hcl
+# bootstrap/terraform.tf
+terraform {
+  backend "s3" {
+    key = "bootstrap.tfstate"
+  }
+}
+
+# live/terraform.tf
+terraform {
+  backend "s3" {
+    key = "live-dev.tfstate"
+  }
+}
+```
+
+### WRONG -- Service infrastructure in infra-terraform repo
+
+```hcl
+# infra-terraform/live/dev/service-api.tf
+module "service_api_rds" { ... }
+module "service_api_ecr" { ... }
+```
+
+### CORRECT -- Service Terraform in service repo, consuming infra remote state
+
+```hcl
+# {service}-repo/terraform/live/data.tf
+data "terraform_remote_state" "infra" {
+  backend = "s3"
+  config = {
+    bucket = var.infra_state_bucket
+    key    = var.infra_state_key
+    region = var.aws_region
+  }
+}
+```
+
+### WRONG -- Locals scattered across files
+
+```hcl
+# rds.tf
+locals { db_name = "mydb" }
+
+# redis.tf
+locals { redis_name = "myredis" }
+```
+
+### CORRECT -- All locals in locals.tf
+
+```hcl
+# locals.tf
+locals {
+  db_name    = "mydb"
+  redis_name = "myredis"
+}
+```
+
+---
+
+## Quick Reference
+
+| Aspect | Rule |
+|--------|------|
+| Template choice | Multi-root for multi-account, single-root for simple setups |
+| Tiers | bootstrap -> config -> live (strict dependency chain) |
+| Service infra | In service repo, not infra-terraform |
+| File per resource | One resource type per `.tf` file in modules |
+| Locals | ALL in `locals.tf`, never scattered |
+| Providers | Only in `live/` layer |
+| Environment config | `envs/{env}/` with state.config, terraform.tfvars, secrets.tfvars |

package/rules/infrastructure/VARIABLES.md

@@ -0,0 +1,285 @@
+---
+paths:
+  - "**/*.tf"
+  - "**/*.hcl"
+  - "**/*.tfvars"
+---
+# Variable Design and Validation
+
+## Validation Blocks
+
+Add validation blocks to constrain variable values at plan time, not apply time.
+
+```hcl
+variable "environment" {
+  description = "Deployment environment"
+  type        = string
+
+  validation {
+    condition     = can(regex("^(dev|staging|prod)$", var.environment))
+    error_message = "Must be dev, staging, or prod."
+  }
+}
+
+variable "aws_region" {
+  description = "AWS region"
+  type        = string
+
+  validation {
+    condition     = can(regex("^[a-z]{2}-[a-z]+-[0-9]$", var.aws_region))
+    error_message = "Must be a valid AWS region (e.g., us-west-2)."
+  }
+}
+
+variable "service_name" {
+  description = "Service name (kebab-case)"
+  type        = string
+
+  validation {
+    condition     = can(regex("^[a-z][a-z0-9-]+$", var.service_name))
+    error_message = "Must be lowercase kebab-case."
+  }
+}
+```
+
+### WRONG -- No validation on constrained values
+
+```hcl
+variable "environment" {
+  type = string
+  # No validation -- "production", "PROD", "p" all accepted
+}
+```
+
+### CORRECT -- Validation with clear error message
+
+```hcl
+variable "environment" {
+  type = string
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.environment)
+    error_message = "Must be dev, staging, or prod."
+  }
+}
+```
+
+---
+
+## Sensitive Flag
+
+Mark all credential variables with `sensitive = true`. This prevents values from appearing in plan output and logs.
+
+```hcl
+variable "openai_api_key" {
+  description = "OpenAI API key"
+  type        = string
+  sensitive   = true
+}
+
+variable "datadog_api_key" {
+  description = "Datadog API key"
+  type        = string
+  sensitive   = true
+}
+
+variable "slack_webhook_url" {
+  description = "Slack webhook URL for alerts"
+  type        = string
+  sensitive   = true
+}
+```
+
+---
+
+## Flat Locals Pattern
+
+Extract remote state values into flat locals in `locals.tf`. Reference locals throughout the module instead of repeating `data.terraform_remote_state` lookups.
+
+### WRONG -- Nested lookups in module calls
+
+```hcl
+# rds.tf
+module "rds" {
+  source     = "c0x12c/rds/aws"
+  version    = "~> 0.6.6"
+  vpc_id     = data.terraform_remote_state.infra.outputs.vpc_id
+  subnet_ids = data.terraform_remote_state.infra.outputs.private_subnet_ids
+}
+
+# redis.tf
+module "redis" {
+  source     = "c0x12c/redis/aws"
+  version    = "~> 0.2.0"
+  vpc_id     = data.terraform_remote_state.infra.outputs.vpc_id       # Repeated
+  subnet_ids = data.terraform_remote_state.infra.outputs.private_subnet_ids  # Repeated
+}
+```
+
+### CORRECT -- Flat locals, reference once
+
+```hcl
+# locals.tf
+locals {
+  vpc_id             = data.terraform_remote_state.infra.outputs.vpc_id
+  private_subnet_ids = data.terraform_remote_state.infra.outputs.private_subnet_ids
+  vpc_cidr_block     = data.terraform_remote_state.infra.outputs.vpc_cidr_block
+  eks_cluster_name   = data.terraform_remote_state.infra.outputs.eks_cluster_name
+}
+
+# rds.tf
+module "rds" {
+  source     = "c0x12c/rds/aws"
+  version    = "~> 0.6.6"
+  vpc_id     = local.vpc_id
+  subnet_ids = local.private_subnet_ids
+}
+
+# redis.tf
+module "redis" {
+  source     = "c0x12c/redis/aws"
+  version    = "~> 0.2.0"
+  vpc_id     = local.vpc_id
+  subnet_ids = local.private_subnet_ids
+}
+```
+
+---
+
+## ALL Locals in locals.tf
+
+Never scatter `locals {}` blocks across multiple files. One file, one block.
+
+### WRONG -- Locals in multiple files
+
+```hcl
+# rds.tf
+locals {
+  db_name = replace(var.service_name, "-", "_")
+}
+
+# eks.tf
+locals {
+  namespace = var.service_name
+}
+```
+
+### CORRECT -- Single locals.tf
+
+```hcl
+# locals.tf
+locals {
+  db_name   = replace(var.service_name, "-", "_")
+  namespace = var.service_name
+
+  vpc_id             = data.terraform_remote_state.infra.outputs.vpc_id
+  private_subnet_ids = data.terraform_remote_state.infra.outputs.private_subnet_ids
+}
+```
+
+---
+
+## .tfvars Separation
+
+Split variable values into two files per environment:
+
+- `terraform.tfvars` -- public, version-controlled, non-sensitive
+- `secrets.tfvars` -- encrypted via git-secret-protector, sensitive values only
+
+```hcl
+# envs/dev/terraform.tfvars
+environment        = "dev"
+aws_region         = "us-west-2"
+service_name       = "{service}"
+rds_instance_class = "db.t3.micro"
+redis_node_type    = "cache.t3.micro"
+
+# envs/dev/secrets.tfvars (encrypted in git)
+openai_api_key    = "sk-..."
+datadog_api_key   = "dd-..."
+slack_webhook_url = "https://hooks.slack.com/..."
+```
+
+Apply with both files:
+
+```bash
+terraform plan \
+  -var-file=envs/dev/terraform.tfvars \
+  -var-file=envs/dev/secrets.tfvars
+```
+
+---
+
+## Default Values for Sizing
+
+Provide sensible defaults for sizing parameters. Override per environment in `.tfvars`.
+
+```hcl
+variable "rds_instance_class" {
+  description = "RDS instance class"
+  type        = string
+  default     = "db.t3.micro"  # Dev default, override for prod
+}
+
+variable "redis_node_type" {
+  description = "ElastiCache node type"
+  type        = string
+  default     = "cache.t3.micro"
+}
+
+variable "rds_allocated_storage" {
+  description = "RDS allocated storage in GB"
+  type        = number
+  default     = 20
+}
+
+variable "eks_cluster_version" {
+  description = "EKS cluster Kubernetes version"
+  type        = string
+  default     = "1.31"
+}
+```
+
+---
+
+## Config Modules for Shared Constants
+
+Use config modules (in `config/`) for values shared across layers (region, AZs, stack name, default tags). Import in both bootstrap and live.
+
+```hcl
+# config/aws/main.tf
+output "region" {
+  value = "us-west-2"
+}
+
+output "availability_zones" {
+  value = ["us-west-2a", "us-west-2b"]
+}
+
+output "default_tags" {
+  value = {
+    ManagedBy = "Terraform"
+    Project   = var.project_name
+  }
+}
+
+# live/config.tf
+module "config_aws" {
+  source = "../config/aws"
+}
+```
+
+---
+
+## Quick Reference
+
+| Aspect | Rule |
+|--------|------|
+| Validation | Add `validation {}` blocks for constrained values |
+| Sensitive | `sensitive = true` on all credentials |
+| Flat locals | Extract remote state to `locals {}`, reference `local.*` |
+| Locals file | ALL locals in `locals.tf`, never scattered |
+| tfvars split | `terraform.tfvars` (public) + `secrets.tfvars` (encrypted) |
+| Sizing defaults | Provide dev-appropriate defaults, override in tfvars |
+| Config modules | `config/` for shared constants (region, AZs, tags) |
+| Variable naming | `snake_case` with resource prefix |
+| Descriptions | Every variable must have a `description` |

package/rules/shared-backend/ARCHITECTURE.md

@@ -0,0 +1,46 @@
+# Layered Architecture
+
+> Full guide: use `/api-endpoint-creator` or `/backend-api-design` skill
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           LAYERED ARCHITECTURE                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  CONTROLLER                                                                  │
+│  ───────────                                                                 │
+│  HTTP handling, validation, authentication                                   │
+│  Calls: Managers ONLY                                                        │
+│                                                                              │
+│         │                                                                    │
+│         ▼                                                                    │
+│                                                                              │
+│  MANAGER                                                                     │
+│  ────────                                                                    │
+│  Business logic, orchestration, transactions, persistence                    │
+│  Calls: Services (for external data), Repositories (for DB)                  │
+│                                                                              │
+│         │                    │                                               │
+│         ▼                    ▼                                               │
+│                                                                              │
+│  SERVICE                 REPOSITORY                                          │
+│  ────────                ───────────                                         │
+│  External API calls      Database access                                     │
+│  Data transformation     CRUD operations                                     │
+│  Returns DTOs            Returns Entities                                    │
+│                                                                              │
+│         │                                                                    │
+│         ▼                                                                    │
+│                                                                              │
+│  EXTERNAL APIs           DATABASE                                            │
+│  (GitHub, Slack, etc)    (PostgreSQL)                                        │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+| Layer | Can Call | Cannot Call |
+|-------|----------|-------------|
+| Controller | Managers, Detectors | Repositories, DB Context |
+| Manager | Repositories, Services, Other Managers | External APIs directly |
+| Service | External API clients, Config | Repositories, DB Context |
+| Repository | Database | - |