@jaguilar87/gaia 5.0.0-rc.2

package/skills/brief-spec/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: brief-spec
+description: Use when the user wants to create a brief or spec for a feature before planning
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Brief Spec
+
+Conversational brief creation. The orchestrator loads this inline to
+co-create a brief with the user before dispatching to gaia-planner.
+
+## Cuando llegas aquí
+
+El orquestador cargó esta skill porque la conversación entró en Cerrar:
+el usuario y él han acordado varias cosas y es momento de materializarlas.
+No estás aquí porque la petición superó un umbral de tamaño. Estás aquí
+porque hay acuerdos que capturar.
+
+Tu trabajo:
+1. Resumir los acuerdos que ya emergieron en la conversación previa —
+   no re-descubrirlos desde cero.
+2. Preguntar sólo lo que falte para convertir los acuerdos en AC
+   reproducibles (evidence types, surface type).
+3. Escribir el brief y presentarlo al usuario para validar.
+
+## Process
+
+1. **Ask questions** -- Target gaps, not completeness:
+   - **Surface type** (always, before AC): Is this a UI a human uses, an API,
+     or a background job? Determines valid evidence types for the ACs.
+   - What problem does this solve?
+   - What constraints matter? (cloud, performance, security, timeline)
+   - How will you verify each AC yourself? (reproduce steps, not just "it works")
+   - What artifact do you want to review after execution?
+     (log file, screenshot, JSON snapshot, HTTP response, diff)
+   - If this failed silently, what symptom would you look for?
+   - What is explicitly NOT in scope?
+
+   One question per round via AskUserQuestion. Stop when each AC has
+   a declared evidence type and every question above has an answer or
+   an explicit "N/A".
+
+2. **Write brief.md** -- Use the structure below. Write to:
+   `.claude/project-context/briefs/open_{feature-name}/brief.md`
+   where `{feature-name}` is a kebab-case slug.
+
+   **Directory prefix convention:**
+   - `open_` -- draft or ready, no work started yet (this skill always creates with `open_`)
+   - `in-progress_` -- work has begun
+   - `closed_` -- complete, verified, or done
+
+   Transitions between prefixes are done with `gaia plans rename`. This skill
+   only ever creates with `open_`.
+
+## Brief Structure
+
+The frontmatter is the executable source of truth (orchestrator parses it
+with `yaml.safe_load`). The body's `## Acceptance Criteria` section mirrors
+it as a human summary.
+
+```markdown
+---
+status: draft
+surface_type: ui | api | job | cli
+acceptance_criteria:
+  - id: AC-1
+    description: "Login button visible on /login"
+    evidence:
+      type: url
+      shape:
+        method: GET
+        url: http://localhost:3000/login
+        expect:
+          status: 200
+          body_contains: "Sign in"
+    artifact: evidence/AC-1.json
+  - id: AC-2
+    description: "pytest auth suite green"
+    evidence:
+      type: command
+      shape:
+        run: "pytest tests/auth/ -q"
+        expect: "exit 0"
+    artifact: evidence/AC-2.txt
+---
+
+# [Feature Name]
+
+## Objective
+[1-3 sentences: what problem, why now, who benefits]
+
+## Context
+[Project constraints relevant to this feature]
+
+## Approach
+[High-level strategy, not implementation details. 3-5 sentences max]
+
+## Acceptance Criteria
+Human-readable summary. Source of truth lives in frontmatter.
+- AC-1: Login button visible on /login (evidence: url)
+- AC-2: pytest auth suite green (evidence: command)
+
+## Milestones (M/L features only)
+- M1: [name] -- [what is shippable after this]
+- M2: [name] -- [what is shippable after this]
+
+## Out of Scope
+[Explicit boundaries -- what this feature does NOT include]
+```
+
+## Acceptance Criteria Rules
+
+- Every AC has a description (user observation) and an evidence block.
+- Evidence must be reproducible by the user -- not only by the agent.
+- Every AC declares an `artifact` path; the orchestrator persists the
+  verification output there so the user can read it after completion.
+- Vague ACs get pushed back: "Fast means what? Under 200ms p95?"
+- Surface type restricts valid evidence types (see table).
+
+### Evidence Types
+
+The shapes below are frontmatter fragments under `acceptance_criteria:`.
+The body's `## Acceptance Criteria` section mirrors them for human reading;
+the frontmatter is the executable source of truth.
+
+| type | shape | valid surface |
+|------|-------|---------------|
+| `command` | `run: "bash command"; expect: exit_code \| substring` | any |
+| `url` | `method: GET\|POST; url; expect: {status, body_contains}` | ui, api |
+| `playwright` | `url; steps: [...]; assert: "selector visible" \| screenshot` | ui |
+| `artifact` | `path; kind: json\|log\|screenshot; assert: schema \| contains` | any |
+| `metric` | `query; threshold: "p95 < 200ms"` | api, job |
+
+Shape examples (frontmatter fragments):
+
+```yaml
+# command
+evidence:
+  type: command
+  shape:
+    run: "pytest tests/auth/ -q"
+    expect: "exit 0"
+
+# url
+evidence:
+  type: url
+  shape:
+    method: GET
+    url: http://localhost:3000/health
+    expect:
+      status: 200
+      body_contains: '"status":"ok"'
+
+# playwright
+evidence:
+  type: playwright
+  shape:
+    url: http://localhost:3000/login
+    steps:
+      - fill: "#email with user@test.com"
+      - click: "button[type=submit]"
+    assert: "selector [data-testid=dashboard] visible"
+
+# artifact
+evidence:
+  type: artifact
+  shape:
+    path: dist/build-report.json
+    kind: json
+    assert: ".summary.errors == 0"
+
+# metric
+evidence:
+  type: metric
+  shape:
+    query: "curl -s http://localhost:3000/metrics | grep http_p95"
+    threshold: "< 200"
+```
+
+## After Brief
+
+Present the full brief. Ask: "Does this capture what you want?"
+When confirmed, suggest dispatching to gaia-planner to create a plan.

