Vision: define an authoritative plugin capability contract for ourocode

[Q00]

Vision

ourocode should not have to infer installed UserLevel plugin capabilities from prompt text, filesystem layout, or ad hoc shell behavior. It needs an authoritative capability contract from Ouroboros that says which plugins are installed, which commands they expose, what safety state applies, and what artifacts a command may produce.

This builds on proposed scope item 2 in #2: resolving installed plugins and commands through the Ouroboros plugin registry, lockfile, or a stable CLI/MCP surface. The product goal is to make plugin discovery boring, deterministic, and safe enough for both direct ooo <plugin> ... prompts and natural-language routing.

Product direction

Define a stable plugin capability contract that ourocode can consume before dispatching anything. The contract should be owned by Ouroboros plugin metadata or an official Ouroboros CLI/MCP discovery surface, while ourocode uses it as the read-only source of truth for routing and UI decisions.

The contract should answer:

• which UserLevel plugins are installed and available in the current scope
• which commands each plugin exposes, including aliases and descriptions
• what arguments are required, optional, or repeatable
• whether a command is read-only, handoff-producing, or potentially destructive
• what trust or permission state blocks execution
• what output artifacts may be produced, including Seeds, handoff files, reports, and logs
• what remediation message should be shown for missing, untrusted, or incompatible plugins

Why this matters

Without an authoritative contract, every layer has to guess:

• the router guesses whether a natural-language prompt refers to an installed plugin
• the command palette guesses which commands are valid
• dispatch code guesses whether it is safe to execute
• continuation logic guesses where generated artifacts live
• tests end up hardcoding plugin-specific behavior instead of validating a generic interface

A clear contract lets ourocode stay thin: discover capabilities, show them, route to them, and dispatch through the existing Ouroboros trust/firewall boundary. It also keeps plugin authors from needing bespoke ourocode integrations for every workflow.

Relationship to existing issues

• Support natural-language dispatch for installed Ouroboros UserLevel plugins #2 defines the end-to-end UserLevel plugin dispatch experience.
• Build a plugin capability index for intent-driven workflows #5 and Establish a plugin capability registry for natural-language dispatch #8 describe the ourocode-side capability index/registry that would consume this contract.
• Vision: treat plugin run artifacts and continuations as first-class session objects #7 describes the post-dispatch artifact and continuation lifecycle that should use declared artifact metadata.
• docs: rescope userlevel plugin dispatch around SSOT #25 (PR 1/5) #3 documents the first design pass for natural-language UserLevel plugin dispatch.

This issue is specifically about the cross-boundary contract that should feed those features, not the UI or dispatch implementation itself.

Proposed scope

1. Define the minimum capability schema needed by ourocode for routing, trust display, dispatch payload construction, and artifact continuation.
2. Decide the authoritative source for the schema: registry/lockfile metadata, a stable ouroboros plugin capabilities CLI command, an MCP endpoint, or a combination with clear precedence.
3. Include versioning and compatibility behavior so ourocode can reject unsupported metadata without unsafe fallback execution.
4. Represent trust and permission state explicitly without granting trust or expanding permissions.
5. Represent expected output artifacts generically enough for workflows like superpowers test-driven-development to declare generated seed.md files.
6. Add fixture-based tests that let ourocode validate routing and UI behavior without executing plugin code.

Acceptance criteria

• There is a documented capability contract that ourocode can consume without plugin-specific hardcoding.
• The contract includes plugin identity, command metadata, argument metadata, trust/permission state, risk classification, and expected artifact declarations.
• superpowers commands can be represented by the contract, including read-only commands and handoff-producing workflows.
• Unsupported contract versions produce actionable blocked states rather than falling back to arbitrary shell execution.
• The contract can be tested with static fixtures and does not require executing plugin commands during discovery.
• Future ourocode routing work can use this contract as the only source of plugin command truth.

Non-goals

• Implementing plugin dispatch.
• Building a marketplace or install flow.
• Auto-trusting plugins.
• Replacing the Ouroboros plugin firewall.
• Designing a full artifact browser.