oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-tf-infra/resources/execution-protocol.md

@@ -0,0 +1,129 @@
+# TF Infra Agent: Execution Protocol
+
+## Preparation
+Use the task's scope, existing project conventions, and acceptance criteria. Follow `../../_shared/core/execution-policy.md` when it has not already been supplied. Read only references needed by the selected operation; consult lessons or recovery guides for an observed issue. Expand planning depth only when the change requires it.
+
+## Step 1: Analyze
+
+1. **Identify Cloud Provider**: Detect from `provider.tf`, backend config, or existing resources
+2. Scan existing Terraform files for naming conventions, module patterns, and state configuration
+3. Identify required services, resource dependencies, and security constraints
+4. Load domain-specific references:
+   - `multi-cloud-examples.md` when creating compute, OIDC, or secret resources
+   - `cost-optimization.md` when sizing or cost review is needed
+   - `policy-testing-examples.md` when setting up policy enforcement or tests
+   - `iso-42001-infra.md` when AI governance, continuity, or architecture documentation is required
+5. List assumptions and unknowns
+
+## Step 2: Plan
+
+1. Define resource naming using project conventions and `locals` block:
+
+   | Resource Type | Pattern | Examples |
+   |--------------|---------|----------|
+   | Compute | `{prefix}-{service}` | `fs-dev-api`, `fs-prod-web` |
+   | Database | `{prefix}-db` | `fs-dev-db`, `fs-prod-postgres` |
+   | Storage | `{prefix}-{purpose}` | `fs-dev-assets`, `fs-dev-tfstate` |
+   | IAM Role/SA | `{prefix}-{role}` | `fs-dev-api-role`, `fs-dev-deployer` |
+   | Network | `{prefix}-{type}` | `fs-dev-vpc`, `fs-dev-subnet` |
+
+2. Plan file structure following project patterns:
+   ```
+   apps/infra/
+   ├── provider.tf          # Provider configuration
+   ├── versions.tf          # Version constraints
+   ├── variables.tf         # Input variables
+   ├── locals.tf            # Local values and naming
+   ├── backend.tf           # State backend
+   ├── compute.tf           # Compute resources
+   ├── database.tf          # Databases
+   ├── storage.tf           # Object storage
+   ├── networking.tf        # VPC, subnets, LB, CDN
+   ├── messaging.tf         # Queues and messaging
+   ├── iam.tf               # IAM roles and policies
+   ├── cicd-auth.tf         # OIDC/workload identity
+   ├── security.tf          # Security groups, WAF, secrets
+   ├── outputs.tf           # Output values
+   └── terraform.tfvars     # Variable values (gitignored)
+   ```
+3. Plan module interfaces following composability principles:
+   ```
+   modules/
+   ├── vpc/                    # Reusable VPC module
+   │   ├── main.tf
+   │   ├── variables.tf
+   │   ├── outputs.tf
+   │   └── README.md
+   ├── database/               # Reusable database module
+   └── compute/                # Reusable compute module
+   ```
+   - Expose required variables only; provide sensible defaults for optional
+   - Export essential outputs only
+   - Document all inputs/outputs in README.md
+   - Version modules using Git tags or Terraform Registry
+4. Choose an environment separation strategy:
+   - Prefer directory-per-environment (`envs/dev`, `envs/prod`) with isolated state backends for team setups
+   - CLI workspaces only for lightweight, same-config variants (shared backend is a blast-radius risk)
+   - Consider Terragrunt when many environments share identical module wiring
+5. Identify security requirements (IAM, encryption, network boundaries)
+6. Estimate cost impact for new resources (run Infracost when available)
+
+## Step 3: Implement
+
+1. Create/modify .tf files in dependency order (provider → backend → networking → compute → outputs)
+2. Use `locals` for environment-specific naming and tags
+3. Apply consistent tags: Environment, Project, Owner, CostCenter
+4. Use `for_each` over `count` for resource collections
+5. Set `depends_on` for explicit resource ordering where needed
+6. Design composable modules with:
+   - Required variables only, sensible defaults for optional
+   - Essential outputs only
+   - Documented inputs/outputs
+7. Run `terraform validate` and `terraform fmt`
+8. Run `terraform plan` and review output
+
+## Infrastructure Testing Levels
+
+| Level | Tool | Purpose |
+|-------|------|---------|
+| Unit | `terraform validate` | Syntax, variable types |
+| Static Analysis | TFLint, Checkov, Trivy (`trivy config`) | Best practices, security |
+| Module Tests | `terraform test` (TF >= 1.6, `.tftest.hcl`) | Module logic via plan/apply assertions |
+| Integration | Terratest | Resource creation verification |
+| Compliance | OPA/Sentinel | Organizational policy enforcement |
+| E2E | Custom scripts | Full workflow validation |
+
+See `policy-testing-examples.md` for native `terraform test`, Terratest, and CI/CD integration examples.
+
+## Step 4: Verify
+
+1. Run `checklist.md` self-verification
+2. Use applicable `../../_shared/core/common-checklist.md` sections for cross-domain checks
+3. Confirm:
+   - `terraform validate` passes
+   - `terraform plan` shows expected changes only
+   - No secrets in .tf files
+   - All resources tagged
+   - IAM follows least privilege
+   - Cost impact acceptable
+4. For AI systems: verify IAM, logging, encryption, monitoring, and retention controls documented
+5. For continuity: verify RTO/RPO, failover, backup, and restore documented
+
+## Output Format
+
+When creating new infrastructure, provide:
+1. Cloud provider identified from context
+2. Complete HCL code blocks for each resource
+3. Required variable definitions with types and descriptions
+4. Outputs for resource IDs and endpoints
+5. Migration notes if importing existing resources
+6. Cost estimation considerations
+7. For AI systems: infrastructure control notes covering access, logging, encryption, monitoring, and retention
+8. For continuity-sensitive systems: RTO/RPO, failover, backup, and restore notes
+9. For architecture documentation requests: stakeholder/concern/view/rationale notes
+
+When reviewing terraform plan, provide:
+1. Summary of changes (add/change/destroy counts)
+2. Risk assessment for destructive changes
+3. Provider-specific considerations
+4. Confirmation checklist before apply

package/skills/oma-tf-infra/resources/iso-42001-infra.md

@@ -0,0 +1,229 @@
+# TF Infra Agent - ISO/IEC 42001 / ISO 22301 / ISO/IEC/IEEE 42010 Guide
+
+Use this file when the task involves AI systems and the user wants infrastructure controls or audit-friendly recommendations aligned with ISO/IEC 42001, continuity and recovery guidance aligned with ISO 22301, or infrastructure architecture documentation guidance aligned with ISO/IEC/IEEE 42010.
+
+## Scope
+
+This guide is for:
+
+- **infrastructure controls** that support AI governance
+- **continuity and recovery controls** for infrastructure resilience
+- **architecture description guidance** for infrastructure decisions
+
+It does **not** replace:
+
+- organizational policy
+- model governance
+- human oversight design
+- AI risk management process ownership
+
+Those belong primarily to PM, QA, backend, or security governance work.
+
+## What TF Infra Agent Should Cover
+
+For AI systems, focus on infrastructure controls such as:
+
+- IAM and least privilege
+- service-to-service identity
+- network segmentation and private connectivity
+- encryption at rest and in transit
+- secrets management
+- centralized logging and audit trails
+- monitoring and alerting
+- backup and retention
+- environment isolation
+- change traceability in CI/CD and Terraform state
+- continuity and failover design
+- architecture views, dependencies, and decision rationale
+
+## Recommended Control Areas
+
+### 1. Access Control
+
+Implement:
+
+- least-privilege IAM roles
+- workload identity / OIDC for CI/CD
+- separation of admin, deployer, runtime, and read-only roles
+- scoped access to model endpoints, vector stores, object stores, and databases
+
+Avoid:
+
+- shared admin roles
+- long-lived keys
+- wildcard permissions to AI-related data or services
+
+### 2. Network Boundaries
+
+Implement:
+
+- private subnets for sensitive workloads
+- VPC/VNet/VCN peering or private service endpoints
+- restricted egress where feasible
+- ingress limited to approved paths such as ALB, API Gateway, or internal load balancers
+
+Use stronger isolation when:
+
+- prompts or training data contain sensitive data
+- model outputs affect business-critical actions
+- cross-region or cross-tenant exposure is a concern
+
+### 3. Encryption and Secrets
+
+Implement:
+
+- provider-managed KMS or customer-managed keys where required
+- encrypted storage for object stores, DBs, queues, and state backends
+- TLS for internal and external traffic where supported
+- secrets in cloud secret managers, not in Terraform variables committed to git
+
+### 4. Logging and Auditability
+
+Implement:
+
+- centralized audit logs for IAM, network, storage, and runtime services
+- immutable or retention-locked log targets where needed
+- request tracing across gateways, application services, and data stores
+- Terraform plan/apply evidence in CI/CD logs
+
+For AI-related systems, especially capture evidence around:
+
+- who changed infrastructure
+- who can access model-serving paths
+- where prompts, embeddings, or outputs are stored
+- whether logging retention matches policy
+
+### 5. Monitoring and Alerting
+
+Implement:
+
+- uptime and health monitoring
+- resource utilization metrics
+- security event alerting
+- data egress anomaly alerting where available
+- alerting for failed backups, replication, or logging pipelines
+
+If the AI system is production-critical, recommend:
+
+- SLO-aligned alerting
+- model endpoint availability monitoring
+- queue/backlog monitoring for ingestion pipelines
+- vector or search cluster health checks if present
+
+### 6. Retention, Backup, and Recovery
+
+Implement:
+
+- backup policies for stateful systems
+- snapshot retention and lifecycle rules
+- archival tiers for logs and historical data
+- restore procedures and periodic recovery validation
+
+For AI systems, think about:
+
+- prompt / output retention requirements
+- embedding index rebuild strategy
+- backup of canonical data stores rather than only derived indexes
+
+### 7. Environment and Tenant Isolation
+
+Implement:
+
+- separate environments by account/project/subscription/compartment when practical
+- isolated state backends per environment
+- tagging/labeling for ownership and cost attribution
+- tenant-aware segmentation when AI data is multi-tenant
+
+## 8. ISO 22301 Continuity View
+
+For infrastructure continuity, recommend improvements around:
+
+- critical service identification
+- RTO / RPO assumptions
+- backup scope and retention
+- restore verification
+- redundancy and failover
+- cross-region or cross-zone strategy
+- dependency mapping
+- manual fallback and degraded-mode assumptions
+
+Examples of infra-focused suggestions:
+
+- multi-AZ or multi-zone deployment for critical paths
+- warm standby or replicated storage for essential services
+- tested snapshot restore workflow
+- documented dependency chain for identity, DNS, storage, and network services
+- alerting for failed replication or backup jobs
+
+## 9. ISO/IEC/IEEE 42010 Architecture View
+
+Use 42010 as an architecture description guide, not as a control checklist.
+
+Capture:
+
+- stakeholders
+- concerns
+- architecture views
+- interfaces and dependencies
+- constraints
+- rationale and tradeoffs
+
+For infrastructure work, useful views include:
+
+- context view
+- deployment / runtime view
+- network boundary view
+- identity and trust view
+- resilience / recovery view
+- observability view
+
+Useful documentation prompts:
+
+- Who needs this architecture description?
+- What concerns are they trying to answer?
+- Which infrastructure elements and interfaces matter?
+- What tradeoffs were chosen and why?
+- What dependencies create operational risk?
+
+## Review Questions
+
+When applying ISO/IEC 42001 / ISO 22301 / ISO/IEC/IEEE 42010 thinking, ask:
+
+- Can access to AI-related data paths be audited?
+- Are model-serving and data-serving paths protected with least privilege?
+- Are logs centralized, retained, and protected against tampering?
+- Are backups, retention, and restore procedures defined?
+- Are continuity objectives such as RTO / RPO explicit?
+- Are failover paths and critical dependencies visible?
+- Is network exposure minimized?
+- Is CI/CD access ephemeral and traceable?
+- Is there clear ownership for each critical resource?
+- Are the stakeholders, concerns, and architecture rationale documented clearly?
+
+## Output Pattern
+
+When relevant, add a short section like:
+
+```md
+## ISO/IEC 42001 / ISO 22301 / 42010 Notes
+- Access control:
+- Network boundary:
+- Encryption:
+- Logging / auditability:
+- Monitoring / alerting:
+- Backup / retention:
+- Continuity / RTO / RPO:
+- Failover / dependency view:
+- Stakeholders / concerns / views:
+- Gaps:
+- Recommended Terraform changes:
+```
+
+## Guardrails
+
+- Do not claim ISO/IEC 42001 compliance from Terraform alone
+- Do not claim ISO 22301 compliance from backup settings alone
+- Do not expand this skill into full AI governance process design
+- Do not turn 42010 into paperwork without architectural value
+- Keep suggestions concrete and infra-implementable
+- If the gap is organizational rather than infrastructural, say so explicitly

