Create Kandev Plugin

---
name: create-kandev-plugin
description: Create, modify, debug, test, package, or publish a Kandev runtime plugin in its dedicated repository. Use only when the requested work targets a Kandev plugin implementation or its release and marketplace lifecycle, including fixing a bug in an existing plugin. Do not use for agent skills, MCP servers, general integrations, or Kandev host, SDK, loader, and registry changes that do not also change a 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](../../../docs/public/plugins-authoring.md).
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:

```text
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:

| Need | Surface | Contract to design for |
| --- | --- | --- |
| React to Kandev activity | `OnEvent` | Retryable best-effort delivery, bounded in-memory queues, and possible loss require idempotency and reconciliation for critical workflows. |
| Receive an external call or relay a UI request | `HandleWebhook` | Only declared keys are routed; validate method, authentication, and provider signatures inside the plugin. |
| Store small structured data | Host state | Values are JSON objects keyed by scope and key; there is no transaction or compare-and-swap API. |
| Store files or use a plugin-managed database | `KANDEV_PLUGIN_DATA_DIR` | The plugin owns schema, locking, migrations, and recovery. |
| Read Kandev entities | Typed Host readers plus `api_read` | Use opaque pagination cursors and stable SDK DTOs; never query Kandev's database or internal HTTP API. |
| Mutate Kandev entities | Typed Host writers | `api_write:tasks` gates `Tasks().Create/Update`; `api_write:messages` gates `Messages().Send`. A missing mutation requires a separate Host API change. |
| Notify another plugin | `Host.EmitEvent` | Events are published as `plugin.<id>.<name>`; keep names and payloads versionable. |
| Add native interface | UI registry and `host.ui` | Use host-owned React and components so themes, contexts, portals, and mobile behavior remain compatible. |

## 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.

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.
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.

## Create A New Repository

Skip this section for changes to an existing plugin after resolving its owning
repository above.

1. Derive a lowercase plugin id and repository name. For an official plugin,
   use the full `kandev-plugin-<slug>` value for both. Keep the manifest `id`,
   Go module, Makefile binary and package names, UI registration id, release
   asset name, and catalog id synchronized as the template documents.
2. Create the repository from `kdlbs/kandev-plugin-template`; do not hand-roll
   files that the template already maintains.
3. For official plugins, create or target `kdlbs/kandev-plugin-<slug>` and set
   `repo_url` to that public repository. Do not publish to the organization or
   mutate repository settings unless the user requested that external action.
4. Inspect repository-local instructions before editing. Replace template
   identity and example behavior without deleting its packaging, test, or
   release safeguards.
5. Materialize the plugin as a sibling of the Kandev checkout, or update the
   template's `go.mod` replacement deliberately. Until the SDK is a standalone
   module, the default `replace` resolves `../kandev/apps/backend`.

If the requested repository does not exist and cannot be created with the
available GitHub tooling, stop after producing a precise repository bootstrap
request. Do not silently substitute a directory in the Kandev monorepo.

## Implement With Least Privilege

1. Write concrete behavior examples and failure cases before implementation.
   Use `/tdd` for backend and manifest logic.
2. Declare only the capabilities the plugin exercises. Treat `api_read`,
   `state`, `secrets`, event subscriptions, and webhooks as permission
   boundaries rather than descriptive metadata.
3. Embed `pluginsdk.UnimplementedPlugin`, override only required methods, and
   access Kandev through the injected Host API. The Host can be unavailable
   during construction and isolated tests, so resolve it when handling work.
   Honor context cancellation and do not reach into Kandev internal packages,
   its database, or undocumented REST endpoints.
4. Make event handling idempotent by `EventID`. Kandev makes one attempt plus
   three retries after 5s, 15s, and 45s, using the same event id. Delivery is
   sequential per plugin, but its queue and error-state buffer are bounded and
   in memory; backend restarts and sustained overload can lose events. Add a
   source-of-truth reconciliation path when missing an event is unacceptable.
5. Keep operator credentials in `config_schema` secret fields or the Host
   secret APIs. `GetConfig` returns the plugin's own secret values in cleartext,
   so never commit real credentials or log complete config objects.
6. For a UI bundle, use `host.jsx`, `host.ui`, `host.store`, and
   `host.api.fetch` as documented. Do not bundle another React or Radix runtime.
   Make `initialize` repeatable and use `destroy` to remove timers,
   subscriptions, and side effects; Kandev revokes registered routes, slots,
   handlers, styles, and navigation separately. Use `/mobile-parity` for
   interaction design and `/e2e` for user-visible flows.
7. API v2 webhook routes require a real Kandev caller identity by default. API
   v1 keeps omitted access public for compatibility, so new plugins must use
   API v2. Follow
   `docs/public/plugins-authoring.md` for the current body-size and route
   limits. Kandev rejects undeclared keys and, unless the manifest declares
   `webhooks[].public: true`, rejects anonymous callers with 401 before your
   handler runs. Only mark a webhook `public` when it is genuinely third-party
   ingress (a provider callback, an SSO initiate/callback pair) that your own
   handler authenticates — Kandev does not enforce the manifest's informational
   `method` field or verify that a public webhook's own auth is correct.
   Validate method and signature before side effects, return status codes from
   100 through 599, and avoid reflecting unsafe headers or bodies.
8. Keep package paths and platform declarations synchronized. Build every
   executable declared in `runtime.executables`; include `.exe` for Windows.

## Verify The Artifact

Run the plugin repository's own formatting, tests, and lint commands first,
then verify the artifact rather than only the source tree:

1. Run the plugin repository's tests, vet/lint, and build. Build a host-only
   package with the template's `make package-host` target for the local loop.
2. Confirm the archive contains `manifest.yaml`, the current host executable,
   optional UI assets, and the generated internal `checksums.txt`. Never author
   the internal checksum file by hand.
3. Install the archive into a disposable dev Kandev instance, enable it, and
   exercise every declared capability. Cover config validation, permission
   failures, lifecycle restart, events or webhooks, and native UI registration
   as applicable.
4. Exercise the failure guarantees that matter to this plugin: duplicate event
   delivery, handler cancellation, missing or invalid webhook authentication,
   unavailable dependencies, denied Host calls, and corrupt state. For native
   UI, run initialize/destroy twice and verify one plugin's initialization
   failure does not break the host or another plugin.
5. Verify an upgrade preserves Host state and the data directory when the
   plugin owns either. Verify disable preserves operator data and uninstall
   removes it when lifecycle behavior is part of the change.
6. Bump the manifest version or uninstall the existing version before
   reinstalling; Kandev rejects reinstalling the same id and version.
7. Before release, run the repository's full cross-platform package workflow
   and confirm its release asset name is `<id>-<version>.tar.gz`.

There is no standalone exhaustive package checker in this branch. `plugin-pack`
stages files and generates checksums; install-time `pkgtar.Install` validates the
manifest, archive safety, checksums, managed runtime, and host executable. These
checks do not execute plugin code or prove browser/module behavior, so the
disposable-instance smoke test remains required.

Do not test with a developer's primary instance, database, or credentials.
Report commands run, artifact name, host platform tested, and any platform or
integration path not exercised.

## Publish When Requested

1. Keep source public before submitting an official marketplace entry.
2. Tag the version through the repository's release workflow. Confirm the
   GitHub Release contains the required plugin tarball; the release-level
   tarball digest file is optional under the current marketplace contract.
3. For the official catalog, add the repository pointer to
   `plugin-registry/plugins.yaml` in `kdlbs/kandev` only after a valid latest
   release exists. Keep catalog `id` equal to manifest `id`; leave `featured`
   to maintainers.
4. Verify the registry build resolves the latest release and package asset.
   Catalog categories are free-form discovery tags and are distinct from the
   manifest category enum.
5. For an official plugin, review dependencies, release provenance, requested
   capabilities, filesystem and network use, secret handling, and UI store
   access. Internal package checksums detect corruption but do not prove
   provenance; release-level digests are advisory and signature verification is
   not wired by default in the shipped product.

Publishing, tagging, creating organization repositories, and marketplace
submission are external side effects. Perform only the actions the user asked
for, while completing local implementation and verification independently.