cokit-cli 1.2.7 → 1.4.0

package/templates/repo/.github/skills/ck-common/api_key_helper.py

@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+"""
+Common API Key Detection Helper for Gemini Skills
+
+Supports both Google AI Studio and Vertex AI endpoints.
+
+API Key Detection Order:
+1. Process environment variable
+2. Project root .env file
+3. Skill directory .env file
+
+Vertex AI Configuration:
+- GEMINI_USE_VERTEX: Set to "true" to use Vertex AI endpoint
+- VERTEX_PROJECT_ID: GCP project ID (required for Vertex AI)
+- VERTEX_LOCATION: GCP region (default: us-central1)
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+
+
+def find_api_key(skill_dir: Optional[Path] = None) -> Optional[str]:
+    """
+    Find GEMINI_API_KEY using 3-step lookup:
+    1. Process environment
+    2. Project root .env
+    3. Skill directory .env
+
+    Args:
+        skill_dir: Path to skill directory (optional, auto-detected if None)
+
+    Returns:
+        API key string or None if not found
+    """
+    # Step 1: Check process environment
+    api_key = os.getenv('GEMINI_API_KEY')
+    if api_key:
+        print("✓ Using API key from environment variable", file=sys.stderr)
+        return api_key
+
+    # Determine paths
+    if skill_dir is None:
+        skill_dir = Path(__file__).parent.parent
+    project_dir = skill_dir.parent.parent.parent  # 3 levels up from skill dir
+
+    # Step 2: Check project root .env
+    project_env = project_dir / '.env'
+    if project_env.exists():
+        api_key = load_env_file(project_env)
+        if api_key:
+            print(f"✓ Using API key from {project_env}", file=sys.stderr)
+            return api_key
+
+    # Step 3: Check skill directory .env
+    skill_env = skill_dir / '.env'
+    if skill_env.exists():
+        api_key = load_env_file(skill_env)
+        if api_key:
+            print(f"✓ Using API key from {skill_env}", file=sys.stderr)
+            return api_key
+
+    return None
+
+
+def load_env_file(env_path: Path) -> Optional[str]:
+    """
+    Load GEMINI_API_KEY from .env file
+
+    Args:
+        env_path: Path to .env file
+
+    Returns:
+        API key or None
+    """
+    try:
+        with open(env_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith('GEMINI_API_KEY='):
+                    # Extract value, removing quotes if present
+                    value = line.split('=', 1)[1].strip()
+                    value = value.strip('"').strip("'")
+                    if value:
+                        return value
+    except Exception as e:
+        print(f"Warning: Error reading {env_path}: {e}", file=sys.stderr)
+
+    return None
+
+
+def load_env_var(env_path: Path, var_name: str) -> Optional[str]:
+    """
+    Load a specific environment variable from .env file
+
+    Args:
+        env_path: Path to .env file
+        var_name: Name of the environment variable
+
+    Returns:
+        Variable value or None
+    """
+    try:
+        with open(env_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith(f'{var_name}='):
+                    value = line.split('=', 1)[1].strip()
+                    value = value.strip('"').strip("'")
+                    if value:
+                        return value
+    except Exception as e:
+        print(f"Warning: Error reading {env_path}: {e}", file=sys.stderr)
+
+    return None
+
+
+def find_env_var(var_name: str, skill_dir: Optional[Path] = None) -> Optional[str]:
+    """
+    Find environment variable using 3-step lookup (same as API key)
+
+    Args:
+        var_name: Name of environment variable
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        Variable value or None
+    """
+    # Step 1: Check process environment
+    value = os.getenv(var_name)
+    if value:
+        return value
+
+    # Determine paths
+    if skill_dir is None:
+        skill_dir = Path(__file__).parent.parent
+    project_dir = skill_dir.parent.parent.parent
+
+    # Step 2-3: Check .env files in order
+    env_files = [
+        project_dir / '.env',
+        skill_dir / '.env'
+    ]
+
+    for env_path in env_files:
+        if env_path.exists():
+            value = load_env_var(env_path, var_name)
+            if value:
+                return value
+
+    return None
+
+
+def find_all_api_keys(skill_dir: Optional[Path] = None) -> List[str]:
+    """
+    Find all Gemini API keys for rotation.
+
+    Searches for:
+    - GEMINI_API_KEY (primary, required)
+    - GEMINI_API_KEY_2, GEMINI_API_KEY_3, ... (additional, optional)
+
+    Uses the same 5-step lookup as find_api_key().
+
+    Args:
+        skill_dir: Path to skill directory (optional, auto-detected if None)
+
+    Returns:
+        List of API keys (may be empty if none found)
+    """
+    keys: List[str] = []
+    seen: set = set()  # Deduplicate keys
+
+    # Determine paths
+    if skill_dir is None:
+        skill_dir = Path(__file__).parent.parent
+    project_dir = skill_dir.parent.parent.parent
+
+    # Collect all .env file paths in priority order
+    env_files = [
+        project_dir / '.env',
+        skill_dir / '.env'
+    ]
+
+    def add_key(key: Optional[str]) -> None:
+        """Add key if valid and not duplicate."""
+        if key and key not in seen:
+            seen.add(key)
+            keys.append(key)
+
+    # Step 1: Check process environment for all GEMINI_API_KEY* vars
+    for env_key, value in os.environ.items():
+        if env_key == 'GEMINI_API_KEY' or re.match(r'^GEMINI_API_KEY_\d+$', env_key):
+            add_key(value)
+
+    # Step 2-5: Check .env files
+    for env_path in env_files:
+        if not env_path.exists():
+            continue
+
+        # Load all GEMINI_API_KEY* from this file
+        file_keys = _load_all_api_keys_from_file(env_path)
+        for key in file_keys:
+            add_key(key)
+
+    return keys
+
+
+def _load_all_api_keys_from_file(env_path: Path) -> List[str]:
+    """
+    Load all GEMINI_API_KEY* variables from an .env file.
+
+    Args:
+        env_path: Path to .env file
+
+    Returns:
+        List of API keys found in the file
+    """
+    keys: List[str] = []
+    pattern = re.compile(r'^GEMINI_API_KEY(_\d+)?=(.+)$')
+
+    try:
+        with open(env_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith('#') or not line:
+                    continue
+
+                match = pattern.match(line)
+                if match:
+                    value = match.group(2).strip()
+                    # Remove quotes if present
+                    value = value.strip('"').strip("'")
+                    if value and value != 'your_api_key_here':
+                        keys.append(value)
+    except Exception as e:
+        print(f"Warning: Error reading {env_path}: {e}", file=sys.stderr)
+
+    return keys
+
+
+def get_key_rotator(skill_dir: Optional[Path] = None, verbose: bool = False):
+    """
+    Get a KeyRotator instance with all available API keys.
+
+    Args:
+        skill_dir: Path to skill directory (optional)
+        verbose: Whether to enable verbose logging
+
+    Returns:
+        KeyRotator instance or None if no keys found
+    """
+    # Import here to avoid circular dependency
+    from api_key_rotator import KeyRotator
+
+    keys = find_all_api_keys(skill_dir)
+    if not keys:
+        return None
+
+    return KeyRotator(keys=keys, verbose=verbose)
+
+
+def get_vertex_config(skill_dir: Optional[Path] = None) -> Dict[str, Any]:
+    """
+    Get Vertex AI configuration from environment variables
+
+    Args:
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        Dictionary with Vertex AI configuration:
+        {
+            'use_vertex': bool,
+            'project_id': str or None,
+            'location': str (default: 'us-central1')
+        }
+    """
+    use_vertex_str = find_env_var('GEMINI_USE_VERTEX', skill_dir)
+    use_vertex = use_vertex_str and use_vertex_str.lower() in ('true', '1', 'yes')
+
+    config = {
+        'use_vertex': use_vertex,
+        'project_id': find_env_var('VERTEX_PROJECT_ID', skill_dir) if use_vertex else None,
+        'location': find_env_var('VERTEX_LOCATION', skill_dir) or 'us-central1'
+    }
+
+    return config
+
+
+def get_api_key_or_exit(skill_dir: Optional[Path] = None) -> str:
+    """
+    Get API key or exit with helpful error message
+
+    Args:
+        skill_dir: Path to skill directory (optional, auto-detected if None)
+
+    Returns:
+        API key string
+    """
+    api_key = find_api_key(skill_dir)
+
+    if not api_key:
+        print("\n❌ Error: GEMINI_API_KEY not found!", file=sys.stderr)
+        print("\n📋 Please set your API key using one of these methods (in priority order):", file=sys.stderr)
+
+        if skill_dir is None:
+            skill_dir = Path(__file__).parent.parent
+        project_dir = skill_dir.parent.parent.parent
+
+        print("\n1️⃣  Environment variable (recommended for development):", file=sys.stderr)
+        print("   export GEMINI_API_KEY='your-api-key'", file=sys.stderr)
+
+        print("\n2️⃣  Project root .env file:", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.env", file=sys.stderr)
+
+        print("\n3️⃣  Skill directory .env file:", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {skill_dir}/.env", file=sys.stderr)
+
+        print("\n🔑 Get your API key at: https://aistudio.google.com/apikey", file=sys.stderr)
+        print("\n💡 Tip: Add .env files to .gitignore to avoid committing API keys", file=sys.stderr)
+        sys.exit(1)
+
+    return api_key
+
+
+def get_client(skill_dir: Optional[Path] = None):
+    """
+    Get appropriate Gemini client (AI Studio or Vertex AI)
+
+    Args:
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        genai.Client or vertexai client
+    """
+    vertex_config = get_vertex_config(skill_dir)
+
+    if vertex_config['use_vertex']:
+        # Use Vertex AI
+        import vertexai
+        from vertexai.generative_models import GenerativeModel
+
+        if not vertex_config['project_id']:
+            print("\n❌ Error: VERTEX_PROJECT_ID required when GEMINI_USE_VERTEX=true!", file=sys.stderr)
+            print("\n📋 Set your GCP project ID:", file=sys.stderr)
+            print("   export VERTEX_PROJECT_ID='your-project-id'", file=sys.stderr)
+            print("   Or add to .env file: VERTEX_PROJECT_ID=your-project-id", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"✓ Using Vertex AI endpoint", file=sys.stderr)
+        print(f"  Project: {vertex_config['project_id']}", file=sys.stderr)
+        print(f"  Location: {vertex_config['location']}", file=sys.stderr)
+
+        vertexai.init(
+            project=vertex_config['project_id'],
+            location=vertex_config['location']
+        )
+
+        return {'type': 'vertex', 'config': vertex_config}
+    else:
+        # Use AI Studio
+        from google import genai
+
+        api_key = get_api_key_or_exit(skill_dir)
+        client = genai.Client(api_key=api_key)
+
+        return {'type': 'aistudio', 'client': client}
+
+
+if __name__ == '__main__':
+    # Test the API key detection
+    api_key = get_api_key_or_exit()
+    print(f"✓ Found API key: {api_key[:8]}..." + "*" * (len(api_key) - 8))
+
+    # Test Vertex AI config
+    vertex_config = get_vertex_config()
+    if vertex_config['use_vertex']:
+        print(f"\n✓ Vertex AI enabled:")
+        print(f"  Project: {vertex_config['project_id']}")
+        print(f"  Location: {vertex_config['location']}")

package/templates/repo/.github/skills/ck-context-engineering/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: ck-context-engineering
+description: >-
+  Check context usage limits, monitor time remaining, optimize token consumption, debug context failures.
+  Use when asking about context percentage, rate limits, usage warnings, context optimization, agent architectures, memory systems.
+argument-hint: "[topic or question]"
+---
+
+# Context Engineering
+
+Context engineering curates the smallest high-signal token set for LLM tasks. The goal: maximize reasoning quality while minimizing token usage.
+
+## When to Activate
+
+- Designing/debugging agent systems
+- Context limits constrain performance
+- Optimizing cost/latency
+- Building multi-agent coordination
+- Implementing memory systems
+- Evaluating agent performance
+- Developing LLM-powered pipelines
+
+## Core Principles
+
+1. **Context quality > quantity** - High-signal tokens beat exhaustive content
+2. **Attention is finite** - U-shaped curve favors beginning/end positions
+3. **Progressive disclosure** - Load information just-in-time
+4. **Isolation prevents degradation** - Partition work across sub-agents
+5. **Measure before optimizing** - Know your baseline
+
+**IMPORTANT:**
+- Sacrifice grammar for the sake of concision.
+- Ensure token efficiency while maintaining high quality.
+- Pass these rules to subagents.
+
+## Quick Reference
+
+| Topic | When to Use | Reference |
+|-------|-------------|-----------|
+| **Fundamentals** | Understanding context anatomy, attention mechanics | [context-fundamentals.md](./references/context-fundamentals.md) |
+| **Degradation** | Debugging failures, lost-in-middle, poisoning | [context-degradation.md](./references/context-degradation.md) |
+| **Optimization** | Compaction, masking, caching, partitioning | [context-optimization.md](./references/context-optimization.md) |
+| **Compression** | Long sessions, summarization strategies | [context-compression.md](./references/context-compression.md) |
+| **Memory** | Cross-session persistence, knowledge graphs | [memory-systems.md](./references/memory-systems.md) |
+| **Multi-Agent** | Coordination patterns, context isolation | [multi-agent-patterns.md](./references/multi-agent-patterns.md) |
+| **Evaluation** | Testing agents, LLM-as-Judge, metrics | [evaluation.md](./references/evaluation.md) |
+| **Tool Design** | Tool consolidation, description engineering | [tool-design.md](./references/tool-design.md) |
+| **Pipelines** | Project development, batch processing | [project-development.md](./references/project-development.md) |
+| **Runtime Awareness** | Usage limits, context window monitoring | [runtime-awareness.md](./references/runtime-awareness.md) |
+
+## Key Metrics
+
+- **Token utilization**: Warning at 70%, trigger optimization at 80%
+- **Token variance**: Explains 80% of agent performance variance
+- **Multi-agent cost**: ~15x single agent baseline
+- **Compaction target**: 50-70% reduction, <5% quality loss
+- **Cache hit target**: 70%+ for stable workloads
+
+## Four-Bucket Strategy
+
+1. **Write**: Save context externally (scratchpads, files)
+2. **Select**: Pull only relevant context (retrieval, filtering)
+3. **Compress**: Reduce tokens while preserving info (summarization)
+4. **Isolate**: Split across sub-agents (partitioning)
+
+## Anti-Patterns
+
+- Exhaustive context over curated context
+- Critical info in middle positions
+- No compaction triggers before limits
+- Single agent for parallelizable tasks
+- Tools without clear descriptions
+
+## Guidelines
+
+1. Place critical info at beginning/end of context
+2. Implement compaction at 70-80% utilization
+3. Use sub-agents for context isolation, not role-play
+4. Design tools with 4-question framework (what, when, inputs, returns)
+5. Optimize for tokens-per-task, not tokens-per-request
+6. Validate with probe-based evaluation
+7. Monitor KV-cache hit rates in production
+8. Start minimal, add complexity only when proven necessary
+
+## Runtime Awareness
+
+The system automatically injects usage awareness via PostToolUse hook:
+
+```xml
+<usage-awareness>
+AI Usage Limits: 5h=45%, 7d=32%
+Context Window Usage: 67%
+</usage-awareness>
+```
+
+**Thresholds:**
+- 70%: WARNING - consider optimization/compaction
+- 90%: CRITICAL - immediate action needed
+
+**Data Sources:**
+- Usage limits: Anthropic OAuth API (`https://api.anthropic.com/api/oauth/usage`)
+- Context window: Statusline temp file (`/tmp/ck-context-{session_id}.json`)
+
+## Scripts
+
+- [context_analyzer.py](./scripts/context_analyzer.py) - Context health analysis, degradation detection
+- [compression_evaluator.py](./scripts/compression_evaluator.py) - Compression quality evaluation

package/templates/repo/.github/skills/ck-context-engineering/references/context-degradation.md

@@ -0,0 +1,93 @@
+# Context Degradation Patterns
+
+Predictable degradation as context grows. Not binary - a continuum.
+
+## Degradation Patterns
+
+| Pattern | Cause | Detection |
+|---------|-------|-----------|
+| **Lost-in-Middle** | U-shaped attention | Critical info recall drops 10-40% |
+| **Context Poisoning** | Errors compound via reference | Persistent hallucinations despite correction |
+| **Context Distraction** | Irrelevant info overwhelms | Single distractor degrades performance |
+| **Context Confusion** | Multiple tasks mix | Wrong tool calls, mixed requirements |
+| **Context Clash** | Contradictory info | Conflicting outputs, inconsistent reasoning |
+
+## Lost-in-Middle Phenomenon
+
+- Information in middle gets 10-40% lower recall
+- Models allocate massive attention to first token (BOS sink)
+- As context grows, middle tokens fail to get sufficient attention
+- **Mitigation**: Place critical info at beginning/end
+
+```markdown
+[CURRENT TASK]              # Beginning - high attention
+- Critical requirements
+
+[DETAILED CONTEXT]          # Middle - lower attention
+- Supporting details
+
+[KEY FINDINGS]              # End - high attention
+- Important conclusions
+```
+
+## Context Poisoning
+
+**Entry points**:
+1. Tool outputs with errors/unexpected formats
+2. Retrieved docs with incorrect/outdated info
+3. Model-generated summaries with hallucinations
+
+**Detection symptoms**:
+- Degraded quality on previously successful tasks
+- Tool misalignment (wrong tools/parameters)
+- Persistent hallucinations
+
+**Recovery**:
+- Truncate to before poisoning point
+- Explicit note + re-evaluation request
+- Restart with clean context, preserve only verified info
+
+## Model Degradation Thresholds
+
+| Model | Degradation Onset | Severe Degradation |
+|-------|-------------------|-------------------|
+| GPT-5.2 | ~64K tokens | ~200K tokens |
+| Opus 4.5 | ~100K tokens | ~180K tokens |
+| Sonnet 4.5 | ~80K tokens | ~150K tokens |
+| Gemini 3 Pro | ~500K tokens | ~800K tokens |
+
+## Four-Bucket Mitigation
+
+1. **Write**: Save externally (scratchpads, files)
+2. **Select**: Pull only relevant (retrieval, filtering)
+3. **Compress**: Reduce tokens (summarization)
+4. **Isolate**: Split across sub-agents (partitioning)
+
+## Detection Heuristics
+
+```python
+def calculate_health(utilization, degradation_risk, poisoning_risk):
+    """Health score: 1.0 = healthy, 0.0 = critical"""
+    score = 1.0
+    score -= utilization * 0.5 if utilization > 0.7 else 0
+    score -= degradation_risk * 0.3
+    score -= poisoning_risk * 0.2
+    return max(0, score)
+
+# Thresholds: healthy >0.8, warning >0.6, degraded >0.4, critical <=0.4
+```
+
+## Guidelines
+
+1. Monitor context length vs performance correlation
+2. Place critical info at beginning/end
+3. Implement compaction before degradation
+4. Validate retrieved docs before adding
+5. Use versioning to prevent outdated clash
+6. Segment tasks to prevent confusion
+7. Design for graceful degradation
+
+## Related Topics
+
+- [Context Optimization](./context-optimization.md) - Mitigation techniques
+- [Multi-Agent Patterns](./multi-agent-patterns.md) - Isolation strategies