@jetrabbits/agentic 0.0.1

package/areas/devops/infrastructure/skills/state-management/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: state-management
+type: skill
+description: Manage Terraform remote state — backend setup, state isolation, locking, import, mv, and state surgery.
+related-rules:
+  - state-management.md
+  - iac-standards.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Skill: Terraform State Management
+
+> **Expertise:** Remote backends, state isolation, import, mv, rm, state surgery, cross-stack references.
+
+## When to load
+
+When setting up a new Terraform backend, debugging state lock, importing manually-created resources, or safely moving resources between state files.
+
+## Backend Setup Patterns
+
+```hcl
+# AWS S3 + DynamoDB lock
+terraform {
+  backend "s3" {
+    bucket         = "mycompany-terraform-state"
+    key            = "${var.environment}/${var.component}/terraform.tfstate"
+    region         = "us-east-1"
+    encrypt        = true
+    kms_key_id     = "alias/terraform-state"
+    dynamodb_table = "terraform-state-lock"
+  }
+}
+
+# GCS (GCP) — built-in locking, no separate lock table needed
+terraform {
+  backend "gcs" {
+    bucket = "mycompany-terraform-state"
+    prefix = "${var.environment}/${var.component}"
+  }
+}
+
+# Terraform Cloud / HCP Terraform
+terraform {
+  cloud {
+    organization = "mycompany"
+    workspaces { name = "production-network" }
+  }
+}
+```
+
+## State Isolation (per environment × component)
+
+```
+state/
+├── staging/
+│   ├── network/terraform.tfstate
+│   ├── k8s-cluster/terraform.tfstate
+│   └── databases/terraform.tfstate
+└── production/
+    ├── network/terraform.tfstate
+    ├── k8s-cluster/terraform.tfstate
+    └── databases/terraform.tfstate
+```
+
+**Rule**: Staging and production **must** use separate state files (separate key/prefix, ideally separate bucket).
+
+## Cross-Stack Values (avoid `terraform_remote_state`)
+
+```hcl
+# ✅ Publish outputs to SSM Parameter Store
+resource "aws_ssm_parameter" "vpc_id" {
+  name  = "/${var.environment}/network/vpc_id"
+  type  = "String"
+  value = aws_vpc.this.id
+}
+
+# ✅ Consume in another stack via data source
+data "aws_ssm_parameter" "vpc_id" {
+  name = "/${var.environment}/network/vpc_id"
+}
+
+resource "aws_subnet" "app" {
+  vpc_id = data.aws_ssm_parameter.vpc_id.value
+}
+```
+
+## State Import (bring unmanaged resource under TF control)
+
+```bash
+# 1. Write the resource block in .tf first
+resource "aws_s3_bucket" "legacy" {
+  bucket = "my-legacy-bucket"
+}
+
+# 2. Import the existing resource
+terraform import aws_s3_bucket.legacy my-legacy-bucket
+
+# 3. Run plan — should show no changes if .tf matches reality
+terraform plan   # should be: "No changes."
+```
+
+## State Move (rename / reorganize)
+
+```hcl
+# Safe rename using moved{} block (Terraform 1.1+) — no CLI required
+moved {
+  from = aws_instance.web
+  to   = aws_instance.this["web-01"]
+}
+
+# After apply, remove the moved{} block
+```
+
+```bash
+# Manual state mv (use when moved{} block is not applicable)
+# ALWAYS take a backup first
+terraform state pull > backup-$(date +%Y%m%d-%H%M%S).tfstate
+
+terraform state mv \
+  'aws_security_group.old_name' \
+  'aws_security_group.new_name'
+```
+
+## State Surgery (break-glass commands)
+
+```bash
+# List all resources in state
+terraform state list
+
+# Show a specific resource's state
+terraform state show 'aws_instance.this["web-01"]'
+
+# Remove a resource from state WITHOUT destroying it (use when managed outside TF)
+terraform state rm 'aws_s3_bucket.legacy'
+
+# Force-unlock a stuck state lock (use only when lock is genuinely stale)
+terraform force-unlock <LOCK_ID>
+# Lock ID from error message: "Error acquiring the state lock"
+
+# Pull state for manual inspection
+terraform state pull | jq '.resources[] | {type: .type, name: .name}'
+
+# Replace a resource (force-recreate without destroy first)
+terraform apply -replace='aws_instance.this["web-01"]'
+```
+
+## Debugging Lock Issues
+
+```bash
+# Error: "Error acquiring the state lock" + lock ID
+# Check DynamoDB for stale lock:
+aws dynamodb get-item \
+  --table-name terraform-state-lock \
+  --key '{"LockID": {"S": "mycompany-terraform-state/production/network/terraform.tfstate"}}'
+
+# Verify no apply is actually running before force-unlock
+# Only force-unlock if you are certain no other process holds the lock
+terraform force-unlock <LOCK_ID_FROM_ERROR>
+```

