@jaguilar87/gaia-ops 4.4.0 → 4.7.2

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

@@ -0,0 +1,93 @@
+# Terraform Patterns — HCL Reference
+
+Structural patterns for Terraform and Terragrunt. Cloud-agnostic — use values from project-context, never hardcode.
+
+For cloud-specific resource examples (VPCs, clusters, databases), discover patterns from the existing codebase using the `investigation` skill.
+
+---
+
+## Remote State (root terragrunt.hcl)
+
+```hcl
+remote_state {
+  backend = "gcs"                          # gcs | s3 | azurerm — from cloud_provider in context
+  config = {
+    bucket   = "{project_id}-terraform-state"
+    prefix   = "${path_relative_to_include()}/terraform.tfstate"
+    project  = "{project_id}"              # from project-context
+    location = "{primary_region}"          # from project-context
+  }
+}
+```
+
+## Component (terragrunt.hcl)
+
+```hcl
+include "root" { path = find_in_parent_folders() }
+terraform { source = "../../../../../terraform//{module-name}" }
+
+dependency "vpc" {
+  config_path = "../vpc"
+  mock_outputs = { network_id = "mock-network" }
+  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
+}
+
+inputs = {
+  project_id = "{project_id}"              # from project-context
+  region     = "{primary_region}"          # from project-context
+  network_id = dependency.vpc.outputs.network_id
+}
+```
+
+## Required Labels
+
+Every resource must include:
+
+```hcl
+labels = {
+  environment = "{env}"                    # from project-context
+  managed_by  = "terraform"
+  project     = "{project_id}"            # from project-context
+}
+```
+
+## Outputs Pattern
+
+```hcl
+output "resource_id" {
+  description = "Description of what this output represents"
+  value       = resource_type.name.id
+}
+```
+
+Always: snake_case name, non-empty description, no sensitive values unless `sensitive = true`.
+
+## Module Sourcing
+
+```hcl
+# Local module (GCP preferred)
+terraform { source = "../../../../../terraform//{module-name}" }
+
+# Registry module (AWS preferred)
+terraform { source = "tfr:///terraform-aws-modules/{module}/aws?version=x.y.z" }
+```
+
+Always pin exact versions — never `latest`, never unpinned.
+
+## State Operations
+
+```bash
+terragrunt state list
+terragrunt state show {resource_type}.{name}
+terragrunt import {resource_type}.{name} {live_id}
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| State lock | Check state backend lock table, wait or force-unlock with caution |
+| Module not found | Run `terragrunt init` |
+| Dependency cycle | Review dependency `config_path` declarations |
+| Mock outputs mismatch | Update `mock_outputs` to match actual output types |
+| Plan shows unexpected destroy | Check for naming drift between code and live state |

package/dist/gaia-ops/speckit/README.md

@@ -0,0 +1,516 @@
+# Spec-Kit - Structured Feature Development System
+
+Structured workflow framework for specification-driven feature development. Spec-Kit is an open-source framework integrated as agentic functionality for Claude Code. It provides templates, scripts, and a lean agent (`speckit-planner`) that detects the current workflow phase from existing artifacts and loads the corresponding skill — no slash commands needed. governance.md is auto-generated on first use and kept in sync with `project-context.json` on every session.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Skills Reference](#skills-reference)
+- [Auto-Enrichment](#auto-enrichment)
+- [Surface Routing](#surface-routing)
+- [Troubleshooting](#troubleshooting)
+- [Best Practices](#best-practices)
+- [References](#references)
+- [Support](#support)
+
+## Overview
+
+### What is Spec-Kit?
+
+Spec-Kit provides structured workflow for feature planning:
+1. **Specify** - Define feature specifications (conversational, orchestrator-driven)
+2. **Plan** - Create technical implementation plans
+3. **Tasks** - Generate actionable task lists with metadata
+4. **Analyze** - Validate consistency across artifacts
+5. **Execute** - Orchestrator routes tasks to agents for execution
+6. **Governance** - Maintain project governance principles
+
+### Key Features
+
+- ✅ **Natural language** - No slash commands; describe what you need in plain language
+- ✅ **Phase auto-detection** - Agent reads artifacts and knows which skill to apply
+- ✅ **Governance auto-sync** - governance.md generated on first use, kept in sync with project-context on every session
+- ✅ **GOVERNANCE_UPDATE** - plan skill detects new technologies and updates governance.md automatically
+- ✅ **Multi-project** - Work with multiple spec-kits simultaneously
+- ✅ **Portable** - Works with any project structure
+- ✅ **Auto-enrichment** - Tasks automatically tagged with surface-routing metadata
+- ✅ **Risk analysis** - High-risk tasks (T2/T3) analyzed before execution
+- ✅ **Surface routing** - Tasks can target one or more specialized agents automatically
+- ✅ **Git-agnostic** - User controls Git workflow independently
+- ✅ **Template-based** - Consistent structure across features
+- ✅ **State machine** - Always know where you are and what to run next
+- ✅ **Drift detection** - Verify declared completions against real code evidence
+
+## Architecture
+
+### Directory Structure
+
+```
+.claude/speckit/
+├── README.md                # This file
+├── scripts/                 # Reserved - not yet implemented
+├── templates/               # 5 markdown templates
+│   ├── spec-template.md     # Feature specification template
+│   ├── plan-template.md     # Implementation plan template
+│   ├── tasks-template.md    # Task list template
+│   ├── adr-template.md      # Architecture Decision Record template
+│   └── agent-file-template.md  # Agent context file template
+
+.claude/agents/
+└── speckit-planner.md       # Lean agent — phase detection + skill dispatch
+
+.claude/skills/
+└── speckit-workflow/SKILL.md    # Single skill with full workflow logic
+
+.claude/commands/            # 5 slash commands
+├── speckit.init.md              # Bootstrap project-context.json
+├── speckit.plan.md              # Generate plan.md + design artifacts
+├── speckit.tasks.md             # Generate enriched tasks.md
+├── speckit.add-task.md          # Add ad-hoc task with enrichment
+└── speckit.analyze-task.md      # Deep-dive before executing risky tasks
+
+.claude/tools/               # Python utilities
+├── context/                 # Context provisioning and enrichment
+│   ├── context_provider.py  # Main context provisioning logic
+│   └── context_section_reader.py  # Token-optimized context extraction
+├── memory/                  # Episodic memory system
+│   └── episodic.py          # Persistent episode storage and retrieval
+└── validation/              # Approval gates
+    └── approval_gate.py     # T3 approval workflow
+
+<project-root>/              # User-specified root (e.g., specs/)
+├── governance.md            # Auto-generated by gaia-scan, synced from project-context.json
+└── specs/                   # Feature specifications
+    ├── 001-feature-name/
+    │   ├── spec.md          # Feature specification
+    │   ├── plan.md          # Implementation plan
+    │   ├── tasks.md         # Task list (auto-enriched)
+    │   ├── research.md      # Research notes (optional)
+    │   ├── data-model.md    # Data model (optional)
+    │   └── contracts/       # API contracts (optional)
+    └── 002-feature-name/
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Used By |
+|-----------|---------------|---------|
+| **speckit-planner** | Phase detection, skill dispatch | Claude orchestrator |
+| **Skills** | Per-phase process and protocol | Agent automatically |
+| **Scripts** | Reserved - not yet implemented | -- |
+| **Templates** | Consistent artifact structure | Scripts during creation |
+| **Governance** | Project governance principles | All planning skills |
+
+## Installation
+
+### Initial Setup
+
+**Step 1: Create project directory**
+```bash
+mkdir -p specs/specs
+```
+
+**Step 2: Bootstrap project context** (natural language)
+```
+"initialize speckit for this project"
+"bootstrap specs"
+```
+
+**Ready!** The `speckit-planner` agent detects the phase automatically. Example conversation:
+
+```
+"I want to add dark mode to the settings page"
+→ Orchestrator drives spec creation conversationally → writes spec.md
+
+"plan the dark mode feature"
+→ speckit-planner: spec.md exists, no plan.md → runs plan skill → writes plan.md
+
+"generate tasks for 001-dark-mode"
+→ speckit-planner: plan.md exists, no tasks.md → runs tasks skill → writes tasks.md
+
+"execute the tasks for 001-dark-mode"
+→ Orchestrator reads tasks.md → routes each task to the appropriate agent
+```
+
+---
+
+## Skills Reference
+
+The `speckit-planner` agent uses a single skill (`skills/speckit-workflow/SKILL.md`) that contains plan + task generation logic. Spec creation is conversational (orchestrator-driven). Task execution is handled by the orchestrator routing tasks to agents. Additionally, 5 slash commands in `commands/` provide direct phase invocation.
+
+| Phase | Purpose | Trigger phrase examples |
+|-------|---------|------------------------|
+| **specify** | Define feature spec conversationally | "I want to add X", "create spec for Y" (orchestrator-driven) |
+| **init** | Verify prerequisites, generate/sync governance.md | Runs silently -- user does not invoke directly |
+| **plan** | Generate plan.md + design artifacts | "plan feature X", "generate implementation plan" |
+| **tasks** | Generate enriched tasks.md | "generate tasks for X", "create task list" |
+| **execute** | Route tasks to agents | "execute the tasks", "start implementation" (orchestrator-driven) |
+| **add-task** | Add task with auto-enrichment | "add a task for X", "I need a task to fix Y" |
+| **analyze-task** | Deep-dive before executing risky task | "analyze T042", "what does T015 do" |
+
+> **init** runs automatically as Step 0 before any agent action. It generates `governance.md` on first use and syncs it with `project-context.json` on subsequent sessions -- silently unless changes are made.
+
+---
+
+## Auto-Enrichment
+
+### What is Auto-Enrichment?
+
+Automatic injection of metadata into tasks for agent routing and risk assessment.
+
+### When Does It Happen?
+
+**Automatic enrichment:**
+- ✨ Tasks phase (`speckit.tasks` skill) — all tasks enriched when generated
+- ✨ Add-task phase (`speckit.add-task` skill) — new task enriched when added
+
+**No manual enrichment step needed**
+
+### Enrichment Process
+
+**Step 1: Surface routing** (handled by the speckit.tasks skill during task generation)
+
+**Step 2: Metadata injection**
+```markdown
+- [ ] T001 Create GKE cluster
+  <!-- 🤖 Agent: terraform-architect | ✅ T1 | ❓ 0.85 -->
+  <!-- 🏷️ Tags: #terraform #gcp #gke -->
+  <!-- 🎯 skill: terraform_operations (8.0) -->
+  <!-- 🧭 Adjacent surfaces: note any cross-layer checks or follow-up agents -->
+```
+
+### Metadata Components
+
+**Agent assignment:**
+```
+🤖 Agent: terraform-architect
+```
+Primary agent for task execution
+
+**Risk tier:**
+```
+✅ T0 (read-only)
+✅ T1 (validation)
+🔒 T2 (simulation) - Requires analysis
+🚫 T3 (blocked) - Not executed
+```
+
+**Confidence score:**
+```
+❓ 0.85 (0.0-1.0 scale)
+```
+Router confidence in agent assignment
+
+**Tags:**
+```
+🏷️ Tags: #terraform #gcp #gke
+```
+Technology and domain tags
+
+**Skill scores:**
+```
+🎯 skill: terraform_operations (8.0)
+```
+Agent capability match
+
+**Adjacent surface note:**
+```
+🧭 Adjacent surfaces: app_ci_tooling, live_runtime
+```
+Cross-layer follow-up or validation surfaces to review before execution
+
+**High-risk warning:**
+```
+⚠️ HIGH RISK: Analyze before execution
+💡 Suggested: analyze task T001
+```
+For T2/T3 tasks only. The orchestrator triggers analysis automatically before execution.
+
+**Low-confidence warning** (score < 0.5):
+```
+⚠️ LOW_CONFIDENCE: score=0.3 — review surface classification manually
+```
+Emitted automatically when routing confidence falls below `MIN_CONFIDENCE: 0.5`
+
+### Enrichment Benefits
+
+- [x] Automatic surface routing
+- [x] Risk visibility
+- [x] Execution safety
+- [x] Audit trail
+- [x] Team coordination
+- [x] Confidence threshold warnings (MIN_CONFIDENCE: 0.5)
+- [x] Machine-readable dependency graph (YAML) in tasks.md
+
+## Surface Routing
+
+### How Routing Works
+
+**Step 1: Infer active surfaces from task metadata**
+```markdown
+<!-- 🤖 Agent: gitops-operator | ✅ T0 | ❓ 0.92 -->
+<!-- 🧭 Surface: gitops_desired_state -->
+```
+
+**Step 2: Load surface-relevant context**
+```python
+from tools.context.context_section_reader import ContextSectionReader
+reader = ContextSectionReader(project_context)
+context = reader.get_sections_for_agent('gitops-operator')
+```
+
+**Step 3: Invoke one or more specialized agents**
+```python
+Task(
+    subagent_type='gitops-operator',
+    prompt=f"{context}\n\n{task_instructions}"
+)
+```
+
+If the task spans multiple surfaces, dispatch the primary agent for each active surface and consolidate the findings before acting.
+
+### Core Surfaces
+
+| Surface | Primary agent | Typical signals |
+|-------|---------------|-----------|
+| `terraform_iac` | **terraform-architect** | Terraform/Terragrunt, IAM, buckets, shared modules |
+| `gitops_desired_state` | **gitops-operator** | Kubernetes manifests, Flux, Helm, desired state in Git |
+| `live_runtime` | **cloud-troubleshooter** | Live cluster/cloud diagnostics, pods, logs, runtime drift |
+| `app_ci_tooling` | **devops-developer** | Application code, CI/CD, Docker, build/test tooling |
+
+### Routing Decision Factors
+
+- Detect dominant edit surface from paths, tools, and artifacts named in the task.
+- If the task crosses desired state, live state, and infra/app boundaries, treat it as multi-surface.
+- Ask each agent for evidence: patterns checked, files/paths checked, exact commands run, key outputs, and cross-layer impacts.
+- Use `devops-developer` for narrow reconnaissance when the dominant surface is unclear, not as a silent default owner.
+
+### Unclear or Multi-Surface Tasks
+
+**If the dominant surface is clear:**
+1. Route to that surface's primary agent.
+
+**If multiple surfaces are active:**
+1. Invoke the primary agent for each active surface.
+2. Consolidate findings before implementation or approval.
+
+**If the surface is unclear:**
+1. Ask the user or run a narrow reconnaissance task.
+2. Re-classify after evidence arrives.
+
+## Troubleshooting
+
+### Config Not Found
+
+**Error:**
+```
+ERROR: project-context.json not found
+```
+
+**Solution:**
+Ask the agent to initialize: "initialize speckit for this project" or "bootstrap specs". The agent will ask for project details interactively.
+
+---
+
+### Governance File Not Found
+
+**This should not happen in normal operation.** The agent generates governance.md automatically as Step 0 on first use.
+
+**If it occurs:**
+```
+WARNING: governance.md not found at specs/governance.md
+```
+
+**Solution:**
+Ask the agent: "initialize speckit". The speckit.init skill will generate governance.md from your project-context.json values. Alternatively, ensure `paths.speckit_root` is set in `.claude/project-context/project-context.json`.
+
+---
+
+### Feature Directory Missing
+
+**Error:**
+```
+ERROR: Feature directory not found
+```
+
+**Solution:**
+Tell the orchestrator: "I want to specify a new feature for dark mode". The orchestrator will drive spec creation conversationally and create the directory.
+
+---
+
+### Plan Missing
+
+**Error:**
+```
+ERROR: plan.md not found in specs/specs/003-feature-name
+```
+
+**Solution:**
+Ask the agent: "plan feature 003-feature-name". The agent detects the missing plan.md and runs the plan skill.
+
+---
+
+### Tasks Not Enriched
+
+**Symptoms:**
+- Tasks missing metadata comments
+- No agent assignments
+- No risk tiers
+
+**Solution:**
+Tasks are automatically enriched by the tasks skill and add-task skill. No manual action needed.
+
+**Verify enrichment:**
+```bash
+grep "🤖 Agent:" specs/specs/003-feature-name/tasks.md
+```
+
+---
+
+### Wrong Agent Assigned
+
+**Symptoms:**
+- Task routed to incorrect agent
+- Low confidence score (<0.5) with `⚠️ LOW_CONFIDENCE` warning
+
+**Solution:**
+Edit the metadata comment in tasks.md manually:
+```markdown
+- [ ] T001 Task description
+  <!-- 🤖 Agent: correct-agent | ✅ T1 | ❓ 0.85 -->
+```
+
+---
+
+### High-Risk Task Blocked
+
+**Symptoms:**
+- Task marked with ⚠️ HIGH RISK
+- Agent requests confirmation before proceeding
+
+**This is expected behavior for T2/T3 tasks**
+
+**Solution:**
+1. Review the analysis the agent presents automatically
+2. Confirm "yes" to proceed or "no" to skip
+3. If not safe, ask the agent to modify the approach
+
+---
+
+### JQ Not Installed
+
+**Error:**
+```
+ERROR: jq is required but not installed
+```
+
+**Solution:**
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# Verify installation
+jq --version
+```
+
+## Best Practices
+
+### Configuration Management
+
+- ✅ Run `npx gaia-scan` once per project to generate project-context.json and governance.md
+- ✅ Set `paths.speckit_root` in project-context.json so the agent knows where governance.md lives
+- ✅ Don't hardcode paths in custom scripts
+- ✅ Trust governance auto-sync — don't edit governance.md manually for stack values
+
+### Feature Development
+
+- ✅ Ask "where are we with feature X?" to orient yourself at any time
+- ✅ Let the agent detect the phase — don't force a specific skill
+- ✅ Follow workflow order (specify → plan → tasks → execute)
+- ✅ Let auto-enrichment handle metadata (don't edit manually)
+- ✅ Ask "validate feature X" after implementation to confirm real completion
+
+### Risk Management
+
+- ✅ Always analyze T2/T3 tasks before execution
+- ✅ Review agent assignments for tasks with LOW_CONFIDENCE warnings (score < 0.5)
+- ✅ Keep confidence scores >0.7 for critical operations
+- ✅ Use fallback agents when primary confidence is low
+
+### Git Workflow
+
+- ✅ User controls Git workflow (no auto-branching)
+- ✅ Branch when ready (not enforced by scripts)
+- ✅ Commit regularly during implementation
+- ✅ Use descriptive commit messages
+
+### Documentation
+
+- ✅ Keep governance.md up-to-date with learnings
+- ✅ Document architecture decisions in plan.md
+- ✅ Create research.md for investigation notes
+- ✅ Use contracts/ for API specifications
+
+## References
+
+### Internal Documentation
+
+- `.claude/project-context/project-context.json` - Project-specific context
+- `CLAUDE.md` - Repository guidance for Claude Code
+- `specs/governance.md` - Project governance principles
+
+### Agent and Skills
+
+Agent: `.claude/agents/speckit-planner.md`
+
+Skill: `.claude/skills/speckit-workflow/SKILL.md` (single skill with full workflow logic)
+
+Slash commands in `.claude/commands/`:
+- speckit.init.md
+- speckit.plan.md
+- speckit.tasks.md
+- speckit.add-task.md
+- speckit.analyze-task.md
+
+### Tool Files
+
+- `.claude/tools/context/context_provider.py` - Context provisioning
+- `.claude/tools/context/context_section_reader.py` - Token-optimized context extraction
+- `.claude/tools/memory/episodic.py` - Episodic memory system
+- `.claude/tools/validation/approval_gate.py` - T3 approval workflow
+
+**Framework Base**
+
+Spec-Kit is an open-source framework adapted as agentic functionality for Claude Code. Main modifications:
+
+- ✅ Natural language interaction - No slash commands
+- ✅ Governance auto-sync - governance.md generated and kept in sync automatically
+- ✅ Auto-enrichment - Tasks with routing metadata
+- ✅ Risk analysis - T0-T3 with automatic validation
+- ✅ Multi-project - Simultaneous spec support
+- ✅ Agentic integration - Automatic routing to specialized agents
+
+---
+
+## Support
+
+**For Claude orchestrator:**
+- Spec creation is conversational -- the orchestrator drives it directly with the user
+- Route to `speckit-planner` when the spec is ready and the user wants to plan or generate tasks
+- Task execution is orchestrator-driven -- read tasks.md and route each task to the appropriate agent
+
+**For users:**
+- Describe what you need in natural language
+- Create project directory first: `mkdir -p specs/specs`
+- Ask "where are we?" or "what's next?" at any point to orient yourself
+- Trust auto-enrichment (don't edit metadata manually)
+- The agent will ask for confirmation before any high-risk task
+
+---
+
+**Version:** 4.2.0 | **Updated:** 2026-03-11