@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-ops/config/surface-routing.json

@@ -0,0 +1,417 @@
+{
+  "version": "1.0",
+  "reconnaissance_agent": "developer",
+  "surfaces": {
+    "live_runtime": {
+      "intent": "The user needs to inspect, diagnose, or validate the actual state of running systems — pods, services, logs, cloud resources, network connectivity, SSH access, or compare what IS running against what SHOULD be running.",
+      "primary_agent": "cloud-troubleshooter",
+      "adjacent_surfaces": [
+        "gitops_desired_state",
+        "terraform_iac"
+      ],
+      "contract_sections": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "infrastructure",
+        "orchestration",
+        "cluster_details",
+        "monitoring_observability",
+        "application_services",
+        "infrastructure_topology",
+        "architecture_overview"
+      ],
+      "required_checks": [
+        "Prefer read-only live validation when runtime state is the question",
+        "Capture the exact diagnostic command and the key output that changed your conclusion",
+        "Compare actual state against desired state when manifests or IaC are implicated"
+      ],
+      "signals": {
+        "keywords": [
+          "live cluster",
+          "runtime drift",
+          "pod",
+          "pods",
+          "logs",
+          "incident",
+          "crashloopbackoff",
+          "imagepullbackoff",
+          "service unavailable",
+          "latency",
+          "outage",
+          "runtime",
+          "remote",
+          "transfer",
+          "copy to",
+          "copy from",
+          "WSL",
+          "Windows",
+          "Metra Tower"
+        ],
+        "commands": [
+          "kubectl",
+          "gcloud",
+          "aws",
+          "eksctl",
+          "gsutil",
+          "ssh",
+          "scp",
+          "rsync",
+          "sftp",
+          "tailscale"
+        ],
+        "artifacts": [
+          "pod",
+          "service",
+          "ingress",
+          "node pool",
+          "cluster"
+        ]
+      }
+    },
+    "gitops_desired_state": {
+      "intent": "The user needs to create, modify, or review the desired state of Kubernetes workloads — Flux HelmReleases, Kustomizations, manifests, Helm values, or any declarative config that defines what SHOULD run in the cluster.",
+      "primary_agent": "gitops-operator",
+      "adjacent_surfaces": [
+        "live_runtime",
+        "terraform_iac",
+        "app_ci_tooling"
+      ],
+      "contract_sections": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "infrastructure",
+        "orchestration",
+        "gitops_configuration",
+        "cluster_details",
+        "application_services",
+        "operational_guidelines",
+        "architecture_overview"
+      ],
+      "required_checks": [
+        "Search existing manifests and neighboring GitOps resources before proposing changes",
+        "Check desired state against runtime symptoms when the task smells like drift",
+        "Surface any deployment/runtime contract that another surface must validate"
+      ],
+      "signals": {
+        "keywords": [
+          "gitops",
+          "flux",
+          "helm",
+          "kustomize",
+          "manifest",
+          "deployment",
+          "state in git",
+          "desired state",
+          "helmrelease",
+          "kustomization",
+          "rollout",
+          "configmap",
+          "ingress"
+        ],
+        "commands": [
+          "helm",
+          "flux",
+          "kustomize",
+          "kubectl diff",
+          "kubectl apply --dry-run"
+        ],
+        "artifacts": [
+          "yaml",
+          "manifest",
+          "helmrelease",
+          "kustomization",
+          "deployment",
+          "service",
+          "ingress"
+        ]
+      }
+    },
+    "terraform_iac": {
+      "intent": "The user needs to create, modify, review, or validate Infrastructure as Code — Terraform modules, Terragrunt configs, cloud resource definitions (IAM, VPC, buckets), state files, or plan/apply workflows.",
+      "primary_agent": "terraform-architect",
+      "adjacent_surfaces": [
+        "gitops_desired_state",
+        "app_ci_tooling",
+        "live_runtime"
+      ],
+      "contract_sections": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "infrastructure",
+        "orchestration",
+        "terraform_infrastructure",
+        "infrastructure_topology",
+        "cluster_details",
+        "application_services",
+        "architecture_overview"
+      ],
+      "required_checks": [
+        "Compare against 2-3 sibling modules or stacks before introducing new structure",
+        "Call out blast radius when the change touches shared modules, IAM, or stateful resources",
+        "State clearly which live/runtime or GitOps surfaces must cross-check the result"
+      ],
+      "signals": {
+        "keywords": [
+          "terraform",
+          "terragrunt",
+          "iac",
+          "iam",
+          "bucket",
+          "state",
+          "module",
+          "service account",
+          "workload identity",
+          "secret manager",
+          "vpc",
+          "subnet",
+          "policy"
+        ],
+        "commands": [
+          "terraform",
+          "terragrunt",
+          "tflint"
+        ],
+        "artifacts": [
+          ".tf",
+          ".hcl",
+          "module",
+          "terragrunt.hcl",
+          "provider",
+          "backend"
+        ]
+      }
+    },
+    "app_ci_tooling": {
+      "intent": "The user needs to write, modify, test, or build application code — Node.js/TypeScript or Python, Docker images, CI/CD pipelines, package management, testing frameworks, linting, or developer tooling.",
+      "primary_agent": "developer",
+      "adjacent_surfaces": [
+        "terraform_iac",
+        "gitops_desired_state"
+      ],
+      "contract_sections": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "infrastructure",
+        "application_services",
+        "operational_guidelines",
+        "architecture_overview"
+      ],
+      "required_checks": [
+        "Search for existing application, CI, and developer workflow patterns before changing build or runtime behavior",
+        "Surface deployment, runtime, or infrastructure implications instead of treating the task as app-only by default",
+        "Include exact build, test, or verification commands whenever they informed the conclusion"
+      ],
+      "signals": {
+        "keywords": [
+          "ci",
+          "cd",
+          "pipeline",
+          "docker",
+          "dockerfile",
+          "build",
+          "test",
+          "lint",
+          "package",
+          "npm",
+          "pnpm",
+          "yarn",
+          "turbo",
+          "turborepo",
+          "remote cache",
+          "application code",
+          "env var",
+          "environment variable"
+        ],
+        "commands": [
+          "npm",
+          "pnpm",
+          "yarn",
+          "node",
+          "pytest",
+          "jest",
+          "eslint",
+          "prettier",
+          "turbo",
+          "docker"
+        ],
+        "artifacts": [
+          "package.json",
+          "Dockerfile",
+          "workflow",
+          "pipeline",
+          "tests",
+          "src/"
+        ]
+      }
+    },
+    "planning_specs": {
+      "intent": "The user needs to create a brief/spec, plan a feature, execute a plan, check plan status, or break down requirements into tasks.",
+      "primary_agent": "gaia-planner",
+      "adjacent_surfaces": [
+        "app_ci_tooling",
+        "gaia_system"
+      ],
+      "contract_sections": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "infrastructure",
+        "operational_guidelines",
+        "application_services",
+        "architecture_overview"
+      ],
+      "required_checks": [
+        "Keep planning artifacts aligned with governance and project context",
+        "Tag adjacent surfaces explicitly when the plan crosses infra, runtime, or app boundaries",
+        "Do not silently choose an implementation path when multiple valid options remain"
+      ],
+      "skills": ["brief-spec"],
+      "signals": {
+        "keywords": [
+          "brief",
+          "spec",
+          "plan",
+          "execute plan",
+          "plan status",
+          "acceptance criteria",
+          "specification",
+          "implementation plan",
+          "feature planning",
+          "feature spec",
+          "create a plan",
+          "run the plan"
+        ],
+        "commands": [],
+        "artifacts": [
+          "brief.md",
+          "spec.md",
+          "plan.md"
+        ]
+      }
+    },
+    "gaia_system": {
+      "intent": "The user needs to modify or analyze the Gaia orchestration system itself — hooks, skills, agent definitions, surface routing, security tiers, approval pipelines, contract formats, or system architecture.",
+      "primary_agent": "gaia-system",
+      "adjacent_surfaces": [
+        "app_ci_tooling"
+      ],
+      "contract_sections": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "infrastructure",
+        "orchestration",
+        "operational_guidelines",
+        "architecture_overview"
+      ],
+      "required_checks": [
+        "Keep hooks, skills, templates, and tests aligned as one system",
+        "Check for duplicated contract text or diverging runtime/prompt behavior",
+        "Call out any cross-agent or cross-hook impact explicitly"
+      ],
+      "signals": {
+        "keywords": [
+          "hook",
+          "hooks",
+          "skill",
+          "skills",
+          "agent",
+          "agents",
+          "claude.md",
+          "project context",
+          "orchestrator",
+          "context provider",
+          "response contract",
+          "pre_tool_use",
+          "subagent_stop",
+          "gaia",
+          "scanner",
+          "contract",
+          "project-context",
+          "project-context.json",
+          "dispatch",
+          "routing",
+          "identity",
+          "meta-agent"
+        ],
+        "commands": [],
+        "artifacts": [
+          "hooks/",
+          "skills/",
+          "agents/",
+          "templates/",
+          "claude.md",
+          "project-context.json"
+        ]
+      }
+    },
+    "workspace": {
+      "intent": "The user needs personal workspace operations — memory management, scheduled tasks, loops, email, cross-machine file transfers, or general automation that no specialist domain covers.",
+      "primary_agent": "gaia-operator",
+      "adjacent_surfaces": [
+        "live_runtime",
+        "app_ci_tooling",
+        "gaia_system"
+      ],
+      "contract_sections": [
+        "project_identity",
+        "stack",
+        "git",
+        "environment",
+        "workspace_repos"
+      ],
+      "required_checks": [
+        "Verify task doesn't belong to a specialist domain before proceeding",
+        "Check memory index before creating duplicate entries"
+      ],
+      "signals": {
+        "keywords": [
+          "save this",
+          "remember this",
+          "note this",
+          "save to memory",
+          "add to memory",
+          "update memory",
+          "gaia memory",
+          "memory search",
+          "memory stats",
+          "memory conflicts",
+          "search my memory",
+          "qué recuerdas de",
+          "busca en memoria",
+          "recuerdos",
+          "sesiones pasadas",
+          "memoria episódica",
+          "schedule",
+          "loop",
+          "cron",
+          "email",
+          "gmail",
+          "inbox",
+          "file transfer",
+          "organize",
+          "automate",
+          "workspace",
+          "personal",
+          "general task"
+        ],
+        "commands": [
+          "cron"
+        ],
+        "artifacts": [
+          "crontab"
+        ]
+      }
+    }
+  }
+}

