Create Kandev Plugin

Create Kandev Plugin

Build Kandev runtime plugins from the official template and current public contracts. Keep plugin source outside the Kandev monorepo and prove the packaged artifact against a disposable development instance before publishing it.

Start with the canonical plugin authoring guide. Use this skill for the repository workflow after choosing a recipe there: choose recipe → edit manifest → implement → validate → package → smoke test. The guide owns the complete hook/Host matrix; this skill keeps the repository and verification procedure concise.

Establish The Boundary

1. Invoke this skill only when the user intends to create, change, fix, test, package, release, or submit a Kandev runtime plugin. A passing mention of plugins, a generic extension request, or the presence of plugin host code in the Kandev monorepo is not sufficient.
2. Confirm the artifact: a Kandev runtime plugin ships a manifest.yaml, a platform executable built with the Go pluginsdk, and optionally a native UI bundle. Agent instruction packages, MCP servers, and other products that also use the word "plugin" are outside this skill.
3. Classify the work as a new plugin, an existing plugin change, a Kandev host or SDK dependency required by the plugin, or a marketplace-only change.
4. Keep each production plugin in one dedicated repository. For an official plugin, use a public kdlbs/kandev-plugin-<slug> repository. For a community plugin, use the author's public repository. Do not add a production plugin implementation to kdlbs/kandev; the in-tree plugin fixture is test support, not a starter location.
5. Keep host API, SDK, registry runtime, and plugin-loader changes in the Kandev repository. If the plugin needs a missing host capability, treat that as a separate Kandev change with its own tests and compatibility review.

Resolve The Owning Repository

Resolve the plugin repository before editing, especially for bug reports:

1. Start with repository information in the request, issue, pull request, or current task. Otherwise match the manifest id and repo_url against the official catalog entry or the installed plugin metadata. Do not infer that a similarly named fixture or host package in kdlbs/kandev owns the bug.
2. Check the repositories already materialized for the current task and locate the worktree whose manifest id matches the target plugin.
3. When running as a Kandev task and the repository is not attached, discover and call add_branch_to_task_kandev with exactly one of repository_url, repository_id, or local_path. It defaults to the current task and can find or add a repository to the workspace, then materialize its branch as a separate worktree.
4. add_branch_to_task_kandev only works with the Worktree executor. For other executors, or when the task tool is unavailable, ask to attach the repository or create a related task that explicitly targets it. Do not clone a nested repository inside the Kandev monorepo worktree.
5. Change the working directory to the plugin worktree and read its local agent instructions, manifest, build files, tests, and release workflow. For a bug, reproduce and fix the behavior there with /fix and /tdd, then retain this skill's artifact verification. If the fix also needs a Kandev host or SDK change, keep the two repository deliverables and verification steps explicit.

Understand The Runtime Model

Treat a plugin as two independently loaded surfaces joined by the manifest:

package tarball -> validate + extract -> supervised plugin executable <-> Host gRPC
                              |-------> static UI bundle -> browser plugin registry
Kandev event bus -> bounded per-plugin delivery queue -> OnEvent
external or UI request -> declared webhook route -> HandleWebhook

• Kandev owns the executable lifecycle. It starts the declared host-platform binary with the install directory as its working directory, injects a fresh Host connection on every start, and supervises crashes and failed health checks. Do not launch a second long-running server from the plugin.
• KANDEV_PLUGIN_DATA_DIR is the plugin-owned durable file directory. It survives restarts and version upgrades and is deleted on uninstall. Host state is the better fit for small JSON objects that should participate in Kandev backups.
• Install attempts to activate the plugin immediately. Disable preserves its config, state, secrets, versions, and data; uninstall removes them. A config update restarts an active plugin, so load configuration during startup.
• The UI bundle is served from the extracted package and does not pass through the plugin process. Its initialize and optional destroy hooks may run repeatedly as a plugin is disabled and re-enabled in the same browser tab.
• Capabilities gate Host API methods; they are not an operating-system or browser sandbox. The plugin executable inherits Kandev's process environment, and the UI runs as same-origin JavaScript with host store access. Treat installation as privileged code execution and hold official plugins to dependency, credential, and data-access review.

