@botpress/adk-cli 1.19.0-beta.3 → 1.19.0-beta.5

package/dist/adk-build-emhwd0tg.md

@@ -0,0 +1,39 @@
+---
+name: adk-build
+description: Interview the user about a new ADK primitive or feature, then build it
+argument-hint: "[primitive] <description>"
+---
+
+Load the `adk` skill, then build the requested target immediately.
+
+The target can be a **single primitive** (one file under `src/`, e.g. an action called `calculate-discount`) or a **feature** — a piece of bot functionality that needs several primitives wired together (e.g. a checkout flow = workflow + actions + table). The user does not need to know which it is. Decide based on `$ARGUMENTS`:
+
+- If the first token is a primitive type — `action`, `tool`, `workflow`, `convo`/`conversation`, `table`, `trigger`, `kb`/`knowledge` — and the description fits one file, build a single primitive.
+- Otherwise treat the whole argument as a feature description and decompose it into the primitives needed.
+
+If `$ARGUMENTS` is empty or only a primitive type with no description, ask what the user wants to build (in outcome terms).
+
+## Workflow
+
+1. **Read context first.** Read `agent.config.ts` for available integrations and models. Glob `src/` and skim 1–2 existing primitives in each directory you expect to touch, to match the project's naming, file structure, and import style.
+
+   **Conversation handlers — read every existing one.** Glob `src/conversations/*.ts` and read each file's `channel:` field, not just one or two of them. Build a map of `<file> → <channels>`. From that map:
+
+   - **Default rule: extend, do not add.** If any existing handler routes through a channel set that overlaps with what the new behavior needs (and `*` overlaps with everything; identical arrays overlap; arrays sharing any one channel overlap), the new behavior must be added to that existing handler — new turn, new tool wiring, new state field, whatever — *not* a new file. Two conversation handlers with overlapping channels both fire on the same message and produce ambiguous routing; this is the failure mode the user has hit before.
+   - **Only create a new file when channels are disjoint.** A new conversation file is justifiable when its channel set has zero overlap with every existing handler — e.g., a Slack-only handler when all existing handlers are `webchat.channel` only. State the disjointness explicitly in the plan (step 4).
+   - **Or when the user asked for one.** If the user explicitly requested a separate handler ("a dedicated triage conversation distinct from the main chat"), honor that — but still call out the channel overlap in the plan so they can confirm.
+2. **Interview only about *what*, never *how*.** Ask only outcome and behavior questions — what should this do, when should it happen from the user's perspective, what does success look like. Do not ask about schemas, return types, durability, retry policy, channel routing, storage shape, or *which primitives to use* — infer those from the description, existing primitives, and sensible defaults.
+
+   Examples of acceptable questions:
+   - "What should this do, in plain language?"
+   - "When should it kick in — what's the user-visible trigger?"
+   - "What does success look like when this is done?"
+   - "Should this finish on its own, or pause and wait for someone?"
+   - For a feature: "Is X part of this, or a separate thing?" — only when scope is genuinely ambiguous.
+
+   Ask 1–3 questions max, only when the description leaves a genuine outcome-level gap. If the description already conveys intent, skip the interview entirely.
+3. **Decompose (feature mode only).** From the outcome, identify the primitives needed and the directories they belong in (`src/workflows/`, `src/actions/`, `src/tables/`, etc.). State the decomposition explicitly in the plan — *"This needs a `checkout` workflow, a `process-payment` action, and an `orders` table because …"*.
+4. **Propose a plan.** List every file to create or modify (full path), the exports, and any dependencies (integrations to add, models needed, `agent.config.ts` edits). For features, also describe how the primitives wire together. **If the plan involves a new conversation file**, include a one-line "channel-overlap check" justifying the new file (channels disjoint from every existing handler, or explicit user request) — if you can't justify it, fold the change into an existing handler instead. Wait for approval if the plan is non-trivial or touches `agent.config.ts`.
+5. **Build it.** Write the files under the right `src/<dir>/` paths. Use `@botpress/runtime` imports. Match the conventions you read in step 1. For a feature, build the primitives in dependency order (table → action → workflow → conversation), so each file's imports resolve as it's written. For conversation behavior, edit the existing handler identified in step 1 — do not spawn a new one unless step 4's channel-overlap check explicitly justified it.
+6. **Validate — always.** Run `adk check --format json` after every build, no exceptions. If it reports errors or warnings, fix them in this same turn and re-run. Do not report the task done until the check passes.
+7. **Suggest next steps.** Offer `/adk-validate <name>` to confirm wiring (especially for a feature), `/adk-test <name>` to run it once, and `/adk-eval <name>` to pin its behavior with assertions.

