Merge branch 'main' into adk-api-server

Author: yeesian

.agents/skills/adk-git/SKILL.md

@@ -73,6 +73,7 @@ Self-check before committing: read your subject line and ask "does this tell me
 4. **50 char limit** on subject line when possible, max 72.
 5. **Use body for context** - Add a blank line then explain _why_,
    not _how_, when the subject alone isn't enough.
+6. **Reference GitHub issues** - If the commit fixes a GitHub issue, include "Fixes #<issue-number>" or "Closes #<issue-number>" (or the full issue URL if cross-repository) in the commit message body.
 
 ### Examples
 

.agents/skills/adk-issue-analyze/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: adk-issue-analyze
+description: Analyze and triage a GitHub issue for the adk-python repository. Use this skill to retrieve issue details, inspect the codebase, evaluate legitimacy, check for existing PRs, and produce a structured analysis report.
+---
+
+# ADK Issue Triage & Analysis (Read-Only)
+
+This skill provides a structured workflow for analyzing, verifying, and triaging GitHub issues from the `google/adk-python` repository. When instructed to analyze/triage an issue, follow this read-only workflow.
+
+> [!IMPORTANT]
+> This skill is strictly **read-only**: Do NOT modify any code, create new branches, or write any implementation during this phase.
+
+## Step 1: Retrieve and Parse the Issue
+1. **Extract the issue number**: Parse the number from the link or prompt (e.g., `https://github.com/google/adk-python/issues/5882` -> `5882`).
+2. **Fetch issue details**: Use the `gh` CLI tool to fetch issue details in JSON format:
+   ```bash
+   gh issue view <issue_number> --repo google/adk-python --json number,title,body,state,labels,comments,assignees,createdAt,closedAt
+   ```
+   *If the `gh` CLI is not available or errors out, use `read_url_content` to fetch the public GitHub issue page:*
+   ```
+   https://github.com/google/adk-python/issues/<issue_number>
+   ```
+
+---
+
+## Step 2: Deep Investigation & Analysis
+Address the following four critical questions and present your findings in a structured, premium report.
+
+### 1. What is broken?
+Explain the root cause of the issue or failure:
+- **Trace the execution flow**: Identify which components, classes, or functions are malfunctioning.
+- **Pinpoint the bug**: Detail why the system is behaving incorrectly and where the failure originates (e.g. incorrect logic, missing configuration, unhandled states).
+
+### 2. Is the issue legitimate?
+Inspect the codebase to confirm if the issue represents a real problem:
+- **Examine the description**: Identify the component, class, function, or file referenced.
+- **Search the codebase**: Use `grep_search` to locate the relevant files/functions in the local workspace.
+- **Inspect the code**: Open the files using `view_file` to analyze the code's current logic.
+- **Verify the bug**:
+  - Is the reported problem actually present in the code?
+  - Does it produce the reported error or behavior under the current version (ADK 2.0)?
+  - Is it a documentation typo, setup discrepancy, or a genuine code/logic bug?
+- **Document your code evidence**: Reference specific file paths and line ranges (using clickable markdown file links, e.g., `[skill_toolset.py](file:///path/to/file#L123)`) in your report.
+
+### 3. Should we fix it?
+Formulate a recommendation on whether the issue should be addressed:
+- **Assess the impact**:
+  - Does it break core functionality?
+  - Does it affect standard developer workflows or introduce brittle workarounds?
+  - Is it a high-priority bug or a low-impact cosmetic/feature request?
+- **Check alignment**:
+  - Does the suggested solution align with `adk-architecture` and `adk-style`?
+  - Is it consistent with Python idioms and Pydantic validation rules?
+- **Evaluate workarounds**: Is there a clean workaround, or is a core fix necessary?
+- **Final Recommendation**: Clearly declare whether we should fix it, along with the reasoning and estimated complexity/scope of the fix.
+
+### 4. Is there a linked PR that fixes this issue?
+Search for any existing pull requests that attempt to resolve the issue:
+- **Search PRs**: Run `gh pr list --repo google/adk-python --search "<issue_number>"` to list pull requests mentioning the issue number in the branch name, title, or body.
+- **Verify the PR details**: If PRs are found, fetch their details:
+  ```bash
+  gh pr view <pr_number> --repo google/adk-python --json number,title,state,url,body,author
+  ```
+- **Analyze progress**: Check if the PR is open, merged, or closed, and if it successfully fixes the issue according to the repository's testing patterns.
+- **Present the structured report**: Format and present your findings structured as a premium report following the **Report Template** below.
+
+---
+
+## Report Template
+
+Present your final analysis as a high-quality markdown response using the following structure:
+
+```markdown
+# GitHub Issue #<issue_number> Analysis: <Issue Title>
+
+## Detailed Analysis
+
+### 1. Root Cause Analysis ("What is broken?")
+- Explanation of the failure or bug (what is failing and why).
+- Pinpoint the exact file, function, or design component that is malfunctioning.
+
+### 2. Legitimacy Analysis
+- **Status**: [Legitimate Bug / Feature Request / Duplicate / Invalid / Not Reproducible]
+- **Evidence**:
+  - Code references: [filename.py](file:///absolute/path/to/file#L100-L120)
+  - Analysis of code behavior and why the issue occurs.
+
+### 3. Fix Recommendation
+- **Recommendation**: [Should Fix (High Priority) / Should Fix (Medium/Low Priority) / Won't Fix / Needs Discussion]
+- **Rationale**:
+  - Impact on user experience, workflows, or architecture.
+  - Implementation complexity and risk of side effects.
+
+### 4. Existing Pull Requests
+- **Linked PR**: [None / Pull Request #<pr_number> - <PR Title> (<state>)]
+- **PR URL**: <PR URL>
+- **Analysis**: Brief summary of the PR's approach and status (e.g., "Fixes the bug by implementing X in Y, currently awaiting review").
+
+---
+
+## Executive Summary
+1. **What is broken?** [Brief explanation of the root cause or error]
+2. **Is the issue legitimate?** [Yes / No - brief explanation]
+3. **Should we fix it?** [Yes / No / Needs Discussion - priority & brief reasoning]
+4. **Is there a linked PR that fixes this issue?** [None / Yes, PR #<pr_number> - <state>]
+```
+
+---
+
+## Tips & Best Practices
+> [!TIP]
+> Always use explicit repository qualifiers (`--repo google/adk-python`) when running `gh` commands to avoid failures due to custom internal or local git remotes.
+
+> [!IMPORTANT]
+> When presenting code files and lines, always use markdown file links that point directly to the files in the workspace. Make sure the link is clickable and formatted as `[filename.py](file:///absolute/path/to/file#L100-L120)` without surrounding backticks around the brackets.