package/areas/devops/infrastructure/skills/terraform-modules/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: terraform-modules
+type: skill
+description: Design reusable, well-tested Terraform modules with cloud-agnostic interfaces and safe state management.
+related-rules:
+  - iac-standards.md
+  - state-management.md
+  - secret-hygiene.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Skill: Terraform Modules
+
+> **Expertise:** Reusable module design, for_each patterns, remote state, data sources, module testing with Terratest.
+
+## When to load
+
+When writing new Terraform, reviewing IaC PRs, designing module interfaces, or debugging plan/apply failures.
+
+## Module Interface Design
+
+```hcl
+# variables.tf — define a clean, minimal interface
+variable "project" {
+  description = "Project name used in resource naming and tags"
+  type        = string
+}
+
+variable "environment" {
+  description = "Deployment environment (dev|staging|production)"
+  type        = string
+  validation {
+    condition     = contains(["dev", "staging", "production"], var.environment)
+    error_message = "environment must be dev, staging, or production."
+  }
+}
+
+variable "instance_count" {
+  description = "Number of instances to create"
+  type        = number
+  default     = 1
+}
+
+# outputs.tf — expose only what callers need
+output "instance_ids" {
+  description = "List of created instance IDs"
+  value       = aws_instance.this[*].id
+}
+
+output "private_ips" {
+  description = "Private IP addresses"
+  value       = aws_instance.this[*].private_ip
+  sensitive   = false
+}
+```
+
+## for_each vs count
+
+```hcl
+# ✅ for_each — stable keys, safe to add/remove
+resource "aws_security_group_rule" "allow" {
+  for_each    = var.allowed_ports   # map: { "http" = 80, "https" = 443 }
+  type        = "ingress"
+  from_port   = each.value
+  to_port     = each.value
+  protocol    = "tcp"
+  cidr_blocks = ["0.0.0.0/0"]
+}
+
+# ❌ count — index-based, removing item N shifts all subsequent items
+resource "aws_instance" "this" {
+  count = var.instance_count   # removing instance 0 destroys ALL and recreates
+}
+
+# ✅ for_each with map for instances
+resource "aws_instance" "this" {
+  for_each      = var.instances   # map: { "web-1" = {...}, "web-2" = {...} }
+  instance_type = each.value.instance_type
+}
+```
+
+## Dynamic Blocks
+
+```hcl
+resource "aws_security_group" "this" {
+  name = "${var.project}-${var.environment}-sg"
+
+  dynamic "ingress" {
+    for_each = var.ingress_rules
+    content {
+      from_port   = ingress.value.from_port
+      to_port     = ingress.value.to_port
+      protocol    = ingress.value.protocol
+      cidr_blocks = ingress.value.cidr_blocks
+    }
+  }
+}
+```
+
+## Data Sources (cloud-agnostic patterns)
+
+```hcl
+# Latest Ubuntu 22.04 AMI (AWS)
+data "aws_ami" "ubuntu" {
+  most_recent = true
+  owners      = ["099720109477"]  # Canonical
+  filter {
+    name   = "name"
+    values = ["ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"]
+  }
+}
+
+# Cross-stack reference via SSM (avoid terraform_remote_state across envs)
+data "aws_ssm_parameter" "vpc_id" {
+  name = "/${var.environment}/network/vpc_id"
+}
+```
+
+## Locals for DRY Code
+
+```hcl
+locals {
+  name_prefix = "${var.project}-${var.environment}"
+  common_tags = {
+    Project     = var.project
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Owner       = var.owner
+  }
+}
+
+resource "aws_s3_bucket" "this" {
+  bucket = "${local.name_prefix}-assets-${random_id.suffix.hex}"
+  tags   = local.common_tags
+}
+```
+
+## moved Block (safe refactoring)
+
+```hcl
+# When renaming a resource — prevents destroy+create
+moved {
+  from = aws_instance.web
+  to   = aws_instance.this["web-1"]
+}
+```
+
+## CI/CD Integration
+
+```bash
+# Standard pipeline steps
+terraform init -backend-config=environments/${ENV}/backend.hcl
+terraform validate
+terraform fmt -check -recursive
+terraform plan -var-file=environments/${ENV}/terraform.tfvars -out=tfplan
+# After approval:
+terraform apply tfplan
+```
+
+## Anti-Patterns
+
+| Anti-pattern | Fix |
+|:---|:---|
+| `count` for multi-instance | Use `for_each` with map keys |
+| Hardcoded region/AZ | Use `data` source or variable |
+| `?ref=main` module source | Pin to version tag |
+| Provider config inside module | Provider in root module only |
+| `terraform_remote_state` across envs | SSM / Consul KV for cross-stack values |
+| Sensitive values in outputs without `sensitive=true` | Mark all secret outputs as sensitive |