package/dist/adk-debug-yrrdtpmb.md

@@ -0,0 +1,23 @@
+---
+name: adk-debug
+description: Debug ADK bot issues
+argument-hint: "[error or problem description]"
+---
+
+Load the `adk-debugger` and `adk` skills, then start debugging immediately.
+
+If `$ARGUMENTS` is vague ("broken", "not working", "slow", "weird", or empty), don't ask "what's wrong?" — investigate first. Run `adk check --format json` and `adk logs error --format json`, then present what you found.
+
+If `$ARGUMENTS` mentions a specific component ("the search tool", "my workflow"), go directly to traces filtered by that component.
+
+If `$ARGUMENTS` contains a pasted error or stack trace, read the file at the referenced line number immediately.
+
+## Debug Workflow
+
+1. Run `adk check --format json` to rule out offline issues first.
+2. Reproduce with `adk chat --single "<relevant message>" --format json`.
+3. Read traces and logs: `adk logs error --format json`, `adk traces --format json`.
+4. Identify root cause using the debug workflow from the skill.
+5. Suggest a targeted fix.
+6. Verify the fix with another `adk chat` or `adk check`.
+7. Write a regression eval for the bug — load the `adk-evals` skill, generate the eval file using the reproduction message as the user turn and the verified behavior as assertions, save it to `evals/`, and run `adk evals <name>` to confirm it passes.

package/dist/adk-dev-console-7z9rtjpy.md

@@ -0,0 +1,17 @@
+---
+name: adk-dev-console
+description: Explain ADK Dev Console features, tabs, and UI concepts
+argument-hint: "[UI concept, tab name, or question]"
+---
+
+Load the `adk-dev-console` skill, then answer the user's question about **$ARGUMENTS** immediately.
+
+Resolve shorthand: "agent steps" = the execution visualizer on the Chat page, "turns" = conversation exchanges in Agent Steps, "iterations" = autonomous loop steps, "traces" = the Observe > Traces page, "cp" / "panel" / "console" = the Dev Console itself.
+
+If the user named a specific UI concept (e.g., "agent steps", "turns", "iterations"), look it up in the skill's references and explain what it is and what the user sees. A one-word or short topic is a conceptual question — give a clear definition and describe the visual, then stop.
+
+If the user named a tab or page (e.g., "evals tab", "observe", "tables"), explain what that page shows, its layout, and key features.
+
+If the user asks a broad question ("what is the dev console?", "what tabs are there?", or no arguments), give the quick reference from the SKILL.md — tab groups with their pages and purpose.
+
+If the user asks "where do I find X?", name the tab group, page, and URL path.

package/dist/adk-document-ras6zzzh.md

@@ -0,0 +1,68 @@
+---
+name: adk-document
+description: Create, review, update, sync, or search project documentation for an ADK bot
+argument-hint: "[action] [topic or doc-path]"
+---
+
+Load the `adk-docs` skill for documentation standards and the `adk` skill for ADK context, then help with documentation immediately.
+
+Parse `$ARGUMENTS` to determine the action. The first word is usually the action (but not always); everything after is the target.
+
+## Route by Action
+
+### create [topic]
+E.g., `/adk-document create workflows`, `/adk-document create the checkout flow`
+
+If the topic is a broad term ("workflows", "tools", "actions"), read `src/<relevant-dir>/` to enumerate the user's actual primitives first. Document *their specific implementations* — not generic concepts.
+
+1. **Research**: Find the user's ADK project (`agent.config.ts`), read relevant source files in `src/`, check existing docs in `./docs/` or `./guides/`.
+2. **Choose type**: Reference (400-500 lines), Conceptual (500-700), Comprehensive (600-800) — see doc-standards reference.
+3. **Write**: Every concept needs a working code example from the user's actual code. Include file paths for verification. Use clear headers for ripgrep searchability. No speculative Common Mistakes or Best Practices sections.
+4. **Save**: Ask where if unclear (common: `./docs/`, `./guides/`). Verify headers are searchable.
+
+### review [doc-path]
+E.g., `/adk-document review docs/workflows.md`
+
+Review the doc for technical accuracy, searchability, and completeness:
+- **Code accuracy**: correct imports (`@botpress/runtime`), examples from actual code with file paths, no speculation
+- **Searchability**: clear section headers, TOC present, keyword-rich section names
+- **ADK-specific**: distinguishes ADK vs SDK primitives, messages vs events, channel-specific vs agnostic
+- **Validation**: `Grep` for imports, check referenced files exist, flag speculative content
+
+Report: Critical Issues → Searchability Issues → Speculative Content → Missing Verification → Recommendations.
+
+### update [doc-path] [what-changed]
+E.g., `/adk-document update docs/workflows.md added new step type`
+
+1. Read the existing doc.
+2. Find what changed in the user's project code.
+3. Preserve existing structure, style, and TOC.
+4. Verify all code examples still work. Add new features with project code examples.
+5. Mark deprecations clearly. Update file path references.
+
+### sync [optional-doc-path]
+E.g., `/adk-document sync`, `/adk-document sync docs/actions.md`
+
+Check if docs are current with the code:
+1. Find API changes: new exports, deprecated features, changed signatures.
+2. Cross-reference: what's documented vs. what exists in `src/`.
+3. Verify: do documented code examples still match actual code?
+
+Report: Undocumented Features → Deprecated Content → Broken Examples → Missing Patterns → Recommendations.
+If gaps found, offer to fix them.
+
+### search [term]
+E.g., `/adk-document search workflows`, `/adk-document search sendMessage`
+
+1. Find project docs: `Glob({ pattern: "./{docs,guides}/**/*.md" })`
+2. Search headers and content for the term.
+3. Return: which file, which section, key excerpt (not full dump), related docs.
+4. If not found in docs, search the project code, then suggest creating docs for the gap.
+
+## If No Action Specified
+
+If `$ARGUMENTS` doesn't start with create/review/update/sync/search, infer the intent:
+- Looks like a file path (contains `/` or `.md`) → **review** that file
+- Looks like a search term → **search** for it
+- Looks like a topic to document → **create** docs for it
+- Looks like gibberish, ask the user a clarification question

