@jaguilar87/gaia 5.0.0-rc.2

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"
+      ]
+    }
+  }
+}

package/dist/gaia-ops/config/crons-schema.md

@@ -0,0 +1,81 @@
+# Crons Persistence Schema
+
+**Version:** 1  
+**File location:** `.claude/crons.json`  
+**Owner:** Gaia cron persistence system
+
+---
+
+## Schema
+
+```json
+{
+  "crons": [
+    {
+      "name": "check-email",
+      "interval_minutes": 180,
+      "prompt": "Revisa el correo y haz triage según gmail-triage skill",
+      "enabled": true,
+      "created": "2026-04-13T20:00:00Z",
+      "last_run": "2026-04-13T23:00:00Z"
+    }
+  ],
+  "version": 1
+}
+```
+
+## Field Definitions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Unique identifier for the cron. Used as the dedup key during restore. Must be URL-safe (alphanumeric, hyphens). |
+| `interval_minutes` | integer | yes | How often the cron fires, in minutes. Mirrors CronCreate interval. |
+| `prompt` | string | yes | The exact prompt sent to the orchestrator on each tick. |
+| `enabled` | boolean | yes | If false, the cron is skipped during restore. Allows pausing without deletion. |
+| `created` | string (ISO 8601 UTC) | yes | Timestamp when the cron was first created. Set once, never updated. |
+| `last_run` | string (ISO 8601 UTC) or null | yes | Timestamp of the most recent execution. Null if the cron has never run. |
+
+## Top-level Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `crons` | array | The list of persisted cron entries. May be empty. |
+| `version` | integer | Schema version. Currently 1. Increment when field semantics change. |
+
+## Constraints
+
+- `name` must be unique within the `crons` array. Duplicate names are invalid.
+- `interval_minutes` must be a positive integer greater than 0.
+- `last_run` is `null` when the cron has been created but has not yet fired.
+
+## Example: Multiple Crons
+
+```json
+{
+  "crons": [
+    {
+      "name": "check-email",
+      "interval_minutes": 180,
+      "prompt": "Revisa el correo y haz triage según gmail-triage skill",
+      "enabled": true,
+      "created": "2026-04-13T20:00:00Z",
+      "last_run": "2026-04-13T23:00:00Z"
+    },
+    {
+      "name": "drift-monitor",
+      "interval_minutes": 60,
+      "prompt": "Check for infrastructure drift in the current project",
+      "enabled": false,
+      "created": "2026-04-10T10:00:00Z",
+      "last_run": null
+    }
+  ],
+  "version": 1
+}
+```
+
+## File Location
+
+The file lives at `.claude/crons.json`, resolved relative to the active project root (same directory where `.claude/` is found). The path module `find_claude_dir()` from `hooks/modules/core/paths.py` provides the canonical `.claude/` path.
+
+For projects that use `CLAUDE_PLUGIN_DATA`, the file lives under that data directory instead, consistent with how other persisted data (logs, sessions, grants) is stored.

package/dist/gaia-ops/config/git_standards.json

@@ -0,0 +1,72 @@
+{
+  "commit_message": {
+    "format": "conventional_commits",
+    "description": "Commit messages must follow Conventional Commits specification",
+
+    "type_allowed": [
+      "feat",
+      "fix",
+      "refactor",
+      "docs",
+      "test",
+      "chore",
+      "ci",
+      "perf",
+      "style",
+      "build"
+    ],
+
+    "scope_required": false,
+    "scope_examples": ["helmrelease", "terraform", "pg-non-prod", "infrastructure"],
+
+    "subject_max_length": 72,
+    "subject_rules": {
+      "capitalize_first_letter": false,
+      "no_period_at_end": true,
+      "imperative_mood": true,
+      "no_emoji": true
+    },
+
+    "body_max_line_length": 72,
+    "body_required": false,
+
+    "footer_forbidden": [
+      "Generated with Claude Code",
+      "Co-Authored-By: Claude",
+      "🤖 Generated with"
+    ],
+
+    "footer_allowed": [
+      "BREAKING CHANGE:",
+      "Refs:",
+      "Closes:",
+      "Fixes:",
+      "Implements:",
+      "See:"
+    ],
+
+    "examples_valid": [
+      "feat(helmrelease): add Phase 3.3 services",
+      "fix(pg-non-prod): correct API key environment variable mappings",
+      "refactor: simplify context provider logic",
+      "docs: update README with new workflow",
+      "chore(deps): update terraform to v1.6.0"
+    ],
+
+    "examples_invalid": [
+      "Added new feature",
+      "Fixed bugs",
+      "Updates",
+      "feat: add feature\n\n🤖 Generated with Claude Code",
+      "feat: add new feature 🚀",
+      "fix: 🐛 correct bug"
+    ]
+  },
+
+  "enforcement": {
+    "enabled": true,
+    "block_on_failure": true,
+    "log_violations": true,
+    "log_path": ".claude/logs/commit-violations.jsonl"
+  }
+}