Design a UserLevel plugin manager for operational workflows

[Q00]

Vision

Ouroboros should be understood as an OS-like core plus UserLevel programs built on top of it.

The core should provide stable primitives. UserLevel programs should compose those primitives into useful workflows. Some UserLevel programs can be first-party and ship with Ouroboros, such as ooo auto. Others should be installable plugins maintained by teams or the ecosystem.

This gives us a cleaner boundary than putting every useful workflow into core, or into ooo auto.

Layer Model

+-------------------------------------------------------------------+
|                Installable UserLevel Programs                      |
|                                                                   |
|  github-pr-ops   merge-assistant   jira-sync   linear-triage       |
|  slack-incident  release-coordinator  customer-debugger  ...       |
+-------------------------------+-----------------------------------+
                                |
                                | plugin contract / declared scopes
                                v
+-------------------------------------------------------------------+
|                First-party UserLevel Programs                      |
|                                                                   |
|  ooo auto     ooo run     ooo pm     ooo review?     ...           |
|                                                                   |
|  These are product-level workflows maintained with Ouroboros,       |
|  but they are still programs above the core, not the core itself.   |
+-------------------------------+-----------------------------------+
                                |
                                | uses stable OS primitives
                                v
+-------------------------------------------------------------------+
|                         Ouroboros Core / OS                         |
|                                                                   |
|  Seed      Ledger      State      Runtime      MCP                 |
|  Provenance  Safety Boundaries  Progress/Status  Handoff           |
+-------------------------------+-----------------------------------+
                                |
                                | bounded adapters / external calls
                                v
+-------------------------------------------------------------------+
|                    External Systems / Runtimes                      |
|                                                                   |
|  GitHub   Jira   Linear   Slack   CI   Local repo   Agent CLIs      |
+-------------------------------------------------------------------+

Core Boundary

Core should provide primitives that can support many workflows:

• Seed generation and validation
• Ledger and evidence/provenance tracking
• Durable workflow state
• Runtime/provider abstraction
• MCP tool surfaces
• Safety boundaries and permission checks
• Progress, recovery, and status reporting
• Execution handoff and result attachment

Core should not directly encode every domain workflow. It should not need built-in knowledge of GitHub PR merge policy, Jira triage semantics, Slack incident response flows, release checklist conventions, or customer support debugging playbooks.

Those belong at the UserLevel.

First-party UserLevel Programs

ooo auto is not the core. It is a first-party UserLevel program built on core primitives.

Its product boundary should stay clear:

ooo auto:
  goal -> clarification/interview -> Seed -> validation -> execution handoff

That is a valuable first-party workflow. It can use Seed, ledger, state, provenance, safety, runtime, MCP, progress, recovery, and handoff primitives. But it should not become the place where every operational workflow is routed.

This distinction matters. Saying something does not belong in core does not mean Ouroboros cannot ship UserLevel programs. It means those programs should have explicit product boundaries.

Installable UserLevel Programs

Many useful workflows should live beside ooo auto, not inside it.

Examples:

github-pr-ops       review PRs, summarize status, prepare merge decisions
merge-assistant     enforce team-specific merge policies
jira-sync           turn Seeds or execution results into Jira updates
linear-triage       classify and route product/engineering issues
slack-incident      gather context, summarize incident state, draft updates
release-coordinator coordinate changelog, CI, tags, and rollout checks

These workflows can be powerful while remaining outside both core and ooo auto.

Plugin / Program Manager

To support installable UserLevel programs, Ouroboros needs a manager layer.

The manager is not just a convenience installer. It is the boundary that lets external programs use core primitives safely and predictably.

Example UX sketches:

ouroboros plugin add github-pr-ops
ouroboros plugin trust github-pr-ops --scope github:read,pull_request:write

ooo github-pr review https://github.com/org/repo/pull/123
ooo github-pr merge --policy team-default

or, if we want a shorter UserLevel syntax:

ooo add github-pr-ops
ooo github-pr "review and prepare merge for PR #123"

The plugin owns the command namespace. Core owns the permission model, audit trail, state contract, and execution boundaries.

Required Contract

A first-class UserLevel program/plugin contract likely needs:

• Manifest: name, version, description, commands, entry points
• Capabilities: declared access to core primitives such as Seed, ledger, state, MCP, runtime, and handoff
• Permissions: declared external scopes such as GitHub read/write, filesystem, network, shell, or repo access
• Command namespace: explicit ownership and collision handling
• State boundaries: plugin-owned state vs core-owned state
• Audit/provenance: every program-driven action records who invoked it, what program ran, what capabilities were used, and what external systems were touched
• Version pinning: reproducible workflow behavior across teams and agents
• Trust policy: local plugins, git-sourced plugins, registry plugins, signed or verified plugins
• Uninstall/update semantics: remove or upgrade without corrupting core state

Why This Matters

The failure mode is clear:

Bad direction:
  ooo auto grows GitHub logic, Jira logic, Slack logic, release logic, etc.

