@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-ops/skills/approval/reference.md

@@ -0,0 +1,57 @@
+# Approval Plan Template
+
+Use this template when presenting a T3 plan for user approval.
+The fields below map directly to the `approval_request` object in your `json:contract` block.
+
+```markdown
+## Deployment Plan
+
+### Summary (3-5 bullets)
+- What will be changed
+- Why this change is needed
+- What the expected outcome is
+
+### Changes Proposed
+
+**Resources to CREATE:**
+- [Resource]: [Description]
+
+**Resources to MODIFY:**
+- [Resource]: [What changes] (before -> after)
+
+**Resources to DELETE:**
+- [Resource]: [Why deletion]
+
+### Validation Results
+
+**Dry-run status:**
+- `[simulation command]` - [result summary]
+
+**Dependencies verified:**
+- [Dependency]: Available
+
+### approval_request fields
+
+These 6 fields MUST appear in the `approval_request` object of your `json:contract`:
+
+| Field | Example value |
+|-------|---------------|
+| `operation` | `"apply Terraform changes to dev VPC"` |
+| `exact_content` | `"terraform -chdir=/infra/dev apply -auto-approve"` |
+| `scope` | `"infra/dev/vpc.tf, infra/dev/subnets.tf -- dev environment only"` |
+| `risk_level` | `"MEDIUM"` |
+| `rollback` | `"terraform -chdir=/infra/dev apply -target=module.vpc -var='cidr=10.0.0.0/16'"` |
+| `verification` | `"terraform -chdir=/infra/dev output vpc_id -- expect vpc-xxx"` |
+
+When a hook blocked the command, also include:
+| Field | Example value |
+|-------|---------------|
+| `approval_id` | `"a1b2c3d4e5f6..."` (hex from hook deny response) |
+
+### Files Affected
+
+**Git changes:**
+- Modified: [files]
+- Added: [files]
+- Deleted: [files]
+```

package/dist/gaia-ops/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** — working directory is not reliable.
+5. **Quote variables** — always `"${VAR}"`.
+
+## 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/dist/gaia-ops/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/dist/gaia-ops/skills/context-updater/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: context-updater
+description: Use when investigation reveals data that is missing from or differs from project-context.json
+metadata:
+  user-invocable: false
+---
+
+# Context Updater Protocol
+
+## 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 (see `investigation` skill DOCUMENT rule)
+
+Do NOT emit if findings match existing data exactly.
+
+## Format
+
+Place this block after analysis and before the `json:contract` block:
+
+```
+CONTEXT_UPDATE:
+{
+  "section_name": {
+    "key": "value"
+  }
+}
+```
+
+**Rules:**
+- Must be valid JSON
+- Section names must match your writable sections
+- One block per response (combine all updates)
+- Include only keys to add or update
+
+## Merge Rules
+
+| 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 |
+
+## Writable Sections Source of Truth
+
+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` and `speckit-planner` do not write to project-context — they manage
+gaia-ops internals and specs respectively.
+
+## Progressive Enrichment Targets
+
+When a section you own is empty or sparse, prioritize populating it with 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.

package/dist/gaia-ops/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"
+  }
+}
+```
+
+## devops-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/dist/gaia-ops/skills/developer-patterns/SKILL.md

