* docs(adk): fix skill gaps surfaced by the 06-20 benchmark sweep
Each change was verified against agent-lack source (runtime/CLI/bundler)
before editing. Skills-only; no runtime/CLI changes.
- ADK-702: custom events nest authored data at event.payload.payload,
not event.payload (conversations.md, patterns-mistakes.md)
- ADK-703: route natural language to execute()/adk.zai.extract instead
of hand-rolled keyword/regex parsers (conversations.md,
patterns-mistakes.md)
- ADK-704: single-quote `adk chat --single` messages; $ expands in
double quotes and silently mangles input (cli.md, adk-test.md)
- ADK-705: test pushed chat:custom events with an eval event turn +
adk evals, not adk chat --single or curl (adk-test.md,
debug-workflow.md, conversations.md)
- ADK-708/707: ship bundled data via static JSON import; assets.get()
returns a URL only, never file bytes (patterns-mistakes.md, assets.md)
- eval event turns take { payload } only (no type field); pushed events
arrive as chat:custom (adk-evals SKILL.md, eval-format.md,
test-patterns.md)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore: format .claude-plugin manifests with oxfmt
Pre-existing format:check failures on dev (multi-line keywords arrays),
unrelated to the skill doc changes — fixes the Code Quality check.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(adk): address review — guard message access + link zai reference
- patterns-mistakes.md: use message?.payload.text in the WRONG routing
example so it doesn't model an unguarded-access crash on event turns
- conversations.md: cross-link zai-agent-reference.md where adk.zai.extract
is mentioned, so the API and its import are discoverable
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(adk): fix skill gaps causing bot failures and excessive iteration
Targets only items the benchmark surfaced as hard failures or large turn/token waste:
- actions: `output` is required; bare Zui schema, not { schema: ... }
- tools: `.asTool()` is Action→Tool only; pass a Tool directly
- tables: prefer user/bot state over a Table for simple per-user memory
- context-api: Tools/Actions can't call conversation.send(); return data
- conversations: custom/proactive event recipe (events + type==='event'), not Trigger + createMessage
- workflows: use conversation state for simple turn-by-turn chat, not request/provide
- knowledge-bases: drop non-existent `adk kb status`; sync with --dev/--force
* docs(adk): require camelCase custom event names
Production adk build rejects snake_case event names and fails the build;
state the constraint in the triggers reference (surfaced by benchmark runs
where agents declared snake_case custom events, e.g. claim_update).
* docs(adk): teach chat:custom for receiving pushed events
Models invented domain event names (claimUpdate, etc.) to receive a
pushed conversation event instead of subscribing to chat:custom, so no
handler fired. Scope the camelCase rule to events you define/emit, point
triggers.md + SKILL.md at the conversations.md chat:custom pattern, and
add a patterns-mistakes entry.
* docs(adk): stop teaching reserved id/createdAt/updatedAt columns
tables.md defined createdAt/updatedAt as user columns and wrote them in
create/update payloads, but the runtime reserves all three (auto-managed)
and throws if you define them — and an 'always add timestamps for audit
trails' best-practice taught exactly the pattern that fails the build.
Broaden the reserved-column rule to id/createdAt/updatedAt, drop the
column defs and payload writes, and keep the read/query/sort uses.
* docs(adk): clarify reserved-id upsert key + show event.payload read
Address PR review:
- tables.md: the reserved-column bullets were contradictory (never set them
in payloads vs. provide id in upsertRows). Reconcile: never write
createdAt/updatedAt in any payload; id passed to upsertRows is the match
key that locates the row, not a column value you set.
- conversations.md: the proactive-event example destructured event but never
used it. Read event.payload (with the cast channel:'*' requires) so the
handler reacts to the pushed data instead of static text.
* docs(adk): patch CLI reference gaps and flag drift
Fills the out-of-scope gaps flagged during the workflows-diagnostics work,
plus accuracy drift found by auditing cli.md against agent-lack master
(v1.19.0-beta.2). All specs verified directly from
packages/cli/src/cli.ts and the command implementations.
Flag drift (docs described flags that no longer exist):
- adk dev: removed `-l, --logs` and `--no-open` (gone from source); added
the real flags `--non-interactive`, `-v/--verbose`, `--otlp`,
`--port-otlp`. Fixed Quick Start, the dev examples, automation notes,
and the two stale references in adk/SKILL.md.
- adk ps: added `--wide`.
- adk dashboard: added `--port-console`, `--no-browser`, `--format`.
- adk kb sync: added `--confirm-storage-changes`, `--format`.
Newly documented commands (existed in source, missing from docs):
- adk chat: documented `--timeout` (default 60s) and `--conversation-id`.
- adk conversations (list/show): new section — diagnostic command over the
local trace store.
- adk logout, adk secret / secret:set / secret:delete, adk models.
Quick Reference updated (Diagnostics block, logout, secret, models).
Deliberately did NOT touch the `### adk traces` section — PR #44 already
rewrites it, so this avoids an overlap/conflict with that unmerged PR.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(adk): fix invalid `adk dev --format json` guidance (ADK-618)
ADK-618 reports the skills/docs still recommend removed headless dev flags.
The main `adk` skill's `adk dev --logs --no-open` was already corrected to
`--non-interactive` in the previous commit on this branch. This commit
closes the remaining instances of the same bug class in the debugger skill:
`adk dev --non-interactive --format json` (3 places).
`adk dev` has no `--format` option (only --port, --port-console, --otlp,
--port-otlp, --verbose, --non-interactive in agent-lack
packages/cli/src/cli.ts), and the CLI does not allowUnknownOption, so
Commander rejects `--format` before the command runs. In --non-interactive
mode the output is already a structured NDJSON event stream, so --format is
both invalid and redundant.
- adk-debugger/SKILL.md: command cheatsheet + prerequisites checklist
- adk-debugger/references/traces-and-logs.md: CLI tools table row, and
softened the "All commands support --format json" header to note that
adk dev is the exception.
Verified against agent-lack master (v1.19.0-beta.2): ADK-618 is accurate,
not hallucinated.
Refs: ADK-618
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(adk): address CLI reference review gaps
* docs(adk): clarify debugger CLI options header
* Update skills/adk/references/cli.md
Co-authored-by: Augusto Mota Pinheiro <augusto.pinheiro@botpress.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Augusto Mota Pinheiro <augusto.pinheiro@botpress.com>
* docs(adk): document adk workflows runs diagnostic command
Documents the new `adk workflows runs` subcommand from agent-lack#614
which lists durable workflow runs (with name/status/limit/nextToken
filters) and shows a single run's status, state, and steps payloads
when given a `wrkflow_` instance id.
- adk/references/cli.md: new section between `adk traces` and `adk evals`,
plus a Quick Reference entry
- adk-debugger/references/traces-and-logs.md: row added to the CLI
Debugging Tools table
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(adk): expand workflow diagnostics — adk workflows family + adk traces filter tokens
Fills in the workflow-diagnostics commands that already exist in agent-lack
but weren't documented in skills:
- `adk workflows list / inspect / run` (siblings of `runs`, all shipped in
agent-lack PRs #283 and #300). Restructured the `### adk workflows runs`
section into a single `### adk workflows` section covering the whole family,
including the JSON-only `--format` constraint that applies to all four.
- `adk traces` filter tokens — the section previously listed only `--format`
and a non-existent `--conversation-id` flag. The real command takes
positional tokens: `error`, `workflow=`, `action=`, `trigger=`,
`conversation=`, `trace=`, `since=`, `until=`, `limit=`, plus `--follow`
and `--include-llm`. `workflow=<name>` is the most useful entry point for
diagnosing a specific workflow's recent activity.
Quick Reference updated. adk-debugger/traces-and-logs.md table row and
"Querying Traces" example block updated to match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(adk): clarify --format on `adk workflows run`
Greptile catch (PR #44): the bullet said `run` "always emits JSON
regardless of value", which contradicted the family-level rule that any
non-`json` `--format` is rejected. Both are partially true: the command
hard-codes its logger to JSON, but `ensureWorkflowJsonOnlyFormat` still
throws before that hard-coding runs. The user-visible behavior is the
same rejection as siblings; the only difference is the default value.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(adk): put tokens before flags in adk traces follow examples
Greptile catch (PR #44, 2x): `adk traces --follow error` mixes flag-then-
token ordering when the section's synopsis and every other example put
positional tokens first.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(adk): centralize Zai docs and add everyday problems & edge cases
Zai documentation was scattered across multiple reference files with
redundant inline explanations. This centralizes Zai content into the
dedicated reference files and adds practical guidance for common use
cases and pitfalls.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): address Greptile review comments on Zai reference
- Split rate/sort example to clarify they're independent operations
- Replace p-limit import with dependency-free stagger pattern
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(adk): consolidate adk-integrations into main adk skill
Merge the standalone adk-integrations skill into the main adk skill's
integrations.md reference. Update all CLI docs to reflect the new
`adk integrations` subcommand structure and lock file system from
agent-lack, replacing the old flat commands and agent.config.ts
dependencies pattern.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): remove stale ADK 1.9+ note from agent-config.md
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): remove incorrect plugin references from integration docs
Plugins have their own `adk plugins` commands — they don't belong
in `adk integrations` examples.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(adk): add plugins.md reference for plugin management
Document the `adk plugins` CLI subcommands, interface dependency
resolution, lock file structure, and plugin lifecycle. Add to SKILL.md
reference listing and cli.md quick reference.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: mention plugins in README
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(adk): mention plugins in main SKILL.md
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): address Greptile review comments
- Add lock files to project structure tree, remove stale "(includes
integrations)" from agent.config.ts comment
- Add missing --to flag on adk integrations upgrade
- Add missing --dry-run on sync, --from/--to on copy
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): route plugin queries to adk plugins commands in /adk-integration
Addresses Greptile P1: plugin names like desk-hitl were silently
routed to adk integrations commands which can't find them.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(adk): rename sync/apply to pull-lock/push-lock
Matches agent-lack#594 which renames the dependency-management CLI
commands so direction is unambiguous (pull = cloud → lockfile,
push = lockfile → cloud). "sync" and "apply" were ambiguous because
both are reused elsewhere (kb sync, assets sync) with different meaning.
Also documents the new bundled top-level commands `adk pull-lock` and
`adk push-lock` that run both integrations and plugins at once.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(adk): fix flag scope contradictions in cli.md
- Move `--to <version>` out of "Plugin-specific flags" since
`adk integrations upgrade` supports it too.
- Add a `pull-lock` options callout — it supports `--dry-run`
like `push-lock`, but the cli.md callout was missing.
Addresses Greptile review on PR #35.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(adk-dev-console): add multi-agent dashboard and Agent Map documentation
The Dev Console now supports multiple running agents, agent switching,
console modes (local/cloud), dev/prod targets, and CLI commands for
agent management. This updates the skill to cover those features.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk-dev-console): remove internal routing details from multi-agent reference
Skills should describe user-facing behavior, not internal architecture
like socket protocols, query parameter routing, or file-level contracts.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(adk): add multi-agent CLI commands to CLI reference and cross-link
Add adk agents, adk ps, adk dashboard, and adk kill to the CLI
reference with full options and examples. Update adk dev to mention
multi-agent registration. Link multi-agent-dashboard.md back to the
CLI reference instead of duplicating command details.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk-dev-console): trim verbose details in pages.md and multi-agent CLI table
Keep pages.md multi-agent section to a brief pointer; keep CLI table
cells short since the CLI reference has the full details.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): remove nonexistent adk agents command
adk agents doesn't exist — adk ps covers listing running agents and
processes. Removed from CLI reference, SKILL.md, and multi-agent
dashboard reference.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): add missing --cloud flag to adk ps docs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk-dev-console): address Greptile review comments on SKILL.md
Remove non-existent `adk agents` command from docs table and add
missing "About" footer action to the sidebar section.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk-dev-console): address Greptile review comments
- Add missing "About" to sidebar footer actions list
- Fix adk dev step 6 wording: "Dev Console available at" instead of
"Starts UI server" since the singleton may already be running
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk-dev-console): remove duplicate About in footer actions
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Use mktemp instead of hardcoded tmp.json in sync-versions.sh
- Add push trigger for master/dev in validate-version.yml
- Replace npx semver with bash regex for semver validation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add skills.json as single source of truth for ADK version compatibility.
Add sync-versions.sh to keep plugin.json and marketplace.json in sync.
Add CI workflow to validate version consistency on PRs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(adk): add workflow step methods reference
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): add cross-references to workflow-steps
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): correct step.abort() signature in workflows.md
step.abort() takes no arguments and is synchronous (void return),
not async with a reason string. Verified against runtime source.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): address review feedback on workflow-steps reference
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): remove broken delayed retry pattern from workflow-steps
The polling pattern with step caching + sleep + abort deadlocks after
the first cycle. Removed per reviewer request.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(adk): add interfaces reference
Document the built-in interface abstraction layer (typing-indicator, llm,
listable) that maps integration actions to a common contract. Covers
build-time mapping generation, runtime resolution, CLI commands, and
the relationship to integrations.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): add cross-references to interfaces
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): address review feedback on interfaces reference
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(adk): add plugin consumption reference
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): add cross-references to plugins
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(adk): correct CLI flags in plugins reference
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
github-actions[bot]