Better direction:
  Core exposes stable OS primitives.
  ooo auto remains a first-party goal -> Seed -> handoff program.
  Additional domain workflows become separate UserLevel programs.

This gives contributors a clean place to put useful but domain-specific ideas. Instead of debating whether every workflow belongs in core or inside ooo auto, we can ask:

1. Is this an OS primitive?
2. Is this part of an existing first-party UserLevel program's product boundary?
3. Or should it be a separate UserLevel program/plugin?

Relationship To #689

#689 is a good example of the boundary problem.

The GitHub PR operational workflow is useful, but it is neither an OS primitive nor part of the ooo auto product boundary.

It should become a separate UserLevel program such as github-pr-ops or merge-assistant, using core primitives for state, provenance, safety, policy checks, and execution handoff.

That keeps core small, keeps ooo auto coherent, and still allows the ecosystem to grow.

MVP Direction

Sub-issue priority: C + D first (audit-wrapped invocation + github-pr-ops reference plugin). A and B (manifest format expansion, manager UX maturation) emerge from what D actually exercises. See #726 for the full sub-issue index.

A full package ecosystem is a large product. The first step should probably be a local-only contract MVP, not a registry.

Possible MVP:

• Local plugin/program manifest
• Command namespace registration
• Declared core capabilities
• Declared external permissions
• Read-only provenance/audit recording
• No registry
• No auto-update
• No destructive permissions by default
• One reference UserLevel program, likely github-pr-ops, to validate the contract

The goal is to stabilize the contract before promising a full ecosystem.

Open Questions

