@jaguilar87/gaia 5.0.0-rc1

package/skills/execution/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: execution
+description: Use when the user has approved a T3 operation and execution is about to begin
+metadata:
+  user-invocable: false
+  type: discipline
+---
+
+# Execution
+
+```
+Commands finishing is not success.
+Verification criteria passing is success.
+```
+
+## Mental Model
+
+A command can exit 0 and leave the system in a broken state.
+`terraform apply` can succeed while creating a misconfigured resource.
+`kubectl apply` can succeed while a pod crash-loops. The only evidence
+that matters is verification against the criteria from your plan —
+not the exit code, not the absence of errors.
+
+## Pre-Execution Checklist
+
+Before executing an approved operation:
+
+- [ ] Grant is active — the hook activated the nonce via `APPROVE:<nonce>` user approval
+- [ ] Current state captured — without a rollback baseline, partial failure is unrecoverable
+- [ ] Plan still valid — state drifts between planning and execution; re-run dry-run if stale
+- [ ] No interactive prompts — agent sessions cannot provide stdin; commands that prompt will hang
+
+If a check fails → `BLOCKED` with which check and why.
+
+## Precondition Verification
+
+Before executing any approved command, verify that the preconditions for success still hold. Use domain knowledge to determine what to check -- this is not a lookup table, it is a judgment call.
+
+The world changes between approval and execution. A command approved 5 minutes ago may fail because the environment moved. Checking first avoids a wasted failure cycle.
+
+**Principle**: If the command depends on external state, verify that state before executing.
+
+**Recovery**: If a precondition fails and the fix is local (pull --rebase, state refresh, resource re-fetch), attempt it ONCE, then retry the original command. If recovery also fails, report the situation -- do not loop.
+
+**Boundary**: Recovery actions must only modify LOCAL state. Never attempt remote-mutating recovery (force push, remote delete, state import) without explicit user approval.
+
+## Environment Drift Detection
+
+When the pending file includes an `environment` snapshot (captured when the command was originally blocked), compare current state against it before executing.
+
+If drift is detected (e.g., remote HEAD has moved, resource version changed), surface the drift to the user before proceeding. The user decides whether to continue or abort.
+
+When no snapshot is available, verify observable state regardless -- the absence of a snapshot does not exempt the agent from precondition checks.
+
+## Execution Protocol
+
+1. Run each step separately — verify exit code before next
+2. On failure — classify: recoverable (`IN_PROGRESS`) or not (`BLOCKED`)
+3. After all steps — run Verification Criteria from the plan
+
+## Error Reporting
+
+```
+Error Type: [Transient | Validation | Permission | State conflict]
+Error Message: [exact output]
+Rollback Status: [what needs rollback if partial]
+```
+
+## Rollback
+
+Know your rollback path BEFORE executing. This varies by domain:
+your domain skill defines the specific rollback strategy.
+
+## Traps
+
+| If you're thinking... | The reality is... |
+|---|---|
+| "The plan just ran, no drift possible" | State can change between planning and execution |
+| "Dry-run passed during planning" | Stale dry-run ≠ current state — re-run |
+| "All commands exited 0, I'm done" | Exit 0 ≠ desired state — run verification criteria |
+| "It's only dev, fewer checks needed" | Irreversibility is irreversibility regardless of env |
+| "Preconditions held during planning" | State changes between approval and execution -- verify again |
+| "No environment snapshot, no drift check" | Verify observable state regardless of whether a snapshot exists |
+| "Half the bundle ran, I can finish after a SendMessage resume" | `mode` dies on resume; if the remaining steps touch `.claude/` writes, CC native re-blocks. Emit BLOCKED, let orchestrator re-dispatch fresh with the same mode. |
+
+## Bundled Multi-Step Execution on Protected Paths
+
+When the approved operation is a **bundle** of steps on `.claude/` paths (e.g., mv directory + 4 Edits across `.claude/project-context/`), execute every step in the SAME turn the dispatch started. Splitting the bundle across dispatch + SendMessage resume fails because `mode` is per-dispatch and does not survive a SendMessage resume -- CC native re-blocks the later Edits in `default` mode.
+
+If a hook blocks a step mid-bundle, emit BLOCKED and stop. Do NOT emit APPROVAL_REQUEST mid-bundle hoping to continue after resume. The orchestrator's correct recovery is a fresh dispatch (same mode, bundle re-packed) after any required approval, not a SendMessage back into the same subagent.
+
+## Anti-Patterns
+
+- **COMPLETE without verification** — the most common failure mode; exit 0 is not evidence
+- **Execute on approximate approval** — "user approved something like this" does not activate the grant; the hook checks exact nonces
+- **Mutate without a rollback path** — if you cannot describe how to undo it, partial failure becomes permanent damage
+- **Skipping precondition verification because the user already approved** — approval reflects state at approval time; state may have changed
+- **Looping on failed recovery instead of reporting after one attempt** — attempt recovery once, then report; do not retry in a loop
+- **Splitting a `.claude/` bundle across a SendMessage resume** — `mode` is per-dispatch; the resume runs in `default` and CC native re-blocks the remaining steps

