@jaguilar87/gaia 5.0.0-rc.2

package/skills/pending-approvals/reference.md

@@ -0,0 +1,214 @@
+# Pending Approvals — Reference
+
+Read on-demand when processing approval requests.
+
+## Pending JSON Schema
+
+File: `.claude/cache/approvals/pending-{nonce}.json`
+
+```json
+{
+  "nonce": "8072af8044f0da0571c348041ad2cef6",
+  "session_id": "abc123",
+  "command": "kubectl apply -f manifest.yaml",
+  "danger_verb": "apply",
+  "danger_category": "MUTATIVE",
+  "scope_type": "semantic_signature",
+  "scope_signature": {
+    "base_cmd": "kubectl",
+    "cli_family": "k8s",
+    "verb": "apply",
+    "semantic_tokens": ["kubectl", "apply", "manifest.yaml"],
+    "normalized_flags": ["-f"]
+  },
+  "timestamp": 1775843292.4328,
+  "ttl_minutes": 5,
+  "context": {
+    "scope": "k8s cluster — dev namespace",
+    "rollback": "kubectl delete -f manifest.yaml",
+    "risk": "MEDIUM"
+  }
+}
+```
+
+The `context` field is optional. When absent, derive scope/rollback/risk from `scope_signature` and `danger_category`.
+
+## Nonce Prefix Matching
+
+User references "P-8072af8" → match against nonces starting with "8072af8".
+Minimum 4 characters. If multiple nonces share the same prefix, ask user to be more specific.
+
+## Summary Format (SessionStart injection)
+
+```
+Tienes N aprobaciones pendientes:
+
+P-{nonce[0:8]}  {command}  [{danger_verb}]  hace {age}
+P-{nonce[0:8]}  {command}  [{danger_verb}]  hace {age}
+
+Di "ver P-XXXX" para detalles o "aprobar P-XXXX" para ejecutar.
+```
+
+## Detail View Format
+
+```
+P-{nonce[0:8]} — Detalle
+
+COMANDO:    {command}
+OPERACION:  {danger_verb} en {base_cmd}
+CATEGORIA:  {danger_category}
+SCOPE:      {scope}
+ROLLBACK:   {rollback}
+CREADO:     {timestamp as readable datetime}
+```
+
+## AskUserQuestion Template
+
+```python
+AskUserQuestion(
+    question=(
+        "APPROVAL REQUIRED\n\n"
+        f"OPERACION: {danger_verb} on {base_cmd}\n"
+        f"COMANDO:   {command}\n"       # verbatim, never paraphrased
+        f"SCOPE:     {scope}\n"
+        f"RIESGO:    {danger_category}\n"
+        f"ROLLBACK:  {rollback}"
+    ),
+    options=[f"Approve -- {danger_verb} {base_cmd} {target} [P-{nonce[:8]}]", "Reject"]
+    # Option label MUST name the specific action, e.g.:
+    # "Approve -- kubectl apply -f manifest.yaml [P-8072af80]"
+    # NEVER: "Approve", "Approve -- proceed", "Approve -- aplicar cambios"
+)
+```
+
+The PostToolUse hook checks `answer.lower().startswith("approve")` to activate the grant.
+"Reject" (or any non-"Approve" answer) does NOT activate the grant.
+
+## Post-Approval Dispatch Template
+
+After AskUserQuestion returns "Approve", check whether the pending file belongs to the current session. Both dispatch paths use the same smart prompt structure -- the only difference is whether the nonce is included.
+
+### Dispatch prompt structure
+
+The dispatch prompt tells the agent three things: what to run, where to run it, and how to handle failure. This replaces fire-and-forget dispatch, which reports failure without attempting recovery.
+
+```
+Ejecuta este comando aprobado por el usuario. No requiere confirmacion adicional.
+{Nonce: {nonce}  -- only for same-session dispatch}
+Comando: {command}
+Directorio: {cwd}
+
+PREFLIGHT: Before executing, verify preconditions still hold.
+- For git push: fetch and check if the local branch is ahead of remote.
+- For kubectl/helm apply: confirm the target resource exists and is not mid-rollout.
+- For terraform apply: run a quick plan to confirm no unexpected drift.
+- General: if the command depends on state that may have changed, check that state first.
+If a precondition fails, report what changed and do NOT execute.
+
+RECOVERY: If the command fails with a recoverable error, attempt ONE standard local recovery, then retry.
+- git push (non-fast-forward): pull --rebase, then retry push.
+- terraform apply (state conflict): refresh state, then retry apply.
+- kubectl apply (conflict): re-fetch the resource, re-apply.
+- General: if the error message suggests a local fix (rebase, refresh, retry), do that fix ONCE.
+Do NOT attempt remote-mutating recovery (force push, remote delete, taint, import).
+Do NOT retry more than once -- if recovery + retry fails, report the error.
+```
+
+The `cwd` field may be present in the pending JSON. When present, include it in the dispatch as `Directorio:`. When absent, omit the line.
+
+### Dispatch `mode` for post-approval execution
+
+The Gaia grant activates on the blocked command signature -- that covers the Gaia hook, but CC native is a separate gate. Pick `mode` based on the command target:
+
+| Approved command targets... | mode | session | Why |
+|-----------------------------|------|---------|-----|
+| Normal paths (src/, infra/, /tmp/) | `default` | foreground | CC native does not protect these; no mode needed |
+| `.claude/` writes only (Edit/Write on skills, agents, briefs) | `acceptEdits` | foreground | CC native prompts on `.claude/` writes; `acceptEdits` satisfies it |
+| Bash mutativo sobre `.claude/` (rm, mv, mkdir) | `bypassPermissions` | foreground | CC native intercepts `.claude/` destructive ops regardless of verb; bypass satisfies it |
+| Bundle: Bash on `.claude/` + Edits on `.claude/` | `bypassPermissions` | foreground | The bundle needs one mode that covers both layers; pack all steps in one dispatch turn |
+
+The dispatch is single-turn and cannot split: if the bundle emits APPROVAL_REQUEST mid-execution, the orchestrator must re-dispatch fresh with the same mode, not SendMessage resume -- mode does not survive resume.
+
+### Same-session dispatch
+
+When `pending.session_id == CLAUDE_SESSION_ID` -- pass the nonce:
+
+1. Build the dispatch prompt with nonce, command, and cwd (if available)
+2. Dispatch the one-shot agent
+3. The hook finds the nonce, activates the grant, and allows the T3 operation through
+
+### Cross-session dispatch
+
+When `pending.session_id != CLAUDE_SESSION_ID` -- the nonce is stale:
+
+1. The PostToolUse hook will have already activated the grant under the current session
+2. Build the dispatch prompt with command and cwd (if available), no nonce
+3. Dispatch the one-shot agent
+4. The hook finds the pre-activated grant (by command signature) and allows the T3 operation through
+
+### Recovery scope guardrail
+
+Recovery actions must only modify LOCAL state. The agent should never attempt:
+- `git push --force` or `git push --force-with-lease` (remote-mutating)
+- `terraform state rm` or `terraform import` (state-mutating beyond refresh)
+- `kubectl delete` followed by re-create (destructive recovery)
+- Any action that would require its own T3 approval
+
+If the only path forward requires remote mutation, the agent reports the failure and lets the user decide.
+
+## Complete Flow Example
+
+### Same-session path
+
+```
+SessionStart
+  → scans .claude/cache/approvals/pending-*.json
+  → injects summary into additionalContext
+
+User sees:
+  "Tienes 1 aprobación pendiente:
+   P-8072af8  kubectl apply -f manifest.yaml  [apply]  hace 2 min"
+
+User: "ver P-8072af8"
+  → orchestrator reads pending-8072af8044f0da0571c348041ad2cef6.json
+  → presents detail view
+
+User: "aprobar P-8072af8"
+  → orchestrator calls AskUserQuestion with all 5 fields visible
+  → user selects "Approve -- kubectl apply -f manifest.yaml [P-8072af80]"
+  → PostToolUse hook extracts nonce from label, activates grant for nonce 8072af8044f0da0571c348041ad2cef6
+  → orchestrator dispatches one-shot agent with nonce + command
+  → agent runs command; hook validates nonce and allows T3 through
+  → agent returns COMPLETE; pending file deleted
+```
+
+### Cross-session path
+
+```
+SessionStart (new session)
+  → scans .claude/cache/approvals/pending-*.json
+  → pending-8072af8044f0da0571c348041ad2cef6.json has session_id = "prior-session"
+  → scanner annotates entry with [session anterior]
+  → injects summary into additionalContext
+
+User sees:
+  "Tienes 1 aprobación pendiente:
+   P-8072af8  kubectl apply -f manifest.yaml  [apply]  hace 5 min  [session anterior]"
+
+User: "aprobar P-8072af8"
+  → orchestrator calls AskUserQuestion with all 5 fields visible
+  → user selects "Approve -- kubectl apply -f manifest.yaml [P-8072af80]"
+  → orchestrator detects pending.session_id != CLAUDE_SESSION_ID
+  → calls activate_cross_session_pending(pending_data) — grant created in current session
+  → deletes old pending file
+  → dispatches one-shot agent with command only (no nonce)
+  → agent runs command; hook finds pre-activated grant and allows T3 through
+  → agent returns COMPLETE
+```
+
+## Pending File Location
+
+All pending files: `.claude/cache/approvals/pending-{nonce}.json`
+Index file (per-session): `.claude/cache/approvals/pending-index-{session_id}.json`
+
+Use glob `pending-*.json` to find all pending files. Skip files starting with `pending-index-`.