package/dist/adk-eval-vx76dwq0.md

@@ -0,0 +1,17 @@
+---
+name: adk-eval
+description: Write, run, or debug evals for an ADK bot
+argument-hint: "[what to test]"
+---
+
+Load the `adk-evals` and `adk` skills, then help with evals immediately.
+
+If `$ARGUMENTS` names a primitive or feature (e.g., "search", "checkout", "tickets"), check if evals already exist (`Glob({ pattern: "evals/**" })`). If found, ask: run them, debug them, or write a new one? If not found, search `src/` for related primitives, read the source code, and generate an eval tailored to that code with realistic assertions.
+
+If `$ARGUMENTS` asks to run evals, run `adk evals` with appropriate flags.
+
+If `$ARGUMENTS` mentions a failure ("failing", "broken", "wrong"), inspect the failing eval's traces and identify whether the issue is the eval's assertions or the bot's behavior.
+
+If `$ARGUMENTS` is empty, check existing eval coverage (`Glob({ pattern: "evals/**" })`) and the user's primitives in `src/`, then suggest writing evals for untested primitives.
+
+Follow the eval format, assertion types, and per-primitive testing patterns from the skill documentation.

package/dist/adk-explain-fcsaw852.md

@@ -0,0 +1,22 @@
+---
+name: adk-explain
+description: Explain an ADK bot's architecture, flow, and components
+argument-hint: "[component or question about the bot]"
+---
+
+Load the `adk` skill, then answer the user's question about **$ARGUMENTS** immediately.
+
+Resolve shorthand first: "kbs" = knowledge bases, "convos" = conversations, "wf" = workflows, "int" = integrations, "config" = agent.config.ts.
+
+If the user named a specific ADK concept or primitive, look it up in the `adk` skill's references and explain it. Match depth to the question — a one-word topic like "kbs" is a conceptual question: give a one-sentence explanation and a short code example from the references, then stop.
+
+If the user is in an ADK project (check for `agent.config.ts`), also check whether their project uses the component they asked about. If it does, read the relevant source files in `src/` and explain *their specific setup* — not just the generic concept.
+
+If the user asks a broad question ("explain my bot", "what does this do?", or no arguments):
+
+1. Run `adk status --format json`.
+2. Read `agent.config.ts` and relevant source files in `src/`.
+3. Identify the bot archetype (RAG assistant, support agent, ticket router, automation, etc.).
+4. Map the flow: channels → conversations → tools/actions → tables/KBs.
+5. Flag any issues (unconfigured integrations, missing models, hardcoded secrets).
+6. Follow the explanation patterns in **references/explain-config.md** from the `adk` skill.

package/dist/adk-init-9kmxmbbe.md