@@ -0,0 +1,93 @@
+---
+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
+
+Project-agnostic conventions for application development. Use values from your injected project-context — never hardcode environment-specific configuration.
+
+For config file templates (tsconfig.json, pyproject.toml, jest.config.ts), read `reference.md` in this directory.
+
+## Node.js / TypeScript
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Entry point / public API
+├── {module}/
+│   ├── index.ts          # Module public API
+│   ├── {module}.ts       # Implementation
+│   └── {module}.test.ts  # Co-located tests
+├── types/                # Shared type definitions
+└── utils/                # Shared utilities
+```
+
+### Toolchain
+
+| Concern | Tool |
+|---------|------|
+| Type checking | TypeScript (`strict: true`) |
+| Linting | ESLint |
+| Formatting | Prettier |
+| Testing | Jest or Vitest |
+| Pre-commit | Husky + lint-staged |
+| Security | `npm audit` |
+
+### Key Conventions
+
+- **Strict TypeScript** — `strict: true`, `noImplicitAny: true`, `strictNullChecks: true`
+- **Tests co-located** — `{file}.test.ts` next to `{file}.ts`, not in a separate `/tests` folder
+- **Absolute imports** — configure `paths` in tsconfig, never `../../../`
+- **No barrel exports** unless intentional — they create circular dependency risks
+- **Lock file committed** — `package-lock.json` or `pnpm-lock.yaml` always in Git
+
+---
+
+## Python
+
+### Project Structure
+
+```
+src/
+└── {package}/
+    ├── __init__.py
+    ├── {module}.py
+    └── tests/
+        ├── conftest.py       # Shared fixtures at directory level
+        └── test_{module}.py
+pyproject.toml                # Single source of truth
+```
+
+### Toolchain
+
+| Concern | Tool |
+|---------|------|
+| Packaging + deps | Poetry or pip-tools |
+| Linting + formatting | ruff (replaces black + isort + flake8) |
+| Type checking | mypy |
+| Testing | pytest |
+| Security | `pip-audit` |
+
+### Key Conventions
+
+- **src layout** — package under `src/`, not at root — prevents import confusion during development
+- **pyproject.toml only** — no `setup.py`, no `setup.cfg`, no bare `requirements.txt` for packaged code
+- **ruff over black + flake8** — one tool, faster, same behavior
+- **Type hints everywhere** — return types, parameter types; no `Any` without an inline comment explaining why
+- **Fixtures in conftest.py** — shared fixtures at directory level, not duplicated across test files
+- **Lock file committed** — `poetry.lock` always in Git
+
+---
+
+## Key Rules (Both Stacks)
+
+1. **Tests before merge** — no code without tests; CI must enforce
+2. **Linter is non-negotiable** — CI must fail on lint errors; never disable rules without comment
+3. **No secrets in code** — environment variables only; `.env.example` documents what's needed
+4. **Dependency pinning** — lock files always committed
+5. **Security scanning** — `npm audit` / `pip-audit` before release, not just on CI failures

package/dist/gaia-ops/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
+```

package/dist/gaia-ops/skills/execution/SKILL.md

@@ -0,0 +1,66 @@
+---
+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
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+Commands finishing is not success. Verification criteria passing is success.
+```
+
+## Mental Model
+
+T3 operations modify live state. Live state changes can be
+irreversible. You cannot claim COMPLETE until you have verified
+the result — not assumed it. A command can exit 0 and leave the
+system in a broken state.
+
+## Pre-Execution Checklist
+
+Before executing ANY approved operation:
+
+- [ ] User approved via AskUserQuestion and ElicitationResult hook activated the grant
+- [ ] Capture current state — know what you can roll back to
+- [ ] Plan still valid — re-run dry-run if time has passed
+- [ ] Commands will not prompt for interactive input
+
+If ANY check fails → `BLOCKED`.
+
+## 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 |
+
+## Anti-Patterns
+
+- COMPLETE without running verification criteria — the most common failure mode
+- Execute on approximate approval — "user approved something like this" is not the canonical token
+- Mutate without knowing rollback path — if you can't undo it, you're not ready to do it

package/dist/gaia-ops/skills/fast-queries/SKILL.md

@@ -0,0 +1,47 @@
+---
+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
+
+**Always run fast-queries FIRST** when investigating issues, checking status, or validating changes.
+
+## 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`
+
+## Exit Codes
+
+- `0` OK = All healthy — proceed
+- `1` WARNING = Warnings found — review before proceeding, not necessarily blocking
+- `2` ERROR = Errors found — stop and investigate before continuing
+- `3` SCRIPT_ERROR = Script error (missing tools, permissions) — check setup
+
+## Usage Pattern
+
+```
+1. User reports issue or asks for status
+2. Run fast-queries for relevant domain
+3. Interpret by exit code:
+   - 0 OK → proceed with task
+   - 1 WARNING → review each warning, decide if blocking before continuing
+   - 2 ERROR → report to user, do not proceed, investigate flagged issues
+   - 3 SCRIPT_ERROR → check tool availability and permissions
+4. Deep-dive only on flagged issues (exit 1 or 2)
+```
+
+Use domain-specific scripts when you know the area. Use `all` only for general status checks.