thanh-kit 2.5.0 → 2.5.2

package/templates/skills/gkg/references/cli-commands.md

@@ -0,0 +1,106 @@
+# GKG CLI Commands
+
+## gkg index
+
+Index repositories into knowledge graph.
+
+```bash
+# Index current directory
+gkg index
+
+# Index specific path
+gkg index /path/to/workspace
+
+# With statistics output
+gkg index --stats
+
+# Save stats as JSON
+gkg index --stats stats.json
+
+# Verbose logging
+gkg index -v
+
+# Control thread count (default: CPU cores)
+gkg index --threads 4
+```
+
+**Auto-detection**: Detects if path is workspace (multiple repos) or single repository.
+
+**Output location**: `~/.gkg/{workspace_hash}/{project_hash}/`
+
+## gkg server
+
+Start HTTP server for API and MCP access.
+
+```bash
+# Start server (default: http://localhost:27495)
+gkg server start
+
+# Start with MCP endpoints
+gkg server start --register-mcp
+
+# Stop server
+gkg server stop
+
+# Check status
+gkg server status
+```
+
+**Port**: 27495 (0x6b67 = "kg" in hex). Falls back to unused port if busy.
+
+**Important**: Stop server before re-indexing: `gkg server stop`
+
+## gkg remove
+
+Remove indexed data.
+
+```bash
+# Remove entire workspace
+gkg remove --workspace /path/to/workspace
+
+# Remove single project
+gkg remove --project /path/to/project --workspace-folder /path/to/workspace
+```
+
+## gkg clean
+
+Clean orphaned or corrupted data.
+
+```bash
+# Clean all orphaned data
+gkg clean
+
+# Dry run (preview only)
+gkg clean --dry-run
+```
+
+## Common Workflows
+
+### Initial Setup
+```bash
+cd /my/project
+gkg index --stats
+gkg server start
+```
+
+### Re-index After Changes
+```bash
+gkg server stop
+gkg index
+gkg server start
+```
+
+### Multi-repo Workspace
+```bash
+# Index parent directory containing multiple repos
+gkg index /path/to/workspace
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| High memory | Reduce `--threads` |
+| Slow indexing | Increase `--threads` or use `-v` |
+| Server conflict | Run `gkg server stop` first |
+| Stale data | Run `gkg clean` |

package/templates/skills/gkg/references/http-api.md

@@ -0,0 +1,102 @@
+# GKG HTTP API
+
+Base URL: `http://localhost:27495`
+
+## Server Info
+
+```
+GET /api/info
+```
+Returns port, version.
+
+## Workspace Management
+
+### List Workspaces
+```
+GET /api/workspace/list
+```
+Returns all indexed workspaces and projects.
+
+### Index Workspace
+```
+POST /api/workspace/index
+Content-Type: application/json
+
+{"path": "/path/to/workspace"}
+```
+Index or re-index workspace.
+
+### Delete Workspace
+```
+DELETE /api/workspace/delete
+Content-Type: application/json
+
+{"path": "/path/to/workspace"}
+```
+
+### Delete Project
+```
+DELETE /api/project/delete
+Content-Type: application/json
+
+{
+  "project_path": "/path/to/project",
+  "workspace_path": "/path/to/workspace"
+}
+```
+
+## Graph Queries
+
+### Initial Graph Data
+```
+GET /api/graph/initial?project=/path/to/project
+```
+Fetch visualization starting data.
+
+### Neighbors
+```
+GET /api/graph/neighbors?node_id=xxx&project=/path
+```
+Get connected nodes for exploration.
+
+### Search
+```
+GET /api/graph/search?pattern=MyClass&project=/path
+```
+Search definitions by pattern.
+
+### Statistics
+```
+GET /api/graph/stats?project=/path
+```
+Returns: files, definitions, relationships counts.
+
+## Real-time Events
+
+```
+GET /api/events
+```
+Server-Sent Events stream. Event types:
+- `gkg-connection`: Connection status
+- `gkg-event`: Indexing progress updates
+
+## Error Handling
+
+| Status | Meaning |
+|--------|---------|
+| 200 | Success |
+| 400 | Bad request |
+| 404 | Not found |
+| 500 | Server error |
+
+Response format:
+```json
+{
+  "error": "message",
+  "code": "ERROR_CODE"
+}
+```
+
+## CORS
+
+Accepts localhost origins. No authentication required locally.