package/dist/gaia-ops/config/universal-rules.json

@@ -0,0 +1,102 @@
+{
+  "rules": {
+    "universal": [
+      {
+        "rule": "Your prompt includes a Project Context section with confirmed project knowledge. Extract relevant data from it BEFORE executing commands."
+      },
+      {
+        "rule": "context_map: The Project Context section is organized into named sections (e.g. project_identity, stack, git, infrastructure). Each section contains data scanned from the project. Reading the wrong section wastes tokens and produces stale assumptions; reading none at all causes commands built on defaults to fail in ways that are hard to trace back to the root cause."
+      }
+    ],
+    "agent_specific": {
+      "cloud-troubleshooter": {
+        "rules": [
+          {
+            "rule": "monitoring_observability and cluster_details are the primary diagnostic surfaces. A diagnosis that skips these sections will miss the live state of the cluster and produce recommendations that contradict what is already deployed."
+          },
+          {
+            "rule": "infrastructure_topology describes how services are connected across regions and availability zones. Ignoring it when investigating connectivity or latency issues leads to remediation steps that address symptoms rather than the structural cause."
+          },
+          {
+            "rule": "operational_guidelines encodes team conventions for runbooks, escalation paths, and SLOs. Bypassing it risks proposing changes that violate on-call agreements or SLA boundaries."
+          }
+        ]
+      },
+      "gitops-operator": {
+        "rules": [
+          {
+            "rule": "gitops_configuration holds the source-of-truth for Flux/ArgoCD sync targets, kustomize overlays, and reconciliation intervals. Writing manifests without reading this section produces changes that the GitOps controller will override or reject on the next sync cycle."
+          },
+          {
+            "rule": "cluster_details defines the Kubernetes version, node pools, and namespacing conventions. A manifest targeting the wrong API version or namespace will apply cleanly and then fail at runtime, making the error hard to attribute."
+          },
+          {
+            "rule": "operational_guidelines specifies change-window and approval policies. Bypassing it risks triggering a sync during a protected window and causing a production incident."
+          }
+        ]
+      },
+      "terraform-architect": {
+        "rules": [
+          {
+            "rule": "terraform_infrastructure contains existing module versions, backend configuration, and remote state references. Planning without this data generates a diff that replaces instead of updates, and can destroy live resources that were not in scope."
+          },
+          {
+            "rule": "infrastructure_topology maps provider accounts, VPCs, and cross-account trust relationships. Missing this context leads to resource definitions that introduce duplicate CIDR blocks or broken IAM trust chains."
+          },
+          {
+            "rule": "operational_guidelines captures cost-center tagging requirements and provider version constraints. Ignoring them produces plans that pass validation but are rejected at code review or fail cost attribution."
+          }
+        ]
+      },
+      "developer": {
+        "rules": [
+          {
+            "rule": "stack defines the languages, frameworks, and build tools in use. Writing code against a different stack version or framework than what is declared here produces changes that pass local tests and break in CI."
+          },
+          {
+            "rule": "application_services describes service boundaries, ports, and inter-service contracts. Changing a service's interface without consulting this section breaks consumers that are not under active development and not visible in the immediate file context."
+          },
+          {
+            "rule": "operational_guidelines specifies coding standards, test coverage thresholds, and linting rules. Code that meets the functional requirement but ignores these standards will be rejected at the review gate, requiring a rework cycle."
+          }
+        ]
+      },
+      "gaia-planner": {
+        "rules": [
+          {
+            "rule": "architecture_overview describes the current system design and known constraints. A plan that ignores these constraints will produce tasks that are technically coherent but architecturally incompatible with the existing system, requiring replanning after the first implementation attempt."
+          },
+          {
+            "rule": "application_services lists live services and their owners. Omitting this context leads to plans that assume capabilities are missing when they already exist, or that schedule work in the wrong order relative to service dependencies."
+          },
+          {
+            "rule": "operational_guidelines records process constraints such as deployment windows and team capacity limits. A plan that ignores them will hit blockers during execution that were predictable at planning time."
+          }
+        ]
+      },
+      "gaia-operator": {
+        "rules": [
+          {
+            "rule": "workspace_repos is this agent's primary surface: it lists every repository in the workspace with its path, platform, and role. Operating on a repo that is absent from this list risks working in the wrong directory or missing the canonical remote URL, causing pushes to fail or go to the wrong origin."
+          },
+          {
+            "rule": "git describes the platform, default branch, and branching strategy. Ignoring it produces branch names or merge strategies that conflict with the project's CI configuration and require manual cleanup."
+          }
+        ]
+      },
+      "gaia-system": {
+        "rules": [
+          {
+            "rule": "architecture_overview is the write target for system-level changes: updates made without first reading the current state overwrite accurate data with stale assumptions, corrupting the context that all other agents depend on."
+          },
+          {
+            "rule": "operational_guidelines captures team-agreed constraints on the Gaia system itself. Proposing architectural changes that contradict these guidelines produces recommendations that will be rejected and mislead agents that read the context between now and the rejection."
+          },
+          {
+            "rule": "infrastructure provides the deployment environment for Gaia components. Missing this section leads to skill or hook designs that assume capabilities (e.g. network access, file system layout) that do not exist in the actual runtime environment."
+          }
+        ]
+      }
+    }
+  }
+}

