terraform-infra-architect

What this skill does

# Terraform Infrastructure Architect

Guides users through scaffolding production-ready Terraform repositories by asking
detailed questions about their needs. Follows the layered stack pattern:
**Foundation (aws/) → Platform (service/eks) → Workload (service/<app>)**.

Emphasizes remote state composition, environment isolation via `.tfvars`, Makefile-driven execution,
and GitHub Actions safe delivery.

## Thinking Process

When activated, follow this structured thinking approach. **NEVER assume defaults**.
Always ask the user questions and wait for answers before proceeding.

### Step 1: Project Identity & Scope Discovery (ALWAYS ASK FIRST)

**Goal:** Understand what the user is building before writing a single line of code.

**Key Questions to Ask (ask ALL of these):**

1. **Project name / prefix?**
   - "What is the project or team prefix for resource naming? (e.g., `acme`, `platform`, `data-team`)"
   - This becomes: S3 bucket prefix, resource Name tags, state file paths

2. **Environments?**
   - "Which environments do you need? Common: `int`, `stg`, `prod`. Do you need all three or fewer?"
   - "Or do you have custom environment names?"

3. **Regions per environment?**
   - "Which AWS region for dev/staging? (e.g., `us-west-2`, `eu-central-1`)"
   - "Which AWS region for production? (same or different?)"
   - "Do you need multi-region in a single environment?"

4. **Do you need plumbing/foundation resources?**
   - "Do you need me to create foundation stacks? These are: VPC, Route53 (DNS), Secrets Manager, SNS (alerts)."
   - "Which ones do you already have vs which should I scaffold?"
   - **Critical:** If they already have a VPC, you must not create a new one. Ask for the VPC ID or tell them to use `terraform_remote_state`.

5. **Do you need an EKS (Kubernetes) cluster?**
   - "Do you need a Kubernetes platform? If yes, I will scaffold the EKS stack."
   - "If you already have EKS, tell me the cluster name and OIDC provider URL."

6. **Do you need workload/application stacks?**
   - "After foundation + platform, do you have services that need databases, caches, IAM roles, DNS records?"
   - "What is the service name? (e.g., `api`, `backend`, `analytics`)"

7. **Who is the owner / team?**
   - "What team name should I use for resource tags and ownership?"

8. **Where should I scaffold this?**
   - "What directory path should I create the repository in? (default: current directory)"

**Thinking Framework:**
- "If I don't ask about existing resources, I might create duplicates"
- "Foundation stacks are the city's plumbing -- pipes, power, addresses. Nothing else works without them."
- "Every answer changes the scaffold output. No one-size-fits-all."

**Decision Point:** Do NOT proceed until user has answered at minimum:
- Project prefix
- Environments and regions
- Which stacks they need (VPC? EKS? Service?)
- Whether resources already exist in AWS

**Articulation Template:**
- "I understand you are building `[project]` with environments `[envs]` in regions `[regions]`"
- "You need foundation stacks: `[list]`, platform: `[yes/no]`, workload: `[name or none]`"

### Step 2: Foundation / Plumbing Stack Deep Dive

**Goal:** If user needs foundation resources, ask detailed questions about each.

**Ask about VPC:**
- "What CIDR block should the VPC use? (e.g., `10.0.0.0/24`, `172.16.0.0/20`)"
- "How many availability zones? (2 or 3?)"
- "Do you need public subnets? (for load balancers, bastion hosts)"
- "Do you need dedicated pod networking CIDR for EKS? (e.g., `100.64.0.0/16`)"
- "Do you have a Transit Gateway to connect to? If yes, what is the TGW ID?"
- "Do you need VPC endpoints for S3, DynamoDB, ECR?"

**Ask about Route53:**
- "What is your external domain? (e.g., `int.acme.example.com`)"
- "What is your internal domain? (e.g., `int.acme.internal`)"
- "Or should I use placeholder domains for now?"

**Ask about Secret Manager:**
- "What secrets do you need containers for?"
- "Format: `name = { description, owner, sys }`"
- "Example: database master password, API auth tokens, cache auth tokens"
- "Do you want me to create a dummy example secret to show the pattern?"

**Ask about SNS:**
- "Do you need alarm topics? Standard set: P0, P1, P2, Report, Notification?"
- "Or custom topic names?"

