Skip to content

Commit 6af8a81

Browse files
rohityanrohityan
authored
Merge branch 'main' into fix/artifact-display-name-roundtrip
2 parents 82b4573 + 9670ce2 commit 6af8a81

133 files changed

Lines changed: 14854 additions & 6534 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
name: adk-issue-analyze
3+
description: Analyze and triage a GitHub issue for the adk-python repository. Use this skill to retrieve issue details, inspect the codebase, evaluate justification, check for existing PRs, and produce a structured analysis report. Triggers on "/adk-issue-analyze" commands. This skill is strictly read-only and must be used whenever the "/adk-issue-analyze" command is explicitly called.
4+
---
5+
6+
# ADK Issue Triage & Analysis (Read-Only)
7+
8+
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.
9+
10+
> [!IMPORTANT]
11+
> **Strict Read-Only Constraint**:
12+
> This skill is strictly **read-only**. You MUST NOT modify any code, create new branches, or write any implementation. Your role is only to analyze the issue and output the report. Do NOT use file creation or editing tools (e.g. `write_to_file`, `replace_file_content`, `edit_file`, etc.).
13+
>
14+
> **Strict Tooling Constraint**:
15+
> Do NOT use `curl`, `wget`, or any HTTP requests to fetch issue/PR content. You MUST parse/extract the issue number and use strictly the custom `fetch_github_issue` / `fetch_github_pr` python tools (or the `gh` command).
16+
17+
## Step 1: Retrieve and Parse the Issue
18+
1. **Extract the issue number**: Parse the number from the link or prompt (e.g., `https://github.com/google/adk-python/issues/5882` -> `5882`).
19+
2. **Fetch issue details**: Use the custom python tool `fetch_github_issue(issue_number=<number>)` to get the issue metadata. This is the preferred method as it avoids command execution policy issues.
20+
*If the custom python tool is not available, fall back to running the gh command:*
21+
```bash
22+
gh issue view <issue_number> --repo google/adk-python --json number,title,body,state,labels,comments,assignees,createdAt,closedAt
23+
```
24+
25+
---
26+
27+
## Step 2: Deep Investigation & Analysis
28+
Address the following three critical questions and present your findings in a structured, premium report.
29+
30+
### 1. What is broken?
31+
Explain the root cause of the issue or failure:
32+
- **Trace the execution flow**: Use `grep_search` and `view_file` to locate and analyze the malfunctioning components, classes, or functions in the local workspace.
33+
- **Pinpoint the bug**: Detail why the system is behaving incorrectly and where the failure originates (e.g., incorrect logic, missing configuration, unhandled states).
34+
- **Document code evidence**: Reference specific file paths and line ranges using clickable markdown file links, e.g., `[filename.py](file:///absolute/path/to/file#L100-L120)`.
35+
36+
### 2. Is there a linked PR that fixes this issue?
37+
Search for any existing pull requests that attempt to resolve the issue:
38+
- **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.
39+
- **Verify the PR details**: If PRs are found, fetch their details:
40+
```bash
41+
gh pr view <pr_number> --repo google/adk-python --json number,title,state,url,body,author
42+
```
43+
- **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.
44+
45+
### 3. Recommendation
46+
Formulate a recommendation on whether the issue should be addressed:
47+
- **Assess the impact**:
48+
- Does it break core functionality?
49+
- Does it affect standard developer workflows or introduce brittle workarounds?
50+
- Is it a high-priority bug or a low-impact cosmetic/feature request?
51+
- **Check alignment**:
52+
- Does the suggested solution align with `adk-architecture` and `adk-style`?
53+
- Is it consistent with Python idioms and Pydantic validation rules?
54+
- **Evaluate workarounds**: Is there a clean workaround, or is a core fix necessary?
55+
- **Final Recommendation**: Clearly declare whether we should fix it, along with the reasoning and estimated complexity/scope of the fix.
56+
57+
---
58+
59+
## Report Template
60+
61+
Present your final analysis as a high-quality markdown response using the following structure:
62+
63+
```markdown
64+
# GitHub Issue #<issue_number> Analysis: <Issue Title>
65+
66+
## Executive Summary
67+
1. **What is broken?** [Brief explanation of the root cause or error]
68+
2. **Is there a linked PR that fixes this issue?** [None / Yes, PR #<pr_number> - <state>]
69+
3. **Recommendation**: [Should Fix (High Priority) / Should Fix (Medium/Low Priority) / Won't Fix / Needs Discussion - priority & brief reasoning]
70+
71+
<details>
72+
<summary><b>Detailed Analysis</b></summary>
73+
74+
### 1. Root Cause Analysis ("What is broken?")
75+
- Explanation of the failure or bug (what is failing and why).
76+
- Pinpoint the exact file, function, or design component that is malfunctioning.
77+
- Code references: [filename.py](file:///absolute/path/to/file#L100-L120)
78+
79+
### 2. Existing Pull Requests ("Is there a linked PR that fixes this issue?")
80+
- **Linked PR**: [None / Pull Request #<pr_number> - <PR Title> (<state>)]
81+
- **PR URL**: <PR URL>
82+
- **Analysis**: Brief summary of the PR's approach and status (e.g., "Fixes the bug by implementing X in Y, currently awaiting review").
83+
84+
### 3. Recommendation
85+
- **Recommendation**: [Should Fix (High Priority) / Should Fix (Medium/Low Priority) / Won't Fix / Needs Discussion]
86+
- **Rationale**:
87+
- Impact on user experience, workflows, or architecture.
88+
- Implementation complexity and risk of side effects.
89+
</details>
90+
```
91+
92+
---
93+
94+
## Tips & Best Practices
95+
> [!IMPORTANT]
96+
> **Command Sandbox Policy**:
97+
> When running commands via `run_command`, you MUST ONLY use `gh` or `git` commands. Commands like `curl`, `wget`, or direct HTTP network requests are strictly forbidden and will be automatically denied.
98+
> Furthermore, you MUST ONLY use simple commands without special characters (such as `;`, `&`, `|`, `$`, `` ` ``, `<`, `>`, `\n`, `\r`, `(`, `)`, `{`, `}`, `\`). The runner environment runs a security policy that automatically denies any commands containing these characters. Always run clean `gh` or `git` commands directly with arguments, without redirections, command chaining, or shell expansions.
99+
100+
> [!IMPORTANT]
101+
> **Strict Read-Only Enforcement**:
102+
> When executing the `adk-issue-analyze` skill, you MUST NOT use any file modification or editing tools (such as `edit_file`, `replace_file_content`, `write_to_file`, `notebook_edit`, etc.). Your output must strictly be a text markdown report following the template provided, without editing any workspace files or writing/fixing code.
103+
104+
> [!TIP]
105+
> Always use explicit repository qualifiers (`--repo google/adk-python`) when running `gh` commands to avoid failures due to custom internal or local git remotes.
106+
107+
> [!IMPORTANT]
108+
> 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‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: adk-issue-fix
3+
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. Triggers on "/adk-issue-fix" commands.
4+
---
5+
6+
# ADK Issue Fix Implementation
7+
8+
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.
9+
10+
## Implementation Steps
11+
12+
### 1. Check for Existing Pull Requests (Entry Gate)
13+
- **Check linked pull requests**: Before creating a branch or implementing changes, check if the issue is already linked to any pull requests by querying the issue details:
14+
```bash
15+
gh issue view <issue_number> --repo google/adk-python --json closedByPullRequestsReferences
16+
```
17+
- **Refuse to Proceed**: If the `closedByPullRequestsReferences` list is not empty (which indicates that there are already pull requests linked to this issue):
18+
- **Stop immediately**: You MUST refuse to proceed with the fix implementation.
19+
- **Output details**: Report the linked PR details (PR number, URL) to the user and terminate the skill execution.
20+
21+
### 2. Base the Branch on Remote HEAD & Create Branch
22+
- **Do NOT commit the changes**: Leave them uncommitted in the workspace so the user can review and iterate on them.
23+
- **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:
24+
```bash
25+
git checkout -b fix/issue-<issue_number> origin/main
26+
```
27+
28+
### 3. Implement the Fix
29+
- Modify the necessary source files implementing clean, robust logic following `adk-style` and `adk-architecture`.
30+
31+
### 4. Add or Update Unittests
32+
- Write comprehensive unit tests to verify the behavior and prevent regressions. Refer to the testing patterns in the testing guides.
33+
34+
### 5. Update Documentation & Samples
35+
- Update `/docs/design` and `/docs/guides` if applicable to the changes.
36+
- Update `/contributing/samples` if applicable to demonstrate the new capability or updated behavior.

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

Lines changed: 9 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,18 @@
11
---
22
name: adk-issue
3-
description: Analyze and triage GitHub issues for the adk-python repository. Use this skill when the user provides an issue number or link to investigate whether the issue is legitimate, whether it should be fixed, and if there is an existing PR addressing it. Triggers on "analyze issue", "issue #", "github issue", "github.com/google/adk-python/issues/".
3+
description: Orchestrate analyzing, triaging, and resolving GitHub issues for the adk-python repository. Use this skill when a user provides a GitHub issue number or link to perform both analysis and implementation. 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/". Do NOT trigger or use this skill when the prompt explicitly requests the "/adk-issue-analyze" command (use the read-only "adk-issue-analyze" skill instead).
44
---
55

6-
# ADK Issue Analyzer & Triager
6+
# ADK Issue Resolution Orchestrator
77

8-
This skill provides a structured workflow for analyzing, verifying, and triaging GitHub issues from the `google/adk-python` repository. When a user provides a GitHub issue number or link, use this skill to perform deep investigation and report your findings.
9-
10-
> [!IMPORTANT]
11-
> ## CRITICAL EXECUTION RULE: STOP AFTER STEP 2
12-
> * **Phase 1 (Triage & Report) is strictly read-only**: Do NOT modify any code, create new branches, or write any implementation in your first response.
13-
> * **STOP and ask**: You must present the analysis report first and explicitly ask the user:
14-
> > "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.)"
15-
> * **Wait for Approval**: Only proceed with Phase 2 (Step 3: Implementation) in a subsequent turn *after* the user explicitly approves the recommendation.
8+
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:
169

1710
## Phase 1: Triage and Analysis (Read-Only)
18-
19-
### Step 1: Retrieve and Parse the Issue
20-
1. **Extract the issue number**: Parse the number from the link or prompt (e.g., `https://github.com/google/adk-python/issues/5882` -> `5882`).
21-
2. **Fetch issue details**: Use the `gh` CLI tool to fetch issue details in JSON format:
22-
```bash
23-
gh issue view <issue_number> --repo google/adk-python --json number,title,body,state,labels,comments,assignees,createdAt,closedAt
24-
```
25-
*If the `gh` CLI is not available or errors out, use `read_url_content` to fetch the public GitHub issue page:*
26-
```
27-
https://github.com/google/adk-python/issues/<issue_number>
28-
```
29-
30-
---
31-
32-
### Step 2: Deep Investigation & Analysis
33-
Address the following four critical questions and present your findings in a structured, premium report.
34-
35-
#### 1. What is broken?
36-
Explain the root cause of the issue or failure:
37-
- **Trace the execution flow**: Identify which components, classes, or functions are malfunctioning.
38-
- **Pinpoint the bug**: Detail why the system is behaving incorrectly and where the failure originates (e.g. incorrect logic, missing configuration, unhandled states).
39-
40-
#### 2. Is the issue legitimate?
41-
Inspect the codebase to confirm if the issue represents a real problem:
42-
- **Examine the description**: Identify the component, class, function, or file referenced.
43-
- **Search the codebase**: Use `grep_search` to locate the relevant files/functions in the local workspace.
44-
- **Inspect the code**: Open the files using `view_file` to analyze the code's current logic.
45-
- **Verify the bug**:
46-
- Is the reported problem actually present in the code?
47-
- Does it produce the reported error or behavior under the current version (ADK 2.0)?
48-
- Is it a documentation typo, setup discrepancy, or a genuine code/logic bug?
49-
- **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.
50-
51-
#### 3. Should we fix it?
52-
Formulate a recommendation on whether the issue should be addressed:
53-
- **Assess the impact**:
54-
- Does it break core functionality?
55-
- Does it affect standard developer workflows or introduce brittle workarounds?
56-
- Is it a high-priority bug or a low-impact cosmetic/feature request?
57-
- **Check alignment**:
58-
- Does the suggested solution align with `adk-architecture` and `adk-style`?
59-
- Is it consistent with Python idioms and Pydantic validation rules?
60-
- **Evaluate workarounds**: Is there a clean workaround, or is a core fix necessary?
61-
- **Final Recommendation**: Clearly declare whether we should fix it, along with the reasoning and estimated complexity/scope of the fix.
62-
63-
#### 4. Is there a linked PR that fixes this issue?
64-
Search for any existing pull requests that attempt to resolve the issue:
65-
- **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.
66-
- **Verify the PR details**: If PRs are found, fetch their details:
67-
```bash
68-
gh pr view <pr_number> --repo google/adk-python --json number,title,state,url,body,author
69-
```
70-
- **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.
71-
- **Present the structured report**: Format and present your findings structured as a premium report following the **Report Template** below.
72-
- **Offer to create a fix**: If no existing PR is found, you MUST 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.)"
73-
74-
---
11+
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 justification, search for existing PRs, and present a structured analysis report.
12+
2. **CRITICAL**: Do NOT modify any code, create new branches, or write any implementation yet.
13+
3. **Ask for Approval**: Present the report and explicitly ask the user:
14+
> "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.)"
15+
4. **Wait for Approval**: Do not proceed to Phase 2 until the user explicitly approves.
7516

