fusion/docs/plugin-management.md

Plugin Management Guide

← Docs index

This guide is the canonical end-user workflow for managing Fusion plugins across the full lifecycle: discover, install, enable/disable, configure, use, update, uninstall, and troubleshoot.

Plugin author/developer details (manifest, SDK APIs, hooks, routes, and runtime implementation) live in Plugin Authoring.

1) Plugin basics

Fusion uses two plugin surfaces in Settings:

• Fusion Plugins (Settings → Plugins → Fusion Plugins): extend Fusion behavior (tools, routes, UI slots/views, runtimes)
• Pi Extensions (Settings → Plugins → Pi Extensions): manage pi extension packages/sources

These are related but different systems; do not treat Pi Extensions as Fusion Plugins.

Lifecycle states

State	Meaning
installed	Registered but not started yet
started	Loaded and active
stopped	Disabled/stopped
error	Failed to load or failed at runtime

Common locations

Location	Purpose
~/.fusion/plugins/	Default local plugin install location
Bundled plugin manifests (shipped with Fusion)	Discoverable/installable from Plugin Manager
Custom local path (absolute path)	Install plugin from a local directory

2) Discover available plugins

Dashboard

1. Open Settings → Plugins → Fusion Plugins.
2. Review bundled entries in Bundled Plugins and currently installed entries.
3. Check each plugin’s status/state in the manager.

Expected outcome: You can see what is already installed, what is bundled and available, and each plugin’s current lifecycle state.

CLI

1. Run:

   fn plugin list
   

2. Review installed plugin IDs and status.

Expected outcome: You have a terminal view of installed plugins for scripting/remote workflows.

3) Install plugins

Install bundled plugin (dashboard)

1. Go to Settings → Plugins → Fusion Plugins.
2. In Bundled Plugins, click Install for the plugin.

Expected outcome: Plugin is registered and appears with an initial state (typically installed then started when enabled/loaded).

Install from local path (dashboard)

1. Go to Settings → Plugins → Fusion Plugins.
2. Use Install and provide an absolute plugin path.
3. Confirm installation.

Expected outcome: Plugin is added to your local plugin set and appears in the manager.

Install from local path (CLI)

1. Run:

   fn plugin install <path>
   

2. Confirm the plugin appears in:

   fn plugin list
   

Expected outcome: Plugin is installed from the specified path and visible in plugin listings.

4) Enable, disable, and reload plugins

Dashboard

1. Open Settings → Plugins → Fusion Plugins.
2. Toggle plugin enable/disable controls.
3. Use reload controls when available.

Expected outcome: Plugin transitions between runtime states (started / stopped) and reflects transitions in the manager.

CLI

fn plugin enable <id>
fn plugin disable <id>

Expected outcome: Plugin is enabled or disabled by ID.

5) Configure plugin settings

1. Go to Settings → Plugins → Fusion Plugins.
2. Open the plugin settings editor (gear/settings action).
3. Update fields and save.

Expected outcome: Plugin-defined settings are persisted and used by that plugin at runtime.

6) Use post-install plugin capabilities

After a plugin is installed/enabled, these are the current user-visible capability surfaces.

A) Plugin-contributed skills (runtime behavior)

Plugin-contributed skills are merged into agent sessions automatically at runtime when enabled.

1. Install + enable the plugin.
2. Run a task through an agent flow (triage/executor/reviewer/merger).
3. Check agent output/logs for skill-driven behavior from that plugin.

Expected outcome: plugin skills affect session behavior, but there is no dedicated "plugin skills" management panel in Fusion Plugins.

Note: Skills view shows discovered execution skills and toggles, but plugin-contributed skills are documented as runtime session behavior here (not a plugin-manager-specific skills UI).

B) Plugin-contributed workflow step templates (dashboard + API)

Plugin templates are visible in the workflow-step chooser.

1. Open Settings → Workflow Steps.
2. Click Add Workflow Step.
3. In the templates chooser, find plugin-contributed templates (grouped/labeled with plugin attribution).
4. Add the template and configure phase/mode as needed.

Expected outcome: plugin templates appear alongside built-in templates and run like any other workflow step.

See also: Workflow Steps and Plugin Authoring §16.

C) Plugin prompt contributions (runtime-only)

Prompt contributions modify agent prompts at runtime on supported surfaces (for example executor/triage/reviewer/heartbeat).

1. Install + enable the plugin.
2. Run the relevant agent flow.
3. Validate behavior via agent output/logs (for example extra instructions being followed).

