@jaguilar87/gaia-ops 1.0.0

package/tools/agent_capabilities.json

@@ -0,0 +1,231 @@
+{
+  "schema_version": "1.0",
+  "last_updated": "2025-09-25",
+  "routing_matrix": {
+    "skills": {
+      "infrastructure_planning": {
+        "primary_agent": "terraform-architect",
+        "fallback_agent": "devops-developer",
+        "base_tier": "T1",
+        "confidence_boost": 0.4,
+        "keywords": ["infrastructure", "architecture", "planning", "design", "resource", "networking"],
+        "file_patterns": ["*.tf", "*.tfvars", "terragrunt.hcl", "infrastructure/", "terraform/"],
+        "priority_indicators": {
+          "high_impact": ["production", "critical", "security", "compliance"],
+          "uncertain": ["experimental", "prototype", "poc", "investigate"],
+          "time_sensitive": ["emergency", "hotfix", "urgent", "immediate"]
+        }
+      },
+      "terraform_operations": {
+        "primary_agent": "terraform-architect",
+        "fallback_agent": "devops-developer",
+        "base_tier": "T1",
+        "confidence_boost": 0.5,
+        "keywords": ["terraform", "terragrunt", "module", "state", "plan", "apply", "destroy"],
+        "file_patterns": ["*.tf", "*.tfvars", "*.hcl"],
+        "command_patterns": ["terraform", "terragrunt", "tflint", "checkov"],
+        "security_rules": {
+          "T0": ["show", "output", "graph", "version", "fmt", "validate"],
+          "T1": ["plan", "validate", "fmt", "init"],
+          "T2": ["plan -detailed-exitcode"],
+          "T3": ["apply", "destroy", "import", "taint", "untaint"]
+        }
+      },
+      "kubernetes_deployment": {
+        "primary_agent": "gitops-operator",
+        "fallback_agent": "devops-developer",
+        "base_tier": "T0",
+        "confidence_boost": 0.4,
+        "keywords": ["kubernetes", "k8s", "deployment", "service", "pod", "manifest", "yaml"],
+        "file_patterns": ["*.yaml", "*.yml", "manifests/", "k8s/"],
+        "command_patterns": ["kubectl"],
+        "security_rules": {
+          "T0": ["get", "describe", "logs", "port-forward"],
+          "T1": ["diff", "dry-run", "validate", "explain"],
+          "T2": ["apply --dry-run", "create --dry-run"],
+          "T3": ["apply", "create", "delete", "patch", "replace"]
+        }
+      },
+      "helm_management": {
+        "primary_agent": "gitops-operator",
+        "fallback_agent": "devops-developer",
+        "base_tier": "T1",
+        "confidence_boost": 0.3,
+        "keywords": ["helm", "chart", "values", "template", "release"],
+        "file_patterns": ["Chart.yaml", "values.yaml", "templates/", "charts/"],
+        "command_patterns": ["helm"],
+        "security_rules": {
+          "T0": ["list", "status", "get", "history"],
+          "T1": ["template", "lint", "test"],
+          "T2": ["install --dry-run", "upgrade --dry-run"],
+          "T3": ["install", "upgrade", "uninstall", "rollback"]
+        }
+      },
+      "gcp_operations": {
+        "primary_agent": "gcp-troubleshooter",
+        "fallback_agent": "devops-developer",
+        "base_tier": "T0",
+        "confidence_boost": 0.4,
+        "keywords": ["gcp", "gke", "gcloud", "google cloud", "cloud sql", "monitoring"],
+        "file_patterns": ["gcp/", "google-cloud/"],
+        "command_patterns": ["gcloud", "gsutil", "bq"],
+        "security_rules": {
+          "T0": ["describe", "list", "get-iam-policy", "logs"],
+          "T1": ["config", "auth", "info"],
+          "T2": ["--dry-run", "simulate"],
+          "T3": ["create", "delete", "update", "set-iam-policy"]
+        }
+      },
+      "aws_operations": {
+        "primary_agent": "aws-troubleshooter",
+        "fallback_agent": "devops-developer",
+        "base_tier": "T0",
+        "confidence_boost": 0.4,
+        "keywords": ["aws", "eks", "cloudformation", "cloudwatch", "ec2", "s3"],
+        "file_patterns": ["aws/", "cloudformation/"],
+        "command_patterns": ["aws", "eksctl"],
+        "security_rules": {
+          "T0": ["describe", "list", "get", "logs"],
+          "T1": ["validate", "estimate-cost"],
+          "T2": ["--dry-run", "simulate"],
+          "T3": ["create", "delete", "update", "deploy"]
+        }
+      },
+      "application_development": {
+        "primary_agent": "devops-developer",
+        "fallback_agent": "gitops-operator",
+        "base_tier": "T1",
+        "confidence_boost": 0.3,
+        "keywords": ["application", "code", "api", "frontend", "backend", "service"],
+        "file_patterns": ["src/", "app/", "*.js", "*.ts", "*.py", "package.json"],
+        "command_patterns": ["npm", "node", "python", "pytest"],
+        "security_rules": {
+          "T0": ["test", "lint", "format", "check"],
+          "T1": ["build", "compile", "validate"],
+          "T2": ["install --dry-run", "preview"],
+          "T3": ["deploy", "publish", "release"]
+        }
+      },
+      "testing_validation": {
+        "primary_agent": "devops-developer",
+        "fallback_agent": "gitops-operator",
+        "base_tier": "T1",
+        "confidence_boost": 0.5,
+        "keywords": ["test", "testing", "validation", "unit", "integration", "contract", "security"],
+        "file_patterns": ["tests/", "test/", "*test*", "*spec*"],
+        "command_patterns": ["pytest", "jest", "npm test"],
+        "security_rules": {
+          "T1": ["test", "validate", "lint", "security scan", "contract test"]
+        },
+        "priority_indicators": {
+          "critical": ["security", "contract", "integration"],
+          "high_confidence": ["unit", "validation", "lint"]
+        }
+      },
+      "documentation_creation": {
+        "primary_agent": "devops-developer",
+        "fallback_agent": "gitops-operator",
+        "base_tier": "T1",
+        "confidence_boost": 0.2,
+        "keywords": ["documentation", "docs", "guide", "readme", "manual"],
+        "file_patterns": ["*.md", "docs/", "README*"],
+        "security_rules": {
+          "T1": ["create", "update", "write", "document"]
+        }
+      },
+      "configuration_management": {
+        "primary_agent": "gitops-operator",
+        "fallback_agent": "devops-developer",
+        "base_tier": "T0",
+        "confidence_boost": 0.3,
+        "keywords": ["config", "configuration", "configmap", "secret", "environment"],
+        "file_patterns": ["config/", "*.conf", "*.ini", "*.env"],
+        "security_rules": {
+          "T0": ["create configmap", "update configuration"],
+          "T1": ["validate config", "lint configuration"],
+          "T3": ["secret", "credential", "key", "password", "token"]
+        }
+      },
+      "monitoring_observability": {
+        "primary_agent": "gcp-troubleshooter",
+        "fallback_agent": "aws-troubleshooter",
+        "base_tier": "T0",
+        "confidence_boost": 0.3,
+        "keywords": ["monitoring", "metrics", "logging", "observability", "health", "alerts"],
+        "file_patterns": ["monitoring/", "metrics/", "alerts/"],
+        "security_rules": {
+          "T0": ["health check", "monitoring", "metrics", "logs"],
+          "T1": ["configure monitoring", "setup alerts"]
+        }
+      }
+    },
+    "taxonomies": {
+      "service_types": {
+        "api": ["rest", "graphql", "grpc", "endpoint", "service"],
+        "web": ["frontend", "ui", "interface", "webapp", "client"],
+        "data": ["database", "storage", "persistence", "cache", "queue"],
+        "infrastructure": ["network", "compute", "storage", "security", "monitoring"]
+      },
+      "domains": {
+        "training": ["tcm", "compliance", "training", "certification", "course"],
+        "platform": ["kubernetes", "cloud", "infrastructure", "devops"],
+        "security": ["auth", "sso", "rbac", "encryption", "compliance"],
+        "integration": ["api", "webhook", "event", "message", "sync"]
+      },
+      "artifact_types": {
+        "code": ["implementation", "feature", "function", "class", "module"],
+        "config": ["manifest", "values", "environment", "settings"],
+        "test": ["unit", "integration", "contract", "performance", "security"],
+        "docs": ["readme", "guide", "manual", "specification", "architecture"]
+      }
+    },
+    "priority_signals": {
+      "thresholds": {
+        "high_impact": 0.8,
+        "medium_impact": 0.5,
+        "low_impact": 0.2,
+        "high_uncertainty": 0.7,
+        "medium_uncertainty": 0.4,
+        "low_uncertainty": 0.1,
+        "time_critical": 0.9,
+        "time_sensitive": 0.6,
+        "normal_priority": 0.3
+      },
+      "signal_mapping": {
+        "🎯": "high_confidence_critical",
+        "⚡": "high_impact_fast",
+        "❓": "uncertain_investigate",
+        "🚨": "critical_immediate",
+        "⚠️": "caution_required",
+        "✅": "validated_safe"
+      }
+    }
+  },
+  "fallback_rules": {
+    "confidence_threshold": 0.7,
+    "default_agent": "devops-developer",
+    "escalation_triggers": [
+      "multiple_agents_equal_score",
+      "confidence_below_threshold",
+      "security_tier_mismatch",
+      "critical_priority_detected"
+    ]
+  },
+  "integration_metadata": {
+    "bundle_fields": [
+      "suggested_agent",
+      "confidence_score",
+      "security_tier",
+      "priority_signal",
+      "routing_reasoning",
+      "fallback_options",
+      "skill_matches"
+    ],
+    "handshake_validation": {
+      "verify_agent_match": true,
+      "verify_tier_compatibility": true,
+      "require_approval_on_mismatch": true,
+      "log_routing_decisions": true
+    }
+  }
+}

