Ouroboros Plugins

UserLevel plugin ecosystem for Ouroboros.

Ouroboros core should provide stable OS primitives. Plugins and first-party programs compose those primitives into domain-specific workflows.

+-------------------------------------------------------------------+
|                Installable UserLevel Programs                      |
|                                                                   |
|  autoresearch    gsd-agentos     target-capabilities  github-pr-ops |
|  openai-skills-superpowers  openhands-agentos  merge-assistant       |
|  openhands-agentos  merge-assistant  jira-sync  slack-incident      |
|  swe-agent-harness  release-coordinator  customer-debugger  ...       |
+-------------------------------+-----------------------------------+
                                |
                                | plugin contract / declared scopes
                                v
+-------------------------------------------------------------------+
|                First-party UserLevel Programs                      |
|                                                                   |
|  ooo auto     ooo run     ooo pm     ooo review?     ...           |
+-------------------------------+-----------------------------------+
                                |
                                | stable OS primitives
                                v
+-------------------------------------------------------------------+
|                         Ouroboros Core / OS                         |
|                                                                   |
|  Seed      Ledger      State      Runtime      MCP                 |
|  Provenance  Safety Boundaries  Progress/Status  Handoff           |
+-------------------------------------------------------------------+

Repository Purpose

This repository is the home for the UserLevel plugin contract and reference plugin packages. It is intentionally not a registry server yet.

The initial goal is a local-only contract MVP:

• Plugin manifest format
• Command namespace declaration
• Core capability declaration
• External permission declaration
• Provenance and audit requirements
• Example UserLevel plugin packages, including external capability-assimilation adapters
• Anthropic Agent Skills assimilation reference plugin for anthropics/skills
• OpenAI/Agent Skills assimilation reference plugin for openai/skills
• External repository capability assimilation reference package

Core Boundary

Ouroboros core owns primitives:

• 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

Plugins own domain-specific workflows:

• GitHub PR operations
• Autoresearch experiment handoff
• GSD AgentOS capability assimilation
• OpenAI/Agent Skill superpower assimilation
• SWE-agent issue-to-patch harness assimilation
• Merge assistance
• Jira/Linear synchronization
• Slack incident workflows
• Release coordination
• Customer debugging playbooks

Example UX

ouroboros plugin add https://github.com/Q00/ouroboros-plugins --plugin autoresearch
ouroboros plugin add https://github.com/Q00/ouroboros-plugins --plugin github-pr-ops
ouroboros plugin add https://github.com/Q00/ouroboros-plugins --plugin gsd-agentos
ouroboros plugin add https://github.com/Q00/ouroboros-plugins --plugin openhands-agentos
ouroboros plugin add https://github.com/Q00/ouroboros-plugins --plugin swe-agent-harness
ouroboros plugin add https://github.com/<author>/<target>-ouroboros --plugin target-capabilities
ouroboros plugin trust github-pr-ops --scope github:read --scope github:pull_request:write

ooo auto-research prepare /path/to/autoresearch --goal "Improve validation bpb"
ooo gsd plan-phase 1
ooo gsd verify-work 1
ooo github-pr review https://github.com/org/repo/pull/123
ooo openhands agentos --workspace /path/to/repo --goal "Fix the failing test" --trusted-shell-execute
ooo superpower run openai-docs -- "explain how to build a plugin"
ooo swe-agent run --config config/default.yaml --problem_statement.github_url https://github.com/org/repo/issues/123
ooo github-pr merge --policy team-default

Ouroboros v0.39.1+ prompts for non-destructive required permissions during plugin add, so autoresearch can grant filesystem:read and filesystem:write during install. Destructive scopes, including PR write scopes, still require an explicit plugin trust command.

OpenAI Skills Superpowers and AgentOS Capability Assimilation