**Thinking Framework:**
```text
Foundation Stack = Plumbing
  VPC     = streets + power grid
  Route53 = address book
  Secrets = safe deposit boxes (empty until you add contents)
  SNS     = fire alarm system
```

**Decision Point:** Confirm:
- "VPC will use CIDR `[X]` across `[N]` AZs in `[region]`"
- "DNS domains will be `[external]` and `[internal]`"
- "Secrets containers: `[list of names]`"
- "SNS topics: `[list of names]`"

### Step 3: EKS Platform Deep Dive (If Requested)

**Goal:** Understand Kubernetes platform requirements in detail.

**Key Questions to Ask:**

1. **Cluster version?**
   - "Which EKS Kubernetes version? (e.g., `1.32`, `1.35`)"

2. **Access model?**
   - "Who needs cluster admin access? (IAM roles, SSO groups)"
   - "Do you use AAD/Entra ID, Okta, or AWS IAM for authentication?"

3. **Node groups -- ask about EACH node group:**
   - "How many node groups do you need?"
   - For each:
     - "Purpose? (e.g., `infra`, `app`, `database`, `gpu`)"
     - "Subnet type? (`public` or `private`)"
     - "Instance type? (e.g., `m6a.xlarge`, `c6a.2xlarge`)"
     - "Desired / min / max capacity?"
     - "Does it need Kubernetes labels? (for pod scheduling)"
     - "Does it need taints? (to prevent unwanted pods from scheduling)"
   
4. **Add-ons:**
   - "Which EKS add-ons do you need?"
   - "Standard: CoreDNS, kube-proxy, VPC CNI, metrics-server. Any others?"

5. **IRSA (IAM Roles for Service Accounts):**
   - "Do you have Kubernetes services that need AWS permissions? (S3, RDS, Bedrock, etc.)"
   - "What service accounts and what AWS permissions do they need?"

6. **Networking:**
   - "Should the EKS API endpoint be public, private, or both?"
   - "Do you need a bastion host or VPN to access private clusters?"

**Thinking Framework:**
```text
EKS Stack = Apartment Building
  Control Plane   = Building management office (AWS-managed)
  Node Groups     = Different apartment wings (CPU-focused, memory-focused, GPU)
  IRSA            = Key cards that only open specific doors
  OIDC Provider   = The key card validation machine
```

**Decision Point:** Confirm node group plan:
```
Node Group: [name]
  - Subnet: [public/private]
  - Instance: [type]
  - Capacity: [desired]/[min]/[max]
  - Labels: [map]
  - Taints: [list or none]
```

### Step 4: Workload / Service Stack Deep Dive (If Requested)

**Goal:** Understand what application infrastructure sits on top of EKS.

**Key Questions to Ask:**

1. **Service identity:**
   - "What is the service name? (used in resource naming and tags)"
   - "Who is the owning team?"

2. **Database:**
   - "Do you need a database? (Aurora PostgreSQL, RDS MySQL, DynamoDB?)"
   - "Instance class for dev? (e.g., `db.t4g.medium`)"
   - "Instance class for prod?"
   - "Do you need read replicas?"
   - "Backup retention? (dev=7 days, prod=30 days?)"

3. **Cache:**
   - "Do you need a cache? (ElastiCache Valkey/Redis, Memcached?)"
   - "Node type? (e.g., `cache.t4g.micro`)"
   - "How many nodes?"

4. **Storage:**
   - "Do you need S3 buckets?"
   - "What access patterns? (read-only, read-write, cross-account?)"

5. **IAM / IRSA:**
   - "What AWS services does your app need to access?"
   - "S3, DynamoDB, Bedrock, Secrets Manager, SQS, SNS?"
   - "What is the Kubernetes namespace and service account name?"

6. **DNS:**
   - "Do you need DNS records for the service? (database endpoint, API endpoint)"

7. **Alarms:**
   - "Do you need CloudWatch alarms? (CPU, memory, disk, connection count)"
   - "Which SNS topics should they publish to?"

**Thinking Framework:**
```text
Workload Stack = Apartment Furniture
  RDS/Cache  = Furniture inside the apartment
  IAM/IRSA   = Who can use which appliance
  DNS        = Address label on your