@jaguilar87/gaia 5.0.0-rc1

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@jaguilar87/gaia",
+  "version": "5.0.0-rc1",
+  "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "gaia": "bin/gaia",
+    "gaia-doctor": "bin/gaia-doctor.js",
+    "gaia-skills-diagnose": "bin/gaia-skills-diagnose.js",
+    "gaia-cleanup": "bin/gaia-cleanup.js",
+    "gaia-uninstall": "bin/gaia-uninstall.js",
+    "gaia-metrics": "bin/gaia-metrics.js",
+    "gaia-review": "bin/gaia-review.js",
+    "gaia-status": "bin/gaia-status.js",
+    "gaia-history": "bin/gaia-history.js",
+    "gaia-update": "bin/gaia-update.js",
+    "gaia-scan": "bin/gaia-scan",
+    "gaia-evidence": "bin/gaia-evidence"
+  },
+  "keywords": [
+    "claude-code",
+    "devops",
+    "gitops",
+    "terraform",
+    "kubernetes",
+    "ai-agents",
+    "gaia",
+    "orchestration",
+    "automation"
+  ],
+  "author": "Jorge Aguilar <jorge.aguilar87@gmail.com>",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metraton/gaia.git"
+  },
+  "homepage": "https://github.com/metraton/gaia#readme",
+  "bugs": {
+    "url": "https://github.com/metraton/gaia/issues",
+    "email": "jorge.aguilar87@gmail.com"
+  },
+  "files": [
+    ".claude-plugin/",
+    "bin/",
+    "agents/",
+    "tools/",
+    "hooks/",
+    "commands/",
+    "templates/",
+    "config/",
+    "skills/",
+    "dist/",
+    "git-hooks/",
+    "README.md",
+    "INSTALL.md",
+    "CHANGELOG.md",
+    "ARCHITECTURE.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "pyproject.toml",
+    "index.js"
+  ],
+  "scripts": {
+    "test": "python3 -m pytest tests/ -v --ignore=tests/layer2_llm_evaluation --ignore=tests/layer3_e2e",
+    "test:layer1": "python3 -m pytest tests/ -v --ignore=tests/layer2_llm_evaluation --ignore=tests/layer3_e2e",
+    "test:layer2": "python3 -m pytest tests/layer2_llm_evaluation/ -v -m llm",
+    "test:layer3": "python3 -m pytest tests/layer3_e2e/ -v -m e2e",
+    "test:all": "python3 -m pytest tests/ -v -m ''",
+    "test:promptfoo": "npx promptfoo eval --config tests/promptfoo.yaml",
+    "lint": "eslint .",
+    "clean:dist": "rm -rf dist/",
+    "build:plugins": "npm run clean:dist && python3 scripts/build-plugin.py gaia-security && python3 scripts/build-plugin.py gaia-ops",
+    "clean": "find . -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true",
+    "pre-publish": "node bin/pre-publish-validate.js",
+    "pre-publish:dry": "node bin/pre-publish-validate.js --dry-run",
+    "pre-publish:validate": "node bin/pre-publish-validate.js --validate-only",
+    "prepack": "npm run clean",
+    "prepublishOnly": "npm run build:plugins && node bin/pre-publish-validate.js",
+    "postinstall": "node bin/gaia-update.js",
+    "preuninstall": "node bin/gaia-cleanup.js"
+  },
+  "_postinstall_note": "postinstall: settings.json replaced (hooks only), permissions merged into settings.local.json (union, user config preserved)",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "ora": "^7.0.1",
+    "prompts": "^2.4.2",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "eslint": "^8.50.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "python": ">=3.9"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "gaia"
+version = "5.0.0-rc1"
+description = "Multi-agent orchestration system for Claude Code - DevOps automation toolkit"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Jorge Aguilar", email = "jorge.aguilar87@gmail.com"},
+]
+readme = "README.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.4.0",
+]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "tools/scan/tests"]
+markers = [
+    "parity: JS-Python CLI parity comparison tests",
+]

package/skills/README.md

