Epic: Expose every Superpowers skill as an Ouroboros-native agentOS command

[shaun0927]

Summary

Build an Ouroboros-native Superpowers plugin that exposes every skill from obra/superpowers as an explicit Ouroboros command while preserving the Ouroboros plugin contract: manifest validation, scoped capabilities, external permissions, risk classification, lifecycle/trust semantics, audit/provenance, Seed-compatible handoff, and resumable execution state.

This is intentionally more ambitious than a thin compatibility wrapper. The goal is to make Superpowers run smoothly inside Ouroboros so that Ouroboros becomes a true agentOS: a substrate where external agent methodologies can be installed, trusted, invoked, audited, resumed, and composed through first-class UserLevel plugin commands.

Related consensus issue: #27

Core thesis:

Superpowers skill library / agentic development methodology
        ↓
Ouroboros plugin contract and command namespace
        ↓
Seed / Ledger / State / Provenance / Permission / Audit / Handoff
        ↓
Ouroboros-native agentOS execution surface

---

Background

obra/superpowers is an agentic software-development methodology distributed as a cross-harness skill/plugin system. It currently supports multiple agent surfaces, including Claude Code, Codex, Gemini CLI, Cursor, and OpenCode.

The repository contains a skill library centered on:

• brainstorming and requirements refinement,
• implementation planning,
• test-driven development,
• systematic debugging,
• subagent-driven execution,
• code review loops,
• branch finishing workflows,
• skill authoring and verification discipline.

This makes Superpowers an ideal test case for the capability-assimilation direction described in #27. It is not merely a CLI tool. It is an external OSS methodology for shaping agent behavior. Ouroboros should be able to assimilate it as a permissioned, auditable, command-addressable UserLevel capability.

---

Goal

Expose every upstream Superpowers skill as an Ouroboros command under a stable command namespace, while translating each skill into Ouroboros-native execution semantics.

The user-facing target should feel like:

ooo superpowers list

ooo superpowers using-superpowers

ooo superpowers brainstorming --goal "Build a React todo app"
ooo superpowers writing-plans --spec docs/specs/todo.md
ooo superpowers test-driven-development --task "Add retry behavior"
ooo superpowers systematic-debugging --symptom "Tests are flaky"
ooo superpowers subagent-driven-development --plan docs/plans/todo.md
ooo superpowers requesting-code-review --range main..HEAD
ooo superpowers verification-before-completion --claim "tests pass"
ooo superpowers finishing-a-development-branch --branch feature/todo

The important property is not the exact command spelling; it is that each skill becomes a first-class, inspectable, permissioned Ouroboros command rather than an opaque prompt fragment.

---

Non-goals

This epic should not turn Q00/ouroboros-plugins into a marketplace.

This epic should not bypass the plugin firewall by directly injecting arbitrary Superpowers instructions into core runtime without manifest, trust, permission, and audit checks.

This epic should not make ooo auto a catch-all router for Superpowers-specific branching. ooo auto may consume plugin-prepared Seeds or handoff artifacts, but Superpowers-specific behavior should live in the plugin.

This epic should not begin with destructive branch/merge behavior. Workflows such as finishing-a-development-branch may describe destructive options, but actual destructive actions require explicit command risk, permission, trust, and confirmation semantics.

This epic should not require immediate manifest schema expansion unless an implemented reference path proves the existing v0.1 contract cannot express the needed behavior.

---

Proposed plugin identity

Suggested plugin name:

superpowers

Alternative if we want to emphasize adaptation rather than upstream ownership:

superpowers-adapter

Suggested command namespace:

superpowers

Suggested repository layout if implemented in this repository as a reference plugin:

plugins/
  superpowers/
    ouroboros.plugin.json
    README.md
    superpowers_ouroboros/
      __main__.py
      upstream.py
      skill_index.py
      command_router.py
      handoff_builder.py
      provenance.py
      audit.py
      permissions.py
    vendor/
      superpowers/
        LICENSE
        README.md
        skills/
          ...

Suggested layout if distributed from a separate author repository:

ouroboros-superpowers/
  README.md
  plugins/
    superpowers/
      ouroboros.plugin.json
      README.md
      superpowers_ouroboros/
        ...
  catalog/
    index.json

Per #27, the repository URL remains the unit of distribution, and plugins/superpowers/ is the unit of selection.

---

Upstream skill inventory to expose

The upstream obra/superpowers repository currently includes these skills, all of which should receive a corresponding Ouroboros command surface:

