Plugin Development

---
name: plugin-development
description: Builds, extends, tests, debugs, packages, and maintains portable EvoFlux Agent Plugins end to end, including plugin.json, immediate-child Agent Skills, portable MCP servers (mcp.json), credentials, installation-scoped data, Plugin Center and evoflux plugin CLI lifecycle, and runtime verification. Use when the user asks to author or repair an unpacked plugin or .evoplugin package, or to change the generic EvoFlux Plugin Platform. Not for merely installing a finished package, raw single-file hook URLs, standalone skills, or global MCP configuration.
disable-model-invocation: true
---

# EvoFlux Plugin Development

Build portable Agent Plugins as isolated packages, then prove the package through the same lifecycle an EvoFlux user exercises. Keep the package contract portable and isolate EvoFlux-specific behavior in declared extensions.

## Choose the workflow

Select the smallest path that covers the requested outcome:

- **Package authoring:** create or change the manifest, Skills, MCP servers,
  credentials, data use, tests, or archive.
- **Package debugging:** locate the first invalid or stale package/runtime
  boundary and add a regression test there.
- **Platform development:** change generic validation, lifecycle, runtime, API,
  CLI, or Plugin Center behavior without adding a domain-specific bundle.

First confirm that “plugin” means a managed Plugin Center package. EvoFlux also
has trusted in-process hooks: those are single `.py` files discovered from the
`plugins/` subdirectory of the EvoFlux configuration directory (or the
directories listed in `EVOFLUX_PLUGINS_DIRS`) and must export `async def plugin()` or
`class Plugin(BaseAgentHook)`. They are a different trust/runtime contract and
must never be scaffolded as an Agent Plugin directory. Provider plugins are
also loaded from that trusted file root by their own registry.

Hand adjacent operations to their owning workflow:

- Installing a trusted single-file hook from a raw Python URL: read the `plugin-installer` skill.
- A standalone skill that is not packaged in a plugin: read the `skill-creator` skill.
- Global user/project MCP configuration outside a plugin: read the `mcp-installer` skill.
- For a finished package that only needs installation, use Plugin Center or the plugin CLI directly.
- Do not invent commands, agents, a storage SDK, signatures, registry import, or rich connection types; none of those is part of the platform contract.

## Load the right contracts

Read only the references required by the work, but read each selected file completely:

- Read [package-contract.md](references/package-contract.md) before creating or changing package structure, `plugin.json`, Skills, packaging, or installation behavior.
- Read [runtime-and-credentials.md](references/runtime-and-credentials.md) before implementing or debugging MCP, credentials, environment variables, data, tool grants, or runtime readiness.
- Read [test-and-debug.md](references/test-and-debug.md) before testing, debugging, packing, updating, or declaring completion.
- Read [evoflux-source-map.md](references/evoflux-source-map.md) when changing the Plugin Platform inside the EvoFlux repository or when exact CLI, API, or host UI ownership matters.

Treat current source and `/api/plugins` OpenAPI as authoritative if a reference and the implementation differ. Update the reference in the same change when the contract changed intentionally.

## Establish the target

1. Read repository instructions and inspect the existing package before editing.
2. Decide whether the plugin is Skills-only, MCP-only, or hybrid.
3. Define the user outcome, each Skill trigger, each MCP tool boundary, credential needs, persistent data, and expected failure behavior.
4. Confirm whether the work targets a developer link, a managed installation, or both.
5. Preserve unrelated changes in a dirty worktree.

Keep third-party runtime code inside the plugin process. Never import plugin code into the FastAPI or React hosts.

## Scaffold the smallest valid package

Start from the official scaffold when practical:

```bash
evoflux plugin create ./my-plugin --name my-plugin --skill my-workflow
```

Use Plugin Center's Create flow when the author/license/Skill form is useful. A blank Starter Skill field defaults to the plugin name, so the UI scaffold contributes a discoverable workflow immediately. The CLI scaffold takes a destination, a required name, an optional description, and an optional Skill; set version, author, and license in `plugin.json` afterwards or use Plugin Center. EvoFlux intentionally does not generate an MCP implementation because it cannot guarantee a portable executable or install plugin dependencies.