package/skills/fast-queries/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: fast-queries
+description: Use when diagnosing an issue, checking system health, or validating infrastructure state before starting a task
+metadata:
+  user-invocable: false
+  type: reference
+---
+
+# Fast-Query Diagnostics
+
+A 10-second triage run surfaces 80% of issues that would otherwise take
+minutes of manual commands to discover. Running triage first means your
+investigation starts from known state, not assumptions about what is healthy.
+
+## Available Scripts
+
+Run from project root. Use absolute path if calling from a different directory.
+
+| Script | Command | Duration |
+|--------|---------|----------|
+| **All systems** | `bash .claude/tools/fast-queries/run_triage.sh [domain]` | 8-15s |
+| **GitOps/K8s** | `bash .claude/tools/fast-queries/gitops/quicktriage_gitops_operator.sh [ns]` | 2-3s |
+| **Terraform** | `bash .claude/tools/fast-queries/terraform/quicktriage_terraform_architect.sh [dir]` | 3-4s |
+| **AWS** | `bash .claude/tools/fast-queries/cloud/aws/quicktriage_aws_troubleshooter.sh` | 4-5s |
+| **GCP** | `bash .claude/tools/fast-queries/cloud/gcp/quicktriage_gcp_troubleshooter.sh [project]` | 4-5s |
+
+**Domains for triage:** `all`, `gitops`, `terraform`, `cloud`, `appservices`
+
+Use domain-specific scripts when you know the area. Use `all` only for
+general status checks -- it runs every domain and takes longer.
+
+## Exit Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `0` OK | All healthy | Proceed with task |
+| `1` WARNING | Warnings found | Review each; not necessarily blocking |
+| `2` ERROR | Errors found | Report to user, investigate flagged issues before continuing |
+| `3` SCRIPT_ERROR | Script failure | Check tool availability and permissions |
+
+Deep-dive only on flagged issues (exit 1 or 2). Exit 0 means the
+environment is healthy -- spending time re-verifying what triage already
+confirmed wastes investigation budget on non-problems.

