{ "plugins": { "webhook.delivery": { "provider": "webhooks", "options": { "webhooks": [ { "id": "wh_a1b2c3d4e5f67890", "url": "https://example.com/hook", "events": ["task.created", "task.updated"], "active": true } ] } } } } ``` Webhook management still converges on the same SDK methods, but ownership is now split by host surface: - SDK: additive extension path via `sdk.getExtension('kl-plugin-webhook')`, plus stable compatibility shims on `sdk.listWebhooks()`, `sdk.createWebhook()`, `sdk.updateWebhook()`, `sdk.deleteWebhook()`, and `sdk.getWebhookStatus()` - REST API: plugin-owned `/api/webhooks` routes via the standalone HTTP plugin seam - CLI: plugin-owned `kl webhooks`, `kl webhooks add`, `kl webhooks update`, `kl webhooks remove` - MCP: plugin-owned `list_webhooks`, `add_webhook`, `update_webhook`, `remove_webhook` via the `mcpPlugin` registration seam ### Events | Event | Trigger | |-------|---------| | `task.created` | A new task is created | | `form.submit` | A card form payload is validated, persisted, and submitted | | `task.updated` | Task properties are changed | | `task.moved` | Task is moved to a different column or transferred between boards | | `task.deleted` | A task is deleted | | `comment.created` | A comment is added to a task | | `comment.updated` | A comment is edited | | `comment.deleted` | A comment is removed | | `column.created` | A new column is added | | `column.updated` | Column name or color is changed | | `column.deleted` | A column is removed | | `attachment.added` | A file is attached to a task | | `attachment.removed` | An attachment is removed from a task | | `settings.updated` | Board display settings are changed | | `board.created` | A new board is created | | `board.updated` | Board configuration is changed | | `board.deleted` | A board is deleted | | `board.action` | A board-level action is triggered from the toolbar, CLI, REST API, or MCP | | `card.action.triggered` | A card action is triggered | | `board.log.added` | A board log entry is appended | | `board.log.cleared` | Board log entries are cleared | | `log.added` | A card log entry is appended | | `log.cleared` | Card log entries are cleared | | `storage.migrated` | Card storage is migrated between providers | | `form.submitted` | A card form payload is validated, persisted, and submitted | ### Payload ```json { "event": "task.created", "timestamp": "2026-02-21T10:30:00.000Z", "data": { "id": "my-task", "status": "todo", "priority": "high", "..." : "..." } } ``` ### Headers - `Content-Type: application/json` - `X-Webhook-Event: task.created` - `X-Webhook-Signature: sha256=` (if a secret is configured) - `Authorization: Bearer ` (when `KANBAN_LITE_TOKEN` is set in the webhook runtime) ### Manage via CLI or API ```bash # Register kl webhooks add --url https://example.com/hook --events task.created,task.moved --secret mykey # Update kl webhooks update wh_abc123 --active false kl webhooks update wh_abc123 --events task.created,task.deleted # API curl -X POST http://localhost:3000/api/webhooks \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com/hook", "events": ["task.created", "task.moved"], "secret": "mykey"}' ``` Webhook registrations are stored in `.kanban.json` at the workspace root and persist across server restarts. Subscriptions support exact event names, `*`, and prefix wildcards ending in `.*` such as `task.*` or `board.log.*`. Only committed SDK after-events are delivered; before-events such as `form.submit` stay internal to the SDK lifecycle. ## Card Forms Forms let you attach structured JSON Schema-driven workflows directly to cards. Each attachment becomes its own tab in the webview card editor, is validated with the SDK-owned rules, and can be submitted from the UI, CLI, REST API, SDK, or MCP. ### Define reusable workspace forms Declare named reusable forms in `.kanban.json` under the top-level `forms` map: ```json { "forms": { "incident-report": { "schema": { "type": "object", "title": "Incident Report", "properties": { "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "owner": { "type": "string" }, "service": { "type": "string" } }, "required": ["severity", "owner"] }, "ui": { "type": "VerticalLayout", "elements": [ { "type": "Control", "scope": "#/properties/severity" }, { "type": "Control", "scope": "#/properties/owner" }, { "type": "Control", "scope": "#/properties/service" } ] }, "data": { "severity": "medium" } } } } ``` ### Attach forms to cards Cards can attach reusable named forms or inline card-local definitions in frontmatter: ```yaml forms: - name: incident-report - schema: type: object title: Postmortem properties: summary: type: string data: summary: Initial draft formData: incident-report: service: billing ``` ### Merge order and submit behavior For every attached form, the resolved payload is built in this order, from lowest to highest priority: 1. Workspace form defaults from `.kanban.json` (`forms..data`) 2. Card-scoped attachment defaults, then previously persisted `formData[formId]` 3. Card metadata fields whose keys exist in the form schema 4. The submitted payload The SDK validates that final payload before persistence and before any `form.submit` webhook fires. After a successful submission, Kanban Lite also appends a card log entry containing the submitted payload for traceability. ### Webview behavior - Every attached form renders as an extra tab in the card editor. - Tabs are stable and deep-linkable in standalone mode using `form:` tab ids. - Tab labels use the resolved display name and render as `form:

