@botpress/adk-cli 1.19.0-beta.4 → 1.19.0-beta.6

package/dist/SKILL-chnwzmt1.md

@@ -0,0 +1,548 @@
+---
+name: adk
+description: a set of guidelines to build with Botpress's Agent Development Kit (ADK) - use these whenever you're tasked with building a feature using the ADK
+license: MIT
+---
+
+# Botpress ADK Guidelines
+
+Use this skill when you've got questions about the Botpress Agent Development Kit (ADK) - like when you're building a feature that involves tables, actions, tools, workflows, conversations, files, knowledge bases, triggers, assets, integrations, plugins, evals, or Zai.
+
+## What is the ADK?
+
+The Botpress ADK is a **convention-based TypeScript framework** where **file structure maps directly to bot behavior**. Place files in the correct directories, and they automatically become available as bot capabilities.
+
+The ADK provides primitives for:
+
+- Actions & Tools (reusable functions and AI-callable tools)
+- Workflows (long-running, resumable processes)
+- Conversations (message handling)
+- Tables (data storage with semantic search)
+- Files (file storage with semantic search)
+- Knowledge Bases (RAG implementation)
+- Triggers (event-driven automation)
+- Assets (static files with permanent URLs)
+- Integrations (external service connections managed via CLI and lock files)
+- Plugins (reusable agent extensions with interface dependencies)
+- **Zai** (production-ready LLM utility library for common AI operations)
+
+### Project Structure (Convention-Based)
+
+Most primitives must be placed in `src/` directory (assets use the `assets/` directory at the project root):
+
+```
+/                      # Project root
+├── assets/            # Static files → synced to Botpress Cloud with permanent URLs
+├── src/
+│   ├── actions/       # Strongly-typed functions → auto-registered
+│   ├── tools/         # AI-callable tools → available via execute()
+│   ├── workflows/     # Long-running processes → resumable/scheduled
+│   ├── conversations/ # Message handlers → routes by channel
+│   ├── tables/        # Database schemas → auto-created with search
+│   ├── triggers/      # Event handlers → subscribe to events
+│   ├── knowledge/     # Knowledge bases → RAG with semantic search
+│   └── utils/         # Shared helpers (not auto-registered)
+├── dependencies.dev.lock.json   # Integration/plugin state (dev)
+├── dependencies.prod.lock.json  # Integration/plugin state (prod)
+└── agent.config.ts    # Bot configuration
+```
+
+> **Note:** Integrations and plugins are managed via lock files and the `adk integrations` / `adk plugins` CLI. See `integrations.md` and `plugins.md`.
+
+> **Critical:** Files outside `src/` are not discovered. Location = behavior.
+
+## Session Start
+
+The first time you help with an ADK project in a session, silently check the project's health:
+
+1. Run `adk check --format json` and `adk status --format json`.
+2. If there are errors or warnings (unconfigured integrations, missing models, validation issues), proactively mention them before answering the user's question: *"Before we start — I noticed [issue]. Want me to help fix that?"*
+3. Only do this once per session. Don't re-run on every question.
+
+## Available Commands
+
+If the user asks "what can you help with?", "what commands are available?", or invokes `/adk-explain` without arguments, present:
+
+- **Build**: `/adk-init` (scaffold project), `/adk-build` (interview & build a primitive), `/adk-integration` (add services), `/adk-frontend` (build UI)
+- **Test & Debug**: `/adk-validate` (check a primitive's schema/types/config), `/adk-test` (invoke a primitive once), `/adk-eval` (write assertion tests), `/adk-debug` (fix issues)
+- **Ship**: `/adk-ship` (pre-flight checks + deploy)
+- **Document**: `/adk-document` (create, review, update, sync, search)
+- **Understand**: `/adk-explain` (explain bot architecture and components), `/adk-dev-console` (navigate the Dev Console)
+
+Then ask: *"What are you working on?"*
+
+## When to Use This Skill
+
+Activate this skill when users ask ADK-related questions like:
+
+- "How do I create an Action/Tool/Workflow/Conversation?"
+- "What is the difference between X and Y?"
+- "Show me an example of..."
+- "How do I configure...?"
+- "What's the CLI command for...?"
+- "How do I use the Context API?"
+- "How do I call integration actions?"
+- "How do I use Zai for [extract/check/label/etc]?"
+- "What are the best practices for...?"
+- "How do I avoid common mistakes?"
+- "How do I handle ticket assignment/escalation?"
+- "Explain my config"
+- "What does my bot do?"
+- "What models am I using?"
+- "What integrations do I have?"
+- "What state does my bot track?"
+
+## Plugin Installation Prompt
+
+If you are running inside Claude Code and the `/adk-*` commands (like `/adk-debug`, `/adk-eval`, `/adk-init`) are not available as slash commands, suggest that the user install the Botpress ADK plugin to get the full set of skills and commands:
+
+```
+/plugin marketplace add botpress/skills
+/plugin install adk@botpress-skills
+```
+
+Only suggest this once per session. If the user declines, do not ask again.
+
+## How to Answer ADK Questions
+
+ADK questions fall into two categories: **CLI queries** and **documentation lookups**.
+
+### Option 1: Direct CLI Commands (FAST - Use First!)
+
+For integration discovery and CLI queries, use the Bash tool to run commands directly:
+
+**Integration Discovery:**
+
+```bash
+# Search for integrations
+adk integrations search <query>
+
+# List all available integrations
+adk integrations list --available
+
+# Get detailed integration info (actions, channels, events)
+adk integrations info <integration-name>
+
+# Check installed integrations (must be in ADK project)
+adk integrations list
+```
+
+**Project Info:**
+
+```bash
+# Check CLI version
+adk --version
+
+# Show project status
+adk
+
+# Get help
+adk --help
+```
+
+**Prefer non-interactive paths when driving ADK workflows:**
+
+```bash
+# Login without browser prompts
+adk login --token "$BOTPRESS_TOKEN"
+
+# Scaffold with sensible defaults and skip linking
+adk init my-agent --yes --skip-link
+
+# Link directly when IDs are known
+adk link --workspace ws_123 --bot bot_456
+
+# More automation-friendly dev mode (NDJSON events, no TUI)
+adk dev --non-interactive
+
+# Auto-approve non-destructive deploy-plan changes
+adk deploy --yes
+```
+
+Use these defaults when relevant:
+
+- Prefer `adk login --token "$BOTPRESS_TOKEN"` or `adk login --token <token>` over interactive login.
+- Treat bare `BOTPRESS_TOKEN` as a no-TTY convenience, not a guaranteed interactive-terminal shortcut.
+- Prefer `adk init <name> --yes --skip-link` for AI-driven scaffolding, but only after login is already completed.
+- Treat `adk link --workspace ... --bot ...` as scriptable, but not guaranteed safe in every no-TTY environment.
+- Treat `adk dev --non-interactive` as CI-friendly, not fully prompt-free.
+- Treat `adk deploy --yes` as auto-approving non-destructive deploy-plan changes; config validation and destructive storage changes can still block automation.
+
+**When to use CLI commands:**
+
+- "What integrations are available?"
+- "Search for Slack integration"
+- "Show me details about the Linear integration"
+- "What actions does the Slack integration have?"
+- "What version of ADK am I using?"
+- "How do I add an integration?"
+
+**Response pattern:**
+
+1. Use Bash tool to run the appropriate `adk` command
+2. Parse and present the output to the user
+3. Optionally suggest next steps (e.g., "Run `adk integrations add slack@3.0.0` to install")
+
+### Option 2: Documentation Questions (For Conceptual Questions)
+
+For documentation, patterns, and how-to questions, search and reference the documentation files directly:
+
+**When to use documentation:**
+
+- "How do I create a workflow?"
+- "What's the difference between Actions and Tools?"
+- "Show me an example of using Zai"
+- "What are best practices for state management?"
+- "How do I fix this error?"
+- "What's the pattern for X?"
+
+**How to answer documentation questions:**
+
+1. **Find relevant files** - Use Glob to discover documentation:
+
+   ```
+   pattern: **/references/*.md
+   ```
+
+2. **Search for keywords** - Use Grep to find relevant content:
+
+   ```
+   pattern: <keyword from user question>
+   path: <path to references directory from step 1>
+   output_mode: files_with_matches
+   ```
+
+3. **Read the files** - Use Read to load relevant documentation
+
+4. **Provide answer** with:
+   - Concise explanation
+   - Code examples from the references
+   - File references with line numbers (e.g., "From references/actions.md:215")
+   - Common pitfalls if relevant
+   - Related topics for further reading
+
+### Option 3: Config Explanation (CLI + File Reading)
+
+For questions about what a bot does, how it's configured, or what it's capable of, combine CLI and file reading:
+
+**When to use:**
+
+- "What does my bot do?"
+- "Explain my config"
+- "What models am I using?"
+- "What integrations do I have?"
+- "What state does my bot track?"
+
+**Response pattern:**
+
+1. Run `adk status --format json` to get the structured project overview
+2. Read `agent.config.ts` for full configuration details
+3. Follow the explanation patterns in **references/explain-config.md**
+4. Produce a structured explanation covering metadata, models, integrations, state, and primitives
+5. Flag any issues (unconfigured integrations, missing models, hardcoded secrets)
+
+## Available Documentation
+
+Documentation should be located in `./references/` directory relative to this skill. When answering questions, search for these topics:
+
+### Core Concepts
+
+- **actions.md** - Actions with strong typing and validation
+- **tools.md** - AI-callable tools and Autonomous namespace
+- **autonomous-execution.md** - Advanced execute() API: Objects, Exits, hooks, configuration
+- **workflows.md** - Workflows and step-based execution
+- **workflow-steps.md** - Complete Workflow Step API reference (step.request, step.map, step.notify, etc.)
+- **conversations.md** - Conversation handlers and message routing
+- **conversation-lifecycle.md** - Nudge/expiration lifecycle management for conversations
+- **triggers.md** - Event-driven automation
+- **messages.md** - Sending messages and events
+- **custom-components.md** - Custom webchat components (`.bp.tsx` files, metadata, usage in conversations)
+
+### Zai (AI Operations)
+
+- **zai-agent-reference.md** - Quick reference: all operations, everyday problems Zai solves, edge cases & gotchas
+- **zai-complete-guide.md** - Full developer guide: architecture, active learning, chunking, performance tuning
+
+### Data & Content
+
+- **tables.md** - Data storage with semantic search
+- **files.md** - File storage and management
+- **knowledge-bases.md** - RAG implementation
+- **assets.md** - Static files with permanent URLs and sync lifecycle
+
+### Configuration & Integration
+
+- **agent-config.md** - Bot configuration and state management
+- **explain-config.md** - How to interpret and explain an agent's configuration to developers
+- **model-configuration.md** - AI model configuration reference
+- **context-api.md** - Runtime context access
+- **integration-actions.md** - Using integration actions
+- **tags.md** - Entity tags for bot, user, conversation, and workflow
+- **cli.md** - Complete CLI command reference
+- **mcp-server.md** - MCP server for AI assistants
+- **desk.md** - Desk integration for ticket/support workflows
+- **integrations.md** - Integration management overview (points to adk-integrations skill)
+- **interfaces.md** - Built-in interface abstraction layer over integrations (typing indicators, LLM, listable)
+- **plugins.md** - Plugin consumption: discovery, installation, configuration, and usage
+
+### Patterns & Best Practices
+
+- **advanced-patterns.md** - Guardrails, admin auth, logging/observability, extension composition
+- **patterns-mistakes.md** - Common mistakes, correct patterns, and context access reference
+
+### Frontend Integration
+
+> **Note:** Frontend integration docs are in the separate **adk-frontend** skill. Install it with `npx skills add botpress/skills --skill adk-frontend`. The `adk-frontend` skill covers @botpress/client, calling actions, type generation, and authentication. You need it if you are touching any frontend code.
+
+### Evals
+
+> **Note:** Detailed eval docs are in the separate **adk-evals** skill. Install it with `npx skills add botpress/skills --skill adk-evals`. The `adk-evals` skill covers writing evals, assertion types, testing workflows, and CLI usage. You usually always need it, for testing and evaluations.
+
+## Runtime Access Patterns
+
+Quick reference for accessing ADK runtime services:
+
+### Imports
+
+```typescript
+// Always import from @botpress/runtime
+import {
+  Action,
+  Autonomous,
+  Workflow,
+  Conversation,
+  z,
+  actions,
+  adk,
+  user,
+  bot,
+  conversation,
+  configuration,
+  context,
+} from "@botpress/runtime";
+```
+
+### State Management
+
+```typescript
+// Bot state (defined in agent.config.ts)
+bot.state.maintenanceMode = true;
+bot.state.lastDeployedAt = new Date().toISOString();
+
+// User state (defined in agent.config.ts)
+user.state.preferredLanguage = "en";
+user.state.onboardingComplete = true;
+
+// User tags
+user.tags.email; // Access user metadata
+```
+
+### Calling Actions
+
+```typescript
+// Call bot actions
+await actions.fetchUser({ userId: "123" });
+await actions.processOrder({ orderId: "456" });
+
+// Call integration actions
+await actions.slack.sendMessage({ channel: "...", text: "..." });
+await actions.linear.issueList({ teamId: "..." });
+
+// Convert action to tool
+tools: [fetchUser.asTool()];
+```
+
+### Context API
+
+```typescript
+// Get runtime services
+const client = context.get("client"); // Botpress client
+const cognitive = context.get("cognitive"); // AI model client
+const citations = context.get("citations"); // Citation manager
+```
+
+### File Naming
+
+- **Actions/Tools/Workflows**: `myAction.ts`, `searchDocs.ts` (camelCase)
+- **Tables**: `Users.ts`, `Orders.ts` (PascalCase)
+- **Conversations/Triggers**: `chat.ts`, `slack.ts` (lowercase)
+
+## Critical ADK Patterns (Always Reference in Answers)
+
+When answering questions, always verify these patterns against the documentation:
+
+### Package Management
+
+```bash
+# All package managers are supported
+bun install       # Recommended (fastest)
+npm install       # Works fine
+yarn install      # Works fine
+pnpm install      # Works fine
+
+# ADK auto-detects based on lock files
+# - bun.lockb → uses bun
+# - package-lock.json → uses npm
+# - yarn.lock → uses yarn
+# - pnpm-lock.yaml → uses pnpm
+```
+
+### Imports
+
+```typescript
+// ✅ CORRECT - Always from @botpress/runtime
+import { Action, Autonomous, Workflow, z } from "@botpress/runtime";
+
+// ❌ WRONG - Never from zod or @botpress/sdk
+import { z } from "zod"; // ❌ Wrong
+import { Action } from "@botpress/sdk"; // ❌ Wrong
+```
+
+### Export Patterns
+
+```typescript
+// ✅ Both patterns work - export const is recommended
+export const myAction = new Action({ ... });  // Recommended
+export default new Action({ ... });           // Also valid
+
+// Why export const?
+// - Enables direct imports: import { myAction } from "./actions/myAction"
+// - Can pass to execute(): tools: [myAction.asTool()]
+```
+
+### Actions
+
+```typescript
+// ✅ CORRECT - Handler receives { input, client }
+export const fetchUser = new Action({
+  name: "fetchUser",
+  async handler({ input, client }) {  // ✅ Destructure from props
+    const { userId } = input;         // ✅ Then destructure fields
+    return { name: userId };
+  }
+});
+
+// ❌ WRONG - Cannot destructure input fields directly
+handler({ userId }) {  // ❌ Wrong - must be { input }
+  return { name: userId };
+}
+```
+
+### Tools
+
+```typescript
+// ✅ CORRECT - Tools CAN destructure directly
+export const myTool = new Autonomous.Tool({
+  handler: async ({ query, maxResults }) => {
+    // ✅ Direct destructuring OK
+    return search(query, maxResults);
+  },
+});
+```
+
+### Conversations
+
+```typescript
+// ✅ CORRECT - Use conversation.send() method
+await conversation.send({
+  type: "text",
+  payload: { text: "Hello!" }
+});
+
+// ❌ WRONG - Never use client.createMessage() directly
+await client.createMessage({ ... });  // ❌ Wrong
+```
+
+### Conversation Handler Types
+
+```typescript
+// Handler receives typed context based on the event type:
+// type: "message" | "event" | "workflow_request" | "workflow_callback"
+async handler({ type, message, event, request, completion, conversation, execute }) {
+  if (type === "workflow_request") {
+    // event: WorkflowDataRequestEventType, request: WorkflowRequest
+    await request.workflow.provide("email", { email: "..." });
+  }
+  if (type === "workflow_callback") {
+    // event: WorkflowCallbackEventType, completion: WorkflowCallback
+    console.log(completion.status); // "completed" | "failed" | "canceled" | "timed_out"
+  }
+}
+
+// ⚠️ isWorkflowDataRequest() and isWorkflowCallback() are deprecated
+// Use type === "workflow_request" / "workflow_callback" instead
+```
+
+## Examples of Questions This Skill Answers
+
+### Beginner Questions
+
+- "What is an Action?"
+- "How do I create my first workflow?"
+- "What's the difference between Actions and Tools?"
+
+### Implementation Questions
+
+- "How do I access the Botpress client?"
+- "How do I use citations in RAG?"
+- "What's the syntax for searchable table columns?"
+- "How do I call a Slack integration action?"
+- "How do I use Zai to extract structured data?"
+- "How do I validate content with Zai?"
+
+### Advanced Pattern Questions
+
+- "How do I add guardrails to prevent hallucinations?"
+- "How do I implement admin authentication?"
+- "How do I add logging and observability?"
+- "How do I compose multiple extensions?"
+- "How do I manage context in async tool handlers?"
+
+### Troubleshooting Questions
+
+- "Why am I getting 'Cannot destructure property' error?"
+- "How do I fix import errors?"
+- "What's wrong with my workflow state access?"
+
+### Best Practices Questions
+
+- "What are common mistakes to avoid?"
+- "How should I structure my project?"
+- "What's the recommended pattern for X?"
+
+## Response Format
+
+**Match your response depth to the question depth.** Not every question needs a full walkthrough.
+
+### Conceptual Questions ("what is X?", "what's the difference between X and Y?")
+
+One sentence definition + one short code example. That's it.
+
+```
+Knowledge bases add RAG to your bot — place markdown or PDF files in `src/knowledge/` and they become queryable with semantic search.
+
+import { Autonomous } from '@botpress/runtime'
+export default new Autonomous.Tool({
+  handler: async ({ query }) => adk.knowledgeBase.search({ query }),
+})
+```
+
+### How-To Questions ("how do I create X?", "how do I use X?")
+
+Brief explanation + working code example + one critical pitfall only if it's a common trap.
+
+### Implementation Questions ("implement X in my project", "add X to my bot")
+
+Read the user's existing files first (`src/actions/`, `src/tools/`, `src/tables/`, `agent.config.ts`). Generate code that uses their actual names, patterns, and conventions. Only mention pitfalls they're likely to hit given their specific code.
+
+### Architecture Questions ("explain my bot", "how does X work in my project?")
+
+Full structured response: read `adk status --format json`, `agent.config.ts`, and relevant source files. Map the data flow and identify the bot's archetype (RAG assistant, support agent, automation, etc.).
+
+### Troubleshooting Questions ("X is broken", "why is X failing?")
+
+Don't answer with documentation. Run `adk check --format json` and `adk logs error --format json`, show evidence, and point to the root cause. Follow the debug loop from the `adk-debugger` skill.
+
+### Default Rule
+
+If the answer fits in one sentence and a code snippet, don't add headers, pitfall sections, or related topics. More structure ≠ more helpful.