The openai-skills-superpowers reference plugin shows how Ouroboros can assimilate the OpenAI/Agent Skills catalog without becoming a central marketplace. It projects skills into ooo superpower ... commands with manifest-backed permissions, audit/provenance events, trust gates, and handoff artifacts. See plugins/openai-skills-superpowers/README.md and docs/openai-skills-superpowers-pr-plan.md.

Layout

docs/
  architecture.md      Layer model and design principles
  contract.md          Plugin contract MVP
  lifecycle.md         Local-only plugin lifecycle
  permissions.md       Permission and trust model
  audit.md             Audit and provenance event model
  migrations/          MAJOR-version schema migration guides (added when needed)
schemas/
  0.1/
    plugin.schema.json       Draft JSON Schema for plugin manifests (v0.1)
    audit-event.schema.json  Draft JSON Schema for audit events (v0.1)
plugins/
  anthropic-agent-skills/ Anthropic Agent Skills assimilation reference plugin
  openai-skills-superpowers/ OpenAI/Agent Skills capability-assimilation adapter
  autoresearch/        Autoresearch-to-ooo-auto handoff plugin
  gsd-agentos/         GSD command-surface assimilation plugin
  target-capabilities/ Reference external-repo assimilation package
  opa-policy-gate/     OPA policy gate reference plugin
  github-pr-ops/       Reference plugin skeleton
  openhands-agentos/   OpenHands-to-AgentOS audited handoff plugin
catalog/
  index.json           Local catalog (boring index for reproducibility,
                       NOT a package-registry server)

Validate

A contract-validation GitHub Actions workflow runs the validator on every pull request and on pushes to main. To run it locally:

pip install -r requirements-dev.txt
python3 scripts/validate_contract.py
PYTHONPATH=plugins/autoresearch python3 -m ouroboros_autoresearch inspect /path/to/autoresearch
PYTHONPATH=plugins/autoresearch python3 -m ouroboros_autoresearch prepare /path/to/autoresearch --goal "Improve validation bpb"
PYTHONPATH=plugins/gsd-agentos python3 -m gsd_agentos validate-catalog
PYTHONPATH=plugins/gsd-agentos python3 -m gsd_agentos list
PYTHONPATH=plugins/github-pr-ops python3 -m github_pr_ops review https://github.com/Q00/ouroboros/pull/1
PYTHONPATH=plugins/openhands-agentos python3 -m openhands_agentos inspect
PYTHONPATH=plugins/target-capabilities python3 -m target_capabilities list-commands
PYTHONPATH=plugins/openai-skills-superpowers python3 -m ouroboros_superpowers catalog refresh --source-path tests/fixtures/openai-skills --ref fixture --out superpowers-catalog.json
PYTHONPATH=plugins/openai-skills-superpowers python3 -m ouroboros_superpowers --catalog superpowers-catalog.json run openai-docs -- "explain plugins"
PYTHONPATH=plugins/swe-agent-harness python3 -m swe_agent_harness inspect /path/to/swe-agent-output

During plugin development, install from the local checkout instead:

ouroboros plugin add . --plugin autoresearch

The first step is required: validate_contract.py imports jsonschema from requirements-dev.txt. On a clean checkout, skipping it makes the validator exit 2 with a "jsonschema is required" message.

Issue #45 is captured in docs/opa-policy-gate-pr-plan.md. The short version: opa-policy-gate proves that a mature external policy engine can keep native OPA/Rego workflows while gaining Ouroboros permission, audit, provenance, and handoff semantics through the plugin contract.

Status

Draft. This repository is for shaping the contract before committing to a full package registry or marketplace.

External Repository Assimilation

Issue #29 is captured in docs/assimilation.md, and the broader #27 authoring consensus is captured in docs/rfc/plugin-authoring-and-capability-assimilation.md. The short version: ouroboros-plugins is the contract/reference substrate, while an external target repository is assimilated as a permissioned, auditable, continuable plugin package. The target-capabilities package is the v0 reference fixture for that boundary.