Create a new npm package that implements a kanban-lite storage plugin. Use this whenever the user asks to build a new kanban-lite provider, external storage plugin, `card.storage` plugin, `attachment.storage` plugin, or a package that can be selected in `.kanban.json`. If the backend or package details are incomplete, ask a small batch of targeted questions first, then scaffold the package and wiring.
Use this skill to create a new installable npm package that kanban-lite can load as an external storage provider.
The goal is not just to explain the plugin system. The goal is to leave the user with a real package scaffold that:
.kanban.json.Create a package directory with, at minimum:
package.jsontsconfig.jsonsrc/index.tsREADME.mdThe package should normally export one or both of:
cardStoragePluginattachmentStoragePluginEvery package must also export a pluginManifest constant. The engine uses
this manifest for fast, reliable capability discovery:
export const pluginManifest = {
id: 'kl-plugin-storage-example',
capabilities: {
'card.storage': ['example'] as const,
'attachment.storage': ['example'] as const,
},
} as const
The manifest declares the package id, the capability namespaces it provides, and
the provider ids for each capability. Optionally add an integrations array
when the package also contributes standalone.http, cli, mcp.tools,
sdk.extension, or event.listener surfaces.
If the attachment provider supports efficient append-heavy workloads (for example card logs), it may also implement the optional hook:
appendAttachment(card, attachment, content)Before writing files:
https://github.com/borgius/kanban-lite/blob/main/docs/plugins.mdhttps://github.com/borgius/kanban-lite/blob/main/README.md (Storage Providers / plugin sections)If the request is underspecified, ask a single small batch of targeted questions. Keep it to the minimum needed to generate a real package.
Ask about:
card.storageattachment.storagelocalfsIf the user already answered some of these, do not ask again.
If the user says “just scaffold it” and leaves details vague, default to:
card.storagedist/index.cjsnull)localfs unless the user explicitly wants attachment support in the same packageTell the user when you chose defaults.
Make sure the package will export the exact runtime surface kanban-lite expects.
For a card storage plugin, the important shape is:
pluginManifest — package-level manifest with capabilities and optional integrationsmanifest.idmanifest.provides including card.storagecreateEngine(kanbanDir, options)nodeCapabilitiesFor an attachment plugin, the important shape is:
pluginManifest — package-level manifest with capabilities and optional integrationsmanifest.idmanifest.provides including attachment.storagecopyAttachment(...)appendAttachment(...) when the backend can efficiently append in-placegetCardDir(...) or materializeAttachment(...)Use references/provider-contracts.md for the compact contract summary.
Do not stop after generating types or empty files. Create a compileable package scaffold.
That means:
package.jsonappendAttachment(...)Use the bundled templates as a starting point when they fit:
templates/package.json.template.jsontemplates/tsconfig.json.template.jsontemplates/src/index.template.tstemplates/README.template.mdkanban-lite currently validates external plugins by runtime shape. The plugin-author API is not yet a polished stable package surface.
That means the safest default is:
kanban-lite/sdk when they are actually exported and useful,The runtime loads external plugins with createRequire(...), so the safest output is a require-compatible package.
Prefer one of these:
require exportAvoid pure ESM-only output unless the user explicitly wants to take on that compatibility risk.
If the provider depends on a heavy or optional runtime driver — for example a database driver — load it lazily and surface an actionable install error.
Good pattern:
Install it with: npm install <driver>If the provider is not file-backed, say so in nodeCapabilities.
Typical non-file-backed behavior:
isFileBacked: falsegetLocalCardPath(): nullgetWatchGlob(): nullIf it is file-backed, return real values and document them.
.kanban.json usageThe README you generate for the new package should always include:
.kanban.jsonlocalfsappendAttachment(...) are supported, and when the runtime falls back to normal rewrite behaviorIf you are changing the core kanban-lite repo while adding or evolving plugin behavior, update the related first-party docs in the same task — especially docs/plugins.md, README.md, and CHANGELOG.md.
Whenever possible:
At the end, provide a concise summary covering: