@jaguilar87/gaia 5.0.0-rc1

package/dist/gaia-ops/agents/gitops-operator.md

@@ -0,0 +1,61 @@
+---
+name: gitops-operator
+description: A specialized agent that manages the Kubernetes application lifecycle via GitOps. It analyzes, proposes, and realizes changes to declarative configurations in the Git repository.
+tools: Read, Edit, Write, Glob, Grep, Bash, Task, Skill
+model: inherit
+maxTurns: 40
+permissionMode: acceptEdits
+disallowedTools: [NotebookEdit]
+skills:
+  - agent-protocol
+  - security-tiers
+  - investigation
+  - command-execution
+  - gitops-patterns
+  - context-updater
+  - fast-queries
+---
+
+## Workflow
+
+1. **Triage first**: When checking reconciliation status or cluster health, run the fast-queries GitOps triage script before manual kubectl commands.
+2. **Deep analysis**: When investigating drift between desired state and live state, follow the investigation phases.
+3. **Update context**: Before completing, if you discovered namespaces, services, or GitOps configurations not in Project Context, emit a CONTEXT_UPDATE block.
+
+## Identity
+
+You are a senior GitOps operator. You manage the entire lifecycle of Kubernetes applications by interacting **only with the declarative configuration in the Git repository**. Flux synchronizes your code to the cluster — you never apply resources directly.
+
+**Your output is always a Realization Package:**
+- YAML manifest(s) to create or modify
+- `kubectl diff --dry-run` output
+- Pattern explanation: which existing manifest you followed and why
+
+## Scope
+
+### CAN DO
+- Analyze existing YAML manifests (HelmRelease, Kustomization, ConfigMap, etc.)
+- Generate new YAML manifests following `gitops-patterns`
+- Run kubectl commands (get, describe, logs, diff, apply --dry-run=server)
+- Run helm commands (template, lint, list, status)
+- Run flux commands (get, reconcile with timeout)
+- Git operations for realization (add, commit, push)
+
+### CANNOT DO → DELEGATE
+
+| Need | Agent |
+|------|-------|
+| Terraform / cloud infrastructure | `terraform-architect` |
+| Query live cloud state (`gcloud`, `aws`) | `cloud-troubleshooter` |
+| Application code (Python, Node.js) | `developer` |
+| gaia-ops modifications | `gaia` |
+
+## Domain Errors
+
+| Error | Action |
+|-------|--------|
+| `flux reconcile` timeout | Check kustomization status, increase timeout |
+| `HelmRelease` failed | `kubectl describe helmrelease <name>`, check values |
+| `ImagePullBackOff` | Verify image tag exists, check registry auth |
+| `CrashLoopBackOff` | `kubectl logs <pod>`, check app config and secrets |
+| Git push rejected | `git pull --rebase`, resolve conflicts |

package/dist/gaia-ops/agents/terraform-architect.md

@@ -0,0 +1,63 @@
+---
+name: terraform-architect
+description: A specialized agent that manages the cloud infrastructure lifecycle via IaC. It analyzes, proposes, and realizes changes to declarative configurations using Terraform and Terragrunt.
+tools: Read, Edit, Write, Glob, Grep, Bash, Task, Skill, WebFetch
+model: inherit
+maxTurns: 40
+permissionMode: acceptEdits
+disallowedTools: [NotebookEdit]
+skills:
+  - agent-protocol
+  - security-tiers
+  - investigation
+  - command-execution
+  - terraform-patterns
+  - context-updater
+  - fast-queries
+---
+
+## Workflow
+
+1. **Understand what exists**: Follow the investigation phases — read existing modules, discover naming patterns, find the project's Terraform organization before proposing anything.
+2. **Check current state**: When drift is suspected or runtime data is needed, run the fast-queries Terraform or cloud triage script.
+3. **Propose with evidence**: Build a plan grounded in what you found — which existing module you followed, which patterns you matched, what the plan output shows.
+4. **Present for review**: When `terragrunt apply` or other T3 operations are needed, present a REVIEW plan first. If a hook blocks it, include the `approval_id` from the deny response in your REVIEW approval_request.
+5. **Execute and verify**: After approval (T3) or after investigation confirms patterns (T0-T2), create/modify files and run verification.
+6. **Update context**: Before completing, if you discovered infrastructure topology, service accounts, or network configs not in Project Context, emit a CONTEXT_UPDATE block.
+
+## Identity
+
+You are a senior Terraform architect. You manage the entire lifecycle of cloud infrastructure by working **primarily with the declarative configuration in the Git repository**. You use `terragrunt plan` to compare code against live state, but you never query live cloud resources directly via `gcloud` or `aws` CLI — delegate that to `cloud-troubleshooter`.
+
+**Your output is always a Realization Package:**
+- HCL code to create or modify
+- `terragrunt plan` output
+- Pattern explanation: which existing module you followed and why
+
+## Scope
+
+### CAN DO
+- Analyze existing Terraform/Terragrunt configurations
+- Generate `.tf` / `.hcl` files following `terraform-patterns`
+- Investigate existing configurations before generating anything new
+- Run terraform/terragrunt commands (init, validate, plan, apply — T3 requires approval)
+- Git operations for realization (add, commit, push)
+
+### CANNOT DO → DELEGATE
+
+| Need | Agent |
+|------|-------|
+| Query live cloud state (`gcloud`, `aws`) | `cloud-troubleshooter` |
+| Kubernetes / Flux manifests | `gitops-operator` |
+| Application code (Python, Node.js) | `developer` |
+| gaia-ops modifications | `gaia` |
+
+## Domain Errors
+
+| Error | Action |
+|-------|--------|
+| `terraform init` fails | Check credentials and provider version |
+| Plan shows unexpected **destroys** | HALT — report, require explicit confirmation |
+| Apply timeout | Check cloud quotas, retry |
+| State lock | Report who holds the lock — wait or force-unlock with caution |
+| Drift detected | Report — ask: sync code to live, or apply code to live? |

package/dist/gaia-ops/commands/gaia.md

@@ -0,0 +1,37 @@
+---
+name: gaia
+description: Invoke the Gaia meta-agent for system architecture analysis, agent design, skill creation, and orchestration debugging
+allowed-tools:
+  - Bash(*)
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+  - Task
+  - Agent
+  - Skill
+---
+
+Invoke the Gaia meta-agent (`gaia-system`) to work on the gaia-ops orchestration
+system itself. This is the entry point for tasks that modify or analyze agents,
+skills, hooks, or system architecture.
+
+## When to use
+
+- Analyze or improve the gaia-ops architecture
+- Create or update agent definitions (`.md` files)
+- Create or update skills (`SKILL.md` files)
+- Write or debug Python hooks and tools
+- Update `CLAUDE.md` or system configuration
+- Research best practices for agent orchestration
+
+## How it works
+
+This command delegates to the `gaia-system` agent, which is the meta-agent
+specialized in the orchestration system. It follows the standard agent protocol
+and returns a `json:contract` block with findings and status.
+
+$ARGUMENTS

package/dist/gaia-ops/config/README.md

@@ -0,0 +1,71 @@
+# Config
+
+Configuration lives here, separate from hooks, because these are data files — not code. Hooks are Python scripts that run at runtime; config files are JSON documents that those scripts read to make decisions. Keeping them apart means you can audit and change system behavior (which agents see which context sections, what git commit patterns are allowed, which surfaces route where) without touching executable code. It also makes the config files version-controllable and reviewable on their own terms.
+
+The contracts are the most important piece in this directory. `context-contracts.json` defines, per agent, which sections of `project-context.json` the agent is allowed to read and which it is allowed to write. This is the access control layer for project knowledge — an agent that is not in the contracts file receives no context injection at all. The cloud extension files in `cloud/` extend these contracts for cloud-specific sections without modifying the base file, so adding a new cloud provider is a new file, not an edit to the core.
+
+The other files — routing, git standards, universal rules — are each consumed by a specific module and do exactly what their names say. There is no magic here: the files are loaded, parsed, and applied by the module that reads them.
+
+## Cuándo se activa
+
+This component does not activate as a runtime process. Each file is read on-demand by the module that needs it. The table below shows the read point for each file.
+
+**Cuándo se lee cada archivo:**
+
+| File | Read by | When |
+|------|---------|------|
+| `surface-routing.json` | `hooks/user_prompt_submit.py` | Every prompt — determines routing recommendation injected into orchestrator context |
+| `context-contracts.json` | `tools/context/context_provider.py` | Every agent dispatch — determines which project-context sections to inject |
+| `git_standards.json` | `hooks/modules/validation/commit_validator.py` | Every `git commit` call intercepted by PreToolUse |
+| `universal-rules.json` | `tools/context/context_provider.py` | Every agent dispatch — injected into all agents alongside project context |
+| `cloud/gcp.json` | `tools/context/context_provider.py` | Agent dispatch when `cloud_provider = gcp` in project-context.json |
+| `cloud/aws.json` | `tools/context/context_provider.py` | Agent dispatch when `cloud_provider = aws` in project-context.json |
+
+**Base + cloud merge flow:**
+
+```
+Agent dispatch triggered
+        |
+context_provider.py reads context-contracts.json    <- cloud-agnostic base
+        |
+Detects cloud_provider from project-context.json
+        |
+Reads cloud/{provider}.json                         <- cloud extensions
+        |
+Merges: extends read/write lists per agent (no duplicates)
+        |
+Result: complete contract for this agent on this cloud
+        |
+Agent receives filtered project-context sections
+```
+
+## Qué hay aquí
+
+```
+config/
+├── context-contracts.json   # Per-agent read/write access to project-context sections
+├── surface-routing.json     # Intent classification and agent routing signals
+├── git_standards.json       # Commit type allowlist, footer rules, Conventional Commits config
+├── universal-rules.json     # Behavior rules injected into all agents at dispatch time
+├── cloud/
+│   ├── gcp.json             # GCP-specific context sections (extends base contracts)
+│   └── aws.json             # AWS-specific context sections (extends base contracts)
+└── README.md
+```
+
+## Convenciones
+
+**context-contracts.json schema:** Each entry is keyed by agent name. Each agent has `read` (list of project-context section names the agent receives) and `write` (list of sections the agent can update via CONTEXT_UPDATE). `core_sections` is a top-level list of sections injected into every agent regardless of per-agent config.
+
+**Adding a new cloud:** Create `cloud/azure.json` following the same schema as `cloud/gcp.json`. Define agent-specific sections for that cloud. No code changes needed — `context_provider.py` detects the file automatically by matching `cloud_provider` from project-context.
+
+**surface-routing.json format:** Each surface entry has `intent`, `primary_agent`, `adjacent_surfaces`, and `signals` (with `high` and `medium` confidence keyword lists). High-confidence signals are checked first; medium signals act as tie-breakers.
+
+**universal-rules.json:** Changes here affect every agent in every session. Add only rules that are truly universal — constraints that apply regardless of domain. Domain-specific rules belong in the relevant skill (`security-tiers`, `command-execution`, etc.).
+
+## Ver también
+
+- [`hooks/user_prompt_submit.py`](../hooks/user_prompt_submit.py) — reads `surface-routing.json` on every prompt
+- [`hooks/modules/validation/`](../hooks/modules/validation/) — reads `git_standards.json` on commit validation
+- [`tools/context/`](../tools/context/) — reads contracts and universal-rules at agent dispatch time
+- [`agents/README.md`](../agents/README.md) — agent names that must match context-contracts.json keys

package/dist/gaia-ops/config/cloud/aws.json

@@ -0,0 +1,134 @@
+{
+  "version": "2.0",
+  "provider": "aws",
+  "description": "AWS-specific context extensions. Merged on top of context-contracts.json at runtime by context_provider.py.",
+  "agents": {
+    "cloud-troubleshooter": {
+      "read": [
+        "vpc_mapping",
+        "load_balancers",
+        "api_gateway",
+        "irsa_bindings",
+        "aws_accounts"
+      ],
+      "write": [
+        "vpc_mapping",
+        "load_balancers",
+        "irsa_bindings"
+      ]
+    },
+    "terraform-architect": {
+      "read": [
+        "vpc_mapping",
+        "load_balancers",
+        "api_gateway",
+        "irsa_bindings",
+        "aws_accounts"
+      ],
+      "write": [
+        "vpc_mapping",
+        "load_balancers",
+        "api_gateway",
+        "irsa_bindings"
+      ]
+    },
+    "gitops-operator": {
+      "read": [
+        "irsa_bindings"
+      ],
+      "write": []
+    },
+    "developer": {
+      "read": [
+        "aws_accounts",
+        "load_balancers"
+      ],
+      "write": []
+    }
+  },
+  "section_schemas": {
+    "aws_accounts": {
+      "_description": "AWS account IDs by environment. AWS projects often use multiple accounts (prod, dev, shared services).",
+      "production": {
+        "account_id": "",
+        "account_alias": "",
+        "region": "us-east-1"
+      },
+      "development": {
+        "account_id": "",
+        "account_alias": "",
+        "region": "us-east-1"
+      },
+      "shared": {
+        "account_id": "",
+        "account_alias": "",
+        "purpose": "Shared services (ECR, shared EKS, tooling)"
+      }
+    },
+    "vpc_mapping": {
+      "_description": "AWS VPC topology per environment, including subnets and AZ mapping",
+      "vpcs": [
+        {
+          "vpc_id": "",
+          "name": "",
+          "environment": "production",
+          "region": "us-east-1",
+          "cidr": "10.0.0.0/16",
+          "subnets": {
+            "private": [],
+            "public": []
+          },
+          "availability_zones": [],
+          "clusters": [],
+          "status": "ACTIVE"
+        }
+      ]
+    },
+    "load_balancers": {
+      "_description": "AWS NLB and ALB resources by service and cluster",
+      "_example": {
+        "my-service-nlb-prod": {
+          "name": "my-service-nlb-prod",
+          "type": "network",
+          "scheme": "internal",
+          "dns": "xxxx.elb.us-east-1.amazonaws.com",
+          "service": "my-service",
+          "namespace": "my-namespace",
+          "cluster": "my-eks-cluster",
+          "purpose": ""
+        }
+      }
+    },
+    "api_gateway": {
+      "_description": "AWS API Gateway V2 (HTTP/WebSocket) configurations and VPC Links",
+      "vpc_links": {
+        "_example_key": {
+          "id": "",
+          "status": "ACTIVE",
+          "target_nlb": "",
+          "target_nlb_dns": "",
+          "backend_service": "",
+          "namespace": "",
+          "cluster": "",
+          "host": "",
+          "purpose": ""
+        }
+      },
+      "apis": []
+    },
+    "irsa_bindings": {
+      "_description": "IAM Roles for Service Accounts (OIDC-based). AWS equivalent of GCP Workload Identity.",
+      "_example": {
+        "my-service-sa": {
+          "kubernetes_sa": "my-service-sa",
+          "namespace": "my-namespace",
+          "iam_role_arn": "arn:aws:iam::123456789012:role/my-service-role",
+          "iam_policies": [
+            "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
+          ],
+          "purpose": "Describe what this service account does"
+        }
+      }
+    }
+  }
+}

package/dist/gaia-ops/config/cloud/gcp.json

@@ -0,0 +1,139 @@
+{
+  "version": "2.0",
+  "provider": "gcp",
+  "description": "GCP-specific context extensions. Merged on top of context-contracts.json at runtime by context_provider.py.",
+  "agents": {
+    "cloud-troubleshooter": {
+      "read": [
+        "gcp_services",
+        "workload_identity",
+        "static_ips"
+      ],
+      "write": [
+        "gcp_services",
+        "workload_identity",
+        "static_ips"
+      ]
+    },
+    "terraform-architect": {
+      "read": [
+        "gcp_services",
+        "workload_identity",
+        "static_ips"
+      ],
+      "write": [
+        "gcp_services",
+        "workload_identity",
+        "static_ips"
+      ]
+    },
+    "gitops-operator": {
+      "read": [
+        "workload_identity",
+        "gcp_services"
+      ],
+      "write": []
+    },
+    "developer": {
+      "read": [
+        "gcp_services"
+      ],
+      "write": []
+    }
+  },
+  "section_schemas": {
+    "gcp_services": {
+      "_description": "GCP-managed services used by the project (Artifact Registry, Cloud SQL, Memorystore, etc.)",
+      "artifact_registry": {
+        "repositories": [
+          {
+            "name": "",
+            "location": "",
+            "format": "DOCKER",
+            "project": "",
+            "url": ""
+          }
+        ]
+      },
+      "cloud_sql": {
+        "instances": [
+          {
+            "name": "",
+            "version": "POSTGRES_15",
+            "tier": "db-f1-micro",
+            "region": "",
+            "database_flags": {},
+            "status": ""
+          }
+        ]
+      },
+      "memorystore": {
+        "instances": [
+          {
+            "name": "",
+            "tier": "BASIC",
+            "memory_size_gb": 1,
+            "region": "",
+            "status": ""
+          }
+        ]
+      },
+      "cloud_storage": {
+        "buckets": [
+          {
+            "name": "",
+            "location": "",
+            "storage_class": "STANDARD",
+            "purpose": ""
+          }
+        ]
+      },
+      "secret_manager": {
+        "enabled": true,
+        "secrets": []
+      },
+      "pubsub": {
+        "topics": [],
+        "subscriptions": []
+      },
+      "cloud_nat": {
+        "name": "",
+        "router": "",
+        "region": "",
+        "status": ""
+      }
+    },
+    "workload_identity": {
+      "_description": "GCP Workload Identity bindings: Kubernetes ServiceAccount -> GCP ServiceAccount with IAM roles",
+      "_example": {
+        "my-service-sa": {
+          "kubernetes_sa": "my-service-sa",
+          "namespace": "my-namespace",
+          "gcp_sa": "my-service-sa@project-id.iam.gserviceaccount.com",
+          "iam_roles": [
+            "roles/cloudsql.client",
+            "roles/secretmanager.secretAccessor",
+            "roles/artifactregistry.reader"
+          ],
+          "purpose": "Describe what this service account does"
+        }
+      }
+    },
+    "static_ips": {
+      "_description": "GCP global and regional static IP addresses used for Ingress and services",
+      "_example": {
+        "my-service-ip": {
+          "name": "my-service-ip",
+          "address": "34.x.x.x",
+          "type": "global",
+          "purpose": "Ingress for my-service",
+          "dns_records": [
+            "my-service.example.com"
+          ],
+          "ssl_certificates": "Active until YYYY-MM-DD",
+          "status": ""
+        }
+      }
+    }
+  }
+}

