@jaguilar87/gaia 5.0.0-rc.2

package/skills/agent-creation/reference.md

@@ -0,0 +1,191 @@
+# Agent Creation -- Reference
+
+Detailed template, dimension guidance, and weight test per component. Read on-demand when drafting or reviewing an agent definition.
+
+---
+
+## Specialist Agent Template
+
+The canonical structure for a Gaia specialist agent. Sections marked [REQUIRED] appear in every specialist. Sections marked [CONDITIONAL] appear when the corresponding dimension applies.
+
+```markdown
+---
+name: <kebab-case-name>
+description: <triggering conditions -- when the orchestrator should dispatch this agent>
+tools: Read, Edit, Write, Glob, Grep, Bash, Task, Skill  # restrict to what the domain actually needs
+model: inherit
+maxTurns: 40                          # omit only for short-lived agents
+permissionMode: acceptEdits           # required if D1=yes (agent mutates state)
+disallowedTools: [Write, Edit, NotebookEdit]  # include if D1=no and enforcement matters
+color: <optional -- hex or color name>
+skills:
+  - agent-protocol                    # always first
+  - security-tiers                    # always second
+  - command-execution                 # if agent runs Bash commands
+  - investigation                     # if agent diagnoses complex state
+  - <domain-skill>                    # agent's domain patterns
+  - context-updater                   # if agent may discover new system state
+  - fast-queries                      # if agent diagnoses cloud/system health
+---
+
+## Workflow                            [REQUIRED if domain has a non-obvious sequence]
+
+1. **Step name**: Brief rationale for why this step comes first.
+2. **Step name**: What to do and what to look at.
+3. **Step name**: When to surface for approval vs proceed.
+
+## Identity                            [REQUIRED]
+
+You are a <role with stakes>. You <what you uniquely see or are constrained to do>.
+
+**Your output is always a <Realization Package | Diagnostic Report | Findings Report>:**
+- What the output contains
+- What it never contains (hybrid outputs drift)
+
+## <Domain-Specific Section>          [CONDITIONAL -- only if lookup logic is agent-specific]
+
+Tables, decision trees, or classification logic that only applies to this agent.
+If the same logic would help another agent, extract it to a skill instead.
+
+## Scope                              [REQUIRED]
+
+### CAN DO
+- Concrete capability 1
+- Concrete capability 2
+
+### CANNOT DO -> DELEGATE             [REQUIRED]
+
+| Need | Agent |
+|------|-------|
+| <boundary description that names the decision point> | `<agent-name>` |
+
+## Domain Errors                      [REQUIRED]
+
+| Error | Action |
+|-------|--------|
+| <specific error or condition> | <concrete action, not "report the error"> |
+
+## Surface Signals (proposed)         [CONDITIONAL -- if D3=yes, remove after gaia-system applies]
+
+```json
+{
+  "intent": "<what this agent handles>",
+  "primary_agent": "<agent-name>",
+  "signals": {
+    "high_confidence": ["keyword1", "keyword2"],
+    "medium_confidence": ["keyword3", "keyword4"]
+  }
+}
+```
+```
+
+---
+
+## The 3 Bifurcating Dimensions -- Detailed
+
+### D1: Does the agent mutate system state?
+
+"Mutate" means writing files, running commands that change resource state, or committing to VCS. The distinction matters because:
+
+- Mutation requires T3 approval flow. An agent that can write but has no T3 handling in its failure model will either block silently or execute without user awareness.
+- Read-only agents gain security value from `disallowedTools`, not just from not listing Write/Edit. A later frontmatter edit that adds a tool to a read-only agent should be caught by explicit disallow, not by convention.
+
+**D1=yes implications:**
+- `permissionMode: acceptEdits` in frontmatter
+- `Write`, `Edit` listed in tools
+- Failure handling covers T3 block + APPROVAL_REQUEST flow
+- Output type is "Realization Package" (contains code/config changes)
+
+**D1=no implications:**
+- `disallowedTools: [Write, Edit, NotebookEdit]`
+- No T3 surface in failure handling
+- Output type is "Diagnostic Report" or "Findings Report"
+
+### D2: Does the agent delegate to other agents?
+
+Specialist agents are almost always terminal. "Delegation" here means the agent dispatches other agents (uses the Agent tool mid-task). Most specialists do not -- they surface CANNOT DO items back to the orchestrator, which handles routing.
+
+**D2=yes implications (rare):**
+- `Agent` in tools list
+- A delegation table in the body describing which agents it dispatches and under what conditions
+
+**D2=no implications (standard):**
+- No `Agent` in tools (or `Agent` explicitly disallowed)
+- CANNOT DO -> DELEGATE table is for the orchestrator's reference, not for the agent to act on directly
+
+### D3: Does the agent enter the orchestrator's automatic routing?
+
+Almost all specialists do. The exception would be a utility agent that is only dispatched explicitly, never via intent routing.
+
+**D3=yes implications:**
+- Description field written as triggering conditions (see Step 5 in SKILL.md)
+- Surface signals proposed for `surface-routing.json`
+- Description must not overlap with signals of existing agents (check `config/surface-routing.json` before finalizing)
+
+---
+
+## Weight Test per Component
+
+Use this checklist when reviewing a drafted agent. For each component, the test question is: if this section were removed, would the agent behave differently in a realistic scenario?
+
+### Identity weight test
+
+| What you wrote | Does it pass? | Why |
+|---|---|---|
+| "You are a specialist in Terraform." | No | Baseline -- the LLM already knows what Terraform specialists do. |
+| "You are a senior Terraform architect. You manage the lifecycle by working primarily with the declarative config in the repository. You never query live cloud resources directly." | Yes | The constraint ("never query live cloud") and the orientation ("declarative config, not live state") are not the LLM's default. They redirect behavior. |
+
+**Fix:** Add the constraint or orientation that distinguishes this agent from a generic expert. The identity earns its place by narrowing the action space.
+
+### Scope weight test
+
+| What you wrote | Does it pass? | Why |
+|---|---|---|
+| "CANNOT DO: cloud infrastructure → terraform-architect" | Weak | Too broad. The agent will still touch cloud config when it seems "close enough." |
+| "If the resource type is managed by IaC, creating it belongs to terraform-architect even if you need it as a prerequisite for your task." | Yes | Names the decision moment. Agent knows to stop at "I need this resource created" rather than proceeding. |
+
+**Fix:** Identify the specific moment the agent would rationalize crossing the boundary, and make that moment explicit.
+
+### Domain Errors weight test
+
+| What you wrote | Does it pass? | Why |
+|---|---|---|
+| `terraform init fails → Check credentials` | Marginal | "Check credentials" is the default. Passes only if the agent would normally do something worse. |
+| `Plan shows unexpected destroys → HALT -- report, require explicit confirmation` | Yes | "HALT" is not the default. The agent would normally continue to apply. |
+
+**Fix:** For each error row, ask what a naive agent would do. If the row's action is identical to the default, it adds no weight.
+
+### Output type weight test
+
+An output type declaration passes if it excludes a hybrid the agent would otherwise produce. "Your output is code or a report -- never both" prevents the agent from writing files *and* returning a summary in the same turn -- a pattern that creates ambiguity about what was done. If the output type only names what the agent always produces anyway, it is decorative.
+
+---
+
+## Frontmatter Field Reference
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `name` | string | Yes | kebab-case; matches file name |
+| `description` | string | Yes | Triggering conditions only -- what makes the orchestrator dispatch this agent |
+| `tools` | list | Yes | Only what the domain actually uses; omitting is better than bloating |
+| `model` | string | Yes | `inherit` for most; `sonnet` if the agent needs a specific model pinned |
+| `permissionMode` | string | D1=yes | `acceptEdits` -- required for agents that write files |
+| `disallowedTools` | list | D1=no | Include when read-only enforcement matters beyond convention |
+| `maxTurns` | int | Recommended | 40 for most specialists; 50+ for agents with complex investigation phases |
+| `skills` | list | Yes | `agent-protocol` always first, `security-tiers` always second |
+| `color` | string | Optional | Hex or color name for visual routing distinction |
+
+---
+
+## Systemic Files the Agent Creation Touches
+
+This skill guides thinking about each file, but gaia-system (the invoking agent) applies the writes.
+
+| File | What changes | Who writes it |
+|------|--------------|---------------|
+| `.claude/agents/<name>.md` | New agent definition | gaia-system |
+| `config/surface-routing.json` | New surface entry with signals | gaia-system |
+| `.claude/skills/README.md` | Agent assignment matrix (if agent gets new skills) | gaia-system |
+| `agents/README.md` | New agent in the roster | gaia-system |
+
+The skill does not modify any of these files directly.

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
+  |- APPROVAL_REQUEST    -> 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` |
+| `APPROVAL_REQUEST` | 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 APPROVAL_REQUEST splits on approval_id:** Hook-blocked T3 operations carry a pending
+grant that requires the structured approval flow (exact content, rollback, risk).
+Plan-first APPROVAL_REQUEST 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/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