package/templates/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/templates/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/templates/skills/google-adk-python/SKILL.md

@@ -1,237 +1,133 @@
-# Google ADK Python Skill
-
-You are an expert guide for Google's Agent Development Kit (ADK) Python - an open-source, code-first toolkit for building, evaluating, and deploying AI agents.
-
-## When to Use This Skill
-
-Use this skill when users need to:
-- Build AI agents with tool integration and orchestration capabilities
-- Create multi-agent systems with hierarchical coordination
-- Implement workflow agents (sequential, parallel, loop) for predictable pipelines
-- Integrate LLM-powered agents with Google Search, Code Execution, or custom tools
-- Deploy agents to Vertex AI Agent Engine, Cloud Run, or custom infrastructure
-- Evaluate and test agent performance systematically
-- Implement human-in-the-loop approval flows for tool execution
-
-## Core Concepts
-
-### Agent Types
-
-**LlmAgent**: LLM-powered agents capable of dynamic routing and adaptive behavior
-- Define with name, model, instruction, description, and tools
-- Supports sub-agents for delegation and coordination
-- Intelligent decision-making based on context
-
-**Workflow Agents**: Structured, predictable orchestration patterns
-- **SequentialAgent**: Execute agents in defined order
-- **ParallelAgent**: Run multiple agents concurrently
-- **LoopAgent**: Repeat execution with iteration logic
+---
+name: ck: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
+argument-hint: "[agent or feature]"
+---
 
-**BaseAgent**: Foundation for custom agent implementations
-
-### Key Components
+# Google ADK Python Skill
 
-**Tools Ecosystem**:
-- Pre-built tools (google_search, code_execution)
-- Custom Python functions as tools
-- OpenAPI specification integration
-- Tool confirmation flows for human approval
+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.
 
-**Multi-Agent Architecture**:
-- Hierarchical agent composition
-- Specialized agents for specific domains
-- Coordinator agents for delegation
+## When to Activate
 
-## Installation
+- 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
 
-```bash
-# Stable release (recommended)
-pip install google-adk
+## Agent Structure Convention (Required)
 
-# Development version (latest features)
-pip install git+https://github.com/google/adk-python.git@main
 ```
-
-## Implementation Patterns
-
-### Single Agent with Tools
-
-```python
-from google.adk.agents import LlmAgent
-from google.adk.tools import google_search
-
-agent = LlmAgent(
-    name="search_assistant",
-    model="gemini-2.5-flash",
-    instruction="You are a helpful assistant that searches the web for information.",
-    description="Search assistant for web queries",
-    tools=[google_search]
-)
+my_agent/
+├── __init__.py   # MUST: from . import agent
+└── agent.py      # MUST: root_agent = Agent(...) OR app = App(...)
 ```
 
-### Multi-Agent System
-
-```python
-from google.adk.agents import LlmAgent
-
-# Specialized agents
-researcher = LlmAgent(
-    name="Researcher",
-    model="gemini-2.5-flash",
-    instruction="Research topics thoroughly using web search.",
-    tools=[google_search]
-)
+## Quick Start
 
-writer = LlmAgent(
-    name="Writer",
-    model="gemini-2.5-flash",
-    instruction="Write clear, engaging content based on research.",
-)
-
-# Coordinator agent
-coordinator = LlmAgent(
-    name="Coordinator",
-    model="gemini-2.5-flash",
-    instruction="Delegate tasks to researcher and writer agents.",
-    sub_agents=[researcher, writer]
-)
+```bash
+pip install google-adk          # stable (weekly releases)
+uv sync --all-extras            # dev setup (uv required, Python 3.10+, 3.11+ recommended)
 ```
 
-### Custom Tool Creation
-
 ```python
-from google.adk.tools import Tool
+from google.adk import Agent
 