package/dist/gaia-ops/config/context-contracts.json

@@ -0,0 +1,158 @@
+{
+  "version": "4.0",
+  "description": "Context contracts v4: universal core sections + agent-specific ops sections + workspace_repos. Core sections are granted to every agent. Cloud-specific extensions live in cloud/{provider}.json.",
+  "core_sections": [
+    "project_identity",
+    "stack",
+    "git",
+    "environment",
+    "application_services",
+    "architecture_overview",
+    "operational_guidelines"
+  ],
+  "section_schemas": {
+    "workspace_repos": {
+      "description": "Array of repositories in a multi-repo workspace",
+      "schema": {
+        "repos": [
+          {
+            "name": "string",
+            "path": "string (relative to workspace root)",
+            "remote_url": "string",
+            "platform": "string (github/gitlab/bitbucket)",
+            "role": "string (gitops/iac/platform/agent/library)",
+            "primary_language": "string"
+          }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "cloud-troubleshooter": {
+      "read": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "application_services",
+        "architecture_overview",
+        "operational_guidelines",
+        "infrastructure",
+        "orchestration",
+        "cluster_details",
+        "infrastructure_topology",
+        "terraform_infrastructure",
+        "gitops_configuration",
+        "monitoring_observability",
+        "workspace_repos"
+      ],
+      "write": [
+        "cluster_details",
+        "infrastructure_topology",
+        "application_services",
+        "monitoring_observability",
+        "architecture_overview"
+      ]
+    },
+    "gitops-operator": {
+      "read": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "application_services",
+        "architecture_overview",
+        "operational_guidelines",
+        "infrastructure",
+        "orchestration",
+        "gitops_configuration",
+        "cluster_details",
+        "workspace_repos"
+      ],
+      "write": [
+        "gitops_configuration",
+        "cluster_details",
+        "application_services"
+      ]
+    },
+    "terraform-architect": {
+      "read": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "application_services",
+        "architecture_overview",
+        "operational_guidelines",
+        "infrastructure",
+        "orchestration",
+        "terraform_infrastructure",
+        "infrastructure_topology",
+        "cluster_details",
+        "workspace_repos"
+      ],
+      "write": [
+        "terraform_infrastructure",
+        "infrastructure_topology"
+      ]
+    },
+    "developer": {
+      "read": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "application_services",
+        "architecture_overview",
+        "operational_guidelines",
+        "infrastructure",
+        "workspace_repos"
+      ],
+      "write": [
+        "application_services",
+        "architecture_overview"
+      ]
+    },
+    "gaia-planner": {
+      "read": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "application_services",
+        "architecture_overview",
+        "operational_guidelines",
+        "infrastructure",
+        "workspace_repos"
+      ],
+      "write": []
+    },
+    "gaia-operator": {
+      "read": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "workspace_repos"
+      ],
+      "write": [
+        "workspace_repos"
+      ]
+    },
+    "gaia-system": {
+      "read": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "application_services",
+        "architecture_overview",
+        "operational_guidelines",
+        "infrastructure"
+      ],
+      "write": [
+        "architecture_overview"
+      ]
+    }
+  }
+}