package/skills/readme-writing/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: readme-writing
+description: Use when writing or updating a README for a Gaia component folder (agents/, skills/, hooks/, commands/, config/, bin/, tests/, build/, templates/, or the repo root)
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# README Writing
+
+A folder README is not a table of contents. It is the mental model a developer or agent needs before touching anything in that folder. A README that only lists files is worse than none -- it creates the impression the folder is understood when it is not.
+
+Gaia is event-driven. Every component has a trigger: a hook fires, a skill is injected, a command is dispatched, a config file is loaded. A README that does not explain WHEN and HOW a component activates leaves the reader guessing the most important thing.
+
+## Step 1: Choose your target
+
+Write or update a README when:
+- A new folder is created (agents/, skills/<name>/, hooks/, etc.)
+- You add a file that changes what the folder does or when it activates
+- A drift report in `cross_layer_impacts` flags a README as stale
+
+## Step 2: Write the 5 sections in order
+
+Every README uses this structure. Order is not optional -- a reader skimming top-to-bottom should understand activation before they see a file tree.
+
+**Section 1: Intro narrative** (2-4 paragraphs, no bullets, conversational)
+- One sentence on what lives here
+- Why this folder exists separately (the conceptual contract)
+- How to think about this folder (mental model or analogy)
+- Who touches it: developer, agent at runtime, CI, admin
+
+**Section 2: When activated** (the core -- do not skip)
+- The concrete trigger: what event, condition, or code path fires this
+- ASCII diagram if more than 2 steps chain together
+- Step-by-step list as complement when the diagram is not enough
+- What happens if this folder is absent or broken
+
+**Section 3: What's here** (annotated tree)
+- One-line comment per file or subdirectory
+- Mark generated files so they are not edited by hand
+
+**Section 4: Conventions** (concrete rules, not aspirations)
+- How to name new files
+- What internal structure new files must follow
+- What to update elsewhere when adding something here
+- What validation runs against this folder
+
+**Section 5: See also** (relative links with reason)
+- Adjacent components with a one-line reason per link
+
+## Step 3: Write the activation section for judgment
+
+The activation section fails when it describes intent ("skills are injected at startup") without describing mechanism ("the pre_tool_use hook reads `skills:` from agent frontmatter, then calls `skill_injection.py`, which reads each SKILL.md and prepends it to the agent context").
+
+Concrete mechanism is the test. If the description would be true for any event-driven system, it is not concrete enough.
+
+## Step 4: Integration points
+
+**With skill-creation:** When completing a new skill, update the `skills/` README to reflect the new entry. This is the last step of the skill-creation workflow, not optional cleanup.
+
+**With gaia-patterns (Documentation Drift Awareness):** When an agent adds a file to `agents/`, `skills/`, `hooks/`, or any top-level folder, it must include the relevant README in `cross_layer_impacts` if the README no longer accurately describes the folder. The orchestrator dispatches a readme-writing task from that signal. The agent that added the file does NOT update the README itself -- it reports drift and stops.
+
+**With test_directory_structure.py:** The system test verifies README existence for all key folders. Adding a new top-level folder without a README will cause a test failure. See `tests/system/test_directory_structure.py`.
+
+## Anti-Patterns
+
+- **Activation section describes intent, not mechanism** -- "agents use skills" is intent; "pre_tool_use.py reads frontmatter and calls skill_injection.py" is mechanism.
+- **File tree without comments** -- a bare tree adds no value over `ls`; every entry needs a reason.
+- **Conventions that are aspirational** -- "files should be well-named" is not a convention; "skill folders use kebab-case matching the `name:` field in frontmatter" is.
+- **See also without reasons** -- a link list without context shifts the burden to the reader.
+- **Updating README inline during feature work** -- drift reporting exists so README updates happen as deliberate tasks, not rushed afterthoughts mid-feature.

