@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-ops/skills/security-tiers/reference.md

@@ -0,0 +1,39 @@
+# Security Tiers -- Reference
+
+Read on-demand by infrastructure agents. Not injected automatically.
+
+## Cloud-Specific Classification Examples
+
+### T0 -- Read-Only
+
+- `kubectl get pods`, `kubectl get svc`, `kubectl describe node`
+- `terraform show`, `terraform output`
+- `gcloud describe`, `gcloud sql instances describe`, `gcloud container clusters list`
+- `helm status`, `helm list`
+- `flux get kustomizations`, `flux get sources`
+
+### T1 -- Validation
+
+- `terraform validate`
+- `helm lint`
+- `tflint`
+- `kustomize build`
+
+### T2 -- Simulation
+
+- `terraform plan` / `terragrunt plan`
+- `kubectl diff -f manifest.yaml`
+- `helm upgrade --dry-run`
+- `kubectl apply --dry-run=server`
+
+### Conditional (T0 or T3 depending on flags)
+
+- `git branch` -- T0 for listing (no args or `--list`), T3 with `-D`, `-d`, `-m`, `-M`, `--delete`, `--move`
+
+### T3 -- Realization
+
+- `terraform apply` / `terragrunt apply`
+- `kubectl apply -f manifest.yaml`
+- `helm upgrade` (without `--dry-run`)
+- `flux reconcile` (write operations)
+- `git commit`, `git push` (any branch)

package/dist/gaia-ops/skills/skill-creation/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: skill-creation
+description: Use when creating a new skill, improving an existing skill, or deciding what a skill should contain and how it should be structured
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Skill Creation
+
+## What is a skill?
+
+Injected procedural knowledge — the "how" for agents. The agent brings identity and domain knowledge. The skill brings process and protocol. They never duplicate each other.
+
+## Step 1: Choose the type
+
+Type determines structure. Choose before writing anything.
+
+| Type | Purpose | When it applies |
+|------|---------|-----------------|
+| **Discipline** | Enforces rules the agent will rationalize around under pressure | command-execution, execution |
+| **Technique** | How to think about or approach a class of problem | investigation, approval |
+| **Reference** | Lookup tables, classifications, format specifications | security-tiers, output-format, git-conventions |
+| **Domain** | Project-specific patterns for a technical area | terraform-patterns, gitops-patterns |
+| **Protocol** | System operating contract — state machines, mandatory formats | agent-protocol |
+
+## Step 2: Apply the type structure
+
+### Discipline
+Iron Law → Mental Model → Rules → Traps → Anti-patterns
+
+Discipline skills enforce behavior agents will try to avoid. Every trap you don't name explicitly is a loophole.
+
+**Checklist:**
+- [ ] Iron Law in a code block at the top — the rule, stated bluntly
+- [ ] Mental model explains WHY (not just what not to do)
+- [ ] Rules — the concrete constraints
+- [ ] Traps table — "If you're thinking X → the reality is Y" (fuses red flags + rationalizations)
+- [ ] Anti-patterns with real code examples
+
+### Technique
+Overview (core principle + when to use) → Process (numbered steps) → Anti-patterns
+
+### Reference
+Quick-scan table at top → Examples → Edge cases / special rules
+
+### Domain
+Conventions (naming, structure) → Examples/snippets → Key rules → links to reference files
+
+### Protocol
+State machine / flow → Mandatory format → State transitions → Error handling
+
+---
+
+## Step 3: Write the description field (CSO)
+
+The description determines when the agent reads the skill. It must contain **triggering conditions only** — never summarize the process.
+
+If the description says what the skill does step by step, the agent follows the description and skips reading the content.
+
+```yaml
+# ❌ BAD — summarizes process, agent skips content
+description: Defensive command execution - timeout protection, pipe avoidance, safe shell patterns
+
+# ✅ GOOD — triggering conditions only
+description: Use when executing any bash command, cloud CLI, or shell operation
+```
+
+---
+
+## Step 4: Respect the line budget
+
+| Injection method | Budget | Reason |
+|-----------------|--------|--------|
+| Frontmatter (always loaded) | < 100 lines | Loaded on every agent call |
+| On-demand (read from disk) | < 500 lines | Loaded only when explicitly needed |
+
+Heavy reference material → move to `reference.md` (read on-demand).
+Concrete examples → move to `examples.md` (read on-demand).
+Executable tools → `scripts/` directory.
+
+```
+skill-name/
+├── SKILL.md          ← main content (always loaded)
+├── reference.md      ← heavy docs (on-demand)
+├── examples.md       ← concrete examples (on-demand)
+└── scripts/          ← executable tools
+```
+
+---
+
+## When to create vs update
+
+**Create new skill:**
+- Distinct behavioral concern not covered by any existing skill
+- Domain knowledge living inline in an agent that applies to multiple agents
+
+**Update existing skill:**
+- Agent ignores a rule the skill already defines → strengthen with Red Flags
+- Skill is missing a type-appropriate section
+
+**Do NOT create a skill — put elsewhere:**
+- Project-specific config → CLAUDE.md or agent inline
+- Single-agent-only behavior → keep inline in that agent
+- Knowledge the LLM covers well from training → not needed
+
+---
+
+## Anti-Patterns
+
+**❌ Description summarizes process** — agent follows the description and skips reading the skill body
+
+**❌ Discipline skill without Red Flags** — agents are smart; they rationalize. Every unnamed loophole gets used.
+
+**❌ Too generic** — "be careful with commands" teaches nothing. Skills need specific, concrete rules.
+
+**❌ Duplicates agent content** — two sources of truth both become stale. Pick one place.
+
+**❌ Single responsibility violated** — if a skill needs to cover two distinct behaviors, split it into two skills.

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

