@jaguilar87/gaia 5.0.0-rc.2

package/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/commands/scan-project.md

@@ -0,0 +1,67 @@
+---
+name: scan-project
+description: Scan the current project to detect stack, infrastructure, tools, and generate/update project-context.json
+allowed-tools:
+  - Bash(*)
+  - Read
+---
+
+Run the gaia modular project scanner to detect the project stack, infrastructure,
+git setup, CLI tools, orchestration, and runtime environment. The scanner produces
+(or updates) `.claude/project-context/project-context.json` with structured,
+machine-readable context that agents consume.
+
+## What this does
+
+The scanner runs 6 independent modules in parallel:
+- **stack** -- languages, frameworks, package managers
+- **git** -- platform, remotes, branching strategy, monorepo detection
+- **infrastructure** -- cloud providers, IaC, CI/CD, containers
+- **orchestration** -- Kubernetes, GitOps (Flux/Argo), Helm charts
+- **tools** -- installed CLI tools (kubectl, terraform, gcloud, etc.)
+- **environment** -- OS info, language runtimes, .env file patterns
+
+It preserves agent-enriched sections (data added by agents via CONTEXT_UPDATE)
+and merges new scan data with existing context using section-ownership rules.
+
+## How to run
+
+Run the scanner CLI:
+
+```bash
+python3 bin/gaia-scan.py
+```
+
+Optional flags:
+- `--verbose` -- show scanner-by-scanner progress
+- `--scanners stack,git` -- run only specific scanners
+- `--output /path/to/output.json` -- custom output path
+- `--check-staleness` -- skip scan if context is already fresh (<24h old)
+
+$ARGUMENTS
+
+## Expected output
+
+The CLI writes project-context.json and prints a JSON summary to stdout:
+
+```
+{
+  "status": "success",
+  "scanner_version": "0.1.0",
+  "sections_updated": ["project_identity", "stack", "git", ...],
+  "scanners_run": 6,
+  "warnings_count": 0,
+  "duration_ms": 2500.0
+}
+```
+
+A human-readable summary is also printed to stderr showing scanner count,
+section count, warnings, and elapsed time.
+
+## After scanning
+
+Read the generated context to verify:
+
+```bash
+python3 -c "import json; d=json.load(open('.claude/project-context/project-context.json')); print(json.dumps(list(d.get('sections',{}).keys()), indent=2))"
+```

package/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/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/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/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/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.