@jaguilar87/gaia-ops 1.0.0

package/templates/code-examples/clarification_workflow.py

@@ -0,0 +1,94 @@
+# Phase 0: Clarification Workflow Example
+# Use when user request contains ambiguous terms or missing context
+
+import sys
+sys.path.insert(0, '/home/jaguilar/aaxis/rnd/repositories/.claude/tools')
+from clarify_engine import request_clarification, process_clarification
+
+# Example 1: Detect ambiguity
+def detect_ambiguity(user_prompt: str, command_context: dict):
+    """
+    Detect if user request needs clarification.
+    """
+    clarification_data = request_clarification(
+        user_prompt=user_prompt,
+        command_context=command_context  # {"command": "general_prompt"} or speckit command
+    )
+
+    # Check if clarification needed
+    if not clarification_data["needs_clarification"]:
+        # No ambiguity, proceed with original prompt
+        return {"skip_clarification": True, "prompt": user_prompt}
+
+    # Ambiguity detected, need to ask user
+    return {
+        "skip_clarification": False,
+        "clarification_data": clarification_data
+    }
+
+
+# Example 2: Present clarification questions
+def present_clarification(clarification_data: dict):
+    """
+    Present ambiguity summary and ask questions.
+    """
+    # Show summary to user
+    summary = clarification_data["summary"]
+    print(f"Ambiguity detected: {summary}")
+
+    # Ask questions using AskUserQuestion tool
+    question_config = clarification_data["question_config"]
+    # response = AskUserQuestion(**question_config)
+
+    return question_config
+
+
+# Example 3: Process user responses
+def process_user_responses(clarification_data: dict, user_responses: dict, original_prompt: str):
+    """
+    Generate enriched prompt from user responses.
+    """
+    result = process_clarification(
+        engine_instance=clarification_data["engine_instance"],
+        original_prompt=original_prompt,
+        user_responses=user_responses,
+        clarification_context=clarification_data["clarification_context"]
+    )
+
+    enriched_prompt = result["enriched_prompt"]
+
+    # Example: "revisa el servicio" + {service: "tcm-api", namespace: "tcm-non-prod"}
+    # Becomes: "revisa el servicio tcm-api en el namespace tcm-non-prod"
+
+    return enriched_prompt
+
+
+# Example 4: Full clarification workflow
+def clarification_workflow(user_prompt: str):
+    """
+    Complete Phase 0 workflow.
+    """
+    # Step 1: Detect ambiguity
+    detection = detect_ambiguity(user_prompt, {"command": "general_prompt"})
+
+    if detection["skip_clarification"]:
+        # No clarification needed
+        return detection["prompt"]
+
+    # Step 2: Get clarification data
+    clarification_data = detection["clarification_data"]
+
+    # Step 3: Ask user (via AskUserQuestion tool)
+    question_config = present_clarification(clarification_data)
+    # user_responses = AskUserQuestion(**question_config)  # Simulated
+
+    # Step 4: Process responses and enrich prompt
+    user_responses = {"service": "tcm-api", "namespace": "tcm-non-prod"}  # Example
+    enriched_prompt = process_user_responses(
+        clarification_data,
+        user_responses,
+        user_prompt
+    )
+
+    # Step 5: Use enriched prompt for Phase 1 (Routing)
+    return enriched_prompt

package/templates/code-examples/commit_validation.py