`. - Shared config forms show a **Shared** badge in the tab content. - Shared config forms may define `name` (default: capitalized form key) and `description` (default: empty string) in `.kanban.json`. - Submit stays disabled until validation passes, and successful submissions update the card's saved `formData`. - Successful submissions also append a system card log whose JSON object includes `formId`, `formName`, and the submitted `payload`. ### Programmatic submission surfaces - **SDK**: `await sdk.submitForm({ cardId, formId, data, boardId? })` - **CLI**: `kl form submit --data ''` - **REST API**: `POST /api/tasks/:id/forms/:formId/submit` - **Board-scoped REST API**: `POST /api/boards/:boardId/tasks/:id/forms/:formId/submit` - **MCP**: `submit_card_form` ## Card Actions Actions let you attach named triggers to a card — things like `retry`, `deploy`, `rollback`, or `notify`. When triggered, the system sends an HTTP POST to a single global **action webhook URL** configured in `.kanban.json`, with the action name and the full card context. Your webhook handles the actual work. ### How it works 1. **Configure the webhook URL** in `.kanban.json`: ```json { "actionWebhookUrl": "https://example.com/kanban-actions" } ``` 2. **Add actions to a card** — either as an array of action keys, or an object mapping action keys to display titles: ```yaml # Array form — action key is used as the button label actions: ["retry", "rollback", "notify-slack"] # Object form — keys are the action names sent to the webhook, values are the UI labels actions: retry: "Retry deployment" rollback: "Roll back to v1" notify-slack: "Notify Slack" ``` 3. **Trigger an action** from any interface: - **UI**: Open a card in the editor — a "Run Action" dropdown appears in the header when the card has actions. Click to select and fire. - **CLI**: `kl action trigger ` - **REST API**: `POST /api/tasks/:id/actions/:action` - **SDK**: `await sdk.triggerAction(cardId, action)` - **MCP**: `trigger_action` tool ### Webhook payload ```json { "action": "notify-slack", "board": "default", "list": "in-progress", "card": { "id": "42-deploy-v2", "status": "in-progress", "priority": "high", "assignee": "alice", "labels": ["deploy"], "content": "# Deploy v2.0\n...", "actions": ["retry", "rollback", "notify-slack"] // or {"retry": "Retry deployment", ...} } } ``` The webhook receives the full card object (same shape as the SDK `Card` type, minus `filePath`). Your server responds with any 2xx status to acknowledge; non-2xx responses are treated as errors. ### Managing actions Actions are stored in the `actions` field of the card's YAML frontmatter — either as a plain string array or as a key→title object. Edit them directly in the markdown file, or use any interface: ```bash # Add actions when creating a card kl add --title "Deploy service" --priority high --actions "retry,rollback,notify-slack" # Update actions on an existing card kl edit 42 --actions "retry,rollback,notify-slack,promote" # Trigger kl action trigger 42 notify-slack ``` ```bash # Via REST API curl -X POST http://localhost:3000/api/tasks/42/actions/notify-slack # Create card with actions via API curl -X POST http://localhost:3000/api/tasks \ -H "Content-Type: application/json" \ -d '{"content": "# Deploy v2.0", "status": "todo", "actions": ["retry", "rollback"]}' ``` ### Notes - There is **one global webhook URL** for all actions across all boards. The `action` field in the payload tells your server which action was triggered; the `board` and `list` fields provide context. - If `actionWebhookUrl` is not set, triggering an action returns an error. - Actions are **fire-and-forget** — no retry logic or delivery guarantees are built in. Implement idempotency and retries in your own webhook handler if needed. - Action strings have no special meaning to Kanban Lite; you define the vocabulary. ## Board Actions Board actions are the board-level sibling to card actions. Define them once per board, and they appear in the toolbar **Actions** dropdown for that board. If you prefer not to edit raw JSON, the shared settings panel now exposes the same per-board action list under **Board → Actions**, including stable action keys and user-facing titles. ### How it works 1. **Define actions on the board** in `.kanban.json`: ```json { "boards": { "default": { "name": "Default Board", "actions": { "deploy": "Deploy to Production", "announce": "Post release update" } } } } ``` 2. **Trigger them from any interface**: - **UI**: Use the toolbar **Actions** dropdown on a board that defines actions. - **CLI**: `kl board-actions fire --board ` - **REST API**: `POST /api/boards/:boardId/actions/:key/trigger` - **MCP**: `trigger_board_action` 3. **Receive a webhook event**: triggering a board action emits a `board.action` event containing the board ID, action key, and display title. ### Managing board actions ```bash # List existing actions kl board-actions list --board default # Add or update a named action kl board-actions add --board default --key deploy --title "Deploy to Production" # Remove an action kl board-actions remove --board default deploy # Trigger an action kl board-actions fire --board default deploy ``` ## n8n Integration Kanban Lite ships a first-party n8n package at `packages/n8n-nodes-kanban-lite`, published as [`n8n-nodes-kanban-lite`](https://www.npmjs.com/package/n8n-nodes-kanban-lite). It adds two nodes: - **`Kanban Lite`** — app node for boards, cards, columns, comments, attachments, labels, settings, storage, forms, webhooks, workspace info, and auth status - **`Kanban Lite Trigger`** — trigger node for transport-aware Kanban Lite events Both nodes support two connection modes: | Mode | Best for | Requirements | |------|----------|--------------| | **Remote API** | Connecting n8n to a running standalone Kanban Lite server | Configure the `Kanban Lite API` credential with server URL and auth settings | | **Local SDK** | Running n8n on the same machine as the workspace for direct local access | Configure the `Kanban Lite SDK (Local)` credential, make the workspace path accessible to n8n, and install `kanban-lite` in the n8n runtime so the node can load `kanban-lite/sdk` | Trigger parity is intentionally asymmetric: - **Local SDK mode** can subscribe to both **before-events** and **after-events** from the canonical SDK event catalog - **Remote API mode** receives **after-events only** through webhook delivery from the standalone server - **Remote API trigger mode requires a reachable n8n webhook URL** so Kanban Lite can POST event deliveries back into the workflow In practice, that means SDK mode can observe pre-commit events such as `card.create`, `column.reorder`, `storage.migrate`, or `form.submit`, while both modes can observe committed events such as `task.created`, `task.updated`, `board.created`, `comment.updated`, `attachment.added`, `form.submitted`, `storage.migrated`, and `auth.allowed` / `auth.denied`. See [`packages/n8n-nodes-kanban-lite/README.md`](packages/n8n-nodes-kanban-lite/README.md) for installation steps, credential setup, action coverage, and trigger examples. ## CrewAI Integration Kanban Lite ships a first-party Python package at `packages/kl-adapter-crewai`, published as [`kl-adapter-crewai`](https://pypi.org/project/kl-adapter-crewai/). It wraps kanban-lite REST API operations as CrewAI `BaseTool` subclasses so specialized agents (PM, Dev, QA) can each manage their own board lane. ```bash pip install kl-adapter-crewai ``` ```python from crewai import Agent from kl_adapter_crewai import KanbanLiteClient, KanbanLiteToolkit client = KanbanLiteClient("http://localhost:3000") toolkit = KanbanLiteToolkit(client=client) pm_agent = Agent( role="Project Manager", goal="Keep the board organized", backstory="You are a seasoned PM.", tools=toolkit.get_tools(), ) ``` 9 tools are available: `list_cards`, `get_card`, `create_card`, `update_card`, `move_card`, `delete_card`, `list_columns`, `get_comments`, `add_comment`. Use `toolkit.get_tools(read_only=True)` for report-only agents. See [`packages/kl-adapter-crewai/README.md`](packages/kl-adapter-crewai/README.md) for full setup, multi-agent examples, and authentication configuration. ## LangChain / LangGraph Integration Kanban Lite ships a first-party LangChain adapter at `packages/kl-adapter-langchain`, published as [`kl-adapter-langchain`](https://www.npmjs.com/package/kl-adapter-langchain). It exposes all kanban-lite features as **39 LangChain `StructuredTool` instances** — including streaming comments, labels, actions, logs, and attachments. ```sh npm install kl-adapter-langchain @langchain/core # optional – for LangGraph state/nodes: npm install @langchain/langgraph ``` ### Quick Start ```ts import { KanbanSDK } from 'kanban-lite/sdk' import { createKanbanToolkit } from 'kl-adapter-langchain' const sdk = new KanbanSDK('/path/to/.kanban') await sdk.init() const tools = createKanbanToolkit(sdk) // Pass `tools` to any LangChain agent or LangGraph ToolNode ``` ### LangGraph Support Optional LangGraph helpers (`getKanbanBoardState`, `createRefreshBoardNode`, `createKanbanToolNode`) provide a board-state annotation and pre-built graph nodes for stateful agent workflows. ### Streaming Comments The `streamCommentDirect` helper enables true chunk-by-chunk comment streaming from an `AsyncIterable` (e.g. an LLM textStream), with `onStart` / `onChunk` callbacks for live WebSocket broadcast. See [`packages/kl-adapter-langchain/README.md`](packages/kl-adapter-langchain/README.md) for detailed usage, selective tool loading, streaming examples, and LangGraph integration guide. ## MCP Server Expose your kanban board to AI agents (Claude, Cursor, etc.) via the [Model Context Protocol](https://modelcontextprotocol.io/). ### Setup with Claude Code Add to your `.claude/settings.json`: ```json { "mcpServers": { "kanban": { "type": "stdio", "command": "npx", "args": ["kanban-lite", "mcp"], "env": { "KANBAN_DIR": "/path/to/your/project/.kanban" } } } }

kanban-lite

Installation