Choose the narrowest surface that satisfies the behavior:

Read The Current Contracts

Read these sources before designing the plugin:

1. docs/public/plugins-authoring.md for the supported backend, Host API, native UI, recipes, packaging, install, and iteration workflow.
2. docs/public/plugins-manifest.md for the authoritative manifest fields, capability gates, and event vocabulary.
3. docs/public/plugins-marketplace.md when publishing or updating a catalog entry.
4. The current kdlbs/kandev-plugin-template repository, including its README.md, Makefile, tests, and release workflow.

Marketplace attribution: The manifest author is independent from GitHub repository ownership or organization. Never infer author kandev from a kdlbs/kandev-plugin-* repository. Read and preserve the manifest author, verify repo_url separately, and require an explicit contributor identity when an externally maintained plugin is released.

Prefer the public authoring docs and current template over old examples. The frontend contract pair is docs/plans/plugins/PLUGIN-API.md plus apps/web/lib/plugins/types.ts; concrete UI exports are in apps/web/lib/plugins/host-api.ts. The backend contract is apps/backend/pkg/pluginsdk plus apps/backend/proto/kandev/plugin/v1/plugin.proto. Read docs/plans/plugins/GRPC-CONTRACT.md when changing the wire contract or when the public docs do not answer a low-level compatibility question.

The frontend and backend matrices in docs/public/plugins-authoring.md, together with apps/web/lib/plugins/types.ts and apps/backend/pkg/pluginsdk, are the authoritative record of what exists today. Read them rather than asserting from memory that a hook is missing, and do not publish a signature they do not declare.

When debugging a contract discrepancy, verify it at the implementation boundary: manifest and package rules live under apps/backend/internal/plugins/manifest and pkgtar; runtime, Host, webhook, and delivery behavior live under apps/backend/internal/plugins; native UI loading and registration live under apps/web/lib/plugins.

When Adding Or Changing A Hook

Treat a new hook, Host method, capability, manifest field, or mounted UI slot as a contract change. Do not implement the runtime surface and leave author docs for later. In the same change:

1. Update the implementation boundary and its focused tests.
2. Update the authoritative contract source:
   • frontend: docs/plans/plugins/PLUGIN-API.md plus apps/web/lib/plugins/types.ts; update host-api.ts, registry.ts, or the mounted component when the concrete surface changes;
   • backend: apps/backend/pkg/pluginsdk, apps/backend/proto/kandev/plugin/v1/plugin.proto, and the manifest model or validator when applicable; update docs/plans/plugins/GRPC-CONTRACT.md for wire-level changes.
3. Update docs/public/plugins-authoring.md in the same change: add the hook to the frontend or backend matrix, document inputs/props, capability and lifecycle/cleanup behavior, and add a copy-pasteable recipe or maintained fixture link. Adding the row to the matrix is the update — do not introduce a separate "unavailable" list anywhere.
4. Update docs/public/plugins-manifest.md for capability/manifest changes and update docs/public/plugins.md, docs/plugins-example.md, or the relevant ADR when their claims or links change. Keep the public guide as a summary; never create a second schema or type definition in prose. When a public plugin page benefits from an architecture, lifecycle, data-flow, or trust-boundary visual, use /diagram-design and its references/kandev-public-docs.md integration guide. Publish a reviewed local image with precise alt text and nearby explanatory prose.
5. Recheck the root/backend/web AGENTS.md authority pointers and this skill if the source-of-truth locations or author workflow changed.
6. Run the focused implementation tests plus node --test scripts/validate-public-docs.test.mjs, node scripts/validate-public-docs.mjs, and a stale-reference search. Report the exact commands and results.

A hook absent from the relevant frontend/backend matrix and its corresponding authoritative contract source does not exist yet; point the author at the nearest supported recipe instead of publishing a speculative signature, and do not record the gap as a durable list entry in this skill or an AGENTS.md — the matrix and the contract sources are the only place absence or presence is tracked. If the hook is implemented but the matrix, recipe, fixture, or authoritative contract is missing, the plugin change is not documentation complete.