@@ -0,0 +1,186 @@
+---
+name: specification
+description: Use when the user describes a feature, problem, or need and a structured spec does not yet exist
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Specification
+
+**Orchestrator-only skill.** This skill is executed by the orchestrator, which
+cannot read files, write files, or run commands. Every file I/O step must name
+the delegation target (agent) explicitly. The orchestrator drives spec creation
+through dialogue -- it never delegates spec authoring to an agent.
+
+A spec captures WHAT to build and WHY.
+
+**The line between spec and plan:**
+- Technologies as problem context = OK in the spec. "The service needs a Cloud SQL
+  database for transaction storage" describes WHAT.
+- Implementation details = NOT OK. "Create a Cloud SQL instance with db-f1-micro
+  tier in us-central1 using Terraform module google_sql_database_instance" is HOW.
+
+The user will naturally mention technologies -- "deploy to GKE", "use Flux CD",
+"set up a Cloud SQL database." That is part of the problem domain. Accept it.
+What does NOT belong is file paths, class names, config values, or step-by-step
+instructions.
+
+## When to Activate
+
+Activate when ANY of these are true:
+- User describes a feature, capability, or change they want
+- User says "I want to build..." / "we need..." / "what if we..."
+- User pastes a ticket, issue, or informal requirements
+- The `planning_specs` surface is active and no `spec.md` exists yet
+
+Do NOT activate when:
+- A spec.md already exists and the user wants to plan or implement
+- The user is asking about live infrastructure or runtime state
+
+## Step 1: Load Context and Constraints
+
+Before asking the first question, delegate to the `gaia` agent to read:
+- `governance.md` from the speckit root -- architectural principles, stack constraints
+- `project-context.json` -- existing services, infrastructure, paths
+
+**Discovering `speckit_root`:** The path is stored in `project-context.json` at
+`paths.speckit_root`. The `gaia` agent resolves this during the read above. If
+the key is missing, default to `specs/` relative to project root; if that also
+does not exist, set status `BLOCKED` and ask the user for the path.
+
+Extract:
+- Mandatory architectural principles (GitOps, Workload Identity, etc.)
+- Technology stack constraints (cloud provider, orchestration, IaC tool)
+- Existing services and infrastructure that may overlap with the request
+
+These feed your critical thinking. Do not dump them to the user -- use them
+to ask better questions and catch problems early.
+
+## Step 2: Capture the Raw Idea
+
+Let the user talk. This is brainstorming -- messy and nonlinear is fine.
+Collect everything they say without restructuring yet.
+
+Identify from their words:
+- **Who benefits** -- the actor or stakeholder
+- **What problem** they face today
+- **What outcome** they want
+- **What triggers** the need (event, pain point, dependency)
+
+If any of these four are missing after the user's initial description,
+ask ONE focused question to fill the biggest gap. Do not interrogate.
+Prefer "What problem does this solve?" over a list of five questions.
+
+## Step 3: Challenge and Clarify
+
+This is where the orchestrator earns its keep. Do not just transcribe --
+think critically about what the user is asking.
+
+**Proactive checks (run these against loaded context):**
+- Does an existing service already cover this? Alert: "The project already
+  has a payment service at services/payments/ -- is this replacing it or
+  something separate?"
+- Does the request conflict with governance? Alert: "Governance mandates
+  ArgoCD but you mentioned Flux -- is there a reason to diverge?"
+- Is there unnecessary complexity? Push back: "Do you really need a separate
+  microservice, or could this be a module in the existing order service?"
+- Do stated requirements match the acceptance criteria? Challenge: "You said
+  real-time notifications, but the acceptance criteria suggest hourly batches
+  would satisfy the users. Which is it?"
+
+**Say NO when something does not make sense.** If the request contradicts
+governance, duplicates existing work, or introduces unjustified complexity,
+surface that clearly. The user can override, but they should do it consciously.
+
+**Clarifying questions** -- ask at most 3 rounds. Each round: one question,
+wait for the answer, integrate it. Stop asking when:
+- You can write a problem statement without guessing
+- You can list at least 2 acceptance scenarios
+- Scope boundaries are clear (what is IN, what is OUT)
+
+Good clarifying questions:
+- "What should happen when [edge case]?"
+- "Is [adjacent feature] in scope or separate?"
+- "Who else uses this besides [primary actor]?"
+- "What does success look like from the user's perspective?"
+
+Bad clarifying questions (never ask these):
+- "How should the database schema look?" (implementation detail)
+- "What API endpoints do you need?" (implementation detail)
+- "Which Terraform module should we use?" (implementation detail)
+
+## Step 4: Draft the Spec
+
+Organize findings into this structure. Use the spec template from
+`speckit/templates/spec-template.md` as the canonical format.
+
+**Mandatory sections:**
+
+1. **Problem Statement** -- 2-3 sentences. The pain point and who feels it.
+
+2. **User Stories** -- "As [actor], I want [goal], so that [benefit]."
+   Minimum 1, maximum 5. Each must name a real actor, not "the system."
+
+3. **Acceptance Criteria** -- Given/When/Then format. At least one per
+   user story. These are the contract the implementation must satisfy.
+
+4. **Scope Boundaries** -- Two columns: IN scope / OUT of scope.
+   Explicit exclusions prevent scope creep during planning.
+
+5. **Constraints** -- Pull from governance.md. Only list constraints
+   that are relevant to this feature. Do not dump the entire governance.
+
+6. **Key Entities** -- If the feature involves data, name the entities
+   and their relationships in plain language. No field types, no schemas.
+
+**Optional sections** (include only when relevant):
+
+- **Edge Cases** -- What happens when [boundary condition]?
+- **Security Considerations** -- If the feature handles auth, PII, or secrets
+- **Performance Expectations** -- Only if the user stated targets
+
+Mark anything uncertain with `[NEEDS CLARIFICATION: specific question]`.
+
+## Step 5: Present for Review
+
+Show the full draft spec to the user. Ask:
+- "Does this capture what you want?"
+- "Anything missing or wrong?"
+- "Are the scope boundaries right?"
+
+Iterate until the user approves. Each iteration: apply their feedback,
+show the updated section (not the full spec again), confirm.
+
+## Step 6: Save
+
+When the user approves, delegate to the `devops-developer` agent to save
+`spec.md` in the feature directory: `{speckit_root}/{feature-name}/spec.md`.
+
+The feature directory name: lowercase, hyphenated, descriptive.
+Example: `payment-gateway`, `user-notifications`, `report-export`.
+
+After saving, suggest: "The spec is ready. Want me to start planning?"
+This transitions to the `speckit-planner` agent via the `/speckit.plan` skill
+invocation (not a shell command -- it is a slash-command that the orchestrator
+dispatches as a skill).
+
+## Quality Checks
+
+Before presenting the draft, verify:
+- [ ] Every user story names a real actor (not "the system")
+- [ ] Every acceptance criterion is testable without knowing the implementation
+- [ ] Technologies appear only as problem context, never as implementation instructions
+- [ ] Scope boundaries explicitly exclude at least one adjacent concern
+- [ ] Constraints come from governance, not from assumptions
+- [ ] Problem statement explains WHY, not WHAT to build
+
+## Anti-Patterns
+
+- **Agreeable transcriber** -- just writing down what the user says without questioning it. The orchestrator guides, challenges, and shapes.
+- **Interrogation** -- asking 10 questions before writing anything. Capture first, clarify gaps.
+- **Premature structure** -- forcing the user into Given/When/Then before they have finished describing the idea.
+- **Technology ban** -- rejecting all technology mentions. "Deploy to GKE with Flux CD" is problem context, not implementation detail.
+- **Completionism** -- trying to spec every edge case. The plan phase handles depth.
+- **Skipping governance** -- writing a spec that violates known constraints, wasting plan time.
+- **Ignoring existing state** -- not checking project-context for services or infrastructure that overlap with the request.

