AGENTS.md · google/adk-recipes

Sections

1. General
2. Git
3. Models
4. Python

First lines (shown under the repo's Apache-2.0 license)

# Agent Guidelines for adk-recipes
All agents must follow the guidelines below without being reminded.

## General
- Use the term **recipe** instead of **sample** everywhere — responses,
  code comments, commit messages, PR descriptions, docs.
- Keep the terms straight:
  - **Plugins** — recipes under `plugins/<vertical>/<solution>/`
    (e.g. `plugins/retail/store-ops/`). Shipped to users.
  - **Repo skills** — AI coding-assistant helpers under `.agents/skills/`
    (e.g. `prepare-python-recipe`). Used to build this repo.
- Recipes live under `core/` (curated), `contrib/` (community), or
  `plugins/` (vertical solutions). Repo skills are a completely separate
  concept. Do NOT mix `.agents/skills/` changes and recipe/plugin
  changes in the same PR. If a tool run modifies files outside your task's
  scope (e.g. a repo-wide ruff sweep touching an unrelated recipe), revert
  those and mention them so the user can decide.
- When your task is scoped to a specific recipe, plugin or skill, stay inside
  its directory. If you notice similar issues elsewhere, flag them in your
  response instead of opportunistically fixing them.

## Git
- Never run `git commit`, `git push`, `git rebase`, `git merge`,
  `gh pr create`, `gh pr merge`, or any other command that mutates git history
  or the remote, unless the user's **most recent message** contains an
  **explicit** request to do that specific action (e.g. "commit this",
  "push it", "create a PR", "open a PR"). Even a request scoped to the exact
  paths you have just modified needs the explicit verb.
- If, after doing the requested work, there are uncommitted changes and you
  believe they should be committed, **ask first**. Show the diff summary,
  suggest a commit message, and wait for an explicit "yes, commit" or
  "yes, push".
- Safe read-only git commands are always fine: `git status`, `git diff`,
  `git log`, `git show`, `git branch`, `gh pr view`, `gh pr list`.
- Reverting your own uncommitted work (`git checkout <path>` on a working-tree
  change you made in this session) is also fine — it undoes, it doesn't
  mutate history.

## Models
- Do NOT use `gemini-2.0-flash` or `gemini-2.5-flash` — both are deprecated. Use `gemini-3.7-flash` instead.

## Python
- Python recipes go under `contrib/python/` or `core/python/`. Plugins
  go under `plugins/<vertical>/<solution>/` (e.g.
  `plugins/retail/store-ops/`) — that middle folder is a **vertical**, not a
  language, and it is mandatory. A plugin's language comes from
  `manifest.language`.
- Minimum python version: 3.11
- Package manager: Use `uv`, not `pip`
- Formatter/linter: `ruff` — line length 80, double quotes. Config lives
  in the root `pyproject.toml`; never create a standalone `ruff.toml` or
  `.ruff.toml` inside a recipe.
- Test runner: `pytest`.
- Do not rely on `.env` being present for the unit tests. However,
  `.env.example` files are present for each recipe and the unit tests can
  rely on those.