@jaguilar87/gaia 5.0.0-rc1

package/commands/README.md

@@ -0,0 +1,64 @@
+# Commands
+
+Slash commands are direct shortcuts into Gaia's orchestration layer. When you type `/gaia` or `/scan-project`, Claude Code detects the slash prefix, finds the matching `.md` file in this directory, and injects its contents as instructions to the currently active orchestrator. There is no subagent spawn — the orchestrator reads the command file and executes inline.
+
+This makes slash commands different from agent dispatch. An agent dispatch creates a new Claude Code subprocess with its own identity, skills, and tool set. A slash command is a context injection into the orchestrator's current session. Think of it as a macro: the `.md` file says "when the user invokes this command, do the following." The orchestrator follows those instructions directly.
+
+The practical implication is that slash commands are best suited for tasks that the orchestrator can complete by delegating to existing agents — not tasks that require a new agent identity. They are entry points, not agents.
+
+## Cuándo se activa
+
+```
+User types /command-name [args]
+        |
+Claude Code detects / prefix
+        |
+Looks up commands/<command-name>.md
+        |
+Injects the file's contents into the orchestrator's active context
+        |
+Orchestrator reads the command instructions and executes them
+  (may dispatch agents, call tools, or respond directly)
+        |
+Result returned to user in the current session
+```
+
+No subagent is spawned. No new identity is loaded. The orchestrator handles execution within its current session using its existing tool set and the instructions from the command file.
+
+## Qué hay aquí
+
+```
+commands/
+├── gaia.md           # /gaia — invoke the Gaia meta-agent (gaia-system) for system work
+└── scan-project.md   # /scan-project — scan codebase, detect stack, update project-context.json
+```
+
+Note: a `/gaia-plan` command is referenced in some older documentation but the file does not exist here. Planning is handled conversationally through the orchestrator and the `gaia-planner` agent — not via a slash command.
+
+## Convenciones
+
+**File format:**
+
+```markdown
+---
+name: command-name
+description: One-line description shown in Claude Code autocomplete
+---
+
+# Command Name
+
+[Instructions the orchestrator follows when this command is invoked]
+```
+
+**Registration:** Each command file must also be listed in `build/gaia-ops.manifest.json` under the `commands` array. A file that exists here but is not in the manifest will not appear in Claude Code's slash command list.
+
+**Scope:** Commands inject instructions into the orchestrator. If the task requires domain work (Terraform, code changes, cloud ops), the command's instructions should dispatch the appropriate agent — the command itself should not attempt domain execution.
+
+**Arguments:** Slash commands can receive arguments after the command name (e.g., `/gaia-plan Add OAuth2 support`). The command's `.md` file can reference these as context, and the orchestrator receives them as part of the injected content.
+
+## Ver también
+
+- [`build/gaia-ops.manifest.json`](../build/gaia-ops.manifest.json) — command registration
+- [`agents/gaia-system.md`](../agents/gaia-system.md) — the Gaia meta-agent invoked by `/gaia`
+- [`agents/gaia-orchestrator.md`](../agents/gaia-orchestrator.md) — orchestrator that executes command instructions
+- [`skills/gaia-planner/SKILL.md`](../skills/gaia-planner/SKILL.md) — planning workflow (used by gaia-planner agent, not a slash command)

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