package/skills/gaia-compact/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gaia-compact
+description: Use when the user asks to compact the current session -- "compacta", "compact", "oye Gaia compacta", "orquestador compacta", "haz un compact", "compactemos la sesión". Runs /compact with a structured prompt that preserves decisions, components, gaps, file map, and next steps.
+metadata:
+  user-invocable: true
+  type: technique
+---
+
+# Gaia Compact
+
+A raw `/compact` tells the model "summarize everything you remember." What survives that summary is what the model happened to find salient -- which is rarely the same as what the user needs to resume work. This skill replaces that default with a preservation contract: the six categories below are what matter for continuity, and the compact prompt forces the model to retain them with high fidelity.
+
+## When this skill fires
+
+Load this skill when the user asks the orchestrator to compact the session. Spanish and English both trigger: "compacta", "orquestador compacta", "oye Gaia compacta", "haz un compact", "compact the session", "compactemos".
+
+## What the orchestrator does
+
+The Skill tool cannot invoke `/compact` directly -- built-in slash commands are not reachable through Skill. The orchestrator reads this skill, builds the combined prompt below, and then invokes `/compact <combined_prompt>` itself as its next action.
+
+## Process
+
+1. **Extract any extra preservation instructions** the user gave alongside the compact request. Examples:
+   - "compacta pero preserva el estado del DB schema"
+   - "compacta y no olvides la decisión sobre Tailscale"
+   - "compact keeping the failing test output"
+
+   If the user gave no extra instructions, `$ARGUMENTS` is empty and the base prompt is used as-is.
+
+2. **Build the combined prompt** by concatenating the base preservation prompt with any extra instructions:
+
+   ```
+   <BASE_PROMPT>
+
+   Additional preservation instructions from this request:
+   $ARGUMENTS
+   ```
+
+   If `$ARGUMENTS` is empty, omit the "Additional preservation instructions" block entirely -- do not leave a dangling header.
+
+3. **Before invoking /compact, verify persistence-critical work**. If any of the following are in-flight and NOT yet written to disk, surface them to the user and ask whether to persist first:
+   - Unsaved changes to `MEMORY.md` or memory documents under `.claude/projects/*/memory/`
+   - Brief or plan files under `.claude/project-context/briefs/` that were drafted but not written
+   - Evidence files (`T{N}.txt`, `AC-N.*`) from a dispatch whose verification has not been persisted
+   - Uncommitted git changes the user asked to commit
+
+   Compaction is lossy by design. Anything only held in the model's context window is gone after `/compact`.
+
+4. **Invoke /compact with the combined prompt**. The orchestrator runs this as its own action -- the skill does not and cannot execute it.
+
+5. **After /compact returns**, briefly confirm to the user what was preserved (the six categories plus any extra instructions they gave).
+
+## Base preservation prompt
+
+This is the literal text the orchestrator prepends:
+
+```
+Preserve the following with high fidelity:
+1. DECISIONS: Every architectural decision made, including the rationale and alternatives rejected.
+2. COMPONENTS: Agent roster with responsibilities, skill assignments, and known gaps identified.
+3. OPEN ITEMS: All pending briefs, open questions, and identified gaps -- with their current status.
+4. FILE MAP: Absolute paths of every file read, created, or modified, with one-line description.
+5. KEY FINDINGS: Bugs, security issues, or design problems surfaced during investigation.
+6. NEXT STEPS: The exact next action agreed upon before this compact.
+Compress tool outputs, file contents, and intermediate reasoning. Retain conclusions, not process.
+```
+
+## Anti-patterns
+
+- **Compacting without the preservation prompt** -- defaults to a generic summary that drops file paths, approval_ids, and nonces; resuming becomes guesswork.
+- **Compacting while a T3 approval is in flight** -- the approval_id and nonce live in context; after `/compact` the grant activation can lose its anchor. Resolve approvals first, then compact.
+- **Ignoring user-provided preservation hints** -- if the user says "preserva el DB schema", appending that to `$ARGUMENTS` is the whole point; dropping it makes the skill a fancy wrapper for the default.
+- **Compacting with unsaved memory or brief drafts in context** -- these are not recoverable from `/compact` output; warn the user before running.
+- **Summarizing what was preserved in vague terms** -- after compacting, name the six categories explicitly so the user can spot a missing one immediately.