package/dist/gaia-ops/skills/speckit-workflow/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: speckit-workflow
+description: Use when planning features using the Spec-Kit framework (plan, tasks)
+metadata:
+  user-invocable: false
+---
+
+# Spec-Kit Workflow
+
+Domain workflow for feature planning. Artifacts go to `{speckit_root}/{feature-name}/`.
+Templates live at `{project-root}/speckit/templates/`. Read the template before generating any artifact.
+
+**Path resolution:** `speckit_root` comes from project-context.json `paths.speckit_root`. Default: `specs/` relative to project root. The agent definition's Context Resolution section is authoritative for path resolution.
+
+## Flow
+
+```
+Completed spec.md (from orchestrator)
+        |
+    Plan -> plan.md + research.md + data-model.md + contracts/
+        |
+    Tasks -> tasks.md (enriched, self-contained)
+        |
+    Return to orchestrator (routes tasks to agents)
+```
+
+## Phase 0: Governance Sync (MANDATORY before any phase)
+
+1. Read `project-context.json`. Missing -> BLOCKED, ask user for `npx gaia-scan`.
+2. Update `## Stack Definition` in `{speckit_root}/governance.md` from project-context.
+   Missing governance.md -> create from template. Exists -> update Stack Definition only.
+3. Read updated governance.md -- this is your working context for all phases.
+
+---
+
+## Phase 1: Plan
+
+**Input:** Validated `spec.md` (no unresolved `[NEEDS CLARIFICATION]`).
+**Output:** `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`.
+**Template:** Read `speckit/templates/plan-template.md` FIRST.
+
+### Procedure
+
+1. **Verify prerequisite.** Read spec.md. If missing -> BLOCKED, ask orchestrator to provide a completed spec. If unresolved
+   `[NEEDS CLARIFICATION]` markers remain -> STOP, resolve them first.
+
+2. **Initialize plan.md** from the plan template. If plan.md already exists, skip (do not overwrite).
+
+3. **Clarify planning ambiguities** (max 5 questions):
+   - Scan for: functional scope, data model gaps, non-functional targets,
+     integration unknowns, edge cases, vague terminology.
+   - Ask one question at a time. Integrate answers into spec.md immediately.
+
+4. **Fill Technical Context** in plan.md:
+   - Language/version, dependencies, storage, testing framework, target platform.
+   - Ask user for anything you cannot infer.
+
+5. **Run Constitution Check** against governance.md:
+   - GitOps patterns enforced? HTTPS for external endpoints? Health checks?
+     No `:latest` image tags? Scope boundaries respected?
+   - Violations -> document in Complexity Tracking with justification.
+   - Unjustifiable violations -> ERROR "Simplify approach first."
+
+6. **Phase 0 -- Research.** For each unknown or technology choice:
+   - Research best practices. Consolidate in `research.md` with:
+     Decision, Rationale, Alternatives considered.
+
+7. **Phase 1 -- Design.** From spec + research:
+   - Extract entities -> `data-model.md` (fields, relationships, validations).
+   - Generate API contracts from functional requirements -> `contracts/` directory.
+   - Generate failing contract tests (one per endpoint).
+   - Extract test scenarios from user stories -> `quickstart.md`.
+
+8. **Re-run Constitution Check.** New violations -> refactor, return to step 7.
+
+9. **Describe Phase 2 task approach** in plan.md -- do NOT create tasks.md.
+
+10. **STOP.** Plan phase is complete. Suggest next step: `/speckit.tasks`.
+
+---
+
+## Phase 2: Tasks
+
+**Input:** `plan.md` + available design docs (`data-model.md`, `contracts/`, `research.md`).
+**Output:** `{feature-dir}/tasks.md`.
+**Template:** Read `speckit/templates/tasks-template.md` FIRST.
+
+### Procedure
+
+1. **Verify prerequisite.** plan.md must exist. If missing -> ERROR.
+
+2. **Load all available design documents:**
+   - plan.md (REQUIRED) -- tech stack, architecture, file structure.
+   - data-model.md (if exists) -- entities and relationships.
+   - contracts/ (if exists) -- API specifications.
+   - research.md (if exists) -- technical decisions.
+   - quickstart.md (if exists) -- test scenarios.
+
+3. **Read the tasks template** from `speckit/templates/tasks-template.md`.
+
+4. **Generate tasks by category:**
+   - **Setup:** Project init, dependencies, linting, config.
+   - **Tests [P]:** One per contract, one per integration scenario (TDD -- tests first).
+   - **Core:** One per entity model, one per service, one per endpoint/command.
+   - **Integration:** DB connections, middleware, logging, external services.
+   - **Polish [P]:** Unit tests, performance tests, docs, cleanup.
+
+5. **Apply parallelism rules:**
+   - Different files with no shared dependencies -> mark `[P]`.
+   - Same file -> sequential (no `[P]`).
+
+6. **Order by dependency:**
+   Setup -> Tests -> Models -> Services -> Endpoints -> Integration -> Polish.
+
+7. **Enrich EVERY task with inline metadata:**
+   ```markdown
+   - [ ] T001 Description
+     - context: relevant plan slice (tech stack, architecture decisions)
+     - files: expected file paths
+     - depends-on: task IDs or `none`
+     - exit-criteria: `command` expected outcome
+     - suggested-agent: {agent}
+     - tier: {T0|T1|T2|T3}
+     <!-- Tags: #tag1 #tag2 -->
+   ```
+   - **Agent:** terraform keywords -> `terraform-architect`, kubectl/helm -> `gitops-operator`,
+     code/test/build -> `devops-developer`, logs/monitoring -> `cloud-troubleshooter`.
+   - **Tier:** T0 (read), T1 (validate), T2 (simulate), T3 (mutate).
+   - **Tags:** tech (#terraform, #kubernetes), domain (#database, #security), type (#setup, #test).
+   - **T2/T3 tasks** get: `<!-- HIGH RISK: Analyze before execution -->`.
+
+8. **CRITICAL -- every task MUST include:**
+   - An `exit-criteria:` line with a command or observable outcome.
+   - Enough context for the executing agent to work without loading multiple files.
+
+9. **Generate dependency graph** in YAML at the bottom of tasks.md.
+
+10. **Cross-artifact validation:**
+    - All spec requirements covered by at least one task?
+    - All contracts have test tasks? All entities have model tasks?
+    - CRITICAL gaps -> pause, require user approval.
+    - LOW/MEDIUM gaps -> add notes to Dependencies section.
+
+11. **Report** with: task count, coverage percentage, any issues found.
+    Tasks are returned to the orchestrator for execution.
+
+---
+
+## Task Enrichment Rules (applies to Phase 2)
+
+Every task gets automatic metadata:
+- **Agent:** detect from keywords (terraform -> `terraform-architect`, kubectl -> `gitops-operator`,
+  code/test -> `devops-developer`, monitoring/logs -> `cloud-troubleshooter`).
+- **Security Tier:** classify using `security-tiers` skill.
+- **Tags:** technology (#terraform, #kubernetes), domain (#database, #security), type (#setup, #test).
+- **Exit criteria:** a command or observable outcome confirming completion.
+- **Context slice:** relevant portion of the plan so the task is self-contained.
+
+## Critical Rules
+
+1. **Always read templates** from `speckit/templates/` before generating any artifact.
+2. Every task MUST include: exit criteria + enough inline context to be self-contained.
+3. Tasks must be **self-contained** -- executable by the assigned agent without SpecKit knowledge.
+4. Each phase STOPS at its boundary. Do not auto-advance to the next phase.
+5. Spec is WHAT (no implementation details). Plan is HOW. Tasks are DO.

package/dist/gaia-ops/skills/speckit-workflow/reference.md

@@ -0,0 +1,117 @@
+# Spec-Kit Workflow -- Reference
+
+For full templates, read from `{project-root}/speckit/templates/`. The templates below are summaries only.
+
+## Template Paths
+
+| Artifact | Template path |
+|----------|---------------|
+| spec.md | `speckit/templates/spec-template.md` |
+| plan.md | `speckit/templates/plan-template.md` |
+| tasks.md | `speckit/templates/tasks-template.md` |
+
+## Artifact Summary: spec.md
+
+Spec creation is handled conversationally by the orchestrator. The speckit-planner receives a completed spec.md as input.
+
+```markdown
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`
+**Created**: [DATE]
+**Status**: Draft
+
+## User Scenarios & Testing *(mandatory)*
+### Primary User Story
+### Acceptance Scenarios (Given/When/Then)
+### Edge Cases
+
+## Requirements *(mandatory)*
+### Functional Requirements (FR-001, FR-002...)
+### Key Entities *(if data involved)*
+
+## Review Checklist
+- [ ] No implementation details
+- [ ] Requirements testable and unambiguous
+- [ ] All [NEEDS CLARIFICATION] resolved
+```
+
+## Artifact Summary: plan.md
+
+```markdown
+# Implementation Plan: [FEATURE]
+
+## Summary
+## Technical Context (Language, Dependencies, Storage, Testing)
+## Constitution Check (GitOps, Security, Scope)
+## Project Structure (docs + source code layout)
+## Phase 0: Research -> research.md
+## Phase 1: Design -> data-model.md, contracts/, quickstart.md
+## Phase 2: Task Planning Approach (describe only, do NOT create tasks.md)
+## Progress Tracking
+```
+
+## Artifact Summary: tasks.md
+
+Every task MUST include exit criteria and enough inline context to be self-contained.
+
+```markdown
+# Tasks: [FEATURE NAME]
+
+## Phase 1: Setup
+- [ ] T001 Create project structure
+  - context: NestJS project, TypeScript 5.x, PostgreSQL
+  - files: src/modules/auth/{controller,service,module}.ts
+  - depends-on: none
+  - exit-criteria: `ls src/modules/auth/` shows controller.ts, service.ts, module.ts
+  - suggested-agent: devops-developer
+  - tier: T0
+  <!-- Tags: #setup #config -->
+
+## Phase 2: Tests First (TDD)
+- [ ] T004 [P] Contract test POST /api/users
+  - context: REST API, Jest testing framework
+  - files: tests/contract/test_users_post.py
+  - depends-on: T001
+  - exit-criteria: `pytest tests/contract/test_users_post.py` runs (fails before impl)
+  - suggested-agent: devops-developer
+  - tier: T1
+  <!-- Tags: #test #api -->
+
+## Phase 3: Core Implementation
+## Phase 4: Integration
+## Phase 5: Polish
+## Dependencies (YAML dependency graph)
+```
+
+**High-risk tasks (T2/T3):**
+
+```markdown
+- [ ] T042 Apply Terraform changes to production
+  - context: VPC module, shared networking layer
+  - files: terraform/modules/vpc/main.tf
+  - depends-on: T041
+  - exit-criteria: `terraform show` confirms expected resources
+  - suggested-agent: terraform-architect
+  - tier: T3
+  <!-- Tags: #terraform #infrastructure #production -->
+  <!-- HIGH RISK: Analyze before execution -->
+```
+
+## Agent Routing Signals
+
+| Signals in task | Agent |
+|-----------------|-------|
+| terraform, .tf, vpc, gke, iam | `terraform-architect` |
+| kubectl, helm, flux, k8s, deployment | `gitops-operator` |
+| gcloud, cloud logging, runtime drift | `cloud-troubleshooter` |
+| docker, npm, build, test, CI, code | `devops-developer` |
+
+## Security Tier Detection
+
+| Tier | Verbs |
+|------|-------|
+| T0 | describe, get, show, list, logs, read |
+| T1 | validate, lint, template, format |
+| T2 | plan, dry-run, diff |
+| T3 | apply, push, create, delete, deploy |

package/dist/gaia-ops/skills/terraform-patterns/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: terraform-patterns
+description: Use when creating, modifying, or reviewing Terraform or Terragrunt configuration files
+metadata:
+  user-invocable: false
+  type: domain
+---
+
+# Terraform Patterns
+
+Project-specific conventions. Use values from your injected project-context — never hardcode project IDs, regions, or account identifiers.
+
+For HCL examples (remote state, component structure, labels, outputs), read `reference.md` in this directory.
+
+## Directory Structure
+
+```
+terraform/
+└── [module-name]/
+    ├── main.tf        # Resource definitions
+    ├── variables.tf   # Input variables
+    ├── outputs.tf     # Output values (snake_case, with descriptions)
+    └── provider.tf    # Provider config (if module-level)
+
+features/infra/[env]/
+├── terragrunt.hcl           # Root: remote state config
+└── [component]/
+    └── terragrunt.hcl       # Component: inputs + dependency references
+```
+
+## Naming Convention
+
+| Resource | Pattern | Notes |
+|----------|---------|-------|
+| Network/VPC | `{app}-{env}-vpc` | From context: project + env |
+| Cluster | `{app}-{env}-cluster-{n}` | Match context cluster_name |
+| Database | `{app}-{env}-{engine}-instance` | Engine: postgres, mysql |
+| Secret | `{service}-secret` | Matches app service name |
+| Service Account | `{resource}-sa` | Scope: resource it serves |
+
+## Module Sourcing
+
+- **Local modules** (preferred for GCP): `../../../../../terraform//{module-name}`
+- **Registry modules** (preferred for AWS): `tfr:///terraform-aws-modules/{module}/aws?version=x.y.z`
+- **Always pin exact versions** — never `latest`, never unpinned
+
+## Key Rules
+
+1. **Prefer Terragrunt** — prefer `terragrunt` commands for all environment operations; raw `terraform` is acceptable for module development and testing only
+2. **Dependencies via blocks** — never hardcode IDs, always `dependency.x.outputs.y`
+3. **Version pinning** — exact versions for modules, `~>` for providers
+4. **Tags on everything** — all resources get the standard label block
+5. **snake_case outputs** — descriptive names with `description` field
+6. **mock_outputs on dependencies** — required for `validate` and `plan` to work offline
+
+## Reference Docs
+
+Use `WebFetch` when a resource or attribute is unknown or ambiguous. Do not use WebFetch to discover patterns — the codebase always wins over external docs.
+
+| Need | URL |
+|------|-----|
+| Google provider resources | `https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/{resource}` |
+| Terragrunt config blocks | `https://terragrunt.gruntwork.io/docs/reference/config-blocks-and-attributes` |