• Should the package unit be called plugin, skill, package, workflow, or UserLevel program?
• Should the manager reuse the existing skill system, extend it, or replace parts of it?
• What permissions are needed for v1? (scope partly resolved by RFC: Trust UX for required:true destructive permissions ouroboros-plugins#9)
• Should plugins run in-process, out-of-process, or both?
• Should plugin commands be exposed through ooo <namespace> ..., ouroboros plugin run ..., or both?
• How do plugins publish MCP tools without bypassing core audit/provenance? (partly resolved by the firewall in Phase 1: Implement plugin invocation firewall + audit-event emitter #729; remaining MCP-specific concerns to file separately if surfaced)

Resolved questions (kept for history; resolutions are referenced):

• "Should first-party programs and installable plugins share the same manifest format?" — resolved YES by RFC: Should first-party programs share the plugin manifest? (source.type=first_party semantics) ouroboros-plugins#8.
• "What is the minimum stable manifest format?" — resolved by RFC: Manifest minimum required fields — 4 vs 10 ouroboros-plugins#6 (8 required + 2 optional).
• "Should there be an official registry, or should v1 support local path and git URL only?" — resolved: local + git URL only. Marketplace as a product surface is a non-goal.

Non-goals

• Do not move domain-specific operational workflows into core.
• Do not put every useful workflow into ooo auto.
• Do not let plugins mutate arbitrary core state without declared capabilities.
• Do not make install imply trust for destructive actions.
• Do not design this only for GitHub PR workflows; GitHub should be one UserLevel program, not the architecture.
• Marketplace as a product surface is a non-goal. Plugin distribution is local path + git URL only. Any future catalog/index is reproducibility infrastructure, not a discovery / ranking / recommendation surface.

Self-restraint (operating principles)

The plugin layer exists to keep core small, not to grow ecosystem surface area. Specifically:

• We do not pursue plugin count, marketplace dynamics, or "ecosystem health" as success metrics. The success metric for Ouroboros remains the strength of the spec-first discipline (Interview / Seed / Evolve / Provenance) and the quality of execution under that discipline.
• Reference plugins are deliberately few, high-quality, and maintained by core authors or co-maintainers — not a long-tail catalog.
• Lock-in for Ouroboros comes from the spec-first discipline and the durable substrate (ledger, provenance, seed history), not from how many plugins exist on top.
• The plugin layer is plumbing. It exists invisibly to prevent core bloat. It is not a product surface.

[ouroboros-agent]

This looks like a multi-PR effort that needs design discussion before implementation. Labeling needs-design for human planning.

Scope assessment:

• Existing plugin/skill foundations already exist in src/ouroboros/plugin/skills/registry.py, src/ouroboros/plugin/skills/executor.py, and the extension-point docs in docs/architecture.md.
• The proposal goes beyond those internals and would need a user-facing package manager design: install/update/remove flows, version pinning, trust policy, permission declarations, command namespace ownership, provenance/audit integration, and CLI surface changes.
• Likely affected areas span plugin architecture, command routing/CLI UX, persistence/audit boundaries, docs, and tests, so this should be planned as a staged design rather than a single implementation PR.

ouroboros-agent[bot]

[shaun0927]

Follow-up on the previous comment, sharpening one specific aspect of the vision: what the plugin layer is for.

Re-reading the issue, I want to flag that there are two possible readings of #725 and they lead to very different v0 designs:

Two readings of "plugin layer"

Reading	Purpose	Success metric	OS analogy
(A) Growth-oriented	Healthy ecosystem of installable workflows; ecosystem health is the value	Number / diversity / composition of plugins	Linux + apt, iOS + App Store
(B) Defense-oriented	Escape valve to keep core small; plugin layer is plumbing that prevents core bloat, not the product	Spec-first discipline preserved; few high-quality reference skills	Neovim, Obsidian

#725 as written reads closer to (A) — "ecosystem", 7 plugin examples in the Plugin Layer section, an open question about an official registry, "ecosystem expansion without turning ooo auto into a catch-all" framed as a positive.

I'd argue strongly for (B), and I think it's actually the read the rest of the project supports. Stating it explicitly in #725 would change several v0 decisions.

Why defense-oriented, not growth-oriented

1. Lock-in for Ouroboros comes from the spec-first discipline, not from plugin count. The unique value is Interview → Seed → Evolve → Provenance — quantified ambiguity gating, durable why-decisions. That is not replicable by another tool adopting "plugin XYZ". GitHub PR ops, Jira sync, Slack incident response — every adjacent tool has those. Plugins are commodity; spec-first discipline is not.
2. Ecosystem-driven lock-in is fragile at fork scale. A healthy ecosystem (governance, security review, breaking-change discipline, support) is operationally expensive. If maintaining 50 plugins becomes the steady state, the maintainer cost grows with the ecosystem and the unique value gets diluted. Neovim and Obsidian survive because their core does one thing exceptionally well without plugins, and plugins are a sweetener, not the offer.
3. A user-facing "AI workflow App Store" is not what ooo should sell. The promise of ooo auto "do X" is "spec-first agent does the right thing." Adding "...but first, browse the marketplace and install the right plugin" makes the entry experience worse, not better. The plugin system needs to exist invisibly — to keep core small — and not become a UX surface.

What this changes in v0 design

If we adopt the defense-oriented reading explicitly, several open questions resolve:

• Reference skills at v0: exactly one (github-pr-ops, the Add direct operational-task path for concrete PR and merge goals in ooo auto #689 capability). Not "a few to dogfood" — one. The point of the first reference skill is to prove the contract, not to populate an ecosystem.
• Registry: permanent non-goal, not "open question". v0/v1/forever = local path + git URL only. No marketplace.
• Permissions: declared-only, never enforced by core. Sandboxing is a separate product (it's a sandboxing tool, not Ouroboros). If Ouroboros ever ends up needing isolation, it should compose with an existing sandboxing primitive, not grow one inside.
• Manifest contract: the minimum 4 fields that prevent core bloat (commands, capabilities, permissions, audit hook). The other 5 in the "Required Core Contract" list (version pinning, trust policy, uninstall semantics, ...) are valuable but should land only when a concrete second reference skill needs them — not preemptively.
• Memory / hermes integration: usable, but for dispatch learning ("this user always picks github-pr-ops for PR URLs → auto-route") rather than for plugin discovery / recommendation. The latter is the App Store reflex and should be avoided.
• Sub-issue prioritization: I previously suggested A → (B || C) → D. Under defense-oriented framing this becomes C + D first (audit-wrapped MCP + the one reference skill); A and B fall out only as much as is needed to make D work. This avoids over-specifying the contract before any plugin actually exercises it.

Concrete proposed addition to the issue body

Suggest adding a section that pins this self-restraint, immediately after Non-goals:

## Self-restraint (operating principles)

The plugin layer exists to keep core small, not to grow ecosystem
surface area. Specifically:

- We do not pursue plugin count, marketplace dynamics, or "ecosystem
  health" as success metrics. The success metric for Ouroboros remains
  the strength of the spec-first discipline (Interview / Seed / Evolve /
  Provenance) and the quality of execution under that discipline.
- Reference skills are deliberately few (target ~1–5 long-term),
  high-quality, and maintained by core authors or co-maintainers — not
  a long-tail catalog.
- Lock-in for Ouroboros comes from the spec-first discipline and the
  durable substrate (ledger, provenance, seed history), not from how
  many plugins exist on top.
- The plugin layer is plumbing. It exists *invisibly* to prevent core
  bloat. It is not a product surface.

And one Non-goal addition:

- Do not build, host, or sanction an official registry / marketplace
  for plugins. Plugin distribution is local path + git URL only,
  permanently.

What I'm asking for

Concur or push back on the defense-oriented reading. Specifically:

1. Do we agree on one reference skill at v0 (not a few)?
2. Do we agree on registry as permanent non-goal?
3. Do we agree on declared-only permissions, no enforcement layer?
4. Do we agree on C + D first (audit-wrapped MCP + github-pr-ops), with A and B emerging from D's needs?

Big picture: I'm not arguing against the Agent OS abstraction or the 4-layer architecture. Both are right. I'm arguing that the abstraction should serve a deliberately small product, not become the product itself. Vim/Neovim is the model worth borrowing here, not VSCode.

If this framing lands, every future "should this go in core or plugin?" question gets a third option: "do we even want this?" — which I think is the question this project has been quietly avoiding.