package/skills/command-execution/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: command-execution
+description: Use when executing any bash command, CLI tool, or shell operation
+metadata:
+  user-invocable: false
+  type: discipline
+---
+
+# Command Execution
+
+```
+ONE COMMAND. ONE RESULT. ONE EXIT CODE.
+NO PIPES. NO CHAINS. NO REDIRECTS.
+```
+
+## Mental Model
+
+When you reach for a pipe, you have not looked for the flag yet.
+CLIs have `--format`, `--filter`, `--limit` flags that do what pipes
+do — without hiding exit codes or triggering extra permission prompts.
+
+When you want to chain with `&&`, stop. Run one command, verify the
+exit code, then run the next. Two verified commands beat one fragile chain.
+
+For file I/O, always use Claude Code tools over Bash:
+
+| Bash | Claude Code tool |
+|---|---|
+| `cat`, `head`, `tail` | Read |
+| `echo >`, heredocs | Write |
+| `sed -i`, `awk` | Edit |
+| `grep -r`, `rg` | Grep |
+| `find` | Glob |
+
+## Rules
+
+1. **No pipes** — find the CLI's native flag first.
+2. **One command per step** — no `&&` or `;`.
+3. **Tools over Bash** — for file I/O, always.
+4. **Absolute paths** — agent cwd resets between calls; relative paths break silently.
+5. **Quote variables** — unquoted `${VAR}` with spaces becomes multiple arguments.
+
+## Traps
+
+| If you're thinking... | The reality is... |
+|---|---|
+| "I'll pipe to grep/awk/jq to filter" | Find `--filter` or `--format` flag |
+| "I'll chain with && for efficiency" | Run separately, verify each exit code |
+| "Let me cat/head this file" | Use the Read tool |
+| "Let me cd first, then run" | Use absolute path or `-chdir` |
+| "I need jq to parse JSON" | Use `--format json` at source |
+| "A heredoc is cleanest for multi-line" | Use Write tool. Heredocs fail in batch. |
+| "This pipe is read-only, it's safe" | Pipes still hide exit codes |
+
+**Exception:** `git commit -m "$(cat <<'EOF' ...)"` heredocs are allowed.
+
+## Anti-Patterns
+
+- `kubectl get pods | grep Error` → use `-l` label selectors or `--field-selector`
+- `cd dir && terraform plan` → `terraform -chdir=/absolute/path plan`
+- `cat file | wc -l` → Read tool
+
+The `cloud_pipe_validator.py` hook enforces no-pipes at runtime.
+For mutation rules and cloud CLI examples, see `reference.md`.

package/skills/command-execution/reference.md