package/areas/devops/infrastructure/workflows/destroy-environment.md

@@ -0,0 +1,96 @@
+---
+name: destroy-environment
+type: workflow
+trigger: /destroy-environment
+description: Safely destroy a Terraform-managed environment — pre-checks, approval gate, ordered teardown, and state cleanup.
+inputs:
+  - environment_name
+  - reason (decommission|cost-saving|reset)
+outputs:
+  - environment_destroyed
+  - state_cleaned
+roles:
+  - devops-engineer
+  - team-lead
+execution:
+  initiator: developer
+related-rules:
+  - state-management.md
+  - immutability.md
+uses-skills:
+  - terraform-modules
+  - state-management
+quality-gates:
+  - explicit team-lead approval required before any destroy
+  - backup of state file taken before destroy
+  - production environment requires VP Engineering sign-off
+---
+
+## Steps
+
+### 1. Confirm Scope — `@devops-engineer`
+- List all resources to be destroyed: `terraform plan -destroy -var-file=terraform.tfvars`
+- Verify: is there **production data** in this environment? (databases, object storage)
+- Confirm no active traffic or dependent services
+- **Stop here if**: environment has active users or unarchived data
+
+### 2. Approval — `@team-lead` (+ VP Eng if production)
+- Review the destroy plan output
+- Confirm: data archived or migrated
+- Sign off in the PR/ticket: `APPROVED FOR DESTROY — [name] [date]`
+- **Done when:** written approval recorded
+
+### 3. Pre-Destroy Backup — `@devops-engineer`
+```bash
+# Back up Terraform state file
+terraform state pull > backups/state-${ENV}-$(date +%Y%m%d-%H%M%S).tfstate
+
+# If databases present: take final snapshot
+pgbackrest --stanza=${ENV}-db --type=full backup
+
+# Export any S3/GCS bucket contents if needed
+aws s3 sync s3://${ENV}-data ./backups/s3-${ENV}/
+```
+- **Done when:** backups verified (not just initiated)
+
+### 4. Ordered Teardown — `@devops-engineer`
+```bash
+# Destroy in reverse dependency order
+# Workloads first, then networking, then storage last
+
+# Option A: full destroy
+terraform destroy -var-file=terraform.tfvars -auto-approve
+
+# Option B: targeted destroy (preferred for partial teardown)
+# 1. Destroy compute/K8s cluster first
+terraform destroy -target=module.k8s_cluster -var-file=terraform.tfvars -auto-approve
+# 2. Then networking
+terraform destroy -target=module.vpc -var-file=terraform.tfvars -auto-approve
+# 3. Finally storage (confirm buckets are empty first)
+terraform destroy -target=module.object_storage -var-file=terraform.tfvars -auto-approve
+```
+- Watch for destroy errors; some resources require manual intervention (e.g., non-empty S3 buckets)
+
+### 5. Verify & Cleanup — `@devops-engineer`
+```bash
+# Confirm no resources remain
+terraform state list   # should be empty
+
+# Remove backend state file (only after confirming destroy is complete)
+# AWS S3:
+aws s3 rm s3://mycompany-terraform-state/${ENV}/ --recursive
+# GCS:
+gsutil -m rm -r gs://mycompany-terraform-state/${ENV}/
+
+# Remove DynamoDB lock entries
+aws dynamodb delete-item \
+  --table-name terraform-state-lock \
+  --key '{"LockID": {"S": "mycompany-terraform-state/${ENV}/terraform.tfstate"}}'
+```
+- **Done when:** state list empty; DNS entries removed; cloud console confirms no resources
+
+### 6. Document — `@devops-engineer`
+- Record in decommission log: environment, date, approver, reason, data disposition
+
+## Exit
+Terraform state empty + cloud console clean + documentation filed = environment destroyed.

package/areas/devops/infrastructure/workflows/drift-remediation.md

