@stella-studio/ck 1.0.0

package/.claude/skills/gkg/references/language-support.md

@@ -0,0 +1,57 @@
+# GKG Language Support
+
+## Support Matrix
+
+| Language | Definitions | Imports | Intra-file Refs | Cross-file Refs |
+|----------|-------------|---------|-----------------|-----------------|
+| Ruby | ✅ | ✅ | ✅ | ✅ |
+| Java | ✅ | ✅ | ✅ | ✅ |
+| Kotlin | ✅ | ✅ | ✅ | ✅ |
+| Python | ✅ | ✅ | ✅ | 🚧 |
+| TypeScript | ✅ | ✅ | ✅ | 🚧 |
+| JavaScript | ✅ | ✅ | ✅ | 🚧 |
+
+## Feature Definitions
+
+**Definitions**: Classes, functions, methods, constants, interfaces extracted from AST.
+
+**Imports**: Module/package imports tracked for dependency analysis.
+
+**Intra-file Refs**: References to symbols within same file.
+
+**Cross-file Refs**: References to symbols defined in other files. Critical for impact analysis.
+
+## Fully Supported (Ruby, Java, Kotlin)
+
+Complete semantic analysis:
+- Go-to-definition across files
+- Find all usages across codebase
+- Full dependency graph
+- Impact analysis for refactoring
+
+## Partially Supported (Python, TS/JS)
+
+Current capabilities:
+- Definition extraction works
+- Import tracking works
+- Same-file reference tracking works
+
+Limitations:
+- Cross-file `get_references` may miss some usages
+- `get_definition` may not resolve all external symbols
+- Use with awareness of gaps
+
+## Best Practices
+
+### For Full Support Languages
+Use all MCP tools confidently for complete analysis.
+
+### For Partial Support Languages
+1. Verify critical refactoring impacts manually
+2. Use `search_codebase_definitions` for discovery
+3. Cross-reference with `grep` for completeness
+4. Supplement with repomix for context dumps
+
+## Future Plans
+
+Cross-file reference support for Python/TS/JS under active development. Check [GitLab Knowledge Graph](https://gitlab.com/gitlab-org/rust/knowledge-graph) for updates.

package/.claude/skills/gkg/references/mcp-tools.md

@@ -0,0 +1,99 @@
+# GKG MCP Tools
+
+7 Model Context Protocol tools for AI assistants. Available when server runs with `--register-mcp`.
+
+## Endpoints
+
+- **HTTP**: `http://localhost:27495/mcp`
+- **SSE**: `http://localhost:27495/mcp/sse`
+
+## Tools
+
+### list_projects
+
+List all indexed projects with paths.
+
+**Use**: Discover available codebases before analysis.
+
+**Returns**: Project names and absolute paths.
+
+### search_codebase_definitions
+
+Search for functions, classes, methods, constants, interfaces.
+
+**Parameters**:
+- `query`: Search terms
+- `limit`: Max results (pagination)
+
+**Use**: Find symbol definitions by name pattern.
+
+**Returns**: Matching definitions with FQN and locations.
+
+### index_project
+
+Re-index a project to reflect code changes.
+
+**Parameters**:
+- `project_path`: Path to project
+
+**Use**: Update graph after code modifications.
+
+**Returns**: Statistics (files processed, definitions found).
+
+### get_references
+
+Find all usages of a specific definition.
+
+**Parameters**:
+- `definition_id`: Symbol identifier
+- `project_path`: Project context
+
+**Use**: Impact analysis, find call sites before refactoring.
+
+**Returns**: All locations where symbol is referenced.
+
+### read_definitions
+
+Retrieve complete source code for multiple symbols.
+
+**Parameters**:
+- `definition_ids`: List of symbol IDs
+
+**Use**: Batch-read implementations. Token-efficient for same-file symbols.
+
+**Returns**: Full definition bodies.
+
+### get_definition
+
+Navigate to definition of a call on specific line.
+
+**Parameters**:
+- `file_path`: Source file
+- `line`: Line number
+- `column`: Column position
+
+**Use**: Go-to-definition for function/method calls.
+
+**Returns**: Definition location (handles workspace and external deps).
+
+### repo_map
+
+Generate token-efficient ASCII tree of repository structure.
+
+**Parameters**:
+- `project_path`: Repository path
+- `depth`: Tree depth limit
+
+**Use**: Quick codebase overview for LLMs.
+
+**Returns**: Compact tree with condensed definitions, human-readable.
+
+## Integration Pattern
+
+```
+1. list_projects → discover codebases
+2. search_codebase_definitions → find symbols
+3. read_definitions → get implementations
+4. get_references → find usages
+5. repo_map → architecture overview
+```

package/.claude/skills/google-adk-python/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: google-adk-python
+description: "Build AI agents with Google ADK Python. Multi-agent systems, A2A protocol, MCP tools, workflow agents, state/memory, callbacks/plugins, Vertex AI deployment, evaluation."
+license: Apache-2.0
+version: 2.0.0
+---
+
+# Google ADK Python Skill
+
+Expert guide for Google's Agent Development Kit (ADK) Python — open-source, code-first toolkit for building, evaluating, and deploying AI agents. Optimized for Gemini, model-agnostic by design.
+
+## When to Activate
+
+- Build single or multi-agent systems with tool integration
+- Implement A2A protocol for remote agent communication
+- Integrate MCP servers as agent tools
+- Use workflow agents (sequential, parallel, loop) for pipelines
+- Manage sessions, state, memory, and artifacts
+- Add callbacks, plugins, or observability hooks
+- Deploy to Cloud Run, Vertex AI Agent Engine, or GKE
+- Evaluate agents with `adk eval` framework
+
+## Agent Structure Convention (Required)
+
+```
+my_agent/
+├── __init__.py   # MUST: from . import agent
+└── agent.py      # MUST: root_agent = Agent(...) OR app = App(...)
+```
+
+## Quick Start
+
+```bash
+pip install google-adk          # stable (weekly releases)
+uv sync --all-extras            # dev setup (uv required, Python 3.10+, 3.11+ recommended)
+```
+
+```python
+from google.adk import Agent
+
+root_agent = Agent(
+    name="assistant",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant.",
+    description="General assistant agent.",
+    tools=[get_weather],
+)
+```
+
+## App Pattern (Production)
+
+```python
+from google.adk import Agent
+from google.adk.apps import App
+from google.adk.apps.app import EventsCompactionConfig
+from google.adk.plugins.save_files_as_artifacts_plugin import SaveFilesAsArtifactsPlugin
+
+app = App(
+    name="my_app",
+    root_agent=Agent(name="my_agent", model="gemini-2.5-flash", ...),
+    plugins=[SaveFilesAsArtifactsPlugin()],
+    events_compaction_config=EventsCompactionConfig(compaction_interval=2),
+)
+```
+
+Use `App` when needing plugins, event compaction, or custom lifecycle management.
+
+## CLI Tools
+
+| Command | Purpose |
+|---------|---------|
+| `adk web <agents_dir>` | Dev UI (recommended for development) |
+| `adk run <agent_dir>` | Interactive CLI testing |
+| `adk api_server <agents_dir>` | FastAPI production server |
+| `adk eval <agent> <evalset.json>` | Run evaluation suite |
+
+## Agent Types
+
+| Type | Use Case |
+|------|----------|
+| `Agent` / `LlmAgent` | Dynamic routing, tool use, reasoning |
+| `SequentialAgent` | Fixed-order pipeline |
+| `ParallelAgent` | Concurrent execution |
+| `LoopAgent` | Iterative processing |
+| `RemoteA2aAgent` | Remote agent via A2A protocol |
+
+## Key APIs
+
+| Feature | API |
+|---------|-----|
+| State | `tool_context.state[key] = value` |
+| Artifacts | `tool_context.save_artifact(name, part)` |
+| Callbacks | `before_agent_callback`, `after_model_callback`, etc. |
+| MCP Tools | `MCPToolset(connection_params=StdioConnectionParams(...))` |
+| Sub-agents | `Agent(..., sub_agents=[agent1, agent2])` |
+| Human-in-loop | `LongRunningFunctionTool(func=my_func)` |
+| Plugins | `App(..., plugins=[MyPlugin()])` |
+
+## Model Support
+
+Latest: `gemini-2.5-flash` (default), `gemini-2.5-pro`, `gemini-2.0-flash` (sunsets Mar 2026)
+Preview: `gemini-3-flash-preview`, `gemini-3-pro-preview`
+Also: Anthropic Claude, Ollama, LiteLLM, vLLM, Model Garden
+
+## Best Practices
+
+1. **Code-first** — define agents in Python for version control and testing
+2. **Agent convention** — always use `root_agent` or `app` variable in `agent.py`
+3. **Modular agents** — specialize per domain, compose via `sub_agents`
+4. **Workflow selection** — workflow agents for predictable, LlmAgent for dynamic
+5. **State** — `ToolContext.state` for ephemeral, `MemoryService` for long-term
+6. **Safety** — callbacks for guardrails, tool confirmation for sensitive ops
+7. **Evaluate** — test with `adk eval` + evalset JSON before deployment
+
+## References
+
+Detailed guides (load as needed):
+
+- `references/agent-types-and-architecture.md` — Agent types, workflows, custom agents
+- `references/tools-and-mcp-integration.md` — Custom tools, MCP, tool filtering
+- `references/multi-agent-and-a2a-protocol.md` — Sub-agents, A2A, coordinator patterns
+- `references/sessions-state-memory-artifacts.md` — State, artifacts, sessions, memory
+- `references/callbacks-plugins-observability.md` — Lifecycle hooks, plugins, tracing
+- `references/evaluation-testing-cli.md` — adk eval, CLI, evalset format
+- `references/deployment-cloud-run-vertex-gke.md` — Cloud Run, Vertex AI, GKE
+
+## External Resources
+
+- GitHub: https://github.com/google/adk-python
+- Docs: https://google.github.io/adk-docs/
+- Samples: https://github.com/google/adk-python/tree/main/contributing/samples
+- llms.txt: https://raw.githubusercontent.com/google/adk-python/refs/heads/main/llms.txt

package/.claude/skills/google-adk-python/references/agent-types-and-architecture.md

@@ -0,0 +1,128 @@
+# Agent Types and Architecture
+
+## LlmAgent
+
+Dynamic routing agent.
+
+**Properties:** `model`, `instruction`, `description`, `tools`, `sub_agents`, `generate_content_config`
+
+```python
+from google.adk.agents import Agent
+
+agent = Agent(
+    name="assistant", model="gemini-2.5-flash",
+    instruction="You are a helpful assistant.",
+    tools=[search_tool], sub_agents=[code_agent],
+    generate_content_config={"temperature": 0.7}
+)
+```
+
+## Workflow Agents
+
+### SequentialAgent
+
+```python
+from google.adk.agents import SequentialAgent
+
+pipeline = SequentialAgent(
+    name="research_pipeline",
+    sub_agents=[
+        Agent(name="searcher", model="gemini-2.5-flash", tools=[search]),
+        Agent(name="writer", model="gemini-2.5-flash", tools=[write]),
+    ]
+)
+```
+
+### ParallelAgent
+
+```python
+from google.adk.agents import ParallelAgent
+
+parallel = ParallelAgent(
+    name="multi_source",
+    sub_agents=[
+        Agent(name="web", model="gemini-2.5-flash", tools=[web_search]),
+        Agent(name="db", model="gemini-2.5-flash", tools=[db_query]),
+    ]
+)
+```
+
+### LoopAgent
+
+```python
+from google.adk.agents import LoopAgent
+
+loop = LoopAgent(
+    name="refiner",
+    sub_agents=[
+        Agent(name="generator", model="gemini-2.5-flash", tools=[generate]),
+        Agent(name="validator", model="gemini-2.5-flash", tools=[validate]),
+    ],
+    max_iterations=5,
+)
+```
+
+## BaseAgent
+
+Override `run_async()` and `get_agent_card()`.
+
+```python
+from google.adk.agents.base_agent import BaseAgent
+
+class CustomAgent(BaseAgent):
+    async def run_async(self, query: str, context: dict) -> dict:
+        return {"response": "Custom"}
+```
+
+## Agent Structure
+
+```
+my_agent/
+├── __init__.py      # Export root_agent or app
+├── agent.py         # Agent definition
+└── tools.py         # Custom tools
+```
+
+```python
+# __init__.py
+from my_agent.agent import root_agent
+__all__ = ["root_agent"]
+
+# agent.py
+from google.adk.agents import Agent
+root_agent = Agent(name="my_agent", model="gemini-2.5-flash", instruction="...")
+
+# A2A server
+from google.adk.servers.a2a_server import create_a2a_server
+app = create_a2a_server(root_agent)
+```
+
+## Source Structure
+
+```
+src/google/adk/
+├── agents/                # Agent implementations
+├── tools/                 # Tool system
+├── sessions/              # Session management
+├── runners/               # Execution orchestration
+└── servers/               # A2A server utilities
+```
+
+## Global Instructions
+
+```python
+root = Agent(
+    name="root", model="gemini-2.5-flash",
+    instruction="Root behavior.",
+    global_instruction="Always be polite and concise.",
+    sub_agents=[Agent(name="sub1", model="gemini-2.5-flash")]
+)
+```
+
+## Best Practices
+
+- Use descriptive `name`/`description` for routing
+- Keep `instruction` focused on single responsibility
+- Delegate specialized tasks to sub-agents
+- Use workflow agents for orchestration
+- Export `root_agent` or `app` from `__init__.py`

package/.claude/skills/google-adk-python/references/callbacks-plugins-observability.md

@@ -0,0 +1,117 @@
+# Callbacks, Plugins, Observability
+
+## Callback Types
+
+- `before_agent`, `after_agent`: Agent lifecycle
+- `before_model`, `after_model`: LLM calls
+- `before_tool`, `after_tool`: Tool execution
+
+## Callback Signatures
+
+```python
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.models.content import ModelContent
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.adk.tools.tool_context import ToolContext
+
+def before_agent_callback(callback_context: CallbackContext) -> None:
+    print(f"Agent: {callback_context.agent_name}")
+
+def after_agent_callback(callback_context: CallbackContext) -> ModelContent | None:
+    return None
+
+def before_model_callback(callback_context: CallbackContext, llm_request: LlmRequest) -> None:
+    print(f"Model: {llm_request.model_id}")
+
+def after_model_callback(callback_context: CallbackContext, llm_response: LlmResponse) -> None:
+    print(f"Tokens: {llm_response.usage_metadata}")
+
+def before_tool_callback(tool: str, args: dict, tool_context: ToolContext) -> None:
+    print(f"Tool: {tool}")
+
+def after_tool_callback(tool: str, args: dict, tool_context: ToolContext, response: Any) -> Any:
+    return response
+```
+
+## Using Callbacks
+
+```python
+from google.adk.agents.web_agent import WebAgent
+
+agent = WebAgent(
+    name='my_agent', model='gemini-2.5-flash',
+    before_agent_callback=before_agent_callback,
+    before_model_callback=[callback1, callback2]
+)
+
+# Async supported
+async def async_callback(callback_context: CallbackContext) -> None:
+    await log_to_database(callback_context)
+```
+
+## Plugins
+
+```python
+from google.adk.plugins.base_plugin import BasePlugin
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.models.llm_request import LlmRequest
+
+class CountPlugin(BasePlugin):
+    def __init__(self):
+        super().__init__(name='count')
+        self.count = 0
+
+    async def before_agent_callback(self, *, agent, callback_context: CallbackContext):
+        self.count += 1
+        print(f"#{self.count}")
+
+    async def before_model_callback(self, *, callback_context: CallbackContext, llm_request: LlmRequest):
+        print(f"Model: {llm_request.model_id}")
+
+agent = WebAgent(name='agent', model='gemini-2.5-flash', plugins=[CountPlugin()])
+```
+
+## Built-in Plugins
+
+```python
+from google.adk.plugins.save_files_as_artifacts_plugin import SaveFilesAsArtifactsPlugin
+from google.adk.plugins.context_filter_plugin import ContextFilterPlugin
+
+plugin1 = SaveFilesAsArtifactsPlugin()
+plugin2 = ContextFilterPlugin(filter_fn=lambda ctx: ctx.priority > 5)
+agent = WebAgent(name='agent', model='gemini-2.5-flash', plugins=[plugin1, plugin2])
+```
+
+## Observability
+
+### Arize Phoenix
+
+```python
+from phoenix.otel import register
+
+tracer_provider = register(
+    project_name='my_project',
+    endpoint='http://localhost:6006/v1/traces'
+)
+
+agent = WebAgent(name='agent', model='gemini-2.5-flash')
+result = await agent.run('What is 2+2?')
+```
+
+### Custom Metrics
+
+```python
+class MetricsPlugin(BasePlugin):
+    def __init__(self):
+        super().__init__(name='metrics')
+        self.latencies = []
+
+    async def before_model_callback(self, *, callback_context, llm_request):
+        callback_context.start_time = time.time()
+
+    async def after_model_callback(self, *, callback_context, llm_response):
+        latency = time.time() - callback_context.start_time
+        self.latencies.append(latency)
+        print(f"Avg: {sum(self.latencies) / len(self.latencies):.2f}s")
+```

package/.claude/skills/google-adk-python/references/deployment-cloud-run-vertex-gke.md

@@ -0,0 +1,138 @@
+# Deployment: Cloud Run, Vertex AI, GKE
+
+## Development Modes
+
+```bash
+adk web samples/agents/my_agent.py:agent --port 8080
+adk run samples/agents/my_agent.py:agent "What is 2+2?" --streaming
+adk api_server samples/agents/my_agent.py:agent --port 8000
+```
+
+Endpoints: `/chat`, `/stream`, `/health`
+
+## Cloud Run
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY pyproject.toml uv.lock ./
+COPY src/ ./src/
+RUN uv sync --frozen --no-cache
+EXPOSE 8080
+CMD ["uv", "run", "adk", "api_server", "src/my_agent.py:agent", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+```bash
+export PROJECT_ID=my-project REGION=us-central1
+gcloud builds submit --tag gcr.io/$PROJECT_ID/my-agent
+gcloud run deploy my-agent \
+  --image gcr.io/$PROJECT_ID/my-agent \
+  --region $REGION \
+  --set-env-vars GOOGLE_API_KEY=$GOOGLE_API_KEY
+
+# Secret Manager
+echo -n "key" | gcloud secrets create google-api-key --data-file=-
+gcloud run deploy my-agent --set-secrets GOOGLE_API_KEY=google-api-key:latest
+```
+
+## Vertex AI
+
+```bash
+adk deploy --target vertex --agent my_agent.py:agent --project my-project
+```
+
+```yaml
+agent:
+  name: my-agent
+  model: gemini-2.5-flash
+  region: us-central1
+  scaling: {min_instances: 1, max_instances: 10}
+  resources: {cpu: 2, memory: 4Gi}
+```
+
+```python
+from google.cloud import aiplatform
+aiplatform.init(project='my-project', location='us-central1')
+endpoint = aiplatform.Endpoint('projects/123/locations/us-central1/endpoints/456')
+response = endpoint.predict(instances=[{'prompt': 'What is 2+2?'}])
+```
+
+## GKE
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata: {name: my-agent}
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+      - name: agent
+        image: gcr.io/my-project/my-agent:latest
+        ports: [{containerPort: 8080}]
+        env:
+        - name: GOOGLE_API_KEY
+          valueFrom: {secretKeyRef: {name: google-api-key, key: key}}
+        resources:
+          requests: {memory: "2Gi", cpu: "1"}
+          limits: {memory: "4Gi", cpu: "2"}
+---
+apiVersion: v1
+kind: Service
+metadata: {name: my-agent}
+spec:
+  type: LoadBalancer
+  ports: [{port: 80, targetPort: 8080}]
+---
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata: {name: my-agent-hpa}
+spec:
+  scaleTargetRef: {kind: Deployment, name: my-agent}
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+  - type: Resource
+    resource: {name: cpu, target: {type: Utilization, averageUtilization: 70}}
+```
+
+```bash
+gcloud container clusters create my-cluster --region us-central1 --num-nodes 3
+gcloud container clusters get-credentials my-cluster --region us-central1
+kubectl create secret generic google-api-key --from-literal=key=$GOOGLE_API_KEY
+kubectl apply -f deployment.yaml
+```
+
+## Best Practices
+
+```python
+# config.py
+import os
+from dataclasses import dataclass
+
+@dataclass
+class Config:
+  model_id: str = os.getenv('MODEL_ID', 'gemini-2.5-flash')
+  api_key: str = os.getenv('GOOGLE_API_KEY')
+  log_level: str = os.getenv('LOG_LEVEL', 'INFO')
+
+# Health checks
+@app.get('/health')
+async def health(): return {'status': 'healthy'}
+
+# Logging
+from google.cloud import logging
+client = logging.Client()
+client.setup_logging()
+
+# Rate limiting
+from slowapi import Limiter
+limiter = Limiter(key_func=get_remote_address)
+
+@app.post('/chat')
+@limiter.limit('10/minute')
+async def chat(request: Request, prompt: str):
+  return {'response': (await agent.run(prompt)).text}
+```