@jaguilar87/gaia 5.0.0-rc1

package/dist/gaia-ops/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/dist/gaia-ops/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/dist/gaia-ops/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/dist/gaia-ops/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). |

package/dist/gaia-ops/skills/agentic-loop/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: agentic-loop
+description: Use when the orchestrator injects "Carga la skill agentic-loop" with a goal, eval_command, metric, and threshold
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Agentic Loop
+
+Iterative improvement through small, reversible changes evaluated against a single metric. Each iteration is one hypothesis, one edit, one eval, one decision. The metric decides -- not you.
+
+## Parameters (from orchestrator prompt)
+
+`goal`, `eval_command`, `metric`, `direction` (higher/lower), `threshold`, `max_iterations`, `files_in_scope`, `branch`
+
+## Setup
+
+1. Read every file in `files_in_scope` deeply -- understand before changing
+2. `git checkout -b {branch}`
+3. Run `eval_command` -- parse `METRIC {name}={number}` from stdout -- this is your baseline
+4. Write `state.json` and `worklog.md` (schemas in `reference.md`)
+5. `git commit -m "baseline: {metric} {value}"`
+
+## Loop (repeat until threshold, max_iterations, or stop)
+
+1. **HYPOTHESIZE** -- based on worklog insights and last failure. When stuck, re-read source files; thinking longer beats trying faster
+2. **EDIT** -- one focused change. Smaller diffs are easier to evaluate and reverse
+3. **EVALUATE** -- run `eval_command`, parse `METRIC {name}={number}`
+4. **DECIDE** (mechanically, not judgment):
+   - Improved (or equal with less code) -- KEEP -- `git add -A` then `git commit -m "improve: {metric} {old}->{new}"`
+   - Same or worse -- DISCARD -- `git checkout -- .` then `git clean -fd`
+5. **LOG** -- append to `worklog.md`: run number, what changed, result, insight, next idea
+6. **UPDATE** -- write `state.json` with current values
+7. **ESCALATE** if needed:
+   - 3 consecutive discards -- REFINE (adjust within current strategy)
+   - 5 consecutive discards -- PIVOT (structurally different approach)
+   - 3 pivots without a keep -- STOP and report blockers
+8. Every 10 iterations: re-read `files_in_scope`, review worklog "What's Been Tried", recalibrate
+
+## Termination
+
+- **Threshold reached** -- `git commit -m "final: {metric} {baseline}->{final} in N iterations"`, write summary
+- **Max iterations** -- report best achieved vs threshold
+- **Stop from escalation** -- report what was tried and what blocked progress
+- All paths: finalize `state.json` (status: complete/stopped), write summary in `worklog.md`
+
+## Contract Integration
+
+Include `loop_status` in your `json:contract` agent_status on every response:
+
+```json
+"loop_status": {
+  "iteration": 5,
+  "metric": 94.5,
+  "best": 94.5,
+  "baseline": 89.0,
+  "threshold": 98,
+  "status": "iterating"
+}
+```
+
+Do NOT return `plan_status: "COMPLETE"` until the loop finishes. The user may be away for hours.
+
+## Rules
+
+- **Loop forever.** Never ask "should I continue?" The metric and thresholds decide when to stop. The user may be away for hours.
+- **One change per iteration.** Multiple changes make it impossible to isolate what helped.
+- **Metric is king.** Personal judgment about code quality does not override the number.
+- **Simpler wins ties.** Removing code for equal performance is a keep.
+- **Think longer when stuck.** Re-read source files before trying faster. Fresh context beats more iterations.
+- **Retreat, don't thrash.** Same idea reverting repeatedly means the approach is wrong -- pivot.
+
+## Anti-Patterns
+
+- Making multiple changes per iteration -- cannot isolate what helped or hurt
+- Skipping eval after a change -- invisible regressions compound
+- Continuing after 3 pivots without improvement -- diminishing returns; stop and report
+- Using `git clean -fdx` instead of `-fd` -- destroys untracked config files needed by eval
+- Editing state.json by hand instead of writing it atomically after each phase