@lovehlmmm/primekit 1.0.0

package/skills/goal-warmup/references/handoff-packet.md

@@ -0,0 +1,80 @@
+# Handoff packet templates
+
+Warmup **never** invokes `/goal` or starts a long-run session.
+
+## Ready
+
+```markdown
+# Goal packet (from pk:goal-warmup)
+
+## Outcome contract (LOCKED)
+- Intended result: ...
+- In scope: ...
+- Out of scope: ...
+- Acceptance signals: ...
+- Constraints: ...
+- Allowed substitutions: ...
+- Decision owner: user
+
+## Plan
+- Path: <repo-relative or session>
+- Contract traceability: present
+
+## Preflight
+- Blocking: none
+- Deferred: <list or none>
+
+## Scope guard (MUST follow during long-run)
+At each phase boundary:
+1. Diff proposed deliverables vs locked contract
+2. If material mismatch → pause for user; do not finish under reduced scope
+3. Do not weaken, skip, or delete tests to satisfy the stop condition
+4. Pause for human decision instead of inventing product choices
+
+## Codex opener
+/goal Complete <intended result>.
+Read first: <plan path>.
+Constraints: <contract constraints + out of scope>.
+Validate after each checkpoint: <acceptance commands>.
+Keep a brief progress log.
+Stop when <acceptance signals>, or when further work needs human input.
+Follow the scope guard above.
+
+## Claude long-run opener
+Complete <intended result>.
+Read first: <plan path>.
+Honor the LOCKED outcome contract above.
+Validate: <acceptance signals>.
+At each phase boundary apply the scope guard.
+Stop when done or when a human decision is required.
+Do not auto-expand scope.
+```
+
+## Blocked
+
+```markdown
+# Goal warmup — Blocked
+
+Unresolved blockers (only):
+1. <requirement> — status: missing — action: <exact user action>
+2. ...
+
+Resume: re-run `/pk:goal-warmup` after supplying the above.
+Do not start /goal until Ready.
+```
+
+## Decision required
+
+```markdown
+# Goal warmup — Decision required
+
+## Trade-off
+<what makes the locked outcome hard or infeasible>
+
+## Options
+1. <option> — consequences: ...
+2. <option> — consequences: ...
+3. Abort warmup
+
+Reply with the option number. Warmup will re-lock the contract if outcome changes.
+```

package/skills/goal-warmup/references/outcome-contract.md

@@ -0,0 +1,50 @@
+# Outcome Contract
+
+## Purpose
+
+User-approved definition of success that is **immutable** for the warmup run
+and for the subsequent long-run handoff.
+
+## Schema (required fields)
+
+| Field | Meaning |
+|-------|---------|
+| Intended result | Observable end state |
+| In scope | Must-have deliverables |
+| Out of scope | Explicit exclusions |
+| Acceptance signals | How the user judges success (commands, artifacts, behaviors) |
+| Constraints | Budget, deadline, platforms, quality/security |
+| Allowed substitutions | Only explicitly approved alternatives |
+| Decision owner | Always `user` |
+
+## Approval gate
+
+1. Present the full contract markdown.
+2. Require `ask_user` with options: **approve** / **edit** / **abort**.
+   Free-form inference is not approval.
+3. On edit: revise and re-approve before planning.
+4. On abort: stop; no plan, no preflight.
+
+## Immutability
+
+After approval:
+
+- Planner, review, and preflight may add risks, evidence, questions, alternatives.
+- They **must not** redefine intended result, remove a must-have, or silently
+  substitute an approach not in Allowed substitutions.
+- Any proposed outcome/scope change → classify `outcome-change-request` and
+  enter **Decision required**.
+
+## Storage (v1)
+
+- Carry in session context and Ready handoff packet only.
+- Do not write untracked project files solely to hold the contract.
+- Never embed secret values; redact if user pastes credentials.
+
+## Abbreviated interview
+
+When the user already supplies a complete contract-like brief, still:
+
+1. Restate it in the schema above.
+2. Require explicit approval.
+3. Skip only the exploratory interview questions that no longer change the reframing.

package/skills/goal-warmup/references/preflight-matrix.md

@@ -0,0 +1,42 @@
+# Preflight matrix
+
+## Rule
+
+Inspect **every** plan phase — not only the first. Prefer `unknown` + blocking
+over false Ready when a check cannot run safely.
+
+## Matrix columns
+
+| Phase | Requirement | Check method | Status | Owner / unblock action | Blocking? |
+|-------|-------------|--------------|--------|------------------------|-----------|
+
+**Status:** `available` | `missing` | `pending` | `unknown` | `n/a`
+
+## Portable check catalog (v1)
+
+| Check | Method | Secret-safe |
+|-------|--------|-------------|
+| CLI present | `command -v <bin>` | yes |
+| Env var present | name exists; **never print value** | yes |
+| Config shape | parse keys/schema only | yes |
+| GitHub auth | `gh auth status` (no token dump) | yes |
+| Adapter-specific | optional documented probes | yes |
+
+## Output groups
+
+1. **Must provide before long-run** — `Blocking? = yes` and status not available
+2. **Should decide before long-run** — choices that would cause drift
+3. **Can be deferred** — non-blocking and already allowed by contract
+
+## Redaction
+
+- Matrix and chat show `ENV_NAME: present|missing` only.
+- Scrub tool stdout/stderr before copying into matrix rows.
+- Never persist raw probe output that may contain secrets.
+
+## Prohibited by default
+
+- Creating cloud resources
+- Writing/deleting remote data
+- Chargeable API calls
+- Printing tokens, cookies, private keys

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

@@ -0,0 +1,139 @@
+---
+name: pk: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."
+user-invocable: true
+when_to_use: "Invoke for Google ADK agents, A2A, MCP, or Vertex deployment."
+category: ai-ml
+keywords: [google-adk, agents, a2a, mcp, vertex-ai]
+license: Apache-2.0
+argument-hint: "[agent or feature]"
+metadata:
+  author: primekit
+  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
+
+Flash: `gemini-2.5-flash` (default, stable), `gemini-3-flash-preview` (preview)
+Pro: `gemini-2.5-pro` (stable), `gemini-3.1-pro-preview` (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/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/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/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}
+```