@@ -0,0 +1,154 @@
+# Skills
+
+Skills are the procedural knowledge layer of Gaia. Where agents carry identity — their scope, their tone, their domain — skills carry process: how to classify a command, how to format a response contract, how to approach an investigation. An agent without skills knows who it is but not how to operate. Skills bridge that gap by injecting step-by-step protocols that the agent follows during its session.
+
+Each skill lives in its own directory under `skills/<name>/` and contains at minimum a `SKILL.md` file. That file is what gets injected. Supporting material (`reference.md`, `examples.md`) lives in the same directory but is read on-demand — the agent pulls it from disk when needed rather than receiving it at startup. This keeps startup context lean while making full documentation accessible.
+
+Skills are not shared via inheritance or imports — they are text injected verbatim into the agent's context window. The size limit for injected skills is roughly 100 lines. If a skill grows beyond that, the detailed content moves to `reference.md` and the main `SKILL.md` becomes a compact index pointing there.
+
+The assignment matrix below shows which skills each agent receives. The first two — `agent-protocol` and `security-tiers` — appear on every agent. They are the non-negotiables: every agent must understand the response contract and the tier system.
+
+## Cuándo se activa
+
+Skills reach an agent through two distinct routes, and understanding both matters when troubleshooting why a skill is or is not present in a session.
+
+**Route 1 — Startup injection via frontmatter:**
+
+```
+Orchestrator dispatches agent
+        |
+pre_tool_use.py intercepts the Task/Agent tool call
+        |
+Reads agents/<name>.md frontmatter -> skills: list
+        |
+For each skill in the list:
+  reads skills/<skill>/SKILL.md from disk
+  appends content to agent's system context
+        |
+Agent starts with all listed skills already in context
+```
+
+**Route 2 — On-demand via Skill tool:**
+
+```
+Agent is running and encounters a situation
+requiring a workflow skill (e.g. approval, execution, git-conventions)
+        |
+Agent calls Skill tool: Skill("request-approval")
+        |
+Claude Code reads skills/request-approval/SKILL.md from disk
+        |
+Content is injected into the agent's active context window
+        |
+Agent follows the newly loaded protocol
+```
+
+Orchestrator-level skills (`agent-response`, `orchestrator-approval`) are always Route 2 — they are never in a frontmatter list, only loaded when the orchestrator needs to interpret a specific situation.
+
+## Qué hay aquí
+
+```
+skills/
+├── agent-protocol/        # Response contract format, state machine, error handling
+├── agent-response/        # Orchestrator: interpret agent json:contract responses
+├── agentic-loop/          # Iterative metric-driven improvement loop (on-demand injection)
+├── blog-writing/          # Blog article writing and publishing for metraton.github.io
+├── brief-spec/            # Brief and spec creation for features before planning
+├── command-execution/     # Defensive Bash execution, no-pipes discipline
+│   └── reference.md
+├── context-updater/       # CONTEXT_UPDATE format and writable sections contract
+│   └── examples.md
+├── developer-patterns/    # Application code patterns (Node.js, Python)
+├── execution/             # Post-approval execution discipline
+├── fast-queries/          # Quick diagnostic scripts for cloud/system state
+├── gaia-compact/          # Orchestrator: structured /compact prompt with preservation contract
+├── gaia-patterns/         # Gaia component patterns: hooks, agents, routing, CLI
+│   └── reference.md
+├── gaia-planner/          # Feature planning, briefs, task decomposition
+├── gaia-release/          # Gaia release pipeline: live, dry-run, beta, stable
+├── gaia-self-check/       # Validate internal consistency of the .claude/ installation
+├── gaia-verify/           # Verify a Gaia installation across delivery surfaces
+├── git-conventions/       # Conventional Commits (on-demand workflow skill)
+├── gitops-patterns/       # GitOps/Flux/Kubernetes patterns
+│   └── reference.md
+├── gmail-policy/          # Gmail domain policy (label-only, no delete)
+├── gmail-triage/          # Interactive Gmail inbox triage
+├── gws-setup/             # Google Workspace CLI (gws) installation and configuration
+├── investigation/         # Diagnosis methodology and pattern analysis
+├── memory-curation/       # Curate MEMORY.md index and topic files
+├── memory-search/         # Query episodic memory via `gaia memory` CLI
+├── orchestrator-approval/ # T3 approval presentation for orchestrator
+├── pending-approvals/     # Present and manage pending approval requests
+├── readme-writing/        # How to write READMEs for Gaia component folders
+├── request-approval/      # T3 approval-request workflow (attempt first, emit APPROVAL_REQUEST)
+│   ├── reference.md
+│   └── examples.md
+├── schedule-task/         # Dispatch parameter extraction and prompt templates
+├── security-tiers/        # T0-T3 classification + hook enforcement model
+│   └── reference.md
+├── skill-creation/        # How to design and write new skills
+├── terraform-patterns/    # Terraform/Terragrunt patterns
+│   └── reference.md
+└── reference.md           # Cross-skill reference index
+```
+
+## Convenciones
+
+**Skill assignment matrix:**
+
+| Agent | Core Skills | Domain Skills |
+|-------|-------------|---------------|
+| cloud-troubleshooter | agent-protocol, security-tiers, investigation, command-execution | context-updater, fast-queries |
+| terraform-architect | agent-protocol, security-tiers, investigation, command-execution, terraform-patterns | context-updater, fast-queries |
+| gitops-operator | agent-protocol, security-tiers, investigation, command-execution, gitops-patterns | context-updater, fast-queries |
+| developer | agent-protocol, security-tiers, investigation, command-execution, developer-patterns | context-updater, fast-queries |
+| gaia-system | agent-protocol, security-tiers, command-execution, gaia-patterns, gaia-release, skill-creation | gaia-verify |
+| gaia-planner | agent-protocol, security-tiers | gaia-planner |
+| gaia-operator | agent-protocol, security-tiers, command-execution, context-updater, memory-curation, memory-search, gmail-triage, gws-setup | blog-writing |
+
+Orchestrator skills (loaded on-demand via Skill tool, not assigned in frontmatter):
+- `agent-response` — contract status interpretation and presentation
+- `orchestrator-approval` — T3 approval presentation and grant activation
+- `gaia-compact` — structured `/compact` invocation with a six-category preservation prompt
+
+Workflow skills (on-demand injection, not in any agent frontmatter):
+- `agentic-loop` — iterative metric-driven improvement; injected by orchestrator text prompt, `user-invocable: false`
+- `brief-spec` — brief and spec creation; loaded on demand by orchestrator
+- `execution` — post-approval execution discipline
+- `git-conventions` — Conventional Commits format
+- `pending-approvals` — present and resolve pending approval requests
+- `request-approval` — T3 approval-request workflow
+- `schedule-task` — dispatch parameter templates
+
+**Skill types:**
+
+| Type | Injection | Examples |
+|------|-----------|---------|
+| Core | Always via `skills:` frontmatter | agent-protocol, security-tiers |
+| Common | Most agents via `skills:` frontmatter | command-execution, context-updater |
+| Domain | Per-agent via `skills:` frontmatter | terraform-patterns, gaia-patterns |
+| Workflow | On-demand (agent reads from disk) | request-approval, execution, git-conventions |
+| Orchestrator | On-demand via Skill tool | agent-response, orchestrator-approval |
+
+**SKILL.md format:**
+
+```yaml
+---
+name: skill-name
+description: When Claude should load and follow this skill
+metadata:
+  user-invocable: false
+  type: core
+---
+
+# Skill Content
+```
+
+**Line budget:** Keep injected `SKILL.md` under 100 lines. Move details to `reference.md` (read on-demand). Supporting examples go in `examples.md`.
+
+## Ver también
+
+- [`agents/README.md`](../agents/README.md) — agent frontmatter and skills: field
+- [`hooks/pre_tool_use.py`](../hooks/pre_tool_use.py) — where skill injection happens at runtime
+- [`skills/skill-creation/SKILL.md`](./skill-creation/SKILL.md) — how to design a new skill
+- [`skills/gaia-patterns/reference.md`](./gaia-patterns/reference.md) — full component inventory

