diff --git a/.agents/skills/adk-bot-review/README.md b/.agents/skills/adk-bot-review/README.md new file mode 100644 index 000000000..461be44fe --- /dev/null +++ b/.agents/skills/adk-bot-review/README.md @@ -0,0 +1,29 @@ +# adk-bot-review skill + +Usage guide for the `adk-bot-review` skill. + +**What it does:** Reviews adk-bot-authored pull requests for technical accuracy +against ADK source code, checks PR state and formatting, and applies ADK docs +style conventions. + +**Audience:** Maintainers. + +## How to invoke + +Ask the agent naturally, for example: + +- "Review bot PR #" +- "Check bot changes for issue #" +- "Verify bot issue #" + +## What you get back + +- Findings ordered blockers first, then required edits, then nits. +- A recommended outcome for the bot PR(s). + +## Follow-up actions + +- Close the bot PR(s). +- Approve as-is. +- Edit in place, then approve. +- Open a new consolidating PR and close the superseded bot PR(s). diff --git a/.agents/skills/integration-create/README.md b/.agents/skills/integration-create/README.md new file mode 100644 index 000000000..fe8d09290 --- /dev/null +++ b/.agents/skills/integration-create/README.md @@ -0,0 +1,34 @@ +# integration-create skill + +Usage guide for the `integration-create` skill. + +**What it does:** Drafts a new integration page under `docs/integrations/`, +picking the right category template (MCP tool, observability, plugin, etc.) and +following the catalog conventions. + +**Audience:** Contributors. + +## How to invoke + +Ask the agent naturally, for example: + +- "Create an integration page for " +- "Add an integration for " +- "Write an integration page for " + +## What you get back + +- A drafted `docs/integrations/.md` with frontmatter and the + category-appropriate sections. +- A hand-off note reminding you to add the icon asset at + `docs/integrations/assets/.png` (and any screenshots). + +## Follow-up actions + +- Provide the inputs it gathers: product name, category, language support, + package name and install command, the tools or methods it exposes, and links + (docs, repo, PyPI/npm, API key). +- Iterate on the draft. +- Run the `integration-review` skill before submitting. +- Run `mkdocs serve` to confirm the card renders and the icon loads. +- Open a pull request. diff --git a/.agents/skills/integration-review/README.md b/.agents/skills/integration-review/README.md new file mode 100644 index 000000000..61690bca3 --- /dev/null +++ b/.agents/skills/integration-review/README.md @@ -0,0 +1,37 @@ +# integration-review skill + +Usage guide for the `integration-review` skill. + +**What it does:** Reviews an integration page or pull request under +`docs/integrations/` for correctness, structure, style, working code, valid +links, and catalog conventions. + +**Audience:** Contributors and maintainers. + +## How to invoke + +Ask the agent naturally, for example: + +- "Review integration PR #1959" +- "Run integration-review on `docs/integrations/bigquery.md`" +- "Review this integration" + +## What you get back + +- A prioritized report with all four tiers listed (🔴 Critical, 🟠 Quality, + 🟡 Style, 🔵 Nits), each finding tagged with `file:line`. +- A developer value and maturity assessment. +- A recommended decision: approve, request changes, or close PR. +- A top-level review response. +- Draft line-anchored comments, one per finding. + +Everything is a draft. Nothing is posted to GitHub and no files are changed +unless you explicitly ask. + +## Follow-up actions + +- Act on the decision: approve, request changes, or close the PR. +- Edit the drafted review response and comments before sending them to the + author. +- Ask the agent to apply fixes (for example, "apply the fixes"); it edits files + only when explicitly asked. diff --git a/.agents/skills/integration-review/SKILL.md b/.agents/skills/integration-review/SKILL.md index d5108b52b..70d68839a 100644 --- a/.agents/skills/integration-review/SKILL.md +++ b/.agents/skills/integration-review/SKILL.md @@ -1,6 +1,6 @@ --- name: integration-review -description: Reviews an ADK integration documentation page (a Markdown file under docs/integrations/) or an integration pull request for correctness, structure, style, working code, valid links, and catalog conventions. Produces a prioritized review report and only fixes issues when explicitly asked. Triggers on "integration-review", "review integration page", "review integration PR", "review this integration", "check integration docs". +description: Reviews an ADK integration documentation page (a Markdown file under docs/integrations/) or an integration pull request for correctness, structure, style, working code, valid links, and catalog conventions. Produces a prioritized review report, a recommended decision (approve, request changes, or close PR), a top-level review response, and draft line-anchored comments; only fixes issues when explicitly asked. Triggers on "integration-review", "review integration page", "review integration PR", "review this integration", "check integration docs". --- # ADK Integration Page Reviewer (integration-review) @@ -36,8 +36,8 @@ The authoritative sources of truth for this review are: files that only show in the full diff. - Check whether "Allow edits from maintainers" is enabled (`maintainerCanModify`) so fixes can be pushed directly if requested later. -- Confirm the CLA is signed (the `google-cla` bot). An unsigned CLA is a hard - blocker. +- Confirm the CLA is signed (the `google-cla` bot). An unsigned CLA is a 🔴 + Critical finding and blocks merge until signed. - If reviewing a local file, run `git status` and `git diff` to see the change. ### Step 2: Find and read similar pages @@ -58,13 +58,21 @@ Work through every dimension in the review checklist below. Do real verification, not a surface read (see "Deep verification"). -### Step 5: Report and stop +### Step 5: Research developer value and maturity -Produce the prioritized report (see "Report format"). Do **not** edit files or -offer to fix issues by default. Stop and wait for an explicit instruction to -fix. +Gather objective evidence about the project's maturity, adoption, and whether it +genuinely integrates with ADK (see "Developer value and maturity"). Base the +assessment on verifiable facts, not impressions or the PR's own marketing. -### Step 6 (only if asked): Apply fixes +### Step 6: Report, decide, and stop + +Produce the prioritized report (see "Report format"), then emit the three +follow-on outputs in "Review decision and response": a top-level review +response, a decision (approve, request changes, or close PR), and draft +line-anchored comments. Do **not** edit files, post to GitHub, or offer to fix +issues by default. Stop and wait for an explicit instruction to fix. + +### Step 7 (only if asked): Apply fixes If, and only if, the user explicitly asks you to fix findings: apply precise edits, keep the contributor's wording where possible, fix only ADK-owned issues @@ -202,10 +210,14 @@ source repositories are listed in `docs/community/contributing-guide.md`. - **Package reality**: confirm the PyPI (or npm) package exists and that any stated version and Python requirement match the prose. - **ADK API**: verify every ADK symbol and pattern used in the code samples - against `~/Repos/adk-python` or the relevant language SDK (e.g. `Runner`, - `run_async`, `create_session`, `append_event`, `save_artifact`, + against the canonical source repositories (listed in + `docs/community/contributing-guide.md`) for the relevant language SDK (e.g. + `Runner`, `run_async`, `create_session`, `append_event`, `save_artifact`, session/artifact service URIs, `adk web` / `adk run` CLI flags, genai types). - Flag mismatches. + Do not assume a local checkout: fetch the source with `gh` or `git` (or use a + local clone if one exists), and check the **released version** the docs target + rather than a main branch that may be ahead of or behind the release. Note the + version you verified against, and flag mismatches. - **Vendor SDK**: verify the vendor's classes, methods, and arguments against the vendor SDK source or docs. - **Ownership of bugs**: distinguish ADK-owned issues from vendor-SDK-owned @@ -213,9 +225,56 @@ source repositories are listed in `docs/community/contributing-guide.md`. - **Test by hand** when practical: run the example with a real ADK agent, or at minimum `mkdocs serve` to confirm the card renders and the icon loads. +## Developer value and maturity + +Integration pages are official ADK documentation, so an integration must earn +its place by offering real, demonstrated value to developers. The goal here is +to research and determine if the integration is for an established platform with +genuine utility, a track record, and real adoption vs. for a brand-new or +low-adoption project with little substance behind it. Do the research and report +the evidence; do not infer value from the PR's own description or marketing. + +Gather objective, verifiable signals and cite each with a source: + +- **Package reality and age**: confirm a real published package exists. Query + the PyPI JSON API (`https://pypi.org/pypi//json`) or the npm registry + (`https://registry.npmjs.org/`) for the first-release date, number of + releases, and latest version, and check download counts (pypistats or the npm + downloads API). A missing package, or one published the same day as the PR, is + a strong negative signal. +- **Source repository signals**: use `gh api repos//` to read + `created_at`, stars, forks, contributor count, commit count, releases, + license, and last-commit date. A repository created within the last few weeks, + with a handful of commits, a single author, or no license is a negative + signal. +- **Adoption and track record**: gauge real usage from verifiable signals: + package download counts (see above), repository stars, forks, and dependent + projects, plus any documented production users, case studies, or independent + third-party coverage found via web search, and how long the product has + operated. Broad, verifiable usage is a positive signal; its absence across + every source is a negative one. +- **Genuine ADK integration**: confirm the project actually uses ADK extension + points (callbacks, plugins, toolsets, MCP) rather than patching a dependency + such as `google-genai`, or wrapping a REST API with plain functions and + presenting that as an ADK integration (cross-check against "Deep verification" + and the scope trigger below). +- **Website liveness**: confirm the linked site is a real, live product site, + not a parked domain or placeholder. + +**Weighing the evidence.** A new project is not automatically low-value: an +established vendor shipping a brand-new package, or a project with clear utility +plus a real source repository, tests, and a license, is credible and should not +be treated as a value concern. Genuine concern is the accumulation of negative +signals: brand-new and unpublished, no adoption or track record, no source or +license, no real ADK extension use, and claims the page makes that your +verification could not confirm. When the evidence is mixed, give the contributor +the benefit of the doubt, lay out the facts, and recommend closing as a judgment +call for the maintainer rather than asserting a verdict. Keep the write-up +neutral and factual. + ## Acceptance and rejection -**Hard blockers / rejection triggers:** +**Rejection triggers (close the PR):** - Documents unreleased, unmerged, or fabricated APIs. We cannot document functionality that does not exist yet. @@ -224,6 +283,15 @@ source repositories are listed in `docs/community/contributing-guide.md`. - Code that does not match the real ADK or vendor API. - Broken or hallucinated links. - Unsigned CLA. +- Insufficient developer value or maturity: a brand-new repository, an + unpublished or same-day package, no adoption or track record, or no source + repository or license. Support this with the evidence from "Developer value + and maturity" and treat it as a maintainer judgment call, not an automatic + verdict. +- Misrepresented integration: manual code that ignores ADK's extension points + while claiming to integrate with ADK. +- Out of scope: a generic "wrap a REST API as a function tool" page with no + ADK-specific artifact. The ADK docs are not an API directory. - Spam signals (no connection to either project, no ADK-specific functionality, contribution-graph padding, very new integrations with low usage). @@ -238,10 +306,16 @@ overclaims or marketing bias; auto-discovered with no nav edits. ## Report format -Produce a Markdown report categorized by priority, each finding with `file:line` -and context: +Produce a Markdown report categorized by priority, each finding with an exact +`file:line` and context. Derive line numbers from the file under review (the +local page, or the PR via `gh pr diff` or a fetched copy) using a line-numbered +read, `grep -n`, or the diff's hunk headers; never approximate (no `~`). +**Always list all four tiers in order and print `None` under any tier with no +findings**, so the absence of Critical issues is stated, not merely implied. A +finding you consider genuinely take-or-leave belongs under 🔵 **Nits**; keep 🔴, +🟠, and 🟡 reserved for items that must be fixed before merge. -- 🔴 **Blockers**: fabricated/unreleased APIs, non-working code, broken or +- 🔴 **Critical**: fabricated/unreleased APIs, non-working code, broken or hallucinated links, unsigned CLA, wrong destination directory, duplicate page. - 🟠 **Quality**: structure or template mismatch, missing/misnamed sections, overclaims, incorrect vendor/ADK API details. @@ -251,7 +325,97 @@ and context: - 🔵 **Nits**: tag comma spacing, absolute-vs-relative ADK links on vendor-owned pages, image size, heading-capitalization variants. -After the report, **stop**. Do not modify files unless the user explicitly asks. +Every finding you list here must produce at least one line-anchored comment in +output 3 (a finding that spans multiple locations gets one comment per +location); the report and the comments must cover the same items. + +After the tiers, add a short **Developer value and maturity** narrative +paragraph: summarize the evidence gathered in the "Research developer value and +maturity" step (package age, adoption and track record, repository signals, +genuine ADK extension use), cite each signal with a source link, and end with a +provisional lean. When the research concludes value or maturity is insufficient, +also record it as a 🔴 **Critical** finding tagged "judgment call" so it stays +consistent with the approve gate. + +After the prioritized report, produce the outputs in "Review decision and +response" below. + +## Review decision and response + +After the prioritized report, emit these three outputs in order. They map onto a +GitHub PR review (review body + decision + inline comments). Everything here is +a **draft**: do not post to GitHub, do not run `gh`, and do not edit files +unless the user explicitly asks. + +### 1. Top-level review response + +A short review body (a few sentences), suitable to paste as the GitHub PR review +summary. State what the integration is, the overall assessment, the headline +reasons, and what needs to happen next. Use the "Feedback tone" below: short, +direct, diplomatic, and actionable. For a Close PR outcome, adapt the matching +snippet from "Decline response templates" and fill in the specific evidence. + +### 2. Decision + +Choose exactly one, justified by citing the specific findings from the report +above it. Cross-reference the "Acceptance and rejection" criteria so the +decision stays consistent with them. + +- **Approve**: the report shows no 🔴, 🟠, or 🟡 findings (all three are + `None`); at most 🔵 nits remain, and the page meets the "A good page" bar. +- **Request changes** (the common case): a salvageable page with any 🔴/🟠/🟡 + finding that must be fixed before it can merge. List the must-fix items. +- **Close PR**: hits a rejection trigger from "Acceptance and rejection" + (fabricated/unreleased APIs, duplicate page, code that does not match the real + ADK or vendor API, broken or hallucinated links, unsigned CLA, misrepresented + integration, out of scope, insufficient value/maturity, spam signals). + Recommend the PR be closed and record the reason (link the superseding doc or + PR where relevant). When insufficient developer value/maturity is the *only* + concern (the code otherwise works), present it as a recommendation explicitly + flagged as a maintainer judgment call, backed by the "Developer value and + maturity" narrative, rather than an automatic hard blocker. + +Do not use a plain "comment" (no-decision) outcome unless there is a strong, +stated reason the review genuinely cannot land on one of the three above. + +### 3. Line-anchored comments + +A copy-pasteable list of inline PR comments a maintainer can drop onto the diff. +Cover **every finding in the report, across all four tiers (🔴 🟠 🟡 🔵)**. Do +not filter by severity or decide that some categories are not worth commenting: +every flagged item, down to the last nit, gets a comment so the maintainer can +relay all of it and nothing is silently dropped. + +- **Format each comment to be pasted as-is** into a GitHub inline comment: a + `file:line` (or `file:start-end`) locator with the tier emoji on its own line, + then the one- to two-sentence suggestion as a blockquote so it copies cleanly. + For example: + + `docs/integrations/weave.md:76` 🟡 Style + + > Use `model="gemini-flash-latest"` instead of the pinned + > `model="gemini-2.5-flash"` to match repo convention and avoid + > model-version churn. + +- Use the exact `file:line` for the finding, taken from the file under review + (the local page or the PR diff), never approximated (no `~`). Only when a + finding genuinely maps to no line (for example, a missing section, or the + value and maturity judgment call) fall back to a page-level or + frontmatter-level comment, and say so explicitly. +- Give the contributor an out where appropriate (e.g. "remove this link and the + page serves as the sample"). +- Group the comments by tier in the same order as the report. +- One finding can produce more than one comment: a finding that spans multiple + locations (e.g. the same issue in the Python and TypeScript samples) gets one + comment per location. +- Reconcile before finishing: every finding in the report has at least one + comment (so comments equal or outnumber findings). If any finding lacks one, + add it rather than shipping a partial list. + +These are drafts only; do not post them. + +After these three outputs, **stop**. Do not modify files unless the user +explicitly asks. ## Feedback tone (for PR comments you draft) @@ -260,5 +424,44 @@ After the report, **stop**. Do not modify files unless the user explicitly asks. sample agent in a repo? Otherwise you can remove this link and this page will serve as the sample."). - Use precise, actionable terminology (e.g. "rename the catalog title" for the - frontmatter field, not "rename the page"). Reference the contributing guide for - mechanics instead of over-explaining. + frontmatter field, not "rename the page"). Reference the contributing guide + for mechanics instead of over-explaining. + +## Decline response templates + +When the decision is Close PR, adapt the matching template below for the +top-level review response. These mirror the maintainer's established voice; keep +them short and **replace every `[bracket]` with the specific, verified +evidence** for this PR. Link the acceptance criteria +(`https://github.com/google/adk-docs/blob/main/CONTRIBUTING.md#acceptance-criteria`). +More than one may apply; combine the relevant paragraphs. + +- **Value for developers**: "Thank you for the PR! After reviewing it against + our [acceptance criteria], we're not able to accept this integration at this + time. **Value for developers:** We look for integrations that provide clear, + demonstrated value to developers building agents with ADK, and we evaluate + factors such as project maturity, active user base, and track record. + [evidence: e.g. the supporting repository was created within the last few + weeks, there is no published package to integrate against, and the project + does not yet have the community adoption or track record we look for.]" +- **Completeness and testability**: "Thank you for the PR. After reviewing it + against our [acceptance criteria], we're not able to accept this integration + at this time. **Completeness and testability:** Code examples in our docs must + be functional and runnable by developers. [evidence: e.g. the ADK imports and + classes referenced do not exist / the `` package is not published / the + example imports from an unmerged PR.]" +- **Publishability**: "Thanks for the PR. However, we're unable to accept this + integration. Per our [acceptance criteria], we can't publish integrations for + services that may circumvent technical protection measures, violate terms of + service, or access services without authorization. [evidence]" +- **Out of scope**: "Thanks for the PR! However, this integration page is out of + scope for the ADK docs. Integration pages are for third-party functionality + that extends or tightly integrates with ADK (tools, plugins, toolsets, MCP + servers, or observability platforms). [evidence: e.g. this defines plain + functions that call a REST API, the generic 'wrap a REST API as a function + tool' pattern, which is already documented and applies to any API. The ADK + docs are not an API directory.]" +- **Duplicate / superseded**: "Thanks for the PR. This is superseded by #`` / + duplicates the existing [``]. [Optional: vendor-specific features belong + in the vendor's own docs, with at most a one-line link from the existing ADK + page.]"