package/skills/gaia-patterns/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: gaia-patterns
+description: Use when building or modifying gaia-ops components -- agents, skills, hooks, CLI tools, commands, or routing config
+metadata:
+  user-invocable: false
+  type: domain
+---
+
+# Gaia-Ops Code Patterns
+
+Construction patterns for building Gaia components. Every component type follows a discoverable pattern -- read 2-3 existing examples before creating a new one. For the full component inventory, see `reference.md`.
+
+## Prompt -> Result Flow
+
+```
+1. User sends prompt
+   |
+2. Orchestrator routes to agent (surface-routing.json)
+   |
+3. Pre-Tool Hook (pre_tool_use.py)
+   +-- Inject project-context.json
+   +-- Load skills from frontmatter
+   +-- Validate permissions
+   |
+4. Agent executes -> returns json:contract
+   |
+5. Post-Tool Hook -> audit + metrics
+   |
+6. Orchestrator processes plan_status (REVIEW / NEEDS_INPUT / COMPLETE)
+```
+
+## Hook Patterns
+
+Entry points (`hooks/*.py`) are stdin/stdout glue only. All logic lives in the adapter layer.
+
+```
+hooks/pre_tool_use.py          -- reads stdin, calls adapter, writes stdout
+  -> adapters/claude_code.py   -- parses event, dispatches to modules
+    -> modules/security/*      -- blocked_commands, mutative_verbs
+    -> modules/context/*       -- context_injector, contracts_loader
+    -> modules/agents/*        -- contract_validator, skill_injection
+```
+
+**To add a new module:** Write module in `modules/<package>/`, import and call it from the relevant adapter method. Modules receive parsed context and return results; they never read stdin or write stdout.
+
+**To add a new hook entry point:** Create `hooks/<event_name>.py`, register it in `build/<plugin>.manifest.json`, add matchers. The entry point reads stdin JSON, calls the adapter, and prints the response.
+
+## Agent Patterns
+
+```yaml
+---
+name: agent-name
+description: Routing label -- triggers when orchestrator sees matching intent
+tools: Read, Edit, Write, Glob, Grep, Bash  # restrict per domain
+model: inherit
+permissionMode: acceptEdits  # required for most agents; omit only for orchestrator and read-only agents
+skills:
+  - agent-protocol        # always first
+  - security-tiers        # always second
+  - command-execution     # if agent runs commands
+  - domain-skill          # agent's domain patterns
+  - context-updater       # if agent modifies project state
+---
+```
+
+**Identity** (1-2 paragraphs): domain, output format. **Scope**: CAN DO / CANNOT DO -> DELEGATE table. **Domain Errors**: agent-specific errors only.
+
+Agents get instantiated as: identity (.md) + skills (injected from frontmatter) + project-context (filtered by context-contracts.json) + orchestrator request.
+
+## Routing Patterns
+
+`config/surface-routing.json` maps user intent to agents. Each surface has: `intent`, `primary_agent`, `adjacent_surfaces`, and `signals` (high/medium confidence keyword patterns).
+
+**To add a surface:** Add entry to `surfaces` with intent + primary_agent + signals. Update L1 routing tests.
+**To add a signal:** Add keyword patterns to the appropriate confidence level in an existing surface.
+
+## CLI Tool Patterns
+
+CLI tools live in `bin/` and are registered in `package.json` `bin` field. Pattern: parse args, resolve paths (follow symlinks to source), run checks, exit with code. `gaia-doctor` is the diagnostic model -- read it first.
+
+## Command Patterns
+
+Slash commands live in `commands/<name>.md` -- markdown files that instruct the orchestrator on `/<name>`. To add: create the `.md`, add to `build/<plugin>.manifest.json`.
+
+## Documentation Drift Awareness
+
+When you modify any Gaia component (hook, skill, agent definition, routing config, security rule), check if existing reference docs describe that component's behavior. If drift exists, report it via `cross_layer_impacts` in your json:contract. The orchestrator then decides whether to dispatch a documentation update task.
+
+**Do NOT update docs yourself** -- your job is to flag the drift and let the orchestrator choose the next action.
+
+**Examples of drift to flag:**
+- Changed `_is_protected()` paths in `adapters/claude_code.py` → check `security-tiers/SKILL.md` for path documentation
+- Added a new agent definition → check `gaia-patterns/reference.md` for agents table
+- Modified hook enforcement logic → check `security-tiers` and `agent-protocol` references
+- When adding or modifying files in agents/, skills/, hooks/, commands/, config/, bin/, tests/, build/, templates/ or the repo root, load Skill('readme-writing') to update the relevant README.md
+
+**Format:** In `cross_layer_impacts`, list the doc file and the behavior change, e.g.:
+```
+"cross_layer_impacts": [
+  "security-tiers/SKILL.md: _is_protected() now excludes .claude/settings.local.json"
+]
+```
+
+## Key Principles
+
+- **Skills teach process. Agents teach identity. Runtime enforces contracts.** Never duplicate across these layers.
+- **Delegation first.** The orchestrator routes; it cannot read files, run commands, or edit code.
+- **Consolidation loop.** For multi-surface work, the orchestrator may dispatch multiple agent rounds, stopping when gaps are no longer actionable.