@@ -0,0 +1,66 @@
+---
+name: drift-remediation
+type: workflow
+trigger: /drift-remediation
+description: Detect, classify, and remediate infrastructure drift between Terraform state and actual cloud state.
+inputs:
+  - environment
+  - component (optional — specific module to check)
+outputs:
+  - drift_report
+  - remediation_applied or deferred
+roles:
+  - devops-engineer
+  - team-lead
+execution:
+  initiator: developer
+related-rules:
+  - immutability.md
+  - iac-standards.md
+uses-skills:
+  - drift-detection
+  - terraform-modules
+quality-gates:
+  - drift classified before any apply
+  - INVESTIGATE drift treated as security incident
+---
+
+## Steps
+
+### 1. Detect Drift — `@devops-engineer`
+```bash
+# Run plan across all components; capture exit code
+# Exit 0 = no changes, Exit 2 = changes detected
+terraform plan -var-file=terraform.tfvars -detailed-exitcode 2>&1 | tee drift-report.txt
+echo "Exit code: $?"
+```
+
+### 2. Classify Findings — `@devops-engineer` + `@team-lead`
+
+| Class | Criteria | Action |
+|:---|:---|:---|
+| `ACCEPT` | Documented exception in PR comment | Suppress; add to ignore list |
+| `REMEDIATE` | Unintended config change | Terraform apply within 48h |
+| `INVESTIGATE` | Unknown origin; IAM/SG/encryption changes | Treat as P1; audit access logs |
+
+- Any change to: IAM policies, security groups, encryption settings → **automatic INVESTIGATE**
+
+### 3. Remediate (if REMEDIATE class) — `@devops-engineer`
+```bash
+# Review plan again — confirm only expected changes
+terraform plan -var-file=terraform.tfvars -out=remediation.plan
+# Apply after team-lead approval
+terraform apply remediation.plan
+```
+
+### 4. Investigate (if INVESTIGATE class) — `@devops-engineer` + security
+- Open P1 incident
+- Pull cloud provider audit logs (CloudTrail / GCP Audit Logs) for affected resource
+- Identify who/what made the change and when
+- Remediate AND file security incident report
+
+### 5. Report — `@devops-engineer`
+- Update `drift-log.md` with date, resources affected, classification, action taken
+
+## Exit
+All drift classified + REMEDIATE resolved + INVESTIGATE escalated = drift cycle complete.

package/areas/devops/infrastructure/workflows/module-development.md

@@ -0,0 +1,101 @@
+---
+name: module-development
+type: workflow
+trigger: /module-development
+description: Develop, test, and publish a new reusable Terraform module — design, implementation, examples, tests, and versioned release.
+inputs:
+  - module_name
+  - module_purpose
+  - cloud_targets
+outputs:
+  - published_module
+  - module_documentation
+roles:
+  - devops-engineer
+  - team-lead
+execution:
+  initiator: developer
+related-rules:
+  - iac-standards.md
+  - state-management.md
+uses-skills:
+  - terraform-modules
+  - drift-detection
+quality-gates:
+  - all examples produce clean plan (no-op on re-apply)
+  - terraform validate passes
+  - no provider config inside module
+  - README documents all variables and outputs
+---
+
+## Steps
+
+### 1. Design Interface — `@devops-engineer` + `@team-lead`
+- Define: what problem does this module solve?
+- Map all input variables (required vs optional with defaults)
+- Map all outputs callers will need
+- Decide: cloud-specific or cloud-agnostic? (prefer agnostic with per-cloud examples)
+- **Done when:** interface design reviewed and signed off
+
+### 2. Implement Module — `@devops-engineer`
+```
+modules/<module-name>/
+├── main.tf         ← resource definitions
+├── variables.tf    ← all inputs with descriptions + validation
+├── outputs.tf      ← all outputs with descriptions
+├── versions.tf     ← required_version + required_providers (no provider block)
+└── README.md       ← auto-generated with terraform-docs
+```
+- Add `validation {}` blocks to all critical variables
+- Use `for_each` over `count` for multi-instance resources
+- No hardcoded regions, account IDs, or environment names
+- **Done when:** `terraform validate` passes; `terraform fmt -check` passes
+
+### 3. Write Examples — `@devops-engineer`
+```
+modules/<module-name>/examples/
+├── basic/          ← minimal config, happy path
+│   ├── main.tf
+│   └── README.md
+└── advanced/       ← all options exercised
+    ├── main.tf
+    └── README.md
+```
+- Examples must have complete provider configs
+- Run each example against a test account/project: `terraform init && terraform plan`
+- **Done when:** both examples produce a clean plan
+
+### 4. Test — `@devops-engineer`
+```bash
+# Terratest (Go)
+cd modules/<module-name>/test
+go test -v -timeout 30m
+
+# Or: checkov for static security analysis
+checkov -d modules/<module-name>/ --quiet
+
+# terraform-docs: generate README from code
+terraform-docs markdown table modules/<module-name>/ \
+  > modules/<module-name>/README.md
+```
+
+### 5. Code Review — `@team-lead`
+- Interface is minimal (no unnecessary variables)
+- No provider config in module
+- Examples clean
+- README complete (all variables, outputs, usage examples)
+- **Done when:** PR approved
+
+### 6. Release — `@devops-engineer`
+```bash
+# Semantic version tag
+git tag -a modules/<module-name>/v1.0.0 \
+  -m "Initial release of <module-name> module"
+git push origin modules/<module-name>/v1.0.0
+
+# Update module registry / internal docs
+# Reference in other modules: ?ref=v1.0.0 (never ?ref=main)
+```
+
+## Exit
+Module published + examples tested + documentation complete = module released.

