ADK workflow design

Produce the smallest justified orchestration change, or an actionable design/review when implementation is not requested. Establish what constitutes a usable result, how work stops, and which evidence supports the outcome. The skill is self-contained; the book and companion repository are optional provenance, not prerequisites.

Inspect before selecting a pattern

1. Read project instructions, status/diff, manifests and lockfiles, entry points, existing tests and startup/cleanup commands. Preserve the package manager, conventions and unrelated changes. Inspect configuration names without printing credential values or importing application modules just to inspect them.

2. Record the target Python, ADK and GenAI versions, model/backend, current result contract, state ownership, side effects and relevant test commands. Use the existing project interpreter. The read-only helper can provide an initial map:

   python "$SKILL_DIR/scripts/inspect_project.py" --project .

   Resolve SKILL_DIR to this skill's installed directory. Read compatibility.md before using an SDK recipe or interpreting the helper. A different/missing version blocks claims of tested compatibility; independent planning continues. Resolve the target API contract or report the exact blocker, keeping dependency pins as they are.

3. Define acceptance in observable terms: ordered handoff, two preserved branch outputs, bounded refinement with an explicit result, typed node output, or a callback action. For example, "the reviewer node receives the writer's actual draft text, and a reviewer exception leaves the draft saved and the run marked failed" is acceptance; an import or an HTTP 200 is a precondition. List missing prerequisites together. Ask for the decisions only the user can settle and continue independent offline work meanwhile.

Inspection is complete when the chosen mode, version baseline, output contract and validation path are known, or their specific blockers are recorded.

Choose a mode

Modes can combine within one task. Read only relevant references. Cloud hosting, retrieval, long-term memory and tenant authentication may be architectural recommendations; implementing them is a separate scope decision.

When the project has agents-cli-manifest.yaml, consult the installed google-agents-cli-adk-code skill (references/adk-python-workflows.md for the graph API, references/adk-python.md for SequentialAgent, ParallelAgent and LoopAgent, or the ambient-expense-agent and deep-search recipes in google/adk-recipes); if it is not installed, adk-engineer explains how to get it. Keep this skill's acceptance contracts; the scaffold's conventions (agent code in app/, App(name=) equal to that directory name for agents-cli eval) are project facts to preserve, not design decisions.

Implement or advise

1. Present a short plan before broad edits. For a planning/review request, give the selected pattern, alternatives that materially affect the decision, output contract, failure boundaries and acceptance plan; stop short of generating an unsolicited application.
2. For authorised implementation, reproduce the reported failure through the public runner, CLI, HTTP or UI path before a narrow correction. Reuse existing orchestration and change only the boundary causing the defect. Keep a regression case. Greenfield work starts from the actual user task.
3. Account for each output, model/tool attempt and state writer. Authorisation lives in code, a request budget in a reservation before dispatch, and exactly-once execution in an idempotency key; a prompt, a loop limit and a checkpoint each do a different job. Label simulated inputs/results explicitly.
4. Keep proposed production controls distinct from implemented controls. Add deadlines, idempotency, persistence or observability when the task requires them, and validate each claim. Derive limits and identities from the new project's own measurements; a historical campaign's numbers are provenance.

Authority and external work

Inspection is read-only, and code generation authorises no deployment, paid call or live test. Before any consequential operation (an API, billing or quota change, a billable resource, a secret, IAM, a data migration, a deployment, a deletion, or a paid or destructive test), read consequential operations, present the exact scope and limits, obtain explicit approval and end the turn to wait for it. Cleanup is a separate confirmed operation on resources this workflow created.

Present the execution window with the request and retry limits. Read external-validation.md only when real-service acceptance or cloud prerequisites are in scope.

Validate and finish

Follow validation.md for mode-specific assertions, offline boundary doubles, browser timings and a concise result format. Run the project's relevant tests and static/build checks, including a real application path where applicable. Prove concurrent branches overlap, state survives only as claimed, and a failed branch yields a failed result. Repeat setup/adaptation to check that it preserves existing work rather than duplicating it.

For structured review/correction, read review-contracts.md before tuning model reliability: pass honest references for decisive and nondecisive issues, required controls and unresolved/contradictory evidence through the actual schema, checker and Runner/served boundary. Solvability is shown by an honest reference that keeps every obligation and passes.

When a drafting stage produces officer-facing decisions, read content-safeguards.md: check internal consistency in code on every fresh draft (a condition cannot require what a reason waives; a refusal carries no conditions), rank warnings by whether they could change the decision, treat source documents as data, and ask the reviewer for the strongest objection. When a model check's verdict stops the run or sends a case to a person, re-check its costly verdict in code (its "Re-check the verdict whose error costs most" section).

For strict paid-request limits, SDK retries or campaign restart, read model-call-controls.md before choosing the enforcement point: a transport cap is enforced where the HTTP attempt is made, with a callback counter as the observer.

Report changed files, exact commands and versions, actual outcomes, warnings, manual prerequisites and outstanding work, giving an outcome for offline execution, live behaviour, browser functionality, latency and cleanup as applicable. Historical companion results are provenance for the rule, not the pass for the target project.

Label each result with its tier (offline, local, live or release) and outcome (pass, fail, blocked or not run) as evidence labels defines them; earlier, vendor and documentation-only results are historical, vendor-measured or guidance, never this session's evidence.

This is an independent community project, not affiliated with or endorsed by Google.