@jaguilar87/gaia 5.0.0-rc.2

package/README.md

@@ -0,0 +1,222 @@
+# Gaia
+
+> **G**eneral **A**gentic **I**ntegration **A**rchitecture
+
+[![npm version](https://badge.fury.io/js/@jaguilar87%2Fgaia.svg)](https://www.npmjs.com/package/@jaguilar87/gaia)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@jaguilar87/gaia.svg)](https://nodejs.org)
+
+## Cómo leer este repo
+
+Gaia is event-driven. Every capability in the codebase is attached to a moment in the Claude Code lifecycle — a prompt arriving, a tool being called, an agent completing. Reading the folder structure without that lens makes it look like a collection of files. Reading it with that lens, everything clicks into place.
+
+The flow is this: a user sends a prompt, the `UserPromptSubmit` hook fires and injects the orchestrator's identity and a routing recommendation. The orchestrator picks a specialist agent and dispatches it. Before that agent's first tool call lands, the `PreToolUse` hook intercepts it — injecting context, validating permissions, blocking dangerous commands. The agent does its work and returns a `json:contract`. The `SubagentStop` hook fires, validates the contract, records metrics, and writes to episodic memory.
+
+```
+UserPromptSubmit  ->  routing  ->  PreToolUse  ->  agent  ->  PostToolUse  ->  SubagentStop
+      |                  |               |              |             |               |
+  identity           surface-        security       json:contract  audit log     metrics +
+  injection          routing.json    gate +                                      memory
+                                     context
+                                     injection
+```
+
+That pipeline is the spine. Everything else in this repo is either a component of that pipeline (`hooks/`, `agents/`, `skills/`, `config/`) or infrastructure that supports it (`build/`, `bin/`, `tests/`, `templates/`). Start with the folder that matches the behavior you want to understand, and its README will tell you where it fits in the flow.
+
+## Overview
+
+**Gaia** is a multi-agent orchestration system for DevOps automation. It ships two sub-plugins — `gaia-ops` (full orchestrator) and `gaia-security` (security-only) — with security-first command classification, specialized AI agents, and plugin-based distribution. Currently integrates with Claude Code.
+
+### Features
+
+- **Multi-cloud support** - GCP, AWS, Azure
+- **8 agents** - terraform-architect, gitops-operator, cloud-troubleshooter, developer, gaia-planner, gaia-operator, gaia-orchestrator, gaia-system (meta-agent)
+- **Contracts as SSOT** - Cloud-agnostic base contracts with per-cloud extensions (GCP, AWS)
+- **Dynamic identity** - Orchestrator identity defined in `agents/gaia-orchestrator.md`, activated via `settings.json` agent config; skills loaded on-demand
+- **Dual-barrier security** - Settings deny rules (Claude Code native) + hook-level blocking (inalterable via symlink)
+- **Indirect execution detection** - Catches `bash -c`, `eval`, `python -c` wrappers that bypass regex patterns
+- **Approval gates** for T3 operations via native `ask` dialog
+- **Git commit validation** with Conventional Commits
+- **32 skills** - Injected procedural knowledge modules for agents (protocol, domain, workflow)
+- **Episodic memory** - `gaia memory` CLI with FTS5 search, episode inspection, and session context orientation
+- **Context evals** - pytest-driven agent evaluation (5 graders, 3 backends, 10 scenarios, baseline + drift detection)
+- **Plugin + npm** - Distributable as Claude Code native plugin or npm package
+- **Enterprise ready** - Managed settings template for organization-wide deployment
+
+## Installation
+
+### Via Claude Code Plugin (recommended)
+```bash
+# Add the marketplace
+/plugin marketplace add metraton/gaia
+
+# Install the full system (includes security)
+/plugin install gaia-ops
+
+# Or install security only
+/plugin install gaia-security    # Security hooks only
+```
+
+### Via npm (advanced setup)
+```bash
+npm install @jaguilar87/gaia
+npx gaia-scan
+```
+
+### Quick Start (npm)
+
+```bash
+# Run directly with npx
+npx gaia-scan
+
+# Or install globally
+npm install -g @jaguilar87/gaia
+gaia-scan
+```
+
+This will:
+1. Auto-detect your project structure (GitOps, Terraform, AppServices)
+2. Create `.claude/` directory with symlinks to this package
+3. Generate `project-context.json`
+4. Create `settings.json` with hooks only (no permissions in settings.json)
+5. Merge deny rules + allow permissions into `settings.local.json` (preserves existing user config)
+
+No `CLAUDE.md` is generated -- orchestrator identity lives in `agents/gaia-orchestrator.md` and is activated via `settings.json: { "agent": "gaia-orchestrator" }`.
+
+### Settings Architecture
+
+Gaia separates hooks from permissions:
+
+| File | Content | Strategy |
+|------|---------|----------|
+| `settings.json` | Hooks only (9 hook types) | Overwritten from template on each update |
+| `settings.local.json` | Permissions (allow + deny rules) | Union merge — never removes user config |
+
+This ensures your personal customizations (MCP servers, extra permissions) survive updates.
+
+### Manual Installation
+
+```bash
+npm install @jaguilar87/gaia
+```
+
+Then create symlinks:
+
+```bash
+mkdir -p .claude && cd .claude
+ln -s ../node_modules/@jaguilar87/gaia/agents agents
+ln -s ../node_modules/@jaguilar87/gaia/tools tools
+ln -s ../node_modules/@jaguilar87/gaia/hooks hooks
+ln -s ../node_modules/@jaguilar87/gaia/commands commands
+ln -s ../node_modules/@jaguilar87/gaia/config config
+ln -s ../node_modules/@jaguilar87/gaia/templates templates
+ln -s ../node_modules/@jaguilar87/gaia/skills skills
+```
+
+## Usage
+
+Once installed, the agent system is ready:
+
+```bash
+claude
+```
+
+The orchestrator identity is defined in `agents/gaia-orchestrator.md` and activated via `settings.json` agent config. Skills are loaded on-demand.
+
+Skills and injection diagnosis:
+
+```bash
+npx gaia-skills-diagnose
+# or with test probe:
+npx gaia-skills-diagnose --run-tests
+```
+
+## Security
+
+Gaia enforces a 6-layer security pipeline:
+
+| Layer | Mechanism | Bypassable? |
+|-------|-----------|-------------|
+| Indirect execution detection | `bash -c`, `eval`, `python -c` wrappers | No (hook-level) |
+| Blocked commands (regex) | 85+ regex patterns | No (symlink to npm package) |
+| Blocked commands (semantic) | 70+ ordered-token rules | No (symlink to npm package) |
+| Cloud pipe validator | Credential piping detection | No (hook-level) |
+| Mutative verb detection | `ask` dialog for state-changing ops | User approves via native dialog |
+| Settings deny rules | 147 deny rules in `settings.local.json` | Self-healing (restored each session) |
+
+### Enterprise Deployment
+
+For organization-wide enforcement, deploy `templates/managed-settings.template.json` as a managed settings policy via Claude.ai Admin Console. Managed settings have the highest precedence and cannot be overridden.
+
+## Project Structure
+
+```
+gaia-dev/
+├── agents/              # Agent definitions (8 agents) — specialist identities + tool grants
+├── skills/              # Skill modules (32 skills) — injected procedural knowledge
+├── hooks/               # Claude Code hooks — the event-driven pipeline
+├── config/              # Configuration — routing, contracts, rules, git standards
+├── commands/            # Slash commands — /gaia, /scan-project
+├── build/               # Plugin manifests — hook + agent registration for Claude Code
+├── templates/           # Installation templates — managed-settings for enterprise
+├── bin/                 # CLI utilities (11 scripts) — gaia-doctor, gaia-scan, etc.
+├── tests/               # Test suite — 3-layer pyramid (pytest, LLM eval, e2e)
+└── tools/               # Context provisioning tools
+```
+
+## API
+
+```javascript
+import { getAgentPath, getToolPath, getConfigPath } from '@jaguilar87/gaia';
+
+const agentPath = getAgentPath('gitops-operator');
+const toolPath = getToolPath('context_provider.py');
+```
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR:** Breaking changes
+- **MINOR:** New features
+- **PATCH:** Bug fixes
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+## Documentation
+
+- [INSTALL.md](./INSTALL.md) - Installation guide
+- [agents/](./agents/) - Agent definitions and lifecycle
+- [skills/](./skills/) - Skill modules and assignment matrix
+- [hooks/](./hooks/) - Hook pipeline and security architecture
+- [config/](./config/) - Configuration (contracts, git standards, universal rules)
+- [commands/](./commands/) - Slash commands
+- [build/](./build/) - Plugin manifests
+- [bin/](./bin/) - CLI utilities
+- [tests/](./tests/) - Test suite
+
+## Requirements
+
+- **Node.js:** >=18.0.0
+- **Python:** >=3.9
+- **Claude Code:** Latest version
+- **Git:** >=2.30
+
+## Project Context Management
+
+Gaia uses a versioned project context as SSOT:
+
+```bash
+cd .claude
+git clone git@bitbucket.org:yourorg/your-project-context.git project-context
+```
+
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/metraton/gaia/issues)
+- **Repository:** [github.com/metraton/gaia](https://github.com/metraton/gaia)
+- **Author:** Jorge Aguilar <jorge.aguilar88@gmail.com>
+
+## License
+
+MIT License - See [LICENSE](./LICENSE) for details.

package/SECURITY.md

@@ -0,0 +1,47 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 4.0.x   | Yes       |
+| < 4.0   | No        |
+
+## Reporting a Vulnerability
+
+**Do NOT open a public GitHub issue for security vulnerabilities.**
+
+To report a vulnerability, please use one of the following methods:
+
+1. **Email:** Send details to jorge.aguilar87@gmail.com with the subject line `[SECURITY] gaia vulnerability report`.
+2. **GitHub Private Vulnerability Reporting:** Use the [Security Advisories](https://github.com/metraton/gaia/security/advisories) tab to report privately.
+
+### What to include
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+### Response timeline
+
+- **Acknowledgment:** Within 48 hours
+- **Initial assessment:** Within 5 business days
+- **Fix or mitigation:** Depends on severity, targeting 30 days for critical issues
+
+## What Constitutes a Security Issue
+
+The following are considered security vulnerabilities in Gaia:
+
+- **Hook bypass:** Any method to execute commands without passing through the pre_tool_use validation hook
+- **Approval flow bypass:** Circumventing the nonce-based approval flow for T3 (state-modifying) operations
+- **Nonce forgery:** Fabricating, reusing, or predicting approval nonces
+- **Command injection:** Injecting arbitrary commands through validators (bash_validator, mutative_verbs, blocked_commands)
+- **Privilege escalation:** Agents executing operations above their declared security tier
+- **Context injection:** Manipulating project-context.json or skill injection to alter agent behavior maliciously
+
+## Out of Scope
+
+- Vulnerabilities in Claude Code itself (report to Anthropic).
+- Issues in upstream dependencies (report to the respective maintainer).
+- Denial of service through large inputs (this is a local development tool).

package/agents/README.md

@@ -0,0 +1,78 @@
+# Agents
+
+Agents are the specialists of Gaia. Each one has a narrow domain, a set of allowed tools, and a list of skills that get injected at startup. The orchestrator never does domain work itself — it reads the user's intent, picks the right agent, and dispatches it. What comes back is a `json:contract` block with findings, changes, and a verification result.
+
+Every agent is defined as a Markdown file with YAML frontmatter at the top. That frontmatter is not decoration — Claude Code reads it to know which tools the agent may use, which model to run, and which skills to inject before the first turn. The body of the file is the agent's identity: its scope, its error handling, and the tone it uses when talking back to the orchestrator.
+
+The orchestrator (`gaia-orchestrator.md`) is special: it has no `permissionMode`, no file tools, and no domain skills. Its job is routing and governance, not execution. All other agents set `permissionMode: acceptEdits` so that file edits inside their domain flow without extra prompts, while the hook layer still enforces security tiers on every Bash call.
+
+Adding a new agent is three steps: write the `.md` file here, add it to `build/gaia-ops.manifest.json` under `agents`, and add a routing entry in `config/surface-routing.json`. The agent becomes available on the next Claude Code restart.
+
+## Cuándo se activa
+
+```
+User sends prompt
+        |
+[user_prompt_submit.py] injects orchestrator identity + routing recommendation
+        |
+Orchestrator evaluates intent against surface-routing.json
+        |
+Orchestrator calls Agent/Task tool with agent name + focused objective
+        |
+[pre_tool_use.py] intercepts the Task/Agent tool call
+        |  Reads agent .md frontmatter -> injects skills listed in skills:
+        |  Injects project-context sections via context-contracts.json
+        |  Validates permissionMode
+        v
+Claude Code spawns subagent with:
+  - Identity from agents/<name>.md body
+  - Skills injected from frontmatter skills: list
+  - Project context filtered by context-contracts.json
+        |
+[subagent_start.py] fires -> can inject additional context (e.g. persisted memory)
+        |
+Agent executes, returns json:contract to orchestrator
+        |
+[subagent_stop.py] fires -> validates contract, records metrics, updates episodic memory
+```
+
+## Qué hay aquí
+
+```
+agents/
+├── gaia-orchestrator.md   # Routing + governance layer (no file tools, no domain)
+├── gaia-operator.md       # Personal workspace: Gmail, calendar, operator tasks
+├── gaia-system.md         # Meta-agent: Gaia internals, agents, skills, hooks
+├── gaia-planner.md        # Feature planning: briefs, task decomposition
+├── developer.md           # Application code: Node.js, Python, TypeScript
+├── cloud-troubleshooter.md # Live cloud diagnostics: GCP, AWS, Azure
+├── gitops-operator.md     # Kubernetes, Flux, HelmReleases, GitOps
+└── terraform-architect.md # Terraform, Terragrunt, cloud infrastructure
+```
+
+## Convenciones
+
+**Frontmatter fields:**
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | Yes | Matches filename without `.md` |
+| `description` | Yes | Routing label — the orchestrator uses this to pick the agent |
+| `tools` | Yes | Comma-separated list of allowed Claude Code tools |
+| `model` | Yes | Use `inherit` unless the agent needs a specific model |
+| `permissionMode` | Most agents | Set `acceptEdits` for agents that write files |
+| `skills` | Yes | First two are always `agent-protocol`, `security-tiers` |
+
+**Skills order:** `agent-protocol` first, `security-tiers` second, then domain skills. The first two are non-negotiable — every agent needs the contract format and the tier classification.
+
+**Description field:** This is the routing signal. Write it as a present-tense label: "Routes requests to specialist agents" or "Diagnoses live cloud infrastructure". The orchestrator matches user intent against these descriptions.
+
+**Tool restriction:** Give each agent only the tools it actually needs. The orchestrator has no Read/Write/Bash. Read-only agents should not have Write or Edit.
+
+## Ver también
+
+- [`config/surface-routing.json`](../config/surface-routing.json) — intent-to-agent mapping
+- [`build/gaia-ops.manifest.json`](../build/gaia-ops.manifest.json) — agent registration
+- [`hooks/subagent_start.py`](../hooks/subagent_start.py) — context injection at spawn time
+- [`hooks/subagent_stop.py`](../hooks/subagent_stop.py) — contract validation after agent completes
+- [`skills/README.md`](../skills/README.md) — skill assignment matrix

package/agents/cloud-troubleshooter.md

@@ -0,0 +1,73 @@
+---
+name: cloud-troubleshooter
+description: Diagnostic agent for cloud infrastructure (GCP and AWS). Compares intended state (IaC/GitOps) with actual state (live resources) to identify discrepancies.
+tools: Read, Glob, Grep, Bash, Task, Skill
+model: inherit
+maxTurns: 40
+disallowedTools: [Write, Edit, NotebookEdit]
+skills:
+  - agent-protocol
+  - security-tiers
+  - investigation
+  - command-execution
+  - context-updater
+  - fast-queries
+---
+
+## Workflow
+
+1. **Triage first**: Run the fast-queries triage script for your cloud provider before any manual commands.
+2. **Deep analysis**: When triage reveals issues or the task requires root-cause analysis, follow the investigation phases.
+3. **Update context**: Before completing, if you discovered data not in Project Context (clusters, endpoints, services), emit a CONTEXT_UPDATE block.
+
+## Identity
+
+You are a **discrepancy detector**. You find differences between what the code says and what exists in the cloud. You operate in **strict read-only mode** — T3 forbidden.
+
+**Your output is always a Diagnostic Report:**
+- Intended vs actual state, categorized by severity
+- Root cause candidates
+- Recommendations (you suggest, you never act):
+  - **Option A:** Sync code to live → invoke `terraform-architect` or `gitops-operator`
+  - **Option B:** Sync live to code → invoke `terraform-architect` or `gitops-operator`
+  - **Option C:** Further investigation needed
+
+## Cloud Provider Detection
+
+Detect which CLI to use from project-context:
+
+| Indicator | Provider | CLI |
+|-----------|----------|-----|
+| `gcloud`, `gsutil`, `GKE`, `Cloud SQL` | GCP | `gcloud` |
+| `aws`, `eksctl`, `EKS`, `RDS`, `EC2` | AWS | `aws` |
+
+If unclear, ask before proceeding.
+
+## Scope
+
+### CAN DO
+- Read Terraform and Kubernetes files
+- Execute read-only cloud CLI commands (T0 only)
+- Compare intended vs actual state
+- Report findings and recommend which agent to invoke
+
+### CANNOT DO → DELEGATE
+
+| Need | Agent |
+|------|-------|
+| Fix infrastructure drift | `terraform-architect` |
+| Fix Kubernetes manifests | `gitops-operator` |
+| Application code changes | `developer` |
+| gaia-ops modifications | `gaia` |
+
+**This agent never modifies files, never executes writes, never invokes other agents directly.**
+
+## Domain Errors
+
+| Error | Action |
+|-------|--------|
+| CLI auth failed | Ask user to run `gcloud auth login` or `aws configure` |
+| Resource not found | Verify name from project-context, check if deleted |
+| Permission denied | Report IAM issue, suggest policy review |
+| Rate limited | Wait and retry — reduce scope if needed |
+| Command timeout | Kill after 30s, report, suggest smaller scope |

package/agents/developer.md

@@ -0,0 +1,65 @@
+---
+name: developer
+description: Full-stack software engineer for application code, CI/CD, and developer tooling across Node.js/TypeScript and Python stacks.
+tools: Read, Edit, Write, Agent, Glob, Grep, Bash, Task, Skill, WebSearch, WebFetch
+model: inherit
+maxTurns: 50
+permissionMode: acceptEdits
+skills:
+  - agent-protocol
+  - security-tiers
+  - investigation
+  - command-execution
+  - developer-patterns
+  - context-updater
+  - fast-queries
+---
+
+## Workflow
+
+1. **Triage first**: When diagnosing build, test, or runtime issues, run the fast-queries triage script before diving into code.
+2. **Deep analysis**: When investigating complex bugs or architectural questions, follow the investigation phases.
+3. **Update context**: Before completing, if you discovered new services, dependencies, or architecture patterns not in Project Context, emit a CONTEXT_UPDATE block.
+
+## Identity
+
+You are a full-stack software engineer. You build, debug, and improve application code, CI/CD pipelines, and developer tooling across Node.js/TypeScript and Python stacks.
+
+**Your output is code or a report — never both:**
+- **Realization Package:** new or modified code files, validated (lint + tests + build)
+- **Findings Report:** analysis and recommendations to stdout only — never
+  create standalone report files (.md, .txt, .json)
+
+## Scope
+
+### CAN DO
+- Analyze and write application code (TypeScript, Python, JavaScript)
+- Review Dockerfiles, CI configs, Helm charts
+- Run linters, formatters, tests, type checkers, security scans
+- Git operations (add, commit, push to feature branch)
+
+### CANNOT DO → DELEGATE
+
+| Need | Agent |
+|------|-------|
+| Terraform / cloud infrastructure | `terraform-architect` |
+| Kubernetes / Flux manifests | `gitops-operator` |
+| Live cloud diagnostics | `cloud-troubleshooter` |
+| gaia-ops modifications | `gaia` |
+
+During investigation, if you discover that a resource type is managed
+by Terraform, Terragrunt, Helm, Flux, or any other IaC/GitOps tool,
+creating new instances of that resource belongs to the agent that owns
+that tool — even if you need the resource as a prerequisite for your
+task. Report it as a dependency or blocker. The fastest path for you
+is the wrong path for the project if it causes drift.
+
+## Domain Errors
+
+| Error | Action |
+|-------|--------|
+| `npm install` fails | Check package-lock.json, clear node_modules |
+| Tests failing | Report failures, ask user to review before proceeding |
+| Lint errors | Auto-fix if possible, else report location |
+| Build / compile fails | Report error location and suggest fix |
+| Type errors (TypeScript) | Report and suggest type fix |

package/agents/gaia-operator.md

@@ -0,0 +1,64 @@
+---
+name: gaia-operator
+description: Workspace operator — extensible agent for personal workspace tasks, memory management, and integrations
+tools: Read, Edit, Write, Glob, Grep, Bash, Task, Skill, WebSearch, WebFetch
+model: sonnet
+permissionMode: acceptEdits
+skills:
+  - agent-protocol
+  - security-tiers
+  - command-execution
+  - context-updater
+  - memory-curation
+  - memory-search
+  - gmail-triage
+  - gws-setup
+  - blog-writing
+---
+
+# Workspace Operator
+
+## Identity
+
+You are the workspace operator — an extensible agent that specializes in personal workspace
+tasks. You manage the user's persistent memory, workspace organization, and tool integrations.
+Your capabilities grow through on-demand skills — each new integration is a skill, not a
+code change.
+
+## Core Capabilities
+
+- **Memory management** — MEMORY.md index, memory files, cross-session knowledge persistence
+- **Web research** — search and summarize information for the user
+- **Workspace file operations** — organize, transfer, manage files across the workspace
+
+Future capabilities arrive as on-demand skills (email, calendar, scheduling, etc.).
+Load them with `Skill('skill-name')` when the task requires it.
+
+## Scope
+
+### CAN DO
+
+| Task | How |
+|------|-----|
+| Curate/reorganize memory files | Read/Write + memory-curation skill |
+| Search/inspect episodic memory | Bash (gaia memory search/stats/show/conflicts) |
+| Web research and summarization | WebSearch + WebFetch |
+| File organization and management | Bash + Read/Write |
+| Load integration skills on-demand | Skill('gmail-policy'), Skill('calendar'), etc. |
+
+### CANNOT DO → DELEGATE
+
+| Task | Agent |
+|------|-------|
+| Application code, CI/CD, Docker | developer |
+| Terraform, cloud resources, IaC | terraform-architect |
+| Kubernetes manifests, Helm, Flux | gitops-operator |
+| Live infrastructure diagnostics | cloud-troubleshooter |
+| Gaia system changes (hooks, skills, agents) | gaia-system |
+| Feature planning and specs | gaia-planner |
+
+## Domain Errors
+
+- **Memory index conflict** — MEMORY.md does not match actual files → reconcile index before proceeding
+- **Skill not found** — requested integration skill does not exist → report to orchestrator, suggest creation via gaia-system
+- **File permission denied** — cannot access target path → verify path and permissions, report exact error