.agents/skills/adk-issue-fix/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: adk-issue-fix
+description: Implement a bug fix or feature for a GitHub issue in the adk-python repository. Use this skill after the triage/analysis is complete and approved. It creates a new branch, implements code changes, adds tests, and updates relevant documentation/samples.
+---
+
+# ADK Issue Fix Implementation
+
+This skill provides a structured workflow for implementing bug fixes or new features for GitHub issues in the `google/adk-python` repository. Only invoke/use this skill once the user has approved the fix.
+
+## Implementation Steps
+
+### 1. Base the Branch on Remote HEAD & Create Branch
+- **Do NOT commit the changes**: Leave them uncommitted in the workspace so the user can review and iterate on them.
+- **Base the branch on remote HEAD**: When creating the new branch, ensure it is based on the remote tracking branch HEAD (`origin/main`), not the current local branch. For example:
+  ```bash
+  git checkout -b fix/<issue_number>-<desc> origin/main
+  ```
+
+### 2. Implement the Fix
+- Modify the necessary source files implementing clean, robust logic following `adk-style` and `adk-architecture`.
+
+### 3. Add or Update Unittests
+- Write comprehensive unit tests to verify the behavior and prevent regressions. Refer to the testing patterns in the testing guides.
+
+### 4. Update Documentation & Samples
+- Update `/docs/design` and `/docs/guides` if applicable to the changes.
+- Update `/contributing/samples` if applicable to demonstrate the new capability or updated behavior.

.agents/skills/adk-issue/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: adk-issue
+description: Orchestrate analyzing and triaging GitHub issues for the adk-python repository. Use this skill when a user provides a GitHub issue number or link. It coordinates triage analysis via `adk-issue-analyze` and implementation via `adk-issue-fix`. Triggers on "analyze issue", "issue #", "github issue", "github.com/google/adk-python/issues/".
+---
+
+# ADK Issue Resolution Orchestrator
+
+This skill orchestrates the analysis, triage, and resolution of GitHub issues for the `google/adk-python` repository. When a user provides a GitHub issue number or link, follow this two-phase workflow by delegating/calling the specific sub-skills:
+
+## Phase 1: Triage and Analysis (Read-Only)
+1. **Delegate to `adk-issue-analyze`**: Follow the instructions in the `adk-issue-analyze` skill (located at `.agents/skills/adk-issue-analyze/SKILL.md`) to fetch the issue, inspect the codebase, evaluate legitimacy, search for existing PRs, and present a structured analysis report.
+2. **CRITICAL**: Do NOT modify any code, create new branches, or write any implementation yet.
+3. **Ask for Approval**: Present the report and explicitly ask the user:
+   > "Would you like me to create and implement a fix for this issue in the workspace? (Note: The changes and tests will be created in a new branch but NOT committed, so you can review and iterate on them.)"
+4. **Wait for Approval**: Do not proceed to Phase 2 until the user explicitly approves.
+
+## Phase 2: Implementation (After User Approval)
+1. **Delegate to `adk-issue-fix`**: Once the user approves, follow the instructions in the `adk-issue-fix` skill (located at `.agents/skills/adk-issue-fix/SKILL.md`) to create the branch, implement the fix, add/update tests, update docs, and update samples.