Expected outcome: prompt modifications apply during agent runs. There is no verified dedicated dashboard UI to inspect/edit plugin prompt contributions directly.

See: Plugin Authoring §17.

D) Optional plugin binary setup (currently CLI-driven)

Some plugins expose optional setup hooks for managed binaries/runtimes.

1. Ensure the plugin is installed and enabled.
2. Check setup status:

   fn plugin setup-status <id>
   

3. Trigger install or uninstall:

   fn plugin setup <id> --action install
   fn plugin setup <id> --action uninstall
   

Expected outcome: setup status and setup actions run via CLI. Current behavior is CLI-driven; do not assume a dedicated dashboard setup control exists.

See: Plugin Authoring §18.

7) Verify plugin is working

After installing/enabling, verify success signals relevant to that plugin:

• Plugin state remains started (not error)
• Plugin tools/routes/UI/runtime contributions appear where that plugin declares them
• Plugin-contributed workflow templates are available in Settings → Workflow Steps
• Plugin-contributed skills and prompt contributions are observable during agent runtime behavior/logs
• Optional setup-capable plugins report expected setup status via CLI

If you need capability-level details for a specific plugin, check its README and Plugin Authoring.

8) Update plugins

Fusion does not use a dedicated fn plugin update command. Update by reinstalling the desired plugin version/source.

Dashboard

1. Reinstall from the bundled entry or updated local path.
2. Re-check state and behavior in the plugin manager.

CLI

1. Re-run install against the updated source path:

   fn plugin install <path>
   

2. Confirm with:

   fn plugin list
   

Expected outcome: Updated plugin build/version is installed and operational.

9) Uninstall plugins

Dashboard

1. Open Settings → Plugins → Fusion Plugins.
2. Uninstall the target plugin.

Expected outcome: Plugin is removed from the installed list and no longer active.

CLI

1. Run:

   fn plugin uninstall <id> --force
   

2. Verify removal:

   fn plugin list
   

Expected outcome: Plugin is removed by ID.

10) Dashboard vs CLI mapping

Workflow	Dashboard path	CLI command
List installed plugins	Settings → Plugins → Fusion Plugins	fn plugin list
Install plugin	Settings → Plugins → Fusion Plugins → Install	fn plugin install <path>
Enable plugin	Settings → Plugins → Fusion Plugins → Enable toggle	fn plugin enable <id>
Disable plugin	Settings → Plugins → Fusion Plugins → Disable toggle	fn plugin disable <id>
Uninstall plugin	Settings → Plugins → Fusion Plugins → Uninstall	fn plugin uninstall <id> --force
Check plugin setup status	CLI-only in current user flow	fn plugin setup-status <id>
Install/uninstall plugin setup binary/runtime	CLI-only in current user flow	`fn plugin setup --action install
Add plugin workflow step template	Settings → Workflow Steps → Add Workflow Step	POST /api/workflow-step-templates/:id/create (API)
Scaffold new plugin (authoring)	n/a (developer workflow)	fn plugin create <name>

11) Troubleshooting

Plugin is in error state

1. Open Settings → Plugins → Fusion Plugins and inspect state/transition feedback.
2. Disable then re-enable the plugin.
3. Confirm plugin source path and dependencies are valid.
4. If needed, uninstall and reinstall the plugin.

Plugin installed but features are not visible

1. Confirm plugin state is started.
2. Verify what that plugin actually contributes (tools/routes/UI/runtime/skills/workflow templates/prompt contributions/setup hooks) in plugin docs.
3. Confirm you are checking the correct surface:
   • Workflow templates: Settings → Workflow Steps
   • Skills/prompt contributions: runtime agent behavior/logs
   • Setup hooks: CLI commands (setup-status, setup)
   • UI routes/slots: dashboard nav/sections/cards according to plugin design

Confusion between Fusion Plugins and Pi Extensions

1. Use Fusion Plugins for Fusion plugin lifecycle management.
2. Use Pi Extensions only for pi extension sources/extensions/skills/prompts/themes.

Plugin has setup requirements but dashboard has no setup control

Use CLI setup commands:

fn plugin setup-status <id>
fn plugin setup <id> --action install
fn plugin setup <id> --action uninstall

Need implementation/API details

Use Plugin Authoring for manifest fields, lifecycle hook signatures, UI/runtime contribution contracts, and SDK examples.

For sections referenced in this guide:

• Skills: §15
• Workflow templates: §16
• Prompt contributions: §17
• Binary setup hooks: §18