From 6359a67aab04754ec16cddd626b3015e24a09954 Mon Sep 17 00:00:00 2001 From: gsxdsm Date: Wed, 10 Jun 2026 10:31:46 -0700 Subject: [PATCH] FN-6200: document plugin-gated built-in workflows Explain how bundled workflows stay hidden until their required plugin is installed. - document the plugin-gated built-in workflow model in the plugin authoring guide - show the core gating map and workflow visibility rules for listing and lookup - note that the Compound Engineering built-in workflow appears only while its plugin is installed Files changed: docs/PLUGIN_AUTHORING.md | 48 ++++++++++++++++++++++++++++++++++++ docs/plugins/compound-engineering.md | 6 +++++ 2 files changed, 54 insertions(+) Fusion-Task-Id: FN-6200 Fusion-Task-Lineage: 72c64220-aef9-4f6b-92c3-5f53e67292fc --- docs/PLUGIN_AUTHORING.md | 48 ++++++++++++++++++++++++++++ docs/plugins/compound-engineering.md | 6 ++++ 2 files changed, 54 insertions(+) diff --git a/docs/PLUGIN_AUTHORING.md b/docs/PLUGIN_AUTHORING.md index e3dcb02104..9d578e203d 100644 --- a/docs/PLUGIN_AUTHORING.md +++ b/docs/PLUGIN_AUTHORING.md @@ -1692,6 +1692,54 @@ the `plugin::` form, and values must be JSON objects. If the extension is registered and declares a `configSchema`, the engine validates the metadata fields during IR validation. +## 16.7. Plugin-Gated Built-in Workflows + +Plugin-gated built-in workflows are read-only workflow definitions that ship in +Fusion's `BUILTIN_WORKFLOWS` array but stay hidden until their associated plugin +is installed. For example, `builtin:compound-engineering` is bundled with core so +it can be selected like any other built-in workflow, but it references +Compound Engineering plugin skills that do not exist unless the plugin is active. + +Runtime gating is declared in `packages/core/src/builtin-workflows.ts`. The +`PLUGIN_GATED_BUILTIN_WORKFLOWS` map links each gated built-in workflow id to the +plugin id that unlocks it: + +```typescript +// In packages/core/src/builtin-workflows.ts +const PLUGIN_GATED_BUILTIN_WORKFLOWS: ReadonlyMap = new Map([ + ["builtin:compound-engineering", "fusion-plugin-compound-engineering"], +]); +``` + +When the dashboard or API lists workflow definitions, `listWorkflowDefinitions()` +checks each built-in with `isBuiltinWorkflowPluginGated()` and then calls +`isPluginInstalled()` for the required plugin before including it. Direct lookup +uses the same rule: `getWorkflowDefinition()` returns `undefined` for a gated +built-in until `getRequiredPluginIdForBuiltinWorkflow()` resolves to an installed +plugin. + +The workflow-definition cache is invalidated on plugin register/unregister +events, so installing or removing a plugin updates the visible workflow list +immediately. Gated built-ins are also excluded from +`defaultEnabledBuiltinWorkflowIds()`: they are never enabled by default and only +surface when the gating plugin is present. + +Use this pattern when a first-party built-in workflow references plugin-provided +skills, tools, workflow handlers, or other runtime capabilities that would be +missing without the plugin. The gate prevents users from selecting a workflow +that cannot run in their project. + +The current first-party example is `builtin:compound-engineering`, which is gated +on `fusion-plugin-compound-engineering`. It does not appear in the workflow +picker or task workflow selection until the Compound Engineering plugin is +installed and enabled; if the plugin is uninstalled, the workflow is hidden +again. + +> **Plugin author note:** plugin-gated built-in workflows are currently for +> first-party, bundled workflows because the gating map lives in `@fusion/core`. +> Plugin authors who want to add their own workflow behavior should use the +> workflow step contribution API in §16 or workflow extensions in §16.6 instead. + ## 17. Contributing Prompt Modifications Prompt contributions let a plugin inject additional instructions into specific prompt surfaces. diff --git a/docs/plugins/compound-engineering.md b/docs/plugins/compound-engineering.md index 2447daae98..c74a391e49 100644 --- a/docs/plugins/compound-engineering.md +++ b/docs/plugins/compound-engineering.md @@ -14,6 +14,12 @@ When installed and enabled, the plugin registers the **Compound Engineering** dashboard view destination and installs its bundled `ce-*` skills into a plugin-local, discoverable directory (never a global `~/.claude/skills` path). +**Built-in workflow gating:** the `builtin:compound-engineering` workflow is +hidden from the workflow picker and task workflow selection until this plugin is +installed and enabled. Once the plugin is active, the workflow appears +automatically alongside other built-in workflows — no additional configuration is +needed. If the plugin is uninstalled, the workflow is hidden again. + ## Dashboard view The Compound Engineering view is registered as a primary plugin destination