Upstream skill	Proposed Ouroboros command	Primary risk	Notes
using-superpowers	ooo superpowers using-superpowers	read_only	Introduces the Superpowers methodology and skill-loading discipline. In Ouroboros this should become inspectable guidance, not an uncontrolled session-start injection.
brainstorming	ooo superpowers brainstorming	write	Converts a rough idea into a design/spec artifact. Should integrate with Ouroboros clarification/deep-interview and Seed preparation rather than bypassing them.
writing-plans	ooo superpowers writing-plans	write	Converts an approved spec into a detailed implementation plan / Seed-compatible handoff.
executing-plans	ooo superpowers executing-plans	write	Executes an existing plan with checkpoints. Should use Ouroboros runtime state and audit events.
subagent-driven-development	ooo superpowers subagent-driven-development	write	Maps Superpowers subagent workflow onto Ouroboros/native subagent or team execution surfaces. Must preserve file ownership and review stages.
dispatching-parallel-agents	ooo superpowers dispatching-parallel-agents	write	Prepares or launches bounded parallel task execution. Should declare runtime/progress capabilities and audit task fanout.
test-driven-development	ooo superpowers test-driven-development	write	Enforces RED/GREEN/REFACTOR constraints for implementation tasks. Should produce verification evidence and ledger entries.
systematic-debugging	ooo superpowers systematic-debugging	write	Produces or executes a root-cause investigation workflow. Should record hypotheses, evidence, and fix verification.
requesting-code-review	ooo superpowers requesting-code-review	read_only or write	Reviews diff/range and emits findings. write only if it records artifacts/ledger/handoff.
receiving-code-review	ooo superpowers receiving-code-review	write	Converts review feedback into verified implementation tasks. Should distinguish accepted vs rejected feedback in provenance.
verification-before-completion	ooo superpowers verification-before-completion	read_only or write	Gates completion claims against fresh verification evidence. Should attach evidence to ledger/handoff.
finishing-a-development-branch	ooo superpowers finishing-a-development-branch	write / future destructive	v0 should prepare completion options and evidence. Actual merge/discard/push paths require destructive risk and explicit trust.
using-git-worktrees	ooo superpowers using-git-worktrees	write	Creates or verifies isolated workspaces. Requires careful filesystem permission bounds.
writing-skills	ooo superpowers writing-skills	write	Creates or edits skill documents using documentation-TDD. Should be bounded to declared output paths.

The adapter should discover this list from upstream skill frontmatter where possible rather than hardcoding it forever. However, the public command surface should remain stable and versioned.

---

Manifest strategy

The v0 implementation should try to remain within the current v0.1 manifest contract.

Required manifest fields:

• schema_version
• name
• version
• source
• commands
• capabilities
• permissions
• entrypoint

Expected capabilities:

seed:read
seed:write
ledger:write
state:write
provenance:write
runtime:execute
handoff:attach
progress:write

Expected external permissions:

filesystem:read      required, read_only
filesystem:write     optional/required by mutating workflows, write
shell:execute        optional, write or destructive depending on command
network:read         optional, read_only for upstream fetch/update checks
github:read          optional, read_only for PR/code-review workflows if needed later
github:pull_request:write  future only, destructive if PR mutation is implemented

Risk policy:

• Skill inspection commands are read_only.
• Artifact generation, plan generation, state writes, and workspace setup are write.
• Merge, discard, push, PR mutation, branch deletion, or external posting are destructive and should be excluded from v0 execution unless trust UX is fully honored.

---

Required Ouroboros-native behavior

Each Superpowers skill command should be more than:

Print this skill file and ask the agent to follow it.

A compliant command should answer:

• Which upstream Superpowers skill was invoked?
• Which upstream version and commit supplied the skill?
• Which Ouroboros command represented it?
• What user inputs were supplied?
• Which files were read or written?
• Which core capabilities were used?
• Which external permissions were used?
• What artifact, handoff, Seed, plan, state update, or review result was produced?
• What evidence supports completion?
• Was the command completed, blocked, failed, or cancelled?
• What should a human or harness do next?

This is the line between a trivial wrapper and an Ouroboros-native assimilation layer.

---

Runtime and command model

The plugin should provide a command router entrypoint, for example:

python -m superpowers_ouroboros <skill-command> [args...]

The router should support at least:

python -m superpowers_ouroboros list
python -m superpowers_ouroboros inspect <skill>
python -m superpowers_ouroboros run <skill> [--goal ...] [--input ...]
python -m superpowers_ouroboros prepare-handoff <skill> [--goal ...] [--input ...]

The Ouroboros command declarations can map these into user-facing commands under ooo superpowers ....

The implementation should separate:

1. Skill discovery — read upstream skill frontmatter and supporting files.
2. Command declaration — expose stable command names in ouroboros.plugin.json.
3. Permission planning — determine which permissions a command needs before invocation.
4. Execution/handoff — translate the skill into an Ouroboros artifact or execution stage.
5. Audit/provenance — record what happened and why.
6. Verification — attach command-specific completion evidence.

---

Seed and handoff integration

The adapter should produce artifacts that Ouroboros can understand.

Suggested artifact types:

.omx/superpowers/
  skill-index.json
  runs/<run-id>/
    invocation.json
    provenance.json
    handoff.md
    seed.json or seed.md
    evidence.json

For example:

• brainstorming should produce a design/spec handoff.
• writing-plans should produce an implementation-plan handoff or Seed candidate.
• systematic-debugging should produce a root-cause investigation state document.
• test-driven-development should produce a test-first execution checklist and verification evidence contract.
• requesting-code-review should produce a review report artifact.
• verification-before-completion should produce an evidence gate result.

If future Workflow IR / Run / Step / Artifact projections exist in core, this plugin should map to them without needing to rewrite its public command contract.

---

Audit and provenance requirements

Every command invocation should emit or prepare the standard plugin event vocabulary:

plugin.invoked
plugin.permission_used
plugin.completed
plugin.failed

When lifecycle support exists, install/trust events remain separate:

plugin.discovered
plugin.installed
plugin.trusted

Minimum provenance fields:

{
  "upstream_repo": "https://github.com/obra/superpowers",
  "upstream_version": "<version>",
  "upstream_commit": "<commit>",
  "upstream_skill": "<skill-name>",
  "ouroboros_command": "superpowers <command>",
  "artifact_path": "<path>",
  "invoked_by": "direct|handoff|auto|team",
  "source_platform": "cli"
}

Do not write unbounded user prompts, secrets, tokens, or raw external payloads into provenance.

---

Permission and trust UX expectations

Install must not imply trust.

The plugin should be inspectable before trust is granted.

Read-only commands should be invokable with only read scopes.

Write commands should fail clearly if filesystem/state/handoff permissions are not trusted.

Destructive paths must not be silently enabled. For example, finishing-a-development-branch may initially generate a completion report with merge/PR/discard options, but actual merge, branch deletion, push, PR creation, or discard should require a future destructive command declaration and explicit trust.

---

Implementation phases

Phase 1 — RFC alignment and reference design

• Define the intended Superpowers assimilation model in docs.
• Cross-link SSOT: UserLevel plugin authoring and capability assimilation #27.
• Decide whether this plugin lives in Q00/ouroboros-plugins as a reference plugin or in a separate repository as a third-party plugin example.
• Define the command naming convention.
• Define v0 non-destructive boundaries.

Phase 2 — Manifest and skeleton plugin

• Add plugins/superpowers/ouroboros.plugin.json.
• Add plugins/superpowers/README.md.
• Add a minimal python -m superpowers_ouroboros entrypoint.
• Expose list, inspect, and prepare-handoff first.
• Validate manifest with python3 scripts/validate_contract.py.

Phase 3 — Skill discovery and command map

• Vendor or fetch pinned upstream Superpowers skill metadata.
• Parse each SKILL.md frontmatter.
• Generate a skill index.
• Ensure every upstream skill has a corresponding command mapping.
• Record upstream repo/version/commit/license provenance.

Phase 4 — Handoff generation for every skill

• Implement handoff generation for each skill.
• Each handoff must state:
  • purpose,
  • inputs,
  • required capabilities,
  • required permissions,
  • expected artifacts,
  • verification evidence,
  • continuation instructions.
• Preserve Superpowers intent while translating tool names and workflow concepts into Ouroboros surfaces.

Phase 5 — Controlled execution integration

• For safe workflows, allow the command to drive Ouroboros-native stages rather than only preparing handoffs.
• Map subagent workflows to native subagents or team execution surfaces where available.
• Keep execution resumable via state artifacts.
• Keep destructive operations blocked or confirmation-gated.

Phase 6 — Audit, provenance, and tests

• Add tests for manifest validity.
• Add tests that every upstream skill is represented in the command map.
• Add tests for permission/risk classification.
• Add tests for generated handoff shape.
• Add golden fixtures for representative skills:
  • brainstorming
  • writing-plans
  • test-driven-development
  • systematic-debugging
  • subagent-driven-development
  • finishing-a-development-branch

Phase 7 — Future schema/runtime feedback

Only after the reference implementation proves a concrete need, consider follow-up issues for:

• manifest-level skill bundle metadata,
• lifecycle hooks,
• richer command argument schemas,
• Workflow IR / Run / Step / Artifact integration,
• first-class agent/subagent capability declarations,
• destructive workflow trust UX extensions.

---

Acceptance criteria

This epic is complete when:

• A Superpowers plugin or plugin proposal exists under the repository-based plugin layout expected by the Ouroboros plugin lifecycle.
• The plugin manifest validates against the current supported schema or a documented schema-change issue explains why it cannot.
• Every upstream Superpowers skill has a corresponding Ouroboros command mapping.
• The command map distinguishes read-only, write, and destructive behavior.
• The plugin distinguishes Ouroboros core capabilities from external permissions.
• The plugin records upstream Superpowers version, commit, repository, and license provenance.
• Each command can produce an Ouroboros-native handoff artifact.
• Safe commands can be invoked without destructive permissions.
• Destructive actions are excluded from v0 execution or gated behind explicit destructive trust semantics.
• Generated artifacts are Seed-compatible or explicitly marked as Seed-preparation handoffs.
• Audit events can answer which skill/command ran, what arguments were supplied, what permissions were used, and what artifact was produced.
• Tests verify that no upstream skill is missing from the command map.
• Tests verify manifest validation and representative handoff generation.
• README documentation explains how Superpowers becomes Ouroboros-native rather than a thin command wrapper.
• Documentation links back to SSOT: UserLevel plugin authoring and capability assimilation #27 and explains why this is a capability-assimilation reference case.

---

Open questions

1. Should the reference plugin be named superpowers or superpowers-adapter?
2. Should this live in Q00/ouroboros-plugins as a contract-bearing reference plugin, or in a separate repository as the canonical third-party distribution example?
3. Should v0 vendor a pinned Superpowers snapshot, fetch from upstream at install time, or support both?
4. Should ooo superpowers <skill> execute the workflow directly, or should the first version only produce handoffs consumed by ooo auto, ooo run, $team, or $ralph?
5. What is the minimum core runtime support needed for smooth subagent/team execution mapping?
6. Do we need a manifest extension for skill bundles, or can the current commands + entrypoint contract remain sufficient for v0?
7. How should Superpowers session-start/bootstrap behavior map to Ouroboros without bypassing the plugin firewall?

---

Why this matters

If Ouroboros can assimilate Superpowers cleanly, it proves the plugin layer can absorb not only external CLIs and SDKs, but also external agent methodologies.

That is the agentOS direction:

External agent method
  → permissioned plugin
  → auditable command
  → Seed/handoff/state/provenance
  → composable Ouroboros execution

Superpowers should become a first-class, command-addressable capability inside Ouroboros, not an opaque prompt blob and not a branch inside core.

[shaun0927]

Implemented as a 5-PR stacked sequence:

1. PR Issue #28 PR1: define Superpowers AgentOS assimilation scope #116 — Issue Epic: Expose every Superpowers skill as an Ouroboros-native agentOS command #28 PR1: define Superpowers AgentOS assimilation scope
2. PR Issue #28 PR2: add Superpowers manifest and discovery #117 — Issue Epic: Expose every Superpowers skill as an Ouroboros-native agentOS command #28 PR2: add Superpowers manifest and discovery
3. PR Issue #28 PR3: generate Superpowers handoff artifacts #118 — Issue Epic: Expose every Superpowers skill as an Ouroboros-native agentOS command #28 PR3: generate Superpowers handoff artifacts
4. PR Issue #28 PR4: test Superpowers coverage and artifacts #119 — Issue Epic: Expose every Superpowers skill as an Ouroboros-native agentOS command #28 PR4: test Superpowers coverage and artifacts
5. PR Issue #28 PR5: catalog and final-validate Superpowers plugin #120 — Issue Epic: Expose every Superpowers skill as an Ouroboros-native agentOS command #28 PR5: catalog and final-validate Superpowers plugin

Merge order: #116 → #117 → #118 → #119 → #120.

Final validation on the top stacked branch:

python3 -m compileall -q plugins/superpowers/superpowers_ouroboros
python3 scripts/validate_contract.py
python3 -m unittest tests.test_superpowers_plugin tests.test_validator tests.test_autoresearch_plugin

Result: contract validation passed for 3 manifests; 25 unittest tests passed.