@@ -0,0 +1,30 @@
+---
+name: adk-init
+description: Scaffold a new Botpress ADK project
+argument-hint: "[project-name]"
+---
+
+Help the user initialize a new Botpress ADK project.
+
+First, load the `adk` skill for full ADK knowledge.
+
+1. If `$ARGUMENTS` contains a project name, use it. Otherwise ask.
+2. Ensure the user is logged in (`adk login --token "$BOTPRESS_TOKEN"` or `adk login`).
+3. Run `adk init <name> --yes --skip-link --template hello-world` to scaffold the project.
+4. Guide through linking with `adk link` and initial configuration.
+5. Verify the project starts cleanly: `adk check --format json`.
+
+## After Scaffolding
+
+Don't just explain the project structure — ask what they want to build and guide next steps:
+
+*"Your project is ready. What are you building?"*
+
+- **Support agent** → suggest adding a conversation handler, ticket table, and relevant integrations (Slack, Linear, etc.)
+- **Knowledge-base Q&A** → suggest creating a knowledge base in `src/knowledge/` and a search tool
+- **Multi-channel bot** → suggest adding channel integrations (Slack, WhatsApp, Webchat) and a conversation handler
+- **Automation** → suggest creating workflows and triggers
+
+Then offer the relevant commands: `/adk-integration` to add services, `/adk-eval` to set up tests.
+
+Follow all ADK CLI best practices from the skill documentation.

package/dist/adk-ship-dybzn884.md

@@ -0,0 +1,29 @@
+---
+name: adk-ship
+description: Run pre-flight checks and deploy an ADK bot to production
+---
+
+Load the `adk` skill, then run pre-flight checks before deploying.
+
+This is a deploy-to-production command — treat it as destructive-by-default. Confirm with the user before running `adk deploy`, even when pre-flight is green. Never pass `--yes` to `adk deploy` unless the user has explicitly approved it in this turn.
+
+## Workflow
+
+1. **Pre-flight (run in parallel where possible):**
+   - `adk check --format json` — must pass with zero errors.
+   - `adk evals --format json` — must pass if any evals exist; if none exist, surface that as a warning and offer `/adk-eval` before shipping.
+   - `git status` — surface uncommitted changes; ask whether to ship the working tree as-is or commit first.
+   - `adk status --format json` — confirm the project is linked to the intended workspace and bot.
+   - Check `agent.config.ts` for unconfigured integrations (missing secrets, missing models). If any, block the ship and list them.
+
+2. **Summarize.** Show a tight pre-flight report: ✅ checks passed, ⚠️ warnings, ❌ blockers. Include the linked bot and a one-line diff summary if there are uncommitted changes.
+
+3. **Confirm.** Always ask before deploying — the original `/adk-ship` invocation is not consent. If there are blockers, stop and offer to fix each. Otherwise (warnings or fully green), ask: *"Ship to <bot>? (yes / no)"*.
+
+4. **Deploy.** Run `adk deploy`. Stream output. If `adk deploy` prompts for preflight approval, surface the prompt to the user — do not auto-approve.
+
+5. **Verify.** After deploy, run `adk status --format json` to confirm the deployed version. Report deployed version and any post-deploy warnings. Note: `adk chat` runs against the local dev bot, not the deployed one — do not use it as a production smoke test. Direct the user to the Dev Console for live verification.
+
+6. **Wrap up.** Link the user to the Dev Console if a URL is in the deploy output. If the ship fixed a bug, point the user at `/adk-eval` to capture a regression eval.
+
+Always re-run pre-flight on every `/adk-ship` invocation. The filesystem may have changed between invocations (manual edits, `git pull`, codegen) and there is no reliable way to detect that from inside the conversation.

package/dist/adk-test-xq67savs.md