Derive the tree from the components the package actually contributes. The
smallest useful Skills package is:

```text
my-plugin/
├── plugin.json
└── skills/
    └── my-workflow/
        ├── SKILL.md
        ├── references/        # optional Skill resources
        ├── scripts/           # optional Skill resources
        └── assets/            # optional Skill resources
```

Add root `mcp.json` only when the package has a genuinely runnable portable MCP
server. Its implementation path is chosen by that server's declared command;
there is no required root `server.py`, `backend/`, or package-local `tests/`
directory. EvoFlux repository regression tests belong under the owning `tests/`
tree. Keep each Skill as an immediate child of `skills/`. A manifest-only plugin
is valid; do not add empty capabilities merely to fill the tree.

## Implement from the outside in

### 1. Manifest

Declare the canonical schema, portable name, semantic version, and useful description. Put EvoFlux-specific declarations under `extensions`; unknown root fields are ignored with warnings and are not extension points.

Avoid encoding installation identity or absolute machine paths. Installation IDs are generated by EvoFlux and remain stable across managed updates.

### 2. Skills

Each plugin Skill follows the Agent Skills contract: `SKILL.md` plus optional `references/`, `scripts/`, and `assets/`; frontmatter with `name` (matching the directory) and a third-person `description` saying what the Skill does and when to use it, plus only the optional keys `license`, `compatibility`, `metadata`, `allowed-tools`, `disable-model-invocation`, and `user-invocable`. Make the body an imperative, executable workflow. For frontmatter rules, body structure, and evaluation scenarios, read the `skill-creator` skill.

When a Skill calls plugin MCP tools:

- describe the stable server/tool suffix, not the generated installation prefix;
- tell the agent to select the available namespaced tool ending in that suffix;
- load only references needed for the current request;
- never ask users to paste secrets into chat.

### 3. MCP servers

Declare servers in `mcp.json`. Prefer `stdio` for bundled local code and `streamable-http` for a remote MCP endpoint. Legacy `sse` may validate but is skipped by EvoFlux.