@@ -0,0 +1,86 @@
+# Git Commit Validation Example
+# Use this pattern for ALL commit operations (orchestrator and agents)
+
+import sys
+sys.path.insert(0, '/home/jaguilar/aaxis/rnd/repositories/.claude/tools')
+from commit_validator import safe_validate_before_commit
+
+# Example 1: Orchestrator-level commit (ad-hoc)
+def orchestrator_commit(commit_message: str):
+    """
+    Orchestrator creates ad-hoc commit.
+    """
+    # Validate
+    if not safe_validate_before_commit(commit_message):
+        return {
+            "status": "failed",
+            "reason": "commit_message_validation_failed"
+        }
+
+    # Only if validation passes: proceed with git operations
+    # Execute: git add . && git commit -m "$commit_message"
+    return {"status": "success"}
+
+
+# Example 2: Agent-level commit (realization phase)
+def agent_commit_in_realization(realization_package: dict):
+    """
+    Agent creates commit as part of workflow realization.
+    """
+    commit_message = realization_package["git_operations"]["commit_message"]
+
+    # Validate (same validation as orchestrator)
+    if not safe_validate_before_commit(commit_message):
+        return {
+            "status": "failed",
+            "reason": "commit_message_validation_failed",
+            "message": "Orchestrator provided invalid commit message"
+        }
+
+    # Proceed with git operations
+    # Execute: git add . && git commit -m "$commit_message" && git push
+    return {"status": "success"}
+
+
+# Example 3: Generating commit message
+def generate_commit_message(changes: dict) -> str:
+    """
+    Generate commit message following Conventional Commits.
+    """
+    commit_type = changes.get("type", "chore")  # feat, fix, refactor, etc.
+    scope = changes.get("scope", "")  # helmrelease, terraform, etc.
+    description = changes.get("description", "")  # imperative mood, <72 chars
+
+    if scope:
+        return f"{commit_type}({scope}): {description}"
+    else:
+        return f"{commit_type}: {description}"
+
+
+# Example 4: Handling validation failure
+def commit_with_retry(commit_message: str, max_retries: int = 2):
+    """
+    Attempt commit with validation, regenerate if fails.
+    """
+    for attempt in range(max_retries):
+        if safe_validate_before_commit(commit_message):
+            # Valid, proceed
+            return {"status": "success", "message": commit_message}
+
+        # Invalid, regenerate
+        commit_message = regenerate_commit_message(commit_message, attempt)
+
+    # All attempts failed
+    return {
+        "status": "failed",
+        "reason": "Cannot generate valid commit message after retries"
+    }
+
+
+def regenerate_commit_message(original: str, attempt: int) -> str:
+    """
+    Regenerate commit message after validation failure.
+    """
+    # Implement regeneration logic based on validation errors
+    # Example: shorten if too long, fix imperative mood, remove forbidden footers
+    return original  # Placeholder

package/templates/project-context.template.json

@@ -0,0 +1,126 @@
+{
+  "project_name": "YOUR_PROJECT_NAME",
+  "project_id_gcp": "your-gcp-project-id",
+  "description": "Brief description of your project",
+  "cloud_provider": "GCP",
+  "primary_region": "us-central1",
+
+  "infrastructure": {
+    "clusters": {
+      "primary": {
+        "name": "your-cluster-name",
+        "provider": "GCP",
+        "type": "GKE",
+        "region": "us-central1",
+        "node_pools": [],
+        "networking": {
+          "vpc": "your-vpc-name",
+          "subnet": "your-subnet-name"
+        }
+      }
+    },
+
+    "databases": {
+      "primary_sql": {
+        "name": "your-postgres-instance",
+        "type": "Cloud SQL PostgreSQL",
+        "version": "15",
+        "tier": "db-custom-2-7680",
+        "region": "us-central1"
+      }
+    },
+
+    "artifact_repositories": {
+      "docker": {
+        "name": "your-artifact-registry",
+        "format": "Docker",
+        "location": "us-central1"
+      }
+    }
+  },
+
+  "gitops": {
+    "flux_version": "v2.x",
+    "repositories": {
+      "gitops": {
+        "url": "https://github.com/your-org/your-gitops-repo",
+        "path": "clusters/your-cluster",
+        "branch": "main"
+      }
+    },
+    "namespaces": [
+      "default",
+      "your-app-namespace"
+    ]
+  },
+
+  "services": {
+    "your_service_name": {
+      "description": "Your service description",
+      "type": "backend|frontend|worker",
+      "repository": "https://github.com/your-org/your-service-repo",
+      "deployment": {
+        "namespace": "your-app-namespace",
+        "replicas": 2,
+        "resources": {
+          "requests": {
+            "cpu": "100m",
+            "memory": "256Mi"
+          },
+          "limits": {
+            "cpu": "500m",
+            "memory": "512Mi"
+          }
+        }
+      },
+      "endpoints": {
+        "internal": "http://your-service.your-namespace.svc.cluster.local:8080",
+        "external": "https://your-service.yourdomain.com"
+      }
+    }
+  },
+
+  "terraform": {
+    "version": "1.5+",
+    "backend": {
+      "type": "gcs",
+      "bucket": "your-terraform-state-bucket",
+      "prefix": "your-project/terraform/state"
+    },
+    "modules": [
+      {
+        "name": "gke-cluster",
+        "path": "terraform/modules/gke"
+      }
+    ]
+  },
+
+  "access_patterns": {
+    "kubectl_context": "gke_your-project-id_us-central1_your-cluster-name",
+    "gcloud_project": "your-gcp-project-id"
+  },
+
+  "recent_changes": [],
+
+  "_instructions": {
+    "description": "Template for creating new project contexts",
+    "usage": [
+      "1. Copy this file to your project: cp templates/project-context.template.json .claude/project-context.json",
+      "2. Replace ALL placeholder values (YOUR_*, your-*) with actual values",
+      "3. Remove this _instructions section",
+      "4. Validate JSON syntax: jq . .claude/project-context.json"
+    ],
+    "required_fields": [
+      "project_name",
+      "project_id_gcp",
+      "cloud_provider",
+      "infrastructure.clusters.primary",
+      "access_patterns.kubectl_context"
+    ],
+    "optional_sections": [
+      "databases (if no databases)",
+      "terraform (if not using terraform)",
+      "services (initially empty, add as you develop)"
+    ]
+  }
+}