package/skills/oma-tf-infra/resources/multi-cloud-examples.md

@@ -0,0 +1,241 @@
+# Multi-Cloud Resource Examples
+
+Detailed HCL examples for AWS, GCP, Azure, and Oracle Cloud.
+
+## AWS Examples
+
+### ECS Fargate Service
+```hcl
+resource "aws_ecs_service" "api" {
+  name            = "${local.prefix}-api"
+  cluster         = aws_ecs_cluster.main.id
+  task_definition = aws_ecs_task_definition.api.arn
+  desired_count   = var.api_min_instances
+  launch_type     = "FARGATE"
+
+  network_configuration {
+    subnets          = aws_subnet.private[*].id
+    security_groups  = [aws_security_group.api.id]
+    assign_public_ip = false
+  }
+
+  load_balancer {
+    target_group_arn = aws_lb_target_group.api.arn
+    container_name   = "api"
+    container_port   = 8000
+  }
+}
+```
+
+### OIDC for GitHub Actions
+```hcl
+# Since 2023-07 AWS validates GitHub's OIDC IdP via its trusted root CA library,
+# so the thumbprint is ignored — but the AWS provider still requires the field.
+# Fetch it dynamically instead of hardcoding a value that goes stale.
+data "tls_certificate" "github" {
+  url = "https://token.actions.githubusercontent.com/.well-known/openid-configuration"
+}
+
+resource "aws_iam_openid_connect_provider" "github" {
+  url             = "https://token.actions.githubusercontent.com"
+  client_id_list  = ["sts.amazonaws.com"]
+  thumbprint_list = [data.tls_certificate.github.certificates[0].sha1_fingerprint]
+}
+
+resource "aws_iam_role" "github_actions" {
+  name = "${local.prefix}-github-actions"
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Principal = { Federated = aws_iam_openid_connect_provider.github.arn }
+      Action = "sts:AssumeRoleWithWebIdentity"
+      Condition = {
+        StringEquals = { "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com" }
+        StringLike = { "token.actions.githubusercontent.com:sub" = "repo:${var.github_repo}:*" }
+      }
+    }]
+  })
+}
+```
+
+### Secrets Manager
+```hcl
+data "aws_secretsmanager_secret_version" "db_password" {
+  secret_id = "${local.prefix}/db-password"
+}
+```
+
+## GCP Examples
+
+### Cloud Run Service
+```hcl
+resource "google_cloud_run_v2_service" "api" {
+  name     = "${local.prefix}-api"
+  location = var.region
+  project  = var.project_id
+
+  template {
+    service_account = google_service_account.api.email
+    
+    scaling {
+      min_instances = var.api_min_instances
+      max_instances = var.api_max_instances
+    }
+
+    containers {
+      image = "${var.region}-docker.pkg.dev/${var.project_id}/${local.prefix}/api:${var.image_tag}"
+      
+      resources {
+        limits = { cpu = "2", memory = "1Gi" }
+        cpu_idle = true
+      }
+
+      ports { container_port = 8000 }
+    }
+
+    vpc_access {
+      connector = google_vpc_access_connector.main.id
+      egress    = "ALL_TRAFFIC"
+    }
+  }
+}
+```
+
+### Workload Identity Federation
+```hcl
+resource "google_iam_workload_identity_pool" "github" {
+  workload_identity_pool_id = "github-pool"
+  display_name              = "GitHub Actions Pool"
+}
+
+resource "google_iam_workload_identity_pool_provider" "github" {
+  workload_identity_pool_id          = google_iam_workload_identity_pool.github.workload_identity_pool_id
+  workload_identity_pool_provider_id = "github-provider"
+  
+  attribute_mapping = {
+    "google.subject"       = "assertion.sub"
+    "attribute.repository" = "assertion.repository"
+  }
+
+  # GitHub has a shared issuer: restrict tokens to your organization/repository.
+  # Prefer immutable numeric owner/repository IDs when configured by the project.
+  attribute_condition = "assertion.repository_owner == '${var.github_org}' && assertion.repository == '${var.github_repo}'"
+  oidc {
+    issuer_uri = "https://token.actions.githubusercontent.com"
+  }
+}
+```
+
+### Secret Manager
+```hcl
+data "google_secret_manager_secret_version" "db_password" {
+  secret  = "db-password"
+  version = "latest"
+}
+```
+
+## Azure Examples
+
+### Container Apps
+```hcl
+resource "azurerm_container_app" "api" {
+  name                         = "${local.prefix}-api"
+  container_app_environment_id = azurerm_container_app_environment.main.id
+  resource_group_name          = azurerm_resource_group.main.name
+  revision_mode                = "Single"
+
+  template {
+    min_replicas = var.api_min_instances
+    max_replicas = var.api_max_instances
+
+    container {
+      name   = "api"
+      image  = "${azurerm_container_registry.main.login_server}/${local.prefix}/api:${var.image_tag}"
+      cpu    = 1.0
+      memory = "2Gi"
+
+      env {
+        name  = "DATABASE_URL"
+        value = "postgresql://..."
+      }
+    }
+  }
+}
+```
+
+### Federated Credentials
+```hcl
+# azuread provider >= 3.0: `application_object_id` was removed; use the
+# application's resource ID via `application_id`.
+resource "azuread_application_federated_identity_credential" "github" {
+  application_id = azuread_application.github.id
+  display_name   = "github-actions"
+  description    = "GitHub Actions OIDC"
+  audiences      = ["api://AzureADTokenExchange"]
+  issuer         = "https://token.actions.githubusercontent.com"
+  subject        = "repo:${var.github_repo}:ref:refs/heads/main"
+}
+```
+
+### Key Vault
+```hcl
+data "azurerm_key_vault_secret" "db_password" {
+  name         = "db-password"
+  key_vault_id = azurerm_key_vault.main.id
+}
+```
+
+## Oracle Cloud Examples
+
+### Container Instances
+```hcl
+resource "oci_container_instances_container_instance" "api" {
+  compartment_id = var.compartment_id
+  display_name   = "${local.prefix}-api"
+  
+  containers {
+    image_url = "${oci_artifacts_container_repository.api.repository_url}:${var.image_tag}"
+    display_name = "api"
+    
+    environment_variables = {
+      "DATABASE_URL" = "postgresql://..."
+    }
+  }
+}
+```
+
+### Vault
+```hcl
+data "oci_secrets_secretbundle" "db_password" {
+  secret_id = oci_vault_secret.db_password.id
+}
+```
+
+## Secrets and Terraform State
+
+The secret data-source reads above keep credentials out of `.tf` files, but the
+fetched values still persist in plaintext in the plan artifact and state file.
+Always treat state as sensitive (encrypted backend, restricted access), and on
+newer Terraform prefer patterns that never touch state:
+
+- **Terraform >= 1.10**: `ephemeral` resources/variables — read secrets without
+  persisting them to plan or state.
+- **Terraform >= 1.11**: write-only arguments (`*_wo` + `*_wo_version`) — pass
+  secrets into managed resources without storing them in state.
+
+```hcl
+# Terraform >= 1.11 example: password never lands in state
+ephemeral "aws_secretsmanager_secret_version" "db_password" {
+  secret_id = "${local.prefix}/db-password"
+}
+
+resource "aws_db_instance" "main" {
+  # ...
+  password_wo         = ephemeral.aws_secretsmanager_secret_version.db_password.secret_string
+  password_wo_version = 1 # bump to rotate
+}
+```
+
+Provider support for write-only arguments varies by resource; fall back to the
+data-source pattern plus state hygiene when unavailable.