@@ -0,0 +1,27 @@
+---
+name: adk-test
+description: Invoke an ADK primitive end-to-end with realistic input to confirm it works
+argument-hint: "[primitive name] [input]"
+---
+
+Load the `adk` skill, then run the named primitive immediately.
+
+This is exploratory, one-shot testing — *does it work right now?*. It is distinct from `/adk-eval`, which writes persistent assertion-based eval files. If the user wants assertions or coverage, route them there.
+
+If `$ARGUMENTS` is empty, list the user's primitives and ask which to test.
+
+## Workflow
+
+1. **Locate and identify type.** Glob `src/**/<name>.ts`. The directory tells you the type (action / tool / workflow / conversation / table / trigger / knowledge base).
+2. **Build an invocation appropriate for the type.** If the user provided input after the primitive name, use it as-is; otherwise generate a realistic probe from the primitive's schema:
+   - **Tool / conversation handler / agent step:** `adk chat --single "<probe message that exercises this primitive>" --format json`. The probe should plausibly cause the LLM to call the tool / route to the handler.
+   - **Action:** invoke through `adk run .adk/scratch/test-<name>.ts` after writing a small disposable runner under `.adk/scratch/`, or via a chat probe that triggers a tool which calls the action. Prefer the runner when the action has a deterministic input shape.
+   - **Workflow:** trigger via the documented entry point (chat probe, action call, or trigger event).
+   - **Trigger:** simulate the source event the trigger subscribes to. If the event source is external, explain the limitation and fall back to invoking the trigger handler directly via `adk run`.
+   - **Table:** insert a sample row, run a representative query, then **delete the row** before reporting. Tag the test row with a recognizable marker (e.g., a `__test_<timestamp>` value in a string column) so the cleanup query is unambiguous. If the project is linked to a shared or production workspace, ask the user before inserting at all — offer to scope the test to a local dev table instead.
+   - **Knowledge base:** run a search query against it.
+3. **Run it and read traces.** Capture the response. Run `adk traces --format json` filtered to the most recent invocation if the response alone is not enough to judge correctness.
+4. **Report.** Show the input used, the output, latency, and any errors or surprising behavior. Be explicit if the trace shows the primitive was *not* exercised (e.g., the LLM ignored the tool).
+5. **Suggest follow-ups.** If the test surfaced something worth pinning down, offer `/adk-eval <name>` to capture it as a regression eval. If it failed, offer `/adk-debug` with the relevant context.
+
+Clean up any disposable runner scripts under `.adk/scratch/test-*.ts` after the test unless the user asks to keep them.

package/dist/adk-validate-1p4skv4m.md

@@ -0,0 +1,31 @@
+---
+name: adk-validate
+description: Validate an ADK primitive or a feature (a set of related primitives)
+argument-hint: "[primitive or feature name]"
+---
+
+Load the `adk` skill, then validate the named target immediately.
+
+The target can be either a **single primitive** (one file under `src/`, e.g. a tool called `search` or a workflow called `checkout`) or a **feature** — a piece of bot functionality spread across multiple primitives (e.g. "checkout" implemented as `src/workflows/checkout.ts` + `src/actions/process-payment.ts` + `src/tables/orders.ts`). Resolve which one before validating.
+
+This is the proactive counterpart to `/adk-debug`: nothing is necessarily broken — confirm the target is correctly defined and wired up. If `$ARGUMENTS` is empty, list the user's primitives (Glob `src/**/*.ts` excluding `utils/`) and ask which one to validate.
+
+## Workflow
+
+1. **Run baseline checks first, in parallel.** TypeScript type check (the project's `typecheck` / `type-check` script in `package.json` if defined, otherwise `tsc --noEmit`) and `adk check --format json`. Capture both outputs. If either fails project-wide for reasons unrelated to the named primitive, surface that up front — the primitive's own issues are noise until the project compiles.
+2. **Resolve the target — primitive or feature.** Try in this order:
+   - **Exact primitive match.** Glob `src/**/<name>.ts`. If exactly one file matches, that's the target.
+   - **Multiple primitive matches.** List them with their types (action / tool / workflow / etc.) and ask which one — or whether the user wants to validate the whole set as a feature.
+   - **No exact match — treat as a feature.** Search the codebase for the term: file names, exported symbols, string literals, and comments under `src/`. Present the candidate set ("Found these files that look like the *<name>* feature: …") and confirm with the user before proceeding. If nothing plausible turns up, suggest the closest exact filename hits and stop.
+3. **Read each file in the target set.** Identify the type of each from its directory.
+4. **Filter the baseline output.** From the type-check and `adk check` output captured in step 1, pull out diagnostics that mention any name or file path in the target set.
+5. **Static checks** (read the sources and verify):
+   - Imports come from `@botpress/runtime` (not the SDK).
+   - Each primitive is exported in the shape the ADK expects for its type (see references in the `adk` skill).
+   - Zod / schema definitions cover all inputs and outputs the code uses.
+   - Any referenced integration is installed (`adk list --format json`) and configured in `agent.config.ts`.
+   - Any referenced model is available in the project's model config.
+   - Any referenced sibling primitive (table, action, tool) actually exists in `src/`.
+   - **Feature-level only:** the primitives in the set actually wire together — e.g., the workflow's action calls resolve to existing actions, the table the workflow writes to matches the schema the action reads.
+   - No hardcoded secrets, tokens, or API keys.
+6. **Report.** Group findings as ❌ Errors → ⚠️ Warnings → ✅ Passed, with each finding tagged by file. For a feature target, also include a short "wiring" subsection that summarizes how the primitives connect. End with one line: *"Run `/adk-test <name>` to actually invoke it."* Do not apply fixes from this command — let the user decide which to take.