For local servers, use an executable plus argument array—never a shell command string. Resolve bundled files through `${PLUGIN_ROOT}` and mutable state through `${PLUGIN_DATA}`. These are plugin runtime environment variables, not skill placeholders: EvoFlux substitutes `${PLUGIN_ROOT}` (the installed or linked package root) and `${PLUGIN_DATA}` (the installation's mutable data root) in stdio `args`, `env` values, and `cwd` of `mcp.json`, and sets `PLUGIN_ROOT` and `PLUGIN_DATA` in the server process environment. Return bounded, structured results and sanitize operational errors.

There is no automatic MCP starter and no host-Python alias. Prefer a
package-owned executable such as `./bin/my-server`, or a remote
`streamable-http` endpoint. If a bare interpreter command is unavoidable,
document and verify it plus every imported dependency on each target platform;
static package validation cannot prove runtime readiness.

Give tools accurate read/write/destructive/idempotent annotations where the MCP library supports them. Keep transport boot logs off stdout for stdio servers.

### 4. Credentials and data

Declare every configurable secret or value under
`extensions["org.evoelsewhere.evoflux.credentials"].fields`. Use unique field keys and
environment names. Do not reserve `PATH`, `PLUGIN_ROOT`, or `PLUGIN_DATA`.

Credential values are injected only into plugin stdio processes. Do not use
the credential extension as authentication for `streamable-http`; portable
remote headers remain literal package data and must not contain secrets.

Treat `${PLUGIN_DATA}` as installation-scoped mutable state. Do not write generated state into the installed package. Persist files with restrictive permissions when they contain secrets, and mask secrets in all list/read responses.

Use `extensions["org.evoelsewhere.evoflux.mcp"].servers.<name>.capabilities` only for
supported declared capabilities (`webbridge-safe` is accepted but has no effect now); never infer trust from package
installation alone.

Existing packages using `evoflux.credentials` or `evoflux.mcp` remain readable
as compatibility aliases, but all newly authored or updated packages must use
the canonical reverse-domain namespaces above.

## Validate in short loops

Run structural inspection after every contract-level change:

```bash
evoflux plugin inspect ./my-plugin
```

Treat fatal manifest/MCP errors differently from isolated component errors. A bad Skill should not invalidate unrelated Skills; a bad MCP server should not take down healthy sibling servers.

Run focused component tests before broad suites. Cover input validation, timeouts, pagination or result bounds, error sanitization, secret masking, file permissions, and failure isolation as relevant.

For developer feedback, link the source package and observe runtime state:

```bash
evoflux plugin link ./my-plugin
evoflux plugin list
evoflux plugin show <installation-id>
```

Linked edits should hot reload. The runtime keeps the last-known-good server across transient invalid writes, so inspect both validation state and live runtime state when debugging.

## Prove the end-to-end lifecycle

Do not stop at unit tests for a new or materially changed plugin. Exercise the applicable path:

1. Inspect the unpacked source.
2. Pack twice to separate outputs and compare bytes when deterministic
   packaging changed; always write outputs outside the plugin root.
3. Install the packed artifact as a managed installation and inspect the
   returned installed root. `evoflux plugin inspect` accepts unpacked
   directories, not archive files.
4. Configure credentials through Plugin Center or the credentials API when declared.
5. Wait for each expected MCP server to become ready.
6. Invoke at least one representative tool through the actual MCP runtime.
7. Verify secret values never appear in status, logs, tool errors, or serialized results.
8. For a linked MCP plugin, edit implementation code without touching
   `mcp.json`; verify the runner restarts and the changed behavior is visible.
9. Verify disable removes Skills and stops runtime servers; verify enable restores them.
10. For update work, verify installation ID, data, and enabled state are
    preserved for both version changes and same-version replacement; verify a
    rejected update leaves the current installation runnable.
11. Uninstall the test installation and decide explicitly whether test data should be preserved or removed.

Perform lifecycle mutations only against isolated EvoFlux data, config, and
cache roots created for the test. Use a local deterministic fixture server for
external APIs whenever possible. Do not make a release test depend on live
credentials, an uncontrolled remote service, or the user's real installations.

## Debug by ownership layer

Locate the first failing boundary before editing:

1. **Package discovery:** wrong root, missing `plugin.json`, duplicate install source, archive safety rejection.
2. **Manifest:** schema/name/version/root-field error or invalid EvoFlux extension.
3. **Skill discovery:** nested Skill, name mismatch, bad frontmatter, oversized file, or local validation error.
4. **MCP declaration:** invalid top level, unsupported server type, unsafe URL/cwd/path, or `${PLUGIN_ROOT}`/`${PLUGIN_DATA}` in an unsupported position.
5. **Process startup:** missing executable/dependency, stdout noise, wrong argument, environment, cwd, or permissions.
6. **Credentials/data:** undeclared env, missing required field, stale runtime refresh, unsafe file mode, or incorrect `${PLUGIN_DATA}` usage.
7. **Tool behavior:** API contract, auth, timeout, pagination, annotations, response size, or unsanitized exception.
8. **Lifecycle/host UI:** stale validation/runtime snapshot, enable state,
   update identity, cache invalidation, or managed-versus-linked behavior.

Capture the smallest reproducer and add a regression test at the owning layer. Do not hide a platform defect by weakening package validation or bypassing the permission pipeline.

## Complete with evidence

Before reporting completion:

- ensure validation has no unexpected errors or warnings;
- run the focused plugin tests and relevant EvoFlux platform tests;
- verify the packed artifact, not only source files;
- report the capabilities added, lifecycle path exercised, tests run, and any untested external dependency;
- distinguish supported behavior from future/deferred ideas.