@@ -0,0 +1,83 @@
+# Command Execution -- Reference
+
+Read on-demand by infrastructure agents. Not injected automatically.
+
+## Timeouts
+
+| Operation | Timeout |
+|-----------|---------|
+| Read / query | 30s |
+| Validation (lint, fmt) | 30s |
+| Simulation (plan, diff) | 300s |
+| Realization (apply, deploy) | 600s |
+| Flux reconcile | 90s |
+
+Use tool-native timeout flag first (`--request-timeout=30s`), fall back to `timeout 30s <cmd>`. Unreachable -- report and abort.
+
+## Rule 5: Validate Before Mutate
+
+Mutations are irreversible. Always dry-run, then diff, then apply -- each a separate, atomic confirmation.
+
+```bash
+kubectl apply -f manifest.yaml --dry-run=server
+kubectl diff -f manifest.yaml
+kubectl apply -f manifest.yaml
+```
+
+## Rule 6: Files Over Inline Data
+
+Inline JSON/YAML/HCL creates shell quoting fragility. Write to a temp file, reference by path: `helm upgrade app chart -f /tmp/values.yaml` instead of `--set "config={key: value}"`.
+
+## Cloud CLI Examples
+
+### No Pipes (Rule 1)
+
+```bash
+# BAD:  kubectl get pods -o json | jq '.items[0].metadata.name'
+# GOOD: kubectl get pods -o jsonpath='{.items[0].metadata.name}'
+```
+
+### One Command Per Step (Rule 2)
+
+```bash
+# BAD:  terraform init && terraform validate && terraform plan
+# GOOD: run each separately, verify each exit code
+terraform init
+terraform validate
+terraform plan -out=/tmp/tfplan
+```
+
+### Absolute Paths (Rule 4)
+
+```bash
+# BAD:  cd ../../shared/vpc && terraform plan
+# GOOD: terraform plan -chdir="/abs/path/to/terraform/shared/vpc"
+```
+
+## Additional Red Flags (Mutation-Specific)
+
+- *"It won't hang"* -- Timeouts: apply it anyway
+- *"Dry-run passed, I can apply"* -- Rule 5: dry-run, then diff, then apply -- three required steps
+- *"Simple value, I'll inline it"* -- Rule 6: write to temp file first
+
+## Rationalization Table
+
+Every excuse an agent makes for violating a rule, and why it is wrong.
+
+| Rationalization | Reality | Rule |
+|----------------|---------|------|
+| "This command is fast, no timeout needed" | External systems hang for reasons unrelated to command complexity | Timeouts |
+| "It's just to filter output, not a real pipe" | Pipes hide exit codes and split the atomic contract regardless of intent | 1 |
+| "I need `grep` to find what I'm looking for" | `gcloud`/`kubectl` `--filter` finds it natively, without a subprocess | 1 |
+| "These steps always run together, chaining is fine" | Each command needs its own exit code verification -- chaining loses that | 2 |
+| "I need to persist the output for later analysis" | Use the Write tool -- redirects in bash break the hook's structured output | 3 |
+| "It's faster to use `cat` than the Read tool" | Bash subprocesses lose structured output and create unnecessary permission prompts | 3 |
+| "The relative path should work here" | Working directory is not reliable across tool calls -- it will break | 4 |
+| "Dry-run passed so apply is safe" | dry-run and diff are separate validations -- skip either and you miss drift | 5 |
+| "The inline value is simple enough" | Shell quoting breaks at spaces, special chars, and nested quotes -- always | 6 |
+| "This variable definitely won't have spaces" | It will, eventually -- and when it does, it breaks silently and is hard to debug | 7 |
+| "I need to search file contents with grep" | Use the Grep tool -- it handles permissions, output formatting, and never needs piping | 3 |
+
+## Anti-Patterns
+
+Pipe as shortcut. Chain as convenience. Redirect as persistence. `cd` before command. Inline complex data. Unquoted variables.

