Skip to content
Chapter 7 · Decisions 7-44

User plugins: bundled skills, instructions, hooks and MCP servers

Status

Accepted by the owner on 2026-11-06 (user-level only; no plugin slash commands).

Context

The owner wants users to create, share and install plugins: one folder that bundles the extension points Ru already has. Today each lives in its own fixed place:

  • Skills: SkillRoots.For/ForUser (project, user and %LOCALAPPDATA%\Ru\skills roots), GitHub packages under ADR 0036.
  • Instructions: RuInstructionLoader (~/.ru/AGENTS.md, then workspace files).
  • Slash commands: CustomPromptCommands, expanded by the CLI only.
  • Hooks: HookConfiguration.Load over ~/.ru/hooks.json and, once trusted, <workspace>/.ru/hooks.json.
  • MCP servers: McpConfiguration, the user's ~/.ru/mcp.json only (ADR 0025).

Several documents state that plugins are not loaded or discoverable (runtime-behavior.md, harness.md, coding-agent-capabilities.md, CONTEXT.md). Hooks and MCP servers run programs as the user, so a plugin is executable content and needs the boundaries the owner chose: full contents, with consent.

Decision

  1. A plugin is a folder with ru-plugin.json. The manifest is strict (unknown fields rejected): id (^[a-z][a-z0-9-]{0,23}$, so <id>-<server> still fits the MCP name limit), name, description, version. Optional parts are found by fixed names: skills/, AGENTS.md, hooks.json, mcp.json, each with the same format and limits as today. Plugins carry no slash commands: reusable prompts are skills, which the model loads on demand.

  2. User-level only. Plugins live in ~/.ru/plugins/<id> (local and created) and %LOCALAPPDATA%\Ru\plugins\<id> (managed GitHub installs). There are no project plugins: they would reopen workspace-declared MCP servers (ADR 0025) and trust-gated workspace hooks. A plugin is off until the user enables it, and the enabled set is stored on the Host side, never inside the plugin folder.

  3. Each part joins its existing loader at the lowest precedence:

  4. Skills: enabled plugins' skills/ are appended after the user roots in SkillRoots.ForUser. At most 8 enabled plugins may carry skills (the catalog caps roots at 16). A plugin skill shadowed by a user or project skill is reported in Customize, not dropped silently.
  5. Instructions: a new PromptInstructionOrigin.Plugin, source id plugin:<id>, read after ~/.ru/AGENTS.md and before workspace files; within the existing 64/256 KiB limits and block cap.
  6. Hooks: plugin hooks are user-level sources, behaving exactly like ~/.ru/hooks.json at all three HookConfiguration.Load call sites.
  7. MCP: servers merge into McpServerHost as <id>-<server>. A name the user's own file already declares wins; the plugin's server is refused with a diagnostic. Per-call approval (ExternalTerminal) is unchanged.

  8. Consent for executable parts. The executable surface of a plugin is the canonical list of hook events, matchers, commands and timeouts, plus each MCP server's transport, command, args, cwd, url and environment variable names (never values; the digest still covers the values, so changing one asks again). Enabling a plugin with an executable surface shows that list and records its SHA-256 once the user allows it; the approval request carries the digest the user was shown and fails with plugin_changed if the plugin changed meanwhile. A plugin hook receives its folder as RU_PLUGIN_ROOT; a plugin MCP server starts in its plugin folder unless its cwd says otherwise. Every load recomputes the digest; on a mismatch the hooks and MCP servers of that plugin are suspended (fail closed) and Customize shows "changed, approve again". Skills, commands and instructions need only enable, like today's files. Instructions and skills remain guidance and never grant permission.

  9. Protection. Both plugin roots join ProtectedPathCatalog (version bump), so the agent's structured file tools cannot edit installed plugins in plan and standard; full_access stays literally full. The digest is the backstop for anything that changes the files outside those tools; the terminal is not confined, the same boundary as today.

  10. Creating a plugin.

  11. Customize → Plugins → New plugin scaffolds ~/.ru/plugins/<id> from a short form (id, name, description, parts) and opens the folder.
  12. A built-in create-plugin skill lets the user describe a plugin in chat. Because installed roots are protected, the skill writes a draft folder inside the workspace (a non-dot folder); the user imports it with Add plugin from folder, which copies it into ~/.ru/plugins and goes through enable and consent. A plugin the agent wrote is never enabled automatically.

  13. Installing from GitHub. A PluginPackageInstaller reuses ADR 0036's mechanics: tree URLs pinned to a full commit, codeload with redirects disabled, size and file limits, an exclusive lock, staging and rollback, and per-file hashes in a managed manifest. It never runs scripts or installs dependencies. An update that changes the executable-surface digest asks for consent again. New routes join public-route-contract.json.

  14. Lifecycle. Enabling, disabling, consent and updates apply to new runs; run-local skill snapshots (ADR 0032) are unchanged. Disabling a plugin stops its MCP servers.

Alternatives and consequences

  • Project plugins were rejected for v1 (decision 2).
  • Safe-only plugins (no hooks or MCP) were the owner's alternative; they chose full contents with consent.
  • Plugin slash commands were dropped: the owner wants the model, not a composer shortcut, to use a plugin's prompts, which skills already provide. .ru/commands stays a CLI feature.
  • Skill ids stay un-namespaced to keep /skill <id> and existing preferences working; shadowing is reported instead.
  • This amends "plugins are not loaded" in runtime-behavior.md, harness.md, coding-agent-capabilities.md, CONTEXT.md and the CLI README, and extends ADR 0025 (a second, user-level MCP source behind consent) and ADR 0036 (a second managed package kind).

Implementation phases

Each phase is built, tested and committed on its own.

  1. Manifest and loader; user plugins with skills and instructions; the plugin list with enable/disable in Customize → Plugins (Computer use stays); New plugin scaffolding. Done.
  2. Hooks and MCP with the consent digest and path protection (policy change: full matrix). Done.
  3. GitHub install and update (new routes: full matrix and route guards). Done: SkillPackageInstaller takes a package kind; a plugin package needs ru-plugin.json (whose id must match the folder), writes .ru-plugin-package.json, reports plugin_* codes, and installs under %LOCALAPPDATA%\Ru\plugins. A local plugin with the same id refuses the install (plugin_target_exists).
  4. create-plugin skill and Add plugin from folder. Done: Ru ships built-in skills in skills-builtin next to the Host (BuiltInSkills.Root), searched after plugin skills so any other skill with the same id wins. create-plugin writes a draft under ru-plugin-drafts\<id> in the workspace. The import action on POST /agent/v1/plugins/settings (no new route) copies a draft into ~/.ru/plugins/<id> after checking the manifest, refusing links, more than 256 files or 64 MiB, and any id already installed locally or managed; it skips .git and installer metadata, copies through a staging folder, and never enables the plugin: importing (or freshly installing from GitHub) an id clears any enable flag and approval left from an earlier plugin with that id.