package/templates/settings.template.json

@@ -0,0 +1,307 @@
+{
+  "system_prompt": "You are part of an intelligent DevOps agent system. Use specialized agents via the Task tool for complex operations.",
+
+  "hooks": {
+    "pre_tool_use": ".claude/hooks/pre_tool_use.py",
+    "post_tool_use": ".claude/hooks/post_tool_use.py",
+    "subagent_stop": ".claude/hooks/subagent_stop.py"
+  },
+
+  "commands": {
+    "speckit.init": {
+      "file": ".claude/commands/speckit.init.md",
+      "description": "Bootstrap Spec-Kit and validate/create project-context.json"
+    },
+    "speckit.specify": {
+      "file": ".claude/commands/speckit.specify.md",
+      "description": "Create feature specification with auto-filled project context"
+    },
+    "speckit.plan": {
+      "file": ".claude/commands/speckit.plan.md",
+      "description": "Generate implementation plan with integrated clarification"
+    },
+    "speckit.tasks": {
+      "file": ".claude/commands/speckit.tasks.md",
+      "description": "Generate enriched task list with validation"
+    },
+    "speckit.implement": {
+      "file": ".claude/commands/speckit.implement.md",
+      "description": "Execute implementation tasks with agent orchestration"
+    },
+    "speckit.add-task": {
+      "file": ".claude/commands/speckit.add-task.md",
+      "description": "Add single task with inline metadata"
+    },
+    "speckit.analyze-task": {
+      "file": ".claude/commands/speckit.analyze-task.md",
+      "description": "Deep analysis of specific task (auto-triggered for T2/T3)"
+    },
+    "save-session": {
+      "file": ".claude/commands/save-session.md",
+      "description": "Export session bundle with active context"
+    }
+  },
+
+  "agents": {
+    "terraform-architect": {
+      "prompt_file": ".claude/agents/terraform-architect.md",
+      "triggers": ["#terraform", "#infrastructure", "terraform", "terragrunt"],
+      "security_tier": ["T0", "T1", "T2"]
+    },
+    "gitops-operator": {
+      "prompt_file": ".claude/agents/gitops-operator.md",
+      "triggers": ["#kubernetes", "#gitops", "#helm", "kubectl", "flux", "helm"],
+      "security_tier": ["T0", "T1", "T2"]
+    },
+    "gcp-troubleshooter": {
+      "prompt_file": ".claude/agents/gcp-troubleshooter.md",
+      "triggers": ["#gcp", "#gke", "gcloud", "GKE", "Cloud SQL"],
+      "security_tier": ["T0"]
+    },
+    "aws-troubleshooter": {
+      "prompt_file": ".claude/agents/aws-troubleshooter.md",
+      "triggers": ["#aws", "#eks", "#ec2", "aws", "EKS", "RDS"],
+      "security_tier": ["T0"]
+    },
+    "devops-developer": {
+      "prompt_file": ".claude/agents/devops-developer.md",
+      "triggers": ["#dockerfile", "#ci", "#pipeline", "docker", "npm", "build"],
+      "security_tier": ["T0", "T1"]
+    }
+  },
+
+  "security": {
+    "default_tier": "T0",
+    "tier_definitions": {
+      "T0": {
+        "name": "Read Only",
+        "description": "describe, get, show, list operations only",
+        "allowed_patterns": [
+          "terraform (fmt|validate|plan|show|output|version)",
+          "kubectl (get|describe|logs|explain|version)",
+          "gcloud .* (describe|list|show|get)",
+          "helm (template|lint|list|status|version)"
+        ]
+      },
+      "T1": {
+        "name": "Validation",
+        "description": "validate, plan, template, lint operations",
+        "allowed_patterns": [
+          "terraform (validate|plan|fmt -check)",
+          "helm (template|lint)",
+          "kubectl .* --dry-run=client"
+        ]
+      },
+      "T2": {
+        "name": "Dry Run",
+        "description": "--dry-run and --plan-only operations",
+        "allowed_patterns": [
+          ".* --dry-run.*",
+          ".* --plan-only.*"
+        ]
+      },
+      "T3": {
+        "name": "Blocked",
+        "description": "apply, reconcile, deploy operations - BLOCKED",
+        "blocked": true
+      }
+    },
+    "always_blocked": [
+      "terraform apply",
+      "terraform destroy",
+      "kubectl apply",
+      "kubectl delete",
+      "helm install",
+      "helm upgrade",
+      "gcloud .* (create|update|delete|patch)"
+    ]
+  },
+
+  "permissions": {
+    "allow": [
+      "Bash(echo \"Generated password for tcm_app: $TCM_APP_PASSWORD\")",
+      "Read(*)",
+      "Glob(*)",
+      "Grep(*)",
+      "Bash(./tests/task-*-validation.sh:*)",
+      "Bash(/home/jaguilar/aaxis/rnd/repositories/tcm-deployment/tests/task-104-validation.sh:*)",
+      "Bash(./spec-kit-tcm-plan/.specify/scripts/bash/check-prerequisites.sh:*)",
+      "Bash(./scripts/dev/setup-local.sh:*)",
+      "Bash(./scripts/dev/test-local-container-stack.sh:*)",
+      "Bash(./scripts/headless/synthesize-bundle.sh:*)",
+      "Bash(./scripts/test-pubsub-flow.sh:*)",
+      "Bash(./scripts/validate-eslint.sh:*)",
+      "Bash(./test-session-intelligence.sh:*)",
+      "Bash(./test-session-intelligence-v2.sh:*)",
+      "Bash(./test-hooks.sh:*)",
+      "Bash(./ssl-validation-test.sh:*)",
+      "Bash(./e2e-test-complete.sh:*)",
+      "Bash(/home/jaguilar/aaxis/rnd/repositories/.claude/tools/quicktriage_gitops_operator.sh:*)",
+      "Bash(/home/jaguilar/aaxis/rnd/repositories/.claude/tools/test_context_reader.sh)",
+      "Bash(chmod:*)",
+      "Bash(tree:*)",
+      "Bash(find:*)",
+      "Bash(cat:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(ls:*)",
+      "Bash(pwd:*)",
+      "Bash(wc:*)",
+      "Bash(diff:*)",
+      "Bash(which:*)",
+      "Bash(whoami:*)",
+      "Bash(date:*)",
+      "Bash(env:*)",
+      "Bash(printenv:*)",
+      "Bash(basename:*)",
+      "Bash(dirname:*)",
+      "Bash(realpath:*)",
+      "Bash(touch:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(tee:*)",
+      "Bash(echo:*)",
+      "Bash(awk:*)",
+      "Bash(sed:*)",
+      "Bash(grep:*)",
+      "Bash(egrep:*)",
+      "Bash(rg:*)",
+      "Bash(jq:*)",
+      "Bash(yq:*)",
+      "Bash(base64:*)",
+      "Bash(sha256sum:*)",
+      "Bash(md5sum:*)",
+      "Bash(nslookup:*)",
+      "Bash(dig:*)",
+      "Bash(openssl:*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)",
+      "Bash(nc:*)",
+      "Bash(ping:*)",
+      "Bash(traceroute:*)",
+      "Bash(PROJECT_ID=\"aaxis-rnd-general-project\")",
+      "Bash(REGION=\"us-central1\")",
+      "Bash(POSTGRES_INSTANCE=\"tcm-postgres-non-prod\")",
+      "Bash(export PUBSUB_EMULATOR_HOST=localhost:8085)",
+      "Bash(terragrunt (output|plan|validate|fmt|init|show|state|graph-dependencies):*)",
+      "Bash(terragrunt run-all (plan|validate|output|init):*)",
+      "Bash(terraform (fmt|validate|plan|show|output|version):*)",
+      "Bash(helm (template|lint|list|status):*)",
+      "Bash(helm show values:*)",
+      "Bash(kubectl (get|describe|logs|top|version):*)",
+      "Bash(kubectl explain:*)",
+      "Bash(kubectl wait:*)",
+      "Bash(kubeseal:*)",
+      "Bash(flux (check|get):*)",
+      "Bash(flux reconcile helmrelease --dry-run:*)",
+      "Bash(flux reconcile kustomization --dry-run:*)",
+      "Bash(flux reconcile helmrelease * --timeout=*)",
+      "Bash(flux reconcile kustomization * --timeout=*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git diff --cached:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git branch:*)",
+      "Bash(gcloud auth:*)",
+      "Bash(gcloud config get-value:*)",
+      "Bash(gcloud config set:*)",
+      "Bash(gcloud .* (describe|list|get):*)",
+      "Bash(gcloud logging read:*)",
+      "Bash(gcloud asset search-all-resources:*)",
+      "Bash(gcloud container clusters describe:*)",
+      "Bash(gcloud container images list:*)",
+      "Bash(gcloud container images describe:*)",
+      "Bash(gcloud compute (describe|list|get)-*:*)",
+      "Bash(gcloud compute backend-services (describe|list|get-health):*)",
+      "Bash(gcloud compute health-checks describe:*)",
+      "Bash(gcloud compute forwarding-rules list:*)",
+      "Bash(gcloud compute url-maps describe:*)",
+      "Bash(gcloud compute ssl-certificates (list|describe):*)",
+      "Bash(gcloud compute ssl-policies list:*)",
+      "Bash(gcloud dns record-sets list:*)",
+      "Bash(gcloud artifacts docker (tags|images) (list|describe):*)",
+      "Bash(gcloud iam service-accounts (list|get-iam-policy|keys list):*)",
+      "Bash(gcloud projects get-iam-policy:*)",
+      "Bash(aws sts get-caller-identity:*)",
+      "Bash(aws eks (describe|list)-*:*)",
+      "Bash(aws elbv2 (describe|list)-*:*)",
+      "Bash(aws ec2 (describe|list)-*:*)",
+      "Bash(aws rds (describe|list)-*:*)",
+      "Bash(aws iam (get|list)-*:*)",
+      "Bash(aws cloudwatch (describe|list)-*:*)",
+      "Bash(aws logs (describe|list)-*:*)",
+      "Bash(aws s3 ls:*)",
+      "Bash(aws ecr (describe|list)-*:*)",
+      "Bash(aws cloudformation (describe|list)-*:*)",
+      "Bash(aws route53 (list|get)-*:*)",
+      "Bash(eksctl get:*)",
+      "Bash(npm run:*)",
+      "Bash(npm test:*)",
+      "Bash(npm run test:*)",
+      "Bash(pnpm run lint:*)",
+      "Bash(pnpm test:*)",
+      "Bash(python3:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(pytest:*)",
+      "Bash(pip install:*)",
+      "Bash(docker (build|run|logs|stop|rm|rmi|exec|compose|ps|images):*)",
+      "Bash(docker-compose:*)",
+      "Bash(time docker build:*)",
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:dify.ai)",
+      "WebFetch(domain:docs.dify.ai)",
+      "WebFetch(domain:docs.aws.amazon.com)",
+      "WebFetch(domain:cloud.google.com)"
+    ],
+    "deny": [],
+    "ask": [
+      "Edit(*)",
+      "Write(*)",
+      "NotebookEdit(*)",
+      "Bash(rm:*)",
+      "Bash(rmdir:*)",
+      "Bash(mv:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(terraform apply:*)",
+      "Bash(kubectl apply:*)",
+      "Bash(kubectl delete:*)",
+      "Bash(helm (install|upgrade):*)",
+      "Bash(gcloud .* (create|update|delete|patch):*)",
+      "Bash(aws .* (create|update|delete|modify|put):*)"
+    ]
+  },
+
+  "routing": {
+    "auto_route_tasks": true,
+    "task_metadata_required": false,
+    "fallback_agent": "devops-developer",
+    "confidence_threshold": 0.7
+  },
+
+  "logging": {
+    "audit_enabled": true,
+    "metrics_enabled": true,
+    "log_directory": ".claude/logs",
+    "metrics_directory": ".claude/metrics",
+    "retention_days": 30
+  },
+
+  "context": {
+    "bundle_directory": "contexts/bundles",
+    "auto_bundle_on_completion": true,
+    "max_bundle_size_mb": 50
+  },
+
+  "environment": {
+    "project_id": "aaxis-rnd-general-project",
+    "region": "us-central1",
+    "cluster_name": "tcm-gke-non-prod",
+    "postgres_instance": "tcm-postgres-non-prod"
+  }
+}