package/skills/context-updater/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: context-updater
+description: Use when investigation reveals data that is missing from or differs from project-context.json
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Context Updater
+
+project-context.json is shared memory across agents. When you discover something
+about the project that other agents would need, you are the only one who saw it.
+If you do not write it, the next agent starts from zero on that question.
+
+## When to Emit CONTEXT_UPDATE
+
+Emit a `CONTEXT_UPDATE` block when ANY of these are true:
+
+1. **Empty section** — A section you own exists but has no data
+2. **Drift detected** — Discovered data differs from current section
+3. **New resources found** — Resources not currently listed
+4. **Pattern discovered** — Investigation revealed a pattern, structure, or config not yet captured
+
+Skip when findings match existing data exactly -- redundant writes
+create noise in the audit trail without adding information.
+
+## How to Emit
+
+**Step 1: Check permissions**
+
+Do **not** memorize a static table from this skill. Your write permissions are
+shown in the injected context under **Your Write Permissions**. The
+`writable_sections` list there is the source of truth.
+
+If `write_permissions` is absent, fall back to your agent contract in
+`config/context-contracts.json`. Do not invent section names. Writing to a
+section you do not own will be rejected by the hook. `gaia-system` and `gaia-planner` do not write to project-context -- they
+manage gaia-ops internals and planning respectively.
+
+**Step 2: Build the CONTEXT_UPDATE block**
+
+Place this block after analysis and before the `json:contract` block:
+
+```
+CONTEXT_UPDATE:
+{
+  "section_name": {
+    "key": "value"
+  }
+}
+```
+
+Rules: valid JSON, section names must match writable sections, one block per
+response (combine all updates), include only keys to add or update.
+
+**Step 3: Apply merge semantics**
+
+| Operation | Behavior |
+|-----------|----------|
+| **ADD** | New keys inserted into the section |
+| **MERGE** | Existing dicts recursively merged |
+| **UNION** | Lists merged, no duplicates |
+| **OVERWRITE** | Scalar values replaced |
+| **NO-DELETE** | Keys you don't mention are preserved |
+
+## Prioritization
+
+When a section you own is empty or sparse, prioritize high-value keys first.
+
+| Priority | What to capture | Why |
+|----------|----------------|-----|
+| **P0** | Resource identifiers (names, IDs, paths) | Enables direct targeting in future searches |
+| **P1** | Structural relationships (what connects to what) | Enables cross-agent reasoning |
+| **P2** | Configuration values (versions, replicas, limits) | Enables drift detection |
+| **P3** | Behavioral patterns (conventions, naming schemes) | Enables consistency enforcement |
+
+Capture P0 keys on every investigation. P1-P3 when naturally encountered -- do
+not investigate solely to populate context.
+
+For concrete examples, read `examples.md` in this directory.
+
+## Anti-Patterns
+
+- Emitting updates without checking writable sections
+- Overwriting user-curated fields with generic values
+- Waiting until task completion to emit (emit as you discover)
+- Skipping P0 fields while enriching lower-priority ones

package/skills/context-updater/examples.md

@@ -0,0 +1,71 @@
+# CONTEXT_UPDATE Examples
+
+## cloud-troubleshooter
+
+```
+CONTEXT_UPDATE:
+{
+  "cluster_details": {
+    "kubernetes_version": "1.29",
+    "node_pools": [
+      {"name": "default-pool", "machine_type": "e2-standard-4", "node_count": 3}
+    ]
+  }
+}
+```
+
+## gitops-operator
+
+```
+CONTEXT_UPDATE:
+{
+  "gitops_configuration": {
+    "flux_version": "v2.6.1",
+    "reconciliation_interval": "1m"
+  }
+}
+```
+
+## terraform-architect
+
+```
+CONTEXT_UPDATE:
+{
+  "terraform_infrastructure": {
+    "modules": ["vpc", "eks", "rds"],
+    "backend": "s3"
+  }
+}
+```
+
+## developer
+
+```
+CONTEXT_UPDATE:
+{
+  "application_services": {
+    "services": [
+      {"name": "graphql-server", "port": 3000, "namespace": "common"}
+    ]
+  }
+}
+```
+
+## Fresh Install Enrichment
+
+After investigating a new cluster, the gitops-operator discovers namespace structure:
+
+```
+CONTEXT_UPDATE:
+{
+  "cluster_details": {
+    "namespaces": {
+      "application": ["adm", "dev", "test"],
+      "infrastructure": ["flux-system", "ingress-nginx"],
+      "system": ["kube-system", "kube-public"]
+    }
+  }
+}
+```
+
+This merges into existing `cluster_details`. Keys already present (like `kubernetes_version`) are preserved. The `namespaces` dict is added as a new key.

