Description
Surface-Scoped Superpower Invocation is the shared runtime that turns a stored Superpower row into context an AI interaction can use. It first resolves whether the row is active and allowed on the requested surface, then maps its persisted template id to one of the eight known kinds and renders the kind-specific properties into a system-prompt fragment. Chat, CLI, MCP, and API consumers therefore share one visibility and translation contract.
The runtime deliberately separates listing from invocation-time validation. A picker can request the currently invokable roster, while the dispatch path checks the row again immediately before rendering. Disabling a Superpower after selection therefore prevents a stale choice from running.
Selling Points
- Gives administrators one switch per surface instead of duplicating a Superpower for each channel.
- Removes draft, disabled, and archived content from invocation regardless of permissive surface flags.
- Keeps Chat, CLI, MCP, and API behavior aligned through a single visibility predicate.
- Converts all eight stored Superpower shapes into predictable prompt context without consumer-specific parsing.
- Degrades malformed structured blocks by omitting them rather than crashing the entire conversation.
User Story
An administrator activates a research Skill for Chat and MCP but leaves API access off. It appears in the Chat picker and can be discovered by an MCP client. If the administrator disables it during an active session, the next dispatch rechecks the same row, drops the invocation, and prevents stale cached UI state from bypassing the new setting.
Extension Surface
packages/superpowers/src/templates/shared.ts places configurable enabled_for_chat, enabled_for_cli, enabled_for_mcp, and enabled_for_api properties on every type. packages/superpowers/src/internal/visibility.ts interprets those values with explicit absent defaults, making per-row configuration the supported extension point while keeping the surface vocabulary fixed.
Capabilities & Limits
The runtime lists invokable rows through an injected database seam, narrows persisted template ids to known Superpower types, enforces active status plus surface enablement, and renders type-specific fragments. It supports both raw property envelopes and projected DTO-like rows.
Invocation presentation is co-owned by its consumers: this package does not own the Chat picker, MCP tool transport, CLI command registration, or Forge authoring. API access also defaults off when its enablement value is absent, while Chat, CLI, and MCP default on. The renderer never repairs malformed stored structures; it safely drops only the invalid block.
Implementation Map
packages/superpowers/src/internal/visibility.tspackages/superpowers/src/internal/render-fragment.tspackages/superpowers/src/internal/services/invokable-superpowers-service.tspackages/api/src/routes/superpowers.tsapps/web/src/composition/invoked-superpower-dispatch-seams.ts