package/tools/agent_invoker_helper.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""
+Agent Invoker Helper - Context Pre-Loading Pattern
+
+This helper demonstrates the CORRECT pattern for invoking specialized agents
+with pre-loaded, filtered context from project-context.json.
+
+Philosophy:
+- Claude orchestrator (main conversation) pre-loads context BEFORE invoking agents
+- Agents receive everything in the prompt - NO file reads needed
+- 50-76% token savings per agent invocation
+
+Usage:
+    from .claude.tools.agent_invoker_helper import AgentInvokerHelper
+
+    helper = AgentInvokerHelper()
+
+    # Get pre-loaded context for terraform-architect
+    context = helper.get_agent_context('terraform-architect')
+
+    # Build prompt with pre-loaded context
+    prompt = helper.build_prompt(
+        agent='terraform-architect',
+        task_description='Clean up legacy TCM resources',
+        instructions=[
+            'Identify all Terraform modules...',
+            'Create a plan showing...',
+            'Generate instructions...'
+        ]
+    )
+
+    # Invoke agent with pre-loaded context
+    Task(
+        subagent_type='terraform-architect',
+        description='Clean up legacy TCM resources',
+        prompt=prompt
+    )
+"""
+
+from pathlib import Path
+from typing import List, Optional, Dict
+import json
+
+
+class AgentInvokerHelper:
+    """Helper for invoking agents with pre-loaded, filtered context."""
+
+    def __init__(self):
+        """Initialize the helper with context reader."""
+        from context_section_reader import ContextSectionReader
+        self.reader = ContextSectionReader()
+
+    def get_agent_context(self, agent_name: str) -> str:
+        """
+        Get pre-filtered context for a specific agent.
+
+        Args:
+            agent_name: Name of the agent (e.g., 'terraform-architect')
+
+        Returns:
+            Markdown string with pre-filtered context sections
+
+        Example:
+            context = helper.get_agent_context('terraform-architect')
+            # Returns ~145 lines, ~580 tokens (vs 1,312 tokens full)
+        """
+        return self.reader.get_for_agent(agent_name)
+
+    def get_token_savings(self, agent_name: str) -> Dict:
+        """
+        Get token savings estimate for context pre-loading.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Dictionary with token counts and savings percentage
+        """
+        return self.reader.get_agent_stats(agent_name)
+
+    def build_prompt(
+        self,
+        agent: str,
+        task_description: str,
+        instructions: List[str],
+        additional_context: Optional[str] = None
+    ) -> str:
+        """
+        Build a prompt with pre-loaded context for an agent.
+
+        This is the CORRECT pattern - context comes in the prompt, not from files.
+
+        Args:
+            agent: Agent name (e.g., 'terraform-architect')
+            task_description: High-level description of the task
+            instructions: List of specific instructions
+            additional_context: Optional additional context
+
+        Returns:
+            Complete prompt with pre-loaded context
+
+        Example:
+            prompt = helper.build_prompt(
+                agent='terraform-architect',
+                task_description='Clean up TCM resources',
+                instructions=[
+                    'List modules in /terraform/tf_live/rnd/',
+                    'Create plan for tcm-vpc removal',
+                    'Do NOT execute destroy'
+                ]
+            )
+        """
+        # Get pre-filtered context for this agent
+        context = self.get_agent_context(agent)
+
+        # Build instruction section
+        instruction_text = '\n'.join([f'{i+1}. {instr}' for i, instr in enumerate(instructions)])
+
+        # Construct prompt
+        prompt = f"""# Project Context (Pre-Loaded for {agent})
+
+{context}
+
+---
+
+# Task Description
+
+{task_description}
+
+# Task Instructions
+
+{instruction_text}
+"""
+
+        if additional_context:
+            prompt += f"""
+# Additional Context
+
+{additional_context}
+"""
+
+        return prompt
+
+    def invoke_agent_with_context(
+        self,
+        agent_name: str,
+        task_description: str,
+        instructions: List[str],
+        additional_context: Optional[str] = None
+    ) -> str:
+        """
+        Generate a complete Task tool invocation with pre-loaded context.
+
+        This shows how to invoke agents the CORRECT way.
+
+        Args:
+            agent_name: Agent to invoke
+            task_description: Task description
+            instructions: Task instructions
+            additional_context: Optional additional context
+
+        Returns:
+            Python code snippet ready for Task() invocation
+        """
+        prompt = self.build_prompt(
+            agent=agent_name,
+            task_description=task_description,
+            instructions=instructions,
+            additional_context=additional_context
+        )
+
+        code_snippet = f'''# CORRECT INVOCATION PATTERN
+Task(
+    subagent_type='{agent_name}',
+    description='{task_description}',
+    prompt=f"""
+{prompt}
+"""
+)
+'''
+        return code_snippet
+
+    def print_agent_stats(self) -> None:
+        """Print token savings statistics for all agents."""
+        print("\n📊 Token Savings by Agent (Context Pre-Loading)\n")
+        print("Agent                      | Lines | Tokens | Savings")
+        print("-" * 60)
+
+        for agent in self.reader.AGENT_SECTIONS.keys():
+            stats = self.reader.get_agent_stats(agent)
+            print(
+                f"{agent:26} | {stats['lines_loaded']:5} | "
+                f"{stats['tokens_estimated']:6} | {stats['savings']['percentage']:.1f}%"
+            )
+
+        full_stats = self.reader.get_stats()
+        print("\n" + "=" * 60)
+        print(f"Full project-context.json: {full_stats['total_lines']} lines, "
+              f"{full_stats['total_tokens_estimated']} tokens")
+        print("=" * 60)
+
+
+# Example usage showing the CORRECT pattern
+if __name__ == '__main__':
+    helper = AgentInvokerHelper()
+
+    # Show stats
+    helper.print_agent_stats()
+
+    print("\n\n" + "="*70)
+    print("EXAMPLE: Invoking terraform-architect with pre-loaded context")
+    print("="*70 + "\n")
+
+    # Build example prompt
+    example_prompt = helper.build_prompt(
+        agent='terraform-architect',
+        task_description='Clean up legacy TCM resources',
+        instructions=[
+            'Identify all Terraform modules in /terraform/tf_live/rnd/',
+            'Create a plan showing what will be destroyed',
+            'Do NOT execute destroy - only plan and document'
+        ]
+    )
+
+    print(example_prompt[:500] + "...\n")
+
+    print("\n" + "="*70)
+    print("CORRECT INVOCATION CODE:")
+    print("="*70 + "\n")
+
+    print(helper.invoke_agent_with_context(
+        agent_name='terraform-architect',
+        task_description='Clean up legacy TCM resources',
+        instructions=[
+            'Identify all Terraform modules in /terraform/tf_live/rnd/',
+            'Create a plan showing what will be destroyed',
+            'Do NOT execute destroy - only plan and document'
+        ]
+    ))