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

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. Treat webhook routes as public ingress. Follow docs/public/plugins-authoring.md for the current body-size and route limits. Kandev rejects undeclared keys, but it does not authenticate callers or enforce the manifest's informational method field. Validate both 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.