-def calculate_sum(a: int, b: int) -> int:
-    """Calculate the sum of two numbers."""
-    return a + b
-
-# Convert function to tool
-sum_tool = Tool.from_function(calculate_sum)
-
-agent = LlmAgent(
-    name="calculator",
+root_agent = Agent(
+    name="assistant",
     model="gemini-2.5-flash",
-    tools=[sum_tool]
+    instruction="You are a helpful assistant.",
+    description="General assistant agent.",
+    tools=[get_weather],
 )
 ```
 
-### Sequential Workflow
+## App Pattern (Production)
 
 ```python
-from google.adk.agents import SequentialAgent
-
-workflow = SequentialAgent(
-    name="research_workflow",
-    agents=[researcher, summarizer, writer]
+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),
 )
 ```
 
-### Parallel Workflow
+Use `App` when needing plugins, event compaction, or custom lifecycle management.
 
-```python
-from google.adk.agents import ParallelAgent
+## CLI Tools
 
-parallel_research = ParallelAgent(
-    name="parallel_research",
-    agents=[web_researcher, paper_researcher, expert_researcher]
-)
-```
+| 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 |
 
-### Human-in-the-Loop
+## Agent Types
 
-```python
-from google.adk.tools import google_search
+| 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 |
 
-# Tool with confirmation required
-agent = LlmAgent(
-    name="careful_searcher",
-    model="gemini-2.5-flash",
-    tools=[google_search],
-    tool_confirmation=True  # Requires approval before execution
-)
-```
-
-## Deployment Options
-
-### Cloud Run Deployment
+## Key APIs
 
-```bash
-# Containerize agent
-docker build -t my-agent .
-
-# Deploy to Cloud Run
-gcloud run deploy my-agent --image my-agent
-```
-
-### Vertex AI Agent Engine
-
-```python
-# Deploy to Vertex AI for scalable agent hosting
-# Integrates with Google Cloud's managed infrastructure
-```
-
-### Custom Infrastructure
-
-```python
-# Run agents locally or on custom servers
-# Full control over deployment environment
-```
+| 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
 
-**Optimized for Gemini**:
-- gemini-2.5-flash
-- gemini-2.5-pro
-- gemini-1.5-flash
-- gemini-1.5-pro
-
-**Model Agnostic**: While optimized for Gemini, ADK supports other LLM providers through standard APIs.
+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 Philosophy**: Define agents in Python for version control, testing, and flexibility
-2. **Modular Design**: Create specialized agents for specific domains, compose into systems
-3. **Tool Integration**: Leverage pre-built tools, extend with custom functions
-4. **Evaluation**: Test agents systematically against test cases
-5. **Safety**: Implement confirmation flows for sensitive operations
-6. **Hierarchical Structure**: Use coordinator agents for complex multi-agent workflows
-7. **Workflow Selection**: Choose workflow agents for predictable pipelines, LLM agents for dynamic routing
+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
 
-## Common Use Cases
+## References
 
-- **Research Assistants**: Web search + summarization + report generation
-- **Code Assistants**: Code execution + documentation + debugging
-- **Customer Support**: Query routing + knowledge base + escalation
-- **Content Creation**: Research + writing + editing pipelines
-- **Data Analysis**: Data fetching + processing + visualization
-- **Task Automation**: Multi-step workflows with conditional logic
+Detailed guides (load as needed):
 
-## Development UI
+- `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
 
-ADK includes built-in interface for:
-- Testing agent behavior interactively
-- Debugging tool calls and responses
-- Evaluating agent performance
-- Iterating on agent design
-
-## Resources
+## External Resources
 
 - GitHub: https://github.com/google/adk-python
-- Documentation: https://google.github.io/adk-docs/
+- 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
-
-## Implementation Workflow
-
-When implementing ADK-based agents:
-
-1. **Define Requirements**: Identify agent capabilities and tools needed
-2. **Choose Architecture**: Single agent, multi-agent, or workflow-based
-3. **Select Tools**: Pre-built, custom functions, or OpenAPI integrations
-4. **Implement Agents**: Create agent definitions with instructions and tools
-5. **Test Locally**: Use development UI for iteration
-6. **Add Evaluation**: Create test cases for systematic validation
-7. **Deploy**: Choose Cloud Run, Vertex AI, or custom infrastructure
-8. **Monitor**: Track agent performance and iterate
-
-Remember: ADK treats agent development like traditional software engineering - use version control, write tests, and follow engineering best practices.