package/skills/developer-patterns/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: developer-patterns
+description: Use when creating, modifying, or reviewing application code in Node.js/TypeScript or Python
+metadata:
+  user-invocable: false
+  type: domain
+---
+
+# Developer Patterns
+
+Reference conventions for Node.js/TypeScript and Python. The codebase is the authority -- these patterns help you find and interpret what's already there.
+
+For config file templates (tsconfig.json, pyproject.toml, jest.config.ts), read `reference.md` in this directory.
+
+## Discover the Project's Conventions
+
+Before writing code, understand how THIS project is organized.
+
+1. **Find the entry points.** Look for `src/`, `lib/`, `app/`, or the package.json `main`/`exports` field. The layout varies -- what matters is where this project puts its code.
+2. **Read 2-3 existing modules.** How are tests organized -- co-located or in a `tests/` directory? What import style is used? What tooling does the config reflect?
+3. **Check the existing toolchain.** Read `package.json` scripts, `tsconfig.json`, `pyproject.toml`, or equivalent. The project's configured tools are your tools.
+4. **Follow the majority pattern.** If the project uses Vitest, don't introduce Jest. If tests live in `__tests__/`, put yours there too. Consistency with the project matters more than what you'd choose on a greenfield.
+
+## Node.js / TypeScript (Reference)
+
+Common conventions -- defer to the project's actual configuration.
+
+- **Strict TypeScript** — `strict: true` catches entire categories of null/undefined bugs at compile time rather than runtime
+- **Tests co-located** — `{file}.test.ts` next to `{file}.ts` keeps test and implementation in sync; but some projects prefer `__tests__/` directories, and that's fine
+- **Absolute imports** — path aliases in tsconfig eliminate fragile `../../../` chains that break on refactors
+- **Barrel exports with care** — re-export files (`index.ts`) create circular dependency risks in larger projects; use them intentionally
+- **Lock file committed** — reproducible installs across environments; without it, CI and local can diverge silently
+
+## Python (Reference)
+
+Common conventions -- defer to the project's actual configuration.
+
+- **src layout** — package under `src/` prevents accidental imports of the uninstalled package during development
+- **pyproject.toml** — single source of truth for packaging; `setup.py` and `setup.cfg` are legacy unless the project already uses them
+- **Type hints** — return types, parameter types; `Any` without a comment explaining why is a hole in the type safety net
+- **Fixtures in conftest.py** — shared fixtures at directory level prevent duplication; pytest discovers them automatically
+- **Lock file committed** — same reason as Node: reproducible installs
+
+## Key Rules (Both Stacks)
+
+1. **Tests with code** — untested code is unverified code; CI should enforce this, and if it doesn't, that's worth flagging
+2. **Linter runs clean** — disabling a lint rule without a comment explaining why creates invisible technical debt
+3. **No secrets in code** — environment variables only; `.env.example` documents what's needed so new developers don't have to guess
+4. **Dependency pinning** — lock files committed; without them, "works on my machine" is the default state
+5. **Security scanning** — `npm audit` / `pip-audit` catches known vulnerabilities before they reach production

package/skills/developer-patterns/reference.md

@@ -0,0 +1,112 @@
+# Developer Patterns — Config Reference
+
+Minimal config templates. Replace `{package-name}` and other placeholders with project values.
+
+For project-specific examples, discover patterns from the existing codebase using the `investigation` skill.
+
+---
+
+## tsconfig.json (strict baseline)
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## pyproject.toml (Poetry baseline)
+
+```toml
+[tool.poetry]
+name = "{package-name}"
+version = "0.1.0"
+description = ""
+packages = [{include = "{package-name}", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+ruff = "^0.4"
+mypy = "^1.10"
+
+[tool.ruff]
+line-length = 88
+select = ["E", "F", "I", "N", "UP"]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+[tool.pytest.ini_options]
+testpaths = ["src"]
+```
+
+## jest.config.ts (TypeScript)
+
+```typescript
+import type { Config } from 'jest'
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts'],
+  coverageThreshold: {
+    global: { lines: 80 }
+  }
+}
+
+export default config
+```
+
+## pytest conftest.py (fixture baseline)
+
+```python
+import pytest
+
+@pytest.fixture(scope="session")
+def db_connection():
+    """Session-scoped fixture for database connection."""
+    # Setup
+    conn = create_connection()
+    yield conn
+    # Teardown
+    conn.close()
+
+@pytest.fixture(autouse=True)
+def reset_state():
+    """Auto-use fixture to reset state between tests."""
+    yield
+    # cleanup after each test
+```
+
+## .env.example
+
+```bash
+# Required
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+API_KEY=your-api-key-here
+
+# Optional
+LOG_LEVEL=info
+PORT=3000
+```