7617
## Phase 2: Implementation (After User Approval)
77-
78-
### Step 3: Propose and Implement Fix
79-
Once the user has approved the implementation of the fix in the workspace, follow these rules:
80-
- **Do NOT commit the changes**: Leave them uncommitted in the workspace so the user can review and iterate on them.
81-
- **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:
82-
```bash
83-
git checkout -b fix/<issue_number>-<desc> origin/main
84-
```
85-
- **Follow these implementation steps**:
86-
1. **Create the fix**: Modify the necessary source files implementing clean, robust logic following `adk-style` and `adk-architecture`.
87-
2. **Add or update unittests**: Write comprehensive unit tests to verify the behavior and prevent regressions.
88-
3. **Update documentation**: Update `/docs/design` and `/docs/guides` if applicable to the changes.
89-
4. **Update samples**: Update `/contributing/samples` if applicable to demonstrate the new capability or updated behavior.
90-
91-
---
92-
93-
## Report Template
94-
95-
Present your final analysis as a high-quality markdown response using the following structure:
96-
97-
```markdown
98-
# GitHub Issue #<issue_number> Analysis: <Issue Title>
99-
100-
## Detailed Analysis
101-
102-
### 1. Root Cause Analysis ("What is broken?")
103-
- Explanation of the failure or bug (what is failing and why).
104-
- Pinpoint the exact file, function, or design component that is malfunctioning.
105-
106-
### 2. Legitimacy Analysis
107-
- **Status**: [Legitimate Bug / Feature Request / Duplicate / Invalid / Not Reproducible]
108-
- **Evidence**:
109-
- Code references: [filename.py](file:///absolute/path/to/file#L100-L120)
110-
- Analysis of code behavior and why the issue occurs.
111-
112-
### 3. Fix Recommendation
113-
- **Recommendation**: [Should Fix (High Priority) / Should Fix (Medium/Low Priority) / Won't Fix / Needs Discussion]
114-
- **Rationale**:
115-
- Impact on user experience, workflows, or architecture.
116-
- Implementation complexity and risk of side effects.
117-
118-
### 4. Existing Pull Requests
119-
- **Linked PR**: [None / Pull Request #<pr_number> - <PR Title> (<state>)]
120-
- **PR URL**: <PR URL>
121-
- **Analysis**: Brief summary of the PR's approach and status (e.g., "Fixes the bug by implementing X in Y, currently awaiting review").
122-
123-
---
124-
125-
## Executive Summary
126-
1. **What is broken?** [Brief explanation of the root cause or error]
127-
2. **Is the issue legitimate?** [Yes / No - brief explanation]
128-
3. **Should we fix it?** [Yes / No / Needs Discussion - priority & brief reasoning]
129-
4. **Is there a linked PR that fixes this issue?** [None / Yes, PR #<pr_number> - <state>]
130-
```
131-
132-
---
133-
134-
## Tips & Best Practices
135-
> [!TIP]
136-
> Always use explicit repository qualifiers (`--repo google/adk-python`) when running `gh` commands to avoid failures due to custom internal or local git remotes.
137-
138-
> [!IMPORTANT]
139-
> 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.
18+
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.

0 commit comments

Comments
 (0)