Plugin Development Guide

MRP-VM is a typed plugin kernel. The VM does not own retrieval, indexing, decomposition policy, solver heuristics, or answer format logic. Those live inside plugins.

This guide shows how to build each plugin family, where the files usually live, which metadata is required, and which configuration surfaces matter for the default system.

Typical Built-In Layout

src/
  core/
    boot/                    # core boot sequence
    conversation/            # session lifecycle
    engine/                  # request/frame execution kernel
    ingest/                  # source ingest orchestration
    kb/                      # repositories, persistence, workspaces
  mrp-vm-sdk/
    knowledge/               # KU/pragmatics helpers shared by plugins
    retrieval/               # shared retrieval helpers/backends
    strategies/              # shared NL/CNL strategy implementations
    synthesis/               # shared answer composition helpers
  plugins/
    runtime/                 # plugin loader, registry, wrapper runtime
    sd-plugin/sd-symbolic/
    sd-plugin/sd-llm-fast/
    kb-plugin/kb-fast/
    kb-plugin/kb-balanced/
    gs-plugin/gs-symbolic/
    mrp-plan-plugin/planner-default/
config/
  plugins.json               # built-in plugin catalog + fallback orders
  conversation.json          # session defaults
  prompts/*.md               # LLM prompt templates

The usual workflow for a new built-in plugin is:

Create src/plugins/<type>/<plugin-id>/ with index.mjs, plugin.json, and plugin.kus.md.
Keep plugin-specific code inside that package; move any helper reused across multiple plugin families into src/mrp-vm-sdk/.
Expose a valid descriptor with the correct type, id, plannerHints, maxLLMCalls, and modelRoles.
Add the plugin module to config/plugins.json if it should be part of the shipped built-in catalog.
Add direct tests for the plugin package plus any needed deterministic integration coverage.

Plugin Family Tutorial

`sd-plugin`

Extracts Intent CNL plus current-turn KUs in one pass. It should also classify KU phase relevance through PhaseScopes when possible.

`kb-plugin`

Owns retrieval, indexing, backend fusion, and sufficiency checks. Any lexical, associative, or symbolic backend belongs here, not in the VM.

`gs-plugin`

Consumes resolved intents and goal-solver guidance KUs to produce the final answer document and Markdown output.

`mrp-plan-plugin`

Chooses KB and solver order, decides decomposition, and reacts to planner / decomposition / validation guidance.

`val-plugin`

Runs after a successful answer. It may use validation guidance KUs to enforce domain-specific output or evidence rules.

Required Descriptor Fields

Field	Required	Notes
`id`	Yes	Stable unique plugin identifier.
`type`	Yes	One of `sd-plugin`, `kb-plugin`, `gs-plugin`, `mrp-plan-plugin`, `val-plugin`.
`description`	Yes	Planner-readable description of when the plugin is useful.
`maxLLMCalls`	Yes	Conservative request-budget reservation.
`modelRoles`	If LLM-backed	Roles from DS028.
`plannerHints`	For planner-facing stages	Cost, latency, supported acts, topic tags, evidence style.
`provides`	Yes	Operational capability tags used by docs and diagnostics.

Per-Type Checklist

`sd-plugin`

Implement detectSeeds(input, ctx).
If it participates in ingest, implement normalizePersistentContext(...) or expose an ingest strategy wrapper.
Emit both intentCNL and currentTurnContextCNL.
Use PhaseScopes for output instructions, planning hints, decomposition hints, and validation rules when detectable.

`kb-plugin`

Implement retrieve(input, ctx).
Optionally implement onSourceText(...) and onSessionEvent(...) for plugin-private artifacts.
Return resolvedIntents with evidence plus guidanceUnits buckets.
Keep indexing and scoring private to the plugin or its documented backends.

`gs-plugin`

Implement solve(input, ctx).
Consume guidanceUnits from retrieval, especially answer-shaping instructions.
Return responseMarkdown and responseDocument.
Use status: "needs-decomposition" only when a child frame is genuinely required.

`mrp-plan-plugin`

Implement buildPlan(input, ctx) and optionally recordOutcome(...).
Read the phase-specific guidance arrays instead of assuming one undifferentiated strategy blob.
Remember that request budgets are global across child frames.

`val-plugin`

Implement validate(input, ctx).
Reject only when the answer truly violates the contract; rejection triggers planner backtracking.
Use validation guidance KUs if the domain defines output rules or proof obligations.

Configuration Surfaces

File	What it controls
`config/plugins.json`	Built-in plugin catalog, default planner, and shipped fallback order.
`config/conversation.json`	Session defaults; use `null` for auto-routing rather than silently pinning a plugin.
`config/kb.json`	Shared ingest chunking and repository/workspace settings, not plugin-private index policy.
`config/prompts/*.md`	Prompt templates used by LLM-backed strategies.

External Wrapper Plugins

If a plugin should run out of process, use the wrapper convention from DS016. Wrapper metadata lives in a wrapper directory and describes how the typed plugin is spawned, but the typed plugin contract itself still comes from DS027.

Testing

Add deterministic tests for planner ordering, retrieval sufficiency, guidance routing, and budget behavior.
For chat-visible plugins, verify both buffered and streamed chat responses.
When the plugin touches ingest, add a regression for medium-size sources near the normalizer ceiling.