package/skills/agent-protocol/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: agent-protocol
+description: Use when producing any agent response
+metadata:
+  user-invocable: false
+  type: protocol
+---
+
+# Agent Protocol
+
+This protocol governs REPORTING FORMAT, not tool access. All agents may use their declared tools during any phase.
+
+## Response Contract
+
+Every response MUST end with a single fenced `json:contract` block.
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "<STATUS>",
+    "agent_id": "<a + 5+ hex chars>",
+    "pending_steps": [],
+    "next_action": "done"
+  },
+  "evidence_report": {
+    "patterns_checked": [],
+    "files_checked": [],
+    "commands_run": [],
+    "key_outputs": [],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": [],
+    "open_gaps": [],
+    "verification": null
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+**agent_status** -- `plan_status` (one of 5 states below), `agent_id` (generate once, reuse), `pending_steps` (`[]` when done), `next_action` (`"done"` or what's next).
+
+**evidence_report** -- Use `[]` when not applicable, 1-3 items each. `key_outputs`: what changed. `verbatim_outputs`: literal output, truncate ~100 lines. `cross_layer_impacts`: adjacent surfaces. `open_gaps`: what remains unverified. `verification`: **required when COMPLETE** (see Verification Gate), `null` otherwise.
+
+**consolidation_report** -- Required when `consolidation_required` or `multi_surface` is true. Otherwise `null`. Fields: `ownership_assessment`, `confirmed_findings`, `suspected_findings`, `conflicts`, `next_best_agent`. See `examples.md`.
+
+**approval_request** -- Required when APPROVAL_REQUEST. Fields: `operation`, `exact_content`, `scope`, `risk_level`, `rollback`, `verification`. On `[T3_BLOCKED]` with `approval_id`: set APPROVAL_REQUEST, include `approval_id`, wait. See `examples.md`.
+
+## Universal Execution Loop
+
+Each increment: **INVESTIGATE** (read, search) -> **PLAN** (propose; APPROVAL_REQUEST if T3) -> **EXECUTE** (write, run) -> **VERIFY** (confirm results) -> **COMPLETE** or loop back on failure. Decompose large tasks into 2-5 increments; each is one action paired with one verification. Every increment ends verified. Fix before moving on -- compounding failures is exponential.
+
+## Verification Gate
+
+An agent cannot set `plan_status: "COMPLETE"` without a `verification` object in `evidence_report`. When verification fails, loop back to EXECUTE -- do not complete.
+
+```json
+"verification": {
+  "method": "test | dry-run | metric | self-review",
+  "checks": ["what was checked"],
+  "result": "pass | fail",
+  "details": "concrete evidence"
+}
+```
+
+Choose the method that fits your domain. Infrastructure: `dry-run` (terraform plan). Code: `test` (pytest, lint). Gaia skills: `self-review` (line count, frontmatter). Email: `metric` (count match). Git/file ops: `test` or `self-review`. When no automated check exists, `self-review` is the minimum: state what you checked and what you observed. For full examples see `examples.md`.
+
+## State Machine
+
+| Status | Meaning |
+|--------|---------|
+| `IN_PROGRESS` | Investigating, planning, or executing work |
+| `APPROVAL_REQUEST` | Emitted when a hook blocks a specific mutative command -- agent requests user approval for the exact command via `approval_request` |
+| `COMPLETE` | Verified -- `verification.result` is `"pass"` |
+| `BLOCKED` | Cannot proceed -- escalated |
+| `NEEDS_INPUT` | Missing information from user |
+
+### Transitions
+
+```
+IN_PROGRESS -> COMPLETE                            (requires verification evidence)
+IN_PROGRESS -> APPROVAL_REQUEST -> IN_PROGRESS -> COMPLETE
+IN_PROGRESS -> BLOCKED | NEEDS_INPUT               (any point)
+IN_PROGRESS -> IN_PROGRESS                         (retry or verify-fail loop, max 2)
+```
+
+## Error Handling
+
+| Type | Action | Status |
+|------|--------|--------|
+| Recoverable | Fix and retry (max 2) | `IN_PROGRESS` |
+| Blocker | Log details, list solutions | `BLOCKED` |
+| Ambiguous | List options | `NEEDS_INPUT` |
+| Contract repair | Reissue `json:contract`, skip re-investigation (max 2) | `IN_PROGRESS` |

package/skills/agent-protocol/examples.md

@@ -0,0 +1,223 @@
+# Agent Protocol -- Status-Specific Examples
+
+Read on-demand when constructing a `json:contract` block.
+See `SKILL.md` for the schema definition and field rules.
+
+## COMPLETE (verified result)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "COMPLETE",
+    "agent_id": "ab7e4d2",
+    "pending_steps": [],
+    "next_action": "done"
+  },
+  "evidence_report": {
+    "patterns_checked": ["existing HelmRelease naming convention in flux/apps/"],
+    "files_checked": ["flux/apps/qxo-api/helmrelease.yaml"],
+    "commands_run": ["kubectl get hr -n qxo -> all reconciled"],
+    "key_outputs": ["All 12 HelmReleases healthy, no drift detected"],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": [],
+    "open_gaps": [],
+    "verification": {
+      "method": "test",
+      "checks": ["kubectl get hr -n qxo shows all reconciled", "no suspended or failed HelmReleases"],
+      "result": "pass",
+      "details": "12/12 HelmReleases Ready=True. Last reconciled within 5m."
+    }
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+## BLOCKED (cannot proceed)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "BLOCKED",
+    "agent_id": "ac3a1f9",
+    "pending_steps": ["validate IAM binding", "apply terraform change"],
+    "next_action": "User must grant roles/container.admin to SA"
+  },
+  "evidence_report": {
+    "patterns_checked": ["SA binding pattern in terraform/iam/"],
+    "files_checked": ["terraform/iam/main.tf", "terraform/iam/variables.tf"],
+    "commands_run": ["gcloud iam service-accounts get-iam-policy sa@proj.iam -> missing binding"],
+    "key_outputs": ["SA lacks roles/container.admin required for node pool ops"],
+    "verbatim_outputs": ["gcloud iam service-accounts get-iam-policy sa@proj.iam:\n```\nbindings: []\n```"],
+    "cross_layer_impacts": ["GKE node pool scaling depends on this SA"],
+    "open_gaps": ["Whether SA should get role directly or via workload identity"],
+    "verification": null
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+## NEEDS_INPUT (missing information)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "NEEDS_INPUT",
+    "agent_id": "ad9f2b1",
+    "pending_steps": ["create namespace manifest", "configure HelmRelease"],
+    "next_action": "User must choose: Option A (shared namespace) or Option B (dedicated namespace)"
+  },
+  "evidence_report": {
+    "patterns_checked": ["namespace conventions in flux/clusters/"],
+    "files_checked": ["flux/clusters/dev/namespaces/"],
+    "commands_run": [],
+    "key_outputs": ["Both patterns exist in codebase -- no single convention"],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": ["Network policies differ per pattern"],
+    "open_gaps": ["User preference for namespace isolation"],
+    "verification": null
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+## APPROVAL_REQUEST (hook blocked T3 command or plan ready for user feedback)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "APPROVAL_REQUEST",
+    "agent_id": "ae5c8a3",
+    "pending_steps": ["execute terraform apply", "verify state"],
+    "next_action": "Awaiting user feedback on terraform apply plan"
+  },
+  "evidence_report": {
+    "patterns_checked": ["existing bucket naming in terraform/gcs/"],
+    "files_checked": ["terraform/gcs/main.tf", "terraform/gcs/variables.tf"],
+    "commands_run": ["terraform plan -out=tfplan -> 1 to add, 0 to change, 0 to destroy"],
+    "key_outputs": ["Plan adds 1 GCS bucket with standard config"],
+    "verbatim_outputs": ["terraform plan:\n```\n+ google_storage_bucket.events\n  name: qxo-events-dev\n  location: us-east4\n```"],
+    "cross_layer_impacts": ["Flux ExternalSecret must reference new bucket"],
+    "open_gaps": [],
+    "verification": null
+  },
+  "consolidation_report": null,
+  "approval_request": {
+    "operation": "Create GCS bucket qxo-events-dev",
+    "exact_content": "terraform apply -auto-approve",
+    "scope": "terraform/gcs/main.tf, GCS bucket in us-east4",
+    "risk_level": "MEDIUM",
+    "rollback": "terraform destroy -target=google_storage_bucket.events",
+    "verification": "gcloud storage buckets describe gs://qxo-events-dev"
+  }
+}
+```
+
+## APPROVAL_REQUEST with approval_id (hook blocked T3 command)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "APPROVAL_REQUEST",
+    "agent_id": "af1d9b7",
+    "pending_steps": ["execute git push", "verify Flux reconciliation"],
+    "next_action": "Hook blocked git push -- awaiting user approval"
+  },
+  "evidence_report": {
+    "patterns_checked": ["git branch naming in flux/clusters/"],
+    "files_checked": ["flux/apps/qxo-api/helmrelease.yaml"],
+    "commands_run": ["git diff HEAD -> 1 file changed", "git push origin main -> BLOCKED by hook"],
+    "key_outputs": ["Push blocked by security hook, approval_id issued"],
+    "verbatim_outputs": ["[T3_BLOCKED] MUTATIVE operation requires user approval. approval_id: a1b2c3..."],
+    "cross_layer_impacts": ["Flux will reconcile HelmRelease on push"],
+    "open_gaps": [],
+    "verification": null
+  },
+  "consolidation_report": null,
+  "approval_request": {
+    "operation": "Push HelmRelease changes to main",
+    "exact_content": "git push origin main",
+    "scope": "flux/apps/qxo-api/helmrelease.yaml",
+    "risk_level": "MEDIUM",
+    "rollback": "git revert HEAD && git push",
+    "verification": "flux get hr -n qxo -> reconciled",
+    "approval_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
+  }
+}
+```
+
+## With Consolidation (multi-surface task)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "COMPLETE",
+    "agent_id": "af4b2e8",
+    "pending_steps": [],
+    "next_action": "done"
+  },
+  "evidence_report": {
+    "patterns_checked": ["terraform module structure in terraform/modules/"],
+    "files_checked": ["terraform/modules/gke/main.tf", "flux/clusters/dev/kustomization.yaml"],
+    "commands_run": ["terragrunt plan -chdir=/abs/path -> no changes"],
+    "key_outputs": ["Terraform state matches code; Flux kustomization references correct cluster"],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": ["Flux depends on GKE node pool count from terraform output"],
+    "open_gaps": ["HPA config in flux not verified"],
+    "verification": {
+      "method": "dry-run",
+      "checks": ["terragrunt plan shows no changes", "kustomization references match cluster name"],
+      "result": "pass",
+      "details": "Plan: 0 to add, 0 to change, 0 to destroy. Kustomization sourceRef matches cluster af4b2e8."
+    }
+  },
+  "consolidation_report": {
+    "ownership_assessment": "cross_surface_dependency",
+    "confirmed_findings": ["GKE cluster config matches terraform code", "Node pool count is 3 in both plan and live"],
+    "suspected_findings": ["HPA max replicas may exceed node capacity"],
+    "conflicts": [],
+    "open_gaps": ["HPA config in flux not verified -- gitops-operator should check"],
+    "next_best_agent": "gitops-operator"
+  },
+  "approval_request": null
+}
+```
+
+## COMPLETE with task decomposition (multi-increment)
+
+Shows a skill-creation task where each subtask was verified individually.
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "COMPLETE",
+    "agent_id": "a9c4f71",
+    "pending_steps": [],
+    "next_action": "done"
+  },
+  "evidence_report": {
+    "patterns_checked": ["existing skill structure in skills/", "skill-creation standards"],
+    "files_checked": ["skills/new-skill/SKILL.md", "skills/new-skill/reference.md"],
+    "commands_run": [],
+    "key_outputs": ["Created new-skill with SKILL.md (87 lines) and reference.md"],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": ["Agents using this skill need frontmatter update"],
+    "open_gaps": [],
+    "verification": {
+      "method": "self-review",
+      "checks": [
+        "SKILL.md line count: 87 (under 100 budget)",
+        "Frontmatter has name, description, metadata fields",
+        "Description contains triggering conditions only",
+        "Type-appropriate structure (domain: conventions, examples, key rules)"
+      ],
+      "result": "pass",
+      "details": "87 lines. Frontmatter valid. Description triggers on domain conditions. Structure matches domain type from skill-creation standards."
+    }
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```

package/skills/agent-response/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: agent-response
+description: Use when an agent returns a json:contract response that needs to be interpreted and presented to the user
+metadata:
+  user-invocable: false
+  type: protocol
+---
+
+# Agent Response Protocol
+
+The orchestrator's job is translation -- turning structured agent output into
+clear user communication. Every status requires a different response because
+each represents a different kind of decision point for the user.
+
+## State Machine
+
+```
+Agent returns json:contract
+  |- COMPLETE         -> Summarize key_outputs (3-5 bullets)
+  |- NEEDS_INPUT      -> AskUserQuestion, then SendMessage answer back
+  |- REVIEW           -> Load Skill("orchestrator-approval") if approval_id present,
+  |                      otherwise AskUserQuestion (execute/modify/cancel),
+  |                      then SendMessage to resume the same agent
+  |- BLOCKED          -> Present open_gaps via AskUserQuestion
+  |                      If user provides direction: dispatch new agent addressing the blocker.
+  |                      If user accepts the limitation: close the task as incomplete and move on.
+  +- IN_PROGRESS      -> SendMessage to resume agent
+```
+
+## Mandatory Actions per Status
+
+| Status | Action | Tool |
+|---|---|---|
+| `COMPLETE` | Summarize `key_outputs` in 3-5 bullets. Mention `cross_layer_impacts` and `open_gaps` if non-empty. Say "ask for details" if `verbatim_outputs` exists. | Direct response |
+| `NEEDS_INPUT` | Present the agent's question with options | `AskUserQuestion` -> `SendMessage` |
+| `REVIEW` | If `approval_request.approval_id` is present: load `Skill("orchestrator-approval")`. Otherwise: present plan with options execute / modify / cancel. On execute or modify: resume the SAME agent via SendMessage -- it already holds full context from its investigation. | `AskUserQuestion` -> `SendMessage` |
+| `BLOCKED` | Present alternatives from `open_gaps`. If user provides direction, dispatch a new agent addressing the blocker. If user accepts the limitation, close as incomplete and move on. | `AskUserQuestion` |
+| `IN_PROGRESS` | Agent was interrupted, let it continue | `SendMessage` |
+
+**Why REVIEW splits on approval_id:** Hook-blocked T3 operations carry a pending
+grant that requires the structured approval flow (exact content, rollback, risk).
+Plan-first REVIEW has no pending grant -- the user just needs to confirm direction.
+Treating both the same either over-formalizes simple plans or under-secures T3 ops.
+
+## Output Fields
+
+| Field | When to surface |
+|---|---|
+| `key_outputs` | Always -- base your summary on these |
+| `verbatim_outputs` | Only when user asks for details -- relay in code blocks |
+| `cross_layer_impacts` | Always mention if non-empty -- these are side effects the user may not anticipate |
+| `open_gaps` | Always mention -- never imply certainty the agent does not have |
+| `consolidation_report` | Check for `conflicts` and `next_best_agent` |
+| `next_best_agent` | Ask user if they want to dispatch |
+
+## Multiple Agents
+
+Wait for ALL dispatched agents before responding. Partial results
+mislead -- the user acts on incomplete information, then the second
+agent contradicts the first.
+
+Consolidate findings. If agents conflict, present both sides and
+ask the user to decide.
+
+## Error Handling
+
+| Situation | Action |
+|---|---|
+| Malformed contract | Resume agent with repair instructions (max 2 retries). |