Plugin Development

Plugins package capability extensions for installation into SOIT workspaces. A plugin can export tools, MCP servers, skills, workflow nodes, or a mixed set of artifacts.

Package shape

A plugin is a zip archive:

manifest.json          # package metadata + enabled flag
spec.json              # capability contract, validated against plugin_spec.schema.json
files/
  skills/<skill_name>.json
  mcp/<server_name>.json
  tools/<tool_name>.json
  nodes/<node_name>.json

Declaring exports

spec.json declares what the plugin contributes:

• spec.plugin_type — skill, mcp, tool, workflow_node, or mixed.
• spec.exports.tools — a list of tool refs like tool:http:ticket_create; for each ref, SOIT loads the tool spec from files/tools/<tool_name>.json (the last ref segment).
• spec.exports.workflow_nodes — node refs like node:tool:health_check, loaded from files/nodes/<node_name>.json.
• spec.exports.skills and spec.exports.mcp_servers — plugin-owned skill and MCP artifacts.
• spec.artifacts — optional explicit mapping of exported refs to package JSON paths.

Development workflow

1. Author spec.json and validate it against kernel/specs/v1/plugin_spec.schema.json — installation rejects invalid specs.
2. Add exported artifact files under files/.
3. Zip and upload through the web /plugin workbench or POST /api/v1/plugins/package?mode=auto.
4. Iterate: bumping spec.version and re-uploading upgrades the installation; the same version re-upload requires explicit mode=reinstall.
5. Verify runtime registration: GET /api/v1/plugins/runtime/tools shows what the tool router can dispatch, and POST /api/v1/plugins/runtime/reload re-syncs after manual changes.

Rules

• Exported tools and workflow nodes use stable refs — consumers bind the ref, not the file.
• Installation, upgrade, enablement, disablement, and uninstall flow through plugin lifecycle APIs; artifacts on disk under var/plugins/ are managed by the platform.
• Projectors call module application services — plugin lifecycle code never writes skill, MCP, tool, or workflow business details directly.
• Plugin tool calls execute through the governed tool router, so timeouts, audit, egress policy, and cost tracking apply automatically.

Related pages

• Plugins — the lifecycle and API surface.
• MCP and Skills — the plugin-owned artifact model.
• Specs and Schemas — refs and validation rules.