package/skills/readme-writing/reference.md

@@ -0,0 +1,188 @@
+# README Writing Reference
+
+Extended examples for the readme-writing skill. Load this file when you need a filled-in template to work from.
+
+## Canonical filled example: skills/
+
+The example below is the README for the `skills/` top-level folder. Use it as the gold standard for voice, section depth, and activation detail.
+
+---
+
+```markdown
+# Skills
+
+Las skills son conocimiento procedimental inyectado en los agentes. No son código que se ejecuta -- son texto que el agente recibe y sigue. Piénsalas como el manual de procedimientos que le das a un contractor: le dices cómo clasificar riesgos, cómo reportar resultados, cómo ejecutar comandos. El agente trae su identidad (qué es, qué puede hacer); la skill trae el proceso (cómo lo hace).
+
+Esta carpeta existe separada de `agents/` porque el mismo procedimiento aplica a múltiples agentes. `security-tiers` la siguen seis agentes distintos. Si esa lógica viviera inline en cada `.md`, tendríamos seis copias divergiendo. Una skill es la SSOT del proceso.
+
+Mental model: una skill es como un módulo importable, pero para texto. El agente la "importa" en startup (si está en su frontmatter) o la "requiere" en runtime (si la lee bajo demanda con el Read tool).
+
+Las skills las toca el developer cuando crea o refina procedimientos, y el agente en runtime cuando las lee on-demand. El hook layer nunca las lee directamente.
+
+---
+
+## Cuándo se activa
+
+Hay dos rutas de activación:
+
+**RUTA 1 -- Startup injection (frontmatter)**
+
+```
+Agent .md frontmatter
+  skills:
+    - agent-protocol
+    - security-tiers
+          |
+          v
+pre_tool_use.py fires on agent start
+          |
+          v
+adapters/claude_code.py -> modules/agents/skill_injection.py
+          |
+          v
+Reads each SKILL.md from disk
+Prepends content to agent system prompt
+          |
+          v
+Agent receives process knowledge before first tool call
+```
+
+Skills listed in frontmatter load unconditionally on every call. Keep this list short (< 5 skills, < 100 lines each) -- everything here costs tokens on every invocation.
+
+**RUTA 2 -- On-demand (workflow skills)**
+
+```
+Agent encounters task that needs a process
+          |
+          v
+Agent reads SKILL.md directly via Read tool
+          |
+          v
+Agent follows the process inline
+```
+
+Workflow skills (approval, execution, investigation) are read on-demand because they are only needed for specific task types. Listing them in frontmatter would waste tokens on every agent call.
+
+**What breaks if skills/ is missing or corrupted:**
+- Startup-injected skills: agent proceeds without process knowledge, silently. No error. Wrong behavior.
+- On-demand skills: agent gets a file-not-found error and must improvise or halt. Improvising produces inconsistent results across agents.
+
+---
+
+## Qué hay aquí
+
+```
+skills/
+├── README.md                  <- este archivo
+├── reference.md               <- índice de skills con tipo y descripción
+├── agent-protocol/
+│   ├── SKILL.md               <- protocol: response contract, state machine
+│   └── examples.md            <- filled json:contract examples
+├── security-tiers/
+│   ├── SKILL.md               <- reference: T0-T3 tier definitions
+│   └── reference.md           <- cloud CLI examples, conditional commands
+├── skill-creation/
+│   ├── SKILL.md               <- technique: how to build a skill
+│   └── reference.md           <- tone guide by skill type
+├── command-execution/
+│   ├── SKILL.md               <- discipline: no pipes, one command per step
+│   └── reference.md           <- cloud CLI mutation examples
+└── ... (one folder per skill)
+```
+
+---
+
+## Convenciones
+
+- Folder name = `name:` field in SKILL.md frontmatter, kebab-case
+- Every skill folder contains at minimum `SKILL.md`
+- `SKILL.md` must have valid frontmatter: `name:`, `description:`, `metadata.type:`
+- `description:` contains triggering conditions only -- not process summary
+- `SKILL.md` < 150 lines; heavy content goes to `reference.md`
+- After creating a new skill, update this README's "Qué hay aquí" section
+- After creating a new skill, update `skills/reference.md` index table
+
+Validation: `tests/system/test_directory_structure.py` verifies all skill folders have a `SKILL.md`.
+
+---
+
+## Ver también
+
+- `agents/` -- agent definitions that consume skills via frontmatter
+- `hooks/modules/agents/skill_injection.py` -- runtime that reads and injects skill content
+- `skills/skill-creation/SKILL.md` -- how to build a new skill (type selection, line budget, description rules)
+- `tests/system/test_directory_structure.py` -- verifies README and SKILL.md existence
+```
+
+---
+
+## Template (blank)
+
+Copy this when writing a README from scratch. Fill every section -- do not delete sections that seem inapplicable, as the absence of a section signals the folder was not fully analyzed.
+
+```markdown
+# <Folder Name>
+
+<Intro paragraph 1: one sentence on what lives here>
+
+<Intro paragraph 2: why this folder exists separately -- the conceptual contract>
+
+<Intro paragraph 3: how to think about this folder -- mental model or analogy>
+
+<Intro paragraph 4: who touches it: developer / agent at runtime / CI / admin>
+
+---
+
+## Cuándo se activa
+
+<Concrete trigger: what event, condition, or code path fires this>
+
+```
+<ASCII diagram if > 2 steps chain>
+```
+
+<Step-by-step list as complement>
+
+<What breaks if this folder is absent or broken>
+
+---
+
+## Qué hay aquí
+
+```
+<folder>/
+├── <file>      <- <one-line comment>
+└── <subdir>/   <- <one-line comment>
+```
+
+---
+
+## Convenciones
+
+- <Naming rule for new files>
+- <Required internal structure>
+- <What to update elsewhere when adding something here>
+- <Validation that runs against this folder>
+
+---
+
+## Ver también
+
+- `<path>` -- <one-line reason>
+```
+
+---
+
+## Section depth guide by folder type
+
+| Folder | Activation complexity | Typical diagram? |
+|--------|----------------------|-----------------|
+| `hooks/` | High -- event-driven, multi-module | Yes |
+| `agents/` | Medium -- routing dispatch | Optional |
+| `skills/` | Medium -- two injection paths | Yes |
+| `commands/` | Low -- user-invoked slash commands | No |
+| `config/` | Low -- read at startup or on-demand | No |
+| `bin/` | Low -- CLI tools, user-invoked | No |
+| `tests/` | Low -- run by CI or developer | No |
+| `build/` | Medium -- triggered by npm run build | Optional |
+| `templates/` | Low -- read by build scripts | No |

package/skills/reference.md

@@ -0,0 +1,135 @@
+# Agent Reference
+
+> **Legacy reference.** Current patterns and the full component inventory are in `gaia-patterns/reference.md`. This file is retained for historical context and the agent template below.
+
+## Agent Template
+
+```markdown
+---
+name: agent-name
+description: One-line description of what this agent does
+tools: Tool1, Tool2, Tool3
+model: inherit
+permissionMode: acceptEdits  # standard for most agents; omit for orchestrator and read-only agents
+skills:
+  - security-tiers
+  - agent-protocol
+  - context-updater
+  - investigation
+  - command-execution
+---
+
+## TL;DR
+
+**Purpose:** [What this agent does]
+**Input:** [What context it needs]
+**Output:** [What it produces]
+**Tier:** [T0-T2 or T0-T3]
+
+For T3 approval/execution workflows, read `.claude/skills/request-approval/SKILL.md` and `.claude/skills/execution/SKILL.md`.
+
+---
+
+## Core Identity
+
+[What makes this agent unique - 2-3 paragraphs max]
+
+### Code-First Protocol
+
+1. **Trust the Contract** - [Key contract field]
+2. **Analyze Before Generating** - Follow `investigation` skill
+3. **Pattern-Aware Generation** - [Domain-specific generation rules]
+4. **Validate** - [Domain-specific validation]
+5. **Output is a Realization Package** - [What the package contains]
+
+---
+
+## 4-Phase Workflow
+
+### Phase 1: Investigation
+Follow `investigation` skill protocol. Then: [domain-specific steps]
+
+### Phase 2: Present
+[What to show user]
+
+### Phase 3: Confirm
+[Approval requirements]
+
+### Phase 4: Execute
+[Execution steps]
+
+---
+
+## Scope
+
+### CAN DO
+- [List capabilities]
+
+### CANNOT DO
+- [List restrictions with delegation targets]
+
+### DELEGATE
+[When to recommend other agents]
+
+---
+
+## Error Handling
+
+| Error | Detection | Recovery |
+|-------|-----------|----------|
+| [error] | [how detected] | [how to recover] |
+```
+
+## Release Checklist
+
+When publishing a new version:
+
+1. Read `package.json` for current version
+2. Review changes (`git log`, CHANGELOG.md)
+3. Determine version bump (patch/minor/major)
+4. Update CHANGELOG.md with changes
+5. Test symlinks work in consuming project:
+   ```bash
+   # In consuming project
+   ls -la .claude/  # Should point to node_modules/@jaguilar87/gaia/
+   ```
+6. Bump version:
+   ```bash
+   npm version [patch|minor|major]
+   ```
+7. Publish:
+   ```bash
+   npm publish --access public
+   ```
+8. Verify:
+   ```bash
+   npm info @jaguilar87/gaia version
+   ```
+
+## Documentation Template
+
+```markdown
+# Component Name
+
+Brief description of what this does and why it exists.
+Written like you're explaining to a colleague.
+
+## Where This Fits
+
+```
+User request → Orchestrator → **This Tool** → Agent receives context
+```
+
+## Quick Start
+
+\`\`\`bash
+python3 tool.py --help
+\`\`\`
+
+## Examples
+
+\`\`\`bash
+python3 tool.py "example input"
+# Output: example output
+\`\`\`
+```