package/areas/devops/infrastructure/workflows/provision-environment.md

@@ -0,0 +1,96 @@
+---
+name: provision-environment
+type: workflow
+trigger: /provision-environment
+description: Provision a complete infrastructure environment using Terraform + Ansible — from VPC to configured K8s-ready nodes.
+inputs:
+  - environment_name (staging|production)
+  - cloud_provider (aws|gcp|hetzner|bare-metal)
+  - component_scope (network|compute|all)
+outputs:
+  - provisioned_environment
+  - provision_report
+roles:
+  - devops-engineer
+  - team-lead
+execution:
+  initiator: developer
+related-rules:
+  - iac-standards.md
+  - state-management.md
+  - secret-hygiene.md
+  - immutability.md
+uses-skills:
+  - terraform-modules
+  - ansible-playbooks
+quality-gates:
+  - terraform plan reviewed and approved before apply
+  - no secrets in plan output
+  - smoke test passes post-provision
+---
+
+## Steps
+
+### 1. Plan & Review — `@devops-engineer` + `@team-lead`
+- **Actions:**
+  ```bash
+  cd terraform/environments/${ENV}
+  terraform init -backend-config=backend.hcl
+  terraform validate
+  terraform fmt -check -recursive
+
+  # Generate plan
+  terraform plan \
+    -var-file=terraform.tfvars \
+    -out=tfplan.binary \
+    2>&1 | tee tfplan.txt
+  ```
+- Review plan output for: unexpected destroys, missing tags, security group wildcards, unencrypted storage
+- **Done when:** `@team-lead` approves plan; no unexpected destroys
+
+### 2. Apply Infrastructure — `@devops-engineer`
+- **Actions:**
+  ```bash
+  terraform apply tfplan.binary
+  # Save outputs for Ansible
+  terraform output -json > environments/${ENV}/tf-outputs.json
+  ```
+- **Done when:** apply exits 0; all resources in state
+
+### 3. Configure Nodes (Ansible) — `@devops-engineer`
+- **Actions:**
+  ```bash
+  # Generate dynamic inventory from Terraform outputs
+  python3 scripts/tf-to-inventory.py tf-outputs.json > inventory/${ENV}/hosts.ini
+
+  # Dry run first
+  ansible-playbook -i inventory/${ENV}/hosts.ini \
+    playbooks/site.yml --check --diff \
+    --vault-password-file ~/.vault-pass
+
+  # Apply configuration
+  ansible-playbook -i inventory/${ENV}/hosts.ini \
+    playbooks/site.yml \
+    --vault-password-file ~/.vault-pass
+  ```
+- **Done when:** all plays complete with 0 failures
+
+### 4. Smoke Tests — `@devops-engineer`
+- **Actions:**
+  - For cloud environments: verify VPC, subnets, security groups via AWS/GCP CLI
+  - For K8s-destined nodes: run `kubeadm init phase preflight` (pre-check only)
+  - Connectivity: SSH to each node, verify ports
+  ```bash
+  ansible -i inventory/${ENV}/hosts.ini all -m ping
+  ansible -i inventory/${ENV}/hosts.ini k8s_cluster -m command -a "systemctl is-active containerd"
+  ```
+- **Done when:** all nodes reachable; containerd/kubelet running
+
+### 5. Document & Store Outputs — `@devops-engineer`
+- Commit any generated inventory/config to Git
+- Store node IPs in SSM / Consul KV for downstream use
+- Write `provision_report.md`: environment, resources created, cost estimate, next steps
+- **Done when:** report committed; outputs stored
+
+## Exit
+Terraform apply clean + Ansible 0 failures + smoke tests pass = environment provisioned.