package/dist/gaia-ops/hooks/adapters/__init__.py

@@ -0,0 +1,52 @@
+"""
+Adapter Layer for Gaia-Ops Hooks.
+
+Provides CLI-agnostic normalized types and the abstract HookAdapter interface.
+Business logic modules consume and produce these types; concrete adapters
+translate between these types and CLI-specific JSON protocols.
+
+Modules:
+- types: Frozen dataclasses and enums for all hook event/response data
+- base: Abstract HookAdapter interface
+"""
+
+from .types import (
+    HookEventType,
+    PermissionDecision,
+    DistributionChannel,
+    HookEvent,
+    ValidationRequest,
+    ValidationResult,
+    ToolResult,
+    AgentCompletion,
+    CompletionResult,
+    ContextResult,
+    BootstrapResult,
+    QualityResult,
+    VerificationResult,
+    HookResponse,
+)
+from .base import HookAdapter
+from .claude_code import ClaudeCodeAdapter
+from .utils import has_stdin_data, warn_if_dual_channel
+
+__all__ = [
+    "HookEventType",
+    "PermissionDecision",
+    "DistributionChannel",
+    "HookEvent",
+    "ValidationRequest",
+    "ValidationResult",
+    "ToolResult",
+    "AgentCompletion",
+    "CompletionResult",
+    "ContextResult",
+    "BootstrapResult",
+    "QualityResult",
+    "VerificationResult",
+    "HookResponse",
+    "HookAdapter",
+    "ClaudeCodeAdapter",
+    "has_stdin_data",
+    "warn_if_dual_channel",
+]